[2/2] docs: fault-injection: Add requirements of error injectable functions
Commit Message
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(-)
Comments
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 \
>
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
@@ -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
-----------------------------------------
@@ -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 \