Documentation: ACPI: move apei/einj.txt to firmware-guide/acpi and convert to reST

.. 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)

the BIOS menu.

To use EINJ, make sure the following are options enabled in your kernel

configuration:

configuration::

  CONFIG_DEBUG_FS

  CONFIG_ACPI_APEI

  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

  0x00000200        Platform Correctable

  0x00000400        Platform Uncorrectable non-fatal

  0x00000800        Platform Uncorrectable fatal

  ================  ===================================

  The format of the file contents are as above, except present are only

  the available error types.

  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.

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;

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

	+-------------------------------------------------+

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

  # 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

   debug

   aml-debugger

   apei/output_format

   apei/einj

   gpio-properties

   i2c-muxes

   acpi-lid