@@ -14,6 +14,7 @@ IMAGES = $(top_srcdir)/doc/images/overview.svg \
$(top_srcdir)/doc/images/odp_scheduling.svg \
$(top_srcdir)/doc/images/odp_traffic_manager.svg \
$(top_srcdir)/doc/images/ordered_queue.svg \
+ $(top_srcdir)/doc/images/packet_flow.svg \
$(top_srcdir)/doc/images/packet-adddata.svg \
$(top_srcdir)/doc/images/packet-align.svg \
$(top_srcdir)/doc/images/packet-copyops.svg \
old mode 100644
new mode 100755
@@ -181,7 +181,8 @@ as it scales from 4, to 40, to 400 cores.
== Organization of this Document
This document is organized into several sections. The first presents a high
-level overview of the ODP API component areas and their associated abstract
+level overview of ODP applications, the ODP API component areas,
+and their associated abstract
data types. This section introduces ODP APIs at a conceptual level.
The second provides a tutorial on the programming model(s)
supported by ODP, paying particular attention to the event model as this
@@ -194,6 +195,59 @@ full reference specification for each API. The latter is intended to be used
by ODP application programmers, as well as implementers, to understand the
precise syntax and semantics of each API.
+== ODP Applications and Packet Flow
+Data plane applications are fundamentally concerned with receiving, examining,
+manipulating, and transmitting packets. The distinguishing feature of the
+data plane is that these applications are mostly concerned with the lowest
+layers of the ISO stack (Layers 2 and 3) and they have very high to extreme
+performance requirements. ODP is designed to provide a portable framework for
+such applications.
+
+At the highest level, an *ODP Application* is a program that uses one or more
+ODP APIs. Because ODP is a framework rather than a programming environment,
+applications are free to also use other APIs that may or may not provide the
+same portability characteristics as ODP APIs.
+
+ODP applications vary in terms of what they do and how they operate, but in
+general all share the following characteristics:
+
+. They are organized into one or more _threads_ that execute in parallel.
+. These threads communicate and coordinate their activities using various
+_synchronization_ mechanisms.
+. They receive packets from one or more _packet I/O interfaces_.
+. They examine, transform, or otherwise process packets.
+. They transmit packets to one or more _packet I/O interfaces_.
+
+At the highest level, an ODP application looks as follows:
+
+.ODP Application Packet Flow Overview
+image::packet_flow.svg[align="center"]
+
+Packets arrive and are received (RX) from a network interface represented by
+a _PktIO_ abstraction. From here they go either directly to _Queues_ that are
+polled by ODP _Threads_, or can pass through the _Classifier_ and sorted into
+Queues that represent individual flows. These queues can then be dispatched
+to application threads via the _Scheduler_.
+
+Threads, in term can invoke various ODP APIs to manipulate packet contents
+prior to disposing of them. For output processing, packets make by directly
+queued to a PktIO output queue or else they may be handed to the _Traffic
+Manager_ for programmatic _Quality of Service (QoS)_ processing before winding
+up being transmitted (TX). Note that output interfaces may operate in
+_loopback_ mode, in which case packets sent to them are re-routed back to the
+input lines for "second pass" processing. For example, an incoming IPSec packet
+cannot be properly classified (beyond being IPSec traffic) until it is
+decrypted. Once decrypted and its actual contents made visible, it can then
+be classified into its real flow.
+
+What is important to note is that the only part of the above diagram that need
+be written are the boxes in yellow that contain the application
+logic. Everything else shown here is provided by the ODP framework and
+available for use by any ODP application. This represents the "machinery" of a
+data plane application and is structured to allow applications written to the
+ODP APIs to be both portable and optimized for each platform that offers an
+ODP implementation without additional programming effort.
+
== ODP API Concepts
ODP programs are built around several conceptual structures that every
application programmer needs to be familiar with to use ODP effectively. The
@@ -298,11 +352,11 @@ with each packet for its own use.
Packets are represented by handles of abstract type `odp_packet_t`.
-=== PktIO
-PktIO is how ODP represents I/O interfaces. A pktio object is a logical
-port capable of receiving and/or transmitting packets. This may be directly
-supported by the underlying platform as an integrated feature,
-or may represent a device attached via a PCIE or other bus.
+=== Packet I/O (PktIO)
+PktIO is how ODP represents I/O interfaces. A pktio object is a logical port
+capable of receiving (RX) and/or transmitting (TX) packets. This may be
+directly supported by the underlying platform as an integrated feature, or may
+represent a device attached via a PCIE or other bus.
PktIOs are represented by handles of abstract type `odp_pktio_t`.
@@ -444,23 +498,7 @@ goals. Again, the advantage here is that on many platforms traffic management
functions are implemented in hardware, permitting transparent offload of
this work.
-== ODP Application Programming
-At the highest level, an *ODP Application* is a program that uses one or more
-ODP APIs. Because ODP is a framework rather than a programming environment,
-applications are free to also use other APIs that may or may not provide the
-same portability characteristics as ODP APIs.
-
-ODP applications vary in terms of what they do and how they operate, but in
-general all share the following characteristics:
-
-. They are organized into one or more _threads_ that execute in parallel.
-. These threads communicate and coordinate their activities using various
-_synchronization_ mechanisms.
-. They receive packets from one or more _packet I/O interfaces_.
-. They examine, transform, or otherwise process packets.
-. They transmit packets to one or more _packet I/O interfaces_.
-
-ODP provides APIs to assist in each of these areas.
+== ODP Application Programming Structure
=== The include structure
Applications only include the 'include/odp_api.h' file, which includes the
@@ -509,9 +547,12 @@ which is either `ODP_THREAD_WORKER` or `ODP_THREAD_CONTROL`.
=== Shutdown
Shutdown is the logical reverse of the initialization procedure, with
-'odp_term_local()' called for each thread before 'odp_term_global()' is
+`odp_term_local()` called for each thread before `odp_term_global()` is
called to terminate ODP.
+=== Application Initialization/Termination Structure
+ODP Applications follow the general structure flow shown below:
+
.ODP Application Structure Flow Diagram
image::resource_management.svg[align="center"]