Merge git://git.infradead.org/mtd-2.6

[linux-2.6] / Documentation / kbuild / kconfig-language.txt

diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt
index a43fcc68e171ab96491599959314c7039a7b2525..00b950d1c1931a7b20c19c2595eb2fbf062eb424 100644 (file)
--- a/Documentation/kbuild/kconfig-language.txt
+++ b/Documentation/kbuild/kconfig-language.txt
@@ -104,14 +104,15 @@ applicable everywhere (see syntax).
   Reverse dependencies can only be used with boolean or tristate
   symbols.
   Note:
-       select is evil.... select will by brute force set a symbol
-       equal to 'y' without visiting the dependencies. So abusing
-       select you are able to select a symbol FOO even if FOO depends
-       on BAR that is not set. In general use select only for
-       non-visible symbols (no prompts anywhere) and for symbols with
-       no dependencies. That will limit the usefulness but on the
-       other hand avoid the illegal configurations all over. kconfig
-       should one day warn about such things.
+       select should be used with care. select will force
+       a symbol to a value without visiting the dependencies.
+       By abusing select you are able to select a symbol FOO even
+       if FOO depends on BAR that is not set.
+       In general use select only for non-visible symbols
+       (no prompts anywhere) and for symbols with no dependencies.
+       That will limit the usefulness but on the other hand avoid
+       the illegal configurations all over.
+       kconfig should one day warn about such things.
 
 - numerical ranges: "range" <symbol> <symbol> ["if" <expr>]
   This allows to limit the range of possible input values for int
@@ -330,6 +331,42 @@ This is a collection of Kconfig tips, most of which aren't obvious at
 first glance and most of which have become idioms in several Kconfig
 files.
 
+Adding common features and make the usage configurable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It is a common idiom to implement a feature/functionality that are
+relevant for some architectures but not all.
+The recommended way to do so is to use a config variable named HAVE_*
+that is defined in a common Kconfig file and selected by the relevant
+architectures.
+An example is the generic IOMAP functionality.
+
+We would in lib/Kconfig see:
+
+# Generic IOMAP is used to ...
+config HAVE_GENERIC_IOMAP
+
+config GENERIC_IOMAP
+       depends on HAVE_GENERIC_IOMAP && FOO
+
+And in lib/Makefile we would see:
+obj-$(CONFIG_GENERIC_IOMAP) += iomap.o
+
+For each architecture using the generic IOMAP functionality we would see:
+
+config X86
+       select ...
+       select HAVE_GENERIC_IOMAP
+       select ...
+
+Note: we use the existing config option and avoid creating a new
+config variable to select HAVE_GENERIC_IOMAP.
+
+Note: the use of the internal config variable HAVE_GENERIC_IOMAP, it is
+introduced to overcome the limitation of select which will force a
+config option to 'y' no matter the dependencies.
+The dependencies are moved to the symbol GENERIC_IOMAP and we avoid the
+situation where select forces a symbol equals to 'y'.
+
 Build as module only
 ~~~~~~~~~~~~~~~~~~~~
 To restrict a component build to module-only, qualify its config symbol