1*a96a7948SMatt Spinler# Platform Event Log Message Registry 2*a96a7948SMatt SpinlerOn the BMC, PELs are created from the standard event logs provided by 3*a96a7948SMatt Spinlerphosphor-logging using a message registry that provides the PEL related fields. 4*a96a7948SMatt SpinlerThe message registry is a JSON file. 5*a96a7948SMatt Spinler 6*a96a7948SMatt Spinler## Contents 7*a96a7948SMatt Spinler* [Component IDs](#component-ids) 8*a96a7948SMatt Spinler* [Message Registry](#message-registry-fields) 9*a96a7948SMatt Spinler 10*a96a7948SMatt Spinler## Component IDs 11*a96a7948SMatt SpinlerA component ID is a 2 byte value of the form 0xYY00 used in a PEL to: 12*a96a7948SMatt Spinler1. Provide the upper byte (the YY from above) of an SRC reason code in `BD` 13*a96a7948SMatt Spinler SRCs. 14*a96a7948SMatt Spinler2. Reside in the section header of the Private Header PEL section to specify 15*a96a7948SMatt Spinler the error log creator's component ID. 16*a96a7948SMatt Spinler3. Reside in the section header of the User Header section to specify the error 17*a96a7948SMatt Spinler log committer's component ID. 18*a96a7948SMatt Spinler4. Reside in the section header in the User Data section to specify which 19*a96a7948SMatt Spinler parser to call to parse that section. 20*a96a7948SMatt Spinler 21*a96a7948SMatt SpinlerComponent IDs are specified in the message registry either as the upper byte of 22*a96a7948SMatt Spinlerthe SRC reason code field for `BD` SRCs, or in the standalone `ComponentID` 23*a96a7948SMatt Spinlerfield. 24*a96a7948SMatt Spinler 25*a96a7948SMatt SpinlerComponent IDs will be unique on a per-repository basis for errors unique to 26*a96a7948SMatt Spinlerthat repository. When the same errors are created by multiple repositories, 27*a96a7948SMatt Spinlerthose errors will all share the same component ID. The master list of 28*a96a7948SMatt Spinlercomponent IDs is [here](ComponentIDs.md). 29*a96a7948SMatt Spinler 30*a96a7948SMatt Spinler## Message Registry Fields 31*a96a7948SMatt SpinlerThe message registry schema is [here](schema/schema.json), and the message 32*a96a7948SMatt Spinlerregistry itself is [here](message_registry.json). The schema will be validated 33*a96a7948SMatt Spinlereither during a bitbake build or during CI, or eventually possibly both. 34*a96a7948SMatt Spinler 35*a96a7948SMatt SpinlerIn the message registry, there are fields for specifying: 36*a96a7948SMatt Spinler 37*a96a7948SMatt Spinler### Name 38*a96a7948SMatt SpinlerThis is the key into the message registry, and is the Message property 39*a96a7948SMatt Spinlerof the OpenBMC event log that the PEL is being created from. 40*a96a7948SMatt Spinler 41*a96a7948SMatt Spinler``` 42*a96a7948SMatt Spinler"Name": "xyz.openbmc_project.Power.Fault" 43*a96a7948SMatt Spinler``` 44*a96a7948SMatt Spinler 45*a96a7948SMatt Spinler### Subsystem 46*a96a7948SMatt SpinlerThis field is part of the PEL User Header section, and is used to specify 47*a96a7948SMatt Spinlerthe subsystem pertaining to the error. It is an enumeration that maps to the 48*a96a7948SMatt Spinleractual PEL value. 49*a96a7948SMatt Spinler 50*a96a7948SMatt Spinler``` 51*a96a7948SMatt Spinler"Subsystem": "power_supply" 52*a96a7948SMatt Spinler``` 53*a96a7948SMatt Spinler 54*a96a7948SMatt Spinler### Severity 55*a96a7948SMatt SpinlerThis field is part of the PEL User Header section, and is used to specify 56*a96a7948SMatt Spinlerthe PEL severity. It is an optional field, if it isn't specified, then the 57*a96a7948SMatt Spinlerseverity of the OpenBMC event log will be converted into a PEL severity value. 58*a96a7948SMatt Spinler 59*a96a7948SMatt Spinler``` 60*a96a7948SMatt Spinler"Severity": "unrecoverable" 61*a96a7948SMatt Spinler``` 62*a96a7948SMatt Spinler 63*a96a7948SMatt Spinler### Mfg Severity 64*a96a7948SMatt SpinlerThis is an optional field and is used to override the Severity field when a 65*a96a7948SMatt Spinlerspecific manufacturing isolation mode is enabled. 66*a96a7948SMatt Spinler 67*a96a7948SMatt Spinler``` 68*a96a7948SMatt Spinler"MfgSeverity": "unrecoverable" 69*a96a7948SMatt Spinler``` 70*a96a7948SMatt Spinler 71*a96a7948SMatt Spinler### Event Scope 72*a96a7948SMatt SpinlerThis field is part of the PEL User Header section, and is used to specify 73*a96a7948SMatt Spinlerthe event scope, as defined by the PEL spec. It is optional and defaults to 74*a96a7948SMatt Spinler"entire platform". 75*a96a7948SMatt Spinler 76*a96a7948SMatt Spinler``` 77*a96a7948SMatt Spinler"EventScope": "entire_platform" 78*a96a7948SMatt Spinler``` 79*a96a7948SMatt Spinler 80*a96a7948SMatt Spinler### Event Type 81*a96a7948SMatt SpinlerThis field is part of the PEL User Header section, and is used to specify 82*a96a7948SMatt Spinlerthe event type, as defined by the PEL spec. It is optional and defaults to 83*a96a7948SMatt Spinler"not applicable". 84*a96a7948SMatt Spinler 85*a96a7948SMatt Spinler``` 86*a96a7948SMatt Spinler"EventType": "na" 87*a96a7948SMatt Spinler``` 88*a96a7948SMatt Spinler 89*a96a7948SMatt Spinler### Action Flags 90*a96a7948SMatt SpinlerThis field is part of the PEL User Header section, and is used to specify the 91*a96a7948SMatt SpinlerPEL action flags, as defined by the PEL spec. It is an array of enumerations. 92*a96a7948SMatt Spinler 93*a96a7948SMatt Spinler``` 94*a96a7948SMatt Spinler"ActionFlags": ["service_action", "report", "call_home"] 95*a96a7948SMatt Spinler``` 96*a96a7948SMatt Spinler 97*a96a7948SMatt Spinler### Mfg Action Flags 98*a96a7948SMatt SpinlerThis is an optional field and is used to override the Action Flags field when a 99*a96a7948SMatt Spinlerspecific manufacturing isolation mode is enabled. 100*a96a7948SMatt Spinler 101*a96a7948SMatt Spinler``` 102*a96a7948SMatt Spinler"MfgActionFlags": ["service_action", "report", "call_home"] 103*a96a7948SMatt Spinler``` 104*a96a7948SMatt Spinler 105*a96a7948SMatt Spinler### Component ID 106*a96a7948SMatt SpinlerThis is the component ID of the PEL creator, in the form 0xYY00. For `BD` 107*a96a7948SMatt SpinlerSRCs, this is an optional field and if not present the value will be taken from 108*a96a7948SMatt Spinlerthe upper byte of the reason code. If present for `BD` SRCs, then this byte 109*a96a7948SMatt Spinlermust match the upper byte of the reason code. 110*a96a7948SMatt Spinler 111*a96a7948SMatt Spinler``` 112*a96a7948SMatt Spinler"ComponentID": "0x5500" 113*a96a7948SMatt Spinler``` 114*a96a7948SMatt Spinler 115*a96a7948SMatt Spinler### SRC Type 116*a96a7948SMatt SpinlerThis specifies the type of SRC to create. The type is the first 2 characters 117*a96a7948SMatt Spinlerof the 8 character ASCII string field of the PEL. The allowed types are `BD`, 118*a96a7948SMatt Spinlerfor the standard OpenBMC error, and `11`, for power related errors. It is 119*a96a7948SMatt Spinleroptional and if not specified will default to `BD`. 120*a96a7948SMatt Spinler 121*a96a7948SMatt SpinlerNote: The ASCII string for BD SRCs looks like: `BDBBCCCC`, where: 122*a96a7948SMatt Spinler* BD = SRC type 123*a96a7948SMatt Spinler* BB = PEL subsystem as mentioned above 124*a96a7948SMatt Spinler* CCCC SRC reason code 125*a96a7948SMatt Spinler 126*a96a7948SMatt SpinlerFor `11` SRCs, it looks like: `1100RRRR`, where RRRR is the SRC reason code. 127*a96a7948SMatt Spinler 128*a96a7948SMatt Spinler``` 129*a96a7948SMatt Spinler"Type": "11" 130*a96a7948SMatt Spinler``` 131*a96a7948SMatt Spinler 132*a96a7948SMatt Spinler### SRC Reason Code 133*a96a7948SMatt SpinlerThis is the 4 character value in the latter half of the SRC ASCII string. It 134*a96a7948SMatt Spinleris treated as a 2 byte hex value, such as 0x5678. For `BD` SRCs, the first 135*a96a7948SMatt Spinlerbyte is the same as the first byte of the component ID field in the Private 136*a96a7948SMatt SpinlerHeader section that represents the creator's component ID. 137*a96a7948SMatt Spinler 138*a96a7948SMatt Spinler``` 139*a96a7948SMatt Spinler"ReasonCode": "0x5544" 140*a96a7948SMatt Spinler``` 141*a96a7948SMatt Spinler 142*a96a7948SMatt Spinler### SRC Symptom ID Fields 143*a96a7948SMatt SpinlerThe symptom ID is in the Extended User Header section and is defined in the PEL 144*a96a7948SMatt Spinlerspec as the unique event signature string. It always starts with the ASCII 145*a96a7948SMatt Spinlerstring. This field in the message registry allows one to choose which SRC words 146*a96a7948SMatt Spinlerto use in addition to the ASCII string field to form the symptom ID. All words 147*a96a7948SMatt Spinlerare separated by underscores. If not specified, the code will choose a default 148*a96a7948SMatt Spinlerformat, which may depend on the SRC type. 149*a96a7948SMatt Spinler 150*a96a7948SMatt SpinlerFor example: ["SRCWord3", "SRCWord9"] would be: 151*a96a7948SMatt Spinler`<ASCII_STRING>_<SRCWord3>_<SRCWord9>`, which could look like: 152*a96a7948SMatt Spinler`B181320_00000050_49000000`. 153*a96a7948SMatt Spinler 154*a96a7948SMatt Spinler``` 155*a96a7948SMatt Spinler"SymptomIDFields": ["SRCWord3", "SRCWord9"] 156*a96a7948SMatt Spinler``` 157*a96a7948SMatt Spinler 158*a96a7948SMatt Spinler### SRC words 6 to 9 159*a96a7948SMatt SpinlerIn a PEL, these SRC words are free format and can be filled in by the user as 160*a96a7948SMatt Spinlerdesired. On the BMC, the source of these words is the AdditionalData fields in 161*a96a7948SMatt Spinlerthe event log. The message registry provides a way for the log creator to 162*a96a7948SMatt Spinlerspecify which AdditionalData property field to get the data from, and also to 163*a96a7948SMatt Spinlerdefine what the SRC word means for use by parsers. If not specified, these SRC 164*a96a7948SMatt Spinlerwords will be set to zero in the PEL. 165*a96a7948SMatt Spinler 166*a96a7948SMatt Spinler``` 167*a96a7948SMatt Spinler"Words6to9": 168*a96a7948SMatt Spinler{ 169*a96a7948SMatt Spinler "6": 170*a96a7948SMatt Spinler { 171*a96a7948SMatt Spinler "description": "Failing unit number", 172*a96a7948SMatt Spinler "AdditionalDataPropSource": "PS_NUM" 173*a96a7948SMatt Spinler } 174*a96a7948SMatt Spinler} 175*a96a7948SMatt Spinler``` 176*a96a7948SMatt Spinler 177*a96a7948SMatt Spinler### SRC Power Fault flag 178*a96a7948SMatt SpinlerThe SRC has a bit in it to indicate if the error is a power fault. This is an 179*a96a7948SMatt Spinleroptional field in the message registry and defaults to false. 180*a96a7948SMatt Spinler 181*a96a7948SMatt Spinler``` 182*a96a7948SMatt Spinler"PowerFault: false 183*a96a7948SMatt Spinler``` 184*a96a7948SMatt Spinler 185*a96a7948SMatt Spinler### Documentation Fields 186*a96a7948SMatt SpinlerThe documentation fields are used by PEL parsers to display a human readable 187*a96a7948SMatt Spinlerdescription of a PEL. They are also the source for the Redfish event log 188*a96a7948SMatt Spinlermessages. 189*a96a7948SMatt Spinler 190*a96a7948SMatt Spinler#### Message 191*a96a7948SMatt SpinlerThis field is used by the BMC's PEL parser as the description of the error log. 192*a96a7948SMatt SpinlerIt will also be used in Redfish event logs. It supports argument substitution 193*a96a7948SMatt Spinlerusing the %1, %2, etc placeholders allowing any of the SRC user data words 6 - 194*a96a7948SMatt Spinler9 to be displayed as part of the message. If the placeholders are used, then 195*a96a7948SMatt Spinlerthe `MessageArgSources` property must be present to say which SRC words to use 196*a96a7948SMatt Spinlerfor each placeholder. 197*a96a7948SMatt Spinler 198*a96a7948SMatt Spinler``` 199*a96a7948SMatt Spinler"Message": "Processor %1 had %2 errors" 200*a96a7948SMatt Spinler``` 201*a96a7948SMatt Spinler 202*a96a7948SMatt Spinler#### MessageArgSources 203*a96a7948SMatt SpinlerThis optional field is required when the Message field contains the %X 204*a96a7948SMatt Spinlerplaceholder arguments. It is an array that says which SRC words to get the 205*a96a7948SMatt Spinlerplaceholders from. In the example below, SRC word 6 would be used for %1, and 206*a96a7948SMatt SpinlerSRC word 7 for %2. 207*a96a7948SMatt Spinler 208*a96a7948SMatt Spinler``` 209*a96a7948SMatt Spinler"MessageArgSources": 210*a96a7948SMatt Spinler[ 211*a96a7948SMatt Spinler "SRCWord6", "SRCWord7" 212*a96a7948SMatt Spinler] 213*a96a7948SMatt Spinler``` 214*a96a7948SMatt Spinler 215*a96a7948SMatt Spinler#### Description 216*a96a7948SMatt SpinlerA short description of the error. This is required by the Redfish schema to generate a Redfish message entry, but is not used in Redfish or PEL output. 217*a96a7948SMatt Spinler 218*a96a7948SMatt Spinler``` 219*a96a7948SMatt Spinler"Description": "A power fault" 220*a96a7948SMatt Spinler``` 221*a96a7948SMatt Spinler 222*a96a7948SMatt Spinler#### Notes 223*a96a7948SMatt SpinlerThis is an optional free format text field for keeping any notes for the 224*a96a7948SMatt Spinlerregistry entry, as comments are not allowed in JSON. It is an array of strings 225*a96a7948SMatt Spinlerfor easier readability of long fields. 226*a96a7948SMatt Spinler 227*a96a7948SMatt Spinler``` 228*a96a7948SMatt Spinler"Notes": [ 229*a96a7948SMatt Spinler "This entry is for every type of power fault.", 230*a96a7948SMatt Spinler "There is probably a hardware failure." 231*a96a7948SMatt Spinler] 232*a96a7948SMatt Spinler``` 233