text: /** @file
    AML String.
  
    Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved. <BR>
    Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>
  
    SPDX-License-Identifier: BSD-2-Clause-Patent
  **/
  
  #include <String/AmlString.h>
  
  #include <AmlDefines.h>
  #include <IndustryStandard/AcpiAml.h>
  
  /** Check NameString/path information is valid.
  
    Root, ParentPrefix and SegCount cannot be 0 at the same time.
    This function works for ASL and AML name strings.
  
    @param [in]   Root          Number of root char.
                                Must be 0 or 1.
    @param [in]   ParentPrefix  Number of carets char ('^').
                                Must be [0-255].
    @param [in]   SegCount      Number of NameSeg (s).
                                Must be [0-255].
  
    @retval TRUE id the input information is in the right boundaries.
            FALSE otherwise.
  **/
  BOOLEAN
  EFIAPI
  AmlIsNameString (
    IN  UINT32    Root,
    IN  UINT32    ParentPrefix,
    IN  UINT32    SegCount
    )
  {
    if (((Root == 0) || (Root == 1))            &&
        (ParentPrefix <= MAX_UINT8)             &&
        (!((ParentPrefix != 0) && (Root != 0))) &&
        (SegCount <= MAX_UINT8)                 &&
        ((SegCount + Root + ParentPrefix) != 0)) {
      return TRUE;
    }
    return FALSE;
  }
  
  /** Copy bytes from SrcBuffer to DstBuffer and convert to upper case.
      Don't copy more than MaxDstBufferSize bytes.
  
    @param  [out] DstBuffer         Destination buffer.
    @param  [in]  MaxDstBufferSize  Maximum size of DstBuffer.
                                    Must be non-zero.
    @param  [in]  SrcBuffer         Source buffer.
    @param  [in]  Count             Count of bytes to copy from SrcBuffer.
                                    Return success if 0.
  
    @retval EFI_SUCCESS             The function completed successfully.
    @retval EFI_INVALID_PARAMETER   Invalid parameter.
  **/
  EFI_STATUS
  EFIAPI
  AmlUpperCaseMemCpyS (
    OUT       CHAR8   * DstBuffer,
    IN        UINT32    MaxDstBufferSize,
    IN  CONST CHAR8   * SrcBuffer,
    IN        UINT32    Count
    )
  {
    UINT32 Index;
  
    if ((DstBuffer == NULL) ||
        (SrcBuffer == NULL)) {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    if (Count == 0) {
      return EFI_SUCCESS;
    }
  
    if (Count > MaxDstBufferSize) {
      Count = MaxDstBufferSize;
    }
  
    for (Index = 0; Index < Count; Index++) {
      if ((SrcBuffer[Index] >= 'a') && (SrcBuffer[Index] <= 'z')) {
        DstBuffer[Index] = (CHAR8)((UINT8)SrcBuffer[Index] - ('a' - 'A'));
      } else {
        DstBuffer[Index] = SrcBuffer[Index];
      }
    }
  
    return EFI_SUCCESS;
  }
  
  /** Check whether Buffer is a root path ('\').
  
    This function works for both ASL and AML pathnames.
    Buffer must be at least 2 bytes long.
  
    @param  [in]  Buffer   An ASL/AML path.
  
    @retval TRUE    Buffer is a root path
    @retval FALSE   Buffer is not a root path.
  **/
  BOOLEAN
  EFIAPI
  AmlIsRootPath (
    IN  CONST  CHAR8  * Buffer
    )
  {
    if (Buffer == NULL) {
      return FALSE;
    }
  
    if ((Buffer[0] == AML_ROOT_CHAR) && (Buffer[1] == '\0')) {
      return TRUE;
    } else {
      return FALSE;
    }
  }
  
  /** Check whether Ch is an ASL/AML LeadName.
  
    This function works for both ASL and AML pathnames.
  
    ACPI 6.3 specification, s19.2.2. "ASL Name and Pathname Terms":
    LeadNameChar := 'A'-'Z' | 'a'-'z' | '_'
  
    ACPI 6.3 specification, s20.2.2. "Name Objects Encoding":
    LeadNameChar := 'A'-'Z' | 'a'-'z' | '_'
  
    @param  [in]  Ch    The char to test.
  
    @retval TRUE    Ch is an ASL/AML LeadName.
    @retval FALSE   Ch is not an ASL/AML LeadName.
  **/
  BOOLEAN
  EFIAPI
  AmlIsLeadNameChar (
    IN  CHAR8   Ch
    )
  {
    if ((Ch == '_') || (Ch >= 'A' && Ch <= 'Z') || (Ch >= 'a' && Ch <= 'z')) {
      return TRUE;
    } else {
      return FALSE;
    }
  }
  
  /** Check whether Ch is an ASL/AML NameChar.
  
    This function works for both ASL and AML pathnames.
  
    ACPI 6.3 specification, s19.2.2. "ASL Name and Pathname Terms":
    NameChar := DigitChar | LeadNameChar
    LeadNameChar := 'A'-'Z' | 'a'-'z' | '_'
    DigitChar := '0'-'9'
  
    ACPI 6.3 specification, s20.2.2. "Name Objects Encoding":
    NameChar := DigitChar | LeadNameChar
    LeadNameChar := 'A'-'Z' | 'a'-'z' | '_'
    DigitChar := '0'-'9'
  
    @param  [in]  Ch    The char to test.
  
    @retval TRUE    Ch is an ASL/AML NameChar.
    @retval FALSE   Ch is not an ASL/AML NameChar.
  **/
  BOOLEAN
  EFIAPI
  AmlIsNameChar (
    IN  CHAR8  Ch
    )
  {
    if (AmlIsLeadNameChar (Ch) || (Ch >= '0' && Ch <= '9')) {
      return TRUE;
    } else {
      return FALSE;
    }
  }
  
  /** Check whether AslBuffer is an ASL NameSeg.
  
    This function only works for ASL NameStrings/pathnames.
    ASL NameStrings/pathnames are at most 4 chars long.
  
    @param [in]   AslBuffer   Pointer in an ASL NameString/pathname.
    @param [out]  Size        Size of the NameSeg.
  
    @retval TRUE    AslBuffer is an ASL NameSeg.
    @retval FALSE   AslBuffer is not an ASL NameSeg.
  **/
  BOOLEAN
  EFIAPI
  AslIsNameSeg (
    IN  CONST  CHAR8    * AslBuffer,
    OUT        UINT32   * Size
    )
  {
    UINT32    Index;
  
    if ((AslBuffer == NULL) ||
        (Size == NULL)) {
      return FALSE;
    }
  
    if (!AmlIsLeadNameChar (AslBuffer[0])) {
      return FALSE;
    }
  
    for (Index = 1; Index < AML_NAME_SEG_SIZE; Index++) {
      if ((AslBuffer[Index] == '.')   ||
          (AslBuffer[Index] == '\0')) {
        *Size = Index;
        return TRUE;
      } else if (!AmlIsNameChar (AslBuffer[Index])) {
        return FALSE;
      }
    }
  
    *Size = Index;
    return TRUE;
  }
  
  /** Check whether AmlBuffer is an AML NameSeg.
  
    This function only works for AML NameStrings/pathnames.
    AML NameStrings/pathnames must be 4 chars long.
  
    @param [in] AmlBuffer   Pointer in an AML NameString/pathname.
  
    @retval TRUE    AmlBuffer is an AML NameSeg.
    @retval FALSE   AmlBuffer is not an AML NameSeg.
  **/
  BOOLEAN
  EFIAPI
  AmlIsNameSeg (
    IN  CONST  CHAR8    * AmlBuffer
    )
  {
    UINT32    Index;
  
    if (AmlBuffer == NULL) {
      return FALSE;
    }
  
    if (!AmlIsLeadNameChar (AmlBuffer[0])) {
      return FALSE;
    }
  
    for (Index = 1; Index < AML_NAME_SEG_SIZE; Index++) {
      if (!AmlIsNameChar (AmlBuffer[Index])) {
        return FALSE;
      }
    }
  
    return TRUE;
  }
  
  /** Parse an ASL NameString/path.
  
    An ASL NameString/path must be NULL terminated.
    Information found in the ASL NameString/path is returned via pointers:
    Root, ParentPrefix, SegCount.
  
    @param [in]    Buffer       ASL NameString/path.
    @param [out]   Root         Pointer holding the number of root char.
                                Can be 0 or 1.
    @param [out]   ParentPrefix Pointer holding the number of carets char ('^').
                                Can be [0-255].
    @param [out]   SegCount     Pointer holding the number of NameSeg (s).
                                Can be [0-255].
  
    @retval EFI_SUCCESS             The function completed successfully.
    @retval EFI_INVALID_PARAMETER   Invalid parameter.
  **/
  EFI_STATUS
  EFIAPI
  AslParseNameStringInfo (
    IN  CONST CHAR8     * Buffer,
    OUT       UINT32    * Root,
    OUT       UINT32    * ParentPrefix,
    OUT       UINT32    * SegCount
    )
  {
    UINT32      NameSegSize;
  
    if ((Buffer == NULL)        ||
        (Root == NULL)          ||
        (ParentPrefix == NULL)  ||
        (SegCount == NULL)) {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    *Root = 0;
    *ParentPrefix = 0;
    *SegCount = 0;
  
    // Handle Root and ParentPrefix(s).
    if (*Buffer == AML_ROOT_CHAR) {
      *Root = 1;
      Buffer++;
    } else if (*Buffer == AML_PARENT_PREFIX_CHAR) {
      do {
        Buffer++;
        (*ParentPrefix)++;
      } while (*Buffer == AML_PARENT_PREFIX_CHAR);
    }
  
    // Handle SegCount(s).
    while (AslIsNameSeg (Buffer, &NameSegSize)) {
      // Safety checks on NameSegSize.
      if ((NameSegSize == 0) || (NameSegSize > AML_NAME_SEG_SIZE)) {
        ASSERT (0);
        return EFI_INVALID_PARAMETER;
      }
  
      // Increment the NameSeg count.
      (*SegCount)++;
      Buffer += NameSegSize;
  
      // Skip the '.' separator if present.
      if (*Buffer == '.') {
        Buffer++;
      }
    } // while
  
    // An ASL NameString/path must be NULL terminated.
    if (*Buffer != '\0') {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    if (!AmlIsNameString (*Root, *ParentPrefix, *SegCount)) {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    return EFI_SUCCESS;
  }
  
  /** Parse an AML NameString/path.
  
    It is possible to determine the size of an AML NameString/path just
    by sight reading it. So no overflow can occur.
    Information found in the AML NameString/path is returned via pointers:
    Root, ParentPrefix, SegCount.
  
    @param [in]    Buffer         AML NameString/path.
    @param [out]   Root           Pointer holding the number of root char.
                                  Can be 0 or 1.
    @param [out]   ParentPrefix   Pointer holding the number of carets char ('^').
                                  Can be [0-255].
    @param [out]   SegCount       Pointer holding the number of NameSeg(s).
                                  Can be [0-255].
  
    @retval EFI_SUCCESS             The function completed successfully.
    @retval EFI_INVALID_PARAMETER   Invalid parameter.
  **/
  EFI_STATUS
  EFIAPI
  AmlParseNameStringInfo (
    IN  CONST CHAR8   * Buffer,
    OUT       UINT32  * Root,
    OUT       UINT32  * ParentPrefix,
    OUT       UINT32  * SegCount
    )
  {
    if ((Buffer == NULL) ||
        (Root == NULL)   ||
        (ParentPrefix == NULL) ||
        (SegCount == NULL)) {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    *Root = 0;
    *ParentPrefix = 0;
    *SegCount = 0;
  
    // Handle Root and ParentPrefix(s).
    if (*Buffer == AML_ROOT_CHAR) {
      *Root = 1;
      Buffer++;
    } else if (*Buffer == AML_PARENT_PREFIX_CHAR) {
      do {
        Buffer++;
        (*ParentPrefix)++;
      } while (*Buffer == AML_PARENT_PREFIX_CHAR);
    }
  
    // Handle SegCount(s).
    if (*Buffer == AML_DUAL_NAME_PREFIX) {
      *SegCount = 2;
    } else if (*Buffer == AML_MULTI_NAME_PREFIX) {
      *SegCount = *((UINT8*)(Buffer + 1));
    } else if (AmlIsNameSeg (Buffer)) {
      *SegCount = 1;
    } else if (*Buffer == AML_ZERO_OP) {
      *SegCount = 0;
    } else {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    // Safety checks on exit.
    if (!AmlIsNameString (*Root, *ParentPrefix, *SegCount)) {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    return EFI_SUCCESS;
  }
  
  /** Compute the ASL NameString/path size from NameString
      information (Root, ParentPrefix, SegCount).
  
    @param [in] Root          Number of root char.
                              Can be 0 or 1.
    @param [in] ParentPrefix  Number of carets char ('^').
                              Can be [0-255].
    @param [in] SegCount      Pointer holding the number of NameSeg(s).
                              Can be [0-255].
  
    @return Size of the ASL NameString/path.
  **/
  UINT32
  EFIAPI
  AslComputeNameStringSize (
    IN  UINT32    Root,
    IN  UINT32    ParentPrefix,
    IN  UINT32    SegCount
    )
  {
    UINT32    TotalSize;
  
    if (!AmlIsNameString (Root, ParentPrefix, SegCount)) {
      ASSERT (0);
      return 0;
    }
  
    // Root and ParentPrefix(s).
    TotalSize = Root + ParentPrefix;
  
    // Add size required for NameSeg(s).
    TotalSize += (SegCount * AML_NAME_SEG_SIZE);
  
    // Add size required for '.' separator(s).
    TotalSize += (SegCount > 1) ? (SegCount - 1) : 0;
  
    // Add 1 byte for NULL termination '\0'.
    TotalSize += 1;
  
    return TotalSize;
  }
  
  /** Compute the AML NameString/path size from NameString
      information (Root, ParentPrefix, SegCount).
  
    @param [in] Root          Number of root char.
                              Can be 0 or 1.
    @param [in] ParentPrefix  Number of carets char ('^').
                              Can be [0-255].
    @param [in] SegCount      Pointer holding the number of NameSeg(s).
                              Can be [0-255].
  
    @return Size of the AML NameString/path.
  **/
  UINT32
  EFIAPI
  AmlComputeNameStringSize (
    IN  UINT32    Root,
    IN  UINT32    ParentPrefix,
    IN  UINT32    SegCount
    )
  {
    UINT32    TotalSize;
  
    if (!AmlIsNameString (Root, ParentPrefix, SegCount)) {
      ASSERT (0);
      return 0;
    }
  
    // Root and ParentPrefix(s).
    TotalSize = Root + ParentPrefix;
  
    // If SegCount == 0, '\0' must end the AML NameString/path.
    TotalSize += (SegCount == 0) ? 1 : (SegCount * AML_NAME_SEG_SIZE);
  
    // AML prefix. SegCount > 2 = MultiNamePrefix, SegCount = 2 DualNamePrefix.
    TotalSize += (SegCount > 2) ? 2 : ((SegCount == 2) ? 1 : 0);
  
    return TotalSize;
  }
  
  /** Get the ASL NameString/path size.
  
    @param [in]   AslPath         An ASL NameString/path.
    @param [out]  AslPathSizePtr  Pointer holding the ASL NameString/path size.
  
    @retval EFI_SUCCESS             Success.
    @retval EFI_INVALID_PARAMETER   Invalid parameter.
  **/
  EFI_STATUS
  EFIAPI
  AslGetNameStringSize (
    IN  CONST CHAR8   * AslPath,
    OUT       UINT32  * AslPathSizePtr
    )
  {
    if ((AslPath == NULL) ||
        (AslPathSizePtr == NULL)) {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    *AslPathSizePtr = 0;
    do {
      (*AslPathSizePtr)++;
      AslPath++;
    } while (*AslPath != '\0');
  
    return EFI_SUCCESS;
  }
  
  /** Get the AML NameString/path size.
  
    @param [in]   AmlPath         An AML NameString/path.
    @param [out]  AmlPathSizePtr  Pointer holding the AML NameString/path size.
  
    @retval EFI_SUCCESS             Success.
    @retval EFI_INVALID_PARAMETER   Invalid parameter.
  **/
  EFI_STATUS
  EFIAPI
  AmlGetNameStringSize (
    IN   CONST  CHAR8   * AmlPath,
    OUT         UINT32  * AmlPathSizePtr
    )
  {
    EFI_STATUS    Status;
  
    UINT32        Root;
    UINT32        ParentPrefix;
    UINT32        SegCount;
  
    if ((AmlPath == NULL) ||
        (AmlPathSizePtr == NULL)) {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    Status = AmlParseNameStringInfo (
               AmlPath,
               &Root,
               &ParentPrefix,
               &SegCount
               );
    if (EFI_ERROR (Status)) {
      ASSERT (0);
      return Status;
    }
  
    *AmlPathSizePtr = AmlComputeNameStringSize (Root, ParentPrefix, SegCount);
    if (*AmlPathSizePtr == 0) {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    return Status;
  }
  
  /** Convert an ASL NameString/path to an AML NameString/path.
      The caller must free the memory allocated in this function
      for AmlPath using FreePool ().
  
    @param  [in]  AslPath     An ASL NameString/path.
    @param  [out] OutAmlPath  Buffer containing the AML path.
  
    @retval EFI_SUCCESS             Success.
    @retval EFI_INVALID_PARAMETER   Invalid parameter.
    @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
  **/
  EFI_STATUS
  EFIAPI
  ConvertAslNameToAmlName (
    IN  CONST  CHAR8   * AslPath,
    OUT        CHAR8  ** OutAmlPath
    )
  {
    EFI_STATUS      Status;
  
    UINT32          Root;
    UINT32          ParentPrefix;
    UINT32          SegCount;
    UINT32          TotalSize;
    UINT32          NameSegSize;
  
    CONST CHAR8   * AslBuffer;
    CHAR8         * AmlBuffer;
    CHAR8         * AmlPath;
  
    if ((AslPath == NULL) ||
        (OutAmlPath == NULL)) {
      return EFI_INVALID_PARAMETER;
    }
  
    // Analyze AslPath. AslPath is checked in the call.
    Status = AslParseNameStringInfo (AslPath, &Root, &ParentPrefix, &SegCount);
    if (EFI_ERROR (Status)) {
      ASSERT (0);
      return Status;
    }
  
    // Compute TotalSize.
    TotalSize = AmlComputeNameStringSize (Root, ParentPrefix, SegCount);
    if (TotalSize == 0) {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    // Allocate memory.
    AmlPath = AllocateZeroPool (TotalSize);
    if (AmlPath == NULL) {
      ASSERT (0);
      return EFI_OUT_OF_RESOURCES;
    }
  
    AmlBuffer = AmlPath;
    AslBuffer = AslPath;
  
    // Handle Root and ParentPrefix(s).
    if (Root == 1) {
      *AmlBuffer = AML_ROOT_CHAR;
      AmlBuffer++;
      AslBuffer++;
    } else if (ParentPrefix > 0) {
      SetMem (AmlBuffer, ParentPrefix, AML_PARENT_PREFIX_CHAR);
      AmlBuffer += ParentPrefix;
      AslBuffer += ParentPrefix;
    }
  
    // Handle prefix and SegCount(s).
    if (SegCount > 2) {
      *AmlBuffer = AML_MULTI_NAME_PREFIX;
      AmlBuffer++;
      *AmlBuffer = (UINT8)SegCount;
      AmlBuffer++;
    } else if (SegCount == 2) {
      *AmlBuffer = AML_DUAL_NAME_PREFIX;
      AmlBuffer++;
    }
  
    if (SegCount != 0) {
      // Write NameSeg(s).
      while (1) {
        SegCount--;
  
        // Get the NameSeg size.
        if (!AslIsNameSeg (AslBuffer, &NameSegSize)) {
          ASSERT (0);
          Status = EFI_INVALID_PARAMETER;
          goto error_handler;
        }
  
        // Convert to Upper case and copy.
        Status = AmlUpperCaseMemCpyS (
                   AmlBuffer,
                   TotalSize,
                   AslBuffer,
                   NameSegSize
                   );
        if (EFI_ERROR (Status)) {
          ASSERT (0);
          goto error_handler;
        }
  
        // Complete the NameSeg with an underscore ('_') if shorter than 4 bytes.
        SetMem (
          AmlBuffer + NameSegSize,
          AML_NAME_SEG_SIZE - NameSegSize,
          AML_NAME_CHAR__
          );
  
        // Go to the next NameSeg.
        AmlBuffer += AML_NAME_SEG_SIZE;
        AslBuffer += NameSegSize;
  
        // Skip the '.' separator.
        if (SegCount != 0) {
          if (*AslBuffer == '.') {
            AslBuffer++;
          } else {
            ASSERT (0);
            Status = EFI_INVALID_PARAMETER;
            goto error_handler;
          }
        } else {
          // (SegCount == 0)
          if (*AslBuffer == '\0') {
            break;
          } else {
            ASSERT (0);
            Status = EFI_INVALID_PARAMETER;
            goto error_handler;
          }
        }
      } // while
  
    } else {
      // (SegCount == 0)
      // '\0' needs to end the AML NameString/path.
      *AmlBuffer = AML_ZERO_OP;
      AmlBuffer++;
    }
  
    // Safety checks on exit.
    // Check that AmlPath has been filled with TotalSize bytes.
    if ((SegCount != 0)               ||
        (*AslBuffer != AML_ZERO_OP)   ||
        (((UINT32)(AmlBuffer - AmlPath)) != TotalSize)) {
        ASSERT (0);
        Status = EFI_INVALID_PARAMETER;
        goto error_handler;
    }
  
    *OutAmlPath = AmlPath;
    return EFI_SUCCESS;
  
  error_handler:
    FreePool (AmlPath);
    return Status;
  }
  
  /** Convert an AML NameString/path to an ASL NameString/path.
      The caller must free the memory allocated in this function.
      using FreePool ().
  
    @param  [in]  AmlPath     An AML NameString/path.
    @param  [out] OutAslPath  Buffer containing the ASL path.
  
    @retval EFI_SUCCESS             Success.
    @retval EFI_INVALID_PARAMETER   Invalid parameter.
    @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
  **/
  EFI_STATUS
  EFIAPI
  ConvertAmlNameToAslName (
    IN  CONST CHAR8     * AmlPath,
    OUT       CHAR8    ** OutAslPath
    )
  {
    EFI_STATUS      Status;
  
    UINT32          Root;
    UINT32          ParentPrefix;
    UINT32          SegCount;
    UINT32          TotalSize;
  
    CONST CHAR8   * AmlBuffer;
    CHAR8         * AslBuffer;
    CHAR8         * AslPath;
  
    if ((AmlPath == NULL)   ||
        (OutAslPath == NULL)) {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    // Analyze AslPath. AmlPath is checked in the call.
    Status = AmlParseNameStringInfo (AmlPath, &Root, &ParentPrefix, &SegCount);
    if (EFI_ERROR (Status)) {
      ASSERT (0);
      return Status;
    }
  
    // Compute TotalSize.
    TotalSize = AslComputeNameStringSize (Root, ParentPrefix, SegCount);
    if (TotalSize == 0) {
      ASSERT (0);
      return EFI_INVALID_PARAMETER;
    }
  
    // Allocate memory.
    AslPath = AllocateZeroPool (TotalSize);
    if (AslPath == NULL) {
      ASSERT (0);
      return EFI_OUT_OF_RESOURCES;
    }
  
    AmlBuffer = AmlPath;
    AslBuffer = AslPath;
  
    // Handle prefix and SegCount(s).
    if (Root == 1) {
      *AslBuffer = AML_ROOT_CHAR;
      AslBuffer++;
      AmlBuffer++;
    } else if (ParentPrefix > 0) {
      SetMem (AslBuffer, ParentPrefix, AML_PARENT_PREFIX_CHAR);
      AslBuffer += ParentPrefix;
      AmlBuffer += ParentPrefix;
    }
  
    // Handle Root and Parent(s).
    // Skip the MultiName or DualName prefix chars.
    if (SegCount > 2) {
      AmlBuffer += 2;
    } else if (SegCount == 2) {
      AmlBuffer += 1;
    }
  
    // Write NameSeg(s).
    while (SegCount) {
      // NameSeg is already in upper case and always 4 bytes long.
      CopyMem (AslBuffer, AmlBuffer, AML_NAME_SEG_SIZE);
      AslBuffer += AML_NAME_SEG_SIZE;
      AmlBuffer += AML_NAME_SEG_SIZE;
  
      SegCount--;
  
      // Write the '.' separator if there is another NameSeg following.
      if (SegCount != 0) {
        *AslBuffer = '.';
        AslBuffer++;
      }
    } // while
  
    // NULL terminate the ASL NameString.
    *AslBuffer = '\0';
    AslBuffer++;
  
    // Safety checks on exit.
    // Check that AslPath has been filled with TotalSize bytes.
    if (((UINT32)(AslBuffer - AslPath)) != TotalSize) {
      ASSERT (0);
      Status = EFI_INVALID_PARAMETER;
      goto error_handler;
    }
  
    *OutAslPath = AslPath;
    return EFI_SUCCESS;
  
  error_handler:
    FreePool (AslPath);
    return Status;
  }
  
  /** Compare two ASL NameStrings.
  
    @param [in] AslName1    First NameString to compare.
    @param [in] AslName2    Second NameString to compare.
  
    @retval TRUE if the two strings are identical.
    @retval FALSE otherwise, or if error.
  **/
  BOOLEAN
  EFIAPI
  AslCompareNameString (
    IN  CONST CHAR8 *   AslName1,
    IN  CONST CHAR8 *   AslName2
    )
  {
    EFI_STATUS    Status;
    UINT32        AslName1Len;
    UINT32        AslName2Len;
  
    if ((AslName1 == NULL) ||
        (AslName2 == NULL)) {
      ASSERT (0);
      return FALSE;
    }
  
    Status = AslGetNameStringSize (AslName1, &AslName1Len);
    if (EFI_ERROR (Status)) {
      ASSERT (0);
      return FALSE;
    }
  
    Status = AslGetNameStringSize (AslName2, &AslName2Len);
    if (EFI_ERROR (Status)) {
      ASSERT (0);
      return FALSE;
    }
  
    // AslName1 and AslName2 don't have the same length
    if (AslName1Len != AslName2Len) {
      return FALSE;
    }
  
    return (CompareMem (AslName1, AslName2, AslName1Len) == 0);
  }
  
  /** Compare two AML NameStrings.
  
    @param [in] AmlName1    First NameString to compare.
    @param [in] AmlName2    Second NameString to compare.
  
    @retval TRUE if the two strings are identical.
    @retval FALSE otherwise, or if error.
  **/
  BOOLEAN
  EFIAPI
  AmlCompareNameString (
    IN  CONST CHAR8 *   AmlName1,
    IN  CONST CHAR8 *   AmlName2
    )
  {
    EFI_STATUS    Status;
    UINT32        AmlName1Len;
    UINT32        AmlName2Len;
  
    if ((AmlName1 == NULL) ||
        (AmlName2 == NULL)) {
      ASSERT (0);
      return FALSE;
    }
  
    Status = AmlGetNameStringSize (AmlName1, &AmlName1Len);
    if (EFI_ERROR (Status)) {
      ASSERT (0);
      return FALSE;
    }
  
    Status = AmlGetNameStringSize (AmlName2, &AmlName2Len);
    if (EFI_ERROR (Status)) {
      ASSERT (0);
      return FALSE;
    }
  
    // AmlName1 and AmlName2 don't have the same length
    if (AmlName1Len != AmlName2Len) {
      return FALSE;
    }
  
    return (CompareMem (AmlName1, AmlName2, AmlName1Len) == 0);
  }
  
  /** Compare an AML NameString and an ASL NameString.
  
    The ASL NameString is converted to an AML NameString before
    being compared with the ASL NameString. This allows to expand
    NameSegs shorter than 4 chars.
    E.g.: AslName: "DEV" will be expanded to "DEV_" before being
          compared.
  
    @param [in] AmlName1   AML NameString to compare.
    @param [in] AslName2   ASL NameString to compare.
  
    @retval TRUE if the two strings are identical.
    @retval FALSE otherwise, or if error.
  **/
  BOOLEAN
  EFIAPI
  CompareAmlWithAslNameString (
    IN  CONST CHAR8 *   AmlName1,
    IN  CONST CHAR8 *   AslName2
    )
  {
    EFI_STATUS    Status;
  
    CHAR8       * AmlName2;
    BOOLEAN       RetVal;
  
    if ((AmlName1 == NULL) ||
        (AslName2 == NULL)) {
      ASSERT (0);
      return FALSE;
    }
  
    // Convert the AslName2 to an AmlName2.
    // AmlName2 must be freed.
    Status = ConvertAmlNameToAslName (AslName2, &AmlName2);
    if (EFI_ERROR (Status)) {
      ASSERT (0);
      return FALSE;
    }
  
    RetVal = AmlCompareNameString (AmlName1, AmlName2);
  
    // Free AmlName2.
    FreePool (AmlName2);
  
    return RetVal;
  }
  /** Given an AmlPath, return the address of the first NameSeg.
  
    It is possible to determine the size of an AML NameString/path just
    by sight reading it. So no overflow can occur.
  
    @param  [in]  AmlPath       The AML pathname.
    @param  [in]  Root          The AML pathname starts with a root char.
                                It is an absolute path.
    @param  [in]  ParentPrefix  The AML pathname has ParentPrefix
                                carets in its name.
  
    @return Pointer to the first NameSeg of the NameString.
            Return NULL if AmlPath is NULL.
  **/
  CONST
  CHAR8 *
  EFIAPI
  AmlGetFirstNameSeg (
    IN  CONST  CHAR8    * AmlPath,
    IN         UINT32     Root,
    IN         UINT32     ParentPrefix
    )
  {
    if (AmlPath == NULL) {
      ASSERT (0);
      return NULL;
    }
  
    AmlPath += Root;
    AmlPath += ParentPrefix;
    AmlPath += ((*AmlPath == AML_MULTI_NAME_PREFIX) ? 2
                 : (*AmlPath == AML_DUAL_NAME_PREFIX) ? 1 : 0);
    return AmlPath;
  }
  