--- name: "rte_compressdev.h" section: "3" platform: "linux" package: "dpdk-doc" version: "24.11.4-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rte_compressdev.h" --- # rte\_compressdev.h(3) ## NAME rte\_compressdev.h ## SYNOPSIS `#include 'rte_comp.h'`\ ### Data Structures struct **rte\_param\_log2\_range**\ struct **rte\_compressdev\_capabilities**\ struct **rte\_compressdev\_info**\ struct **rte\_compressdev\_stats**\ struct **rte\_compressdev\_config**\ ### Macros \#define **RTE\_COMP\_END\_OF\_CAPABILITIES\_LIST**() { RTE\_COMP\_ALGO\_UNSPECIFIED }\ \#define **RTE\_COMPDEV\_FF\_HW\_ACCELERATED** (1ULL \<\< 0)\ \#define **RTE\_COMPDEV\_FF\_CPU\_SSE** (1ULL \<\< 1)\ \#define **RTE\_COMPDEV\_FF\_CPU\_AVX** (1ULL \<\< 2)\ \#define **RTE\_COMPDEV\_FF\_CPU\_AVX2** (1ULL \<\< 3)\ \#define **RTE\_COMPDEV\_FF\_CPU\_AVX512** (1ULL \<\< 4)\ \#define **RTE\_COMPDEV\_FF\_CPU\_NEON** (1ULL \<\< 5)\ \#define **RTE\_COMPDEV\_FF\_OP\_DONE\_IN\_DEQUEUE** (1ULL \<\< 6)\ ### Functions const char \* **rte\_compressdev\_get\_feature\_name** (uint64\_t flag)\ int **rte\_compressdev\_get\_dev\_id** (const char \*name)\ const char \* **rte\_compressdev\_name\_get** (uint8\_t dev\_id)\ uint8\_t **rte\_compressdev\_count** (void)\ uint8\_t **rte\_compressdev\_devices\_get** (const char \*driver\_name, uint8\_t \*devices, uint8\_t nb\_devices)\ int **rte\_compressdev\_configure** (uint8\_t dev\_id, struct **rte\_compressdev\_config** \*config)\ int **rte\_compressdev\_start** (uint8\_t dev\_id)\ void **rte\_compressdev\_stop** (uint8\_t dev\_id)\ int **rte\_compressdev\_close** (uint8\_t dev\_id)\ int **rte\_compressdev\_queue\_pair\_setup** (uint8\_t dev\_id, uint16\_t queue\_pair\_id, uint32\_t max\_inflight\_ops, int socket\_id)\ uint16\_t **rte\_compressdev\_queue\_pair\_count** (uint8\_t dev\_id)\ int **rte\_compressdev\_stats\_get** (uint8\_t dev\_id, struct **rte\_compressdev\_stats** \*stats)\ void **rte\_compressdev\_stats\_reset** (uint8\_t dev\_id)\ void **rte\_compressdev\_info\_get** (uint8\_t dev\_id, struct **rte\_compressdev\_info** \*dev\_info)\ uint16\_t **rte\_compressdev\_dequeue\_burst** (uint8\_t dev\_id, uint16\_t qp\_id, struct **rte\_comp\_op** \*\*ops, uint16\_t nb\_ops)\ uint16\_t **rte\_compressdev\_enqueue\_burst** (uint8\_t dev\_id, uint16\_t qp\_id, struct **rte\_comp\_op** \*\*ops, uint16\_t nb\_ops)\ int **rte\_compressdev\_stream\_create** (uint8\_t dev\_id, const struct **rte\_comp\_xform** \*xform, void \*\*stream)\ int **rte\_compressdev\_stream\_free** (uint8\_t dev\_id, void \*stream)\ int **rte\_compressdev\_private\_xform\_create** (uint8\_t dev\_id, const struct **rte\_comp\_xform** \*xform, void \*\*private\_xform)\ int **rte\_compressdev\_private\_xform\_free** (uint8\_t dev\_id, void \*private\_xform)\ ## Detailed Description RTE Compression Device APIs. Defines comp device APIs for the provisioning of compression operations. Definition in file **rte\_compressdev.h**. ## Macro Definition Documentation ### #define RTE\_COMP\_END\_OF\_CAPABILITIES\_LIST() { RTE\_COMP\_ALGO\_UNSPECIFIED } Macro used at end of comp PMD list Definition at line **48** of file **rte\_compressdev.h**. ### #define RTE\_COMPDEV\_FF\_HW\_ACCELERATED (1ULL \<\< 0) compression device supported feature flags **Note** New features flags should be added to the end of the list Keep these flags synchronised with **rte\_compressdev\_get\_feature\_name()** Operations are off-loaded to an external hardware accelerator Definition at line **63** of file **rte\_compressdev.h**. ### #define RTE\_COMPDEV\_FF\_CPU\_SSE (1ULL \<\< 1) Utilises CPU SIMD SSE instructions Definition at line **65** of file **rte\_compressdev.h**. ### #define RTE\_COMPDEV\_FF\_CPU\_AVX (1ULL \<\< 2) Utilises CPU SIMD AVX instructions Definition at line **67** of file **rte\_compressdev.h**. ### #define RTE\_COMPDEV\_FF\_CPU\_AVX2 (1ULL \<\< 3) Utilises CPU SIMD AVX2 instructions Definition at line **69** of file **rte\_compressdev.h**. ### #define RTE\_COMPDEV\_FF\_CPU\_AVX512 (1ULL \<\< 4) Utilises CPU SIMD AVX512 instructions Definition at line **71** of file **rte\_compressdev.h**. ### #define RTE\_COMPDEV\_FF\_CPU\_NEON (1ULL \<\< 5) Utilises CPU NEON instructions Definition at line **73** of file **rte\_compressdev.h**. ### #define RTE\_COMPDEV\_FF\_OP\_DONE\_IN\_DEQUEUE (1ULL \<\< 6) A PMD should set this if the bulk of the processing is done during the dequeue. It should leave it cleared if the processing is done during the enqueue (default). Applications can use this as a hint for tuning. Definition at line **79** of file **rte\_compressdev.h**. ## Function Documentation ### const char \* rte\_compressdev\_get\_feature\_name (uint64\_t flag) Get the name of a compress device feature flag. **Parameters** *flag* The mask describing the flag **Returns** The name of this flag, or NULL if it's not a valid feature flag. ### int rte\_compressdev\_get\_dev\_id (const char \* name) Get the device identifier for the named compress device. **Parameters** *name* Device name to select the device structure **Returns** - • Returns compress device identifier on success. - • Return -1 on failure to find named compress device. ### const char \* rte\_compressdev\_name\_get (uint8\_t dev\_id) Get the compress device name given a device identifier. **Parameters** *dev\_id* Compress device identifier **Returns** - • Returns compress device name. - • Returns NULL if compress device is not present. ### uint8\_t rte\_compressdev\_count (void) Get the total number of compress devices that have been successfully initialised. **Returns** - • The total number of usable compress devices. ### uint8\_t rte\_compressdev\_devices\_get (const char \* driver\_name, uint8\_t \* devices, uint8\_t nb\_devices) Get number and identifiers of attached comp devices that use the same compress driver. **Parameters** *driver\_name* Driver name \ *devices* Output devices identifiers \ *nb\_devices* Maximal number of devices **Returns** Returns number of attached compress devices. ### int rte\_compressdev\_configure (uint8\_t dev\_id, struct rte\_compressdev\_config \* config) Configure a device. This function must be invoked first before any other function in the API. This function can also be re-invoked when a device is in the stopped state. **Parameters** *dev\_id* Compress device identifier \ *config* The compress device configuration **Returns** - • 0: Success, device configured. - • \<0: Error code returned by the driver configuration function. ### int rte\_compressdev\_start (uint8\_t dev\_id) Start a device. The device start step is called after configuring the device and setting up its queue pairs. On success, data-path functions exported by the API (enqueue/dequeue, etc) can be invoked. **Parameters** *dev\_id* Compress device identifier **Returns** - • 0: Success, device started. - • \<0: Error code of the driver device start function. ### void rte\_compressdev\_stop (uint8\_t dev\_id) Stop a device. The device can be restarted with a call to **rte\_compressdev\_start()** **Parameters** *dev\_id* Compress device identifier ### int rte\_compressdev\_close (uint8\_t dev\_id) Close an device. The memory allocated in the device gets freed. After calling this function, in order to use the device again, it is required to configure the device again. **Parameters** *dev\_id* Compress device identifier **Returns** - • 0 on successfully closing device - • \<0 on failure to close device ### int rte\_compressdev\_queue\_pair\_setup (uint8\_t dev\_id, uint16\_t queue\_pair\_id, uint32\_t max\_inflight\_ops, int socket\_id) Allocate and set up a receive queue pair for a device. This should only be called when the device is stopped. **Parameters** *dev\_id* Compress device identifier \ *queue\_pair\_id* The index of the queue pairs to set up. The value must be in the range \[0, nb\_queue\_pair - 1\] previously supplied to **rte\_compressdev\_configure()** \ *max\_inflight\_ops* Max number of ops which the qp will have to accommodate simultaneously \ *socket\_id* The *socket\_id* argument is the socket identifier in case of NUMA. The value can be *SOCKET\_ID\_ANY* if there is no NUMA constraint for the DMA memory allocated for the receive queue pair **Returns** - • 0: Success, queue pair correctly set up. - • \<0: Queue pair configuration failed ### uint16\_t rte\_compressdev\_queue\_pair\_count (uint8\_t dev\_id) Get the number of queue pairs on a specific comp device **Parameters** *dev\_id* Compress device identifier **Returns** - • The number of configured queue pairs. ### int rte\_compressdev\_stats\_get (uint8\_t dev\_id, struct rte\_compressdev\_stats \* stats) Retrieve the general I/O statistics of a device. **Parameters** *dev\_id* The identifier of the device \ *stats* A pointer to a structure of type **rte\_compressdev\_stats to be filled with the values of device counters** **Returns** - • **Zero if successful.** - • **Non-zero otherwise.** ### void rte\_compressdev\_stats\_reset (uint8\_t dev\_id) **Reset the general I/O statistics of a device.** **Parameters** *dev\_id* **The identifier of the device.** ### void rte\_compressdev\_info\_get (uint8\_t dev\_id, struct rte\_compressdev\_info \* dev\_info) **Retrieve the contextual information of a device.** **Parameters** *dev\_id* **Compress device identifier** \ *dev\_info* **A pointer to a structure of type rte\_compressdev\_info to be filled with the contextual information of the device** **Note** **The capabilities field of dev\_info is set to point to the first element of an array of struct rte\_compressdev\_capabilities. The element after the last valid element has it's op field set to RTE\_COMP\_ALGO\_UNSPECIFIED.** ### uint16\_t rte\_compressdev\_dequeue\_burst (uint8\_t dev\_id, uint16\_t qp\_id, struct rte\_comp\_op \*\* ops, uint16\_t nb\_ops) **Dequeue a burst of processed compression operations from a queue on the comp device. The dequeued operation are stored in rte\_comp\_op structures whose pointers are supplied in the** *ops* **array.** **The rte\_compressdev\_dequeue\_burst() function returns the number of ops actually dequeued, which is the number of rte\_comp\_op data structures effectively supplied into the** *ops* **array.** **A return value equal to** *nb\_ops* **indicates that the queue contained at least** *nb\_ops* **operations, and this is likely to signify that other processed operations remain in the devices output queue. Applications implementing a 'retrieve as many processed operations as possible' policy can check this specific case and keep invoking the rte\_compressdev\_dequeue\_burst() function until a value less than** *nb\_ops* **is returned.** **The rte\_compressdev\_dequeue\_burst() function does not provide any error notification to avoid the corresponding overhead.** **Note** **: operation ordering is not maintained within the queue pair.** **: In case op status = OUT\_OF\_SPACE\_TERMINATED, op.consumed=0 and the op must be resubmitted with the same input data and a larger output buffer. op.produced is usually 0, but in decompression cases a PMD may return \> 0 and the application may find it useful to inspect that data. This status is only returned on STATELESS ops.** **: In case op status = OUT\_OF\_SPACE\_RECOVERABLE, op.produced can be used and next op in stream should continue on from op.consumed+1 with a fresh output buffer. Consumed=0, produced=0 is an unusual but allowed case. There may be useful state/history stored in the PMD, even though no output was produced yet.** **Parameters** *dev\_id* **Compress device identifier** \ *qp\_id* **The index of the queue pair from which to retrieve processed operations. The value must be in the range \[0, nb\_queue\_pair - 1\] previously supplied to rte\_compressdev\_configure()** \ *ops* **The address of an array of pointers to rte\_comp\_op structures that must be large enough to store** *nb\_ops* **pointers in it** \ *nb\_ops* **The maximum number of operations to dequeue** **Returns** - • **The number of operations actually dequeued, which is the number of pointers to rte\_comp\_op structures effectively supplied to the** *ops* **array.** ### uint16\_t rte\_compressdev\_enqueue\_burst (uint8\_t dev\_id, uint16\_t qp\_id, struct rte\_comp\_op \*\* ops, uint16\_t nb\_ops) **Enqueue a burst of operations for processing on a compression device.** **The rte\_compressdev\_enqueue\_burst() function is invoked to place comp operations on the queue** *qp\_id* **of the device designated by its** *dev\_id***.** **The** *nb\_ops* **parameter is the number of operations to process which are supplied in the** *ops* **array of rte\_comp\_op structures.** **The rte\_compressdev\_enqueue\_burst() function returns the number of operations it actually enqueued for processing. A return value equal to** *nb\_ops* **means that all packets have been enqueued.** **Note** **All compression operations are Out-of-place (OOP) operations, as the size of the output data is different to the size of the input data.** **The rte\_comp\_op contains both input and output parameters and is the vehicle for the application to pass data into and out of the PMD. While an op is inflight, i.e. once it has been enqueued, the private\_xform or stream attached to it and any mbufs or memory referenced by it should not be altered or freed by the application. The PMD may use or change some of this data at any time until it has been returned in a dequeue operation.** **The flush flag only applies to operations which return SUCCESS. In OUT\_OF\_SPACE cases whether STATEFUL or STATELESS, data in dest buffer is as if flush flag was FLUSH\_NONE.** **flush flag only applies in compression direction. It has no meaning for decompression.** **: operation ordering is not maintained within the queue pair.** **Parameters** *dev\_id* **Compress device identifier** \ *qp\_id* **The index of the queue pair on which operations are to be enqueued for processing. The value must be in the range \[0, nb\_queue\_pairs - 1\] previously supplied to** *rte\_compressdev\_configure* \ *ops* **The address of an array of** *nb\_ops* **pointers to rte\_comp\_op structures which contain the operations to be processed** \ *nb\_ops* **The number of operations to process** **Returns** **The number of operations actually enqueued on the device. The return value can be less than the value of the** *nb\_ops* **parameter when the comp devices queue is full or if invalid parameters are specified in a rte\_comp\_op.** ### int rte\_compressdev\_stream\_create (uint8\_t dev\_id, const struct rte\_comp\_xform \* xform, void \*\* stream) **This should alloc a stream from the device's mempool and initialise it. The application should call this API when setting up for the stateful processing of a set of data on a device. The API can be called multiple times to set up a stream for each data set. The handle returned is only for use with ops of op\_type STATEFUL and must be passed to the PMD with every op in the data stream** **Parameters** *dev\_id* **Compress device identifier** \ *xform* **xform data** \ *stream* **Pointer to where PMD's private stream handle should be stored** **Returns** - • **0 if successful and valid stream handle** - • **\<0 in error cases** - • **Returns -EINVAL if input parameters are invalid.** - • **Returns -ENOTSUP if comp device does not support STATEFUL operations.** - • **Returns -ENOTSUP if comp device does not support the comp transform.** - • **Returns -ENOMEM if the private stream could not be allocated.** ### int rte\_compressdev\_stream\_free (uint8\_t dev\_id, void \* stream) **This should clear the stream and return it to the device's mempool.** **Parameters** *dev\_id* **Compress device identifier**\ *stream* **PMD's private stream data** **Returns** - • **0 if successful** - • **\<0 in error cases** - • **Returns -EINVAL if input parameters are invalid.** - • **Returns -ENOTSUP if comp device does not support STATEFUL operations.** - • **Returns -EBUSY if can't free stream as there are inflight operations** ### int rte\_compressdev\_private\_xform\_create (uint8\_t dev\_id, const struct rte\_comp\_xform \* xform, void \*\* private\_xform) **This should alloc a private\_xform from the device's mempool and initialise it. The application should call this API when setting up for stateless processing on a device. If it returns non-shareable, then the appl cannot share this handle with multiple in-flight ops and should call this API again to get a separate handle for every in-flight op. The handle returned is only valid for use with ops of op\_type STATELESS.** **Parameters** *dev\_id* **Compress device identifier** \ *xform* **xform data** \ *private\_xform* **Pointer to where PMD's private\_xform handle should be stored** **Returns** - • **if successful returns 0 and valid private\_xform handle** - • **\<0 in error cases** - • **Returns -EINVAL if input parameters are invalid.** - • **Returns -ENOTSUP if comp device does not support the comp transform.** - • **Returns -ENOMEM if the private\_xform could not be allocated.** ### int rte\_compressdev\_private\_xform\_free (uint8\_t dev\_id, void \* private\_xform) **This should clear the private\_xform and return it to the device's mempool. It is the application's responsibility to ensure that private\_xform data is not cleared while there are still in-flight operations using it.** **Parameters** *dev\_id* **Compress device identifier**\ *private\_xform* **PMD's private\_xform data** **Returns** - • **0 if successful** - • **\<0 in error cases** - • **Returns -EINVAL if input parameters are invalid.** ## Author **Generated automatically by Doxygen for DPDK from the source code.**