Docs: Update ITS doxygen documentation in the header
Update the ITS doxygen documentation according to the PSA Storage API 1.0
pdf issued on 17/06/2019.
Change-Id: If351627bb127c75cf27b8e08aaa5c64b7ec0954c
Signed-off-by: Tudor Cretu <tudor.cretu@arm.com>
diff --git a/interface/include/psa/internal_trusted_storage.h b/interface/include/psa/internal_trusted_storage.h
index 8f67f22..3920bc9 100644
--- a/interface/include/psa/internal_trusted_storage.h
+++ b/interface/include/psa/internal_trusted_storage.h
@@ -20,13 +20,46 @@
#ifdef __cplusplus
extern "C" {
#endif
-#define PSA_ITS_API_VERSION_MAJOR 1
-#define PSA_ITS_API_VERSION_MINOR 0
-
+#define PSA_ITS_API_VERSION_MAJOR 1 /**< The major version number of the
+ * PSA ITS API
+ */
+#define PSA_ITS_API_VERSION_MINOR 0 /**< The minor version number of the
+ * PSA ITS API
+ */
// This version of the header file is associated with 1.0 final release.
/**
- * Create a new or modify an existing uid/value pair
+ * \brief Create a new, or modify an existing, uid/value pair
+ *
+ * Stores data in the internal storage.
+ *
+ * \param[in] uid The identifier for the data
+ * \param[in] data_length The size in bytes of the data in `p_data`
+ * \param[in] p_data A buffer containing the data
+ * \param[in] create_flags The flags that the data will be stored with
+ *
+ * \return A status indicating the success/failure of the operation
+ *
+ * \retval PSA_SUCCESS The operation completed successfully
+ * \retval PSA_ERROR_NOT_PERMITTED The operation failed because the
+ * provided `uid` value was already
+ * created with
+ * PSA_STORAGE_FLAG_WRITE_ONCE
+ * \retval PSA_ERROR_NOT_SUPPORTED The operation failed because one or
+ * more of the flags provided in
+ * `create_flags` is not supported or is
+ * not valid
+ * \retval PSA_ERROR_INSUFFICIENT_STORAGE The operation failed because there
+ * was insufficient space on the
+ * storage medium
+ * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the
+ * physical storage has failed (Fatal
+ * error)
+ * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one
+ * of the provided pointers(`p_data`)
+ * is invalid, for example is `NULL` or
+ * references memory the caller cannot
+ * access
*/
psa_status_t psa_its_set(psa_storage_uid_t uid,
size_t data_length,
@@ -34,7 +67,40 @@
psa_storage_create_flags_t create_flags);
/**
- * Retrieve data associated with a provided UID
+ * \brief Retrieve data associated with a provided UID
+ *
+ * Retrieves up to `data_size` bytes of the data associated with `uid`, starting
+ * at `data_offset` bytes from the beginning of the data. Upon successful
+ * completion, the data will be placed in the `p_data` buffer, which must be at
+ * least `data_size` bytes in size. The length of the data returned will be in
+ * `p_data_length`. If `data_size` is 0, the contents of `p_data_length` will
+ * be set to zero.
+ *
+ * \param[in] uid The uid value
+ * \param[in] data_offset The starting offset of the data requested
+ * \param[in] data_size The amount of data requested
+ * \param[out] p_data On success, the buffer where the data will
+ * be placed
+ * \param[out] p_data_length On success, this will contain size of the data
+ * placed in `p_data`
+ *
+ * \return A status indicating the success/failure of the operation
+ *
+ * \retval PSA_SUCCESS The operation completed successfully
+ * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the
+ * provided `uid` value was not found in
+ * the storage
+ * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the
+ * physical storage has failed (Fatal
+ * error)
+ * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the
+ * provided arguments (`p_data`,
+ * `p_data_length`) is invalid, for example
+ * is `NULL` or references memory the
+ * caller cannot access. In addition, this
+ * can also happen if `data_offset` is
+ * larger than the size of the data
+ * associated with `uid`
*/
psa_status_t psa_its_get(psa_storage_uid_t uid,
size_t data_offset,
@@ -43,13 +109,51 @@
size_t *p_data_length);
/**
- * Retrieve the metadata about the provided uid
+ * \brief Retrieve the metadata about the provided uid
+ *
+ * Retrieves the metadata stored for a given `uid` as a `psa_storage_info_t`
+ * structure.
+ *
+ * \param[in] uid The `uid` value
+ * \param[out] p_info A pointer to the `psa_storage_info_t` struct that will
+ * be populated with the metadata
+ *
+ * \return A status indicating the success/failure of the operation
+ *
+ * \retval PSA_SUCCESS The operation completed successfully
+ * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided
+ * uid value was not found in the storage
+ * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical
+ * storage has failed (Fatal error)
+ * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one of the
+ * provided pointers(`p_info`)
+ * is invalid, for example is `NULL` or
+ * references memory the caller cannot
+ * access
*/
psa_status_t psa_its_get_info(psa_storage_uid_t uid,
struct psa_storage_info_t *p_info);
/**
- * Remove the provided key and its associated data from the storage
+ * \brief Remove the provided uid and its associated data from the storage
+ *
+ * Deletes the data from internal storage.
+ *
+ * \param[in] uid The `uid` value
+ *
+ * \return A status indicating the success/failure of the operation
+ *
+ * \retval PSA_SUCCESS The operation completed successfully
+ * \retval PSA_ERROR_INVALID_ARGUMENT The operation failed because one or more
+ * of the given arguments were invalid (null
+ * pointer, wrong flags and so on)
+ * \retval PSA_ERROR_DOES_NOT_EXIST The operation failed because the provided
+ * uid value was not found in the storage
+ * \retval PSA_ERROR_NOT_PERMITTED The operation failed because the provided
+ * uid value was created with
+ * PSA_STORAGE_FLAG_WRITE_ONCE
+ * \retval PSA_ERROR_STORAGE_FAILURE The operation failed because the physical
+ * storage has failed (Fatal error)
*/
psa_status_t psa_its_remove(psa_storage_uid_t uid);