# linux-goxceed/gxdl-rs architecture

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

- Interactive diagram: https://gitdiagram.com/linux-goxceed/gxdl-rs
- Repository: https://github.com/linux-goxceed/gxdl-rs

## Overview

gxdl-rs is a Rust library and CLI for uploading loaders to NationalChip GX BootROM devices and issuing bootloader commands. The main flow parses CLI options, selects a loader (or attaches to an existing prompt), opens a serial connection, performs BootROM synchronization and staged upload, then dispatches optional commands. Commands cover serial/USB transfers, flash and OTP operations, network transfers, and host-side file comparison. The graph follows shown calls and README-described behavior; unsampled command handlers are grouped by capability rather than inferred individually.

Main entry points: [`src/protocol.rs`](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/protocol.rs) (Boot protocol session), [`src/commands.rs`](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/commands.rs) (Command parsing), [`src/main.rs`](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/main.rs) (Application entry), [`src/uploader.rs`](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/uploader.rs) (Uploader API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and API"]
  node_cli["CLI options<br/>[cli.rs]"]
  node_app["Application entry<br/>[main.rs]"]
  node_uploader["Uploader API<br/>[uploader.rs]"]
end

subgraph group_boot["Loader and Boot"]
  node_loader["Loader selection<br/>[loader.rs]"]
  node_bundled["Bundled loaders"]
end

subgraph group_transport["Protocol Transport"]
  node_session["Boot protocol session<br/>[protocol.rs]"]
  node_serial["Serial transport<br/>[serial.rs]"]
end

subgraph group_commands["Command Operations"]
  node_command["Command parsing<br/>[commands.rs]"]
  node_transfer["Serial / USB I/O<br/>[commands.rs]"]
  node_flashotp["Flash and OTP<br/>[commands.rs]"]
  node_hostutil["Host file utilities<br/>[commands.rs]"]
end

subgraph group_network["Network Transfer"]
  node_netcommands["Network commands<br/>[commands.rs]"]
  node_tftp["TFTP server<br/>[tftp.rs]"]
end

node_user(("Operator / API caller"))
node_device(("GX BootROM / bootloader"))
node_tftpserver(("PC TFTP server"))

node_user -->|"provides options"| node_cli
node_app -->|"parses and validates"| node_cli
node_app -->|"parses command"| node_command
node_app -->|"resolves image"| node_loader
node_app -->|"configures and invokes"| node_uploader
node_loader -->|"loads embedded images"| node_bundled
node_uploader -->|"opens device"| node_serial
node_uploader -->|"creates and boots session"| node_session
node_session -->|"uses image and bootcode data"| node_loader
node_session -->|"reads and writes"| node_serial
node_session -->|"synchronizes and uploads stages"| node_device
node_uploader -->|"dispatches commands"| node_command
node_command -->|"parses transfer operations"| node_transfer
node_command -->|"parses device operations"| node_flashotp
node_command -->|"parses host utilities"| node_hostutil
node_command -->|"parses network operations"| node_netcommands
node_transfer -->|"issues device commands"| node_session
node_flashotp -->|"issues device commands"| node_session
node_hostutil -->|"reads or compares files"| node_user
node_netcommands -->|"configures device transfer"| node_session
node_netcommands -->|"starts send or receive"| node_tftp
node_tftp -->|"transfers files with"| node_tftpserver
node_device -->|"exchanges TFTP packets"| node_tftp

click node_cli "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/cli.rs"
click node_app "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/main.rs"
click node_uploader "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/uploader.rs"
click node_loader "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/loader.rs"
click node_bundled "https://github.com/linux-goxceed/gxdl-rs/tree/master/src/loaders"
click node_session "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/protocol.rs"
click node_serial "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/serial.rs"
click node_command "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/commands.rs"
click node_transfer "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/commands.rs"
click node_flashotp "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/commands.rs"
click node_hostutil "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/commands.rs"
click node_netcommands "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/commands.rs"
click node_tftp "https://github.com/linux-goxceed/gxdl-rs/blob/master/src/tftp.rs"

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_app,node_uploader toneBlue
class node_loader,node_bundled toneAmber
class node_session,node_serial,node_user,node_tftpserver toneMint
class node_command,node_transfer,node_flashotp,node_hostutil toneRose
class node_netcommands,node_tftp,node_device toneIndigo
```

## Components

### CLI and API

- [CLI options](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/cli.rs): `src/cli.rs`
- [Application entry](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/main.rs): `src/main.rs`
- [Uploader API](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/uploader.rs): `src/uploader.rs`

### Loader and Boot

- [Loader selection](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/loader.rs): `src/loader.rs`
- [Bundled loaders](https://github.com/linux-goxceed/gxdl-rs/tree/master/src/loaders): `src/loaders`

### Protocol Transport

- [Boot protocol session](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/protocol.rs): `src/protocol.rs`
- [Serial transport](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/serial.rs): `src/serial.rs`

### Command Operations

- [Command parsing](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/commands.rs): `src/commands.rs`
- [Serial / USB I/O](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/commands.rs): `src/commands.rs`
- [Flash and OTP](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/commands.rs): `src/commands.rs`
- [Host file utilities](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/commands.rs): `src/commands.rs`

### Network Transfer

- [Network commands](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/commands.rs): `src/commands.rs`
- [TFTP server](https://github.com/linux-goxceed/gxdl-rs/blob/master/src/tftp.rs): `src/tftp.rs`

### Other components

- **Operator / API caller**
- **GX BootROM / bootloader**
- **PC TFTP server**

## Connections

- Operator / API caller → CLI options: provides options (evidence: `README.md`)
- Application entry → CLI options: parses and validates (evidence: `src/main.rs`)
- Application entry → Command parsing: parses command (evidence: `src/main.rs`)
- Application entry → Loader selection: resolves image (evidence: `src/main.rs`)
- Application entry → Uploader API: configures and invokes (evidence: `src/main.rs`)
- Loader selection → Bundled loaders: loads embedded images (evidence: `README.md`)
- Uploader API → Serial transport: opens device (evidence: `src/uploader.rs`)
- Uploader API → Boot protocol session: creates and boots session (evidence: `src/uploader.rs`)
- Boot protocol session → Loader selection: uses image and bootcode data (evidence: `src/protocol.rs`)
- Boot protocol session → Serial transport: reads and writes (evidence: `src/protocol.rs`)
- Boot protocol session → GX BootROM / bootloader: synchronizes and uploads stages (evidence: `README.md`)
- Uploader API → Command parsing: dispatches commands (evidence: `src/uploader.rs`)
- Command parsing → Serial / USB I/O: parses transfer operations (evidence: `src/commands.rs`)
- Command parsing → Flash and OTP: parses device operations (evidence: `README.md`)
- Command parsing → Host file utilities: parses host utilities (evidence: `src/commands.rs`)
- Command parsing → Network commands: parses network operations (evidence: `README.md`)
- Serial / USB I/O → Boot protocol session: issues device commands (evidence: `src/commands.rs`)
- Flash and OTP → Boot protocol session: issues device commands (evidence: `src/commands.rs`)
- Host file utilities → Operator / API caller: reads or compares files (evidence: `README.md`)
- Network commands → Boot protocol session: configures device transfer (evidence: `src/commands.rs`)
- Network commands → TFTP server: starts send or receive (evidence: `src/commands.rs`)
- TFTP server → PC TFTP server: transfers files with (evidence: `README.md`)
- GX BootROM / bootloader → TFTP server: exchanges TFTP packets (evidence: `README.md`)