Enet LLD IOCTL interface

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.

Using the IOCTL interface

The Enet_ioctl() function takes the following parameters:

Enet LLD provides helper macros to setup the IOCTL parameters. There are four helper macros available to choose depending on the number of 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_Version version;
int32_t status;
...
/* Open the Enet LLD */
hEnet = Enet_open(enetType, 0U, cfg);
...
/* 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.

Semaphore_Handle sem;
void myFunc(void)
{
int32_t status;
...
/* Open the Enet LLD */
hEnet = Enet_open(enetType, 0U, cfg);
...
/* Register an event callback function. This function is called upon event
* detection in Enet_poll() */
Enet_registerEventCb(hEnet, evt, 0U, myEventCallbackFunc, NULL);
...
/* Prepare IOCTL params */
/* Run asynchronous IOCTL command */
status = Enet_ioctl(hEnet, coreId, ENET_FDB_IOCTL_REMOVE_ALL_ENTRIES, &prms);
if (status == ENET_SINPROGRESS)
{
/* Block until IOCTL completion event is detected via Enet_poll() */
Semaphore_pend(sem, timeout);
}
else if (status != ENET_SOK)
{
printf("Failed to get Enet peripheral version: %d\n", status);
}
...
/* Unregister event callback function */
Enet_registerEventCb(hEnet, evt, 0U);
...
/* Close the Enet LLD */
Enet_close(hEnet);
...
}
/* Poll function called periodically */
void myPollFunc(void)
{
uint32_t pollMask = ENET_EVT_ASYNC_CMD_RESP;
/* Registered callback is called in this context */
Enet_poll(hEnet, pollMask);
}
void myEventCallbackFunc(Enet_Event evt,
uint32_t evtNum,
void *evtCbArgs,
void *arg1,
void *arg2)
{
/* ENET_EVT_ASYNC_CMD_RESP has occurred! */
Semaphore_post(sem);
}

Copyright 2020, Texas Instruments Incorporated