Phabricator wiki is deprecated, remove TF-A links to this website.
Signed-off-by: Olivier Deprez <olivier.deprez@arm.com>
Change-Id: I1255a1513524504636b9c914f9dacf3c54063196
- Warn contributors that they need to register their email address in
their Gerrit profile. Not doing so causes errors at patch submission
and is a recurrent question on the mailing list.
- Add some links where useful.
- Remove confusing CGit link to TF-A source code. In the context of
setting up a local copy of the repo for contributing patches,
developers should rather clone it through Gerrit and this is best
covered by the "Getting the TF-A Source" section of TF-A
documentation.
- Add references to the OpenCI documentation, which has a lot more
details on some of the topics we briefly cover in the contribution
guidelines.
- Encourage the user to use the 'git review' command for patch
submission, inline with OpenCI documentation instructions. This
automatically sorts out which Gerrit server to push to and against
which repo branch (thanks to the '.gitreview' configuration file in
TF-A root directory).
- Elaborate the Coverity Scan section.
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Change-Id: I1131662d8bc3502967b269a599869ea130897efb
TF-A aims to comply with MISRA C:2012 Guidelines. We maintain a list of
all rules and directives and whether the project aims to comply with
them or not. A rationale is given for each deviation.
This list used to be provided as an '.ods' spreadsheet file hosted on
developer.trustedfirmware.org. This raises the following issues:
- The list is not version-controlled under the same scheme as TF-A
source code. This could lead to synchronization issues between the
two.
- The file needs to be open in a separate program, which is not as
straightforward as reading it from TF-A documentation itself.
- developer.trustedfirmware.org is deprecated, thus the file cannot be
safely kept there for any longer.
To address these issues, convert the '.ods' file into a CSV (Comma
Separated Values) file, which we import into TF-A source tree itself.
Make use of Sphinx's ability to process and render CSV files as tables
to display that information directly into the Coding Guidelines
document.
Also make the following minor changes along the way:
- Remove dead link to MISRA C:2012 Guidelines page. Replace it with a
link to a Wikipedia page to give a bit of context to the reader.
- We no longer use Coverity for MISRA compliance checks. Instead, we
use ECLAIR nowadays. Reflect this in the document.
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Change-Id: I422fdd8246f4f9c2498c1be18115408a873b86ac
developer.trustedfirmware.org is deprecated so we cannot use its issues
tracker anymore. Instead, the project will now make use of the issues
tracker associated with the project's Github mirror at [1].
Reflect this change in TF-A documentation.
[1] https://github.com/TrustedFirmware-A/trusted-firmware-a/issues
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Change-Id: I912f7dafc74368dba4e61ba4c9f358d5bf8346a9
tf.org-wide documents have been migrated away from
developer.trustedfirmware.org, because the latter will be
decomissioned at some point in the future. These documents are now
hosted in a new 'tf_docs' repository hosted on Github [1] and can be
easily browsed through a new ReadTheDocs website at [2].
Update all relevant links in TF-A documentation to refer to [2].
[1] https://github.com/TrustedFirmware/tf_docs
[2] https://trusted-firmware-docs.readthedocs.io/
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Change-Id: Ib9d39c36250a05754fe5e46cb6f3044ecb776534
The ability to read a character from the console constitutes an attack
vector into TF-A, as it gives attackers a means to inject arbitrary
data into TF-A. It is dangerous to keep that feature enabled if not
strictly necessary, especially in production firmware builds.
Thus, we need a way to disable this feature. Moreover, when it is
disabled, all related code should be eliminated from the firmware
binaries, such that no remnant/dead getc() code remains in memory,
which could otherwise be used as a gadget as part of a bigger security
attack.
This patch disables getc() feature by default. For legitimate getc()
use cases [1], it can be explicitly enabled by building TF-A with
ENABLE_CONSOLE_GETC=1.
The following changes are introduced when getc() is disabled:
- The multi-console framework no longer provides the console_getc()
function.
- If the console driver selected by the platform attempts to register
a getc() callback into the multi-console framework then TF-A will
now fail to build.
If registered through the assembly function finish_console_register():
- On AArch64, you'll get:
Error: undefined symbol CONSOLE_T_GETC used as an immediate value.
- On AArch32, you'll get:
Error: internal_relocation (type: OFFSET_IMM) not fixed up
If registered through the C function console_register(), this requires
populating a struct console with a getc field, which will trigger:
error: 'console_t' {aka 'struct console'} has no member named 'getc'
- All console drivers which previously registered a getc() callback
have been modified to do so only when ENABLE_CONSOLE_GETC=1.
[1] Example of such use cases would be:
- Firmware recovery: retrieving a golden BL2 image over the console in
order to repair a broken firmware on a bricked board.
- Factory CLI tool: Drive some soak tests through the console.
Discussed on TF-A mailing list here:
https://lists.trustedfirmware.org/archives/list/tf-a@lists.trustedfirmware.org/thread/YS7F6RCNTWBTEOBLAXIRTXWIOYINVRW7/
Change-Id: Icb412304cd23dbdd7662df7cf8992267b7975cc5
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Acked-by: Baruch Siach <baruch@tkos.co.il>
- Fix the name of the user account under which the CI bot posts
review comments.
- The CI has now transitioned to trustedfirmware.org so CI results
are publically accessible.
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Change-Id: I53dd93e200c9e119b5df6bbaf2644485cde57ce5
The code review guidelines have been updated to explain when
patches that do not receive a response to the review comments
will be abandoned.
Change-Id: I60539e16ca41245cf1b352f24557be1b3c67c367
Signed-off-by: Manish V Badarkhe <Manish.Badarkhe@arm.com>
Assembly language is rarely required and when it is, there are a lot of
helpers available to reduce the amount needed. Update the guidelines to
give pointers to them.
Signed-off-by: Boyan Karatotev <boyan.karatotev@arm.com>
Change-Id: Ic484e4ba57242594c351a9185ecb625d6e5dc223
Add a new page in TF-A documentation for clarifying the process to
elect a new maintainer. This builds on top of the Trusted Firmware
process [1], with the following TF-A specific details:
- Must have contributed to the project for at least a couple of years.
- Must dedicate at least 2 hours a week for maintainer duties.
- Details about the election process. In particular, setting a
one-calendar-week deadline for other maintainers to raise
objections.
[1] https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Change-Id: Ibef08bbbd4d18cd7aea13e01ba570972a7ee808d
Our process documentation already mentions that if a platform is no
longer maintained, it is best to deprecate it to keep the project's
source tree clean and healthy.
The same argument stands for drivers or library interfaces so extend
this policy to those.
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Change-Id: Ieb235d6a1fb089343e0e1e3e5f36067552f2f8f0
Clarify that downstream platforms generally do not affect code
deprecation / removal decisions.
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Change-Id: I44b979c4e67ee03537852769e96544e19137bda3
Currently there is no guidelines in docs for including thirdparty
includes, trying to address that with a proposed method to use third
party includes.
Change-Id: Ieec7a5c88a60b66ca72228741ba1894545130a06
Signed-off-by: Govindraj Raja <govindraj.raja@arm.com>
As a coding guideline, we now discourage introducing new weak
functions in platform-agnostic code going forward and provide the
rationale for this.
This was already enforced most of the time in code reviews but this
patch makes it explicit in the project's documentation.
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Change-Id: I88f4a55788899fb4146c4d26afb3a7418376b30c
Added few missed links for Security Advisories.
Change-Id: I9cab72b70a518273cbb1a291142f452198427127
Signed-off-by: Manish V Badarkhe <Manish.Badarkhe@arm.com>
Our documentation currently says that new security advisories will be
announced on the project's issue tracker. However, this issue tracker
is barely used by TF-A community and the software it is based on is
getting deprecated. Thus from now on, security advisories will rather
be announced on the project's mailing list.
Update TF-A documentation to reflect that.
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Change-Id: If2f635795e0af4c794015a025899bfcc7116ab38
When -Wextra was added, the warning levels changed their meaning. Add a
description in the build option section and leave the security hardening
section as mostly a pointer to it.
Signed-off-by: Boyan Karatotev <boyan.karatotev@arm.com>
Change-Id: Iabf2f598d0bf3e865c9b991c5d44d2acb9572bd5
Top level sections are not numbered. Adding numbers makes referring to
sections easier. For example the Maintainers page changes from
"about/3.1" to simply "1.3.1".
Signed-off-by: Boyan Karatotev <boyan.karatotev@arm.com>
Change-Id: If90a18ee8d6a6858d58f0687f31ea62b69399e04
Couple for urls under section: `5.6. Use of built-in C and libc
data types` from docs has broken urls since the new arm procedure
call doc is moved to be part of `ARM-software/abi-aa`.
Change-Id: Ied184ed56c8335d4cbc687e56962439091a18e42
Signed-off-by: Govindraj Raja <govindraj.raja@arm.com>
We used to have a dedicated page for deprecated platforms information.
This document contained 2 pieces of information:
a) the process for deprecating a platform port;
b) the list of deprecated platforms to this day.
I think it makes more sense to move b) to the platforms ports landing
page, such that it is more visible.
This also has the nice effect to move the 'Deprecated platforms' title
as the last entry of the 'Platform ports' table of contents, like so:
- Platform ports
- 1. Allwinner ARMv8 SoCs
- 2. Arm Development Platforms
...
- 39. Broadcom Stingray
- Deprecated platforms
instead of it being lost in the middle of supported platform ports.
Regarding a), this gets moved under the "Processes & Policies" section.
More specifically, it gets clubbed with the existing platform
compatibility policy. The combined document gets renamed into a
"Platforms Ports Policy" document.
Change-Id: I6e9ce2abc68b8a8ac88e7bd5f21749c14c9a2af6
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
The link to the Developer Certificate of Origin was mistakenly removed
in a patch some time ago. This change re-adds it.
Change-Id: Ia8aed055cb449cdf4c1aaeac9b81ca15099e73f5
Signed-off-by: Chris Kay <chris.kay@arm.com>
With the transition to mailman3, the URLs of TF-A and TF-A Tests
mailing lists have changed. However, we still refer to the old
location, which are now dead links.
Update all relevant links throughout the documentation.
There is one link referring to a specific thread on the TF-A mailing
list in the SPM documentation, for which I had to make a guess as to
what's the equivalent mailman3 URL. The old URL scheme indicates that
the thread dates from February 2020 but beyond that, I could not make
sense of the thread id within the old URL so I picked the most likely
match amongst the 3 emails posted on the subject in this time period.
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Reported-by: Kuohong Wang <kuohong.wang@mediatek.com>
Change-Id: I83f4843afd1dd46f885df225931d8458152dbb58
Added a couple of sub-sections (Coverity Scan and Test Configuration)
under "Add build configuration" to update the patch owners on the
sections they need to be aware of while introducing new source files.
Signed-off-by: Jayanth Dodderi Chidanand <jayanthdodderi.chidanand@arm.com>
Change-Id: I84adb182f9633863aac864df43578249c2269c1e
This change replaces cz-conventional-changelog with cz-commitlint, which
automatically configures Commitizen using our commitlint configuration
file. Currently, we use some manual Javascript magic to load our
Commitizen configuration into commitlint (the opposite of what's
introduced by this change), which can be removed.
With this change, we also move our commitlint configuration into a
new `changelog.yaml` file. This file holds the same data as `.cz.json`
previously did.
Change-Id: I14ff2308f1a0b2b293c2128b28ca2df578ce9c1c
Signed-off-by: Chris Kay <chris.kay@arm.com>
This change adds a new documentation page describing the commit style,
acceptable Conventional Commits types and scopes, and documents the
process for expanding the list of scopes.
Change-Id: Iad957b67fa71a879e8aa0790c58a5b08cec300d6
Signed-off-by: Chris Kay <chris.kay@arm.com>
This patch will fix the formatting errors concerning code snippet,
lines 245 and 256 respectively.
The code snippet is updated to 'shell' to lex it appropriately.
Signed-off-by: Jayanth Dodderi Chidanand <jayanthdodderi.chidanand@arm.com>
Change-Id: I53aefd81da350b6511e7a97b5fee7b0d6f9dde2d
Added a sub-section in the "Processes and Policies" chapter under
Contributor's guide on how to add new build configurations when new
source files are added to the TF-A repository. This will help the patch
contributor to update their files to get analysed by Coverity Scan.
Signed-off-by: Jayanth Dodderi Chidanand <jayanthdodderi.chidanand@arm.com>
Change-Id: I71f410a061028f89bd0e984e48e61e5935616d71
This change adds a configuration for commitlint - a tool designed to
enforce a particular commit message style - and run it as part of Git's
commit-msg hook. This validates commits immediately after the editor has
been exited, and the configuration is derived from the configuration we
provide to Commitizen.
While the configuration provided suggests a maximum header and body
length, neither of these are hard errors. This is to accommodate the
occasional commit where it may be difficult or impossible to comply
with the length requirements (for example, with a particularly long
scope, or a long URL in the message body).
Change-Id: Ib5e90472fd1f1da9c2bff47703c9682232ee5679
Signed-off-by: Chris Kay <chris.kay@arm.com>
Fix a number of typos and misspellings in TF-A
documentation and comments.
Signed-off-by: David Horstmann <david.horstmann@arm.com>
Change-Id: I34c5a28c3af15f28d1ccada4d9866aee6af136ee
Document the code review process in TF-A.
Specifically:
* Give an overview of code review and best practices.
* Give guidelines for the participants in code review.
* Outline responsibilities of each type of participant.
* Explain the Gerrit labels used in the review process.
Change-Id: I519ca4b2859601a7b897706e310f149a0c92e390
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Signed-off-by: David Horstmann <david.horstmann@arm.com>
- Add some guidance about the type of information a patch author should
provide to facilitate the review (and for future reference).
- Make a number of implicit expectations explicit:
- Every patch must compile.
- All CI tests must pass.
- Mention that the patch author is expected to add reviewers and explain
how to choose them.
- Explain the patch submission rules in terms of Gerrit labels.
Also do some cosmetic changes, like adding empty lines, shuffling some
paragraphs around.
Change-Id: I6dac486684310b5a35aac7353e10fe5474a81ec5
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Add a section for that in the coding guidelines.
Change-Id: Ie6819c4df5889a861460eb96acf2bc9c0cfb494e
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Ensuring that each file changed by a patch has the correct copyright and
license information does not only apply to documentation files but to
all files within the source tree.
Move the guidance for copyright and license headers out of the paragraph
about updating the documentation to avoid any confusion.
Also do some cosmetic changes (adding empty lines, fitting in longer
lines in the 80-column limit, ...) to improve the readability of the RST
file.
Change-Id: I241a2089ca9db70f5a9f26b7070b947674b43265
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
We have noticed that Phabricator (the ticketing system on tf.org [1])
has far less visibility within the community than the mailing list [2].
For this reason, let's drop usage of Phabricator for anything else than
bug reports. For the rest, advise contributors to start a discussion on
the mailing list, where they are more likely to get feedback.
[1] https://developer.trustedfirmware.org/project/board/1/
[2] https://lists.trustedfirmware.org/mailman/listinfo/tf-a
Change-Id: I7d2d3d305ad0a0f8aacc2a2f25eb5ff429853a3f
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
All projects under the TrustedFirmware.org project now use the same
security incident process, therefore update the disclosure/vulnerability
reporting information in the TF-A documentation.
------------------------------------------------------------------------
/!\ IMPORTANT /!\
Please note that the email address to send these reports to has changed.
Please do *not* use trusted-firmware-security@arm.com anymore.
Similarly, the PGP key provided to encrypt emails to the security email
alias has changed as well. Please do *not* use the former one provided
in the TF-A source tree. It is recommended to remove it from your
keyring to avoid any mistake. Please use the new key provided on
TrustedFirmware.org from now on.
------------------------------------------------------------------------
Change-Id: I14eb61017ab99182f1c45d1e156b96d5764934c1
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
This patch adds information on the PMU configuration registers
and security considerations related to the PMU.
Signed-off-by: Petre-Ionut Tudor <petre-ionut.tudor@arm.com>
Change-Id: I36b15060b9830a77d3f47f293c0a6dafa3c581fb
This patch expands the coding style documentation, splitting it
into two documents: the core style rules and extended guidelines.
Note that it does not redefine or change the coding style (aside
from section 4.6.2) - generally, it is only documenting the
existing style in more detail.
The aim is for the coding style to be more readable and, in turn,
for it to be followed by more people. We can use this as a more
concrete reference when discussing the accepted style with external
contributors.
Change-Id: I87405ace9a879d7f81e6b0b91b93ca69535e50ff
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
Signed-off-by: Petre-Ionut Tudor <petre-ionut.tudor@arm.com>
-Wpadded warns whenever the C compiler automatically includes any
padding in a structure. Because TF-A has a large number of structures,
this occurs fairly frequently and is incredibly verbose, and as such is
unlikely to ever be fixed.
The utility of this warning is also extremely limited - knowing that a
structure includes padding does not point to the existence of an error,
and is probably quite unlikely to indicate actually buggy behaviour.
Therefore, it's probably best to keep this warning off at all times.
Change-Id: I0797cb75f06b4fea0d2fdc16fd5ad978a31d76ec
Signed-off-by: Justin Chadwell <justin.chadwell@arm.com>
