| emacps Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List
- Examples

Functions
xemacps_example_intr_dma.c File Reference

## Overview

Implements examples that utilize the EmacPs's interrupt driven DMA packet transfer mode to send and receive frames.

These examples demonstrate:

- How to perform simple send and receive.
- Interrupt
- Error handling
- Device reset

Functional guide to example:

- EmacPsDmaSingleFrameIntrExample demonstrates the simplest way to send and receive frames in in interrupt driven DMA mode.
- EmacPsErrorHandler() demonstrates how to manage asynchronous errors.
- EmacPsResetDevice() demonstrates how to reset the driver/HW without losing all configuration settings.

    MODIFICATION HISTORY:

    Ver   Who  Date     Changes

    1.00a wsy  01/10/10 First release
    1.00a asa  11/25/11 The cache disable routines are removed. So now both
                  I-cache and D-cache are enabled. The array RxBuffer is
                  removed to avoid an extra copy from RxBuffer to RxFrame.
                  Now the address of RxFrame is submitted to the Rx BD
                  instead of the address of RxBuffer.
                  In function EmacPsDmaSingleFrameIntrExample, BdRxPtr
                  is made as a pointer instead of array of pointers. This
                  is done since on the Rx path we now submit a single BD
                  instead of all 32 BDs. Because of this change, relevant
                  changes are made throughout the function
                  EmacPsDmaSingleFrameIntrExample.
                  Cache invalidation is now being done for the RxFrame
                  buffer.
                  The unnecessary cache flush (Xil_DCacheFlushRange) is
                  removed. This was being done towards the end of the
                  example which was unnecessary.
    1.00a asa 01/24/12  Support for Zynq board is added. The SLCR divisors are
                          different for Zynq. Changes are made for the same.
                          Presently the SLCR GEM clock divisors are hard-coded
                  assuming that IO PLL output frequency is 1000 MHz.
                          The BDs are allocated at the address 0xFF00000 and the
                          1 MB address range starting from this address is made
                          uncached. This is because, for GEM the BDs need to be
                          placed in uncached memory. The RX BDs are allocated at
                          address 0xFF00000 and TX BDs are allocated at address
                          0xFF10000.
                          The MDIO divisor used of 224 is used for Zynq board.
    1.01a asa 02/27/12  The hardcoded SLCR divisors for Zynq are removed. The
                  divisors are obtained from xparameters.h.c. The sleep
                  values are reduced for Zynq. One sleep is added after
                  MDIO divisor is set. Some of the prints are removed.
    1.01a asa 03/14/12  The SLCR divisor support for ENET1 is added.
    1.01a asa 04/15/12  The funcation calls to Xil_DisableMMU and Xil_EnableMMU
                  are removed for setting the translation table
                  attributes for the BD memory region.
    1.05a asa 09/22/13 Cache handling is changed to fix an issue (CR#663885).
                      The cache invalidation of the Rx frame is now moved to
                      XEmacPsRecvHandler so that invalidation happens after the
                      received data is available in the memory. The variable
                      TxFrameLength is now made global.
    2.1     srt 07/11/14 Implemented 64-bit changes and modified as per
                  Zynq Ultrascale Mp GEM specification
    3.0  kpc  01/23/14 Removed PEEP board related code
    3.0  hk   03/18/15 Added support for jumbo frames.
                       Add cache flush after BD terminate entries.
    3.2  hk   10/15/15 Added clock control using CRL_APB_GEM_REF_CTRL register.
                       Enabled 1G speed for ZynqMP GEM.
                       Select GEM interrupt based on instance present.
                       Manage differences between emulation platform and silicon.
    3.2  mus  20/02/16.Added support for INTC interrupt controlller.
                       Added support to access zynq emacps interrupt from
                       microblaze.
    3.3 kpc   12/09/16 Fixed issue when -O2 is enabled
    3.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.
    3.5 hk    08/14/17 Don't perform data cache operations when CCI is enabled
                       on ZynqMP.
    3.8 hk    10/01/18 Fix warning for redefinition of interrupt number.
    3.9 hk    02/12/19 Change MDC divisor for Versal emulation.
              03/06/19 Fix BD space assignment and its memory attributes.
              03/20/19 Fix alignment pragmas for IAR compiler.
    3.10 hk   05/17/19 Use correct platform register for Versal.
              08/12/19 Add clock setup support for Versal.
              14/08/19 Move definition of Platform to _util file for common use.
              08/24/19 Add support for clock configuration in EL1 Non Secure for
                       Versal.
    3.14 sk   12/23/20 Remove documentation for None param in main function to fix
                         the doxygen warning.

## Functions
LONG | EmacPsDmaIntrExample (INTC *IntcInstancePtr, XEmacPs *EmacPsInstancePtr, u16 EmacPsDeviceId)
| This function demonstrates the usage of the EmacPs driver by sending by sending and receiving frames in interrupt driven DMA mode. More...
LONG | EmacPsDmaSingleFrameIntrExample (XEmacPs *EmacPsInstancePtr, u32 packet)
| This function demonstrates the usage of the EMACPS by sending and receiving a single frame in DMA interrupt mode. More...
void | XEmacPsClkSetup (XEmacPs *EmacPsInstancePtr, u16 EmacPsIntrId)
| This function sets up the clock divisors for 1000Mbps. More...
void | XEmacPs_SetMdioDivisor (XEmacPs *InstancePtr, XEmacPs_MdcDiv Divisor)
| Set the MDIO clock divisor. More...
int | main (void)
| This is the main function for the EmacPs example. More...

## Function Documentation

LONG EmacPsDmaIntrExample | ( | INTC * | IntcInstancePtr,
|  | XEmacPs * | EmacPsInstancePtr,
|  | u16 | EmacPsDeviceId
| ) |  |

This function demonstrates the usage of the EmacPs driver by sending by sending and receiving frames in interrupt driven DMA mode.

Parameters

  IntcInstancePtr | is a pointer to the instance of the Intc driver.
  EmacPsInstancePtr | is a pointer to the instance of the EmacPs driver.
  EmacPsDeviceId | is Device ID of the EmacPs Device , typically XPAR_<EMACPS_instance>_DEVICE_ID value from xparameters.h.

Returns
  XST_SUCCESS to indicate success, otherwise XST_FAILURE.

Note
  None.

References XEmacPs_Config::BaseAddress, EmacpsDelay(), EmacPsDmaSingleFrameIntrExample(), EmacPsUtilErrorTrap(), XEMACPS_BD_ALIGNMENT, XEmacPs_BdClear, XEmacPs_BdRingClone(), XEmacPs_BdRingCreate(), XEmacPs_BdSetStatus, XEmacPs_CfgInitialize(), XEmacPs_GetRxRing, XEmacPs_GetTxRing, XEmacPs_IntrHandler(), XEmacPs_LookupConfig(), XEMACPS_RECV, XEMACPS_SEND, XEmacPs_SetHandler(), XEmacPs_SetMacAddress(), XEmacPs_SetMdioDivisor(), XEmacPs_SetOperatingSpeed(), XEmacPs_SetOptions(), XEmacPs_Stop(), XEMACPS_TXBUF_USED_MASK, and XEmacPsClkSetup().

Referenced by main().

LONG EmacPsDmaSingleFrameIntrExample | ( | XEmacPs * | EmacPsInstancePtr,
|  | u32 | packet
| ) |  |

This function demonstrates the usage of the EMACPS by sending and receiving a single frame in DMA interrupt mode.

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

Parameters

  EmacPsInstancePtr | is a pointer to the instance of the EmacPs driver.
  packet | is the count of current transmitted/received packet

Returns
  XST_SUCCESS to indicate success, otherwise XST_FAILURE.

Note
  None.

References XEmacPs_Config::BaseAddress, XEmacPs_BdRing::BaseBdAddr, EmacPsUtilErrorTrap(), EmacPsUtilFrameHdrFormatMAC(), EmacPsUtilFrameHdrFormatType(), EmacPsUtilFrameMemClear(), EmacPsUtilFrameSetPayloadData(), EmacPsUtilFrameVerify(), XEmacPs_Config::IsCacheCoherent, XEmacPs_BdClear, XEmacPs_BdClearTxUsed, XEmacPs_BdGetLength, XEmacPs_BdRingAlloc(), XEmacPs_BdRingFree(), XEmacPs_BdRingFromHwRx(), XEmacPs_BdRingFromHwTx(), XEmacPs_BdRingToHw(), XEmacPs_BdSetAddressRx, XEmacPs_BdSetAddressTx, XEmacPs_BdSetLast, XEmacPs_BdSetLength, XEmacPs_BdSetStatus, XEMACPS_CMPA_ENABLE_MASK, XEmacPs_GetRxFrameSize, XEmacPs_GetRxRing, XEmacPs_GetTxRing, XEMACPS_RECV, XEMACPS_RXBUF_NEW_MASK, XEMACPS_RXBUF_WRAP_MASK, XEMACPS_SEND, XEmacPs_SetQueuePtr(), XEmacPs_Start(), XEmacPs_Stop(), XEmacPs_Transmit, XEMACPS_TXBUF_USED_MASK, XEMACPS_TXBUF_WRAP_MASK, and XEmacPs_WriteReg.

Referenced by EmacPsDmaIntrExample().

int main | ( | void |  | ) |

This is the main function for the EmacPs example.

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

Returns
  XST_SUCCESS to indicate success, otherwise XST_FAILURE.

Note
  None.

References XEmacPs_Config::BaseAddress, EmacPsDmaIntrExample(), EmacPsUtilErrorTrap(), XEmacPs_ReadReg, XEMACPS_RXCNT_OFFSET, and XEMACPS_TXCNT_OFFSET.

void XEmacPsClkSetup | ( | XEmacPs * | EmacPsInstancePtr,
|  | u16 | EmacPsIntrId
| ) |  |

This function sets up the clock divisors for 1000Mbps.

Parameters

  EmacPsInstancePtr | is a pointer to the instance of the EmacPs driver.
  EmacPsIntrId | is the Interrupt ID and is typically XPAR_<EMACPS_instance>_INTR value from xparameters.h.

Returns
  None.

Note
  None.

References XEmacPs_Config::BaseAddress, XEmacPs_Config::S1GDiv0, and XEmacPs_Config::S1GDiv1.

Referenced by EmacPsDmaIntrExample().