docs: discourage usage of weak functions

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

diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 0e4d1e31c702e0e28f8029ab140e9bde8eecc151..6735cb1470e4275bd88994b9dc286a331d2ead99 100644 (file)
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -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

diff --git a/docs/process/coding-guidelines.rst b/docs/process/coding-guidelines.rst
index 26c272d864457620d2109cd6ed12a7021d2212f3..13fb7cbaf907fc3a45cd6b1e491408f96fdf99a7 100644 (file)
--- a/docs/process/coding-guidelines.rst
+++ b/docs/process/coding-guidelines.rst
@@ -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