# linux-goxceed/gxipl architecture

> Architecture diagram of the GitHub repository linux-goxceed/gxipl, 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/gxipl
- Repository: https://github.com/linux-goxceed/gxipl

## Overview

gxipl is a first-stage loader and DDR-resident bootcode for NationalChip GX6702/GX6706. BootROM starts the IPL, which initializes the chip and DDR, then obtains GXBC bootcode through SPI or UART. The bootcode selects USB FAT, SPI BOOT, or UART recovery (with configuration able to alter the order), and transfers control to a loaded executable. The graph also preserves the IPL’s USB/FAT loading path, SPI/table discovery, and shared configuration and hardware-initialization layers. Some subsystem links rely on README descriptions or source-index references; unsampled implementations are not inferred beyond those links.

Main entry points: [`bootcode/main.c`](https://github.com/linux-goxceed/gxipl/blob/main/bootcode/main.c) (Boot selection), [`bootcode/usb_boot.c`](https://github.com/linux-goxceed/gxipl/blob/main/bootcode/usb_boot.c) (USB boot), [`ipl/ipl.c`](https://github.com/linux-goxceed/gxipl/blob/main/ipl/ipl.c) (IPL startup), [`ipl/ipl_common.c`](https://github.com/linux-goxceed/gxipl/blob/main/ipl/ipl_common.c) (IPL common flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ipl["Stage-one IPL"]
  node_ipl_entry["IPL startup<br/>[ipl.c]"]
  node_soc_init["SoC and DDR init<br/>[gx6706_ipl.c]"]
  node_ipl_common["IPL common flow<br/>[ipl_common.c]"]
  node_ipl_usb["USB FAT loader<br/>[stage15_usb.c]"]
  node_ipl_usb_msc["IPL USB MSC<br/>[usb_msc_min.c]"]
  node_ipl_spi["IPL SPI reader<br/>[gx_spi.c]"]
end

subgraph group_bootcode["DDR bootcode"]
  node_bootcode_main["Boot selection<br/>[main.c]"]
  node_bc_usb["USB boot<br/>[usb_boot.c]"]
  node_bc_usb_msc["Bootcode USB MSC<br/>[usb_msc.c]"]
  node_bc_spi["SPI BOOT loader<br/>[spi_boot.c]"]
  node_table["Flash table discovery<br/>[gx_table.c]"]
  node_bc_uart["UART recovery<br/>[uart_boot.c]"]
  node_elf["ELF loader<br/>[elf.c]"]
  node_bootcode_record["GXBC bootcode<br/>[bootcode_hdr.h]"]
end

subgraph group_storage["Storage and filesystems"]
  node_ipl_fat["Petit FAT<br/>[pff.c]"]
  node_fatfs["FatFs<br/>[ff.c]"]
  node_usb_diskio["USB disk I/O<br/>[diskio_usb.c]"]
end

subgraph group_platform["Platform services"]
  node_config["IPL configuration<br/>[ipl_config.c]"]
  node_hw["Hardware definitions<br/>[gx_hw.h]"]
end

node_bootrom(("BootROM"))
node_loaded_program["Loaded executable"]

node_bootrom -->|"loads stage one"| node_ipl_entry
node_ipl_entry -.->|"initializes platform"| node_soc_init
node_ipl_entry -.->|"runs boot flow"| node_ipl_common
node_ipl_common -.->|"reads SPI"| node_ipl_spi
node_ipl_common -->|"loads over USB"| node_ipl_usb
node_ipl_usb -->|"reads USB storage"| node_ipl_usb_msc
node_ipl_usb -->|"reads FAT files"| node_ipl_fat
node_ipl_common -->|"loads GXBC"| node_bootcode_record
node_bootcode_record -->|"hands off"| node_bootcode_main
node_bootcode_main -->|"loads settings"| node_config
node_bootcode_main -->|"tries USB first"| node_bc_usb
node_bootcode_main -->|"tries SPI next"| node_bc_spi
node_bootcode_main -->|"falls back UART"| node_bc_uart
node_bc_usb -->|"uses USB MSC"| node_bc_usb_msc
node_bc_usb -->|"reads sectors"| node_usb_diskio
node_usb_diskio -.->|"serves disk reads"| node_fatfs
node_bc_usb -->|"reads FAT32"| node_fatfs
node_bc_spi -.->|"discovers BOOT"| node_table
node_bc_spi -.->|"loads executable"| node_elf
node_bc_usb -->|"loads ELF"| node_elf
node_bc_uart -->|"receives program"| node_loaded_program
node_elf -->|"loads into DDR"| node_loaded_program
node_ipl_entry -.->|"uses hardware map"| node_hw
node_bootcode_main -.->|"uses hardware map"| node_hw

click node_ipl_entry "https://github.com/linux-goxceed/gxipl/blob/main/ipl/ipl.c"
click node_soc_init "https://github.com/linux-goxceed/gxipl/blob/main/ipl/gx6706_ipl.c"
click node_ipl_common "https://github.com/linux-goxceed/gxipl/blob/main/ipl/ipl_common.c"
click node_ipl_usb "https://github.com/linux-goxceed/gxipl/blob/main/ipl/fat/stage15_usb.c"
click node_ipl_usb_msc "https://github.com/linux-goxceed/gxipl/blob/main/ipl/usb/usb_msc_min.c"
click node_ipl_fat "https://github.com/linux-goxceed/gxipl/blob/main/ipl/fat/pff.c"
click node_ipl_spi "https://github.com/linux-goxceed/gxipl/blob/main/ipl/gx_spi.c"
click node_bootcode_main "https://github.com/linux-goxceed/gxipl/blob/main/bootcode/main.c"
click node_bc_usb "https://github.com/linux-goxceed/gxipl/blob/main/bootcode/usb_boot.c"
click node_bc_usb_msc "https://github.com/linux-goxceed/gxipl/blob/main/bootcode/usb/usb_msc.c"
click node_fatfs "https://github.com/linux-goxceed/gxipl/blob/main/fatfs/ff.c"
click node_usb_diskio "https://github.com/linux-goxceed/gxipl/blob/main/bootcode/fat/diskio_usb.c"
click node_bc_spi "https://github.com/linux-goxceed/gxipl/blob/main/bootcode/spi_boot.c"
click node_table "https://github.com/linux-goxceed/gxipl/blob/main/bootcode/gx_table.c"
click node_bc_uart "https://github.com/linux-goxceed/gxipl/blob/main/bootcode/uart_boot.c"
click node_elf "https://github.com/linux-goxceed/gxipl/blob/main/bootcode/elf.c"
click node_config "https://github.com/linux-goxceed/gxipl/blob/main/ipl/ipl_config.c"
click node_hw "https://github.com/linux-goxceed/gxipl/blob/main/include/gx_hw.h"
click node_bootcode_record "https://github.com/linux-goxceed/gxipl/blob/main/include/bootcode_hdr.h"

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_ipl_entry,node_soc_init,node_ipl_common,node_ipl_usb,node_ipl_usb_msc,node_ipl_spi toneBlue
class node_bootcode_main,node_bc_usb,node_bc_usb_msc,node_bc_spi,node_table,node_bc_uart,node_elf,node_bootcode_record toneAmber
class node_ipl_fat,node_fatfs,node_usb_diskio toneMint
class node_config,node_hw toneRose
class node_bootrom,node_loaded_program toneIndigo
```

## Components

### Stage-one IPL

- [IPL startup](https://github.com/linux-goxceed/gxipl/blob/main/ipl/ipl.c): `ipl/ipl.c`
- [SoC and DDR init](https://github.com/linux-goxceed/gxipl/blob/main/ipl/gx6706_ipl.c): `ipl/gx6706_ipl.c`
- [IPL common flow](https://github.com/linux-goxceed/gxipl/blob/main/ipl/ipl_common.c): `ipl/ipl_common.c`
- [USB FAT loader](https://github.com/linux-goxceed/gxipl/blob/main/ipl/fat/stage15_usb.c): `ipl/fat/stage15_usb.c`
- [IPL USB MSC](https://github.com/linux-goxceed/gxipl/blob/main/ipl/usb/usb_msc_min.c): `ipl/usb/usb_msc_min.c`
- [IPL SPI reader](https://github.com/linux-goxceed/gxipl/blob/main/ipl/gx_spi.c): `ipl/gx_spi.c`

### DDR bootcode

- [Boot selection](https://github.com/linux-goxceed/gxipl/blob/main/bootcode/main.c): `bootcode/main.c`
- [USB boot](https://github.com/linux-goxceed/gxipl/blob/main/bootcode/usb_boot.c): `bootcode/usb_boot.c`
- [Bootcode USB MSC](https://github.com/linux-goxceed/gxipl/blob/main/bootcode/usb/usb_msc.c): `bootcode/usb/usb_msc.c`
- [SPI BOOT loader](https://github.com/linux-goxceed/gxipl/blob/main/bootcode/spi_boot.c): `bootcode/spi_boot.c`
- [Flash table discovery](https://github.com/linux-goxceed/gxipl/blob/main/bootcode/gx_table.c): `bootcode/gx_table.c`
- [UART recovery](https://github.com/linux-goxceed/gxipl/blob/main/bootcode/uart_boot.c): `bootcode/uart_boot.c`
- [ELF loader](https://github.com/linux-goxceed/gxipl/blob/main/bootcode/elf.c): `bootcode/elf.c`
- [GXBC bootcode](https://github.com/linux-goxceed/gxipl/blob/main/include/bootcode_hdr.h): `include/bootcode_hdr.h`

### Storage and filesystems

- [Petit FAT](https://github.com/linux-goxceed/gxipl/blob/main/ipl/fat/pff.c): `ipl/fat/pff.c`
- [FatFs](https://github.com/linux-goxceed/gxipl/blob/main/fatfs/ff.c): `fatfs/ff.c`
- [USB disk I/O](https://github.com/linux-goxceed/gxipl/blob/main/bootcode/fat/diskio_usb.c): `bootcode/fat/diskio_usb.c`

### Platform services

- [IPL configuration](https://github.com/linux-goxceed/gxipl/blob/main/ipl/ipl_config.c): `ipl/ipl_config.c`
- [Hardware definitions](https://github.com/linux-goxceed/gxipl/blob/main/include/gx_hw.h): `include/gx_hw.h`

### Other components

- **BootROM**
- **Loaded executable**

## Connections

- BootROM → IPL startup: loads stage one
- IPL startup → SoC and DDR init: initializes platform
- IPL startup → IPL common flow: runs boot flow
- IPL common flow → IPL SPI reader: reads SPI
- IPL common flow → USB FAT loader: loads over USB
- USB FAT loader → IPL USB MSC: reads USB storage (evidence: `ipl/fat/stage15_usb.c`)
- USB FAT loader → Petit FAT: reads FAT files (evidence: `ipl/fat/stage15_usb.c`)
- IPL common flow → GXBC bootcode: loads GXBC (evidence: `ipl/ipl_common.c`)
- GXBC bootcode → Boot selection: hands off
- Boot selection → IPL configuration: loads settings (evidence: `bootcode/main.c`)
- Boot selection → USB boot: tries USB first (evidence: `bootcode/main.c`)
- Boot selection → SPI BOOT loader: tries SPI next (evidence: `bootcode/main.c`)
- Boot selection → UART recovery: falls back UART (evidence: `bootcode/main.c`)
- USB boot → Bootcode USB MSC: uses USB MSC (evidence: `bootcode/usb_boot.c`)
- USB boot → USB disk I/O: reads sectors (evidence: `bootcode/fat/diskio_usb.c`)
- USB disk I/O → FatFs: serves disk reads
- USB boot → FatFs: reads FAT32
- SPI BOOT loader → Flash table discovery: discovers BOOT
- SPI BOOT loader → ELF loader: loads executable
- USB boot → ELF loader: loads ELF
- UART recovery → Loaded executable: receives program
- ELF loader → Loaded executable: loads into DDR
- IPL startup → Hardware definitions: uses hardware map (evidence: `ipl/ipl.c`)
- Boot selection → Hardware definitions: uses hardware map (evidence: `bootcode/main.c`)