.TH "rte_compressdev.h" 3 "Version 25.11.0" "DPDK" \" -*- nroff -*- .ad l .nh .SH NAME rte_compressdev.h .SH SYNOPSIS .br .PP \fR#include 'rte_comp\&.h'\fP .br .SS "Data Structures" .in +1c .ti -1c .RI "struct \fBrte_param_log2_range\fP" .br .ti -1c .RI "struct \fBrte_compressdev_capabilities\fP" .br .ti -1c .RI "struct \fBrte_compressdev_info\fP" .br .ti -1c .RI "struct \fBrte_compressdev_stats\fP" .br .ti -1c .RI "struct \fBrte_compressdev_config\fP" .br .in -1c .SS "Macros" .in +1c .ti -1c .RI "#define \fBRTE_COMP_END_OF_CAPABILITIES_LIST\fP()" .br .ti -1c .RI "#define \fBRTE_COMPDEV_FF_HW_ACCELERATED\fP (1ULL << 0)" .br .ti -1c .RI "#define \fBRTE_COMPDEV_FF_CPU_SSE\fP (1ULL << 1)" .br .ti -1c .RI "#define \fBRTE_COMPDEV_FF_CPU_AVX\fP (1ULL << 2)" .br .ti -1c .RI "#define \fBRTE_COMPDEV_FF_CPU_AVX2\fP (1ULL << 3)" .br .ti -1c .RI "#define \fBRTE_COMPDEV_FF_CPU_AVX512\fP (1ULL << 4)" .br .ti -1c .RI "#define \fBRTE_COMPDEV_FF_CPU_NEON\fP (1ULL << 5)" .br .ti -1c .RI "#define \fBRTE_COMPDEV_FF_OP_DONE_IN_DEQUEUE\fP (1ULL << 6)" .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "const char * \fBrte_compressdev_get_feature_name\fP (uint64_t flag)" .br .ti -1c .RI "int \fBrte_compressdev_get_dev_id\fP (const char *name)" .br .ti -1c .RI "const char * \fBrte_compressdev_name_get\fP (uint8_t dev_id)" .br .ti -1c .RI "uint8_t \fBrte_compressdev_count\fP (void)" .br .ti -1c .RI "uint8_t \fBrte_compressdev_devices_get\fP (const char *driver_name, uint8_t *devices, uint8_t nb_devices)" .br .ti -1c .RI "int \fBrte_compressdev_configure\fP (uint8_t dev_id, struct \fBrte_compressdev_config\fP *config)" .br .ti -1c .RI "int \fBrte_compressdev_start\fP (uint8_t dev_id)" .br .ti -1c .RI "void \fBrte_compressdev_stop\fP (uint8_t dev_id)" .br .ti -1c .RI "int \fBrte_compressdev_close\fP (uint8_t dev_id)" .br .ti -1c .RI "int \fBrte_compressdev_queue_pair_setup\fP (uint8_t dev_id, uint16_t queue_pair_id, uint32_t max_inflight_ops, int socket_id)" .br .ti -1c .RI "uint16_t \fBrte_compressdev_queue_pair_count\fP (uint8_t dev_id)" .br .ti -1c .RI "int \fBrte_compressdev_stats_get\fP (uint8_t dev_id, struct \fBrte_compressdev_stats\fP *stats)" .br .ti -1c .RI "void \fBrte_compressdev_stats_reset\fP (uint8_t dev_id)" .br .ti -1c .RI "void \fBrte_compressdev_info_get\fP (uint8_t dev_id, struct \fBrte_compressdev_info\fP *dev_info)" .br .ti -1c .RI "uint16_t \fBrte_compressdev_dequeue_burst\fP (uint8_t dev_id, uint16_t qp_id, struct \fBrte_comp_op\fP **ops, uint16_t nb_ops)" .br .ti -1c .RI "uint16_t \fBrte_compressdev_enqueue_burst\fP (uint8_t dev_id, uint16_t qp_id, struct \fBrte_comp_op\fP **ops, uint16_t nb_ops)" .br .ti -1c .RI "int \fBrte_compressdev_stream_create\fP (uint8_t dev_id, const struct \fBrte_comp_xform\fP *xform, void **stream)" .br .ti -1c .RI "int \fBrte_compressdev_stream_free\fP (uint8_t dev_id, void *stream)" .br .ti -1c .RI "int \fBrte_compressdev_private_xform_create\fP (uint8_t dev_id, const struct \fBrte_comp_xform\fP *xform, void **private_xform)" .br .ti -1c .RI "int \fBrte_compressdev_private_xform_free\fP (uint8_t dev_id, void *private_xform)" .br .in -1c .SH "Detailed Description" .PP RTE Compression Device APIs\&. .PP Defines comp device APIs for the provisioning of compression operations\&. .PP Definition in file \fBrte_compressdev\&.h\fP\&. .SH "Macro Definition Documentation" .PP .SS "#define RTE_COMP_END_OF_CAPABILITIES_LIST()" \fBValue:\fP .nf { RTE_COMP_ALGO_UNSPECIFIED } .PP .fi Macro used at end of comp PMD list .PP Definition at line \fB48\fP of file \fBrte_compressdev\&.h\fP\&. .SS "#define RTE_COMPDEV_FF_HW_ACCELERATED (1ULL << 0)" compression device supported feature flags .PP \fBNote\fP .RS 4 New features flags should be added to the end of the list .RE .PP Keep these flags synchronised with \fBrte_compressdev_get_feature_name()\fP Operations are off-loaded to an external hardware accelerator .PP Definition at line \fB62\fP of file \fBrte_compressdev\&.h\fP\&. .SS "#define RTE_COMPDEV_FF_CPU_SSE (1ULL << 1)" Utilises CPU SIMD SSE instructions .PP Definition at line \fB64\fP of file \fBrte_compressdev\&.h\fP\&. .SS "#define RTE_COMPDEV_FF_CPU_AVX (1ULL << 2)" Utilises CPU SIMD AVX instructions .PP Definition at line \fB66\fP of file \fBrte_compressdev\&.h\fP\&. .SS "#define RTE_COMPDEV_FF_CPU_AVX2 (1ULL << 3)" Utilises CPU SIMD AVX2 instructions .PP Definition at line \fB68\fP of file \fBrte_compressdev\&.h\fP\&. .SS "#define RTE_COMPDEV_FF_CPU_AVX512 (1ULL << 4)" Utilises CPU SIMD AVX512 instructions .PP Definition at line \fB70\fP of file \fBrte_compressdev\&.h\fP\&. .SS "#define RTE_COMPDEV_FF_CPU_NEON (1ULL << 5)" Utilises CPU NEON instructions .PP Definition at line \fB72\fP of file \fBrte_compressdev\&.h\fP\&. .SS "#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\&. .PP Definition at line \fB74\fP of file \fBrte_compressdev\&.h\fP\&. .SH "Function Documentation" .PP .SS "const char * rte_compressdev_get_feature_name (uint64_t flag)" Get the name of a compress device feature flag\&. .PP \fBParameters\fP .RS 4 \fIflag\fP The mask describing the flag .RE .PP \fBReturns\fP .RS 4 The name of this flag, or NULL if it's not a valid feature flag\&. .RE .PP .SS "int rte_compressdev_get_dev_id (const char * name)" Get the device identifier for the named compress device\&. .PP \fBParameters\fP .RS 4 \fIname\fP Device name to select the device structure .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Returns compress device identifier on success\&. .IP "\(bu" 2 Return -1 on failure to find named compress device\&. .PP .RE .PP .SS "const char * rte_compressdev_name_get (uint8_t dev_id)" Get the compress device name given a device identifier\&. .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Returns compress device name\&. .IP "\(bu" 2 Returns NULL if compress device is not present\&. .PP .RE .PP .SS "uint8_t rte_compressdev_count (void )" Get the total number of compress devices that have been successfully initialised\&. .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 The total number of usable compress devices\&. .PP .RE .PP .SS "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\&. .PP \fBParameters\fP .RS 4 \fIdriver_name\fP Driver name .br \fIdevices\fP Output devices identifiers .br \fInb_devices\fP Maximal number of devices .RE .PP \fBReturns\fP .RS 4 Returns number of attached compress devices\&. .RE .PP .SS "int rte_compressdev_configure (uint8_t dev_id, struct \fBrte_compressdev_config\fP * config)" Configure a device\&. .PP 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\&. .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .br \fIconfig\fP The compress device configuration .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success, device configured\&. .IP "\(bu" 2 <0: Error code returned by the driver configuration function\&. .PP .RE .PP .SS "int rte_compressdev_start (uint8_t dev_id)" Start a device\&. .PP 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\&. .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success, device started\&. .IP "\(bu" 2 <0: Error code of the driver device start function\&. .PP .RE .PP .SS "void rte_compressdev_stop (uint8_t dev_id)" Stop a device\&. The device can be restarted with a call to \fBrte_compressdev_start()\fP .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .RE .PP .SS "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\&. .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0 on successfully closing device .IP "\(bu" 2 <0 on failure to close device .PP .RE .PP .SS "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\&. .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .br \fIqueue_pair_id\fP The index of the queue pairs to set up\&. The value must be in the range [0, nb_queue_pair - 1] previously supplied to \fBrte_compressdev_configure()\fP .br \fImax_inflight_ops\fP Max number of ops which the qp will have to accommodate simultaneously .br \fIsocket_id\fP The \fIsocket_id\fP argument is the socket identifier in case of NUMA\&. The value can be \fISOCKET_ID_ANY\fP if there is no NUMA constraint for the DMA memory allocated for the receive queue pair .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0: Success, queue pair correctly set up\&. .IP "\(bu" 2 <0: Queue pair configuration failed .PP .RE .PP .SS "uint16_t rte_compressdev_queue_pair_count (uint8_t dev_id)" Get the number of queue pairs on a specific comp device .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 The number of configured queue pairs\&. .PP .RE .PP .SS "int rte_compressdev_stats_get (uint8_t dev_id, struct \fBrte_compressdev_stats\fP * stats)" Retrieve the general I/O statistics of a device\&. .PP \fBParameters\fP .RS 4 \fIdev_id\fP The identifier of the device .br \fIstats\fP A pointer to a structure of type \fI\fBrte_compressdev_stats\fP\fP to be filled with the values of device counters .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Zero if successful\&. .IP "\(bu" 2 Non-zero otherwise\&. .PP .RE .PP .SS "void rte_compressdev_stats_reset (uint8_t dev_id)" Reset the general I/O statistics of a device\&. .PP \fBParameters\fP .RS 4 \fIdev_id\fP The identifier of the device\&. .RE .PP .SS "void rte_compressdev_info_get (uint8_t dev_id, struct \fBrte_compressdev_info\fP * dev_info)" Retrieve the contextual information of a device\&. .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .br \fIdev_info\fP A pointer to a structure of type \fI\fBrte_compressdev_info\fP\fP to be filled with the contextual information of the device .RE .PP \fBNote\fP .RS 4 The capabilities field of dev_info is set to point to the first element of an array of struct \fBrte_compressdev_capabilities\fP\&. The element after the last valid element has it's op field set to RTE_COMP_ALGO_UNSPECIFIED\&. .RE .PP .SS "uint16_t rte_compressdev_dequeue_burst (uint8_t dev_id, uint16_t qp_id, struct \fBrte_comp_op\fP ** 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 \fI\fBrte_comp_op\fP\fP structures whose pointers are supplied in the \fIops\fP array\&. .PP The \fBrte_compressdev_dequeue_burst()\fP function returns the number of ops actually dequeued, which is the number of \fI\fBrte_comp_op\fP\fP data structures effectively supplied into the \fIops\fP array\&. .PP A return value equal to \fInb_ops\fP indicates that the queue contained at least \fInb_ops\fP 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 \fBrte_compressdev_dequeue_burst()\fP function until a value less than \fInb_ops\fP is returned\&. .PP The \fBrte_compressdev_dequeue_burst()\fP function does not provide any error notification to avoid the corresponding overhead\&. .PP \fBNote\fP .RS 4 : operation ordering is not maintained within the queue pair\&. .PP : 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\&. .PP : 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\&. .RE .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .br \fIqp_id\fP 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 \fBrte_compressdev_configure()\fP .br \fIops\fP The address of an array of pointers to \fI\fBrte_comp_op\fP\fP structures that must be large enough to store \fInb_ops\fP pointers in it .br \fInb_ops\fP The maximum number of operations to dequeue .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 The number of operations actually dequeued, which is the number of pointers to \fI\fBrte_comp_op\fP\fP structures effectively supplied to the \fIops\fP array\&. .PP .RE .PP .SS "uint16_t rte_compressdev_enqueue_burst (uint8_t dev_id, uint16_t qp_id, struct \fBrte_comp_op\fP ** ops, uint16_t nb_ops)" Enqueue a burst of operations for processing on a compression device\&. .PP The \fBrte_compressdev_enqueue_burst()\fP function is invoked to place comp operations on the queue \fIqp_id\fP of the device designated by its \fIdev_id\fP\&. .PP The \fInb_ops\fP parameter is the number of operations to process which are supplied in the \fIops\fP array of \fI\fBrte_comp_op\fP\fP structures\&. .PP The \fBrte_compressdev_enqueue_burst()\fP function returns the number of operations it actually enqueued for processing\&. A return value equal to \fInb_ops\fP means that all packets have been enqueued\&. .PP \fBNote\fP .RS 4 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\&. .PP The \fBrte_comp_op\fP 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\&. .PP 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\&. .PP flush flag only applies in compression direction\&. It has no meaning for decompression\&. .PP : operation ordering is not maintained within the queue pair\&. .RE .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .br \fIqp_id\fP 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 \fIrte_compressdev_configure\fP .br \fIops\fP The address of an array of \fInb_ops\fP pointers to \fI\fBrte_comp_op\fP\fP structures which contain the operations to be processed .br \fInb_ops\fP The number of operations to process .RE .PP \fBReturns\fP .RS 4 The number of operations actually enqueued on the device\&. The return value can be less than the value of the \fInb_ops\fP parameter when the comp devices queue is full or if invalid parameters are specified in a \fI\fBrte_comp_op\fP\fP\&. .RE .PP .SS "int rte_compressdev_stream_create (uint8_t dev_id, const struct \fBrte_comp_xform\fP * 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 .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .br \fIxform\fP xform data .br \fIstream\fP Pointer to where PMD's private stream handle should be stored .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0 if successful and valid stream handle .IP "\(bu" 2 <0 in error cases .IP "\(bu" 2 Returns -EINVAL if input parameters are invalid\&. .IP "\(bu" 2 Returns -ENOTSUP if comp device does not support STATEFUL operations\&. .IP "\(bu" 2 Returns -ENOTSUP if comp device does not support the comp transform\&. .IP "\(bu" 2 Returns -ENOMEM if the private stream could not be allocated\&. .PP .RE .PP .SS "int rte_compressdev_stream_free (uint8_t dev_id, void * stream)" This should clear the stream and return it to the device's mempool\&. .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .br \fIstream\fP PMD's private stream data .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0 if successful .IP "\(bu" 2 <0 in error cases .IP "\(bu" 2 Returns -EINVAL if input parameters are invalid\&. .IP "\(bu" 2 Returns -ENOTSUP if comp device does not support STATEFUL operations\&. .IP "\(bu" 2 Returns -EBUSY if can't free stream as there are inflight operations .PP .RE .PP .SS "int rte_compressdev_private_xform_create (uint8_t dev_id, const struct \fBrte_comp_xform\fP * 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\&. .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .br \fIxform\fP xform data .br \fIprivate_xform\fP Pointer to where PMD's private_xform handle should be stored .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 if successful returns 0 and valid private_xform handle .IP "\(bu" 2 <0 in error cases .IP "\(bu" 2 Returns -EINVAL if input parameters are invalid\&. .IP "\(bu" 2 Returns -ENOTSUP if comp device does not support the comp transform\&. .IP "\(bu" 2 Returns -ENOMEM if the private_xform could not be allocated\&. .PP .RE .PP .SS "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\&. .PP \fBParameters\fP .RS 4 \fIdev_id\fP Compress device identifier .br \fIprivate_xform\fP PMD's private_xform data .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0 if successful .IP "\(bu" 2 <0 in error cases .IP "\(bu" 2 Returns -EINVAL if input parameters are invalid\&. .PP .RE .PP .SH "Author" .PP Generated automatically by Doxygen for DPDK from the source code\&.