1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2017-2018 Intel Corporation
11 * RTE definitions for Data Compression Service
19 #include <rte_mempool.h>
23 * compression service feature flags
25 * @note New features flags should be added to the end of the list
27 * Keep these flags synchronised with rte_comp_get_feature_name()
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
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
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
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.
67 /** Status of comp operation */
68 enum rte_comp_op_status {
69 RTE_COMP_OP_STATUS_SUCCESS = 0,
70 /**< Operation completed successfully */
71 RTE_COMP_OP_STATUS_NOT_PROCESSED,
72 /**< Operation has not yet been processed by the device */
73 RTE_COMP_OP_STATUS_INVALID_ARGS,
74 /**< Operation failed due to invalid arguments in request */
75 RTE_COMP_OP_STATUS_ERROR,
76 /**< Error handling operation */
77 RTE_COMP_OP_STATUS_INVALID_STATE,
78 /**< Operation is invoked in invalid state */
79 RTE_COMP_OP_STATUS_OUT_OF_SPACE_TERMINATED,
80 /**< Output buffer ran out of space before operation completed.
81 * Error case. Application must resubmit all data with a larger
84 RTE_COMP_OP_STATUS_OUT_OF_SPACE_RECOVERABLE,
85 /**< Output buffer ran out of space before operation completed, but this
86 * is not an error case. Output data up to op.produced can be used and
87 * next op in the stream should continue on from op.consumed+1.
91 /** Compression Algorithms */
92 enum rte_comp_algorithm {
93 RTE_COMP_ALGO_UNSPECIFIED = 0,
94 /** No Compression algorithm */
97 * Pass-through, data is copied unchanged from source buffer to
100 RTE_COMP_ALGO_DEFLATE,
101 /**< DEFLATE compression algorithm
102 * https://tools.ietf.org/html/rfc1951
105 /**< LZS compression algorithm
106 * https://tools.ietf.org/html/rfc2395
108 RTE_COMP_ALGO_LIST_END
111 /** Compression Hash Algorithms */
112 enum rte_comp_hash_algorithm {
113 RTE_COMP_HASH_ALGO_NONE = 0,
115 RTE_COMP_HASH_ALGO_SHA1,
116 /**< SHA1 hash algorithm */
117 RTE_COMP_HASH_ALGO_SHA2_256,
118 /**< SHA256 hash algorithm of SHA2 family */
119 RTE_COMP_HASH_ALGO_LIST_END
122 /**< Compression Level.
123 * The number is interpreted by each PMD differently. However, lower numbers
124 * give fastest compression, at the expense of compression ratio while
125 * higher numbers may give better compression ratios but are likely slower.
127 #define RTE_COMP_LEVEL_PMD_DEFAULT (-1)
128 /** Use PMD Default */
129 #define RTE_COMP_LEVEL_NONE (0)
130 /** Output uncompressed blocks if supported by the specified algorithm */
131 #define RTE_COMP_LEVEL_MIN (1)
132 /** Use minimum compression level supported by the PMD */
133 #define RTE_COMP_LEVEL_MAX (9)
134 /** Use maximum compression level supported by the PMD */
136 /** Compression checksum types */
137 enum rte_comp_checksum_type {
138 RTE_COMP_CHECKSUM_NONE,
139 /**< No checksum generated */
140 RTE_COMP_CHECKSUM_CRC32,
141 /**< Generates a CRC32 checksum, as used by gzip */
142 RTE_COMP_CHECKSUM_ADLER32,
143 /**< Generates an Adler-32 checksum, as used by zlib */
144 RTE_COMP_CHECKSUM_CRC32_ADLER32,
145 /**< Generates both Adler-32 and CRC32 checksums, concatenated.
146 * CRC32 is in the lower 32bits, Adler-32 in the upper 32 bits.
151 /** Compression Huffman Type - used by DEFLATE algorithm */
152 enum rte_comp_huffman {
153 RTE_COMP_HUFFMAN_DEFAULT,
154 /**< PMD may choose which Huffman codes to use */
155 RTE_COMP_HUFFMAN_FIXED,
156 /**< Use Fixed Huffman codes */
157 RTE_COMP_HUFFMAN_DYNAMIC,
158 /**< Use Dynamic Huffman codes */
161 /** Compression flush flags */
162 enum rte_comp_flush_flag {
164 /**< Data is not flushed. Output may remain in the compressor and be
165 * processed during a following op. It may not be possible to decompress
166 * output until a later op with some other flush flag has been sent.
169 /**< All data should be flushed to output buffer. Output data can be
170 * decompressed. However state and history is not cleared, so future
171 * operations may use history from this operation.
174 /**< All data should be flushed to output buffer. Output data can be
175 * decompressed. State and history data is cleared, so future
176 * ops will be independent of ops processed before this.
179 /**< Same as RTE_COMP_FLUSH_FULL but if op.algo is RTE_COMP_ALGO_DEFLATE
180 * then bfinal bit is set in the last block.
184 /** Compression transform types */
185 enum rte_comp_xform_type {
187 /**< Compression service - compress */
189 /**< Compression service - decompress */
192 /** Compression operation type */
193 enum rte_comp_op_type {
194 RTE_COMP_OP_STATELESS,
195 /**< All data to be processed is submitted in the op, no state or
196 * history from previous ops is used and none will be stored for future
197 * ops. Flush flag must be set to either FLUSH_FULL or FLUSH_FINAL.
200 /**< There may be more data to be processed after this op, it's part of
201 * a stream of data. State and history from previous ops can be used
202 * and resulting state and history can be stored for future ops,
203 * depending on flush flag.
208 /** Parameters specific to the deflate algorithm */
209 struct rte_comp_deflate_params {
210 enum rte_comp_huffman huffman;
211 /**< Compression huffman encoding type */
214 /** Setup Data for compression */
215 struct rte_comp_compress_xform {
216 enum rte_comp_algorithm algo;
217 /**< Algorithm to use for compress operation */
219 struct rte_comp_deflate_params deflate;
220 /**< Parameters specific to the deflate algorithm */
221 }; /**< Algorithm specific parameters */
223 /**< Compression level */
225 /**< Base two log value of sliding window to be used. If window size
226 * can't be supported by the PMD then it may fall back to a smaller
227 * size. This is likely to result in a worse compression ratio.
229 enum rte_comp_checksum_type chksum;
230 /**< Type of checksum to generate on the uncompressed data */
231 enum rte_comp_hash_algorithm hash_algo;
232 /**< Hash algorithm to be used with compress operation. Hash is always
238 * Setup Data for decompression.
240 struct rte_comp_decompress_xform {
241 enum rte_comp_algorithm algo;
242 /**< Algorithm to use for decompression */
243 enum rte_comp_checksum_type chksum;
244 /**< Type of checksum to generate on the decompressed data */
246 /**< Base two log value of sliding window which was used to generate
247 * compressed data. If window size can't be supported by the PMD then
248 * setup of stream or private_xform should fail.
250 enum rte_comp_hash_algorithm hash_algo;
251 /**< Hash algorithm to be used with decompress operation. Hash is always
257 * Compression transform structure.
259 * This is used to specify the compression transforms required.
260 * Each transform structure can hold a single transform, the type field is
261 * used to specify which transform is contained within the union.
263 struct rte_comp_xform {
264 enum rte_comp_xform_type type;
267 struct rte_comp_compress_xform compress;
268 /**< xform for compress operation */
269 struct rte_comp_decompress_xform decompress;
270 /**< decompress xform */
275 * Compression Operation.
277 * This structure contains data relating to performing a compression
278 * operation on the referenced mbuf data buffers.
280 * Comp operations are enqueued and dequeued in comp PMDs using the
281 * rte_compressdev_enqueue_burst() / rte_compressdev_dequeue_burst() APIs
284 enum rte_comp_op_type op_type;
287 /**< Stateless private PMD data derived from an rte_comp_xform.
288 * A handle returned by rte_compressdev_private_xform_create()
289 * must be attached to operations of op_type RTE_COMP_STATELESS.
292 /**< Private PMD data derived initially from an rte_comp_xform,
293 * which holds state and history data and evolves as operations
294 * are processed. rte_compressdev_stream_create() must be called
295 * on a device for all STATEFUL data streams and the resulting
296 * stream attached to the one or more operations associated
297 * with the data stream.
298 * All operations in a stream must be sent to the same device.
302 struct rte_mempool *mempool;
303 /**< Pool from which operation is allocated */
304 rte_iova_t iova_addr;
305 /**< IOVA address of this operation */
306 struct rte_mbuf *m_src;
308 * The total size of the input buffer(s) can be retrieved using
309 * rte_pktmbuf_data_len(m_src). The max data size which can fit in a
310 * single mbuf is limited by the uint16_t rte_mbuf.data_len to 64k-1.
311 * If the input data is bigger than this it can be passed to the PMD in
312 * a chain of mbufs if the PMD's capabilities indicate it supports this.
314 struct rte_mbuf *m_dst;
315 /**< destination mbuf
316 * The total size of the output buffer(s) can be retrieved using
317 * rte_pktmbuf_data_len(m_dst). The max data size which can fit in a
318 * single mbuf is limited by the uint16_t rte_mbuf.data_len to 64k-1.
319 * If the output data is expected to be bigger than this a chain of
320 * mbufs can be passed to the PMD if the PMD's capabilities indicate
326 /**< Starting point for compression or decompression,
327 * specified as number of bytes from start of packet in
329 * This offset starts from the first segment
330 * of the buffer, in case the m_src is a chain of mbufs.
331 * Starting point for checksum generation in compress direction.
334 /**< The length, in bytes, of the data in source buffer
335 * to be compressed or decompressed.
336 * Also the length of the data over which the checksum
337 * should be generated in compress direction
342 /**< Starting point for writing output data, specified as
343 * number of bytes from start of packet in dest
345 * This offset starts from the first segment
346 * of the buffer, in case the m_dst is a chain of mbufs.
347 * Starting point for checksum generation in
348 * decompress direction.
353 /**< Output buffer to store hash output, if enabled in xform.
354 * Buffer would contain valid value only after an op with
355 * flush flag = RTE_COMP_FLUSH_FULL/FLUSH_FINAL is processed
358 * Length of buffer should be contiguous and large enough to
359 * accommodate digest produced by specific hash algo.
361 rte_iova_t iova_addr;
362 /**< IO address of the buffer */
364 enum rte_comp_flush_flag flush_flag;
365 /**< Defines flush characteristics for the output data.
366 * Only applicable in compress direction
368 uint64_t input_chksum;
369 /**< An input checksum can be provided to generate a
370 * cumulative checksum across sequential blocks in a STATELESS stream.
371 * Checksum type is as specified in xform chksum_type
373 uint64_t output_chksum;
374 /**< If a checksum is generated it will be written in here.
375 * Checksum type is as specified in xform chksum_type.
378 /**< The number of bytes from the source buffer
379 * which were compressed/decompressed.
382 /**< The number of bytes written to the destination buffer
383 * which were compressed/decompressed.
385 uint64_t debug_status;
387 * Status of the operation is returned in the status param.
388 * This field allows the PMD to pass back extra
389 * pmd-specific debug information. Value is not defined on the API.
393 * Operation status - use values from enum rte_comp_status.
395 * RTE_COMP_OP_STATUS_NOT_PROCESSED on allocation from mempool and
396 * will be set to RTE_COMP_OP_STATUS_SUCCESS after operation
397 * is successfully processed by a PMD
399 } __rte_cache_aligned;
402 * Creates an operation pool
407 * Number of elements in pool
409 * Number of elements to cache on lcore, see
410 * *rte_mempool_create* for further details about cache size
412 * Size of private data to allocate for user with each operation
414 * Socket to identifier allocate memory on
416 * - On success pointer to mempool
419 struct rte_mempool * __rte_experimental
420 rte_comp_op_pool_create(const char *name,
421 unsigned int nb_elts, unsigned int cache_size,
422 uint16_t user_size, int socket_id);
425 * Allocate an operation from a mempool with default parameters set
428 * Compress operation mempool
431 * - On success returns a valid rte_comp_op structure
432 * - On failure returns NULL
434 struct rte_comp_op * __rte_experimental
435 rte_comp_op_alloc(struct rte_mempool *mempool);
438 * Bulk allocate operations from a mempool with default parameters set
441 * Compress operation mempool
443 * Array to place allocated operations
445 * Number of operations to allocate
448 * - -ENOENT: Not enough entries in the mempool; no ops are retrieved.
450 int __rte_experimental
451 rte_comp_op_bulk_alloc(struct rte_mempool *mempool,
452 struct rte_comp_op **ops, uint16_t nb_ops);
455 * Free operation structure
456 * If operation has been allocate from a rte_mempool, then the operation will
457 * be returned to the mempool.
462 void __rte_experimental
463 rte_comp_op_free(struct rte_comp_op *op);
466 * Get the name of a compress service feature flag
469 * The mask describing the flag
472 * The name of this flag, or NULL if it's not a valid feature flag.
474 const char * __rte_experimental
475 rte_comp_get_feature_name(uint64_t flag);
481 #endif /* _RTE_COMP_H_ */