* [dpdk-stable] [PATCH] crypto/scheduler: fix Doxygen comments
@ 2017-04-11 16:15 Fan Zhang
2017-04-11 16:36 ` Mcnamara, John
0 siblings, 1 reply; 2+ messages in thread
From: Fan Zhang @ 2017-04-11 16:15 UTC (permalink / raw)
To: dev; +Cc: pablo.de.lara.guarch, stable, john.mcnamara
This patch adds the missing doxygen comments and updated
inline comments to cryptodev scheduler
Fixes: d58a3f312545 ("crypto/scheduler: add documentation")
Signed-off-by: Fan Zhang <roy.fan.zhang@intel.com>
---
doc/api/doxy-api-index.md | 3 +-
doc/api/doxy-api.conf | 1 +
drivers/crypto/scheduler/rte_cryptodev_scheduler.h | 133 ++++++++++++++-------
3 files changed, 94 insertions(+), 43 deletions(-)
diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md
index a26846a..f5f1f19 100644
--- a/doc/api/doxy-api-index.md
+++ b/doc/api/doxy-api-index.md
@@ -51,7 +51,8 @@ There are many libraries, so their headers may be grouped by topics:
[vhost] (@ref rte_vhost.h),
[KNI] (@ref rte_kni.h),
[ixgbe] (@ref rte_pmd_ixgbe.h),
- [i40e] (@ref rte_pmd_i40e.h)
+ [i40e] (@ref rte_pmd_i40e.h),
+ [crypto_scheduler] (@ref rte_cryptodev_scheduler.h)
- **memory**:
[memseg] (@ref rte_memory.h),
diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf
index 97fb551..ca9194f 100644
--- a/doc/api/doxy-api.conf
+++ b/doc/api/doxy-api.conf
@@ -30,6 +30,7 @@
PROJECT_NAME = DPDK
INPUT = doc/api/doxy-api-index.md \
+ drivers/crypto/scheduler \
drivers/net/bonding \
drivers/net/i40e \
drivers/net/ixgbe \
diff --git a/drivers/crypto/scheduler/rte_cryptodev_scheduler.h b/drivers/crypto/scheduler/rte_cryptodev_scheduler.h
index 3b816d3..9ecc7ff 100644
--- a/drivers/crypto/scheduler/rte_cryptodev_scheduler.h
+++ b/drivers/crypto/scheduler/rte_cryptodev_scheduler.h
@@ -34,6 +34,18 @@
#ifndef _RTE_CRYPTO_SCHEDULER_H
#define _RTE_CRYPTO_SCHEDULER_H
+/**
+ * @file rte_cryptodev_scheduler.h
+ *
+ * RTE Cryptodev Scheduler Device
+ *
+ * The RTE Cryptodev Scheduler Device allows the aggregation of multiple (slave)
+ * Cryptodevs into a single logical crypto device, and the scheduling the of
+ * crypto operations to the slaves based on the mode of the specified mode of
+ * operation specified and supported. This implementation supports 3 modes of
+ * operation: round robin, packet-size based, and fail-over.
+ */
+
#include "rte_cryptodev_scheduler_operations.h"
#ifdef __cplusplus
@@ -45,19 +57,21 @@ extern "C" {
#define RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES (8)
#endif
-/* round-robin scheduling mode */
+/** round-robin scheduling mode string */
#define SCHEDULER_MODE_NAME_ROUND_ROBIN round-robin
-/* packet-size based distribution scheduling mode */
+/** packet-size based distribution scheduling mode string */
#define SCHEDULER_MODE_NAME_PKT_SIZE_DISTR packet-size-distr
-/* fail-over mode */
+/** fail-over scheduling mode string */
#define SCHEDULER_MODE_NAME_FAIL_OVER fail-over
-/**
+/**
* Crypto scheduler PMD operation modes
*/
enum rte_cryptodev_scheduler_mode {
CDEV_SCHED_MODE_NOT_SET = 0,
+ /** user defined mode */
CDEV_SCHED_MODE_USERDEFINED,
+ /** round-robin mode */
CDEV_SCHED_MODE_ROUNDROBIN,
/** packet-size based distribution mode */
CDEV_SCHED_MODE_PKT_SIZE_DISTR,
@@ -75,36 +89,49 @@ struct rte_cryptodev_scheduler;
/**
* Load a user defined scheduler
*
- * @param scheduler_id The target scheduler device ID
- * scheduler Pointer to the user defined scheduler
+ * @param scheduler_id
+ * The target scheduler device ID
+ * @param scheduler
+ * Pointer to the user defined scheduler
*
* @return
- * 0 if loading successful, negative integer if otherwise.
+ * - 0 if the scheduler is successfully loaded
+ * - -ENOTSUP if the operation is not supported.
+ * - -EBUSY if device is started.
*/
int
rte_cryptodev_scheduler_load_user_scheduler(uint8_t scheduler_id,
struct rte_cryptodev_scheduler *scheduler);
/**
- * Attach a pre-configured crypto device to the scheduler
+ * Attach a crypto device to the scheduler
*
- * @param scheduler_id The target scheduler device ID
- * slave_id crypto device ID to be attached
+ * @param scheduler_id
+ * The target scheduler device ID
+ * @param slave_id
+ * crypto device ID to be attached
*
* @return
- * 0 if attaching successful, negative int if otherwise.
+ * - 0 if the slave is attached.
+ * - -ENOTSUP if the operation is not supported.
+ * - -EBUSY if device is started.
+ * - -ENOMEM if the scheduler's slave list is full.
*/
int
rte_cryptodev_scheduler_slave_attach(uint8_t scheduler_id, uint8_t slave_id);
/**
- * Detach a attached crypto device to the scheduler
+ * Detach a crypto device from the scheduler
*
- * @param scheduler_id The target scheduler device ID
- * slave_id crypto device ID to be detached
+ * @param scheduler_id
+ * The target scheduler device ID
+ * @param slave_id
+ * crypto device ID to be detached
*
* @return
- * 0 if detaching successful, negative int if otherwise.
+ * - 0 if the slave is detached.
+ * - -ENOTSUP if the operation is not supported.
+ * - -EBUSY if device is started.
*/
int
rte_cryptodev_scheduler_slave_detach(uint8_t scheduler_id, uint8_t slave_id);
@@ -113,11 +140,15 @@ rte_cryptodev_scheduler_slave_detach(uint8_t scheduler_id, uint8_t slave_id);
/**
* Set the scheduling mode
*
- * @param scheduler_id The target scheduler device ID
- * mode The scheduling mode
+ * @param scheduler_id
+ * The target scheduler device ID
+ * @param mode
+ * The scheduling mode
*
* @return
- * 0 if attaching successful, negative integer if otherwise.
+ * - 0 if the mode is set.
+ * - -ENOTSUP if the operation is not supported.
+ * - -EBUSY if device is started.
*/
int
rte_cryptodev_scheduler_mode_set(uint8_t scheduler_id,
@@ -126,8 +157,12 @@ rte_cryptodev_scheduler_mode_set(uint8_t scheduler_id,
/**
* Get the current scheduling mode
*
- * @param scheduler_id The target scheduler device ID
- * mode Pointer to write the scheduling mode
+ * @param scheduler_id
+ * The target scheduler device ID
+ *
+ * @return mode
+ * - non-negative enumerate value: the scheduling mode
+ * - -ENOTSUP if the operation is not supported.
*/
enum rte_cryptodev_scheduler_mode
rte_cryptodev_scheduler_mode_get(uint8_t scheduler_id);
@@ -136,8 +171,10 @@ rte_cryptodev_scheduler_mode_get(uint8_t scheduler_id);
* @deprecated
* Set the scheduling mode
*
- * @param scheduler_id The target scheduler device ID
- * mode The scheduling mode
+ * @param scheduler_id
+ * The target scheduler device ID
+ * @param mode
+ * The scheduling mode
*
* @return
* 0 if attaching successful, negative integer if otherwise.
@@ -151,8 +188,12 @@ rte_crpytodev_scheduler_mode_set(uint8_t scheduler_id,
* @deprecated
* Get the current scheduling mode
*
- * @param scheduler_id The target scheduler device ID
- * mode Pointer to write the scheduling mode
+ * @param scheduler_id
+ * The target scheduler device ID
+ *
+ * @return
+ * If successful, returns the scheduling mode, negative integer
+ * otherwise
*/
__rte_deprecated
enum rte_cryptodev_scheduler_mode
@@ -161,13 +202,17 @@ rte_crpytodev_scheduler_mode_get(uint8_t scheduler_id);
/**
* Set the crypto ops reordering feature on/off
*
- * @param dev_id The target scheduler device ID
- * enable_reorder set the crypto op reordering feature
- * 0: disable reordering
- * 1: enable reordering
+ * @param scheduler_id
+ * The target scheduler device ID
+ * @param enable_reorder
+ * Set the crypto op reordering feature
+ * - 0: disable reordering
+ * - 1: enable reordering
*
* @return
- * 0 if setting successful, negative integer if otherwise.
+ * - 0 if the ordering is set.
+ * - -ENOTSUP if the operation is not supported.
+ * - -EBUSY if device is started.
*/
int
rte_cryptodev_scheduler_ordering_set(uint8_t scheduler_id,
@@ -176,12 +221,13 @@ rte_cryptodev_scheduler_ordering_set(uint8_t scheduler_id,
/**
* Get the current crypto ops reordering feature
*
- * @param dev_id The target scheduler device ID
+ * @param scheduler_id
+ * The target scheduler device ID
*
* @return
- * 0 if reordering is disabled
- * 1 if reordering is enabled
- * negative integer if otherwise.
+ * - 0 if reordering is disabled
+ * - 1 if reordering is enabled
+ * - -ENOTSUP if the operation is not supported.
*/
int
rte_cryptodev_scheduler_ordering_get(uint8_t scheduler_id);
@@ -192,15 +238,13 @@ rte_cryptodev_scheduler_ordering_get(uint8_t scheduler_id);
* @param scheduler_id
* The target scheduler device ID
* @param slaves
- * If successful, the function will write back
- * all slaves' device IDs to it. This
- * parameter SHALL either be an uint8_t array
- * of RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES
- * elements or NULL.
+ * If successful, the function will write back all slaves' device IDs to it.
+ * This parameter SHALL either be an uint8_t array of
+ * RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES elements or NULL.
*
* @return
* - non-negative number: the number of slaves attached
- * - negative integer if error occurs.
+ * - -ENOTSUP if the operation is not supported.
*/
int
rte_cryptodev_scheduler_slaves_get(uint8_t scheduler_id, uint8_t *slaves);
@@ -211,16 +255,21 @@ typedef uint16_t (*rte_cryptodev_scheduler_burst_enqueue_t)(void *qp_ctx,
typedef uint16_t (*rte_cryptodev_scheduler_burst_dequeue_t)(void *qp_ctx,
struct rte_crypto_op **ops, uint16_t nb_ops);
+/** The data structure associated with each mode of scheduler. */
struct rte_cryptodev_scheduler {
- const char *name;
- const char *description;
- enum rte_cryptodev_scheduler_mode mode;
+ const char *name; /**< scheduler name */
+ const char *description; /**< scheduler description */
+ enum rte_cryptodev_scheduler_mode mode; /**< scheduling mode */
+ /**< pointer to scheduler operation structure */
struct rte_cryptodev_scheduler_ops *ops;
};
+/** round-robin mode scheduler */
extern struct rte_cryptodev_scheduler *roundrobin_scheduler;
+/** packet-size based distribution mode scheduler */
extern struct rte_cryptodev_scheduler *pkt_size_based_distr_scheduler;
+/** fail-over mode scheduler */
extern struct rte_cryptodev_scheduler *failover_scheduler;
#ifdef __cplusplus
--
2.7.4
^ permalink raw reply [flat|nested] 2+ messages in thread
* Re: [dpdk-stable] [PATCH] crypto/scheduler: fix Doxygen comments
2017-04-11 16:15 [dpdk-stable] [PATCH] crypto/scheduler: fix Doxygen comments Fan Zhang
@ 2017-04-11 16:36 ` Mcnamara, John
0 siblings, 0 replies; 2+ messages in thread
From: Mcnamara, John @ 2017-04-11 16:36 UTC (permalink / raw)
To: Zhang, Roy Fan, dev; +Cc: De Lara Guarch, Pablo, stable
> -----Original Message-----
> From: Zhang, Roy Fan
> Sent: Tuesday, April 11, 2017 5:16 PM
> To: dev@dpdk.org
> Cc: De Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>;
> stable@dpdk.org; Mcnamara, John <john.mcnamara@intel.com>
> Subject: [PATCH] crypto/scheduler: fix Doxygen comments
>
> This patch adds the missing doxygen comments and updated inline comments
> to cryptodev scheduler
>
> Fixes: d58a3f312545 ("crypto/scheduler: add documentation")
>
> Signed-off-by: Fan Zhang <roy.fan.zhang@intel.com>
Tested-by: John McNamara <john.mcnamara@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2017-04-11 16:36 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-04-11 16:15 [dpdk-stable] [PATCH] crypto/scheduler: fix Doxygen comments Fan Zhang
2017-04-11 16:36 ` Mcnamara, John
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).