Hi-- On 12/11/22 18:46, Masami Hiramatsu (Google) wrote: > From: Masami Hiramatsu (Google) <mhiramat@xxxxxxxxxx> > > 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@xxxxxxxxxx> > Link: https://lore.kernel.org/all/20221211115218.2e6e289bb85f8cf53c11aa97@xxxxxxxxxx/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
