From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by dpdk.org (Postfix) with ESMTP id 38ED81B4E1 for ; Thu, 11 Oct 2018 16:22:26 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga102.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 11 Oct 2018 07:22:26 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.54,368,1534834800"; d="scan'208";a="91139437" Received: from sivswdev02.ir.intel.com (HELO localhost.localdomain) ([10.237.217.46]) by orsmga003.jf.intel.com with ESMTP; 11 Oct 2018 07:20:31 -0700 From: Konstantin Ananyev To: dev@dpdk.org Cc: Konstantin Ananyev Date: Thu, 11 Oct 2018 15:20:24 +0100 Message-Id: <1539267624-31373-1-git-send-email-konstantin.ananyev@intel.com> X-Mailer: git-send-email 1.7.0.7 Subject: [dpdk-dev] [PATCH] doc: cryptodev deprecation notice for sym session changes 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: Thu, 11 Oct 2018 14:22:27 -0000 Below are details and reasoning for proposed changes. 1.rte_cryptodev_sym_session_init()/ rte_cryptodev_sym_session_clear() operate based on cytpodev device id, though inside rte_cryptodev_sym_session device specific data is addressed by driver id (not device id). That creates a problem with current implementation when we have two or more devices with the same driver used by the same session. Consider the following example: struct rte_cryptodev_sym_session *sess; rte_cryptodev_sym_session_init(dev_id=X, sess, ...); rte_cryptodev_sym_session_init(dev_id=Y, sess, ...); rte_cryptodev_sym_session_clear(dev_id=X, sess); After that point if X and Y uses the same driver, then sess can't be used by device Y any more. The reason for that - driver specific (not device specific) data per session, plus there is no information how many device instances use that data. Probably the simplest way to deal with that issue - add a reference counter per each driver data. 2.rte_cryptodev_sym_session_set_user_data() and rte_cryptodev_sym_session_get_user_data() - with current implementation there is no defined way for the user to determine what is the max allowed size of the private data. rte_cryptodev_sym_session_set_user_data() just blindly copies user provided data without checking memory boundaries violation. To overcome that issue propose to add 'uint16_t priv_size' into rte_cryptodev_sym_session structure. 3.rte_cryptodev_sym_session contains an array of variable size for driver specific data. Though number of elements in that array is determined by static variable nb_drivers, that could be modified by rte_cryptodev_allocate_driver(). That construction seems to work ok so far, as right now users register all their PMDs at startup, though it doesn't mean that it would always remain like that. To make it less error prone propose to add 'uint16_t nb_drivers' into the rte_cryptodev_sym_session structure. At least that allows related functions to check that provided driver id wouldn't overrun variable array boundaries, again it allows to determine size of already allocated session without accessing global variable. 4.#2 and #3 above implies that now each struct rte_cryptodev_sym_session would have sort of readonly type data (init once at allocation time, keep unmodified through session life-time). That requires more changes in current cryptodev implementation: Right now inside cryptodev framework both rte_cryptodev_sym_session and driver specific session data are two completely different sctrucures (e.g. struct cryptodev_sym_session and struct null_crypto_session). Though current cryptodev implementation implicitly assumes that driver will allocate both of them from within the same mempool. Plus this is done in a manner that they override each other fields (reuse the same space - sort of implicit C union). That's probably not the best programming practice, plus make impossible to have readonly fields inside both of them. To overcome that situation propose to changed an API a bit, to allow to use two different mempools for these two distinct data structures. 5. Add 'uint64_t userdata' inside struct rte_cryptodev_sym_session. I suppose that self-explanatory, and might be used in a lot of places (would be quite useful for ipsec library we develop). The new proposed layout for rte_cryptodev_sym_session: struct rte_cryptodev_sym_session { uint64_t userdata; /**< Can be used for external metadata */ uint16_t nb_drivers; /**< number of elements in sess_data array */ uint16_t priv_size; /**< session private data will be placed after sess_data */ __extension__ struct { void *data; uint16_t refcnt; } sess_data[0]; /**< Driver specific session material, variable size */ }; Signed-off-by: Konstantin Ananyev --- doc/guides/rel_notes/deprecation.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst index d2aec64d1..998a0d92c 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -74,3 +74,12 @@ Deprecation Notices This is due to a lack of flexibility and reliance on a type unusable with C++ programs (struct rte_flow_desc). + +* cryptodev: several API and ABI changes are planned for rte_cryptodev + in v19.02: + + - The size and layout of ``rte_cryptodev_sym_session`` will change + to fix existing issues. + - The size and layout of ``rte_cryptodev_qp_conf`` and syntax of + ``rte_cryptodev_queue_pair_setup`` will change to to allow to use + two different mempools for crypto and device private sessions. -- 2.13.6