acpi.h@ 109019

Last change on this file since 109019 was 108253, checked in by vboxsync, 2 months ago
scm fixes
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 18.5 KB

Line
1	/* $Id: acpi.h 108253 2025-02-17 10:44:24Z vboxsync $ */
2	/** @file
3	* IPRT - Internal RTAcpi header.
4	*/
5
6	/*
7	* Copyright (C) 2025 Oracle and/or its affiliates.
8	*
9	* This file is part of VirtualBox base platform packages, as
10	* available from https://www.virtualbox.org.
11	*
12	* This program is free software; you can redistribute it and/or
13	* modify it under the terms of the GNU General Public License
14	* as published by the Free Software Foundation, in version 3 of the
15	* License.
16	*
17	* This program is distributed in the hope that it will be useful, but
18	* WITHOUT ANY WARRANTY; without even the implied warranty of
19	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20	* General Public License for more details.
21	*
22	* You should have received a copy of the GNU General Public License
23	* along with this program; if not, see <https://www.gnu.org/licenses>.
24	*
25	* The contents of this file may alternatively be used under the terms
26	* of the Common Development and Distribution License Version 1.0
27	* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
28	* in the VirtualBox distribution, in which case the provisions of the
29	* CDDL are applicable instead of those of the GPL.
30	*
31	* You may elect to license modified versions of this file under the
32	* terms and conditions of either the GPL or the CDDL or both.
33	*
34	* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
35	*/
36
37	#ifndef IPRT_INCLUDED_INTERNAL_acpi_h
38	#define IPRT_INCLUDED_INTERNAL_acpi_h
39	#ifndef RT_WITHOUT_PRAGMA_ONCE
40	# pragma once
41	#endif
42
43	#include <iprt/acpi.h>
44	#include <iprt/list.h>
45
46	RT_C_DECLS_BEGIN
47
48	/** Pointer to an ACPI AST node. */
49	typedef struct RTACPIASTNODE *PRTACPIASTNODE;
50	/** Pointer to a const ACPI AST node. */
51	typedef const struct RTACPIASTNODE *PCRTACPIASTNODE;
52	/** Pointer to an ACPI namespace entry. */
53	typedef struct RTACPINSENTRY *PRTACPINSENTRY;
54
55
56	/**
57	* External declaration.
58	*/
59	typedef struct RTACPIASLEXTERNAL
60	{
61	/** List node for the list of externals. */
62	RTLISTNODE NdExternal;
63	/** The object type. */
64	RTACPIOBJTYPE enmObjType;
65	/** For methods this will hold the argument count. */
66	uint32_t cArgs;
67	/** The name as parsed from the source file. */
68	const char *pszName;
69	/** Size of the full name path in characters excluding the terminating zero. */
70	size_t cchNamePath;
71	/** The name path - variable in size. */
72	char szNamePath[1];
73	} RTACPIASLEXTERNAL;
74	/** Pointer to an external declaration. */
75	typedef RTACPIASLEXTERNAL *PRTACPIASLEXTERNAL;
76	/** Pointer to a const external declaration. */
77	typedef const RTACPIASLEXTERNAL *PCRTACPIASLEXTERNAL;
78
79
80	/**
81	* ACPI namespace entry type.
82	*/
83	typedef enum RTACPINSENTRYTYPE
84	{
85	/** Invalid type. */
86	kAcpiNsEntryType_Invalid = 0,
87	/** Namespace entry points to an AST node. */
88	kAcpiNsEntryType_AstNode,
89	/** Namesapce entry points to an external declaration. */
90	kAcpiNsEntryType_External,
91	/** Namespace entry is a resource field containing an offset and number of bits. */
92	kAcpiNsEntryType_ResourceField,
93	/** 32bit hack. */
94	kAcpiNsEntryType_32Bit_Hack = 0x7fffffff
95	} RTACPINSENTRYTYPE;
96
97
98	/**
99	* An ACPI namespace entry.
100	*/
101	typedef struct RTACPINSENTRY
102	{
103	/** Node for the namespace list. */
104	RTLISTNODE NdNs;
105	/** Pointer to the parent in the namespace, NULL if this is the root. */
106	PRTACPINSENTRY pParent;
107	/** The name segment identifying the entry. */
108	char achNameSeg[4];
109	/** Namespace entry type. */
110	RTACPINSENTRYTYPE enmType;
111	/** Type dependent data. */
112	union
113	{
114	/** The AST node associated with this namespace entry. */
115	PCRTACPIASTNODE pAstNd;
116	/** Pointer to the external declaration. */
117	PCRTACPIASLEXTERNAL pExternal;
118	/** Resource field data. */
119	struct
120	{
121	/** Bit offset for resource fields. */
122	uint32_t offBits;
123	/** Bit count for resource fields. */
124	uint32_t cBits;
125	} RsrcFld;
126	};
127	/** List of namespace entries below this entry. */
128	RTLISTANCHOR LstNsEntries;
129	} RTACPINSENTRY;
130	/** Pointer to a const ACPI namespace entry. */
131	typedef const RTACPINSENTRY *PCRTACPINSENTRY;
132
133
134	/**
135	* AST node argument type.
136	*/
137	typedef enum RTACPIASTARGTYPE
138	{
139	kAcpiAstArgType_Invalid = 0,
140	kAcpiAstArgType_AstNode,
141	kAcpiAstArgType_NameString,
142	kAcpiAstArgType_Bool,
143	kAcpiAstArgType_U8,
144	kAcpiAstArgType_U16,
145	kAcpiAstArgType_U32,
146	kAcpiAstArgType_U64,
147	kAcpiAstArgType_ObjType,
148	kAcpiAstArgType_RegionSpace,
149	kAcpiAstArgType_FieldAcc,
150	kAcpiAstArgType_FieldUpdate,
151	kAcpiAstArgType_StringLiteral,
152	kAcpiAstArgType_32Bit_Hack = 0x7fffffff
153	} RTACPIASTARGTYPE;
154
155
156	/**
157	* An AST node argument
158	*/
159	typedef struct RTACPIASTARG
160	{
161	/** Argument type. */
162	RTACPIASTARGTYPE enmType;
163	/** Type dependent data. */
164	union
165	{
166	uintptr_t uPtrInternal;
167	PRTACPIASTNODE pAstNd;
168	const char *pszNameString;
169	const char *pszStrLit;
170	bool f;
171	uint8_t u8;
172	uint16_t u16;
173	uint32_t u32;
174	uint64_t u64;
175	RTACPIOBJTYPE enmObjType;
176	RTACPIOPREGIONSPACE enmRegionSpace;
177	RTACPIFIELDACC enmFieldAcc;
178	RTACPIFIELDUPDATE enmFieldUpdate;
179	} u;
180	} RTACPIASTARG;
181	/** Pointer to an AST node argument. */
182	typedef RTACPIASTARG *PRTACPIASTARG;
183	/** Pointer to a const AST node argument. */
184	typedef const RTACPIASTARG *PCRTACPIASTARG;
185
186
187	/**
188	* The ACPI AST node op.
189	*/
190	typedef enum RTACPIASTNODEOP
191	{
192	kAcpiAstNodeOp_Invalid = 0,
193	kAcpiAstNodeOp_Identifier,
194	kAcpiAstNodeOp_StringLiteral,
195	kAcpiAstNodeOp_Number,
196	kAcpiAstNodeOp_Scope,
197	kAcpiAstNodeOp_Processor,
198	kAcpiAstNodeOp_External,
199	kAcpiAstNodeOp_Method,
200	kAcpiAstNodeOp_Device,
201	kAcpiAstNodeOp_If,
202	kAcpiAstNodeOp_Else,
203	kAcpiAstNodeOp_LAnd,
204	kAcpiAstNodeOp_LOr,
205	kAcpiAstNodeOp_LEqual,
206	kAcpiAstNodeOp_LGreater,
207	kAcpiAstNodeOp_LGreaterEqual,
208	kAcpiAstNodeOp_LLess,
209	kAcpiAstNodeOp_LLessEqual,
210	kAcpiAstNodeOp_LNot,
211	kAcpiAstNodeOp_LNotEqual,
212	kAcpiAstNodeOp_Zero,
213	kAcpiAstNodeOp_One,
214	kAcpiAstNodeOp_Ones,
215	kAcpiAstNodeOp_Return,
216	kAcpiAstNodeOp_Unicode,
217	kAcpiAstNodeOp_OperationRegion,
218	kAcpiAstNodeOp_Field,
219	kAcpiAstNodeOp_Name,
220	kAcpiAstNodeOp_ResourceTemplate,
221	kAcpiAstNodeOp_Arg0,
222	kAcpiAstNodeOp_Arg1,
223	kAcpiAstNodeOp_Arg2,
224	kAcpiAstNodeOp_Arg3,
225	kAcpiAstNodeOp_Arg4,
226	kAcpiAstNodeOp_Arg5,
227	kAcpiAstNodeOp_Arg6,
228	kAcpiAstNodeOp_Local0,
229	kAcpiAstNodeOp_Local1,
230	kAcpiAstNodeOp_Local2,
231	kAcpiAstNodeOp_Local3,
232	kAcpiAstNodeOp_Local4,
233	kAcpiAstNodeOp_Local5,
234	kAcpiAstNodeOp_Local6,
235	kAcpiAstNodeOp_Local7,
236	kAcpiAstNodeOp_Package,
237	kAcpiAstNodeOp_Buffer,
238	kAcpiAstNodeOp_ToUuid,
239	kAcpiAstNodeOp_DerefOf,
240	kAcpiAstNodeOp_Index,
241	kAcpiAstNodeOp_Store,
242	kAcpiAstNodeOp_Break,
243	kAcpiAstNodeOp_Continue,
244	kAcpiAstNodeOp_Add,
245	kAcpiAstNodeOp_Subtract,
246	kAcpiAstNodeOp_Multiply,
247	kAcpiAstNodeOp_And,
248	kAcpiAstNodeOp_Nand,
249	kAcpiAstNodeOp_Or,
250	kAcpiAstNodeOp_Xor,
251	kAcpiAstNodeOp_ShiftLeft,
252	kAcpiAstNodeOp_ShiftRight,
253	kAcpiAstNodeOp_Not,
254	kAcpiAstNodeOp_Notify,
255	kAcpiAstNodeOp_SizeOf,
256	kAcpiAstNodeOp_While,
257	kAcpiAstNodeOp_Increment,
258	kAcpiAstNodeOp_Decrement,
259	kAcpiAstNodeOp_CondRefOf,
260	kAcpiAstNodeOp_IndexField,
261	kAcpiAstNodeOp_EisaId,
262	kAcpiAstNodeOp_CreateField,
263	kAcpiAstNodeOp_CreateBitField,
264	kAcpiAstNodeOp_CreateByteField,
265	kAcpiAstNodeOp_CreateWordField,
266	kAcpiAstNodeOp_CreateDWordField,
267	kAcpiAstNodeOp_CreateQWordField,
268	kAcpiAstNodeOp_ConcatenateResTemplate,
269	kAcpiAstNodeOp_FindSetLeftBit,
270	kAcpiAstNodeOp_FindSetRightBit,
271	kAcpiAstNodeOp_32Bit_Hack = 0x7fffffff
272	} RTACPIASTNODEOP;
273
274
275	/**
276	* The core ACPI AST node.
277	*/
278	typedef struct RTACPIASTNODE
279	{
280	/** List node. */
281	RTLISTNODE NdAst;
282	/** The owning namespace entry. */
283	PCRTACPINSENTRY pNsEntry;
284	/** The AML op defining the node. */
285	RTACPIASTNODEOP enmOp;
286	/** Some additional flags. */
287	uint32_t fFlags;
288	/** Operation dependent data. */
289	union
290	{
291	/** List of other AST nodes for the opened scope if indicated by the AST flags (RTACPIASTNODE). */
292	RTLISTANCHOR LstScopeNodes;
293	/** Pointer to the identifier if an identifier node. */
294	const char *pszIde;
295	/** Pointer to the string literal if a string literal node. */
296	const char *pszStrLit;
297	/** A number */
298	uint64_t u64;
299	struct
300	{
301	/** Pointer to the field unit list - freed with RTMemFree() when the node is freed. */
302	PRTACPIFIELDENTRY paFields;
303	/** Number of field entries. */
304	uint32_t cFields;
305	} Fields;
306	/** The resource template. */
307	RTACPIRES hAcpiRes;
308	};
309	/** Number of "arguments" for the opcode following (for example Scope(), Method(), If(), etc., i.e. anything requiring () after the keyword ). */
310	uint8_t cArgs;
311	/** Padding */
312	uint8_t abRsvd[2];
313	/** The AST node arguments - variable in size. */
314	RTACPIASTARG aArgs[1];
315	} RTACPIASTNODE;
316
317	/** Default flags. */
318	#define RTACPI_AST_NODE_F_DEFAULT 0
319	/** The AST node opens a new scope. */
320	#define RTACPI_AST_NODE_F_NEW_SCOPE RT_BIT_32(0)
321	/** The AST node has an associated namespace entry. */
322	#define RTACPI_AST_NODE_F_NS_ENTRY RT_BIT_32(1)
323	/** The AST node switches the namespace (only Scope). */
324	#define RTACPI_AST_NODE_F_NS_SWITCH RT_BIT_32(2)
325
326
327	/**
328	* An ACPI namespace root
329	*/
330	typedef struct RTACPINSROOT
331	{
332	/** Root namespace entry. */
333	RTACPINSENTRY RootEntry;
334	/** Current top of the stack. */
335	uint8_t idxNsStack;
336	/** Stack of name space entries for navigation - 255 entries
337	* is enough because a path name can only be encoded with 255 entries. */
338	PRTACPINSENTRY aNsStack[255];
339	} RTACPINSROOT;
340	/** Pointer to an ACPI namespace root. */
341	typedef RTACPINSROOT *PRTACPINSROOT;
342	/** Pointer to a const ACPI namespace root. */
343	typedef const RTACPINSROOT *PCRTACPINSROOT;
344
345
346	/**
347	* Allocates a new ACPI AST node initialized with the given properties.
348	*
349	* @returns Pointer to the new ACPI AST node or NULL if out of memory.
350	* @param pNs The namespace this AST node will be part of.
351	* @param enmOp The operation of the AST node.
352	* @param fFlags Flags for this node.
353	* @param cArgs Number of arguments to allocate.
354	*/
355	DECLHIDDEN(PRTACPIASTNODE) rtAcpiAstNodeAlloc(PCRTACPINSROOT pNs, RTACPIASTNODEOP enmOp, uint32_t fFlags, uint8_t cArgs);
356
357
358	/**
359	* Frees the given AST node and all children nodes linked to this one.
360	*
361	* @param pAstNd The AST node to free.
362	*/
363	DECLHIDDEN(void) rtAcpiAstNodeFree(PRTACPIASTNODE pAstNd);
364
365
366	/**
367	* Does a few transformations on the given AST node and its children where required.
368	*
369	* @returns IPRT status.
370	* @param pAstNd The AST node to transform.
371	* @param pNsRoot The namespace root.
372	* @param pErrInfo Some additional error information on failure.
373	*/
374	DECLHIDDEN(int) rtAcpiAstNodeTransform(PRTACPIASTNODE pAstNd, PRTACPINSROOT pNsRoot, PRTERRINFO pErrInfo);
375
376
377	/**
378	* Creates a new namespace and returns the root.
379	*
380	* @returns Pointer to the namespace root or NULL if out of memory.
381	*/
382	DECLHIDDEN(PRTACPINSROOT) rtAcpiNsCreate(void);
383
384
385	/**
386	* Destroys the given namespace, freeing all allocated resources,
387	* including all namespace entries int it.
388	*
389	* @param pNsRoot The namespace root to destroy.
390	*/
391	DECLHIDDEN(void) rtAcpiNsDestroy(PRTACPINSROOT pNsRoot);
392
393
394	/**
395	* Switches to the given existing namespace.
396	*
397	* @returns IPRT status code.
398	* @param pNsRoot The namespace root.
399	* @param pszNameString The namespace to switch to.
400	*/
401	DECLHIDDEN(int) rtAcpiNsSwitchTo(PRTACPINSROOT pNsRoot, const char *pszNameString);
402
403
404	/**
405	* Adds a new namespace entry to the given name space - AST node variant.
406	*
407	* @returns IPRT status code.
408	* @param pNsRoot The namespace root to add the entry to.
409	* @param pszNameString An ACPI NameString (either segment or path).
410	* @param pAstNd The AST node to associate with the entry.
411	* @param fSwitchTo Flag whether to switch the current point for the namespace to this entry.
412	*/
413	DECLHIDDEN(int) rtAcpiNsAddEntryAstNode(PRTACPINSROOT pNsRoot, const char *pszNameString, PCRTACPIASTNODE pAstNd, bool fSwitchTo);
414
415
416	/**
417	* Adds a new namespace entry to the given name space - resource field.
418	*
419	* @returns IPRT status code.
420	* @param pNsRoot The namespace root to add the entry to.
421	* @param pszNameString An ACPI NameString (either segment or path).
422	* @param offBits Bit offset from the beginning of the resource.
423	* @param cBits NUmber of bits this resource field has.
424	*/
425	DECLHIDDEN(int) rtAcpiNsAddEntryRsrcField(PRTACPINSROOT pNsRoot, const char *pszNameString, uint32_t offBits, uint32_t cBits);
426
427
428	/**
429	* Adds a new namespace entry to the given name space - resource field.
430	*
431	* @returns IPRT status code.
432	* @param pNsRoot The namespace root to add the entry to.
433	* @param pszNameString An ACPI NameString (either segment or path).
434	* @param pExternal The external to add the entry for.
435	*/
436	DECLHIDDEN(int) rtAcpiNsAddEntryExternal(PRTACPINSROOT pNsRoot, const char *pszNameString, PCRTACPIASLEXTERNAL pExternal);
437
438
439	/**
440	* Queries the name path for the given name string based on the current scope.
441	*
442	* @returns IPRT status code.
443	* @retval VERR_NOT_FOUND if the name string can't be resolved to a name path with the given namespace.
444	* @retval VERR_BUFFER_OVERFLOW if the buffer for holding the name path is too small. pcchNamePath will
445	* hold the required number of characters, excluding the zero temrinator.
446	* @param pNsRoot The namespace root.
447	* @param pszNameString The name string to query the name path for.
448	* @param pachNamePath Where to store the name path (including zero terminator), or NULL if the size is queried.
449	* @param pcchNamePath Holds the size of the name path buffer on input, on successful return
450	* holds the actual length of the name path excluding the zero terminator.
451	*/
452	DECLHIDDEN(int) rtAcpiNsQueryNamePathForNameString(PRTACPINSROOT pNsRoot, const char pszNameString, char pachNamePath, size_t *pcchNamePath);
453
454
455	/**
456	* Tries to compress the given name string to a shorter representation.
457	*
458	* @returns IPRT status code.
459	* @param pNsRoot The namespace root.
460	* @param pNsEntry The namespace entry the namestring belongs to.
461	* @param pszNameString The name string to try to compress.
462	* @param pszNameStringComp Where to store the result.
463	* @param cchNameStringComp Size of the buffer in characters.
464	*
465	* @note This will only try to compress absolute name paths by converting it to a relative one
466	* (\\SEG1 -> SEG1 for example if the current scope is \\) Otherwise the string is just copied as is.
467	*/
468	DECLHIDDEN(int) rtAcpiNsCompressNameString(PCRTACPINSROOT pNsRoot, PCRTACPINSENTRY pNsEntry, const char pszNameString, char pszNameStringComp, size_t cchNameStringComp);
469
470
471	/**
472	* Tries to convert an absolute namestring to a relative one from the given namespace.
473	*
474	* @returns IPRT status code.
475	* @param pNsRoot The namespace root.
476	* @param pNsEntrySrc The source namespace.
477	* @param pszNameStringDst The destination name string to try to convert.
478	* @param pszNameStringRel Where to store the result.
479	* @param cchNameStringRel Size of the buffer in characters.
480	*
481	* @note This will only try to resolve absolute name paths. Others are just copied as is.
482	*/
483	DECLHIDDEN(int) rtAcpiNsAbsoluteNameStringToRelative(PRTACPINSROOT pNsRoot, PCRTACPINSENTRY pNsEntrySrc,
484	const char *pszNameStringDst,
485	char *pszNameStringRel, size_t cchNameStringRel);
486
487
488	/**
489	* Pops the current name space entry from the stack and returns to the previous one.
490	*
491	* @returns IPRT status code.
492	* @param pNsRoot The namespace root.
493	*/
494	DECLHIDDEN(int) rtAcpiNsPop(PRTACPINSROOT pNsRoot);
495
496
497	/**
498	* Looks up the given name string and returns the namespace entry if found.
499	*
500	* @returns Pointer to the namespace entry or NULL if not found.
501	* @param pNsRoot The namespace root.
502	* @param pszNameString The ACPI NameString (either segment or path) to lookup.
503	*/
504	DECLHIDDEN(PRTACPINSENTRY) rtAcpiNsLookup(PRTACPINSROOT pNsRoot, const char *pszNameString);
505
506
507	/**
508	* Returns the current namespace entry being active.
509	*
510	* @returns Pointer to the current namespace entry.
511	* @param pNsRoot The namespace root.
512	*/
513	DECLHIDDEN(PCRTACPINSENTRY) rtAcpiNsGetCurrent(PCRTACPINSROOT pNsRoot);
514
515
516	/**
517	* Dumps the given AST node and everything it references to the given ACPI table.
518	*
519	* @returns IPRT status code.
520	* @param pAstNd The AST node to dump.
521	* @param pNsRoot The namespace root this AST belongs to.
522	* @param hAcpiTbl The ACPI table to dump to.
523	*/
524	DECLHIDDEN(int) rtAcpiAstDumpToTbl(PCRTACPIASTNODE pAstNd, PRTACPINSROOT pNsRoot, RTACPITBL hAcpiTbl);
525
526
527	/**
528	* Worker for decompiling AML bytecode to the ASL source language.
529	*
530	* @returns IPRT status code.
531	* @param hVfsIosOut The VFS I/O stream handle to output the result to.
532	* @param hVfsIosIn The VFS I/O stream handle to read the ACPI table from.
533	* @param pErrInfo Where to return additional error information.
534	*/
535	DECLHIDDEN(int) rtAcpiTblConvertFromAmlToAsl(RTVFSIOSTREAM hVfsIosOut, RTVFSIOSTREAM hVfsIosIn, PRTERRINFO pErrInfo);
536
537
538	/**
539	* Worker for compiling ASL to the AML bytecode.
540	*
541	* @returns IPRT status code.
542	* @param hVfsIosOut The VFS I/O stream handle to output the result to.
543	* @param hVfsIosIn The VFS I/O stream handle to read the ACPI table from.
544	* @param pErrInfo Where to return additional error information.
545	*/
546	DECLHIDDEN(int) rtAcpiTblConvertFromAslToAml(RTVFSIOSTREAM hVfsIosOut, RTVFSIOSTREAM hVfsIosIn, PRTERRINFO pErrInfo);
547
548
549	RT_C_DECLS_END
550
551	#endif /* !IPRT_INCLUDED_INTERNAL_acpi_h */
552

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Runtime/include/internal/acpi.h@ 109019

Download in other formats: