Skip to content

@MatiasElo MatiasElo released this Jun 2, 2021

OpenDataPlane (

Backward incompatible API changes

  • New mandatory traffic manager odp_tm_start() and odp_tm_stop() calls for starting and stopping a traffic manager system
  • New traffic manager capabilities (odp_tm_capabilities_t) for supported dynamic configuration updates
  • Deprecated traffic manager shaper commit information rate bps (odp_tm_shaper_params_t.commit_bps) and peak information rate bps (odp_tm_shaper_params_t.peak_bps) fields. odp_tm_shaper_params_t.commit_rate and odp_tm_shaper_params_t.peak_rate fields should be used instead.

Backward compatible API changes

  • New traffic manager option to enable packet mode shaper (packets per second as opposed to bits per second)
  • Clarified packet IO spec to specify explicitly that an application may enqueue to packet input side event queues, and cannot dequeue from output side event queues
  • Added success bytes to IPsec stats (odp_ipsec_stats_t.success_bytes)
  • New time stamp read functions which read time stamp value more strictly in the program order: odp_time_local_strict(), odp_time_local_strict_ns(), odp_time_global_strict(), odp_time_global_strict_ns()
  • Added timer default clock source enumeration ODP_CLOCK_DEFAULT (=ODP_CLOCK_SRC_0) and support for multiple clock sources (ODP_CLOCK_SRC_1, ODP_CLOCK_SRC_2...). The old ODP_CLOCK_CPU and ODP_CLOCK_EXT enumerations will be deprecated in the future.
  • Renamed timer set operation return codes (odp_timer_set_t) to better document expiration time position to current time:
  • Renamed timer set operation failure code (odp_timer_set_t) to cover all error cases:

Helper library

  • Added new mandatory odph_cli_init() and odph_cli_term() functions for initializing and terminating CLI helper
  • Added odph_cli_register_command() function for registering user defined CLI commands
Assets 2

@MatiasElo MatiasElo released this May 6, 2021

OpenDataPlane (

Backward incompatible API changes

  • Modified packet IO statistics counters (odp_pktio_stats_t) definitions
  • Deprecated packet IO statistics field odp_pktio_stats_t.in_unknown_protos

Backward compatible API changes

  • New APIs for inline IP reassembly offload for packet input and IPsec
  • New odp_log_thread_fn_set() function for setting a thread specific log function
  • New packet IO statistics counters odp_pktio_stats_t.in_packets/out_packets

Implementation changes

  • ABI compatibility default value has been changed to disabled. User can enable ABI
    compatibility with --enable-abi-compat configure option.
Assets 2

@MatiasElo MatiasElo released this Apr 1, 2021

OpenDataPlane (

Backward incompatible API changes

  • New crypto capabilities for defining if a queue type (scheduled/plain) can be used as a crypto completion event destination

Backward compatible API changes

  • New packet TX completion event type and related functions
  • New packet APIs for requesting packet TX completion events
  • New packet APIs for requesting packet TX drop based on packet age
  • New odp_cls_print_all() function for printing implementation specific debug information about all classifier rules
  • New enumerations for ARMv8.7-A, ARMv9.0-A, ARMv9.1-A, and ARMv9.2-A ISA versions
Assets 2

@MatiasElo MatiasElo released this Feb 24, 2021

OpenDataPlane (

Backward incompatible API changes

  • IPsec post-processing happens in the odp_ipsec_result() function that must be called at least once before packet data or metadata may be accessed.

Backward compatible API changes

  • New 128-bit atomic operations: init, store, load, and CAS
  • Clarify that atomic CAS operations are strong type
  • New odp_ipsec_test_sa_update() function for SA testing
  • odp_ipsec_sa_info() may return non-exact copy of SA parameters
  • Specify default values for more IPsec SA parameter fields
  • Changed odp_timer_alloc() user context pointer argument to const
  • New odp_timer_pool_print() function for printing timer pool debug information
  • New odp_timer_print() function for printing timer debug information
  • New odp_timeout_print() function for printing timeout debug information
  • New odp_queue_print_all() function for printing debug information about all queues
Assets 2

@MatiasElo MatiasElo released this Feb 8, 2021

OpenDataPlane (

Backward incompatible API changes

  • Only ODP_SCHED_NO_WAIT variants of schedule calls are allowed after calling odp_schedule_pause()
  • IPsec config must have been completed before enabling inbound inline IPsec in pktio

Backward compatible API changes

  • New odp_pktio_maxlen_set() function (and related capabilities) for configuring input/output maximum frame lengths
  • New Large Send Offload (LSO) APIs
  • Clarify odp_schedule_capability_t.max_groups capability definition
  • Added configure option to enable/disable predefined scheduling groups
Assets 2

@MatiasElo MatiasElo released this Jul 3, 2020

OpenDataPlane (

Summary of Changes

This release introduces a new stash API module. The other main API additions are
pool buffer caching configuration and packet IO link information. The release
also includes several smaller API improvements and clarifications.



  • Added missing const qualifiers

Some API calls missed const qualifiers on read-only data pointers.

  • Improved Doxygen module descriptions
  • Use param_init functions for parameter defaults

When available, parameter init functions must be used to initialize parameters
into their default values.



Added macro for rounding up a value to the next multiple of cache line size.
This round up is needed e.g. when selecting buffer sizes so that false sharing
is avoided.


  • Make supporting CPU frequency and cycle counter optional

CPU frequencies or CPU cycle counter may not be available on all HW/SW
platforms. Zero is returned if those cannot be read.


  • Added feature bits stash and compress into odp_feature_t.


  • Clarify packet length function argument definitions

Modify documentations of functions, which decrease packet length, to clearly
state what are the allowed values for length argument. This is done to avoid
creating zero length packets which are not allowed by the packet API.

  • Added odp_packet_input_set() function

An application may use this for testing or other purposes, when perception of
the packet input interface need to be changed.

Packet I/O

  • Added odp_pktio_link_info() function for reading link status information

    • Autonegotiation mode (unknown/enabled/disabled)
    • Duplex mode (unknown/half duplex/full duplex)
    • Flow control (unknown/on/off)
    • Link status (unknown/up/down)
    • Media (media type as string)
    • Speed (unknown/Mbps)
  • Modified odp_pktio_link_status() to return odp_pktio_link_status_t enum
    (backward compatible values)


  • Added cache_size parameters to odp_pool_capability_t and odp_pool_param_t

Added thread local cache size parameter and capability. This allows application
to control thread local caching and prepare large enough pool when
implementation caches events per thread. The default value is implementation
specific for backwards compatibility.

  • Removed default value of packet max_len from odp_pool_param_t

The default value is implementation specific and may not be equal to the maximum

  • Added packet data align parameter to odp_pool_param_t

Added packet pool parameter to request minimum data alignment for user allocated
packets. When user allocates a new packet and fills in protocol headers, it's
convenient that data alignment does not need to be checked (and tuned) on each
allocated packet.


  • Unify max_size capa specification for all plain queue types

Specify queue maximum size capability the same way for all non-blocking levels
of zero means that there is no size limit.

  • Clarify that queue operations include memory barriers

Clarify that queue enqueue operations include memory barrier of release
semantics and queue dequeue operations include acquire semantics.


  • Clarify how much data odp_random_data() and odp_random_test_data() output on success.

It may not be possible for random generator functions to return requested number
of bytes. Clarify that implementation is not required to loop until len bytes
are available. Instead application should contain such logic.


  • Clarify synchronization of store operations during atomic context

Stores performed while holding an atomic scheduling context are seen correctly
by other thread when they hold the same context later on. This is guaranteed
also when queue enqueue is not used in between.

  • Clarify that schedule operations include memory barriers

Clarify that event schedule operations include memory barrier of acquire

Shared Memory

  • Add ODP_SHM_HW_ACCESS flag

This can be used to memory allocations where both CPUs and HW accelerators
access the same memory area. These HW accelerators may be programmed outside of
ODP APIs, but the memory is reserved and shared normally inside/between ODP


  • Added new stash API module

Application needs often store object handles for later usage. From current APIs,
e.g. buffers and queues could be used to store these handles, but buffers
consume more memory than is necessary and event queues are not needed for this
simple use case. This new API maybe implemented e.g. as a ring of object handles
in memory, or with a HW buffer manager.


  • Added odp_time_local_ns() and odp_time_global_ns() functions for acquiring
    current time stamp in nanoseconds

Added functions to get the current local/global
time stamp directly in nanoseconds. For example, odp_time_local_ns() is
equivalent of calling odp_time_to_ns(odp_time_local()). This simplifies use
cases where time will be always converted to nanoseconds. However, when time API
performance is important conversions to nanoseconds should be avoided or


  • Clarify that odp_timeout_tick() returns original expiration time

Specification was open if returned expiration time is the original or actual
expiration time. HW based implementations will not likely modify timeout event
with actual expiration time. Also original expiration time is more valuable to
an application as it can be used to calculate e.g. the next period.

  • Add resolution in hertz parameter res_hz into odp_timer_pool_param_t

Added option to specify timer pool resolution in hertz. High resolution values
in nanoseconds result small numbers and thus poor granularity. Hertz offers
better granularity with high resolution values. User gives resolution either in
nanoseconds or hertz, and sets the other parameter to zero.

Traffic Manager

  • Add missing handle debug functions

Traffic Manager API defines all types as platform specific, yet unit tests
expect to be able to print them. Therefore introduce u64 debug print conversion
functions for all TM types: odp_tm_to_u64(), odp_tm_queue_to_u64(),
odp_tm_node_to_u64(), odp_tm_shaper_to_u64(), odp_tm_sched_to_u64(),
odp_tm_threshold_to_u64(), odp_tm_wred_to_u64()

  • Info structures are written only on success

Clarify that info structures (odp_tm_node_info_t, odp_tm_node_fanin_info_t,
odp_tm_queue_info_t, odp_tm_query_info_t) are written only on success.


  • Added ODP_VERSION_API define and ODP_VERSION_API_NUM macro

Added a macro and version number defines for easier comparison of API version

Assets 2

@MatiasElo MatiasElo released this Nov 13, 2019

OpenDataPlane (

Summary of Changes

The ODP API changes in this release are related to the classifier module.

The implementation changes include bug fixes (classifier, socket pktio),
configurability improvements (inline timer), new packet segmentation
implementation, and performance improvements (pool).



The PMR term documentation was not explicit about endianness of value and mask
fields. Most terms assumed CPU endian, but terms with larger data sizes assumed
big endian (MAC, IPv6 address and custom).

Term specification was harmonized so that all terms expect value/mask data to be
in big-endian format, have fixed size, and allow free memory alignment. Packet
length term is an exception to this as it does not represent a field in a

Added new ODP_PMR_CUSTOM_L3 term to match custom layer 3 protocol fields. PMR
offset refers to the start of layer 3 in the packet. Other PMR rules (e.g. L2
classification rules) may precede custom L3 rules.


Duplicate ODPH_UNUSED macro has been removed. ODP_UNUSED should be used

Validation Tests


Improved test result output when some tests are inactive (skipped due to missing
capability). Now inactive tests are listed by default in the test suite results.


Cleaned up validation test code. Classifier implementation missed reporting some
capabilities, tests didn't check those capabilities and they were tested. Source
IPv4 term test was missing.

Added serial PMR test, which tests series of PMR and CoS:

  • From default CoS to dest IPv4 CoS
  • From dest IPv4 CoS to dest UDP CoS

Added parallel PMR test, which test serial and parallel PMR and CoS:

  • From default CoS to dest IPv4 CoS
  • From dest IPv4 CoS to a parallel UDP CoS per destination port number


Added new validation tests to verify that packet order is maintained when events
are enqueued and dequeued to/from a plain queue while maintaining atomic/ordered
scheduling context.


Added private timer pool test, which creates a timer pool with the priv flag
set. The same thread calls schedule / queue_deq that created the pool.

##Example Applications


Added new test application to measure schedule call CPU cycle consumption with
various timer pool parameter combinations. This measurement is mostly
interesting with software-based timer implementations, where timers may be
polled from the schedule call.

New odp_ping application

This application replies to IPv4 ping requests. It can be used to test
connectivity with standard ping utility. ARP table needs to be setup manually on
the sender side as the application does not reply to ARP requests.


Added source CoS name into the parameter list of -p option. This enables
linking classification rules together. When a source CoS is not defined, the
default CoS is used as the source CoS.

Option -p parameter list format is now:


Where <src_cos> is optional and number of "xxx", "yyy", etc. parameters is
term depend.

Added -v option which prints received packet with CoS queue
name. This can be used for debugging classification rules.



Fix bug in timer start offset calculation. Test results were offset by current
local time value.

Added delay and extra schedule calls to ensure that (software) timer
implementation has passed its initial state before setting up timers.

Added -f option to control offset to the first timer. This can be used e.g. to
avoid best/worst case synchronization of timers to timer tick boundaries /


Added ICMP support. Print ICMP offset and ICMPv4 type/code. This helps to verify
that ping requests are received.


Added missing tests for the following packet functions:

  • odp_packet_data_seg_len()
  • odp_packet_free_sp()
  • odp_packet_from_event_multi()
  • odp_packet_to_event_multi()
  • odp_packet_subtype()
  • odp_packet_parse()
  • odp_packet_parse_multi()



Cleaned up implementation. Fixed endianness.

Inline Timer

Cleaned up code. Fixed accuracy issue with high resolution (<100us) timer pools.
Added configuration option inline_poll_interval_nsec to select default poll
interval in nsec.

Added configure file option for inline timer (inline_thread_type) to select if
control threads poll shared timer pools or not. Control threads still poll their
private pools. With this user can configure control and worker threads to use
separate timer pools.

###Packet I/O
Enable explicit pktio type definition. The pktio type is selected by adding
pktio_type prefix in front of device name separated by a colon

The socket mmsg pktio implementation has been refactored and performance has
been improved.

The IPC pktio implementation has been modified to use standard ODP internal
ring_ptr_t rings to implement IPC rings. This enables removing the duplicate
_ring_t implementation.


Packet segmentation has been reimplemented using a linked list. The new
implementation is simpler and has the added benefit of greatly reducing
packet and buffer header sizes.

Bug Fixes

Unnumbered Bugs / Issues

  • Fixed socket mmap pktio throughput collapse under heavy traffic

  • Fixed missing config header in install directory

  • Include only ODP defines in autogenerated header files

  • Fixed GCC 9 address-of-packed-member warnings

  • Disable building static test applications without static ODP lib

  • Fixed a segfault in odp_pktin_recv_mq_tmo() implementation

  • Fixed classifier vlan match bugs and tests

  • Fixed classifier matching of parallel PMRs

Assets 2

@MatiasElo MatiasElo released this Aug 22, 2019

OpenDataPlane (

Summary of Changes

ODP v1.22.0.0 adds several smaller API changes mainly related to API

API Changes

Added odp_queue_order_t parameter to odp_queue_param_t

Added a parameter to control if a destination queue does not require event
re-ordering. By default, event order is maintained for all destination queues as
before. Application may use ODP_QUEUE_ORDER_IGNORE for those queues that are
used under ordered queue context, but do not require re-ordering and/or do need
to avoid extra re-ordering delays.

Added ODP_SHM_HP flag for odp_shm_reserve()

When set, this flag guarantees that the memory reserved by odp_shm_reserve()
is allocated from huge pages. If enough huge page memory is not available the
call will fail.

Improved initialization and termination specification

Improve specification of initialization and termination steps. Explicitly list
those functions that may be used before global init (those that are needed for
setting up parameters). No changes to functionality.

Improved queue context specification

Highlight that queue context default value is NULL. This was defined already in
odp_queue_param_t specification.

New Crypto Algorithm Support

Support for new crypto algorithms is added by defining symbols for:


Support for new crypto authentication algorithms is added by defining symbols


Added enumeration for digest (unkeyed) algorithms. They are added as auth
algorithms with empty key required.


Crypto specification improvements / fixes

Correct documentation for ODP_AUTH_ALG_SNOW3G_UIA2 to reference 128-EIA1
instead of 128-EEA1.

Clarify IV data format and point to proper documents for 3GPP algorithms.

Timer specification clarification

Timer API intention has always been to allow any event type to be used as
timeout events. Application should use ODP_EVENT_TIMEOUT type events
(odp_timeout_t) by default, but also other event types may be used. Also,
clarified timer set/reset functionality of odp_timer_set_abs() and
odp_timer_set_rel() functions.

API functionality not changed, just wording updated.

Added timer resolution capability

Typically, timer implementation needs to trade-off between highest resolution
and longest timeout. Add new capability information
(odp_timer_res_capability_t) and function to check limits between resolution
and maximum timeout length.

This function fills in capability limits for timer pool resolution and min/max
timeout values, based on either resolution or maximum timeout.

Added defines for minute and hour

Defines for a minute and an hour are useful e.g. when setting timers for a bit
longer (background, session lifetime, etc.) timeouts.


Helper Changes

Added helper library version

Added helper library version defines, so that application can track helper
version independent of ODP API version:


Also, added a function for generating easy printout of the versions number.

The version string defines the helper library version the following format:

Added new thread create and join functions

Defined new versions of thread create and join calls. The new calls explicitly
support thread create and join in multiple steps. Also, per thread
(odph_thread_param_t) and common parameters (odph_thread_common_param_t)
have been improved.

Create and pin threads (as Linux pthreads or processes)

Wait previously launched threads to exit

Old functions odph_odpthreads_create() and odph_odpthreads_join()
have been deprecated.

Added helper debug defines

Added debug defines/macros into helper API and configure options to
enable/disable helper debugging. These defines may be used both in helper and
application code:

  • ODPH_DEBUG is 1 when helper debugging is enabled (--enable-helper-debug)
  • ODPH_DEBUG_PRINT is 1 when helper debug printing is enabled (--enable-helper-debug-print)
  • ODPH_ASSERT() generates assertion code when helper debugging is enabled

Validation Test Improvements

Timer Test Improvements

Enables passing tests on high core count devices.

Test min/max timeouts with the highest resolution and longest timeout

Scheduler Test Fixes

The group test would fail if odp_schedule(ODP_SCHED_NO_WAIT) wouldn't return
any events on the first call.

scheduler_test_pause_resume() would get stuck if all events were not
successfully enqueued.

Fixed a number of synchronization problems revealed by a scheduler
implementation doing pre-scheduling. Makes sure scheduling context is always
properly released.

Classification Test Fixes

Some of the test array elements may have not been set if the number of supported
scheduling priorities was low.

Pktio Test Improvements

Added more debug information on magic number misses.

Initialization Test Improvements / Fixes

Added missing local init/term calls to all test cases.

Added test case to set num_worker and num_control parameters.

Added test case to set not used features flags in init parameters.

Buffer Test Fixes

Test suite missed to output the return value of odp_cunit_run().

Queue Test Improvements

Check that queue context pointer value is NULL by default.

IPsec Test Fixes

Check pktio level inline IPsec support before running tests.

Crypto Test Improvements

Added support for AES-194-GMAC and AES-256-GMAC algorithms.

Added more AES-CBC and AES-CTR test vectors.

Example Changes

Added new pipeline example application

The application receives packets from one interface and passes them through 0-N
worker stages before outputting them from a second network interface. The RX,
worker, and TX stages are connected using plain queues and each stage is run on
a separate CPU thread. Optionally, the worker stages calculate CRC-32C over
packet data.

Time example fixes

Fix single worker deadlock and run the application as part of make check.

IPsec example fixes

Fixed a number of issues in IPsec example applications and run them during
make check.

New command line options


  • added -b option to control maximum packet receive burst size


  • added -n option to allocate multiple event bursts before freeing those
  • added -t option to select between buffer or packet pool types
  • added -s option to select data size


  • added -w option to simulate application work
  • added -g and -j options to test scheduling with a number of schedule groups

Implementation Improvements

Pool Implementation Improvements

Refactor local buffer caching into separate functions and optimize
implementation by caching buffer header pointers instead of indices.

New configuration options have been added for local cache
(pool:local_cache_size) and burst sizes (pool:burst_size).

Pool implementation has been modified to store buffer headers instead of
indices to reduce type conversion overhead.

Timer Implementation Improvements

Added warm up period into POSIX timer pool startup to avoid the first timeout
to slip. Otherwise, timer pthread receives the first signal after about 15ms and
first timeout of the pool slips.

DPDK Packet I/O Improvements

The zero-copy DPDK pktio implementation has been cleaned up resulting a small
performance improvement. Linking to DPDK library has also been simplified.


  • ODP project has been moved from Linaro to OpenFastPath Foundation. Project
    documentation and domain addresses have been updated to reflect this change.

  • Added --without-pcap configuration option to explicitly build ODP without
    PCAP pktio regardless of if the library is available on the build host.

  • Added --enable-lto configuration option to build ODP with link time
    optimization (-flto flag).

  • Travis default distribution is updated to Ubuntu Xenial.

  • Added -O3, -O0, and LTO build tests to Travis

  • Supported Netmap version has been bumped to v13.0

Bug Fixes

Numbered Bugs / Issues

  • Fixed: #827
    API doc links are not working

  • Fixed: #817
    ODP fails to compile with latest OpenSSL

  • Fixed: #784
    Bus error

Unnumbered Bugs / Issues

  • Fixed build problems on Debian 8

  • Fixed AES-GMAC with OpenSSL 1.1.1b and later

  • Fixed out-of-tree build

  • Fixed pcapng pipe read permissions and made possible to capture traffic from
    multiple interfaces

Assets 2
Jan 28, 2019
== OpenDataPlane (
=== Summary of Changes
ODP v1.21.0.0 adds two new API families as well as several small improvements.

==== APIs
===== Compression Support
A new family of APIs is added that provides for session-oriented support for
packet data compression and decompression. Compression sessions define the
parameters used to control compression operations and their associated
integrity hashes.  Once created, sessions are input parameters to the new
`odp_comp_op()` and `odp_comp_op_enq()` APIs that provide access to
synchronous and asynchronous compression services on packets.

Associated with the completion of asynchronous compression operations, a new
packet subtype, `ODP_EVENT_PACKET_COMP` is defined. This subtype indicates
that the packet includes additional metadata (retrievable via
`odp_comp_result()`) that provides the result of the requested operation.

A number of different compression and associated hash algorithms are defined,
which are communicated with three new capability APIs:

Provides information about general compression related capabilities
offered by this implementation

Provides details about the capabilities of individual compression algorithms

Provides details about the capabilities of individual hash algorithms
supported for use with compression.

===== Flow Aware Scheduler Support
A new capability for flow aware scheduling is added. As part of this, the
scheduler now supports capabilities and configurability. As a result, the
initialization sequence for applications that make use of the ODP scheduler
has changed slightly. The new API call sequence is:
It is a programming error to call `odp_schedule()` (or its variants) without
having first initialized the scheduler with an `odp_schedule_config()` call.
This call may only be issued once per ODP instance as scheduler configuration
is global.

By default the scheduler operates as before. When configured to operate in
flow aware mode, the scheduler will now respect event flow ids (managed by the
new `odp_event_flow_id()` and `odp_event_flow_id_set()` APIs) when making
scheduling decisions. This means that flow identification is a combination of
event flow id and queue id. For example, when operating in flow aware mode the
scheduler may dispatch events from an atomic queue to multiple threads
concurrently, as long as those events have different flow ids. For
applications that process large numbers of lightweight flows that have limited
context needs, this can lead to throughput improvements as well as reduced
implementation memory footprint.

==== DPDK v18.11 Support
The latest LTS release of DPDK (v18.11) is now supported by ODP. Support for
the previous LTS release (v17.11) is retained. Prior versions of DPDK are
no longer supported.

==== Queue Capabilities Moved to Scheduler
As part of the introduction of flow-aware scheduling, capabilities associated
with `SCHED` queues have been moved from the `odp_queue_capabilities_t` struct
returned by `odp_queue_capabilities()` to the new `odp_sched_capabilities_t`
struct returned by `odp_sched_capabilities()`.

Capabilities moved include `max_ordered_locks`, `max_sched_groups`, and
`sched_prios`. The `max_sched_groups` capability is renamed `max_groups`. In
addition, `max_queues`, `max_queue_size`, and the support capabilities for
lock free and wait free non blocking queues is now part of the scheduler

In support of flow aware scheduling mode, the `max_flows` scheduler capability
is renamed `max_flow_id`. A value of 0 indicates that flow aware mode
scheduling is not available in this ODP implementation.

=== Test/Validation Improvements
==== Travis readability improvement
The "BUILD_ONLY` environment variable has been renamed `CHECK` for improved
output readability.

==== Flow aware scheduler testing
As part of flow aware mode, scheduler validation tests will now test this mode
if `odp_schedule_capability()` indicates that flow-aware mode is supported.

=== Bug Fixes
==== Unnumbered Bugs/Issues

* Latest version of netmap `nm_ring_empty()` implementation has changed.
PktIO netmap support updated to support this as well as previous releases.

* Improved compatibility of PktIO socket support with latest versions
of the clang compiler.

* Add match pattern for missing DPDK PMD drivers for improved compatibility.
Dec 4, 2018
== OpenDataPlane (
=== Summary of Changes
ODP v1.20.0.0 is a refresh of ODP, incorporating significant configurability
and performance improvements as well as new APIs and API restructures.

==== APIs
===== Symbol `ODP_SHM_NULL` Removed.
An invalid `odp_shm_t` has the value `ODP_SHM_INVALID`, consistent with other
ODP types. The legacy synonym `ODP_SHM_NULL` is now removed for consistency.

===== New 3GPP Crypto Algorithm Support
New support for 3GPP crypto algorithms is added by defining symbols for


In addition new authentication algorithm symbols are defined for


These values are returned as ODP capabilities as well as being accepted in
crypto session creation for implementations that indicate support for them.

===== Crypto Capability for Bitwise Operation
The new `bit_mode` capability Boolean is added to the
`odp_crypto_cipher_capability_t` struct to indicate that an implementation
supports operating in bit mode. When operating in bit
mode, field offsets and lengths are expressed in terms of bits rather than
bytes. However, such lengths must always be specified in multiples of 8.

===== Improved Crypto Spec Documentation
The ODP crypto API specification is tightened to specify default values for
cipher and authentication algorithms. Also documented when key and IV
parameters need to be set.

===== IPsec Extensions
IPsec requires "salt" (extra keying material) when the GMAC authentication
algorithm is used. To accommodate this the `auth_key_extra` field is added to
the `odp_ipsec_crypto_param_t` struct and documentation is added clarifying
when this field is needed and how it should be used.

===== Classifier Type Rename
The `odp_pmr_t` type name for an invalid value is renamed from `ODP_PMR_INVAL`
to `ODP_PMR_INVALID` for consistency with the rest of ODP type names. The old
symbol is still available when ODP is configured with

===== New API for Packet Event Subtypes
The `odp_packet_subtype()` API is added that returns the subtype of a packet
event directly.

===== Streamlined Packet Parsing Results
The `odp_packet_parse_result()` API is added that returns the result of
packet parsing as a single `odp_packet_parse_result_t` struct. This can
offer efficiency improvements for applications that need all parse results
rather than making individual parse result calls.

===== PktIO Extensions to Support per-Queue Configuration
PktIO interfaces support multiple input queues to enable increased parallelism
in I/O processing. Previously, all of these input queues were required to
belong to the same scheduler group. The `odp_pktin_queue_param_t` struct is
now extended with an optional `odp_pktin_queue_param_ovr_t` struct that
permits individual pktin queues to be assigned to separate scheduler groups.
This may permit improved performance for advanced application use cases.

===== Timer Pool Capabilities
The `odp_timer_capability_t` struct is extended to return three additional
pieces of information:

The total number of timer pools that can be created combining different
clock sources

The maximum number of timer pools for a given clock source.

The maximum number of timers in a single pool. A zero value means number is
limited only by available memory.

===== Add Scheduler mix/max/default Priority Functions
Three new APIs: `odp_schedule_max_prio()`, `odp_schedule_min_prio()`, and
`odp_schedule_default_prio()` are added that return the min, max, and default
values specified for the `prio` field in the `odp_schedule_param_t` struct.

With the introduction of these scheduling priority functions the previously
`ODP_SCHED_PRIO_LOWEST`) are now deprecated and should no longer be used.

===== Specification of `odp_schedule_prio_t` as an `int`
Previously, the `odp_schedule_prio_t` type definition was left to each
implementation. With the addition of explicit schedule priority ranges, this
type is now specified to be an `int` to permit efficient implementation
(including inlining) of these functions.

====== New Scheduler APIs
The new scheduler APIs `odp_schedule_multi_wait()` and
`odp_schedule_multi_no_wait()` are added to provide more efficiently
implementable versions of these functions. The existing scheduler APIs remain
unchanged. These new APIs can simply provide a fastpath for some
applications/implementations as an alternative to specifying a parameter on

===== Memory Model in `odp_init_global()`
The `odp_init_t` parameter passed to `odp_init_global()` is extended to
add the `mem_model` field. This field is defined by the new `odp_mem_model_t`
struct and is used to specify whether the application will be using a
memory model. The default is a thread model is used for compatibility with
previous levels of ODP.

==== ABI Changes
A number of changes to the ODP ABI have also been made in this release to
improve application binary portability.

===== Strong Typing for Timer Pools
The `odp_timer_pool_t` is now strongly typed.

===== Consistent Initialization
The values of the various `ODP_xxx_INVALID` symbols for ODP abstract types in
the `odp-linux` reference implementation are now consistently zeros. This
reduces errors and improves portability.

=== Implementation Improvements
==== Configuration File
A new configuration file mechanism is introduced that makes use of[libconfig] to
enable various runtime ODP parameters to be specified dynamically.

Default configuration values for the `odp-linux` reference implementation are
contained in the `config/odp-linux-generic.conf` file. Users may override
these default values by supplying their own configuration file. At
`odp_init_global()` time, if the `ODP_CONFIG_FILE` environment variable is set,
this is used to locate the path to the override configuration file.

==== Process Mode Support
The `odp-linux` reference implementation now supports applications that run in
process mode (`mem_model` = `ODP_MEM_MODEL_PROCESS`) as well as the default
thread mode. This support only applies within a single ODP instance, so any
`fork()` calls must be done only _after_ `odp_init_global()` has been called
to initialize ODP on a root process.

==== Removal of `iQuery` Scheduler
The `iQuery` scheduler is removed from the `odp-linux` reference
implementation, as it offers no performance advantages and has not seen
application use.

==== Number of CPUs
The `odp-linux` reference implementation now supports up to 256 CPUs by
default (increased from 128).

==== Support for Large Burst Sizes
The `odp-linux` reference implementation now supports large burst sizes for
both I/O and non-I/O scheduled events. Large bursts (when available) are
received directly to the application without any stashing for improved
throughput. Burst sizes are configurable via the new configuration file
mechanism, as described above.

==== `--without-openssl` Warnings
When building `odp-linux` using `--without-openssl` a warning will be issued
cautioning that strong cryptography will not be available.

==== Inline Queue Enq/Deq APIs
The various enq/deq APIs are now subject to inlining when `odp-linux` is
built with `--disable-abi-compat`.

==== Configurable Timer Controls
Inline timers are now controlled via a config file option. Timer polling
frequency is similarly controlled via the config file.

==== Huge Page Configuration
The config file is now used to specify the huge page usage limit.

==== Single and Multi-Consumer/Producer Rings
The queue implementation in `odp-linux` now automatically makes use of
optimized single and multi-consumer/producer rings to significantly speed
up enq/deq processing.

==== `odp_shm_print_all()` Improvements
The output from `odp_shm_print_all()` is reworked to provide more useful
and comprehensive shared memory usage information in `odp-linux`.

==== IPsec Improvements
SA lifetime checking is now more scalable to multiple threads. This
significantly reduces overhead for multithreaded IPsec applications.

==== Native Builds
When running in non-ABI compatibility mode, `odp-linux` now enables
native machine-specific optimizations for the CPU architecture of the
local machine.

=== Validation Test Improvements
==== SCTP Test Packets
SCTP test packets are now used in parser testing. SCTP headers are added to
ODP and ODP helpers and SCTP checksums are now inserted and verified as part
of validation testing.

==== `odp_packet_reset()` Test
The packet validation test suite now properly tests `odp_packet_reset()`.

=== Helper Changes
In support of process mode, ODP helper functions have been changed to
better match these new capabilities

==== New `enum`
The `odph_linux_thread_type_t enum` has been replaced with the new
`odp_mem_model_t` type.

==== Helper Options
The new `odph_options()` getter function is added that returns
applicable options in effect via the new `odph_helper_options_t` struct.
This currently includes the memory model (thread or process) that is in use.

==== SCTP Helpers
The new helper APIs `odph_sctp_chksum_set()` and `odph_sctp_chksum_verify()`
are added to facilitate working with SCTP packet checksums.

=== Performance Test Improvements
==== Pool Performance
A new `odp_pool_perf` test has been added that stress-tests ODP pool
functions in a multithreaded environment to generate performance statistics.

==== Scheduler Performance
A new `odp_sched_perf` test has been added that stress-tests the scheduler
in a multithreaded environment.

==== CPU Performance
A new `odp_cpu_bench` performance test has been added that runs
compute-intensive packet operations in a multithreaded environment and prints
the observed maximum throughput for each thread.

=== Example Improvements
==== Classifier Example changes
The `odp_classifier` example program now uses a reduced number of threads by
default to reduce elapsed run time. `ODP_THREAD_COUNT_MAX` is also now used as
the max worker count.

==== Generator Improvements
The `odp_generator` example has numerous cleanups and performance improvements.

==== IPsec Example
The `odp_ipsec` example now properly stops and closes pktio devices on exit.

==== Packet Dumping
A new `odp_packet_dump` example is added that prints received packets to the
terminal. This is useful for debugging packet I/O interfaces.

==== Sysinfo Example
A new `odp_sysinfo` example is provided that prints system information. Useful
for checking the ODP environment during debugging. This includes providing
detailed information about the various crypto facilities supported, as well
as the feature flags used at build time (_e.g.,_ if the binary was built with
ARMv8.0 or ARMv8.1 instructions).

==== Traffic Manager Example
The traffic manager example now properly destroys all TM queues it creates
for improved reliability. It also now always prints a proper termination
summary message.

=== Bug Fixes
==== Numbered Bugs/Issues
=====[Bug 3983]
Compile fails on OpenSuSE 42.2 Leap with error: negative width in bit field

=====[Bug 3989]
odp_system_info_init() issues

=====[Bug 3999]
IPsec antireplay check drops packets when sequence number jumps.

=====[Bug 4002]
IPsec SA creation must fail for ESN-enabled SAs

=====[Bug 4013]
Per-SA IPv4 ID allocation may cause duplicate IDs.

=====[Bug 4017]
Unexpected IP ID causes IPsec API validation to fail

===== #662 662]
rte_mempool_ops_alloc() is not dpdk api

==== Unnumbered Bugs/Issues
* Fixed enq/deq issues encountered on architectures with weak memory ordering.
* Return 0 from `odp_sys_huge_page_size_all()` if hugepages are not
supported/detected. Tests modified to not treat this as an error.
* Set `ODP_CACHE_LINE_SIZE` to 128 on ppc64le systems.
* iplookuptable fix putting values into table
* DPDK pktio support now works properly across multiple ODP instances.
* Zero timer pool memory on reserve (fixes timer failures due to uninitialized
* `-march=native` disabled for `clang`. This fixes a known issue with recent
levels of clang.

=== Known Issues
====[Bug 3998]
IPsec extended sequence number support is missing

====[Bug 4014]
Separate IP ID allocation for transport and tunnel mode SAs may cause
duplicate IDs

====[Bug 4018]
Unexpected IV causes IPsec API validation to fail

====[Bug 4040]
Clang build fails on Ubuntu 18.04