# mkschreder/rockutil architecture

> Architecture diagram of the GitHub repository mkschreder/rockutil, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mkschreder/rockutil
- Repository: https://github.com/mkschreder/rockutil

## Overview

rockutil is a C command-line utility for discovering and managing Rockchip devices over USB, including MaskROM recovery, loader operations, firmware flashing, partition imaging, GPT creation, and offline image inspection. The principal recovery workflow is to parse/extract loader and firmware data, upload MaskROM stages, wait for the Loader transition, then write firmware partitions over Rockusb. The CLI also handles direct sector operations and parameter-driven partition tasks. Paths and relationships for major commands are based on the README; the sampled excerpts do not expose every command handler, so uncertain internal wiring is omitted.

Main entry points: [`rockutil.c`](https://github.com/mkschreder/rockutil/blob/main/rockutil.c) (Command dispatcher), [`rkusb.c`](https://github.com/mkschreder/rockutil/blob/main/rkusb.c) (Rockusb transport), [`rkparam.c`](https://github.com/mkschreder/rockutil/blob/main/rkparam.c) (Parameter parser), [`rkimage.c`](https://github.com/mkschreder/rockutil/blob/main/rkimage.c) (RKFW RKAF RKBOOT)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command workflows"]
  node_cli["Command dispatcher<br/>[rockutil.c]"]
  node_maskrom["MaskROM upload<br/>[rkusb.c]"]
  node_firmware["Firmware workflows<br/>[rockutil.c]"]
  node_sector["Sector operations<br/>[rockutil.c]"]
end

subgraph group_usb["USB device access"]
  node_discovery["Device discovery<br/>[rkusb.c]"]
  node_rockusb["Rockusb transport<br/>[rkusb.c]"]
end

subgraph group_images["Firmware and images"]
  node_imageparse["RKFW RKAF RKBOOT<br/>[rkimage.c]"]
  node_sparse["Sparse expansion<br/>[rksparse.c]"]
end

subgraph group_partitions["Partition handling"]
  node_parameter["Parameter parser<br/>[rkparam.c]"]
  node_gpt["GPT builder<br/>[rkparam.c]"]
end

subgraph group_core["Protocol utilities"]
  node_crc["CRC routines<br/>[rkcrc.c]"]
end

node_operator(("Operator"))
node_libusb["libusb"]
node_device["Rockchip device"]
node_imagefiles["Firmware files"]
node_paramfile["parameter.txt"]
node_flash[("Device flash")]

node_operator -->|"runs commands"| node_cli
node_cli -->|"lists devices"| node_discovery
node_discovery -->|"enumerates"| node_libusb
node_libusb -->|"enumerates USB"| node_device
node_cli -->|"issues commands"| node_rockusb
node_rockusb -->|"transfers data"| node_libusb
node_rockusb -->|"sends Rockusb"| node_device
node_cli -->|"uploads boot stages"| node_maskrom
node_maskrom -->|"sends control transfers"| node_rockusb
node_cli -->|"runs upgrades"| node_firmware
node_firmware -->|"loads containers"| node_imageparse
node_imageparse -->|"reads image data"| node_imagefiles
node_firmware -->|"starts handoff"| node_maskrom
node_firmware -->|"writes loader and partitions"| node_rockusb
node_cli -->|"inspects images"| node_imageparse
node_cli -->|"loads partition table"| node_parameter
node_parameter -->|"reads syntax"| node_paramfile
node_cli -->|"builds GPT"| node_gpt
node_gpt -->|"uses partitions"| node_parameter
node_gpt -->|"checksums entries"| node_crc
node_cli -->|"expands partition image"| node_sparse
node_sparse -->|"writes chunks"| node_rockusb
node_cli -->|"runs LBA operations"| node_sector
node_sector -->|"reads writes erases"| node_rockusb
node_rockusb -->|"accesses sectors"| node_flash
node_firmware -->|"uses partition metadata"| node_parameter

click node_cli "https://github.com/mkschreder/rockutil/blob/main/rockutil.c"
click node_discovery "https://github.com/mkschreder/rockutil/blob/main/rkusb.c"
click node_rockusb "https://github.com/mkschreder/rockutil/blob/main/rkusb.c"
click node_maskrom "https://github.com/mkschreder/rockutil/blob/main/rkusb.c"
click node_firmware "https://github.com/mkschreder/rockutil/blob/main/rockutil.c"
click node_imageparse "https://github.com/mkschreder/rockutil/blob/main/rkimage.c"
click node_parameter "https://github.com/mkschreder/rockutil/blob/main/rkparam.c"
click node_gpt "https://github.com/mkschreder/rockutil/blob/main/rkparam.c"
click node_sparse "https://github.com/mkschreder/rockutil/blob/main/rksparse.c"
click node_sector "https://github.com/mkschreder/rockutil/blob/main/rockutil.c"
click node_crc "https://github.com/mkschreder/rockutil/blob/main/rkcrc.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_maskrom,node_firmware,node_sector toneBlue
class node_discovery,node_rockusb,node_flash toneAmber
class node_imageparse,node_sparse toneMint
class node_parameter,node_gpt toneRose
class node_crc,node_operator,node_libusb,node_device,node_imagefiles,node_paramfile toneIndigo
```

## Components

### Command workflows

- [Command dispatcher](https://github.com/mkschreder/rockutil/blob/main/rockutil.c): `rockutil.c`
- [MaskROM upload](https://github.com/mkschreder/rockutil/blob/main/rkusb.c): `rkusb.c`
- [Firmware workflows](https://github.com/mkschreder/rockutil/blob/main/rockutil.c): `rockutil.c`
- [Sector operations](https://github.com/mkschreder/rockutil/blob/main/rockutil.c): `rockutil.c`

### USB device access

- [Device discovery](https://github.com/mkschreder/rockutil/blob/main/rkusb.c): `rkusb.c`
- [Rockusb transport](https://github.com/mkschreder/rockutil/blob/main/rkusb.c): `rkusb.c`

### Firmware and images

- [RKFW RKAF RKBOOT](https://github.com/mkschreder/rockutil/blob/main/rkimage.c): `rkimage.c`
- [Sparse expansion](https://github.com/mkschreder/rockutil/blob/main/rksparse.c): `rksparse.c`

### Partition handling

- [Parameter parser](https://github.com/mkschreder/rockutil/blob/main/rkparam.c): `rkparam.c`
- [GPT builder](https://github.com/mkschreder/rockutil/blob/main/rkparam.c): `rkparam.c`

### Protocol utilities

- [CRC routines](https://github.com/mkschreder/rockutil/blob/main/rkcrc.c): `rkcrc.c`

### Other components

- **Operator**
- **libusb**
- **Rockchip device**
- **Firmware files**
- **parameter.txt**
- **Device flash**

## Connections

- Operator → Command dispatcher: runs commands
- Command dispatcher → Device discovery: lists devices
- Device discovery → libusb: enumerates
- libusb → Rockchip device: enumerates USB
- Command dispatcher → Rockusb transport: issues commands
- Rockusb transport → libusb: transfers data
- Rockusb transport → Rockchip device: sends Rockusb
- Command dispatcher → MaskROM upload: uploads boot stages
- MaskROM upload → Rockusb transport: sends control transfers
- Command dispatcher → Firmware workflows: runs upgrades
- Firmware workflows → RKFW RKAF RKBOOT: loads containers
- RKFW RKAF RKBOOT → Firmware files: reads image data
- Firmware workflows → MaskROM upload: starts handoff
- Firmware workflows → Rockusb transport: writes loader and partitions
- Command dispatcher → RKFW RKAF RKBOOT: inspects images
- Command dispatcher → Parameter parser: loads partition table
- Parameter parser → parameter.txt: reads syntax
- Command dispatcher → GPT builder: builds GPT
- GPT builder → Parameter parser: uses partitions
- GPT builder → CRC routines: checksums entries
- Command dispatcher → Sparse expansion: expands partition image
- Sparse expansion → Rockusb transport: writes chunks
- Command dispatcher → Sector operations: runs LBA operations
- Sector operations → Rockusb transport: reads writes erases
- Rockusb transport → Device flash: accesses sectors
- Firmware workflows → Parameter parser: uses partition metadata