1.2.5.2.2 _tag_TCPIP_MAC_PACKET Structure

C

struct _tag_TCPIP_MAC_PACKET {
struct _tag_TCPIP_MAC_PACKET* next;
struct _tag_TCPIP_MAC_PACKET* pkt_next;
TCPIP_MAC_PACKET_ACK_FUNC ackFunc;
const void* ackParam;
TCPIP_MAC_DATA_SEGMENT* pDSeg;
uint8_t* pMacLayer;
uint8_t* pNetLayer;
uint8_t* pTransportLayer;
uint16_t totTransportLen;
uint16_t pktFlags;
uint32_t tStamp;
const void* pktIf;
int16_t ackRes;
union {
    uint16_t pktClientData[3];
    struct {
    uint16_t ipv4PktData;
    uint16_t ipv6PktData;
    uint16_t modPktData;
    };
};
uint8_t pktPriority;
uint32_t pktClientLoad[];
};

Description

MAC Packet.

Structure of a packet transferred with the MAC. This is the structure used for both TX and RX. See the description of each individual field.

Members


Members	Description
next	Multi-packet/queuing support. This field is used for chaining/queuing packets.
pkt_next	Multi-packet/queuing support. This field is used for chaining packet fragments, etc.
ackFunc	Packet acknowledgment function. On TX: A stack module owns the packet. Once the MAC is done transmitting the packet (success or failure) it has to set an appropriate acknowledge result in the ackRes field ( a TCPIP_MAC_PKT_ACK_RES) adjust some packet flags (see TCPIP_MAC_PKT_FLAG_QUEUED) and call the packet acknowledge function (ackFunc). This call informs the packet owner that the MAC is done with using that packet. It is up to the implementation what action the ackFunc takes: reuse, free, discard the packet or if some of the above steps are included in the ackFunc itself. On RX: The packet is under the MAC control and it's passed to the stack when it contains valid data. Once the recipient of the packet (IP, ICMP, UDP, TCP, etc.) is done with the packet processing it has to set an appropriate acknowledge result in the ackRes field ( a TCPIP_MAC_PKT_ACK_RES) adjust some packet flags (see TCPIP_MAC_PKT_FLAG_QUEUED) and call the packet acknowledge function (ackFunc). This call informs the packet owner (the MAC) that the processing of the packet is completed. It is up to the implementation what action the ackFunc takes: reuse, free, discard the packet or if some of the above steps are included in the ackFunc itself.
ackParam	Associated acknowledgment parameter to be used when ackFunc is called. For TX packets: this is a client supplied parameter and is not used by the MAC driver. For RX: If the MAC owns the RX packet then the MAC driver can use this field for further dispatching in the MAC driver owned acknowledgment function.
pDSeg	Data (root) segment associated to this packet. It is up to the design if the root data segment associated with a packet is contiguous in memory with the packet itself. It can be 0 if the packet has no associated data.
pMacLayer	Pointer to the MAC frame. On TX: the sending higher layer protocol updates this field. On RX: the MAC driver updates this field before handing over the packet. (MCHP TCP/IP stack note: The packet allocation function update this field automatically).
pNetLayer	Pointer to the network layer data. On TX: the sending higher layer protocol updates this field. The MAC driver shouldn't need this field. On RX: the MAC driver updates this field before handing over the packet. (MCHP TCP/IP stack note: The packet allocation function updates this field automatically. But not for IPv6!).
pTransportLayer	Pointer to the transport layer. The MAC driver does not use this field.
totTransportLen	Total length of the transport layer. The MAC driver shouldn't need this field.
pktFlags	TCPIP_MAC_PACKET_FLAGS associated packet flags. On TX: the MAC driver has to set: TCPIP_MAC_PKT_FLAG_QUEUED - if the driver needs to queue the packet On RX: the MAC driver updates this field before handing over the packet. Flags that the MAC driver has to set/clear: TCPIP_MAC_PKT_FLAG_RX and TCPIP_MAC_PKT_FLAG_UNICAST, TCPIP_MAC_PKT_FLAG_BCAST and TCPIP_MAC_PKT_FLAG_MCAST TCPIP_MAC_PKT_FLAG_QUEUED TCPIP_MAC_PKT_FLAG_SPLIT
tStamp	Time stamp value. Statistics, info. On TX: the sending higher layer protocol updates this field. The MAC driver shouldn't need this field On RX: the MAC driver updates this field before handing over the packet.
pktIf	The packet interface. On TX: the sending higher layer protocol updates this field. The MAC driver doesn't use this field. On RX: the receiving higher level protocol updates this value. The MAC driver doesn't use this field.
ackRes	A TCPIP_MAC_PKT_ACK_RES code associated with the packet. On TX: The MAC driver sets this field when calling the packet ackFunc. On RX: The higher level protocol which is the recipient of the packet sets this field when calling the packet ackFunc.
pktPriority	Priority associated with the packet. On TX: The MAC driver use this field to transmit packet using priority queues. On RX: The MAC driver inform stack about the priority of the packet received.
pktClientLoad	Additional client packet payload, variable packet data. Ignored by the MAC driver.

Remarks

Specific TCP/IP stack implementations might offer packet support functions to assist in driver development. (For the MCHP TCP/IP stack see tcpip_packet.h).

Since the packets may be dynamically allocated, an acknowledge function can result in data deallocation (blocking). Therefore, the acknowledgment function should NOT be called from within an interrupt context.