muvarov replied on github web page: CHANGELOG line 187 @@ -1,3 +1,386 @@ +== OpenDataPlane (1.17.0.0) +=== New Features +ODP v1.17.0.0 is Tiger Moth Release Candidate 1 (RC 1). It introduces +significant new API support as well as functional refinements that expand +ODP offload support to cover IPsec, as well as other improvements. + +==== APIs +The following new and changed APIs are included in this release: + +===== Event Extensions +The ODP event model has been expanded to include new types as well as event +subtypes. Subtypes are used to qualify an event by indidating that the event +carries additional metadata relating to specific usage or operations. + +New event `ODP_EVENT_IPSEC_STATUS` (to be discussed +below) is added. The initial subtypes defined are: `ODP_EVENT_PACKET_BASIC`, +`ODP_EVENT_PACKET_CRYPTO`, `ODP_EVENT_PACKET_IPSEC`, and +`ODP_EVENT_NO_SUBTYPE`, which are also discussed below. + +Associated with this support, new event APIs are added: + +* `odp_event_subtype()` extracts the `odp_event_subtype_t` from an +`odp_event_t`. + +* `odp_event_types()` returns the `odp_event_type_t` and `odp_event_subtype_t` +of an `odp_event_t` in a single call. + +* `odp_event_type_multi()` scans a list of `odp_event_t` objects and returns +the number that share the same indicated `odp_event_type_t`. This allows +multiple events to be processed by groups of the same event type. + +* `odp_event_filter_packet()` scans a list of `odp_event_t` objects and +partitions them into a returned array of `odp_packet_t` objects and a remaining +array of non-packet events. + +* `odp_event_free_multi()` frees multiple events in a single call. + +* `odp_event_free_sp()` frees multiple events originating from the same +pool in a single call. The caller must assure that the input events are from +the same pool. + +===== IPsec support +ODP Tiger Moth introduces comprehensive protocol offload support for IPsec, +allowing applications to leverage the IPsec acceleration capabilities of many +SoCs. Support includes APIs for Security Association (SA) creation and +lifecycle management, as well as IPsec packet operations for inbound (RX) and +outbound (TX) processing. Packet operations are further divided into lookaside +and inline support. + +====== Lookaside Support +Lookaside processing enables IPsec packets to be decrypted into plain packets +or plain packets to be encrypted into IPsec packets in a single operation under +explicit application control. This is useful for packets that need pre- or +post-processing, or to better fit with existing application design. + +Two forms of lookaside processing are provided: the `odp_ipsec_in()` and +`odp_ipsec_out()` APIs provide synchronous decrypt and encrypt support, +respectively. The corresponding `odp_ipsec_in_enq()` and `odp_ipsec_out_enq()` +APIs provide these same services in asynchronous form where operations can be +launched and completed later. + +====== Inline Support +In contrast to lookaside support, IPsec inline support permits applications to +fully leverage the offload capabilities found in many SoCs by allowing inbound +IPsec packets to be recognized and decrypted automatically before they are +presented to the application for processing. This is done by configuring a +Security Association (SA) and its associated PktIO to operate in inline mode. + +Similarly, following output SA and PktIO configuration, the +`odp_ipsec_out_inline()` API permits a packet to be encrypted into an IPsec +packet and automatically scheduled for TX processing in a single +operation. Such "fire and forget" processing enables applications to leverage +IPsec HW support for such processing in a portable manner. + +Applications using IPsec inline support need only "touch" a packet once +compared to three times when using lookaside processing, leading to greater +processing efficiency. + +====== IPsec Events +New event types and subtypes are introduced to provide support for IPsec +processing. The `ODP_EVENT_PACKET` type has a new subtype: +`ODP_EVENT_PACKET_IPSEC` that provides extended metadata associated with +IPsec packets that have been processed. The new `ODP_EVENT_IPSEC_STATUS` +event, in turn, is used to report IPsec status events such as completion +notifications associated with `odp_ipsec_sa_disable()` calls. + +The `odp_ipsec_result()` API is used to obtain IPsec result metadata from +a packet that has event subtype `ODP_EVENT_PACKET_IPSEC`, while the +`odp_ipsec_status()` API is used to obtain IPsec status metadata from an +`ODP_EVENT_IPSEC_STATUS` event. + +===== Parser APIs +Packet parsing has been overhauled with the introduction of two new APIs: + +* `odp_packet_parse()` +* `odp_packet_parse_multi()` + +These use an `odp_packet_parse_param_t` struct to control the type and depth +of parsing to be performed. These routines are intended to be used to +process packets that have been decapsulated following IPsec decryption or other +tunneling or on IP fragments after they have been reassembled. + +Associated with this improved parse support, the `odp_parser_layer_t` struct +is deprecated and replaced with a more general `odp_proto_layer_t` struct that +is used both in PktIO configuration as well as the new parser APIs. + +===== Crypto AES-CTR and AES-GMAC Support +The ODP crypto APIs are extended to provide support for AES-CTR cipher and +AES-GMAC authentication modes, reflecting the growing availability of +accelerated support for these. + +===== Crypto removal of DES-CBC +DES-CBC is no longer considered secure and support for it is removed in ODP. + +===== Crypto move AAD length to sessions +The Additional Authentication Data (AAD) length is now part of the +`odp_crypto_session_t` rather than individual crypto operations. This provides +better compatibility with DPDK, which made a similar API adjustment in it's +17.08 release. + +===== Crypto Packet APIs +While the `odp_crypto_operation()` API is retained for compatibility, +new packet-oriented variants are introduced that provide additional +capabilities and flexibility. These APIs are: + +* `odp_crypto_op()` Performs synchronous crypto operations on one or more +input packets under the control of an associated `odp_crypto_packet_op_param_t` +struct. + +* `odp_crypto_op_enq()` Performs asynchronous crypto operations on or or more +input packets under the control of an associated `odp_crypto_packet_op_param_t` +struct. + +While `odp_crypto_operation()` calls result in `ODP_EVENT_CRYPTO_COMPL` events +for compatibility, the new packet-oriented APIs result in `ODP_EVENT_PACKET` +events that carry the new event subtype `ODP_EVENT_PACKET_CRYPTO`. These +packets contain additional metadata associated with the crypto operation. +New APIs added for manipulating this metadata include: + +* `odp_crypto_packet_from_event()` converts an `odp_event_t` of type +`ODP_EVENT_PACKET` and subtype `ODP_EVENT_PACKET_CRYPTO` to an `odp_packet_t`. + +* `odp_crypto_packet_to_event()` converts an `odp_packet_t` crypto packet +back into an `odp_event_t`. + +* `odp_crypto_result()` extracts the `odp_crypto_packet_result_t` struct that +contains the crypto metadata associated with an `odp_packet_t` of event +subtype `ODP_EVENT_PACKET_CRYPTO`. This struct provides a summary bit that +says whether the operation completed successfully as well as +`odp_crypto_op_status_t` fields for the `cipher_status` and `auth_status` if a +problem was detected. + +===== Classification Random Early Detection (RED) Support +Random Early Detection (RED) provides a means for input HW to ensure that +traffic is treated fairly under conditions of temporary resource overload due +to excessive inbound traffic. ODP RED support provides the ability to measure +and respond to resource pressure on either pools or queues, and only provides +flexibility in how such conditions are to be processed. They can result in +input packet drops or backpressure being indicated by transmitting pause +frames, depending on the underlying platform capabilities. + +The `odp_cls_capability_t` struct returned by the `odp_cls_capability()` API +has been expanded to cover this support. + +===== Time difference in nanoseconds +The new `odp_time_diff_ns()` API permits the delta between two `odp_time_t` +values to be computed in a single call. + +===== PktIO API Changes +====== PktIO Maximum Frame Lengths +The `odp_pktio_mtu()` API is deprecated and replaced by two new APIs: +`odp_pktin_maxlen()` and `odp_pktout_maxlen()`. These return the maximum +sized packets that are supported for RX and TX processing, +respectively, on a given `odp_pktio_t`. + +====== PktIO settable MAC address +The `odp_pktio_mac_addr_set()` API is added to allow setting of the MAC +address associated with an `odp_pktio_t`. The `odp_pktio_set_op_t` field of +the `odp_pktio_capability_t` returned by the `odp_pktio_capability()` API now +includes the `mac_addr`` field to indicate that this `odp_ptkio_t` supports +setting its MAC address. + +====== Multiple loop devices +The `odp_pktio_config_t` now contains the `enable_loop` boolean, which enables +any supported `odp_pktio_t` to be place into loopback mode. Since not every +interface supports such mode, this is also returned as part of the +`odp_pktio_capability()` information for each `odp_pktio_t`.
Comment: Bill described here API changes. Internal things should not be here. So that description is ok. > Dmitry Eremin-Solenikov(lumag) wrote: > Argh. I meant loopX pktio devices in linux-generic. >> Dmitry Eremin-Solenikov(lumag) wrote: >> new typo: application >>> Dmitry Eremin-Solenikov(lumag) wrote: >>> initial >>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>> AArch64 >>>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>>> OK, I missed that. Thanks. Will fix in v3. >>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>> see above. >>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>> ``` >>>>>>> * Returns 16-bit ones' complement sum that was calculated over a >>>>>>> portion of >>>>>>> * packet data during a packet processing operation (e.g. packet input >>>>>>> or >>>>>>> * IPSEC offload). The data range is output with 'range' parameter, and >>>>>>> usually >>>>>>> * includes IP payload (L4 headers and payload). When 'range.length' is >>>>>>> zero, >>>>>>> * the sum has not been calculated. In case of odd number of bytes, >>>>>>> * calculation uses a zero byte as padding at the end. The sum may be >>>>>>> used as >>>>>>> * part of e.g. UDP/TCP checksum checking, especially with IP fragments. >>>>>>> ``` >>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>> I'll send a patch then... >>>>>>>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>>>>>>> How so? The only difference between the two is the one sums over a >>>>>>>>> packet range while the other sums over an in-memory area. >>>>>>>>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>>>>>>>> `odp_packet_ones_comp()` is specifically for computing partial >>>>>>>>>> checksums, no? >>>>>>>>>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>>>>>>>>> Ethernet is the only frame format currently supported by ODP but I >>>>>>>>>>> can make this more generic. >>>>>>>>>>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>>>>>>>>>> DES-CBC is obsolete. I thought we had simply removed it. No modern >>>>>>>>>>>> application should be using it and I doubt if legacy apps would >>>>>>>>>>>> object to updating to a more modern cipher if they wished to move >>>>>>>>>>>> to ODP. >>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>> https://bugs.linaro.org/show_bug.cgi?id=3210 >>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>> `odp_packet_ones_comp()` description needs to be fixed. >>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>> This is not quite true. There is no support for computing >>>>>>>>>>>>>>> partial checksum for a packet. Current API returns information >>>>>>>>>>>>>>> about checksum precomputed by hardware when receiving a packet. >>>>>>>>>>>>>>> Computing partial checksum over a buffer is supported. >>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>> L2 packets? >>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>> From linux-generic. Algorithm definition still exists for >>>>>>>>>>>>>>>>> those who really want it. Maybe we should deprecate DES-CBC >>>>>>>>>>>>>>>>> alltogether? >>>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>>> AAD length >>>>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>>>> Configure: SA, PktI/O. >>>>>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>>>>> PktI/O also needs to be configured (IPsec inbound inline >>>>>>>>>>>>>>>>>>>> should be supported and enabled on this PktI/O). >>>>>>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>>>>>> Please add a note what event subtypes are. https://github.com/Linaro/odp/pull/373#discussion_r158904939 updated_at 2017-12-28 07:03:16
