| Message ID | 1470998304-32698-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
On Fri, Aug 12, 2016 at 5:38 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > v2 > clean up to text (Bill) > Added comment on bisect ability on patch acceptance > > 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..24e7545 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. > This is somewhat confusing. The reference to "the structures" here is ambiguous and not accurate. ODP does define some structs as part of its API (e.g., the various odp_xxx_param_t and odp_xxx_capability_t objects are explicitly defined as structs in the API) and these are not subject to modification by any implementation since they are part of the API specification. What I believe you're referring to is the fact that implementations are free to use structs internally in how they implement other ODP data types like odp_packet_t, but any application visibility into these objects is only done via access functions rather than exposing these internal structs. The key API vs. ABI distinction here is that in ABI mode these access functions are actual function calls into the shared library while in non-ABI mode they may be expanded as inline functions that have knowledge of these internals, which may result in improved performance at the cost of loss of ABI compatibility. + > +==== ABI compatibility > +In a more traditional system where a possible performance penalty can be > more > Perhaps "non-embedded environments" may be better here than "traditional system"? > +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..24e7545 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 a more traditional system 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> --- v2 clean up to text (Bill) Added comment on bisect ability on patch acceptance doc/process-guide/release-guide.adoc | 52 ++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) -- 2.7.4