This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "".
The branch, api-next has been updated via 2c93306bd2efe1a5716067609949eccd67d493a3 (commit) from 00385dbab270b585291cf197f62cd4d7f92c2af9 (commit)
Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below.
- Log ----------------------------------------------------------------- commit 2c93306bd2efe1a5716067609949eccd67d493a3 Author: Bill Fischofer bill.fischofer@linaro.org Date: Fri Dec 28 11:41:02 2018 -0600
doc: userguide: add section for compression support
Add section to User's Guide for compression and decompression support
Signed-off-by: Bill Fischofer bill.fischofer@linaro.org Reviewed-by: Petri Savolainen petri.savolainen@linaro.org Signed-off-by: Maxim Uvarov maxim.uvarov@linaro.org
diff --git a/doc/users-guide/Makefile.am b/doc/users-guide/Makefile.am index 6b2e818d..f5386dfa 100644 --- a/doc/users-guide/Makefile.am +++ b/doc/users-guide/Makefile.am @@ -2,6 +2,7 @@ include ../Makefile.inc
SRC = users-guide.adoc \ users-guide-cls.adoc \ + users-guide-comp.adoc \ users-guide-crypto.adoc \ users-guide-ipsec.adoc \ users-guide-packet.adoc \ diff --git a/doc/users-guide/users-guide-comp.adoc b/doc/users-guide/users-guide-comp.adoc new file mode 100644 index 00000000..11a39a0c --- /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%5BRFC 1951]. +`ODP_COMP_ALG_ZLIB`:: +The ZLIB compression algorithm specified by +https://www.ietf.org/rfc/rfc1950.txt%5BRFC 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. diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 8ed581f5..dce457ff 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -1200,6 +1200,8 @@ include::users-guide-crypto.adoc[]
include::users-guide-ipsec.adoc[]
+include::users-guide-comp.adoc[] + include::users-guide-tm.adoc[]
include::users-guide-cls.adoc[]
-----------------------------------------------------------------------
Summary of changes: doc/users-guide/Makefile.am | 1 + doc/users-guide/users-guide-comp.adoc | 168 ++++++++++++++++++++++++++++++++++ doc/users-guide/users-guide.adoc | 2 + 3 files changed, 171 insertions(+) create mode 100644 doc/users-guide/users-guide-comp.adoc
hooks/post-receive