Jump to main content

##

# MAC_DRVR_PacketRx Function

## C

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

## Returns

- a valid pointer to an available RX packet
- 0 if no packet pending/available

## Description

This function will return a packet if such a pending packet exists. Additional information about the packet is available by providing the pRes and ppPktStat fields.

## Remarks

- 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 are updated by the MAC driver:

  - TCPIP_MAC_PKT_FLAG_RX will be set
  - TCPIP_MAC_PKT_FLAG_UNICAST is set if that packet is a unicast packet
  - TCPIP_MAC_PKT_FLAG_BCAST is set if that packet is a broadcast packet
  - TCPIP_MAC_PKT_FLAG_MCAST is set if that packet is a multicast packet
  - TCPIP_MAC_PKT_FLAG_QUEUED is set
  - TCPIP_MAC_PKT_FLAG_SPLIT is set if the packet has multiple data segments

- The MAC driver dequeues and return to the caller just one single packet. That is the packets are not chained.

- The packet buffers are allocated by the Ethernet MAC driver itself, 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 MAC driver that it can resume control of that packet.

- Once the stack modules are done processing the RX packets and the acknowledge function is called, the MAC driver will reuse the RX packets.

- The MAC driver may use the MAC_DRVR_Process() for obtaining new RX packets if needed.

## Preconditions

- MAC_DRVR_Initialize() should have been called.
- MAC_DRVR_Open() should have been called to obtain a valid handle.

## Parameters

Parameters | Description
--- | ---
hMac | Ethernet MAC client handle
pRes | optional pointer to an address that will receive an additional result associated with the operation. Can be 0 if not needed.
ppPktStat | optional 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.