pci: use SPDX tags in 6WIND copyrighted files
[dpdk.git] / lib / librte_cryptodev / rte_cryptodev_pmd.h
1 /*-
2  *
3  *   Copyright(c) 2015-2016 Intel Corporation. All rights reserved.
4  *
5  *   Redistribution and use in source and binary forms, with or without
6  *   modification, are permitted provided that the following conditions
7  *   are met:
8  *
9  *     * Redistributions of source code must retain the above copyright
10  *       notice, this list of conditions and the following disclaimer.
11  *     * Redistributions in binary form must reproduce the above copyright
12  *       notice, this list of conditions and the following disclaimer in
13  *       the documentation and/or other materials provided with the
14  *       distribution.
15  *     * Neither the name of Intel Corporation nor the names of its
16  *       contributors may be used to endorse or promote products derived
17  *       from this software without specific prior written permission.
18  *
19  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30  */
31
32 #ifndef _RTE_CRYPTODEV_PMD_H_
33 #define _RTE_CRYPTODEV_PMD_H_
34
35 /** @file
36  * RTE Crypto PMD APIs
37  *
38  * @note
39  * These API are from crypto PMD only and user applications should not call
40  * them directly.
41  */
42
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46
47 #include <string.h>
48
49 #include <rte_config.h>
50 #include <rte_dev.h>
51 #include <rte_malloc.h>
52 #include <rte_mbuf.h>
53 #include <rte_mempool.h>
54 #include <rte_log.h>
55 #include <rte_common.h>
56
57 #include "rte_crypto.h"
58 #include "rte_cryptodev.h"
59
60
61 #define RTE_CRYPTODEV_PMD_DEFAULT_MAX_NB_QUEUE_PAIRS    8
62 #define RTE_CRYPTODEV_PMD_DEFAULT_MAX_NB_SESSIONS       2048
63
64 #define RTE_CRYPTODEV_PMD_NAME_ARG                      ("name")
65 #define RTE_CRYPTODEV_PMD_MAX_NB_QP_ARG                 ("max_nb_queue_pairs")
66 #define RTE_CRYPTODEV_PMD_MAX_NB_SESS_ARG               ("max_nb_sessions")
67 #define RTE_CRYPTODEV_PMD_SOCKET_ID_ARG                 ("socket_id")
68
69
70 static const char * const cryptodev_pmd_valid_params[] = {
71         RTE_CRYPTODEV_PMD_NAME_ARG,
72         RTE_CRYPTODEV_PMD_MAX_NB_QP_ARG,
73         RTE_CRYPTODEV_PMD_MAX_NB_SESS_ARG,
74         RTE_CRYPTODEV_PMD_SOCKET_ID_ARG
75 };
76
77 /**
78  * @internal
79  * Initialisation parameters for crypto devices
80  */
81 struct rte_cryptodev_pmd_init_params {
82         char name[RTE_CRYPTODEV_NAME_MAX_LEN];
83         size_t private_data_size;
84         int socket_id;
85         unsigned int max_nb_queue_pairs;
86         unsigned int max_nb_sessions;
87 };
88
89 /** Global structure used for maintaining state of allocated crypto devices */
90 struct rte_cryptodev_global {
91         struct rte_cryptodev *devs;     /**< Device information array */
92         struct rte_cryptodev_data *data[RTE_CRYPTO_MAX_DEVS];
93         /**< Device private data */
94         uint8_t nb_devs;                /**< Number of devices found */
95         uint8_t max_devs;               /**< Max number of devices */
96 };
97
98 /* Cryptodev driver, containing the driver ID */
99 struct cryptodev_driver {
100         TAILQ_ENTRY(cryptodev_driver) next; /**< Next in list. */
101         const struct rte_driver *driver;
102         uint8_t id;
103 };
104
105 /** pointer to global crypto devices data structure. */
106 extern struct rte_cryptodev_global *rte_cryptodev_globals;
107
108 /**
109  * Get the rte_cryptodev structure device pointer for the device. Assumes a
110  * valid device index.
111  *
112  * @param       dev_id  Device ID value to select the device structure.
113  *
114  * @return
115  *   - The rte_cryptodev structure pointer for the given device ID.
116  */
117 struct rte_cryptodev *
118 rte_cryptodev_pmd_get_dev(uint8_t dev_id);
119
120 /**
121  * Get the rte_cryptodev structure device pointer for the named device.
122  *
123  * @param       name    device name to select the device structure.
124  *
125  * @return
126  *   - The rte_cryptodev structure pointer for the given device ID.
127  */
128 struct rte_cryptodev *
129 rte_cryptodev_pmd_get_named_dev(const char *name);
130
131 /**
132  * Validate if the crypto device index is valid attached crypto device.
133  *
134  * @param       dev_id  Crypto device index.
135  *
136  * @return
137  *   - If the device index is valid (1) or not (0).
138  */
139 unsigned int
140 rte_cryptodev_pmd_is_valid_dev(uint8_t dev_id);
141
142 /**
143  * The pool of rte_cryptodev structures.
144  */
145 extern struct rte_cryptodev *rte_cryptodevs;
146
147
148 /**
149  * Definitions of all functions exported by a driver through the
150  * the generic structure of type *crypto_dev_ops* supplied in the
151  * *rte_cryptodev* structure associated with a device.
152  */
153
154 /**
155  *      Function used to configure device.
156  *
157  * @param       dev     Crypto device pointer
158  *              config  Crypto device configurations
159  *
160  * @return      Returns 0 on success
161  */
162 typedef int (*cryptodev_configure_t)(struct rte_cryptodev *dev,
163                 struct rte_cryptodev_config *config);
164
165 /**
166  * Function used to start a configured device.
167  *
168  * @param       dev     Crypto device pointer
169  *
170  * @return      Returns 0 on success
171  */
172 typedef int (*cryptodev_start_t)(struct rte_cryptodev *dev);
173
174 /**
175  * Function used to stop a configured device.
176  *
177  * @param       dev     Crypto device pointer
178  */
179 typedef void (*cryptodev_stop_t)(struct rte_cryptodev *dev);
180
181 /**
182  * Function used to close a configured device.
183  *
184  * @param       dev     Crypto device pointer
185  * @return
186  * - 0 on success.
187  * - EAGAIN if can't close as device is busy
188  */
189 typedef int (*cryptodev_close_t)(struct rte_cryptodev *dev);
190
191
192 /**
193  * Function used to get statistics of a device.
194  *
195  * @param       dev     Crypto device pointer
196  * @param       stats   Pointer to crypto device stats structure to populate
197  */
198 typedef void (*cryptodev_stats_get_t)(struct rte_cryptodev *dev,
199                                 struct rte_cryptodev_stats *stats);
200
201
202 /**
203  * Function used to reset statistics of a device.
204  *
205  * @param       dev     Crypto device pointer
206  */
207 typedef void (*cryptodev_stats_reset_t)(struct rte_cryptodev *dev);
208
209
210 /**
211  * Function used to get specific information of a device.
212  *
213  * @param       dev     Crypto device pointer
214  */
215 typedef void (*cryptodev_info_get_t)(struct rte_cryptodev *dev,
216                                 struct rte_cryptodev_info *dev_info);
217
218 /**
219  * Start queue pair of a device.
220  *
221  * @param       dev     Crypto device pointer
222  * @param       qp_id   Queue Pair Index
223  *
224  * @return      Returns 0 on success.
225  */
226 typedef int (*cryptodev_queue_pair_start_t)(struct rte_cryptodev *dev,
227                                 uint16_t qp_id);
228
229 /**
230  * Stop queue pair of a device.
231  *
232  * @param       dev     Crypto device pointer
233  * @param       qp_id   Queue Pair Index
234  *
235  * @return      Returns 0 on success.
236  */
237 typedef int (*cryptodev_queue_pair_stop_t)(struct rte_cryptodev *dev,
238                                 uint16_t qp_id);
239
240 /**
241  * Setup a queue pair for a device.
242  *
243  * @param       dev             Crypto device pointer
244  * @param       qp_id           Queue Pair Index
245  * @param       qp_conf         Queue configuration structure
246  * @param       socket_id       Socket Index
247  * @param       session_pool    Pointer to device session mempool
248  *
249  * @return      Returns 0 on success.
250  */
251 typedef int (*cryptodev_queue_pair_setup_t)(struct rte_cryptodev *dev,
252                 uint16_t qp_id, const struct rte_cryptodev_qp_conf *qp_conf,
253                 int socket_id, struct rte_mempool *session_pool);
254
255 /**
256  * Release memory resources allocated by given queue pair.
257  *
258  * @param       dev     Crypto device pointer
259  * @param       qp_id   Queue Pair Index
260  *
261  * @return
262  * - 0 on success.
263  * - EAGAIN if can't close as device is busy
264  */
265 typedef int (*cryptodev_queue_pair_release_t)(struct rte_cryptodev *dev,
266                 uint16_t qp_id);
267
268 /**
269  * Get number of available queue pairs of a device.
270  *
271  * @param       dev     Crypto device pointer
272  *
273  * @return      Returns number of queue pairs on success.
274  */
275 typedef uint32_t (*cryptodev_queue_pair_count_t)(struct rte_cryptodev *dev);
276
277 /**
278  * Create a session mempool to allocate sessions from
279  *
280  * @param       dev             Crypto device pointer
281  * @param       nb_objs         number of sessions objects in mempool
282  * @param       obj_cache       l-core object cache size, see *rte_ring_create*
283  * @param       socket_id       Socket Id to allocate  mempool on.
284  *
285  * @return
286  * - On success returns a pointer to a rte_mempool
287  * - On failure returns a NULL pointer
288  */
289 typedef int (*cryptodev_sym_create_session_pool_t)(
290                 struct rte_cryptodev *dev, unsigned nb_objs,
291                 unsigned obj_cache_size, int socket_id);
292
293
294 /**
295  * Get the size of a cryptodev session
296  *
297  * @param       dev             Crypto device pointer
298  *
299  * @return
300  *  - On success returns the size of the session structure for device
301  *  - On failure returns 0
302  */
303 typedef unsigned (*cryptodev_sym_get_session_private_size_t)(
304                 struct rte_cryptodev *dev);
305
306 /**
307  * Configure a Crypto session on a device.
308  *
309  * @param       dev             Crypto device pointer
310  * @param       xform           Single or chain of crypto xforms
311  * @param       priv_sess       Pointer to cryptodev's private session structure
312  * @param       mp              Mempool where the private session is allocated
313  *
314  * @return
315  *  - Returns 0 if private session structure have been created successfully.
316  *  - Returns -EINVAL if input parameters are invalid.
317  *  - Returns -ENOTSUP if crypto device does not support the crypto transform.
318  *  - Returns -ENOMEM if the private session could not be allocated.
319  */
320 typedef int (*cryptodev_sym_configure_session_t)(struct rte_cryptodev *dev,
321                 struct rte_crypto_sym_xform *xform,
322                 struct rte_cryptodev_sym_session *session,
323                 struct rte_mempool *mp);
324
325 /**
326  * Free driver private session data.
327  *
328  * @param       dev             Crypto device pointer
329  * @param       sess            Cryptodev session structure
330  */
331 typedef void (*cryptodev_sym_free_session_t)(struct rte_cryptodev *dev,
332                 struct rte_cryptodev_sym_session *sess);
333
334 /**
335  * Optional API for drivers to attach sessions with queue pair.
336  * @param       dev             Crypto device pointer
337  * @param       qp_id           queue pair id for attaching session
338  * @param       priv_sess       Pointer to cryptodev's private session structure
339  * @return
340  *  - Return 0 on success
341  */
342 typedef int (*cryptodev_sym_queue_pair_attach_session_t)(
343                   struct rte_cryptodev *dev,
344                   uint16_t qp_id,
345                   void *session_private);
346
347 /**
348  * Optional API for drivers to detach sessions from queue pair.
349  * @param       dev             Crypto device pointer
350  * @param       qp_id           queue pair id for detaching session
351  * @param       priv_sess       Pointer to cryptodev's private session structure
352  * @return
353  *  - Return 0 on success
354  */
355 typedef int (*cryptodev_sym_queue_pair_detach_session_t)(
356                   struct rte_cryptodev *dev,
357                   uint16_t qp_id,
358                   void *session_private);
359
360 /** Crypto device operations function pointer table */
361 struct rte_cryptodev_ops {
362         cryptodev_configure_t dev_configure;    /**< Configure device. */
363         cryptodev_start_t dev_start;            /**< Start device. */
364         cryptodev_stop_t dev_stop;              /**< Stop device. */
365         cryptodev_close_t dev_close;            /**< Close device. */
366
367         cryptodev_info_get_t dev_infos_get;     /**< Get device info. */
368
369         cryptodev_stats_get_t stats_get;
370         /**< Get device statistics. */
371         cryptodev_stats_reset_t stats_reset;
372         /**< Reset device statistics. */
373
374         cryptodev_queue_pair_setup_t queue_pair_setup;
375         /**< Set up a device queue pair. */
376         cryptodev_queue_pair_release_t queue_pair_release;
377         /**< Release a queue pair. */
378         cryptodev_queue_pair_start_t queue_pair_start;
379         /**< Start a queue pair. */
380         cryptodev_queue_pair_stop_t queue_pair_stop;
381         /**< Stop a queue pair. */
382         cryptodev_queue_pair_count_t queue_pair_count;
383         /**< Get count of the queue pairs. */
384
385         cryptodev_sym_get_session_private_size_t session_get_size;
386         /**< Return private session. */
387         cryptodev_sym_configure_session_t session_configure;
388         /**< Configure a Crypto session. */
389         cryptodev_sym_free_session_t session_clear;
390         /**< Clear a Crypto sessions private data. */
391         cryptodev_sym_queue_pair_attach_session_t qp_attach_session;
392         /**< Attach session to queue pair. */
393         cryptodev_sym_queue_pair_detach_session_t qp_detach_session;
394         /**< Detach session from queue pair. */
395 };
396
397
398 /**
399  * Function for internal use by dummy drivers primarily, e.g. ring-based
400  * driver.
401  * Allocates a new cryptodev slot for an crypto device and returns the pointer
402  * to that slot for the driver to use.
403  *
404  * @param       name            Unique identifier name for each device
405  * @param       socket_id       Socket to allocate resources on.
406  * @return
407  *   - Slot in the rte_dev_devices array for a new device;
408  */
409 struct rte_cryptodev *
410 rte_cryptodev_pmd_allocate(const char *name, int socket_id);
411
412 /**
413  * Function for internal use by dummy drivers primarily, e.g. ring-based
414  * driver.
415  * Release the specified cryptodev device.
416  *
417  * @param cryptodev
418  * The *cryptodev* pointer is the address of the *rte_cryptodev* structure.
419  * @return
420  *   - 0 on success, negative on error
421  */
422 extern int
423 rte_cryptodev_pmd_release_device(struct rte_cryptodev *cryptodev);
424
425
426 /**
427  * @internal
428  *
429  * PMD assist function to parse initialisation arguments for crypto driver
430  * when creating a new crypto PMD device instance.
431  *
432  * PMD driver should set default values for that PMD before calling function,
433  * these default values will be over-written with successfully parsed values
434  * from args string.
435  *
436  * @param       params  parsed PMD initialisation parameters
437  * @param       args    input argument string to parse
438  *
439  * @return
440  *  - 0 on success
441  *  - errno on failure
442  */
443 int
444 rte_cryptodev_pmd_parse_input_args(
445                 struct rte_cryptodev_pmd_init_params *params,
446                 const char *args);
447
448 /**
449  * @internal
450  *
451  * PMD assist function to provide boiler plate code for crypto driver to create
452  * and allocate resources for a new crypto PMD device instance.
453  *
454  * @param       name    crypto device name.
455  * @param       device  base device instance
456  * @param       params  PMD initialisation parameters
457  *
458  * @return
459  *  - crypto device instance on success
460  *  - NULL on creation failure
461  */
462 struct rte_cryptodev *
463 rte_cryptodev_pmd_create(const char *name,
464                 struct rte_device *device,
465                 struct rte_cryptodev_pmd_init_params *params);
466
467 /**
468  * @internal
469  *
470  * PMD assist function to provide boiler plate code for crypto driver to
471  * destroy and free resources associated with a crypto PMD device instance.
472  *
473  * @param       cryptodev       crypto device handle.
474  *
475  * @return
476  *  - 0 on success
477  *  - errno on failure
478  */
479 int
480 rte_cryptodev_pmd_destroy(struct rte_cryptodev *cryptodev);
481
482 /**
483  * Executes all the user application registered callbacks for the specific
484  * device.
485  *  *
486  * @param       dev     Pointer to cryptodev struct
487  * @param       event   Crypto device interrupt event type.
488  *
489  * @return
490  *  void
491  */
492 void rte_cryptodev_pmd_callback_process(struct rte_cryptodev *dev,
493                                 enum rte_cryptodev_event_type event);
494
495 /**
496  * @internal
497  * Create unique device name
498  */
499 int
500 rte_cryptodev_pmd_create_dev_name(char *name, const char *dev_name_prefix);
501
502 /**
503  * @internal
504  * Allocate Cryptodev driver.
505  *
506  * @param crypto_drv
507  *   Pointer to cryptodev_driver.
508  * @param drv
509  *   Pointer to rte_driver.
510  *
511  * @return
512  *  The driver type identifier
513  */
514 uint8_t rte_cryptodev_allocate_driver(struct cryptodev_driver *crypto_drv,
515                 const struct rte_driver *drv);
516
517
518 #define RTE_PMD_REGISTER_CRYPTO_DRIVER(crypto_drv, drv, driver_id)\
519 RTE_INIT(init_ ##driver_id);\
520 static void init_ ##driver_id(void)\
521 {\
522         driver_id = rte_cryptodev_allocate_driver(&crypto_drv, &(drv).driver);\
523 }
524
525 static inline void *
526 get_session_private_data(const struct rte_cryptodev_sym_session *sess,
527                 uint8_t driver_id) {
528         return sess->sess_private_data[driver_id];
529 }
530
531 static inline void
532 set_session_private_data(struct rte_cryptodev_sym_session *sess,
533                 uint8_t driver_id, void *private_data)
534 {
535         sess->sess_private_data[driver_id] = private_data;
536 }
537
538 #ifdef __cplusplus
539 }
540 #endif
541
542 #endif /* _RTE_CRYPTODEV_PMD_H_ */