axiethernet
Vitis Drivers API Documentation
Functions
xaxiethernet_example_intr_sgdma.c File Reference

Overview

Implements examples that utilize the Axi Ethernet's interrupt driven SGDMA packet transfer mode to send and receive frames.

These examples demonstrate:

  • How to perform simple send and receive
  • Interrupt coalescing
  • Checksum offload
  • Error handling
  • Device reset

Functional guide to example:

  • AxiEthernetSgDmaIntrSingleFrameExample demonstrates the simplest way to send and receive frames in in interrupt driven SGDMA mode.
  • AxiEthernetSgDmaIntrCoalescingExample demonstrates how to use interrupt coalescing to increase throughput.
  • AxiEthernetSgDmaPartialChecksumOffloadExample demonstrates the partial checksum offloading. The HW must be setup for partial checksum offloading for this example to execute.
  • AxiEthernetSgDmaFullChecksumOffloadExample demonstrates the full checksum offloading. The HW must be setup for full checksum offloading for this example to execute.
  • AxiEthernetAxiEthernetErrorHandler() demonstrates how to manage asynchronous errors.
  • AxiEthernetResetDevice() demonstrates how to reset the driver/HW without losing all configuration settings.
MODIFICATION HISTORY:
Ver   Who  Date     Changes






1.00a asa  4/30/10  First release based on the ll temac driver
1.01a asa  12/10/10 Added full checksum offload example.
                                  Changes made to enable the AXIDMA Tx/Rx ring interrupts
                          before allocation of Tx/Rx BDs for all examples.
3.00a asa  6/25/12  Modified XAxiDma_BdSetLength API call to support new
                          AXI DMA driver version 7.00a. Removed the calls to
                          XAxiDma_BdRingStart for the coalesce and checksum
                          offload examples. They are not required with the new
                          AxiDMA version.
3.00a bss  10/22/12 Added support for Fast Interrupt Handlers.
3.01a srt  02/14/13 Added support for Zynq (CR 681136).
5.4   ms   01/23/17 Modified xil_printf statement in main function to
                    ensure that "Successfully ran" and "Failed" strings are
                    available in all examples. This is a fix for CR-965028.
      ms   04/05/17 Added tabspace for return statements in functions
                    for proper documentation while generating doxygen.
5.8   rsp  07/23/18 Fix gcc '[-Wint-conversion]' warning.
      rsp  10/22/18 Set RX BD length to jumbo frame size. It fixes 'Error
                    committing RxBD to HW' error for designs having length
                    register width < 19 bits.

Functions

int AxiEthernetSgDmaIntrExample (INTC *IntcInstancePtr, XAxiEthernet *AxiEthernetInstancePtr, XAxiDma *DmaInstancePtr, u16 AxiEthernetDeviceId, u16 AxiDmaDeviceId, u16 AxiEthernetIntrId, u16 DmaRxIntrId, u16 DmaTxIntrId)
 This function demonstrates the usage usage of the Axi Ethernet by sending and receiving frames in interrupt driven SGDMA mode. More...
 
int AxiEthernetSgDmaIntrSingleFrameExample (XAxiEthernet *AxiEthernetInstancePtr, XAxiDma *DmaInstancePtr)
 This function demonstrates the usage of the Axi Ethernet by sending and receiving a single frame in SGDMA interrupt mode. More...
 
int AxiEthernetSgDmaIntrCoalescingExample (XAxiEthernet *AxiEthernetInstancePtr, XAxiDma *DmaInstancePtr)
 This example sends frames with the interrupt coalescing settings altered from their defaults. More...
 
int AxiEthernetSgDmaPartialChecksumOffloadExample (XAxiEthernet *AxiEthernetInstancePtr, XAxiDma *DmaInstancePtr)
 This example sends and receives a single packet in loopback mode with checksum offloading support. More...
 
int AxiEthernetSgDmaFullChecksumOffloadExample (XAxiEthernet *AxiEthernetInstancePtr, XAxiDma *DmaInstancePtr)
 This example sends and receives a single packet in loopback mode with full checksum offloading support. More...
 
int main (void)
 This is the main function for the Axi Ethernet example. More...
 

Function Documentation

int AxiEthernetSgDmaFullChecksumOffloadExample ( XAxiEthernet *  AxiEthernetInstancePtr,
XAxiDma *  DmaInstancePtr 
)

This example sends and receives a single packet in loopback mode with full checksum offloading support.

An Ethernet frame is formed with IP header, TCP header and payload. The hardware calculates the IP Header checksum and populates it at the appropriate location in the IP header. Similarly, the hardware calculates the TCP Pseudo header from IP header and calculates TCP checksum for TCP Pseudo header, TCP header and TCP payload. It then populates the checksum in the TCP header. The Ethernet frame is then looped back and received. The hardware validates the IP header checksum and the TCP checksum. The example retrieves the checksum validation information from the AXI4- Stream Appword2.

Parameters
AxiEthernetInstancePtris a pointer to the instance of the AxiEthernet component.
DmaInstancePtris a pointer to the instance of the Dma component.
Returns
-XST_SUCCESS to indicate success -XST_FAILURE to indicate failure
Note
None.

References AxiEthernetUtilErrorTrap(), AxiEthernetUtilFrameHdrFormatMAC(), AxiEthernetUtilFrameHdrFormatType(), AxiEthernetUtilFrameSetPayloadData(), XAE_INT_RECV_ERROR_MASK, XAE_RECEIVER_ENABLE_OPTION, XAE_TRANSMITTER_ENABLE_OPTION, XAxiEthernet_IntEnable, XAxiEthernet_SetOptions(), XAxiEthernet_Start(), and XAxiEthernet_Stop().

int AxiEthernetSgDmaIntrCoalescingExample ( XAxiEthernet *  AxiEthernetInstancePtr,
XAxiDma *  DmaInstancePtr 
)

This example sends frames with the interrupt coalescing settings altered from their defaults.

The default settings will interrupt the processor after every frame has been sent. This example will increase the threshold resulting in lower CPU utilization since it spends less time servicing interrupts.

Parameters
AxiEthernetInstancePtris a pointer to the instance of the Axi Ethernet component.
DmaInstancePtris a pointer to the instance of the Dma component.
Returns
-XST_SUCCESS to indicate success -XST_FAILURE to indicate failure
Note
None.

References AxiEthernetUtilErrorTrap(), AxiEthernetUtilFrameHdrFormatMAC(), AxiEthernetUtilFrameHdrFormatType(), AxiEthernetUtilFrameSetPayloadData(), XAE_RECEIVER_ENABLE_OPTION, XAE_TRANSMITTER_ENABLE_OPTION, XAxiEthernet_ClearOptions(), XAxiEthernet_SetOptions(), XAxiEthernet_Start(), and XAxiEthernet_Stop().

Referenced by AxiEthernetSgDmaIntrExample().

int AxiEthernetSgDmaIntrExample ( INTC *  IntcInstancePtr,
XAxiEthernet *  AxiEthernetInstancePtr,
XAxiDma *  DmaInstancePtr,
u16  AxiEthernetDeviceId,
u16  AxiDmaDeviceId,
u16  AxiEthernetIntrId,
u16  DmaRxIntrId,
u16  DmaTxIntrId 
)

This function demonstrates the usage usage of the Axi Ethernet by sending and receiving frames in interrupt driven SGDMA mode.

Parameters
IntcInstancePtris a pointer to the instance of the Intc component.
AxiEthernetInstancePtris a pointer to the instance of the AxiEthernet component.
DmaInstancePtris a pointer to the instance of the AXIDMA component.
AxiEthernetDeviceIdis Device ID of the Axi Ethernet Device , typically XPAR_<AXIETHERNET_instance>_DEVICE_ID value from xparameters.h.
AxiDmaDeviceIdis Device ID of the Axi DMAA Device , typically XPAR_<AXIDMA_instance>_DEVICE_ID value from xparameters.h.
AxiEthernetIntrIdis the Interrupt ID and is typically XPAR_<INTC_instance>_<AXIETHERNET_instance>_VEC_ID value from xparameters.h.
DmaRxIntrIdis the interrupt id for DMA Rx and is typically taken from XPAR_<AXIETHERNET_instance>_CONNECTED_DMARX_INTR
DmaTxIntrIdis the interrupt id for DMA Tx and is typically taken from XPAR_<AXIETHERNET_instance>_CONNECTED_DMATX_INTR
Returns
-XST_SUCCESS to indicate success -XST_FAILURE to indicate failure
Note
AxiDma hardware must be initialized before initializing AxiEthernet. Since AxiDma reset line is connected to the AxiEthernet reset line, a reset of AxiDma hardware during its initialization would reset AxiEthernet.

References XAxiEthernet_Config::AxiDevBaseAddress, XAxiEthernet_Config::AxiDevType, AxiEthernetSgDmaFullChecksumOffloadExample(), AxiEthernetSgDmaIntrCoalescingExample(), AxiEthernetSgDmaIntrSingleFrameExample(), AxiEthernetSgDmaPartialChecksumOffloadExample(), AxiEthernetUtilEnterLoopback(), AxiEthernetUtilErrorTrap(), AxiEthernetUtilPhyDelay(), XAxiEthernet_Config::BaseAddress, XAxiEthernet::Config, XAxiEthernet_CfgInitialize(), XAxiEthernet_GetPhysicalInterface, XAxiEthernet_IsRxFullCsum, XAxiEthernet_IsRxPartialCsum, XAxiEthernet_IsRxVlanStrp, XAxiEthernet_IsRxVlanTag, XAxiEthernet_IsRxVlanTran, XAxiEthernet_IsTxFullCsum, XAxiEthernet_IsTxPartialCsum, XAxiEthernet_IsTxVlanStrp, XAxiEthernet_IsTxVlanTag, XAxiEthernet_IsTxVlanTran, XAxiEthernet_LookupConfig(), XAxiEthernet_SetMacAddress(), XAxiEthernet_SetOperatingSpeed(), and XAxiEthernet_Stop().

int AxiEthernetSgDmaIntrSingleFrameExample ( XAxiEthernet *  AxiEthernetInstancePtr,
XAxiDma *  DmaInstancePtr 
)

This function demonstrates the usage of the Axi Ethernet by sending and receiving a single frame in SGDMA interrupt mode.

The source packet will be described by two descriptors. It will be received into a buffer described by a single descriptor.

Parameters
AxiEthernetInstancePtris a pointer to the instance of the Axi Ethernet component.
DmaInstancePtris a pointer to the instance of the Dma component.
Returns
-XST_SUCCESS to indicate success -XST_FAILURE to indicate failure
Note
None.

References AxiEthernetUtilErrorTrap(), AxiEthernetUtilFrameHdrFormatMAC(), AxiEthernetUtilFrameHdrFormatType(), AxiEthernetUtilFrameMemClear(), AxiEthernetUtilFrameSetPayloadData(), AxiEthernetUtilFrameVerify(), XAE_INT_RECV_ERROR_MASK, XAE_RECEIVER_ENABLE_OPTION, XAE_TRANSMITTER_ENABLE_OPTION, XAxiEthernet_IntEnable, XAxiEthernet_SetOptions(), XAxiEthernet_Start(), and XAxiEthernet_Stop().

int AxiEthernetSgDmaPartialChecksumOffloadExample ( XAxiEthernet *  AxiEthernetInstancePtr,
XAxiDma *  DmaInstancePtr 
)

This example sends and receives a single packet in loopback mode with checksum offloading support.

The transmit frame will be checksummed over the entire Ethernet payload and inserted into the last 2 bytes of the frame.

On receive, HW should calculate the Ethernet payload checksum and return a value of 0xFFFF which means the payload data was likely not corrupted.

Parameters
AxiEthernetInstancePtris a pointer to the instance of the AxiEthernet component.
DmaInstancePtris a pointer to the instance of the Dma component.
Returns
-XST_SUCCESS to indicate success -XST_FAILURE to indicate failure
Note
None.

References AxiEthernetUtilErrorTrap(), AxiEthernetUtilFrameHdrFormatMAC(), AxiEthernetUtilFrameHdrFormatType(), AxiEthernetUtilFrameMemClear(), AxiEthernetUtilFrameSetPayloadData(), XAE_INT_RECV_ERROR_MASK, XAE_RECEIVER_ENABLE_OPTION, XAE_TRANSMITTER_ENABLE_OPTION, XAxiEthernet_IntEnable, XAxiEthernet_IsRxPartialCsum, XAxiEthernet_IsTxPartialCsum, XAxiEthernet_SetOptions(), XAxiEthernet_Start(), and XAxiEthernet_Stop().

int main ( void  )

This is the main function for the Axi Ethernet example.

This function is not included if the example is generated from the TestAppGen test tool.

Parameters
None.
Returns
  • XST_SUCCESS to indicate success.
  • XST_FAILURE to indicate failure
Note
None.

References AXIETHERNET_DEVICE_ID, AxiEthernetSgDmaIntrExample(), and AxiEthernetUtilErrorTrap().