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

[Changbin Du <changbin.du@gmail.com>]

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@gmail.com> 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@gmail.com>
> > ---
> >  .../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@kernel.org>
> 
> >  
> >    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