APEI output format

APEI printk record envelope

APEI는 hardware error reporting interface로 `printk`를 사용한다. 하나의 generic hardware error record는 전체 severity와 하나 이상의 section으로 구성되며, 각 section에는 독립 severity·flags·FRU 식별자·section type·type별 data가 들어간다.

Record 첫 줄은 `APEI generic hardware error status`이고, 다음 줄의 `severity`는 integer와 문자열을 함께 표시한다. 이어지는 `section: <integer>`는 section 번호이며 그 section의 severity를 별도로 기록한다.

Section flags는 bitmask와 설정된 bit의 문자열 목록으로 출력된다. 가능한 의미는 primary, containment warning, reset, threshold exceeded, resource not accessible, latent error다. `fru_id`는 UUID, `fru_text`는 사람이 읽는 문자열이다.

Section type은 generic processor error, memory error, PCIe error 또는 `unknown, <uuid string>` 중 하나다. Type을 알면 뒤의 section data를 processor·memory·PCIe grammar로 해석하고, 알 수 없거나 payload가 없으면 null로 처리한다.

.. SPDX-License-Identifier: GPL-2.0

==================
APEI output format
==================

APEI uses printk as hardware error reporting interface, the output
format is as follow::

        <error record> :=
        APEI generic hardware error status
        severity: <integer>, <severity string>
        section: <integer>, severity: <integer>, <severity string>
        flags: <integer>
        <section flags strings>
        fru_id: <uuid string>
        fru_text: <string>
        section_type: <section type string>
        <section data>

        <severity string>* := recoverable | fatal | corrected | info

        <section flags strings># :=
        [primary][, containment warning][, reset][, threshold exceeded]\
        [, resource not accessible][, latent error]

        <section type string> := generic processor error | memory error | \
        PCIe error | unknown, <uuid string>

Generic processor section

Generic processor section의 모든 대괄호 field는 optional이다. `processor_type`은 IA32/X64 또는 IA64 계열을, `processor_isa`는 IA32·IA64·X64 instruction set을 integer index와 문자열로 나타낸다.

`error_type`은 cache, TLB, bus, micro-architectural error를 bitmask와 여러 줄의 문자열로 표시한다. `operation`은 unknown or generic, data read, data write, instruction execution 중 하나다.

Processor `flags`는 restartable, precise IP, overflow, corrected bit를 나타낸다. 나머지 optional scalar는 level, version_info, processor_id, target_address, requestor_id, responder_id와 instruction pointer인 `IP`다.

        <section data> :=
        <generic processor section data> | <memory section data> | \
        <pcie section data> | <null>

        <generic processor section data> :=
        [processor_type: <integer>, <proc type string>]
        [processor_isa: <integer>, <proc isa string>]
        [error_type: <integer>
        <proc error type strings>]
        [operation: <integer>, <proc operation string>]
        [flags: <integer>
        <proc flags strings>]
        [level: <integer>]
        [version_info: <integer>]
        [processor_id: <integer>]
        [target_address: <integer>]
        [requestor_id: <integer>]
        [responder_id: <integer>]
        [IP: <integer>]

        <proc type string>* := IA32/X64 | IA64

        <proc isa string>* := IA32 | IA64 | X64

        <processor error type strings># :=
        [cache error][, TLB error][, bus error][, micro-architectural error]

        <proc operation string>* := unknown or generic | data read | data write | \
        instruction execution

Memory section

Memory section도 각 field가 optional이다. `error_status`, `physical_address`, `physical_address_mask`가 error 상태와 address 범위를 나타내며, node·card·module·bank·device·row·column·bit_position이 memory topology와 정확한 location을 기술한다.

`requestor_id`, `responder_id`, `target_id`는 transaction participant를 식별한다. 마지막 `error_type`은 integer와 memory error type 문자열 하나를 함께 출력한다.

Memory error type은 unknown과 no error부터 single-bit·multi-bit ECC, chipkill ECC, abort, parity, timeout, invalid address, mirror·sparing, scrub result까지 순서가 정해진 enum이다. 원문의 `mirror Broken` 대소문자는 source에 그대로 보존한다.

        <proc flags strings># :=
        [restartable][, precise IP][, overflow][, corrected]

        <memory section data> :=
        [error_status: <integer>]
        [physical_address: <integer>]
        [physical_address_mask: <integer>]
        [node: <integer>]
        [card: <integer>]
        [module: <integer>]
        [bank: <integer>]
        [device: <integer>]
        [row: <integer>]
        [column: <integer>]
        [bit_position: <integer>]
        [requestor_id: <integer>]
        [responder_id: <integer>]
        [target_id: <integer>]
        [error_type: <integer>, <mem error type string>]

        <mem error type string>* :=
        unknown | no error | single-bit ECC | multi-bit ECC | \
        single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \
        target abort | parity error | watchdog timeout | invalid address | \
        mirror Broken | memory sparing | scrub corrected error | \
        scrub uncorrected error

        <pcie section data> :=

PCIe section과 port type

PCIe section은 `port_type`, PCIe version, command·status와 상세 device identity를 optional field로 출력한다. `device_id` 첫 줄은 segment:bus:device.function 형식이며 이어 slot, secondary_bus, vendor_id, device_id와 class_code가 붙는다.

추가 field에는 두 integer로 된 serial number와 bridge secondary_status·control이 있다. AER block은 aer_status·aer_mask, decoded status string, optional aer_uncor_severity, layer·agent, 네 DWORD의 TLP header를 포함한다.

`device_id`라는 label은 BDF tuple을 시작하는 바깥 field와 vendor_id 옆의 PCI device ID에 다시 등장하므로 현재 nested block 문맥으로 구분해야 한다. AER 역시 한 줄 record가 아니며 유효 field에 따라 여러 후속 줄이 선택적으로 붙는다.

        [port_type: <integer>, <pcie port type string>]
        [version: <integer>.<integer>]
        [command: <integer>, status: <integer>]
        [device_id: <integer>:<integer>:<integer>.<integer>
        slot: <integer>
        secondary_bus: <integer>
        vendor_id: <integer>, device_id: <integer>
        class_code: <integer>]
        [serial number: <integer>, <integer>]
        [bridge: secondary_status: <integer>, control: <integer>]
        [aer_status: <integer>, aer_mask: <integer>
        <aer status string>
        [aer_uncor_severity: <integer>]
        aer_layer=<aer layer string>, aer_agent=<aer agent string>
        aer_tlp_header: <integer> <integer> <integer> <integer>]

        <pcie port type string>* := PCIe end point | legacy PCI end point | \
        unknown | unknown | root port | upstream switch port | \
        downstream switch port | PCIe to PCI/PCI-X bridge | \
        PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \
        root complex event collector

        if section severity is fatal or recoverable
        <aer status string># :=
        unknown | unknown | unknown | unknown | Data Link Protocol | \
        unknown | unknown | unknown | unknown | unknown | unknown | unknown | \
        Poisoned TLP | Flow Control Protocol | Completion Timeout | \
        Completer Abort | Unexpected Completion | Receiver Overflow | \
        Malformed TLP | ECRC | Unsupported Request
        else
        <aer status string># :=

AER status·layer·agent decode

AER status 문자열은 section severity에 따라 서로 다른 bit table을 사용한다. Severity가 fatal 또는 recoverable이면 uncorrectable status mapping을, 그 밖의 corrected·info 문맥이면 correctable status mapping을 적용한다.

`aer_layer`는 Physical, Data Link, Transaction Layer 중 하나다. `aer_agent`는 Receiver ID, Requester ID, Completer ID, Transmitter ID 중 하나로 error를 관찰하거나 유발한 protocol participant 역할을 나타낸다.

        Receiver Error | unknown | unknown | unknown | unknown | unknown | \
        Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \
        Replay Timer Timeout | Advisory Non-Fatal
        fi

        <aer layer string> :=
        Physical Layer | Data Link Layer | Transaction Layer

        <aer agent string> :=
        Receiver ID | Requester ID | Completer ID | Transmitter ID

Where, [] designate corresponding content is optional

All <field string> description with * has the following format::

        field: <integer>, <field string>

Where value of <integer> should be the position of "string" in <field
string> description. Otherwise, <field string> will be "unknown".

Optional·enum·bitmask 표기 규칙

Grammar에서 대괄호 `[]`는 해당 내용이 optional임을 뜻한다. Field가 유효하지 않거나 error record에 포함되지 않으면 그 줄 전체가 생략될 수 있으므로 고정 line 수나 고정 위치만으로 parser를 작성하면 안 된다.

별표 `*`가 붙은 `<field string>`은 `field: <integer>, <field string>` 형식이다. Integer는 정의된 문자열 목록에서의 position이며 범위를 벗어나면 출력 문자열은 `unknown`이다.

샵 `#`가 붙은 `<field strings>`는 첫 줄에 `field: <integer>` bitmask를 출력하고 다음 줄에 설정된 각 bit에 대응하는 문자열들을 출력한다. Bit position은 정의된 문자열 목록에서의 position과 같다.

각 field의 상세 의미는 UEFI specification 2.3 이상 Appendix N `Common Platform Error Record`를 참고한다. Kernel log parser는 이 grammar와 함께 실제 CPER field validity bit와 specification version을 대조해야 한다.

All <field strings> description with # has the following format::

        field: <integer>
        <field strings>

Where each string in <fields strings> corresponding to one set bit of
<integer>. The bit position is the position of "string" in <field
strings> description.

For more detailed explanation of every field, please refer to UEFI
specification version 2.3 or later, section Appendix N: Common
Platform Error Record.