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

[Chen Yu]

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 <yu.c.chen@xxxxxxxxx> writes:
> 
> > Add the Platform Firmware Runtime Update/Telemetry documentation.
> >
> > Signed-off-by: Chen Yu <yu.c.chen@xxxxxxxxx>
> > ---
> >  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