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 13*8f55cde2SSandrine Bailleuxcompatibility for upstream platforms. 14*8f55cde2SSandrine Bailleux 15*8f55cde2SSandrine BailleuxDue to evolving requirements and enhancements, there might be changes affecting 16*8f55cde2SSandrine Bailleuxplatform compatibility, which means the previous interface needs to be deprecated 17*8f55cde2SSandrine Bailleuxand a new interface introduced to replace it. In case the migration to the new 18*8f55cde2SSandrine Bailleuxinterface is trivial, the contributor of the change is expected to make good 19*8f55cde2SSandrine Bailleuxeffort to migrate the upstream platforms to the new interface. 20*8f55cde2SSandrine Bailleux 21*8f55cde2SSandrine BailleuxThe project will generally not take into account downstream platforms. If those 22*8f55cde2SSandrine Bailleuxare affected by a deprecation / removal decision, we encourage their maintainers 23*8f55cde2SSandrine Bailleuxto upstream their platform code or copy the latest version of the code being 24*8f55cde2SSandrine 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 35a6a1dcbeSSandrine BailleuxPlatform deprecation policy 36a6a1dcbeSSandrine Bailleux--------------------------- 37a6a1dcbeSSandrine Bailleux 38a6a1dcbeSSandrine BailleuxIf a platform is no longer maintained, it is best to deprecate it to keep the 39a6a1dcbeSSandrine Bailleuxprojects' source tree clean and healthy. Deprecation can be a 1-stage or 2-stage 40a6a1dcbeSSandrine Bailleuxprocess (up to the platform maintainers). 41a6a1dcbeSSandrine Bailleux 42a6a1dcbeSSandrine Bailleux - *2-stage*: The platform's source code can be kept in the repository for a 43a6a1dcbeSSandrine Bailleux cooling off period before deleting it (typically 2 release cycles). In this 44a6a1dcbeSSandrine Bailleux case, we keep track ot the *Deprecated* version separately from the *Deleted* 45a6a1dcbeSSandrine Bailleux version. 46a6a1dcbeSSandrine Bailleux 47a6a1dcbeSSandrine Bailleux - *1-stage*: The platform's source code can be deleted straight away. In this 48a6a1dcbeSSandrine Bailleux case, both versions are the same. 49a6a1dcbeSSandrine Bailleux 50a6a1dcbeSSandrine BailleuxThe :ref:`Platform Ports` page provides a list of all deprecated/deleted 51a6a1dcbeSSandrine Bailleuxplatform ports (or soon to be) to this day. 52a6a1dcbeSSandrine Bailleux 53a6a1dcbeSSandrine Bailleux-------------- 54a6a1dcbeSSandrine Bailleux 55*8f55cde2SSandrine Bailleux*Copyright (c) 2018-2023, Arm Limited and Contributors. All rights reserved.* 56a6a1dcbeSSandrine Bailleux 57a6a1dcbeSSandrine Bailleux.. _TF-A public mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-a.lists.trustedfirmware.org/ 58