Improve documentation of SE driver persistent state
Explain what it can be used for and when it is saved to storage.
diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h
index 60447ce..9aebc45 100644
--- a/include/psa/crypto_se_driver.h
+++ b/include/psa/crypto_se_driver.h
@@ -55,8 +55,13 @@
typedef struct {
/** A read-only pointer to the driver's persistent data.
*
- * The PSA Cryptography core saves the persistent data from one
- * session to the next.
+ * Drivers typically use this persistent data to keep track of
+ * which slot numbers are available. This is only a guideline:
+ * drivers may use the persistent data for any purpose, keeping
+ * in mind the restrictions on when the persistent data is saved
+ * to storage: the persistent data is only saved after calling
+ * certain functions that receive a writable pointer to the
+ * persistent data.
*
* The core allocates a memory buffer for the persistent data.
* The pointer is guaranteed to be suitably aligned for any data type,
@@ -74,7 +79,23 @@
*
* This pointer is to read-only data. Only a few driver functions are
* allowed to modify the persistent data. These functions receive a
- * writable pointer.
+ * writable pointer. These functions are:
+ * - psa_drv_se_t::p_init
+ * - psa_drv_se_key_management_t::p_allocate
+ * - psa_drv_se_key_management_t::p_destroy
+ *
+ * The PSA Cryptography core saves the persistent data from one
+ * session to the next. It does this before returning from API functions
+ * that call a driver method that is allowed to modify the persistent
+ * data, specifically:
+ * - psa_crypto_init() causes a call to psa_drv_se_t::p_init, and may call
+ * psa_drv_se_key_management_t::p_destroy to complete an action
+ * that was interrupted by a power failure.
+ * - Key creation functions cause a call to
+ * psa_drv_se_key_management_t::p_allocate, and may cause a call to
+ * psa_drv_se_key_management_t::p_destroy in case an error occurs.
+ * - psa_destroy_key() causes a call to
+ * psa_drv_se_key_management_t::p_destroy.
*/
const void *const persistent_data;
@@ -1118,7 +1139,14 @@
*/
uint32_t hal_version;
- /** The size of the driver's persistent data in bytes. */
+ /** The size of the driver's persistent data in bytes.
+ *
+ * This can be 0 if the driver does not need persistent data.
+ *
+ * See the documentation of psa_drv_se_context_t::persistent_data
+ * for more information about why and how a driver can use
+ * persistent data.
+ */
size_t persistent_data_size;
/** The driver initialization function.