[1/5,RFC] Documentation: Introduce Platform Firmware Runtime Update documentation

Commit Message

Chen Yu Sept. 7, 2021, 3:15 p.m. UTC

Add the Platform Firmware Runtime Update/Telemetry documentation.

Signed-off-by: Chen Yu <[e-mail]>
---
 Documentation/x86/pfru.rst | 98 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 Documentation/x86/pfru.rst

Comments

Jonathan Corbet Sept. 7, 2021, 3:23 p.m. UTC | #1

Thanks for adding to the documentation.  I have a few nits for you...

Chen Yu <[e-mail]> writes:

> Add the Platform Firmware Runtime Update/Telemetry documentation.
>
> Signed-off-by: Chen Yu <[e-mail]>
> ---
>  Documentation/x86/pfru.rst | 98 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 98 insertions(+)
>  create mode 100644 Documentation/x86/pfru.rst

When you add a new RST file, you also need to find a spot for it in
index.rst so it becomes part of the docs build.

> diff --git a/Documentation/x86/pfru.rst b/Documentation/x86/pfru.rst
> new file mode 100644
> index 000000000000..321729f46737
> --- /dev/null
> +++ b/Documentation/x86/pfru.rst
> @@ -0,0 +1,98 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +========================================================
> +The Linux Platform Firmware Runtime Update and Telemetry
> +========================================================
> +
> +According to the specification of <Management Mode Firmware Runtime Update>[1],
> +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 "Platform Firmware Runtime Update"(PFRU)
> +
> +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.

Sticking to the 80-column limit is preferable; it keeps the text
readable. 

> +PFRU interfaces
> +=====================

Underline lengths should match the title text, or Sphinx will get grumpy
with you.

> +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);

These will not render the way you would like; you'll want to use literal
blocks for the code samples.

> + 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
> +=============
> +
> +The user space tool manipulates on /dev/pfru/telemetry for PFRU telemetry log.
> +Sample code:
> +
> + 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 <Management Mode Firmware Runtime Update>[1], 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.
> +
> +[1] https://uefi.org/sites/default/files/resources/Intel_MM_OS_Interface_Spec_Rev100.pdf
> -- 
> 2.25.1

Thanks,

jon

Chen Yu Sept. 7, 2021, 3:48 p.m. UTC | #2

Hi Jon,
On Tue, Sep 07, 2021 at 09:23:53AM -0600, Jonathan Corbet wrote:
> Thanks for adding to the documentation.  I have a few nits for you...
> 
Thank you very much for your comments.
> Chen Yu <[e-mail]> writes:
> 
> > Add the Platform Firmware Runtime Update/Telemetry documentation.
> >
> > Signed-off-by: Chen Yu <[e-mail]>
> > ---
> >  Documentation/x86/pfru.rst | 98 ++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 98 insertions(+)
> >  create mode 100644 Documentation/x86/pfru.rst
> 
> When you add a new RST file, you also need to find a spot for it in
> index.rst so it becomes part of the docs build.
> 
I see. Will do in next version.
> > diff --git a/Documentation/x86/pfru.rst b/Documentation/x86/pfru.rst
> > new file mode 100644
> > index 000000000000..321729f46737
> > --- /dev/null
> > +++ b/Documentation/x86/pfru.rst
> > @@ -0,0 +1,98 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +========================================================
> > +The Linux Platform Firmware Runtime Update and Telemetry
> > +========================================================
> > +
> > +According to the specification of <Management Mode Firmware Runtime Update>[1],
> > +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 "Platform Firmware Runtime Update"(PFRU)
> > +
> > +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.
> 
> Sticking to the 80-column limit is preferable; it keeps the text
> readable. 
> 
Okay, will do.
> > +PFRU interfaces
> > +=====================
> 
> Underline lengths should match the title text, or Sphinx will get grumpy
> with you.
> 
Got it, will fix it.
> > +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);
> 
> These will not render the way you would like; you'll want to use literal
> blocks for the code samples.
> 
Okay, I'll fix it.

thanks,
Chenyu

Patch

diff --git a/Documentation/x86/pfru.rst b/Documentation/x86/pfru.rst
new file mode 100644
index 000000000000..321729f46737
--- /dev/null
+++ b/Documentation/x86/pfru.rst
@@ -0,0 +1,98 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+========================================================
+The Linux Platform Firmware Runtime Update and Telemetry
+========================================================
+
+According to the specification of <Management Mode Firmware Runtime Update>[1],
+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 "Platform Firmware Runtime Update"(PFRU)
+
+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
+=============
+
+The user space tool manipulates on /dev/pfru/telemetry for PFRU telemetry log.
+Sample code:
+
+ 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 <Management Mode Firmware Runtime Update>[1], 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.
+
+[1] https://uefi.org/sites/default/files/resources/Intel_MM_OS_Interface_Spec_Rev100.pdf