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