diff options
Diffstat (limited to 'doc/users-guide/users-guide-comp.adoc')
| -rw-r--r-- | doc/users-guide/users-guide-comp.adoc | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/doc/users-guide/users-guide-comp.adoc b/doc/users-guide/users-guide-comp.adoc new file mode 100644 index 000000000..11a39a0c2 --- /dev/null +++ b/doc/users-guide/users-guide-comp.adoc @@ -0,0 +1,168 @@ +== Compression services +ODP provides APIs to perform compression and decompression operations required +by applications. ODP compression APIs are session based and provide +compression algorithm offload services, with and without associated +integrity hashing. This section covers the main compression APIs. + +ODP provides support for the following compression algorithms: + +`ODP_COMP_ALG_NONE`:: +The null compression algorithm. Used for testing as well as to +specify hash-only operations. +`ODP_COMP_ALG_DEFLATE`:: +The deflate compression algorithm specified by +https://www.ietf.org/rfc/rfc1951.txt[RFC 1951]. +`ODP_COMP_ALG_ZLIB`:: +The ZLIB compression algorithm specified by +https://www.ietf.org/rfc/rfc1950.txt[RFC 1950]. +`ODP_COMP_ALG_LZS`:: +The LZS compression algorithm as specified by ANSI X3.241. + +The following hash algorithms are also defined to be used in conjunction +with these compression algorithms: + +`ODP_COMP_HASH_ALG_NONE`:: +A dummy that specifies no associated hashing is to be performed. +`ODP_COMP_HASH_ALG_SHA1`:: +SHA-1 hashing with a 64-bit digest length. +`ODP_COMP_HASH_ALG_SHA256`:: +SHA-2 hashing with a 256-bit digest length. + +=== Compression Sessions +ODP compression services are session based and operate on input packets and +deliver output packets. A compression session (`odp_comp_session_t`) provides +the context for controlling the operations performed on packets. All of the +packets processed by a session share the parameters that define the +session. + +ODP supports synchronous and asynchronous compression sessions. For +asynchronous sessions, the output of a compression operation is posted to +a queue defined as the completion queue in its session parameters. + +Other session parameters include: the type of operation (compression or +decompression), the operating mode (synchronous or asynchronous), the +compression and hashing algorithms to be used, as well as any parameters +needed by those algorithms to configure them. For asynchronous compression +sessions, the application also specifies whether queue order must be +maintained. Additional throughput may be achieved in some implementations if +strict ordering is not required. + +The parameters that describe the characteristics of a compression session +are encoded in the `odp_comp_session_param_t` struct that is passed to the +`odp_comp_session_create()` API. A successful call returns an +`odp_comp_session_t` handle that is then used as an input parameter to +compression operation calls. + +When an application is finished with a compression session, the +`odp_comp_session_destroy()` API is used to release the resources +associated with an `odp_comp_session_t`. + +=== Compression operations +After session creation, a compression operation can be applied to a packet +in one of two ways: synchronous and asynchronous, depending on how the +session was created. + +==== Synchronous compression operations +Synchronous compression operations take the following form: + +.Invoking synchronous compression operations +[source,c] +----- +int odp_comp_op(const odp_packet_t pkt_in[], odp_packet_t pkt_out[], + int num_pkt, const odp_comp_packet_op_param_t param[]); +----- +An input packet array is compressed/decompressed into a supplied output +packet array under the control of a supplied parameter struct. + +The supplied `odp_comp_packet_op_param_t` struct looks as follows: + +.ODP compression parameter structure +[source,c] +----- +/** + * Compression per packet operation parameters + */ +typedef struct odp_comp_packet_op_param_t { + /** Session handle */ + odp_comp_session_t session; + + /** Input data range to process. where, + * + * offset - starting offset + * length - length of data for compression operation + * */ + odp_packet_data_range_t in_data_range; + + /** Output packet data range. + * Indicates where processed packet will be written. where, + * + * offset - starting offset + * length - length of buffer available for output + * + * Output packet data is not modified outside of this provided data + * range. If output data length is not sufficient for compression + * operation ODP_COMP_STATUS_OUT_OF_SPACE_TERM error will occur + */ + odp_packet_data_range_t out_data_range; +} odp_comp_packet_op_param_t; +----- +Note that this struct points to the session used to control the operation and +specifies the input and output packet data ranges to be used for the +operation. For input, the output data range must be sufficiently sized to +contain the result of the operation to avoid an out of space error. Upon +output, this range is updated to reflect the actual data written. This +information can then be used to trim off any excess padding before +continuing processing of the output packet(s). + +==== Asynchronous compression operations +Asynchronous compression operations are invoked with a slightly +different API: + +.Invoking asynchronous compression operations +[source,c] +----- +int odp_comp_op_enq(const odp_packet_t pkt_in[], odp_packet_t pkt_out[], + int num_pkt, const odp_comp_packet_op_param_t param[]); +----- +Here the session pointed to by the `odp_comp_packet_op_param_t` indicates +the completion queue to be used for the operation, so a zero return from +`odp_comp_op_enq()` means only that the operation was successfully +initiated. + +The resulting completion queue can then be polled either directly +via `odp_queue_deq()` or indirectly via the scheduler. The result is +presented as an event of type `ODP_EVENT_PACKET` with subtype +`ODP_EVENT_PACKET_COMP`. + +When receiving this event, the `odp_comp_packet_from_event()` API is used to +convert the event into a usable `odp_packet_t`, and the `odp_comp_result()` +API is used to retrieve the `odp_comp_packet_result_t` metadata associated +with this packet. This struct looks as follows: + +.Compression output result +[source,c] +----- +/** + * Compression packet operation result + */ +typedef struct odp_comp_packet_result_t { + /** Operation status code */ + odp_comp_status_t status; + + /** Input packet handle */ + odp_packet_t pkt_in; + + /** Output packet data range + * Specifies offset and length of data resulting from compression + * operation. When hashing is configured output_data_range.len equals + * length of output data + length of digest. + */ + odp_packet_data_range_t output_data_range; +} odp_comp_packet_result_t; +----- +Note that if the originating `odp_comp_op_enq()` call specified an array of +input packets, each of these generates a separate result event. The order of +these events on the completion queue associated with the compression session is +controlled by the session's `packet_order` flag. If this flag is set then the +results will be in the same order as the original input list. If not, then +results are free to be reordered to make them available as soon as possible. |