Message went to tsc-bounces instead of tsc list.
-----Original Message----- From: Arnaud POULIQUEN arnaud.pouliquen@st.com Sent: Tuesday, May 19, 2020 8:50 AM To: Mills, William wmills@ti.com Cc: tsc-bounces@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@lists.openampproject.org On Behalf Of Mills, William via Tsc Sent: samedi 18 avril 2020 17:41 To: tsc@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@lists.openampproject.org https://lists.openampproject.org/mailman/listinfo/tsc