This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "".
The branch, master has been updated
via b1564eb643c16dc98048fb9aa072580451ed90b2 (commit)
from 8b0ac26e358b7632f891557be07c8c1f43a29a4a (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit b1564eb643c16dc98048fb9aa072580451ed90b2
Author: Petri Savolainen <petri.savolainen(a)linaro.org>
Date: Thu Jan 31 11:13:35 2019 +0200
linux-gen: buffer: clean checkpatch warnings
Checkpatch reported warnings when running it against the file.
Corrected all reported warnings.
Signed-off-by: Petri Savolainen <petri.savolainen(a)linaro.org>
Reviewed-by: Matias Elo <matias.elo(a)nokia.com>
diff --git a/platform/linux-generic/odp_buffer.c b/platform/linux-generic/odp_buffer.c
index ac0b9f9c..f3864bfd 100644
--- a/platform/linux-generic/odp_buffer.c
+++ b/platform/linux-generic/odp_buffer.c
@@ -65,16 +65,16 @@ int odp_buffer_snprint(char *str, uint32_t n, odp_buffer_t buf)
hdr = buf_hdl_to_hdr(buf);
pool = hdr->pool_ptr;
- len += snprintf(&str[len], n-len,
+ len += snprintf(&str[len], n - len,
"Buffer\n");
- len += snprintf(&str[len], n-len,
+ len += snprintf(&str[len], n - len,
" pool %" PRIu64 "\n",
odp_pool_to_u64(pool->pool_hdl));
- len += snprintf(&str[len], n-len,
+ len += snprintf(&str[len], n - len,
" addr %p\n", hdr->seg[0].data);
- len += snprintf(&str[len], n-len,
+ len += snprintf(&str[len], n - len,
" size %" PRIu32 "\n", odp_buffer_size(buf));
- len += snprintf(&str[len], n-len,
+ len += snprintf(&str[len], n - len,
" type %i\n", hdr->type);
return len;
@@ -86,7 +86,7 @@ void odp_buffer_print(odp_buffer_t buf)
char str[max_len];
int len;
- len = odp_buffer_snprint(str, max_len-1, buf);
+ len = odp_buffer_snprint(str, max_len - 1, buf);
str[len] = 0;
ODP_PRINT("\n%s\n", str);
-----------------------------------------------------------------------
Summary of changes:
platform/linux-generic/odp_buffer.c | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
hooks/post-receive
--
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "".
The annotated tag, v1.21.0.0 has been created
at 62b0005078c07a7f44f084dc6785265a3607e6f0 (tag)
tagging 8b0ac26e358b7632f891557be07c8c1f43a29a4a (commit)
replaces v1.20.0.0
tagged by Maxim Uvarov
on Mon Jan 28 16:48:09 2019 +0300
- Log -----------------------------------------------------------------
== OpenDataPlane (1.21.0.0)
=== 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:
`odp_comp_capability()`::
Provides information about general compression related capabilities
offered by this implementation
`odp_comp_alg_capability()`::
Provides details about the capabilities of individual compression algorithms
supported.
`odp_comp_hash_alg_capability()`::
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:
[source,c]
-----
odp_schedule_capability()
odp_schedule_config_init()
odp_schedule_config()
odp_schedule()
-----
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
capabilities.
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.
Balasubramanian Manoharan (1):
api: comp: compression specification
Bill Fischofer (3):
doc: userguide: add documentation for flow aware scheduler mode
doc: userguide: add section for compression support
changelog: add change log updates for odp v1.21.0.0
Dmitry Eremin-Solenikov (31):
api: queue, schedule: move scheduler capabilities to scheduler
linux-gen: move NUM_INTERNAL_QUEUES to config
linux-gen: queue, schedule: move scheduler capabilities to scheduler
example, tests: move scheduler capabilities to scheduler
api: queue, schedule: move scheduled queue capabilities to sched
linux-gen: queue, schedule: move scheduled queue capabilities to sched
example, tests: move scheduled queue capabilities to sched
api: schedule: add scheduler config and start API
api: schedule: add scheduler flow aware mode
linux-gen: schedule: rename config to get_config
linux-gen: implement odp_schedule_config() API call
validation: add calls to odp_schedule_config()
performance: add calls to odp_schedule_config()
examples: add calls to odp_schedule_config()
validation: scheduler use schedule_config instead of capabilities
linux-gen: event: support flow-awareness API
api: event: define ODP_EVENT_PACKET_COMP
api: fix compression API headers
linux-gen: add compression ABI file
linux-gen: event: define ODP_EVENT_PACKET_COMP
validation: add compression tests
linux-gen: comp: add stub implementation
linux-gen: add miniz library at 3a884afaa7a9eefb4eb80041aee6e7995a2f5215
linux-gen: miniz local modifications
linux-gen: comp: add deflate/zlib implementation based on miniz
validation: add comp_main to .gitignore
linux-gen: miniz: disable unaligned loads/stores to fix compilation with clang
m4: move -lnuma detection to global file
build: support detection of DPDK through pkg-config
build: provide PKG_CHECK_MODULES_STATIC implementation
linux-gen: fix compiling dpdk pktio with Clang
Matias Elo (8):
linux-gen: netmap: update ring->head in netmap_recv_desc()
linux-gen: socket_mmap: fix build with older clang versions
linux-gen: dpdk: fix build with no pmd drivers
travis: add CentOS 7 build test
travis: rename BUILD_ONLY to CHECK
test: odp_pktio_ordered: add missing schedule_config initialization
linux-gen: dpdk: add a fallback value for the number of numa nodes
travis: add dpdk 18.11 test
Maxim Uvarov (1):
changelog: updates for odp v1.21.0.0
Petri Savolainen (7):
linux-gen: dpdk: support DPDK version up to v18.11
dependencies: dpdk: list supported versions
api: sched: max_flow_id capability
linux-gen: sched: check that config has been done
validation: sched: add flow aware test case
linux-gen: sched: dummy flow aware implementation
dependencies: add libconfig package name
-----------------------------------------------------------------------
hooks/post-receive
--
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "".
The branch, master has been updated
via 8b0ac26e358b7632f891557be07c8c1f43a29a4a (commit)
from a0038f5d6a06aaf3596adddfb950011abe2aa8bd (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 8b0ac26e358b7632f891557be07c8c1f43a29a4a
Author: Maxim Uvarov <maxim.uvarov(a)linaro.org>
Date: Mon Jan 28 16:26:52 2019 +0300
changelog: updates for odp v1.21.0.0
Signed-off-by: Maxim Uvarov <maxim.uvarov(a)linaro.org>
diff --git a/configure.ac b/configure.ac
index 8efb8525..f6eeeb7e 100644
--- a/configure.ac
+++ b/configure.ac
@@ -3,7 +3,7 @@ AC_PREREQ([2.5])
# Set correct API version
##########################################################################
m4_define([odpapi_generation_version], [1])
-m4_define([odpapi_major_version], [20])
+m4_define([odpapi_major_version], [21])
m4_define([odpapi_minor_version], [0])
m4_define([odpapi_point_version], [0])
m4_define([odpapi_version],
-----------------------------------------------------------------------
Summary of changes:
configure.ac | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
hooks/post-receive
--
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "".
The branch, master has been updated
via a0038f5d6a06aaf3596adddfb950011abe2aa8bd (commit)
from 3a9cf94b77aab17ea6d94bd8c8b667f183ee1521 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit a0038f5d6a06aaf3596adddfb950011abe2aa8bd
Author: Bill Fischofer <bill.fischofer(a)linaro.org>
Date: Wed Jan 23 14:18:18 2019 -0600
changelog: add change log updates for odp v1.21.0.0
Add the updates to the ODP change log for the v1.21.0.0 release.
Signed-off-by: Bill Fischofer <bill.fischofer(a)linaro.org>
Reviewed-by: Petri Savolainen <petri.savolainen(a)linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov(a)linaro.org>
diff --git a/CHANGELOG b/CHANGELOG
index a0bdf558..3322ea7c 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,105 @@
+== OpenDataPlane (1.21.0.0)
+=== 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:
+
+`odp_comp_capability()`::
+Provides information about general compression related capabilities
+offered by this implementation
+
+`odp_comp_alg_capability()`::
+Provides details about the capabilities of individual compression algorithms
+supported.
+
+`odp_comp_hash_alg_capability()`::
+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:
+[source,c]
+-----
+odp_schedule_capability()
+odp_schedule_config_init()
+odp_schedule_config()
+odp_schedule()
+-----
+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
+capabilities.
+
+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.
+
== OpenDataPlane (1.20.0.0)
=== Summary of Changes
ODP v1.20.0.0 is a refresh of ODP, incorporating significant configurability
-----------------------------------------------------------------------
Summary of changes:
CHANGELOG | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 102 insertions(+)
hooks/post-receive
--
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "".
The branch, master has been updated
via 5c69d869bc287afd48d57c841e1d68728e646cbb (commit)
from 45caf39520a1f7aac3e40265bc46bc4dba695cbc (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 5c69d869bc287afd48d57c841e1d68728e646cbb
Author: Matias Elo <matias.elo(a)nokia.com>
Date: Thu Jan 17 13:06:10 2019 +0200
travis: add dpdk 18.11 test
Signed-off-by: Matias Elo <matias.elo(a)nokia.com>
Reviewed-by: Bill Fischofer <bill.fischofer(a)linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov(a)linaro.org>
diff --git a/.travis.yml b/.travis.yml
index c308d5ed..bbcec4fd 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -155,6 +155,18 @@ jobs:
-e ODP_CONFIG_FILE=/odp/platform/linux-generic/test/process-mode.conf
-e ODPH_PROC_MODE=1
${DOCKER_NAMESPACE}/travis-odp-lng-ubuntu_16.04 /odp/scripts/ci/check.sh
+ - stage: test
+ env: TEST=dpdk_18.11
+ install:
+ - true
+ compiler: gcc
+ script:
+ - if [ -z "${DOCKER_NAMESPACE}" ] ; then export DOCKER_NAMESPACE="opendataplane"; fi
+ - docker run --privileged -i -t
+ -v `pwd`:/odp --shm-size 8g
+ -e CC="${CC}"
+ -e CONF=""
+ ${DOCKER_NAMESPACE}/travis-odp-lng-ubuntu_16.04-dpdk_18.11 /odp/scripts/ci/check.sh
- stage: test
env: TEST=inline_timer
install:
-----------------------------------------------------------------------
Summary of changes:
.travis.yml | 12 ++++++++++++
1 file changed, 12 insertions(+)
hooks/post-receive
--
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "".
The branch, master has been updated
via 45caf39520a1f7aac3e40265bc46bc4dba695cbc (commit)
from de255937275a99cebe62f159f3fc7c4b70bc04bb (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 45caf39520a1f7aac3e40265bc46bc4dba695cbc
Author: Matias Elo <matias.elo(a)nokia.com>
Date: Thu Jan 17 11:12:16 2019 +0200
linux-gen: dpdk: add a fallback value for the number of numa nodes
numa_num_configured_nodes() may return 0 on some platforms. In that case
use 1 as a replacement value.
Signed-off-by: Matias Elo <matias.elo(a)nokia.com>
Reviewed-by: Bill Fischofer <bill.fischofer(a)linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov(a)linaro.org>
diff --git a/platform/linux-generic/pktio/dpdk.c b/platform/linux-generic/pktio/dpdk.c
index 1edd2488..1d322057 100644
--- a/platform/linux-generic/pktio/dpdk.c
+++ b/platform/linux-generic/pktio/dpdk.c
@@ -1197,7 +1197,11 @@ static int dpdk_pktio_init(void)
}
mem_str_len = snprintf(NULL, 0, "%d,", DPDK_MEMORY_MB);
+
+ /* numa_num_configured_nodes() may return 0 on some platforms */
numa_nodes = numa_num_configured_nodes();
+ if (numa_nodes <= 0)
+ numa_nodes = 1;
char mem_str[mem_str_len * numa_nodes];
-----------------------------------------------------------------------
Summary of changes:
platform/linux-generic/pktio/dpdk.c | 4 ++++
1 file changed, 4 insertions(+)
hooks/post-receive
--
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "".
The branch, master has been updated
via de255937275a99cebe62f159f3fc7c4b70bc04bb (commit)
from c419dc00dd13fc2760ae1dbe370a3285893c58f6 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit de255937275a99cebe62f159f3fc7c4b70bc04bb
Author: Matias Elo <matias.elo(a)nokia.com>
Date: Wed Jan 16 15:31:51 2019 +0200
test: odp_pktio_ordered: add missing schedule_config initialization
Signed-off-by: Matias Elo <matias.elo(a)nokia.com>
Reported-by: Jari Mustajärvi <jari.mustajarvi(a)nokia-bell-labs.com>
Reviewed-by: Bill Fischofer <bill.fischofer(a)linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov(a)linaro.org>
diff --git a/test/performance/odp_pktio_ordered.c b/test/performance/odp_pktio_ordered.c
index 15229aeb..51ec03ce 100644
--- a/test/performance/odp_pktio_ordered.c
+++ b/test/performance/odp_pktio_ordered.c
@@ -1130,7 +1130,8 @@ int main(int argc, char *argv[])
/* Parse and store the application arguments */
parse_args(argc, argv, &gbl_args->appl);
- odp_schedule_config(NULL);
+ odp_schedule_config_init(&schedule_config);
+ odp_schedule_config(&schedule_config);
if (gbl_args->appl.in_mode == SCHED_ORDERED) {
/* At least one ordered lock required */
-----------------------------------------------------------------------
Summary of changes:
test/performance/odp_pktio_ordered.c | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
hooks/post-receive
--
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "".
The branch, master has been updated
via c419dc00dd13fc2760ae1dbe370a3285893c58f6 (commit)
from eac3c037e7547b1ed1a15f0ee2e0daccacc88ec5 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit c419dc00dd13fc2760ae1dbe370a3285893c58f6
Author: Bill Fischofer <bill.fischofer(a)linaro.org>
Date: Thu Dec 27 10:04:43 2018 -0600
doc: userguide: add documentation for flow aware scheduler mode
Update the ODP User Guide to include information on scheduler
capabilities and configuration and operating in flow aware mode.
Signed-off-by: Bill Fischofer <bill.fischofer(a)linaro.org>
Reviewed-by: Petri Savolainen <petri.savolainen(a)linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov(a)linaro.org>
diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc
index 8ed581f5..4ec7cd72 100644
--- a/doc/users-guide/users-guide.adoc
+++ b/doc/users-guide/users-guide.adoc
@@ -965,7 +965,7 @@ same value on all ODP threads, for a given memory block, in this case)
Note that ODP implementations may have restrictions of the amount of memory
which can be allocated with this flag.
-== Queues
+== Queues and the Scheduler
Queues are the fundamental event sequencing mechanism provided by ODP and all
ODP applications make use of them either explicitly or implicitly. Queues are
created via the 'odp_queue_create()' API that returns a handle of type
@@ -1184,11 +1184,179 @@ until the locking order for this lock for all prior events has been resolved
and then enters the critical section. The *odp_schedule_order_unlock()* call
releases the critical section and allows the next order to enter it.
+=== Scheduler Capabilities and Configuration
+As with other ODP components, the ODP scheduler offers a range of capabilities
+and configuration options that are used by applications to control its
+behavior.
+
+The sequence of API calls used by applications that make use of the scheduler
+is as follows:
+
+.ODP API Scheduler Usage
+[source,c]
+-----
+odp_schedule_capability()
+odp_schedule_config_init()
+odp_schedule_config()
+odp_schedule()
+-----
+The `odp_schedule_capability()` API returns an `odp_schedule_capability_t`
+struct that defines various limits and capabilities offered by this
+implementation of the ODP scheduler:
+
+.ODP Scheduler Capabilities
+[source,c]
+-----
+/**
+ * Scheduler capabilities
+ */
+typedef struct odp_schedule_capability_t {
+ /** Maximum number of ordered locks per queue */
+ uint32_t max_ordered_locks;
+
+ /** Maximum number of scheduling groups */
+ uint32_t max_groups;
+
+ /** Number of scheduling priorities */
+ uint32_t max_prios;
+
+ /** Maximum number of scheduled (ODP_BLOCKING) queues of the default
+ * size. */
+ uint32_t max_queues;
+
+ /** Maximum number of events a scheduled (ODP_BLOCKING) queue can store
+ * simultaneously. The value of zero means that scheduled queues do not
+ * have a size limit, but a single queue can store all available
+ * events. */
+ uint32_t max_queue_size;
+
+ /** Maximum flow ID per queue
+ *
+ * Valid flow ID range in flow aware mode of scheduling is from 0 to
+ * this maximum value. So, maximum number of flows per queue is this
+ * value plus one. A value of 0 indicates that flow aware mode is not
+ * supported. */
+ uint32_t max_flow_id;
+
+ /** Lock-free (ODP_NONBLOCKING_LF) queues support.
+ * The specification is the same as for the blocking implementation. */
+ odp_support_t lockfree_queues;
+
+ /** Wait-free (ODP_NONBLOCKING_WF) queues support.
+ * The specification is the same as for the blocking implementation. */
+ odp_support_t waitfree_queues;
+
+} odp_schedule_capability_t;
+-----
+This struct indicates the various scheduling limits supported by this ODP
+implementation. Of note is the `max_flow_id` capability, which indicates
+whether this implementation is able to operate in _flow aware mode_.
+
+==== Flow Aware Scheduling
+A _flow_ is a sequence of events that share some application-specific meaning
+and context. A good example of a flow might be a TCP connection. Various
+events associated with that connection, such as packets containing
+connection data, as well as associated timeout events used for transmission
+control, are logically connected and meaningful to the application processing
+that TCP connection.
+
+Normally a single flow is associated with an ODP queue. That is, all events
+on a given queue belong to the same flow. So the queue id is synonymous with
+the flow id for those events. However, this is not without drawbacks. Queues
+are relatively heavyweight objects and provide both synchronization as well as
+user contexts. The number of queues supported by a given implementation
+(`max_queues`) may be less than the number of flows an application needs to
+be able to process.
+
+To address these needs, ODP allows schedulers to operate in flow aware mode
+in which flow id is maintained separately as part of each event. Two new
+APIs:
+
+* `odp_event_flow_id()`
+* `odp_event_flow_id_set()`
+
+are used to query and set a 32-bit flow id associated with individual events.
+The assignment and interpretation of individual flow ids is under application
+control.
+
+When operating in flow aware mode, it is the combination of flow id and
+queue id that is used by the scheduler in making scheduling decisions. So,
+for example, an Atomic queue would normally be able to dispatch events only a
+single thread at a time. When operating in flow aware mode, however, the
+scheduler will provide this exclusion only when two events on the same atomic
+queue have the same flow id. If they have different flow ids, then they can be
+scheduled concurrently to different threads.
+
+Note that when operating in this mode, any sharing of queue context must be
+done with application-provided synchronization controls (similar to how
+parallel queues behave).
+
+==== Scheduler Configuration
+After determining the scheduler's capabilities, but before starting to use
+the scheduler to process events, applications must configure the scheduler
+by calling `odp_schedule_config()`.
+
+The argument to this call is the `odp_schedule_config_t` struct:
+
+.ODP Scheduler Configuration
+[source,c]
+-----
+/**
+ * Schedule configuration
+ */
+typedef struct odp_schedule_config_t {
+ /** Maximum number of scheduled queues to be supported.
+ *
+ * @see odp_schedule_capability_t
+ */
+ uint32_t num_queues;
+
+ /** Maximum number of events required to be stored simultaneously in
+ * scheduled queue. This number must not exceed 'max_queue_size'
+ * capability. A value of 0 configures default queue size supported by
+ * the implementation.
+ */
+ uint32_t queue_size;
+
+ /** Maximum flow ID per queue
+ *
+ * This value must not exceed 'max_flow_id' capability. Flow aware
+ * mode of scheduling is enabled when the value is greater than 0.
+ * The default value is 0.
+ *
+ * Application can assign events to specific flows by calling
+ * odp_event_flow_id_set() before enqueuing events into a scheduled
+ * queue. When in flow aware mode, the event flow id value affects
+ * scheduling of the event and synchronization is maintained per flow
+ * within each queue.
+ *
+ * Depeding on implementation, there may be much more flows supported
+ * than queues, as flows are lightweight entities.
+ *
+ * @see odp_schedule_capability_t, odp_event_flow_id()
+ */
+ uint32_t max_flow_id;
+
+} odp_schedule_config_t;
+-----
+The `odp_schedule_config_init()` API should be used to initialize this
+struct to its default values. The application then sets whatever
+overrides it needs prior to calling `odp_schedule_config()` to activate
+them. Note that `NULL` may be passed as the argument to `odp_schedule_config()`
+if the application simply wants to use the implementation-defined default
+configuration. In the default configuration, the scheduler does not operate in
+flow aware mode.
+
+Once configured, `odp_schedule()` calls can be made to get events. It is
+a programming error to attempt to use the scheduler before it has been
+configured.
+
=== Queue Scheduling Summary
NOTE: Both ordered and parallel queues improve throughput over atomic queues
due to parallel event processing, but require that the application take
-steps to ensure context data synchronization if needed.
+steps to ensure context data synchronization if needed. The same is true for
+atomic queues when the scheduler is operating in flow aware mode.
include::users-guide-packet.adoc[]
-----------------------------------------------------------------------
Summary of changes:
doc/users-guide/users-guide.adoc | 172 ++++++++++++++++++++++++++++++++++++++-
1 file changed, 170 insertions(+), 2 deletions(-)
hooks/post-receive
--