kconfig: document use of HAVE_*

It has been discussed on lkml several times but we need it documented as this is new stuff. Signed-off-by: Sam Ravnborg <sam@ravnborg.org>

kconfig: document use of HAVE_*
It has been discussed on lkml several times but we need it documented as this is new stuff. Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
Sam Ravnborg
1 parent 312b1485fb
Showing 1 changed file with 36 additions and 0 deletions Side-by-side Diff
Documentation/kbuild/kconfig-language.txt
@@ -330,6 +330,42 @@
 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
...	...	@@ -330,6 +330,42 @@
330	330	first glance and most of which have become idioms in several Kconfig
331	331	files.
332	332
	333	+Adding common features and make the usage configurable
	334	+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	335	+It is a common idiom to implement a feature/functionality that are
	336	+relevant for some architectures but not all.
	337	+The recommended way to do so is to use a config variable named HAVE_*
	338	+that is defined in a common Kconfig file and selected by the relevant
	339	+architectures.
	340	+An example is the generic IOMAP functionality.
	341	+
	342	+We would in lib/Kconfig see:
	343	+
	344	+# Generic IOMAP is used to ...
	345	+config HAVE_GENERIC_IOMAP
	346	+
	347	+config GENERIC_IOMAP
	348	+ depends on HAVE_GENERIC_IOMAP && FOO
	349	+
	350	+And in lib/Makefile we would see:
	351	+obj-$(CONFIG_GENERIC_IOMAP) += iomap.o
	352	+
	353	+For each architecture using the generic IOMAP functionality we would see:
	354	+
	355	+config X86
	356	+ select ...
	357	+ select HAVE_GENERIC_IOMAP
	358	+ select ...
	359	+
	360	+Note: we use the existing config option and avoid creating a new
	361	+config variable to select HAVE_GENERIC_IOMAP.
	362	+
	363	+Note: the use of the internal config variable HAVE_GENERIC_IOMAP, it is
	364	+introduced to overcome the limitation of select which will force a
	365	+config option to 'y' no matter the dependencies.
	366	+The dependencies are moved to the symbol GENERIC_IOMAP and we avoid the
	367	+situation where select forces a symbol equals to 'y'.
	368	+
333	369	Build as module only
334	370	~~~~~~~~~~~~~~~~~~~~
335	371	To restrict a component build to module-only, qualify its config symbol