1a96a7948SMatt Spinler# Platform Event Log Message Registry 226919f07SPatrick Williams 3a96a7948SMatt SpinlerOn the BMC, PELs are created from the standard event logs provided by 4a96a7948SMatt Spinlerphosphor-logging using a message registry that provides the PEL related fields. 5a96a7948SMatt SpinlerThe message registry is a JSON file. 6a96a7948SMatt Spinler 7a96a7948SMatt Spinler## Contents 826919f07SPatrick Williams 926919f07SPatrick Williams- [Component IDs](#component-ids) 1026919f07SPatrick Williams- [Message Registry](#message-registry-fields) 1126919f07SPatrick Williams- [Modifying and Testing](#modifying-and-testing) 12a96a7948SMatt Spinler 13a96a7948SMatt Spinler## Component IDs 1426919f07SPatrick Williams 15a96a7948SMatt SpinlerA component ID is a 2 byte value of the form 0xYY00 used in a PEL to: 1626919f07SPatrick Williams 17a96a7948SMatt Spinler1. Provide the upper byte (the YY from above) of an SRC reason code in `BD` 18a96a7948SMatt Spinler SRCs. 1926919f07SPatrick Williams2. Reside in the section header of the Private Header PEL section to specify the 2026919f07SPatrick Williams error log creator's component ID. 21a96a7948SMatt Spinler3. Reside in the section header of the User Header section to specify the error 22a96a7948SMatt Spinler log committer's component ID. 2326919f07SPatrick Williams4. Reside in the section header in the User Data section to specify which parser 2426919f07SPatrick Williams to call to parse that section. 25a96a7948SMatt Spinler 26a96a7948SMatt SpinlerComponent IDs are specified in the message registry either as the upper byte of 27a96a7948SMatt Spinlerthe SRC reason code field for `BD` SRCs, or in the standalone `ComponentID` 28a96a7948SMatt Spinlerfield. 29a96a7948SMatt Spinler 3026919f07SPatrick WilliamsComponent IDs will be unique on a per-repository basis for errors unique to that 3126919f07SPatrick Williamsrepository. When the same errors are created by multiple repositories, those 3226919f07SPatrick Williamserrors will all share the same component ID. The master list of component IDs is 3326919f07SPatrick Williams[here](O_component_ids.json). That file can used by PEL parsers to display a 3426919f07SPatrick Williamsname for the component ID. The 'O' in the name is the creator ID value for BMC 3526919f07SPatrick Williamscreated PELs. 36a96a7948SMatt Spinler 37a96a7948SMatt Spinler## Message Registry Fields 3826919f07SPatrick Williams 39a96a7948SMatt SpinlerThe message registry schema is [here](schema/schema.json), and the message 40a96a7948SMatt Spinlerregistry itself is [here](message_registry.json). The schema will be validated 41a96a7948SMatt Spinlereither during a bitbake build or during CI, or eventually possibly both. 42a96a7948SMatt Spinler 43a96a7948SMatt SpinlerIn the message registry, there are fields for specifying: 44a96a7948SMatt Spinler 45a96a7948SMatt Spinler### Name 4626919f07SPatrick Williams 4726919f07SPatrick WilliamsThis is the key into the message registry, and is the Message property of the 4826919f07SPatrick WilliamsOpenBMC event log that the PEL is being created from. 49a96a7948SMatt Spinler 50a6c48787SMatt Spinler```json 51a96a7948SMatt Spinler"Name": "xyz.openbmc_project.Power.Fault" 52a96a7948SMatt Spinler``` 53a96a7948SMatt Spinler 54a96a7948SMatt Spinler### Subsystem 5526919f07SPatrick Williams 5626919f07SPatrick WilliamsThis field is part of the PEL User Header section, and is used to specify the 5726919f07SPatrick Williamssubsystem pertaining to the error. It is an enumeration that maps to the actual 5826919f07SPatrick WilliamsPEL value. If the subsystem isn't known ahead of time, it can be passed in at 5926919f07SPatrick Williamsthe time of PEL creation using the 'PEL_SUBSYSTEM' AdditionalData field. In this 6026919f07SPatrick Williamscase, 'Subsystem' isn't required, though 'PossibleSubsystems' is. 61a96a7948SMatt Spinler 62a6c48787SMatt Spinler```json 63a96a7948SMatt Spinler"Subsystem": "power_supply" 64a96a7948SMatt Spinler``` 65a96a7948SMatt Spinler 6623970b0dSMatt Spinler### PossibleSubsystems 6726919f07SPatrick Williams 6826919f07SPatrick WilliamsThis field is used by scripts that build documentation from the message registry 6926919f07SPatrick Williamsto know which subsystems are possible for an error when it can't be hardcoded 7026919f07SPatrick Williamsusing the 'Subsystem' field. It is mutually exclusive with the 'Subsystem' 7126919f07SPatrick Williamsfield. 7223970b0dSMatt Spinler 73a6c48787SMatt Spinler```json 7423970b0dSMatt Spinler"PossibleSubsystems": ["memory", "processor"] 7523970b0dSMatt Spinler``` 7623970b0dSMatt Spinler 77a96a7948SMatt Spinler### Severity 7826919f07SPatrick Williams 7926919f07SPatrick WilliamsThis field is part of the PEL User Header section, and is used to specify the 8026919f07SPatrick WilliamsPEL severity. It is an optional field, if it isn't specified, then the severity 8126919f07SPatrick Williamsof the OpenBMC event log will be converted into a PEL severity value. 82a96a7948SMatt Spinler 8317952d94SMatt SpinlerIt can either be the plain severity value, or an array of severity values that 8417952d94SMatt Spinlerare based on system type, where an entry without a system type will match 8517952d94SMatt Spinleranything unless another entry has a matching system type. 8617952d94SMatt Spinler 87a6c48787SMatt Spinler```json 88a96a7948SMatt Spinler"Severity": "unrecoverable" 89a96a7948SMatt Spinler``` 90a96a7948SMatt Spinler 91a6c48787SMatt Spinler```json 9217952d94SMatt SpinlerSeverity": 9317952d94SMatt Spinler[ 9417952d94SMatt Spinler { 9517952d94SMatt Spinler "System": "system1", 9617952d94SMatt Spinler "SevValue": "recovered" 9717952d94SMatt Spinler }, 9817952d94SMatt Spinler { 9917952d94SMatt Spinler "Severity": "unrecoverable" 10017952d94SMatt Spinler } 10117952d94SMatt Spinler] 10217952d94SMatt Spinler``` 10326919f07SPatrick Williams 10426919f07SPatrick WilliamsThe above example shows that on system 'system1' the severity will be recovered, 10526919f07SPatrick Williamsand on every other system it will be unrecoverable. 10617952d94SMatt Spinler 107a96a7948SMatt Spinler### Mfg Severity 10826919f07SPatrick Williams 109a96a7948SMatt SpinlerThis is an optional field and is used to override the Severity field when a 11017952d94SMatt Spinlerspecific manufacturing isolation mode is enabled. It has the same format as 11117952d94SMatt SpinlerSeverity. 112a96a7948SMatt Spinler 113a6c48787SMatt Spinler```json 114a96a7948SMatt Spinler"MfgSeverity": "unrecoverable" 115a96a7948SMatt Spinler``` 116a96a7948SMatt Spinler 117a96a7948SMatt Spinler### Event Scope 11826919f07SPatrick Williams 11926919f07SPatrick WilliamsThis field is part of the PEL User Header section, and is used to specify the 12026919f07SPatrick Williamsevent scope, as defined by the PEL spec. It is optional and defaults to "entire 12126919f07SPatrick Williamsplatform". 122a96a7948SMatt Spinler 123a6c48787SMatt Spinler```json 124a96a7948SMatt Spinler"EventScope": "entire_platform" 125a96a7948SMatt Spinler``` 126a96a7948SMatt Spinler 127a96a7948SMatt Spinler### Event Type 12826919f07SPatrick Williams 12926919f07SPatrick WilliamsThis field is part of the PEL User Header section, and is used to specify the 13026919f07SPatrick Williamsevent type, as defined by the PEL spec. It is optional and defaults to "not 13126919f07SPatrick Williamsapplicable" for non-informational logs, and "misc_information_only" for 1323fb208e3SMatt Spinlerinformational ones. 133a96a7948SMatt Spinler 134a6c48787SMatt Spinler```json 135a96a7948SMatt Spinler"EventType": "na" 136a96a7948SMatt Spinler``` 137a96a7948SMatt Spinler 138a96a7948SMatt Spinler### Action Flags 13926919f07SPatrick Williams 140a96a7948SMatt SpinlerThis field is part of the PEL User Header section, and is used to specify the 141a96a7948SMatt SpinlerPEL action flags, as defined by the PEL spec. It is an array of enumerations. 142a96a7948SMatt Spinler 1433fb208e3SMatt SpinlerThe action flags can usually be deduced from other PEL fields, such as the 14426919f07SPatrick Williamsseverity or if there are any callouts. As such, this is an optional field and if 14526919f07SPatrick Williamsnot supplied the code will fill them in based on those fields. 1463fb208e3SMatt Spinler 1473fb208e3SMatt SpinlerIn fact, even if supplied here, the code may still modify them to ensure they 14878feef04SMatt Spinlerare correct. The rules used for this are 14978feef04SMatt Spinler[here](../README.md#action-flags-and-event-type-rules). 1503fb208e3SMatt Spinler 151a6c48787SMatt Spinler```json 152a96a7948SMatt Spinler"ActionFlags": ["service_action", "report", "call_home"] 153a96a7948SMatt Spinler``` 154a96a7948SMatt Spinler 155a96a7948SMatt Spinler### Mfg Action Flags 15626919f07SPatrick Williams 157a96a7948SMatt SpinlerThis is an optional field and is used to override the Action Flags field when a 158a96a7948SMatt Spinlerspecific manufacturing isolation mode is enabled. 159a96a7948SMatt Spinler 160a6c48787SMatt Spinler```json 161a96a7948SMatt Spinler"MfgActionFlags": ["service_action", "report", "call_home"] 162a96a7948SMatt Spinler``` 163a96a7948SMatt Spinler 164a96a7948SMatt Spinler### Component ID 16526919f07SPatrick Williams 16626919f07SPatrick WilliamsThis is the component ID of the PEL creator, in the form 0xYY00. For `BD` SRCs, 16726919f07SPatrick Williamsthis is an optional field and if not present the value will be taken from the 16826919f07SPatrick Williamsupper byte of the reason code. If present for `BD` SRCs, then this byte must 16926919f07SPatrick Williamsmatch the upper byte of the reason code. 170a96a7948SMatt Spinler 171a6c48787SMatt Spinler```json 172a96a7948SMatt Spinler"ComponentID": "0x5500" 173a96a7948SMatt Spinler``` 174a96a7948SMatt Spinler 175a96a7948SMatt Spinler### SRC Type 17626919f07SPatrick Williams 17726919f07SPatrick WilliamsThis specifies the type of SRC to create. The type is the first 2 characters of 17826919f07SPatrick Williamsthe 8 character ASCII string field of the PEL. The allowed types are `BD`, for 17926919f07SPatrick Williamsthe standard OpenBMC error, and `11`, for power related errors. It is optional 18026919f07SPatrick Williamsand if not specified will default to `BD`. 181a96a7948SMatt Spinler 182a96a7948SMatt SpinlerNote: The ASCII string for BD SRCs looks like: `BDBBCCCC`, where: 18326919f07SPatrick Williams 18426919f07SPatrick Williams- BD = SRC type 18526919f07SPatrick Williams- BB = PEL subsystem as mentioned above 18626919f07SPatrick Williams- CCCC SRC reason code 187a96a7948SMatt Spinler 188a96a7948SMatt SpinlerFor `11` SRCs, it looks like: `1100RRRR`, where RRRR is the SRC reason code. 189a96a7948SMatt Spinler 190a6c48787SMatt Spinler```json 191a96a7948SMatt Spinler"Type": "11" 192a96a7948SMatt Spinler``` 193a96a7948SMatt Spinler 194a96a7948SMatt Spinler### SRC Reason Code 19526919f07SPatrick Williams 19626919f07SPatrick WilliamsThis is the 4 character value in the latter half of the SRC ASCII string. It is 19726919f07SPatrick Williamstreated as a 2 byte hex value, such as 0x5678. For `BD` SRCs, the first byte is 19826919f07SPatrick Williamsthe same as the first byte of the component ID field in the Private Header 19926919f07SPatrick Williamssection that represents the creator's component ID. 200a96a7948SMatt Spinler 201a6c48787SMatt Spinler```json 202a96a7948SMatt Spinler"ReasonCode": "0x5544" 203a96a7948SMatt Spinler``` 204a96a7948SMatt Spinler 205a96a7948SMatt Spinler### SRC Symptom ID Fields 20626919f07SPatrick Williams 207a96a7948SMatt SpinlerThe symptom ID is in the Extended User Header section and is defined in the PEL 208a96a7948SMatt Spinlerspec as the unique event signature string. It always starts with the ASCII 209a96a7948SMatt Spinlerstring. This field in the message registry allows one to choose which SRC words 210a96a7948SMatt Spinlerto use in addition to the ASCII string field to form the symptom ID. All words 211a96a7948SMatt Spinlerare separated by underscores. If not specified, the code will choose a default 212a96a7948SMatt Spinlerformat, which may depend on the SRC type. 213a96a7948SMatt Spinler 214a96a7948SMatt SpinlerFor example: ["SRCWord3", "SRCWord9"] would be: 215a96a7948SMatt Spinler`<ASCII_STRING>_<SRCWord3>_<SRCWord9>`, which could look like: 216a96a7948SMatt Spinler`B181320_00000050_49000000`. 217a96a7948SMatt Spinler 218a6c48787SMatt Spinler```json 219a96a7948SMatt Spinler"SymptomIDFields": ["SRCWord3", "SRCWord9"] 220a96a7948SMatt Spinler``` 221a96a7948SMatt Spinler 222a96a7948SMatt Spinler### SRC words 6 to 9 22326919f07SPatrick Williams 224a96a7948SMatt SpinlerIn a PEL, these SRC words are free format and can be filled in by the user as 225a96a7948SMatt Spinlerdesired. On the BMC, the source of these words is the AdditionalData fields in 226a96a7948SMatt Spinlerthe event log. The message registry provides a way for the log creator to 227a96a7948SMatt Spinlerspecify which AdditionalData property field to get the data from, and also to 228a96a7948SMatt Spinlerdefine what the SRC word means for use by parsers. If not specified, these SRC 229a96a7948SMatt Spinlerwords will be set to zero in the PEL. 230a96a7948SMatt Spinler 231a6c48787SMatt Spinler```json 232a96a7948SMatt Spinler"Words6to9": 233a96a7948SMatt Spinler{ 234a96a7948SMatt Spinler "6": 235a96a7948SMatt Spinler { 236a96a7948SMatt Spinler "description": "Failing unit number", 237a96a7948SMatt Spinler "AdditionalDataPropSource": "PS_NUM" 238a96a7948SMatt Spinler } 239a96a7948SMatt Spinler} 240a96a7948SMatt Spinler``` 241a96a7948SMatt Spinler 2423fe93e96SMatt Spinler### SRC Deconfig Flag 2433fe93e96SMatt Spinler 2443fe93e96SMatt SpinlerBit 6 in hex word 5 of the SRC means that one or more called out resources have 2453fe93e96SMatt Spinlerbeen deconfigured, and this flag can be used to set that bit. The only other way 2463fe93e96SMatt Spinlerto set it is by indicating it when 2473fe93e96SMatt Spinler[passing in the callouts via JSON](../README.md#callouts). 2483fe93e96SMatt Spinler 2493fe93e96SMatt SpinlerThis is looked at by the software that creates the periodic PELs that indicate a 2503fe93e96SMatt Spinlersystem is running with deconfigured hardware. 2513fe93e96SMatt Spinler 2523fe93e96SMatt Spinler```json 2533fe93e96SMatt Spinler"DeconfigFlag": true 2543fe93e96SMatt Spinler``` 2553fe93e96SMatt Spinler 256da5b76b2SMatt Spinler### SRC Checkstop Flag 257da5b76b2SMatt Spinler 258da5b76b2SMatt SpinlerThis is used to indicate the PEL is for a hardware checkstop, and causes bit 0 259da5b76b2SMatt Spinlerin hex word 5 of the SRC to be set. 260da5b76b2SMatt Spinler 261da5b76b2SMatt Spinler```json 262da5b76b2SMatt Spinler"CheckstopFlag": true 263da5b76b2SMatt Spinler``` 264da5b76b2SMatt Spinler 265a96a7948SMatt Spinler### Documentation Fields 26626919f07SPatrick Williams 267a96a7948SMatt SpinlerThe documentation fields are used by PEL parsers to display a human readable 268a96a7948SMatt Spinlerdescription of a PEL. They are also the source for the Redfish event log 269a96a7948SMatt Spinlermessages. 270a96a7948SMatt Spinler 271a96a7948SMatt Spinler#### Message 27226919f07SPatrick Williams 273a96a7948SMatt SpinlerThis field is used by the BMC's PEL parser as the description of the error log. 274a96a7948SMatt SpinlerIt will also be used in Redfish event logs. It supports argument substitution 27526919f07SPatrick Williamsusing the %1, %2, etc placeholders allowing any of the SRC user data words 6 - 9 27626919f07SPatrick Williamsto be displayed as part of the message. If the placeholders are used, then the 27726919f07SPatrick Williams`MessageArgSources` property must be present to say which SRC words to use for 27826919f07SPatrick Williamseach placeholder. 279a96a7948SMatt Spinler 280a6c48787SMatt Spinler```json 281a96a7948SMatt Spinler"Message": "Processor %1 had %2 errors" 282a96a7948SMatt Spinler``` 283a96a7948SMatt Spinler 284a96a7948SMatt Spinler#### MessageArgSources 28526919f07SPatrick Williams 286a96a7948SMatt SpinlerThis optional field is required when the Message field contains the %X 287a96a7948SMatt Spinlerplaceholder arguments. It is an array that says which SRC words to get the 288a96a7948SMatt Spinlerplaceholders from. In the example below, SRC word 6 would be used for %1, and 289a96a7948SMatt SpinlerSRC word 7 for %2. 290a96a7948SMatt Spinler 291a6c48787SMatt Spinler```json 292a96a7948SMatt Spinler"MessageArgSources": 293a96a7948SMatt Spinler[ 294a96a7948SMatt Spinler "SRCWord6", "SRCWord7" 295a96a7948SMatt Spinler] 296a96a7948SMatt Spinler``` 297a96a7948SMatt Spinler 298a96a7948SMatt Spinler#### Description 29926919f07SPatrick Williams 30026919f07SPatrick WilliamsA short description of the error. This is required by the Redfish schema to 30126919f07SPatrick Williamsgenerate a Redfish message entry, but is not used in Redfish or PEL output. 302a96a7948SMatt Spinler 303a6c48787SMatt Spinler```json 304a96a7948SMatt Spinler"Description": "A power fault" 305a96a7948SMatt Spinler``` 306a96a7948SMatt Spinler 307a96a7948SMatt Spinler#### Notes 30826919f07SPatrick Williams 309a96a7948SMatt SpinlerThis is an optional free format text field for keeping any notes for the 310a96a7948SMatt Spinlerregistry entry, as comments are not allowed in JSON. It is an array of strings 311a96a7948SMatt Spinlerfor easier readability of long fields. 312a96a7948SMatt Spinler 313a6c48787SMatt Spinler```json 314a96a7948SMatt Spinler"Notes": [ 315a96a7948SMatt Spinler "This entry is for every type of power fault.", 316a96a7948SMatt Spinler "There is probably a hardware failure." 317a96a7948SMatt Spinler] 318a96a7948SMatt Spinler``` 31970311203SMatt Spinler 32070311203SMatt Spinler### Callout Fields 32126919f07SPatrick Williams 32226919f07SPatrick WilliamsThe callout fields allow one to specify the PEL callouts (either a hardware FRU, 32326919f07SPatrick Williamsa symbolic FRU, or a maintenance procedure) in the entry for a particular error. 32426919f07SPatrick WilliamsThese callouts can vary based on system type, as well as a user specified 32526919f07SPatrick WilliamsAdditionalData property field. Callouts will be added to the PEL in the order 32626919f07SPatrick Williamsthey are listed in the JSON. If a callout is passed into the error, say with 32726919f07SPatrick WilliamsCALLOUT_INVENTORY_PATH, then that callout will be added to the PEL before the 32826919f07SPatrick Williamscallouts in the registry. 32970311203SMatt Spinler 33070311203SMatt SpinlerThere is room for up to 10 callouts in a PEL. 33170311203SMatt Spinler 332*2edce4e2SMatt SpinlerAvailable maintenance procedures are listed [here][1] and in the source code 333*2edce4e2SMatt Spinler[here][2]. 334*2edce4e2SMatt Spinler 335*2edce4e2SMatt Spinler[1]: 336*2edce4e2SMatt Spinler https://github.com/ibm-openbmc/openpower-pel-parsers/blob/master/modules/calloutparsers/ocallouts/ocallouts.py 337*2edce4e2SMatt Spinler[2]: 338*2edce4e2SMatt Spinler https://github.com/openbmc/phosphor-logging/blob/master/extensions/openpower-pels/pel_values.cpp 339*2edce4e2SMatt Spinler 340*2edce4e2SMatt SpinlerIf a procedure is needed that doesn't exist yet, please contact the owner of 341*2edce4e2SMatt Spinlerthis code for instructions. 342*2edce4e2SMatt Spinler 34370311203SMatt Spinler#### Callouts example based on the system type 34470311203SMatt Spinler 345a6c48787SMatt Spinler```json 34670311203SMatt Spinler"Callouts": 34770311203SMatt Spinler[ 34870311203SMatt Spinler { 34970311203SMatt Spinler "System": "system1", 35070311203SMatt Spinler "CalloutList": 35170311203SMatt Spinler [ 35270311203SMatt Spinler { 35370311203SMatt Spinler "Priority": "high", 35470311203SMatt Spinler "LocCode": "P1-C1" 35570311203SMatt Spinler }, 35670311203SMatt Spinler { 35770311203SMatt Spinler "Priority": "low", 35870311203SMatt Spinler "LocCode": "P1" 35970311203SMatt Spinler } 36070311203SMatt Spinler ] 36170311203SMatt Spinler }, 36270311203SMatt Spinler { 36370311203SMatt Spinler "CalloutList": 36470311203SMatt Spinler [ 36570311203SMatt Spinler { 36670311203SMatt Spinler "Priority": "high", 367*2edce4e2SMatt Spinler "Procedure": "BMC0002" 36870311203SMatt Spinler } 36970311203SMatt Spinler ] 37070311203SMatt Spinler 37170311203SMatt Spinler } 37270311203SMatt Spinler] 37370311203SMatt Spinler 37470311203SMatt Spinler``` 37570311203SMatt Spinler 37626919f07SPatrick WilliamsThe above example shows that on system 'system1', the FRU at location P1-C1 will 37726919f07SPatrick Williamsbe called out with a priority of high, and the FRU at P1 with a priority of low. 378*2edce4e2SMatt SpinlerOn every other system, the maintenance procedure BMC0002 is called out. 37970311203SMatt Spinler 38070311203SMatt Spinler#### Callouts example based on an AdditionalData field 38170311203SMatt Spinler 382a6c48787SMatt Spinler```json 38370311203SMatt Spinler"CalloutsUsingAD": 38470311203SMatt Spinler{ 38570311203SMatt Spinler "ADName": "PROC_NUM", 38670311203SMatt Spinler "CalloutsWithTheirADValues": 38770311203SMatt Spinler [ 38870311203SMatt Spinler { 38970311203SMatt Spinler "ADValue": "0", 39070311203SMatt Spinler "Callouts": 39170311203SMatt Spinler [ 39270311203SMatt Spinler { 39370311203SMatt Spinler "CalloutList": 39470311203SMatt Spinler [ 39570311203SMatt Spinler { 39670311203SMatt Spinler "Priority": "high", 39770311203SMatt Spinler "LocCode": "P1-C5" 39870311203SMatt Spinler } 39970311203SMatt Spinler ] 40070311203SMatt Spinler } 40170311203SMatt Spinler ] 40270311203SMatt Spinler }, 40370311203SMatt Spinler { 40470311203SMatt Spinler "ADValue": "1", 40570311203SMatt Spinler "Callouts": 40670311203SMatt Spinler [ 40770311203SMatt Spinler { 40870311203SMatt Spinler "CalloutList": 40970311203SMatt Spinler [ 41070311203SMatt Spinler { 41170311203SMatt Spinler "Priority": "high", 41270311203SMatt Spinler "LocCode": "P1-C6" 41370311203SMatt Spinler } 41470311203SMatt Spinler ] 41570311203SMatt Spinler } 41670311203SMatt Spinler ] 41770311203SMatt Spinler } 41870311203SMatt Spinler ] 41970311203SMatt Spinler} 42070311203SMatt Spinler 42170311203SMatt Spinler``` 42270311203SMatt Spinler 42370311203SMatt SpinlerThis example shows that the callouts were selected based on the 'PROC_NUM' 42426919f07SPatrick WilliamsAdditionalData field. When PROC_NUM was 0, the FRU at P1-C5 was called out. When 42526919f07SPatrick Williamsit was 1, P1-C6 was called out. Note that the same 'Callouts' array is used as 42626919f07SPatrick Williamsin the previous example, so these callouts can also depend on the system type. 42770311203SMatt Spinler 42826919f07SPatrick WilliamsIf it's desired to use a different set of callouts when there isn't a match on 42926919f07SPatrick Williamsthe AdditionalData field, one can use CalloutsWhenNoADMatch. In the following 43026919f07SPatrick Williamsexample, the 'air_mover' callout will be added if 'PROC_NUM' isn't 0. 43126919f07SPatrick Williams'CalloutsWhenNoADMatch' has the same schema as the 'Callouts' section. 4323d923311SMatt Spinler 433a6c48787SMatt Spinler```json 4343d923311SMatt Spinler"CalloutsUsingAD": 4353d923311SMatt Spinler{ 4363d923311SMatt Spinler "ADName": "PROC_NUM", 4373d923311SMatt Spinler "CalloutsWithTheirADValues": 4383d923311SMatt Spinler [ 4393d923311SMatt Spinler { 4403d923311SMatt Spinler "ADValue": "0", 4413d923311SMatt Spinler "Callouts": 4423d923311SMatt Spinler [ 4433d923311SMatt Spinler { 4443d923311SMatt Spinler "CalloutList": 4453d923311SMatt Spinler [ 4463d923311SMatt Spinler { 4473d923311SMatt Spinler "Priority": "high", 4483d923311SMatt Spinler "LocCode": "P1-C5" 4493d923311SMatt Spinler } 4503d923311SMatt Spinler ] 4513d923311SMatt Spinler } 4523d923311SMatt Spinler ] 4533d923311SMatt Spinler }, 4543d923311SMatt Spinler ], 4553d923311SMatt Spinler "CalloutsWhenNoADMatch": [ 4563d923311SMatt Spinler { 4573d923311SMatt Spinler "CalloutList": [ 4583d923311SMatt Spinler { 4593d923311SMatt Spinler "Priority": "high", 4603d923311SMatt Spinler "SymbolicFRU": "air_mover" 4613d923311SMatt Spinler } 4623d923311SMatt Spinler ] 4633d923311SMatt Spinler } 4643d923311SMatt Spinler ] 4653d923311SMatt Spinler} 4663d923311SMatt Spinler 4673d923311SMatt Spinler``` 4683d923311SMatt Spinler 46970311203SMatt Spinler#### CalloutType 47026919f07SPatrick Williams 47126919f07SPatrick WilliamsThis field can be used to modify the failing component type field in the callout 47226919f07SPatrick Williamswhen the default doesn\'t fit: 47370311203SMatt Spinler 474a6c48787SMatt Spinler```json 47570311203SMatt Spinler{ 47670311203SMatt Spinler 47770311203SMatt Spinler "Priority": "high", 47870311203SMatt Spinler "Procedure": "FIXIT22" 47970311203SMatt Spinler "CalloutType": "config_procedure" 48070311203SMatt Spinler} 48170311203SMatt Spinler``` 48270311203SMatt Spinler 48370311203SMatt SpinlerThe defaults are: 48426919f07SPatrick Williams 48570311203SMatt Spinler- Normal hardware FRU: hardware_fru 48670311203SMatt Spinler- Symbolic FRU: symbolic_fru 48770311203SMatt Spinler- Procedure: maint_procedure 488d03d3d91SMatt Spinler 489f00f9d0fSMatt Spinler#### Symbolic FRU callouts with dynamic trusted location codes 490f00f9d0fSMatt Spinler 491f00f9d0fSMatt SpinlerA special case is when one wants to use a symbolic FRU callout with a trusted 492f00f9d0fSMatt Spinlerlocation code, but the location code to use isn\'t known until runtime. This 493f00f9d0fSMatt Spinlermeans it can\'t be specified using the 'LocCode' key in the registry. 494f00f9d0fSMatt Spinler 495f00f9d0fSMatt SpinlerIn this case, one should use the 'SymbolicFRUTrusted' key along with the 496f00f9d0fSMatt Spinler'UseInventoryLocCode' key, and then pass in the inventory item that has the 497f00f9d0fSMatt Spinlerdesired location code using the 'CALLOUT_INVENTORY_PATH' entry inside of the 498f00f9d0fSMatt SpinlerAdditionalData property. The code will then look up the location code for that 49926919f07SPatrick Williamspassed in inventory FRU and place it in the symbolic FRU callout. The normal FRU 50026919f07SPatrick Williamscallout with that inventory item will not be created. The symbolic FRU must be 50126919f07SPatrick Williamsthe first callout in the registry for this to work. 502f00f9d0fSMatt Spinler 503a6c48787SMatt Spinler```json 504f00f9d0fSMatt Spinler{ 505f00f9d0fSMatt Spinler "Priority": "high", 506f00f9d0fSMatt Spinler "SymbolicFRUTrusted": "AIR_MOVR", 507f00f9d0fSMatt Spinler "UseInventoryLocCode": true 508f00f9d0fSMatt Spinler} 509f00f9d0fSMatt Spinler``` 510f00f9d0fSMatt Spinler 511f22b4a1eSMatt Spinler### Capturing the Journal 512f22b4a1eSMatt Spinler 513f22b4a1eSMatt SpinlerThe PEL daemon can be told to capture pieces of the journal in PEL UserData 514f22b4a1eSMatt Spinlersections. This could be useful for debugging problems where a BMC dump which 515f22b4a1eSMatt Spinlerwould also contain the journal isn't available. 516f22b4a1eSMatt Spinler 517f22b4a1eSMatt SpinlerThe 'JournalCapture' field has two formats, one that will create one UserData 518f22b4a1eSMatt Spinlersection with the previous N lines of the journal, and another that can capture 519f22b4a1eSMatt Spinlerany number of journal snippets based on the journal's SYSLOG_IDENTIFIER field. 520f22b4a1eSMatt Spinler 521f22b4a1eSMatt Spinler```json 522f22b4a1eSMatt Spinler"JournalCapture": { 523f22b4a1eSMatt Spinler "NumLines": 30 524f22b4a1eSMatt Spinler} 525f22b4a1eSMatt Spinler``` 526f22b4a1eSMatt Spinler 527f22b4a1eSMatt Spinler```json 528f22b4a1eSMatt Spinler"JournalCapture": 529f22b4a1eSMatt Spinler{ 530f22b4a1eSMatt Spinler "Sections": [ 531f22b4a1eSMatt Spinler { 532f22b4a1eSMatt Spinler "SyslogID": "phosphor-bmc-state-manager", 533f22b4a1eSMatt Spinler "NumLines": 20 534f22b4a1eSMatt Spinler }, 535f22b4a1eSMatt Spinler { 536f22b4a1eSMatt Spinler "SyslogID": "phosphor-log-manager", 537f22b4a1eSMatt Spinler "NumLines": 15 538f22b4a1eSMatt Spinler } 539f22b4a1eSMatt Spinler ] 540f22b4a1eSMatt Spinler} 541f22b4a1eSMatt Spinler``` 542f22b4a1eSMatt Spinler 543f22b4a1eSMatt SpinlerThe first example will capture the previous 30 lines from the journal into a 544f22b4a1eSMatt Spinlersingle UserData section. 545f22b4a1eSMatt Spinler 546f22b4a1eSMatt SpinlerThe second example will create two UserData sections, the first with the most 547f22b4a1eSMatt Spinlerrecent 20 lines from phosphor-bmc-state-manager, and the second with 15 lines 548f22b4a1eSMatt Spinlerfrom phosphor-log-manager. 549f22b4a1eSMatt Spinler 550f22b4a1eSMatt SpinlerIf a UserData section would make the PEL exceed its maximum size of 16KB, it 551f22b4a1eSMatt Spinlerwill be dropped. 552f22b4a1eSMatt Spinler 553d03d3d91SMatt Spinler## Modifying and Testing 554d03d3d91SMatt Spinler 555d03d3d91SMatt SpinlerThe general process for adding new entries to the message registry is: 556d03d3d91SMatt Spinler 557d03d3d91SMatt Spinler1. Update message_registry.json to add the new errors. 558d03d3d91SMatt Spinler2. If a new component ID is used (usually the first byte of the SRC reason 5598e823e12SMatt Spinler code), document it in O_component_ids.json. 560d03d3d91SMatt Spinler3. Validate the file. It must be valid JSON and obey the schema. The 5611ed1067cSMatt Spinler `validate_registry.py` script in `extensions/openpower-pels/registry/tools` 562d03d3d91SMatt Spinler will validate both, though it requires the python-jsonschema package to do 563d03d3d91SMatt Spinler the schema validation. This script is also run to validate the message 564d03d3d91SMatt Spinler registry as part of CI testing. 565d03d3d91SMatt Spinler 566a6c48787SMatt Spinler ```sh 5671ed1067cSMatt Spinler ./tools/validate_registry.py -s schema/schema.json -r message_registry.json 568d03d3d91SMatt Spinler ``` 569d03d3d91SMatt Spinler 570d03d3d91SMatt Spinler4. One can test what PELs are generated from these new entries without writing 571d03d3d91SMatt Spinler any code to create the corresponding event logs: 572a6c48787SMatt Spinler 573d03d3d91SMatt Spinler 1. Copy the modified message_registry.json into `/etc/phosphor-logging/` on 574d03d3d91SMatt Spinler the BMC. That directory may need to be created. 57526919f07SPatrick Williams 2. Use busctl to call the Create method to create an event log corresponding 57626919f07SPatrick Williams to the message registry entry under test. 577d03d3d91SMatt Spinler 578a6c48787SMatt Spinler ```sh 579d03d3d91SMatt Spinler busctl call xyz.openbmc_project.Logging /xyz/openbmc_project/logging \ 580d03d3d91SMatt Spinler xyz.openbmc_project.Logging.Create Create ssa{ss} \ 581d03d3d91SMatt Spinler xyz.openbmc_project.Common.Error.Timeout \ 582d03d3d91SMatt Spinler xyz.openbmc_project.Logging.Entry.Level.Error 1 "TIMEOUT_IN_MSEC" "5" 583d03d3d91SMatt Spinler ``` 584d03d3d91SMatt Spinler 585d03d3d91SMatt Spinler 3. Check the PEL that was created using peltool. 586d03d3d91SMatt Spinler 4. When finished, delete the file from `/etc/phosphor-logging/`. 587