Bench Architecture

This page describes the SatLink system as a whole, from the FPGA fabric up to the network services. It is the map to keep in mind when reading a telemetry value or a report.

The Zynq, split in two#

flowchart TB
    subgraph PS["PS: dual Cortex-A9, Linux"]
      sd[satlinkd]
      uio["/dev/uio0 (1 MiB register window)"]
      iio["IIO: satlink-modem-tx / -rx, ad9361-phy, cf-ad9361-dds-core"]
      sd --> uio
      sd --> iio
    end
    subgraph PL["PL: xc7z020 fabric"]
      shell["shell: AXI-Lite decode, IRQ, loopback mux"]
      tx[tx_top]
      rx[rx_top]
      ch[channel_impair]
      mon[monitor_top]
      seq[profile_sequencer]
      dmac["axi_dmac tx / rx / adc"]
      ad["axi_ad9361 (LVDS)"]
    end
    uio -- "M_AXI_GP0, AXI-Lite" --> shell
    iio -- "S_AXI_HP, DMA" --> dmac
    shell --> tx & rx & ch & mon & seq
    dmac --> tx
    rx --> dmac
    tx --> ad
    ad --> rx
    ad <--> chip((AD9361))

• Control plane. The PS reaches the PL's registers through one 1 MiB AXI-Lite window at 0x4000_0000, mapped into user space by the kernel's UIO driver as /dev/uio0 (named satlink). satlinkd reads and writes registers by name through a catalogue that shares its addresses with the daemon's own code (see PL Register Map).
• Data plane. Bytes travel between the PS and the modem through ADI axi_dmac cores, exposed by a SatLink kernel module (satlink-modem.ko) as two IIO buffer devices, satlink-modem-tx and satlink-modem-rx. A third DMA channel captures raw ADC samples for IQ captures and the spectrum view.
• RF front end. ADI's axi_ad9361 core connects the fabric to the AD9361's LVDS bus. The AD9361 itself is configured by the Linux ad9361-phy driver over SPI; its DAC core appears as cf-ad9361-dds-core.

The DMA wire format: le:u8/32#

The modem's byte streams are 8 bits wide, but the DMA moves 32-bit words. Each 32-bit little-endian word carries one useful byte in its low lane; the other three bytes are zero.

satlinkd expands and extracts the lanes for you: what you push through the API, the CLI or the link service is plain bytes, and what the link service publishes is lane-extracted. Two consequences matter:

• A block is only submitted to the DMA when it is full. Low-rate traffic must be flushed (see Datapath and Transmission).
• Frame lengths used for slot framing and transfer frames must divide 4096, or alignment is lost at the first flush.

Files for satlinkctl loopback and satlinkctl compare are in the raw le:u8/32 encoding, unless compare --dense is given.

Clocks#

Register accesses to modem blocks cross from fclk0 to the modem clock through a request and acknowledge synchroniser; samples cross between the modem clock and the AD9361 clock through two asynchronous FIFOs.

The three signal paths#

The chain target decides where the transmitter's samples go:

• The PL loopback is the reference: it has no analog path and no frequency or phase error, and it is the only path with the channel emulator.
• The device loopback proves the LVDS interface in both directions. The LOs, gains and attenuation have no effect on it at all, and nothing reaches a connector; calling it "RF" is a classic source of confusion.
• The air target is the only one that reaches the connectors. Your cabling decides whether the signal comes back into RX1 (an external loopback) or reaches another radio.

A profile's radio.loopback flag writes the loopback mux on every apply. Chain conditioning applies the profile first and sets the mode afterwards, so the mux ends up where the target wants it. See Chain Conditioning.

Shadow registers and the profile sequencer#

Most modem configuration registers are double-buffered. A write lands in the shadow bank, the datapath keeps running on the active bank, and the profile sequencer swaps them in one cycle when asked. Its states:

A commit only happens at a safe point. If some stream never goes quiet, the sequencer stays in WAIT_SAFE and the apply times out: SEQ_STATE = 0x03 is therefore also a sign that the datapath is jammed. Reads always return the active bank, so a staged write reads back as the old value until it is committed.

Inside satlinkd#

satlinkd is one Rust process built from a set of crates under ps/crates/:

The run store lives at /var/lib/satlink/satlink.db, on the RAM disk: reports do not survive a reboot. Export the ones you need (see Analysis & Reporting). Campaign cursors live on the persistent /mnt/jffs2 partition so a campaign can resume after a reboot it asked for.

Where things are configured#