docs: code review guidelines ...

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>

Merge "doc: Recommend using C rather than assembly language" into integration

doc: Improve contribution guidelines ...

- 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>

Merge "doc: Minor formatting improvement in the coding guidelines document" into integration

doc: Recommend using C rather than assembly language ...

Add a section for that in the coding guidelines.

Change-Id: Ie6819c4df5889a861460eb96acf2bc9c0cfb494e
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

doc: Minor formatting improvement in the coding guidelines document ...

Change-Id: I5362780db422772fd547dc8e68e459109edccdd0
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

doc: Refactor the contribution guidelines ...

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>

doc: Emphasize that security issues must not be reported as normal bugs ...

Change-Id: I43e452c9993a8608b20ec029562982f5dcf8e6b2
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

doc: Stop advising the creation of Phabricator issues ...

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>

Redirect security incident report to TrustedFirmware.org ...

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>

doc: Update various process documents ...

Most of the changes consist in using the new code owners terminology
(from [1]).

[1] https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/

Change-Id: Icead20e9335af12aa47d3f1ac5d04ca157b20c82
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

Update docs with PMU security information ...

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

doc: Split and expand coding style documentation ...

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>

Remove -Wpadded warning ...

-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>

Merge "Remove unnecessary warning options" into integration

doc: Split the User Guide into multiple files ...

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>

Remove unnecessary warning options ...

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>

doc: Move "About" content from index.rst to a new chapter ...

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>

doc: Misc syntax and spelling fixes ...

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>

doc: Convert internal links to RST format ...

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>

Merge "Fix RST rendering problem" into integration

Fix RST rendering problem ...

Change-Id: Ic5aab23b549d0bf8e0f7053b46fd59243214aac1
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>

docs: removing references to GitHub ...

Change-Id: Ibdee91ad337ee362872924d93e82f5b5e47e63d9
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>

Merge changes from topic "banned_api_list" into integration ...

* changes:
  Fix the License header template in imx_aipstz.c
  docs: Add the list of banned/use with caution APIs

docs: Add the list of banned/use with caution APIs ...

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>

Fix links in documentation ...

Change-Id: Ifef4d634b4a34d23f42f61df5e326a1cc05d3844
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>

doc: Isolate security-related build options ...

Reference security specific build options from the user guide.

Change-Id: I0e1efbf47d914cf3c473104175c702ff1a80eb67
Signed-off-by: Ambroise Vincent <ambroise.vincent@arm.com>

Further fixes to documentation links ...

Change-Id: Ib021c721652d96f6c06ea18741f19a72bba1d00f
Signed-off-by: John Tsichritzis <john.tsichritzis@arm.com>

Update security documentation ...

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>

doc: Use proper note and warning annotations ...

The documentation contains plenty of notes and warnings. Enable
special rendering of these blocks by converting the note prefix
into a .. note:: annotation.

Change-Id: I34e26ca6bf313d335672ab6c2645741900338822
Signed-off-by: Paul Beesley <paul.beesley@arm.com>