|
|
udi_nic_rx_cb_t(3udi)
Network receive control block
#include <udi.h>typedef struct { udi_cb_t gcb; udi_nic_rx_cb_t *chain; udi_buf_t *rx_buf; udi_ubit8_t rx_status; udi_ubit8_t addr_match; udi_ubit8_t rx_valid; } udi_nic_rx_cb_t; /* Network Receive Control Block Group Number */#define UDI_NIC_RX_CB_NUM 7/* values for rx_status */#define UDI_NIC_RX_BADCKSUM (1U<<0) #define UDI_NIC_RX_UNDERRUN (1U<<1) #define UDI_NIC_RX_OVERRUN (1U<<2) #define UDI_NIC_RX_DRIBBLE (1U<<3) #define UDI_NIC_RX_FRAME_ERR (1U<<4) #define UDI_NIC_RX_MAC_ERR (1U<<5) #define UDI_NIC_RX_OTHER_ERR (1U<<7)/* values for addr_match */#define UDI_NIC_RX_UNKNOWN 0 #define UDI_NIC_RX_EXACT 1 #define UDI_NIC_RX_HASH 2 #define UDI_NIC_RX_BROADCAST 3/* values for rx_valid */#define UDI_NIC_RX_GOOD_IP_CKSUM (1U<<0) #define UDI_NIC_RX_GOOD_TCP_CKSUM (1U<<1) #define UDI_NIC_RX_GOOD_UDP_CKSUM (1U<<2)MEMBERS gcb is the generic control block header which includes a pointer to the scratch space associated with this block and the channel context for the associated channel. The driver may use the scratch space while it owns the control block, but the values are not guaranteed to persist across channel operations.
chain is a pointer to the next udi_nic_rx_cb_t structure (and associated packet buffer) for this operation. The ND and NSR will use this field to "batch" a number of identical receive indications or responses into a single metalanguage operation. The ND, NSR, or environment are free to divide the chain at any point and implement explicit operations for each resulting portion of the chain, but performance concerns would indicate that processing the entire chain as a batch is highly desirable. The end of the chain is indicated by a NULL pointer.
rx_buf is the buffer containing the packet that has been received. This field is used to pass an empty buffer (rx_buf->buf_size = 0) to the ND in the udi_nd_rx_rdy operation which will be filled in with an incoming packet and returned (buffer data is preserved) with the udi_nsr_rx_ind or udi_nsr_exp_rx_ind indications.
rx_status is a bitmask indicating if there were any problems with the received packet. This field supports the following bit values:
UDI_NIC_RX_BADCKSUM - Indicates that the adapter hardware or associated driver performed checksum calculation and validation and determined that the calculated checksum value for the packet did not match one or more of the corresponding checksum values indicated internally in the packet. If this status is not indicated for the packet it only indicates that there was no specific checksum failure detected by the ND or the adapter but not that the checksums have been validated to be correct.
UDI_NIC_RX_UNDERRUN - Indicates that the packet is too short (did not meet minimum PDU size requirements) or that the reception terminated before the entire packet was received. Also known as a runt packet.
UDI_NIC_RX_OVERRUN - Indicates that the packet is too large (exceeds maximum PDU size requirements).
UDI_NIC_RX_DRIBBLE - Indicates that the frame contained a non-integer multiple of 8 bits ("dribbling" bits). The disposition of the dribbled bits is indeterminate: the hardware may or may not provide them to the ND, therefore the NSR should not examine the data for the dribble value.
UDI_NIC_RX_FRAME_ERR - Indicates that the packet had a framing error. These are technology-specific but include such causes as: incorrect frame header characters, incorrect frame trailer characters, invalid characters in the frame header or trailer, or an invalid CRC value for the frame.
UDI_NIC_RX_MAC_ERR - Indicates that the packet was damaged by a media access error. These types of errors are network specific. A typical use of this bit is for a late collision that has occured after the valid collision period for a broadcast media technology (e.g. Ethernet).
UDI_NIC_RX_OTHER_ERR - Indicates that some type of error was detected by the adapter or driver that does not fit into one of the other error classes. The ND is not expected to signal errors related to the operation of the local hardware or the driver; the rx_status field should be used only for packet or network related errors encountered during receives.
When the ND indicates a receive packet error via a non-zero rx_status value, no guarantees are made regarding whether data will be returned in the associated buffer and any data present should only be used for diagnostic purposes; under no circumstances must this data be used as part of the normal transfer operations.
addr_match is an indicator of the ND's knowledge of the MAC address match for the current packet. The ND is not required to know how the receive packet matched the set of acceptable addresses, but if a determination can easily be made from hardware registers or additional packet information, the ND can supply this information to the NSR in this field to optimize processing of the packet.
Valid values for this field are:
UDI_NIC_RX_UNKNOWN - The ND does not know how the received packet matched
UDI_NIC_RX_EXACT - The received packet exactly matched a valid unicast or multicast address for which the ND and associated adapter were registered.
UDI_NIC_RX_HASH - The received packet matched based on a hashing algorithm and the address needs to be further verified by the NSR at some point.
UDI_NIC_RX_BROADCAST - The received packet used the media broadcast address.
The addr_match field is a hint to the NSR to optimize processing of the packet, therefore the ND must never indicate any type of match that is not known to be valid (e.g. indicate an EXACT match when it was a BROADCAST). When in doubt, the ND should always use the UNKNOWN indicator.
rx_valid indicates that one or more aspects of this receive have been successfully validated:
UDI_NIC_RX_GOOD_IP_CKSUM - indicates that the IP checksum was validated and found to be correct for the received packet.
UDI_NIC_RX_GOOD_TCP_CKSUM - indicates that the TCP checksum was validated and found to be correct for the received packet.
UDI_NIC_RX_GOOD_UDP_CKSUM - indicates that the UDP checksum was validated and found to be correct for the received packet.
If the checksum value is also known, it may be attached to the buffer via the UDI_BUFTAG_BE16_CHECKSUM tag; if the NSR has indicated at bind time that the checksum will not be used (by not setting UDI_NIC_CAP_USE_RX_CKSUM) then the ND should not bother to set the tag, even if the checksum value is known.
DESCRIPTION The udi_nic_rx_cb_t structure is used to pass packets from the ND to the NSR after they have been received. They are provided to the ND via the udi_nd_rx_rdy operation.
These structures are supplied to the ND by the NSR to be attached to received packets. If the NSR has not supplied the ND with one of these control blocks to attach to a received data packet, the ND is flow-blocked and may not allocate one of these control blocks to handle the incoming data. It may save or preserve the data but it cannot pass more data to the NSR until the NSR has supplied available udi_nic_rx_cb_t structures.
This control block must be declared by specifying the control block index value UDI_NIC_RX_CB_NUM in a udi_cb_init_t in the driver's udi_init_info.
The NSR obtains the udi_nic_rx_cb_t structure by calling udi_cb_alloc with a cb_idx that has been defined for the UDI_NIC_RX_CB_NUM control block.
If the NSR uses the rx_valid field for checking the validity of the received packet, it must zero this field before passing the control block to the ND. The ND must not set these bits unless the checksum has been validated and the packet is of the appropriate type (e.g. the UDI_NIC_RX_GOOD_TCP_CKSUM bit must not be set if this is not a TCP packet). The use of this field allows performance optimizations when handling this packet; neither the ND nor the NSR is required to utilize this field.
REFERENCES udi_nsr_rx_ind, udi_nsr_exp_rx_ind, udi_nd_rx_rdy, udi_init_info, udi_cb_init_t, udi_cb_alloc