rte_compressdev.h(3)

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

🌸 rte_compressdev.h(3) — Library Functions Manual 🌸

okay bestie, sit DOWN, because we're about to talk about the RTE Compression Device APIs and honestly? it's giving infrastructure. it's giving plumbing that makes the whole building work. no cap. 💅

✨ NAME ✨

rte_compressdev.h — the header you include when you want to do compression stuff in DPDK, periodt. 🎀

🦋 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()
  • #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()

Value:

{ 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 62 of file rte_compressdev.h.

🌈 #define RTE_COMPDEV_FF_CPU_SSE (1ULL << 1)

Utilises CPU SIMD SSE instructions

Definition at line 64 of file rte_compressdev.h.

🌈 #define RTE_COMPDEV_FF_CPU_AVX (1ULL << 2)

Utilises CPU SIMD AVX instructions

Definition at line 66 of file rte_compressdev.h.

🌈 #define RTE_COMPDEV_FF_CPU_AVX2 (1ULL << 3)

Utilises CPU SIMD AVX2 instructions

Definition at line 68 of file rte_compressdev.h.

🌈 #define RTE_COMPDEV_FF_CPU_AVX512 (1ULL << 4)

Utilises CPU SIMD AVX512 instructions

Definition at line 70 of file rte_compressdev.h.

🌈 #define RTE_COMPDEV_FF_CPU_NEON (1ULL << 5)

Utilises CPU NEON instructions

Definition at line 72 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 74 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. 😭 (yes, again again, we said what we said)

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. (iconic behaviour tbh, silently efficient ✨)

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.

to be continued, bestie — the rest of the functions are coming up in part 2 💜

okay so we're picking right back up inside the rte_compressdev_dequeue_burst() notes — no heading, we been here, we're just finishing the vibe check 💅

  • bestie listen: in case op status = OUT_OF_SPACE_RECOVERABLE, op.produced can be used, and the next op in the 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 you're pulling processed operations from. It has to be in the range [0, nb_queue_pair - 1], and you gotta have already handed those values to rte_compressdev_configure()
  • ops — the address of an array of pointers to rte_comp_op structures, and it has to be big enough to hold nb_ops pointers in it
  • nb_ops — the maximum number of operations to dequeue

Returns

  • the number of operations actually dequeued, which is literally just the number of pointers to rte_comp_op structures that actually made it into the ops array

rte_compressdev_enqueue_burst

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. 🚀

You call rte_compressdev_enqueue_burst() to place comp operations on the queue qp_id of the device that its dev_id designates. That's the whole move, no cap.

The nb_ops parameter is the number of operations to process, which are supplied in the ops array of rte_comp_op structures.

So then — rte_compressdev_enqueue_burst() tells you back the number of operations it actually enqueued for processing. If the return value equals nb_ops, then all the packets have been enqueued. slay ✨

Note — read this part, bestie, it's lowkey the whole assignment: - All compression operations are Out-of-place (OOP) operations, because the size of the output data is different from the size of the input data. like they are literally not the same size, that's the point. - The rte_comp_op holds both input and output parameters, and it's 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, plus 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 — the data in the dest buffer is as if the flush flag was FLUSH_NONE. - The flush flag only applies in the compression direction. It has no meaning for decompression. periodt. - Operation ordering is not maintained within the queue pair. 💀

Parameters

  • dev_id — Compress device identifier
  • qp_id — the index of the queue pair the operations are gonna be enqueued onto for processing. Gotta 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. Heads up: this return value can be less than the value of the nb_ops parameter when the comp device's queue is full, or if invalid parameters are specified in a rte_comp_op. 😭

rte_compressdev_stream_create

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. 🎀

Call this API when you're setting up for the stateful processing of a set of data on a device. You can call it multiple times to set up a stream for each data set — no limits, we love that for you. The handle you get back is only for use with ops of op_type STATEFUL, and it must be passed to the PMD with every op in the data stream. every. single. one.

Parameters

  • dev_id — Compress device identifier
  • xform — xform data
  • stream — pointer to where the 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 the comp device does not support STATEFUL operations.
  • Returns -ENOTSUP if the comp device does not support the comp transform.
  • Returns -ENOMEM if the private stream could not be allocated.

rte_compressdev_stream_free

int rte_compressdev_stream_free (uint8_t dev_id, void * stream)

This should clear the stream and return it to the device's mempool. bye bestie, thanks for the memories 🦋

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 the comp device does not support STATEFUL operations.
  • Returns -EBUSY if it can't free the stream because there are inflight operations. 😭 the ops are still in there!!

rte_compressdev_private_xform_create

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. 🌸

Call this API when you're 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. one handle per op, no sharing, we don't do that here. 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 the PMD's private_xform handle should be stored

Returns

  • if successful, returns 0 and a valid private_xform handle ⭐
  • <0 in error cases
  • Returns -EINVAL if input parameters are invalid.
  • Returns -ENOTSUP if the comp device does not support the comp transform.
  • Returns -ENOMEM if the private_xform could not be allocated.

rte_compressdev_private_xform_free

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. 🫶

And this part is on you, bestie: it is the application's responsibility to make sure that private_xform data is not cleared while there are still in-flight operations using it. iykyk. 💀

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. (not me being a whole author, it's the robots 💖)

and that's the whole page, bestie!! 🎀 this was DPDK, version 25.11.3, page rte_compressdev.h(3) — go forth and compress, main character energy only, no cap ✨💅🔥

📦 where this page comes from