diff options
author | Paul Beesley <paul.beesley@arm.com> | 2019-02-11 17:54:45 +0000 |
---|---|---|
committer | Paul Beesley <paul.beesley@arm.com> | 2019-05-21 15:05:56 +0100 |
commit | 40d553cfde38d4f68449c62967cd1ce0d6478750 (patch) | |
tree | 1fafd4701066cdf0e5fb15aee2d842279a67b611 /docs/process | |
parent | 12b67439e93a78a4b756e987e1bd1b6e22cc4bf8 (diff) |
doc: Move documents into subdirectories
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>
Diffstat (limited to 'docs/process')
-rw-r--r-- | docs/process/coding-guidelines.rst | 554 | ||||
-rw-r--r-- | docs/process/contributing.rst | 149 | ||||
-rw-r--r-- | docs/process/faq.rst | 79 | ||||
-rw-r--r-- | docs/process/index.rst | 14 | ||||
-rw-r--r-- | docs/process/platform-compatibility-policy.rst | 44 | ||||
-rw-r--r-- | docs/process/release-information.rst | 89 | ||||
-rw-r--r-- | docs/process/security-center.rst | 103 | ||||
-rw-r--r-- | docs/process/security-reporting.asc | 45 |
8 files changed, 1077 insertions, 0 deletions
diff --git a/docs/process/coding-guidelines.rst b/docs/process/coding-guidelines.rst new file mode 100644 index 00000000..644f8288 --- /dev/null +++ b/docs/process/coding-guidelines.rst @@ -0,0 +1,554 @@ +Trusted Firmware-A Coding Guidelines +==================================== + + + +.. contents:: + +The following sections contain TF coding guidelines. They are continually +evolving and should not be considered "set in stone". Feel free to question them +and provide feedback. + +Some of the guidelines may also apply to other codebases. + +**Note:** the existing TF codebase does not necessarily comply with all the +below guidelines but the intent is for it to do so eventually. + +Checkpatch overrides +-------------------- + +Some checkpatch warnings in the TF codebase are deliberately ignored. These +include: + +- ``**WARNING: line over 80 characters**``: Although the codebase should + generally conform to the 80 character limit this is overly restrictive in some + cases. + +- ``**WARNING: Use of volatile is usually wrong``: see + `Why the “volatile” type class should not be used`_ . Although this document + contains some very useful information, there are several legimate uses of the + volatile keyword within the TF codebase. + +Headers and inclusion +--------------------- + +Header guards +^^^^^^^^^^^^^ + +For a header file called "some_driver.h" the style used by the Trusted Firmware +is: + +.. code:: c + + #ifndef SOME_DRIVER_H + #define SOME_DRIVER_H + + <header content> + + #endif /* SOME_DRIVER_H */ + +Include statement ordering +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +All header files that are included by a source file must use the following, +grouped ordering. This is to improve readability (by making it easier to quickly +read through the list of headers) and maintainability. + +#. *System* includes: Header files from the standard *C* library, such as + ``stddef.h`` and ``string.h``. + +#. *Project* includes: Header files under the ``include/`` directory within TF + are *project* includes. + +#. *Platform* includes: Header files relating to a single, specific platform, + and which are located under the ``plat/<platform_name>`` directory within TF, + are *platform* includes. + +Within each group, ``#include`` statements must be in alphabetical order, +taking both the file and directory names into account. + +Groups must be separated by a single blank line for clarity. + +The example below illustrates the ordering rules using some contrived header +file names; this type of name reuse should be otherwise avoided. + +.. code:: c + + #include <string.h> + + #include <a_dir/example/a_header.h> + #include <a_dir/example/b_header.h> + #include <a_dir/test/a_header.h> + #include <b_dir/example/a_header.h> + + #include "./a_header.h" + +Include statement variants +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Two variants of the ``#include`` directive are acceptable in the TF codebase. +Correct use of the two styles improves readability by suggesting the location +of the included header and reducing ambiguity in cases where generic and +platform-specific headers share a name. + +For header files that are in the same directory as the source file that is +including them, use the ``"..."`` variant. + +For header files that are **not** in the same directory as the source file that +is including them, use the ``<...>`` variant. + +Example (bl1_fwu.c): + +.. code:: c + + #include <assert.h> + #include <errno.h> + #include <string.h> + + #include "bl1_private.h" + +Platform include paths +^^^^^^^^^^^^^^^^^^^^^^ + +Platforms are allowed to add more include paths to be passed to the compiler. +The ``PLAT_INCLUDES`` variable is used for this purpose. This is needed in +particular for the file ``platform_def.h``. + +Example: + +.. code:: c + + PLAT_INCLUDES += -Iinclude/plat/myplat/include + +Types and typedefs +------------------ + +Use of built-in *C* and *libc* data types +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The TF codebase should be kept as portable as possible, especially since both +64-bit and 32-bit platforms are supported. To help with this, the following data +type usage guidelines should be followed: + +- Where possible, use the built-in *C* data types for variable storage (for + example, ``char``, ``int``, ``long long``, etc) instead of the standard *C99* + types. Most code is typically only concerned with the minimum size of the + data stored, which the built-in *C* types guarantee. + +- Avoid using the exact-size standard *C99* types in general (for example, + ``uint16_t``, ``uint32_t``, ``uint64_t``, etc) since they can prevent the + compiler from making optimizations. There are legitimate uses for them, + for example to represent data of a known structure. When using them in struct + definitions, consider how padding in the struct will work across architectures. + For example, extra padding may be introduced in AArch32 systems if a struct + member crosses a 32-bit boundary. + +- Use ``int`` as the default integer type - it's likely to be the fastest on all + systems. Also this can be assumed to be 32-bit as a consequence of the + `Procedure Call Standard for the Arm Architecture`_ and the `Procedure Call + Standard for the Arm 64-bit Architecture`_ . + +- Avoid use of ``short`` as this may end up being slower than ``int`` in some + systems. If a variable must be exactly 16-bit, use ``int16_t`` or + ``uint16_t``. + +- Avoid use of ``long``. This is guaranteed to be at least 32-bit but, given + that `int` is 32-bit on Arm platforms, there is no use for it. For integers of + at least 64-bit, use ``long long``. + +- Use ``char`` for storing text. Use ``uint8_t`` for storing other 8-bit data. + +- Use ``unsigned`` for integers that can never be negative (counts, + indices, sizes, etc). TF intends to comply with MISRA "essential type" coding + rules (10.X), where signed and unsigned types are considered different + essential types. Choosing the correct type will aid this. MISRA static + analysers will pick up any implicit signed/unsigned conversions that may lead + to unexpected behaviour. + +- For pointer types: + + - If an argument in a function declaration is pointing to a known type then + simply use a pointer to that type (for example: ``struct my_struct *``). + + - If a variable (including an argument in a function declaration) is pointing + to a general, memory-mapped address, an array of pointers or another + structure that is likely to require pointer arithmetic then use + ``uintptr_t``. This will reduce the amount of casting required in the code. + Avoid using ``unsigned long`` or ``unsigned long long`` for this purpose; it + may work but is less portable. + + - For other pointer arguments in a function declaration, use ``void *``. This + includes pointers to types that are abstracted away from the known API and + pointers to arbitrary data. This allows the calling function to pass a + pointer argument to the function without any explicit casting (the cast to + ``void *`` is implicit). The function implementation can then do the + appropriate casting to a specific type. + + - Use ``ptrdiff_t`` to compare the difference between 2 pointers. + +- Use ``size_t`` when storing the ``sizeof()`` something. + +- Use ``ssize_t`` when returning the ``sizeof()`` something from a function that + can also return an error code; the signed type allows for a negative return + code in case of error. This practice should be used sparingly. + +- Use ``u_register_t`` when it's important to store the contents of a register + in its native size (32-bit in AArch32 and 64-bit in AArch64). This is not a + standard *C99* type but is widely available in libc implementations, + including the FreeBSD version included with the TF codebase. Where possible, + cast the variable to a more appropriate type before interpreting the data. For + example, the following struct in ``ep_info.h`` could use this type to minimize + the storage required for the set of registers: + +.. code:: c + + typedef struct aapcs64_params { + u_register_t arg0; + u_register_t arg1; + u_register_t arg2; + u_register_t arg3; + u_register_t arg4; + u_register_t arg5; + u_register_t arg6; + u_register_t arg7; + } aapcs64_params_t; + +If some code wants to operate on ``arg0`` and knows that it represents a 32-bit +unsigned integer on all systems, cast it to ``unsigned int``. + +These guidelines should be updated if additional types are needed. + +Avoid anonymous typedefs of structs/enums in headers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For example, the following definition: + +.. code:: c + + typedef struct { + int arg1; + int arg2; + } my_struct_t; + + +is better written as: + +.. code:: c + + struct my_struct { + int arg1; + int arg2; + }; + +This allows function declarations in other header files that depend on the +struct/enum to forward declare the struct/enum instead of including the +entire header: + +.. code:: c + + #include <my_struct.h> + void my_func(my_struct_t *arg); + +instead of: + +.. code:: c + + struct my_struct; + void my_func(struct my_struct *arg); + +Some TF definitions use both a struct/enum name **and** a typedef name. This +is discouraged for new definitions as it makes it difficult for TF to comply +with MISRA rule 8.3, which states that "All declarations of an object or +function shall use the same names and type qualifiers". + +The Linux coding standards also discourage new typedefs and checkpatch emits +a warning for this. + +Existing typedefs will be retained for compatibility. + +Error handling and robustness +----------------------------- + +Using CASSERT to check for compile time data errors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Where possible, use the ``CASSERT`` macro to check the validity of data known at +compile time instead of checking validity at runtime, to avoid unnecessary +runtime code. + +For example, this can be used to check that the assembler's and compiler's views +of the size of an array is the same. + +.. code:: c + + #include <cassert.h> + + define MY_STRUCT_SIZE 8 /* Used by assembler source files */ + + struct my_struct { + uint32_t arg1; + uint32_t arg2; + }; + + CASSERT(MY_STRUCT_SIZE == sizeof(struct my_struct), assert_my_struct_size_mismatch); + + +If ``MY_STRUCT_SIZE`` in the above example were wrong then the compiler would +emit an error like this: + +.. code:: c + + my_struct.h:10:1: error: size of array ‘assert_my_struct_size_mismatch’ is negative + + +Using assert() to check for programming errors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In general, each secure world TF image (BL1, BL2, BL31 and BL32) should be +treated as a tightly integrated package; the image builder should be aware of +and responsible for all functionality within the image, even if code within that +image is provided by multiple entities. This allows us to be more aggressive in +interpreting invalid state or bad function arguments as programming errors using +``assert()``, including arguments passed across platform porting interfaces. +This is in contrast to code in a Linux environment, which is less tightly +integrated and may attempt to be more defensive by passing the error back up the +call stack. + +Where possible, badly written TF code should fail early using ``assert()``. This +helps reduce the amount of untested conditional code. By default these +statements are not compiled into release builds, although this can be overridden +using the ``ENABLE_ASSERTIONS`` build flag. + +Examples: + +- Bad argument supplied to library function +- Bad argument provided by platform porting function +- Internal secure world image state is inconsistent + + +Handling integration errors +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each secure world image may be provided by a different entity (for example, a +Trusted Boot vendor may provide the BL2 image, a TEE vendor may provide the BL32 +image and the OEM/SoC vendor may provide the other images). + +An image may contain bugs that are only visible when the images are integrated. +The system integrator may not even have access to the debug variants of all the +images in order to check if asserts are firing. For example, the release variant +of BL1 may have already been burnt into the SoC. Therefore, TF code that detects +an integration error should _not_ consider this a programming error, and should +always take action, even in release builds. + +If an integration error is considered non-critical it should be treated as a +recoverable error. If the error is considered critical it should be treated as +an unexpected unrecoverable error. + +Handling recoverable errors +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The secure world **must not** crash when supplied with bad data from an external +source. For example, data from the normal world or a hardware device. Similarly, +the secure world **must not** crash if it detects a non-critical problem within +itself or the system. It must make every effort to recover from the problem by +emitting a ``WARN`` message, performing any necessary error handling and +continuing. + +Examples: + +- Secure world receives SMC from normal world with bad arguments. +- Secure world receives SMC from normal world at an unexpected time. +- BL31 receives SMC from BL32 with bad arguments. +- BL31 receives SMC from BL32 at unexpected time. +- Secure world receives recoverable error from hardware device. Retrying the + operation may help here. +- Non-critical secure world service is not functioning correctly. +- BL31 SPD discovers minor configuration problem with corresponding SP. + +Handling unrecoverable errors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In some cases it may not be possible for the secure world to recover from an +error. This situation should be handled in one of the following ways: + +1. If the unrecoverable error is unexpected then emit an ``ERROR`` message and + call ``panic()``. This will end up calling the platform-specific function + ``plat_panic_handler()``. +2. If the unrecoverable error is expected to occur in certain circumstances, + then emit an ``ERROR`` message and call the platform-specific function + ``plat_error_handler()``. + +Cases 1 and 2 are subtly different. A platform may implement ``plat_panic_handler`` +and ``plat_error_handler`` in the same way (for example, by waiting for a secure +watchdog to time-out or by invoking an interface on the platform's power +controller to reset the platform). However, ``plat_error_handler`` may take +additional action for some errors (for example, it may set a flag so the +platform resets into a different mode). Also, ``plat_panic_handler()`` may +implement additional debug functionality (for example, invoking a hardware +breakpoint). + +Examples of unexpected unrecoverable errors: + +- BL32 receives an unexpected SMC response from BL31 that it is unable to + recover from. +- BL31 Trusted OS SPD code discovers that BL2 has not loaded the corresponding + Trusted OS, which is critical for platform operation. +- Secure world discovers that a critical hardware device is an unexpected and + unrecoverable state. +- Secure world receives an unexpected and unrecoverable error from a critical + hardware device. +- Secure world discovers that it is running on unsupported hardware. + +Examples of expected unrecoverable errors: + +- BL1/BL2 fails to load the next image due to missing/corrupt firmware on disk. +- BL1/BL2 fails to authenticate the next image due to an invalid certificate. +- Secure world continuously receives recoverable errors from a hardware device + but is unable to proceed without a valid response. + +Handling critical unresponsiveness +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the secure world is waiting for a response from an external source (for +example, the normal world or a hardware device) which is critical for continued +operation, it must not wait indefinitely. It must have a mechanism (for example, +a secure watchdog) for resetting itself and/or the external source to prevent +the system from executing in this state indefinitely. + +Examples: + +- BL1 is waiting for the normal world to raise an SMC to proceed to the next + stage of the secure firmware update process. +- A Trusted OS is waiting for a response from a proxy in the normal world that + is critical for continued operation. +- Secure world is waiting for a hardware response that is critical for continued + operation. + +Security considerations +----------------------- + +Part of the security of a platform is handling errors correctly, as described in +the previous section. There are several other security considerations covered in +this section. + +Do not leak secrets to the normal world +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The secure world **must not** leak secrets to the normal world, for example in +response to an SMC. + +Handling Denial of Service attacks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The secure world **should never** crash or become unusable due to receiving too +many normal world requests (a *Denial of Service* or *DoS* attack). It should +have a mechanism for throttling or ignoring normal world requests. + +Performance considerations +-------------------------- + +Avoid printf and use logging macros +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``debug.h`` provides logging macros (for example, ``WARN`` and ``ERROR``) +which wrap ``tf_log`` and which allow the logging call to be compiled-out +depending on the ``make`` command. Use these macros to avoid print statements +being compiled unconditionally into the binary. + +Each logging macro has a numerical log level: + +.. code:: c + + #define LOG_LEVEL_NONE 0 + #define LOG_LEVEL_ERROR 10 + #define LOG_LEVEL_NOTICE 20 + #define LOG_LEVEL_WARNING 30 + #define LOG_LEVEL_INFO 40 + #define LOG_LEVEL_VERBOSE 50 + + +By default, all logging statements with a log level ``<= LOG_LEVEL_INFO`` will +be compiled into debug builds and all statements with a log level +``<= LOG_LEVEL_NOTICE`` will be compiled into release builds. This can be +overridden from the command line or by the platform makefile (although it may be +necessary to clean the build directory first). For example, to enable +``VERBOSE`` logging on FVP: + +``make PLAT=fvp LOG_LEVEL=50 all`` + +Use const data where possible +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For example, the following code: + +.. code:: c + + struct my_struct { + int arg1; + int arg2; + }; + + void init(struct my_struct *ptr); + + void main(void) + { + struct my_struct x; + x.arg1 = 1; + x.arg2 = 2; + init(&x); + } + +is better written as: + +.. code:: c + + struct my_struct { + int arg1; + int arg2; + }; + + void init(const struct my_struct *ptr); + + void main(void) + { + const struct my_struct x = { 1, 2 }; + init(&x); + } + +This allows the linker to put the data in a read-only data section instead of a +writeable data section, which may result in a smaller and faster binary. Note +that this may require dependent functions (``init()`` in the above example) to +have ``const`` arguments, assuming they don't need to modify the data. + +Library and driver code +----------------------- + +TF library code (under ``lib/`` and ``include/lib``) is any code that provides a +reusable interface to other code, potentially even to code outside of TF. + +In some systems drivers must conform to a specific driver framework to provide +services to the rest of the system. TF has no driver framework and the +distinction between a driver and library is somewhat subjective. + +A driver (under ``drivers/`` and ``include/drivers/``) is defined as code that +interfaces with hardware via a memory mapped interface. + +Some drivers (for example, the Arm CCI driver in ``include/drivers/arm/cci.h``) +provide a general purpose API to that specific hardware. Other drivers (for +example, the Arm PL011 console driver in ``drivers/arm/pl011/pl011_console.S``) +provide a specific hardware implementation of a more abstract library API. In +the latter case there may potentially be multiple drivers for the same hardware +device. + +Neither libraries nor drivers should depend on platform-specific code. If they +require platform-specific data (for example, a base address) to operate then +they should provide an initialization function that takes the platform-specific +data as arguments. + +TF common code (under ``common/`` and ``include/common/``) is code that is re-used +by other generic (non-platform-specific) TF code. It is effectively internal +library code. + +.. _`Why the “volatile” type class should not be used`: https://www.kernel.org/doc/html/latest/process/volatile-considered-harmful.html +.. _`Procedure Call Standard for the Arm Architecture`: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042f/IHI0042F_aapcs.pdf +.. _`Procedure Call Standard for the Arm 64-bit Architecture`: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055b/IHI0055B_aapcs64.pdf diff --git a/docs/process/contributing.rst b/docs/process/contributing.rst new file mode 100644 index 00000000..bd950e51 --- /dev/null +++ b/docs/process/contributing.rst @@ -0,0 +1,149 @@ +Contributing to Trusted Firmware-A +================================== + +Getting Started +--------------- + +- Make sure you have a Github account and you are logged on + `developer.trustedfirmware.org`_. +- Create an `issue`_ for your work if one does not already exist. This gives + everyone visibility of whether others are working on something similar. + + - If you intend to include Third Party IP in your contribution, please + raise a separate `issue`_ for this and ensure that the changes that + include Third Party IP are made on a separate topic branch. + +- Clone `arm-trusted-firmware-a`_ on your own machine as suggested on the + `User Guide`_. +- Create a local topic branch based on the `arm-trusted-firmware-a`_ ``master`` + branch. + +Making Changes +-------------- + +- Make commits of logical units. See these general `Git guidelines`_ for + contributing to a project. +- Follow the `Coding Guidelines`_. + + - Use the checkpatch.pl script provided with the Linux source tree. A + Makefile target is provided for convenience (see the "Checking source code + style" section in the `User Guide`_). + +- Keep the commits on topic. If you need to fix another bug or make another + enhancement, please create a separate `issue`_ and address it on a separate + topic branch. +- Avoid long commit series. If you do have a long series, consider whether + some commits should be squashed together or addressed in a separate topic. +- Make sure your commit messages are in the proper format. If a commit fixes + an `issue`_, include a reference. +- Where appropriate, please update the documentation. + + - Consider whether the `User Guide`_, `Porting Guide`_, `Firmware Design`_ + or other in-source documentation needs updating. + - Ensure that each changed file has the correct copyright and license + information. Files that entirely consist of contributions to this + project should have a copyright notice and BSD-3-Clause SPDX license + identifier of the form as shown in `license.rst`_. Files that contain + changes to imported Third Party IP files should retain their original + copyright and license notices. For significant contributions you may + add your own copyright notice in following format: + + :: + + Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved. + + where XXXX is the year of first contribution (if different to YYYY) and + YYYY is the year of most recent contribution. <OWNER> is your name or + your company name. + - If you are submitting new files that you intend to be the technical + sub-maintainer for (for example, a new platform port), then also update + the `Maintainers`_ file. + - For topics with multiple commits, you should make all documentation + changes (and nothing else) in the last commit of the series. Otherwise, + include the documentation changes within the single commit. + +- Please test your changes. As a minimum, ensure that Linux boots on the + Foundation FVP. See `Running the software on FVP`_ for more information. For + more extensive testing, consider running the `TF-A Tests`_ against your + patches. + +Submitting Changes +------------------ + +- Ensure that each commit in the series has at least one ``Signed-off-by:`` + line, using your real name and email address. The names in the + ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else + contributes to the commit, they must also add their own ``Signed-off-by:`` + line. By adding this line the contributor certifies the contribution is made + under the terms of the `Developer Certificate of Origin (DCO)`_. + + More details may be found in the `Gerrit Signed-off-by Lines guidelines`_. + +- Ensure that each commit also has a unique ``Change-Id:`` line. If you have + cloned the repository with the "`Clone with commit-msg hook`" clone method + (as advised on the `User Guide`_), this should already be the case. + + More details may be found in the `Gerrit Change-Ids documentation`_. + +- Submit your changes for review at https://review.trustedfirmware.org + targeting the ``integration`` branch. + + - The changes will then undergo further review and testing by the + `Maintainers`_. Any review comments will be made directly on your patch. + This may require you to do some rework. + + Refer to the `Gerrit Uploading Changes documentation`_ for more details. + +- When the changes are accepted, the `Maintainers`_ will integrate them. + + - Typically, the `Maintainers`_ will merge the changes into the + ``integration`` branch. + - If the changes are not based on a sufficiently-recent commit, or if they + cannot be automatically rebased, then the `Maintainers`_ may rebase it on + the ``master`` branch or ask you to do so. + - After final integration testing, the changes will make their way into the + ``master`` branch. If a problem is found during integration, the merge + commit will be removed from the ``integration`` branch and the + `Maintainers`_ will ask you to create a new patch set to resolve the + problem. + +Binary Components +----------------- + +- Platforms may depend on binary components submitted to the `Trusted Firmware + binary repository`_ if they require code that the contributor is unable or + unwilling to open-source. This should be used as a rare exception. +- All binary components must follow the contribution guidelines (in particular + licensing rules) outlined in the `readme.rst <tf-binaries-readme_>`_ file of + the binary repository. +- Binary components must be restricted to only the specific functionality that + cannot be open-sourced and must be linked into a larger open-source platform + port. The majority of the platform port must still be implemented in open + source. Platform ports that are merely a thin wrapper around a binary + component that contains all the actual code will not be accepted. +- Only platform port code (i.e. in the ``plat/<vendor>`` directory) may rely on + binary components. Generic code must always be fully open-source. + +-------------- + +*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* + +.. _developer.trustedfirmware.org: https://developer.trustedfirmware.org +.. _issue: https://developer.trustedfirmware.org/project/board/1/ +.. _arm-trusted-firmware-a: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git +.. _Git guidelines: http://git-scm.com/book/ch5-2.html +.. _Coding Guidelines: ./docs/coding-guidelines.rst +.. _User Guide: ./docs/user-guide.rst +.. _Porting Guide: ./docs/porting-guide.rst +.. _Firmware Design: ./docs/firmware-design.rst +.. _license.rst: ./license.rst +.. _Acknowledgements: ./acknowledgements.rst +.. _Maintainers: ./maintainers.rst +.. _Running the software on FVP: ./docs/user-guide.rst#user-content-running-the-software-on-fvp +.. _Developer Certificate of Origin (DCO): ./dco.txt +.. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html +.. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html +.. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html +.. _TF-A Tests: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/about/ +.. _Trusted Firmware binary repository: https://review.trustedfirmware.org/admin/repos/tf-binaries +.. _tf-binaries-readme: https://git.trustedfirmware.org/tf-binaries.git/tree/readme.rst diff --git a/docs/process/faq.rst b/docs/process/faq.rst new file mode 100644 index 00000000..6aa04f0a --- /dev/null +++ b/docs/process/faq.rst @@ -0,0 +1,79 @@ +Frequently-Asked Questions (FAQ) +================================ + +How do I update my changes? +--------------------------- + +Often it is necessary to update your patch set before it is merged. Refer to the +`Gerrit Upload Patch Set documentation`_ on how to do so. + +If you need to modify an existing patch set with multiple commits, refer to the +`Gerrit Replace Changes documentation`_. + +How long will my changes take to merge into ``integration``? +------------------------------------------------------------ + +This can vary a lot, depending on: + +* How important the patch set is considered by the TF maintainers. Where + possible, you should indicate the required timescales for merging the patch + set and the impact of any delay. Feel free to add a comment to your patch set + to get an estimate of when it will be merged. + +* The quality of the patch set. Patches are likely to be merged more quickly if + they follow the coding guidelines, have already had some code review, and have + been appropriately tested. + +* The impact of the patch set. For example, a patch that changes a key generic + API is likely to receive much greater scrutiny than a local change to a + specific platform port. + +* How much opportunity for external review is required. For example, the TF + maintainers may not wait for external review comments to merge trivial + bug-fixes but may wait up to a week to merge major changes, or ones requiring + feedback from specific parties. + +* How many other patch sets are waiting to be integrated and the risk of + conflict between the topics. + +* If there is a code freeze in place in preparation for the release. Please + refer the `release information`_ for more details. + +* The workload of the TF maintainers. + +How long will it take for my changes to go from ``integration`` to ``master``? +------------------------------------------------------------------------------ + +This depends on how many concurrent patches are being processed at the same +time. In simple cases where all potential regressions have already been tested, +the delay will be less than 1 day. If the TF maintainers are trying to merge +several things over the course of a few days, it might take up to a week. +Typically, it will be 1-2 days. + +The worst case is if the TF maintainers are trying to make a release while also +receiving patches that will not be merged into the release. In this case, the +patches will be merged onto ``integration``, which will temporarily diverge from +the release branch. The ``integration`` branch will be rebased onto ``master`` +after the release, and then ``master`` will be fast-forwarded to ``integration`` +1-2 days later. This whole process could take up 4 weeks. Please refer the +`release information`_ for code freeze dates. The TF maintainers will inform the +patch owner if this is going to happen. + +It is OK to create a patch based on commits that are only available in +``integration`` or another patch set, rather than ``master``. There is a risk +that the dependency commits will change (for example due to patch set rework or +integration problems). If this happens, the dependent patch will need reworking. + +What are these strange comments in my changes? +---------------------------------------------- + +All the comments from ``ci-bot-user`` are associated with Continuous Integration +infrastructure. The links published on the comment are not currently accessible, +but would be after the CI has been transitioned to `trustedfirmware.org`_. +Please refer to https://github.com/ARM-software/tf-issues/issues/681 for more +details on the timelines. + +.. _release information: release-information.rst +.. _Gerrit Upload Patch Set documentation: https://review.trustedfirmware.org/Documentation/intro-user.html#upload-patch-set +.. _Gerrit Replace Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html#push_replace +.. _trustedfirmware.org: https://www.trustedfirmware.org/ diff --git a/docs/process/index.rst b/docs/process/index.rst new file mode 100644 index 00000000..91f1beb2 --- /dev/null +++ b/docs/process/index.rst @@ -0,0 +1,14 @@ +Processes & Policies +==================== + +.. toctree:: + :maxdepth: 1 + :caption: Contents + :numbered: + + release-information + security-center + platform-compatibility-policy + coding-guidelines + contributing + faq diff --git a/docs/process/platform-compatibility-policy.rst b/docs/process/platform-compatibility-policy.rst new file mode 100644 index 00000000..e977e63a --- /dev/null +++ b/docs/process/platform-compatibility-policy.rst @@ -0,0 +1,44 @@ +TF-A Platform Compatibility Policy +================================== + + + + +.. contents:: + +-------------- + +Introduction +------------ + +This document clarifies the project's policy around compatibility for upstream +platforms. + +Platform compatibility policy +----------------------------- + +Platform compatibility is mainly affected by changes to Platform APIs (as +documented in the `Porting Guide`_), driver APIs (like the GICv3 drivers) or +library interfaces (like xlat_table library). The project will try to maintain +compatibility for upstream platforms. Due to evolving requirements and +enhancements, there might be changes affecting platform compatibility which +means the previous interface needs to be deprecated and a new interface +introduced to replace it. In case the migration to the new interface is trivial, +the contributor of the change is expected to make good effort to migrate the +upstream platforms to the new interface. + +The `Release information`_ documents the deprecated interfaces and the intended +release after which it will be removed. When an interface is deprecated, the +page must be updated to indicate the release after which the interface will be +removed. This must be at least 1 full release cycle in future. For non-trivial +interface changes, a `tf-issue`_ should be posted to notify platforms that they +should migrate away from the deprecated interfaces. Platforms are expected to +migrate before the removal of the deprecated interface. + +-------------- + +*Copyright (c) 2018, Arm Limited and Contributors. All rights reserved.* + +.. _Porting Guide: ../getting_started/porting-guide.rst +.. _Release information: https://github.com/ARM-software/arm-trusted-firmware/wiki/TF-A-Release-information#removal-of-deprecated-interfaces +.. _tf-issue: https://github.com/ARM-software/tf-issues/issues diff --git a/docs/process/release-information.rst b/docs/process/release-information.rst new file mode 100644 index 00000000..55311503 --- /dev/null +++ b/docs/process/release-information.rst @@ -0,0 +1,89 @@ +TF-A Release Information +======================== + +.. section-numbering:: + :suffix: . + +.. contents:: + +-------------- + +Project Release Cadence +----------------------- + +The project currently aims to do a release once every 6 months which will be +tagged on the master branch. There will be a code freeze (stop merging +non-essential PRs) up to 4 weeks prior to the target release date. The release +candidates will start appearing after this and only bug fixes or updates +required for the release will be merged. The maintainers are free to use their +judgement on what PRs are essential for the release. A release branch may be +created after code freeze if there are significant PRs that need merging onto +the integration branch during the merge window. + +The release testing will be performed on release candidates and depending on +issues found, additional release candidates may be created to fix the issues. + +:: + + |<----------6 months---------->| + |<---4 weeks--->| |<---4 weeks--->| + +-----------------------------------------------------------> time + | | | | + code freeze ver w.x code freeze ver y.z + + +Upcoming Releases +~~~~~~~~~~~~~~~~~ + +These are the estimated dates for the upcoming release. These may change +depending on project requirement and partner feedback. + ++-----------------+---------------------------+------------------------------+ +| Release Version | Target Date | Expected Code Freeze | ++=================+===========================+==============================+ +| v2.0 | 1st week of Oct '18 | 1st week of Sep '18 | ++-----------------+---------------------------+------------------------------+ +| v2.1 | 5th week of Mar '19 | 1st week of Mar '19 | ++-----------------+---------------------------+------------------------------+ + +Removal of Deprecated Interfaces +-------------------------------- + +As mentioned in the `Platform compatibility policy`_, this is a live document +cataloging all the deprecated interfaces in TF-A project and the Release version +after which it will be removed. + ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Interface | Deprecation | Removed | Comments | +| | Date | after | | +| | | Release | | ++================================+=============+=========+=========================================================+ +| Legacy Console API | Jan '18 | v2.1 | Deprecated in favour of ``MULTI_CONSOLE_API`` | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Weak default | Oct '18 | v2.1 | The default implementations are defined in | +| ``plat_crash_console_*`` | | | `crash_console_helpers.S`_. The platforms have to | +| APIs | | | define ``plat_crash_console_*``. | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| ``finish_console_register`` | Oct '18 | v2.1 | The old version of the macro is deprecated. See commit | +| macro in | | | cc5859c_ for more details. | +| ``MULTI_CONSOLE_API`` | | | | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Types ``tzc_action_t`` and | Oct '18 | v2.1 | Using logical operations such as OR in enumerations | +| ``tzc_region_attributes_t`` | | | goes against the MISRA guidelines. | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Macro ``EL_IMPLEMENTED()`` | Oct '18 | v2.1 | Deprecated in favour of ``el_implemented()``. | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| ``get_afflvl_shift()``, | Dec '18 | v2.1 | Removed. | +| ``mpidr_mask_lower_afflvls()``,| | | | +| and ``eret()``. | | | | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Extra include paths in the | Jan '18 | v2.1 | Now it is needed to use the full path of the common | +| Makefile in ``INCLUDES``. | | | header files. More information in commit 09d40e0e0828_. | ++--------------------------------+-------------+---------+---------------------------------------------------------+ + +*Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.* + +.. _Platform compatibility policy: platform-compatibility-policy.rst +.. _crash_console_helpers.S: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/common/aarch64/crash_console_helpers.S +.. _cc5859c: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=cc5859ca19ff546c35eb0331000dae090b6eabcf +.. _09d40e0e0828: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=09d40e0e08283a249e7dce0e106c07c5141f9b7e diff --git a/docs/process/security-center.rst b/docs/process/security-center.rst new file mode 100644 index 00000000..672c5632 --- /dev/null +++ b/docs/process/security-center.rst @@ -0,0 +1,103 @@ +Security Center +=============== + +Security Disclosures +-------------------- + +We disclose all security vulnerabilities we find or are advised about that are +relevant for ARM Trusted Firmware (TF). We encourage responsible disclosure of +vulnerabilities and inform users as best we can about all possible issues. + +We disclose TF vulnerabilities as Security Advisories. These are listed at the +bottom of this page and announced as issues in the `GitHub issue tracker`_ with +the "security-advisory" tag. You can receive notification emails for these by +watching that project. + +Found a Security Issue? +----------------------- + +Although we try to keep TF secure, we can only do so with the help of the +community of developers and security researchers. + +If you think you have found a security vulnerability, please *do not* report it +in the `GitHub issue tracker`_. Instead send an email to +trusted-firmware-security@arm.com + +Please include: + +* Trusted Firmware version (or commit) affected + +* A description of the concern or vulnerability + +* Details on how to replicate the vulnerability, including: + + - Configuration details + + - Proof of concept exploit code + + - Any additional software or tools required + +We recommend using `this PGP/GPG key`_ for encrypting the information. This key +is also available at http://keyserver.pgp.com and LDAP port 389 of the same +server. The fingerprint for this key is: + +:: + + 1309 2C19 22B4 8E87 F17B FE5C 3AB7 EFCB 45A0 DFD0 + +If you would like replies to be encrypted, please provide your public key. + +Please give us the time to respond to you and fix the vulnerability before going +public. We do our best to respond and fix any issues quickly. We also need to +ensure providers of products that use TF have a chance to consider the +implications of the vulnerability and its remedy. + +Afterwards, we encourage you to write-up your findings about the TF source code. + +Attribution +----------- + +We will name and thank you in the ``change-log.rst`` distributed with the source +code and in any published security advisory. + +Security Advisories +------------------- + ++-----------+------------------------------------------------------------------+ +| ID | Title | ++===========+==================================================================+ +| `TFV-1`_ | Malformed Firmware Update SMC can result in copy of unexpectedly | +| | large data into secure memory | ++-----------+------------------------------------------------------------------+ +| `TFV-2`_ | Enabled secure self-hosted invasive debug interface can allow | +| | normal world to panic secure world | ++-----------+------------------------------------------------------------------+ +| `TFV-3`_ | RO memory is always executable at AArch64 Secure EL1 | ++-----------+------------------------------------------------------------------+ +| `TFV-4`_ | Malformed Firmware Update SMC can result in copy or | +| | authentication of unexpected data in secure memory in AArch32 | +| | state | ++-----------+------------------------------------------------------------------+ +| `TFV-5`_ | Not initializing or saving/restoring PMCR_EL0 can leak secure | +| | world timing information | ++-----------+------------------------------------------------------------------+ +| `TFV-6`_ | Arm Trusted Firmware exposure to speculative processor | +| | vulnerabilities using cache timing side-channels | ++-----------+------------------------------------------------------------------+ +| `TFV-7`_ | Trusted Firmware-A exposure to cache speculation vulnerability | +| | Variant 4 | ++-----------+------------------------------------------------------------------+ +| `TFV-8`_ | Not saving x0 to x3 registers can leak information from one | +| | Normal World SMC client to another | ++-----------+------------------------------------------------------------------+ + +.. _GitHub issue tracker: https://github.com/ARM-software/tf-issues/issues +.. _this PGP/GPG key: security-reporting.asc +.. _TFV-1: ./security_advisories/security-advisory-tfv-1.rst +.. _TFV-2: ./security_advisories/security-advisory-tfv-2.rst +.. _TFV-3: ./security_advisories/security-advisory-tfv-3.rst +.. _TFV-4: ./security_advisories/security-advisory-tfv-4.rst +.. _TFV-5: ./security_advisories/security-advisory-tfv-5.rst +.. _TFV-6: ./security_advisories/security-advisory-tfv-6.rst +.. _TFV-7: ./security_advisories/security-advisory-tfv-7.rst +.. _TFV-8: ./security_advisories/security-advisory-tfv-8.rst diff --git a/docs/process/security-reporting.asc b/docs/process/security-reporting.asc new file mode 100644 index 00000000..8c41f7bf --- /dev/null +++ b/docs/process/security-reporting.asc @@ -0,0 +1,45 @@ +-----BEGIN PGP PUBLIC KEY BLOCK----- +Version: PGP Desktop 10.2.0 (Build 2317) + +mQENBFey/QMBCACyxJaLsMYU794ZfzLdY172tHXRJfP0X3b34HU35G7kYl1zNiYc +/NoygtQdtDv/aW1B2A/YTNhGge+gX4BWAREd5CYDbdPEoMWC395/qbnmMmez7YNY +PEJ9Iq9e5AayAWwZTL1zgKwdvE+WTwWok/nMbsifJSEdhdrOIHNqRcZgplUUyZ2R +sDqFtSbACO3xj4Psk8KJ23Ax7UZgULouZOJaHOnyq8F9V/U7zWvX4Odf96XaC1Em +cUTsG0kQfa7Y4Hqqjzowq366I4k2o2LAtuLPWNCvq5jjEceLs2+qV4cNLgyL2dzO +wtUL6EdkrGfkxsPHpsVKXig4wjeX9ehCSqRlABEBAAG0PVRydXN0ZWQgRmlybXdh +cmUgU2VjdXJpdHkgPHRydXN0ZWQtZmlybXdhcmUtc2VjdXJpdHlAYXJtLmNvbT6J +AYwEEAECAHYFAley/SEwFIAAAAAAIAAHcHJlZmVycmVkLWVtYWlsLWVuY29kaW5n +QHBncC5jb21wZ3BtaW1lCAsJCAcDAgEKAhkBGRhsZGFwOi8va2V5c2VydmVyLnBn +cC5jb20FGwMAAAAFFgADAgEFHgEAAAAGFQgJCgMCAAoJEDq378tFoN/QFJsH/0ly +H91LYYzKIQrbolQw7Rp47lgzH88uN1rInYpW2GaTbjwPffAhYJ4VsN8RaiFskD9m +DjMg4vY8p0jPTCUX1Acq20Wq0Ybv3HcrtjUp4ie0+rLUi3043yJyKFMWkJC2Kr+p +SobnxSrAie4HDFUgSaPoh9Qf1zXEzOavdgcziMiyS5iVUf6NXYZ9z82OTZ6TdPKS +u+L5zOHTdrV3+hD54w00Xa+EIE7u4v0to6Uwm977508hyGuvpOVq+u7+S3qJQvnY ++JheStbgLsm6CyoRjyrlTE01ujAD6hI6Ef9yMgEljOBEy4phKAJ67SCRLEOiCp5U +YHFCULwhzIyg2y3WmZSJASIEEAECAAwFAlezAnwFAwASdQAACgkQlxC4m8pXrXzd +GAf/T8YEICI9qQt2vnCtCbBvVaTc2sAphVZ51kZVDqCDPB7znDtJYRBpi/9IPELt +mYwIElMx2mqmahVaeUghmbzmcLZe8QHUi8GanO1mh+ook6uyjRojSIq6VUVV5uUf +tuscfhpilOvUclqMqYEIgXfl08YwS40Kmmj0qokwad0co0zGQ8GEhlgMi2yvJfiG +fPS0Xcn1J0980E/VgJQCAKwZvukrbb32WVwuhgepqs/4/62PZNxglcErioFt6P0A +ik4t9Hr0uErqCeEKiYtmEw5e9ioRdX7CV+tJgIk907Tpv6E0iDFRJHmJBvmsz82O +stOazS3wZ5Xck7asTqkvoyo9Z7kBDQRXsv0DAQgAsmL1UUIWyoNmYJWixSPDmclP +0ul3T1FCOsIlWTeVeshnHByYdgZOfce78ETCUoq8G7qvYm4GRrEDpqVbxqTxJioP +4Li05WDdNCKzSoqWd8ADA48gYnnJEu2NhA7ZkEC6u3+Mdbmd3M0J6nsAWeE0BV1p +F5zI600sJuoH2QNWB7Kv5N3GCFE4IgCIH8MwDo4Y4FTZtygx4GjEtSExiOIz+bpX +2+GkFCQGpIyLHLP4FmQmrsNzsIdEyFuG0IdoVuQ2PtNLiw+Wkm7CXWgRmFx/dtPN +eVnOFWdbTtjBWVv/Z6zbANos2knfc75KR4FCQ6pWRvVeJuMuMopUDkfFDMtR8QAR +AQABiQJBBBgBAgErBQJXsv0EBRsMAAAAwF0gBBkBCAAGBQJXsv0DAAoJENaB8ph8 +s9hu/nsH/Rx696ZR+1vZi5qCTUwo6s0Qa15x4OuyJEM85VgMLVY7/MZpp1Y8If6u +A5BynQpy4QIPxIRsRx6twduW9/gb8UVhpMRPyuJ+5sSv0/KeUqkPbKSUGro2zGlR +sjqPrchi6uafWZqOR/y/DNkEvkgZZaP+f9xs2qWKuoF08yTioo76QoroA4DVuVAT +MkDFe9d3natAmfmjO4kvxuthg3y7R+sdXrCHpYYJZdbiR6gyj7e8whlSLwHQT3lz +7QBL/CvVvL/dmhu5pk8fsksbehepMQTkCJ6GGEamOPEhwh7IvlzhEt97U4uzjuMd +BPjqOCes+4QTmn/+lMTySG0kXxnHOEUACgkQOrfvy0Wg39D8Jgf/Uf3epkMOJ9xm +N1l5vW8tQQ6RR055YQxQ9P6JMyCQGEJmGOcvrasCho69wMQDy4AYVtJaZd25LH/3 +LX/lcyDOP4C9VYXM+IxlcaRmjBKqWx9UzQeeioIkfmjMpJFU846ZP1dacge0lPx8 +p6ocPbM0rkv0xuF/dwkDQd4BPSmv4/3/UM8FRoYo8Q7SHkDR98wJ8FCm6k9wRtWC +K/jzmBswY2TewAHom3jLzTM0FZ/n5Sini3EGAI2EvnQrxWRpeE7ZOkHKqLHEOaHl +zeST4U/cUgxhwgnhbGJ7zmrFsHpYnnZYM3mIKfQ3/EhksZ68TF9IB1tfUiQTij4r +9jWa0ybRdQ== +=nZZb +-----END PGP PUBLIC KEY BLOCK----- |