The patch titled
Subject: docs: fault-injection: add requirements of error injectable functions
has been added to the -mm mm-nonmm-unstable branch. Its filename is
docs-fault-injection-add-requirements-of-error-injectable-functions.patch
This patch will shortly appear at
https://git.kernel.org/pub/scm/linux/kernel/git/akpm/25-new.git/tree/patches/docs-fault-injection-add-requirements-of-error-injectable-functions.patch
This patch will later appear in the mm-nonmm-unstable branch at
git://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm
Before you just go and hit "reply", please:
a) Consider who else should be cc'ed
b) Prefer to cc a suitable mailing list as well
c) Ideally: find the original patch on the mailing list and do a
reply-to-all to that, adding suitable additional cc's
*** Remember to use Documentation/process/submit-checklist.rst when testing your code ***
The -mm tree is included into linux-next via the mm-everything
branch at git://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm
and is updated there every 2-3 working days
------------------------------------------------------
From: Masami Hiramatsu (Google) <mhiramat@xxxxxxxxxx>
Subject: docs: fault-injection: add requirements of error injectable functions
Date: Mon, 12 Dec 2022 11:46:54 +0900
Add a section about the requirements of the error injectable functions and
the type of errors.
Since this section must be read before using ALLOW_ERROR_INJECTION()
macro, that section is referred from the comment of the macro too.
Link: https://lkml.kernel.org/r/167081321427.387937.15475445689482551048.stgit@devnote3
Link: https://lore.kernel.org/all/20221211115218.2e6e289bb85f8cf53c11aa97@xxxxxxxxxx/T/#u
Signed-off-by: Masami Hiramatsu (Google) <mhiramat@xxxxxxxxxx>
Cc: Alexei Starovoitov <alexei.starovoitov@xxxxxxxxx>
Cc: Borislav Petkov (AMD) <bp@xxxxxxxxx>
Cc: Chris Mason <clm@xxxxxxxx>
Cc: Christoph Hellwig <hch@xxxxxxxxxxxxx>
Cc: Florent Revest <revest@xxxxxxxxxxxx>
Cc: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
Cc: Jonathan Corbet <corbet@xxxxxxx>
Cc: Josh Poimboeuf <jpoimboe@xxxxxxxxxx>
Cc: Kees Cook <keescook@xxxxxxxxxxxx>
Cc: KP Singh <kpsingh@xxxxxxxxxx>
Cc: Mark Rutland <mark.rutland@xxxxxxx>
Cc: Peter Zijlstra <peterz@xxxxxxxxxxxxx>
Cc: Steven Rostedt (Google) <rostedt@xxxxxxxxxxx>
Signed-off-by: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx>
---
Documentation/fault-injection/fault-injection.rst | 65 ++++++++++++
include/asm-generic/error-injection.h | 6 -
2 files changed, 69 insertions(+), 2 deletions(-)
--- a/Documentation/fault-injection/fault-injection.rst~docs-fault-injection-add-requirements-of-error-injectable-functions
+++ a/Documentation/fault-injection/fault-injection.rst
@@ -231,6 +231,71 @@ proc entries
This feature is intended for systematic testing of faults in a single
system call. See an example below.
+
+Error Injectable Functions
+--------------------------
+
+This part is for the kenrel developers considering to add a function to
+ALLOW_ERROR_INJECTION() macro.
+
+Requirements for the Error Injectable Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since the function-level error injection forcibly changes the code path
+and returns an error even if the input and conditions are proper, this can
+cause unexpected kernel crash if you allow error injection on the function
+which is NOT error injectable. Thus, you (and reviewers) must ensure;
+
+- The function returns an error code if it fails, and the callers must check
+ it correctly (need to recover from it).
+
+- The function does not execute any code which can change any state before
+ the first error return. The state includes global or local, or input
+ variable. For example, clear output address storage (e.g. `*ret = NULL`),
+ increments/decrements counter, set a flag, preempt/irq disable or get
+ a lock (if those are recovered before returning error, that will be OK.)
+
+The first requirement is important, and it will result in that the release
+(free objects) functions are usually harder to inject errors than allocate
+functions. If errors of such release functions are not correctly handled
+it will cause a memory leak easily (the caller will confuse that the object
+has been released or corrupted.)
+
+The second one is for the caller which expects the function should always
+does something. Thus if the function error injection skips whole of the
+function, the expectation is betrayed and causes an unexpected error.
+
+Type of the Error Injectable Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each error injectable functions will have the error type specified by the
+ALLOW_ERROR_INJECTION() macro. You have to choose it carefully if you add
+a new error injectable function. If the wrong error type is chosen, the
+kernel may crash because it may not be able to handle the error.
+There are 4 types of errors defined in include/asm-generic/error-injection.h
+
+EI_ETYPE_NULL
+ This function will return `NULL` if it fails. e.g. return an allocateed
+ object address.
+
+EI_ETYPE_ERRNO
+ This function will return an `-errno` error code if it fails. e.g. return
+ -EINVAL if the input is wrong. This will include the functions which will
+ return an address which encodes `-errno` by ERR_PTR() macro.
+
+EI_ETYPE_ERRNO_NULL
+ This function will return an `-errno` or `NULL` if it fails. If the caller
+ of this function checks the return value with IS_ERR_OR_NULL() macro, this
+ type will be appropriate.
+
+EI_ETYPE_TRUE
+ This function will return `true` (non-zero positive value) if it fails.
+
+If you specifies a wrong type, for example, EI_TYPE_ERRNO for the function
+which returns an allocated object, it may cause a problem because the returned
+value is not an object address and the caller can not access to the address.
+
+
How to add new fault injection capability
-----------------------------------------
--- a/include/asm-generic/error-injection.h~docs-fault-injection-add-requirements-of-error-injectable-functions
+++ a/include/asm-generic/error-injection.h
@@ -19,8 +19,10 @@ struct pt_regs;
#ifdef CONFIG_FUNCTION_ERROR_INJECTION
/*
- * Whitelist generating macro. Specify functions which can be
- * error-injectable using this macro.
+ * Whitelist generating macro. Specify functions which can be error-injectable
+ * using this macro. If you unsure what is required for the error-injectable
+ * functions, please read Documentation/fault-injection/fault-injection.rst
+ * 'Error Injectable Functions' section.
*/
#define ALLOW_ERROR_INJECTION(fname, _etype) \
static struct error_injection_entry __used \
_
Patches currently in -mm which might be from mhiramat@xxxxxxxxxx are
error-injection-remove-ei_etype_none.patch
docs-fault-injection-add-requirements-of-error-injectable-functions.patch
