acpi.h@ 107681

Last change on this file since 107681 was 107064, checked in by vboxsync, 3 months ago
Runtime/RTAcpi*: Support more statements, an extended variant of the Region() API, bugref:10733
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 29.9 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	/**
60	* Regenerates the ACPI checksum for the given data.
61	*
62	* @returns The checksum for the given data.
63	* @param pvData The data to check sum.
64	* @param cbData Number of bytes to check sum.
65	*/
66	RTDECL(uint8_t) RTAcpiChecksumGenerate(const void *pvData, size_t cbData);
67
68
69	/**
70	* Generates and writes the table header checksum for the given ACPI table.
71	*
72	* @param pTbl Pointer to the ACPI table to set the checksum for.
73	* @param cbTbl Size of the table in bytes, including the ACPI table header.
74	*/
75	RTDECL(void) RTAcpiTblHdrChecksumGenerate(PACPITBLHDR pTbl, size_t cbTbl);
76
77
78	/**
79	* Creates a new empty ACPI table.
80	*
81	* @returns IPRT status code.
82	* @param phAcpiTbl Where to store the ACPI table handle on success.
83	* @param u32TblSig The signature of the table to use.
84	* @param bRevision The revision of the table.
85	* @param pszOemId The OEM supplied string identifiying the OEM, maximum of 6 characters.
86	* @param pszOemTblId The OEM supplied string identifiying the OEM table, maximum of 8 characters.
87	* @param u32OemRevision The OEM supplied revision number.
88	* @param pszCreatorId Vendor ID of the utility that created the table, maximum of 4 characters.
89	* @param u32CreatorRevision Revision of the utility that created the table.
90	*/
91	RTDECL(int) RTAcpiTblCreate(PRTACPITBL phAcpiTbl, uint32_t u32TblSig, uint8_t bRevision, const char *pszOemId,
92	const char pszOemTblId, uint32_t u32OemRevision, const char pszCreatorId,
93	uint32_t u32CreatorRevision);
94
95
96	/**
97	* Destroys the given ACPI table, freeing all resources.
98	*
99	* @param hAcpiTbl The ACPI table handle to destroy.
100	*/
101	RTDECL(void) RTAcpiTblDestroy(RTACPITBL hAcpiTbl);
102
103
104	/**
105	* Finalizes the given ACPI table, setting the header and generating checksums.
106	*
107	* @returns IPRT status code.
108	* @param hAcpiTbl The ACPI table handle to finalize.
109	*
110	* @note Nothing can be added to the table after this was called.
111	*/
112	RTDECL(int) RTAcpiTblFinalize(RTACPITBL hAcpiTbl);
113
114
115	/**
116	* Returns the size of the given ACPI table.
117	*
118	* @returns Size of the given ACPI table in bytes, 0 on error.
119	* @param hAcpiTbl The ACPI table handle.
120	*
121	* @note This can only be called after RTAcpiTblFinalize() was called successfully.
122	*/
123	RTDECL(uint32_t) RTAcpiTblGetSize(RTACPITBL hAcpiTbl);
124
125
126	/**
127	* Dumps the given ACPI table to the given VFS I/O stream.
128	*
129	* @returns IPRT status code.
130	* @param hAcpiTbl The ACPI table handle.
131	* @param hVfsIos The VFS I/O stream handle to dump the table to.
132	*/
133	RTDECL(int) RTAcpiTblDumpToVfsIoStrm(RTACPITBL hAcpiTbl, RTVFSIOSTREAM hVfsIos);
134
135
136	/**
137	* Dumps the given ACPI table to the given file.
138	*
139	* @returns IPRT status code.
140	* @param hAcpiTbl The ACPI table handle.
141	* @param pszFilename The file path to dump the table to.
142	*/
143	RTDECL(int) RTAcpiTblDumpToFile(RTACPITBL hAcpiTbl, const char *pszFilename);
144
145
146	/**
147	* Starts a new DefScope object.
148	*
149	* @returns IPRT status code.
150	* @param hAcpiTbl The ACPI table handle.
151	* @param pszName Name of the scope, can have a root (\) specifier optionally.
152	*/
153	RTDECL(int) RTAcpiTblScopeStart(RTACPITBL hAcpiTbl, const char *pszName);
154
155
156	/**
157	* Finalizes the current scope object, nothing can be added to the scope afterwards.
158	*
159	* @returns IPRT status code.
160	* @param hAcpiTbl The ACPI table handle.
161	*/
162	RTDECL(int) RTAcpiTblScopeFinalize(RTACPITBL hAcpiTbl);
163
164
165	/**
166	* Starts a new DefPackage object.
167	*
168	* @returns IPRT status code.
169	* @param hAcpiTbl The ACPI table handle.
170	* @param cElements Number of element which will be inside the package,
171	* only supports up to 255 elements, use DefVarPackage if more is required.
172	*/
173	RTDECL(int) RTAcpiTblPackageStart(RTACPITBL hAcpiTbl, uint8_t cElements);
174
175
176	/**
177	* Finalizes the current DefPackage object, and return to the enclosing object's scope.
178	*
179	* @returns IPRT status code.
180	* @param hAcpiTbl The ACPI table handle.
181	*/
182	RTDECL(int) RTAcpiTblPackageFinalize(RTACPITBL hAcpiTbl);
183
184
185	/**
186	* Starts a new device object for the given ACPI table in the current scope.
187	*
188	* @returns IPRT status code.
189	* @param hAcpiTbl The ACPI table handle.
190	* @param pszName Name of the device object, must be <= 4 characters long.
191	*/
192	RTDECL(int) RTAcpiTblDeviceStart(RTACPITBL hAcpiTbl, const char *pszName);
193
194
195	/**
196	* Starts a new device object for the given ACPI table in the current scope.
197	*
198	* @returns IPRT status code.
199	* @param hAcpiTbl The ACPI table handle.
200	* @param pszNameFmt The name of the device as a format string.
201	* @param ... The format arguments.
202	*/
203	RTDECL(int) RTAcpiTblDeviceStartF(RTACPITBL hAcpiTbl, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(2, 3);
204
205
206	/**
207	* Starts a new device object for the given ACPI table in the current scope.
208	*
209	* @returns IPRT status code.
210	* @param hAcpiTbl The ACPI table handle.
211	* @param pszNameFmt The name of the device as a format string.
212	* @param va The format arguments.
213	*/
214	RTDECL(int) RTAcpiTblDeviceStartV(RTACPITBL hAcpiTbl, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
215
216
217	/**
218	* Finalizes the current scope object, nothing can be added to the scope afterwards.
219	*
220	* @returns IPRT status code.
221	* @param hAcpiTbl The ACPI table handle.
222	*/
223	RTDECL(int) RTAcpiTblDeviceFinalize(RTACPITBL hAcpiTbl);
224
225
226	/**
227	* Starts a new method object for the given ACPI table in the current scope.
228	*
229	* @returns IPRT status code.
230	* @param hAcpiTbl The ACPI table handle.
231	* @param pszName The method name.
232	* @param fFlags AML method flags, see RTACPI_METHOD_F_XXX.
233	* @param cArgs Number of arguments this method takes.
234	* @param uSyncLvl The sync level.
235	*/
236	RTDECL(int) RTAcpiTblMethodStart(RTACPITBL hAcpiTbl, const char *pszName, uint8_t cArgs, uint32_t fFlags, uint8_t uSyncLvl);
237
238
239	/** ACPI method is not serialized. */
240	#define RTACPI_METHOD_F_NOT_SERIALIZED 0
241	/** ACPI method call needs to be serialized in the ACPI interpreter. */
242	#define RTACPI_METHOD_F_SERIALIZED RT_BIT_32(0)
243
244
245	/**
246	* Finalizes the current method object, nothing can be added to the method afterwards.
247	*
248	* @returns IPRT status code.
249	* @param hAcpiTbl The ACPI table handle.
250	*/
251	RTDECL(int) RTAcpiTblMethodFinalize(RTACPITBL hAcpiTbl);
252
253
254	/**
255	* Appends a new DefName object (only the NameOp NameString part, DataRefObject is left for the caller
256	* to append).
257	*
258	* @returns IPRT status code.
259	* @param hAcpiTbl The ACPI table handle.
260	* @param pszName The name to append.
261	*/
262	RTDECL(int) RTAcpiTblNameAppend(RTACPITBL hAcpiTbl, const char *pszName);
263
264
265	/**
266	* Appends a new NullName object.
267	*
268	* @returns IPRT status code.
269	* @param hAcpiTbl The ACPI table handle.
270	*/
271	RTDECL(int) RTAcpiTblNullNameAppend(RTACPITBL hAcpiTbl);
272
273
274	/**
275	* Appends a new NameString object.
276	*
277	* @returns IPRT status code.
278	* @param hAcpiTbl The ACPI table handle.
279	* @param pszName The name to append.
280	*/
281	RTDECL(int) RTAcpiTblNameStringAppend(RTACPITBL hAcpiTbl, const char *pszName);
282
283
284	/**
285	* Appends a new String object.
286	*
287	* @returns IPRT status code.
288	* @param hAcpiTbl The ACPI table handle.
289	* @param psz The string to append.
290	*/
291	RTDECL(int) RTAcpiTblStringAppend(RTACPITBL hAcpiTbl, const char *psz);
292
293
294	/**
295	* Appends a new integer object (depending on the value ZeroOp, OneOp,
296	* BytePrefix, WordPrefix, DWordPrefix or QWordPrefix is used).
297	*
298	* @returns IPRT status code.
299	* @param hAcpiTbl The ACPI table handle.
300	* @param u64 The 64-bit value to append.
301	*/
302	RTDECL(int) RTAcpiTblIntegerAppend(RTACPITBL hAcpiTbl, uint64_t u64);
303
304
305	/**
306	* Appends a new DefBuffer object under the current scope.
307	*
308	* @returns IPRT status code.
309	* @param hAcpiTbl The ACPI table handle.
310	* @param pvBuf The buffer data.
311	* @param cbBuf Size of the buffer in bytes.
312	*/
313	RTDECL(int) RTAcpiTblBufferAppend(RTACPITBL hAcpiTbl, const void *pvBuf, size_t cbBuf);
314
315
316	/**
317	* Appends the given resource as a DefBuffer under the current scope.
318	*
319	* @returns IPRT status code.
320	* @param hAcpiTbl The ACPI table handle.
321	* @param hAcpiRes The ACPI resource handle.
322	*/
323	RTDECL(int) RTAcpiTblResourceAppend(RTACPITBL hAcpiTbl, RTACPIRES hAcpiRes);
324
325
326	/**
327	* List of statements.
328	*/
329	typedef enum RTACPISTMT
330	{
331	/** Invalid statement. */
332	kAcpiStmt_Invalid = 0,
333	/** Return statement. */
334	kAcpiStmt_Return,
335	/** Breakpoint statement. */
336	kAcpiStmt_Breakpoint,
337	/** No operation statement. */
338	kAcpiStmt_Nop,
339	/** Break statement. */
340	kAcpiStmt_Break,
341	/** Continue statement. */
342	kAcpiStmt_Continue,
343	/** Add(Operand, Operand, Target) statement. */
344	kAcpiStmt_Add,
345	/** Subtract(Operand, Operand, Target) statement. */
346	kAcpiStmt_Subtract,
347	/** And(Operand, Operand, Target) statement. */
348	kAcpiStmt_And,
349	/** Nand(Operand, Operand, Target) statement. */
350	kAcpiStmt_Nand,
351	/** Or(Operand, Operand, Target) statement. */
352	kAcpiStmt_Or,
353	/** Xor(Operand, Operand, Target) statement. */
354	kAcpiStmt_Xor,
355	/** Not(Operand, Target) statement. */
356	kAcpiStmt_Not,
357	/** Store(TermArg, Supername) statement. */
358	kAcpiStmt_Store,
359	/** Index(BuffPkgStrObj, IndexValue, Target) statement. */
360	kAcpiStmt_Index,
361	/** DerefOf(ObjReference) statement. */
362	kAcpiStmt_DerefOf
363	} RTACPISTMT;
364
365
366	/**
367	* Appends the given simple statement to the given ACPI table in the current scope.
368	*
369	* @returns IPRT status code.
370	* @param hAcpiTbl The ACPI table handle.
371	* @param enmStmt The statement to add.
372	*/
373	RTDECL(int) RTAcpiTblStmtSimpleAppend(RTACPITBL hAcpiTbl, RTACPISTMT enmStmt);
374
375
376	/**
377	* Starts a new If statement operation.
378	*
379	* @returns IPRT status code.
380	* @param hAcpiTbl The ACPI table handle.
381	*/
382	RTDECL(int) RTAcpiTblIfStart(RTACPITBL hAcpiTbl);
383
384
385	/**
386	* Finalizes the current If statement operation.
387	*
388	* @returns IPRT status code.
389	* @param hAcpiTbl The ACPI table handle.
390	*/
391	RTDECL(int) RTAcpiTblIfFinalize(RTACPITBL hAcpiTbl);
392
393
394	/**
395	* Starts a new Else operation (only valid if currently inside an If oepration).
396	*
397	* @returns IPRT status code.
398	* @param hAcpiTbl The ACPI table handle.
399	*/
400	RTDECL(int) RTAcpiTblElseStart(RTACPITBL hAcpiTbl);
401
402
403	/**
404	* Finalizes the current Else statement operation.
405	*
406	* @returns IPRT status code.
407	* @param hAcpiTbl The ACPI table handle.
408	*/
409	RTDECL(int) RTAcpiTblElseFinalize(RTACPITBL hAcpiTbl);
410
411
412	/**
413	* List of binary operations.
414	*/
415	typedef enum RTACPIBINARYOP
416	{
417	/** Invalid binary operation. */
418	kAcpiBinaryOp_Invalid = 0,
419	/** LAnd(Operand, Operand). */
420	kAcpiBinaryOp_LAnd,
421	/** LEqual(Operand, Operand). */
422	kAcpiBinaryOp_LEqual,
423	/** LGreater(Operand, Operand). */
424	kAcpiBinaryOp_LGreater,
425	/** LGreaterEqual(Operand, Operand). */
426	kAcpiBinaryOp_LGreaterEqual,
427	/** LLess(Operand, Operand). */
428	kAcpiBinaryOp_LLess,
429	/** LLessEqual(Operand, Operand). */
430	kAcpiBinaryOp_LLessEqual,
431	/** LNotEqual(Operand, Operand). */
432	kAcpiBinaryOp_LNotEqual
433	} RTACPIBINARYOP;
434
435
436	/**
437	* Appends the given binary operand.
438	*
439	* @returns IPRT status code.
440	* @param hAcpiTbl The ACPI table handle.
441	* @param enmBinaryOp The binary operation to append.
442	*/
443	RTDECL(int) RTAcpiTblBinaryOpAppend(RTACPITBL hAcpiTbl, RTACPIBINARYOP enmBinaryOp);
444
445
446	/**
447	* Appends the given Arg<idArg> operand.
448	*
449	* @returns IPRT status code.
450	* @param hAcpiTbl The ACPI table handle.
451	* @param idArg The argument ID to append [0..6].
452	*/
453	RTDECL(int) RTAcpiTblArgOpAppend(RTACPITBL hAcpiTbl, uint8_t idArg);
454
455
456	/**
457	* Appends the given Local<idLocal> operand.
458	*
459	* @returns IPRT status code.
460	* @param hAcpiTbl The ACPI table handle.
461	* @param idLocal The local ID to append [0..7].
462	*/
463	RTDECL(int) RTAcpiTblLocalOpAppend(RTACPITBL hAcpiTbl, uint8_t idLocal);
464
465
466	/**
467	* Appends the given UUID as a buffer object.
468	*
469	* @returns IPRT status code.
470	* @param hAcpiTbl The ACPI table handle.
471	* @param pUuid The UUID to append.
472	*/
473	RTDECL(int) RTAcpiTblUuidAppend(RTACPITBL hAcpiTbl, PCRTUUID pUuid);
474
475
476	/**
477	* Appends the given UUID string as a UUID buffer object.
478	*
479	* @returns IPRT status code.
480	* @param hAcpiTbl The ACPI table handle.
481	* @param pszUuid The UUID string to append as a buffer.
482	*/
483	RTDECL(int) RTAcpiTblUuidAppendFromStr(RTACPITBL hAcpiTbl, const char *pszUuid);
484
485
486	/**
487	* Known operation region space types.
488	*/
489	typedef enum RTACPIOPREGIONSPACE
490	{
491	/** Invalid region space type. */
492	kAcpiOperationRegionSpace_Invalid = 0,
493	/** Region is in system memory space. */
494	kAcpiOperationRegionSpace_SystemMemory,
495	/** Region is in system I/O space. */
496	kAcpiOperationRegionSpace_SystemIo,
497	/** Region is in PCI config space. */
498	kAcpiOperationRegionSpace_PciConfig,
499	/** Region is in embedded control space. */
500	kAcpiOperationRegionSpace_EmbeddedControl,
501	/** Region is in SMBUS space. */
502	kAcpiOperationRegionSpace_SmBus,
503	/** Region is in system CMOS space. */
504	kAcpiOperationRegionSpace_SystemCmos,
505	/** Region is a PCI bar target. */
506	kAcpiOperationRegionSpace_PciBarTarget,
507	/** Region is in IPMI space. */
508	kAcpiOperationRegionSpace_Ipmi,
509	/** Region is in GPIO space. */
510	kAcpiOperationRegionSpace_Gpio,
511	/** Region is in generic serial bus space. */
512	kAcpiOperationRegionSpace_GenericSerialBus,
513	/** Region is in platform communications channel (PCC) space. */
514	kAcpiOperationRegionSpace_Pcc,
515	/** 32bit hack. */
516	kAcpiOperationRegionSpace_32bit_Hack = 0x7fffffff
517	} RTACPIOPREGIONSPACE;
518
519
520	/**
521	* Appends a new OperationRegion() to the given ACPI table - extended version.
522	*
523	* @returns IPRT status code.
524	* @param hAcpiTbl The ACPI table handle.
525	* @param pszName The name of the operation region.
526	* @param enmSpace The operation region space type.
527	*
528	* @note This doesn't encode the region offset and size arguments but leaves it up to the caller
529	* to be able to encode complex stuff.
530	*/
531	RTDECL(int) RTAcpiTblOpRegionAppendEx(RTACPITBL hAcpiTbl, const char *pszName, RTACPIOPREGIONSPACE enmSpace);
532
533
534	/**
535	* Appends a new OperationRegion() to the given ACPI table.
536	*
537	* @returns IPRT status code.
538	* @param hAcpiTbl The ACPI table handle.
539	* @param pszName The name of the operation region.
540	* @param enmSpace The operation region space type.
541	* @param offRegion Offset of the region.
542	* @param cbRegion Size of the region in bytes.
543	*/
544	RTDECL(int) RTAcpiTblOpRegionAppend(RTACPITBL hAcpiTbl, const char *pszName, RTACPIOPREGIONSPACE enmSpace,
545	uint64_t offRegion, uint64_t cbRegion);
546
547
548	/**
549	* Field access type.
550	*/
551	typedef enum RTACPIFIELDACC
552	{
553	/** Invalid access type. */
554	kAcpiFieldAcc_Invalid = 0,
555	/** Any access width is okay. */
556	kAcpiFieldAcc_Any,
557	/** Byte (8-bit) access. */
558	kAcpiFieldAcc_Byte,
559	/** Word (16-bit) access. */
560	kAcpiFieldAcc_Word,
561	/** Double word (32-bit) access. */
562	kAcpiFieldAcc_DWord,
563	/** Quad word (64-bit) access. */
564	kAcpiFieldAcc_QWord,
565	/** Buffer like access. */
566	kAcpiFieldAcc_Buffer
567	} RTACPIFIELDACC;
568
569
570	/**
571	* Field update rule.
572	*/
573	typedef enum RTACPIFIELDUPDATE
574	{
575	/** Invalid upadte rule. */
576	kAcpiFieldUpdate_Invalid = 0,
577	/** Preserve content not being accessed. */
578	kAcpiFieldUpdate_Preserve,
579	/** Write as ones. */
580	kAcpiFieldUpdate_WriteAsOnes,
581	/** Write as zeroes. */
582	kAcpiFieldUpdate_WriteAsZeroes
583	} RTACPIFIELDUPDATE;
584
585
586	/**
587	* Field entry.
588	*/
589	typedef struct RTACPIFIELDENTRY
590	{
591	/** The field name. */
592	const char *pszName;
593	/** Number of bits of the field. */
594	uint64_t cBits;
595	} RTACPIFIELDENTRY;
596	/** Pointer to a field entry. */
597	typedef RTACPIFIELDENTRY *PRTACPIFIELDENTRY;
598	/** Pointer to a const field entry. */
599	typedef const RTACPIFIELDENTRY *PCRTACPIFIELDENTRY;
600
601
602	/**
603	* Appends a new field descriptor to the given ACPI table.
604	*
605	* @returns IPRT status code.
606	* @param hAcpiTbl The ACPI table handle.
607	* @param pszNameRef The region/buffer the field describes.
608	* @param enmAcc The access type,
609	* @param fLock Flag whether access must happen under a lock.
610	* @param enmUpdate The update rule.
611	* @param paFields Pointer to the field descriptors.
612	* @param cFields Number of entries in the array.
613	*/
614	RTDECL(int) RTAcpiTblFieldAppend(RTACPITBL hAcpiTbl, const char *pszNameRef, RTACPIFIELDACC enmAcc,
615	bool fLock, RTACPIFIELDUPDATE enmUpdate, PCRTACPIFIELDENTRY paFields,
616	uint32_t cFields);
617
618
619
620	/** @name ACPI resource builder related API.
621	* @{ */
622
623	/**
624	* Creates a new empty resource template.
625	*
626	* @returns IPRT status code.
627	* @param phAcpiRes Where to store the handle to the ACPI resource on success.
628	*/
629	RTDECL(int) RTAcpiResourceCreate(PRTACPIRES phAcpiRes);
630
631
632	/**
633	* Destroys the given ACPI resource, freeing all allocated resources.
634	*
635	* @param hAcpiRes The ACPI resource handle to destroy.
636	*/
637	RTDECL(void) RTAcpiResourceDestroy(RTACPIRES hAcpiRes);
638
639
640	/**
641	* Resets the given ACPI resource handle to create a new empty template.
642	*
643	* @param hAcpiRes The ACPI resource handle.
644	*/
645	RTDECL(void) RTAcpiResourceReset(RTACPIRES hAcpiRes);
646
647
648	/**
649	* Seals the given ACPI resource against further changes and adds any
650	* missing data required to complete the resource buffer.
651	*
652	* @returns IPRT status code.
653	* @param hAcpiRes The ACPI resource handle.
654	*
655	* @note After a call to this method completed successfully it is not possible
656	* to add new resources until RTAcpiResourceReset() was called.
657	*/
658	RTDECL(int) RTAcpiResourceSeal(RTACPIRES hAcpiRes);
659
660
661	/**
662	* Queries the pointer to the buffer holding the encoded data.
663	*
664	* @returns IPRT status code.
665	* @param hAcpiRes The ACPI resource handle.
666	* @param ppvRes Where to store the pointer to the buffer holding the encoded resource template on success.
667	* @param pcbRes Where to store the size of the encoded data in bytes on success.
668	*
669	* @note The ACPI resource must be successfully sealed with RTAcpiResourceSeal() for this function to succeed.
670	* Also the buffer pointer will only be valid until a call to any other RTAcpiResource* method.
671	*/
672	RTDECL(int) RTAcpiResourceQueryBuffer(RTACPIRES hAcpiRes, const void *ppvRes, size_t pcbRes);
673
674
675	/**
676	* Adds a fixed memory range with the given start address and size to the given ACPI resource.
677	*
678	* @returns IPRT status code.
679	* @param hAcpiRes The ACPI resource handle.
680	* @param u32AddrBase The base address to encode.
681	* @param cbRange The range length in bytes to encode.
682	* @param fRw Flag whether this address range is read-write or read-only.
683	*/
684	RTDECL(int) RTAcpiResourceAdd32BitFixedMemoryRange(RTACPIRES hAcpiRes, uint32_t u32AddrBase, uint32_t cbRange,
685	bool fRw);
686
687
688	/**
689	* Adds an extended interrupt descriptor with the given configuration to the given ACPI resource.
690	*
691	* @returns IPRT status code.
692	* @param hAcpiRes The ACPI resource handle.
693	* @param fConsumer Flag whether the entity this resource is assigned to consumes the interrupt (true) or produces it (false).
694	* @param fEdgeTriggered Flag whether the interrupt is edged (true) or level (false) triggered.
695	* @param fActiveLow Flag whether the interrupt polarity is active low (true) or active high (false).
696	* @param fShared Flag whether the interrupt is shared between different entities (true) or exclusive to the assigned entity (false).
697	* @param fWakeCapable Flag whether the interrupt can wake the system (true) or not (false).
698	* @param cIntrs Number of interrupts following.
699	* @param pau32Intrs Pointer to the array of interrupt numbers.
700	*/
701	RTDECL(int) RTAcpiResourceAddExtendedInterrupt(RTACPIRES hAcpiRes, bool fConsumer, bool fEdgeTriggered, bool fActiveLow, bool fShared,
702	bool fWakeCapable, uint8_t cIntrs, uint32_t *pau32Intrs);
703
704
705	/** @name Generic address space flags.
706	* @{ */
707	#define RTACPI_RESOURCE_ADDR_RANGE_F_DECODE_TYPE_SUB RT_BIT_32(0)
708	#define RTACPI_RESOURCE_ADDR_RANGE_F_DECODE_TYPE_POS 0
709
710	#define RTACPI_RESOURCE_ADDR_RANGE_F_MIN_ADDR_FIXED RT_BIT_32(1)
711	#define RTACPI_RESOURCE_ADDR_RANGE_F_MIN_ADDR_CHANGEABLE 0
712
713	#define RTACPI_RESOURCE_ADDR_RANGE_F_MAX_ADDR_FIXED RT_BIT_32(2)
714	#define RTACPI_RESOURCE_ADDR_RANGE_F_MAX_ADDR_CHANGEABLE 0
715
716	#define RTACPI_RESOURCE_ADDR_RANGE_F_VALID_MASK UINT32_C(0x00000007)
717	/** @} */
718
719	/**
720	* Memory range cacheability
721	*/
722	typedef enum RTACPIRESMEMRANGECACHEABILITY
723	{
724	/** Usual invalid value. */
725	kAcpiResMemRangeCacheability_Invalid = 0,
726	/** Memory range is non cacheable (like MMIO, etc.). */
727	kAcpiResMemRangeCacheability_NonCacheable,
728	/** Memory is cacheable. */
729	kAcpiResMemRangeCacheability_Cacheable,
730	/** Memory is cacheable and supports write comining. */
731	kAcpiResMemRangeCacheability_CacheableWriteCombining,
732	/** Memory is cacheable and supports prefetching. */
733	kAcpiResMemRangeCacheability_CacheablePrefetchable,
734	/** 32-bit blow up hack. */
735	kAcpiResMemRangeCacheability_32BitHack = 0x7fffffff
736	} RTACPIRESMEMRANGECACHEABILITY;
737
738
739	/**
740	* Memory attribute.
741	*/
742	typedef enum RTACPIRESMEMRANGETYPE
743	{
744	/** Invalid memory range type. */
745	kAcpiResMemType_Invalid = 0,
746	/** Memory range is actual memory. */
747	kAcpiResMemType_Memory,
748	/** Memory range is reserved. */
749	kAcpiResMemType_Reserved,
750	/** Memory range is reserved to ACPI. */
751	kAcpiResMemType_Acpi,
752	/** Memory range is no volatile storage. */
753	kAcpiResMemType_Nvs,
754	/** 32-bit blow up hack. */
755	kAcpiResMemType_32BitHack = 0x7fffffff
756	} RTACPIRESMEMRANGETYPE;
757
758
759	/**
760	* Adds a quad word (64-bit) memory range to the given ACPI resource.
761	*
762	* @returns IPRT status code.
763	* @param hAcpiRes The ACPI resource handle.
764	* @param enmCacheability The cacheability of the memory range.
765	* @param enmType Memory range type.
766	* @param fRw Flag whether the memory range is read/write (true) or readonly (false).
767	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
768	* @param u64AddrMin The start address of the memory range.
769	* @param u64AddrMax Last valid address of the range.
770	* @param u64OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
771	* @param u64Granularity The access granularity of the range in bytes.
772	* @param u64Length Length of the memory range in bytes.
773	*/
774	RTDECL(int) RTAcpiResourceAddQWordMemoryRange(RTACPIRES hAcpiRes, RTACPIRESMEMRANGECACHEABILITY enmCacheability,
775	RTACPIRESMEMRANGETYPE enmType, bool fRw, uint32_t fAddrSpace,
776	uint64_t u64AddrMin, uint64_t u64AddrMax, uint64_t u64OffTrans,
777	uint64_t u64Granularity, uint64_t u64Length);
778
779
780	/**
781	* Adds a double word (32-bit) memory range to the given ACPI resource.
782	*
783	* @returns IPRT status code.
784	* @param hAcpiRes The ACPI resource handle.
785	* @param enmCacheability The cacheability of the memory range.
786	* @param enmType Memory range type.
787	* @param fRw Flag whether the memory range is read/write (true) or readonly (false).
788	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
789	* @param u32AddrMin The start address of the memory range.
790	* @param u32AddrMax Last valid address of the range.
791	* @param u32OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
792	* @param u32Granularity The access granularity of the range in bytes.
793	* @param u32Length Length of the memory range in bytes.
794	*/
795	RTDECL(int) RTAcpiResourceAddDWordMemoryRange(RTACPIRES hAcpiRes, RTACPIRESMEMRANGECACHEABILITY enmCacheability,
796	RTACPIRESMEMRANGETYPE enmType, bool fRw, uint32_t fAddrSpace,
797	uint32_t u32AddrMin, uint32_t u32AddrMax, uint32_t u32OffTrans,
798	uint32_t u32Granularity, uint32_t u32Length);
799
800
801	/**
802	* I/O range coverage.
803	*/
804	typedef enum RTACPIRESIORANGE
805	{
806	/** Invalid range. */
807	kAcpiResIoRange_Invalid = 0,
808	/** Range covers only non ISA I/O ports. */
809	kAcpiResIoRange_NonIsaOnly,
810	/** Range covers only ISA I/O ports. */
811	kAcpiResIoRange_IsaOnly,
812	/** Range covers the whole I/O port range. */
813	kAcpiResIoRange_Whole,
814	/** 32-bit blow up hack. */
815	kAcpiResIoRange_32BitHack = 0x7fffffff
816	} RTACPIRESIORANGE;
817
818
819	/**
820	* I/O range type.
821	*/
822	typedef enum RTACPIRESIORANGETYPE
823	{
824	/** Invalid value. */
825	kAcpiResIoRangeType_Invalid = 0,
826	/** Resource is I/O on the primary and secondary side of the bridge. */
827	kAcpiResIoRangeType_Static,
828	/** Resource is memory on the primary and I/O on the secondary side of the bridge,
829	* primary side memory address for a given I/O port is calculated with
830	* address = (((Port & 0xfffc) << 10) \|\| (Port & 0xfff)) + AddrMin. */
831	kAcpiResIoRangeType_Translation_Sparse,
832	/** Resource is memory on the primary and I/O on the secondary side of the bridge,
833	* primary side memory address for a given I/O port is calculated with
834	* address = AddrMin + Port. */
835	kAcpiResIoRangeType_Translation_Dense,
836	/** 32-bit blowup hack. */
837	kAcpiResIoRangeType_32BitHack = 0x7fffffff
838	} RTACPIRESIORANGETYPE;
839
840
841	/**
842	* Adds a quad word (64-bit) I/O range to the given ACPI resource.
843	*
844	* @returns IPRT status code.
845	* @param hAcpiRes The ACPI resource handle.
846	* @param enmIoType The I/O range type.
847	* @param enmIoRange The I/O range coverage.
848	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
849	* @param u64AddrMin The start address of the memory range.
850	* @param u64AddrMax Last valid address of the range.
851	* @param u64OffTrans Translation offset being applied to the address (for a PCIe bridge or IOMMU for example).
852	* @param u64Granularity The access granularity of the range in bytes.
853	* @param u64Length Length of the memory range in bytes.
854	*/
855	RTDECL(int) RTAcpiResourceAddQWordIoRange(RTACPIRES hAcpiRes, RTACPIRESIORANGETYPE enmIoType, RTACPIRESIORANGE enmIoRange,
856	uint32_t fAddrSpace, uint64_t u64AddrMin, uint64_t u64AddrMax, uint64_t u64OffTrans,
857	uint64_t u64Granularity, uint64_t u64Length);
858
859
860	/**
861	* Adds a word (16-bit) bus number to the given ACPI resource.
862	*
863	* @returns IPRT status code.
864	* @param hAcpiRes The ACPI resource handle.
865	* @param fAddrSpace Additional address space flags (combination of RTACPI_RESOURCE_ADDR_RANGE_F_XXX).
866	* @param u16BusMin Starting bus number.
867	* @param u16BusMax Last valid bus number.
868	* @param u16OffTrans Translation offset being applied to the bus number.
869	* @param u16Granularity The access granularity of the bus number.
870	* @param u16Length Length of the bus range.
871	*/
872	RTDECL(int) RTAcpiResourceAddWordBusNumber(RTACPIRES hAcpiRes, uint32_t fAddrSpace, uint16_t u16BusMin, uint16_t u16BusMax,
873	uint16_t u16OffTrans, uint16_t u16Granularity, uint16_t u16Length);
874
875	/** @} */
876
877	#endif /* IN_RING3 */
878
879	/** @} */
880
881	RT_C_DECLS_END
882
883	#endif /* !IPRT_INCLUDED_acpi_h */
884

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

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

Download in other formats: