patches for DPDK stable branches
 help / color / mirror / Atom feed
* [PATCH] doc: fix cryptodev code block mismatch
@ 2023-03-21 13:05 Akhil Goyal
  2023-03-21 14:50 ` Thomas Monjalon
  2023-03-27  8:21 ` Power, Ciara
  0 siblings, 2 replies; 8+ messages in thread
From: Akhil Goyal @ 2023-03-21 13:05 UTC (permalink / raw)
  To: dev
  Cc: thomas, david.marchand, hemant.agrawal, anoobj,
	pablo.de.lara.guarch, fiona.trahe, declan.doherty, matan,
	g.singh, fanzhang.oss, jianjay.zhou, asomalap, ruifeng.wang,
	konstantin.v.ananyev, radu.nicolau, ajit.khaparde, rnagadheeraj,
	adwivedi, ciara.power, Akhil Goyal, stable

Certain structures were replicated in programmer's guide,
which resulted in mismatch when that structure is changed
in future releases.
Added literal includes to copy code block while compiling.

Fixes: 0318c02b57cf ("doc: add cryptodev chapter in prog guide")
Cc: stable@dpdk.org

Signed-off-by: Akhil Goyal <gakhil@marvell.com>
Reported-by: David Marchand <david.marchand@redhat.com>
---
 doc/guides/prog_guide/cryptodev_lib.rst | 121 ++++--------------------
 lib/cryptodev/rte_crypto_sym.h          |   4 +
 lib/cryptodev/rte_cryptodev.h           |   6 ++
 3 files changed, 31 insertions(+), 100 deletions(-)

diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst
index 0d9f7059ea..2b513bbf82 100644
--- a/doc/guides/prog_guide/cryptodev_lib.rst
+++ b/doc/guides/prog_guide/cryptodev_lib.rst
@@ -98,14 +98,10 @@ The rte_cryptodev_configure API is used to configure a Crypto device.
 The ``rte_cryptodev_config`` structure is used to pass the configuration
 parameters for socket selection and number of queue pairs.
 
-.. code-block:: c
-
-    struct rte_cryptodev_config {
-        int socket_id;
-        /**< Socket to allocate resources on */
-        uint16_t nb_queue_pairs;
-        /**< Number of queue pairs to configure on device */
-    };
+.. literalinclude:: ../../../lib/cryptodev/rte_cryptodev.h
+   :language: c
+   :start-after: Structure rte_cryptodev_config 8<
+   :end-before: >8 End of structure rte_cryptodev_config.
 
 
 Configuration of Queue Pairs
@@ -121,11 +117,11 @@ Each queue pairs resources may be allocated on a specified socket.
                 const struct rte_cryptodev_qp_conf *qp_conf,
                 int socket_id)
 
-   struct rte_cryptodev_qp_conf {
-        uint32_t nb_descriptors; /**< Number of descriptors per queue pair */
-        struct rte_mempool *mp_session;
-        /**< The mempool for creating session in sessionless mode */
-    };
+
+.. literalinclude:: ../../../lib/cryptodev/rte_cryptodev.h
+   :language: c
+   :start-after: Structure rte_cryptodev_qp_conf 8<
+   :end-before: >8 End of structure rte_cryptodev_qp_conf.
 
 
 The field ``mp_session`` is used for creating temporary session to process
@@ -271,23 +267,10 @@ This allows the user to query a specific Crypto PMD and get all the device
 features and capabilities. The ``rte_cryptodev_info`` structure contains all the
 relevant information for the device.
 
-.. code-block:: c
-
-    struct rte_cryptodev_info {
-        const char *driver_name;
-        uint8_t driver_id;
-        struct rte_device *device;
-
-        uint64_t feature_flags;
-
-        const struct rte_cryptodev_capabilities *capabilities;
-
-        unsigned max_nb_queue_pairs;
-
-        struct {
-            unsigned max_nb_sessions;
-        } sym;
-    };
+.. literalinclude:: ../../../lib/cryptodev/rte_cryptodev.h
+   :language: c
+   :start-after: Structure rte_cryptodev_info 8<
+   :end-before: >8 End of structure rte_cryptodev_info.
 
 
 Operation Processing
@@ -540,22 +523,10 @@ Currently there are three transforms types cipher, authentication and AEAD.
 Also it is important to note that the order in which the
 transforms are passed indicates the order of the chaining.
 
-.. code-block:: c
-
-    struct rte_crypto_sym_xform {
-        struct rte_crypto_sym_xform *next;
-        /**< next xform in chain */
-        enum rte_crypto_sym_xform_type type;
-        /**< xform type */
-        union {
-            struct rte_crypto_auth_xform auth;
-            /**< Authentication / hash xform */
-            struct rte_crypto_cipher_xform cipher;
-            /**< Cipher xform */
-            struct rte_crypto_aead_xform aead;
-            /**< AEAD xform */
-        };
-    };
+.. literalinclude:: ../../../lib/cryptodev/rte_crypto_sym.h
+   :language: c
+   :start-after: Structure rte_crypto_sym_xform 8<
+   :end-before: >8 End of structure rte_crypto_sym_xform.
 
 The API does not place a limit on the number of transforms that can be chained
 together but this will be limited by the underlying Crypto device poll mode
@@ -578,61 +549,11 @@ authentication/ cipher/ AEAD parameters required depending on the type of operat
 specified in the session or the transform
 chain.
 
-.. code-block:: c
+.. literalinclude:: ../../../lib/cryptodev/rte_crypto_sym.h
+   :language: c
+   :start-after: Structure rte_crypto_sym_op 8<
+   :end-before: >8 End of structure rte_crypto_sym_op.
 
-    struct rte_crypto_sym_op {
-        struct rte_mbuf *m_src;
-        struct rte_mbuf *m_dst;
-
-        union {
-            void *session;
-            /**< Handle for the initialised session context */
-            struct rte_crypto_sym_xform *xform;
-            /**< Session-less API Crypto operation parameters */
-        };
-
-        union {
-            struct {
-                struct {
-                    uint32_t offset;
-                    uint32_t length;
-                } data; /**< Data offsets and length for AEAD */
-
-                struct {
-                    uint8_t *data;
-                    rte_iova_t phys_addr;
-                } digest; /**< Digest parameters */
-
-                struct {
-                    uint8_t *data;
-                    rte_iova_t phys_addr;
-                } aad;
-                /**< Additional authentication parameters */
-            } aead;
-
-            struct {
-                struct {
-                    struct {
-                        uint32_t offset;
-                        uint32_t length;
-                    } data; /**< Data offsets and length for ciphering */
-                } cipher;
-
-                struct {
-                    struct {
-                        uint32_t offset;
-                        uint32_t length;
-                    } data;
-                    /**< Data offsets and length for authentication */
-
-                    struct {
-                        uint8_t *data;
-                        rte_iova_t phys_addr;
-                    } digest; /**< Digest parameters */
-                } auth;
-            };
-        };
-    };
 
 Synchronous mode
 ----------------
diff --git a/lib/cryptodev/rte_crypto_sym.h b/lib/cryptodev/rte_crypto_sym.h
index 2cfe66530c..b43174dbec 100644
--- a/lib/cryptodev/rte_crypto_sym.h
+++ b/lib/cryptodev/rte_crypto_sym.h
@@ -582,6 +582,7 @@ enum rte_crypto_sym_xform_type {
  * hold a single transform, the type field is used to specify which transform
  * is contained within the union
  */
+/* Structure rte_crypto_sym_xform 8< */
 struct rte_crypto_sym_xform {
 	struct rte_crypto_sym_xform *next;
 	/**< next xform in chain */
@@ -597,6 +598,7 @@ struct rte_crypto_sym_xform {
 		/**< AEAD xform */
 	};
 };
+/* >8 End of structure rte_crypto_sym_xform. */
 
 /**
  * Symmetric Cryptographic Operation.
@@ -628,6 +630,7 @@ struct rte_crypto_sym_xform {
  * destination buffer being at a different alignment, relative to buffer start,
  * to the data in the source buffer.
  */
+/* Structure rte_crypto_sym_op 8< */
 struct rte_crypto_sym_op {
 	struct rte_mbuf *m_src;	/**< source mbuf */
 	struct rte_mbuf *m_dst;	/**< destination mbuf */
@@ -889,6 +892,7 @@ struct rte_crypto_sym_op {
 		};
 	};
 };
+/* >8 End of structure rte_crypto_sym_op. */
 
 
 /**
diff --git a/lib/cryptodev/rte_cryptodev.h b/lib/cryptodev/rte_cryptodev.h
index 27cdec8495..3a9ad13660 100644
--- a/lib/cryptodev/rte_cryptodev.h
+++ b/lib/cryptodev/rte_cryptodev.h
@@ -553,6 +553,7 @@ extern const char *
 rte_cryptodev_get_feature_name(uint64_t flag);
 
 /**  Crypto device information */
+/* Structure rte_cryptodev_info 8< */
 struct rte_cryptodev_info {
 	const char *driver_name;	/**< Driver name. */
 	uint8_t driver_id;		/**< Driver identifier */
@@ -581,6 +582,7 @@ struct rte_cryptodev_info {
 		 */
 	} sym;
 };
+/* >8 End of structure rte_cryptodev_info. */
 
 #define RTE_CRYPTODEV_DETACHED  (0)
 #define RTE_CRYPTODEV_ATTACHED  (1)
@@ -593,11 +595,13 @@ enum rte_cryptodev_event_type {
 };
 
 /** Crypto device queue pair configuration structure. */
+/* Structure rte_cryptodev_qp_conf 8<*/
 struct rte_cryptodev_qp_conf {
 	uint32_t nb_descriptors; /**< Number of descriptors per queue pair */
 	struct rte_mempool *mp_session;
 	/**< The mempool for creating session in sessionless mode */
 };
+/* >8 End of structure rte_cryptodev_qp_conf. */
 
 /**
  * Function type used for processing crypto ops when enqueue/dequeue burst is
@@ -726,6 +730,7 @@ extern int
 rte_cryptodev_socket_id(uint8_t dev_id);
 
 /** Crypto device configuration structure */
+/* Structure rte_cryptodev_config 8< */
 struct rte_cryptodev_config {
 	int socket_id;			/**< Socket to allocate resources on */
 	uint16_t nb_queue_pairs;
@@ -738,6 +743,7 @@ struct rte_cryptodev_config {
 	 *  - RTE_CRYTPODEV_FF_SECURITY
 	 */
 };
+/* >8 End of structure rte_cryptodev_config. */
 
 /**
  * Configure a device.
-- 
2.25.1


^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH] doc: fix cryptodev code block mismatch
  2023-03-21 13:05 [PATCH] doc: fix cryptodev code block mismatch Akhil Goyal
@ 2023-03-21 14:50 ` Thomas Monjalon
  2023-03-21 14:57   ` [EXT] " Akhil Goyal
  2023-03-27  8:21 ` Power, Ciara
  1 sibling, 1 reply; 8+ messages in thread
From: Thomas Monjalon @ 2023-03-21 14:50 UTC (permalink / raw)
  To: Akhil Goyal
  Cc: dev, david.marchand, hemant.agrawal, anoobj,
	pablo.de.lara.guarch, fiona.trahe, declan.doherty, matan,
	g.singh, fanzhang.oss, jianjay.zhou, asomalap, ruifeng.wang,
	konstantin.v.ananyev, radu.nicolau, ajit.khaparde, rnagadheeraj,
	adwivedi, ciara.power, stable

21/03/2023 14:05, Akhil Goyal:
> Certain structures were replicated in programmer's guide,
> which resulted in mismatch when that structure is changed
> in future releases.
> Added literal includes to copy code block while compiling.

The best is to avoid including code in docs.
Why do we need these structures in the guide?




^ permalink raw reply	[flat|nested] 8+ messages in thread

* RE: [EXT] Re: [PATCH] doc: fix cryptodev code block mismatch
  2023-03-21 14:50 ` Thomas Monjalon
@ 2023-03-21 14:57   ` Akhil Goyal
  2023-03-21 16:08     ` Thomas Monjalon
  0 siblings, 1 reply; 8+ messages in thread
From: Akhil Goyal @ 2023-03-21 14:57 UTC (permalink / raw)
  To: Thomas Monjalon
  Cc: dev, david.marchand, hemant.agrawal, Anoob Joseph,
	pablo.de.lara.guarch, fiona.trahe, declan.doherty, matan,
	g.singh, fanzhang.oss, jianjay.zhou, asomalap, ruifeng.wang,
	konstantin.v.ananyev, radu.nicolau, ajit.khaparde,
	Nagadheeraj Rottela, Ankur Dwivedi, ciara.power, stable

> 21/03/2023 14:05, Akhil Goyal:
> > Certain structures were replicated in programmer's guide,
> > which resulted in mismatch when that structure is changed
> > in future releases.
> > Added literal includes to copy code block while compiling.
> 
> The best is to avoid including code in docs.
> Why do we need these structures in the guide?
> 
These are not complete code, only the structure defines
Which helps in understanding the fields and flow of APIs.

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [EXT] Re: [PATCH] doc: fix cryptodev code block mismatch
  2023-03-21 14:57   ` [EXT] " Akhil Goyal
@ 2023-03-21 16:08     ` Thomas Monjalon
  2023-03-24 17:53       ` Akhil Goyal
  0 siblings, 1 reply; 8+ messages in thread
From: Thomas Monjalon @ 2023-03-21 16:08 UTC (permalink / raw)
  To: Akhil Goyal
  Cc: dev, david.marchand, hemant.agrawal, Anoob Joseph,
	pablo.de.lara.guarch, fiona.trahe, declan.doherty, matan,
	g.singh, fanzhang.oss, jianjay.zhou, asomalap, ruifeng.wang,
	konstantin.v.ananyev, radu.nicolau, ajit.khaparde,
	Nagadheeraj Rottela, Ankur Dwivedi, ciara.power, stable

21/03/2023 15:57, Akhil Goyal:
> > 21/03/2023 14:05, Akhil Goyal:
> > > Certain structures were replicated in programmer's guide,
> > > which resulted in mismatch when that structure is changed
> > > in future releases.
> > > Added literal includes to copy code block while compiling.
> > 
> > The best is to avoid including code in docs.
> > Why do we need these structures in the guide?
> > 
> These are not complete code, only the structure defines
> Which helps in understanding the fields and flow of APIs.

I'm not opposed, but in general I think it is better
to explain the global design and usage flow in the guides.
The detailed API is explained in the doxygen comments.

With that said, you are the maintainer, so we rely on your choices :)



^ permalink raw reply	[flat|nested] 8+ messages in thread

* RE: [EXT] Re: [PATCH] doc: fix cryptodev code block mismatch
  2023-03-21 16:08     ` Thomas Monjalon
@ 2023-03-24 17:53       ` Akhil Goyal
  0 siblings, 0 replies; 8+ messages in thread
From: Akhil Goyal @ 2023-03-24 17:53 UTC (permalink / raw)
  To: Thomas Monjalon
  Cc: dev, david.marchand, hemant.agrawal, Anoob Joseph,
	pablo.de.lara.guarch, fiona.trahe, declan.doherty, matan,
	g.singh, fanzhang.oss, jianjay.zhou, asomalap, ruifeng.wang,
	konstantin.v.ananyev, radu.nicolau, ajit.khaparde,
	Nagadheeraj Rottela, Ankur Dwivedi, ciara.power, stable

> Subject: Re: [EXT] Re: [PATCH] doc: fix cryptodev code block mismatch
> 
> 21/03/2023 15:57, Akhil Goyal:
> > > 21/03/2023 14:05, Akhil Goyal:
> > > > Certain structures were replicated in programmer's guide,
> > > > which resulted in mismatch when that structure is changed
> > > > in future releases.
> > > > Added literal includes to copy code block while compiling.
> > >
> > > The best is to avoid including code in docs.
> > > Why do we need these structures in the guide?
> > >
> > These are not complete code, only the structure defines
> > Which helps in understanding the fields and flow of APIs.
> 
> I'm not opposed, but in general I think it is better
> to explain the global design and usage flow in the guides.
> The detailed API is explained in the doxygen comments.

Agreed with your point, and I do feel some of these can be removed.
But there is mismatch in the structs along past releases.
I thought of fixing this in stable releases, and we can remove whichever 
Not required in future release.

> 
> With that said, you are the maintainer, so we rely on your choices :)
> 
Thank you for your trust.
Moreover, I am always open for suggestions and improvements.

^ permalink raw reply	[flat|nested] 8+ messages in thread

* RE: [PATCH] doc: fix cryptodev code block mismatch
  2023-03-21 13:05 [PATCH] doc: fix cryptodev code block mismatch Akhil Goyal
  2023-03-21 14:50 ` Thomas Monjalon
@ 2023-03-27  8:21 ` Power, Ciara
  2023-03-27  9:51   ` Hemant Agrawal
  1 sibling, 1 reply; 8+ messages in thread
From: Power, Ciara @ 2023-03-27  8:21 UTC (permalink / raw)
  To: Akhil Goyal, dev
  Cc: thomas, david.marchand, hemant.agrawal, anoobj, De Lara Guarch,
	Pablo, Trahe, Fiona, Doherty, Declan, matan, g.singh,
	fanzhang.oss, jianjay.zhou, asomalap, ruifeng.wang,
	konstantin.v.ananyev, Nicolau, Radu, ajit.khaparde, rnagadheeraj,
	adwivedi, stable



> -----Original Message-----
> From: Akhil Goyal <gakhil@marvell.com>
> Sent: Tuesday 21 March 2023 13:05
> To: dev@dpdk.org
> Cc: thomas@monjalon.net; david.marchand@redhat.com;
> hemant.agrawal@nxp.com; anoobj@marvell.com; De Lara Guarch, Pablo
> <pablo.de.lara.guarch@intel.com>; Trahe, Fiona <fiona.trahe@intel.com>;
> Doherty, Declan <declan.doherty@intel.com>; matan@nvidia.com;
> g.singh@nxp.com; fanzhang.oss@gmail.com; jianjay.zhou@huawei.com;
> asomalap@amd.com; ruifeng.wang@arm.com;
> konstantin.v.ananyev@yandex.ru; Nicolau, Radu <radu.nicolau@intel.com>;
> ajit.khaparde@broadcom.com; rnagadheeraj@marvell.com;
> adwivedi@marvell.com; Power, Ciara <ciara.power@intel.com>; Akhil Goyal
> <gakhil@marvell.com>; stable@dpdk.org
> Subject: [PATCH] doc: fix cryptodev code block mismatch
> 
> Certain structures were replicated in programmer's guide, which resulted in
> mismatch when that structure is changed in future releases.
> Added literal includes to copy code block while compiling.
> 
> Fixes: 0318c02b57cf ("doc: add cryptodev chapter in prog guide")
> Cc: stable@dpdk.org
> 
> Signed-off-by: Akhil Goyal <gakhil@marvell.com>
> Reported-by: David Marchand <david.marchand@redhat.com>
> ---
>  doc/guides/prog_guide/cryptodev_lib.rst | 121 ++++--------------------
>  lib/cryptodev/rte_crypto_sym.h          |   4 +
>  lib/cryptodev/rte_cryptodev.h           |   6 ++
>  3 files changed, 31 insertions(+), 100 deletions(-)

Acked-by: Ciara Power <ciara.power@intel.com>

^ permalink raw reply	[flat|nested] 8+ messages in thread

* RE: [PATCH] doc: fix cryptodev code block mismatch
  2023-03-27  8:21 ` Power, Ciara
@ 2023-03-27  9:51   ` Hemant Agrawal
  2023-03-28  6:39     ` Akhil Goyal
  0 siblings, 1 reply; 8+ messages in thread
From: Hemant Agrawal @ 2023-03-27  9:51 UTC (permalink / raw)
  To: Power, Ciara, Akhil Goyal, dev
  Cc: thomas, david.marchand, anoobj, De Lara Guarch, Pablo, Trahe,
	Fiona, Doherty, Declan, matan, Gagandeep Singh, fanzhang.oss,
	jianjay.zhou, asomalap, ruifeng.wang, konstantin.v.ananyev,
	Nicolau, Radu, ajit.khaparde, rnagadheeraj, adwivedi, stable

Acked-by: Hemant Agrawal <hemant.agrawal@nxp.com>

^ permalink raw reply	[flat|nested] 8+ messages in thread

* RE: [PATCH] doc: fix cryptodev code block mismatch
  2023-03-27  9:51   ` Hemant Agrawal
@ 2023-03-28  6:39     ` Akhil Goyal
  0 siblings, 0 replies; 8+ messages in thread
From: Akhil Goyal @ 2023-03-28  6:39 UTC (permalink / raw)
  To: Hemant Agrawal, Power, Ciara, dev
  Cc: thomas, david.marchand, Anoob Joseph, De Lara Guarch, Pablo,
	Trahe, Fiona, Doherty, Declan, matan, Gagandeep Singh,
	fanzhang.oss, jianjay.zhou, asomalap, ruifeng.wang,
	konstantin.v.ananyev, Nicolau, Radu, ajit.khaparde,
	Nagadheeraj Rottela, Ankur Dwivedi, stable

> Acked-by: Hemant Agrawal <hemant.agrawal@nxp.com>

Applied to dpdk-next-crypto

Thanks.

^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2023-03-28  6:39 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-03-21 13:05 [PATCH] doc: fix cryptodev code block mismatch Akhil Goyal
2023-03-21 14:50 ` Thomas Monjalon
2023-03-21 14:57   ` [EXT] " Akhil Goyal
2023-03-21 16:08     ` Thomas Monjalon
2023-03-24 17:53       ` Akhil Goyal
2023-03-27  8:21 ` Power, Ciara
2023-03-27  9:51   ` Hemant Agrawal
2023-03-28  6:39     ` Akhil Goyal

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).