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

1 files changed, 174 insertions, 3 deletions

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 <ConfigRequest> 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 <MultiConfigRequest> 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 <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_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 <ConfigResp> 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 (