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