|
|
udi_nic_bind_cb_t(3udi)
Network bind control block
#include <udi.h>typedef struct { udi_cb_t gcb; udi_ubit8_t media_type; udi_ubit32_t min_pdu_size; udi_ubit32_t max_pdu_size; udi_ubit32_t rx_hw_threshold; udi_ubit32_t capabilities; udi_ubit8_t max_perfect_multicast; udi_ubit8_t max_total_multicast; udi_ubit8_t mac_addr_len; udi_ubit8_t mac_addr[UDI_NIC_MAC_ADDRESS_SIZE]; } udi_nic_bind_cb_t; /* Network Bind Control Block Group Number */#define UDI_NIC_BIND_CB_NUM 2/* Maximum MAC Address Size Definition */#define UDI_NIC_MAC_ADDRESS_SIZE20 /* media_type values */#define UDI_NIC_ETHER 0 #define UDI_NIC_TOKEN 1 #define UDI_NIC_FASTETHER 2 #define UDI_NIC_GIGETHER 3 #define UDI_NIC_VGANYLAN 4 #define UDI_NIC_FDDI 5 #define UDI_NIC_ATM 6 #define UDI_NIC_FC 7 #define UDI_NIC_MISCMEDIA 0xff/* capabilities indications */#define UDI_NIC_CAP_TX_IP_CKSUM (1U<<0) #define UDI_NIC_CAP_TX_TCP_CKSUM (1U<<1) #define UDI_NIC_CAP_TX_UDP_CKSUM (1U<<2) #define UDI_NIC_CAP_MCAST_LOOPBK (1U<<3) #define UDI_NIC_CAP_BCAST_LOOPBK (1U<<4)/* capabilities requests */#define UDI_NIC_CAP_USE_TX_CKSUM (1U<<30) #define UDI_NIC_CAP_USE_RX_CKSUM (1U<<31)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.
media_type is the network media type supported by the ND and associated Adapter hardware. This information is used by the NSR to parse and create frame headers for packets. Valid values for media_type are specified in Table 3-1 on page 5.
The media_type specified in this control block is expected to be the same as the media_type enumeration attribute value; where the values differ the value from this control block will be used. The same is true for the mac_addr specification.
If there is not an exact match for your media type appearing in the table, select the media type with the framing style closest to the device's network type. The media_type value suggests default values for the remaining net_bind_ack_cb_t configuration values and also hints to the NSR about handling packets for this network interface.
min_pdu_size is the minimum size of a data packet including the headers that the NSR or other modules will supply. The ND must return this information in the ack operation. If specified as 0, the default is used based on the specified media_type (as specified in Table 3-1).
max_pdu_size is the maximum size of a data packet including the headers that the NSR or other modules will supply. The ND must return this information in the ack operation. If specified as 0, the default is used based on the specified media_type.
rx_hw_threshold is the number of receive requests that may be posted to the hardware adapter at any one time. This value is used as a hint to the NSR to indicate the number of receive control blocks and buffers that should be provided to the ND for receive operations. The ND should be prepared to operate with more or less than this value but this should represent the optimal requirements of the ND and its hardware adapter.
capabilities specifies the capabilities of the Network Driver and its associated hardware. This information will be used by the NSR and protocol stacks to determine how to most effectively utilize the hardware in the current environment.
UDI_NIC_CAP_TX_IP_CKSUM indicates that the hardware is capable of automatically detecting outbound IP packets and generating and inserting IP checksum values for those packets.
UDI_NIC_CAP_TX_TCP_CKSUM indicates that the hardware is capable of automatically detecting outbound TCP packets and generating and inserting TCP checksum values for those packets.
If this capability is expressed by the ND then the NSR and corresponding IP module must ensure that: either the entire TCP packet is sent to this ND as a single IP fragment or else the NSR or IP module must calculate and insert the TCP checksum itself when the packet is fragmented. This is required because the NSR or IP module may choose to send different fragments of the request to different ND modules, therefore calculation of the TCP checksum in the ND is not possible (and many hardware adapters lack the capability of calculating a checksum across multiple fragments of a TCP packet).
The ND can assist in ensuring that the TCP packet is received in its entirety by indicating a large max_pdu_size and performing actual MTU fragmentation itself.UDI_NIC_CAP_TX_UDP_CKSUM indicates that the hardware is capable of automatically detecting outbound UDI packets and generating and inserting UDP checksum values for those packets.
UDI_NIC_CAP_MCAST_LOOPBK indicates that the hardware will receive it's own transmitted multicast packets if the multicast address matches the hardware's multicast receive addressing. The NSR should use this information to determine how multicast loopback should be handled in the environment implementation.
UDI_NIC_CAP_BCAST_LOOPBK indicates that the hardware will receive it's own transmitted broadcast packets. The NSR should use this information to determine how broadcast loopback should be handled in the environment implementation.
In addition, the NSR may request various functionality from the Network Driver. Any capabilities requests of this type are simply requests and not requirements; the ND is not required to supply the requested functionality.
UDI_NIC_CAP_USE_RX_CKSUM indicates that the NSR will utilize any receive checksum buffer tags that are attached to the buffer by the ND. This flag is primarily used to optimize performance: for an NSR which will not utilize a receive checksum buffer tag, clearing this flag will reduce overhead in the ND associated with generating this tag.
UDI_NIC_CAP_USE_TX_CKSUM indicates that the NSR will be passing packets to the ND that require checksum insertion. If the NSR or upper level protocols will always generate all checksums for transmitted packets then there will be no checksum tags on transmit buffers and the ND does not need to check for those tags. By exchanging this information at bind time, resource allocation and device initialization can be appropriately adjusted to account for checksum generation requirements
max_perfect_multicast is the maximum number of perfect multicast address matches that the Network Driver and associated hardware support. A perfect multicast address match is one which matches one and only one address (i.e. not a hashed match). This informs the NSR that there may be performance degradation if the ND is asked to match more multicast addresses than this perfect match limit.
If the NSR assigns more than one unicast address to the ND, then all unicast addresses beyond the first are also counted against the max_perfect_multicast limit to again avoid overloading the NIC hardware capabilities. In this case, #_perfect_multicast + #_unicast - 1 must be no greater than max_perfect_multicast.
max_total_multicast is the maximum number of multicast addresses that can be matched by the Network Driver and associated hardware. This is used to allow the NSR to determine how to handle situations where more multicast addresses are desired beyond hardware capabilities. The NSR must not, in any situation, issue a NIC control request that would set the total number of multicast addresses to be matched above this number.
mac_addr_len is the number of bytes to be used by the NSR for MAC addresses for this ND and overrides any default size for this media type. If specified as 0, the default MAC Address size is used based on the specified media_type.
mac_addr is the current (factory) MAC address of the adapter being managed by the ND. The current MAC address of the adapter will be written to the first mac_addr_len bytes (or the number of bytes appropriate to that media_type if mac_addr_len is zero). The MAC address must be specified as an array of 8-bit binary values; each byte must be in host bit ordering format and not wire format; the bytes in the array must be in wire-format order.
DESCRIPTION The udi_nic_bind_cb_t structure is used for the udi_nsr_bind_req and udi_nsr_bind_ack response operation between the parent (ND) and the child (NSR). This structure is "empty" on the udi_nsr_bind_req and the ND fills in the appropriate values to establish the parameters for the associated NIC Adapter for subsequent network data handling.
This control block must be declared by specifying the control block index value UDI_NIC_BIND_CB_NUM in a udi_cb_init_t in the driver's udi_init_info.
The min_pdu_size and max_pdu_size arguments must not include space for any additional headers or trailers added by the ND.
REFERENCES udi_nsr_bind_ack, udi_init_info, udi_cb_init_t, udi_cb_alloc