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 #include <string.h> 17 18 #include <dev_driver.h> 19 20 #include "rte_compressdev.h" 21 #include "rte_compressdev_internal.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 #define RTE_COMPRESSDEV_PMD_NAME_ARG ("name") 28 #define RTE_COMPRESSDEV_PMD_SOCKET_ID_ARG ("socket_id") 29 30 static const char * const compressdev_pmd_valid_params[] = { 31 RTE_COMPRESSDEV_PMD_NAME_ARG, 32 RTE_COMPRESSDEV_PMD_SOCKET_ID_ARG 33 }; 34 35 /** 36 * @internal 37 * Initialisation parameters for comp devices 38 */ 39 struct rte_compressdev_pmd_init_params { 40 char name[RTE_COMPRESSDEV_NAME_MAX_LEN]; 41 int socket_id; 42 }; 43 44 /** Global structure used for maintaining state of allocated comp devices */ 45 struct rte_compressdev_global { 46 struct rte_compressdev *devs; /**< Device information array */ 47 struct rte_compressdev_data *data[RTE_COMPRESS_MAX_DEVS]; 48 /**< Device private data */ 49 uint8_t nb_devs; /**< Number of devices found */ 50 uint8_t max_devs; /**< Max number of devices */ 51 }; 52 53 /** 54 * Get the rte_compressdev structure device pointer for the named device. 55 * 56 * @param name 57 * Compress device name 58 * @return 59 * - The rte_compressdev structure pointer for the given device identifier. 60 */ 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 struct rte_compressdev * 294 rte_compressdev_pmd_allocate(const char *name, int socket_id); 295 296 /** 297 * @internal 298 * 299 * Function for internal use by dummy drivers primarily, e.g. ring-based 300 * driver. 301 * Release the specified compressdev device. 302 * 303 * @param dev 304 * Compress device 305 * @return 306 * - 0 on success, negative on error 307 */ 308 int 309 rte_compressdev_pmd_release_device(struct rte_compressdev *dev); 310 311 312 /** 313 * @internal 314 * 315 * PMD assist function to parse initialisation arguments for comp driver 316 * when creating a new comp PMD device instance. 317 * 318 * PMD should set default values for that PMD before calling function, 319 * these default values will be over-written with successfully parsed values 320 * from args string. 321 * 322 * @param params 323 * Parsed PMD initialisation parameters 324 * @param args 325 * Input argument string to parse 326 * @return 327 * - 0 on success 328 * - errno on failure 329 */ 330 int 331 rte_compressdev_pmd_parse_input_args( 332 struct rte_compressdev_pmd_init_params *params, 333 const char *args); 334 335 /** 336 * @internal 337 * 338 * PMD assist function to provide boiler plate code for comp driver to create 339 * and allocate resources for a new comp PMD device instance. 340 * 341 * @param name 342 * Compress device name 343 * @param device 344 * Base device instance 345 * @param params 346 * PMD initialisation parameters 347 * @return 348 * - comp device instance on success 349 * - NULL on creation failure 350 */ 351 struct rte_compressdev * 352 rte_compressdev_pmd_create(const char *name, 353 struct rte_device *device, 354 size_t private_data_size, 355 struct rte_compressdev_pmd_init_params *params); 356 357 /** 358 * @internal 359 * 360 * PMD assist function to provide boiler plate code for comp driver to 361 * destroy and free resources associated with a comp PMD device instance. 362 * 363 * @param dev 364 * Compress device 365 * @return 366 * - 0 on success 367 * - errno on failure 368 */ 369 int 370 rte_compressdev_pmd_destroy(struct rte_compressdev *dev); 371 372 #ifdef __cplusplus 373 } 374 #endif 375 376 #endif /* _RTE_COMPRESSDEV_PMD_H_ */ 377