]>
Commit | Line | Data |
---|---|---|
31962537 PG |
1 | /** @file\r |
2 | AML Core Interface.\r | |
3 | \r | |
4 | Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>\r | |
5 | \r | |
6 | SPDX-License-Identifier: BSD-2-Clause-Patent\r | |
7 | **/\r | |
8 | \r | |
9 | #ifndef AML_CORE_INTERFACE_H_\r | |
10 | #define AML_CORE_INTERFACE_H_\r | |
11 | \r | |
12 | /* This header file does not include internal Node definition,\r | |
13 | i.e. AML_ROOT_NODE, AML_OBJECT_NODE, etc. The node definitions\r | |
14 | must be included by the caller file. The function prototypes must\r | |
15 | only expose AML_NODE_HANDLE, AML_ROOT_NODE_HANDLE, etc. node\r | |
16 | definitions.\r | |
17 | This allows to keep the functions defined here both internal and\r | |
18 | potentially external. If necessary, any function of this file can\r | |
19 | be exposed externally.\r | |
20 | The Api folder is internal to the AmlLib, but should only use these\r | |
21 | functions. They provide a "safe" way to interact with the AmlLib.\r | |
22 | */\r | |
23 | \r | |
24 | #include <AmlDefines.h>\r | |
25 | #include <Include/Library/AmlLib/AmlLib.h>\r | |
26 | #include <ResourceData/AmlResourceData.h>\r | |
27 | \r | |
28 | /**\r | |
29 | @defgroup CoreApis Core APIs\r | |
30 | @ingroup AMLLib\r | |
31 | @{\r | |
32 | Core APIs are the main APIs of the library. They allow to:\r | |
33 | - Create an AML tree;\r | |
34 | - Delete an AML tree;\r | |
35 | - Clone an AML tree/node;\r | |
36 | - Serialize an AML tree (convert the tree to a DSDT/SSDT table).\r | |
37 | @}\r | |
38 | */\r | |
39 | \r | |
40 | /** Serialize a tree to create a DSDT/SSDT table.\r | |
41 | \r | |
42 | If:\r | |
43 | - the content of BufferSize is >= to the size needed to serialize the\r | |
44 | definition block;\r | |
45 | - Buffer is not NULL;\r | |
46 | first serialize the ACPI DSDT/SSDT header from the root node,\r | |
47 | then serialize the AML blob from the rest of the tree.\r | |
48 | \r | |
49 | The content of BufferSize is always updated to the size needed to\r | |
50 | serialize the definition block.\r | |
51 | \r | |
52 | @ingroup CoreApis\r | |
53 | \r | |
54 | @param [in] RootNode Pointer to a root node.\r | |
55 | @param [in] Buffer Buffer to write the DSDT/SSDT table to.\r | |
56 | If Buffer is NULL, the size needed to\r | |
57 | serialize the DSDT/SSDT table is returned\r | |
58 | in BufferSize.\r | |
59 | @param [in, out] BufferSize Pointer holding the size of the Buffer.\r | |
60 | Its content is always updated to the size\r | |
61 | needed to serialize the DSDT/SSDT table.\r | |
62 | \r | |
63 | @retval EFI_SUCCESS The function completed successfully.\r | |
64 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
65 | @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.\r | |
66 | **/\r | |
67 | EFI_STATUS\r | |
68 | EFIAPI\r | |
69 | AmlSerializeTree (\r | |
70 | IN AML_ROOT_NODE_HANDLE RootNode,\r | |
fe2d8189 | 71 | IN UINT8 * Buffer OPTIONAL,\r |
31962537 PG |
72 | IN OUT UINT32 * BufferSize\r |
73 | );\r | |
74 | \r | |
75 | /** Clone a node.\r | |
76 | \r | |
77 | This function does not clone the children nodes.\r | |
78 | The cloned node returned is not attached to any tree.\r | |
79 | \r | |
80 | @ingroup CoreApis\r | |
81 | \r | |
82 | @param [in] Node Pointer to a node.\r | |
83 | @param [out] ClonedNode Pointer holding the cloned node.\r | |
84 | \r | |
85 | @retval EFI_SUCCESS The function completed successfully.\r | |
86 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
87 | @retval EFI_OUT_OF_RESOURCES Could not allocate memory.\r | |
88 | **/\r | |
89 | EFI_STATUS\r | |
90 | EFIAPI\r | |
91 | AmlCloneNode (\r | |
92 | IN AML_NODE_HANDLE Node,\r | |
93 | OUT AML_NODE_HANDLE * ClonedNode\r | |
94 | );\r | |
95 | \r | |
96 | /**\r | |
97 | @defgroup TreeModificationApis Tree modification APIs\r | |
98 | @ingroup AMLLib\r | |
99 | @{\r | |
100 | Tree modification APIs allow to add/remove/replace nodes that are in a\r | |
101 | variable list of arguments.\r | |
102 | \r | |
103 | No interface is provided to add/remove/replace nodes that are in a fixed\r | |
104 | list of arguments. Indeed, these nodes are the spine of the tree and a\r | |
105 | mismanipulation would make the tree inconsistent.\r | |
106 | \r | |
107 | It is however possible to modify the content of fixed argument nodes via\r | |
108 | @ref NodeInterfaceApis APIs.\r | |
109 | @}\r | |
110 | */\r | |
111 | \r | |
112 | /** Remove the Node from its parent's variable list of arguments.\r | |
113 | \r | |
114 | The function will fail if the Node is in its parent's fixed\r | |
115 | argument list.\r | |
116 | The Node is not deleted. The deletion is done separately\r | |
117 | from the removal.\r | |
118 | \r | |
119 | @ingroup TreeModificationApis\r | |
120 | \r | |
121 | @param [in] Node Pointer to a Node.\r | |
122 | Must be a data node or an object node.\r | |
123 | \r | |
124 | @retval EFI_SUCCESS The function completed successfully.\r | |
125 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
126 | **/\r | |
127 | EFI_STATUS\r | |
128 | EFIAPI\r | |
129 | AmlRemoveNodeFromVarArgList (\r | |
130 | IN AML_NODE_HANDLE Node\r | |
131 | );\r | |
132 | \r | |
133 | /** Add the NewNode to the head of the variable list of arguments\r | |
134 | of the ParentNode.\r | |
135 | \r | |
136 | @ingroup TreeModificationApis\r | |
137 | \r | |
138 | @param [in] ParentNode Pointer to the parent node.\r | |
139 | Must be a root or an object node.\r | |
140 | @param [in] NewNode Pointer to the node to add.\r | |
141 | \r | |
142 | @retval EFI_SUCCESS The function completed successfully.\r | |
143 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
144 | **/\r | |
145 | EFI_STATUS\r | |
146 | EFIAPI\r | |
147 | AmlVarListAddHead (\r | |
148 | IN AML_NODE_HANDLE ParentNode,\r | |
149 | IN AML_NODE_HANDLE NewNode\r | |
150 | );\r | |
151 | \r | |
152 | /** Add the NewNode to the tail of the variable list of arguments\r | |
153 | of the ParentNode.\r | |
154 | \r | |
155 | @ingroup TreeModificationApis\r | |
156 | \r | |
157 | @param [in] ParentNode Pointer to the parent node.\r | |
158 | Must be a root or an object node.\r | |
159 | @param [in] NewNode Pointer to the node to add.\r | |
160 | \r | |
161 | @retval EFI_SUCCESS The function completed successfully.\r | |
162 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
163 | **/\r | |
164 | EFI_STATUS\r | |
165 | EFIAPI\r | |
166 | AmlVarListAddTail (\r | |
167 | IN AML_NODE_HANDLE ParentNode,\r | |
168 | IN AML_NODE_HANDLE NewNode\r | |
169 | );\r | |
170 | \r | |
171 | /** Add the NewNode before the Node in the list of variable\r | |
172 | arguments of the Node's parent.\r | |
173 | \r | |
174 | @ingroup TreeModificationApis\r | |
175 | \r | |
176 | @param [in] Node Pointer to a node.\r | |
177 | Must be a root or an object node.\r | |
178 | @param [in] NewNode Pointer to the node to add.\r | |
179 | \r | |
180 | @retval EFI_SUCCESS The function completed successfully.\r | |
181 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
182 | **/\r | |
183 | EFI_STATUS\r | |
184 | EFIAPI\r | |
185 | AmlVarListAddBefore (\r | |
186 | IN AML_NODE_HANDLE Node,\r | |
187 | IN AML_NODE_HANDLE NewNode\r | |
188 | );\r | |
189 | \r | |
190 | /** Add the NewNode after the Node in the variable list of arguments\r | |
191 | of the Node's parent.\r | |
192 | \r | |
193 | @ingroup TreeModificationApis\r | |
194 | \r | |
195 | @param [in] Node Pointer to a node.\r | |
196 | Must be a root or an object node.\r | |
197 | @param [in] NewNode Pointer to the node to add.\r | |
198 | \r | |
199 | @retval EFI_SUCCESS The function completed successfully.\r | |
200 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
201 | **/\r | |
202 | EFI_STATUS\r | |
203 | EFIAPI\r | |
204 | AmlVarListAddAfter (\r | |
205 | IN AML_NODE_HANDLE Node,\r | |
206 | IN AML_NODE_HANDLE NewNode\r | |
207 | );\r | |
208 | \r | |
209 | /** Append a Resource Data node to the BufferOpNode.\r | |
210 | \r | |
211 | The Resource Data node is added at the end of the variable\r | |
212 | list of arguments of the BufferOpNode, but before the End Tag.\r | |
213 | If no End Tag is found, the function returns an error.\r | |
214 | \r | |
215 | @param [in] BufferOpNode Buffer node containing resource data elements.\r | |
216 | @param [in] NewRdNode The new Resource Data node to add.\r | |
217 | \r | |
218 | @retval EFI_SUCCESS The function completed successfully.\r | |
219 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
220 | **/\r | |
221 | EFI_STATUS\r | |
222 | EFIAPI\r | |
223 | AmlAppendRdNode (\r | |
224 | IN AML_OBJECT_NODE_HANDLE BufferOpNode,\r | |
225 | IN AML_DATA_NODE_HANDLE NewRdNode\r | |
226 | );\r | |
227 | \r | |
228 | /** Replace the OldNode, which is in a variable list of arguments,\r | |
229 | with the NewNode.\r | |
230 | \r | |
231 | Note: This function unlinks the OldNode from the tree. It is the callers\r | |
232 | responsibility to delete the OldNode if needed.\r | |
233 | \r | |
234 | @ingroup TreeModificationApis\r | |
235 | \r | |
236 | @param [in] OldNode Pointer to the node to replace.\r | |
237 | Must be a data node or an object node.\r | |
238 | @param [in] NewNode The new node to insert.\r | |
239 | Must be a data node or an object node.\r | |
240 | \r | |
241 | @retval EFI_SUCCESS The function completed successfully.\r | |
242 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
243 | **/\r | |
244 | EFI_STATUS\r | |
245 | EFIAPI\r | |
246 | AmlReplaceVariableArgument (\r | |
247 | IN AML_NODE_HANDLE OldNode,\r | |
248 | IN AML_NODE_HANDLE NewNode\r | |
249 | );\r | |
250 | \r | |
251 | /**\r | |
252 | @defgroup NodeInterfaceApis Node Interface APIs\r | |
253 | @ingroup AMLLib\r | |
254 | @{\r | |
255 | Node Interface APIs allow to query information from a node. Some functions\r | |
256 | expect a specific node type among the root/object/data node types.\r | |
257 | \r | |
258 | For instance, AmlGetRootNodeInfo expects to receive a root node.\r | |
259 | \r | |
260 | E.g.: Query the node type, the ACPI header stored in the root node,\r | |
261 | the OpCode/SubOpCode/PkgLen of an object node, the type of data\r | |
262 | stored in a data node, etc.\r | |
263 | \r | |
264 | These APIs also allow to update some information.\r | |
265 | \r | |
266 | E.g.: The ACPI header stored in the root node, the buffer of a data node.\r | |
267 | \r | |
268 | The information of object nodes and the data type of data nodes cannot be\r | |
269 | modified. This prevents the creation of an inconsistent tree.\r | |
270 | \r | |
271 | It is however possible to remove a node from a variable list of arguments\r | |
272 | and replace it. Use the @ref TreeModificationApis APIs for this.\r | |
273 | @}\r | |
274 | */\r | |
275 | \r | |
276 | /** Returns the tree node type (Root/Object/Data).\r | |
277 | \r | |
278 | @ingroup NodeInterfaceApis\r | |
279 | \r | |
280 | @param [in] Node Pointer to a Node.\r | |
281 | \r | |
282 | @return The node type.\r | |
283 | EAmlNodeUnknown if invalid parameter.\r | |
284 | **/\r | |
285 | EAML_NODE_TYPE\r | |
286 | EFIAPI\r | |
287 | AmlGetNodeType (\r | |
288 | IN AML_NODE_HANDLE Node\r | |
289 | );\r | |
290 | \r | |
291 | /** Get the RootNode information.\r | |
292 | The Node must be a root node.\r | |
293 | \r | |
294 | @ingroup NodeInterfaceApis\r | |
295 | \r | |
296 | @param [in] RootNode Pointer to a root node.\r | |
297 | @param [out] SdtHeaderBuffer Buffer to copy the ACPI DSDT/SSDT header to.\r | |
298 | \r | |
299 | @retval EFI_SUCCESS The function completed successfully.\r | |
300 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
301 | **/\r | |
302 | EFI_STATUS\r | |
303 | EFIAPI\r | |
304 | AmlGetRootNodeInfo (\r | |
305 | IN AML_ROOT_NODE_HANDLE RootNode,\r | |
306 | OUT EFI_ACPI_DESCRIPTION_HEADER * SdtHeaderBuffer\r | |
307 | );\r | |
308 | \r | |
309 | /** Get the ObjectNode information.\r | |
310 | The Node must be an object node.\r | |
311 | \r | |
312 | @ingroup NodeInterfaceApis\r | |
313 | \r | |
314 | @param [in] ObjectNode Pointer to an object node.\r | |
315 | @param [out] OpCode Pointer holding the OpCode.\r | |
316 | Optional, can be NULL.\r | |
317 | @param [out] SubOpCode Pointer holding the SubOpCode.\r | |
318 | Optional, can be NULL.\r | |
319 | @param [out] PkgLen Pointer holding the PkgLen.\r | |
320 | The PkgLen is 0 for nodes\r | |
321 | not having the Pkglen attribute.\r | |
322 | Optional, can be NULL.\r | |
323 | @param [out] IsNameSpaceNode Pointer holding TRUE if the node is defining\r | |
324 | or changing the NameSpace scope.\r | |
325 | E.g.: The "Name ()" and "Scope ()" ASL\r | |
326 | statements add/modify the NameSpace scope.\r | |
327 | Their corresponding node are NameSpace nodes.\r | |
328 | Optional, can be NULL.\r | |
329 | \r | |
330 | @retval EFI_SUCCESS The function completed successfully.\r | |
331 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
332 | **/\r | |
333 | EFI_STATUS\r | |
334 | EFIAPI\r | |
335 | AmlGetObjectNodeInfo (\r | |
336 | IN AML_OBJECT_NODE_HANDLE ObjectNode,\r | |
fe2d8189 MK |
337 | OUT UINT8 * OpCode OPTIONAL,\r |
338 | OUT UINT8 * SubOpCode OPTIONAL,\r | |
339 | OUT UINT32 * PkgLen OPTIONAL,\r | |
31962537 PG |
340 | OUT BOOLEAN * IsNameSpaceNode OPTIONAL\r |
341 | );\r | |
342 | \r | |
343 | /** Returns the count of the fixed arguments for the input Node.\r | |
344 | \r | |
345 | @ingroup NodeInterfaceApis\r | |
346 | \r | |
347 | @param [in] Node Pointer to an object node.\r | |
348 | \r | |
349 | @return Number of fixed arguments of the object node.\r | |
350 | Return 0 if the node is not an object node.\r | |
351 | **/\r | |
352 | UINT8\r | |
353 | AmlGetFixedArgumentCount (\r | |
354 | IN AML_OBJECT_NODE_HANDLE Node\r | |
355 | );\r | |
356 | \r | |
357 | /** Get the data type of the DataNode.\r | |
358 | The Node must be a data node.\r | |
359 | \r | |
360 | @ingroup NodeInterfaceApis\r | |
361 | \r | |
362 | @param [in] DataNode Pointer to a data node.\r | |
363 | @param [out] DataType Pointer holding the data type of the data buffer.\r | |
364 | \r | |
365 | @retval EFI_SUCCESS The function completed successfully.\r | |
366 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
367 | **/\r | |
368 | EFI_STATUS\r | |
369 | EFIAPI\r | |
370 | AmlGetNodeDataType (\r | |
371 | IN AML_DATA_NODE_HANDLE DataNode,\r | |
372 | OUT EAML_NODE_DATA_TYPE * DataType\r | |
373 | );\r | |
374 | \r | |
375 | /** Get the descriptor Id of the resource data element\r | |
376 | contained in the DataNode.\r | |
377 | \r | |
378 | The Node must be a data node.\r | |
379 | The Node must have the resource data type, i.e. have the\r | |
380 | EAmlNodeDataTypeResourceData data type.\r | |
381 | \r | |
382 | @ingroup NodeInterfaceApis\r | |
383 | \r | |
384 | @param [in] DataNode Pointer to a data node containing a\r | |
385 | resource data element.\r | |
386 | @param [out] ResourceDataType Pointer holding the descriptor Id of\r | |
387 | the resource data.\r | |
388 | \r | |
389 | @retval EFI_SUCCESS The function completed successfully.\r | |
390 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
391 | **/\r | |
392 | EFI_STATUS\r | |
393 | EFIAPI\r | |
394 | AmlGetResourceDataType (\r | |
395 | IN AML_DATA_NODE_HANDLE DataNode,\r | |
396 | OUT AML_RD_HEADER * ResourceDataType\r | |
397 | );\r | |
398 | \r | |
399 | /** Get the data buffer and size of the DataNode.\r | |
400 | The Node must be a data node.\r | |
401 | \r | |
402 | BufferSize is always updated to the size of buffer of the DataNode.\r | |
403 | \r | |
404 | If:\r | |
405 | - the content of BufferSize is >= to the DataNode's buffer size;\r | |
406 | - Buffer is not NULL;\r | |
407 | then copy the content of the DataNode's buffer in Buffer.\r | |
408 | \r | |
409 | @ingroup NodeInterfaceApis\r | |
410 | \r | |
411 | @param [in] DataNode Pointer to a data node.\r | |
412 | @param [out] Buffer Buffer to write the data to.\r | |
413 | Optional, if NULL, only update BufferSize.\r | |
414 | @param [in, out] BufferSize Pointer holding:\r | |
415 | - At entry, the size of the Buffer;\r | |
416 | - At exit, the size of the DataNode's\r | |
417 | buffer size.\r | |
418 | \r | |
419 | @retval EFI_SUCCESS The function completed successfully.\r | |
420 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
421 | **/\r | |
422 | EFI_STATUS\r | |
423 | EFIAPI\r | |
424 | AmlGetDataNodeBuffer (\r | |
425 | IN AML_DATA_NODE_HANDLE DataNode,\r | |
fe2d8189 | 426 | OUT UINT8 * Buffer OPTIONAL,\r |
31962537 PG |
427 | IN OUT UINT32 * BufferSize\r |
428 | );\r | |
429 | \r | |
430 | /** Update the ACPI DSDT/SSDT table header.\r | |
431 | \r | |
432 | The input SdtHeader information is copied to the tree RootNode.\r | |
433 | The table Length field is automatically updated.\r | |
434 | The checksum field is only updated when serializing the tree.\r | |
435 | \r | |
436 | @ingroup NodeInterfaceApis\r | |
437 | \r | |
438 | @param [in] RootNode Pointer to a root node.\r | |
439 | @param [in] SdtHeader Pointer to an ACPI DSDT/SSDT table header.\r | |
440 | \r | |
441 | @retval EFI_SUCCESS The function completed successfully.\r | |
442 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
443 | **/\r | |
444 | EFI_STATUS\r | |
445 | EFIAPI\r | |
446 | AmlUpdateRootNode (\r | |
447 | IN AML_ROOT_NODE_HANDLE RootNode,\r | |
448 | IN CONST EFI_ACPI_DESCRIPTION_HEADER * SdtHeader\r | |
449 | );\r | |
450 | \r | |
451 | /** Update an object node representing an integer with a new value.\r | |
452 | \r | |
453 | The object node must have one of the following OpCodes:\r | |
454 | - AML_BYTE_PREFIX\r | |
455 | - AML_WORD_PREFIX\r | |
456 | - AML_DWORD_PREFIX\r | |
457 | - AML_QWORD_PREFIX\r | |
458 | - AML_ZERO_OP\r | |
459 | - AML_ONE_OP\r | |
460 | \r | |
461 | The following OpCode is not supported:\r | |
462 | - AML_ONES_OP\r | |
463 | \r | |
464 | @param [in] IntegerOpNode Pointer an object node containing an integer.\r | |
465 | Must not be an object node with an AML_ONES_OP\r | |
466 | OpCode.\r | |
467 | @param [in] NewInteger New integer value to set.\r | |
468 | \r | |
469 | @retval EFI_SUCCESS The function completed successfully.\r | |
470 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
471 | **/\r | |
472 | EFI_STATUS\r | |
473 | EFIAPI\r | |
474 | AmlUpdateInteger (\r | |
475 | IN AML_OBJECT_NODE_HANDLE IntegerOpNode,\r | |
476 | IN UINT64 NewInteger\r | |
477 | );\r | |
478 | \r | |
479 | /** Update the buffer of a data node.\r | |
480 | \r | |
481 | Note: The data type of the buffer's content must match the data type of the\r | |
482 | DataNode. This is a hard restriction to prevent undesired behaviour.\r | |
483 | \r | |
484 | @ingroup NodeInterfaceApis\r | |
485 | \r | |
486 | @param [in] DataNode Pointer to a data node.\r | |
487 | @param [in] DataType Data type of the Buffer's content.\r | |
488 | @param [in] Buffer Buffer containing the new data. The content of\r | |
489 | the Buffer is copied.\r | |
490 | @param [in] Size Size of the Buffer.\r | |
491 | \r | |
492 | @retval EFI_SUCCESS The function completed successfully.\r | |
493 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
494 | @retval EFI_UNSUPPORTED Operation not supporter.\r | |
495 | **/\r | |
496 | EFI_STATUS\r | |
497 | EFIAPI\r | |
498 | AmlUpdateDataNode (\r | |
499 | IN AML_DATA_NODE_HANDLE DataNode,\r | |
500 | IN EAML_NODE_DATA_TYPE DataType,\r | |
501 | IN UINT8 * Buffer,\r | |
502 | IN UINT32 Size\r | |
503 | );\r | |
504 | \r | |
505 | /**\r | |
506 | @defgroup NavigationApis Navigation APIs\r | |
507 | @ingroup AMLLib\r | |
508 | @{\r | |
509 | Navigation APIs allow to navigate in the AML tree. There are different\r | |
510 | ways to navigate in the tree by:\r | |
511 | - Direct relation (@ref CoreNavigationApis);\r | |
512 | - Enumeration: enumerate all the nodes and call a callback function\r | |
513 | (@ref EnumerationApis);\r | |
514 | - Iteration: instantiate an iterator and use it to navigate\r | |
515 | (@ref IteratorApis);\r | |
516 | - NameSpace path: use the AML namespace to navigate the tree\r | |
517 | (@ref NameSpaceApis).\r | |
518 | @}\r | |
519 | */\r | |
520 | \r | |
521 | /**\r | |
522 | @defgroup CoreNavigationApis Core Navigation APIs\r | |
523 | @ingroup NavigationApis\r | |
524 | @{\r | |
525 | Core Navigation APIs allow to get a node by specifying a relation.\r | |
526 | \r | |
527 | E.g.: Get the parent, the n-th fixed argument, the next variable\r | |
528 | argument, etc.\r | |
529 | @}\r | |
530 | */\r | |
531 | \r | |
532 | /** Get the parent node of the input Node.\r | |
533 | \r | |
534 | @ingroup CoreNavigationApis\r | |
535 | \r | |
536 | @param [in] Node Pointer to a node.\r | |
537 | \r | |
538 | @return The parent node of the input Node.\r | |
539 | NULL otherwise.\r | |
540 | **/\r | |
541 | AML_NODE_HANDLE\r | |
542 | EFIAPI\r | |
543 | AmlGetParent (\r | |
544 | IN AML_NODE_HANDLE Node\r | |
545 | );\r | |
546 | \r | |
547 | /** Get the node at the input Index in the fixed argument list of the input\r | |
548 | ObjectNode.\r | |
549 | \r | |
550 | @ingroup CoreNavigationApis\r | |
551 | \r | |
552 | @param [in] ObjectNode Pointer to an object node.\r | |
553 | @param [in] Index The Index of the fixed argument to get.\r | |
554 | \r | |
555 | @return The node at the input Index in the fixed argument list\r | |
556 | of the input ObjectNode.\r | |
557 | NULL otherwise, e.g. if the node is not an object node, or no\r | |
558 | node is available at this Index.\r | |
559 | **/\r | |
560 | AML_NODE_HANDLE\r | |
561 | EFIAPI\r | |
562 | AmlGetFixedArgument (\r | |
563 | IN AML_OBJECT_NODE_HANDLE ObjectNode,\r | |
564 | IN EAML_PARSE_INDEX Index\r | |
565 | );\r | |
566 | \r | |
567 | /** Get the sibling node among the nodes being in\r | |
568 | the same variable argument list.\r | |
569 | \r | |
570 | (ParentNode) /-i # Child of fixed argument b\r | |
571 | \ /\r | |
572 | |- [a][b][c][d] # Fixed Arguments\r | |
573 | |- {(VarArgNode)->(f)->(g)} # Variable Arguments\r | |
574 | \\r | |
575 | \-h # Child of variable argument e\r | |
576 | \r | |
577 | Node must be in a variable list of arguments.\r | |
578 | Traversal Order: VarArgNode, f, g, NULL\r | |
579 | \r | |
580 | @ingroup CoreNavigationApis\r | |
581 | \r | |
582 | @param [in] VarArgNode Pointer to a node.\r | |
583 | Must be in a variable list of arguments.\r | |
584 | \r | |
585 | @return The next node after VarArgNode in the variable list of arguments.\r | |
586 | Return NULL if\r | |
587 | - VarArgNode is the last node of the list, or\r | |
588 | - VarArgNode is not part of a variable list of arguments.\r | |
589 | **/\r | |
590 | AML_NODE_HANDLE\r | |
591 | EFIAPI\r | |
592 | AmlGetSiblingVariableArgument (\r | |
593 | IN AML_NODE_HANDLE VarArgNode\r | |
594 | );\r | |
595 | \r | |
596 | /** Get the next variable argument.\r | |
597 | \r | |
598 | (Node) /-i # Child of fixed argument b\r | |
599 | \ /\r | |
600 | |- [a][b][c][d] # Fixed Arguments\r | |
601 | |- {(e)->(f)->(g)} # Variable Arguments\r | |
602 | \\r | |
603 | \-h # Child of variable argument e\r | |
604 | \r | |
605 | Traversal Order: e, f, g, NULL\r | |
606 | \r | |
607 | @ingroup CoreNavigationApis\r | |
608 | \r | |
609 | @param [in] Node Pointer to a Root node or Object Node.\r | |
610 | @param [in] CurrVarArg Pointer to the Current Variable Argument.\r | |
611 | \r | |
612 | @return The node after the CurrVarArg in the variable list of arguments.\r | |
613 | If CurrVarArg is NULL, return the first node of the\r | |
614 | variable argument list.\r | |
615 | Return NULL if\r | |
616 | - CurrVarArg is the last node of the list, or\r | |
617 | - Node does not have a variable list of arguments.\r | |
618 | **/\r | |
619 | AML_NODE_HANDLE\r | |
620 | EFIAPI\r | |
621 | AmlGetNextVariableArgument (\r | |
622 | IN AML_NODE_HANDLE Node,\r | |
623 | IN AML_NODE_HANDLE CurrVarArg\r | |
624 | );\r | |
625 | \r | |
626 | /** Get the previous variable argument.\r | |
627 | \r | |
628 | (Node) /-i # Child of fixed argument b\r | |
629 | \ /\r | |
630 | |- [a][b][c][d] # Fixed Arguments\r | |
631 | |- {(e)->(f)->(g)} # Variable Arguments\r | |
632 | \\r | |
633 | \-h # Child of variable argument e\r | |
634 | \r | |
635 | Traversal Order: g, f, e, NULL\r | |
636 | \r | |
637 | @ingroup CoreNavigationApis\r | |
638 | \r | |
639 | @param [in] Node Pointer to a root node or an object node.\r | |
640 | @param [in] CurrVarArg Pointer to the Current Variable Argument.\r | |
641 | \r | |
642 | @return The node before the CurrVarArg in the variable list of\r | |
643 | arguments.\r | |
644 | If CurrVarArg is NULL, return the last node of the\r | |
645 | variable list of arguments.\r | |
646 | Return NULL if:\r | |
647 | - CurrVarArg is the first node of the list, or\r | |
648 | - Node doesn't have a variable list of arguments.\r | |
649 | **/\r | |
650 | AML_NODE_HANDLE\r | |
651 | EFIAPI\r | |
652 | AmlGetPreviousVariableArgument (\r | |
653 | IN AML_NODE_HANDLE Node,\r | |
654 | IN AML_NODE_HANDLE CurrVarArg\r | |
655 | );\r | |
656 | \r | |
657 | /**\r | |
658 | @defgroup EnumerationApis Enumeration APIs\r | |
659 | @ingroup NavigationApis\r | |
660 | @{\r | |
661 | Enumeration APIs are navigation APIs, allowing to call a callback function\r | |
662 | on each node enumerated. Nodes are enumerated in the AML bytestream order,\r | |
663 | i.e. in a depth first order.\r | |
664 | @}\r | |
665 | */\r | |
666 | \r | |
667 | /**\r | |
668 | Callback function prototype used when iterating through the tree.\r | |
669 | \r | |
670 | @ingroup EnumerationApis\r | |
671 | \r | |
672 | @param [in] Node The Node currently being processed.\r | |
673 | @param [in, out] Context A context for the callback function.\r | |
674 | Can be optional.\r | |
675 | @param [in, out] Status End the enumeration if pointing to a value\r | |
676 | evaluated to TRUE.\r | |
677 | Can be optional.\r | |
678 | \r | |
679 | @retval TRUE if the enumeration can continue or has finished without\r | |
680 | interruption.\r | |
681 | @retval FALSE if the enumeration needs to stopped or has stopped.\r | |
682 | **/\r | |
683 | typedef\r | |
684 | BOOLEAN\r | |
685 | (EFIAPI * EDKII_AML_TREE_ENUM_CALLBACK) (\r | |
686 | IN AML_NODE_HANDLE Node,\r | |
fe2d8189 | 687 | IN OUT VOID * Context OPTIONAL,\r |
31962537 PG |
688 | IN OUT EFI_STATUS * Status OPTIONAL\r |
689 | );\r | |
690 | \r | |
691 | /** Enumerate all nodes of the subtree under the input Node in the AML\r | |
692 | bytestream order (i.e. in a depth first order), and call the CallBack\r | |
693 | function with the input Context.\r | |
694 | The prototype of the Callback function is EDKII_AML_TREE_ENUM_CALLBACK.\r | |
695 | \r | |
696 | @ingroup EnumerationApis\r | |
697 | \r | |
698 | @param [in] Node Enumerate nodes of the subtree under this Node.\r | |
699 | Must be a valid node.\r | |
700 | @param [in] CallBack Callback function to call on each node.\r | |
701 | @param [in, out] Context Void pointer used to pass some information\r | |
702 | to the Callback function.\r | |
703 | Optional, can be NULL.\r | |
704 | @param [out] Status Optional parameter that can be used to get\r | |
705 | the status of the Callback function.\r | |
706 | If used, need to be init to EFI_SUCCESS.\r | |
707 | \r | |
708 | @retval TRUE if the enumeration can continue or has finished without\r | |
709 | interruption.\r | |
710 | @retval FALSE if the enumeration needs to stopped or has stopped.\r | |
711 | **/\r | |
712 | BOOLEAN\r | |
713 | EFIAPI\r | |
714 | AmlEnumTree (\r | |
715 | IN AML_NODE_HANDLE Node,\r | |
716 | IN EDKII_AML_TREE_ENUM_CALLBACK CallBack,\r | |
fe2d8189 | 717 | IN OUT VOID * Context OPTIONAL,\r |
31962537 PG |
718 | OUT EFI_STATUS * Status OPTIONAL\r |
719 | );\r | |
720 | \r | |
721 | /**\r | |
722 | @defgroup NameSpaceApis NameSpace APIs\r | |
723 | @ingroup NavigationApis\r | |
724 | @{\r | |
725 | NameSpace APIs allow to find a node from an AML path, and reciprocally\r | |
726 | get the AML path of a node.\r | |
727 | \r | |
728 | These APIs only operate on "NameSpace nodes", i.e. nodes that are\r | |
729 | part of the AML namespace. These are the root node and object nodes\r | |
730 | acknowledged by AmlGetObjectNodeInfo in @ref NodeInterfaceApis.\r | |
731 | @}\r | |
732 | */\r | |
733 | \r | |
734 | /** Build the absolute ASL pathname to Node.\r | |
735 | \r | |
736 | BufferSize is always updated to the size of the pathname.\r | |
737 | \r | |
738 | If:\r | |
739 | - the content of BufferSize is >= to the size of the pathname AND;\r | |
740 | - Buffer is not NULL;\r | |
741 | then copy the pathname in the Buffer. A buffer of the size\r | |
742 | MAX_ASL_NAMESTRING_SIZE is big enough to receive any ASL pathname.\r | |
743 | \r | |
744 | @ingroup NameSpaceApis\r | |
745 | \r | |
746 | @param [in] Node Node to build the absolute path to.\r | |
747 | Must be a root node, or a namespace node.\r | |
748 | @param [out] Buffer Buffer to write the path to.\r | |
749 | If NULL, only update *BufferSize.\r | |
750 | @param [in, out] BufferSize Pointer holding:\r | |
751 | - At entry, the size of the Buffer;\r | |
752 | - At exit, the size of the pathname.\r | |
753 | \r | |
754 | @retval EFI_SUCCESS The function completed successfully.\r | |
755 | @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.\r | |
756 | @retval EFI_INVALID_PARAMETER Invalid parameter.\r | |
757 | @retval EFI_OUT_OF_RESOURCES Out of memory.\r | |
758 | **/\r | |
759 | EFI_STATUS\r | |
760 | EFIAPI\r | |
761 | AmlGetAslPathName (\r | |
762 | IN AML_NODE_HANDLE Node,\r | |
763 | OUT CHAR8 * Buffer,\r | |
764 | IN OUT UINT32 * BufferSize\r | |
765 | );\r | |
766 | \r | |
767 | #endif // AML_CORE_INTERFACE_H_\r |