1# Introduction 2 3An attention is a hardware, firmware or software alert mechanism used to 4request service from an Attention Handler via an attention signal (e.g. a 5GPIO). An attention handler is, in this case, a stateless service that handles 6attention requests. The attention handler in combination with a hardware 7analyzer constitutes the Openpower Hardware Diagnostics (hardware diags) 8component. Hardware diags can operate in daemon mode and in application mode. 9When operating in daemon mode openpower hardware diags may be referred to as 10the attention handler or attention handler service. When operating in 11application mode openpower hardware diags may be referred to as the analyzer. 12Both modes executing simultaneously is supported however. There can be at most 13one instance of the attention handler service, per attention signal. 14 15# Overview 16 17The main role of the attention handler is a long running process monitoring the 18attention interrupt signal and delegating tasks to external components to aid 19in handling attention requests. The attention handler is loaded into memory 20when the host is started and monitors the attention signal until the host is 21stopped. When an attention (signal) is detected by the attention handler 22(monitor) the attention handler will query the state of the host to determine 23the nature of the active attention(s). 24 25The attention handler services four types of attentions namely, and in order of 26priority, Vital Attention (vital), Terminate Immediately (TI), Breakpoint 27Attention (BP) and Checkstop Attention (checkstop). TI and BP attentions are 28categorically called Special Attentions (special) and are mutually exclusive. 29Additionally a TI can be raised by either hostboot (HBTI) or the hypervisor 30(PHYPTI). 31 32The general handling of attentions is as follows: 33- vital: log an event, request a SBE dump and request a re-ipl of the host. 34- PHYPTI: log an event and request a memory preserving IPL (MPIPL) of the host. 35- HBTI: log an event, request a hardware dump and request a re-ipl of the host. 36- BP: notify the debug agent (e.g. Cronus) 37- checkstop: log an event, call the analyzer, request a system dump and request 38 a re-ipl of the host. 39 40# Implementation Details 41 42## External Components 43 44The attention handler relies on several external components and BMC services 45for the handling of attentions. Among these are systemd, dbus, phosphor-logging 46and PDBG. 47 48The general use of these components are as follows: 49- systemd: loading and unloading of the attention handler service. 50- dbus: querying the state of the BMC and host, requesting dumps and requesting 51 host IPL's 52- phosphor-logging: debug tracing and logging platform events. 53- PDBG: querying host hardware. 54 55## Component Usage 56 57- Platform Event Log (PEL) entry creation and debug tracing: phosphor-logging 58 component. 59- Host Transition (re-IPL, MPIPL request): dbus interface. 60- Attention handler starting and stopping: systemd. 61 62## Starting and Stopping 63 64The attention handler service is started via the BMC systemd infrastructure 65when the host is started. When the attention handler is started it will 66register itself as the GPIO event handler associated with the attention GPIO 67and remain resident in memory waiting for attentions. The attention handler 68will be stopped via the BMC systemd infrastructure when the host is stopped. 69 70If the attention handler terminates due to an error condition it will 71automatically be restarted by systemd. The attention handler restart policy is 72based on the BMC default restart policy (n-number of restarts in n-seconds 73maximum). 74 75## Attentions 76 77When the attention signal becomes active the attention handler will begin 78handling attentions. Using the PDBG interface the attention handler will query 79the host to determine the reason for the active attention handler signal. Each 80enabled processor will be queried and a map of active attentions will be 81created. The first attention of highest priority will be the one that is 82serviced (see Overview for attention type and priority). The Global Interrupt 83Status Register in combination with an associated attention mask register is 84used to determine active attentions. 85 86### Vital Attention 87 88A vital attention is handled by generating an event log via the 89phosphor-logging inteface and then using the dump manager dbus interface to 90request a hardware dump. The attention handler will wait, up to one hour, for 91the dump to complete and then use the systemd interface to request a re-IPL of 92the host. This type of attention indicates that there was a problem with the 93Self Boot Engine (SBE) hardware. 94 95### Special Attentions 96 97Three types of attentions, HBTI, PHYPTI and BP, share a single attention status 98flag (special attention) in the global interrupt status register. In order to 99determine the specific type of special attention the attention handler relies 100on a portion of shared memory called the Shared TI Information Data Area (TI 101info). The attention handler gains access to this memory region by submitting a 102request for its memory address through the PDBG interface. The request is via a 103Chip Operation (chipop) command. 104 105#### HBTI 106 107These attention types are indications from hostboot that an error has occurred 108or a shutdown has been requested. When servicing a HBTI the attention handler 109will consider two cases namely a TI with SRC and a TI with EID. 110 111For a TI with SRC, using the TI info, the attention handler will create and 112submit a PEL entry on behalf of hostboot, request a hostboot dump and upon 113completion, or timeout, request a re-IPL of the host using the dbus interface. 114Optionally, based upon flags in the TI info, the attention handler may mark the 115PEL entry as hidden. 116 117For a TI with EID, the attention handler will, based upon flags in the TI info, 118request a hostboot dump using the dbus interface. Upon completion, or timeout, 119of the dump the attention handler will request a re-IPL of the host via the 120dbus interface. For a TI with EID the attention handler will forgo creating a 121PEL entry (hostboot has already done this). 122 123#### PHYPTI 124 125These attentions are indications from the hypervisor that an error has 126occurred. When servicing a PHYPTI the attention handler will generate a PEL 127entry and then request a host MPIPL using the PDBG interface (chipop). 128 129#### BP (breakpoint) 130 131These attentions are used to signal to the attention handler that it should 132notify the debug agent (e.g. Cronus) that a debug breakpoint has been 133encountered. If the TI info data is considered valid and neither a HBTI or 134PHYPTI is determined to be the cause of the special attention then a BP 135attention is assumed. When a BP attention occurs the attention handler will use 136the dbus interface to notify the debug agent that a breakpoint condition was 137encountered. The attention handler will then go back to listening for 138attentions. 139 140#### Recoverables 141 142These attentions are indications that recoverable errors have been encountered. 143These attentions do not generate an attention GPIO event however when servicing 144a TI the attention handler will note whether or not the host is reporting 145recoverable errors. If recoverable errors are present the attention handler 146will call the analyzer before requesting a dump or IPL. The check for 147recoverable errors is done using the PDBG interface (the Global Interrupt 148Status Register). 149 150### Checkstop 151 152These attentions indicate that a hardware error has occurred and further 153hardware analyses is required to determine root cause. When servicing a 154checkstop attention the attention handler will call the analyzer and then wait 155for analyses to complete. Once analyses have completed the attention handler 156will use the dbus interface to request a system dump and upon completetion, or 157timeout, will request a re-IPL of the host. 158 159## Configuration 160 161Some attention handler behavior can be configured by passing parameters to the 162service using the service file or using the command line. Currently the 163following behaviors are configurable: 164- vital handling enable/disable, default enable 165- TI handling enable/disable, default enable 166- BP handling enable/disable, default enable 167- checkstop handling enable/disable, default enable 168- special attention default BP/TI, default BP 169 170## Additional Considerations 171 172Regardless of the type of special attention the attention handler will always 173create at least one PEL entry containing attention handler specific FFDC. In 174some cases this entry may be informational. 175 176Regardless of the type of attention, after servicing the attention the 177attention handler will return to listening for attentions. In most cases no 178more attentions will be detected unless the currently active attentions are 179cleared. Normally active attentions will be cleared by the host re-IPL but any 180component could clear the active attentions as is the case for BP attentions 181and the debug agent. 182 183If the attention handler encounters any errors while servicing an interrupt it 184will generate a PEL entry to indicate the error that was encountered. 185