== OpenDataPlane (1.13.0.0)

=== New Features

==== APIs
ODP v1.13.0.0 represents the initial preview of the Tiger Moth release series
and as such introduces new APIs and extensions that will be built on as this
release matures.

===== Crypto Parameter Normalization
Many ODP APIs take parameter structs of type `odp_xxx_param_t`. The crypto APIs,
for historical reasons, failed to follow this convention, using instead structs
of type `odp_crypto_params_t`, etc. These pluralized names are now deprecated
and their singular forms are introduced as the preferred names for these
structs. The old names are retained (for now) to ease migration, however
applications should convert to the new forms at their convenience as these
deprecated forms will be removed in the final Tiger Moth release.

The changes introduced for this include:

* `odp_crypto_op_params_t` => `odp_crypto_op_param_t`
* `odp_crypto_session_params_t` => `odp_crypto_session_param_t`

===== Crypto Decouple Key Length from Algorithm Specification
To provide a more flexible programming for handling all possible
key/digest/iv length combinations, the enums used for crypto specification
are split to decouple lengths from algorithm names. The only exception
is the SHA-2 family of hash routines, which have well-established naming
conventions that incorporate digest lengths (SHA-224, SHA-256, etc.)

Changes included with this restructure include:

* The `odp_crypto_capability_t` structure returned by the
`odp_crypto_capability()` API contains streamlined `odp_crypto_cipher_algos_t`
and `odp_crypto_auth_algos_t` substructures.
* A new `odp_crypto_cipher_capability()` API is added to return detailed
information about available cipher capabilities.
* A new `odp_crypto_auth_capability()` API is added to return detailed
information about available authentication capabilities.

===== `odp_crypto_session_param_init()` API
For completeness the `odp_crypto_session_param_init()` API is provided to
enable platform-independent initialization of the `odp_crypto_session_param_t`
structure used as input to `odp_crypto_session_create()`.

===== Bitfield and Byteorder Cleanup
The `ODP_BITFIELD_ORDER` define is added to the ODP specification to parallel
the existing `ODP_BYTEFIELD_ORDER` define. This will be set to the value
`ODP_BIG_ENDIAN_BITFIELD` or `ODP_LITTLE_ENDIAN_BITFIELD`. This also addresses
https://bugs.linaro.org/show_bug.cgi?id=2402[Bug 2402], however since fixing
this required a small API change this was deferred until an API release
boundary.

===== Improved Name Argument Definitions in `odp_xxx_create()` Functions
The use of name arguments to the various resource creation APIs has
been standardized and documentation improved to clarify that unique
names are not required and that these may be specified as NULL for
anonymous resource creation. When non-unique resource names are used, it is
unspecified which of these are returned by a corresponding lookup API.

===== Pool Parameters for Packet Pools
The `odp_pool_param_t` structure adds the new field `max_len` to be used in
packet pools to advise the implementation of the maximum sized packet that
the application will allocate with a single `odp_packet_alloc()` call. This
may enable storage pool optimization.

===== Packet Clarifications
API documentation for `odp_packet_concat()` and `odp_packet_copy_from_pkt()`
is clarified to specify that the source and destination packets supplied to
these APIs should not refer to the same packet.

===== Packet Allocation Length Clarification
API documentation for `odp_packet_alloc()` is clarified to specify that
the supplied length for requested packet allocation should be greater
than zero.

===== Random API Changes
The APIs provided for working with random data have been revised. The third
parameter to `odp_random_data()` is now of type `odp_random_kind_t`, which is
an `enum` that is used to specify the quality of random data required. The
kinds of random data defined are:

`ODP_RANDOM_BASIC`::
No specific quality guarantees. This is assumed to be pseudo-random data
generated by software where speed of generation is more important than the
quality of the results.This is the lowest kind of random.

`ODP_RANDOM_CRYPTO`::
Random data suitable for use in cryptographic operations.

`ODP_RANDOM_TRUE`::
True random data generated from a hardware entropy source. This is the
highest kind of random.

The `odp_random_max_kind()` API is provided that returns the highest kind of
data available on this implementation. Requests for higher kinds than can be
supplied will fail.

For testing purposes it is often desirable to generate "random" sequences that
are repeatable. To support this use case, the `odp_random_test_data()` API is
introduced. This always returns BASIC random data but uses a user-supplied
64-byte seed parameter that is update for each call and can be used to
repeat the same sequence as needed.

===== Shared Memory Improvements
The `odp_shm_reserve()` API adds two new additional flags to support external
memory.

* `ODP_SHM_SINGLE_VA` guarantees that all ODP threads sharing this memory
will see the block at the same virtual address regardless of whether threads
are implemented as pthreads or processes and when `fork()` calls are made to
create them.

* `ODP_SHM_EXPORT` allows the memory block to be visible to other ODP
instances. Other ODP instances can retrieve this block via the new
`odp_shm_import()` API.

===== Classification Clarifications
The relationship between classification and queue configuration in the
`odp_pktin_queue_param_t` structure is clarified to emphasize that
classification subsumes queue-based I/O processing. This is an API
documentation change only.

=== Helpers
New helper APIs are introduced for IP table lookup support for longest prefix
matching as well as cuckoo hash tables. These are designed to provide analogs
to functions available in DPDK to assist applications being ported to ODP.

=== Performance Improvements
The odp-linux reference implementation includes a number of improvements to
make it more suitable for production use on platforms that rely on software
implementations of key ODP APIs.

==== Ring-based Pool Implementation
Storage pools used for buffers and packets are now implemented via lockless
ring structures that support burst mode read/writes to local caches for
significantly improved multi-core scalability

==== Buffer/Packet Header Optimizations
The layout of the structs used to support buffers and packets has been
optimized to reduce cache footprint and minimize path lengths in packet
manipulation.

==== Ordered Queue Improvements
The implementation of ordered queues has been streamlined and made more
scaleable in multi-core systems.

==== Packet Segmentation Improvements
The more advance segmentation capabilities present in the new ODP packet
implementation are used to streamline the implementation of APIs like
`odp_packet_concat()` and the head/tail extend/trunc APIs.

=== Bug Fixes

==== https://bugs.linaro.org/show_bug.cgi?id=2405[Bug 2405]
A number of "todos" were removed from the packet validation test suite.

==== https://bugs.linaro.org/show_bug.cgi?id=2472[Bug 2472]
The CPU affinity is now correctly read from the cpuset.

==== https://bugs.linaro.org/show_bug.cgi?id=2496[Bug 2496]
The PktIO validation test no longer uses invalid MAC addresses.

==== https://bugs.linaro.org/show_bug.cgi?id=2512[Bug 2512]
The TCP checksum is now properly calculated for generated packets.

==== https://bugs.linaro.org/show_bug.cgi?id=2798[Bug 2798]
The odp-linux reference implementation makes use of the OpenSSL library to
support the `odp_random_xxx()` APIs and some crypto operations. To support
OpenSSL versions prior to 1.1.0, which are not thread safe, support is added
for OpenSSL locking callbacks that use ODP ticketlocks to provide OpenSSL thread
safety.

=== Known Issues

==== https://bugs.linaro.org/show_bug.cgi?id=2812[Bug 2812]
Make check fails on a single core VM in the process mode helper test.