rte_comp.h(3)

📦
version 25.11.3 · 4 versions
, in ubuntu resolute, ubuntu stonking

bestie. okay so. this is rte_comp.h, and it lives in section 3 — the Library Functions Manual — and it's literally the header that carries every RTE definition for the Data Compression Service in DPDK. it's giving ✨ foundational ✨. grab a snack, because this one is long and there's absolutely no filler. 🍓

💖 NAME 💖

rte_comp.h — that's the whole name, no notes. it's a header. she's a header. slay. 🫶

✨ SYNOPSIS ✨

#include <rte_common.h>
#include <rte_mbuf.h>

🎀 Data Structures 🎀

  • struct rte_comp_deflate_params
  • struct rte_comp_inflate_params
  • struct rte_comp_lz4_params
  • struct rte_comp_compress_xform
  • struct rte_comp_decompress_xform
  • struct rte_comp_xform
  • struct rte_comp_op

🌈 Macros 🌈

#define RTE_COMP_FF_STATEFUL_COMPRESSION   (1ULL << 0)
#define RTE_COMP_FF_STATEFUL_DECOMPRESSION   (1ULL << 1)
#define RTE_COMP_FF_OOP_SGL_IN_SGL_OUT   (1ULL << 2)
#define RTE_COMP_FF_OOP_SGL_IN_LB_OUT   (1ULL << 3)
#define RTE_COMP_FF_OOP_LB_IN_SGL_OUT   (1ULL << 4)
#define RTE_COMP_FF_ADLER32_CHECKSUM   (1ULL << 5)
#define RTE_COMP_FF_CRC32_CHECKSUM   (1ULL << 6)
#define RTE_COMP_FF_CRC32_ADLER32_CHECKSUM   (1ULL << 7)
#define RTE_COMP_FF_MULTI_PKT_CHECKSUM   (1ULL << 8)
#define RTE_COMP_FF_SHA1_HASH   (1ULL << 9)
#define RTE_COMP_FF_SHA2_SHA256_HASH   (1ULL << 10)
#define RTE_COMP_FF_NONCOMPRESSED_BLOCKS   (1ULL << 11)
#define RTE_COMP_FF_SHAREABLE_PRIV_XFORM   (1ULL << 12)
#define RTE_COMP_FF_HUFFMAN_FIXED   (1ULL << 13)
#define RTE_COMP_FF_HUFFMAN_DYNAMIC   (1ULL << 14)
#define RTE_COMP_FF_XXHASH32_CHECKSUM   (1ULL << 15)
#define RTE_COMP_FF_LZ4_DICT_ID   (1ULL << 16)
#define RTE_COMP_FF_LZ4_CONTENT_WITH_CHECKSUM   (1ULL << 17)
#define RTE_COMP_FF_LZ4_CONTENT_SIZE   (1ULL << 18)
#define RTE_COMP_FF_LZ4_BLOCK_INDEPENDENCE   (1ULL << 19)
#define RTE_COMP_FF_LZ4_BLOCK_WITH_CHECKSUM   (1ULL << 20)
#define RTE_COMP_LEVEL_NONE   (0)
#define RTE_COMP_LEVEL_MIN   (1)
#define RTE_COMP_LEVEL_MAX   (9)
#define RTE_COMP_LZ4_FLAG_DICT_ID   (1 << 0)
#define RTE_COMP_LZ4_FLAG_CONTENT_CHECKSUM   (1 << 2)
#define RTE_COMP_LZ4_FLAG_CONTENT_SIZE   (1 << 3)
#define RTE_COMP_LZ4_FLAG_BLOCK_CHECKSUM   (1 << 4)
#define RTE_COMP_LZ4_FLAG_BLOCK_INDEPENDENCE   (1 << 5)

👑 Enumerations 👑

enum rte_comp_op_status { RTE_COMP_OP_STATUS_SUCCESS = 0,
    RTE_COMP_OP_STATUS_NOT_PROCESSED, RTE_COMP_OP_STATUS_INVALID_ARGS,
    RTE_COMP_OP_STATUS_ERROR, RTE_COMP_OP_STATUS_INVALID_STATE,
    RTE_COMP_OP_STATUS_OUT_OF_SPACE_TERMINATED,
    RTE_COMP_OP_STATUS_OUT_OF_SPACE_RECOVERABLE,
    RTE_COMP_OP_STATUS_CHECKSUM_VALIDATION_FAILED }
enum rte_comp_algorithm {  }
enum rte_comp_hash_algorithm { RTE_COMP_HASH_ALGO_NONE = 0,
    RTE_COMP_HASH_ALGO_SHA1, RTE_COMP_HASH_ALGO_SHA2_256 }
enum rte_comp_checksum_type { RTE_COMP_CHECKSUM_NONE,
    RTE_COMP_CHECKSUM_CRC32, RTE_COMP_CHECKSUM_ADLER32,
    RTE_COMP_CHECKSUM_CRC32_ADLER32, RTE_COMP_CHECKSUM_XXHASH32,
    RTE_COMP_CHECKSUM_3GPP_PDCP_UDC }
enum rte_comp_huffman { RTE_COMP_HUFFMAN_DEFAULT,
    RTE_COMP_HUFFMAN_FIXED, RTE_COMP_HUFFMAN_DYNAMIC }
enum rte_comp_flush_flag { RTE_COMP_FLUSH_NONE, RTE_COMP_FLUSH_SYNC,
    RTE_COMP_FLUSH_FULL, RTE_COMP_FLUSH_FINAL }
enum rte_comp_xform_type { RTE_COMP_COMPRESS, RTE_COMP_DECOMPRESS }
enum rte_comp_op_type { RTE_COMP_OP_STATELESS, RTE_COMP_OP_STATEFUL }

(and yes, enum rte_comp_algorithm { } really is just vibes and empty braces in here — that's how she is, no cap. 💀)

🦋 Functions 🦋

  • void rte_comp_op_free (struct rte_comp_op *op)
  • struct rte_mempool * rte_comp_op_pool_create (const char *name, unsigned int nb_elts, unsigned int cache_size, uint16_t user_size, int socket_id) __rte_malloc __rte_dealloc(rte_comp_op_free
  • struct rte_mempool struct rte_comp_op * rte_comp_op_alloc (struct rte_mempool *mempool)
  • int rte_comp_op_bulk_alloc (struct rte_mempool *mempool, struct rte_comp_op **ops, uint16_t nb_ops)
  • void rte_comp_op_bulk_free (struct rte_comp_op **ops, uint16_t nb_ops)
  • const char * rte_comp_get_feature_name (uint64_t flag)

🌸 Detailed Description 🌸

RTE definitions for Data Compression Service

Definition in file rte_comp.h.

💜 Macro Definition Documentation 💜

✨ #define RTE_COMP_FF_STATEFUL_COMPRESSION (1ULL << 0) ✨

these are the compression service feature flags, bestie. 🚩

📌 Note: New features flags should be added to the end of the list. Keep these flags synchronised with rte_comp_get_feature_name()

Stateful compression is supported.

Definition at line 28 of file rte_comp.h.

✨ #define RTE_COMP_FF_STATEFUL_DECOMPRESSION (1ULL << 1) ✨

Stateful decompression is supported.

Definition at line 30 of file rte_comp.h.

✨ #define RTE_COMP_FF_OOP_SGL_IN_SGL_OUT (1ULL << 2) ✨

Out-of-place Scatter-gather (SGL) buffers, with multiple segments, are supported in input and output.

Definition at line 32 of file rte_comp.h.

✨ #define RTE_COMP_FF_OOP_SGL_IN_LB_OUT (1ULL << 3) ✨

Out-of-place Scatter-gather (SGL) buffers are supported in input, combined with linear buffers (LB), with a single segment, in output.

Definition at line 36 of file rte_comp.h.

✨ #define RTE_COMP_FF_OOP_LB_IN_SGL_OUT (1ULL << 4) ✨

Out-of-place Scatter-gather (SGL) buffers are supported in output, combined with linear buffers (LB) in input.

Definition at line 41 of file rte_comp.h.

✨ #define RTE_COMP_FF_ADLER32_CHECKSUM (1ULL << 5) ✨

Adler-32 Checksum is supported.

Definition at line 45 of file rte_comp.h.

✨ #define RTE_COMP_FF_CRC32_CHECKSUM (1ULL << 6) ✨

CRC32 Checksum is supported.

Definition at line 47 of file rte_comp.h.

✨ #define RTE_COMP_FF_CRC32_ADLER32_CHECKSUM (1ULL << 7) ✨

Adler-32/CRC32 Checksum is supported.

Definition at line 49 of file rte_comp.h.

✨ #define RTE_COMP_FF_MULTI_PKT_CHECKSUM (1ULL << 8) ✨

Generation of checksum across multiple stateless packets is supported.

Definition at line 51 of file rte_comp.h.

✨ #define RTE_COMP_FF_SHA1_HASH (1ULL << 9) ✨

SHA1 Hash is supported.

Definition at line 53 of file rte_comp.h.

✨ #define RTE_COMP_FF_SHA2_SHA256_HASH (1ULL << 10) ✨

SHA256 Hash of SHA2 family is supported.

Definition at line 55 of file rte_comp.h.

✨ #define RTE_COMP_FF_NONCOMPRESSED_BLOCKS (1ULL << 11) ✨

Creation of non-compressed blocks using RTE_COMP_LEVEL_NONE is supported.

Definition at line 57 of file rte_comp.h.

✨ #define RTE_COMP_FF_SHAREABLE_PRIV_XFORM (1ULL << 12) ✨

Private xforms created by the PMD can be shared across multiple stateless operations. If not set, then app needs to create as many priv_xforms as it expects to have stateless operations in-flight.

Definition at line 59 of file rte_comp.h.

✨ #define RTE_COMP_FF_HUFFMAN_FIXED (1ULL << 13) ✨

Fixed huffman encoding is supported.

Definition at line 65 of file rte_comp.h.

✨ #define RTE_COMP_FF_HUFFMAN_DYNAMIC (1ULL << 14) ✨

Dynamic huffman encoding is supported.

Definition at line 67 of file rte_comp.h.

✨ #define RTE_COMP_FF_XXHASH32_CHECKSUM (1ULL << 15) ✨

xxHash-32 Checksum is supported.

Definition at line 69 of file rte_comp.h.

✨ #define RTE_COMP_FF_LZ4_DICT_ID (1ULL << 16) ✨

LZ4 dictionary ID is supported.

Definition at line 71 of file rte_comp.h.

✨ #define RTE_COMP_FF_LZ4_CONTENT_WITH_CHECKSUM (1ULL << 17) ✨

LZ4 content with checksum is supported.

Definition at line 73 of file rte_comp.h.

✨ #define RTE_COMP_FF_LZ4_CONTENT_SIZE (1ULL << 18) ✨

LZ4 content size is supported.

Definition at line 75 of file rte_comp.h.

✨ #define RTE_COMP_FF_LZ4_BLOCK_INDEPENDENCE (1ULL << 19) ✨

LZ4 block independent is supported.

Definition at line 77 of file rte_comp.h.

✨ #define RTE_COMP_FF_LZ4_BLOCK_WITH_CHECKSUM (1ULL << 20) ✨

LZ4 block with checksum is supported.

Definition at line 79 of file rte_comp.h.

✨ #define RTE_COMP_LEVEL_NONE (0) ✨

Use PMD Default.

Definition at line 150 of file rte_comp.h.

✨ #define RTE_COMP_LEVEL_MIN (1) ✨

Output uncompressed blocks if supported by the specified algorithm.

Definition at line 152 of file rte_comp.h.

✨ #define RTE_COMP_LEVEL_MAX (9) ✨

Use minimum compression level supported by the PMD.

Definition at line 154 of file rte_comp.h.

✨ #define RTE_COMP_LZ4_FLAG_DICT_ID (1 << 0) ✨

Dictionary ID flag. If this flag is set, a 4-byte dict-ID field will be present, after the descriptor flags and the content size.

Definition at line 258 of file rte_comp.h.

✨ #define RTE_COMP_LZ4_FLAG_CONTENT_CHECKSUM (1 << 2) ✨

Content checksum flag. If this flag is set, a 32-bit content checksum will be appended after the end mark.

Definition at line 265 of file rte_comp.h.

✨ #define RTE_COMP_LZ4_FLAG_CONTENT_SIZE (1 << 3) ✨

Content size flag. If this flag is set, the uncompressed size of data included within the frame will be present as an 8-byte unsigned little-endian value, after the flags. Content size usage is optional.

Definition at line 273 of file rte_comp.h.

✨ #define RTE_COMP_LZ4_FLAG_BLOCK_CHECKSUM (1 << 4) ✨

Block checksum flag. If this flag is set, each data block will be followed by a 4-byte checksum, calculated with the xxHash-32 algorithm on the raw (compressed) data block. The intent is to detect data corruption (storage or transmission errors) immediately, before decoding. Block checksum usage is optional.

Definition at line 283 of file rte_comp.h.

✨ #define RTE_COMP_LZ4_FLAG_BLOCK_INDEPENDENCE (1 << 5) ✨

Block independence flag. If this flag is set to 1, blocks are independent. If this flag is set to 0, each block depends on previous ones (up to LZ4 window size, which is 64 KB). In such case, it is necessary to decode all blocks in sequence. Block dependency improves compression ratio, especially for small blocks. On the other hand, it makes random access or multi-threaded decoding impossible.

Definition at line 294 of file rte_comp.h.

🔥 ENUMERATION TYPE DOCUMENTATION 💅

okay bestie, this is the big part — all the enums, all the values, no skipping. let's go 🫶

🌸 enum rte_comp_op_status

the status of a comp operation — like, how did it go? did it slay or did it flop?

✨ Enumerator ✨

  • RTE_COMP_OP_STATUS_SUCCESS — it worked. Operation completed successfully. we love to see it 👑
  • RTE_COMP_OP_STATUS_NOT_PROCESSED — the device hasn't even touched it yet. Operation has not yet been processed by the device. it's giving "unread message" energy 📩
  • RTE_COMP_OP_STATUS_INVALID_ARGS — Operation failed due to invalid arguments in request. the request said something cursed 😭
  • RTE_COMP_OP_STATUS_ERROR — Error handling operation. yeah. that happened. 💀
  • RTE_COMP_OP_STATUS_INVALID_STATE — Operation is invoked in invalid state. wrong vibe, wrong moment, wrong state fr fr 🙈
  • RTE_COMP_OP_STATUS_OUT_OF_SPACE_TERMINATED — Output buffer ran out of space before operation completed. Error case. Application must resubmit all data with a larger output buffer. like, ALL the data, from the start, with a bigger buffer. no shortcuts. 🚨
  • RTE_COMP_OP_STATUS_OUT_OF_SPACE_RECOVERABLE — Output buffer ran out of space before operation completed, but this is not an error case. Output data up to op.produced can be used and next op in the stream should continue on from op.consumed+1. okay so this one's actually fine, breathe 💖
  • RTE_COMP_OP_STATUS_CHECKSUM_VALIDATION_FAILED — Checksum validation failed. Either calculated does checksum not match the one provided or there was an error calculating the checksum. the math said no 🧮💔

Definition at line 83 of file rte_comp.h.

🦋 enum rte_comp_algorithm

Compression Algorithms — pick your fighter ✨

✨ Enumerator ✨

Definition at line 111 of file rte_comp.h.

🎀 enum rte_comp_hash_algorithm

Compression Hash Algorithms — the hash girlies 🌈

✨ Enumerator ✨

  • RTE_COMP_HASH_ALGO_NONE — No hash. nothing. nada. 🚫
  • RTE_COMP_HASH_ALGO_SHA1 — SHA1 hash algorithm
  • RTE_COMP_HASH_ALGO_SHA2_256 — SHA256 hash algorithm of SHA2 family

Definition at line 134 of file rte_comp.h.

💜 enum rte_comp_checksum_type

Use maximum compression level supported by the PMD Compression checksum types — yeah that's literally what the page says, I'm not editing the source bestie 😭 (that phrase really said "two thoughts, one line")

✨ Enumerator ✨

  • RTE_COMP_CHECKSUM_NONE — No checksum generated
  • RTE_COMP_CHECKSUM_CRC32 — Generates a CRC32 checksum, as used by gzip
  • RTE_COMP_CHECKSUM_ADLER32 — Generates an Adler-32 checksum, as used by zlib
  • RTE_COMP_CHECKSUM_CRC32_ADLER32 — Generates both Adler-32 and CRC32 checksums, concatenated. CRC32 is in the lower 32bits, Adler-32 in the upper 32 bits. two checksums, one number, iconic 🫶
  • RTE_COMP_CHECKSUM_XXHASH32 — Generates a xxHash-32 checksum, as used by LZ4. https://github.com/Cyan4973/xxHash/blob/dev/doc/xxhash_spec.md
  • RTE_COMP_CHECKSUM_3GPP_PDCP_UDC — Generates checksum as defined under Uplink Data Compression checksum as defined in the 3GPP PDCP specification

Definition at line 158 of file rte_comp.h.

🧚 enum rte_comp_huffman

Compression Huffman Type - used by DEFLATE algorithm — yes, this is the Huffman thing, and yes it only applies to DEFLATE ✨

✨ Enumerator ✨

  • RTE_COMP_HUFFMAN_DEFAULT — PMD may choose which Huffman codes to use. let the PMD cook 👩‍🍳
  • RTE_COMP_HUFFMAN_FIXED — Use Fixed Huffman codes
  • RTE_COMP_HUFFMAN_DYNAMIC — Use Dynamic Huffman codes

Definition at line 180 of file rte_comp.h.

⭐ enum rte_comp_flush_flag

Compression flush flags — whether we flush, and how much. this one matters SO much bestie, pay attention 💅

✨ Enumerator ✨

  • RTE_COMP_FLUSH_NONE — Data is not flushed. Output may remain in the compressor and be processed during a following op. It may not be possible to decompress output until a later op with some other flush flag has been sent. so like... stuff might just be chilling inside the compressor, unreadable, until you send a later op with a different flush flag 👀
  • RTE_COMP_FLUSH_SYNC — All data should be flushed to output buffer. Output data can be decompressed. However state and history is not cleared, so future operations may use history from this operation.
  • RTE_COMP_FLUSH_FULL — All data should be flushed to output buffer. Output data can be decompressed. State and history data is cleared, so future ops will be independent of ops processed before this.
  • RTE_COMP_FLUSH_FINAL — Same as RTE_COMP_FLUSH_FULL but if op.algo is RTE_COMP_ALGO_DEFLATE then bfinal bit is set in the last block. the grand finale 🎆

Definition at line 190 of file rte_comp.h.

🌈 enum rte_comp_xform_type

Compression transform types — are we zipping or unzipping? important question 🎧

✨ Enumerator ✨

  • RTE_COMP_COMPRESS — Compression service - compress
  • RTE_COMP_DECOMPRESS — Compression service - decompress

Definition at line 213 of file rte_comp.h.

💖 enum rte_comp_op_type

Compression operation type — stateless or stateful, the eternal question 🌸

✨ Enumerator ✨

  • RTE_COMP_OP_STATELESS — All data to be processed is submitted in the op, no state or history from previous ops is used and none will be stored for future ops. Flush flag must be set to either FLUSH_FULL or FLUSH_FINAL. no memory, no baggage, main character energy 🔥
  • RTE_COMP_OP_STATEFUL — There may be more data to be processed after this op, it's part of a stream of data. State and history from previous ops can be used and resulting state and history can be stored for future ops, depending on flush flag.

Definition at line 221 of file rte_comp.h.

🫶 FUNCTION DOCUMENTATION 🫶

here come the functions, bestie. every parameter, every return value, all of it 🎀

💅 void rte_comp_op_free (struct rte_comp_op * op)

Free operation structure — If operation has been allocate from a rte_mempool, then the operation will be returned to the mempool. giving it back to the pool, as one does ✨

🍓 Parameters

  • op — Compress operation pointer allocated from rte_comp_op_alloc(). If op is NULL, no operation is performed.

🌸 struct rte_mempool * rte_comp_op_pool_create (const char * name, unsigned int nb_elts, unsigned int cache_size, uint16_t user_size, int socket_id)

Creates an operation pool. new pool, who dis 💁‍♀️

🍓 Parameters

  • name — Compress pool name
  • nb_elts — Number of elements in pool
  • cache_size — Number of elements to cache on lcore, see rte_mempool_create for further details about cache size
  • user_size — Size of private data to allocate for user with each operation
  • socket_id — Socket to identifier allocate memory on

🍓 Returns

  • On success pointer to mempool
  • On failure NULL

⭐ struct rte_mempool struct rte_comp_op * rte_comp_op_alloc (struct rte_mempool * mempool)

Allocate an operation from a mempool with default parameters set. (yes, that signature is exactly what the page says — I don't make the rules, I just copy them character for character 😭)

🍓 Parameters

  • mempool — Compress operation mempool

🍓 Returns

  • On success returns a valid rte_comp_op structure
  • On failure returns NULL

🦋 int rte_comp_op_bulk_alloc (struct rte_mempool * mempool, struct rte_comp_op ** ops, uint16_t nb_ops)

Bulk allocate operations from a mempool with default parameters set. bulk? in THIS economy? yes bestie, efficiency 💅

🍓 Parameters

  • mempool — Compress operation mempool
  • ops — Array to place allocated operations
  • nb_ops — Number of operations to allocate

🍓 Returns

  • nb_ops: Success, the nb_ops requested was allocated
  • 0: Not enough entries in the mempool; no ops are retrieved. (and by "no ops" they mean none at all, zero, empty-handed 😭)

🧚 void rte_comp_op_bulk_free (struct rte_comp_op ** ops, uint16_t nb_ops)

Bulk free operation structures. If operations have been allocated from an rte_mempool, then the operations will be returned to the mempool. The array entry will be cleared. so satisfying honestly ✨

🍓 Parameters

  • ops — Array of Compress operations
  • nb_ops — Number of operations to free

🌈 const char * rte_comp_get_feature_name (uint64_t flag)

Get the name of a compress service feature flag — you've got a mask, now let's find out what it's called 🎀

🍓 Parameters

  • flag — The mask describing the flag

🍓 Returns

The name of this flag, or NULL if it's not a valid feature flag.

👑 AUTHOR

Generated automatically by Doxygen for DPDK from the source code. — so if the wording is cursed sometimes, that's the robots, not me 🫶

and that's a wrap on rte_comp.h(3) bestie!! 🌸 this whole thing came from the DPDK manpage set, Version 25.11.3, and you just finished reading it all. go forth and compress responsibly. periodt 💅✨

📦 where this page comes from