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>
The User Guide document has grown organically over time and
now covers a wide range of topics, making it difficult to
skim read and extract information from. Currently, it covers
these topics and maybe a couple more:
- Requirements (hardware, tools, libs)
- Checking out the repo
- Basic build instructions
- A comprehensive list of build flags
- FIP packaging
- Building specifically for Juno
- Firmware update images
- EL3 payloads
- Preloaded BL33 boot flow
- Running on FVPs
- Running on Juno
I have separated these out into a few groups that become new
documents. Broadly speaking, build instructions for the tools,
for TF-A generally, and for specific scenarios are separated.
Content relating to specific platforms (Juno and the FVPs are
Arm-specific platforms, essentially) has been moved into the
documentation that is specific to those platforms, under
docs/plat/arm.
Change-Id: Ica87c52d8cd4f577332be0b0738998ea3ba3bbec
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
Both -Wmissing-field-initializers and -Wsign-compare are both covered by
-Wextra which is enabled at W=1 anyway. Therefore, the explicit options
are not required.
Change-Id: I2e7d95b5fc14af7c70895859a7ebbeac5bc0d2a4
Signed-off-by: Justin Chadwell <justin.chadwell@arm.com>
The index.rst page is now the primary landing page for the TF-A
documentation. It contains quite a lot of content these days,
including:
- The project purpose and general intro
- A list of functionality
- A list of planned functionality
- A list of supported platforms
- "Getting started" links to other documents
- Contact information for raising issues
This patch creates an "About" chapter in the table
of contents and moves some content there. In order,
the above listed content:
- Stayed where it is. This is the right place for it.
- Moved to About->Features
- Moved to About->Features (in subsection)
- Stayed where it is. Moved in a later patch.
- Was expanded in-place
- Moved to About->Contact
Change-Id: I254bb87560fd09140b9e485cf15246892aa45943
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
Tidying up a few Sphinx warnings that had built-up over time.
None of these are critical but it cleans up the Sphinx output.
At the same time, fixing some spelling errors that were detected.
Change-Id: I38209e235481eed287f8008c6de9dedd6b12ab2e
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
Currently links between documents are using the format:
<path/to/><filename>.rst
This was required for services like GitHub because they render each
document in isolation - linking to another document is like linking
to any other file, just provide the full path.
However, with the new approach, the .rst files are only the raw
source for the documents. Once the documents have been rendered
the output is now in another format (HTML in our case) and so,
when linking to another document, the link must point to the
rendered version and not the .rst file.
The RST spec provides a few methods for linking between content.
The parent of this patch enabled the automatic creation of anchors
for document titles - we will use these anchors as the targets for
our links. Additional anchors can be added by hand if needed, on
section and sub-section titles, for example.
An example of this new format, for a document with the title
"Firmware Design" is :ref:`Firmware Design`.
One big advantage of this is that anchors are not dependent on
paths. We can then move documents around, even between directories,
without breaking any links between documents. Links will need to be
updated only if the title of a document changes.
Change-Id: I9e2340a61dd424cbd8fd1ecc2dc166f460d81703
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
Credit to sam.ellis@arm.com for the input to create the list.
Change-Id: Id70a8eddc5f2490811bebb278482c61950f10cce
Signed-off-by: Soby Mathew <soby.mathew@arm.com>
Reference security specific build options from the user guide.
Change-Id: I0e1efbf47d914cf3c473104175c702ff1a80eb67
Signed-off-by: Ambroise Vincent <ambroise.vincent@arm.com>
1) Replace references to "Arm Trusted Firmware" with "TF-A"
2) Update issue tracker link
Change-Id: I12d827d49f6cc34e46936d7f7ccf44e32b26a0bd
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>
Sandrine Bailleux
Manish V Badarkhe
Boyan Karatotev
Govindraj Raja
Chris Kay
Jayanth Dodderi Chidanand
David Horstmann
Petre-Ionut Tudor
Paul Beesley
Justin Chadwell
John Tsichritzis
Soby Mathew
Ambroise Vincent