DynamicTablesPkg/Library/Common/AcpiHelperLib/AcpiHelper.c

   1 /** @file
   2   Acpi Helper
   3
   4   Copyright (c) 2017 - 2021, Arm Limited. All rights reserved.<BR>
   5
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7 **/
   8
   9 #include <Library/BaseLib.h>
  10 #include <Library/DebugLib.h>
  11
  12 // Module specific include files.
  13 #include <Library/AcpiHelperLib.h>
  14
  15 /** Convert a hex number to its ASCII code.
  16
  17  @param [in]  Hex   Hex number to convert.
  18                     Must be 0 <= x < 16.
  19
  20  @return The ASCII code corresponding to x.
  21          -1 if error.
  22 **/
  23 UINT8
  24 EFIAPI
  25 AsciiFromHex (
  26   IN  UINT8  Hex
  27   )
  28 {
  29   if (Hex < 10) {
  30     return (UINT8)(Hex + '0');
  31   }
  32
  33   if (Hex < 16) {
  34     return (UINT8)(Hex - 10 + 'A');
  35   }
  36
  37   ASSERT (FALSE);
  38   return (UINT8)-1;
  39 }
  40
  41 /** Convert an ASCII char representing an hexadecimal number
  42     to its integer value.
  43
  44  @param [in]  Char  Char to convert.
  45                     Must be between '0'-'9' or 'A'-'F' or 'a'-'f'.
  46
  47  @return The corresponding integer (between 0-16).
  48          -1 if error.
  49 **/
  50 UINT8
  51 EFIAPI
  52 HexFromAscii (
  53   IN  CHAR8  Char
  54   )
  55 {
  56   if ((Char >= '0') && (Char <= '9')) {
  57     return (UINT8)(Char - '0');
  58   }
  59
  60   if ((Char >= 'A') && (Char <= 'F')) {
  61     return (UINT8)(Char - 'A' + 10);
  62   }
  63
  64   if ((Char >= 'a') && (Char <= 'f')) {
  65     return (UINT8)(Char - 'a' + 10);
  66   }
  67
  68   ASSERT (FALSE);
  69   return (UINT8)-1;
  70 }
  71
  72 /** Check if a HID is a valid PNP ID.
  73
  74   @param     [in] Hid     The Hid to validate.
  75
  76   @retval    TRUE         The Hid is a valid PNP ID.
  77   @retval    FALSE        The Hid is not a valid PNP ID.
  78 **/
  79 BOOLEAN
  80 IsValidPnpId (
  81   IN  CONST CHAR8  *Hid
  82   )
  83 {
  84   UINTN  Index;
  85
  86   if (AsciiStrLen (Hid) != 7) {
  87     return FALSE;
  88   }
  89
  90   // A valid PNP ID must be of the form "AAA####"
  91   // where A is an uppercase letter and # is a hex digit.
  92   for (Index = 0; Index < 3; Index++) {
  93     if (!IS_UPPER_CHAR (Hid[Index])) {
  94       return FALSE;
  95     }
  96   }
  97
  98   for (Index = 3; Index < 7; Index++) {
  99     if (!IS_UPPER_HEX (Hid[Index])) {
 100       return FALSE;
 101     }
 102   }
 103
 104   return TRUE;
 105 }
 106
 107 /** Check if a HID is a valid ACPI ID.
 108
 109   @param     [in] Hid     The Hid to validate.
 110
 111   @retval    TRUE         The Hid is a valid ACPI ID.
 112   @retval    FALSE        The Hid is not a valid ACPI ID.
 113 **/
 114 BOOLEAN
 115 IsValidAcpiId (
 116   IN  CONST CHAR8  *Hid
 117   )
 118 {
 119   UINTN  Index;
 120
 121   if (AsciiStrLen (Hid) != 8) {
 122     return FALSE;
 123   }
 124
 125   // A valid ACPI ID must be of the form "NNNN####"
 126   // where N is an uppercase letter or a digit ('0'-'9')
 127   // and # is a hex digit.
 128   for (Index = 0; Index < 4; Index++) {
 129     if (!(IS_UPPER_CHAR (Hid[Index]) || IS_DIGIT (Hid[Index]))) {
 130       return FALSE;
 131     }
 132   }
 133
 134   for (Index = 4; Index < 8; Index++) {
 135     if (!IS_UPPER_HEX (Hid[Index])) {
 136       return FALSE;
 137     }
 138   }
 139
 140   return TRUE;
 141 }
 142
 143 /** Convert a EisaId string to its compressed UINT32 equivalent.
 144
 145   Cf. ACPI 6.4 specification, s19.3.4 "ASL Macros": "Eisaid"
 146
 147   @param  [in]  EisaIdStr   Input EisaId string.
 148   @param  [out] EisaIdInt   Output EisaId UINT32 (compressed).
 149
 150   @retval EFI_SUCCESS             The function completed successfully.
 151   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 152 **/
 153 EFI_STATUS
 154 EFIAPI
 155 AmlGetEisaIdFromString (
 156   IN  CONST CHAR8   *EisaIdStr,
 157   OUT       UINT32  *EisaIdInt
 158   )
 159 {
 160   if ((EisaIdStr == NULL)         ||
 161       (!IsValidPnpId (EisaIdStr)) ||
 162       (EisaIdInt == NULL))
 163   {
 164     ASSERT (0);
 165     return EFI_INVALID_PARAMETER;
 166   }
 167
 168   /* Cf. ACPI 6.4 specification, s19.3.4 "ASL Macros": "Eisaid"
 169
 170   Converts and compresses the 7-character text argument into its corresponding
 171   4-byte numeric EISA ID encoding (Integer). This can be used when declaring
 172   IDs for devices that are EISA IDs.
 173
 174   The algorithm used to convert the TextID is as shown in the following
 175   example:
 176     Starting with a seven character input string "PNP0303", we want to create
 177     a DWordConst. This string contains a three character manufacturer code
 178     "PNP", a three character hex product identifier "030", and a one character
 179     revision identifier "3".
 180     The compressed manufacturer code is created as follows:
 181       1) Find hex ASCII value for each letter
 182       2) Subtract 40h from each ASCII value
 183       3) Retain 5 least significant bits for each letter and discard remaining
 184          0's:
 185
 186       Byte 0:
 187         Bit 7: reserved (0)
 188         Bit 6-2: 1st character of compressed mfg code "P"
 189         Bit 1-0: Upper 2 bits of 2nd character of mfg code "N"
 190       Byte 1:
 191         Bit 7-5: Lower 3 bits of 2nd character of mfg code "N"
 192         Bit 4-0: 3rd character of mfg code "P"
 193       Byte 2:
 194         Bit 7-4: 1st hex digit of product number "0"
 195         Bit 3-0: 2nd hex digit of product number "3"
 196       Byte 3:
 197         Bit 7-4: 3rd hex digit of product number "0"
 198         Bit 3-0: 4th hex digit of product number "3"
 199   */
 200   *EisaIdInt = SwapBytes32 (
 201                  ((EisaIdStr[0] - 0x40) << 26)       |
 202                  ((EisaIdStr[1] - 0x40) << 21)       |
 203                  ((EisaIdStr[2] - 0x40) << 16)       |
 204                  (HexFromAscii (EisaIdStr[3]) << 12) |
 205                  (HexFromAscii (EisaIdStr[4]) << 8)  |
 206                  (HexFromAscii (EisaIdStr[5]) << 4)  |
 207                  (HexFromAscii (EisaIdStr[6]))
 208                  );
 209
 210   return EFI_SUCCESS;
 211 }