Add comments for library function interface.

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

2 files changed, 81 insertions, 35 deletions

diff --git a/IntelFrameworkPkg/Library/DxeSmmDriverEntryPoint/DriverEntryPoint.c b/IntelFrameworkPkg/Library/DxeSmmDriverEntryPoint/DriverEntryPoint.c
index 4283c8422b..df25c6d493 100644
--- a/IntelFrameworkPkg/Library/DxeSmmDriverEntryPoint/DriverEntryPoint.c
+++ b/IntelFrameworkPkg/Library/DxeSmmDriverEntryPoint/DriverEntryPoint.c
@@ -1,5 +1,7 @@
 /** @file

-  Entry point to a EFI/DXE driver.

+  This file implement EfiMain() for library class DxeSmmDriverEntryPoint.

+  EfiMain() is common driver entry point for all SMM driver who uses DxeSmmDriverEntryPoint

+  library class.

 

 Copyright (c) 2006, Intel Corporation<BR>

 All rights reserved. This program and the accompanying materials

diff --git a/IntelFrameworkPkg/Library/FrameworkHiiLib/HiiLib.c b/IntelFrameworkPkg/Library/FrameworkHiiLib/HiiLib.c
index 01530461a1..dd4cedddd9 100644
--- a/IntelFrameworkPkg/Library/FrameworkHiiLib/HiiLib.c
+++ b/IntelFrameworkPkg/Library/FrameworkHiiLib/HiiLib.c
@@ -10,8 +10,6 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 

-  Module Name:  HiiLib.c

-

 **/

 

 

@@ -19,15 +17,28 @@
 

 #include <Protocol/FrameworkHii.h>

 

-

 #include <Library/FrameworkHiiLib.h>

 #include <Library/DebugLib.h>

 #include <Library/MemoryAllocationLib.h>

 #include <Library/UefiBootServicesTableLib.h>

 #include <Library/BaseMemoryLib.h>

 

+

 EFI_HII_PROTOCOL *mHii = NULL;

 

+/**

+  Library constustor function for HiiLib library instance locate the

+  gEfiHiiProtocolGuid firstly, the other interface in this library

+  instance will dependent on the protocol of gEfiHiiProtocolGuid.

+  So the depex of gEfiHiiProtocolGuid is required for this library 

+  instance.

+  If protocol of gEfiHiiProtocolGuid is not installed, then ASSERT().

+  

+  @param ImageHandle  The image handle of driver module who use this library 

+                      instance.

+  @param SystemTable  Pointer to the EFI System Table.

+  @retval EFI_SUCCESS library constuctor always success.

+**/

 EFI_STATUS

 EFIAPI

 FrameworkHiiLibConstructor (

@@ -48,7 +59,18 @@ FrameworkHiiLibConstructor (
   return EFI_SUCCESS;

 }

 

-

+/**

+  This function is internal function that prepare and create

+  HII packages with given number and package's guid.

+  It is invoked by HiiAddPackages() and PreparePackages() interface.

+  If the parameter of package's number is 0, then ASSERT().

+  

+  @param NumberOfPackages  Given number of package item in a HII package list.

+  @param Guid              Given GUID of a HII package list.

+  @param Marker            Package's content list.

+  

+  @return pointer to new created HII package list.

+**/

 EFI_HII_PACKAGES *

 InternalPreparePackages (

   IN UINTN           NumberOfPackages,

@@ -78,7 +100,6 @@ InternalPreparePackages (
 

 }

 

-

 /**

   This function allocates pool for an EFI_HII_PACKAGES structure

   with enough space for the variable argument list of package pointers.

@@ -159,6 +180,18 @@ HiiLibAddPackages (
   return Status;

 }

 

+/**

+  Removes a package list from the default HII database.

+

+  If HiiHandle is NULL, then ASSERT.

+  If HiiHandle is not a valid EFI_HII_HANDLE in the default HII database, then ASSERT.

+

+  @param  HiiHandle                The handle that was previously registered to the data base that is requested for removal.

+                                             List later.

+

+  @return  VOID

+

+**/

 VOID

 EFIAPI

 HiiLibRemovePackages (

@@ -211,33 +244,22 @@ HiiLibNewString (
   return Status;

 }

 

+/**

+  Get the string given the StringId and String package Producer's Guid. The caller

+  is responsible to free the *String.

 

-EFI_STATUS

-EFIAPI

-HiiLibUpdateString (

-  IN  EFI_HII_HANDLE                  PackageList,

-  IN  EFI_STRING_ID                   StringId,

-  IN  CONST EFI_STRING                String

-  )

-{

-  FRAMEWORK_EFI_HII_HANDLE  FrameworkHiiHandle;

-  EFI_STATUS                Status;

+  If PackageList with the matching ProducerGuid is not found, then ASSERT.

+  If PackageList with the matching ProducerGuid is found but no String is

+  specified by StringId is found, then ASSERT.

 

-  FrameworkHiiHandle = (FRAMEWORK_EFI_HII_HANDLE) (UINTN) PackageList;

-  Status = mHii->NewString (

-            mHii,

-            NULL,

-            FrameworkHiiHandle,

-            &StringId,

-            String

-          );

+  @param  ProducerGuid           The Guid of String package list.

+  @param  StringId               The String ID.

+  @param  String                 The output string.

 

-  return Status;

-}

+  @retval EFI_SUCCESS            Operation is successful.

+  @retval EFI_OUT_OF_RESOURCES   There is not enought memory in the system.

 

-//

-// Just use the UEFI prototype

-//

+**/

 EFI_STATUS

 EFIAPI

 HiiLibGetStringFromToken (

@@ -249,9 +271,24 @@ HiiLibGetStringFromToken (
   return EFI_SUCCESS;  

 }

 

-//

-// Just use the UEFI prototype

-//

+/**

+  Get string specified by StringId form the HiiHandle. The caller

+  is responsible to free the *String.

+

+  If String is NULL, then ASSERT.

+  If HiiHandle could not be found in the default HII database, then ASSERT.

+  If StringId is not found in PackageList, then ASSERT.

+

+  @param  HiiHandle              The HII handle of package list.

+  @param  StringId               The String ID.

+  @param  String                 The output string.

+

+  @retval EFI_NOT_FOUND          String is not found.

+  @retval EFI_SUCCESS            Operation is successful.

+  @retval EFI_OUT_OF_RESOURCES   There is not enought memory in the system.

+  @retval EFI_INVALID_PARAMETER  The String is NULL.

+

+**/

 EFI_STATUS

 EFIAPI

 HiiLibGetStringFromHandle (

@@ -263,9 +300,16 @@ HiiLibGetStringFromHandle (
   return EFI_SUCCESS;

 }

 

-//

-// Just use the UEFI prototype

-//

+/**

+  Create the driver handle for HII driver. The protocol and 

+  Package list of this driver wili be installed into this 

+  driver handle. 

+  The implement set DriverHandle to NULL simpliy to let 

+  handle manager create a default new handle.

+  

+  @param[out] DriverHandle the pointer of driver handle

+  @return always successful.

+**/

 EFI_STATUS

 EFIAPI

 HiiLibCreateHiiDriverHandle (