AXI4-Stream: TVALID, TREADY, TDATA, TLAST and TKEEP

Not all data has an address. Video pixels, network packets, audio samples and DSP data simply flow from one block to the next. AXI4-Stream is the AMBA protocol for that: a single channel from a transmitter to a receiver, with the same VALID/READY handshake as AXI, data, byte qualifiers, and a TLAST signal to mark the end of a packet. This article explains the AXI4-Stream signals and builds a block that consumes one stream and produces another.

8 min read | Intermediate

What You'll Learn

• Name the AXI4-Stream signals and what each one is for
• Use TLAST to mark packet boundaries
• Use TKEEP for packets that are not a whole number of words
• Build a stream block that applies and respects backpressure

One Channel, No Addresses

Only TVALID is strictly required; most interfaces use TVALID, TREADY, TDATA and TLAST, and add TKEEP when packets can end in the middle of a word. A transfer happens at every rising edge where TVALID and TREADY are both high, with the same rules as AXI: the transmitter must not wait for TREADY before raising TVALID, and once TVALID is high the transfer must stay unchanged until it is accepted.

Packets and TLAST

A stream is a sequence of transfers. TLAST groups them into packets: the transfer with TLAST high ends one packet, and the next transfer starts a new one. A 14-byte packet on a 32-bit stream takes four transfers: three full words and a fourth with only two bytes kept, marked with TKEEP = 0011.

A Packet Byte Counter

This block reads packets from its input stream and, at the end of each one, sends the packet's length in bytes on its output stream. It counts only the bytes whose TKEEP bit is set:

module axis_pkt_count (
  input             aclk,
  input             aresetn,
  input      [31:0] s_tdata,
  input      [3:0]  s_tkeep,
  input             s_tlast,
  input             s_tvalid,
  output            s_tready,
  output reg [15:0] m_tdata,
  output reg        m_tvalid,
  input             m_tready
);
  reg [15:0] bytes;

  wire [2:0] kept = s_tkeep[0] + s_tkeep[1] + s_tkeep[2] + s_tkeep[3];

  // Stall the input while a count is waiting to be taken on the output
  assign s_tready = !m_tvalid || m_tready;

  always @(posedge aclk) begin
    if (!aresetn) begin
      bytes    <= 16'd0;
      m_tvalid <= 1'b0;
    end
    else begin
      if (m_tvalid && m_tready)
        m_tvalid <= 1'b0;
      if (s_tvalid && s_tready) begin
        if (s_tlast) begin
          m_tdata  <= bytes + kept;
          m_tvalid <= 1'b1;
          bytes    <= 16'd0;
        end
        else begin
          bytes <= bytes + kept;
        end
      end
    end
  end
endmodule

The s_ ports are the receiver side and the m_ ports the transmitter side, a naming convention used by most stream IP. The interesting line is s_tready: the block accepts input only when it can also deliver its output. If a count is waiting and the next block is not ready, the counter stops taking input. That is backpressure: a slow block at the end of a chain slows down everything before it, and no data is lost.

The Simulation

The testbench sends three packets: 14 bytes in four transfers, a single byte, and two full words with a gap between them. The receiver of the counts is busy for four cycles in the middle:

35  in   data=0x03020100 keep=1111
45  in   data=0x07060504 keep=1111
55  in   data=0x0b0a0908 keep=1111
65  in   data=0x00000d0c keep=0011 last
75  in   data=0x000000ee keep=0001 last
75  out  packet length = 14 bytes
125  in   data=0x13121110 keep=1111
125  out  packet length = 1 bytes
155  in   data=0x17161514 keep=1111 last
165  out  packet length = 8 bytes

The count of packet 2 is ready at 85 ns, but the receiver is busy until 120 ns. During that time s_tready is low and the first word of packet 3 waits on the input with TVALID high. As soon as the count is taken, the waiting word is accepted in the same cycle.

Where AXI4-Stream Is Used

• Video: one pixel or a few pixels per transfer, TUSER marking the start of a frame and TLAST the end of each line.
• Networking: one packet per TLAST, TKEEP for the last partial word.
• DMA: a DMA engine reads memory over AXI4 and pushes the data out as a stream, or the reverse.
• DSP chains: filters and FFT blocks that each take a stream and produce one.

Running It in ChipVerify Lab

The example contains the byte counter and the packet testbench. Change the TKEEP values and the packet lengths, and check the counts.

Common Mistakes

beat(32'h33221100, 4'b1111, 0);
beat(32'h00550044, 4'b0101, 0);
beat(32'h99887766, 4'b1111, 1);

75  in   data=0x33221100 keep=1111
85  in   data=0x00550044 keep=0101
95  in   data=0x99887766 keep=1111 last
125  out  packet length = 10 bytes