| Message ID | 1409925103-32346-1-git-send-email-taras.kondratiuk@linaro.org |
|---|---|
| State | New |
| Headers | show |
Good idea. What's the strict meaning of the a/b/c numbers? I would like to see a definition on how these numbers change when you make common changes. E.g. add function or type remove function or type syntactical change (but same semantics so functionally backwards compatible), maybe adding an argument or change in header files semantic change (but same syntax so existing code would compile but perhaps not run as expected) other cases? -- Ola On 5 September 2014 15:51, Taras Kondratiuk <taras.kondratiuk@linaro.org> wrote: > API and header names will evolve and change continuously. Some changes > may be not backward compatible. Application need some mechanism to > support at least a few recent revisions of ODP API. Hence add a few > macros to be able to compare ODP API versions. > > Macros can be used in a following way: > > #include <odp_version.h> > #if ODP_VERSION_API >= ODP_VERSION(2,0,0) > /* Call ODP v2.0 API */ > #elif ODP_VERSION_API >= ODP_VERSION(1,0,0) > /* Call ODP v1.0 API */ > #else > /* Call pre v1.0 API */ > #endif > > Signed-off-by: Taras Kondratiuk <taras.kondratiuk@linaro.org> > Signed-off-by: Taras Kondratiuk <taras@ti.com> > --- > platform/linux-generic/include/api/odp_version.h | 16 ++++++++++++++++ > 1 file changed, 16 insertions(+) > > diff --git a/platform/linux-generic/include/api/odp_version.h > b/platform/linux-generic/include/api/odp_version.h > index c823e2d..97f8e26 100644 > --- a/platform/linux-generic/include/api/odp_version.h > +++ b/platform/linux-generic/include/api/odp_version.h > @@ -44,6 +44,22 @@ extern "C" { > */ > #define ODP_VERSION_API_BUG 1 > > +/** > + * Macro to merge three parts of ODP API version into one word > + * > + * Merge ODP version into one word: > + * byte 0 - bug correction version > + * byte 1 - sub version > + * byte 2 - main version > + */ > +#define ODP_VERSION(a, b, c) (((a) << 16) + ((b) << 8) + (c)) > + > +/** > + * Current version of ODP API in one word form > + */ > +#define ODP_VERSION_API ODP_VERSION((ODP_VERSION_API_MAIN), \ > + (ODP_VERSION_API_SUB), \ > + (ODP_VERSION_API_BUG)) > > /** @internal Version string expand */ > #define ODP_VERSION_STR_EXPAND(x) #x > -- > 1.7.9.5 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
- Major version numbers change whenever there is something significant, a large or potentially backward-incompatible change to a software package. - Minor version numbers change when a new, minor feature is introduced, or when a set of smaller features is rolled out. - Patch numbers change when a new build of the software is released to customers. This is normally for small bugfixes or the like. On 5 September 2014 10:54, Ola Liljedahl <ola.liljedahl@linaro.org> wrote: > Good idea. > What's the strict meaning of the a/b/c numbers? I would like to see a > definition on how these numbers change when you make common changes. > E.g. > add function or type > remove function or type > syntactical change (but same semantics so functionally backwards > compatible), maybe adding an argument or change in header files > semantic change (but same syntax so existing code would compile but > perhaps not run as expected) > other cases? > > -- Ola > > > > > On 5 September 2014 15:51, Taras Kondratiuk <taras.kondratiuk@linaro.org> > wrote: > >> API and header names will evolve and change continuously. Some changes >> may be not backward compatible. Application need some mechanism to >> support at least a few recent revisions of ODP API. Hence add a few >> macros to be able to compare ODP API versions. >> >> Macros can be used in a following way: >> >> #include <odp_version.h> >> #if ODP_VERSION_API >= ODP_VERSION(2,0,0) >> /* Call ODP v2.0 API */ >> #elif ODP_VERSION_API >= ODP_VERSION(1,0,0) >> /* Call ODP v1.0 API */ >> #else >> /* Call pre v1.0 API */ >> #endif >> >> Signed-off-by: Taras Kondratiuk <taras.kondratiuk@linaro.org> >> Signed-off-by: Taras Kondratiuk <taras@ti.com> >> --- >> platform/linux-generic/include/api/odp_version.h | 16 ++++++++++++++++ >> 1 file changed, 16 insertions(+) >> >> diff --git a/platform/linux-generic/include/api/odp_version.h >> b/platform/linux-generic/include/api/odp_version.h >> index c823e2d..97f8e26 100644 >> --- a/platform/linux-generic/include/api/odp_version.h >> +++ b/platform/linux-generic/include/api/odp_version.h >> @@ -44,6 +44,22 @@ extern "C" { >> */ >> #define ODP_VERSION_API_BUG 1 >> >> +/** >> + * Macro to merge three parts of ODP API version into one word >> + * >> + * Merge ODP version into one word: >> + * byte 0 - bug correction version >> + * byte 1 - sub version >> + * byte 2 - main version >> + */ >> +#define ODP_VERSION(a, b, c) (((a) << 16) + ((b) << 8) + (c)) >> + >> +/** >> + * Current version of ODP API in one word form >> + */ >> +#define ODP_VERSION_API ODP_VERSION((ODP_VERSION_API_MAIN), \ >> + (ODP_VERSION_API_SUB), \ >> + (ODP_VERSION_API_BUG)) >> >> /** @internal Version string expand */ >> #define ODP_VERSION_STR_EXPAND(x) #x >> -- >> 1.7.9.5 >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp >> > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp > >
On Fri, Sep 05, 2014 at 11:06:47AM -0400, Mike Holmes wrote: > • Major version numbers change whenever there is something significant, a > large or potentially backward-incompatible change to a software package. > • Minor version numbers change when a new, minor feature is introduced, or > when a set of smaller features is rolled out. > • Patch numbers change when a new build of the software is released to > customers. This is normally for small bugfixes or the like. *nod* There's extra complexity on top of that if you're providing a shared library, but AIUI we've decided not to do that for ODP. Cheers,
We also need to remember that pre-v1.0 we've made no guarantees of API stability. That's one of the big milestones for ODP v1.0--that APIs have achieved stability. As part of the v1.0 delivery, everything in the repository should be at a v1.0 level--so there should be no need for any of this until post-v1.0 delivery. Going forward, API changes need to be subject to release versioning. Following Mike's points, anything that's not backward-compatible with v1.0 would need to be v2.0. If we do a v1.1, etc. it would only be to add or extend things in a compatible manner. Patches (v1.0.1, etc.) are just bug fixes and can have no API changes. One of the things we'll be discussing with the LNG-SC during LCU is expectations for support (e.g., do we need a v1.0 LTS even after v2.0 shows up, etc.). All part of the "growing pains" of having real users for ODP--something we certainly want. Bill On Fri, Sep 5, 2014 at 10:06 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > > - Major version numbers change whenever there is something > significant, a large or potentially backward-incompatible change to a > software package. > - Minor version numbers change when a new, minor feature is > introduced, or when a set of smaller features is rolled out. > - Patch numbers change when a new build of the software is released to > customers. This is normally for small bugfixes or the like. > > > > On 5 September 2014 10:54, Ola Liljedahl <ola.liljedahl@linaro.org> wrote: > >> Good idea. >> What's the strict meaning of the a/b/c numbers? I would like to see a >> definition on how these numbers change when you make common changes. >> E.g. >> add function or type >> remove function or type >> syntactical change (but same semantics so functionally backwards >> compatible), maybe adding an argument or change in header files >> semantic change (but same syntax so existing code would compile but >> perhaps not run as expected) >> other cases? >> >> -- Ola >> >> >> >> >> On 5 September 2014 15:51, Taras Kondratiuk <taras.kondratiuk@linaro.org> >> wrote: >> >>> API and header names will evolve and change continuously. Some changes >>> may be not backward compatible. Application need some mechanism to >>> support at least a few recent revisions of ODP API. Hence add a few >>> macros to be able to compare ODP API versions. >>> >>> Macros can be used in a following way: >>> >>> #include <odp_version.h> >>> #if ODP_VERSION_API >= ODP_VERSION(2,0,0) >>> /* Call ODP v2.0 API */ >>> #elif ODP_VERSION_API >= ODP_VERSION(1,0,0) >>> /* Call ODP v1.0 API */ >>> #else >>> /* Call pre v1.0 API */ >>> #endif >>> >>> Signed-off-by: Taras Kondratiuk <taras.kondratiuk@linaro.org> >>> Signed-off-by: Taras Kondratiuk <taras@ti.com> >>> --- >>> platform/linux-generic/include/api/odp_version.h | 16 ++++++++++++++++ >>> 1 file changed, 16 insertions(+) >>> >>> diff --git a/platform/linux-generic/include/api/odp_version.h >>> b/platform/linux-generic/include/api/odp_version.h >>> index c823e2d..97f8e26 100644 >>> --- a/platform/linux-generic/include/api/odp_version.h >>> +++ b/platform/linux-generic/include/api/odp_version.h >>> @@ -44,6 +44,22 @@ extern "C" { >>> */ >>> #define ODP_VERSION_API_BUG 1 >>> >>> +/** >>> + * Macro to merge three parts of ODP API version into one word >>> + * >>> + * Merge ODP version into one word: >>> + * byte 0 - bug correction version >>> + * byte 1 - sub version >>> + * byte 2 - main version >>> + */ >>> +#define ODP_VERSION(a, b, c) (((a) << 16) + ((b) << 8) + (c)) >>> + >>> +/** >>> + * Current version of ODP API in one word form >>> + */ >>> +#define ODP_VERSION_API ODP_VERSION((ODP_VERSION_API_MAIN), \ >>> + (ODP_VERSION_API_SUB), \ >>> + (ODP_VERSION_API_BUG)) >>> >>> /** @internal Version string expand */ >>> #define ODP_VERSION_STR_EXPAND(x) #x >>> -- >>> 1.7.9.5 >>> >>> >>> _______________________________________________ >>> lng-odp mailing list >>> lng-odp@lists.linaro.org >>> http://lists.linaro.org/mailman/listinfo/lng-odp >>> >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp >> >> > > > -- > *Mike Holmes* > Linaro Technical Manager / Lead > LNG - ODP > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp > >
Related to versioning frequency and for your thoughts and inclusion in the ARC doc with the above info I don't think we should have weekly, monthly or other period internal releases only Public ones, instead the expectation would be like this. All patches no matter what compile for all public platforms (a driver towards public participation in line with linux, the modifier of code must address your platform as necessary) New Feature Caveats:- - new features only have to compile on all platforms, i.e it is ok to add stubs to DPDK,netmap & KS2 for a new API that is only fully implemented on linux-generic - new features have a minimal validation test at 1st patch submission so that other platforms can start working towards compliance - Obviously by every full release the validation suite is completed by all public platforms, others are free to prove compliance later on their own schedule - The validation suite is contributed to by all platform developers (private implementations as well if LNG members) before a public release ensure we do everything we can to specify how that feature should behave in the test suite. Bug Fixes to existing APIs Caveats:- - Patches must work for all public platforms, the validation tests must be run, this should be via private or possibly Maxims public staging branch. but you won't want it to get to him before it fails. CI makes these staging run set ups for your own git repo easy. On 5 September 2014 11:26, Bill Fischofer <bill.fischofer@linaro.org> wrote: > We also need to remember that pre-v1.0 we've made no guarantees of API > stability. That's one of the big milestones for ODP v1.0--that APIs have > achieved stability. As part of the v1.0 delivery, everything in the > repository should be at a v1.0 level--so there should be no need for any of > this until post-v1.0 delivery. > > Going forward, API changes need to be subject to release versioning. > Following Mike's points, anything that's not backward-compatible with v1.0 > would need to be v2.0. If we do a v1.1, etc. it would only be to add or > extend things in a compatible manner. Patches (v1.0.1, etc.) are just bug > fixes and can have no API changes. > > One of the things we'll be discussing with the LNG-SC during LCU is > expectations for support (e.g., do we need a v1.0 LTS even after v2.0 shows > up, etc.). All part of the "growing pains" of having real users for > ODP--something we certainly want. > > Bill > > > On Fri, Sep 5, 2014 at 10:06 AM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> >> - Major version numbers change whenever there is something >> significant, a large or potentially backward-incompatible change to a >> software package. >> - Minor version numbers change when a new, minor feature is >> introduced, or when a set of smaller features is rolled out. >> - Patch numbers change when a new build of the software is released >> to customers. This is normally for small bugfixes or the like. >> >> >> >> On 5 September 2014 10:54, Ola Liljedahl <ola.liljedahl@linaro.org> >> wrote: >> >>> Good idea. >>> What's the strict meaning of the a/b/c numbers? I would like to see a >>> definition on how these numbers change when you make common changes. >>> E.g. >>> add function or type >>> remove function or type >>> syntactical change (but same semantics so functionally backwards >>> compatible), maybe adding an argument or change in header files >>> semantic change (but same syntax so existing code would compile but >>> perhaps not run as expected) >>> other cases? >>> >>> -- Ola >>> >>> >>> >>> >>> On 5 September 2014 15:51, Taras Kondratiuk <taras.kondratiuk@linaro.org >>> > wrote: >>> >>>> API and header names will evolve and change continuously. Some changes >>>> may be not backward compatible. Application need some mechanism to >>>> support at least a few recent revisions of ODP API. Hence add a few >>>> macros to be able to compare ODP API versions. >>>> >>>> Macros can be used in a following way: >>>> >>>> #include <odp_version.h> >>>> #if ODP_VERSION_API >= ODP_VERSION(2,0,0) >>>> /* Call ODP v2.0 API */ >>>> #elif ODP_VERSION_API >= ODP_VERSION(1,0,0) >>>> /* Call ODP v1.0 API */ >>>> #else >>>> /* Call pre v1.0 API */ >>>> #endif >>>> >>>> Signed-off-by: Taras Kondratiuk <taras.kondratiuk@linaro.org> >>>> Signed-off-by: Taras Kondratiuk <taras@ti.com> >>>> --- >>>> platform/linux-generic/include/api/odp_version.h | 16 >>>> ++++++++++++++++ >>>> 1 file changed, 16 insertions(+) >>>> >>>> diff --git a/platform/linux-generic/include/api/odp_version.h >>>> b/platform/linux-generic/include/api/odp_version.h >>>> index c823e2d..97f8e26 100644 >>>> --- a/platform/linux-generic/include/api/odp_version.h >>>> +++ b/platform/linux-generic/include/api/odp_version.h >>>> @@ -44,6 +44,22 @@ extern "C" { >>>> */ >>>> #define ODP_VERSION_API_BUG 1 >>>> >>>> +/** >>>> + * Macro to merge three parts of ODP API version into one word >>>> + * >>>> + * Merge ODP version into one word: >>>> + * byte 0 - bug correction version >>>> + * byte 1 - sub version >>>> + * byte 2 - main version >>>> + */ >>>> +#define ODP_VERSION(a, b, c) (((a) << 16) + ((b) << 8) + (c)) >>>> + >>>> +/** >>>> + * Current version of ODP API in one word form >>>> + */ >>>> +#define ODP_VERSION_API ODP_VERSION((ODP_VERSION_API_MAIN), \ >>>> + (ODP_VERSION_API_SUB), \ >>>> + (ODP_VERSION_API_BUG)) >>>> >>>> /** @internal Version string expand */ >>>> #define ODP_VERSION_STR_EXPAND(x) #x >>>> -- >>>> 1.7.9.5 >>>> >>>> >>>> _______________________________________________ >>>> lng-odp mailing list >>>> lng-odp@lists.linaro.org >>>> http://lists.linaro.org/mailman/listinfo/lng-odp >>>> >>> >>> >>> _______________________________________________ >>> lng-odp mailing list >>> lng-odp@lists.linaro.org >>> http://lists.linaro.org/mailman/listinfo/lng-odp >>> >>> >> >> >> -- >> *Mike Holmes* >> Linaro Technical Manager / Lead >> LNG - ODP >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp >> >> >
I think we should separate between ODP implementations and the ODP API. Users (applications) are primarily interested in the API. Any API changes can be separated into backwards and not backwards compatible changes. I think a major.minor designation for the ODP API is sufficient (there is no patch level of the API specification or?). The major number changes for any incompatible changes (with minor number reset), the minor number changes for any backwards compatible change (with major number kept). Small or big change is not relevant. One can imagine an application that attempts to handle changes (bugs and bug fixes) in the ODP implementation by checking which version (including the C number as defined below) the implementation is at. But this will be difficult with ODP since there will be multiple implementations and those can and will likely have different version sequences. The application would also need a mean to identify which ODP implementation it is using. How is Linux/Unix handling similar *interface* versioning, e.g. X server interface? The X server interface has one version, the X server implementation (and there is or at least was more than one) has another version from different version sequence. -- Ola On 5 September 2014 17:06, Mike Holmes <mike.holmes@linaro.org> wrote: > > - Major version numbers change whenever there is something > significant, a large or potentially backward-incompatible change to a > software package. > - Minor version numbers change when a new, minor feature is > introduced, or when a set of smaller features is rolled out. > - Patch numbers change when a new build of the software is released to > customers. This is normally for small bugfixes or the like. > > > > On 5 September 2014 10:54, Ola Liljedahl <ola.liljedahl@linaro.org> wrote: > >> Good idea. >> What's the strict meaning of the a/b/c numbers? I would like to see a >> definition on how these numbers change when you make common changes. >> E.g. >> add function or type >> remove function or type >> syntactical change (but same semantics so functionally backwards >> compatible), maybe adding an argument or change in header files >> semantic change (but same syntax so existing code would compile but >> perhaps not run as expected) >> other cases? >> >> -- Ola >> >> >> >> >> On 5 September 2014 15:51, Taras Kondratiuk <taras.kondratiuk@linaro.org> >> wrote: >> >>> API and header names will evolve and change continuously. Some changes >>> may be not backward compatible. Application need some mechanism to >>> support at least a few recent revisions of ODP API. Hence add a few >>> macros to be able to compare ODP API versions. >>> >>> Macros can be used in a following way: >>> >>> #include <odp_version.h> >>> #if ODP_VERSION_API >= ODP_VERSION(2,0,0) >>> /* Call ODP v2.0 API */ >>> #elif ODP_VERSION_API >= ODP_VERSION(1,0,0) >>> /* Call ODP v1.0 API */ >>> #else >>> /* Call pre v1.0 API */ >>> #endif >>> >>> Signed-off-by: Taras Kondratiuk <taras.kondratiuk@linaro.org> >>> Signed-off-by: Taras Kondratiuk <taras@ti.com> >>> --- >>> platform/linux-generic/include/api/odp_version.h | 16 ++++++++++++++++ >>> 1 file changed, 16 insertions(+) >>> >>> diff --git a/platform/linux-generic/include/api/odp_version.h >>> b/platform/linux-generic/include/api/odp_version.h >>> index c823e2d..97f8e26 100644 >>> --- a/platform/linux-generic/include/api/odp_version.h >>> +++ b/platform/linux-generic/include/api/odp_version.h >>> @@ -44,6 +44,22 @@ extern "C" { >>> */ >>> #define ODP_VERSION_API_BUG 1 >>> >>> +/** >>> + * Macro to merge three parts of ODP API version into one word >>> + * >>> + * Merge ODP version into one word: >>> + * byte 0 - bug correction version >>> + * byte 1 - sub version >>> + * byte 2 - main version >>> + */ >>> +#define ODP_VERSION(a, b, c) (((a) << 16) + ((b) << 8) + (c)) >>> + >>> +/** >>> + * Current version of ODP API in one word form >>> + */ >>> +#define ODP_VERSION_API ODP_VERSION((ODP_VERSION_API_MAIN), \ >>> + (ODP_VERSION_API_SUB), \ >>> + (ODP_VERSION_API_BUG)) >>> >>> /** @internal Version string expand */ >>> #define ODP_VERSION_STR_EXPAND(x) #x >>> -- >>> 1.7.9.5 >>> >>> >>> _______________________________________________ >>> lng-odp mailing list >>> lng-odp@lists.linaro.org >>> http://lists.linaro.org/mailman/listinfo/lng-odp >>> >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp >> >> > > > -- > *Mike Holmes* > Linaro Technical Manager / Lead > LNG - ODP >
On 09/10/2014 05:35 PM, Ola Liljedahl wrote: > I think we should separate between ODP implementations and the ODP API. > Users (applications) are primarily interested in the API. Any API > changes can be separated into backwards and not backwards compatible > changes. I think a major.minor designation for the ODP API is sufficient > (there is no patch level of the API specification or?). The major number > changes for any incompatible changes (with minor number reset), the > minor number changes for any backwards compatible change (with major > number kept). Small or big change is not relevant. I had in mind a bit different schema: major.minor.sub. - 'major.minor' is an official ODP release version, like v1.0 we are going to have by EOY. - 'sub' is a version that must be incremented on each incompatible API change (syntax or semantics) between releases. It is reset on each major.minor change. IMO there is no point to change API version for backward compatible changes. > > One can imagine an application that attempts to handle changes (bugs and > bug fixes) in the ODP implementation by checking which version > (including the C number as defined below) the implementation is at. But > this will be difficult with ODP since there will be multiple > implementations and those can and will likely have different version > sequences. The application would also need a mean to identify which ODP > implementation it is using. Currently ODP_VERSION_API* macros address only API versions. Adding versions for implementation is a separate story. To use it we may need a way for application to detect which implementation is used. Maybe expose define like ODP_PLATFORM_LINUX_GENERIC.
Hi, Agree with Taras on three levels. It's there in odp_version.h already, but we may need to revise the comments a bit. The main digit must be reserved for ODP API generations (major reorganizations, etc). If it would be used only to indicate backward incompatibility, we'd be in ODP 15.0 in couple of months... Similarly I see that after 1.0 comes 1.1 (2.0 would be major rework of the whole thing). So, first two digits indicate (potential) backward incompatibility. Third one can be used for backward compatible changes (small additions, bug fixes, missing doxygen comments, documentation bugs, white spaces, etc). The point being that if all three are the same, it's 100% the same. If first two are the same, application compiles and runs without any change. -Petri > -----Original Message----- > From: ext Taras Kondratiuk [mailto:taras.kondratiuk@linaro.org] > Sent: Wednesday, September 10, 2014 6:10 PM > To: Ola Liljedahl; Mike Holmes > Cc: Savolainen, Petri (NSN - FI/Espoo); Taras Kondratiuk; lng- > odp@lists.linaro.org > Subject: Re: [lng-odp] [PATCH] linux-generic: version: Add macros to > compare ODP versions > > On 09/10/2014 05:35 PM, Ola Liljedahl wrote: > > I think we should separate between ODP implementations and the ODP API. > > Users (applications) are primarily interested in the API. Any API > > changes can be separated into backwards and not backwards compatible > > changes. I think a major.minor designation for the ODP API is sufficient > > (there is no patch level of the API specification or?). The major number > > changes for any incompatible changes (with minor number reset), the > > minor number changes for any backwards compatible change (with major > > number kept). Small or big change is not relevant. > > I had in mind a bit different schema: major.minor.sub. > - 'major.minor' is an official ODP release version, like v1.0 we are > going to have by EOY. > - 'sub' is a version that must be incremented on each incompatible > API change (syntax or semantics) between releases. It is reset on > each major.minor change. > > IMO there is no point to change API version for backward compatible > changes. > > > > > One can imagine an application that attempts to handle changes (bugs and > > bug fixes) in the ODP implementation by checking which version > > (including the C number as defined below) the implementation is at. But > > this will be difficult with ODP since there will be multiple > > implementations and those can and will likely have different version > > sequences. The application would also need a mean to identify which ODP > > implementation it is using. > > Currently ODP_VERSION_API* macros address only API versions. > Adding versions for implementation is a separate story. To use it we > may need a way for application to detect which implementation is used. > Maybe expose define like ODP_PLATFORM_LINUX_GENERIC.
Taras: - 'sub' is a version that must be incremented on each *incompatible* API change (syntax or semantics) between releases. It is reset on each major.minor change. You mean "compatible"? I think it makes sense to change the API version also when making backwards compatible changes. E.g. if we are adding a function or some parameter flag but this is not worthy of a major.minor increment. An application might want to know if a specific function or feature is available. Petri: This is not equivalent to Mike's description where only the major number would be changed for incompatible changes where you write that the first two digits (or numbers) indicate (potential) backward incompatibility. I think your definition is the best. I also think the description needs to include what promises are made to the users (the applications), e.g. your two last sentences, otherwise the definition is going to be too abstract and we will come back and argue what the version numbers really means. In the mean time, changes will have been made that violate the versioning scheme. On 11 September 2014 09:25, Savolainen, Petri (NSN - FI/Espoo) < petri.savolainen@nsn.com> wrote: > Hi, > > Agree with Taras on three levels. It's there in odp_version.h already, but > we may need to revise the comments a bit. > > The main digit must be reserved for ODP API generations (major > reorganizations, etc). If it would be used only to indicate backward > incompatibility, we'd be in ODP 15.0 in couple of months... Similarly I see > that after 1.0 comes 1.1 (2.0 would be major rework of the whole thing). > > So, first two digits indicate (potential) backward incompatibility. Third > one can be used for backward compatible changes (small additions, bug > fixes, missing doxygen comments, documentation bugs, white spaces, etc). > The point being that if all three are the same, it's 100% the same. If > first two are the same, application compiles and runs without any change. > > -Petri > > > > -----Original Message----- > > From: ext Taras Kondratiuk [mailto:taras.kondratiuk@linaro.org] > > Sent: Wednesday, September 10, 2014 6:10 PM > > To: Ola Liljedahl; Mike Holmes > > Cc: Savolainen, Petri (NSN - FI/Espoo); Taras Kondratiuk; lng- > > odp@lists.linaro.org > > Subject: Re: [lng-odp] [PATCH] linux-generic: version: Add macros to > > compare ODP versions > > > > On 09/10/2014 05:35 PM, Ola Liljedahl wrote: > > > I think we should separate between ODP implementations and the ODP API. > > > Users (applications) are primarily interested in the API. Any API > > > changes can be separated into backwards and not backwards compatible > > > changes. I think a major.minor designation for the ODP API is > sufficient > > > (there is no patch level of the API specification or?). The major > number > > > changes for any incompatible changes (with minor number reset), the > > > minor number changes for any backwards compatible change (with major > > > number kept). Small or big change is not relevant. > > > > I had in mind a bit different schema: major.minor.sub. > > - 'major.minor' is an official ODP release version, like v1.0 we are > > going to have by EOY. > > - 'sub' is a version that must be incremented on each incompatible > > API change (syntax or semantics) between releases. It is reset on > > each major.minor change. > > > > IMO there is no point to change API version for backward compatible > > changes. > > > > > > > > One can imagine an application that attempts to handle changes (bugs > and > > > bug fixes) in the ODP implementation by checking which version > > > (including the C number as defined below) the implementation is at. But > > > this will be difficult with ODP since there will be multiple > > > implementations and those can and will likely have different version > > > sequences. The application would also need a mean to identify which ODP > > > implementation it is using. > > > > Currently ODP_VERSION_API* macros address only API versions. > > Adding versions for implementation is a separate story. To use it we > > may need a way for application to detect which implementation is used. > > Maybe expose define like ODP_PLATFORM_LINUX_GENERIC. >
Is there any follow on from connect on this thread ? I realise Taras is out but can we all converge on the final wording for a three level configuration ? All this is from the application writers perspective and not from the PLATFORM implementers perspective, it ONLY describes the API, not infrastructure changes. 'major.minor.sub ' The *major* digit is the ODP API generation. It would be used generally to indicate backward incompatibility, a change to this digit will break backwards compatibility - Altering API signature - Altering a structure - Changing the required calling sequence for APIs - Changes to the installed structure - New element to an enum that is an output from ODP The *minor* digit is for changes that are probably backwards compatible. Things such as the the addition of a new API. Existing application code probably does not have to change. Any existing app should not need to change any calls and it should continue to compile with the new ODP API version - Adding a new struct - Adding a new function - Adding an additional alternate API to an existing one. - New element to an enum that is an input to ODP *The first two digits indicate (potential) backward incompatibility, only ODP (the community) can update these two numbers. * The *sub* digit is used for backward compatible changes Any existing app should work as before with the caveat that a bug fix may change the executable behavior (hopefully improve it) - Optimize the implementation - Documentation updates - Whitespace - bug fixes in implementation On 11 September 2014 09:00, Ola Liljedahl <ola.liljedahl@linaro.org> wrote: > Taras: > - 'sub' is a version that must be incremented on each *incompatible* > API change (syntax or semantics) between releases. It is reset on > each major.minor change. > You mean "compatible"? > > I think it makes sense to change the API version also when making > backwards compatible changes. E.g. if we are adding a function or some > parameter flag but this is not worthy of a major.minor increment. An > application might want to know if a specific function or feature is > available. > > Petri: > This is not equivalent to Mike's description where only the major number > would be changed for incompatible changes where you write that the first > two digits (or numbers) indicate (potential) backward incompatibility. > > I think your definition is the best. I also think the description needs to > include what promises are made to the users (the applications), e.g. your > two last sentences, otherwise the definition is going to be too abstract > and we will come back and argue what the version numbers really means. In > the mean time, changes will have been made that violate the versioning > scheme. > > > > On 11 September 2014 09:25, Savolainen, Petri (NSN - FI/Espoo) < > petri.savolainen@nsn.com> wrote: > >> Hi, >> >> Agree with Taras on three levels. It's there in odp_version.h already, >> but we may need to revise the comments a bit. >> >> The main digit must be reserved for ODP API generations (major >> reorganizations, etc). If it would be used only to indicate backward >> incompatibility, we'd be in ODP 15.0 in couple of months... Similarly I see >> that after 1.0 comes 1.1 (2.0 would be major rework of the whole thing). >> >> So, first two digits indicate (potential) backward incompatibility. Third >> one can be used for backward compatible changes (small additions, bug >> fixes, missing doxygen comments, documentation bugs, white spaces, etc). >> The point being that if all three are the same, it's 100% the same. If >> first two are the same, application compiles and runs without any change. >> >> -Petri >> >> >> > -----Original Message----- >> > From: ext Taras Kondratiuk [mailto:taras.kondratiuk@linaro.org] >> > Sent: Wednesday, September 10, 2014 6:10 PM >> > To: Ola Liljedahl; Mike Holmes >> > Cc: Savolainen, Petri (NSN - FI/Espoo); Taras Kondratiuk; lng- >> > odp@lists.linaro.org >> > Subject: Re: [lng-odp] [PATCH] linux-generic: version: Add macros to >> > compare ODP versions >> > >> > On 09/10/2014 05:35 PM, Ola Liljedahl wrote: >> > > I think we should separate between ODP implementations and the ODP >> API. >> > > Users (applications) are primarily interested in the API. Any API >> > > changes can be separated into backwards and not backwards compatible >> > > changes. I think a major.minor designation for the ODP API is >> sufficient >> > > (there is no patch level of the API specification or?). The major >> number >> > > changes for any incompatible changes (with minor number reset), the >> > > minor number changes for any backwards compatible change (with major >> > > number kept). Small or big change is not relevant. >> > >> > I had in mind a bit different schema: major.minor.sub. >> > - 'major.minor' is an official ODP release version, like v1.0 we are >> > going to have by EOY. >> > - 'sub' is a version that must be incremented on each incompatible >> > API change (syntax or semantics) between releases. It is reset on >> > each major.minor change. >> > >> > IMO there is no point to change API version for backward compatible >> > changes. >> > >> > > >> > > One can imagine an application that attempts to handle changes (bugs >> and >> > > bug fixes) in the ODP implementation by checking which version >> > > (including the C number as defined below) the implementation is at. >> But >> > > this will be difficult with ODP since there will be multiple >> > > implementations and those can and will likely have different version >> > > sequences. The application would also need a mean to identify which >> ODP >> > > implementation it is using. >> > >> > Currently ODP_VERSION_API* macros address only API versions. >> > Adding versions for implementation is a separate story. To use it we >> > may need a way for application to detect which implementation is used. >> > Maybe expose define like ODP_PLATFORM_LINUX_GENERIC. >> > >
I agree with this proposal. Some clarification needed. The ODP API major.minor version will only change at well-defined release points, not for every commit. Between releases, the API may change (including incompatible changes) without this being reflected in the API version. - Ola On 23 September 2014 22:53, Mike Holmes <mike.holmes@linaro.org> wrote: > Is there any follow on from connect on this thread ? > I realise Taras is out but can we all converge on the final wording for a > three level configuration ? > All this is from the application writers perspective and not from the > PLATFORM implementers perspective, it ONLY describes the API, not > infrastructure changes. > > 'major.minor.sub ' > > The *major* digit is the ODP API generation. > It would be used generally to indicate backward incompatibility, a change > to this digit will break backwards compatibility > > - Altering API signature > - Altering a structure > - Changing the required calling sequence for APIs > - Changes to the installed structure > - New element to an enum that is an output from ODP > > The *minor* digit is for changes that are probably backwards compatible. > Things such as the the addition of a new API. Existing application code > probably does not have to change. > Any existing app should not need to change any calls and it should > continue to compile with the new ODP API version > > - Adding a new struct > - Adding a new function > - Adding an additional alternate API to an existing one. > - New element to an enum that is an input to ODP > > *The first two digits indicate (potential) backward incompatibility, only > ODP (the community) can update these two numbers. * > > The *sub* digit is used for backward compatible changes > Any existing app should work as before with the caveat that a bug fix may > change the executable behavior (hopefully improve it) > > - Optimize the implementation > - Documentation updates > - Whitespace > - bug fixes in implementation > > > > On 11 September 2014 09:00, Ola Liljedahl <ola.liljedahl@linaro.org> > wrote: > >> Taras: >> - 'sub' is a version that must be incremented on each *incompatible* >> API change (syntax or semantics) between releases. It is reset on >> each major.minor change. >> You mean "compatible"? >> >> I think it makes sense to change the API version also when making >> backwards compatible changes. E.g. if we are adding a function or some >> parameter flag but this is not worthy of a major.minor increment. An >> application might want to know if a specific function or feature is >> available. >> >> Petri: >> This is not equivalent to Mike's description where only the major number >> would be changed for incompatible changes where you write that the first >> two digits (or numbers) indicate (potential) backward incompatibility. >> >> I think your definition is the best. I also think the description needs >> to include what promises are made to the users (the applications), e.g. >> your two last sentences, otherwise the definition is going to be too >> abstract and we will come back and argue what the version numbers really >> means. In the mean time, changes will have been made that violate the >> versioning scheme. >> >> >> >> On 11 September 2014 09:25, Savolainen, Petri (NSN - FI/Espoo) < >> petri.savolainen@nsn.com> wrote: >> >>> Hi, >>> >>> Agree with Taras on three levels. It's there in odp_version.h already, >>> but we may need to revise the comments a bit. >>> >>> The main digit must be reserved for ODP API generations (major >>> reorganizations, etc). If it would be used only to indicate backward >>> incompatibility, we'd be in ODP 15.0 in couple of months... Similarly I see >>> that after 1.0 comes 1.1 (2.0 would be major rework of the whole thing). >>> >>> So, first two digits indicate (potential) backward incompatibility. >>> Third one can be used for backward compatible changes (small additions, bug >>> fixes, missing doxygen comments, documentation bugs, white spaces, etc). >>> The point being that if all three are the same, it's 100% the same. If >>> first two are the same, application compiles and runs without any change. >>> >>> -Petri >>> >>> >>> > -----Original Message----- >>> > From: ext Taras Kondratiuk [mailto:taras.kondratiuk@linaro.org] >>> > Sent: Wednesday, September 10, 2014 6:10 PM >>> > To: Ola Liljedahl; Mike Holmes >>> > Cc: Savolainen, Petri (NSN - FI/Espoo); Taras Kondratiuk; lng- >>> > odp@lists.linaro.org >>> > Subject: Re: [lng-odp] [PATCH] linux-generic: version: Add macros to >>> > compare ODP versions >>> > >>> > On 09/10/2014 05:35 PM, Ola Liljedahl wrote: >>> > > I think we should separate between ODP implementations and the ODP >>> API. >>> > > Users (applications) are primarily interested in the API. Any API >>> > > changes can be separated into backwards and not backwards compatible >>> > > changes. I think a major.minor designation for the ODP API is >>> sufficient >>> > > (there is no patch level of the API specification or?). The major >>> number >>> > > changes for any incompatible changes (with minor number reset), the >>> > > minor number changes for any backwards compatible change (with major >>> > > number kept). Small or big change is not relevant. >>> > >>> > I had in mind a bit different schema: major.minor.sub. >>> > - 'major.minor' is an official ODP release version, like v1.0 we are >>> > going to have by EOY. >>> > - 'sub' is a version that must be incremented on each incompatible >>> > API change (syntax or semantics) between releases. It is reset on >>> > each major.minor change. >>> > >>> > IMO there is no point to change API version for backward compatible >>> > changes. >>> > >>> > > >>> > > One can imagine an application that attempts to handle changes (bugs >>> and >>> > > bug fixes) in the ODP implementation by checking which version >>> > > (including the C number as defined below) the implementation is at. >>> But >>> > > this will be difficult with ODP since there will be multiple >>> > > implementations and those can and will likely have different version >>> > > sequences. The application would also need a mean to identify which >>> ODP >>> > > implementation it is using. >>> > >>> > Currently ODP_VERSION_API* macros address only API versions. >>> > Adding versions for implementation is a separate story. To use it we >>> > may need a way for application to detect which implementation is used. >>> > Maybe expose define like ODP_PLATFORM_LINUX_GENERIC. >>> >> >> > > > -- > *Mike Holmes* > Linaro Technical Manager / Lead > LNG - ODP >
On 24 Sep 2014 14:52, "Ola Liljedahl" <ola.liljedahl@linaro.org> wrote: > > I agree with this proposal. Some clarification needed. The ODP API major.minor version will only change at well-defined release points, not for every commit. Between releases, the API may change (including incompatible changes) without this being reflected in the API version. Yes! > > - Ola > > > On 23 September 2014 22:53, Mike Holmes <mike.holmes@linaro.org> wrote: >> >> Is there any follow on from connect on this thread ? >> I realise Taras is out but can we all converge on the final wording for a three level configuration ? >> All this is from the application writers perspective and not from the PLATFORM implementers perspective, it ONLY describes the API, not infrastructure changes. >> >> 'major.minor.sub ' >> >> The major digit is the ODP API generation. >> It would be used generally to indicate backward incompatibility, a change to this digit will break backwards compatibility >> Altering API signature >> Altering a structure >> Changing the required calling sequence for APIs >> Changes to the installed structure >> New element to an enum that is an output from ODP >> The minor digit is for changes that are probably backwards compatible. >> Things such as the the addition of a new API. Existing application code probably does not have to change. >> Any existing app should not need to change any calls and it should continue to compile with the new ODP API version >> Adding a new struct >> Adding a new function >> Adding an additional alternate API to an existing one. >> New element to an enum that is an input to ODP >> The first two digits indicate (potential) backward incompatibility, only ODP (the community) can update these two numbers. >> >> The sub digit is used for backward compatible changes >> Any existing app should work as before with the caveat that a bug fix may change the executable behavior (hopefully improve it) >> Optimize the implementation >> Documentation updates >> Whitespace >> bug fixes in implementation >> >> >> On 11 September 2014 09:00, Ola Liljedahl <ola.liljedahl@linaro.org> wrote: >>> >>> Taras: >>> - 'sub' is a version that must be incremented on each incompatible >>> API change (syntax or semantics) between releases. It is reset on >>> each major.minor change. >>> You mean "compatible"? >>> >>> I think it makes sense to change the API version also when making backwards compatible changes. E.g. if we are adding a function or some parameter flag but this is not worthy of a major.minor increment. An application might want to know if a specific function or feature is available. >>> >>> Petri: >>> This is not equivalent to Mike's description where only the major number would be changed for incompatible changes where you write that the first two digits (or numbers) indicate (potential) backward incompatibility. >>> >>> I think your definition is the best. I also think the description needs to include what promises are made to the users (the applications), e.g. your two last sentences, otherwise the definition is going to be too abstract and we will come back and argue what the version numbers really means. In the mean time, changes will have been made that violate the versioning scheme. >>> >>> >>> >>> On 11 September 2014 09:25, Savolainen, Petri (NSN - FI/Espoo) < petri.savolainen@nsn.com> wrote: >>>> >>>> Hi, >>>> >>>> Agree with Taras on three levels. It's there in odp_version.h already, but we may need to revise the comments a bit. >>>> >>>> The main digit must be reserved for ODP API generations (major reorganizations, etc). If it would be used only to indicate backward incompatibility, we'd be in ODP 15.0 in couple of months... Similarly I see that after 1.0 comes 1.1 (2.0 would be major rework of the whole thing). >>>> >>>> So, first two digits indicate (potential) backward incompatibility. Third one can be used for backward compatible changes (small additions, bug fixes, missing doxygen comments, documentation bugs, white spaces, etc). The point being that if all three are the same, it's 100% the same. If first two are the same, application compiles and runs without any change. >>>> >>>> -Petri >>>> >>>> >>>> > -----Original Message----- >>>> > From: ext Taras Kondratiuk [mailto:taras.kondratiuk@linaro.org] >>>> > Sent: Wednesday, September 10, 2014 6:10 PM >>>> > To: Ola Liljedahl; Mike Holmes >>>> > Cc: Savolainen, Petri (NSN - FI/Espoo); Taras Kondratiuk; lng- >>>> > odp@lists.linaro.org >>>> > Subject: Re: [lng-odp] [PATCH] linux-generic: version: Add macros to >>>> > compare ODP versions >>>> > >>>> > On 09/10/2014 05:35 PM, Ola Liljedahl wrote: >>>> > > I think we should separate between ODP implementations and the ODP API. >>>> > > Users (applications) are primarily interested in the API. Any API >>>> > > changes can be separated into backwards and not backwards compatible >>>> > > changes. I think a major.minor designation for the ODP API is sufficient >>>> > > (there is no patch level of the API specification or?). The major number >>>> > > changes for any incompatible changes (with minor number reset), the >>>> > > minor number changes for any backwards compatible change (with major >>>> > > number kept). Small or big change is not relevant. >>>> > >>>> > I had in mind a bit different schema: major.minor.sub. >>>> > - 'major.minor' is an official ODP release version, like v1.0 we are >>>> > going to have by EOY. >>>> > - 'sub' is a version that must be incremented on each incompatible >>>> > API change (syntax or semantics) between releases. It is reset on >>>> > each major.minor change. >>>> > >>>> > IMO there is no point to change API version for backward compatible >>>> > changes. >>>> > >>>> > > >>>> > > One can imagine an application that attempts to handle changes (bugs and >>>> > > bug fixes) in the ODP implementation by checking which version >>>> > > (including the C number as defined below) the implementation is at. But >>>> > > this will be difficult with ODP since there will be multiple >>>> > > implementations and those can and will likely have different version >>>> > > sequences. The application would also need a mean to identify which ODP >>>> > > implementation it is using. >>>> > >>>> > Currently ODP_VERSION_API* macros address only API versions. >>>> > Adding versions for implementation is a separate story. To use it we >>>> > may need a way for application to detect which implementation is used. >>>> > Maybe expose define like ODP_PLATFORM_LINUX_GENERIC. >>> >>> >> >> >> >> -- >> Mike Holmes >> Linaro Technical Manager / Lead >> LNG - ODP > > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
diff --git a/platform/linux-generic/include/api/odp_version.h b/platform/linux-generic/include/api/odp_version.h index c823e2d..97f8e26 100644 --- a/platform/linux-generic/include/api/odp_version.h +++ b/platform/linux-generic/include/api/odp_version.h @@ -44,6 +44,22 @@ extern "C" { */ #define ODP_VERSION_API_BUG 1 +/** + * Macro to merge three parts of ODP API version into one word + * + * Merge ODP version into one word: + * byte 0 - bug correction version + * byte 1 - sub version + * byte 2 - main version + */ +#define ODP_VERSION(a, b, c) (((a) << 16) + ((b) << 8) + (c)) + +/** + * Current version of ODP API in one word form + */ +#define ODP_VERSION_API ODP_VERSION((ODP_VERSION_API_MAIN), \ + (ODP_VERSION_API_SUB), \ + (ODP_VERSION_API_BUG)) /** @internal Version string expand */ #define ODP_VERSION_STR_EXPAND(x) #x