diff options
| author | eric_tian <eric_tian@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-04-17 08:28:51 +0000 |
|---|---|---|
| committer | eric_tian <eric_tian@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-04-17 08:28:51 +0000 |
| commit | 12618416ec7a468bc7e47d9739cf973a0bb418fc (patch) | |
| tree | 1a23c7d46665240f08b061aaa13832da602162d3 | |
| parent | d16fc3dbb3461dab1cb8a8df21b9e3c2e09723e6 (diff) | |
| download | edk2-platforms-12618416ec7a468bc7e47d9739cf973a0bb418fc.tar.xz | |
[Description]
change the old code style to comply with Doxgen format
[Impaction]
add comments for every function
[Reference Info]
add comments to achieve the highest standard of code quality matrix
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5079 6f19259b-4bc3-4df7-8a09-765794883524
25 files changed, 2431 insertions, 2095 deletions
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/ComponentName.c b/MdeModulePkg/Universal/Network/IScsiDxe/ComponentName.c index 3deab7705b..bb7484e2dd 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/ComponentName.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/ComponentName.c @@ -1,6 +1,7 @@ -/*++
+/** @file
+ UEFI Component Name(2) protocol implementation.
-Copyright (c) 2004 - 2007, Intel Corporation
+Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -17,7 +18,7 @@ Abstract: ComponentName protocol for iSCSI.
---*/
+**/
#include "IScsiImpl.h"
@@ -40,10 +41,48 @@ GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME2_PROTOCOL gIScsiComponentNam };
GLOBAL_REMOVE_IF_UNREFERENCED EFI_UNICODE_STRING_TABLE mIScsiDriverNameTable[] = {
- {"eng;en", L"iSCSI Driver"},
- {NULL, NULL}
+ {"eng;en", L"iSCSI Driver"},
+ {NULL, NULL}
};
+/**
+ Retrieves a Unicode string that is the user readable name of the EFI Driver.
+
+ This function retrieves the user readable name of a driver in the form of a
+ Unicode string. If the driver specified by This has a user readable name in
+ the language specified by Language, then a pointer to the driver name is
+ returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
+ by This does not support the language specified by Language,
+ then EFI_UNSUPPORTED is returned.
+
+ @param This[in] A pointer to the EFI_COMPONENT_NAME_PROTOCOL
+ instance.
+
+ @param Language[in] A pointer to a three character ISO 639-2 language
+ identifier.
+ This is the language of the driver name that that
+ the caller is requesting, and it must match one of
+ the languages specified in SupportedLanguages.
+ The number of languages supported by a driver is up
+ to the driver writer.
+
+ @param DriverName[out] A pointer to the Unicode string to return.
+ This Unicode string is the name of the
+ driver specified by This in the language
+ specified by Language.
+
+ @retval EFI_SUCCESS The Unicode string for the Driver specified by
+ This and the language specified by Language was
+ returned in DriverName.
+
+ @retval EFI_INVALID_PARAMETER Language is NULL.
+
+ @retval EFI_INVALID_PARAMETER DriverName is NULL.
+
+ @retval EFI_UNSUPPORTED The driver specified by This does not support
+ the language specified by Language.
+
+**/
EFI_STATUS
EFIAPI
IScsiComponentNameGetDriverName (
@@ -51,32 +90,6 @@ IScsiComponentNameGetDriverName ( IN CHAR8 *Language,
OUT CHAR16 **DriverName
)
-/*++
-
- Routine Description:
- Retrieves a Unicode string that is the user readable name of the EFI Driver.
-
- Arguments:
- This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
- Language - A pointer to a three character ISO 639-2 language identifier.
- This is the language of the driver name that that the caller
- is requesting, and it must match one of the languages specified
- in SupportedLanguages. The number of languages supported by a
- driver is up to the driver writer.
- DriverName - A pointer to the Unicode string to return. This Unicode string
- is the name of the driver specified by This in the language
- specified by Language.
-
- Returns:
- EFI_SUCCESS - The Unicode string for the Driver specified by This
- and the language specified by Language was returned
- in DriverName.
- EFI_INVALID_PARAMETER - Language is NULL.
- EFI_INVALID_PARAMETER - DriverName is NULL.
- EFI_UNSUPPORTED - The driver specified by This does not support the
- language specified by Language.
-
---*/
{
return LookupUnicodeString2 (
Language,
@@ -87,6 +100,55 @@ IScsiComponentNameGetDriverName ( );
}
+/**
+ Retrieves a Unicode string that is the user readable name of the controller
+ that is being managed by an EFI Driver.
+
+ @param This[in] A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
+
+ @param ControllerHandle[in] The handle of a controller that the driver specified by
+ This is managing. This handle specifies the controller
+ whose name is to be returned.
+
+ @param ChildHandle[in] The handle of the child controller to retrieve the name
+ of. This is an optional parameter that may be NULL. It
+ will be NULL for device drivers. It will also be NULL
+ for a bus drivers that wish to retrieve the name of the
+ bus controller. It will not be NULL for a bus driver
+ that wishes to retrieve the name of a child controller.
+
+ @param Language[in] A pointer to a three character ISO 639-2 language
+ identifier. This is the language of the controller name
+ that that the caller is requesting, and it must match one
+ of the languages specified in SupportedLanguages. The
+ number of languages supported by a driver is up to the
+ driver writer.
+
+ @param ControllerName[out] A pointer to the Unicode string to return. This Unicode
+ string is the name of the controller specified by
+ ControllerHandle and ChildHandle in the language
+ specified by Language from the point of view of the
+ driver specified by This.
+
+ @retval EFI_SUCCESS The Unicode string for the user readable name in the
+ language specified by Language for the driver
+ specified by This was returned in DriverName.
+
+ @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
+
+ @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid EFI_HANDLE.
+
+ @retval EFI_INVALID_PARAMETER Language is NULL.
+
+ @retval EFI_INVALID_PARAMETER ControllerName is NULL.
+
+ @retval EFI_UNSUPPORTED The driver specified by This is not currently managing
+ the controller specified by ControllerHandle and ChildHandle.
+
+ @retval EFI_UNSUPPORTED The driver specified by This does not support the
+ language specified by Language.
+
+**/
EFI_STATUS
EFIAPI
IScsiComponentNameGetControllerName (
@@ -96,51 +158,6 @@ IScsiComponentNameGetControllerName ( IN CHAR8 *Language,
OUT CHAR16 **ControllerName
)
-/*++
-
- Routine Description:
- Retrieves a Unicode string that is the user readable name of the controller
- that is being managed by an EFI Driver.
-
- Arguments:
- This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
- ControllerHandle - The handle of a controller that the driver specified by
- This is managing. This handle specifies the controller
- whose name is to be returned.
- ChildHandle - The handle of the child controller to retrieve the name
- of. This is an optional parameter that may be NULL. It
- will be NULL for device drivers. It will also be NULL
- for a bus drivers that wish to retrieve the name of the
- bus controller. It will not be NULL for a bus driver
- that wishes to retrieve the name of a child controller.
- Language - A pointer to a three character ISO 639-2 language
- identifier. This is the language of the controller name
- that that the caller is requesting, and it must match one
- of the languages specified in SupportedLanguages. The
- number of languages supported by a driver is up to the
- driver writer.
- ControllerName - A pointer to the Unicode string to return. This Unicode
- string is the name of the controller specified by
- ControllerHandle and ChildHandle in the language
- specified by Language from the point of view of the
- driver specified by This.
-
- Returns:
- EFI_SUCCESS - The Unicode string for the user readable name in the
- language specified by Language for the driver
- specified by This was returned in DriverName.
- EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.
- EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid
- EFI_HANDLE.
- EFI_INVALID_PARAMETER - Language is NULL.
- EFI_INVALID_PARAMETER - ControllerName is NULL.
- EFI_UNSUPPORTED - The driver specified by This is not currently
- managing the controller specified by
- ControllerHandle and ChildHandle.
- EFI_UNSUPPORTED - The driver specified by This does not support the
- language specified by Language.
-
---*/
{
return EFI_UNSUPPORTED;
}
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.c b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.c index 4dca145318..0dcb9a8796 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.c @@ -1,6 +1,7 @@ -/*++
+/** @file
+ Challenge-Handshake Authentication Protocol (CHAP) Configuration
-Copyright (c) 2004 - 2007, Intel Corporation
+Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -15,7 +16,9 @@ Module Name: Abstract:
---*/
+ This file is for CHAP configuration
+
+**/
#include "IScsiImpl.h"
#include "Md5.h"
@@ -92,30 +95,26 @@ IScsiCHAPAuthTarget ( return Status;
}
-EFI_STATUS
-IScsiCHAPOnRspReceived (
- IN ISCSI_CONNECTION *Conn,
- IN BOOLEAN Transit
- )
-/*++
-
-Routine Description:
-
+/**
This function checks the received iSCSI Login Response during the security
negotiation stage.
-Arguments:
+ @param Conn[in] The iSCSI connection.
- Conn - The iSCSI connection.
- Transit - The transit flag of the latest iSCSI Login Response.
+ @param Transit[in] The transit flag of the latest iSCSI Login Response.
-Returns:
+ @retval EFI_SUCCESS The Login Response passed the CHAP validation.
- EFI_SUCCESS - The Login Response passed the CHAP validation.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
- EFI_PROTOCOL_ERROR - Some kind of protocol error happend.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
---*/
+ @retval EFI_PROTOCOL_ERROR Some kind of protocol error happend.
+
+**/
+EFI_STATUS
+IScsiCHAPOnRspReceived (
+ IN ISCSI_CONNECTION *Conn,
+ IN BOOLEAN Transit
+ )
{
EFI_STATUS Status;
ISCSI_SESSION *Session;
@@ -288,31 +287,27 @@ ON_EXIT: return Status;
}
-EFI_STATUS
-IScsiCHAPToSendReq (
- IN ISCSI_CONNECTION *Conn,
- IN NET_BUF *Pdu
- )
-/*++
-
-Routine Description:
-
+/**
This function fills the CHAP authentication information into the login PDU
during the security negotiation stage in the iSCSI connection login.
-
-Arguments:
- Conn - The iSCSI connection.
- Pdu - The PDU to send out.
+ @param Conn[in] The iSCSI connection.
-Returns:
+ @param Pdu[in] The PDU to send out.
- EFI_SUCCESS - All check passed and the phase-related CHAP authentication
- info is filled into the iSCSI PDU.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
- EFI_PROTOCOL_ERROR - Some kind of protocol error happend.
+ @retval EFI_SUCCESS All check passed and the phase-related CHAP
+ authentication info is filled into the iSCSI PDU.
---*/
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+ @retval EFI_PROTOCOL_ERROR Some kind of protocol error happend.
+
+**/
+EFI_STATUS
+IScsiCHAPToSendReq (
+ IN ISCSI_CONNECTION *Conn,
+ IN NET_BUF *Pdu
+ )
{
EFI_STATUS Status;
ISCSI_SESSION *Session;
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.h index 2889167b32..bd5b13c00c 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.h @@ -1,4 +1,5 @@ -/*++
+/** @file
+ The header file of CHAP configuration
Copyright (c) 2004 - 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -14,8 +15,8 @@ Module Name: IScsiCHAP.h
Abstract:
-
---*/
+ the header file for CHAP
+**/
#ifndef _ISCSI_CHAP_H_
#define _ISCSI_CHAP_H_
@@ -80,12 +81,43 @@ typedef struct _ISCSI_CHAP_AUTH_DATA { UINT32 OutChallengeLength;
} ISCSI_CHAP_AUTH_DATA;
+/**
+ This function checks the received iSCSI Login Response during the security
+ negotiation stage.
+
+ @param Conn[in] The iSCSI connection.
+
+ @param Transit[in] The transit flag of the latest iSCSI Login Response.
+
+ @retval EFI_SUCCESS The Login Response passed the CHAP validation.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+ @retval EFI_PROTOCOL_ERROR Some kind of protocol error happend.
+
+**/
EFI_STATUS
IScsiCHAPOnRspReceived (
IN ISCSI_CONNECTION *Conn,
IN BOOLEAN Transit
);
+/**
+ This function fills the CHAP authentication information into the login PDU
+ during the security negotiation stage in the iSCSI connection login.
+
+ @param Conn[in] The iSCSI connection.
+
+ @param Pdu[in] The PDU to send out.
+
+ @retval EFI_SUCCESS All check passed and the phase-related CHAP
+ authentication info is filled into the iSCSI PDU.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+ @retval EFI_PROTOCOL_ERROR Some kind of protocol error happend.
+
+**/
EFI_STATUS
IScsiCHAPToSendReq (
IN ISCSI_CONNECTION *Conn,
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCommon.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCommon.h index 3f5e0187b7..cd5d257d9e 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCommon.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCommon.h @@ -1,6 +1,7 @@ -/*++
+/** @file
+ The common header file of Iscsi
-Copyright (c) 2004 - 2007, Intel Corporation
+Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -15,7 +16,9 @@ Module Name: Abstract:
---*/
+ The common header file of Iscsi
+
+**/
#ifndef _ISCSI_COMMON_H_
#define _ISCSI_COMMON_H_
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfig.c b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfig.c index 4944152111..e196ffda3d 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfig.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfig.c @@ -1,4 +1,5 @@ -/*++
+/** @file
+ Helper functions for configuring or getting the parameters relating to ISCSI
Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -15,7 +16,9 @@ Module Name: Abstract:
---*/
+ Helper functions for configuring or getting the parameters relating to ISCSI
+
+**/
#include "IScsiImpl.h"
@@ -29,76 +32,56 @@ LIST_ENTRY mIScsiConfigFormList = { &mIScsiConfigFormList
};
+/**
+ Convert the IPv4 address into a dotted string.
+
+ @param Ip[in] The IPv4 address.
+
+ @param Str[out] The dotted IP string.
+
+ @retval None.
+
+**/
STATIC
VOID
IScsiIpToStr (
IN EFI_IPv4_ADDRESS *Ip,
OUT CHAR16 *Str
)
-/*++
-
-Routine Description:
-
- Convert the IPv4 address into a dotted string.
-
-Arguments:
-
- Ip - The IPv4 address.
- Str - The dotted IP string.
-
-Returns:
-
- None.
-
---*/
{
UnicodeSPrint ( Str, 2 * IP4_STR_MAX_SIZE, L"%d.%d.%d.%d", Ip->Addr[0], Ip->Addr[1], Ip->Addr[2], Ip->Addr[3]);
}
-VOID
-PopUpInvalidNotify (
- IN CHAR16 *Warning
- )
-/*++
-
-Routine Description:
-
+/**
Pop up an invalid notify which displays the message in Warning.
-Arguments:
-
- Warning - The warning message.
+ @param Warning[in] The warning message.
-Returns:
+ @retval None.
- None.
-
---*/
+**/
+VOID
+PopUpInvalidNotify (
+ IN CHAR16 *Warning
+ )
{
EFI_INPUT_KEY Key;
IfrLibCreatePopUp (1, &Key, Warning);
}
-EFI_STATUS
-IScsiUpdateDeviceList (
- VOID
- )
-/*++
-
-Routine Description:
-
+/**
Update the list of iSCSI devices the iSCSI driver is controlling.
-Arguments:
-
- None.
+ @param None.
-Returns:
+ @retval None.
- None.
-
---*/
+**/
+EFI_STATUS
+IScsiUpdateDeviceList (
+ VOID
+ )
{
EFI_STATUS Status;
ISCSI_DEVICE_LIST *DeviceList;
@@ -226,26 +209,19 @@ Returns: return Status;
}
+/**
+ Get the iSCSI configuration form entry by the index of the goto opcode actived.
+
+ @param Index[in] The 0-based index of the goto opcode actived.
+
+ @retval The iSCSI configuration form entry found.
+
+**/
STATIC
ISCSI_CONFIG_FORM_ENTRY *
IScsiGetConfigFormEntryByIndex (
IN UINT32 Index
)
-/*++
-
-Routine Description:
-
- Get the iSCSI configuration form entry by the index of the goto opcode actived.
-
-Arguments:
-
- Index - The 0-based index of the goto opcode actived.
-
-Returns:
-
- The iSCSI configuration form entry found.
-
---*/
{
UINT32 CurrentIndex;
LIST_ENTRY *Entry;
@@ -266,28 +242,22 @@ Returns: return ConfigFormEntry;
}
+/**
+ Convert the iSCSI configuration data into the IFR data.
+
+ @param ConfigFormEntry[in] The iSCSI configuration form entry.
+
+ @param IfrNvData[in] The IFR nv data.
+
+ @retval None.
+
+**/
STATIC
VOID
IScsiConvertDeviceConfigDataToIfrNvData (
IN ISCSI_CONFIG_FORM_ENTRY *ConfigFormEntry,
IN ISCSI_CONFIG_IFR_NVDATA *IfrNvData
)
-/*++
-
-Routine Description:
-
- Convert the iSCSI configuration data into the IFR data.
-
-Arguments:
-
- ConfigFormEntry - The iSCSI configuration form entry.
- IfrNvData - The IFR nv data.
-
-Returns:
-
- None.
-
---*/
{
ISCSI_SESSION_CONFIG_NVDATA *SessionConfigData;
ISCSI_CHAP_AUTH_CONFIG_NVDATA *AuthConfigData;
@@ -324,7 +294,33 @@ Returns: IScsiAsciiStrToUnicodeStr (AuthConfigData->ReverseCHAPSecret, IfrNvData->ReverseCHAPSecret);
}
+/**
+ This function allows a caller to extract the current configuration for one
+ or more named elements from the target driver.
+
+ @param This[in] Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
+
+ @param Request[in] A null-terminated Unicode string in <ConfigRequest> format.
+ @param Progress[out] On return, points to a character in the Request string.
+ Points to the string's null terminator if request was successful.
+ Points to the most recent '&' before the first failing name/value
+ pair (or the beginning of the string if the failure is in the
+ first name/value pair) if the request was not successful.
+
+ @param Results[out] A null-terminated Unicode string in <ConfigAltResp> format which
+ has all values filled in for the names in the Request string.
+ String to be allocated by the called function.
+
+ @retval EFI_SUCCESS The Results is filled with the requested values.
+
+ @retval EFI_OUT_OF_RESOURCES Not enough memory to store the results.
+
+ @retval EFI_INVALID_PARAMETER Request is NULL, illegal syntax, or unknown name.
+
+ @retval EFI_NOT_FOUND Routing data doesn't match any storage in this driver.
+
+**/
EFI_STATUS
EFIAPI
IScsiFormExtractConfig (
@@ -333,31 +329,6 @@ IScsiFormExtractConfig ( OUT EFI_STRING *Progress,
OUT EFI_STRING *Results
)
-/*++
-
- Routine Description:
- This function allows a caller to extract the current configuration for one
- or more named elements from the target driver.
-
- Arguments:
- This - Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
- Request - A null-terminated Unicode string in <ConfigRequest> format.
- Progress - On return, points to a character in the Request string.
- Points to the string's null terminator if request was successful.
- Points to the most recent '&' before the first failing name/value
- pair (or the beginning of the string if the failure is in the
- first name/value pair) if the request was not successful.
- Results - A null-terminated Unicode string in <ConfigAltResp> format which
- has all values filled in for the names in the Request string.
- String to be allocated by the called function.
-
- Returns:
- EFI_SUCCESS - The Results is filled with the requested values.
- EFI_OUT_OF_RESOURCES - Not enough memory to store the results.
- EFI_INVALID_PARAMETER - Request is NULL, illegal syntax, or unknown name.
- EFI_NOT_FOUND - Routing data doesn't match any storage in this driver.
-
---*/
{
EFI_STATUS Status;
CHAR8 InitiatorName[ISCSI_NAME_IFR_MAX_SIZE];
@@ -406,6 +377,25 @@ IScsiFormExtractConfig ( return Status;
}
+/**
+ This function processes the results of changes in configuration.
+
+ @param This[in] Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
+
+ @param Configuration[in] A null-terminated Unicode string in <ConfigResp> format.
+
+ @param Progress[out] A pointer to a string filled in with the offset of the most
+ recent '&' before the first failing name/value pair (or the
+ beginning of the string if the failure is in the first
+ name/value pair) or the terminating NULL if all was successful.
+
+ @retval EFI_SUCCESS The Results is processed successfully.
+
+ @retval EFI_INVALID_PARAMETER Configuration is NULL.
+
+ @retval EFI_NOT_FOUND Routing data doesn't match any storage in this driver.
+
+**/
EFI_STATUS
EFIAPI
IScsiFormRouteConfig (
@@ -413,29 +403,35 @@ IScsiFormRouteConfig ( IN CONST EFI_STRING Configuration,
OUT EFI_STRING *Progress
)
-/*++
+{
+ return EFI_SUCCESS;
+}
- Routine Description:
- This function processes the results of changes in configuration.
+/**
+ This function processes the results of changes in configuration.
- Arguments:
- This - Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
- Configuration - A null-terminated Unicode string in <ConfigResp> format.
- Progress - A pointer to a string filled in with the offset of the most
- recent '&' before the first failing name/value pair (or the
- beginning of the string if the failure is in the first
- name/value pair) or the terminating NULL if all was successful.
+ @param This[in] Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
- Returns:
- EFI_SUCCESS - The Results is processed successfully.
- EFI_INVALID_PARAMETER - Configuration is NULL.
- EFI_NOT_FOUND - Routing data doesn't match any storage in this driver.
+ @param Action[in] Specifies the type of action taken by the browser.
---*/
-{
- return EFI_SUCCESS;
-}
+ @param QuestionId[in] A unique value which is sent to the original exporting driver
+ so that it can identify the type of data to expect.
+
+ @param Type[in] The type of value for the question.
+
+ @param Value[in] A pointer to the data being sent to the original exporting driver.
+
+ @param ActionRequest[out] On return, points to the action requested by the callback function.
+
+ @retval EFI_SUCCESS The callback successfully handled the action.
+
+ @retval EFI_OUT_OF_RESOURCES Not enough storage is available to hold the variable and its data.
+ @retval EFI_DEVICE_ERROR The variable could not be saved.
+
+ @retval EFI_UNSUPPORTED The specified Action is not supported by the callback.
+
+**/
EFI_STATUS
EFIAPI
IScsiFormCallback (
@@ -446,27 +442,6 @@ IScsiFormCallback ( IN EFI_IFR_TYPE_VALUE *Value,
OUT EFI_BROWSER_ACTION_REQUEST *ActionRequest
)
-/*++
-
- Routine Description:
- This function processes the results of changes in configuration.
-
- Arguments:
- This - Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
- Action - Specifies the type of action taken by the browser.
- QuestionId - A unique value which is sent to the original exporting driver
- so that it can identify the type of data to expect.
- Type - The type of value for the question.
- Value - A pointer to the data being sent to the original exporting driver.
- ActionRequest - On return, points to the action requested by the callback function.
-
- Returns:
- EFI_SUCCESS - The callback successfully handled the action.
- EFI_OUT_OF_RESOURCES - Not enough storage is available to hold the variable and its data.
- EFI_DEVICE_ERROR - The variable could not be saved.
- EFI_UNSUPPORTED - The specified Action is not supported by the callback.
-
---*/
{
ISCSI_FORM_CALLBACK_INFO *Private;
UINTN BufferSize;
@@ -722,32 +697,27 @@ IScsiFormCallback ( return Status;
}
-
-EFI_STATUS
-IScsiConfigUpdateForm (
- IN EFI_HANDLE DriverBindingHandle,
- IN EFI_HANDLE Controller,
- IN BOOLEAN AddForm
- )
-/*++
-
-Routine Description:
-
+/**
Updates the iSCSI configuration form to add/delete an entry for the iSCSI
device specified by the Controller.
-Arguments:
+ @param DriverBindingHandle[in] The driverbinding handle.
+
+ @param Controller[in] The controller handle of the iSCSI device.
- DriverBindingHandle - The driverbinding handle.
- Controller - The controller handle of the iSCSI device.
- AddForm - Whether to add or delete a form entry.
+ @param AddForm[in] Whether to add or delete a form entry.
-Returns:
+ @retval EFI_SUCCESS The iSCSI configuration form is updated.
- EFI_SUCCESS - The iSCSI configuration form is updated.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
---*/
+**/
+EFI_STATUS
+IScsiConfigUpdateForm (
+ IN EFI_HANDLE DriverBindingHandle,
+ IN EFI_HANDLE Controller,
+ IN BOOLEAN AddForm
+ )
{
LIST_ENTRY *Entry;
ISCSI_CONFIG_FORM_ENTRY *ConfigFormEntry;
@@ -887,26 +857,20 @@ Returns: return EFI_SUCCESS;
}
-EFI_STATUS
-IScsiConfigFormInit (
- IN EFI_HANDLE DriverBindingHandle
- )
-/*++
-
-Routine Description:
-
+/**
Initialize the iSCSI configuration form.
-Arguments:
+ @param DriverBindingHandle[in] The iSCSI driverbinding handle.
- DriverBindingHandle - The iSCSI driverbinding handle.
+ @retval EFI_SUCCESS The iSCSI configuration form is initialized.
-Returns:
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
- EFI_SUCCESS - The iSCSI configuration form is initialized.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
-
---*/
+**/
+EFI_STATUS
+IScsiConfigFormInit (
+ IN EFI_HANDLE DriverBindingHandle
+ )
{
EFI_STATUS Status;
EFI_HII_DATABASE_PROTOCOL *HiiDatabase;
@@ -980,28 +944,22 @@ Returns: return Status;
}
-EFI_STATUS
-IScsiConfigFormUnload (
- IN EFI_HANDLE DriverBindingHandle
- )
-/*++
-
-Routine Description:
-
+/**
Unload the iSCSI configuration form, this includes: delete all the iSCSI
device configuration entries, uninstall the form callback protocol and
free the resources used.
-Arguments:
-
- DriverBindingHandle - The iSCSI driverbinding handle.
+ @param DriverBindingHandle[in] The iSCSI driverbinding handle.
-Returns:
+ @retval EFI_SUCCESS The iSCSI configuration form is unloaded.
- EFI_SUCCESS - The iSCSI configuration form is unloaded.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
---*/
+**/
+EFI_STATUS
+IScsiConfigFormUnload (
+ IN EFI_HANDLE DriverBindingHandle
+ )
{
ISCSI_CONFIG_FORM_ENTRY *ConfigFormEntry;
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfig.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfig.h index c3c664d449..8f48be9a14 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfig.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfig.h @@ -1,6 +1,7 @@ -/*++
+/** @file
+ The header file of IScsiConfig.c
-Copyright (c) 2004 - 2007, Intel Corporation
+Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -15,8 +16,9 @@ Module Name: Abstract:
+ The header file of IScsiConfig.c
---*/
+**/
#ifndef _ISCSI_CONFIG_H_
#define _ISCSI_CONFIG_H_
@@ -84,6 +86,21 @@ typedef struct _ISCSI_FORM_CALLBACK_INFO { ISCSI_CONFIG_FORM_ENTRY *Current;
} ISCSI_FORM_CALLBACK_INFO;
+/**
+ Updates the iSCSI configuration form to add/delete an entry for the iSCSI
+ device specified by the Controller.
+
+ @param DriverBindingHandle[in] The driverbinding handle.
+
+ @param Controller[in] The controller handle of the iSCSI device.
+
+ @param AddForm[in] Whether to add or delete a form entry.
+
+ @retval EFI_SUCCESS The iSCSI configuration form is updated.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+**/
EFI_STATUS
IScsiConfigUpdateForm (
IN EFI_HANDLE DriverBindingHandle,
@@ -91,11 +108,33 @@ IScsiConfigUpdateForm ( IN BOOLEAN AddForm
);
+/**
+ Initialize the iSCSI configuration form.
+
+ @param DriverBindingHandle[in] The iSCSI driverbinding handle.
+
+ @retval EFI_SUCCESS The iSCSI configuration form is initialized.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+**/
EFI_STATUS
IScsiConfigFormInit (
IN EFI_HANDLE DriverBindingHandle
);
+/**
+ Unload the iSCSI configuration form, this includes: delete all the iSCSI
+ device configuration entries, uninstall the form callback protocol and
+ free the resources used.
+
+ @param DriverBindingHandle[in] The iSCSI driverbinding handle.
+
+ @retval EFI_SUCCESS The iSCSI configuration form is unloaded.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+**/
EFI_STATUS
IScsiConfigFormUnload (
IN EFI_HANDLE DriverBindingHandle
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfigNVDataStruc.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfigNVDataStruc.h index 768547a314..516b45913e 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfigNVDataStruc.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiConfigNVDataStruc.h @@ -1,4 +1,5 @@ -/*++
+/** @file
+ Define NVData structures used by the iSCSI configuration component
Copyright (c) 2004 - 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -17,7 +18,7 @@ Abstract: NVData structure used by the iSCSI configuration component.
---*/
+**/
#ifndef _ISCSI_NVDATASTRUC_H_
#define _ISCSI_NVDATASTRUC_H_
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDhcp.c b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDhcp.c index df4772b8c4..6b7e83d2ce 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDhcp.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDhcp.c @@ -1,4 +1,5 @@ -/*++
+/**
+ ISci DHCP related configuration routines.
Copyright (c) 2004 - 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -15,12 +16,30 @@ Module Name: Abstract:
- iSCSI DHCP related configuration routines.
+ IScsi DHCP related configuration routines.
---*/
+**/
#include "IScsiImpl.h"
+/**
+ Extract the Root Path option and get the required target information.
+
+ @param RootPath[in] The RootPath.
+
+ @param Length[in] Length of the RootPath option payload.
+
+ @param ConfigNvData[in] The iSCSI session configuration data read from nonvolatile device.
+
+ @retval EFI_SUCCESS All required information is extracted from the RootPath option.
+
+ @retval EFI_NOT_FOUND The RootPath is not an iSCSI RootPath.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+ @retval EFI_INVALID_PARAMETER The RootPath is mal-formatted.
+
+**/
STATIC
EFI_STATUS
IScsiDhcpExtractRootPath (
@@ -28,26 +47,6 @@ IScsiDhcpExtractRootPath ( IN UINT8 Length,
IN ISCSI_SESSION_CONFIG_NVDATA *ConfigNvData
)
-/*++
-
-Routine Description:
-
- Extract the Root Path option and get the required target information.
-
-Arguments:
-
- RootPath - The RootPath.
- Length - Length of the RootPath option payload.
- ConfigNvData - The iSCSI session configuration data read from nonvolatile device.
-
-Returns:
-
- EFI_SUCCESS - All required information is extracted from the RootPath option.
- EFI_NOT_FOUND - The RootPath is not an iSCSI RootPath.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
- EFI_INVALID_PARAMETER - The RootPath is mal-formatted.
-
---*/
{
EFI_STATUS Status;
UINT8 IScsiRootPathIdLen;
@@ -183,6 +182,28 @@ ON_EXIT: return Status;
}
+/**
+ The callback function registerd to the DHCP4 instance which is used to select
+ the qualified DHCP OFFER.
+
+ @param This[in] The DHCP4 protocol.
+
+ @param Context[in] The context set when configuring the DHCP4 protocol.
+
+ @param CurrentState[in] The current state of the DHCP4 protocol.
+
+ @param Dhcp4Event[in] The event occurs in the current state.
+
+ @param Packet[in] The DHCP packet that is to be sent or already received.
+
+ @param NewPackt[out] The packet used to replace the above Packet.
+
+ @retval EFI_NOT_READY The DHCP OFFER packet doesn't match our requirements.
+
+ @retval EFI_SUCCESS Either the DHCP OFFER is qualified or we're not intereseted
+ in the Dhcp4Event.
+
+**/
STATIC
EFI_STATUS
IScsiDhcpSelectOffer (
@@ -193,29 +214,6 @@ IScsiDhcpSelectOffer ( IN EFI_DHCP4_PACKET * Packet, OPTIONAL
OUT EFI_DHCP4_PACKET **NewPacket OPTIONAL
)
-/*++
-
-Routine Description:
-
- The callback function registerd to the DHCP4 instance which is used to select
- the qualified DHCP OFFER.
-
-Arguments:
-
- This - The DHCP4 protocol.
- Context - The context set when configuring the DHCP4 protocol.
- CurrentState - The current state of the DHCP4 protocol.
- Dhcp4Event - The event occurs in the current state.
- Packet - The DHCP packet that is to be sent or already received.
- NewPackt - The packet used to replace the above Packet.
-
-Returns:
-
- EFI_NOT_READY - The DHCP OFFER packet doesn't match our requirements.
- EFI_SUCCESS - Either the DHCP OFFER is qualified or we're not intereseted
- in the Dhcp4Event.
-
---*/
{
EFI_STATUS Status;
UINT32 OptionCount;
@@ -267,30 +265,27 @@ Returns: return Status;
}
-EFI_STATUS
-IScsiParseDhcpAck (
- IN EFI_DHCP4_PROTOCOL *Dhcp4,
- IN ISCSI_SESSION_CONFIG_DATA *ConfigData
- )
-/*++
+/**
+ Parse the DHCP ACK to get the address configuration and DNS information.
-Routine Description:
+ @param Dhcp4[in] The DHCP4 protocol.
- Parse the DHCP ACK to get the address configuration and DNS information.
-
-Arguments:
+ @param ConfigData[in] The session configuration data.
- Dhcp4 - The DHCP4 protocol.
- ConfigData - The session configuration data.
+ @retval EFI_SUCCESS The DNS information is got from the DHCP ACK.
-Returns:
+ @retval EFI_NO_MAPPING DHCP failed to acquire address and other information.
- EFI_SUCCESS - The DNS information is got from the DHCP ACK.
- EFI_NO_MAPPING - DHCP failed to acquire address and other information.
- EFI_INVALID_PARAMETER - The DHCP ACK's DNS option is mal-formatted.
- EFI_DEVICE_ERROR - Some unexpected error happened.
+ @retval EFI_INVALID_PARAMETER The DHCP ACK's DNS option is mal-formatted.
---*/
+ @retval EFI_DEVICE_ERROR Some unexpected error happened.
+
+**/
+EFI_STATUS
+IScsiParseDhcpAck (
+ IN EFI_DHCP4_PROTOCOL *Dhcp4,
+ IN ISCSI_SESSION_CONFIG_DATA *ConfigData
+ )
{
EFI_STATUS Status;
EFI_DHCP4_MODE_DATA Dhcp4ModeData;
@@ -366,32 +361,30 @@ Returns: return Status;
}
-EFI_STATUS
-IScsiDoDhcp (
- IN EFI_HANDLE Image,
- IN EFI_HANDLE Controller,
- IN ISCSI_SESSION_CONFIG_DATA *ConfigData
- )
-/*++
-
-Routine Description:
-
+/**
Parse the DHCP ACK to get the address configuration and DNS information.
-Arguments:
+ @param Image[in] The handle of the driver image.
+
+ @param Controller[in] The handle of the controller;
- Image - The handle of the driver image.
- Controller - The handle of the controller;
- ConfigData - The session configuration data.
+ @param ConfigData[in] The session configuration data.
-Returns:
+ @retval EFI_SUCCESS The DNS information is got from the DHCP ACK.
- EFI_SUCCESS - The DNS information is got from the DHCP ACK.
- EFI_NO_MAPPING - DHCP failed to acquire address and other information.
- EFI_INVALID_PARAMETER - The DHCP ACK's DNS option is mal-formatted.
- EFI_DEVICE_ERROR - Some unexpected error happened.
+ @retval EFI_NO_MAPPING DHCP failed to acquire address and other information.
---*/
+ @retval EFI_INVALID_PARAMETER The DHCP ACK's DNS option is mal-formatted.
+
+ @retval EFI_DEVICE_ERROR Some unexpected error happened.
+
+**/
+EFI_STATUS
+IScsiDoDhcp (
+ IN EFI_HANDLE Image,
+ IN EFI_HANDLE Controller,
+ IN ISCSI_SESSION_CONFIG_DATA *ConfigData
+ )
{
EFI_HANDLE Dhcp4Handle;
EFI_DHCP4_PROTOCOL *Dhcp4;
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDhcp.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDhcp.h index 92b303976e..75bc7a1673 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDhcp.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDhcp.h @@ -1,4 +1,5 @@ -/*++
+/** @file
+ Data structure for DHCP support
Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -14,8 +15,9 @@ Module Name: IScsiDhcp.h
Abstract:
+ The header file of IScsiDhcp.c
---*/
+**/
#ifndef _ISCSI_DHCP_H_
#define _ISCSI_DHCP_H_
@@ -45,6 +47,24 @@ typedef struct _ISCSI_ROOT_PATH_FIELD { UINT8 Len;
} ISCSI_ROOT_PATH_FIELD;
+/**
+ Parse the DHCP ACK to get the address configuration and DNS information.
+
+ @param Image[in] The handle of the driver image.
+
+ @param Controller[in] The handle of the controller;
+
+ @param ConfigData[in] The session configuration data.
+
+ @retval EFI_SUCCESS The DNS information is got from the DHCP ACK.
+
+ @retval EFI_NO_MAPPING DHCP failed to acquire address and other information.
+
+ @retval EFI_INVALID_PARAMETER The DHCP ACK's DNS option is mal-formatted.
+
+ @retval EFI_DEVICE_ERROR Some unexpected error happened.
+
+**/
EFI_STATUS
IScsiDoDhcp (
IN EFI_HANDLE Image,
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDriver.c b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDriver.c index de93240b05..beee62c51b 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDriver.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDriver.c @@ -1,4 +1,5 @@ -/*++
+/** @file
+ The entry point of IScsi driver
Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -14,8 +15,9 @@ Module Name: IScsiDriver.c
Abstract:
+ The entry point of IScsi driver
---*/
+**/
#include "IScsiImpl.h"
@@ -30,32 +32,29 @@ EFI_DRIVER_BINDING_PROTOCOL gIScsiDriverBinding = { EFI_GUID mIScsiPrivateGuid = ISCSI_PRIVATE_GUID;
-EFI_STATUS
-EFIAPI
-IScsiDriverBindingSupported (
- IN EFI_DRIVER_BINDING_PROTOCOL * This,
- IN EFI_HANDLE ControllerHandle,
- IN EFI_DEVICE_PATH_PROTOCOL * RemainingDevicePath OPTIONAL
- )
-/*++
+/**
+ Test to see if IScsi driver supports the given controller.
-Routine Description:
+ @param This[in] Protocol instance pointer.
- Test to see if iSCSI driver supports the given controller.
+ @param ControllerHandle[in] Handle of controller to test.
-Arguments:
+ @param RemainingDevicePath[in] Optional parameter use to pick a specific child device to start.
- This - Protocol instance pointer.
- ControllerHandle - Handle of controller to test.
- RemainingDevicePath - Optional parameter use to pick a specific child device to start.
+ @retval EFI_SUCCES This driver supports the controller.
-Returns:
+ @retval EFI_ALREADY_STARTED This driver is already running on this device.
- EFI_SUCCES - This driver supports the controller.
- EFI_ALREADY_STARTED - This driver is already running on this device.
- EFI_UNSUPPORTED - This driver doesn't support the controller.
+ @retval EFI_UNSUPPORTED This driver doesn't support the controller.
---*/
+**/
+EFI_STATUS
+EFIAPI
+IScsiDriverBindingSupported (
+ IN EFI_DRIVER_BINDING_PROTOCOL * This,
+ IN EFI_HANDLE ControllerHandle,
+ IN EFI_DEVICE_PATH_PROTOCOL * RemainingDevicePath OPTIONAL
+ )
{
EFI_STATUS Status;
EFI_DEVICE_PATH_PROTOCOL *CurrentDevicePath;
@@ -100,6 +99,20 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Start to manage the controller.
+
+ @param This[in] Protocol instance pointer.
+
+ @param ControllerHandle[in] Handle of the controller.
+
+ @param RemainingDevicePath[in] Optional parameter use to pick a specific child device to start.
+
+ @retval EFI_SUCCES This driver supports this device.
+
+ @retval EFI_ALREADY_STARTED This driver is already running on this device.
+
+**/
EFI_STATUS
EFIAPI
IScsiDriverBindingStart (
@@ -107,24 +120,6 @@ IScsiDriverBindingStart ( IN EFI_HANDLE ControllerHandle,
IN EFI_DEVICE_PATH_PROTOCOL * RemainingDevicePath OPTIONAL
)
-/*++
-
-Routine Description:
-
- Start to manage the controller.
-
-Arguments:
-
- This - Protocol instance pointer.
- ControllerHandle - Handle of the controller.
- RemainingDevicePath - Optional parameter use to pick a specific child device to start.
-
-Returns:
-
- EFI_SUCCES - This driver supports this device.
- EFI_ALREADY_STARTED - This driver is already running on this device.
-
---*/
{
EFI_STATUS Status;
ISCSI_DRIVER_DATA *Private;
@@ -209,6 +204,20 @@ ON_ERROR: return Status;
}
+/**
+ Release the control of this controller and remove the IScsi functions.
+
+ @param This[in] Protocol instance pointer.
+
+ @param ControllerHandle[in] Handle of controller to stop.
+
+ @param NumberOfChildren[in] Not used.
+
+ @param ChildHandleBuffer[in] Not used.
+
+ @retval EFI_SUCCES This driver supports this device.
+
+**/
EFI_STATUS
EFIAPI
IScsiDriverBindingStop (
@@ -217,24 +226,6 @@ IScsiDriverBindingStop ( IN UINTN NumberOfChildren,
IN EFI_HANDLE *ChildHandleBuffer
)
-/*++
-
-Routine Description:
-
- Release the control of this controller and remove the iSCSI functions.
-
-Arguments:
-
- This - Protocol instance pointer.
- ControllerHandle - Handle of controller to stop.
- NumberOfChildren - Not used.
- ChildHandleBuffer - Not used.
-
-Returns:
-
- EFI_SUCCES - This driver supports this device.
-
---*/
{
EFI_HANDLE IScsiController;
EFI_STATUS Status;
@@ -315,27 +306,21 @@ Returns: return EFI_SUCCESS;
}
-EFI_STATUS
-EFIAPI
-EfiIScsiUnload (
- IN EFI_HANDLE ImageHandle
- )
-/*++
-
-Routine Description:
-
+/**
Unload the iSCSI driver.
-Arguments:
-
- ImageHandle - The handle of the driver image.
+ @param ImageHandle[in] The handle of the driver image.
-Returns:
+ @retval EFI_SUCCESS The driver is unloaded.
- EFI_SUCCESS - The driver is unloaded.
- EFI_DEVICE_ERROR - Some unexpected error happened.
+ @retval EFI_DEVICE_ERROR Some unexpected error happened.
---*/
+**/
+EFI_STATUS
+EFIAPI
+EfiIScsiUnload (
+ IN EFI_HANDLE ImageHandle
+ )
{
EFI_STATUS Status;
UINTN DeviceHandleCount;
@@ -389,29 +374,24 @@ Returns: return Status;
}
-EFI_STATUS
-EFIAPI
-IScsiDriverEntryPoint (
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
- )
-/*++
-
-Routine Description:
-
+/**
Initialize the global variables publish the driver binding protocol.
-Arguments:
+ @param ImageHandle[in] The handle of the driver image.
- ImageHandle - The handle of the driver image.
- SystemTable - The EFI system table.
+ @param SystemTable[in] The EFI system table.
-Returns:
+ @retval EFI_SUCCESS The protocols are installed.
- EFI_SUCCESS - The protocols are installed.
- EFI_DEVICE_ERROR - Some unexpected error happened.
+ @retval EFI_DEVICE_ERROR Some unexpected error happened.
---*/
+**/
+EFI_STATUS
+EFIAPI
+IScsiDriverEntryPoint (
+ IN EFI_HANDLE ImageHandle,
+ IN EFI_SYSTEM_TABLE *SystemTable
+ )
{
EFI_STATUS Status;
EFI_ISCSI_INITIATOR_NAME_PROTOCOL *IScsiInitiatorName;
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDriver.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDriver.h index b6a43243a7..a66fc151e9 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDriver.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiDriver.h @@ -1,4 +1,5 @@ -/*++
+/** @file
+ The header file of IScsiDriver.c
Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -14,8 +15,9 @@ Module Name: IScsiDriver.h
Abstract:
+ The header file of IScsiDriver.c
---*/
+**/
#ifndef _ISCSI_DRIVER_H_
#define _ISCSI_DRIVER_H_
@@ -55,6 +57,22 @@ typedef struct _ISCSI_PRIVATE_PROTOCOL { //
// EFI Driver Binding Protocol for iSCSI driver.
//
+/**
+ Test to see if IScsi driver supports the given controller.
+
+ @param This[in] Protocol instance pointer.
+
+ @param ControllerHandle[in] Handle of controller to test.
+
+ @param RemainingDevicePath[in] Optional parameter use to pick a specific child device to start.
+
+ @retval EFI_SUCCES This driver supports the controller.
+
+ @retval EFI_ALREADY_STARTED This driver is already running on this device.
+
+ @retval EFI_UNSUPPORTED This driver doesn't support the controller.
+
+**/
EFI_STATUS
EFIAPI
IScsiDriverBindingSupported (
@@ -63,6 +81,20 @@ IScsiDriverBindingSupported ( IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
);
+/**
+ Start to manage the controller.
+
+ @param This[in] Protocol instance pointer.
+
+ @param ControllerHandle[in] Handle of the controller.
+
+ @param RemainingDevicePath[in] Optional parameter use to pick a specific child device to start.
+
+ @retval EFI_SUCCES This driver supports this device.
+
+ @retval EFI_ALREADY_STARTED This driver is already running on this device.
+
+**/
EFI_STATUS
EFIAPI
IScsiDriverBindingStart (
@@ -71,6 +103,20 @@ IScsiDriverBindingStart ( IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
);
+/**
+ Release the control of this controller and remove the IScsi functions.
+
+ @param This[in] Protocol instance pointer.
+
+ @param ControllerHandle[in] Handle of controller to stop.
+
+ @param NumberOfChildren[in] Not used.
+
+ @param ChildHandleBuffer[in] Not used.
+
+ @retval EFI_SUCCES This driver supports this device.
+
+**/
EFI_STATUS
EFIAPI
IScsiDriverBindingStop (
@@ -81,8 +127,46 @@ IScsiDriverBindingStop ( );
//
-// EFI Component Name Protocol for iSCSI driver.
+// EFI Component Name Protocol for IScsi driver.
//
+/**
+ Retrieves a Unicode string that is the user readable name of the EFI Driver.
+
+ This function retrieves the user readable name of a driver in the form of a
+ Unicode string. If the driver specified by This has a user readable name in
+ the language specified by Language, then a pointer to the driver name is
+ returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
+ by This does not support the language specified by Language,
+ then EFI_UNSUPPORTED is returned.
+
+ @param This[in] A pointer to the EFI_COMPONENT_NAME_PROTOCOL
+ instance.
+
+ @param Language[in] A pointer to a three character ISO 639-2 language
+ identifier.
+ This is the language of the driver name that that
+ the caller is requesting, and it must match one of
+ the languages specified in SupportedLanguages.
+ The number of languages supported by a driver is up
+ to the driver writer.
+
+ @param DriverName[out] A pointer to the Unicode string to return.
+ This Unicode string is the name of the
+ driver specified by This in the language
+ specified by Language.
+
+ @retval EFI_SUCCESS The Unicode string for the Driver specified by
+ This and the language specified by Language was
+ returned in DriverName.
+
+ @retval EFI_INVALID_PARAMETER Language is NULL.
+
+ @retval EFI_INVALID_PARAMETER DriverName is NULL.
+
+ @retval EFI_UNSUPPORTED The driver specified by This does not support
+ the language specified by Language.
+
+**/
EFI_STATUS
EFIAPI
IScsiComponentNameGetDriverName (
@@ -91,6 +175,55 @@ IScsiComponentNameGetDriverName ( OUT CHAR16 **DriverName
);
+/**
+ Retrieves a Unicode string that is the user readable name of the controller
+ that is being managed by an EFI Driver.
+
+ @param This[in] A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
+
+ @param ControllerHandle[in] The handle of a controller that the driver specified by
+ This is managing. This handle specifies the controller
+ whose name is to be returned.
+
+ @param ChildHandle[in] The handle of the child controller to retrieve the name
+ of. This is an optional parameter that may be NULL. It
+ will be NULL for device drivers. It will also be NULL
+ for a bus drivers that wish to retrieve the name of the
+ bus controller. It will not be NULL for a bus driver
+ that wishes to retrieve the name of a child controller.
+
+ @param Language[in] A pointer to a three character ISO 639-2 language
+ identifier. This is the language of the controller name
+ that that the caller is requesting, and it must match one
+ of the languages specified in SupportedLanguages. The
+ number of languages supported by a driver is up to the
+ driver writer.
+
+ @param ControllerName[out] A pointer to the Unicode string to return. This Unicode
+ string is the name of the controller specified by
+ ControllerHandle and ChildHandle in the language
+ specified by Language from the point of view of the
+ driver specified by This.
+
+ @retval EFI_SUCCESS The Unicode string for the user readable name in the
+ language specified by Language for the driver
+ specified by This was returned in DriverName.
+
+ @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
+
+ @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid EFI_HANDLE.
+
+ @retval EFI_INVALID_PARAMETER Language is NULL.
+
+ @retval EFI_INVALID_PARAMETER ControllerName is NULL.
+
+ @retval EFI_UNSUPPORTED The driver specified by This is not currently managing
+ the controller specified by ControllerHandle and ChildHandle.
+
+ @retval EFI_UNSUPPORTED The driver specified by This does not support the
+ language specified by Language.
+
+**/
EFI_STATUS
EFIAPI
IScsiComponentNameGetControllerName (
@@ -102,8 +235,35 @@ IScsiComponentNameGetControllerName ( );
//
-// EFI iSCSI Initiator Name Protocol for iSCSI driver.
+// EFI IScsi Initiator Name Protocol for IScsi driver.
//
+/**
+ Retrieves the current set value of iSCSI Initiator Name.
+
+ @param This[in] Pointer to the EFI_ISCSI_INITIATOR_NAME_PROTOCOL instance.
+
+ @param BufferSize[in][out] Size of the buffer in bytes pointed to by Buffer / Actual
+ size of the variable data buffer.
+
+ @param Buffer[out] Pointer to the buffer for data to be read.
+
+ @retval EFI_SUCCESS Data was successfully retrieved into the provided
+ buffer and the BufferSize was sufficient to handle the
+ iSCSI initiator name.
+ @retval 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.
+
+ @retval EFI_INVALID_PARAMETER BufferSize is NULL. BufferSize and Buffer will not be
+ affected.
+
+ @retval EFI_INVALID_PARAMETER Buffer is NULL. BufferSize and Buffer will not be
+ affected.
+
+ @retval EFI_DEVICE_ERROR The iSCSI initiator name could not be retrieved due to
+ a hardware error.
+
+**/
EFI_STATUS
EFIAPI
IScsiGetInitiatorName (
@@ -112,6 +272,35 @@ IScsiGetInitiatorName ( OUT VOID *Buffer
);
+/**
+ Sets the iSCSI Initiator Name.
+
+ @param This[in] Pointer to the EFI_ISCSI_INITIATOR_NAME_PROTOCOL instance.
+
+ @param BufferSize[in][out] Size of the buffer in bytes pointed to by Buffer.
+
+ @param Buffer[out] Pointer to the buffer for data to be written.
+
+ @retval EFI_SUCCESS Data was successfully stored by the protocol.
+
+ @retval EFI_UNSUPPORTED Platform policies do not allow for data to be written.
+
+ @retval EFI_INVALID_PARAMETER BufferSize exceeds the maximum allowed limit.
+ BufferSize will be updated with the maximum size
+ required to complete the request.
+
+ @retval EFI_INVALID_PARAMETER Buffersize is NULL. BufferSize and Buffer will not be
+ affected.
+
+ @retval EFI_INVALID_PARAMETER Buffer is NULL. BufferSize and Buffer will not be affected.
+
+ @retval EFI_DEVICE_ERROR The data could not be stored due to a hardware error.
+
+ @retval EFI_OUT_OF_RESOURCES Not enough storage is available to hold the data.
+
+ @retval EFI_PROTOCOL_ERROR Input iSCSI initiator name does not adhere to RFC 3720.
+
+**/
EFI_STATUS
EFIAPI
IScsiSetInitiatorName (
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiExtScsiPassThru.c b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiExtScsiPassThru.c index 697424ad72..2e99efc032 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiExtScsiPassThru.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiExtScsiPassThru.c @@ -1,4 +1,5 @@ -/*++
+/** @file
+ The IScsi's EFI_EXT_SCSI_PASS_THRU_PROTOCOL driver
Copyright (c) 2004 - 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -14,11 +15,29 @@ Module Name: IScsiExtScsiPassThru.c
Abstract:
+ The IScsi's EFI_EXT_SCSI_PASS_THRU_PROTOCOL driver
---*/
+**/
#include "IScsiImpl.h"
+/**
+ This function sends out the SCSI command via iSCSI transport layer and returned
+ back the data received from the iSCSI target.
+
+ @param This[in] The EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
+
+ @param Target[in] The Target ID of device to send the SCSI Request Packet.
+
+ @param Lun[in] The LUN of the device to send the SCSI Request Packet.
+
+ @param Packet[in][out] The SCSI Request Packet to send to the device.
+
+ @param Event[in] The event used in non-blocking mode, it should be always NULL.
+
+ @retval EFI_STATUS
+
+**/
EFI_STATUS
EFIAPI
IScsiExtScsiPassThruFunction (
@@ -28,26 +47,6 @@ IScsiExtScsiPassThruFunction ( IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet,
IN EFI_EVENT Event OPTIONAL
)
-/*++
-
-Routine Description:
-
- This function sends out the SCSI command via iSCSI transport layer and returned
- back the data received from the iSCSI target.
-
-Arguments:
-
- This - The EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
- Target - The Target ID of device to send the SCSI Request Packet.
- Lun - The LUN of the device to send the SCSI Request Packet.
- Packet - The SCSI Request Packet to send to the device.
- Event - The event used in non-blocking mode, it should be always NULL.
-
-Returns:
-
- EFI_STATUS
-
---*/
{
if (Target[0] != 0) {
return EFI_INVALID_PARAMETER;
@@ -60,39 +59,36 @@ Returns: return IScsiExecuteScsiCommand (This, Target, Lun, Packet);
}
-EFI_STATUS
-EFIAPI
-IScsiExtScsiPassThruGetNextTargetLun (
- IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This,
- IN OUT UINT8 **Target,
- IN OUT UINT64 *Lun
- )
-/*++
+/**
+ Retrieve the list of legal Target IDs for SCSI devices on a SCSI channel.
-Routine Description:
+ @param This[in] The EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
- Retrieve the list of legal Target IDs for SCSI devices on a SCSI channel.
+ @param Target[in][out] On input, a pointer to the Target ID of a SCSI device present on the
+ SCSI channel. On output, a pointer to the Target ID of the next SCSI
+ device present on a SCSI channel. An input value of 0xFFFFFFFF retrieves
+ the Target ID of the first SCSI device present on a SCSI channel.
-Arguments:
+ @param Lun[in][out] On input, a pointer to the LUN of a SCSI device present on the SCSI
+ channel. On output, a pointer to the LUN of the next SCSI device
+ present on a SCSI channel.
- This - The EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance..
- Target - On input, a pointer to the Target ID of a SCSI device present on the
- SCSI channel. On output, a pointer to the Target ID of the next SCSI
- device present on a SCSI channel. An input value of 0xFFFFFFFF
- retrieves the Target ID of the first SCSI device present on a SCSI channel.
- Lun - On input, a pointer to the LUN of a SCSI device present on the SCSI
- channel. On output, a pointer to the LUN of the next SCSI device present on
- a SCSI channel.
+ @retval EFI_SUCCESS The Target ID and Lun of the next SCSI device
+ on the SCSI channel was returned in Target and Lun.
-Returns:
+ @retval EFI_NOT_FOUND There are no more SCSI devices on this SCSI channel.
- EFI_SUCCESS - The Target ID and Lun of the next SCSI device
- on the SCSI channel was returned in Target and Lun.
- EFI_NOT_FOUND - There are no more SCSI devices on this SCSI channel.
- EFI_INVALID_PARAMETER - Target is not 0xFFFFFFFF,and Target and Lun were not
- returned on a previous call to GetNextDevice().
+ @retval EFI_INVALID_PARAMETER Target is not 0xFFFFFFFF,and Target and Lun were not
+ returned on a previous call to GetNextDevice().
---*/
+**/
+EFI_STATUS
+EFIAPI
+IScsiExtScsiPassThruGetNextTargetLun (
+ IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This,
+ IN OUT UINT8 **Target,
+ IN OUT UINT64 *Lun
+ )
{
ISCSI_DRIVER_DATA *Private;
ISCSI_SESSION_CONFIG_NVDATA *ConfigNvData;
@@ -119,6 +115,38 @@ Returns: return EFI_INVALID_PARAMETER;
}
+/**
+ Allocate and build a device path node for a SCSI device on a SCSI channel.
+
+ @param This[in] Protocol instance pointer.
+
+ @param Target[in] The Target ID of the SCSI device for which
+ a device path node is to be allocated and built.
+
+ @param Lun[in] The LUN of the SCSI device for which a device
+ path node is to be allocated and built.
+
+ @param DevicePath[in][out] A pointer to a single device path node that
+ describes the SCSI device specified by
+ Target and Lun. This function is responsible
+ for allocating the buffer DevicePath with the boot
+ service AllocatePool(). It is the caller's
+ responsibility to free DevicePath when the caller
+ is finished with DevicePath.
+
+ @retval EFI_SUCCESS The device path node that describes the SCSI device
+ specified by Target and Lun was allocated and
+ returned in DevicePath.
+
+ @retval EFI_NOT_FOUND The SCSI devices specified by Target and Lun does
+ not exist on the SCSI channel.
+
+ @retval EFI_INVALID_PARAMETER DevicePath is NULL.
+
+ @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate
+ DevicePath.
+
+**/
EFI_STATUS
EFIAPI
IScsiExtScsiPassThruBuildDevicePath (
@@ -127,39 +155,6 @@ IScsiExtScsiPassThruBuildDevicePath ( IN UINT64 Lun,
IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath
)
-/*++
-
-Routine Description:
-
- Allocate and build a device path node for a SCSI device on a SCSI channel.
-
-Arguments:
-
- This - Protocol instance pointer.
- Target - The Target ID of the SCSI device for which
- a device path node is to be allocated and built.
- Lun - The LUN of the SCSI device for which a device
- path node is to be allocated and built.
- DevicePath - A pointer to a single device path node that
- describes the SCSI device specified by
- Target and Lun. This function is responsible
- for allocating the buffer DevicePath with the boot
- service AllocatePool(). It is the caller's
- responsibility to free DevicePath when the caller
- is finished with DevicePath.
-
-Returns:
-
- EFI_SUCCESS - The device path node that describes the SCSI device
- specified by Target and Lun was allocated and
- returned in DevicePath.
- EFI_NOT_FOUND - The SCSI devices specified by Target and Lun does
- not exist on the SCSI channel.
- EFI_INVALID_PARAMETER - DevicePath is NULL.
- EFI_OUT_OF_RESOURCES - There are not enough resources to allocate
- DevicePath.
-
---*/
{
ISCSI_DRIVER_DATA *Private;
ISCSI_SESSION *Session;
@@ -223,6 +218,33 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Translate a device path node to a Target ID and LUN.
+
+ @param This[in] Protocol instance pointer.
+
+ @param DevicePath[in] A pointer to the device path node that
+ describes a SCSI device on the SCSI channel.
+
+ @param Target[out] A pointer to the Target ID of a SCSI device
+ on the SCSI channel.
+
+ @param Lun[out] A pointer to the LUN of a SCSI device on
+ the SCSI channel.
+
+ @retval EFI_SUCCESS DevicePath was successfully translated to a
+ Target ID and LUN, and they were returned
+ in Target and Lun.
+
+ @retval EFI_INVALID_PARAMETER DevicePath/Target/Lun is NULL.
+
+ @retval EFI_UNSUPPORTED This driver does not support the device path
+ node type in DevicePath.
+
+ @retval EFI_NOT_FOUND A valid translation from DevicePath to a
+ Target ID and LUN does not exist.
+
+**/
EFI_STATUS
EFIAPI
IScsiExtScsiPassThruGetTargetLun (
@@ -231,33 +253,6 @@ IScsiExtScsiPassThruGetTargetLun ( OUT UINT8 **Target,
OUT UINT64 *Lun
)
-/*++
-
-Routine Description:
-
- Translate a device path node to a Target ID and LUN.
-
-Arguments:
-
- This - Protocol instance pointer.
- DevicePath - A pointer to the device path node that
- describes a SCSI device on the SCSI channel.
- Target - A pointer to the Target ID of a SCSI device
- on the SCSI channel.
- Lun - A pointer to the LUN of a SCSI device on
- the SCSI channel.
-Returns:
-
- EFI_SUCCESS - DevicePath was successfully translated to a
- Target ID and LUN, and they were returned
- in Target and Lun.
- EFI_INVALID_PARAMETER - DevicePath/Target/Lun is NULL.
- EFI_UNSUPPORTED - This driver does not support the device path
- node type in DevicePath.
- EFI_NOT_FOUND - A valid translation from DevicePath to a
- Target ID and LUN does not exist.
-
---*/
{
ISCSI_DRIVER_DATA *Private;
ISCSI_SESSION_CONFIG_NVDATA *ConfigNvData;
@@ -287,31 +282,36 @@ Returns: return EFI_SUCCESS;
}
+/**
+ Resets a SCSI channel.This operation resets all the SCSI devices connected to
+ the SCSI channel.
+
+ @param This[in] Protocol instance pointer.
+
+ @retval EFI_UNSUPPORTED It's not supported.
+
+**/
EFI_STATUS
EFIAPI
IScsiExtScsiPassThruResetChannel (
IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This
)
-/*++
-
-Routine Description:
-
- Resets a SCSI channel.This operation resets all the SCSI devices connected to
- the SCSI channel.
+{
+ return EFI_UNSUPPORTED;
+}
-Arguments:
+/**
+ Resets a SCSI device that is connected to a SCSI channel.
- This - Protocol instance pointer.
+ @param This[in] Protocol instance pointer.
-Returns:
+ @param Target[in] The Target ID of the SCSI device to reset.
- EFI_UNSUPPORTED - It's not supported.
+ @param Lun[in] The LUN of the SCSI device to reset.
---*/
-{
- return EFI_UNSUPPORTED;
-}
+ @retval EFI_UNSUPPORTED It's not supported.
+**/
EFI_STATUS
EFIAPI
IScsiExtScsiPassThruResetTargetLun (
@@ -319,61 +319,37 @@ IScsiExtScsiPassThruResetTargetLun ( IN UINT8 *Target,
IN UINT64 Lun
)
-/*++
+{
+ return EFI_UNSUPPORTED;
+}
-Routine Description:
+/**
+ Retrieve the list of legal Target IDs for SCSI devices on a SCSI channel.
- Resets a SCSI device that is connected to a SCSI channel.
+ @param This[in] Protocol instance pointer.
-Arguments:
+ @param Target[in] On input, a pointer to the Target ID of a SCSI
+ device present on the SCSI channel. On output,
+ a pointer to the Target ID of the next SCSI device
+ present on a SCSI channel. An input value of
+ 0xFFFFFFFF retrieves the Target ID of the first
+ SCSI device present on a SCSI channel.
- This - Protocol instance pointer.
- Target - The Target ID of the SCSI device to reset.
- Lun - The LUN of the SCSI device to reset.
-
-Returns:
+ @retval EFI_SUCCESS The Target ID and Lun of the next SCSI device
+ on the SCSI channel was returned in Target and Lun.
- EFI_UNSUPPORTED - It's not supported.
+ @retval EFI_NOT_FOUND There are no more SCSI devices on this SCSI channel.
---*/
-{
- return EFI_UNSUPPORTED;
-}
+ @retval EFI_INVALID_PARAMETER Target is not 0xFFFFFFFF,and Target and Lun were not
+ returned on a previous call to GetNextDevice().
+**/
EFI_STATUS
EFIAPI
IScsiExtScsiPassThruGetNextTarget (
IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *This,
IN OUT UINT8 **Target
)
-/*++
-
-Routine Description:
-
- Retrieve the list of legal Target IDs for SCSI devices on a SCSI channel.
-
-Arguments:
- This - Protocol instance pointer.
- Target - On input, a pointer to the Target ID of a SCSI
- device present on the SCSI channel. On output,
- a pointer to the Target ID of the next SCSI device
- present on a SCSI channel. An input value of
- 0xFFFFFFFF retrieves the Target ID of the first
- SCSI device present on a SCSI channel.
- Lun - On input, a pointer to the LUN of a SCSI device
- present on the SCSI channel. On output, a pointer
- to the LUN of the next SCSI device present on
- a SCSI channel.
-
-Returns:
-
- EFI_SUCCESS - The Target ID and Lun of the next SCSI device
- on the SCSI channel was returned in Target and Lun.
- EFI_NOT_FOUND - There are no more SCSI devices on this SCSI channel.
- EFI_INVALID_PARAMETER - Target is not 0xFFFFFFFF,and Target and Lun were not
- returned on a previous call to GetNextDevice().
-
---*/
{
UINT8 TargetId[TARGET_MAX_BYTES];
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiExtScsiPassThru.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiExtScsiPassThru.h index 26f59a2f9e..1f3c84f096 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiExtScsiPassThru.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiExtScsiPassThru.h @@ -1,4 +1,5 @@ -/*++
+/** @file
+ The header file of IScsiExtScsiPassThru.c
Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -14,8 +15,9 @@ Module Name: IScsiExtScsiPassThru.h
Abstract:
+ The header file of IScsiExtScsiPassThru.c
---*/
+**/
#ifndef _ISCSI_EXT_SCSI_PASS_THRU_H_
#define _ISCSI_EXT_SCSI_PASS_THRU_H_
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiIbft.c b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiIbft.c index cd4be8b3c9..3c8dac371c 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiIbft.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiIbft.c @@ -1,6 +1,7 @@ -/*++
+/** @file
+ Implementation for iSCSI Boot Firmware Table publication.
-Copyright (c) 2004 - 2007, Intel Corporation
+Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -17,30 +18,23 @@ Abstract: Implementation for iSCSI Boot Firmware Table publication.
---*/
+**/
#include "IScsiImpl.h"
+/**
+ Initialize the header of the iSCSI Boot Firmware Table.
+
+ @param Header[in] The header of the iSCSI Boot Firmware Table.
+
+ @retval None.
+
+**/
STATIC
VOID
IScsiInitIbfTableHeader (
IN EFI_ACPI_ISCSI_BOOT_FIRMWARE_TABLE_HEADER *Header
)
-/*++
-
-Routine Description:
-
- Initialize the header of the iSCSI Boot Firmware Table.
-
-Arguments:
-
- Header - The header of the iSCSI Boot Firmware Table.
-
-Returns:
-
- None.
-
---*/
{
ZeroMem (Header, sizeof (EFI_ACPI_ISCSI_BOOT_FIRMWARE_TABLE_HEADER));
@@ -56,29 +50,23 @@ Returns: Header->OemId[4] = 'L';
}
+/**
+ Initialize the control section of the iSCSI Boot Firmware Table.
+
+ @param Table[in] The ACPI table.
+
+ @param HandleCount[in] The number of the handles associated with iSCSI sessions, it's
+ equal to the number of iSCSI sessions.
+
+ @retval None.
+
+**/
STATIC
VOID
IScsiInitControlSection (
IN EFI_ACPI_ISCSI_BOOT_FIRMWARE_TABLE_HEADER *Table,
IN UINTN HandleCount
)
-/*++
-
-Routine Description:
-
- Initialize the control section of the iSCSI Boot Firmware Table.
-
-Arguments:
-
- Table - The ACPI table.
- HandleCount - The number of the handles associated with iSCSI sessions, it's
- equal to the number of iSCSI sessions.
-
-Returns:
-
- None.
-
---*/
{
EFI_ACPI_ISCSI_BOOT_FIRMWARE_TABLE_CONTROL_STRUCTURE *Control;
UINTN NumOffset;
@@ -105,6 +93,19 @@ Returns: }
}
+/**
+ Add one item into the heap.
+
+ @param Heap[in][out] On input, the current address of the heap; On output, the address of
+ the heap after the item is added.
+
+ @param Data[in] The data to add into the heap.
+
+ @param Len[in] Length of the Data in byte.
+
+ @retval None.
+
+**/
STATIC
VOID
IScsiAddHeapItem (
@@ -112,24 +113,6 @@ IScsiAddHeapItem ( IN VOID *Data,
IN UINTN Len
)
-/*++
-
-Routine Description:
-
- Add one item into the heap.
-
-Arguments:
-
- Heap - On input, the current address of the heap; On output, the address of
- the heap after the item is added.
- Data - The data to add into the heap.
- Len - Length of the Data in byte.
-
-Returns:
-
- None.
-
---*/
{
//
// Add one byte for the NULL delimiter.
@@ -140,6 +123,18 @@ Returns: *(*Heap + Len) = 0;
}
+/**
+ Fill the Initiator section of the iSCSI Boot Firmware Table.
+
+ @param Table[in] The ACPI table.
+
+ @param Heap[in][out] The heap.
+
+ @param Handle[in] The handle associated with the iSCSI session.
+
+ @retval None.
+
+**/
STATIC
VOID
IScsiFillInitiatorSection (
@@ -147,23 +142,6 @@ IScsiFillInitiatorSection ( IN OUT UINT8 **Heap,
IN EFI_HANDLE Handle
)
-/*++
-
-Routine Description:
-
- Fill the Initiator section of the iSCSI Boot Firmware Table.
-
-Arguments:
-
- Table - The ACPI table.
- Heap - The heap.
- Handle - The handle associated with the iSCSI session.
-
-Returns:
-
- None.
-
---*/
{
EFI_ACPI_ISCSI_BOOT_FIRMWARE_TABLE_CONTROL_STRUCTURE *Control;
EFI_ACPI_ISCSI_BOOT_FIRMWARE_TABLE_INITIATOR_STRUCTURE *Initiator;
@@ -209,28 +187,22 @@ Returns: Initiator->IScsiNameOffset = (UINT16) ((UINTN) *Heap - (UINTN) Table);
}
+/**
+ Map the v4 IP address into v6 IP address.
+
+ @param V4 The v4 IP address.
+
+ @param V6 The v6 IP address.
+
+ @retval None.
+
+**/
STATIC
VOID
IScsiMapV4ToV6Addr (
IN EFI_IPv4_ADDRESS *V4,
OUT EFI_IPv6_ADDRESS *V6
)
-/*++
-
-Routine Description:
-
- Map the v4 IP address into v6 IP address.
-
-Arguments:
-
- V4 - The v4 IP address.
- V6 - The v6 IP address.
-
-Returns:
-
- None.
-
---*/
{
UINTN Index;
@@ -244,27 +216,20 @@ Returns: }
}
-STATIC
-UINT16
-IScsiGetNICPciLocation (
- IN EFI_HANDLE Controller
- )
-/*++
-
-Routine Description:
-
+/**
Get the NIC's PCI location and return it accroding to the composited
format defined in iSCSI Boot Firmware Table.
-
-Arguments:
- Controller - The handle of the controller.
+ @param Controller[in] The handle of the controller.
-Returns:
+ @retval UINT16 The composited representation of the NIC PCI location.
- UINT16 - The composited representation of the NIC PCI location.
-
---*/
+**/
+STATIC
+UINT16
+IScsiGetNICPciLocation (
+ IN EFI_HANDLE Controller
+ )
{
EFI_STATUS Status;
EFI_DEVICE_PATH_PROTOCOL *DevicePath;
@@ -306,26 +271,19 @@ Returns: return (UINT16) ((Bus << 8) | (Device << 3) | Function);
}
+/**
+ Get the MAC address of the controller.
+
+ @param Controller[in] The handle of the controller.
+
+ @retval EFI_MAC_ADDRESS * The mac address.
+
+**/
STATIC
EFI_MAC_ADDRESS *
IScsiGetMacAddress (
IN EFI_HANDLE Controller
)
-/*++
-
-Routine Description:
-
- Get the MAC address of the controller.
-
-Arguments:
-
- Controller - The handle of the controller.
-
-Returns:
-
- EFI_MAC_ADDRESS * - The mac address.
-
---*/
{
EFI_STATUS Status;
EFI_SIMPLE_NETWORK_PROTOCOL *Snp;
@@ -340,6 +298,20 @@ Returns: return &Snp->Mode->PermanentAddress;
}
+/**
+ Fill the NIC and target sections in iSCSI Boot Firmware Table.
+
+ @param Table[in] The buffer of the ACPI table.
+
+ @param Heap[in][out] The heap buffer used to store the variable length parameters such as iSCSI name.
+
+ @param HandleCount[in] The number of handles having iSCSI private protocol installed.
+
+ @param Handles[in] The handle buffer.
+
+ @retval None.
+
+**/
STATIC
VOID
IScsiFillNICAndTargetSections (
@@ -348,24 +320,6 @@ IScsiFillNICAndTargetSections ( IN UINTN HandleCount,
IN EFI_HANDLE *Handles
)
-/*++
-
-Routine Description:
-
- Fill the NIC and target sections in iSCSI Boot Firmware Table.
-
-Arguments:
-
- Table - The buffer of the ACPI table.
- Heap - The heap buffer used to store the variable length parameters such as iSCSI name.
- HandleCount - The number of handles having iSCSI private protocol installed.
- Handles - The handle buffer.
-
-Returns:
-
- None.
-
---*/
{
EFI_ACPI_ISCSI_BOOT_FIRMWARE_TABLE_CONTROL_STRUCTURE *Control;
EFI_ACPI_ISCSI_BOOT_FIRMWARE_TABLE_NIC_STRUCTURE *Nic;
@@ -520,26 +474,19 @@ Returns: }
}
-VOID
-IScsiPublishIbft (
- IN VOID
- )
-/*++
-
-Routine Description:
-
+/**
Publish and remove the iSCSI Boot Firmware Table according to the iSCSI
session status.
-Arguments:
-
- None.
+ @param None.
-Returns:
+ @retval None.
- None.
-
---*/
+**/
+VOID
+IScsiPublishIbft (
+ IN VOID
+ )
{
EFI_STATUS Status;
UINTN TableHandle;
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiIbft.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiIbft.h index 40097c944c..b426b064a7 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiIbft.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiIbft.h @@ -1,4 +1,5 @@ -/*++
+/** @file
+ Some extra definitions for iBFT
Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -17,7 +18,7 @@ Abstract: Some extra definitions for iBFT.
---*/
+**/
#ifndef _ISCSI_IBFT_H_
#define _ISCSI_IBFT_H_
@@ -32,6 +33,15 @@ Abstract: #define IBFT_ROUNDUP(size) NET_ROUNDUP ((size), EFI_ACPI_ISCSI_BOOT_FIRMWARE_TABLE_STRUCTURE_ALIGNMENT)
+/**
+ Publish and remove the iSCSI Boot Firmware Table according to the iSCSI
+ session status.
+
+ @param None.
+
+ @retval None.
+
+**/
VOID
IScsiPublishIbft (
IN VOID
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiImpl.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiImpl.h index 1eb4b4b91b..743857cfef 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiImpl.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiImpl.h @@ -1,6 +1,7 @@ -/*++
+/** @file
+ The header file of IScsiImpl.c
-Copyright (c) 2004 - 2007, Intel Corporation
+Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -14,8 +15,9 @@ Module Name: IScsiImpl.h
Abstract:
+ The header file of IScsiImpl.c
---*/
+**/
#ifndef _ISCSI_IMPL_H_
#define _ISCSI_IMPL_H_
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiInitiatorName.c b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiInitiatorName.c index f93594fdcd..3a8bd3a2ff 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiInitiatorName.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiInitiatorName.c @@ -1,6 +1,7 @@ -/*++
+/** @file
+ Implementation for EFI iSCSI Initiator Name Protocol.
-Copyright (c) 2004 - 2007, Intel Corporation
+Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -17,7 +18,7 @@ Abstract: Implementation for EFI iSCSI Initiator Name Protocol.
---*/
+**/
#include "IScsiImpl.h"
@@ -26,6 +27,33 @@ EFI_ISCSI_INITIATOR_NAME_PROTOCOL gIScsiInitiatorName = { IScsiSetInitiatorName
};
+/**
+ Retrieves the current set value of iSCSI Initiator Name.
+
+ @param This[in] Pointer to the EFI_ISCSI_INITIATOR_NAME_PROTOCOL instance.
+
+ @param BufferSize[in][out] Size of the buffer in bytes pointed to by Buffer / Actual
+ size of the variable data buffer.
+
+ @param Buffer[out] Pointer to the buffer for data to be read.
+
+ @retval EFI_SUCCESS Data was successfully retrieved into the provided
+ buffer and the BufferSize was sufficient to handle the
+ iSCSI initiator name.
+ @retval 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.
+
+ @retval EFI_INVALID_PARAMETER BufferSize is NULL. BufferSize and Buffer will not be
+ affected.
+
+ @retval EFI_INVALID_PARAMETER Buffer is NULL. BufferSize and Buffer will not be
+ affected.
+
+ @retval EFI_DEVICE_ERROR The iSCSI initiator name could not be retrieved due to
+ a hardware error.
+
+**/
EFI_STATUS
EFIAPI
IScsiGetInitiatorName (
@@ -33,35 +61,6 @@ IScsiGetInitiatorName ( IN OUT UINTN *BufferSize,
OUT VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Retrieves the current set value of iSCSI Initiator Name.
-
-Arguments:
-
- 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.
-
-Returns:
-
- 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.
-
---*/
{
EFI_STATUS Status;
@@ -80,40 +79,42 @@ Returns: return Status;
}
-EFI_STATUS
-EFIAPI
-IScsiSetInitiatorName (
- IN EFI_ISCSI_INITIATOR_NAME_PROTOCOL *This,
- IN OUT UINTN *BufferSize,
- OUT VOID *Buffer
- )
-/*++
+/**
+ Sets the iSCSI Initiator Name.
+
+ @param This[in] Pointer to the EFI_ISCSI_INITIATOR_NAME_PROTOCOL instance.
+
+ @param BufferSize[in][out] Size of the buffer in bytes pointed to by Buffer.
+
+ @param Buffer[out] Pointer to the buffer for data to be written.
+
+ @retval EFI_SUCCESS Data was successfully stored by the protocol.
-Routine Description:
+ @retval EFI_UNSUPPORTED Platform policies do not allow for data to be written.
- Sets the iSSI Initiator Name.
+ @retval EFI_INVALID_PARAMETER BufferSize exceeds the maximum allowed limit.
+ BufferSize will be updated with the maximum size
+ required to complete the request.
-Arguments:
+ @retval EFI_INVALID_PARAMETER Buffersize is NULL. BufferSize and Buffer will not be
+ affected.
- 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.
+ @retval EFI_INVALID_PARAMETER Buffer is NULL. BufferSize and Buffer will not be affected.
-Returns:
+ @retval EFI_DEVICE_ERROR The data could not be stored due to a hardware error.
- 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
+ @retval EFI_OUT_OF_RESOURCES Not enough storage is available to hold the data.
---*/
+ @retval EFI_PROTOCOL_ERROR Input iSCSI initiator name does not adhere to RFC 3720.
+
+**/
+EFI_STATUS
+EFIAPI
+IScsiSetInitiatorName (
+ IN EFI_ISCSI_INITIATOR_NAME_PROTOCOL *This,
+ IN OUT UINTN *BufferSize,
+ OUT VOID *Buffer
+ )
{
EFI_STATUS Status;
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiMisc.c b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiMisc.c index 985f02e940..1699bfb709 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiMisc.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiMisc.c @@ -1,6 +1,7 @@ -/*++
+/** @file
+ Miscellaneous routines for IScsi driver.
-Copyright (c) 2004 - 2007, Intel Corporation
+Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -15,35 +16,33 @@ Module Name: Abstract:
- Miscellaneous routines for iSCSI driver.
+ Miscellaneous routines for IScsi driver.
---*/
+**/
#include "IScsiImpl.h"
STATIC CONST CHAR8 IScsiHexString[] = "0123456789ABCDEFabcdef";
+/**
+ Determines if a Unicode character is a hexadecimal digit.
+ The test is case insensitive.
+
+ @param Digit[out] Pointer to byte that receives the value of the hex character.
+
+ @param Char[in] Unicode character to test.
+
+ @retval TRUE If the character is a hexadecimal digit.
+
+ @retval FALSE Otherwise.
+
+**/
static
BOOLEAN
IsHexDigit (
OUT UINT8 *Digit,
IN CHAR16 Char
)
-/*++
-
- Routine Description:
- Determines if a Unicode character is a hexadecimal digit.
- The test is case insensitive.
-
- Arguments:
- Digit - Pointer to byte that receives the value of the hex character.
- Char - Unicode character to test.
-
- Returns:
- TRUE - If the character is a hexadecimal digit.
- FALSE - Otherwise.
-
---*/
{
if ((Char >= L'0') && (Char <= L'9')) {
*Digit = (UINT8) (Char - L'0');
@@ -63,27 +62,23 @@ IsHexDigit ( return FALSE;
}
+/**
+ Removes (trims) specified leading and trailing characters from a string.
+
+ @param str[in][out] Pointer to the null-terminated string to be trimmed. On return,
+ str will hold the trimmed string.
+
+ @param CharC[in] Character will be trimmed from str.
+
+ @retval NONE.
+
+**/
static
VOID
StrTrim (
IN OUT CHAR16 *str,
IN CHAR16 CharC
)
-/*++
-
-Routine Description:
-
- Removes (trims) specified leading and trailing characters from a string.
-
-Arguments:
-
- str - Pointer to the null-terminated string to be trimmed. On return,
- str will hold the trimmed string.
- CharC - Character will be trimmed from str.
-
-Returns:
-
---*/
{
CHAR16 *p1;
CHAR16 *p2;
@@ -123,25 +118,18 @@ Returns: }
}
-UINT8
-IScsiGetSubnetMaskPrefixLength (
- IN EFI_IPv4_ADDRESS *SubnetMask
- )
-/*++
-
-Routine Description:
-
+/**
Calculate the prefix length of the IPv4 subnet mask.
-Arguments:
+ @param SubnetMask[in] The IPv4 subnet mask.
- SubnetMask - The IPv4 subnet mask.
+ @retval The prefix length of the subnet mask.
-Returns:
-
- The prefix length of the subnet mask.
-
---*/
+**/
+UINT8
+IScsiGetSubnetMaskPrefixLength (
+ IN EFI_IPv4_ADDRESS *SubnetMask
+ )
{
UINT8 Len;
UINT32 ReverseMask;
@@ -170,28 +158,23 @@ Returns: return (UINT8) (32 - Len);
}
-EFI_STATUS
-IScsiAsciiStrToLun (
- IN CHAR8 *Str,
- OUT UINT8 *Lun
- )
-/*++
-
-Routine Description:
-
+/**
Convert the hexadecimal encoded LUN string into the 64-bit LUN.
-Arguments:
+ @param Str[in] The hexadecimal encoded LUN string.
- Str - The hexadecimal encoded LUN string.
- Lun - Storage to return the 64-bit LUN.
+ @param Lun[out] Storage to return the 64-bit LUN.
-Returns:
+ @retval EFI_SUCCESS The 64-bit LUN is stored in Lun.
- EFI_SUCCESS - The 64-bit LUN is stored in Lun.
- EFI_INVALID_PARAMETER - The string is malformatted.
+ @retval EFI_INVALID_PARAMETER The string is malformatted.
---*/
+**/
+EFI_STATUS
+IScsiAsciiStrToLun (
+ IN CHAR8 *Str,
+ OUT UINT8 *Lun
+ )
{
UINT32 Index;
CHAR8 *LunUnitStr[4];
@@ -245,27 +228,21 @@ Returns: return EFI_SUCCESS;
}
-VOID
-IScsiLunToUnicodeStr (
- IN UINT8 *Lun,
- OUT CHAR16 *Str
- )
-/*++
-
-Routine Description:
-
+/**
Convert the 64-bit LUN into the hexadecimal encoded LUN string.
-Arguments:
-
- Lun - The 64-bit LUN.
- Str - The storage to return the hexadecimal encoded LUN string.
+ @param Lun[in] The 64-bit LUN.
-Returns:
+ @param Str[out] The storage to return the hexadecimal encoded LUN string.
- None.
+ @retval None.
---*/
+**/
+VOID
+IScsiLunToUnicodeStr (
+ IN UINT8 *Lun,
+ OUT CHAR16 *Str
+ )
{
UINTN Index;
CHAR16 *TempStr;
@@ -301,27 +278,21 @@ Returns: }
}
-CHAR16 *
-IScsiAsciiStrToUnicodeStr (
- IN CHAR8 *Source,
- OUT CHAR16 *Destination
- )
-/*++
-
-Routine Description:
-
+/**
Convert the ASCII string into a UNICODE string.
-Arguments:
+ @param Source[out] The ASCII string.
- Source - The ASCII string.
- Destination - The storage to return the UNICODE string.
+ @param Destination[out] The storage to return the UNICODE string.
-Returns:
+ @retval CHAR16 * Pointer to the UNICODE string.
- Pointer to the UNICODE string.
-
---*/
+**/
+CHAR16 *
+IScsiAsciiStrToUnicodeStr (
+ IN CHAR8 *Source,
+ OUT CHAR16 *Destination
+ )
{
ASSERT (Destination != NULL);
ASSERT (Source != NULL);
@@ -335,27 +306,21 @@ Returns: return Destination;
}
-CHAR8 *
-IScsiUnicodeStrToAsciiStr (
- IN CHAR16 *Source,
- OUT CHAR8 *Destination
- )
-/*++
-
-Routine Description:
-
+/**
Convert the UNICODE string into an ASCII string.
-Arguments:
+ @param Source[in] The UNICODE string.
- Source - The UNICODE string.
- Destination - The storage to return the ASCII string.
+ @param Destination[out] The storage to return the ASCII string.
-Returns:
+ @retval CHAR8 * Pointer to the ASCII string.
- Pointer to the ASCII string.
-
---*/
+**/
+CHAR8 *
+IScsiUnicodeStrToAsciiStr (
+ IN CHAR16 *Source,
+ OUT CHAR8 *Destination
+ )
{
ASSERT (Destination != NULL);
ASSERT (Source != NULL);
@@ -374,28 +339,23 @@ Returns: return Destination;
}
-EFI_STATUS
-IScsiAsciiStrToIp (
- IN CHAR8 *Str,
- OUT EFI_IPv4_ADDRESS *Ip
- )
-/*++
-
-Routine Description:
-
+/**
Convert the decimal dotted IPv4 address into the binary IPv4 address.
-Arguments:
+ @param Str[in] The UNICODE string.
- Str - The UNICODE string.
- Ip - The storage to return the ASCII string.
+ @param Ip[out] The storage to return the ASCII string.
-Returns:
+ @retval EFI_SUCCESS The binary IP address is returned in Ip.
- EFI_SUCCESS - The binary IP address is returned in Ip.
- EFI_INVALID_PARAMETER - The IP string is malformatted.
+ @retval EFI_INVALID_PARAMETER The IP string is malformatted.
---*/
+**/
+EFI_STATUS
+IScsiAsciiStrToIp (
+ IN CHAR8 *Str,
+ OUT EFI_IPv4_ADDRESS *Ip
+ )
{
UINTN Index;
UINTN Number;
@@ -445,29 +405,24 @@ Returns: return EFI_SUCCESS;
}
-VOID
-IScsiMacAddrToStr (
- IN EFI_MAC_ADDRESS *Mac,
- IN UINT32 Len,
- OUT CHAR16 *Str
- )
-/*++
-
-Routine Description:
-
+/**
Convert the mac address into a hexadecimal encoded "-" seperated string.
-Arguments:
+ @param Mac[in] The mac address.
- Mac - The mac address.
- Len - Length in bytes of the mac address.
- Str - The storage to return the mac string.
+ @param Len[in] Length in bytes of the mac address.
-Returns:
+ @param Str[out] The storage to return the mac string.
- None.
+ @retval None.
---*/
+**/
+VOID
+IScsiMacAddrToStr (
+ IN EFI_MAC_ADDRESS *Mac,
+ IN UINT32 Len,
+ OUT CHAR16 *Str
+ )
{
UINT32 Index;
@@ -480,33 +435,30 @@ Returns: Str[3 * Index - 1] = L'\0';
}
-EFI_STATUS
-IScsiBinToHex (
- IN UINT8 *BinBuffer,
- IN UINT32 BinLength,
- IN OUT CHAR8 *HexStr,
- IN OUT UINT32 *HexLength
- )
-/*++
+/**
+ Convert the binary encoded buffer into a hexadecimal encoded string.
-Routine Description:
+ @param BinBuffer[in] The buffer containing the binary data.
- Convert the binary encoded buffer into a hexadecimal encoded string.
+ @param BinLength[in] Length of the binary buffer.
-Arguments:
+ @param HexStr[in][out] Pointer to the string.
- BinBuffer - The buffer containing the binary data.
- BinLength - Length of the binary buffer.
- HexStr - Pointer to the string.
- HexLength - The length of the string.
+ @param HexLength[in][out] The length of the string.
-Returns:
+ @retval EFI_SUCCESS The binary data is converted to the hexadecimal string
+ and the length of the string is updated.
- EFI_SUCCESS - The binary data is converted to the hexadecimal string
- and the length of the string is updated.
- EFI_BUFFER_TOO_SMALL - The string is too small.
+ @retval EFI_BUFFER_TOO_SMALL The string is too small.
---*/
+**/
+EFI_STATUS
+IScsiBinToHex (
+ IN UINT8 *BinBuffer,
+ IN UINT32 BinLength,
+ IN OUT CHAR8 *HexStr,
+ IN OUT UINT32 *HexLength
+ )
{
UINTN Index;
@@ -536,31 +488,27 @@ Returns: return EFI_SUCCESS;
}
-EFI_STATUS
-IScsiHexToBin (
- IN OUT UINT8 *BinBuffer,
- IN OUT UINT32 *BinLength,
- IN CHAR8 *HexStr
- )
-/*++
-
-Routine Description:
-
+/**
Convert the hexadecimal string into a binary encoded buffer.
-Arguments:
+ @param BinBuffer[in][out] The binary buffer.
- BinBuffer - The binary buffer.
- BinLength - Length of the binary buffer.
- HexStr - The hexadecimal string.
+ @param BinLength[in][out] Length of the binary buffer.
-Returns:
+ @param HexStr[in] The hexadecimal string.
- EFI_SUCCESS - The hexadecimal string is converted into a binary
- encoded buffer.
- EFI_BUFFER_TOO_SMALL - The binary buffer is too small to hold the converted data.s
+ @retval EFI_SUCCESS The hexadecimal string is converted into a binary
+ encoded buffer.
---*/
+ @retval EFI_BUFFER_TOO_SMALL The binary buffer is too small to hold the converted data.s
+
+**/
+EFI_STATUS
+IScsiHexToBin (
+ IN OUT UINT8 *BinBuffer,
+ IN OUT UINT32 *BinLength,
+ IN CHAR8 *HexStr
+ )
{
UINTN Index;
UINT32 HexCount;
@@ -613,27 +561,21 @@ Returns: return EFI_SUCCESS;
}
-VOID
-IScsiGenRandom (
- IN OUT UINT8 *Rand,
- IN UINTN RandLength
- )
-/*++
-
-Routine Description:
-
+/**
Generate random numbers.
-Arguments:
+ @param Rand[in][out] The buffer to contain random numbers.
- Rand - The buffer to contain random numbers.
- RandLength - The length of the Rand buffer.
+ @param RandLength[in] The length of the Rand buffer.
-Returns:
+ @retval None.
- None.
-
---*/
+**/
+VOID
+IScsiGenRandom (
+ IN OUT UINT8 *Rand,
+ IN UINTN RandLength
+ )
{
UINT32 Random;
@@ -644,27 +586,21 @@ Returns: }
}
-ISCSI_DRIVER_DATA *
-IScsiCreateDriverData (
- IN EFI_HANDLE Image,
- IN EFI_HANDLE Controller
- )
-/*++
-
-Routine Description:
-
+/**
Create the iSCSI driver data..
-Arguments:
+ @param Image[in] The handle of the driver image.
- Image - The handle of the driver image.
- Controller - The handle of the controller.
+ @param Controller[in] The handle of the controller.
-Returns:
+ @retval The iSCSI driver data created.
- The iSCSI driver data created.
-
---*/
+**/
+ISCSI_DRIVER_DATA *
+IScsiCreateDriverData (
+ IN EFI_HANDLE Image,
+ IN EFI_HANDLE Controller
+ )
{
ISCSI_DRIVER_DATA *Private;
EFI_STATUS Status;
@@ -725,25 +661,18 @@ Returns: return Private;
}
-VOID
-IScsiCleanDriverData (
- IN ISCSI_DRIVER_DATA *Private
- )
-/*++
-
-Routine Description:
-
+/**
Clean the iSCSI driver data.
-Arguments:
-
- Private - The iSCSI driver data.
-
-Returns:
+ @param Private[in] The iSCSI driver data.
- None.
+ @retval None.
---*/
+**/
+VOID
+IScsiCleanDriverData (
+ IN ISCSI_DRIVER_DATA *Private
+ )
{
if (Private->DevicePath != NULL) {
gBS->UninstallProtocolInterface (
@@ -768,26 +697,21 @@ Returns: gBS->FreePool (Private);
}
-EFI_STATUS
-IScsiGetConfigData (
- IN ISCSI_DRIVER_DATA *Private
- )
-/*++
-
-Routine Description:
+/**
Get the various configuration data of this iSCSI instance.
-Arguments:
-
- Private - The iSCSI driver data.
+ @param Private[in] The iSCSI driver data.
-Returns:
+ @retval EFI_SUCCESS The configuration of this instance is got.
- EFI_SUCCESS - The configuration of this instance is got.
- EFI_NOT_FOUND - This iSCSI instance is not configured yet.
+ @retval EFI_NOT_FOUND This iSCSI instance is not configured yet.
---*/
+**/
+EFI_STATUS
+IScsiGetConfigData (
+ IN ISCSI_DRIVER_DATA *Private
+ )
{
EFI_STATUS Status;
ISCSI_SESSION *Session;
@@ -866,25 +790,18 @@ Returns: return Status;
}
-EFI_DEVICE_PATH_PROTOCOL *
-IScsiGetTcpConnDevicePath (
- IN ISCSI_DRIVER_DATA *Private
- )
-/*++
-
-Routine Description:
-
+/**
Get the device path of the iSCSI tcp connection and update it.
-Arguments:
+ @param Private[in] The iSCSI driver data.
- Private - The iSCSI driver data.
+ @retval The updated device path.
-Returns:
-
- The updated device path.
-
---*/
+**/
+EFI_DEVICE_PATH_PROTOCOL *
+IScsiGetTcpConnDevicePath (
+ IN ISCSI_DRIVER_DATA *Private
+ )
{
ISCSI_SESSION *Session;
ISCSI_CONNECTION *Conn;
@@ -937,28 +854,22 @@ Returns: return DevicePath;
}
+/**
+ Abort the session when the transition from BS to RT is initiated.
+
+ @param Event[in] The event signaled.
+
+ @param Context[in] The iSCSI driver data.
+
+ @retval None.
+
+**/
VOID
EFIAPI
IScsiOnExitBootService (
IN EFI_EVENT Event,
IN VOID *Context
)
-/*++
-
-Routine Description:
-
- Abort the session when the transition from BS to RT is initiated.
-
-Arguments:
-
- Event - The event signaled.
- Context - The iSCSI driver data.
-
-Returns:
-
- None.
-
---*/
{
ISCSI_DRIVER_DATA *Private;
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiMisc.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiMisc.h index 33315ae581..4eb4247c6f 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiMisc.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiMisc.h @@ -1,6 +1,7 @@ -/*++
+/** @file
+ Miscellaneous definitions for IScsi driver.
-Copyright (c) 2004 - 2007, Intel Corporation
+Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -15,9 +16,9 @@ Module Name: Abstract:
- Miscellaneous definitions for iSCSI driver.
+ Miscellaneous definitions for IScsi driver.
---*/
+**/
#ifndef _ISCSI_MISC_H_
#define _ISCSI_MISC_H_
@@ -47,35 +48,97 @@ struct _ISCSI_SESSION_CONFIG_DATA { EFI_IPv4_ADDRESS DhcpServer;
};
+/**
+ Calculate the prefix length of the IPv4 subnet mask.
+
+ @param SubnetMask[in] The IPv4 subnet mask.
+
+ @retval UINT8 The prefix length of the subnet mask.
+
+**/
UINT8
IScsiGetSubnetMaskPrefixLength (
IN EFI_IPv4_ADDRESS *SubnetMask
);
+/**
+ Convert the hexadecimal encoded LUN string into the 64-bit LUN.
+
+ @param Str[in] The hexadecimal encoded LUN string.
+
+ @param Lun[out] Storage to return the 64-bit LUN.
+
+ @retval EFI_SUCCESS The 64-bit LUN is stored in Lun.
+
+ @retval EFI_INVALID_PARAMETER The string is malformatted.
+
+**/
EFI_STATUS
IScsiAsciiStrToLun (
IN CHAR8 *Str,
OUT UINT8 *Lun
);
+/**
+ Convert the 64-bit LUN into the hexadecimal encoded LUN string.
+
+ @param Lun[in] The 64-bit LUN.
+
+ @param Str[out] The storage to return the hexadecimal encoded LUN string.
+
+ @retval None.
+
+**/
VOID
IScsiLunToUnicodeStr (
IN UINT8 *Lun,
OUT CHAR16 *String
);
-CHAR16 *
+/**
+ Convert the ASCII string into a UNICODE string.
+
+ @param Source[out] The ASCII string.
+
+ @param Destination[out] The storage to return the UNICODE string.
+
+ @retval CHAR16 * Pointer to the UNICODE string.
+
+**/
+CHAR16 *
IScsiAsciiStrToUnicodeStr (
IN CHAR8 *Source,
OUT CHAR16 *Destination
);
-CHAR8 *
+/**
+ Convert the UNICODE string into an ASCII string.
+
+ @param Source[in] The UNICODE string.
+
+ @param Destination[out] The storage to return the ASCII string.
+
+ @retval CHAR8 * Pointer to the ASCII string.
+
+**/
+CHAR8 *
IScsiUnicodeStrToAsciiStr (
IN CHAR16 *Source,
OUT CHAR8 *Destination
);
+/**
+ Convert the mac address into a hexadecimal encoded "-" seperated string.
+
+ @param Mac[in] The mac address.
+
+ @param Len[in] Length in bytes of the mac address.
+
+ @param Str[out] The storage to return the mac string.
+
+ @retval None.
+
+**/
VOID
IScsiMacAddrToStr (
IN EFI_MAC_ADDRESS *Mac,
@@ -83,12 +146,41 @@ IScsiMacAddrToStr ( OUT CHAR16 *Str
);
+/**
+ Convert the decimal dotted IPv4 address into the binary IPv4 address.
+
+ @param Str[in] The UNICODE string.
+
+ @param Ip[out] The storage to return the ASCII string.
+
+ @retval EFI_SUCCESS The binary IP address is returned in Ip.
+
+ @retval EFI_INVALID_PARAMETER The IP string is malformatted.
+
+**/
EFI_STATUS
IScsiAsciiStrToIp (
IN CHAR8 *Str,
OUT EFI_IPv4_ADDRESS *Ip
);
+/**
+ Convert the binary encoded buffer into a hexadecimal encoded string.
+
+ @param BinBuffer[in] The buffer containing the binary data.
+
+ @param BinLength[in] Length of the binary buffer.
+
+ @param HexStr[in][out] Pointer to the string.
+
+ @param HexLength[in][out] The length of the string.
+
+ @retval EFI_SUCCESS The binary data is converted to the hexadecimal string
+ and the length of the string is updated.
+
+ @retval EFI_BUFFER_TOO_SMALL The string is too small.
+
+**/
EFI_STATUS
IScsiBinToHex (
IN UINT8 *BinBuffer,
@@ -97,6 +189,21 @@ IScsiBinToHex ( IN OUT UINT32 *HexLength
);
+/**
+ Convert the hexadecimal string into a binary encoded buffer.
+
+ @param BinBuffer[in][out] The binary buffer.
+
+ @param BinLength[in][out] Length of the binary buffer.
+
+ @param HexStr[in] The hexadecimal string.
+
+ @retval EFI_SUCCESS The hexadecimal string is converted into a binary
+ encoded buffer.
+
+ @retval EFI_BUFFER_TOO_SMALL The binary buffer is too small to hold the converted data.s
+
+**/
EFI_STATUS
IScsiHexToBin (
IN OUT UINT8 *BinBuffer,
@@ -104,33 +211,90 @@ IScsiHexToBin ( IN CHAR8 *HexStr
);
+/**
+ Generate random numbers.
+
+ @param Rand[in][out] The buffer to contain random numbers.
+
+ @param RandLength[in] The length of the Rand buffer.
+
+ @retval None.
+
+**/
VOID
IScsiGenRandom (
IN OUT UINT8 *Rand,
IN UINTN RandLength
);
-ISCSI_DRIVER_DATA *
+/**
+ Create the iSCSI driver data..
+
+ @param Image[in] The handle of the driver image.
+
+ @param Controller[in] The handle of the controller.
+
+ @retval The iSCSI driver data created.
+
+**/
+ISCSI_DRIVER_DATA *
IScsiCreateDriverData (
IN EFI_HANDLE Image,
IN EFI_HANDLE Controller
);
+/**
+ Clean the iSCSI driver data.
+
+ @param Private[in] The iSCSI driver data.
+
+ @retval None.
+
+**/
VOID
IScsiCleanDriverData (
IN ISCSI_DRIVER_DATA *Private
);
+/**
+
+ Get the various configuration data of this iSCSI instance.
+
+ @param Private[in] The iSCSI driver data.
+
+ @retval EFI_SUCCESS The configuration of this instance is got.
+
+ @retval EFI_NOT_FOUND This iSCSI instance is not configured yet.
+
+**/
EFI_STATUS
IScsiGetConfigData (
IN ISCSI_DRIVER_DATA *Private
);
+/**
+ Get the device path of the iSCSI tcp connection and update it.
+
+ @param Private[in] The iSCSI driver data.
+
+ @retval The updated device path.
+
+**/
EFI_DEVICE_PATH_PROTOCOL *
IScsiGetTcpConnDevicePath (
IN ISCSI_DRIVER_DATA *Private
);
+/**
+ Abort the session when the transition from BS to RT is initiated.
+
+ @param Event[in] The event signaled.
+
+ @param Context[in] The iSCSI driver data.
+
+ @retval None.
+
+**/
VOID
EFIAPI
IScsiOnExitBootService (
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiProto.c b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiProto.c index 93b7f715e1..d87b5d6cad 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiProto.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiProto.c @@ -1,6 +1,7 @@ -/*++
+/** @file
+ The implementation of IScsi protocol based on RFC3720
-Copyright (c) 2004 - 2007, Intel Corporation
+Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -14,86 +15,68 @@ Module Name: IScsiProto.c
Abstract:
+ The implementation of IScsi protocol based on RFC3720
---*/
+**/
#include "IScsiImpl.h"
static UINT32 mDataSegPad = 0;
-VOID
-IScsiAttatchConnection (
- IN ISCSI_SESSION *Session,
- IN ISCSI_CONNECTION *Conn
- )
-/*++
-
-Routine Description:
-
+/**
Attach the iSCSI connection to the iSCSI session.
-Arguments:
+ @param Session[in] The iSCSI session.
- Session - The iSCSI session.
- Conn - The iSCSI connection.
+ @param Conn[in] The iSCSI connection.
-Returns:
+ @retval None.
- None.
-
---*/
+**/
+VOID
+IScsiAttatchConnection (
+ IN ISCSI_SESSION *Session,
+ IN ISCSI_CONNECTION *Conn
+ )
{
InsertTailList (&Session->Conns, &Conn->Link);
Conn->Session = Session;
Session->NumConns++;
}
-VOID
-IScsiDetatchConnection (
- IN ISCSI_CONNECTION *Conn
- )
-/*++
-
-Routine Description:
-
+/**
Detach the iSCSI connection from the session it belongs to.
-Arguments:
-
- Conn - The iSCSI connection.
-
-Returns:
+ @param Conn[in] The iSCSI connection.
- None.
+ @retval None.
---*/
+**/
+VOID
+IScsiDetatchConnection (
+ IN ISCSI_CONNECTION *Conn
+ )
{
RemoveEntryList (&Conn->Link);
Conn->Session->NumConns--;
Conn->Session = NULL;
}
-EFI_STATUS
-IScsiCheckSN (
- IN UINT32 *ExpSN,
- IN UINT32 NewSN
- )
-/*++
-
-Routine Description:
-
+/**
Check the sequence number according to RFC3720.
-Arguments:
-
- ExpSN - The currently expected sequence number.
- NewSN - The sequence number to check.
+ @param ExpSN[in] The currently expected sequence number.
-Returns:
+ @param NewSN[in] The sequence number to check.
- EFI_SUCCESS - The check passed and the ExpSN is increased.
+ @retval EFI_SUCCESS The check passed and the ExpSN is increased.
---*/
+**/
+EFI_STATUS
+IScsiCheckSN (
+ IN UINT32 *ExpSN,
+ IN UINT32 NewSN
+ )
{
if (!ISCSI_SEQ_EQ (NewSN, *ExpSN)) {
if (ISCSI_SEQ_LT (NewSN, *ExpSN)) {
@@ -113,29 +96,24 @@ Returns: }
}
-VOID
-IScsiUpdateCmdSN (
- IN ISCSI_SESSION *Session,
- IN UINT32 MaxCmdSN,
- IN UINT32 ExpCmdSN
- )
-/*++
-
-Routine Description:
-
+/**
Update the sequence numbers for the iSCSI command.
-Arguments:
+ @param Session[in] The iSCSI session.
- Session - The iSCSI session.
- MaxCmdSN - Maximum CmdSN from the target.
- ExpCmdSN - Next expected CmdSN from the target.
+ @param MaxCmdSN[in] Maximum CmdSN from the target.
-Returns:
+ @param ExpCmdSN[in] Next expected CmdSN from the target.
- None.
+ @retval None.
---*/
+**/
+VOID
+IScsiUpdateCmdSN (
+ IN ISCSI_SESSION *Session,
+ IN UINT32 MaxCmdSN,
+ IN UINT32 ExpCmdSN
+ )
{
if (ISCSI_SEQ_LT (MaxCmdSN, ExpCmdSN - 1)) {
return ;
@@ -150,27 +128,22 @@ Returns: }
}
-EFI_STATUS
-IScsiConnLogin (
- IN ISCSI_CONNECTION *Conn
- )
-/*++
-
-Routine Description:
-
+/**
This function does the iSCSI connection login.
-Arguments:
+ @param Conn[in] The iSCSI connection to login.
- Conn - The iSCSI connection to login.
+ @retval EFI_SUCCESS The iSCSI connection is logged into the iSCSI target.
-Returns:
+ @retval EFI_TIMEOUT Timeout happened during the login procedure.
- EFI_SUCCESS - The iSCSI connection is logged into the iSCSI target.
- EFI_TIMEOUT - Timeout happened during the login procedure.
- EFI_PROTOCOL_ERROR - Some kind of iSCSI protocol error happened.
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
---*/
+**/
+EFI_STATUS
+IScsiConnLogin (
+ IN ISCSI_CONNECTION *Conn
+ )
{
EFI_STATUS Status;
@@ -210,50 +183,37 @@ Returns: return Status;
}
+/**
+ Reset the iSCSI connection.
+
+ @param Conn[in] The iSCSI connection to reset.
+
+ @retval None.
+
+**/
VOID
IScsiConnReset (
IN ISCSI_CONNECTION *Conn
)
-/*++
-
-Routine Description:
-
- Reset the iSCSI connection.
+{
+ Tcp4IoReset (&Conn->Tcp4Io);
+}
-Arguments:
+/**
+ Create a TCP connection for the iSCSI session.
- Conn - The iSCSI connection to reset.
+ @param Private[in] The iSCSI driver data.
-Returns:
+ @param Session[in] Maximum CmdSN from the target.
- None.
-
---*/
-{
- Tcp4IoReset (&Conn->Tcp4Io);
-}
+ @retval The newly created iSCSI connection.
+**/
ISCSI_CONNECTION *
IScsiCreateConnection (
IN ISCSI_DRIVER_DATA *Private,
IN ISCSI_SESSION *Session
)
-/*++
-
-Routine Description:
-
- Create a TCP connection for the iSCSI session.
-
-Arguments:
-
- Private - The iSCSI driver data.
- Session - Maximum CmdSN from the target.
-
-Returns:
-
- The newly created iSCSI connection.
-
---*/
{
ISCSI_CONNECTION *Conn;
TCP4_IO_CONFIG_DATA Tcp4IoConfig;
@@ -320,25 +280,18 @@ Returns: return Conn;
}
-VOID
-IScsiDestroyConnection (
- IN ISCSI_CONNECTION *Conn
- )
-/*++
-
-Routine Description:
-
+/**
Destroy an iSCSI connection.
-Arguments:
+ @param Conn[in] The connection to destroy.
- Conn - The connection to destroy.
+ @retval None.
-Returns:
-
- None.
-
---*/
+**/
+VOID
+IScsiDestroyConnection (
+ IN ISCSI_CONNECTION *Conn
+ )
{
Tcp4IoDestroySocket (&Conn->Tcp4Io);
NetbufQueFlush (&Conn->RspQue);
@@ -346,27 +299,22 @@ Returns: gBS->FreePool (Conn);
}
-EFI_STATUS
-IScsiSessionLogin (
- IN ISCSI_DRIVER_DATA *Private
- )
-/*++
-
-Routine Description:
-
+/**
Login the iSCSI session.
-Arguments:
+ @param Private[in] The iSCSI driver data.
- Private - The iSCSI driver data.
+ @retval EFI_SUCCESS The iSCSI session login procedure finished.
-Returns:
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
- EFI_SUCCESS - The iSCSI session login procedure finished.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
- EFI_PROTOCOL_ERROR - Some kind of iSCSI protocol error happened.
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
---*/
+**/
+EFI_STATUS
+IScsiSessionLogin (
+ IN ISCSI_DRIVER_DATA *Private
+ )
{
EFI_STATUS Status;
ISCSI_SESSION *Session;
@@ -409,29 +357,24 @@ Returns: return Status;
}
-EFI_STATUS
-IScsiSendLoginReq (
- IN ISCSI_CONNECTION *Conn
- )
-/*++
-
-Routine Description:
-
+/**
Build and send the iSCSI login request to the iSCSI target according to
the current login stage.
-Arguments:
+ @param Conn[in] The connection in the iSCSI login phase.
- Conn - The connection in the iSCSI login phase.
+ @retval EFI_SUCCESS The iSCSI login request PDU is built and sent on this
+ connection.
-Returns:
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
- EFI_SUCCESS - The iSCSI login request PDU is built and sent on this
- connection.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
- EFI_PROTOCOL_ERROR - Some kind of iSCSI protocol error happened.
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
---*/
+**/
+EFI_STATUS
+IScsiSendLoginReq (
+ IN ISCSI_CONNECTION *Conn
+ )
{
NET_BUF *Pdu;
EFI_STATUS Status;
@@ -453,27 +396,22 @@ Returns: return Status;
}
-EFI_STATUS
-IScsiReceiveLoginRsp (
- IN ISCSI_CONNECTION *Conn
- )
-/*++
-
-Routine Description:
-
+/**
Receive and process the iSCSI login response.
-Arguments:
+ @param Conn[in] The connection in the iSCSI login phase.
- Conn - The connection in the iSCSI login phase.
+ @retval EFI_SUCCESS The iSCSI login response PDU is received and processed.
-Returns:
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
- EFI_SUCCESS - The iSCSI login response PDU is received and processed.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
- EFI_PROTOCOL_ERROR - Some kind of iSCSI protocol error happened.
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
---*/
+**/
+EFI_STATUS
+IScsiReceiveLoginRsp (
+ IN ISCSI_CONNECTION *Conn
+ )
{
EFI_STATUS Status;
NET_BUF *Pdu;
@@ -495,34 +433,31 @@ Returns: return Status;
}
-EFI_STATUS
-IScsiAddKeyValuePair (
- IN NET_BUF *Pdu,
- IN CHAR8 *Key,
- IN CHAR8 *Value
- )
-/*++
-
-Routine Description:
-
+/**
Add an iSCSI key-value pair as a string into the data segment of the Login Request PDU.
The DataSegmentLength and the actual size of the net buffer containing this PDU will be
updated.
-Arguments:
+ @param Pdu[in] The iSCSI PDU whose data segment the key-value pair will
+ be added to.
+
+ @param Key[in] The key name string.
- Pdu - The iSCSI PDU whose data segment the key-value pair will be added to.
- Key - The key name string.
- Value - The value string.
+ @param Value[in] The value string.
-Returns:
+ @retval EFI_SUCCESS The key-valu pair is added to the PDU's datasegment and
+ the correspondence length fields are updated.
- EFI_SUCCESS - The key-valu pair is added to the PDU's datasegment and
- the correspondence length fields are updated.
- EFI_OUT_OF_RESOURCES - There is not enough space in the PDU to add the key-value
- pair.
+ @retval EFI_OUT_OF_RESOURCES There is not enough space in the PDU to add the key-value
+ pair.
---*/
+**/
+EFI_STATUS
+IScsiAddKeyValuePair (
+ IN NET_BUF *Pdu,
+ IN CHAR8 *Key,
+ IN CHAR8 *Value
+ )
{
UINT32 DataSegLen;
UINT32 KeyLen;
@@ -575,25 +510,18 @@ Returns: return EFI_SUCCESS;
}
-NET_BUF *
-IScsiPrepareLoginReq (
- IN ISCSI_CONNECTION *Conn
- )
-/*++
-
-Routine Description:
-
+/**
Prepare the iSCSI login request to be sent according to the current login status.
-Arguments:
+ @param Conn[in] The connection in the iSCSI login phase.
- Conn - The connection in the iSCSI login phase.
+ @retval The pointer to the net buffer containing the iSCSI login request built.
-Returns:
-
- The pointer to the net buffer containing the iSCSI login request built.
-
---*/
+**/
+NET_BUF *
+IScsiPrepareLoginReq (
+ IN ISCSI_CONNECTION *Conn
+ )
{
ISCSI_SESSION *Session;
NET_BUF *Nbuf;
@@ -674,28 +602,23 @@ Returns: return Nbuf;
}
-EFI_STATUS
-IScsiProcessLoginRsp (
- IN ISCSI_CONNECTION *Conn,
- IN NET_BUF *Pdu
- )
-/*++
-
-Routine Description:
-
+/**
Process the iSCSI Login Response.
-Arguments:
+ @param Conn[in] The connection on which the iSCSI login response is received.
- Conn - The connection on which the iSCSI login response is received.
- Pdu - The iSCSI login response PDU.
+ @param Pdu[in] The iSCSI login response PDU.
-Returns:
+ @retval EFI_SUCCESS The iSCSI login response PDU is processed and all check are passed.
- EFI_SUCCESS - The iSCSI login response PDU is processed and all check are passed.
- EFI_PROTOCOL_ERROR - Some kind of iSCSI protocol error happened.
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
---*/
+**/
+EFI_STATUS
+IScsiProcessLoginRsp (
+ IN ISCSI_CONNECTION *Conn,
+ IN NET_BUF *Pdu
+ )
{
EFI_STATUS Status;
ISCSI_SESSION *Session;
@@ -886,32 +809,30 @@ Returns: return Status;
}
-EFI_STATUS
-IScsiUpdateTargetAddress (
- IN ISCSI_SESSION *Session,
- IN CHAR8 *Data,
- IN UINT32 Len
- )
-/*++
-
-Routine Description:
-
+/**
Updated the target information according the data received in the iSCSI
login response with an target redirection status.
-Arguments:
+ @param Session[in] The iSCSI session.
+
+ @param Data[in] The data segment which should contain the
+ TargetAddress key-value list.
+
+ @param Len[in] Length of the data.
- Session - The iSCSI session.
- Data - The data segment which should contain the TargetAddress key-value list.
- Len - Length of the data.
+ @retval EFI_SUCCESS The target address is updated.
-Returns:
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
- EFI_SUCCESS - The target address is updated.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
- EFI_NOT_FOUND - The TargetAddress key is not found.
+ @retval EFI_NOT_FOUND The TargetAddress key is not found.
---*/
+**/
+EFI_STATUS
+IScsiUpdateTargetAddress (
+ IN ISCSI_SESSION *Session,
+ IN CHAR8 *Data,
+ IN UINT32 Len
+ )
{
LIST_ENTRY *KeyValueList;
CHAR8 *TargetAddress;
@@ -989,25 +910,18 @@ Returns: return Status;
}
-VOID
-IScsiFreeNbufList (
- VOID *Arg
- )
-/*++
-
-Routine Description:
-
+/**
The callback function to free the net buffer list.
-Arguments:
+ @param Arg[in] The opaque parameter.
- Arg - The opaque parameter.
+ @retval None.
-Returns:
-
- None.
-
---*/
+**/
+VOID
+IScsiFreeNbufList (
+ VOID *Arg
+ )
{
ASSERT (Arg != NULL);
@@ -1015,28 +929,45 @@ Returns: gBS->FreePool (Arg);
}
+/**
+ The callback function called in NetBufFree, it does nothing.
+
+ @param Arg[in] The opaque parameter.
+
+ @retval None.
+
+**/
VOID
IScsiNbufExtFree (
VOID *Arg
)
-/*++
+{
+}
-Routine Description:
+/**
+ Receive an iSCSI response PDU. An iSCSI response PDU contains an iSCSI PDU header and
+ an optional data segment. The two parts will be put into two blocks of buffers in the
+ net buffer. The digest check will be conducted in this function if needed and the digests
+ will be trimmed from the PDU buffer.
- The callback function called in NetBufFree, it does nothing.
+ @param Conn[in] The iSCSI connection to receive data from.
-Arguments:
+ @param Pdu[out] The received iSCSI pdu.
- Arg - The opaque parameter.
+ @param Context[in] The context used to describe information on the caller provided
+ buffer to receive data segment of the iSCSI pdu, it's optional.
-Returns:
+ @param HeaderDigest[in] Whether there will be header digest received.
- None.
+ @param DataDigest[in] Whether there will be data digest.
---*/
-{
-}
+ @param TimeoutEvent[in] The timeout event, it's optional.
+
+ @retval EFI_SUCCESS An iSCSI pdu is received.
+
+ @retval EFI_TIMEOUT Timeout happenend.
+**/
EFI_STATUS
IScsiReceivePdu (
IN ISCSI_CONNECTION *Conn,
@@ -1046,31 +977,6 @@ IScsiReceivePdu ( IN BOOLEAN DataDigest,
IN EFI_EVENT TimeoutEvent OPTIONAL
)
-/*++
-
-Routine Description:
-
- Receive an iSCSI response PDU. An iSCSI response PDU contains an iSCSI PDU header and
- an optional data segment. The two parts will be put into two blocks of buffers in the
- net buffer. The digest check will be conducted in this function if needed and the digests
- will be trimmed from the PDU buffer.
-
-Arguments:
-
- Conn - The iSCSI connection to receive data from.
- Pdu - The received iSCSI pdu.
- Context - The context used to describe information on the caller provided
- buffer to receive data segment of the iSCSI pdu, it's optional.
- HeaderDigest - Whether there will be header digest received.
- DataDigest - Whether there will be data digest.
- TimeoutEvent - The timeout event, it's optional.
-
-Returns:
-
- EFI_SUCCESS - An iSCSI pdu is received.
- EFI_TIMEOUT - Timeout happenend.
-
---*/
{
LIST_ENTRY *NbufList;
UINT32 Len;
@@ -1242,28 +1148,23 @@ ON_EXIT: return Status;
}
-EFI_STATUS
-IScsiCheckOpParams (
- IN ISCSI_CONNECTION *Conn,
- IN BOOLEAN Transit
- )
-/*++
-
-Routine Description:
-
+/**
Check and get the result of the prameter negotiation.
-Arguments:
+ @param Conn[in] The connection in iSCSI login.
- Conn - The connection in iSCSI login.
- Pdu - The iSCSI response PDU containing the parameter list.
+ @param Pdu[in] The iSCSI response PDU containing the parameter list.
-Returns:
+ @retval EFI_SUCCESS The parmeter check is passed and negotiation is finished.
- EFI_SUCCESS - The parmeter check is passed and negotiation is finished.
- EFI_PROTOCOL_ERROR - Some kind of iSCSI protocol error happened.
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
---*/
+**/
+EFI_STATUS
+IScsiCheckOpParams (
+ IN ISCSI_CONNECTION *Conn,
+ IN BOOLEAN Transit
+ )
{
EFI_STATUS Status;
LIST_ENTRY *KeyValueList;
@@ -1504,28 +1405,23 @@ ON_ERROR: return Status;
}
-EFI_STATUS
-IScsiFillOpParams (
- IN ISCSI_CONNECTION *Conn,
- IN NET_BUF *Pdu
- )
-/*++
-
-Routine Description:
-
+/**
Fill the oprational prameters.
-Arguments:
+ @param Conn[in] The connection in iSCSI login.
- Conn - The connection in iSCSI login.
- Pdu - The iSCSI login request PDU to fill the parameters.
+ @param Pdu[in] The iSCSI login request PDU to fill the parameters.
-Returns:
+ @retval EFI_SUCCESS The parmeters are filled into the iSCSI login request PDU.
- EFI_SUCCESS - The parmeters are filled into the iSCSI login request PDU.
- EFI_OUT_OF_RESOURCES - There is not enough space in the PDU to hold the parameters.
+ @retval EFI_OUT_OF_RESOURCES There is not enough space in the PDU to hold the parameters.
---*/
+**/
+EFI_STATUS
+IScsiFillOpParams (
+ IN ISCSI_CONNECTION *Conn,
+ IN NET_BUF *Pdu
+ )
{
ISCSI_SESSION *Session;
CHAR8 Value[256];
@@ -1577,29 +1473,24 @@ Returns: return EFI_SUCCESS;
}
-EFI_STATUS
-IScsiPadSegment (
- IN NET_BUF *Pdu,
- IN UINT32 Len
- )
-/*++
-
-Routine Description:
-
+/**
Pad the iSCSI AHS or data segment to an integer number of 4 byte words.
-Arguments:
+ @param Pdu[in] The iSCSI pdu which contains segments to pad.
- Pdu - The iSCSI pdu which contains segments to pad.
- Len - The length of the last semgnet in the PDU.
+ @param Len[in] The length of the last semgnet in the PDU.
-Returns:
+ @retval EFI_SUCCESS The segment is padded or no need to pad it.
- EFI_SUCCESS - The segment is padded or no need to pad it.
- EFI_OUT_OF_RESOURCES - There is not enough remaining free space to add the
- padding bytes.
+ @retval EFI_OUT_OF_RESOURCES There is not enough remaining free space to add the
+ padding bytes.
---*/
+**/
+EFI_STATUS
+IScsiPadSegment (
+ IN NET_BUF *Pdu,
+ IN UINT32 Len
+ )
{
UINT32 PadLen;
UINT8 *Data;
@@ -1618,27 +1509,21 @@ Returns: return EFI_SUCCESS;
}
-LIST_ENTRY *
-IScsiBuildKeyValueList (
- IN CHAR8 *Data,
- IN UINT32 Len
- )
-/*++
-
-Routine Description:
-
+/**
Build a key-value list from the data segment.
-Arguments:
-
- Data - The data segment containing the key-value pairs.
- Len - Length of the data segment.
+ @param Data[in] The data segment containing the key-value pairs.
-Returns:
+ @param Len[in] Length of the data segment.
- The key-value list.
+ @retval The key-value list.
---*/
+**/
+LIST_ENTRY *
+IScsiBuildKeyValueList (
+ IN CHAR8 *Data,
+ IN UINT32 Len
+ )
{
LIST_ENTRY *ListHead;
ISCSI_KEY_VALUE_PAIR *KeyValuePair;
@@ -1692,28 +1577,22 @@ ON_ERROR: return NULL;
}
-CHAR8 *
-IScsiGetValueByKeyFromList (
- IN LIST_ENTRY *KeyValueList,
- IN CHAR8 *Key
- )
-/*++
-
-Routine Description:
-
+/**
Get the value string by the key name from the key-value list. If found,
the key-value entry will be removed from the list.
-Arguments:
+ @param KeyValueList[in] The key-value list.
- KeyValueList - The key-value list.
- Key - The key name to find.
+ @param Key[in] The key name to find.
-Returns:
+ @retval The value string.
- The value string.
-
---*/
+**/
+CHAR8 *
+IScsiGetValueByKeyFromList (
+ IN LIST_ENTRY *KeyValueList,
+ IN CHAR8 *Key
+ )
{
LIST_ENTRY *Entry;
ISCSI_KEY_VALUE_PAIR *KeyValuePair;
@@ -1736,25 +1615,18 @@ Returns: return Value;
}
+/**
+ Free the key-value list.
+
+ @param KeyValueList[in] The key-value list.
+
+ @retval None.
+
+**/
VOID
IScsiFreeKeyValueList (
IN LIST_ENTRY *KeyValueList
)
-/*++
-
-Routine Description:
-
- Free the key-value list.
-
-Arguments:
-
- KeyValueList - The key-value list.
-
-Returns:
-
- None.
-
---*/
{
LIST_ENTRY *Entry;
ISCSI_KEY_VALUE_PAIR *KeyValuePair;
@@ -1769,28 +1641,23 @@ Returns: gBS->FreePool (KeyValueList);
}
-EFI_STATUS
-IScsiNormalizeName (
- IN CHAR8 *Name,
- IN UINTN Len
- )
-/*++
-
-Routine Description:
-
+/**
Normalize the iSCSI name according to RFC.
-Arguments:
+ @param Name[in] The iSCSI name.
- Name - The iSCSI name.
- Len - length of the iSCSI name.
+ @param Len[in] length of the iSCSI name.
-Returns:
+ @retval EFI_SUCCESS The iSCSI name is valid and normalized.
- EFI_SUCCESS - The iSCSI name is valid and normalized.
- EFI_PROTOCOL_ERROR - The iSCSI name is mal-formatted or not in the IQN format.
+ @retval EFI_PROTOCOL_ERROR The iSCSI name is mal-formatted or not in the IQN format.
---*/
+**/
+EFI_STATUS
+IScsiNormalizeName (
+ IN CHAR8 *Name,
+ IN UINTN Len
+ )
{
UINTN Index;
@@ -1826,28 +1693,23 @@ Returns: return EFI_SUCCESS;
}
-EFI_STATUS
-IScsiNewTcb (
- IN ISCSI_CONNECTION *Conn,
- OUT ISCSI_TCB **Tcb
- )
-/*++
-
-Routine Description:
-
+/**
Create an iSCSI task control block.
-Arguments:
+ @param Conn[in] The connection on which the task control block will be created.
- Conn - The connection on which the task control block will be created.
- Tcb - The newly created task control block.
+ @param Tcb[out] The newly created task control block.
-Returns:
+ @retval EFI_SUCCESS The task control block is created.
- EFI_SUCCESS - The task control block is created.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
---*/
+**/
+EFI_STATUS
+IScsiNewTcb (
+ IN ISCSI_CONNECTION *Conn,
+ OUT ISCSI_TCB **Tcb
+ )
{
ISCSI_SESSION *Session;
ISCSI_TCB *NewTcb;
@@ -1885,52 +1747,39 @@ Returns: return EFI_SUCCESS;
}
-VOID
-IScsiDelTcb (
- IN ISCSI_TCB *Tcb
- )
-/*++
-
-Routine Description:
-
+/**
Delete the tcb from the connection and destroy it.
-Arguments:
-
- Tcb - The tcb to delete.
+ @param Tcb The tcb to delete.
-Returns:
+ @retval None.
- None.
-
---*/
+**/
+VOID
+IScsiDelTcb (
+ IN ISCSI_TCB *Tcb
+ )
{
RemoveEntryList (&Tcb->Link);
gBS->FreePool (Tcb);
}
-ISCSI_TCB *
-IScsiFindTcbByITT (
- IN LIST_ENTRY *TcbList,
- IN UINT32 InitiatorTaskTag
- )
-/*++
-
-Routine Description:
-
+/**
Find the task control block by the initator task tag.
-Arguments:
-
- TcbList - The tcb list.
- InitiatorTaskTag - The initiator task tag.
+ @param TcbList[in] The tcb list.
-Returns:
+ @param InitiatorTaskTag[in] The initiator task tag.
- The task control block found.
+ @retval The task control block found.
---*/
+**/
+ISCSI_TCB *
+IScsiFindTcbByITT (
+ IN LIST_ENTRY *TcbList,
+ IN UINT32 InitiatorTaskTag
+ )
{
ISCSI_TCB *Tcb;
LIST_ENTRY *Entry;
@@ -1950,29 +1799,24 @@ Returns: return Tcb;
}
-NET_BUF *
-IScsiNewDataSegment (
- IN UINT8 *Data,
- IN UINT32 Len,
- IN BOOLEAN DataDigest
- )
-/*++
-
-Routine Description:
-
+/**
Create a data segment, pad it and calculate the CRC if needed.
-Arguments:
+ @param Data[in] The data to fill into the data segment.
- Data - The data to fill into the data segment.
- Len - Length of the data.
- DataDigest - Whether to calculate CRC for this data segment.
+ @param Len[in] Length of the data.
-Returns:
+ @param DataDigest[in] Whether to calculate CRC for this data segment.
- The net buffer wrapping the data segment.
+ @retval The net buffer wrapping the data segment.
---*/
+**/
+NET_BUF *
+IScsiNewDataSegment (
+ IN UINT8 *Data,
+ IN UINT32 Len,
+ IN BOOLEAN DataDigest
+ )
{
NET_FRAGMENT Fragment[2];
UINT32 FragmentCount;
@@ -1997,30 +1841,25 @@ Returns: return DataSeg;
}
-NET_BUF *
-IScsiNewScsiCmdPdu (
- IN EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet,
- IN UINT64 Lun,
- IN ISCSI_TCB *Tcb
- )
-/*++
-
-Routine Description:
-
+/**
Create a iSCSI SCSI command PDU to encapsulate the command issued
by SCSI through the EXT SCSI PASS THRU Protocol.
-Arguments:
+ @param Packet[in] The EXT SCSI PASS THRU request packet containing the SCSI command.
- Packet - The EXT SCSI PASS THRU request packet containing the SCSI command.
- Lun - The LUN.
- Tcb - The tcb assocated with this SCSI command.
+ @param Lun[in] The LUN.
-Returns:
+ @param Tcb[in] The tcb assocated with this SCSI command.
- The created iSCSI SCSI command PDU.
+ @retval The created iSCSI SCSI command PDU.
---*/
+**/
+NET_BUF *
+IScsiNewScsiCmdPdu (
+ IN EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet,
+ IN UINT64 Lun,
+ IN ISCSI_TCB *Tcb
+ )
{
LIST_ENTRY *NbufList;
NET_BUF *Pdu;
@@ -2177,6 +2016,22 @@ ON_EXIT: return Pdu;
}
+/**
+ Create a new iSCSI SCSI Data Out PDU.
+
+ @param Data[in] The data to put into the Data Out PDU.
+
+ @param Len[in] Length of the data.
+
+ @param DataSN[in] The DataSN of the Data Out PDU.
+
+ @param Tcb[in] The task control block of this Data Out PDU.
+
+ @param Lun[in] The LUN.
+
+ @retval The net buffer wrapping the Data Out PDU.
+
+**/
NET_BUF *
IScsiNewDataOutPdu (
IN UINT8 *Data,
@@ -2185,25 +2040,6 @@ IScsiNewDataOutPdu ( IN ISCSI_TCB *Tcb,
IN UINT64 Lun
)
-/*++
-
-Routine Description:
-
- Create a new iSCSI SCSI Data Out PDU.
-
-Arguments:
-
- Data - The data to put into the Data Out PDU.
- Len - Length of the data.
- DataSN - The DataSN of the Data Out PDU.
- Tcb - The task control block of this Data Out PDU.
- Lun - The LUN.
-
-Returns:
-
- The net buffer wrapping the Data Out PDU.
-
---*/
{
LIST_ENTRY *NbufList;
NET_BUF *PduHdr;
@@ -2273,29 +2109,24 @@ Returns: return Pdu;
}
-LIST_ENTRY *
-IScsiGenerateDataOutPduSequence (
- IN UINT8 *Data,
- IN ISCSI_TCB *Tcb,
- IN UINT64 Lun
- )
-/*++
-
-Routine Description:
-
+/**
Generate a consecutive sequence of iSCSI SCSI Data Out PDUs.
-Arguments:
+ @param Data[in] The data which will be carried by the sequence of iSCSI SCSI Data Out PDUs.
- Data - The data which will be carried by the sequence of iSCSI SCSI Data Out PDUs.
- Tcb - The task control block of the data to send out.
- Lun - The LUN the data will be sent to.
+ @param Tcb[in] The task control block of the data to send out.
-Returns:
+ @param Lun[in] The LUN the data will be sent to.
- A list of net buffers with each of them wraps an iSCSI SCSI Data Out PDU.
+ @retval A list of net buffers with each of them wraps an iSCSI SCSI Data Out PDU.
---*/
+**/
+LIST_ENTRY *
+IScsiGenerateDataOutPduSequence (
+ IN UINT8 *Data,
+ IN ISCSI_TCB *Tcb,
+ IN UINT64 Lun
+ )
{
LIST_ENTRY *PduList;
UINT32 DataSN;
@@ -2353,30 +2184,26 @@ ON_EXIT: return PduList;
}
-EFI_STATUS
-IScsiSendDataOutPduSequence (
- IN UINT8 *Data,
- IN UINT64 Lun,
- IN ISCSI_TCB *Tcb
- )
-/*++
-
-Routine Description:
-
+/**
Send the Data in a sequence of Data Out PDUs one by one.
-Arguments:
+ @param Data[in] The data to carry by Data Out PDUs.
- Data - The data to carry by Data Out PDUs.
- Lun - The LUN the data will be sent to.
- Tcb - The task control block.
+ @param Lun[in] The LUN the data will be sent to.
-Returns:
+ @param Tcb[in] The task control block.
- EFI_SUCCES - The data is sent out to the LUN.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
+ @retval EFI_SUCCES The data is sent out to the LUN.
---*/
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+**/
+EFI_STATUS
+IScsiSendDataOutPduSequence (
+ IN UINT8 *Data,
+ IN UINT64 Lun,
+ IN ISCSI_TCB *Tcb
+ )
{
LIST_ENTRY *DataOutPduList;
LIST_ENTRY *Entry;
@@ -2410,31 +2237,27 @@ Returns: return Status;
}
-EFI_STATUS
-IScsiOnDataInRcvd (
- IN NET_BUF *Pdu,
- IN ISCSI_TCB *Tcb,
- IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet
- )
-/*++
-
-Routine Description:
-
+/**
Process the received iSCSI SCSI Data In PDU.
-Arguments:
+ @param Pdu[in] The Data In PDU received.
+
+ @param Tcb[in] The task control block.
- Pdu - The Data In PDU received.
- Tcb - The task control block.
- Packet - The EXT SCSI PASS THRU request packet.
+ @param Packet[in][out] The EXT SCSI PASS THRU request packet.
-Returns:
+ @retval EFI_SUCCES The check on the Data IN PDU is passed and some update
+ actions are taken.
- EFI_SUCCES - The check on the Data IN PDU is passed and some update
- actions are taken.
- EFI_PROTOCOL_ERROR - Some kind of iSCSI protocol errror happened.
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol errror happened.
---*/
+**/
+EFI_STATUS
+IScsiOnDataInRcvd (
+ IN NET_BUF *Pdu,
+ IN ISCSI_TCB *Tcb,
+ IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet
+ )
{
ISCSI_SCSI_DATA_IN *DataInHdr;
EFI_STATUS Status;
@@ -2502,32 +2325,29 @@ Returns: return Status;
}
-EFI_STATUS
-IScsiOnR2TRcvd (
- IN NET_BUF *Pdu,
- IN ISCSI_TCB *Tcb,
- IN UINT64 Lun,
- IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet
- )
-/*++
+/**
+ Process the received iSCSI R2T PDU.
-Routine Description:
+ @param Pdu[in] The R2T PDU received.
- Process the received iSCSI R2T PDU.
+ @param Tcb[in] The task control block.
-Arguments:
+ @param Lun[in] The Lun.
- Pdu - The R2T PDU received.
- Tcb - The task control block.
- Lun - The Lun.
- Packet - The EXT SCSI PASS THRU request packet.
+ @param Packet[in][out] The EXT SCSI PASS THRU request packet.
-Returns:
+ @retval EFI_SUCCES The R2T PDU is valid and the solicited data is sent out.
- EFI_SUCCES - The R2T PDU is valid and the solicited data is sent out.
- EFI_PROTOCOL_ERROR - Some kind of iSCSI protocol errror happened.
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol errror happened.
---*/
+**/
+EFI_STATUS
+IScsiOnR2TRcvd (
+ IN NET_BUF *Pdu,
+ IN ISCSI_TCB *Tcb,
+ IN UINT64 Lun,
+ IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet
+ )
{
ISCSI_READY_TO_TRANSFER *R2THdr;
EFI_STATUS Status;
@@ -2573,30 +2393,26 @@ Returns: return Status;
}
-EFI_STATUS
-IScsiOnScsiRspRcvd (
- IN NET_BUF *Pdu,
- IN ISCSI_TCB *Tcb,
- IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet
- )
-/*++
-
-Routine Description:
-
+/**
Process the received iSCSI SCSI Response PDU.
-Arguments:
+ @param Pdu[in] The Response PDU received.
- Pdu - The Response PDU received.
- Tcb - The task control block.
- Packet - The EXT SCSI PASS THRU request packet.
+ @param Tcb[in] The task control block.
-Returns:
+ @param Packet[in][out] The EXT SCSI PASS THRU request packet.
- EFI_SUCCES - The Response PDU is processed.
- EFI_PROTOCOL_ERROR - Some kind of iSCSI protocol errror happened.
+ @retval EFI_SUCCES The Response PDU is processed.
---*/
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol errror happened.
+
+**/
+EFI_STATUS
+IScsiOnScsiRspRcvd (
+ IN NET_BUF *Pdu,
+ IN ISCSI_TCB *Tcb,
+ IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet
+ )
{
SCSI_RESPONSE *ScsiRspHdr;
ISCSI_SENSE_DATA *SenseData;
@@ -2680,29 +2496,24 @@ Returns: return Status;
}
-EFI_STATUS
-IScsiOnNopInRcvd (
- IN NET_BUF *Pdu,
- IN ISCSI_TCB *Tcb
- )
-/*++
-
-Routine Description:
-
+/**
Process the received NOP In PDU.
-Arguments:
+ @param Pdu[in] The NOP In PDU received.
- Pdu - The NOP In PDU received.
- Tcb - The task control block.
+ @param Tcb[in] The task control block.
-Returns:
+ @retval EFI_SUCCES The NOP In PDU is processed and the related sequence
+ numbers are updated.
- EFI_SUCCES - The NOP In PDU is processed and the related sequence
- numbers are updated.
- EFI_PROTOCOL_ERROR - Some kind of iSCSI protocol errror happened.
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol errror happened.
---*/
+**/
+EFI_STATUS
+IScsiOnNopInRcvd (
+ IN NET_BUF *Pdu,
+ IN ISCSI_TCB *Tcb
+ )
{
ISCSI_NOP_IN *NopInHdr;
EFI_STATUS Status;
@@ -2729,34 +2540,31 @@ Returns: return EFI_SUCCESS;
}
-EFI_STATUS
-IScsiExecuteScsiCommand (
- IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *PassThru,
- IN UINT8 *Target,
- IN UINT64 Lun,
- IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet
- )
-/*++
+/**
+ Execute the SCSI command issued through the EXT SCSI PASS THRU protocol.
-Routine Description:
+ @param PassThru[in] The EXT SCSI PASS THRU protocol.
- Execute the SCSI command issued through the EXT SCSI PASS THRU protocol.
+ @param Target[in] The target ID.
-Arguments:
+ @param Lun[in] The LUN.
- PassThru - The EXT SCSI PASS THRU protocol.
- Target - The target ID.
- Lun - The LUN.
- Packet - The request packet containing IO request, SCSI command buffer and
- buffers to read/write.
+ @param Packet[in][out] The request packet containing IO request, SCSI command
+ buffer and buffers to read/write.
-Returns:
+ @retval EFI_SUCCES The SCSI command is executed and the result is updated to
+ the Packet.
- EFI_SUCCES - The SCSI command is executed and the result is updated to
- the Packet.
- EFI_DEVICE_ERROR - Some unexpected error happened.
+ @retval EFI_DEVICE_ERROR Some unexpected error happened.
---*/
+**/
+EFI_STATUS
+IScsiExecuteScsiCommand (
+ IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *PassThru,
+ IN UINT8 *Target,
+ IN UINT64 Lun,
+ IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet
+ )
{
EFI_STATUS Status;
ISCSI_DRIVER_DATA *Private;
@@ -2923,26 +2731,20 @@ ON_EXIT: return Status;
}
-EFI_STATUS
-IScsiSessionReinstatement (
- IN ISCSI_DRIVER_DATA *Private
- )
-/*++
-
-Routine Description:
-
+/**
Reinstate the session on some error.
-Arguments:
+ @param Private[in] The iSCSI driver data.
- Private - The iSCSI driver data.
+ @retval EFI_SUCCES The session is reinstated from some error.
-Returns:
+ @retval other Reinstatement failed.
- EFI_SUCCES - The session is reinstated from some error.
- other - Reinstatement failed.
-
---*/
+**/
+EFI_STATUS
+IScsiSessionReinstatement (
+ IN ISCSI_DRIVER_DATA *Private
+ )
{
ISCSI_SESSION *Session;
EFI_STATUS Status;
@@ -2964,27 +2766,21 @@ Returns: return Status;
}
-VOID
-IScsiSessionInit (
- IN ISCSI_SESSION *Session,
- IN BOOLEAN Recovery
- )
-/*++
-
-Routine Description:
-
+/**
Initialize some session parameters before login.
-Arguments:
+ @param Session[in] The iSCSI session.
- Session - The iSCSI session.
- Recovery - Whether the request is from a fresh new start or recovery.
+ @param Recovery[in] Whether the request is from a fresh new start or recovery.
-Returns:
+ @retval None.
- None.
-
---*/
+**/
+VOID
+IScsiSessionInit (
+ IN ISCSI_SESSION *Session,
+ IN BOOLEAN Recovery
+ )
{
UINT32 Random;
@@ -3025,26 +2821,19 @@ Returns: Session->ErrorRecoveryLevel = 0;
}
-EFI_STATUS
-IScsiSessionAbort (
- IN ISCSI_SESSION *Session
- )
-/*++
-
-Routine Description:
-
+/**
Abort the iSCSI session, that is, reset all the connection and free the
resources.
-Arguments:
-
- Session - The iSCSI session.
-
-Returns:
+ @param Session[in] The iSCSI session.
- EFI_SUCCES - The session is aborted.
+ @retval EFI_SUCCES The session is aborted.
---*/
+**/
+EFI_STATUS
+IScsiSessionAbort (
+ IN ISCSI_SESSION *Session
+ )
{
ISCSI_DRIVER_DATA *Private;
ISCSI_CONNECTION *Conn;
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiProto.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiProto.h index 43a8c25f96..794ac40c3f 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiProto.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiProto.h @@ -1,4 +1,5 @@ -/*++
+/** @file
+ The header file of IScsi Protocol that defines many specific data structures.
Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -15,9 +16,9 @@ Module Name: Abstract:
- Protocol definitions for iSCSI driver, mainly from RFC3720.
+ Protocol definitions for IScsi driver, mainly from RFC3720.
---*/
+**/
#ifndef _ISCSI_PROTO_H_
#define _ISCSI_PROTO_H_
@@ -636,48 +637,153 @@ typedef struct _ISCSI_KEY_VALUE_PAIR { //
// function prototypes.
//
+/**
+ Attach the iSCSI connection to the iSCSI session.
+
+ @param Session[in] The iSCSI session.
+
+ @param Conn[in] The iSCSI connection.
+
+ @retval None.
+
+**/
VOID
IScsiAttatchConnection (
IN ISCSI_SESSION *Session,
IN ISCSI_CONNECTION *Conn
);
+/**
+ Detach the iSCSI connection from the session it belongs to.
+
+ @param Conn[in] The iSCSI connection.
+
+ @retval None.
+
+**/
VOID
IScsiDetatchConnection (
IN ISCSI_CONNECTION *Conn
);
+/**
+ This function does the iSCSI connection login.
+
+ @param Conn[in] The iSCSI connection to login.
+
+ @retval EFI_SUCCESS The iSCSI connection is logged into the iSCSI target.
+
+ @retval EFI_TIMEOUT Timeout happened during the login procedure.
+
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
+
+**/
EFI_STATUS
IScsiConnLogin (
IN ISCSI_CONNECTION *Conn
);
+/**
+ Create a TCP connection for the iSCSI session.
+
+ @param Private[in] The iSCSI driver data.
+
+ @param Session[in] Maximum CmdSN from the target.
+
+ @retval The newly created iSCSI connection.
+
+**/
ISCSI_CONNECTION *
IScsiCreateConnection (
IN ISCSI_DRIVER_DATA *Private,
IN ISCSI_SESSION *Session
);
+/**
+ Destroy an iSCSI connection.
+
+ @param Conn[in] The connection to destroy.
+
+ @retval None.
+
+**/
VOID
IScsiDestroyConnection (
IN ISCSI_CONNECTION *Conn
);
+/**
+ Login the iSCSI session.
+
+ @param Private[in] The iSCSI driver data.
+
+ @retval EFI_SUCCESS The iSCSI session login procedure finished.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
+
+**/
EFI_STATUS
IScsiSessionLogin (
IN ISCSI_DRIVER_DATA *Private
);
+/**
+ Build and send the iSCSI login request to the iSCSI target according to
+ the current login stage.
+
+ @param Conn[in] The connection in the iSCSI login phase.
+
+ @retval EFI_SUCCESS The iSCSI login request PDU is built and sent on this
+ connection.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
+
+**/
EFI_STATUS
IScsiSendLoginReq (
IN ISCSI_CONNECTION *Conn
);
+/**
+ Receive and process the iSCSI login response.
+
+ @param Conn[in] The connection in the iSCSI login phase.
+
+ @retval EFI_SUCCESS The iSCSI login response PDU is received and processed.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
+
+**/
EFI_STATUS
IScsiReceiveLoginRsp (
IN ISCSI_CONNECTION *Conn
);
+/**
+ Add an iSCSI key-value pair as a string into the data segment of the Login Request PDU.
+ The DataSegmentLength and the actual size of the net buffer containing this PDU will be
+ updated.
+
+ @param Pdu[in] The iSCSI PDU whose data segment the key-value pair will
+ be added to.
+
+ @param Key[in] The key name string.
+
+ @param Value[in] The value string.
+
+ @retval EFI_SUCCESS The key-valu pair is added to the PDU's datasegment and
+ the correspondence length fields are updated.
+
+ @retval EFI_OUT_OF_RESOURCES There is not enough space in the PDU to add the key-value
+ pair.
+
+**/
EFI_STATUS
IScsiAddKeyValuePair (
IN NET_BUF *Pdu,
@@ -685,17 +791,55 @@ IScsiAddKeyValuePair ( IN CHAR8 *Value
);
-NET_BUF *
+/**
+ Prepare the iSCSI login request to be sent according to the current login status.
+
+ @param Conn[in] The connection in the iSCSI login phase.
+
+ @retval The pointer to the net buffer containing the iSCSI login request built.
+
+**/
+NET_BUF *
IScsiPrepareLoginReq (
IN ISCSI_CONNECTION *Conn
);
+/**
+ Process the iSCSI Login Response.
+
+ @param Conn[in] The connection on which the iSCSI login response is received.
+
+ @param Pdu[in] The iSCSI login response PDU.
+
+ @retval EFI_SUCCESS The iSCSI login response PDU is processed and all check are passed.
+
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
+
+**/
EFI_STATUS
IScsiProcessLoginRsp (
IN ISCSI_CONNECTION *Conn,
IN NET_BUF *Pdu
);
+/**
+ Updated the target information according the data received in the iSCSI
+ login response with an target redirection status.
+
+ @param Session[in] The iSCSI session.
+
+ @param Data[in] The data segment which should contain the
+ TargetAddress key-value list.
+
+ @param Len[in] Length of the data.
+
+ @retval EFI_SUCCESS The target address is updated.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+ @retval EFI_NOT_FOUND The TargetAddress key is not found.
+
+**/
EFI_STATUS
IScsiUpdateTargetAddress (
IN ISCSI_SESSION *Session,
@@ -703,11 +847,43 @@ IScsiUpdateTargetAddress ( IN UINT32 Len
);
+/**
+ The callback function to free the net buffer list.
+
+ @param Arg[in] The opaque parameter.
+
+ @retval None.
+
+**/
VOID
IScsiFreeNbufList (
VOID *Arg
);
+/**
+ Receive an iSCSI response PDU. An iSCSI response PDU contains an iSCSI PDU header and
+ an optional data segment. The two parts will be put into two blocks of buffers in the
+ net buffer. The digest check will be conducted in this function if needed and the digests
+ will be trimmed from the PDU buffer.
+
+ @param Conn[in] The iSCSI connection to receive data from.
+
+ @param Pdu[out] The received iSCSI pdu.
+
+ @param Context[in] The context used to describe information on the caller provided
+ buffer to receive data segment of the iSCSI pdu, it's optional.
+
+ @param HeaderDigest[in] Whether there will be header digest received.
+
+ @param DataDigest[in] Whether there will be data digest.
+
+ @param TimeoutEvent[in] The timeout event, it's optional.
+
+ @retval EFI_SUCCESS An iSCSI pdu is received.
+
+ @retval EFI_TIMEOUT Timeout happenend.
+
+**/
EFI_STATUS
IScsiReceivePdu (
IN ISCSI_CONNECTION *Conn,
@@ -718,47 +894,143 @@ IScsiReceivePdu ( IN EFI_EVENT TimeoutEvent OPTIONAL
);
+/**
+ Check and get the result of the prameter negotiation.
+
+ @param Conn[in] The connection in iSCSI login.
+
+ @param Pdu[in] The iSCSI response PDU containing the parameter list.
+
+ @retval EFI_SUCCESS The parmeter check is passed and negotiation is finished.
+
+ @retval EFI_PROTOCOL_ERROR Some kind of iSCSI protocol error happened.
+
+**/
EFI_STATUS
IScsiCheckOpParams (
IN ISCSI_CONNECTION *Conn,
IN BOOLEAN Transit
);
+/**
+ Fill the oprational prameters.
+
+ @param Conn[in] The connection in iSCSI login.
+
+ @param Pdu[in] The iSCSI login request PDU to fill the parameters.
+
+ @retval EFI_SUCCESS The parmeters are filled into the iSCSI login request PDU.
+
+ @retval EFI_OUT_OF_RESOURCES There is not enough space in the PDU to hold the parameters.
+
+**/
EFI_STATUS
IScsiFillOpParams (
IN ISCSI_CONNECTION *Conn,
IN NET_BUF *Pdu
);
+/**
+ Pad the iSCSI AHS or data segment to an integer number of 4 byte words.
+
+ @param Pdu[in] The iSCSI pdu which contains segments to pad.
+
+ @param Len[in] The length of the last semgnet in the PDU.
+
+ @retval EFI_SUCCESS The segment is padded or no need to pad it.
+
+ @retval EFI_OUT_OF_RESOURCES There is not enough remaining free space to add the
+ padding bytes.
+
+**/
EFI_STATUS
IScsiPadSegment (
IN NET_BUF *Pdu,
IN UINT32 Len
);
-LIST_ENTRY *
+/**
+ Build a key-value list from the data segment.
+
+ @param Data[in] The data segment containing the key-value pairs.
+
+ @param Len[in] Length of the data segment.
+
+ @retval The key-value list.
+
+**/
+LIST_ENTRY *
IScsiBuildKeyValueList (
IN CHAR8 *Data,
IN UINT32 Len
);
-CHAR8 *
+/**
+ Get the value string by the key name from the key-value list. If found,
+ the key-value entry will be removed from the list.
+
+ @param KeyValueList[in] The key-value list.
+
+ @param Key[in] The key name to find.
+
+ @retval The value string.
+
+**/
+CHAR8 *
IScsiGetValueByKeyFromList (
IN LIST_ENTRY *KeyValueList,
IN CHAR8 *Key
);
+/**
+ Free the key-value list.
+
+ @param KeyValueList[in] The key-value list.
+
+ @retval None.
+
+**/
VOID
IScsiFreeKeyValueList (
IN LIST_ENTRY *KeyValueList
);
+/**
+ Normalize the iSCSI name according to RFC.
+
+ @param Name[in] The iSCSI name.
+
+ @param Len[in] length of the iSCSI name.
+
+ @retval EFI_SUCCESS The iSCSI name is valid and normalized.
+
+ @retval EFI_PROTOCOL_ERROR The iSCSI name is mal-formatted or not in the IQN format.
+
+**/
EFI_STATUS
IScsiNormalizeName (
IN CHAR8 *Name,
IN UINTN Len
);
+/**
+ Execute the SCSI command issued through the EXT SCSI PASS THRU protocol.
+
+ @param PassThru[in] The EXT SCSI PASS THRU protocol.
+
+ @param Target[in] The target ID.
+
+ @param Lun[in] The LUN.
+
+ @param Packet[in][out] The request packet containing IO request, SCSI command
+ buffer and buffers to read/write.
+
+ @retval EFI_SUCCES The SCSI command is executed and the result is updated to
+ the Packet.
+
+ @retval EFI_DEVICE_ERROR Some unexpected error happened.
+
+**/
EFI_STATUS
IScsiExecuteScsiCommand (
IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL *PassThru,
@@ -767,17 +1039,46 @@ IScsiExecuteScsiCommand ( IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET *Packet
);
+/**
+ Reinstate the session on some error.
+
+ @param Private[in] The iSCSI driver data.
+
+ @retval EFI_SUCCES The session is reinstated from some error.
+
+ @retval other Reinstatement failed.
+
+**/
EFI_STATUS
IScsiSessionReinstatement (
IN ISCSI_DRIVER_DATA *Private
);
+/**
+ Initialize some session parameters before login.
+
+ @param Session[in] The iSCSI session.
+
+ @param Recovery[in] Whether the request is from a fresh new start or recovery.
+
+ @retval None.
+
+**/
VOID
IScsiSessionInit (
IN ISCSI_SESSION *Session,
IN BOOLEAN Recovery
);
+/**
+ Abort the iSCSI session, that is, reset all the connection and free the
+ resources.
+
+ @param Session[in] The iSCSI session.
+
+ @retval EFI_SUCCES The session is aborted.
+
+**/
EFI_STATUS
IScsiSessionAbort (
IN ISCSI_SESSION *Session
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiTcp4Io.c b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiTcp4Io.c index 06caf72166..02f561e157 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiTcp4Io.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiTcp4Io.c @@ -1,4 +1,5 @@ -/*++
+/** @file
+ The wrap of TCP/IP Socket interface
Copyright (c) 2004 - 2007, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -14,37 +15,48 @@ Module Name: IScsiTcp4Io.c
Abstract:
+ The wrap of TCP/IP Socket interface
---*/
+**/
#include "IScsiImpl.h"
+/**
+ The common notify function associated with various Tcp4Io events.
+
+ @param Event[in] The event signaled.
+
+ @param Contect[in] The context.
+
+ @retval None.
+
+**/
VOID
EFIAPI
Tcp4IoCommonNotify (
IN EFI_EVENT Event,
IN VOID *Context
)
-/*++
-
-Routine Description:
+{
+ *((BOOLEAN *) Context) = TRUE;
+}
- The common notify function associated with various Tcp4Io events.
+/**
+ Create a TCP socket with the specified configuration data.
-Arguments:
+ @param Image[in] The handle of the driver image.
- Event - The event signaled.
- Contect - The context.
+ @param Controller[in] The handle of the controller.
-Returns:
+ @param ConfigData[in] The Tcp4 configuration data.
- None.
+ @param Tcp4Io[in] The Tcp4Io.
+
+ @retval EFI_SUCCESS The TCP socket is created and configured.
---*/
-{
- *((BOOLEAN *) Context) = TRUE;
-}
+ @retval Other Failed to create the TCP socket or configure it.
+**/
EFI_STATUS
Tcp4IoCreateSocket (
IN EFI_HANDLE Image,
@@ -52,25 +64,6 @@ Tcp4IoCreateSocket ( IN TCP4_IO_CONFIG_DATA *ConfigData,
IN TCP4_IO *Tcp4Io
)
-/*++
-
-Routine Description:
-
- Create a TCP socket with the specified configuration data.
-
-Arguments:
-
- Image - The handle of the driver image.
- Controller - The handle of the controller.
- ConfigData - The Tcp4 configuration data.
- Tcp4Io - The Tcp4Io.
-
-Returns:
-
- EFI_SUCCESS - The TCP socket is created and configured.
- other - Failed to create the TCP socket or configure it.
-
---*/
{
EFI_STATUS Status;
EFI_TCP4_PROTOCOL *Tcp4;
@@ -252,25 +245,18 @@ ON_ERROR: return Status;
}
-VOID
-Tcp4IoDestroySocket (
- IN TCP4_IO *Tcp4Io
- )
-/*++
-
-Routine Description:
-
+/**
Destroy the socket.
-Arguments:
+ @param[in] Tcp4Io The Tcp4Io which wraps the socket to be destroyeds.
- Tcp4Io - The Tcp4Io which wraps the socket to be destroyeds.
+ @retval None.
-Returns:
-
- None.
-
---*/
+**/
+VOID
+Tcp4IoDestroySocket (
+ IN TCP4_IO *Tcp4Io
+ )
{
EFI_TCP4_PROTOCOL *Tcp4;
@@ -297,27 +283,21 @@ Returns: );
}
-EFI_STATUS
-Tcp4IoConnect (
- IN TCP4_IO *Tcp4Io,
- IN EFI_EVENT Timeout
- )
-/*++
-
-Routine Description:
-
+/**
Connect to the other endpoint of the TCP socket.
-Arguments:
-
- Tcp4Io - The Tcp4Io wrapping the TCP socket.
- Timeout - The time to wait for connection done.
+ @param Tcp4Io[in] The Tcp4Io wrapping the TCP socket.
-Returns:
+ @param Timeout[in] The time to wait for connection done.
- None.
+ @retval None.
---*/
+**/
+EFI_STATUS
+Tcp4IoConnect (
+ IN TCP4_IO *Tcp4Io,
+ IN EFI_EVENT Timeout
+ )
{
EFI_TCP4_PROTOCOL *Tcp4;
EFI_STATUS Status;
@@ -342,25 +322,18 @@ Returns: return Status;
}
-VOID
-Tcp4IoReset (
- IN TCP4_IO *Tcp4Io
- )
-/*++
-
-Routine Description:
-
+/**
Reset the socket.
-Arguments:
-
- Tcp4Io - The Tcp4Io wrapping the TCP socket.
-
-Returns:
+ @param Tcp4Io[in] The Tcp4Io wrapping the TCP socket.
- None.
+ @retval None.
---*/
+**/
+VOID
+Tcp4IoReset (
+ IN TCP4_IO *Tcp4Io
+ )
{
EFI_STATUS Status;
EFI_TCP4_PROTOCOL *Tcp4;
@@ -379,28 +352,23 @@ Returns: }
}
-EFI_STATUS
-Tcp4IoTransmit (
- IN TCP4_IO *Tcp4Io,
- IN NET_BUF *Packet
- )
-/*++
-
-Routine Description:
-
+/**
Transmit the Packet to the other endpoint of the socket.
-Arguments:
+ @param Tcp4Io[in] The Tcp4Io wrapping the TCP socket.
- Tcp4Io - The Tcp4Io wrapping the TCP socket.
- Packet - The packet to transmit
+ @param Packet[in] The packet to transmit
-Returns:
+ @retval EFI_SUCCESS The packet is trasmitted.
- EFI_SUCCESS - The packet is trasmitted.
- EFI_OUT_OF_RESOURCES - Failed to allocate memory.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
---*/
+**/
+EFI_STATUS
+Tcp4IoTransmit (
+ IN TCP4_IO *Tcp4Io,
+ IN NET_BUF *Packet
+ )
{
EFI_TCP4_TRANSMIT_DATA *TxData;
EFI_TCP4_PROTOCOL *Tcp4;
@@ -447,35 +415,33 @@ ON_EXIT: return Status;
}
-EFI_STATUS
-Tcp4IoReceive (
- IN TCP4_IO *Tcp4Io,
- IN NET_BUF *Packet,
- IN BOOLEAN AsyncMode,
- IN EFI_EVENT Timeout
- )
-/*++
+/**
+ Receive data from the socket.
-Routine Description:
+ @param Tcp4Io[in] The Tcp4Io which wraps the socket to be destroyeds.
- Receive data from the socket.
+ @param Packet[in] The buffer to hold the data copy from the soket rx buffer.
-Arguments:
+ @param AsyncMode[in] Is this receive asyncronous or not.
- Tcp4Io - The Tcp4Io which wraps the socket to be destroyeds.
- Packet - The buffer to hold the data copy from the soket rx buffer.
- AsyncMode - Is this receive asyncronous or not.
- Timeout - The time to wait for receiving the amount of data the Packet
- can hold.
+ @param Timeout[in] The time to wait for receiving the amount of data the Packet
+ can hold.
-Returns:
+ @retval EFI_SUCCESS The required amount of data is received from the socket.
- EFI_SUCCESS - The required amount of data is received from the socket.
- EFI_OUT_OF_RESOURCES - Failed to allocate momery.
- EFI_TIMEOUT - Failed to receive the required amount of data in the
- specified time period.
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate momery.
---*/
+ @retval EFI_TIMEOUT Failed to receive the required amount of data in the
+ specified time period.
+
+**/
+EFI_STATUS
+Tcp4IoReceive (
+ IN TCP4_IO *Tcp4Io,
+ IN NET_BUF *Packet,
+ IN BOOLEAN AsyncMode,
+ IN EFI_EVENT Timeout
+ )
{
EFI_TCP4_PROTOCOL *Tcp4;
EFI_TCP4_RECEIVE_DATA RxData;
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiTcp4Io.h b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiTcp4Io.h index 2a70a6bd40..f46e8df8b3 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiTcp4Io.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiTcp4Io.h @@ -1,4 +1,5 @@ -/*++
+/**
+ IScsi Tcp4 IO related definitions.
Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -15,9 +16,9 @@ Module Name: Abstract:
- iSCSI Tcp4 IO related definitions.
+ IScsi Tcp4 IO related definitions.
---*/
+**/
#ifndef _ISCSI_TCP4_IO_H_
#define _ISCSI_TCP4_IO_H_
@@ -52,6 +53,22 @@ typedef struct _TCP4_IO { BOOLEAN IsCloseDone;
} TCP4_IO;
+/**
+ Create a TCP socket with the specified configuration data.
+
+ @param Image[in] The handle of the driver image.
+
+ @param Controller[in] The handle of the controller.
+
+ @param ConfigData[in] The Tcp4 configuration data.
+
+ @param Tcp4Io[in] The Tcp4Io.
+
+ @retval EFI_SUCCESS The TCP socket is created and configured.
+
+ @retval Other Failed to create the TCP socket or configure it.
+
+**/
EFI_STATUS
Tcp4IoCreateSocket (
IN EFI_HANDLE Image,
@@ -60,28 +77,86 @@ Tcp4IoCreateSocket ( IN TCP4_IO *Tcp4Io
);
+/**
+ Destroy the socket.
+
+ @param[in] Tcp4Io The Tcp4Io which wraps the socket to be destroyeds.
+
+ @retval None.
+
+**/
VOID
Tcp4IoDestroySocket (
IN TCP4_IO *Tcp4Io
);
+/**
+ Connect to the other endpoint of the TCP socket.
+
+ @param Tcp4Io[in] The Tcp4Io wrapping the TCP socket.
+
+ @param Timeout[in] The time to wait for connection done.
+
+ @retval None.
+
+**/
EFI_STATUS
Tcp4IoConnect (
IN TCP4_IO *Tcp4Io,
IN EFI_EVENT Timeout
);
+/**
+ Reset the socket.
+
+ @param Tcp4Io[in] The Tcp4Io wrapping the TCP socket.
+
+ @retval None.
+
+**/
VOID
Tcp4IoReset (
IN TCP4_IO *Tcp4Io
);
+/**
+ Transmit the Packet to the other endpoint of the socket.
+
+ @param Tcp4Io[in] The Tcp4Io wrapping the TCP socket.
+
+ @param Packet[in] The packet to transmit
+
+ @retval EFI_SUCCESS The packet is trasmitted.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
+
+**/
EFI_STATUS
Tcp4IoTransmit (
IN TCP4_IO *Tcp4Io,
IN NET_BUF *Packet
);
+/**
+ Receive data from the socket.
+
+ @param Tcp4Io[in] The Tcp4Io which wraps the socket to be destroyeds.
+
+ @param Packet[in] The buffer to hold the data copy from the soket rx buffer.
+
+ @param AsyncMode[in] Is this receive asyncronous or not.
+
+ @param Timeout[in] The time to wait for receiving the amount of data the Packet
+ can hold.
+
+ @retval EFI_SUCCESS The required amount of data is received from the socket.
+
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate momery.
+
+ @retval EFI_TIMEOUT Failed to receive the required amount of data in the
+ specified time period.
+
+**/
EFI_STATUS
Tcp4IoReceive (
IN TCP4_IO *Tcp4Io,
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/Md5.c b/MdeModulePkg/Universal/Network/IScsiDxe/Md5.c index a86144b207..b1aa888e24 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/Md5.c +++ b/MdeModulePkg/Universal/Network/IScsiDxe/Md5.c @@ -1,6 +1,7 @@ -/*++
+/** @file
+ Implementation of MD5 algorithm
-Copyright (c) 2004 - 2007, Intel Corporation
+Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -17,7 +18,7 @@ Abstract: Implementation of MD5 algorithm
---*/
+**/
#include "Md5.h"
@@ -122,26 +123,19 @@ STATIC CONST MD5_TRANSFORM_FUNC MD5_F[] = { TF4
};
+/**
+ Perform the MD5 transform on 64 bytes data segment
+
+ @param Md5Ctx[in] it includes the data segment for Md5 transform
+
+ @retval NONE.
+
+**/
STATIC
VOID
MD5Transform (
IN MD5_CTX *Md5Ctx
)
-/*++
-
-Routine Description:
-
- GC_TODO: Add function description
-
-Arguments:
-
- Md5Ctx - GC_TODO: add argument description
-
-Returns:
-
- GC_TODO: add return values
-
---*/
{
UINT32 i;
UINT32 j;
@@ -177,6 +171,23 @@ Returns: }
}
+/**
+ Copy data segment into the M field of MD5_CTX structure for later transform.
+ If the length of data segment is larger than 64 bytes, then does the transform
+ immediately and the generated Md5 code is stored in the States field of MD5_CTX
+ data struct for later accumulation.
+ All of Md5 code generated for the sequential 64-bytes data segaments are be
+ accumulated in MD5Final() function.
+
+ @param Md5Ctx[in] the data structure of storing the original data
+ segment and the final result.
+
+ @param Data[in] the data wanted to be transformed
+
+ @param DataLen[in] the length of data
+
+ @retval NONE.
+**/
STATIC
VOID
MD5UpdateBlock (
@@ -184,23 +195,6 @@ MD5UpdateBlock ( IN CONST UINT8 *Data,
IN UINTN DataLen
)
-/*++
-
-Routine Description:
-
- GC_TODO: Add function description
-
-Arguments:
-
- Md5Ctx - GC_TODO: add argument description
- Data - GC_TODO: add argument description
- DataLen - GC_TODO: add argument description
-
-Returns:
-
- GC_TODO: add return values
-
---*/
{
UINTN Limit;
@@ -217,25 +211,18 @@ Returns: Md5Ctx->Count += DataLen;
}
+/**
+ Initialize four 32-bits chaining variables and use them to do the Md5 transform.
+
+ @param Md5Ctx[in] the data structure of Md5
+
+ @retval EFI_SUCCESS initialization is ok
+
+**/
EFI_STATUS
MD5Init (
IN MD5_CTX *Md5Ctx
)
-/*++
-
-Routine Description:
-
- GC_TODO: Add function description
-
-Arguments:
-
- Md5Ctx - GC_TODO: add argument description
-
-Returns:
-
- EFI_SUCCESS - GC_TODO: Add description for return value
-
---*/
{
ZeroMem (Md5Ctx, sizeof (*Md5Ctx));
@@ -250,29 +237,25 @@ Returns: return EFI_SUCCESS;
}
+/**
+ the external interface of Md5 algorithm
+
+ @param Md5Ctx[in] the data structure of storing the original data
+ segment and the final result.
+
+ @param Data[in] the data wanted to be transformed.
+
+ @param DataLen[in] the length of data.
+
+ @retval EFI_SUCCESS the transform is ok.
+
+**/
EFI_STATUS
MD5Update (
IN MD5_CTX *Md5Ctx,
IN VOID *Data,
IN UINTN DataLen
)
-/*++
-
-Routine Description:
-
- GC_TODO: Add function description
-
-Arguments:
-
- Md5Ctx - GC_TODO: add argument description
- Data - GC_TODO: add argument description
- DataLen - GC_TODO: add argument description
-
-Returns:
-
- EFI_SUCCESS - GC_TODO: Add description for return value
-
---*/
{
if (EFI_ERROR (Md5Ctx->Status)) {
return Md5Ctx->Status;
@@ -283,27 +266,23 @@ Returns: return EFI_SUCCESS;
}
+/**
+ accumulate the MD5 value of every data segment and generate the finial
+ result according to MD5 algorithm
+
+ @param Md5Ctx[in] the data structure of storing the original data
+ segment and the final result.
+
+ @param HashVal[out] the final 128-bits output.
+
+ @retval EFI_SUCCESS the transform is ok.
+
+**/
EFI_STATUS
MD5Final (
IN MD5_CTX *Md5Ctx,
OUT UINT8 *HashVal
)
-/*++
-
-Routine Description:
-
- GC_TODO: Add function description
-
-Arguments:
-
- Md5Ctx - GC_TODO: add argument description
- HashVal - GC_TODO: add argument description
-
-Returns:
-
- EFI_SUCCESS - GC_TODO: Add description for return value
-
---*/
{
UINTN PadLength;
diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/Md5.h b/MdeModulePkg/Universal/Network/IScsiDxe/Md5.h index 365b5cbbe6..dd59626f37 100644 --- a/MdeModulePkg/Universal/Network/IScsiDxe/Md5.h +++ b/MdeModulePkg/Universal/Network/IScsiDxe/Md5.h @@ -1,4 +1,5 @@ -/*++
+/** @file
+ Header file for Md5
Copyright (c) 2004 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -17,7 +18,7 @@ Abstract: Header file for Md5
---*/
+**/
#ifndef _MD5_H_
#define _MD5_H_
@@ -36,73 +37,58 @@ typedef struct _MD5_CTX { UINTN Count;
} MD5_CTX;
+/**
+ Initialize four 32-bits chaining variables and use them to do the Md5 transform.
+
+ @param Md5Ctx[in] the data structure of Md5
+
+ @retval EFI_SUCCESS initialization is ok
+
+**/
EFI_STATUS
MD5Init (
IN MD5_CTX *Md5Ctx
)
-/*++
-
-Routine Description:
-
- GC_TODO: Add function description
+;
-Arguments:
+/**
+ the external interface of Md5 algorithm
- Md5Ctx - GC_TODO: add argument description
+ @param Md5Ctx[in] the data structure of storing the original data
+ segment and the final result.
-Returns:
+ @param Data[in] the data wanted to be transformed.
- EFI_SUCCESS - GC_TODO: Add description for return value
+ @param DataLen[in] the length of data.
---*/
-;
+ @retval EFI_SUCCESS the transform is ok.
+**/
EFI_STATUS
MD5Update (
IN MD5_CTX *Md5Ctx,
IN VOID *Data,
IN UINTN DataLen
)
-/*++
-
-Routine Description:
-
- GC_TODO: Add function description
-
-Arguments:
+;
- Md5Ctx - GC_TODO: add argument description
- Data - GC_TODO: add argument description
- DataLen - GC_TODO: add argument description
+/**
+ accumulate the MD5 value of every data segment and generate the finial
+ result according to MD5 algorithm
-Returns:
+ @param Md5Ctx[in] the data structure of storing the original data
+ segment and the final result.
- EFI_SUCCESS - GC_TODO: Add description for return value
+ @param HashVal[out] the final 128-bits output.
---*/
-;
+ @retval EFI_SUCCESS the transform is ok.
+**/
EFI_STATUS
MD5Final (
IN MD5_CTX *Md5Ctx,
OUT UINT8 *HashVal
)
-/*++
-
-Routine Description:
-
- GC_TODO: Add function description
-
-Arguments:
-
- Md5Ctx - GC_TODO: add argument description
- HashVal - GC_TODO: add argument description
-
-Returns:
-
- EFI_SUCCESS - GC_TODO: Add description for return value
-
---*/
;
#endif // _MD5_H
|