1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2017-2018 Intel Corporation 3 */ 4 5 #ifndef _RTE_COMP_H_ 6 #define _RTE_COMP_H_ 7 8 /** 9 * @file rte_comp.h 10 * 11 * RTE definitions for Data Compression Service 12 * 13 */ 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 #include <rte_mbuf.h> 20 21 /** 22 * compression service feature flags 23 * 24 * @note New features flags should be added to the end of the list 25 * 26 * Keep these flags synchronised with rte_comp_get_feature_name() 27 */ 28 #define RTE_COMP_FF_STATEFUL_COMPRESSION (1ULL << 0) 29 /**< Stateful compression is supported */ 30 #define RTE_COMP_FF_STATEFUL_DECOMPRESSION (1ULL << 1) 31 /**< Stateful decompression is supported */ 32 #define RTE_COMP_FF_OOP_SGL_IN_SGL_OUT (1ULL << 2) 33 /**< Out-of-place Scatter-gather (SGL) buffers, 34 * with multiple segments, are supported in input and output 35 */ 36 #define RTE_COMP_FF_OOP_SGL_IN_LB_OUT (1ULL << 3) 37 /**< Out-of-place Scatter-gather (SGL) buffers are supported 38 * in input, combined with linear buffers (LB), with a 39 * single segment, in output 40 */ 41 #define RTE_COMP_FF_OOP_LB_IN_SGL_OUT (1ULL << 4) 42 /**< Out-of-place Scatter-gather (SGL) buffers are supported 43 * in output, combined with linear buffers (LB) in input 44 */ 45 #define RTE_COMP_FF_ADLER32_CHECKSUM (1ULL << 5) 46 /**< Adler-32 Checksum is supported */ 47 #define RTE_COMP_FF_CRC32_CHECKSUM (1ULL << 6) 48 /**< CRC32 Checksum is supported */ 49 #define RTE_COMP_FF_CRC32_ADLER32_CHECKSUM (1ULL << 7) 50 /**< Adler-32/CRC32 Checksum is supported */ 51 #define RTE_COMP_FF_MULTI_PKT_CHECKSUM (1ULL << 8) 52 /**< Generation of checksum across multiple stateless packets is supported */ 53 #define RTE_COMP_FF_SHA1_HASH (1ULL << 9) 54 /**< SHA1 Hash is supported */ 55 #define RTE_COMP_FF_SHA2_SHA256_HASH (1ULL << 10) 56 /**< SHA256 Hash of SHA2 family is supported */ 57 #define RTE_COMP_FF_NONCOMPRESSED_BLOCKS (1ULL << 11) 58 /**< Creation of non-compressed blocks using RTE_COMP_LEVEL_NONE is supported */ 59 #define RTE_COMP_FF_SHAREABLE_PRIV_XFORM (1ULL << 12) 60 /**< Private xforms created by the PMD can be shared 61 * across multiple stateless operations. If not set, then app needs 62 * to create as many priv_xforms as it expects to have stateless 63 * operations in-flight. 64 */ 65 #define RTE_COMP_FF_HUFFMAN_FIXED (1ULL << 13) 66 /**< Fixed huffman encoding is supported */ 67 #define RTE_COMP_FF_HUFFMAN_DYNAMIC (1ULL << 14) 68 /**< Dynamic huffman encoding is supported */ 69 70 /** Status of comp operation */ 71 enum rte_comp_op_status { 72 RTE_COMP_OP_STATUS_SUCCESS = 0, 73 /**< Operation completed successfully */ 74 RTE_COMP_OP_STATUS_NOT_PROCESSED, 75 /**< Operation has not yet been processed by the device */ 76 RTE_COMP_OP_STATUS_INVALID_ARGS, 77 /**< Operation failed due to invalid arguments in request */ 78 RTE_COMP_OP_STATUS_ERROR, 79 /**< Error handling operation */ 80 RTE_COMP_OP_STATUS_INVALID_STATE, 81 /**< Operation is invoked in invalid state */ 82 RTE_COMP_OP_STATUS_OUT_OF_SPACE_TERMINATED, 83 /**< Output buffer ran out of space before operation completed. 84 * Error case. Application must resubmit all data with a larger 85 * output buffer. 86 */ 87 RTE_COMP_OP_STATUS_OUT_OF_SPACE_RECOVERABLE, 88 /**< Output buffer ran out of space before operation completed, but this 89 * is not an error case. Output data up to op.produced can be used and 90 * next op in the stream should continue on from op.consumed+1. 91 */ 92 }; 93 94 /** Compression Algorithms */ 95 enum rte_comp_algorithm { 96 RTE_COMP_ALGO_UNSPECIFIED = 0, 97 /** No Compression algorithm */ 98 RTE_COMP_ALGO_NULL, 99 /**< No compression. 100 * Pass-through, data is copied unchanged from source buffer to 101 * destination buffer. 102 */ 103 RTE_COMP_ALGO_DEFLATE, 104 /**< DEFLATE compression algorithm 105 * https://tools.ietf.org/html/rfc1951 106 */ 107 RTE_COMP_ALGO_LZS, 108 /**< LZS compression algorithm 109 * https://tools.ietf.org/html/rfc2395 110 */ 111 RTE_COMP_ALGO_LIST_END 112 }; 113 114 /** Compression Hash Algorithms */ 115 enum rte_comp_hash_algorithm { 116 RTE_COMP_HASH_ALGO_NONE = 0, 117 /**< No hash */ 118 RTE_COMP_HASH_ALGO_SHA1, 119 /**< SHA1 hash algorithm */ 120 RTE_COMP_HASH_ALGO_SHA2_256, 121 /**< SHA256 hash algorithm of SHA2 family */ 122 RTE_COMP_HASH_ALGO_LIST_END 123 }; 124 125 /**< Compression Level. 126 * The number is interpreted by each PMD differently. However, lower numbers 127 * give fastest compression, at the expense of compression ratio while 128 * higher numbers may give better compression ratios but are likely slower. 129 */ 130 #define RTE_COMP_LEVEL_PMD_DEFAULT (-1) 131 /** Use PMD Default */ 132 #define RTE_COMP_LEVEL_NONE (0) 133 /** Output uncompressed blocks if supported by the specified algorithm */ 134 #define RTE_COMP_LEVEL_MIN (1) 135 /** Use minimum compression level supported by the PMD */ 136 #define RTE_COMP_LEVEL_MAX (9) 137 /** Use maximum compression level supported by the PMD */ 138 139 /** Compression checksum types */ 140 enum rte_comp_checksum_type { 141 RTE_COMP_CHECKSUM_NONE, 142 /**< No checksum generated */ 143 RTE_COMP_CHECKSUM_CRC32, 144 /**< Generates a CRC32 checksum, as used by gzip */ 145 RTE_COMP_CHECKSUM_ADLER32, 146 /**< Generates an Adler-32 checksum, as used by zlib */ 147 RTE_COMP_CHECKSUM_CRC32_ADLER32, 148 /**< Generates both Adler-32 and CRC32 checksums, concatenated. 149 * CRC32 is in the lower 32bits, Adler-32 in the upper 32 bits. 150 */ 151 }; 152 153 154 /** Compression Huffman Type - used by DEFLATE algorithm */ 155 enum rte_comp_huffman { 156 RTE_COMP_HUFFMAN_DEFAULT, 157 /**< PMD may choose which Huffman codes to use */ 158 RTE_COMP_HUFFMAN_FIXED, 159 /**< Use Fixed Huffman codes */ 160 RTE_COMP_HUFFMAN_DYNAMIC, 161 /**< Use Dynamic Huffman codes */ 162 }; 163 164 /** Compression flush flags */ 165 enum rte_comp_flush_flag { 166 RTE_COMP_FLUSH_NONE, 167 /**< Data is not flushed. Output may remain in the compressor and be 168 * processed during a following op. It may not be possible to decompress 169 * output until a later op with some other flush flag has been sent. 170 */ 171 RTE_COMP_FLUSH_SYNC, 172 /**< All data should be flushed to output buffer. Output data can be 173 * decompressed. However state and history is not cleared, so future 174 * operations may use history from this operation. 175 */ 176 RTE_COMP_FLUSH_FULL, 177 /**< All data should be flushed to output buffer. Output data can be 178 * decompressed. State and history data is cleared, so future 179 * ops will be independent of ops processed before this. 180 */ 181 RTE_COMP_FLUSH_FINAL 182 /**< Same as RTE_COMP_FLUSH_FULL but if op.algo is RTE_COMP_ALGO_DEFLATE 183 * then bfinal bit is set in the last block. 184 */ 185 }; 186 187 /** Compression transform types */ 188 enum rte_comp_xform_type { 189 RTE_COMP_COMPRESS, 190 /**< Compression service - compress */ 191 RTE_COMP_DECOMPRESS, 192 /**< Compression service - decompress */ 193 }; 194 195 /** Compression operation type */ 196 enum rte_comp_op_type { 197 RTE_COMP_OP_STATELESS, 198 /**< All data to be processed is submitted in the op, no state or 199 * history from previous ops is used and none will be stored for future 200 * ops. Flush flag must be set to either FLUSH_FULL or FLUSH_FINAL. 201 */ 202 RTE_COMP_OP_STATEFUL 203 /**< There may be more data to be processed after this op, it's part of 204 * a stream of data. State and history from previous ops can be used 205 * and resulting state and history can be stored for future ops, 206 * depending on flush flag. 207 */ 208 }; 209 210 211 /** Parameters specific to the deflate algorithm */ 212 struct rte_comp_deflate_params { 213 enum rte_comp_huffman huffman; 214 /**< Compression huffman encoding type */ 215 }; 216 217 /** Setup Data for compression */ 218 struct rte_comp_compress_xform { 219 enum rte_comp_algorithm algo; 220 /**< Algorithm to use for compress operation */ 221 union { 222 struct rte_comp_deflate_params deflate; 223 /**< Parameters specific to the deflate algorithm */ 224 }; /**< Algorithm specific parameters */ 225 int level; 226 /**< Compression level */ 227 uint8_t window_size; 228 /**< Base two log value of sliding window to be used. If window size 229 * can't be supported by the PMD then it may fall back to a smaller 230 * size. This is likely to result in a worse compression ratio. 231 */ 232 enum rte_comp_checksum_type chksum; 233 /**< Type of checksum to generate on the uncompressed data */ 234 enum rte_comp_hash_algorithm hash_algo; 235 /**< Hash algorithm to be used with compress operation. Hash is always 236 * done on plaintext. 237 */ 238 }; 239 240 /** 241 * Setup Data for decompression. 242 */ 243 struct rte_comp_decompress_xform { 244 enum rte_comp_algorithm algo; 245 /**< Algorithm to use for decompression */ 246 enum rte_comp_checksum_type chksum; 247 /**< Type of checksum to generate on the decompressed data */ 248 uint8_t window_size; 249 /**< Base two log value of sliding window which was used to generate 250 * compressed data. If window size can't be supported by the PMD then 251 * setup of stream or private_xform should fail. 252 */ 253 enum rte_comp_hash_algorithm hash_algo; 254 /**< Hash algorithm to be used with decompress operation. Hash is always 255 * done on plaintext. 256 */ 257 }; 258 259 /** 260 * Compression transform structure. 261 * 262 * This is used to specify the compression transforms required. 263 * Each transform structure can hold a single transform, the type field is 264 * used to specify which transform is contained within the union. 265 */ 266 struct rte_comp_xform { 267 enum rte_comp_xform_type type; 268 /**< xform type */ 269 union { 270 struct rte_comp_compress_xform compress; 271 /**< xform for compress operation */ 272 struct rte_comp_decompress_xform decompress; 273 /**< decompress xform */ 274 }; 275 }; 276 277 /** 278 * Compression Operation. 279 * 280 * This structure contains data relating to performing a compression 281 * operation on the referenced mbuf data buffers. 282 * 283 * Comp operations are enqueued and dequeued in comp PMDs using the 284 * rte_compressdev_enqueue_burst() / rte_compressdev_dequeue_burst() APIs 285 */ 286 struct rte_comp_op { 287 enum rte_comp_op_type op_type; 288 union { 289 void *private_xform; 290 /**< Stateless private PMD data derived from an rte_comp_xform. 291 * A handle returned by rte_compressdev_private_xform_create() 292 * must be attached to operations of op_type RTE_COMP_STATELESS. 293 */ 294 void *stream; 295 /**< Private PMD data derived initially from an rte_comp_xform, 296 * which holds state and history data and evolves as operations 297 * are processed. rte_compressdev_stream_create() must be called 298 * on a device for all STATEFUL data streams and the resulting 299 * stream attached to the one or more operations associated 300 * with the data stream. 301 * All operations in a stream must be sent to the same device. 302 */ 303 }; 304 305 struct rte_mempool *mempool; 306 /**< Pool from which operation is allocated */ 307 rte_iova_t iova_addr; 308 /**< IOVA address of this operation */ 309 struct rte_mbuf *m_src; 310 /**< source mbuf 311 * The total size of the input buffer(s) can be retrieved using 312 * rte_pktmbuf_pkt_len(m_src). The max data size which can fit in a 313 * single mbuf is limited by the uint16_t rte_mbuf.data_len to 64k-1. 314 * If the input data is bigger than this it can be passed to the PMD in 315 * a chain of mbufs if the PMD's capabilities indicate it supports this. 316 */ 317 struct rte_mbuf *m_dst; 318 /**< destination mbuf 319 * The total size of the output buffer(s) can be retrieved using 320 * rte_pktmbuf_pkt_len(m_dst). The max data size which can fit in a 321 * single mbuf is limited by the uint16_t rte_mbuf.data_len to 64k-1. 322 * If the output data is expected to be bigger than this a chain of 323 * mbufs can be passed to the PMD if the PMD's capabilities indicate 324 * it supports this. 325 * 326 * @note, if incompressible data is passed to an engine for compression 327 * using RTE_COMP_ALGO_DEFLATE, it's possible for the output data 328 * to be larger than the uncompressed data, due to the inclusion 329 * of the DEFLATE header blocks. The size of m_dst should accommodate 330 * this, else OUT_OF_SPACE errors can be expected in this case. 331 */ 332 333 struct { 334 uint32_t offset; 335 /**< Starting point for compression or decompression, 336 * specified as number of bytes from start of packet in 337 * source buffer. 338 * This offset starts from the first segment 339 * of the buffer, in case the m_src is a chain of mbufs. 340 * Starting point for checksum generation in compress direction. 341 */ 342 uint32_t length; 343 /**< The length, in bytes, of the data in source buffer 344 * to be compressed or decompressed. 345 * Also the length of the data over which the checksum 346 * should be generated in compress direction 347 */ 348 } src; 349 struct { 350 uint32_t offset; 351 /**< Starting point for writing output data, specified as 352 * number of bytes from start of packet in dest 353 * buffer. 354 * This offset starts from the first segment 355 * of the buffer, in case the m_dst is a chain of mbufs. 356 * Starting point for checksum generation in 357 * decompress direction. 358 */ 359 } dst; 360 struct { 361 uint8_t *digest; 362 /**< Output buffer to store hash output, if enabled in xform. 363 * Buffer would contain valid value only after an op with 364 * flush flag = RTE_COMP_FLUSH_FULL/FLUSH_FINAL is processed 365 * successfully. 366 * 367 * Length of buffer should be contiguous and large enough to 368 * accommodate digest produced by specific hash algo. 369 */ 370 rte_iova_t iova_addr; 371 /**< IO address of the buffer */ 372 } hash; 373 enum rte_comp_flush_flag flush_flag; 374 /**< Defines flush characteristics for the output data. 375 * Only applicable in compress direction 376 */ 377 uint64_t input_chksum; 378 /**< An input checksum can be provided to generate a 379 * cumulative checksum across sequential blocks in a STATELESS stream. 380 * Checksum type is as specified in xform chksum_type 381 */ 382 uint64_t output_chksum; 383 /**< If a checksum is generated it will be written in here. 384 * Checksum type is as specified in xform chksum_type. 385 */ 386 uint32_t consumed; 387 /**< The number of bytes from the source buffer 388 * which were compressed/decompressed. 389 */ 390 uint32_t produced; 391 /**< The number of bytes written to the destination buffer 392 * which were compressed/decompressed. 393 */ 394 uint64_t debug_status; 395 /**< 396 * Status of the operation is returned in the status param. 397 * This field allows the PMD to pass back extra 398 * pmd-specific debug information. Value is not defined on the API. 399 */ 400 uint8_t status; 401 /**< 402 * Operation status - use values from enum rte_comp_status. 403 * This is reset to 404 * RTE_COMP_OP_STATUS_NOT_PROCESSED on allocation from mempool and 405 * will be set to RTE_COMP_OP_STATUS_SUCCESS after operation 406 * is successfully processed by a PMD 407 */ 408 } __rte_cache_aligned; 409 410 /** 411 * Creates an operation pool 412 * 413 * @param name 414 * Compress pool name 415 * @param nb_elts 416 * Number of elements in pool 417 * @param cache_size 418 * Number of elements to cache on lcore, see 419 * *rte_mempool_create* for further details about cache size 420 * @param user_size 421 * Size of private data to allocate for user with each operation 422 * @param socket_id 423 * Socket to identifier allocate memory on 424 * @return 425 * - On success pointer to mempool 426 * - On failure NULL 427 */ 428 __rte_experimental 429 struct rte_mempool * 430 rte_comp_op_pool_create(const char *name, 431 unsigned int nb_elts, unsigned int cache_size, 432 uint16_t user_size, int socket_id); 433 434 /** 435 * Allocate an operation from a mempool with default parameters set 436 * 437 * @param mempool 438 * Compress operation mempool 439 * 440 * @return 441 * - On success returns a valid rte_comp_op structure 442 * - On failure returns NULL 443 */ 444 __rte_experimental 445 struct rte_comp_op * 446 rte_comp_op_alloc(struct rte_mempool *mempool); 447 448 /** 449 * Bulk allocate operations from a mempool with default parameters set 450 * 451 * @param mempool 452 * Compress operation mempool 453 * @param ops 454 * Array to place allocated operations 455 * @param nb_ops 456 * Number of operations to allocate 457 * @return 458 * - nb_ops: Success, the nb_ops requested was allocated 459 * - 0: Not enough entries in the mempool; no ops are retrieved. 460 */ 461 __rte_experimental 462 int 463 rte_comp_op_bulk_alloc(struct rte_mempool *mempool, 464 struct rte_comp_op **ops, uint16_t nb_ops); 465 466 /** 467 * Free operation structure 468 * If operation has been allocate from a rte_mempool, then the operation will 469 * be returned to the mempool. 470 * 471 * @param op 472 * Compress operation 473 */ 474 __rte_experimental 475 void 476 rte_comp_op_free(struct rte_comp_op *op); 477 478 /** 479 * Bulk free operation structures 480 * If operations have been allocated from an rte_mempool, then the operations 481 * will be returned to the mempool. 482 * The array entry will be cleared. 483 * 484 * @param ops 485 * Array of Compress operations 486 * @param nb_ops 487 * Number of operations to free 488 */ 489 __rte_experimental 490 void 491 rte_comp_op_bulk_free(struct rte_comp_op **ops, uint16_t nb_ops); 492 493 /** 494 * Get the name of a compress service feature flag 495 * 496 * @param flag 497 * The mask describing the flag 498 * 499 * @return 500 * The name of this flag, or NULL if it's not a valid feature flag. 501 */ 502 __rte_experimental 503 const char * 504 rte_comp_get_feature_name(uint64_t flag); 505 506 #ifdef __cplusplus 507 } 508 #endif 509 510 #endif /* _RTE_COMP_H_ */ 511