Documentation: ACPI: move apei/output_format.txt to firmware-guide/acpi and convert to reST

This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du <changbin.du@gmail.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

Documentation: ACPI: move apei/output_format.txt to firmware-guide/acpi and convert to reST
This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du <changbin.du@gmail.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Changbin Du · Rafael J. Wysocki
1 parent 472e89b4e1
Showing 3 changed files with 151 additions and 147 deletions Side-by-side Diff
Documentation/acpi/apei/output_format.txt
Documentation/firmware-guide/acpi/apei/output_format.rst
Documentation/firmware-guide/acpi/index.rst
-                     APEI output format
-                     ~~~~~~~~~~~~~~~~~~
-
-APEI uses printk as hardware error reporting interface, the output
-format is as follow.
-
-<error record> :=
-APEI generic hardware error status
-severity: <integer>, <severity string>
-section: <integer>, severity: <integer>, <severity string>
-flags: <integer>
-<section flags strings>
-fru_id: <uuid string>
-fru_text: <string>
-section_type: <section type string>
-<section data>
-
-<severity string>* := recoverable | fatal | corrected | info
-
-<section flags strings># :=
-[primary][, containment warning][, reset][, threshold exceeded]\
-[, resource not accessible][, latent error]
-
-<section type string> := generic processor error | memory error | \
-PCIe error | unknown, <uuid string>
-
-<section data> :=
-<generic processor section data> | <memory section data> | \
-<pcie section data> | <null>
-
-<generic processor section data> :=
-[processor_type: <integer>, <proc type string>]
-[processor_isa: <integer>, <proc isa string>]
-[error_type: <integer>
-<proc error type strings>]
-[operation: <integer>, <proc operation string>]
-[flags: <integer>
-<proc flags strings>]
-[level: <integer>]
-[version_info: <integer>]
-[processor_id: <integer>]
-[target_address: <integer>]
-[requestor_id: <integer>]
-[responder_id: <integer>]
-[IP: <integer>]
-
-<proc type string>* := IA32/X64 | IA64
-
-<proc isa string>* := IA32 | IA64 | X64
-
-<processor error type strings># :=
-[cache error][, TLB error][, bus error][, micro-architectural error]
-
-<proc operation string>* := unknown or generic | data read | data write | \
-instruction execution
-
-<proc flags strings># :=
-[restartable][, precise IP][, overflow][, corrected]
-
-<memory section data> :=
-[error_status: <integer>]
-[physical_address: <integer>]
-[physical_address_mask: <integer>]
-[node: <integer>]
-[card: <integer>]
-[module: <integer>]
-[bank: <integer>]
-[device: <integer>]
-[row: <integer>]
-[column: <integer>]
-[bit_position: <integer>]
-[requestor_id: <integer>]
-[responder_id: <integer>]
-[target_id: <integer>]
-[error_type: <integer>, <mem error type string>]
-
-<mem error type string>* :=
-unknown | no error | single-bit ECC | multi-bit ECC | \
-single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \
-target abort | parity error | watchdog timeout | invalid address | \
-mirror Broken | memory sparing | scrub corrected error | \
-scrub uncorrected error
-
-<pcie section data> :=
-[port_type: <integer>, <pcie port type string>]
-[version: <integer>.<integer>]
-[command: <integer>, status: <integer>]
-[device_id: <integer>:<integer>:<integer>.<integer>
-slot: <integer>
-secondary_bus: <integer>
-vendor_id: <integer>, device_id: <integer>
-class_code: <integer>]
-[serial number: <integer>, <integer>]
-[bridge: secondary_status: <integer>, control: <integer>]
-[aer_status: <integer>, aer_mask: <integer>
-<aer status string>
-[aer_uncor_severity: <integer>]
-aer_layer=<aer layer string>, aer_agent=<aer agent string>
-aer_tlp_header: <integer> <integer> <integer> <integer>]
-
-<pcie port type string>* := PCIe end point | legacy PCI end point | \
-unknown | unknown | root port | upstream switch port | \
-downstream switch port | PCIe to PCI/PCI-X bridge | \
-PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \
-root complex event collector
-
-if section severity is fatal or recoverable
-<aer status string># :=
-unknown | unknown | unknown | unknown | Data Link Protocol | \
-unknown | unknown | unknown | unknown | unknown | unknown | unknown | \
-Poisoned TLP | Flow Control Protocol | Completion Timeout | \
-Completer Abort | Unexpected Completion | Receiver Overflow | \
-Malformed TLP | ECRC | Unsupported Request
-else
-<aer status string># :=
-Receiver Error | unknown | unknown | unknown | unknown | unknown | \
-Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \
-Replay Timer Timeout | Advisory Non-Fatal
-fi
-
-<aer layer string> :=
-Physical Layer | Data Link Layer | Transaction Layer
-
-<aer agent string> :=
-Receiver ID | Requester ID | Completer ID | Transmitter ID
-
-Where, [] designate corresponding content is optional
-
-All <field string> description with * has the following format:
-
-field: <integer>, <field string>
-
-Where value of <integer> should be the position of "string" in <field
-string> description. Otherwise, <field string> will be "unknown".
-
-All <field strings> description with # has the following format:
-
-field: <integer>
-<field strings>
-
-Where each string in <fields strings> corresponding to one set bit of
-<integer>. The bit position is the position of "string" in <field
-strings> description.
-
-For more detailed explanation of every field, please refer to UEFI
-specification version 2.3 or later, section Appendix N: Common
-Platform Error Record.
+.. SPDX-License-Identifier: GPL-2.0
+
+==================
+APEI output format
+==================
+
+APEI uses printk as hardware error reporting interface, the output
+format is as follow::
+
+        <error record> :=
+        APEI generic hardware error status
+        severity: <integer>, <severity string>
+        section: <integer>, severity: <integer>, <severity string>
+        flags: <integer>
+        <section flags strings>
+        fru_id: <uuid string>
+        fru_text: <string>
+        section_type: <section type string>
+        <section data>
+
+        <severity string>* := recoverable | fatal | corrected | info
+
+        <section flags strings># :=
+        [primary][, containment warning][, reset][, threshold exceeded]\
+        [, resource not accessible][, latent error]
+
+        <section type string> := generic processor error | memory error | \
+        PCIe error | unknown, <uuid string>
+
+        <section data> :=
+        <generic processor section data> | <memory section data> | \
+        <pcie section data> | <null>
+
+        <generic processor section data> :=
+        [processor_type: <integer>, <proc type string>]
+        [processor_isa: <integer>, <proc isa string>]
+        [error_type: <integer>
+        <proc error type strings>]
+        [operation: <integer>, <proc operation string>]
+        [flags: <integer>
+        <proc flags strings>]
+        [level: <integer>]
+        [version_info: <integer>]
+        [processor_id: <integer>]
+        [target_address: <integer>]
+        [requestor_id: <integer>]
+        [responder_id: <integer>]
+        [IP: <integer>]
+
+        <proc type string>* := IA32/X64 | IA64
+
+        <proc isa string>* := IA32 | IA64 | X64
+
+        <processor error type strings># :=
+        [cache error][, TLB error][, bus error][, micro-architectural error]
+
+        <proc operation string>* := unknown or generic | data read | data write | \
+        instruction execution
+
+        <proc flags strings># :=
+        [restartable][, precise IP][, overflow][, corrected]
+
+        <memory section data> :=
+        [error_status: <integer>]
+        [physical_address: <integer>]
+        [physical_address_mask: <integer>]
+        [node: <integer>]
+        [card: <integer>]
+        [module: <integer>]
+        [bank: <integer>]
+        [device: <integer>]
+        [row: <integer>]
+        [column: <integer>]
+        [bit_position: <integer>]
+        [requestor_id: <integer>]
+        [responder_id: <integer>]
+        [target_id: <integer>]
+        [error_type: <integer>, <mem error type string>]
+
+        <mem error type string>* :=
+        unknown | no error | single-bit ECC | multi-bit ECC | \
+        single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \
+        target abort | parity error | watchdog timeout | invalid address | \
+        mirror Broken | memory sparing | scrub corrected error | \
+        scrub uncorrected error
+
+        <pcie section data> :=
+        [port_type: <integer>, <pcie port type string>]
+        [version: <integer>.<integer>]
+        [command: <integer>, status: <integer>]
+        [device_id: <integer>:<integer>:<integer>.<integer>
+        slot: <integer>
+        secondary_bus: <integer>
+        vendor_id: <integer>, device_id: <integer>
+        class_code: <integer>]
+        [serial number: <integer>, <integer>]
+        [bridge: secondary_status: <integer>, control: <integer>]
+        [aer_status: <integer>, aer_mask: <integer>
+        <aer status string>
+        [aer_uncor_severity: <integer>]
+        aer_layer=<aer layer string>, aer_agent=<aer agent string>
+        aer_tlp_header: <integer> <integer> <integer> <integer>]
+
+        <pcie port type string>* := PCIe end point | legacy PCI end point | \
+        unknown | unknown | root port | upstream switch port | \
+        downstream switch port | PCIe to PCI/PCI-X bridge | \
+        PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \
+        root complex event collector
+
+        if section severity is fatal or recoverable
+        <aer status string># :=
+        unknown | unknown | unknown | unknown | Data Link Protocol | \
+        unknown | unknown | unknown | unknown | unknown | unknown | unknown | \
+        Poisoned TLP | Flow Control Protocol | Completion Timeout | \
+        Completer Abort | Unexpected Completion | Receiver Overflow | \
+        Malformed TLP | ECRC | Unsupported Request
+        else
+        <aer status string># :=
+        Receiver Error | unknown | unknown | unknown | unknown | unknown | \
+        Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \
+        Replay Timer Timeout | Advisory Non-Fatal
+        fi
+
+        <aer layer string> :=
+        Physical Layer | Data Link Layer | Transaction Layer
+
+        <aer agent string> :=
+        Receiver ID | Requester ID | Completer ID | Transmitter ID
+
+Where, [] designate corresponding content is optional
+
+All <field string> description with * has the following format::
+
+        field: <integer>, <field string>
+
+Where value of <integer> should be the position of "string" in <field
+string> description. Otherwise, <field string> will be "unknown".
+
+All <field strings> description with # has the following format::
+
+        field: <integer>
+        <field strings>
+
+Where each string in <fields strings> corresponding to one set bit of
+<integer>. The bit position is the position of "string" in <field
+strings> description.
+
+For more detailed explanation of every field, please refer to UEFI
+specification version 2.3 or later, section Appendix N: Common
+Platform Error Record.
@@ -17,6 +17,7 @@
    DSD-properties-rules
    debug
    aml-debugger
+   apei/output_format
    gpio-properties
    i2c-muxes
    acpi-lid
1		- APEI output format
2		- ~~~~~~~~~~~~~~~~~~
3		-
4		-APEI uses printk as hardware error reporting interface, the output
5		-format is as follow.
6		-
7		-<error record> :=
8		-APEI generic hardware error status
9		-severity: <integer>, <severity string>
10		-section: <integer>, severity: <integer>, <severity string>
11		-flags: <integer>
12		-<section flags strings>
13		-fru_id: <uuid string>
14		-fru_text: <string>
15		-section_type: <section type string>
16		-<section data>
17		-
18		-<severity string>* := recoverable \| fatal \| corrected \| info
19		-
20		-<section flags strings># :=
21		-[primary][, containment warning][, reset][, threshold exceeded]\
22		-[, resource not accessible][, latent error]
23		-
24		-<section type string> := generic processor error \| memory error \| \
25		-PCIe error \| unknown, <uuid string>
26		-
27		-<section data> :=
28		-<generic processor section data> \| <memory section data> \| \
29		-<pcie section data> \| <null>
30		-
31		-<generic processor section data> :=
32		-[processor_type: <integer>, <proc type string>]
33		-[processor_isa: <integer>, <proc isa string>]
34		-[error_type: <integer>
35		-<proc error type strings>]
36		-[operation: <integer>, <proc operation string>]
37		-[flags: <integer>
38		-<proc flags strings>]
39		-[level: <integer>]
40		-[version_info: <integer>]
41		-[processor_id: <integer>]
42		-[target_address: <integer>]
43		-[requestor_id: <integer>]
44		-[responder_id: <integer>]
45		-[IP: <integer>]
46		-
47		-<proc type string>* := IA32/X64 \| IA64
48		-
49		-<proc isa string>* := IA32 \| IA64 \| X64
50		-
51		-<processor error type strings># :=
52		-[cache error][, TLB error][, bus error][, micro-architectural error]
53		-
54		-<proc operation string>* := unknown or generic \| data read \| data write \| \
55		-instruction execution
56		-
57		-<proc flags strings># :=
58		-[restartable][, precise IP][, overflow][, corrected]
59		-
60		-<memory section data> :=
61		-[error_status: <integer>]
62		-[physical_address: <integer>]
63		-[physical_address_mask: <integer>]
64		-[node: <integer>]
65		-[card: <integer>]
66		-[module: <integer>]
67		-[bank: <integer>]
68		-[device: <integer>]
69		-[row: <integer>]
70		-[column: <integer>]
71		-[bit_position: <integer>]
72		-[requestor_id: <integer>]
73		-[responder_id: <integer>]
74		-[target_id: <integer>]
75		-[error_type: <integer>, <mem error type string>]
76		-
77		-<mem error type string>* :=
78		-unknown \| no error \| single-bit ECC \| multi-bit ECC \| \
79		-single-symbol chipkill ECC \| multi-symbol chipkill ECC \| master abort \| \
80		-target abort \| parity error \| watchdog timeout \| invalid address \| \
81		-mirror Broken \| memory sparing \| scrub corrected error \| \
82		-scrub uncorrected error
83		-
84		-<pcie section data> :=
85		-[port_type: <integer>, <pcie port type string>]
86		-[version: <integer>.<integer>]
87		-[command: <integer>, status: <integer>]
88		-[device_id: <integer>:<integer>:<integer>.<integer>
89		-slot: <integer>
90		-secondary_bus: <integer>
91		-vendor_id: <integer>, device_id: <integer>
92		-class_code: <integer>]
93		-[serial number: <integer>, <integer>]
94		-[bridge: secondary_status: <integer>, control: <integer>]
95		-[aer_status: <integer>, aer_mask: <integer>
96		-<aer status string>
97		-[aer_uncor_severity: <integer>]
98		-aer_layer=<aer layer string>, aer_agent=<aer agent string>
99		-aer_tlp_header: <integer> <integer> <integer> <integer>]
100		-
101		-<pcie port type string>* := PCIe end point \| legacy PCI end point \| \
102		-unknown \| unknown \| root port \| upstream switch port \| \
103		-downstream switch port \| PCIe to PCI/PCI-X bridge \| \
104		-PCI/PCI-X to PCIe bridge \| root complex integrated endpoint device \| \
105		-root complex event collector
106		-
107		-if section severity is fatal or recoverable
108		-<aer status string># :=
109		-unknown \| unknown \| unknown \| unknown \| Data Link Protocol \| \
110		-unknown \| unknown \| unknown \| unknown \| unknown \| unknown \| unknown \| \
111		-Poisoned TLP \| Flow Control Protocol \| Completion Timeout \| \
112		-Completer Abort \| Unexpected Completion \| Receiver Overflow \| \
113		-Malformed TLP \| ECRC \| Unsupported Request
114		-else
115		-<aer status string># :=
116		-Receiver Error \| unknown \| unknown \| unknown \| unknown \| unknown \| \
117		-Bad TLP \| Bad DLLP \| RELAY_NUM Rollover \| unknown \| unknown \| unknown \| \
118		-Replay Timer Timeout \| Advisory Non-Fatal
119		-fi
120		-
121		-<aer layer string> :=
122		-Physical Layer \| Data Link Layer \| Transaction Layer
123		-
124		-<aer agent string> :=
125		-Receiver ID \| Requester ID \| Completer ID \| Transmitter ID
126		-
127		-Where, [] designate corresponding content is optional
128		-
129		-All <field string> description with * has the following format:
130		-
131		-field: <integer>, <field string>
132		-
133		-Where value of <integer> should be the position of "string" in <field
134		-string> description. Otherwise, <field string> will be "unknown".
135		-
136		-All <field strings> description with # has the following format:
137		-
138		-field: <integer>
139		-<field strings>
140		-
141		-Where each string in <fields strings> corresponding to one set bit of
142		-<integer>. The bit position is the position of "string" in <field
143		-strings> description.
144		-
145		-For more detailed explanation of every field, please refer to UEFI
146		-specification version 2.3 or later, section Appendix N: Common
147		-Platform Error Record.
	1	+.. SPDX-License-Identifier: GPL-2.0
	2	+
	3	+==================
	4	+APEI output format
	5	+==================
	6	+
	7	+APEI uses printk as hardware error reporting interface, the output
	8	+format is as follow::
	9	+
	10	+ <error record> :=
	11	+ APEI generic hardware error status
	12	+ severity: <integer>, <severity string>
	13	+ section: <integer>, severity: <integer>, <severity string>
	14	+ flags: <integer>
	15	+ <section flags strings>
	16	+ fru_id: <uuid string>
	17	+ fru_text: <string>
	18	+ section_type: <section type string>
	19	+ <section data>
	20	+
	21	+ <severity string>* := recoverable \| fatal \| corrected \| info
	22	+
	23	+ <section flags strings># :=
	24	+ [primary][, containment warning][, reset][, threshold exceeded]\
	25	+ [, resource not accessible][, latent error]
	26	+
	27	+ <section type string> := generic processor error \| memory error \| \
	28	+ PCIe error \| unknown, <uuid string>
	29	+
	30	+ <section data> :=
	31	+ <generic processor section data> \| <memory section data> \| \
	32	+ <pcie section data> \| <null>
	33	+
	34	+ <generic processor section data> :=
	35	+ [processor_type: <integer>, <proc type string>]
	36	+ [processor_isa: <integer>, <proc isa string>]
	37	+ [error_type: <integer>
	38	+ <proc error type strings>]
	39	+ [operation: <integer>, <proc operation string>]
	40	+ [flags: <integer>
	41	+ <proc flags strings>]
	42	+ [level: <integer>]
	43	+ [version_info: <integer>]
	44	+ [processor_id: <integer>]
	45	+ [target_address: <integer>]
	46	+ [requestor_id: <integer>]
	47	+ [responder_id: <integer>]
	48	+ [IP: <integer>]
	49	+
	50	+ <proc type string>* := IA32/X64 \| IA64
	51	+
	52	+ <proc isa string>* := IA32 \| IA64 \| X64
	53	+
	54	+ <processor error type strings># :=
	55	+ [cache error][, TLB error][, bus error][, micro-architectural error]
	56	+
	57	+ <proc operation string>* := unknown or generic \| data read \| data write \| \
	58	+ instruction execution
	59	+
	60	+ <proc flags strings># :=
	61	+ [restartable][, precise IP][, overflow][, corrected]
	62	+
	63	+ <memory section data> :=
	64	+ [error_status: <integer>]
	65	+ [physical_address: <integer>]
	66	+ [physical_address_mask: <integer>]
	67	+ [node: <integer>]
	68	+ [card: <integer>]
	69	+ [module: <integer>]
	70	+ [bank: <integer>]
	71	+ [device: <integer>]
	72	+ [row: <integer>]
	73	+ [column: <integer>]
	74	+ [bit_position: <integer>]
	75	+ [requestor_id: <integer>]
	76	+ [responder_id: <integer>]
	77	+ [target_id: <integer>]
	78	+ [error_type: <integer>, <mem error type string>]
	79	+
	80	+ <mem error type string>* :=
	81	+ unknown \| no error \| single-bit ECC \| multi-bit ECC \| \
	82	+ single-symbol chipkill ECC \| multi-symbol chipkill ECC \| master abort \| \
	83	+ target abort \| parity error \| watchdog timeout \| invalid address \| \
	84	+ mirror Broken \| memory sparing \| scrub corrected error \| \
	85	+ scrub uncorrected error
	86	+
	87	+ <pcie section data> :=
	88	+ [port_type: <integer>, <pcie port type string>]
	89	+ [version: <integer>.<integer>]
	90	+ [command: <integer>, status: <integer>]
	91	+ [device_id: <integer>:<integer>:<integer>.<integer>
	92	+ slot: <integer>
	93	+ secondary_bus: <integer>
	94	+ vendor_id: <integer>, device_id: <integer>
	95	+ class_code: <integer>]
	96	+ [serial number: <integer>, <integer>]
	97	+ [bridge: secondary_status: <integer>, control: <integer>]
	98	+ [aer_status: <integer>, aer_mask: <integer>
	99	+ <aer status string>
	100	+ [aer_uncor_severity: <integer>]
	101	+ aer_layer=<aer layer string>, aer_agent=<aer agent string>
	102	+ aer_tlp_header: <integer> <integer> <integer> <integer>]
	103	+
	104	+ <pcie port type string>* := PCIe end point \| legacy PCI end point \| \
	105	+ unknown \| unknown \| root port \| upstream switch port \| \
	106	+ downstream switch port \| PCIe to PCI/PCI-X bridge \| \
	107	+ PCI/PCI-X to PCIe bridge \| root complex integrated endpoint device \| \
	108	+ root complex event collector
	109	+
	110	+ if section severity is fatal or recoverable
	111	+ <aer status string># :=
	112	+ unknown \| unknown \| unknown \| unknown \| Data Link Protocol \| \
	113	+ unknown \| unknown \| unknown \| unknown \| unknown \| unknown \| unknown \| \
	114	+ Poisoned TLP \| Flow Control Protocol \| Completion Timeout \| \
	115	+ Completer Abort \| Unexpected Completion \| Receiver Overflow \| \
	116	+ Malformed TLP \| ECRC \| Unsupported Request
	117	+ else
	118	+ <aer status string># :=
	119	+ Receiver Error \| unknown \| unknown \| unknown \| unknown \| unknown \| \
	120	+ Bad TLP \| Bad DLLP \| RELAY_NUM Rollover \| unknown \| unknown \| unknown \| \
	121	+ Replay Timer Timeout \| Advisory Non-Fatal
	122	+ fi
	123	+
	124	+ <aer layer string> :=
	125	+ Physical Layer \| Data Link Layer \| Transaction Layer
	126	+
	127	+ <aer agent string> :=
	128	+ Receiver ID \| Requester ID \| Completer ID \| Transmitter ID
	129	+
	130	+Where, [] designate corresponding content is optional
	131	+
	132	+All <field string> description with * has the following format::
	133	+
	134	+ field: <integer>, <field string>
	135	+
	136	+Where value of <integer> should be the position of "string" in <field
	137	+string> description. Otherwise, <field string> will be "unknown".
	138	+
	139	+All <field strings> description with # has the following format::
	140	+
	141	+ field: <integer>
	142	+ <field strings>
	143	+
	144	+Where each string in <fields strings> corresponding to one set bit of
	145	+<integer>. The bit position is the position of "string" in <field
	146	+strings> description.
	147	+
	148	+For more detailed explanation of every field, please refer to UEFI
	149	+specification version 2.3 or later, section Appendix N: Common
	150	+Platform Error Record.
...	...	@@ -17,6 +17,7 @@
17	17	DSD-properties-rules
18	18	debug
19	19	aml-debugger
	20	+ apei/output_format
20	21	gpio-properties
21	22	i2c-muxes
22	23	acpi-lid