xref: /openbmc/phosphor-logging/extensions/openpower-pels/src.hpp (revision 0dd22c8301e3f132ca50a8f76860eb55af78eff5)
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