Re: [v2, 6/6] doc: add event crypto adapter documentation

[Jerin Jacob <jerin.jacob@caviumnetworks.com>]

-----Original Message-----
> Date: Tue, 24 Apr 2018 18:13:27 +0530
> From: Abhinandan Gujjar <abhinandan.gujjar@intel.com>
> To: jerin.jacob@caviumnetworks.com, hemant.agrawal@nxp.com,
>  akhil.goyal@nxp.com, dev@dpdk.org
> CC: narender.vangati@intel.com, abhinandan.gujjar@intel.com,
>  nikhil.rao@intel.com, gage.eads@intel.com
> Subject: [v2,6/6] doc: add event crypto adapter documentation
> X-Mailer: git-send-email 1.9.1
> 
> Add entries in the programmer's guide, API index, maintainer's file
> and release notes for the event crypto adapter.
> 
> Signed-off-by: Abhinandan Gujjar <abhinandan.gujjar@intel.com>
> ---
> +
> +The packet flow from cryptodev to the event device can be accomplished
> +using both SW and HW based transfer mechanisms.
> +The Adapter queries an eventdev PMD to determine which mechanism to be used.
> +The adapter uses an 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.
> +
> +Crypto adapter uses a new event type called ``RTE_EVENT_TYPE_CRYPTODEV``
> +to indicate the event source.
> +

I think, we can add diagrams used in rte_event_crypto_adapter.h with
sequence number in SVG format here to make it easier to understand for the end user.


> +API Overview
> +------------
> +
> +This section has a brief introduction to the event crypto adapter APIs.
> +The application is expected to create an adapter which is associated with
> +a single eventdev, then add cryptodev and queue pair to the adapter instance.
> +
> +Adapter can be started in ``RTE_EVENT_CRYPTO_ADAPTER_DEQ_ONLY`` or
> +``RTE_EVENT_CRYPTO_ADAPTER_ENQ_DEQ`` mode.
> +In first mode, application will submit a crypto operation directly to cryptodev.
> +In the second mode, application will send a crypto ops to cryptodev adapter
> +via eventdev. The cryptodev adapter then submits the crypto operation to the
> +crypto device.
> +
> +Create an adapter instance
> +--------------------------
> +
> +An adapter instance is created using ``rte_event_crypto_adapter_create()``. This
> +function is called with event device to be associated with the adapter and port
> +configuration for the adapter to setup an event port(if the adapter needs to use
> +a service function).
> +
> +.. code-block:: c
> +
> +        int err;
> +        uint8_t dev_id, id;
> +        struct rte_event_dev_info dev_info;
> +        struct rte_event_port_conf conf;
> +	enum rte_event_crypto_adapter_mode mode;
> +
> +        err = rte_event_dev_info_get(id, &dev_info);
> +
> +        conf.new_event_threshold = dev_info.max_num_events;
> +        conf.dequeue_depth = dev_info.max_event_port_dequeue_depth;
> +        conf.enqueue_depth = dev_info.max_event_port_enqueue_depth;
> +	mode = RTE_EVENT_CRYPTO_ADAPTER_ENQ_DEQ;
> +        err = rte_event_crypto_adapter_create(id, dev_id, &conf, mode);
> +
> +If the application desires to have finer control of eventdev port allocation
> +and setup, it can use the ``rte_event_crypto_adapter_create_ext()`` function.
> +The ``rte_event_crypto_adapter_create_ext()`` function is passed as a callback
> +function. The callback function is invoked if the adapter needs to use a
> +service function and needs to create an event port for it. The callback is
> +expected to fill the ``struct rte_event_crypto_adapter_conf`` structure
> +passed to it.
> +
> +For ENQ-DEQ mode, the event port created by adapter can be retrived using

s/retrived/retrieved ?

> +``rte_event_crypto_adapter_event_port_get()`` API.
> +Application can use this event port to link with event queue on which it
> +enqueue events towards the crypto adapter.
> +
> +.. code-block:: c
> +
> +	uint8_t id, evdev, crypto_ev_port_id, app_qid;
> +	struct rte_event ev;
> +	int ret;
> +
> +	ret = rte_event_crypto_adapter_event_port_get(id, &crypto_ev_port_id);
> +	ret = rte_event_queue_setup(evdev, app_qid, NULL);
> +	ret = rte_event_port_link(evdev, crypto_ev_port_id, &app_qid, NULL, 1);
> +
> +	/* Fill in event info and update event_ptr with rte_crypto_op */
> +	memset(&ev, 0, sizeof(ev));
> +	ev.queue_id = app_qid;
> +	.
> +	.
> +	ev.event_ptr = op;
> +	ret = rte_event_enqueue_burst(evdev, app_ev_port_id, ev, nb_events);
> +
> +
> +Adding queue pair to the adapter instance
> +-----------------------------------------
> +
> +Cryptodev device id and queue pair are created using cryptodev APIs.
> +Refer '<http://dpdk.org/doc/guides/prog_guide/cryptodev_lib.html>`_.
> +
> +.. code-block:: c
> +
> +	struct rte_cryptodev_config conf;
> +	struct rte_cryptodev_qp_conf qp_conf;
> +	uint8_t cdev_id = 0;
> +	uint16_t qp_id = 0;
> +
> +	rte_cryptodev_configure(cdev_id, &conf);
> +	rte_cryptodev_queue_pair_setup(cdev_id, qp_id, &qp_conf);
> +
> +These cryptodev id and queue pair are added to the instance using the
> +``rte_event_crypto_adapter_queue_pair_add()`` function.
> +The same is removed using ``rte_event_crypto_adapter_queue_pair_del()``.
> +
> +.. code-block:: c
> +
> +	struct rte_event_crypto_queue_pair_conf conf;
> +
> +	rte_event_crypto_adapter_queue_pair_add(id, cdev_id, qp_id, &conf);
> +
> +
> +Querying adapter capabilities
> +-----------------------------
> +
> +The ``rte_event_crypto_adapter_caps_get()`` function allows
> +the application to query the adapter capabilities for an eventdev and cryptodev
> +combination. This API provides whether cryptodev and eventdev are connected using
> +internal HW port or not.
> +
> +.. code-block:: c
> +
> +        rte_event_crypto_adapter_caps_get(dev_id, cdev_id, &cap);
> +
> +
> +Configure the service function
> +------------------------------
> +
> +If the adapter uses a service function, the application is required to assign
> +a service core to the service function as show below.
> +
> +.. code-block:: c
> +
> +        uint32_t service_id;
> +
> +        if (rte_event_crypto_adapter_service_id_get(id, &service_id) == 0)
> +                rte_service_map_lcore_set(service_id, CORE_ID);
> +
> +
> +Set event request/response information
> +--------------------------------------
> +
> +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 ``struct rte_crypto_op`` private data or session's
> +private data.

I think, we can mention the use of rte_event_crypto_adapter_event_port_get()
API here.

> +
> +In the DEQ mode, the application is required to provide only the
> +response information.
> +
> +The SW adapter or HW PMD uses ``rte_crypto_op::sess_type`` to
> +decide whether request/response data is located in the crypto session/
> +crypto security session or at an offset in the ``struct rte_crypto_op``.
> +The ``rte_crypto_op::private_data_offset`` is used to locate the request/
> +response in the ``rte_crypto_op``.
> +
> +For crypto session, ``rte_cryptodev_sym_session_set_private_data()`` API
> +will be used to set request/response data. The same data will be obtained
> +by ``rte_cryptodev_sym_session_get_private_data()`` API.
> +
> +For security session, ``rte_security_session_set_private_data()`` API
> +will be used to set request/response data. The same data will be obtained
> +by ``rte_security_session_get_private_data()`` API.

I think, we need to talk about RTE_EVENT_CRYPTO_ADAPTER_CAP_SESSION_PRIVATE_DATA
capability here and have check in sample code/common code(please ignore
if the check is already present in common code)

> +
> +For session-less it is mandatory to place the request/response data with
> +the ``rte_crypto_op``.
> +
> +.. code-block:: c
> +
> +	union rte_event_crypto_metadata m_data;
> +	struct rte_event ev;
> +	struct rte_crypto_op *op;
> +
> +	/* Allocate & fill op structure */
> +	op = rte_crypto_op_alloc();
> +
> +	memset(&m_data, 0, sizeof(m_data));
> +	memset(&ev, 0, sizeof(ev));
> +	/* Fill event information and update event_ptr to rte_crypto_op */
> +	ev.event_ptr = op;
> +
> +	if (op->sess_type == RTE_CRYPTO_OP_WITH_SESSION) {
> +		/* Copy response information */
> +		rte_memcpy(&m_data.response_info, &ev, sizeof(ev));
> +		/* Copy request information */
> +		m_data.request_info.cdev_id = cdev_id;
> +		m_data.request_info.queue_pair_id = qp_id;
> +		/* Call set API to store private data information */
> +		rte_cryptodev_sym_session_set_private_data(
> +				op->sym->session,
> +				&m_data,
> +				sizeof(m_data));
> +	} if (op->sess_type == RTE_CRYPTO_OP_SESSIONLESS) {
> +		uint32_t len = IV_OFFSET + MAXIMUM_IV_LENGTH +
> +				(sizeof(struct rte_crypto_sym_xform) * 2);
> +		op->private_data_offset = len;
> +		/* Copy response information */
> +		rte_memcpy(&m_data.response_info, &ev, sizeof(ev));
> +		/* Copy request information */
> +		m_data.request_info.cdev_id = cdev_id;
> +		m_data.request_info.queue_pair_id = qp_id;
> +		/* Store private data information along with rte_crypto_op */
> +		rte_memcpy(op + len, &m_data, sizeof(m_data));
> +	}
> +