| #ifndef PDR_H |
| #define PDR_H |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| #include <stdbool.h> |
| #include <stddef.h> |
| #include <stdint.h> |
| |
| /** @struct pldm_pdr |
| * opaque structure that acts as a handle to a PDR repository |
| */ |
| typedef struct pldm_pdr pldm_pdr; |
| |
| /** @struct pldm_pdr_record |
| * opaque structure that acts as a handle to a PDR record |
| */ |
| typedef struct pldm_pdr_record pldm_pdr_record; |
| |
| /* ====================== */ |
| /* Common PDR access APIs */ |
| /* ====================== */ |
| |
| /** @brief Make a new PDR repository |
| * |
| * @return opaque pointer that acts as a handle to the repository; NULL if no |
| * repository could be created |
| * |
| * @note Caller may make multiple repositories (for its own PDRs, as well as |
| * for PDRs received by other entities) and can associate the returned handle |
| * to a PLDM terminus id. |
| */ |
| pldm_pdr *pldm_pdr_init(); |
| |
| /** @brief Destroy a PDR repository (and free up associated resources) |
| * |
| * @param[in/out] repo - pointer to opaque pointer acting as a PDR repo handle |
| */ |
| void pldm_pdr_destroy(pldm_pdr *repo); |
| |
| /** @brief Get number of records in a PDR repository |
| * |
| * @param[in] repo - opaque pointer acting as a PDR repo handle |
| * |
| * @return uint32_t - number of records |
| */ |
| uint32_t pldm_pdr_get_record_count(const pldm_pdr *repo); |
| |
| /** @brief Get size of a PDR repository, in bytes |
| * |
| * @param[in] repo - opaque pointer acting as a PDR repo handle |
| * |
| * @return uint32_t - size in bytes |
| */ |
| uint32_t pldm_pdr_get_repo_size(const pldm_pdr *repo); |
| |
| /** @brief Add a PDR record to a PDR repository |
| * |
| * @param[in/out] repo - opaque pointer acting as a PDR repo handle |
| * @param[in] data - pointer to a PDR record, pointing to a PDR definition as |
| * per DSP0248. This data is memcpy'd. |
| * @param[in] size - size of input PDR record in bytes |
| * @param[in] record_handle - record handle of input PDR record; if this is set |
| * to 0, then a record handle is computed and assigned to this PDR record |
| * @param[in] is_remote - if true, then the PDR is not from this terminus |
| * |
| * @return uint32_t - record handle assigned to PDR record |
| */ |
| uint32_t pldm_pdr_add(pldm_pdr *repo, const uint8_t *data, uint32_t size, |
| uint32_t record_handle, bool is_remote); |
| |
| /** @brief Get record handle of a PDR record |
| * |
| * @param[in] repo - opaque pointer acting as a PDR repo handle |
| * @param[in] record - opaque pointer acting as a PDR record handle |
| * |
| * @return uint32_t - record handle assigned to PDR record; 0 if record is not |
| * found |
| */ |
| uint32_t pldm_pdr_get_record_handle(const pldm_pdr *repo, |
| const pldm_pdr_record *record); |
| |
| /** @brief Find PDR record by record handle |
| * |
| * @param[in] repo - opaque pointer acting as a PDR repo handle |
| * @param[in] record_handle - input record handle |
| * @param[in/out] data - will point to PDR record data (as per DSP0248) on |
| * return |
| * @param[out] size - *size will be size of PDR record |
| * @param[out] next_record_handle - *next_record_handle will be the record |
| * handle of record next to the returned PDR record |
| * |
| * @return opaque pointer acting as PDR record handle, will be NULL if record |
| * was not found |
| */ |
| const pldm_pdr_record *pldm_pdr_find_record(const pldm_pdr *repo, |
| uint32_t record_handle, |
| uint8_t **data, uint32_t *size, |
| uint32_t *next_record_handle); |
| |
| /** @brief Get PDR record next to input PDR record |
| * |
| * @param[in] repo - opaque pointer acting as a PDR repo handle |
| * @param[in] curr_record - opaque pointer acting as a PDR record handle |
| * @param[in/out] data - will point to PDR record data (as per DSP0248) on |
| * return |
| * @param[out] size - *size will be size of PDR record |
| * @param[out] next_record_handle - *next_record_handle will be the record |
| * handle of record nect to the returned PDR record |
| * |
| * @return opaque pointer acting as PDR record handle, will be NULL if record |
| * was not found |
| */ |
| const pldm_pdr_record * |
| pldm_pdr_get_next_record(const pldm_pdr *repo, |
| const pldm_pdr_record *curr_record, uint8_t **data, |
| uint32_t *size, uint32_t *next_record_handle); |
| |
| /** @brief Find (first) PDR record by PDR type |
| * |
| * @param[in] repo - opaque pointer acting as a PDR repo handle |
| * @param[in] pdr_type - PDR type number as per DSP0248 |
| * @param[in] curr_record - opaque pointer acting as a PDR record handle; if |
| * not NULL, then search will begin from this record's next record |
| * @param[in/out] data - will point to PDR record data (as per DSP0248) on |
| * return, if input is not NULL |
| * @param[out] size - *size will be size of PDR record, if input is not NULL |
| * |
| * @return opaque pointer acting as PDR record handle, will be NULL if record |
| * was not found |
| */ |
| const pldm_pdr_record * |
| pldm_pdr_find_record_by_type(const pldm_pdr *repo, uint8_t pdr_type, |
| const pldm_pdr_record *curr_record, uint8_t **data, |
| uint32_t *size); |
| |
| bool pldm_pdr_record_is_remote(const pldm_pdr_record *record); |
| |
| /** @brief Remove all PDR records that belong to a remote terminus |
| * |
| * @param[in] repo - opaque pointer acting as a PDR repo handle |
| */ |
| void pldm_pdr_remove_remote_pdrs(pldm_pdr *repo); |
| |
| /** @brief Update the validity of TL PDR - the validity is decided based on |
| * whether the valid bit is set or not as per the spec DSP0248 |
| * |
| * @param[in] repo - opaque pointer acting as a PDR repo handle |
| * @param[in] terminusHandle - PLDM terminus handle |
| * @param[in] tid - Terminus ID |
| * @param[in] tlEid - MCTP endpoint EID |
| * @param[in] valid - validity bit of TLPDR |
| */ |
| void pldm_pdr_update_TL_pdr(const pldm_pdr *repo, uint16_t terminusHandle, |
| uint8_t tid, uint8_t tlEid, bool valid); |
| |
| /* ======================= */ |
| /* FRU Record Set PDR APIs */ |
| /* ======================= */ |
| |
| /** @brief Add a FRU record set PDR record to a PDR repository |
| * |
| * @param[in/out] repo - opaque pointer acting as a PDR repo handle |
| * @param[in] terminus_handle - PLDM terminus handle of terminus owning the PDR |
| * record |
| * @param[in] fru_rsi - FRU record set identifier |
| * @param[in] entity_type - entity type of FRU |
| * @param[in] entity_instance_num - entity instance number of FRU |
| * @param[in] container_id - container id of FRU |
| * @param[in] bmc_record_handle - handle used to construct the next record |
| * |
| * @return uint32_t - record handle assigned to PDR record |
| */ |
| uint32_t pldm_pdr_add_fru_record_set(pldm_pdr *repo, uint16_t terminus_handle, |
| uint16_t fru_rsi, uint16_t entity_type, |
| uint16_t entity_instance_num, |
| uint16_t container_id, |
| uint32_t bmc_record_handle); |
| |
| /** @brief Find a FRU record set PDR by FRU record set identifier |
| * |
| * @param[in] repo - opaque pointer acting as a PDR repo handle |
| * @param[in] fru_rsi - FRU record set identifier |
| * @param[in] terminus_handle - *terminus_handle will be FRU terminus handle of |
| * found PDR, or 0 if not found |
| * @param[in] entity_type - *entity_type will be FRU entity type of found PDR, |
| * or 0 if not found |
| * @param[in] entity_instance_num - *entity_instance_num will be FRU entity |
| * instance number of found PDR, or 0 if not found |
| * @param[in] container_id - *cintainer_id will be FRU container id of found |
| * PDR, or 0 if not found |
| * |
| * @return uint32_t - record handle assigned to PDR record |
| */ |
| const pldm_pdr_record *pldm_pdr_fru_record_set_find_by_rsi( |
| const pldm_pdr *repo, uint16_t fru_rsi, uint16_t *terminus_handle, |
| uint16_t *entity_type, uint16_t *entity_instance_num, |
| uint16_t *container_id); |
| |
| /* =========================== */ |
| /* Entity Association PDR APIs */ |
| /* =========================== */ |
| |
| typedef struct pldm_entity { |
| uint16_t entity_type; |
| uint16_t entity_instance_num; |
| uint16_t entity_container_id; |
| } __attribute__((packed)) pldm_entity; |
| |
| enum entity_association_containment_type { |
| PLDM_ENTITY_ASSOCIAION_PHYSICAL = 0x0, |
| PLDM_ENTITY_ASSOCIAION_LOGICAL = 0x1, |
| }; |
| |
| /** @struct pldm_entity_association_tree |
| * opaque structure that represents the entity association hierarchy |
| */ |
| typedef struct pldm_entity_association_tree pldm_entity_association_tree; |
| |
| /** @struct pldm_entity_node |
| * opaque structure that represents a node in the entity association hierarchy |
| */ |
| typedef struct pldm_entity_node pldm_entity_node; |
| |
| /** @brief Make a new entity association tree |
| * |
| * @return opaque pointer that acts as a handle to the tree; NULL if no |
| * tree could be created |
| */ |
| pldm_entity_association_tree *pldm_entity_association_tree_init(); |
| |
| /** @brief Add an entity into the entity association tree |
| * |
| * @param[in/out] tree - opaque pointer acting as a handle to the tree |
| * @param[in/out] entity - pointer to the entity to be added. Input has the |
| * entity type. On output, instance number and the |
| * container id are populated. |
| * @param[in] entity_instance_number - entity instance number, we can use the |
| * entity instance number of the entity by |
| * default if its value is equal 0xFFFF. |
| * @param[in] parent - pointer to the node that should be the parent of input |
| * entity. If this is NULL, then the entity is the root |
| * @param[in] association_type - relation with the parent : logical or physical |
| * |
| * @return pldm_entity_node* - opaque pointer to added entity |
| */ |
| pldm_entity_node *pldm_entity_association_tree_add( |
| pldm_entity_association_tree *tree, pldm_entity *entity, |
| uint16_t entity_instance_number, pldm_entity_node *parent, |
| uint8_t association_type); |
| |
| /** @brief Visit and note each entity in the entity association tree |
| * |
| * @param[in] tree - opaque pointer acting as a handle to the tree |
| * @param[out] entities - pointer to list of pldm_entity's. To be free()'d by |
| * the caller |
| * @param[out] size - number of pldm_entity's |
| */ |
| void pldm_entity_association_tree_visit(pldm_entity_association_tree *tree, |
| pldm_entity **entities, size_t *size); |
| |
| /** @brief Extract pldm entity by the pldm_entity_node |
| * |
| * @param[in] node - opaque pointer to added entity |
| * |
| * @return pldm_entity - pldm entity |
| */ |
| pldm_entity pldm_entity_extract(pldm_entity_node *node); |
| |
| /** @brief Destroy entity association tree |
| * |
| * @param[in] tree - opaque pointer acting as a handle to the tree |
| */ |
| void pldm_entity_association_tree_destroy(pldm_entity_association_tree *tree); |
| |
| /** @brief Check if input enity node is a parent |
| * |
| * @param[in] node - opaque pointer acting as a handle to an entity node |
| * |
| * @return bool true if node is a parent, false otherwise |
| */ |
| bool pldm_entity_is_node_parent(pldm_entity_node *node); |
| |
| /** @brief Get parent of entity |
| * |
| * @param[in] node - opaque pointer acting as a handle to an entity node |
| * |
| * @return pldm_entity_node* - opaque pointer to parent entity |
| */ |
| pldm_entity_node *pldm_entity_get_parent(pldm_entity_node *node); |
| |
| /** @brief Convert entity association tree to PDR |
| * |
| * @param[in] tree - opaque pointer to entity association tree |
| * @param[in] repo - PDR repo where entity association records should be added |
| * @param[in] is_remote - if true, then the PDR is not from this terminus |
| */ |
| void pldm_entity_association_pdr_add(pldm_entity_association_tree *tree, |
| pldm_pdr *repo, bool is_remote); |
| /** @brief Add entity association pdr from node |
| * |
| * @param[in] node - opaque pointer acting as a handle to an entity node |
| * @param[in] repo - PDR repo where entity association records should be added |
| * @param[in] is_remote - if true, then the PDR is not from this terminus |
| */ |
| void pldm_entity_association_pdr_add_from_node(pldm_entity_node *node, |
| pldm_pdr *repo, |
| pldm_entity **entities, |
| size_t num_entities, |
| bool is_remote); |
| |
| /** @brief Find entity reference in tree |
| * |
| * @param[in] tree - opaque pointer to entity association tree |
| * @param[in] entity - PLDM entity |
| * @param[in] node - node to the entity |
| */ |
| void pldm_find_entity_ref_in_tree(pldm_entity_association_tree *tree, |
| pldm_entity entity, pldm_entity_node **node); |
| |
| /** @brief Get number of children of entity |
| * |
| * @param[in] node - opaque pointer acting as a handle to an entity node |
| * @param[in] association_type - relation type filter : logical or physical |
| * |
| * @return uint8_t number of children |
| */ |
| uint8_t pldm_entity_get_num_children(pldm_entity_node *node, |
| uint8_t association_type); |
| |
| /** @brief Verify that the current node is a child of the current parent |
| * |
| * @param[in] parent - opaque pointer acting as a handle to an entity parent |
| * @param[in] node - pointer to the node of the pldm entity |
| */ |
| bool pldm_is_current_parent_child(pldm_entity_node *parent, pldm_entity *node); |
| |
| /** @brief Find an entity in the entity association tree |
| * |
| * @param[in] tree - pointer to entity association tree |
| * @param[in/out] entity - entity type and instance id set on input, container |
| * id set on output |
| * |
| * @return pldm_entity_node* pointer to entity if found, NULL otherwise |
| */ |
| pldm_entity_node * |
| pldm_entity_association_tree_find(pldm_entity_association_tree *tree, |
| pldm_entity *entity); |
| |
| /** @brief Create a copy of an existing entity association tree |
| * |
| * @param[in] org_tree - pointer to source tree |
| * @param[in/out] new_tree - pointer to destination tree |
| */ |
| void pldm_entity_association_tree_copy_root( |
| pldm_entity_association_tree *org_tree, |
| pldm_entity_association_tree *new_tree); |
| |
| /** @brief Destroy all the nodes of the entity association tree |
| * |
| * @param[in] tree - pointer to entity association tree |
| */ |
| void pldm_entity_association_tree_destroy_root( |
| pldm_entity_association_tree *tree); |
| |
| /** @brief Check whether the entity association tree is empty |
| * |
| * @param[in] tree - pointer to entity association tree |
| * @return bool, true if tree is empty |
| */ |
| bool pldm_is_empty_entity_assoc_tree(pldm_entity_association_tree *tree); |
| |
| /** @brief Extract entities from entity association PDR |
| * |
| * @param[in] pdr - entity association PDR |
| * @param[in] pdr_len - size of entity association PDR in bytes |
| * @param[out] num_entities - number of entities found, including the container |
| * @param[out] entities - extracted entities, container is *entities[0]. Caller |
| * must free *entities |
| */ |
| void pldm_entity_association_pdr_extract(const uint8_t *pdr, uint16_t pdr_len, |
| size_t *num_entities, |
| pldm_entity **entities); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* PDR_H */ |