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