docs: kbuild: convert docs to ReST and rename to *.rst

The kbuild documentation clearly shows that the documents there are written at different times: some use markdown, some use their own peculiar logic to split sections. Convert everything to ReST without affecting too much the author's style and avoiding adding uneeded markups. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings.

Mauro Carvalho Chehab committed 7 years ago

Commit cd238ef1 parent d7b461c48 files · +846 −567Browse files

Unified · Split

48 files

Documentation/admin-guide/README.rst +1 −1
Documentation/kbuild/headers_install.rst +3 −2
Documentation/kbuild/index.rst +27 −0
Documentation/kbuild/issues.rst +11 −0
Documentation/kbuild/kbuild.rst +68 −51
Documentation/kbuild/kconfig-language.rst +131 −111
Documentation/kbuild/kconfig-macro-language.rst +21 −16
Documentation/kbuild/kconfig.rst +82 −54
Documentation/kbuild/makefiles.rst +335 −195
Documentation/kbuild/modules.rst +100 −70
Documentation/kernel-hacking/hacking.rst +2 −2
Documentation/process/coding-style.rst +1 −1
Documentation/process/submit-checklist.rst +1 −1
Documentation/translations/it_IT/kernel-hacking/hacking.rst +2 −2
Documentation/translations/it_IT/process/coding-style.rst +1 −1
Documentation/translations/it_IT/process/submit-checklist.rst +1 −1
Documentation/translations/zh_CN/process/coding-style.rst +1 −1
Documentation/translations/zh_CN/process/submit-checklist.rst +1 −1
Kconfig +1 −1
arch/arc/plat-eznps/Kconfig +1 −1
arch/c6x/Kconfig +1 −1
arch/microblaze/Kconfig.debug +1 −1
arch/microblaze/Kconfig.platform +1 −1
arch/nds32/Kconfig +1 −1
arch/openrisc/Kconfig +1 −1
arch/powerpc/sysdev/Kconfig +1 −1
arch/riscv/Kconfig +1 −1
drivers/auxdisplay/Kconfig +1 −1
drivers/firmware/Kconfig +1 −1
drivers/mtd/devices/Kconfig +1 −1
drivers/net/ethernet/smsc/Kconfig +3 −3
drivers/net/wireless/intel/iwlegacy/Kconfig +2 −2
drivers/net/wireless/intel/iwlwifi/Kconfig +1 −1
drivers/parport/Kconfig +1 −1
drivers/scsi/Kconfig +2 −2
drivers/staging/sm750fb/Kconfig +1 −1
drivers/usb/misc/Kconfig +2 −2
drivers/video/fbdev/Kconfig +7 −7
net/bridge/netfilter/Kconfig +1 −1
net/ipv4/netfilter/Kconfig +1 −1
net/ipv6/netfilter/Kconfig +1 −1
net/netfilter/Kconfig +8 −8
net/tipc/Kconfig +1 −1
scripts/Kbuild.include +2 −2
scripts/Makefile.host +1 −1
scripts/kconfig/symbol.c +1 −1
scripts/kconfig/tests/err_recursive_dep/expected_stderr +7 −7
sound/oss/dmasound/Kconfig +3 −3

Documentation/admin-guide/README.rst+1−1

@@ -227,7 +227,7 @@ Configuring the kernel · 226 unmodified lines
227	227	"make tinyconfig" Configure the tiniest possible kernel.
228	228
229	229	You can find more information on using the Linux kernel config tools
230		− in Documentation/kbuild/kconfig.txt.
	230	+ in Documentation/kbuild/kconfig.rst.
231	231
232	232	- NOTES on ``make config``:
233	233

Documentation/kbuild/headers_install.rstrenamed from Documentation/kbuild/headers_install.txt+3−2

@@ -1,3 +1,4 @@
	1	+=============================================
1	2	Exporting kernel headers for use by userspace
2	3	=============================================
3	4
@@ -22,14 +23,14 @@ older kernel. · 18 unmodified lines
22	23
23	24	The "make headers_install" command can be run in the top level directory of the
24	25	kernel source code (or using a standard out-of-tree build). It takes two
25		−optional arguments:
	26	+optional arguments::
26	27
27	28	make headers_install ARCH=i386 INSTALL_HDR_PATH=/usr
28	29
29	30	ARCH indicates which architecture to produce headers for, and defaults to the
30	31	current architecture. The linux/asm directory of the exported kernel headers
31	32	is platform-specific, to see a complete list of supported architectures use
32		−the command:
	33	+the command::
33	34
34	35	ls -d include/asm-* \| sed 's/.*-//'
35	36

Documentation/kbuild/index.rst+27−0

@@ -0,0 +1,27 @@
	1	+:orphan:
	2	+
	3	+===================
	4	+Kernel Build System
	5	+===================
	6	+
	7	+.. toctree::
	8	+ :maxdepth: 1
	9	+
	10	+ kconfig-language
	11	+ kconfig-macro-language
	12	+
	13	+ kbuild
	14	+ kconfig
	15	+ makefiles
	16	+ modules
	17	+
	18	+ headers_install
	19	+
	20	+ issues
	21	+
	22	+.. only:: subproject and html
	23	+
	24	+ Indices
	25	+ =======
	26	+
	27	+ * :ref:`genindex`

Documentation/kbuild/issues.rst+11−0

@@ -0,0 +1,11 @@
	1	+Recursion issue #1
	2	+------------------
	3	+
	4	+ .. include:: Kconfig.recursion-issue-01
	5	+ :literal:
	6	+
	7	+Recursion issue #2
	8	+------------------
	9	+
	10	+ .. include:: Kconfig.recursion-issue-02
	11	+ :literal:

Documentation/kbuild/kbuild.rstrenamed from Documentation/kbuild/kbuild.txt+68−51

@@ -1,13 +1,19 @@
	1	+======
	2	+Kbuild
	3	+======
	4	+
	5	+
1	6	Output files
	7	+============
2	8
3	9	modules.order
4		−--------------------------------------------------
	10	+-------------
5	11	This file records the order in which modules appear in Makefiles. This
6	12	is used by modprobe to deterministically resolve aliases that match
7	13	multiple modules.
8	14
9	15	modules.builtin
10		−--------------------------------------------------
	16	+---------------
11	17	This file lists all modules that are built into the kernel. This is used
12	18	by modprobe to not fail when trying to load something builtin.
13	19
@@ -18,84 +24,90 @@ Unlike modinfo of a separate module, all fields are prefixed with module name. · 4 unmodified lines
18	24
19	25
20	26	Environment variables
	27	+=====================
21	28
22	29	KCPPFLAGS
23		−--------------------------------------------------
	30	+---------
24	31	Additional options to pass when preprocessing. The preprocessing options
25	32	will be used in all cases where kbuild does preprocessing including
26	33	building C files and assembler files.
27	34
28	35	KAFLAGS
29		−--------------------------------------------------
	36	+-------
30	37	Additional options to the assembler (for built-in and modules).
31	38
32	39	AFLAGS_MODULE
33		−--------------------------------------------------
	40	+-------------
34	41	Additional module specific options to use for $(AS).
35	42
36	43	AFLAGS_KERNEL
37		−--------------------------------------------------
	44	+-------------
38	45	Additional options for $(AS) when used for assembler
39	46	code for code that is compiled as built-in.
40	47
41	48	KCFLAGS
42		−--------------------------------------------------
	49	+-------
43	50	Additional options to the C compiler (for built-in and modules).
44	51
45	52	CFLAGS_KERNEL
46		−--------------------------------------------------
	53	+-------------
47	54	Additional options for $(CC) when used to compile
48	55	code that is compiled as built-in.
49	56
50	57	CFLAGS_MODULE
51		−--------------------------------------------------
	58	+-------------
52	59	Additional module specific options to use for $(CC).
53	60
54	61	LDFLAGS_MODULE
55		−--------------------------------------------------
	62	+--------------
56	63	Additional options used for $(LD) when linking modules.
57	64
58	65	HOSTCFLAGS
59		−--------------------------------------------------
	66	+----------
60	67	Additional flags to be passed to $(HOSTCC) when building host programs.
61	68
62	69	HOSTCXXFLAGS
63		−--------------------------------------------------
	70	+------------
64	71	Additional flags to be passed to $(HOSTCXX) when building host programs.
65	72
66	73	HOSTLDFLAGS
67		−--------------------------------------------------
	74	+-----------
68	75	Additional flags to be passed when linking host programs.
69	76
70	77	HOSTLDLIBS
71		−--------------------------------------------------
	78	+----------
72	79	Additional libraries to link against when building host programs.
73	80
74	81	KBUILD_KCONFIG
75		−--------------------------------------------------
	82	+--------------
76	83	Set the top-level Kconfig file to the value of this environment
77	84	variable. The default name is "Kconfig".
78	85
79	86	KBUILD_VERBOSE
80		−--------------------------------------------------
	87	+--------------
81	88	Set the kbuild verbosity. Can be assigned same values as "V=...".
	89	+
82	90	See make help for the full list.
	91	+
83	92	Setting "V=..." takes precedence over KBUILD_VERBOSE.
84	93
85	94	KBUILD_EXTMOD
86		−--------------------------------------------------
	95	+-------------
87	96	Set the directory to look for the kernel source when building external
88	97	modules.
	98	+
89	99	Setting "M=..." takes precedence over KBUILD_EXTMOD.
90	100
91	101	KBUILD_OUTPUT
92		−--------------------------------------------------
	102	+-------------
93	103	Specify the output directory when building the kernel.
	104	+
94	105	The output directory can also be specified using "O=...".
	106	+
95	107	Setting "O=..." takes precedence over KBUILD_OUTPUT.
96	108
97	109	KBUILD_DEBARCH
98		−--------------------------------------------------
	110	+--------------
99	111	For the deb-pkg target, allows overriding the normal heuristics deployed by
100	112	deb-pkg. Normally deb-pkg attempts to guess the right architecture based on
101	113	the UTS_MACHINE variable, and on some architectures also the kernel config.
@@ -103,44 +115,48 @@ The value of KBUILD_DEBARCH is assumed (not checked) to be a valid Debian · 1 unmodified line
103	115	architecture.
104	116
105	117	ARCH
106		−--------------------------------------------------
	118	+----
107	119	Set ARCH to the architecture to be built.
	120	+
108	121	In most cases the name of the architecture is the same as the
109	122	directory name found in the arch/ directory.
	123	+
110	124	But some architectures such as x86 and sparc have aliases.
111		−x86: i386 for 32 bit, x86_64 for 64 bit
112		−sh: sh for 32 bit, sh64 for 64 bit
113		−sparc: sparc32 for 32 bit, sparc64 for 64 bit
	125	+
	126	+- x86: i386 for 32 bit, x86_64 for 64 bit
	127	+- sh: sh for 32 bit, sh64 for 64 bit
	128	+- sparc: sparc32 for 32 bit, sparc64 for 64 bit
114	129
115	130	CROSS_COMPILE
116		−--------------------------------------------------
	131	+-------------
117	132	Specify an optional fixed part of the binutils filename.
118	133	CROSS_COMPILE can be a part of the filename or the full path.
119	134
120	135	CROSS_COMPILE is also used for ccache in some setups.
121	136
122	137	CF
123		−--------------------------------------------------
	138	+--
124	139	Additional options for sparse.
125		−CF is often used on the command-line like this:
	140	+
	141	+CF is often used on the command-line like this::
126	142
127	143	make CF=-Wbitwise C=2
128	144
129	145	INSTALL_PATH
130		−--------------------------------------------------
	146	+------------
131	147	INSTALL_PATH specifies where to place the updated kernel and system map
132	148	images. Default is /boot, but you can set it to other values.
133	149
134	150	INSTALLKERNEL
135		−--------------------------------------------------
	151	+-------------
136	152	Install script called when using "make install".
137	153	The default name is "installkernel".
138	154
139	155	The script will be called with the following arguments:
140		− $1 - kernel version
141		− $2 - kernel image file
142		− $3 - kernel map file
143		− $4 - default install path (use root directory if blank)
	156	+ - $1 - kernel version
	157	+ - $2 - kernel image file
	158	+ - $3 - kernel map file
	159	+ - $4 - default install path (use root directory if blank)
144	160
145	161	The implementation of "make install" is architecture specific
146	162	and it may differ from the above.
@@ -149,32 +165,33 @@ INSTALLKERNEL is provided to enable the possibility to · 2 unmodified lines
149	165	specify a custom installer when cross compiling a kernel.
150	166
151	167	MODLIB
152		−--------------------------------------------------
	168	+------
153	169	Specify where to install modules.
154		−The default value is:
	170	+The default value is::
155	171
156	172	$(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE)
157	173
158	174	The value can be overridden in which case the default value is ignored.
159	175
160	176	INSTALL_MOD_PATH
161		−--------------------------------------------------
	177	+----------------
162	178	INSTALL_MOD_PATH specifies a prefix to MODLIB for module directory
163	179	relocations required by build roots. This is not defined in the
164	180	makefile but the argument can be passed to make if needed.
165	181
166	182	INSTALL_MOD_STRIP
167		−--------------------------------------------------
	183	+-----------------
168	184	INSTALL_MOD_STRIP, if defined, will cause modules to be
169	185	stripped after they are installed. If INSTALL_MOD_STRIP is '1', then
170	186	the default option --strip-debug will be used. Otherwise,
171	187	INSTALL_MOD_STRIP value will be used as the options to the strip command.
172	188
173	189	INSTALL_HDR_PATH
174		−--------------------------------------------------
	190	+----------------
175	191	INSTALL_HDR_PATH specifies where to install user space headers when
176	192	executing "make headers_*".
177		−The default value is:
	193	+
	194	+The default value is::
178	195
179	196	$(objtree)/usr
180	197
@@ -184,65 +201,65 @@ The output directory is often set using "O=..." on the commandline. · 3 unmodified lines
184	201	The value can be overridden in which case the default value is ignored.
185	202
186	203	KBUILD_SIGN_PIN
187		−--------------------------------------------------
	204	+---------------
188	205	This variable allows a passphrase or PIN to be passed to the sign-file
189	206	utility when signing kernel modules, if the private key requires such.
190	207
191	208	KBUILD_MODPOST_WARN
192		−--------------------------------------------------
	209	+-------------------
193	210	KBUILD_MODPOST_WARN can be set to avoid errors in case of undefined
194	211	symbols in the final module linking stage. It changes such errors
195	212	into warnings.
196	213
197	214	KBUILD_MODPOST_NOFINAL
198		−--------------------------------------------------
	215	+----------------------
199	216	KBUILD_MODPOST_NOFINAL can be set to skip the final link of modules.
200	217	This is solely useful to speed up test compiles.
201	218
202	219	KBUILD_EXTRA_SYMBOLS
203		−--------------------------------------------------
	220	+--------------------
204	221	For modules that use symbols from other modules.
205	222	See more details in modules.txt.
206	223
207	224	ALLSOURCE_ARCHS
208		−--------------------------------------------------
	225	+---------------
209	226	For tags/TAGS/cscope targets, you can specify more than one arch
210		−to be included in the databases, separated by blank space. E.g.:
	227	+to be included in the databases, separated by blank space. E.g.::
211	228
212	229	$ make ALLSOURCE_ARCHS="x86 mips arm" tags
213	230
214		−To get all available archs you can also specify all. E.g.:
	231	+To get all available archs you can also specify all. E.g.::
215	232
216	233	$ make ALLSOURCE_ARCHS=all tags
217	234
218	235	KBUILD_ENABLE_EXTRA_GCC_CHECKS
219		−--------------------------------------------------
	236	+------------------------------
220	237	If enabled over the make command line with "W=1", it turns on additional
221	238	gcc -W... options for more extensive build-time checking.
222	239
223	240	KBUILD_BUILD_TIMESTAMP
224		−--------------------------------------------------
	241	+----------------------
225	242	Setting this to a date string overrides the timestamp used in the
226	243	UTS_VERSION definition (uname -v in the running kernel). The value has to
227	244	be a string that can be passed to date -d. The default value
228	245	is the output of the date command at one point during build.
229	246
230	247	KBUILD_BUILD_USER, KBUILD_BUILD_HOST
231		−--------------------------------------------------
	248	+------------------------------------
232	249	These two variables allow to override the user@host string displayed during
233	250	boot and in /proc/version. The default value is the output of the commands
234	251	whoami and host, respectively.
235	252
236	253	KBUILD_LDS
237		−--------------------------------------------------
	254	+----------
238	255	The linker script with full path. Assigned by the top-level Makefile.
239	256
240	257	KBUILD_VMLINUX_OBJS
241		−--------------------------------------------------
	258	+-------------------
242	259	All object files for vmlinux. They are linked to vmlinux in the same
243	260	order as listed in KBUILD_VMLINUX_OBJS.
244	261
245	262	KBUILD_VMLINUX_LIBS
246		−--------------------------------------------------
	263	+-------------------
247	264	All .a "lib" files for vmlinux. KBUILD_VMLINUX_OBJS and KBUILD_VMLINUX_LIBS
248	265	together specify all the object files used to link vmlinux.

Documentation/kbuild/kconfig-language.rstrenamed from Documentation/kbuild/kconfig-language.txt+131−111

@@ -1,8 +1,12 @@
	1	+================
	2	+Kconfig Language
	3	+================
	4	+
1	5	Introduction
2	6	------------
3	7
4	8	The configuration database is a collection of configuration options
5		−organized in a tree structure:
	9	+organized in a tree structure::
6	10
7	11	+- Code maturity level options
8	12	\| +- Prompt for development and/or incomplete code/drivers
@@ -25,9 +29,9 @@ Menu entries · 16 unmodified lines
25	29	------------
26	30
27	31	Most entries define a config option; all other entries help to organize
28		−them. A single configuration option is defined like this:
	32	+them. A single configuration option is defined like this::
29	33
30		−config MODVERSIONS
	34	+ config MODVERSIONS
31	35	bool "Set version information on all module symbols"
32	36	depends on MODULES
33	37	help
@@ -52,10 +56,12 @@ applicable everywhere (see syntax). · 18 unmodified lines
52	56	Every config option must have a type. There are only two basic types:
53	57	tristate and string; the other types are based on these two. The type
54	58	definition optionally accepts an input prompt, so these two examples
55		− are equivalent:
	59	+ are equivalent::
56	60
57	61	bool "Networking support"
58		− and
	62	+
	63	+ and::
	64	+
59	65	bool
60	66	prompt "Networking support"
61	67
@@ -98,8 +104,10 @@ applicable everywhere (see syntax). · 36 unmodified lines
98	104	d) Hardware or infrastructure that everybody expects, such as CONFIG_NET
99	105	or CONFIG_BLOCK. These are rare exceptions.
100	106
101		−- type definition + default value:
	107	+- type definition + default value::
	108	+
102	109	"def_bool"/"def_tristate" <expr> ["if" <expr>]
	110	+
103	111	This is a shorthand notation for a type definition plus a value.
104	112	Optionally dependencies for this default value can be added with "if".
105	113
@@ -107,11 +115,13 @@ applicable everywhere (see syntax). · 1 unmodified line
107	115	This defines a dependency for this menu entry. If multiple
108	116	dependencies are defined, they are connected with '&&'. Dependencies
109	117	are applied to all other options within this menu entry (which also
110		− accept an "if" expression), so these two examples are equivalent:
	118	+ accept an "if" expression), so these two examples are equivalent::
111	119
112	120	bool "foo" if BAR
113	121	default y if BAR
114		− and
	122	+
	123	+ and::
	124	+
115	125	depends on BAR
116	126	bool "foo"
117	127	default y
@@ -124,6 +134,7 @@ applicable everywhere (see syntax). · 6 unmodified lines
124	134	times, the limit is set to the largest selection.
125	135	Reverse dependencies can only be used with boolean or tristate
126	136	symbols.
	137	+
127	138	Note:
128	139	select should be used with care. select will force
129	140	a symbol to a value without visiting the dependencies.
@@ -139,24 +150,26 @@ applicable everywhere (see syntax). · 9 unmodified lines
139	150	symbol except that the "implied" symbol's value may still be set to n
140	151	from a direct dependency or with a visible prompt.
141	152
142		− Given the following example:
	153	+ Given the following example::
143	154
144		− config FOO
	155	+ config FOO
145	156	tristate
146	157	imply BAZ
147	158
148		− config BAZ
	159	+ config BAZ
149	160	tristate
150	161	depends on BAR
151	162
152	163	The following values are possible:
153	164
	165	+ === === ============= ==============
154	166	FOO BAR BAZ's default choice for BAZ
155		− --- --- ------------- --------------
	167	+ === === ============= ==============
156	168	n y n N/m/y
157	169	m y m M/y/n
158	170	y y y Y/n
159	171	y n * N
	172	+ === === ============= ==============
160	173
161	174	This is useful e.g. with multiple drivers that want to indicate their
162	175	ability to hook into a secondary subsystem while allowing the user to
@@ -208,9 +221,9 @@ Menu dependencies · 45 unmodified lines
208	221	Dependencies define the visibility of a menu entry and can also reduce
209	222	the input range of tristate symbols. The tristate logic used in the
210	223	expressions uses one more state than normal boolean logic to express the
211		−module state. Dependency expressions have the following syntax:
	224	+module state. Dependency expressions have the following syntax::
212	225
213		−<expr> ::= <symbol> (1)
	226	+ <expr> ::= <symbol> (1)
214	227	<symbol> '=' <symbol> (2)
215	228	<symbol> '!=' <symbol> (3)
216	229	<symbol1> '<' <symbol2> (4)
@@ -222,7 +235,7 @@ module state. Dependency expressions have the following syntax: · 5 unmodified lines
222	235	<expr> '&&' <expr> (7)
223	236	<expr> '\|\|' <expr> (8)
224	237
225		−Expressions are listed in decreasing order of precedence.
	238	+Expressions are listed in decreasing order of precedence.
226	239
227	240	(1) Convert the symbol into an expression. Boolean and tristate symbols
228	241	are simply converted into the respective expression values. All
@@ -255,15 +268,15 @@ Menu structure · 26 unmodified lines
255	268	--------------
256	269
257	270	The position of a menu entry in the tree is determined in two ways. First
258		−it can be specified explicitly:
	271	+it can be specified explicitly::
259	272
260		−menu "Network device support"
	273	+ menu "Network device support"
261	274	depends on NET
262	275
263		−config NETDEVICES
	276	+ config NETDEVICES
264	277	...
265	278
266		−endmenu
	279	+ endmenu
267	280
268	281	All entries within the "menu" ... "endmenu" block become a submenu of
269	282	"Network device support". All subentries inherit the dependencies from
@@ -275,17 +288,18 @@ dependencies. If a menu entry somehow depends on the previous entry, it · 5 unmodified lines
275	288	can be made a submenu of it. First, the previous (parent) symbol must
276	289	be part of the dependency list and then one of these two conditions
277	290	must be true:
	291	+
278	292	- the child entry must become invisible, if the parent is set to 'n'
279		−- the child entry must only be visible, if the parent is visible
	293	+- the child entry must only be visible, if the parent is visible::
280	294
281		−config MODULES
	295	+ config MODULES
282	296	bool "Enable loadable module support"
283	297
284		−config MODVERSIONS
	298	+ config MODVERSIONS
285	299	bool "Set version information on all module symbols"
286	300	depends on MODULES
287	301
288		−comment "module support disabled"
	302	+ comment "module support disabled"
289	303	depends on !MODULES
290	304
291	305	MODVERSIONS directly depends on MODULES, this means it's only visible if
@@ -299,6 +313,7 @@ Kconfig syntax · 7 unmodified lines
299	313	The configuration file describes a series of menu entries, where every
300	314	line starts with a keyword (except help texts). The following keywords
301	315	end a menu entry:
	316	+
302	317	- config
303	318	- menuconfig
304	319	- choice/endchoice
@@ -306,17 +321,17 @@ end a menu entry: · 1 unmodified line
306	321	- menu/endmenu
307	322	- if/endif
308	323	- source
309		−The first five also start the definition of a menu entry.
310	324
311		−config:
	325	+The first five also start the definition of a menu entry.
312	326
	327	+config::
313	328	"config" <symbol>
314	329	<config options>
315	330
316	331	This defines a config symbol <symbol> and accepts any of above
317	332	attributes as options.
318	333
319		−menuconfig:
	334	+menuconfig::
320	335	"menuconfig" <symbol>
321	336	<config options>
322	337
@@ -325,43 +340,43 @@ hint to front ends, that all suboptions should be displayed as a · 2 unmodified lines
325	340	separate list of options. To make sure all the suboptions will really
326	341	show up under the menuconfig entry and not outside of it, every item
327	342	from the <config options> list must depend on the menuconfig symbol.
328		−In practice, this is achieved by using one of the next two constructs:
329		−
330		−(1):
331		−menuconfig M
332		−if M
333		− config C1
334		− config C2
335		−endif
336		−
337		−(2):
338		−menuconfig M
339		−config C1
340		− depends on M
341		−config C2
342		− depends on M
	343	+In practice, this is achieved by using one of the next two constructs::
	344	+
	345	+ (1):
	346	+ menuconfig M
	347	+ if M
	348	+ config C1
	349	+ config C2
	350	+ endif
	351	+
	352	+ (2):
	353	+ menuconfig M
	354	+ config C1
	355	+ depends on M
	356	+ config C2
	357	+ depends on M
343	358
344	359	In the following examples (3) and (4), C1 and C2 still have the M
345	360	dependency, but will not appear under menuconfig M anymore, because
346		−of C0, which doesn't depend on M:
347		−
348		−(3):
349		−menuconfig M
350		− config C0
351		−if M
352		− config C1
353		− config C2
354		−endif
355		−
356		−(4):
357		−menuconfig M
358		−config C0
359		−config C1
360		− depends on M
361		−config C2
362		− depends on M
363		−
364		−choices:
	361	+of C0, which doesn't depend on M::
	362	+
	363	+ (3):
	364	+ menuconfig M
	365	+ config C0
	366	+ if M
	367	+ config C1
	368	+ config C2
	369	+ endif
	370	+
	371	+ (4):
	372	+ menuconfig M
	373	+ config C0
	374	+ config C1
	375	+ depends on M
	376	+ config C2
	377	+ depends on M
	378	+
	379	+choices::
365	380
366	381	"choice" [symbol]
367	382	<choice options>
@@ -387,7 +402,7 @@ definitions of that choice. If a [symbol] is associated to the choice, · 19 unmodified lines
387	402	then you may define the same choice (i.e. with the same entries) in another
388	403	place.
389	404
390		−comment:
	405	+comment::
391	406
392	407	"comment" <prompt>
393	408	<comment options>
@@ -396,7 +411,7 @@ This defines a comment which is displayed to the user during the · 2 unmodified lines
396	411	configuration process and is also echoed to the output files. The only
397	412	possible options are dependencies.
398	413
399		−menu:
	414	+menu::
400	415
401	416	"menu" <prompt>
402	417	<menu options>
@@ -407,7 +422,7 @@ This defines a menu block, see "Menu structure" above for more · 4 unmodified lines
407	422	information. The only possible options are dependencies and "visible"
408	423	attributes.
409	424
410		−if:
	425	+if::
411	426
412	427	"if" <expr>
413	428	<if block>
@@ -416,13 +431,13 @@ if: · 2 unmodified lines
416	431	This defines an if block. The dependency expression <expr> is appended
417	432	to all enclosed menu entries.
418	433
419		−source:
	434	+source::
420	435
421	436	"source" <prompt>
422	437
423	438	This reads the specified configuration file. This file is always parsed.
424	439
425		−mainmenu:
	440	+mainmenu::
426	441
427	442	"mainmenu" <prompt>
428	443
@@ -452,20 +467,21 @@ that is defined in a common Kconfig file and selected by the relevant · 23 unmodified lines
452	467	architectures.
453	468	An example is the generic IOMAP functionality.
454	469
455		−We would in lib/Kconfig see:
	470	+We would in lib/Kconfig see::
456	471
457		−# Generic IOMAP is used to ...
458		−config HAVE_GENERIC_IOMAP
	472	+ # Generic IOMAP is used to ...
	473	+ config HAVE_GENERIC_IOMAP
459	474
460		−config GENERIC_IOMAP
	475	+ config GENERIC_IOMAP
461	476	depends on HAVE_GENERIC_IOMAP && FOO
462	477
463		−And in lib/Makefile we would see:
464		−obj-$(CONFIG_GENERIC_IOMAP) += iomap.o
	478	+And in lib/Makefile we would see::
465	479
466		−For each architecture using the generic IOMAP functionality we would see:
	480	+ obj-$(CONFIG_GENERIC_IOMAP) += iomap.o
467	481
468		−config X86
	482	+For each architecture using the generic IOMAP functionality we would see::
	483	+
	484	+ config X86
469	485	select ...
470	486	select HAVE_GENERIC_IOMAP
471	487	select ...
@@ -484,25 +500,25 @@ Adding features that need compiler support · 12 unmodified lines
484	500
485	501	There are several features that need compiler support. The recommended way
486	502	to describe the dependency on the compiler feature is to use "depends on"
487		−followed by a test macro.
	503	+followed by a test macro::
488	504
489		−config STACKPROTECTOR
	505	+ config STACKPROTECTOR
490	506	bool "Stack Protector buffer overflow detection"
491	507	depends on $(cc-option,-fstack-protector)
492	508	...
493	509
494	510	If you need to expose a compiler capability to makefiles and/or C source files,
495		−CC_HAS_ is the recommended prefix for the config option.
	511	+`CC_HAS_` is the recommended prefix for the config option::
496	512
497		−config CC_HAS_STACKPROTECTOR_NONE
	513	+ config CC_HAS_STACKPROTECTOR_NONE
498	514	def_bool $(cc-option,-fno-stack-protector)
499	515
500	516	Build as module only
501	517	~~~~~~~~~~~~~~~~~~~~
502	518	To restrict a component build to module-only, qualify its config symbol
503		−with "depends on m". E.g.:
	519	+with "depends on m". E.g.::
504	520
505		−config FOO
	521	+ config FOO
506	522	depends on BAR && m
507	523
508	524	limits FOO to module (=m) or disabled (=n).
@@ -529,18 +545,18 @@ Simple Kconfig recursive issue · 20 unmodified lines
529	545
530	546	Read: Documentation/kbuild/Kconfig.recursion-issue-01
531	547
532		−Test with:
	548	+Test with::
533	549
534		−make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig
	550	+ make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig
535	551
536	552	Cumulative Kconfig recursive issue
537	553	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
538	554
539	555	Read: Documentation/kbuild/Kconfig.recursion-issue-02
540	556
541		−Test with:
	557	+Test with::
542	558
543		−make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig
	559	+ make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig
544	560
545	561	Practical solutions to kconfig recursive issue
546	562	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -551,7 +567,9 @@ historical issues resolved through these different solutions. · 4 unmodified lines
551	567
552	568	a) Remove any superfluous "select FOO" or "depends on FOO"
553	569	b) Match dependency semantics:
	570	+
554	571	b1) Swap all "select FOO" to "depends on FOO" or,
	572	+
555	573	b2) Swap all "depends on FOO" to "select FOO"
556	574
557	575	The resolution to a) can be tested with the sample Kconfig file
@@ -566,8 +584,9 @@ Documentation/kbuild/Kconfig.recursion-issue-02. · 8 unmodified lines
566	584	Below is a list of examples of prior fixes for these types of recursive issues;
567	585	all errors appear to involve one or more select's and one or more "depends on".
568	586
	587	+============ ===================================
569	588	commit fix
570		−====== ===
	589	+============ ===================================
571	590	06b718c01208 select A -> depends on A
572	591	c22eacfe82f9 depends on A -> depends on B
573	592	6a91e854442c select A -> depends on A
@@ -590,6 +609,7 @@ d9f9ab51e55e select A -> depends on A · 16 unmodified lines
590	609	0c51a4d8abd6 depends on A -> select A (3)
591	610	e98062ed6dc4 select A -> depends on A (3)
592	611	91e5d284a7f1 select A -> (null)
	612	+============ ===================================
593	613
594	614	(1) Partial (or no) quote of error.
595	615	(2) That seems to be the gist of that fix.
@@ -616,11 +636,11 @@ Semantics of Kconfig · 20 unmodified lines
616	636	~~~~~~~~~~~~~~~~~~~~
617	637
618	638	The use of Kconfig is broad, Linux is now only one of Kconfig's users:
619		−one study has completed a broad analysis of Kconfig use in 12 projects [0].
	639	+one study has completed a broad analysis of Kconfig use in 12 projects [0]_.
620	640	Despite its widespread use, and although this document does a reasonable job
621	641	in documenting basic Kconfig syntax a more precise definition of Kconfig
622	642	semantics is welcomed. One project deduced Kconfig semantics through
623		−the use of the xconfig configurator [1]. Work should be done to confirm if
	643	+the use of the xconfig configurator [1]_. Work should be done to confirm if
624	644	the deduced semantics matches our intended Kconfig design goals.
625	645
626	646	Having well defined semantics can be useful for tools for practical
@@ -628,42 +648,42 @@ evaluation of depenencies, for instance one such use known case was work to · 1 unmodified line
628	648	express in boolean abstraction of the inferred semantics of Kconfig to
629	649	translate Kconfig logic into boolean formulas and run a SAT solver on this to
630	650	find dead code / features (always inactive), 114 dead features were found in
631		−Linux using this methodology [1] (Section 8: Threats to validity).
	651	+Linux using this methodology [1]_ (Section 8: Threats to validity).
632	652
633	653	Confirming this could prove useful as Kconfig stands as one of the the leading
634		−industrial variability modeling languages [1] [2]. Its study would help
	654	+industrial variability modeling languages [1]_ [2]_. Its study would help
635	655	evaluate practical uses of such languages, their use was only theoretical
636	656	and real world requirements were not well understood. As it stands though
637	657	only reverse engineering techniques have been used to deduce semantics from
638		−variability modeling languages such as Kconfig [3].
	658	+variability modeling languages such as Kconfig [3]_.
639	659
640		−[0] http://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf
641		−[1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
642		−[2] http://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf
643		−[3] http://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf
	660	+.. [0] http://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf
	661	+.. [1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
	662	+.. [2] http://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf
	663	+.. [3] http://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf
644	664
645	665	Full SAT solver for Kconfig
646	666	~~~~~~~~~~~~~~~~~~~~~~~~~~~
647	667
648		−Although SAT solvers [0] haven't yet been used by Kconfig directly, as noted in
649		−the previous subsection, work has been done however to express in boolean
	668	+Although SAT solvers [4]_ haven't yet been used by Kconfig directly, as noted
	669	+in the previous subsection, work has been done however to express in boolean
650	670	abstraction the inferred semantics of Kconfig to translate Kconfig logic into
651		−boolean formulas and run a SAT solver on it [1]. Another known related project
652		−is CADOS [2] (former VAMOS [3]) and the tools, mainly undertaker [4], which has
653		−been introduced first with [5]. The basic concept of undertaker is to exract
654		−variability models from Kconfig, and put them together with a propositional
655		−formula extracted from CPP #ifdefs and build-rules into a SAT solver in order
656		−to find dead code, dead files, and dead symbols. If using a SAT solver is
657		−desirable on Kconfig one approach would be to evaluate repurposing such efforts
658		−somehow on Kconfig. There is enough interest from mentors of existing projects
659		−to not only help advise how to integrate this work upstream but also help
660		−maintain it long term. Interested developers should visit:
	671	+boolean formulas and run a SAT solver on it [5]_. Another known related project
	672	+is CADOS [6]_ (former VAMOS [7]_) and the tools, mainly undertaker [8]_, which
	673	+has been introduced first with [9]_. The basic concept of undertaker is to
	674	+exract variability models from Kconfig, and put them together with a
	675	+propositional formula extracted from CPP #ifdefs and build-rules into a SAT
	676	+solver in order to find dead code, dead files, and dead symbols. If using a SAT
	677	+solver is desirable on Kconfig one approach would be to evaluate repurposing
	678	+such efforts somehow on Kconfig. There is enough interest from mentors of
	679	+existing projects to not only help advise how to integrate this work upstream
	680	+but also help maintain it long term. Interested developers should visit:
661	681
662	682	http://kernelnewbies.org/KernelProjects/kconfig-sat
663	683
664		−[0] http://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf
665		−[1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
666		−[2] https://cados.cs.fau.de
667		−[3] https://vamos.cs.fau.de
668		−[4] https://undertaker.cs.fau.de
669		−[5] https://www4.cs.fau.de/Publications/2011/tartler_11_eurosys.pdf
	684	+.. [4] http://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf
	685	+.. [5] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
	686	+.. [6] https://cados.cs.fau.de
	687	+.. [7] https://vamos.cs.fau.de
	688	+.. [8] https://undertaker.cs.fau.de
	689	+.. [9] https://www4.cs.fau.de/Publications/2011/tartler_11_eurosys.pdf

Documentation/kbuild/kconfig-macro-language.rstrenamed from Documentation/kbuild/kconfig-macro-language.txt+21−16

@@ -1,3 +1,7 @@
	1	+======================
	2	+Kconfig macro language
	3	+======================
	4	+
1	5	Concept
2	6	-------
3	7
@@ -7,7 +11,7 @@ targets and prerequisites. The other is a macro language for performing textual · 3 unmodified lines
7	11	substitution.
8	12
9	13	There is clear distinction between the two language stages. For example, you
10		−can write a makefile like follows:
	14	+can write a makefile like follows::
11	15
12	16	APP := foo
13	17	SRC := foo.c
@@ -17,7 +21,7 @@ can write a makefile like follows: · 3 unmodified lines
17	21	$(CC) -o $(APP) $(SRC)
18	22
19	23	The macro language replaces the variable references with their expanded form,
20		−and handles as if the source file were input like follows:
	24	+and handles as if the source file were input like follows::
21	25
22	26	foo: foo.c
23	27	gcc -o foo foo.c
@@ -26,7 +30,7 @@ Then, Make analyzes the dependency graph and determines the targets to be · 2 unmodified lines
26	30	updated.
27	31
28	32	The idea is quite similar in Kconfig - it is possible to describe a Kconfig
29		−file like this:
	33	+file like this::
30	34
31	35	CC := gcc
32	36
@@ -34,7 +38,7 @@ file like this: · 1 unmodified line
34	38	def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC))
35	39
36	40	The macro language in Kconfig processes the source file into the following
37		−intermediate:
	41	+intermediate::
38	42
39	43	config CC_HAS_FOO
40	44	def_bool y
@@ -69,7 +73,7 @@ variable. The righthand side of += is expanded immediately if the lefthand · 28 unmodified lines
69	73	side was originally defined as a simple variable. Otherwise, its evaluation is
70	74	deferred.
71	75
72		−The variable reference can take parameters, in the following form:
	76	+The variable reference can take parameters, in the following form::
73	77
74	78	$(name,arg1,arg2,arg3)
75	79
@@ -141,7 +145,7 @@ Make vs Kconfig · 65 unmodified lines
141	145	Kconfig adopts Make-like macro language, but the function call syntax is
142	146	slightly different.
143	147
144		−A function call in Make looks like this:
	148	+A function call in Make looks like this::
145	149
146	150	$(func-name arg1,arg2,arg3)
147	151
@@ -149,14 +153,14 @@ The function name and the first argument are separated by at least one · 1 unmodified line
149	153	whitespace. Then, leading whitespaces are trimmed from the first argument,
150	154	while whitespaces in the other arguments are kept. You need to use a kind of
151	155	trick to start the first parameter with spaces. For example, if you want
152		−to make "info" function print " hello", you can write like follows:
	156	+to make "info" function print " hello", you can write like follows::
153	157
154	158	empty :=
155	159	space := $(empty) $(empty)
156	160	$(info $(space)$(space)hello)
157	161
158	162	Kconfig uses only commas for delimiters, and keeps all whitespaces in the
159		−function call. Some people prefer putting a space after each comma delimiter:
	163	+function call. Some people prefer putting a space after each comma delimiter::
160	164
161	165	$(func-name, arg1, arg2, arg3)
162	166
@@ -166,7 +170,7 @@ Make - for example, $(subst .c, .o, $(sources)) is a typical mistake; it · 3 unmodified lines
166	170	replaces ".c" with " .o".
167	171
168	172	In Make, a user-defined function is referenced by using a built-in function,
169		−'call', like this:
	173	+'call', like this::
170	174
171	175	$(call my-func,arg1,arg2,arg3)
172	176
@@ -179,12 +183,12 @@ Likewise, $(info hello, world) prints "hello, world" to stdout. You could say · 6 unmodified lines
179	183	this is _useful_ inconsistency.
180	184
181	185	In Kconfig, for simpler implementation and grammatical consistency, commas that
182		−appear in the $( ) context are always delimiters. It means
	186	+appear in the $( ) context are always delimiters. It means::
183	187
184	188	$(shell, echo hello, world)
185	189
186	190	is an error because it is passing two parameters where the 'shell' function
187		−accepts only one. To pass commas in arguments, you can use the following trick:
	191	+accepts only one. To pass commas in arguments, you can use the following trick::
188	192
189	193	comma := ,
190	194	$(shell, echo hello$(comma) world)
@@ -195,7 +199,7 @@ Caveats · 4 unmodified lines
195	199
196	200	A variable (or function) cannot be expanded across tokens. So, you cannot use
197	201	a variable as a shorthand for an expression that consists of multiple tokens.
198		−The following works:
	202	+The following works::
199	203
200	204	RANGE_MIN := 1
201	205	RANGE_MAX := 3
@@ -204,7 +208,7 @@ The following works: · 2 unmodified lines
204	208	int "foo"
205	209	range $(RANGE_MIN) $(RANGE_MAX)
206	210
207		−But, the following does not work:
	211	+But, the following does not work::
208	212
209	213	RANGES := 1 3
210	214
@@ -213,7 +217,7 @@ But, the following does not work: · 2 unmodified lines
213	217	range $(RANGES)
214	218
215	219	A variable cannot be expanded to any keyword in Kconfig. The following does
216		−not work:
	220	+not work::
217	221
218	222	MY_TYPE := tristate
219	223
@@ -223,7 +227,8 @@ not work: · 3 unmodified lines
223	227
224	228	Obviously from the design, $(shell command) is expanded in the textual
225	229	substitution phase. You cannot pass symbols to the 'shell' function.
226		−The following does not work as expected.
	230	+
	231	+The following does not work as expected::
227	232
228	233	config ENDIAN_FLAG
229	234	string
@@ -234,7 +239,7 @@ The following does not work as expected. · 4 unmodified lines
234	239	def_bool $(shell $(srctree)/scripts/gcc-check-flag ENDIAN_FLAG)
235	240
236	241	Instead, you can do like follows so that any function call is statically
237		−expanded.
	242	+expanded::
238	243
239	244	config CC_HAS_ENDIAN_FLAG
240	245	bool

Documentation/kbuild/kconfig.rstrenamed from Documentation/kbuild/kconfig.txt+82−54

@@ -1,4 +1,8 @@
1		−This file contains some assistance for using "make *config".
	1	+===================
	2	+Kconfig make config
	3	+===================
	4	+
	5	+This file contains some assistance for using `make *config`.
2	6
3	7	Use "make help" to list all of the possible configuration targets.
4	8
@@ -6,9 +10,8 @@ The xconfig ('qconf'), menuconfig ('mconf'), and nconfig ('nconf') · 1 unmodified line
6	10	programs also have embedded help text. Be sure to check that for
7	11	navigation, search, and other general help text.
8	12
9		−======================================================================
10	13	General
11		−--------------------------------------------------
	14	+-------
12	15
13	16	New kernel releases often introduce new config symbols. Often more
14	17	important, new kernel releases may rename config symbols. When
@@ -17,51 +20,55 @@ this happens, using a previously working .config file and running · 2 unmodified lines
17	20	for you, so you may find that you need to see what NEW kernel
18	21	symbols have been introduced.
19	22
20		−To see a list of new config symbols, use
	23	+To see a list of new config symbols, use::
21	24
22	25	cp user/some/old.config .config
23	26	make listnewconfig
24	27
25	28	and the config program will list any new symbols, one per line.
26	29
27		−Alternatively, you can use the brute force method:
	30	+Alternatively, you can use the brute force method::
28	31
29	32	make oldconfig
30	33	scripts/diffconfig .config.old .config \| less
31	34
32		−______________________________________________________________________
33		−Environment variables for '*config'
	35	+----------------------------------------------------------------------
	36	+
	37	+Environment variables for `*config`
34	38
35	39	KCONFIG_CONFIG
36		−--------------------------------------------------
	40	+--------------
37	41	This environment variable can be used to specify a default kernel config
38	42	file name to override the default name of ".config".
39	43
40	44	KCONFIG_OVERWRITECONFIG
41		−--------------------------------------------------
	45	+-----------------------
42	46	If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not
43	47	break symlinks when .config is a symlink to somewhere else.
44	48
45		−CONFIG_
46		−--------------------------------------------------
47		−If you set CONFIG_ in the environment, Kconfig will prefix all symbols
	49	+`CONFIG_`
	50	+---------
	51	+If you set `CONFIG_` in the environment, Kconfig will prefix all symbols
48	52	with its value when saving the configuration, instead of using the default,
49		−"CONFIG_".
	53	+`CONFIG_`.
	54	+
	55	+----------------------------------------------------------------------
50	56
51		−______________________________________________________________________
52	57	Environment variables for '{allyes/allmod/allno/rand}config'
53	58
54	59	KCONFIG_ALLCONFIG
55		−--------------------------------------------------
	60	+-----------------
56	61	(partially based on lkml email from/by Rob Landley, re: miniconfig)
	62	+
57	63	--------------------------------------------------
	64	+
58	65	The allyesconfig/allmodconfig/allnoconfig/randconfig variants can also
59	66	use the environment variable KCONFIG_ALLCONFIG as a flag or a filename
60	67	that contains config symbols that the user requires to be set to a
61	68	specific value. If KCONFIG_ALLCONFIG is used without a filename where
62		−KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", "make *config"
	69	+KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", `make *config`
63	70	checks for a file named "all{yes/mod/no/def/random}.config"
64		−(corresponding to the *config command that was used) for symbol values
	71	+(corresponding to the `*config` command that was used) for symbol values
65	72	that are to be forced. If this file is not found, it checks for a
66	73	file named "all.config" to contain forced values.
67	74
@@ -74,43 +81,55 @@ This 'KCONFIG_ALLCONFIG' file is a config file which contains · 6 unmodified lines
74	81	(usually a subset of all) preset config symbols. These variable
75	82	settings are still subject to normal dependency checks.
76	83
77		−Examples:
	84	+Examples::
	85	+
78	86	KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig
79		−or
	87	+
	88	+or::
	89	+
80	90	KCONFIG_ALLCONFIG=mini.config make allnoconfig
81		−or
	91	+
	92	+or::
	93	+
82	94	make KCONFIG_ALLCONFIG=mini.config allnoconfig
83	95
84	96	These examples will disable most options (allnoconfig) but enable or
85	97	disable the options that are explicitly listed in the specified
86	98	mini-config files.
87	99
88		−______________________________________________________________________
	100	+----------------------------------------------------------------------
	101	+
89	102	Environment variables for 'randconfig'
90	103
91	104	KCONFIG_SEED
92		−--------------------------------------------------
	105	+------------
93	106	You can set this to the integer value used to seed the RNG, if you want
94	107	to somehow debug the behaviour of the kconfig parser/frontends.
95	108	If not set, the current time will be used.
96	109
97	110	KCONFIG_PROBABILITY
98		−--------------------------------------------------
	111	+-------------------
99	112	This variable can be used to skew the probabilities. This variable can
100	113	be unset or empty, or set to three different formats:
	114	+
	115	+ ======================= ================== =====================
101	116	KCONFIG_PROBABILITY y:n split y:m:n split
102		− -----------------------------------------------------------------
	117	+ ======================= ================== =====================
103	118	unset or empty 50 : 50 33 : 33 : 34
104	119	N N : 100-N N/2 : N/2 : 100-N
105	120	[1] N:M N+M : 100-(N+M) N : M : 100-(N+M)
106	121	[2] N:M:L N : 100-N M : L : 100-(M+L)
	122	+ ======================= ================== =====================
107	123
108	124	where N, M and L are integers (in base 10) in the range [0,100], and so
109	125	that:
	126	+
110	127	[1] N+M is in the range [0,100]
	128	+
111	129	[2] M+L is in the range [0,100]
112	130
113		−Examples:
	131	+Examples::
	132	+
114	133	KCONFIG_PROBABILITY=10
115	134	10% of booleans will be set to 'y', 90% to 'n'
116	135	5% of tristates will be set to 'y', 5% to 'm', 90% to 'n'
@@ -121,34 +140,36 @@ Examples: · 4 unmodified lines
121	140	10% of booleans will be set to 'y', 90% to 'n'
122	141	15% of tristates will be set to 'y', 15% to 'm', 70% to 'n'
123	142
124		−______________________________________________________________________
	143	+----------------------------------------------------------------------
	144	+
125	145	Environment variables for 'syncconfig'
126	146
127	147	KCONFIG_NOSILENTUPDATE
128		−--------------------------------------------------
	148	+----------------------
129	149	If this variable has a non-blank value, it prevents silent kernel
130	150	config updates (requires explicit updates).
131	151
132	152	KCONFIG_AUTOCONFIG
133		−--------------------------------------------------
	153	+------------------
134	154	This environment variable can be set to specify the path & name of the
135	155	"auto.conf" file. Its default value is "include/config/auto.conf".
136	156
137	157	KCONFIG_TRISTATE
138		−--------------------------------------------------
	158	+----------------
139	159	This environment variable can be set to specify the path & name of the
140	160	"tristate.conf" file. Its default value is "include/config/tristate.conf".
141	161
142	162	KCONFIG_AUTOHEADER
143		−--------------------------------------------------
	163	+------------------
144	164	This environment variable can be set to specify the path & name of the
145	165	"autoconf.h" (header) file.
146	166	Its default value is "include/generated/autoconf.h".
147	167
148	168
149		−======================================================================
	169	+----------------------------------------------------------------------
	170	+
150	171	menuconfig
151		−--------------------------------------------------
	172	+----------
152	173
153	174	SEARCHING for CONFIG symbols
154	175
@@ -158,7 +179,8 @@ Searching in menuconfig: · 3 unmodified lines
158	179	names, so you have to know something close to what you are
159	180	looking for.
160	181
161		− Example:
	182	+ Example::
	183	+
162	184	/hotplug
163	185	This lists all config symbols that contain "hotplug",
164	186	e.g., HOTPLUG_CPU, MEMORY_HOTPLUG.
@@ -166,48 +188,55 @@ Searching in menuconfig: · 1 unmodified line
166	188	For search help, enter / followed by TAB-TAB (to highlight
167	189	<Help>) and Enter. This will tell you that you can also use
168	190	regular expressions (regexes) in the search string, so if you
169		− are not interested in MEMORY_HOTPLUG, you could try
	191	+ are not interested in MEMORY_HOTPLUG, you could try::
170	192
171	193	/^hotplug
172	194
173	195	When searching, symbols are sorted thus:
	196	+
174	197	- first, exact matches, sorted alphabetically (an exact match
175	198	is when the search matches the complete symbol name);
176	199	- then, other matches, sorted alphabetically.
	200	+
177	201	For example: ^ATH.K matches:
	202	+
178	203	ATH5K ATH9K ATH5K_AHB ATH5K_DEBUG [...] ATH6KL ATH6KL_DEBUG
179	204	[...] ATH9K_AHB ATH9K_BTCOEX_SUPPORT ATH9K_COMMON [...]
	205	+
180	206	of which only ATH5K and ATH9K match exactly and so are sorted
181	207	first (and in alphabetical order), then come all other symbols,
182	208	sorted in alphabetical order.
183	209
184		−______________________________________________________________________
	210	+----------------------------------------------------------------------
	211	+
185	212	User interface options for 'menuconfig'
186	213
187	214	MENUCONFIG_COLOR
188		−--------------------------------------------------
	215	+----------------
189	216	It is possible to select different color themes using the variable
190		−MENUCONFIG_COLOR. To select a theme use:
	217	+MENUCONFIG_COLOR. To select a theme use::
191	218
192	219	make MENUCONFIG_COLOR=<theme> menuconfig
193	220
194		−Available themes are:
195		− mono => selects colors suitable for monochrome displays
196		− blackbg => selects a color scheme with black background
197		− classic => theme with blue background. The classic look
198		− bluetitle => a LCD friendly version of classic. (default)
	221	+Available themes are::
	222	+
	223	+ - mono => selects colors suitable for monochrome displays
	224	+ - blackbg => selects a color scheme with black background
	225	+ - classic => theme with blue background. The classic look
	226	+ - bluetitle => a LCD friendly version of classic. (default)
199	227
200	228	MENUCONFIG_MODE
201		−--------------------------------------------------
	229	+---------------
202	230	This mode shows all sub-menus in one large tree.
203	231
204		−Example:
	232	+Example::
	233	+
205	234	make MENUCONFIG_MODE=single_menu menuconfig
206	235
	236	+----------------------------------------------------------------------
207	237
208		−======================================================================
209	238	nconfig
210		−--------------------------------------------------
	239	+-------
211	240
212	241	nconfig is an alternate text-based configurator. It lists function
213	242	keys across the bottom of the terminal (window) that execute commands.
@@ -231,16 +260,16 @@ Searching in nconfig: · 17 unmodified lines
231	260	given string or regular expression (regex).
232	261
233	262	NCONFIG_MODE
234		−--------------------------------------------------
	263	+------------
235	264	This mode shows all sub-menus in one large tree.
236	265
237		−Example:
	266	+Example::
238	267	make NCONFIG_MODE=single_menu nconfig
239	268
	269	+----------------------------------------------------------------------
240	270
241		−======================================================================
242	271	xconfig
243		−--------------------------------------------------
	272	+-------
244	273
245	274	Searching in xconfig:
246	275
@@ -260,13 +289,12 @@ Searching in xconfig: · 13 unmodified lines
260	289	to return to the main menu.
261	290
262	291
263		−======================================================================
	292	+----------------------------------------------------------------------
	293	+
264	294	gconfig
265		−--------------------------------------------------
	295	+-------
266	296
267	297	Searching in gconfig:
268	298
269	299	There is no search command in gconfig. However, gconfig does
270	300	have several different viewing choices, modes, and options.
271		−
272		−###

Documentation/kbuild/makefiles.rstrenamed from Documentation/kbuild/makefiles.txt+335−195

@@ -1,8 +1,10 @@
	1	+======================
1	2	Linux Kernel Makefiles
	3	+======================
2	4
3	5	This document describes the Linux kernel Makefiles.
4	6
5		−=== Table of Contents
	7	+.. Table of Contents
6	8
7	9	=== 1 Overview
8	10	=== 2 Who does what
@@ -54,9 +56,10 @@ This document describes the Linux kernel Makefiles. · 45 unmodified lines
54	56	=== 10 Credits
55	57	=== 11 TODO
56	58
57		−=== 1 Overview
	59	+1 Overview
	60	+==========
58	61
59		−The Makefiles have five parts:
	62	+The Makefiles have five parts::
60	63
61	64	Makefile the top Makefile.
62	65	.config the kernel configuration file.
@@ -85,7 +88,8 @@ scripts/Makefile.* contains all the definitions/rules etc. that · 22 unmodified lines
85	88	are used to build the kernel based on the kbuild makefiles.
86	89
87	90
88		−=== 2 Who does what
	91	+2 Who does what
	92	+===============
89	93
90	94	People have four different relationships with the kernel Makefiles.
91	95
@@ -110,7 +114,8 @@ These people need to know about all aspects of the kernel Makefiles. · 18 unmodified lines
110	114	This document is aimed towards normal developers and arch developers.
111	115
112	116
113		−=== 3 The kbuild files
	117	+3 The kbuild files
	118	+==================
114	119
115	120	Most Makefiles within the kernel are kbuild Makefiles that use the
116	121	kbuild infrastructure. This chapter introduces the syntax used in the
@@ -122,7 +127,8 @@ file will be used. · 5 unmodified lines
122	127	Section 3.1 "Goal definitions" is a quick intro, further chapters provide
123	128	more details, with real examples.
124	129
125		−--- 3.1 Goal definitions
	130	+3.1 Goal definitions
	131	+--------------------
126	132
127	133	Goal definitions are the main part (heart) of the kbuild Makefile.
128	134	These lines define the files to be built, any special compilation
@@ -130,7 +136,8 @@ more details, with real examples. · 1 unmodified line
130	136
131	137	The most simple kbuild makefile contains one line:
132	138
133		− Example:
	139	+ Example::
	140	+
134	141	obj-y += foo.o
135	142
136	143	This tells kbuild that there is one object in that directory, named
@@ -139,14 +146,16 @@ more details, with real examples. · 2 unmodified lines
139	146	If foo.o shall be built as a module, the variable obj-m is used.
140	147	Therefore the following pattern is often used:
141	148
142		− Example:
	149	+ Example::
	150	+
143	151	obj-$(CONFIG_FOO) += foo.o
144	152
145	153	$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
146	154	If CONFIG_FOO is neither y nor m, then the file will not be compiled
147	155	nor linked.
148	156
149		−--- 3.2 Built-in object goals - obj-y
	157	+3.2 Built-in object goals - obj-y
	158	+---------------------------------
150	159
151	160	The kbuild Makefile specifies object files for vmlinux
152	161	in the $(obj-y) lists. These lists depend on the kernel
@@ -167,14 +176,16 @@ more details, with real examples. · 14 unmodified lines
167	176	order may e.g. change the order in which your SCSI
168	177	controllers are detected, and thus your disks are renumbered.
169	178
170		− Example:
	179	+ Example::
	180	+
171	181	#drivers/isdn/i4l/Makefile
172	182	# Makefile for the kernel ISDN subsystem and device drivers.
173	183	# Each configuration option enables a list of files.
174	184	obj-$(CONFIG_ISDN_I4L) += isdn.o
175	185	obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
176	186
177		−--- 3.3 Loadable module goals - obj-m
	187	+3.3 Loadable module goals - obj-m
	188	+---------------------------------
178	189
179	190	$(obj-m) specifies object files which are built as loadable
180	191	kernel modules.
@@ -183,7 +194,8 @@ more details, with real examples. · 2 unmodified lines
183	194	files. In the case of one source file, the kbuild makefile
184	195	simply adds the file to $(obj-m).
185	196
186		− Example:
	197	+ Example::
	198	+
187	199	#drivers/isdn/i4l/Makefile
188	200	obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
189	201
@@ -195,7 +207,8 @@ more details, with real examples. · 5 unmodified lines
195	207	module from, so you have to tell it by setting a $(<module_name>-y)
196	208	variable.
197	209
198		− Example:
	210	+ Example::
	211	+
199	212	#drivers/isdn/i4l/Makefile
200	213	obj-$(CONFIG_ISDN_I4L) += isdn.o
201	214	isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
@@ -205,10 +218,11 @@ more details, with real examples. · 3 unmodified lines
205	218	"$(LD) -r" on the list of these files to generate isdn.o.
206	219
207	220	Due to kbuild recognizing $(<module_name>-y) for composite objects,
208		− you can use the value of a CONFIG_ symbol to optionally include an
	221	+ you can use the value of a `CONFIG_` symbol to optionally include an
209	222	object file as part of a composite object.
210	223
211		− Example:
	224	+ Example::
	225	+
212	226	#fs/ext2/Makefile
213	227	obj-$(CONFIG_EXT2_FS) += ext2.o
214	228	ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \
@@ -225,12 +239,14 @@ more details, with real examples. · 10 unmodified lines
225	239	kbuild will build an ext2.o file for you out of the individual
226	240	parts and then link this into built-in.a, as you would expect.
227	241
228		−--- 3.4 Objects which export symbols
	242	+3.4 Objects which export symbols
	243	+--------------------------------
229	244
230	245	No special notation is required in the makefiles for
231	246	modules exporting symbols.
232	247
233		−--- 3.5 Library file goals - lib-y
	248	+3.5 Library file goals - lib-y
	249	+------------------------------
234	250
235	251	Objects listed with obj-* are used for modules, or
236	252	combined in a built-in.a for that specific directory.
@@ -247,18 +263,21 @@ more details, with real examples. · 10 unmodified lines
247	263	and to be part of a library. Therefore the same directory
248	264	may contain both a built-in.a and a lib.a file.
249	265
250		− Example:
	266	+ Example::
	267	+
251	268	#arch/x86/lib/Makefile
252	269	lib-y := delay.o
253	270
254	271	This will create a library lib.a based on delay.o. For kbuild to
255	272	actually recognize that there is a lib.a being built, the directory
256	273	shall be listed in libs-y.
	274	+
257	275	See also "6.4 List directories to visit when descending".
258	276
259		− Use of lib-y is normally restricted to lib/ and arch/*/lib.
	277	+ Use of lib-y is normally restricted to `lib/` and `arch/*/lib`.
260	278
261		−--- 3.6 Descending down in directories
	279	+3.6 Descending down in directories
	280	+----------------------------------
262	281
263	282	A Makefile is only responsible for building objects in its own
264	283	directory. Files in subdirectories should be taken care of by
@@ -270,7 +289,8 @@ more details, with real examples. · 5 unmodified lines
270	289	ext2 lives in a separate directory, and the Makefile present in fs/
271	290	tells kbuild to descend down using the following assignment.
272	291
273		− Example:
	292	+ Example::
	293	+
274	294	#fs/Makefile
275	295	obj-$(CONFIG_EXT2_FS) += ext2/
276	296
@@ -281,11 +301,12 @@ more details, with real examples. · 4 unmodified lines
281	301	the directory, it is the Makefile in the subdirectory that
282	302	specifies what is modular and what is built-in.
283	303
284		− It is good practice to use a CONFIG_ variable when assigning directory
	304	+ It is good practice to use a `CONFIG_` variable when assigning directory
285	305	names. This allows kbuild to totally skip the directory if the
286		− corresponding CONFIG_ option is neither 'y' nor 'm'.
	306	+ corresponding `CONFIG_` option is neither 'y' nor 'm'.
287	307
288		−--- 3.7 Compilation flags
	308	+3.7 Compilation flags
	309	+---------------------
289	310
290	311	ccflags-y, asflags-y and ldflags-y
291	312	These three flags apply only to the kbuild makefile in which they
@@ -297,7 +318,8 @@ more details, with real examples. · 5 unmodified lines
297	318
298	319	ccflags-y specifies options for compiling with $(CC).
299	320
300		− Example:
	321	+ Example::
	322	+
301	323	# drivers/acpi/acpica/Makefile
302	324	ccflags-y := -Os -D_LINUX -DBUILDING_ACPICA
303	325	ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT
@@ -308,13 +330,15 @@ more details, with real examples. · 4 unmodified lines
308	330
309	331	asflags-y specifies options for assembling with $(AS).
310	332
311		− Example:
	333	+ Example::
	334	+
312	335	#arch/sparc/kernel/Makefile
313	336	asflags-y := -ansi
314	337
315	338	ldflags-y specifies options for linking with $(LD).
316	339
317		− Example:
	340	+ Example::
	341	+
318	342	#arch/cris/boot/compressed/Makefile
319	343	ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds
320	344
@@ -325,18 +349,19 @@ more details, with real examples. · 4 unmodified lines
325	349	Options specified using subdir-* are added to the commandline before
326	350	the options specified using the non-subdir variants.
327	351
328		− Example:
	352	+ Example::
	353	+
329	354	subdir-ccflags-y := -Werror
330	355
331	356	CFLAGS_$@, AFLAGS_$@
332		−
333	357	CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
334	358	kbuild makefile.
335	359
336	360	$(CFLAGS_$@) specifies per-file options for $(CC). The $@
337	361	part has a literal value which specifies the file that it is for.
338	362
339		− Example:
	363	+ Example::
	364	+
340	365	# drivers/scsi/Makefile
341	366	CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF
342	367	CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \
@@ -347,24 +372,27 @@ more details, with real examples. · 4 unmodified lines
347	372	$(AFLAGS_$@) is a similar feature for source files in assembly
348	373	languages.
349	374
350		− Example:
	375	+ Example::
	376	+
351	377	# arch/arm/kernel/Makefile
352	378	AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET)
353	379	AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
354	380	AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt
355	381
356	382
357		−--- 3.9 Dependency tracking
	383	+3.9 Dependency tracking
	384	+-----------------------
358	385
359	386	Kbuild tracks dependencies on the following:
360		− 1) All prerequisite files (both .c and .h)
361		− 2) CONFIG_ options used in all prerequisite files
	387	+ 1) All prerequisite files (both `.c` and `.h`)
	388	+ 2) `CONFIG_` options used in all prerequisite files
362	389	3) Command-line used to compile target
363	390
364	391	Thus, if you change an option to $(CC) all affected files will
365	392	be re-compiled.
366	393
367		−--- 3.10 Special Rules
	394	+3.10 Special Rules
	395	+------------------
368	396
369	397	Special rules are used when the kbuild infrastructure does
370	398	not provide the required support. A typical example is
@@ -379,43 +407,47 @@ more details, with real examples. · 8 unmodified lines
379	407
380	408	Two variables are used when defining special rules:
381	409
382		− $(src)
383		− $(src) is a relative path which points to the directory
384		− where the Makefile is located. Always use $(src) when
385		− referring to files located in the src tree.
	410	+ $(src)
	411	+ $(src) is a relative path which points to the directory
	412	+ where the Makefile is located. Always use $(src) when
	413	+ referring to files located in the src tree.
	414	+
	415	+ $(obj)
	416	+ $(obj) is a relative path which points to the directory
	417	+ where the target is saved. Always use $(obj) when
	418	+ referring to generated files.
386	419
387		− $(obj)
388		− $(obj) is a relative path which points to the directory
389		− where the target is saved. Always use $(obj) when
390		− referring to generated files.
	420	+ Example::
391	421
392		− Example:
393	422	#drivers/scsi/Makefile
394	423	$(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
395	424	$(CPP) -DCHIP=810 - < $< \| ... $(src)/script_asm.pl
396	425
397		− This is a special rule, following the normal syntax
398		− required by make.
399		− The target file depends on two prerequisite files. References
400		− to the target file are prefixed with $(obj), references
401		− to prerequisites are referenced with $(src) (because they are not
402		− generated files).
403		−
404		− $(kecho)
405		− echoing information to user in a rule is often a good practice
406		− but when execution "make -s" one does not expect to see any output
407		− except for warnings/errors.
408		− To support this kbuild defines $(kecho) which will echo out the
409		− text following $(kecho) to stdout except if "make -s" is used.
410		−
411		− Example:
	426	+ This is a special rule, following the normal syntax
	427	+ required by make.
	428	+
	429	+ The target file depends on two prerequisite files. References
	430	+ to the target file are prefixed with $(obj), references
	431	+ to prerequisites are referenced with $(src) (because they are not
	432	+ generated files).
	433	+
	434	+ $(kecho)
	435	+ echoing information to user in a rule is often a good practice
	436	+ but when execution "make -s" one does not expect to see any output
	437	+ except for warnings/errors.
	438	+ To support this kbuild defines $(kecho) which will echo out the
	439	+ text following $(kecho) to stdout except if "make -s" is used.
	440	+
	441	+ Example::
	442	+
412	443	#arch/blackfin/boot/Makefile
413	444	$(obj)/vmImage: $(obj)/vmlinux.gz
414	445	$(call if_changed,uimage)
415	446	@$(kecho) 'Kernel: $@ is ready'
416	447
417	448
418		−--- 3.11 $(CC) support functions
	449	+3.11 $(CC) support functions
	450	+----------------------------
419	451
420	452	The kernel may be built with several different versions of
421	453	$(CC), each supporting a unique set of features and options.
@@ -425,10 +457,11 @@ more details, with real examples. · 3 unmodified lines
425	457
426	458	as-option
427	459	as-option is used to check if $(CC) -- when used to compile
428		− assembler (*.S) files -- supports the given option. An optional
	460	+ assembler (`*.S`) files -- supports the given option. An optional
429	461	second option may be specified if the first option is not supported.
430	462
431		− Example:
	463	+ Example::
	464	+
432	465	#arch/sh/Makefile
433	466	cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
434	467
@@ -437,6 +470,21 @@ more details, with real examples. · 2 unmodified lines
437	470	The second argument is optional, and if supplied will be used
438	471	if first argument is not supported.
439	472
	473	+ cc-ldoption
	474	+ cc-ldoption is used to check if $(CC) when used to link object files
	475	+ supports the given option. An optional second option may be
	476	+ specified if first option are not supported.
	477	+
	478	+ Example::
	479	+
	480	+ #arch/x86/kernel/Makefile
	481	+ vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)
	482	+
	483	+ In the above example, vsyscall-flags will be assigned the option
	484	+ -Wl$(comma)--hash-style=sysv if it is supported by $(CC).
	485	+ The second argument is optional, and if supplied will be used
	486	+ if first argument is not supported.
	487	+
440	488	as-instr
441	489	as-instr checks if the assembler reports a specific instruction
442	490	and then outputs either option1 or option2
@@ -447,7 +495,8 @@ more details, with real examples. · 4 unmodified lines
447	495	cc-option is used to check if $(CC) supports a given option, and if
448	496	not supported to use an optional second option.
449	497
450		− Example:
	498	+ Example::
	499	+
451	500	#arch/x86/Makefile
452	501	cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
453	502
@@ -461,7 +510,8 @@ more details, with real examples. · 7 unmodified lines
461	510	cc-option-yn is used to check if gcc supports a given option
462	511	and return 'y' if supported, otherwise 'n'.
463	512
464		− Example:
	513	+ Example::
	514	+
465	515	#arch/ppc/Makefile
466	516	biarch := $(call cc-option-yn, -m32)
467	517	aflags-$(biarch) += -a32
@@ -479,7 +529,8 @@ more details, with real examples. · 11 unmodified lines
479	529	because gcc 4.4 and later accept any unknown -Wno-* option and only
480	530	warn about it if there is another warning in the source file.
481	531
482		− Example:
	532	+ Example::
	533	+
483	534	KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)
484	535
485	536	In the above example, -Wno-unused-but-set-variable will be added to
@@ -490,7 +541,8 @@ more details, with real examples. · 4 unmodified lines
490	541	if version expression is true, or the fifth (if given) if the version
491	542	expression is false.
492	543
493		− Example:
	544	+ Example::
	545	+
494	546	#fs/reiserfs/Makefile
495	547	ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)
496	548
@@ -515,7 +567,8 @@ more details, with real examples. · 18 unmodified lines
515	567	build (host arch is different from target arch). And if CROSS_COMPILE
516	568	is already set then leave it with the old value.
517	569
518		− Example:
	570	+ Example::
	571	+
519	572	#arch/m68k/Makefile
520	573	ifneq ($(SUBARCH),$(ARCH))
521	574	ifeq ($(CROSS_COMPILE),)
@@ -523,7 +576,8 @@ more details, with real examples. · 1 unmodified line
523	576	endif
524	577	endif
525	578
526		−--- 3.12 $(LD) support functions
	579	+3.12 $(LD) support functions
	580	+----------------------------
527	581
528	582	ld-option
529	583	ld-option is used to check if $(LD) supports the supplied option.
@@ -531,12 +585,14 @@ more details, with real examples. · 1 unmodified line
531	585	The second argument is an optional option that can be used if the
532	586	first option is not supported by $(LD).
533	587
534		− Example:
	588	+ Example::
	589	+
535	590	#Makefile
536	591	LDFLAGS_vmlinux += $(call ld-option, -X)
537	592
538	593
539		−=== 4 Host Program support
	594	+4 Host Program support
	595	+======================
540	596
541	597	Kbuild supports building executables on the host for use during the
542	598	compilation stage.
@@ -550,21 +606,24 @@ This can be done in two ways. Either add the dependency in a rule, · 7 unmodified lines
550	606	or utilise the variable $(always).
551	607	Both possibilities are described in the following.
552	608
553		−--- 4.1 Simple Host Program
	609	+4.1 Simple Host Program
	610	+-----------------------
554	611
555	612	In some cases there is a need to compile and run a program on the
556	613	computer where the build is running.
557	614	The following line tells kbuild that the program bin2hex shall be
558	615	built on the build host.
559	616
560		− Example:
	617	+ Example::
	618	+
561	619	hostprogs-y := bin2hex
562	620
563	621	Kbuild assumes in the above example that bin2hex is made from a single
564	622	c-source file named bin2hex.c located in the same directory as
565	623	the Makefile.
566	624
567		−--- 4.2 Composite Host Programs
	625	+4.2 Composite Host Programs
	626	+---------------------------
568	627
569	628	Host programs can be made up based on composite objects.
570	629	The syntax used to define composite objects for host programs is
@@ -572,7 +631,8 @@ Both possibilities are described in the following. · 1 unmodified line
572	631	$(<executable>-objs) lists all objects used to link the final
573	632	executable.
574	633
575		− Example:
	634	+ Example::
	635	+
576	636	#scripts/lxdialog/Makefile
577	637	hostprogs-y := lxdialog
578	638	lxdialog-objs := checklist.o lxdialog.o
@@ -580,16 +640,19 @@ Both possibilities are described in the following. · 1 unmodified line
580	640	Objects with extension .o are compiled from the corresponding .c
581	641	files. In the above example, checklist.c is compiled to checklist.o
582	642	and lxdialog.c is compiled to lxdialog.o.
	643	+
583	644	Finally, the two .o files are linked to the executable, lxdialog.
584	645	Note: The syntax <executable>-y is not permitted for host-programs.
585	646
586		−--- 4.3 Using C++ for host programs
	647	+4.3 Using C++ for host programs
	648	+-------------------------------
587	649
588	650	kbuild offers support for host programs written in C++. This was
589	651	introduced solely to support kconfig, and is not recommended
590	652	for general use.
591	653
592		− Example:
	654	+ Example::
	655	+
593	656	#scripts/kconfig/Makefile
594	657	hostprogs-y := qconf
595	658	qconf-cxxobjs := qconf.o
@@ -600,13 +663,15 @@ Both possibilities are described in the following. · 4 unmodified lines
600	663	If qconf is composed of a mixture of .c and .cc files, then an
601	664	additional line can be used to identify this.
602	665
603		− Example:
	666	+ Example::
	667	+
604	668	#scripts/kconfig/Makefile
605	669	hostprogs-y := qconf
606	670	qconf-cxxobjs := qconf.o
607	671	qconf-objs := check.o
608	672
609		−--- 4.4 Controlling compiler options for host programs
	673	+4.4 Controlling compiler options for host programs
	674	+--------------------------------------------------
610	675
611	676	When compiling host programs, it is possible to set specific flags.
612	677	The programs will always be compiled utilising $(HOSTCC) passed
@@ -614,27 +679,31 @@ Both possibilities are described in the following. · 1 unmodified line
614	679	To set flags that will take effect for all host programs created
615	680	in that Makefile, use the variable HOST_EXTRACFLAGS.
616	681
617		− Example:
	682	+ Example::
	683	+
618	684	#scripts/lxdialog/Makefile
619	685	HOST_EXTRACFLAGS += -I/usr/include/ncurses
620	686
621	687	To set specific flags for a single file the following construction
622	688	is used:
623	689
624		− Example:
	690	+ Example::
	691	+
625	692	#arch/ppc64/boot/Makefile
626	693	HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
627	694
628	695	It is also possible to specify additional options to the linker.
629	696
630		− Example:
	697	+ Example::
	698	+
631	699	#scripts/kconfig/Makefile
632	700	HOSTLDLIBS_qconf := -L$(QTDIR)/lib
633	701
634	702	When linking qconf, it will be passed the extra option
635	703	"-L$(QTDIR)/lib".
636	704
637		−--- 4.5 When host programs are actually built
	705	+4.5 When host programs are actually built
	706	+-----------------------------------------
638	707
639	708	Kbuild will only build host-programs when they are referenced
640	709	as a prerequisite.
@@ -642,7 +711,8 @@ Both possibilities are described in the following. · 1 unmodified line
642	711
643	712	(1) List the prerequisite explicitly in a special rule.
644	713
645		− Example:
	714	+ Example::
	715	+
646	716	#drivers/pci/Makefile
647	717	hostprogs-y := gen-devlist
648	718	$(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
@@ -653,11 +723,13 @@ Both possibilities are described in the following. · 4 unmodified lines
653	723	the host programs in special rules must be prefixed with $(obj).
654	724
655	725	(2) Use $(always)
	726	+
656	727	When there is no suitable special rule, and the host program
657	728	shall be built when a makefile is entered, the $(always)
658	729	variable shall be used.
659	730
660		− Example:
	731	+ Example::
	732	+
661	733	#scripts/lxdialog/Makefile
662	734	hostprogs-y := lxdialog
663	735	always := $(hostprogs-y)
@@ -665,11 +737,13 @@ Both possibilities are described in the following. · 1 unmodified line
665	737	This will tell kbuild to build lxdialog even if not referenced in
666	738	any rule.
667	739
668		−--- 4.6 Using hostprogs-$(CONFIG_FOO)
	740	+4.6 Using hostprogs-$(CONFIG_FOO)
	741	+---------------------------------
669	742
670	743	A typical pattern in a Kbuild file looks like this:
671	744
672		− Example:
	745	+ Example::
	746	+
673	747	#scripts/Makefile
674	748	hostprogs-$(CONFIG_KALLSYMS) += kallsyms
675	749
@@ -679,7 +753,8 @@ Both possibilities are described in the following. · 3 unmodified lines
679	753	like hostprogs-y. But only hostprogs-y is recommended to be used
680	754	when no CONFIG symbols are involved.
681	755
682		−=== 5 Kbuild clean infrastructure
	756	+5 Kbuild clean infrastructure
	757	+=============================
683	758
684	759	"make clean" deletes most generated files in the obj tree where the kernel
685	760	is compiled. This includes generated files such as host programs.
@@ -691,7 +766,8 @@ generated by kbuild are deleted all over the kernel src tree when · 5 unmodified lines
691	766
692	767	Additional files can be specified in kbuild makefiles by use of $(clean-files).
693	768
694		− Example:
	769	+ Example::
	770	+
695	771	#lib/Makefile
696	772	clean-files := crc32table.h
697	773
@@ -701,7 +777,8 @@ Makefile, except if prefixed with $(objtree). · 3 unmodified lines
701	777
702	778	To delete a directory hierarchy use:
703	779
704		− Example:
	780	+ Example::
	781	+
705	782	#scripts/package/Makefile
706	783	clean-dirs := $(objtree)/debian/
707	784
@@ -711,7 +788,8 @@ subdirectories. · 3 unmodified lines
711	788	To exclude certain files from make clean, use the $(no-clean-files) variable.
712	789	This is only a special case used in the top level Kbuild file:
713	790
714		− Example:
	791	+ Example::
	792	+
715	793	#Kbuild
716	794	no-clean-files := $(bounds-file) $(offsets-file)
717	795
@@ -719,7 +797,8 @@ Usually kbuild descends down in subdirectories due to "obj-* := dir/", · 1 unmodified line
719	797	but in the architecture makefiles where the kbuild infrastructure
720	798	is not sufficient this sometimes needs to be explicit.
721	799
722		− Example:
	800	+ Example::
	801	+
723	802	#arch/x86/boot/Makefile
724	803	subdir- := compressed/
725	804
@@ -729,7 +808,8 @@ directory compressed/ when "make clean" is executed. · 3 unmodified lines
729	808	To support the clean infrastructure in the Makefiles that build the
730	809	final bootimage there is an optional target named archclean:
731	810
732		− Example:
	811	+ Example::
	812	+
733	813	#arch/x86/Makefile
734	814	archclean:
735	815	$(Q)$(MAKE) $(clean)=arch/x86/boot
@@ -745,7 +825,8 @@ is not operational at that point. · 9 unmodified lines
745	825	Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
746	826	be visited during "make clean".
747	827
748		−=== 6 Architecture Makefiles
	828	+6 Architecture Makefiles
	829	+========================
749	830
750	831	The top level Makefile sets up the environment and does the preparation,
751	832	before starting to descend down in the individual directories.
@@ -756,6 +837,7 @@ To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines · 4 unmodified lines
756	837	a few targets.
757	838
758	839	When kbuild executes, the following steps are followed (roughly):
	840	+
759	841	1) Configuration of the kernel => produce .config
760	842	2) Store kernel version in include/linux/version.h
761	843	3) Updating all other prerequisites to the target prepare:
@@ -773,37 +855,45 @@ When kbuild executes, the following steps are followed (roughly): · 11 unmodified lines
773	855	- Preparing initrd images and the like
774	856
775	857
776		−--- 6.1 Set variables to tweak the build to the architecture
	858	+6.1 Set variables to tweak the build to the architecture
	859	+--------------------------------------------------------
777	860
778		− LDFLAGS Generic $(LD) options
	861	+ LDFLAGS
	862	+ Generic $(LD) options
779	863
780	864	Flags used for all invocations of the linker.
781	865	Often specifying the emulation is sufficient.
782	866
783		− Example:
	867	+ Example::
	868	+
784	869	#arch/s390/Makefile
785	870	LDFLAGS := -m elf_s390
	871	+
786	872	Note: ldflags-y can be used to further customise
787	873	the flags used. See chapter 3.7.
788	874
789		− LDFLAGS_vmlinux Options for $(LD) when linking vmlinux
	875	+ LDFLAGS_vmlinux
	876	+ Options for $(LD) when linking vmlinux
790	877
791	878	LDFLAGS_vmlinux is used to specify additional flags to pass to
792	879	the linker when linking the final vmlinux image.
793	880	LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
794	881
795		− Example:
	882	+ Example::
	883	+
796	884	#arch/x86/Makefile
797	885	LDFLAGS_vmlinux := -e stext
798	886
799		− OBJCOPYFLAGS objcopy flags
	887	+ OBJCOPYFLAGS
	888	+ objcopy flags
800	889
801	890	When $(call if_changed,objcopy) is used to translate a .o file,
802	891	the flags specified in OBJCOPYFLAGS will be used.
803	892	$(call if_changed,objcopy) is often used to generate raw binaries on
804	893	vmlinux.
805	894
806		− Example:
	895	+ Example::
	896	+
807	897	#arch/s390/Makefile
808	898	OBJCOPYFLAGS := -O binary
809	899
@@ -814,30 +904,34 @@ When kbuild executes, the following steps are followed (roughly): · 4 unmodified lines
814	904	In this example, the binary $(obj)/image is a binary version of
815	905	vmlinux. The usage of $(call if_changed,xxx) will be described later.
816	906
817		− KBUILD_AFLAGS $(AS) assembler flags
	907	+ KBUILD_AFLAGS
	908	+ $(AS) assembler flags
818	909
819	910	Default value - see top level Makefile
820	911	Append or modify as required per architecture.
821	912
822		− Example:
	913	+ Example::
	914	+
823	915	#arch/sparc64/Makefile
824	916	KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
825	917
826		− KBUILD_CFLAGS $(CC) compiler flags
	918	+ KBUILD_CFLAGS
	919	+ $(CC) compiler flags
827	920
828	921	Default value - see top level Makefile
829	922	Append or modify as required per architecture.
830	923
831	924	Often, the KBUILD_CFLAGS variable depends on the configuration.
832	925
833		− Example:
	926	+ Example::
	927	+
834	928	#arch/x86/boot/compressed/Makefile
835	929	cflags-$(CONFIG_X86_32) := -march=i386
836	930	cflags-$(CONFIG_X86_64) := -mcmodel=small
837	931	KBUILD_CFLAGS += $(cflags-y)
838	932
839	933	Many arch Makefiles dynamically run the target C compiler to
840		− probe supported options:
	934	+ probe supported options::
841	935
842	936	#arch/x86/Makefile
843	937
@@ -853,32 +947,39 @@ When kbuild executes, the following steps are followed (roughly): · 9 unmodified lines
853	947	The first example utilises the trick that a config option expands
854	948	to 'y' when selected.
855	949
856		− KBUILD_AFLAGS_KERNEL $(AS) options specific for built-in
	950	+ KBUILD_AFLAGS_KERNEL
	951	+ $(AS) options specific for built-in
857	952
858	953	$(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
859	954	resident kernel code.
860	955
861		− KBUILD_AFLAGS_MODULE Options for $(AS) when building modules
	956	+ KBUILD_AFLAGS_MODULE
	957	+ Options for $(AS) when building modules
862	958
863	959	$(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that
864	960	are used for $(AS).
	961	+
865	962	From commandline AFLAGS_MODULE shall be used (see kbuild.txt).
866	963
867		− KBUILD_CFLAGS_KERNEL $(CC) options specific for built-in
	964	+ KBUILD_CFLAGS_KERNEL
	965	+ $(CC) options specific for built-in
868	966
869	967	$(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
870	968	resident kernel code.
871	969
872		− KBUILD_CFLAGS_MODULE Options for $(CC) when building modules
	970	+ KBUILD_CFLAGS_MODULE
	971	+ Options for $(CC) when building modules
873	972
874	973	$(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that
875	974	are used for $(CC).
876	975	From commandline CFLAGS_MODULE shall be used (see kbuild.txt).
877	976
878		− KBUILD_LDFLAGS_MODULE Options for $(LD) when linking modules
	977	+ KBUILD_LDFLAGS_MODULE
	978	+ Options for $(LD) when linking modules
879	979
880	980	$(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options
881	981	used when linking modules. This is often a linker script.
	982	+
882	983	From commandline LDFLAGS_MODULE shall be used (see kbuild.txt).
883	984
884	985	KBUILD_ARFLAGS Options for $(AR) when creating archives
@@ -894,7 +995,8 @@ When kbuild executes, the following steps are followed (roughly): · 9 unmodified lines
894	995	means for an architecture to override the defaults.
895	996
896	997
897		−--- 6.2 Add prerequisites to archheaders:
	998	+6.2 Add prerequisites to archheaders
	999	+------------------------------------
898	1000
899	1001	The archheaders: rule is used to generate header files that
900	1002	may be installed into user space by "make header_install" or
@@ -907,13 +1009,15 @@ When kbuild executes, the following steps are followed (roughly): · 6 unmodified lines
907	1009	architecture itself.
908	1010
909	1011
910		−--- 6.3 Add prerequisites to archprepare:
	1012	+6.3 Add prerequisites to archprepare
	1013	+------------------------------------
911	1014
912	1015	The archprepare: rule is used to list prerequisites that need to be
913	1016	built before starting to descend down in the subdirectories.
914	1017	This is usually used for header files containing assembler constants.
915	1018
916		− Example:
	1019	+ Example::
	1020	+
917	1021	#arch/arm/Makefile
918	1022	archprepare: maketools
919	1023
@@ -923,7 +1027,8 @@ When kbuild executes, the following steps are followed (roughly): · 3 unmodified lines
923	1027	generating offset header files.
924	1028
925	1029
926		−--- 6.4 List directories to visit when descending
	1030	+6.4 List directories to visit when descending
	1031	+---------------------------------------------
927	1032
928	1033	An arch Makefile cooperates with the top Makefile to define variables
929	1034	which specify how to build the vmlinux file. Note that there is no
@@ -931,28 +1036,34 @@ When kbuild executes, the following steps are followed (roughly): · 1 unmodified line
931	1036	machinery is all architecture-independent.
932	1037
933	1038
934		− head-y, init-y, core-y, libs-y, drivers-y, net-y
	1039	+ head-y, init-y, core-y, libs-y, drivers-y, net-y
	1040	+ $(head-y) lists objects to be linked first in vmlinux.
	1041	+
	1042	+ $(libs-y) lists directories where a lib.a archive can be located.
	1043	+
	1044	+ The rest list directories where a built-in.a object file can be
	1045	+ located.
935	1046
936		− $(head-y) lists objects to be linked first in vmlinux.
937		− $(libs-y) lists directories where a lib.a archive can be located.
938		− The rest list directories where a built-in.a object file can be
939		− located.
	1047	+ $(init-y) objects will be located after $(head-y).
940	1048
941		− $(init-y) objects will be located after $(head-y).
942		− Then the rest follows in this order:
943		− $(core-y), $(libs-y), $(drivers-y) and $(net-y).
	1049	+ Then the rest follows in this order:
944	1050
945		− The top level Makefile defines values for all generic directories,
946		− and arch/$(ARCH)/Makefile only adds architecture-specific directories.
	1051	+ $(core-y), $(libs-y), $(drivers-y) and $(net-y).
	1052	+
	1053	+ The top level Makefile defines values for all generic directories,
	1054	+ and arch/$(ARCH)/Makefile only adds architecture-specific
	1055	+ directories.
	1056	+
	1057	+ Example::
947	1058
948		− Example:
949	1059	#arch/sparc64/Makefile
950	1060	core-y += arch/sparc64/kernel/
951	1061	libs-y += arch/sparc64/prom/ arch/sparc64/lib/
952	1062	drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/
953	1063
954	1064
955		−--- 6.5 Architecture-specific boot images
	1065	+6.5 Architecture-specific boot images
	1066	+-------------------------------------
956	1067
957	1068	An arch Makefile specifies goals that take the vmlinux file, compress
958	1069	it, wrap it in bootstrapping code, and copy the resulting files
@@ -970,7 +1081,8 @@ When kbuild executes, the following steps are followed (roughly): · 11 unmodified lines
970	1081	arch/$(ARCH)/Makefile, and use the full path when calling down
971	1082	into the arch/$(ARCH)/boot/Makefile.
972	1083
973		− Example:
	1084	+ Example::
	1085	+
974	1086	#arch/x86/Makefile
975	1087	boot := arch/x86/boot
976	1088	bzImage: vmlinux
@@ -983,7 +1095,8 @@ When kbuild executes, the following steps are followed (roughly): · 6 unmodified lines
983	1095	but executing "make help" will list all relevant targets.
984	1096	To support this, $(archhelp) must be defined.
985	1097
986		− Example:
	1098	+ Example::
	1099	+
987	1100	#arch/x86/Makefile
988	1101	define archhelp
989	1102	echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)'
@@ -997,25 +1110,30 @@ When kbuild executes, the following steps are followed (roughly): · 7 unmodified lines
997	1110	Add a new prerequisite to all: to select a default goal different
998	1111	from vmlinux.
999	1112
1000		− Example:
	1113	+ Example::
	1114	+
1001	1115	#arch/x86/Makefile
1002	1116	all: bzImage
1003	1117
1004	1118	When "make" is executed without arguments, bzImage will be built.
1005	1119
1006		−--- 6.6 Building non-kbuild targets
	1120	+6.6 Building non-kbuild targets
	1121	+-------------------------------
1007	1122
1008	1123	extra-y
1009		−
1010	1124	extra-y specifies additional targets created in the current
1011		− directory, in addition to any targets specified by obj-*.
	1125	+ directory, in addition to any targets specified by `obj-*`.
1012	1126
1013	1127	Listing all targets in extra-y is required for two purposes:
	1128	+
1014	1129	1) Enable kbuild to check changes in command lines
	1130	+
1015	1131	- When $(call if_changed,xxx) is used
	1132	+
1016	1133	2) kbuild knows what files to delete during "make clean"
1017	1134
1018		− Example:
	1135	+ Example::
	1136	+
1019	1137	#arch/x86/kernel/Makefile
1020	1138	extra-y := head.o init_task.o
1021	1139
@@ -1023,16 +1141,17 @@ When kbuild executes, the following steps are followed (roughly): · 1 unmodified line
1023	1141	shall be built, but shall not be linked as part of built-in.a.
1024	1142
1025	1143
1026		−--- 6.7 Commands useful for building a boot image
	1144	+6.7 Commands useful for building a boot image
	1145	+---------------------------------------------
1027	1146
1028		− Kbuild provides a few macros that are useful when building a
1029		− boot image.
	1147	+ Kbuild provides a few macros that are useful when building a
	1148	+ boot image.
1030	1149
1031	1150	if_changed
1032		−
1033	1151	if_changed is the infrastructure used for the following commands.
1034	1152
1035		− Usage:
	1153	+ Usage::
	1154	+
1036	1155	target: source(s) FORCE
1037	1156	$(call if_changed,ld/objcopy/gzip/...)
1038	1157
@@ -1050,12 +1169,16 @@ When kbuild executes, the following steps are followed (roughly): · 11 unmodified lines
1050	1169	Note: It is a typical mistake to forget the FORCE prerequisite.
1051	1170	Another common pitfall is that whitespace is sometimes
1052	1171	significant; for instance, the below will fail (note the extra space
1053		− after the comma):
	1172	+ after the comma)::
	1173	+
1054	1174	target: source(s) FORCE
1055		− #WRONG!# $(call if_changed, ld/objcopy/gzip/...)
1056	1175
1057		− Note: if_changed should not be used more than once per target.
	1176	+ WRONG! $(call if_changed, ld/objcopy/gzip/...)
	1177	+
	1178	+ Note:
	1179	+ if_changed should not be used more than once per target.
1058	1180	It stores the executed command in a corresponding .cmd
	1181	+
1059	1182	file and multiple calls would result in overwrites and
1060	1183	unwanted results when the target is up to date and only the
1061	1184	tests on changed commands trigger execution of commands.
@@ -1063,7 +1186,8 @@ When kbuild executes, the following steps are followed (roughly): · 1 unmodified line
1063	1186	ld
1064	1187	Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
1065	1188
1066		− Example:
	1189	+ Example::
	1190	+
1067	1191	#arch/x86/boot/Makefile
1068	1192	LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
1069	1193	LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext
@@ -1077,12 +1201,15 @@ When kbuild executes, the following steps are followed (roughly): · 7 unmodified lines
1077	1201	LDFLAGS_$@ syntax - one for each potential target.
1078	1202	$(targets) are assigned all potential targets, by which kbuild knows
1079	1203	the targets and will:
	1204	+
1080	1205	1) check for commandline changes
1081	1206	2) delete target during make clean
1082	1207
1083	1208	The ": %: %.o" part of the prerequisite is a shorthand that
1084	1209	frees us from listing the setup.o and bootsect.o files.
1085		− Note: It is a common mistake to forget the "targets :=" assignment,
	1210	+
	1211	+ Note:
	1212	+ It is a common mistake to forget the "targets :=" assignment,
1086	1213	resulting in the target file being recompiled for no
1087	1214	obvious reason.
1088	1215
@@ -1094,7 +1221,8 @@ When kbuild executes, the following steps are followed (roughly): · 5 unmodified lines
1094	1221	gzip
1095	1222	Compress target. Use maximum compression to compress target.
1096	1223
1097		− Example:
	1224	+ Example::
	1225	+
1098	1226	#arch/x86/boot/compressed/Makefile
1099	1227	$(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE
1100	1228	$(call if_changed,gzip)
@@ -1105,26 +1233,30 @@ When kbuild executes, the following steps are followed (roughly): · 4 unmodified lines
1105	1233	in an init section in the image. Platform code must copy the
1106	1234	blob to non-init memory prior to calling unflatten_device_tree().
1107	1235
1108		− To use this command, simply add *.dtb into obj-y or targets, or make
1109		− some other target depend on %.dtb
	1236	+ To use this command, simply add `*.dtb` into obj-y or targets, or make
	1237	+ some other target depend on `%.dtb`
1110	1238
1111		− A central rule exists to create $(obj)/%.dtb from $(src)/%.dts;
	1239	+ A central rule exists to create `$(obj)/%.dtb` from `$(src)/%.dts`;
1112	1240	architecture Makefiles do no need to explicitly write out that rule.
1113	1241
1114		− Example:
	1242	+ Example::
	1243	+
1115	1244	targets += $(dtb-y)
1116	1245	DTC_FLAGS ?= -p 1024
1117	1246
1118		−--- 6.8 Custom kbuild commands
	1247	+6.8 Custom kbuild commands
	1248	+--------------------------
1119	1249
1120	1250	When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
1121	1251	of a command is normally displayed.
1122	1252	To enable this behaviour for custom commands kbuild requires
1123		− two variables to be set:
1124		− quiet_cmd_<command> - what shall be echoed
1125		− cmd_<command> - the command to execute
	1253	+ two variables to be set::
	1254	+
	1255	+ quiet_cmd_<command> - what shall be echoed
	1256	+ cmd_<command> - the command to execute
	1257	+
	1258	+ Example::
1126	1259
1127		− Example:
1128	1260	#
1129	1261	quiet_cmd_image = BUILD $@
1130	1262	cmd_image = $(obj)/tools/build $(BUILDFLAGS) \
@@ -1135,9 +1267,9 @@ When kbuild executes, the following steps are followed (roughly): · 4 unmodified lines
1135	1267	$(call if_changed,image)
1136	1268	@echo 'Kernel: $@ is ready'
1137	1269
1138		− When updating the $(obj)/bzImage target, the line
	1270	+ When updating the $(obj)/bzImage target, the line:
1139	1271
1140		− BUILD arch/x86/boot/bzImage
	1272	+ BUILD arch/x86/boot/bzImage
1141	1273
1142	1274	will be displayed with "make KBUILD_VERBOSE=0".
1143	1275
@@ -1148,9 +1280,10 @@ When kbuild executes, the following steps are followed (roughly): · 4 unmodified lines
1148	1280	arch/$(ARCH)/kernel/vmlinux.lds is used.
1149	1281	The script is a preprocessed variant of the file vmlinux.lds.S
1150	1282	located in the same directory.
1151		− kbuild knows .lds files and includes a rule lds.S -> lds.
	1283	+ kbuild knows .lds files and includes a rule `lds.S` -> `lds`.
	1284	+
	1285	+ Example::
1152	1286
1153		− Example:
1154	1287	#arch/x86/kernel/Makefile
1155	1288	always := vmlinux.lds
1156	1289
@@ -1162,17 +1295,19 @@ When kbuild executes, the following steps are followed (roughly): · 5 unmodified lines
1162	1295	The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
1163	1296	specified options when building the target vmlinux.lds.
1164	1297
1165		− When building the *.lds target, kbuild uses the variables:
1166		− KBUILD_CPPFLAGS : Set in top-level Makefile
1167		− cppflags-y : May be set in the kbuild makefile
1168		− CPPFLAGS_$(@F) : Target-specific flags.
1169		− Note that the full filename is used in this
1170		− assignment.
	1298	+ When building the `*.lds` target, kbuild uses the variables::
	1299	+
	1300	+ KBUILD_CPPFLAGS : Set in top-level Makefile
	1301	+ cppflags-y : May be set in the kbuild makefile
	1302	+ CPPFLAGS_$(@F) : Target-specific flags.
	1303	+ Note that the full filename is used in this
	1304	+ assignment.
1171	1305
1172		− The kbuild infrastructure for *lds files is used in several
	1306	+ The kbuild infrastructure for `*lds` files is used in several
1173	1307	architecture-specific files.
1174	1308
1175		−--- 6.10 Generic header files
	1309	+6.10 Generic header files
	1310	+-------------------------
1176	1311
1177	1312	The directory include/asm-generic contains the header files
1178	1313	that may be shared between individual architectures.
@@ -1180,7 +1315,8 @@ When kbuild executes, the following steps are followed (roughly): · 1 unmodified line
1180	1315	to list the file in the Kbuild file.
1181	1316	See "7.2 generic-y" for further info on syntax etc.
1182	1317
1183		−--- 6.11 Post-link pass
	1318	+6.11 Post-link pass
	1319	+-------------------
1184	1320
1185	1321	If the file arch/xxx/Makefile.postlink exists, this makefile
1186	1322	will be invoked for post-link objects (vmlinux and modules.ko)
@@ -1195,15 +1331,17 @@ When kbuild executes, the following steps are followed (roughly): · 8 unmodified lines
1195	1331	For example, powerpc uses this to check relocation sanity of
1196	1332	the linked vmlinux file.
1197	1333
1198		−=== 7 Kbuild syntax for exported headers
	1334	+7 Kbuild syntax for exported headers
	1335	+------------------------------------
1199	1336
1200	1337	The kernel includes a set of headers that is exported to userspace.
1201	1338	Many headers can be exported as-is but other headers require a
1202	1339	minimal pre-processing before they are ready for user-space.
1203	1340	The pre-processing does:
	1341	+
1204	1342	- drop kernel-specific annotations
1205	1343	- drop include of compiler.h
1206		−- drop all sections that are kernel internal (guarded by ifdef __KERNEL__)
	1344	+- drop all sections that are kernel internal (guarded by `ifdef __KERNEL__`)
1207	1345
1208	1346	All headers under include/uapi/, include/generated/uapi/,
1209	1347	arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/
@@ -1213,40 +1351,45 @@ A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and · 3 unmodified lines
1213	1351	arch/<arch>/include/asm/ to list asm files coming from asm-generic.
1214	1352	See subsequent chapter for the syntax of the Kbuild file.
1215	1353
1216		−--- 7.1 no-export-headers
	1354	+7.1 no-export-headers
	1355	+---------------------
1217	1356
1218	1357	no-export-headers is essentially used by include/uapi/linux/Kbuild to
1219	1358	avoid exporting specific headers (e.g. kvm.h) on architectures that do
1220	1359	not support it. It should be avoided as much as possible.
1221	1360
1222		−--- 7.2 generic-y
	1361	+7.2 generic-y
	1362	+-------------
1223	1363
1224	1364	If an architecture uses a verbatim copy of a header from
1225	1365	include/asm-generic then this is listed in the file
1226	1366	arch/$(ARCH)/include/asm/Kbuild like this:
1227	1367
1228		− Example:
	1368	+ Example::
	1369	+
1229	1370	#arch/x86/include/asm/Kbuild
1230	1371	generic-y += termios.h
1231	1372	generic-y += rtc.h
1232	1373
1233	1374	During the prepare phase of the build a wrapper include
1234		− file is generated in the directory:
	1375	+ file is generated in the directory::
1235	1376
1236	1377	arch/$(ARCH)/include/generated/asm
1237	1378
1238	1379	When a header is exported where the architecture uses
1239	1380	the generic header a similar wrapper is generated as part
1240		− of the set of exported headers in the directory:
	1381	+ of the set of exported headers in the directory::
1241	1382
1242	1383	usr/include/asm
1243	1384
1244	1385	The generated wrapper will in both cases look like the following:
1245	1386
1246		− Example: termios.h
	1387	+ Example: termios.h::
	1388	+
1247	1389	#include <asm-generic/termios.h>
1248	1390
1249		−--- 7.3 generated-y
	1391	+7.3 generated-y
	1392	+---------------
1250	1393
1251	1394	If an architecture generates other header files alongside generic-y
1252	1395	wrappers, generated-y specifies them.
@@ -1254,11 +1397,13 @@ See subsequent chapter for the syntax of the Kbuild file. · 1 unmodified line
1254	1397	This prevents them being treated as stale asm-generic wrappers and
1255	1398	removed.
1256	1399
1257		− Example:
	1400	+ Example::
	1401	+
1258	1402	#arch/x86/include/asm/Kbuild
1259	1403	generated-y += syscalls_32.h
1260	1404
1261		−--- 7.4 mandatory-y
	1405	+7.4 mandatory-y
	1406	+---------------
1262	1407
1263	1408	mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild
1264	1409	to define the minimum set of ASM headers that all architectures must have.
@@ -1270,12 +1415,12 @@ See subsequent chapter for the syntax of the Kbuild file. · 5 unmodified lines
1270	1415	The convention is to list one subdir per line and
1271	1416	preferably in alphabetic order.
1272	1417
1273		−=== 8 Kbuild Variables
	1418	+8 Kbuild Variables
	1419	+==================
1274	1420
1275	1421	The top Makefile exports the following variables:
1276	1422
1277	1423	VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
1278		−
1279	1424	These variables define the current kernel version. A few arch
1280	1425	Makefiles actually use these values directly; they should use
1281	1426	$(KERNELRELEASE) instead.
@@ -1289,32 +1434,28 @@ The top Makefile exports the following variables: · 7 unmodified lines
1289	1434	such as "-pre4", and is often blank.
1290	1435
1291	1436	KERNELRELEASE
1292		−
1293	1437	$(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
1294	1438	for constructing installation directory names or showing in
1295	1439	version strings. Some arch Makefiles use it for this purpose.
1296	1440
1297	1441	ARCH
1298		−
1299	1442	This variable defines the target architecture, such as "i386",
1300	1443	"arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
1301	1444	determine which files to compile.
1302	1445
1303	1446	By default, the top Makefile sets $(ARCH) to be the same as the
1304	1447	host system architecture. For a cross build, a user may
1305		− override the value of $(ARCH) on the command line:
	1448	+ override the value of $(ARCH) on the command line::
1306	1449
1307	1450	make ARCH=m68k ...
1308	1451
1309	1452
1310	1453	INSTALL_PATH
1311		−
1312	1454	This variable defines a place for the arch Makefiles to install
1313	1455	the resident kernel image and System.map file.
1314	1456	Use this for architecture-specific install targets.
1315	1457
1316	1458	INSTALL_MOD_PATH, MODLIB
1317		−
1318	1459	$(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
1319	1460	installation. This variable is not defined in the Makefile but
1320	1461	may be passed in by the user if desired.
@@ -1325,7 +1466,6 @@ The top Makefile exports the following variables: · 4 unmodified lines
1325	1466	override this value on the command line if desired.
1326	1467
1327	1468	INSTALL_MOD_STRIP
1328		−
1329	1469	If this variable is specified, it will cause modules to be stripped
1330	1470	after they are installed. If INSTALL_MOD_STRIP is '1', then the
1331	1471	default option --strip-debug will be used. Otherwise, the
@@ -1333,7 +1473,8 @@ The top Makefile exports the following variables: · 1 unmodified line
1333	1473	command.
1334	1474
1335	1475
1336		−=== 9 Makefile language
	1476	+9 Makefile language
	1477	+===================
1337	1478
1338	1479	The kernel Makefiles are designed to be run with GNU Make. The Makefiles
1339	1480	use only the documented features of GNU Make, but they do use many
@@ -1352,18 +1493,17 @@ time the left-hand side is used. · 12 unmodified lines
1352	1493	There are some cases where "=" is appropriate. Usually, though, ":="
1353	1494	is the right choice.
1354	1495
1355		−=== 10 Credits
	1496	+10 Credits
	1497	+==========
1356	1498
1357		−Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
1358		−Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
1359		−Updates by Sam Ravnborg <sam@ravnborg.org>
1360		−Language QA by Jan Engelhardt <jengelh@gmx.de>
	1499	+- Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
	1500	+- Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
	1501	+- Updates by Sam Ravnborg <sam@ravnborg.org>
	1502	+- Language QA by Jan Engelhardt <jengelh@gmx.de>
1361	1503
1362		−=== 11 TODO
	1504	+11 TODO
	1505	+=======
1363	1506
1364	1507	- Describe how kbuild supports shipped files with _shipped.
1365	1508	- Generating offset header files.
1366	1509	- Add more variables to section 7?
1367		−
1368		−
1369		−

Documentation/kbuild/modules.rstrenamed from Documentation/kbuild/modules.txt+100−70

@@ -1,8 +1,10 @@
	1	+=========================
1	2	Building External Modules
	3	+=========================
2	4
3	5	This document describes how to build an out-of-tree kernel module.
4	6
5		−=== Table of Contents
	7	+.. Table of Contents
6	8
7	9	=== 1 Introduction
8	10	=== 2 How to Build External Modules
@@ -31,7 +33,8 @@ This document describes how to build an out-of-tree kernel module. · 22 unmodified lines
31	33
32	34
33	35
34		−=== 1. Introduction
	36	+1. Introduction
	37	+===============
35	38
36	39	"kbuild" is the build system used by the Linux kernel. Modules must use
37	40	kbuild to stay compatible with changes in the build infrastructure and
@@ -48,7 +51,8 @@ easily accomplished, and a complete example will be presented in · 10 unmodified lines
48	51	section 3.
49	52
50	53
51		−=== 2. How to Build External Modules
	54	+2. How to Build External Modules
	55	+================================
52	56
53	57	To build external modules, you must have a prebuilt kernel available
54	58	that contains the configuration and header files used in the build.
@@ -65,25 +69,27 @@ NOTE: "modules_prepare" will not build Module.symvers even if · 10 unmodified lines
65	69	CONFIG_MODVERSIONS is set; therefore, a full kernel build needs to be
66	70	executed to make module versioning work.
67	71
68		−--- 2.1 Command Syntax
	72	+2.1 Command Syntax
	73	+==================
69	74
70		− The command to build an external module is:
	75	+ The command to build an external module is::
71	76
72	77	$ make -C <path_to_kernel_src> M=$PWD
73	78
74	79	The kbuild system knows that an external module is being built
75	80	due to the "M=<dir>" option given in the command.
76	81
77		− To build against the running kernel use:
	82	+ To build against the running kernel use::
78	83
79	84	$ make -C /lib/modules/`uname -r`/build M=$PWD
80	85
81	86	Then to install the module(s) just built, add the target
82		− "modules_install" to the command:
	87	+ "modules_install" to the command::
83	88
84	89	$ make -C /lib/modules/`uname -r`/build M=$PWD modules_install
85	90
86		−--- 2.2 Options
	91	+2.2 Options
	92	+===========
87	93
88	94	($KDIR refers to the path of the kernel source directory.)
89	95
@@ -100,7 +106,8 @@ executed to make module versioning work. · 10 unmodified lines
100	106	directory where the external module (kbuild file) is
101	107	located.
102	108
103		−--- 2.3 Targets
	109	+2.3 Targets
	110	+===========
104	111
105	112	When building an external module, only a subset of the "make"
106	113	targets are available.
@@ -130,26 +137,29 @@ executed to make module versioning work. · 23 unmodified lines
130	137	help
131	138	List the available targets for external modules.
132	139
133		−--- 2.4 Building Separate Files
	140	+2.4 Building Separate Files
	141	+===========================
134	142
135	143	It is possible to build single files that are part of a module.
136	144	This works equally well for the kernel, a module, and even for
137	145	external modules.
138	146
139		− Example (The module foo.ko, consist of bar.o and baz.o):
	147	+ Example (The module foo.ko, consist of bar.o and baz.o)::
	148	+
140	149	make -C $KDIR M=$PWD bar.lst
141	150	make -C $KDIR M=$PWD baz.o
142	151	make -C $KDIR M=$PWD foo.ko
143	152	make -C $KDIR M=$PWD ./
144	153
145	154
146		−=== 3. Creating a Kbuild File for an External Module
	155	+3. Creating a Kbuild File for an External Module
	156	+================================================
147	157
148	158	In the last section we saw the command to build a module for the
149	159	running kernel. The module is not actually built, however, because a
150	160	build file is required. Contained in this file will be the name of
151	161	the module(s) being built, along with the list of requisite source
152		−files. The file may be as simple as a single line:
	162	+files. The file may be as simple as a single line::
153	163
154	164	obj-m := <module_name>.o
155	165
@@ -157,15 +167,15 @@ The kbuild system will build <module_name>.o from <module_name>.c, · 1 unmodified line
157	167	and, after linking, will result in the kernel module <module_name>.ko.
158	168	The above line can be put in either a "Kbuild" file or a "Makefile."
159	169	When the module is built from multiple sources, an additional line is
160		−needed listing the files:
	170	+needed listing the files::
161	171
162	172	<module_name>-y := <src1>.o <src2>.o ...
163	173
164	174	NOTE: Further documentation describing the syntax used by kbuild is
165		−located in Documentation/kbuild/makefiles.txt.
	175	+located in Documentation/kbuild/makefiles.rst.
166	176
167	177	The examples below demonstrate how to create a build file for the
168		−module 8123.ko, which is built from the following files:
	178	+module 8123.ko, which is built from the following files::
169	179
170	180	8123_if.c
171	181	8123_if.h
@@ -181,7 +191,8 @@ module 8123.ko, which is built from the following files: · 9 unmodified lines
181	191	but should be filtered out from kbuild due to possible name
182	192	clashes.
183	193
184		− Example 1:
	194	+ Example 1::
	195	+
185	196	--> filename: Makefile
186	197	ifneq ($(KERNELRELEASE),)
187	198	# kbuild part of makefile
@@ -209,14 +220,16 @@ module 8123.ko, which is built from the following files: · 21 unmodified lines
209	220	line; the second pass is by the kbuild system, which is
210	221	initiated by the parameterized "make" in the default target.
211	222
212		−--- 3.2 Separate Kbuild File and Makefile
	223	+3.2 Separate Kbuild File and Makefile
	224	+-------------------------------------
213	225
214	226	In newer versions of the kernel, kbuild will first look for a
215	227	file named "Kbuild," and only if that is not found, will it
216	228	then look for a makefile. Utilizing a "Kbuild" file allows us
217	229	to split up the makefile from example 1 into two files:
218	230
219		− Example 2:
	231	+ Example 2::
	232	+
220	233	--> filename: Kbuild
221	234	obj-m := 8123.o
222	235	8123-y := 8123_if.o 8123_pci.o 8123_bin.o
@@ -238,7 +251,8 @@ module 8123.ko, which is built from the following files: · 15 unmodified lines
238	251
239	252	The next example shows a backward compatible version.
240	253
241		− Example 3:
	254	+ Example 3::
	255	+
242	256	--> filename: Kbuild
243	257	obj-m := 8123.o
244	258	8123-y := 8123_if.o 8123_pci.o 8123_bin.o
@@ -266,7 +280,8 @@ module 8123.ko, which is built from the following files: · 21 unmodified lines
266	280	makefiles, to be used when the "make" and kbuild parts are
267	281	split into separate files.
268	282
269		−--- 3.3 Binary Blobs
	283	+3.3 Binary Blobs
	284	+----------------
270	285
271	286	Some external modules need to include an object file as a blob.
272	287	kbuild has support for this, but requires the blob file to be
@@ -277,7 +292,7 @@ module 8123.ko, which is built from the following files: · 4 unmodified lines
277	292
278	293	Throughout this section, 8123_bin.o_shipped has been used to
279	294	build the kernel module 8123.ko; it has been included as
280		− 8123_bin.o.
	295	+ 8123_bin.o::
281	296
282	297	8123-y := 8123_if.o 8123_pci.o 8123_bin.o
283	298
@@ -285,11 +300,12 @@ module 8123.ko, which is built from the following files: · 1 unmodified line
285	300	files and the binary file, kbuild will pick up different rules
286	301	when creating the object file for the module.
287	302
288		−--- 3.4 Building Multiple Modules
	303	+3.4 Building Multiple Modules
	304	+=============================
289	305
290	306	kbuild supports building multiple modules with a single build
291	307	file. For example, if you wanted to build two modules, foo.ko
292		− and bar.ko, the kbuild lines would be:
	308	+ and bar.ko, the kbuild lines would be::
293	309
294	310	obj-m := foo.o bar.o
295	311	foo-y := <foo_srcs>
@@ -298,7 +314,8 @@ module 8123.ko, which is built from the following files: · 2 unmodified lines
298	314	It is that simple!
299	315
300	316
301		−=== 4. Include Files
	317	+4. Include Files
	318	+================
302	319
303	320	Within the kernel, header files are kept in standard locations
304	321	according to the following rule:
@@ -310,22 +327,25 @@ according to the following rule: · 5 unmodified lines
310	327	of the kernel that are located in different directories, then
311	328	the file is placed in include/linux/.
312	329
313		− NOTE: There are two notable exceptions to this rule: larger
314		− subsystems have their own directory under include/, such as
315		− include/scsi; and architecture specific headers are located
316		− under arch/$(ARCH)/include/.
	330	+ NOTE:
	331	+ There are two notable exceptions to this rule: larger
	332	+ subsystems have their own directory under include/, such as
	333	+ include/scsi; and architecture specific headers are located
	334	+ under arch/$(ARCH)/include/.
317	335
318		−--- 4.1 Kernel Includes
	336	+4.1 Kernel Includes
	337	+-------------------
319	338
320	339	To include a header file located under include/linux/, simply
321		− use:
	340	+ use::
322	341
323	342	#include <linux/module.h>
324	343
325	344	kbuild will add options to "gcc" so the relevant directories
326	345	are searched.
327	346
328		−--- 4.2 Single Subdirectory
	347	+4.2 Single Subdirectory
	348	+-----------------------
329	349
330	350	External modules tend to place header files in a separate
331	351	include/ directory where their source is located, although this
@@ -334,7 +354,7 @@ according to the following rule: · 2 unmodified lines
334	354
335	355	Using the example from section 3, if we moved 8123_if.h to a
336	356	subdirectory named include, the resulting kbuild file would
337		− look like:
	357	+ look like::
338	358
339	359	--> filename: Kbuild
340	360	obj-m := 8123.o
@@ -346,23 +366,24 @@ according to the following rule: · 5 unmodified lines
346	366	the path. This is a limitation of kbuild: there must be no
347	367	space present.
348	368
349		−--- 4.3 Several Subdirectories
	369	+4.3 Several Subdirectories
	370	+--------------------------
350	371
351	372	kbuild can handle files that are spread over several directories.
352		− Consider the following example:
353		−
354		− .
355		− \|__ src
356		− \| \|__ complex_main.c
357		− \| \|__ hal
358		− \| \|__ hardwareif.c
359		− \| \|__ include
360		− \| \|__ hardwareif.h
361		− \|__ include
362		− \|__ complex.h
	373	+ Consider the following example::
	374	+
	375	+ .
	376	+ \|__ src
	377	+ \| \|__ complex_main.c
	378	+ \| \|__ hal
	379	+ \| \|__ hardwareif.c
	380	+ \| \|__ include
	381	+ \| \|__ hardwareif.h
	382	+ \|__ include
	383	+ \|__ complex.h
363	384
364	385	To build the module complex.ko, we then need the following
365		− kbuild file:
	386	+ kbuild file::
366	387
367	388	--> filename: Kbuild
368	389	obj-m := complex.o
@@ -385,7 +406,8 @@ according to the following rule: · 16 unmodified lines
385	406	file is located.
386	407
387	408
388		−=== 5. Module Installation
	409	+5. Module Installation
	410	+======================
389	411
390	412	Modules which are included in the kernel are installed in the
391	413	directory:
@@ -396,11 +418,12 @@ And external modules are installed in: · 4 unmodified lines
396	418
397	419	/lib/modules/$(KERNELRELEASE)/extra/
398	420
399		−--- 5.1 INSTALL_MOD_PATH
	421	+5.1 INSTALL_MOD_PATH
	422	+--------------------
400	423
401	424	Above are the default directories but as always some level of
402	425	customization is possible. A prefix can be added to the
403		− installation path using the variable INSTALL_MOD_PATH:
	426	+ installation path using the variable INSTALL_MOD_PATH::
404	427
405	428	$ make INSTALL_MOD_PATH=/frodo modules_install
406	429	=> Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/
@@ -410,20 +433,22 @@ And external modules are installed in: · 3 unmodified lines
410	433	calling "make." This has effect when installing both in-tree
411	434	and out-of-tree modules.
412	435
413		−--- 5.2 INSTALL_MOD_DIR
	436	+5.2 INSTALL_MOD_DIR
	437	+-------------------
414	438
415	439	External modules are by default installed to a directory under
416	440	/lib/modules/$(KERNELRELEASE)/extra/, but you may wish to
417	441	locate modules for a specific functionality in a separate
418	442	directory. For this purpose, use INSTALL_MOD_DIR to specify an
419		− alternative name to "extra."
	443	+ alternative name to "extra."::
420	444
421	445	$ make INSTALL_MOD_DIR=gandalf -C $KDIR \
422	446	M=$PWD modules_install
423	447	=> Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/
424	448
425	449
426		−=== 6. Module Versioning
	450	+6. Module Versioning
	451	+====================
427	452
428	453	Module versioning is enabled by the CONFIG_MODVERSIONS tag, and is used
429	454	as a simple ABI consistency check. A CRC value of the full prototype
@@ -435,14 +460,16 @@ module. · 5 unmodified lines
435	460	Module.symvers contains a list of all exported symbols from a kernel
436	461	build.
437	462
438		−--- 6.1 Symbols From the Kernel (vmlinux + modules)
	463	+6.1 Symbols From the Kernel (vmlinux + modules)
	464	+-----------------------------------------------
439	465
440	466	During a kernel build, a file named Module.symvers will be
441	467	generated. Module.symvers contains all exported symbols from
442	468	the kernel and compiled modules. For each symbol, the
443	469	corresponding CRC value is also stored.
444	470
445		− The syntax of the Module.symvers file is:
	471	+ The syntax of the Module.symvers file is::
	472	+
446	473	<CRC> <Symbol> <module>
447	474
448	475	0x2d036834 scsi_remove_host drivers/scsi/scsi_mod
@@ -451,10 +478,12 @@ build. · 2 unmodified lines
451	478	would read 0x00000000.
452	479
453	480	Module.symvers serves two purposes:
	481	+
454	482	1) It lists all exported symbols from vmlinux and all modules.
455	483	2) It lists the CRC if CONFIG_MODVERSIONS is enabled.
456	484
457		−--- 6.2 Symbols and External Modules
	485	+6.2 Symbols and External Modules
	486	+--------------------------------
458	487
459	488	When building an external module, the build system needs access
460	489	to the symbols from the kernel to check if all external symbols
@@ -481,17 +510,17 @@ build. · 20 unmodified lines
481	510	foo.ko needs symbols from bar.ko, you can use a
482	511	common top-level kbuild file so both modules are
483	512	compiled in the same build. Consider the following
484		− directory layout:
	513	+ directory layout::
485	514
486		− ./foo/ <= contains foo.ko
487		− ./bar/ <= contains bar.ko
	515	+ ./foo/ <= contains foo.ko
	516	+ ./bar/ <= contains bar.ko
488	517
489		− The top-level kbuild file would then look like:
	518	+ The top-level kbuild file would then look like::
490	519
491		− #./Kbuild (or ./Makefile):
492		− obj-y := foo/ bar/
	520	+ #./Kbuild (or ./Makefile):
	521	+ obj-y := foo/ bar/
493	522
494		− And executing
	523	+ And executing::
495	524
496	525	$ make -C $KDIR M=$PWD
497	526
@@ -518,14 +547,16 @@ build. · 20 unmodified lines
518	547	initialization of its symbol tables.
519	548
520	549
521		−=== 7. Tips & Tricks
	550	+7. Tips & Tricks
	551	+================
522	552
523		−--- 7.1 Testing for CONFIG_FOO_BAR
	553	+7.1 Testing for CONFIG_FOO_BAR
	554	+------------------------------
524	555
525		− Modules often need to check for certain CONFIG_ options to
	556	+ Modules often need to check for certain `CONFIG_` options to
526	557	decide if a specific feature is included in the module. In
527		− kbuild this is done by referencing the CONFIG_ variable
528		− directly.
	558	+ kbuild this is done by referencing the `CONFIG_` variable
	559	+ directly::
529	560
530	561	#fs/ext2/Makefile
531	562	obj-$(CONFIG_EXT2_FS) += ext2.o
@@ -534,8 +565,7 @@ build. · 2 unmodified lines
534	565	ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o
535	566
536	567	External modules have traditionally used "grep" to check for
537		− specific CONFIG_ settings directly in .config. This usage is
	568	+ specific `CONFIG_` settings directly in .config. This usage is
538	569	broken. As introduced before, external modules should use
539	570	kbuild for building and can therefore use the same methods as
540		− in-tree modules when testing for CONFIG_ definitions.
541		−
	571	+ in-tree modules when testing for `CONFIG_` definitions.

Documentation/kernel-hacking/hacking.rst+2−2

@@ -718,7 +718,7 @@ make a neat patch, there's administrative work to be done: · 717 unmodified lines
718	718	- Usually you want a configuration option for your kernel hack. Edit
719	719	``Kconfig`` in the appropriate directory. The Config language is
720	720	simple to use by cut and paste, and there's complete documentation in
721		− ``Documentation/kbuild/kconfig-language.txt``.
	721	+ ``Documentation/kbuild/kconfig-language.rst``.
722	722
723	723	In your description of the option, make sure you address both the
724	724	expert user and the user who knows nothing about your feature.
@@ -728,7 +728,7 @@ make a neat patch, there's administrative work to be done: · 3 unmodified lines
728	728
729	729	- Edit the ``Makefile``: the CONFIG variables are exported here so you
730	730	can usually just add a "obj-$(CONFIG_xxx) += xxx.o" line. The syntax
731		− is documented in ``Documentation/kbuild/makefiles.txt``.
	731	+ is documented in ``Documentation/kbuild/makefiles.rst``.
732	732
733	733	- Put yourself in ``CREDITS`` if you've done something noteworthy,
734	734	usually beyond a single file (your name should be at the top of the

Documentation/process/coding-style.rst+1−1

@@ -686,7 +686,7 @@ filesystems) should advertise this prominently in their prompt string:: · 685 unmodified lines
686	686	...
687	687
688	688	For full documentation on the configuration files, see the file
689		−Documentation/kbuild/kconfig-language.txt.
	689	+Documentation/kbuild/kconfig-language.rst.
690	690
691	691
692	692	11) Data structures

Documentation/process/submit-checklist.rst+1−1

@@ -39,7 +39,7 @@ and elsewhere regarding submitting Linux kernel patches. · 38 unmodified lines
39	39
40	40	6) Any new or modified ``CONFIG`` options do not muck up the config menu and
41	41	default to off unless they meet the exception criteria documented in
42		− ``Documentation/kbuild/kconfig-language.txt`` Menu attributes: default value.
	42	+ ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value.
43	43
44	44	7) All new ``Kconfig`` options have help text.
45	45

Documentation/translations/it_IT/kernel-hacking/hacking.rst+2−2

@@ -755,7 +755,7 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare: · 754 unmodified lines
755	755	- Solitamente vorrete un'opzione di configurazione per la vostra modifica
756	756	al kernel. Modificate ``Kconfig`` nella cartella giusta. Il linguaggio
757	757	Config è facile con copia ed incolla, e c'è una completa documentazione
758		− nel file ``Documentation/kbuild/kconfig-language.txt``.
	758	+ nel file ``Documentation/kbuild/kconfig-language.rst``.
759	759
760	760	Nella descrizione della vostra opzione, assicuratevi di parlare sia agli
761	761	utenti esperti sia agli utente che non sanno nulla del vostro lavoro.
@@ -767,7 +767,7 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare: · 5 unmodified lines
767	767	- Modificate il file ``Makefile``: le variabili CONFIG sono esportate qui,
768	768	quindi potete solitamente aggiungere una riga come la seguete
769	769	"obj-$(CONFIG_xxx) += xxx.o". La sintassi è documentata nel file
770		− ``Documentation/kbuild/makefiles.txt``.
	770	+ ``Documentation/kbuild/makefiles.rst``.
771	771
772	772	- Aggiungete voi stessi in ``CREDITS`` se avete fatto qualcosa di notevole,
773	773	solitamente qualcosa che supera il singolo file (comunque il vostro nome

Documentation/translations/it_IT/process/coding-style.rst+1−1

@@ -696,7 +696,7 @@ nella stringa di titolo:: · 695 unmodified lines
696	696	...
697	697
698	698	Per la documentazione completa sui file di configurazione, consultate
699		−il documento Documentation/kbuild/kconfig-language.txt
	699	+il documento Documentation/kbuild/kconfig-language.rst
700	700
701	701
702	702	11) Strutture dati

Documentation/translations/it_IT/process/submit-checklist.rst+1−1

@@ -43,7 +43,7 @@ sottomissione delle patch, in particolare · 42 unmodified lines
43	43
44	44	6) Le opzioni ``CONFIG``, nuove o modificate, non scombussolano il menu
45	45	di configurazione e sono preimpostate come disabilitate a meno che non
46		− soddisfino i criteri descritti in ``Documentation/kbuild/kconfig-language.txt``
	46	+ soddisfino i criteri descritti in ``Documentation/kbuild/kconfig-language.rst``
47	47	alla punto "Voci di menu: valori predefiniti".
48	48
49	49	7) Tutte le nuove opzioni ``Kconfig`` hanno un messaggio di aiuto.

Documentation/translations/zh_CN/process/coding-style.rst+1−1

@@ -599,7 +599,7 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 · 598 unmodified lines
599	599	depends on ADFS_FS
600	600	...
601	601
602		−要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.txt。
	602	+要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.rst。
603	603
604	604
605	605	11) 数据结构

Documentation/translations/zh_CN/process/submit-checklist.rst+1−1

@@ -38,7 +38,7 @@ Linux内核补丁提交清单 · 37 unmodified lines
38	38	违规行为。
39	39
40	40	6) 任何新的或修改过的 ``CONFIG`` 选项都不会弄脏配置菜单，并默认为关闭，除非
41		− 它们符合 ``Documentation/kbuild/kconfig-language.txt`` 中记录的异常条件,
	41	+ 它们符合 ``Documentation/kbuild/kconfig-language.rst`` 中记录的异常条件,
42	42	菜单属性：默认值.
43	43
44	44	7) 所有新的 ``kconfig`` 选项都有帮助文本。

Kconfig+1−1

@@ -1,7 +1,7 @@
1	1	# SPDX-License-Identifier: GPL-2.0
2	2	#
3	3	# For a description of the syntax of this configuration file,
4		−# see Documentation/kbuild/kconfig-language.txt.
	4	+# see Documentation/kbuild/kconfig-language.rst.
5	5	#
6	6	mainmenu "Linux/$(ARCH) $(KERNELVERSION) Kernel Configuration"
7	7

arch/arc/plat-eznps/Kconfig+1−1

@@ -1,7 +1,7 @@
1	1	# SPDX-License-Identifier: GPL-2.0
2	2	#
3	3	# For a description of the syntax of this configuration file,
4		−# see Documentation/kbuild/kconfig-language.txt.
	4	+# see Documentation/kbuild/kconfig-language.rst.
5	5	#
6	6
7	7	menuconfig ARC_PLAT_EZNPS

arch/c6x/Kconfig+1−1

@@ -1,7 +1,7 @@
1	1	# SPDX-License-Identifier: GPL-2.0
2	2	#
3	3	# For a description of the syntax of this configuration file,
4		−# see Documentation/kbuild/kconfig-language.txt.
	4	+# see Documentation/kbuild/kconfig-language.rst.
5	5	#
6	6
7	7	config C6X

arch/microblaze/Kconfig.debug+1−1

@@ -1,6 +1,6 @@
1	1	# SPDX-License-Identifier: GPL-2.0-only
2	2	# For a description of the syntax of this configuration file,
3		−# see Documentation/kbuild/kconfig-language.txt.
	3	+# see Documentation/kbuild/kconfig-language.rst.
4	4
5	5	config TRACE_IRQFLAGS_SUPPORT
6	6	def_bool y

arch/microblaze/Kconfig.platform+1−1

@@ -1,6 +1,6 @@
1	1	# SPDX-License-Identifier: GPL-2.0-only
2	2	# For a description of the syntax of this configuration file,
3		−# see Documentation/kbuild/kconfig-language.txt.
	3	+# see Documentation/kbuild/kconfig-language.rst.
4	4	#
5	5	# Platform selection Kconfig menu for MicroBlaze targets
6	6	#

arch/nds32/Kconfig+1−1

@@ -1,7 +1,7 @@
1	1	# SPDX-License-Identifier: GPL-2.0-only
2	2	#
3	3	# For a description of the syntax of this configuration file,
4		−# see Documentation/kbuild/kconfig-language.txt.
	4	+# see Documentation/kbuild/kconfig-language.rst.
5	5	#
6	6
7	7	config NDS32

arch/openrisc/Kconfig+1−1

@@ -1,7 +1,7 @@
1	1	# SPDX-License-Identifier: GPL-2.0
2	2	#
3	3	# For a description of the syntax of this configuration file,
4		−# see Documentation/kbuild/kconfig-language.txt.
	4	+# see Documentation/kbuild/kconfig-language.rst.
5	5	#
6	6
7	7	config OPENRISC

arch/powerpc/sysdev/Kconfig+1−1

@@ -1,6 +1,6 @@
1	1	# SPDX-License-Identifier: GPL-2.0
2	2	# For a description of the syntax of this configuration file,
3		−# see Documentation/kbuild/kconfig-language.txt.
	3	+# see Documentation/kbuild/kconfig-language.rst.
4	4	#
5	5
6	6	config PPC4xx_PCI_EXPRESS

arch/riscv/Kconfig+1−1

@@ -1,7 +1,7 @@
1	1	# SPDX-License-Identifier: GPL-2.0-only
2	2	#
3	3	# For a description of the syntax of this configuration file,
4		−# see Documentation/kbuild/kconfig-language.txt.
	4	+# see Documentation/kbuild/kconfig-language.rst.
5	5	#
6	6
7	7	config 64BIT

drivers/auxdisplay/Kconfig+1−1

@@ -1,7 +1,7 @@
1	1	# SPDX-License-Identifier: GPL-2.0
2	2	#
3	3	# For a description of the syntax of this configuration file,
4		−# see Documentation/kbuild/kconfig-language.txt.
	4	+# see Documentation/kbuild/kconfig-language.rst.
5	5	#
6	6	# Auxiliary display drivers configuration.
7	7	#

drivers/firmware/Kconfig+1−1

@@ -1,7 +1,7 @@
1	1	# SPDX-License-Identifier: GPL-2.0-only
2	2	#
3	3	# For a description of the syntax of this configuration file,
4		−# see Documentation/kbuild/kconfig-language.txt.
	4	+# see Documentation/kbuild/kconfig-language.rst.
5	5	#
6	6
7	7	menu "Firmware Drivers"

drivers/mtd/devices/Kconfig+1−1

@@ -48,7 +48,7 @@ config MTD_MS02NV · 47 unmodified lines
48	48
49	49	If you want to compile this driver as a module ( = code which can be
50	50	inserted in and removed from the running kernel whenever you want),
51		− say M here and read <file:Documentation/kbuild/modules.txt>.
	51	+ say M here and read <file:Documentation/kbuild/modules.rst>.
52	52	The module will be called ms02-nv.
53	53
54	54	config MTD_DATAFLASH

drivers/net/ethernet/smsc/Kconfig+3−3

@@ -49,7 +49,7 @@ config SMC91X · 48 unmodified lines
49	49	This driver is also available as a module ( = code which can be
50	50	inserted in and removed from the running kernel whenever you want).
51	51	The module will be called smc91x. If you want to compile it as a
52		− module, say M here and read <file:Documentation/kbuild/modules.txt>.
	52	+ module, say M here and read <file:Documentation/kbuild/modules.rst>.
53	53
54	54	config PCMCIA_SMC91C92
55	55	tristate "SMC 91Cxx PCMCIA support"
@@ -86,7 +86,7 @@ config SMC911X · 30 unmodified lines
86	86
87	87	This driver is also available as a module. The module will be
88	88	called smc911x. If you want to compile it as a module, say M
89		− here and read <file:Documentation/kbuild/modules.txt>
	89	+ here and read <file:Documentation/kbuild/modules.rst>
90	90
91	91	config SMSC911X
92	92	tristate "SMSC LAN911x/LAN921x families embedded ethernet support"
@@ -121,6 +121,6 @@ config SMSC9420 · 28 unmodified lines
121	121
122	122	This driver is also available as a module. The module will be
123	123	called smsc9420. If you want to compile it as a module, say M
124		− here and read <file:Documentation/kbuild/modules.txt>
	124	+ here and read <file:Documentation/kbuild/modules.rst>
125	125
126	126	endif # NET_VENDOR_SMSC

drivers/net/wireless/intel/iwlegacy/Kconfig+2−2

@@ -32,7 +32,7 @@ config IWL4965 · 31 unmodified lines
32	32
33	33	If you want to compile the driver as a module ( = code which can be
34	34	inserted in and removed from the running kernel whenever you want),
35		− say M here and read <file:Documentation/kbuild/modules.txt>. The
	35	+ say M here and read <file:Documentation/kbuild/modules.rst>. The
36	36	module will be called iwl4965.
37	37
38	38	config IWL3945
@@ -58,7 +58,7 @@ config IWL3945 · 19 unmodified lines
58	58
59	59	If you want to compile the driver as a module ( = code which can be
60	60	inserted in and removed from the running kernel whenever you want),
61		− say M here and read <file:Documentation/kbuild/modules.txt>. The
	61	+ say M here and read <file:Documentation/kbuild/modules.rst>. The
62	62	module will be called iwl3945.
63	63
64	64	menu "iwl3945 / iwl4965 Debugging Options"

drivers/net/wireless/intel/iwlwifi/Kconfig+1−1

@@ -40,7 +40,7 @@ config IWLWIFI · 39 unmodified lines
40	40
41	41	If you want to compile the driver as a module ( = code which can be
42	42	inserted in and removed from the running kernel whenever you want),
43		− say M here and read <file:Documentation/kbuild/modules.txt>. The
	43	+ say M here and read <file:Documentation/kbuild/modules.rst>. The
44	44	module will be called iwlwifi.
45	45
46	46	if IWLWIFI

drivers/parport/Kconfig+1−1

@@ -1,7 +1,7 @@
1	1	# SPDX-License-Identifier: GPL-2.0-only
2	2	#
3	3	# For a description of the syntax of this configuration file,
4		−# see Documentation/kbuild/kconfig-language.txt.
	4	+# see Documentation/kbuild/kconfig-language.rst.
5	5	#
6	6	# Parport configuration.
7	7	#

drivers/scsi/Kconfig+2−2

@@ -183,7 +183,7 @@ config CHR_DEV_SCH · 182 unmodified lines
183	183
184	184	If you want to compile this as a module ( = code which can be
185	185	inserted in and removed from the running kernel whenever you want),
186		− say M here and read <file:Documentation/kbuild/modules.txt> and
	186	+ say M here and read <file:Documentation/kbuild/modules.rst> and
187	187	<file:Documentation/scsi/scsi.txt>. The module will be called ch.o.
188	188	If unsure, say N.
189	189
@@ -1474,7 +1474,7 @@ config ZFCP · 1284 unmodified lines
1474	1474
1475	1475	This driver is also available as a module. This module will be
1476	1476	called zfcp. If you want to compile it as a module, say M here
1477		− and read <file:Documentation/kbuild/modules.txt>.
	1477	+ and read <file:Documentation/kbuild/modules.rst>.
1478	1478
1479	1479	config SCSI_PMCRAID
1480	1480	tristate "PMC SIERRA Linux MaxRAID adapter support"

drivers/staging/sm750fb/Kconfig+1−1

@@ -12,4 +12,4 @@ config FB_SM750 · 11 unmodified lines
12	12
13	13	This driver is also available as a module. The module will be
14	14	called sm750fb. If you want to compile it as a module, say M
15		− here and read <file:Documentation/kbuild/modules.txt>.
	15	+ here and read <file:Documentation/kbuild/modules.rst>.

drivers/usb/misc/Kconfig+2−2

@@ -16,7 +16,7 @@ config USB_EMI62 · 15 unmodified lines
16	16	This code is also available as a module ( = code which can be
17	17	inserted in and removed from the running kernel whenever you want).
18	18	The module will be called audio. If you want to compile it as a
19		− module, say M here and read <file:Documentation/kbuild/modules.txt>.
	19	+ module, say M here and read <file:Documentation/kbuild/modules.rst>.
20	20
21	21	config USB_EMI26
22	22	tristate "EMI 2\|6 USB Audio interface support"
@@ -67,7 +67,7 @@ config USB_LEGOTOWER · 44 unmodified lines
67	67	inserted in and removed from the running kernel whenever you want).
68	68	The module will be called legousbtower. If you want to compile it as
69	69	a module, say M here and read
70		− <file:Documentation/kbuild/modules.txt>.
	70	+ <file:Documentation/kbuild/modules.rst>.
71	71
72	72	config USB_LCD
73	73	tristate "USB LCD driver support"

drivers/video/fbdev/Kconfig+7−7

@@ -289,7 +289,7 @@ config FB_ARMCLCD · 288 unmodified lines
289	289
290	290	If you want to compile this as a module (=code which can be
291	291	inserted into and removed from the running kernel), say M
292		− here and read <file:Documentation/kbuild/modules.txt>. The module
	292	+ here and read <file:Documentation/kbuild/modules.rst>. The module
293	293	will be called amba-clcd.
294	294
295	295	config FB_ACORN
@@ -1752,7 +1752,7 @@ config FB_PXA · 1456 unmodified lines
1752	1752	This driver is also available as a module ( = code which can be
1753	1753	inserted and removed from the running kernel whenever you want). The
1754	1754	module will be called pxafb. If you want to compile it as a module,
1755		− say M here and read <file:Documentation/kbuild/modules.txt>.
	1755	+ say M here and read <file:Documentation/kbuild/modules.rst>.
1756	1756
1757	1757	If unsure, say N.
1758	1758
@@ -1833,7 +1833,7 @@ config FB_W100 · 74 unmodified lines
1833	1833	This driver is also available as a module ( = code which can be
1834	1834	inserted and removed from the running kernel whenever you want). The
1835	1835	module will be called w100fb. If you want to compile it as a module,
1836		− say M here and read <file:Documentation/kbuild/modules.txt>.
	1836	+ say M here and read <file:Documentation/kbuild/modules.rst>.
1837	1837
1838	1838	If unsure, say N.
1839	1839
@@ -1862,7 +1862,7 @@ config FB_TMIO · 22 unmodified lines
1862	1862	This driver is also available as a module ( = code which can be
1863	1863	inserted and removed from the running kernel whenever you want). The
1864	1864	module will be called tmiofb. If you want to compile it as a module,
1865		− say M here and read <file:Documentation/kbuild/modules.txt>.
	1865	+ say M here and read <file:Documentation/kbuild/modules.rst>.
1866	1866
1867	1867	If unsure, say N.
1868	1868
@@ -1908,7 +1908,7 @@ config FB_S3C2410 · 39 unmodified lines
1908	1908	This driver is also available as a module ( = code which can be
1909	1909	inserted and removed from the running kernel whenever you want). The
1910	1910	module will be called s3c2410fb. If you want to compile it as a module,
1911		− say M here and read <file:Documentation/kbuild/modules.txt>.
	1911	+ say M here and read <file:Documentation/kbuild/modules.rst>.
1912	1912
1913	1913	If unsure, say N.
1914	1914	config FB_S3C2410_DEBUG
@@ -1945,7 +1945,7 @@ config FB_SM501 · 30 unmodified lines
1945	1945	This driver is also available as a module ( = code which can be
1946	1946	inserted and removed from the running kernel whenever you want). The
1947	1947	module will be called sm501fb. If you want to compile it as a module,
1948		− say M here and read <file:Documentation/kbuild/modules.txt>.
	1948	+ say M here and read <file:Documentation/kbuild/modules.rst>.
1949	1949
1950	1950	If unsure, say N.
1951	1951
@@ -2288,7 +2288,7 @@ config FB_SM712 · 336 unmodified lines
2288	2288
2289	2289	This driver is also available as a module. The module will be
2290	2290	called sm712fb. If you want to compile it as a module, say M
2291		− here and read <file:Documentation/kbuild/modules.txt>.
	2291	+ here and read <file:Documentation/kbuild/modules.rst>.
2292	2292
2293	2293	source "drivers/video/fbdev/omap/Kconfig"
2294	2294	source "drivers/video/fbdev/omap2/Kconfig"

net/bridge/netfilter/Kconfig+1−1

@@ -114,7 +114,7 @@ config BRIDGE_EBT_LIMIT · 113 unmodified lines
114	114	equivalent of the iptables limit match.
115	115
116	116	If you want to compile it as a module, say M here and read
117		− <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
	117	+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
118	118
119	119	config BRIDGE_EBT_MARK
120	120	tristate "ebt: mark filter support"

net/ipv4/netfilter/Kconfig+1−1

@@ -308,7 +308,7 @@ config IP_NF_RAW · 307 unmodified lines
308	308	and OUTPUT chains.
309	309
310	310	If you want to compile it as a module, say M here and read
311		− <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
	311	+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
312	312
313	313	# security table for MAC policy
314	314	config IP_NF_SECURITY

net/ipv6/netfilter/Kconfig+1−1

@@ -241,7 +241,7 @@ config IP6_NF_RAW · 240 unmodified lines
241	241	and OUTPUT chains.
242	242
243	243	If you want to compile it as a module, say M here and read
244		− <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
	244	+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
245	245
246	246	# security table for MAC policy
247	247	config IP6_NF_SECURITY

net/netfilter/Kconfig+8−8

@@ -1056,7 +1056,7 @@ config NETFILTER_XT_TARGET_TRACE · 1055 unmodified lines
1056	1056	the tables, chains, rules.
1057	1057
1058	1058	If you want to compile it as a module, say M here and read
1059		− <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
	1059	+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
1060	1060
1061	1061	config NETFILTER_XT_TARGET_SECMARK
1062	1062	tristate '"SECMARK" target support'
@@ -1115,7 +1115,7 @@ config NETFILTER_XT_MATCH_ADDRTYPE · 52 unmodified lines
1115	1115	eg. UNICAST, LOCAL, BROADCAST, ...
1116	1116
1117	1117	If you want to compile it as a module, say M here and read
1118		− <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
	1118	+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
1119	1119
1120	1120	config NETFILTER_XT_MATCH_BPF
1121	1121	tristate '"bpf" match support'
@@ -1160,7 +1160,7 @@ config NETFILTER_XT_MATCH_COMMENT · 38 unmodified lines
1160	1160	comments in your iptables ruleset.
1161	1161
1162	1162	If you want to compile it as a module, say M here and read
1163		− <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
	1163	+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
1164	1164
1165	1165	config NETFILTER_XT_MATCH_CONNBYTES
1166	1166	tristate '"connbytes" per-connection counter match support'
@@ -1171,7 +1171,7 @@ config NETFILTER_XT_MATCH_CONNBYTES · 4 unmodified lines
1171	1171	number of bytes and/or packets for each direction within a connection.
1172	1172
1173	1173	If you want to compile it as a module, say M here and read
1174		− <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
	1174	+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
1175	1175
1176	1176	config NETFILTER_XT_MATCH_CONNLABEL
1177	1177	tristate '"connlabel" match support'
@@ -1237,7 +1237,7 @@ config NETFILTER_XT_MATCH_DCCP · 59 unmodified lines
1237	1237	and DCCP flags.
1238	1238
1239	1239	If you want to compile it as a module, say M here and read
1240		− <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
	1240	+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
1241	1241
1242	1242	config NETFILTER_XT_MATCH_DEVGROUP
1243	1243	tristate '"devgroup" match support'
@@ -1473,7 +1473,7 @@ config NETFILTER_XT_MATCH_QUOTA · 229 unmodified lines
1473	1473	byte counter.
1474	1474
1475	1475	If you want to compile it as a module, say M here and read
1476		− <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
	1476	+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
1477	1477
1478	1478	config NETFILTER_XT_MATCH_RATEEST
1479	1479	tristate '"rateest" match support'
@@ -1497,7 +1497,7 @@ config NETFILTER_XT_MATCH_REALM · 17 unmodified lines
1497	1497	in tc world.
1498	1498
1499	1499	If you want to compile it as a module, say M here and read
1500		− <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
	1500	+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
1501	1501
1502	1502	config NETFILTER_XT_MATCH_RECENT
1503	1503	tristate '"recent" match support'
@@ -1519,7 +1519,7 @@ config NETFILTER_XT_MATCH_SCTP · 15 unmodified lines
1519	1519	and SCTP chunk types.
1520	1520
1521	1521	If you want to compile it as a module, say M here and read
1522		− <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
	1522	+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
1523	1523
1524	1524	config NETFILTER_XT_MATCH_SOCKET
1525	1525	tristate '"socket" match support'

net/tipc/Kconfig+1−1

@@ -17,7 +17,7 @@ menuconfig TIPC · 16 unmodified lines
17	17	This protocol support is also available as a module ( = code which
18	18	can be inserted in and removed from the running kernel whenever you
19	19	want). The module will be called tipc. If you want to compile it
20		− as a module, say M here and read <file:Documentation/kbuild/modules.txt>.
	20	+ as a module, say M here and read <file:Documentation/kbuild/modules.rst>.
21	21
22	22	If in doubt, say N.
23	23

scripts/Kbuild.include+2−2

@@ -68,7 +68,7 @@ endef · 67 unmodified lines
68	68
69	69	######
70	70	# gcc support functions
71		−# See documentation in Documentation/kbuild/makefiles.txt
	71	+# See documentation in Documentation/kbuild/makefiles.rst
72	72
73	73	# cc-cross-prefix
74	74	# Usage: CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu- m68k-linux-)
@@ -210,7 +210,7 @@ objectify = $(foreach o,$(1),$(if $(filter /%,$(o)),$(o),$(obj)/$(o))) · 135 unmodified lines
210	210	# if_changed_dep - as if_changed, but uses fixdep to reveal dependencies
211	211	# including used config symbols
212	212	# if_changed_rule - as if_changed but execute rule instead
213		−# See Documentation/kbuild/makefiles.txt for more info
	213	+# See Documentation/kbuild/makefiles.rst for more info
214	214
215	215	ifneq ($(KBUILD_NOCMDDEP),1)
216	216	# Check if both arguments are the same including their order. Result is empty

scripts/Makefile.host+1−1

@@ -6,7 +6,7 @@ · 5 unmodified lines
6	6	#
7	7	# Both C and C++ are supported, but preferred language is C for such utilities.
8	8	#
9		−# Sample syntax (see Documentation/kbuild/makefiles.txt for reference)
	9	+# Sample syntax (see Documentation/kbuild/makefiles.rst for reference)
10	10	# hostprogs-y := bin2hex
11	11	# Will compile bin2hex.c and create an executable named bin2hex
12	12	#

scripts/kconfig/symbol.c+1−1

@@ -1114,7 +1114,7 @@ static void sym_check_print_recursive(struct symbol *last_sym) · 1113 unmodified lines
1114	1114	}
1115	1115
1116	1116	fprintf(stderr,
1117		− "For a resolution refer to Documentation/kbuild/kconfig-language.txt\n"
	1117	+ "For a resolution refer to Documentation/kbuild/kconfig-language.rst\n"
1118	1118	"subsection \"Kconfig recursive dependency limitations\"\n"
1119	1119	"\n");
1120	1120

scripts/kconfig/tests/err_recursive_dep/expected_stderr+7−7

@@ -1,38 +1,38 @@
1	1	Kconfig:11:error: recursive dependency detected!
2	2	Kconfig:11: symbol B is selected by B
3		−For a resolution refer to Documentation/kbuild/kconfig-language.txt
	3	+For a resolution refer to Documentation/kbuild/kconfig-language.rst
4	4	subsection "Kconfig recursive dependency limitations"
5	5
6	6	Kconfig:5:error: recursive dependency detected!
7	7	Kconfig:5: symbol A depends on A
8		−For a resolution refer to Documentation/kbuild/kconfig-language.txt
	8	+For a resolution refer to Documentation/kbuild/kconfig-language.rst
9	9	subsection "Kconfig recursive dependency limitations"
10	10
11	11	Kconfig:17:error: recursive dependency detected!
12	12	Kconfig:17: symbol C1 depends on C2
13	13	Kconfig:21: symbol C2 depends on C1
14		−For a resolution refer to Documentation/kbuild/kconfig-language.txt
	14	+For a resolution refer to Documentation/kbuild/kconfig-language.rst
15	15	subsection "Kconfig recursive dependency limitations"
16	16
17	17	Kconfig:32:error: recursive dependency detected!
18	18	Kconfig:32: symbol D2 is selected by D1
19	19	Kconfig:27: symbol D1 depends on D2
20		−For a resolution refer to Documentation/kbuild/kconfig-language.txt
	20	+For a resolution refer to Documentation/kbuild/kconfig-language.rst
21	21	subsection "Kconfig recursive dependency limitations"
22	22
23	23	Kconfig:37:error: recursive dependency detected!
24	24	Kconfig:37: symbol E1 depends on E2
25	25	Kconfig:42: symbol E2 is implied by E1
26		−For a resolution refer to Documentation/kbuild/kconfig-language.txt
	26	+For a resolution refer to Documentation/kbuild/kconfig-language.rst
27	27	subsection "Kconfig recursive dependency limitations"
28	28
29	29	Kconfig:60:error: recursive dependency detected!
30	30	Kconfig:60: symbol G depends on G
31		−For a resolution refer to Documentation/kbuild/kconfig-language.txt
	31	+For a resolution refer to Documentation/kbuild/kconfig-language.rst
32	32	subsection "Kconfig recursive dependency limitations"
33	33
34	34	Kconfig:51:error: recursive dependency detected!
35	35	Kconfig:51: symbol F2 depends on F1
36	36	Kconfig:49: symbol F1 default value contains F2
37		−For a resolution refer to Documentation/kbuild/kconfig-language.txt
	37	+For a resolution refer to Documentation/kbuild/kconfig-language.rst
38	38	subsection "Kconfig recursive dependency limitations"

sound/oss/dmasound/Kconfig+3−3

@@ -11,7 +11,7 @@ config DMASOUND_ATARI · 10 unmodified lines
11	11	This driver is also available as a module ( = code which can be
12	12	inserted in and removed from the running kernel whenever you
13	13	want). If you want to compile it as a module, say M here and read
14		− <file:Documentation/kbuild/modules.txt>.
	14	+ <file:Documentation/kbuild/modules.rst>.
15	15
16	16	config DMASOUND_PAULA
17	17	tristate "Amiga DMA sound support"
@@ -25,7 +25,7 @@ config DMASOUND_PAULA · 7 unmodified lines
25	25	This driver is also available as a module ( = code which can be
26	26	inserted in and removed from the running kernel whenever you
27	27	want). If you want to compile it as a module, say M here and read
28		− <file:Documentation/kbuild/modules.txt>.
	28	+ <file:Documentation/kbuild/modules.rst>.
29	29
30	30	config DMASOUND_Q40
31	31	tristate "Q40 sound support"
@@ -39,7 +39,7 @@ config DMASOUND_Q40 · 7 unmodified lines
39	39	This driver is also available as a module ( = code which can be
40	40	inserted in and removed from the running kernel whenever you
41	41	want). If you want to compile it as a module, say M here and read
42		− <file:Documentation/kbuild/modules.txt>.
	42	+ <file:Documentation/kbuild/modules.rst>.
43	43
44	44	config DMASOUND
45	45	tristate

docs: kbuild: convert docs to ReST and rename to *.rst

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code