git-lng-odp January 2019

git-lng-odp@lists.linaro.org

1 participants
12 discussions

[COMMIT] branch api-next updated. v1.20.0.0-35-g2c93306b

by git＠git-us.linaro.org

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(a)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(a)linaro.org> Reviewed-by: Petri Savolainen <petri.savolainen(a)linaro.org> Signed-off-by: Maxim Uvarov <maxim.uvarov(a)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[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. 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 --

5 years, 3 months

[COMMIT] branch master updated. v1.20.0.0-29-geac3c037

by git＠git-us.linaro.org

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, master has been updated via eac3c037e7547b1ed1a15f0ee2e0daccacc88ec5 (commit) from 87a81d8b4feb08fdf60a960ac2b003233fc0ae3b (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 eac3c037e7547b1ed1a15f0ee2e0daccacc88ec5 Author: Petri Savolainen <petri.savolainen(a)linaro.org> Date: Fri Jan 4 16:21:02 2019 +0200 dependencies: add libconfig package name Added apt-get and yum package names for libconfig. Signed-off-by: Petri Savolainen <petri.savolainen(a)linaro.org> Reviewed-by: Bill Fischofer <bill.fischofer(a)linaro.org> Signed-off-by: Maxim Uvarov <maxim.uvarov(a)linaro.org> diff --git a/DEPENDENCIES b/DEPENDENCIES index 10a9861c..d5214663 100644 --- a/DEPENDENCIES +++ b/DEPENDENCIES @@ -19,7 +19,13 @@ Prerequisites for building the OpenDataPlane (ODP) API 3. Required packages - Libraries currently required to link: openssl, libatomic, libconfig + Libraries currently required to link: libconfig, openssl, libatomic + + On Debian/Ubuntu systems: + $ sudo apt-get install libconfig-dev + + On CentOS/RedHat/Fedora systems: + $ sudo yum install libconfig-devel It is possible to build ODP without OpenSSL by passing flag --without-openssl to configure script. However this will result in ----------------------------------------------------------------------- Summary of changes: DEPENDENCIES | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) hooks/post-receive --

5 years, 3 months

2024

2023

2022

2021

2020

2019

2018

2017

2016

git-lng-odp January 2019