2 Header file for ACPI parser
4 Copyright (c) 2016 - 2019, ARM Limited. All rights reserved.
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
17 #define OUTPUT_FIELD_COLUMN_WIDTH 36
19 /// The RSDP table signature is "RSD PTR " (8 bytes)
20 /// However The signature for ACPI tables is 4 bytes.
21 /// To work around this oddity define a signature type
22 /// that allows us to process the log options.
23 #define RSDP_TABLE_INFO SIGNATURE_32('R', 'S', 'D', 'P')
26 This function increments the ACPI table error counter.
35 This function increments the ACPI table warning counter.
39 IncrementWarningCount (
44 This function verifies the ACPI table checksum.
46 This function verifies the checksum for the ACPI table and optionally
49 @param [in] Log If TRUE log the status of the checksum.
50 @param [in] Ptr Pointer to the start of the table buffer.
51 @param [in] Length The length of the buffer.
53 @retval TRUE The checksum is OK.
54 @retval FALSE The checksum failed.
65 This function performs a raw data dump of the ACPI table.
67 @param [in] Ptr Pointer to the start of the table buffer.
68 @param [in] Length The length of the buffer.
78 This function traces 1 byte of datum as specified in the format string.
80 @param [in] Format The format string for tracing the data.
81 @param [in] Ptr Pointer to the start of the buffer.
86 IN CONST CHAR16
* Format
,
91 This function traces 2 bytes of data as specified in the format string.
93 @param [in] Format The format string for tracing the data.
94 @param [in] Ptr Pointer to the start of the buffer.
99 IN CONST CHAR16
* Format
,
104 This function traces 4 bytes of data as specified in the format string.
106 @param [in] Format The format string for tracing the data.
107 @param [in] Ptr Pointer to the start of the buffer.
112 IN CONST CHAR16
* Format
,
117 This function traces 8 bytes of data as specified by the format string.
119 @param [in] Format The format string for tracing the data.
120 @param [in] Ptr Pointer to the start of the buffer.
125 IN CONST CHAR16
* Format
,
130 This function traces 3 characters which can be optionally
131 formated using the format string if specified.
133 If no format string is specified the Format must be NULL.
135 @param [in] Format Optional format string for tracing the data.
136 @param [in] Ptr Pointer to the start of the buffer.
141 IN CONST CHAR16
* Format OPTIONAL
,
146 This function traces 4 characters which can be optionally
147 formated using the format string if specified.
149 If no format string is specified the Format must be NULL.
151 @param [in] Format Optional format string for tracing the data.
152 @param [in] Ptr Pointer to the start of the buffer.
157 IN CONST CHAR16
* Format OPTIONAL
,
162 This function traces 6 characters which can be optionally
163 formated using the format string if specified.
165 If no format string is specified the Format must be NULL.
167 @param [in] Format Optional format string for tracing the data.
168 @param [in] Ptr Pointer to the start of the buffer.
173 IN CONST CHAR16
* Format OPTIONAL
,
178 This function traces 8 characters which can be optionally
179 formated using the format string if specified.
181 If no format string is specified the Format must be NULL.
183 @param [in] Format Optional format string for tracing the data.
184 @param [in] Ptr Pointer to the start of the buffer.
189 IN CONST CHAR16
* Format OPTIONAL
,
194 This function indents and prints the ACPI table Field Name.
196 @param [in] Indent Number of spaces to add to the global table
197 indent. The global table indent is 0 by default;
198 however this value is updated on entry to the
199 ParseAcpi() by adding the indent value provided to
200 ParseAcpi() and restored back on exit. Therefore
201 the total indent in the output is dependent on from
202 where this function is called.
203 @param [in] FieldName Pointer to the Field Name.
209 IN CONST CHAR16
* FieldName
213 This function pointer is the template for customizing the trace output
215 @param [in] Format Format string for tracing the data as specified by
216 the 'Format' member of ACPI_PARSER.
217 @param [in] Ptr Pointer to the start of the buffer.
219 typedef VOID (EFIAPI
*FNPTR_PRINT_FORMATTER
)(CONST CHAR16
* Format
, UINT8
* Ptr
);
222 This function pointer is the template for validating an ACPI table field.
224 @param [in] Ptr Pointer to the start of the field data.
225 @param [in] Context Pointer to context specific information as specified by
226 the 'Context' member of the ACPI_PARSER.
227 e.g. this could be a pointer to the ACPI table header.
229 typedef VOID (EFIAPI
*FNPTR_FIELD_VALIDATOR
)(UINT8
* Ptr
, VOID
* Context
);
232 The ACPI_PARSER structure describes the fields of an ACPI table and
233 provides means for the parser to interpret and trace appropriately.
235 The first three members are populated based on information present in
236 in the ACPI table specifications. The remaining members describe how
237 the parser should report the field information, validate the field data
238 and/or update an external pointer to the field (ItemPtr).
240 ParseAcpi() uses the format string specified by 'Format' for tracing
241 the field data. If the field is more complex and requires additional
242 processing for formatting and representation a print formatter function
243 can be specified in 'PrintFormatter'.
244 The PrintFormatter function may choose to use the format string
245 specified by 'Format' or use its own internal format string.
247 The 'Format' and 'PrintFormatter' members allow flexibility for
248 representing the field data.
250 typedef struct AcpiParser
{
252 /// String describing the ACPI table field
253 /// (Field column from ACPI table spec)
254 CONST CHAR16
* NameStr
;
256 /// The length of the field.
257 /// (Byte Length column from ACPI table spec)
260 /// The offset of the field from the start of the table.
261 /// (Byte Offset column from ACPI table spec)
264 /// Optional Print() style format string for tracing the data. If not
265 /// used this must be set to NULL.
266 CONST CHAR16
* Format
;
268 /// Optional pointer to a print formatter function which
269 /// is typically used to trace complex field information.
270 /// If not used this must be set to NULL.
271 /// The Format string is passed to the PrintFormatter function
272 /// but may be ignored by the implementation code.
273 FNPTR_PRINT_FORMATTER PrintFormatter
;
275 /// Optional pointer which may be set to request the parser to update
276 /// a pointer to the field data. If unused this must be set to NULL.
279 /// Optional pointer to a field validator function.
280 /// The function should directly report any appropriate error or warning
281 /// and invoke the appropriate counter update function.
282 /// If not used this parameter must be set to NULL.
283 FNPTR_FIELD_VALIDATOR FieldValidator
;
285 /// Optional pointer to context specific information,
286 /// which the Field Validator function can use to determine
287 /// additional information about the ACPI table and make
288 /// decisions about the field being validated.
289 /// e.g. this could be a pointer to the ACPI table header
294 A structure used to store the pointers to the members of the
295 ACPI description header structure that was parsed.
297 typedef struct AcpiDescriptionHeaderInfo
{
298 /// ACPI table signature
300 /// Length of the ACPI table
306 /// OEM Id - length is 6 bytes
315 UINT32
* CreatorRevision
;
316 } ACPI_DESCRIPTION_HEADER_INFO
;
319 This function is used to parse an ACPI table buffer.
321 The ACPI table buffer is parsed using the ACPI table parser information
322 specified by a pointer to an array of ACPI_PARSER elements. This parser
323 function iterates through each item on the ACPI_PARSER array and logs the
326 This function can optionally be used to parse ACPI tables and fetch specific
327 field values. The ItemPtr member of the ACPI_PARSER structure (where used)
328 is updated by this parser function to point to the selected field data
329 (e.g. useful for variable length nested fields).
331 @param [in] Trace Trace the ACPI fields TRUE else only parse the
333 @param [in] Indent Number of spaces to indent the output.
334 @param [in] AsciiName Optional pointer to an ASCII string that describes
335 the table being parsed.
336 @param [in] Ptr Pointer to the start of the buffer.
337 @param [in] Length Length of the buffer pointed by Ptr.
338 @param [in] Parser Pointer to an array of ACPI_PARSER structure that
339 describes the table being parsed.
340 @param [in] ParserItems Number of items in the ACPI_PARSER array.
342 @retval Number of bytes parsed.
349 IN CONST CHAR8
* AsciiName OPTIONAL
,
352 IN CONST ACPI_PARSER
* Parser
,
353 IN UINT32 ParserItems
357 This is a helper macro to pass parameters to the Parser functions.
359 @param [in] Parser The name of the ACPI_PARSER array describing the
362 #define PARSER_PARAMS(Parser) Parser, sizeof (Parser) / sizeof (Parser[0])
365 This is a helper macro for describing the ACPI header fields.
367 @param [out] Info Pointer to retrieve the ACPI table header information.
369 #define PARSE_ACPI_HEADER(Info) \
370 { L"Signature", 4, 0, NULL, Dump4Chars, \
371 (VOID**)&(Info)->Signature , NULL, NULL }, \
372 { L"Length", 4, 4, L"%d", NULL, \
373 (VOID**)&(Info)->Length, NULL, NULL }, \
374 { L"Revision", 1, 8, L"%d", NULL, \
375 (VOID**)&(Info)->Revision, NULL, NULL }, \
376 { L"Checksum", 1, 9, L"0x%X", NULL, \
377 (VOID**)&(Info)->Checksum, NULL, NULL }, \
378 { L"Oem ID", 6, 10, NULL, Dump6Chars, \
379 (VOID**)&(Info)->OemId, NULL, NULL }, \
380 { L"Oem Table ID", 8, 16, NULL, Dump8Chars, \
381 (VOID**)&(Info)->OemTableId, NULL, NULL }, \
382 { L"Oem Revision", 4, 24, L"0x%X", NULL, \
383 (VOID**)&(Info)->OemRevision, NULL, NULL }, \
384 { L"Creator ID", 4, 28, NULL, Dump4Chars, \
385 (VOID**)&(Info)->CreatorId, NULL, NULL }, \
386 { L"Creator Revision", 4, 32, L"0x%X", NULL, \
387 (VOID**)&(Info)->CreatorRevision, NULL, NULL }
390 Length of the ACPI GAS structure.
392 NOTE: This might normally be defined as
393 sizeof (EFI_ACPI_6_2_GENERIC_ADDRESS_STRUCTURE).
394 However, we deliberately minimise any reference to the EDK2 ACPI
395 headers in an attempt to provide cross checking.
397 #define GAS_LENGTH 12
400 Length of the ACPI Header structure.
402 NOTE: This might normally be defined as
403 sizeof (EFI_ACPI_DESCRIPTION_HEADER).
404 However, we deliberately minimise any reference to the EDK2 ACPI
405 headers in an attempt to provide cross checking.
407 #define ACPI_DESCRIPTION_HEADER_LENGTH 36
410 This function indents and traces the GAS structure as described by the GasParser.
412 @param [in] Ptr Pointer to the start of the buffer.
413 @param [in] Indent Number of spaces to indent the output.
423 This function traces the GAS structure as described by the GasParser.
425 @param [in] Format Optional format string for tracing the data.
426 @param [in] Ptr Pointer to the start of the buffer.
431 IN CONST CHAR16
* Format OPTIONAL
,
436 This function traces the ACPI header as described by the AcpiHeaderParser.
438 @param [in] Ptr Pointer to the start of the buffer.
440 @retval Number of bytes parsed.
449 This function parses the ACPI header as described by the AcpiHeaderParser.
451 This function optionally returns the Signature, Length and revision of the
454 @param [in] Ptr Pointer to the start of the buffer.
455 @param [out] Signature Gets location of the ACPI table signature.
456 @param [out] Length Gets location of the length of the ACPI table.
457 @param [out] Revision Gets location of the revision of the ACPI table.
459 @retval Number of bytes parsed.
465 OUT CONST UINT32
** Signature
,
466 OUT CONST UINT32
** Length
,
467 OUT CONST UINT8
** Revision
471 This function parses the ACPI BGRT table.
472 When trace is enabled this function parses the BGRT table and
473 traces the ACPI table fields.
475 This function also performs validation of the ACPI table fields.
477 @param [in] Trace If TRUE, trace the ACPI fields.
478 @param [in] Ptr Pointer to the start of the buffer.
479 @param [in] AcpiTableLength Length of the ACPI table.
480 @param [in] AcpiTableRevision Revision of the ACPI table.
487 IN UINT32 AcpiTableLength
,
488 IN UINT8 AcpiTableRevision
492 This function parses the ACPI DBG2 table.
493 When trace is enabled this function parses the DBG2 table and
494 traces the ACPI table fields.
496 This function also performs validation of the ACPI table fields.
498 @param [in] Trace If TRUE, trace the ACPI fields.
499 @param [in] Ptr Pointer to the start of the buffer.
500 @param [in] AcpiTableLength Length of the ACPI table.
501 @param [in] AcpiTableRevision Revision of the ACPI table.
508 IN UINT32 AcpiTableLength
,
509 IN UINT8 AcpiTableRevision
513 This function parses the ACPI DSDT table.
514 When trace is enabled this function parses the DSDT table and
515 traces the ACPI table fields.
516 For the DSDT table only the ACPI header fields are parsed and
519 @param [in] Trace If TRUE, trace the ACPI fields.
520 @param [in] Ptr Pointer to the start of the buffer.
521 @param [in] AcpiTableLength Length of the ACPI table.
522 @param [in] AcpiTableRevision Revision of the ACPI table.
529 IN UINT32 AcpiTableLength
,
530 IN UINT8 AcpiTableRevision
534 This function parses the ACPI FADT table.
535 This function parses the FADT table and optionally traces the ACPI
538 This function also performs validation of the ACPI table fields.
540 @param [in] Trace If TRUE, trace the ACPI fields.
541 @param [in] Ptr Pointer to the start of the buffer.
542 @param [in] AcpiTableLength Length of the ACPI table.
543 @param [in] AcpiTableRevision Revision of the ACPI table.
550 IN UINT32 AcpiTableLength
,
551 IN UINT8 AcpiTableRevision
555 This function parses the ACPI GTDT table.
556 When trace is enabled this function parses the GTDT table and
557 traces the ACPI table fields.
559 This function also parses the following platform timer structures:
563 This function also performs validation of the ACPI table fields.
565 @param [in] Trace If TRUE, trace the ACPI fields.
566 @param [in] Ptr Pointer to the start of the buffer.
567 @param [in] AcpiTableLength Length of the ACPI table.
568 @param [in] AcpiTableRevision Revision of the ACPI table.
575 IN UINT32 AcpiTableLength
,
576 IN UINT8 AcpiTableRevision
580 This function parses the ACPI IORT table.
581 When trace is enabled this function parses the IORT table and
582 traces the ACPI fields.
584 This function also parses the following nodes:
592 This function also performs validation of the ACPI table fields.
594 @param [in] Trace If TRUE, trace the ACPI fields.
595 @param [in] Ptr Pointer to the start of the buffer.
596 @param [in] AcpiTableLength Length of the ACPI table.
597 @param [in] AcpiTableRevision Revision of the ACPI table.
604 IN UINT32 AcpiTableLength
,
605 IN UINT8 AcpiTableRevision
609 This function parses the ACPI MADT table.
610 When trace is enabled this function parses the MADT table and
611 traces the ACPI table fields.
613 This function currently parses the following Interrupt Controller
621 This function also performs validation of the ACPI table fields.
623 @param [in] Trace If TRUE, trace the ACPI fields.
624 @param [in] Ptr Pointer to the start of the buffer.
625 @param [in] AcpiTableLength Length of the ACPI table.
626 @param [in] AcpiTableRevision Revision of the ACPI table.
633 IN UINT32 AcpiTableLength
,
634 IN UINT8 AcpiTableRevision
638 This function parses the ACPI MCFG table.
639 When trace is enabled this function parses the MCFG table and
640 traces the ACPI table fields.
642 This function also performs validation of the ACPI table fields.
644 @param [in] Trace If TRUE, trace the ACPI fields.
645 @param [in] Ptr Pointer to the start of the buffer.
646 @param [in] AcpiTableLength Length of the ACPI table.
647 @param [in] AcpiTableRevision Revision of the ACPI table.
654 IN UINT32 AcpiTableLength
,
655 IN UINT8 AcpiTableRevision
659 This function parses the ACPI PPTT table.
660 When trace is enabled this function parses the PPTT table and
661 traces the ACPI table fields.
663 This function also performs validation of the ACPI table fields.
665 @param [in] Trace If TRUE, trace the ACPI fields.
666 @param [in] Ptr Pointer to the start of the buffer.
667 @param [in] AcpiTableLength Length of the ACPI table.
668 @param [in] AcpiTableRevision Revision of the ACPI table.
675 IN UINT32 AcpiTableLength
,
676 IN UINT8 AcpiTableRevision
680 This function parses the ACPI RSDP table.
682 This function invokes the parser for the XSDT table.
683 * Note - This function does not support parsing of RSDT table.
685 This function also performs a RAW dump of the ACPI table and
686 validates the checksum.
688 @param [in] Trace If TRUE, trace the ACPI fields.
689 @param [in] Ptr Pointer to the start of the buffer.
690 @param [in] AcpiTableLength Length of the ACPI table.
691 @param [in] AcpiTableRevision Revision of the ACPI table.
698 IN UINT32 AcpiTableLength
,
699 IN UINT8 AcpiTableRevision
703 This function parses the ACPI SLIT table.
704 When trace is enabled this function parses the SLIT table and
705 traces the ACPI table fields.
707 This function also validates System Localities for the following:
708 - Diagonal elements have a normalized value of 10
709 - Relative distance from System Locality at i*N+j is same as
712 @param [in] Trace If TRUE, trace the ACPI fields.
713 @param [in] Ptr Pointer to the start of the buffer.
714 @param [in] AcpiTableLength Length of the ACPI table.
715 @param [in] AcpiTableRevision Revision of the ACPI table.
722 IN UINT32 AcpiTableLength
,
723 IN UINT8 AcpiTableRevision
727 This function parses the ACPI SPCR table.
728 When trace is enabled this function parses the SPCR table and
729 traces the ACPI table fields.
731 This function also performs validations of the ACPI table fields.
733 @param [in] Trace If TRUE, trace the ACPI fields.
734 @param [in] Ptr Pointer to the start of the buffer.
735 @param [in] AcpiTableLength Length of the ACPI table.
736 @param [in] AcpiTableRevision Revision of the ACPI table.
743 IN UINT32 AcpiTableLength
,
744 IN UINT8 AcpiTableRevision
748 This function parses the ACPI SRAT table.
749 When trace is enabled this function parses the SRAT table and
750 traces the ACPI table fields.
752 This function parses the following Resource Allocation Structures:
753 - Processor Local APIC/SAPIC Affinity Structure
754 - Memory Affinity Structure
755 - Processor Local x2APIC Affinity Structure
756 - GICC Affinity Structure
758 This function also performs validation of the ACPI table fields.
760 @param [in] Trace If TRUE, trace the ACPI fields.
761 @param [in] Ptr Pointer to the start of the buffer.
762 @param [in] AcpiTableLength Length of the ACPI table.
763 @param [in] AcpiTableRevision Revision of the ACPI table.
770 IN UINT32 AcpiTableLength
,
771 IN UINT8 AcpiTableRevision
775 This function parses the ACPI SSDT table.
776 When trace is enabled this function parses the SSDT table and
777 traces the ACPI table fields.
778 For the SSDT table only the ACPI header fields are
781 @param [in] Trace If TRUE, trace the ACPI fields.
782 @param [in] Ptr Pointer to the start of the buffer.
783 @param [in] AcpiTableLength Length of the ACPI table.
784 @param [in] AcpiTableRevision Revision of the ACPI table.
791 IN UINT32 AcpiTableLength
,
792 IN UINT8 AcpiTableRevision
796 This function parses the ACPI XSDT table
797 and optionally traces the ACPI table fields.
799 This function also performs validation of the XSDT table.
801 @param [in] Trace If TRUE, trace the ACPI fields.
802 @param [in] Ptr Pointer to the start of the buffer.
803 @param [in] AcpiTableLength Length of the ACPI table.
804 @param [in] AcpiTableRevision Revision of the ACPI table.
811 IN UINT32 AcpiTableLength
,
812 IN UINT8 AcpiTableRevision
815 #endif // ACPIPARSER_H_