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