api: crypto: introduce a session parameter to control output packet handling

Introduce new "operation type" session parameter that controls how the
crypto operations interpret their parameters and handle the output packet.

- Legacy type is the default and provides backward compatibility.
- Basic type provides a slightly simplified interface

Other types can be introduced later.

In the basic operation type the pool session parameter must be set to
ODP_POOL_INVALID. This is to enable backward compatibility for a possible
future API change that would allow caller to optionally specify the pool
of the output packet instead of having ODP use the pool of the input
packet.

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

2 files changed, 69 insertions, 7 deletions

diff --git a/include/odp/api/spec/crypto.h b/include/odp/api/spec/crypto.h
index ee84cd537..674f476b0 100644
--- a/include/odp/api/spec/crypto.h
+++ b/include/odp/api/spec/crypto.h
@@ -156,6 +156,9 @@ void odp_crypto_compl_free(odp_crypto_compl_t completion_event);
  *
  * @deprecated Use odp_crypto_op() or odp_crypto_op_enq() instead.
  *
+ * This function may be called only for sessions configured with
+ * the ODP_CRYPTO_OP_TYPE_LEGACY operation type.
+ *
  * Performs the cryptographic operations specified during session creation
  * on the packet.  If the operation is performed synchronously, "posted"
  * will return FALSE and the result of the operation is immediately available.
@@ -275,10 +278,16 @@ int odp_crypto_result(odp_crypto_packet_result_t *result,
  * Crypto packet operation
  *
  * Performs the SYNC cryptographic operations specified during session creation
- * on the packets. Caller should initialize each element of pkt_out either with
- * the desired output packet handle or with ODP_PACKET_INVALID to make ODP
- * allocate a new packet from provided pool. All arrays should be of num_pkt
- * size.
+ * on the packets. All arrays should be of num_pkt size.
+ *
+ * Use of the pkt_out parameter depends on the configured crypto operation
+ * type as described below.
+ *
+ * ODP_CRYPTO_OP_TYPE_LEGACY:
+ *
+ * Caller should initialize each element of pkt_out either with the desired
+ * output packet handle or with ODP_PACKET_INVALID to make ODP allocate a new
+ * packet from provided pool.
  *
  * All packet data and metadata are copied from the input packet to the output
  * packet before the requested crypto operation is performed to the output
@@ -294,6 +303,19 @@ int odp_crypto_result(odp_crypto_packet_result_t *result,
  * is consumed but returned as the output packet (with possibly different
  * memory layout).
  *
+ * ODP_CRYPTO_OP_TYPE_BASIC:
+ *
+ * ODP allocates the output packet from the pool from which the input
+ * packet was allocated. The processed input packet is consumed. All
+ * packet data and metadata are copied from the input packet to the output
+ * packet before the requested crypto operation is applied to the output
+ * packet. Memory layout (including packet data pointers, head and tail room,
+ * segmentation) of the output packet may differ from that of the input
+ * packet.
+ *
+ * The value of pktout[n] is ignored as pktout[n] is used purely as an
+ * output parameter that returns the handle of the newly allocated packet.
+ *
  * @param         pkt_in   Packets to be processed
  * @param[in,out] pkt_out  Packet handle array for resulting packets
  * @param         param    Operation parameters array
@@ -314,6 +336,9 @@ int odp_crypto_op(const odp_packet_t pkt_in[],
  * creation on the packets. Behaves otherwise like odp_crypto_op() but
  * returns output packets through events.
  *
+ * All arrays should be of num_pkt size, except that pkt_out parameter
+ * is ignored when the crypto operation type is ODP_CRYPTO_OP_TYPE_BASIC.
+ *
  * @param pkt_in   Packets to be processed
  * @param pkt_out  Packet handle array for resulting packets
  * @param param    Operation parameters array
diff --git a/include/odp/api/spec/crypto_types.h b/include/odp/api/spec/crypto_types.h
index b581f451e..205bdb700 100644
--- a/include/odp/api/spec/crypto_types.h
+++ b/include/odp/api/spec/crypto_types.h
@@ -53,7 +53,7 @@ typedef enum {
 } odp_crypto_op_mode_t;
 
 /**
- * Crypto API operation type
+ * Crypto API operation
  */
 typedef enum {
 	/** Encrypt and/or compute authentication ICV */
@@ -510,6 +510,28 @@ typedef struct odp_crypto_key {
 } odp_crypto_key_t;
 
 /**
+ * Type of odp_crypto_op()/odp_crypto_op_enq() calls.
+ */
+typedef enum odp_crypto_op_type_t {
+	/**
+	 * Input packet data and metadata are copied in the output packet
+	 * and then processed. Output packet is allocated by the caller
+	 * or by ODP. odp_crypto_op(), odp_crypto_op_enq() and
+	 * odp_crypto_operation() can be used.
+	 *
+	 * This is the default value but will be deprecated in the future.
+	 */
+	ODP_CRYPTO_OP_TYPE_LEGACY,
+
+	/**
+	 * Input packet data and metadata are copied in the output packet
+	 * and then processed. Output packet is allocated by ODP.
+	 * odp_crypto_op() and odp_crypto_op_enq() can be used.
+	 */
+	ODP_CRYPTO_OP_TYPE_BASIC,
+} odp_crypto_op_type_t;
+
+/**
  * Crypto API session creation parameters
  */
 typedef struct odp_crypto_session_param_t {
@@ -519,6 +541,18 @@ typedef struct odp_crypto_session_param_t {
 	 */
 	odp_crypto_op_t op;
 
+	/** Crypto operation type
+	 *
+	 *  This field defines how the crypto operation functions are
+	 *  to be called and what they return. In particular, this field
+	 *  specifies the interpretation of the output packet parameter,
+	 *  how output packets are allocated and what data and metadata
+	 *  they contain.
+	 *
+	 *  The default value is ODP_CRYPTO_OP_TYPE_LEGACY.
+	 */
+	odp_crypto_op_type_t op_type;
+
 	/** Authenticate cipher vs. plain text
 	 *
 	 *  Controls ordering of authentication and cipher operations,
@@ -632,8 +666,11 @@ typedef struct odp_crypto_session_param_t {
 	/** Output pool
 	 *
 	 *  When the output packet is not specified during the call to
-	 *  crypto operation, the output packet will be allocated
-	 *  from this pool.
+	 *  crypto operation in the legacy operation type, the output
+	 *  packet will be allocated from this pool.
+	 *
+	 *  In ODP_CRYPTO_OP_TYPE_BASIC operation type this must be set to
+	 *  ODP_POOL_INVALID.
 	 */
 	odp_pool_t output_pool;