api: crypto: simplify operation result reporting

Make the return value of odp_crypto_result() indicate crypto operation
success/failure too. Deprecate the ok field of odp_crypto_packet_result_t.

Specify that the status fields of odp_crypto_packet_result_t are valid
only when the operation failed, odp_crypto_result() returned -1. This way
an implementation does not need to fill the status fields in the typical
case when the operation succeeds.

Allow the result pointer to be null, making filling the result structure
optional.

Deprecate odp_crypto_hw_err_t type and the hw_err field of
odp_crypto_op_status_t. It is simpler to have all errors reported
through the alg_err field.

Deprecate ODP_CRYPTO_ALG_ERR_KEY_SIZE and ODP_CRYPTO_ALG_ERR_IV_INVALID
error codes. Key length is a session parameter and an error in key size
can be reported at session creation time. IV is now a mandatory operation
parameter so a specific error code for null IV pointer is less useful
than it was when it was possible to provide IV at session creation.

Clarify the description of ODP_CRYPTO_ALG_ERR_DATA_SIZE.

Add a new crypto operation error ODP_CRYPTO_ALG_ERR_OTHER to cover cases
for which the other errors do not fit.

Signed-off-by: Janne Peltonen <janne.peltonen@nokia.com>
Reviewed-by: Anoob Joseph <anoobj@marvell.com>
Reviewed-by: Petri Savolainen <petri.savolainen@nokia.com>

1 files changed, 19 insertions, 8 deletions

diff --git a/include/odp/api/spec/crypto.h b/include/odp/api/spec/crypto.h
index 4292b78c1..d9265c57e 100644
--- a/include/odp/api/spec/crypto.h
+++ b/include/odp/api/spec/crypto.h
@@ -259,17 +259,28 @@ odp_event_t odp_crypto_packet_to_event(odp_packet_t pkt);
 /**
  * Get crypto operation results from a crypto processed packet
  *
- * Successful crypto operations of all types (SYNC and ASYNC) produce packets
- * which contain crypto result metadata. This function copies the operation
- * results from a crypto processed packet. Event subtype of this kind of
- * packet is ODP_EVENT_PACKET_CRYPTO. Results are undefined if a non-crypto
- * processed packet is passed as input.
+ * Crypto operations of all types (SYNC and ASYNC) produce packets which
+ * contain crypto result metadata. This function returns success status
+ * of the crypto operation that was applied to a packet and optionally
+ * writes additional information in a result structure.
+ *
+ * If the crypto operation succeeded, zero is returned and the values
+ * written in the cipher_status and auth_status fields of the result
+ * structure have undefined values.
+ *
+ * If the crypto operation failed, -1 is returned and the cipher_status
+ * and auth_status fields of the result structure indicate the reason for
+ * the failure.
+ *
+ * The subtype of the passed packet must be ODP_EVENT_PACKET_CRYPTO,
+ * otherwise the result of the call is undefined.
  *
  * @param         packet  A crypto processed packet (ODP_EVENT_PACKET_CRYPTO)
- * @param[out]    result  Pointer to operation result for output
+ * @param[out]    result  Pointer to operation result for output or NULL
  *
- * @retval  0     On success
- * @retval <0     On failure
+ * @retval   0    Crypto operation succeeded
+ * @retval  -1    Crypto operation failed
+ * @retval <-1    Failed to get crypto operation status of the packet
  */
 int odp_crypto_result(odp_crypto_packet_result_t *result,
 		      odp_packet_t packet);