From 980230e965316f5f068e10f90e665a56bf044942 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Thu, 1 Apr 2021 15:37:49 +0200 Subject: [PATCH] psa: include: Update and improve multipart-op struct design notes Signed-off-by: Ronald Cron --- include/psa/crypto_struct.h | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h index b2da6a2c5..8ac7ce1ef 100644 --- a/include/psa/crypto_struct.h +++ b/include/psa/crypto_struct.h @@ -15,12 +15,20 @@ * *

Design notes about multipart operation structures

* - * Each multipart operation structure contains a `psa_algorithm_t alg` - * field which indicates which specific algorithm the structure is for. - * When the structure is not in use, `alg` is 0. Most of the structure - * consists of a union which is discriminated by `alg`. + * For multipart operations without driver delegation support, each multipart + * operation structure contains a `psa_algorithm_t alg` field which indicates + * which specific algorithm the structure is for. When the structure is not in + * use, `alg` is 0. Most of the structure consists of a union which is + * discriminated by `alg`. * - * Note that when `alg` is 0, the content of other fields is undefined. + * For multipart operations with driver delegation support, each multipart + * operation structure contains an `unsigned int id` field indicating which + * driver got assigned to do the operation. When the structure is not in use, + * 'id' is 0. The structure contains also a driver context which is the union + * of the contexts of all drivers able to handle the type of multipart + * operation. + * + * Note that when `alg` or `id` is 0, the content of other fields is undefined. * In particular, it is not guaranteed that a freshly-initialized structure * is all-zero: we initialize structures to something like `{0, 0}`, which * is only guaranteed to initializes the first member of the union; @@ -76,9 +84,9 @@ struct psa_hash_operation_s /** Unique ID indicating which driver got assigned to do the * operation. Since driver contexts are driver-specific, swapping * drivers halfway through the operation is not supported. - * ID values are auto-generated in psa_driver_wrappers.h + * ID values are auto-generated in psa_driver_wrappers.h. * ID value zero means the context is not valid or not assigned to - * any driver (i.e. none of the driver contexts are active). */ + * any driver (i.e. the driver context is not active, in use). */ unsigned int id; psa_driver_hash_context_t ctx; };