The Zynq SoC & the AXI Bus

Everything you have built so far lived in the programmable logic (PL): LUTs, flip-flops, block RAMs and DSP slices that you wire together with HDL. But the chip on the PYNQ-Z2 is not just an FPGA. The Zynq XC7Z020 is a system-on-chip (SoC): next to the PL sits a complete processing system (PS) built around a dual-core ARM Cortex-A9 processor, running at 650 MHz on this board, with its own 512 MB of DDR3 memory. The PS is ordinary, fixed silicon — it runs Linux and Python just like a small computer.

The point of putting the two together is to let each do what it is good at. Software is flexible and easy to change; hardware is parallel, deterministic and cycle-exact. In Part VII you will write a peripheral in the PL, talk to it from the ARM, and end (Chapter 22) with Python feeding your own accelerator. This chapter is about the road between the two worlds: the AXI bus.

A useful rule of thumb: put in the PS anything that is control, irregular or changes often — the operating system, file and network access, the user interface, decisions. Put in the PL anything that is a fixed, repetitive operation on a stream of data, or that needs exact timing — filters, pixel pipelines, protocol engines, counters measured in nanoseconds. The PL has no instruction fetch and no operating system; it does the same thing on every clock edge.

Unlike a pure FPGA, the Zynq is a processor-first device: the PS always starts first, and the PL stays blank until someone configures it. At a high level, booting from the SD card goes like this:

1. A boot ROM burnt into the PS reads the boot-mode jumpers and loads the first-stage boot loader (FSBL) from the SD card into on-chip memory.
2. The FSBL sets up the clocks, the DDR controller and the pin multiplexing of the PS. These settings come from the Vivado configuration of the processing system. It can also load a bitstream into the PL.
3. The FSBL hands over to a second-stage loader (U-Boot), which starts the Linux kernel.
4. Once Linux runs, a program can (re)load the PL at any time. That is exactly what PYNQ does when you create an Overlay in Chapter 21: the bitstream becomes a file you load from Python.

The PS also gives the PL its clocks (FCLK_CLK0 to FCLK_CLK3, typically 100 MHz for FCLK_CLK0 in a PYNQ design), a reset, and interrupt lines from the PL back to the ARM. In Part VII the PL logic attached to the AXI bus runs from FCLK_CLK0, not from the 125 MHz board oscillator on H16 that Part V used.

AXI (Advanced eXtensible Interface) is part of ARM's AMBA family of on-chip bus standards. Every Xilinx IP block speaks it, so learning it once lets you connect anything to anything. The side that starts a transaction is the master (also called manager); the side that answers is the slave (subordinate). Three variants matter here:

Memory-mapped AXI (Lite and full) works like reading and writing memory: every transfer carries an address, and the slave decides what that address means. A peripheral exposes its controls as memory-mapped registers: writing 5 to address 0x43C0_0004 is not storing a number in RAM, it is setting an input of your hardware. AXI-Stream has no addresses at all — it is a one-way pipe from a source to a sink, ideal for data that simply flows.

AXI4-Lite splits a peripheral access into five independent channels, each with its own handshake. Writes use three, reads use two:

Because AW and W are separate channels, the address and the data of a write may arrive in either order, or in the same cycle. The slave answers on B only after it has both. Full AXI4 adds burst length and type, IDs for out-of-order transactions, and WLAST/RLAST to mark the last beat of a burst — but the channels and the handshake are the same. AXI-Stream keeps only one channel: TVALID, TREADY, TDATA, and optionally TLAST (end of packet) and TKEEP(which bytes are valid).

Every AXI channel, of every flavour, moves data with the same two wires. The source drives VALID (“the data on the bus is meaningful”); the destination drives READY (“I can take it”). The precise rules are short:

1. A transfer happens on a rising clock edge at which VALID and READY are both high. On any other edge, nothing moves.
2. The source must not wait for READY before asserting VALID.
3. Once the source asserts VALID, it must keep VALID high and the data unchanged until the transfer happens.
4. The destination may wait for VALID before asserting READY, and may raise and lower READY freely while VALID is low.

From the ARM's point of view, the PL is a range of addresses. A load or store to an address in that range leaves the processor, travels out of a master port as an AXI-Lite (or AXI) transaction, passes through an interconnect that looks at the address and routes it to one slave, and comes back with a response. The table that says which slave owns which range is the address map, set in Vivado's address editor (Chapter 20).

Inside a peripheral, registers are 32 bits wide and AXI addresses count bytes, so register\(k\) lives at byte offset \(4k\):

When Vivado assigns addresses automatically, the first custom peripheral on GP0 typically lands at 0x43C0_0000. Treat that as a common default, not a law — always read the actual value from the address editor, or let PYNQ read it for you from the hardware description file.

The PS exposes several AXI ports to the PL, each with a different job. (Internally the Zynq-7000 ports speak AXI3, the previous version of the protocol; Vivado inserts the converters for you, so your IP can be AXI4.)

GP (general purpose) ports are for control: a handful of register accesses, each taking on the order of a hundred nanoseconds or more round trip. HP (high performance) ports have their own FIFOs and a short path to the DDR controller; a DMA engine in the PL uses them to stream large buffers while the ARM does something else. HP accesses bypass the ARM's caches, which is why Chapter 21 must worry about cache coherence. The ACP (accelerator coherency port) goes through the ARM's snoop control unit, so the PL sees the same data as the caches — convenient for small, latency-sensitive exchanges, at the cost of competing with the CPU for the cache.

The handshake has a hidden cost. In a long pipeline, TREADY travels backwards: if the last stage stalls, every stage before it must stall in the same cycle. If TREADY is computed combinationally through several modules, that path gets long and limits the clock frequency (Chapter 15). The standard fix is a register slice: a small block that sits on a stream and drives every one of its outputs, including the upstream TREADY, from a flip-flop.

The catch: with a registered s_tready, the slice tells the source “ready” one cycle before it knows whether the sink will stall. If the sink does stall, the word that arrives anyway must go somewhere. A second storage slot — the skid buffer — catches it, and s_tready drops for the next cycle. Our version also counts transferred words, a handy debugging register.

// AXI4-Stream register slice ("skid buffer") with a transfer counter.
// Every output is driven straight from a flip-flop, so the slice cuts
// long combinational paths in BOTH directions (data forward, tready back)
// while still moving one word per clock when nobody stalls.
module axis_skid #(
    parameter W = 32                  // TDATA width in bits
) (
    input  wire         clk,
    input  wire         rst,
    // slave side (upstream source -> us)
    input  wire         s_tvalid,
    output reg          s_tready = 1'b0,
    input  wire [W-1:0] s_tdata,
    input  wire         s_tlast,
    // master side (us -> downstream sink)
    output reg          m_tvalid = 1'b0,
    input  wire         m_tready,
    output reg  [W-1:0] m_tdata  = {W{1'b0}},
    output reg          m_tlast  = 1'b0,
    // number of words delivered on the master side
    output reg  [31:0]  count    = 32'd0
);
    reg         skid_valid = 1'b0;          // second storage slot
    reg [W-1:0] skid_data  = {W{1'b0}};
    reg         skid_last  = 1'b0;

    wire in_xfer  = s_tvalid & s_tready;    // a word enters this cycle
    wire out_xfer = m_tvalid & m_tready;    // a word leaves this cycle

    always @(posedge clk) begin
        if (rst) begin
            m_tvalid   <= 1'b0;
            skid_valid <= 1'b0;
            s_tready   <= 1'b0;
            count      <= 32'd0;
        end else begin
            if (out_xfer)
                count <= count + 1;

            if (m_tready || !m_tvalid) begin
                // the output register is free (or being emptied) this cycle
                if (skid_valid) begin
                    m_tvalid   <= 1'b1;            // drain the skid slot first
                    m_tdata    <= skid_data;
                    m_tlast    <= skid_last;
                    skid_valid <= 1'b0;
                end else begin
                    m_tvalid   <= in_xfer;         // pass the input straight on
                    m_tdata    <= s_tdata;
                    m_tlast    <= s_tlast;
                end
                s_tready <= 1'b1;                  // both slots free next cycle
            end else if (in_xfer) begin
                // output is stalled but we already promised to take this word
                skid_valid <= 1'b1;
                skid_data  <= s_tdata;
                skid_last  <= s_tlast;
                s_tready   <= 1'b0;                // full: stop the source
            end
        end
    end
endmodule

-- AXI4-Stream register slice ("skid buffer") with a transfer counter.
-- Every output is driven straight from a flip-flop, so the slice cuts
-- long combinational paths in BOTH directions (data forward, tready back)
-- while still moving one word per clock when nobody stalls.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity axis_skid is
    generic (
        W : positive := 32                          -- TDATA width in bits
    );
    port (
        clk      : in  std_logic;
        rst      : in  std_logic;
        -- slave side (upstream source -> us)
        s_tvalid : in  std_logic;
        s_tready : out std_logic;
        s_tdata  : in  std_logic_vector(W - 1 downto 0);
        s_tlast  : in  std_logic;
        -- master side (us -> downstream sink)
        m_tvalid : out std_logic;
        m_tready : in  std_logic;
        m_tdata  : out std_logic_vector(W - 1 downto 0);
        m_tlast  : out std_logic;
        -- number of words delivered on the master side
        count    : out std_logic_vector(31 downto 0)
    );
end entity;

architecture rtl of axis_skid is
    signal out_valid  : std_logic := '0';           -- output register
    signal out_data   : std_logic_vector(W - 1 downto 0) := (others => '0');
    signal out_last   : std_logic := '0';
    signal in_ready   : std_logic := '0';
    signal skid_valid : std_logic := '0';           -- second storage slot
    signal skid_data  : std_logic_vector(W - 1 downto 0) := (others => '0');
    signal skid_last  : std_logic := '0';
    signal n_out      : unsigned(31 downto 0) := (others => '0');
    signal in_xfer    : std_logic;
    signal out_xfer   : std_logic;
begin
    in_xfer  <= s_tvalid and in_ready;              -- a word enters this cycle
    out_xfer <= out_valid and m_tready;             -- a word leaves this cycle

    process (clk)
    begin
        if rising_edge(clk) then
            if rst = '1' then
                out_valid  <= '0';
                skid_valid <= '0';
                in_ready   <= '0';
                n_out      <= (others => '0');
            else
                if out_xfer = '1' then
                    n_out <= n_out + 1;
                end if;

                if m_tready = '1' or out_valid = '0' then
                    -- the output register is free (or being emptied) this cycle
                    if skid_valid = '1' then
                        out_valid  <= '1';          -- drain the skid slot first
                        out_data   <= skid_data;
                        out_last   <= skid_last;
                        skid_valid <= '0';
                    else
                        out_valid  <= in_xfer;      -- pass the input straight on
                        out_data   <= s_tdata;
                        out_last   <= s_tlast;
                    end if;
                    in_ready <= '1';                -- both slots free next cycle
                elsif in_xfer = '1' then
                    -- output is stalled but we already promised to take this word
                    skid_valid <= '1';
                    skid_data  <= s_tdata;
                    skid_last  <= s_tlast;
                    in_ready   <= '0';              -- full: stop the source
                end if;
            end if;
        end if;
    end process;

    s_tready <= in_ready;
    m_tvalid <= out_valid;
    m_tdata  <= out_data;
    m_tlast  <= out_last;
    count    <= std_logic_vector(n_out);
end architecture;

Read the main branch carefully. If the output register is empty or being emptied this cycle (m_tready || !m_tvalid), it is refilled — from the skid slot if that holds a word (to keep the order), otherwise straight from the input. Otherwise the output is stalled, and a word accepted this cycle is parked in the skid slot. The two slots are enough because s_tready drops exactly one cycle after the stall begins.

A stream block that works when everybody is always ready proves very little. The testbench below makes the source go idle about 25 % of the time and the sink refuse about 50 % of the time, using two 16-bit LFSRs (linear-feedback shift registers, cheap pseudo-random generators) so both languages see exactly the same “random” pattern. It checks four things: the words arrive in order, TLAST marks every eighth word, the slice never changes m_tvalid or m_tdata while stalled (rule 3), and the counter equals the number of words received. The source in the testbench obeys the rules too: once it raises s_tvalid, it holds the word until it is accepted.

`timescale 1ns/1ps
// Random back-pressure on both sides; checks order, TLAST, the AXI rule
// "valid and data stay put until accepted", and the transfer counter.
module axis_skid_tb;
    localparam N = 200;                       // words to send
    reg clk = 0, rst = 1;
    always #4 clk = ~clk;                     // 125 MHz

    // source (drives the slave side)
    reg         s_tvalid = 0;
    reg  [31:0] s_tdata  = 0;
    reg         s_tlast  = 0;
    wire        s_tready;
    // sink (drives tready on the master side)
    reg         m_tready = 0;
    wire        m_tvalid, m_tlast;
    wire [31:0] m_tdata, count;

    axis_skid #(.W(32)) dut (
        .clk(clk), .rst(rst),
        .s_tvalid(s_tvalid), .s_tready(s_tready), .s_tdata(s_tdata), .s_tlast(s_tlast),
        .m_tvalid(m_tvalid), .m_tready(m_tready), .m_tdata(m_tdata), .m_tlast(m_tlast),
        .count(count));

    // two 16-bit Galois LFSRs: reproducible "random" bits, identical in VHDL
    reg [15:0] lfsr_s = 16'hACE1, lfsr_m = 16'h1D2B;
    function [15:0] step(input [15:0] x);
        step = {1'b0, x[15:1]} ^ (x[0] ? 16'hB400 : 16'h0000);
    endfunction

    integer sent = 0, got = 0, errors = 0, cycles = 0;
    reg        was_stalled = 0;
    reg [31:0] held_data   = 0;

    always @(posedge clk) if (!rst) begin
        cycles <= cycles + 1;
        lfsr_s <= step(lfsr_s);
        lfsr_m <= step(lfsr_m);

        // ---- source: obey the rule "once valid, hold until accepted"
        if (s_tvalid && s_tready) sent = sent + 1;
        if (s_tvalid && !s_tready) begin
            // keep everything as it is
        end else if (sent < N && lfsr_s[1:0] != 2'b00) begin   // valid ~75 %
            s_tvalid <= 1;
            s_tdata  <= 32'hC0DE_0000 + sent;
            s_tlast  <= (sent % 8 == 7);
        end else
            s_tvalid <= 0;

        // ---- sink: random ready (~50 %), check every accepted word
        m_tready <= lfsr_m[0];
        if (was_stalled && (!m_tvalid || m_tdata !== held_data)) begin
            $display("FAIL: master changed valid/data while stalled at cycle %0d", cycles);
            errors = errors + 1;
        end
        was_stalled <= m_tvalid && !m_tready;
        held_data   <= m_tdata;
        if (m_tvalid && m_tready) begin
            if (m_tdata !== 32'hC0DE_0000 + got || m_tlast !== (got % 8 == 7)) begin
                $display("FAIL: word %0d = %h last=%b", got, m_tdata, m_tlast);
                errors = errors + 1;
            end
            got = got + 1;
        end
    end

    initial begin
        repeat (3) @(posedge clk);
        rst <= 0;
        wait (got == N);
        repeat (4) @(posedge clk);
        if (errors == 0 && count == N)
            $display("PASS: %0d words in order, count=%0d, %0d cycles", got, count, cycles);
        else
            $display("FAIL: errors=%0d count=%0d", errors, count);
        $finish;
    end
endmodule

-- Random back-pressure on both sides; checks order, TLAST, the AXI rule
-- "valid and data stay put until accepted", and the transfer counter.
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity axis_skid_tb is
end entity;

architecture sim of axis_skid_tb is
    constant N : natural := 200;                    -- words to send
    signal clk : std_logic := '0';
    signal rst : std_logic := '1';
    signal done : boolean := false;
    -- source (drives the slave side)
    signal s_tvalid : std_logic := '0';
    signal s_tdata  : std_logic_vector(31 downto 0) := (others => '0');
    signal s_tlast  : std_logic := '0';
    signal s_tready : std_logic;
    -- sink (drives tready on the master side)
    signal m_tready : std_logic := '0';
    signal m_tvalid, m_tlast : std_logic;
    signal m_tdata, count : std_logic_vector(31 downto 0);
    signal got, ncyc, nerr : natural := 0;

    -- 16-bit Galois LFSR step, identical to the Verilog testbench
    function step(x : unsigned(15 downto 0)) return unsigned is
    begin
        if x(0) = '1' then
            return shift_right(x, 1) xor x"B400";
        else
            return shift_right(x, 1);
        end if;
    end function;
begin
    clk <= not clk after 4 ns when not done;        -- 125 MHz

    dut : entity work.axis_skid
        generic map (W => 32)
        port map (clk => clk, rst => rst,
                  s_tvalid => s_tvalid, s_tready => s_tready, s_tdata => s_tdata, s_tlast => s_tlast,
                  m_tvalid => m_tvalid, m_tready => m_tready, m_tdata => m_tdata, m_tlast => m_tlast,
                  count => count);

    traffic : process (clk)
        variable lfsr_s : unsigned(15 downto 0) := x"ACE1";
        variable lfsr_m : unsigned(15 downto 0) := x"1D2B";
        variable sent, n_got, errors, cycles : natural := 0;
        variable was_stalled : boolean := false;
        variable held_data   : std_logic_vector(31 downto 0) := (others => '0');
        variable last_now    : std_logic;
    begin
        if rising_edge(clk) and rst = '0' then
            cycles := cycles + 1;
            -- ---- source: obey the rule "once valid, hold until accepted"
            if s_tvalid = '1' and s_tready = '1' then
                sent := sent + 1;
            end if;
            if s_tvalid = '1' and s_tready = '0' then
                null;                               -- keep everything as it is
            elsif sent < N and lfsr_s(1 downto 0) /= "00" then   -- valid ~75 %
                s_tvalid <= '1';
                s_tdata  <= std_logic_vector(x"C0DE0000" + to_unsigned(sent, 32));
                if sent mod 8 = 7 then s_tlast <= '1'; else s_tlast <= '0'; end if;
            else
                s_tvalid <= '0';
            end if;

            -- ---- sink: random ready (~50 %), check every accepted word
            m_tready <= lfsr_m(0);
            if was_stalled and (m_tvalid = '0' or m_tdata /= held_data) then
                report "FAIL: master changed valid/data while stalled at cycle "
                    & integer'image(cycles);
                errors := errors + 1;
            end if;
            was_stalled := m_tvalid = '1' and m_tready = '0';
            held_data   := m_tdata;
            if m_tvalid = '1' and m_tready = '1' then
                if n_got mod 8 = 7 then last_now := '1'; else last_now := '0'; end if;
                if unsigned(m_tdata) /= x"C0DE0000" + to_unsigned(n_got, 32) or m_tlast /= last_now then
                    report "FAIL: word " & integer'image(n_got);
                    errors := errors + 1;
                end if;
                n_got := n_got + 1;
            end if;
            got   <= n_got;
            ncyc  <= cycles;
            nerr  <= errors;
            lfsr_s := step(lfsr_s);
            lfsr_m := step(lfsr_m);
        end if;
    end process;

    stimulus : process
    begin
        for i in 1 to 3 loop
            wait until rising_edge(clk);
        end loop;
        rst <= '0';
        wait until got = N;
        for i in 1 to 4 loop
            wait until rising_edge(clk);
        end loop;
        if nerr = 0 and unsigned(count) = N then
            report "PASS: " & integer'image(got) & " words in order, count="
                & integer'image(to_integer(unsigned(count))) & ", "
                & integer'image(ncyc) & " cycles";
        else
            report "FAIL: errors=" & integer'image(nerr) & " count="
                & integer'image(to_integer(unsigned(count))) severity error;
        end if;
        done <= true;
        wait;
    end process;
end architecture;

iverilog -g2012 -o tb axis_skid.v axis_skid_tb.v && vvp tb
# PASS: 200 words in order, count=200, 402 cycles

ghdl -a --std=08 axis_skid.vhd axis_skid_tb.vhd
ghdl -e --std=08 axis_skid_tb && ghdl -r --std=08 axis_skid_tb
# PASS: 200 words in order, count=200, 402 cycles

200 words took 402 cycles: about one word every two cycles, which is what you expect when the sink is ready half the time. The slice itself did not slow anything down — the next section shows that in general.

This model runs a stream link for 20 000 cycles with a source that always has data and a sink that is ready with probability \(p\). It compares a direct wire, our skid buffer (same update rules as the HDL), and a naive one-slot slice whose s_tready simply means “my register is empty”. The skid buffer matches the wire: throughput \(\approx p\). The naive slice never exceeds half a word per cycle, because it cannot accept a new word in the same cycle it hands one on (Problem 5).