[PATCH 0/2] error-injection: Clarify the requirements of error injectable functions

[PATCH 0/2] error-injection: Clarify the requirements of error injectable functions

[Masami Hiramatsu (Google)]

Hi,

Here are the patches for clarifying the requirement of error injectable
functions and remove confusing EI_ETYPE_NONE.

Here is the thread of discussions which leads this series.

https://lore.kernel.org/all/167019256481.3792653.4369637751468386073.stgit@devnote3/T/#u

I agreed that NACK the taint flag itself, and I thought I need to update
the function error injection so that the developers understand the
requirements and carefully use the ALLOW_ERROR_INJECTION() macro.
So I removed the confusing EI_ETYPE_NONE (this should not be there,
use errno instead), and update the document about error injectable
functions.

Thank you,

---

Masami Hiramatsu (Google) (2):
      error-injection: Remove EI_ETYPE_NONE
      docs: fault-injection: Add requirements of error injectable functions


 Documentation/fault-injection/fault-injection.rst |   65 +++++++++++++++++++++
 include/asm-generic/error-injection.h             |    7 +-
 include/linux/error-injection.h                   |    2 -
 lib/error-inject.c                                |    2 -
 4 files changed, 71 insertions(+), 5 deletions(-)

--
Masami Hiramatsu (Google) <mhiramat@kernel.org>

[PATCH 1/2] error-injection: Remove EI_ETYPE_NONE

[Masami Hiramatsu (Google)]

From: Masami Hiramatsu (Google) <mhiramat@kernel.org>

Since the EI_ETYPE_NONE is confusing type, replace it with appropriate
errno. The EI_ETYPE_NONE has been introduced for a dummy (error) value,
but it can mislead people that they can use ALLOW_ERROR_INJECTION(func,
NONE). So remove it from the EI_ETYPE and use appropriate errno instead.

Signed-off-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
Fixes: 663faf9f7bee ("error-injection: Add injectable error types")
---
 include/asm-generic/error-injection.h |    1 -
 include/linux/error-injection.h       |    2 +-
 lib/error-inject.c                    |    2 +-
 3 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/include/asm-generic/error-injection.h b/include/asm-generic/error-injection.h
index fbca56bd9cbc..c0b9d3217ed9 100644
--- a/include/asm-generic/error-injection.h
+++ b/include/asm-generic/error-injection.h
@@ -4,7 +4,6 @@
 
 #if defined(__KERNEL__) && !defined(__ASSEMBLY__)
 enum {
-	EI_ETYPE_NONE,		/* Dummy value for undefined case */
 	EI_ETYPE_NULL,		/* Return NULL if failure */
 	EI_ETYPE_ERRNO,		/* Return -ERRNO if failure */
 	EI_ETYPE_ERRNO_NULL,	/* Return -ERRNO or NULL if failure */
diff --git a/include/linux/error-injection.h b/include/linux/error-injection.h
index 635a95caf29f..268fecfc1e82 100644
--- a/include/linux/error-injection.h
+++ b/include/linux/error-injection.h
@@ -19,7 +19,7 @@ static inline bool within_error_injection_list(unsigned long addr)
 
 static inline int get_injectable_error_type(unsigned long addr)
 {
-	return EI_ETYPE_NONE;
+	return -EOPNOTSUPP;
 }
 
 #endif
diff --git a/lib/error-inject.c b/lib/error-inject.c
index 1afca1b1cdea..32c14770508e 100644
--- a/lib/error-inject.c
+++ b/lib/error-inject.c
@@ -40,7 +40,7 @@ bool within_error_injection_list(unsigned long addr)
 int get_injectable_error_type(unsigned long addr)
 {
 	struct ei_entry *ent;
-	int ei_type = EI_ETYPE_NONE;
+	int ei_type = -EINVAL;
 
 	mutex_lock(&ei_mutex);
 	list_for_each_entry(ent, &error_injection_list, list) {

[PATCH 2/2] docs: fault-injection: Add requirements of error injectable functions

[Masami Hiramatsu (Google)]

From: Masami Hiramatsu (Google) <mhiramat@kernel.org>

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.

Signed-off-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
Link: https://lore.kernel.org/all/20221211115218.2e6e289bb85f8cf53c11aa97@kernel.org/T/#u
---
 Documentation/fault-injection/fault-injection.rst |   65 +++++++++++++++++++++
 include/asm-generic/error-injection.h             |    6 +-
 2 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/Documentation/fault-injection/fault-injection.rst b/Documentation/fault-injection/fault-injection.rst
index 17779a2772e5..da6c5796b1f8 100644
--- a/Documentation/fault-injection/fault-injection.rst
+++ b/Documentation/fault-injection/fault-injection.rst
@@ -233,6 +233,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
 -----------------------------------------
 
diff --git a/include/asm-generic/error-injection.h b/include/asm-generic/error-injection.h
index c0b9d3217ed9..b05253f68eaa 100644
--- a/include/asm-generic/error-injection.h
+++ b/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				\

Re: [PATCH 1/2] error-injection: Remove EI_ETYPE_NONE

[Masami Hiramatsu]

On Mon, 12 Dec 2022 12:55:24 +0800
kernel test robot <lkp@intel.com> wrote:

> Hi Masami,
> 
> Thank you for the patch! Yet something to improve:
> 
> [auto build test ERROR on arnd-asm-generic/master]
> [also build test ERROR on linus/master v6.1 next-20221208]
> [If your patch is applied to the wrong git tree, kindly drop us a note.
> And when submitting patch, we suggest to use '--base' as documented in
> https://git-scm.com/docs/git-format-patch#_base_tree_information]
> 
> url:    https://github.com/intel-lab-lkp/linux/commits/Masami-Hiramatsu-Google/error-injection-Clarify-the-requirements-of-error-injectable-functions/20221212-104859
> base:   https://git.kernel.org/pub/scm/linux/kernel/git/arnd/asm-generic.git master
> patch link:    https://lore.kernel.org/r/167081320421.387937.4259807348852421112.stgit%40devnote3
> patch subject: [PATCH 1/2] error-injection: Remove EI_ETYPE_NONE
> config: hexagon-randconfig-r045-20221211
> compiler: clang version 16.0.0 (https://github.com/llvm/llvm-project 6e4cea55f0d1104408b26ac574566a0e4de48036)
> reproduce (this is a W=1 build):
>         wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
>         chmod +x ~/bin/make.cross
>         # https://github.com/intel-lab-lkp/linux/commit/ffd600c8d5c881bc0e58401c24c7457a566f6207
>         git remote add linux-review https://github.com/intel-lab-lkp/linux
>         git fetch --no-tags linux-review Masami-Hiramatsu-Google/error-injection-Clarify-the-requirements-of-error-injectable-functions/20221212-104859
>         git checkout ffd600c8d5c881bc0e58401c24c7457a566f6207
>         # save the config file
>         mkdir build_dir && cp config build_dir/.config
>         COMPILER_INSTALL_PATH=$HOME/0day COMPILER=clang make.cross W=1 O=build_dir ARCH=hexagon SHELL=/bin/bash fs/btrfs/
> 
> If you fix the issue, kindly add following tag where applicable
> | Reported-by: kernel test robot <lkp@intel.com>
> 
> All errors (new ones prefixed by >>):
> 
>    In file included from fs/btrfs/tree-checker.c:20:
> >> include/linux/error-injection.h:22:10: error: use of undeclared identifier 'EOPNOTSUPP'
>            return -EOPNOTSUPP;

Oops, I need to include linux/errno.h. Let me update it.

Thanks!

>                    ^
>    In file included from fs/btrfs/tree-checker.c:21:
>    In file included from fs/btrfs/ctree.h:9:
>    In file included from include/linux/mm.h:737:
>    In file included from include/linux/huge_mm.h:8:
>    In file included from include/linux/fs.h:33:
>    In file included from include/linux/percpu-rwsem.h:7:
>    In file included from include/linux/rcuwait.h:6:
>    In file included from include/linux/sched/signal.h:6:
>    include/linux/signal.h:97:11: warning: array index 3 is past the end of the array (that has type 'unsigned long[2]') [-Warray-bounds]
>                    return (set->sig[3] | set->sig[2] |
>                            ^        ~
>    include/uapi/asm-generic/signal.h:62:2: note: array 'sig' declared here
>            unsigned long sig[_NSIG_WORDS];
>            ^
>    In file included from fs/btrfs/tree-checker.c:21:
>    In file included from fs/btrfs/ctree.h:9:
>    In file included from include/linux/mm.h:737:
>    In file included from include/linux/huge_mm.h:8:
>    In file included from include/linux/fs.h:33:
>    In file included from include/linux/percpu-rwsem.h:7:
>    In file included from include/linux/rcuwait.h:6:
>    In file included from include/linux/sched/signal.h:6:
>    include/linux/signal.h:97:25: warning: array index 2 is past the end of the array (that has type 'unsigned long[2]') [-Warray-bounds]
>                    return (set->sig[3] | set->sig[2] |
>                                          ^        ~
>    include/uapi/asm-generic/signal.h:62:2: note: array 'sig' declared here
>            unsigned long sig[_NSIG_WORDS];
>            ^
>    In file included from fs/btrfs/tree-checker.c:21:
>    In file included from fs/btrfs/ctree.h:9:
>    In file included from include/linux/mm.h:737:
>    In file included from include/linux/huge_mm.h:8:
>    In file included from include/linux/fs.h:33:
>    In file included from include/linux/percpu-rwsem.h:7:
>    In file included from include/linux/rcuwait.h:6:
>    In file included from include/linux/sched/signal.h:6:
>    include/linux/signal.h:113:11: warning: array index 3 is past the end of the array (that has type 'const unsigned long[2]') [-Warray-bounds]
>                    return  (set1->sig[3] == set2->sig[3]) &&
>                             ^         ~
>    include/uapi/asm-generic/signal.h:62:2: note: array 'sig' declared here
>            unsigned long sig[_NSIG_WORDS];
>            ^
>    In file included from fs/btrfs/tree-checker.c:21:
>    In file included from fs/btrfs/ctree.h:9:
>    In file included from include/linux/mm.h:737:
>    In file included from include/linux/huge_mm.h:8:
>    In file included from include/linux/fs.h:33:
>    In file included from include/linux/percpu-rwsem.h:7:
>    In file included from include/linux/rcuwait.h:6:
>    In file included from include/linux/sched/signal.h:6:
>    include/linux/signal.h:113:27: warning: array index 3 is past the end of the array (that has type 'const unsigned long[2]') [-Warray-bounds]
>                    return  (set1->sig[3] == set2->sig[3]) &&
>                                             ^         ~
>    include/uapi/asm-generic/signal.h:62:2: note: array 'sig' declared here
>            unsigned long sig[_NSIG_WORDS];
>            ^
>    In file included from fs/btrfs/tree-checker.c:21:
>    In file included from fs/btrfs/ctree.h:9:
>    In file included from include/linux/mm.h:737:
>    In file included from include/linux/huge_mm.h:8:
>    In file included from include/linux/fs.h:33:
>    In file included from include/linux/percpu-rwsem.h:7:
>    In file included from include/linux/rcuwait.h:6:
>    In file included from include/linux/sched/signal.h:6:
>    include/linux/signal.h:114:5: warning: array index 2 is past the end of the array (that has type 'const unsigned long[2]') [-Warray-bounds]
>                            (set1->sig[2] == set2->sig[2]) &&
>                             ^         ~
>    include/uapi/asm-generic/signal.h:62:2: note: array 'sig' declared here
>            unsigned long sig[_NSIG_WORDS];
>            ^
>    In file included from fs/btrfs/tree-checker.c:21:
>    In file included from fs/btrfs/ctree.h:9:
>    In file included from include/linux/mm.h:737:
>    In file included from include/linux/huge_mm.h:8:
>    In file included from include/linux/fs.h:33:
>    In file included from include/linux/percpu-rwsem.h:7:
>    In file included from include/linux/rcuwait.h:6:
>    In file included from include/linux/sched/signal.h:6:
>    include/linux/signal.h:114:21: warning: array index 2 is past the end of the array (that has type 'const unsigned long[2]') [-Warray-bounds]
>                            (set1->sig[2] == set2->sig[2]) &&
>                                             ^         ~
>    include/uapi/asm-generic/signal.h:62:2: note: array 'sig' declared here
>            unsigned long sig[_NSIG_WORDS];
>            ^
>    In file included from fs/btrfs/tree-checker.c:21:
>    In file included from fs/btrfs/ctree.h:9:
>    In file included from include/linux/mm.h:737:
>    In file included from include/linux/huge_mm.h:8:
>    In file included from include/linux/fs.h:33:
>    In file included from include/linux/percpu-rwsem.h:7:
>    In file included from include/linux/rcuwait.h:6:
>    In file included from include/linux/sched/signal.h:6:
>    include/linux/signal.h:156:1: warning: array index 3 is past the end of the array (that has type 'const unsigned long[2]') [-Warray-bounds]
>    _SIG_SET_BINOP(sigorsets, _sig_or)
>    ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>    include/linux/signal.h:137:8: note: expanded from macro '_SIG_SET_BINOP'
>                    a3 = a->sig[3]; a2 = a->sig[2];                         \
>                         ^      ~
> 
> 
> vim +/EOPNOTSUPP +22 include/linux/error-injection.h
> 
>     19	
>     20	static inline int get_injectable_error_type(unsigned long addr)
>     21	{
>   > 22		return -EOPNOTSUPP;
>     23	}
>     24	
> 
> -- 
> 0-DAY CI Kernel Test Service
> https://01.org/lkp


-- 
Masami Hiramatsu (Google) <mhiramat@kernel.org>

Re: [PATCH 2/2] docs: fault-injection: Add requirements of error injectable functions

[Randy Dunlap]

Hi--

On 12/11/22 18:46, Masami Hiramatsu (Google) wrote:
> From: Masami Hiramatsu (Google) <mhiramat@kernel.org>
> 
> 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.
> 
> Signed-off-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
> Link: https://lore.kernel.org/all/20221211115218.2e6e289bb85f8cf53c11aa97@kernel.org/T/#u
> ---
>  Documentation/fault-injection/fault-injection.rst |   65 +++++++++++++++++++++
>  include/asm-generic/error-injection.h             |    6 +-
>  2 files changed, 69 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/fault-injection/fault-injection.rst b/Documentation/fault-injection/fault-injection.rst
> index 17779a2772e5..da6c5796b1f8 100644
> --- a/Documentation/fault-injection/fault-injection.rst
> +++ b/Documentation/fault-injection/fault-injection.rst
> @@ -233,6 +233,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

                        kernel developers considering adding a function

> +ALLOW_ERROR_INJECTION() macro.

   using the 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

     increment/decrement a counter,

> +  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

   do something.                                        skips all 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

                         function

> +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

                                                                  allocated

> +  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

          specify

> +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
>  -----------------------------------------
>  
> diff --git a/include/asm-generic/error-injection.h b/include/asm-generic/error-injection.h
> index c0b9d3217ed9..b05253f68eaa 100644
> --- a/include/asm-generic/error-injection.h
> +++ b/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

                        If you are unsure ...

> + * 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				\
> 

-- 
~Randy

Re: [PATCH 2/2] docs: fault-injection: Add requirements of error injectable functions

[Masami Hiramatsu]

Hi Randy,

Thank you very much for the review!
OK, I'll fix those typos and misses.

Thanks!

On Mon, 12 Dec 2022 22:54:08 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:

> Hi--
> 
> On 12/11/22 18:46, Masami Hiramatsu (Google) wrote:
> > From: Masami Hiramatsu (Google) <mhiramat@kernel.org>
> > 
> > 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.
> > 
> > Signed-off-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
> > Link: https://lore.kernel.org/all/20221211115218.2e6e289bb85f8cf53c11aa97@kernel.org/T/#u
> > ---
> >  Documentation/fault-injection/fault-injection.rst |   65 +++++++++++++++++++++
> >  include/asm-generic/error-injection.h             |    6 +-
> >  2 files changed, 69 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/fault-injection/fault-injection.rst b/Documentation/fault-injection/fault-injection.rst
> > index 17779a2772e5..da6c5796b1f8 100644
> > --- a/Documentation/fault-injection/fault-injection.rst
> > +++ b/Documentation/fault-injection/fault-injection.rst
> > @@ -233,6 +233,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
> 
>                         kernel developers considering adding a function
> 
> > +ALLOW_ERROR_INJECTION() macro.
> 
>    using the 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
> 
>      increment/decrement a counter,
> 
> > +  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
> 
>    do something.                                        skips all 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
> 
>                          function
> 
> > +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
> 
>                                                                   allocated
> 
> > +  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
> 
>           specify
> 
> > +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
> >  -----------------------------------------
> >  
> > diff --git a/include/asm-generic/error-injection.h b/include/asm-generic/error-injection.h
> > index c0b9d3217ed9..b05253f68eaa 100644
> > --- a/include/asm-generic/error-injection.h
> > +++ b/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
> 
>                         If you are unsure ...
> 
> > + * 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				\
> > 
> 
> -- 
> ~Randy


-- 
Masami Hiramatsu (Google) <mhiramat@kernel.org>