[PATCH 5/5 -v2] acpi, apei, Document for APEI

[PATCH 5/5 -v2] acpi, apei, Document for APEI

[Huang Ying]

Add document for APEI, including kernel parameters and EINJ debug file
sytem interface.

Signed-off-by: Huang Ying <ying.huang@intel.com>
---
 Documentation/acpi/apei/einj.txt    |   49 ++++++++++++++++++++++++++++++++++++
 Documentation/kernel-parameters.txt |    5 +++
 2 files changed, 54 insertions(+)
 create mode 100644 Documentation/acpi/apei/einj.txt

--- /dev/null
+++ b/Documentation/acpi/apei/einj.txt
@@ -0,0 +1,49 @@
+			APEI Error INJection
+			~~~~~~~~~~~~~~~~~~~~
+
+EINJ provides a hardware error injection mechanism, it is very useful
+for debugging and testing of other APEI and RAS features.
+
+To use EINJ, make the following is enabled in your kernel
+configuration:
+
+CONFIG_DEBUG_FS
+CONFIG_ACPI_APEI
+CONFIG_ACPI_APEI_EINJ
+
+The user interface of EINJ is in debug file system, under the
+directory apei/einj. The following files are provided.
+
+- available_error_type
+  Read this file will return the error injection capability of the
+  platform, that is, which error types are supported. The error type
+  definition is as follow, the left field is the error type value, the
+  right field is 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
+
+  The format of file contents are as above, except there are only the
+  available error type lines.
+
+- error_type
+  This file is used to set the error type value. The error type value
+  is defined in "available_error_type" description.
+
+- error_inject
+  Write any integer to this file to trigger the error
+  injection. Before this, please specify all necessary error
+  parameters.
+
+For more information about EINJ, please refer to ACPI specification
+version 4.0, section 17.5.
--- a/Documentation/kernel-parameters.txt
+++ b/Documentation/kernel-parameters.txt
@@ -338,6 +338,11 @@ and is between 256 and 4096 characters. 
 			not play well with APC CPU idle - disable it if you have
 			APC and your system crashes randomly.
 
+	apei.hest_disable= [ACPI]
+			Disable Hardware Error Source Table (HEST) support,
+			corresponding firmware-first mode error processing
+			logic will be disabled.
+
 	apic=		[APIC,X86-32] Advanced Programmable Interrupt Controller
 			Change the output verbosity whilst booting
 			Format: { quiet (default) | verbose | debug }

Re: [PATCH 5/5 -v2] acpi, apei, Document for APEI

[Bjorn Helgaas]

On Thursday 10 December 2009 12:17:04 am Huang Ying wrote:
> Add document for APEI, including kernel parameters and EINJ debug file
> sytem interface.

>From a stylistic point of view, I think it's better if the
documentation is added by the same patch that adds the functionality.
Having them in separate patches means there's a point in time where
the tree contains the functionality but not the documentation, or
vice versa.

Bjorn

> Signed-off-by: Huang Ying <ying.huang@intel.com>
> ---
>  Documentation/acpi/apei/einj.txt    |   49 ++++++++++++++++++++++++++++++++++++
>  Documentation/kernel-parameters.txt |    5 +++
>  2 files changed, 54 insertions(+)
>  create mode 100644 Documentation/acpi/apei/einj.txt
> 
> --- /dev/null
> +++ b/Documentation/acpi/apei/einj.txt
> @@ -0,0 +1,49 @@
> +			APEI Error INJection
> +			~~~~~~~~~~~~~~~~~~~~
> +
> +EINJ provides a hardware error injection mechanism, it is very useful
> +for debugging and testing of other APEI and RAS features.
> +
> +To use EINJ, make the following is enabled in your kernel
> +configuration:
> +
> +CONFIG_DEBUG_FS
> +CONFIG_ACPI_APEI
> +CONFIG_ACPI_APEI_EINJ
> +
> +The user interface of EINJ is in debug file system, under the
> +directory apei/einj. The following files are provided.
> +
> +- available_error_type
> +  Read this file will return the error injection capability of the
> +  platform, that is, which error types are supported. The error type
> +  definition is as follow, the left field is the error type value, the
> +  right field is 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
> +
> +  The format of file contents are as above, except there are only the
> +  available error type lines.
> +
> +- error_type
> +  This file is used to set the error type value. The error type value
> +  is defined in "available_error_type" description.
> +
> +- error_inject
> +  Write any integer to this file to trigger the error
> +  injection. Before this, please specify all necessary error
> +  parameters.
> +
> +For more information about EINJ, please refer to ACPI specification
> +version 4.0, section 17.5.
> --- a/Documentation/kernel-parameters.txt
> +++ b/Documentation/kernel-parameters.txt
> @@ -338,6 +338,11 @@ and is between 256 and 4096 characters. 
>  			not play well with APC CPU idle - disable it if you have
>  			APC and your system crashes randomly.
>  
> +	apei.hest_disable= [ACPI]
> +			Disable Hardware Error Source Table (HEST) support,
> +			corresponding firmware-first mode error processing
> +			logic will be disabled.
> +
>  	apic=		[APIC,X86-32] Advanced Programmable Interrupt Controller
>  			Change the output verbosity whilst booting
>  			Format: { quiet (default) | verbose | debug }
> 
> 

Re: [PATCH 5/5 -v2] acpi, apei, Document for APEI

[Huang Ying]

On Sat, 2009-12-12 at 00:58 +0800, Bjorn Helgaas wrote: 
> On Thursday 10 December 2009 12:17:04 am Huang Ying wrote:
> > Add document for APEI, including kernel parameters and EINJ debug file
> > sytem interface.
> 
> From a stylistic point of view, I think it's better if the
> documentation is added by the same patch that adds the functionality.
> Having them in separate patches means there's a point in time where
> the tree contains the functionality but not the documentation, or
> vice versa.

Sounds reasonable, I will change this.

Best Regards,
Huang Ying

Re: [PATCH 5/5 -v2] acpi, apei, Document for APEI

[Len Brown]

On Mon, 14 Dec 2009, Huang Ying wrote:

> On Sat, 2009-12-12 at 00:58 +0800, Bjorn Helgaas wrote: 
> > On Thursday 10 December 2009 12:17:04 am Huang Ying wrote:
> > > Add document for APEI, including kernel parameters and EINJ debug file
> > > sytem interface.
> > 
> > From a stylistic point of view, I think it's better if the
> > documentation is added by the same patch that adds the functionality.
> > Having them in separate patches means there's a point in time where
> > the tree contains the functionality but not the documentation, or
> > vice versa.
> 
> Sounds reasonable, I will change this.

I don't mind if the documentation preceeds or follows the code
in a patch series.  Personally, I'd probably put it in its own
patch like you did just as a lazy way to keep the patches small.
Anybody looking at this code will be looking at the whole series
and it isn't as if documentation is going to break bisect...

What I do mind from a patch submitting style point of view
is to start a series with [PATCH 2/5 -v2].

Please start with 0/5 explaining the difference between v1 and v2;
and then number staring with 1, not 2; else at first glance,
everybody thinks that the most important patch is missing...

That said, all this code is under its own config option,
making it relatively low risk.  The question is if there
would be a significant benefit to merging this code upstream
while we know there is still going to be some significant
movement in this area before it is fully baked...

(that would be another thing to describe in 0/5...)

thanks,
-Len Brown, Intel Open Source Technology Center

Re: [PATCH 5/5 -v2] acpi, apei, Document for APEI

[Huang Ying]

On Wed, 2009-12-16 at 12:32 +0800, Len Brown wrote: 
> On Mon, 14 Dec 2009, Huang Ying wrote:
> 
> > On Sat, 2009-12-12 at 00:58 +0800, Bjorn Helgaas wrote: 
> > > On Thursday 10 December 2009 12:17:04 am Huang Ying wrote:
> > > > Add document for APEI, including kernel parameters and EINJ debug file
> > > > sytem interface.
> > > 
> > > From a stylistic point of view, I think it's better if the
> > > documentation is added by the same patch that adds the functionality.
> > > Having them in separate patches means there's a point in time where
> > > the tree contains the functionality but not the documentation, or
> > > vice versa.
> > 
> > Sounds reasonable, I will change this.
> 
> I don't mind if the documentation preceeds or follows the code
> in a patch series.  Personally, I'd probably put it in its own
> patch like you did just as a lazy way to keep the patches small.
> Anybody looking at this code will be looking at the whole series
> and it isn't as if documentation is going to break bisect...
> 
> What I do mind from a patch submitting style point of view
> is to start a series with [PATCH 2/5 -v2].

Sorry, because of typo, the series start with [PATH 1/5 -v2], which
should be [PATCH 1/5 -v2].

> Please start with 0/5 explaining the difference between v1 and v2;
> and then number staring with 1, not 2; else at first glance,
> everybody thinks that the most important patch is missing...
> 
> That said, all this code is under its own config option,
> making it relatively low risk.  The question is if there
> would be a significant benefit to merging this code upstream
> while we know there is still going to be some significant
> movement in this area before it is fully baked...
> 
> (that would be another thing to describe in 0/5...)

OK. I will add 0/5 about difference between versions and why we need
this patchset. This patchset only provides basic support for APEI, some
important part such as ERST, HEST generic error source, BERT is still
missing because they are not finalized. But the code in this patchset
will not change significantly, further development will be incremental.

In this patchset, HEST table parsing code can be used by PCIE AER
initialization code to prevent touch PCIE root port in firmware first
mode. EINJ can be used to test some RAS related code such as MCE and
PCIE AER.

Best Regards,
Huang Ying