Message went to tsc-bounces instead of tsc list.
-----Original Message-----
From: Arnaud POULIQUEN <arnaud.pouliquen(a)st.com>
Sent: Tuesday, May 19, 2020 8:50 AM
To: Mills, William <wmills(a)ti.com>
Cc: tsc-bounces(a)lists.openampproject.org
Subject: RE: API and Wire protocol stability
Hi Bill, all
Thanks Bill for this proposal. Look to me a good approach.
Could version number management in openAMP help applications to better manage API and Wire protocol evolution?
Today the status is:
- libmetal: API fo get lib version exists ( MAJOR.MINOR.PATCH format) but no evolution of the version since a while: Current version 0.1.0
- OpenAMP: version only handled for Zephyr with same format than libmetal, no API to get the library version. Current version 0.1.0
Another point, probably quite out of scope here, but reviewing this policy reminds me some of the requirements that were defined when we started the OpenAMP library redesign in 2018.
- The first was the library's memory footprint. This requirement was a condition for the viability of OpenAMP on
MCU with low memory. The target was 3 kB for the ROM. Today, we are close to ( but higher than) this target. And the footprint continue to grow by adding
fixes and new features. For instance, the cost of integrating the "zero copy" feature is about 0.5 KB.
- The second was the support of systems without dynamic allocation. Today, I think we are still meeting this requirement.
I wonder whether these requirements should not be reshaped in policies, as they also have an impact on the evolution of the library.
So I would appreciate if we can also clarify this 2 points, (after the API and wire protocol policies, of course :) )
Thanks
Arnaud
> -----Original Message-----
> From: Tsc <tsc-bounces(a)lists.openampproject.org> On Behalf Of Mills,
> William via Tsc
> Sent: samedi 18 avril 2020 17:41
> To: tsc(a)lists.openampproject.org
> Subject: [OA-Tsc] API and Wire protocol stability
>
> All,
>
> I have the action to write up thought on API stability.
> On 4/17 we added wire protocol stability to the list.
> There is also discussion of API homogeneity across different
> implementations and/or operating environments but that topic is out of
> scope for this discussion and I specifically opted out of leading that
> discussion.
>
> **** API Stability:
>
> For reference here is the Zephyr policy on API lifecycle:
> https://docs.zephyrproject.org/latest/development_process/api_lifecycle.h
> tml
>
> ** Scope:
>
> The scope of the OpenAMP API lifecycle policy is mostly the libraries and
> supporting code owned by the project.
> Today that is primarily the open-amp and libmetal libraries but we expect
> that to expand in the future.
>
> Specifically out of scope would be the APIs internal to the Linux kernel. The
> Linux kernel has a famous "no stable api" policy.
> Probably also out of scope would be the kernel / user interface. This
> interface has a more stringent "don't break the user interface policy" than
> will be described here.
>
> Nothing prevents us from trying to apply our policies to the Linux kernel on a
> best effort basis but we need to understand the kernel's policies will
> override ours in a conflict.
>
> ** Why have a policy?:
>
> One possible policy is to have no policy or a weak one. Under such a policy,
> If someone is using the old API's, let then use the old version of the library.
> When they want to upgrade to a new version, they should upgrade to the
> new APIs as well.
>
> I don't think a weak policy is wise. We are a small project and don't want to
> maintain and test many versions of the libraries. To date we don't have an
> LTS policy and I think it would be good if we did not have to go there. A
> strong API stability statement means that users can pick up bug fixes, new
> platforms and even some new features without having to change [much] of
> their application/system. Even if we define an LTS policy a stable API policy
> lowers the barrier to pick up that one new feature you need.
>
> ** Comments on the Zephyr policy:
>
> OpenAMP is a smaller project than Zephyr so I think we can simplify the
> model a bit.
> Certainly we want the API states of stable, deprecated, and removed.
> I don't see any need to have two states before stable.
> "Experimental" APIs should not be in the release branches, they should be in
> experimental branches or git repo forks.
> You could say the same for "Unstable" but there are valid reasons to include
> it as well.
>
> The Zephyr policy says things stay in depreciated state for 2 releases. Zephyr
> makes releases ~ 2 times per year. So applications have to upgrade versions
> at least once a year to have any benefit from the policy. This seems very
> short to me. A 2 year depreciation stay seems more appropriate to me.
> Another approach would be to specify a minimum and a maximum time in
> deprecated state. Things that are easy to keep can stay for the max time and
> things that cause big headaches to maintain can stay for the minimum time.
>
> ** Mechanism of compatibility
>
> As with the Zephyr policy we are focused on source level compatibility. It is
> acceptable if the user has to recompile his application to use the new library
> version.
>
> Maintaining a binary level API (more correctly an ABI) is a decent amount of
> extra work. If we do have Linux shared libraries that get commonly used we
> will need to look at this. However, I suggest we tackle that issues as it arises.
> (A static library does not have the same issue)
>
> **** Wire Protocol Stability:
>
> The wire protocol describes the interactions of two independent CPUs in an
> AMP system. The bar for maintaining compatibility at this level is much
> higher.
>
> Some random thoughts/suggestions:
>
> (I am using "firmware" and "kernel" as stand-ins for the more general cases
> also)
>
> * break of compatibility of the protocol level should require TSC approval
> * New kernels should run old firmware
> * New firmware that has extra features with new kernels should still work
> with old kernels if that is desired
> * We need to know what properties of interaction are guaranteed vs just
> how the current implementation works today
> ** We need a protocol document
> ** Until we do, we have to treat current UPSTREAM model as the defacto
> standard
> ** We can't really have protocol compatibility states until we have a protocol
> document
> ** Anything currently only in vendor branches is considered Experimental
> * New Protocol features and versions are best if they can be discovered live
> ** However manual opt-in by both parties is acceptable as a fallback
>
> Thanks,
> Bill
>
>
> ---------------------------------------------------
> William A. Mills
> Chief Technologist, Open Source
> Texas Instruments, Processors
> 20250 Century Blvd, Suit 300
> Germantown MD, 20874
> (work/mobile) +1-240-643-0836
>
>
> --
> Tsc mailing list
> Tsc(a)lists.openampproject.org
> https://lists.openampproject.org/mailman/listinfo/tsc
Grant,
On 5/18/20 12:09 PM, Grant Likely via Tsc wrote:
> Hi Bill,
>
> I don't have particularly strong opinions on the details of the policy.
> I do agree it is important to start with something (can be adjusted as
> the project goes along if necessary). Agree that being firm on wire
> protocol stability (and I think versioning) is very important, and
> you're thoughts on simplifying the Zepher model sound sensible.
>
> I would err toward not removing APIs, or moving them to a libcompat as
> wrappers to their replacements. The latter approach has a nice benefit
> of making it obvious when an API layer is no longer the preferred
> interface because the compat lib needs to be linked in.
>
Yes I agree. I think moving to libcompat should be strongly recommended.
Thanks for the review.
-- Bill
> g.
>
> On 14/05/2020 08:22, Nathalie Chan King Choy via Tsc wrote:
>> Hi all,
>>
>> In today's TSC call, the suggestion was to continue this discussion
>> over email
>> & then come to a decision during the July TSC call.
>>
>> Thanks & regards,
>> Nathalie
>>
>>> -----Original Message-----
>>> From: Tsc <tsc-bounces(a)lists.openampproject.org> On Behalf Of Mills,
>>> William via Tsc
>>> Sent: Saturday, April 18, 2020 8:41 AM
>>> To: tsc(a)lists.openampproject.org
>>> Subject: [OA-Tsc] API and Wire protocol stability
>>>
>>> CAUTION: This message has originated from an External Source. Please use
>>> proper judgment and caution when opening attachments, clicking links, or
>>> responding to this email.
>>>
>>>
>>> All,
>>>
>>> I have the action to write up thought on API stability.
>>> On 4/17 we added wire protocol stability to the list.
>>> There is also discussion of API homogeneity across different
>>> implementations and/or operating environments but that topic is out of
>>> scope for this discussion and I specifically opted out of leading that
>>> discussion.
>>>
>>> **** API Stability:
>>>
>>> For reference here is the Zephyr policy on API lifecycle:
>>> https://docs.zephyrproject.org/latest/development_process/api_lifecycle.html
>>>
>>>
>>> ** Scope:
>>>
>>> The scope of the OpenAMP API lifecycle policy is mostly the libraries
>>> and
>>> supporting code owned by the project.
>>> Today that is primarily the open-amp and libmetal libraries but we
>>> expect
>>> that to expand in the future.
>>>
>>> Specifically out of scope would be the APIs internal to the Linux
>>> kernel. The
>>> Linux kernel has a famous "no stable api" policy.
>>> Probably also out of scope would be the kernel / user interface. This
>>> interface has a more stringent "don't break the user interface
>>> policy" than
>>> will be described here.
>>>
>>> Nothing prevents us from trying to apply our policies to the Linux
>>> kernel on a
>>> best effort basis but we need to understand the kernel's policies will
>>> override ours in a conflict.
>>>
>>> ** Why have a policy?:
>>>
>>> One possible policy is to have no policy or a weak one. Under such a
>>> policy,
>>> If someone is using the old API's, let then use the old version of
>>> the library.
>>> When they want to upgrade to a new version, they should upgrade to the
>>> new APIs as well.
>>>
>>> I don't think a weak policy is wise. We are a small project and
>>> don't want to
>>> maintain and test many versions of the libraries. To date we don't
>>> have an
>>> LTS policy and I think it would be good if we did not have to go
>>> there. A
>>> strong API stability statement means that users can pick up bug
>>> fixes, new
>>> platforms and even some new features without having to change [much] of
>>> their application/system. Even if we define an LTS policy a stable
>>> API policy
>>> lowers the barrier to pick up that one new feature you need.
>>>
>>> ** Comments on the Zephyr policy:
>>>
>>> OpenAMP is a smaller project than Zephyr so I think we can simplify the
>>> model a bit.
>>> Certainly we want the API states of stable, deprecated, and removed.
>>> I don't see any need to have two states before stable.
>>> "Experimental" APIs should not be in the release branches, they
>>> should be in
>>> experimental branches or git repo forks.
>>> You could say the same for "Unstable" but there are valid reasons to
>>> include
>>> it as well.
>>>
>>> The Zephyr policy says things stay in depreciated state for 2
>>> releases. Zephyr
>>> makes releases ~ 2 times per year. So applications have to upgrade
>>> versions
>>> at least once a year to have any benefit from the policy. This seems
>>> very
>>> short to me. A 2 year depreciation stay seems more appropriate to me.
>>> Another approach would be to specify a minimum and a maximum time in
>>> deprecated state. Things that are easy to keep can stay for the max
>>> time and
>>> things that cause big headaches to maintain can stay for the minimum
>>> time.
>>>
>>> ** Mechanism of compatibility
>>>
>>> As with the Zephyr policy we are focused on source level
>>> compatibility. It is
>>> acceptable if the user has to recompile his application to use the
>>> new library
>>> version.
>>>
>>> Maintaining a binary level API (more correctly an ABI) is a decent
>>> amount of
>>> extra work. If we do have Linux shared libraries that get commonly
>>> used we
>>> will need to look at this. However, I suggest we tackle that issues
>>> as it arises.
>>> (A static library does not have the same issue)
>>>
>>> **** Wire Protocol Stability:
>>>
>>> The wire protocol describes the interactions of two independent CPUs
>>> in an
>>> AMP system. The bar for maintaining compatibility at this level is much
>>> higher.
>>>
>>> Some random thoughts/suggestions:
>>>
>>> (I am using "firmware" and "kernel" as stand-ins for the more general
>>> cases
>>> also)
>>>
>>> * break of compatibility of the protocol level should require TSC
>>> approval
>>> * New kernels should run old firmware
>>> * New firmware that has extra features with new kernels should still
>>> work
>>> with old kernels if that is desired
>>> * We need to know what properties of interaction are guaranteed vs just
>>> how the current implementation works today
>>> ** We need a protocol document
>>> ** Until we do, we have to treat current UPSTREAM model as the defacto
>>> standard
>>> ** We can't really have protocol compatibility states until we have a
>>> protocol
>>> document
>>> ** Anything currently only in vendor branches is considered Experimental
>>> * New Protocol features and versions are best if they can be
>>> discovered live
>>> ** However manual opt-in by both parties is acceptable as a fallback
>>>
>>> Thanks,
>>> Bill
>>>
>>>
>>> ---------------------------------------------------
>>> William A. Mills
>>> Chief Technologist, Open Source
>>> Texas Instruments, Processors
>>> 20250 Century Blvd, Suit 300
>>> Germantown MD, 20874
>>> (work/mobile) +1-240-643-0836
>>>
>>>
>>> --
>>> Tsc mailing list
>>> Tsc(a)lists.openampproject.org
>>> https://lists.openampproject.org/mailman/listinfo/tsc
> IMPORTANT NOTICE: The contents of this email and any attachments are
> confidential and may also be privileged. If you are not the intended
> recipient, please notify the sender immediately and do not disclose the
> contents to any other person, use it for any purpose, or store or copy
> the information in any medium. Thank you.
Hi Bill,
I don't have particularly strong opinions on the details of the policy.
I do agree it is important to start with something (can be adjusted as
the project goes along if necessary). Agree that being firm on wire
protocol stability (and I think versioning) is very important, and
you're thoughts on simplifying the Zepher model sound sensible.
I would err toward not removing APIs, or moving them to a libcompat as
wrappers to their replacements. The latter approach has a nice benefit
of making it obvious when an API layer is no longer the preferred
interface because the compat lib needs to be linked in.
g.
On 14/05/2020 08:22, Nathalie Chan King Choy via Tsc wrote:
> Hi all,
>
> In today's TSC call, the suggestion was to continue this discussion over email
> & then come to a decision during the July TSC call.
>
> Thanks & regards,
> Nathalie
>
>> -----Original Message-----
>> From: Tsc <tsc-bounces(a)lists.openampproject.org> On Behalf Of Mills,
>> William via Tsc
>> Sent: Saturday, April 18, 2020 8:41 AM
>> To: tsc(a)lists.openampproject.org
>> Subject: [OA-Tsc] API and Wire protocol stability
>>
>> CAUTION: This message has originated from an External Source. Please use
>> proper judgment and caution when opening attachments, clicking links, or
>> responding to this email.
>>
>>
>> All,
>>
>> I have the action to write up thought on API stability.
>> On 4/17 we added wire protocol stability to the list.
>> There is also discussion of API homogeneity across different
>> implementations and/or operating environments but that topic is out of
>> scope for this discussion and I specifically opted out of leading that
>> discussion.
>>
>> **** API Stability:
>>
>> For reference here is the Zephyr policy on API lifecycle:
>> https://docs.zephyrproject.org/latest/development_process/api_lifecycle.html
>>
>> ** Scope:
>>
>> The scope of the OpenAMP API lifecycle policy is mostly the libraries and
>> supporting code owned by the project.
>> Today that is primarily the open-amp and libmetal libraries but we expect
>> that to expand in the future.
>>
>> Specifically out of scope would be the APIs internal to the Linux kernel. The
>> Linux kernel has a famous "no stable api" policy.
>> Probably also out of scope would be the kernel / user interface. This
>> interface has a more stringent "don't break the user interface policy" than
>> will be described here.
>>
>> Nothing prevents us from trying to apply our policies to the Linux kernel on a
>> best effort basis but we need to understand the kernel's policies will
>> override ours in a conflict.
>>
>> ** Why have a policy?:
>>
>> One possible policy is to have no policy or a weak one. Under such a policy,
>> If someone is using the old API's, let then use the old version of the library.
>> When they want to upgrade to a new version, they should upgrade to the
>> new APIs as well.
>>
>> I don't think a weak policy is wise. We are a small project and don't want to
>> maintain and test many versions of the libraries. To date we don't have an
>> LTS policy and I think it would be good if we did not have to go there. A
>> strong API stability statement means that users can pick up bug fixes, new
>> platforms and even some new features without having to change [much] of
>> their application/system. Even if we define an LTS policy a stable API policy
>> lowers the barrier to pick up that one new feature you need.
>>
>> ** Comments on the Zephyr policy:
>>
>> OpenAMP is a smaller project than Zephyr so I think we can simplify the
>> model a bit.
>> Certainly we want the API states of stable, deprecated, and removed.
>> I don't see any need to have two states before stable.
>> "Experimental" APIs should not be in the release branches, they should be in
>> experimental branches or git repo forks.
>> You could say the same for "Unstable" but there are valid reasons to include
>> it as well.
>>
>> The Zephyr policy says things stay in depreciated state for 2 releases. Zephyr
>> makes releases ~ 2 times per year. So applications have to upgrade versions
>> at least once a year to have any benefit from the policy. This seems very
>> short to me. A 2 year depreciation stay seems more appropriate to me.
>> Another approach would be to specify a minimum and a maximum time in
>> deprecated state. Things that are easy to keep can stay for the max time and
>> things that cause big headaches to maintain can stay for the minimum time.
>>
>> ** Mechanism of compatibility
>>
>> As with the Zephyr policy we are focused on source level compatibility. It is
>> acceptable if the user has to recompile his application to use the new library
>> version.
>>
>> Maintaining a binary level API (more correctly an ABI) is a decent amount of
>> extra work. If we do have Linux shared libraries that get commonly used we
>> will need to look at this. However, I suggest we tackle that issues as it arises.
>> (A static library does not have the same issue)
>>
>> **** Wire Protocol Stability:
>>
>> The wire protocol describes the interactions of two independent CPUs in an
>> AMP system. The bar for maintaining compatibility at this level is much
>> higher.
>>
>> Some random thoughts/suggestions:
>>
>> (I am using "firmware" and "kernel" as stand-ins for the more general cases
>> also)
>>
>> * break of compatibility of the protocol level should require TSC approval
>> * New kernels should run old firmware
>> * New firmware that has extra features with new kernels should still work
>> with old kernels if that is desired
>> * We need to know what properties of interaction are guaranteed vs just
>> how the current implementation works today
>> ** We need a protocol document
>> ** Until we do, we have to treat current UPSTREAM model as the defacto
>> standard
>> ** We can't really have protocol compatibility states until we have a protocol
>> document
>> ** Anything currently only in vendor branches is considered Experimental
>> * New Protocol features and versions are best if they can be discovered live
>> ** However manual opt-in by both parties is acceptable as a fallback
>>
>> Thanks,
>> Bill
>>
>>
>> ---------------------------------------------------
>> William A. Mills
>> Chief Technologist, Open Source
>> Texas Instruments, Processors
>> 20250 Century Blvd, Suit 300
>> Germantown MD, 20874
>> (work/mobile) +1-240-643-0836
>>
>>
>> --
>> Tsc mailing list
>> Tsc(a)lists.openampproject.org
>> https://lists.openampproject.org/mailman/listinfo/tsc
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
Hi all,
In today's TSC call, the suggestion was to continue this discussion over email
& then come to a decision during the July TSC call.
Thanks & regards,
Nathalie
> -----Original Message-----
> From: Tsc <tsc-bounces(a)lists.openampproject.org> On Behalf Of Mills,
> William via Tsc
> Sent: Saturday, April 18, 2020 8:41 AM
> To: tsc(a)lists.openampproject.org
> Subject: [OA-Tsc] API and Wire protocol stability
>
> CAUTION: This message has originated from an External Source. Please use
> proper judgment and caution when opening attachments, clicking links, or
> responding to this email.
>
>
> All,
>
> I have the action to write up thought on API stability.
> On 4/17 we added wire protocol stability to the list.
> There is also discussion of API homogeneity across different
> implementations and/or operating environments but that topic is out of
> scope for this discussion and I specifically opted out of leading that
> discussion.
>
> **** API Stability:
>
> For reference here is the Zephyr policy on API lifecycle:
> https://docs.zephyrproject.org/latest/development_process/api_lifecycle.html
>
> ** Scope:
>
> The scope of the OpenAMP API lifecycle policy is mostly the libraries and
> supporting code owned by the project.
> Today that is primarily the open-amp and libmetal libraries but we expect
> that to expand in the future.
>
> Specifically out of scope would be the APIs internal to the Linux kernel. The
> Linux kernel has a famous "no stable api" policy.
> Probably also out of scope would be the kernel / user interface. This
> interface has a more stringent "don't break the user interface policy" than
> will be described here.
>
> Nothing prevents us from trying to apply our policies to the Linux kernel on a
> best effort basis but we need to understand the kernel's policies will
> override ours in a conflict.
>
> ** Why have a policy?:
>
> One possible policy is to have no policy or a weak one. Under such a policy,
> If someone is using the old API's, let then use the old version of the library.
> When they want to upgrade to a new version, they should upgrade to the
> new APIs as well.
>
> I don't think a weak policy is wise. We are a small project and don't want to
> maintain and test many versions of the libraries. To date we don't have an
> LTS policy and I think it would be good if we did not have to go there. A
> strong API stability statement means that users can pick up bug fixes, new
> platforms and even some new features without having to change [much] of
> their application/system. Even if we define an LTS policy a stable API policy
> lowers the barrier to pick up that one new feature you need.
>
> ** Comments on the Zephyr policy:
>
> OpenAMP is a smaller project than Zephyr so I think we can simplify the
> model a bit.
> Certainly we want the API states of stable, deprecated, and removed.
> I don't see any need to have two states before stable.
> "Experimental" APIs should not be in the release branches, they should be in
> experimental branches or git repo forks.
> You could say the same for "Unstable" but there are valid reasons to include
> it as well.
>
> The Zephyr policy says things stay in depreciated state for 2 releases. Zephyr
> makes releases ~ 2 times per year. So applications have to upgrade versions
> at least once a year to have any benefit from the policy. This seems very
> short to me. A 2 year depreciation stay seems more appropriate to me.
> Another approach would be to specify a minimum and a maximum time in
> deprecated state. Things that are easy to keep can stay for the max time and
> things that cause big headaches to maintain can stay for the minimum time.
>
> ** Mechanism of compatibility
>
> As with the Zephyr policy we are focused on source level compatibility. It is
> acceptable if the user has to recompile his application to use the new library
> version.
>
> Maintaining a binary level API (more correctly an ABI) is a decent amount of
> extra work. If we do have Linux shared libraries that get commonly used we
> will need to look at this. However, I suggest we tackle that issues as it arises.
> (A static library does not have the same issue)
>
> **** Wire Protocol Stability:
>
> The wire protocol describes the interactions of two independent CPUs in an
> AMP system. The bar for maintaining compatibility at this level is much
> higher.
>
> Some random thoughts/suggestions:
>
> (I am using "firmware" and "kernel" as stand-ins for the more general cases
> also)
>
> * break of compatibility of the protocol level should require TSC approval
> * New kernels should run old firmware
> * New firmware that has extra features with new kernels should still work
> with old kernels if that is desired
> * We need to know what properties of interaction are guaranteed vs just
> how the current implementation works today
> ** We need a protocol document
> ** Until we do, we have to treat current UPSTREAM model as the defacto
> standard
> ** We can't really have protocol compatibility states until we have a protocol
> document
> ** Anything currently only in vendor branches is considered Experimental
> * New Protocol features and versions are best if they can be discovered live
> ** However manual opt-in by both parties is acceptable as a fallback
>
> Thanks,
> Bill
>
>
> ---------------------------------------------------
> William A. Mills
> Chief Technologist, Open Source
> Texas Instruments, Processors
> 20250 Century Blvd, Suit 300
> Germantown MD, 20874
> (work/mobile) +1-240-643-0836
>
>
> --
> Tsc mailing list
> Tsc(a)lists.openampproject.org
> https://lists.openampproject.org/mailman/listinfo/tsc
Hi all,
You can find the notes at: https://github.com/OpenAMP/open-amp/wiki/TSC-Meeting-Notes-2020#20200512
If you attended, please check & update the notes if you spot any errors or important omissions.
Regarding one topic that came back up about Pull Requests, during the Feb TSC call, the official decision on that in Feb was:
Will continue to use GitHub PR flow for contributions. Ed & Arnaud should also submit PRs for what they commit.
So, basically no change to what was decided in Feb.
Action items:
* All: Continue API discussion by email
* Stefano & Bruce: Document System DT & Lopper goals in OpenAMP Wiki at https://github.com/OpenAMP/open-amp/wiki/Future-Topics-for-System-Device-Tr…
* Ed: Update the governance document to reflect what we're actually doing
* Ed to do gap analysis of OpenAMP documentation & look at using Sphinx
* Nathalie: Schedule next TSC call for July
Decisions
* Stefano officially voted in as the new leader of System DT OpenAMP working group
* Informal: OpenAMP releases to continue at cadence of 2x/year until there is a need to change
* Informal: Consider Sphinx for documentation instead of exhaustive analysis
Thanks & regards,
Nathalie C. Chan King Choy
Program Manager focused on Open Source & Community
resend
-----Original Message-----
From: Mills, William
Sent: Saturday, April 18, 2020 11:35 AM
To: tsc(a)lists.openampproject.org
Subject: API and Wire protocol stability
All,
I have the action to write up thought on API stability.
On 4/17 we added wire protocol stability to the list.
There is also discussion of API homogeneity across different implementations and/or operating environments but that topic is out of scope for this discussion and I specifically opted out of leading that discussion.
**** API Stability:
For reference here is the Zephyr policy on API lifecycle:
https://docs.zephyrproject.org/latest/development_process/api_lifecycle.html
** Scope:
The scope of the OpenAMP API lifecycle policy is mostly the libraries and supporting code owned by the project.
Today that is primarily the open-amp and libmetal libraries but we expect that to expand in the future.
Specifically out of scope would be the APIs internal to the Linux kernel. The Linux kernel has a famous "no stable api" policy.
Probably also out of scope would be the kernel / user interface. This interface has a more stringent "don't break the user interface policy" than will be described here.
Nothing prevents us from trying to apply our policies to the Linux kernel on a best effort basis but we need to understand the kernel's policies will override ours in a conflict.
** Why have a policy?:
One possible policy is to have no policy or a weak one. Under such a policy, If someone is using the old API's, let then use the old version of the library. When they want to upgrade to a new version, they should upgrade to the new APIs as well.
I don't think a weak policy is wise. We are a small project and don't want to maintain and test many versions of the libraries. To date we don't have an LTS policy and I think it would be good if we did not have to go there. A strong API stability statement means that users can pick up bug fixes, new platforms and even some new features without having to change [much] of their application/system. Even if we define an LTS policy a stable API policy lowers the barrier to pick up that one new feature you need.
** Comments on the Zephyr policy:
OpenAMP is a smaller project than Zephyr so I think we can simplify the model a bit.
Certainly we want the API states of stable, deprecated, and removed.
I don't see any need to have two states before stable.
"Experimental" APIs should not be in the release branches, they should be in experimental branches or git repo forks.
You could say the same for "Unstable" but there are valid reasons to include it as well.
The Zephyr policy says things stay in depreciated state for 2 releases. Zephyr makes releases ~ 2 times per year. So applications have to upgrade versions at least once a year to have any benefit from the policy. This seems very short to me. A 2 year depreciation stay seems more appropriate to me. Another approach would be to specify a minimum and a maximum time in deprecated state. Things that are easy to keep can stay for the max time and things that cause big headaches to maintain can stay for the minimum time.
** Mechanism of compatibility
As with the Zephyr policy we are focused on source level compatibility. It is acceptable if the user has to recompile his application to use the new library version.
Maintaining a binary level API (more correctly an ABI) is a decent amount of extra work. If we do have Linux shared libraries that get commonly used we will need to look at this. However, I suggest we tackle that issues as it arises. (A static library does not have the same issue)
**** Wire Protocol Stability:
The wire protocol describes the interactions of two independent CPUs in an AMP system. The bar for maintaining compatibility at this level is much higher.
Some random thoughts/suggestions:
(I am using "firmware" and "kernel" as stand-ins for the more general cases also)
* break of compatibility of the protocol level should require TSC approval
* New kernels should run old firmware
* New firmware that has extra features with new kernels should still work with old kernels if that is desired
* We need to know what properties of interaction are guaranteed vs just how the current implementation works today
** We need a protocol document
** Until we do, we have to treat current UPSTREAM model as the defacto standard
** We can't really have protocol compatibility states until we have a protocol document
** Anything currently only in vendor branches is considered Experimental
* New Protocol features and versions are best if they can be discovered live
** However manual opt-in by both parties is acceptable as a fallback
Thanks,
Bill
---------------------------------------------------
William A. Mills
Chief Technologist, Open Source
Texas Instruments, Processors
20250 Century Blvd, Suit 300
Germantown MD, 20874
(work/mobile) +1-240-643-0836
Hi all,
Please send your suggestions for agenda items. I have collected so far:
* Tomas, Maarten, Bill: Present working group goals/aspirations for next 6 months
* Bill: API stability & Zephyr policy
* Pick additional topics from Ed's Governance list. Options are:
* Selection of new features for development
* Testing
* Documentation
* Branching & tagging strategy
* Release process
Action items from last call are:
* Maarten/Dan: document the goals/aspirations for App Services group in Future and Current work pages in OpenAMP Wiki
* Tomas/Stefano/Bruce: document the goals/aspirations for System DT group in Future and Current work pages in OpenAMP Wiki
* Bill M: document the goals/aspirations for OpenAMP-rp group in Future and Current work pages in OpenAMP Wiki
* Bill M to write up the thoughts on API stability policy & point to the Zephyr policy
* Bill M volunteers to drive the topic of wire protocol stability.
Thanks & regards,
Nathalie
-----Original Appointment-----
Subject: OpenAMP TSC - May call
When: Tuesday, May 12, 2020 9:00 AM-10:00 AM (UTC-08:00) Pacific Time (US & Canada).
Where: Zoom
Hi all,
Please join on Zoom: https://zoom.us/my/openampproject
(If you need the meeting ID, it's 9031895760. I will email out the password directly to list members shortly before the call)
The notes from the previous call (April 17) can be found at https://github.com/OpenAMP/open-amp/wiki/TSC-Meeting-Notes-2020#20200417
For info about the list, link to the archives, to unsubscribe yourself, or for someone to subscribe themselves, visit:
https://lists.openampproject.org/mailman/listinfo/tsc
Best regards,
Nathalie C. Chan King Choy
Program Manager focused on Open Source and Community
Hi all,
You can find the notes at: https://github.com/OpenAMP/open-amp/wiki/TSC-Meeting-Notes-2020#20200417
If you attended, please check & update the notes if you spot any errors or important omissions.
Action Items:
* Nathalie: Put on board meeting agenda
* We will vote at the next Board meeting to add to the charter at what interval we should re-pick the TSC chair. Suggestion is 1 year.
* Make it official at Board meeting that working group proposes someone & TSC approves. Working group lead should attend TSC calls.
* Maarten/Dan: document the goals/aspirations for App Services group in Future and Current work pages in OpenAMP Wiki
* Tomas/Stefano/Bruce: document the goals/aspirations for System DT group in Future and Current work pages in OpenAMP Wiki
* Bill M: document the goals/aspirations for OpenAMP-rp group in Future and Current work pages in OpenAMP Wiki
* Bill M to write up the thoughts on API stability policy & point to the Zephyr policy
* Bill M volunteers to drive the topic of wire protocol stability.
Decisions
* Tomas Evensen officially voted in as TSC chair
Thanks & regards,
Nathalie C. Chan King Choy
Program Manager focused on Open Source & Community
All,
I have the action to write up thought on API stability.
On 4/17 we added wire protocol stability to the list.
There is also discussion of API homogeneity across different implementations and/or operating environments but that topic is out of scope for this discussion and I specifically opted out of leading that discussion.
**** API Stability:
For reference here is the Zephyr policy on API lifecycle:
https://docs.zephyrproject.org/latest/development_process/api_lifecycle.html
** Scope:
The scope of the OpenAMP API lifecycle policy is mostly the libraries and supporting code owned by the project.
Today that is primarily the open-amp and libmetal libraries but we expect that to expand in the future.
Specifically out of scope would be the APIs internal to the Linux kernel. The Linux kernel has a famous "no stable api" policy.
Probably also out of scope would be the kernel / user interface. This interface has a more stringent "don't break the user interface policy" than will be described here.
Nothing prevents us from trying to apply our policies to the Linux kernel on a best effort basis but we need to understand the kernel's policies will override ours in a conflict.
** Why have a policy?:
One possible policy is to have no policy or a weak one. Under such a policy, If someone is using the old API's, let then use the old version of the library. When they want to upgrade to a new version, they should upgrade to the new APIs as well.
I don't think a weak policy is wise. We are a small project and don't want to maintain and test many versions of the libraries. To date we don't have an LTS policy and I think it would be good if we did not have to go there. A strong API stability statement means that users can pick up bug fixes, new platforms and even some new features without having to change [much] of their application/system. Even if we define an LTS policy a stable API policy lowers the barrier to pick up that one new feature you need.
** Comments on the Zephyr policy:
OpenAMP is a smaller project than Zephyr so I think we can simplify the model a bit.
Certainly we want the API states of stable, deprecated, and removed.
I don't see any need to have two states before stable.
"Experimental" APIs should not be in the release branches, they should be in experimental branches or git repo forks.
You could say the same for "Unstable" but there are valid reasons to include it as well.
The Zephyr policy says things stay in depreciated state for 2 releases. Zephyr makes releases ~ 2 times per year. So applications have to upgrade versions at least once a year to have any benefit from the policy. This seems very short to me. A 2 year depreciation stay seems more appropriate to me. Another approach would be to specify a minimum and a maximum time in deprecated state. Things that are easy to keep can stay for the max time and things that cause big headaches to maintain can stay for the minimum time.
** Mechanism of compatibility
As with the Zephyr policy we are focused on source level compatibility. It is acceptable if the user has to recompile his application to use the new library version.
Maintaining a binary level API (more correctly an ABI) is a decent amount of extra work. If we do have Linux shared libraries that get commonly used we will need to look at this. However, I suggest we tackle that issues as it arises. (A static library does not have the same issue)
**** Wire Protocol Stability:
The wire protocol describes the interactions of two independent CPUs in an AMP system. The bar for maintaining compatibility at this level is much higher.
Some random thoughts/suggestions:
(I am using "firmware" and "kernel" as stand-ins for the more general cases also)
* break of compatibility of the protocol level should require TSC approval
* New kernels should run old firmware
* New firmware that has extra features with new kernels should still work with old kernels if that is desired
* We need to know what properties of interaction are guaranteed vs just how the current implementation works today
** We need a protocol document
** Until we do, we have to treat current UPSTREAM model as the defacto standard
** We can't really have protocol compatibility states until we have a protocol document
** Anything currently only in vendor branches is considered Experimental
* New Protocol features and versions are best if they can be discovered live
** However manual opt-in by both parties is acceptable as a fallback
Thanks,
Bill
---------------------------------------------------
William A. Mills
Chief Technologist, Open Source
Texas Instruments, Processors
20250 Century Blvd, Suit 300
Germantown MD, 20874
(work/mobile) +1-240-643-0836
