Re: [dpdk-dev] [RFC v2, 2/2] eventdev: add crypto adapter API header

["Gujjar, Abhinandan S" <abhinandan.gujjar@intel.com>]

A gentle remainder for review :)

-Abhinandan

> -----Original Message-----
> From: Gujjar, Abhinandan S
> Sent: Monday, January 15, 2018 4:24 PM
> To: jerin.jacob@caviumnetworks.com
> Cc: dev@dpdk.org; Vangati, Narender <narender.vangati@intel.com>; Gujjar,
> Abhinandan S <abhinandan.gujjar@intel.com>; Rao, Nikhil
> <nikhil.rao@intel.com>; Eads, Gage <gage.eads@intel.com>
> Subject: [RFC v2, 2/2] eventdev: add crypto adapter API header
> 
> Add crypto event adapter APIs to support packet transfer mechanism between
> cryptodev and event device.
> 
> Signed-off-by: Abhinandan Gujjar <abhinandan.gujjar@intel.com>
> Signed-off-by: Nikhil Rao <nikhil.rao@intel.com>
> Signed-off-by: Gage Eads <gage.eads@intel.com>
> ---
> Notes:
> 	V2:
> 	1. Updated type as ENQ-DEQ in rte_event_crypto_adapter_type
> 	2. Removed enum rte_event_crypto_conf_type
> 	3. Updated struct rte_event_crypto_metadata
> 	4. Removed struct rte_event_crypto_queue_pair_conf
> 	5. Updated rte_event_crypto_adapter_queue_pair_add() API
> 
>  lib/librte_eventdev/Makefile                   |   1 +
>  lib/librte_eventdev/rte_event_crypto_adapter.h | 452
> +++++++++++++++++++++++++
>  2 files changed, 453 insertions(+)
>  create mode 100644 lib/librte_eventdev/rte_event_crypto_adapter.h
> 
> diff --git a/lib/librte_eventdev/Makefile b/lib/librte_eventdev/Makefile index
> 7fd78c7..a5a6214 100644
> --- a/lib/librte_eventdev/Makefile
> +++ b/lib/librte_eventdev/Makefile
> @@ -27,6 +27,7 @@ SYMLINK-y-include += rte_eventdev_pmd_pci.h  SYMLINK-
> y-include += rte_eventdev_pmd_vdev.h  SYMLINK-y-include += rte_event_ring.h
> SYMLINK-y-include += rte_event_eth_rx_adapter.h
> +SYMLINK-y-include += rte_event_crypto_adapter.h
> 
>  # versioning export map
>  EXPORT_MAP := rte_eventdev_version.map
> diff --git a/lib/librte_eventdev/rte_event_crypto_adapter.h
> b/lib/librte_eventdev/rte_event_crypto_adapter.h
> new file mode 100644
> index 0000000..e90b57e
> --- /dev/null
> +++ b/lib/librte_eventdev/rte_event_crypto_adapter.h
> @@ -0,0 +1,452 @@
> +/*
> + *   Copyright(c) 2018 Intel Corporation. All rights reserved.
> + *   All rights reserved.
> + *
> + *   Redistribution and use in source and binary forms, with or without
> + *   modification, are permitted provided that the following conditions
> + *   are met:
> + *
> + *     * Redistributions of source code must retain the above copyright
> + *       notice, this list of conditions and the following disclaimer.
> + *     * Redistributions in binary form must reproduce the above copyright
> + *       notice, this list of conditions and the following disclaimer in
> + *       the documentation and/or other materials provided with the
> + *       distribution.
> + *     * Neither the name of Intel Corporation nor the names of its
> + *       contributors may be used to endorse or promote products derived
> + *       from this software without specific prior written permission.
> + *
> + *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
> CONTRIBUTORS
> + *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
> + *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
> FITNESS FOR
> + *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
> COPYRIGHT
> + *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
> INCIDENTAL,
> + *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
> NOT
> + *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
> OF USE,
> + *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
> ON ANY
> + *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
> TORT
> + *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
> THE USE
> + *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
> DAMAGE.
> + */
> +
> +#ifndef _RTE_EVENT_CRYPTO_ADAPTER_
> +#define _RTE_EVENT_CRYPTO_ADAPTER_
> +
> +/**
> + * This adapter adds support to enqueue crypto completions to event device.
> + * The packet flow from cryptodev to the event device can be
> +accomplished
> + * using both SW and HW based transfer mechanisms.
> + * The adapter uses a EAL service core function for SW based packet
> +transfer
> + * and uses the eventdev PMD functions to configure HW based packet
> +transfer
> + * between the cryptodev and the event device.
> + *
> + * In the case of SW based transfers, application can choose to submit
> +a
> + * crypto operation directly to cryptodev or send it  to the cryptodev
> + * adapter via eventdev, the cryptodev adapter then submits the crypto
> + * operation to the crypto device. The first mode is known as the
> + * dequeue only (DEQ) mode  and the second as the enqueue - dequeue
> + * (ENQ_DEQ) mode. The choice of mode can be specified when creating
> + * the adapter.
> + * In the latter choice, the cryptodev adapter is able to use
> + * RTE_OP_FORWARD as the event dev enqueue type, this has a performance
> + * advantage in "closed system" eventdevs like the eventdev SW PMD and
> + * also, the event cannot be dropped.
> + *
> + * In the ENQ_DEQ mode the application needs to specify the cryptodev
> +ID
> + * and queue pair ID (request information) in addition to the event
> + * information (response information) needed to enqueue an event after
> + * the crypto operation has completed. The request and response
> +information
> + * are specified in the rte_crypto_op private_data. In the DEQ mode the
> + * the application is required to provide only the response information.
> + *
> + * In the ENQ_DEQ mode, application sends crypto operations as events
> +to
> + * the adapter which dequeues events and programs cryptodev operations.
> + * The adapter then dequeues crypto completions from cryptodev and
> + * enqueue events to the event device.
> + *
> + * In the case of HW based transfers, the cryptodev PMD callback
> +invoked
> + * from rte_cryptodev_enqueue_burst() uses the response information to
> + * setup the event for the cryptodev completion.
> + *
> + * The event crypto adapter provides common APIs to configure the
> +packet flow
> + * from the cryptodev to event devices across both SW and HW based
> transfers.
> + * The crypto event adapter's functions are:
> + *  - rte_event_crypto_adapter_create_ext()
> + *  - rte_event_crypto_adapter_create()
> + *  - rte_event_crypto_adapter_free()
> + *  - rte_event_crypto_adapter_queue_pair_add()
> + *  - rte_event_crypto_adapter_queue_pair_del()
> + *  - rte_event_crypto_adapter_start()
> + *  - rte_event_crypto_adapter_stop()
> + *  - rte_event_crypto_adapter_stats_get()
> + *  - rte_event_crypto_adapter_stats_reset()
> +
> + * The applicaton creates an instance using
> + rte_event_crypto_adapter_create()
> + * or rte_event_crypto_adapter_create_ext().
> + *
> + * Cryptodev queue pair addition/deletion is done
> + * using the rte_event_crypto_adapter_queue_pair_xxx() APIs.
> + *
> + * The SW adapter or HW PMD uses rte_crypto_op::private_data_type to
> + decide
> + * whether request/response data is located in the crypto
> + session/crypto
> + * security session or at an offset in the rte_crypto_op.
> + * rte_crypto_op::private_data_offset is used to locate the
> + request/response
> + * in the rte_crypto_op. If the rte_crypto_op::private_data_type
> + * indicates that the data is in the crypto session/crypto security
> + session
> + * then the rte_crypto_op::sess_type is used to decide whether the
> + private
> + * data is in the session or security session.
> + *
> + * For session-less it is mandatory to place the request/response data
> + with
> + * the rte_crypto_op where as with crypto session/security session it
> + can be
> + * placed with the rte_crypto_op or in the session/security session.
> + */
> +
> +#ifdef __cplusplus
> +extern "C" {
> +#endif
> +
> +#include <stdint.h>
> +#include <rte_service.h>
> +
> +#include "rte_eventdev.h"
> +
> +#define RTE_EVENT_CRYPTO_ADAPTER_MAX_INSTANCE 32
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this enum may change without prior notice
> + *
> + * Crypto event adapter type
> + */
> +enum rte_event_crypto_adapter_type {
> +	RTE_EVENT_CRYPTO_ADAPTER_DEQ_ONLY = 1,
> +	/**< Start only dequeue part of crypto adapter.
> +	 * Packets dequeued from cryptodev are enqueued to eventdev
> +	 * as new events and events will be treated as RTE_EVENT_OP_NEW. */
> +	RTE_EVENT_CRYPTO_ADAPTER_ENQ_DEQ,
> +	/**< Start both enqueue & dequeue part of crypto adapter.
> +	 * Packet's event context will be retained and
> +	 * event will be treated as RTE_EVENT_OP_FORWARD. */ };
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this structure may change without prior notice
> + *
> + * Crypto event request structure will be fill by application to
> + * provide event request information to the adapter.
> + */
> +struct rte_event_crypto_request {
> +	uint8_t resv[8];
> +	/**< Overlaps with first 8 bytes of struct rte_event
> +	 * that encode the response event information
> +	 */
> +	uint16_t cdev_id;
> +	/**< cryptodev ID to be used */
> +	uint16_t queue_pair_id;
> +	/**< cryptodev queue pair ID to be used */
> +	uint32_t resv1;
> +	/**< Reserved bits */
> +};
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this structure may change without prior notice
> + *
> + * Crypto event metadata structure will be filled by application
> + * to provide crypto request and event response information.
> + *
> + * If crypto events are enqueued using a HW mechanism, the cryptodev
> + * PMD will use the event response information to set up the event
> + * that is enqueued back to eventdev after completion of the crypto
> + * operation. If the transfer is done by SW, it will be used by the
> + * adapter.
> + */
> +union rte_event_crypto_metadata {
> +	struct rte_event_crypto_request request_info;
> +	struct rte_event response_info;
> +};
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this structure may change without prior notice
> + *
> + * Adapter configuration structure that the adapter configuration
> +callback
> + * function is expected to fill out
> + * @see rte_event_crypto_adapter_conf_cb  */ struct
> +rte_event_crypto_adapter_conf {
> +	uint8_t event_port_id;
> +	/**< Event port identifier, the adapter enqueues mbuf events to this
> +	 * port.
> +	 */
> +	uint32_t max_nb;
> +	/**< The adapter can return early if it has processed at least
> +	 * max_nb crypto ops. This isn't treated as a requirement; batching may
> +	 * cause the adapter to process more than max_nb crypto ops.
> +	 */
> +};
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice
> + *
> + * Function type used for adapter configuration callback. The callback
> +is
> + * used to fill in members of the struct rte_event_crypto_adapter_conf,
> +this
> + * callback is invoked when creating a SW service for packet transfer
> +from
> + * cryptodev queue pair to the event device. The SW service is created
> +within
> + * the rte_event_crypto_adapter_queue_add() function if SW based packet
> + * transfers from cryptodev queue pair to the event device are required.
> + *
> + * @param id
> + *  Adapter identifier.
> + *
> + * @param dev_id
> + *  Crypto device identifier.
> + *
> + * @param [out] conf
> + *  Structure that needs to be populated by this callback.
> + *
> + * @param arg
> + *  Argument to the callback. This is the same as the conf_arg passed
> +to the
> + *  rte_event_crypto_adapter_create_ext().
> + */
> +typedef int (*rte_event_crypto_adapter_conf_cb) (uint8_t id, uint8_t cdev_id,
> +			struct rte_event_crypto_adapter_conf *conf,
> +			void *arg);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this structure may change without prior notice
> + *
> + * A structure used to retrieve statistics for an event crypto adapter
> + * instance.
> + */
> +
> +struct rte_event_crypto_adapter_stats {
> +	uint64_t event_poll_count;
> +	/**< Event port poll count */
> +	uint64_t event_dequeue_count;
> +	/**< Event dequeue count */
> +	uint64_t crypto_enq_fail;
> +	/**< Cryptodev enqueue failed count */
> +	uint64_t crypto_deq_count;
> +	/**< Cryptodev dequeue count */
> +	uint64_t event_enq_retry_count;
> +	/**< Event enqueue retry count */
> +	uint64_t event_enq_fail_count;
> +	/**< Event enqueue fail count */
> +};
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice
> + *
> + * Create a new event crypto adapter with the specified identifier.
> + *
> + * @param id
> + *  Adapter identifier.
> + *
> + * @param cdev_id
> + *  Crypto device identifier.
> + *
> + * @param conf_cb
> + *  Callback function that fills in members of a
> + *  struct rte_event_crypto_adapter_conf struct passed into
> + *  it.
> + *
> + * @param conf_arg
> + *  Argument that is passed to the conf_cb function.
> + *
> + * @return
> + *   - 0: Success
> + *   - <0: Error code on failure
> + */
> +int rte_event_crypto_adapter_create_ext(uint8_t id, uint8_t cdev_id,
> +				rte_event_crypto_adapter_conf_cb conf_cb,
> +				void *conf_arg);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice
> + *
> + * Create a new event crypto adapter with the specified identifier.
> + * This function uses an internal configuration function that creates
> +an event
> + * port. This default function reconfigures the event device with an
> + * additional event port and setups up the event port using the
> +port_config
> + * parameter passed into this function. In case the application needs
> +more
> + * control in configuration of the service, it should use the
> + * rte_event_crypto_adapter_create_ext() version.
> + *
> + * @param id
> + *  Adapter identifier.
> + *
> + * @param cdev_id
> + *  Crypto device identifier.
> + *
> + * @param port_config
> + *  Argument of type *rte_event_port_conf* that is passed to the
> +conf_cb
> + *  function.
> + *
> + * @return
> + *   - 0: Success
> + *   - <0: Error code on failure
> + */
> +int rte_event_crypto_adapter_create(uint8_t id, uint8_t cdev_id,
> +				    struct rte_event_port_conf *port_config);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice
> + *
> + * Free an event crypto adapter
> + *
> + * @param id
> + *  Adapter identifier.
> + *
> + * @return
> + *   - 0: Success
> + *   - <0: Error code on failure, If the adapter still has queue pairs
> + *      added to it, the function returns -EBUSY.
> + */
> +int rte_event_crypto_adapter_free(uint8_t id);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice
> + *
> + * Add a queue pair to an event crypto adapter.
> + *
> + * @param id
> + *  Adapter identifier.
> + *
> + * @param cdev_id
> + *  Cryptodev identifier.
> + *
> + * @param queue_pair_id
> + *  Cryptodev queue pair identifier. If queue_pair_id is set -1,
> + *  adapter adds all the pre configured queue pairs to the instance.
> + *
> + *
> + * @return
> + *  - 0: Success, Receive queue pair added correctly.
> + *  - <0: Error code on failure.
> + */
> +int rte_event_crypto_adapter_queue_pair_add(uint8_t id,
> +			uint8_t cdev_id,
> +			int32_t queue_pair_id);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice
> + *
> + * Delete a queue pair from an event crypto adapter.
> + *
> + * @param id
> + *  Adapter identifier.
> + *
> + * @param cdev_id
> + *  Cryptodev identifier.
> + *
> + * @param queue_pair_id
> + *  Cryptodev queue pair identifier.
> + *
> + * @return
> + *  - 0: Success, queue pair deleted successfully.
> + *  - <0: Error code on failure.
> + */
> +int rte_event_crypto_adapter_queue_pair_del(uint8_t id, uint8_t cdev_id,
> +					    int32_t queue_pair_id);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice
> + *
> + * Start event crypto adapter
> + *
> + * @param id
> + *  Adapter identifier.
> + *
> + * @param type
> + *  Flag to indicate to start dequeue only or both enqueue & dequeue.
> + *
> + * @return
> + *  - 0: Success, Adapter started successfully.
> + *  - <0: Error code on failure.
> + */
> +int rte_event_crypto_adapter_start(uint8_t id,
> +				   enum rte_event_crypto_adapter_type type);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice
> + *
> + * Stop event crypto adapter
> + *
> + * @param id
> + *  Adapter identifier.
> + *
> + * @return
> + *  - 0: Success, Adapter stopped successfully.
> + *  - <0: Error code on failure.
> + */
> +int rte_event_crypto_adapter_stop(uint8_t id);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice
> + *
> + * Retrieve statistics for an adapter
> + *
> + * @param id
> + *  Adapter identifier.
> + *
> + * @param [out] stats
> + *  A pointer to structure used to retrieve statistics for an adapter.
> + *
> + * @return
> + *  - 0: Success, retrieved successfully.
> + *  - <0: Error code on failure.
> + */
> +int rte_event_crypto_adapter_stats_get(uint8_t id,
> +				struct rte_event_crypto_adapter_stats *stats);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice
> + *
> + * Reset statistics for an adapter.
> + *
> + * @param id
> + *  Adapter identifier.
> + *
> + * @return
> + *  - 0: Success, statistics reset successfully.
> + *  - <0: Error code on failure.
> + */
> +int rte_event_crypto_adapter_stats_reset(uint8_t id);
> +
> +/**
> + * @warning
> + * @b EXPERIMENTAL: this API may change without prior notice
> + *
> + * Retrieve the service ID of an adapter. If the adapter doesn't use
> + * a rte_service function, this function returns -ESRCH.
> + *
> + * @param id
> + *  Adapter identifier.
> + *
> + * @param [out] service_id
> + *  A pointer to a uint32_t, to be filled in with the service id.
> + *
> + * @return
> + *  - 0: Success
> + *  - <0: Error code on failure, if the adapter doesn't use a
> +rte_service
> + * function, this function returns -ESRCH.
> + */
> +int rte_event_crypto_adapter_service_id_get(uint8_t id, uint32_t
> +*service_id);
> +
> +#ifdef __cplusplus
> +}
> +#endif
> +#endif	/* _RTE_EVENT_CRYPTO_ADAPTER_ */
> --
> 1.9.1