Hard Processor System Technical Reference Manual: Agilex™ 5 SoCs

ID 814346
Date 4/01/2024
Public
Document Table of Contents

5.1.6.3.3. Transmit Descriptor

The DMA in EMAC requires at least one descriptor for a transmit packet. In addition to two buffer length fields, and two address pointers, the transmit descriptor has control fields which can be used to control the packet processing on per-transmit packet basis. The transmit normal descriptor has the following two formats: read format and write-back format

Transmit Normal Descriptor (Read Format)

The following figure shows the read format for a transmit normal descriptor. This is the format in which the software can prepare the descriptor contents and hand it over to the DMA engines of the EMAC.
Figure 58. Transmit Descriptor Read Format
The following tables describe the TDES0-3 fields for the transmit normal descriptor (read format).
Table 120.  TDES0 Normal Descriptor (Read Format)
Bit Name Description
31:0 BUF1AP

Buffer 1 address pointer or TSO header address pointer.

These bits indicate the physical address of Buffer 1. These bits indicate the TSO header address pointer when the following bits are set:
  • TSE bit of TDES3
  • FD bit of TDES3
Table 121.  TDES1 Normal Descriptor (Read Format)
Bit Name Description
31:0 BUF2AP

Buffer 2 or buffer 1 address pointer.

This bit indicates the physical address of buffer 2 when a descriptor ring structure is used.

There is no limitation for the buffer address alignment.

In 40- or 48-bit addressing mode, these bits indicate the most significant 8- or 16-bits of the buffer 1 address pointer.

Table 122.  TDES2 Normal Descriptor (Read Format)
Bit Name Description
31 IOC

Interrupt on completion.

This bit sets the TI bit in the DMA_CH(#i)_Status register after the present packet has been transmitted.

30

TTSE/

TMWD

Transmit timestamp enable or external TSO memory write disable.

This bit enables the IEEE1588 time stamping for transmit packet referenced by the descriptor, if TSE bit not set.

If TSE bit is set and external TSO memory is enabled, setting this bit disables external TSO memory writing for this packet.

29:16 B2L

Buffer 2 length.

The driver sets this field. When set, this field indicates buffer 2 length.

15:14 VTIR

VLAN tag insertion or replacement.

These bits request the MAC to perform VLAN tagging or untagging before transmitting the packets. If the packet is modified for VLAN tags, the MAC automatically recalculates and replaces the CRC bytes. The following list describes the values of these bits:

  • 2'b00: Do not add a VLAN tag.
  • 2'b01: Remove the VLAN tag from the packets before transmission. This option must be used only with the VLAN packets.
  • 2'b10: Insert a VLAN tag with the tag value programmed in the MAC_VLAN_Incl register or context descriptor.
  • 2'b11: Replace the VLAN tag in packets with the tag value programmed in the MAC_VLAN_Incl register or context descriptor. This option must be used only with the VLAN packets.

These bits are valid when the enable SA and VLAN insertion on TX option is selected while configuring the EMAC controller.

13:0 HL or B1L

Header length or buffer 1 length.

For header length, only bits [9:0] are taken. The size [13:0] is applicable only when interpreting buffer 1 length. If the TCP segmentation offload feature is enabled through the TSE bit of TDES3, this field is equal to the header length. When the TSE bit is set in TDES3, the header length includes the length in bytes from Ethernet source address till the end of the TCP header. The minimum value of header length is 0x30 (48 bytes) when SA insertion is enabled, or 0x36 (54 bytes), otherwise. If the value is less than this, TCP segmentation is not performed on the packet. The maximum header length supported for TSO feature is 1023 bytes.

If SA insertion is performed on this packet, the header length must be no less than 48 bytes, otherwise, it must be no less than 54 bytes.

If the TCP segmentation offload feature is not enabled, this field is equal to buffer 1 length.

Table 123.  TDES3 Normal Descriptor (Read Format)
Bit Name Description
31 OWN

Own bit.

When this bit is set, it indicates that the DMA owns the descriptor. When this bit is reset, it indicates that the application owns the descriptor. The DMA clears this bit after it completes the transfer of data given in the associated buffers.

30 CTXT

Context type.

This bit must be set to 1'b0 for normal descriptor.

29 FD

First descriptor.

When this bit is set, it indicates that the buffer contains the first segment of a packet.

28 LD

Last descriptor.

When this bit is set, it indicates that the buffer contains the last segment of the packet.

When this bit is set, the B1L or B2L field must have a non-zero value.

27:26 CPC

CRC pad control.

This field controls the CRC and pad insertion for TX packets. This field is valid only when the first descriptor bit (TDES3[29]) is set. The following list describes the values of bits[27:26]:

  • 2'b00: CRC and Pad Insertion

    The MAC appends the cyclic redundancy check (CRC) at the end of the transmitted packet of length greater than or equal to 60 bytes. The MAC automatically adds padding and CRC to a frame shorter than 60 bytes.

  • 2'b01: CRC insertion (disable pad insertion)

    The MAC appends the CRC at the end of the transmitted packet but it does not append padding. The application must ensure that the padding bytes are present in the packet being transferred from the Transmit buffer, that is, the packet being transferred from the Transmit buffer is of length greater than or equal to 60 bytes.

  • 2'b10: Disable CRC insertion

    The MAC does not append the CRC at the end of the transmitted packet. The application must ensure that the padding and CRC bytes are present in the packet being transferred from the Transmit buffer.

  • 2'b11: CRC replacement

    The MAC replaces the last four bytes of the transmitted packet with recalculated CRC bytes. The application must ensure that the padding and CRC bytes are present in the packet being transferred from the Transmit buffer.

Note: When the TSE bit is set, the MAC ignores this field because the CRC and pad insertion is always done for segmentation.
25:23 SAIC/

VNP

SA insertion control/Virtualized tunnel packet control.

These bits request the MAC to add or replace the source address field in the Ethernet packet with the value given in the MAC address 0 register. If the source address field is modified in a packet, the MAC automatically recalculates and replaces the CRC bytes.

Bit 25 specifies the MAC address register (1 or 0) value that is used for source address insertion or replacement.

The following list describes the values of Bits[24:23]:

  • 2'b00: Do not include the source address
  • 2'b01: Include or insert the source address. For reliable transmission, the application must provide frames without source addresses.
  • 2'b10: Replace the source address. For reliable transmission, the application must provide frames with source addresses.
  • 2'b11: Reserved

These bits are valid in the EMAC configurations when the enable SA and VLAN insertion on TX option is selected while configuring the EMAC controller and when the first segment control bit (TDES3 [29]) is set.

Virtualized tunnel packet (VNP):

When these bits are set to 3’b011, the current packet is treated as tunneled packet by the TSO and TxCOE functions in the transmit path. VNP is applicable only when Enable support for VxLAN/NVGRE packets is selected while configuring the EMAC controller and when bit FD is set.
Note: SA insertion control feature is not supported for tunneled packets.
22:19

SLOTNUM or

THL

SLOTNUM: Slot number control bits in AV mode.

These bits indicate the slot interval in which the data must be fetched from the corresponding buffers addressed by TDES0 or TDES1.

When the transmit descriptor is fetched, the DMA compares the slot number value in this field with the slot interval maintained in the RSN field of DMA_CH(#i)_Slot_Function_Control_Status. It fetches the data from the buffers only if a value matches. These bits are valid only for the AV channels.

TCP header length:

If the TSE bit is set, this field contains the length of the TCP header (in terms of 32-bit words). The minimum value of this field must be 5.

18 TSE

TCP segmentation enable.

When this bit is set, the DMA performs the TCP segmentation for a packet. This bit is valid only if the FD bit and TSE bit in the corresponding DMA_CH(#i)_Tx_Control are set. Otherwise, this bit is ignored and considered as 0.

17:16 CIC/TPL

Checksum insertion control or TCP payload length.

These bits control the checksum calculation and insertion. The following list describes the bit encoding:

  • 2'b00: Checksum insertion disabled.
  • 2'b01: Only IP header checksum calculation and insertion are enabled (both outer and inner headers in case of tunneled packet).
  • 2'b10: IP header checksum and payload checksum calculation and insertion are enabled, but pseudo-header checksum is not calculated in hardware (both outer and inner headers in case of tunneled packet).
  • 2'b11: IP header checksum and payload checksum calculation and insertion are enabled, and pseudo-header checksum is calculated in hardware (both outer and inner headers in case of tunneled packet).

This field is valid when the enable Transmit TCP/IP checksum offload option is selected and the TSE bit is reset.

When the TSE bit is set, this field contains the upper bits [17:16] of the TCP payload length. This allows the TCP packet length field to span across TDES3[17:0] to provide 256 KB packet length support.

When timestamping is enabled without one step timestamping feature and OSTC bit is set in the context descriptor, the content of this field is not effective and checksum is updated as though CIC field is set to 2'b11.
Note: In case of tunneled packets (as indicated by SAIC/VNP = 3'b011 and the VxLAN mode is enabled in the MAC transmit configuration register), the outer Header UDP checksum is always 0 as per the VxLAN standard compliance.
15 TPL

TCP payload length.

When the TSE bit is reset, this bit is reserved. When the TSE bit is set, this is bit 15 of the TCP payload length [17:0].

This field is valid only when the enable TCP segmentation offloading for TCP/IP packets option is selected while configuring the XGMAC controller.

14:0 FL/TPL

Packet length or TCP payload length.

This field is equal to the length of the packet to be transmitted in bytes. When the TSE bit is not set, this field is equal to the total length of the packet to be transmitted: Ethernet Header Length + TCP /IP Header Length – Preamble Length – SFD Length + Ethernet Payload Length.

When the TSE bit is set, this field is equal to the lower 15 bits of the TCP payload length. This length does not include Ethernet header or TCP/IP header length.

Transmit Normal Descriptor (Write-Back Format)

The EMAC processes the descriptor, acts on it and then writes back the status content. This operation indicates to the software that the descriptor is free and no longer required by the hardware. The EMAC writes only bits[31:24] of TDES3 during this operation and all the other fields of the descriptor in the host memory are not modified.

Figure 59. Transmit Descriptor Write-Back Format
Table 124.  TDES3 Normal Descriptor (Write-Back Format)
Bit Name Description
31 OWN

Own bit.

When this bit is set, it indicates that the EMAC DMA owns the descriptor. The DMA clears this bit when it writes back the descriptor. The DMA closes the descriptor when either of the following conditions are true:
  • The DMA completes the transfer of data indicated by the buffers from the host memory to the corresponding TX queue.
  • The B1L and B2L values are zero, indicating empty buffers.
30 CTXT

Context type.

This bit is set to 1'b0 for normal descriptor.

29 FD

First descriptor.

This bit indicates that the buffer contains the first segment of a packet.

28 LD

Last descriptor.

This bit is set 1'b1 for last descriptor of a packet. The DMA writes the status fields only in the last descriptor of the packet.

27 DERR

Descriptor error.

When this bit is set, it indicates that the descriptor content is incorrect.

The DMA sets this bit during write-back while closing the descriptor. The descriptor errors can be:
  • AXI bus error: This bit is asserted when AXI bus error response is received while processing the descriptor. This can be either when the descriptor is being fetched or when the packet data indicated by its buffer pointers are fetched.
    • When a transmit descriptor read from descriptor memory has FD, LD and CD bits set to 1, the transmit DMA terminates the ongoing DMA transfer (forcing a CRC error when partial packet is transmitted on the line) and enters stop state.
    • The DDE and TPS bits of corresponding DMA_CH(#i)_Status register is set to 1. Recovery Mechanism: Perform a software reset by programming the SWR field of the DMA_Mode register to 1.
  • All 1s
26:0 RSVD Reserved

Transmit Context Descriptor

The Transmit context descriptor can be provided any time before a packet descriptor. The context is valid for the current packet and subsequent packets. The context descriptor is used to provide the timestamps for one-step timestamp correction, VLAN tag ID for VLAN insertion feature, and SA insertion bit for SA insertion. Write back is done on a context descriptor only to reset the OWN bit and to set the CDE bit if necessary.
Note: The VLAN tag IDs and MSS values, provided by the application in a context descriptor with their corresponding valid bits set, are stored internally by the DMA. When the outer or inner VLAN tag is provided with the Valid bit set, the DMA always passes the last valid VLAN tag to the MTL. The application cannot invalidate the valid VLAN tag stored by the DMA. The VLAN tag is inserted or replaced based on the control inputs provided for the packet.
The inner VLAN tag control input is used only for the next packet that immediately follows the context descriptor. The application must provide a context descriptor before the normal descriptor of each packet for which the DMA must use the inner VLAN tag control input.
Figure 60. Transmit Context Descriptor
Table 125.  TDES0 Context Descriptor
Bit Name Description
31:0 TTSL

Transmit packet timestamp low or packet ID.

For one-step correction, the driver can provide the lower 32 bits of timestamp in this descriptor word. The DMA uses this value as the low word for doing one-step timestamp correction. This field is valid only if the OSTC and TCMSSV bits of TDES3 context descriptor are set.

When the OSTC bit is reset and PIDV is set, the lower 10-bits [9:0] indicate the packet ID which is used for 2-step time stamping.

Table 126.  TDES1 Context Descriptor
Bit Name Description
31:0 TTSH

Transmit packet timestamp high.

For one-step correction, the driver can provide the upper 32 bits of timestamp in this descriptor.

The DMA uses this value as the high word for doing one-step timestamp correction. This field is valid only if the OSTC and TCMSSV bits of TDES3 context descriptor are set.

Table 127.  TDES2 Context Descriptor
Bit Name Description
31:16 IVT

Inner VLAN tag.

When the IVLTV bit of TDES3 context descriptor is set and the TCMSSV and OSTC bits of TDES3 context descriptor are reset, TDES2[31:16] contains the inner VLAN tag to be inserted in the subsequent transmit packets.

15:14 RSVD Reserved
13:0 MSS

Maximum segment size.

When the enable TCP segmentation offloading for TCP/IP Packets option is selected, the driver can provide maximum segment size in this field. This segment size is used while segmenting the TCP/IP payload. This field is valid only if the TCMSSV bit of TDES3 context descriptor is set and the OSTC bit of the TDES3 context descriptor is reset.

Table 128.  TDES3 Context Descriptor (Read Format)
Bit Name Description
31 OWN

Own bit.

When this bit is set, it indicates that the EMAC DMA owns the descriptor. When this bit is reset, it indicates that the application owns the descriptor. The DMA clears this bit after it accepts the context descriptor contents.

30 CTXT

Context type.

This bit is set to 1’b1 for context descriptor.

29:28 RSVD Reserved
27 OSTC

One-Step timestamp correction enable.

When this bit is set, the DMA performs a one-step timestamp correction with reference to the timestamp values provided in TDES0 and TDES1.

26 TCMSSV

One-Step timestamp correction input or MSS valid.

When this bit and the OSTC bit are set, it indicates that the timestamp correction input provided in TDES0 and TDES1 is valid.

When the OSTC bit is reset and this bit and the TSE bit of TDES3 are set in subsequent normal descriptor, it indicates that the MSS input in TDES2 is valid.

25 PIDV

Packet ID valid.

When this bit is set and OSTC bit is reset, the bits [9:0] of TDES0 context descriptor indicate the packet ID for 2-step time stamping.

24 RSVD Reserved
23:20 RSVD Reserved
19:18 IVTIR

Inner VLAN tag insert or replace.

When this bit is set, these bits request the MAC to perform inner VLAN tagging or untagging before transmitting the packets. If the packet is modified for VLAN tags, the MAC automatically recalculates and replaces the CRC bytes.

The following list describes the values of these bits:
  • 2'b00: Do not add the inner VLAN tag.
  • 2'b01: Remove the inner VLAN tag from the packets before transmission. This option must be used only with the VLAN frames.
  • 2'b10: Insert an inner VLAN tag with the tag value programmed in the register or context descriptor.
  • 2'b11: Replace the inner VLAN tag in packets with the tag value programmed in the register or context descriptor. This option must be used only with the VLAN frames.

These bits are valid when the enable SA and VLAN Insertion on TX and enable double VLAN processing options are selected.

17 IVLTV

Inner VLAN tag valid.

When this bit is set, it indicates that the IVT field of TDES2 is valid.

16 VLTV

VLAN tag valid.

When this bit is set, it indicates that the VT field of TDES3 is valid.

15:0 VT

VLAN tag.

This field contains the VLAN tag to be inserted or replaced in the packet. This field is used as VLAN tag only when the VLTI bit of the MAC_VLAN_Incl register is set.

Table 129.  TDES3 Context Descriptor (Write-Back Format)
Bit Name Description
31 OWN

Own bit

When this bit is set, it indicates that the EMAC DMA owns the descriptor. When this bit is reset by the DMA, it indicates that the application owns the descriptor. The DMA clears this bit after it accepts the context descriptor contents.

30 CTXT

Context type

This bit is set to 1’b1 for context descriptor.

29 CDE

Context descriptor error

When this bit is set, it indicates that the context descriptor was provided in the incorrect sequence and the DMA ignored it. The DMA sets this bit during write-back while closing the context descriptor. When the context descriptor is read by DMA, this bit is reserved and must have a value 1‘b0.

28:0 RSVD Reserved