acpi.h@ 108089

Last change on this file since 108089 was 108089, checked in by vboxsync, 2 weeks ago
Runtime/RTAcpi*: Updates to the ASL -> AML compiler, it is now possible to produce a valid AML table from the pre processed vbox-cpuhotplug.dsl SSDT, bugref:10733 [build fix]
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 36.3 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	* Starts a new DefScope object.
203	*
204	* @returns IPRT status code.
205	* @param hAcpiTbl The ACPI table handle.
206	* @param pszName Name of the scope, can have a root (\) specifier optionally.
207	*/
208	RTDECL(int) RTAcpiTblScopeStart(RTACPITBL hAcpiTbl, const char *pszName);
209
210
211	/**
212	* Finalizes the current scope object, nothing can be added to the scope afterwards.
213	*
214	* @returns IPRT status code.
215	* @param hAcpiTbl The ACPI table handle.
216	*/
217	RTDECL(int) RTAcpiTblScopeFinalize(RTACPITBL hAcpiTbl);
218
219
220	/**
221	* Starts a new DefPackage object.
222	*
223	* @returns IPRT status code.
224	* @param hAcpiTbl The ACPI table handle.
225	* @param cElements Number of element which will be inside the package,
226	* only supports up to 255 elements, use DefVarPackage if more is required.
227	*/
228	RTDECL(int) RTAcpiTblPackageStart(RTACPITBL hAcpiTbl, uint8_t cElements);
229
230
231	/**
232	* Finalizes the current DefPackage object, and return to the enclosing object's scope.
233	*
234	* @returns IPRT status code.
235	* @param hAcpiTbl The ACPI table handle.
236	*/
237	RTDECL(int) RTAcpiTblPackageFinalize(RTACPITBL hAcpiTbl);
238
239
240	/**
241	* Starts a new device object for the given ACPI table in the current scope.
242	*
243	* @returns IPRT status code.
244	* @param hAcpiTbl The ACPI table handle.
245	* @param pszName Name of the device object, must be <= 4 characters long.
246	*/
247	RTDECL(int) RTAcpiTblDeviceStart(RTACPITBL hAcpiTbl, const char *pszName);
248
249
250	/**
251	* Starts a new device object for the given ACPI table in the current scope.
252	*
253	* @returns IPRT status code.
254	* @param hAcpiTbl The ACPI table handle.
255	* @param pszNameFmt The name of the device as a format string.
256	* @param ... The format arguments.
257	*/
258	RTDECL(int) RTAcpiTblDeviceStartF(RTACPITBL hAcpiTbl, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(2, 3);
259
260
261	/**
262	* Starts a new device object for the given ACPI table in the current scope.
263	*
264	* @returns IPRT status code.
265	* @param hAcpiTbl The ACPI table handle.
266	* @param pszNameFmt The name of the device as a format string.
267	* @param va The format arguments.
268	*/
269	RTDECL(int) RTAcpiTblDeviceStartV(RTACPITBL hAcpiTbl, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
270
271
272	/**
273	* Finalizes the current scope object, nothing can be added to the scope afterwards.
274	*
275	* @returns IPRT status code.
276	* @param hAcpiTbl The ACPI table handle.
277	*/
278	RTDECL(int) RTAcpiTblDeviceFinalize(RTACPITBL hAcpiTbl);
279
280
281	/**
282	* Starts a new processor object for the given ACPI table in the current scope.
283	*
284	* @returns IPRT status code.
285	* @param hAcpiTbl The ACPI table handle.
286	* @param pszName Name of the device object, must be <= 4 characters long.
287	* @param bProcId The processor ID.
288	* @param u32PBlkAddr Address of the processor register block.
289	* @param cbPBlk Size of the processor register block in bytes.
290	*/
291	RTDECL(int) RTAcpiTblProcessorStart(RTACPITBL hAcpiTbl, const char *pszName, uint8_t bProcId, uint32_t u32PBlkAddr,
292	uint8_t cbPBlk);
293
294
295	/**
296	* Starts a new processor object for the given ACPI table in the current scope.
297	*
298	* @returns IPRT status code.
299	* @param hAcpiTbl The ACPI table handle.
300	* @param bProcId The processor ID.
301	* @param u32PBlkAddr Address of the processor register block.
302	* @param cbPBlk Size of the processor register block in bytes.
303	* @param pszNameFmt The name of the device as a format string.
304	* @param ... The format arguments.
305	*/
306	RTDECL(int) RTAcpiTblProcessorStartF(RTACPITBL hAcpiTbl, uint8_t bProcId, uint32_t u32PBlkAddr, uint8_t cbPBlk,
307	const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(5, 6);
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 va The format arguments.
320	*/
321	RTDECL(int) RTAcpiTblProcessorStartV(RTACPITBL hAcpiTbl, uint8_t bProcId, uint32_t u32PBlkAddr, uint8_t cbPBlk,
322	const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(5, 0);
323
324
325	/**
326	* Finalizes the current scope object, nothing can be added to the scope afterwards.
327	*
328	* @returns IPRT status code.
329	* @param hAcpiTbl The ACPI table handle.
330	*/
331	RTDECL(int) RTAcpiTblProcessorFinalize(RTACPITBL hAcpiTbl);
332
333
334	/**
335	* Starts a new method object for the given ACPI table in the current scope.
336	*
337	* @returns IPRT status code.
338	* @param hAcpiTbl The ACPI table handle.
339	* @param pszName The method name.
340	* @param fFlags AML method flags, see RTACPI_METHOD_F_XXX.
341	* @param cArgs Number of arguments this method takes.
342	* @param uSyncLvl The sync level.
343	*/
344	RTDECL(int) RTAcpiTblMethodStart(RTACPITBL hAcpiTbl, const char *pszName, uint8_t cArgs, uint32_t fFlags, uint8_t uSyncLvl);
345
346
347	/** ACPI method is not serialized. */
348	#define RTACPI_METHOD_F_NOT_SERIALIZED 0
349	/** ACPI method call needs to be serialized in the ACPI interpreter. */
350	#define RTACPI_METHOD_F_SERIALIZED RT_BIT_32(0)
351
352
353	/**
354	* Finalizes the current method object, nothing can be added to the method afterwards.
355	*
356	* @returns IPRT status code.
357	* @param hAcpiTbl The ACPI table handle.
358	*/
359	RTDECL(int) RTAcpiTblMethodFinalize(RTACPITBL hAcpiTbl);
360
361
362	/**
363	* Appends a new DefName object (only the NameOp NameString part, DataRefObject is left for the caller
364	* to append).
365	*
366	* @returns IPRT status code.
367	* @param hAcpiTbl The ACPI table handle.
368	* @param pszName The name to append.
369	*/
370	RTDECL(int) RTAcpiTblNameAppend(RTACPITBL hAcpiTbl, const char *pszName);
371
372
373	/**
374	* Appends a new NullName object.
375	*
376	* @returns IPRT status code.
377	* @param hAcpiTbl The ACPI table handle.
378	*/
379	RTDECL(int) RTAcpiTblNullNameAppend(RTACPITBL hAcpiTbl);
380
381
382	/**
383	* Appends a new NameString object.
384	*
385	* @returns IPRT status code.
386	* @param hAcpiTbl The ACPI table handle.
387	* @param pszName The name to append.
388	*/
389	RTDECL(int) RTAcpiTblNameStringAppend(RTACPITBL hAcpiTbl, const char *pszName);
390
391
392	/**
393	* Appends a new String object.
394	*
395	* @returns IPRT status code.
396	* @param hAcpiTbl The ACPI table handle.
397	* @param psz The string to append.
398	*/
399	RTDECL(int) RTAcpiTblStringAppend(RTACPITBL hAcpiTbl, const char *psz);
400
401
402	/**
403	* Appends a given UTF-8 string as UTF-16 using a buffer object (Unicode() equivalent).
404	*
405	* @returns IPRT status code.
406	* @param hAcpiTbl The ACPI table handle.
407	* @param psz The string to append.
408	*/
409	RTDECL(int) RTAcpiTblStringAppendAsUtf16(RTACPITBL hAcpiTbl, const char *psz);
410
411
412	/**
413	* Appends a new integer object (depending on the value ZeroOp, OneOp,
414	* BytePrefix, WordPrefix, DWordPrefix or QWordPrefix is used).
415	*
416	* @returns IPRT status code.
417	* @param hAcpiTbl The ACPI table handle.
418	* @param u64 The 64-bit value to append.
419	*/
420	RTDECL(int) RTAcpiTblIntegerAppend(RTACPITBL hAcpiTbl, uint64_t u64);
421
422
423	/**
424	* Appends a new DefBuffer object under the current scope.
425	*
426	* @returns IPRT status code.
427	* @param hAcpiTbl The ACPI table handle.
428	* @param pvBuf The buffer data.
429	* @param cbBuf Size of the buffer in bytes.
430	*/
431	RTDECL(int) RTAcpiTblBufferAppend(RTACPITBL hAcpiTbl, const void *pvBuf, size_t cbBuf);
432
433
434	/**
435	* Appends the given resource as a DefBuffer under the current scope.
436	*
437	* @returns IPRT status code.
438	* @param hAcpiTbl The ACPI table handle.
439	* @param hAcpiRes The ACPI resource handle.
440	*/
441	RTDECL(int) RTAcpiTblResourceAppend(RTACPITBL hAcpiTbl, RTACPIRES hAcpiRes);
442
443
444	/**
445	* List of statements.
446	*/
447	typedef enum RTACPISTMT
448	{
449	/** Invalid statement. */
450	kAcpiStmt_Invalid = 0,
451	/** Return statement. */
452	kAcpiStmt_Return,
453	/** Breakpoint statement. */
454	kAcpiStmt_Breakpoint,
455	/** No operation statement. */
456	kAcpiStmt_Nop,
457	/** Break statement. */
458	kAcpiStmt_Break,
459	/** Continue statement. */
460	kAcpiStmt_Continue,
461	/** Add(Operand, Operand, Target) statement. */
462	kAcpiStmt_Add,
463	/** Subtract(Operand, Operand, Target) statement. */
464	kAcpiStmt_Subtract,
465	/** And(Operand, Operand, Target) statement. */
466	kAcpiStmt_And,
467	/** Nand(Operand, Operand, Target) statement. */
468	kAcpiStmt_Nand,
469	/** Or(Operand, Operand, Target) statement. */
470	kAcpiStmt_Or,
471	/** Xor(Operand, Operand, Target) statement. */
472	kAcpiStmt_Xor,
473	/** Not(Operand, Target) statement. */
474	kAcpiStmt_Not,
475	/** Store(TermArg, Supername) statement. */
476	kAcpiStmt_Store,
477	/** Index(BuffPkgStrObj, IndexValue, Target) statement. */
478	kAcpiStmt_Index,
479	/** DerefOf(ObjReference) statement. */
480	kAcpiStmt_DerefOf,
481	/** Store(SuperName, TermArg => Integer) statement. */
482	kAcpiStmt_Notify
483	} RTACPISTMT;
484
485
486	/**
487	* Appends the given simple statement to the given ACPI table in the current scope.
488	*
489	* @returns IPRT status code.
490	* @param hAcpiTbl The ACPI table handle.
491	* @param enmStmt The statement to add.
492	*/
493	RTDECL(int) RTAcpiTblStmtSimpleAppend(RTACPITBL hAcpiTbl, RTACPISTMT enmStmt);
494
495
496	/**
497	* Starts a new If statement operation.
498	*
499	* @returns IPRT status code.
500	* @param hAcpiTbl The ACPI table handle.
501	*/
502	RTDECL(int) RTAcpiTblIfStart(RTACPITBL hAcpiTbl);
503
504
505	/**
506	* Finalizes the current If statement operation.
507	*
508	* @returns IPRT status code.
509	* @param hAcpiTbl The ACPI table handle.
510	*/
511	RTDECL(int) RTAcpiTblIfFinalize(RTACPITBL hAcpiTbl);
512
513
514	/**
515	* Starts a new Else operation (only valid if currently inside an If oepration).
516	*
517	* @returns IPRT status code.
518	* @param hAcpiTbl The ACPI table handle.
519	*/
520	RTDECL(int) RTAcpiTblElseStart(RTACPITBL hAcpiTbl);
521
522
523	/**
524	* Finalizes the current Else statement operation.
525	*
526	* @returns IPRT status code.
527	* @param hAcpiTbl The ACPI table handle.
528	*/
529	RTDECL(int) RTAcpiTblElseFinalize(RTACPITBL hAcpiTbl);
530
531
532	/**
533	* List of binary operations.
534	*/
535	typedef enum RTACPIBINARYOP
536	{
537	/** Invalid binary operation. */
538	kAcpiBinaryOp_Invalid = 0,
539	/** LAnd(Operand, Operand). */
540	kAcpiBinaryOp_LAnd,
541	/** LEqual(Operand, Operand). */
542	kAcpiBinaryOp_LEqual,
543	/** LGreater(Operand, Operand). */
544	kAcpiBinaryOp_LGreater,
545	/** LGreaterEqual(Operand, Operand). */
546	kAcpiBinaryOp_LGreaterEqual,
547	/** LLess(Operand, Operand). */
548	kAcpiBinaryOp_LLess,
549	/** LLessEqual(Operand, Operand). */
550	kAcpiBinaryOp_LLessEqual,
551	/** LNotEqual(Operand, Operand). */
552	kAcpiBinaryOp_LNotEqual
553	} RTACPIBINARYOP;
554
555
556	/**
557	* Appends the given binary operand.
558	*
559	* @returns IPRT status code.
560	* @param hAcpiTbl The ACPI table handle.
561	* @param enmBinaryOp The binary operation to append.
562	*/
563	RTDECL(int) RTAcpiTblBinaryOpAppend(RTACPITBL hAcpiTbl, RTACPIBINARYOP enmBinaryOp);
564
565
566	/**
567	* Appends the given Arg<idArg> operand.
568	*
569	* @returns IPRT status code.
570	* @param hAcpiTbl The ACPI table handle.
571	* @param idArg The argument ID to append [0..6].
572	*/
573	RTDECL(int) RTAcpiTblArgOpAppend(RTACPITBL hAcpiTbl, uint8_t idArg);
574
575
576	/**
577	* Appends the given Local<idLocal> operand.
578	*
579	* @returns IPRT status code.
580	* @param hAcpiTbl The ACPI table handle.
581	* @param idLocal The local ID to append [0..7].
582	*/
583	RTDECL(int) RTAcpiTblLocalOpAppend(RTACPITBL hAcpiTbl, uint8_t idLocal);
584
585
586	/**
587	* Appends the given UUID as a buffer object.
588	*
589	* @returns IPRT status code.
590	* @param hAcpiTbl The ACPI table handle.
591	* @param pUuid The UUID to append.
592	*/
593	RTDECL(int) RTAcpiTblUuidAppend(RTACPITBL hAcpiTbl, PCRTUUID pUuid);
594
595
596	/**
597	* Appends the given UUID string as a UUID buffer object.
598	*
599	* @returns IPRT status code.
600	* @param hAcpiTbl The ACPI table handle.
601	* @param pszUuid The UUID string to append as a buffer.
602	*/
603	RTDECL(int) RTAcpiTblUuidAppendFromStr(RTACPITBL hAcpiTbl, const char *pszUuid);
604
605
606	/**
607	* Known operation region space types.
608	*/
609	typedef enum RTACPIOPREGIONSPACE
610	{
611	/** Invalid region space type. */
612	kAcpiOperationRegionSpace_Invalid = 0,
613	/** Region is in system memory space. */
614	kAcpiOperationRegionSpace_SystemMemory,
615	/** Region is in system I/O space. */
616	kAcpiOperationRegionSpace_SystemIo,
617	/** Region is in PCI config space. */
618	kAcpiOperationRegionSpace_PciConfig,
619	/** Region is in embedded control space. */
620	kAcpiOperationRegionSpace_EmbeddedControl,
621	/** Region is in SMBUS space. */
622	kAcpiOperationRegionSpace_SmBus,
623	/** Region is in system CMOS space. */
624	kAcpiOperationRegionSpace_SystemCmos,
625	/** Region is a PCI bar target. */
626	kAcpiOperationRegionSpace_PciBarTarget,
627	/** Region is in IPMI space. */
628	kAcpiOperationRegionSpace_Ipmi,
629	/** Region is in GPIO space. */
630	kAcpiOperationRegionSpace_Gpio,
631	/** Region is in generic serial bus space. */
632	kAcpiOperationRegionSpace_GenericSerialBus,
633	/** Region is in platform communications channel (PCC) space. */
634	kAcpiOperationRegionSpace_Pcc,
635	/** 32bit hack. */
636	kAcpiOperationRegionSpace_32bit_Hack = 0x7fffffff
637	} RTACPIOPREGIONSPACE;
638
639
640	/**
641	* Appends a new OperationRegion() to the given ACPI table - extended version.
642	*
643	* @returns IPRT status code.
644	* @param hAcpiTbl The ACPI table handle.
645	* @param pszName The name of the operation region.
646	* @param enmSpace The operation region space type.
647	*
648	* @note This doesn't encode the region offset and size arguments but leaves it up to the caller
649	* to be able to encode complex stuff.
650	*/
651	RTDECL(int) RTAcpiTblOpRegionAppendEx(RTACPITBL hAcpiTbl, const char *pszName, RTACPIOPREGIONSPACE enmSpace);
652
653
654	/**
655	* Appends a new OperationRegion() to the given ACPI table.
656	*
657	* @returns IPRT status code.
658	* @param hAcpiTbl The ACPI table handle.
659	* @param pszName The name of the operation region.
660	* @param enmSpace The operation region space type.
661	* @param offRegion Offset of the region.
662	* @param cbRegion Size of the region in bytes.
663	*/
664	RTDECL(int) RTAcpiTblOpRegionAppend(RTACPITBL hAcpiTbl, const char *pszName, RTACPIOPREGIONSPACE enmSpace,
665	uint64_t offRegion, uint64_t cbRegion);
666
667
668	/**
669	* Field access type.
670	*/
671	typedef enum RTACPIFIELDACC
672	{
673	/** Invalid access type. */
674	kAcpiFieldAcc_Invalid = 0,
675	/** Any access width is okay. */
676	kAcpiFieldAcc_Any,
677	/** Byte (8-bit) access. */
678	kAcpiFieldAcc_Byte,
679	/** Word (16-bit) access. */
680	kAcpiFieldAcc_Word,
681	/** Double word (32-bit) access. */
682	kAcpiFieldAcc_DWord,
683	/** Quad word (64-bit) access. */
684	kAcpiFieldAcc_QWord,
685	/** Buffer like access. */
686	kAcpiFieldAcc_Buffer
687	} RTACPIFIELDACC;
688
689
690	/**
691	* Field update rule.
692	*/
693	typedef enum RTACPIFIELDUPDATE
694	{
695	/** Invalid upadte rule. */
696	kAcpiFieldUpdate_Invalid = 0,
697	/** Preserve content not being accessed. */
698	kAcpiFieldUpdate_Preserve,
699	/** Write as ones. */
700	kAcpiFieldUpdate_WriteAsOnes,
701	/** Write as zeroes. */
702	kAcpiFieldUpdate_WriteAsZeroes
703	} RTACPIFIELDUPDATE;
704
705
706	/**
707	* Field entry.
708	*/
709	typedef struct RTACPIFIELDENTRY
710	{
711	/** The field name - NULL means the NullName. */
712	const char *pszName;
713	/** Number of bits of the field. */
714	uint64_t cBits;
715	} RTACPIFIELDENTRY;
716	/** Pointer to a field entry. */
717	typedef RTACPIFIELDENTRY *PRTACPIFIELDENTRY;
718	/** Pointer to a const field entry. */
719	typedef const RTACPIFIELDENTRY *PCRTACPIFIELDENTRY;
720
721
722	/**
723	* Appends a new field descriptor to the given ACPI table.
724	*
725	* @returns IPRT status code.
726	* @param hAcpiTbl The ACPI table handle.
727	* @param pszNameRef The region/buffer the field describes.
728	* @param enmAcc The access type,
729	* @param fLock Flag whether access must happen under a lock.
730	* @param enmUpdate The update rule.
731	* @param paFields Pointer to the field descriptors.
732	* @param cFields Number of entries in the array.
733	*/
734	RTDECL(int) RTAcpiTblFieldAppend(RTACPITBL hAcpiTbl, const char *pszNameRef, RTACPIFIELDACC enmAcc,
735	bool fLock, RTACPIFIELDUPDATE enmUpdate, PCRTACPIFIELDENTRY paFields,
736	uint32_t cFields);
737
738
739	/**
740	* Object type.
741	*/
742	typedef enum RTACPIOBJTYPE
743	{
744	/** Invalid object type. */
745	kAcpiObjType_Invalid = 0,
746	/** Unknown object - UnknownObj */
747	kAcpiObjType_Unknown,
748	/** Integer object - IntObj */
749	kAcpiObjType_Int,
750	/** String object - StrObj */
751	kAcpiObjType_Str,
752	/** Buffer object - BuffObj */
753	kAcpiObjType_Buff,
754	/** Package object - PkgObj */
755	kAcpiObjType_Pkg,
756	/** Field unit object - FieldUnitObj */
757	kAcpiObjType_FieldUnit,
758	/** Device object - DeviceObj */
759	kAcpiObjType_Device,
760	/** Event object - EventObj */
761	kAcpiObjType_Event,
762	/** Method object - MethodObj */
763	kAcpiObjType_Method,
764	/** Mutex object - MutexObj */
765	kAcpiObjType_MutexObj,
766	/** OpRegion object - OpRegionObj */
767	kAcpiObjType_OpRegion,
768	/** Power resource object - PowerResObj */
769	kAcpiObjType_PowerRes,
770	/** Thermal zone object - ThermalZoneObj */
771	kAcpiObjType_ThermalZone,
772	/** Buffer field object - BuffFieldObj */
773	kAcpiObjType_BuffField,
774	/** Processor object - ProcessorObj */
775	kAcpiObjType_Processor
776	} RTACPIOBJTYPE;
777
778
779	/**
780	* Appends a new External declaration to the given ACPI table.
781	*
782	* @returns IPRT status code.
783	* @param hAcpiTbl The ACPI table handle.
784	* @param pszName The name stirng of the external object.
785	* @param enmObjType The object type.
786	* @param cArgs Number of arguments for the object (mostly method), valid is [0..7].
787	*/
788	RTDECL(int) RTAcpiTblExternalAppend(RTACPITBL hAcpiTbl, const char *pszName, RTACPIOBJTYPE enmObjType, uint8_t cArgs);
789
790
791	/** @name ACPI resource builder related API.
792	* @{ */
793
794	/**
795	* Creates a new empty resource template.
796	*
797	* @returns IPRT status code.
798	* @param phAcpiRes Where to store the handle to the ACPI resource on success.
799	*/
800	RTDECL(int) RTAcpiResourceCreate(PRTACPIRES phAcpiRes);
801
802
803	/**
804	* Destroys the given ACPI resource, freeing all allocated resources.
805	*
806	* @param hAcpiRes The ACPI resource handle to destroy.
807	*/
808	RTDECL(void) RTAcpiResourceDestroy(RTACPIRES hAcpiRes);
809
810
811	/**
812	* Resets the given ACPI resource handle to create a new empty template.
813	*
814	* @param hAcpiRes The ACPI resource handle.
815	*/
816	RTDECL(void) RTAcpiResourceReset(RTACPIRES hAcpiRes);
817
818
819	/**
820	* Seals the given ACPI resource against further changes and adds any
821	* missing data required to complete the resource buffer.
822	*
823	* @returns IPRT status code.
824	* @param hAcpiRes The ACPI resource handle.
825	*
826	* @note After a call to this method completed successfully it is not possible
827	* to add new resources until RTAcpiResourceReset() was called.
828	*/
829	RTDECL(int) RTAcpiResourceSeal(RTACPIRES hAcpiRes);
830
831
832	/**
833	* Queries the pointer to the buffer holding the encoded data.
834	*
835	* @returns IPRT status code.
836	* @param hAcpiRes The ACPI resource handle.
837	* @param ppvRes Where to store the pointer to the buffer holding the encoded resource template on success.
838	* @param pcbRes Where to store the size of the encoded data in bytes on success.
839	*
840	* @note The ACPI resource must be successfully sealed with RTAcpiResourceSeal() for this function to succeed.
841	* Also the buffer pointer will only be valid until a call to any other RTAcpiResource* method.
842	*/
843	RTDECL(int) RTAcpiResourceQueryBuffer(RTACPIRES hAcpiRes, const void *ppvRes, size_t pcbRes);
844
845
846	/**
847	* Adds a fixed memory range with the given start address and size to the given ACPI resource.
848	*
849	* @returns IPRT status code.
850	* @param hAcpiRes The ACPI resource handle.
851	* @param u32AddrBase The base address to encode.
852	* @param cbRange The range length in bytes to encode.
853	* @param fRw Flag whether this address range is read-write or read-only.
854	*/
855	RTDECL(int) RTAcpiResourceAdd32BitFixedMemoryRange(RTACPIRES hAcpiRes, uint32_t u32AddrBase, uint32_t cbRange,
856	bool fRw);
857
858
859	/**
860	* Adds an extended interrupt descriptor with the given configuration to the given ACPI resource.
861	*
862	* @returns IPRT status code.
863	* @param hAcpiRes The ACPI resource handle.
864	* @param fConsumer Flag whether the entity this resource is assigned to consumes the interrupt (true) or produces it (false).
865	* @param fEdgeTriggered Flag whether the interrupt is edged (true) or level (false) triggered.
866	* @param fActiveLow Flag whether the interrupt polarity is active low (true) or active high (false).
867	* @param fShared Flag whether the interrupt is shared between different entities (true) or exclusive to the assigned entity (false).
868	* @param fWakeCapable Flag whether the interrupt can wake the system (true) or not (false).
869	* @param cIntrs Number of interrupts following.
870	* @param pau32Intrs Pointer to the array of interrupt numbers.
871	*/
872	RTDECL(int) RTAcpiResourceAddExtendedInterrupt(RTACPIRES hAcpiRes, bool fConsumer, bool fEdgeTriggered, bool fActiveLow, bool fShared,
873	bool fWakeCapable, uint8_t cIntrs, uint32_t *pau32Intrs);
874
875
876	/** @name Generic address space flags.
877	* @{ */
878	#define RTACPI_RESOURCE_ADDR_RANGE_F_DECODE_TYPE_SUB RT_BIT_32(0)
879	#define RTACPI_RESOURCE_ADDR_RANGE_F_DECODE_TYPE_POS 0
880
881	#define RTACPI_RESOURCE_ADDR_RANGE_F_MIN_ADDR_FIXED RT_BIT_32(1)
882	#define RTACPI_RESOURCE_ADDR_RANGE_F_MIN_ADDR_CHANGEABLE 0
883
884	#define RTACPI_RESOURCE_ADDR_RANGE_F_MAX_ADDR_FIXED RT_BIT_32(2)
885	#define RTACPI_RESOURCE_ADDR_RANGE_F_MAX_ADDR_CHANGEABLE 0
886
887	#define RTACPI_RESOURCE_ADDR_RANGE_F_VALID_MASK UINT32_C(0x00000007)
888	/** @} */
889
890	/**
891	* Memory range cacheability
892	*/
893	typedef enum RTACPIRESMEMRANGECACHEABILITY
894	{
895	/** Usual invalid value. */
896	kAcpiResMemRangeCacheability_Invalid = 0,
897	/** Memory range is non cacheable (like MMIO, etc.). */
898	kAcpiResMemRangeCacheability_NonCacheable,
899	/** Memory is cacheable. */
900	kAcpiResMemRangeCacheability_Cacheable,
901	/** Memory is cacheable and supports write comining. */
902	kAcpiResMemRangeCacheability_CacheableWriteCombining,
903	/** Memory is cacheable and supports prefetching. */
904	kAcpiResMemRangeCacheability_CacheablePrefetchable,
905	/** 32-bit blow up hack. */
906	kAcpiResMemRangeCacheability_32BitHack = 0x7fffffff
907	} RTACPIRESMEMRANGECACHEABILITY;
908
909
910	/**
911	* Memory attribute.
912	*/
913	typedef enum RTACPIRESMEMRANGETYPE
914	{
915	/** Invalid memory range type. */
916	kAcpiResMemType_Invalid = 0,
917	/** Memory range is actual memory. */
918	kAcpiResMemType_Memory,
919	/** Memory range is reserved. */
920	kAcpiResMemType_Reserved,
921	/** Memory range is reserved to ACPI. */
922	kAcpiResMemType_Acpi,
923	/** Memory range is no volatile storage. */
924	kAcpiResMemType_Nvs,
925	/** 32-bit blow up hack. */
926	kAcpiResMemType_32BitHack = 0x7fffffff
927	} RTACPIRESMEMRANGETYPE;
928
929
930	/**
931	* Adds a quad word (64-bit) memory range to the given ACPI resource.
932	*
933	* @returns IPRT status code.
934	* @param hAcpiRes The ACPI resource handle.
935	* @param enmCacheability The cacheability of the memory range.
936	* @param enmType Memory range type.
937	* @param fRw Flag whether the memory range is read/write (true) or readonly (false).
938	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
939	* @param u64AddrMin The start address of the memory range.
940	* @param u64AddrMax Last valid address of the range.
941	* @param u64OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
942	* @param u64Granularity The access granularity of the range in bytes.
943	* @param u64Length Length of the memory range in bytes.
944	*/
945	RTDECL(int) RTAcpiResourceAddQWordMemoryRange(RTACPIRES hAcpiRes, RTACPIRESMEMRANGECACHEABILITY enmCacheability,
946	RTACPIRESMEMRANGETYPE enmType, bool fRw, uint32_t fAddrSpace,
947	uint64_t u64AddrMin, uint64_t u64AddrMax, uint64_t u64OffTrans,
948	uint64_t u64Granularity, uint64_t u64Length);
949
950
951	/**
952	* Adds a double word (32-bit) memory range to the given ACPI resource.
953	*
954	* @returns IPRT status code.
955	* @param hAcpiRes The ACPI resource handle.
956	* @param enmCacheability The cacheability of the memory range.
957	* @param enmType Memory range type.
958	* @param fRw Flag whether the memory range is read/write (true) or readonly (false).
959	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
960	* @param u32AddrMin The start address of the memory range.
961	* @param u32AddrMax Last valid address of the range.
962	* @param u32OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
963	* @param u32Granularity The access granularity of the range in bytes.
964	* @param u32Length Length of the memory range in bytes.
965	*/
966	RTDECL(int) RTAcpiResourceAddDWordMemoryRange(RTACPIRES hAcpiRes, RTACPIRESMEMRANGECACHEABILITY enmCacheability,
967	RTACPIRESMEMRANGETYPE enmType, bool fRw, uint32_t fAddrSpace,
968	uint32_t u32AddrMin, uint32_t u32AddrMax, uint32_t u32OffTrans,
969	uint32_t u32Granularity, uint32_t u32Length);
970
971
972	/**
973	* I/O range coverage.
974	*/
975	typedef enum RTACPIRESIORANGE
976	{
977	/** Invalid range. */
978	kAcpiResIoRange_Invalid = 0,
979	/** Range covers only non ISA I/O ports. */
980	kAcpiResIoRange_NonIsaOnly,
981	/** Range covers only ISA I/O ports. */
982	kAcpiResIoRange_IsaOnly,
983	/** Range covers the whole I/O port range. */
984	kAcpiResIoRange_Whole,
985	/** 32-bit blow up hack. */
986	kAcpiResIoRange_32BitHack = 0x7fffffff
987	} RTACPIRESIORANGE;
988
989
990	/**
991	* I/O range type.
992	*/
993	typedef enum RTACPIRESIORANGETYPE
994	{
995	/** Invalid value. */
996	kAcpiResIoRangeType_Invalid = 0,
997	/** Resource is I/O on the primary and secondary side of the bridge. */
998	kAcpiResIoRangeType_Static,
999	/** Resource is memory on the primary and I/O on the secondary side of the bridge,
1000	* primary side memory address for a given I/O port is calculated with
1001	* address = (((Port & 0xfffc) << 10) \|\| (Port & 0xfff)) + AddrMin. */
1002	kAcpiResIoRangeType_Translation_Sparse,
1003	/** Resource is memory on the primary and I/O on the secondary side of the bridge,
1004	* primary side memory address for a given I/O port is calculated with
1005	* address = AddrMin + Port. */
1006	kAcpiResIoRangeType_Translation_Dense,
1007	/** 32-bit blowup hack. */
1008	kAcpiResIoRangeType_32BitHack = 0x7fffffff
1009	} RTACPIRESIORANGETYPE;
1010
1011
1012	/**
1013	* Adds a quad word (64-bit) I/O range to the given ACPI resource.
1014	*
1015	* @returns IPRT status code.
1016	* @param hAcpiRes The ACPI resource handle.
1017	* @param enmIoType The I/O range type.
1018	* @param enmIoRange The I/O range coverage.
1019	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
1020	* @param u64AddrMin The start address of the memory range.
1021	* @param u64AddrMax Last valid address of the range.
1022	* @param u64OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
1023	* @param u64Granularity The access granularity of the range in bytes.
1024	* @param u64Length Length of the memory range in bytes.
1025	*/
1026	RTDECL(int) RTAcpiResourceAddQWordIoRange(RTACPIRES hAcpiRes, RTACPIRESIORANGETYPE enmIoType, RTACPIRESIORANGE enmIoRange,
1027	uint32_t fAddrSpace, uint64_t u64AddrMin, uint64_t u64AddrMax, uint64_t u64OffTrans,
1028	uint64_t u64Granularity, uint64_t u64Length);
1029
1030
1031	/**
1032	* Adds a word (16-bit) bus number to the given ACPI resource.
1033	*
1034	* @returns IPRT status code.
1035	* @param hAcpiRes The ACPI resource handle.
1036	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
1037	* @param u16BusMin Starting bus number.
1038	* @param u16BusMax Last valid bus number.
1039	* @param u16OffTrans Translation offset being applied to the bus number.
1040	* @param u16Granularity The access granularity of the bus number.
1041	* @param u16Length Length of the bus range.
1042	*/
1043	RTDECL(int) RTAcpiResourceAddWordBusNumber(RTACPIRES hAcpiRes, uint32_t fAddrSpace, uint16_t u16BusMin, uint16_t u16BusMax,
1044	uint16_t u16OffTrans, uint16_t u16Granularity, uint16_t u16Length);
1045
1046	/** @} */
1047
1048	#endif /* IN_RING3 */
1049
1050	/** @} */
1051
1052	RT_C_DECLS_END
1053
1054	#endif /* !IPRT_INCLUDED_acpi_h */
1055

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

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

Download in other formats: