|
@@ -7,8 +7,12 @@ Getting Started
|
|
|
- Make sure you have a Github account and you are logged on both
|
|
|
`developer.trustedfirmware.org`_ and `review.trustedfirmware.org`_.
|
|
|
|
|
|
+ Also make sure that you have registered your full name and email address in
|
|
|
+ your `review.trustedfirmware.org`_ profile. Otherwise, the Gerrit server
|
|
|
+ might reject patches you attempt to post for review.
|
|
|
+
|
|
|
- If you plan to contribute a major piece of work, it is usually a good idea to
|
|
|
- start a discussion around it on the mailing list. This gives everyone
|
|
|
+ start a discussion around it on the `TF-A mailing list`_. This gives everyone
|
|
|
visibility of what is coming up, you might learn that somebody else is
|
|
|
already working on something similar or the community might be able to
|
|
|
provide some early input to help shaping the design of the feature.
|
|
@@ -17,16 +21,16 @@ Getting Started
|
|
|
it explicitly in the email thread and ensure that the changes that include
|
|
|
Third Party IP are made in a separate patch (or patch series).
|
|
|
|
|
|
-- Clone `Trusted Firmware-A`_ on your own machine as described in
|
|
|
+- Clone the Trusted Firmware-A source code on your own machine as described in
|
|
|
:ref:`prerequisites_get_source`.
|
|
|
|
|
|
-- Create a local topic branch based on the `Trusted Firmware-A`_ ``master``
|
|
|
+- Create a local topic branch based on the Trusted Firmware-A ``master``
|
|
|
branch.
|
|
|
|
|
|
Making Changes
|
|
|
==============
|
|
|
|
|
|
-- Ensure commits adhere to the the project's :ref:`Commit Style`.
|
|
|
+- Ensure commits adhere to the project's :ref:`Commit Style`.
|
|
|
|
|
|
- Make commits of logical units. See these general `Git guidelines`_ for
|
|
|
contributing to a project.
|
|
@@ -93,13 +97,21 @@ Making Changes
|
|
|
Submitting Changes
|
|
|
==================
|
|
|
|
|
|
-- Submit your changes for review at https://review.trustedfirmware.org
|
|
|
- targeting the ``integration`` branch.
|
|
|
+.. note::
|
|
|
+ Please follow the `How to Contribute Code`_ section of the OpenCI
|
|
|
+ documentation for general instructions on setting up Gerrit and posting
|
|
|
+ patches there. The rest of this section provides details about patch
|
|
|
+ submission rules specifically for the TF-A project.
|
|
|
+
|
|
|
+- Submit your changes for review using the ``git review`` command.
|
|
|
|
|
|
-- Add reviewers for your patch:
|
|
|
+ This will automatically rebase them onto the upstream ``integration`` branch,
|
|
|
+ as required by TF-A's patch submission process.
|
|
|
|
|
|
- - At least one code owner for each module modified by the patch. See the list
|
|
|
- of modules and their :ref:`code owners`.
|
|
|
+- From the Gerrit web UI, add reviewers for your patch:
|
|
|
+
|
|
|
+ - At least one code owner for each module modified by the patch. See the
|
|
|
+ list of modules and their :ref:`code owners`.
|
|
|
|
|
|
- At least one maintainer. See the list of :ref:`maintainers`.
|
|
|
|
|
@@ -167,26 +179,54 @@ Submitting Changes
|
|
|
Add CI Configurations
|
|
|
=====================
|
|
|
|
|
|
-- TF-A uses Jenkins tool for Continuous Integration and testing activities.
|
|
|
- Various CI Jobs are deployed which run tests on every patch before being
|
|
|
- merged. So each of your patches go through a series of checks before they
|
|
|
- get merged on to the master branch. Kindly ensure, that everytime you add
|
|
|
- new files under your platform, they are covered under the following two sections:
|
|
|
+TF-A uses Jenkins for Continuous Integration and testing activities. Various CI
|
|
|
+jobs are deployed to run tests on every patch before being merged. Each of your
|
|
|
+patches go through a series of checks before they get merged on to the master
|
|
|
+branch. Kindly ensure that every time you add new files under your platform,
|
|
|
+they are covered by the following two sections.
|
|
|
|
|
|
Coverity Scan
|
|
|
-------------
|
|
|
|
|
|
-- ``Coverity Scan analysis`` is one of the tests we perform on our source code
|
|
|
- at regular intervals. We maintain a build script ``tf-cov-make`` which contains the
|
|
|
- build configurations of various platforms in order to cover the entire source
|
|
|
- code being analysed by Coverity.
|
|
|
+The TF-A project makes use of `Coverity Scan` for static analysis, a service
|
|
|
+offered by Synopsys for open-source projects. This tool is able to find defects
|
|
|
+and vulnerabilities in a code base, such as dereferences of NULL pointers, use
|
|
|
+of uninitialized data, control flow issues and many other things.
|
|
|
+
|
|
|
+The TF-A source code is submitted daily to this service for analysis. Results of
|
|
|
+the latest and previous scans, as well as the complete list of defects it
|
|
|
+detected, are accessible online from
|
|
|
+https://scan.coverity.com/projects/arm-software-arm-trusted-firmware.
|
|
|
+
|
|
|
+The `tf-a-ci-scripts repository`_ contains scripts to run the Coverity Scan
|
|
|
+tools on the integration branch of the TF-A code base and make them available on
|
|
|
+https://scan.coverity.com. These scripts get executed daily by the
|
|
|
+`tf-a-coverity Jenkins job`_.
|
|
|
+
|
|
|
+In order to maintain a high level of coverage, including on newly introduced
|
|
|
+code, it is important to maintain the appropriate TF-A CI scripts. Details of
|
|
|
+when to update these scripts and how to do so follow.
|
|
|
+
|
|
|
+We maintain a build script - ``tf-cov-make`` - which contains the build
|
|
|
+configurations of various platforms in order to cover the entire source code
|
|
|
+being analysed by Coverity.
|
|
|
|
|
|
-- When you submit your patches for review containing new source files, please
|
|
|
- ensure to include them for the ``Coverity Scan analysis`` by adding the
|
|
|
- respective build configurations in the ``tf-cov-make`` build script.
|
|
|
+When you submit your patches for review, and if they contain new source files,
|
|
|
+`TF-A CI static checks job`_ might report that these files are not covered. In
|
|
|
+this case, the job's console output will show the following error message::
|
|
|
|
|
|
-- In this section you find the details on how to append your new build
|
|
|
- configurations for Coverity scan analysis illustrated with examples:
|
|
|
+ ****** Newly added files detection check for Coverity Scan analysis on patch(es) ******
|
|
|
+
|
|
|
+ Result : FAILURE
|
|
|
+
|
|
|
+ New source files have been identified in your patch..
|
|
|
+ some/dir/file.c
|
|
|
+
|
|
|
+ please ensure to include them for the ``Coverity Scan analysis`` by adding
|
|
|
+ the respective build configurations in the ``tf-cov-make`` build script.
|
|
|
+
|
|
|
+In this section you find the details on how to append your new build
|
|
|
+configurations for Coverity scan analysis illustrated with examples:
|
|
|
|
|
|
#. We maintain a separate repository named `tf-a-ci-scripts repository`_
|
|
|
for placing all the test scripts which will be executed by the CI Jobs.
|
|
@@ -194,9 +234,9 @@ Coverity Scan
|
|
|
#. In this repository, ``tf-cov-make`` script is located at
|
|
|
``tf-a-ci-scripts/script/tf-coverity/tf-cov-make``
|
|
|
|
|
|
-#. Edit `tf-cov-make`_ script by appending all the possible build configurations with
|
|
|
- the specific ``build-flags`` relevant to your platform, so that newly added
|
|
|
- source files get built and analysed by Coverity.
|
|
|
+#. Edit the `tf-cov-make`_ script by appending all the possible build
|
|
|
+ configurations with the specific build flags relevant to your platform, so
|
|
|
+ that newly added source files get built and analysed by Coverity.
|
|
|
|
|
|
#. For better understanding follow the below specified examples listed in the
|
|
|
``tf-cov-make`` script.
|
|
@@ -220,45 +260,44 @@ Coverity Scan
|
|
|
make PLAT=hikey960 $(common_flags) ${TBB_OPTIONS} all
|
|
|
make PLAT=poplar $(common_flags) all
|
|
|
|
|
|
-- In this case for ``Hikey`` boards additional ``build-flags`` has been included
|
|
|
- along with the ``commom_flags`` to cover most of the files relevant to it.
|
|
|
+- In this case for ``Hikey`` boards additional build flags have been included
|
|
|
+ along with the ``common_flags`` to cover most of the files relevant to it.
|
|
|
|
|
|
- Similar to this you can still find many other different build configurations
|
|
|
of various other platforms listed in the ``tf-cov-make`` script. Kindly refer
|
|
|
them and append your build configurations respectively.
|
|
|
|
|
|
-Test Build Configuration (``tf-l1-build-plat``)
|
|
|
------------------------------------------------
|
|
|
-
|
|
|
-- Coverity Scan analysis, runs on a daily basis and will not be triggered for
|
|
|
- every individual trusted-firmware patch.
|
|
|
+Test Build Configurations
|
|
|
+-------------------------
|
|
|
|
|
|
-- Considering this, we have other distinguished CI jobs which run a set of test
|
|
|
- configurations on every patch, before they are being passed to ``Coverity scan analysis``.
|
|
|
+We have CI jobs which run a set of test configurations on every TF-A patch
|
|
|
+before they get merged upstream.
|
|
|
|
|
|
-- ``tf-l1-build-plat`` is the test group, which holds the test configurations
|
|
|
- to build all the platforms. So be kind enough to verify that your newly added
|
|
|
- files are built as part of one of the existing platform configurations present
|
|
|
- in ``tf-l1-build-plat`` test group.
|
|
|
+At the bare minimum, TF-A code should build without any errors for every
|
|
|
+supported platform - and every feature of this platform. To make sure this is
|
|
|
+the case, we maintain a set of build tests. ``tf-l1-build-plat`` is the test
|
|
|
+group which holds all build tests for all platforms. So be kind enough to
|
|
|
+verify that your newly added files are covered by such a build test.
|
|
|
|
|
|
-- In this section you find the details on how to add the appropriate files,
|
|
|
- needed to build your newly introduced platform as part of ``tf-l1-build-plat``
|
|
|
- test group, illustrated with an example:
|
|
|
+If this is not the case, please follow the instructions below to add the
|
|
|
+appropriate files. We will illustrate this with an example for the ``Hikey``
|
|
|
+platform.
|
|
|
|
|
|
-- Lets consider ``Hikey`` platform:
|
|
|
- In the `tf-a-ci-scripts repository`_ we need to add a build configuration file ``hikey-default``
|
|
|
- under tf_config folder, ``tf_config/hikey-default`` listing all the build parameters
|
|
|
- relevant to it.
|
|
|
+- In the `tf-a-ci-scripts repository`_ we need to add a build configuration file
|
|
|
+ ``hikey-default`` under ``tf_config/`` folder. ``tf_config/hikey-default``
|
|
|
+ must list all the build parameters relevant to it.
|
|
|
|
|
|
.. code:: shell
|
|
|
|
|
|
- #Hikey Build Parameters
|
|
|
+ # Hikey Build Parameters
|
|
|
CROSS_COMPILE=aarch64-none-elf-
|
|
|
PLAT=hikey
|
|
|
|
|
|
-- Further a test-configuration file ``hikey-default:nil`` need to be added under the
|
|
|
- test group, ``tf-l1-build-plat`` located at ``tf-a-ci-scripts/group/tf-l1-build-plat``,
|
|
|
- to allow the platform to be built as part of this group.
|
|
|
+- Further another file, ``hikey-default:nil``, needs to be added under
|
|
|
+ ``group/tf-l1-build-plat/`` folder to allow the platform to be built as part
|
|
|
+ of this test group. ``group/tf-l1-build-plat/hikey-default:nil`` file just
|
|
|
+ needs to exist but does not contain anything meaningful, apart from a
|
|
|
+ mandatory copyright notice:
|
|
|
|
|
|
.. code:: shell
|
|
|
|
|
@@ -268,7 +307,11 @@ Test Build Configuration (``tf-l1-build-plat``)
|
|
|
# SPDX-License-Identifier: BSD-3-Clause
|
|
|
#
|
|
|
|
|
|
-- As illustrated above, you need to add the similar files supporting your platform.
|
|
|
+- As illustrated above, you need to add similar files supporting your platform.
|
|
|
+
|
|
|
+For a more elaborate explanation of the TF-A CI scripts internals, including how
|
|
|
+to add more complex tests beyond a simple build test, please refer to the `TF-A
|
|
|
+CI scripts overview`_ section of the OpenCI documentation.
|
|
|
|
|
|
Binary Components
|
|
|
=================
|
|
@@ -289,11 +332,10 @@ Binary Components
|
|
|
|
|
|
--------------
|
|
|
|
|
|
-*Copyright (c) 2013-2022, Arm Limited and Contributors. All rights reserved.*
|
|
|
+*Copyright (c) 2013-2024, Arm Limited and Contributors. All rights reserved.*
|
|
|
|
|
|
.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
|
|
|
.. _review.trustedfirmware.org: https://review.trustedfirmware.org
|
|
|
-.. _Trusted Firmware-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
|
|
|
.. _Git guidelines: http://git-scm.com/book/ch5-2.html
|
|
|
.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html
|
|
|
.. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io
|
|
@@ -302,3 +344,7 @@ Binary Components
|
|
|
.. _TF-A mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-a.lists.trustedfirmware.org/
|
|
|
.. _tf-a-ci-scripts repository: https://git.trustedfirmware.org/ci/tf-a-ci-scripts.git/
|
|
|
.. _tf-cov-make: https://git.trustedfirmware.org/ci/tf-a-ci-scripts.git/tree/script/tf-coverity/tf-cov-make
|
|
|
+.. _How to Contribute Code: https://tf-ci-users-guide.readthedocs.io/en/latest/#how-to-contribute-code
|
|
|
+.. _TF-A CI scripts overview: https://tf-ci-users-guide.readthedocs.io/en/latest/#tf-a-ci-scripts-overview
|
|
|
+.. _tf-a-coverity Jenkins job: https://ci.trustedfirmware.org/job/tf-a-coverity/
|
|
|
+.. _TF-A CI static checks job: https://ci.trustedfirmware.org/job/tf-a-static-checks/
|