From e83c9064f5f83809760c84174f936bacccac1c02 Mon Sep 17 00:00:00 2001 From: lgao4 Date: Wed, 8 Jul 2009 12:06:28 +0000 Subject: [PATCH] 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 --- .../Include/Library/GenericBdsLib.h | 154 +++++++++--------- .../IntelFrameworkModulePkg.dec | 2 +- .../Library/GenericBdsLib/BdsBoot.c | 13 +- .../Universal/BdsDxe/BootMaint/BBSsupport.c | 40 +++-- .../Universal/BdsDxe/BootMaint/BootMaint.c | 6 +- .../Universal/BdsDxe/BootMaint/BootMaint.h | 6 - 6 files changed, 107 insertions(+), 114 deletions(-) diff --git a/IntelFrameworkModulePkg/Include/Library/GenericBdsLib.h b/IntelFrameworkModulePkg/Include/Library/GenericBdsLib.h index db302c986a..37f8276afa 100644 --- 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. extern EFI_HANDLE mBdsImageHandle; -// -// Constants which are variable names used to access variables -// +/// +/// Constants which are variable names used to access variables +/// #define VAR_LEGACY_DEV_ORDER L"LegacyDevOrder" -// -// Data structures and defines -// +/// +/// Data structures and defines +/// #define FRONT_PAGE_QUESTION_ID 0x0000 #define FRONT_PAGE_DATA_WIDTH 0x01 -// -// ConnectType -// +/// +/// ConnectType +/// #define CONSOLE_OUT 0x00000001 #define STD_ERROR 0x00000002 #define CONSOLE_IN 0x00000004 #define CONSOLE_ALL (CONSOLE_OUT | CONSOLE_IN | STD_ERROR) -// -// Load Option Attributes defined in EFI Specification -// +/// +/// Load Option Attributes +/// #define LOAD_OPTION_ACTIVE 0x00000001 #define LOAD_OPTION_FORCE_RECONNECT 0x00000002 @@ -56,22 +56,19 @@ extern EFI_HANDLE mBdsImageHandle; #define IS_LOAD_OPTION_TYPE(_c, _Mask) (BOOLEAN) (((_c) & (_Mask)) != 0) -// -// Define Maxmim characters that will be accepted -// +/// +/// Define Maxmim characters that will be accepted +/// #define MAX_CHAR 480 #define MAX_CHAR_SIZE (MAX_CHAR * 2) -#define MIN_ALIGNMENT_SIZE 4 -#define ALIGN_SIZE(a) ((a % MIN_ALIGNMENT_SIZE) ? MIN_ALIGNMENT_SIZE - (a % MIN_ALIGNMENT_SIZE) : 0) - -// -// Define maximum characters for boot option variable "BootXXXX" -// +/// +/// Define maximum characters for boot option variable "BootXXXX" +/// #define BOOT_OPTION_MAX_CHAR 10 // -// This data structure is the part of BDS_CONNECT_ENTRY that we can hard code. +// This data structure is the part of BDS_CONNECT_ENTRY // #define BDS_LOAD_OPTION_SIGNATURE SIGNATURE_32 ('B', 'd', 'C', 'O') @@ -98,10 +95,6 @@ typedef struct { UINTN ConnectType; } BDS_CONSOLE_CONNECT_ENTRY; -// -// Lib Functions -// - // // Bds boot related lib functions // @@ -182,6 +175,7 @@ BdsLibBootViaBootOption ( @retval EFI_SUCCESS Finished all the boot device enumerate and create the boot option base on that boot device + @retval EFI_OUT_OF_RESOURCES Failed to enumerate the boot device and create the boot option list **/ EFI_STATUS EFIAPI @@ -260,15 +254,11 @@ BdsLibLoadDrivers ( Process BootOrder, or DriverOrder variables, by calling BdsLibVariableToOption () for each UINT16 in the variables. - @param BdsCommonOptionList The header of the option list base on variable - VariableName - @param VariableName EFI Variable name indicate the BootOrder or - DriverOrder - - @retval EFI_SUCCESS Success create the boot option or driver option - list - @retval EFI_OUT_OF_RESOURCES Failed to get the boot option or driver option list + @param BdsCommonOptionList The header of the option list base on variable VariableName. + @param VariableName EFI Variable name indicate the BootOrder or DriverOrder. + @retval EFI_SUCCESS Success create the boot option or driver option list. + @retval EFI_OUT_OF_RESOURCES Failed to get the boot option or driver option list. **/ EFI_STATUS EFIAPI @@ -666,12 +656,13 @@ BdsDeleteAllInvalidLegacyBootOptions ( ); /** - Add the legacy boot options from BBS table if they do not exist. - @retval EFI_SUCCESS The boot options are added successfully - or they are already in boot options. - + @retval EFI_SUCCESS The boot options are added successfully + or they are already in boot options. + @retval EFI_NOT_FOUND No legacy boot options is found. + @retval EFI_OUT_OF_RESOURCE No enough memory. + @return Other value LegacyBoot options are not added. **/ EFI_STATUS EFIAPI @@ -680,12 +671,14 @@ BdsAddNonExistingLegacyBootOptions ( ); /** - Add the legacy boot devices from BBS table into the legacy device boot order. - @retval EFI_SUCCESS The boot devices are added successfully. - + @retval EFI_SUCCESS The boot devices are added successfully. + @retval EFI_NOT_FOUND The legacy boot devices are not found. + @retval EFI_OUT_OF_RESOURCES Memmory or storage is not enough. + @retval EFI_DEVICE_ERROR Fail to add the legacy device boot order into EFI variable + because of hardware error. **/ EFI_STATUS EFIAPI @@ -694,13 +687,13 @@ BdsUpdateLegacyDevOrder ( ); /** - Set the boot priority for BBS entries based on boot option entry and boot order. @param Entry The boot option is to be checked for refresh BBS table. - @retval EFI_SUCCESS The boot priority for BBS entries is refreshed successfully. - + @retval EFI_SUCCESS The boot priority for BBS entries is refreshed successfully. + @retval EFI_NOT_FOUND BBS entries can't be found. + @retval EFI_OUT_OF_RESOURCES Failed to get the legacy device boot order. **/ EFI_STATUS EFIAPI @@ -709,15 +702,16 @@ BdsRefreshBbsTableForBoot ( ); /** + Deletete the Boot Option from EFI Variable. The Boot Order Arrray + is also updated. - Delete boot option specified by OptionNumber and adjust the boot order. - - @param OptionNumber The boot option to be deleted. - @param BootOrder Boot order list to be adjusted by remove this boot option. - @param BootOrderSize The size of Boot order list will be modified. - - @retval EFI_SUCCESS The boot option is deleted successfully. + @param OptionNumber The number of Boot option want to be deleted. + @param BootOrder The Boot Order array. + @param BootOrderSize The size of the Boot Order Array. + @retval EFI_SUCCESS The Boot Option Variable was found and removed + @retval EFI_UNSUPPORTED The Boot Option Variable store was inaccessible + @retval EFI_NOT_FOUND The Boot Option Variable was not found **/ EFI_STATUS EFIAPI @@ -808,10 +802,9 @@ SetupResetReminder ( ); -// -// Define the boot option default description -// NOTE: This is not defined in UEFI spec. -// +/// +/// Define the boot option default description +/// #define DESCRIPTION_FLOPPY L"EFI Floppy" #define DESCRIPTION_FLOPPY_NUM L"EFI Floppy %d" #define DESCRIPTION_DVD L"EFI DVD/CDROM" @@ -827,42 +820,43 @@ SetupResetReminder ( #define DESCRIPTION_NON_BLOCK L"EFI Non-Block Boot Device" #define DESCRIPTION_NON_BLOCK_NUM L"EFI Non-Block Boot Device %d" -// -// Define the boot type which to classify the boot option type -// Different boot option type could have different boot behavior -// Use their device path node (Type + SubType) as type value -// The boot type here can be added according to requirement -// -// -// ACPI boot type. For ACPI device, cannot use sub-type to distinguish device, so hardcode their value -// +/// +/// Define the boot type which to classify the boot option type +/// Different boot option type could have different boot behavior +/// Use their device path node (Type + SubType) as type value +/// The boot type here can be added according to requirement +/// + +/// +/// ACPI boot type. For ACPI device, cannot use sub-type to distinguish device, so hardcode their value +/// #define BDS_EFI_ACPI_FLOPPY_BOOT 0x0201 -// -// Message boot type -// If a device path of boot option only point to a message node, the boot option is message boot type -// +/// +/// Message boot type +/// If a device path of boot option only point to a message node, the boot option is message boot type +/// #define BDS_EFI_MESSAGE_ATAPI_BOOT 0x0301 // Type 03; Sub-Type 01 #define BDS_EFI_MESSAGE_SCSI_BOOT 0x0302 // Type 03; Sub-Type 02 #define BDS_EFI_MESSAGE_USB_DEVICE_BOOT 0x0305 // Type 03; Sub-Type 05 #define BDS_EFI_MESSAGE_SATA_BOOT 0x0318 // Type 03; Sub-Type 18 #define BDS_EFI_MESSAGE_MISC_BOOT 0x03FF -// -// Media boot type -// If a device path of boot option contain a media node, the boot option is media boot type -// +/// +/// Media boot type +/// If a device path of boot option contain a media node, the boot option is media boot type +/// #define BDS_EFI_MEDIA_HD_BOOT 0x0401 // Type 04; Sub-Type 01 #define BDS_EFI_MEDIA_CDROM_BOOT 0x0402 // Type 04; Sub-Type 02 -// -// BBS boot type -// If a device path of boot option contain a BBS node, the boot option is BBS boot type -// +/// +/// BBS boot type +/// If a device path of boot option contain a BBS node, the boot option is BBS boot type +/// #define BDS_LEGACY_BBS_BOOT 0x0501 // Type 05; Sub-Type 01 #define BDS_EFI_UNSUPPORT 0xFFFF -// -// USB host controller Programming Interface. -// +/// +/// USB host controller Programming Interface. +/// #define PCI_CLASSC_PI_UHCI 0x00 #define PCI_CLASSC_PI_EHCI 0x20 @@ -914,7 +908,7 @@ BdsExpandPartitionPartialDevicePathToFull ( @param DevicePath Device Path to a bootable device - @retval NULL The media on the DevicePath is not bootable + @return The bootable media handle. If the media on the DevicePath is not bootable, NULL will return. **/ EFI_HANDLE diff --git a/IntelFrameworkModulePkg/IntelFrameworkModulePkg.dec b/IntelFrameworkModulePkg/IntelFrameworkModulePkg.dec index 9e6a9bf1ca..4e8e2c423f 100644 --- a/IntelFrameworkModulePkg/IntelFrameworkModulePkg.dec +++ b/IntelFrameworkModulePkg/IntelFrameworkModulePkg.dec @@ -131,7 +131,7 @@ ## This PCD specifies whether PciBus supports the hot plug device. gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdPciBusHotplugDeviceSupport|TRUE|BOOLEAN|0x0001003d - ## ISA bus related PCD can be merged into one. + ## ISA bus related PCDs to support DMA, SlaveDMA and Memory feature. gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdIsaBusSupportDma|TRUE|BOOLEAN|0x00010040 gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdIsaBusOnlySupportSlaveDma|FALSE|BOOLEAN|0x00010041 gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdIsaBusSupportIsaMemory|TRUE|BOOLEAN|0x00010042 diff --git a/IntelFrameworkModulePkg/Library/GenericBdsLib/BdsBoot.c b/IntelFrameworkModulePkg/Library/GenericBdsLib/BdsBoot.c index d0ce36e987..7fb6082fc8 100644 --- 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 the boot option base on that boot device + @retval EFI_OUT_OF_RESOURCES Failed to enumerate the boot device and create the boot option list **/ EFI_STATUS EFIAPI @@ -961,8 +962,8 @@ BdsLibEnumerateAllBootOption ( // device from the boot order variable // if (mEnumBootDevice) { - BdsLibBuildOptionFromVar (BdsBootOptionList, L"BootOrder"); - return EFI_SUCCESS; + Status = BdsLibBuildOptionFromVar (BdsBootOptionList, L"BootOrder"); + return Status; } // @@ -1172,10 +1173,10 @@ BdsLibEnumerateAllBootOption ( // Make sure every boot only have one time // boot device enumerate // - BdsLibBuildOptionFromVar (BdsBootOptionList, L"BootOrder"); + Status = BdsLibBuildOptionFromVar (BdsBootOptionList, L"BootOrder"); mEnumBootDevice = TRUE; - return EFI_SUCCESS; + return Status; } /** @@ -1302,9 +1303,9 @@ BdsLibBootNext ( Second, check whether the device path point to a device which support SimpleFileSystemProtocol, Third, detect the the default boot file in the Media, and return the removable Media handle. - @param DevicePath Device Path to a bootable device + @param DevicePath Device Path to a bootable device - @retval NULL The media on the DevicePath is not bootable + @return The bootable media handle. If the media on the DevicePath is not bootable, NULL will return. **/ EFI_HANDLE diff --git a/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BBSsupport.c b/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BBSsupport.c index 044e1387e8..7063aed60e 100644 --- a/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BBSsupport.c +++ b/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BBSsupport.c @@ -675,12 +675,13 @@ BdsCreateOneLegacyBootOption ( } /** - Add the legacy boot options from BBS table if they do not exist. - @retval EFI_SUCCESS The boot options are added successfully - or they are already in boot options. - + @retval EFI_SUCCESS The boot options are added successfully + or they are already in boot options. + @retval EFI_NOT_FOUND No legacy boot options is found. + @retval EFI_OUT_OF_RESOURCE No enough memory. + @return Other value LegacyBoot options are not added. **/ EFI_STATUS EFIAPI @@ -826,12 +827,12 @@ BdsFillDevOrderBuf ( @param BbsTable The BBS table. @param BbsCount The BBS Count. - @retval EFI_SUCCES The buffer is created and the EFI variable named - VAR_LEGACY_DEV_ORDER and EfiLegacyDevOrderGuid is - set correctly. - @return Other value if the set of EFI variable fails. Check gRT->SetVariable - for detailed information. - + @retval EFI_SUCCES The buffer is created and the EFI variable named + VAR_LEGACY_DEV_ORDER and EfiLegacyDevOrderGuid is + set correctly. + @retval EFI_OUT_OF_RESOURCES Memmory or storage is not enough. + @retval EFI_DEVICE_ERROR Fail to add the device order into EFI variable fail + because of hardware error. **/ EFI_STATUS BdsCreateDevOrder ( @@ -968,12 +969,14 @@ BdsCreateDevOrder ( } /** - Add the legacy boot devices from BBS table into the legacy device boot order. - @retval EFI_SUCCESS The boot devices are added successfully. - + @retval EFI_SUCCESS The boot devices are added successfully. + @retval EFI_NOT_FOUND The legacy boot devices are not found. + @retval EFI_OUT_OF_RESOURCES Memmory or storage is not enough. + @retval EFI_DEVICE_ERROR Fail to add the legacy device boot order into EFI variable + because of hardware error. **/ EFI_STATUS EFIAPI @@ -1414,8 +1417,9 @@ BdsUpdateLegacyDevOrder ( @param LocalBbsTable The BBS table. @param Priority The prority table. - @retval EFI_SUCCESS The function completes successfully. - @retval EFI_NOT_FOUND Failed to find device. + @retval EFI_SUCCESS The function completes successfully. + @retval EFI_NOT_FOUND Failed to find device. + @retval EFI_OUT_OF_RESOURCES Failed to get the efi variable of device order. **/ EFI_STATUS @@ -1526,13 +1530,13 @@ PrintBbsTable ( } /** - Set the boot priority for BBS entries based on boot option entry and boot order. @param Entry The boot option is to be checked for refresh BBS table. - @retval EFI_SUCCESS The boot priority for BBS entries is refreshed successfully. - @return status of BdsSetBootPriority4SameTypeDev() + @retval EFI_SUCCESS The boot priority for BBS entries is refreshed successfully. + @retval EFI_NOT_FOUND BBS entries can't be found. + @retval EFI_OUT_OF_RESOURCES Failed to get the legacy device boot order. **/ EFI_STATUS EFIAPI diff --git a/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.c b/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.c index d5674e3b42..23e38b1cea 100644 --- 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. @param BootOrderSize The size of the Boot Order Array. - @return Other value if the Boot Option specified by OptionNumber is not deleteed succesfully. - @retval EFI_SUCCESS If function return successfully. - + @retval EFI_SUCCESS The Boot Option Variable was found and removed + @retval EFI_UNSUPPORTED The Boot Option Variable store was inaccessible + @retval EFI_NOT_FOUND The Boot Option Variable was not found **/ EFI_STATUS EFIAPI diff --git a/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.h b/IntelFrameworkModulePkg/Universal/BdsDxe/BootMaint/BootMaint.h index 781c747a35..42449fb90d 100644 --- 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. // #define VAR_FLAG EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS | EFI_VARIABLE_NON_VOLATILE -// -// Define Maxmim characters that will be accepted -// -#define MAX_CHAR 480 -#define MAX_CHAR_SIZE (MAX_CHAR * 2) - extern EFI_GUID mBootMaintGuid; extern EFI_GUID mFileExplorerGuid; extern CHAR16 mFileExplorerStorageName[]; -- 2.39.2