16. Protocols — iSCSI Boot

16.1. Overview

The iSCSI protocol defines a transport for SCSI data over TCP/IP. It also provides an interoperable solution that takes advantage of existing internet infrastructure, management facilities, and addresses distance limitations. The iSCSI protocol specification was developed by the Internet Engineering Task Force (IETF) and is SCSI Architecture Model-2 (SAM-2) compliant. iSCSI encapsulates block-oriented SCSI commands into iSCSI Protocol Data Units (PDU) that traverse the network over TCP/IP. iSCSI defines a Session, the initiator and target nexus (I-T nexus), which could be a bundle of one or more TCP connections.

Similar to other existing mass storage protocols like Fibre Channel and parallel SCSI, boot over iSCSI is an important functionality. This document will attempt to capture the various cases for iSCSI boot and common up with generic EFI protocol changes to address them.

16.1.1. iSCSI UEFI Driver Layering

iSCSI UEFI Drivers may exist in two different forms:

  • iSCSI UEFI Driver on a NIC:

    The driver will be layered on top of the networking layers. It will use the DHCP, IP, and TCP and packet level interface protocols of the UEFI networking stack. The driver will use an iSCSI software initiator.

  • iSCSI UEFI Driver on a Host Bus Adapter (HBA)that may use an offloading engine such as TOE (or anyother TCP offload card):

    The driver will be layered on top of the TOE TCP interfaces. It will use the DHCP, IP, TCP protocols of the TOE. The driver will present itself as a SCSI device driver using interfaces such as EFI_EXT_SCSI_PASS_THRU_PROTOCOL .

To help in detecting iSCSI UEFI Drivers and their capabilities, the iSCSI UEFI driver handle must include an instance of the EFI_ADAPTER_INFORMATION_PROTOCOL with a EFI_ADAPTER_INFO_NETWORK_BOOT structure.

16.2. EFI iSCSI Initiator Name Protocol

This protocol sets and obtains the iSCSI Initiator Name. The iSCSI Initiator Name protocol builds a default iSCSI name. The iSCSI name configures using the programming interfaces defined below. Successive configuration of the iSCSI initiator name overwrites the previously existing name. Once overwritten, the previous name will not be retrievable. Setting an iSCSI name string that is zero length is illegal. The maximum size of the iSCSI Initiator Name is 224 bytes (including the NULL terminator).

16.2.1. EFI_ISCSI_INITIATOR_NAME_PROTOCOL

Summary

iSCSI Initiator Name Protocol for setting and obtaining the iSCSI Initiator Name.

GUID

#define EFI_ISCSI_INITIATOR_NAME_PROTOCOL_GUID \
  {0x59324945, 0xec44, 0x4c0d, \
    {0xb1, 0xcd, 0x9d, 0xb1, 0x39, 0xdf, 0x07, 0x0c}}

Protocol Interface Structure

typedef struct _EFI_ISCSI_INITIATOR_NAME_PROTOCOL {
  EFI_ISCSI_INITIATOR_NAME_GET                    Get;
  EFI_ISCSI_INITIATOR_NAME_SET                    Set;
}   EFI_ISCSI_INITIATOR_NAME_PROTOCOL;

Parameters

Get

Used to retrieve the iSCSI Initiator Name.

Set

Used to set the iSCSI Initiator Name.

Description

The EFI_ISCSI_INIT_NAME_PROTOCOL provides the ability to get and set the iSCSI Initiator Name.

16.2.2. EFI_ISCSI_INITIATOR_NAME_PROTOCOL. Get()

Summary

Retrieves the current set value of iSCSI Initiator Name.

Prototype

typedef EFI_STATUS
(EFIAPI *EFI_ISCSI_INITIATOR_NAME_GET) (
  IN EFI_ISCSI_INITIATOR_NAME_PROTOCOL    *This,
  IN OUT UINTN                            *BufferSize,
  OUT VOID                                *Buffer
  );

Parameters

This

Pointer to the EFI_ISCSI_INITIATOR_NAME_PROTOCOL instance.

BufferSize

Size of the buffer in bytes pointed to by Buffer / Actual size of the variable data buffer.

Buffer

Pointer to the buffer for data to be read. The data is a null-terminated UTF-8 encoded string. The maximum length is 223 characters, including the null-terminator.

Description

This function will retrieve the iSCSI Initiator Name from Non-volatile memory.

Status Codes Returned

EFI_SUCCESS

Data was successfully retrieved into the provided buffer and the BufferSize was sufficient to handle the iSCSI initiator name

EFI_BUFFER_TOO_SMALL

BufferSize is too small for the result. BufferSize will be updated with the size required to complete the request. Buffer will not be affected.

EFI_INVALID_PARAMETER

BufferSize is NULL. BufferSize and Buffer will not be affected.

EFI_INVALID_PARAMETER

Buffer is NULL. BufferSize and Buffer will not be affected.

EFI_DEVICE_ERROR

The iSCSI initiator name could not be retrieved due to a hardware error.

16.2.3. EFI_ISCSI_INITIATOR_NAME_PROTOCOL.Set()

Summary

Sets the iSCSI Initiator Name.

Prototype

typedef EFI_STATUS
(EFIAPI *EFI_ISCSI_INITIATOR_NAME_SET) (
  IN EFI_ISCSI_INITIATOR_NAME_PROTOCOL       *This,
  IN OUT UINTN                               *BufferSize,
  IN VOID                                    *Buffer
  );

Parameters

This

Pointer to the EFI_ISCSI_INITIATOR_NAME_PROTOCOL instance

BufferSize

Size of the buffer in bytes pointed to by Buffer.

Buffer

Pointer to the buffer for data to be written. The data is a null-terminated UTF-8 encoded string. The maximum length is 223 characters, including the null-terminator.

Description

This function will set the iSCSI Initiator Name into Non-volatile memory.

Status Codes Returned

EFI_SUCCESS

Data was successfully stored by the protocol

EFI_UNSUPPORTED

Platform policies do not allow for data to be written

EFI_INVALID_PARAMETER

BufferSize exceeds the maximum allowed limit. BufferSize will be updated with the maximum size required to complete the request.

EFI_INVALID_PARAMETER

Buffersize is NULL. BufferSize and Buffer will not be affected

EFI_INVALID_PARAMETER

Buffer is NULL. BufferSize and Buffer will not be affected.

EFI_DEVICE_ERROR

The data could not be stored due to a hardware error.

EFI_OUT_OF_RESOURCES

Not enough storage is available to hold the data

EFI_PROTOCOL_ERROR

Input iSCSI initiator name does not adhere to RFC 3720 (and other related protocols)