| Sandrine Bailleux | dad3561 | 2022-11-08 13:36:42 +0100 | [diff] [blame] | 1 | Platform Ports Policy |
| 2 | ===================== |
| Soby Mathew | 02bdbb9 | 2018-09-26 11:17:23 +0100 | [diff] [blame] | 3 | |
| Sandrine Bailleux | dad3561 | 2022-11-08 13:36:42 +0100 | [diff] [blame] | 4 | This document clarifies a couple of policy points around platform ports |
| 5 | management. |
| Soby Mathew | 02bdbb9 | 2018-09-26 11:17:23 +0100 | [diff] [blame] | 6 | |
| 7 | Platform compatibility policy |
| 8 | ----------------------------- |
| 9 | |
| 10 | Platform compatibility is mainly affected by changes to Platform APIs (as |
| Paul Beesley | f864067 | 2019-04-12 14:19:42 +0100 | [diff] [blame] | 11 | documented in the :ref:`Porting Guide`), driver APIs (like the GICv3 drivers) or |
| Soby Mathew | 02bdbb9 | 2018-09-26 11:17:23 +0100 | [diff] [blame] | 12 | library interfaces (like xlat_table library). The project will try to maintain |
| Sandrine Bailleux | 1ffc9e5 | 2023-04-17 15:37:48 +0200 | [diff] [blame] | 13 | compatibility for upstream platforms. |
| 14 | |
| 15 | Due to evolving requirements and enhancements, there might be changes affecting |
| 16 | platform compatibility, which means the previous interface needs to be deprecated |
| 17 | and a new interface introduced to replace it. In case the migration to the new |
| 18 | interface is trivial, the contributor of the change is expected to make good |
| 19 | effort to migrate the upstream platforms to the new interface. |
| 20 | |
| 21 | The project will generally not take into account downstream platforms. If those |
| 22 | are affected by a deprecation / removal decision, we encourage their maintainers |
| 23 | to upstream their platform code or copy the latest version of the code being |
| 24 | deprecated into their downstream tree. |
| Soby Mathew | 02bdbb9 | 2018-09-26 11:17:23 +0100 | [diff] [blame] | 25 | |
| Paul Beesley | f864067 | 2019-04-12 14:19:42 +0100 | [diff] [blame] | 26 | The deprecated interfaces are listed inside :ref:`Release Processes` as well as |
| John Tsichritzis | 4730c11 | 2019-07-05 14:14:40 +0100 | [diff] [blame] | 27 | the release after which each one will be removed. When an interface is |
| 28 | deprecated, the page must be updated to indicate the release after which the |
| 29 | interface will be removed. This must be at least 1 full release cycle in future. |
| 30 | For non-trivial interface changes, an email should be sent out to the `TF-A |
| 31 | public mailing list`_ to notify platforms that they should migrate away from the |
| 32 | deprecated interfaces. Platforms are expected to migrate before the removal of |
| 33 | the deprecated interface. |
| Soby Mathew | 02bdbb9 | 2018-09-26 11:17:23 +0100 | [diff] [blame] | 34 | |
| Sandrine Bailleux | dad3561 | 2022-11-08 13:36:42 +0100 | [diff] [blame] | 35 | Platform deprecation policy |
| 36 | --------------------------- |
| 37 | |
| 38 | If a platform is no longer maintained, it is best to deprecate it to keep the |
| 39 | projects' source tree clean and healthy. Deprecation can be a 1-stage or 2-stage |
| 40 | process (up to the platform maintainers). |
| 41 | |
| 42 | - *2-stage*: The platform's source code can be kept in the repository for a |
| 43 | cooling off period before deleting it (typically 2 release cycles). In this |
| 44 | case, we keep track ot the *Deprecated* version separately from the *Deleted* |
| 45 | version. |
| 46 | |
| 47 | - *1-stage*: The platform's source code can be deleted straight away. In this |
| 48 | case, both versions are the same. |
| 49 | |
| 50 | The :ref:`Platform Ports` page provides a list of all deprecated/deleted |
| 51 | platform ports (or soon to be) to this day. |
| 52 | |
| Soby Mathew | 02bdbb9 | 2018-09-26 11:17:23 +0100 | [diff] [blame] | 53 | -------------- |
| 54 | |
| Sandrine Bailleux | 1ffc9e5 | 2023-04-17 15:37:48 +0200 | [diff] [blame] | 55 | *Copyright (c) 2018-2023, Arm Limited and Contributors. All rights reserved.* |
| Soby Mathew | 02bdbb9 | 2018-09-26 11:17:23 +0100 | [diff] [blame] | 56 | |
| Sandrine Bailleux | 1a4efb1 | 2022-04-21 10:17:22 +0200 | [diff] [blame] | 57 | .. _TF-A public mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-a.lists.trustedfirmware.org/ |