# arnurkabdylkak/sdio_rgmii_brd architecture

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

- Interactive diagram: https://gitdiagram.com/arnurkabdylkak/sdio_rgmii_brd
- Repository: https://github.com/arnurkabdylkak/sdio_rgmii_brd

## Overview

This repository is a bare-metal LiteX/VexRiscv port that brings up a CYW55500 Wi-Fi 6 module over SDIO on a Tang Primer 25K. The principal path is firmware boot and WHD initialization, firmware download, network scan and selection, WPA2 association/host-side handshake, then data-path handoff. The graph also preserves the custom SoC hardware, WHD’s SDIO and resource layers, and the documented packet-analysis utilities. Some runtime links are documented rather than visible in sampled implementation excerpts; those use the README as evidence.

Main entry points: [`firmware/main_whd.c`](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/main_whd.c) (WHD boot flow), [`wifi-host-driver/WHD/COMPONENT_WIFI6/src/whd_wifi_api.c`](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/wifi-host-driver/WHD/COMPONENT_WIFI6/src/whd_wifi_api.c) (WHD API), [`firmware/wpa2_eapol.c`](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/wpa2_eapol.c) (WPA2 handshake), [`firmware/cyhal_sdio_litex.c`](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/cyhal_sdio_litex.c) (LiteX SDIO HAL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["FPGA platform"]
  node_soc["LiteX SoC"]
  node_sdio_hw["SDIO controller<br/>[litex_sd_hw.h]"]
  node_wifi_hw["Wi-Fi controls<br/>[litex_sd_hw.h]"]
end

subgraph group_firmware["Firmware workflow"]
  node_boot["WHD boot flow<br/>[main_whd.c]"]
  node_sdio_hal["LiteX SDIO HAL<br/>[cyhal_sdio_litex.c]"]
  node_rtos["Bare-metal RTOS port<br/>[cy_rtos_litex.c]"]
  node_scan["Scan and join<br/>[main_whd.c]"]
  node_netif["Network interface port<br/>[whd_netif_litex.c]"]
end

subgraph group_driver["WHD driver"]
  node_whd_api["WHD API<br/>[whd_wifi_api.c]"]
  node_sdio_bus["WHD SDIO protocol"]
  node_resources["Firmware resources<br/>[whd_resources.c]"]
end

subgraph group_security["Security and data"]
  node_wpa["WPA2 handshake<br/>[wpa2_eapol.c]"]
  node_crypto["WPA2 cryptography<br/>[wpa2_crypto.c]"]
  node_data_path["Data-path handoff<br/>[main_whd.c]"]
end

subgraph group_utilities["Network utilities"]
  node_sniffer["Handshake capture<br/>[sniff_handshake.py]"]
  node_decrypt["CCMP decoder<br/>[decrypt_ccmp.py]"]
  node_inject["ARP injection<br/>[wifi_inject_arp.py]"]
  node_eth_tools["Ethernet utilities<br/>[eth_ping.py]"]
end

node_operator(("Operator"))
node_cyw["CYW55500 module"]
node_ap(("Wi-Fi access point"))

node_operator -->|"starts firmware"| node_boot
node_boot -->|"initializes SDIO"| node_sdio_hal
node_sdio_hal -->|"accesses registers"| node_sdio_hw
node_boot -->|"initializes WHD"| node_whd_api
node_boot -.->|"uses timing services"| node_rtos
node_whd_api -.->|"dispatches bus operations"| node_sdio_bus
node_sdio_bus -.->|"uses SDIO HAL"| node_sdio_hal
node_whd_api -.->|"loads resources"| node_resources
node_resources -->|"supplies firmware"| node_cyw
node_sdio_hw -->|"transfers SDIO data"| node_cyw
node_wifi_hw -->|"controls power"| node_cyw
node_boot -->|"scans and selects"| node_scan
node_scan -->|"calls scan APIs"| node_whd_api
node_scan -->|"discovers network"| node_ap
node_boot -->|"runs handshake"| node_wpa
node_wpa -->|"uses primitives"| node_crypto
node_wpa -->|"uses WHD interface"| node_whd_api
node_boot -.->|"configures network port"| node_netif
node_boot -->|"hands off data path"| node_data_path
node_ap -.->|"emits captured traffic"| node_sniffer
node_sniffer -.->|"provides handshake data"| node_decrypt
node_operator -.->|"requests packet injection"| node_inject
node_operator -.->|"runs diagnostics"| node_eth_tools

click node_soc "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/sipeed_tang_primer_25k.py"
click node_sdio_hw "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/litex_sd_hw.h"
click node_wifi_hw "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/litex_sd_hw.h"
click node_boot "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/main_whd.c"
click node_sdio_hal "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/cyhal_sdio_litex.c"
click node_rtos "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/cy_rtos_litex.c"
click node_whd_api "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/wifi-host-driver/WHD/COMPONENT_WIFI6/src/whd_wifi_api.c"
click node_sdio_bus "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/wifi-host-driver/WHD/COMPONENT_WIFI6/src/bus_protocols/whd_bus_sdio_protocol.c"
click node_resources "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/wifi-host-driver/WHD/COMPONENT_WIFI6/resources/resource_imp/whd_resources.c"
click node_scan "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/main_whd.c"
click node_wpa "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/wpa2_eapol.c"
click node_crypto "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/wpa2_crypto.c"
click node_netif "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/whd_netif_litex.c"
click node_data_path "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/main_whd.c"
click node_sniffer "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/tools/sniff_handshake.py"
click node_decrypt "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/tools/decrypt_ccmp.py"
click node_inject "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/tools/wifi_inject_arp.py"
click node_eth_tools "https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/tools/eth_ping.py"

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_soc,node_sdio_hw,node_wifi_hw toneBlue
class node_boot,node_sdio_hal,node_rtos,node_scan,node_netif toneAmber
class node_whd_api,node_sdio_bus,node_resources toneMint
class node_wpa,node_crypto,node_data_path toneRose
class node_sniffer,node_decrypt,node_inject,node_eth_tools,node_operator,node_cyw,node_ap toneIndigo
```

## Components

### FPGA platform

- [LiteX SoC](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/sipeed_tang_primer_25k.py): `sipeed_tang_primer_25k.py`
- [SDIO controller](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/litex_sd_hw.h): `firmware/litex_sd_hw.h`
- [Wi-Fi controls](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/litex_sd_hw.h): `firmware/litex_sd_hw.h`

### Firmware workflow

- [WHD boot flow](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/main_whd.c): `firmware/main_whd.c`
- [LiteX SDIO HAL](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/cyhal_sdio_litex.c): `firmware/cyhal_sdio_litex.c`
- [Bare-metal RTOS port](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/cy_rtos_litex.c): `firmware/cy_rtos_litex.c`
- [Scan and join](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/main_whd.c): `firmware/main_whd.c`
- [Network interface port](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/whd_netif_litex.c): `firmware/whd_netif_litex.c`

### WHD driver

- [WHD API](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/wifi-host-driver/WHD/COMPONENT_WIFI6/src/whd_wifi_api.c): `wifi-host-driver/WHD/COMPONENT_WIFI6/src/whd_wifi_api.c`
- [WHD SDIO protocol](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/wifi-host-driver/WHD/COMPONENT_WIFI6/src/bus_protocols/whd_bus_sdio_protocol.c): `wifi-host-driver/WHD/COMPONENT_WIFI6/src/bus_protocols/whd_bus_sdio_protocol.c`
- [Firmware resources](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/wifi-host-driver/WHD/COMPONENT_WIFI6/resources/resource_imp/whd_resources.c): `wifi-host-driver/WHD/COMPONENT_WIFI6/resources/resource_imp/whd_resources.c`

### Security and data

- [WPA2 handshake](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/wpa2_eapol.c): `firmware/wpa2_eapol.c`
- [WPA2 cryptography](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/wpa2_crypto.c): `firmware/wpa2_crypto.c`
- [Data-path handoff](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/firmware/main_whd.c): `firmware/main_whd.c`

### Network utilities

- [Handshake capture](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/tools/sniff_handshake.py): `tools/sniff_handshake.py`
- [CCMP decoder](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/tools/decrypt_ccmp.py): `tools/decrypt_ccmp.py`
- [ARP injection](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/tools/wifi_inject_arp.py): `tools/wifi_inject_arp.py`
- [Ethernet utilities](https://github.com/arnurkabdylkak/sdio_rgmii_brd/blob/main/tools/eth_ping.py): `tools/eth_ping.py`

### Other components

- **Operator**
- **CYW55500 module**
- **Wi-Fi access point**

## Connections

- Operator → WHD boot flow: starts firmware
- WHD boot flow → LiteX SDIO HAL: initializes SDIO (evidence: `firmware/main_whd.c`)
- LiteX SDIO HAL → SDIO controller: accesses registers (evidence: `firmware/cyhal_sdio_litex.c`)
- WHD boot flow → WHD API: initializes WHD (evidence: `firmware/main_whd.c`)
- WHD boot flow → Bare-metal RTOS port: uses timing services
- WHD API → WHD SDIO protocol: dispatches bus operations
- WHD SDIO protocol → LiteX SDIO HAL: uses SDIO HAL
- WHD API → Firmware resources: loads resources
- Firmware resources → CYW55500 module: supplies firmware
- SDIO controller → CYW55500 module: transfers SDIO data
- Wi-Fi controls → CYW55500 module: controls power
- WHD boot flow → Scan and join: scans and selects (evidence: `firmware/main_whd.c`)
- Scan and join → WHD API: calls scan APIs (evidence: `firmware/main_whd.c`)
- Scan and join → Wi-Fi access point: discovers network
- WHD boot flow → WPA2 handshake: runs handshake
- WPA2 handshake → WPA2 cryptography: uses primitives (evidence: `firmware/wpa2_eapol.c`)
- WPA2 handshake → WHD API: uses WHD interface (evidence: `firmware/wpa2_eapol.c`)
- WHD boot flow → Network interface port: configures network port
- WHD boot flow → Data-path handoff: hands off data path (evidence: `firmware/main_whd.c`)
- Wi-Fi access point → Handshake capture: emits captured traffic
- Handshake capture → CCMP decoder: provides handshake data
- Operator → ARP injection: requests packet injection
- Operator → Ethernet utilities: runs diagnostics
