1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
|
/** @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_
|
