blob: 671b726922e8c612b2fb9b2f080ee3f397e6c139 [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
Manojkiran Eda3ca40452021-10-04 22:51:37 +053068 * @param[in] terminus_handle - terminus handle of the input PDR record
Deepak Kodihalli3b02ed82020-02-06 01:18:25 -060069 *
70 * @return uint32_t - record handle assigned to PDR record
71 */
72uint32_t pldm_pdr_add(pldm_pdr *repo, const uint8_t *data, uint32_t size,
Manojkiran Eda3ca40452021-10-04 22:51:37 +053073 uint32_t record_handle, bool is_remote,
74 uint16_t terminus_handle);
Deepak Kodihalli3b02ed82020-02-06 01:18:25 -060075
76/** @brief Get record handle of a PDR record
77 *
78 * @param[in] repo - opaque pointer acting as a PDR repo handle
79 * @param[in] record - opaque pointer acting as a PDR record handle
80 *
81 * @return uint32_t - record handle assigned to PDR record; 0 if record is not
82 * found
83 */
84uint32_t pldm_pdr_get_record_handle(const pldm_pdr *repo,
85 const pldm_pdr_record *record);
86
87/** @brief Find PDR record by record handle
88 *
89 * @param[in] repo - opaque pointer acting as a PDR repo handle
90 * @param[in] record_handle - input record handle
91 * @param[in/out] data - will point to PDR record data (as per DSP0248) on
92 * return
93 * @param[out] size - *size will be size of PDR record
94 * @param[out] next_record_handle - *next_record_handle will be the record
95 * handle of record next to the returned PDR record
96 *
97 * @return opaque pointer acting as PDR record handle, will be NULL if record
98 * was not found
99 */
100const pldm_pdr_record *pldm_pdr_find_record(const pldm_pdr *repo,
101 uint32_t record_handle,
102 uint8_t **data, uint32_t *size,
103 uint32_t *next_record_handle);
104
105/** @brief Get PDR record next to input PDR record
106 *
107 * @param[in] repo - opaque pointer acting as a PDR repo handle
108 * @param[in] curr_record - opaque pointer acting as a PDR record handle
109 * @param[in/out] data - will point to PDR record data (as per DSP0248) on
110 * return
111 * @param[out] size - *size will be size of PDR record
112 * @param[out] next_record_handle - *next_record_handle will be the record
113 * handle of record nect to the returned PDR record
114 *
115 * @return opaque pointer acting as PDR record handle, will be NULL if record
116 * was not found
117 */
118const pldm_pdr_record *
119pldm_pdr_get_next_record(const pldm_pdr *repo,
120 const pldm_pdr_record *curr_record, uint8_t **data,
121 uint32_t *size, uint32_t *next_record_handle);
122
123/** @brief Find (first) PDR record by PDR type
124 *
125 * @param[in] repo - opaque pointer acting as a PDR repo handle
126 * @param[in] pdr_type - PDR type number as per DSP0248
127 * @param[in] curr_record - opaque pointer acting as a PDR record handle; if
128 * not NULL, then search will begin from this record's next record
129 * @param[in/out] data - will point to PDR record data (as per DSP0248) on
Pavithra Barithayae8beb892020-04-14 23:24:25 -0500130 * return, if input is not NULL
131 * @param[out] size - *size will be size of PDR record, if input is not NULL
Deepak Kodihalli3b02ed82020-02-06 01:18:25 -0600132 *
133 * @return opaque pointer acting as PDR record handle, will be NULL if record
134 * was not found
135 */
136const pldm_pdr_record *
137pldm_pdr_find_record_by_type(const pldm_pdr *repo, uint8_t pdr_type,
138 const pldm_pdr_record *curr_record, uint8_t **data,
139 uint32_t *size);
140
Deepak Kodihalli87514cc2020-04-16 09:08:38 -0500141bool pldm_pdr_record_is_remote(const pldm_pdr_record *record);
142
Deepak Kodihalli4a680932020-04-22 03:31:17 -0500143/** @brief Remove all PDR records that belong to a remote terminus
144 *
145 * @param[in] repo - opaque pointer acting as a PDR repo handle
146 */
147void pldm_pdr_remove_remote_pdrs(pldm_pdr *repo);
148
Manojkiran Eda3ca40452021-10-04 22:51:37 +0530149/** @brief Remove all remote PDR's that beling to a specific terminus
150 * handle
151 * @param[in] repo - opaque pointer acting as a PDR repo handle
152 * @param[in] terminus_handle - Terminus Handle of the remove PLDM terminus
153 */
154void pldm_pdr_remove_pdrs_by_terminus_handle(pldm_pdr *repo,
155 uint16_t terminus_handle);
156
Pavithra Barithaya4f2538a2021-03-05 07:32:15 -0600157/** @brief Update the validity of TL PDR - the validity is decided based on
158 * whether the valid bit is set or not as per the spec DSP0248
159 *
160 * @param[in] repo - opaque pointer acting as a PDR repo handle
161 * @param[in] terminusHandle - PLDM terminus handle
162 * @param[in] tid - Terminus ID
163 * @param[in] tlEid - MCTP endpoint EID
164 * @param[in] valid - validity bit of TLPDR
165 */
166void pldm_pdr_update_TL_pdr(const pldm_pdr *repo, uint16_t terminusHandle,
167 uint8_t tid, uint8_t tlEid, bool valid);
168
Deepak Kodihallidb914672020-02-07 02:47:45 -0600169/* ======================= */
170/* FRU Record Set PDR APIs */
171/* ======================= */
172
173/** @brief Add a FRU record set PDR record to a PDR repository
174 *
175 * @param[in/out] repo - opaque pointer acting as a PDR repo handle
176 * @param[in] terminus_handle - PLDM terminus handle of terminus owning the PDR
177 * record
178 * @param[in] fru_rsi - FRU record set identifier
179 * @param[in] entity_type - entity type of FRU
180 * @param[in] entity_instance_num - entity instance number of FRU
181 * @param[in] container_id - container id of FRU
Pavithra Barithaya4f2538a2021-03-05 07:32:15 -0600182 * @param[in] bmc_record_handle - handle used to construct the next record
Deepak Kodihallidb914672020-02-07 02:47:45 -0600183 *
184 * @return uint32_t - record handle assigned to PDR record
185 */
186uint32_t pldm_pdr_add_fru_record_set(pldm_pdr *repo, uint16_t terminus_handle,
187 uint16_t fru_rsi, uint16_t entity_type,
188 uint16_t entity_instance_num,
Pavithra Barithaya4f2538a2021-03-05 07:32:15 -0600189 uint16_t container_id,
190 uint32_t bmc_record_handle);
Deepak Kodihallidb914672020-02-07 02:47:45 -0600191
192/** @brief Find a FRU record set PDR by FRU record set identifier
193 *
194 * @param[in] repo - opaque pointer acting as a PDR repo handle
195 * @param[in] fru_rsi - FRU record set identifier
196 * @param[in] terminus_handle - *terminus_handle will be FRU terminus handle of
197 * found PDR, or 0 if not found
198 * @param[in] entity_type - *entity_type will be FRU entity type of found PDR,
199 * or 0 if not found
200 * @param[in] entity_instance_num - *entity_instance_num will be FRU entity
201 * instance number of found PDR, or 0 if not found
202 * @param[in] container_id - *cintainer_id will be FRU container id of found
203 * PDR, or 0 if not found
204 *
205 * @return uint32_t - record handle assigned to PDR record
206 */
207const pldm_pdr_record *pldm_pdr_fru_record_set_find_by_rsi(
208 const pldm_pdr *repo, uint16_t fru_rsi, uint16_t *terminus_handle,
209 uint16_t *entity_type, uint16_t *entity_instance_num,
210 uint16_t *container_id);
211
Deepak Kodihalli05787052020-03-10 01:54:08 -0500212/* =========================== */
213/* Entity Association PDR APIs */
214/* =========================== */
215
216typedef struct pldm_entity {
217 uint16_t entity_type;
218 uint16_t entity_instance_num;
219 uint16_t entity_container_id;
220} __attribute__((packed)) pldm_entity;
221
222enum entity_association_containment_type {
223 PLDM_ENTITY_ASSOCIAION_PHYSICAL = 0x0,
Deepak Kodihalli0a738f02020-03-10 01:56:21 -0500224 PLDM_ENTITY_ASSOCIAION_LOGICAL = 0x1,
Deepak Kodihalli05787052020-03-10 01:54:08 -0500225};
226
227/** @struct pldm_entity_association_tree
228 * opaque structure that represents the entity association hierarchy
229 */
230typedef struct pldm_entity_association_tree pldm_entity_association_tree;
231
232/** @struct pldm_entity_node
233 * opaque structure that represents a node in the entity association hierarchy
234 */
235typedef struct pldm_entity_node pldm_entity_node;
236
237/** @brief Make a new entity association tree
238 *
239 * @return opaque pointer that acts as a handle to the tree; NULL if no
240 * tree could be created
241 */
242pldm_entity_association_tree *pldm_entity_association_tree_init();
243
244/** @brief Add an entity into the entity association tree
245 *
246 * @param[in/out] tree - opaque pointer acting as a handle to the tree
247 * @param[in/out] entity - pointer to the entity to be added. Input has the
248 * entity type. On output, instance number and the
249 * container id are populated.
George Liu64a8f0f2021-06-12 10:56:11 +0800250 * @param[in] entity_instance_number - entity instance number, we can use the
251 * entity instance number of the entity by
252 * default if its value is equal 0xFFFF.
Deepak Kodihalli05787052020-03-10 01:54:08 -0500253 * @param[in] parent - pointer to the node that should be the parent of input
254 * entity. If this is NULL, then the entity is the root
255 * @param[in] association_type - relation with the parent : logical or physical
256 *
257 * @return pldm_entity_node* - opaque pointer to added entity
258 */
George Liu64a8f0f2021-06-12 10:56:11 +0800259pldm_entity_node *pldm_entity_association_tree_add(
260 pldm_entity_association_tree *tree, pldm_entity *entity,
261 uint16_t entity_instance_number, pldm_entity_node *parent,
262 uint8_t association_type);
Deepak Kodihalli05787052020-03-10 01:54:08 -0500263
264/** @brief Visit and note each entity in the entity association tree
265 *
266 * @param[in] tree - opaque pointer acting as a handle to the tree
267 * @param[out] entities - pointer to list of pldm_entity's. To be free()'d by
268 * the caller
269 * @param[out] size - number of pldm_entity's
270 */
271void pldm_entity_association_tree_visit(pldm_entity_association_tree *tree,
272 pldm_entity **entities, size_t *size);
273
George Liud9855ab2021-05-13 09:41:31 +0800274/** @brief Extract pldm entity by the pldm_entity_node
275 *
276 * @param[in] node - opaque pointer to added entity
277 *
278 * @return pldm_entity - pldm entity
279 */
280pldm_entity pldm_entity_extract(pldm_entity_node *node);
281
Deepak Kodihalli05787052020-03-10 01:54:08 -0500282/** @brief Destroy entity association tree
283 *
284 * @param[in] tree - opaque pointer acting as a handle to the tree
285 */
286void pldm_entity_association_tree_destroy(pldm_entity_association_tree *tree);
287
288/** @brief Check if input enity node is a parent
289 *
290 * @param[in] node - opaque pointer acting as a handle to an entity node
291 *
292 * @return bool true if node is a parent, false otherwise
293 */
294bool pldm_entity_is_node_parent(pldm_entity_node *node);
295
George Liufe77eea2021-04-28 15:08:07 +0800296/** @brief Get parent of entity
297 *
298 * @param[in] node - opaque pointer acting as a handle to an entity node
299 *
George Liub6b3cf32021-06-07 16:30:59 +0800300 * @return pldm_entity - pldm entity
George Liufe77eea2021-04-28 15:08:07 +0800301 */
George Liub6b3cf32021-06-07 16:30:59 +0800302pldm_entity pldm_entity_get_parent(pldm_entity_node *node);
303
304/** @brief Check the current pldm entity is exist parent
305 *
306 * @param[in] node - opaque pointer acting as a handle to an entity node
307 *
308 * @return bool true if exist parent, false otherwise
309 */
310bool pldm_entity_is_exist_parent(pldm_entity_node *node);
George Liufe77eea2021-04-28 15:08:07 +0800311
Deepak Kodihalli0a738f02020-03-10 01:56:21 -0500312/** @brief Convert entity association tree to PDR
313 *
314 * @param[in] tree - opaque pointer to entity association tree
315 * @param[in] repo - PDR repo where entity association records should be added
Deepak Kodihalli87514cc2020-04-16 09:08:38 -0500316 * @param[in] is_remote - if true, then the PDR is not from this terminus
Manojkiran Eda3ca40452021-10-04 22:51:37 +0530317 * @param[in] terminus_handle - terminus handle of the terminus
Deepak Kodihalli0a738f02020-03-10 01:56:21 -0500318 */
319void pldm_entity_association_pdr_add(pldm_entity_association_tree *tree,
Manojkiran Eda3ca40452021-10-04 22:51:37 +0530320 pldm_pdr *repo, bool is_remote,
321 uint16_t terminus_handle);
Sampa Misra719ed392021-06-04 05:15:13 -0500322/** @brief Add entity association pdr from node
323 *
324 * @param[in] node - opaque pointer acting as a handle to an entity node
325 * @param[in] repo - PDR repo where entity association records should be added
326 * @param[in] is_remote - if true, then the PDR is not from this terminus
Manojkiran Eda3ca40452021-10-04 22:51:37 +0530327 * @param[in] terminus_handle - terminus handle of the terminus
Sampa Misra719ed392021-06-04 05:15:13 -0500328 */
Manojkiran Eda3ca40452021-10-04 22:51:37 +0530329void pldm_entity_association_pdr_add_from_node(
330 pldm_entity_node *node, pldm_pdr *repo, pldm_entity **entities,
331 size_t num_entities, bool is_remote, uint16_t terminus_handle);
Sampa Misra719ed392021-06-04 05:15:13 -0500332
333/** @brief Find entity reference in tree
334 *
335 * @param[in] tree - opaque pointer to entity association tree
336 * @param[in] entity - PLDM entity
337 * @param[in] node - node to the entity
338 */
339void pldm_find_entity_ref_in_tree(pldm_entity_association_tree *tree,
340 pldm_entity entity, pldm_entity_node **node);
Deepak Kodihalli0a738f02020-03-10 01:56:21 -0500341
342/** @brief Get number of children of entity
343 *
344 * @param[in] node - opaque pointer acting as a handle to an entity node
345 * @param[in] association_type - relation type filter : logical or physical
346 *
347 * @return uint8_t number of children
348 */
349uint8_t pldm_entity_get_num_children(pldm_entity_node *node,
350 uint8_t association_type);
351
George Liu6a6c3ab2021-06-22 16:12:42 +0800352/** @brief Verify that the current node is a child of the current parent
353 *
354 * @param[in] parent - opaque pointer acting as a handle to an entity parent
355 * @param[in] node - pointer to the node of the pldm entity
356 */
357bool pldm_is_current_parent_child(pldm_entity_node *parent, pldm_entity *node);
358
Deepak Kodihalli3b28ba82020-03-30 07:39:47 -0500359/** @brief Find an entity in the entity association tree
360 *
361 * @param[in] tree - pointer to entity association tree
362 * @param[in/out] entity - entity type and instance id set on input, container
363 * id set on output
364 *
365 * @return pldm_entity_node* pointer to entity if found, NULL otherwise
366 */
367pldm_entity_node *
368pldm_entity_association_tree_find(pldm_entity_association_tree *tree,
369 pldm_entity *entity);
370
Sampa Misrac073a202021-05-08 10:56:05 -0500371/** @brief Create a copy of an existing entity association tree
372 *
373 * @param[in] org_tree - pointer to source tree
374 * @param[in/out] new_tree - pointer to destination tree
375 */
376void pldm_entity_association_tree_copy_root(
377 pldm_entity_association_tree *org_tree,
378 pldm_entity_association_tree *new_tree);
379
380/** @brief Destroy all the nodes of the entity association tree
381 *
382 * @param[in] tree - pointer to entity association tree
383 */
384void pldm_entity_association_tree_destroy_root(
385 pldm_entity_association_tree *tree);
386
387/** @brief Check whether the entity association tree is empty
388 *
389 * @param[in] tree - pointer to entity association tree
390 * @return bool, true if tree is empty
391 */
392bool pldm_is_empty_entity_assoc_tree(pldm_entity_association_tree *tree);
393
Deepak Kodihalli3b28ba82020-03-30 07:39:47 -0500394/** @brief Extract entities from entity association PDR
395 *
396 * @param[in] pdr - entity association PDR
397 * @param[in] pdr_len - size of entity association PDR in bytes
398 * @param[out] num_entities - number of entities found, including the container
399 * @param[out] entities - extracted entities, container is *entities[0]. Caller
400 * must free *entities
401 */
402void pldm_entity_association_pdr_extract(const uint8_t *pdr, uint16_t pdr_len,
403 size_t *num_entities,
404 pldm_entity **entities);
405
Deepak Kodihalli3b02ed82020-02-06 01:18:25 -0600406#ifdef __cplusplus
407}
408#endif
409
410#endif /* PDR_H */