Merge "docs: discourage usage of weak functions" into integration
diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 0e4d1e3..6735cb1 100644
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -14,10 +14,17 @@
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 26c272d..13fb7cb 100644
--- a/docs/process/coding-guidelines.rst
+++ b/docs/process/coding-guidelines.rst
@@ -461,9 +461,56 @@
- 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