|
|
NIC Driver Requirements and Bindings
2.1 General Requirements
2.1.1 Versioning
All functions and structures defined in the UDI NIC Driver Specification are part of the "udi_nic" interface, currently at version "0x101". A driver which conforms to and uses the UDI Network Interface Metalanguage, Version 1.01, must include the following declaration in its udiprops.txt file (see Chapter 30, "Static Driver Properties", of the UDI Core Specification):
requires udi_nic 0x101In each UDI NIC driver source file, before including any UDI header files, the driver must define the preprocessor symbol, UDI_NIC_VERSION, to indicate the version of the UDI Network Interface Metalanguage to which it conforms, which must be the same as the interface version defined above.
#define UDI_NIC_VERSION 0x101A portable implementation of the Network Interface Metalanguage must include a corresponding "provides" declaration in its udiprops.txt file, must define UDI_NIC_VERSION, and must conform to the requirements specified in the Metalanguage-to-Environment (MEI) interface defined in Chapter 27, "Introduction to MEI", of the UDI Core Specification and Chapter 28, "Metalanguage-to-Environment Interface", of the UDI Core Specification.
As defined in Section 30.4.6, "Requires Declaration," on page 30-6 of the UDI Core Specification, the two least-significant digits of the interface version represent the minor number; the remaining hex digits represent the major number. Versions that have the same "major version number" as an earlier version shall be backward compatible with that earlier version (i.e., a strict superset).1
2.1.2 Header Files
Each UDI NIC driver source file must include the file "udi_nic.h" after it includes "udi.h", as follows:
#include <udi.h> #include <udi_nic.h>The "udi_nic.h" header file contains function prototypes and other definitions needed to use the UDI NIC interfaces.
2.2 NIC Metalanguage Model
The Network Interface Metalanguage is designed to support the interface between a Network Interface Card Driver (ND) and the associated network protocol stacks in the operating system. Under the UDI model, the NIC driver is primarily concerned with the management of the hardware itself, the state of the link, and with sending and receiving network packets. Management of the network address space, topology discovery, and packet composition/decomposition operations are not the responsibility of the NIC driver and are left to the network protocol stacks.
The NIC driver will bind to a single network protocol module (NSR); there is expected to be a one-to-one relationship between NIC driver instances and network protocol module instances with a single Network Interface Metalanguage binding between each pair. Any packet multiplexing/demultiplexing operations on the basis of protocol type, destination address, or other filter are the responsibility of the network protocol module and are not handled in the ND. All packets received by the NIC (subject to local address and multicast address filtering) are passed to the network protocol module for handling.
The NIC driver implements inbound and outbound flow control between itself and the protocol stack by controlling the acknowledgement and corresponding control block recycling across the NIC Metalanguage data channels. Each control block represents either a packet (received or to be transmitted) or a capability to receive or transmit a packet; when no capability is present the corresponding operation is "blocked", thereby imposing flow control characteristics on the corresponding modules.
Because the NIC Metalanguage model is based on an asynchronous as-needed operational basis none of the operations defined by this metalanguage are abortable with udi_channel_op_abort or recoverable (as described in Section 4.10.1, "Overview of Region-Kill," on page 4-6 of the UDI Core Specification).
2.3 Bindings to the UDI Core Specification
2.3.1 Instance Attributes Bindings
In each of the attribute tables below, the ATTRIBUTE NAME is a null-terminated string (see Section 15.2, "Instance Attribute Names," on page 15-1 of the UDI Core Specification); the TYPE column specifies an attribute data type as defined in udi_instance_attr_type_t; and the SIZE column specifies the valid size range, in bytes, for each attribute.
2.3.1.1 Enumeration Attributes
The UDI Network Adapter Driver enumerates network access points provided by that adapter. The following table specifies the enumeration attributes that can be specified for each network access point enumerated:
Table 2-1 NIC Enumeration Attributes ATTRIBUTE NAME TYPE SIZE Description if_num UDI_ATTR_UBIT32 4 Instance number for the media interface port relative to the other interface ports on this device. if_media UDI_ATTR_STRING 1..8 Media type string as defined in Table 2-2 on page 2-3. The size range specified includes the null-terminator identifier UDI_ATTR_STRING 1..41 String representation of the Factory MAC address of the NIC media interface port (see mac_addr in udi_nic_bind_cb_t on page 3-23), as an uppercase UDI_ATTR_ARRAY8 encoding per Table 30-1 on page 30-16 of the UDI Core Specification. The size range specified includes the null-terminator. address_locator UDI_ATTR_STRING 1..11 String representation of if_num, as an ASCII-encoded decimal string. The size range specified includes the null-terminator. physical_locator UDI_ATTR_STRING 1..11 String representation of if_num, as an ASCII-encoded decimal string. The size range specified includes the null-terminator physical_label UDI_ATTR_STRING 1..64 Driver-defined string uniquely identifying this device (optional). The following table defines the media string prefixes for the different media types to be specified in the locator attribute:
2.3.1.2 Enumeration Attribute Ranking
To support the ranking of enumerated devices against available drivers for the udi_mei_enumerate_rank_func_t, each rankable enumeration attribute is assigned a numeric ranking value; the ultimate rank returned by the ranking function is the sum of the individual attribute ranking values for all attributes which are matched in the enumeration.
The rankable enumeration attributes and their ranking values are shown in the following table:
Table 2-3 NIC Enumeration Attribute Ranking Values Enumeration Attribute Ranking Value if_num 8 if_media 16 identifier 32 physical_label 64 2.3.1.3 Filter Attributes
The if_media enumeration attribute may be used as a filter attribute. There is no range specification allowed for this filter; an exact value match must be made if this attribute is used for filtering.
2.3.1.4 Custom Attributes
The following well-known attributes must be included, if applicable, as "custom" declarations in the NIC driver's udiprops.txt static driver properties file for appropriate configuration of the target driver:
2.3.1.5 Parent-Visible Attributes
There are no defined parent-visible attributes for the Network Interface Metalanguage.
2.3.2 Trace Event Bindings
The following definitions describe usage of the trace events for the Network Interface Metalanguage and NIC Drivers. These trace events are defined in the "Trace Event Types" section of "Tracing and Logging" of the UDI Core Specification.
- UDI_TREVENT_IO_SCHEDULED
- UDI_TREVENT_META_SPECIFIC_1
- UDI_TREVENT_IO_COMPLETED
- UDI_TREVENT_META_SPECIFIC_2
2.3.3 Static Driver Property Bindings
Some of the bindings for the static driver properties are defined in Section 2.1.1, "Versioning". This includes the definition of the relevant interface name(s) (i.e., the <interface_name> parameter on the "requires" and "provides" and other property declarations), and the definition of the interface version number for this version of this specification.
The driver category to be used with the "category" declaration (see Section 30.5.3, "Category Declaration," on page 30-11 of the UDI Core Specification) by a portable implementation of the Network Interface Metalanguage Library shall be "Network Interface Cards".
2.3.4 Device Management Bindings
As described in Section 24.6.2, "Suspend," on page 24-28 of the UDI Core Specification, a driver may be suspended to allow for physical or logical device modifications or replacement. Both the ND and the NSR may queue some amount of traffic but are expected to discard data transfer operations until subsequently resumed.
2.4 NIC Metalanguage State Diagram
See "Driver Instantiation" on page 24-2 of the UDI Core Specification for the general configuration sequence of UDI drivers. See "Management Metalanguage States" on page 24-37 of the UDI Core Specification for details on the Management Metalanguage states. The following state diagram shows the Network Interface Metalanguage state diagram (from the perspective of the ND) which is the set of states specific to the Network Interface Metalanguage.
2.4.1 NIC Metalanguage States
UNBOUND A network bind channel in the unbound state has been established between the two regions but has not yet been initialized in those regions for general use. The NSR (child) side of the network bind channel should initiate the network bind operation when in this state.
BINDING This indicates that the NSR (child) side of the network bind channel has initiated a bind operation and is waiting for the ND (parent) side of the network channel to complete its initialization and acknowledge that bind request.
BOUND This indicates that the network channels are fully bound between the two regions and that they are ready for other Network Interface Metalanguage operations. In the UNBOUND or BINDING states only the Network Interface Metalanguage bind operations should be used; once the BOUND state is reached the other metalanguage operations may be used.
ENABLED This indicates that the ND has enabled the interface for I/O activity on the network. This does not necessarily indicate that the link is up.
ACTIVE This indicates that the ND has enabled the interface and that the link is up. This is the only state where it is expected that network packet transmit and receive operations will be successful.
UNBINDING This indicates that the Network channels are being shutdown. The NSR can cause this state to be entered by issuing a udi_nd_unbind_req. When the unbind operation is acknowledged then both the ND and the NSR will progress to the UNBOUND state.
1As an exception to this version compatibility, version 1.0 (0x100) is not forward compatible with any other versions bearing the major number of 1; version 1.0 of the specification cannot be wholly implemented as a functional product.