1=========================
2Building External Modules
3=========================
4
5This document describes how to build an out-of-tree kernel module.
6
7.. Table of Contents
8
9	=== 1 Introduction
10	=== 2 How to Build External Modules
11	   --- 2.1 Command Syntax
12	   --- 2.2 Options
13	   --- 2.3 Targets
14	   --- 2.4 Building Separate Files
15	=== 3. Creating a Kbuild File for an External Module
16	   --- 3.1 Shared Makefile
17	   --- 3.2 Separate Kbuild file and Makefile
18	   --- 3.3 Binary Blobs
19	   --- 3.4 Building Multiple Modules
20	=== 4. Include Files
21	   --- 4.1 Kernel Includes
22	   --- 4.2 Single Subdirectory
23	   --- 4.3 Several Subdirectories
24	=== 5. Module Installation
25	   --- 5.1 INSTALL_MOD_PATH
26	   --- 5.2 INSTALL_MOD_DIR
27	=== 6. Module Versioning
28	   --- 6.1 Symbols From the Kernel (vmlinux + modules)
29	   --- 6.2 Symbols and External Modules
30	   --- 6.3 Symbols From Another External Module
31	=== 7. Tips & Tricks
32	   --- 7.1 Testing for CONFIG_FOO_BAR
33
34
35
361. Introduction
37===============
38
39"kbuild" is the build system used by the Linux kernel. Modules must use
40kbuild to stay compatible with changes in the build infrastructure and
41to pick up the right flags to "gcc." Functionality for building modules
42both in-tree and out-of-tree is provided. The method for building
43either is similar, and all modules are initially developed and built
44out-of-tree.
45
46Covered in this document is information aimed at developers interested
47in building out-of-tree (or "external") modules. The author of an
48external module should supply a makefile that hides most of the
49complexity, so one only has to type "make" to build the module. This is
50easily accomplished, and a complete example will be presented in
51section 3.
52
53
542. How to Build External Modules
55================================
56
57To build external modules, you must have a prebuilt kernel available
58that contains the configuration and header files used in the build.
59Also, the kernel must have been built with modules enabled. If you are
60using a distribution kernel, there will be a package for the kernel you
61are running provided by your distribution.
62
63An alternative is to use the "make" target "modules_prepare." This will
64make sure the kernel contains the information required. The target
65exists solely as a simple way to prepare a kernel source tree for
66building external modules.
67
68NOTE: "modules_prepare" will not build Module.symvers even if
69CONFIG_MODVERSIONS is set; therefore, a full kernel build needs to be
70executed to make module versioning work.
71
722.1 Command Syntax
73==================
74
75	The command to build an external module is::
76
77		$ make -C <path_to_kernel_src> M=$PWD
78
79	The kbuild system knows that an external module is being built
80	due to the "M=<dir>" option given in the command.
81
82	To build against the running kernel use::
83
84		$ make -C /lib/modules/`uname -r`/build M=$PWD
85
86	Then to install the module(s) just built, add the target
87	"modules_install" to the command::
88
89		$ make -C /lib/modules/`uname -r`/build M=$PWD modules_install
90
912.2 Options
92===========
93
94	($KDIR refers to the path of the kernel source directory.)
95
96	make -C $KDIR M=$PWD
97
98	-C $KDIR
99		The directory where the kernel source is located.
100		"make" will actually change to the specified directory
101		when executing and will change back when finished.
102
103	M=$PWD
104		Informs kbuild that an external module is being built.
105		The value given to "M" is the absolute path of the
106		directory where the external module (kbuild file) is
107		located.
108
1092.3 Targets
110===========
111
112	When building an external module, only a subset of the "make"
113	targets are available.
114
115	make -C $KDIR M=$PWD [target]
116
117	The default will build the module(s) located in the current
118	directory, so a target does not need to be specified. All
119	output files will also be generated in this directory. No
120	attempts are made to update the kernel source, and it is a
121	precondition that a successful "make" has been executed for the
122	kernel.
123
124	modules
125		The default target for external modules. It has the
126		same functionality as if no target was specified. See
127		description above.
128
129	modules_install
130		Install the external module(s). The default location is
131		/lib/modules/<kernel_release>/extra/, but a prefix may
132		be added with INSTALL_MOD_PATH (discussed in section 5).
133
134	clean
135		Remove all generated files in the module directory only.
136
137	help
138		List the available targets for external modules.
139
1402.4 Building Separate Files
141===========================
142
143	It is possible to build single files that are part of a module.
144	This works equally well for the kernel, a module, and even for
145	external modules.
146
147	Example (The module foo.ko, consist of bar.o and baz.o)::
148
149		make -C $KDIR M=$PWD bar.lst
150		make -C $KDIR M=$PWD baz.o
151		make -C $KDIR M=$PWD foo.ko
152		make -C $KDIR M=$PWD ./
153
154
1553. Creating a Kbuild File for an External Module
156================================================
157
158In the last section we saw the command to build a module for the
159running kernel. The module is not actually built, however, because a
160build file is required. Contained in this file will be the name of
161the module(s) being built, along with the list of requisite source
162files. The file may be as simple as a single line::
163
164	obj-m := <module_name>.o
165
166The kbuild system will build <module_name>.o from <module_name>.c,
167and, after linking, will result in the kernel module <module_name>.ko.
168The above line can be put in either a "Kbuild" file or a "Makefile."
169When the module is built from multiple sources, an additional line is
170needed listing the files::
171
172	<module_name>-y := <src1>.o <src2>.o ...
173
174NOTE: Further documentation describing the syntax used by kbuild is
175located in Documentation/kbuild/makefiles.rst.
176
177The examples below demonstrate how to create a build file for the
178module 8123.ko, which is built from the following files::
179
180	8123_if.c
181	8123_if.h
182	8123_pci.c
183	8123_bin.o_shipped	<= Binary blob
184
185--- 3.1 Shared Makefile
186
187	An external module always includes a wrapper makefile that
188	supports building the module using "make" with no arguments.
189	This target is not used by kbuild; it is only for convenience.
190	Additional functionality, such as test targets, can be included
191	but should be filtered out from kbuild due to possible name
192	clashes.
193
194	Example 1::
195
196		--> filename: Makefile
197		ifneq ($(KERNELRELEASE),)
198		# kbuild part of makefile
199		obj-m  := 8123.o
200		8123-y := 8123_if.o 8123_pci.o 8123_bin.o
201
202		else
203		# normal makefile
204		KDIR ?= /lib/modules/`uname -r`/build
205
206		default:
207			$(MAKE) -C $(KDIR) M=$$PWD
208
209		# Module specific targets
210		genbin:
211			echo "X" > 8123_bin.o_shipped
212
213		endif
214
215	The check for KERNELRELEASE is used to separate the two parts
216	of the makefile. In the example, kbuild will only see the two
217	assignments, whereas "make" will see everything except these
218	two assignments. This is due to two passes made on the file:
219	the first pass is by the "make" instance run on the command
220	line; the second pass is by the kbuild system, which is
221	initiated by the parameterized "make" in the default target.
222
2233.2 Separate Kbuild File and Makefile
224-------------------------------------
225
226	In newer versions of the kernel, kbuild will first look for a
227	file named "Kbuild," and only if that is not found, will it
228	then look for a makefile. Utilizing a "Kbuild" file allows us
229	to split up the makefile from example 1 into two files:
230
231	Example 2::
232
233		--> filename: Kbuild
234		obj-m  := 8123.o
235		8123-y := 8123_if.o 8123_pci.o 8123_bin.o
236
237		--> filename: Makefile
238		KDIR ?= /lib/modules/`uname -r`/build
239
240		default:
241			$(MAKE) -C $(KDIR) M=$$PWD
242
243		# Module specific targets
244		genbin:
245			echo "X" > 8123_bin.o_shipped
246
247	The split in example 2 is questionable due to the simplicity of
248	each file; however, some external modules use makefiles
249	consisting of several hundred lines, and here it really pays
250	off to separate the kbuild part from the rest.
251
252	The next example shows a backward compatible version.
253
254	Example 3::
255
256		--> filename: Kbuild
257		obj-m  := 8123.o
258		8123-y := 8123_if.o 8123_pci.o 8123_bin.o
259
260		--> filename: Makefile
261		ifneq ($(KERNELRELEASE),)
262		# kbuild part of makefile
263		include Kbuild
264
265		else
266		# normal makefile
267		KDIR ?= /lib/modules/`uname -r`/build
268
269		default:
270			$(MAKE) -C $(KDIR) M=$$PWD
271
272		# Module specific targets
273		genbin:
274			echo "X" > 8123_bin.o_shipped
275
276		endif
277
278	Here the "Kbuild" file is included from the makefile. This
279	allows an older version of kbuild, which only knows of
280	makefiles, to be used when the "make" and kbuild parts are
281	split into separate files.
282
2833.3 Binary Blobs
284----------------
285
286	Some external modules need to include an object file as a blob.
287	kbuild has support for this, but requires the blob file to be
288	named <filename>_shipped. When the kbuild rules kick in, a copy
289	of <filename>_shipped is created with _shipped stripped off,
290	giving us <filename>. This shortened filename can be used in
291	the assignment to the module.
292
293	Throughout this section, 8123_bin.o_shipped has been used to
294	build the kernel module 8123.ko; it has been included as
295	8123_bin.o::
296
297		8123-y := 8123_if.o 8123_pci.o 8123_bin.o
298
299	Although there is no distinction between the ordinary source
300	files and the binary file, kbuild will pick up different rules
301	when creating the object file for the module.
302
3033.4 Building Multiple Modules
304=============================
305
306	kbuild supports building multiple modules with a single build
307	file. For example, if you wanted to build two modules, foo.ko
308	and bar.ko, the kbuild lines would be::
309
310		obj-m := foo.o bar.o
311		foo-y := <foo_srcs>
312		bar-y := <bar_srcs>
313
314	It is that simple!
315
316
3174. Include Files
318================
319
320Within the kernel, header files are kept in standard locations
321according to the following rule:
322
323	* If the header file only describes the internal interface of a
324	  module, then the file is placed in the same directory as the
325	  source files.
326	* If the header file describes an interface used by other parts
327	  of the kernel that are located in different directories, then
328	  the file is placed in include/linux/.
329
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/.
335
3364.1 Kernel Includes
337-------------------
338
339	To include a header file located under include/linux/, simply
340	use::
341
342		#include <linux/module.h>
343
344	kbuild will add options to "gcc" so the relevant directories
345	are searched.
346
3474.2 Single Subdirectory
348-----------------------
349
350	External modules tend to place header files in a separate
351	include/ directory where their source is located, although this
352	is not the usual kernel style. To inform kbuild of the
353	directory, use either ccflags-y or CFLAGS_<filename>.o.
354
355	Using the example from section 3, if we moved 8123_if.h to a
356	subdirectory named include, the resulting kbuild file would
357	look like::
358
359		--> filename: Kbuild
360		obj-m := 8123.o
361
362		ccflags-y := -Iinclude
363		8123-y := 8123_if.o 8123_pci.o 8123_bin.o
364
365	Note that in the assignment there is no space between -I and
366	the path. This is a limitation of kbuild: there must be no
367	space present.
368
3694.3 Several Subdirectories
370--------------------------
371
372	kbuild can handle files that are spread over several directories.
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
384
385	To build the module complex.ko, we then need the following
386	kbuild file::
387
388		--> filename: Kbuild
389		obj-m := complex.o
390		complex-y := src/complex_main.o
391		complex-y += src/hal/hardwareif.o
392
393		ccflags-y := -I$(src)/include
394		ccflags-y += -I$(src)/src/hal/include
395
396	As you can see, kbuild knows how to handle object files located
397	in other directories. The trick is to specify the directory
398	relative to the kbuild file's location. That being said, this
399	is NOT recommended practice.
400
401	For the header files, kbuild must be explicitly told where to
402	look. When kbuild executes, the current directory is always the
403	root of the kernel tree (the argument to "-C") and therefore an
404	absolute path is needed. $(src) provides the absolute path by
405	pointing to the directory where the currently executing kbuild
406	file is located.
407
408
4095. Module Installation
410======================
411
412Modules which are included in the kernel are installed in the
413directory:
414
415	/lib/modules/$(KERNELRELEASE)/kernel/
416
417And external modules are installed in:
418
419	/lib/modules/$(KERNELRELEASE)/extra/
420
4215.1 INSTALL_MOD_PATH
422--------------------
423
424	Above are the default directories but as always some level of
425	customization is possible. A prefix can be added to the
426	installation path using the variable INSTALL_MOD_PATH::
427
428		$ make INSTALL_MOD_PATH=/frodo modules_install
429		=> Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/
430
431	INSTALL_MOD_PATH may be set as an ordinary shell variable or,
432	as shown above, can be specified on the command line when
433	calling "make." This has effect when installing both in-tree
434	and out-of-tree modules.
435
4365.2 INSTALL_MOD_DIR
437-------------------
438
439	External modules are by default installed to a directory under
440	/lib/modules/$(KERNELRELEASE)/extra/, but you may wish to
441	locate modules for a specific functionality in a separate
442	directory. For this purpose, use INSTALL_MOD_DIR to specify an
443	alternative name to "extra."::
444
445		$ make INSTALL_MOD_DIR=gandalf -C $KDIR \
446		       M=$PWD modules_install
447		=> Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/
448
449
4506. Module Versioning
451====================
452
453Module versioning is enabled by the CONFIG_MODVERSIONS tag, and is used
454as a simple ABI consistency check. A CRC value of the full prototype
455for an exported symbol is created. When a module is loaded/used, the
456CRC values contained in the kernel are compared with similar values in
457the module; if they are not equal, the kernel refuses to load the
458module.
459
460Module.symvers contains a list of all exported symbols from a kernel
461build.
462
4636.1 Symbols From the Kernel (vmlinux + modules)
464-----------------------------------------------
465
466	During a kernel build, a file named Module.symvers will be
467	generated. Module.symvers contains all exported symbols from
468	the kernel and compiled modules. For each symbol, the
469	corresponding CRC value is also stored.
470
471	The syntax of the Module.symvers file is::
472
473	<CRC>       <Symbol>         <Module>                         <Export Type>     <Namespace>
474
475	0xe1cc2a05  usb_stor_suspend drivers/usb/storage/usb-storage  EXPORT_SYMBOL_GPL USB_STORAGE
476
477	The fields are separated by tabs and values may be empty (e.g.
478	if no namespace is defined for an exported symbol).
479
480	For a kernel build without CONFIG_MODVERSIONS enabled, the CRC
481	would read 0x00000000.
482
483	Module.symvers serves two purposes:
484
485	1) It lists all exported symbols from vmlinux and all modules.
486	2) It lists the CRC if CONFIG_MODVERSIONS is enabled.
487
4886.2 Symbols and External Modules
489--------------------------------
490
491	When building an external module, the build system needs access
492	to the symbols from the kernel to check if all external symbols
493	are defined. This is done in the MODPOST step. modpost obtains
494	the symbols by reading Module.symvers from the kernel source
495	tree. During the MODPOST step, a new Module.symvers file will be
496	written containing all exported symbols from that external module.
497
4986.3 Symbols From Another External Module
499----------------------------------------
500
501	Sometimes, an external module uses exported symbols from
502	another external module. Kbuild needs to have full knowledge of
503	all symbols to avoid spitting out warnings about undefined
504	symbols. Two solutions exist for this situation.
505
506	NOTE: The method with a top-level kbuild file is recommended
507	but may be impractical in certain situations.
508
509	Use a top-level kbuild file
510		If you have two modules, foo.ko and bar.ko, where
511		foo.ko needs symbols from bar.ko, you can use a
512		common top-level kbuild file so both modules are
513		compiled in the same build. Consider the following
514		directory layout::
515
516			./foo/ <= contains foo.ko
517			./bar/ <= contains bar.ko
518
519		The top-level kbuild file would then look like::
520
521			#./Kbuild (or ./Makefile):
522				obj-m := foo/ bar/
523
524		And executing::
525
526			$ make -C $KDIR M=$PWD
527
528		will then do the expected and compile both modules with
529		full knowledge of symbols from either module.
530
531	Use an extra Module.symvers file
532		When an external module is built, a Module.symvers file
533		is generated containing all exported symbols which are
534		not defined in the kernel. To get access to symbols
535		from bar.ko, copy the Module.symvers file from the
536		compilation of bar.ko to the directory where foo.ko is
537		built. During the module build, kbuild will read the
538		Module.symvers file in the directory of the external
539		module, and when the build is finished, a new
540		Module.symvers file is created containing the sum of
541		all symbols defined and not part of the kernel.
542
543	Use "make" variable KBUILD_EXTRA_SYMBOLS
544		If it is impractical to add a top-level kbuild file,
545		you can assign a space separated list
546		of files to KBUILD_EXTRA_SYMBOLS in your build file.
547		These files will be loaded by modpost during the
548		initialization of its symbol tables.
549
550
5517. Tips & Tricks
552================
553
5547.1 Testing for CONFIG_FOO_BAR
555------------------------------
556
557	Modules often need to check for certain `CONFIG_` options to
558	decide if a specific feature is included in the module. In
559	kbuild this is done by referencing the `CONFIG_` variable
560	directly::
561
562		#fs/ext2/Makefile
563		obj-$(CONFIG_EXT2_FS) += ext2.o
564
565		ext2-y := balloc.o bitmap.o dir.o
566		ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o
567
568	External modules have traditionally used "grep" to check for
569	specific `CONFIG_` settings directly in .config. This usage is
570	broken. As introduced before, external modules should use
571	kbuild for building and can therefore use the same methods as
572	in-tree modules when testing for `CONFIG_` definitions.
573