blob: ef9ebd38db621680ad15456c7177a75bce2b4e61 [file] [log] [blame]
Paul Beesleyfc9ee362019-03-07 15:47:15 +00001Contributor's Guide
Jayanth Dodderi Chidanandf69f1982022-02-08 14:18:24 +00002*******************
Douglas Raillardd7c21b72017-06-28 15:23:03 +01003
4Getting Started
Jayanth Dodderi Chidanandf69f1982022-02-08 14:18:24 +00005===============
Douglas Raillardd7c21b72017-06-28 15:23:03 +01006
Sandrine Bailleuxd3147342020-05-12 10:36:05 +02007- Make sure you have a Github account and you are logged on both
8 `developer.trustedfirmware.org`_ and `review.trustedfirmware.org`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01009
Sandrine Bailleux6ef77ce2020-08-03 10:27:19 +020010- 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).
Douglas Raillardd7c21b72017-06-28 15:23:03 +010019
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010020- Clone `Trusted Firmware-A`_ on your own machine as described in
21 :ref:`prerequisites_get_source`.
Sandrine Bailleux75804e52020-08-12 11:29:46 +020022
John Tsichritzis2fd3d922019-05-28 13:13:39 +010023- Create a local topic branch based on the `Trusted Firmware-A`_ ``master``
Douglas Raillardd7c21b72017-06-28 15:23:03 +010024 branch.
25
26Making Changes
Jayanth Dodderi Chidanandf69f1982022-02-08 14:18:24 +000027==============
Douglas Raillardd7c21b72017-06-28 15:23:03 +010028
Chris Kay1b706e62021-11-15 10:50:30 +000029- Ensure commits adhere to the the project's :ref:`Commit Style`.
30
Douglas Raillardd7c21b72017-06-28 15:23:03 +010031- Make commits of logical units. See these general `Git guidelines`_ for
32 contributing to a project.
Sandrine Bailleux75804e52020-08-12 11:29:46 +020033
Douglas Raillardd7c21b72017-06-28 15:23:03 +010034- Keep the commits on topic. If you need to fix another bug or make another
Sandrine Bailleux6ef77ce2020-08-03 10:27:19 +020035 enhancement, please address it on a separate topic branch.
Sandrine Bailleux75804e52020-08-12 11:29:46 +020036
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +020037- Split the patch in manageable units. Small patches are usually easier to
38 review so this will speed up the review process.
39
Douglas Raillardd7c21b72017-06-28 15:23:03 +010040- 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.
Sandrine Bailleux75804e52020-08-12 11:29:46 +020042
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +020043- 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.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010048
Sandrine Bailleux75804e52020-08-12 11:29:46 +020049- Where appropriate, please update the documentation.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010050
Sandrine Bailleux75804e52020-08-12 11:29:46 +020051 - Consider whether the :ref:`Porting Guide`, :ref:`Firmware Design` document
52 or other in-source documentation needs updating.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010053
Sandrine Bailleuxd3147342020-05-12 10:36:05 +020054 - 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.
Sandrine Bailleux75804e52020-08-12 11:29:46 +020057
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
Sandrine Bailleux398b1882020-08-17 08:52:33 +020062.. _copyright-license-guidance:
63
Sandrine Bailleux75804e52020-08-12 11:29:46 +020064- 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.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010081
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +020082- Ensure that each patch in the patch series compiles in all supported
83 configurations. Patches which do not compile will not be merged.
84
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000085- Please test your changes. As a minimum, ensure that Linux boots on the
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010086 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.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010089
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +020090- Ensure that all CI automated tests pass. Failures should be fixed. They might
91 block a patch, depending on how critical they are.
92
Douglas Raillardd7c21b72017-06-28 15:23:03 +010093Submitting Changes
Jayanth Dodderi Chidanandf69f1982022-02-08 14:18:24 +000094==================
Douglas Raillardd7c21b72017-06-28 15:23:03 +010095
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +020096- Submit your changes for review at https://review.trustedfirmware.org
97 targeting the ``integration`` branch.
Louis Mayencourt72ef3d42019-03-22 11:47:22 +000098
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +020099- Add reviewers for your patch:
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000100
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +0200101 - At least one code owner for each module modified by the patch. See the list
102 of modules and their :ref:`code owners`.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100103
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +0200104 - At least one maintainer. See the list of :ref:`maintainers`.
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000105
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +0200106 - 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.
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000110
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +0200111 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.
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000124
125 Refer to the `Gerrit Uploading Changes documentation`_ for more details.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100126
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +0200127- 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
Paul Beesleyf8640672019-04-12 14:19:42 +0100152- When the changes are accepted, the :ref:`maintainers` will integrate them.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100153
Paul Beesleyf8640672019-04-12 14:19:42 +0100154 - Typically, the :ref:`maintainers` will merge the changes into the
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000155 ``integration`` branch.
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +0200156
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000157 - If the changes are not based on a sufficiently-recent commit, or if they
Paul Beesleyf8640672019-04-12 14:19:42 +0100158 cannot be automatically rebased, then the :ref:`maintainers` may rebase it
Sandrine Bailleuxd3147342020-05-12 10:36:05 +0200159 on the ``integration`` branch or ask you to do so.
Sandrine Bailleuxe0cb1892020-08-14 15:58:50 +0200160
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000161 - After final integration testing, the changes will make their way into the
Sandrine Bailleuxd3147342020-05-12 10:36:05 +0200162 ``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.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100166
Jayanth Dodderi Chidanandf69f1982022-02-08 14:18:24 +0000167Add CI Configurations
168=====================
Jayanth Dodderi Chidanand32e5fa02021-08-31 12:27:48 +0100169
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
Jayanth Dodderi Chidanandf69f1982022-02-08 14:18:24 +0000173 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-------------
Jayanth Dodderi Chidanand32e5fa02021-08-31 12:27:48 +0100178
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
Jayanth Dodderi Chidanandf69f1982022-02-08 14:18:24 +0000189 configurations for Coverity scan analysis illustrated with examples:
Jayanth Dodderi Chidanand32e5fa02021-08-31 12:27:48 +0100190
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
Jayanth Dodderi Chidanandef7d6f32021-09-09 14:23:10 +0100204.. code:: shell
Jayanth Dodderi Chidanand32e5fa02021-08-31 12:27:48 +0100205
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
Jayanth Dodderi Chidanandef7d6f32021-09-09 14:23:10 +0100215.. code:: shell
Jayanth Dodderi Chidanand32e5fa02021-08-31 12:27:48 +0100216
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
Jayanth Dodderi Chidanandf69f1982022-02-08 14:18:24 +0000230Test 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
Julius Wernercece91a2019-04-18 16:47:46 -0700273Binary Components
Jayanth Dodderi Chidanandf69f1982022-02-08 14:18:24 +0000274=================
Julius Wernercece91a2019-04-18 16:47:46 -0700275
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
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100290--------------
291
Jayanth Dodderi Chidanandf69f1982022-02-08 14:18:24 +0000292*Copyright (c) 2013-2022, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100293
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000294.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
Sandrine Bailleuxd3147342020-05-12 10:36:05 +0200295.. _review.trustedfirmware.org: https://review.trustedfirmware.org
John Tsichritzis2fd3d922019-05-28 13:13:39 +0100296.. _Trusted Firmware-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100297.. _Git guidelines: http://git-scm.com/book/ch5-2.html
Louis Mayencourt72ef3d42019-03-22 11:47:22 +0000298.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
Sandrine Bailleuxd3147342020-05-12 10:36:05 +0200299.. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io
Julius Wernercece91a2019-04-18 16:47:46 -0700300.. _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
Sandrine Bailleux1a4efb12022-04-21 10:17:22 +0200302.. _TF-A mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-a.lists.trustedfirmware.org/
Jayanth Dodderi Chidanand32e5fa02021-08-31 12:27:48 +0100303.. _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