1Contributor's Guide 2******************* 3 4Getting Started 5=============== 6 7- Make sure you have a Github account and you are logged on both 8 `developer.trustedfirmware.org`_ and `review.trustedfirmware.org`_. 9 10- If you plan to contribute a major piece of work, it is usually a good idea to 11 start a discussion around it on the mailing list. This gives everyone 12 visibility of what is coming up, you might learn that somebody else is 13 already working on something similar or the community might be able to 14 provide some early input to help shaping the design of the feature. 15 16 If you intend to include Third Party IP in your contribution, please mention 17 it explicitly in the email thread and ensure that the changes that include 18 Third Party IP are made in a separate patch (or patch series). 19 20- Clone `Trusted Firmware-A`_ on your own machine as described in 21 :ref:`prerequisites_get_source`. 22 23- Create a local topic branch based on the `Trusted Firmware-A`_ ``master`` 24 branch. 25 26Making Changes 27============== 28 29- Ensure commits adhere to the the project's :ref:`Commit Style`. 30 31- Make commits of logical units. See these general `Git guidelines`_ for 32 contributing to a project. 33 34- Keep the commits on topic. If you need to fix another bug or make another 35 enhancement, please address it on a separate topic branch. 36 37- Split the patch in manageable units. Small patches are usually easier to 38 review so this will speed up the review process. 39 40- Avoid long commit series. If you do have a long series, consider whether 41 some commits should be squashed together or addressed in a separate topic. 42 43- Follow the :ref:`Coding Style` and :ref:`Coding Guidelines`. 44 45 - Use the checkpatch.pl script provided with the Linux source tree. A 46 Makefile target is provided for convenience, see :ref:`this 47 section<automatic-compliance-checking>` for more details. 48 49- Where appropriate, please update the documentation. 50 51 - Consider whether the :ref:`Porting Guide`, :ref:`Firmware Design` document 52 or other in-source documentation needs updating. 53 54 - If you are submitting new files that you intend to be the code owner for 55 (for example, a new platform port), then also update the 56 :ref:`code owners` file. 57 58 - For topics with multiple commits, you should make all documentation changes 59 (and nothing else) in the last commit of the series. Otherwise, include 60 the documentation changes within the single commit. 61 62.. _copyright-license-guidance: 63 64- Ensure that each changed file has the correct copyright and license 65 information. Files that entirely consist of contributions to this project 66 should have a copyright notice and BSD-3-Clause SPDX license identifier of 67 the form as shown in :ref:`license`. Files that contain changes to imported 68 Third Party IP files should retain their original copyright and license 69 notices. 70 71 For significant contributions you may add your own copyright notice in the 72 following format: 73 74 :: 75 76 Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved. 77 78 where XXXX is the year of first contribution (if different to YYYY) and YYYY 79 is the year of most recent contribution. <OWNER> is your name or your company 80 name. 81 82- Ensure that each patch in the patch series compiles in all supported 83 configurations. Patches which do not compile will not be merged. 84 85- Please test your changes. As a minimum, ensure that Linux boots on the 86 Foundation FVP. See :ref:`Arm Fixed Virtual Platforms (FVP)` for more 87 information. For more extensive testing, consider running the `TF-A Tests`_ 88 against your patches. 89 90- Ensure that all CI automated tests pass. Failures should be fixed. They might 91 block a patch, depending on how critical they are. 92 93Submitting Changes 94================== 95 96- Submit your changes for review at https://review.trustedfirmware.org 97 targeting the ``integration`` branch. 98 99- Add reviewers for your patch: 100 101 - At least one code owner for each module modified by the patch. See the list 102 of modules and their :ref:`code owners`. 103 104 - At least one maintainer. See the list of :ref:`maintainers`. 105 106 - If some module has no code owner, try to identify a suitable (non-code 107 owner) reviewer. Running ``git blame`` on the module's source code can 108 help, as it shows who has been working the most recently on this area of 109 the code. 110 111 Alternatively, if it is impractical to identify such a reviewer, you might 112 send an email to the `TF-A mailing list`_ to broadcast your review request 113 to the community. 114 115 Note that self-reviewing a patch is prohibited, even if the patch author is 116 the only code owner of a module modified by the patch. Getting a second pair 117 of eyes on the code is essential to keep up with the quality standards the 118 project aspires to. 119 120- The changes will then undergo further review by the designated people. Any 121 review comments will be made directly on your patch. This may require you to 122 do some rework. For controversial changes, the discussion might be moved to 123 the `TF-A mailing list`_ to involve more of the community. 124 125 Refer to the `Gerrit Uploading Changes documentation`_ for more details. 126 127- The patch submission rules are the following. For a patch to be approved 128 and merged in the tree, it must get: 129 130 - One ``Code-Owner-Review+1`` for each of the modules modified by the patch. 131 - A ``Maintainer-Review+1``. 132 133 In the case where a code owner could not be found for a given module, 134 ``Code-Owner-Review+1`` is substituted by ``Code-Review+1``. 135 136 In addition to these various code review labels, the patch must also get a 137 ``Verified+1``. This is usually set by the Continuous Integration (CI) bot 138 when all automated tests passed on the patch. Sometimes, some of these 139 automated tests may fail for reasons unrelated to the patch. In this case, 140 the maintainers might (after analysis of the failures) override the CI bot 141 score to certify that the patch has been correctly tested. 142 143 In the event where the CI system lacks proper tests for a patch, the patch 144 author or a reviewer might agree to perform additional manual tests 145 in their review and the reviewer incorporates the review of the additional 146 testing in the ``Code-Review+1`` or ``Code-Owner-Review+1`` as applicable to 147 attest that the patch works as expected. Where possible additional tests should 148 be added to the CI system as a follow up task. For example, for a 149 platform-dependent patch where the said platform is not available in the CI 150 system's board farm. 151 152- When the changes are accepted, the :ref:`maintainers` will integrate them. 153 154 - Typically, the :ref:`maintainers` will merge the changes into the 155 ``integration`` branch. 156 157 - If the changes are not based on a sufficiently-recent commit, or if they 158 cannot be automatically rebased, then the :ref:`maintainers` may rebase it 159 on the ``integration`` branch or ask you to do so. 160 161 - After final integration testing, the changes will make their way into the 162 ``master`` branch. If a problem is found during integration, the 163 :ref:`maintainers` will request your help to solve the issue. They may 164 revert your patches and ask you to resubmit a reworked version of them or 165 they may ask you to provide a fix-up patch. 166 167Add CI Configurations 168===================== 169 170- TF-A uses Jenkins tool for Continuous Integration and testing activities. 171 Various CI Jobs are deployed which run tests on every patch before being 172 merged. So each of your patches go through a series of checks before they 173 get merged on to the master branch. Kindly ensure, that everytime you add 174 new files under your platform, they are covered under the following two sections: 175 176Coverity Scan 177------------- 178 179- ``Coverity Scan analysis`` is one of the tests we perform on our source code 180 at regular intervals. We maintain a build script ``tf-cov-make`` which contains the 181 build configurations of various platforms in order to cover the entire source 182 code being analysed by Coverity. 183 184- When you submit your patches for review containing new source files, please 185 ensure to include them for the ``Coverity Scan analysis`` by adding the 186 respective build configurations in the ``tf-cov-make`` build script. 187 188- In this section you find the details on how to append your new build 189 configurations for Coverity scan analysis illustrated with examples: 190 191#. We maintain a separate repository named `tf-a-ci-scripts repository`_ 192 for placing all the test scripts which will be executed by the CI Jobs. 193 194#. In this repository, ``tf-cov-make`` script is located at 195 ``tf-a-ci-scripts/script/tf-coverity/tf-cov-make`` 196 197#. Edit `tf-cov-make`_ script by appending all the possible build configurations with 198 the specific ``build-flags`` relevant to your platform, so that newly added 199 source files get built and analysed by Coverity. 200 201#. For better understanding follow the below specified examples listed in the 202 ``tf-cov-make`` script. 203 204.. code:: shell 205 206 Example 1: 207 #Intel 208 make PLAT=stratix10 $(common_flags) all 209 make PLAT=agilex $(common_flags) all 210 211- In the above example there are two different SoCs ``stratix`` and ``agilex`` 212 under the Intel platform and the build configurations has been added suitably 213 to include most of their source files. 214 215.. code:: shell 216 217 Example 2: 218 #Hikey 219 make PLAT=hikey $(common_flags) ${TBB_OPTIONS} ENABLE_PMF=1 all 220 make PLAT=hikey960 $(common_flags) ${TBB_OPTIONS} all 221 make PLAT=poplar $(common_flags) all 222 223- In this case for ``Hikey`` boards additional ``build-flags`` has been included 224 along with the ``commom_flags`` to cover most of the files relevant to it. 225 226- Similar to this you can still find many other different build configurations 227 of various other platforms listed in the ``tf-cov-make`` script. Kindly refer 228 them and append your build configurations respectively. 229 230Test Build Configuration (``tf-l1-build-plat``) 231----------------------------------------------- 232 233- Coverity Scan analysis, runs on a daily basis and will not be triggered for 234 every individual trusted-firmware patch. 235 236- Considering this, we have other distinguished CI jobs which run a set of test 237 configurations on every patch, before they are being passed to ``Coverity scan analysis``. 238 239- ``tf-l1-build-plat`` is the test group, which holds the test configurations 240 to build all the platforms. So be kind enough to verify that your newly added 241 files are built as part of one of the existing platform configurations present 242 in ``tf-l1-build-plat`` test group. 243 244- In this section you find the details on how to add the appropriate files, 245 needed to build your newly introduced platform as part of ``tf-l1-build-plat`` 246 test group, illustrated with an example: 247 248- Lets consider ``Hikey`` platform: 249 In the `tf-a-ci-scripts repository`_ we need to add a build configuration file ``hikey-default`` 250 under tf_config folder, ``tf_config/hikey-default`` listing all the build parameters 251 relevant to it. 252 253.. code:: shell 254 255 #Hikey Build Parameters 256 CROSS_COMPILE=aarch64-none-elf- 257 PLAT=hikey 258 259- Further a test-configuration file ``hikey-default:nil`` need to be added under the 260 test group, ``tf-l1-build-plat`` located at ``tf-a-ci-scripts/group/tf-l1-build-plat``, 261 to allow the platform to be built as part of this group. 262 263.. code:: shell 264 265 # 266 # Copyright (c) 2019-2022 Arm Limited. All rights reserved. 267 # 268 # SPDX-License-Identifier: BSD-3-Clause 269 # 270 271- As illustrated above, you need to add the similar files supporting your platform. 272 273Binary Components 274================= 275 276- Platforms may depend on binary components submitted to the `Trusted Firmware 277 binary repository`_ if they require code that the contributor is unable or 278 unwilling to open-source. This should be used as a rare exception. 279- All binary components must follow the contribution guidelines (in particular 280 licensing rules) outlined in the `readme.rst <tf-binaries-readme_>`_ file of 281 the binary repository. 282- Binary components must be restricted to only the specific functionality that 283 cannot be open-sourced and must be linked into a larger open-source platform 284 port. The majority of the platform port must still be implemented in open 285 source. Platform ports that are merely a thin wrapper around a binary 286 component that contains all the actual code will not be accepted. 287- Only platform port code (i.e. in the ``plat/<vendor>`` directory) may rely on 288 binary components. Generic code must always be fully open-source. 289 290-------------- 291 292*Copyright (c) 2013-2022, Arm Limited and Contributors. All rights reserved.* 293 294.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org 295.. _review.trustedfirmware.org: https://review.trustedfirmware.org 296.. _Trusted Firmware-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git 297.. _Git guidelines: http://git-scm.com/book/ch5-2.html 298.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html 299.. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io 300.. _Trusted Firmware binary repository: https://review.trustedfirmware.org/admin/repos/tf-binaries 301.. _tf-binaries-readme: https://git.trustedfirmware.org/tf-binaries.git/tree/readme.rst 302.. _TF-A mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-a.lists.trustedfirmware.org/ 303.. _tf-a-ci-scripts repository: https://git.trustedfirmware.org/ci/tf-a-ci-scripts.git/ 304.. _tf-cov-make: https://git.trustedfirmware.org/ci/tf-a-ci-scripts.git/tree/script/tf-coverity/tf-cov-make 305