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 66 { 67 terminateFwErr = 0x20000000, 68 deconfigured = 0x02000000, 69 guarded = 0x01000000 70 }; 71 72 SRC() = delete; 73 ~SRC() = default; 74 SRC(const SRC&) = delete; 75 SRC& operator=(const SRC&) = delete; 76 SRC(SRC&&) = delete; 77 SRC& operator=(SRC&&) = delete; 78 79 /** 80 * @brief Constructor 81 * 82 * Fills in this class's data fields from the stream. 83 * 84 * @param[in] pel - the PEL data stream 85 */ 86 explicit SRC(Stream& pel); 87 88 /** 89 * @brief Constructor 90 * 91 * Creates the section with data from the PEL message registry entry for 92 * this error, along with the AdditionalData property contents from the 93 * corresponding event log. 94 * 95 * @param[in] regEntry - The message registry entry for this event log 96 * @param[in] additionalData - The AdditionalData properties in this event 97 * log 98 * @param[in] dataIface - The DataInterface object 99 */ 100 SRC(const message::Entry& regEntry, const AdditionalData& additionalData, 101 const DataInterfaceBase& dataIface) : 102 SRC(regEntry, additionalData, nlohmann::json{}, dataIface) 103 {} 104 105 /** 106 * @brief Constructor 107 * 108 * Creates the section with data from the PEL message registry entry for 109 * this error, along with the AdditionalData property contents from the 110 * corresponding event log, and a JSON array of callouts to add. 111 * 112 * @param[in] regEntry - The message registry entry for this event log 113 * @param[in] additionalData - The AdditionalData properties in this event 114 * log 115 * @param[in] jsonCallouts - The array of JSON callouts, or an empty object. 116 * @param[in] dataIface - The DataInterface object 117 */ 118 SRC(const message::Entry& regEntry, const AdditionalData& additionalData, 119 const nlohmann::json& jsonCallouts, const DataInterfaceBase& dataIface); 120 121 /** 122 * @brief Flatten the section into the stream 123 * 124 * @param[in] stream - The stream to write to 125 */ 126 void flatten(Stream& stream) const override; 127 128 /** 129 * @brief Returns the SRC version, which is a different field 130 * than the version byte in the section header. 131 * 132 * @return uint8_t 133 */ 134 uint8_t version() const 135 { 136 return _version; 137 } 138 139 /** 140 * @brief Returns the flags byte 141 * 142 * @return uint8_t 143 */ 144 uint8_t flags() const 145 { 146 return _flags; 147 } 148 149 /** 150 * @brief Returns the hex data word count. 151 * 152 * Even though there always 8 words, this returns 9 due to previous 153 * SRC version formats. 154 * 155 * @return uint8_t 156 */ 157 uint8_t hexWordCount() const 158 { 159 return _wordCount; 160 } 161 162 /** 163 * @brief Returns the size of the SRC section, not including the header. 164 * 165 * @return uint16_t 166 */ 167 uint16_t size() const 168 { 169 return _size; 170 } 171 172 /** 173 * @brief Returns the 8 hex data words. 174 * 175 * @return const std::array<uint32_t, numSRCHexDataWords>& 176 */ 177 const std::array<uint32_t, numSRCHexDataWords>& hexwordData() const 178 { 179 return _hexData; 180 } 181 182 /** 183 * @brief Returns the ASCII string 184 * 185 * @return std::string 186 */ 187 std::string asciiString() const 188 { 189 return _asciiString->get(); 190 } 191 192 /** 193 * @brief Returns the callouts subsection 194 * 195 * If no callouts, this unique_ptr will be empty 196 * 197 * @return const std::unique_ptr<src::Callouts>& 198 */ 199 const std::unique_ptr<src::Callouts>& callouts() const 200 { 201 return _callouts; 202 } 203 204 /** 205 * @brief Returns the size of this section when flattened into a PEL 206 * 207 * @return size_t - the size of the section 208 */ 209 size_t flattenedSize() const 210 { 211 return _header.size; 212 } 213 214 /** 215 * @brief Says if this SRC has additional subsections in it 216 * 217 * Note: The callouts section is the only possible subsection. 218 * 219 * @return bool 220 */ 221 inline bool hasAdditionalSections() const 222 { 223 return _flags & additionalSections; 224 } 225 226 /** 227 * @brief Indicates if this event log is for a power fault. 228 * 229 * This comes from a field in the message registry for BMC 230 * generated PELs. 231 * 232 * @return bool 233 */ 234 inline bool isPowerFaultEvent() const 235 { 236 return _flags & powerFaultEvent; 237 } 238 239 /** 240 * @brief Get the _hexData[] index to use based on the corresponding 241 * SRC word number. 242 * 243 * Converts the specification nomenclature to this data structure. 244 * See the _hexData documentation below for more information. 245 * 246 * @param[in] wordNum - The SRC word number, as defined by the spec. 247 * 248 * @return size_t The corresponding index into _hexData. 249 */ 250 inline size_t getWordIndexFromWordNum(size_t wordNum) const 251 { 252 assert(wordNum >= 2 && wordNum <= 9); 253 return wordNum - 2; 254 } 255 256 /** 257 * @brief Get section in JSON. 258 * @param[in] registry - Registry object reference 259 * @param[in] plugins - Vector of strings of plugins found in filesystem 260 * @param[in] creatorID - Creator Subsystem ID from Private Header 261 * @return std::optional<std::string> - SRC section's JSON 262 */ 263 std::optional<std::string> getJSON(message::Registry& registry, 264 const std::vector<std::string>& plugins, 265 uint8_t creatorID) const override; 266 267 /** 268 * @brief Get error details based on refcode and hexwords 269 * @param[in] registry - Registry object 270 * @param[in] type - detail level enum value : single message or full json 271 * @param[in] toCache - boolean to cache registry in memory, default=false 272 * @return std::optional<std::string> - Error details 273 */ 274 std::optional<std::string> getErrorDetails(message::Registry& registry, 275 DetailLevel type, 276 bool toCache = false) const; 277 278 /** 279 * @brief Says if this SRC was created by the BMC (i.e. this code). 280 * 281 * @return bool - If created by the BMC or not 282 */ 283 bool isBMCSRC() const; 284 285 /** 286 * @brief Says if this SRC was created by Hostboot 287 * 288 * @return bool - If created by Hostboot or not 289 */ 290 bool isHostbootSRC() const; 291 292 /** 293 * @brief Set the terminate bit in hex data word 3. 294 */ 295 void setTerminateBit() 296 { 297 setErrorStatusFlag(ErrorStatusFlags::terminateFwErr); 298 } 299 300 /** 301 * @brief Get the SRC structure to pass on to the boot progress dbus 302 * interface. 303 * 304 * @return std::vector<uint8_t> - SRC struct data 305 */ 306 std::vector<uint8_t> getSrcStruct(); 307 308 /** 309 * @brief Extracts the first 8 characters of the ASCII String field 310 * from the raw progress SRC and converts it to a uint32_t. 311 * 312 * @param[in] rawProgressSRC - The progress SRC bytes 313 * 314 * @return uint32_t - The code, like 0xCC0099EE from "CC0099EE" 315 */ 316 static uint32_t getProgressCode(std::vector<uint8_t>& rawProgressSRC); 317 318 /** 319 * @brief Return the value of the passed in error status flag. 320 * 321 * @param[in] flag - The flag 322 * 323 * @return bool - If the flag is set. 324 */ 325 bool getErrorStatusFlag(ErrorStatusFlags flag) const 326 { 327 return _hexData[3] & static_cast<uint32_t>(flag); 328 } 329 330 /** 331 * @brief Clears an error status flag in the SRC. 332 * 333 * @param[in] flag - The flag to set 334 */ 335 void clearErrorStatusFlag(ErrorStatusFlags flag) 336 { 337 _hexData[3] &= ~static_cast<uint32_t>(flag); 338 } 339 340 private: 341 /** 342 * @brief Fills in the user defined hex words from the 343 * AdditionalData fields. 344 * 345 * When creating this section from a message registry entry, 346 * that entry has a field that says which AdditionalData property 347 * fields to use to fill in the user defined hex data words 6-9 348 * (which correspond to hexData words 4-7). 349 * 350 * For example, given that AdditionalData is a map of string keys 351 * to string values, find the AdditionalData value for AdditionalData 352 * key X, convert it to a uint32_t, and save it in user data word Y. 353 * 354 * @param[in] regEntry - The message registry entry for the error 355 * @param[in] additionalData - The AdditionalData map 356 */ 357 void setUserDefinedHexWords(const message::Entry& regEntry, 358 const AdditionalData& additionalData); 359 /** 360 * @brief Fills in the object from the stream data 361 * 362 * @param[in] stream - The stream to read from 363 */ 364 void unflatten(Stream& stream); 365 366 /** 367 * @brief Says if the word number is in the range of user defined words. 368 * 369 * This is only used for BMC generated SRCs, where words 6 - 9 are the 370 * user defined ones, meaning that setUserDefinedHexWords() will be 371 * used to fill them in based on the contents of the OpenBMC event log. 372 * 373 * @param[in] wordNum - The SRC word number, as defined by the spec. 374 * 375 * @return bool - If this word number can be filled in by the creator. 376 */ 377 inline bool isUserDefinedWord(size_t wordNum) const 378 { 379 return (wordNum >= 6) && (wordNum <= 9); 380 } 381 382 /** 383 * @brief Sets the SRC format byte in the hex word data. 384 */ 385 inline void setBMCFormat() 386 { 387 _hexData[0] |= bmcSRCFormat; 388 } 389 390 /** 391 * @brief Sets the hex word field that specifies which BMC 392 * (primary vs backup) created the error. 393 * 394 * Can be hardcoded until there are systems with redundant BMCs. 395 */ 396 inline void setBMCPosition() 397 { 398 _hexData[1] |= primaryBMCPosition; 399 } 400 401 /** 402 * @brief Sets the motherboard CCIN hex word field 403 * 404 * @param[in] dataIface - The DataInterface object 405 */ 406 void setMotherboardCCIN(const DataInterfaceBase& dataIface); 407 408 /** 409 * @brief Sets the progress code hex word field 410 * 411 * @param[in] dataIface - The DataInterface object 412 */ 413 void setProgressCode(const DataInterfaceBase& dataIface); 414 415 /** 416 * @brief Sets an error status bit in the SRC. 417 * 418 * @param[in] flag - The flag to set 419 */ 420 void setErrorStatusFlag(ErrorStatusFlags flag) 421 { 422 _hexData[3] |= static_cast<uint32_t>(flag); 423 } 424 425 /** 426 * @brief Validates the section contents 427 * 428 * Updates _valid (in Section) with the results. 429 */ 430 void validate() override; 431 432 /** 433 * @brief Get error description from message registry 434 * @param[in] regEntry - The message registry entry for the error 435 * @return std::optional<std::string> - Error message 436 */ 437 std::optional<std::string> 438 getErrorMessage(const message::Entry& regEntry) const; 439 440 /** 441 * @brief Get Callout info in JSON 442 * @return std::optional<std::string> - Callout details 443 */ 444 std::optional<std::string> getCallouts() const; 445 446 /** 447 * @brief Checks the AdditionalData property and the message registry 448 * JSON and adds any necessary callouts. 449 * 450 * The callout sources are the AdditionalData event log property 451 * and the message registry JSON. 452 * 453 * @param[in] regEntry - The message registry entry for the error 454 * @param[in] additionalData - The AdditionalData values 455 * @param[in] jsonCallouts - The array of JSON callouts, or an empty object 456 * @param[in] dataIface - The DataInterface object 457 */ 458 void addCallouts(const message::Entry& regEntry, 459 const AdditionalData& additionalData, 460 const nlohmann::json& jsonCallouts, 461 const DataInterfaceBase& dataIface); 462 463 /** 464 * @brief Adds a FRU callout based on an inventory path 465 * 466 * @param[in] inventoryPath - The inventory item to call out 467 * @param[in] priority - An optional priority (uses high if nullopt) 468 * @param[in] locationCode - The expanded location code (or look it up) 469 * @param[in] dataIface - The DataInterface object 470 * @param[in] mrus - The MRUs to add to the callout 471 */ 472 void 473 addInventoryCallout(const std::string& inventoryPath, 474 const std::optional<CalloutPriority>& priority, 475 const std::optional<std::string>& locationCode, 476 const DataInterfaceBase& dataIface, 477 const std::vector<src::MRU::MRUCallout>& mrus = {}); 478 479 /** 480 * @brief Returns the callouts to use from the registry entry. 481 * 482 * @param[in] regEntry - The message registry entry for the error 483 * @param[in] additionalData - The AdditionalData property 484 * @param[in] dataIface - The DataInterface object 485 */ 486 std::vector<message::RegistryCallout> 487 getRegistryCallouts(const message::Entry& regEntry, 488 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 */ 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 Sets the dump status 589 * 590 * @param[in] dataIface - The DataInterface object 591 */ 592 void setDumpStatus(const DataInterfaceBase& dataIface); 593 594 /** 595 * @brief The SRC version field 596 */ 597 uint8_t _version; 598 599 /** 600 * @brief The SRC flags field 601 */ 602 uint8_t _flags; 603 604 /** 605 * @brief A byte of reserved data after the flags field 606 */ 607 uint8_t _reserved1B; 608 609 /** 610 * @brief The hex data word count. 611 * 612 * To be compatible with previous versions of SRCs, this is 613 * number of hex words (8) + 1 = 9. 614 */ 615 uint8_t _wordCount; 616 617 /** 618 * @brief Two bytes of reserved data after the hex word count 619 */ 620 uint16_t _reserved2B; 621 622 /** 623 * @brief The total size of the SRC section, not including the section 624 * header. 625 */ 626 uint16_t _size; 627 628 /** 629 * @brief The SRC 'hex words'. 630 * 631 * In the spec these are referred to as SRC words 2 - 9 as words 0 and 1 632 * are filled by the 8 bytes of fields from above. 633 */ 634 std::array<uint32_t, numSRCHexDataWords> _hexData; 635 636 /** 637 * @brief The 32 byte ASCII character string of the SRC 638 * 639 * It is padded with spaces to fill the 32 bytes. 640 * An example is: 641 * "BD8D1234 " 642 * 643 * That first word is what is commonly referred to as the refcode, and 644 * sometimes also called an SRC. 645 */ 646 std::unique_ptr<src::AsciiString> _asciiString; 647 648 /** 649 * @brief The callouts subsection. 650 * 651 * Optional and only created if there are callouts. 652 */ 653 std::unique_ptr<src::Callouts> _callouts; 654 }; 655 656 } // namespace pels 657 } // namespace openpower 658