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
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
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
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>
- 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>
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>
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>
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>
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>
Several code blocks do not specify a language for syntax
highlighting. This results in Sphinx using a default highlighter
which is Python.
This patch adds the correct language to each code block that doesn't
already specify it.
Change-Id: Icce1949aabfdc11a334a42d49edf55fa673cddc3
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
These are no longer needed as there will always be a table of contents
rendered to the left of every page.
Some of these lists can be quite long and, when opening a page, the
reader sees nothing but a huge list of contents! After this patch,
the document contents are front-and-centre and the contents are
nicely rendered in the sidebar without duplication.
Change-Id: I444754d548ec91d00f2b04e861de8dde8856aa62
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
This patch attempts to standardise the document titles as well as
adding titles to documents that were missing one. The aim is to
remove needless references to "TF-A" or "Trusted Firmware" in the
title of every document and to make sure that the title matches
with the document content.
Change-Id: I9b93ccf43b5d57e8dc793a5311b8ed7c4dd245cc
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
This change creates the following directories under docs/
in order to provide a grouping for the content:
- components
- design
- getting_started
- perf
- process
In each of these directories an index.rst file is created
and this serves as an index / landing page for each of the
groups when the pages are compiled. Proper layout of the
top-level table of contents relies on this directory/index
structure.
Without this patch it is possible to build the documents
correctly with Sphinx but the output looks messy because
there is no overall hierarchy.
Change-Id: I3c9f4443ec98571a56a6edf775f2c8d74d7f429f
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
2019-05-21 15:05:56 +01:00
Renamed from docs/coding-guidelines.rst (Browse further)
