2 Header file for ACPI parser
4 Copyright (c) 2016 - 2018, 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')
25 /** This function increments the ACPI table error counter.
33 /** This function increments the ACPI table warning counter.
37 IncrementWarningCount (
41 /** This function verifies the ACPI table checksum.
43 This function verifies the checksum for the ACPI table and optionally
46 @param [in] Log If TRUE log the status of the checksum.
47 @param [in] Ptr Pointer to the start of the table buffer.
48 @param [in] Length The length of the buffer.
50 @retval TRUE The checksum is OK.
51 @retval FALSE The checksum failed.
61 /** This function performs a raw data dump of the ACPI table.
63 @param [in] Ptr Pointer to the start of the table buffer.
64 @param [in] Length The length of the buffer.
73 /** This function traces 1 byte of datum as specified in the
76 @param [in] Format The format string for tracing the data.
77 @param [in] Ptr Pointer to the start of the buffer.
82 IN CONST CHAR16
* Format
,
86 /** This function traces 2 bytes of data as specified in the
89 @param [in] Format The format string for tracing the data.
90 @param [in] Ptr Pointer to the start of the buffer.
95 IN CONST CHAR16
* Format
,
99 /** This function traces 4 bytes of data as specified in the
102 @param [in] Format The format string for tracing the data.
103 @param [in] Ptr Pointer to the start of the buffer.
108 IN CONST CHAR16
* Format
,
112 /** This function traces 8 bytes of data as specified by the
115 @param [in] Format The format string for tracing the data.
116 @param [in] Ptr Pointer to the start of the buffer.
121 IN CONST CHAR16
* Format
,
125 /** This function traces 3 characters which can be optionally
126 formated using the format string if specified.
128 If no format string is specified the Format must be NULL.
130 @param [in] Format Optional format string for tracing the data.
131 @param [in] Ptr Pointer to the start of the buffer.
136 IN CONST CHAR16
* Format OPTIONAL
,
140 /** This function traces 4 characters which can be optionally
141 formated using the format string if specified.
143 If no format string is specified the Format must be NULL.
145 @param [in] Format Optional format string for tracing the data.
146 @param [in] Ptr Pointer to the start of the buffer.
151 IN CONST CHAR16
* Format OPTIONAL
,
155 /** This function traces 6 characters which can be optionally
156 formated using the format string if specified.
158 If no format string is specified the Format must be NULL.
160 @param [in] Format Optional format string for tracing the data.
161 @param [in] Ptr Pointer to the start of the buffer.
166 IN CONST CHAR16
* Format OPTIONAL
,
170 /** This function traces 8 characters which can be optionally
171 formated using the format string if specified.
173 If no format string is specified the Format must be NULL.
175 @param [in] Format Optional format string for tracing the data.
176 @param [in] Ptr Pointer to the start of the buffer.
181 IN CONST CHAR16
* Format OPTIONAL
,
185 /** This function indents and prints the ACPI table Field Name.
187 @param [in] Indent Number of spaces to add to the global table
188 indent. The global table indent is 0 by default;
189 however this value is updated on entry to the
190 ParseAcpi() by adding the indent value provided to
191 ParseAcpi() and restored back on exit. Therefore
192 the total indent in the output is dependent on from
193 where this function is called.
194 @param [in] FieldName Pointer to the Field Name.
200 IN CONST CHAR16
* FieldName
203 /** This function pointer is the template for customizing the trace output
205 @param [in] Format Format string for tracing the data as specified by
206 the 'Format' member of ACPI_PARSER.
207 @param [in] Ptr Pointer to the start of the buffer.
209 typedef VOID (EFIAPI
*FNPTR_PRINT_FORMATTER
)(CONST CHAR16
* Format
, UINT8
* Ptr
);
211 /** This function pointer is the template for validating an ACPI table field.
213 @param [in] Ptr Pointer to the start of the field data.
214 @param [in] Context Pointer to context specific information as specified by
215 the 'Context' member of the ACPI_PARSER.
216 e.g. this could be a pointer to the ACPI table header.
218 typedef VOID (EFIAPI
*FNPTR_FIELD_VALIDATOR
)(UINT8
* Ptr
, VOID
* Context
);
220 /** The ACPI_PARSER structure describes the fields of an ACPI table and
221 provides means for the parser to interpret and trace appropriately.
223 The first three members are populated based on information present in
224 in the ACPI table specifications. The remaining members describe how
225 the parser should report the field information, validate the field data
226 and/or update an external pointer to the field (ItemPtr).
228 ParseAcpi() uses the format string specified by 'Format' for tracing
229 the field data. If the field is more complex and requires additional
230 processing for formatting and representation a print formatter function
231 can be specified in 'PrintFormatter'.
232 The PrintFormatter function may choose to use the format string
233 specified by 'Format' or use its own internal format string.
235 The 'Format' and 'PrintFormatter' members allow flexibility for
236 representing the field data.
238 typedef struct AcpiParser
{
240 /// String describing the ACPI table field
241 /// (Field column from ACPI table spec)
242 CONST CHAR16
* NameStr
;
244 /// The length of the field.
245 /// (Byte Length column from ACPI table spec)
248 /// The offset of the field from the start of the table.
249 /// (Byte Offset column from ACPI table spec)
252 /// Optional Print() style format string for tracing the data. If not
253 /// used this must be set to NULL.
254 CONST CHAR16
* Format
;
256 /// Optional pointer to a print formatter function which
257 /// is typically used to trace complex field information.
258 /// If not used this must be set to NULL.
259 /// The Format string is passed to the PrintFormatter function
260 /// but may be ignored by the implementation code.
261 FNPTR_PRINT_FORMATTER PrintFormatter
;
263 /// Optional pointer which may be set to request the parser to update
264 /// a pointer to the field data. If unused this must be set to NULL.
267 /// Optional pointer to a field validator function.
268 /// The function should directly report any appropriate error or warning
269 /// and invoke the appropriate counter update function.
270 /// If not used this parameter must be set to NULL.
271 FNPTR_FIELD_VALIDATOR FieldValidator
;
273 /// Optional pointer to context specific information,
274 /// which the Field Validator function can use to determine
275 /// additional information about the ACPI table and make
276 /// decisions about the field being validated.
277 /// e.g. this could be a pointer to the ACPI table header
281 /** A structure used to store the pointers to the members of the
282 ACPI description header structure that was parsed.
284 typedef struct AcpiDescriptionHeaderInfo
{
285 /// ACPI table signature
287 /// Length of the ACPI table
293 /// OEM Id - length is 6 bytes
302 UINT32
* CreatorRevision
;
303 } ACPI_DESCRIPTION_HEADER_INFO
;
305 /** This function is used to parse an ACPI table buffer.
307 The ACPI table buffer is parsed using the ACPI table parser information
308 specified by a pointer to an array of ACPI_PARSER elements. This parser
309 function iterates through each item on the ACPI_PARSER array and logs the
312 This function can optionally be used to parse ACPI tables and fetch specific
313 field values. The ItemPtr member of the ACPI_PARSER structure (where used)
314 is updated by this parser function to point to the selected field data
315 (e.g. useful for variable length nested fields).
317 @param [in] Trace Trace the ACPI fields TRUE else only parse the
319 @param [in] Indent Number of spaces to indent the output.
320 @param [in] AsciiName Optional pointer to an ASCII string that describes
321 the table being parsed.
322 @param [in] Ptr Pointer to the start of the buffer.
323 @param [in] Length Length of the buffer pointed by Ptr.
324 @param [in] Parser Pointer to an array of ACPI_PARSER structure that
325 describes the table being parsed.
326 @param [in] ParserItems Number of items in the ACPI_PARSER array.
328 @retval Number of bytes parsed.
335 IN CONST CHAR8
* AsciiName OPTIONAL
,
338 IN CONST ACPI_PARSER
* Parser
,
339 IN UINT32 ParserItems
342 /** This is a helper macro to pass parameters to the Parser functions.
344 @param [in] Parser The name of the ACPI_PARSER array describing the
347 #define PARSER_PARAMS(Parser) Parser, sizeof (Parser) / sizeof (Parser[0])
349 /** This is a helper macro for describing the ACPI header fields.
351 @param [out] Info Pointer to retrieve the ACPI table header information.
353 #define PARSE_ACPI_HEADER(Info) \
354 { L"Signature", 4, 0, NULL, Dump4Chars, \
355 (VOID**)&(Info)->Signature , NULL, NULL }, \
356 { L"Length", 4, 4, L"%d", NULL, \
357 (VOID**)&(Info)->Length, NULL, NULL }, \
358 { L"Revision", 1, 8, L"%d", NULL, \
359 (VOID**)&(Info)->Revision, NULL, NULL }, \
360 { L"Checksum", 1, 9, L"0x%X", NULL, \
361 (VOID**)&(Info)->Checksum, NULL, NULL }, \
362 { L"Oem ID", 6, 10, NULL, Dump6Chars, \
363 (VOID**)&(Info)->OemId, NULL, NULL }, \
364 { L"Oem Table ID", 8, 16, NULL, Dump8Chars, \
365 (VOID**)&(Info)->OemTableId, NULL, NULL }, \
366 { L"Oem Revision", 4, 24, L"0x%X", NULL, \
367 (VOID**)&(Info)->OemRevision, NULL, NULL }, \
368 { L"Creator ID", 4, 28, NULL, Dump4Chars, \
369 (VOID**)&(Info)->CreatorId, NULL, NULL }, \
370 { L"Creator Revision", 4, 32, L"0x%X", NULL, \
371 (VOID**)&(Info)->CreatorRevision, NULL, NULL }
373 /** Length of the ACPI GAS structure.
375 NOTE: This might normally be defined as
376 sizeof (EFI_ACPI_6_2_GENERIC_ADDRESS_STRUCTURE).
377 However, we deliberately minimise any reference to the EDK2 ACPI
378 headers in an attempt to provide cross checking.
380 #define GAS_LENGTH 12
382 /** Length of the ACPI Header structure.
384 NOTE: This might normally be defined as
385 sizeof (EFI_ACPI_DESCRIPTION_HEADER).
386 However, we deliberately minimise any reference to the EDK2 ACPI
387 headers in an attempt to provide cross checking.
389 #define ACPI_DESCRIPTION_HEADER_LENGTH 36
391 /** This function indents and traces the GAS structure as described
394 @param [in] Ptr Pointer to the start of the buffer.
395 @param [in] Indent Number of spaces to indent the output.
404 /** This function traces the GAS structure as described by the GasParser.
406 @param [in] Format Optional format string for tracing the data.
407 @param [in] Ptr Pointer to the start of the buffer.
412 IN CONST CHAR16
* Format OPTIONAL
,
416 /** This function traces the ACPI header as described by the AcpiHeaderParser.
418 @param [in] Ptr Pointer to the start of the buffer.
420 @retval Number of bytes parsed.
428 /** This function parses the ACPI header as described by the AcpiHeaderParser.
430 This function optionally returns the Signature, Length and revision of the
433 @param [in] Ptr Pointer to the start of the buffer.
434 @param [out] Signature Gets location of the ACPI table signature.
435 @param [out] Length Gets location of the length of the ACPI table.
436 @param [out] Revision Gets location of the revision of the ACPI table.
438 @retval Number of bytes parsed.
444 OUT CONST UINT32
** Signature
,
445 OUT CONST UINT32
** Length
,
446 OUT CONST UINT8
** Revision
449 /** This function parses the ACPI BGRT table.
450 When trace is enabled this function parses the BGRT table and
451 traces the ACPI table fields.
453 This function also performs validation of the ACPI table fields.
455 @param [in] Trace If TRUE, trace the ACPI fields.
456 @param [in] Ptr Pointer to the start of the buffer.
457 @param [in] AcpiTableLength Length of the ACPI table.
458 @param [in] AcpiTableRevision Revision of the ACPI table.
465 IN UINT32 AcpiTableLength
,
466 IN UINT8 AcpiTableRevision
469 /** This function parses the ACPI DBG2 table.
470 When trace is enabled this function parses the DBG2 table and
471 traces the ACPI table fields.
473 This function also performs validation of the ACPI table fields.
475 @param [in] Trace If TRUE, trace the ACPI fields.
476 @param [in] Ptr Pointer to the start of the buffer.
477 @param [in] AcpiTableLength Length of the ACPI table.
478 @param [in] AcpiTableRevision Revision of the ACPI table.
485 IN UINT32 AcpiTableLength
,
486 IN UINT8 AcpiTableRevision
489 /** This function parses the ACPI DSDT table.
490 When trace is enabled this function parses the DSDT table and
491 traces the ACPI table fields.
492 For the DSDT table only the ACPI header fields are parsed and
495 @param [in] Trace If TRUE, trace the ACPI fields.
496 @param [in] Ptr Pointer to the start of the buffer.
497 @param [in] AcpiTableLength Length of the ACPI table.
498 @param [in] AcpiTableRevision Revision of the ACPI table.
505 IN UINT32 AcpiTableLength
,
506 IN UINT8 AcpiTableRevision
509 /** This function parses the ACPI FADT table.
510 This function parses the FADT table and optionally traces the ACPI
513 This function also performs validation of the ACPI table fields.
515 @param [in] Trace If TRUE, trace the ACPI fields.
516 @param [in] Ptr Pointer to the start of the buffer.
517 @param [in] AcpiTableLength Length of the ACPI table.
518 @param [in] AcpiTableRevision Revision of the ACPI table.
525 IN UINT32 AcpiTableLength
,
526 IN UINT8 AcpiTableRevision
529 /** This function parses the ACPI GTDT table.
530 When trace is enabled this function parses the GTDT table and
531 traces the ACPI table fields.
533 This function also parses the following platform timer structures:
537 This function also performs validation of the ACPI table fields.
539 @param [in] Trace If TRUE, trace the ACPI fields.
540 @param [in] Ptr Pointer to the start of the buffer.
541 @param [in] AcpiTableLength Length of the ACPI table.
542 @param [in] AcpiTableRevision Revision of the ACPI table.
549 IN UINT32 AcpiTableLength
,
550 IN UINT8 AcpiTableRevision
553 /** This function parses the ACPI IORT table.
554 When trace is enabled this function parses the IORT table and
555 traces the ACPI fields.
557 This function also parses the following nodes:
565 This function also performs validation of the ACPI table fields.
567 @param [in] Trace If TRUE, trace the ACPI fields.
568 @param [in] Ptr Pointer to the start of the buffer.
569 @param [in] AcpiTableLength Length of the ACPI table.
570 @param [in] AcpiTableRevision Revision of the ACPI table.
577 IN UINT32 AcpiTableLength
,
578 IN UINT8 AcpiTableRevision
581 /** This function parses the ACPI MADT table.
582 When trace is enabled this function parses the MADT table and
583 traces the ACPI table fields.
585 This function currently parses the following Interrupt Controller
593 This function also performs validation of the ACPI table fields.
595 @param [in] Trace If TRUE, trace the ACPI fields.
596 @param [in] Ptr Pointer to the start of the buffer.
597 @param [in] AcpiTableLength Length of the ACPI table.
598 @param [in] AcpiTableRevision Revision of the ACPI table.
605 IN UINT32 AcpiTableLength
,
606 IN UINT8 AcpiTableRevision
609 /** This function parses the ACPI MCFG table.
610 When trace is enabled this function parses the MCFG table and
611 traces the ACPI table fields.
613 This function also performs validation of the ACPI table fields.
615 @param [in] Trace If TRUE, trace the ACPI fields.
616 @param [in] Ptr Pointer to the start of the buffer.
617 @param [in] AcpiTableLength Length of the ACPI table.
618 @param [in] AcpiTableRevision Revision of the ACPI table.
625 IN UINT32 AcpiTableLength
,
626 IN UINT8 AcpiTableRevision
629 /** This function parses the ACPI RSDP table.
631 This function invokes the parser for the XSDT table.
632 * Note - This function does not support parsing of RSDT table.
634 This function also performs a RAW dump of the ACPI table and
635 validates the checksum.
637 @param [in] Trace If TRUE, trace the ACPI fields.
638 @param [in] Ptr Pointer to the start of the buffer.
639 @param [in] AcpiTableLength Length of the ACPI table.
640 @param [in] AcpiTableRevision Revision of the ACPI table.
647 IN UINT32 AcpiTableLength
,
648 IN UINT8 AcpiTableRevision
651 /** This function parses the ACPI SLIT table.
652 When trace is enabled this function parses the SLIT table and
653 traces the ACPI table fields.
655 This function also validates System Localities for the following:
656 - Diagonal elements have a normalized value of 10
657 - Relative distance from System Locality at i*N+j is same as
660 @param [in] Trace If TRUE, trace the ACPI fields.
661 @param [in] Ptr Pointer to the start of the buffer.
662 @param [in] AcpiTableLength Length of the ACPI table.
663 @param [in] AcpiTableRevision Revision of the ACPI table.
670 IN UINT32 AcpiTableLength
,
671 IN UINT8 AcpiTableRevision
674 /** This function parses the ACPI SPCR table.
675 When trace is enabled this function parses the SPCR table and
676 traces the ACPI table fields.
678 This function also performs validations of the ACPI table fields.
680 @param [in] Trace If TRUE, trace the ACPI fields.
681 @param [in] Ptr Pointer to the start of the buffer.
682 @param [in] AcpiTableLength Length of the ACPI table.
683 @param [in] AcpiTableRevision Revision of the ACPI table.
690 IN UINT32 AcpiTableLength
,
691 IN UINT8 AcpiTableRevision
694 /** This function parses the ACPI SRAT table.
695 When trace is enabled this function parses the SRAT table and
696 traces the ACPI table fields.
698 This function parses the following Resource Allocation Structures:
699 - Processor Local APIC/SAPIC Affinity Structure
700 - Memory Affinity Structure
701 - Processor Local x2APIC Affinity Structure
702 - GICC Affinity Structure
704 This function also performs validation of the ACPI table fields.
706 @param [in] Trace If TRUE, trace the ACPI fields.
707 @param [in] Ptr Pointer to the start of the buffer.
708 @param [in] AcpiTableLength Length of the ACPI table.
709 @param [in] AcpiTableRevision Revision of the ACPI table.
716 IN UINT32 AcpiTableLength
,
717 IN UINT8 AcpiTableRevision
720 /** This function parses the ACPI SSDT table.
721 When trace is enabled this function parses the SSDT table and
722 traces the ACPI table fields.
723 For the SSDT table only the ACPI header fields are
726 @param [in] Trace If TRUE, trace the ACPI fields.
727 @param [in] Ptr Pointer to the start of the buffer.
728 @param [in] AcpiTableLength Length of the ACPI table.
729 @param [in] AcpiTableRevision Revision of the ACPI table.
736 IN UINT32 AcpiTableLength
,
737 IN UINT8 AcpiTableRevision
740 /** This function parses the ACPI XSDT table
741 and optionally traces the ACPI table fields.
743 This function also performs validation of the XSDT table.
745 @param [in] Trace If TRUE, trace the ACPI fields.
746 @param [in] Ptr Pointer to the start of the buffer.
747 @param [in] AcpiTableLength Length of the ACPI table.
748 @param [in] AcpiTableRevision Revision of the ACPI table.
755 IN UINT32 AcpiTableLength
,
756 IN UINT8 AcpiTableRevision
759 #endif // ACPIPARSER_H_