From 98cf93471dc3c2bf4e277d42a88cf5d5548dc7b9 Mon Sep 17 00:00:00 2001 From: klu2 Date: Fri, 26 Dec 2008 02:22:37 +0000 Subject: Refine function comments for BdsDxe module. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7127 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Universal/BdsDxe/BootMaint/ConsoleOption.c | 2 - .../Universal/BdsDxe/BootMaint/FileExplorer.c | 4 +- .../Universal/BdsDxe/BootMaint/UpdatePage.c | 20 +++---- MdeModulePkg/Universal/BdsDxe/BootMaint/Variable.c | 39 ++++++------- .../Universal/BdsDxe/BootMngr/BootManager.c | 2 +- MdeModulePkg/Universal/BdsDxe/Capsules.c | 17 +++--- .../Universal/BdsDxe/DeviceMngr/DeviceManager.c | 8 +-- MdeModulePkg/Universal/BdsDxe/FrontPage.c | 67 ++++++++++------------ MdeModulePkg/Universal/BdsDxe/Hotkey.c | 23 ++------ MdeModulePkg/Universal/BdsDxe/HwErrRecSupport.c | 8 +-- 10 files changed, 80 insertions(+), 110 deletions(-) (limited to 'MdeModulePkg/Universal') diff --git a/MdeModulePkg/Universal/BdsDxe/BootMaint/ConsoleOption.c b/MdeModulePkg/Universal/BdsDxe/BootMaint/ConsoleOption.c index b9ffa05..0fc187a 100644 --- a/MdeModulePkg/Universal/BdsDxe/BootMaint/ConsoleOption.c +++ b/MdeModulePkg/Universal/BdsDxe/BootMaint/ConsoleOption.c @@ -18,7 +18,6 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Function creates a device path data structure that identically matches the device path passed in. - @param DevPath A pointer to a device path data structure. @return The new copy of DevPath is created to identically match the input. @@ -33,7 +32,6 @@ DevicePathInstanceDup ( /** Update Com Ports attributes from DevicePath - @param DevicePath DevicePath that contains Com ports @retval EFI_SUCCESS The update is successful. diff --git a/MdeModulePkg/Universal/BdsDxe/BootMaint/FileExplorer.c b/MdeModulePkg/Universal/BdsDxe/BootMaint/FileExplorer.c index 8a946d3..8253ded 100644 --- a/MdeModulePkg/Universal/BdsDxe/BootMaint/FileExplorer.c +++ b/MdeModulePkg/Universal/BdsDxe/BootMaint/FileExplorer.c @@ -232,7 +232,7 @@ UpdateFileExplorer ( @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. - + @retval EFI_INVALID_PARAMETER If paramter Value or ActionRequest is NULL. **/ EFI_STATUS EFIAPI @@ -259,7 +259,7 @@ FileExplorerCallback ( *ActionRequest = EFI_BROWSER_ACTION_REQUEST_NONE; // - // Retrive uncommitted data from Form Browser + // Retrieve uncommitted data from Form Browser // NvRamMap = &Private->FeFakeNvData; BufferSize = sizeof (FILE_EXPLORER_NV_DATA); diff --git a/MdeModulePkg/Universal/BdsDxe/BootMaint/UpdatePage.c b/MdeModulePkg/Universal/BdsDxe/BootMaint/UpdatePage.c index 2ffb1ff..486f2fd 100644 --- a/MdeModulePkg/Universal/BdsDxe/BootMaint/UpdatePage.c +++ b/MdeModulePkg/Universal/BdsDxe/BootMaint/UpdatePage.c @@ -114,11 +114,9 @@ UpdatePageEnd ( } /** - Clean up the dynamic opcode at label and form specified by - both LabelId. + Clean up the dynamic opcode at label and form specified by both LabelId. - @param LabelId It is both the Form ID and Label ID for - opcode deletion. + @param LabelId It is both the Form ID and Label ID for opcode deletion. @param CallbackData The BMM context data. **/ @@ -150,7 +148,7 @@ CleanUpPage ( of the file to be boot from. @retval EFI_SUCCESS The function completed successfull. - @return Other value if the boot from the file fails. + @return Other value if the boot from the file fails. **/ EFI_STATUS @@ -163,7 +161,7 @@ BootThisFile ( CHAR16 *ExitData; BDS_COMMON_OPTION *Option; - Status = gBS->AllocatePool (EfiBootServicesData, sizeof (BDS_COMMON_OPTION), (VOID **) &Option); + Option = (BDS_COMMON_OPTION *) AllocatePool (sizeof (BDS_COMMON_OPTION)); Option->Description = FileContext->FileName; Option->DevicePath = FileContext->DevicePath; Option->LoadOptionsSize = 0; @@ -562,7 +560,7 @@ UpdateOrderPage ( /** Create the dynamic page to allow user to set - the "BootNext" vaule. + the "BootNext" value. @param CallbackData The BMM context data. @@ -633,8 +631,7 @@ UpdateBootNextPage ( } /** - Create the dynamic page to allow user to set - the "TimeOut" vaule. + Create the dynamic page to allow user to set the "TimeOut" value. @param CallbackData The BMM context data. @@ -673,7 +670,7 @@ UpdateTimeOutPage ( } /** - Refresh the text mode page + Refresh the text mode page. @param CallbackData The BMM context data. @@ -778,8 +775,7 @@ UpdateConModePage ( } /** - Create the dynamic page which allows user to - set the property such as Baud Rate, Data Bits, + Create the dynamic page which allows user to set the property such as Baud Rate, Data Bits, Parity, Stop Bits, Terminal Type. @param CallbackData The BMM context data. diff --git a/MdeModulePkg/Universal/BdsDxe/BootMaint/Variable.c b/MdeModulePkg/Universal/BdsDxe/BootMaint/Variable.c index 8576e41..55af813 100644 --- a/MdeModulePkg/Universal/BdsDxe/BootMaint/Variable.c +++ b/MdeModulePkg/Universal/BdsDxe/BootMaint/Variable.c @@ -20,7 +20,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. make sure BootOrder is in valid state. @retval EFI_SUCCESS If all boot load option EFI Variables corresponding to - BM_LOAD_CONTEXT marked for deletion is deleted + BM_LOAD_CONTEXT marked for deletion is deleted. + @retval EFI_NOT_FOUND If can not find the boot option want to be deleted. @return Others If failed to update the "BootOrder" variable after deletion. **/ @@ -176,7 +177,8 @@ Var_ChangeBootOrder ( After deleting this Driver option, call Var_ChangeDriverOrder to make sure DriverOrder is in valid state. - @retval EFI_SUCCESS Load Option is successfully updated. + @retval EFI_SUCCESS Load Option is successfully updated. + @retval EFI_NOT_FOUND Fail to find the driver option want to be deleted. @return Other value than EFI_SUCCESS if failed to update "Driver Order" EFI Variable. @@ -476,8 +478,7 @@ Var_UpdateConsoleOption ( console device. @retval EFI_SUCCESS The function complete successfully. - @return The EFI variable can be saved. See gRT->SetVariable - for detail return information. + @return The EFI variable can not be saved. See gRT->SetVariable for detail return information. **/ EFI_STATUS Var_UpdateConsoleInpOption ( @@ -492,8 +493,7 @@ Var_UpdateConsoleInpOption ( console device. @retval EFI_SUCCESS The function complete successfully. - @return The EFI variable can be saved. See gRT->SetVariable - for detail return information. + @return The EFI variable can not be saved. See gRT->SetVariable for detail return information. **/ EFI_STATUS Var_UpdateConsoleOutOption ( @@ -508,8 +508,7 @@ Var_UpdateConsoleOutOption ( console device. @retval EFI_SUCCESS The function complete successfully. - @return The EFI variable can be saved. See gRT->SetVariable - for detail return information. + @return The EFI variable can not be saved. See gRT->SetVariable for detail return information. **/ EFI_STATUS Var_UpdateErrorOutOption ( @@ -586,6 +585,7 @@ Var_UpdateDriverOption ( NewMenuEntry = BOpt_CreateMenuEntry (BM_LOAD_CONTEXT_SELECT); if (NULL == NewMenuEntry) { + FreePool (Buffer); return EFI_OUT_OF_RESOURCES; } @@ -1007,10 +1007,9 @@ Var_UpdateBootOrder ( @param CallbackData The BMM context data. - @retval EFI_SUCCESS The function complete successfully. - @retval EFI_SUCCESS Not enough memory to complete the function. - @return The EFI variable can be saved. See gRT->SetVariable - for detail return information. + @retval EFI_SUCCESS The function complete successfully. + @retval EFI_OUT_OF_RESOURCES Not enough memory to complete the function. + @return The EFI variable can not be saved. See gRT->SetVariable for detail return information. **/ EFI_STATUS @@ -1076,9 +1075,9 @@ Var_UpdateDriverOrder ( @param CallbackData The context data for BMM. - @return EFI_SUCCESS The function completed successfully. - @retval EFI_NOT_FOUND If L"LegacyDevOrder" and EfiLegacyDevOrderGuid EFI Variable can be found. - + @return EFI_SUCCESS The function completed successfully. + @retval EFI_NOT_FOUND If L"LegacyDevOrder" and EfiLegacyDevOrderGuid EFI Variable can be found. + @retval EFI_OUT_OF_RESOURCES Fail to allocate memory resource **/ EFI_STATUS Var_UpdateBBSOption ( @@ -1169,7 +1168,7 @@ Var_UpdateBBSOption ( &VarSize ); - if (NULL == VarData) { + if (VarData == NULL) { return EFI_NOT_FOUND; } @@ -1192,7 +1191,7 @@ Var_UpdateBBSOption ( } NewOrder = (UINT16 *) AllocateZeroPool (DevOrder->Length - sizeof (UINT16)); - if (NULL == NewOrder) { + if (NewOrder == NULL) { FreePool (VarData); return EFI_OUT_OF_RESOURCES; } @@ -1243,7 +1242,7 @@ Var_UpdateBBSOption ( // BootOptionVar = GetLegacyBootOptionVar (CallbackData->BbsType, &Index, &OptionSize); - if (NULL != BootOptionVar) { + if (BootOptionVar != NULL) { CopyMem ( DescString, LegacyDeviceContext->Description, @@ -1263,7 +1262,7 @@ Var_UpdateBBSOption ( Attribute = (UINT32 *) Ptr; *Attribute |= LOAD_OPTION_ACTIVE; - if (0xFF == LegacyDev[0]) { + if (LegacyDev[0] == 0xFF) { // // Disable this legacy boot option // @@ -1276,7 +1275,7 @@ Var_UpdateBBSOption ( Ptr += StrSize ((CHAR16 *) Ptr); NewOptionPtr = AllocateZeroPool (NewOptionSize); - if (NULL == NewOptionPtr) { + if (NewOptionPtr == NULL) { return EFI_OUT_OF_RESOURCES; } diff --git a/MdeModulePkg/Universal/BdsDxe/BootMngr/BootManager.c b/MdeModulePkg/Universal/BdsDxe/BootMngr/BootManager.c index 459a396..d0ac2fc 100644 --- a/MdeModulePkg/Universal/BdsDxe/BootMngr/BootManager.c +++ b/MdeModulePkg/Universal/BdsDxe/BootMngr/BootManager.c @@ -1,5 +1,5 @@ /** @file - The platform boot manager reference implement + The platform boot manager reference implementation Copyright (c) 2004 - 2008, Intel Corporation.
All rights reserved. This program and the accompanying materials diff --git a/MdeModulePkg/Universal/BdsDxe/Capsules.c b/MdeModulePkg/Universal/BdsDxe/Capsules.c index 0ecf3a6..904a775 100644 --- a/MdeModulePkg/Universal/BdsDxe/Capsules.c +++ b/MdeModulePkg/Universal/BdsDxe/Capsules.c @@ -70,17 +70,16 @@ BdsLockFv ( Then call the dispatcher to dispatch drivers from them. Finally, check the status of the updates. + This function should be called by BDS in case we need to do some + sort of processing even if there is no capsule to process. We + need to do this if an earlier update went away and we need to + clear the capsule variable so on the next reset PEI does not see it and + think there is a capsule available. - @param BootMode - the current boot mode + @param BootMode the current boot mode - @retval EFI_INVALID_PARAMETER boot mode is not correct for an update - Note: - This function should be called by BDS in case we need to do some - sort of processing even if there is no capsule to process. We - need to do this if an earlier update went awry and we need to - clear the capsule variable so on the next reset PEI does not see it and - think there is a capsule available. - @retval EFI_SUCCESS There is no error when processing capsule + @retval EFI_INVALID_PARAMETER boot mode is not correct for an update + @retval EFI_SUCCESS There is no error when processing capsule **/ EFI_STATUS diff --git a/MdeModulePkg/Universal/BdsDxe/DeviceMngr/DeviceManager.c b/MdeModulePkg/Universal/BdsDxe/DeviceMngr/DeviceManager.c index 5621efd..f0e07ec 100644 --- a/MdeModulePkg/Universal/BdsDxe/DeviceMngr/DeviceManager.c +++ b/MdeModulePkg/Universal/BdsDxe/DeviceMngr/DeviceManager.c @@ -1,5 +1,5 @@ /** @file - The platform device manager reference implement + The platform device manager reference implementation Copyright (c) 2004 - 2008, Intel Corporation.
All rights reserved. This program and the accompanying materials @@ -44,7 +44,6 @@ DEVICE_MANAGER_MENU_ITEM mDeviceManagerMenuItemTable[] = { Formset. The decision by user is saved to gCallbackKey for later processing. If user set VBIOS, the new value is saved to EFI variable. - @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. @param Action Specifies the type of action taken by the browser. @param QuestionId A unique value which is sent to the original exporting driver @@ -163,7 +162,6 @@ InitializeDeviceManager ( } /** - Call the browser and display the device manager to allow user to configure the platform. @@ -171,7 +169,7 @@ InitializeDeviceManager ( section header for all class of devices, one-of opcode to set VBIOS. @retval EFI_SUCCESS Operation is successful. - @retval Other values if failed to clean up the dynamic content from HII + @return Other values if failed to clean up the dynamic content from HII database. **/ @@ -306,7 +304,7 @@ CallDeviceManager ( &gEfiGenericPlatformVariableGuid, &VideoOptionSize ); - if (NULL == VideoOption) { + if (VideoOption == NULL) { gDeviceManagerPrivate.VideoBios = 0; } else { gDeviceManagerPrivate.VideoBios = VideoOption[0]; diff --git a/MdeModulePkg/Universal/BdsDxe/FrontPage.c b/MdeModulePkg/Universal/BdsDxe/FrontPage.c index 570dcd8..44a1e08 100644 --- a/MdeModulePkg/Universal/BdsDxe/FrontPage.c +++ b/MdeModulePkg/Universal/BdsDxe/FrontPage.c @@ -42,14 +42,14 @@ FRONT_PAGE_CALLBACK_DATA gFrontPagePrivate = { or more named elements from the target driver. - @param This - Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. - @param Request - A null-terminated Unicode string in format. - @param Progress - On return, points to a character in the Request string. + @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. + @param Request A null-terminated Unicode string in format. + @param 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. - @param Results - A null-terminated Unicode string in format which + @param Results A null-terminated Unicode string in format which has all values filled in for the names in the Request string. String to be allocated by the called function. @@ -75,9 +75,9 @@ FakeExtractConfig ( This function processes the results of changes in configuration. - @param This - Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. - @param Configuration - A null-terminated Unicode string in format. - @param Progress - A pointer to a string filled in with the offset of the most + @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. + @param Configuration A null-terminated Unicode string in format. + @param 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. @@ -102,13 +102,13 @@ FakeRouteConfig ( This function processes the results of changes in configuration. - @param This - Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. - @param Action - Specifies the type of action taken by the browser. - @param QuestionId - A unique value which is sent to the original exporting driver + @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. + @param Action Specifies the type of action taken by the browser. + @param QuestionId A unique value which is sent to the original exporting driver so that it can identify the type of data to expect. - @param Type - The type of value for the question. - @param Value - A pointer to the data being sent to the original exporting driver. - @param ActionRequest - On return, points to the action requested by the callback function. + @param Type The type of value for the question. + @param Value A pointer to the data being sent to the original exporting driver. + @param ActionRequest 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. @@ -491,9 +491,9 @@ CallFrontPage ( Acquire the string associated with the ProducerGuid and return it. - @param ProducerGuid - The Guid to search the HII database for - @param Token - The token value of the string to extract - @param String - The string that is extracted + @param ProducerGuid The Guid to search the HII database for + @param Token The token value of the string to extract + @param String The string that is extracted @retval EFI_SUCCESS The function returns EFI_SUCCESS always. @@ -518,11 +518,8 @@ GetProducerString ( /** Convert Processor Frequency Data to a string - - @param ProcessorFrequency - The frequency data to process - @param String - The string that is created - - @return VOID. + @param ProcessorFrequency The frequency data to process + @param String The string that is created **/ VOID @@ -559,9 +556,8 @@ ConvertProcessorToString ( /** Convert Memory Size to a string. - - @param MemorySize - The size of the memory to process - @param String - The string that is created + @param MemorySize The size of the memory to process + @param String The string that is created **/ VOID @@ -689,13 +685,11 @@ UpdateFrontPageStrings ( /** Function waits for a given event to fire, or for an optional timeout to expire. + @param Event The event to wait for + @param Timeout An optional timeout value in 100 ns units. - @param Event The event to wait for - - @param Timeout An optional timeout value in 100 ns units. - - @retval EFI_SUCCESS Event fired before Timeout expired. - @retval EFI_TIME_OUT Timout expired before Event fired.. + @retval EFI_SUCCESS Event fired before Timeout expired. + @retval EFI_TIME_OUT Timout expired before Event fired.. **/ EFI_STATUS @@ -755,8 +749,7 @@ WaitForSingleEvent ( Function show progress bar to wait for user input. - @param TimeoutDefault - The fault time out value before the system - continue to boot. + @param TimeoutDefault The fault time out value before the system continue to boot. @retval EFI_SUCCESS User pressed some key except "Enter" @retval EFI_TIME_OUT Timout expired or user press "Enter" @@ -850,12 +843,10 @@ ShowProgress ( this is the platform reference part and can be customize. - @param TimeoutDefault - The fault time out value before the system - continue to boot. - @param ConnectAllHappened - The indicater to check if the connect all have - already happended. - - @return VOID. + @param TimeoutDefault The fault time out value before the system + continue to boot. + @param ConnectAllHappened The indicater to check if the connect all have + already happended. **/ VOID diff --git a/MdeModulePkg/Universal/BdsDxe/Hotkey.c b/MdeModulePkg/Universal/BdsDxe/Hotkey.c index 96ce6d7..9efba6d 100644 --- a/MdeModulePkg/Universal/BdsDxe/Hotkey.c +++ b/MdeModulePkg/Universal/BdsDxe/Hotkey.c @@ -23,10 +23,8 @@ VOID *mHotkeyRegistration; /** - Check if the Key Option is valid or not. - @param KeyOption The Hot Key Option to be checked. @retval TRUE The Hot Key Option is valid. @@ -67,15 +65,14 @@ IsKeyOptionValid ( } /** - Create Key#### for the given hotkey. - @param KeyOption The Hot Key Option to be added. @param KeyOptionNumber The key option number for Key#### (optional). @retval EFI_SUCCESS Register hotkey successfully. @retval EFI_INVALID_PARAMETER The hotkey option is invalid. + @retval EFI_OUT_OF_RESOURCES Fail to allocate memory resource. **/ EFI_STATUS @@ -110,7 +107,6 @@ RegisterHotkey ( // // check whether HotKey conflict with keys used by Setup Browser // - KeyOrder = BdsLibGetVariableAndSize ( VAR_KEY_ORDER, &gEfiGlobalVariableGuid, @@ -187,7 +183,7 @@ RegisterHotkey ( KeyOption ); if (EFI_ERROR (Status)) { - gBS->FreePool (KeyOrder); + FreePool (KeyOrder); return Status; } @@ -201,6 +197,7 @@ RegisterHotkey ( NewKeyOrder = AllocatePool (KeyOrderSize); if (NewKeyOrder == NULL) { + FreePool (KeyOrder); return EFI_OUT_OF_RESOURCES; } @@ -307,11 +304,10 @@ UnregisterHotkey ( This is the common notification function for HotKeys, it will be registered with SimpleTextInEx protocol interface - RegisterKeyNotify() of ConIn handle. - @param KeyData A pointer to a buffer that is filled in with the keystroke information for the key that was pressed. - @retval EFI_SUCCESS KeyData is successfully processed. + @retval EFI_SUCCESS KeyData is successfully processed. **/ EFI_STATUS @@ -427,10 +423,8 @@ HotkeyCallback ( } /** - Register the common HotKey notify function to given SimpleTextInEx protocol instance. - @param SimpleTextInEx Simple Text Input Ex protocol instance @retval EFI_SUCCESS Register hotkey notification function successfully. @@ -481,12 +475,9 @@ HotkeyRegisterNotify ( /** Callback function for SimpleTextInEx protocol install events - @param Event the event that is signaled. @param Context not used here. - @return VOID - **/ VOID EFIAPI @@ -528,14 +519,12 @@ HotkeyEvent ( } /** - Insert Key Option to hotkey list. - @param KeyOption The Hot Key Option to be added to hotkey list. - @retval EFI_SUCCESS Add to hotkey list success. - + @retval EFI_SUCCESS Add to hotkey list success. + @retval EFI_OUT_OF_RESOURCES Fail to allocate memory resource. **/ EFI_STATUS HotkeyInsertList ( diff --git a/MdeModulePkg/Universal/BdsDxe/HwErrRecSupport.c b/MdeModulePkg/Universal/BdsDxe/HwErrRecSupport.c index 9ea6dbc..3b48c37 100644 --- a/MdeModulePkg/Universal/BdsDxe/HwErrRecSupport.c +++ b/MdeModulePkg/Universal/BdsDxe/HwErrRecSupport.c @@ -22,10 +22,10 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. @param HwErrRecSupportLevel - zero value - Indicates that the platform implements no support for - Hardware Error Record Persistence. - non-zero value - Indicates that the platform implements Hardware Error - Record Persistence. + zero value: Indicates that the platform implements no support for + Hardware Error Record Persistence. + non-zero value: Indicates that the platform implements Hardware Error + Record Persistence. **/ VOID -- cgit v1.1