### Xilinx Processor IP Library

<hl>Software Drivers</hl>

Main Page | Data Structures | File List | Data Fields | Globals

# xemaclite.h File Reference

## Detailed Description

## Data Structures

struct | XEmacLite_Config
struct | XEmacLite

## Defines

#define | XEmacLite_mNextTransmitAddr(InstancePtr)
#define | XEmacLite_mNextReceiveAddr(InstancePtr)
#define | XEmacLite_mIsMdioConfigured(InstancePtr)
#define | XEmacLite_mIsLoopbackConfigured(InstancePtr)

## Functions

int | XEmacLite_CfgInitialize (XEmacLite *InstancePtr, XEmacLite_Config *EmacLiteConfigPtr, u32 EffectiveAddr)
void | XEmacLite_SetMacAddress (XEmacLite *InstancePtr, u8 *AddressPtr)
int | XEmacLite_TxBufferAvailable (XEmacLite *InstancePtr)
void | XEmacLite_FlushReceive (XEmacLite *InstancePtr)
int | XEmacLite_Send (XEmacLite *InstancePtr, u8 *FramePtr, unsigned ByteCount)
u16 | XEmacLite_Recv (XEmacLite *InstancePtr, u8 *FramePtr)
int | XEmacLite_PhyRead (XEmacLite *InstancePtr, u32 PhyAddress, u32 RegNum, u16 *PhyDataPtr)
int | XEmacLite_PhyWrite (XEmacLite *InstancePtr, u32 PhyAddress, u32 RegNum, u16 PhyData)
void | XEmacLite_EnableLoopBack (XEmacLite *InstancePtr)
void | XEmacLite_DisableLoopBack (XEmacLite *InstancePtr)
XEmacLite_Config * | XEmacLite_LookupConfig (u16 DeviceId)
int | XEmacLite_Initialize (XEmacLite *InstancePtr, u16 DeviceId)
int | XEmacLite_EnableInterrupts (XEmacLite *InstancePtr)
void | XEmacLite_DisableInterrupts (XEmacLite *InstancePtr)
void | XEmacLite_InterruptHandler (void *InstancePtr)
void | XEmacLite_SetRecvHandler (XEmacLite *InstancePtr, void *CallBackRef, XEmacLite_Handler FuncPtr)
void | XEmacLite_SetSendHandler (XEmacLite *InstancePtr, void *CallBackRef, XEmacLite_Handler FuncPtr)
int | XEmacLite_SelfTest (XEmacLite *InstancePtr)

## Define Documentation

#define XEmacLite_mIsLoopbackConfigured | ( | InstancePtr |  | ) |

This macro determines if the device is currently configured for internal loopback.

Parameters:

  | InstancePtr | is the pointer to the instance of the EmacLite driver.

Returns:
  - XTRUE if the device is configured for internal loopback.
  - XFALSE if the device is NOT configured for internal loopback.

Note:
  C-Style signature: int XEmacLite_mIsLoopbackConfigured(XEmacLite *InstancePtr)

#define XEmacLite_mIsMdioConfigured | ( | InstancePtr |  | ) |

This macro determines if the device is currently configured for MDIO.

Parameters:

  | InstancePtr | is the pointer to the instance of the EmacLite driver.

Returns:
  - XTRUE if the device is configured for MDIO.
  - XFALSE if the device is NOT configured for MDIO.

Note:
  C-Style signature: int XEmacLite_mIsMdioConfigured(XEmacLite *InstancePtr)

#define XEmacLite_mNextReceiveAddr | ( | InstancePtr |  | ) |

Return the next expected Receive Buffer's address.

Parameters:

  | InstancePtr | is the pointer to the instance of the driver to be worked on

Note:
  C-Style signature: u32 XEmacLite_mNextReceiveAddr(XEmacLite *InstancePtr);

This macro returns the address of the next receive buffer to read data from. This is the expected receive buffer address if the driver is in sync.

#define XEmacLite_mNextTransmitAddr | ( | InstancePtr |  | ) |

Return the next expected Transmit Buffer's address .

Parameters:

  | InstancePtr | is the pointer to the instance of the driver to be worked on

Note:
  C-Style signature: u32 XEmacLite_mNextTransmitAddr(XEmacLite *InstancePtr);

This macro returns the address of the next transmit buffer to put data into. This is used to determine the destination of the next transmit data frame.

## Function Documentation

int XEmacLite_CfgInitialize | ( | XEmacLite * | InstancePtr,
|  | XEmacLite_Config * | EmacLiteConfigPtr,
|  | u32 | EffectiveAddr
| ) |

Initialize a specific XEmacLite instance/driver. The initialization entails:

- Initialize fields of the XEmacLite instance structure.

The driver defaults to polled mode operation.

Parameters:

  | InstancePtr | is a pointer to the XEmacLite instance.
  | EmacLiteConfigPtr | points to the XEmacLite device configuration structure.
  | EffectiveAddr | is the device base address in the virtual memory address space. If the address translation is not used then the physical address is passed. Unexpected errors may occur if the address mapping is changed after this function is invoked.

Returns:
  - XST_SUCCESS if initialization was successful.

Note:
  The initialization of the PHY device is not done in this function. The user needs to use XEmacLite_PhyRead and XEmacLite_PhyWrite functions to access the PHY device.

void XEmacLite_DisableInterrupts | ( | XEmacLite * | InstancePtr | ) |

Disables the interrupts from the device (the higher layer software is responsible for disabling interrupts at the interrupt controller).

To start using the device again, _EnableInterrupts must be called.

Parameters:

  | InstancePtr | is a pointer to the XEmacLite instance .

Returns:
  None.

Note:
  None.

void XEmacLite_DisableLoopBack | ( | XEmacLite * | InstancePtr | ) |

Disable Internal loop back functionality.

Parameters:

  | InstancePtr | is the pointer to the instance of the driver.

Returns:
  None.

Note:
  None.

int XEmacLite_EnableInterrupts | ( | XEmacLite * | InstancePtr | ) |

Enable the EmacLite Interrupts.

This function must be called before other functions to send or receive data in interrupt driven mode. The user should have connected the interrupt handler of the driver to an interrupt source such as an interrupt controller or the processor interrupt prior to this function being called.

Parameters:

  | InstancePtr | is a pointer to the XEmacLite instance.

Returns:
  - XST_SUCCESS if the device interrupts were enabled successfully.
  - XST_NO_CALLBACK if the callbacks were not set.

Note:
  None.

void XEmacLite_EnableLoopBack | ( | XEmacLite * | InstancePtr | ) |

Enable Internal loop back functionality.

Parameters:

  | InstancePtr | is the pointer to the instance of the driver.

Returns:
  None.

Note:
  None.

void XEmacLite_FlushReceive | ( | XEmacLite * | InstancePtr | ) |

Flush the Receive buffers. All data will be lost.

Parameters:

  | InstancePtr | is the pointer to the instance of the driver to be worked on.

Returns:
  None.

Note:
  None.

int XEmacLite_Initialize | ( | XEmacLite * | InstancePtr,
|  | u16 | DeviceId
| ) |

Initialize a specific XEmacLite instance/driver. The initialization entails:

- Initialize fields of the XEmacLite instance structure.

The driver defaults to polled mode operation.

Parameters:

  | InstancePtr | is a pointer to the XEmacLite instance.
  | DeviceId | is the unique id of the device controlled by this XEmacLite instance. Passing in a device id associates the generic XEmacLite instance to a specific device, as chosen by the caller or application developer.

Returns:
  - XST_SUCCESS if initialization was successful.
  - XST_DEVICE_NOT_FOUND/XST_FAILURE if device configuration information was not found for a device with the supplied device ID.

Note:
  None

void XEmacLite_InterruptHandler | ( | void * | InstancePtr | ) |

Interrupt handler for the EmacLite driver. It performs the following processing:

- Get the interrupt status from the registers to determine the source of the interrupt.
- Call the appropriate handler based on the source of the interrupt.

Parameters:

  | InstancePtr | contains a pointer to the EmacLite device instance for the interrupt.

Returns:
  None.

Note:
  None.

XEmacLite_Config* XEmacLite_LookupConfig | ( | u16 | DeviceId | ) |

Lookup the device configuration based on the unique device ID. The table XEmacLite_ConfigTable contains the configuration info for each device in the system.

Parameters:

  | DeviceId | is the unique device ID of the device being looked up.

Returns:
  A pointer to the configuration table entry corresponding to the given device ID, or NULL if no match is found.

Note:
  None.

int XEmacLite_PhyRead | ( | XEmacLite * | InstancePtr,
|  | u32 | PhyAddress,
|  | u32 | RegNum,
|  | u16 * | PhyDataPtr
| ) |

Read the specified PHY register.

Parameters:

  | InstancePtr | is the pointer to the instance of the driver.
  | PhyAddress | is the address of the PHY device. The valid range is is from 0 to 31.
  | RegNum | is the register number in the PHY device which is to be read. The valid range is is from 0 to 31.
  | PhyDataPtr | is a pointer to the data in which the data read from the PHY device is returned.

Returns:
  - XST_SUCCESS if the data is read from the PHY.
  - XST_DEVICE_BUSY if MDIO is busy.

Note:
  This function waits for the completion of MDIO data transfer.

int XEmacLite_PhyWrite | ( | XEmacLite * | InstancePtr,
|  | u32 | PhyAddress,
|  | u32 | RegNum,
|  | u16 | PhyData
| ) |

Write the given data to the specified register in the PHY device.

Parameters:

  | InstancePtr | is the pointer to the instance of the driver.
  | PhyAddress | is the address of the PHY device. The valid range is is from 0 to 31.
  | RegNum | is the register number in the PHY device which is to be written. The valid range is is from 0 to 31.
  | PhyData | is the data to be written to the specified register in the PHY device.

Returns:
  - XST_SUCCESS if the data is written to the PHY.
  - XST_DEVICE_BUSY if MDIO is busy.

Note:
  This function waits for the completion of MDIO data transfer.

u16 XEmacLite_Recv | ( | XEmacLite * | InstancePtr,
|  | u8 * | FramePtr
| ) |

Receive a frame. Intended to be called from the interrupt context or with a wrapper which waits for the receive frame to be available.

Parameters:

  | InstancePtr | is a pointer to the XEmacLite instance.
  | FramePtr | is a pointer to a buffer where the frame will be stored. The buffer must be at least XEL_MAX_FRAME_SIZE bytes. For optimal performance, a 32-bit aligned buffer should be used but it is not required, the function will align the data if necessary.

Returns:

The type/length field of the frame received. When the type/length field contains the type, XEL_MAX_FRAME_SIZE bytes will be copied out of the buffer and it is up to the higher layers to sort out the frame. Function returns 0 if there is no data waiting in the receive buffer or the pong buffer if configured.

Note:

This function call is not blocking in nature, i.e. it will not wait until a frame arrives.

int XEmacLite_SelfTest | ( | XEmacLite * | InstancePtr | ) |

Performs a SelfTest on the EmacLite device as follows:

- Writes to the mandatory TX buffer and reads back to verify.
- If configured, writes to the secondary TX buffer and reads back to verify.
- Writes to the mandatory RX buffer and reads back to verify.
- If configured, writes to the secondary RX buffer and reads back to verify.

Parameters:

  | InstancePtr | is a pointer to the XEmacLite instance .

Returns:
  - XST_SUCCESS if the device Passed the Self Test.
  - XST_FAILURE if any of the data read backs fail.

Note:
  None.

int XEmacLite_Send | ( | XEmacLite * | InstancePtr,
|  | u8 * | FramePtr,
|  | unsigned | ByteCount
| ) |

Send an Ethernet frame. The ByteCount is the total frame size, including header.

Parameters:

  | InstancePtr | is a pointer to the XEmacLite instance.
  | FramePtr | is a pointer to frame. For optimal performance, a 32-bit aligned buffer should be used but it is not required, the function will align the data if necessary.
  | ByteCount | is the size, in bytes, of the frame

Returns:
  - XST_SUCCESS if data was transmitted.
  - XST_FAILURE if buffer(s) was (were) full and no valid data was transmitted.

Note:

This function call is not blocking in nature, i.e. it will not wait until the frame is transmitted.

void XEmacLite_SetMacAddress | ( | XEmacLite * | InstancePtr,
|  | u8 * | AddressPtr
| ) |

Set the MAC address for this device. The address is a 48-bit value.

Parameters:

  | InstancePtr | is a pointer to the XEmacLite instance.
  | AddressPtr | is a pointer to a 6-byte MAC address. the format of the MAC address is major octet to minor octet

Returns:
  None.

Note:

- TX must be idle and RX should be idle for deterministic results. It is recommended that this function should be called after the initialization and before transmission of any packets from the device.
- Function will not return if hardware is absent or not functioning properly.
- The MAC address can be programmed using any of the two transmit buffers (if configured).

void XEmacLite_SetRecvHandler | ( | XEmacLite * | InstancePtr,
|  | void * | CallBackRef,
|  | XEmacLite_Handler | FuncPtr
| ) |

Sets the callback function for handling received frames in interrupt mode. The upper layer software should call this function during initialization. The callback is called when a frame is received. The callback function should communicate the data to a thread such that the processing is not performed in an interrupt context.

The callback is invoked by the driver within interrupt context, so it needs to do its job quickly. If there are other potentially slow operations within the callback, these should be done at task-level.

Parameters:

  | InstancePtr | is a pointer to the XEmacLite instance..
  | CallBackRef | is a reference pointer to be passed back to the application in the callback. This helps the application correlate the callback to a particular driver.
  | FuncPtr | is the pointer to the callback function.

Returns:
  None.

Note:
  None.

void XEmacLite_SetSendHandler | ( | XEmacLite * | InstancePtr,
|  | void * | CallBackRef,
|  | XEmacLite_Handler | FuncPtr
| ) |

Sets the callback function for handling transmitted frames in interrupt mode. The upper layer software should call this function during initialization. The callback is called when a frame is transmitted. The callback function should communicate the data to a thread such that the processing is not performed in an interrupt context.

The callback is invoked by the driver within interrupt context, so it needs to do its job quickly. If there are other potentially slow operations within the callback, these should be done at task-level.

Parameters:

  | InstancePtr | is a pointer to the XEmacLite instance.
  | CallBackRef | is a reference pointer to be passed back to the application in the callback. This helps the application correlate the callback to a particular driver.
  | FuncPtr | is the pointer to the callback function.

Returns:
  None.

Note:
  None.

int XEmacLite_TxBufferAvailable | ( | XEmacLite * | InstancePtr | ) |

Determine if there is a transmit buffer available.

Parameters:

  | InstancePtr | is the pointer to the instance of the driver to be worked on.

Returns:
  - TRUE if there is a TX buffer available for data to be written
  - FALSE if Tx Buffer is not available.

Note:
  None.

Copyright © 1995-2009 Xilinx, Inc. All rights reserved.