1a6a1dcbeSSandrine BailleuxPlatform Ports Policy 2a6a1dcbeSSandrine Bailleux===================== 3a6a1dcbeSSandrine Bailleux 4a6a1dcbeSSandrine BailleuxThis document clarifies a couple of policy points around platform ports 5a6a1dcbeSSandrine Bailleuxmanagement. 6a6a1dcbeSSandrine Bailleux 7a6a1dcbeSSandrine BailleuxPlatform compatibility policy 8a6a1dcbeSSandrine Bailleux----------------------------- 9a6a1dcbeSSandrine Bailleux 10a6a1dcbeSSandrine BailleuxPlatform compatibility is mainly affected by changes to Platform APIs (as 11a6a1dcbeSSandrine Bailleuxdocumented in the :ref:`Porting Guide`), driver APIs (like the GICv3 drivers) or 12a6a1dcbeSSandrine Bailleuxlibrary interfaces (like xlat_table library). The project will try to maintain 138f55cde2SSandrine Bailleuxcompatibility for upstream platforms. 148f55cde2SSandrine Bailleux 158f55cde2SSandrine BailleuxDue to evolving requirements and enhancements, there might be changes affecting 168f55cde2SSandrine Bailleuxplatform compatibility, which means the previous interface needs to be deprecated 178f55cde2SSandrine Bailleuxand a new interface introduced to replace it. In case the migration to the new 188f55cde2SSandrine Bailleuxinterface is trivial, the contributor of the change is expected to make good 198f55cde2SSandrine Bailleuxeffort to migrate the upstream platforms to the new interface. 208f55cde2SSandrine Bailleux 218f55cde2SSandrine BailleuxThe project will generally not take into account downstream platforms. If those 228f55cde2SSandrine Bailleuxare affected by a deprecation / removal decision, we encourage their maintainers 238f55cde2SSandrine Bailleuxto upstream their platform code or copy the latest version of the code being 248f55cde2SSandrine Bailleuxdeprecated into their downstream tree. 25a6a1dcbeSSandrine Bailleux 26a6a1dcbeSSandrine BailleuxThe deprecated interfaces are listed inside :ref:`Release Processes` as well as 27a6a1dcbeSSandrine Bailleuxthe release after which each one will be removed. When an interface is 28a6a1dcbeSSandrine Bailleuxdeprecated, the page must be updated to indicate the release after which the 29a6a1dcbeSSandrine Bailleuxinterface will be removed. This must be at least 1 full release cycle in future. 30a6a1dcbeSSandrine BailleuxFor non-trivial interface changes, an email should be sent out to the `TF-A 31a6a1dcbeSSandrine Bailleuxpublic mailing list`_ to notify platforms that they should migrate away from the 32a6a1dcbeSSandrine Bailleuxdeprecated interfaces. Platforms are expected to migrate before the removal of 33a6a1dcbeSSandrine Bailleuxthe deprecated interface. 34a6a1dcbeSSandrine Bailleux 35*47801a69SSandrine BailleuxDeprecation policy 36*47801a69SSandrine Bailleux------------------ 37a6a1dcbeSSandrine Bailleux 38*47801a69SSandrine BailleuxIf a platform, driver or library interface is no longer maintained, it is best 39*47801a69SSandrine Bailleuxto deprecate it to keep the projects' source tree clean and healthy. Deprecation 40*47801a69SSandrine Bailleuxcan be a 1-stage or 2-stage process (up to the maintainers). 41a6a1dcbeSSandrine Bailleux 42*47801a69SSandrine Bailleux - *2-stage*: The source code can be kept in the repository for a cooling off 43*47801a69SSandrine Bailleux period before deleting it (typically 2 release cycles). In this case, we keep 44*47801a69SSandrine Bailleux track of the *Deprecated* version separately from the *Deleted* version. 45a6a1dcbeSSandrine Bailleux 46*47801a69SSandrine Bailleux - *1-stage*: The source code can be deleted straight away. In this case, both 47*47801a69SSandrine Bailleux versions are the same. 48a6a1dcbeSSandrine Bailleux 49a6a1dcbeSSandrine BailleuxThe :ref:`Platform Ports` page provides a list of all deprecated/deleted 50a6a1dcbeSSandrine Bailleuxplatform ports (or soon to be) to this day. 51a6a1dcbeSSandrine Bailleux 52a6a1dcbeSSandrine Bailleux-------------- 53a6a1dcbeSSandrine Bailleux 548f55cde2SSandrine Bailleux*Copyright (c) 2018-2023, Arm Limited and Contributors. All rights reserved.* 55a6a1dcbeSSandrine Bailleux 56a6a1dcbeSSandrine Bailleux.. _TF-A public mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-a.lists.trustedfirmware.org/ 57