# oszimilian/yellowpirat architecture

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

- Interactive diagram: https://gitdiagram.com/oszimilian/yellowpirat
- Repository: https://github.com/oszimilian/yellowpirat

## Overview

This repository implements an FPGA-based Briey embedded system with firmware for CAN recording and Ethernet networking. The principal runtime path starts in `software/app/main.c`: it initializes DMA, Ethernet and CAN-flow state, creates FreeRTOS tasks, then starts the scheduler. Network tasks serve TCP or optional UDP traffic; CAN recording and Ethernet receive run as separate tasks. The bootloader loads an application image from LittleFS-backed SD storage into SDRAM and jumps to it. Hardware modules and broader protocol capabilities are identified from the tree; their internal wiring was not established by the sampled excerpts.

Main entry points: [`software/app/main.c`](https://github.com/oszimilian/yellowpirat/blob/main/software/app/main.c) (Application entry), [`software/app/src/can_rec.c`](https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/can_rec.c) (CAN recorder task), [`software/app/src/yp_flow.c`](https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/yp_flow.c) (CAN flow state), [`software/bootloader/main.c`](https://github.com/oszimilian/yellowpirat/blob/main/software/bootloader/main.c) (Bootloader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Firmware runtime"]
  node_app["Application entry<br/>[main.c]"]
  node_scheduler["FreeRTOS scheduler<br/>[tasks.c]"]
  node_can_task["CAN recorder task<br/>[can_rec.c]"]
  node_eth_task["Ethernet RX task<br/>[eth_task.c]"]
  node_tcp_task["TCP server task<br/>[tcp.c]"]
  node_udp_task["UDP server task<br/>[udp.c]"]
  node_flow["CAN flow state<br/>[yp_flow.c]"]
  node_uart_task["UART task<br/>[uart_task.c]"]
  node_trace["Task statistics<br/>[task_trace.c]"]
  node_fault["Fault handling<br/>[fault.c]"]
end

subgraph group_io["Hardware I/O"]
  node_cpu["Briey SoC<br/>[briey.scala]"]
  node_can_hw["CTU CAN hardware<br/>[ctu_can.scala]"]
  node_eth_hw["Ethernet MAC<br/>[eth_mac.scala]"]
  node_dma_hw["DMA hardware<br/>[dma.scala]"]
  node_can_drv["CAN driver<br/>[ctucan.c]"]
  node_dma_drv["DMA driver<br/>[dma.c]"]
  node_eth_drv["Ethernet driver<br/>[eth.c]"]
end

subgraph group_network["Network stack"]
  node_lwip["lwIP networking<br/>[netif.c]"]
  node_tcp["TCP transport<br/>[tcp.c]"]
  node_udp["UDP transport<br/>[udp.c]"]
end

subgraph group_boot["Boot and storage"]
  node_bootloader["Bootloader<br/>[main.c]"]
  node_littlefs["LittleFS<br/>[lfs.c]"]
  node_sdcard["SD/MMC interface<br/>[sdmmc.h]"]
  node_sdram[("Application SDRAM")]
end

node_can_bus(("CAN network"))
node_ethernet_peer(("Ethernet peer"))
node_uart(("UART console"))
node_freertos(("FreeRTOS runtime"))

node_app -->|"initializes DMA"| node_dma_drv
node_app -->|"initializes and starts"| node_eth_drv
node_app -->|"initializes flow"| node_flow
node_app -->|"creates tasks; starts"| node_scheduler
node_app -->|"registers task"| node_can_task
node_app -->|"registers task"| node_eth_task
node_app -->|"registers task"| node_tcp_task
node_app -.->|"optional task"| node_udp_task
node_app -->|"registers task"| node_uart_task
node_app -->|"registers task"| node_trace
node_scheduler -->|"runs tasks"| node_freertos
node_can_task -->|"uses CAN state"| node_flow
node_can_task -->|"uses DMA"| node_dma_drv
node_can_task -->|"records frames"| node_can_bus
node_eth_task -->|"receives frames"| node_eth_drv
node_tcp_task -->|"serves CAN state"| node_flow
node_udp_task -.->|"serves CAN state"| node_flow
node_tcp_task -->|"uses TCP"| node_tcp
node_udp_task -.->|"uses UDP"| node_udp
node_eth_drv -->|"network interface"| node_lwip
node_lwip -->|"exchanges packets"| node_ethernet_peer
node_uart_task -->|"communicates"| node_uart
node_eth_hw -->|"hardware integration"| node_dma_hw
node_can_hw -->|"CAN frames"| node_can_bus
node_bootloader -->|"reads image"| node_littlefs
node_littlefs -->|"storage I/O"| node_sdcard
node_bootloader -->|"copies application"| node_sdram
node_bootloader -->|"jumps to loaded image"| node_app

click node_app "https://github.com/oszimilian/yellowpirat/blob/main/software/app/main.c"
click node_scheduler "https://github.com/oszimilian/yellowpirat/blob/main/software/freertos/tasks.c"
click node_can_task "https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/can_rec.c"
click node_eth_task "https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/eth_task.c"
click node_tcp_task "https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/tcp.c"
click node_udp_task "https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/udp.c"
click node_flow "https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/yp_flow.c"
click node_uart_task "https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/uart_task.c"
click node_trace "https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/task_trace.c"
click node_fault "https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/fault.c"
click node_cpu "https://github.com/oszimilian/yellowpirat/blob/main/cpu/src/main/scala/briey.scala"
click node_can_hw "https://github.com/oszimilian/yellowpirat/blob/main/can/src/main/scala/ctu_can/ctu_can.scala"
click node_eth_hw "https://github.com/oszimilian/yellowpirat/blob/main/ethernet/src/main/scala/ypethmac/eth_mac.scala"
click node_dma_hw "https://github.com/oszimilian/yellowpirat/blob/main/dma/src/main/scala/dma/dma.scala"
click node_can_drv "https://github.com/oszimilian/yellowpirat/blob/main/software/ctucan/src/ctucan.c"
click node_dma_drv "https://github.com/oszimilian/yellowpirat/blob/main/software/dma/src/dma.c"
click node_eth_drv "https://github.com/oszimilian/yellowpirat/blob/main/software/eth/src/eth.c"
click node_lwip "https://github.com/oszimilian/yellowpirat/blob/main/software/lwip/src/core/netif.c"
click node_tcp "https://github.com/oszimilian/yellowpirat/blob/main/software/lwip/src/core/tcp.c"
click node_udp "https://github.com/oszimilian/yellowpirat/blob/main/software/lwip/src/core/udp.c"
click node_bootloader "https://github.com/oszimilian/yellowpirat/blob/main/software/bootloader/main.c"
click node_littlefs "https://github.com/oszimilian/yellowpirat/blob/main/software/littlefs/src/lfs.c"
click node_sdcard "https://github.com/oszimilian/yellowpirat/blob/main/software/sdcard/inc/sdmmc.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_app,node_scheduler,node_can_task,node_eth_task,node_tcp_task,node_udp_task,node_flow,node_uart_task,node_trace,node_fault toneBlue
class node_cpu,node_can_hw,node_eth_hw,node_dma_hw,node_can_drv,node_dma_drv,node_eth_drv toneAmber
class node_lwip,node_tcp,node_udp toneMint
class node_bootloader,node_littlefs,node_sdcard,node_sdram toneRose
class node_can_bus,node_ethernet_peer,node_uart,node_freertos toneIndigo
```

## Components

### Firmware runtime

- [Application entry](https://github.com/oszimilian/yellowpirat/blob/main/software/app/main.c): `software/app/main.c`
- [FreeRTOS scheduler](https://github.com/oszimilian/yellowpirat/blob/main/software/freertos/tasks.c): `software/freertos/tasks.c`
- [CAN recorder task](https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/can_rec.c): `software/app/src/can_rec.c`
- [Ethernet RX task](https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/eth_task.c): `software/app/src/eth_task.c`
- [TCP server task](https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/tcp.c): `software/app/src/tcp.c`
- [UDP server task](https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/udp.c): `software/app/src/udp.c`
- [CAN flow state](https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/yp_flow.c): `software/app/src/yp_flow.c`
- [UART task](https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/uart_task.c): `software/app/src/uart_task.c`
- [Task statistics](https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/task_trace.c): `software/app/src/task_trace.c`
- [Fault handling](https://github.com/oszimilian/yellowpirat/blob/main/software/app/src/fault.c): `software/app/src/fault.c`

### Hardware I/O

- [Briey SoC](https://github.com/oszimilian/yellowpirat/blob/main/cpu/src/main/scala/briey.scala): `cpu/src/main/scala/briey.scala`
- [CTU CAN hardware](https://github.com/oszimilian/yellowpirat/blob/main/can/src/main/scala/ctu_can/ctu_can.scala): `can/src/main/scala/ctu_can/ctu_can.scala`
- [Ethernet MAC](https://github.com/oszimilian/yellowpirat/blob/main/ethernet/src/main/scala/ypethmac/eth_mac.scala): `ethernet/src/main/scala/ypethmac/eth_mac.scala`
- [DMA hardware](https://github.com/oszimilian/yellowpirat/blob/main/dma/src/main/scala/dma/dma.scala): `dma/src/main/scala/dma/dma.scala`
- [CAN driver](https://github.com/oszimilian/yellowpirat/blob/main/software/ctucan/src/ctucan.c): `software/ctucan/src/ctucan.c`
- [DMA driver](https://github.com/oszimilian/yellowpirat/blob/main/software/dma/src/dma.c): `software/dma/src/dma.c`
- [Ethernet driver](https://github.com/oszimilian/yellowpirat/blob/main/software/eth/src/eth.c): `software/eth/src/eth.c`

### Network stack

- [lwIP networking](https://github.com/oszimilian/yellowpirat/blob/main/software/lwip/src/core/netif.c): `software/lwip/src/core/netif.c`
- [TCP transport](https://github.com/oszimilian/yellowpirat/blob/main/software/lwip/src/core/tcp.c): `software/lwip/src/core/tcp.c`
- [UDP transport](https://github.com/oszimilian/yellowpirat/blob/main/software/lwip/src/core/udp.c): `software/lwip/src/core/udp.c`

### Boot and storage

- [Bootloader](https://github.com/oszimilian/yellowpirat/blob/main/software/bootloader/main.c): `software/bootloader/main.c`
- [LittleFS](https://github.com/oszimilian/yellowpirat/blob/main/software/littlefs/src/lfs.c): `software/littlefs/src/lfs.c`
- [SD/MMC interface](https://github.com/oszimilian/yellowpirat/blob/main/software/sdcard/inc/sdmmc.h): `software/sdcard/inc/sdmmc.h`
- **Application SDRAM**

### Other components

- **CAN network**
- **Ethernet peer**
- **UART console**
- **FreeRTOS runtime**

## Connections

- Application entry → DMA driver: initializes DMA
- Application entry → Ethernet driver: initializes and starts
- Application entry → CAN flow state: initializes flow
- Application entry → FreeRTOS scheduler: creates tasks; starts
- Application entry → CAN recorder task: registers task
- Application entry → Ethernet RX task: registers task
- Application entry → TCP server task: registers task
- Application entry → UDP server task: optional task
- Application entry → UART task: registers task
- Application entry → Task statistics: registers task
- FreeRTOS scheduler → FreeRTOS runtime: runs tasks
- CAN recorder task → CAN flow state: uses CAN state
- CAN recorder task → DMA driver: uses DMA
- CAN recorder task → CAN network: records frames
- Ethernet RX task → Ethernet driver: receives frames
- TCP server task → CAN flow state: serves CAN state
- UDP server task → CAN flow state: serves CAN state
- TCP server task → TCP transport: uses TCP
- UDP server task → UDP transport: uses UDP
- Ethernet driver → lwIP networking: network interface
- lwIP networking → Ethernet peer: exchanges packets
- UART task → UART console: communicates
- Ethernet MAC → DMA hardware: hardware integration
- CTU CAN hardware → CAN network: CAN frames
- Bootloader → LittleFS: reads image
- LittleFS → SD/MMC interface: storage I/O
- Bootloader → Application SDRAM: copies application
- Bootloader → Application entry: jumps to loaded image