On 19 May 2016 at 06:05, Bill Fischofer <bill.fischo...@linaro.org> wrote:
> 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. This is saying that all ODP threads of a given ODP instance are descendant of the ODP instantiation process. I already tried to define ODP threads this way, but it was rejected, and the ODP instance number was added to the API so that any thread/process could join any ODP instance. I still get the feeling that, despite this add-on, we are still saying that a odpthread belongs to the ODP instance it is a descendand of, rather than the one specified in the "instance" parameter passed at odp_local_init() time... The only possible usage of the odp_instance parameter passed at odp_local_init() time would then be on OSes which do not support process hierarchy... Is any such OS known to suport ODP? If not, I thing the odp_instance number should either be suppressed, or clearly stated as meaningless on OS which have process hierarchy, as the process hierarchy seems to take precedence over this parameter in all our discussions. I will post a patch on the glossary just stating that, see if we can at least all agree on that little thing... 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 > *ODP* threads are assumed to be Posix-style threads... This is for monarch only, right? +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. > Confused: are talking monarch or some later version? BTW is monarch the name of the API version only or does the "monarch" name also include the linux-generic platform example? > + > +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) > "any ODP resource": That includes everything, e.g. atomics, barrier, timers... as well...right...? +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. > well... yes... But the interesting point is really not mentioned: Either we say: *ALL* odp objects *have to* be created between opd_init_global() and any odp thread creation. That is clear but very restrictive (it would includes everything: for instance, all atomics would have to be known in advance. same for timers or barriers... while it is maybe clear for pools, it is maybe harder to enforce this for these small objects). But at least the definition would be clear... or we say SOME odp objects *have to* be created between opd_init_global() and any odp thread creation, in which case, we have to come with a clear list of which ones we talk about and a precise description of how objects which are not on that list behave, especially when created after fork. This description could of course refer to the OS behavior, but should clearly state what this OS rule applies to (e.g. a how buffer or packet alloc performed after fork() behaves -I guess it depends on when the pool was allocated...). Saying that "most" ODP objects "would possibly" be defined at init time does not really tell much... + > +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 > > Thank you for trying, Bill. We need to succeed. I'll keep trying with you. A french writter, Boileau, wrote " Ce qui se conçoit bien, s'énonce clairement". I know you speak some french... I guess this guy would laugh at us right now :-) Christophe _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp > _______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org https://lists.linaro.org/mailman/listinfo/lng-odp
