/** @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_ |