1*a6a1dcbeSSandrine BailleuxPlatform Ports Policy 2*a6a1dcbeSSandrine Bailleux===================== 3*a6a1dcbeSSandrine Bailleux 4*a6a1dcbeSSandrine BailleuxThis document clarifies a couple of policy points around platform ports 5*a6a1dcbeSSandrine Bailleuxmanagement. 6*a6a1dcbeSSandrine Bailleux 7*a6a1dcbeSSandrine BailleuxPlatform compatibility policy 8*a6a1dcbeSSandrine Bailleux----------------------------- 9*a6a1dcbeSSandrine Bailleux 10*a6a1dcbeSSandrine BailleuxPlatform compatibility is mainly affected by changes to Platform APIs (as 11*a6a1dcbeSSandrine Bailleuxdocumented in the :ref:`Porting Guide`), driver APIs (like the GICv3 drivers) or 12*a6a1dcbeSSandrine Bailleuxlibrary interfaces (like xlat_table library). The project will try to maintain 13*a6a1dcbeSSandrine Bailleuxcompatibility for upstream platforms. Due to evolving requirements and 14*a6a1dcbeSSandrine Bailleuxenhancements, there might be changes affecting platform compatibility which 15*a6a1dcbeSSandrine Bailleuxmeans the previous interface needs to be deprecated and a new interface 16*a6a1dcbeSSandrine Bailleuxintroduced to replace it. In case the migration to the new interface is trivial, 17*a6a1dcbeSSandrine Bailleuxthe contributor of the change is expected to make good effort to migrate the 18*a6a1dcbeSSandrine Bailleuxupstream platforms to the new interface. 19*a6a1dcbeSSandrine Bailleux 20*a6a1dcbeSSandrine BailleuxThe deprecated interfaces are listed inside :ref:`Release Processes` as well as 21*a6a1dcbeSSandrine Bailleuxthe release after which each one will be removed. When an interface is 22*a6a1dcbeSSandrine Bailleuxdeprecated, the page must be updated to indicate the release after which the 23*a6a1dcbeSSandrine Bailleuxinterface will be removed. This must be at least 1 full release cycle in future. 24*a6a1dcbeSSandrine BailleuxFor non-trivial interface changes, an email should be sent out to the `TF-A 25*a6a1dcbeSSandrine Bailleuxpublic mailing list`_ to notify platforms that they should migrate away from the 26*a6a1dcbeSSandrine Bailleuxdeprecated interfaces. Platforms are expected to migrate before the removal of 27*a6a1dcbeSSandrine Bailleuxthe deprecated interface. 28*a6a1dcbeSSandrine Bailleux 29*a6a1dcbeSSandrine BailleuxPlatform deprecation policy 30*a6a1dcbeSSandrine Bailleux--------------------------- 31*a6a1dcbeSSandrine Bailleux 32*a6a1dcbeSSandrine BailleuxIf a platform is no longer maintained, it is best to deprecate it to keep the 33*a6a1dcbeSSandrine Bailleuxprojects' source tree clean and healthy. Deprecation can be a 1-stage or 2-stage 34*a6a1dcbeSSandrine Bailleuxprocess (up to the platform maintainers). 35*a6a1dcbeSSandrine Bailleux 36*a6a1dcbeSSandrine Bailleux - *2-stage*: The platform's source code can be kept in the repository for a 37*a6a1dcbeSSandrine Bailleux cooling off period before deleting it (typically 2 release cycles). In this 38*a6a1dcbeSSandrine Bailleux case, we keep track ot the *Deprecated* version separately from the *Deleted* 39*a6a1dcbeSSandrine Bailleux version. 40*a6a1dcbeSSandrine Bailleux 41*a6a1dcbeSSandrine Bailleux - *1-stage*: The platform's source code can be deleted straight away. In this 42*a6a1dcbeSSandrine Bailleux case, both versions are the same. 43*a6a1dcbeSSandrine Bailleux 44*a6a1dcbeSSandrine BailleuxThe :ref:`Platform Ports` page provides a list of all deprecated/deleted 45*a6a1dcbeSSandrine Bailleuxplatform ports (or soon to be) to this day. 46*a6a1dcbeSSandrine Bailleux 47*a6a1dcbeSSandrine Bailleux-------------- 48*a6a1dcbeSSandrine Bailleux 49*a6a1dcbeSSandrine Bailleux*Copyright (c) 2018-2022, Arm Limited and Contributors. All rights reserved.* 50*a6a1dcbeSSandrine Bailleux 51*a6a1dcbeSSandrine Bailleux.. _TF-A public mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-a.lists.trustedfirmware.org/ 52