| Message ID | 1471529390-26282-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | Accepted |
| Commit | f11a255716190184f8eaeef1888fd5b82773aa66 |
| Headers | show |
On Thu, Aug 18, 2016 at 9:09 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > v3: > use "non-embedded environments" (bill) > > doc/process-guide/release-guide.adoc | 52 ++++++++++++++++++++++++++++++ > ++++++ > 1 file changed, 52 insertions(+) > > diff --git a/doc/process-guide/release-guide.adoc > b/doc/process-guide/release-guide.adoc > index 788eb6b..8ea147a 100644 > --- a/doc/process-guide/release-guide.adoc > +++ b/doc/process-guide/release-guide.adoc > @@ -83,6 +83,7 @@ repository. > > All patches are acknowledged on the list as soon as they have been > applied to > the repository. > +No patch may be accepted that knowingly breaks git bisect. > > === api-next === > * api-next is always rebased on top of master when there is a release > point in > @@ -115,6 +116,57 @@ 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 through access functions to the > data rather > +than direct structure access. In an embedded use case this allows maximum > +performance with the hardware 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 non-embedded environments where a possible performance penalty can be > more > +acceptable 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. > + > +===== 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 a tag in the master branch of the ODP git > repository. Recall that ODP consists of three separate components: > -- > 2.7.4 > >
Merged, Maxim.. On 08/18/16 17:18, Bill Fischofer wrote: > On Thu, Aug 18, 2016 at 9:09 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> > Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org> > > >> --- >> v3: >> use "non-embedded environments" (bill) >> >> doc/process-guide/release-guide.adoc | 52 ++++++++++++++++++++++++++++++ >> ++++++ >> 1 file changed, 52 insertions(+) >> >> diff --git a/doc/process-guide/release-guide.adoc >> b/doc/process-guide/release-guide.adoc >> index 788eb6b..8ea147a 100644 >> --- a/doc/process-guide/release-guide.adoc >> +++ b/doc/process-guide/release-guide.adoc >> @@ -83,6 +83,7 @@ repository. >> >> All patches are acknowledged on the list as soon as they have been >> applied to >> the repository. >> +No patch may be accepted that knowingly breaks git bisect. >> >> === api-next === >> * api-next is always rebased on top of master when there is a release >> point in >> @@ -115,6 +116,57 @@ 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 through access functions to the >> data rather >> +than direct structure access. In an embedded use case this allows maximum >> +performance with the hardware 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 non-embedded environments where a possible performance penalty can be >> more >> +acceptable 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. >> + >> +===== 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 a tag in the master branch of the ODP git >> repository. Recall that ODP consists of three separate components: >> -- >> 2.7.4 >> >>
diff --git a/doc/process-guide/release-guide.adoc b/doc/process-guide/release-guide.adoc index 788eb6b..8ea147a 100644 --- a/doc/process-guide/release-guide.adoc +++ b/doc/process-guide/release-guide.adoc @@ -83,6 +83,7 @@ repository. All patches are acknowledged on the list as soon as they have been applied to the repository. +No patch may be accepted that knowingly breaks git bisect. === api-next === * api-next is always rebased on top of master when there is a release point in @@ -115,6 +116,57 @@ 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 through access functions to the data rather +than direct structure access. In an embedded use case this allows maximum +performance with the hardware 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 non-embedded environments where a possible performance penalty can be more +acceptable 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. + +===== 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 a tag in the master branch of the ODP git repository. Recall that ODP consists of three separate components:
Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- v3: use "non-embedded environments" (bill) doc/process-guide/release-guide.adoc | 52 ++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) -- 2.7.4