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