qemu/docs/specs/acpi_erst.rst

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 accommodate 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", specifically
    "Error Record Persistence Mechanism".