drivers/crypto/scheduler/rte_cryptodev_scheduler.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2017 Intel Corporation. All rights reserved.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 #ifndef _RTE_CRYPTO_SCHEDULER_H
  35 #define _RTE_CRYPTO_SCHEDULER_H
  36
  37 /**
  38  * @file rte_cryptodev_scheduler.h
  39  *
  40  * RTE Cryptodev Scheduler Device
  41  *
  42  * The RTE Cryptodev Scheduler Device allows the aggregation of multiple (slave)
  43  * Cryptodevs into a single logical crypto device, and the scheduling the
  44  * crypto operations to the slaves based on the mode of the specified mode of
  45  * operation specified and supported. This implementation supports 3 modes of
  46  * operation: round robin, packet-size based, and fail-over.
  47  */
  48
  49 #include <stdint.h>
  50 #include "rte_cryptodev_scheduler_operations.h"
  51
  52 #ifdef __cplusplus
  53 extern "C" {
  54 #endif
  55
  56 /** Maximum number of bonded devices per device */
  57 #ifndef RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES
  58 #define RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES   (8)
  59 #endif
  60
  61 /** Maximum number of multi-core worker cores */
  62 #define RTE_CRYPTODEV_SCHEDULER_MAX_NB_WORKER_CORES     (64)
  63
  64 /** Round-robin scheduling mode string */
  65 #define SCHEDULER_MODE_NAME_ROUND_ROBIN         round-robin
  66 /** Packet-size based distribution scheduling mode string */
  67 #define SCHEDULER_MODE_NAME_PKT_SIZE_DISTR      packet-size-distr
  68 /** Fail-over scheduling mode string */
  69 #define SCHEDULER_MODE_NAME_FAIL_OVER           fail-over
  70 /** multi-core scheduling mode string */
  71 #define SCHEDULER_MODE_NAME_MULTI_CORE          multi-core
  72
  73 /**
  74  * Crypto scheduler PMD operation modes
  75  */
  76 enum rte_cryptodev_scheduler_mode {
  77         CDEV_SCHED_MODE_NOT_SET = 0,
  78         /** User defined mode */
  79         CDEV_SCHED_MODE_USERDEFINED,
  80         /** Round-robin mode */
  81         CDEV_SCHED_MODE_ROUNDROBIN,
  82         /** Packet-size based distribution mode */
  83         CDEV_SCHED_MODE_PKT_SIZE_DISTR,
  84         /** Fail-over mode */
  85         CDEV_SCHED_MODE_FAILOVER,
  86         /** multi-core mode */
  87         CDEV_SCHED_MODE_MULTICORE,
  88
  89         CDEV_SCHED_MODE_COUNT /**< number of modes */
  90 };
  91
  92 #define RTE_CRYPTODEV_SCHEDULER_NAME_MAX_LEN    (64)
  93 #define RTE_CRYPTODEV_SCHEDULER_DESC_MAX_LEN    (256)
  94
  95 /**
  96  * Crypto scheduler option types
  97  */
  98 enum rte_cryptodev_schedule_option_type {
  99         CDEV_SCHED_OPTION_NOT_SET = 0,
 100         CDEV_SCHED_OPTION_THRESHOLD,
 101
 102         CDEV_SCHED_OPTION_COUNT
 103 };
 104
 105 /**
 106  * Threshold option structure
 107  */
 108 struct rte_cryptodev_scheduler_threshold_option {
 109         uint32_t threshold;     /**< Threshold for packet-size mode */
 110 };
 111
 112 struct rte_cryptodev_scheduler;
 113
 114 /**
 115  * Load a user defined scheduler
 116  *
 117  * @param scheduler_id
 118  *   The target scheduler device ID
 119  * @param scheduler
 120  *   Pointer to the user defined scheduler
 121  *
 122  * @return
 123  *   - 0 if the scheduler is successfully loaded
 124  *   - -ENOTSUP if the operation is not supported.
 125  *   - -EBUSY if device is started.
 126  *   - -EINVAL if input values are invalid.
 127  */
 128 int
 129 rte_cryptodev_scheduler_load_user_scheduler(uint8_t scheduler_id,
 130                 struct rte_cryptodev_scheduler *scheduler);
 131
 132 /**
 133  * Attach a crypto device to the scheduler
 134  *
 135  * @param scheduler_id
 136  *   The target scheduler device ID
 137  * @param slave_id
 138  *   Crypto device ID to be attached
 139  *
 140  * @return
 141  *   - 0 if the slave is attached.
 142  *   - -ENOTSUP if the operation is not supported.
 143  *   - -EBUSY if device is started.
 144  *   - -ENOMEM if the scheduler's slave list is full.
 145  */
 146 int
 147 rte_cryptodev_scheduler_slave_attach(uint8_t scheduler_id, uint8_t slave_id);
 148
 149 /**
 150  * Detach a crypto device from the scheduler
 151  *
 152  * @param scheduler_id
 153  *   The target scheduler device ID
 154  * @param slave_id
 155  *   Crypto device ID to be detached
 156  *
 157  * @return
 158  *   - 0 if the slave is detached.
 159  *   - -ENOTSUP if the operation is not supported.
 160  *   - -EBUSY if device is started.
 161  */
 162 int
 163 rte_cryptodev_scheduler_slave_detach(uint8_t scheduler_id, uint8_t slave_id);
 164
 165
 166 /**
 167  * Set the scheduling mode
 168  *
 169  * @param scheduler_id
 170  *   The target scheduler device ID
 171  * @param mode
 172  *   The scheduling mode
 173  *
 174  * @return
 175  *   - 0 if the mode is set.
 176  *   - -ENOTSUP if the operation is not supported.
 177  *   - -EBUSY if device is started.
 178  */
 179 int
 180 rte_cryptodev_scheduler_mode_set(uint8_t scheduler_id,
 181                 enum rte_cryptodev_scheduler_mode mode);
 182
 183 /**
 184  * Get the current scheduling mode
 185  *
 186  * @param scheduler_id
 187  *   The target scheduler device ID
 188  *
 189  * @return mode
 190  *   - non-negative enumerate value: the scheduling mode
 191  *   - -ENOTSUP if the operation is not supported.
 192  */
 193 enum rte_cryptodev_scheduler_mode
 194 rte_cryptodev_scheduler_mode_get(uint8_t scheduler_id);
 195
 196 /**
 197  * Set the crypto ops reordering feature on/off
 198  *
 199  * @param scheduler_id
 200  *   The target scheduler device ID
 201  * @param enable_reorder
 202  *   Set the crypto op reordering feature
 203  *   - 0: disable reordering
 204  *   - 1: enable reordering
 205  *
 206  * @return
 207  *   - 0 if the ordering is set.
 208  *   - -ENOTSUP if the operation is not supported.
 209  *   - -EBUSY if device is started.
 210  */
 211 int
 212 rte_cryptodev_scheduler_ordering_set(uint8_t scheduler_id,
 213                 uint32_t enable_reorder);
 214
 215 /**
 216  * Get the current crypto ops reordering feature
 217  *
 218  * @param scheduler_id
 219  *   The target scheduler device ID
 220  *
 221  * @return
 222  *   - 0 if reordering is disabled
 223  *   - 1 if reordering is enabled
 224  *   - -ENOTSUP if the operation is not supported.
 225  */
 226 int
 227 rte_cryptodev_scheduler_ordering_get(uint8_t scheduler_id);
 228
 229 /**
 230  * Get the the attached slaves' count and/or ID
 231  *
 232  * @param scheduler_id
 233  *   The target scheduler device ID
 234  * @param slaves
 235  *   If successful, the function will write back all slaves' device IDs to it.
 236  *   This parameter will either be an uint8_t array of
 237  *   RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES elements or NULL.
 238  *
 239  * @return
 240  *   - non-negative number: the number of slaves attached
 241  *   - -ENOTSUP if the operation is not supported.
 242  */
 243 int
 244 rte_cryptodev_scheduler_slaves_get(uint8_t scheduler_id, uint8_t *slaves);
 245
 246 /**
 247  * Set the mode specific option
 248  *
 249  * @param scheduler_id
 250  *   The target scheduler device ID
 251  * @param option_type
 252  *   The option type enumerate
 253  * @param option
 254  *   The specific mode's option structure
 255  *
 256  * @return
 257  *   - 0 if successful
 258  *   - negative integer if otherwise.
 259  */
 260 int
 261 rte_cryptodev_scheduler_option_set(uint8_t scheduler_id,
 262                 enum rte_cryptodev_schedule_option_type option_type,
 263                 void *option);
 264
 265 /**
 266  * Set the mode specific option
 267  *
 268  * @param scheduler_id
 269  *   The target scheduler device ID
 270  * @param option_type
 271  *   The option type enumerate
 272  * @param option
 273  *   If successful, the function will write back the current
 274  *
 275  * @return
 276  *   - 0 if successful
 277  *   - negative integer if otherwise.
 278  */
 279 int
 280 rte_cryptodev_scheduler_option_get(uint8_t scheduler_id,
 281                 enum rte_cryptodev_schedule_option_type option_type,
 282                 void *option);
 283
 284 typedef uint16_t (*rte_cryptodev_scheduler_burst_enqueue_t)(void *qp_ctx,
 285                 struct rte_crypto_op **ops, uint16_t nb_ops);
 286
 287 typedef uint16_t (*rte_cryptodev_scheduler_burst_dequeue_t)(void *qp_ctx,
 288                 struct rte_crypto_op **ops, uint16_t nb_ops);
 289
 290 /** The data structure associated with each mode of scheduler. */
 291 struct rte_cryptodev_scheduler {
 292         const char *name;                        /**< Scheduler name */
 293         const char *description;                 /**< Scheduler description */
 294         enum rte_cryptodev_scheduler_mode mode;  /**< Scheduling mode */
 295
 296         /** Pointer to scheduler operation structure */
 297         struct rte_cryptodev_scheduler_ops *ops;
 298 };
 299
 300 /** Round-robin mode scheduler */
 301 extern struct rte_cryptodev_scheduler *roundrobin_scheduler;
 302 /** Packet-size based distribution mode scheduler */
 303 extern struct rte_cryptodev_scheduler *pkt_size_based_distr_scheduler;
 304 /** Fail-over mode scheduler */
 305 extern struct rte_cryptodev_scheduler *failover_scheduler;
 306 /** multi-core mode scheduler */
 307 extern struct rte_cryptodev_scheduler *multicore_scheduler;
 308
 309 #ifdef __cplusplus
 310 }
 311 #endif
 312 #endif /* _RTE_CRYPTO_SCHEDULER_H */