Hive-S internals

LiteX/VexRiscv RISC-V soft-SoC on Artix-7. Buildroot rootfs, UWM firmware, single SPI flash image.

Project layout

PathContent
project.jsonConfig: repos, SoC args, flash mapping.
container/Dockerfile (RISC-V toolchain, LiteX pinned to tag 2025.04, bun), entrypoint.
hw/LiteX SoC generator: make.py, soc_linux.py, vhdl/, xci/ (AXI clock converter IP).
buildroot/BR2_EXTERNAL tree: configs/ntl_defconfig, board/hive-s/ (kernel config, post-image), patches/ (LiteX/LiteEth/LiteSPI/VexRiscv kernel patches, vexriscv-aes ssl patches), rootfs_overlay/ (motd, S99uwm.sh, /opt/ntl env + CA + uwm-loader).
images/Build outputs + bitstream.bin. Never touched by template updates.
tools/Vivado/OpenOCD flash scripts (flash_device.tcl, FTDI/Arty configs, bscan-spi bitstream).
ip/Generated IP cores (output of build hw).

Docker volumes: ntl_buildhive_hw_<name>_<id> and ntl_buildhive_sw_<name>_<id>. Host mounts: images/, hw/ (ro, HW container), buildroot/ (ro, SW container).

build hw

  1. HW container: pulls LiteX + VexRiscv sources, runs ./make.py <hw.args> - generates gateware sources and the device tree (rv32.dtb).
  2. Rewrites paths in the generated aionyx_hive_s.tcl from container to host paths.
  3. Host: vivado -mode batch -source aionyx_hive_s.tcl builds the IP cores, copied to ip/.

Bitstream generation itself is manual in Vivado; import the result with buildhive configure bitstream -f <file> (→ images/bitstream.bin).

build sw

SW container, two stages:

  1. UWM - clone sw.uwm into sources/uwm, make out/hive-s_full_tls → images/uwm.xz + uwm-loader; loader also copied into buildroot/rootfs_overlay/opt/ntl.
  2. Buildroot - clone sw.buildroot, make ntl_defconfig (BR2_EXTERNAL=/buildroot), make -j → images/: Image.lzma, rootfs.cpio.xz, u-boot.bin, u-boot.dtb, opensbi.bin, rv32.dtb.

Flash image

build flash runs on the host, no Docker:

  • Each flash mapping entry is wrapped as .fbi: 4-byte length + 4-byte CRC32 + data.
  • mapping_table.bin holds the sorted (src, dst) address pairs.
  • images/flash.bin layout: bitstream at offset 0, each component at src − 0x01000000, mapping table at 0x3F0000.

At boot the SoC firmware walks the mapping table and copies each blob from its flash src to its RAM dst. Entries without dst (e.g. uwm.xz) stay in flash. info flash prints the table and the assembled layout.

deploy flash

vivado -mode gui -source tools/flash_device.tcl - programs the SPI flash over JTAG. Prompts for device selection if several are connected.