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")
Cc: stable@dpdk.org
Signed-off-by: Fan Zhang <roy.fan.zhang@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>

diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md
index a26846a..f5f1f19 100644 (file)
--- 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 (file)
--- 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 4d3de47..7a34d0a 100644 (file)
--- a/drivers/crypto/scheduler/rte_cryptodev_scheduler.h
+++ b/drivers/crypto/scheduler/rte_cryptodev_scheduler.h
@@ -34,37 +34,51 @@
 #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
+ * 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
 extern "C" {
 #endif
 
-/**< Maximum number of bonded devices per device */
+/** Maximum number of bonded devices per device */
 #ifndef RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES
 #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 */
+       /** Packet-size based distribution mode */
        CDEV_SCHED_MODE_PKT_SIZE_DISTR,
-       /** fail-over mode */
+       /** Fail-over mode */
        CDEV_SCHED_MODE_FAILOVER,
 
-       CDEV_SCHED_MODE_COUNT /* number of modes */
+       CDEV_SCHED_MODE_COUNT /**< number of modes */
 };
 
 #define RTE_CRYPTODEV_SCHEDULER_NAME_MAX_LEN   (64)
@@ -84,7 +98,7 @@ enum rte_cryptodev_schedule_option_type {
  * Threshold option structure
  */
 struct rte_cryptodev_scheduler_threshold_option {
-       uint32_t threshold;
+       uint32_t threshold;     /**< Threshold for packet-size mode */
 };
 
 struct rte_cryptodev_scheduler;
@@ -92,36 +106,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);
@@ -130,11 +157,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,
@@ -143,8 +174,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);
@@ -153,8 +188,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.
@@ -168,8 +205,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
@@ -178,13 +219,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,
@@ -193,12 +238,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);
@@ -209,15 +255,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 will 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);
@@ -225,7 +269,7 @@ rte_cryptodev_scheduler_slaves_get(uint8_t scheduler_id, uint8_t *slaves);
 /**
  * Set the mode specific option
  *
- * @param dev_id
+ * @param scheduler_id
  *   The target scheduler device ID
  * @param option_type
  *   The option type enumerate
@@ -244,7 +288,7 @@ rte_cryptodev_scheduler_option_set(uint8_t scheduler_id,
 /**
  * Set the mode specific option
  *
- * @param dev_id
+ * @param scheduler_id
  *   The target scheduler device ID
  * @param option_type
  *   The option type enumerate
@@ -266,16 +310,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