|
|
udi_nic_ctrl_cb_t(3udi)
Network control operation control block
#include <udi.h>typedef struct { udi_cb_t gcb; udi_ubit8_t command; udi_ubit32_t indicator; udi_buf_t *data_buf; } udi_nic_ctrl_cb_t; /* Network Control Op Control Block Group Num */#define UDI_NIC_CTRL_CB_NUM 3/* Network Control Operation Commands */#define UDI_NIC_ADD_MULTI 1 #define UDI_NIC_DEL_MULTI 2 #define UDI_NIC_ALLMULTI_ON 3 #define UDI_NIC_ALLMULTI_OFF 4 #define UDI_NIC_GET_CURR_MAC 5 #define UDI_NIC_SET_CURR_MAC 6 #define UDI_NIC_GET_FACT_MAC 7 #define UDI_NIC_PROMISC_ON 8 #define UDI_NIC_PROMISC_OFF 9 #define UDI_NIC_HW_RESET 10 #define UDI_NIC_BAD_RXPKT 11MEMBERS 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.
command is the control command the driver must execute. The following control commands have been identified:
UDI_NIC_ADD_MULTI -- Configures the multicast addresses specified in the supplied buffer. The data_buf contains the array of MAC addresses to be added to the existing filter (the number of addresses being specified is indicated by the indicator field). The remaining portion of the data_buf contains the new filter table including the newly added addresses.
Devices which can modify their address filtering simply by knowing the addresses which are to be added or removed can use the initial indicator number of addresses to modify their filter. Other devices require access to the full table of addresses to be filtered to recompute the filter and may use the latter portion of the data_buf.
Although it is possible for the network stack or user-level applications to register multiple times for a specific multicast address, the NSR is responsible for handling this redundancy; the ND is only notified of multicast address modifications when the actual received packet filter must be modified. The NSR must also validate the multicast addresses to ensure that only valid multicast addresses are passed to the ND.
The contents of the data buffer are guaranteed to be preserved across a channel for the request but not for the response.UDI_NIC_DEL_MULTI -- Removes the multicast addresses specified in the supplied buffer. In a manner similar to the UDI_NIC_ADD_MULTI operation, the initial indicator number of addresses in the data_buf lists the addresses to be removed, and the latter portion of the data_buf lists the new filter set after removing the specified addresses.
The contents of the data buffer are guaranteed to be preserved across a channel for the request but not for the response.UDI_NIC_ALLMULTI_ON -- Enables the network adapter to receive all multicast addressed packets. The indicator field is unused and the data_buf field must be NULL. This operation additionally indicates that any specific multicast addresses registered (via UDI_NIC_ADD_MULTI) must be removed.
UDI_NIC_ALLMULTI_OFF -- Disables the reception of all multicast addresses. The indicator and data_buf arguments are used in the same manner as in the UDI_NIC_ADD_MULTI operation to specify the new list of specific multicast addresses (if any) that are to be passed to the NSR.
The adapter hardware is to be returned to the standard reception mode with no multicast addresses being received unless UDI_PROMISC_ON is in effect or unless specifically registered via this operation.
The contents of the data buffer are guaranteed to be preserved across a channel for the request but not for the response.UDI_NIC_GET_CURR_MAC -- Reads the network adapter card's current physical MAC address or addresses. The array of MAC addresses is placed into the data_buf and the number of MAC addresses is placed into the indicator field in the same manner as described for the UDI_NIC_SET_CURR_MAC command. The buf_size in the data_buf divided by the indicator value should yield the same MAC address size as specified in the bind operation.
The contents of the data buffer are guaranteed to be preserved across a channel for the response but not for the request.UDI_NIC_SET_CURR_MAC -- Configures the network adapter card's current physical MAC address or addresses. A typical card will have only a single unicast MAC address, but some configurations and hardware support the registration of multiple unicast MAC addresses for a network interface. The NSR may instruct the ND to register for multiple unicast MAC addresses by specifying an array of addresses in in the associated buffer. All unicast addresses beyond the first address will be accrued against the ND's max_perfect_multicast address count limit as specified in the bind operation; the total number of multicast and unicast addresses (excluding the first) registered by the NSR must not exceed the max_perfect_multicast value. The array of MAC addresses to be set is contained in the data_buf and the number of MAC addresses is in the indicator field. The buf_size in the data_buf divided by the indicator value should yield the same MAC address size as specified in the bind operation.
The contents of the data buffer are guaranteed to be preserved across a channel for the request but not for the response.UDI_NIC_GET_FACT_MAC -- Reads the network adapter card's factory installed physical MAC address. The factory MAC address is specified as the single element array in the data_buf in the same manner as for the UDI_NIC_GET_CURR_MAC command. This is the initial MAC address used to operate the NIC until changed via UDI_NIC_SET_CURR_MAC.
The contents of the data buffer are guaranteed to be preserved across a channel for the response but not for the request.UDI_NIC_PROMISC_ON -- Enables the promiscuous mode on the network adapter card. The indicator field is unused and the data_buf field must be NULL. When promiscuous mode is enabled, the hardware should be configured such that no destination address matching is performed and all packets should be received and sent to the NSR. Error packets will still be discarded by the ND unless UDI_NIC_BAD_RXPKT is used to specify otherwise.
UDI_NIC_PROMISC_OFF -- Disables the promiscuous mode on the network adapter card. The indicator field is unused and the data_buf field must be NULL. The NSR must now be passed only unicast addresses specific to this adapter or any multicast addresses enabled by any previous UDI_NIC_ADD_MULTI or UDI_NIC_ALLMULTI_ON operations.
UDI_NIC_HW_RESET -- Resets the network adapter card. The indicator field is unused and the data_buf field must be NULL. This operation should cause the hardware to be physically reset if possible. Any operations pending on the hardware should be cancelled and cleaned up; any operations pending in the driver that have not yet been delivered to the hardware (or which have already been completed by the hardware) should be processed as normal following the reset. All other activity should be suspended during the reset operation and the driver should restore the hardware to the same operational state that it had before the reset was issued with the following exceptions: promiscuous mode is disabled, no multicast addresses are registered, the current MAC address must be reprogrammed (i.e. the factory MAC address does not override the current setting), and link status should be established if the driver's state is ENABLED or ACTIVE when this request is received.
UDI_NIC_BAD_RXPKT -- Specifies ND handling of received packets which have an error indication. If the indicator is zero, the ND must simply discard the bad packet and await the next received packet.
If non-zero, the indicator specifies how many bytes of the bad packet should be passed to the NSR (with the appropriate rx_status indication). This is intended as a hint to allow the ND to terminate or discard reception of bad packets if needed; the bad packet is not required or guaranteed by the ND to match the length field in the indicator. A receive indication with a bad packet status must be passed to the NSR even if no bytes from the received packet can be passed.
The data_buf field is unused and must be NULL.indicator is a field which supplies additional information for the control operation as specified on a per-command basis.
data_buf is the data buffer associated with the control request, e.g., the buffer containing the multicast list addresses.
DESCRIPTION The network control structure is used to configure, retrieve information or request a specific configuration action from the driver and/or the network adapter card. This structure is used with network control operations issued to the control channel.
The UDI_NIC_PROMISC_ON and UDI_NIC_ALLMULTI_ON shall be individually applied and the enabling or disabling of one shall not affect the setting of the other. The UDI_NIC_PROMISC settings do not affect the current multicast address table but the UDI_NIC_ALLMULTI_ON will delete the current list of explicit multicast addresses (which may be re-established in whole or in part by the UDI_NIC_ALLMULTI_OFF).
This control block must be declared by specifying the control block index value UDI_NIC_CTRL_CB_NUM in a udi_cb_init_t in the driver's udi_init_info.
The NSR obtains the udi_nic_ctrl_cb_t structure to use with the udi_nd_ctrl_req operation by calling udi_cb_alloc with a cb_idx that has been defined for the UDI_NIC_CTRL_CB_NUM control block.
REFERENCES udi_nd_ctrl_req, udi_init_info, udi_cb_init_t, udi_cb_alloc