archive mirror
 help / color / mirror / Atom feed
From: Chen Yu <>
	"Rafael J. Wysocki" <>,
	Len Brown <>,
	Dan Williams <>,
	Andy Shevchenko <>,
	Aubrey Li <>, Ashok Raj <>,
	Chen Yu <>, Mike Rapoport <>,
	Ard Biesheuvel <>,
	Thomas Gleixner <>,
	Ingo Molnar <>, Borislav Petkov <>,
	"H. Peter Anvin" <>,
	Jonathan Corbet <>,,
Subject: [PATCH v2 1/5] Documentation: Introduce Platform Firmware Runtime Update documentation
Date: Tue, 14 Sep 2021 15:28:00 +0800	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

Add the Platform Firmware Runtime Update/Telemetry documentation.

Signed-off-by: Chen Yu <>
v2: Add a spot in index.rst so it becomes part of the docs build
    (Jonathan Corbet).
    Sticking to the 80-column limit(Jonathan Corbet).
    Underline lengths should match the title text(Jonathan Corbet).
    Use literal blocks for the code samples(Jonathan Corbet).
 Documentation/x86/index.rst |   1 +
 Documentation/x86/pfru.rst  | 100 ++++++++++++++++++++++++++++++++++++
 2 files changed, 101 insertions(+)
 create mode 100644 Documentation/x86/pfru.rst

diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index 383048396336..3791fabf964c 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -37,3 +37,4 @@ x86-specific Documentation
+   pfru
diff --git a/Documentation/x86/pfru.rst b/Documentation/x86/pfru.rst
new file mode 100644
index 000000000000..29fe0e518e6d
--- /dev/null
+++ b/Documentation/x86/pfru.rst
@@ -0,0 +1,100 @@
+.. SPDX-License-Identifier: GPL-2.0
+The Linux Platform Firmware Runtime Update and Telemetry
+According to the specification of `Management Mode Firmware Runtime Update
+Rev100.pdf>`_, certain computing systems require high Service Level Agreements
+(SLAs) where system reboot fewer firmware updates are required to deploy
+firmware changes to address bug fixes, security updates and to debug and root
+cause issues. This technology is called Intel Seamless Update. The management
+mode (MM), UEFI runtime services and ACPI services handle most of the system
+runtime functions. Changing the MM code execution during runtime is called MM
+Runtime Update. Since the "MM" acronyms might be misunderstood as "Memory
+Management", this driver uses the name of "Platform Firmware Runtime Update"
+PFRU provides the following facilities: Performs a runtime firmware driver
+update and activate. Ability to inject firmware code at runtime, for dynamic
+instrumentation. PFRU Telemetry is a service which allows Runtime Update
+handler to produce telemetry data to upper layer OS consumer at runtime. The
+OS provides interfaces to let the users query the telemetry data via read
+operations. The specification specifies the interface and recommended policy
+to extract the data, the format and use are left to individual OEM's and BIOS
+implementations on what that data represents.
+PFRU interfaces
+The user space tool manipulates on /dev/pfru/update for code injection and
+driver update. PFRU stands for Platform Firmware Runtime Update, and the
+/dev/pfru directory might be reserved for future usage::
+ 1. mmap the capsule file.
+    fd_capsule = open("capsule.cap", O_RDONLY);
+    fstat(fd_capsule, &stat);
+    addr = mmap(0, stat.st_size, PROT_READ, fd_capsule);
+ 2. Get the capability information(version control, etc) from BIOS via
+    read() and do sanity check in user space.
+    fd_update = open("/dev/pfru/update", O_RDWR);
+    read(fd_update, &cap, sizeof(cap));
+    sanity_check(&cap);
+ 3. Write the capsule file to runtime update communication buffer.
+    kernel might return error if capsule file size is longer than
+    communication buffer.
+    write(fd_update, addr, stat.st_size);
+ 4. Stage the code injection.
+    ioctl(fd_update, PFRU_IOC_STATGE);
+ 5. Activate the code injection.
+    ioctl(fd_update, PFRU_IOC_ACTIVATE);
+ 6. Stage and activate the code injection.
+    ioctl(fd_update, PFRU_IOC_STAGE_ACTIVATE);
+    PFRU_IOC_STATGE: Stage a capsule image from communication buffer
+    and perform authentication.
+    [PFRU_IOC_ACTIVATE] Activate a previous staged capsule image.
+    [PFRU_IOC_STAGE_ACTIVATE] Perform both stage and activation actions.
+PFRU Telemetry interfaces
+The user space tool manipulates on /dev/pfru/telemetry for PFRU telemetry log::
+ 1. Open telemetry device
+    fd_log = open("/dev/pfru/telemetry", O_RDWR);
+ 2. Get log level, log type, revision_id via one ioctl invoke
+    ioctl(fd_log, PFRU_IOC_GET_LOG_INFO, &info);
+ 3. Set log level, log type, revision_id
+    ioctl(fd_log, PFRU_IOC_SET_LOG_INFO, &info);
+ 4. ioctl(fd_log, PFRU_IOC_GET_DATA_INFO, &data_info);
+    Query the information of PFRU telemetry log buffer. The user is
+    responsible for parsing the result per the specification.
+ 5. Read the telemetry data:
+    read(fd_log, buf, data_info.size);
+Please refer to tools/testing/selftests/pfru/pfru_test.c for detail.
+According to the specification of `Management Mode Firmware Runtime Update
+Rev100.pdf>`_, the telemetry buffer is a wrap around buffer. If the telemetry
+buffer gets full, most recent log data will overwrite old log data. Besides,
+it is required in the spec that the read of telemetry should support both full
+data retrieval and delta telemetry data retrieval. Since this requirement is
+more likely a policy we leave this implementation in user space. That is to
+say, it is recommended for the user to double-read the telemetry parameters
+such as chunk1_size, chunk2_size, rollover_cnt in data_info structure to make
+sure that there is no more data appended while the user is reading the buffer.
+Besides, only after the runtime update has been run at least once, the telemetry
+log would have valid data, otherwise errno code of EBUSY would be returned.

  reply	other threads:[~2021-09-14  7:22 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-09-14  7:24 [PATCH v2 0/5] Introduce Platform Firmware Runtime Update and Telemetry drivers Chen Yu
2021-09-14  7:28 ` Chen Yu [this message]
2021-09-14  7:30 ` [PATCH v2 2/5] efi: Introduce EFI_FIRMWARE_MANAGEMENT_CAPSULE_HEADER and corresponding structures Chen Yu
2021-09-14  7:58 ` [PATCH v2 3/5] drivers/acpi: Introduce Platform Firmware Runtime Update device driver Chen Yu
2021-09-14  8:11   ` Greg Kroah-Hartman
2021-09-15  9:03     ` Chen Yu
2021-09-14  8:11 ` [PATCH v2 4/5] drivers/acpi: Introduce Platform Firmware Runtime Update Telemetry Chen Yu
2021-09-14  8:12 ` [PATCH v2 5/5] selftests/pfru: add test for Platform Firmware Runtime Update and Telemetry Chen Yu

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:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \

* 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).