xref: /openbmc/phosphor-logging/extensions/openpower-pels/src.hpp (revision 8e65f4ea9ca7ce1045a4e001571b5ef9b57732c5)
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 Set the terminate bit in hex data word 3.
287      */
288     void setTerminateBit()
289     {
290         setErrorStatusFlag(ErrorStatusFlags::terminateFwErr);
291     }
292 
293     /**
294      * @brief Get the SRC structure to pass on to the boot progress dbus
295      * interface.
296      *
297      * @return std::vector<uint8_t> - SRC struct data
298      */
299     std::vector<uint8_t> getSrcStruct();
300 
301     /**
302      * @brief Extracts the first 8 characters of the ASCII String field
303      *        from the raw progress SRC and converts it to a uint32_t.
304      *
305      * @param[in] rawProgressSRC - The progress SRC bytes
306      *
307      * @return uint32_t - The code, like 0xCC0099EE from "CC0099EE"
308      */
309     static uint32_t getProgressCode(std::vector<uint8_t>& rawProgressSRC);
310 
311     /**
312      * @brief Return the value of the passed in error status flag.
313      *
314      * @param[in] flag - The flag
315      *
316      * @return bool - If the flag is set.
317      */
318     bool getErrorStatusFlag(ErrorStatusFlags flag) const
319     {
320         return _hexData[3] & static_cast<uint32_t>(flag);
321     }
322 
323   private:
324     /**
325      * @brief Fills in the user defined hex words from the
326      *        AdditionalData fields.
327      *
328      * When creating this section from a message registry entry,
329      * that entry has a field that says which AdditionalData property
330      * fields to use to fill in the user defined hex data words 6-9
331      * (which correspond to hexData words 4-7).
332      *
333      * For example, given that AdditionalData is a map of string keys
334      * to string values, find the AdditionalData value for AdditionalData
335      * key X, convert it to a uint32_t, and save it in user data word Y.
336      *
337      * @param[in] regEntry - The message registry entry for the error
338      * @param[in] additionalData - The AdditionalData map
339      */
340     void setUserDefinedHexWords(const message::Entry& regEntry,
341                                 const AdditionalData& additionalData);
342     /**
343      * @brief Fills in the object from the stream data
344      *
345      * @param[in] stream - The stream to read from
346      */
347     void unflatten(Stream& stream);
348 
349     /**
350      * @brief Says if the word number is in the range of user defined words.
351      *
352      * This is only used for BMC generated SRCs, where words 6 - 9 are the
353      * user defined ones, meaning that setUserDefinedHexWords() will be
354      * used to fill them in based on the contents of the OpenBMC event log.
355      *
356      * @param[in] wordNum - The SRC word number, as defined by the spec.
357      *
358      * @return bool - If this word number can be filled in by the creator.
359      */
360     inline bool isUserDefinedWord(size_t wordNum) const
361     {
362         return (wordNum >= 6) && (wordNum <= 9);
363     }
364 
365     /**
366      * @brief Sets the SRC format byte in the hex word data.
367      */
368     inline void setBMCFormat()
369     {
370         _hexData[0] |= bmcSRCFormat;
371     }
372 
373     /**
374      * @brief Sets the hex word field that specifies which BMC
375      *        (primary vs backup) created the error.
376      *
377      * Can be hardcoded until there are systems with redundant BMCs.
378      */
379     inline void setBMCPosition()
380     {
381         _hexData[1] |= primaryBMCPosition;
382     }
383 
384     /**
385      * @brief Sets the motherboard CCIN hex word field
386      *
387      * @param[in] dataIface - The DataInterface object
388      */
389     void setMotherboardCCIN(const DataInterfaceBase& dataIface);
390 
391     /**
392      * @brief Sets the progress code hex word field
393      *
394      * @param[in] dataIface - The DataInterface object
395      */
396     void setProgressCode(const DataInterfaceBase& dataIface);
397 
398     /**
399      * @brief Sets an error status bit in the SRC.
400      *
401      * @param[in] flag - The flag to set
402      */
403     void setErrorStatusFlag(ErrorStatusFlags flag)
404     {
405         _hexData[3] |= static_cast<uint32_t>(flag);
406     }
407 
408     /**
409      * @brief Validates the section contents
410      *
411      * Updates _valid (in Section) with the results.
412      */
413     void validate() override;
414 
415     /**
416      * @brief Get error description from message registry
417      * @param[in] regEntry - The message registry entry for the error
418      * @return std::optional<std::string> - Error message
419      */
420     std::optional<std::string>
421         getErrorMessage(const message::Entry& regEntry) const;
422 
423     /**
424      * @brief Get Callout info in JSON
425      * @return std::optional<std::string> - Callout details
426      */
427     std::optional<std::string> getCallouts() const;
428 
429     /**
430      * @brief Checks the AdditionalData property and the message registry
431      *        JSON and adds any necessary callouts.
432      *
433      * The callout sources are the AdditionalData event log property
434      * and the message registry JSON.
435      *
436      * @param[in] regEntry - The message registry entry for the error
437      * @param[in] additionalData - The AdditionalData values
438      * @param[in] jsonCallouts - The array of JSON callouts, or an empty object
439      * @param[in] dataIface - The DataInterface object
440      */
441     void addCallouts(const message::Entry& regEntry,
442                      const AdditionalData& additionalData,
443                      const nlohmann::json& jsonCallouts,
444                      const DataInterfaceBase& dataIface);
445 
446     /**
447      * @brief Adds a FRU callout based on an inventory path
448      *
449      * @param[in] inventoryPath - The inventory item to call out
450      * @param[in] priority - An optional priority (uses high if nullopt)
451      * @param[in] locationCode - The expanded location code (or look it up)
452      * @param[in] dataIface - The DataInterface object
453      * @param[in] mrus - The MRUs to add to the callout
454      */
455     void
456         addInventoryCallout(const std::string& inventoryPath,
457                             const std::optional<CalloutPriority>& priority,
458                             const std::optional<std::string>& locationCode,
459                             const DataInterfaceBase& dataIface,
460                             const std::vector<src::MRU::MRUCallout>& mrus = {});
461 
462     /**
463      * @brief Returns the callouts to use from the registry entry.
464      *
465      * @param[in] regEntry - The message registry entry for the error
466      * @param[in] additionalData - The AdditionalData property
467      * @param[in] dataIface - The DataInterface object
468      */
469     std::vector<message::RegistryCallout>
470         getRegistryCallouts(const message::Entry& regEntry,
471                             const AdditionalData& additionalData,
472                             const DataInterfaceBase& dataIface);
473 
474     /**
475      * @brief Adds the FRU callouts from the list of registry callouts
476      *        passed in to the SRC.
477      *
478      * The last parameter is used only in a special case when the first
479      * callout is a symbolic FRU with a trusted location code.  See the
480      * addRegistryCallout documentation.
481      *
482      * @param[in] callouts - The message registry callouts to add
483      * @param[in] dataIface - The DataInterface object
484      * @param[in] trustedSymbolicFRUInvPath - The optional inventory path used
485      *                                        in the symbolic FRU case.
486      */
487     void addRegistryCallouts(
488         const std::vector<message::RegistryCallout>& callouts,
489         const DataInterfaceBase& dataIface,
490         std::optional<std::string> trustedSymbolicFRUInvPath);
491 
492     /**
493      * @brief Adds a single FRU callout from the message registry.
494      *
495      * If the last parameter is filled in, and the registry callout is a
496      * symbolic FRU callout with a trusted location code, and it has the
497      * 'useInventoryLocCode' member set to true, then the location code of
498      * that inventory item will be what is used for that trusted location code.
499      *
500      * @param[in] callout - The registry callout structure
501      * @param[in] dataIface - The DataInterface object
502      * @param[in] trustedSymbolicFRUInvPath - The optional inventory path used
503      *                                        in the symbolic FRU case.
504      */
505     void addRegistryCallout(
506         const message::RegistryCallout& callout,
507         const DataInterfaceBase& dataIface,
508         const std::optional<std::string>& trustedSymbolicFRUInvPath);
509 
510     /**
511      * @brief Creates the Callouts object _callouts
512      *        so that callouts can be added to it.
513      */
514     void createCalloutsObject()
515     {
516         if (!_callouts)
517         {
518             _callouts = std::make_unique<src::Callouts>();
519             _flags |= additionalSections;
520         }
521     }
522 
523     /**
524      * @brief Adds any FRU callouts based on a device path in the
525      *        AdditionalData parameter.
526      *
527      * @param[in] additionalData - The AdditionalData values
528      * @param[in] dataIface - The DataInterface object
529      */
530     void addDevicePathCallouts(const AdditionalData& additionalData,
531                                const DataInterfaceBase& dataIface);
532 
533     /**
534      * @brief Adds any FRU callouts specified in the incoming JSON.
535      *
536      * @param[in] jsonCallouts - The JSON array of callouts
537      * @param[in] dataIface - The DataInterface object
538      */
539     void addJSONCallouts(const nlohmann::json& jsonCallouts,
540                          const DataInterfaceBase& dataIface);
541 
542     /**
543      * @brief Adds a single callout based on the JSON
544      *
545      * @param[in] jsonCallouts - A single callout entry
546      * @param[in] dataIface - The DataInterface object
547      */
548     void addJSONCallout(const nlohmann::json& jsonCallout,
549                         const DataInterfaceBase& dataIface);
550 
551     /**
552      * @brief Extracts a CalloutPriority value from the json
553      *        using the 'Priority' key.
554      *
555      * @param[in] json - A JSON object that contains the priority key
556      *
557      * @return CalloutPriority - The priority value
558      */
559     CalloutPriority getPriorityFromJSON(const nlohmann::json& json);
560 
561     /**
562      * @brief Exracts MRU values and their priorities from the
563      *        input JSON array.
564      *
565      * @param[in] mruJSON - The JSON array
566      */
567     std::vector<src::MRU::MRUCallout>
568         getMRUsFromJSON(const nlohmann::json& mruJSON);
569 
570     /**
571      * @brief Sets the dump status
572      *
573      * @param[in] dataIface - The DataInterface object
574      */
575     void setDumpStatus(const DataInterfaceBase& dataIface);
576 
577     /**
578      * @brief The SRC version field
579      */
580     uint8_t _version;
581 
582     /**
583      * @brief The SRC flags field
584      */
585     uint8_t _flags;
586 
587     /**
588      * @brief A byte of reserved data after the flags field
589      */
590     uint8_t _reserved1B;
591 
592     /**
593      * @brief The hex data word count.
594      *
595      * To be compatible with previous versions of SRCs, this is
596      * number of hex words (8) + 1 = 9.
597      */
598     uint8_t _wordCount;
599 
600     /**
601      * @brief Two bytes of reserved data after the hex word count
602      */
603     uint16_t _reserved2B;
604 
605     /**
606      * @brief The total size of the SRC section, not including the section
607      *        header.
608      */
609     uint16_t _size;
610 
611     /**
612      * @brief The SRC 'hex words'.
613      *
614      * In the spec these are referred to as SRC words 2 - 9 as words 0 and 1
615      * are filled by the 8 bytes of fields from above.
616      */
617     std::array<uint32_t, numSRCHexDataWords> _hexData;
618 
619     /**
620      * @brief The 32 byte ASCII character string of the SRC
621      *
622      * It is padded with spaces to fill the 32 bytes.
623      * An example is:
624      * "BD8D1234                        "
625      *
626      * That first word is what is commonly referred to as the refcode, and
627      * sometimes also called an SRC.
628      */
629     std::unique_ptr<src::AsciiString> _asciiString;
630 
631     /**
632      * @brief The callouts subsection.
633      *
634      * Optional and only created if there are callouts.
635      */
636     std::unique_ptr<src::Callouts> _callouts;
637 };
638 
639 } // namespace pels
640 } // namespace openpower
641