1 #pragma once
2 
3 #include "additional_data.hpp"
4 #include "data_interface.hpp"
5 #include "journal.hpp"
6 #include "private_header.hpp"
7 #include "registry.hpp"
8 #include "src.hpp"
9 #include "user_data.hpp"
10 #include "user_data_formats.hpp"
11 #include "user_header.hpp"
12 
13 #include <memory>
14 #include <vector>
15 
16 namespace openpower
17 {
18 namespace pels
19 {
20 
21 /**
22  * @brief Contains information about an FFDC file.
23  */
24 struct PelFFDCfile
25 {
26     UserDataFormat format;
27     uint8_t subType;
28     uint8_t version;
29     int fd;
30 };
31 
32 using PelFFDC = std::vector<PelFFDCfile>;
33 
34 constexpr uint8_t jsonCalloutSubtype = 0xCA;
35 
36 /** @class PEL
37  *
38  * @brief This class represents a specific event log format referred to as a
39  * Platform Event Log.
40  *
41  * Every field in a PEL are in structures call sections, of which there are
42  * several types.  Some sections are required, and some are optional.  In some
43  * cases there may be more than one instance of a section type.
44  *
45  * The only two required sections for every type of PEL are the Private Header
46  * section and User Header section, which must be in the first and second
47  * positions, respectively.
48  *
49  * Every section starts with an 8 byte section header, which has the section
50  * size and type, among other things.
51  *
52  * This class represents all sections with objects.
53  *
54  * The class can be constructed:
55  * - From a full formed flattened PEL.
56  * - From scratch based on an OpenBMC event and its corresponding PEL message
57  *   registry entry.
58  *
59  * The data() method allows one to retrieve the PEL as a vector<uint8_t>.  This
60  * is the format in which it is stored and transmitted.
61  */
62 class PEL
63 {
64   public:
65     PEL() = delete;
66     ~PEL() = default;
67     PEL(const PEL&) = delete;
68     PEL& operator=(const PEL&) = delete;
69     PEL(PEL&&) = delete;
70     PEL& operator=(PEL&&) = delete;
71 
72     /**
73      * @brief Constructor
74      *
75      * Build a PEL from raw data.
76      *
77      * Note: Neither this nor the following constructor can take a const vector&
78      * because the Stream class that is used to read from the vector cannot take
79      * a const.  The alternative is to make a copy of the data, but as PELs can
80      * be up to 16KB that is undesireable.
81      *
82      * @param[in] data - The PEL data
83      */
84     explicit PEL(std::vector<uint8_t>& data);
85 
86     /**
87      * @brief Constructor
88      *
89      * Build a PEL from the raw data.
90      *
91      * @param[in] data - the PEL data
92      * @param[in] obmcLogID - the corresponding OpenBMC event log ID
93      */
94     PEL(std::vector<uint8_t>& data, uint32_t obmcLogID);
95 
96     /**
97      * @brief Constructor
98      *
99      * Creates a PEL from an OpenBMC event log and its message
100      * registry entry.
101      *
102      * @param[in] entry - The message registry entry for this error
103      * @param[in] obmcLogID - ID of corresponding OpenBMC event log
104      * @param[in] timestamp - Timestamp from the event log
105      * @param[in] severity - Severity from the event log
106      * @param[in] additionalData - The AdditionalData contents
107      * @param[in] ffdcFiles - FFCD files that go into UserData sections
108      * @param[in] dataIface - The data interface object
109      * @param[in] journal - The journal object
110      */
111     PEL(const openpower::pels::message::Entry& entry, uint32_t obmcLogID,
112         uint64_t timestamp, phosphor::logging::Entry::Level severity,
113         const AdditionalData& additionalData, const PelFFDC& ffdcFiles,
114         const DataInterfaceBase& dataIface, const JournalBase& journal);
115 
116     /**
117      * @brief Convenience function to return the log ID field from the
118      *        Private Header section.
119      *
120      * @return uint32_t - the ID
121      */
122     uint32_t id() const
123     {
124         return _ph->id();
125     }
126 
127     /**
128      * @brief Convenience function to return the PLID field from the
129      *        Private Header section.
130      *
131      * @return uint32_t - the PLID
132      */
133     uint32_t plid() const
134     {
135         return _ph->plid();
136     }
137 
138     /**
139      * @brief Convenience function to return the OpenBMC event log ID field
140      * from the Private Header section.
141      *
142      * @return uint32_t - the OpenBMC event log ID
143      */
144     uint32_t obmcLogID() const
145     {
146         return _ph->obmcLogID();
147     }
148 
149     /**
150      * @brief Convenience function to return the commit time field from
151      *        the Private Header section.
152      *
153      * @return BCDTime - the timestamp
154      */
155     BCDTime commitTime() const
156     {
157         return _ph->commitTimestamp();
158     }
159 
160     /**
161      * @brief Convenience function to return the create time field from
162      *        the Private Header section.
163      *
164      * @return BCDTime - the timestamp
165      */
166     BCDTime createTime() const
167     {
168         return _ph->createTimestamp();
169     }
170 
171     /**
172      * @brief Gives access to the Private Header section class
173      *
174      * @return const PrivateHeader& - the private header
175      */
176     const PrivateHeader& privateHeader() const
177     {
178         return *_ph;
179     }
180 
181     /**
182      * @brief Gives access to the User Header section class
183      *
184      * @return const UserHeader& - the user header
185      */
186     const UserHeader& userHeader() const
187     {
188         return *_uh;
189     }
190 
191     /**
192      * @brief Gives access to the primary SRC's section class
193      *
194      * This is technically an optional section, so the return
195      * value is an std::optional<SRC*>.
196      *
197      * @return std::optional<SRC*> - the SRC section object
198      */
199     std::optional<SRC*> primarySRC() const;
200 
201     /**
202      * @brief Returns the optional sections, which is everything but
203      *        the Private and User Headers.
204      *
205      * @return const std::vector<std::unique_ptr<Section>>&
206      */
207     const std::vector<std::unique_ptr<Section>>& optionalSections() const
208     {
209         return _optionalSections;
210     }
211 
212     /**
213      * @brief Returns the PEL data.
214      *
215      * @return std::vector<uint8_t> - the raw PEL data
216      */
217     std::vector<uint8_t> data() const;
218 
219     /**
220      * @brief Returns the size of the PEL
221      *
222      * @return size_t The PEL size in bytes
223      */
224     size_t size() const;
225 
226     /**
227      * @brief Says if the PEL is valid (the sections are all valid)
228      *
229      * @return bool - if the PEL is valid
230      */
231     bool valid() const;
232 
233     /**
234      * @brief Sets the commit timestamp to the current time
235      */
236     void setCommitTime();
237 
238     /**
239      * @brief Sets the error log ID field to a unique ID.
240      */
241     void assignID();
242 
243     /**
244      * @brief Output a PEL in JSON.
245      * @param[in] registry - Registry object reference
246      * @param[in] plugins - Vector of strings of plugins found in filesystem
247      */
248     void toJSON(message::Registry& registry,
249                 const std::vector<std::string>& plugins) const;
250 
251     /**
252      * @brief Sets the host transmission state in the User Header
253      *
254      * @param[in] state - The state value
255      */
256     void setHostTransmissionState(TransmissionState state)
257     {
258         _uh->setHostTransmissionState(static_cast<uint8_t>(state));
259     }
260 
261     /**
262      * @brief Returns the host transmission state
263      *
264      * @return HostTransmissionState - The state
265      */
266     TransmissionState hostTransmissionState() const
267     {
268         return static_cast<TransmissionState>(_uh->hostTransmissionState());
269     }
270 
271     /**
272      * @brief Sets the HMC transmission state in the User Header
273      *
274      * @param[in] state - The state value
275      */
276     void setHMCTransmissionState(TransmissionState state)
277     {
278         _uh->setHMCTransmissionState(static_cast<uint8_t>(state));
279     }
280 
281     /**
282      * @brief Returns the HMC transmission state
283      *
284      * @return HMCTransmissionState - The state
285      */
286     TransmissionState hmcTransmissionState() const
287     {
288         return static_cast<TransmissionState>(_uh->hmcTransmissionState());
289     }
290 
291     /**
292      * @brief Returns true if a hardware callout is present in the primary SRC
293      *
294      * @return true if hardware callout present, false otherwise
295      */
296     bool isHwCalloutPresent() const;
297 
298     /**
299      * @brief Updates the system info data into HB extended user
300      *        data section to this PEL object
301      *
302      * @param[in] dataIface - The data interface object
303      */
304     void updateSysInfoInExtendedUserDataSection(
305         const DataInterfaceBase& dataIface);
306 
307     /**
308      * @brief Return the deconfig flag from hex data word 5 of BMC and
309      *        hostboot PELs.
310      *
311      * This only applies to BMC and hostboot PELs because only those
312      * SRC formats have this flag defined.
313      *
314      * @return bool - If the 'one or more resources are deconfigured'
315      *                flag is set.
316      */
317     bool getDeconfigFlag() const;
318 
319     /**
320      * @brief Return the guard flag from hex data word 5 of BMC and
321      *        hostboot PELs.
322      *
323      * This only applies to BMC and hostboot PELs because only those
324      * SRC formats have this flag defined.
325      *
326      * @return bool - If the 'one or more resources are guarded'
327      *                flag is set.
328      */
329     bool getGuardFlag() const;
330 
331   private:
332     /**
333      * @brief Builds the section objects from a PEL data buffer
334      *
335      * Note: The data parameter cannot be const for the same reasons
336      * as listed in the constructor.
337      *
338      * @param[in] data - The PEL data
339      * @param[in] obmcLogID - The OpenBMC event log ID to use for that
340      *                        field in the Private Header.
341      */
342     void populateFromRawData(std::vector<uint8_t>& data, uint32_t obmcLogID);
343 
344     /**
345      * @brief Flattens the PEL objects into the buffer
346      *
347      * @param[out] pelBuffer - What the data will be written to
348      */
349     void flatten(std::vector<uint8_t>& pelBuffer) const;
350 
351     /**
352      * @brief Check that the PEL fields that need to be in agreement
353      *        with each other are, and fix them up if necessary.
354      */
355     void checkRulesAndFix();
356 
357     /**
358      * @brief Returns a map of the section IDs that appear more than once
359      *        in the PEL.  The data value for each entry will be set to 0.
360      *
361      * @return std::map<uint16_t, size_t>
362      */
363     std::map<uint16_t, size_t> getPluralSections() const;
364 
365     /**
366      * @brief Adds the UserData section to this PEL object,
367      *        shrinking it if necessary
368      *
369      * @param[in] userData - The section to add
370      *
371      * @return bool - If the section was added or not.
372      */
373     bool addUserDataSection(std::unique_ptr<UserData> userData);
374 
375     /**
376      * @brief helper function for printing PELs.
377      * @param[in] Section& - section object reference
378      * @param[in] std::string - PEL string
379      * @param[in|out] pluralSections - Map used to track sections counts for
380      *                                 when there is more than 1.
381      * @param[in] registry - Registry object reference
382      * @param[in] plugins - Vector of strings of plugins found in filesystem
383      * @param[in] creatorID - Creator Subsystem ID (only for UserData section)
384      */
385     void printSectionInJSON(
386         const Section& section, std::string& buf,
387         std::map<uint16_t, size_t>& pluralSections, message::Registry& registry,
388         const std::vector<std::string>& plugins, uint8_t creatorID = 0) const;
389 
390     /**
391      * @brief Returns any callout JSON found in the FFDC files.
392      *
393      * Looks for an FFDC file that is JSON format and has the
394      * sub-type value set to 0xCA and returns its data as a JSON object.
395      *
396      * @param[in] ffdcFiles - FFCD files that go into UserData sections
397      *
398      * @return json - The callout JSON, or an empty object if not found
399      */
400     nlohmann::json getCalloutJSON(const PelFFDC& ffdcFiles);
401 
402     /**
403      * @brief Update terminate bit in primary SRC section to this PEL object is
404      * severity set to 0x51 = critical error, system termination
405      */
406     void updateTerminateBitInSRCSection();
407 
408     /**
409      * @brief Adds journal data to the PEL as UserData sections
410      *        if specified to in the message registry.
411      *
412      * @param regEntry - The registry entry
413      * @param journal - The journal object
414      */
415     void addJournalSections(const message::Entry& regEntry,
416                             const JournalBase& journal);
417 
418     /**
419      * @brief The PEL Private Header section
420      */
421     std::unique_ptr<PrivateHeader> _ph;
422 
423     /**
424      * @brief The PEL User Header section
425      */
426     std::unique_ptr<UserHeader> _uh;
427 
428     /**
429      * @brief Holds all sections by the PH and UH.
430      */
431     std::vector<std::unique_ptr<Section>> _optionalSections;
432 
433     /**
434      * @brief The maximum size a PEL can be in bytes.
435      */
436     static constexpr size_t _maxPELSize = 16384;
437 };
438 
439 namespace util
440 {
441 
442 /**
443  * @brief Creates a UserData section object that contains JSON.
444  *
445  * @param[in] json - The JSON contents
446  *
447  * @return std::unique_ptr<UserData> - The UserData object
448  */
449 std::unique_ptr<UserData> makeJSONUserDataSection(const nlohmann::json& json);
450 
451 /**
452  * @brief Create a UserData section containing the AdditionalData
453  *        contents as a JSON string.
454  *
455  * @param[in] ad - The AdditionalData contents
456  *
457  * @return std::unique_ptr<UserData> - The section
458  */
459 std::unique_ptr<UserData> makeADUserDataSection(const AdditionalData& ad);
460 
461 /**
462  * @brief Create a UserData section containing various useful pieces
463  *        of system information as a JSON string.
464  *
465  * @param[in] ad - The AdditionalData contents
466  * @param[in] dataIface - The data interface object
467  * @param[in] addUptime - Whether to add the uptime attribute the default is
468  *                        true
469  *
470  * @return std::unique_ptr<UserData> - The section
471  */
472 std::unique_ptr<UserData> makeSysInfoUserDataSection(
473     const AdditionalData& ad, const DataInterfaceBase& dataIface,
474     bool addUptime = true);
475 
476 /**
477  * @brief Reads data from an opened file descriptor.
478  *
479  * @param[in] fd - The FD to read from
480  *
481  * @return std::vector<uint8_t> - The data read
482  */
483 std::vector<uint8_t> readFD(int fd);
484 
485 /**
486  * @brief Create a UserData section that contains the data in the file
487  *        pointed to by the file descriptor passed in.
488  *
489  * @param[in] componentID - The component ID of the PEL creator
490  * @param[in] file - The FFDC file information
491  */
492 std::unique_ptr<UserData>
493     makeFFDCuserDataSection(uint16_t componentID, const PelFFDCfile& file);
494 
495 /**
496  * @brief Flattens a vector of strings into a vector of bytes suitable
497  *        for storing in a PEL section.
498  *
499  * Adds a newline character after each string.
500  *
501  * @param lines - The vector of strings to convert
502  *
503  * @return std::vector<uint8_t> - The flattened data
504  */
505 std::vector<uint8_t> flattenLines(const std::vector<std::string>& lines);
506 
507 } // namespace util
508 
509 } // namespace pels
510 } // namespace openpower
511