On 3 May 2016 at 15:28, Bill Fischofer <[email protected]> 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 <[email protected]> > Reviewed-by: Mike Holmes <[email protected]> > --- > 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 > [email protected] > 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"
_______________________________________________ lng-odp mailing list [email protected] https://lists.linaro.org/mailman/listinfo/lng-odp
