== opendataplane (1.15.0.0)

=== new features
odp v1.15.0.0 continues the preview of tiger moth, introducing new apis and
extensions, as well as numerous bug fixes and functional improvements.

==== deprecation framework
to permit smoother evolution of the odp api specification, a deprecation
framework is introduced to permit controlled deprecation.

when an odp api or defined struct parameter is deprecated, odp validation
tests will be updated to no longer use that api and instead use the
replacement api. by default, attempts to compile with the older api/feature
will fail and applications wishing to move to the new odp release should be
updated to use the replacement api. to permit evaluation of new odp
releases in advance of such updating, however, odp supports the `configure`
option `--enable-deprecated`, which makes the obsolete apis visible again.

this feature will be used on a case-by-case basis and documented in the
release notes for each release that introduces replacement api(s). in general
the deprecated forms will not be maintained for more than a single release
cycle. after that they will no longer be present in the api specification and
the replacement forms must be used to compile with that level of the api
specification.

==== apis
a number of new and refined apis are introduced in crypto, packet parsing,
and queue configuration:

===== crypto enhancements
the odp crypto apis receive several enhancements in this release:

====== new authentication algorithms
additional enumerations added for hmac-sha-1 and hmac-sha-512 authentication.

====== deprecated cipher/authentication algorithms
the following cipher/authentication algorithms have been deprecated in favor
of newer replacement algorithms:

* `odp_cipher_alg_aes128_cbc` is replaced by `odp_cipher_alg_aes_cbc`
* `odp_cipher_alg_aes128_gcm` is replaced by `odp_cipher_alg_aes_gcm`
* `odp_auth_alg_md5_96` is replaced by `odp_auth_alg_md5_hmac`
* `odp_auth_alg_sha256_128` is replaced by `odp_auth_alg_sha256_hmac`
* `odp_auth_alg_aes128_gcm1 is replaced by `odp_auth_alg_aes_gcm`

====== deprecated name for crypto parameter struct
`odp_crypto_op_params_t` is deprecated in favor of `odp_crypto_op_param_t`
for consistency with other odp `param` structs.

====== digest length session parameter
`odp_crypto_session_param_t` adds the field `auth_digest_len` to permit
specification of the authentication digest length to be used for this
session. the `odp_crypto_auth_capability()` api returns the list of
supported digest lengths.

====== additional authentication data (aad)
the `odp_crypto_op_param_t` struct adds an optional pointer and length for
aad information. this allows applications to specify aad information from
the list of supported lengths provided by `odp_crypto_auth_capability()`.

===== packet range data
the former `odp_crypto_data_range_t` type is deprecated and renamed to
`odp_packet_data_range_t` since it can be used to specify ranges for other
than crypto purposes.

===== parser configuration
applications may now specify the maximum packet layer of interest. for
example, a router may not care about anything beyond iso layer 3 in packets.
this can be used by odp implementations to control the depth of packet
parsing needed by the application and may allow greater efficiency,
especially in software implementations.

this is controlled by a new `odp_pktio_parser_layer_t` enum that is
part of the new `odp_pktio_parser_config_t` struct that is added to the
`odp_pktio_config_t` struct used by the `odp_pktio_config()` api. the
supported parser layers are also returned in this struct as part of the
`odp_pktio_capability_t` struct returned by the `odp_pktio_capability()` api.

===== queue size parameter
the `odp_queue_capability_t` struct returned by the `odp_queue_capability()`
api is enhanced as follows:
* the `max_queues` field is now defined to return the maximum number of event
queues of any type.
* new sub-structs (`plain` and `sched`) are added that detail the `max_num` of
queues of that type supported as well as the new field `max_size` that
specifies the maximum number of elements that each queue of this type can
store. a value of zero for `max_num` indicates no fixed limit.

in addition, the `odp_queue_param_t` passed to `odp_queue_create()` now adds
a `size` field to allow applications to specify the minimum number of events
that this queue should be able to store. a value of zero specified requests that
the implementation default limits be used.

the odp examples have been updated to show this configuration, for example,
the `l2fwd_simple` example does layer 2 forwarding and hence doesn't need
packets to be parsed beyond layer 2. so prior to opening an interface via
`odp_pktio_open()` the configuration processing now includes code of the form:
[source,c]
-----
odp_pktio_config_init(&config);
config.parser.layer = odp_pktio_parser_layer_l2;
odp_pktio_config(pktio, &config);
-----
this serves as a hint to the odp implementation that parsing beyond layer 2
is not required on this interface.

===== removal of `odp_time_to_u64()` api
the `odp_time_to_u64()` api is removed without deprecation in this release.
this is redundant since the `odp_time_to_ns()` api already returns a `uint64_t`
value for `odp_time_t` and can be used for the same purpose.

===== new `odp_sys_info_print()` api
for debugging / diagnostic use, the `odp_sys_info_print()` api is added.
this prints implementation defined information about the system and odp
environment and may contain information about cpus, memory, and other
hardware configuration.

=== helpers
==== linux helpers
odp helper functions fall into two categories: system-independent, and those
that rely on linux. for backwards compatibility, these have been
reorganized into a new `helper/linux` directory that is installed only when
the `--enable-helper-linux` `configure` option is specified.

=== `odp-linux` performance
==== scheduler improvements
the default scheduler is streamlined by using precomputed weight tables and
separated priority queues for different scheduling groups. this improves
both latency and scalability.

also included in this change, the default number of scheduling groups is
lowered from 256 to 32, which experience has shown is sufficient for most
applications.

the scheduler fairness checks are also enhanced to avoid low priority event
starvation if `config_burst_size` is set to 1.

=== `odp_linux` crypto improvements
* errors in implicit packet copy operations performed during crypto operation
are now handled properly.
* if `odp_crypto_session_create()` fails, proper cleanup is now performed to
avoid memory leaks.
* the auth digest len is now used when calculating hmacs, and full-length
digests are now added to supported sha capabilities.
* numerous crypto functions have been rewritten to use the openssl `evp_`
functions for improved efficiency and accuracy.

=== `odp-linux` packet improvements
* the packet parser now recognizes icmpv6 packets in addition to icmpv4.

=== `odp-linux` pktio improvements
* the `ethtool` and `socket` drivers add additional initializations to avoid
valgrind warnings.
* the `dpdk` driver is upgraded to dpdk 17.02 and is now also built with the
`--whole-archive` option, which means that pmds no longer need to be linked
individually but are automatically included in builds that make use of dpdk
pktio support.

=== `odp-linux` time improvements
* the odp time apis are now more efficiently handled by replacing the previous
linux timespec with simple nanoseconds (ns) and using native hardware time
counters in x86 and arm environments, when available.

=== `odp-linux` traffic manager improvements
* weighting is now handled properly when weight=1 is specified. previously
this caused an overflow that distorted packet priorities.

=== miscellaneous fixes and improvements
==== native clang build on armv8
armv8 compilation now works properly when using the clang compiler.

==== test improvements
* the `odp_scheduling` performance test now handles dequeueing from
potentially concurrent queues properly.
* the traffic manager and time tests are now invoked via scripts to better
account for load-sensitivity when running regressions in ci environments.
* the l2fwd test now supports an additional parameter to specify the number
of scheduling groups to use in the test.
* the `odp_sched_latency` performance test now handles queue draining in
a robust manner.
* the crypto validation tests now properly check and validate message digests,
and include negative tests to verify that incorrect digests are properly
flagged. note that this may expose omissions in other odp implementations that
had previously passed this validation test.
* the crypto validation test now adds an explicit test for the null cipher,
as well as hmac-sha-1 and hmac-sha-512.
* the pktio_ipc test now properly cleans up only its own temp files.

==== examples improvements
* the `odp_generator` example now properly honors stop criteria based on
number of packets sent.
* the `odp_generator` example now properly flushes output messages
* the `odp_generator` example now supports port configuration.

=== bug fixes
==== https://bugs.linaro.org/show_bug.cgi?id=2416[bug 2416]
example/generator/odp_generator.c contains todo items

==== https://bugs.linaro.org/show_bug.cgi?id=2779[bug 2779]
error handling issues (checked_return)

==== https://bugs.linaro.org/show_bug.cgi?id=2826[bug 2826]
unchecked return in pool.c

==== https://bugs.linaro.org/show_bug.cgi?id=2831[bug 2831]
unchecked return in mmap_unmap_sock()

==== https://bugs.linaro.org/show_bug.cgi?id=2852[bug 2852]
odp_static_assert() fails when used by c++

==== https://bugs.linaro.org/show_bug.cgi?id=2872[bug 2872]
odp_pktio_ordered_run.sh: line 34: integer expression expected

==== https://bugs.linaro.org/show_bug.cgi?id=2881[bug 2881]
load sensitive tests fail on ci

==== https://bugs.linaro.org/show_bug.cgi?id=2895[bug 2895]
the `odp_crypto_operation()` routine does not work with multi-segment packets.

==== https://bugs.linaro.org/show_bug.cgi?id=2908[bug 2908]
packet validation test fails if implementation does not limit packet length

==== https://bugs.linaro.org/show_bug.cgi?id=2910[bug 2910]
odph_iplookup_table_put_value() uses overlapping pointer addresses

==== https://bugs.linaro.org/show_bug.cgi?id=2933[bug 2933]
miss to call unlock if there are some errors happen in loopback_send() function

==== https://bugs.linaro.org/show_bug.cgi?id=2940[bug 2940]
`odp_packet_seg_t` fails abi compatibility between odp-linux and odp-dpdk

==== https://bugs.linaro.org/show_bug.cgi?id=2942[bug 2942]
compilation fails using clang 4.0.0

==== https://bugs.linaro.org/show_bug.cgi?id=2952[bug 2952]
doxygen errors and travis does not catch them

==== https://bugs.linaro.org/show_bug.cgi?id=2969[bug 2969]
tm validation test does find traffic_mngr_main

==== https://bugs.linaro.org/show_bug.cgi?id=2974[bug 2974]
`odp_rwlock_read_trylock()` fails if lock is already held for read access

==== https://bugs.linaro.org/show_bug.cgi?id=3002[bug 3002]
packet order lost when enqueuing to pktout queue

==== https://bugs.linaro.org/show_bug.cgi?id=3003[bug 3003]
aes-gcm returns 'valid' tag when checking invalid tag

==== https://bugs.linaro.org/show_bug.cgi?id=3013[bug 3013]
various failures if config_packet_max_segs is set to 1

==== https://bugs.linaro.org/show_bug.cgi?id=3017[bug 3017]
travis: time main test out of boundaries

==== https://bugs.linaro.org/show_bug.cgi?id=3027[bug 3027]
compilation failures using gcc 7 series

==== https://bugs.linaro.org/show_bug.cgi?id=3039[bug 3039]
socket pktio recv fails on large number of packet

=== known issues
==== https://bugs.linaro.org/show_bug.cgi?id=3024[bug 3024]
odp_traffic_mngr example is broken

==== https://bugs.linaro.org/show_bug.cgi?id=3026[bug 3026]
pktio_ips_run test can fail due to segfault