ZC706 + ADRV9009: JESD204B HDL and no-OS Bare-Metal Link
Complete guide to building the ZC706 + ADRV9009 JESD204B link — HDL project generation, block design parameters, no-OS initialization sequence, link self-check, DMA capture, and a five-point troubleshooting checklist.
1. One ZC706 + One ADRV9009: What This HDL + no-OS Project Actually Solves
For anyone who has both a ZC706 and an ADRV9009 evaluation board, the first blocker is usually not RF performance — it's "how do I actually build this link?" This zc706_adrv9009 project puts the answer right in front of you: on the HDL side, a synthesizable JESD204B transceiver link plus DMA; on the SDK side, a no-OS bare-metal program that, after power-up, brings up the AD9528 clock, the ADRV9009 profile, the JESD204B link state, and the RX/TX channel enables — all without any operating system — and finally reads raw sample data from DDR. It's suitable for RF and FPGA developers who just got the boards and want to do prototype validation, and also for embedded engineers who have algorithms and want to rewire the bare-metal path to their own data port. The project isn't large, but it paves the most time-consuming road: board-level connections → link parameters → bare-metal initialization.
2. Project Skeleton: How hdl and no-OS Divide the Work
2.1 Hardware Layering from the FMC HPC Upward
The ZC706 is a Zynq-7045 board with a dual-core A9 PS and on-board DDR3. On the PL side, it exposes an FMC HPC connector carrying 4 GTH transceivers, a pair of GBTCLK differential reference clocks, and a large number of LA/HA single-ended IOs. The ADRV9009 evaluation board plugs into this FMC port — power, SPI control lines, GPIO, device clock, SYSREF, and 4 SERDES lanes all pass through this connector. Understanding this is critical, because it determines the division of labor for all subsequent code.
The division is straightforward: the PS handles only slow control — configuring AD9528 and ADRV9009 registers via SPI, reading link status, starting DMA, and moving data from DDR to serial or Ethernet. The PL handles only high-speed data — GTH transceiving, JESD204B deframing, sample reordering, and DMA transfers. This split isn't laziness on the designer's part; it's because ADRV9009 sample rates are often hundreds of MSPS, and no frame of data could make it through PS software interrupts in time. The hdl and no-OS repositories being separate is the physical embodiment of this boundary.
2.2 Directory Structure: What Each Repository Manages
After extraction, the typical directory layout looks roughly like this. Different versions vary, but the layering logic is stable:
zc706_adrv9009/
├── hdl/ # Vivado side, produces bit and xsa
│ ├── projects/adrv9009_zc706/
│ │ ├── adrv9009_zc706.v # Top level, instantiates system_wrapper and board IO
│ │ ├── system_bd.tcl # Pure script description of the block design
│ │ ├── system_constr.xdc # FMC pins, clocks, timing constraints
│ │ └── adi_project_adrv9009_zc706.tcl# Project entry, calls IPs in library
│ └── library/
│ ├── axi_adrv9009/ # TX/RX core, channel alignment and sample alignment here
│ ├── axi_adxcvr/ # GTH dynamic reconfiguration, used to change line rate
│ ├── axi_jesd204_tx/ axi_jesd204_rx/# JESD204B link layer
│ └── xilinx/axi_dmac/ # DMA for capture and transmit
└── no-OS/ # SDK/Vitis side, produces elf
├── projects/adrv9009/src/app/ # app_config.h, clock and JESD initialization
├── projects/adrv9009/src/hal/ # Platform abstraction: SPI, GPIO, delay, UART
└── src/ # Drivers for adrv9009, ad9528, axi_*
The IPs in library are where this project's real value lies. axi_adrv9009 reorders deframed data by channel, performs 16-bit alignment, and provides valid signals; axi_jesd204_rx handles link-layer state machines like CGS and ILA; axi_adxcvr lets you change GTH line rates at runtime without re-synthesizing. During secondary development you'll basically never touch the internal logic of these IPs, but you must know which port the data comes out of.
The drivers under no-OS/src are pure C — no OS dependency, no dynamic memory allocation, all device structures static. This is especially friendly for bare-metal debugging: to check a status, just set a breakpoint in main — register reads and writes are synchronous, so you won't get the "state changed in an interrupt but the main loop doesn't see it" weirdness.
2.3 Four Modules Chained in a Receive Path
Looking at the receive direction alone, the data flow is: the GTH transceiver deserializes the differential signal into parallel data, hands it to axi_jesd204_rx for 8b/10b decoding and frame alignment, then to axi_adrv9009_rx to split interleaved samples into CH0 and CH1, and finally through AXI4-Stream into axi_dmac, which writes it via DMA to a specified address in PS-side DDR. The transmit direction is perfectly symmetric, just swapping DMA for read and deframer for framer.
Every stage on this chain has its own status registers, and all can be read from the PS side. For the GTH stage, look at axi_adxcvr's CPLL/QPLL lock bits; for the JESD stage, look at link state and per-lane sync status; for the ADRV9009 core stage, check for overflow flags; for the DMA stage, check the transfer complete count. Debug in this order, stage by stage — when a stage breaks, stop there. Don't thrash on data content repeatedly.
3. HDL Side Breakdown: From tcl to bit — How the JESD204B Link Is Built
3.1 Generating the Vivado Project with make
ADI's hdl repository is driven by Makefiles — no need to manually click through Vivado's GUI. After entering the project directory, set environment variables first, then proceed in two steps:
cd hdl/projects/adrv9009_zc706
# Point to your local Vivado; the version must match what the project's IPs support
export XILINX_VIVADO=/opt/Xilinx/Vivado/2021.1
export PATH=$XILINX_VIVADO/bin:$PATH
# Step 1: generate the project only, no synthesis — block design visible in tens of seconds
make project
# Step 2: synthesis + implementation + export xsa — roughly 10s of minutes to 1 hour depending on machine
make
The make project step is well worth running separately. It rebuilds the block design, constraints, and IP parameters entirely from the adi_project_adrv9009_zc706.tcl script, generating a Vivado project you can open directly. After opening, first check the Address Editor for each AXI peripheral's address allocation, then confirm the JESD204 lines are connected to the correct GTHs — much faster than guessing from documentation from scratch.
The make output is in the build/ directory, producing both the bit file and the xsa. The xsa is what you'll use later to create the platform in Vitis/SDK — don't grab the plain bit by mistake.
make, the platform project in Vitis must be regenerated along with its BSP. Otherwise the address mapping is still old — the program compiles but crashes immediately when run.3.2 How the RX Link Is Assembled in system_bd.tcl
The block design isn't drawn — it's written by script. The core sections for the receive direction look roughly like this. Parameter names vary slightly between versions — copy from your own adi_project_*.tcl, don't write from memory:
# Receive direction: GTH transceiver -> JESD204B RX -> ADRV9009 RX core
ad_ip_instance axi_adxcvr axi_adxcvr_rx
ad_ip_parameter axi_adxcvr_rx CONFIG.NUM_OF_LANES 4
ad_ip_parameter axi_adxcvr_rx CONFIG.TX_OR_RX_N 0 ;# 0 = receive direction
# Link layer: lane count, converter count, bit width, samples per frame must match profile
ad_ip_instance axi_jesd204_rx axi_jesd204_rx
ad_ip_parameter axi_jesd204_rx CONFIG.NUM_OF_LANES 4
ad_ip_parameter axi_jesd204_rx CONFIG.NUM_OF_CONVERTERS 2
ad_ip_parameter axi_jesd204_rx CONFIG.CONVERTER_RESOLUTION 16
ad_ip_parameter axi_jesd204_rx CONFIG.SAMPLES_PER_FRAME 4
# Application-layer core: channel splitting and sample alignment, output to DMA
ad_ip_instance axi_adrv9009 axi_adrv9009_rx
ad_connect axi_adrv9009_rx/gt_rx_data axi_jesd204_rx/gt_rx_data
ad_connect axi_jesd204_rx/adc_data axi_adrv9009_rx/adc_data
NUM_OF_LANES 4 corresponds to the common configuration of two receive channels each occupying 2 lanes. NUM_OF_CONVERTERS 2 means there are two converters (two receive channels) on this link. CONVERTER_RESOLUTION 16 is the container bit width used in JESD204B transport — the ADRV9009's internal ADC is 12-bit, but the link layer aligns to 16 bits. Getting this value wrong causes sample high/low bit misalignment, and the symptom is a waveform that looks like it has signal but is entirely distorted.
SAMPLES_PER_FRAME corresponds to the F parameter in the profile — the number of samples carried per frame per lane. These parameters aren't arbitrary choices; they correspond one-to-one with the ADRV9009's internal profile. Changing any one requires changing both sides simultaneously — the consequences of changing only one side are detailed in Chapter 5.
3.3 If the Profile Numbers Don't Match, the Link Won't Come Up
The hardest part of JESD204B is parameter coupling. This table is what I check every time I change the configuration. Values are based on a typical profile at 245.76 MSPS:
| Parameter | Meaning | Typical Value | Direct Consequence of Wrong Value |
|---|---|---|---|
| L | Number of lanes per link | 2 per channel, 4 total | One lane short — fails at CGS stage |
| M | Number of converters per link | 2 | Channel data misaligned, CH1 mixed into CH0 |
| F | Octets per frame per lane | 4 | Frame boundary miscalculated, data offset overall |
| K | Frames per multiframe | 32 | SYSREF alignment fails, link state repeatedly toggles |
| S | Samples per converter per frame | 1 | Actual sample rate differs from what you think |
These parameters also determine the line rate. Calculating with the values above: sample rate 245.76 MSPS × M=2 × 16 bit × 10/8 ÷ 2 lanes per channel = 4.9152 Gbps per lane. This number must fall within the GTH capability range on the ZC706, and must also match the reference clock divider configured in axi_adxcvr. If the calculated line rate exceeds that GTH tier's limit, synthesis won't report an error, but on the board the CPLL won't lock — the symptom looks like broken hardware, with the transceiver never locking.
The device clock must be calculated too. It's typically 1/20 of the line rate — 245.76 MHz in the example above — output by the AD9528, fed through the FMC clock pin into the PL, and also fed to the ADRV9009 itself. SYSREF is an integer division of the device clock, and the division ratio must cover the K×F multiframe length. Once the relationship between these three frequencies breaks, the link simply won't come up — and the error messages are extremely vague, leaving you to capture with an oscilloscope or ILA.
NUM_OF_LANES, NUM_OF_CONVERTERS, and SAMPLES_PER_FRAME must be changed from the same source. Mismatch between the two sides is the most common failure point in this project.4. no-OS Side Breakdown: What Happens in the Few Hundred Milliseconds from Power-Up to Data
4.1 Initialization Order in main
Bare-metal programs have no OS to sort dependencies for you — all initialization order must be hard-coded. The main logic in this project looks roughly like this. Function names may differ by a few letters from your copy, but the order is consistent:
int main(void)
{
int32_t status;
struct adi_hal *hal = NULL;
/* 1. Platform layer: UART, interrupt controller, timer, SPI/GPIO handles */
status = adi_hal_init(&hal, &hal_init_param);
if (status != SUCCESS)
goto error;
/* 2. Clock chip AD9528: output device clock and SYSREF first, everything else depends on it */
status = ad9528_init(&ad9528_device, &ad9528_init_param, hal);
if (status != SUCCESS)
goto error;
status = ad9528_setup(&ad9528_device);
/* 3. Transceiver itself: load profile via SPI, enable channels, run internal calibration */
status = adrv9009_init(&adrv9009_device, &adrv9009_init_param, hal);
if (status != SUCCESS)
goto error;
status = adrv9009_setup(&adrv9009_device);
/* 4. JESD204B: wait for link to come up, then start DMA capture */
status = app_jesd204_setup();
/* 5. Enter main loop, periodically read status and move data */
while (1) {
app_monitor();
mdelay(1000);
}
error:
while (1)
; /* Stop here, use debugger to see which step status stopped at */
return status;
}
The order cannot be swapped. The AD9528 must come before the ADRV9009, because the latter only responds to SPI after detecting a valid device clock at power-up. JESD204B link enable must come after the ADRV9009 profile is loaded — otherwise the framer's output data format isn't yet defined, and the receive side will be stuck in CGS forever.
adrv9009_setup before ad9528_setup "to be faster." The result: SPI ID reads kept returning 0, and they spent ages thinking it was a soldering problem.The adrv9009_setup step internally runs a period of calibration, including quadrature error correction and DC offset correction, taking a few hundred milliseconds. During this time the CPU is purely blocking — no UART output at all. On the first run, don't assume the program died. Set the timeout larger, or print a log line beforehand.
4.2 Link Self-Check: Read Link State and Lane Status
Before questioning the data, confirm the link is correct. The JESD204B state machine has clear levels: CGS is code group synchronization, ILA is initial lane alignment — data is only usable after both complete:
#define JESD_LINK_CGS_DONE 0x1
#define JESD_LINK_ILA_DONE 0x3
static int32_t wait_link_up(struct axi_jesd204_rx *jesd, uint32_t timeout_ms)
{
uint32_t link_state = 0;
uint32_t lane_state = 0;
uint32_t elapsed = 0;
while (elapsed < timeout_ms) {
/* Overall link status; register offset per axi_jesd204 driver header */
axi_jesd204_rx_read(jesd, AXI_JESD204_REG_LINK_STATE, &link_state);
if ((link_state & JESD_LINK_ILA_DONE) == JESD_LINK_ILA_DONE)
return SUCCESS;
mdelay(10);
elapsed += 10;
}
/* Not up — print each lane's status to see if all or just some lanes are unsynced */
axi_jesd204_rx_read(jesd, AXI_JESD204_REG_LANE_STATUS, &lane_state);
printf("link=%lx lanes=%lx\n", link_state, lane_state);
return FAILURE;
}
link_state of 1 means only CGS done; 3 means truly usable. Stuck at 1 usually means lane polarity reversed or line rate mismatch; always 0 means check whether the GTH is locked. lane_state is bit-mapped — each bit corresponds to one lane. If only one bit won't light up, the problem is most likely on that lane's physical connection or that lane's K-code configuration, not global parameters.
adrv9009_setup and before DMA start, as a hard gate. If the link isn't up and you keep running, the data you get is garbage — which will make you think your algorithm is wrong.4.3 DMA Moves Data into DDR
Once the link is up, data is a continuous AXI4-Stream that needs a mover to land it in memory. The project uses axi_dmac, configured for PL-to-PS-DDR direction in cyclic mode:
/* Capture buffer address: don't collide with .bss/.data, generally in a reserved region or high DDR */
#define ADC_CAPTURE_ADDR (0x20000000UL)
#define ADC_CAPTURE_SIZE (65536 * 4) /* Two channels interleaved, 4 bytes per group after 16-bit alignment */
static struct axi_dmac rx_dmac;
static struct axi_dmac_init rx_dmac_init = {
.name = "rx_dmac",
.base = RX_DMA_BASEADDR,
.irq_option = IRQ_DISABLED, /* Bare-metal: poll first, don't enable interrupts right away */
};
static int32_t start_capture(void)
{
struct axi_dmac_transfer transfer = {
.src_addr = RX_CORE_DATA_ADDR, /* RX core data port address */
.dest_addr = ADC_CAPTURE_ADDR,
.size = ADC_CAPTURE_SIZE,
.flags = DMA_TRANSFER_CYCLIC, /* Cyclic transfer, overwrite each round when full */
};
axi_dmac_init(&rx_dmac, &rx_dmac_init);
axi_dmac_transfer_start(&rx_dmac, &transfer);
/* Wait for first round to complete; afterward you can read the buffer directly from DDR */
return axi_dmac_transfer_wait_completion(&rx_dmac, 2000);
}
ADC_CAPTURE_SIZE is the byte count per transfer — must be an integer multiple of the DMA width and aligned to that DDR region's boundary. Cyclic mode's benefit is uninterrupted capture; the cost is the buffer gets overwritten, so when reading data you either stop DMA or use double buffering. This doesn't matter for prototype validation, but must change for any production logic.
irq_option is deliberately set to IRQ_DISABLED. In a bare-metal environment, the interrupt vector table and GIC initialization must be built by hand. Enabling interrupts from the start easily leads to "breakpoints won't stop" and "program jumps randomly somewhere." Poll first to get the path working and confirm data correctness, then switch to interrupts.
5. Troubleshooting Checklist: Five Places to Look First When the Link Won't Come Up or Data Is All Zeros
5.1 link state Stuck at CGS
Symptom: UART repeatedly prints link=1, lane_state shows some lanes synced, but never reaches ILA complete.
Cause: Most commonly, SYSREF isn't reaching the FPGA, or it's in continuous mode but phase isn't aligned to LMFC; second most common is the AD9528 configured the clock but didn't enable SYSREF output.
Solution: First read AD9528's readback registers to confirm the SYSREF channel is truly enabled, then confirm the SYSREF differential pair on the FMC is connected to the correct pins and the constraints have the corresponding IO standard, and finally try changing SYSREF to N-shot single output. The most direct approach at this step is to capture the sysref rising edge with ILA.
5.2 Changed the Profile but Didn't Re-run Synthesis
Symptom: The software-side readback of channel enables is correct, SPI communication is fine, but captured data has two paths mixed together or is offset by half a sample overall.
Cause: Only changed the configuration arrays and profile files in no-OS, while the HDL's NUM_OF_CONVERTERS and SAMPLES_PER_FRAME are still old values — the two sides don't match.
Solution: Copy the L/M/F/K/S from the profile to the corresponding ad_ip_parameter entries in system_bd.tcl, re-run make to produce bit and xsa, then rebuild the Vitis platform and BSP. Never think you can skip this flow.
5.3 Program Downloads but Crashes
Symptom: In Vitis, clicking debug stops the program inside adi_hal_init and it won't come out, or UART prints nothing at all.
Cause: Changed to a new xsa but the BSP is still old — peripheral base addresses don't match; or PS-side UART/DDR parameters don't match the actual board configuration.
Solution: Delete the platform project and recreate it, regenerate the BSP, then confirm that macros like XPAR_AXI_UART in xparameters.h have addresses matching those shown in Vivado's Address Editor. There's no shortcut here.
5.4 Captured Data Is All Zeros or Constants
Symptom: DMA transfer complete flag is set, but the buffer reads all 0x0000 or a repeating value.
Cause: Three possibilities — the ADRV9009 receive channel isn't enabled at all; the RX core's AXI-Stream has no valid signal; or DMA's source address points to the wrong place.
Solution: First read the ADRV9009 channel enable register to confirm, then use ILA to capture the RX core output port's valid and data, and finally check the DMA source address against the Address Editor. Following this order, you'll usually localize within three steps.
5.5 Synthesis Passes but Timing Doesn't Close
Symptom: Implementation reports setup violations, or on-board data shows occasional errors and fails when temperature rises.
Cause: FMC GTH reference clock constraints not written, or SYSREF line routed as ordinary IO without IDDR/ODDR handling for clock domain crossing.
Solution: Check whether create_clock in system_constr.xdc covers GBTCLK, and whether the SYSREF-related set_input_delay is filled in per transmission delay. For paths with very small timing margin, prioritize checking the JESD204 stages' clock domain crossing handshakes — that's where problems most easily arise.
6. Secondary Development: Changing Sample Rate, Connecting Your Own Algorithm Module, and How to Verify You Didn't Break Anything
Changing the sample rate involves more changes than you'd think. The complete action set: regenerate the profile with the configuration tool, copy the L/M/F/K/S back into system_bd.tcl, write the new device clock and line rate into AD9528's divider parameters, re-run make to produce bit and xsa, then synchronize the profile configuration arrays in no-OS. After changing, don't rush to capture data — run the self-check in Section 4.2 to confirm link state reaches 3, then capture a single tone and do an FFT to see whether SNR and SFDR have dropped. If they drop too much, the problem is clock or JESD parameters, not the RF circuit.
To connect data into your own algorithm module, the easiest approach is not to modify axi_adrv9009, but to insert a bypass tap between it and the DMA — listening only, not participating in handshakes:
// Bypass monitor: doesn't consume DMA bandwidth, doesn't alter original valid/ready timing
tap_adc_stream u_tap (
.clk (rx_clk),
.rst (rx_rst),
.s_axis_tvalid (rx_valid),
.s_axis_tdata (rx_data[31:0]), // CH0/CH1 each 16-bit interleaved
.peak_flag (peak_flag) // Used as soft interrupt for PS
);
Inside this module you can do simple threshold detection, accumulation, or decimation, with results returned to PS via AXI-Lite registers. Verification after modification is fixed at three steps: first read JESD link state to confirm it hasn't been dragged down, then use ILA to capture peak_flag to confirm trigger timing is correct, and finally return to PS to compare the tap's statistics against the DMA buffer data for self-consistency. Only after all three pass is the change considered complete.
7. Quick Project Validation
If you want to shorten development cycles and accelerate project validation, we recommend the following board: