Add porting Guide to obsolete Edk Library interfaces.

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

diff --git a/Tools/Conf/Migration/R8Lib.c b/Tools/Conf/Migration/R8Lib.c
index dcc083c0d7b023a80b1ed68128d6d361f36d26d4..6a838869051100d89642d43e1f727bda0c587659 100644 (file)
--- a/Tools/Conf/Migration/R8Lib.c
+++ b/Tools/Conf/Migration/R8Lib.c
@@ -49,8 +49,19 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

-  //EfiInitializeDriverLib (ImageHandle, SystemTable);\r
-\r
+  //\r
+  // Porting Guide:\r
+  // This obsolete Edk library interface installs driver binding protocol.\r
+  // If the entry point of that module only invoke this function, it can\r
+  // use UefiDriverModuleLib in MdePkg and expose "DriverBinding" protocol interface\r
+  // at the <Externs> tag, build tool will auto generate code to handle it.\r
+  // For example:\r
+  // <Externs>\r
+  //   <Extern>\r
+  //     <DriverBinding>gFatDriverBinding</DriverBinding>\r
+  //   </Extern>\r
+  // </Externs>\r
+  //\r

   DriverBinding->ImageHandle          = ImageHandle;\r
 \r
   DriverBinding->DriverBindingHandle  = DriverBindingHandle;\r
   DriverBinding->ImageHandle          = ImageHandle;\r
 \r
   DriverBinding->DriverBindingHandle  = DriverBindingHandle;\r


@@ -110,6 +121,24 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This obsolete Edk library interface installs driver binding protocol\r
+  // with optional component name, driver configuration & driver diagnotics protocols.\r
+  // If the entry point of that module only invoke this function, it can\r
+  // use UefiDriverModuleLib in MdePkg and expose "DriverBinding", "ComponentName",\r
+  // "DriverConfiguration" and "DriverDiagnostics" protocol interfaces.\r
+  // at the <Externs> tag, build tool will auto generate code to handle it.\r
+  // For example:\r
+  //  <Externs>\r
+  //    <Extern>\r
+  //      <DriverBinding>gFatDriverBinding</DriverBinding>\r
+  //    </Extern>\r
+  //    <Extern>\r
+  //      <ComponentName>gFatComponentName</ComponentName>\r
+  //    </Extern>\r
+  //  </Externs>\r
+  //\r

   EFI_STATUS  Status;\r
 \r
   Status = R8_EfiLibInstallDriverBinding (ImageHandle, SystemTable, DriverBinding, DriverBindingHandle);\r
   EFI_STATUS  Status;\r
 \r
   Status = R8_EfiLibInstallDriverBinding (ImageHandle, SystemTable, DriverBinding, DriverBindingHandle);\r


@@ -181,6 +210,11 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  //\r

   UINTN Index;\r
 \r
   for (Index = 0; Index < 3; Index++) {\r
   UINTN Index;\r
 \r
   for (Index = 0; Index < 3; Index++) {\r


@@ -221,6 +255,11 @@ R8_BufToHexString (
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  //\r

   UINTN       Idx;\r
   UINT8       Byte;\r
   UINTN       StrLen;\r
   UINTN       Idx;\r
   UINT8       Byte;\r
   UINTN       StrLen;\r


@@ -275,6 +314,11 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  //\r

   CHAR16  *p1;\r
   CHAR16  *p2;\r
   \r
   CHAR16  *p1;\r
   CHAR16  *p2;\r
   \r


@@ -344,6 +388,14 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // Edk II BasePrintLib function UnicodeValueToString does not support \r
+  // to convert Value to Hex String. \r
+  // Include the source code to user code or use the full PrintLib funtion \r
+  // UnicodeVSPrintAsciiFormat (Buffer, MAXIMUM_VALUE_CHARACTERS, "%x", Value) instead.\r
+  //\r
+\r

   CHAR16  TempBuffer[MAXIMUM_VALUE_CHARACTERS];\r
   CHAR16  *TempStr;\r
   CHAR16  Prefix;\r
   CHAR16  TempBuffer[MAXIMUM_VALUE_CHARACTERS];\r
   CHAR16  *TempStr;\r
   CHAR16  Prefix;\r


@@ -436,6 +488,12 @@ R8_HexStringToBuf (
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  //\r
+\r

   UINTN       HexCnt;\r
   UINTN       Idx;\r
   UINTN       BufferLength;\r
   UINTN       HexCnt;\r
   UINTN       Idx;\r
   UINTN       BufferLength;\r


@@ -515,6 +573,12 @@ R8_IsHexDigit (
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  //\r
+\r

   if ((Char >= L'0') && (Char <= L'9')) {\r
     *Digit = (UINT8) (Char - L'0');\r
     return TRUE;\r
   if ((Char >= L'0') && (Char <= L'9')) {\r
     *Digit = (UINT8) (Char - L'0');\r
     return TRUE;\r


@@ -552,6 +616,12 @@ R8_NibbleToHexChar (
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  //\r
+\r

   Nibble &= 0x0F;\r
   if (Nibble <= 0x9) {\r
     return (CHAR16)(Nibble + L'0');\r
   Nibble &= 0x0F;\r
   if (Nibble <= 0x9) {\r
     return (CHAR16)(Nibble + L'0');\r


@@ -585,6 +655,14 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // Edk II HobLib GetNextHob () is an equivelent function with the following exceptions:\r
+  // 1. GetNextHob () does not allow NULL value as the argument of HobStart by ASSERT ()  \r
+  // 2. GetNextHob () will return NULL instead of returning HobStart when such kind of\r
+  //    HOB can be retrieved, so caller does not need to re-check the return HOB type any longer.\r
+  //\r
+\r

   VOID    *Hob;\r
   //\r
   // Return input if not found\r
   VOID    *Hob;\r
   //\r
   // Return input if not found\r


@@ -622,6 +700,11 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  //\r

   EFI_PEI_HOB_POINTERS  Hob;\r
   UINTN                 Size;\r
 \r
   EFI_PEI_HOB_POINTERS  Hob;\r
   UINTN                 Size;\r
 \r


@@ -660,6 +743,12 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  //\r
+\r

   EFI_PEI_HOB_POINTERS  Hob;\r
 \r
   Hob.Raw = HobStart;\r
   EFI_PEI_HOB_POINTERS  Hob;\r
 \r
   Hob.Raw = HobStart;\r


@@ -693,6 +782,20 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  // In fact, since EFI_HANDOFF_HOB must be the first Hob,\r
+  // the following code can retrieve boot mode.\r
+  //\r
+  // EFI_HOB_HANDOFF_INFO_TABLE *HandOffHob;\r
+  //\r
+  // HandOffHob = GetHobList ();  \r
+  // ASSERT (HandOffHob->Header.HobType = EFI_HOB_TYPE_HANDOFF);\r
+  // \r
+  // BootMode = HandOffHob->BootMode;\r
+  //\r

   EFI_PEI_HOB_POINTERS  Hob;\r
 \r
   Hob.Raw = HobStart;\r
   EFI_PEI_HOB_POINTERS  Hob;\r
 \r
   Hob.Raw = HobStart;\r


@@ -735,6 +838,21 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  // If Cpu HOB info is indispensable, user is able to ASSERT ()\r
+  // first to save error handling code\r
+  // For example:\r
+  //\r
+  // EFI_HOB_CPU  *CpuHob;\r
+  // \r
+  // CpuHob = GetHob (EFI_HOB_TYPE_CPU, HobStart);\r
+  // ASSERT (CpuHob != NULL);\r
+  // \r
+  // ...\r
+  // \r

   EFI_HOB_CPU  *CpuHob;\r
 \r
   CpuHob = GetHob (EFI_HOB_TYPE_CPU, HobStart);\r
   EFI_HOB_CPU  *CpuHob;\r
 \r
   CpuHob = GetHob (EFI_HOB_TYPE_CPU, HobStart);\r


@@ -778,29 +896,27 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  // \r

   EFI_PEI_HOB_POINTERS  DxeCoreHob;\r
   \r
   EFI_PEI_HOB_POINTERS  DxeCoreHob;\r
   \r

-  DxeCoreHob.Raw  = HobStart;\r
-  DxeCoreHob.Raw  = GetHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, DxeCoreHob.Raw);\r
-  while (DxeCoreHob.Header->HobType == EFI_HOB_TYPE_MEMORY_ALLOCATION && \r
-         !EfiCompareGuid (&DxeCoreHob.MemoryAllocationModule->MemoryAllocationHeader.Name, \r
-                          &gEfiHobMemeryAllocModuleGuid)) {\r
-\r
-    DxeCoreHob.Raw  = GET_NEXT_HOB (DxeCoreHob);\r
-    DxeCoreHob.Raw  = GetHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, DxeCoreHob.Raw);\r
-\r
-  }\r
-\r
-  if (DxeCoreHob.Header->HobType != EFI_HOB_TYPE_MEMORY_ALLOCATION) {\r
-    return EFI_NOT_FOUND;\r
+  for (DxeCoreHob.Raw = HobStart; \r
+      (DxeCoreHob.Raw = GetNextHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, DxeCoreHob.Raw)) != NULL;\r
+       DxeCoreHob.Raw = GET_NEXT_HOB (DxeCoreHob)) {\r
+    if (CompareGuid (&DxeCoreHob.MemoryAllocationModule->MemoryAllocationHeader.Name, \r
+                      &gEfiHobMemeryAllocModuleGuid)) {\r
+        *BaseAddress  = DxeCoreHob.MemoryAllocationModule->MemoryAllocationHeader.MemoryBaseAddress;\r
+        *Length       = DxeCoreHob.MemoryAllocationModule->MemoryAllocationHeader.MemoryLength;\r
+        *EntryPoint   = (VOID *) (UINTN) DxeCoreHob.MemoryAllocationModule->EntryPoint;\r
+        *FileName     = &DxeCoreHob.MemoryAllocationModule->ModuleName;\r
+        return EFI_SUCCESS;\r
+    }\r

   }\r
 \r
   }\r
 \r

-  *BaseAddress  = DxeCoreHob.MemoryAllocationModule->MemoryAllocationHeader.MemoryBaseAddress;\r
-  *Length       = DxeCoreHob.MemoryAllocationModule->MemoryAllocationHeader.MemoryLength;\r
-  *EntryPoint   = (VOID *) (UINTN) DxeCoreHob.MemoryAllocationModule->EntryPoint;\r
-  *FileName     = &DxeCoreHob.MemoryAllocationModule->ModuleName;\r
-\r
-  return EFI_SUCCESS;\r
+  return EFI_NOT_FOUND;\r

 }\r
 ////~\r
 \r
 }\r
 ////~\r
 \r


@@ -833,6 +949,25 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  // Pay attention that caller is REQUIRED to update HobStart with:\r
+  // *HobStart =  GET_NEXT_HOB (FirmwareVolumeHob)\r
+  //\r
+  // If FV HOB info is indispensable, user is able to ASSERT ()\r
+  // first to save error handling code\r
+  // For example:\r
+  //\r
+  // EFI_HOB_FIRMWARE_VOLUME  *FirmwareVolumeHob;\r
+  // \r
+  // FirmwareVolumeHob = GetHob (EFI_HOB_TYPE_FV, HobStart);\r
+  // ASSERT (FirmwareVolumeHob != NULL);\r
+  // \r
+  // ...\r
+  //\r
+\r

   EFI_PEI_HOB_POINTERS  FirmwareVolumeHob;\r
 \r
   FirmwareVolumeHob.Raw = GetNextHob (EFI_HOB_TYPE_FV, *HobStart);\r
   EFI_PEI_HOB_POINTERS  FirmwareVolumeHob;\r
 \r
   FirmwareVolumeHob.Raw = GetNextHob (EFI_HOB_TYPE_FV, *HobStart);\r


@@ -879,6 +1014,17 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is changed substantially with R9 counerpart GetNextGuidHob (). \r
+  // 1. R9 GetNextGuidHob has two parameters and returns the matched GUID HOB from the StartHob. \r
+  // 2. R9 GetNextGuidHob does not strip the HOB header, so caller is required to apply\r
+  //    GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE () to extract the data section and its\r
+  //    size info respectively.\r
+  // 3. this function does not skip the starting HOB pointer unconditionally:\r
+  //    it returns HobStart back if HobStart itself meets the requirement;\r
+  //    caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.\r
+  //\r

   EFI_PEI_HOB_POINTERS  GuidHob;\r
 \r
   if (Buffer == NULL) {\r
   EFI_PEI_HOB_POINTERS  GuidHob;\r
 \r
   if (Buffer == NULL) {\r


@@ -962,6 +1108,11 @@ Returns:
 \r
 --*/\r
 {\r
 \r
 --*/\r
 {\r

+  //\r
+  // Porting Guide:\r
+  // This library interface is simply obsolete. \r
+  // Include the source code to user code.\r
+  //\r

   EFI_HOB_GUID_TYPE   *GuidHob;\r
 \r
   GuidHob = GetNextGuidHob (&gEfiIoBaseHobGuid, HobStart);\r
   EFI_HOB_GUID_TYPE   *GuidHob;\r
 \r
   GuidHob = GetNextGuidHob (&gEfiIoBaseHobGuid, HobStart);\r