Re: [dpdk-dev] [PATCH] cryptodev: rename experimental private data APIs

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

Acked-by: Abhinandan Gujjar <abhinandan.gujjar@intel.com>


> -----Original Message-----
> From: Trahe, Fiona
> Sent: Friday, July 6, 2018 7:10 PM
> To: dev@dpdk.org
> Cc: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>; Trahe, Fiona
> <fiona.trahe@intel.com>; Gujjar, Abhinandan S <abhinandan.gujjar@intel.com>
> Subject: [PATCH] cryptodev: rename experimental private data APIs
> 
> The name private_data is confusing in these APIs:
> rte_cryptodev_sym_session_set_private_data()
> rte_cryptodev_sym_session_get_private_data()
> It refers to data added at the end of the session hdr for use by the application.
> The session already contains sess_private_data[index] which is used to store
> private pmd data and most references to private data refer to that.
> e.g. external apis
> rte_cryptodev_sym_get_private_session_size() and internal
> set/get_session_private_data() refer to sess_private_data[].
> 
> So rename to user_data, i.e.
> rte_cryptodev_sym_session_set_user_data()
> rte_cryptodev_sym_session_get_user_data()
> 
> Refers to changes introduced here:
> https://patches.dpdk.org/patch/38172/
> 
> Signed-off-by: Fiona Trahe <fiona.trahe@intel.com>
> ---
>  doc/guides/prog_guide/cryptodev_lib.rst        | 14 +++++++-------
>  doc/guides/prog_guide/event_crypto_adapter.rst |  6 +++---
>  doc/guides/rel_notes/release_18_08.rst         |  8 ++++++++
>  lib/librte_cryptodev/rte_cryptodev.c           | 16 ++++++++--------
>  lib/librte_cryptodev/rte_cryptodev.h           | 14 +++++++-------
>  lib/librte_cryptodev/rte_cryptodev_version.map |  4 ++--
> lib/librte_eventdev/rte_event_crypto_adapter.c |  4 ++--
>  test/test/test_event_crypto_adapter.c          |  8 ++++----
>  8 files changed, 41 insertions(+), 33 deletions(-)
> 
> diff --git a/doc/guides/prog_guide/cryptodev_lib.rst
> b/doc/guides/prog_guide/cryptodev_lib.rst
> index 30f0bcf7a..3dbf4dde6 100644
> --- a/doc/guides/prog_guide/cryptodev_lib.rst
> +++ b/doc/guides/prog_guide/cryptodev_lib.rst
> @@ -302,24 +302,24 @@ enqueue call.
>  Private data
>  ~~~~~~~~~~~~
>  For session-based operations, the set and get API provides a mechanism for an -
> application to store and retrieve the private data information stored along with -
> the crypto session.
> +application to store and retrieve the private user data information
> +stored along with the crypto session.
> 
>  For example, suppose an application is submitting a crypto operation with a
> session -associated and wants to indicate private data information which is
> required to be
> +associated and wants to indicate private user data information which is
> +required to be
>  used after completion of the crypto operation. In this case, the application can
> use -the set API to set the private data and retrieve it using get API.
> +the set API to set the user data and retrieve it using get API.
> 
>  .. code-block:: c
> 
> -	int rte_cryptodev_sym_session_set_private_data(
> +	int rte_cryptodev_sym_session_set_user_data(
>  		struct rte_cryptodev_sym_session *sess,	void *data, uint16_t
> size);
> 
> -	void * rte_cryptodev_sym_session_get_private_data(
> +	void * rte_cryptodev_sym_session_get_user_data(
>  		struct rte_cryptodev_sym_session *sess);
> 
> 
> -For session-less mode, the private data information can be placed along with
> the
> +For session-less mode, the private user data information can be placed
> +along with the
>  ``struct rte_crypto_op``. The ``rte_crypto_op::private_data_offset`` indicates
> the  start of private data information. The offset is counted from the start of the
> rte_crypto_op including other crypto information such as the IVs (since there
> can diff --git a/doc/guides/prog_guide/event_crypto_adapter.rst
> b/doc/guides/prog_guide/event_crypto_adapter.rst
> index 5c1354dec..9fe09c805 100644
> --- a/doc/guides/prog_guide/event_crypto_adapter.rst
> +++ b/doc/guides/prog_guide/event_crypto_adapter.rst
> @@ -223,9 +223,9 @@ 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
> +For crypto session, ``rte_cryptodev_sym_session_set_user_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.  The
> +by ``rte_cryptodev_sym_session_get_user_data()`` API.  The
>  RTE_EVENT_CRYPTO_ADAPTER_CAP_SESSION_PRIVATE_DATA capability
> indicates  whether HW or SW supports this feature.
> 
> @@ -257,7 +257,7 @@ the ``rte_crypto_op``.
>                  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(
> +                rte_cryptodev_sym_session_set_user_data(
>                          op->sym->session,
>                          &m_data,
>                          sizeof(m_data)); diff --git
> a/doc/guides/rel_notes/release_18_08.rst
> b/doc/guides/rel_notes/release_18_08.rst
> index bc0124295..8f84a088c 100644
> --- a/doc/guides/rel_notes/release_18_08.rst
> +++ b/doc/guides/rel_notes/release_18_08.rst
> @@ -60,6 +60,14 @@ API Changes
>     Also, make sure to start the actual text at the margin.
>     =========================================================
> 
> +* **Renamed cryptodev experimental APIs.**
> +
> +  Used user_data instead of private_data in following APIs to avoid
> + confusion  with the existing session parameter ``sess_private_data[]`` and
> related APIs.
> +  ``rte_cryptodev_sym_session_set_private_data()`` changed to
> + ``rte_cryptodev_sym_session_set_user_data()``
> +  ``rte_cryptodev_sym_session_get_private_data()`` changed to
> + ``rte_cryptodev_sym_session_get_user_data()``
> 
>  ABI Changes
>  -----------
> diff --git a/lib/librte_cryptodev/rte_cryptodev.c
> b/lib/librte_cryptodev/rte_cryptodev.c
> index 7e5821246..88f4af5f6 100644
> --- a/lib/librte_cryptodev/rte_cryptodev.c
> +++ b/lib/librte_cryptodev/rte_cryptodev.c
> @@ -1123,7 +1123,7 @@ rte_cryptodev_sym_session_create(struct
> rte_mempool *mp)
>  	}
> 
>  	/* Clear device session pointer.
> -	 * Include the flag indicating presence of private data
> +	 * Include the flag indicating presence of user data
>  	 */
>  	memset(sess, 0, (sizeof(void *) * nb_drivers) + sizeof(uint8_t));
> 
> @@ -1236,7 +1236,7 @@ rte_cryptodev_sym_get_header_session_size(void)
>  	/*
>  	 * Header contains pointers to the private data
>  	 * of all registered drivers, and a flag which
> -	 * indicates presence of private data
> +	 * indicates presence of user data
>  	 */
>  	return ((sizeof(void *) * nb_drivers) + sizeof(uint8_t));  } @@ -1277,31
> +1277,31 @@ rte_cryptodev_sym_get_private_session_size(uint8_t dev_id)  }
> 
>  int __rte_experimental
> -rte_cryptodev_sym_session_set_private_data(
> +rte_cryptodev_sym_session_set_user_data(
>  					struct rte_cryptodev_sym_session
> *sess,
>  					void *data,
>  					uint16_t size)
>  {
>  	uint16_t off_set = sizeof(void *) * nb_drivers;
> -	uint8_t *private_data_present = (uint8_t *)sess + off_set;
> +	uint8_t *user_data_present = (uint8_t *)sess + off_set;
> 
>  	if (sess == NULL)
>  		return -EINVAL;
> 
> -	*private_data_present = 1;
> +	*user_data_present = 1;
>  	off_set += sizeof(uint8_t);
>  	rte_memcpy((uint8_t *)sess + off_set, data, size);
>  	return 0;
>  }
> 
>  void * __rte_experimental
> -rte_cryptodev_sym_session_get_private_data(
> +rte_cryptodev_sym_session_get_user_data(
>  					struct rte_cryptodev_sym_session
> *sess)  {
>  	uint16_t off_set = sizeof(void *) * nb_drivers;
> -	uint8_t *private_data_present = (uint8_t *)sess + off_set;
> +	uint8_t *user_data_present = (uint8_t *)sess + off_set;
> 
> -	if (sess == NULL || !*private_data_present)
> +	if (sess == NULL || !*user_data_present)
>  		return NULL;
> 
>  	off_set += sizeof(uint8_t);
> diff --git a/lib/librte_cryptodev/rte_cryptodev.h
> b/lib/librte_cryptodev/rte_cryptodev.h
> index ccc0f73fd..5d4e690c2 100644
> --- a/lib/librte_cryptodev/rte_cryptodev.h
> +++ b/lib/librte_cryptodev/rte_cryptodev.h
> @@ -1041,35 +1041,35 @@ int rte_cryptodev_driver_id_get(const char
> *name);  const char *rte_cryptodev_driver_name_get(uint8_t driver_id);
> 
>  /**
> - * Set private data for a session.
> + * Store user data in a session.
>   *
>   * @param	sess		Session pointer allocated by
>   *				*rte_cryptodev_sym_session_create*.
> - * @param	data		Pointer to the private data.
> - * @param	size		Size of the private data.
> + * @param	data		Pointer to the user data.
> + * @param	size		Size of the user data.
>   *
>   * @return
>   *  - On success, zero.
>   *  - On failure, a negative value.
>   */
>  int __rte_experimental
> -rte_cryptodev_sym_session_set_private_data(
> +rte_cryptodev_sym_session_set_user_data(
>  					struct rte_cryptodev_sym_session
> *sess,
>  					void *data,
>  					uint16_t size);
> 
>  /**
> - * Get private data of a session.
> + * Get user data stored in a session.
>   *
>   * @param	sess		Session pointer allocated by
>   *				*rte_cryptodev_sym_session_create*.
>   *
>   * @return
> - *  - On success return pointer to private data.
> + *  - On success return pointer to user data.
>   *  - On failure returns NULL.
>   */
>  void * __rte_experimental
> -rte_cryptodev_sym_session_get_private_data(
> +rte_cryptodev_sym_session_get_user_data(
>  					struct rte_cryptodev_sym_session
> *sess);
> 
>  #ifdef __cplusplus
> diff --git a/lib/librte_cryptodev/rte_cryptodev_version.map
> b/lib/librte_cryptodev/rte_cryptodev_version.map
> index be8f4c1a7..c0ea9c875 100644
> --- a/lib/librte_cryptodev/rte_cryptodev_version.map
> +++ b/lib/librte_cryptodev/rte_cryptodev_version.map
> @@ -97,6 +97,6 @@ DPDK_18.05 {
>  EXPERIMENTAL {
>          global:
> 
> -	rte_cryptodev_sym_session_get_private_data;
> -	rte_cryptodev_sym_session_set_private_data;
> +	rte_cryptodev_sym_session_get_user_data;
> +	rte_cryptodev_sym_session_set_user_data;
>  };
> diff --git a/lib/librte_eventdev/rte_event_crypto_adapter.c
> b/lib/librte_eventdev/rte_event_crypto_adapter.c
> index ba63a87b7..11b28ca9b 100644
> --- a/lib/librte_eventdev/rte_event_crypto_adapter.c
> +++ b/lib/librte_eventdev/rte_event_crypto_adapter.c
> @@ -342,7 +342,7 @@ eca_enq_to_cryptodev(struct
> rte_event_crypto_adapter *adapter,
>  		if (crypto_op == NULL)
>  			continue;
>  		if (crypto_op->sess_type == RTE_CRYPTO_OP_WITH_SESSION) {
> -			m_data =
> rte_cryptodev_sym_session_get_private_data(
> +			m_data = rte_cryptodev_sym_session_get_user_data(
>  					crypto_op->sym->session);
>  			if (m_data == NULL) {
>  				rte_pktmbuf_free(crypto_op->sym->m_src);
> @@ -512,7 +512,7 @@ eca_ops_enqueue_burst(struct
> rte_event_crypto_adapter *adapter,
>  	for (i = 0; i < num; i++) {
>  		struct rte_event *ev = &events[nb_ev++];
>  		if (ops[i]->sess_type == RTE_CRYPTO_OP_WITH_SESSION) {
> -			m_data =
> rte_cryptodev_sym_session_get_private_data(
> +			m_data = rte_cryptodev_sym_session_get_user_data(
>  					ops[i]->sym->session);
>  		} else if (ops[i]->sess_type == RTE_CRYPTO_OP_SESSIONLESS
> &&
>  				ops[i]->private_data_offset) {
> diff --git a/test/test/test_event_crypto_adapter.c
> b/test/test/test_event_crypto_adapter.c
> index 066b0adef..de258c346 100644
> --- a/test/test/test_event_crypto_adapter.c
> +++ b/test/test/test_event_crypto_adapter.c
> @@ -205,12 +205,12 @@ test_op_forward_mode(uint8_t session_less)
>  		TEST_ASSERT_SUCCESS(ret, "Failed to get adapter
> capabilities\n");
> 
>  		if (cap &
> RTE_EVENT_CRYPTO_ADAPTER_CAP_SESSION_PRIVATE_DATA) {
> -			/* Fill in private date information */
> +			/* Fill in private user data information */
>  			rte_memcpy(&m_data.response_info, &response_info,
>  				sizeof(response_info));
>  			rte_memcpy(&m_data.request_info, &request_info,
>  				sizeof(request_info));
> -			rte_cryptodev_sym_session_set_private_data(sess,
> +			rte_cryptodev_sym_session_set_user_data(sess,
>  						&m_data, sizeof(m_data));
>  		}
> 
> @@ -389,10 +389,10 @@ test_op_new_mode(uint8_t session_less)
>  		TEST_ASSERT_SUCCESS(ret, "Failed to get adapter
> capabilities\n");
> 
>  		if (cap &
> RTE_EVENT_CRYPTO_ADAPTER_CAP_SESSION_PRIVATE_DATA) {
> -			/* Fill in private data information */
> +			/* Fill in private user data information */
>  			rte_memcpy(&m_data.response_info, &response_info,
>  				   sizeof(m_data));
> -			rte_cryptodev_sym_session_set_private_data(sess,
> +			rte_cryptodev_sym_session_set_user_data(sess,
>  						&m_data, sizeof(m_data));
>  		}
>  		rte_cryptodev_sym_session_init(TEST_CDEV_ID, sess,
> --
> 2.13.6