NetDev_Rx() (Ethernet)

The receive/Rx() function is called by µC/TCP-IP’s Receive task after the Interrupt Service Routine handler has signaled to the Receive task that a receive event has occurred. The Receive function requires that the device driver return a pointer to the data area containing the received data and return the size of the received frame via pointer.

Files

Every device driver’s net_dev.c

Prototype

          static void NetDev_Rx (NET_IF      *pif,
                                 CPU_INT08U **p_data,
                                 CPU_INT16U  *size,
                                 NET_ERR     *perr);

Note that since every device driver’s Rx() function is accessed only by function pointer via the device driver’s API structure, it doesn’t need to be globally available and should therefore be declared as ‘static’.

Arguments

pif

Pointer to the interface to receive data from a network device.

p_data

Pointer to return the address of the received data.

size

Pointer to return the size of the received data.

perr

Pointer to variable that will receive the return error code from this function.

Returned Value

None.

Required Configuration

None.

Notes / Warnings

The receive function should perform the following actions:

1. Check for receive errors if applicable. If an error should occur during reception, the driver should set *size to 0 and *p_data to (CPU_INT08U *)0 and return. Additional steps may be necessary depending on the device being serviced.
2. For Ethernet devices, get the size of the received frame and subtract 4 bytes for the CRC. It it always recommended that the frame size is checked to ensure that it is greater than 4 bytes before performing the subtraction to ensure that an underflow does not occur. Set *size equal to the adjusted frame size.
3. Get a new data buffer area by calling NetBuf_GetDataPtr(). If memory is not available, an error will be returned and the device driver should set *size to 0 and *p_data to (CPU_INT08U *)0. For DMA devices, the current receive descriptor should be marked as available or owned by hardware. The device driver should then return from the receive function.
4. If an error does not occur while getting a new data area, DMA devices should perform the following operations:

   a. Set *p_data equal to the address of the data area within the descriptor being serviced.

   b. Set the data area pointer within the receive descriptor to the address of the data area obtained by calling NetBuf_GetDataPtr().

   c. Update any descriptor ring pointers if applicable.

5. Non DMA devices should Mem_Copy() the data stored within the device to the address of the buffer obtained by calling NetBuf_GetDataPtr() and set *p_data equal to the address of the obtained data area.
6. Set perr to NET_DEV_ERR_NONE and return from the receive function. Otherwise, set perr to an appropriate network device error code.