1# OpenPower Platform Event Log (PEL) extension
2
3This extension will create PELs for every OpenBMC event log. It is also
4possible to point to the raw PEL to use in the OpenBMC event, and then that
5will be used instead of creating one.
6
7## Passing PEL related data within an OpenBMC event log
8
9An error log creator can pass in data that is relevant to a PEL by using
10certain keywords in the AdditionalData property of the event log.
11
12### AdditionalData keywords
13
14#### RAWPEL
15
16This keyword is used to point to an existing PEL in a binary file that should
17be associated with this event log.  The syntax is:
18```
19RAWPEL=<path to PEL File>
20e.g.
21RAWPEL="/tmp/pels/pel.5"
22```
23The code will assign its own error log ID to this PEL, and also update the
24commit timestamp field to the current time.
25
26#### ESEL
27
28This keyword's data contains a full PEL in string format.  This is how hostboot
29sends down PELs when it is configured in IPMI communication mode.  The PEL is
30handled just like the PEL obtained using the RAWPEL keyword.
31
32The syntax is:
33
34```
35ESEL=
36"00 00 df 00 00 00 00 20 00 04 12 01 6f aa 00 00 50 48 00 30 01 00 33 00 00..."
37```
38
39Note that there are 16 bytes of IPMI SEL data before the PEL data starts.
40
41#### _PID
42
43This keyword that contains the application's PID is added automatically by the
44phosphor-logging daemon when the `commit` or `report` APIs are used to create
45an event log, but not when the `Create` D-Bus method is used.  If a caller of
46the `Create` API wishes to have their PID captured in the PEL this should be
47used.
48
49This will be added to the PEL in a section of type User Data (UD), along with
50the application name it corresponds to.
51
52The syntax is:
53```
54_PID=<PID of application>
55e.g.
56_PID="12345"
57```
58
59#### CALLOUT_INVENTORY_PATH
60
61This is used to pass in an inventory item to use as a callout.  See [here for
62details](#passing-callouts-in-with-the-additionaldata-property)
63
64#### CALLOUT_DEVICE_PATH with CALLOUT_ERRNO
65
66This is used to pass in a device path to create callouts from.  See [here for
67details](#passing-callouts-in-with-the-additionaldata-property)
68
69#### CALLOUT_IIC_BUS with CALLOUT_IIC_ADDR and CALLOUT_ERRNO
70
71This is used to pass in an I2C bus and address to create callouts from.  See
72[here for details](#passing-callouts-in-with-the-additionaldata-property)
73
74## Default UserData sections for BMC created PELs
75
76The extension code that creates PELs will add these UserData sections to every
77PEL:
78
79- The AdditionalData property contents
80  - If the AdditionalData property in the OpenBMC event log has anything in it,
81    it will be saved in a UserData section as a JSON string.
82
83- System information
84  - This section contains various pieces of system information, such as the
85    full code level and the BMC, chassis, and host state properties.
86
87## The PEL Message Registry
88
89The PEL message registry is used to create PELs from OpenBMC event logs.
90Documentation can be found [here](registry/README.md).
91
92## Callouts
93
94A callout points to a FRU, a symbolic FRU, or an isolation procedure.  There
95can be from zero to ten of them in each PEL, where they are located in the SRC
96section.
97
98There are a few different ways to add callouts to a PEL:
99
100### Passing callouts in with the AdditionalData property
101
102The PEL code can add callouts based on the values of special entries in the
103AdditionalData event log property.  They are:
104
105- CALLOUT_INVENTORY_PATH
106
107    This keyword is used to call out a single FRU by passing in its D-Bus
108    inventory path.  When the PEL code sees this, it will create a single high
109    priority FRU callout, using the VPD properties (location code, FN, CCIN)
110    from that inventory item.  If that item is not a FRU itself and does not
111    have a location code, it will keep searching its parents until it finds one
112    that is.
113
114    ```
115    CALLOUT_INVENTORY_PATH=
116    "/xyz/openbmc_project/inventory/system/chassis/motherboard"
117    ```
118
119- CALLOUT_DEVICE_PATH with CALLOUT_ERRNO
120
121    These keywords are required as a pair to indicate faulty device
122    communication, usually detected by a failure accessing a device at that
123    sysfs path.  The PEL code will use a data table generated by the MRW to map
124    these device paths to FRU callout lists.  The errno value may influence the
125    callout.
126
127    TBD: Which exact types of device paths are supported.
128
129    ```
130    CALLOUT_DEVICE_PATH="/sys/bus/i2c/devices/3-0069"
131    CALLOUT_ERRNO="2"
132    ```
133
134- CALLOUT_IIC_BUS with CALLOUT_IIC_ADDR and CALLOUT_ERRNO
135
136    These 3 keywords can be used to callout a failing I2C device path when the
137    full device path isn't known.  It is similar to CALLOUT_DEVICE_PATH in that
138    it will use data tables generated by the MRW to create the callouts.
139
140    CALLOUT_IIC_BUS is in the form "/dev/i2c-X" where X is the bus number.
141    CALLOUT_IIC_ADDR is the 7 bit address either as a decimal or a hex number
142    if preceded with a "0x".
143
144    ```
145    CALLOUT_IIC_BUS="/dev/i2c-7"
146    CALLOUT_IIC_ADDR="81"
147    CALLOUT_ERRNO=62
148    ```
149
150### Defining callouts in the message registry
151
152Callouts can be completely defined inside that error's definition in the PEL
153message registry.  This method allows the callouts to vary based on the system
154type or on any AdditionalData item.
155
156At a high level, this involves defining a callout section inside the registry
157entry that contain the location codes or procedure names to use, along with
158their priority.  If these can vary based on system type, the type provided by
159the entity manager will be one of the keys.  If they can also depend on an
160AdditionalData entry, then that will also be a key.
161
162See the message registry [README](registry/README.md) and
163[schema](registry/schema/schema.json) for the details.
164
165### Using the message registry along with CALLOUT_ entries
166
167If the message registry entry contains a callout definition and the event log
168also contains one of aforementioned CALLOUT keys in the AdditionalData
169property, then the PEL code will first add the callouts stemming from the
170CALLOUT items, followed by the callouts from the message registry.
171
172### Using external callout tables
173
174Some applications, such as the code from the openpower-hw-diags repository,
175have their own callout tables that contain the callouts to use for the errors
176they generate.
177
178**TODO**:  The best way to pass these callouts in to the PEL creation code.
179
180## `Action Flags` and `Event Type` Rules
181
182The `Action Flags` and `Event Type` PEL fields are optional in the message
183registry, and if not present the code will set them based on certain rules
184layed out in the PEL spec.  In fact, even if they were specified, the checks
185are still done to ensure consistency across all the logs.
186
187These rules are:
1881. Always set the `Report` flag, unless the `Do Not Report` flag is already on.
1892. Always clear the `SP Call Home` flag, as that feature isn't supported.
1903. If the severity is `Non-error Event`:
191    - Clear the `Service Action` flag.
192    - Clear the `Call Home` flag.
193    - If the `Event Type` field is `Not Applicable`, change it to `Information
194      Only`.
195    - If the `Event Type` field is `Information Only` or `Tracing`, set the
196      `Hidden` flag.
1974. If the severity is `Recovered`:
198    - Set the `Hidden` flag.
199    - Clear the `Service Action` flag.
200    - Clear the `Call Home` flag.
2015. For all other severities:
202    - Clear the `Hidden` flag.
203    - Set the `Service Action` flag.
204    - Set the `Call Home` flag.
205
206Additional rules may be added in the future if necessary.
207
208## D-Bus Interfaces
209