1# Platform Event Log Message Registry 2On the BMC, PELs are created from the standard event logs provided by 3phosphor-logging using a message registry that provides the PEL related fields. 4The message registry is a JSON file. 5 6## Contents 7* [Component IDs](#component-ids) 8* [Message Registry](#message-registry-fields) 9 10## Component IDs 11A component ID is a 2 byte value of the form 0xYY00 used in a PEL to: 121. Provide the upper byte (the YY from above) of an SRC reason code in `BD` 13 SRCs. 142. Reside in the section header of the Private Header PEL section to specify 15 the error log creator's component ID. 163. Reside in the section header of the User Header section to specify the error 17 log committer's component ID. 184. Reside in the section header in the User Data section to specify which 19 parser to call to parse that section. 20 21Component IDs are specified in the message registry either as the upper byte of 22the SRC reason code field for `BD` SRCs, or in the standalone `ComponentID` 23field. 24 25Component IDs will be unique on a per-repository basis for errors unique to 26that repository. When the same errors are created by multiple repositories, 27those errors will all share the same component ID. The master list of 28component IDs is [here](ComponentIDs.md). 29 30## Message Registry Fields 31The message registry schema is [here](schema/schema.json), and the message 32registry itself is [here](message_registry.json). The schema will be validated 33either during a bitbake build or during CI, or eventually possibly both. 34 35In the message registry, there are fields for specifying: 36 37### Name 38This is the key into the message registry, and is the Message property 39of the OpenBMC event log that the PEL is being created from. 40 41``` 42"Name": "xyz.openbmc_project.Power.Fault" 43``` 44 45### Subsystem 46This field is part of the PEL User Header section, and is used to specify 47the subsystem pertaining to the error. It is an enumeration that maps to the 48actual PEL value. 49 50``` 51"Subsystem": "power_supply" 52``` 53 54### Severity 55This field is part of the PEL User Header section, and is used to specify 56the PEL severity. It is an optional field, if it isn't specified, then the 57severity of the OpenBMC event log will be converted into a PEL severity value. 58 59``` 60"Severity": "unrecoverable" 61``` 62 63### Mfg Severity 64This is an optional field and is used to override the Severity field when a 65specific manufacturing isolation mode is enabled. 66 67``` 68"MfgSeverity": "unrecoverable" 69``` 70 71### Event Scope 72This field is part of the PEL User Header section, and is used to specify 73the event scope, as defined by the PEL spec. It is optional and defaults to 74"entire platform". 75 76``` 77"EventScope": "entire_platform" 78``` 79 80### Event Type 81This field is part of the PEL User Header section, and is used to specify 82the event type, as defined by the PEL spec. It is optional and defaults to 83"not applicable" for non-informational logs, and "misc_information_only" for 84informational ones. 85 86``` 87"EventType": "na" 88``` 89 90### Action Flags 91This field is part of the PEL User Header section, and is used to specify the 92PEL action flags, as defined by the PEL spec. It is an array of enumerations. 93 94The action flags can usually be deduced from other PEL fields, such as the 95severity or if there are any callouts. As such, this is an optional field and 96if not supplied the code will fill them in based on those fields. 97 98In fact, even if supplied here, the code may still modify them to ensure they 99are correct. 100 101``` 102"ActionFlags": ["service_action", "report", "call_home"] 103``` 104 105### Mfg Action Flags 106This is an optional field and is used to override the Action Flags field when a 107specific manufacturing isolation mode is enabled. 108 109``` 110"MfgActionFlags": ["service_action", "report", "call_home"] 111``` 112 113### Component ID 114This is the component ID of the PEL creator, in the form 0xYY00. For `BD` 115SRCs, this is an optional field and if not present the value will be taken from 116the upper byte of the reason code. If present for `BD` SRCs, then this byte 117must match the upper byte of the reason code. 118 119``` 120"ComponentID": "0x5500" 121``` 122 123### SRC Type 124This specifies the type of SRC to create. The type is the first 2 characters 125of the 8 character ASCII string field of the PEL. The allowed types are `BD`, 126for the standard OpenBMC error, and `11`, for power related errors. It is 127optional and if not specified will default to `BD`. 128 129Note: The ASCII string for BD SRCs looks like: `BDBBCCCC`, where: 130* BD = SRC type 131* BB = PEL subsystem as mentioned above 132* CCCC SRC reason code 133 134For `11` SRCs, it looks like: `1100RRRR`, where RRRR is the SRC reason code. 135 136``` 137"Type": "11" 138``` 139 140### SRC Reason Code 141This is the 4 character value in the latter half of the SRC ASCII string. It 142is treated as a 2 byte hex value, such as 0x5678. For `BD` SRCs, the first 143byte is the same as the first byte of the component ID field in the Private 144Header section that represents the creator's component ID. 145 146``` 147"ReasonCode": "0x5544" 148``` 149 150### SRC Symptom ID Fields 151The symptom ID is in the Extended User Header section and is defined in the PEL 152spec as the unique event signature string. It always starts with the ASCII 153string. This field in the message registry allows one to choose which SRC words 154to use in addition to the ASCII string field to form the symptom ID. All words 155are separated by underscores. If not specified, the code will choose a default 156format, which may depend on the SRC type. 157 158For example: ["SRCWord3", "SRCWord9"] would be: 159`<ASCII_STRING>_<SRCWord3>_<SRCWord9>`, which could look like: 160`B181320_00000050_49000000`. 161 162``` 163"SymptomIDFields": ["SRCWord3", "SRCWord9"] 164``` 165 166### SRC words 6 to 9 167In a PEL, these SRC words are free format and can be filled in by the user as 168desired. On the BMC, the source of these words is the AdditionalData fields in 169the event log. The message registry provides a way for the log creator to 170specify which AdditionalData property field to get the data from, and also to 171define what the SRC word means for use by parsers. If not specified, these SRC 172words will be set to zero in the PEL. 173 174``` 175"Words6to9": 176{ 177 "6": 178 { 179 "description": "Failing unit number", 180 "AdditionalDataPropSource": "PS_NUM" 181 } 182} 183``` 184 185### SRC Power Fault flag 186The SRC has a bit in it to indicate if the error is a power fault. This is an 187optional field in the message registry and defaults to false. 188 189``` 190"PowerFault: false 191``` 192 193### Documentation Fields 194The documentation fields are used by PEL parsers to display a human readable 195description of a PEL. They are also the source for the Redfish event log 196messages. 197 198#### Message 199This field is used by the BMC's PEL parser as the description of the error log. 200It will also be used in Redfish event logs. It supports argument substitution 201using the %1, %2, etc placeholders allowing any of the SRC user data words 6 - 2029 to be displayed as part of the message. If the placeholders are used, then 203the `MessageArgSources` property must be present to say which SRC words to use 204for each placeholder. 205 206``` 207"Message": "Processor %1 had %2 errors" 208``` 209 210#### MessageArgSources 211This optional field is required when the Message field contains the %X 212placeholder arguments. It is an array that says which SRC words to get the 213placeholders from. In the example below, SRC word 6 would be used for %1, and 214SRC word 7 for %2. 215 216``` 217"MessageArgSources": 218[ 219 "SRCWord6", "SRCWord7" 220] 221``` 222 223#### Description 224A short description of the error. This is required by the Redfish schema to generate a Redfish message entry, but is not used in Redfish or PEL output. 225 226``` 227"Description": "A power fault" 228``` 229 230#### Notes 231This is an optional free format text field for keeping any notes for the 232registry entry, as comments are not allowed in JSON. It is an array of strings 233for easier readability of long fields. 234 235``` 236"Notes": [ 237 "This entry is for every type of power fault.", 238 "There is probably a hardware failure." 239] 240``` 241 242### Callout Fields 243The callout fields allow one to specify the PEL callouts (either a hardware 244FRU, a symbolic FRU, or a maintenance procedure) in the entry for a particular 245error. These callouts can vary based on system type, as well as a user 246specified AdditionalData property field. Callouts will be added to the PEL in 247the order they are listed in the JSON. If a callout is passed into the error, 248say with CALLOUT_INVENTORY_PATH, then that callout will be added to the PEL 249before the callouts in the registry. 250 251There is room for up to 10 callouts in a PEL. 252 253#### Callouts example based on the system type 254 255``` 256"Callouts": 257[ 258 { 259 "System": "system1", 260 "CalloutList": 261 [ 262 { 263 "Priority": "high", 264 "LocCode": "P1-C1" 265 }, 266 { 267 "Priority": "low", 268 "LocCode": "P1" 269 } 270 ] 271 }, 272 { 273 "CalloutList": 274 [ 275 { 276 "Priority": "high", 277 "Procedure": "SVCDOCS" 278 } 279 ] 280 281 } 282] 283 284``` 285 286The above example shows that on system 'system1', the FRU at location P1-C1 287will be called out with a priority of high, and the FRU at P1 with a priority 288of low. On every other system, the maintenance procedure SVCDOCS is called 289out. 290 291#### Callouts example based on an AdditionalData field 292 293``` 294"CalloutsUsingAD": 295{ 296 "ADName": "PROC_NUM", 297 "CalloutsWithTheirADValues": 298 [ 299 { 300 "ADValue": "0", 301 "Callouts": 302 [ 303 { 304 "CalloutList": 305 [ 306 { 307 "Priority": "high", 308 "LocCode": "P1-C5" 309 } 310 ] 311 } 312 ] 313 }, 314 { 315 "ADValue": "1", 316 "Callouts": 317 [ 318 { 319 "CalloutList": 320 [ 321 { 322 "Priority": "high", 323 "LocCode": "P1-C6" 324 } 325 ] 326 } 327 ] 328 } 329 ] 330} 331 332``` 333 334This example shows that the callouts were selected based on the 'PROC_NUM' 335AdditionalData field. When PROC_NUM was 0, the FRU at P1-C5 was called out. 336When it was 1, P1-C6 was called out. Note that the same 'Callouts' array is 337used as in the previous example, so these callouts can also depend on the 338system type. 339 340#### CalloutType 341This field can be used to modify the failing component type field in the 342callout when the default doesn\'t fit: 343 344``` 345{ 346 347 "Priority": "high", 348 "Procedure": "FIXIT22" 349 "CalloutType": "config_procedure" 350} 351``` 352 353The defaults are: 354- Normal hardware FRU: hardware_fru 355- Symbolic FRU: symbolic_fru 356- Procedure: maint_procedure 357