resend

-----Original Message----- From: Mills, William Sent: Saturday, April 18, 2020 11:35 AM To: tsc@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