1.2.5.2.32 TCPIP_MAC_PacketRx Function

C

TCPIP_MAC_PACKET* TCPIP_MAC_PacketRx(
    DRV_HANDLE hMac, 
    TCPIP_MAC_RES* pRes, 
    const TCPIP_MAC_PACKET_RX_STAT** ppPktStat
);

Description

This is the MAC receive function.

Once a pending packet is available in the MAC driver internal RX queues this function will dequeue the packet and hand it over to the MAC driver's client - i.e., the stack - for further processing.

The flags for a RX packet have to be updated by the MAC driver: TCPIP_MAC_PKT_FLAG_RX has to be set. If the MAC supports it, it should set:

  • TCPIP_MAC_PKT_FLAG_UNICAST has to be set if that packet is a unicast packet

  • TCPIP_MAC_PKT_FLAG_BCAST has to be set if that packet is a broadcast packet

  • TCPIP_MAC_PKT_FLAG_MCAST has to be set if that packet is a multicast packet

  • TCPIP_MAC_PKT_FLAG_QUEUED has to be set

  • TCPIP_MAC_PKT_FLAG_SPLIT has to be set if the packet has multiple data segments

Additional information about the packet is available by providing the pRes and ppPktStat fields.

Precondtions

TCPIP_MAC_Initialize() should have been called. TCPIP_MAC_Open() should have been called to obtain a valid handle.

Parameters

ParametersDescription
hMacHandle identifying the MAC driver client.
pResOptional pointer to an address that will receive an additional result associated with the operation. Can be 0 if not needed.
ppPktStatOptional pointer to an address that will receive the received packet status. Note that this pointer cannot be used once the packet acknowledgment function was called. Can be 0 if not needed.

Returns

  • Valid pointer to an available RX packet.

  • 0 if no packet pending/available.

Remarks

The MAC driver should dequeue and return to the caller just one single packet, and not multiple chained packets.

Once the higher level layers in the stack are done with processing the RX packet, they have to call the corresponding packet acknowledgment function that tells the owner of that packet that it can resume control of that packet.

Once the stack modules are done processing the RX packets and the acknowledge function is called it is up to the driver design to reuse the RX packets, or simply return them to the pool they were allocated from (assuming that some sort of allocation is implemented). This document makes no requirement about how the MAC RX packets are obtained, using dynamic or static allocation techniques. This is up to the design of the MAC.

The MAC driver can use the TCPIP_MAC_Process() for obtaining new RX packets if needed.

Not all the MACs have hardware support for the received packet status. If the MAC driver cannot supply the TCPIP_MAC_PACKET_RX_STAT info, it should set the ppPktStat to 0.