AM263Px MCU+ SDK: Enet LLD IOCTL interface

| AM263Px MCU+ SDK 26.00.00 |

Enet LLD IOCTL interface

# Introduction

The Enet LLD provides an IOCTL interface to configure the control related functionality of the Ethernet hardware, via Enet_ioctl() function.

The IOCTLs commands are classified according to the Enet LLD layer they belong: peripheral or module. The module IOCTL commands are further grouped into sets related to hardware modules typically found in Ethernet peripherals.

- Peripheral layer IOCTLs
- Module layer IOCTLs
  - Host port IOCTLs
  - MAC port IOCTLs
  - Forwarding database (FDB) IOCTLs
  - MDIO IOCTLs
  - Statistics IOCTLs
  - Time synchronization IOCTLs

## Using the IOCTL interface

The Enet_ioctl() function takes the following parameters:

- Enet driver handle which is obtained after opening the driver via Enet_open() function.
- Core id of the caller which is needed to identify calls originated locally or from a remote core.
- IOCTL command id.
- IOCTL arguments, which can be either input argument, output argument, both or none. Please refer to the description of each IOCTL to find out the required parameters and their types.

Enet LLD provides helper macros to setup the IOCTL parameters. There are four helper macros available to choose depending on the number of arguments:

- ENET_IOCTL_SET_NO_ARGS for IOCTLs that don't take any arguments.
- ENET_IOCTL_SET_IN_ARGS for IOCTLs that take only input arguments.
- ENET_IOCTL_SET_OUT_ARGS for IOCTLs that take only output arguments.
- ENET_IOCTL_SET_INOUT_ARGS for IOCTLs that take both, input and output arguments.

The code snippet below shows an example of the Enet LLD IOCTL interface, used for reading the version of an Ethernet peripheral.

void myFunction(void)
{
Enet_Handle hEnet;
Enet_IoctlPrms prms;
Enet_Version version;
int32_t status;
...
/* Open the Enet LLD */
hEnet = Enet_open(enetType, 0U, cfg, cfgSize);
...
/* Prepare IOCTL params */
ENET_IOCTL_SET_OUT_ARGS(&prms, &version);
/* Do the IOCTL command */
status = Enet_ioctl(hEnet, coreId, ENET_PER_IOCTL_GET_VERSION, &prms);
if (status != ENET_SOK)
{
printf("Failed to get Enet peripheral version: %d\n", status);
}
...
/* Close the Enet LLD */
Enet_close(hEnet);
...
}

## Synchronous and Asynchronous IOCTLs

The IOCTLs commands can be synchronous or asynchronous in nature. Synchronous IOCTLs execute immediately and return the operation status (see Enet_ErrorCodes). Asynchronous IOCTLs initiate an operation but don't wait for completion, they return ENET_SINPROGRESS code. The application must call Enet_poll() function to poll for the operation completion event.

The synchronous or asynchronous nature of IOCTLs is peripheral dependent, please refer to the peripheral specific documentation for further details.

The sample code in previous section corresponds to a synchronous IOCTL. The code snippet below shows the Enet LLD APIs involved in handling an asynchronous IOCTL.

Enet_Handle hEnet;
Semaphore_Handle sem;
void myFunc(void)
{
Enet_IoctlPrms prms;
Enet_Event evt;
SemaphoreP_Status semStatus;
int32_t status;
...
/* Open the Enet LLD */
hEnet = Enet_open(enetType, 0U, cfg, cfgSize);
...
/* Register an event callback function. This function is called upon event
* detection in Enet_poll() */
Enet_registerEventCb(hEnet, ENET_EVT_ASYNC_CMD_RESP, 0U, myEventCallbackFunc, NULL);
...
/* Prepare IOCTL params */
ENET_IOCTL_SET_NO_ARGS(&prms);
/* Run asynchronous IOCTL command */
status = Enet_ioctl(hEnet, coreId, ENET_FDB_IOCTL_REMOVE_ALL_ENTRIES, &prms);
if (status == ENET_SINPROGRESS)
{
/* Wait for asyc ioctl to complete */
do
{
Enet_poll(hEnet, ENET_EVT_ASYNC_CMD_RESP, NULL, 0);
semStatus = SemaphoreP_pend(sem, 1U);
} while (semStatus != SemaphoreP_OK);
status = ENET_SOK;
}
else if (status != ENET_SOK)
{
printf("Failed to run IOCTL command: %d\n", status);
}
...
/* Unregister event callback function */
Enet_registerEventCb(hEnet, evt, 0U);
...
/* Close the Enet LLD */
Enet_close(hEnet);
...
}
void myEventCallbackFunc(Enet_Event evt,
uint32_t evtNum,
void *evtCbArgs,
void *arg1,
void *arg2)
{
/* ENET_EVT_ASYNC_CMD_RESP has occurred! */
Semaphore_post(sem);
}
ENET_PER_IOCTL_GET_VERSION
@ ENET_PER_IOCTL_GET_VERSION
Get the hardware version of the peripheral.
Definition: enet_per.h:88
ENET_IOCTL_SET_NO_ARGS
#define ENET_IOCTL_SET_NO_ARGS(prms)
Set null args for an IOCTL command that takes no arguments.
Definition: enet_ioctl.h:111
Enet_open
Enet_Handle Enet_open(Enet_Type enetType, uint32_t instId, const void *cfg, uint32_t cfgSize)
Open and initializes the Enet driver for a peripheral.
ENET_SINPROGRESS
#define ENET_SINPROGRESS
Operation in progress.
Definition: enet_types.h:79
Enet_poll
void Enet_poll(Enet_Handle hEnet, Enet_Event evt, const void *arg, uint32_t argSize)
Poll for Ethernet events.
Enet_Event
Enet_Event
Ethernet events.
Definition: enet_types.h:268
ENET_IOCTL_SET_OUT_ARGS
#define ENET_IOCTL_SET_OUT_ARGS(prms, out)
Set the output args for an IOCTL command.
Definition: enet_ioctl.h:133
ENET_EVT_ASYNC_CMD_RESP
@ ENET_EVT_ASYNC_CMD_RESP
Definition: enet_types.h:276
Enet_registerEventCb
void Enet_registerEventCb(Enet_Handle hEnet, Enet_Event evt, uint32_t evtNum, Enet_EventCallback evtCb, void *evtCbArgs)
Register a callback for an event.
Enet_close
void Enet_close(Enet_Handle hEnet)
Close the Enet peripheral.
Enet_IoctlPrms
Enet IOCTL param.
Definition: enet_ioctl.h:282
Enet_Version
Version of a peripheral or module.
Definition: enet_types.h:322
ENET_SOK
#define ENET_SOK
Success.
Definition: enet_types.h:76
Enet_Handle
struct Enet_Obj_s * Enet_Handle
Ethernet driver handle.
Definition: enet_base.h:106
SemaphoreP_pend
int32_t SemaphoreP_pend(SemaphoreP_Object *obj, uint32_t timeToWaitInTicks)
Pend on a semaphore object or lock a mutex.