Adding Iterator and rename functions

doc/storage/api/api.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2019, 2022-2023 Arm Limited and/or its affiliates <[email protected]>
+.. SPDX-FileCopyrightText: Copyright 2018-2019, 2022-2024 Arm Limited and/or its affiliates <[email protected]>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 API Reference
@@ -9,7 +9,7 @@ Status codes
 
 The |API| uses the status code definitions that are shared with the other PSA Certified APIs.
 
-The following elements are defined in :file:`psa/error.h` from :cite-title:`PSA-STAT` (previously defined in :cite:`PSA-FFM`):
+The following elements are defined in :file:`psa/error.h` from :cite-title:`PSA-STAT` (previously defined in :cite:`PSA-FF-M`):
 
 .. code-block:: xref
 
@@ -63,15 +63,29 @@ These definitions must be defined in the header file :file:`psa/storage_common.h
     .. field:: psa_storage_create_flags_t flags
         The flags set when the ``uid`` was create
 
-.. struct:: psa_storage_iterator_t
+.. struct:: psa_its_storage_iterator_t
 
     .. summary::
         An implementation-defined opaque structure containing the context for an iterator.
         The structure MUST contain all all the state required by the iterator.
         That is, further state MUST NOT be retained by the implementation.
 
-        The structure is initilaised by the `ps_iterator_start()` function.
-        It is modified by the `ps_iterator_next()` function.
+        The structure is initilaised by the ``ps_iterator_start()`` function.
+        It is modified by the ``ps_iterator_next()`` function.
+
+        the caller can discard or reuse the iterator object once it has finished using it. This can be before, or after, the iterator has reached the end of the iteration.
+
+        The header file is only required to define this structure if PSA_STORAGE_SUPPORT_ITERATION is true.
+
+.. struct:: psa_ps_storage_iterator_t
+
+    .. summary::
+        An implementation-defined opaque structure containing the context for an iterator.
+        The structure MUST contain all all the state required by the iterator.
+        That is, further state MUST NOT be retained by the implementation.
+
+        The structure is initilaised by the ``ps_iterator_start()`` function.
+        It is modified by the ``ps_iterator_next()`` function.
 
         the caller can discard or reuse the iterator object once it has finished using it. This can be before, or after, the iterator has reached the end of the iteration.
 
@@ -128,14 +142,7 @@ These definitions must be defined in the header file :file:`psa/storage_common.h
 .. macro:: PSA_STORAGE_SUPPORT_ITERATION
     (1u << 2)
 
-    Flag indicating that `psa_ps_iterator_start()` and `psa_ps_iterator_next()` are supported.
-
-.. macro:: PSA_STORAGE_ITERATOR_CTX__SIZE
-    :definition: /* implementation-defined value */
-
-    .. summary::
-        A sufficient buffer size for a iterator context, in bytes.
-        This macro is only required if PSA_STORAGE_SUPPORT_ITERATION is true
+    Flag indicating that `psa_its_iterator_start()`, `psa_its_iterator_next()`  `psa_ps_iterator_start` and `psa_ps_iterator_next` are supported.
 
 
 .. _ITS-API:
@@ -217,7 +224,7 @@ These definitions must be defined in the header file :file:`psa/internal_trusted
 
     * The ``uid`` value must not be zero.
 
-    * If ``uid`` exists it must not have been created as with `PSA_STORAGE_FLAG_WRITE_ONCE` --- would result in `PSA_ERROR_NOT_PERMITTED`
+    * If ``uid`` exists it must not have been created as with `PSA_STORAGE_FLAG_WRITE_ONCE` --- would result in ``PSA_ERROR_NOT_PERMITTED``.
 
     * The caller must have access all memory from ``p_data`` to ``p_data + data_length``.
 
@@ -349,6 +356,133 @@ These definitions must be defined in the header file :file:`psa/internal_trusted
 
     * Even if all parameters are correct, the function can fail in the case of a storage failure.
 
+.. function:: psa_its_iterator_start
+
+   .. summary::
+       Initialises an iterator that can be used to return a list of uids in the Internal Trusted Storage.
+       This function must be fully defined if `PSA_STORAGE_SUPPORT_ITERATION` is true.
+       If `PSA_STORAGE_SUPPORT_ITERATION` is false, then this function SHALL always return ``PSA_ERROR_NOT_SUPPORTED``
+
+
+   .. param::  psa_its_storage_iterator_t* context
+       A pointer to a context for this iterator. The pointer may be NULL. This is set to a new value on success and is undefined on error. The content of the iterator is implementation defined.
+
+   .. param:: psa_storage_uid_t filter
+       A value used to filter the results included in this iteration.
+
+   .. param:: int_t filter_length
+       A length of the filter to use, this must be a value ``0 < filter_lemngth < 63``.
+
+   .. param:: psa_storage_uid_t *result
+        A pointer to the location in which to store ``uid``. On success the contents of this location will be updated with the first matching ``uid``. On error, the contents are undefined.
+
+   .. return:: psa_status_t
+       A status indicating the success or failure of the operation.
+
+   .. retval:: PSA_SUCCESS
+       The operation completed successfully.
+
+   .. retval:: PSA_ERROR_DOES_NOT_EXIST
+       No ``uid`` matches this iteration.
+
+   .. retval:: PSA_ERROR_STORAGE_FAILURE
+       The operation failed because the physical storage has failed (Fatal error).
+
+   The iterator returns those values where the ``filter_length`` bits of the ``uid`` matches the left most bits in ``filter``.
+
+   The iterator will only returns those ``uid`` that were created by the caller. It MUST not return any ``uid`` created by a different user.
+
+   An iterator is not required to return uids in any specific order, but MUST return them in a consistent order each time it is called. For example, if an implementation returns entries in numerical order, it should not arbitrarily change to returning them in creation order. However, the caller should not make assumptions as to the order in which entries are returned, except that each ``uid`` will be returned only once in each iteration.
+
+   Changes to storage by other users MUST NOT affect any open iterations.
+
+   A caller may initialize multiple iteration contexts at the same time. Each iteration shall be independent. Calling ``psa_its_iterator_next()`` on one iterator MUST not effect any other open iteration.
+
+   An iterator MUST return all data objects whose ``uid`` matches the filter that are extant when the filter was created, unless these are deleted or renamed before the iteration would return them, or the caller stops before all matching objects have been returned.
+
+   A caller may delete a ``uid`` with `psa_its_remove()` without invalidating the iteration context. the iterator MUST never return a ``uid`` that has been deleted. However, if the caller is multi-threaded it ia possible another thread may delete a ``uid``.
+
+   A caller may read the contents of any ``uid`` with `psa_its_get()` or write with `psa_its_set` without invalidating the iteration context.
+
+   A caller may create a ``uid`` with `psa_its_set()` without invalidating the iteration context. However, the iterator is NOT guaranteed to return the new object, ``uid``, the behavior is dependent on both implementation and identity. In particular, the iterator is not expected to return ``uid`` if the iteration is already past the point at which it would naturally be returned.
+
+   A caller may call ``psa_its_rename(uid, uid_new)`` without invalidating the iteration context. The iterator must not return ``uid``. The iterator is not guaranteed to return ``uid_new``, the behavior is dependent on both implementation and identity.
+
+   The following code snippet uses a linked list to store the matching files before iterating over that list and removing them.
+
+   .. code-block:: c
+
+      my_context = NULL
+      my_filter = 0x1111 0000 0000 0000
+      my_length = 0x0020
+      my_result = NULL
+      if psa_its_iterator_start(my_context, my_filter, my-length, my_result) == PSA_SUCCESS
+      	{
+      	do
+      	   {
+      	   	// do something with my_result
+      	    psa_its_iterator_next(my_context, my_result)
+      	    // we will get an does not exist error when we reach the last item, any other error is a storage failure
+      	    if my_reult <> PSA_ERROR_DOES_NOT_EXIST
+      	   	  {
+      	   	  	/* deal with storage failure */
+      	   	  }
+      	   }
+        while my_result == PSA_SUCCESS ;
+        };
+
+
+
+
+.. function:: psa_its_iterator_next
+
+   .. summary::
+
+      Returns the next ``uid`` in this iteration.
+      This function must be fully defined if `PSA_STORAGE_SUPPORT_ITERATION` is true.
+      If `PSA_STORAGE_SUPPORT_ITERATION` is false, then this function SHALL always return ``PSA_ERROR_NOT_SUPPORTED``
+
+
+   .. param::  psa_its_storage_iterator_t* context
+       A pointer to a context for this iterator as returned by `psa_its_iterator_start()` or updated by a previous call to `psa_its_iterator_next()`.  The content of the iterator will change on success and is undefined on error.
+
+   .. param:: psa_storage_uid_t *result
+        A pointer to the location in which to store ``uid``. On success the contents of this location will be updated with the next matching ``uid``. On error, the contents are undefined.
+
+   .. return:: psa_status_t
+       A status indicating the success or failure of the operation.
+
+   .. retval:: PSA_SUCCESS
+       The operation completed successfully.
+
+   .. retval:: PSA_ERROR_DOES_NOT_EXIST
+       The iterator has returned all the uids that match this iteration.
+
+   .. retval:: PSA_ERROR_STORAGE_FAILURE
+       The operation failed because the physical storage has failed (Fatal error).
+
+   .. retval:: PSA_ERROR_DATA_CORRUPT
+       The operation failed because the contents of the iteration have changed. That is a ``uid`` matching the filter has either been created or deleted.
+
+   .. retval:: PSA_ERROR_INVALID_ARGUMENT
+       The operation failed because either:
+
+       * The provided context is not valid.
+
+       * The caller cannot access the memory at ``result``
+
+.. function:: psa_its_get_support
+
+    .. summary::
+        Returns a bitmask with flags set for the optional features supported by the implementation.
+
+    Currently defined flags are limited to:
+
+    * `PSA_STORAGE_SUPPORT_ITERATION`
+
+    .. return:: uint32_t
+
+
 .. _PS-API:
 
 Protected Storage API
@@ -396,7 +530,7 @@ These definitions must be defined in the header file :file:`psa/protected_storag
     .. param:: size_t data_length
         The size in bytes of the data in ``p_data``.
         If ``data_length == 0`` the implementation will create a zero-length asset associated with the ``uid``.
-        While no data can be stored in such an asset, a call to `psa_ps_get_info()` will return `PSA_SUCCESS`.
+        While no data can be stored in such an asset, a call to `psa_ps_get_info()` will return ``PSA_SUCCESS``.
     .. param:: const void * p_data
         A buffer containing the data.
     .. param:: psa_storage_create_flags_t create_flags
@@ -637,6 +771,8 @@ These definitions must be defined in the header file :file:`psa/protected_storag
 
     .. summary::
         Overwrite part of the data of the specified ``uid``, leaving remaining data unchanged.
+        This function must be fully defined if `PSA_STORAGE_SUPPORT_SET_EXTENDED` is true.
+        If `PSA_STORAGE_SUPPORT_SET_EXTENDED` is false, then this function SHALL always return ``PSA_ERROR_NOT_SUPPORTED``.
 
     .. param:: psa_storage_uid_t uid
         The unique identifier for the asset.
@@ -709,7 +845,9 @@ These definitions must be defined in the header file :file:`psa/protected_storag
 .. function:: psa_ps_rename
 
    .. summary::
-        Atomically renames the storage location with the specified ``uid`` to a ``uid_new``.
+      Atomically renames the storage location with the specified ``uid`` to a ``uid_new``.
+      This function must be fully defined if `PSA_STORAGE_SUPPORT_RENAME` is true.
+      If `PSA_STORAGE_SUPPORT_RENAME` is false, then this function SHALL always return ``PSA_ERROR_NOT_SUPPORTED``.
 
    .. param:: psa_storage_uid_t uid
         The current identifier for the data.
@@ -762,9 +900,12 @@ These definitions must be defined in the header file :file:`psa/protected_storag
 .. function:: psa_ps_iterator_start
 
    .. summary::
-       Initialises an iterator that can be used to return a list of uids in the Protected Storage .
+       Initialises an iterator that can be used to return a list of uids in the Protected Storage.
+       This function must be fully defined if `PSA_STORAGE_SUPPORT_ITERATION` is true.
+       If `PSA_STORAGE_SUPPORT_ITERATION` is false, then this function SHALL always return ``PSA_ERROR_NOT_SUPPORTED``
 
-   .. param::  psa_storage_iterator_t* context
+
+   .. param::  psa_ps_storage_iterator_t* context
        A pointer to a context for this iterator. The pointer may be NULL. This is set to a new value on success and is undefined on error. The content of the iterator is implementation defined.
 
    .. param:: psa_storage_uid_t filter
@@ -796,17 +937,17 @@ These definitions must be defined in the header file :file:`psa/protected_storag
 
    Changes to storage by other users MUST NOT affect any open iterations.
 
-   A caller may initialize multiple iteration contexts at the same time. Each iteration shall be independent. Calling ``psa_ps_iterator_next()`` on one iterator MUST not effect any other open iteration.
+   A caller may initialize multiple iteration contexts at the same time. Each iteration shall be independent. Calling ``psa_ps_iterator_next`` on one iterator MUST not effect any other open iteration.
 
    An iterator MUST return all data objects whose ``uid`` matches the filter that are extant when the filter was created, unless these are deleted or renamed before the iteration would return them, or the caller stops before all matching objects have been returned.
 
-   A caller may delete a ``uid`` with `psa_ps_remove(uid)` without invalidating the iteration context. the iterator MUST never return a ``uid`` that has been deleted. However, if the caller is multi-threaded it ia possible another thread may delete a ``uid``.
+   A caller may delete a ``uid`` with `psa_ps_remove()` without invalidating the iteration context. the iterator MUST never return a ``uid`` that has been deleted. However, if the caller is multi-threaded it ia possible another thread may delete a ``uid``.
 
-   A caller may read the contents of any ``uid`` with `psa_ps_get()` or write with `psa_ps_set(` or `psa_ps_set_extended()` without invalidating the iteration context.
+   A caller may read the contents of any ``uid`` with `psa_ps_get()` or write with `psa_ps_set()` or `psa_ps_set_extended()` without invalidating the iteration context.
 
    A caller may create a ``uid`` with `psa_ps_set()` or `psa_ps_create()` without invalidating the iteration context. However, the iterator is NOT guaranteed to return the new object, ``uid``, the behavior is dependent on both implementation and identity. In particular, the iterator is not expected to return ``uid`` if the iteration is already past the point at which it would naturally be returned.
 
-   A caller may call `psa_ps_rename(uid, uid_new)` without invalidating the iteration context. The iterator must not return ``uid``. The iterator is not guaranteed to return ``uid_new``, the behavior is dependent on both implementation and identity.
+   A caller may call ``psa_ps_rename(uid, uid_new)`` without invalidating the iteration context. The iterator must not return ``uid``. The iterator is not guaranteed to return ``uid_new``, the behavior is dependent on both implementation and identity.
 
    The following code snippet uses a linked list to store the matching files before iterating over that list and removing them.
 
@@ -837,11 +978,12 @@ These definitions must be defined in the header file :file:`psa/protected_storag
 .. function:: psa_ps_iterator_next
 
    .. summary::
-
       Returns the next ``uid`` in this iteration.
+      This function must be fully defined if `PSA_STORAGE_SUPPORT_ITERATION` is true.
+      If `PSA_STORAGE_SUPPORT_ITERATION` is false, then this function SHALL always return ``PSA_ERROR_NOT_SUPPORTED``
 
-   .. param::  psa_storage_iterator_t* context
-       A pointer to a context for this iterator as returned by `psa_ps_iterator_start()` or updated by a previous call to `psa_ps_iterator_next()`.  The content of the iterator will change on success and is undefined on error.
+   .. param::  psa_ps_storage_iterator_t* context
+       A pointer to a context for this iterator as returned by `psa_ps_iterator_start` or updated by a previous call to `psa_ps_iterator_next`.  The content of the iterator will change on success and is undefined on error.
 
    .. param:: psa_storage_uid_t *result
         A pointer to the location in which to store ``uid``. On success the contents of this location will be updated with the next matching ``uid``. On error, the contents are undefined.
@@ -866,7 +1008,7 @@ These definitions must be defined in the header file :file:`psa/protected_storag
 
        * The provided context is not valid.
 
-       * The caller cannot access the memory at `result`
+       * The caller cannot access the memory at ``result``
 
 .. function:: psa_ps_get_support
 
@@ -880,3 +1022,4 @@ These definitions must be defined in the header file :file:`psa/protected_storag
     * `PSA_STORAGE_SUPPORT_ITERATION`
 
     .. return:: uint32_t
+