| Message ID | 1463662129-21078-1-git-send-email-christophe.milard@linaro.org |
|---|---|
| State | New |
| Headers | show |
On Thu, May 19, 2016 at 7:48 AM, Christophe Milard < christophe.milard@linaro.org> wrote: > Making clear which ODP instance a thread is joining > when calling odp_init_local(). > > Signed-off-by: Christophe Milard <christophe.milard@linaro.org> > --- > doc/glossary.adoc | 24 +++++++++++++++++------- > include/odp/api/spec/init.h | 4 ++++ > 2 files changed, 21 insertions(+), 7 deletions(-) > > diff --git a/doc/glossary.adoc b/doc/glossary.adoc > index 2c0de24..209a292 100644 > --- a/doc/glossary.adoc > +++ b/doc/glossary.adoc > @@ -10,7 +10,8 @@ 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 OS "flow of execution" (i.e. OS process or OS thread) > + 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,12 +20,21 @@ 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. > - 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 > - 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 > + `odp_init_local()` becomes an ODP thread. > + On OSes supporting process hierarchy (e.g. linux), any "flow of > execution" > + calling `odp_init_local()` becomes an ODP thread of the ODP instance > whose > + ODP instantiation process is an ancestor of (or same as) this > + "flow of execution". > + This means that on these OSes, all ODP threads are descendant of (or > + same as) their ODP instantiation process. > + This also means that on these OSes, the ODP instance passed as > + `odp_init_local()` parameter is redundant, as the ODP instance the > thread > + belongs to is actually already defined by the process hierarchy. > I don't think we need to be making this point both because it is unnecessary and also because it may not be accurate. Even today this parameter is used for call validation (pass a bogus value into odp_init_local() and the call will fail, regardless of where you are in the process hierarchy). Since it is opaque, tomorrow, or in other implementations, it may also have other uses known only to the implementation. > + This parameter is only meaningful on OSes which do not support process > + hierarchy. The instance number should nevertheless be set to the > correct > + value (matching the ancestor ODP instance on OS supporting process > + hierarchy). > Again, this is unneeded and potentially inaccurate. > + Note that, e.g. 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()` > will be referred as ODP thread, not ODP process). > event:: > diff --git a/include/odp/api/spec/init.h b/include/odp/api/spec/init.h > index fec6774..7592669 100644 > --- a/include/odp/api/spec/init.h > +++ b/include/odp/api/spec/init.h > @@ -234,6 +234,10 @@ int odp_term_global(odp_instance_t instance); > * All threads must call this function before calling any other ODP API > * functions. The instance parameter specifies which ODP instance the > thread > * joins. A thread may be simultaneously part of single ODP instance only. > + * On OSes supporting process hierarchy (e.g linux), this parameter is > actually > + * redundant as all ODP threads have to be descendant of their ODP > + * instantiation process: In these case, the instance parameter must > match the > + * ODP instance of the ancestor process which called ODP_init_global() > API change not needed for reasons cited above in addition to Petri's point about not changing the API files. > * > * @param instance Instance handle > * @param thr_type Thread type > -- > 2.5.0 > >
On 20 May 2016 at 05:32, Bill Fischofer <bill.fischofer@linaro.org> wrote: > > > On Thu, May 19, 2016 at 7:48 AM, Christophe Milard < > christophe.milard@linaro.org> wrote: > >> Making clear which ODP instance a thread is joining >> when calling odp_init_local(). >> >> Signed-off-by: Christophe Milard <christophe.milard@linaro.org> >> --- >> doc/glossary.adoc | 24 +++++++++++++++++------- >> include/odp/api/spec/init.h | 4 ++++ >> 2 files changed, 21 insertions(+), 7 deletions(-) >> >> diff --git a/doc/glossary.adoc b/doc/glossary.adoc >> index 2c0de24..209a292 100644 >> --- a/doc/glossary.adoc >> +++ b/doc/glossary.adoc >> @@ -10,7 +10,8 @@ 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 OS "flow of execution" (i.e. OS process or OS thread) >> + 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,12 +20,21 @@ 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. >> - 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 >> - 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 >> + `odp_init_local()` becomes an ODP thread. >> + On OSes supporting process hierarchy (e.g. linux), any "flow of >> execution" >> + calling `odp_init_local()` becomes an ODP thread of the ODP instance >> whose >> + ODP instantiation process is an ancestor of (or same as) this >> + "flow of execution". >> + This means that on these OSes, all ODP threads are descendant of (or >> + same as) their ODP instantiation process. >> + This also means that on these OSes, the ODP instance passed as >> + `odp_init_local()` parameter is redundant, as the ODP instance the >> thread >> + belongs to is actually already defined by the process hierarchy. >> > > I don't think we need to be making this point both because it is > unnecessary and also because it may not be accurate. Even today this > parameter is used for call validation (pass a bogus value into > odp_init_local() and the call will fail, regardless of where you are in the > process hierarchy). Since it is opaque, tomorrow, or in other > implementations, it may also have other uses known only to the > implementation. > If the API does not say anything more than it says today, and I write a test trying to attach to an ODP instance a completely unrelated process (using the instance defined in the ODP API), the test will fail on the linux-generic ODP implementation. Hence the ODP linux implementation is proven to be incompatible with the ODP specification. If any function parameter defined in the ODP API can freely be interpreted or ignored by any ODP implementation, the API definition becomes useless. Can we at least agree that the API should state that "Other requirements may be defined by the ODP implemention" for this specific instance parameter and the the process hierarchy requirement text (as desribed above) can be applied to the linux generic ODP implementation? Christophe. > > >> + This parameter is only meaningful on OSes which do not support >> process >> + hierarchy. The instance number should nevertheless be set to the >> correct >> + value (matching the ancestor ODP instance on OS supporting process >> + hierarchy). >> > > Again, this is unneeded and potentially inaccurate. > > >> + Note that, e.g. 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()` >> will be referred as ODP thread, not ODP process). >> event:: >> diff --git a/include/odp/api/spec/init.h b/include/odp/api/spec/init.h >> index fec6774..7592669 100644 >> --- a/include/odp/api/spec/init.h >> +++ b/include/odp/api/spec/init.h >> @@ -234,6 +234,10 @@ int odp_term_global(odp_instance_t instance); >> * All threads must call this function before calling any other ODP API >> * functions. The instance parameter specifies which ODP instance the >> thread >> * joins. A thread may be simultaneously part of single ODP instance >> only. >> + * On OSes supporting process hierarchy (e.g linux), this parameter is >> actually >> + * redundant as all ODP threads have to be descendant of their ODP >> + * instantiation process: In these case, the instance parameter must >> match the >> + * ODP instance of the ancestor process which called ODP_init_global() >> > > API change not needed for reasons cited above in addition to Petri's point > about not changing the API files. > > >> * >> * @param instance Instance handle >> * @param thr_type Thread type >> -- >> 2.5.0 >> >> >
On Fri, May 20, 2016 at 2:52 AM, Savolainen, Petri (Nokia - FI/Espoo) < petri.savolainen@nokia.com> wrote: > > > > > *From:* Christophe Milard [mailto:christophe.milard@linaro.org] > *Sent:* Friday, May 20, 2016 10:22 AM > *To:* Bill Fischofer <bill.fischofer@linaro.org> > *Cc:* Mike Holmes <mike.holmes@linaro.org>; Savolainen, Petri (Nokia - > FI/Espoo) <petri.savolainen@nokia.com>; LNG ODP Mailman List < > lng-odp@lists.linaro.org> > *Subject:* Re: [PATCHv2] doc: proper definition of ODP thread > > > > > > > > On 20 May 2016 at 05:32, Bill Fischofer <bill.fischofer@linaro.org> wrote: > > > > > > On Thu, May 19, 2016 at 7:48 AM, Christophe Milard < > christophe.milard@linaro.org> wrote: > > Making clear which ODP instance a thread is joining > when calling odp_init_local(). > > Signed-off-by: Christophe Milard <christophe.milard@linaro.org> > --- > doc/glossary.adoc | 24 +++++++++++++++++------- > include/odp/api/spec/init.h | 4 ++++ > 2 files changed, 21 insertions(+), 7 deletions(-) > > diff --git a/doc/glossary.adoc b/doc/glossary.adoc > index 2c0de24..209a292 100644 > --- a/doc/glossary.adoc > +++ b/doc/glossary.adoc > @@ -10,7 +10,8 @@ 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 OS "flow of execution" (i.e. OS process or OS thread) > + 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,12 +20,21 @@ 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. > - 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 > - 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 > + `odp_init_local()` becomes an ODP thread. > + On OSes supporting process hierarchy (e.g. linux), any "flow of > execution" > + calling `odp_init_local()` becomes an ODP thread of the ODP instance > whose > + ODP instantiation process is an ancestor of (or same as) this > + "flow of execution". > + This means that on these OSes, all ODP threads are descendant of (or > + same as) their ODP instantiation process. > + This also means that on these OSes, the ODP instance passed as > + `odp_init_local()` parameter is redundant, as the ODP instance the > thread > + belongs to is actually already defined by the process hierarchy. > > > > I don't think we need to be making this point both because it is > unnecessary and also because it may not be accurate. Even today this > parameter is used for call validation (pass a bogus value into > odp_init_local() and the call will fail, regardless of where you are in the > process hierarchy). Since it is opaque, tomorrow, or in other > implementations, it may also have other uses known only to the > implementation. > > > > If the API does not say anything more than it says today, and I write a > test trying to attach to an ODP instance a completely unrelated process > (using the instance defined in the ODP API), the test will fail on the > linux-generic ODP implementation. Hence the ODP linux implementation is > proven to be incompatible with the ODP specification. > > If any function parameter defined in the ODP API can freely be interpreted > or ignored by any ODP implementation, the API definition becomes useless. > > Can we at least agree that the API should state that > > "Other requirements may be defined by the ODP implemention" for this > specific instance parameter and the the process hierarchy requirement text > (as desribed above) can be applied to the linux generic ODP implementation? > > > > Christophe. > > > > > > > > API says: application passes instance ID from global_init to local_init > (to identify into which instance the thread connects in local_init) > > > > odp-linux says: processes are support as odp threads only when there’s a > common init process that first calls global_init and then the same process > forks other processes. > > > > What’s the problem? When application runs on top of odp-linux, it must > apply both specifications (and not try to attach unrelated processes into > an instance, since odp-linux won’t support that). > Agreed. However does this not imply that a single initial thread could call odp_init_global() twice and get back two separate instance handles that it can be used by sub-threads/processes independently? Right now odp-linux doesn't support that but it's also the case that odp_init_global() doesn't check for this and as a result a second call would simply wipe out the first instance. This also prevents odp_init_local() from detecting/responding to attempted duplicate calls (a situation Barry ran into yesterday when he tried using odph_linux_pthread_create() and didn't realize that it too calls odp_init_local(). > > > -Petri > > > > >
diff --git a/doc/glossary.adoc b/doc/glossary.adoc index 2c0de24..209a292 100644 --- a/doc/glossary.adoc +++ b/doc/glossary.adoc @@ -10,7 +10,8 @@ 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 OS "flow of execution" (i.e. OS process or OS thread) + 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,12 +20,21 @@ 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. - 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 - 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 + `odp_init_local()` becomes an ODP thread. + On OSes supporting process hierarchy (e.g. linux), any "flow of execution" + calling `odp_init_local()` becomes an ODP thread of the ODP instance whose + ODP instantiation process is an ancestor of (or same as) this + "flow of execution". + This means that on these OSes, all ODP threads are descendant of (or + same as) their ODP instantiation process. + This also means that on these OSes, the ODP instance passed as + `odp_init_local()` parameter is redundant, as the ODP instance the thread + belongs to is actually already defined by the process hierarchy. + This parameter is only meaningful on OSes which do not support process + hierarchy. The instance number should nevertheless be set to the correct + value (matching the ancestor ODP instance on OS supporting process + hierarchy). + Note that, e.g. 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()` will be referred as ODP thread, not ODP process). event:: diff --git a/include/odp/api/spec/init.h b/include/odp/api/spec/init.h index fec6774..7592669 100644 --- a/include/odp/api/spec/init.h +++ b/include/odp/api/spec/init.h @@ -234,6 +234,10 @@ int odp_term_global(odp_instance_t instance); * All threads must call this function before calling any other ODP API * functions. The instance parameter specifies which ODP instance the thread * joins. A thread may be simultaneously part of single ODP instance only. + * On OSes supporting process hierarchy (e.g linux), this parameter is actually + * redundant as all ODP threads have to be descendant of their ODP + * instantiation process: In these case, the instance parameter must match the + * ODP instance of the ancestor process which called ODP_init_global() * * @param instance Instance handle * @param thr_type Thread type
Making clear which ODP instance a thread is joining when calling odp_init_local(). Signed-off-by: Christophe Milard <christophe.milard@linaro.org> --- doc/glossary.adoc | 24 +++++++++++++++++------- include/odp/api/spec/init.h | 4 ++++ 2 files changed, 21 insertions(+), 7 deletions(-)