blob: bf31405946cb79208827ded22c40b546e25b76eb [file] [log] [blame]
Deepak Kodihalli3b02ed82020-02-06 01:18:25 -06001#ifndef PDR_H
2#define PDR_H
3
4#ifdef __cplusplus
5extern "C" {
6#endif
7
Deepak Kodihalli05787052020-03-10 01:54:08 -05008#include <stdbool.h>
9#include <stddef.h>
Deepak Kodihalli3b02ed82020-02-06 01:18:25 -060010#include <stdint.h>
11
12/** @struct pldm_pdr
13 * opaque structure that acts as a handle to a PDR repository
14 */
15typedef struct pldm_pdr pldm_pdr;
16
17/** @struct pldm_pdr_record
18 * opaque structure that acts as a handle to a PDR record
19 */
20typedef struct pldm_pdr_record pldm_pdr_record;
21
22/* ====================== */
23/* Common PDR access APIs */
24/* ====================== */
25
26/** @brief Make a new PDR repository
27 *
28 * @return opaque pointer that acts as a handle to the repository; NULL if no
29 * repository could be created
30 *
31 * @note Caller may make multiple repositories (for its own PDRs, as well as
32 * for PDRs received by other entities) and can associate the returned handle
33 * to a PLDM terminus id.
34 */
35pldm_pdr *pldm_pdr_init();
36
37/** @brief Destroy a PDR repository (and free up associated resources)
38 *
39 * @param[in/out] repo - pointer to opaque pointer acting as a PDR repo handle
40 */
41void pldm_pdr_destroy(pldm_pdr *repo);
42
43/** @brief Get number of records in a PDR repository
44 *
45 * @param[in] repo - opaque pointer acting as a PDR repo handle
46 *
47 * @return uint32_t - number of records
48 */
49uint32_t pldm_pdr_get_record_count(const pldm_pdr *repo);
50
51/** @brief Get size of a PDR repository, in bytes
52 *
53 * @param[in] repo - opaque pointer acting as a PDR repo handle
54 *
55 * @return uint32_t - size in bytes
56 */
57uint32_t pldm_pdr_get_repo_size(const pldm_pdr *repo);
58
59/** @brief Add a PDR record to a PDR repository
60 *
61 * @param[in/out] repo - opaque pointer acting as a PDR repo handle
62 * @param[in] data - pointer to a PDR record, pointing to a PDR definition as
63 * per DSP0248. This data is memcpy'd.
64 * @param[in] size - size of input PDR record in bytes
65 * @param[in] record_handle - record handle of input PDR record; if this is set
66 * to 0, then a record handle is computed and assigned to this PDR record
Deepak Kodihalli87514cc2020-04-16 09:08:38 -050067 * @param[in] is_remote - if true, then the PDR is not from this terminus
Deepak Kodihalli3b02ed82020-02-06 01:18:25 -060068 *
69 * @return uint32_t - record handle assigned to PDR record
70 */
71uint32_t pldm_pdr_add(pldm_pdr *repo, const uint8_t *data, uint32_t size,
Deepak Kodihalli87514cc2020-04-16 09:08:38 -050072 uint32_t record_handle, bool is_remote);
Deepak Kodihalli3b02ed82020-02-06 01:18:25 -060073
74/** @brief Get record handle of a PDR record
75 *
76 * @param[in] repo - opaque pointer acting as a PDR repo handle
77 * @param[in] record - opaque pointer acting as a PDR record handle
78 *
79 * @return uint32_t - record handle assigned to PDR record; 0 if record is not
80 * found
81 */
82uint32_t pldm_pdr_get_record_handle(const pldm_pdr *repo,
83 const pldm_pdr_record *record);
84
85/** @brief Find PDR record by record handle
86 *
87 * @param[in] repo - opaque pointer acting as a PDR repo handle
88 * @param[in] record_handle - input record handle
89 * @param[in/out] data - will point to PDR record data (as per DSP0248) on
90 * return
91 * @param[out] size - *size will be size of PDR record
92 * @param[out] next_record_handle - *next_record_handle will be the record
93 * handle of record next to the returned PDR record
94 *
95 * @return opaque pointer acting as PDR record handle, will be NULL if record
96 * was not found
97 */
98const pldm_pdr_record *pldm_pdr_find_record(const pldm_pdr *repo,
99 uint32_t record_handle,
100 uint8_t **data, uint32_t *size,
101 uint32_t *next_record_handle);
102
103/** @brief Get PDR record next to input PDR record
104 *
105 * @param[in] repo - opaque pointer acting as a PDR repo handle
106 * @param[in] curr_record - opaque pointer acting as a PDR record handle
107 * @param[in/out] data - will point to PDR record data (as per DSP0248) on
108 * return
109 * @param[out] size - *size will be size of PDR record
110 * @param[out] next_record_handle - *next_record_handle will be the record
111 * handle of record nect to the returned PDR record
112 *
113 * @return opaque pointer acting as PDR record handle, will be NULL if record
114 * was not found
115 */
116const pldm_pdr_record *
117pldm_pdr_get_next_record(const pldm_pdr *repo,
118 const pldm_pdr_record *curr_record, uint8_t **data,
119 uint32_t *size, uint32_t *next_record_handle);
120
121/** @brief Find (first) PDR record by PDR type
122 *
123 * @param[in] repo - opaque pointer acting as a PDR repo handle
124 * @param[in] pdr_type - PDR type number as per DSP0248
125 * @param[in] curr_record - opaque pointer acting as a PDR record handle; if
126 * not NULL, then search will begin from this record's next record
127 * @param[in/out] data - will point to PDR record data (as per DSP0248) on
Pavithra Barithayae8beb892020-04-14 23:24:25 -0500128 * return, if input is not NULL
129 * @param[out] size - *size will be size of PDR record, if input is not NULL
Deepak Kodihalli3b02ed82020-02-06 01:18:25 -0600130 *
131 * @return opaque pointer acting as PDR record handle, will be NULL if record
132 * was not found
133 */
134const pldm_pdr_record *
135pldm_pdr_find_record_by_type(const pldm_pdr *repo, uint8_t pdr_type,
136 const pldm_pdr_record *curr_record, uint8_t **data,
137 uint32_t *size);
138
Deepak Kodihalli87514cc2020-04-16 09:08:38 -0500139bool pldm_pdr_record_is_remote(const pldm_pdr_record *record);
140
Deepak Kodihalli4a680932020-04-22 03:31:17 -0500141/** @brief Remove all PDR records that belong to a remote terminus
142 *
143 * @param[in] repo - opaque pointer acting as a PDR repo handle
144 */
145void pldm_pdr_remove_remote_pdrs(pldm_pdr *repo);
146
Deepak Kodihallidb914672020-02-07 02:47:45 -0600147/* ======================= */
148/* FRU Record Set PDR APIs */
149/* ======================= */
150
151/** @brief Add a FRU record set PDR record to a PDR repository
152 *
153 * @param[in/out] repo - opaque pointer acting as a PDR repo handle
154 * @param[in] terminus_handle - PLDM terminus handle of terminus owning the PDR
155 * record
156 * @param[in] fru_rsi - FRU record set identifier
157 * @param[in] entity_type - entity type of FRU
158 * @param[in] entity_instance_num - entity instance number of FRU
159 * @param[in] container_id - container id of FRU
160 *
161 * @return uint32_t - record handle assigned to PDR record
162 */
163uint32_t pldm_pdr_add_fru_record_set(pldm_pdr *repo, uint16_t terminus_handle,
164 uint16_t fru_rsi, uint16_t entity_type,
165 uint16_t entity_instance_num,
166 uint16_t container_id);
167
168/** @brief Find a FRU record set PDR by FRU record set identifier
169 *
170 * @param[in] repo - opaque pointer acting as a PDR repo handle
171 * @param[in] fru_rsi - FRU record set identifier
172 * @param[in] terminus_handle - *terminus_handle will be FRU terminus handle of
173 * found PDR, or 0 if not found
174 * @param[in] entity_type - *entity_type will be FRU entity type of found PDR,
175 * or 0 if not found
176 * @param[in] entity_instance_num - *entity_instance_num will be FRU entity
177 * instance number of found PDR, or 0 if not found
178 * @param[in] container_id - *cintainer_id will be FRU container id of found
179 * PDR, or 0 if not found
180 *
181 * @return uint32_t - record handle assigned to PDR record
182 */
183const pldm_pdr_record *pldm_pdr_fru_record_set_find_by_rsi(
184 const pldm_pdr *repo, uint16_t fru_rsi, uint16_t *terminus_handle,
185 uint16_t *entity_type, uint16_t *entity_instance_num,
186 uint16_t *container_id);
187
Deepak Kodihalli05787052020-03-10 01:54:08 -0500188/* =========================== */
189/* Entity Association PDR APIs */
190/* =========================== */
191
192typedef struct pldm_entity {
193 uint16_t entity_type;
194 uint16_t entity_instance_num;
195 uint16_t entity_container_id;
196} __attribute__((packed)) pldm_entity;
197
198enum entity_association_containment_type {
199 PLDM_ENTITY_ASSOCIAION_PHYSICAL = 0x0,
Deepak Kodihalli0a738f02020-03-10 01:56:21 -0500200 PLDM_ENTITY_ASSOCIAION_LOGICAL = 0x1,
Deepak Kodihalli05787052020-03-10 01:54:08 -0500201};
202
203/** @struct pldm_entity_association_tree
204 * opaque structure that represents the entity association hierarchy
205 */
206typedef struct pldm_entity_association_tree pldm_entity_association_tree;
207
208/** @struct pldm_entity_node
209 * opaque structure that represents a node in the entity association hierarchy
210 */
211typedef struct pldm_entity_node pldm_entity_node;
212
213/** @brief Make a new entity association tree
214 *
215 * @return opaque pointer that acts as a handle to the tree; NULL if no
216 * tree could be created
217 */
218pldm_entity_association_tree *pldm_entity_association_tree_init();
219
220/** @brief Add an entity into the entity association tree
221 *
222 * @param[in/out] tree - opaque pointer acting as a handle to the tree
223 * @param[in/out] entity - pointer to the entity to be added. Input has the
224 * entity type. On output, instance number and the
225 * container id are populated.
226 * @param[in] parent - pointer to the node that should be the parent of input
227 * entity. If this is NULL, then the entity is the root
228 * @param[in] association_type - relation with the parent : logical or physical
229 *
230 * @return pldm_entity_node* - opaque pointer to added entity
231 */
232pldm_entity_node *
233pldm_entity_association_tree_add(pldm_entity_association_tree *tree,
234 pldm_entity *entity, pldm_entity_node *parent,
235 uint8_t association_type);
236
237/** @brief Visit and note each entity in the entity association tree
238 *
239 * @param[in] tree - opaque pointer acting as a handle to the tree
240 * @param[out] entities - pointer to list of pldm_entity's. To be free()'d by
241 * the caller
242 * @param[out] size - number of pldm_entity's
243 */
244void pldm_entity_association_tree_visit(pldm_entity_association_tree *tree,
245 pldm_entity **entities, size_t *size);
246
George Liud9855ab2021-05-13 09:41:31 +0800247/** @brief Extract pldm entity by the pldm_entity_node
248 *
249 * @param[in] node - opaque pointer to added entity
250 *
251 * @return pldm_entity - pldm entity
252 */
253pldm_entity pldm_entity_extract(pldm_entity_node *node);
254
Deepak Kodihalli05787052020-03-10 01:54:08 -0500255/** @brief Destroy entity association tree
256 *
257 * @param[in] tree - opaque pointer acting as a handle to the tree
258 */
259void pldm_entity_association_tree_destroy(pldm_entity_association_tree *tree);
260
261/** @brief Check if input enity node is a parent
262 *
263 * @param[in] node - opaque pointer acting as a handle to an entity node
264 *
265 * @return bool true if node is a parent, false otherwise
266 */
267bool pldm_entity_is_node_parent(pldm_entity_node *node);
268
George Liufe77eea2021-04-28 15:08:07 +0800269/** @brief Get parent of entity
270 *
271 * @param[in] node - opaque pointer acting as a handle to an entity node
272 *
273 * @return pldm_entity_node* - opaque pointer to parent entity
274 */
275pldm_entity_node *pldm_entity_get_parent(pldm_entity_node *node);
276
Deepak Kodihalli0a738f02020-03-10 01:56:21 -0500277/** @brief Convert entity association tree to PDR
278 *
279 * @param[in] tree - opaque pointer to entity association tree
280 * @param[in] repo - PDR repo where entity association records should be added
Deepak Kodihalli87514cc2020-04-16 09:08:38 -0500281 * @param[in] is_remote - if true, then the PDR is not from this terminus
Deepak Kodihalli0a738f02020-03-10 01:56:21 -0500282 */
283void pldm_entity_association_pdr_add(pldm_entity_association_tree *tree,
Deepak Kodihalli87514cc2020-04-16 09:08:38 -0500284 pldm_pdr *repo, bool is_remote);
Deepak Kodihalli0a738f02020-03-10 01:56:21 -0500285
286/** @brief Get number of children of entity
287 *
288 * @param[in] node - opaque pointer acting as a handle to an entity node
289 * @param[in] association_type - relation type filter : logical or physical
290 *
291 * @return uint8_t number of children
292 */
293uint8_t pldm_entity_get_num_children(pldm_entity_node *node,
294 uint8_t association_type);
295
Deepak Kodihalli3b28ba82020-03-30 07:39:47 -0500296/** @brief Find an entity in the entity association tree
297 *
298 * @param[in] tree - pointer to entity association tree
299 * @param[in/out] entity - entity type and instance id set on input, container
300 * id set on output
301 *
302 * @return pldm_entity_node* pointer to entity if found, NULL otherwise
303 */
304pldm_entity_node *
305pldm_entity_association_tree_find(pldm_entity_association_tree *tree,
306 pldm_entity *entity);
307
Sampa Misrac073a202021-05-08 10:56:05 -0500308/** @brief Create a copy of an existing entity association tree
309 *
310 * @param[in] org_tree - pointer to source tree
311 * @param[in/out] new_tree - pointer to destination tree
312 */
313void pldm_entity_association_tree_copy_root(
314 pldm_entity_association_tree *org_tree,
315 pldm_entity_association_tree *new_tree);
316
317/** @brief Destroy all the nodes of the entity association tree
318 *
319 * @param[in] tree - pointer to entity association tree
320 */
321void pldm_entity_association_tree_destroy_root(
322 pldm_entity_association_tree *tree);
323
324/** @brief Check whether the entity association tree is empty
325 *
326 * @param[in] tree - pointer to entity association tree
327 * @return bool, true if tree is empty
328 */
329bool pldm_is_empty_entity_assoc_tree(pldm_entity_association_tree *tree);
330
Deepak Kodihalli3b28ba82020-03-30 07:39:47 -0500331/** @brief Extract entities from entity association PDR
332 *
333 * @param[in] pdr - entity association PDR
334 * @param[in] pdr_len - size of entity association PDR in bytes
335 * @param[out] num_entities - number of entities found, including the container
336 * @param[out] entities - extracted entities, container is *entities[0]. Caller
337 * must free *entities
338 */
339void pldm_entity_association_pdr_extract(const uint8_t *pdr, uint16_t pdr_len,
340 size_t *num_entities,
341 pldm_entity **entities);
342
Deepak Kodihalli3b02ed82020-02-06 01:18:25 -0600343#ifdef __cplusplus
344}
345#endif
346
347#endif /* PDR_H */