From: qwang12 Date: Thu, 15 May 2008 09:14:36 +0000 (+0000) Subject: 1) Add Doxygen Comments X-Git-Tag: edk2-stable201903~21005 X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=1a6cdbd9c5661838bc4bab81d2989acd01f5a6e0 1) Add Doxygen Comments 2) Add some ASSERTs to assist debug. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5206 6f19259b-4bc3-4df7-8a09-765794883524 --- diff --git a/EdkCompatibilityPkg/Compatibility/FrameworkHiiToUefiHiiThunk/ConfigAccess.c b/EdkCompatibilityPkg/Compatibility/FrameworkHiiToUefiHiiThunk/ConfigAccess.c index 6a83c3a3b7..a0cb4112b3 100644 --- a/EdkCompatibilityPkg/Compatibility/FrameworkHiiToUefiHiiThunk/ConfigAccess.c +++ b/EdkCompatibilityPkg/Compatibility/FrameworkHiiToUefiHiiThunk/ConfigAccess.c @@ -27,6 +27,25 @@ HII_TRHUNK_CONFIG_ACCESS_PROTOCOL_INSTANCE ConfigAccessProtocolInstanceTempate = {NULL, NULL} //ConfigAccessStorageListHead }; +/** + Find and return the pointer to Package Header of the Form package + in the Framework Package List. The Framework Package List is created + by a module calling the Framework HII interface. + The Framwork Package List contains package data + generated by Intel's UEFI VFR Compiler and String gather tool. The data format + of the package data is defined by TIANO_AUTOGEN_PACKAGES_HEADER. + + If the package list contains other type of packages such as KEYBOARD_LAYOUT, + FONTS and IMAGES, the ASSERT. This is to make sure the caller is a + Framework Module which does not include packages introduced by UEFI Specification + or packages that is not supported by Thunk layer. + + @param Packages The Framework Package List + + @retval EFI_HII_PACKAGE_HEADER* Return the Package Header of + Form Package. + @retval NULL If no Form Package is found. +**/ EFI_HII_PACKAGE_HEADER * GetIfrFormSet ( IN CONST EFI_HII_PACKAGES *Packages @@ -73,6 +92,21 @@ GetIfrFormSet ( return (EFI_HII_PACKAGE_HEADER *) NULL; } +/** + This function scan EFI_IFR_VARSTORE_OP in the Form Package. + It create entries for these VARSTORE found and append the entry + to a Link List. + + If FormSetPackage is not EFI_HII_PACKAGE_FORM, then ASSERT. + If there is no linear buffer storage in this formset, then ASSERT. + + @param FormSetPackage The Form Package header. + @param BufferStorageListHead The link list for the VARSTORE found in the form package. + + @retval EFI_SUCCESS The function scan the form set and find one or more + VARSTOREs. + @retval EFI_OUT_OF_RESOURCES There is not enough memory to complete the function. +**/ EFI_STATUS GetBufferStorage ( IN CONST EFI_HII_PACKAGE_HEADER *FormSetPackage, @@ -86,6 +120,8 @@ GetBufferStorage ( EFI_IFR_VARSTORE *VarStoreOpCode; HII_TRHUNK_BUFFER_STORAGE_KEY *BufferStorageKey; + ASSERT (FormSetPackage->Type == EFI_HII_PACKAGE_FORM); + OpCodeOffset = sizeof (EFI_HII_PACKAGE_HEADER); while (OpCodeOffset < FormSetPackage->Length) { OpCodeData = (UINT8 *) FormSetPackage + OpCodeOffset; @@ -113,10 +149,24 @@ GetBufferStorage ( InsertTailList (BufferStorageListHead, &BufferStorageKey->List); } } + return EFI_SUCCESS; } - +/** + This function installs a EFI_CONFIG_ACCESS_PROTOCOL instance for a form package registered + by a module using Framework HII Protocol Interfaces. + + UEFI HII require EFI_HII_CONFIG_ACCESS_PROTOCOL to be installed on a EFI_HANDLE, so + that Setup Utility can load the Buffer Storage using this protocol. + + @param Packages The framework package list. + @param MapEntry The Thunk Layer Handle Mapping Database Entry. + + @retval EFI_SUCCESS The Config Access Protocol is installed successfully. + @retval EFI_OUT_RESOURCE There is not enough memory. + +**/ EFI_STATUS InstallDefaultUefiConfigAccessProtocol ( IN CONST EFI_HII_PACKAGES *Packages, @@ -132,12 +182,15 @@ InstallDefaultUefiConfigAccessProtocol ( sizeof (HII_TRHUNK_CONFIG_ACCESS_PROTOCOL_INSTANCE), &ConfigAccessProtocolInstanceTempate ); + ASSERT (ConfigAccessInstance != NULL); InitializeListHead (&ConfigAccessInstance->ConfigAccessBufferStorageListHead); // // We assume there is only one formset package in each Forms Package // FormSetPackage = GetIfrFormSet (Packages); + ASSERT (FormSetPackage != NULL); + Status = GetBufferStorage (FormSetPackage, &ConfigAccessInstance->ConfigAccessBufferStorageListHead); if (EFI_ERROR (Status)) { FreePool (ConfigAccessInstance); @@ -160,6 +213,17 @@ InstallDefaultUefiConfigAccessProtocol ( return EFI_SUCCESS; } +/** + + Wrap EFI_HII_CONFIG_ACCESS_PROTOCOL.RouteConfig to a call to EFI_FORM_CALLBACK_PROTOCOL.NvWrite. + + @param BufferStorageKey The key with all attributes needed to call EFI_FORM_CALLBACK_PROTOCOL.NvWrite. + @param FrameworkFormCallBack The EFI_FORM_CALLBACK_PROTOCOL registered by Framework HII module. + @param Data The data to be saved. + @param DataSize The size of data. + + @retval EFI_STATUS The status returned by the EFI_FORM_CALLBACK_PROTOCOL.NvWrite. + **/ EFI_STATUS RouteConfigToFrameworkFormCallBack ( IN HII_TRHUNK_BUFFER_STORAGE_KEY *BufferStorageKey, @@ -183,6 +247,18 @@ RouteConfigToFrameworkFormCallBack ( return Status; } +/** + Wrap the EFI_HII_CONFIG_ACCESS_PROTOCOL.ExtractConfig to a call to EFI_FORM_CALLBACK_PROTOCOL.NvRead. + + @param BufferStorageKey The key with all attributes needed to call EFI_FORM_CALLBACK_PROTOCOL.NvRead. + @param FrameworkFormCallBack The EFI_FORM_CALLBACK_PROTOCOL registered by Framework HII module. + @param Data The data read. + @param DataSize The size of data. + + @retval EFI_STATUS The status returned by the EFI_FORM_CALLBACK_PROTOCOL.NvWrite. + @retval EFI_INVALID_PARAMETER If the EFI_FORM_CALLBACK_PROTOCOL.NvRead return the size information of the data + does not match what has been recorded early in he HII_TRHUNK_BUFFER_STORAGE_KEY. + **/ EFI_STATUS ExtractConfigFromFrameworkFormCallBack ( IN HII_TRHUNK_BUFFER_STORAGE_KEY *BufferStorageKey, @@ -228,6 +304,16 @@ ExtractConfigFromFrameworkFormCallBack ( return Status; } +/** + Wrap the EFI_HII_CONFIG_ACCESS_PROTOCOL.ExtractConfig to a call to UEFI Variable Set Service. + + @param BufferStorageKey The key with all attributes needed to call a UEFI Variable Get Service. + @param Data The data read. + @param DataSize The size of data. + + @retval EFI_STATUS The status returned by the UEFI Variable Set Service. + + **/ EFI_STATUS RouteConfigToUefiVariable ( IN HII_TRHUNK_BUFFER_STORAGE_KEY *BufferStorageKey, @@ -244,6 +330,23 @@ RouteConfigToUefiVariable ( ); } + +/** + Wrap the EFI_HII_CONFIG_ACCESS_PROTOCOL.ExtractConfig to a call to UEFI Variable Get Service. + + @param BufferStorageKey The key with all attributes needed to call a UEFI Variable Get Service. + @param Data The data read. + @param DataSize The size of data. + + If the UEFI Variable Get Service return the size information of the data + does not match what has been recorded early in he HII_TRHUNK_BUFFER_STORAGE_KEY. + then ASSERT. + + @retval EFI_STATUS The status returned by the UEFI Variable Get Service. + @retval EFI_INVALID_PARAMETER If the UEFI Variable Get Service return the size information of the data + does not match what has been recorded early in he HII_TRHUNK_BUFFER_STORAGE_KEY. + **/ + EFI_STATUS ExtractConfigFromUefiVariable ( IN HII_TRHUNK_BUFFER_STORAGE_KEY *BufferStorageKey, @@ -286,7 +389,29 @@ ExtractConfigFromUefiVariable ( return Status; } - +/** + + This function implement the EFI_HII_CONFIG_ACCESS_PROTOCOL.ExtractConfig + so that data can be read from the data storage such as UEFI Variable or module's + customized storage exposed by EFI_FRAMEWORK_CALLBACK. + + @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL + @param Request A null-terminated Unicode string in format. Note that this + includes the routing information as well as the configurable name / value pairs. It is + invalid for this string to be 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 has all + values filled in for the names in the Request string. String to be allocated by the called + function. + + @retval EFI_INVALID_PARAMETER If there is no Buffer Storage for this Config Access instance. + @retval EFI_SUCCESS The setting is retrived successfully. + @retval !EFI_SUCCESS The error returned by UEFI Get Variable or Framework Form Callback Nvread. + **/ EFI_STATUS EFIAPI ThunkExtractConfig ( @@ -306,6 +431,9 @@ ThunkExtractConfig ( Data = NULL; ConfigaAccessInstance = HII_TRHUNK_CONFIG_ACCESS_PROTOCOL_INSTANCE_FROM_PROTOCOL (This); + // + // For now, only one var varstore is supported so that we don't need to parse the Configuration string. + // ListEntry = GetFirstNode (&ConfigaAccessInstance->ConfigAccessBufferStorageListHead); if (ListEntry == NULL) { ASSERT (FALSE); @@ -345,7 +473,22 @@ ThunkExtractConfig ( return Status; } - +/** + + This function implement the EFI_HII_CONFIG_ACCESS_PROTOCOL.RouteConfig + so that data can be written to the data storage such as UEFI Variable or module's + customized storage exposed by EFI_FRAMEWORK_CALLBACK. + + @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL + @param Configuration A null-terminated Unicode string in format. + @param 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_INVALID_PARAMETER If there is no Buffer Storage for this Config Access instance. + @retval EFI_SUCCESS The setting is saved successfully. + @retval !EFI_SUCCESS The error returned by UEFI Set Variable or Framework Form Callback Nvwrite. +**/ EFI_STATUS EFIAPI ThunkRouteConfig ( @@ -365,6 +508,9 @@ ThunkRouteConfig ( Data = NULL; ConfigaAccessInstance = HII_TRHUNK_CONFIG_ACCESS_PROTOCOL_INSTANCE_FROM_PROTOCOL (This); + // + // For now, only one var varstore is supported so that we don't need to parse the Configuration string. + // ListEntry = GetFirstNode (&ConfigaAccessInstance->ConfigAccessBufferStorageListHead); if (ListEntry == NULL) { ASSERT (FALSE); @@ -411,6 +557,31 @@ Done: return Status; } +/** + Wrap the EFI_HII_CONFIG_ACCESS_PROTOCOL.CallBack to EFI_FORM_CALLBACK_PROTOCOL.Callback. Therefor, + the framework HII module willl do no porting (except some porting works needed for callback for EFI_ONE_OF_OPTION opcode) + and still work with a UEFI HII SetupBrowser. + + @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. + @param Action Specifies the type of action taken by the browser. See EFI_BROWSER_ACTION_x. + @param QuestionId A unique value which is sent to the original exporting driver so that it can identify the + type of data to expect. The format of the data tends to vary based on the opcode that + generated the callback. + @param Type The type of value for the question. See EFI_IFR_TYPE_x in + EFI_IFR_ONE_OF_OPTION. + @param Value A pointer to the data being sent to the original exporting driver. The type is specified + by Type. Type EFI_IFR_TYPE_VALUE is defined in + EFI_IFR_ONE_OF_OPTION. + @param ActionRequest On return, points to the action requested by the callback function. Type + EFI_BROWSER_ACTION_REQUEST is specified in SendForm() in the Form + Browser Protocol. + + @retval EFI_UNSUPPORTED If the Framework HII module does not register Callback although it specify the opcode under + focuse to be INTERRACTIVE. + @retval EFI_SUCCESS The callback complete successfully. + @retval !EFI_SUCCESS The error code returned by EFI_FORM_CALLBACK_PROTOCOL.Callback. + + **/ EFI_STATUS EFIAPI ThunkCallback (