Add comments for the return value of GenericBdsLib functions.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8822 6f19259b-4bc3-4df7-8a09-765794883524

diff --git a/IntelFrameworkModulePkg/Include/Library/GenericBdsLib.h b/IntelFrameworkModulePkg/Include/Library/GenericBdsLib.h
index db302c986a7f002e555508d18f26a47c791734c0..37f8276afa7d1a01b9fb3b113a1f50c4d01ba340 100644 (file)
--- a/IntelFrameworkModulePkg/Include/Library/GenericBdsLib.h
+++ b/IntelFrameworkModulePkg/Include/Library/GenericBdsLib.h
@@ -20,28 +20,28 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 \r
 extern EFI_HANDLE mBdsImageHandle;\r
 \r
-//\r
-// Constants which are variable names used to access variables\r
-//\r
+///\r
+/// Constants which are variable names used to access variables\r
+///\r
 #define VAR_LEGACY_DEV_ORDER L"LegacyDevOrder"\r
 \r
-//\r
-// Data structures and defines\r
-//\r
+///\r
+/// Data structures and defines\r
+///\r
 #define FRONT_PAGE_QUESTION_ID  0x0000\r
 #define FRONT_PAGE_DATA_WIDTH   0x01\r
 \r
-//\r
-// ConnectType\r
-//\r
+///\r
+/// ConnectType\r
+///\r
 #define CONSOLE_OUT 0x00000001\r
 #define STD_ERROR   0x00000002\r
 #define CONSOLE_IN  0x00000004\r
 #define CONSOLE_ALL (CONSOLE_OUT | CONSOLE_IN | STD_ERROR)\r
 \r
-//\r
-// Load Option Attributes defined in EFI Specification\r
-//\r
+///\r
+/// Load Option Attributes\r
+///\r
 #define LOAD_OPTION_ACTIVE              0x00000001\r
 #define LOAD_OPTION_FORCE_RECONNECT     0x00000002\r
 \r
@@ -56,22 +56,19 @@ extern EFI_HANDLE mBdsImageHandle;
 \r
 #define IS_LOAD_OPTION_TYPE(_c, _Mask)  (BOOLEAN) (((_c) & (_Mask)) != 0)\r
 \r
-//\r
-// Define Maxmim characters that will be accepted\r
-//\r
+///\r
+/// Define Maxmim characters that will be accepted\r
+///\r
 #define MAX_CHAR            480\r
 #define MAX_CHAR_SIZE       (MAX_CHAR * 2)\r
 \r
-#define MIN_ALIGNMENT_SIZE  4\r
-#define ALIGN_SIZE(a)       ((a % MIN_ALIGNMENT_SIZE) ? MIN_ALIGNMENT_SIZE - (a % MIN_ALIGNMENT_SIZE) : 0)\r
-\r
-//\r
-// Define maximum characters for boot option variable "BootXXXX"\r
-//\r
+///\r
+/// Define maximum characters for boot option variable "BootXXXX"\r
+///\r
 #define BOOT_OPTION_MAX_CHAR 10\r
 \r
 //\r
-// This data structure is the part of BDS_CONNECT_ENTRY that we can hard code.\r
+// This data structure is the part of BDS_CONNECT_ENTRY\r
 //\r
 #define BDS_LOAD_OPTION_SIGNATURE SIGNATURE_32 ('B', 'd', 'C', 'O')\r
 \r
@@ -98,10 +95,6 @@ typedef struct {
   UINTN                     ConnectType;\r
 } BDS_CONSOLE_CONNECT_ENTRY;\r
 \r
-//\r
-// Lib Functions\r
-//\r
-\r
 //\r
 // Bds boot related lib functions\r
 //\r
@@ -182,6 +175,7 @@ BdsLibBootViaBootOption (
   @retval EFI_SUCCESS            Finished all the boot device enumerate and create\r
                                  the boot option base on that boot device\r
 \r
+  @retval EFI_OUT_OF_RESOURCES   Failed to enumerate the boot device and create the boot option list\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -260,15 +254,11 @@ BdsLibLoadDrivers (
   Process BootOrder, or DriverOrder variables, by calling\r
   BdsLibVariableToOption () for each UINT16 in the variables.\r
 \r
-  @param  BdsCommonOptionList   The header of the option list base on variable\r
-                                VariableName\r
-  @param  VariableName          EFI Variable name indicate the BootOrder or\r
-                                DriverOrder\r
-\r
-  @retval EFI_SUCCESS           Success create the boot option or driver option\r
-                                list\r
-  @retval EFI_OUT_OF_RESOURCES  Failed to get the boot option or driver option list\r
+  @param  BdsCommonOptionList   The header of the option list base on variable VariableName.\r
+  @param  VariableName          EFI Variable name indicate the BootOrder or DriverOrder.\r
 \r
+  @retval EFI_SUCCESS           Success create the boot option or driver option list.\r
+  @retval EFI_OUT_OF_RESOURCES  Failed to get the boot option or driver option list.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -666,12 +656,13 @@ BdsDeleteAllInvalidLegacyBootOptions (
   );\r
 \r
 /**\r
-\r
   Add the legacy boot options from BBS table if they do not exist.\r
 \r
-  @retval EFI_SUCCESS       The boot options are added successfully \r
-                            or they are already in boot options.\r
-\r
+  @retval EFI_SUCCESS          The boot options are added successfully \r
+                               or they are already in boot options.\r
+  @retval EFI_NOT_FOUND        No legacy boot options is found.\r
+  @retval EFI_OUT_OF_RESOURCE  No enough memory.\r
+  @return Other value          LegacyBoot options are not added.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -680,12 +671,14 @@ BdsAddNonExistingLegacyBootOptions (
   );\r
 \r
 /**\r
-\r
   Add the legacy boot devices from BBS table into \r
   the legacy device boot order.\r
 \r
-  @retval EFI_SUCCESS       The boot devices are added successfully.\r
-\r
+  @retval EFI_SUCCESS           The boot devices are added successfully.\r
+  @retval EFI_NOT_FOUND         The legacy boot devices are not found.\r
+  @retval EFI_OUT_OF_RESOURCES  Memmory or storage is not enough.\r
+  @retval EFI_DEVICE_ERROR      Fail to add the legacy device boot order into EFI variable\r
+                                because of hardware error.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -694,13 +687,13 @@ BdsUpdateLegacyDevOrder (
   );\r
 \r
 /**\r
-\r
   Set the boot priority for BBS entries based on boot option entry and boot order.\r
 \r
   @param  Entry             The boot option is to be checked for refresh BBS table.\r
   \r
-  @retval EFI_SUCCESS       The boot priority for BBS entries is refreshed successfully.\r
-\r
+  @retval EFI_SUCCESS           The boot priority for BBS entries is refreshed successfully.\r
+  @retval EFI_NOT_FOUND         BBS entries can't be found.\r
+  @retval EFI_OUT_OF_RESOURCES  Failed to get the legacy device boot order.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -709,15 +702,16 @@ BdsRefreshBbsTableForBoot (
   );\r
 \r
 /**\r
+  Deletete the Boot Option from EFI Variable. The Boot Order Arrray\r
+  is also updated.\r
 \r
-  Delete boot option specified by OptionNumber and adjust the boot order.\r
-\r
-  @param  OptionNumber      The boot option to be deleted.\r
-  @param  BootOrder         Boot order list to be adjusted by remove this boot option.\r
-  @param  BootOrderSize     The size of Boot order list will be modified.\r
-  \r
-  @retval EFI_SUCCESS       The boot option is deleted successfully.\r
+  @param OptionNumber    The number of Boot option want to be deleted.\r
+  @param BootOrder       The Boot Order array.\r
+  @param BootOrderSize   The size of the Boot Order Array.\r
 \r
+  @retval  EFI_SUCCESS           The Boot Option Variable was found and removed\r
+  @retval  EFI_UNSUPPORTED       The Boot Option Variable store was inaccessible\r
+  @retval  EFI_NOT_FOUND         The Boot Option Variable was not found\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -808,10 +802,9 @@ SetupResetReminder (
   );\r
 \r
 \r
-//\r
-// Define the boot option default description \r
-// NOTE: This is not defined in UEFI spec.\r
-//\r
+///\r
+/// Define the boot option default description \r
+///\r
 #define DESCRIPTION_FLOPPY        L"EFI Floppy"\r
 #define DESCRIPTION_FLOPPY_NUM    L"EFI Floppy %d"\r
 #define DESCRIPTION_DVD           L"EFI DVD/CDROM"\r
@@ -827,42 +820,43 @@ SetupResetReminder (
 #define DESCRIPTION_NON_BLOCK     L"EFI Non-Block Boot Device"\r
 #define DESCRIPTION_NON_BLOCK_NUM L"EFI Non-Block Boot Device %d"\r
 \r
-//\r
-// Define the boot type which to classify the boot option type\r
-// Different boot option type could have different boot behavior\r
-// Use their device path node (Type + SubType) as type value\r
-// The boot type here can be added according to requirement\r
-//\r
-//\r
-// ACPI boot type. For ACPI device, cannot use sub-type to distinguish device, so hardcode their value\r
-//\r
+///\r
+/// Define the boot type which to classify the boot option type\r
+/// Different boot option type could have different boot behavior\r
+/// Use their device path node (Type + SubType) as type value\r
+/// The boot type here can be added according to requirement\r
+///\r
+\r
+///\r
+/// ACPI boot type. For ACPI device, cannot use sub-type to distinguish device, so hardcode their value\r
+///\r
 #define  BDS_EFI_ACPI_FLOPPY_BOOT         0x0201\r
-//\r
-// Message boot type\r
-// If a device path of boot option only point to a message node, the boot option is message boot type\r
-//\r
+///\r
+/// Message boot type\r
+/// If a device path of boot option only point to a message node, the boot option is message boot type\r
+///\r
 #define  BDS_EFI_MESSAGE_ATAPI_BOOT       0x0301 // Type 03; Sub-Type 01\r
 #define  BDS_EFI_MESSAGE_SCSI_BOOT        0x0302 // Type 03; Sub-Type 02\r
 #define  BDS_EFI_MESSAGE_USB_DEVICE_BOOT  0x0305 // Type 03; Sub-Type 05\r
 #define  BDS_EFI_MESSAGE_SATA_BOOT        0x0318 // Type 03; Sub-Type 18\r
 #define  BDS_EFI_MESSAGE_MISC_BOOT        0x03FF\r
-//\r
-// Media boot type\r
-// If a device path of boot option contain a media node, the boot option is media boot type\r
-//\r
+///\r
+/// Media boot type\r
+/// If a device path of boot option contain a media node, the boot option is media boot type\r
+///\r
 #define  BDS_EFI_MEDIA_HD_BOOT            0x0401 // Type 04; Sub-Type 01\r
 #define  BDS_EFI_MEDIA_CDROM_BOOT         0x0402 // Type 04; Sub-Type 02\r
-//\r
-// BBS boot type\r
-// If a device path of boot option contain a BBS node, the boot option is BBS boot type\r
-//\r
+///\r
+/// BBS boot type\r
+/// If a device path of boot option contain a BBS node, the boot option is BBS boot type\r
+///\r
 #define  BDS_LEGACY_BBS_BOOT              0x0501 //  Type 05; Sub-Type 01\r
 \r
 #define  BDS_EFI_UNSUPPORT                0xFFFF\r
 \r
-//\r
-// USB host controller Programming Interface.\r
-//\r
+///\r
+/// USB host controller Programming Interface.\r
+///\r
 #define  PCI_CLASSC_PI_UHCI               0x00\r
 #define  PCI_CLASSC_PI_EHCI               0x20\r
 \r
@@ -914,7 +908,7 @@ BdsExpandPartitionPartialDevicePathToFull (
 \r
   @param  DevicePath             Device Path to a  bootable device\r
 \r
-  @retval NULL                   The media on the DevicePath is not bootable\r
+  @return  The bootable media handle. If the media on the DevicePath is not bootable, NULL will return.\r
 \r
 **/\r
 EFI_HANDLE\r

diff --git a/IntelFrameworkModulePkg/IntelFrameworkModulePkg.dec b/IntelFrameworkModulePkg/IntelFrameworkModulePkg.dec
index 9e6a9bf1caad407b1ecefe8b3d4ed917d9751648..4e8e2c423f03688904b8ae5b84c4ab034087b33a 100644 (file)
--- a/IntelFrameworkModulePkg/IntelFrameworkModulePkg.dec
+++ b/IntelFrameworkModulePkg/IntelFrameworkModulePkg.dec
@@ -131,7 +131,7 @@
   ## This PCD specifies whether PciBus supports the hot plug device.\r
   gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdPciBusHotplugDeviceSupport|TRUE|BOOLEAN|0x0001003d\r
   \r
-  ## ISA bus related PCD can be merged into one.\r
+  ## ISA bus related PCDs to support DMA, SlaveDMA and Memory feature.\r
   gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdIsaBusSupportDma|TRUE|BOOLEAN|0x00010040\r
   gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdIsaBusOnlySupportSlaveDma|FALSE|BOOLEAN|0x00010041\r
   gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdIsaBusSupportIsaMemory|TRUE|BOOLEAN|0x00010042\r

diff --git a/IntelFrameworkModulePkg/Library/GenericBdsLib/BdsBoot.c b/IntelFrameworkModulePkg/Library/GenericBdsLib/BdsBoot.c
index d0ce36e9870a9c73fe601592498641fb60596a0f..7fb6082fc858c1a571dd147a07112e85fcf0dfb6 100644 (file)
--- a/IntelFrameworkModulePkg/Library/GenericBdsLib/BdsBoot.c
+++ b/IntelFrameworkModulePkg/Library/GenericBdsLib/BdsBoot.c
@@ -912,6 +912,7 @@ BdsDeleteAllInvalidEfiBootOption (
   @retval EFI_SUCCESS            Finished all the boot device enumerate and create\r
                                  the boot option base on that boot device\r
 \r
+  @retval EFI_OUT_OF_RESOURCES   Failed to enumerate the boot device and create the boot option list\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -961,8 +962,8 @@ BdsLibEnumerateAllBootOption (
   // device from the boot order variable\r
   //\r
   if (mEnumBootDevice) {\r
-    BdsLibBuildOptionFromVar (BdsBootOptionList, L"BootOrder");\r
-    return EFI_SUCCESS;\r
+    Status = BdsLibBuildOptionFromVar (BdsBootOptionList, L"BootOrder");\r
+    return Status;\r
   }\r
   \r
   //\r
@@ -1172,10 +1173,10 @@ BdsLibEnumerateAllBootOption (
   // Make sure every boot only have one time\r
   // boot device enumerate\r
   //\r
-  BdsLibBuildOptionFromVar (BdsBootOptionList, L"BootOrder");\r
+  Status = BdsLibBuildOptionFromVar (BdsBootOptionList, L"BootOrder");\r
   mEnumBootDevice = TRUE;\r
 \r
-  return EFI_SUCCESS;\r
+  return Status;\r
 }\r
 \r
 /**\r
@@ -1302,9 +1303,9 @@ BdsLibBootNext (
   Second, check whether the device path point to a device which support SimpleFileSystemProtocol,\r
   Third, detect the the default boot file in the Media, and return the removable Media handle.\r
 \r
-  @param  DevicePath             Device Path to a  bootable device\r
+  @param  DevicePath  Device Path to a  bootable device\r
 \r
-  @retval NULL                   The media on the DevicePath is not bootable\r
+  @return  The bootable media handle. If the media on the DevicePath is not bootable, NULL will return.\r
 \r
 **/\r
 EFI_HANDLE\r

diff --git a/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BBSsupport.c b/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BBSsupport.c
index 044e1387e8e5a41defa04d44c9c7ddfa660faf56..7063aed60e886f9c49cc5a81db49b3005de5efec 100644 (file)
--- a/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BBSsupport.c
+++ b/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BBSsupport.c
@@ -675,12 +675,13 @@ BdsCreateOneLegacyBootOption (
 }\r
 \r
 /**\r
-\r
   Add the legacy boot options from BBS table if they do not exist.\r
 \r
-  @retval EFI_SUCCESS       The boot options are added successfully \r
-                            or they are already in boot options.\r
-\r
+  @retval EFI_SUCCESS          The boot options are added successfully \r
+                               or they are already in boot options.\r
+  @retval EFI_NOT_FOUND        No legacy boot options is found.\r
+  @retval EFI_OUT_OF_RESOURCE  No enough memory.\r
+  @return Other value          LegacyBoot options are not added.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -826,12 +827,12 @@ BdsFillDevOrderBuf (
   @param BbsTable        The BBS table.\r
   @param BbsCount        The BBS Count.\r
 \r
-  @retval EFI_SUCCES     The buffer is created and the EFI variable named \r
-                         VAR_LEGACY_DEV_ORDER and EfiLegacyDevOrderGuid is\r
-                         set correctly.\r
-  @return Other value if the set of EFI variable fails. Check gRT->SetVariable\r
-          for detailed information.\r
-\r
+  @retval EFI_SUCCES             The buffer is created and the EFI variable named \r
+                                 VAR_LEGACY_DEV_ORDER and EfiLegacyDevOrderGuid is\r
+                                 set correctly.\r
+  @retval EFI_OUT_OF_RESOURCES   Memmory or storage is not enough.\r
+  @retval EFI_DEVICE_ERROR       Fail to add the device order into EFI variable fail\r
+                                 because of hardware error.\r
 **/\r
 EFI_STATUS\r
 BdsCreateDevOrder (\r
@@ -968,12 +969,14 @@ BdsCreateDevOrder (
 }\r
 \r
 /**\r
-\r
   Add the legacy boot devices from BBS table into \r
   the legacy device boot order.\r
 \r
-  @retval EFI_SUCCESS       The boot devices are added successfully.\r
-\r
+  @retval EFI_SUCCESS           The boot devices are added successfully.\r
+  @retval EFI_NOT_FOUND         The legacy boot devices are not found.\r
+  @retval EFI_OUT_OF_RESOURCES  Memmory or storage is not enough.\r
+  @retval EFI_DEVICE_ERROR      Fail to add the legacy device boot order into EFI variable\r
+                                because of hardware error.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -1414,8 +1417,9 @@ BdsUpdateLegacyDevOrder (
   @param LocalBbsTable   The BBS table.\r
   @param Priority        The prority table.\r
 \r
-  @retval EFI_SUCCESS    The function completes successfully.\r
-  @retval EFI_NOT_FOUND  Failed to find device.\r
+  @retval EFI_SUCCESS           The function completes successfully.\r
+  @retval EFI_NOT_FOUND         Failed to find device.\r
+  @retval EFI_OUT_OF_RESOURCES  Failed to get the efi variable of device order.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -1526,13 +1530,13 @@ PrintBbsTable (
 }\r
 \r
 /**\r
-\r
   Set the boot priority for BBS entries based on boot option entry and boot order.\r
 \r
   @param  Entry             The boot option is to be checked for refresh BBS table.\r
   \r
-  @retval EFI_SUCCESS       The boot priority for BBS entries is refreshed successfully.\r
-  @return status of BdsSetBootPriority4SameTypeDev()\r
+  @retval EFI_SUCCESS           The boot priority for BBS entries is refreshed successfully.\r
+  @retval EFI_NOT_FOUND         BBS entries can't be found.\r
+  @retval EFI_OUT_OF_RESOURCES  Failed to get the legacy device boot order.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r

diff --git a/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.c b/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.c
index d5674e3b42d555987a82c3a1d3318b39f3ce8088..23e38b1cea20f3fcdbabe083b88471a8e846d591 100644 (file)
--- a/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.c
+++ b/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.c
@@ -1397,9 +1397,9 @@ FormSetDispatcher (
   @param BootOrder       The Boot Order array.\r
   @param BootOrderSize   The size of the Boot Order Array.\r
 \r
-  @return Other value if the Boot Option specified by OptionNumber is not deleteed succesfully.\r
-  @retval EFI_SUCCESS    If function return successfully.\r
-\r
+  @retval  EFI_SUCCESS           The Boot Option Variable was found and removed\r
+  @retval  EFI_UNSUPPORTED       The Boot Option Variable store was inaccessible\r
+  @retval  EFI_NOT_FOUND         The Boot Option Variable was not found\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r

diff --git a/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.h b/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.h
index 781c747a3517699c512c7f1d1f3da5bc7aaa8b5d..42449fb90d245ca57f405e21e3c7743b49e8fd66 100644 (file)
--- a/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.h
+++ b/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.h
@@ -55,12 +55,6 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 //\r
 #define VAR_FLAG  EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS | EFI_VARIABLE_NON_VOLATILE\r
 \r
-//\r
-// Define Maxmim characters that will be accepted\r
-//\r
-#define MAX_CHAR      480\r
-#define MAX_CHAR_SIZE (MAX_CHAR * 2)\r
-\r
 extern EFI_GUID mBootMaintGuid;\r
 extern EFI_GUID mFileExplorerGuid;\r
 extern CHAR16   mFileExplorerStorageName[];\r