| Message ID | 1463630733-30902-1-git-send-email-bill.fischofer@linaro.org |
|---|---|
| State | New |
| Headers | show |
On 19 May 2016 at 06:05, Bill Fischofer <bill.fischofer@linaro.org> wrote: > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > doc/users-guide/users-guide.adoc | 11 +++++++++++ > 1 file changed, 11 insertions(+) > > diff --git a/doc/users-guide/users-guide.adoc > b/doc/users-guide/users-guide.adoc > index 62f5833..745b85f 100755 > --- a/doc/users-guide/users-guide.adoc > +++ b/doc/users-guide/users-guide.adoc > @@ -155,6 +155,17 @@ and minor release numbers correspond to the ODP API > level that the suite > validates and the fix level represents the service level of the validation > suite itself for that API level. > > +=== ODP Helpers > +ODP also provides a set of _helper_ functions that are > +distinguished by the `odph_` prefix. These are not part of the ODP API > +specification, but may be useful to both applications and implementations. > This statement allows for circular dependancy: Using helpers from the application means that helpers will use ODP, as helpers will perform usual stuff that application needs to do: for instance helpers uses the ODP cpu_mask for creating threads, and helpers may do other common application things toward ODP according to this definition. Having things such as IP header description in helpers means that helpers are needed by ODP: In other words: helper is needed by ODP and needs ODP! I know this is the situation today, but I am not sure we should write this in stone. Maybe the helpers should be splitted as ODP_helpers and APP_helpers? > +This include things like mappings for common packet headers (IPv4, IPv6, > +TCP, UDP, etc.) as well as wrapper functions for the Posix threading model > +used in the odp-linux reference implementation of ODP. Helpers also > provide > +a home for utility APIs that are more experimental in nature and > +are not part of the official ODP API specification. ODP helper APIs are > +described further in the _ODP Helper Reference Manual_. > + > === ODP Design Goals > ODP has three primary goals that follow from its component structure. The > first > is application portability across a wide range of platforms. These > platforms > -- > 2.7.4 > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
On Thu, May 19, 2016 at 3:09 AM, Savolainen, Petri (Nokia - FI/Espoo) < petri.savolainen@nokia.com> wrote: > > > > -----Original Message----- > > From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of > > Christophe Milard > > Sent: Thursday, May 19, 2016 10:43 AM > > To: Bill Fischofer <bill.fischofer@linaro.org> > > Cc: LNG ODP Mailman List <lng-odp@lists.linaro.org> > > Subject: Re: [lng-odp] [PATCH 1/2] doc: userguide: add section describing > > helpers > > > > On 19 May 2016 at 06:05, Bill Fischofer <bill.fischofer@linaro.org> > wrote: > > > > > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > > > > > > > > +=== ODP Helpers > > > +ODP also provides a set of _helper_ functions that are > > > +distinguished by the `odph_` prefix. These are not part of the ODP API > > > +specification, but may be useful to both applications and > > implementations. > > > > > > > This statement allows for circular dependancy: > > Using helpers from the application means that helpers will use ODP, as > > helpers will perform usual stuff that application needs to do: for > > instance > > helpers uses the ODP cpu_mask for creating threads, and helpers may do > > other common application things toward ODP according to this definition. > > Having things such as IP header description in helpers means that helpers > > are needed by ODP: > > In other words: helper is needed by ODP and needs ODP! > > I know this is the situation today, but I am not sure we should write > this > > in stone. Maybe the helpers should be splitted as ODP_helpers and > > APP_helpers? > I don't see the need to make this distinction. While it is true that some helpers use ODP APIs that's perfectly fine since ODP implementations are free to use ODP APIs themselves, and we do that a lot to simplify the code in many places. To have a true circular reference would be to have an unresolvable recursive reference, which is not the case here. > > > > Helpers are for applications (reuse code and definitions in examples and > tests). Implementations should contain their own (protocol header) > definitions, so no dependency to the helper lib. > The reason we put the header mappings in the helpers in the first place is to avoid this sort of unnecessary duplication, so this statement seems odd. There is, of course, no requirement that implementations use these or any other helper functions. They are simply there as a matter of application and/or implementation convenience. > > -Petri > > >
On 20 May 2016 at 03:14, Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia.com> wrote: > > > From: Bill Fischofer [mailto:bill.fischofer@linaro.org] > Sent: Friday, May 20, 2016 2:58 AM > To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia.com> > Cc: Christophe Milard <christophe.milard@linaro.org>; LNG ODP Mailman List <lng-odp@lists.linaro.org> > Subject: Re: [lng-odp] [PATCH 1/2] doc: userguide: add section describing helpers > > > > On Thu, May 19, 2016 at 3:09 AM, Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia.com<mailto:petri.savolainen@nokia.com>> wrote: > > >> -----Original Message----- >> From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org<mailto:lng-odp-bounces@lists.linaro.org>] On Behalf Of >> Christophe Milard >> Sent: Thursday, May 19, 2016 10:43 AM >> To: Bill Fischofer <bill.fischofer@linaro.org<mailto:bill.fischofer@linaro.org>> >> Cc: LNG ODP Mailman List <lng-odp@lists.linaro.org<mailto:lng-odp@lists.linaro.org>> >> Subject: Re: [lng-odp] [PATCH 1/2] doc: userguide: add section describing >> helpers >> >> On 19 May 2016 at 06:05, Bill Fischofer <bill.fischofer@linaro.org<mailto:bill.fischofer@linaro.org>> wrote: >> >> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org<mailto:bill.fischofer@linaro.org>> > > >> > >> > +=== ODP Helpers >> > +ODP also provides a set of _helper_ functions that are >> > +distinguished by the `odph_` prefix. These are not part of the ODP API >> > +specification, but may be useful to both applications and >> implementations. >> > >> >> This statement allows for circular dependancy: >> Using helpers from the application means that helpers will use ODP, as >> helpers will perform usual stuff that application needs to do: for >> instance >> helpers uses the ODP cpu_mask for creating threads, and helpers may do >> other common application things toward ODP according to this definition. >> Having things such as IP header description in helpers means that helpers >> are needed by ODP: >> In other words: helper is needed by ODP and needs ODP! >> I know this is the situation today, but I am not sure we should write this >> in stone. Maybe the helpers should be splitted as ODP_helpers and >> APP_helpers? > > I don't see the need to make this distinction. While it is true that some helpers use ODP APIs that's perfectly fine since ODP implementations are free to use ODP APIs themselves, and we do that a lot to simplify the code in many places. To have a true circular reference would be to have an unresolvable recursive reference, which is not the case here. > >> > > Helpers are for applications (reuse code and definitions in examples and tests). Implementations should contain their own (protocol header) definitions, so no dependency to the helper lib. > > The reason we put the header mappings in the helpers in the first place is to avoid this sort of unnecessary duplication, so this statement seems odd. There is, of course, no requirement that implementations use these or any other helper functions. They are simply there as a matter of application and/or implementation convenience. > > > Since this is user documentation, it does not need to speculate how implementation might have been constructed. This is an old thread but odp-linux cannot depend on odp helpers, you can't package aloop cleanly I am told, so I dont know if that needs documenting From user point of view all odph_ definitions are there for test/example/other app convenience. agree, they are not for the implementations, at least we need to split them if there are to be helpers for both, implementation helpers and app helpers. Each implementation decides independently how and where it defines e.g. protocol headers (include those from SDK or some other library, define from scratch, include odp helpers, …). disagree, no implementation should depend on helpers, it breaks packaging. Any implementation that does this is not going to work well with distributions. It may get them from an SDK, but then the dependency remains one way > > -Petri > > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp
On Tue, May 24, 2016 at 12:35 PM, Mike Holmes <mike.holmes@linaro.org> wrote: > On 20 May 2016 at 03:14, Savolainen, Petri (Nokia - FI/Espoo) > <petri.savolainen@nokia.com> wrote: > > > > > > From: Bill Fischofer [mailto:bill.fischofer@linaro.org] > > Sent: Friday, May 20, 2016 2:58 AM > > To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia.com> > > Cc: Christophe Milard <christophe.milard@linaro.org>; LNG ODP Mailman > List <lng-odp@lists.linaro.org> > > Subject: Re: [lng-odp] [PATCH 1/2] doc: userguide: add section > describing helpers > > > > > > > > On Thu, May 19, 2016 at 3:09 AM, Savolainen, Petri (Nokia - FI/Espoo) < > petri.savolainen@nokia.com<mailto:petri.savolainen@nokia.com>> wrote: > > > > > >> -----Original Message----- > >> From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org<mailto: > lng-odp-bounces@lists.linaro.org>] On Behalf Of > >> Christophe Milard > >> Sent: Thursday, May 19, 2016 10:43 AM > >> To: Bill Fischofer <bill.fischofer@linaro.org<mailto: > bill.fischofer@linaro.org>> > >> Cc: LNG ODP Mailman List <lng-odp@lists.linaro.org<mailto: > lng-odp@lists.linaro.org>> > >> Subject: Re: [lng-odp] [PATCH 1/2] doc: userguide: add section > describing > >> helpers > >> > >> On 19 May 2016 at 06:05, Bill Fischofer <bill.fischofer@linaro.org > <mailto:bill.fischofer@linaro.org>> wrote: > >> > >> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org<mailto: > bill.fischofer@linaro.org>> > > > > > >> > > >> > +=== ODP Helpers > >> > +ODP also provides a set of _helper_ functions that are > >> > +distinguished by the `odph_` prefix. These are not part of the ODP > API > >> > +specification, but may be useful to both applications and > >> implementations. > >> > > >> > >> This statement allows for circular dependancy: > >> Using helpers from the application means that helpers will use ODP, as > >> helpers will perform usual stuff that application needs to do: for > >> instance > >> helpers uses the ODP cpu_mask for creating threads, and helpers may do > >> other common application things toward ODP according to this definition. > >> Having things such as IP header description in helpers means that > helpers > >> are needed by ODP: > >> In other words: helper is needed by ODP and needs ODP! > >> I know this is the situation today, but I am not sure we should write > this > >> in stone. Maybe the helpers should be splitted as ODP_helpers and > >> APP_helpers? > > > > I don't see the need to make this distinction. While it is true that > some helpers use ODP APIs that's perfectly fine since ODP implementations > are free to use ODP APIs themselves, and we do that a lot to simplify the > code in many places. To have a true circular reference would be to have an > unresolvable recursive reference, which is not the case here. > > > >> > > > > Helpers are for applications (reuse code and definitions in examples and > tests). Implementations should contain their own (protocol header) > definitions, so no dependency to the helper lib. > > > > The reason we put the header mappings in the helpers in the first place > is to avoid this sort of unnecessary duplication, so this statement seems > odd. There is, of course, no requirement that implementations use these or > any other helper functions. They are simply there as a matter of > application and/or implementation convenience. > > > > > > Since this is user documentation, it does not need to speculate how > implementation might have been constructed. > > This is an old thread but odp-linux cannot depend on odp helpers, you > can't package aloop cleanly I am told, so I dont know if that needs > documenting > > From user point of view all odph_ definitions are there for > test/example/other app convenience. > > agree, they are not for the implementations, at least we need to split > them if there are to be helpers for both, implementation helpers and > app helpers. > > Each implementation decides independently how and where it defines > e.g. protocol headers (include those from SDK or some other library, > define from scratch, include odp helpers, …). > > disagree, no implementation should depend on helpers, it breaks > packaging. Any implementation that does this is not going to work well > with distributions. It may get them from an SDK, but then the > dependency remains one way > I've added this as a discussion topic for Wednesday's ARCH call. The question of packaging is separate for whether or not helpers are useful to implementations. I'd like to better understand the packaging issues and what (if anything) we can do about that. Clearly we do have a packaging issue for mixing at least some helper functions with odp-linux. The question is why and whether this is something we should fix. > > > > -Petri > > > > > > > > _______________________________________________ > > 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 │ Open source software for ARM SoCs > "Work should be fun and collaborative, the rest follows" >
diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 62f5833..745b85f 100755 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -155,6 +155,17 @@ and minor release numbers correspond to the ODP API level that the suite validates and the fix level represents the service level of the validation suite itself for that API level. +=== ODP Helpers +ODP also provides a set of _helper_ functions that are +distinguished by the `odph_` prefix. These are not part of the ODP API +specification, but may be useful to both applications and implementations. +This include things like mappings for common packet headers (IPv4, IPv6, +TCP, UDP, etc.) as well as wrapper functions for the Posix threading model +used in the odp-linux reference implementation of ODP. Helpers also provide +a home for utility APIs that are more experimental in nature and +are not part of the official ODP API specification. ODP helper APIs are +described further in the _ODP Helper Reference Manual_. + === ODP Design Goals ODP has three primary goals that follow from its component structure. The first is application portability across a wide range of platforms. These platforms
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- doc/users-guide/users-guide.adoc | 11 +++++++++++ 1 file changed, 11 insertions(+)