1 #pragma once
2 
3 #include "fru_identity.hpp"
4 #include "mru.hpp"
5 #include "pce_identity.hpp"
6 #include "pel_types.hpp"
7 #include "stream.hpp"
8 
9 namespace openpower
10 {
11 namespace pels
12 {
13 namespace src
14 {
15 
16 /**
17  * @class Callout
18  *
19  * Represents a single FRU callout in the SRC's FRU callout
20  * subsection.
21  *
22  * The 'Callouts' class holds a list of these objects.
23  *
24  * The callout priority and location code are in this structure.
25  *
26  * There can also be up to one each of three types of substructures
27  * in a single callout:
28  *  * FRU Identity  (must be first if present)
29  *  * Power Controlling Enclosure (PCE)
30  *  * Manufacturing Replaceable Unit (MRU)
31  *
32  * These substructures have their own objects managed by unique_ptrs
33  * which will only be allocated if those substructures exist.
34  */
35 class Callout
36 {
37   public:
38     /**
39      * @brief Which callout substructures are included.
40      */
41     enum calloutFlags
42     {
43         calloutType = 0b0010'0000,
44         fruIdentIncluded = 0b0000'1000,
45         mruIncluded = 0b0000'0100
46 
47         // Leaving out the various PCE identity ones since
48         // we don't use them.
49     };
50 
51     Callout() = delete;
52     ~Callout() = default;
53     Callout(const Callout&) = delete;
54     Callout& operator=(const Callout&) = delete;
55     Callout(Callout&&) = delete;
56     Callout& operator=(Callout&&) = delete;
57 
58     /**
59      * @brief Constructor
60      *
61      * Fills in this class's data fields from the stream.
62      *
63      * @param[in] pel - the PEL data stream
64      */
65     explicit Callout(Stream& pel);
66 
67     /**
68      * @brief Constructor
69      *
70      * Creates the objects with a FRUIdentity substructure that calls
71      * out a normal hardware FRU.
72      *
73      * @param[in] priority - The priority of the callout
74      * @param[in] locationCode - The location code of the callout
75      * @param[in] partNumber - The part number of the callout
76      * @param[in] ccin - The CCIN of the callout
77      * @param[in] serialNumber - The serial number of the callout
78      */
79     Callout(CalloutPriority priority, const std::string& locationCode,
80             const std::string& partNumber, const std::string& ccin,
81             const std::string& serialNumber);
82 
83     /**
84      * @brief Constructor
85      *
86      * Creates the objects with a FRUIdentity substructure that calls
87      * out a normal hardware FRU, and takes a list of MRUs that will
88      * be added to the callout.
89      *
90      * @param[in] priority - The priority of the callout
91      * @param[in] locationCode - The location code of the callout
92      * @param[in] partNumber - The part number of the callout
93      * @param[in] ccin - The CCIN of the callout
94      * @param[in] serialNumber - The serial number of the callout
95      * @param[in] mrus - The MRUs, if any, to add to the callout
96      */
97     Callout(CalloutPriority priority, const std::string& locationCode,
98             const std::string& partNumber, const std::string& ccin,
99             const std::string& serialNumber,
100             const std::vector<MRU::MRUCallout>& mrus);
101 
102     /**
103      * @brief Constructor
104      *
105      * Creates the objects with a FRUIdentity substructure that calls
106      * out a maintenance procedure.
107      *
108      * @param[in] priority - The priority of the callout
109      * @param[in] procedure - The maintenance procedure name
110      * @param[in] type - If the procedure is the raw name or the registry name
111      */
112     Callout(CalloutPriority priority, const std::string& procedure,
113             CalloutValueType type);
114 
115     /**
116      * @brief Constructor
117      *
118      * Creates the objects with a FRUIdentity substructure that calls
119      * out a maintenance procedure.
120      *
121      * @param[in] priority - The priority of the callout
122      * @param[in] procedureFromRegistry - The maintenance procedure name
123      *                                    as defined in the message registry.
124      */
Callout(CalloutPriority priority,const std::string & procedureFromRegistry)125     Callout(CalloutPriority priority,
126             const std::string& procedureFromRegistry) :
127         Callout(priority, procedureFromRegistry, CalloutValueType::registryName)
128     {}
129 
130     /**
131      * @brief Constructor
132      *
133      * Creates the objects with a FRUIdentity substructure that calls
134      * out a symbolic FRU.
135      *
136      * @param[in] priority - The priority of the callout
137      * @param[in] symbolicFRU - The symbolic FRU name
138      * @param[in] type - If the FRU is the raw name or the registry name
139      * @param[in] locationCode - The location code of the callout
140      * @param[in] trustedLocationCode - If the location is trusted
141      */
142     Callout(CalloutPriority priority, const std::string& symbolicFRU,
143             CalloutValueType type, const std::string& locationCode,
144             bool trustedLocationCode);
145 
146     /**
147      * @brief Constructor
148      *
149      * Creates the objects with a FRUIdentity substructure that calls
150      * out a symbolic FRU.
151      *
152      * @param[in] priority - The priority of the callout
153      * @param[in] symbolicFRUFromRegistry - The symbolic FRU name as
154      *                                      defined in the message registry.
155      * @param[in] locationCode - The location code of the callout
156      * @param[in] trustedLocationCode - If the location is trusted
157      */
Callout(CalloutPriority priority,const std::string & symbolicFRUFromRegistry,const std::string & locationCode,bool trustedLocationCode)158     Callout(CalloutPriority priority,
159             const std::string& symbolicFRUFromRegistry,
160             const std::string& locationCode, bool trustedLocationCode) :
161         Callout(priority, symbolicFRUFromRegistry,
162                 CalloutValueType::registryName, locationCode,
163                 trustedLocationCode)
164     {}
165 
166     /**
167      * @brief Returns the size of this object when flattened into a PEL
168      *
169      * @return size_t - The size of the section
170      */
171     size_t flattenedSize() const;
172 
173     /**
174      * @brief Flatten the object into the stream
175      *
176      * @param[in] stream - The stream to write to
177      */
178     void flatten(Stream& pel) const;
179 
180     /**
181      * @brief Returns the flags field of a callout
182      *
183      * @return uint8_t - The flags
184      */
flags() const185     uint8_t flags() const
186     {
187         return _flags;
188     }
189 
190     /**
191      * @brief Returns the priority field of a callout
192      *
193      * @return uint8_t - The priority
194      */
priority() const195     uint8_t priority() const
196     {
197         return _priority;
198     }
199 
200     /**
201      * @brief Set the priority of the callout
202      *
203      * @param[in] priority - The priority value
204      */
setPriority(uint8_t priority)205     void setPriority(uint8_t priority)
206     {
207         _priority = priority;
208     }
209 
210     /**
211      * @brief Returns the location code of the callout
212      *
213      * @return std::string - The location code
214      */
locationCode() const215     std::string locationCode() const
216     {
217         std::string lc;
218         if (!_locationCode.empty())
219         {
220             // NULL terminated
221             lc = static_cast<const char*>(_locationCode.data());
222         }
223         return lc;
224     }
225 
226     /**
227      * @brief Returns the location code size
228      *
229      * @return size_t - The size, including the terminating null.
230      */
locationCodeSize() const231     size_t locationCodeSize() const
232     {
233         return _locationCodeSize;
234     }
235 
236     /**
237      * @brief Returns the FRU identity substructure
238      *
239      * @return const std::unique_ptr<FRUIdentity>&
240      */
fruIdentity() const241     const std::unique_ptr<FRUIdentity>& fruIdentity() const
242     {
243         return _fruIdentity;
244     }
245 
246     /**
247      * @brief Returns the PCE identity substructure
248      *
249      * @return const std::unique_ptr<PCEIdentity>&
250      */
pceIdentity() const251     const std::unique_ptr<PCEIdentity>& pceIdentity() const
252     {
253         return _pceIdentity;
254     }
255 
256     /**
257      * @brief Returns the MRU identity substructure
258      *
259      * @return const std::unique_ptr<MRU>&
260      */
mru() const261     const std::unique_ptr<MRU>& mru() const
262     {
263         return _mru;
264     }
265 
266     /**
267      * @brief Operator == used for finding duplicate callouts
268      *
269      * Checks if the location codes then maintenance procedure
270      * value, then symbolic FRU value match.
271      *
272      * @param[in] right - The callout to compare to
273      * @return bool - true if they are the same
274      */
275     bool operator==(const Callout& right) const;
276 
277     /**
278      * @brief Operator > used for sorting callouts by priority
279      *
280      * @param[in] right - The callout to compare to
281      * @return bool - true if callout has higher priority than other
282      */
283     bool operator>(const Callout& right) const;
284 
285   private:
286     /**
287      * @brief Sets the location code field
288      *
289      * @param[in] locationCode - The location code string
290      */
291     void setLocationCode(const std::string& locationCode);
292 
293     /**
294      * @brief The size of this structure in the PEL
295      */
296     uint8_t _size;
297 
298     /**
299      * @brief The flags byte of this structure
300      */
301     uint8_t _flags;
302 
303     /**
304      * @brief The replacement priority
305      */
306     uint8_t _priority;
307 
308     /**
309      * @brief The length of the location code field.
310      *
311      * Includes the NULL termination, and must be a
312      * multiple of 4 (padded with zeros)
313      */
314     uint8_t _locationCodeSize = 0;
315 
316     /**
317      * @brief NULL terminated location code
318      *
319      * Includes the NULL termination, and must be a
320      * multiple of 4 (padded with zeros)
321      */
322     std::vector<char> _locationCode;
323 
324     /**
325      * @brief FRU (Field Replaceable Unit) Identity substructure
326      */
327     std::unique_ptr<FRUIdentity> _fruIdentity;
328 
329     /**
330      * @brief PCE (Power Controlling Enclosure) Identity substructure
331      */
332     std::unique_ptr<PCEIdentity> _pceIdentity;
333 
334     /**
335      * @brief MRU (Manufacturing Replaceable Unit) substructure
336      */
337     std::unique_ptr<MRU> _mru;
338 };
339 
340 } // namespace src
341 } // namespace pels
342 } // namespace openpower
343