@@ -41,4 +41,83 @@ associated with the pktio device over which the packet is to be sent, the
implementation is then responsible for taking the packet from the output queue
and effecting its transmission.
+@section func Functional Description
+
+The pktio APIs define the following handles to be used to access a pktio
+interface;
+
+ - @c odp_pktio_t one per interface, all configuration of the interface is
+ performed using a handle of this type. There can be only one handle of this
+ type per interface at any time.
+ - @c odp_pktio_worker_t one per interface for each worker thread, used for I/O
+ and read only access to pktio configuration.
+
+@subsection initialisation_sequence Initialisation sequence
+
+The following section walks through a simplified example of an initialisation
+sequence an ODP application may go through to use a pktio device.
+
+1. Call @c odp_global_init(), if necessary passing platform specific information
+ required to configure the pktio interfaces.
+2. Call @c odp_cos_create() to create a CoS.
+3. Call @c odp_buffer_pool_create() to create pool of buffers of type
+ @c ODP_BUFFER_TYPE_PACKET and and call @c odp_cos_set_pool() to associate it
+ with the CoS, so that packets matching this CoS will be allocated from this
+ pool.
+4. Call @c odp_queue_create() to create a queue of type ODP_QUEUE_TYPE_PKTIN
+ and call @c odp_pktio_set_default_cos() to associate it with the CoS so that
+ matching packets matching this CoS will be delivered to this queue.
+5. Call @c odp_pktio_open() passing the above CoS as the default CoS for the
+ interface. As there are no L2/L3/PMR rules paired with the pktio interface,
+ all received packets will be assigned the default class of service.
+6. Start calling @c odp_schedule() from each of the worker tasks to begin
+ receiving packets.
+7. For each received packet, call @c odp_packet_outq() to determine which
+ output queue is to be used for transmission based on which interface the
+ packet was received on.
+8. Call @c odp_queue_enq() to queue the packet for transmission on the selected
+ output queue.
+
+Steps 1 to 5 would typically be performed at application startup in the main
+thread. The worker tasks at step 7 could be active prior to any of the previous
+steps, but packets only start being delivered after the association between the
+pktio interface and the input queue is made during the odp_pktio_open() call.
+
+Further examples showing different ways an application can use the API are
+found in the \ref examples section later in the document.
+
+@subsection ordering Ordering and Atomicity
+
+There are two methods of receiving or sending packets via a pktio device,
+either working directly with the pktio device via odp_pktio_recv/send or
+indirectly via queues and the scheduler. The application writer must select
+the method that best suits their requirements, using both methods for a single
+interface is not supported.
+
+In ODP, ordering and atomicity are functions of the scheduler, and in many cases
+obtaining packets via the scheduler is how the best performance will be achieved,
+particularly on platforms that make use of a hardware accelerated scheduler.
+
+Directly invoking send/recv on the pktio interface avoids the scheduler and
+therefore the application is given no guarantees of ordering or atomicity.
+There are however some cases where this can offer a performance improvement, for
+example if the application maintains order by some other means such as only
+accessing and interface from a single core, as it avoids the need to invoke the
+scheduler and enqueue/dequeue packets.
+
+@subsection ifacetypes Supporting multiple interface types
+
+Some platforms have a number of different types of pktio interface, or at least
+a number of different configuration options for a single type of interface. In
+order for the ODP API to remain portable these differences must not require the
+application to take platform specific code paths. The general mechanism for
+coping with this is to assign a unique identifier to each interface (a character
+string), this identifier is essentially opaque to the API but it used by the
+implementation to determine which underlying interface is being accessed and
+therefore the mechanisms used to work with it.
+
+In addition to this the application can provide platform specific
+initialisation data to odp_global_init() which can be used to configure
+non-portable properties of the interface implementation.
+
*/
Signed-off-by: Anders Roxell <anders.roxell@linaro.org> --- packet_io.dox | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+)