From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id 8F2247CCC for ; Mon, 3 Jul 2017 01:57:35 +0200 (CEST) Received: from orsmga002.jf.intel.com ([10.7.209.21]) by orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 02 Jul 2017 16:57:35 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.40,300,1496127600"; d="scan'208";a="106359517" Received: from silpixa00399464.ir.intel.com (HELO silpixa00399464.ger.corp.intel.com) ([10.237.222.157]) by orsmga002.jf.intel.com with ESMTP; 02 Jul 2017 16:57:32 -0700 From: Pablo de Lara To: declan.doherty@intel.com, zbigniew.bodek@caviumnetworks.com, jerin.jacob@caviumnetworks.com, akhil.goyal@nxp.com, hemant.agrawal@nxp.com, fiona.trahe@intel.com, john.griffin@intel.com, deepak.k.jain@intel.com Cc: dev@dpdk.org, Pablo de Lara , Slawomir Mrozowicz Date: Sun, 2 Jul 2017 16:57:19 +0100 Message-Id: <20170702155719.66530-13-pablo.de.lara.guarch@intel.com> X-Mailer: git-send-email 2.9.4 In-Reply-To: <20170702155719.66530-1-pablo.de.lara.guarch@intel.com> References: <20170630170933.56631-1-pablo.de.lara.guarch@intel.com> <20170702155719.66530-1-pablo.de.lara.guarch@intel.com> Subject: [dpdk-dev] [PATCH v3 12/12] doc: add new crypto session information X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 02 Jul 2017 23:57:36 -0000 Modified cryptodev library section in Programmer's Guide, with the recent changes in the crypto sessions. Signed-off-by: Slawomir Mrozowicz Signed-off-by: Pablo de Lara --- doc/guides/prog_guide/cryptodev_lib.rst | 59 ++-- doc/guides/prog_guide/img/cryptodev_sym_sess.svg | 418 ++++++++++++++++++++--- 2 files changed, 400 insertions(+), 77 deletions(-) diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst index 4644802..3d3239d 100644 --- a/doc/guides/prog_guide/cryptodev_lib.rst +++ b/doc/guides/prog_guide/cryptodev_lib.rst @@ -114,9 +114,8 @@ The rte_cryptodev_configure API is used to configure a Crypto device. int rte_cryptodev_configure(uint8_t dev_id, struct rte_cryptodev_config *config) -The ``rte_cryptodev_config`` structure is used to pass the configuration parameters. -In contains parameter for socket selection, number of queue pairs and the -session mempool configuration. +The ``rte_cryptodev_config`` structure is used to pass the configuration +parameters for socket selection and number of queue pairs. .. code-block:: c @@ -125,12 +124,6 @@ session mempool configuration. /**< Socket to allocate resources on */ uint16_t nb_queue_pairs; /**< Number of queue pairs to configure on device */ - - struct { - uint32_t nb_objs; - uint32_t cache_size; - } session_mp; - /**< Session mempool configuration */ }; @@ -431,7 +424,7 @@ operations, as well as also supporting AEAD operations. Session and Session Management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Session are used in symmetric cryptographic processing to store the immutable +Sessions are used in symmetric cryptographic processing to store the immutable data defined in a cryptographic transform which is used in the operation processing of a packet flow. Sessions are used to manage information such as expand cipher keys and HMAC IPADs and OPADs, which need to be calculated for a @@ -442,27 +435,31 @@ Crypto workloads. .. figure:: img/cryptodev_sym_sess.* -The Crypto device framework provides a set of session pool management APIs for -the creation and freeing of the sessions, utilizing the Mempool Library. - -The framework also provides hooks so the PMDs can pass the amount of memory -required for that PMDs private session parameters, as well as initialization -functions for the configuration of the session parameters and freeing function -so the PMD can managed the memory on destruction of a session. - -**Note**: Sessions created on a particular device can only be used on Crypto -devices of the same type - the same driver id used by this devices, -and if you try to use a session on a device different -to that on which it was created then the Crypto operation will fail. - -``rte_cryptodev_sym_session_create()`` is used to create a symmetric session on -Crypto device. A symmetric transform chain is used to specify the particular -operation and its parameters. See the section below for details on transforms. - -.. code-block:: c - - struct rte_cryptodev_sym_session * rte_cryptodev_sym_session_create( - uint8_t dev_id, struct rte_crypto_sym_xform *xform); +The Crypto device framework provides APIs to allocate and initizalize sessions +for crypto devices, where sessions are mempool objects. +It is the application's responsibility to create and manage the session mempools. +This approach allows for different scenarios such as having a single session +mempool for all crypto devices (where the mempool object size is big +enough to hold the private session of any crypto device), as well as having +multiple session mempools of different sizes for better memory usage. + +An application can use ``rte_cryptodev_get_private_session_size()`` to +get the private session size of given crypto device. This function would allow +an application to calculate the max device session size of all crypto devices +to create a single session mempool. +If instead an application creates multiple session mempools, the Crypto device +framework also provides ``rte_cryptodev_get_header_session_size`` to get +the size of an uninitialized session. + +Once the session mempools have been created, ``rte_cryptodev_sym_session_create()`` +is used to allocate an uninitialized session from the given mempool. +The session then must be initialized using ``rte_cryptodev_sym_session_init()`` +for each of the required crypto devices. A symmetric transform chain +is used to specify the operation and its parameters. See the section below for +details on transforms. + +Unused session should be freed using ``rte_cryptodev_sym_session_free`` which +returns them to their mempool. **Note**: For AEAD operations the algorithm selected for authentication and ciphering must aligned, eg AES_GCM. diff --git a/doc/guides/prog_guide/img/cryptodev_sym_sess.svg b/doc/guides/prog_guide/img/cryptodev_sym_sess.svg index e5f41ec..a807ceb 100644 --- a/doc/guides/prog_guide/img/cryptodev_sym_sess.svg +++ b/doc/guides/prog_guide/img/cryptodev_sym_sess.svg @@ -1,10 +1,50 @@ - - - -- 2.9.4