From patchwork Tue Apr 11 16:15:45 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Fan Zhang X-Patchwork-Id: 23568 Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [IPv6:::1]) by dpdk.org (Postfix) with ESMTP id 89B38D326; Tue, 11 Apr 2017 18:13:59 +0200 (CEST) Received: from mga06.intel.com (mga06.intel.com [134.134.136.31]) by dpdk.org (Postfix) with ESMTP id 8D5F1D2B6; Tue, 11 Apr 2017 18:13:57 +0200 (CEST) Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga104.jf.intel.com with ESMTP; 11 Apr 2017 09:13:56 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.37,186,1488873600"; d="scan'208";a="954819025" Received: from silpixa00381633.ir.intel.com (HELO silpixa00381633.ger.corp.intel.com) ([10.237.222.114]) by orsmga003.jf.intel.com with ESMTP; 11 Apr 2017 09:13:55 -0700 From: Fan Zhang To: dev@dpdk.org Cc: pablo.de.lara.guarch@intel.com, stable@dpdk.org, john.mcnamara@intel.com Date: Tue, 11 Apr 2017 17:15:45 +0100 Message-Id: <1491927345-30463-1-git-send-email-roy.fan.zhang@intel.com> X-Mailer: git-send-email 2.7.4 Subject: [dpdk-dev] [PATCH] crypto/scheduler: fix Doxygen comments X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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 Tested-by: John McNamara Acked-by: John McNamara --- 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