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  */
 120 int
 121 rte_cryptodev_scheduler_load_user_scheduler(uint8_t scheduler_id,
 122                 struct rte_cryptodev_scheduler *scheduler);
 123
 124 /**
 125  * Attach a crypto device to the scheduler
 126  *
 127  * @param scheduler_id
 128  *   The target scheduler device ID
 129  * @param slave_id
 130  *   Crypto device ID to be attached
 131  *
 132  * @return
 133  *   - 0 if the slave is attached.
 134  *   - -ENOTSUP if the operation is not supported.
 135  *   - -EBUSY if device is started.
 136  *   - -ENOMEM if the scheduler's slave list is full.
 137  */
 138 int
 139 rte_cryptodev_scheduler_slave_attach(uint8_t scheduler_id, uint8_t slave_id);
 140
 141 /**
 142  * Detach a crypto device from the scheduler
 143  *
 144  * @param scheduler_id
 145  *   The target scheduler device ID
 146  * @param slave_id
 147  *   Crypto device ID to be detached
 148  *
 149  * @return
 150  *   - 0 if the slave is detached.
 151  *   - -ENOTSUP if the operation is not supported.
 152  *   - -EBUSY if device is started.
 153  */
 154 int
 155 rte_cryptodev_scheduler_slave_detach(uint8_t scheduler_id, uint8_t slave_id);
 156
 157
 158 /**
 159  * Set the scheduling mode
 160  *
 161  * @param scheduler_id
 162  *   The target scheduler device ID
 163  * @param mode
 164  *   The scheduling mode
 165  *
 166  * @return
 167  *   - 0 if the mode is set.
 168  *   - -ENOTSUP if the operation is not supported.
 169  *   - -EBUSY if device is started.
 170  */
 171 int
 172 rte_cryptodev_scheduler_mode_set(uint8_t scheduler_id,
 173                 enum rte_cryptodev_scheduler_mode mode);
 174
 175 /**
 176  * Get the current scheduling mode
 177  *
 178  * @param scheduler_id
 179  *   The target scheduler device ID
 180  *
 181  * @return mode
 182  *   - non-negative enumerate value: the scheduling mode
 183  *   - -ENOTSUP if the operation is not supported.
 184  */
 185 enum rte_cryptodev_scheduler_mode
 186 rte_cryptodev_scheduler_mode_get(uint8_t scheduler_id);
 187
 188 /**
 189  * @deprecated
 190  * Set the scheduling mode
 191  *
 192  * @param scheduler_id
 193  *   The target scheduler device ID
 194  * @param mode
 195  *   The scheduling mode
 196  *
 197  * @return
 198  *      0 if attaching successful, negative integer if otherwise.
 199  */
 200 __rte_deprecated
 201 int
 202 rte_crpytodev_scheduler_mode_set(uint8_t scheduler_id,
 203                 enum rte_cryptodev_scheduler_mode mode);
 204
 205 /**
 206  * @deprecated
 207  * Get the current scheduling mode
 208  *
 209  * @param scheduler_id
 210  *   The target scheduler device ID
 211  *
 212  * @return
 213  *      If successful, returns the scheduling mode, negative integer
 214  *      otherwise
 215  */
 216 __rte_deprecated
 217 enum rte_cryptodev_scheduler_mode
 218 rte_crpytodev_scheduler_mode_get(uint8_t scheduler_id);
 219
 220 /**
 221  * Set the crypto ops reordering feature on/off
 222  *
 223  * @param scheduler_id
 224  *   The target scheduler device ID
 225  * @param enable_reorder
 226  *   Set the crypto op reordering feature
 227  *   - 0: disable reordering
 228  *   - 1: enable reordering
 229  *
 230  * @return
 231  *   - 0 if the ordering is set.
 232  *   - -ENOTSUP if the operation is not supported.
 233  *   - -EBUSY if device is started.
 234  */
 235 int
 236 rte_cryptodev_scheduler_ordering_set(uint8_t scheduler_id,
 237                 uint32_t enable_reorder);
 238
 239 /**
 240  * Get the current crypto ops reordering feature
 241  *
 242  * @param scheduler_id
 243  *   The target scheduler device ID
 244  *
 245  * @return
 246  *   - 0 if reordering is disabled
 247  *   - 1 if reordering is enabled
 248  *   - -ENOTSUP if the operation is not supported.
 249  */
 250 int
 251 rte_cryptodev_scheduler_ordering_get(uint8_t scheduler_id);
 252
 253 /**
 254  * Get the the attached slaves' count and/or ID
 255  *
 256  * @param scheduler_id
 257  *   The target scheduler device ID
 258  * @param slaves
 259  *   If successful, the function will write back all slaves' device IDs to it.
 260  *   This parameter will either be an uint8_t array of
 261  *   RTE_CRYPTODEV_SCHEDULER_MAX_NB_SLAVES elements or NULL.
 262  *
 263  * @return
 264  *   - non-negative number: the number of slaves attached
 265  *   - -ENOTSUP if the operation is not supported.
 266  */
 267 int
 268 rte_cryptodev_scheduler_slaves_get(uint8_t scheduler_id, uint8_t *slaves);
 269
 270 /**
 271  * Set the mode specific option
 272  *
 273  * @param scheduler_id
 274  *   The target scheduler device ID
 275  * @param option_type
 276  *   The option type enumerate
 277  * @param option
 278  *   The specific mode's option structure
 279  *
 280  * @return
 281  *   - 0 if successful
 282  *   - negative integer if otherwise.
 283  */
 284 int
 285 rte_cryptodev_scheduler_option_set(uint8_t scheduler_id,
 286                 enum rte_cryptodev_schedule_option_type option_type,
 287                 void *option);
 288
 289 /**
 290  * Set the mode specific option
 291  *
 292  * @param scheduler_id
 293  *   The target scheduler device ID
 294  * @param option_type
 295  *   The option type enumerate
 296  * @param option
 297  *   If successful, the function will write back the current
 298  *
 299  * @return
 300  *   - 0 if successful
 301  *   - negative integer if otherwise.
 302  */
 303 int
 304 rte_cryptodev_scheduler_option_get(uint8_t scheduler_id,
 305                 enum rte_cryptodev_schedule_option_type option_type,
 306                 void *option);
 307
 308 typedef uint16_t (*rte_cryptodev_scheduler_burst_enqueue_t)(void *qp_ctx,
 309                 struct rte_crypto_op **ops, uint16_t nb_ops);
 310
 311 typedef uint16_t (*rte_cryptodev_scheduler_burst_dequeue_t)(void *qp_ctx,
 312                 struct rte_crypto_op **ops, uint16_t nb_ops);
 313
 314 /** The data structure associated with each mode of scheduler. */
 315 struct rte_cryptodev_scheduler {
 316         const char *name;                        /**< Scheduler name */
 317         const char *description;                 /**< Scheduler description */
 318         enum rte_cryptodev_scheduler_mode mode;  /**< Scheduling mode */
 319
 320         /** Pointer to scheduler operation structure */
 321         struct rte_cryptodev_scheduler_ops *ops;
 322 };
 323
 324 /** Round-robin mode scheduler */
 325 extern struct rte_cryptodev_scheduler *roundrobin_scheduler;
 326 /** Packet-size based distribution mode scheduler */
 327 extern struct rte_cryptodev_scheduler *pkt_size_based_distr_scheduler;
 328 /** Fail-over mode scheduler */
 329 extern struct rte_cryptodev_scheduler *failover_scheduler;
 330
 331 #ifdef __cplusplus
 332 }
 333 #endif
 334 #endif /* _RTE_CRYPTO_SCHEDULER_H */