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      * @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      */
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      */
185     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      */
195     uint8_t priority() const
196     {
197         return _priority;
198     }
199 
200     /**
201      * @brief Returns the location code of the callout
202      *
203      * @return std::string - The location code
204      */
205     std::string locationCode() const
206     {
207         std::string lc;
208         if (!_locationCode.empty())
209         {
210             // NULL terminated
211             lc = static_cast<const char*>(_locationCode.data());
212         }
213         return lc;
214     }
215 
216     /**
217      * @brief Returns the location code size
218      *
219      * @return size_t - The size, including the terminating null.
220      */
221     size_t locationCodeSize() const
222     {
223         return _locationCodeSize;
224     }
225 
226     /**
227      * @brief Returns the FRU identity substructure
228      *
229      * @return const std::unique_ptr<FRUIdentity>&
230      */
231     const std::unique_ptr<FRUIdentity>& fruIdentity() const
232     {
233         return _fruIdentity;
234     }
235 
236     /**
237      * @brief Returns the PCE identity substructure
238      *
239      * @return const std::unique_ptr<PCEIdentity>&
240      */
241     const std::unique_ptr<PCEIdentity>& pceIdentity() const
242     {
243         return _pceIdentity;
244     }
245 
246     /**
247      * @brief Returns the MRU identity substructure
248      *
249      * @return const std::unique_ptr<MRU>&
250      */
251     const std::unique_ptr<MRU>& mru() const
252     {
253         return _mru;
254     }
255 
256   private:
257     /**
258      * @brief Sets the location code field
259      *
260      * @param[in] locationCode - The location code string
261      */
262     void setLocationCode(const std::string& locationCode);
263 
264     /**
265      * @brief The size of this structure in the PEL
266      */
267     uint8_t _size;
268 
269     /**
270      * @brief The flags byte of this structure
271      */
272     uint8_t _flags;
273 
274     /**
275      * @brief The replacement priority
276      */
277     uint8_t _priority;
278 
279     /**
280      * @brief The length of the location code field.
281      *
282      * Includes the NULL termination, and must be a
283      * multiple of 4 (padded with zeros)
284      */
285     uint8_t _locationCodeSize = 0;
286 
287     /**
288      * @brief NULL terminated location code
289      *
290      * Includes the NULL termination, and must be a
291      * multiple of 4 (padded with zeros)
292      */
293     std::vector<char> _locationCode;
294 
295     /**
296      * @brief FRU (Field Replaceable Unit) Identity substructure
297      */
298     std::unique_ptr<FRUIdentity> _fruIdentity;
299 
300     /**
301      * @brief PCE (Power Controlling Enclosure) Identity substructure
302      */
303     std::unique_ptr<PCEIdentity> _pceIdentity;
304 
305     /**
306      * @brief MRU (Manufacturing Replaceable Unit) substructure
307      */
308     std::unique_ptr<MRU> _mru;
309 };
310 
311 } // namespace src
312 } // namespace pels
313 } // namespace openpower
314