From patchwork Fri Jan 6 13:05:00 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Zhang, Fan" X-Patchwork-Id: 121682 X-Patchwork-Delegate: gakhil@marvell.com Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id D4529A00C2; Fri, 6 Jan 2023 14:05:09 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7244F400EF; Fri, 6 Jan 2023 14:05:09 +0100 (CET) Received: from mail-wm1-f53.google.com (mail-wm1-f53.google.com [209.85.128.53]) by mails.dpdk.org (Postfix) with ESMTP id 0BEF0400D4 for ; Fri, 6 Jan 2023 14:05:08 +0100 (CET) Received: by mail-wm1-f53.google.com with SMTP id k22-20020a05600c1c9600b003d1ee3a6289so1025585wms.2 for ; Fri, 06 Jan 2023 05:05:08 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=BfoNAB1EBi/LDpqqXFt4Tz3WlK1qL01BMNhi8U8xWp8=; b=majl/9rO3NiQH4dMuFd/C4q9rz2w97m2Lsx+FgVxN4j1gCXBOOEHjmB1ypNBeIRv36 uw/Xr9JaYiv19ruSyQ3qYc9CG4UB1+Ci0OwC3+/Q59BYaloo0926ViEs5AJEdAaCA5Y0 ahG/WcB0rpXJXWj1O7omyVQvILNzuZ+JhndrfQSTEa8MuLgH3AHSuUQA8vlfHp0wVIH4 t8ubeO2yHbYDE2QaYIVRylIIV3t9YPqJz9Kgy+t/vpOwXv//CZuWBLgvWUdeDpWeTPKr beThTJI32htKN3E+tSfcKAIJ3HbCafv4WKBVgimG48sV9L+I8SxlS14eIAfIv6hN8HJk ZUkg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=BfoNAB1EBi/LDpqqXFt4Tz3WlK1qL01BMNhi8U8xWp8=; b=dTaf5o7+JaiLrm1xRlGCOOqMkVhUrNcaZG3KhkpRjgDMM5WJE0TM/MlZpfYWHyfo4C zojPm1xuv9R2Spv4borIc3jLcIanZek88PKDrNku1iGiYz32i5E7ve9YE9EQ4Yxx81XZ k73g/X0mHNAF0BdpHXsWpBfNHW6Jtmu8Mnyl0KczSvX/9VTBqFFYA4vLEOttZPegneWX IPuF6PQPe7hy4eBYC/ZsS4vVfYldiqPb4582+Rc/5qpHhhre1RBbmHJyflWd5n0ZHODg kxn89TTc1N7yB5xTcg/JNLqehgJwZNZlumQy+By3ACRj7pic4VQPFdvDkDnZcBSMilBq PVAQ== X-Gm-Message-State: AFqh2kqkn3qeMj4+Q9N7F158A7uXdsQqyoloBysdBhFvDRAxlf8CR366 odY05LpQzMF0Xr2IWCaQNZdagUxUSz5bfA== X-Google-Smtp-Source: AMrXdXupIU9IQDXEKuWPWqEHU4KyOWOuAOihvAd79EbtemsORXnvMRXSj3tIpkZnc+/dQa5vPk+RvQ== X-Received: by 2002:a05:600c:1e10:b0:3d3:404a:8a1b with SMTP id ay16-20020a05600c1e1000b003d3404a8a1bmr38600088wmb.8.1673010307270; Fri, 06 Jan 2023 05:05:07 -0800 (PST) Received: from fanz01-PC.localdomain ([64.43.20.179]) by smtp.gmail.com with ESMTPSA id y7-20020a7bcd87000000b003d997e5e679sm1890242wmj.14.2023.01.06.05.05.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Jan 2023 05:05:06 -0800 (PST) From: Fan Zhang To: dev@dpdk.org Cc: gakhil@marvell.com, Fan Zhang Subject: [PATCH] cryptodev: fix sym session mempool creation description Date: Fri, 6 Jan 2023 13:05:00 +0000 Message-Id: <20230106130500.23569-1-fanzhang.oss@gmail.com> X-Mailer: git-send-email 2.25.1 MIME-Version: 1.0 X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org After the session mempool creation API is changed, some description is no longer valid. This patch fixes the descriptions in both API comment and the programmer's guide. Fixes: bdce2564dbf7 ("cryptodev: rework session framework") Cc: gakhil@marvell.com Signed-off-by: Fan Zhang Acked-by: Akhil Goyal --- doc/guides/prog_guide/cryptodev_lib.rst | 41 +- .../prog_guide/img/cryptodev_sym_sess.svg | 417 ------------------ lib/cryptodev/rte_cryptodev.h | 17 +- 3 files changed, 26 insertions(+), 449 deletions(-) delete mode 100644 doc/guides/prog_guide/img/cryptodev_sym_sess.svg diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst index 01aad842a9..6963229898 100644 --- a/doc/guides/prog_guide/cryptodev_lib.rst +++ b/doc/guides/prog_guide/cryptodev_lib.rst @@ -499,37 +499,28 @@ a flow. Crypto sessions cache this immutable data in a optimal way for the underlying PMD and this allows further acceleration of the offload of Crypto workloads. -.. figure:: img/cryptodev_sym_sess.* - The Crypto device framework provides APIs to create session mempool and allocate and initialize sessions for crypto devices, where sessions are mempool objects. The application has to use ``rte_cryptodev_sym_session_pool_create()`` to -create the session header mempool that creates a mempool with proper element -size automatically and stores necessary information for safely accessing the -session in the mempool's private data field. - -To create a mempool for storing session private data, the application has two -options. The first is to create another mempool with elt size equal to or -bigger than the maximum session private data size of all crypto devices that -will share the same session header. The creation of the mempool shall use the -traditional ``rte_mempool_create()`` with the correct ``elt_size``. The other -option is to change the ``elt_size`` parameter in -``rte_cryptodev_sym_session_pool_create()`` to the correct value. The first -option is more complex to implement but may result in better memory usage as -a session header normally takes smaller memory footprint as the session private -data. +create the session mempool header and the private data with the size specified +by the user through the ``elt_size`` parameter in the function. The session +private data is for the driver to initialize and access during crypto operations, +hence the ``elt_size`` should be big enough for all drivers that will share this +mempool. To obtain the proper session private data size of a crypto device, the +user can call ``rte_cryptodev_sym_get_private_session_size()`` function. In case +of heterogeneous crypto devices will share the same session mempool, the maximum +session private data size of them should be passed. 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. +is used to allocate and initialize the session from the given mempool. The +created session can ONLY be used by the crypto devices sharing the same driver ID +as the device ID passed into the function as the parameter. In addition, a symmetric +transform chain is used to specify the operation and its parameters. +See the section below for details on transforms. -When a session is no longer used, user must call ``rte_cryptodev_sym_session_clear()`` -for each of the crypto devices that are using the session, to free all driver -private session data. Once this is done, session should be freed using -``rte_cryptodev_sym_session_free`` which returns them to their mempool. +When a session is no longer used, user must call ``rte_cryptodev_sym_session_free()`` +to uninitialize the session data and return the session back to the mempool it +belongs. Transforms and Transform Chaining diff --git a/doc/guides/prog_guide/img/cryptodev_sym_sess.svg b/doc/guides/prog_guide/img/cryptodev_sym_sess.svg deleted file mode 100644 index 9b522458c8..0000000000 --- a/doc/guides/prog_guide/img/cryptodev_sym_sess.svg +++ /dev/null @@ -1,417 +0,0 @@ - - - -image/svg+xmlRounded Rectangle.12Crypto Symmetric SessionRounded Rectangle.13Private Session Data - - -Rounded Rectangle.12Crypto Symmetric SessionCrypto Driver Private Session -Crypto Symmetric Session -uint16_t nb_drivers; -struct { -void *data; -} session_data[]; -uint16_t user_data_sz; -user_data -uint16_t refcnt; -uint64_t opaque_data; -Rounded Rectangle.13Private Session DataPrivate Session Data -Rounded Rectangle.12Crypto Symmetric SessionCrypto Driver Private Session -Rounded Rectangle.13Private Session DataPrivate Session Data - -... - \ No newline at end of file diff --git a/lib/cryptodev/rte_cryptodev.h b/lib/cryptodev/rte_cryptodev.h index 86d792e2e7..ed4112c625 100644 --- a/lib/cryptodev/rte_cryptodev.h +++ b/lib/cryptodev/rte_cryptodev.h @@ -911,11 +911,14 @@ rte_cryptodev_get_sec_ctx(uint8_t dev_id); * @param nb_elts * The number of elements in the mempool. * @param elt_size - * The size of the element. This value will be ignored if it is smaller than - * the minimum session header size required for the system. For the user who - * want to use the same mempool for sym session and session private data it - * can be the maximum value of all existing devices' private data and session - * header sizes. + * The size of the element. This should be the size of the cryptodev PMD + * session private data obtained through + * rte_cryptodev_sym_get_private_session_size() function call. + * For the user who wants to use the same mempool for heterogeneous PMDs + * this value should be the maximum value of their private session sizes. + * Please note the created mempool will have bigger elt size than this + * value as necessary session header and the possible padding are filled + * into each elt. * @param cache_size * The number of per-lcore cache elements * @param priv_size @@ -926,8 +929,8 @@ rte_cryptodev_get_sec_ctx(uint8_t dev_id); * constraint for the reserved zone. * * @return - * - On success return size of the session - * - On failure returns 0 + * - On success returns the created session mempool pointer + * - On failure returns NULL */ __rte_experimental struct rte_mempool *