diff mbox

[PATCHv3,3/3] doc: users-guide: add packet flow overview

Message ID 1463005931-6890-3-git-send-email-bill.fischofer@linaro.org
State New
Headers show

Commit Message

Bill Fischofer May 11, 2016, 10:32 p.m. UTC 
From: Mike Holmes <mike.holmes@linaro.org>

Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
---
 doc/users-guide/Makefile.am      |  1 +
 doc/users-guide/users-guide.adoc | 37 ++++++++++++++++++++++++++++++-------
 2 files changed, 31 insertions(+), 7 deletions(-)
 mode change 100644 => 100755 doc/users-guide/users-guide.adoc
diff mbox

Patch

diff --git a/doc/users-guide/Makefile.am b/doc/users-guide/Makefile.am
index 439ce69..77594fc 100644
--- a/doc/users-guide/Makefile.am
+++ b/doc/users-guide/Makefile.am
@@ -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 \
diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc
old mode 100644
new mode 100755
index 0221634..7053d7d
--- a/doc/users-guide/users-guide.adoc
+++ b/doc/users-guide/users-guide.adoc
@@ -298,11 +298,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`.
 
@@ -460,7 +460,27 @@  _synchronization_ mechanisms.
 . 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 provides APIs to assist in each of these areas as show below:
+
+.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.
 
 === The include structure
 Applications only include the 'include/odp_api.h' file, which includes the
@@ -509,9 +529,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"]