ACPI ERST: specification for ERST support
Information on the implementation of the ACPI ERST support. Signed-off-by: Eric DeVolder <eric.devolder@oracle.com> Acked-by: Ani Sinha <ani@anisinha.ca> Message-Id: <20220223143322.927136-2-ani@anisinha.ca> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
This commit is contained in:
Eric DeVolder
Michael S. Tsirkin
parent
e36828787f
commit
0ef0506e55
200
docs/specs/acpi_erst.rst
Normal file
200
docs/specs/acpi_erst.rst
Normal file
@ -0,0 +1,200 @@
|
||||
ACPI ERST DEVICE
|
||||
================
|
||||
|
||||
The ACPI ERST device is utilized to support the ACPI Error Record
|
||||
Serialization Table, ERST, functionality. This feature is designed for
|
||||
storing error records in persistent storage for future reference
|
||||
and/or debugging.
|
||||
|
||||
The ACPI specification[1], in Chapter "ACPI Platform Error Interfaces
|
||||
(APEI)", and specifically subsection "Error Serialization", outlines a
|
||||
method for storing error records into persistent storage.
|
||||
|
||||
The format of error records is described in the UEFI specification[2],
|
||||
in Appendix N "Common Platform Error Record".
|
||||
|
||||
While the ACPI specification allows for an NVRAM "mode" (see
|
||||
GET_ERROR_LOG_ADDRESS_RANGE_ATTRIBUTES) where non-volatile RAM is
|
||||
directly exposed for direct access by the OS/guest, this device
|
||||
implements the non-NVRAM "mode". This non-NVRAM "mode" is what is
|
||||
implemented by most BIOS (since flash memory requires programming
|
||||
operations in order to update its contents). Furthermore, as of the
|
||||
time of this writing, Linux only supports the non-NVRAM "mode".
|
||||
|
||||
|
||||
Background/Motivation
|
||||
---------------------
|
||||
|
||||
Linux uses the persistent storage filesystem, pstore, to record
|
||||
information (eg. dmesg tail) upon panics and shutdowns. Pstore is
|
||||
independent of, and runs before, kdump. In certain scenarios (ie.
|
||||
hosts/guests with root filesystems on NFS/iSCSI where networking
|
||||
software and/or hardware fails, and thus kdump fails), pstore may
|
||||
contain information available for post-mortem debugging.
|
||||
|
||||
Two common storage backends for the pstore filesystem are ACPI ERST
|
||||
and UEFI. Most BIOS implement ACPI ERST. UEFI is not utilized in all
|
||||
guests. With QEMU supporting ACPI ERST, it becomes a viable pstore
|
||||
storage backend for virtual machines (as it is now for bare metal
|
||||
machines).
|
||||
|
||||
Enabling support for ACPI ERST facilitates a consistent method to
|
||||
capture kernel panic information in a wide range of guests: from
|
||||
resource-constrained microvms to very large guests, and in particular,
|
||||
in direct-boot environments (which would lack UEFI run-time services).
|
||||
|
||||
Note that Microsoft Windows also utilizes the ACPI ERST for certain
|
||||
crash information, if available[3].
|
||||
|
||||
|
||||
Configuration|Usage
|
||||
-------------------
|
||||
|
||||
To use ACPI ERST, a memory-backend-file object and acpi-erst device
|
||||
can be created, for example:
|
||||
|
||||
qemu ...
|
||||
-object memory-backend-file,id=erstnvram,mem-path=acpi-erst.backing,size=0x10000,share=on \
|
||||
-device acpi-erst,memdev=erstnvram
|
||||
|
||||
For proper operation, the ACPI ERST device needs a memory-backend-file
|
||||
object with the following parameters:
|
||||
|
||||
- id: The id of the memory-backend-file object is used to associate
|
||||
this memory with the acpi-erst device.
|
||||
- size: The size of the ACPI ERST backing storage. This parameter is
|
||||
required.
|
||||
- mem-path: The location of the ACPI ERST backing storage file. This
|
||||
parameter is also required.
|
||||
- share: The share=on parameter is required so that updates to the
|
||||
ERST backing store are written to the file.
|
||||
|
||||
and ERST device:
|
||||
|
||||
- memdev: Is the object id of the memory-backend-file.
|
||||
- record_size: Specifies the size of the records (or slots) in the
|
||||
backend storage. Must be a power of two value greater than or
|
||||
equal to 4096 (PAGE_SIZE).
|
||||
|
||||
|
||||
PCI Interface
|
||||
-------------
|
||||
|
||||
The ERST device is a PCI device with two BARs, one for accessing the
|
||||
programming registers, and the other for accessing the record exchange
|
||||
buffer.
|
||||
|
||||
BAR0 contains the programming interface consisting of ACTION and VALUE
|
||||
64-bit registers. All ERST actions/operations/side effects happen on
|
||||
the write to the ACTION, by design. Any data needed by the action must
|
||||
be placed into VALUE prior to writing ACTION. Reading the VALUE
|
||||
simply returns the register contents, which can be updated by a
|
||||
previous ACTION.
|
||||
|
||||
BAR1 contains the 8KiB record exchange buffer, which is the
|
||||
implemented maximum record size.
|
||||
|
||||
|
||||
Backend Storage Format
|
||||
----------------------
|
||||
|
||||
The backend storage is divided into fixed size "slots", 8KiB in
|
||||
length, with each slot storing a single record. Not all slots need to
|
||||
be occupied, and they need not be occupied in a contiguous fashion.
|
||||
The ability to clear/erase specific records allows for the formation
|
||||
of unoccupied slots.
|
||||
|
||||
Slot 0 contains a backend storage header that identifies the contents
|
||||
as ERST and also facilitates efficient access to the records.
|
||||
Depending upon the size of the backend storage, additional slots will
|
||||
be designated to be a part of the slot 0 header. For example, at 8KiB,
|
||||
the slot 0 header can accomodate 1021 records. Thus a storage size
|
||||
of 8MiB (8KiB * 1024) requires an additional slot for use by the
|
||||
header. In this scenario, slot 0 and slot 1 form the backend storage
|
||||
header, and records can be stored starting at slot 2.
|
||||
|
||||
Below is an example layout of the backend storage format (for storage
|
||||
size less than 8MiB). The size of the storage is a multiple of 8KiB,
|
||||
and contains N number of slots to store records. The example below
|
||||
shows two records (in CPER format) in the backend storage, while the
|
||||
remaining slots are empty/available.
|
||||
|
||||
::
|
||||
|
||||
Slot Record
|
||||
<------------------ 8KiB -------------------->
|
||||
+--------------------------------------------+
|
||||
0 | storage header |
|
||||
+--------------------------------------------+
|
||||
1 | empty/available |
|
||||
+--------------------------------------------+
|
||||
2 | CPER |
|
||||
+--------------------------------------------+
|
||||
3 | CPER |
|
||||
+--------------------------------------------+
|
||||
... | |
|
||||
+--------------------------------------------+
|
||||
N | empty/available |
|
||||
+--------------------------------------------+
|
||||
|
||||
The storage header consists of some basic information and an array
|
||||
of CPER record_id's to efficiently access records in the backend
|
||||
storage.
|
||||
|
||||
All fields in the header are stored in little endian format.
|
||||
|
||||
::
|
||||
|
||||
+--------------------------------------------+
|
||||
| magic | 0x0000
|
||||
+--------------------------------------------+
|
||||
| record_offset | record_size | 0x0008
|
||||
+--------------------------------------------+
|
||||
| record_count | reserved | version | 0x0010
|
||||
+--------------------------------------------+
|
||||
| record_id[0] | 0x0018
|
||||
+--------------------------------------------+
|
||||
| record_id[1] | 0x0020
|
||||
+--------------------------------------------+
|
||||
| record_id[...] |
|
||||
+--------------------------------------------+
|
||||
| record_id[N] | 0x1FF8
|
||||
+--------------------------------------------+
|
||||
|
||||
The 'magic' field contains the value 0x524F545354535245.
|
||||
|
||||
The 'record_size' field contains the value 0x2000, 8KiB.
|
||||
|
||||
The 'record_offset' field points to the first record_id in the array,
|
||||
0x0018.
|
||||
|
||||
The 'version' field contains 0x0100, the first version.
|
||||
|
||||
The 'record_count' field contains the number of valid records in the
|
||||
backend storage.
|
||||
|
||||
The 'record_id' array fields are the 64-bit record identifiers of the
|
||||
CPER record in the corresponding slot. Stated differently, the
|
||||
location of a CPER record_id in the record_id[] array provides the
|
||||
slot index for the corresponding record in the backend storage.
|
||||
|
||||
Note that, for example, with a backend storage less than 8MiB, slot 0
|
||||
contains the header, so the record_id[0] will never contain a valid
|
||||
CPER record_id. Instead slot 1 is the first available slot and thus
|
||||
record_id_[1] may contain a CPER.
|
||||
|
||||
A 'record_id' of all 0s or all 1s indicates an invalid record (ie. the
|
||||
slot is available).
|
||||
|
||||
|
||||
References
|
||||
----------
|
||||
|
||||
[1] "Advanced Configuration and Power Interface Specification",
|
||||
version 4.0, June 2009.
|
||||
|
||||
[2] "Unified Extensible Firmware Interface Specification",
|
||||
version 2.1, October 2008.
|
||||
|
||||
[3] "Windows Hardware Error Architecture", specfically
|
||||
"Error Record Persistence Mechanism".
|
||||
@ -18,3 +18,4 @@ guest hardware that is specific to QEMU.
|
||||
acpi_mem_hotplug
|
||||
acpi_pci_hotplug
|
||||
acpi_nvdimm
|
||||
acpi_erst
|
||||
|
||||
Loading…
Reference in New Issue
Block a user