On 19 May 2016 at 03:30, Christophe Milard <christophe.mil...@linaro.org> wrote:
> 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 :-) > What is conceived well is expressed clearly ? > > 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 > -- 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 lng-odp@lists.linaro.org https://lists.linaro.org/mailman/listinfo/lng-odp
