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*1763a84eSRiya DixitFor example: ["SRCWord3", "SRCWord9"] would be: `<ASCII_STRING>_<SRCWord3>_<SRCWord9>`, 215*1763a84eSRiya Dixitwhich could look like: `B181320_00000050_49000000`. 216a96a7948SMatt Spinler 217a6c48787SMatt Spinler```json 218a96a7948SMatt Spinler"SymptomIDFields": ["SRCWord3", "SRCWord9"] 219a96a7948SMatt Spinler``` 220a96a7948SMatt Spinler 221a96a7948SMatt Spinler### SRC words 6 to 9 22226919f07SPatrick Williams 223a96a7948SMatt SpinlerIn a PEL, these SRC words are free format and can be filled in by the user as 224a96a7948SMatt Spinlerdesired. On the BMC, the source of these words is the AdditionalData fields in 225a96a7948SMatt Spinlerthe event log. The message registry provides a way for the log creator to 226a96a7948SMatt Spinlerspecify which AdditionalData property field to get the data from, and also to 227a96a7948SMatt Spinlerdefine what the SRC word means for use by parsers. If not specified, these SRC 228a96a7948SMatt Spinlerwords will be set to zero in the PEL. 229a96a7948SMatt Spinler 230a6c48787SMatt Spinler```json 231a96a7948SMatt Spinler"Words6to9": 232a96a7948SMatt Spinler{ 233a96a7948SMatt Spinler "6": 234a96a7948SMatt Spinler { 235a96a7948SMatt Spinler "description": "Failing unit number", 236a96a7948SMatt Spinler "AdditionalDataPropSource": "PS_NUM" 237a96a7948SMatt Spinler } 238a96a7948SMatt Spinler} 239a96a7948SMatt Spinler``` 240a96a7948SMatt Spinler 2413fe93e96SMatt Spinler### SRC Deconfig Flag 2423fe93e96SMatt Spinler 2433fe93e96SMatt SpinlerBit 6 in hex word 5 of the SRC means that one or more called out resources have 2443fe93e96SMatt Spinlerbeen deconfigured, and this flag can be used to set that bit. The only other way 2453fe93e96SMatt Spinlerto set it is by indicating it when 2463fe93e96SMatt Spinler[passing in the callouts via JSON](../README.md#callouts). 2473fe93e96SMatt Spinler 2483fe93e96SMatt SpinlerThis is looked at by the software that creates the periodic PELs that indicate a 2493fe93e96SMatt Spinlersystem is running with deconfigured hardware. 2503fe93e96SMatt Spinler 2513fe93e96SMatt Spinler```json 2523fe93e96SMatt Spinler"DeconfigFlag": true 2533fe93e96SMatt Spinler``` 2543fe93e96SMatt Spinler 255da5b76b2SMatt Spinler### SRC Checkstop Flag 256da5b76b2SMatt Spinler 257da5b76b2SMatt SpinlerThis is used to indicate the PEL is for a hardware checkstop, and causes bit 0 258da5b76b2SMatt Spinlerin hex word 5 of the SRC to be set. 259da5b76b2SMatt Spinler 260da5b76b2SMatt Spinler```json 261da5b76b2SMatt Spinler"CheckstopFlag": true 262da5b76b2SMatt Spinler``` 263da5b76b2SMatt Spinler 264a96a7948SMatt Spinler### Documentation Fields 26526919f07SPatrick Williams 266a96a7948SMatt SpinlerThe documentation fields are used by PEL parsers to display a human readable 267a96a7948SMatt Spinlerdescription of a PEL. They are also the source for the Redfish event log 268a96a7948SMatt Spinlermessages. 269a96a7948SMatt Spinler 270a96a7948SMatt Spinler#### Message 27126919f07SPatrick Williams 272a96a7948SMatt SpinlerThis field is used by the BMC's PEL parser as the description of the error log. 273a96a7948SMatt SpinlerIt will also be used in Redfish event logs. It supports argument substitution 27426919f07SPatrick Williamsusing the %1, %2, etc placeholders allowing any of the SRC user data words 6 - 9 27526919f07SPatrick Williamsto be displayed as part of the message. If the placeholders are used, then the 27626919f07SPatrick Williams`MessageArgSources` property must be present to say which SRC words to use for 27726919f07SPatrick Williamseach placeholder. 278a96a7948SMatt Spinler 279a6c48787SMatt Spinler```json 280a96a7948SMatt Spinler"Message": "Processor %1 had %2 errors" 281a96a7948SMatt Spinler``` 282a96a7948SMatt Spinler 283a96a7948SMatt Spinler#### MessageArgSources 28426919f07SPatrick Williams 285a96a7948SMatt SpinlerThis optional field is required when the Message field contains the %X 286a96a7948SMatt Spinlerplaceholder arguments. It is an array that says which SRC words to get the 287a96a7948SMatt Spinlerplaceholders from. In the example below, SRC word 6 would be used for %1, and 288a96a7948SMatt SpinlerSRC word 7 for %2. 289a96a7948SMatt Spinler 290a6c48787SMatt Spinler```json 291a96a7948SMatt Spinler"MessageArgSources": 292a96a7948SMatt Spinler[ 293a96a7948SMatt Spinler "SRCWord6", "SRCWord7" 294a96a7948SMatt Spinler] 295a96a7948SMatt Spinler``` 296a96a7948SMatt Spinler 297a96a7948SMatt Spinler#### Description 29826919f07SPatrick Williams 29926919f07SPatrick WilliamsA short description of the error. This is required by the Redfish schema to 30026919f07SPatrick Williamsgenerate a Redfish message entry, but is not used in Redfish or PEL output. 301a96a7948SMatt Spinler 302a6c48787SMatt Spinler```json 303a96a7948SMatt Spinler"Description": "A power fault" 304a96a7948SMatt Spinler``` 305a96a7948SMatt Spinler 306a96a7948SMatt Spinler#### Notes 30726919f07SPatrick Williams 308a96a7948SMatt SpinlerThis is an optional free format text field for keeping any notes for the 309a96a7948SMatt Spinlerregistry entry, as comments are not allowed in JSON. It is an array of strings 310a96a7948SMatt Spinlerfor easier readability of long fields. 311a96a7948SMatt Spinler 312a6c48787SMatt Spinler```json 313a96a7948SMatt Spinler"Notes": [ 314a96a7948SMatt Spinler "This entry is for every type of power fault.", 315a96a7948SMatt Spinler "There is probably a hardware failure." 316a96a7948SMatt Spinler] 317a96a7948SMatt Spinler``` 31870311203SMatt Spinler 31970311203SMatt Spinler### Callout Fields 32026919f07SPatrick Williams 32126919f07SPatrick WilliamsThe callout fields allow one to specify the PEL callouts (either a hardware FRU, 32226919f07SPatrick Williamsa symbolic FRU, or a maintenance procedure) in the entry for a particular error. 32326919f07SPatrick WilliamsThese callouts can vary based on system type, as well as a user specified 32426919f07SPatrick WilliamsAdditionalData property field. Callouts will be added to the PEL in the order 32526919f07SPatrick Williamsthey are listed in the JSON. If a callout is passed into the error, say with 32626919f07SPatrick WilliamsCALLOUT_INVENTORY_PATH, then that callout will be added to the PEL before the 32726919f07SPatrick Williamscallouts in the registry. 32870311203SMatt Spinler 32970311203SMatt SpinlerThere is room for up to 10 callouts in a PEL. 33070311203SMatt Spinler 33115370292SArya K PadmanThe callouts based on system type can be added in two ways, by using either a 33215370292SArya K Padmankey called `System` or by `Systems`. 33315370292SArya K Padman 33415370292SArya K PadmanThe `System` key will accept the system name as a string and the user can add 33515370292SArya K Padmanthe callouts specific to that system under the `System`. 33615370292SArya K Padman 33715370292SArya K PadmanSuppose if multiple systems have same callouts, the `Systems` key can be used. 33815370292SArya K PadmanThe `Systems` can accept the system names as an array of strings and the list of 33915370292SArya K Padmancallouts common to those systems can be listed under the key. 34015370292SArya K Padman 3412edce4e2SMatt SpinlerAvailable maintenance procedures are listed [here][1] and in the source code 3422edce4e2SMatt Spinler[here][2]. 3432edce4e2SMatt Spinler 3442edce4e2SMatt Spinler[1]: 3452edce4e2SMatt Spinler https://github.com/ibm-openbmc/openpower-pel-parsers/blob/master/modules/calloutparsers/ocallouts/ocallouts.py 3462edce4e2SMatt Spinler[2]: 3472edce4e2SMatt Spinler https://github.com/openbmc/phosphor-logging/blob/master/extensions/openpower-pels/pel_values.cpp 3482edce4e2SMatt Spinler 3492edce4e2SMatt SpinlerIf a procedure is needed that doesn't exist yet, please contact the owner of 3502edce4e2SMatt Spinlerthis code for instructions. 3512edce4e2SMatt Spinler 35270311203SMatt Spinler#### Callouts example based on the system type 35370311203SMatt Spinler 354a6c48787SMatt Spinler```json 35570311203SMatt Spinler"Callouts": 35670311203SMatt Spinler[ 35770311203SMatt Spinler { 35870311203SMatt Spinler "System": "system1", 35970311203SMatt Spinler "CalloutList": 36070311203SMatt Spinler [ 36170311203SMatt Spinler { 36270311203SMatt Spinler "Priority": "high", 36370311203SMatt Spinler "LocCode": "P1-C1" 36470311203SMatt Spinler }, 36570311203SMatt Spinler { 36670311203SMatt Spinler "Priority": "low", 36770311203SMatt Spinler "LocCode": "P1" 36870311203SMatt Spinler } 36970311203SMatt Spinler ] 37070311203SMatt Spinler }, 37170311203SMatt Spinler { 37270311203SMatt Spinler "CalloutList": 37370311203SMatt Spinler [ 37470311203SMatt Spinler { 37570311203SMatt Spinler "Priority": "high", 3762edce4e2SMatt Spinler "Procedure": "BMC0002" 37770311203SMatt Spinler } 37870311203SMatt Spinler ] 37970311203SMatt Spinler 38070311203SMatt Spinler } 38170311203SMatt Spinler] 38270311203SMatt Spinler 38370311203SMatt Spinler``` 38470311203SMatt Spinler 38515370292SArya K PadmanThe above example shows that on system `system1`, the FRU at location P1-C1 will 38626919f07SPatrick Williamsbe called out with a priority of high, and the FRU at P1 with a priority of low. 3872edce4e2SMatt SpinlerOn every other system, the maintenance procedure BMC0002 is called out. 38870311203SMatt Spinler 38915370292SArya K Padman#### Callouts example based on the Systems type 39015370292SArya K Padman 39115370292SArya K Padman```json 39215370292SArya K Padman"Callouts": 39315370292SArya K Padman[ 39415370292SArya K Padman { 39515370292SArya K Padman "Systems": ["system1", "system2"], 39615370292SArya K Padman "CalloutList": 39715370292SArya K Padman [ 39815370292SArya K Padman { 39915370292SArya K Padman "Priority": "high", 40015370292SArya K Padman "LocCode": "P1-C1" 40115370292SArya K Padman }, 40215370292SArya K Padman { 40315370292SArya K Padman "Priority": "low", 40415370292SArya K Padman "LocCode": "P1" 40515370292SArya K Padman } 40615370292SArya K Padman ] 40715370292SArya K Padman }, 40815370292SArya K Padman { 40915370292SArya K Padman "System": "system1", 41015370292SArya K Padman "CalloutList": 41115370292SArya K Padman [ 41215370292SArya K Padman { 41315370292SArya K Padman "Priority": "low", 41415370292SArya K Padman "SymbolicFRU": "service_docs" 41515370292SArya K Padman }, 41615370292SArya K Padman { 41715370292SArya K Padman "Priority": "low", 41815370292SArya K Padman "SymbolicFRUTrusted": "air_mover", 41915370292SArya K Padman "UseInventoryLocCode": true 42015370292SArya K Padman } 42115370292SArya K Padman ] 42215370292SArya K Padman }, 42315370292SArya K Padman { 42415370292SArya K Padman "CalloutList": 42515370292SArya K Padman [ 42615370292SArya K Padman { 42715370292SArya K Padman "Priority": "medium", 42815370292SArya K Padman "Procedure": "BMC0001" 42915370292SArya K Padman } 43015370292SArya K Padman ] 43115370292SArya K Padman } 43215370292SArya K Padman] 43315370292SArya K Padman``` 43415370292SArya K Padman 43515370292SArya K PadmanThe above example shows that on `system1`, the FRU at location P1-C1, P1, 43615370292SArya K Padmanservice_docs and air_mover will be called out. For `system2`, the FRU at 43715370292SArya K Padmanlocation P1-C1, P1 will be called out. On every other system, the maintenance 43815370292SArya K Padmanprocedure BMC0001 is called out. 43915370292SArya K Padman 44070311203SMatt Spinler#### Callouts example based on an AdditionalData field 44170311203SMatt Spinler 442a6c48787SMatt Spinler```json 44370311203SMatt Spinler"CalloutsUsingAD": 44470311203SMatt Spinler{ 44570311203SMatt Spinler "ADName": "PROC_NUM", 44670311203SMatt Spinler "CalloutsWithTheirADValues": 44770311203SMatt Spinler [ 44870311203SMatt Spinler { 44970311203SMatt Spinler "ADValue": "0", 45070311203SMatt Spinler "Callouts": 45170311203SMatt Spinler [ 45270311203SMatt Spinler { 45370311203SMatt Spinler "CalloutList": 45470311203SMatt Spinler [ 45570311203SMatt Spinler { 45670311203SMatt Spinler "Priority": "high", 45770311203SMatt Spinler "LocCode": "P1-C5" 45870311203SMatt Spinler } 45970311203SMatt Spinler ] 46070311203SMatt Spinler } 46170311203SMatt Spinler ] 46270311203SMatt Spinler }, 46370311203SMatt Spinler { 46470311203SMatt Spinler "ADValue": "1", 46570311203SMatt Spinler "Callouts": 46670311203SMatt Spinler [ 46770311203SMatt Spinler { 46870311203SMatt Spinler "CalloutList": 46970311203SMatt Spinler [ 47070311203SMatt Spinler { 47170311203SMatt Spinler "Priority": "high", 47270311203SMatt Spinler "LocCode": "P1-C6" 47370311203SMatt Spinler } 47470311203SMatt Spinler ] 47570311203SMatt Spinler } 47670311203SMatt Spinler ] 47770311203SMatt Spinler } 47870311203SMatt Spinler ] 47970311203SMatt Spinler} 48070311203SMatt Spinler 48170311203SMatt Spinler``` 48270311203SMatt Spinler 48370311203SMatt SpinlerThis example shows that the callouts were selected based on the 'PROC_NUM' 48426919f07SPatrick WilliamsAdditionalData field. When PROC_NUM was 0, the FRU at P1-C5 was called out. When 48526919f07SPatrick Williamsit was 1, P1-C6 was called out. Note that the same 'Callouts' array is used as 48626919f07SPatrick Williamsin the previous example, so these callouts can also depend on the system type. 48770311203SMatt Spinler 48826919f07SPatrick WilliamsIf it's desired to use a different set of callouts when there isn't a match on 48926919f07SPatrick Williamsthe AdditionalData field, one can use CalloutsWhenNoADMatch. In the following 49026919f07SPatrick Williamsexample, the 'air_mover' callout will be added if 'PROC_NUM' isn't 0. 49126919f07SPatrick Williams'CalloutsWhenNoADMatch' has the same schema as the 'Callouts' section. 4923d923311SMatt Spinler 493a6c48787SMatt Spinler```json 4943d923311SMatt Spinler"CalloutsUsingAD": 4953d923311SMatt Spinler{ 4963d923311SMatt Spinler "ADName": "PROC_NUM", 4973d923311SMatt Spinler "CalloutsWithTheirADValues": 4983d923311SMatt Spinler [ 4993d923311SMatt Spinler { 5003d923311SMatt Spinler "ADValue": "0", 5013d923311SMatt Spinler "Callouts": 5023d923311SMatt Spinler [ 5033d923311SMatt Spinler { 5043d923311SMatt Spinler "CalloutList": 5053d923311SMatt Spinler [ 5063d923311SMatt Spinler { 5073d923311SMatt Spinler "Priority": "high", 5083d923311SMatt Spinler "LocCode": "P1-C5" 5093d923311SMatt Spinler } 5103d923311SMatt Spinler ] 5113d923311SMatt Spinler } 5123d923311SMatt Spinler ] 5133d923311SMatt Spinler }, 5143d923311SMatt Spinler ], 5153d923311SMatt Spinler "CalloutsWhenNoADMatch": [ 5163d923311SMatt Spinler { 5173d923311SMatt Spinler "CalloutList": [ 5183d923311SMatt Spinler { 5193d923311SMatt Spinler "Priority": "high", 5203d923311SMatt Spinler "SymbolicFRU": "air_mover" 5213d923311SMatt Spinler } 5223d923311SMatt Spinler ] 5233d923311SMatt Spinler } 5243d923311SMatt Spinler ] 5253d923311SMatt Spinler} 5263d923311SMatt Spinler 5273d923311SMatt Spinler``` 5283d923311SMatt Spinler 52970311203SMatt Spinler#### CalloutType 53026919f07SPatrick Williams 53126919f07SPatrick WilliamsThis field can be used to modify the failing component type field in the callout 53226919f07SPatrick Williamswhen the default doesn\'t fit: 53370311203SMatt Spinler 534a6c48787SMatt Spinler```json 53570311203SMatt Spinler{ 53670311203SMatt Spinler 53770311203SMatt Spinler "Priority": "high", 53870311203SMatt Spinler "Procedure": "FIXIT22" 53970311203SMatt Spinler "CalloutType": "config_procedure" 54070311203SMatt Spinler} 54170311203SMatt Spinler``` 54270311203SMatt Spinler 54370311203SMatt SpinlerThe defaults are: 54426919f07SPatrick Williams 54570311203SMatt Spinler- Normal hardware FRU: hardware_fru 54670311203SMatt Spinler- Symbolic FRU: symbolic_fru 54770311203SMatt Spinler- Procedure: maint_procedure 548d03d3d91SMatt Spinler 549f00f9d0fSMatt Spinler#### Symbolic FRU callouts with dynamic trusted location codes 550f00f9d0fSMatt Spinler 551f00f9d0fSMatt SpinlerA special case is when one wants to use a symbolic FRU callout with a trusted 552f00f9d0fSMatt Spinlerlocation code, but the location code to use isn\'t known until runtime. This 553f00f9d0fSMatt Spinlermeans it can\'t be specified using the 'LocCode' key in the registry. 554f00f9d0fSMatt Spinler 555f00f9d0fSMatt SpinlerIn this case, one should use the 'SymbolicFRUTrusted' key along with the 556f00f9d0fSMatt Spinler'UseInventoryLocCode' key, and then pass in the inventory item that has the 557f00f9d0fSMatt Spinlerdesired location code using the 'CALLOUT_INVENTORY_PATH' entry inside of the 558f00f9d0fSMatt SpinlerAdditionalData property. The code will then look up the location code for that 55926919f07SPatrick Williamspassed in inventory FRU and place it in the symbolic FRU callout. The normal FRU 56026919f07SPatrick Williamscallout with that inventory item will not be created. The symbolic FRU must be 56126919f07SPatrick Williamsthe first callout in the registry for this to work. 562f00f9d0fSMatt Spinler 563a6c48787SMatt Spinler```json 564f00f9d0fSMatt Spinler{ 565f00f9d0fSMatt Spinler "Priority": "high", 566f00f9d0fSMatt Spinler "SymbolicFRUTrusted": "AIR_MOVR", 567f00f9d0fSMatt Spinler "UseInventoryLocCode": true 568f00f9d0fSMatt Spinler} 569f00f9d0fSMatt Spinler``` 570f00f9d0fSMatt Spinler 571f22b4a1eSMatt Spinler### Capturing the Journal 572f22b4a1eSMatt Spinler 573f22b4a1eSMatt SpinlerThe PEL daemon can be told to capture pieces of the journal in PEL UserData 574f22b4a1eSMatt Spinlersections. This could be useful for debugging problems where a BMC dump which 575f22b4a1eSMatt Spinlerwould also contain the journal isn't available. 576f22b4a1eSMatt Spinler 577f22b4a1eSMatt SpinlerThe 'JournalCapture' field has two formats, one that will create one UserData 578f22b4a1eSMatt Spinlersection with the previous N lines of the journal, and another that can capture 579f22b4a1eSMatt Spinlerany number of journal snippets based on the journal's SYSLOG_IDENTIFIER field. 580f22b4a1eSMatt Spinler 581f22b4a1eSMatt Spinler```json 582f22b4a1eSMatt Spinler"JournalCapture": { 583f22b4a1eSMatt Spinler "NumLines": 30 584f22b4a1eSMatt Spinler} 585f22b4a1eSMatt Spinler``` 586f22b4a1eSMatt Spinler 587f22b4a1eSMatt Spinler```json 588f22b4a1eSMatt Spinler"JournalCapture": 589f22b4a1eSMatt Spinler{ 590f22b4a1eSMatt Spinler "Sections": [ 591f22b4a1eSMatt Spinler { 592f22b4a1eSMatt Spinler "SyslogID": "phosphor-bmc-state-manager", 593f22b4a1eSMatt Spinler "NumLines": 20 594f22b4a1eSMatt Spinler }, 595f22b4a1eSMatt Spinler { 596f22b4a1eSMatt Spinler "SyslogID": "phosphor-log-manager", 597f22b4a1eSMatt Spinler "NumLines": 15 598f22b4a1eSMatt Spinler } 599f22b4a1eSMatt Spinler ] 600f22b4a1eSMatt Spinler} 601f22b4a1eSMatt Spinler``` 602f22b4a1eSMatt Spinler 603f22b4a1eSMatt SpinlerThe first example will capture the previous 30 lines from the journal into a 604f22b4a1eSMatt Spinlersingle UserData section. 605f22b4a1eSMatt Spinler 606f22b4a1eSMatt SpinlerThe second example will create two UserData sections, the first with the most 607f22b4a1eSMatt Spinlerrecent 20 lines from phosphor-bmc-state-manager, and the second with 15 lines 608f22b4a1eSMatt Spinlerfrom phosphor-log-manager. 609f22b4a1eSMatt Spinler 610f22b4a1eSMatt SpinlerIf a UserData section would make the PEL exceed its maximum size of 16KB, it 611f22b4a1eSMatt Spinlerwill be dropped. 612f22b4a1eSMatt Spinler 613d03d3d91SMatt Spinler## Modifying and Testing 614d03d3d91SMatt Spinler 615d03d3d91SMatt SpinlerThe general process for adding new entries to the message registry is: 616d03d3d91SMatt Spinler 617d03d3d91SMatt Spinler1. Update message_registry.json to add the new errors. 618d03d3d91SMatt Spinler2. If a new component ID is used (usually the first byte of the SRC reason 6198e823e12SMatt Spinler code), document it in O_component_ids.json. 620d03d3d91SMatt Spinler3. Validate the file. It must be valid JSON and obey the schema. The 6211ed1067cSMatt Spinler `validate_registry.py` script in `extensions/openpower-pels/registry/tools` 622d03d3d91SMatt Spinler will validate both, though it requires the python-jsonschema package to do 623d03d3d91SMatt Spinler the schema validation. This script is also run to validate the message 624d03d3d91SMatt Spinler registry as part of CI testing. 625d03d3d91SMatt Spinler 626a6c48787SMatt Spinler ```sh 6271ed1067cSMatt Spinler ./tools/validate_registry.py -s schema/schema.json -r message_registry.json 628d03d3d91SMatt Spinler ``` 629d03d3d91SMatt Spinler 630d03d3d91SMatt Spinler4. One can test what PELs are generated from these new entries without writing 631d03d3d91SMatt Spinler any code to create the corresponding event logs: 632a6c48787SMatt Spinler 633d03d3d91SMatt Spinler 1. Copy the modified message_registry.json into `/etc/phosphor-logging/` on 634d03d3d91SMatt Spinler the BMC. That directory may need to be created. 63526919f07SPatrick Williams 2. Use busctl to call the Create method to create an event log corresponding 63626919f07SPatrick Williams to the message registry entry under test. 637d03d3d91SMatt Spinler 638a6c48787SMatt Spinler ```sh 639d03d3d91SMatt Spinler busctl call xyz.openbmc_project.Logging /xyz/openbmc_project/logging \ 640d03d3d91SMatt Spinler xyz.openbmc_project.Logging.Create Create ssa{ss} \ 641d03d3d91SMatt Spinler xyz.openbmc_project.Common.Error.Timeout \ 642d03d3d91SMatt Spinler xyz.openbmc_project.Logging.Entry.Level.Error 1 "TIMEOUT_IN_MSEC" "5" 643d03d3d91SMatt Spinler ``` 644d03d3d91SMatt Spinler 645d03d3d91SMatt Spinler 3. Check the PEL that was created using peltool. 646d03d3d91SMatt Spinler 4. When finished, delete the file from `/etc/phosphor-logging/`. 647