Skip to content

Firmware: FuseSoC core library and Hog projects - #446

Draft
lharnaldi wants to merge 14 commits into
mainfrom
fusesoc-hog
Draft

lharnaldi wants to merge 14 commits into
mainfrom
fusesoc-hog

Conversation

@lharnaldi

Copy link
Copy Markdown
Contributor

This PR moves the firmware to a FuseSoC core library and Hog projects. The standard firmware projects are now built from the ported cores, and the legacy project tree and the packaged IPs that those cores replace are removed. The Python side keeps its hand-written drivers.

Each kind of change is a separate commit, so they can be reviewed one at a time:

Commit What it does
firmware: add the RTL library firmware/rtl_lib/: the SystemVerilog/VHDL sources of the ported IPs and their building blocks
firmware: add the fusesoc library cores firmware/fusesoc/cores/lib: one core per building block, each with its testbench
firmware: add the fusesoc IP cores firmware/fusesoc/cores/ip: the 31 IPs (packaging sidecars, constraints, README, tests)
firmware: add the fusesoc environment Makefile, scripts and setup (make sim, make package, make hog-lists-all, ...)
firmware: add Hog and the projects in firmware/Top Hog (submodule) and the 12 standard projects of firmware/projects as Hog projects
firmware: update the shared firmware files small changes to firmware/hdl
firmware: remove the legacy project tree and the ported IP packages firmware/projects, the packaged IPs that the cores replace, qick_com and qick_peripheral_template (unused), and firmware/testbench (it reads the removed packages; QICKEmu replaces it)
firmware: add the ZCU216 demo project in firmware/Top 216/tpv2_demo
qick_lib: support the firmware built from the fusesoc cores drivers bind the new VLNVs; about 100 lines
emulator: add QICKEmu, built from the fusesoc cores
docs: describe the fusesoc and Hog flow, and update the paths it moves
firmware: implementation directives ... / 111/tpv2_std README timing closure of the last two projects
qick_lib: read the reference clock of an ADC tile from the ADC parameters bug fix, independent of the rest (see below)

Behaviour change: signal generator amplitude

The ported axis_signal_gen_v6 quantizes the envelope product at full scale. At the same gain, arb and flat-top pulses are 2x the amplitude of the legacy generator. The driver detects the fusesoc generator, logs a warning and sets env_full_scale, so the plateau of a flat-top pulse stays matched to its ramps. Amplitude calibrations made with legacy firmware do not carry over.

Not changed

  • Legacy IPs that are not ported yet stay in firmware/ip/ as they are (for example axis_pfb_readout_v2, axis_readout_v1, axis_sg_int4_v1, axis_sg_mux4_v1/v2/v3, axis_signal_gen_v4/v5).
  • The SysGen FFT used by the ZCU216 tpv2 projects stays. Its SystemVerilog port will come in a separate PR.
  • Old bitstreams keep working with the new drivers: every driver still binds the legacy VLNVs.

Timing

All 12 projects meet timing: Vivado 2023.1, plain ./Hog/Do CREATEWORKFLOW <project>, no manual step. The build name is the one Hog gives (the SHA of the last commit that changes the project).

Project Build Setup WNS (ns) Hold WHS (ns)
111/tpv1_std 9D75BD7 +0.001 +0.007
111/tpv1_rfbv1_std 5BBEAE5 +0.066 +0.010
111/tpv1_rfbv2_std 5BBEAE5 +0.037 +0.010
111/tpv2_std AD9B7A5 +0.031 +0.009
216/tpv1_std AD9B7A5 +0.000 +0.006
216/tpv2_std 9D75BD7 +0.015 +0.010
216/tpv2_std_rfbv2 9D75BD7 +0.020 +0.009
216/tpv2_demo 4F16EBF +0.003 +0.009
4x2/tpv1_std 9D75BD7 +0.026 +0.010
4x2/tpv2_std 9D75BD7 +0.030 +0.010
2x4/tpv1_std AD9B7A5 +0.000 +0.009
2x4/tpv2_std 9D75BD7 +0.008 +0.010

Several projects close with little or no margin (2x4/tpv1_std and 216/tpv1_std at 0 ps, in the DAC clock). A change in those clock domains may need another round of directives.

Verification

Run on a clean clone of this branch:

  • make sim_svunit (from firmware/fusesoc): the testbenches of all 177 cores pass.
  • Driver register tests: 18 of 18 IPs pass. make driver-bindings: each of the 78 VLNVs is bound by exactly one driver class.
  • make doc-check passes, and make hog-lists-all CHECK=1 shows that the Hog list files match the cores.
  • Every project above was created and built with plain Hog from this branch.

Board tests

Each bitstream was loaded with the drivers of this branch, on a board with SMA loopback cables. The check:

  • finds which generator each readout sees;
  • for each pair, compares const, arb and flat-top pulses: arb/const and the flat-top plateau against arb, both within 10 %;
  • checks that the averaged readout matches the mean of the decimated one;
  • where the firmware has them, captures with the DDR4 and MR buffers.
Board Projects Pairs tested Result
ZCU111 111/tpv1_std gen 5 -> ro 0 pass
ZCU111 111/tpv2_std gen 0 -> ro 2, gen 6 -> ro 0 pass
ZCU216 216/tpv1_std gen 0 -> ro 0 pass
ZCU216 216/tpv2_std gen 0 -> ro 1, gen 8 (int4) -> ro 0 pass
ZCU216 216/tpv2_demo pass
RFSoC 4x2 4x2/tpv1_std, 4x2/tpv2_std 2 pairs each pass
RFSoC 4x2 2x4/tpv1_std, 2x4/tpv2_std gen 0 -> ro 0 pass, partial

The 2x4 projects ran on a 4x2 board with BOARD set to the 2x4: they load and the drivers bind, but only one DAC/ADC pair is wired on that board. They have not run on an RFSoC 2x4.

Not covered: the mux generators, the PFB readouts of the ZCU216 tpv2 projects, and the three RF-board projects (111/tpv1_rfbv1_std, 111/tpv1_rfbv2_std, 216/tpv2_std_rfbv2).

qick_lib: reference clock of the ADC tiles

Since 4972d5e, QickSoc reads the reference clock of every tile, ADC tiles included, from C_DAC<n>_Refclk_Freq. On the ZCU111 tpv2 firmware, ADC tile 2 is enabled and DAC tile 2 is not, and Vivado leaves 6400 MHz in that DAC parameter, so QickSoc refuses the firmware ("refclks [204.8, 204.8, 204.8, 6400.0]"). The released ZCU111 tpv2 firmware has the same tile layout. The fix reads C_ADC<n>_Refclk_Freq for ADC tiles; on the other 11 projects the two parameters hold the same value.

firmware/rtl_lib holds the SystemVerilog and VHDL sources of the ported IPs. It becomes the single source for the
fusesoc cores added next.
The building blocks of the IPs as fusesoc cores, each with its tests. The sources are symbolic links into
firmware/rtl_lib.
One core per IP, named qick:ip:<name>:MAJOR.MINOR.PATCH, with its testbench, its register map in SystemRDL and its
user guide. The packaged IP is generated with make package and is not committed.
Makefile, generators and scripts that simulate, lint, package and document the cores.
Hog is a pinned submodule in firmware/Hog. Each project in firmware/Top/<board>/<project> has its block design, Hog
lists and a proj.tcl that also works without Hog. The block designs use the fusesoc qick:ip VLNVs of every ported IP.
Top-level HDL helpers as the projects in firmware/Top use them; the LO SPI multiplexers become Verilog.
firmware/Top replaces firmware/projects. The IPs ported to fusesoc are generated by make package, so their packages
leave firmware/ip. Of the IPs that are not ported, those superseded by a newer version stay for existing designs;
qick_com (a board link superseded by xcom) and qick_peripheral_template (replaced by the qick_processor README and
qick_periph_loopback) go, since no project uses them. firmware/testbench goes too, because its project reads its
sources from the removed packages, and so do its soccfg.json and the qick_testbench notebooks that drive it. The
emulator added in this branch replaces it.
The port of qick_tprocv2_216_demo, so that the project keeps existing after firmware/projects goes.
Bind the qick:ip VLNVs of the IPs in the standard projects, follow the port names the ports changed (time tagger,
mr_buffer_et, weighted buffer) and the renamed tProc v1 and register slice blocks, and warn about a qick:ip block with
no driver. The tProc v2 assembler accepts revision 29, the revision of the ported core. The drivers keep their
hand-written register maps; legacy firmware follows the same paths as before.

The ported signal generators quantize the envelope product at full scale, so envelope pulses are 2x the legacy
amplitude at the same gain: the driver logs a warning and sets env_full_scale, which keeps the plateau of a flat-top
pulse matched to its ramps.
The Verilator emulator of the qick_emu_v1.1.0 branch, with the design built from the qick:emulator cores
(firmware/fusesoc/cores/lib/emulator, sources in firmware/rtl_lib/emulator) instead of firmware/ip and
firmware/testbench, which this branch removes. docs/source/tutorials/README.rst already points to emulator/ on main.
qick_lib takes the emulator support of that branch: the QickEmu acquire path and board name, phys_addr/addr_range in
the IP config, a trigger without ddr4_buf/mr_buf, the assembler and parser changes.
emulator/regression checks the md5 of seven result arrays against baseline_fusesoc_md5.txt.
Add the firmware documentation and the changelog of the fusesoc environment. The pages of docs/source point to
firmware/fusesoc/cores/ip and firmware/Top where the sources moved, and the link to the tProc v1 note goes with the
note. The ignore rules cover the output of the new flow, including the register packages make driver writes.
…et timing on 2x4 and 216 tpv1_std

Hog applies hog.conf when it creates the project and then sources proj.tcl, whose strategy resets the steps
of the run, so an [impl_1] directive only in hog.conf never reached the build and Hog set the version to 0.
Directives that differ from the strategy are now set in proj.tcl after it, with the same values in hog.conf.

2x4/tpv1_std and 216/tpv1_std failed with the strategy's ExtraNetDelay_high / NoTimingRelaxation by 0.064 and
0.005 ns in the DAC clock. Place ExtraPostPlacementOpt with post-route phys_opt_design met on both in an impl_1
run on the same synthesis: WNS +0.010 ns on 2x4 (route AggressiveExplore), +0.031 ns on 216 (route
NoTimingRelaxation), Vivado 2023.1. 111/tpv2_std goes back to the strategy's directives, the ones it was built
and met timing with.
…s directives

Build AD9B7A5 meets timing: setup WNS +0.031 ns in clk_adc0_x2, hold +0.009 ns.
…ters

The RFDC parse took C_DAC<n>_Refclk_Freq for ADC tile n too. Where ADC tile n is enabled and DAC tile n is
not, Vivado leaves the sampling rate in that DAC parameter (6400 MHz on the ZCU111), and QickSoc refused the
firmware ("RF reference clocks [204.8, 204.8, 204.8, 6400.0] ... must all be equal"). This is the case of
the ZCU111 tProc v2 standard firmware, which uses ADC tiles 0 and 2: the 111/tpv2_std build of this branch
and the released tprocv2r21/r23 bitstreams.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant