NIC Driver Requirements and Bindings

2

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 0x101
 

In 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 0x101
 

A 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).¹

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:

Table 2-2 Media Type Strings

Media Type	Media String
UDI_NIC_ETHER	"eth"
UDI_NIC_TOKEN	"tr"
UDI_NIC_FASTETHER	"fe"
UDI_NIC_GIGETHER	"ge"
UDI_NIC_VGANYLAN	"vg"
UDI_NIC_FDDI	"fddi"
UDI_NIC_ATM	"atm"
UDI_NIC_FC	"fc"
UDI_NIC_MISCMEDIA	"net"

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:

Table 2-4 NIC Custom Attributes

ATTRIBUTE NAME	TYPE	SIZE	Description
%speed_mbps	UDI_ATTR_UBIT32	4	May be used to direct the adapter to use a specific link speed in MBps. This value may be used to represent high-speed network connections; for low speeds the %speed_bps attribute should be used. For example, for Fast Ethernet this would be set to 10 or 100 for 10Mbit or 100Mbit connections, respectively. If this attribute is not set or is set to zero, the speed shall be (auto) negotiated when the link is enabled.
%speed_bps	UDI_ATTR_UBIT32	4	This value is used in the same manner that the %speed_mbps attribute is used, although this value specifies a lower range of speeds. Drivers shall ignore %speed_bps if %speed_mbps is set and non-zero.
%duplex	UDI_ATTR_STRING	1..64	Must be set to "Full", "Half", or "Auto-negotiate" (if appropriate). The size range specified includes the null-terminator. If this attribute is not set, the duplex mode shall be auto-negotiated, or-if the device does not support auto-negotiation-set to the most typical setting for the media type.
%connector	UDI_ATTR_STRING	1..64	May be used to override auto-detection of the port's cable or connector type. The list of valid values is driver-defined but might include some of the following: "BNC", "AUI", "TP", "DB-9", "Copper GBIC", etc. The size range indicated includes the null-terminator for the string.

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
  • Trace indicating a new network transmit request is being handled.
• UDI_TREVENT_META_SPECIFIC_1
  • Trace indicating a network transmit request encountered an error.
• UDI_TREVENT_IO_COMPLETED
  • Trace indicating a network packet was received and is being handled.
• UDI_TREVENT_META_SPECIFIC_2
  • Trace indicating an incoming network packet has an error.

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.

Figure 2-1 NIC Metalanguage State Diagram

Table 2-5 NIC Metalanguage Events

Event	Operation
A	udi_channel_event_ind (UDI_CHANNEL_BOUND) on NSR's parent channel
B	udi_nd_bind_req
C	udi_nsr_bind_ack
D	udi_nd_enable_req + udi_nsr_enable_ack with success
E	udi_nd_disable_req
F	udi_nsr_status_ind UDI_NIC_LINK_UP
G	udi_nsr_tx_rdy, udi_nd_tx_req, udi_nd_exp_tx_req, udi_nsr_rx_ind, udi_nsr_exp_rx_ind, udi_nd_rx_rdy
H	udi_nd_unbind_req
I	udi_nsr_unbind_ack
J	udi_nsr_status_ind UDI_NIC_LINK_DOWN or UDI_NIC_LINK_RESET
K	udi_nsr_tx_rdy, udi_nd_tx_req, udi_nd_exp_tx_req
M	udi_nsr_bind_ack with failure status

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.

Table 2-6 NIC Metalanguage: Valid Operations by State

Operation	UNBOUND	BINDING	BOUND	ENABLED	ACTIVE	UNBINDING
udi_nd_bind_req	YES	no	no	no	no	no
udi_nsr_bind_ack	no	YES	no	no	no	no
udi_nd_unbind_req	no	no	YES	YES	YES	no
udi_nsr_unbind_ack	no	no	no	no	no	YES
udi_nd_enable_req	no	no	YES	no	no	no
udi_nsr_enable_ack	no	no	no	YES	no	no
udi_nd_disable_req	no	no	no	YES	YES	no
udi_nsr_status_ind	no	no	no	YES	YES	no
udi_nd_ctrl_req	no	no	YES	YES	YES	no
udi_nsr_ctrl_ack	no	no	YES	YES	YES	no
udi_nd_info_req	no	no	YES	YES	YES	no
udi_nsr_info_ack	no	no	YES	YES	YES	no
udi_nsr_tx_rdy	no	no	no	YES	YES	no
udi_nd_tx_req	no	no	YES	YES	YES	no
udi_nd_exp_tx_req	no	no	no	YES	YES	no
udi_nsr_rx_ind	no	no	YES	no	YES	no
udi_nsr_exp_rx_ind	no	no	no	no	YES	no
udi_nd_rx_rdy	no	no	no	YES	YES	no

¹As 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.