Re: [PATCH v4 20/63] Documentation: ACPI: move apei/einj.txt to firmware-guide/acpi and convert to reST

From: Changbin Du
Date: Wed Apr 24 2019 - 13:12:22 EST

On Wed, Apr 24, 2019 at 11:33:49AM -0300, Mauro Carvalho Chehab wrote:
> Em Wed, 24 Apr 2019 00:28:49 +0800
> Changbin Du <changbin.du@xxxxxxxxx> escreveu:
>
> > This converts the plain text documentation to reStructuredText format and
> > add it to Sphinx TOC tree. No essential content change.
> >
> > Signed-off-by: Changbin Du <changbin.du@xxxxxxxxx>
> > ---
> > .../acpi/apei/einj.rst} | 98 ++++++++++---------
> > Documentation/firmware-guide/acpi/index.rst | 1 +
> > 2 files changed, 53 insertions(+), 46 deletions(-)
> > rename Documentation/{acpi/apei/einj.txt => firmware-guide/acpi/apei/einj.rst} (67%)
> >
> > diff --git a/Documentation/acpi/apei/einj.txt b/Documentation/firmware-guide/acpi/apei/einj.rst
> > similarity index 67%
> > rename from Documentation/acpi/apei/einj.txt
> > rename to Documentation/firmware-guide/acpi/apei/einj.rst
> > index e550c8b98139..d85e2667155c 100644
> > --- a/Documentation/acpi/apei/einj.txt
> > +++ b/Documentation/firmware-guide/acpi/apei/einj.rst
> > @@ -1,13 +1,16 @@
> > - APEI Error INJection
> > - ~~~~~~~~~~~~~~~~~~~~
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +====================
> > +APEI Error INJection
> > +====================
> >
> > EINJ provides a hardware error injection mechanism. It is very useful
> > for debugging and testing APEI and RAS features in general.
> >
> > You need to check whether your BIOS supports EINJ first. For that, look
> > -for early boot messages similar to this one:
> > +for early boot messages similar to this one::
> >
> > -ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001)
> > + ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001)
> >
> > which shows that the BIOS is exposing an EINJ table - it is the
> > mechanism through which the injection is done.
> > @@ -23,11 +26,11 @@ order to see the APEI,EINJ,... functionality supported and exposed by
> > the BIOS menu.
> >
> > To use EINJ, make sure the following are options enabled in your kernel
> > -configuration:
> > +configuration::
> >
> > -CONFIG_DEBUG_FS
> > -CONFIG_ACPI_APEI
> > -CONFIG_ACPI_APEI_EINJ
> > + CONFIG_DEBUG_FS
> > + CONFIG_ACPI_APEI
> > + CONFIG_ACPI_APEI_EINJ
> >
> > The EINJ user interface is in <debugfs mount point>/apei/einj.
> >
> > @@ -35,22 +38,22 @@ The following files belong to it:
> >
> > - available_error_type
> >
> > - This file shows which error types are supported:
> > -
> > - Error Type Value Error Description
> > - ================ =================
> > - 0x00000001 Processor Correctable
> > - 0x00000002 Processor Uncorrectable non-fatal
> > - 0x00000004 Processor Uncorrectable fatal
> > - 0x00000008 Memory Correctable
> > - 0x00000010 Memory Uncorrectable non-fatal
> > - 0x00000020 Memory Uncorrectable fatal
> > - 0x00000040 PCI Express Correctable
> > - 0x00000080 PCI Express Uncorrectable fatal
> > - 0x00000100 PCI Express Uncorrectable non-fatal
> > - 0x00000200 Platform Correctable
> > - 0x00000400 Platform Uncorrectable non-fatal
> > - 0x00000800 Platform Uncorrectable fatal
> > + This file shows which error types are supported::
> > +
> > + Error Type Value Error Description
> > + ================ =================
> > + 0x00000001 Processor Correctable
> > + 0x00000002 Processor Uncorrectable non-fatal
> > + 0x00000004 Processor Uncorrectable fatal
> > + 0x00000008 Memory Correctable
> > + 0x00000010 Memory Uncorrectable non-fatal
> > + 0x00000020 Memory Uncorrectable fatal
> > + 0x00000040 PCI Express Correctable
> > + 0x00000080 PCI Express Uncorrectable fatal
> > + 0x00000100 PCI Express Uncorrectable non-fatal
> > + 0x00000200 Platform Correctable
> > + 0x00000400 Platform Uncorrectable non-fatal
> > + 0x00000800 Platform Uncorrectable fatal
>
> This is a table and not a literal block.
>
> The best here to preserve the author's intent is to just adjust the table
> markups in order to make it parseable, e. g.:
>
> This file shows which error types are supported:
>
> ================ ===================================
> Error Type Value Error Description
> ================ ===================================
> 0x00000001 Processor Correctable
> 0x00000002 Processor Uncorrectable non-fatal
> 0x00000004 Processor Uncorrectable fatal
> 0x00000008 Memory Correctable
> 0x00000010 Memory Uncorrectable non-fatal
> 0x00000020 Memory Uncorrectable fatal
> 0x00000040 PCI Express Correctable
> 0x00000080 PCI Express Uncorrectable fatal
> 0x00000100 PCI Express Uncorrectable non-fatal
> 0x00000200 Platform Correctable
> 0x00000400 Platform Uncorrectable non-fatal
> 0x00000800 Platform Uncorrectable fatal
> ================ ===================================
>
Done, thanks.

> After such change:
>
> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx>
>
> >
> > The format of the file contents are as above, except present are only
> > the available error types.
> > @@ -73,9 +76,12 @@ The following files belong to it:
> > injection. Value is a bitmask as specified in ACPI5.0 spec for the
> > SET_ERROR_TYPE_WITH_ADDRESS data structure:
> >
> > - Bit 0 - Processor APIC field valid (see param3 below).
> > - Bit 1 - Memory address and mask valid (param1 and param2).
> > - Bit 2 - PCIe (seg,bus,dev,fn) valid (see param4 below).
> > + Bit 0
> > + Processor APIC field valid (see param3 below).
> > + Bit 1
> > + Memory address and mask valid (param1 and param2).
> > + Bit 2
> > + PCIe (seg,bus,dev,fn) valid (see param4 below).
> >
> > If set to zero, legacy behavior is mimicked where the type of
> > injection specifies just one bit set, and param1 is multiplexed.
> > @@ -121,7 +127,7 @@ BIOS versions based on the ACPI 5.0 specification have more control over
> > the target of the injection. For processor-related errors (type 0x1, 0x2
> > and 0x4), you can set flags to 0x3 (param3 for bit 0, and param1 and
> > param2 for bit 1) so that you have more information added to the error
> > -signature being injected. The actual data passed is this:
> > +signature being injected. The actual data passed is this::
> >
> > memory_address = param1;
> > memory_address_range = param2;
> > @@ -131,7 +137,7 @@ signature being injected. The actual data passed is this:
> > For memory errors (type 0x8, 0x10 and 0x20) the address is set using
> > param1 with a mask in param2 (0x0 is equivalent to all ones). For PCI
> > express errors (type 0x40, 0x80 and 0x100) the segment, bus, device and
> > -function are specified using param1:
> > +function are specified using param1::
> >
> > 31 24 23 16 15 11 10 8 7 0
> > +-------------------------------------------------+
> > @@ -152,26 +158,26 @@ documentation for details (and expect changes to this API if vendors
> > creativity in using this feature expands beyond our expectations).
> >
> >
> > -An error injection example:
> > +An error injection example::
> >
> > -# cd /sys/kernel/debug/apei/einj
> > -# cat available_error_type # See which errors can be injected
> > -0x00000002 Processor Uncorrectable non-fatal
> > -0x00000008 Memory Correctable
> > -0x00000010 Memory Uncorrectable non-fatal
> > -# echo 0x12345000 > param1 # Set memory address for injection
> > -# echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page
> > -# echo 0x8 > error_type # Choose correctable memory error
> > -# echo 1 > error_inject # Inject now
> > + # cd /sys/kernel/debug/apei/einj
> > + # cat available_error_type # See which errors can be injected
> > + 0x00000002 Processor Uncorrectable non-fatal
> > + 0x00000008 Memory Correctable
> > + 0x00000010 Memory Uncorrectable non-fatal
> > + # echo 0x12345000 > param1 # Set memory address for injection
> > + # echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page
> > + # echo 0x8 > error_type # Choose correctable memory error
> > + # echo 1 > error_inject # Inject now
> >
> > -You should see something like this in dmesg:
> > +You should see something like this in dmesg::
> >
> > -[22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR
> > -[22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090
> > -[22715.834759] EDAC sbridge MC3: TSC 0
> > -[22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86
> > -[22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0
> > -[22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0)
> > + [22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR
> > + [22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090
> > + [22715.834759] EDAC sbridge MC3: TSC 0
> > + [22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86
> > + [22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0
> > + [22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0)
> >
> > For more information about EINJ, please refer to ACPI specification
> > version 4.0, section 17.5 and ACPI 5.0, section 18.6.
> > diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> > index 869badba6d7a..fca854f017d8 100644
> > --- a/Documentation/firmware-guide/acpi/index.rst
> > +++ b/Documentation/firmware-guide/acpi/index.rst
> > @@ -18,6 +18,7 @@ ACPI Support
> > debug
> > aml-debugger
> > apei/output_format
> > + apei/einj
> > gpio-properties
> > i2c-muxes
> > acpi-lid
>
>
>
> Thanks,
> Mauro

--
Cheers,
Changbin Du