Skip to content

CLAUDE.md

Latest commit

 

History

History
96 lines (76 loc) · 5.34 KB

CLAUDE.md

File metadata and controls

96 lines (76 loc) · 5.34 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

AES67 professional audio-over-IP implementation on a single Cyclone 10LP FPGA. The FPGA hosts both the data plane (Ethernet MAC, PTPv2, RTP audio, media clock) and a LiteX-generated VexRiscv RISC-V softcore running Zephyr RTOS for the control plane. The softcore boots from external SPI flash, uses HyperRAM for main memory, and communicates with the data plane via LiteX CSR registers over the Wishbone bus.

Build Commands

LiteX SoC Generation

cd litex_soc
make    # Generates SoC HDL, device tree, CSR headers

Firmware (Zephyr)

cd soc_firmware/app
source ../.venv/bin/activate
west build -b litex_vexriscv -p    # clean build
west build                          # incremental build

Zephyr v4.2.0, west manifest at soc_firmware/app/west-manifest/west.yml. Build produces a .fbi flash image (binary + length/CRC-32 header).

FPGA

Intel Quartus Prime 25.1, project file FPGA/FPGA.qpf, device 10CL025YU256I7G.

Architecture

Single-FPGA Design

  • Data Plane (FPGA/): ~28 VHDL/Verilog modules. Ethernet MAC (forked from YOL), PTPv2 leader+follower, wallclock discipline, media clock derivation, I2S audio input, RTP packet aggregation.
  • Control Plane (soc_firmware/app/): Zephyr C application running on LiteX VexRiscv SoC. DHCP, PTP BMC algorithm, Si5351A clock generator driver (I2C), SSD1306 OLED display, network management.
  • SoC Generation (litex_soc/): LiteX SoC definition (generate.py), boot stub (RISC-V assembly), generated CSR headers.

SoC-FPGA Interface (LiteX CSR)

The VexRiscv SoC accesses FPGA registers via LiteX CSR registers on the Wishbone bus. Application code uses the FPGA HAL (drivers/fpga_hal/) which abstracts this interface. CSR definitions are auto-generated by LiteX into litex_soc/build/software/include/generated/.

Key memory regions:

  • 0x20000000: HyperRAM (16 MB main memory)
  • 0x30000000: SPI flash (BIOS + firmware)
  • 0xf0000000: CSR peripheral registers

Boot Flow

  1. Boot stub at flash reset vector copies LiteX BIOS to HyperRAM
  2. BIOS loads Zephyr .fbi image from flash
  3. Zephyr boots and starts application threads

FPGA HAL

Application code accesses FPGA registers through drivers/fpga_hal/fpga_hal.h:

  • LiteX backend (fpga_hal_litex.c): Default. Uses LiteX CSR registers. No FPGA-ready gating needed (integrated SoC).
  • FMC backend (fpga_hal_fmc.c): Legacy STM32H7 support. Retained for backward compatibility.

Backend selected via Kconfig: CONFIG_FPGA_HAL_LITEX (default) or CONFIG_FPGA_HAL_FMC.

Critical Hardware Constraints

  1. HyperRAM latency: Boot stub sets 6 CK latency for power-on default before executing from HyperRAM.
  2. Clock domain crossing: FPGA PTP controller uses CDC synchronizers with PRESERVE attributes — do not remove.
  3. SPI flash boot: Boot stub must fit in first sector. BIOS is copied to 0x207F0000 (top of HyperRAM).

Key Source Files

LiteX SoC

  • litex_soc/generate.py — SoC generation script (VexRiscv, HyperRAM, peripherals)
  • litex_soc/boot_stub/boot_stub.S — RISC-V boot stub (flash → HyperRAM copy)
  • litex_soc/build/software/include/generated/ — Auto-generated CSR/memory headers

Firmware

  • soc_firmware/app/src/main.c — Entry point, DHCP, network setup
  • soc_firmware/app/src/ptp_bmc.c — IEEE 1588 Best Master Clock algorithm (multicast 224.0.1.129:320)
  • soc_firmware/app/src/fpga_regs.c — FPGA register helpers (via HAL)
  • soc_firmware/app/src/fpga_poll.c — Status polling thread
  • soc_firmware/app/src/pll_ctrl.c — Si5351A PPB correction
  • soc_firmware/app/drivers/fpga_hal/ — Backend-agnostic FPGA access (LiteX or FMC)
  • soc_firmware/app/drivers/eth_litex/ — LiteX Ethernet driver (primary)
  • soc_firmware/app/drivers/eth_fmc_basic/ — FMC Ethernet driver (legacy, for STM32H7)
  • soc_firmware/app/drivers/si5351a/ — Si5351A I2C clock generator with PPB correction
  • soc_firmware/app/prj.conf — Zephyr kernel/subsystem config
  • soc_firmware/app/litex_vexriscv.overlay — Device tree (LiteX SoC peripherals)
  • soc_firmware/app/boards/litex_vexriscv.conf — Board-specific Kconfig

FPGA

  • FPGA/ptp/ptpv2_controller.vhd — PTP state machine (Sync, Follow_Up, Announce, Delay_Resp)
  • FPGA/ptp/ptpv2_servo.vhd — Wallclock discipline algorithm
  • FPGA/wallclock.vhd — 48-bit seconds + 32-bit nanoseconds PTP clock
  • FPGA/system_config_reg.vhd — Register interface for SoC-accessible config
  • FPGA/clock_ppb_meter.vhd — PPB correction measurement for external PLL

Conventions

  • FPGA: VHDL preferred for new logic. Verilog used for some audio clock modules.
  • Firmware: Follow Zephyr coding style and device tree conventions.
  • HAL changes: New FPGA register access should go through fpga_hal.h. Driver-level changes need updates in the active backend (fpga_hal_litex.c) and the Ethernet driver (eth_litex.c).
  • CSR headers: After modifying generate.py, regenerate with make in litex_soc/. Generated headers in litex_soc/build/ are imported via litex_csr_compat.h.
  • Verification: When unsure about Zephyr APIs or LiteX CSR semantics, read the source or check upstream docs rather than guessing.
  • Debugging: Zephyr shell (CONFIG_SHELL=y) and logging (LOG_INF, LOG_ERR) are enabled.