<!– SPDX-FileCopyrightText: 2026 Ahmed Imamović SPDX-FileCopyrightText: 2026 Tarik Hamedović SPDX-License-Identifier: CC-BY-SA-4.0 –>
SoC Build and Host Tools
The main SoC build flow lives under 3.build. That directory is the working area for building the LiteX SoC, loading it onto the board, running
the firmware/demo flow, and using the host-side utilities for capture and inspection.
Directory Structure
MakefilePrimary entry point for hardware build, FPGA loading, software build, UART terminal access, and editable Python package installation.
scripts/Host-side tools for capture, UDP reception, conversion, and plotting.
build/Generated LiteX build products such as
csr.csvand bitstreams.*.csv,*.txt,*.binLocal experimental outputs created while debugging or analyzing captures.
Core Flow
The Makefile automatically selects an interpreter from the active virtual
environment, then ./.venv, then ~/litex-venv, and finally falls back to
python3.
Typical sequence:
cd 3.build
make install-python
make build-board
make build-sw
make load
make term PORT=/dev/ttyUSB0
Targets
make install-pythonInstall
2.soc/8.pythonin editable mode so the SoC entry point can be run directly from the repository.make build-boardBuild the gateware using
python -m uberclock_socand the selected target options. Defaults toTOOLCHAIN=vivado; passTOOLCHAIN=openxc7for the Vivado-free flow (see openXC7 Toolchain (Vivado-free build) below).make build-swBuild the bare-metal software under
2.soc/2.swagainst the generated LiteX build tree.make loadProgram the FPGA using the repo-local SoC Python entry point.
make termOpen the LiteX UART terminal and load the first
.binfound under2.soc/2.sw.
Host-side scripts
The python scripts under 3.build/scripts are kept separate from the Makefile and are described below.
serial_capture_to_csv.pySerial-console capture helper. It sends the low-speed or high-speed capture commands, waits for memory fill to finish, requests a text dump, and writes a CSV file.
receive_udp_capture.pyUDP receiver for the repository’s
UBD3DDR dump format. It reconstructs a binary capture, detects missing blocks, validates ramp patterns, and can display the resulting waveform.capture_bin_to_txt.pyConverts a binary
capture.binfile into a plain-text integer sample list.plot_capture_bin.pyQuick waveform and FFT viewer for an existing binary capture.
plot_capture_lanes.pyLane-aware plotting helper for interleaved 16-lane DDR captures.
plot_csv_fft.pyFFT inspector for CSV captures, intended for lower-rate serial-dump analysis.
plot_csv_fft_coherent.pyFixed-parameter FFT view for coherent-tone experiments and frequency labeling.
openXC7 Toolchain (Vivado-free build)
Besides Vivado, make build-board also supports a fully open-source
toolchain: openXC7
(Yosys + nextpnr-xilinx + prjxray). LiteX exposes this through its
XilinxYosysNextpnrToolchain, selected with TOOLCHAIN=openxc7.
Setup (one-time)
The Makefile expects an openXC7 install under /opt/openxc7 (or wherever
OPENXC7_DIR points), with a pre-generated chip database for the target
part under CHIPDB (default ~/openxc7-chipdb). It exports PATH,
CHIPDB, PRJXRAY_DB_DIR and NEXTPNR_XILINX_PYTHON_DIR for the
build automatically when TOOLCHAIN=openxc7 is selected.
The openXC7 packer stage also needs fasm2frames, which is not shipped
by the toolchain-installer binary install and is not the fasm PyPI
package. Install it once via:
2.soc/setup_dev.sh --with-openxc7
This sparse-clones f4pga/prjxray, patches its setup.py (the
utils package that the fasm2frames console-script entry point
depends on is not listed there upstream), and installs it editable into the
LiteX venv.
Building the CPU-only configuration
cd 3.build
make build-board TOOLCHAIN=openxc7 \
OPTIONS='--integrated-main-ram-size=0x10000 --nextpnr-seed=42'
This builds RISC-V CPU + UART + 64 KiB integrated RAM end to end – Yosys,
nextpnr-xilinx, and prjxray’s fasm2frames/xc7frames2bit – with zero
placement or routing errors, and produces a working .bit loadable through
the existing OpenFPGALoader-based programmer.
The reduced 64 KiB RAM size is required, not optional: at the default 256 KiB, Yosys infers a depth-cascaded BRAM pair, and nextpnr-xilinx does not enforce that pair’s required column adjacency, producing an unroutable placement.
Known limitations
--with-uberclock (the DSP core) does not build cleanly under openXC7.
Synthesis itself completes (after keeping hierarchy through
synth_xilinx instead of flattening before optimization, and switching to
Yosys’s abc9 LUT mapper via --yosys-abc9 to stay within LUT
capacity), but placement then hits a reproducible nextpnr-xilinx
placement-legality bug: its placer cannot legalize a CARRY4 chain
shape that Yosys abc9’s ALU-extraction pass produces for the CORDIC
pipeline’s adders. This was tested across placers (heap, sa) and
with -nocarry; every combination hits an independent variant of the same
bug class. This is an upstream toolchain maturity gap, not something
fixable from this project’s RTL or LiteX integration.
--with-uberddr3, --with-ethernet, and --with-hdmi are expected to
need Vivado regardless: XilinxYosysNextpnrToolchain silently drops the
Vivado-only I/O properties UberDDR3’s PHY needs (e.g. INTERNAL_VREF), and
has no real static timing analysis or false-path support, so the DDR3 PHY’s
400 MHz domain would be effectively unconstrained and unverified.
Use Vivado for any configuration that includes --with-uberclock,
--with-uberddr3, --with-ethernet, or --with-hdmi. openXC7 is
solid for the CPU-only bring-up configuration above. See
docs/openxc7_port/main.tex at the repository root for the full,
chronological debugging log: every error hit, its root cause, and its fix or
current workaround.
Firmware Memory Placement and In-place Builds
make build-sw builds the source files directly in 2.soc/2.sw.
The nested 2.soc/2.sw/uberClock directory is an older generated application
copy and is not used by this target. The source linker script is restored after
the build, including when a build command fails. This target uses
SW_CODE_MEM, SW_DATA_MEM and WITH_CXX rather than DEMO_FLAGS.
cd 3.build
make build-sw SW_CODE_MEM=main_ram SW_DATA_MEM=main_ram
The default SoC keeps main_ram in 512 KiB of integrated BRAM.
External DDR3 can instead serve as CPU memory with --with-sdram-main-ram.
That option is mutually exclusive with --with-uberddr3 because both use
the same physical DDR3 device. Select memory regions that exist in the
generated memory map, and rebuild firmware against matching generated CSRs.