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      */
125     Callout(CalloutPriority priority,
126             const std::string& procedureFromRegistry) :
127         Callout(priority, procedureFromRegistry, CalloutValueType::registryName)
128     {
129     }
130 
131     /**
132      * @brief Constructor
133      *
134      * Creates the objects with a FRUIdentity substructure that calls
135      * out a symbolic FRU.
136      *
137      * @param[in] priority - The priority of the callout
138      * @param[in] symbolicFRU - The symbolic FRU name
139      * @param[in] type - If the FRU is the raw name or the registry name
140      * @param[in] locationCode - The location code of the callout
141      * @param[in] trustedLocationCode - If the location is trusted
142      */
143     Callout(CalloutPriority priority, const std::string& symbolicFRU,
144             CalloutValueType type, const std::string& locationCode,
145             bool trustedLocationCode);
146 
147     /**
148      * @brief Constructor
149      *
150      * Creates the objects with a FRUIdentity substructure that calls
151      * out a symbolic FRU.
152      *
153      * @param[in] priority - The priority of the callout
154      * @param[in] symbolicFRUFromRegistry - The symbolic FRU name as
155      *                                      defined in the message registry.
156      * @param[in] locationCode - The location code of the callout
157      * @param[in] trustedLocationCode - If the location is trusted
158      */
159     Callout(CalloutPriority priority,
160             const std::string& symbolicFRUFromRegistry,
161             const std::string& locationCode, bool trustedLocationCode) :
162         Callout(priority, symbolicFRUFromRegistry,
163                 CalloutValueType::registryName, locationCode,
164                 trustedLocationCode)
165     {
166     }
167 
168     /**
169      * @brief Returns the size of this object when flattened into a PEL
170      *
171      * @return size_t - The size of the section
172      */
173     size_t flattenedSize() const;
174 
175     /**
176      * @brief Flatten the object into the stream
177      *
178      * @param[in] stream - The stream to write to
179      */
180     void flatten(Stream& pel) const;
181 
182     /**
183      * @brief Returns the flags field of a callout
184      *
185      * @return uint8_t - The flags
186      */
187     uint8_t flags() const
188     {
189         return _flags;
190     }
191 
192     /**
193      * @brief Returns the priority field of a callout
194      *
195      * @return uint8_t - The priority
196      */
197     uint8_t priority() const
198     {
199         return _priority;
200     }
201 
202     /**
203      * @brief Returns the location code of the callout
204      *
205      * @return std::string - The location code
206      */
207     std::string locationCode() const
208     {
209         std::string lc;
210         if (!_locationCode.empty())
211         {
212             // NULL terminated
213             lc = static_cast<const char*>(_locationCode.data());
214         }
215         return lc;
216     }
217 
218     /**
219      * @brief Returns the location code size
220      *
221      * @return size_t - The size, including the terminating null.
222      */
223     size_t locationCodeSize() const
224     {
225         return _locationCodeSize;
226     }
227 
228     /**
229      * @brief Returns the FRU identity substructure
230      *
231      * @return const std::unique_ptr<FRUIdentity>&
232      */
233     const std::unique_ptr<FRUIdentity>& fruIdentity() const
234     {
235         return _fruIdentity;
236     }
237 
238     /**
239      * @brief Returns the PCE identity substructure
240      *
241      * @return const std::unique_ptr<PCEIdentity>&
242      */
243     const std::unique_ptr<PCEIdentity>& pceIdentity() const
244     {
245         return _pceIdentity;
246     }
247 
248     /**
249      * @brief Returns the MRU identity substructure
250      *
251      * @return const std::unique_ptr<MRU>&
252      */
253     const std::unique_ptr<MRU>& mru() const
254     {
255         return _mru;
256     }
257 
258   private:
259     /**
260      * @brief Sets the location code field
261      *
262      * @param[in] locationCode - The location code string
263      */
264     void setLocationCode(const std::string& locationCode);
265 
266     /**
267      * @brief The size of this structure in the PEL
268      */
269     uint8_t _size;
270 
271     /**
272      * @brief The flags byte of this structure
273      */
274     uint8_t _flags;
275 
276     /**
277      * @brief The replacement priority
278      */
279     uint8_t _priority;
280 
281     /**
282      * @brief The length of the location code field.
283      *
284      * Includes the NULL termination, and must be a
285      * multiple of 4 (padded with zeros)
286      */
287     uint8_t _locationCodeSize = 0;
288 
289     /**
290      * @brief NULL terminated location code
291      *
292      * Includes the NULL termination, and must be a
293      * multiple of 4 (padded with zeros)
294      */
295     std::vector<char> _locationCode;
296 
297     /**
298      * @brief FRU (Field Replaceable Unit) Identity substructure
299      */
300     std::unique_ptr<FRUIdentity> _fruIdentity;
301 
302     /**
303      * @brief PCE (Power Controlling Enclosure) Identity substructure
304      */
305     std::unique_ptr<PCEIdentity> _pceIdentity;
306 
307     /**
308      * @brief MRU (Manufacturing Replaceable Unit) substructure
309      */
310     std::unique_ptr<MRU> _mru;
311 };
312 
313 } // namespace src
314 } // namespace pels
315 } // namespace openpower
316