1 #pragma once 2 3 #include "additional_data.hpp" 4 #include "ascii_string.hpp" 5 #include "callouts.hpp" 6 #include "data_interface.hpp" 7 #include "pel_types.hpp" 8 #include "registry.hpp" 9 #include "section.hpp" 10 #include "stream.hpp" 11 12 namespace openpower 13 { 14 namespace pels 15 { 16 17 constexpr uint8_t srcSectionVersion = 0x01; 18 constexpr uint8_t srcSectionSubtype = 0x01; 19 constexpr size_t numSRCHexDataWords = 8; 20 constexpr uint8_t srcVersion = 0x02; 21 constexpr uint8_t bmcSRCFormat = 0x55; 22 constexpr uint8_t primaryBMCPosition = 0x10; 23 constexpr size_t baseSRCSize = 72; 24 25 enum class DetailLevel 26 { 27 message = 0x01, 28 json = 0x02 29 }; 30 /** 31 * @class SRC 32 * 33 * SRC stands for System Reference Code. 34 * 35 * This class represents the SRC sections in the PEL, of which there are 2: 36 * primary SRC and secondary SRC. These are the same structurally, the 37 * difference is that the primary SRC must be the 3rd section in the PEL if 38 * present and there is only one of them, and the secondary SRC sections are 39 * optional and there can be more than one (by definition, for there to be a 40 * secondary SRC, a primary SRC must also exist). 41 * 42 * This section consists of: 43 * - An 8B header (Has the version, flags, hexdata word count, and size fields) 44 * - 8 4B words of hex data 45 * - An ASCII character string 46 * - An optional subsection for Callouts 47 */ 48 class SRC : public Section 49 { 50 public: 51 enum HeaderFlags 52 { 53 additionalSections = 0x01, 54 powerFaultEvent = 0x02, 55 hypDumpInit = 0x04, 56 postOPPanel = 0x08, 57 i5OSServiceEventBit = 0x10, 58 virtualProgressSRC = 0x80 59 }; 60 61 /** 62 * @brief Enums for the error status bits in hex word 5 63 * of BMC SRCs. 64 */ 65 enum class ErrorStatusFlags : uint32_t 66 { 67 hwCheckstop = 0x80000000, 68 terminateFwErr = 0x20000000, 69 deconfigured = 0x02000000, 70 guarded = 0x01000000 71 }; 72 73 SRC() = delete; 74 ~SRC() = default; 75 SRC(const SRC&) = delete; 76 SRC& operator=(const SRC&) = delete; 77 SRC(SRC&&) = delete; 78 SRC& operator=(SRC&&) = delete; 79 80 /** 81 * @brief Constructor 82 * 83 * Fills in this class's data fields from the stream. 84 * 85 * @param[in] pel - the PEL data stream 86 */ 87 explicit SRC(Stream& pel); 88 89 /** 90 * @brief Constructor 91 * 92 * Creates the section with data from the PEL message registry entry for 93 * this error, along with the AdditionalData property contents from the 94 * corresponding event log. 95 * 96 * @param[in] regEntry - The message registry entry for this event log 97 * @param[in] additionalData - The AdditionalData properties in this event 98 * log 99 * @param[in] dataIface - The DataInterface object 100 */ SRC(const message::Entry & regEntry,const AdditionalData & additionalData,const DataInterfaceBase & dataIface)101 SRC(const message::Entry& regEntry, const AdditionalData& additionalData, 102 const DataInterfaceBase& dataIface) : 103 SRC(regEntry, additionalData, nlohmann::json{}, dataIface) 104 {} 105 106 /** 107 * @brief Constructor 108 * 109 * Creates the section with data from the PEL message registry entry for 110 * this error, along with the AdditionalData property contents from the 111 * corresponding event log, and a JSON array of callouts to add. 112 * 113 * @param[in] regEntry - The message registry entry for this event log 114 * @param[in] additionalData - The AdditionalData properties in this event 115 * log 116 * @param[in] jsonCallouts - The array of JSON callouts, or an empty object. 117 * @param[in] dataIface - The DataInterface object 118 */ 119 SRC(const message::Entry& regEntry, const AdditionalData& additionalData, 120 const nlohmann::json& jsonCallouts, const DataInterfaceBase& dataIface); 121 122 /** 123 * @brief Flatten the section into the stream 124 * 125 * @param[in] stream - The stream to write to 126 */ 127 void flatten(Stream& stream) const override; 128 129 /** 130 * @brief Returns the SRC version, which is a different field 131 * than the version byte in the section header. 132 * 133 * @return uint8_t 134 */ version() const135 uint8_t version() const 136 { 137 return _version; 138 } 139 140 /** 141 * @brief Returns the flags byte 142 * 143 * @return uint8_t 144 */ flags() const145 uint8_t flags() const 146 { 147 return _flags; 148 } 149 150 /** 151 * @brief Returns the hex data word count. 152 * 153 * Even though there always 8 words, this returns 9 due to previous 154 * SRC version formats. 155 * 156 * @return uint8_t 157 */ hexWordCount() const158 uint8_t hexWordCount() const 159 { 160 return _wordCount; 161 } 162 163 /** 164 * @brief Returns the size of the SRC section, not including the header. 165 * 166 * @return uint16_t 167 */ size() const168 uint16_t size() const 169 { 170 return _size; 171 } 172 173 /** 174 * @brief Returns the 8 hex data words. 175 * 176 * @return const std::array<uint32_t, numSRCHexDataWords>& 177 */ hexwordData() const178 const std::array<uint32_t, numSRCHexDataWords>& hexwordData() const 179 { 180 return _hexData; 181 } 182 183 /** 184 * @brief Returns the ASCII string 185 * 186 * @return std::string 187 */ asciiString() const188 std::string asciiString() const 189 { 190 return _asciiString->get(); 191 } 192 193 /** 194 * @brief Returns the callouts subsection 195 * 196 * If no callouts, this unique_ptr will be empty 197 * 198 * @return const std::unique_ptr<src::Callouts>& 199 */ callouts() const200 const std::unique_ptr<src::Callouts>& callouts() const 201 { 202 return _callouts; 203 } 204 205 /** 206 * @brief Returns the size of this section when flattened into a PEL 207 * 208 * @return size_t - the size of the section 209 */ flattenedSize() const210 size_t flattenedSize() const 211 { 212 return _header.size; 213 } 214 215 /** 216 * @brief Says if this SRC has additional subsections in it 217 * 218 * Note: The callouts section is the only possible subsection. 219 * 220 * @return bool 221 */ hasAdditionalSections() const222 inline bool hasAdditionalSections() const 223 { 224 return _flags & additionalSections; 225 } 226 227 /** 228 * @brief Indicates if this event log is for a power fault. 229 * 230 * This comes from a field in the message registry for BMC 231 * generated PELs. 232 * 233 * @return bool 234 */ isPowerFaultEvent() const235 inline bool isPowerFaultEvent() const 236 { 237 return _flags & powerFaultEvent; 238 } 239 240 /** 241 * @brief Get the _hexData[] index to use based on the corresponding 242 * SRC word number. 243 * 244 * Converts the specification nomenclature to this data structure. 245 * See the _hexData documentation below for more information. 246 * 247 * @param[in] wordNum - The SRC word number, as defined by the spec. 248 * 249 * @return size_t The corresponding index into _hexData. 250 */ getWordIndexFromWordNum(size_t wordNum) const251 inline size_t getWordIndexFromWordNum(size_t wordNum) const 252 { 253 assert(wordNum >= 2 && wordNum <= 9); 254 return wordNum - 2; 255 } 256 257 /** 258 * @brief Get section in JSON. 259 * @param[in] registry - Registry object reference 260 * @param[in] plugins - Vector of strings of plugins found in filesystem 261 * @param[in] creatorID - Creator Subsystem ID from Private Header 262 * @return std::optional<std::string> - SRC section's JSON 263 */ 264 std::optional<std::string> getJSON(message::Registry& registry, 265 const std::vector<std::string>& plugins, 266 uint8_t creatorID) const override; 267 268 /** 269 * @brief Get error details based on refcode and hexwords 270 * @param[in] registry - Registry object 271 * @param[in] type - detail level enum value : single message or full json 272 * @param[in] toCache - boolean to cache registry in memory, default=false 273 * @return std::optional<std::string> - Error details 274 */ 275 std::optional<std::string> 276 getErrorDetails(message::Registry& registry, DetailLevel type, 277 bool toCache = false) const; 278 279 /** 280 * @brief Says if this SRC was created by the BMC (i.e. this code). 281 * 282 * @return bool - If created by the BMC or not 283 */ 284 bool isBMCSRC() const; 285 286 /** 287 * @brief Says if this SRC was created by Hostboot 288 * 289 * @return bool - If created by Hostboot or not 290 */ 291 bool isHostbootSRC() const; 292 293 /** 294 * @brief Set the terminate bit in hex data word 3. 295 */ setTerminateBit()296 void setTerminateBit() 297 { 298 setErrorStatusFlag(ErrorStatusFlags::terminateFwErr); 299 } 300 301 /** 302 * @brief Get the SRC structure to pass on to the boot progress dbus 303 * interface. 304 * 305 * @return std::vector<uint8_t> - SRC struct data 306 */ 307 std::vector<uint8_t> getSrcStruct(); 308 309 /** 310 * @brief Extracts the first 8 characters of the ASCII String field 311 * from the raw progress SRC and converts it to a uint32_t. 312 * 313 * @param[in] rawProgressSRC - The progress SRC bytes 314 * 315 * @return uint32_t - The code, like 0xCC0099EE from "CC0099EE" 316 */ 317 static uint32_t getProgressCode(std::vector<uint8_t>& rawProgressSRC); 318 319 /** 320 * @brief Return the value of the passed in error status flag. 321 * 322 * @param[in] flag - The flag 323 * 324 * @return bool - If the flag is set. 325 */ getErrorStatusFlag(ErrorStatusFlags flag) const326 bool getErrorStatusFlag(ErrorStatusFlags flag) const 327 { 328 return _hexData[3] & static_cast<uint32_t>(flag); 329 } 330 331 /** 332 * @brief Clears an error status flag in the SRC. 333 * 334 * @param[in] flag - The flag to set 335 */ clearErrorStatusFlag(ErrorStatusFlags flag)336 void clearErrorStatusFlag(ErrorStatusFlags flag) 337 { 338 _hexData[3] &= ~static_cast<uint32_t>(flag); 339 } 340 341 private: 342 /** 343 * @brief Fills in the user defined hex words from the 344 * AdditionalData fields. 345 * 346 * When creating this section from a message registry entry, 347 * that entry has a field that says which AdditionalData property 348 * fields to use to fill in the user defined hex data words 6-9 349 * (which correspond to hexData words 4-7). 350 * 351 * For example, given that AdditionalData is a map of string keys 352 * to string values, find the AdditionalData value for AdditionalData 353 * key X, convert it to a uint32_t, and save it in user data word Y. 354 * 355 * @param[in] regEntry - The message registry entry for the error 356 * @param[in] additionalData - The AdditionalData map 357 */ 358 void setUserDefinedHexWords(const message::Entry& regEntry, 359 const AdditionalData& additionalData); 360 /** 361 * @brief Fills in the object from the stream data 362 * 363 * @param[in] stream - The stream to read from 364 */ 365 void unflatten(Stream& stream); 366 367 /** 368 * @brief Says if the word number is in the range of user defined words. 369 * 370 * This is only used for BMC generated SRCs, where words 6 - 9 are the 371 * user defined ones, meaning that setUserDefinedHexWords() will be 372 * used to fill them in based on the contents of the OpenBMC event log. 373 * 374 * @param[in] wordNum - The SRC word number, as defined by the spec. 375 * 376 * @return bool - If this word number can be filled in by the creator. 377 */ isUserDefinedWord(size_t wordNum) const378 inline bool isUserDefinedWord(size_t wordNum) const 379 { 380 return (wordNum >= 6) && (wordNum <= 9); 381 } 382 383 /** 384 * @brief Sets the SRC format byte in the hex word data. 385 */ setBMCFormat()386 inline void setBMCFormat() 387 { 388 _hexData[0] |= bmcSRCFormat; 389 } 390 391 /** 392 * @brief Sets the hex word field that specifies which BMC 393 * (primary vs backup) created the error. 394 * 395 * Can be hardcoded until there are systems with redundant BMCs. 396 */ setBMCPosition()397 inline void setBMCPosition() 398 { 399 _hexData[1] |= primaryBMCPosition; 400 } 401 402 /** 403 * @brief Sets the motherboard CCIN hex word field 404 * 405 * @param[in] dataIface - The DataInterface object 406 */ 407 void setMotherboardCCIN(const DataInterfaceBase& dataIface); 408 409 /** 410 * @brief Sets the progress code hex word field 411 * 412 * @param[in] dataIface - The DataInterface object 413 */ 414 void setProgressCode(const DataInterfaceBase& dataIface); 415 416 /** 417 * @brief Sets an error status bit in the SRC. 418 * 419 * @param[in] flag - The flag to set 420 */ setErrorStatusFlag(ErrorStatusFlags flag)421 void setErrorStatusFlag(ErrorStatusFlags flag) 422 { 423 _hexData[3] |= static_cast<uint32_t>(flag); 424 } 425 426 /** 427 * @brief Validates the section contents 428 * 429 * Updates _valid (in Section) with the results. 430 */ 431 void validate() override; 432 433 /** 434 * @brief Get error description from message registry 435 * @param[in] regEntry - The message registry entry for the error 436 * @return std::optional<std::string> - Error message 437 */ 438 std::optional<std::string> 439 getErrorMessage(const message::Entry& regEntry) const; 440 441 /** 442 * @brief Get Callout info in JSON 443 * @return std::optional<std::string> - Callout details 444 */ 445 std::optional<std::string> getCallouts() const; 446 447 /** 448 * @brief Checks the AdditionalData property and the message registry 449 * JSON and adds any necessary callouts. 450 * 451 * The callout sources are the AdditionalData event log property 452 * and the message registry JSON. 453 * 454 * @param[in] regEntry - The message registry entry for the error 455 * @param[in] additionalData - The AdditionalData values 456 * @param[in] jsonCallouts - The array of JSON callouts, or an empty object 457 * @param[in] dataIface - The DataInterface object 458 */ 459 void addCallouts(const message::Entry& regEntry, 460 const AdditionalData& additionalData, 461 const nlohmann::json& jsonCallouts, 462 const DataInterfaceBase& dataIface); 463 464 /** 465 * @brief Adds a FRU callout based on an inventory path 466 * 467 * @param[in] inventoryPath - The inventory item to call out 468 * @param[in] priority - An optional priority (uses high if nullopt) 469 * @param[in] locationCode - The expanded location code (or look it up) 470 * @param[in] dataIface - The DataInterface object 471 * @param[in] mrus - The MRUs to add to the callout 472 */ 473 void addInventoryCallout( 474 const std::string& inventoryPath, 475 const std::optional<CalloutPriority>& priority, 476 const std::optional<std::string>& locationCode, 477 const DataInterfaceBase& dataIface, 478 const std::vector<src::MRU::MRUCallout>& mrus = {}); 479 480 /** 481 * @brief Returns the callouts to use from the registry entry. 482 * 483 * @param[in] regEntry - The message registry entry for the error 484 * @param[in] additionalData - The AdditionalData property 485 * @param[in] dataIface - The DataInterface object 486 */ 487 std::vector<message::RegistryCallout> getRegistryCallouts( 488 const message::Entry& regEntry, const AdditionalData& additionalData, 489 const DataInterfaceBase& dataIface); 490 491 /** 492 * @brief Adds the FRU callouts from the list of registry callouts 493 * passed in to the SRC. 494 * 495 * The last parameter is used only in a special case when the first 496 * callout is a symbolic FRU with a trusted location code. See the 497 * addRegistryCallout documentation. 498 * 499 * @param[in] callouts - The message registry callouts to add 500 * @param[in] dataIface - The DataInterface object 501 * @param[in] trustedSymbolicFRUInvPath - The optional inventory path used 502 * in the symbolic FRU case. 503 */ 504 void addRegistryCallouts( 505 const std::vector<message::RegistryCallout>& callouts, 506 const DataInterfaceBase& dataIface, 507 std::optional<std::string> trustedSymbolicFRUInvPath); 508 509 /** 510 * @brief Adds a single FRU callout from the message registry. 511 * 512 * If the last parameter is filled in, and the registry callout is a 513 * symbolic FRU callout with a trusted location code, and it has the 514 * 'useInventoryLocCode' member set to true, then the location code of 515 * that inventory item will be what is used for that trusted location code. 516 * 517 * @param[in] callout - The registry callout structure 518 * @param[in] dataIface - The DataInterface object 519 * @param[in] trustedSymbolicFRUInvPath - The optional inventory path used 520 * in the symbolic FRU case. 521 */ 522 void addRegistryCallout( 523 const message::RegistryCallout& callout, 524 const DataInterfaceBase& dataIface, 525 const std::optional<std::string>& trustedSymbolicFRUInvPath); 526 527 /** 528 * @brief Creates the Callouts object _callouts 529 * so that callouts can be added to it. 530 */ createCalloutsObject()531 void createCalloutsObject() 532 { 533 if (!_callouts) 534 { 535 _callouts = std::make_unique<src::Callouts>(); 536 _flags |= additionalSections; 537 } 538 } 539 540 /** 541 * @brief Adds any FRU callouts based on a device path in the 542 * AdditionalData parameter. 543 * 544 * @param[in] additionalData - The AdditionalData values 545 * @param[in] dataIface - The DataInterface object 546 */ 547 void addDevicePathCallouts(const AdditionalData& additionalData, 548 const DataInterfaceBase& dataIface); 549 550 /** 551 * @brief Adds any FRU callouts specified in the incoming JSON. 552 * 553 * @param[in] jsonCallouts - The JSON array of callouts 554 * @param[in] dataIface - The DataInterface object 555 */ 556 void addJSONCallouts(const nlohmann::json& jsonCallouts, 557 const DataInterfaceBase& dataIface); 558 559 /** 560 * @brief Adds a single callout based on the JSON 561 * 562 * @param[in] jsonCallouts - A single callout entry 563 * @param[in] dataIface - The DataInterface object 564 */ 565 void addJSONCallout(const nlohmann::json& jsonCallout, 566 const DataInterfaceBase& dataIface); 567 568 /** 569 * @brief Extracts a CalloutPriority value from the json 570 * using the 'Priority' key. 571 * 572 * @param[in] json - A JSON object that contains the priority key 573 * 574 * @return CalloutPriority - The priority value 575 */ 576 CalloutPriority getPriorityFromJSON(const nlohmann::json& json); 577 578 /** 579 * @brief Exracts MRU values and their priorities from the 580 * input JSON array. 581 * 582 * @param[in] mruJSON - The JSON array 583 */ 584 std::vector<src::MRU::MRUCallout> 585 getMRUsFromJSON(const nlohmann::json& mruJSON); 586 587 /** 588 * @brief The SRC version field 589 */ 590 uint8_t _version; 591 592 /** 593 * @brief The SRC flags field 594 */ 595 uint8_t _flags; 596 597 /** 598 * @brief A byte of reserved data after the flags field 599 */ 600 uint8_t _reserved1B; 601 602 /** 603 * @brief The hex data word count. 604 * 605 * To be compatible with previous versions of SRCs, this is 606 * number of hex words (8) + 1 = 9. 607 */ 608 uint8_t _wordCount; 609 610 /** 611 * @brief Two bytes of reserved data after the hex word count 612 */ 613 uint16_t _reserved2B; 614 615 /** 616 * @brief The total size of the SRC section, not including the section 617 * header. 618 */ 619 uint16_t _size; 620 621 /** 622 * @brief The SRC 'hex words'. 623 * 624 * In the spec these are referred to as SRC words 2 - 9 as words 0 and 1 625 * are filled by the 8 bytes of fields from above. 626 */ 627 std::array<uint32_t, numSRCHexDataWords> _hexData; 628 629 /** 630 * @brief The 32 byte ASCII character string of the SRC 631 * 632 * It is padded with spaces to fill the 32 bytes. 633 * An example is: 634 * "BD8D1234 " 635 * 636 * That first word is what is commonly referred to as the refcode, and 637 * sometimes also called an SRC. 638 */ 639 std::unique_ptr<src::AsciiString> _asciiString; 640 641 /** 642 * @brief The callouts subsection. 643 * 644 * Optional and only created if there are callouts. 645 */ 646 std::unique_ptr<src::Callouts> _callouts; 647 }; 648 649 } // namespace pels 650 } // namespace openpower 651