Improve documentation of SE driver persistent state

Explain what it can be used for and when it is saved to storage.

Author: gilles-peskine-arm

include/psa/crypto_se_driver.h

@@ -55,8 +55,13 @@ extern "C" {
 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 @@ typedef struct {
      *
      * 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 @@ typedef struct {
      */
     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.