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