Skip to content

Commit

Permalink
doc: fix code blocks in cryptodev guide
Browse files Browse the repository at this point in the history 
[ upstream commit d2d7f0190bce57b2a07942e7c11a1e77a9c029ca ]

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: 0318c02 ("doc: add cryptodev chapter in prog guide")

Reported-by: David Marchand <david.marchand@redhat.com>
Signed-off-by: Akhil Goyal <gakhil@marvell.com>
Acked-by: Ciara Power <ciara.power@intel.com>
Acked-by: Hemant Agrawal <hemant.agrawal@nxp.com>
  • Loading branch information
@bluca
Akhil Goyal authored and bluca committed Mar 29, 2023
1 parent 062d5d3 commit 6500e9e
Show file tree
Hide file tree
Showing 3 changed files with 31 additions and 102 deletions.
123 changes: 21 additions & 102 deletions doc/guides/prog_guide/cryptodev_lib.rst
View file
Expand Up @@ -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/librte_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
Expand All @@ -121,13 +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 */
struct rte_mempool *mp_session_private;
/**< The mempool for creating sess private data in sessionless mode */
};
.. literalinclude:: ../../../lib/librte_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 fields ``mp_session`` and ``mp_session_private`` are used for creating
Expand Down Expand Up @@ -273,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/librte_cryptodev/rte_cryptodev.h
:language: c
:start-after: Structure rte_cryptodev_info 8<
:end-before: >8 End of structure rte_cryptodev_info.


Operation Processing
Expand Down Expand Up @@ -506,22 +487,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/librte_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
Expand All @@ -544,61 +513,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/librte_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 {
struct rte_cryptodev_sym_session *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
----------------
Expand Down
4 changes: 4 additions & 0 deletions lib/librte_cryptodev/rte_crypto_sym.h
View file
Expand Up @@ -540,6 +540,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 */
Expand All @@ -555,6 +556,7 @@ struct rte_crypto_sym_xform {
/**< AEAD xform */
};
};
/* >8 End of structure rte_crypto_sym_xform. */

struct rte_cryptodev_sym_session;

Expand Down Expand Up @@ -588,6 +590,7 @@ struct rte_cryptodev_sym_session;
* 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 */
Expand Down Expand Up @@ -850,6 +853,7 @@ struct rte_crypto_sym_op {
};
};
};
/* >8 End of structure rte_crypto_sym_op. */


/**
Expand Down
6 changes: 6 additions & 0 deletions lib/librte_cryptodev/rte_cryptodev.h
View file
Expand Up @@ -474,6 +474,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 */
Expand Down Expand Up @@ -502,6 +503,7 @@ struct rte_cryptodev_info {
*/
} sym;
};
/* >8 End of structure rte_cryptodev_info. */

#define RTE_CRYPTODEV_DETACHED (0)
#define RTE_CRYPTODEV_ATTACHED (1)
Expand All @@ -514,13 +516,15 @@ 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 */
struct rte_mempool *mp_session_private;
/**< The mempool for creating sess private data in sessionless mode */
};
/* >8 End of structure rte_cryptodev_qp_conf. */

/**
* Typedef for application callback function to be registered by application
Expand Down Expand Up @@ -625,6 +629,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;
Expand All @@ -637,6 +642,7 @@ struct rte_cryptodev_config {
* - RTE_CRYTPODEV_FF_SECURITY
*/
};
/* >8 End of structure rte_cryptodev_config. */

/**
* Configure a device.
Expand Down

0 comments on commit 6500e9e

Please sign in to comment.