From: Eric DeVolder <eric.devolder@oracle.com>
To: qemu-devel@nongnu.org, imammedo@redhat.com
Cc: ehabkost@redhat.com, konrad.wilk@oracle.com, mst@redhat.com,
pbonzini@redhat.com, boris.ostrovsky@oracle.com, rth@twiddle.net
Subject: [PATCH v6 02/10] ACPI ERST: specification for ERST support
Date: Thu, 5 Aug 2021 18:30:31 -0400 [thread overview]
Message-ID: <1628202639-16361-3-git-send-email-eric.devolder@oracle.com> (raw)
In-Reply-To: <1628202639-16361-1-git-send-email-eric.devolder@oracle.com>
Information on the implementation of the ACPI ERST support.
Signed-off-by: Eric DeVolder <eric.devolder@oracle.com>
---
docs/specs/acpi_erst.txt | 147 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 147 insertions(+)
create mode 100644 docs/specs/acpi_erst.txt
diff --git a/docs/specs/acpi_erst.txt b/docs/specs/acpi_erst.txt
new file mode 100644
index 0000000..7f7544f
--- /dev/null
+++ b/docs/specs/acpi_erst.txt
@@ -0,0 +1,147 @@
+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), 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.
+
+
+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 is reserved for 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 reserved to be a part of the slot 0 header. For example, at 8KiB,
+the slot 0 header can accomodate 1024 records. Thus a storage size
+above 8MiB (8KiB * 1024) requires an additional slot. 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
+ +--------------------------------------------+
+ 0 | reserved: storage header |
+ +--------------------------------------------+
+ 1 | empty/available |
+ +--------------------------------------------+
+ 2 | CPER |
+ +--------------------------------------------+
+ 3 | CPER |
+ +--------------------------------------------+
+ ... | |
+ +--------------------------------------------+
+ N | empty/available |
+ +--------------------------------------------+
+ <------------------ 8KiB -------------------->
+
+
+
+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".
--
1.8.3.1
next prev parent reply other threads:[~2021-08-05 22:39 UTC|newest]
Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-08-05 22:30 [PATCH v6 00/10] acpi: Error Record Serialization Table, ERST, support for QEMU Eric DeVolder
2021-08-05 22:30 ` [PATCH v6 01/10] ACPI ERST: bios-tables-test.c steps 1 and 2 Eric DeVolder
2021-09-20 13:05 ` Igor Mammedov
2021-10-04 20:37 ` Eric DeVolder
2021-08-05 22:30 ` Eric DeVolder [this message]
2021-09-20 13:38 ` [PATCH v6 02/10] ACPI ERST: specification for ERST support Igor Mammedov
2021-10-04 20:40 ` Eric DeVolder
2021-10-06 6:58 ` [PATCH] " Ani Sinha
2021-10-06 7:00 ` Ani Sinha
2021-10-06 20:07 ` Eric DeVolder
2021-10-07 4:39 ` Ani Sinha
2021-10-06 8:12 ` [PATCH v6 02/10] " Michael S. Tsirkin
2021-10-06 20:07 ` Eric DeVolder
2021-08-05 22:30 ` [PATCH v6 03/10] ACPI ERST: PCI device_id for ERST Eric DeVolder
2021-09-21 11:32 ` Igor Mammedov
2021-08-05 22:30 ` [PATCH v6 04/10] ACPI ERST: header file " Eric DeVolder
2021-08-05 22:30 ` [PATCH v6 05/10] ACPI ERST: support for ACPI ERST feature Eric DeVolder
2021-09-21 15:30 ` Igor Mammedov
2021-10-04 21:13 ` Eric DeVolder
2021-10-05 11:39 ` Igor Mammedov
2021-10-05 16:40 ` Eric DeVolder
2021-10-06 14:36 ` Igor Mammedov
2021-08-05 22:30 ` [PATCH v6 06/10] ACPI ERST: build the ACPI ERST table Eric DeVolder
2021-08-05 22:30 ` [PATCH v6 07/10] ACPI ERST: create ACPI ERST table for pc/x86 machines Eric DeVolder
2021-08-05 22:30 ` [PATCH v6 08/10] ACPI ERST: qtest for ERST Eric DeVolder
2021-08-05 22:30 ` [PATCH v6 09/10] ACPI ERST: bios-tables-test testcase Eric DeVolder
2021-09-21 11:32 ` Igor Mammedov
2021-10-04 21:13 ` Eric DeVolder
2021-08-05 22:30 ` [PATCH v6 10/10] ACPI ERST: step 6 of bios-tables-test Eric DeVolder
2021-08-06 17:16 ` Eric DeVolder
2021-08-27 21:45 ` Eric DeVolder
2021-09-02 6:34 ` Igor Mammedov
2021-09-21 11:24 ` Igor Mammedov
2021-10-04 21:14 ` Eric DeVolder
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1628202639-16361-3-git-send-email-eric.devolder@oracle.com \
--to=eric.devolder@oracle.com \
--cc=boris.ostrovsky@oracle.com \
--cc=ehabkost@redhat.com \
--cc=imammedo@redhat.com \
--cc=konrad.wilk@oracle.com \
--cc=mst@redhat.com \
--cc=pbonzini@redhat.com \
--cc=qemu-devel@nongnu.org \
--cc=rth@twiddle.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).