[PATCH] fault-injection: Correct, disambiguate, and reformat documentation

# Disable any fault injection

echo 0 > /debug/$1/stacktrace-depth

echo `cat /sys/module/$2/sections/.text` > /debug/$1/address-start

echo `cat /sys/module/$2/sections/.exit.text` > /debug/$1/address-end

echo `cat /sys/module/$2/sections/.text` > /debug/$1/require-start

echo `cat /sys/module/$2/sections/.exit.text` > /debug/$1/require-end

echo $STACKTRACE_DEPTH > /debug/$1/stacktrace-depth

o fail_make_request

  injects disk IO errors on permitted devices by

  injects disk IO errors on devices permitted by setting

  /sys/block/<device>/make-it-fail or

  /sys/block/<device>/<partition>/make-it-fail. (generic_make_request())

fault-inject-debugfs kernel module provides some debugfs entries for runtime

configuration of fault-injection capabilities.

- /debug/*/probability:

- /debug/fail*/probability:

	likelihood of failure injection, in percent.

	Format: <percent>

	Note that one-failure-per-handred is a very high error rate

	for some testcases. Please set probably=100 and configure

	/debug/*/interval for such testcases.

	Note that one-failure-per-hundred is a very high error rate

	for some testcases.  Consider setting probability=100 and configure

	/debug/fail*/interval for such testcases.

- /debug/*/interval:

- /debug/fail*/interval:

	specifies the interval between failures, for calls to

	should_fail() that pass all the other tests.

	Note that if you enable this, by setting interval>1, you will

	probably want to set probability=100.

- /debug/*/times:

- /debug/fail*/times:

	specifies how many times failures may happen at most.

	A value of -1 means "no limit".

- /debug/*/space:

- /debug/fail*/space:

	specifies an initial resource "budget", decremented by "size"

	on each call to should_fail(,size).  Failure injection is

	suppressed until "space" reaches zero.

- /debug/*/verbose

- /debug/fail*/verbose

	Format: { 0 | 1 | 2 }

	specifies the verbosity of the messages when failure is injected.

	We default to 0 (no extra messages), setting it to '1' will

	print only to tell failure happened, '2' will print call trace too -

	it is useful to debug the problems revealed by fault injection

	capabilities.

	specifies the verbosity of the messages when failure is

	injected.  '0' means no messages; '1' will print only a single

	log line per failure; '2' will print a call trace too -- useful

	to debug the problems revealed by fault injection.

- /debug/*/task-filter:

- /debug/fail*/task-filter:

	Format: { 0 | 1 }

	A value of '0' disables filtering by process (default).

	Format: { 'Y' | 'N' }

	A value of 'N' disables filtering by process (default).

	Any positive value limits failures to only processes indicated by

	/proc/<pid>/make-it-fail==1.

- /debug/*/require-start:

- /debug/*/require-end:

- /debug/*/reject-start:

- /debug/*/reject-end:

- /debug/fail*/require-start:

- /debug/fail*/require-end:

- /debug/fail*/reject-start:

- /debug/fail*/reject-end:

	specifies the range of virtual addresses tested during

	stacktrace walking.  Failure is injected only if some caller

	Default required range is [0,ULONG_MAX) (whole of virtual address space).

	Default rejected range is [0,0).

- /debug/*/stacktrace-depth:

- /debug/fail*/stacktrace-depth:

	specifies the maximum stacktrace depth walked during search

	for a caller within [address-start,address-end).

	for a caller within [require-start,require-end) OR

	[reject-start,reject-end).

- /debug/fail_page_alloc/ignore-gfp-highmem:

	Format: { 0 | 1 }

	default is 0, setting it to '1' won't inject failures into

	Format: { 'Y' | 'N' }

	default is 'N', setting it to 'Y' won't inject failures into

	highmem/user allocations.

- /debug/failslab/ignore-gfp-wait:

- /debug/fail_page_alloc/ignore-gfp-wait:

	Format: { 0 | 1 }

	default is 0, setting it to '1' will inject failures

	Format: { 'Y' | 'N' }

	default is 'N', setting it to 'Y' will inject failures

	only into non-sleep allocations (GFP_ATOMIC allocations).

o Boot option

  Please see the definition of struct fault_attr in fault-inject.h

  for details.

o provide the way to configure fault attributes

o provide a way to configure fault attributes

- boot option

  If you need to enable the fault injection capability from boot time, you can

  provide boot option to configure it. There is a helper function for it.

  provide boot option to configure it. There is a helper function for it:

	setup_fault_attr(attr, str);

- debugfs entries

  failslab, fail_page_alloc, and fail_make_request use this way.

  There is a helper function for it.

  Helper functions:

	init_fault_attr_entries(entries, attr, name);

	void cleanup_fault_attr_entries(entries);

o add a hook to insert failures

  should_fail() returns 1 when failures should happen.

  Upon should_fail() returning true, client code should inject a failure.

	should_fail(attr, size);