examples: use new API to create control threads
[dpdk.git] / lib / librte_security / rte_security_driver.h
1 /*-
2  *   BSD LICENSE
3  *
4  *   Copyright(c) 2017 Intel Corporation. All rights reserved.
5  *   Copyright 2017 NXP.
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_SECURITY_DRIVER_H_
35 #define _RTE_SECURITY_DRIVER_H_
36
37 /**
38  * @file rte_security_driver.h
39  * @b EXPERIMENTAL: this API may change without prior notice
40  *
41  * RTE Security Common Definitions
42  *
43  */
44
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48
49 #include "rte_security.h"
50
51 /**
52  * Configure a security session on a device.
53  *
54  * @param       device          Crypto/eth device pointer
55  * @param       conf            Security session configuration
56  * @param       sess            Pointer to Security private session structure
57  * @param       mp              Mempool where the private session is allocated
58  *
59  * @return
60  *  - Returns 0 if private session structure have been created successfully.
61  *  - Returns -EINVAL if input parameters are invalid.
62  *  - Returns -ENOTSUP if crypto device does not support the crypto transform.
63  *  - Returns -ENOMEM if the private session could not be allocated.
64  */
65 typedef int (*security_session_create_t)(void *device,
66                 struct rte_security_session_conf *conf,
67                 struct rte_security_session *sess,
68                 struct rte_mempool *mp);
69
70 /**
71  * Free driver private session data.
72  *
73  * @param       dev             Crypto/eth device pointer
74  * @param       sess            Security session structure
75  */
76 typedef int (*security_session_destroy_t)(void *device,
77                 struct rte_security_session *sess);
78
79 /**
80  * Update driver private session data.
81  *
82  * @param       device          Crypto/eth device pointer
83  * @param       sess            Pointer to Security private session structure
84  * @param       conf            Security session configuration
85  *
86  * @return
87  *  - Returns 0 if private session structure have been updated successfully.
88  *  - Returns -EINVAL if input parameters are invalid.
89  *  - Returns -ENOTSUP if crypto device does not support the crypto transform.
90  */
91 typedef int (*security_session_update_t)(void *device,
92                 struct rte_security_session *sess,
93                 struct rte_security_session_conf *conf);
94
95 /**
96  * Get the size of a security session
97  *
98  * @param       device          Crypto/eth device pointer
99  *
100  * @return
101  *  - On success returns the size of the session structure for device
102  *  - On failure returns 0
103  */
104 typedef unsigned int (*security_session_get_size)(void *device);
105
106 /**
107  * Get stats from the PMD.
108  *
109  * @param       device          Crypto/eth device pointer
110  * @param       sess            Pointer to Security private session structure
111  * @param       stats           Security stats of the driver
112  *
113  * @return
114  *  - Returns 0 if private session structure have been updated successfully.
115  *  - Returns -EINVAL if session parameters are invalid.
116  */
117 typedef int (*security_session_stats_get_t)(void *device,
118                 struct rte_security_session *sess,
119                 struct rte_security_stats *stats);
120
121 /**
122  * Update the mbuf with provided metadata.
123  *
124  * @param       sess            Security session structure
125  * @param       mb              Packet buffer
126  * @param       mt              Metadata
127  *
128  * @return
129  *  - Returns 0 if metadata updated successfully.
130  *  - Returns -ve value for errors.
131  */
132 typedef int (*security_set_pkt_metadata_t)(void *device,
133                 struct rte_security_session *sess, struct rte_mbuf *m,
134                 void *params);
135
136 /**
137  * Get application specific userdata associated with the security session.
138  * Device specific metadata provided would be used to uniquely identify
139  * the security session being referred to.
140  *
141  * @param       device          Crypto/eth device pointer
142  * @param       md              Metadata
143  * @param       userdata        Pointer to receive userdata
144  *
145  * @return
146  *  - Returns 0 if userdata is retrieved successfully.
147  *  - Returns -ve value for errors.
148  */
149 typedef int (*security_get_userdata_t)(void *device,
150                 uint64_t md, void **userdata);
151
152 /**
153  * Get security capabilities of the device.
154  *
155  * @param       device          crypto/eth device pointer
156  *
157  * @return
158  *  - Returns rte_security_capability pointer on success.
159  *  - Returns NULL on error.
160  */
161 typedef const struct rte_security_capability *(*security_capabilities_get_t)(
162                 void *device);
163
164 /** Security operations function pointer table */
165 struct rte_security_ops {
166         security_session_create_t session_create;
167         /**< Configure a security session. */
168         security_session_update_t session_update;
169         /**< Update a security session. */
170         security_session_get_size session_get_size;
171         /**< Return size of security session. */
172         security_session_stats_get_t session_stats_get;
173         /**< Get security session statistics. */
174         security_session_destroy_t session_destroy;
175         /**< Clear a security sessions private data. */
176         security_set_pkt_metadata_t set_pkt_metadata;
177         /**< Update mbuf metadata. */
178         security_get_userdata_t get_userdata;
179         /**< Get userdata associated with session which processed the packet. */
180         security_capabilities_get_t capabilities_get;
181         /**< Get security capabilities. */
182 };
183
184 #ifdef __cplusplus
185 }
186 #endif
187
188 #endif /* _RTE_SECURITY_DRIVER_H_ */