ca04956e1b
Dynamic AML requires encoding/decoding and conversion of AML and ASL strings. A collection of helper functions have been provided for internal use in the AmlLib Library. Signed-off-by: Pierre Gondois <pierre.gondois@arm.com> Signed-off-by: Sami Mujawar <sami.mujawar@arm.com> Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
402 lines
12 KiB
C
402 lines
12 KiB
C
/** @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
|
|
**/
|
|
|
|
#ifndef AML_STRING_H_
|
|
#define AML_STRING_H_
|
|
|
|
/* This header file does not include internal Node definition,
|
|
i.e. AML_ROOT_NODE, AML_OBJECT_NODE, etc. The node definitions
|
|
must be included by the caller file. The function prototypes must
|
|
only expose AML_NODE_HANDLE, AML_ROOT_NODE_HANDLE, etc. node
|
|
definitions.
|
|
This allows to keep the functions defined here both internal and
|
|
potentially external. If necessary, any function of this file can
|
|
be exposed externally.
|
|
The Api folder is internal to the AmlLib, but should only use these
|
|
functions. They provide a "safe" way to interact with the AmlLib.
|
|
*/
|
|
|
|
#include <AmlInclude.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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
/** 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
|
|
);
|
|
|
|
#endif // AML_STRING_H_
|