doc: userguide: change plus to backtick for asciidoctor

In asciidoc monospace characters may be indicated by enclosure
in either backticks or plus signs, however asciidoctor requires
the use of backticks to indicate monospace. Change all uses of
plus signs to backticks so that user guide docs can format
properly using either asciidoc or asciidoctor. Going forward
only backticks should be used to indicate monospace font.

Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
---
 doc/glossary.adoc                      |  10 +--
 doc/users-guide/users-guide-cls.adoc   |   4 +-
 doc/users-guide/users-guide-pktio.adoc |  98 +++++++++++++-------------
 doc/users-guide/users-guide-tm.adoc    |   2 +-
 doc/users-guide/users-guide.adoc       | 124 ++++++++++++++++-----------------
 5 files changed, 119 insertions(+), 119 deletions(-)

On 3 May 2016 at 15:28, Bill Fischofer <bill.fischofer@linaro.org> wrote:

> In asciidoc monospace characters may be indicated by enclosure

> in either backticks or plus signs, however asciidoctor requires

> the use of backticks to indicate monospace. Change all uses of

> plus signs to backticks so that user guide docs can format

> properly using either asciidoc or asciidoctor. Going forward

> only backticks should be used to indicate monospace font.

>

> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>

>


Reviewed-by: Mike Holmes <mike.holmes@linaro.org>



> ---

>  doc/glossary.adoc                      |  10 +--

>  doc/users-guide/users-guide-cls.adoc   |   4 +-

>  doc/users-guide/users-guide-pktio.adoc |  98 +++++++++++++-------------

>  doc/users-guide/users-guide-tm.adoc    |   2 +-

>  doc/users-guide/users-guide.adoc       | 124

> ++++++++++++++++-----------------

>  5 files changed, 119 insertions(+), 119 deletions(-)

>

> diff --git a/doc/glossary.adoc b/doc/glossary.adoc

> index 3106e19..2c0de24 100644

> --- a/doc/glossary.adoc

> +++ b/doc/glossary.adoc

> @@ -10,7 +10,7 @@ control thread::

>      operating system house keeping tasks but will be scheduled by it and

> may

>      receive interrupts.

>  ODP instantiation process::

> -    The process calling +odp_init_global()+, which is probably the

> +    The process calling `odp_init_global()`, which is probably the

>      first process which is started when an ODP application is started.

>      There is one single such process per ODP instantiation.

>  thread::

> @@ -19,13 +19,13 @@ thread::

>  ODP thread::

>      An ODP thread is a flow of execution that belongs to ODP:

>      Any "flow of execution" (i.e. OS process or OS thread) calling

> -    +odp_init_global()+, or +odp_init_local()+ becomes an ODP thread.

> +    `odp_init_global()`, or `odp_init_local()` becomes an ODP thread.

>      This definition currently limits the number of ODP instances on a

> given

> -    machine to one. In the future +odp_init_global()+ will return

> something

> -    like an ODP instance reference and +odp_init_local()+ will take such

> +    machine to one. In the future `odp_init_global()` will return

> something

> +    like an ODP instance reference and `odp_init_local()` will take such

>      a reference in parameter, allowing threads to join any running ODP

> instance.

>      Note that, in a Linux environment an ODP thread can be either a Linux

> -    process or a linux thread (i.e. a linux process calling

> +odp_init_local()+

> +    process or a linux thread (i.e. a linux process calling

> `odp_init_local()`

>      will be referred as ODP thread, not ODP process).

>  event::

>      An event is a notification that can be placed in a queue.

> diff --git a/doc/users-guide/users-guide-cls.adoc

> b/doc/users-guide/users-guide-cls.adoc

> index d306c1c..d2ba743 100644

> --- a/doc/users-guide/users-guide-cls.adoc

> +++ b/doc/users-guide/users-guide-cls.adoc

> @@ -99,7 +99,7 @@ to be processed.

>

>  === Default packet handling

>

> -There is a +odp_cos_t+ assigned to each port with the

> +There is a `odp_cos_t` assigned to each port with the

>  odp_pktio_default_cos_set() function, which will function as the default

>  class-of-service for all packets received from an ingress port,

>  that do not match any of the filters defined subsequently.

> @@ -117,7 +117,7 @@ a packet using one of  three methods:

>  1. The packet may be assigned a specific class-of-service based on its

> Layer-2

>  (802.1P/902.1Q VLAN tag) priority field. Since the standard field defines

> 8

>  discrete priority levels, the API allows to assign an odp_cos to each of

> these

> -priority levels with the +odp_cos_with_l2_priority()+ function.

> +priority levels with the `odp_cos_with_l2_priority()` function.

>

>  2. Similarly, a class-of-service may be assigned using the Layer-3 (IP

> DiffServ)

>  header field. The application supplies an array of odp_cos values that

> covers

> diff --git a/doc/users-guide/users-guide-pktio.adoc

> b/doc/users-guide/users-guide-pktio.adoc

> index 2dd0b15..9ca91f7 100644

> --- a/doc/users-guide/users-guide-pktio.adoc

> +++ b/doc/users-guide/users-guide-pktio.adoc

> @@ -7,23 +7,23 @@ represent a logical I/O interface that is mapped in an

> implementation-defined

>  manner to an underlying integrated I/O adapter or NIC.

>

>  PktIO objects are manipulated through various state transitions via

> -+odp_pktio_xxx()+ API calls as shown below:

> +`odp_pktio_xxx()` API calls as shown below:

>

>  .ODP PktIO Finite State Machine

>  image::../images/pktio_fsm.svg[align="center"]

>

> -PktIOs begin in the *Unallocated* state. From here a call

> +odp_pktio_open()+

> +PktIOs begin in the *Unallocated* state. From here a call

> `odp_pktio_open()`

>  is used to create an *odp_pktio_t* handle that is used in all subsequent

> calls

>  to manipulate the object. This call puts the PktIO into the *Unconfigured*

>  state. To become operational, a PktIO must first be

>  *configured* for Input, Output, or both Input and Output via the

> -+odp_pktin_queue_config()+ and/or +odp_pktout_queue_config()+ APIs, and

> then

> -*started* via the +odp_pktio_start()+ to make it *Ready*.

> +`odp_pktin_queue_config()` and/or `odp_pktout_queue_config()` APIs, and

> then

> +*started* via the `odp_pktio_start()` to make it *Ready*.

>

> -Following the completion of I/O processing, the +odp_pktio_stop()+ API

> returns

> +Following the completion of I/O processing, the `odp_pktio_stop()` API

> returns

>  the PktIO to the *Configured* state. From here it may be *Reconfigured*

> via

> -additional +odp_pktin_queue_config()+ and/or +odp_pktout_queue_config()+

> calls,

> -or *Closed* via the +odp_pktio_close()+ API to return the PktIO to the

> +additional `odp_pktin_queue_config()` and/or `odp_pktout_queue_config()`

> calls,

> +or *Closed* via the `odp_pktio_close()` API to return the PktIO to the

>  *Unallocated* state.

>

>  === PktIO Allocation

> @@ -87,7 +87,7 @@ PktIO objects begin life by being _opened_ via the call:

>  odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool,

>                             const odp_pktio_param_t *param);

>  -----

> -+odp_pktio_open()+ takes three arguments: a *name*, which is an

> +`odp_pktio_open()` takes three arguments: a *name*, which is an

>  implementation-defined string that identifies the logical interface to be

>  opened, a *pool* that identifies the ODP pool that storage for received

>  packets should be allocated from, and a *param* structure that specifies

> @@ -132,20 +132,20 @@ PktIO objects support four different Input and

> Output modes, that may be

>  specified independently at *open* time.

>

>  .PktIO Input Modes

> -* +ODP_PKTIN_MODE_DIRECT+

> -* +ODP_PKTIN_MODE_QUEUE+

> -* +ODP_OKTIN_MODE_SCHED+

> -* +ODP_PKTIN_MODE_DISABLED+

> +* `ODP_PKTIN_MODE_DIRECT`

> +* `ODP_PKTIN_MODE_QUEUE`

> +* `ODP_OKTIN_MODE_SCHED`

> +* `ODP_PKTIN_MODE_DISABLED`

>

>  .PktIO Output Modes

> -* +ODP_PKTOUT_MODE_DIRECT+

> -* +ODP_PKTOUT_MODE_QUEUE+

> -* +ODP_PKTOUT_MODE_TM+

> -* +ODP_PKTOUT_MODE_DISABLED+

> +* `ODP_PKTOUT_MODE_DIRECT`

> +* `ODP_PKTOUT_MODE_QUEUE`

> +* `ODP_PKTOUT_MODE_TM`

> +* `ODP_PKTOUT_MODE_DISABLED`

>

>  The DISABLED modes indicate that either input or output is prohibited on

> this

> -PktIO. Attempts to receive packets on a PktIO whose +in_mode+ is DISABLED

> -return no packets while packets sent to a PktIO whose +out_mode+ is

> DISABLED

> +PktIO. Attempts to receive packets on a PktIO whose `in_mode` is DISABLED

> +return no packets while packets sent to a PktIO whose `out_mode` is

> DISABLED

>  are discarded.

>

>  ==== Direct I/O Modes

> @@ -163,10 +163,10 @@

> image::../images/pktin_direct_recv.svg[align="center"]

>

>  In DIRECT mode, received packets are stored in one or more special PktIO

> queues

>  of type *odp_pktin_queue_t* and are retrieved by threads calling the

> -+odp_pktin_recv()+ API.

> +`odp_pktin_recv()` API.

>

>  Once opened, setting up a DIRECT mode PktIO is performed by the

> -+odp_pktin_queue_config()+ API.

> +`odp_pktin_queue_config()` API.

>  [source,c]

>  -----

>  /**

> @@ -233,10 +233,10 @@ typedef struct odp_pktin_queue_param_t {

>  } odp_pktin_queue_param_t;

>  -----

>  Note that the *queue_param* field of this struct is ignored in DIRECT

> mode.

> -The purpose of +odp_pktin_queue_config()+ is to specify the number of

> PktIn

> +The purpose of `odp_pktin_queue_config()` is to specify the number of

> PktIn

>  queues to be created and to set their attributes.

>

> -It is important to note that while +odp_pktio_queue_config()+ creates a

> +It is important to note that while `odp_pktio_queue_config()` creates a

>  requested number of RX queues that are associated with the PktIO and

> accepts

>  optimization advice as to how the application intends to use them, _i.e._,

>  whether the queues need to be safe for concurrent use by multiple threads

> @@ -250,8 +250,8 @@ how those tools are used.

>  ===== Hash Processing

>  Another feature of DIRECT mode input is the provision of a *hash*

> function  used

>  to distribute incoming packets among the PktIO's PktIn queues. If the

> -+hash_enable+ field of the *odp_pktin_queue_param_t* is 1,

> -then the +hash_proto+ field is used to specify which field(s) of incoming

> +`hash_enable` field of the *odp_pktin_queue_param_t* is 1,

> +then the `hash_proto` field is used to specify which field(s) of incoming

>  packets should be used as input to an implementation-defined packet

>  distribution hash function.

>  [source,c]

> @@ -298,7 +298,7 @@ same PktIn queue.

>  ===== PktIn Queues

>  A *PktIn Queue* is a special type of queue that is used internally by

> PktIOs

>  operating in DIRECT mode. Applications cannot perform enqueues to these

> queues,

> -however they may obtain references to them via the +odp_pktin_queue()+ API

> +however they may obtain references to them via the `odp_pktin_queue()` API

>  [source,c]

>  -----

>  /**

> @@ -322,7 +322,7 @@ however they may obtain references to them via the

> +odp_pktin_queue()+ API

>  int odp_pktin_queue(odp_pktio_t pktio, odp_pktin_queue_t queues[], int

> num);

>  -----

>  Once configured, prior to receiving packets the PktIO must be placed into

> the

> -*Ready* state via a call to +odp_pktio_start()

> +*Ready* state via a call to `odp_pktio_start()`

>  [source,c]

>  -----

>  /**

> @@ -341,7 +341,7 @@ Once configured, prior to receiving packets the PktIO

> must be placed into the

>  int odp_pktio_start(odp_pktio_t pktio);

>  -----

>  Once started, the PktIn queue handles are used as arguments to

> -+odp_pktin_recv()+ to receive packets from the PktIO.

> +`odp_pktin_recv()` to receive packets from the PktIO.

>  [source,c]

>  -----

>  /**

> @@ -379,7 +379,7 @@ A PktIO operating in DIRECT mode performs TX

> processing as shown here:

>  image::../images/pktout_direct_send.svg[align="center"]

>

>  Direct TX processing operates similarly to Direct RX processing. Following

> -open, the +odp_pktout_queue_config()+ API is used to create and configure

> +open, the `odp_pktout_queue_config()` API is used to create and configure

>  one or more *PktOut queues* to be used to support packet transmission by

>  this PktIO

>  [source,c]

> @@ -410,7 +410,7 @@ this PktIO

>  int odp_pktout_queue_config(odp_pktio_t pktio,

>                             const odp_pktout_queue_param_t *param);

>  -----

> -As with +odp_pktin_queue_config()+, the configuration of PktOut queues

> +As with `odp_pktin_queue_config()`, the configuration of PktOut queues

>  involves the use of a parameter struct:

>  [source,c]

>  -----

> @@ -438,7 +438,7 @@ As with direct input, direct output uses one or more

> special output queues

>  of type *odp_pktout_queue_t* that are created and configured by this call.

>

>  As with PktIn queues, the handles for these created PktOut queues may be

> -retrieved by the +odp_pktout_queue()+ API:

> +retrieved by the `odp_pktout_queue()` API:

>  [source,c]

>  -----

>  /**

> @@ -462,8 +462,8 @@ retrieved by the +odp_pktout_queue()+ API:

>  int odp_pktout_queue(odp_pktio_t pktio, odp_pktout_queue_t queues[], int

> num);

>  -----

>  Once the PktIO has been configured for output and started via

> -+odp_pktio_start()+, packets may be transmitted to the PktIO by calling

> -+odp_pktout_send()+:

> +`odp_pktio_start()`, packets may be transmitted to the PktIO by calling

> +`odp_pktout_send()`:

>  [source,c]

>  -----

>  /**

> @@ -506,18 +506,18 @@ image::../images/pktin_queue_recv.svg[align="center"]

>  In QUEUE mode, received packets are stored in one or more standard ODP

> queues.

>  The difference is that these queues are not created directly by the

>  application. Instead, they are created in response to an

> -+odp_pktin_queue_config()+ call.

> +`odp_pktin_queue_config()` call.

>

> -As with DIRECT mode, the +odp_pktin_queue_param_t+ specified to this call

> +As with DIRECT mode, the `odp_pktin_queue_param_t` specified to this call

>  indicates whether an input hash should be used and if so which field(s) of

>  the packet should be considered as input to the has function.

>

>  The main difference between DIRECT and QUEUE RX processing is that because

>  the PktIO uses standard ODP event queues, other parts of the application

> can

> -use +odp_queue_enq()+ API calls to enqueue packets to these queues for

> +use `odp_queue_enq()` API calls to enqueue packets to these queues for

>  "RX" processing in addition to those originating from the PktIO interface

>  itself. To obtain the handles of these input queues, the

> -+odp_pktin_event_queue()+ API is used:

> +`odp_pktin_event_queue()` API is used:

>  [source,c]

>  -----

>  /**

> @@ -543,7 +543,7 @@ itself. To obtain the handles of these input queues,

> the

>  int odp_pktin_event_queue(odp_pktio_t pktio, odp_queue_t queues[], int

> num);

>  -----

>  Similarly, threads receive packets from PktIOs operating in QUEUE mode by

> -making standard +odp_queue_deq()+ calls to one of the event queues

> associated

> +making standard `odp_queue_deq()` calls to one of the event queues

> associated

>  with the PktIO.

>

>  ===== Queue TX Processing

> @@ -554,9 +554,9 @@ image::../images/pktout_queue_send.svg[align="center]

>

>  For TX processing QUEUE mode behaves similar to DIRECT mode except that

>  output queues are regular ODP event queues that receive packets via

> -+odp_queue_enq()+ calls rather than special PktOut queues that use

> -+odp_pktout_send()+. Again, these queues are created via a call to

> -+odp_pktout_queue_config()+ following +odp_pktio_open()+.

> +`odp_queue_enq()` calls rather than special PktOut queues that use

> +`odp_pktout_send()`. Again, these queues are created via a call to

> +`odp_pktout_queue_config()` following `odp_pktio_open()`.

>

>  The main reason for selecting QUEUE mode for output is flexibility. If an

>  application is designed to use a _pipeline model_ where packets flow

> through

> @@ -573,15 +573,15 @@ Scheduled RX Processing is further divided based on

> whether or not the

>  Classifier is used.

>

>  ===== Scheduled RX Processing

> -When a PktIO is opened with +ODP_PKTIN_MODE_SCHED+, it indicates that the

> -input queues created by a subsequent +odp_pktin_queue_config()+ call are

> to

> +When a PktIO is opened with `ODP_PKTIN_MODE_SCHED`, it indicates that the

> +input queues created by a subsequent `odp_pktin_queue_config()` call are

> to

>  be used as input to the *ODP Scheduler*.

>

>  .PktIO SCHED Mode Receive Processing

>  image::../images/pktin_sched_recv.svg[align="center']

>

>  For basic use, SCHED mode simply associates the PktIO input event queues

> -created by +odp_pktin_queue_config()+ with the scheduler. Hashing may

> still be

> +created by `odp_pktin_queue_config()` with the scheduler. Hashing may

> still be

>  employed to distribute input packets among multiple input queues. However

>  instead of these being plain queues they are scheduled queues and have

>  associated scheduling attributes like priority, scheduler group, and

> @@ -595,12 +595,12 @@ to permit fine-grained flow separation on *Class of

> Service (CoS)* boundaries.

>  .PktIO SCHED Mode Receive Processing with Classification

>  image::../images/pktin_sched_cls.svg[align="center"]

>

> -In this mode of operation, the hash function of

> +odp_pktin_queue_config()+ is

> +In this mode of operation, the hash function of

> `odp_pktin_queue_config()` is

>  typically not used. Instead, the event queues created by this call,

>  as well as any additional event queues created via separate

> -+odp_queue_create()+ calls are associated with classes of service via

> -+odp_cls_cos_create()+ calls. Classification is enabled for the PktIO as a

> -whole by assigning a _default_ CoS via the +odp_pktio_default_cos_set()+

> +`odp_queue_create()` calls are associated with classes of service via

> +`odp_cls_cos_create()` calls. Classification is enabled for the PktIO as a

> +whole by assigning a _default_ CoS via the `odp_pktio_default_cos_set()`

>  API.

>

>  When operating in SCHED mode, applications do not call PktIn receive

> functions.

> @@ -615,9 +615,9 @@ process.

>

>  ===== Scheduled TX Processing

>  Scheduled transmit processing is performed via the *ODP Traffic Manager*

> and

> -is requested when a PktIO is opened with an +out_mode+ of

> +ODP_PKTOUT_MODE_TM+.

> +is requested when a PktIO is opened with an `out_mode` of

> `ODP_PKTOUT_MODE_TM`.

>

> -For TX processing via the Traffic Manager, applications use the

> +odp_tm_enq()+

> +For TX processing via the Traffic Manager, applications use the

> `odp_tm_enq()`

>  API:

>  [source,c]

>  -----

> diff --git a/doc/users-guide/users-guide-tm.adoc

> b/doc/users-guide/users-guide-tm.adoc

> index 132fdc1..b2dbbf1 100644

> --- a/doc/users-guide/users-guide-tm.adoc

> +++ b/doc/users-guide/users-guide-tm.adoc

> @@ -256,7 +256,7 @@ common to re-use the same set of parameter set over

> and over again, and also to

>  be able to change the parameter set once and have it affect lots of

> entities

>  with which it is associated with/applied to.

>

> -==== Absolute Limits versus  +odp_tm_capability_t+

> +==== Absolute Limits versus  `odp_tm_capability_t`

>

>  This header file defines some constants representing the absolute maximum

>  settings for any TM system, though in most cases a TM system can (and

> should)

> diff --git a/doc/users-guide/users-guide.adoc

> b/doc/users-guide/users-guide.adoc

> index a2e5058..bc4b777 100644

> --- a/doc/users-guide/users-guide.adoc

> +++ b/doc/users-guide/users-guide.adoc

> @@ -36,8 +36,8 @@ embodiment that they permit innovation in how these

> functions can

>  be realized on various platforms that offer implementations of ODP. To

> achieve

>  this goal, ODP APIs are described using abstract data types whose

> definition

>  is left up to the ODP implementer.  For example, in ODP packets are

> referenced

> -by abstract handles of type +odp_packet_t+, and packet-related APIs take

> -arguments of this type. What an +odp_packet_t+ actually is is not part of

> the

> +by abstract handles of type `odp_packet_t`, and packet-related APIs take

> +arguments of this type. What an `odp_packet_t` actually is is not part of

> the

>  ODP API specification--that is the responsibility of each ODP

> implementation.

>

>  .Summary: ODP API attributes:

> @@ -207,7 +207,7 @@ organized into a collection of threads that perform

> the work that the

>  application is designed to do. ODP threads may or may not share memory

> with

>  other threads--that is up to the implementation. Threads come in two

> "flavors":

>  control and worker, that are represented by the abstract type

> -+odp_thread_type_t+.

> +`odp_thread_type_t`.

>

>  A control thread is a supervisory thread that organizes

>  the operation of worker threads. Worker threads, by contrast, exist to

> @@ -232,7 +232,7 @@ changes in various components of interest to the

> application. Events have an

>  event type that describes what it represents. Threads can create new

> events

>  or consume events processed by them, or they can perform some processing

> on

>  an event and then pass it along to another component for further

> processing.

> -References to events are via handles of abstract type +odp_event_t+. Cast

> +References to events are via handles of abstract type `odp_event_t`. Cast

>  functions are provided to convert these into specific handles of the

>  appropriate type represented by the event.

>

> @@ -246,7 +246,7 @@ have an associated context, which represents a

> persistent state for all

>  events that make use of it. These states are what permit threads to

> perform

>  stateful processing on events as well as stateless processing.

>

> -Queues are represented by handles of abstract type +odp_queue_t+.

> +Queues are represented by handles of abstract type `odp_queue_t`.

>

>  === Pool

>  A pool is a shared memory area from which elements may be drawn. Pools

> @@ -258,14 +258,14 @@ use may be shared between the two. Pools have an

> associated type that

>  characterizes the elements that they contain. The two most important pool

> types

>  are Buffer and Packet.

>

> -Pools are represented by handles of abstract type +odp_pool_t+.

> +Pools are represented by handles of abstract type `odp_pool_t`.

>

>  === Shared Memory

>  Shared memory represents raw blocks of storage that are sharable between

>  threads. They are the building blocks of pools but can be used directly by

>  ODP applications if desired.

>

> -Shared memory is represented by handles of abstract type +odp_shm_t+.

> +Shared memory is represented by handles of abstract type `odp_shm_t`.

>

>  === Buffer

>  A buffer is a fixed sized block of shared storage that is used by ODP

> @@ -283,12 +283,12 @@ no setter is provided to manipulate it.  When object

> have multiple metadata

>  items, each has its own associated getter and/or setter access function to

>  inspect or manipulate it.

>

> -Buffers are represented by handles of abstract type +odp_buffer_t+.

> +Buffers are represented by handles of abstract type `odp_buffer_t`.

>

>  === Packet

>  Packets are received and transmitted via I/O interfaces and represent

>  the basic data that data plane applications manipulate.

> -Packets are drawn from pools of type +ODP_POOL_PACKET+.

> +Packets are drawn from pools of type `ODP_POOL_PACKET`.

>  Unlike  buffers, which are simple objects,

>  ODP packets have a rich set of semantics that permit their inspection

>  and manipulation in complex ways to be described later. Packets also

> support

> @@ -296,7 +296,7 @@ a rich set of metadata as well as user metadata. User

> metadata permits

>  applications to associate an application-determined amount of side

> information

>  with each packet for its own use.

>

> -Packets are represented by handles of abstract type +odp_packet_t+.

> +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

> @@ -304,7 +304,7 @@ 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.

>

> -PktIOs are represented by handles of abstract type +odp_pktio_t+.

> +PktIOs are represented by handles of abstract type `odp_pktio_t`.

>

>  === Time

>  The time API is used to measure time intervals and track time flow of an

> @@ -316,29 +316,29 @@ The local time API is designed to be used within one

> thread and can be faster

>  than the global time API. The local time API cannot be used between

> threads as

>  time consistency is not guaranteed, and in some cases that's enough.

>  So, local time stamps are local to the calling thread and must not be

> shared

> -with other threads. Current local time can be read with

> +odp_time_local()+.

> +with other threads. Current local time can be read with

> `odp_time_local()`.

>

>  ==== Global time

>  The global time API is designed to be used for tracking time between

> threads.

>  So, global time stamps can be shared between threads. Current global time

> can

> -be read with +odp_time_global()+.

> +be read with `odp_time_global()`.

>

>  Both, local and global time is not wrapped during the application life

> cycle.

> -The time API includes functions to operate with time, such as

> +odp_time_diff()+,

> -+odp_time_sum()+, +odp_time_cmp()+, conversion functions like

> -+odp_time_to_ns()+, +odp_time_local_from_ns()+,

> +odp_time_global_from_ns()+.

> -To get rate of time source +odp_time_local_res()+, +odp_time_global_res()+

> -are used. To wait, +odp_time_wait_ns()+ and +odp_time_wait_until()+ are

> used,

> +The time API includes functions to operate with time, such as

> `odp_time_diff()`,

> +`odp_time_sum()`, `odp_time_cmp()`, conversion functions like

> +`odp_time_to_ns()`, `odp_time_local_from_ns()`,

> `odp_time_global_from_ns()`.

> +To get rate of time source `odp_time_local_res()`, `odp_time_global_res()`

> +are used. To wait, `odp_time_wait_ns()` and `odp_time_wait_until()` are

> used,

>  during witch a thread potentially busy loop the entire wait time.

>

> -The +odp_time_t+ opaque type represents local or global timestamps.

> +The `odp_time_t` opaque type represents local or global timestamps.

>

>  === Timer

>  Timers are how ODP applications measure and respond to the passage of

> time.

>  Timers are drawn from specialized pools called timer pools that have their

> -own abstract type (+odp_timer_pool_t+). Applications may have many timers

> +own abstract type (`odp_timer_pool_t`). Applications may have many timers

>  active at the same time and can set them to use either relative or

> absolute

> -time. When timers expire they create events of type +odp_timeout_t+, which

> +time. When timers expire they create events of type `odp_timeout_t`, which

>  serve as notifications of timer expiration.

>

>  === Synchronizer

> @@ -403,7 +403,7 @@ image::odp_scheduling.svg[align="center"]

>  The Scheduler is responsible for selecting and dispatching one or more

> events

>  to a requesting thread. Event selection is based on several factors

> involving

>  both the queues containing schedulable events and the thread making an

> -+odp_schedule()+ or +odp_schedule_multi()+ call.

> +`odp_schedule()` or `odp_schedule_multi()` call.

>

>  ODP queues have a _scheduling priority_ that determines how urgently

> events

>  on them should be processed relative to events contained in other queues.

> @@ -468,7 +468,7 @@ Applications only include the 'include/odp_api.h'

> file, which includes the

>  definition of the API on that platform. The doxygen documentation defining

>  the behavior of the ODP API is all contained in the public API files, and

> the

>  actual definitions for an implementation will be found in the per platform

> -directories. Per-platform data that might normally be a +#define+ can be

> +directories. Per-platform data that might normally be a `#define` can be

>  recovered via the appropriate access function if the #define is not

> directly

>  visible to the application.

>

> @@ -493,9 +493,9 @@ sure it has closed the ingress and subsequently

> drained all queues, etc.

>

>  === Startup

>  The first API that must be called by an ODP application is

> 'odp_init_global()'.

> -This takes two pointers. The first, +odp_init_t+, contains ODP

> initialization

> +This takes two pointers. The first, `odp_init_t`, contains ODP

> initialization

>  data that is platform independent and portable, while the second,

> -+odp_platform_init_t+, is passed unparsed to the implementation

> +`odp_platform_init_t`, is passed unparsed to the implementation

>  to be used for platform specific data that is not yet, or may never be

>  suitable for the ODP API.

>

> @@ -505,7 +505,7 @@ once per application. Following global initialization,

> each thread in turn

>  calls 'odp_init_local()'. This establishes the local ODP thread

>  context for that thread and MUST be called before other ODP APIs may be

>  called by that thread. The sole argument to this call is the _thread

> type_,

> -which is either +ODP_THREAD_WORKER+ or +ODP_THREAD_CONTROL+.

> +which is either `ODP_THREAD_WORKER` or `ODP_THREAD_CONTROL`.

>

>  === Shutdown

>  Shutdown is the logical reverse of the initialization procedure, with

> @@ -522,16 +522,16 @@ conventions.

>

>  === Handles and Special Designators

>  ODP resources are represented via _handles_ that have abstract type

> -_odp_resource_t_.  So pools are represented by handles of type

> +odp_pool_t+,

> -queues by handles of type +odp_queue_t+, etc. Each such type

> +_odp_resource_t_.  So pools are represented by handles of type

> `odp_pool_t`,

> +queues by handles of type `odp_queue_t`, etc. Each such type

>  has a distinguished type _ODP_RESOURCE_INVALID_ that is used to indicate a

>  handle that does not refer to a valid resource of that type. Resources are

>  typically created via an API named _odp_resource_create()_ that returns a

>  handle of type _odp_resource_t_ that represents the created object. This

>  returned handle is set to _ODP_RESOURCE_INVALID_ if, for example, the

>  resource could not be created due to resource exhaustion. Invalid

> resources

> -do not necessarily represent error conditions. For example,

> +ODP_EVENT_INVALID+

> -in response to an +odp_queue_deq()+ call to get an event from a queue

> simply

> +do not necessarily represent error conditions. For example,

> `ODP_EVENT_INVALID`

> +in response to an `odp_queue_deq()` call to get an event from a queue

> simply

>  indicates that the queue is empty.

>

>  === Addressing Scope

> @@ -550,9 +550,9 @@ resource.

>

>  == Shared memory

>  === Allocating shared memory

> -Blocks of shared memory can be created using the +odp_shm_reserve()+ API

> +Blocks of shared memory can be created using the `odp_shm_reserve()` API

>  call. The call expects a shared memory block name, a block size, an

> alignment

> -requirement, and optional flags as parameters. It returns a +odp_shm_t+

> +requirement, and optional flags as parameters. It returns a `odp_shm_t`

>  handle. The size and alignment requirement are given in bytes.

>

>  .creating a block of shared memory

> @@ -583,32 +583,32 @@ shared_data_t *shared_data;

>  shared_data = odp_shm_addr(shm);

>  ----

>

> -The address returned by +odp_shm_addr()+ is valid only in the calling ODP

> +The address returned by `odp_shm_addr()` is valid only in the calling ODP

>  thread space: odp_shm_t handles can be shared between ODP threads and

> remain

> -valid within any threads, whereas the address returned by

> +odp_shm_addr(shm)+

> +valid within any threads, whereas the address returned by

> `odp_shm_addr(shm)`

>  may differ from ODP threads to ODP threads (for the same 'shm' block), and

>  should therefore not be shared between ODP threads.

>  For instance, it would be correct to send a shm handle using IPC between

> two

> -ODP threads and let each of these thread do their own +odp_shm_addr()+ to

> +ODP threads and let each of these thread do their own `odp_shm_addr()` to

>  get the block address. Directly sending the address returned by

> -+odp_shm_addr()+ from one ODP thread to another would however possibly

> fail

> +`odp_shm_addr()` from one ODP thread to another would however possibly

> fail

>  (the address may have no sense in the receiver address space).

>

> -The address returned by +odp_shm_addr()+ is nevertheless guaranteed to be

> +The address returned by `odp_shm_addr()` is nevertheless guaranteed to be

>  aligned according to the alignment requirements provided at block creation

> -time, even if the call to +odp_shm_addr()+ is performed by a different ODP

> -thread than the one which originally called +odp_shm_reserve()+.

> +time, even if the call to `odp_shm_addr()` is performed by a different ODP

> +thread than the one which originally called `odp_shm_reserve()`.

>

>  All shared memory blocks are contiguous in any ODP thread addressing

> space:

>  'address' to 'address'\+'size' (where 'size' is the shared memory block

> size,

> -as provided in the +odp_shm_reserve()+ call) is read and writeable and

> +as provided in the `odp_shm_reserve()` call) is read and writeable and

>  mapping the shared memory block. There is no fragmentation.

>

>  === Memory behaviour

>  By default ODP threads are assumed to behave as cache coherent systems:

>  Any change performed on a shared memory block is guaranteed to eventually

>  become visible to other ODP threads sharing this memory block.

> -(this behaviour may be altered by flags to +odp_shm_reserve()+ in the

> future).

> +(this behaviour may be altered by flags to `odp_shm_reserve()` in the

> future).

>  Nevertheless, there is no implicit memory barrier associated with any

> action

>  on shared memories: *When* a change performed by an ODP thread becomes

> visible

>  to another ODP thread is not known: An application using shared memory

> @@ -619,10 +619,10 @@ validity between ODP threads.

>  As mentioned, shared memory handles can be sent from ODP threads to ODP

>  threads using any IPC mechanism, and then the block address retrieved.

>  A simpler approach to get the shared memory block handle of an already

> created

> -block is to use the +odp_shm_lookup()+ API function call.

> +block is to use the `odp_shm_lookup()` API function call.

>  This nevertheless requires the calling ODP thread to provide the name of

> the

>  shared memory block:

> -+odp_shm_lookup()+ will return +ODP_SHM_INVALID+ if no shared memory block

> +`odp_shm_lookup()` will return `ODP_SHM_INVALID` if no shared memory block

>  with the provided name is known by ODP.

>

>  .retrieving a block handle and address from another ODP task

> @@ -641,11 +641,11 @@ if (shm != ODP_SHM_INVALID) {

>  ----

>

>  === Freeing memory

> -Freeing shared memory is performed using the +odp_shm_free()+ API call.

> -+odp_shm_free()+ takes one single argument, the shared memory block

> handle.

> -Any ODP thread is allowed to perform a +odp_shm_free()+ on a shared memory

> -block (i.e. the thread performing the +odp_shm_free()+ may be different

> -from the thread which did the +odp_shm_reserve()+). Shared memory blocks

> should

> +Freeing shared memory is performed using the `odp_shm_free()` API call.

> +`odp_shm_free()` takes one single argument, the shared memory block

> handle.

> +Any ODP thread is allowed to perform a `odp_shm_free()` on a shared memory

> +block (i.e. the thread performing the `odp_shm_free()` may be different

> +from the thread which did the `odp_shm_reserve()`). Shared memory blocks

> should

>  be freed only once, and once freed, a shared memory block should no longer

>  be referenced by any ODP threads.

>

> @@ -674,7 +674,7 @@ This flag tells ODP that the shared memory will be

> used by the ODP application

>  software only: no HW (such as DMA, or other accelerator) will ever

>  try to access the memory. No other ODP call will be involved on this

> memory

>  (as ODP calls could implicitly involve HW, depending on the ODP

> -implementation), except for +odp_shm_lookup()+ and +odp_shm_free()+.

> +implementation), except for `odp_shm_lookup()` and `odp_shm_free()`.

>  ODP implementations may use this flag as a hint for performance

> optimization,

>  or may as well ignore this flag.

>

> @@ -682,7 +682,7 @@ or may as well ignore this flag.

>  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

> -+odp_queue_t+ that is used to refer to this queue in all subsequent APIs

> that

> +`odp_queue_t` that is used to refer to this queue in all subsequent APIs

> that

>  reference it. Queues have one of two ODP-defined _types_, POLL, and SCHED

> that

>  determine how they are used. POLL queues directly managed by the ODP

>  application while SCHED queues make use of the *ODP scheduler* to provide

> @@ -741,16 +741,16 @@ priority SCHED queue that the caller is eligible to

> receive events from.

>  This latter consideration is determined by the queues _scheduler group_,

> which

>  is set at queue create time, and by the caller's _scheduler group mask_

> that

>  indicates which scheduler group(s) it belongs to. Scheduler groups are

> -represented by handles of type +odp_scheduler_group_t+ and are created by

> +represented by handles of type `odp_scheduler_group_t` and are created by

>  the *odp_scheduler_group_create()* API. A number of scheduler groups are

> -_predefined_ by ODP.  These include +ODP_SCHED_GROUP_ALL+ (all threads),

> -+ODP_SCHED_GROUP_WORKER+ (all worker threads), and

> +ODP_SCHED_GROUP_CONTROL+

> +_predefined_ by ODP.  These include `ODP_SCHED_GROUP_ALL` (all threads),

> +`ODP_SCHED_GROUP_WORKER` (all worker threads), and

> `ODP_SCHED_GROUP_CONTROL`

>  (all control threads). The application is free to create additional

> scheduler

>  groups for its own purpose and threads can join or leave scheduler groups

>  using the *odp_scheduler_group_join()* and *odp_scheduler_group_leave()*

> APIs

>

>  === Scheduler Priority

> -The +prio+ field of the +odp_queue_param_t+ specifies the queue's

> scheduling

> +The `prio` field of the `odp_queue_param_t` specifies the queue's

> scheduling

>  priority, which is how queues within eligible scheduler groups are

> selected

>  for dispatch. Queues have a default scheduling priority of NORMAL but can

> be

>  set to HIGHEST or LOWEST according to application needs.

> @@ -889,7 +889,7 @@ void worker_thread()

>

>  This represents a simplified structure for a typical worker thread

> operating

>  on ordered queues. Multiple events are processed in parallel and the use

> of

> -ordered queues ensures that they will be placed on +dest_q+ in the same

> order

> +ordered queues ensures that they will be placed on `dest_q` in the same

> order

>  as they originated.  While processing in parallel, the use of ordered

> locks

>  enables critical sections to be processed in order within the overall

> parallel

>  flow. When a thread arrives at the *odp_schedule_order_lock()* call, it

> waits

> @@ -914,7 +914,7 @@ Packet objects are normally created at ingress when

> they arrive at a source

>  *odp_pktio_t* and are received by an application either directly or (more

>  typically) for a scheduled receive queue. They MAY be implicitly freed

> when

>  they are transmitted to an output *odp_pktio_t* via an associated transmit

> -queue, or freed directly via the +odp_packet_free()+ API.

> +queue, or freed directly via the `odp_packet_free()` API.

>

>  Occasionally an application may originate a packet itself, either _de

> novo_ or

>  by deriving it from an existing packet, and APIs are provided to assist in

> @@ -947,9 +947,9 @@ to manipulate its structure.

>  To support packet manipulation, predefined _headroom_ and _tailroom_

>  areas are logically associated with a packet. Packets can be adjusted by

>  _pulling_ and _pushing_ these areas. Typical packet processing might

> consist

> -of stripping headers from a packet via +odp_pull_head()+ calls as part of

> +of stripping headers from a packet via `odp_pull_head()` calls as part of

>  receive processing and then replacing them with new headers via

> -+odp_push_head()+ calls as the packet is being prepared for transmit.

> +`odp_push_head()` calls as the packet is being prepared for transmit.

>

>  === Packet Segments and Addressing

>  ODP platforms use various methods and techniques to store and process

> packets

> @@ -993,7 +993,7 @@ additional segments may be part of the packet and

> contain the remaining packet

>  payload and tailroom. The application need not concern itself with

> segments

>  except that when the application requires addressability to a packet it

>  understands that addressability is provided on a per-segment basis. So,

> for

> -example, if the application makes a call like +odp_packet_l4_ptr()+ to

> obtain

> +example, if the application makes a call like `odp_packet_l4_ptr()` to

> obtain

>  addressability to the packet's Layer 4 header, the returned length from

> that

>  call is the number of bytes from the start of the Layer 4 header that are

>  contiguously addressable to the application from the returned pointer

> address.

> @@ -1016,10 +1016,10 @@ changes in the packet contents and/or structure as

> part of its processing of

>  the packet. While changing this metadata may effect some ODP APIs,

> changing

>  metadata is designed to _document_ application changes to the packet but

>  does not in itself _cause_ those changes to be made. For example, if an

> -application changes the Layer 3 offset by using the

> +odp_packet_l3_offset_set()+

> -API, the subsequent calls to +odp_packet_l3_ptr()+ will return an address

> +application changes the Layer 3 offset by using the

> `odp_packet_l3_offset_set()`

> +API, the subsequent calls to `odp_packet_l3_ptr()` will return an address

>  starting from that changed offset, changing an attribute like

> -+odp_packet_has_udp_set()+ will not, by itself, turn a non-UDP packet into

> +`odp_packet_has_udp_set()` will not, by itself, turn a non-UDP packet into

>  a valid UDP packet. Applications are expected to exercise appropriate care

>  when changing packet metadata to ensure that the resulting metadata

> changes

>  reflect the actual changed packet structure that the application has made.

> --

> 2.5.0

>

> _______________________________________________

> lng-odp mailing list

> lng-odp@lists.linaro.org

> https://lists.linaro.org/mailman/listinfo/lng-odp

>




-- 
Mike Holmes
Technical Manager - Linaro Networking Group
Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs
"Work should be fun and collaborative, the rest follows"

merged

On 5 May 2016 at 12:15, Mike Holmes <mike.holmes@linaro.org> wrote:

>

>

> On 3 May 2016 at 15:28, Bill Fischofer <bill.fischofer@linaro.org> wrote:

>

>> In asciidoc monospace characters may be indicated by enclosure

>> in either backticks or plus signs, however asciidoctor requires

>> the use of backticks to indicate monospace. Change all uses of

>> plus signs to backticks so that user guide docs can format

>> properly using either asciidoc or asciidoctor. Going forward

>> only backticks should be used to indicate monospace font.

>>

>> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>

>>

>

> Reviewed-by: Mike Holmes <mike.holmes@linaro.org>

>

>

>> ---

>>  doc/glossary.adoc                      |  10 +--

>>  doc/users-guide/users-guide-cls.adoc   |   4 +-

>>  doc/users-guide/users-guide-pktio.adoc |  98 +++++++++++++-------------

>>  doc/users-guide/users-guide-tm.adoc    |   2 +-

>>  doc/users-guide/users-guide.adoc       | 124

>> ++++++++++++++++-----------------

>>  5 files changed, 119 insertions(+), 119 deletions(-)

>>

>> diff --git a/doc/glossary.adoc b/doc/glossary.adoc

>> index 3106e19..2c0de24 100644

>> --- a/doc/glossary.adoc

>> +++ b/doc/glossary.adoc

>> @@ -10,7 +10,7 @@ control thread::

>>      operating system house keeping tasks but will be scheduled by it and

>> may

>>      receive interrupts.

>>  ODP instantiation process::

>> -    The process calling +odp_init_global()+, which is probably the

>> +    The process calling `odp_init_global()`, which is probably the

>>      first process which is started when an ODP application is started.

>>      There is one single such process per ODP instantiation.

>>  thread::

>> @@ -19,13 +19,13 @@ thread::

>>  ODP thread::

>>      An ODP thread is a flow of execution that belongs to ODP:

>>      Any "flow of execution" (i.e. OS process or OS thread) calling

>> -    +odp_init_global()+, or +odp_init_local()+ becomes an ODP thread.

>> +    `odp_init_global()`, or `odp_init_local()` becomes an ODP thread.

>>      This definition currently limits the number of ODP instances on a

>> given

>> -    machine to one. In the future +odp_init_global()+ will return

>> something

>> -    like an ODP instance reference and +odp_init_local()+ will take such

>> +    machine to one. In the future `odp_init_global()` will return

>> something

>> +    like an ODP instance reference and `odp_init_local()` will take such

>>      a reference in parameter, allowing threads to join any running ODP

>> instance.

>>      Note that, in a Linux environment an ODP thread can be either a Linux

>> -    process or a linux thread (i.e. a linux process calling

>> +odp_init_local()+

>> +    process or a linux thread (i.e. a linux process calling

>> `odp_init_local()`

>>      will be referred as ODP thread, not ODP process).

>>  event::

>>      An event is a notification that can be placed in a queue.

>> diff --git a/doc/users-guide/users-guide-cls.adoc

>> b/doc/users-guide/users-guide-cls.adoc

>> index d306c1c..d2ba743 100644

>> --- a/doc/users-guide/users-guide-cls.adoc

>> +++ b/doc/users-guide/users-guide-cls.adoc

>> @@ -99,7 +99,7 @@ to be processed.

>>

>>  === Default packet handling

>>

>> -There is a +odp_cos_t+ assigned to each port with the

>> +There is a `odp_cos_t` assigned to each port with the

>>  odp_pktio_default_cos_set() function, which will function as the default

>>  class-of-service for all packets received from an ingress port,

>>  that do not match any of the filters defined subsequently.

>> @@ -117,7 +117,7 @@ a packet using one of  three methods:

>>  1. The packet may be assigned a specific class-of-service based on its

>> Layer-2

>>  (802.1P/902.1Q VLAN tag) priority field. Since the standard field

>> defines 8

>>  discrete priority levels, the API allows to assign an odp_cos to each of

>> these

>> -priority levels with the +odp_cos_with_l2_priority()+ function.

>> +priority levels with the `odp_cos_with_l2_priority()` function.

>>

>>  2. Similarly, a class-of-service may be assigned using the Layer-3 (IP

>> DiffServ)

>>  header field. The application supplies an array of odp_cos values that

>> covers

>> diff --git a/doc/users-guide/users-guide-pktio.adoc

>> b/doc/users-guide/users-guide-pktio.adoc

>> index 2dd0b15..9ca91f7 100644

>> --- a/doc/users-guide/users-guide-pktio.adoc

>> +++ b/doc/users-guide/users-guide-pktio.adoc

>> @@ -7,23 +7,23 @@ represent a logical I/O interface that is mapped in an

>> implementation-defined

>>  manner to an underlying integrated I/O adapter or NIC.

>>

>>  PktIO objects are manipulated through various state transitions via

>> -+odp_pktio_xxx()+ API calls as shown below:

>> +`odp_pktio_xxx()` API calls as shown below:

>>

>>  .ODP PktIO Finite State Machine

>>  image::../images/pktio_fsm.svg[align="center"]

>>

>> -PktIOs begin in the *Unallocated* state. From here a call

>> +odp_pktio_open()+

>> +PktIOs begin in the *Unallocated* state. From here a call

>> `odp_pktio_open()`

>>  is used to create an *odp_pktio_t* handle that is used in all subsequent

>> calls

>>  to manipulate the object. This call puts the PktIO into the

>> *Unconfigured*

>>  state. To become operational, a PktIO must first be

>>  *configured* for Input, Output, or both Input and Output via the

>> -+odp_pktin_queue_config()+ and/or +odp_pktout_queue_config()+ APIs, and

>> then

>> -*started* via the +odp_pktio_start()+ to make it *Ready*.

>> +`odp_pktin_queue_config()` and/or `odp_pktout_queue_config()` APIs, and

>> then

>> +*started* via the `odp_pktio_start()` to make it *Ready*.

>>

>> -Following the completion of I/O processing, the +odp_pktio_stop()+ API

>> returns

>> +Following the completion of I/O processing, the `odp_pktio_stop()` API

>> returns

>>  the PktIO to the *Configured* state. From here it may be *Reconfigured*

>> via

>> -additional +odp_pktin_queue_config()+ and/or +odp_pktout_queue_config()+

>> calls,

>> -or *Closed* via the +odp_pktio_close()+ API to return the PktIO to the

>> +additional `odp_pktin_queue_config()` and/or `odp_pktout_queue_config()`

>> calls,

>> +or *Closed* via the `odp_pktio_close()` API to return the PktIO to the

>>  *Unallocated* state.

>>

>>  === PktIO Allocation

>> @@ -87,7 +87,7 @@ PktIO objects begin life by being _opened_ via the call:

>>  odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool,

>>                             const odp_pktio_param_t *param);

>>  -----

>> -+odp_pktio_open()+ takes three arguments: a *name*, which is an

>> +`odp_pktio_open()` takes three arguments: a *name*, which is an

>>  implementation-defined string that identifies the logical interface to be

>>  opened, a *pool* that identifies the ODP pool that storage for received

>>  packets should be allocated from, and a *param* structure that specifies

>> @@ -132,20 +132,20 @@ PktIO objects support four different Input and

>> Output modes, that may be

>>  specified independently at *open* time.

>>

>>  .PktIO Input Modes

>> -* +ODP_PKTIN_MODE_DIRECT+

>> -* +ODP_PKTIN_MODE_QUEUE+

>> -* +ODP_OKTIN_MODE_SCHED+

>> -* +ODP_PKTIN_MODE_DISABLED+

>> +* `ODP_PKTIN_MODE_DIRECT`

>> +* `ODP_PKTIN_MODE_QUEUE`

>> +* `ODP_OKTIN_MODE_SCHED`

>> +* `ODP_PKTIN_MODE_DISABLED`

>>

>>  .PktIO Output Modes

>> -* +ODP_PKTOUT_MODE_DIRECT+

>> -* +ODP_PKTOUT_MODE_QUEUE+

>> -* +ODP_PKTOUT_MODE_TM+

>> -* +ODP_PKTOUT_MODE_DISABLED+

>> +* `ODP_PKTOUT_MODE_DIRECT`

>> +* `ODP_PKTOUT_MODE_QUEUE`

>> +* `ODP_PKTOUT_MODE_TM`

>> +* `ODP_PKTOUT_MODE_DISABLED`

>>

>>  The DISABLED modes indicate that either input or output is prohibited on

>> this

>> -PktIO. Attempts to receive packets on a PktIO whose +in_mode+ is DISABLED

>> -return no packets while packets sent to a PktIO whose +out_mode+ is

>> DISABLED

>> +PktIO. Attempts to receive packets on a PktIO whose `in_mode` is DISABLED

>> +return no packets while packets sent to a PktIO whose `out_mode` is

>> DISABLED

>>  are discarded.

>>

>>  ==== Direct I/O Modes

>> @@ -163,10 +163,10 @@

>> image::../images/pktin_direct_recv.svg[align="center"]

>>

>>  In DIRECT mode, received packets are stored in one or more special PktIO

>> queues

>>  of type *odp_pktin_queue_t* and are retrieved by threads calling the

>> -+odp_pktin_recv()+ API.

>> +`odp_pktin_recv()` API.

>>

>>  Once opened, setting up a DIRECT mode PktIO is performed by the

>> -+odp_pktin_queue_config()+ API.

>> +`odp_pktin_queue_config()` API.

>>  [source,c]

>>  -----

>>  /**

>> @@ -233,10 +233,10 @@ typedef struct odp_pktin_queue_param_t {

>>  } odp_pktin_queue_param_t;

>>  -----

>>  Note that the *queue_param* field of this struct is ignored in DIRECT

>> mode.

>> -The purpose of +odp_pktin_queue_config()+ is to specify the number of

>> PktIn

>> +The purpose of `odp_pktin_queue_config()` is to specify the number of

>> PktIn

>>  queues to be created and to set their attributes.

>>

>> -It is important to note that while +odp_pktio_queue_config()+ creates a

>> +It is important to note that while `odp_pktio_queue_config()` creates a

>>  requested number of RX queues that are associated with the PktIO and

>> accepts

>>  optimization advice as to how the application intends to use them,

>> _i.e._,

>>  whether the queues need to be safe for concurrent use by multiple threads

>> @@ -250,8 +250,8 @@ how those tools are used.

>>  ===== Hash Processing

>>  Another feature of DIRECT mode input is the provision of a *hash*

>> function  used

>>  to distribute incoming packets among the PktIO's PktIn queues. If the

>> -+hash_enable+ field of the *odp_pktin_queue_param_t* is 1,

>> -then the +hash_proto+ field is used to specify which field(s) of incoming

>> +`hash_enable` field of the *odp_pktin_queue_param_t* is 1,

>> +then the `hash_proto` field is used to specify which field(s) of incoming

>>  packets should be used as input to an implementation-defined packet

>>  distribution hash function.

>>  [source,c]

>> @@ -298,7 +298,7 @@ same PktIn queue.

>>  ===== PktIn Queues

>>  A *PktIn Queue* is a special type of queue that is used internally by

>> PktIOs

>>  operating in DIRECT mode. Applications cannot perform enqueues to these

>> queues,

>> -however they may obtain references to them via the +odp_pktin_queue()+

>> API

>> +however they may obtain references to them via the `odp_pktin_queue()`

>> API

>>  [source,c]

>>  -----

>>  /**

>> @@ -322,7 +322,7 @@ however they may obtain references to them via the

>> +odp_pktin_queue()+ API

>>  int odp_pktin_queue(odp_pktio_t pktio, odp_pktin_queue_t queues[], int

>> num);

>>  -----

>>  Once configured, prior to receiving packets the PktIO must be placed

>> into the

>> -*Ready* state via a call to +odp_pktio_start()

>> +*Ready* state via a call to `odp_pktio_start()`

>>  [source,c]

>>  -----

>>  /**

>> @@ -341,7 +341,7 @@ Once configured, prior to receiving packets the PktIO

>> must be placed into the

>>  int odp_pktio_start(odp_pktio_t pktio);

>>  -----

>>  Once started, the PktIn queue handles are used as arguments to

>> -+odp_pktin_recv()+ to receive packets from the PktIO.

>> +`odp_pktin_recv()` to receive packets from the PktIO.

>>  [source,c]

>>  -----

>>  /**

>> @@ -379,7 +379,7 @@ A PktIO operating in DIRECT mode performs TX

>> processing as shown here:

>>  image::../images/pktout_direct_send.svg[align="center"]

>>

>>  Direct TX processing operates similarly to Direct RX processing.

>> Following

>> -open, the +odp_pktout_queue_config()+ API is used to create and configure

>> +open, the `odp_pktout_queue_config()` API is used to create and configure

>>  one or more *PktOut queues* to be used to support packet transmission by

>>  this PktIO

>>  [source,c]

>> @@ -410,7 +410,7 @@ this PktIO

>>  int odp_pktout_queue_config(odp_pktio_t pktio,

>>                             const odp_pktout_queue_param_t *param);

>>  -----

>> -As with +odp_pktin_queue_config()+, the configuration of PktOut queues

>> +As with `odp_pktin_queue_config()`, the configuration of PktOut queues

>>  involves the use of a parameter struct:

>>  [source,c]

>>  -----

>> @@ -438,7 +438,7 @@ As with direct input, direct output uses one or more

>> special output queues

>>  of type *odp_pktout_queue_t* that are created and configured by this

>> call.

>>

>>  As with PktIn queues, the handles for these created PktOut queues may be

>> -retrieved by the +odp_pktout_queue()+ API:

>> +retrieved by the `odp_pktout_queue()` API:

>>  [source,c]

>>  -----

>>  /**

>> @@ -462,8 +462,8 @@ retrieved by the +odp_pktout_queue()+ API:

>>  int odp_pktout_queue(odp_pktio_t pktio, odp_pktout_queue_t queues[], int

>> num);

>>  -----

>>  Once the PktIO has been configured for output and started via

>> -+odp_pktio_start()+, packets may be transmitted to the PktIO by calling

>> -+odp_pktout_send()+:

>> +`odp_pktio_start()`, packets may be transmitted to the PktIO by calling

>> +`odp_pktout_send()`:

>>  [source,c]

>>  -----

>>  /**

>> @@ -506,18 +506,18 @@

>> image::../images/pktin_queue_recv.svg[align="center"]

>>  In QUEUE mode, received packets are stored in one or more standard ODP

>> queues.

>>  The difference is that these queues are not created directly by the

>>  application. Instead, they are created in response to an

>> -+odp_pktin_queue_config()+ call.

>> +`odp_pktin_queue_config()` call.

>>

>> -As with DIRECT mode, the +odp_pktin_queue_param_t+ specified to this call

>> +As with DIRECT mode, the `odp_pktin_queue_param_t` specified to this call

>>  indicates whether an input hash should be used and if so which field(s)

>> of

>>  the packet should be considered as input to the has function.

>>

>>  The main difference between DIRECT and QUEUE RX processing is that

>> because

>>  the PktIO uses standard ODP event queues, other parts of the application

>> can

>> -use +odp_queue_enq()+ API calls to enqueue packets to these queues for

>> +use `odp_queue_enq()` API calls to enqueue packets to these queues for

>>  "RX" processing in addition to those originating from the PktIO interface

>>  itself. To obtain the handles of these input queues, the

>> -+odp_pktin_event_queue()+ API is used:

>> +`odp_pktin_event_queue()` API is used:

>>  [source,c]

>>  -----

>>  /**

>> @@ -543,7 +543,7 @@ itself. To obtain the handles of these input queues,

>> the

>>  int odp_pktin_event_queue(odp_pktio_t pktio, odp_queue_t queues[], int

>> num);

>>  -----

>>  Similarly, threads receive packets from PktIOs operating in QUEUE mode by

>> -making standard +odp_queue_deq()+ calls to one of the event queues

>> associated

>> +making standard `odp_queue_deq()` calls to one of the event queues

>> associated

>>  with the PktIO.

>>

>>  ===== Queue TX Processing

>> @@ -554,9 +554,9 @@ image::../images/pktout_queue_send.svg[align="center]

>>

>>  For TX processing QUEUE mode behaves similar to DIRECT mode except that

>>  output queues are regular ODP event queues that receive packets via

>> -+odp_queue_enq()+ calls rather than special PktOut queues that use

>> -+odp_pktout_send()+. Again, these queues are created via a call to

>> -+odp_pktout_queue_config()+ following +odp_pktio_open()+.

>> +`odp_queue_enq()` calls rather than special PktOut queues that use

>> +`odp_pktout_send()`. Again, these queues are created via a call to

>> +`odp_pktout_queue_config()` following `odp_pktio_open()`.

>>

>>  The main reason for selecting QUEUE mode for output is flexibility. If an

>>  application is designed to use a _pipeline model_ where packets flow

>> through

>> @@ -573,15 +573,15 @@ Scheduled RX Processing is further divided based on

>> whether or not the

>>  Classifier is used.

>>

>>  ===== Scheduled RX Processing

>> -When a PktIO is opened with +ODP_PKTIN_MODE_SCHED+, it indicates that the

>> -input queues created by a subsequent +odp_pktin_queue_config()+ call are

>> to

>> +When a PktIO is opened with `ODP_PKTIN_MODE_SCHED`, it indicates that the

>> +input queues created by a subsequent `odp_pktin_queue_config()` call are

>> to

>>  be used as input to the *ODP Scheduler*.

>>

>>  .PktIO SCHED Mode Receive Processing

>>  image::../images/pktin_sched_recv.svg[align="center']

>>

>>  For basic use, SCHED mode simply associates the PktIO input event queues

>> -created by +odp_pktin_queue_config()+ with the scheduler. Hashing may

>> still be

>> +created by `odp_pktin_queue_config()` with the scheduler. Hashing may

>> still be

>>  employed to distribute input packets among multiple input queues. However

>>  instead of these being plain queues they are scheduled queues and have

>>  associated scheduling attributes like priority, scheduler group, and

>> @@ -595,12 +595,12 @@ to permit fine-grained flow separation on *Class of

>> Service (CoS)* boundaries.

>>  .PktIO SCHED Mode Receive Processing with Classification

>>  image::../images/pktin_sched_cls.svg[align="center"]

>>

>> -In this mode of operation, the hash function of

>> +odp_pktin_queue_config()+ is

>> +In this mode of operation, the hash function of

>> `odp_pktin_queue_config()` is

>>  typically not used. Instead, the event queues created by this call,

>>  as well as any additional event queues created via separate

>> -+odp_queue_create()+ calls are associated with classes of service via

>> -+odp_cls_cos_create()+ calls. Classification is enabled for the PktIO as

>> a

>> -whole by assigning a _default_ CoS via the +odp_pktio_default_cos_set()+

>> +`odp_queue_create()` calls are associated with classes of service via

>> +`odp_cls_cos_create()` calls. Classification is enabled for the PktIO as

>> a

>> +whole by assigning a _default_ CoS via the `odp_pktio_default_cos_set()`

>>  API.

>>

>>  When operating in SCHED mode, applications do not call PktIn receive

>> functions.

>> @@ -615,9 +615,9 @@ process.

>>

>>  ===== Scheduled TX Processing

>>  Scheduled transmit processing is performed via the *ODP Traffic Manager*

>> and

>> -is requested when a PktIO is opened with an +out_mode+ of

>> +ODP_PKTOUT_MODE_TM+.

>> +is requested when a PktIO is opened with an `out_mode` of

>> `ODP_PKTOUT_MODE_TM`.

>>

>> -For TX processing via the Traffic Manager, applications use the

>> +odp_tm_enq()+

>> +For TX processing via the Traffic Manager, applications use the

>> `odp_tm_enq()`

>>  API:

>>  [source,c]

>>  -----

>> diff --git a/doc/users-guide/users-guide-tm.adoc

>> b/doc/users-guide/users-guide-tm.adoc

>> index 132fdc1..b2dbbf1 100644

>> --- a/doc/users-guide/users-guide-tm.adoc

>> +++ b/doc/users-guide/users-guide-tm.adoc

>> @@ -256,7 +256,7 @@ common to re-use the same set of parameter set over

>> and over again, and also to

>>  be able to change the parameter set once and have it affect lots of

>> entities

>>  with which it is associated with/applied to.

>>

>> -==== Absolute Limits versus  +odp_tm_capability_t+

>> +==== Absolute Limits versus  `odp_tm_capability_t`

>>

>>  This header file defines some constants representing the absolute maximum

>>  settings for any TM system, though in most cases a TM system can (and

>> should)

>> diff --git a/doc/users-guide/users-guide.adoc

>> b/doc/users-guide/users-guide.adoc

>> index a2e5058..bc4b777 100644

>> --- a/doc/users-guide/users-guide.adoc

>> +++ b/doc/users-guide/users-guide.adoc

>> @@ -36,8 +36,8 @@ embodiment that they permit innovation in how these

>> functions can

>>  be realized on various platforms that offer implementations of ODP. To

>> achieve

>>  this goal, ODP APIs are described using abstract data types whose

>> definition

>>  is left up to the ODP implementer.  For example, in ODP packets are

>> referenced

>> -by abstract handles of type +odp_packet_t+, and packet-related APIs take

>> -arguments of this type. What an +odp_packet_t+ actually is is not part

>> of the

>> +by abstract handles of type `odp_packet_t`, and packet-related APIs take

>> +arguments of this type. What an `odp_packet_t` actually is is not part

>> of the

>>  ODP API specification--that is the responsibility of each ODP

>> implementation.

>>

>>  .Summary: ODP API attributes:

>> @@ -207,7 +207,7 @@ organized into a collection of threads that perform

>> the work that the

>>  application is designed to do. ODP threads may or may not share memory

>> with

>>  other threads--that is up to the implementation. Threads come in two

>> "flavors":

>>  control and worker, that are represented by the abstract type

>> -+odp_thread_type_t+.

>> +`odp_thread_type_t`.

>>

>>  A control thread is a supervisory thread that organizes

>>  the operation of worker threads. Worker threads, by contrast, exist to

>> @@ -232,7 +232,7 @@ changes in various components of interest to the

>> application. Events have an

>>  event type that describes what it represents. Threads can create new

>> events

>>  or consume events processed by them, or they can perform some processing

>> on

>>  an event and then pass it along to another component for further

>> processing.

>> -References to events are via handles of abstract type +odp_event_t+. Cast

>> +References to events are via handles of abstract type `odp_event_t`. Cast

>>  functions are provided to convert these into specific handles of the

>>  appropriate type represented by the event.

>>

>> @@ -246,7 +246,7 @@ have an associated context, which represents a

>> persistent state for all

>>  events that make use of it. These states are what permit threads to

>> perform

>>  stateful processing on events as well as stateless processing.

>>

>> -Queues are represented by handles of abstract type +odp_queue_t+.

>> +Queues are represented by handles of abstract type `odp_queue_t`.

>>

>>  === Pool

>>  A pool is a shared memory area from which elements may be drawn. Pools

>> @@ -258,14 +258,14 @@ use may be shared between the two. Pools have an

>> associated type that

>>  characterizes the elements that they contain. The two most important

>> pool types

>>  are Buffer and Packet.

>>

>> -Pools are represented by handles of abstract type +odp_pool_t+.

>> +Pools are represented by handles of abstract type `odp_pool_t`.

>>

>>  === Shared Memory

>>  Shared memory represents raw blocks of storage that are sharable between

>>  threads. They are the building blocks of pools but can be used directly

>> by

>>  ODP applications if desired.

>>

>> -Shared memory is represented by handles of abstract type +odp_shm_t+.

>> +Shared memory is represented by handles of abstract type `odp_shm_t`.

>>

>>  === Buffer

>>  A buffer is a fixed sized block of shared storage that is used by ODP

>> @@ -283,12 +283,12 @@ no setter is provided to manipulate it.  When

>> object have multiple metadata

>>  items, each has its own associated getter and/or setter access function

>> to

>>  inspect or manipulate it.

>>

>> -Buffers are represented by handles of abstract type +odp_buffer_t+.

>> +Buffers are represented by handles of abstract type `odp_buffer_t`.

>>

>>  === Packet

>>  Packets are received and transmitted via I/O interfaces and represent

>>  the basic data that data plane applications manipulate.

>> -Packets are drawn from pools of type +ODP_POOL_PACKET+.

>> +Packets are drawn from pools of type `ODP_POOL_PACKET`.

>>  Unlike  buffers, which are simple objects,

>>  ODP packets have a rich set of semantics that permit their inspection

>>  and manipulation in complex ways to be described later. Packets also

>> support

>> @@ -296,7 +296,7 @@ a rich set of metadata as well as user metadata. User

>> metadata permits

>>  applications to associate an application-determined amount of side

>> information

>>  with each packet for its own use.

>>

>> -Packets are represented by handles of abstract type +odp_packet_t+.

>> +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

>> @@ -304,7 +304,7 @@ 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.

>>

>> -PktIOs are represented by handles of abstract type +odp_pktio_t+.

>> +PktIOs are represented by handles of abstract type `odp_pktio_t`.

>>

>>  === Time

>>  The time API is used to measure time intervals and track time flow of an

>> @@ -316,29 +316,29 @@ The local time API is designed to be used within

>> one thread and can be faster

>>  than the global time API. The local time API cannot be used between

>> threads as

>>  time consistency is not guaranteed, and in some cases that's enough.

>>  So, local time stamps are local to the calling thread and must not be

>> shared

>> -with other threads. Current local time can be read with

>> +odp_time_local()+.

>> +with other threads. Current local time can be read with

>> `odp_time_local()`.

>>

>>  ==== Global time

>>  The global time API is designed to be used for tracking time between

>> threads.

>>  So, global time stamps can be shared between threads. Current global

>> time can

>> -be read with +odp_time_global()+.

>> +be read with `odp_time_global()`.

>>

>>  Both, local and global time is not wrapped during the application life

>> cycle.

>> -The time API includes functions to operate with time, such as

>> +odp_time_diff()+,

>> -+odp_time_sum()+, +odp_time_cmp()+, conversion functions like

>> -+odp_time_to_ns()+, +odp_time_local_from_ns()+,

>> +odp_time_global_from_ns()+.

>> -To get rate of time source +odp_time_local_res()+,

>> +odp_time_global_res()+

>> -are used. To wait, +odp_time_wait_ns()+ and +odp_time_wait_until()+ are

>> used,

>> +The time API includes functions to operate with time, such as

>> `odp_time_diff()`,

>> +`odp_time_sum()`, `odp_time_cmp()`, conversion functions like

>> +`odp_time_to_ns()`, `odp_time_local_from_ns()`,

>> `odp_time_global_from_ns()`.

>> +To get rate of time source `odp_time_local_res()`,

>> `odp_time_global_res()`

>> +are used. To wait, `odp_time_wait_ns()` and `odp_time_wait_until()` are

>> used,

>>  during witch a thread potentially busy loop the entire wait time.

>>

>> -The +odp_time_t+ opaque type represents local or global timestamps.

>> +The `odp_time_t` opaque type represents local or global timestamps.

>>

>>  === Timer

>>  Timers are how ODP applications measure and respond to the passage of

>> time.

>>  Timers are drawn from specialized pools called timer pools that have

>> their

>> -own abstract type (+odp_timer_pool_t+). Applications may have many timers

>> +own abstract type (`odp_timer_pool_t`). Applications may have many timers

>>  active at the same time and can set them to use either relative or

>> absolute

>> -time. When timers expire they create events of type +odp_timeout_t+,

>> which

>> +time. When timers expire they create events of type `odp_timeout_t`,

>> which

>>  serve as notifications of timer expiration.

>>

>>  === Synchronizer

>> @@ -403,7 +403,7 @@ image::odp_scheduling.svg[align="center"]

>>  The Scheduler is responsible for selecting and dispatching one or more

>> events

>>  to a requesting thread. Event selection is based on several factors

>> involving

>>  both the queues containing schedulable events and the thread making an

>> -+odp_schedule()+ or +odp_schedule_multi()+ call.

>> +`odp_schedule()` or `odp_schedule_multi()` call.

>>

>>  ODP queues have a _scheduling priority_ that determines how urgently

>> events

>>  on them should be processed relative to events contained in other queues.

>> @@ -468,7 +468,7 @@ Applications only include the 'include/odp_api.h'

>> file, which includes the

>>  definition of the API on that platform. The doxygen documentation

>> defining

>>  the behavior of the ODP API is all contained in the public API files,

>> and the

>>  actual definitions for an implementation will be found in the per

>> platform

>> -directories. Per-platform data that might normally be a +#define+ can be

>> +directories. Per-platform data that might normally be a `#define` can be

>>  recovered via the appropriate access function if the #define is not

>> directly

>>  visible to the application.

>>

>> @@ -493,9 +493,9 @@ sure it has closed the ingress and subsequently

>> drained all queues, etc.

>>

>>  === Startup

>>  The first API that must be called by an ODP application is

>> 'odp_init_global()'.

>> -This takes two pointers. The first, +odp_init_t+, contains ODP

>> initialization

>> +This takes two pointers. The first, `odp_init_t`, contains ODP

>> initialization

>>  data that is platform independent and portable, while the second,

>> -+odp_platform_init_t+, is passed unparsed to the implementation

>> +`odp_platform_init_t`, is passed unparsed to the implementation

>>  to be used for platform specific data that is not yet, or may never be

>>  suitable for the ODP API.

>>

>> @@ -505,7 +505,7 @@ once per application. Following global

>> initialization, each thread in turn

>>  calls 'odp_init_local()'. This establishes the local ODP thread

>>  context for that thread and MUST be called before other ODP APIs may be

>>  called by that thread. The sole argument to this call is the _thread

>> type_,

>> -which is either +ODP_THREAD_WORKER+ or +ODP_THREAD_CONTROL+.

>> +which is either `ODP_THREAD_WORKER` or `ODP_THREAD_CONTROL`.

>>

>>  === Shutdown

>>  Shutdown is the logical reverse of the initialization procedure, with

>> @@ -522,16 +522,16 @@ conventions.

>>

>>  === Handles and Special Designators

>>  ODP resources are represented via _handles_ that have abstract type

>> -_odp_resource_t_.  So pools are represented by handles of type

>> +odp_pool_t+,

>> -queues by handles of type +odp_queue_t+, etc. Each such type

>> +_odp_resource_t_.  So pools are represented by handles of type

>> `odp_pool_t`,

>> +queues by handles of type `odp_queue_t`, etc. Each such type

>>  has a distinguished type _ODP_RESOURCE_INVALID_ that is used to indicate

>> a

>>  handle that does not refer to a valid resource of that type. Resources

>> are

>>  typically created via an API named _odp_resource_create()_ that returns a

>>  handle of type _odp_resource_t_ that represents the created object. This

>>  returned handle is set to _ODP_RESOURCE_INVALID_ if, for example, the

>>  resource could not be created due to resource exhaustion. Invalid

>> resources

>> -do not necessarily represent error conditions. For example,

>> +ODP_EVENT_INVALID+

>> -in response to an +odp_queue_deq()+ call to get an event from a queue

>> simply

>> +do not necessarily represent error conditions. For example,

>> `ODP_EVENT_INVALID`

>> +in response to an `odp_queue_deq()` call to get an event from a queue

>> simply

>>  indicates that the queue is empty.

>>

>>  === Addressing Scope

>> @@ -550,9 +550,9 @@ resource.

>>

>>  == Shared memory

>>  === Allocating shared memory

>> -Blocks of shared memory can be created using the +odp_shm_reserve()+ API

>> +Blocks of shared memory can be created using the `odp_shm_reserve()` API

>>  call. The call expects a shared memory block name, a block size, an

>> alignment

>> -requirement, and optional flags as parameters. It returns a +odp_shm_t+

>> +requirement, and optional flags as parameters. It returns a `odp_shm_t`

>>  handle. The size and alignment requirement are given in bytes.

>>

>>  .creating a block of shared memory

>> @@ -583,32 +583,32 @@ shared_data_t *shared_data;

>>  shared_data = odp_shm_addr(shm);

>>  ----

>>

>> -The address returned by +odp_shm_addr()+ is valid only in the calling ODP

>> +The address returned by `odp_shm_addr()` is valid only in the calling ODP

>>  thread space: odp_shm_t handles can be shared between ODP threads and

>> remain

>> -valid within any threads, whereas the address returned by

>> +odp_shm_addr(shm)+

>> +valid within any threads, whereas the address returned by

>> `odp_shm_addr(shm)`

>>  may differ from ODP threads to ODP threads (for the same 'shm' block),

>> and

>>  should therefore not be shared between ODP threads.

>>  For instance, it would be correct to send a shm handle using IPC between

>> two

>> -ODP threads and let each of these thread do their own +odp_shm_addr()+ to

>> +ODP threads and let each of these thread do their own `odp_shm_addr()` to

>>  get the block address. Directly sending the address returned by

>> -+odp_shm_addr()+ from one ODP thread to another would however possibly

>> fail

>> +`odp_shm_addr()` from one ODP thread to another would however possibly

>> fail

>>  (the address may have no sense in the receiver address space).

>>

>> -The address returned by +odp_shm_addr()+ is nevertheless guaranteed to be

>> +The address returned by `odp_shm_addr()` is nevertheless guaranteed to be

>>  aligned according to the alignment requirements provided at block

>> creation

>> -time, even if the call to +odp_shm_addr()+ is performed by a different

>> ODP

>> -thread than the one which originally called +odp_shm_reserve()+.

>> +time, even if the call to `odp_shm_addr()` is performed by a different

>> ODP

>> +thread than the one which originally called `odp_shm_reserve()`.

>>

>>  All shared memory blocks are contiguous in any ODP thread addressing

>> space:

>>  'address' to 'address'\+'size' (where 'size' is the shared memory block

>> size,

>> -as provided in the +odp_shm_reserve()+ call) is read and writeable and

>> +as provided in the `odp_shm_reserve()` call) is read and writeable and

>>  mapping the shared memory block. There is no fragmentation.

>>

>>  === Memory behaviour

>>  By default ODP threads are assumed to behave as cache coherent systems:

>>  Any change performed on a shared memory block is guaranteed to eventually

>>  become visible to other ODP threads sharing this memory block.

>> -(this behaviour may be altered by flags to +odp_shm_reserve()+ in the

>> future).

>> +(this behaviour may be altered by flags to `odp_shm_reserve()` in the

>> future).

>>  Nevertheless, there is no implicit memory barrier associated with any

>> action

>>  on shared memories: *When* a change performed by an ODP thread becomes

>> visible

>>  to another ODP thread is not known: An application using shared memory

>> @@ -619,10 +619,10 @@ validity between ODP threads.

>>  As mentioned, shared memory handles can be sent from ODP threads to ODP

>>  threads using any IPC mechanism, and then the block address retrieved.

>>  A simpler approach to get the shared memory block handle of an already

>> created

>> -block is to use the +odp_shm_lookup()+ API function call.

>> +block is to use the `odp_shm_lookup()` API function call.

>>  This nevertheless requires the calling ODP thread to provide the name of

>> the

>>  shared memory block:

>> -+odp_shm_lookup()+ will return +ODP_SHM_INVALID+ if no shared memory

>> block

>> +`odp_shm_lookup()` will return `ODP_SHM_INVALID` if no shared memory

>> block

>>  with the provided name is known by ODP.

>>

>>  .retrieving a block handle and address from another ODP task

>> @@ -641,11 +641,11 @@ if (shm != ODP_SHM_INVALID) {

>>  ----

>>

>>  === Freeing memory

>> -Freeing shared memory is performed using the +odp_shm_free()+ API call.

>> -+odp_shm_free()+ takes one single argument, the shared memory block

>> handle.

>> -Any ODP thread is allowed to perform a +odp_shm_free()+ on a shared

>> memory

>> -block (i.e. the thread performing the +odp_shm_free()+ may be different

>> -from the thread which did the +odp_shm_reserve()+). Shared memory blocks

>> should

>> +Freeing shared memory is performed using the `odp_shm_free()` API call.

>> +`odp_shm_free()` takes one single argument, the shared memory block

>> handle.

>> +Any ODP thread is allowed to perform a `odp_shm_free()` on a shared

>> memory

>> +block (i.e. the thread performing the `odp_shm_free()` may be different

>> +from the thread which did the `odp_shm_reserve()`). Shared memory blocks

>> should

>>  be freed only once, and once freed, a shared memory block should no

>> longer

>>  be referenced by any ODP threads.

>>

>> @@ -674,7 +674,7 @@ This flag tells ODP that the shared memory will be

>> used by the ODP application

>>  software only: no HW (such as DMA, or other accelerator) will ever

>>  try to access the memory. No other ODP call will be involved on this

>> memory

>>  (as ODP calls could implicitly involve HW, depending on the ODP

>> -implementation), except for +odp_shm_lookup()+ and +odp_shm_free()+.

>> +implementation), except for `odp_shm_lookup()` and `odp_shm_free()`.

>>  ODP implementations may use this flag as a hint for performance

>> optimization,

>>  or may as well ignore this flag.

>>

>> @@ -682,7 +682,7 @@ or may as well ignore this flag.

>>  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

>> -+odp_queue_t+ that is used to refer to this queue in all subsequent APIs

>> that

>> +`odp_queue_t` that is used to refer to this queue in all subsequent APIs

>> that

>>  reference it. Queues have one of two ODP-defined _types_, POLL, and

>> SCHED that

>>  determine how they are used. POLL queues directly managed by the ODP

>>  application while SCHED queues make use of the *ODP scheduler* to provide

>> @@ -741,16 +741,16 @@ priority SCHED queue that the caller is eligible to

>> receive events from.

>>  This latter consideration is determined by the queues _scheduler group_,

>> which

>>  is set at queue create time, and by the caller's _scheduler group mask_

>> that

>>  indicates which scheduler group(s) it belongs to. Scheduler groups are

>> -represented by handles of type +odp_scheduler_group_t+ and are created by

>> +represented by handles of type `odp_scheduler_group_t` and are created by

>>  the *odp_scheduler_group_create()* API. A number of scheduler groups are

>> -_predefined_ by ODP.  These include +ODP_SCHED_GROUP_ALL+ (all threads),

>> -+ODP_SCHED_GROUP_WORKER+ (all worker threads), and

>> +ODP_SCHED_GROUP_CONTROL+

>> +_predefined_ by ODP.  These include `ODP_SCHED_GROUP_ALL` (all threads),

>> +`ODP_SCHED_GROUP_WORKER` (all worker threads), and

>> `ODP_SCHED_GROUP_CONTROL`

>>  (all control threads). The application is free to create additional

>> scheduler

>>  groups for its own purpose and threads can join or leave scheduler groups

>>  using the *odp_scheduler_group_join()* and *odp_scheduler_group_leave()*

>> APIs

>>

>>  === Scheduler Priority

>> -The +prio+ field of the +odp_queue_param_t+ specifies the queue's

>> scheduling

>> +The `prio` field of the `odp_queue_param_t` specifies the queue's

>> scheduling

>>  priority, which is how queues within eligible scheduler groups are

>> selected

>>  for dispatch. Queues have a default scheduling priority of NORMAL but

>> can be

>>  set to HIGHEST or LOWEST according to application needs.

>> @@ -889,7 +889,7 @@ void worker_thread()

>>

>>  This represents a simplified structure for a typical worker thread

>> operating

>>  on ordered queues. Multiple events are processed in parallel and the use

>> of

>> -ordered queues ensures that they will be placed on +dest_q+ in the same

>> order

>> +ordered queues ensures that they will be placed on `dest_q` in the same

>> order

>>  as they originated.  While processing in parallel, the use of ordered

>> locks

>>  enables critical sections to be processed in order within the overall

>> parallel

>>  flow. When a thread arrives at the *odp_schedule_order_lock()* call, it

>> waits

>> @@ -914,7 +914,7 @@ Packet objects are normally created at ingress when

>> they arrive at a source

>>  *odp_pktio_t* and are received by an application either directly or (more

>>  typically) for a scheduled receive queue. They MAY be implicitly freed

>> when

>>  they are transmitted to an output *odp_pktio_t* via an associated

>> transmit

>> -queue, or freed directly via the +odp_packet_free()+ API.

>> +queue, or freed directly via the `odp_packet_free()` API.

>>

>>  Occasionally an application may originate a packet itself, either _de

>> novo_ or

>>  by deriving it from an existing packet, and APIs are provided to assist

>> in

>> @@ -947,9 +947,9 @@ to manipulate its structure.

>>  To support packet manipulation, predefined _headroom_ and _tailroom_

>>  areas are logically associated with a packet. Packets can be adjusted by

>>  _pulling_ and _pushing_ these areas. Typical packet processing might

>> consist

>> -of stripping headers from a packet via +odp_pull_head()+ calls as part of

>> +of stripping headers from a packet via `odp_pull_head()` calls as part of

>>  receive processing and then replacing them with new headers via

>> -+odp_push_head()+ calls as the packet is being prepared for transmit.

>> +`odp_push_head()` calls as the packet is being prepared for transmit.

>>

>>  === Packet Segments and Addressing

>>  ODP platforms use various methods and techniques to store and process

>> packets

>> @@ -993,7 +993,7 @@ additional segments may be part of the packet and

>> contain the remaining packet

>>  payload and tailroom. The application need not concern itself with

>> segments

>>  except that when the application requires addressability to a packet it

>>  understands that addressability is provided on a per-segment basis. So,

>> for

>> -example, if the application makes a call like +odp_packet_l4_ptr()+ to

>> obtain

>> +example, if the application makes a call like `odp_packet_l4_ptr()` to

>> obtain

>>  addressability to the packet's Layer 4 header, the returned length from

>> that

>>  call is the number of bytes from the start of the Layer 4 header that are

>>  contiguously addressable to the application from the returned pointer

>> address.

>> @@ -1016,10 +1016,10 @@ changes in the packet contents and/or structure

>> as part of its processing of

>>  the packet. While changing this metadata may effect some ODP APIs,

>> changing

>>  metadata is designed to _document_ application changes to the packet but

>>  does not in itself _cause_ those changes to be made. For example, if an

>> -application changes the Layer 3 offset by using the

>> +odp_packet_l3_offset_set()+

>> -API, the subsequent calls to +odp_packet_l3_ptr()+ will return an address

>> +application changes the Layer 3 offset by using the

>> `odp_packet_l3_offset_set()`

>> +API, the subsequent calls to `odp_packet_l3_ptr()` will return an address

>>  starting from that changed offset, changing an attribute like

>> -+odp_packet_has_udp_set()+ will not, by itself, turn a non-UDP packet

>> into

>> +`odp_packet_has_udp_set()` will not, by itself, turn a non-UDP packet

>> into

>>  a valid UDP packet. Applications are expected to exercise appropriate

>> care

>>  when changing packet metadata to ensure that the resulting metadata

>> changes

>>  reflect the actual changed packet structure that the application has

>> made.

>> --

>> 2.5.0

>>

>> _______________________________________________

>> lng-odp mailing list

>> lng-odp@lists.linaro.org

>> https://lists.linaro.org/mailman/listinfo/lng-odp

>>

>

>

>

> --

> Mike Holmes

> Technical Manager - Linaro Networking Group

> Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs

> "Work should be fun and collaborative, the rest follows"

>

>

>



-- 
Mike Holmes
Technical Manager - Linaro Networking Group
Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs
"Work should be fun and collaborative, the rest follows"