-/*++\r
+/** @file\r
+ The header file of IScsi Protocol that defines many specific data structures.\r
\r
Copyright (c) 2004 - 2008, Intel Corporation\r
All rights reserved. This program and the accompanying materials\r
\r
Abstract:\r
\r
- Protocol definitions for iSCSI driver, mainly from RFC3720.\r
+ Protocol definitions for IScsi driver, mainly from RFC3720.\r
\r
---*/\r
+**/\r
\r
#ifndef _ISCSI_PROTO_H_\r
#define _ISCSI_PROTO_H_\r
//\r
// function prototypes.\r
//\r
+/**\r
+ Attach the iSCSI connection to the iSCSI session. \r
+\r
+ @param Session[in] The iSCSI session.\r
+\r
+ @param Conn[in] The iSCSI connection.\r
+\r
+ @retval None.\r
+\r
+**/\r
VOID\r
IScsiAttatchConnection (\r
IN ISCSI_SESSION *Session,\r
IN ISCSI_CONNECTION *Conn\r
);\r
\r
+/**\r
+ Detach the iSCSI connection from the session it belongs to. \r
+\r
+ @param Conn[in] The iSCSI connection.\r
+\r
+ @retval None.\r
+\r
+**/\r
VOID\r
IScsiDetatchConnection (\r
IN ISCSI_CONNECTION *Conn\r
);\r
\r
+/**\r
+ This function does the iSCSI connection login.\r
+\r
+ @param Conn[in] The iSCSI connection to login.\r
+\r
+ @retval EFI_SUCCESS The iSCSI connection is logged into the iSCSI target.\r
+\r
+ @retval EFI_TIMEOUT Timeout happened during the login procedure.\r
+\r
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.\r
+\r
+**/\r
EFI_STATUS\r
IScsiConnLogin (\r
IN ISCSI_CONNECTION *Conn\r
);\r
\r
+/**\r
+ Create a TCP connection for the iSCSI session.\r
+\r
+ @param Private[in] The iSCSI driver data.\r
+\r
+ @param Session[in] Maximum CmdSN from the target.\r
+\r
+ @retval The newly created iSCSI connection.\r
+\r
+**/\r
ISCSI_CONNECTION *\r
IScsiCreateConnection (\r
IN ISCSI_DRIVER_DATA *Private,\r
IN ISCSI_SESSION *Session\r
);\r
\r
+/**\r
+ Destroy an iSCSI connection.\r
+\r
+ @param Conn[in] The connection to destroy.\r
+\r
+ @retval None.\r
+\r
+**/\r
VOID\r
IScsiDestroyConnection (\r
IN ISCSI_CONNECTION *Conn\r
);\r
\r
+/**\r
+ Login the iSCSI session.\r
+\r
+ @param Private[in] The iSCSI driver data.\r
+\r
+ @retval EFI_SUCCESS The iSCSI session login procedure finished.\r
+\r
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.\r
+\r
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.\r
+\r
+**/\r
EFI_STATUS\r
IScsiSessionLogin (\r
IN ISCSI_DRIVER_DATA *Private\r
);\r
\r
+/**\r
+ Build and send the iSCSI login request to the iSCSI target according to\r
+ the current login stage.\r
+\r
+ @param Conn[in] The connection in the iSCSI login phase.\r
+\r
+ @retval EFI_SUCCESS The iSCSI login request PDU is built and sent on this\r
+ connection.\r
+\r
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.\r
+\r
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.\r
+\r
+**/\r
EFI_STATUS\r
IScsiSendLoginReq (\r
IN ISCSI_CONNECTION *Conn\r
);\r
\r
+/**\r
+ Receive and process the iSCSI login response.\r
+\r
+ @param Conn[in] The connection in the iSCSI login phase.\r
+\r
+ @retval EFI_SUCCESS The iSCSI login response PDU is received and processed.\r
+\r
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.\r
+\r
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.\r
+\r
+**/\r
EFI_STATUS\r
IScsiReceiveLoginRsp (\r
IN ISCSI_CONNECTION *Conn\r
);\r
\r
+/**\r
+ Add an iSCSI key-value pair as a string into the data segment of the Login Request PDU.\r
+ The DataSegmentLength and the actual size of the net buffer containing this PDU will be\r
+ updated.\r
+\r
+ @param Pdu[in] The iSCSI PDU whose data segment the key-value pair will\r
+ be added to.\r
+\r
+ @param Key[in] The key name string.\r
+\r
+ @param Value[in] The value string.\r
+\r
+ @retval EFI_SUCCESS The key-valu pair is added to the PDU's datasegment and\r
+ the correspondence length fields are updated.\r
+\r
+ @retval EFI_OUT_OF_RESOURCES There is not enough space in the PDU to add the key-value\r
+ pair.\r
+\r
+**/\r
EFI_STATUS\r
IScsiAddKeyValuePair (\r
IN NET_BUF *Pdu,\r
IN CHAR8 *Value\r
);\r
\r
-NET_BUF *\r
+/**\r
+ Prepare the iSCSI login request to be sent according to the current login status.\r
+\r
+ @param Conn[in] The connection in the iSCSI login phase.\r
+\r
+ @retval The pointer to the net buffer containing the iSCSI login request built.\r
+\r
+**/\r
+NET_BUF *\r
IScsiPrepareLoginReq (\r
IN ISCSI_CONNECTION *Conn\r
);\r
\r
+/**\r
+ Process the iSCSI Login Response.\r
+\r
+ @param Conn[in] The connection on which the iSCSI login response is received.\r
+\r
+ @param Pdu[in] The iSCSI login response PDU.\r
+\r
+ @retval EFI_SUCCESS The iSCSI login response PDU is processed and all check are passed.\r
+\r
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.\r
+\r
+**/\r
EFI_STATUS\r
IScsiProcessLoginRsp (\r
IN ISCSI_CONNECTION *Conn,\r
IN NET_BUF *Pdu\r
);\r
\r
+/**\r
+ Updated the target information according the data received in the iSCSI\r
+ login response with an target redirection status.\r
+\r
+ @param Session[in] The iSCSI session.\r
+\r
+ @param Data[in] The data segment which should contain the\r
+ TargetAddress key-value list.\r
+\r
+ @param Len[in] Length of the data.\r
+\r
+ @retval EFI_SUCCESS The target address is updated.\r
+\r
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.\r
+\r
+ @retval EFI_NOT_FOUND The TargetAddress key is not found.\r
+\r
+**/\r
EFI_STATUS\r
IScsiUpdateTargetAddress (\r
IN ISCSI_SESSION *Session,\r
IN UINT32 Len\r
);\r
\r
+/**\r
+ The callback function to free the net buffer list.\r
+\r
+ @param Arg[in] The opaque parameter.\r
+\r
+ @retval None.\r
+\r
+**/\r
VOID\r
IScsiFreeNbufList (\r
VOID *Arg\r
);\r
\r
+/**\r
+ Receive an iSCSI response PDU. An iSCSI response PDU contains an iSCSI PDU header and\r
+ an optional data segment. The two parts will be put into two blocks of buffers in the\r
+ net buffer. The digest check will be conducted in this function if needed and the digests\r
+ will be trimmed from the PDU buffer.\r
+\r
+ @param Conn[in] The iSCSI connection to receive data from.\r
+\r
+ @param Pdu[out] The received iSCSI pdu.\r
+\r
+ @param Context[in] The context used to describe information on the caller provided\r
+ buffer to receive data segment of the iSCSI pdu, it's optional.\r
+\r
+ @param HeaderDigest[in] Whether there will be header digest received.\r
+\r
+ @param DataDigest[in] Whether there will be data digest.\r
+\r
+ @param TimeoutEvent[in] The timeout event, it's optional.\r
+\r
+ @retval EFI_SUCCESS An iSCSI pdu is received.\r
+\r
+ @retval EFI_TIMEOUT Timeout happenend.\r
+\r
+**/\r
EFI_STATUS\r
IScsiReceivePdu (\r
IN ISCSI_CONNECTION *Conn,\r
IN EFI_EVENT TimeoutEvent OPTIONAL\r
);\r
\r
+/**\r
+ Check and get the result of the prameter negotiation.\r
+\r
+ @param Conn[in] The connection in iSCSI login.\r
+\r
+ @param Pdu[in] The iSCSI response PDU containing the parameter list.\r
+\r
+ @retval EFI_SUCCESS The parmeter check is passed and negotiation is finished.\r
+\r
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.\r
+\r
+**/\r
EFI_STATUS\r
IScsiCheckOpParams (\r
IN ISCSI_CONNECTION *Conn,\r
IN BOOLEAN Transit\r
);\r
\r
+/**\r
+ Fill the oprational prameters.\r
+\r
+ @param Conn[in] The connection in iSCSI login.\r
+\r
+ @param Pdu[in] The iSCSI login request PDU to fill the parameters.\r
+\r
+ @retval EFI_SUCCESS The parmeters are filled into the iSCSI login request PDU.\r
+\r
+ @retval EFI_OUT_OF_RESOURCES There is not enough space in the PDU to hold the parameters.\r
+\r
+**/\r
EFI_STATUS\r
IScsiFillOpParams (\r
IN ISCSI_CONNECTION *Conn,\r
IN NET_BUF *Pdu\r
);\r
\r
+/**\r
+ Pad the iSCSI AHS or data segment to an integer number of 4 byte words.\r
+\r
+ @param Pdu[in] The iSCSI pdu which contains segments to pad.\r
+\r
+ @param Len[in] The length of the last semgnet in the PDU.\r
+\r
+ @retval EFI_SUCCESS The segment is padded or no need to pad it.\r
+\r
+ @retval EFI_OUT_OF_RESOURCES There is not enough remaining free space to add the\r
+ padding bytes.\r
+\r
+**/\r
EFI_STATUS\r
IScsiPadSegment (\r
IN NET_BUF *Pdu,\r
IN UINT32 Len\r
);\r
\r
-LIST_ENTRY *\r
+/**\r
+ Build a key-value list from the data segment.\r
+\r
+ @param Data[in] The data segment containing the key-value pairs.\r
+\r
+ @param Len[in] Length of the data segment.\r
+\r
+ @retval The key-value list.\r
+\r
+**/\r
+LIST_ENTRY *\r
IScsiBuildKeyValueList (\r
IN CHAR8 *Data,\r
IN UINT32 Len\r
);\r
\r
-CHAR8 *\r
+/**\r
+ Get the value string by the key name from the key-value list. If found,\r
+ the key-value entry will be removed from the list.\r
+\r
+ @param KeyValueList[in] The key-value list.\r
+\r
+ @param Key[in] The key name to find.\r
+\r
+ @retval The value string.\r
+\r
+**/\r
+CHAR8 *\r
IScsiGetValueByKeyFromList (\r
IN LIST_ENTRY *KeyValueList,\r
IN CHAR8 *Key\r
);\r
\r
+/**\r
+ Free the key-value list.\r
+\r
+ @param KeyValueList[in] The key-value list.\r
+ \r
+ @retval None.\r
+\r
+**/\r
VOID\r
IScsiFreeKeyValueList (\r
IN LIST_ENTRY *KeyValueList\r
);\r
\r
+/**\r
+ Normalize the iSCSI name according to RFC.\r
+\r
+ @param Name[in] The iSCSI name.\r
+\r
+ @param Len[in] length of the iSCSI name.\r
+\r
+ @retval EFI_SUCCESS The iSCSI name is valid and normalized.\r
+\r
+ @retval EFI_PROTOCOL_ERROR The iSCSI name is mal-formatted or not in the IQN format.\r
+\r
+**/\r
EFI_STATUS\r
IScsiNormalizeName (\r
IN CHAR8 *Name,\r
IN UINTN Len\r
);\r
\r
+/**\r
+ Execute the SCSI command issued through the EXT SCSI PASS THRU protocol.\r
+\r
+ @param PassThru[in] The EXT SCSI PASS THRU protocol.\r
+\r
+ @param Target[in] The target ID.\r
+\r
+ @param Lun[in] The LUN.\r
+\r
+ @param Packet[in][out] The request packet containing IO request, SCSI command\r
+ buffer and buffers to read/write.\r
+\r
+ @retval EFI_SUCCES The SCSI command is executed and the result is updated to \r
+ the Packet.\r
+\r
+ @retval EFI_DEVICE_ERROR Some unexpected error happened.\r
+\r
+**/\r
EFI_STATUS\r
IScsiExecuteScsiCommand (\r
IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *PassThru,\r
IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet\r
);\r
\r
+/**\r
+ Reinstate the session on some error.\r
+\r
+ @param Private[in] The iSCSI driver data.\r
+\r
+ @retval EFI_SUCCES The session is reinstated from some error.\r
+\r
+ @retval other Reinstatement failed.\r
+\r
+**/\r
EFI_STATUS\r
IScsiSessionReinstatement (\r
IN ISCSI_DRIVER_DATA *Private\r
);\r
\r
+/**\r
+ Initialize some session parameters before login.\r
+\r
+ @param Session[in] The iSCSI session.\r
+\r
+ @param Recovery[in] Whether the request is from a fresh new start or recovery.\r
+\r
+ @retval None.\r
+\r
+**/\r
VOID\r
IScsiSessionInit (\r
IN ISCSI_SESSION *Session,\r
IN BOOLEAN Recovery\r
);\r
\r
+/**\r
+ Abort the iSCSI session, that is, reset all the connection and free the\r
+ resources.\r
+\r
+ @param Session[in] The iSCSI session.\r
+\r
+ @retval EFI_SUCCES The session is aborted.\r
+\r
+**/\r
EFI_STATUS\r
IScsiSessionAbort (\r
IN ISCSI_SESSION *Session\r
projects / mirror_edk2.git / blobdiff