[v4] cryptodev: support multiple cipher data-units

From: Matan Azrad <matan@nvidia.com>

In cryptography, a block cipher is a deterministic algorithm operating
on fixed-length groups of bits, called blocks.

A block cipher consists of two paired algorithms, one for encryption
and the other for decryption. Both algorithms accept two inputs:
an input block of size n bits and a key of size k bits; and both yield
an n-bit output block. The decryption algorithm is defined to be the
inverse function of the encryption.

For AES standard the block size is 16 bytes.
For AES in XTS mode, the data to be encrypted\decrypted does not have to
be multiple of 16B size, the unit of data is called data-unit.
The data-unit size can be any size in range [16B, 2^24B], so, in this
case, a data stream is divided into N amount of equal data-units and
must be encrypted\decrypted in the same data-unit resolution.

For ABI compatibility reason, the size is limited to 64K (16-bit field).
The new field dataunit_len is inserted in a struct padding hole,
which is only 2 bytes long in 32-bit build.
It could be moved and extended later during an ABI-breakage window.

The current cryptodev API doesn't allow the user to select a specific
data-unit length supported by the devices.
In addition, there is no definition how the IV is detected per data-unit
when single operation includes more than one data-unit.

That causes applications to use single operation per data-unit even though
all the data is continuous in memory what reduces datapath performance.

Add a new feature flag to support multiple data-unit sizes, called
RTE_CRYPTODEV_FF_CIPHER_MULTIPLE_DATA_UNITS.
Add a new field in cipher capability, called dataunit_set,
where the devices can report the range of the supported data-unit sizes.
Add a new cipher transformation field, called dataunit_len, where the user
can select the data-unit length for all the operations.

All the new fields do not change the size of their structures,
by filling some struct padding holes.
They are added as exceptions in the ABI check file libabigail.abignore.

Using a bitmap to report the supported data-unit sizes capability allows
the devices to report a range simply as same as the user to read it
simply. also, thus sizes are usually common and probably will be shared
among different devices.

Signed-off-by: Matan Azrad <matan@nvidia.com>
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
v1:
- Use data-unit term instead of block.
- Update cipher length description in OP.
- Improve descriptions on xform and capability.
- Improve commit log.

v2:
- Fix typo: MULITPLE->MULTIPLE.
- Remain only planned supported sizes for data-unit capability.

v3:
- Improve some comments.
- Fix ABI breakage.

v4:
- Remove RTE_CRYPTO_CIPHER_DATA_UNIT_LEN_1M_BYTES
- Fix dataunit_len placement in padding hole
---
 devtools/libabigail.abignore               | 12 ++++++++-
 doc/guides/cryptodevs/features/default.ini |  1 +
 doc/guides/cryptodevs/overview.rst         |  3 +++
 doc/guides/rel_notes/release_21_05.rst     |  6 +++++
 lib/librte_cryptodev/rte_crypto_sym.h      | 29 ++++++++++++++++++++--
 lib/librte_cryptodev/rte_cryptodev.c       |  2 ++
 lib/librte_cryptodev/rte_cryptodev.h       | 15 +++++++++++
 7 files changed, 65 insertions(+), 3 deletions(-)

Hi Thomas,

> +	RTE_STD_C11
> +	union { /* temporary anonymous union for ABI compatibility */
> +
>  	struct {
>  		const uint8_t *data;	/**< pointer to key data */
>  		uint16_t length;	/**< key length in bytes */
> @@ -222,6 +225,27 @@ struct rte_crypto_cipher_xform {
>  	 *  - Each key can be either 128 bits (16 bytes) or 256 bits (32 bytes).
>  	 *  - Both keys must have the same size.
>  	 **/
> +
> +	RTE_STD_C11
> +	struct { /* temporary anonymous struct for ABI compatibility */
> +		const uint8_t *_key_data; /* reserved for key.data union */
> +		uint16_t _key_length;     /* reserved for key.length union */
> +		/* next field can fill the padding hole */
> +
> +	uint16_t dataunit_len;
> +	/**< When RTE_CRYPTODEV_FF_CIPHER_MULTIPLE_DATA_UNITS is
> enabled,
> +	 * this is the data-unit length of the algorithm,
> +	 * otherwise or when the value is 0, use the operation length.
> +	 * The value should be in the range defined by the dataunit_set field
> +	 * in the cipher capability.
> +	 *
> +	 * - For AES-XTS it is the size of data-unit, from IEEE Std 1619-2007.
> +	 * For-each data-unit in the operation, the tweak (IV) value is
> +	 * assigned consecutively starting from the operation assigned IV.
> +	 */
> +
> +	}; }; /* temporary struct nested in union for ABI compatibility */
> +
Can we add a deprecation notice also in this patch to remove these temporary
Struct and union, so that we remember to remove them in 21.11

> +/**
> + * Data-unit supported lengths of cipher algorithms.
> + * A bit can represent any set of data-unit sizes
> + * (single size, multiple size, range, etc).
> + */
> +#define RTE_CRYPTO_CIPHER_DATA_UNIT_LEN_512_BYTES	(1 << 0)
> +#define RTE_CRYPTO_CIPHER_DATA_UNIT_LEN_4096_BYTES	(1 << 1)
> +
>  /**
>   * Symmetric Crypto Capability
>   */
> @@ -127,6 +135,11 @@ struct rte_cryptodev_symmetric_capability {
>  			/**< cipher key size range */
>  			struct rte_crypto_param_range iv_size;
>  			/**< Initialisation vector data size range */
> +			uint32_t dataunit_set;
> +			/**<
> +			 * A bitmap for a set of the supported data-unit
> lengths.

Add reference to the newly created macros here

> +			 * 0 for any length defined in the algorithm standard.
> +			 */

14/04/2021 20:37, Akhil Goyal:
> Hi Thomas,
> 
> > +	RTE_STD_C11
> > +	union { /* temporary anonymous union for ABI compatibility */
> > +
> >  	struct {
> >  		const uint8_t *data;	/**< pointer to key data */
> >  		uint16_t length;	/**< key length in bytes */
> > @@ -222,6 +225,27 @@ struct rte_crypto_cipher_xform {
> >  	 *  - Each key can be either 128 bits (16 bytes) or 256 bits (32 bytes).
> >  	 *  - Both keys must have the same size.
> >  	 **/
> > +
> > +	RTE_STD_C11
> > +	struct { /* temporary anonymous struct for ABI compatibility */
> > +		const uint8_t *_key_data; /* reserved for key.data union */
> > +		uint16_t _key_length;     /* reserved for key.length union */
> > +		/* next field can fill the padding hole */
> > +
> > +	uint16_t dataunit_len;
> > +	/**< When RTE_CRYPTODEV_FF_CIPHER_MULTIPLE_DATA_UNITS is
> > enabled,
> > +	 * this is the data-unit length of the algorithm,
> > +	 * otherwise or when the value is 0, use the operation length.
> > +	 * The value should be in the range defined by the dataunit_set field
> > +	 * in the cipher capability.
> > +	 *
> > +	 * - For AES-XTS it is the size of data-unit, from IEEE Std 1619-2007.
> > +	 * For-each data-unit in the operation, the tweak (IV) value is
> > +	 * assigned consecutively starting from the operation assigned IV.
> > +	 */
> > +
> > +	}; }; /* temporary struct nested in union for ABI compatibility */
> > +
> Can we add a deprecation notice also in this patch to remove these temporary
> Struct and union, so that we remember to remove them in 21.11

I thought about it, but a deprecation notice may involve
new design considerations and requires 3 approvals.
I think it is better to send it separately.

> > @@ -127,6 +135,11 @@ struct rte_cryptodev_symmetric_capability {
> >  			/**< cipher key size range */
> >  			struct rte_crypto_param_range iv_size;
> >  			/**< Initialisation vector data size range */
> > +			uint32_t dataunit_set;
> > +			/**<
> > +			 * A bitmap for a set of the supported data-unit
> > lengths.
> 
> Add reference to the newly created macros here
> 
> > +			 * 0 for any length defined in the algorithm standard.
> > +			 */

Yes, I've seen this miss after sending.
I'll reword like this:
  * Supported data-unit lengths:
  * RTE_CRYPTO_CIPHER_DATA_UNIT_LEN_* bits
  * or 0 for lengths defined in the algorithm standard.

> 
> 14/04/2021 20:37, Akhil Goyal:
> > Hi Thomas,
> >
> > > +	RTE_STD_C11
> > > +	union { /* temporary anonymous union for ABI compatibility */
> > > +
> > >  	struct {
> > >  		const uint8_t *data;	/**< pointer to key data */
> > >  		uint16_t length;	/**< key length in bytes */
> > > @@ -222,6 +225,27 @@ struct rte_crypto_cipher_xform {
> > >  	 *  - Each key can be either 128 bits (16 bytes) or 256 bits (32 bytes).
> > >  	 *  - Both keys must have the same size.
> > >  	 **/
> > > +
> > > +	RTE_STD_C11
> > > +	struct { /* temporary anonymous struct for ABI compatibility */
> > > +		const uint8_t *_key_data; /* reserved for key.data union */
> > > +		uint16_t _key_length;     /* reserved for key.length union */
> > > +		/* next field can fill the padding hole */
> > > +
> > > +	uint16_t dataunit_len;
> > > +	/**< When RTE_CRYPTODEV_FF_CIPHER_MULTIPLE_DATA_UNITS is
> > > enabled,
> > > +	 * this is the data-unit length of the algorithm,
> > > +	 * otherwise or when the value is 0, use the operation length.
> > > +	 * The value should be in the range defined by the dataunit_set field
> > > +	 * in the cipher capability.
> > > +	 *
> > > +	 * - For AES-XTS it is the size of data-unit, from IEEE Std 1619-2007.
> > > +	 * For-each data-unit in the operation, the tweak (IV) value is
> > > +	 * assigned consecutively starting from the operation assigned IV.
> > > +	 */
> > > +
> > > +	}; }; /* temporary struct nested in union for ABI compatibility */
> > > +
> > Can we add a deprecation notice also in this patch to remove these
> temporary
> > Struct and union, so that we remember to remove them in 21.11
> 
> I thought about it, but a deprecation notice may involve
> new design considerations and requires 3 approvals.
> I think it is better to send it separately.
In that case you can send it as a separate patch now only.
Just wanted to make sure that it is not forgotten.

> 
> > > @@ -127,6 +135,11 @@ struct rte_cryptodev_symmetric_capability {
> > >  			/**< cipher key size range */
> > >  			struct rte_crypto_param_range iv_size;
> > >  			/**< Initialisation vector data size range */
> > > +			uint32_t dataunit_set;
> > > +			/**<
> > > +			 * A bitmap for a set of the supported data-unit
> > > lengths.
> >
> > Add reference to the newly created macros here
> >
> > > +			 * 0 for any length defined in the algorithm standard.
> > > +			 */
> 
> Yes, I've seen this miss after sending.
> I'll reword like this:
>   * Supported data-unit lengths:
>   * RTE_CRYPTO_CIPHER_DATA_UNIT_LEN_* bits
>   * or 0 for lengths defined in the algorithm standard.

OK

14/04/2021 21:43, Akhil Goyal:
> > 14/04/2021 20:37, Akhil Goyal:
> > > Hi Thomas,
> > >
> > > > +	RTE_STD_C11
> > > > +	union { /* temporary anonymous union for ABI compatibility */
> > > > +
> > > >  	struct {
> > > >  		const uint8_t *data;	/**< pointer to key data */
> > > >  		uint16_t length;	/**< key length in bytes */
> > > > @@ -222,6 +225,27 @@ struct rte_crypto_cipher_xform {
> > > >  	 *  - Each key can be either 128 bits (16 bytes) or 256 bits (32 bytes).
> > > >  	 *  - Both keys must have the same size.
> > > >  	 **/
> > > > +
> > > > +	RTE_STD_C11
> > > > +	struct { /* temporary anonymous struct for ABI compatibility */
> > > > +		const uint8_t *_key_data; /* reserved for key.data union */
> > > > +		uint16_t _key_length;     /* reserved for key.length union */
> > > > +		/* next field can fill the padding hole */
> > > > +
> > > > +	uint16_t dataunit_len;
> > > > +	/**< When RTE_CRYPTODEV_FF_CIPHER_MULTIPLE_DATA_UNITS is
> > > > enabled,
> > > > +	 * this is the data-unit length of the algorithm,
> > > > +	 * otherwise or when the value is 0, use the operation length.
> > > > +	 * The value should be in the range defined by the dataunit_set field
> > > > +	 * in the cipher capability.
> > > > +	 *
> > > > +	 * - For AES-XTS it is the size of data-unit, from IEEE Std 1619-2007.
> > > > +	 * For-each data-unit in the operation, the tweak (IV) value is
> > > > +	 * assigned consecutively starting from the operation assigned IV.
> > > > +	 */
> > > > +
> > > > +	}; }; /* temporary struct nested in union for ABI compatibility */
> > > > +
> > > Can we add a deprecation notice also in this patch to remove these
> > temporary
> > > Struct and union, so that we remember to remove them in 21.11
> > 
> > I thought about it, but a deprecation notice may involve
> > new design considerations and requires 3 approvals.
> > I think it is better to send it separately.
> 
> In that case you can send it as a separate patch now only.
> Just wanted to make sure that it is not forgotten.

Yes, sent:
https://patches.dpdk.org/project/dpdk/patch/20210414201544.1063413-1-thomas@monjalon.net/