pdr: Document preconditions for trivial accessor functions
Don't force the implementation to handle invalid pointers and convolute
what should be a simple API.
Callers must already be validating this precondition to avoid the
assert() in the implementations. The change just explicitly defines the
requirement.
Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
Change-Id: I8285c998ed5cd69489f00b3873dadf7901938ace
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 601fbbc..8c137bc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,24 @@
5. bios_table: pldm_bios_table_iter_next(): Invalid entry halts iteration
6. pdr: pldm_pdr_init(): Return NULL on allocation failure
7. pdr: pldm_pdr_destroy(): Exit early if repo is NULL
+8. pdr: Document preconditions for trivial accessor functions
+
+ A trivial accessor function is one that exposes properties of an object in a
+ way can't result in an error, beyond passing an invalid argument to the
+ function. For APIs meeting this definition we define a precondition that
+ struct pointers must point to valid objects to avoid polluting the function
+ prototypes. The following APIs now have this precondition explicitly defined:
+
+ - pldm_entity_extract()
+ - pldm_entity_get_parent()
+ - pldm_entity_is_exist_parent()
+ - pldm_entity_is_node_parent()
+ - pldm_is_current_parent_child
+ - pldm_is_empty_entity_assoc_tree()
+ - pldm_pdr_get_record_count()
+ - pldm_pdr_get_record_handle()
+ - pldm_pdr_get_repo_size()
+ - pldm_pdr_record_is_remote()
### Deprecated
diff --git a/include/libpldm/pdr.h b/include/libpldm/pdr.h
index de5a787..bff474a 100644
--- a/include/libpldm/pdr.h
+++ b/include/libpldm/pdr.h
@@ -42,6 +42,8 @@
/** @brief Get number of records in a PDR repository
*
+ * @pre repo must point to a valid object
+ *
* @param[in] repo - opaque pointer acting as a PDR repo handle
*
* @return uint32_t - number of records
@@ -50,6 +52,8 @@
/** @brief Get size of a PDR repository, in bytes
*
+ * @pre repo must point to a valid object
+ *
* @param[in] repo - opaque pointer acting as a PDR repo handle
*
* @return uint32_t - size in bytes
@@ -75,6 +79,9 @@
/** @brief Get record handle of a PDR record
*
+ * @pre repo must point to a valid object
+ * @pre record must point to a valid object
+ *
* @param[in] repo - opaque pointer acting as a PDR repo handle
* @param[in] record - opaque pointer acting as a PDR record handle
*
@@ -138,6 +145,12 @@
const pldm_pdr_record *curr_record, uint8_t **data,
uint32_t *size);
+/** @brief Determine if a record is a remote record
+ *
+ * @pre record must point to a valid object
+ *
+ * @return true if the record is a remote record, false otherwise.
+ */
bool pldm_pdr_record_is_remote(const pldm_pdr_record *record);
/** @brief Remove all PDR records that belong to a remote terminus
@@ -337,6 +350,8 @@
/** @brief Extract pldm entity by the pldm_entity_node
*
+ * @pre node must point to a valid object
+ *
* @param[in] node - opaque pointer to added entity
*
* @return pldm_entity - pldm entity
@@ -360,6 +375,8 @@
/** @brief Check if input enity node is a parent
*
+ * @pre node must point to a valid object
+ *
* @param[in] node - opaque pointer acting as a handle to an entity node
*
* @return bool true if node is a parent, false otherwise
@@ -368,6 +385,8 @@
/** @brief Get parent of entity
*
+ * @pre node must point to a valid object
+ *
* @param[in] node - opaque pointer acting as a handle to an entity node
*
* @return pldm_entity - pldm entity
@@ -376,6 +395,8 @@
/** @brief Check the current pldm entity is exist parent
*
+ * @pre node must point to a valid object
+ *
* @param[in] node - opaque pointer acting as a handle to an entity node
*
* @return bool true if exist parent, false otherwise
@@ -442,6 +463,9 @@
/** @brief Verify that the current node is a child of the current parent
*
+ * @pre parent must point to a valid object
+ * @pre node must point to a valid object
+ *
* @param[in] parent - opaque pointer acting as a handle to an entity parent
* @param[in] node - pointer to the node of the pldm entity
*/
@@ -491,6 +515,8 @@
/** @brief Check whether the entity association tree is empty
*
+ * @pre tree must point to a valid object
+ *
* @param[in] tree - pointer to entity association tree
* @return bool, true if tree is empty
*/
diff --git a/src/pdr.c b/src/pdr.c
index c350177..3cd0f3a 100644
--- a/src/pdr.c
+++ b/src/pdr.c
@@ -261,7 +261,8 @@
}
LIBPLDM_ABI_STABLE
-uint32_t pldm_pdr_get_record_handle(const pldm_pdr *repo,
+uint32_t pldm_pdr_get_record_handle(const pldm_pdr *repo
+ __attribute__((unused)),
const pldm_pdr_record *record)
{
assert(repo != NULL);