DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
TOC PREV NEXT INDEX

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).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:
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.

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

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.


TOC PREV NEXT INDEX