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