25.2 NII Protocol and UNDI Implementations

Network drivers that follow the UNDI definition from the UEFI Specification are unique compared to all others peripheral drivers.

• UEFI Drivers that produce UNDI interfaces must be UEFI Runtime Drivers. This allows a UEFI operation system to potentially use the services of this UEFI Runtime Driver to provide basic network connectivity in boot scenarios where the OS driver for the network interface controller is not available.

• UNDI is not a protocol interface. The Network Interface Identifier Protocol defines the entry point to the UNDI structure, but UNDI itself is not a protocol. The Command Descriptor Block (CDB) that the caller passed into each UNDI request must provide services that allow the UNDI to access the network interface controller hardware.

• See the Universal Network Driver Interfaces appendix of the UEFI Specification for more details on UNDI adapters.

Figure 29-UEFI UNDI Network Stack

The implementation of the Network Interface Identifier Protocol is typically found in the file NiiUndi.c. Appendix A contains a template for a NiiUndi.c file for a UEFI Driver. The list of tasks to implement the Network Interface Identifier Protocol and UNDI is as follows:

• Add global variable for the EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL instance to NiiUndi.c.

• Implement the UNDI interface in NiiUndi.c.

• Create child handle in Driver Binding Protocol Start() and install the NII Protocol and the Device Path Protocol.

• Create an Exit Boot Services Event to disable DMA when packets are received.

• Create a Set Virtual Address Map Event to convert physical addresses to virtual addresses.

The following example shows the protocol interface structure for the Network Interface Identifier Protocol for reference. The Network Interface Identifier Protocol is different from many other protocols in that it has no functions inside it, and instead is only composed of data fields. These data fields share information with the platform about the network interface controller capabilities. The field called Id provides the address of a data structure for the UNDI that includes methods for the platform to call the UNDI interfaces.

Example 239-Network Interface Identifier Protocol

typedef struct _EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL
  EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL;

///
/// An optional protocol that is used to describe details about the software
/// layer that is used to produce the Simple Network Protocol.
///
struct _EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL {
  ///
  /// The revision of the EFI_NETWORK_INTERFACE_IDENTIFIER protocol.
  ///
  UINT64 Revision;
  ///
  /// The address of the first byte of the identifying structure for this network
  /// interface. This is only valid when the network interface is started
  /// (see Start()). When the network interface is not started, this field is set
  /// to zero.
  ///
  UINT64 Id;
  ///
  /// The address of the first byte of the identifying structure for this
  /// network interface. This is set to zero if there is no structure.
  ///
  UINT64 ImageAddr;
  ///
  /// The size of unrelocated network interface image.
  ///
  UINT32 ImageSize;
  ///
  /// A four-character ASCII string that is sent in the class identifier field of
  /// option 60 in DHCP. For a Type of EfiNetworkInterfaceUndi, this field is UNDI.
  ///
  CHAR8 StringId[4];
  ///
  /// Network interface type. This will be set to one of the values
  /// in EFI_NETWORK_INTERFACE_TYPE.
  ///
  UINT8 Type;
  ///
  /// Major version number.
  ///
  UINT8 MajorVer;
  ///
  /// Minor version number.
  ///
  UINT8 MinorVer;
  ///
  /// TRUE if the network interface supports IPv6; otherwise FALSE.
  ///
  BOOLEAN Ipv6Supported;
  ///
  /// The network interface number that is being identified by this Network
  /// Interface Identifier Protocol. This field must be less than or equal
  /// to the IFcnt field in the !PXE structure.
  ///
  UINT8 IfNum;
};

extern EFI_GUID gEfiNetworkInterfaceIdentifierProtocolGuid_31;

The following table shows the data structure called !PXE that resides at address specified by the Id field of the Network Interface Identifier Protocol.

Table 37-!PXE interface structure

This table shows the layout of the Command Descriptor Block (CDB) structure that is passed into the function specified by the Entry Point field of the !PXE structure.

Table 38-CDB structure

The UEFI Driver for a network interface controller that implements an UNDI must implement all the UNDI related OpCodes required by the UEFI Specification.