lib/librte_compressdev/rte_comp.h

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