Merge branch 'docs-3.19' into docs-next

	     : /* outputs */ : /* inputs */ : /* clobbers */);

		Chapter 20: Conditional Compilation

Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c

files; doing so makes code harder to read and logic harder to follow.  Instead,

use such conditionals in a header file defining functions for use in those .c

files, providing no-op stub versions in the #else case, and then call those

functions unconditionally from .c files.  The compiler will avoid generating

any code for the stub calls, producing identical results, but the logic will

remain easy to follow.

Prefer to compile out entire functions, rather than portions of functions or

portions of expressions.  Rather than putting an ifdef in an expression, factor

out part or all of the expression into a separate helper function and apply the

conditional to that function.

If you have a function or variable which may potentially go unused in a

particular configuration, and the compiler would warn about its definition

going unused, mark the definition as __maybe_unused rather than wrapping it in

a preprocessor conditional.  (However, if a function or variable *always* goes

unused, delete it.)

Within code, where possible, use the IS_ENABLED macro to convert a Kconfig

symbol into a C boolean expression, and use it in a normal C conditional:

	if (IS_ENABLED(CONFIG_SOMETHING)) {

		...

	}

The compiler will constant-fold the conditional away, and include or exclude

the block of code just as with an #ifdef, so this will not add any runtime

overhead.  However, this approach still allows the C compiler to see the code

inside the block, and check it for correctness (syntax, types, symbol

references, etc).  Thus, you still have to use an #ifdef if the code inside the

block references symbols that will not exist if the condition is not met.

At the end of any non-trivial #if or #ifdef block (more than a few lines),

place a comment after the #endif on the same line, noting the conditional

expression used.  For instance:

#ifdef CONFIG_SOMETHING

...

#endif /* CONFIG_SOMETHING */

		Appendix I: References

=============================================================

To build the tests:

  $ make -C tools/testing/selftests

To run the tests:

  $ make -C tools/testing/selftests run_tests

To build and run the tests with a single command, use:

  $ make kselftest

- note that some tests will require root privileges.

To run only tests targeted for a single subsystem: (including

hotplug targets in limited mode)

  $  make -C tools/testing/selftests TARGETS=cpu-hotplug run_tests

Running a subset of selftests

========================================

You can use the "TARGETS" variable on the make command line to specify

single test to run, or a list of tests to run.

To run only tests targeted for a single subsystem:

  $  make -C tools/testing/selftests TARGETS=ptrace run_tests

You can specify multiple tests to build and run:

  $  make TARGETS="size timers" kselftest

See the top-level tools/testing/selftests/Makefile for the list of all

possible targets.

See the top-level tools/testing/selftests/Makefile for the list of all possible

targets.

Running the full range hotplug selftests

========================================

To build the tests:

To build the hotplug tests:

  $ make -C tools/testing/selftests hotplug

To run the tests:

To run the hotplug tests:

  $ make -C tools/testing/selftests run_hotplug

- note that some tests will require root privileges.

Contributing new tests

======================