From dc8bd2f633a91a1507f01670b430079de87d0f1d Mon Sep 17 00:00:00 2001 From: Fan Zhang Date: Tue, 18 Apr 2017 12:33:15 +0100 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") Cc: stable@dpdk.org Signed-off-by: Fan Zhang Acked-by: John McNamara --- doc/api/doxy-api-index.md | 3 +- doc/api/doxy-api.conf | 1 + .../scheduler/rte_cryptodev_scheduler.h | 147 ++++++++++++------ 3 files changed, 101 insertions(+), 50 deletions(-) diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index a26846a7d1..f5f1f199f6 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 97fb551ee5..ca9194fe01 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 4d3de47020..7a34d0ab8d 100644 --- 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 -- 2.20.1