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 214*110287baSShawn McCarneyFor example: ["SRCWord3", "SRCWord9"] would be: 215*110287baSShawn McCarney`<ASCII_STRING>_<SRCWord3>_<SRCWord9>`, which could look like: 216*110287baSShawn McCarney`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 33215370292SArya K PadmanThe callouts based on system type can be added in two ways, by using either a 33315370292SArya K Padmankey called `System` or by `Systems`. 33415370292SArya K Padman 33515370292SArya K PadmanThe `System` key will accept the system name as a string and the user can add 33615370292SArya K Padmanthe callouts specific to that system under the `System`. 33715370292SArya K Padman 33815370292SArya K PadmanSuppose if multiple systems have same callouts, the `Systems` key can be used. 33915370292SArya K PadmanThe `Systems` can accept the system names as an array of strings and the list of 34015370292SArya K Padmancallouts common to those systems can be listed under the key. 34115370292SArya K Padman 3422edce4e2SMatt SpinlerAvailable maintenance procedures are listed [here][1] and in the source code 3432edce4e2SMatt Spinler[here][2]. 3442edce4e2SMatt Spinler 3452edce4e2SMatt Spinler[1]: 3462edce4e2SMatt Spinler https://github.com/ibm-openbmc/openpower-pel-parsers/blob/master/modules/calloutparsers/ocallouts/ocallouts.py 3472edce4e2SMatt Spinler[2]: 3482edce4e2SMatt Spinler https://github.com/openbmc/phosphor-logging/blob/master/extensions/openpower-pels/pel_values.cpp 3492edce4e2SMatt Spinler 3502edce4e2SMatt SpinlerIf a procedure is needed that doesn't exist yet, please contact the owner of 3512edce4e2SMatt Spinlerthis code for instructions. 3522edce4e2SMatt Spinler 35370311203SMatt Spinler#### Callouts example based on the system type 35470311203SMatt Spinler 355a6c48787SMatt Spinler```json 35670311203SMatt Spinler"Callouts": 35770311203SMatt Spinler[ 35870311203SMatt Spinler { 35970311203SMatt Spinler "System": "system1", 36070311203SMatt Spinler "CalloutList": 36170311203SMatt Spinler [ 36270311203SMatt Spinler { 36370311203SMatt Spinler "Priority": "high", 36470311203SMatt Spinler "LocCode": "P1-C1" 36570311203SMatt Spinler }, 36670311203SMatt Spinler { 36770311203SMatt Spinler "Priority": "low", 36870311203SMatt Spinler "LocCode": "P1" 36970311203SMatt Spinler } 37070311203SMatt Spinler ] 37170311203SMatt Spinler }, 37270311203SMatt Spinler { 37370311203SMatt Spinler "CalloutList": 37470311203SMatt Spinler [ 37570311203SMatt Spinler { 37670311203SMatt Spinler "Priority": "high", 3772edce4e2SMatt Spinler "Procedure": "BMC0002" 37870311203SMatt Spinler } 37970311203SMatt Spinler ] 38070311203SMatt Spinler 38170311203SMatt Spinler } 38270311203SMatt Spinler] 38370311203SMatt Spinler 38470311203SMatt Spinler``` 38570311203SMatt Spinler 38615370292SArya K PadmanThe above example shows that on system `system1`, the FRU at location P1-C1 will 38726919f07SPatrick Williamsbe called out with a priority of high, and the FRU at P1 with a priority of low. 3882edce4e2SMatt SpinlerOn every other system, the maintenance procedure BMC0002 is called out. 38970311203SMatt Spinler 39015370292SArya K Padman#### Callouts example based on the Systems type 39115370292SArya K Padman 39215370292SArya K Padman```json 39315370292SArya K Padman"Callouts": 39415370292SArya K Padman[ 39515370292SArya K Padman { 39615370292SArya K Padman "Systems": ["system1", "system2"], 39715370292SArya K Padman "CalloutList": 39815370292SArya K Padman [ 39915370292SArya K Padman { 40015370292SArya K Padman "Priority": "high", 40115370292SArya K Padman "LocCode": "P1-C1" 40215370292SArya K Padman }, 40315370292SArya K Padman { 40415370292SArya K Padman "Priority": "low", 40515370292SArya K Padman "LocCode": "P1" 40615370292SArya K Padman } 40715370292SArya K Padman ] 40815370292SArya K Padman }, 40915370292SArya K Padman { 41015370292SArya K Padman "System": "system1", 41115370292SArya K Padman "CalloutList": 41215370292SArya K Padman [ 41315370292SArya K Padman { 41415370292SArya K Padman "Priority": "low", 41515370292SArya K Padman "SymbolicFRU": "service_docs" 41615370292SArya K Padman }, 41715370292SArya K Padman { 41815370292SArya K Padman "Priority": "low", 41915370292SArya K Padman "SymbolicFRUTrusted": "air_mover", 42015370292SArya K Padman "UseInventoryLocCode": true 42115370292SArya K Padman } 42215370292SArya K Padman ] 42315370292SArya K Padman }, 42415370292SArya K Padman { 42515370292SArya K Padman "CalloutList": 42615370292SArya K Padman [ 42715370292SArya K Padman { 42815370292SArya K Padman "Priority": "medium", 42915370292SArya K Padman "Procedure": "BMC0001" 43015370292SArya K Padman } 43115370292SArya K Padman ] 43215370292SArya K Padman } 43315370292SArya K Padman] 43415370292SArya K Padman``` 43515370292SArya K Padman 43615370292SArya K PadmanThe above example shows that on `system1`, the FRU at location P1-C1, P1, 43715370292SArya K Padmanservice_docs and air_mover will be called out. For `system2`, the FRU at 43815370292SArya K Padmanlocation P1-C1, P1 will be called out. On every other system, the maintenance 43915370292SArya K Padmanprocedure BMC0001 is called out. 44015370292SArya K Padman 44170311203SMatt Spinler#### Callouts example based on an AdditionalData field 44270311203SMatt Spinler 443a6c48787SMatt Spinler```json 44470311203SMatt Spinler"CalloutsUsingAD": 44570311203SMatt Spinler{ 44670311203SMatt Spinler "ADName": "PROC_NUM", 44770311203SMatt Spinler "CalloutsWithTheirADValues": 44870311203SMatt Spinler [ 44970311203SMatt Spinler { 45070311203SMatt Spinler "ADValue": "0", 45170311203SMatt Spinler "Callouts": 45270311203SMatt Spinler [ 45370311203SMatt Spinler { 45470311203SMatt Spinler "CalloutList": 45570311203SMatt Spinler [ 45670311203SMatt Spinler { 45770311203SMatt Spinler "Priority": "high", 45870311203SMatt Spinler "LocCode": "P1-C5" 45970311203SMatt Spinler } 46070311203SMatt Spinler ] 46170311203SMatt Spinler } 46270311203SMatt Spinler ] 46370311203SMatt Spinler }, 46470311203SMatt Spinler { 46570311203SMatt Spinler "ADValue": "1", 46670311203SMatt Spinler "Callouts": 46770311203SMatt Spinler [ 46870311203SMatt Spinler { 46970311203SMatt Spinler "CalloutList": 47070311203SMatt Spinler [ 47170311203SMatt Spinler { 47270311203SMatt Spinler "Priority": "high", 47370311203SMatt Spinler "LocCode": "P1-C6" 47470311203SMatt Spinler } 47570311203SMatt Spinler ] 47670311203SMatt Spinler } 47770311203SMatt Spinler ] 47870311203SMatt Spinler } 47970311203SMatt Spinler ] 48070311203SMatt Spinler} 48170311203SMatt Spinler 48270311203SMatt Spinler``` 48370311203SMatt Spinler 48470311203SMatt SpinlerThis example shows that the callouts were selected based on the 'PROC_NUM' 48526919f07SPatrick WilliamsAdditionalData field. When PROC_NUM was 0, the FRU at P1-C5 was called out. When 48626919f07SPatrick Williamsit was 1, P1-C6 was called out. Note that the same 'Callouts' array is used as 48726919f07SPatrick Williamsin the previous example, so these callouts can also depend on the system type. 48870311203SMatt Spinler 48926919f07SPatrick WilliamsIf it's desired to use a different set of callouts when there isn't a match on 49026919f07SPatrick Williamsthe AdditionalData field, one can use CalloutsWhenNoADMatch. In the following 49126919f07SPatrick Williamsexample, the 'air_mover' callout will be added if 'PROC_NUM' isn't 0. 49226919f07SPatrick Williams'CalloutsWhenNoADMatch' has the same schema as the 'Callouts' section. 4933d923311SMatt Spinler 494a6c48787SMatt Spinler```json 4953d923311SMatt Spinler"CalloutsUsingAD": 4963d923311SMatt Spinler{ 4973d923311SMatt Spinler "ADName": "PROC_NUM", 4983d923311SMatt Spinler "CalloutsWithTheirADValues": 4993d923311SMatt Spinler [ 5003d923311SMatt Spinler { 5013d923311SMatt Spinler "ADValue": "0", 5023d923311SMatt Spinler "Callouts": 5033d923311SMatt Spinler [ 5043d923311SMatt Spinler { 5053d923311SMatt Spinler "CalloutList": 5063d923311SMatt Spinler [ 5073d923311SMatt Spinler { 5083d923311SMatt Spinler "Priority": "high", 5093d923311SMatt Spinler "LocCode": "P1-C5" 5103d923311SMatt Spinler } 5113d923311SMatt Spinler ] 5123d923311SMatt Spinler } 5133d923311SMatt Spinler ] 5143d923311SMatt Spinler }, 5153d923311SMatt Spinler ], 5163d923311SMatt Spinler "CalloutsWhenNoADMatch": [ 5173d923311SMatt Spinler { 5183d923311SMatt Spinler "CalloutList": [ 5193d923311SMatt Spinler { 5203d923311SMatt Spinler "Priority": "high", 5213d923311SMatt Spinler "SymbolicFRU": "air_mover" 5223d923311SMatt Spinler } 5233d923311SMatt Spinler ] 5243d923311SMatt Spinler } 5253d923311SMatt Spinler ] 5263d923311SMatt Spinler} 5273d923311SMatt Spinler 5283d923311SMatt Spinler``` 5293d923311SMatt Spinler 53070311203SMatt Spinler#### CalloutType 53126919f07SPatrick Williams 53226919f07SPatrick WilliamsThis field can be used to modify the failing component type field in the callout 53326919f07SPatrick Williamswhen the default doesn\'t fit: 53470311203SMatt Spinler 535a6c48787SMatt Spinler```json 53670311203SMatt Spinler{ 53770311203SMatt Spinler 53870311203SMatt Spinler "Priority": "high", 53970311203SMatt Spinler "Procedure": "FIXIT22" 54070311203SMatt Spinler "CalloutType": "config_procedure" 54170311203SMatt Spinler} 54270311203SMatt Spinler``` 54370311203SMatt Spinler 54470311203SMatt SpinlerThe defaults are: 54526919f07SPatrick Williams 54670311203SMatt Spinler- Normal hardware FRU: hardware_fru 54770311203SMatt Spinler- Symbolic FRU: symbolic_fru 54870311203SMatt Spinler- Procedure: maint_procedure 549d03d3d91SMatt Spinler 550f00f9d0fSMatt Spinler#### Symbolic FRU callouts with dynamic trusted location codes 551f00f9d0fSMatt Spinler 552f00f9d0fSMatt SpinlerA special case is when one wants to use a symbolic FRU callout with a trusted 553f00f9d0fSMatt Spinlerlocation code, but the location code to use isn\'t known until runtime. This 554f00f9d0fSMatt Spinlermeans it can\'t be specified using the 'LocCode' key in the registry. 555f00f9d0fSMatt Spinler 556f00f9d0fSMatt SpinlerIn this case, one should use the 'SymbolicFRUTrusted' key along with the 557f00f9d0fSMatt Spinler'UseInventoryLocCode' key, and then pass in the inventory item that has the 558f00f9d0fSMatt Spinlerdesired location code using the 'CALLOUT_INVENTORY_PATH' entry inside of the 559f00f9d0fSMatt SpinlerAdditionalData property. The code will then look up the location code for that 56026919f07SPatrick Williamspassed in inventory FRU and place it in the symbolic FRU callout. The normal FRU 56126919f07SPatrick Williamscallout with that inventory item will not be created. The symbolic FRU must be 56226919f07SPatrick Williamsthe first callout in the registry for this to work. 563f00f9d0fSMatt Spinler 564a6c48787SMatt Spinler```json 565f00f9d0fSMatt Spinler{ 566f00f9d0fSMatt Spinler "Priority": "high", 567f00f9d0fSMatt Spinler "SymbolicFRUTrusted": "AIR_MOVR", 568f00f9d0fSMatt Spinler "UseInventoryLocCode": true 569f00f9d0fSMatt Spinler} 570f00f9d0fSMatt Spinler``` 571f00f9d0fSMatt Spinler 572f22b4a1eSMatt Spinler### Capturing the Journal 573f22b4a1eSMatt Spinler 574f22b4a1eSMatt SpinlerThe PEL daemon can be told to capture pieces of the journal in PEL UserData 575f22b4a1eSMatt Spinlersections. This could be useful for debugging problems where a BMC dump which 576f22b4a1eSMatt Spinlerwould also contain the journal isn't available. 577f22b4a1eSMatt Spinler 578f22b4a1eSMatt SpinlerThe 'JournalCapture' field has two formats, one that will create one UserData 579f22b4a1eSMatt Spinlersection with the previous N lines of the journal, and another that can capture 580f22b4a1eSMatt Spinlerany number of journal snippets based on the journal's SYSLOG_IDENTIFIER field. 581f22b4a1eSMatt Spinler 582f22b4a1eSMatt Spinler```json 583f22b4a1eSMatt Spinler"JournalCapture": { 584f22b4a1eSMatt Spinler "NumLines": 30 585f22b4a1eSMatt Spinler} 586f22b4a1eSMatt Spinler``` 587f22b4a1eSMatt Spinler 588f22b4a1eSMatt Spinler```json 589f22b4a1eSMatt Spinler"JournalCapture": 590f22b4a1eSMatt Spinler{ 591f22b4a1eSMatt Spinler "Sections": [ 592f22b4a1eSMatt Spinler { 593f22b4a1eSMatt Spinler "SyslogID": "phosphor-bmc-state-manager", 594f22b4a1eSMatt Spinler "NumLines": 20 595f22b4a1eSMatt Spinler }, 596f22b4a1eSMatt Spinler { 597f22b4a1eSMatt Spinler "SyslogID": "phosphor-log-manager", 598f22b4a1eSMatt Spinler "NumLines": 15 599f22b4a1eSMatt Spinler } 600f22b4a1eSMatt Spinler ] 601f22b4a1eSMatt Spinler} 602f22b4a1eSMatt Spinler``` 603f22b4a1eSMatt Spinler 604f22b4a1eSMatt SpinlerThe first example will capture the previous 30 lines from the journal into a 605f22b4a1eSMatt Spinlersingle UserData section. 606f22b4a1eSMatt Spinler 607f22b4a1eSMatt SpinlerThe second example will create two UserData sections, the first with the most 608f22b4a1eSMatt Spinlerrecent 20 lines from phosphor-bmc-state-manager, and the second with 15 lines 609f22b4a1eSMatt Spinlerfrom phosphor-log-manager. 610f22b4a1eSMatt Spinler 611f22b4a1eSMatt SpinlerIf a UserData section would make the PEL exceed its maximum size of 16KB, it 612f22b4a1eSMatt Spinlerwill be dropped. 613f22b4a1eSMatt Spinler 614d03d3d91SMatt Spinler## Modifying and Testing 615d03d3d91SMatt Spinler 616d03d3d91SMatt SpinlerThe general process for adding new entries to the message registry is: 617d03d3d91SMatt Spinler 618d03d3d91SMatt Spinler1. Update message_registry.json to add the new errors. 619d03d3d91SMatt Spinler2. If a new component ID is used (usually the first byte of the SRC reason 6208e823e12SMatt Spinler code), document it in O_component_ids.json. 621d03d3d91SMatt Spinler3. Validate the file. It must be valid JSON and obey the schema. The 6221ed1067cSMatt Spinler `validate_registry.py` script in `extensions/openpower-pels/registry/tools` 623d03d3d91SMatt Spinler will validate both, though it requires the python-jsonschema package to do 624d03d3d91SMatt Spinler the schema validation. This script is also run to validate the message 625d03d3d91SMatt Spinler registry as part of CI testing. 626d03d3d91SMatt Spinler 627a6c48787SMatt Spinler ```sh 6281ed1067cSMatt Spinler ./tools/validate_registry.py -s schema/schema.json -r message_registry.json 629d03d3d91SMatt Spinler ``` 630d03d3d91SMatt Spinler 631d03d3d91SMatt Spinler4. One can test what PELs are generated from these new entries without writing 632d03d3d91SMatt Spinler any code to create the corresponding event logs: 633a6c48787SMatt Spinler 634d03d3d91SMatt Spinler 1. Copy the modified message_registry.json into `/etc/phosphor-logging/` on 635d03d3d91SMatt Spinler the BMC. That directory may need to be created. 63626919f07SPatrick Williams 2. Use busctl to call the Create method to create an event log corresponding 63726919f07SPatrick Williams to the message registry entry under test. 638d03d3d91SMatt Spinler 639a6c48787SMatt Spinler ```sh 640d03d3d91SMatt Spinler busctl call xyz.openbmc_project.Logging /xyz/openbmc_project/logging \ 641d03d3d91SMatt Spinler xyz.openbmc_project.Logging.Create Create ssa{ss} \ 642d03d3d91SMatt Spinler xyz.openbmc_project.Common.Error.Timeout \ 643d03d3d91SMatt Spinler xyz.openbmc_project.Logging.Entry.Level.Error 1 "TIMEOUT_IN_MSEC" "5" 644d03d3d91SMatt Spinler ``` 645d03d3d91SMatt Spinler 646d03d3d91SMatt Spinler 3. Check the PEL that was created using peltool. 647d03d3d91SMatt Spinler 4. When finished, delete the file from `/etc/phosphor-logging/`. 648