3.6.Contributor’s Guide

3.6.1.Getting Started

  • Make sure you have a Github account and you are logged on toreview.trustedfirmware.org.

    Also make sure that you have registered your full name and email address inyourreview.trustedfirmware.org profile. Otherwise, the Gerrit servermight reject patches you attempt to post for review.

  • If you plan to contribute a major piece of work, it is usually a good idea tostart a discussion around it on theTF-A mailing list. This gives everyonevisibility of what is coming up, you might learn that somebody else isalready working on something similar or the community might be able toprovide some early input to help shaping the design of the feature.

    If you intend to include Third Party IP in your contribution, please mentionit explicitly in the email thread and ensure that the changes that includeThird Party IP are made in a separate patch (or patch series).

  • Clone the Trusted Firmware-A source code on your own machine as described inAdditional Steps for Contributors.

  • Create a local topic branch based on the Trusted Firmware-Amasterbranch.

3.6.2.Making Changes

  • Ensure commits adhere to the project’sCommit Style.

  • Make commits of logical units. See these generalGit guidelines forcontributing to a project.

  • Keep the commits on topic. If you need to fix another bug or make anotherenhancement, please address it on a separate topic branch.

  • Split the patch in manageable units. Small patches are usually easier toreview so this will speed up the review process.

  • Avoid long commit series. If you do have a long series, consider whethersome commits should be squashed together or addressed in a separate topic.

  • Follow theCoding Style andCoding Guidelines.

    • Use the checkpatch.pl script provided with the Linux source tree. AMakefile target is provided for convenience, seethissection for more details.

  • Where appropriate, please update the documentation.

    • Consider whether thePorting Guide,Firmware Design documentor other in-source documentation needs updating.

    • If you are submitting new files that you intend to be the code owner for(for example, a new platform port), then also update theCode owners file.

    • For topics with multiple commits, you should make all documentation changes(and nothing else) in the last commit of the series. Otherwise, includethe documentation changes within the single commit.

  • Ensure that each changed file has the correct copyright and licenseinformation. Files that entirely consist of contributions to this projectshould have a copyright notice and BSD-3-Clause SPDX license identifier ofthe form as shown inLicense. Files that contain changes to importedThird Party IP files should retain their original copyright and licensenotices.

    For significant contributions you may add your own copyright notice in thefollowing format:

    Portionscopyright(c)[XXXX-]YYYY,<OWNER>.Allrightsreserved.

    where XXXX is the year of first contribution (if different to YYYY) and YYYYis the year of most recent contribution. <OWNER> is your name or your companyname.

  • Ensure that each patch in the patch series compiles in all supportedconfigurations. Patches which do not compile will not be merged.

  • Please test your changes. As a minimum, ensure that Linux boots on theFoundation FVP. SeeArm Fixed Virtual Platforms (FVP) for moreinformation. For more extensive testing, consider running theTF-A Testsagainst your patches.

  • Ensure that all CI automated tests pass. Failures should be fixed. They mightblock a patch, depending on how critical they are.

3.6.3.Submitting Changes

Note

Please follow theHow to Contribute Code section of the OpenCIdocumentation for general instructions on setting up Gerrit and postingpatches there. The rest of this section provides details about patchsubmission rules specifically for the TF-A project.

  • Submit your changes for review using thegitreview command.

    This will automatically rebase them onto the upstreamintegration branch,as required by TF-A’s patch submission process.

  • From the Gerrit web UI, add reviewers for your patch:

    • At least one code owner for each module modified by the patch. See thelist of modules and theirCode owners.

    • At least one maintainer. See the list ofMaintainers.

    • If some module has no code owner, try to identify a suitable (non-codeowner) reviewer. Runninggitblame on the module’s source code canhelp, as it shows who has been working the most recently on this area ofthe code.

      Alternatively, if it is impractical to identify such a reviewer, you mightsend an email to theTF-A mailing list to broadcast your review requestto the community.

    Note that self-reviewing a patch is prohibited, even if the patch author isthe only code owner of a module modified by the patch. Getting a second pairof eyes on the code is essential to keep up with the quality standards theproject aspires to.

  • The changes will then undergo further review by the designated people. Anyreview comments will be made directly on your patch. This may require you todo some rework. For controversial changes, the discussion might be moved totheTF-A mailing list to involve more of the community.

    Refer to theGerrit Uploading Changes documentation for more details.

  • The patch submission rules are the following. For a patch to be approvedand merged in the tree, it must get:

    • OneCode-Owner-Review+1 for each of the modules modified by the patch.

    • AMaintainer-Review+1.

    In the case where a code owner could not be found for a given module,Code-Owner-Review+1 is substituted byCode-Review+1.

    In addition to these various code review labels, the patch must also get aVerified+1. This is usually set by the Continuous Integration (CI) botwhen all automated tests passed on the patch. Sometimes, some of theseautomated tests may fail for reasons unrelated to the patch. In this case,the maintainers might (after analysis of the failures) override the CI botscore to certify that the patch has been correctly tested.

    In the event where the CI system lacks proper tests for a patch, the patchauthor or a reviewer might agree to perform additional manual testsin their review and the reviewer incorporates the review of the additionaltesting in theCode-Review+1 orCode-Owner-Review+1 as applicable toattest that the patch works as expected. Where possible additional tests shouldbe added to the CI system as a follow up task. For example, for aplatform-dependent patch where the said platform is not available in the CIsystem’s board farm.

  • When the changes are accepted, theMaintainers will integrate them.

    • Typically, theMaintainers will merge the changes into theintegration branch.

    • If the changes are not based on a sufficiently-recent commit, or if theycannot be automatically rebased, then theMaintainers may rebase iton theintegration branch or ask you to do so.

    • After final integration testing, the changes will make their way into themaster branch. If a problem is found during integration, theMaintainers will request your help to solve the issue. They mayrevert your patches and ask you to resubmit a reworked version of them orthey may ask you to provide a fix-up patch.

3.6.4.Add CI Configurations

TF-A uses Jenkins for Continuous Integration and testing activities. Various CIjobs are deployed to run tests on every patch before being merged. Each of yourpatches go through a series of checks before they get merged on to the masterbranch. Kindly ensure that every time you add new files under your platform,they are covered by the following two sections.

3.6.4.1.Coverity Scan

The TF-A project makes use ofCoverity Scan for static analysis, a serviceoffered by Synopsys for open-source projects. This tool is able to find defectsand vulnerabilities in a code base, such as dereferences of NULL pointers, useof uninitialized data, control flow issues and many other things.

The TF-A source code is submitted daily to this service for analysis. Results ofthe latest and previous scans, as well as the complete list of defects itdetected, are accessible online fromhttps://scan.coverity.com/projects/arm-software-arm-trusted-firmware.

Thetf-a-ci-scripts repository contains scripts to run the Coverity Scantools on the integration branch of the TF-A code base and make them available onhttps://scan.coverity.com. These scripts get executed daily by thetf-a-coverity Jenkins job.

In order to maintain a high level of coverage, including on newly introducedcode, it is important to maintain the appropriate TF-A CI scripts. Details ofwhen to update these scripts and how to do so follow.

We maintain a build script -tf-cov-make - which contains the buildconfigurations of various platforms in order to cover the entire source codebeing analysed by Coverity.

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. Inthis case, the job’s console output will show the following error message:

****** Newly added files detection check for Coverity Scan analysis on patch(es) ******Result : FAILURENew source files have been identified in your patch..some/dir/file.cplease ensure to include them for the ``Coverity Scan analysis`` by addingthe respective build configurations in the ``tf-cov-make`` build script.

In this section you find the details on how to append your new buildconfigurations for Coverity scan analysis illustrated with examples:

  1. We maintain a separate repository namedtf-a-ci-scripts repositoryfor placing all the test scripts which will be executed by the CI Jobs.

  2. In this repository,tf-cov-make script is located attf-a-ci-scripts/script/tf-coverity/tf-cov-make

  3. Edit thetf-cov-make script by appending all the possible buildconfigurations with the specific build flags relevant to your platform, sothat newly added source files get built and analysed by Coverity.

  4. For better understanding follow the below specified examples listed in thetf-cov-make script.

Example1:#IntelmakePLAT=stratix10$(common_flags)allmakePLAT=agilex$(common_flags)all

  • In the above example there are two different SoCsstratix andagilexunder the Intel platform and the build configurations has been added suitablyto include most of their source files.

Example2:#HikeymakePLAT=hikey$(common_flags)${TBB_OPTIONS}ENABLE_PMF=1allmakePLAT=hikey960$(common_flags)${TBB_OPTIONS}allmakePLAT=poplar$(common_flags)all

  • In this case forHikey boards additional build flags have been includedalong with thecommon_flags to cover most of the files relevant to it.

  • Similar to this you can still find many other different build configurationsof various other platforms listed in thetf-cov-make script. Kindly referthem and append your build configurations respectively.

3.6.4.2.Test Build Configurations

We have CI jobs which run a set of test configurations on every TF-A patchbefore they get merged upstream.

At the bare minimum, TF-A code should build without any errors for everysupported platform - and every feature of this platform. To make sure this isthe case, we maintain a set of build tests.tf-l1-build-plat is the testgroup which holds all build tests for all platforms. So be kind enough toverify that your newly added files are covered by such a build test.

If this is not the case, please follow the instructions below to add theappropriate files. We will illustrate this with an example for theHikeyplatform.

  • In thetf-a-ci-scripts repository we need to add a build configuration filehikey-default undertf_config/ folder.tf_config/hikey-defaultmust list all the build parameters relevant to it.

# Hikey Build ParametersCROSS_COMPILE=aarch64-none-elf-PLAT=hikey

  • Further another file,hikey-default:nil, needs to be added undergroup/tf-l1-build-plat/ folder to allow the platform to be built as partof this test group.group/tf-l1-build-plat/hikey-default:nil file justneeds to exist but does not contain anything meaningful, apart from amandatory copyright notice:

## Copyright (c) 2019-2022 Arm Limited. All rights reserved.## SPDX-License-Identifier: BSD-3-Clause#

  • 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 howto add more complex tests beyond a simple build test, please refer to theTF-ACI scripts overview section of the OpenCI documentation.

3.6.5.Binary Components

  • Platforms may depend on binary components submitted to theTrusted Firmwarebinary repository if they require code that the contributor is unable orunwilling to open-source. This should be used as a rare exception.

  • All binary components must follow the contribution guidelines (in particularlicensing rules) outlined in thereadme.rst file ofthe binary repository.

  • Binary components must be restricted to only the specific functionality thatcannot be open-sourced and must be linked into a larger open-source platformport. The majority of the platform port must still be implemented in opensource. Platform ports that are merely a thin wrapper around a binarycomponent that contains all the actual code will not be accepted.

  • Only platform port code (i.e. in theplat/<vendor> directory) may rely onbinary components. Generic code must always be fully open-source.

Copyright (c) 2013-2024, Arm Limited and Contributors. All rights reserved.