1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
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.
|
