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/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
*/