AM263Px MCU+ SDK: APIs for Enet LLD network

| AM263Px MCU+ SDK 26.00.00 |

Files | Data Structures | Functions | Typedefs | Enumerations | Macros
APIs for Enet LLD network

## Introduction

This module contains APIs which are used by the Enet LLD network driver.

## Files
file | lldtsync.h
| TI Timesync Low Level Driver abstract APIs.
file | lldtype.h
| Data types and macros for TI Enet LLD abstract APIs.
file | lldenet.h
| TI Ethernet Low Level Driver abstract APIs.

## Data Structures
struct | LLDTSyncCfg_t
| Configuration structure for LLDTSync. More...
struct | LLDEnetCfg_t
| Configuration structure for LLDEnet. More...
struct | LLDEnetFrame_t
| Structure representing an Ethernet frame. More...
struct | LLDEnetFrameScatter_t
| Structure representing an Ethernet frame. More...

## Functions
void | LLDTSyncCfgInit (LLDTSyncCfg_t *cfg)
| Initializes the LLDTSyncCfg_t configuration structure. More...
LLDTSync_t * | LLDTSyncOpen (LLDTSyncCfg_t *cfg, LLDTsyncTsSource tsSource)
| Opens a new LLDTSync instance to access the PTP clock. More...
void | LLDTSyncClose (LLDTSync_t *hTSync)
| Closes the LLDTSync instance. More...
int | LLDTSyncGetRxTime (LLDTSync_t *hTSync, uint8_t rxPort, int msgType, uint16_t seqId, uint8_t domain, uint64_t *ts)
| Retrieves the PTP RX timestamp for a specific message. More...
int | LLDTSyncGetTxTime (LLDTSync_t *hTSync, uint8_t txPort, int msgType, uint16_t seqId, uint8_t domain, uint64_t *ts)
| Retrieves the PTP TX timestamp for a specific message. More...
int | LLDTSyncAdjFreq (LLDTSync_t *hTSync, int ppb)
| Adjusts the frequency of the PTP clock. More...
int | LLDTSyncSetTime (LLDTSync_t *hTSync, uint64_t ts)
| Sets the time for the PTP clock. More...
int | LLDTSyncGetTime (LLDTSync_t *hTSync, uint64_t *ts)
| Retrieves the current time from the PTP clock. More...
int | LLDTSyncEnableTsEvent (LLDTSync_t *hTSync, uint32_t ports[], uint32_t numPorts)
| Enables PTP timestamp events for specified ports. More...
int | LLDTSyncShiftTime (LLDTSync_t *hTSync, int64_t offset)
| Shift the time of the PTP clock by offset nsec. More...
int | LLDTsyncPhyWaitTxTs (LLDTSync_t *hTSync, uint8_t txPort, int msgType, uint16_t seqId, uint8_t domain)
| Put the TX packet in the wait list. More...
int | LLDTSyncProcPhyStatusFrame (void *hEnet, uint8_t coreId, uint8_t txPort, uint8_t *frame, uint32_t size)
| Process the status frame. More...
void | LLDEnetCfgInit (LLDEnetCfg_t *cfg)
| Initializes the LLDEnetCfg_t structure. More...
LLDEnet_t * | LLDEnetOpen (LLDEnetCfg_t *cfg)
| Opens an instance of LLDEnet. More...
void | LLDEnetClose (LLDEnet_t *hLLDEnet)
| Closes an instance of LLDEnet. More...
int | LLDEnetFilter (LLDEnet_t *hLLDEnet, uint8_t *dstMacAddr, uint32_t vlanId, uint32_t ethType)
| Filter RX packets by using the destination MAC address and VLAN ID. More...
int | LLDEnetAllocMac (LLDEnet_t *hLLDEnet, uint8_t *srcMacAddr)
| Allocates a source MAC address. More...
void | LLDEnetFreeMac (LLDEnet_t *hLLDEnet, uint8_t *srcMacAddr)
| Frees a previously allocated MAC address. More...
int | LLDEnetSend (LLDEnet_t *hLLDEnet, LLDEnetFrame_t *frame)
| Sends an Ethernet frame using LLDEnet. More...
int | LLDEnetSendMulti (LLDEnet_t *hLLDEnet, LLDEnetFrame_t *frames, uint32_t nFrames)
| Sends multiple Ethernet frames using LLDEnet. More...
int | LLDEnetSendScatter (LLDEnet_t *hLLDEnet, LLDEnetFrameScatter_t *frame)
| Sends an ethernet frame of scatter buffers. More...
int | LLDEnetSendMultiScatter (LLDEnet_t *hLLDEnet, LLDEnetFrameScatter_t *frames, uint32_t nFrames)
| Sends multiples ethernet frames of scatter buffers. More...
int | LLDEnetRecv (LLDEnet_t *hLLDEnet, LLDEnetFrame_t *frame)
| Receives an Ethernet frame using LLDEnet. More...
int | LLDEnetRecvZeroCopy (LLDEnet_t *hLLDEnet, LLDEnetRecvCb_t LLDEnetRecvCb, void *cbArg)
| Receives an Ethernet frame using LLDEnet in the Zero-Copy way. More...
bool | LLDEnetIsPortUp (LLDEnet_t *hLLDEnet, uint8_t portNum)
| Checks if the specified port is up. More...
int | LLDEnetGetLinkInfo (LLDEnet_t *hLLDEnet, uint8_t portNum, uint32_t *speed, uint32_t *duplex)
| Retrieves the link speed and duplex information for the specified port. More...
int | LLDEnetSetTxNotifyCb (LLDEnet_t *hLLDEnet, void(*txNotifyCb)(void *arg), void *arg)
| Sets the transmit notification callback function for LLDEnet. More...
int | LLDEnetSetRxNotifyCb (LLDEnet_t *hLLDEnet, void(*rxNotifyCb)(void *arg), void *arg)
| Sets the receive notification callback function for LLDEnet. More...
int | LLDEnetSetDefaultRxDataCb (LLDEnet_t *hLLDEnet, void(*rxDefaultDataCb)(void *data, int size, int port, void *arg), void *arg)
| Sets the receive data callback function for LLDEnet when filter does not match. This callback is supported only when using the RX DMA shared channel. Currently, only Sitara AM273x is supported for this feature. More...
bool | LLDEnetIsRxTsInPkt (LLDEnet_t *hLLDEnet)
| Checks the receive packet timestamping mode. More...
int | LLDEnet_processStatusFrames (LLDEnet_t *hLLDEnet)
| Proccess the PHY status frames. More...

## Typedefs
typedef struct LLDTSync | LLDTSync_t
| Structure representing the LLDTSync instance. More...
typedef struct LLDEnet | LLDEnet_t
| Structure representing the LLDEnet instance. More...
typedef void(* | LLDEnetRecvCb_t) (LLDEnetFrame_t *frame, void *cbArg)
| Receives callback an Ethernet frame using LLDEnet in the Zero-Copy way. More...

## Enumerations
enum | LLDTsyncTsSource { LLDTSYNC_TS_SOURCE_INVALID = 0, LLDTSYNC_TS_SOURCE_CPTS, LLDTSYNC_TS_SOURCE_PHY }

## Macros
#define | LLDENET_E_OK (0)
#define | LLDENET_E_PARAM (-1)
#define | LLDENET_E_NOBUF (-2)
#define | LLDENET_E_BUFSIZE (-3)
#define | LLDENET_E_NOAVAIL (-4)
#define | LLDENET_E_DMA (-5)
#define | LLDENET_E_IOCTL (-6)
#define | LLDENET_E_NOMATCH (-7)
#define | LLDENET_E_FAILURE (-8)
#define | LLDENET_E_DENY (-9)
#define | LLDENET_E_UNSUPPORT (-10)
#define | LLDENET_MAX_PORTS 10
#define | MAX_NUM_RX_DMA_CH_PER_INSTANCE 2
#define | MAX_BUF_IN_SCATTER_FRAME 32
| Maximum number of buffers in a scatter frame. More...

## Macro Definition Documentation

## ◆ LLDENET_E_OK

#define LLDENET_E_OK (0)

no error

## ◆ LLDENET_E_PARAM

#define LLDENET_E_PARAM (-1)

param invalid

## ◆ LLDENET_E_NOBUF

#define LLDENET_E_NOBUF (-2)

no buffer

## ◆ LLDENET_E_BUFSIZE

#define LLDENET_E_BUFSIZE (-3)

small or invalid bufsize

## ◆ LLDENET_E_NOAVAIL

#define LLDENET_E_NOAVAIL (-4)

request for a not available resource

## ◆ LLDENET_E_DMA

#define LLDENET_E_DMA (-5)

dma error

## ◆ LLDENET_E_IOCTL

#define LLDENET_E_IOCTL (-6)

enet ioctl error

## ◆ LLDENET_E_NOMATCH

#define LLDENET_E_NOMATCH (-7)

does not match expectation

## ◆ LLDENET_E_FAILURE

#define LLDENET_E_FAILURE (-8)

general error

## ◆ LLDENET_E_DENY

#define LLDENET_E_DENY (-9)

The operation is denied

## ◆ LLDENET_E_UNSUPPORT

#define LLDENET_E_UNSUPPORT (-10)

The operation is unsupported

## ◆ LLDENET_MAX_PORTS

#define LLDENET_MAX_PORTS 10

Maximum number of ports supported by the Enet LLD abstract layer

## ◆ MAX_NUM_RX_DMA_CH_PER_INSTANCE

#define MAX_NUM_RX_DMA_CH_PER_INSTANCE 2

Maximum number of DMA rx channels per instance

## ◆ MAX_BUF_IN_SCATTER_FRAME

#define MAX_BUF_IN_SCATTER_FRAME 32

Maximum number of buffers in a scatter frame.

## Typedef Documentation

## ◆ LLDTSync_t

typedef struct LLDTSync LLDTSync_t

Structure representing the LLDTSync instance.

## ◆ LLDEnet_t

typedef struct LLDEnet LLDEnet_t

Structure representing the LLDEnet instance.

## ◆ LLDEnetRecvCb_t

typedef void(* LLDEnetRecvCb_t) (LLDEnetFrame_t *frame, void *cbArg)

Receives callback an Ethernet frame using LLDEnet in the Zero-Copy way.

Parameters

  frame | Pointer to the LLDEnetFrame_t structure to store the received frame.
  cbArg | Callback argument

## Enumeration Type Documentation

## ◆ LLDTsyncTsSource

enum LLDTsyncTsSource

Enumerator
LLDTSYNC_TS_SOURCE_INVALID |
LLDTSYNC_TS_SOURCE_CPTS |
LLDTSYNC_TS_SOURCE_PHY |

## Function Documentation

## ◆ LLDTSyncCfgInit()

void LLDTSyncCfgInit | ( | LLDTSyncCfg_t * | cfg | ) |

Initializes the LLDTSyncCfg_t configuration structure.

Parameters

  cfg | Pointer to the LLDTSyncCfg_t configuration structure.

## ◆ LLDTSyncOpen()

LLDTSync_t* LLDTSyncOpen | ( | LLDTSyncCfg_t * | cfg,
|  | LLDTsyncTsSource | tsSource
| ) |  |

Opens a new LLDTSync instance to access the PTP clock.

Parameters

  cfg | Pointer to the LLDTSyncCfg_t configuration structure.
  tsSource | Timestamp source selection, CPTS or PHY.

Returns
  Pointer to the opened LLDTSync instance.

## ◆ LLDTSyncClose()

void LLDTSyncClose | ( | LLDTSync_t * | hTSync | ) |

Closes the LLDTSync instance.

Parameters

  hTSync | Pointer to the LLDTSync instance.

## ◆ LLDTSyncGetRxTime()

int LLDTSyncGetRxTime | ( | LLDTSync_t * | hTSync,
|  | uint8_t | rxPort,
|  | int | msgType,
|  | uint16_t | seqId,
|  | uint8_t | domain,
|  | uint64_t * | ts
| ) |  |

Retrieves the PTP RX timestamp for a specific message.

Parameters

  hTSync | Pointer to the LLDTSync instance.
  rxPort | Receive port.
  msgType | Message type.
  seqId | Sequence ID.
  domain | Domain number.
  ts | Pointer to store the PTP RX timestamp.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDTSyncGetTxTime()

int LLDTSyncGetTxTime | ( | LLDTSync_t * | hTSync,
|  | uint8_t | txPort,
|  | int | msgType,
|  | uint16_t | seqId,
|  | uint8_t | domain,
|  | uint64_t * | ts
| ) |  |

Retrieves the PTP TX timestamp for a specific message.

Parameters

  hTSync | Pointer to the LLDTSync instance.
  txPort | Transmit port.
  msgType | Message type.
  seqId | Sequence ID.
  domain | Domain number.
  ts | Pointer to store the PTP TX timestamp.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDTSyncAdjFreq()

int LLDTSyncAdjFreq | ( | LLDTSync_t * | hTSync,
|  | int | ppb
| ) |  |

Adjusts the frequency of the PTP clock.

Parameters

  hTSync | Pointer to the LLDTSync instance.
  ppb | Parts per billion adjustment value.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDTSyncSetTime()

int LLDTSyncSetTime | ( | LLDTSync_t * | hTSync,
|  | uint64_t | ts
| ) |  |

Sets the time for the PTP clock.

Parameters

  hTSync | Pointer to the LLDTSync instance.
  ts | Time to set.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDTSyncGetTime()

int LLDTSyncGetTime | ( | LLDTSync_t * | hTSync,
|  | uint64_t * | ts
| ) |  |

Retrieves the current time from the PTP clock.

Parameters

  hTSync | Pointer to the LLDTSync instance.
  ts | Pointer to store the current time.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDTSyncEnableTsEvent()

int LLDTSyncEnableTsEvent | ( | LLDTSync_t * | hTSync,
|  | uint32_t | ports[],
|  | uint32_t | numPorts
| ) |  |

Enables PTP timestamp events for specified ports.

Parameters

  hTSync | Pointer to the LLDTSync instance.
  ports | Array of ports to enable timestamp events for.
  numPorts | Number of ports in the array.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDTSyncShiftTime()

int LLDTSyncShiftTime | ( | LLDTSync_t * | hTSync,
|  | int64_t | offset
| ) |  |

Shift the time of the PTP clock by offset nsec.

Parameters

  hTSync | Pointer to the LLDTSync instance.
  offset | Offset in nanoseconds, the value can be negative.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDTsyncPhyWaitTxTs()

int LLDTsyncPhyWaitTxTs | ( | LLDTSync_t * | hTSync,
|  | uint8_t | txPort,
|  | int | msgType,
|  | uint16_t | seqId,
|  | uint8_t | domain
| ) |  |

Put the TX packet in the wait list.

Parameters

  hTSync | Pointer to the LLDTSync instance.
  txPort | Mac port number of Tx packet.
  msgType | Message type of Tx packet.
  seqId | Sequence ID of Tx packet.
  domain | Domain number of the PTP instance.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDTSyncProcPhyStatusFrame()

int LLDTSyncProcPhyStatusFrame | ( | void * | hEnet,
|  | uint8_t | coreId,
|  | uint8_t | txPort,
|  | uint8_t * | frame,
|  | uint32_t | size
| ) |  |

Process the status frame.

Parameters

  hEnet | Enet handle pointer. (Typecasted to void *)
  coreId | Application core ID.
  txPort | Macport number of TX port.
  frame | Pointer to the ethernet frame.
  size | size of the ethernet frame.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetCfgInit()

void LLDEnetCfgInit | ( | LLDEnetCfg_t * | cfg | ) |

Initializes the LLDEnetCfg_t structure.

Parameters

  cfg | Pointer to the LLDEnetCfg_t structure to be initialized.

## ◆ LLDEnetOpen()

LLDEnet_t* LLDEnetOpen | ( | LLDEnetCfg_t * | cfg | ) |

Opens an instance of LLDEnet.

Parameters

  cfg | Pointer to the LLDEnetCfg_t structure containing the configuration parameters.

Returns
  Pointer to the LLDEnet instance (LLDEnet_t) if successful, NULL otherwise.

## ◆ LLDEnetClose()

void LLDEnetClose | ( | LLDEnet_t * | hLLDEnet | ) |

Closes an instance of LLDEnet.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.

## ◆ LLDEnetFilter()

int LLDEnetFilter | ( | LLDEnet_t * | hLLDEnet,
|  | uint8_t * | dstMacAddr,
|  | uint32_t | vlanId,
|  | uint32_t | ethType
| ) |  |

Filter RX packets by using the destination MAC address and VLAN ID.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  dstMacAddr | Destination MAC address to filter.
  vlanId | VLAN ID to filter.
  ethType | Ethernet type to filter (e.g. PTP ethernet type is 0x88F7).

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetAllocMac()

int LLDEnetAllocMac | ( | LLDEnet_t * | hLLDEnet,
|  | uint8_t * | srcMacAddr
| ) |  |

Allocates a source MAC address.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  srcMacAddr | Pointer to store the allocated MAC address.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetFreeMac()

void LLDEnetFreeMac | ( | LLDEnet_t * | hLLDEnet,
|  | uint8_t * | srcMacAddr
| ) |  |

Frees a previously allocated MAC address.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  srcMacAddr | MAC address to be freed.

## ◆ LLDEnetSend()

int LLDEnetSend | ( | LLDEnet_t * | hLLDEnet,
|  | LLDEnetFrame_t * | frame
| ) |  |

Sends an Ethernet frame using LLDEnet.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  frame | Pointer to the LLDEnetFrame_t structure representing the frame to be sent.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetSendMulti()

int LLDEnetSendMulti | ( | LLDEnet_t * | hLLDEnet,
|  | LLDEnetFrame_t * | frames,
|  | uint32_t | nFrames
| ) |  |

Sends multiple Ethernet frames using LLDEnet.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  frames | Array of LLDEnetFrame_t structures representing the frames to be sent.
  nFrames | Number of frames in the array.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetSendScatter()

int LLDEnetSendScatter | ( | LLDEnet_t * | hLLDEnet,
|  | LLDEnetFrameScatter_t * | frame
| ) |  |

Sends an ethernet frame of scatter buffers.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  frame | Scatter frame

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetSendMultiScatter()

int LLDEnetSendMultiScatter | ( | LLDEnet_t * | hLLDEnet,
|  | LLDEnetFrameScatter_t * | frames,
|  | uint32_t | nFrames
| ) |  |

Sends multiples ethernet frames of scatter buffers.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  frames | Array of Scatter frames
  nFrames | Number of frames in the array.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetRecv()

int LLDEnetRecv | ( | LLDEnet_t * | hLLDEnet,
|  | LLDEnetFrame_t * | frame
| ) |  |

Receives an Ethernet frame using LLDEnet.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  frame | Pointer to the LLDEnetFrame_t structure to store the received frame.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

Note
  The LLDENET_E_NOMATCH error when this function has data but does not match the data filter. This can happens when the RX DMA is shared between multiple data flows.

## ◆ LLDEnetRecvZeroCopy()

int LLDEnetRecvZeroCopy | ( | LLDEnet_t * | hLLDEnet,
|  | LLDEnetRecvCb_t | LLDEnetRecvCb,
|  | void * | cbArg
| ) |  |

Receives an Ethernet frame using LLDEnet in the Zero-Copy way.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  LLDEnetRecvCb | Receive callback
  cbArg | Callback argument

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetIsPortUp()

bool LLDEnetIsPortUp | ( | LLDEnet_t * | hLLDEnet,
|  | uint8_t | portNum
| ) |  |

Checks if the specified port is up.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  portNum | Port number to check.

Returns
  True if the port is up, false otherwise.

## ◆ LLDEnetGetLinkInfo()

int LLDEnetGetLinkInfo | ( | LLDEnet_t * | hLLDEnet,
|  | uint8_t | portNum,
|  | uint32_t * | speed,
|  | uint32_t * | duplex
| ) |  |

Retrieves the link speed and duplex information for the specified port.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  portNum | Port number to retrieve the link information.
  speed | Pointer to store the link speed.
  duplex | Pointer to store the link duplex mode.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetSetTxNotifyCb()

int LLDEnetSetTxNotifyCb | ( | LLDEnet_t * | hLLDEnet,
|  | void(*)(void *arg) | txNotifyCb,
|  | void * | arg
| ) |  |

Sets the transmit notification callback function for LLDEnet.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  txNotifyCb | Pointer to the transmit notification callback function.
  arg | Argument to be passed to the callback function.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetSetRxNotifyCb()

int LLDEnetSetRxNotifyCb | ( | LLDEnet_t * | hLLDEnet,
|  | void(*)(void *arg) | rxNotifyCb,
|  | void * | arg
| ) |  |

Sets the receive notification callback function for LLDEnet.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  rxNotifyCb | Pointer to the receive notification callback function.
  arg | Argument to be passed to the callback function.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetSetDefaultRxDataCb()

int LLDEnetSetDefaultRxDataCb | ( | LLDEnet_t * | hLLDEnet,
|  | void(*)(void *data, int size, int port, void *arg) | rxDefaultDataCb,
|  | void * | arg
| ) |  |

Sets the receive data callback function for LLDEnet when filter does not match. This callback is supported only when using the RX DMA shared channel. Currently, only Sitara AM273x is supported for this feature.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.
  rxDefaultDataCb | Pointer to the receive data callback function.
  arg | Argument to be passed to the callback function.

Returns
  LLDENET_E_OK if successful, an error code otherwise.

## ◆ LLDEnetIsRxTsInPkt()

bool LLDEnetIsRxTsInPkt | ( | LLDEnet_t * | hLLDEnet | ) |

Checks the receive packet timestamping mode.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.

Returns
  true if isRxTsInPkt is true for the LLDEnet handle.

## ◆ LLDEnet_processStatusFrames()

int LLDEnet_processStatusFrames | ( | LLDEnet_t * | hLLDEnet | ) |

Proccess the PHY status frames.

Parameters

  hLLDEnet | Pointer to the LLDEnet instance.

Returns
  Number of status frames processed.