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 /** Round-robin scheduling mode string */
  62 #define SCHEDULER_MODE_NAME_ROUND_ROBIN         round-robin
  63 /** Packet-size based distribution scheduling mode string */
  64 #define SCHEDULER_MODE_NAME_PKT_SIZE_DISTR      packet-size-distr
  65 /** Fail-over scheduling mode string */
  66 #define SCHEDULER_MODE_NAME_FAIL_OVER           fail-over
  67
  68 /**
  69  * Crypto scheduler PMD operation modes
  70  */
  71 enum rte_cryptodev_scheduler_mode {
  72         CDEV_SCHED_MODE_NOT_SET = 0,
  73         /** User defined mode */
  74         CDEV_SCHED_MODE_USERDEFINED,
  75         /** Round-robin mode */
  76         CDEV_SCHED_MODE_ROUNDROBIN,
  77         /** Packet-size based distribution mode */
  78         CDEV_SCHED_MODE_PKT_SIZE_DISTR,
  79         /** Fail-over mode */
  80         CDEV_SCHED_MODE_FAILOVER,
  81
  82         CDEV_SCHED_MODE_COUNT /**< number of modes */
  83 };
  84
  85 #define RTE_CRYPTODEV_SCHEDULER_NAME_MAX_LEN    (64)
  86 #define RTE_CRYPTODEV_SCHEDULER_DESC_MAX_LEN    (256)
  87
  88 /**
  89  * Crypto scheduler option types
  90  */
  91 enum rte_cryptodev_schedule_option_type {
  92         CDEV_SCHED_OPTION_NOT_SET = 0,
  93         CDEV_SCHED_OPTION_THRESHOLD,
  94
  95         CDEV_SCHED_OPTION_COUNT
  96 };
  97
  98 /**
  99  * Threshold option structure
 100  */
 101 struct rte_cryptodev_scheduler_threshold_option {
 102         uint32_t threshold;     /**< Threshold for packet-size mode */
 103 };
 104
 105 struct rte_cryptodev_scheduler;
 106
 107 /**
 108  * Load a user defined scheduler
 109  *
 110  * @param scheduler_id
 111  *   The target scheduler device ID
 112  * @param scheduler
 113  *   Pointer to the user defined scheduler
 114  *
 115  * @return
 116  *   - 0 if the scheduler is successfully loaded
 117  *   - -ENOTSUP if the operation is not supported.
 118  *   - -EBUSY if device is started.
 119  *   - -EINVAL if input values are invalid.
 120  */
 121 int
 122 rte_cryptodev_scheduler_load_user_scheduler(uint8_t scheduler_id,
 123                 struct rte_cryptodev_scheduler *scheduler);
 124
 125 /**
 126  * Attach a crypto device to the scheduler
 127  *
 128  * @param scheduler_id
 129  *   The target scheduler device ID
 130  * @param slave_id
 131  *   Crypto device ID to be attached
 132  *
 133  * @return
 134  *   - 0 if the slave is attached.
 135  *   - -ENOTSUP if the operation is not supported.
 136  *   - -EBUSY if device is started.
 137  *   - -ENOMEM if the scheduler's slave list is full.
 138  */
 139 int
 140 rte_cryptodev_scheduler_slave_attach(uint8_t scheduler_id, uint8_t slave_id);
 141
 142 /**
 143  * Detach a crypto device from the scheduler
 144  *
 145  * @param scheduler_id
 146  *   The target scheduler device ID
 147  * @param slave_id
 148  *   Crypto device ID to be detached
 149  *
 150  * @return
 151  *   - 0 if the slave is detached.
 152  *   - -ENOTSUP if the operation is not supported.
 153  *   - -EBUSY if device is started.
 154  */
 155 int
 156 rte_cryptodev_scheduler_slave_detach(uint8_t scheduler_id, uint8_t slave_id);
 157
 158
 159 /**
 160  * Set the scheduling mode
 161  *
 162  * @param scheduler_id
 163  *   The target scheduler device ID
 164  * @param mode
 165  *   The scheduling mode
 166  *
 167  * @return
 168  *   - 0 if the mode is set.
 169  *   - -ENOTSUP if the operation is not supported.
 170  *   - -EBUSY if device is started.
 171  */
 172 int
 173 rte_cryptodev_scheduler_mode_set(uint8_t scheduler_id,
 174                 enum rte_cryptodev_scheduler_mode mode);
 175
 176 /**
 177  * Get the current scheduling mode
 178  *
 179  * @param scheduler_id
 180  *   The target scheduler device ID
 181  *
 182  * @return mode
 183  *   - non-negative enumerate value: the scheduling mode
 184  *   - -ENOTSUP if the operation is not supported.
 185  */
 186 enum rte_cryptodev_scheduler_mode
 187 rte_cryptodev_scheduler_mode_get(uint8_t scheduler_id);
 188
 189 /**
 190  * @deprecated
 191  * Set the scheduling mode
 192  *
 193  * @param scheduler_id
 194  *   The target scheduler device ID
 195  * @param mode
 196  *   The scheduling mode
 197  *
 198  * @return
 199  *      0 if attaching successful, negative integer if otherwise.
 200  */
 201 __rte_deprecated
 202 int
 203 rte_crpytodev_scheduler_mode_set(uint8_t scheduler_id,
 204                 enum rte_cryptodev_scheduler_mode mode);
 205
 206 /**
 207  * @deprecated
 208  * Get the current scheduling mode
 209  *
 210  * @param scheduler_id
 211  *   The target scheduler device ID
 212  *
 213  * @return
 214  *      If successful, returns the scheduling mode, negative integer
 215  *      otherwise
 216  */
 217 __rte_deprecated
 218 enum rte_cryptodev_scheduler_mode
 219 rte_crpytodev_scheduler_mode_get(uint8_t scheduler_id);
 220
 221 /**
 222  * Set the crypto ops reordering feature on/off
 223  *
 224  * @param scheduler_id
 225  *   The target scheduler device ID
 226  * @param enable_reorder
 227  *   Set the crypto op reordering feature
 228  *   - 0: disable reordering
 229  *   - 1: enable reordering
 230  *
 231  * @return
 232  *   - 0 if the ordering is set.
 233  *   - -ENOTSUP if the operation is not supported.
 234  *   - -EBUSY if device is started.
 235  */
 236 int
 237 rte_cryptodev_scheduler_ordering_set(uint8_t scheduler_id,
 238                 uint32_t enable_reorder);
 239
 240 /**
 241  * Get the current crypto ops reordering feature
 242  *
 243  * @param scheduler_id
 244  *   The target scheduler device ID
 245  *
 246  * @return
 247  *   - 0 if reordering is disabled
 248  *   - 1 if reordering is enabled
 249  *   - -ENOTSUP if the operation is not supported.
 250  */
 251 int
 252 rte_cryptodev_scheduler_ordering_get(uint8_t scheduler_id);
 253
 254 /**
 255  * Get the the attached slaves' count and/or ID
 256  *
 257  * @param scheduler_id
 258  *   The target scheduler device ID
 259  * @param slaves
 260  *   If successful, the function will write back all slaves' device IDs to it.
 261  *   This parameter will either be an uint8_t array of
 262  *   RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES elements or NULL.
 263  *
 264  * @return
 265  *   - non-negative number: the number of slaves attached
 266  *   - -ENOTSUP if the operation is not supported.
 267  */
 268 int
 269 rte_cryptodev_scheduler_slaves_get(uint8_t scheduler_id, uint8_t *slaves);
 270
 271 /**
 272  * Set the mode specific option
 273  *
 274  * @param scheduler_id
 275  *   The target scheduler device ID
 276  * @param option_type
 277  *   The option type enumerate
 278  * @param option
 279  *   The specific mode's option structure
 280  *
 281  * @return
 282  *   - 0 if successful
 283  *   - negative integer if otherwise.
 284  */
 285 int
 286 rte_cryptodev_scheduler_option_set(uint8_t scheduler_id,
 287                 enum rte_cryptodev_schedule_option_type option_type,
 288                 void *option);
 289
 290 /**
 291  * Set the mode specific option
 292  *
 293  * @param scheduler_id
 294  *   The target scheduler device ID
 295  * @param option_type
 296  *   The option type enumerate
 297  * @param option
 298  *   If successful, the function will write back the current
 299  *
 300  * @return
 301  *   - 0 if successful
 302  *   - negative integer if otherwise.
 303  */
 304 int
 305 rte_cryptodev_scheduler_option_get(uint8_t scheduler_id,
 306                 enum rte_cryptodev_schedule_option_type option_type,
 307                 void *option);
 308
 309 typedef uint16_t (*rte_cryptodev_scheduler_burst_enqueue_t)(void *qp_ctx,
 310                 struct rte_crypto_op **ops, uint16_t nb_ops);
 311
 312 typedef uint16_t (*rte_cryptodev_scheduler_burst_dequeue_t)(void *qp_ctx,
 313                 struct rte_crypto_op **ops, uint16_t nb_ops);
 314
 315 /** The data structure associated with each mode of scheduler. */
 316 struct rte_cryptodev_scheduler {
 317         const char *name;                        /**< Scheduler name */
 318         const char *description;                 /**< Scheduler description */
 319         enum rte_cryptodev_scheduler_mode mode;  /**< Scheduling mode */
 320
 321         /** Pointer to scheduler operation structure */
 322         struct rte_cryptodev_scheduler_ops *ops;
 323 };
 324
 325 /** Round-robin mode scheduler */
 326 extern struct rte_cryptodev_scheduler *roundrobin_scheduler;
 327 /** Packet-size based distribution mode scheduler */
 328 extern struct rte_cryptodev_scheduler *pkt_size_based_distr_scheduler;
 329 /** Fail-over mode scheduler */
 330 extern struct rte_cryptodev_scheduler *failover_scheduler;
 331
 332 #ifdef __cplusplus
 333 }
 334 #endif
 335 #endif /* _RTE_CRYPTO_SCHEDULER_H */