From: Konstantin Ananyev Date: Thu, 11 Oct 2018 14:20:24 +0000 (+0100) Subject: doc: announce API change for cryptodev sym session X-Git-Url: http://git.droids-corp.org/?a=commitdiff_plain;h=e9b0cfc28ccdb080bb456c9ffdfb8632be4cd826;p=dpdk.git doc: announce API change for cryptodev sym session 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 Acked-by: Fan Zhang Acked-by: Akhil Goyal Acked-by: Fiona Trahe Acked-by: Anoob Joseph --- diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst index 82f7b37ddb..6bc5189eff 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -79,6 +79,15 @@ Deprecation Notices ``rte_security_session`` structure. That would allow upper layer to easily associate/de-associate some user defined data with the security session. +* 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. + * pdump: As we changed to use generic IPC, some changes in APIs and structure are expected in subsequent release.