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 | ||
efdf02cf | 185 | --- 3.1 Shared Makefile |
1da177e4 | 186 | |
efdf02cf | 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. | |
1da177e4 | 193 | |
cd238eff MCC |
194 | Example 1:: |
195 | ||
1da177e4 LT |
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 | |
efdf02cf | 203 | # normal makefile |
204 | KDIR ?= /lib/modules/`uname -r`/build | |
1da177e4 | 205 | |
efdf02cf | 206 | default: |
207 | $(MAKE) -C $(KDIR) M=$$PWD | |
1da177e4 LT |
208 | |
209 | # Module specific targets | |
210 | genbin: | |
98a1e444 | 211 | echo "X" > 8123_bin.o_shipped |
1da177e4 LT |
212 | |
213 | endif | |
214 | ||
efdf02cf | 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: | |
5793210c | 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 | |
efdf02cf | 221 | initiated by the parameterized "make" in the default target. |
1da177e4 | 222 | |
cd238eff MCC |
223 | 3.2 Separate Kbuild File and Makefile |
224 | ------------------------------------- | |
efdf02cf | 225 | |
226 | In newer versions of the kernel, kbuild will first look for a | |
5793210c | 227 | file named "Kbuild," and only if that is not found, will it |
efdf02cf | 228 | then look for a makefile. Utilizing a "Kbuild" file allows us |
229 | to split up the makefile from example 1 into two files: | |
1da177e4 | 230 | |
cd238eff MCC |
231 | Example 2:: |
232 | ||
1da177e4 LT |
233 | --> filename: Kbuild |
234 | obj-m := 8123.o | |
235 | 8123-y := 8123_if.o 8123_pci.o 8123_bin.o | |
236 | ||
237 | --> filename: Makefile | |
efdf02cf | 238 | KDIR ?= /lib/modules/`uname -r`/build |
239 | ||
240 | default: | |
241 | $(MAKE) -C $(KDIR) M=$$PWD | |
1da177e4 LT |
242 | |
243 | # Module specific targets | |
244 | genbin: | |
baa91878 | 245 | echo "X" > 8123_bin.o_shipped |
1da177e4 | 246 | |
efdf02cf | 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. | |
1da177e4 | 251 | |
efdf02cf | 252 | The next example shows a backward compatible version. |
1da177e4 | 253 | |
cd238eff MCC |
254 | Example 3:: |
255 | ||
1da177e4 LT |
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),) | |
efdf02cf | 262 | # kbuild part of makefile |
1da177e4 | 263 | include Kbuild |
efdf02cf | 264 | |
1da177e4 | 265 | else |
efdf02cf | 266 | # normal makefile |
267 | KDIR ?= /lib/modules/`uname -r`/build | |
1da177e4 | 268 | |
efdf02cf | 269 | default: |
270 | $(MAKE) -C $(KDIR) M=$$PWD | |
1da177e4 LT |
271 | |
272 | # Module specific targets | |
273 | genbin: | |
baa91878 | 274 | echo "X" > 8123_bin.o_shipped |
1da177e4 LT |
275 | |
276 | endif | |
277 | ||
efdf02cf | 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. | |
1da177e4 | 282 | |
cd238eff MCC |
283 | 3.3 Binary Blobs |
284 | ---------------- | |
1da177e4 | 285 | |
efdf02cf | 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 | |
cd238eff | 295 | 8123_bin.o:: |
1da177e4 | 296 | |
1da177e4 LT |
297 | 8123-y := 8123_if.o 8123_pci.o 8123_bin.o |
298 | ||
efdf02cf | 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 | ||
cd238eff MCC |
303 | 3.4 Building Multiple Modules |
304 | ============================= | |
efdf02cf | 305 | |
306 | kbuild supports building multiple modules with a single build | |
5793210c | 307 | file. For example, if you wanted to build two modules, foo.ko |
cd238eff | 308 | and bar.ko, the kbuild lines would be:: |
efdf02cf | 309 | |
310 | obj-m := foo.o bar.o | |
311 | foo-y := <foo_srcs> | |
312 | bar-y := <bar_srcs> | |
313 | ||
314 | It is that simple! | |
1da177e4 LT |
315 | |
316 | ||
cd238eff MCC |
317 | 4. Include Files |
318 | ================ | |
1da177e4 | 319 | |
9f02186c | 320 | Within the kernel, header files are kept in standard locations |
321 | according to the following rule: | |
d9a7ff66 | 322 | |
9f02186c | 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/. | |
1da177e4 | 329 | |
cd238eff MCC |
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/. | |
1da177e4 | 335 | |
cd238eff MCC |
336 | 4.1 Kernel Includes |
337 | ------------------- | |
1da177e4 | 338 | |
9f02186c | 339 | To include a header file located under include/linux/, simply |
cd238eff | 340 | use:: |
1da177e4 | 341 | |
5793210c | 342 | #include <linux/module.h> |
1da177e4 | 343 | |
9f02186c | 344 | kbuild will add options to "gcc" so the relevant directories |
345 | are searched. | |
1da177e4 | 346 | |
cd238eff MCC |
347 | 4.2 Single Subdirectory |
348 | ----------------------- | |
1da177e4 | 349 | |
9f02186c | 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 | |
5793210c | 353 | directory, use either ccflags-y or CFLAGS_<filename>.o. |
1da177e4 | 354 | |
9f02186c | 355 | Using the example from section 3, if we moved 8123_if.h to a |
356 | subdirectory named include, the resulting kbuild file would | |
cd238eff | 357 | look like:: |
1da177e4 LT |
358 | |
359 | --> filename: Kbuild | |
9f02186c | 360 | obj-m := 8123.o |
1da177e4 | 361 | |
9f02186c | 362 | ccflags-y := -Iinclude |
1da177e4 LT |
363 | 8123-y := 8123_if.o 8123_pci.o 8123_bin.o |
364 | ||
9f02186c | 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. | |
253dfa6e | 368 | |
cd238eff MCC |
369 | 4.3 Several Subdirectories |
370 | -------------------------- | |
253dfa6e | 371 | |
9f02186c | 372 | kbuild can handle files that are spread over several directories. |
cd238eff MCC |
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 | |
9f02186c | 384 | |
385 | To build the module complex.ko, we then need the following | |
cd238eff | 386 | kbuild file:: |
253dfa6e | 387 | |
9f02186c | 388 | --> filename: Kbuild |
253dfa6e SR |
389 | obj-m := complex.o |
390 | complex-y := src/complex_main.o | |
391 | complex-y += src/hal/hardwareif.o | |
392 | ||
9f02186c | 393 | ccflags-y := -I$(src)/include |
394 | ccflags-y += -I$(src)/src/hal/include | |
253dfa6e | 395 | |
9f02186c | 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. | |
253dfa6e | 400 | |
9f02186c | 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. | |
253dfa6e | 407 | |
1da177e4 | 408 | |
cd238eff MCC |
409 | 5. Module Installation |
410 | ====================== | |
1da177e4 | 411 | |
9f02186c | 412 | Modules which are included in the kernel are installed in the |
413 | directory: | |
1da177e4 | 414 | |
5793210c | 415 | /lib/modules/$(KERNELRELEASE)/kernel/ |
1da177e4 | 416 | |
9f02186c | 417 | And external modules are installed in: |
1da177e4 | 418 | |
5793210c | 419 | /lib/modules/$(KERNELRELEASE)/extra/ |
1da177e4 | 420 | |
cd238eff MCC |
421 | 5.1 INSTALL_MOD_PATH |
422 | -------------------- | |
1da177e4 | 423 | |
9f02186c | 424 | Above are the default directories but as always some level of |
425 | customization is possible. A prefix can be added to the | |
cd238eff | 426 | installation path using the variable INSTALL_MOD_PATH:: |
1da177e4 LT |
427 | |
428 | $ make INSTALL_MOD_PATH=/frodo modules_install | |
5793210c | 429 | => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/ |
1da177e4 | 430 | |
9f02186c | 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. | |
1da177e4 | 435 | |
cd238eff MCC |
436 | 5.2 INSTALL_MOD_DIR |
437 | ------------------- | |
1da177e4 | 438 | |
9f02186c | 439 | External modules are by default installed to a directory under |
5793210c | 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 | |
cd238eff | 443 | alternative name to "extra.":: |
1da177e4 | 444 | |
9f02186c | 445 | $ make INSTALL_MOD_DIR=gandalf -C $KDIR \ |
446 | M=$PWD modules_install | |
5793210c | 447 | => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/ |
1da177e4 LT |
448 | |
449 | ||
cd238eff MCC |
450 | 6. Module Versioning |
451 | ==================== | |
1da177e4 | 452 | |
9f02186c | 453 | Module versioning is enabled by the CONFIG_MODVERSIONS tag, and is used |
454 | as a simple ABI consistency check. A CRC value of the full prototype | |
455 | for an exported symbol is created. When a module is loaded/used, the | |
456 | CRC values contained in the kernel are compared with similar values in | |
457 | the module; if they are not equal, the kernel refuses to load the | |
458 | module. | |
1da177e4 | 459 | |
9f02186c | 460 | Module.symvers contains a list of all exported symbols from a kernel |
461 | build. | |
1da177e4 | 462 | |
cd238eff MCC |
463 | 6.1 Symbols From the Kernel (vmlinux + modules) |
464 | ----------------------------------------------- | |
1da177e4 | 465 | |
9f02186c | 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. | |
040fcc81 | 470 | |
cd238eff MCC |
471 | The syntax of the Module.symvers file is:: |
472 | ||
cb9b55d2 | 473 | <CRC> <Symbol> <Namespace> <Module> <Export Type> |
9f02186c | 474 | |
cb9b55d2 MM |
475 | 0xe1cc2a05 usb_stor_suspend USB_STORAGE drivers/usb/storage/usb-storage EXPORT_SYMBOL_GPL |
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). | |
040fcc81 | 479 | |
9f02186c | 480 | For a kernel build without CONFIG_MODVERSIONS enabled, the CRC |
481 | would read 0x00000000. | |
040fcc81 | 482 | |
d9a7ff66 | 483 | Module.symvers serves two purposes: |
cd238eff | 484 | |
9f02186c | 485 | 1) It lists all exported symbols from vmlinux and all modules. |
486 | 2) It lists the CRC if CONFIG_MODVERSIONS is enabled. | |
487 | ||
cd238eff MCC |
488 | 6.2 Symbols and External Modules |
489 | -------------------------------- | |
9f02186c | 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. If a Module.symvers file is present in the directory | |
496 | where the external module is being built, this file will be | |
497 | read too. During the MODPOST step, a new Module.symvers file | |
498 | will be written containing all exported symbols that were not | |
499 | defined in the kernel. | |
500 | ||
807f2105 AG |
501 | 6.3 Symbols From Another External Module |
502 | ---------------------------------------- | |
9f02186c | 503 | |
504 | Sometimes, an external module uses exported symbols from | |
43496709 | 505 | another external module. Kbuild needs to have full knowledge of |
4be7f0a3 | 506 | all symbols to avoid spitting out warnings about undefined |
9f02186c | 507 | symbols. Three solutions exist for this situation. |
508 | ||
509 | NOTE: The method with a top-level kbuild file is recommended | |
510 | but may be impractical in certain situations. | |
511 | ||
512 | Use a top-level kbuild file | |
513 | If you have two modules, foo.ko and bar.ko, where | |
5793210c | 514 | foo.ko needs symbols from bar.ko, you can use a |
9f02186c | 515 | common top-level kbuild file so both modules are |
5793210c | 516 | compiled in the same build. Consider the following |
cd238eff | 517 | directory layout:: |
9f02186c | 518 | |
cd238eff MCC |
519 | ./foo/ <= contains foo.ko |
520 | ./bar/ <= contains bar.ko | |
9f02186c | 521 | |
cd238eff | 522 | The top-level kbuild file would then look like:: |
9f02186c | 523 | |
cd238eff | 524 | #./Kbuild (or ./Makefile): |
43496709 | 525 | obj-m := foo/ bar/ |
040fcc81 | 526 | |
cd238eff | 527 | And executing:: |
5793210c | 528 | |
9f02186c | 529 | $ make -C $KDIR M=$PWD |
040fcc81 | 530 | |
5793210c | 531 | will then do the expected and compile both modules with |
9f02186c | 532 | full knowledge of symbols from either module. |
040fcc81 SR |
533 | |
534 | Use an extra Module.symvers file | |
9f02186c | 535 | When an external module is built, a Module.symvers file |
536 | is generated containing all exported symbols which are | |
537 | not defined in the kernel. To get access to symbols | |
538 | from bar.ko, copy the Module.symvers file from the | |
539 | compilation of bar.ko to the directory where foo.ko is | |
540 | built. During the module build, kbuild will read the | |
541 | Module.symvers file in the directory of the external | |
542 | module, and when the build is finished, a new | |
543 | Module.symvers file is created containing the sum of | |
544 | all symbols defined and not part of the kernel. | |
545 | ||
546 | Use "make" variable KBUILD_EXTRA_SYMBOLS | |
547 | If it is impractical to copy Module.symvers from | |
548 | another module, you can assign a space separated list | |
5793210c | 549 | of files to KBUILD_EXTRA_SYMBOLS in your build file. |
550 | These files will be loaded by modpost during the | |
9f02186c | 551 | initialization of its symbol tables. |
552 | ||
5793210c | 553 | |
cd238eff MCC |
554 | 7. Tips & Tricks |
555 | ================ | |
9f02186c | 556 | |
cd238eff MCC |
557 | 7.1 Testing for CONFIG_FOO_BAR |
558 | ------------------------------ | |
9f02186c | 559 | |
cd238eff | 560 | Modules often need to check for certain `CONFIG_` options to |
9f02186c | 561 | decide if a specific feature is included in the module. In |
cd238eff MCC |
562 | kbuild this is done by referencing the `CONFIG_` variable |
563 | directly:: | |
1da177e4 LT |
564 | |
565 | #fs/ext2/Makefile | |
566 | obj-$(CONFIG_EXT2_FS) += ext2.o | |
567 | ||
568 | ext2-y := balloc.o bitmap.o dir.o | |
569 | ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o | |
570 | ||
9f02186c | 571 | External modules have traditionally used "grep" to check for |
cd238eff | 572 | specific `CONFIG_` settings directly in .config. This usage is |
9f02186c | 573 | broken. As introduced before, external modules should use |
574 | kbuild for building and can therefore use the same methods as | |
cd238eff | 575 | in-tree modules when testing for `CONFIG_` definitions. |