1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2017-2018 Intel Corporation 3 */ 4 5 #ifndef _RTE_COMPRESSDEV_PMD_H_ 6 #define _RTE_COMPRESSDEV_PMD_H_ 7 8 /** @file 9 * RTE comp PMD APIs 10 * 11 * @note 12 * These APIs are for comp PMDs only and user applications should not call 13 * them directly. 14 */ 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 #include <string.h> 21 22 #include <rte_dev.h> 23 #include <rte_common.h> 24 25 #include "rte_compressdev.h" 26 #include "rte_compressdev_internal.h" 27 28 #define RTE_COMPRESSDEV_PMD_NAME_ARG ("name") 29 #define RTE_COMPRESSDEV_PMD_SOCKET_ID_ARG ("socket_id") 30 31 static const char * const compressdev_pmd_valid_params[] = { 32 RTE_COMPRESSDEV_PMD_NAME_ARG, 33 RTE_COMPRESSDEV_PMD_SOCKET_ID_ARG 34 }; 35 36 /** 37 * @internal 38 * Initialisation parameters for comp devices 39 */ 40 struct rte_compressdev_pmd_init_params { 41 char name[RTE_COMPRESSDEV_NAME_MAX_LEN]; 42 int socket_id; 43 }; 44 45 /** Global structure used for maintaining state of allocated comp devices */ 46 struct rte_compressdev_global { 47 struct rte_compressdev *devs; /**< Device information array */ 48 struct rte_compressdev_data *data[RTE_COMPRESS_MAX_DEVS]; 49 /**< Device private data */ 50 uint8_t nb_devs; /**< Number of devices found */ 51 uint8_t max_devs; /**< Max number of devices */ 52 }; 53 54 /** 55 * Get the rte_compressdev structure device pointer for the named device. 56 * 57 * @param name 58 * Compress device name 59 * @return 60 * - The rte_compressdev structure pointer for the given device identifier. 61 */ 62 __rte_experimental 63 struct rte_compressdev * 64 rte_compressdev_pmd_get_named_dev(const char *name); 65 66 /** 67 * Definitions of all functions exported by a driver through the 68 * the generic structure of type *comp_dev_ops* supplied in the 69 * *rte_compressdev* structure associated with a device. 70 */ 71 72 /** 73 * Function used to configure device. 74 * 75 * @param dev 76 * Compress device 77 * @param config 78 * Compress device configurations 79 * @return 80 * Returns 0 on success 81 */ 82 typedef int (*compressdev_configure_t)(struct rte_compressdev *dev, 83 struct rte_compressdev_config *config); 84 85 /** 86 * Function used to start a configured device. 87 * 88 * @param dev 89 * Compress device 90 * @return 91 * Returns 0 on success 92 */ 93 typedef int (*compressdev_start_t)(struct rte_compressdev *dev); 94 95 /** 96 * Function used to stop a configured device. 97 * 98 * @param dev 99 * Compress device 100 */ 101 typedef void (*compressdev_stop_t)(struct rte_compressdev *dev); 102 103 /** 104 * Function used to close a configured device. 105 * 106 * @param dev 107 * Compress device 108 * @return 109 * - 0 on success. 110 * - EAGAIN if can't close as device is busy 111 */ 112 typedef int (*compressdev_close_t)(struct rte_compressdev *dev); 113 114 115 /** 116 * Function used to get statistics of a device. 117 * 118 * @param dev 119 * Compress device 120 * @param stats 121 * Compress device stats to populate 122 */ 123 typedef void (*compressdev_stats_get_t)(struct rte_compressdev *dev, 124 struct rte_compressdev_stats *stats); 125 126 127 /** 128 * Function used to reset statistics of a device. 129 * 130 * @param dev 131 * Compress device 132 */ 133 typedef void (*compressdev_stats_reset_t)(struct rte_compressdev *dev); 134 135 136 /** 137 * Function used to get specific information of a device. 138 * 139 * @param dev 140 * Compress device 141 * @param dev_info 142 * Compress device information to populate 143 */ 144 typedef void (*compressdev_info_get_t)(struct rte_compressdev *dev, 145 struct rte_compressdev_info *dev_info); 146 147 /** 148 * Setup a queue pair for a device. 149 * 150 * @param dev 151 * Compress device 152 * @param qp_id 153 * Queue pair identifier 154 * @param max_inflight_ops 155 * Max inflight ops which qp must accommodate 156 * @param socket_id 157 * Socket identifier 158 * @return 159 * Returns 0 on success. 160 */ 161 typedef int (*compressdev_queue_pair_setup_t)(struct rte_compressdev *dev, 162 uint16_t qp_id, uint32_t max_inflight_ops, int socket_id); 163 164 /** 165 * Release memory resources allocated by given queue pair. 166 * 167 * @param dev 168 * Compress device 169 * @param qp_id 170 * Queue pair identifier 171 * @return 172 * - 0 on success. 173 * - EAGAIN if can't close as device is busy 174 */ 175 typedef int (*compressdev_queue_pair_release_t)(struct rte_compressdev *dev, 176 uint16_t qp_id); 177 178 /** 179 * Create driver private stream data. 180 * 181 * @param dev 182 * Compressdev device 183 * @param xform 184 * xform data 185 * @param stream 186 * ptr where handle of pmd's private stream data should be stored 187 * @return 188 * - Returns 0 if private stream structure has been created successfully. 189 * - Returns -EINVAL if input parameters are invalid. 190 * - Returns -ENOTSUP if comp device does not support STATEFUL operations. 191 * - Returns -ENOTSUP if comp device does not support the comp transform. 192 * - Returns -ENOMEM if the private stream could not be allocated. 193 */ 194 typedef int (*compressdev_stream_create_t)(struct rte_compressdev *dev, 195 const struct rte_comp_xform *xform, void **stream); 196 197 /** 198 * Free driver private stream data. 199 * 200 * @param dev 201 * Compressdev device 202 * @param stream 203 * handle of pmd's private stream data 204 * @return 205 * - 0 if successful 206 * - <0 in error cases 207 * - Returns -EINVAL if input parameters are invalid. 208 * - Returns -ENOTSUP if comp device does not support STATEFUL operations. 209 * - Returns -EBUSY if can't free stream as there are inflight operations 210 */ 211 typedef int (*compressdev_stream_free_t)(struct rte_compressdev *dev, 212 void *stream); 213 214 /** 215 * Create driver private_xform data. 216 * 217 * @param dev 218 * Compressdev device 219 * @param xform 220 * xform data 221 * @param private_xform 222 * ptr where handle of pmd's private_xform data should be stored 223 * @return 224 * - if successful returns 0 225 * and valid private_xform handle 226 * - <0 in error cases 227 * - Returns -EINVAL if input parameters are invalid. 228 * - Returns -ENOTSUP if comp device does not support the comp transform. 229 * - Returns -ENOMEM if the private_xform could not be allocated. 230 */ 231 typedef int (*compressdev_private_xform_create_t)(struct rte_compressdev *dev, 232 const struct rte_comp_xform *xform, void **private_xform); 233 234 /** 235 * Free driver private_xform data. 236 * 237 * @param dev 238 * Compressdev device 239 * @param private_xform 240 * handle of pmd's private_xform data 241 * @return 242 * - 0 if successful 243 * - <0 in error cases 244 * - Returns -EINVAL if input parameters are invalid. 245 * - Returns -EBUSY if can't free private_xform due to inflight operations 246 */ 247 typedef int (*compressdev_private_xform_free_t)(struct rte_compressdev *dev, 248 void *private_xform); 249 250 /** comp device operations function pointer table */ 251 struct rte_compressdev_ops { 252 compressdev_configure_t dev_configure; /**< Configure device. */ 253 compressdev_start_t dev_start; /**< Start device. */ 254 compressdev_stop_t dev_stop; /**< Stop device. */ 255 compressdev_close_t dev_close; /**< Close device. */ 256 257 compressdev_info_get_t dev_infos_get; /**< Get device info. */ 258 259 compressdev_stats_get_t stats_get; 260 /**< Get device statistics. */ 261 compressdev_stats_reset_t stats_reset; 262 /**< Reset device statistics. */ 263 264 compressdev_queue_pair_setup_t queue_pair_setup; 265 /**< Set up a device queue pair. */ 266 compressdev_queue_pair_release_t queue_pair_release; 267 /**< Release a queue pair. */ 268 269 compressdev_stream_create_t stream_create; 270 /**< Create a comp stream and initialise its private data. */ 271 compressdev_stream_free_t stream_free; 272 /**< Free a comp stream's private data. */ 273 274 compressdev_private_xform_create_t private_xform_create; 275 /**< Create a comp private_xform and initialise its private data. */ 276 compressdev_private_xform_free_t private_xform_free; 277 /**< Free a comp private_xform's data. */ 278 }; 279 280 /** 281 * @internal 282 * 283 * Function for internal use by dummy drivers primarily, e.g. ring-based 284 * driver. 285 * Allocates a new compressdev slot for an comp device and returns the pointer 286 * to that slot for the driver to use. 287 * 288 * @param name 289 * Unique identifier name for each device 290 * @param socket_id 291 * Socket to allocate resources on 292 * @return 293 * - Slot in the rte_dev_devices array for a new device; 294 */ 295 __rte_experimental 296 struct rte_compressdev * 297 rte_compressdev_pmd_allocate(const char *name, int socket_id); 298 299 /** 300 * @internal 301 * 302 * Function for internal use by dummy drivers primarily, e.g. ring-based 303 * driver. 304 * Release the specified compressdev device. 305 * 306 * @param dev 307 * Compress device 308 * @return 309 * - 0 on success, negative on error 310 */ 311 __rte_experimental 312 int 313 rte_compressdev_pmd_release_device(struct rte_compressdev *dev); 314 315 316 /** 317 * @internal 318 * 319 * PMD assist function to parse initialisation arguments for comp driver 320 * when creating a new comp PMD device instance. 321 * 322 * PMD driver should set default values for that PMD before calling function, 323 * these default values will be over-written with successfully parsed values 324 * from args string. 325 * 326 * @param params 327 * Parsed PMD initialisation parameters 328 * @param args 329 * Input argument string to parse 330 * @return 331 * - 0 on success 332 * - errno on failure 333 */ 334 __rte_experimental 335 int 336 rte_compressdev_pmd_parse_input_args( 337 struct rte_compressdev_pmd_init_params *params, 338 const char *args); 339 340 /** 341 * @internal 342 * 343 * PMD assist function to provide boiler plate code for comp driver to create 344 * and allocate resources for a new comp PMD device instance. 345 * 346 * @param name 347 * Compress device name 348 * @param device 349 * Base device instance 350 * @param params 351 * PMD initialisation parameters 352 * @return 353 * - comp device instance on success 354 * - NULL on creation failure 355 */ 356 __rte_experimental 357 struct rte_compressdev * 358 rte_compressdev_pmd_create(const char *name, 359 struct rte_device *device, 360 size_t private_data_size, 361 struct rte_compressdev_pmd_init_params *params); 362 363 /** 364 * @internal 365 * 366 * PMD assist function to provide boiler plate code for comp driver to 367 * destroy and free resources associated with a comp PMD device instance. 368 * 369 * @param dev 370 * Compress device 371 * @return 372 * - 0 on success 373 * - errno on failure 374 */ 375 __rte_experimental 376 int 377 rte_compressdev_pmd_destroy(struct rte_compressdev *dev); 378 379 #ifdef __cplusplus 380 } 381 #endif 382 383 #endif /* _RTE_COMPRESSDEV_PMD_H_ */ 384