Djam/arm-trusted-firmware
1
0
Fork 0
mirror of https://github.com/ARM-software/arm-trusted-firmware.git synced 2025-04-18 02:24:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge "docs: discourage usage of weak functions" into integration

Browse source
This commit is contained in:
Sandrine Bailleux 2023-03-06 20:38:28 +01:00 • committed by TrustedFirmware Code Review
commit 2b7150b381
2 changed files with 59 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
docs/getting_started/porting-guide.rst
View file

@ -14,10 +14,17 @@ Modifications consist of:
The platform-specific functions and variables are declared in
``include/plat/common/platform.h``. The firmware provides a default
implementation of variables and functions to fulfill the optional requirements.
These implementations are all weakly defined; they are provided to ease the
porting effort. Each platform port can override them with its own implementation
if the default implementation is inadequate.
implementation of variables and functions to fulfill the optional requirements
in order to ease the porting effort. Each platform port can use them as is or
provide their own implementation if the default implementation is inadequate.
.. note::
TF-A historically provided default implementations of platform interfaces
as *weak* functions. This practice is now discouraged and new platform
interfaces as they get introduced in the code base should be *strongly*
defined. We intend to convert existing weak functions over time. Until
then, you will find references to *weak* functions in this document.
Some modifications are common to all Boot Loader (BL) stages. Section 2
discusses these in detail. The subsequent sections discuss the remaining

49
docs/process/coding-guidelines.rst
View file

@ -461,9 +461,56 @@ There are, however, legitimate uses of assembly language. These include:
- Low-level code where specific system-level instructions must be used, such
as cache maintenance operations.
Do not use weak functions
-------------------------
.. note::
The following guideline applies more strongly to common, platform-independent
code. For plaform code (under ``plat/`` directory), it is up to each platform
maintainer to decide whether this should be striclty enforced or not.
The use of weak functions is highly discouraged in the TF-A codebase. Newly
introduced platform interfaces should be strongly defined, wherever possible. In
the rare cases where this is not possible or where weak functions appear as the
best tool to solve the problem at hand, this should be discussed with the
project's maintainers and justified in the code.
For the purpose of providing a default implementation of a platform interface,
an alternative to weak functions is to provide a strongly-defined implementation
under the ``plat/common/`` directory. Then platforms have two options to pull
in this implementation:
- They can include the source file through the platform's makefile. Note that
this method is suitable only if the platform wants *all* default
implementations defined in this file, else either the file should be
refactored or the next approach should be used.
- They access the platform interface through a **constant** function pointer.
In both cases, what matters is that platforms include the default implementation
as a conscious decision.
.. rubric:: Rationale
Weak functions may sound useful to simplify the initial porting effort to a
new platform, such that one can quickly get the firmware to build and link,
without implementing all platform interfaces from the beginning. For this
reason, the TF-A project used to make heavy use of weak functions and there
are still many outstanding usages of them across the code base today. We
intend to convert them to strongly-defined functions over time.
However, weak functions also have major drawbacks, which we consider
outweighing their benefits. They can make it hard to identify which
implementation gets built into the firmware, especially when using multiple
levels of "weakness". This has resulted in bugs in the past.
Weak functions are also forbidden by MISRA coding guidelines, which TF-A aims to
comply with.
--------------
*Copyright (c) 2020, 2022, Arm Limited and Contributors. All rights reserved.*
*Copyright (c) 2020 - 2023, Arm Limited and Contributors. All rights reserved.*
.. _`Linux master tree`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/
.. _`Procedure Call Standard for the Arm Architecture`: https://github.com/ARM-software/abi-aa/blob/main/aapcs32/aapcs32.rst