| Message ID | 1470670496-8651-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
As an aside, this patch and my patch to this file collide, so we need to figure out who goes first and who gets to rebase. On Mon, Aug 8, 2016 at 10:34 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > doc/process-guide/release-guide.adoc | 53 ++++++++++++++++++++++++++++++ > ++++++ > 1 file changed, 53 insertions(+) > > diff --git a/doc/process-guide/release-guide.adoc > b/doc/process-guide/release-guide.adoc > index 8816c03..c9b8484 100644 > --- a/doc/process-guide/release-guide.adoc > +++ b/doc/process-guide/release-guide.adoc > @@ -115,6 +115,59 @@ atomically as possible > * the maintainer updates the version number > * the maintainer tags the master branch > > +=== Long Term Support (LTS) > +ODP is portable at two levels, at a recompiled common API level for > maximum > +performance, and in a more portable way at an ABI level which may > sacrifice > +some performance. > + > +===== odp-linux API and APB compatibility > +In the odp-linux case, the Linux Operating System (OS) provides a > mechanism for > +ensuring ABI compatibility with the .so naming for shared libraries. This > OS > +specific number provides different definitions for the digits to the ODP > API > +version definition and will likely differ. Other OS'es may use other > schemes. > + > +==== Vendor implementations > +Vendors of ODP are said to be compatible with the ODP API if the > implementation > +can pass the validation test suite for the API. This means that > supporting the > +ABI mode is not required, a statically built and executed test suite is > all that > This is a real grammatical nit, but technically you want a semicolon rather than a comma here as these are two independent clauses. > +is required. > + > +==== API compatibility > +ODP allows implementations of the API to modify the structures. In this > case > +application portability is maintained though access functions to the data > rather > through, not though > +than direct structure access. In an embedded use case this allows the > maximum > Delete 'the' here "...this allows maximum performance with hardware structures mapping..." (also, we've spelled out hardware and software in the docs rather than use HW and SW) > +performance with the HW structures mapping directly to the data structures > +manipulated by the CPU. Applications are compiled for the target > +system directly and are usually statically linked. > + > +==== ABI compatibility > +In a more traditional system where a performance penalty can be accepted > to gain > +portability a shared library is likely to be used and it must maintain ABI > +compatibility across that architecture. In this case applications do not > require > +recompiling. The penalty is that the implementation is probably having to > +translate to the ABI from internal data representations. In some cases the > +translation can also be done in hardware at little cost. > As an aside, because of the way ODP abstractions work, the precise implementation details don't matter for ABI purposes as long as the size and alignment requirements of the abstract types are the same. That is, you could have two implementations that use very different 64-bit encodings for handles and they would still be ABI compatible because the handles are opaque and one opaque 64-bit value is ABI compatible with any other such value. I don't think we need to belabor this point since we're not focused on ABI issues in Monarch. > + > +===== Checking which .so version number is required on change > +To determine if the .so number should be changed the check-odp tool can > provide > +the answer. This tool provides a command line summary and a detailed html > +analysis. This tool is based on the abi-compliance-checker > + > +[source,bash] > +---- > +COMPARE_BRANCH=monarch_lts ./diff-abi.sh > + > +... > +preparation, please wait ... > +comparing ABIs ... > +comparing APIs ... > +creating compatibility report ... > +result: COMPATIBLE > +total "Binary" compatibility problems: 0, warnings: 0 > +total "Source" compatibility problems: 0, warnings: 0 > +.... > +---- > + > == Releases == > All releases are from master. > > -- > 2.7.4 > >
On 8 August 2016 at 15:52, Bill Fischofer <bill.fischofer@linaro.org> wrote: > As an aside, this patch and my patch to this file collide, so we need to > figure out who goes first and who gets to rebase. > > On Mon, Aug 8, 2016 at 10:34 AM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> --- >> doc/process-guide/release-guide.adoc | 53 ++++++++++++++++++++++++++++++ >> ++++++ >> 1 file changed, 53 insertions(+) >> >> diff --git a/doc/process-guide/release-guide.adoc >> b/doc/process-guide/release-guide.adoc >> index 8816c03..c9b8484 100644 >> --- a/doc/process-guide/release-guide.adoc >> +++ b/doc/process-guide/release-guide.adoc >> @@ -115,6 +115,59 @@ atomically as possible >> * the maintainer updates the version number >> * the maintainer tags the master branch >> >> +=== Long Term Support (LTS) >> +ODP is portable at two levels, at a recompiled common API level for >> maximum >> +performance, and in a more portable way at an ABI level which may >> sacrifice >> +some performance. >> + >> +===== odp-linux API and APB compatibility >> +In the odp-linux case, the Linux Operating System (OS) provides a >> mechanism for >> +ensuring ABI compatibility with the .so naming for shared libraries. >> This OS >> +specific number provides different definitions for the digits to the ODP >> API >> +version definition and will likely differ. Other OS'es may use other >> schemes. >> + >> +==== Vendor implementations >> +Vendors of ODP are said to be compatible with the ODP API if the >> implementation >> +can pass the validation test suite for the API. This means that >> supporting the >> +ABI mode is not required, a statically built and executed test suite is >> all that >> > > This is a real grammatical nit, but technically you want a semicolon > rather than a comma here as these are two independent clauses. > Fixed in v2 > > >> +is required. >> + >> +==== API compatibility >> +ODP allows implementations of the API to modify the structures. In this >> case >> +application portability is maintained though access functions to the >> data rather >> > > through, not though > Fixed in v2 > > >> +than direct structure access. In an embedded use case this allows the >> maximum >> > > Delete 'the' here "...this allows maximum performance with hardware > structures mapping..." > Fixed in v2 > (also, we've spelled out hardware and software in the docs rather than use > HW and SW) > Fixed in v2 > > >> +performance with the HW structures mapping directly to the data >> structures >> +manipulated by the CPU. Applications are compiled for the target >> +system directly and are usually statically linked. >> + >> +==== ABI compatibility >> +In a more traditional system where a performance penalty can be accepted >> to gain >> +portability a shared library is likely to be used and it must maintain >> ABI >> +compatibility across that architecture. In this case applications do not >> require >> +recompiling. The penalty is that the implementation is probably having to >> +translate to the ABI from internal data representations. In some cases >> the >> +translation can also be done in hardware at little cost. >> > > As an aside, because of the way ODP abstractions work, the precise > implementation details don't matter for ABI purposes as long as the size > and alignment requirements of the abstract types are the same. That is, you > could have two implementations that use very different 64-bit encodings for > handles and they would still be ABI compatible because the handles are > opaque and one opaque 64-bit value is ABI compatible with any other such > value. I don't think we need to belabor this point since we're not focused > on ABI issues in Monarch. > > I have soften this in v2 Thank you for the review Bill :) > + >> +===== Checking which .so version number is required on change >> +To determine if the .so number should be changed the check-odp tool can >> provide >> +the answer. This tool provides a command line summary and a detailed html >> +analysis. This tool is based on the abi-compliance-checker >> + >> +[source,bash] >> +---- >> +COMPARE_BRANCH=monarch_lts ./diff-abi.sh >> + >> +... >> +preparation, please wait ... >> +comparing ABIs ... >> +comparing APIs ... >> +creating compatibility report ... >> +result: COMPATIBLE >> +total "Binary" compatibility problems: 0, warnings: 0 >> +total "Source" compatibility problems: 0, warnings: 0 >> +.... >> +---- >> + >> == Releases == >> All releases are from master. >> >> -- >> 2.7.4 >> >> > -- 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"
diff --git a/doc/process-guide/release-guide.adoc b/doc/process-guide/release-guide.adoc index 8816c03..c9b8484 100644 --- a/doc/process-guide/release-guide.adoc +++ b/doc/process-guide/release-guide.adoc @@ -115,6 +115,59 @@ atomically as possible * the maintainer updates the version number * the maintainer tags the master branch +=== Long Term Support (LTS) +ODP is portable at two levels, at a recompiled common API level for maximum +performance, and in a more portable way at an ABI level which may sacrifice +some performance. + +===== odp-linux API and APB compatibility +In the odp-linux case, the Linux Operating System (OS) provides a mechanism for +ensuring ABI compatibility with the .so naming for shared libraries. This OS +specific number provides different definitions for the digits to the ODP API +version definition and will likely differ. Other OS'es may use other schemes. + +==== Vendor implementations +Vendors of ODP are said to be compatible with the ODP API if the implementation +can pass the validation test suite for the API. This means that supporting the +ABI mode is not required, a statically built and executed test suite is all that +is required. + +==== API compatibility +ODP allows implementations of the API to modify the structures. In this case +application portability is maintained though access functions to the data rather +than direct structure access. In an embedded use case this allows the maximum +performance with the HW structures mapping directly to the data structures +manipulated by the CPU. Applications are compiled for the target +system directly and are usually statically linked. + +==== ABI compatibility +In a more traditional system where a performance penalty can be accepted to gain +portability a shared library is likely to be used and it must maintain ABI +compatibility across that architecture. In this case applications do not require +recompiling. The penalty is that the implementation is probably having to +translate to the ABI from internal data representations. In some cases the +translation can also be done in hardware at little cost. + +===== Checking which .so version number is required on change +To determine if the .so number should be changed the check-odp tool can provide +the answer. This tool provides a command line summary and a detailed html +analysis. This tool is based on the abi-compliance-checker + +[source,bash] +---- +COMPARE_BRANCH=monarch_lts ./diff-abi.sh + +... +preparation, please wait ... +comparing ABIs ... +comparing APIs ... +creating compatibility report ... +result: COMPATIBLE +total "Binary" compatibility problems: 0, warnings: 0 +total "Source" compatibility problems: 0, warnings: 0 +.... +---- + == Releases == All releases are from master.
Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- doc/process-guide/release-guide.adoc | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) -- 2.7.4