Expand thread section to explain rationale for threads not being ODP objects and how this relates to addressability considerations for shared resources.
Signed-off-by: Bill Fischofer <bill.fischo...@linaro.org> --- doc/users-guide/users-guide.adoc | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 745b85f..fbe745f 100755 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -288,6 +288,17 @@ _thread mask_ and _scheduler group_ that determine where they can run and the type of work that they can handle. These will be discussed in greater detail later. +It is important to note that threads are not ODP objects. This is intentional. +The ODP API is designed to abstract objects and functions that are relevant to +data plane programming, and that may find accelerated implementation across +diverse platforms and architectures. It is not, however, designed to abstract +operating system objects and concepts. As a result while ODP _refers_ to +threads, it does not _define_ threads in terms of their creation or management +from an operating system perspective. ODP does provide _helper_ functions that +permit Posix threads to be created and managed, however. Applications are free +to use these helpers or to manage threads in some other manner of their +choosing. + === Event Events are what threads process to perform their work. Events can represent new work, such as the arrival of a packet that needs to be processed, or they @@ -332,6 +343,9 @@ ODP applications if desired. Shared memory is represented by handles of abstract type `odp_shm_t`. +Note that addressability of shared memory is subject to operating system +considerations as described in <<Addressing Scope>>. + === Buffer A buffer is a fixed sized block of shared storage that is used by ODP components and/or applications to realize their function. Buffers contain @@ -587,10 +601,28 @@ in response to an `odp_queue_deq()` call to get an event from a queue simply indicates that the queue is empty. === Addressing Scope -Unless specifically noted in the API, all ODP resources are global to the ODP -application, whether it runs as a single process or multiple processes. ODP -handles therefore have common meaning within an ODP application but have no -meaning outside the scope of the application. +ODP objects and their associated handles are intended to be global to an ODP +instance, _i.e.,_ to the thread that calls `odp_init_global()` and its +descendants. However, because ODP does not impose a threading model, +responsibility for achieving this is shared with both the ODP implementation as +well as the ODP application. In the odp-linux reference implementation, for +example, threads are assumed to be Posix-style threads that all share a single +address space. As a result, all ODP handles and any addresses derived from +them, are globally sharable throughout the ODP instance. Other implementations +may offer the same capabilities or may use a process-based threading model in +which individual threads execute in distinct address spaces. + +If a platform uses process that follow a Unix-style `fork()` model of process +creation, then for best portability ODP applications should be designed so +that any ODP resource creation (_e.g.,_ pools, shared memory objects, pktios) +are created during initialization by the thread that creates the ODP instance +by calling `odp_init_global()` _before_ any other threads are +created/launched. This will allow any common objects to be visible in forked +processes. + +If a platform uses some other process addressing model, then refer to that +platform for recommendations to achieve application-desired shared +addressability. === Resources and Names Many ODP resource objects, such as pools and queues, support an -- 2.7.4 _______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org https://lists.linaro.org/mailman/listinfo/lng-odp
