24. Network Protocols — SNP, PXE, BIS and HTTP Boot

24.1. Simple Network Protocol

This section defines the Simple Network Protocol. This protocol provides a packet level interface to a network adapter.

24.1.1. EFI_SIMPLE_NETWORK_PROTOCOL

Summary

The EFI_SIMPLE_NETWORK_PROTOCOL provides services to initialize a network interface, transmit packets, receive packets, and close a network interface.

GUID

#define EFI_SIMPLE_NETWORK_PROTOCOL_GUID \
  {0xA19832B9,0xAC25,0x11D3,\
    {0x9A,0x2D,0x00,0x90,0x27,0x3f,0xc1,0x4d}}

Revision Number

#define EFI_SIMPLE_NETWORK_PROTOCOL_REVISION 0x00010000

Protocol Interface Structure

typedef struct \_EFI_SIMPLE_NETWORK_PROTOCOL\_ {
  UINT64                               Revision;
  EFI_SIMPLE_NETWORK_START             Start;
  EFI_SIMPLE_NETWORK_STOP              Stop;
  EFI_SIMPLE_NETWORK_INITIALIZE        Initialize;
  EFI_SIMPLE_NETWORK_RESET             Reset;
  EFI_SIMPLE_NETWORK_SHUTDOWN          Shutdown;
  EFI_SIMPLE_NETWORK_RECEIVE_FILTERS   ReceiveFilters;
  EFI_SIMPLE_NETWORK_STATION_ADDRESS   StationAddress;
  EFI_SIMPLE_NETWORK_STATISTICS        Statistics;
  EFI_SIMPLE_NETWORK_MCAST_IP_TO_MAC   MCastIpToMac;
  EFI_SIMPLE_NETWORK_NVDATA            NvData;
  EFI_SIMPLE_NETWORK_GET_STATUS        GetStatus;
  EFI_SIMPLE_NETWORK_TRANSMIT          Transmit;
  EFI_SIMPLE_NETWORK_RECEIVE           Receive;
  EFI_EVENT                            WaitForPacket;
  EFI_SIMPLE_NETWORK_MODE              *Mode;
}   EFI_SIMPLE_NETWORK_PROTOCOL;

Parameters

Revision

Revision of the EFI_SIMPLE_NETWORK_PROTOCOL. All future revisions must be backwards compatible. If a future version is not backwards compatible it is not the same GUID.

Start

Prepares the network interface for further command operations. No other EFI_SIMPLE_NETWORK_PROTOCOL interface functions will operate until this call is made. See the EFI_SIMPLE_NETWORK.Start() function description.

Stop

Stops further network interface command processing. No other EFI_SIMPLE_NETWORK_PROTOCOL interface functions will operate after this call is made until another Start() call is made. See the EFI_SIMPLE_NETWORK.Stop() function description.

Initialize

Resets the network adapter and allocates the transmit and receive buffers. See the EFI_SIMPLE_NETWORK.Initialize() function description.

Reset

Resets the network adapter and reinitializes it with the parameters provided in the previous call to Initialize() . See the EFI_SIMPLE_NETWORK.Reset() function description.

Shutdown

Resets the network adapter and leaves it in a state safe for another driver to initialize. The memory buffers assigned in the Initialize() call are released. After this call, only the Initialize() or Stop() calls may be used. See the EFI_SIMPLE_NETWORK.Shutdown() function description.

ReceiveFilters

Enables and disables the receive filters for the network interface and, if supported, manages the filtered multicast HW MAC (Hardware Media Access Control) address list. See the EFI_SIMPLE_NETWORK.ReceiveFilters() function description.

StationAddress

Modifies or resets the current station address, if supported. See the EFI_SIMPLE_NETWORK.StationAddress() function description.

Statistics

Collects statistics from the network interface and allows the statistics to be reset. See the EFI_SIMPLE_NETWORK.Statistics() function description.

MCastIpToMac

Maps a multicast IP address to a multicast HW MAC address. See the EFI_SIMPLE_NETWORK.MCastIPtoMAC() function description.

NvData

Reads and writes the contents of the NVRAM devices attached to the network interface. See the EFI_SIMPLE_NETWORK.NvData() function description.

GetStatus

Reads the current interrupt status and the list of recycled transmit buffers from the network interface. See the EFI_SIMPLE_NETWORK.GetStatus() function description.

Transmit

Places a packet in the transmit queue. See EFI_SIMPLE_NETWORK.Transmit() function description.

Receive

Retrieves a packet from the receive queue, along with the status flags that describe the packet type. See the EFI_SIMPLE_NETWORK.Receive() function description.

WaitForPacket

Event used with EFI_BOOT_SERVICES.WaitForEvent() to wait for a packet to be received.

Mode

Pointer to the EFI_SIMPLE_NETWORK_MODE data for the device. See “Related Definitions” below.

Related Definitions

//******************************************************
// EFI_SIMPLE_NETWORK_MODE
//
// Note that the fields in this data structure are read-only
// and are updated by the code that produces the
// EFI_SIMPLE_NETWORK_PROTOCOL
// functions. All these fields must be discovered
// in a protocol instance of
// EFI_DRIVER_BINDING_PROTOCOL.Start().
//******************************************************
typedef struct {
  UINT32             State;
  UINT32             HwAddressSize;
  UINT32             MediaHeaderSize;
  UINT32             MaxPacketSize;
  UINT32             NvRamSize;
  UINT32             NvRamAccessSize;
  UINT32             ReceiveFilterMask;
  UINT32             ReceiveFilterSetting;
  UINT32             MaxMCastFilterCount;
  UINT32             MCastFilterCount;
  EFI_MAC_ADDRESS    MCastFilter[MAX_MCAST_FILTER_CNT];
  EFI_MAC_ADDRESS    CurrentAddress;
  EFI_MAC_ADDRESS    BroadcastAddress;
  EFI_MAC_ADDRESS    PermanentAddress;
  UINT8              IfType;
  BOOLEAN            MacAddressChangeable;
  BOOLEAN            MultipleTxSupported;
  BOOLEAN            MediaPresentSupported;
  BOOLEAN            MediaPresent;
}   EFI_SIMPLE_NETWORK_MODE;
State

Reports the current state of the network interface (see EFI_SIMPLE_NETWORK_STATE WORK_STATE below). When an EFI_SIMPLE_NETWORK_PROTOCOL driver initializes a network interface, the network interface is left in the EfiSimpleNetworkStopped state.

HwAddressSize

The size, in bytes, of the network interface’s HW address.

MediaHeaderSize

The size, in bytes, of the network interface’s media header.

MaxPacketSize

The maximum size, in bytes, of the packets supported by the network interface.

NvRamSize

The size, in bytes, of the NVRAM device attached to the network interface. If an NVRAM device is not attached to the network interface, then this field will be zero. This value must be a multiple of NvramAccessSize.

NvRamAccessSize

The size that must be used for all NVRAM reads and writes. The start address for NVRAM read and write operations and the total length of those operations, must be a multiple of this value. The legal values for this field are 0, 1, 2, 4, and 8. If the value is zero, then no NVRAM devices are attached to the network interface.

ReceiveFilterMask

The multicast receive filter settings supported by the network interface.

ReceiveFilterSetting

The current multicast receive filter settings. See “Bit Mask Values for ReceiveFilterSetting ” below.

MaxMCastFilterCount

The maximum number of multicast address receive filters supported by the driver. If this value is zero, then ReceiveFilters() cannot modify the multicast address receive filters. This field may be less than MAX_MCAST_FILTER_CNT (see below).

MCastFilterCount

The current number of multicast address receive filters.

MCastFilter

Array containing the addresses of the current multicast address receive filters.

CurrentAddress

The current HW MAC address for the network interface.

BroadcastAddress

The current HW MAC address for broadcast packets.

PermanentAddress

The permanent HW MAC address for the network interface.

IfType

The interface type of the network interface. See RFC 3232, section “Number Hardware Type.”

MacAddressChangeable

TRUE if the HW MAC address can be changed.

MultipleTxSupported

TRUE if the network interface can transmit more than one packet at a time.

MediaPresentSupported

TRUE if the presence of media can be determined; otherwise FALSE. If FALSE, MediaPresent cannot be used.

MediaPresent

TRUE if media are connected to the network interface; othrwise FALSE. This field shows the media present status as of the most recent GetStatus() call.

//*******************************************************
// EFI_SIMPLE_NETWORK_STATE
//*******************************************************
typedef enum {
EfiSimpleNetworkStopped,
EfiSimpleNetworkStarted,
EfiSimpleNetworkInitialized,
EfiSimpleNetworkMaxState
} EFI_SIMPLE_NETWORK_STATE;

//*******************************************************
// MAX_MCAST_FILTER_CNT
//*******************************************************
#define MAX_MCAST_FILTER_CNT                             16

//*******************************************************
// Bit Mask Values for ReceiveFilterSetting.
//
// Note that all other bit values are reserved.
//*******************************************************
#define EFI_SIMPLE_NETWORK_RECEIVE_UNICAST               0x01
#define EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST             0x02
#define EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST             0x04
#define EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS           0x08
#define EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST 0x10

Description

The EFI_SIMPLE_NETWORK_PROTOCOL protocol is used to initialize access to a network adapter. Once the network adapter initializes, the EFI_SIMPLE_NETWORK_PROTOCOL protocol provides services that allow packets to be transmitted and received. This provides a packet level interface that can then be used by higher level drivers to produce boot services like DHCP, TFTP, and MTFTP. In addition, this protocol can be used as a building block in a full UDP and TCP/IP implementation that can produce a wide variety of application level network interfaces. See the Preboot Execution Environment (PXE) Specification for more information.

NOTE The underlying network hardware may only be able to access 4 GiB (32-bits) of system memory. Any requests to transfer data to/from memory above 4 GiB with 32-bit network hardware will be double-buffered (using intermediate buffers below 4 GiB) and will reduce performance.

NOTE The same handle can have an instance of the EFI_ADAPTER_INFORMATION_PROTOCOL with a EFI_ADAPTER_INFO_MEDIA_STATE type structure.

24.1.2. EFI_SIMPLE_NETWORK.Start()

Summary

Changes the state of a network interface from “stopped” to “started.”

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_START) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL    *This
    );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

Description

This function starts a network interface. If the network interface successfully starts, then EFI_SUCCESS will be returned.

Status Codes Returned

EFI_SUCCESS

The network interface was started.

EFI_ALREADY_STARTED

The network interface is already in the started state.

EFI_INVALID_PARAMETER

This parameter was NULL or did not point to a valid EFI_SIMPLE_NETWORK_PROTOCOL structure.

EFI_DEVICE_ERROR

The command could not be sent to the network interface.

EFI_UNSUPPORTED

This function is not supported by the network interface.

24.1.3. EFI_SIMPLE_NETWORK.Stop()

Summary

Changes the state of a network interface from “started” to “stopped.”

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_STOP) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL      *This
  );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

Description

This function stops a network interface. This call is only valid if the network interface is in the started state. If the network interface was successfully stopped, then EFI_SUCCESS will be returned.

Status Codes Returned

EFI_SUCCESS

The network interface was stopped.

EFI_NOT_STARTED

The network interface has not been started.

EFI_INVALID_PARAMETER

This parameter was NULL or did not point to a valid EFI_SIMPLE_NETWORK_PROTOCOL structure.

EFI_DEVICE_ERROR

The command could not be sent to the network interface.

EFI_UNSUPPORTED

This function is not supported by the network interface.

24.1.4. EFI_SIMPLE_NETWORK.Initialize()

Summary

Resets a network adapter and allocates the transmit and receive buffers required by the network interface; optionally, also requests allocation of additional transmit and receive buffers.

Prototype

typedef
  EFI_STATUS
  (EFIAPI *EFI_SIMPLE_NETWORK_INITIALIZE) (
    IN EFI_SIMPLE_NETWORK_PROTOCOL        *This,
    IN UINTN                              ExtraRxBufferSize OPTIONAL,
    IN UINTN                              ExtraTxBufferSize OPTIONAL
    );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

ExtraRxBufferSize

The size, in bytes, of the extra receive buffer space that the driver should allocate for the network interface. Some network interfaces will not be able to use the extra buffer, and the caller will not know if it is actually being used.

ExtraTxBufferSize

The size, in bytes, of the extra transmit buffer space that the driver should allocate for the network interface. Some network interfaces will not be able to use the extra buffer, and the caller will not know if it is actually being used.

Description

This function allocates the transmit and receive buffers required by the network interface. If this allocation fails, then EFI_OUT_OF_RESOURCES is returned. If the allocation succeeds and the network interface is successfully initialized, then EFI_SUCCESS will be returned.

Status Codes Returned

EFI_SUCCESS

The network interface was initialized.

EFI_NOT_STARTED

The network interface has not been started.

EFI_OUT_OF_RESOURCES

There was not enough memory for the transmit and receive buffers.

EFI_INVALID_PARAMETER

This parameter was NULL or did not point to a valid EFI_SIMPLE_NETWORK_PROTOCOL structure.

EFI_DEVICE_ERROR

The command could not be sent to the network interface.

EFI_UNSUPPORTED

The increased buffer size feature is not supported.

24.1.5. EFI_SIMPLE_NETWORK.Reset()

Summary

Resets a network adapter and reinitializes it with the parameters that were provided in the previous call to EFI_SIMPLE_NETWORK.Initialize().

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_RESET) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL    *This,
  IN BOOLEAN                        ExtendedVerification
  );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

ExtendedVerification

Indicates that the driver may perform a more exhaustive verification operation of the device during reset.

Description

This function resets a network adapter and reinitializes it with the parameters that were provided in the previous call to Initialize(). The transmit and receive queues are emptied and all pending interrupts are cleared. Receive filters, the station address, the statistics, and the multicast-IP-to-HW MAC addresses are not reset by this call. If the network interface was successfully reset, then EFI_SUCCESS will be returned. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.

Status Codes Returned

EFI_SUCCESS

The network interface was reset.

EFI_NOT_STARTED

The network interface has not been started.

EFI_INVALID_PARAMETER

One or more of the parameters has an unsupported value.

EFI_DEVICE_ERROR

The command could not be sent to the network interface.

EFI_UNSUPPORTED

This function is not supported by the network interface.

24.1.6. EFI_SIMPLE_NETWORK.Shutdown()

Summary

Resets a network adapter and leaves it in a state that is safe for another driver to initialize.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_SHUTDOWN) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL       *This
  );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

Description

This function releases the memory buffers assigned in the EFI_SIMPLE_NETWORK.Initialize() call. Pending transmits and receives are lost, and interrupts are cleared and disabled. After this call, only the Initialize() and EFI_SIMPLE_NETWORK.Stop() calls may be used. If the network interface was successfully shutdown, then EFI_SUCCESS will be returned. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.

Status Codes Returned

EFI_SUCCESS

The network interface was shutdown.

EFI_NOT_STARTED

The network interface has not been started.

EFI_INVALID_PARAMETER

This parameter was NULL or did not point to a valid EFI_SIMPLE_NETWORK_PROTOCOL structure.

EFI_DEVICE_ERROR

The command could not be sent to the network interface.

24.1.7. EFI_SIMPLE_NETWORK.ReceiveFilters()

Summary

Manages the multicast receive filters of a network interface.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_RECEIVE_FILTERS) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL       *This,
  IN UINT32                            Enable,
  IN UINT32                            Disable,
  IN BOOLEAN                           ResetMCastFilter,
  IN UINTN                             MCastFilterCnt OPTIONAL,
  IN EFI_MAC_ADDRESS                   MCastFilter OPTIONAL,
  );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

Enable

A bit mask of receive filters to enable on the network interface.

Disable

A bit mask of receive filters to disable on the network interface. For backward compatibility with EFI 1.1 platforms, the EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST bit must be set when the ResetMCastFilter parameter is TRUE.

ResetMCastFilter

Set to TRUE to reset the contents of the multicast receive filters on the network interface to their default values.

MCastFilterCnt

Number of multicast HW MAC addresses in the new MCastFilter list. This value must be less than or equal to the MCastFilterCnt field of EFI_SIMPLE_NETWORK_MODE. This field is optional if ResetMCastFilter is TRUE.

MCastFilter

A pointer to a list of new multicast receive filter HW MAC addresses. This list will replace any existing multicast HW MAC address list. This field is optional if ResetMCastFilter is TRUE.

Description

This function is used enable and disable the hardware and software receive filters for the underlying network device.

The receive filter change is broken down into three steps:

  • The filter mask bits that are set (ON) in the Enable parameter are added to the current receive filter settings.

  • The filter mask bits that are set (ON) in the Disable parameter are subtracted from the updated receive filter settings.

  • If the resulting receive filter setting is not supported by the hardware a more liberal setting is selected.

If the same bits are set in the Enable and Disable parameters, then the bits in the Disable parameter takes precedence.

If the ResetMCastFilter parameter is TRUE, then the multicast address list filter is disabled (irregardless of what other multicast bits are set in the Enable and Disable parameters). The SNP->Mode->MCastFilterCount field is set to zero. The Snp->Mode->MCastFilter contents are undefined.

After enabling or disabling receive filter settings, software should verify the new settings by checking the Snp->Mode->ReceiveFilterSettings, Snp->Mode->MCastFilterCount and Snp->Mode->MCastFilter fields.

Note: Some network drivers and/or devices will automatically promote receive filter settings if the requested setting can not be honored. For example, if a request for four multicast addresses is made and the underlying hardware only supports two multicast addresses the driver might set the promiscuous or promiscuous multicast receive filters instead. The receiving software is responsible for discarding any extra packets that get through the hardware receive filters.

Note: To disable all receive filter hardware, the network driver must be Shutdown() and Stopped(). Calling ReceiveFilters() with Disable set to Snp->Mode->ReceiveFilterSettings will make it so no more packets are returned by the Receive() function, but the receive hardware may still be moving packets into system memory before inspecting and discarding them. Unexpected system errors, reboots and hangs can occur if an OS is loaded and the network devices are not Shutdown() and Stopped().

If ResetMCastFilter is TRUE, then the multicast receive filter list on the network interface will be reset to the default multicast receive filter list. If ResetMCastFilter is FALSE, and this network interface allows the multicast receive filter list to be modified, then the MCastFilterCnt and MCastFilter are used to update the current multicast receive filter list. The modified receive filter list settings can be found in the MCastFilter field of EFI_SIMPLE_NETWORK_MODE in Network Protocols — SNP, PXE, BIS and HTTP Boot. If the network interface does not allow the multicast receive filter list to be modified, then EFI_INVALID_PARAMETER will be returned. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.

If the receive filter mask and multicast receive filter list have been successfully updated on the network interface, EFI_SUCCESS will be returned.

Status Codes Returned

EFI_SUCCESS

The multicast receive filter list was updated.

EFI_NOT_STARTED

The network interface has not been started.

EFI_INVALID_PARAMETER

• One or more of the following conditions is TRUE :
This is NULL
• There are bits set in Enable that are not set in Snp->Mode->ReceiveFilterMask
• There are bits set in Disable that are not set in Snp->Mode->ReceiveFilterMask
• Multicast is being enabled (the EFI _SIMPLE_NETWORK_RECEIVE_MULTICAST bit is set in Enable, it is not set in Disable, and ResetMCastFilter is FALSE ) and MCastFilterCount is zero
• Multicast is being enabled and MCastFilterCount is greater than
Snp->Mode->MaxMCastFilterCount
• Multicast is being enabled and MCastFilter is NULL
• Multicast is being enabled and one or more of the addresses in the MCastFilter list are not valid multicast MAC addresses

EFI_DEVICE_ERROR

• One or more of the following conditions is TRUE :
• The network interface has been started but has not been initialized
• An unexpected error was returned by the underlying network driver or device

EFI_UNSUPPORTED

This function is not supported by the network interface.

24.1.8. EFI_SIMPLE_NETWORK.StationAddress()

Summary

Modifies or resets the current station address, if supported.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_STATION_ADDRESS) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL       *This,
  IN BOOLEAN                           Reset,
  IN EFI_MAC_ADDRESS                   *New OPTIONAL
  );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

Reset

Flag used to reset the station address to the network interface’s permanent address.

New

New station address to be used for the network interface.

Description

This function modifies or resets the current station address of a network interface, if supported. If Reset is TRUE, then the current station address is set to the network interface’s permanent address. If Reset is FALSE, and the network interface allows its station address to be modified, then the current station address is changed to the address specified by New. If the network interface does not allow its station address to be modified, then EFI_INVALID_PARAMETER will be returned. If the station address is successfully updated on the network interface, EFI_SUCCESS will be returned. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.

Status Codes Returned

EFI_SUCCESS

The network interface’s station address was updated.

EFI_NOT_STARTED

The Simple Network Protocol interface has not been started by calling Start().

EFI_INVALID_PARAMETER

The New station address was not accepted by the NIC.

EFI_INVALID_PARAMETER

Reset is FALSE and New is NULL.

EFI_DEVICE_ERROR

The Simple Network Protocol interface has not been initialized by calling Initialize().

EFI_DEVICE_ERROR

An error occurred attempting to set the new station address.

EFI_UNSUPPORTED

The NIC does not support changing the network interface’s station address.

24.1.9. EFI_SIMPLE_NETWORK.Statistics()

Summary

Resets or collects the statistics on a network interface.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_STATISTICS) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL       *This,
  IN BOOLEAN                           Reset,
  IN OUT UINTN                         *StatisticsSize OPTIONAL,
  OUT EFI_NETWORK_STATISTICS           *StatisticsTable OPTIONAL
  );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

Reset

Set to TRUE to reset the statistics for the network interface.

StatisticsSize

On input the size, in bytes, of StatisticsTable. On output the size, in bytes, of the resulting table of statistics.

StatisticsTable

A pointer to the EFI_NETWORK_STATISTICS in Network Protocols — SNP, PXE, BIS and HTTP Boot structure that contains the statistics. Type EFI_NETWORK_STATISTICS is defined in “Related Definitions” below.

Related Definitions

//*******************************************************
// EFI_NETWORK_STATISTICS
//
// Any statistic value that is -1 is not available
// on the device and is to be ignored.
//*******************************************************
typedef struct {
  UINT64     RxTotalFrames;
  UINT64     RxGoodFrames;
  UINT64     RxUndersizeFrames;
  UINT64     RxOversizeFrames;
  UINT64     RxDroppedFrames;
  UINT64     RxUnicastFrames;
  UINT64     RxBroadcastFrames;
  UINT64     RxMulticastFrames;
  UINT64     RxCrcErrorFrames;
  UINT64     RxTotalBytes;
  UINT64     TxTotalFrames;
  UINT64     TxGoodFrames;
  UINT64     TxUndersizeFrames;
  UINT64     TxOversizeFrames;
  UINT64     TxDroppedFrames;
  UINT64     TxUnicastFrames;
  UINT64     TxBroadcastFrames;
  UINT64     TxMulticastFrames;
  UINT64     TxCrcErrorFrames;
  UINT64     TxTotalBytes;
  UINT64     Collisions;
  UINT64     UnsupportedProtocol;
  UINT64     RxDuplicatedFrames;
  UINT64     RxDecryptErrorFrames;
  UINT64     TxErrorFrames;
  UINT64     TxRetryFrames;
}   EFI_NETWORK_STATISTICS;
RxTotalFrames

Total number of frames received. Includes frames with errors and dropped frames.

RxGoodFrames

Number of valid frames received and copied into receive buffers.

RxUndersizeFrames

Number of frames below the minimum length for the communications device.

RxOversizeFrames

Number of frames longer than the maximum length for the communications device.

RxDroppedFrames

Valid frames that were dropped because receive buffers were full.

RxUnicastFrames

Number of valid unicast frames received and not dropped.

RxBroadcastFrames

Number of valid broadcast frames received and not dropped.

RxMulticastFrames

Number of valid multicast frames received and not dropped.

RxCrcErrorFrames

Number of frames with CRC or alignment errors.

RxTotalBytes

Total number of bytes received. Includes frames with errors and dropped frames.

TxTotalFrames

Total number of frames transmitted. Includes frames with errors and dropped frames.

TxGoodFrames

Number of valid frames transmitted and copied into receive buffers.

TxUndersizeFrames

Number of frames below the minimum length for the media. This would be less than 64 for Ethernet.

TxOversizeFrames

Number of frames longer than the maximum length for the media. This would be greater than 1500 for Ethernet.

TxDroppedFrames

Valid frames that were dropped because receive buffers were full.

TxUnicastFrames

Number of valid unicast frames transmitted and not dropped.

TxBroadcastFrames

Number of valid broadcast frames transmitted and not dropped.

TxMulticastFrames

Number of valid multicast frames transmitted and not dropped.

TxCrcErrorFrames

Number of frames with CRC or alignment errors.

TxTotalBytes

Total number of bytes transmitted. Includes frames with errors and dropped frames.

Collisions

Number of collisions detected on this subnet.

UnsupportedProtocol

Number of frames destined for unsupported protocol.

RxDuplicatedFrames

Number of valid frames received that were duplicated.

RxDecryptErrorFrames

Number of encrypted frames received that failed to decrypt.

TxErrorFrames

Number of frames that failed to transmit after exceeding the retry limit.

TxRetryFrames

Number of frames transmitted successfully after more than one attempt.

Description

This function resets or collects the statistics on a network interface. If the size of the statistics table specified by StatisticsSize is not big enough for all the statistics that are collected by the network interface, then a partial buffer of statistics is returned in StatisticsTable, StatisticsSize is set to the size required to collect all the available statistics, and EFI_BUFFER_TOO_SMALL is returned.

If StatisticsSize is big enough for all the statistics, then StatisticsTable will be filled, StatisticsSize will be set to the size of the returned StatisticsTable structure, and EFI_SUCCESS is returned. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.

If Reset is FALSE, and both StatisticsSize and StatisticsTable are NULL, then no operations will be performed, and EFI_SUCCESS will be returned.

If Reset is TRUE, then all of the supported statistics counters on this network interface will be reset to zero.

Status Codes Returned

EFI_SUCCESS

The requested operation succeeded.

EFI_NOT_STARTED

The Simple Network Protocol interface has not been started by calling Start().

EFI_BUFFER_TOO_SMALL

StatisticsSize is not NULL and StatisticsTable is NULL. The current buffer size that is needed to hold all the statistics is returned in StatisticsSize.

EFI_BUFFER_TOO_SMALL

StatisticsSize is not NULL and StatisticsTable is not NULL. The current buffer size that is needed to hold all the statistics is returned in StatisticsSize. A partial set of statistics is returned in StatisticsTable.

EFI_INVALID_PARAMETER

StatisticsSize is NULL and StatisticsTable is not NULL.

EFI_DEVICE_ERROR

The Simple Network Protocol interface has not been initialized by calling Initialize().

EFI_DEVICE_ERROR

An error was encountered collecting statistics from the NIC.

EFI_UNSUPPORTED

The NIC does not support collecting statistics from the network interface.

24.1.10. EFI_SIMPLE_NETWORK.MCastIPtoMAC()

Summary

Converts a multicast IP address to a multicast HW MAC address.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_MCAST_IP_TO_MAC) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL       *This,
  IN BOOLEAN                           IPv6,
  IN EFI_IP_ADDRESS                    *IP,
  OUT EFI_MAC_ADDRESS                  *MAC
  );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

IPv6

Set to TRUE if the multicast IP address is IPv6 [RFC 2460]. Set to FALSE if the multicast IP address is IPv4 [RFC 791].

IP

The multicast IP address that is to be converted to a multicast HW MAC address.

MAC

The multicast HW MAC address that is to be generated from IP.

Description

This function converts a multicast IP address to a multicast HW MAC address for all packet transactions. If the mapping is accepted, then EFI_SUCCESS will be returned.

Status Codes Returned

EFI_SUCCESS

The multicast IP address was mapped to the multicast HW MAC address.

EFI_NOT_STARTED

The Simple Network Protocol interface has not been started by calling Start().

EFI_INVALID_PARAMETER

IP is NULL.

EFI_INVALID_PARAMETER

MAC is NULL.

EFI_INVALID_PARAMETER

IP does not point to a valid IPv4 or IPv6 multicast address.

EFI_DEVICE_ERROR

The Simple Network Protocol interface has not been initialized by calling Initialize().

EFI_UNSUPPORTED

IPv6 is TRUE and the implementation does not support IPv6 multicast to MAC address conversion.

24.1.11. EFI_SIMPLE_NETWORK.NvData()

Summary

Performs read and write operations on the NVRAM device attached to a network interface.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_NVDATA) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL    *This
  IN BOOLEAN                        ReadWrite,
  IN UINTN                          Offset,
  IN UINTN                          BufferSize,
  IN OUT VOID                       *Buffer
  );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

ReadWrite

TRUE for read operations, FALSE for write operations.

Offset

Byte offset in the NVRAM device at which to start the read or write operation. This must be a multiple of NvRamAccessSize and less than NvRamSize. (See EFI_SIMPLE_NETWORK_MODE in Network Protocols — SNP, PXE, BIS and HTTP Boot .

BufferSize

The number of bytes to read or write from the NVRAM device. This must also be a multiple of 2.

Buffer

A pointer to the data buffer.

Description

This function performs read and write operations on the NVRAM device attached to a network interface. If ReadWrite is TRUE, a read operation is performed. If ReadWrite is FALSE, a write operation is performed.

Offset specifies the byte offset at which to start either operation. Offset must be a multiple of NvRamAccessSize, and it must have a value between zero and NvRamSize.

BufferSize specifies the length of the read or write operation. BufferSize must also be a multiple of NvRamAccessSize, and Offset + BufferSize must not exceed NvRamSize.

If any of the above conditions is not met, then EFI_INVALID_PARAMETER will be returned.

If all the conditions are met and the operation is “read,” the NVRAM device attached to the network interface will be read into Buffer and EFI_SUCCESS will be returned. If this is a write operation, the contents of Buffer will be used to update the contents of the NVRAM device attached to the network interface and EFI_SUCCESS will be returned.

Status Codes Returned

EFI_SUCCESS

The NVRAM access was performed.

EFI_NOT_STARTED

The network interface has not been started.

EFI_INVALID_PARAMETER

One or more of the following conditions is TRUE :
• The This parameter is NULL
• The This parameter does not point to a valid EFI_SIMPLE_NETWORK_PROTOCOL structure
• The Offset parameter is not a multiple of EFI_SIMPLE_NETWORK_MODE. NvRamAccessSize
• The Offset parameter is not less than EFI_SIMPLE_NETWORK_MODE. NvRamSize
• The BufferSize parameter is not a multiple of EFI_SIMPLE_NETWORK_MODE. NvRamAccessSize
The Buffer parameter is NULL

EFI_DEVICE_ERROR

The command could not be sent to the network interface.

EFI_UNSUPPORTED

This function is not supported by the network interface.

24.1.12. EFI_SIMPLE_NETWORK.GetStatus()

Summary

Reads the current interrupt status and recycled transmit buffer status from a network interface.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_GET_STATUS) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL       *This,
  OUT UINT32                           *InterruptStatus OPTIONAL,
  OUT VOID                             **TxBuf OPTIONAL
  );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

InterruptStatus

A pointer to the bit mask of the currently active interrupts (see “Related Definitions”). If this is NULL, the interrupt status will not be read from the device. If this is not NULL, the interrupt status will be read from the device. When the interrupt status is read, it will also be cleared. Clearing the transmit interrupt does not empty the recycled transmit buffer array.

TxBuf

Recycled transmit buffer address. The network interface will not transmit if its internal recycled transmit buffer array is full. Reading the transmit buffer does not clear the transmit interrupt. If this is NULL, then the transmit buffer status will not be read. If there are no transmit buffers to recycle and TxBuf is not NULL, * TxBuf will be set to NULL.

Related Definitions

//*******************************************************
// Interrupt Bit Mask Settings for InterruptStatus.
// Note that all other bit values are reserved.
//*******************************************************
#define EFI_SIMPLE_NETWORK_RECEIVE_INTERRUPT    0x01
#define EFI_SIMPLE_NETWORK_TRANSMIT_INTERRUPT   0x02
#define EFI_SIMPLE_NETWORK_COMMAND_INTERRUPT    0x04
#define EFI_SIMPLE_NETWORK_SOFTWARE_INTERRUPT   0x08

Description

This function gets the current interrupt and recycled transmit buffer status from the network interface. The interrupt status is returned as a bit mask in InterruptStatus. If InterruptStatus is NULL, the interrupt status will not be read. Upon successful return of the media status, the MediaPresent field of EFI_SIMPLE_NETWORK_MODE will be updated to reflect any change of media status.Upon successful return of the media status, the MediaPresent field of EFI_SIMPLE_NETWORK_MODE will be updated to reflect any change of media status. If TxBuf is not NULL, a recycled transmit buffer address will be retrieved. If a recycled transmit buffer address is returned in TxBuf, then the buffer has been successfully transmitted, and the status for that buffer is cleared. If the status of the network interface is successfully collected, EFI_SUCCESS will be returned. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.

Status Codes Returned

EFI_SUCCESS

The status of the network interface was retrieved.

EFI_NOT_STARTED

The network interface has not been started.

EFI_INVALID_PARAMETER

This parameter was NULL or did not point to a valid EFI_SIMPLE_NETWORK_PROTOCOL structure.

EFI_DEVICE_ERROR

The command could not be sent to the network interface.

24.1.13. EFI_SIMPLE_NETWORK.Transmit()

Summary

Places a packet in the transmit queue of a network interface.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_TRANSMIT) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL       *This
  IN UINTN                             HeaderSize,
  IN UINTN                             BufferSize,
  IN VOID                              *Buffer,
  IN EFI_MAC_ADDRESS                   *SrcAddr OPTIONAL,
  IN EFI_MAC_ADDRESS                   *DestAddr OPTIONAL,
  IN UINT16                            *Protocol OPTIONAL,
  );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

HeaderSize

The size, in bytes, of the media header to be filled in by the Transmit() function. If HeaderSize is nonzero, then it must be equal to This->Mode->MediaHeaderSize and the DestAddr and Protocol parameters must not be NULL.

BufferSize

The size, in bytes, of the entire packet (media header and data) to be transmitted through the network interface.

Buffer

A pointer to the packet (media header followed by data) to be transmitted. This parameter cannot be NULL. If HeaderSize is zero, then the media header in Buffer must already be filled in by the caller. If HeaderSize is nonzero, then the media header will be filled in by the Transmit() function.

SrcAddr

The source HW MAC address. If HeaderSize is zero, then this parameter is ignored. If HeaderSize is nonzero and SrcAddr is NULL, then This->Mode->CurrentAddress is used for the source HW MAC address.

DestAddr

The destination HW MAC address. If HeaderSize is zero, then this parameter is ignored.

Protocol

The type of header to build. If HeaderSize is zero, then this parameter is ignored. See RFC 3232, section “Ether Types,” for examples.

Description

This function places the packet specified by Header and Buffer on the transmit queue. If HeaderSize is nonzero and HeaderSize is not equal to This->Mode->MediaHeaderSize, then EFI_INVALID_PARAMETER will be returned. If BufferSize is less than This->Mode->MediaHeaderSize, then EFI_BUFFER_TOO_SMALL will be returned. If Buffer is NULL, then EFI_INVALID_PARAMETER will be returned. If HeaderSize is nonzero and DestAddr or Protocol is NULL, then EFI_INVALID_PARAMETER will be returned. If the transmit engine of the network interface is busy, then EFI_NOT_READY will be returned. If this packet can be accepted by the transmit engine of the network interface, the packet contents specified by Buffer will be placed on the transmit queue of the network interface, and EFI_SUCCESS will be returned. EFI_SIMPLE_NETWORK.GetStatus() can be used to determine when the packet has actually been transmitted. The contents of the Buffer must not be modified until the packet has actually been transmitted.

The Transmit() function performs nonblocking I/O. A caller who wants to perform blocking I/O, should call Transmit(), and then GetStatus() until the transmitted buffer shows up in the recycled transmit buffer.

If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.

Status Codes Returned

EFI_SUCCESS

The packet was placed on the transmit queue.

EFI_NOT_STARTED

The network interface has not been started.

EFI_NOT_READY

The network interface is too busy to accept this transmit request.

EFI_BUFFER_TOO_SMALL

The BufferSize parameter is too small.

EFI_INVALID_PARAMETER

One or more of the parameters has an unsupported value.

EFI_DEVICE_ERROR

The command could not be sent to the network interface.

EFI_UNSUPPORTED

This function is not supported by the network interface.

24.1.14. EFI_SIMPLE_NETWORK.Receive()

Summary

Receives a packet from a network interface.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIMPLE_NETWORK_RECEIVE) (
  IN EFI_SIMPLE_NETWORK_PROTOCOL       *This
  OUT  UINTN                           *HeaderSize OPTIONAL,
  IN OUT UINTN                         *BufferSize,
  OUT  VOID                            *Buffer,
  OUT  EFI_MAC_ADDRESS                 *SrcAddr OPTIONAL,
  OUT  EFI_MAC_ADDRESS                 *DestAddr OPTIONAL,
  OUT  UINT16                          *Protocol OPTIONAL
  );

Parameters

This

A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.

HeaderSize

The size, in bytes, of the media header received on the network interface. If this parameter is NULL, then the media header size will not be returned.

BufferSize

On entry, the size, in bytes, of Buffer. On exit, the size, in bytes, of the packet that was received on the network interface.

Buffer

A pointer to the data buffer to receive both the media header and the data.

SrcAddr

The source HW MAC address. If this parameter is NULL, the HW MAC source address will not be extracted from the media header.

DestAddr

The destination HW MAC address. If this parameter is NULL, the HW MAC destination address will not be extracted from the media header.

Protocol

The media header type. If this parameter is NULL, then the protocol will not be extracted from the media header. See RFC 1700 section “Ether Types” for examples.

Description

This function retrieves one packet from the receive queue of a network interface. If there are no packets on the receive queue, then EFI_NOT_READY will be returned. If there is a packet on the receive queue, and the size of the packet is smaller than BufferSize, then the contents of the packet will be placed in Buffer, and BufferSize will be updated with the actual size of the packet. In addition, if SrcAddr, DestAddr, and Protocol are not NULL, then these values will be extracted from the media header and returned. EFI_SUCCESS will be returned if a packet was successfully received. If BufferSize is smaller than the received packet, then the size of the receive packet will be placed in BufferSize and EFI_BUFFER_TOO_SMALL will be returned. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.

Status Codes Returned

EFI_SUCCESS

The received data was stored in Buffer, and BufferSize has been updated to the number of bytes received.

EFI_NOT_STARTED

The network interface has not been started.

EFI_NOT_READY

No packets have been received on the network interface.

EFI_BUFFER_TOO_SMALL

BufferSize is too small for the received packets. BufferSize has been updated to the required size.

EFI_INVALID_PARAMETER

One or more of the following conditions is TRUE :
• The This parameter is NULL
• The This parameter does not point to a valid EFI_SIMPLE_NETWORK_PROTOCOL structure.
• The BufferSize parameter is NULL
• The Buffer parameter is NULL

EFI_DEVICE_ERROR

The command could not be sent to the network interface.

24.2. Network Interface Identifier Protocol

This is an optional protocol that is used to describe details about the software layer that is used to produce the Simple Network Protocol. This protocol is only required if the underlying network interface is 16-bit UNDI, 32/64-bit S/W UNDI, or H/W UNDI. It is used to obtain type and revision information about the underlying network interface.

An instance of the Network Interface Identifier protocol must be created for each physical external network interface that is controlled by the !PXE structure. The !PXE structure is defined in the 32/64-bit UNDI Specification in Appendix E.

24.2.1. EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL

Summary

An optional protocol that is used to describe details about the software layer that is used to produce the Simple Network Protocol.

GUID

#define EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL_GUID_31 \
  {0x1ACED566, 0x76ED, 0x4218,\
    {0xBC, 0x81, 0x76, 0x7F, 0x1F, 0x97, 0x7A, 0x89}}

Revision Number

#define EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL_REVISION \ 0x00020000

Protocol Interface Structure

typedef struct {
  UINT64       Revision;
  UINT64       Id;
  UINT64       ImageAddr;
  UINT32       ImageSize;
  CHAR8        StringId[4];
  UINT8        Type;
  UINT8        MajorVer;
  UINT8        MinorVer;
  BOOLEAN      Ipv6Supported;
  UINT16       IfNum;
} EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL;

Parameters

Revision

The revision of the EFI_NETWORK_INTERFACE_IDENTIFIER protocol.

Id

Address of the first byte of the identifying structure for this network interface. This is only valid when the network interface is started (see EFI_SIMPLE_NETWORK.Start() ). When the network interface is not started, this field is set to zero.

16-bit UNDI and 32/64-bit S/W UNDI:

Id contains the address of the first byte of the copy of the !PXE structure in the relocated UNDI code segment. See the Preboot Execution Environment (PXE) Specification and Appendix E.

H/W UNDI:

Id contains the address of the !PXE structure.

ImageAddr

Address of the unrelocated network interface image.

16-bit UNDI:

ImageAddr is the address of the PXE option ROM image in upper memory.

32/64-bit S/W UNDI:

ImageAddr is the address of the unrelocated S/W UNDI image.

H/W UNDI:

ImageAddr contains zero.

ImageSize

Size of unrelocated network interface image.

16-bit UNDI:

ImageSize is the size of the PXE option ROM image in upper memory.

32/64-bit S/W UNDI:

ImageSize is the size of the unrelocated S/W UNDI image.

H/W UNDI:

ImageSize contains zero.

StringId

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.”

Type

Network interface type. This will be set to one of the values in EFI_NETWORK_INTERFACE_TYPE (see “Related Definitions” below).

MajorVer

Major version number.

16-bit UNDI:

MajorVer comes from the third byte of the UNDIRev field in the UNDI ROM ID structure. Refer to the Preboot Execution Environment (PXE) Specification.

32/64-bit S/W UNDI and H/W UNDI:

MajorVer comes from the Major field in the !PXE structure. See Appendix E.

MinorVer

Minor version number.

16-bit UNDI:

MinorVer comes from the second byte of the UNDIRev field in the UNDI ROM ID structure. Refer to the Preboot Execution Environment (PXE) Specification.

32/64-bit S/W UNDI and H/W UNDI:

MinorVer comes from the Minor field in the !PXE structure. See Appendix E.

Ipv6Supported

TRUE if the network interface supports IPv6; otherwise FALSE.

IfNum

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 | IFcntExt <<8 ) field in the !PXE structure.

Related Definitions

//*******************************************************
// EFI_NETWORK_INTERFACE_TYPE
//*******************************************************
typedef enum {
EfiNetworkInterfaceUndi = 1
} EFI_NETWORK_INTERFACE_TYPE;

Description

The EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL is used by EFI_PXE_BASE_CODE_PROTOCOL and OS loaders to identify the type of the underlying network interface and to locate its initial entry point.

24.3. PXE Base Code Protocol

This section defines the Preboot Execution Environment (PXE) Base Code protocol, which is used to access PXE-compatible devices for network access and network booting. For more information about PXE, see “Links to UEFI-Related Documents” ( http://uefi.org/uefi) under the heading “Preboot Execution Environment (PXE) Specification”.

24.3.1. EFI_PXE_BASE_CODE_PROTOCOL

Summary

The EFI_PXE_BASE_CODE_PROTOCOL is used to control PXE-compatible devices. The features of these devices are defined in the Preboot Execution Environment (PXE) Specification. An EFI_PXE_BASE_CODE_PROTOCOL will be layered on top of an EFI_MANAGED_NETWORK_PROTOCOL protocol in order to perform packet level transactions. The EFI_PXE_BASE_CODE_PROTOCOL handle also supports the See EFI_LOAD_FILE_PROTOCOL protocol. This provides a clean way to obtain control from the boot manager if the boot path is from the remote device.

GUID

#define EFI_PXE_BASE_CODE_PROTOCOL_GUID \
  {0x03C4E603,0xAC28,0x11d3,\
    {0x9A,0x2D,0x00,0x90,0x27,0x3F,0xC1,0x4D}}

Revision Number

#define EFI_PXE_BASE_CODE_PROTOCOL_REVISION 0x00010000

Protocol Interface Structure

typedef struct {
  UINT64                            Revision;
  EFI_PXE_BASE_CODE_START           Start;
  EFI_PXE_BASE_CODE_STOP            Stop;
  EFI_PXE_BASE_CODE_DHCP            Dhcp;
  EFI_PXE_BASE_CODE_DISCOVER        Discover;
  EFI_PXE_BASE_CODE_MTFTP           Mtftp;
  EFI_PXE_BASE_CODE_UDP_WRITE       UdpWrite;
  EFI_PXE_BASE_CODE_UDP_READ        UdpRead;
  EFI_PXE_BASE_CODE_SET_IP_FILTER   SetIpFilter;
  EFI_PXE_BASE_CODE_ARP             Arp;
  EFI_PXE_BASE_CODE_SET_PARAMETERS  SetParameters;
  EFI_PXE_BASE_CODE_SET_STATION_IP  SetStationIp;
  EFI_PXE_BASE_CODE_SET_PACKETS     SetPackets;
  EFI_PXE_BASE_CODE_MODE            *Mode;
}   EFI_PXE_BASE_CODE_PROTOCOL;

Parameters

Revision

The revision of the EFI_PXE_BASE_CODE_PROTOCOL. All future revisions must be backwards compatible. If a future version is not backwards compatible it is not the same GUID.

Start

Starts the PXE Base Code Protocol. Mode structure information is not valid and no other Base Code Protocol functions will operate until the Base Code is started. See the EFI_PXE_BASE_CODE_PROTOCOL.Start() function description.

Stop

Stops the PXE Base Code Protocol. Mode structure information is unchanged by this function. No Base Code Protocol functions will operate until the Base Code is restarted. See the EFI_PXE_BASE_CODE_PROTOCOL.Stop() function description.

Dhcp

Attempts to complete a DHCPv4 D.O.R.A. (discover / offer / request / acknowledge) or DHCPv6 S.A.R.R (solicit / advertise / request / reply) sequence. See the EFI_PXE_BASE_CODE_PROTOCOL.Dhcp() function description.

Discover

Attempts to complete the PXE Boot Server and/or boot image discovery sequence. See the EFI_PXE_BASE_CODE_PROTOCOL.Discover() function description.

Mtftp

Performs TFTP and MTFTP services. See the EFI_PXE_BASE_CODE_PROTOCOL.Mtftp() function description.

UdpWrite

Writes a UDP packet to the network interface. See the EFI_PXE_BASE_CODE_PROTOCOL.UdpWrite() function description.

UdpRead

Reads a UDP packet from the network interface. See the EFI_PXE_BASE_CODE_PROTOCOL.UdpRead() function description.

SetIpFilter

Updates the IP receive filters of the network device. See the EFI_PXE_BASE_CODE_PROTOCOL.SetIpFilter() function description.

Arp

Uses the ARP protocol to resolve a MAC address. See the EFI_PXE_BASE_CODE_PROTOCOL.Arp() function description.

SetParameters

Updates the parameters that affect the operation of the PXE Base Code Protocol. See the EFI_PXE_BASE_CODE_PROTOCOL.SetParameters() function description.

SetStationIp

Updates the station IP address and subnet mask values. See the EFI_PXE_BASE_CODE_PROTOCOL.SetStationIp() function description.

SetPackets

Updates the contents of the cached DHCP and Discover packets. See the EFI_PXE_BASE_CODE_PROTOCOL.SetPackets() function description.

Mode

Pointer to the EFI_PXE_BASE_CODE_MODE for this device. The EFI_PXE_BASE_CODE_MODE structure is defined in “Related Definitions” below.

Related Definitions

//*******************************************************
// Maximum ARP and Route Entries
//*******************************************************
#define EFI_PXE_BASE_CODE_MAX_ARP\_ENTRIES 8
#define EFI_PXE_BASE_CODE_MAX_ROUTE_ENTRIES 8

//*******************************************************
// EFI_PXE_BASE_CODE_MODE
//
// The data values in this structure are read-only and
// are updated by the code that produces the
// EFI_PXE_BASE_CODE_PROTOCOLfunctions.
*********************************************************
typedef struct {
  BOOLEAN            Started;
  BOOLEAN            Ipv6Available;
  BOOLEAN            Ipv6Supported;
  BOOLEAN            UsingIpv6;
  BOOLEAN            BisSupported;
  BOOLEAN            BisDetected;
  BOOLEAN            AutoArp;
  BOOLEAN            SendGUID;
  BOOLEAN            DhcpDiscoverValid;
  BOOLEAN            DhcpAckReceivd;
  BOOLEAN            ProxyOfferReceived;
  BOOLEAN            PxeDiscoverValid;
  BOOLEAN            PxeReplyReceived;
  BOOLEAN            PxeBisReplyReceived;
  BOOLEAN            IcmpErrorReceived;
  BOOLEAN            TftpErrorReceived;
  BOOLEAN            MakeCallbacks;
  UINT8              TTL;
  UINT8              ToS;
  EFI_IP_ADDRESS                 StationIp;
  EFI_IP_ADDRESS                 SubnetMask;
  EFI_PXE_BASE_CODE_PACKET       DhcpDiscover;
  EFI_PXE_BASE_CODE_PACKET       DhcpAck;
  EFI_PXE_BASE_CODE_PACKET       ProxyOffer;
  EFI_PXE_BASE_CODE_PACKET       PxeDiscover;
  EFI_PXE_BASE_CODE_PACKET       PxeReply;
  EFI_PXE_BASE_CODE_PACKET       PxeBisReply;
  EFI_PXE_BASE_CODE_IP_FILTER    IpFilter;
  UINT32                         ArpCacheEntries;
  EFI_PXE_BASE_CODE_ARP\_ENTRY   ArpCache[EFI_PXE_BASE_CODE_MAX_ARP_ENTRIES];
  UINT32                         RouteTableEntries;
  EFI_PXE_BASE_CODE_ROUTE_ENTRY  RouteTable[EFI_PXE_BASE_CODE_MAX_ROUTE_ENTRIES];
  EFI_PXE_BASE_CODE_ICMP_ERROR   IcmpError;
  EFI_PXE_BASE_CODE_TFTP_ERROR   TftpError;
}   EFI_PXE_BASE_CODE_MODE;
Started

TRUE if this device has been started by calling EFI_PXE_BASE_CODE_PROTOCOL.Start() . This field is set to TRUE by the Start() function and to FALSE by the EFI_PXE_BASE_CODE_PROTOCOL.Stop() function.

Ipv6Available

TRUE if the UNDI protocol supports IPv6.

Ipv6Supported

TRUE if this PXE Base Code Protocol implementation supports IPv6.

UsingIpv6

TRUE if this device is currently using IPv6. This field is set by the Start() function.

BisSupported

TRUE if this PXE Base Code implementation supports Boot Integrity Services (BIS). This field is set by the Start() function.

BisDetected

TRUE if this device and the platform support Boot Integrity Services (BIS). This field is set by the Start() function.

AutoArp

TRUE for automatic ARP packet generation; FALSE otherwise. This field is initialized to TRUE by Start() and can be modified with the EFI_PXE_BASE_CODE_PROTOCOL.SetParameters() function.

SendGUID

This field is used to change the Client Hardware Address (chaddr) field in the DHCP and Discovery packets. Set to TRUE to send the SystemGuid (if one is available). Set to FALSE to send the client NIC MAC address. This field is initialized to FALSE by Start() and can be modified with the SetParameters() function.

DhcpDiscoverValid

This field is initialized to FALSE by the Start() function and set to TRUE when the EFI_PXE_BASE_CODE_PROTOCOL.Dhcp() function completes successfully. When TRUE, the DhcpDiscover field is valid. This field can also be changed by the EFI_PXE_BASE_CODE_PROTOCOL.SetPackets() function.

DhcpAckReceived

This field is initialized to FALSE by the EFI_PXE_BASE_CODE_PROTOCOL.Start() function and set to TRUE when the EFI_PXE_BASE_CODE_PROTOCOL.Dhcp() function completes successfully. When TRUE, the DhcpAck field is valid. This field can also be changed by the EFI_PXE_BASE_CODE_PROTOCOL.SetPackets() function.

ProxyOfferReceived

This field is initialized to FALSE by the Start() function and set to TRUE when the Dhcp() function completes successfully and a proxy DHCP offer packet was received. When TRUE, the ProxyOffer packet field is valid. This field can also be changed by the SetPackets() function.

PxeDiscoverValid

When TRUE, the PxeDiscover packet field is valid. This field is set to FALSE by the Start() and Dhcp() functions, and can be set to TRUE or FALSE by the EFI_PXE_BASE_CODE_PROTOCOL.Discover() and SetPackets() functions.

PxeReplyReceived

When TRUE, the PxeReply packet field is valid. This field is set to FALSE by the Start() and Dhcp() functions, and can be set to TRUE or FALSE by the Discover() and SetPackets() functions.

PxeBisReplyReceived

When TRUE, the PxeBisReply packet field is valid. This field is set to FALSE by the Start() and Dhcp() functions, and can be set to TRUE or FALSE by the Discover() and SetPackets() functions.

IcmpErrorReceived

Indicates whether the IcmpError field has been updated. This field is reset to FALSE by the Start(), Dhcp(), Discover(), EFI_PXE_BASE_CODE_PROTOCOL.Mtftp() , EFI_PXE_BASE_CODE_PROTOCOL.UdpRead() , EFI_PXE_BASE_CODE_PROTOCOL.UdpWrite() and EFI_PXE_BASE_CODE_PROTOCOL.Arp() functions. If an ICMP error is received, this field will be set to TRUE after the IcmpError field is updated.

TftpErrorReceived

Indicates whether the TftpError field has been updated. This field is reset to FALSE by the Start() and Mtftp() functions. If a TFTP error is received, this field will be set to TRUE after the TftpError field is updated.

MakeCallbacks

When FALSE, callbacks will not be made. When TRUE, make callbacks to the PXE Base Code Callback Protocol. This field is reset to FALSE by the Start() function if the PXE Base Code Callback Protocol is not available. It is reset to TRUE by the Start() function if the PXE Base Code Callback Protocol is available.

TTL

The “time to live” field of the IP header. This field is initialized to DEFAULT_TTL (See “Related Definitions”) by the Start() function and can be modified by the EFI_PXE_BASE_CODE_PROTOCOL.SetParameters() function.

ToS

The type of service field of the IP header. This field is initialized to DEFAULT_ToS (See “Related Definitions”) by EFI_PXE_BASE_CODE_PROTOCOL.Start() , and can be modified with the EFI_PXE_BASE_CODE_PROTOCOL.SetParameters() function.

StationIp

The device’s current IP address. This field is initialized to a zero address by Start(). This field is set when the EFI_PXE_BASE_CODE_PROTOCOL.Dhcp() function completes successfully. This field can also be set by the EFI_PXE_BASE_CODE_PROTOCOL.SetStationIp() function. This field must be set to a valid IP address by either Dhcp() or SetStationIp() before the EFI_PXE_BASE_CODE_PROTOCOL.Discover() , EFI_PXE_BASE_CODE_PROTOCOL.Mtftp() , EFI_PXE_BASE_CODE_PROTOCOL.UdpRead() , EFI_PXE_BASE_CODE_PROTOCOL.UdpWrite() and EFI_PXE_BASE_CODE_PROTOCOL.Arp() functions are called.

SubnetMask

The device’s current subnet mask. This field is initialized to a zero address by the Start() function. This field is set when the Dhcp() function completes successfully. This field can also be set by the SetStationIp() function. This field must be set to a valid subnet mask by either Dhcp() or SetStationIp() before the Discover(), Mtftp(), UdpRead(), UdpWrite(), or Arp() functions are called.

DhcpDiscover

Cached DHCP Discover packet. This field is zero-filled by the Start() function, and is set when the Dhcp() function completes successfully. The contents of this field can replaced by the EFI_PXE_BASE_CODE_PROTOCOL.SetPackets() function.

DhcpAck

Cached DHCP Ack packet. This field is zero-filled by the Start() function, and is set when the Dhcp() function completes successfully. The contents of this field can be replaced by the SetPackets() function.

ProxyOffer

Cached Proxy Offer packet. This field is zero-filled by the Start() function, and is set when the Dhcp() function completes successfully. The contents of this field can be replaced by the SetPackets() function.

PxeDiscover

Cached PXE Discover packet. This field is zero-filled by the Start() function, and is set when the Discover() function completes successfully. The contents of this field can be replaced by the SetPackets() function.

PxeReply

Cached PXE Reply packet. This field is zero-filled by the Start() function, and is set when the Discover() function completes successfully. The contents of this field can be replaced by the SetPackets() function.

PxeBisReply

Cached PXE BIS Reply packet. This field is zero-filled by the Start() function, and is set when the Discover() function completes successfully. This field can be replaced by the SetPackets() function.

IpFilter

The current IP receive filter settings. The receive filter is disabled and the number of IP receive filters is set to zero by the EFI_PXE_BASE_CODE_PROTOCOL.Start() function, and is set by the EFI_PXE_BASE_CODE_PROTOCOL.SetIpFilter() function.

ArpCacheEntries

The number of valid entries in the ARP cache. This field is reset to zero by the Start() function.

ArpCache

Array of cached ARP entries.

RouteTableEntries

The number of valid entries in the current route table. This field is reset to zero by the Start() function.

RouteTable

Array of route table entries.

IcmpError

ICMP error packet. This field is updated when an ICMP error is received and is undefined until the first ICMP error is received. This field is zero-filled by the Start() function.

TftpError

TFTP error packet. This field is updated when a TFTP error is received and is undefined until the first TFTP error is received. This field is zero-filled by the Start() function.

//*******************************************************
// EFI_PXE_BASE_CODE_UDP_PORT
//*******************************************************
typedef UINT16 EFI_PXE_BASE_CODE_UDP_PORT;

//*******************************************************
// EFI_IPv4_ADDRESS and EFI_IPv6_ADDRESS
//*******************************************************
typedef struct {
  UINT8             Addr[4];
} EFI_IPv4_ADDRESS;

typedef struct {
  UINT8             Addr[16];
}   EFI_IPv6_ADDRESS;

//*******************************************************
// EFI_IP_ADDRESS
//*******************************************************
typedef union {
  UINT32            Addr[4];
  EFI_IPv4_ADDRESS  v4;
  EFI_IPv6_ADDRESS  v6;
}   EFI_IP_ADDRESS;

//******************************************************
// EFI_MAC_ADDRESS
//*******************************************************
typedef struct {
  UINT8             Addr[32];
} EFI_MAC_ADDRESS;

24.3.2. DHCP Packet Data Types

This section defines the data types for DHCP packets, ICMP error packets, and TFTP error packets. All of these are byte-packed data structures.

NOTE: All the multibyte fields in these structures are stored in network order.

//*******************************************************
// EFI_PXE_BASE_CODE_DHCPV4_PACKET
//*******************************************************
typedef struct {
  UINT8            BootpOpcode;
  UINT8            BootpHwType;
  UINT8            BootpHwAddrLen;
  UINT8            BootpGateHops;
  UINT32           BootpIdent;
  UINT16           BootpSeconds;
  UINT16           BootpFlags;
  UINT8            BootpCiAddr[4];
  UINT8            BootpYiAddr[4];
  UINT8            BootpSiAddr[4];
  UINT8            BootpGiAddr[4];
  UINT8            BootpHwAddr[16];
  UINT8            BootpSrvName[64];
  UINT8            BootpBootFile[128];
  UINT32           DhcpMagik;
  UINT8 DhcpOptions[56];
} EFI_PXE_BASE_CODE_DHCPV4_PACKET;

//***********************************************
// DHCPV6 Packet structure
//***********************************************
typedef struct {
  UINT32           MessageType:8;
  UINT32           TransactionId:24;
  UINT8            DhcpOptions[1024];
}   EFI_PXE_BASE_CODE_DHCPV6_PACKET;

//*******************************************************
// EFI_PXE_BASE_CODE_PACKET
//*******************************************************
typedef union {
  UINT8                            Raw[1472];
  EFI_PXE_BASE_CODE_DHCPV4_PACKET  Dhcpv4;
  EFI_PXE_BASE_CODE_DHCPV6_PACKET  Dhcpv6;
}   EFI_PXE_BASE_CODE_PACKET;

//*******************************************************
// EFI_PXE_BASE_CODE_ICMP_ERROR
//*******************************************************
typedef struct {
  UINT8                            Type;
  UINT8                            Code;
  UINT16                           Checksum;
  union {
    UINT32                         reserved;
    UINT32                         Mtu;
    UINT32                         Pointer;
    struct {
      UINT16                       Identifier;
      UINT16                       Sequence;
      }                            Echo;
     }                             u;
   UINT8                           Data[494];
}   EFI_PXE_BASE_CODE_ICMP_ERROR;

//*******************************************************
// EFI_PXE_BASE_CODE_TFTP_ERROR
//*******************************************************
typedef struct {
  UINT8                            ErrorCode;
  CHAR8                            ErrorString[127];
}   EFI_PXE_BASE_CODE_TFTP_ERROR;

24.3.3. IP Receive Filter Settings

This section defines the data types for IP receive filter settings.

#define EFI_PXE_BASE_CODE_MAX_IPCNT8

//*******************************************************
// EFI_PXE_BASE_CODE_IP_FILTER
//*******************************************************
typedef struct {
  UINT8                              Filters;
  UINT8                              IpCnt;
  UINT16                             reserved;
  EFI_IP_ADDRESS                     IpList[EFI_PXE_BASE_CODE_MAX_IPCNT];
}   EFI_PXE_BASE_CODE_IP_FILTER;

#define EFI_PXE_BASE_CODE_IP_FILTER_STATION_IP             0x0001
#define EFI_PXE_BASE_CODE_IP_FILTER_BROADCAST              0x0002
#define EFI_PXE_BASE_CODE_IP_FILTER_PROMISCUOUS            0x0004
#define EFI_PXE_BASE_CODE_IP_FILTER_PROMISCUOUS_MULTICAST  0x0008

24.3.4. ARP Cache Entries

This section defines the data types for ARP cache entries, and route table entries.

//*******************************************************
// EFI_PXE_BASE_CODE_ARP\_ENTRY
//*******************************************************
typedef struct {
  EFI_IP_ADDRESS                 IpAddr;
  EFI_MAC_ADDRESS                MacAddr;
}   EFI_PXE_BASE_CODE_ARP\_ENTRY;

//*******************************************************
// EFI_PXE_BASE_CODE_ROUTE_ENTRY
//*******************************************************
typedef struct {
  EFI_IP_ADDRESS                 IpAddr;
  EFI_IP_ADDRESS                 SubnetMask;
  EFI_IP_ADDRESS                 GwAddr;
}   EFI_PXE_BASE_CODE_ROUTE_ENTRY;

24.3.5. Filter Operations for UDP Read/Write Functions

This section defines the types of filter operations that can be used with the EFI_PXE_BASE_CODE_PROTOCOL.UdpRead() and EFI_PXE_BASE_CODE_PROTOCOL.UdpWrite() functions.

#define EFI_PXE_BASE_CODE_UDP_OPFLAGS_ANY_SRC_IP         0x0001
#define EFI_PXE_BASE_CODE_UDP_OPFLAGS_ANY_SRC_PORT       0x0002
#define EFI_PXE_BASE_CODE_UDP_OPFLAGS_ANY_DEST_IP        0x0004
#define EFI_PXE_BASE_CODE_UDP_OPFLAGS_ANY_DEST_PORT      0x0008
#define EFI_PXE_BASE_CODE_UDP_OPFLAGS_USE_FILTER         0x0010
#define EFI_PXE_BASE_CODE_UDP_OPFLAGS_MAY_FRAGMENT       0x0020
#define DEFAULT_TTL                                      16
#define DEFAULT_ToS                                      0

The following table defines values for the PXE DHCP and Bootserver Discover packet tags that are specific to the UEFI environment. Complete definitions of all PXE tags are defined in the Table below, “PXE DHCP Options (Full List),” in the PXE Specification.

Table 24.1 PXE Tag Definitions for EFI

Tag Name

Tag #

Length

Data Field

Client Network Interface Identifier

94 [0x5E]

3 [0x03]

Type (1), MajorVer (1), MinorVer (1)
Type is a one byte field that identifies the network interface that will be used by the downloaded program. Type is followed by two one byte version number fields, MajorVer and MinorVer.
Type
UNDI (1) = 0x01
Versions
16-bit UNDI: MajorVer = 0x02. MinorVer = 0x00
PXE-2.0 16-bit UNDI: MajorVer = 0x02, MinorVer = 0x01
32/64-bit UNDI & H/W UNDI: MajorVer = 0x03, MinorVer = 0x00

Client System Architecture

93 [0x5D]

2 [0x02]

Type (2)
Type is a two byte, network order, field that identifies the processor and programming environment of the client system.
For the various architecture type encodings, see the table “Processor Architecture Types” at “Links to UEFI-Related Documents” (http:// uefi.org/uefi) under the heading “Processor Architecture Types”

Class Identifier

60 [0x3C]

32 [0x20]

“PXE Client:Arch:xxx xx:UNDI:yyyzzz”
“PXEClient:…” is used to identify communication between PXE clients and servers. Information from tags 93 & 94 is embedded in the Class Identifier string. (The strings defined in this tag are case sensitive and must not be NU LL-terminated.)
xxxxx = ASCII representation of Client System Architecture.
yyyzzz = ASCII representation of Client Network Interface Identifier
version numbers MajorVer(yyy) and MinorVer(zzz).
Example
“PX EClient:Arch:00 002:UNDI:00300” identifies an IA64 PC w/ 32/64-bit UNDI

Description

The basic mechanisms and flow for remote booting in UEFI are identical to the remote boot functionality described in detail in the PXE Specification. However, the actual execution environment, linkage, and calling conventions are replaced and enhanced for the UEFI environment.

The DHCP Option for the Client System Architecture is used to inform the DHCP server if the client is a UEFI environment in supported systems. The server may use this information to provide default images if it does not have a specific boot profile for the client.

The DHCP Option for Client Network Interface Identifier is used to inform the DHCP server of the client underlying network interface information. If the NII protocol is present, such information will be acquired by this protocol. Otherwise, Type = 0x01, MajorVer=0x03, MinorVer=0x00 will be the default value.

A handle that supports EFI_PXE_BASE_CODE_PROTOCOL is required to support EFI_LOAD_FILE_PROTOCOL . The EFI_LOAD_FILE_PROTOCOL function is used by the firmware to load files from devices that do not support file system type accesses. Specifically, the firmware’s boot manager invokes LoadFile() with BootPolicy being TRUE when attempting to boot from the device. The firmware then loads and transfers control to the downloaded PXE boot image. Once the remote image is successfully loaded, it may utilize the EFI_PXE_BASE_CODE_PROTOCOL interfaces, or even the EFI_SIMPLE_NETWORK_PROTOCOL interfaces, to continue the remote process.

24.3.6. EFI_PXE_BASE_CODE_PROTOCOL.Start()

Summary

Enables the use of the PXE Base Code Protocol functions.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_START) (
  IN EFI_PXE_BASE_CODE_PROTOCOL        *This,
  IN BOOLEAN                           UseIpv6
  );

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

UseIpv6

Specifies the type of IP addresses that are to be used during the session that is being started. Set to TRUE for IPv6 addresses, and FALSE for IPv4 addresses.

Description

This function enables the use of the PXE Base Code Protocol functions. If the Started field of the EFI_PXE_BASE_CODE_MODE structure is already TRUE, then EFI_ALREADY_STARTED will be returned. If UseIpv6 is TRUE, then IPv6 formatted addresses will be used in this session. If UseIpv6 is FALSE, then IPv4 formatted addresses will be used in this session. If UseIpv6 is TRUE, and the Ipv6Supported field of the EFI_PXE_BASE_CODE_MODE structure is FALSE, then EFI_UNSUPPORTED will be returned. If there is not enough memory or other resources to start the PXE Base Code Protocol, then EFI_OUT_OF_RESOURCES will be returned. Otherwise, the PXE Base Code Protocol will be started, and all of the fields of the EFI_PXE_BASE_CODE_MODE structure will be initialized as follows:

Started              Set to TRUE.
Ipv6Supported        Unchanged.
Ipv6Available        Unchanged.
UsingIpv6            Set to *UseIpv6*.
BisSupported         Unchanged.
BisDetected          Unchanged.
AutoArp              Set to TRUE.
SendGUID             Set to FALSE.
TTL                  Set to DEFAULT_TTL.
ToS                  Set to DEFAULT_ToS.
DhcpCompleted        Set to FALSE.
ProxyOfferReceived   Set to FALSE.
StationIp            Set to an address of all zeros.
SubnetMask           Set to a subnet mask of all zeros.
DhcpDiscover         Zero-filled.
DhcpAck              Zero-filled.
ProxyOffer           Zero-filled.
PxeDiscoverValid     Set to FALSE.
PxeDiscover          Zero-filled.
PxeReplyValid        Set to FALSE.
PxeReply             Zero-filled.
PxeBisReplyValid     Set to FALSE.
PxeBisReply          Zero-filled.
IpFilter             Set the *Filters* field to 0 and the *IpCnt* field to 0.
ArpCacheEntries      Set to 0.
ArpCache             Zero-filled.
RouteTableEntries    Set to 0.
RouteTable           Zero-filled.
IcmpErrorReceived    Set to FALSE.
IcmpError            Zero-filled.
TftpErroReceived     Set to FALSE.
TftpError            Zero-filled.
MakeCallback         Set to TRUE if the PXE Base Code Callback Protocol is
                     available. Set to FALSE if the PXE Base Code Callback
                     Protocol is not available.

Status Codes Returned

EFI_SUCCESS

The PXE Base Code Protocol was started.

EFI_INVALID_PARAMETER

The This parameter is NULL or does not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure.

EFI_UNSUPPORTED

UseIpv6 is TRUE, but the Ipv6Supported field of the EFI_PX E_BASE_CODE_MODE structure is FALSE.

EFI_ALREADY_STARTED

The PXE Base Code Protocol is already in the started state.

EFI_DEVICE_ERROR

The network device encountered an error during this operation.

EFI_OUT_OF_RESOURCES

Could not allocate enough memory or other resources to start the PXE Base Code Protocol.

24.3.7. EFI_PXE_BASE_CODE_PROTOCOL.Stop()

Summary

Disables the use of the PXE Base Code Protocol functions.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_STOP) (
  IN EFI_PXE_BASE_CODE_PROTOCOL     *This
  );

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

Description

This function stops all activity on the network device. All the resources allocated in EFI_PXE_BASE_CODE_PROTOCOL.Start() are released, the Started field of the EFI_PXE_BASE_CODE_MODE structure is set to FALSE and EFI_SUCCESS is returned. If the Started field of the EFI_PXE_BASE_CODE_MODE structure is already FALSE, then EFI_NOT_STARTED will be returned.

Status Codes Returned

EFI_SUCCESS

The PXE Base Code Protocol was stopped.

EFI_NOT_STARTED

The PXE Base Code Protocol is already in the stopped state.

EFI_INVALID_PARAMETER

The This parameter is NULL or does not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure.

EFI_DEVICE_ERROR

The network device encountered an error during this operation.

24.3.8. EFI_PXE_BASE_CODE_PROTOCOL.Dhcp()

Summary

Attempts to complete a DHCPv4 D.O.R.A. (discover / offer / request / acknowledge) or DHCPv6 S.A.R.R (solicit / advertise / request / reply) sequence.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_DHCP) (
  IN EFI_PXE_BASE_CODE_PROTOCOL     *This,
  IN BOOLEAN                        SortOffers
  );

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

SortOffers

TRUE if the offers received should be sorted. Set to FALSE to try the offers in the order that they are received.

Description

This function attempts to complete the DHCP sequence. If this sequence is completed, then EFI_SUCCESS is returned, and the DhcpCompleted, ProxyOfferReceived, StationIp, SubnetMask, DhcpDiscover, DhcpAck, and ProxyOffer fields of the EFI_PXE_BASE_CODE_MODE structure are filled in.

If SortOffers is TRUE, then the cached DHCP offer packets will be sorted before they are tried. If SortOffers is FALSE, then the cached DHCP offer packets will be tried in the order in which they are received. Please see the Preboot Execution Environment (PXE) Specification for additional details on the implementation of DHCP.

This function can take at least 31 seconds to timeout and return control to the caller. If the DHCP sequence does not complete, then EFI_TIMEOUT will be returned.

If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then the DHCP sequence will be stopped and EFI_ABORTED will be returned.

Status Codes Returned

EFI_SUCCESS

Valid DHCP has completed.

EFI_NOT_STARTED

The PXE Base Code Protocol is in the stopped state.

EFI_INVALID_PARAMETER

The This parameter is NULL or does not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure.

EFI_DEVICE_ERROR

The network device encountered an error during this operation.

EFI_OUT_OF_RESOURCES

Could not allocate enough memory to complete the DHCP Protocol.

EFI_ABORTED

The callback function aborted the DHCP Protocol.

EFI_TIMEOUT

The DHCP Protocol timed out.

EFI_ICMP_ERROR

An ICMP error packet was received during the DHCP session. The ICMP error packet has been cached in the EFI_PXE_BASE_CODE_MODE. IcmpError packet structure. Information about ICMP packet contents can be found in RFC 792.

EFI_NO_RESPONSE

Valid PXE offer was not received.

24.3.9. EFI_PXE_BASE_CODE_PROTOCOL.Discover()

Summary

Attempts to complete the PXE Boot Server and/or boot image discovery sequence.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_DISCOVER) (
  IN EFI_PXE_BASE_CODE_PROTOCOL        *This,
  IN UINT16                            Type,
  IN UINT16                            *Layer,
  IN BOOLEAN                           UseBis,
  IN EFI_PXE_BASE_CODE_DISCOVER_INFO   *Info OPTIONAL
);

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

Type

The type of bootstrap to perform. See “Related Definitions” below.

Layer

Pointer to the boot server layer number to discover, which must be PXE_BOOT_LAYER_INITIAL when a new server type is being discovered. This is the only layer type that will perform multicast and broadcast discovery. All other layer types will only perform unicast discovery. If the boot server changes Layer, then the new Layer will be returned.

UseBis

TRUE if Boot Integrity Services are to be used. FALSE otherwise.

Info

Pointer to a data structure that contains additional information on the type of discovery operation that is to be performed. If this field is NULL, then the contents of the cached DhcpAck and ProxyOffer packets will be used.

Related Definitions

//*******************************************************
// Bootstrap Types
//*******************************************************


#define EFI_PXE_BASE_CODE_BOOT_TYPE_BOOTSTRAP         0
#define EFI_PXE_BASE_CODE_BOOT_TYPE_MS_WINNT_RIS      1
#define EFI_PXE_BASE_CODE_BOOT_TYPE_INTEL_LCM         2
#define EFI_PXE_BASE_CODE_BOOT_TYPE_DOSUNDI           3
#define EFI_PXE_BASE_CODE_BOOT_TYPE_NEC_ESMPRO        4
#define EFI_PXE_BASE_CODE_BOOT_TYPE_IBM_WSoD          5
#define EFI_PXE_BASE_CODE_BOOT_TYPE_IBM_LCCM          6
#define EFI_PXE_BASE_CODE_BOOT_TYPE_CA_UNICENTER_TNG  7
#define EFI_PXE_BASE_CODE_BOOT_TYPE_HP_OPENVIEW       8
#define EFI_PXE_BASE_CODE_BOOT_TYPE_ALTIRIS_9         9
#define EFI_PXE_BASE_CODE_BOOT_TYPE_ALTIRIS_10        10
#define EFI_PXE_BASE_CODE_BOOT_TYPE_ALTIRIS_11        11
#define EFI_PXE_BASE_CODE_BOOT_TYPE_NOT_USED_12       12
#define EFI_PXE_BASE_CODE_BOOT_TYPE_REDHAT_INSTALL    13
#define EFI_PXE_BASE_CODE_BOOT_TYPE_REDHAT_BOOT       14
#define EFI_PXE_BASE_CODE_BOOT_TYPE_REMBO             15
#define EFI_PXE_BASE_CODE_BOOT_TYPE_BEOBOOT           16
//
// Values 17 through 32767 are reserved.
// Values 32768 through 65279 are for vendor use.
// Values 65280 through 65534 are reserved.
//
#define EFI_PXE_BASE_CODE_BOOT_TYPE_PXETEST           65535

#define EFI_PXE_BASE_CODE_BOOT_LAYER_MASK             0x7FFF
#define EFI_PXE_BASE_CODE_BOOT_LAYER_INITIAL          0x0000

//*******************************************************
// EFI_PXE_BASE_CODE_DISCOVER_INFO
//*******************************************************
typedef struct {
  BOOLEAN                        UseMCast;
  BOOLEAN                        UseBCast;
  BOOLEAN                        UseUCast;
  BOOLEAN                        MustUseList;
  EFI_IP_ADDRESS                 ServerMCastIp;
  UINT16                         IpCnt;
  EFI_PXE_BASE_CODE_SRVLIST      SrvList[IpCnt];
}   EFI_PXE_BASE_CODE_DISCOVER_INFO;

//*******************************************************
// EFI_PXE_BASE_CODE_SRVLIST
//*******************************************************
typedef struct {
  UINT16                         Type;
  BOOLEAN                        AcceptAnyResponse;
  UINT8                          reserved;
  EFI_IP_ADDRESS                 IpAddr;
}   EFI_PXE_BASE_CODE_SRVLIST;

Description

This function attempts to complete the PXE Boot Server and/or boot image discovery sequence. If this sequence is completed, then EFI_SUCCESS is returned, and the PxeDiscoverValid, PxeDiscover, PxeReplyReceived, and PxeReply fields of the EFI_PXE_BASE_CODE_MODE in Network Protocols — SNP, PXE, BIS and HTTP Boot structure are filled in. If UseBis is TRUE, then the PxeBisReplyReceived and PxeBisReply fields of the EFI_PXE_BASE_CODE_MODE structure will also be filled in. If UseBis is FALSE, then PxeBisReplyValid will be set to FALSE.

In the structure referenced by parameter Info, the PXE Boot Server list, SrvList[], has two uses: It is the Boot Server IP address list used for unicast discovery (if the UseUCast field is TRUE), and it is the list used for Boot Server verification (if the MustUseList field is TRUE). Also, if the MustUseList field in that structure is TRUE and the AcceptAnyResponse field in the SrvList[] array is TRUE, any Boot Server reply of that type will be accepted. If the AcceptAnyResponse field is FALSE, only responses from Boot Servers with matching IP addresses will be accepted.

This function can take at least 10 seconds to timeout and return control to the caller. If the Discovery sequence does not complete, then EFI_TIMEOUT will be returned. Please see the Preboot Execution Environment (PXE) Specification for additional details on the implementation of the Discovery sequence.

If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then the Discovery sequence is stopped and EFI_ABORTED will be returned.

Status Codes Returned

EFI_SUCCESS

The Discovery sequence has been completed.

EFI_NOT_STARTED

The PXE Base Code Protocol is in the stopped state.

EFI_INVALID_PARAMETER

One or more of the following conditions was TRUE :
• The This parameter was NULL
• The This parameter did not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure
• The Layer parameter was NULL
• The Info->ServerMCastIp parameter does not contain a valid multicast IP address
• The Info->UseUCast parameter is not FALSE and the Info->IpCnt parameter is zero
One or more of the IP addresses in the Info->SrvList[] array is not a valid unicast IP address.

EFI_DEVICE_ERROR

The network device encountered an error during this operation.

EFI_OUT_OF_RESOURCES

Could not allocate enough memory to complete Discovery.

EFI_ABORTED

The callback function aborted the Discovery sequence.

EFI_TIMEOUT

The Discovery sequence timed out.

EFI_ICMP_ERROR

An ICMP error packet was received during the PXE discovery session. The ICMP error packet has been cached in the EFI_PXE_BASE_CODE_MODE. IcmpError packet structure. Information about ICMP packet contents can be found in RFC 792.

24.3.10. EFI_PXE_BASE_CODE_PROTOCOL.Mtftp()

Summary

Used to perform TFTP and MTFTP services.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_MTFTP) (
  IN EFI_PXE_BASE_CODE_PROTOCOL        *This,
  IN EFI_PXE_BASE_CODE_TFTP_OPCODE     Operation,
  IN OUT VOID                          *BufferPtr, OPTIONAL
  IN BOOLEAN                           Overwrite,
  IN OUT UINT64                        *BufferSize,
  IN UINTN                             *BlockSize, OPTIONAL
  IN EFI_IP_ADDRESS                    *ServerIp,
  IN CHAR8                             *Filename, OPTIONAL
  IN EFI_PXE_BASE_CODE_MTFTP_INFO      *Info, OPTIONAL
  IN BOOLEAN                           DontUseBuffer
  );

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

Operation

The type of operation to perform. See “Related Definitions” below for the list of operation types.

BufferPtr

A pointer to the data buffer. Ignored for read file if DontUseBuffer is TRUE.

Overwrite

Only used on write file operations. TRUE if a file on a remote server can be overwritten.

BufferSize

For get-file-size operations, BufferSize returns the size of the requested file. For read-file and write-file operations, this parameter is set to the size of the buffer specified by the BufferPtr parameter. For read-file operations, if EFI_BUFFER_TOO_SMALL is returned, BufferSize returns the size of the requested file.

BlockSize

The requested block size to be used during a TFTP transfer. This must be at least 512. If this field is NULL, then the largest block size supported by the implementation will be used.

ServerIp

The TFTP / MTFTP server IP address.

Filename

A Null-terminated ASCII string that specifies a directory name or a file name. This is ignored by MTFTP read directory.

Info

Pointer to the MTFTP information. This information is required to start or join a multicast TFTP session. It is also required to perform the “get file size” and “read directory” operations of MTFTP. See “Related Definitions” below for the description of this data structure.

DontUseBuffer

Set to FALSE for normal TFTP and MTFTP read file operation. Setting this to TRUE will cause TFTP and MTFTP read file operations to function without a receive buffer, and all of the received packets are passed to the Callback Protocol which is responsible for storing them. This field is only used by TFTP and MTFTP read file.

Related Definitions

//*******************************************************
// EFI_PXE_BASE_CODE_TFTP_OPCODE
//*******************************************************
typedef enum {
  EFI_PXE_BASE_CODE_TFTP_FIRST,
  EFI_PXE_BASE_CODE_TFTP_GET_FILE_SIZE,
  EFI_PXE_BASE_CODE_TFTP_READ_FILE,
  EFI_PXE_BASE_CODE_TFTP_WRITE_FILE,
  EFI_PXE_BASE_CODE_TFTP_READ_DIRECTORY,
  EFI_PXE_BASE_CODE_MTFTP_GET_FILE_SIZE,
  EFI_PXE_BASE_CODE_MTFTP_READ_FILE,
  EFI_PXE_BASE_CODE_MTFTP_READ_DIRECTORY,
  EFI_PXE_BASE_CODE_MTFTP_LAST
}   EFI_PXE_BASE_CODE_TFTP_OPCODE;

//*******************************************************
// EFI_PXE_BASE_CODE_MTFTP_INFO
//*******************************************************
typedef struct {
  EFI_IP_ADDRESS               MCastIp;
  EFI_PXE_BASE_CODE_UDP_PORT   CPort;
  EFI_PXE_BASE_CODE_UDP_PORT   SPort;
  UINT16                       ListenTimeout;
  UINT16                       TransmitTimeout;
}   EFI_PXE_BASE_CODE_MTFTP_INFO;
MCastIp

File multicast IP address. This is the IP address to which the server will send the requested file.

CPort

Client multicast listening port. This is the UDP port to which the server will send the requested file.

SPort

Server multicast listening port. This is the UDP port on which the server listens for multicast open requests and data acks.

ListenTimeout

The number of seconds a client should listen for an active multicast session before requesting a new multicast session.

TransmitTimeout

The number of seconds a client should wait for a packet from the server before retransmitting the previous open request or data ack packet.

Description

This function is used to perform TFTP and MTFTP services. This includes the TFTP operations to get the size of a file, read a directory, read a file, and write a file. It also includes the MTFTP operations to get the size of a file, read a directory, and read a file. The type of operation is specified by Operation. If the callback function that is invoked during the TFTP/MTFTP operation does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then EFI_ABORTED will be returned.

For read operations, the return data will be placed in the buffer specified by BufferPtr. If BufferSize is too small to contain the entire downloaded file, then EFI_BUFFER_TOO_SMALL will be returned and BufferSize will be set to zero or the size of the requested file (the size of the requested file is only returned if the TFTP server supports TFTP options). If BufferSize is large enough for the read operation, then BufferSize will be set to the size of the downloaded file, and EFI_SUCCESS will be returned. Applications using the PxeBc.Mtftp() services should use the get-file-size operations to determine the size of the downloaded file prior to using the read-file operations–especially when downloading large (greater than 64 MiB) files–instead of making two calls to the read-file operation. Following this recommendation will save time if the file is larger than expected and the TFTP server does not support TFTP option extensions. Without TFTP option extension support, the client has to download the entire file, counting and discarding the received packets, to determine the file size.

For write operations, the data to be sent is in the buffer specified by BufferPtr. BufferSize specifies the number of bytes to send. If the write operation completes successfully, then EFI_SUCCESS will be returned.

For TFTP “get file size” operations, the size of the requested file or directory is returned in BufferSize, and EFI_SUCCESS will be returned. If the TFTP server does not support options, the file will be downloaded into a bit bucket and the length of the downloaded file will be returned. For MTFTP “get file size” operations, if the MTFTP server does not support the “get file size” option, EFI_UNSUPPORTED will be returned.

This function can take up to 10 seconds to timeout and return control to the caller. If the TFTP sequence does not complete, EFI_TIMEOUT will be returned.

If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then the TFTP sequence is stopped and EFI_ABORTED will be returned.

The format of the data returned from a TFTP read directory operation is a null-terminated filename followed by a null-terminated information string, of the form “size year-month-day hour:minute:second” (i.e., %d %d-%d-%d %d:%d:%f - note that the seconds field can be a decimal number), where the date and time are UTC. For an MTFTP read directory command, there is additionally a null-terminated multicast IP address preceding the filename of the form %d.%d.%d.%d for IP v4. The final entry is itself null-terminated, so that the final information string is terminated with two null octets.

Status Codes Returned

EFI_SUCCESS

The TFTP/MTFTP operation was completed.

EFI_NOT_STARTED

The PXE Base Code Protocol is in the stopped state.

EFI_INVALID_PARAMETER

One or more of the following conditions was TRUE :
• The This parameter was NULL
• The This parameter did not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure
• The Operation parameter was not one of the listed EFI_PXE_BASE_CODE_TFTP_OPCODE constants
• The BufferPtr parameter was NULL and the DontUseBuffer parameter was FALSE
• The BufferSize parameter was NULL
• The BlockSize parameter was not NULL and * BlockSize was less than 512
• The ServerIp parameter was NULL or did not contain a valid unicast IP address
• The Filename parameter was NULL for a file transfer or information request
• The Info parameter was NULL for a multicast request
The Info->MCastIp parameter is not a valid multicast IP address

EFI_DEVICE_ERROR

The network device encountered an error during this operation.

EFI_BUFFER_TOO_SMALL

The buffer is not large enough to complete the read operation.

EFI_ABORTED

The callback function aborted the TFTP/MTFTP operation.

EFI_TIMEOUT

The TFTP/MTFTP operation timed out.

EFI_TFTP_ERROR

A TFTP error packet was received during the MTFTP session. The TFTP error packet has been cached in the EFI_PXE_BASE_CODE_MODE. TftpError packet structure. Information about TFTP error packet contents can be found in RFC 1350.

EFI_ICMP_ERROR

An ICMP error packet was received during the MTFTP session. The ICMP error packet has been cached in the EFI_PXE_BASE_CODE_MODE. IcmpError packet structure. Information about ICMP packet contents can be found in RFC 792.

24.3.11. EFI_PXE_BASE_CODE_PROTOCOL.UdpWrite()

Summary

Writes a UDP packet to the network interface.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_UDP_WRITE) (
  IN EFI_PXE_BASE_CODE_PROTOCOL        *This,
  IN UINT16                            OpFlags,
  IN EFI_IP_ADDRESS                    *DestIp,
  IN EFI_PXE_BASE_CODE_UDP_PORT        *DestPort,
  IN EFI_IP_ADDRESS                    *GatewayIp, OPTIONAL
  IN EFI_IP_ADDRESS                    *SrcIp, OPTIONAL
  IN OUT EFI_PXE_BASE_CODE_UDP_PORT    *SrcPort, OPTIONAL
  IN UINTN                             *HeaderSize, OPTIONAL
  IN VOID                              *HeaderPtr, OPTIONAL
  IN UINTN                             *BufferSize,
  IN VOID                              *BufferPtr
  );

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

OpFlags

The UDP operation flags. If MAY_FRAGMENT is set, then if required, this UDP write operation may be broken up across multiple packets.

DestIp

The destination IP address.

DestPort

The destination UDP port number.

GatewayIp

The gateway IP address. If DestIp is not in the same subnet as StationIp, then this gateway IP address will be used. If this field is NULL, and the DestIp is not in the same subnet as StationIp, then the RouteTable will be used.

SrcIp

The source IP address. If this field is NULL, then StationIp will be used as the source IP address.

SrcPort

The source UDP port number. If OpFlags has ANY_SRC_PORT set or SrcPort is NULL, then a source UDP port will be automatically selected. If a source UDP port was automatically selected, and SrcPort is not NULL, then it will be returned in SrcPort.

HeaderSize

An optional field which may be set to the length of a header at HeaderPtr to be prefixed to the data at BufferPtr.

HeaderPtr

If HeaderSize is not NULL, a pointer to a header to be prefixed to the data at BufferPtr.

BufferSize

A pointer to the size of the data at BufferPtr.

BufferPtr

A pointer to the data to be written.

Description

This function writes a UDP packet specified by the (optional HeaderPtr and) BufferPtr parameters to the network interface. The UDP header is automatically built by this routine. It uses the parameters OpFlags, DestIp, DestPort, GatewayIp, SrcIp, and SrcPort to build this header. If the packet is successfully built and transmitted through the network interface, then EFI_SUCCESS will be returned. If a timeout occurs during the transmission of the packet, then EFI_TIMEOUT will be returned. If an ICMP error occurs during the transmission of the packet, then the IcmpErrorReceived field is set to TRUE, the IcmpError field is filled in and EFI_ICMP_ERROR will be returned. If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then EFI_ABORTED will be returned.

Status Codes Returned

EFI_SUCCESS

The UDP Write operation was completed.

EFI_NOT_STARTED

The PXE Base Code Protocol is in the stopped state.

EFI_INVALID_PARAMETER

One or more of the following conditions was TRUE :
• The This parameter was NULL
• The This parameter did not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure
• Reserved bits in the OpFlags parameter were not set to zero - The DestIp parameter was NULL
• The DestPort parameter was NULL
• The GatewayIp parameter was not NULL and did not contain a valid unicast IP address.
• The HeaderSize parameter was not NULL and * HeaderSize is zero
• The HeaderSize parameter was not zero and the HeaderPtr parameter was *NULL
• The BufferSize parameter was NULL
• The BufferSize parameter was not zero and the BufferPtr parameter was *NULL

EFI_DEVICE_ERROR

The network device encountered an error during this operation.

EFI_BAD_BUFFER_SIZE

The buffer is too long to be transmitted.

EFI_ABORTED

The callback function aborted the UDP Write operation.

EFI_TIMEOUT

The UDP Write operation timed out.

EFI_ICMP_ERROR

An ICMP error packet was received during the UDP write session. The ICMP error packet has been cached in the EFI_PXE_BASE_CODE_MODE. IcmpError packet structure. Information about ICMP packet contents can be found in RFC 792.

24.3.12. EFI_PXE_BASE_CODE_PROTOCOL.UdpRead()

Summary

Reads a UDP packet from the network interface.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_UDP_READ) (
  IN EFI_PXE_BASE_CODE_PROTOCOL           *This
  IN UINT16                               OpFlags,
  IN OUT EFI_IP_ADDRESS                   *DestIp, OPTIONAL
  IN OUT EFI_PXE_BASE_CODE_UDP_PORT       *DestPort, OPTIONAL
  IN OUT EFI_IP_ADDRESS                   *SrcIp, OPTIONAL
  IN OUT EFI_PXE_BASE_CODE_UDP_PORT       *SrcPort, OPTIONAL
  IN UINTN                                *HeaderSize, OPTIONAL
  IN VOID                                 *HeaderPtr, OPTIONAL
  IN OUT UINTN                            *BufferSize,
  IN VOID                                 *BufferPtr
  );

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

OpFlags

The UDP operation flags.

DestIp

The destination IP address.

DestPort

The destination UDP port number.

SrcIp

The source IP address.

SrcPort

The source UDP port number.

HeaderSize

An optional field which may be set to the length of a header to be put in HeaderPtr.

HeaderPtr

If HeaderSize is not NULL, a pointer to a buffer to hold the HeaderSize bytes which follow the UDP header.

BufferSize

On input, a pointer to the size of the buffer at BufferPtr. On output, the size of the data written to BufferPtr.

BufferPtr

A pointer to the data to be read.

Description

This function reads a UDP packet from a network interface. The data contents are returned in (the optional HeaderPtr and) BufferPtr, and the size of the buffer received is returned in BufferSize. If the input BufferSize is smaller than the UDP packet received (less optional HeaderSize ), it will be set to the required size, and EFI_BUFFER_TOO_SMALL will be returned. In this case, the contents of BufferPtr are undefined, and the packet is lost. If a UDP packet is successfully received, then EFI_SUCCESS will be returned, and the information from the UDP header will be returned in DestIp, DestPort, SrcIp, and SrcPort if they are not NULL. Depending on the values of OpFlags and the DestIp, DestPort, SrcIp, and SrcPort input values, different types of UDP packet receive filtering will be performed. The following tables summarize these receive filter operations.

Destination IP Filter Operation

Table 24.2 Destination IP Filter Operation

OpFlags USE_FILTER

OpFlags ANY_DEST_IP

DestIp

Action

0

0

NULL

Receive a packet sent to StationIp.

0

1

NULL

Receive a packet sent to any IP address.

1

x

NULL

Receive a packet whose destination IP address passes the IP filter.

0

0

not NULL

Receive a packet whose destination IP address matches DestIp.

0

1

not NULL

Receive a packet sent to any IP address and, return the destination IP address in DestIp.

1

x

not NULL

Receive a packet whose destination IP address passes the IP filter, and return the destination IP address in DestIp.

Table 24.3 Destination UDP Port Filter Operation

OpFlags ANY_DEST_PORT

DestPort

Action

0

NULL

Return E FI_INVALID_PARAMETER.

1

NULL

Receive a packet sent to any UDP port.

0

not NULL

Receive a packet whose destination Port matches DestPort.

1

not NULL

Receive a packet sent to any UDP port, and return the destination port in DestPort

Table 24.4 Source IP Filter Operation

OpFlags ANY_SRC_IP

SrcIp

Action

0

NULL

Return E FI_INVALID_PARAMETER.

1

NULL

Receive a packet sent from any IP address.

0

not NULL

Receive a packet whose source IP address matches SrcIp.

1

not NULL

Receive a packet sent from any IP address, and return the source IP address in SrcIp.

Table 24.5 Source UDP Port Filter Operation

OpFlags ANY_SRC_PORT

SrcPort

Action

0

NULL

Return E FI_INVALID_PARAMETER.

1

NULL

Receive a packet sent from any UDP port.

0

not NULL

Receive a packet whose source UDP port matches SrcPort.

1

not NULL

Receive a packet sent from any UDP port, and return the source UPD port in SrcPort.

Status Codes Returned

EFI_SUCCESS

The UDP Read operation was completed.

EFI_NOT_STARTED

The PXE Base Code Protocol is in the stopped state.

EFI_INVALID_PARAMETER

One or more of the following conditions was TRUE :
• The This parameter was NULL
• The This parameter did not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure
• Reserved bits in the OpFlags parameter were not set to zero
• The HeaderSize parameter is not NULL and * HeaderSize is zero
• The HeaderSize parameter is not NULL L and the HeaderPtr parameter is NULL
• The BufferSize parameter is NULL
• The BufferPtr parameter is NULL

EFI_DEVICE_ERROR

The network device encountered an error during this operation.

EFI_BUFFER_TOO_SMALL

The packet is larger than Buffer can hold.

EFI_ABORTED

The callback function aborted the UDP Read operation.

EFI_TIMEOUT

The UDP Read operation timed out.

24.3.13. EFI_PXE_BASE_CODE_PROTOCOL.SetIpFilter()

Summary

Updates the IP receive filters of a network device and enables software filtering.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_SET_IP_FILTER) (
  IN EFI_PXE_BASE_CODE_PROTOCOL           *This,
  IN EFI_PXE_BASE_CODE_IP_FILTER          *NewFilter
  );

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

NewFilter

Pointer to the new set of IP receive filters.

Description

The NewFilter field is used to modify the network device’s current IP receive filter settings and to enable a software filter. This function updates the IpFilter field of the EFI_PXE_BASE_CODE_MODE in Network Protocols — SNP, PXE, BIS and HTTP Boot structure with the contents of NewIpFilter. The software filter is used when the USE_FILTER in OpFlags is set to EFI_PXE_BASE_CODE_PROTOCOL.UdpRead() . The current hardware filter remains in effect no matter what the settings of OpFlags are, so that the meaning of ANY_DEST_IP set in OpFlags to UdpRead() is from those packets whose reception is enabled in hardware - physical NIC address (unicast), broadcast address, logical address or addresses (multicast), or all (promiscuous). UdpRead() does not modify the IP filter settings.

EFI_PXE_BASE_CODE_PROTOCOL.Dhcp() , EFI_PXE_BASE_CODE_PROTOCOL.Discover() , and EFI_PXE_BASE_CODE_PROTOCOL.Mtftp() set the IP filter, and return with the IP receive filter list emptied and the filter set to EFI_PXE_BASE_CODE_IP_FILTER_STATION_IP. If an application or driver wishes to preserve the IP receive filter settings, it will have to preserve the IP receive filter settings before these calls, and use EFI_PXE_BASE_CODE_PROTOCOL.SetIpFilter() to restore them after the calls. If incompatible filtering is requested (for example, PROMISCUOUS with anything else) or if the device does not support a requested filter setting and it cannot be accommodated in software (for example, PROMISCUOUS not supported), EFI_INVALID_PARAMETER will be returned. The IPlist field is used to enable IPs other than the StationIP. They may be multicast or unicast. If IPcnt is set as well as EFI_PXE_BASE_CODE_IP_FILTER_STATION_IP, then both the StationIP and the IPs from the IPlist will be used.

Status Codes Returned

EFI_SUCCESS

The IP receive filter settings were updated.

EFI_INVALID_PARAMETER

• One or more of the following conditions was TRUE :
• The This parameter was NULL
• The This parameter did not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure
• The NewFilter parameter was NULL
• The NewFilter -> IPlist [] array contains one or more broadcast IP addresses

EFI_NOT_STARTED

The PXE Base Code Protocol is not in the started state.

24.3.14. EFI_PXE_BASE_CODE_PROTOCOL.Arp()

Summary

Uses the ARP protocol to resolve a MAC address.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_ARP) (
  IN EFI_PXE_BASE_CODE_PROTOCOL        *This,
  IN EFI_IP_ADDRESS                    *IpAddr,
  IN EFI_MAC_ADDRESS                   *MacAddr OPTIONAL
  );

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

IpAddr

Pointer to the IP address that is used to resolve a MAC address. When the MAC address is resolved, the ArpCacheEntries and ArpCache fields of the EFI_PXE_BASE_CODE_MODE in Network Protocols — SNP, PXE, BIS and HTTP Boot structure are updated.

MacAddr

If not NULL, a pointer to the MAC address that was resolved with the ARP protocol.

Description

This function uses the ARP protocol to resolve a MAC address. The UsingIpv6 field of the EFI_PXE_BASE_CODE_MODE structure is used to determine if IPv4 or IPv6 addresses are being used. The IP address specified by IpAddr is used to resolve a MAC address in the case of IPv4; the concept of Arp is not supported in IPv6, though.

If the ARP protocol succeeds in resolving the specified address, then the ArpCacheEntries and ArpCache fields of the EFI_PXE_BASE_CODE_MODE structure are updated, and EFI_SUCCESS is returned. If MacAddr is not NULL, the resolved MAC address is placed there as well.

If the PXE Base Code protocol is in the stopped state, then EFI_NOT_STARTED is returned. If the ARP protocol encounters a timeout condition while attempting to resolve an address, then EFI_TIMEOUT is returned. If the Callback Protocol does not return EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, then EFI_ABORTED is returned.

Status Codes Returned

EFI_SUCCESS

The IP or MAC address was resolved.

EFI_INVALID_PARAMETER

One or more of the following conditions was :
• The This parameter was NULL
• The This parameter did not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure
• The IpAddr parameter was NULL

EFI_DEVICE_ERROR

The network device encountered an error during this operation.

EFI_NOT_STARTED

The PXE Base Code Protocol is in the stopped state.

EFI_TIMEOUT

The ARP Protocol encountered a timeout condition.

EFI_ABORTED

The callback function aborted the ARP Protocol.

EFI_UNSUPPORTED

When Mode->UsingIpv6 is TRUE because the Arp is a concept special for IPv4.

24.3.15. EFI_PXE_BASE_CODE_PROTOCOL.SetParameters()

Summary

Updates the parameters that affect the operation of the PXE Base Code Protocol.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_SET_PARAMETERS) (
  IN EFI_PXE_BASE_CODE_PROTOCOL              *This,
  IN BOOLEAN                                 *NewAutoArp, OPTIONAL
  IN BOOLEAN                                 *NewSendGUID, OPTIONAL
  IN UINT8                                   *NewTTL, OPTIONAL
  IN UINT8                                   *NewToS, OPTIONAL
  IN BOOLEAN                                 *NewMakeCallback OPTIONAL
  );

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

NewAutoArp

If not NULL, a pointer to a value that specifies whether to replace the current value of AutoARP. TRUE for automatic ARP packet generation, FALSE otherwise. If NULL, this parameter is ignored.

NewSendGUID

If not NULL, a pointer to a value that specifies whether to replace the current value of SendGUID. TRUE to send the SystemGUID (if there is one) as the client hardware address in DHCP; FALSE to send client NIC MAC address. If NULL, this parameter is ignored. If NewSendGUID is TRUE and there is no SystemGUID, then EFI_INVALID_PARAMETER is returned.

NewTTL

If not NULL, a pointer to be used in place of the current value of TTL, the “time to live” field of the IP header. If NULL, this parameter is ignored.

NewToS

If not NULL, a pointer to be used in place of the current value of ToS, the “type of service” field of the IP header. If NULL, this parameter is ignored.

NewMakeCallback

If not NULL, a pointer to a value that specifies whether to replace the current value of the MakeCallback field of the Mode structure. If NULL, this parameter is ignored. If the Callback Protocol is not available EFI_INVALID_PARAMETER is returned.

Description

This function sets parameters that affect the operation of the PXE Base Code Protocol. The parameter specified by NewAutoArp is used to control the generation of ARP protocol packets. If NewAutoArp is TRUE, then ARP Protocol packets will be generated as required by the PXE Base Code Protocol. If NewAutoArp is FALSE, then no ARP Protocol packets will be generated. In this case, the only mappings that are available are those stored in the ArpCache of the EFI_PXE_BASE_CODE_MODE in Network Protocols — SNP, PXE, BIS and HTTP Boot structure. If there are not enough mappings in the ArpCache to perform a PXE Base Code Protocol service, then the service will fail. This function updates the AutoArp field of the EFI_PXE_BASE_CODE_MODE structure to NewAutoArp.

The EFI_PXE_BASE_CODE_PROTOCOL.SetParameters() call must be invoked after a Callback Protocol is installed to enable the use of callbacks.

Status Codes Returned

EFI_SUCCESS

The new parameters values were updated.

EFI_INVALID_PARAMETER

• One or more of the following conditions was TRUE :
• The This parameter was NULL
• The This parameter did not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure
• The NewSendGUID parameter is not NULL and * NewSendGUID is TRUE and a system GUID could not be located
• The NewMakeCallback parameter is not NULL and * NewMakeCallback is TRUE and an EFI _PXE_BASE_CODE_CALLBACK_PROTOCOL could not be located on the network device handle.

EFI_NOT_STARTED

The PXE Base Code Protocol is not in the started state.

24.3.16. EFI_PXE_BASE_CODE_PROTOCOL.SetStationIp()

Summary

Updates the station IP address and/or subnet mask values of a network device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_SET_STATION_IP) (
  IN EFI_PXE_BASE_CODE_PROTOCOL           *This,
  IN EFI_IP_ADDRESS                       *NewStationIp, OPTIONAL
  IN EFI_IP_ADDRESS                       *NewSubnetMask OPTIONAL
  );

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

NewStationIp

Pointer to the new IP address to be used by the network device. If this field is NULL, then the StationIp address will not be modified.

NewSubnetMask

Pointer to the new subnet mask to be used by the network device. If this field is NULL, then the SubnetMask will not be modified.

Description

This function updates the station IP address and/or subnet mask values of a network device.

The NewStationIp field is used to modify the network device’s current IP address. If NewStationIP is NULL, then the current IP address will not be modified. Otherwise, this function updates the StationIp field of the EFI_PXE_BASE_CODE_MODE in Network Protocols — SNP, PXE, BIS and HTTP Boot structure with NewStationIp.

The NewSubnetMask field is used to modify the network device’s current subnet mask. If NewSubnetMask is NULL, then the current subnet mask will not be modified. Otherwise, this function updates the SubnetMask field of the EFI_PXE_BASE_CODE_MODE structure with NewSubnetMask.

Status Codes Returned

EFI_SUCCESS

The new station IP address and/or subnet mask were updated.

EFI_INVALID_PARAMETER

One or more of the following conditions was TRUE :
• The This s parameter was NULL
• The This parameter did not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure
• The NewStationIp parameter is not NULL and * NewStationIp is not a valid unicast IP address
• The NewSubnetMask parameter is not NULL and * NewSubnetMask does not contain a valid IP subnet mask

EFI_NOT_STARTED

The PXE Base Code Protocol is not in the started state.

24.3.17. EFI_PXE_BASE_CODE_PROTOCOL.SetPackets()

Summary

Updates the contents of the cached DHCP and Discover packets.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PXE_BASE_CODE_SET_PACKETS) (
  IN EFI_PXE_BASE_CODE_PROTOCOL              *This,
  IN BOOLEAN                                 *NewDhcpDiscoverValid, OPTIONAL
  IN BOOLEAN                                 *NewDhcpAckReceived, OPTIONAL
  IN BOOLEAN                                 *NewProxyOfferReceived, OPTIONAL
  IN BOOLEAN                                 *NewPxeDiscoverValid, OPTIONAL
  IN BOOLEAN                                 *NewPxeReplyReceived, OPTIONAL
  IN BOOLEAN                                 *NewPxeBisReplyReceived, OPTIONAL
  IN EFI_PXE_BASE_CODE_PACKET                *NewDhcpDiscover, OPTIONAL
  IN EFI_PXE_BASE_CODE_PACKET                *NewDhcpAck, OPTIONAL
  IN EFI_PXE_BASE_CODE_PACKET                *NewProxyOffer, OPTIONAL
  IN EFI_PXE_BASE_CODE_PACKET                *NewPxeDiscover, OPTIONAL
  IN EFI_PXE_BASE_CODE_PACKET                *NewPxeReply, OPTIONAL
  IN EFI_PXE_BASE_CODE_PACKET                *NewPxeBisReply OPTIONAL
  );

Parameters

This

Pointer to the EFI_PXE_BASE_CODE_PROTOCOL instance.

NewDhcpDiscoverValid

Pointer to a value that will replace the current DhcpDiscoverValid field. If NULL, this parameter is ignored.

NewDhcpAckReceived

Pointer to a value that will replace the current DhcpAckReceived field. If NULL, this parameter is ignored.

NewProxyOfferReceived

Pointer to a value that will replace the current ProxyOfferReceived field. If NULL, this parameter is ignored.

NewPxeDiscoverValid

Pointer to a value that will replace the current ProxyOfferReceived field. If NULL, this parameter is ignored.

NewPxeReplyReceived

Pointer to a value that will replace the current PxeReplyReceived field. If NULL, this parameter is ignored.

NewPxeBisReplyReceived

Pointer to a value that will replace the current PxeBisReplyReceived field. If NULL, this parameter is ignored.

NewDhcpDiscover

Pointer to the new cached DHCP Discover packet contents. If NULL, this parameter is ignored.

NewDhcpAck

Pointer to the new cached DHCP Ack packet contents. If NULL, this parameter is ignored.

NewProxyOffer

Pointer to the new cached Proxy Offer packet contents. If NULL, this parameter is ignored.

NewPxeDiscover

Pointer to the new cached PXE Discover packet contents. If NULL, this parameter is ignored.

NewPxeReply

Pointer to the new cached PXE Reply packet contents. If NULL, this parameter is ignored.

NewPxeBisReply

Pointer to the new cached PXE BIS Reply packet contents. If NULL, this parameter is ignored.

Description

The pointers to the new packets are used to update the contents of the cached packets in the EFI_PXE_BASE_CODE_MODE structure.

Status Codes Returned

EFI_SUCCESS

The cached packet contents were updated.

EFI_INVALID_PARAMETER

• One or more of the following conditions was TRUE :
• The This parameter was NULL
The This parameter did not point to a valid EFI_PXE_BASE_CODE_PROTOCOL structure.

EFI_NOT_STARTED

The PXE Base Code Protocol is not in the started state.

24.3.18. Netboot6

For IPv4, PXE drivers typically install a LoadFile protocol on the NIC handle. In the case of supporting both IPv4 and IPv6 where two PXE Base Code and LoadFile protocol instances need be produced, the PXE driver will have to create two child handles and install EFI_LOAD_FILE_PROTOCOL, EFI_SIMPLE_NETWORK_PROTOCOL and PXE_BASE_CODE_PROTOCOL on each child handle. To distinguish these two child handles, an IP device path node can be appended to the parent device path, for example:

PciRoot(0x0)/Pci(0x19,0x0)/MAC(001320F4B4FF,0x0)/IPv4(...)
PciRoot(0x0)/Pci(0x19,0x0)/MAC(001320F4B4FF,0x0)/IPv6(...)

These two instances allow for the boot manager to decide a preference of IPv6 versus IPv4 since the IETF and other bodies do not speak to this policy choice.

24.3.18.1. DHCP6 options for PXE

In IPv4-based PXE, as defined by the rfc2131, rfc2132 and rfc4578, and described by the PXE2.1 specification and the UEFI specification, there are the following PXE related options/fields in DHCPv4 packet:

  • siaddr field/ServerAddress option (54) - next server address.

  • BootFileName option (67

  • ) – NBP file name.

  • BootFileSize option (13)

  • – NBP file size.

  • ClassIdentifier (60)

  • – PXE client tag.

  • ClientSystemArchitectureType option (93)

  • – client architecture type.

  • ClientNetworkInterface Identifier option (94)

  • – client network interface identifier.

In IPv6-based PXE, or ‘netboot6’, there are the following PXE related options in the DHCPv6 packet:

  • BootFileURL option - OPT_BOOTFILE_URL (59) — next server address and NBP (Network Bootable Program) file name.

  • BootFileParameters option

  • – OPT_BOOTFILE_PARAM (60) — NBP file size.

  • VendorClass option (16)

  • – PXE client tag.

  • ClientSystemArchitectureType option — OPTION_CLIENT_ARCH_TYPE (61) — client architecture type.

  • ClientNetworkInterfaceIdentifier option (

  • 62). – client network interface identifier.

The BootFileURL option is used to deliver the next server address or the next server address with NBP file name.

As an example where the next server address delivered only: “tftp://[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210];mode=octet”.

As an example where the next server address and BOOTFILE_NAME delivered both: “tftp://[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]/ BOOTFILE_NAME ;mode=octet”.

The BootFileParameters option is used to deliver the NBP file size with the unit of 512-octet blocks. The maximum of the NBP file size is 65535 * 512 bytes.

As an example where the NBP file size is 1600 * 512 bytes:

para-len 1 = 4
parameter 1 = "1600"

The VendorClass option is used to deliver the PXE client tag.

As an example where the client architecture is EFI-X64 and the client network interface identifier is UNDI:

Enterprise-number = (343)
Vendor-class-data = "PXEClient:Arch:00006:UNDI:003016"

#define DUID-UUID 4

The Netboot6 client will use the DUID-UUID to report the platform identifier as part of the netboot6 DHCP options.

24.3.18.2. IPv6-based PXE boot

As PXE 2.1 specification describes step-by-step synopsis of the IPv4-based PXE process, Figure 1 describes the corresponding synopsis for netboot6.

_images/Network_Protocols_SNP_PXE_BIS-2.png

Fig. 24.1 IPv6-based PXE Boot

24.3.18.2.1. Step 1.

The client multicasts a SOLICIT message to the standard DHCP6 port (547). It contains the following:

  • A tag for client UNDI version.

  • A tag for the client system architecture.

  • A tag for PXE client, Vendor Class data set to

  • “PXEClient:Arch:xxxxx:UNDI:yyyzzz”.

24.3.18.2.2. Step 2.

The DHCP6 or Proxy DHCP6 service responds by sending a ADVERTISE message to the client on the standard DHCP6 reply port (546). If this is a Proxy DHCP6 service, the next server (Boot Server) address is delivered by Boot File URL option. If this is a DHCP6 service, the new assigned client address is delivered by IA option. The extension tags information will be conveyed via the VENDOR OPTS field.

24.3.18.2.3. Steps 3 and 4.

If the client selects an address from a DHCP6 service, then it must complete the standard DHCP6 process by sending a REQUEST for the address back to the service and then waiting for an REPLY from the service.

24.3.18.2.4. Step 5.

The client multicasts a REQUEST message to the Boot Server port 4011, it contains the following:

  • A tag for client UNDI version.

  • A tag for the client system architecture.

  • A tag for PXE client, Vendor Class option, set to

  • “PXEClient:Arch:xxxxx:UNDI:yyyzzz”.

24.3.18.2.5. Step 6.

The Boot Server unicasts a REPLY message back to the client on the client port. It contains the following:

  • A tag for NBP file name.

  • A tag for NBP file size if needed.

24.3.18.2.6. Step 7.

The client requests the NBP file using TFTP (port 69).

24.3.18.2.7. Step 8.

The NBP file, dependent on the client’s CPU architecture, is downloaded into client’s memory.

24.3.18.3. Proxy DHCP6

The netboot6 DHCP6 options may be supplied by the DHCP6 service or a Proxy DHCP6 service. This Proxy DHCP6 service may reside on the same server as the DHCP6 service, or it ma be located on a separate server. A Proxy DHCP6 service on the same server as the DHCP6 service is illustrated in Figure 2. In this case, the Proxy DHCP6 service is listening to UDP port (4011), and communication with the Proxy DHCP6 service occurs after completing the standard DHCP6 process. Proxy DHCP6 uses port (4011) because is cannot share port (547) with the DHCP6 service. The netboot6 client knows how to interrogate the Proxy DHCP6 service because the ADVERTISE from the DHCP6 service contains a VendorClass option “PXEClient” tag without a BootFileURL option (including NBP file name). The client will not request option 16 ( OPTION_VENDOR_CLASS ) in ORO, but server must still reply with “PXEClient” in order to inform the client to start the Proxy DHCPv6 mode. The client will accept just the string “PXEClient” as sufficient, the server need not echo back the entire OPTION_VENDOR_CLASS.

_images/Network_Protocols_SNP_PXE_BIS-3.png

Fig. 24.2 Netboot6 (DHCP6 and ProxyDHCP6 reside on the same server)

The Figure below, IPv6-based PXE boot (DHCP6 and ProxyDHCP6reside on the different server) illustrates the case of a Proxy DHCP6 service and the DHCP6 service on different servers. In this case, the Proxy DHCP6 service listens to UDP port (547) and responds in parallel with DHCP6 service.

_images/Network_Protocols_SNP_PXE_BIS-4.png

Fig. 24.3 IPv6-based PXE boot (DHCP6 and ProxyDHCP6reside on the different server)

24.4. PXE Base Code Callback Protocol

This protocol is a specific instance of the PXE Base Code Callback Protocol that is invoked when the PXE Base Code Protocol is about to transmit, has received, or is waiting to receive a packet. The PXE Base Code Callback Protocol must be on the same handle as the PXE Base Code Protocol.

24.4.1. EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL

Summary

Protocol that is invoked when the PXE Base Code Protocol is about to transmit, has received, or is waiting to receive a packet.

GUID

#define EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL_GUID \
  {0x245DCA21,0xFB7B,0x11d3,\
    {0x8F,0x01,0x00,0xA0, 0xC9,0x69,0x72,0x3B}}

Revision Number

#define EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL_REVISION \\
0x00010000

Protocol Interface Structure

typedef struct {
  UINT64                Revision;
  EFI_PXE_CALLBACK      Callback;
}   EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL;

Parameters

Revision

The revision of the EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL. All future revisions must be backwards compatible. If a future revision is not backwards compatible, it is not the same GUID.

Callback

Callback routine used by the PXE Base Code EFI_PXE_BASE_CODE_PROTOCOL.Dhcp() , EFI_PXE_BASE_CODE_PROTOCOL.Discover() , EFI_PXE_BASE_CODE_PROTOCOL.Mtftp() , EFI_PXE_BASE_CODE_PROTOCOL.UdpWrite() , and EFI_PXE_BASE_CODE_PROTOCOL.Arp() functions.

24.4.2. EFI_PXE_BASE_CODE_CALLBACK.Callback()

Summary

Callback function that is invoked when the PXE Base Code Protocol is about to transmit, has received, or is waiting to receive a packet.

Prototype

typedef
EFI_PXE_BASE_CODE_CALLBACK_STATUS
(*EFI_PXE_CALLBACK) (
  IN EFI_PXE_BASE_CODE_CALLBACK_PROTOCOL        *This,
  IN EFI_PXE_BASE_CODE_FUNCTION                 Function,
  IN BOOLEAN                                    Received,
  IN UINT32                                     PacketLen,
  IN EFI_PXE_BASE_CODE_PACKET                   *Packet OPTIONAL
  );

Parameters

This

Pointer to the See EFI_PXE_BASE_CODE_PROTOCOL instance.

Function

The PXE Base Code Protocol function that is waiting for an event.

Received

TRUE if the callback is being invoked due to a receive event. FALSE if the callback is being invoked due to a transmit event.

PacketLen

The length, in bytes, of Packet. This field will have a value of zero if this is a wait for receive event.

Packet

If Received is TRUE, a pointer to the packet that was just received; otherwise a pointer to the packet that is about to be transmitted. This field will be NULL if this is not a packet event.

Related Definitions

//******************************************************
// EFI_PXE_BASE_CODE_CALLBACK_STATUS
//******************************************************
typedef enum {
EFI_PXE_BASE_CODE_CALLBACK_STATUS_FIRST,
EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE,
EFI_PXE_BASE_CODE_CALLBACK_STATUS_ABORT,
EFI_PXE_BASE_CODE_CALLBACK_STATUS_LAST
} EFI_PXE_BASE_CODE_CALLBACK_STATUS;

//******************************************************
// EFI_PXE_BASE_CODE_FUNCTION
//******************************************************
typedef enum {
EFI_PXE_BASE_CODE_FUNCTION_FIRST,
EFI_PXE_BASE_CODE_FUNCTION_DHCP,
EFI_PXE_BASE_CODE_FUNCTION_DISCOVER,
EFI_PXE_BASE_CODE_FUNCTION_MTFTP,
EFI_PXE_BASE_CODE_FUNCTION_UDP_WRITE,
EFI_PXE_BASE_CODE_FUNCTION_UDP_READ,
EFI_PXE_BASE_CODE_FUNCTION_ARP,
EFI_PXE_BASE_CODE_FUNCTION_IGMP,
EFI_PXE_BASE_CODE_PXE_FUNCTION_LAST
} EFI_PXE_BASE_CODE_FUNCTION;

Description

This function is invoked when the PXE Base Code Protocol is about to transmit, has received, or is waiting to receive a packet. Parameters Function and Received specify the type of event. Parameters PacketLen and Packet specify the packet that generated the event. If these fields are zero and NULL respectively, then this is a status update callback. If the operation specified by Function is to continue, then CALLBACK_STATUS_CONTINUE should be returned. If the operation specified by Function should be aborted, then CALLBACK_STATUS_ABORT should be returned. Due to the polling nature of UEFI device drivers, a callback function should not execute for more than 5 ms.

The EFI_PXE_BASE_CODE_PROTOCOL.SetParameters() function must be called after a Callback Protocol is installed to enable the use of callbacks.

24.5. Boot Integrity Services Protocol

This section defines the Boot Integrity Services (BIS) protocol, which is used to check a digital signature of a data block against a digital certificate for the purpose of an integrity and authorization check. BIS is primarily used by the Preboot Execution Environment (PXE) Base Code protocol See EFI_PXE_BASE_CODE_PROTOCOL to check downloaded network boot images before executing them. BIS is a UEFI Boot Service Driver, so its services are also available to applications written to this specification until the time of EFI_BOOT_SERVICES.ExitBootServices() . More information about BIS can be found in the Boot Integrity Services Application Programming Interface Version 1.0.

This section defines the Boot Integrity Services Protocol. This protocol is used to check a digital signature of a data block against a digital certificate for the purpose of an integrity and authorization check.

24.5.1. EFI_BIS_PROTOCOL

Summary

The EFI_BIS_PROTOCOL is used to check a digital signature of a data block against a digital certificate for the purpose of an integrity and authorization check.

GUID

#define EFI_BIS_PROTOCOL_GUID \
  {0x0b64aab0,0x5429,0x11d4,\
    {0x98,0x16,0x00,0xa0,0xc9,0x1f,0xad,0xcf}}

Protocol Interface Structure

typedef struct \_EFI_BIS_PROTOCOL {
  EFI_BIS_INITIALIZE                                  Initialize;
  EFI_BIS_SHUTDOWN                                    Shutdown;
  EFI_BIS_FREE                                        Free;
  EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE   GetBootObjectAuthorizationCertificate;
  EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG     GetBootObjectAuthorizationCheckFlag;
  EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN  GetBootObjectAuthorizationUpdateToken;
  EFI_BIS_GET_SIGNATURE_INFO                          GetSignatureInfo;
  EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION            UpdateBootObjectAuthorization;
  EFI_BIS_VERIFY_BOOT_OBJECT                          VerifyBootObject;
  EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL               VerifyObjectWithCredential;
}    EFI_BIS_PROTOCOL;

Parameters

Initialize

Initializes an application instance of the EFI_BIS protocol, returning a handle for the application instance. Other functions in the EFI_BIS protocol require a valid application instance handle obtained from this function. See the EFI_BIS_PROTOCOL.Initialize() function description.

Shutdown

Ends the lifetime of an application instance of the EFI_BIS protocol, invalidating its application instance handle. The application instance handle may no longer be used in other functions in the EFI_BIS protocol. See the EFI_BIS_PROTOCOL.Shutdown() function description.

Free

Frees memory structures allocated and returned by other functions in the EFI_BIS protocol. See the EFI_BIS_PROTOCOL.Free() function description.

GetBootObjectAuthorizationCertificate

Retrieves the current digital certificate (if any) used by the EFI_BIS protocol as the source of authorization for verifying boot objects and altering configuration parameters. See the EFI_BIS_PROTOCOL.GetBootObjectAuthorizationCertificate() function description.

GetBootObjectAuthorizationCheckFlag

Retrieves the current setting of the authorization check flag that indicates whether or not authorization checks are required for boot objects. See the EFI_BIS_PROTOCOL.GetBootObjectAuthorizationCheckFlag() function description.

GetBootObjectAuthorizationUpdateToken

Retrieves an uninterpreted token whose value gets included and signed in a subsequent request to alter the configuration parameters, to protect against attempts to “replay” such a request. See the EFI_BIS_PROTOCOL.GetBootObjectAuthorizationUpdateToken() function description.

GetSignatureInfo

Retrieves information about the digital signature algorithms supported and the identity of the installed authorization certificate, if any. See the EFI_BIS_PROTOCOL.GetSignatureInfo() function description.

UpdateBootObjectAuthorization

Requests that the configuration parameters be altered by installing or removing an authorization certificate or changing the setting of the check flag. See the EFI_BIS_PROTOCOL.UpdateBootObjectAuthorization() function description.

VerifyBootObject

Verifies a boot object according to the supplied digital signature and the current authorization certificate and check flag setting. See the EFI_BIS_PROTOCOL.VerifyBootObject() function description.

VerifyObjectWithCredential

Verifies a data object according to a supplied digital signature and a supplied digital certificate. See the EFI_BIS_PROTOCOL.VerifyObjectWithCredential() function description.

Description

The EFI_BIS_PROTOCOL provides a set of functions as defined in this section. There is no physical device associated with these functions, however, in the context of UEFI every protocol operates on a device. Accordingly, BIS installs and operates on a single abstract device that has only a software representation.

24.5.2. EFI_BIS_PROTOCOL.Initialize()

Summary

Initializes the BIS service, checking that it is compatible with the version requested by the caller. After this call, other BIS functions may be invoked.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BIS_INITIALIZE)(
  IN EFI_BIS_PROTOCOL              *This,
  OUT BIS_APPLICATION_HANDLE       *AppHandle,
  IN OUT EFI_BIS_VERSION           *InterfaceVersion,
  IN EFI_BIS_DATA                  *TargetAddress
  );

Parameters

This

A pointer to the EFI_BIS_PROTOCOL object. The protocol implementation may rely on the actual pointer value and object location, so the caller must not copy the object to a new location.

AppHandle

The function writes the new BIS_APPLICATION_HANDLE if successful, otherwise it writes NULL. The caller must eventually destroy this handle by calling EFI_BIS_PROTOCOL.Shutdown() . Type BIS_APPLICATION_HANDLE is defined in “Related Definitions” below.

InterfaceVersion

On input, the caller supplies the major version number of the interface version desired. The minor version number supplied on input is ignored since interface compatibility is determined solely by the major version number. On output, both the major and minor version numbers are updated with the major and minor version numbers of the interface (and underlying implementation). This update is done whether or not the initialization was successful. Type EFI_BIS_VERSION is defined in “Related Definitions” below.

TargetAddress

Indicates a network or device address of the BIS platform to connect to. Local-platform BIS implementations require that the caller sets TargetAddress.Data to NULL, but otherwise ignores this parameter. BIS implementations that redirect calls to an agent at a remote address must define their own format and interpretation of this parameter outside the scope of this document. For all implementations, if the TargetAddress is an unsupported value, the function fails with the error EFI_UNSUPPORTED. Type EFI_BIS_DATA is defined in “Related Definitions” below.

Related Definitions

//******************************************************
// BIS_APPLICATION_HANDLE
//******************************************************
typedef VOID   *BIS_APPLICATION_HANDLE;

This type is an opaque handle representing an initialized instance of the BIS interface. A BIS_APPLICATION_HANDLE value is returned by the Initialize() function as an “out” parameter. Other BIS functions take a BIS_APPLICATION_HANDLE as an “in” parameter to identify the BIS instance.

//******************************************************
// EFI_BIS_VERSION
//******************************************************
typedef struct \_EFI_BIS_VERSION {
  UINT32          Major;
  UINT32          Minor;
}   EFI_BIS_VERSION;
Major

This describes the major BIS version number. The major version number defines version compatibility. That is, when a new version of the BIS interface is created with new capabilities that are not available in the previous interface version, the major version number is increased.

Minor

This describes a minor BIS version number. This version number is increased whenever a new BIS implementation is built that is fully interface compatible with the previous BIS implementation. This number may be reset when the major version number is increased.

This type represents a version number of the BIS interface. This is used as an “in out” parameter of the Initialize() function for a simple form of negotiation of the BIS interface version between the caller and the BIS implementation.

//******************************************************
// EFI_BIS_VERSION predefined values
// Use these values to initialize EFI_BIS_VERSION.Major
// and to interpret results of Initialize.
//******************************************************
#define BIS_CURRENT_VERSION_MAJOR      BIS_VERSION_1
#define BIS_VERSION_1                  1

These C preprocessor macros supply values for the major version number of an EFI_BIS_VERSION. At the time of initialization, a caller supplies a value to request a BIS interface version. On return, the (IN OUT) parameter is over-written with the actual version of the interface.

//******************************************************
// EFI_BIS_DATA
//
// EFI_BIS_DATA instances obtained from BIS must be freed by
// calling `EFI_BIS_PROTOCOL.Free()`_.
//******************************************************
typedef struct \_EFI_BIS_DATA {
  UINT32             Length;
  UINT8              *Data;
}   EFI_BIS_DATA;
Length

The length of the data buffer in bytes.

Data

A pointer to the raw data buffer.

This type defines a structure that describes a buffer. BIS uses this type to pass back and forth most large objects such as digital certificates, strings, etc. Several of the BIS functions allocate a EFI_BIS_DATA* and return it as an “out” parameter. The caller must eventually free any allocated EFI_BIS_DATA* using the EFI_BIS_PROTOCOL.Free() function.

Description

This function must be the first BIS function invoked by an application. It passes back a BIS_APPLICATION_HANDLE value that must be used in subsequent BIS functions. The handle must be eventually destroyed by a call to the EFI_BIS_PROTOCOL.Shutdown() function, thus ending that handle’s lifetime. After the handle is destroyed, BIS functions may no longer be called with that handle value. Thus all other BIS functions may only be called between a pair of EFI_BIS_PROTOCOL.Initialize() and Shutdown() functions.

There is no penalty for calling Initialize() multiple times. Each call passes back a distinct handle value. Each distinct handle must be destroyed by a distinct call to Shutdown(). The lifetimes of handles created and destroyed with these functions may be overlapped in any way.

Status Codes Returned

EFI_SUCCESS

The function completed successfully.

EFI_INCOMPATIBLE_VERSION

The InterfaceVersion.Major requested by the caller was not compatible with the interface version of the implementation.
The InterfaceVersion.Major has been updated with the current interface version.

EFI_UNSUPPORTED

This is a local-platform implementation and TargetAddress.Data was not NULL, or TargetAddress.Data was any other value that was not supported by the implementation.

EFI_OUT_OF_RESOURCES

The function failed due to lack of memory or other resources.

EFI_DEVICE_ERROR

The function encountered an unexpected internal failure while initializing a cryptographic software module, or
No cryptographic software module with compatible version was found, or
A resource limitation was encountered while using a cryptographic software module.

EFI_INVALID_PARAMETER

The This parameter supplied by the caller is NULL or does not reference a valid EFI_BIS_PROTOCOL object, or
The AppHandle parameter supplied by the caller is NULL or an invalid memory reference, or
The InterfaceVersion parameter supplied by the caller is NULL or an invalid memory reference, or
The TargetAddress parameter supplied by the caller is NULL or an invalid memory reference.

24.5.3. EFI_BIS_PROTOCOL.Shutdown()

Summary

Shuts down an application’s instance of the BIS service, invalidating the application handle. After this call, other BIS functions may no longer be invoked using the application handle value.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BIS_SHUTDOWN)(
  IN BIS_APPLICATION_HANDLE    AppHandle
  );

Parameters

AppHandle

An opaque handle that identifies the caller’s instance of initialization of the BIS service. Type BIS_APPLICATION_HANDLE is defined in the EFI_BIS_PROTOCOL.Initialize() function description.

Description

This function shuts down an application’s instance of the BIS service, invalidating the application handle. After this call, other BIS functions may no longer be invoked using the application handle value.

This function must be paired with a preceding successful call to the Initialize() function. The lifetime of an application handle extends from the time the handle was returned from Initialize() until the time the handle is passed to Shutdown(). If there are other remaining handles whose lifetime is still active, they may still be used in calling BIS functions.

The caller must free all memory resources associated with this AppHandle that were allocated and returned from other BIS functions before calling Shutdown(). Memory resources are freed using the EFI_BIS_PROTOCOL.Free() function. Failure to free such memory resources is a caller error, however, this function does not return an error code under this circumstance. Further attempts to access the outstanding memory resources cause unspecified results.

Status Codes Returned

EFI_SUCCESS

The function completed successfully.

EFI_NO_MAPPING

The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.

EFI_DEVICE_ERROR

The function encountered an unexpected internal error while returning resources associated with a cryptographic software module, or
The function encountered an internal error while trying to shut down a cryptographic software module.

EFI_OUT_OF_RESOURCES

The function failed due to lack of memory or other resources.

24.5.4. EFI_BIS_PROTOCOL.Free()

Summary

Frees memory structures allocated and returned by other functions in the EFI_BIS protocol.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BIS_FREE)(
  IN BIS_APPLICATION_HANDLE   AppHandle,
  IN EFI_BIS_DATA             *ToFree
);

Parameters

AppHandle

An opaque handle that identifies the caller’s instance of initialization of the BIS service. Type BIS_APPLICATION_HANDLE is defined in the EFI_BIS_PROTOCOL.Initialize() function description.

ToFree

An EFI_BIS_DATA* and associated memory block to be freed. This EFI_BIS_DATA* must have been allocated by one of the other BIS functions. Type EFI_BIS_DATA is defined in the Initialize() function description.

Description

This function deallocates an EFI_BIS_DATA* and associated memory allocated by one of the other BIS functions.

Callers of other BIS functions that allocate memory in the form of an EFI_BIS_DATA* must eventually call this function to deallocate the memory before calling the EFI_BIS_PROTOCOL.Shutdown() function for the application handle under which the memory was allocated. Failure to do so causes unspecified results, and the continued correct operation of the BIS service cannot be guaranteed.

Status Codes Returned

EFI_SUCCESS

The function completed successfully.

EFI_NO_MAPPING

The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.

EFI_INVALID_PARAMETER

The ToFree parameter is not or is no longer a memory resource associated with this AppHandle.

EFI_OUT_OF_RESOURCES

The function failed due to lack of memory or other resources.

24.5.5. EFI_BIS_PROTOCOL.GetBootObjectAuthorizationCertificate()

Summary

Retrieves the certificate that has been configured as the identity of the organization designated as the source of authorization for signatures of boot objects.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE)(
  IN BIS_APPLICATION_HANDLE         AppHandle,
  OUT EFI_BIS_DATA                  **Certificate
  );

Parameters

AppHandle

An opaque handle that identifies the caller’s instance of initialization of the BIS service. Type BIS_APPLICATION_HANDLE is defined in the EFI_BIS_PROTOCOL.Initialize() function description.

Certificate

The function writes an allocated EFI_BIS_DATA* containing the Boot Object Authorization Certificate object. The caller must eventually free the memory allocated by this function using the function EFI_BIS_PROTOCOL.Free() . Type EFI_BIS_DATA is defined in the Initialize() function description.

Description

This function retrieves the certificate that has been configured as the identity of the organization designated as the source of authorization for signatures of boot objects.

Status Codes Returned

EFI_SUCCESS

The function completed successfully.

EFI_NO_MAPPING

The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.

EFI_NOT_FOUND

There is no Boot Object Authorization Certificate currently installed.

EFI_OUT_OF_RESOURCES

The function failed due to lack of memory or other resources.

EFI_INVALID_PARAMETER

The Certificate parameter supplied by the caller is NULL or an invalid memory reference.

24.5.6. EFI_BIS_PROTOCOL.GetBootObjectAuthorizationCheckFlag()

Summary

Retrieves the current status of the Boot Authorization Check Flag.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG)(
  IN BIS_APPLICATION_HANDLE         AppHandle,
  OUT BOOLEAN                       *CheckIsRequired
  );

Parameters

AppHandle

An opaque handle that identifies the caller’s instance of initialization of the BIS service. Type BIS_APPLICATION_HANDLE is defined in the EFI_BIS_PROTOCOL.Initialize() function description.

CheckIsRequired

The function writes the value TRUE if a Boot Authorization Check is currently required on this platform, otherwise the function writes FALSE.

Description

This function retrieves the current status of the Boot Authorization Check Flag (in other words, whether or not a Boot Authorization Check is currently required on this platform).

Status Codes Returned

EFI_SUCCESS

The function completed successfully.

EFI_NO_MAPPING

The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.

EFI_OUT_OF_RESOURCES

The function failed due to lack of memory or other resources.

EFI_INVALID_PARAMETER

The CheckIsRequired parameter supplied by the caller is NULL or an invalid memory reference.

24.5.7. EFI_BIS_PROTOCOL.GetBootObjectAuthorizationUpdateToken()

Summary

Retrieves a unique token value to be included in the request credential for the next update of any parameter in the Boot Object Authorization set (Boot Object Authorization Certificate and Boot Authorization Check Flag).

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN)(
  IN BIS_APPLICATION_HANDLE            AppHandle,
  OUT EFI_BIS_DATA                     **UpdateToken
  );

Parameters

AppHandle

An opaque handle that identifies the caller’s instance of initialization of the BIS service. Type BIS_APPLICATION_HANDLE is defined in the EFI_BIS_PROTOCOL.Initialize() function description.

UpdateToken

The function writes an allocated EFI_BIS_DATA* containing the new unique update token value. The caller must eventually free the memory allocated by this function using the function EFI_BIS_PROTOCOL.Free() . Type EFI_BIS_DATA is defined in the Initialize() function description.

Description

This function retrieves a unique token value to be included in the request credential for the next update of any parameter in the Boot Object Authorization set (Boot Object Authorization Certificate and Boot Authorization Check Flag). The token value is unique to this platform, parameter set, and instance of parameter values. In particular, the token changes to a new unique value whenever any parameter in this set is changed.

Status Codes Returned

EFI_SUCCESS

The function completed successfully.

EFI_NO_MAPPING

The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.

EFI_OUT_OF_RESOURCES

The function failed due to lack of memory or other resources.

EFI_DEVICE_ERROR

The function encountered an unexpected internal error in a cryptographic software module.

EFI_INVALID_PARAMETER

The UpdateToken parameter supplied by the caller is NULL or an invalid memory reference.

24.5.8. EFI_BIS_PROTOCOL.GetSignatureInfo()

Summary

Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and key-length combinations that the platform supports.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BIS_GET_SIGNATURE_INFO)(
  IN BIS_APPLICATION_HANDLE            AppHandle,
  OUT EFI_BIS_DATA                     **SignatureInfo
  );

Parameters

AppHandle

An opaque handle that identifies the caller’s instance of initialization of the BIS service. Type BIS_APPLICATION_HANDLE is defined in the EFI_BIS_PROTOCOL.Initialize() function description.

SignatureInfo

The function writes an allocated EFI_BIS_DATA* containing the array of EFI_BIS_SIGNATURE_INFO structures representing the supported digital certificate identifier, algorithm, and key length combinations. The caller must eventually free the memory allocated by this function using the function EFI_BIS_PROTOCOL.Free() . Type EFI_BIS_DATA is defined in the Initialize() function description. Type EFI_BIS_SIGNATURE_INFO is defined in “Related Definitions” below.

Related Definitions

//******************************************************
// EFI_BIS_SIGNATURE_INFO
//******************************************************
typedef struct \_EFI_BIS_SIGNATURE_INFO {
  BIS_CERT_ID           CertificateID;
  BIS_ALG_ID            AlgorithmID;
  UINT16                KeyLength;
}   EFI_BIS_SIGNATURE_INFO;
CertificateID

A shortened value identifying the platform’s currently configured Boot Object Authorization Certificate, if one is currently configured. The shortened value is derived from the certificate as defined in the Related Definition for BIS_CERT_ID below. If there is no certificate currently configured, the value is one of the reserved BIS_CERT_ID_XXX values defined below. Type BIS_CERT_ID and its predefined reserved values are defined in “Related Definitions” below.

AlgorithmID

A predefined constant representing a particular digital signature algorithm. Often this represents a combination of hash algorithm and encryption algorithm, however, it may also represent a standalone digital signature algorithm. Type BIS_ALG_ID and its permitted values are defined in “Related Definitions” below.

KeyLength

The length of the public key, in bits, supported by this digital signature algorithm.

This type defines a digital certificate, digital signature algorithm, and key-length combination that may be supported by the BIS implementation. This type is returned by GetSignatureInfo() to describe the combination(s) supported by the implementation.

//******************************************************
// BIS_GET_SIGINFO_COUNT macro
//   Tells how many EFI_BIS_SIGNATURE_INFO elements are contained
//   in a EFI_BIS_DATA struct pointed to by the provided
//   EFI_BIS_DATA*.
//******************************************************
#define BIS_GET_SIGINFO_COUNT(BisDataPtr) \
  ((BisDataPtr)->Length/sizeof(EFI_BIS_SIGNATURE_INFO))
BisDataPtr

Supplies the pointer to the target EFI_BIS_DATA structure.

(return value)

The number of EFI_BIS_SIGNATURE_INFO elements contained in the array.

This macro computes how many EFI_BIS_SIGNATURE_INFO elements are contained in an EFI_BIS_DATA structure returned from GetSignatureInfo(). The number returned is the count of items in the list of supported digital certificate, digital signature algorithm, and key-length combinations.

//*******************************************************
// BIS_GET_SIGINFO_ARRAY macro
//   Produces a EFI_BIS_SIGNATURE_INFO* from a given
//   EFI_BIS_DATA.*
//*******************************************************
#define BIS_GET_SIGINFO_ARRAY(BisDataPtr) \
  ((EFI_BIS_SIGNATURE_INFO*)(BisDataPtr)->Data)
BisDataPtr

Supplies the pointer to the target EFI_BIS_DATA structure.

(return value)

The pointer to the EFI_BIS_SIGNATURE_INFO array, cast as an EFI_BIS_SIGNATURE_INFO*.

This macro returns a pointer to the EFI_BIS_SIGNATURE_INFO array contained in an EFI_BIS_DATA structure returned from GetSignatureInfo() representing the list of supported digital certificate, digital signature algorithm, and key-length combinations.

//******************************************************
// BIS_CERT_ID
//******************************************************
typedef UINT32      BIS_CERT_ID;

This type represents a shortened value that identifies the platform’s currently configured Boot Object Authorization Certificate. The value is the first four bytes, in “little-endian” order, of the SHA-1 hash of the certificate, except that the most-significant bits of the second and third bytes are reserved, and must be set to zero regardless of the outcome of the hash function. This type is included in the array of values returned from the GetSignatureInfo() function to indicate the required source of a signature for a boot object or a configuration update request. There are a few predefined reserved values with special meanings as described below.

//*******************************************************
// BIS_CERT_ID predefined values
//   Currently defined values for EFI_BIS_SIGNATURE_INFO.
//   CertificateId.
//*******************************************************
#define BIS_CERT_ID_DSA   BIS_ALG_DSA   //CSSM_ALGID_DSA
#define BIS_CERT_ID_RSA_MD5  BIS_ALG_RSA_MD5   //CSSM_ALGID_MD5_WITH_RSA

These C preprocessor symbols provide values for the BIS_CERT_ID type. These values are used when the platform has no configured Boot Object Authorization Certificate. They indicate the signature algorithm that is supported by the platform. Users must be careful to avoid constructing Boot Object Authorization Certificates that transform to BIS_CERT_ID values that collide with these predefined values or with the BIS_CERT_ID values of other Boot Object Authorization Certificates they use.

//*******************************************************
// BIS_CERT_ID_MASK
//   The following is a mask value that gets applied to the
//   truncated hash of a platform Boot Object Authorization
//   Certificate to create the CertificateId. A CertificateId
//   must not have any bits set to the value 1 other than bits in
//   this mask.
//*******************************************************
#define BIS_CERT_ID_MASK (0xFF7F7FFF)

This C preprocessor symbol may be used as a bit-wise “AND” value to transform the first four bytes (in little-endian order) of a SHA-1 hash of a certificate into a certificate ID with the “reserved” bits properly set to zero.

//*******************************************************
// BIS_ALG_ID
//*******************************************************
typedef UINT16 BIS_ALG_ID;

This type represents a digital signature algorithm. A digital signature algorithm is often composed of a particular combination of secure hash algorithm and encryption algorithm. This type also allows for digital signature algorithms that cannot be decomposed. Predefined values for this type are as defined below.

//*******************************************************
// BIS_ALG_ID predefined values
//  Currently defined values for EFI_BIS_SIGNATURE_INFO.
//  AlgorithmID. The exact numeric values come from "Common
//  Data Security Architecture (CDSA) Specification."
//*******************************************************
#define BIS_ALG_DSA  (41)   //CSSM_ALGID_DSA
#define BIS_ALG_RSA_MD5  (42)   //CSSM_ALGID_MD5_WITH_RSA

These values represent the two digital signature algorithms predefined for BIS. Each implementation of BIS must support at least one of these digital signature algorithms. Values for the digital signature algorithms are chosen by an industry group known as The Open Group. Developers planning to support additional digital signature algorithms or define new digital signature algorithms should refer to The Open Group for interoperable values to use.

Description

This function retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and key-length combinations that the platform supports. The list is an array of (certificate id, algorithm id, key length) triples, where the certificate id is derived from the platform’s Boot Object Authorization Certificate as described in the Related Definition for BIS_CERT_ID above, the algorithm id represents the combination of signature algorithm and hash algorithm, and the key length is expressed in bits. The number of array elements can be computed using the Length field of the retrieved EFI_BIS_DATA*.

The retrieved list is in order of preference. A digital signature algorithm for which the platform has a currently configured Boot Object Authorization Certificate is preferred over any digital signature algorithm for which there is not a currently configured Boot Object Authorization Certificate. Thus the first element in the list has a CertificateID representing a Boot Object Authorization Certificate if the platform has one configured. Otherwise the CertificateID of the first element in the list is one of the reserved values representing a digital signature algorithm.

Status Codes Returned

EFI_SUCCESS

The function completed successfully.

EFI_NO_MAPPING

The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.

EFI_OUT_OF_RESOURCES

The function failed due to lack of memory or other resources.

EFI_DEVICE_ERROR

The function encountered an unexpected internal error in a cryptographic software module, or
The function encountered an unexpected internal consistency check failure (possible corruption of stored Boot Object Authorization Certificate).

EFI_INVALID_PARAMETER

The SignatureInfo parameter supplied by the caller is NULL or an invalid memory reference.

24.5.9. EFI_BIS_PROTOCOL.UpdateBootObjectAuthorization()

Summary

Updates one of the configurable parameters of the Boot Object Authorization set (Boot Object Authorization Certificate or Boot Authorization Check Flag).

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION)(
  IN BIS_APPLICATION_HANDLE      AppHandle,
  IN EFI_BIS_DATA                *RequestCredential,
  OUT EFI_BIS_DATA               **NewUpdateToken
  );

Parameters

AppHandle

An opaque handle that identifies the caller’s instance of initialization of the BIS service. Type BIS_APPLICATION_HANDLE is defined in the EFI_BIS_PROTOCOL.Initialize() function description.

RequestCredential

This is a Signed Manifest with embedded attributes that carry the details of the requested update. The required syntax of the Signed Manifest is described in the Related Definition for Manifest Syntax below. The key used to sign the request credential must be the private key corresponding to the public key in the platform’s configured Boot Object Authorization Certificate. Authority to update parameters in the Boot Object Authorization set cannot be delegated.

If there is no Boot Object Authorization Certificate, the request credential may be signed with any private key. In this case, this function interacts with the user in a platform-specific way to determine whether the operation should succeed. Type EFI_BIS_DATA is defined in the Initialize() function description.

NewUpdateToken

The function writes an allocated EFI_BIS_DATA* containing the new unique update token value. The caller must eventually free the memory allocated by this function using the function EFI_BIS_PROTOCOL.Free() . Type EFI_BIS_DATA is defined in the Initialize() function description.

Related Definitions

//**********************************************************
// Manifest Syntax

//**********************************************************

The Signed Manifest consists of three parts grouped together into an Electronic Shrink Wrap archive as described in [SM spec]: a manifest file, a signer’s information file, and a signature block file. These three parts, along with examples are described in the following sections. In these examples, text in parentheses is a description of the text that would appear in the signed manifest. Text outside of parentheses must appear exactly as shown. Also note that manifest files and signer’s information files must conform to a 72-byte line-length limit. Continuation lines (lines beginning with a single “space” character) are used for lines longer than 72 bytes. The examples given here follow this rule for continuation lines.

Note that the manifest file and signer’s information file parts of a Signed Manifest are ASCII text files. In cases where these files contain a base-64 encoded string, the string is an ASCII string before base-64 encoding.

//**********************************************************
// Manifest File Example
//**********************************************************

The manifest file must include a section referring to a memory-type data object with the reserved name as shown in the example below. This data object is a zero-length object whose sole purpose in the manifest is to serve as a named collection point for the attributes that carry the details of the requested update. The attributes are also contained in the manifest file. An example manifest file is shown below.

Manifest-Version: 2.0
ManifestPersistentId: (base-64 representation of a unique GUID)

Name: memory:UpdateRequestParameters
Digest-Algorithms: SHA-1
SHA-1-Digest: (base-64 representation of a SHA-1 digest of zero-length buffer)
X-Intel-BIS-ParameterSet: (base-64 representation of BootObjectAuthorizationSetGUID)
X-Intel-BIS-ParameterSetToken: (base-64 representation of the current update token)
X-Intel-BIS-ParameterId: (base-64 representation of
"BootObjectAuthorizationCertificate" or
"BootAuthorizationCheckFlag")
X-Intel-BIS-ParameterValue: (base-64 representation of certificate or
single-byte boolean flag)

A line-by-line description of this manifest file is as follows.

Manifest-Version: 2.0

This is a standard header line that all signed manifests have. It must appear exactly as shown.

ManifestPersistentId: (base-64 representation of a unique GUID)

The left-hand string must appear exactly as shown. The right-hand string must be a unique GUID for every manifest file created. The Win32 function UuidCreate() can be used for this on Win32 systems. The GUID is a binary value that must be base-64 encoded. Base-64 is a simple encoding scheme for representing binary values that uses only printing characters. Base-64 encoding is described in [BASE-64].

Name: memory:UpdateRequestParameters

This identifies the manifest section that carries a dummy zero-length data object serving as the collection point for the attribute values appearing later in this manifest section (lines prefixed with ” X-Intel-BIS- “). The string ” memory:UpdateRequestParameters ” must appear exactly as shown.

Digest-Algorithms: SHA-1

This enumerates the digest algorithms for which integrity data is included for the data object. These are required even though the data object is zero-length. For systems with DSA signing, SHA-1 hash, and 1024-bit key length, the digest algorithm must be ” SHA-1.” For systems with RSA signing, MD5 hash, and 512-bit key length, the digest algorithm must be ” MD5.” Multiple algorithms can be specified as a whitespace-separated list. For every digest algorithm XXX listed, there must also be a corresponding XXX-Digest line.

SHA-1-Digest: (base-64 representation of a SHA-1 digest of zero-length buffer)

Gives the corresponding digest value for the dummy zero-length data object. The value is base-64 encoded. Note that for both MD5 and SHA-1, the digest value for a zero-length data object is not zero.

X-Intel-BIS-ParameterSet: (base-64 representation of BootObjectAuthorizationSetGUID)

A named attribute value that distinguishes updates of BIS parameters from updates of other parameters. The left-hand attribute-name keyword must appear exactly as shown. The GUID value for the right-hand side is always the same, and can be found under the preprocessor symbol BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE. The representation inserted into the manifest is base-64 encoded.

Note the ” X-Intel-BIS- ” prefix on this and the following attributes. The ” X- ” part of the prefix was chosen to avoid collisions with future reserved keywords defined by future versions of the signed manifest specification. The ” Intel-BIS- ” part of the prefix was chosen to avoid collisions with other user-defined attribute names within the user-defined attribute name space.

X-Intel-BIS-ParameterSetToken: (base-64 representation of the current update token)

A named attribute value that makes this update of BIS parameters different from any other on the same target platform. The left-hand attribute-name keyword must appear exactly as shown. The value for the right-hand side is generally different for each update-request manifest generated. The value to be base-64 encoded is retrieved through the functions EFI_BIS_PROTOCOL.GetBootObjectAuthorizationUpdateToken() or EFI_BIS_PROTOCOL.UpdateBootObjectAuthorization() .

X-Intel-BIS-ParameterId: (base-64 representation of
"BootObjectAuthorizationCertificate" or
"BootAuthorizationCheckFlag")

A named attribute value that indicates which BIS parameter is to be updated. The left-hand attribute-name keyword must appear exactly as shown. The value for the right-hand side is the base-64 encoded representation of one of the two strings shown.

X-Intel-BIS-ParameterValue: (base-64 representation of
certificate or
single-byte boolean flag)

A named attribute value that indicates the new value to be set for the indicated parameter. The left-hand attribute-name keyword must appear exactly as shown. The value for the right-hand side is the appropriate base-64 encoded new value to be set. In the case of the Boot Object Authorization Certificate, the value is the new digital certificate raw data. A zero-length value removes the certificate altogether. In the case of the Boot Authorization Check Flag, the value is a single-byte Boolean value, where a nonzero value “turns on” the check and a zero value “turns off” the check.

//**********************************************************
// Signer’s Information File Example
//**********************************************************

The signer’s information file must include a section whose name matches the reserved data object section name of the section in the Manifest file. This section in the signer’s information file carries the integrity data for the attributes in the corresponding section in the manifest file. An example signer’s information file is shown below.

Signature-Version: 2.0
SignerInformationPersistentId: (base-64 representation of a unique GUID)
SignerInformationName: BIS_UpdateManifestSignerInfoName

Name: memory:UpdateRequestParameters
Digest-Algorithms: SHA-1
SHA-1-Digest: (base-64 representation of a SHA-1 digest of the
corresponding manifest section)

A line-by-line description of this signer’s information file is as follows.

Signature-Version: 2.0

This is a standard header line that all signed manifests have. It must appear exactly as shown.

SignerInformationPersistentId: (base-64 representation of a unique GUID)

The left-hand string must appear exactly as shown. The right-hand string must be a unique GUID for every signer’s information file created. The Win32 function UuidCreate() can be used for this on Win32 systems. The GUID is a binary value that must be base-64 encoded. Base-64 is a simple encoding scheme for representing binary values that uses only printing characters. Base-64 encoding is described in [BASE-64].

SignerInformationName: BIS_UpdateManifestSignerInfoName

The left-hand string must appear exactly as shown. The right-hand string must appear exactly as shown.

Name: memory:UpdateRequestParameters

This identifies the section in the signer’s information file corresponding to the section with the same name in the manifest file described earlier. The string ” memory:UpdateRequestParameters ” must appear exactly as shown.

Digest-Algorithms: SHA-1

This enumerates the digest algorithms for which integrity data is included for the corresponding manifest section. Strings identifying digest algorithms are the same as in the manifest file. The digest algorithms specified here must match those specified in the manifest file. For every digest algorithm XXX listed, there must also be a corresponding XXX-Digest line.

SHA-1-Digest: (base-64 representation of a SHA-1 digest of the corresponding manifest section)

Gives the corresponding digest value for the corresponding manifest section. The value is base-64 encoded. Note that for the purpose of computing the hash of the manifest section, the manifest section starts at the beginning of the opening ” Name: ” keyword and continues up to, but not including, the next section’s ” Name: ” keyword or the end-of-file. Thus the hash includes the blank line(s) at the end of a section and any newline(s) preceding the next ” Name: ” keyword or end-of-file.

//**********************************************************
// Signature Block File Example
//**********************************************************

A signature block file is a raw binary file (not base-64 encoded) that is a PKCS#7 defined format signature block. The signature block covers exactly the contents of the signer’s information file. There must be a correspondence between the name of the signer’s information file and the signature block file. The base name matches, and the three-character extension is modified to reflect the signature algorithm used according to the following rules:

  • DSA signature algorithm (which uses SHA-1 hash): extension is DSA.

  • RSA signature algorithm with MD5 hash: extension is RSA.

So for example with a signer’s information file name of “myinfo.SF,” the corresponding DSA signature block file name would be “myinfo.DSA.”

The format of a signature block file is defined in [PKCS].

//**********************************************************
// "X-Intel-BIS-ParameterSet" Attribute value
// Binary Value of "X-Intel-BIS-ParameterSet" Attribute.
// (Value is Base-64 encoded in actual signed manifest).
//**********************************************************

#define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \
  {0xedd35e31,0x7b9,0x11d2,{0x83,0xa3,0x0,0xa0,0xc9,0x1f,0xad,0xcf}}

This preprocessor symbol gives the value for an attribute inserted in signed manifests to distinguish updates of BIS parameters from updates of other parameters. The representation inserted into the manifest is base-64 encoded.

Description

This function updates one of the configurable parameters of the Boot Object Authorization set (Boot Object Authorization Certificate or Boot Authorization Check Flag). It passes back a new unique update token that must be included in the request credential for the next update of any parameter in the Boot Object Authorization set. The token value is unique to this platform, parameter set, and instance of parameter values. In particular, the token changes to a new unique value whenever any parameter in this set is changed.

Status Codes Returned

EFI_SUCCESS

The function completed successfully.

EFI_NO_MAPPING

The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.

EFI_OUT_OF_RESOURCES

The function failed due to lack of memory or other resources.

EFI_DEVICE_ERROR

The function encountered an unexpected internal error in a cryptographic software module.

EFI_SECURITY_VIOLATION

The signed manifest supplied as the RequestCredential parameter was invalid (could not be parsed), or
The signed manifest supplied as the RequestCredential parameter failed to verify using the installed Boot Object Authorization Certificate or the signer’s Certificate in RequestCredential, or Platform-specific authorization failed, or The signed manifest supplied as the RequestCredential parameter did not include the X-Intel-BIS-ParameterSet attribute value, or
The X-Intel-BIS-ParameterSet attribute value supplied did not match the required GUID value, or
The signed manifest supplied as the RequestCredential parameter did not include the X-Intel-BIS-ParameterSetToken attribute value, or
The X-Intel-BIS-ParameterSetToken attribute value supplied did not match the platform’s current update-token value, or
The signed manifest supplied as the RequestCredential parameter did not include the X-Intel-BIS-ParameterId attribute value, or
The X-Intel-BIS-ParameterId attribute value supplied did not match one of the permitted values, or
The signed manifest supplied as the RequestCredential parameter did not include the X-Intel-BIS-ParameterValue attribute value, or
Any other required attribute value was missing, or
The new certificate supplied was too big to store, or
The new certificate supplied was invalid (could not be parsed), or
The new certificate supplied had an unsupported combination of key algorithm and key length, or
The new check flag value supplied is the wrong length (1 byte), or
The signed manifest supplied as the RequestCredential parameter did not include a signer certificate, or
The signed manifest supplied as the RequestCredential parameter did not include the manifest section named ” memory:UpdateRequestParameters,” or
The signed manifest supplied as the RequestCredential parameter had a signing certificate with an unsupported public-key algorithm, or
The manifest section named
memory:UpdateRequestParameters ” did not include a digest with a digest algorithm corresponding to the signing certificate’s public key algorithm, or
The zero-length data object referenced by the manifest section named
memory:UpdateRequestParameters” did not verify with the digest supplied in that manifest section, or
The signed manifest supplied as the RequestCredential parameter did not include a signer’s information file with the SignerInformationName identifying attribute value ” * BIS_UpdateManifestSignerInfoName,*” or
There were no signers associated with the identified signer’s information file, or
There was more than one signer associated with the identified signer’s information file, or
Any other unspecified security violation occurred.

EFI_DEVICE_ERROR

An unexpected internal error occurred while analyzing the new certificate’s key algorithm, or
An unexpected internal error occurred while attempting to retrieve the public key algorithm of the manifest’s signer’s certificate, or
An unexpected internal error occurred in a cryptographic software module.

EFI_INVALID_PARAMETER

The RequestCredential parameter supplied by the caller is NULL or an invalid memory reference, or
The RequestCredential.Data parameter supplied by the caller is NULL or an invalid memory reference, or
The NewUpdateToken parameter supplied by the caller is NULL or an invalid memory reference.

24.5.10. EFI_BIS_PROTOCOL.VerifyBootObject()

Summary

Verifies the integrity and authorization of the indicated data object according to the indicated credentials.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BIS_VERIFY_BOOT_OBJECT)(
  IN BIS_APPLICATION_HANDLE      AppHandle,
  IN EFI_BIS_DATA                *Credentials,
  IN EFI_BIS_DATA                *DataObject,
  OUT BOOLEAN                    *IsVerified
  );

Parameters

AppHandle

An opaque handle that identifies the caller’s instance of initialization of the BIS service. Type BIS_APPLICATION_HANDLE is defined in the EFI_BIS_PROTOCOL.Initialize() function description.

Credentials

A Signed Manifest containing verification information for the indicated data object. The Manifest signature itself must meet the requirements described below. This parameter is optional if a Boot Authorization Check is currently not required on this platform ( Credentials.Data may be NULL ), otherwise this parameter is required. The required syntax of the Signed Manifest is described in the Related Definition for Manifest Syntax below. Type EFI_BIS_DATA is defined in the Initialize() function description.

DataObject

An in-memory copy of the raw data object to be verified. Type EFI_BIS_DATA is defined in the Initialize() function description.

IsVerified

The function writes TRUE if the verification succeeded, otherwise FALSE.

Related Definitions

//**********************************************************
// Manifest Syntax
//**********************************************************

The Signed Manifest consists of three parts grouped together into an Electronic Shrink Wrap archive as described in [SM spec]: a manifest file, a signer’s information file, and a signature block file. These three parts along with examples are described in the following sections. In these examples, text in parentheses is a description of the text that would appear in the signed manifest. Text outside of parentheses must appear exactly as shown. Also note that manifest files and signer’s information files must conform to a 72-byte line-length limit. Continuation lines (lines beginning with a single “space” character) are used for lines longer than 72 bytes. The examples given here follow this rule for continuation lines.

Note that the manifest file and signer’s information file parts of a Signed Manifest are ASCII text files. In cases where these files contain a base-64 encoded string, the string is an ASCII string before base-64 encoding.

//**********************************************************
// Manifest File Example
//**********************************************************

The manifest file must include a section referring to a memory-type data object with the reserved name as shown in the example below. This data object is the Boot Object to be verified. An example manifest file is shown below.

Manifest-Version: 2.0
ManifestPersistentId: (base-64 representation of a unique GUID)

Name: memory:BootObject
Digest-Algorithms: SHA-1
SHA-1-Digest: (base-64 representation of a SHA-1 digest of the boot object)

A line-by-line description of this manifest file is as follows.

Manifest-Version: 2.0

This is a standard header line that all signed manifests have. It must appear exactly as shown.

ManifestPersistentId: (base-64 representation of a unique GUID)

The left-hand string must appear exactly as shown. The right-hand string must be a unique GUID for every manifest file created. The Win32 function UuidCreate() can be used for this on Win32 systems. The GUID is a binary value that must be base-64 encoded. Base-64 is a simple encoding scheme for representing binary values that uses only printing characters. Base-64 encoding is described in [BASE-64].

Name: memory:BootObject

This identifies the section that carries the integrity data for the Boot Object. The string ” memory:BootObject ” must appear exactly as shown. Note that the Boot Object cannot be found directly from this manifest. A caller verifying the Boot Object integrity must load the Boot Object into memory and specify its memory location explicitly to this verification function through the DataObject parameter.

Digest-Algorithms: SHA-1

This enumerates the digest algorithms for which integrity data is included for the data object. For systems with DSA signing, SHA-1 hash, and 1024-bit key length, the digest algorithm must be ” SHA-1.” For systems with RSA signing, MD5 hash, and 512-bit key length, the digest algorithm must be ” MD5.” Multiple algorithms can be specified as a whitespace-separated list. For every digest algorithm XXX listed, there must also be a corresponding XXX-Digest line.

SHA-1-Digest: (base-64 representation of a SHA-1 digest of the boot object)

Gives the corresponding digest value for the data object. The value is base-64 encoded.

//**********************************************************
// Signer’s Information File Example
//**********************************************************

The signer’s information file must include a section whose name matches the reserved data object section name of the section in the Manifest file. This section in the signer’s information file carries the integrity data for the corresponding section in the manifest file. An example signer’s information file is shown below.

Signature-Version: 2.0
SignerInformationPersistentId: (base-64 representation of a unique GUID)
SignerInformationName: BIS_VerifiableObjectSignerInfoName

Name: memory:BootObject
Digest-Algorithms: SHA-1
SHA-1-Digest: (base-64 representation of a SHA-1 digest of the corresponding manifest section)

A line-by-line description of this signer’s information file is as follows.

Signature-Version: 2.0

This is a standard header line that all signed manifests have. It must appear exactly as shown.

SignerInformationPersistentId: (base-64 representation of a unique GUID)

The left-hand string must appear exactly as shown. The right-hand string must be a unique GUID for every signer’s information file created. The Win32 function UuidCreate() can be used for this on Win32 systems. The GUID is a binary value that must be base-64 encoded. Base-64 is a simple encoding scheme for representing binary values that uses only printing characters. Base-64 encoding is described in [BASE-64].

SignerInformationName: BIS_VerifiableObjectSignerInfoName

The left-hand string must appear exactly as shown. The right-hand string must appear exactly as shown.

Name: memory:BootObject

This identifies the section in the signer’s information file corresponding to the section with the same name in the manifest file described earlier. The string ” memory:BootObject ” must appear exactly as shown.

Digest-Algorithms: SHA-1

This enumerates the digest algorithms for which integrity data is included for the corresponding manifest section. Strings identifying digest algorithms are the same as in the manifest file. The digest algorithms specified here must match those specified in the manifest file. For every digest algorithm XXX listed, there must also be a corresponding XXX-Digest line.

SHA-1-Digest: (base-64 representation of a SHA-1 digest of the corresponding manifest section)

Gives the corresponding digest value for the corresponding manifest section. The value is base-64 encoded. Note that for the purpose of computing the hash of the manifest section, the manifest section starts at the beginning of the opening ” Name: ” keyword and continues up to, but not including, the next section’s ” Name: ” keyword or the end-of-file. Thus the hash includes the blank line(s) at the end of a section and any newline(s) preceding the next ” Name: ” keyword or end-of-file.

//**********************************************************
// Signature Block File Example
//**********************************************************

A signature block file is a raw binary file (not base-64 encoded) that is a PKCS#7 defined format signature block. The signature block covers exactly the contents of the signer’s information file. There must be a correspondence between the name of the signer’s information file and the signature block file. The base name matches, and the three-character extension is modified to reflect the signature algorithm used according to the following rules:

  • DSA signature algorithm (which uses SHA-1 hash): extension is DSA.

  • RSA signature algorithm with MD5 hash: extension is RSA.

So for example with a signer’s information file name of “myinfo.SF,” the corresponding DSA signature block file name would be “myinfo.DSA.”

The format of a signature block file is defined in [PKCS].

Description

This function verifies the integrity and authorization of the indicated data object according to the indicated credentials. The rules for successful verification depend on whether or not a Boot Authorization Check is currently required on this platform.

If a Boot Authorization Check is not currently required on this platform, no authorization check is performed. However, the following rules are applied for an integrity check:

  • In this case, the credentials are optional. If they are not supplied ( Credentials.Data is NULL ), no integrity check is performed, and the function returns immediately with a “success” indication and IsVerified is TRUE.

  • If the credentials are supplied ( Credentials.Data is other than NULL ), integrity checks are performed as follows:

    — Verify the credentials - The credentials parameter is a valid signed Manifest, with a single signer. The signer’s identity is included in the credential as a certificate.

    — Verify the data object - The Manifest must contain a section named ” memory:BootObject,” with associated verification information (in other words, hash value). The hash value from this Manifest section must match the hash value computed over the specified DataObject data.

    —If these checks succeed, the function returns with a “success” indication and * IsVerified* is TRUE. Otherwise, IsVerified is FALSE and the function returns with a “security violation” indication.

If a Boot Authorization Check is currently required on this platform, authorization and integrity checks are performed. The integrity check is the same as in the case above, except that it is required. The following rules are applied:

  • Verify the credentials - The credentials parameter is required in this case ( Credentials.Data must be other than NULL ). The credentials parameter is a valid Signed Manifest, with a single signer. The signer’s identity is included in the credential as a certificate.

  • Verify the data object - The Manifest must contain a section named ” memory:BootObject,” with associated verification information (in other words, hash value). The hash value from this Manifest section must match the hash value computed over the specified DataObject data.

  • Do Authorization check — This happens one of two ways depending on whether or not the platform currently has a Boot Object Authorization Certificate configured.

    — If a Boot Object Authorization Certificate is not currently configured, this function interacts with the user in a platform-specific way to determine whether the operation should succeed.

    — If a Boot Object Authorization Certificate is currently configured, this function uses the Boot Object Authorization Certificate to determine whether the operation should succeed. The public key certified by the signer’s certificate must match the public key in the Boot Object Authorization Certificate configured for this platform. The match must be direct, that is, the signature authority cannot be delegated along a certificate chain.

    — If these checks succeed, the function returns with a “success” indication and IsVerified is TRUE. Otherwise, IsVerified is FALSE and the function returns with a “security violation” indication.

Note that if a Boot Authorization Check is currently required on this platform this function always performs an authorization check, either through platform-specific user interaction or through a signature generated with the private key corresponding to the public key in the platform’s Boot Object Authorization Certificate.

Status Codes Returned

EFI_SUCCESS

The function completed successfully.

EFI_NO_MAPPING

The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.

EFI_INVALID_PARAMETER

The Credentials parameter supplied by the caller is NULL or an invalid memory reference,
or
The Boot Authorization Check is currently required on this platform and the Credentials.Data parameter supplied by the caller is NULL or an invalid memory reference,
or
The DataObject parameter supplied by the caller is NULL or an invalid memory reference,
or
The DataObject.Data parameter supplied by the caller is NULL or an invalid memory reference,
or
The IsVerified parameter supplied by the caller is NULL or an invalid memory reference.

EFI_OUT_OF_RESOURCES

The function failed due to lack of memory or other resources.

EFI_SECURITY_VIOLATION

The signed manifest supplied as the Credentials parameter was invalid (could not be parsed),
or
The signed manifest supplied as the Credentials parameter failed to verify using the installed Boot Object Authorization Certificate or the signer’s Certificate in Credentials,
or
Platform-specific authorization failed,
or
Any other required attribute value was missing,
or
The signed manifest supplied as the Credentials parameter did not include a signer certificate, or

EFI_SECURITY_VIOLATION

The signed manifest supplied as the Credentials parameter did not include the manifest section named ” memory:BootObject,
or
The signed manifest supplied as the Credentials parameter had a signing certificate with an unsupported public-key algorithm,
or
The manifest section named ” memory:BootObject ” did not include a digest with a digest algorithm corresponding to the signing certificate’s public key algorithm,
or
The data object supplied as the DataObject parameter and referenced by the manifest section named ” memory:BootObject ” did not verify with the digest supplied in that manifest section,
or
The signed manifest supplied as the Credentials parameter did not include a signer’s information file with the SignerInformationName identifying attribute value ” BI S_VerifiableObjectSignerInfoName,” or
There were no signers associated with the identified signer’s information file,
or
There was more than one signer associated with the identified signer’s information file,
or
The platform’s check flag is “on” (requiring authorization checks) but the Credentials.Data supplied by the caller is NULL,
or
Any other unspecified security violation occurred.

EFI_DEVICE_ERROR

An unexpected internal error occurred while attempting to retrieve the public key algorithm of the manifest’s signer’s certificate,
or
An unexpected internal error occurred in a cryptographic software module.

24.5.11. EFI_BIS_PROTOCOL.VerifyObjectWithCredential()

Summary

Verifies the integrity and authorization of the indicated data object according to the indicated credentials and authority certificate.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL)(
  IN BIS_APPLICATION_HANDLE         AppHandle,
  IN EFI_BIS_DATA                   *Credentials,
  IN EFI_BIS_DATA                   *DataObject,
  IN EFI_BIS_DATA                   *SectionName,
  IN EFI_BIS_DATA                   *AuthorityCertificate,
  OUT BOOLEAN                       *IsVerified
  );

Parameters

AppHandle

An opaque handle that identifies the caller’s instance of initialization of the BIS service. Type BIS_APPLICATION_HANDLE is defined in the EFI_BIS_PROTOCOL.Initialize() function description.

Credentials

A Signed Manifest containing verification information for the indicated data object. The Manifest signature itself must meet the requirements described below. The required syntax of the Signed Manifest is described in the Related Definition of Manifest Syntax below. Type EFI_BIS_DATA is defined in the Initialize() function description.

DataObject

An in-memory copy of the raw data object to be verified. Type EFI_BIS_DATA is defined in the Initialize() function description.

SectionName

An ASCII string giving the section name in the manifest holding the verification information (in other words, hash value) that corresponds to DataObject. Type EFI_BIS_DATA is defined in the Initialize() function description.

AuthorityCertificate

A digital certificate whose public key must match the signer’s public key which is found in the credentials. This parameter is optional ( AuthorityCertificate.Data may be NULL ). Type EFI_BIS_DATA is defined in the EFI_BIS_PROTOCOL.Initialize() function description.

IsVerified

The function writes TRUE if the verification was successful. Otherwise, the function writes FALSE.

Related Definitions

//**********************************************************
// Manifest Syntax
//**********************************************************

The Signed Manifest consists of three parts grouped together into an Electronic Shrink Wrap archive as described in [SM spec]: a manifest file, a signer’s information file, and a signature block file. These three parts along with examples are described in the following sections. In these examples, text in parentheses is a description of the text that would appear in the signed manifest. Text outside of parentheses must appear exactly as shown. Also note that manifest files and signer’s information files must conform to a 72-byte line-length limit. Continuation lines (lines beginning with a single “space” character) are used for lines longer than 72 bytes. The examples given here follow this rule for continuation lines.

Note that the manifest file and signer’s information file parts of a Signed Manifest are ASCII text files. In cases where these files contain a base-64 encoded string, the string is an ASCII string before base-64 encoding.

//**********************************************************
// Manifest File Example
//**********************************************************

The manifest file must include a section referring to a memory-type data object with the caller-chosen name as shown in the example below. This data object is the Data Object to be verified. An example manifest file is shown below.

Manifest-Version: 2.0
ManifestPersistentId: (base-64 representation of a unique GUID)

Name: (a memory-type data object name)
Digest-Algorithms: SHA-1
SHA-1-Digest: (base-64 representation of a SHA-1 digest of the data object)

A line-by-line description of this manifest file is as follows.

Manifest-Version: 2.0

This is a standard header line that all signed manifests have. It must appear exactly as shown.

ManifestPersistentId: (base-64 representation of a unique GUID)

The left-hand string must appear exactly as shown. The right-hand string must be a unique GUID for every manifest file created. The Win32 function UuidCreate() can be used for this on Win32 systems. The GUID is a binary value that must be base-64 encoded. Base-64 is a simple encoding scheme for representing binary values that uses only printing characters. Base-64 encoding is described in [BASE-64].

Name: (a memory-type data object name)

This identifies the section that carries the integrity data for the target Data Object. The right-hand string must obey the syntax for memory-type references, that is, it is of the form ” memory:SomeUniqueName.” The ” memory: ” part of this string must appear exactly. The ” SomeUniqueName ” part is chosen by the caller. It must be unique within the section names in this manifest file. The entire ” memory:SomeUniqueName ” string must match exactly the corresponding string in the signer’s information file described below. Furthermore, this entire string must match the value given for the SectionName parameter to this function. Note that the target Data Object cannot be found directly from this manifest. A caller verifying the Data Object integrity must load the Data Object into memory and specify its memory location explicitly to this verification function through the DataObject parameter.

Digest-Algorithms: SHA-1

This enumerates the digest algorithms for which integrity data is included for the data object. For systems with DSA signing, SHA-1 hash, and 1024-bit key length, the digest algorithm must be ” SHA-1.” For systems with RSA signing, MD5 hash, and 512-bit key length, the digest algorithm must be ” MD5.” Multiple algorithms can be specified as a whitespace-separated list. For every digest algorithm XXX listed, there must also be a corresponding XXX-Digest line.

SHA-1-Digest: (base-64 representation of a SHA-1 digest of the data object)

Gives the corresponding digest value for the data object. The value is base-64 encoded.

//**********************************************************
// Signer’s Information File Example
//**********************************************************

The signer’s information file must include a section whose name matches the reserved data object section name of the section in the Manifest file. This section in the signer’s information file carries the integrity data for the corresponding section in the manifest file. An example signer’s information file is shown below.

Signature-Version: 2.0
SignerInformationPersistentId: (base-64 representation of a unique GUID)
SignerInformationName: BIS_VerifiableObjectSignerInfoName

Name: (a memory-type data object name)
Digest-Algorithms: SHA-1
SHA-1-Digest: (base-64 representation of a SHA-1 digest of the corresponding manifest section)

A line-by-line description of this signer’s information file is as follows.

Signature-Version: 2.0

This is a standard header line that all signed manifests have. It must appear exactly as shown.

SignerInformationPersistentId: (base-64 representation of a unique GUID)

The left-hand string must appear exactly as shown. The right-hand string must be a unique GUID for every signer’s information file created. The Win32 function UuidCreate() can be used for this on Win32 systems. The GUID is a binary value that must be base-64 encoded. Base-64 is a simple encoding scheme for representing binary values that uses only printing characters. Base-64 encoding is described in [BASE-64].

SignerInformationName: BIS_VerifiableObjectSignerInfoName

The left-hand string must appear exactly as shown. The right-hand string must appear exactly as shown.

Name: (a memory-type data object name)

This identifies the section in the signer’s information file corresponding to the section with the same name in the manifest file described earlier. The right-hand string must match exactly the corresponding string in the manifest file described above.

Digest-Algorithms: SHA-1

This enumerates the digest algorithms for which integrity data is included for the corresponding manifest section. Strings identifying digest algorithms are the same as in the manifest file. The digest algorithms specified here must match those specified in the manifest file. For every digest algorithm XXX listed, there must also be a corresponding XXX-Digest line.

SHA-1-Digest: (base-64 representation of a SHA-1 digest of the corresponding manifest section)

Gives the corresponding digest value for the corresponding manifest section. The value is base-64 encoded. Note that for the purpose of computing the hash of the manifest section, the manifest section starts at the beginning of the opening ” Name: ” keyword and continues up to, but not including, the next section’s ” Name: ” keyword or the end-of-file. Thus the hash includes the blank line(s) at the end of a section and any newline(s) preceding the next ” Name: ” keyword or end-of-file.

//**********************************************************
// Signature Block File Example
//**********************************************************

A signature block file is a raw binary file (not base-64 encoded) that is a PKCS#7 defined format signature block. The signature block covers exactly the contents of the signer’s information file. There must be a correspondence between the name of the signer’s information file and the signature block file. The base name matches, and the three-character extension is modified to reflect the signature algorithm used according to the following rules:

  • DSA signature algorithm (which uses SHA-1 hash): extension is DSA.

  • RSA signature algorithm with MD5 hash: extension is RSA.

So for example with a signer’s information file name of “myinfo.SF,” the corresponding DSA signature block file name would be “myinfo.DSA.”

The format of a signature block file is defined in [PKCS].

Description

This function verifies the integrity and authorization of the indicated data object according to the indicated credentials and authority certificate. Both an integrity check and an authorization check are performed. The rules for a successful integrity check are:

  • Verify the credentials - The credentials parameter is a valid Signed Manifest, with a single signer. The signer’s identity is included in the credential as a certificate.

  • Verify the data object - The Manifest must contain a section with the name as specified by the SectionName parameter, with associated verification information (in other words, hash value). The hash value from this Manifest section must match the hash value computed over the data specified by the DataObject parameter of this function.

The authorization check is optional. It is performed only if the AuthorityCertificate.Data parameter is other than NULL . If it is other than NULL, the rules for a successful authorization check are:

  • The AuthorityCertificate parameter is a valid digital certificate. There is no requirement regarding the signer (issuer) of this certificate.

  • The public key certified by the signer’s certificate must match the public key in the AuthorityCertificate. The match must be direct, that is, the signature authority cannot be delegated along a certificate chain.

If all of the integrity and authorization check rules are met, the function returns with a “success” indication and IsVerified is TRUE. Otherwise, it returns with a nonzero specific error code and IsVerified is FALSE.

Status Codes Returned

EFI_SUCCESS

The function completed successfully.

EFI_NO_MAPPING

The AppHandle parameter is not or is no longer a valid application instance handle associated with the EFI_BIS protocol.

EFI_INVALID_PARAMETER

The Credentials parameter supplied by the caller is NULL or an invalid memory reference, or
The Credentials.Data parameter supplied by the caller is NULL or an invalid memory reference, or
The Credentials.Length supplied by the caller is zero, or The DataObject parameter supplied by the caller is NULL or an invalid memory reference, or
The DataObject.Data parameter supplied by the caller is NULL or an invalid memory reference, or

EFI_INVALID_PARAMETER

The SectionName parameter supplied by the caller is NULL or an invalid memory reference, or
The SectionName.Data parameter supplied by the caller is NULL or an invalid memory reference, or
The SectionName.Length supplied by the caller is zero, or
The AuthorityCertificate parameter supplied by the caller is NULL or an invalid memory reference, or
The IsVerified parameter supplied by the caller is NULL or an invalid memory reference.

EFI_OUT_OF_RESOURCES

The function failed due to lack of memory or other resources.

EFI_SECURITY_VIOLATION

The Credentials.Data supplied by the caller is NULL, or
The AuthorityCertificate supplied by the caller was invalid (could not be parsed), or
The signed manifest supplied as Credentials failed to verify using the AuthorityCertificate supplied by the caller or the manifest’s signer’s certificate, or
Any other required attribute value was missing, or
The signed manifest supplied as the Credentials parameter did not include a signer certificate, or
The signed manifest supplied as the Credentials parameter did not include the manifest section named according to SectionName, or
The signed manifest supplied as the Credentials parameter had a signing certificate with an unsupported public-key algorithm, or
The manifest section named according to SectionName did not include a digest with a digest algorithm corresponding to the signing certificate’s public key algorithm, or
The data object supplied as the DataObject parameter and referenced by the manifest section named according to SectionName did not verify with the digest supplied in that manifest section, or

EFI_SECURITY_VIOLATION

The signed manifest supplied as the Credentials parameter did not include a signer’s information file with the SignerInformationName identifying attribute value ” BI S_VerifiableObjectSignerInfoName,” or
There were no signers associated with the identified signer’s information file, or
There was more than one signer associated with the identified signer’s information file, or
Any other unspecified security violation occurred.

EFI_DEVICE_ERROR

An unexpected internal error occurred while attempting to retrieve the public key algorithm of the manifest’s signer’s certificate, or
An unexpected internal error occurred in a cryptographic software module.

24.6. DHCP options for ISCSI on IPV6

Option 59 is the iSCSI Root path

The format of the root path is “iscsi:”<servername>”:”<protocol>”:”<port>”:”<LUN>”:”<targetname>

This is per the description in IETF RFC 4173. See https://uefi.org/uefi#RFC4173 for a link to this document.

Option 60 is the DHCP Server address.

This is formatted the same as parameter 1 in OPT_BOOTFILE_PARAM (60) of the IPv6 address of the DHCP server (IETF RFC 5970). See ` <https://uefi.org/uefi>__` a link to this document.*

24.7. HTTP Boot

24.7.1. Boot from URL

Elsewhere in this specification there is defined a discoverable network boot using DHCP as a control channel allowing a firmware client machine export its architecture type, and then have the boot server response with a binary image. For the UEFI architecture types defined in “Links to UEFI-Related Documents” ( http://uefi.org/uefi) under the heading “IANA DHCPv6 parameters”, the binary image on the boot service is a UEFI-formatted executable with a machine subsystem type that corresponds to the UEFI firmware on the client machine, or it could be mounted as a RAM disk which contains a UEFI-compliant file system ( See File System Format ). This binary image is often referred to as a “Network Boot Program” (NBP). The UEFI client machine that downloads the NBP uses the IPV4 or IPV6 TFTP protocol to address the indicated server, depending upon if DHCP4 or DHCP6 was used initially, in order to download images such as 64-bit UEFI (type 0x07).

This section defines a related method indicated by other codes in the DHCP options, in which the name and path of the NBP are specified as a URI string in one of several formats specifying protocol and unique name identifying the NBP for the specified protocol. In this method the NBP will be downloaded via IPV4 or IPV6 HTTP protocol if the tag indicates x64 UEFI HTTP Boot (type code 0x0f for x86 and 0x10 for x64).

In the future other protocols such as FTP or NFS could be encoded with both new tag types and corresponding URIs (e.g., ‘ftp://nbp.efi or nfs://nbp.efi, respectively). However, assignment of these type codes has not yet occurred.

The rest of this section will describe ‘HTTP Boot’ as one example of ‘boot from URI’. It is expected that the procedure can be extended as additional protocol type codes are defined.

Please reference the definitions of EFI_DNS4_PROTOCOL and EFI_DNS6_PROTOCOL elsewhere in this document. In systems that also support one of both of these protocols, the target URI can be specified using Internet domain name format understood by DNS servers supporting the appropriate RFC specifications.

Also, elsewhere in this document, the PXE2.1 and UEFI2.4 netboot6 sections talk about the ‘boot from TFTP’ method of ‘boot from URI.’

The following RFC documents documents should be consulted for network message details related to the processes described in this chapter:

  1. RFC1034 - “Domain Names - Concepts and Facilities”,

  2. RFC 1035 - “Domain Names - Implementation and Specification”,

  3. RFC 3513 - “Internet Protocol Version 6 (IPv6) Addressing Architecture”, , April 2003.

  4. RFC 3596 - DNS Extensions to Support IP Version 6

  5. RFC 2131 - Dynamic Host Configuration Protocol

  6. RFC 2132 - DHCP options and BOOTP Vendor Extensions

  7. RFC 5970 - DHCPv6 Options for Network Boot

  8. RFC 4578 - Dynamic Host Configuration Protocol (DHCP) Options for the Intel Preboot eXecution Environment (PXE)

  9. RFC 3986 - Uniform Resource Identifiers (URI): Generic Syntax, IETF, 2005

  10. RFC 3004 - The User Class option

  11. RFC3315 - Dynamic Host Configuration Protocol for IPv6 (DHCPv6)

  12. RFC3646 - DNS Configuration options for Dynamic Host Configuration Protocol for IPv6 (DHCPv6)

  13. RFC2246 - TLS protocol Version 1.0

24.7.2. Concept configuration for a typical HTTP Bootscenario

HTTP Boot is client-server communication based application. It combines the DHCP, DNS, and HTTP protocols to provide the capability for system deployment and configuration over the network. This new capability can be utilized as a higher-performance replacement for tftp-based PXE boot methods of network deployment.

24.7.2.1. Use in Corporate environment

_images/Network_Protocols_SNP_PXE_BIS-5.png

Fig. 24.4 HTTP Boot Network Topology Concept -Corporate Environment

A typical network configuration which supports UEFI HTTP Boot may involve one or more UEFI client systems, and several server systems. The Figure above show a typical HTTP Boot network topology for a corporate environment.

  • UEFI HTTP Boot Client initiates the communication between the client and different server system.

  • DHCP server with HTTPBoot extension for boot service discovery. Besides the standard host configuration information (such as address/subnet/gateway/name-server, etc…), the DHCP server with the extensions can also provide the discovery of URI locations for boot images on the HTTP server.

  • HTTP server could be located either inside the corporate environment or across networks, such as on the Internet. The boot resource itself is deployed on the HTTP server. In this example, “http://webserver/boot/boot.efi” is used as the boot resource. Such an application is also called a Network Boot Program (NBP). NBPs are used to setup the client system, which may include installation of an operating system, or running a service OS for maintenance and recovery tasks.

  • DNS server is optional; and provides standard domain name resolution service.

24.7.2.2. Use case in Home environment

In a corporate environment, a standard DHCP server can be enhanced to support the HTTPBoot extension. In a home network, generally only an optional standard DHCP server may be available for host configuration information assignment. The Figure, below, shows the concept network topology for a typical home PC environment.

_images/Network_Protocols_SNP_PXE_BIS-6.png

Fig. 24.5 HTTP Boot Network Topology Concept2 — Homeenvironments

UEFI HTTP Boot Client initiates the communication between the client and different servers. In the home configuration however, the client will expect the boot resource information to be available from a source other than the standard DHCP server, and that source does not typically have HTTPBoot extensions. Instead of DHCP, the boot URI could be created by a UEFI application or extracted from text entered by a user.

DHCP server is optional, and if available in the network,* provides the standard service to assign host configuration information to the UEFI Client (e.g. address/subnet/gateway/name-server/etc.). In case the standard DHCP server is not available, the same host configuration information should be provided by a UEFI application or extracted from text entered by a user prior to the client initiating the communication.

DNS Server is optional, and provides standard domain name resolution service.

24.7.3. Protocol Layout for UEFI HTTP Boot Clientconcept configuration for a typical HTTP Boot scenario

_images/Network_Protocols_SNP_PXE_BIS-7.png

Fig. 24.6 UEFI HTTP Boot Protocol Layout

This figure illustrates the UEFI network layers related to how the HTTP Boot works.

The HTTP Boot driver is layered on top of a UEFI Network stack implementation. It consumes DHCP service to do the Boot service discovery, and DNS service to do domain name resolution if needed. It also consumes HTTP serviced to retrieve images from the HTTP server. The functionality needed in the HTTP Boot scenario is limited to client initiated requests to download the boot image.

TLS is consumed if HTTPS functionality is needed. The TLS design is covered in EFI TLS Protocol.

The HTTP Boot driver produces LoadFile protocol and device path protocol. BDS will provide the boot options for the HTTP Boot. Once a boot option for HTTP boot is executed, a particular network interface is selected. HTTP Boot driver will perform all steps on that interface and it is not required to use other interfaces.

24.7.3.1. Device Path

If both IPv4 and IPv6 are supported, the HTTP Boot driver should create two child handles, with LoadFile and DevicePath installed on each child handle. For the device path, an IP device path node and a BootURI device path are appended to the parent device path, for example:

PciRoot(0x0)/Pci(0x19, 0x0)/MAC(001230F4B4FF, 0x0)/IPv4(0.0.0.0, 0, DHCP, 0.0.0.0, 0.0.0.0, 0.0.0.0)/Uri()

PciRoot(0x0)/Pci(0x19, 0x0)/MAC(001230F4B4FF, 0x0)/IPv6(::/128, 0, Static, ::/128, ::/128, 0)/Uri()

Also, after retrieving the boot resource information and IP address, the BootURI device path node will be updated to include the BootURI information. For example, if the NBP is a UEFI-formatted executable, the device patch will be updated to

PciRoot(0x0)/Pci(0x19, 0x0)/MAC(001230F4B4FF, 0x0)/IPv4(192.168.1.100, TCP, DHCP, 192.168.1.5, 192.168.1.1, 255.255.255.0)/Uri(http://192.168.1.100/shell.efi)

PciRoot(0x0)/Pci(0x19, 0x0)/MAC(001230F4B4FF, 0x0)/IPv6(2015::100, TCP, StatefulAutoConfigure, 2015::5, 2015::10, 64)/UriI(http://2015::100/shell.efi)

These two instances allow for the boot manager to decide a preference of IPv6 versus IPv4.

If the NBP is a binary image which could be mounted as a RAM disk, the device path will be updated to

PciRoot(0x0)/Pci(0x19, 0x0)/MAC(001230F4B4FF, 0x0)/IPv4(192.168.1.100, TCP, DHCP, 192.168.1.5, 192.168.1.1, 255.255.255.0)/Uri(http://192.168.1.100/boot.iso [^])

PciRoot(0x0)/Pci(0x19, 0x0)/MAC(001230F4B4FF, 0x0)/IPv6(2015::100, TCP, StatefulAutoConfigure, 2015::5, 2015::10, 64)/Uri (http://2015::100/boot.iso)

In this case, the HTTP Boot driver will register RAM disk with the downloaded NBP, by appending a RamDisk device node to the device path above, like

PciRoot(0x0)/Pci(0x19, 0x0)/MAC(001230F4B4FF, 0x0)/IPv4(192.168.1.100, TCP, DHCP, 192.168.1.5, 192.168.1.1, 255.255.255.0)/Uri(http://192.168.1.100/boot.iso )/RamDisk(0x049EA000, 0x5DEA000, 0, 3D5ABD30-4175-87CE-6D64-D2ADE523C4BB)

PciRoot(0x0)/Pci(0x19, 0x0)/MAC(001230F4B4FF, 0x0)/IPv6(2015::100, TCP, StatefulAutoConfigure, 2015::5, 2015::10, 64)/Uri (http://2015::100/boot.iso)/ RamDisk(0x049EA000, 0x5DEA000, 0, 3D5ABD30-4175-87CE-6D64-D2ADE523C4BB)

In some cases, Uri includes a host name and DNS become mandatory for translating the name to the IP address of the host. The HTTP Boot driver may append DNS device path node immediately before Uri device path node, for example:

PciRoot(0x0)/Pci(0x19, 0x0)/MAC(001230F4B4FF, 0x0)/IPv4(192.168.1.100, TCP, DHCP, 192.168.1.5, 192.168.1.1, 255.255.255.0)/Dns(192.168.22.100, 192.168.22.101)/Uri(http://www.bootserver.com/boot.iso )/ RamDisk(0x049EA000, 0x5DEA000, 0, 3D5ABD30-4175-87CE-6D64-D2ADE523C4BB)

PciRoot(0x0)/Pci(0x19, 0x0)/MAC(001230F4B4FF, 0x0)/IPv6(2015::100, TCP, StatefulAutoConfigure, 2015::5, 2015::10, 64)/Dns(2016::100, 2016::101)/Uri (http:// www.bootserver.com/ boot.iso)/ RamDisk(0x049EA000, 0x5DEA000, 0, 3D5ABD30-4175-87CE-6D64-D2ADE523C4BB)

If HTTP Boot driver cannot obtain the DNS server addresses, it should not append an empty DNS device path node.

The boot manager could use the example device paths to match the device which produces a device path protocol including a URI device path node in the system, without matching the Specific Device Path data in IP device path node and URI device path node, because the IP device path node and URI device path node might be updated by HTTP Boot driver in different scenarios.

The BootURI information could be retrieved from a DHCP server with HTTPBoot extension, or from a boot option which includes a short-form URI device path, or from a boot option which includes a URI device path node, or created by a UEFI application or extracted from text entered by a user.

Once the HTTP Boot driver retrieves the BootURI information from the short-form URI device path, it will perform all other steps for HTTP boot except retrieving the BootURI from DHCP server. Also, when the short-form URI device path is inputted to HTTP Boot driver via LoadFile protocol, the HTTP Boot driver should expand the short-form URI device path to above example device path after retrieving IP address configuration (address, subnet, gateway, and optionally the name-server) from the DHCP server. In case of the home environment with no DHCP server, the same information may be provisioned by OEM or input by the end user through Setup Options. The IP and optional DNS device path nodes, constructed with this information and prefixed to the short-form URI device path, can be inputted to the HTTP Boot driver via LoadFile protocol. The name server information in the form of DNS device path node is optional, and is used only when the BootURI contains the server name or FQDN. The HTTP Boot driver will then consume the information in the device path and initiate the necessary communication.

Once the HTTP Boot driver retrieves the BootURI information from a boot option which includes a URI device path node, it should retrieve the IP address configuration from the IP device path node of the same boot option. If the IP address configuration or BootURI information is empty, the HTTP Boot driver could retrieve the required information from DHCP server. If the IP address configuration or BootURI information is not empty but invalid, the HTTP boot process will fail.

The HTTP Boot block diagram ( UEFI HTTP Boot Protocol Layout ) describes a suggested implementation for HTTP Boot. Other implementation can create their own HTTP Netboot Driver which meets the requirements for their netboot methodology

24.7.4. Concept of Message Exchange in a typical HTTPBoot scenario (IPv4 in Corporate Environment)

In summary, the newly installed networked client machine (UEFI HTTP Boot Client) should be able to enter a heterogeneous network, acquire a network address from a DHCP server, and then download an NBP to set itself up.

The concept of HTTP Boot message exchange sequence is as follows. The client initiates the DHCPv4 D.O.R.A process by broadcasting a DHCPDISCOVER containing the extension that identifies the request as coming from a client that implements the HTTP Boot functionality. Assuming that a DHCP server or a Proxy DHCP server implementing this extension is available, after several intermediate steps, besides the standard configuration such as address/subnet/router/dns-server, boot resource location will be provided to the client system in the format of a URI. The URI points to the NBP which is appropriate for this client hardware configuration. A boot option is created, and if selected by the system logic the client then uses HTTP to download the NBP from the HTTP server into memory. Finally, the client executes the downloaded NBP image from memory. This image can then consume other UEFI interfaces for further system setup.

_images/Network_Protocols_SNP_PXE_BIS-8.png

Fig. 24.7 HTTP Boot Overall Flow

24.7.4.1. Message exchange between EFI Client and DHCPserver using DHCP Client Extensions

24.7.4.1.1. Client broadcast

The client broadcasts a DHCP Discover message to the standard DHCP port (67).

An option field in this packet contains the following:

  • Fill DHCP option 55 - Parameter Requested List option

    – Address configuration, Server information, Name server, Vendor class identifier

  • A DHCP option 97: UUID/GUID-based Client Identifier

  • A DHCP option 94: Client Network Identifier Option

    – If support UNDI, fill this option (Refer RFC5970)

  • A DHCP option 93: the client system architecture (Refer [Arch-Type])

    – 0x0F - x86 UEFI HTTP Boot

    – 0x10 - x64 UEFI HTTP Boot

  • A DHCP option 60, Vendor Class ID, set to “HTTPClient:Arch:XXXX:UNDI:YYYZZZ”

DHCP server response

The DHCP server responds by sending DHCPOFFER message on standard DHCP reply port (68).

The HTTP Boot Client may possibly receive multiple DHCPOFFER packets from different sources of DHCP Services, possibly from DHCP Services which recognize the HTTP extensions or from Standard DHCP Services.

A service recognizing HTTP extensions must respond with an offer that has Option 60 (Vendor class identifier) parameter set to “HTTPClient”, in response to the Vendor class identifier requested in option 55 in the DHCP Discover message.

Each message contains standard DHCP parameters: an IP address for the client and any other parameters that the administrator might have configured on the DHCP or Proxy DHCP Service. The DHCP service or Proxy DHCP which recognizes the HTTPBoot extension will provide DHCPOFFER with HTTPClient extensions. If this is a Proxy DHCP service, then the client IP address field is (0.0.0.0). If this is from a DHCP service, then the returned client IP address field is valid.

From the received DHCPOFFER(s), the client records the information as follows:

  • Client IP address (and other parameters) offered by a standard DHCP/BOOTP services.

  • If Boot URI information is provided thru ‘file’ field in DHCP Header or option 67, then the client will record the information as well.

  • Optional Name-server information if URI is displayed using domain-name

    • Timeout: After Client sent out the DHCP Discover packet, the Client will wait for a timeout to collect enough DHCP Offers. If failed to retrieve all the required information, the DHCP Discover will be retried, at most four times. The four timeout mechanisms is 4, 8, 16 and 32 seconds respectively,

    • Priority: Among all the received DHCPOFFERs, the Priority is considered as follows:

24.7.5. Priority1

Choose the DHCPOFFER that provides all required information:

<IP address configuration, Boot URI configuration, Name-server configuration (if domain-name used in Boot URI)>

If Boot URI and IP address configuration provided in different DHCPOFFER, Using 5 DHCPOFFER as example for priority description

  • Packet1 - DHCPOFFER, provide <IP address configuration, Name server>

  • Packet2 - DHCPOFFER, provide <IP address configuration>

  • Packet3 - DHCPOFFER, provide <domain-name expressed URI>

  • Packet4 - DHCPOFFER, provide <IP address expressed URI>

  • Packet5 - DHCPOFFER, provide <IP address, domain-name expressed URI>

Then,

24.7.6. Priority2

Choose the DHCPOFFER from different packet, firstly find out URI info represented in IP address mode, then choose DHCPOFFER which provide IP address configuration

In this example, the chosen DHCPOFFER packet is packet4 + packet1 / packet 2 (packet 1/2 take same priority, implementation can make its own implementation choice)

24.7.7. Priority3

Choose the DHCPOFFER from different packet, firstly find out URI info represented in domain-name mode, then choose DHCPOFFER which provide <IP address configuration, domain-name expressed URI>

In this example, the chosen DHCPOFFER packet is packet3 / packet5 + packet1

NOTE: If packet5, then client IP address assigned by Packet5 will be override by IP address in packet1.

24.7.8. Priority4

If failed to retrieve <Boot URI / IP address / (on-demand) Name-server> information through all received DHCPOFFERs, this is deemed as FAILED-CONFIGURATION

Assuming the boot image is in the boot subdirectory of the web server root, the supported URI could be one of below formats. [RFC3986] where ‘/boot/’ is replaced by administrator-created directory, and ‘image’ is the file name of the NBP.

http://reg-name:port/boot/image

http://ipv4address:port/boot/image

http://ipv6address:port/boot/image

In the URL example, Port is optional if web service is provided through port 80 for the HTTP data transfer. Commonly, the reg-name use DNS as name registry mechanism.

After retrieving the boot URI through Device Path , if IP address (either IPv4 or IPv6 address) is provided, the HTTP Boot Client can directly use that address for next step HTTP transfer. If a reg-name is provided in the URI, the HTTP Boot Client driver need initiate DNS process ( See Message in DNS Query/Reply ) to resolve its IP address.

DHCP Request

The HTTP Boot Client selects an IP address offered by a DHCP Service, and then it completes the standard DHCP protocol by sending a DHCP Request packet for the address to the DHCP Server and waiting for acknowledgement from the DHCP server.

DHCP ACK

The server acknowledges the IP address by sending DHCP ACK packet to the client.

24.7.8.1. Message exchange between UEFI Client and DHCPserver not using DHCP Client Extensions

In a home environment, because the Boot URI Information will not be provided by the DHCP Offers, we need other channels to provide this information. The implementation suggestion is provisioning this information by OEM or input by end user through Setup Options, henceforth, the UEFI Boot Client already know the Boot URI before contacting the DHCP server.

The message exchange between the EFI Client and DHCP server will be standard DHCP D.O.R.A to obtain <IP address, Name-server>.

In the case of a home environment without a DHCP server, the above message exchange is not needed, and the UEFI HTTP Boot Client will have the <IP address, Name-server> provisioned by OEM or input by the end user through Setup Options.

24.7.8.2. Message in DNS Query/Reply

The DNS Query/Reply is a standard process defined in DNS Protocol [RFC 1034, RFC 1035]. Multiple IP address might be retrieved from the DNS process. It’s the HTTP Boot Client driver’s responsibility to select proper IP address automatically or expose user interface for customer to decide proper IP address.

24.7.8.3. Message in HTTP Download

In the HTTP Boot scenario, HTTP GET message is used to get image from the Web server.

24.7.9. Concept of Message Exchange in HTTP Bootscenario (IPv6)

24.7.9.1. Message exchange between EFI Client andDHCPv6 server with DHCP Client extensions

24.7.9.1.1. Client multicast a DHCPv6 Solicit messageto the standard DHCPv6 port (547)

Besides the options required for address auto-configuration, option field in this packet also contains the following:

  • Fill DHCPv6 Option 6 - Option Request Option

    — Request server to supply option 59 (OPT_BOOTFILE_URL), option 60 ( OPT_BOOTFILE_PARAM), option 23 (OPT_DNS_SERVERS), option 16 (OPTION_VENDOR_CLASS).

  • A DHCPv6 option 1, Client identifier

  • A DHCPv6 option 16, Vendor Class ID, set to “HTTPClient:Arch:XXXX:UNDI:YYYZZZ”

  • A DHCPv6 option 61: the client system architecture (Refer [Arch-Type])

    — 0x0F - x86 UEFI HTTP Boot

    — 0x10 - x64 UEFI HTTP Boot

  • A DHCPv6 option 62: Client Network Identifier Option

    — If support UNDI, fill this option (Refer RFC5970)

24.7.9.1.2. Server unicast DHCPv6 Advertisement to theClient to the DHCPv6 port (546)

The HTTP Boot Client will receive multiple advertisements from different sources of DHCPv6 Services, possibly from DHCPv6 Services which recognize the HTTP extensions or from Standard DHCPv6 Services.

A DHCPv6 service recognizing HTTP extensions must respond with an Advertisement that has Option 16 (OPTION_VENDOR_CLASS) parameter set to “HTTPClient”, in response to the OPTION_VENDOR_CLASS requested in Option 6 in the DHCPv6 Solicit message.

Each message contains standard DHCP parameters: Identify Association (IA) option which conveys information including <IP address, lifetime, etc…>. Name server option conveys the DNS server address. The DHCP service or Proxy DHCP which recognizes the HTTPBoot extension will provide DHCPv6 Advertisement with HTTPClient extensions, including Boot URI and Optional Boot Parameters.

From the received DHCPOFFER(s), the client records the information as follows:

  • Client IP address (and other parameters) provide through IA option

  • Boot URI provided thru option 59

  • Optional BootFile Parameter provided through option 60 (if no other parameter needed for this boot URI, this option can be eliminated)

  • Optional Name-server information provided through option 23, if URI is displayed using domain-name.

24.7.9.1.3. Client multicast DHCPv6 Request to the selected DHCP Advertisement to confirm the IPaddress assigned by that server

This packet is the same with the DHCPv6 Solicit packet except for the message type is Request.

24.7.9.1.4. Server unicast the DHCPv6 Reply toacknowledge the Client IP address for the UEFI HTTPClient

24.7.9.2. Message exchange between UEFI Client andDHCPv6 server not using DHCP Client Extensions

In a home environment, the Boot URI Information will not be provided by the DHCPv6 Offers, we need other channels to provide this information. Like what is described in Message exchange between UEFI Client and DHCPserver not using DHCP Client Extensions , the implementation suggestion is provisioning this information by OEM or input by end user through Setup Options, henceforth, the UEFI Boot Client already know the Boot URI before contacting the DHCP server.

The message exchange between the EFI Client and DHCP server will be standard DHCP S.A.R.R. to obtain <IP address, Name-server>.

In the case of a home environment without a DHCPv6 server, the above message exchange is not needed, and the UEFI HTTP Boot Client will have the <IP address, Name-server> provisioned by OEM or input by the end user through Setup Options.

24.7.9.3. Message exchange between UEFI Client and DNS6server

The DNS Query/Reply for domain name resolution is the same process as described in See Message in DNS Query/Reply.

24.7.9.4. Message in HTTP Download

HTTP Download process is the same process as described in Message in HTTP Download .

24.7.10. EFI HTTP Boot Callback Protocol

This section defines the EFI HTTP Boot Callback Protocol that is invoked when the HTTP Boot driver is about to transmit or has received a packet. The EFI HTTP Boot Callback Protocol must be installed on the same handle as the Load File Protocol for the HTTP Boot.

24.7.11. EFI_HTTP_BOOT_CALLBACK_PROTOCOL

Summary

Protocol that is invoked when the HTTP Boot driver is about to transmit or has received a packet.

GUID

#define EFI_HTTP_BOOT_CALLBACK_PROTOCOL_GUID \
 {0xba23b311, 0x343d, 0x11e6, {0x91, 0x85, 0x58,0x20, 0xb1, 0xd6, 0x52, 0x99}}

Protocol Interface Structure

typedef struct \_EFI_HTTP_BOOT_CALLBACK_PROTOCOL {
  EFI_HTTP_BOOT_CALLBACK         Callback;
}   EFI_HTTP_BOOT_CALLBACK_PROTOCOL;

Parameters

Callback

Callback routine used by the HTTP Boot driver.

24.7.12. EFI_HTTP_BOOT_CALLBACK_PROTOCOL.Callback()

Summary

Callback function that is invoked when the HTTP Boot driver is about to transmit or has received a packet.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HTTP_BOOT_CALLBACK) (
  IN EFI_HTTP_BOOT_CALLBACK_PROTOCOL   *This,
  IN EFI_HTTP_BOOT_CALLBACK_DATA_TYPE  DataType,
  IN BOOLEAN                           Received,
  IN UINT32                            DataLength,
  IN VOID                              *Data OPTIONAL
  );

Parameters

This

Pointer to the EFI_HTTP_BOOT_CALLBACK_PROTOCOL instance.

DataType

The event that occurs in the current state. Type EFI_HTTP_BOOT_CALLBACK_DATA_TYPE is defined below.

Received

TRUE if the callback is being invoked due to a receive event. FALSE if the callback is being invoked due to a transmit event.

DataLength

The length in bytes of the buffer pointed to by Data.

Data

A pointer to the buffer of data, the data type is specified by DataType.

Related Definitions

//**********************************************
// EFI_HTTP_BOOT_CALLBACK_DATA_TYPE
//**********************************************
typedef enum {
  HttpBootDhcp4,
  HttpBootDhcp6,
  HttpBootHttpRequest,
  HttpBootHttpResponse,
  HttpBootHttpEntityBody,
  HttpBootTypeMax
}   EFI_HTTP_BOOT_CALLBACK_DATA_TYPE;
HttpBootDhcp4

Data points to a DHCP4 packet which is about to transmit or has received.

HttpBootDhcp6

Data points to a DHCP6 packet which is about to be transmit or has received.

HttpBootHttpRequest

Data points to an EFI_HTTP_MESSAGE structure, which contians a HTTP request message to be transmitted.

HttpBootHttpResponse

Data points to an EFI_HTTP_MESSAGE structure, which contians a received HTTP response message.

HttpBootHttpEntityBody

Part of the entity body has been received from the HTTP server. Data points to the buffer of the entity body data.

Description

This function is invoked when the HTTP Boot driver is about to transmit or has received packet. Parameters DataType and Received specify the type of event and the format of the buffer pointed to by Data. Due to the polling nature of UEFI device drivers, this callback function should not execute for more than 5 ms. The returned status code determines the behavior of the HTTP Boot driver.

Status Codes Returned

EFI_SUCCESS

Tells the HTTP Boot driver to continue the HTTP Boot process.

EFI_ABORTED

Tells the HTTP Boot driver to abort the current HTTP Boot process.