libpldm: Explicit deprecated, stable and testing ABI classes
Experimenting with new APIs is important, but ABI stability of the
library is also important. We wish to have the freedom to add APIs
without being burdened by them being immediately set in stone.
We implement this wish by introducing three classes of ABI:
1. deprecated
2. stable
3. testing
These are enforced by corresponding function attributes:
1. LIBPLDM_ABI_DEPRECATED
2. LIBPLDM_ABI_STABLE
3. LIBPLDM_ABI_TESTING
Symbol visibility in the library is flipped to 'hidden' by default, so
one of these annotations must be used for the symbol to be exposed.
With these classes in place there are now clear points in time at which
we update the ABI dumps captured under the abi/ directory: When an API
is migrated from the 'testing' class to the 'stable' class, or when
removed from the 'deprecated' class.
Which classes of functions are exposed by the build is controlled by the
new 'abi' meson option. The option is of array type which contains the
list of ABI classes the build should consider. It defaults to enabling
all classes to provide test coverage in CI. The classes used should be
constrained to deprecated and stable (and not test) in any dependent
projects.
Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
Change-Id: I25402e20c7be9c9f264f9ccd7ac36b384823734c
diff --git a/src/pdr.c b/src/pdr.c
index 232dd89..68342ef 100644
--- a/src/pdr.c
+++ b/src/pdr.c
@@ -1,3 +1,4 @@
+#include "config.h"
#include "pdr.h"
#include "platform.h"
#include <assert.h>
@@ -97,6 +98,7 @@
return record;
}
+LIBPLDM_ABI_STABLE
uint32_t pldm_pdr_add(pldm_pdr *repo, const uint8_t *data, uint32_t size,
uint32_t record_handle, bool is_remote,
uint16_t terminus_handle)
@@ -111,6 +113,7 @@
return record->record_handle;
}
+LIBPLDM_ABI_STABLE
pldm_pdr *pldm_pdr_init(void)
{
pldm_pdr *repo = malloc(sizeof(pldm_pdr));
@@ -123,6 +126,7 @@
return repo;
}
+LIBPLDM_ABI_STABLE
void pldm_pdr_destroy(pldm_pdr *repo)
{
assert(repo != NULL);
@@ -140,6 +144,7 @@
free(repo);
}
+LIBPLDM_ABI_STABLE
const pldm_pdr_record *pldm_pdr_find_record(const pldm_pdr *repo,
uint32_t record_handle,
uint8_t **data, uint32_t *size,
@@ -170,6 +175,7 @@
return NULL;
}
+LIBPLDM_ABI_STABLE
const pldm_pdr_record *
pldm_pdr_get_next_record(const pldm_pdr *repo,
const pldm_pdr_record *curr_record, uint8_t **data,
@@ -194,6 +200,7 @@
return curr_record->next;
}
+LIBPLDM_ABI_STABLE
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,
@@ -223,6 +230,7 @@
return NULL;
}
+LIBPLDM_ABI_STABLE
uint32_t pldm_pdr_get_record_count(const pldm_pdr *repo)
{
assert(repo != NULL);
@@ -230,6 +238,7 @@
return repo->record_count;
}
+LIBPLDM_ABI_STABLE
uint32_t pldm_pdr_get_repo_size(const pldm_pdr *repo)
{
assert(repo != NULL);
@@ -237,6 +246,7 @@
return repo->size;
}
+LIBPLDM_ABI_STABLE
uint32_t pldm_pdr_get_record_handle(const pldm_pdr *repo,
const pldm_pdr_record *record)
{
@@ -246,13 +256,15 @@
return record->record_handle;
}
-inline bool pldm_pdr_record_is_remote(const pldm_pdr_record *record)
+LIBPLDM_ABI_STABLE
+bool pldm_pdr_record_is_remote(const pldm_pdr_record *record)
{
assert(record != NULL);
return record->is_remote;
}
+LIBPLDM_ABI_STABLE
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,
@@ -282,6 +294,7 @@
terminus_handle);
}
+LIBPLDM_ABI_STABLE
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,
@@ -322,6 +335,7 @@
return NULL;
}
+LIBPLDM_ABI_STABLE
/* NOLINTNEXTLINE(readability-identifier-naming) */
void pldm_pdr_update_TL_pdr(const pldm_pdr *repo, uint16_t terminus_handle,
uint8_t tid, uint8_t tl_eid, bool valid_bit)
@@ -372,6 +386,7 @@
return ++tree->last_used_container_id;
}
+LIBPLDM_ABI_STABLE
pldm_entity pldm_entity_extract(pldm_entity_node *node)
{
assert(node != NULL);
@@ -379,6 +394,7 @@
return node->entity;
}
+LIBPLDM_ABI_STABLE
pldm_entity_association_tree *pldm_entity_association_tree_init(void)
{
pldm_entity_association_tree *tree =
@@ -411,6 +427,7 @@
return start;
}
+LIBPLDM_ABI_STABLE
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,
@@ -505,6 +522,7 @@
entity_association_tree_visit(node->first_child, entities, index);
}
+LIBPLDM_ABI_STABLE
void pldm_entity_association_tree_visit(pldm_entity_association_tree *tree,
pldm_entity **entities, size_t *size)
{
@@ -532,6 +550,7 @@
free(node);
}
+LIBPLDM_ABI_STABLE
void pldm_entity_association_tree_destroy(pldm_entity_association_tree *tree)
{
assert(tree != NULL);
@@ -540,21 +559,24 @@
free(tree);
}
-inline bool pldm_entity_is_node_parent(pldm_entity_node *node)
+LIBPLDM_ABI_STABLE
+bool pldm_entity_is_node_parent(pldm_entity_node *node)
{
assert(node != NULL);
return node->first_child != NULL;
}
-inline pldm_entity pldm_entity_get_parent(pldm_entity_node *node)
+LIBPLDM_ABI_STABLE
+pldm_entity pldm_entity_get_parent(pldm_entity_node *node)
{
assert(node != NULL);
return node->parent;
}
-inline bool pldm_entity_is_exist_parent(pldm_entity_node *node)
+LIBPLDM_ABI_STABLE
+bool pldm_entity_is_exist_parent(pldm_entity_node *node)
{
assert(node != NULL);
@@ -567,6 +589,7 @@
return true;
}
+LIBPLDM_ABI_STABLE
uint8_t pldm_entity_get_num_children(pldm_entity_node *node,
uint8_t association_type)
{
@@ -587,6 +610,7 @@
return count;
}
+LIBPLDM_ABI_STABLE
bool pldm_is_current_parent_child(pldm_entity_node *parent, pldm_entity *node)
{
assert(parent != NULL);
@@ -689,6 +713,7 @@
}
}
+LIBPLDM_ABI_STABLE
bool is_present(pldm_entity entity, pldm_entity **entities, size_t num_entities)
{
if (entities == NULL || num_entities == 0) {
@@ -724,6 +749,7 @@
num_entities, is_remote, terminus_handle);
}
+LIBPLDM_ABI_STABLE
void pldm_entity_association_pdr_add(pldm_entity_association_tree *tree,
pldm_pdr *repo, bool is_remote,
uint16_t terminus_handle)
@@ -735,6 +761,7 @@
terminus_handle);
}
+LIBPLDM_ABI_STABLE
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, uint16_t terminus_handle)
@@ -745,6 +772,7 @@
is_remote, terminus_handle);
}
+LIBPLDM_ABI_STABLE
void find_entity_ref_in_tree(pldm_entity_node *tree_node, pldm_entity entity,
pldm_entity_node **node)
{
@@ -763,6 +791,7 @@
find_entity_ref_in_tree(tree_node->next_sibling, entity, node);
}
+LIBPLDM_ABI_STABLE
void pldm_find_entity_ref_in_tree(pldm_entity_association_tree *tree,
pldm_entity entity, pldm_entity_node **node)
{
@@ -770,6 +799,7 @@
find_entity_ref_in_tree(tree->root, entity, node);
}
+LIBPLDM_ABI_STABLE
void pldm_pdr_remove_pdrs_by_terminus_handle(pldm_pdr *repo,
uint16_t terminus_handle)
{
@@ -817,6 +847,8 @@
}
}
}
+
+LIBPLDM_ABI_STABLE
void pldm_pdr_remove_remote_pdrs(pldm_pdr *repo)
{
assert(repo != NULL);
@@ -864,6 +896,7 @@
}
}
+LIBPLDM_ABI_STABLE
void entity_association_tree_find(pldm_entity_node *node, pldm_entity *entity,
pldm_entity_node **out)
{
@@ -882,6 +915,7 @@
entity_association_tree_find(node->first_child, entity, out);
}
+LIBPLDM_ABI_STABLE
pldm_entity_node *
pldm_entity_association_tree_find(pldm_entity_association_tree *tree,
pldm_entity *entity)
@@ -911,6 +945,7 @@
&((*new_node)->next_sibling));
}
+LIBPLDM_ABI_STABLE
void pldm_entity_association_tree_copy_root(
pldm_entity_association_tree *org_tree,
pldm_entity_association_tree *new_tree)
@@ -919,6 +954,7 @@
entity_association_tree_copy(org_tree->root, &(new_tree->root));
}
+LIBPLDM_ABI_STABLE
void pldm_entity_association_tree_destroy_root(
pldm_entity_association_tree *tree)
{
@@ -928,11 +964,13 @@
tree->root = NULL;
}
+LIBPLDM_ABI_STABLE
bool pldm_is_empty_entity_assoc_tree(pldm_entity_association_tree *tree)
{
return ((tree->root == NULL) ? true : false);
}
+LIBPLDM_ABI_STABLE
void pldm_entity_association_pdr_extract(const uint8_t *pdr, uint16_t pdr_len,
size_t *num_entities,
pldm_entity **entities)