acpi.h@ 108695

Last change on this file since 108695 was 108559, checked in by vboxsync, 5 weeks ago
Runtime/RTAcpi*: Some additions to create GpioInt() resource descriptors, bugref:10732 [build fix]
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 57.2 KB

Line
1	/** @file
2	* IPRT - Advanced Configuration and Power Interface (ACPI) Table generation API.
3	*/
4
5	/*
6	* Copyright (C) 2024 Oracle and/or its affiliates.
7	*
8	* This file is part of VirtualBox base platform packages, as
9	* available from https://www.virtualbox.org.
10	*
11	* This program is free software; you can redistribute it and/or
12	* modify it under the terms of the GNU General Public License
13	* as published by the Free Software Foundation, in version 3 of the
14	* License.
15	*
16	* This program is distributed in the hope that it will be useful, but
17	* WITHOUT ANY WARRANTY; without even the implied warranty of
18	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19	* General Public License for more details.
20	*
21	* You should have received a copy of the GNU General Public License
22	* along with this program; if not, see <https://www.gnu.org/licenses>.
23	*
24	* The contents of this file may alternatively be used under the terms
25	* of the Common Development and Distribution License Version 1.0
26	* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27	* in the VirtualBox distribution, in which case the provisions of the
28	* CDDL are applicable instead of those of the GPL.
29	*
30	* You may elect to license modified versions of this file under the
31	* terms and conditions of either the GPL or the CDDL or both.
32	*
33	* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34	*/
35
36	#ifndef IPRT_INCLUDED_acpi_h
37	#define IPRT_INCLUDED_acpi_h
38	#ifndef RT_WITHOUT_PRAGMA_ONCE
39	# pragma once
40	#endif
41
42	#include <iprt/cdefs.h>
43	#include <iprt/types.h>
44	#include <iprt/vfs.h>
45
46	#include <iprt/formats/acpi-tables.h>
47
48
49	RT_C_DECLS_BEGIN
50
51	/** @defgroup grp_rt_acpi RTAcpi - Advanced Configuration and Power Interface (ACPI) Table generation API.
52	* @ingroup grp_rt
53	* @{
54	*/
55
56	#ifdef IN_RING3
57
58	/**
59	* ACPI table type.
60	*/
61	typedef enum RTACPITBLTYPE
62	{
63	/** The invalid output type. */
64	RTACPITBLTYPE_INVALID = 0,
65	/** Type is an UTF-8 ASL source. */
66	RTACPITBLTYPE_ASL,
67	/** Type is the AML bytecode. */
68	RTACPITBLTYPE_AML,
69	/** Usual 32-bit hack. */
70	RTACPITBLTYPE_32BIT_HACK = 0x7fffffff
71	} RTACPITBLTYPE;
72
73
74	/**
75	* Regenerates the ACPI checksum for the given data.
76	*
77	* @returns The checksum for the given data.
78	* @param pvData The data to check sum.
79	* @param cbData Number of bytes to check sum.
80	*/
81	RTDECL(uint8_t) RTAcpiChecksumGenerate(const void *pvData, size_t cbData);
82
83
84	/**
85	* Generates and writes the table header checksum for the given ACPI table.
86	*
87	* @param pTbl Pointer to the ACPI table to set the checksum for.
88	* @param cbTbl Size of the table in bytes, including the ACPI table header.
89	*/
90	RTDECL(void) RTAcpiTblHdrChecksumGenerate(PACPITBLHDR pTbl, size_t cbTbl);
91
92
93	/**
94	* Creates an ACPI table from the given VFS file.
95	*
96	* @returns IPRT status code.
97	* @param phAcpiTbl Where to store the ACPI table handle on success.
98	* @param hVfsIos The VFS I/O stream handle to read the ACPI table from.
99	* @param enmInType The input type of the ACPI table.
100	* @param pErrInfo Where to return additional error information.
101	*/
102	RTDECL(int) RTAcpiTblCreateFromVfsIoStrm(PRTACPITBL phAcpiTbl, RTVFSIOSTREAM hVfsIos, RTACPITBLTYPE enmInType, PRTERRINFO pErrInfo);
103
104
105	/**
106	* Converts a given ACPI table input stream to the given output type.
107	*
108	* @returns IPRT status code.
109	* @param hVfsIosOut The VFS I/O stream handle to output the result to.
110	* @param enmOutType The output type.
111	* @param hVfsIosIn The VFS I/O stream handle to read the ACPI table from.
112	* @param enmInType The input type of the ACPI table.
113	* @param pErrInfo Where to return additional error information.
114	*/
115	RTDECL(int) RTAcpiTblConvertFromVfsIoStrm(RTVFSIOSTREAM hVfsIosOut, RTACPITBLTYPE enmOutType,
116	RTVFSIOSTREAM hVfsIosIn, RTACPITBLTYPE enmInType, PRTERRINFO pErrInfo);
117
118
119	/**
120	* Creates an ACPI table from the given filename.
121	*
122	* @returns IPRT status code.
123	* @param phAcpiTbl Where to store the ACPI table handle on success.
124	* @param pszFilename The filename to read the ACPI table from.
125	* @param enmInType The input type of the ACPI table.
126	* @param pErrInfo Where to return additional error information.
127	*/
128	RTDECL(int) RTAcpiTblCreateFromFile(PRTACPITBL phAcpiTbl, const char *pszFilename, RTACPITBLTYPE enmInType, PRTERRINFO pErrInfo);
129
130
131	/**
132	* Creates a new empty ACPI table.
133	*
134	* @returns IPRT status code.
135	* @param phAcpiTbl Where to store the ACPI table handle on success.
136	* @param u32TblSig The signature of the table to use.
137	* @param bRevision The revision of the table.
138	* @param pszOemId The OEM supplied string identifiying the OEM, maximum of 6 characters.
139	* @param pszOemTblId The OEM supplied string identifiying the OEM table, maximum of 8 characters.
140	* @param u32OemRevision The OEM supplied revision number.
141	* @param pszCreatorId Vendor ID of the utility that created the table, maximum of 4 characters.
142	* @param u32CreatorRevision Revision of the utility that created the table.
143	*/
144	RTDECL(int) RTAcpiTblCreate(PRTACPITBL phAcpiTbl, uint32_t u32TblSig, uint8_t bRevision, const char *pszOemId,
145	const char pszOemTblId, uint32_t u32OemRevision, const char pszCreatorId,
146	uint32_t u32CreatorRevision);
147
148
149	/**
150	* Destroys the given ACPI table, freeing all resources.
151	*
152	* @param hAcpiTbl The ACPI table handle to destroy.
153	*/
154	RTDECL(void) RTAcpiTblDestroy(RTACPITBL hAcpiTbl);
155
156
157	/**
158	* Finalizes the given ACPI table, setting the header and generating checksums.
159	*
160	* @returns IPRT status code.
161	* @param hAcpiTbl The ACPI table handle to finalize.
162	*
163	* @note Nothing can be added to the table after this was called.
164	*/
165	RTDECL(int) RTAcpiTblFinalize(RTACPITBL hAcpiTbl);
166
167
168	/**
169	* Returns the size of the given ACPI table.
170	*
171	* @returns Size of the given ACPI table in bytes, 0 on error.
172	* @param hAcpiTbl The ACPI table handle.
173	*
174	* @note This can only be called after RTAcpiTblFinalize() was called successfully.
175	*/
176	RTDECL(uint32_t) RTAcpiTblGetSize(RTACPITBL hAcpiTbl);
177
178
179	/**
180	* Dumps the given ACPI table to the given VFS I/O stream.
181	*
182	* @returns IPRT status code.
183	* @param hAcpiTbl The ACPI table handle.
184	* @param enmOutType The output type.
185	* @param hVfsIos The VFS I/O stream handle to dump the table to.
186	*/
187	RTDECL(int) RTAcpiTblDumpToVfsIoStrm(RTACPITBL hAcpiTbl, RTACPITBLTYPE enmOutType, RTVFSIOSTREAM hVfsIos);
188
189
190	/**
191	* Dumps the given ACPI table to the given file.
192	*
193	* @returns IPRT status code.
194	* @param hAcpiTbl The ACPI table handle.
195	* @param enmOutType The output type.
196	* @param pszFilename The file path to dump the table to.
197	*/
198	RTDECL(int) RTAcpiTblDumpToFile(RTACPITBL hAcpiTbl, RTACPITBLTYPE enmOutType, const char *pszFilename);
199
200
201	/**
202	* Dumps the given ACPI table to a memory buffer allocated with RTMemAlloc() and returns the pointer
203	* to the allocated memory.
204	*
205	* @returns IPRT status code.
206	* @param hAcpiTbl The ACPI table handle.
207	* @param enmOutType The output type.
208	* @param ppbAcpiTbl Where to store the pointer to the ACPI table on success.
209	* @param pcbAcpiTbl Where to store the size of the ACPI table in bytes on success.
210	*
211	* @note The caller has to free the buffer with RTMemFree().
212	*/
213	RTDECL(int) RTAcpiTblDumpToBufferA(RTACPITBL hAcpiTbl, RTACPITBLTYPE enmOutType, uint8_t *ppbAcpiTbl, size_t pcbAcpiTbl);
214
215
216	/**
217	* Starts a new DefScope object.
218	*
219	* @returns IPRT status code.
220	* @param hAcpiTbl The ACPI table handle.
221	* @param pszName Name of the scope, can have a root (\) specifier optionally.
222	*/
223	RTDECL(int) RTAcpiTblScopeStart(RTACPITBL hAcpiTbl, const char *pszName);
224
225
226	/**
227	* Finalizes the current scope object, nothing can be added to the scope afterwards.
228	*
229	* @returns IPRT status code.
230	* @param hAcpiTbl The ACPI table handle.
231	*/
232	RTDECL(int) RTAcpiTblScopeFinalize(RTACPITBL hAcpiTbl);
233
234
235	/**
236	* Starts a new DefPackage object.
237	*
238	* @returns IPRT status code.
239	* @param hAcpiTbl The ACPI table handle.
240	* @param cElements Number of element which will be inside the package,
241	* only supports up to 255 elements, use DefVarPackage if more is required.
242	*/
243	RTDECL(int) RTAcpiTblPackageStart(RTACPITBL hAcpiTbl, uint8_t cElements);
244
245
246	/**
247	* Finalizes the current DefPackage object, and return to the enclosing object's scope.
248	*
249	* @returns IPRT status code.
250	* @param hAcpiTbl The ACPI table handle.
251	*/
252	RTDECL(int) RTAcpiTblPackageFinalize(RTACPITBL hAcpiTbl);
253
254
255	/**
256	* Starts a new device object for the given ACPI table in the current scope.
257	*
258	* @returns IPRT status code.
259	* @param hAcpiTbl The ACPI table handle.
260	* @param pszName Name of the device object, must be <= 4 characters long.
261	*/
262	RTDECL(int) RTAcpiTblDeviceStart(RTACPITBL hAcpiTbl, const char *pszName);
263
264
265	/**
266	* Starts a new device object for the given ACPI table in the current scope.
267	*
268	* @returns IPRT status code.
269	* @param hAcpiTbl The ACPI table handle.
270	* @param pszNameFmt The name of the device as a format string.
271	* @param ... The format arguments.
272	*/
273	RTDECL(int) RTAcpiTblDeviceStartF(RTACPITBL hAcpiTbl, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(2, 3);
274
275
276	/**
277	* Starts a new device object for the given ACPI table in the current scope.
278	*
279	* @returns IPRT status code.
280	* @param hAcpiTbl The ACPI table handle.
281	* @param pszNameFmt The name of the device as a format string.
282	* @param va The format arguments.
283	*/
284	RTDECL(int) RTAcpiTblDeviceStartV(RTACPITBL hAcpiTbl, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
285
286
287	/**
288	* Finalizes the current scope object, nothing can be added to the scope afterwards.
289	*
290	* @returns IPRT status code.
291	* @param hAcpiTbl The ACPI table handle.
292	*/
293	RTDECL(int) RTAcpiTblDeviceFinalize(RTACPITBL hAcpiTbl);
294
295
296	/**
297	* Starts a new processor object for the given ACPI table in the current scope.
298	*
299	* @returns IPRT status code.
300	* @param hAcpiTbl The ACPI table handle.
301	* @param pszName Name of the device object, must be <= 4 characters long.
302	* @param bProcId The processor ID.
303	* @param u32PBlkAddr Address of the processor register block.
304	* @param cbPBlk Size of the processor register block in bytes.
305	*/
306	RTDECL(int) RTAcpiTblProcessorStart(RTACPITBL hAcpiTbl, const char *pszName, uint8_t bProcId, uint32_t u32PBlkAddr,
307	uint8_t cbPBlk);
308
309
310	/**
311	* Starts a new processor object for the given ACPI table in the current scope.
312	*
313	* @returns IPRT status code.
314	* @param hAcpiTbl The ACPI table handle.
315	* @param bProcId The processor ID.
316	* @param u32PBlkAddr Address of the processor register block.
317	* @param cbPBlk Size of the processor register block in bytes.
318	* @param pszNameFmt The name of the device as a format string.
319	* @param ... The format arguments.
320	*/
321	RTDECL(int) RTAcpiTblProcessorStartF(RTACPITBL hAcpiTbl, uint8_t bProcId, uint32_t u32PBlkAddr, uint8_t cbPBlk,
322	const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(5, 6);
323
324
325	/**
326	* Starts a new processor object for the given ACPI table in the current scope.
327	*
328	* @returns IPRT status code.
329	* @param hAcpiTbl The ACPI table handle.
330	* @param bProcId The processor ID.
331	* @param u32PBlkAddr Address of the processor register block.
332	* @param cbPBlk Size of the processor register block in bytes.
333	* @param pszNameFmt The name of the device as a format string.
334	* @param va The format arguments.
335	*/
336	RTDECL(int) RTAcpiTblProcessorStartV(RTACPITBL hAcpiTbl, uint8_t bProcId, uint32_t u32PBlkAddr, uint8_t cbPBlk,
337	const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(5, 0);
338
339
340	/**
341	* Finalizes the current scope object, nothing can be added to the scope afterwards.
342	*
343	* @returns IPRT status code.
344	* @param hAcpiTbl The ACPI table handle.
345	*/
346	RTDECL(int) RTAcpiTblProcessorFinalize(RTACPITBL hAcpiTbl);
347
348
349	/**
350	* Starts a new buffer object for the given ACPI table in the current scope.
351	*
352	* @returns IPRT status code.
353	* @param hAcpiTbl The ACPI table handle.
354	*/
355	RTDECL(int) RTAcpiTblBufferStart(RTACPITBL hAcpiTbl);
356
357
358	/**
359	* Finalizes the current buffer object, nothing can be added to the scope afterwards.
360	*
361	* @returns IPRT status code.
362	* @param hAcpiTbl The ACPI table handle.
363	*/
364	RTDECL(int) RTAcpiTblBufferFinalize(RTACPITBL hAcpiTbl);
365
366
367	/**
368	* Appends data to the current raw buffer object (needs to be called between RTAcpiTblBufferStart() and RTAcpiTblBufferFinalize()).
369	*
370	* @returns IPRT status code.
371	* @param hAcpiTbl The ACPI table handle.
372	* @param pvBuf The data to append.
373	* @param cbBuf Size of the buffer in bytes.
374	*/
375	RTDECL(int) RTAcpiTblBufferAppendRawData(RTACPITBL hAcpiTbl, const void *pvBuf, size_t cbBuf);
376
377
378	/**
379	* Starts a new method object for the given ACPI table in the current scope.
380	*
381	* @returns IPRT status code.
382	* @param hAcpiTbl The ACPI table handle.
383	* @param pszName The method name.
384	* @param fFlags AML method flags, see RTACPI_METHOD_F_XXX.
385	* @param cArgs Number of arguments this method takes.
386	* @param uSyncLvl The sync level.
387	*/
388	RTDECL(int) RTAcpiTblMethodStart(RTACPITBL hAcpiTbl, const char *pszName, uint8_t cArgs, uint32_t fFlags, uint8_t uSyncLvl);
389
390
391	/**
392	* Starts a new method object for the given ACPI table in the current scope.
393	*
394	* @returns IPRT status code.
395	* @param hAcpiTbl The ACPI table handle.
396	* @param fFlags AML method flags, see RTACPI_METHOD_F_XXX.
397	* @param cArgs Number of arguments this method takes.
398	* @param uSyncLvl The sync level.
399	* @param pszNameFmt The method name format string.
400	* @param ... Format string arguments.
401	*/
402	RTDECL(int) RTAcpiTblMethodStartF(RTACPITBL hAcpiTbl, uint8_t cArgs, uint32_t fFlags, uint8_t uSyncLvl,
403	const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(5, 6);
404
405
406	/**
407	* Starts a new method object for the given ACPI table in the current scope.
408	*
409	* @returns IPRT status code.
410	* @param hAcpiTbl The ACPI table handle.
411	* @param fFlags AML method flags, see RTACPI_METHOD_F_XXX.
412	* @param cArgs Number of arguments this method takes.
413	* @param uSyncLvl The sync level.
414	* @param pszNameFmt The method name format string.
415	* @param va Format string arguments.
416	*/
417	RTDECL(int) RTAcpiTblMethodStartV(RTACPITBL hAcpiTbl, uint8_t cArgs, uint32_t fFlags, uint8_t uSyncLvl,
418	const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(5, 0);
419
420
421	/** ACPI method is not serialized. */
422	#define RTACPI_METHOD_F_NOT_SERIALIZED 0
423	/** ACPI method call needs to be serialized in the ACPI interpreter. */
424	#define RTACPI_METHOD_F_SERIALIZED RT_BIT_32(0)
425
426
427	/**
428	* Finalizes the current method object, nothing can be added to the method afterwards.
429	*
430	* @returns IPRT status code.
431	* @param hAcpiTbl The ACPI table handle.
432	*/
433	RTDECL(int) RTAcpiTblMethodFinalize(RTACPITBL hAcpiTbl);
434
435
436	/**
437	* Appends a new DefName object (only the NameOp NameString part, DataRefObject is left for the caller
438	* to append).
439	*
440	* @returns IPRT status code.
441	* @param hAcpiTbl The ACPI table handle.
442	* @param pszName The name to append.
443	*/
444	RTDECL(int) RTAcpiTblNameAppend(RTACPITBL hAcpiTbl, const char *pszName);
445
446
447	/**
448	* Appends a new NullName object.
449	*
450	* @returns IPRT status code.
451	* @param hAcpiTbl The ACPI table handle.
452	*/
453	RTDECL(int) RTAcpiTblNullNameAppend(RTACPITBL hAcpiTbl);
454
455
456	/**
457	* Appends a new NameString object.
458	*
459	* @returns IPRT status code.
460	* @param hAcpiTbl The ACPI table handle.
461	* @param pszName The name to append.
462	*/
463	RTDECL(int) RTAcpiTblNameStringAppend(RTACPITBL hAcpiTbl, const char *pszName);
464
465
466	/**
467	* Appends a new String object - format string variant.
468	*
469	* @returns IPRT status code.
470	* @param hAcpiTbl The ACPI table handle.
471	* @param pszNameFmt The format string to build the name string from.
472	* @param ... Arguments for the format string.
473	*/
474	RTDECL(int) RTAcpiTblNameStringAppendF(RTACPITBL hAcpiTbl, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(2, 3);
475
476
477	/**
478	* Appends a new String object - format string variant.
479	*
480	* @returns IPRT status code.
481	* @param hAcpiTbl The ACPI table handle.
482	* @param pszNameFmt The format string to build the name string from.
483	* @param va The format arguments.
484	*/
485	RTDECL(int) RTAcpiTblNameStringAppendV(RTACPITBL hAcpiTbl, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
486
487
488	/**
489	* Appends a new String object.
490	*
491	* @returns IPRT status code.
492	* @param hAcpiTbl The ACPI table handle.
493	* @param psz The string to append.
494	*/
495	RTDECL(int) RTAcpiTblStringAppend(RTACPITBL hAcpiTbl, const char *psz);
496
497
498	/**
499	* Appends a new String object - format string variant.
500	*
501	* @returns IPRT status code.
502	* @param hAcpiTbl The ACPI table handle.
503	* @param pszFmt The format string to build the string from.
504	* @param ... Arguments for the format string.
505	*/
506	RTDECL(int) RTAcpiTblStringAppendF(RTACPITBL hAcpiTbl, const char *pszFmt, ...) RT_IPRT_FORMAT_ATTR(2, 3);
507
508
509	/**
510	* Appends a new String object - format string variant.
511	*
512	* @returns IPRT status code.
513	* @param hAcpiTbl The ACPI table handle.
514	* @param pszFmt The format string to build the string from.
515	* @param va The format arguments.
516	*/
517	RTDECL(int) RTAcpiTblStringAppendV(RTACPITBL hAcpiTbl, const char *pszFmt, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
518
519
520	/**
521	* Appends a given UTF-8 string as UTF-16 using a buffer object (Unicode() equivalent).
522	*
523	* @returns IPRT status code.
524	* @param hAcpiTbl The ACPI table handle.
525	* @param psz The string to append.
526	*/
527	RTDECL(int) RTAcpiTblStringAppendAsUtf16(RTACPITBL hAcpiTbl, const char *psz);
528
529
530	/**
531	* Appends a new integer object (depending on the value ZeroOp, OneOp,
532	* BytePrefix, WordPrefix, DWordPrefix or QWordPrefix is used).
533	*
534	* @returns IPRT status code.
535	* @param hAcpiTbl The ACPI table handle.
536	* @param u64 The 64-bit value to append.
537	*/
538	RTDECL(int) RTAcpiTblIntegerAppend(RTACPITBL hAcpiTbl, uint64_t u64);
539
540
541	/**
542	* Appends a new DefBuffer object under the current scope.
543	*
544	* @returns IPRT status code.
545	* @param hAcpiTbl The ACPI table handle.
546	* @param pvBuf The buffer data.
547	* @param cbBuf Size of the buffer in bytes.
548	*/
549	RTDECL(int) RTAcpiTblBufferAppend(RTACPITBL hAcpiTbl, const void *pvBuf, size_t cbBuf);
550
551
552	/**
553	* Appends the given resource as a DefBuffer under the current scope.
554	*
555	* @returns IPRT status code.
556	* @param hAcpiTbl The ACPI table handle.
557	* @param hAcpiRes The ACPI resource handle.
558	*/
559	RTDECL(int) RTAcpiTblResourceAppend(RTACPITBL hAcpiTbl, RTACPIRES hAcpiRes);
560
561
562	/**
563	* List of statements.
564	*/
565	typedef enum RTACPISTMT
566	{
567	/** Invalid statement. */
568	kAcpiStmt_Invalid = 0,
569	/** Ones statement. */
570	kAcpiStmt_Ones,
571	/** Return statement. */
572	kAcpiStmt_Return,
573	/** Breakpoint statement. */
574	kAcpiStmt_Breakpoint,
575	/** No operation statement. */
576	kAcpiStmt_Nop,
577	/** Break statement. */
578	kAcpiStmt_Break,
579	/** Continue statement. */
580	kAcpiStmt_Continue,
581	/** Add(Operand, Operand, Target) statement. */
582	kAcpiStmt_Add,
583	/** Subtract(Operand, Operand, Target) statement. */
584	kAcpiStmt_Subtract,
585	/** Multiply(Operand, Operand, Target) statement. */
586	kAcpiStmt_Multiply,
587	/** And(Operand, Operand, Target) statement. */
588	kAcpiStmt_And,
589	/** Nand(Operand, Operand, Target) statement. */
590	kAcpiStmt_Nand,
591	/** Or(Operand, Operand, Target) statement. */
592	kAcpiStmt_Or,
593	/** Xor(Operand, Operand, Target) statement. */
594	kAcpiStmt_Xor,
595	/** ShiftLeft(Operand, Operand, Target) statement. */
596	kAcpiStmt_ShiftLeft,
597	/** ShiftRight(Operand, Operand, Target) statement. */
598	kAcpiStmt_ShiftRight,
599	/** Not(Operand, Target) statement. */
600	kAcpiStmt_Not,
601	/** Store(TermArg, Supername) statement. */
602	kAcpiStmt_Store,
603	/** Index(BuffPkgStrObj, IndexValue, Target) statement. */
604	kAcpiStmt_Index,
605	/** DerefOf(ObjReference) statement. */
606	kAcpiStmt_DerefOf,
607	/** Store(SuperName, TermArg => Integer) statement. */
608	kAcpiStmt_Notify,
609	/** SizeOf(SuperName) statement. */
610	kAcpiStmt_SizeOf,
611	/** Increment(TermArg) statement. */
612	kAcpiStmt_Increment,
613	/** Decrement(TermArg) statement. */
614	kAcpiStmt_Decrement,
615	/** CondRefOf(TermArg, Target) statement. */
616	kAcpiStmt_CondRefOf,
617	/** LNot(Source) statement. */
618	kAcpiStmt_LNot,
619	/** CreateBitField(SourceBuff, BitIndex, NameString) statement. */
620	kAcpiStmt_CreateBitField,
621	/** CreateByteField(SourceBuff, ByteIndex, NameString) statement. */
622	kAcpiStmt_CreateByteField,
623	/** CreateWordField(SourceBuff, ByteIndex, NameString) statement. */
624	kAcpiStmt_CreateWordField,
625	/** CreateDWordField(SourceBuff, ByteIndex, NameString) statement. */
626	kAcpiStmt_CreateDWordField,
627	/** CreateQWordField(SourceBuff, ByteIndex, NameString) statement. */
628	kAcpiStmt_CreateQWordField,
629	/** ConcatenateResTemplate(Source1, Source2, Result) statement. */
630	kAcpiStmt_ConcatenateResTemplate,
631	/** FindSetLeftBit(Source, Result) statement. */
632	kAcpiStmt_FindSetLeftBit,
633	/** FindSetRightBit(Source, Result) statement. */
634	kAcpiStmt_FindSetRightBit
635	} RTACPISTMT;
636
637
638	/**
639	* Appends the given simple statement to the given ACPI table in the current scope.
640	*
641	* @returns IPRT status code.
642	* @param hAcpiTbl The ACPI table handle.
643	* @param enmStmt The statement to add.
644	*/
645	RTDECL(int) RTAcpiTblStmtSimpleAppend(RTACPITBL hAcpiTbl, RTACPISTMT enmStmt);
646
647
648	/**
649	* Starts a new If statement operation.
650	*
651	* @returns IPRT status code.
652	* @param hAcpiTbl The ACPI table handle.
653	*/
654	RTDECL(int) RTAcpiTblIfStart(RTACPITBL hAcpiTbl);
655
656
657	/**
658	* Finalizes the current If statement operation.
659	*
660	* @returns IPRT status code.
661	* @param hAcpiTbl The ACPI table handle.
662	*/
663	RTDECL(int) RTAcpiTblIfFinalize(RTACPITBL hAcpiTbl);
664
665
666	/**
667	* Starts a new Else operation (only valid if currently inside an If oepration).
668	*
669	* @returns IPRT status code.
670	* @param hAcpiTbl The ACPI table handle.
671	*/
672	RTDECL(int) RTAcpiTblElseStart(RTACPITBL hAcpiTbl);
673
674
675	/**
676	* Finalizes the current Else statement operation.
677	*
678	* @returns IPRT status code.
679	* @param hAcpiTbl The ACPI table handle.
680	*/
681	RTDECL(int) RTAcpiTblElseFinalize(RTACPITBL hAcpiTbl);
682
683
684	/**
685	* Starts a new While statement operation.
686	*
687	* @returns IPRT status code.
688	* @param hAcpiTbl The ACPI table handle.
689	*/
690	RTDECL(int) RTAcpiTblWhileStart(RTACPITBL hAcpiTbl);
691
692
693	/**
694	* Finalizes the current While statement operation.
695	*
696	* @returns IPRT status code.
697	* @param hAcpiTbl The ACPI table handle.
698	*/
699	RTDECL(int) RTAcpiTblWhileFinalize(RTACPITBL hAcpiTbl);
700
701
702	/**
703	* List of binary operations.
704	*/
705	typedef enum RTACPIBINARYOP
706	{
707	/** Invalid binary operation. */
708	kAcpiBinaryOp_Invalid = 0,
709	/** LAnd(Operand, Operand). */
710	kAcpiBinaryOp_LAnd,
711	/** LOr(Operand, Operand). */
712	kAcpiBinaryOp_LOr,
713	/** LEqual(Operand, Operand). */
714	kAcpiBinaryOp_LEqual,
715	/** LGreater(Operand, Operand). */
716	kAcpiBinaryOp_LGreater,
717	/** LGreaterEqual(Operand, Operand). */
718	kAcpiBinaryOp_LGreaterEqual,
719	/** LLess(Operand, Operand). */
720	kAcpiBinaryOp_LLess,
721	/** LLessEqual(Operand, Operand). */
722	kAcpiBinaryOp_LLessEqual,
723	/** LNotEqual(Operand, Operand). */
724	kAcpiBinaryOp_LNotEqual
725	} RTACPIBINARYOP;
726
727
728	/**
729	* Appends the given binary operand.
730	*
731	* @returns IPRT status code.
732	* @param hAcpiTbl The ACPI table handle.
733	* @param enmBinaryOp The binary operation to append.
734	*/
735	RTDECL(int) RTAcpiTblBinaryOpAppend(RTACPITBL hAcpiTbl, RTACPIBINARYOP enmBinaryOp);
736
737
738	/**
739	* Appends the given Arg<idArg> operand.
740	*
741	* @returns IPRT status code.
742	* @param hAcpiTbl The ACPI table handle.
743	* @param idArg The argument ID to append [0..6].
744	*/
745	RTDECL(int) RTAcpiTblArgOpAppend(RTACPITBL hAcpiTbl, uint8_t idArg);
746
747
748	/**
749	* Appends the given Local<idLocal> operand.
750	*
751	* @returns IPRT status code.
752	* @param hAcpiTbl The ACPI table handle.
753	* @param idLocal The local ID to append [0..7].
754	*/
755	RTDECL(int) RTAcpiTblLocalOpAppend(RTACPITBL hAcpiTbl, uint8_t idLocal);
756
757
758	/**
759	* Appends the given UUID as a buffer object.
760	*
761	* @returns IPRT status code.
762	* @param hAcpiTbl The ACPI table handle.
763	* @param pUuid The UUID to append.
764	*/
765	RTDECL(int) RTAcpiTblUuidAppend(RTACPITBL hAcpiTbl, PCRTUUID pUuid);
766
767
768	/**
769	* Appends the given UUID string as a UUID buffer object.
770	*
771	* @returns IPRT status code.
772	* @param hAcpiTbl The ACPI table handle.
773	* @param pszUuid The UUID string to append as a buffer.
774	*/
775	RTDECL(int) RTAcpiTblUuidAppendFromStr(RTACPITBL hAcpiTbl, const char *pszUuid);
776
777
778	/**
779	* Appends the given 7 character EISA ID string as the corresponding 4-byte
780	* integer.
781	*
782	* @returns IPRT status code.
783	* @param hAcpiTbl The ACPI table handle.
784	* @param pszEisaId The EISA ID to append.
785	*/
786	RTDECL(int) RTAcpiTblEisaIdAppend(RTACPITBL hAcpiTbl, const char *pszEisaId);
787
788
789	/**
790	* Known operation region space types.
791	*/
792	typedef enum RTACPIOPREGIONSPACE
793	{
794	/** Invalid region space type. */
795	kAcpiOperationRegionSpace_Invalid = 0,
796	/** Region is in system memory space. */
797	kAcpiOperationRegionSpace_SystemMemory,
798	/** Region is in system I/O space. */
799	kAcpiOperationRegionSpace_SystemIo,
800	/** Region is in PCI config space. */
801	kAcpiOperationRegionSpace_PciConfig,
802	/** Region is in embedded control space. */
803	kAcpiOperationRegionSpace_EmbeddedControl,
804	/** Region is in SMBUS space. */
805	kAcpiOperationRegionSpace_SmBus,
806	/** Region is in system CMOS space. */
807	kAcpiOperationRegionSpace_SystemCmos,
808	/** Region is a PCI bar target. */
809	kAcpiOperationRegionSpace_PciBarTarget,
810	/** Region is in IPMI space. */
811	kAcpiOperationRegionSpace_Ipmi,
812	/** Region is in GPIO space. */
813	kAcpiOperationRegionSpace_Gpio,
814	/** Region is in generic serial bus space. */
815	kAcpiOperationRegionSpace_GenericSerialBus,
816	/** Region is in platform communications channel (PCC) space. */
817	kAcpiOperationRegionSpace_Pcc,
818	/** 32bit hack. */
819	kAcpiOperationRegionSpace_32bit_Hack = 0x7fffffff
820	} RTACPIOPREGIONSPACE;
821
822
823	/**
824	* Appends a new OperationRegion() to the given ACPI table - extended version.
825	*
826	* @returns IPRT status code.
827	* @param hAcpiTbl The ACPI table handle.
828	* @param pszName The name of the operation region.
829	* @param enmSpace The operation region space type.
830	*
831	* @note This doesn't encode the region offset and size arguments but leaves it up to the caller
832	* to be able to encode complex stuff.
833	*/
834	RTDECL(int) RTAcpiTblOpRegionAppendEx(RTACPITBL hAcpiTbl, const char *pszName, RTACPIOPREGIONSPACE enmSpace);
835
836
837	/**
838	* Appends a new OperationRegion() to the given ACPI table.
839	*
840	* @returns IPRT status code.
841	* @param hAcpiTbl The ACPI table handle.
842	* @param pszName The name of the operation region.
843	* @param enmSpace The operation region space type.
844	* @param offRegion Offset of the region.
845	* @param cbRegion Size of the region in bytes.
846	*/
847	RTDECL(int) RTAcpiTblOpRegionAppend(RTACPITBL hAcpiTbl, const char *pszName, RTACPIOPREGIONSPACE enmSpace,
848	uint64_t offRegion, uint64_t cbRegion);
849
850
851	/**
852	* Field access type.
853	*/
854	typedef enum RTACPIFIELDACC
855	{
856	/** Invalid access type. */
857	kAcpiFieldAcc_Invalid = 0,
858	/** Any access width is okay. */
859	kAcpiFieldAcc_Any,
860	/** Byte (8-bit) access. */
861	kAcpiFieldAcc_Byte,
862	/** Word (16-bit) access. */
863	kAcpiFieldAcc_Word,
864	/** Double word (32-bit) access. */
865	kAcpiFieldAcc_DWord,
866	/** Quad word (64-bit) access. */
867	kAcpiFieldAcc_QWord,
868	/** Buffer like access. */
869	kAcpiFieldAcc_Buffer
870	} RTACPIFIELDACC;
871
872
873	/**
874	* Field update rule.
875	*/
876	typedef enum RTACPIFIELDUPDATE
877	{
878	/** Invalid upadte rule. */
879	kAcpiFieldUpdate_Invalid = 0,
880	/** Preserve content not being accessed. */
881	kAcpiFieldUpdate_Preserve,
882	/** Write as ones. */
883	kAcpiFieldUpdate_WriteAsOnes,
884	/** Write as zeroes. */
885	kAcpiFieldUpdate_WriteAsZeroes
886	} RTACPIFIELDUPDATE;
887
888
889	/**
890	* Field entry.
891	*/
892	typedef struct RTACPIFIELDENTRY
893	{
894	/** The field name - NULL means the NullName. */
895	const char *pszName;
896	/** Number of bits of the field. */
897	uint64_t cBits;
898	} RTACPIFIELDENTRY;
899	/** Pointer to a field entry. */
900	typedef RTACPIFIELDENTRY *PRTACPIFIELDENTRY;
901	/** Pointer to a const field entry. */
902	typedef const RTACPIFIELDENTRY *PCRTACPIFIELDENTRY;
903
904
905	/**
906	* Appends a new field descriptor to the given ACPI table.
907	*
908	* @returns IPRT status code.
909	* @param hAcpiTbl The ACPI table handle.
910	* @param pszNameRef The region/buffer the field describes.
911	* @param enmAcc The access type,
912	* @param fLock Flag whether access must happen under a lock.
913	* @param enmUpdate The update rule.
914	* @param paFields Pointer to the field descriptors.
915	* @param cFields Number of entries in the array.
916	*/
917	RTDECL(int) RTAcpiTblFieldAppend(RTACPITBL hAcpiTbl, const char *pszNameRef, RTACPIFIELDACC enmAcc,
918	bool fLock, RTACPIFIELDUPDATE enmUpdate, PCRTACPIFIELDENTRY paFields,
919	uint32_t cFields);
920
921
922	/**
923	* Appends a new index field descriptor to the given ACPI table.
924	*
925	* @returns IPRT status code.
926	* @param hAcpiTbl The ACPI table handle.
927	* @param pszNameIndex The index object.
928	* @param pszNameData The data object.
929	* @param enmAcc The access type,
930	* @param fLock Flag whether access must happen under a lock.
931	* @param enmUpdate The update rule.
932	* @param paFields Pointer to the field descriptors.
933	* @param cFields Number of entries in the array.
934	*/
935	RTDECL(int) RTAcpiTblIndexFieldAppend(RTACPITBL hAcpiTbl, const char pszNameIndex, const char pszNameData,
936	RTACPIFIELDACC enmAcc, bool fLock, RTACPIFIELDUPDATE enmUpdate,
937	PCRTACPIFIELDENTRY paFields, uint32_t cFields);
938
939
940	/**
941	* Object type.
942	*/
943	typedef enum RTACPIOBJTYPE
944	{
945	/** Invalid object type. */
946	kAcpiObjType_Invalid = 0,
947	/** Unknown object - UnknownObj */
948	kAcpiObjType_Unknown,
949	/** Integer object - IntObj */
950	kAcpiObjType_Int,
951	/** String object - StrObj */
952	kAcpiObjType_Str,
953	/** Buffer object - BuffObj */
954	kAcpiObjType_Buff,
955	/** Package object - PkgObj */
956	kAcpiObjType_Pkg,
957	/** Field unit object - FieldUnitObj */
958	kAcpiObjType_FieldUnit,
959	/** Device object - DeviceObj */
960	kAcpiObjType_Device,
961	/** Event object - EventObj */
962	kAcpiObjType_Event,
963	/** Method object - MethodObj */
964	kAcpiObjType_Method,
965	/** Mutex object - MutexObj */
966	kAcpiObjType_MutexObj,
967	/** OpRegion object - OpRegionObj */
968	kAcpiObjType_OpRegion,
969	/** Power resource object - PowerResObj */
970	kAcpiObjType_PowerRes,
971	/** Thermal zone object - ThermalZoneObj */
972	kAcpiObjType_ThermalZone,
973	/** Buffer field object - BuffFieldObj */
974	kAcpiObjType_BuffField,
975	/** Processor object - ProcessorObj */
976	kAcpiObjType_Processor
977	} RTACPIOBJTYPE;
978
979
980	/**
981	* Appends a new External declaration to the given ACPI table.
982	*
983	* @returns IPRT status code.
984	* @param hAcpiTbl The ACPI table handle.
985	* @param pszName The name stirng of the external object.
986	* @param enmObjType The object type.
987	* @param cArgs Number of arguments for the object (mostly method), valid is [0..7].
988	*/
989	RTDECL(int) RTAcpiTblExternalAppend(RTACPITBL hAcpiTbl, const char *pszName, RTACPIOBJTYPE enmObjType, uint8_t cArgs);
990
991
992	/** @name ACPI resource builder related API.
993	* @{ */
994
995	/**
996	* Creates a new empty resource template.
997	*
998	* @returns IPRT status code.
999	* @param phAcpiRes Where to store the handle to the ACPI resource on success.
1000	*/
1001	RTDECL(int) RTAcpiResourceCreate(PRTACPIRES phAcpiRes);
1002
1003
1004	/**
1005	* Destroys the given ACPI resource, freeing all allocated resources.
1006	*
1007	* @param hAcpiRes The ACPI resource handle to destroy.
1008	*/
1009	RTDECL(void) RTAcpiResourceDestroy(RTACPIRES hAcpiRes);
1010
1011
1012	/**
1013	* Resets the given ACPI resource handle to create a new empty template.
1014	*
1015	* @param hAcpiRes The ACPI resource handle.
1016	*/
1017	RTDECL(void) RTAcpiResourceReset(RTACPIRES hAcpiRes);
1018
1019
1020	/**
1021	* Returns the offset where the next resource added to the template would be.
1022	*
1023	* @returns Offset into the resource buffer where the next resource will be appended
1024	* @retval UINT32_MAX if the handle is invalid or the resource is in an error state.
1025	* @param hAcpiRes The ACPI resource handle.
1026	*/
1027	RTDECL(uint32_t) RTAcpiResourceGetOffset(RTACPIRES hAcpiRes);
1028
1029
1030	/**
1031	* Seals the given ACPI resource against further changes and adds any
1032	* missing data required to complete the resource buffer.
1033	*
1034	* @returns IPRT status code.
1035	* @param hAcpiRes The ACPI resource handle.
1036	*
1037	* @note After a call to this method completed successfully it is not possible
1038	* to add new resources until RTAcpiResourceReset() was called.
1039	*/
1040	RTDECL(int) RTAcpiResourceSeal(RTACPIRES hAcpiRes);
1041
1042
1043	/**
1044	* Queries the pointer to the buffer holding the encoded data.
1045	*
1046	* @returns IPRT status code.
1047	* @param hAcpiRes The ACPI resource handle.
1048	* @param ppvRes Where to store the pointer to the buffer holding the encoded resource template on success.
1049	* @param pcbRes Where to store the size of the encoded data in bytes on success.
1050	*
1051	* @note The ACPI resource must be successfully sealed with RTAcpiResourceSeal() for this function to succeed.
1052	* Also the buffer pointer will only be valid until a call to any other RTAcpiResource* method.
1053	*/
1054	RTDECL(int) RTAcpiResourceQueryBuffer(RTACPIRES hAcpiRes, const void *ppvRes, size_t pcbRes);
1055
1056
1057	/**
1058	* Adds a fixed memory range with the given start address and size to the given ACPI resource.
1059	*
1060	* @returns IPRT status code.
1061	* @param hAcpiRes The ACPI resource handle.
1062	* @param u32AddrBase The base address to encode.
1063	* @param cbRange The range length in bytes to encode.
1064	* @param fRw Flag whether this address range is read-write or read-only.
1065	*/
1066	RTDECL(int) RTAcpiResourceAdd32BitFixedMemoryRange(RTACPIRES hAcpiRes, uint32_t u32AddrBase, uint32_t cbRange,
1067	bool fRw);
1068
1069
1070	/**
1071	* Adds an extended interrupt descriptor with the given configuration to the given ACPI resource.
1072	*
1073	* @returns IPRT status code.
1074	* @param hAcpiRes The ACPI resource handle.
1075	* @param fConsumer Flag whether the entity this resource is assigned to consumes the interrupt (true) or produces it (false).
1076	* @param fEdgeTriggered Flag whether the interrupt is edged (true) or level (false) triggered.
1077	* @param fActiveLow Flag whether the interrupt polarity is active low (true) or active high (false).
1078	* @param fShared Flag whether the interrupt is shared between different entities (true) or exclusive to the assigned entity (false).
1079	* @param fWakeCapable Flag whether the interrupt can wake the system (true) or not (false).
1080	* @param cIntrs Number of interrupts following.
1081	* @param pau32Intrs Pointer to the array of interrupt numbers.
1082	*/
1083	RTDECL(int) RTAcpiResourceAddExtendedInterrupt(RTACPIRES hAcpiRes, bool fConsumer, bool fEdgeTriggered, bool fActiveLow, bool fShared,
1084	bool fWakeCapable, uint8_t cIntrs, uint32_t *pau32Intrs);
1085
1086
1087	/** @name Generic address space flags.
1088	* @{ */
1089	#define RTACPI_RESOURCE_ADDR_RANGE_F_DECODE_TYPE_SUB RT_BIT_32(0)
1090	#define RTACPI_RESOURCE_ADDR_RANGE_F_DECODE_TYPE_POS 0
1091
1092	#define RTACPI_RESOURCE_ADDR_RANGE_F_MIN_ADDR_FIXED RT_BIT_32(1)
1093	#define RTACPI_RESOURCE_ADDR_RANGE_F_MIN_ADDR_CHANGEABLE 0
1094
1095	#define RTACPI_RESOURCE_ADDR_RANGE_F_MAX_ADDR_FIXED RT_BIT_32(2)
1096	#define RTACPI_RESOURCE_ADDR_RANGE_F_MAX_ADDR_CHANGEABLE 0
1097
1098	#define RTACPI_RESOURCE_ADDR_RANGE_F_PRODUCER RT_BIT_32(3)
1099	#define RTACPI_RESOURCE_ADDR_RANGE_F_CONSUMER 0
1100
1101	#define RTACPI_RESOURCE_ADDR_RANGE_F_VALID_MASK UINT32_C(0x0000000f)
1102	/** @} */
1103
1104	/**
1105	* Memory range cacheability
1106	*/
1107	typedef enum RTACPIRESMEMRANGECACHEABILITY
1108	{
1109	/** Usual invalid value. */
1110	kAcpiResMemRangeCacheability_Invalid = 0,
1111	/** Memory range is non cacheable (like MMIO, etc.). */
1112	kAcpiResMemRangeCacheability_NonCacheable,
1113	/** Memory is cacheable. */
1114	kAcpiResMemRangeCacheability_Cacheable,
1115	/** Memory is cacheable and supports write combining. */
1116	kAcpiResMemRangeCacheability_CacheableWriteCombining,
1117	/** Memory is cacheable and supports prefetching. */
1118	kAcpiResMemRangeCacheability_CacheablePrefetchable,
1119	/** 32-bit blow up hack. */
1120	kAcpiResMemRangeCacheability_32BitHack = 0x7fffffff
1121	} RTACPIRESMEMRANGECACHEABILITY;
1122
1123
1124	/**
1125	* Memory attribute.
1126	*/
1127	typedef enum RTACPIRESMEMRANGETYPE
1128	{
1129	/** Invalid memory range type. */
1130	kAcpiResMemType_Invalid = 0,
1131	/** Memory range is actual memory. */
1132	kAcpiResMemType_Memory,
1133	/** Memory range is reserved. */
1134	kAcpiResMemType_Reserved,
1135	/** Memory range is reserved to ACPI. */
1136	kAcpiResMemType_Acpi,
1137	/** Memory range is no volatile storage. */
1138	kAcpiResMemType_Nvs,
1139	/** 32-bit blow up hack. */
1140	kAcpiResMemType_32BitHack = 0x7fffffff
1141	} RTACPIRESMEMRANGETYPE;
1142
1143
1144	/**
1145	* Adds a quad word (64-bit) memory range to the given ACPI resource.
1146	*
1147	* @returns IPRT status code.
1148	* @param hAcpiRes The ACPI resource handle.
1149	* @param enmCacheability The cacheability of the memory range.
1150	* @param enmType Memory range type.
1151	* @param fRw Flag whether the memory range is read/write (true) or readonly (false).
1152	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
1153	* @param u64AddrMin The start address of the memory range.
1154	* @param u64AddrMax Last valid address of the range.
1155	* @param u64OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
1156	* @param u64Granularity The access granularity of the range in bytes.
1157	* @param u64Length Length of the memory range in bytes.
1158	*/
1159	RTDECL(int) RTAcpiResourceAddQWordMemoryRange(RTACPIRES hAcpiRes, RTACPIRESMEMRANGECACHEABILITY enmCacheability,
1160	RTACPIRESMEMRANGETYPE enmType, bool fRw, uint32_t fAddrSpace,
1161	uint64_t u64AddrMin, uint64_t u64AddrMax, uint64_t u64OffTrans,
1162	uint64_t u64Granularity, uint64_t u64Length);
1163
1164
1165	/**
1166	* Adds a quad word (64-bit) memory range to the given ACPI resource - extended version.
1167	*
1168	* @returns IPRT status code.
1169	* @param hAcpiRes The ACPI resource handle.
1170	* @param enmCacheability The cacheability of the memory range.
1171	* @param enmType Memory range type.
1172	* @param fRw Flag whether the memory range is read/write (true) or readonly (false).
1173	* @param fStatic Flag whether the translation type is static (true) or translation (false).
1174	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
1175	* @param u64AddrMin The start address of the memory range.
1176	* @param u64AddrMax Last valid address of the range.
1177	* @param u64OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
1178	* @param u64Granularity The access granularity of the range in bytes.
1179	* @param u64Length Length of the memory range in bytes.
1180	* @param pszRsrcSrc Name of the device object that produces the the descriptor consumed by the device, optional.
1181	* NULL means the device consumes the resource out of a global pool.
1182	* @param bRsrcIndex Index into the resource descriptor this device consumes from. Ignored if pszRsrcSrc is NULL.
1183	*/
1184	RTDECL(int) RTAcpiResourceAddQWordMemoryRangeEx(RTACPIRES hAcpiRes, RTACPIRESMEMRANGECACHEABILITY enmCacheability,
1185	RTACPIRESMEMRANGETYPE enmType, bool fRw, bool fStatic, uint32_t fAddrSpace,
1186	uint64_t u64AddrMin, uint64_t u64AddrMax, uint64_t u64OffTrans,
1187	uint64_t u64Granularity, uint64_t u64Length,
1188	const char *pszRsrcSrc, uint8_t bRsrcIndex);
1189
1190
1191	/**
1192	* Adds a double word (32-bit) memory range to the given ACPI resource.
1193	*
1194	* @returns IPRT status code.
1195	* @param hAcpiRes The ACPI resource handle.
1196	* @param enmCacheability The cacheability of the memory range.
1197	* @param enmType Memory range type.
1198	* @param fRw Flag whether the memory range is read/write (true) or readonly (false).
1199	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
1200	* @param u32AddrMin The start address of the memory range.
1201	* @param u32AddrMax Last valid address of the range.
1202	* @param u32OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
1203	* @param u32Granularity The access granularity of the range in bytes.
1204	* @param u32Length Length of the memory range in bytes.
1205	*/
1206	RTDECL(int) RTAcpiResourceAddDWordMemoryRange(RTACPIRES hAcpiRes, RTACPIRESMEMRANGECACHEABILITY enmCacheability,
1207	RTACPIRESMEMRANGETYPE enmType, bool fRw, uint32_t fAddrSpace,
1208	uint32_t u32AddrMin, uint32_t u32AddrMax, uint32_t u32OffTrans,
1209	uint32_t u32Granularity, uint32_t u32Length);
1210
1211
1212	/**
1213	* Adds a double word (32-bit) memory range to the given ACPI resource - extended version.
1214	*
1215	* @returns IPRT status code.
1216	* @param hAcpiRes The ACPI resource handle.
1217	* @param enmCacheability The cacheability of the memory range.
1218	* @param enmType Memory range type.
1219	* @param fRw Flag whether the memory range is read/write (true) or readonly (false).
1220	* @param fStatic Flag whether the translation type is static (true) or translation (false).
1221	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
1222	* @param u32AddrMin The start address of the memory range.
1223	* @param u32AddrMax Last valid address of the range.
1224	* @param u32OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
1225	* @param u32Granularity The access granularity of the range in bytes.
1226	* @param u32Length Length of the memory range in bytes.
1227	* @param pszRsrcSrc Name of the device object that produces the the descriptor consumed by the device, optional.
1228	* NULL means the device consumes the resource out of a global pool.
1229	* @param bRsrcIndex Index into the resource descriptor this device consumes from. Ignored if pszRsrcSrc is NULL.
1230	*/
1231	RTDECL(int) RTAcpiResourceAddDWordMemoryRangeEx(RTACPIRES hAcpiRes, RTACPIRESMEMRANGECACHEABILITY enmCacheability,
1232	RTACPIRESMEMRANGETYPE enmType, bool fRw, bool fStatic, uint32_t fAddrSpace,
1233	uint32_t u32AddrMin, uint32_t u32AddrMax, uint32_t u32OffTrans,
1234	uint32_t u32Granularity, uint32_t u32Length,
1235	const char *pszRsrcSrc, uint8_t bRsrcIndex);
1236
1237
1238	/**
1239	* I/O range coverage.
1240	*/
1241	typedef enum RTACPIRESIORANGE
1242	{
1243	/** Invalid range. */
1244	kAcpiResIoRange_Invalid = 0,
1245	/** Range covers only non ISA I/O ports. */
1246	kAcpiResIoRange_NonIsaOnly,
1247	/** Range covers only ISA I/O ports. */
1248	kAcpiResIoRange_IsaOnly,
1249	/** Range covers the whole I/O port range. */
1250	kAcpiResIoRange_Whole,
1251	/** 32-bit blow up hack. */
1252	kAcpiResIoRange_32BitHack = 0x7fffffff
1253	} RTACPIRESIORANGE;
1254
1255
1256	/**
1257	* I/O range type.
1258	*/
1259	typedef enum RTACPIRESIORANGETYPE
1260	{
1261	/** Invalid value. */
1262	kAcpiResIoRangeType_Invalid = 0,
1263	/** Resource is I/O on the primary and secondary side of the bridge. */
1264	kAcpiResIoRangeType_Static,
1265	/** Resource is memory on the primary and I/O on the secondary side of the bridge,
1266	* primary side memory address for a given I/O port is calculated with
1267	* address = (((Port & 0xfffc) << 10) \|\| (Port & 0xfff)) + AddrMin. */
1268	kAcpiResIoRangeType_Translation_Sparse,
1269	/** Resource is memory on the primary and I/O on the secondary side of the bridge,
1270	* primary side memory address for a given I/O port is calculated with
1271	* address = AddrMin + Port. */
1272	kAcpiResIoRangeType_Translation_Dense,
1273	/** 32-bit blowup hack. */
1274	kAcpiResIoRangeType_32BitHack = 0x7fffffff
1275	} RTACPIRESIORANGETYPE;
1276
1277
1278	/**
1279	* Adds a quad word (64-bit) I/O range to the given ACPI resource.
1280	*
1281	* @returns IPRT status code.
1282	* @param hAcpiRes The ACPI resource handle.
1283	* @param enmIoType The I/O range type.
1284	* @param enmIoRange The I/O range coverage.
1285	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
1286	* @param u64AddrMin The start address of the memory range.
1287	* @param u64AddrMax Last valid address of the range.
1288	* @param u64OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
1289	* @param u64Granularity The access granularity of the range in bytes.
1290	* @param u64Length Length of the memory range in bytes.
1291	*/
1292	RTDECL(int) RTAcpiResourceAddQWordIoRange(RTACPIRES hAcpiRes, RTACPIRESIORANGETYPE enmIoType, RTACPIRESIORANGE enmIoRange,
1293	uint32_t fAddrSpace, uint64_t u64AddrMin, uint64_t u64AddrMax, uint64_t u64OffTrans,
1294	uint64_t u64Granularity, uint64_t u64Length);
1295
1296
1297	/**
1298	* Adds a word (16-bit) I/O range to the given ACPI resource - extended version.
1299	*
1300	* @returns IPRT status code.
1301	* @param hAcpiRes The ACPI resource handle.
1302	* @param enmIoType The I/O range type.
1303	* @param enmIoRange The I/O range coverage.
1304	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
1305	* @param u16AddrMin The start address of the memory range.
1306	* @param u16AddrMax Last valid address of the range.
1307	* @param u16OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
1308	* @param u16Granularity The access granularity of the range in bytes.
1309	* @param u16Length Length of the memory range in bytes.
1310	* @param pszRsrcSrc Name of the device object that produces the the descriptor consumed by the device, optional.
1311	* NULL means the device consumes the resource out of a global pool.
1312	* @param bRsrcIndex Index into the resource descriptor this device consumes from. Ignored if pszRsrcSrc is NULL.
1313	*/
1314	RTDECL(int) RTAcpiResourceAddWordIoRangeEx(RTACPIRES hAcpiRes, RTACPIRESIORANGETYPE enmIoType, RTACPIRESIORANGE enmIoRange,
1315	uint32_t fAddrSpace, uint16_t u16AddrMin, uint16_t u16AddrMax, uint64_t u16OffTrans,
1316	uint16_t u16Granularity, uint16_t u16Length, const char *pszRsrcSrc, uint8_t bRsrcIndex);
1317
1318
1319	/**
1320	* Adds a word (16-bit) bus number to the given ACPI resource.
1321	*
1322	* @returns IPRT status code.
1323	* @param hAcpiRes The ACPI resource handle.
1324	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
1325	* @param u16BusMin Starting bus number.
1326	* @param u16BusMax Last valid bus number.
1327	* @param u16OffTrans Translation offset being applied to the bus number.
1328	* @param u16Granularity The access granularity of the bus number.
1329	* @param u16Length Length of the bus range.
1330	*/
1331	RTDECL(int) RTAcpiResourceAddWordBusNumber(RTACPIRES hAcpiRes, uint32_t fAddrSpace, uint16_t u16BusMin, uint16_t u16BusMax,
1332	uint16_t u16OffTrans, uint16_t u16Granularity, uint16_t u16Length);
1333
1334
1335	/**
1336	* Adds a word (16-bit) bus number to the given ACPI resource - extended version.
1337	*
1338	* @returns IPRT status code.
1339	* @param hAcpiRes The ACPI resource handle.
1340	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
1341	* @param u16BusMin Starting bus number.
1342	* @param u16BusMax Last valid bus number.
1343	* @param u16OffTrans Translation offset being applied to the bus number.
1344	* @param u16Granularity The access granularity of the bus number.
1345	* @param u16Length Length of the bus range.
1346	* @param pszRsrcSrc Name of the device object that produces the the descriptor consumed by the device, optional.
1347	* NULL means the device consumes the resource out of a global pool.
1348	* @param bRsrcIndex Index into the resource descriptor this device consumes from. Ignored if pszRsrcSrc is NULL.
1349	*/
1350	RTDECL(int) RTAcpiResourceAddWordBusNumberEx(RTACPIRES hAcpiRes, uint32_t fAddrSpace, uint16_t u16BusMin, uint16_t u16BusMax,
1351	uint16_t u16OffTrans, uint16_t u16Granularity, uint16_t u16Length,
1352	const char *pszRsrcSrc, uint8_t bRsrcIndex);
1353
1354
1355	/**
1356	* I/O decode type.
1357	*/
1358	typedef enum RTACPIRESIODECODETYPE
1359	{
1360	/** Invalid value. */
1361	kAcpiResIoDecodeType_Invalid = 0,
1362	/** 10-bit decoding. */
1363	kAcpiResIoDecodeType_Decode10,
1364	/** 16-bit decoding. */
1365	kAcpiResIoDecodeType_Decode16,
1366	/** 32-bit blowup hack. */
1367	kAcpiResIoDecodeType_32BitHack = 0x7fffffff
1368	} RTACPIRESIODECODETYPE;
1369
1370
1371	/**
1372	* Adds an I/O port descriptor to the given ACPI resource.
1373	*
1374	* @returns IPRT status code.
1375	* @param hAcpiRes The ACPI resource handle.
1376	* @param enmDecode The decoding type of the range.
1377	* @param u16AddrMin Minimum base I/O address the range might be configured for.
1378	* @param u16AddrMax Maximum base I/O address the range might be configured for.
1379	* @param u8AddrAlignment Alignment of the minimum base address.
1380	* @param u8RangeLength Number of contiguous I/O ports requested.
1381	*/
1382	RTDECL(int) RTAcpiResourceAddIo(RTACPIRES hAcpiRes, RTACPIRESIODECODETYPE enmDecode, uint16_t u16AddrMin, uint16_t u16AddrMax,
1383	uint8_t u8AddrAlignment, uint8_t u8RangeLength);
1384
1385
1386	/**
1387	* Adds an IRQ descriptor with the given configuration to the given ACPI resource.
1388	*
1389	* @returns IPRT status code.
1390	* @param hAcpiRes The ACPI resource handle.
1391	* @param fEdgeTriggered Flag whether the interrupt is edged (true) or level (false) triggered.
1392	* @param fActiveLow Flag whether the interrupt polarity is active low (true) or active high (false).
1393	* @param fShared Flag whether the interrupt is shared between different entities (true) or exclusive to the assigned entity (false).
1394	* @param fWakeCapable Flag whether the interrupt can wake the system (true) or not (false).
1395	* @param bmIntrs Bitmap of interrupts (0..15) requested.
1396	*/
1397	RTDECL(int) RTAcpiResourceAddIrq(RTACPIRES hAcpiRes, bool fEdgeTriggered, bool fActiveLow, bool fShared,
1398	bool fWakeCapable, uint16_t bmIntrs);
1399
1400
1401	/**
1402	* DMA channel speed.
1403	*/
1404	typedef enum RTACPIRESDMACHANSPEED
1405	{
1406	/** Invalid value. */
1407	kAcpiResDmaChanSpeed_Invalid = 0,
1408	/** Compatibility mode. */
1409	kAcpiResDmaChanSpeed_Compatibility,
1410	/** Type A DMA as described in EISA. */
1411	kAcpiResDmaChanSpeed_TypeA,
1412	/** Type B DMA. */
1413	kAcpiResDmaChanSpeed_TypeB,
1414	/** Type F. */
1415	kAcpiResDmaChanSpeed_TypeF,
1416	/** 32-bit blowup hack. */
1417	kAcpiResDmaChanSpeed_32BitHack = 0x7fffffff
1418	} RTACPIRESDMACHANSPEED;
1419
1420
1421	/**
1422	* DMA transfer type.
1423	*/
1424	typedef enum RTACPIRESDMATRANSFERTYPE
1425	{
1426	/** Invalid value. */
1427	kAcpiResDmaTransferType_Invalid = 0,
1428	/** 8bit only. */
1429	kAcpiResDmaTransferType_8Bit,
1430	/** 8-bit and 16-bit. */
1431	kAcpiResDmaTransferType_8Bit_16Bit,
1432	/** 16-bit only. */
1433	kAcpiResDmaTransferType_16Bit,
1434	/** 32-bit blowup hack. */
1435	kAcpiResDmaTransferType_32BitHack = 0x7fffffff
1436	} RTACPIRESDMATRANSFERTYPE;
1437
1438
1439	/**
1440	* Adds a DMA descriptor with the given configuration to the given ACPI resource.
1441	*
1442	* @returns IPRT status code.
1443	* @param hAcpiRes The ACPI resource handle.
1444	* @param enmChanSpeed The DMA channel speed.
1445	* @param fBusMaster Flag whether the device is a bus master.
1446	* @param enmTransferType DMA transfer type preference.
1447	* @param bmChannels Bitmap of DMA channels (0..7) requested.
1448	*/
1449	RTDECL(int) RTAcpiResourceAddDma(RTACPIRES hAcpiRes, RTACPIRESDMACHANSPEED enmChanSpeed, bool fBusMaster,
1450	RTACPIRESDMATRANSFERTYPE enmTransferType, uint8_t bmChannels);
1451
1452
1453	/**
1454	* GPIO Interrupt type.
1455	*/
1456	typedef enum RTACPIRESGPIOMOD
1457	{
1458	/** Invalid type. */
1459	kAcpiResGpioMod_Invalid = 0,
1460	/** Edge interrupt type. */
1461	kAcpiResGpioMod_Edge,
1462	/** Level interrupt type. */
1463	kAcpiResGpioMod_Level,
1464	/** 32-bit blowup hack. */
1465	kAcpiResGpioMod_32Bit_Hack = 0x7fffffff
1466	} RTACPIRESGPIOMOD;
1467
1468
1469	/**
1470	* GPIO polarity config.
1471	*/
1472	typedef enum RTACPIRESGPIOPOL
1473	{
1474	/** Invalid type. */
1475	kAcpiResGpioPol_Invalid = 0,
1476	/** Active if input is high. */
1477	kAcpiResGpioPol_ActiveHigh,
1478	/** Active if input is low. */
1479	kAcpiResGpioPol_ActiveLow,
1480	/** Active on both (only supported if interrupt type is Edge). */
1481	kAcpiResGpioPol_ActiveBoth,
1482	/** 32-bit blowup hack. */
1483	kAcpiResGpioPol_32Bit_Hack = 0x7fffffff
1484	} RTACPIRESGPIOPOL;
1485
1486
1487	/**
1488	* GPIO shared/exclusive config.
1489	*/
1490	typedef enum RTACPIRESGPIOSHR
1491	{
1492	/** Invalid type. */
1493	kAcpiResGpioShr_Invalid = 0,
1494	/** GPIO pins are shared. */
1495	kAcpiResGpioShr_Shared,
1496	/** GPIO pins are exclusive. */
1497	kAcpiResGpioShr_Exclusive,
1498	/** GPIO pins are shared and capabale to wake the system. */
1499	kAcpiResGpioShr_SharedAndWake,
1500	/** GPIO pins are exclusive and capabale to wake the system. */
1501	kAcpiResGpioShr_ExclusiveAndWake,
1502	/** 32-bit blowup hack. */
1503	kAcpiResGpioShr_32Bit_Hack = 0x7fffffff
1504	} RTACPIRESGPIOSHR;
1505
1506
1507	/**
1508	* GPIO pin config.
1509	*/
1510	typedef enum RTACPIRESGPIOPPI
1511	{
1512	/** Invalid config. */
1513	kAcpiResGpioPpi_Invalid = 0,
1514	/** Default pull up/down config. */
1515	kAcpiResGpioPpi_PullDefault,
1516	/** Pin is pulled up. */
1517	kAcpiResGpioPpi_PullUp,
1518	/** Pin is pulled down. */
1519	kAcpiResGpioPpi_PullDown,
1520	/** Pin has no pull up/down resistor attached and is floating. */
1521	kAcpiResGpioPpi_PullNone,
1522	/** 32-bit blowup hack. */
1523	kAcpiResGpioPpi_32Bit_Hack = 0x7fffffff
1524	} RTACPIRESGPIOPPI;
1525
1526
1527	/**
1528	* Adds a GPIO connection descriptor suitable for GPIO input pins with interrupt support
1529	* with the given configuration to the given ACPI resource.
1530	*
1531	* @returns IPRT status code.
1532	* @param hAcpiRes The ACPI resource handle.
1533	* @param enmMod Interrupt configuration.
1534	* @param enmPol Polarity config.
1535	* @param enmShr Shared/Exclusive config.
1536	* @param enmPpi The pin pull up/down config.
1537	* @param u16DebounceWait Debounce wait time in 100ms steps.
1538	* @param pszRsrcSrc The GPIO controller resource name these GPIO pins are part of.
1539	* @param pau16Pins Array of pin numbers.
1540	* @param cPins Number of entries in the array.
1541	*/
1542	RTDECL(int) RTAcpiResourceAddGpioInt(RTACPIRES hAcpiRes, RTACPIRESGPIOMOD enmMod, RTACPIRESGPIOPOL enmPol, RTACPIRESGPIOSHR enmShr,
1543	RTACPIRESGPIOPPI enmPpi, uint16_t u16DebounceWait, const char *pszRsrcSrc,
1544	uint16_t *pau16Pins, uint16_t cPins);
1545
1546	/** @} */
1547
1548	#endif /* IN_RING3 */
1549
1550	/** @} */
1551
1552	RT_C_DECLS_END
1553
1554	#endif /* !IPRT_INCLUDED_acpi_h */
1555

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

source: vbox/trunk/include/iprt/acpi.h@ 108695

Download in other formats: