diff options
author | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 18:20:36 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@ppc970.osdl.org> | 2005-04-16 18:20:36 -0400 |
commit | 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch) | |
tree | 0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/kbuild/modules.txt |
Linux-2.6.12-rc2v2.6.12-rc2
Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.
Let it rip!
Diffstat (limited to 'Documentation/kbuild/modules.txt')
-rw-r--r-- | Documentation/kbuild/modules.txt | 419 |
1 files changed, 419 insertions, 0 deletions
diff --git a/Documentation/kbuild/modules.txt b/Documentation/kbuild/modules.txt new file mode 100644 index 000000000000..c91caf7eb303 --- /dev/null +++ b/Documentation/kbuild/modules.txt | |||
@@ -0,0 +1,419 @@ | |||
1 | |||
2 | In this document you will find information about: | ||
3 | - how to build external modules | ||
4 | - how to make your module use kbuild infrastructure | ||
5 | - how kbuild will install a kernel | ||
6 | - how to install modules in a non-standard location | ||
7 | |||
8 | === Table of Contents | ||
9 | |||
10 | === 1 Introduction | ||
11 | === 2 How to build external modules | ||
12 | --- 2.1 Building external modules | ||
13 | --- 2.2 Available targets | ||
14 | --- 2.3 Available options | ||
15 | --- 2.4 Preparing the kernel tree for module build | ||
16 | === 3. Example commands | ||
17 | === 4. Creating a kbuild file for an external module | ||
18 | === 5. Include files | ||
19 | --- 5.1 How to include files from the kernel include dir | ||
20 | --- 5.2 External modules using an include/ dir | ||
21 | === 6. Module installation | ||
22 | --- 6.1 INSTALL_MOD_PATH | ||
23 | --- 6.2 INSTALL_MOD_DIR | ||
24 | === 7. Module versioning | ||
25 | === 8. Tips & Tricks | ||
26 | --- 8.1 Testing for CONFIG_FOO_BAR | ||
27 | |||
28 | |||
29 | |||
30 | === 1. Introduction | ||
31 | |||
32 | kbuild includes functionality for building modules both | ||
33 | within the kernel source tree and outside the kernel source tree. | ||
34 | The latter is usually referred to as external modules and is used | ||
35 | both during development and for modules that are not planned to be | ||
36 | included in the kernel tree. | ||
37 | |||
38 | What is covered within this file is mainly information to authors | ||
39 | of modules. The author of an external modules should supply | ||
40 | a makefile that hides most of the complexity so one only has to type | ||
41 | 'make' to buld the module. A complete example will be present in | ||
42 | chapter ¤. Creating a kbuild file for an external module". | ||
43 | |||
44 | |||
45 | === 2. How to build external modules | ||
46 | |||
47 | kbuild offers functionality to build external modules, with the | ||
48 | prerequisite that there is a pre-built kernel available with full source. | ||
49 | A subset of the targets available when building the kernel is available | ||
50 | when building an external module. | ||
51 | |||
52 | --- 2.1 Building external modules | ||
53 | |||
54 | Use the following command to build an external module: | ||
55 | |||
56 | make -C <path-to-kernel> M=`pwd` | ||
57 | |||
58 | For the running kernel use: | ||
59 | make -C /lib/modules/`uname -r`/build M=`pwd` | ||
60 | |||
61 | For the above command to succeed the kernel must have been built with | ||
62 | modules enabled. | ||
63 | |||
64 | To install the modules that were just built: | ||
65 | |||
66 | make -C <path-to-kernel> M=`pwd` modules_install | ||
67 | |||
68 | More complex examples later, the above should get you going. | ||
69 | |||
70 | --- 2.2 Available targets | ||
71 | |||
72 | $KDIR refers to path to kernel source top-level directory | ||
73 | |||
74 | make -C $KDIR M=`pwd` | ||
75 | Will build the module(s) located in current directory. | ||
76 | All output files will be located in the same directory | ||
77 | as the module source. | ||
78 | No attempts are made to update the kernel source, and it is | ||
79 | a precondition that a successful make has been executed | ||
80 | for the kernel. | ||
81 | |||
82 | make -C $KDIR M=`pwd` modules | ||
83 | The modules target is implied when no target is given. | ||
84 | Same functionality as if no target was specified. | ||
85 | See description above. | ||
86 | |||
87 | make -C $KDIR M=$PWD modules_install | ||
88 | Install the external module(s). | ||
89 | Installation default is in /lib/modules/<kernel-version>/extra, | ||
90 | but may be prefixed with INSTALL_MOD_PATH - see separate chater. | ||
91 | |||
92 | make -C $KDIR M=$PWD clean | ||
93 | Remove all generated files for the module - the kernel | ||
94 | source directory is not moddified. | ||
95 | |||
96 | make -C $KDIR M=`pwd` help | ||
97 | help will list the available target when building external | ||
98 | modules. | ||
99 | |||
100 | --- 2.3 Available options: | ||
101 | |||
102 | $KDIR refer to path to kernel src | ||
103 | |||
104 | make -C $KDIR | ||
105 | Used to specify where to find the kernel source. | ||
106 | '$KDIR' represent the directory where the kernel source is. | ||
107 | Make will actually change directory to the specified directory | ||
108 | when executed but change back when finished. | ||
109 | |||
110 | make -C $KDIR M=`pwd` | ||
111 | M= is used to tell kbuild that an external module is | ||
112 | being built. | ||
113 | The option given to M= is the directory where the external | ||
114 | module (kbuild file) is located. | ||
115 | When an external module is being built only a subset of the | ||
116 | usual targets are available. | ||
117 | |||
118 | make -C $KDIR SUBDIRS=`pwd` | ||
119 | Same as M=. The SUBDIRS= syntax is kept for backwards | ||
120 | compatibility. | ||
121 | |||
122 | --- 2.4 Preparing the kernel tree for module build | ||
123 | |||
124 | To make sure the kernel contains the information required to | ||
125 | build external modules the target 'modules_prepare' must be used. | ||
126 | 'module_prepare' solely exists as a simple way to prepare | ||
127 | a kernel for building external modules. | ||
128 | Note: modules_prepare will not build Module.symvers even if | ||
129 | CONFIG_MODULEVERSIONING is set. | ||
130 | Therefore a full kernel build needs to be executed to make | ||
131 | module versioning work. | ||
132 | |||
133 | |||
134 | === 3. Example commands | ||
135 | |||
136 | This example shows the actual commands to be executed when building | ||
137 | an external module for the currently running kernel. | ||
138 | In the example below the distribution is supposed to use the | ||
139 | facility to locate output files for a kernel compile in a different | ||
140 | directory than the kernel source - but the examples will also work | ||
141 | when the source and the output files are mixed in the same directory. | ||
142 | |||
143 | # Kernel source | ||
144 | /lib/modules/<kernel-version>/source -> /usr/src/linux-<version> | ||
145 | |||
146 | # Output from kernel compile | ||
147 | /lib/modules/<kernel-version>/build -> /usr/src/linux-<version>-up | ||
148 | |||
149 | Change to the directory where the kbuild file is located and execute | ||
150 | the following commands to build the module: | ||
151 | |||
152 | cd /home/user/src/module | ||
153 | make -C /usr/src/`uname -r`/source \ | ||
154 | O=/lib/modules/`uname-r`/build \ | ||
155 | M=`pwd` | ||
156 | |||
157 | Then to install the module use the following command: | ||
158 | |||
159 | make -C /usr/src/`uname -r`/source \ | ||
160 | O=/lib/modules/`uname-r`/build \ | ||
161 | M=`pwd` \ | ||
162 | modules_install | ||
163 | |||
164 | If one looks closely you will see that this is the same commands as | ||
165 | listed before - with the directories spelled out. | ||
166 | |||
167 | The above are rather long commands, and the following chapter | ||
168 | lists a few tricks to make it all easier. | ||
169 | |||
170 | |||
171 | === 4. Creating a kbuild file for an external module | ||
172 | |||
173 | kbuild is the build system for the kernel, and external modules | ||
174 | must use kbuild to stay compatible with changes in the build system | ||
175 | and to pick up the right flags to gcc etc. | ||
176 | |||
177 | The kbuild file used as input shall follow the syntax described | ||
178 | in Documentation/kbuild/makefiles.txt. This chapter will introduce a few | ||
179 | more tricks to be used when dealing with external modules. | ||
180 | |||
181 | In the following a Makefile will be created for a module with the | ||
182 | following files: | ||
183 | 8123_if.c | ||
184 | 8123_if.h | ||
185 | 8123_pci.c | ||
186 | 8123_bin.o_shipped <= Binary blob | ||
187 | |||
188 | --- 4.1 Shared Makefile for module and kernel | ||
189 | |||
190 | An external module always includes a wrapper Makefile supporting | ||
191 | building the module using 'make' with no arguments. | ||
192 | The Makefile provided will most likely include additional | ||
193 | functionality such as test targets etc. and this part shall | ||
194 | be filtered away from kbuild since it may impact kbuild if | ||
195 | name clashes occurs. | ||
196 | |||
197 | Example 1: | ||
198 | --> filename: Makefile | ||
199 | ifneq ($(KERNELRELEASE),) | ||
200 | # kbuild part of makefile | ||
201 | obj-m := 8123.o | ||
202 | 8123-y := 8123_if.o 8123_pci.o 8123_bin.o | ||
203 | |||
204 | else | ||
205 | # Normal Makefile | ||
206 | |||
207 | KERNELDIR := /lib/modules/`uname -r`/build | ||
208 | all:: | ||
209 | $(MAKE) -C $KERNELDIR M=`pwd` $@ | ||
210 | |||
211 | # Module specific targets | ||
212 | genbin: | ||
213 | echo "X" > 8123_bini.o_shipped | ||
214 | |||
215 | endif | ||
216 | |||
217 | In example 1 the check for KERNELRELEASE is used to separate | ||
218 | the two parts of the Makefile. kbuild will only see the two | ||
219 | assignments whereas make will see everything except the two | ||
220 | kbuild assignments. | ||
221 | |||
222 | In recent versions of the kernel, kbuild will look for a file named | ||
223 | Kbuild and as second option look for a file named Makefile. | ||
224 | Utilising the Kbuild file makes us split up the Makefile in example 1 | ||
225 | into two files as shown in example 2: | ||
226 | |||
227 | Example 2: | ||
228 | --> filename: Kbuild | ||
229 | obj-m := 8123.o | ||
230 | 8123-y := 8123_if.o 8123_pci.o 8123_bin.o | ||
231 | |||
232 | --> filename: Makefile | ||
233 | KERNELDIR := /lib/modules/`uname -r`/build | ||
234 | all:: | ||
235 | $(MAKE) -C $KERNELDIR M=`pwd` $@ | ||
236 | |||
237 | # Module specific targets | ||
238 | genbin: | ||
239 | echo "X" > 8123_bin_shipped | ||
240 | |||
241 | |||
242 | In example 2 we are down to two fairly simple files and for simple | ||
243 | files as used in this example the split is questionable. But some | ||
244 | external modules use Makefiles of several hundred lines and here it | ||
245 | really pays off to separate the kbuild part from the rest. | ||
246 | Example 3 shows a backward compatible version. | ||
247 | |||
248 | Example 3: | ||
249 | --> filename: Kbuild | ||
250 | obj-m := 8123.o | ||
251 | 8123-y := 8123_if.o 8123_pci.o 8123_bin.o | ||
252 | |||
253 | --> filename: Makefile | ||
254 | ifneq ($(KERNELRELEASE),) | ||
255 | include Kbuild | ||
256 | else | ||
257 | # Normal Makefile | ||
258 | |||
259 | KERNELDIR := /lib/modules/`uname -r`/build | ||
260 | all:: | ||
261 | $(MAKE) -C $KERNELDIR M=`pwd` $@ | ||
262 | |||
263 | # Module specific targets | ||
264 | genbin: | ||
265 | echo "X" > 8123_bin_shipped | ||
266 | |||
267 | endif | ||
268 | |||
269 | The trick here is to include the Kbuild file from Makefile so | ||
270 | if an older version of kbuild picks up the Makefile the Kbuild | ||
271 | file will be included. | ||
272 | |||
273 | --- 4.2 Binary blobs included in a module | ||
274 | |||
275 | Some external modules needs to include a .o as a blob. kbuild | ||
276 | has support for this, but requires the blob file to be named | ||
277 | <filename>_shipped. In our example the blob is named | ||
278 | 8123_bin.o_shipped and when the kbuild rules kick in the file | ||
279 | 8123_bin.o is created as a simple copy off the 8213_bin.o_shipped file | ||
280 | with the _shipped part stripped of the filename. | ||
281 | This allows the 8123_bin.o filename to be used in the assignment to | ||
282 | the module. | ||
283 | |||
284 | Example 4: | ||
285 | obj-m := 8123.o | ||
286 | 8123-y := 8123_if.o 8123_pci.o 8123_bin.o | ||
287 | |||
288 | In example 4 there is no distinction between the ordinary .c/.h files | ||
289 | and the binary file. But kbuild will pick up different rules to create | ||
290 | the .o file. | ||
291 | |||
292 | |||
293 | === 5. Include files | ||
294 | |||
295 | Include files are a necessity when a .c file uses something from another .c | ||
296 | files (not strictly in the sense of .c but if good programming practice is | ||
297 | used). Any module that consist of more than one .c file will have a .h file | ||
298 | for one of the .c files. | ||
299 | - If the .h file only describes a module internal interface then the .h file | ||
300 | shall be placed in the same directory as the .c files. | ||
301 | - If the .h files describe an interface used by other parts of the kernel | ||
302 | located in different directories, the .h files shall be located in | ||
303 | include/linux/ or other include/ directories as appropriate. | ||
304 | |||
305 | One exception for this rule is larger subsystems that have their own directory | ||
306 | under include/ such as include/scsi. Another exception is arch-specific | ||
307 | .h files which are located under include/asm-$(ARCH)/*. | ||
308 | |||
309 | External modules have a tendency to locate include files in a separate include/ | ||
310 | directory and therefore needs to deal with this in their kbuild file. | ||
311 | |||
312 | --- 5.1 How to include files from the kernel include dir | ||
313 | |||
314 | When a module needs to include a file from include/linux/ then one | ||
315 | just uses: | ||
316 | |||
317 | #include <linux/modules.h> | ||
318 | |||
319 | kbuild will make sure to add options to gcc so the relevant | ||
320 | directories are searched. | ||
321 | Likewise for .h files placed in the same directory as the .c file. | ||
322 | |||
323 | #include "8123_if.h" | ||
324 | |||
325 | will do the job. | ||
326 | |||
327 | --- 5.2 External modules using an include/ dir | ||
328 | |||
329 | External modules often locate their .h files in a separate include/ | ||
330 | directory although this is not usual kernel style. When an external | ||
331 | module uses an include/ dir then kbuild needs to be told so. | ||
332 | The trick here is to use either EXTRA_CFLAGS (take effect for all .c | ||
333 | files) or CFLAGS_$F.o (take effect only for a single file). | ||
334 | |||
335 | In our example if we move 8123_if.h to a subdirectory named include/ | ||
336 | the resulting Kbuild file would look like: | ||
337 | |||
338 | --> filename: Kbuild | ||
339 | obj-m := 8123.o | ||
340 | |||
341 | EXTRA_CFLAGS := -Iinclude | ||
342 | 8123-y := 8123_if.o 8123_pci.o 8123_bin.o | ||
343 | |||
344 | Note that in the assingment there is no space between -I and the path. | ||
345 | This is a kbuild limitation and no space must be present. | ||
346 | |||
347 | |||
348 | === 6. Module installation | ||
349 | |||
350 | Modules which are included in the kernel is installed in the directory: | ||
351 | |||
352 | /lib/modules/$(KERNELRELEASE)/kernel | ||
353 | |||
354 | External modules are installed in the directory: | ||
355 | |||
356 | /lib/modules/$(KERNELRELEASE)/extra | ||
357 | |||
358 | --- 6.1 INSTALL_MOD_PATH | ||
359 | |||
360 | Above are the default directories, but as always some level of | ||
361 | customization is possible. One can prefix the path using the variable | ||
362 | INSTALL_MOD_PATH: | ||
363 | |||
364 | $ make INSTALL_MOD_PATH=/frodo modules_install | ||
365 | => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel | ||
366 | |||
367 | INSTALL_MOD_PATH may be set as an ordinary shell variable or as in the | ||
368 | example above be specified on the commandline when calling make. | ||
369 | INSTALL_MOD_PATH has effect both when installing modules included in | ||
370 | the kernel as well as when installing external modules. | ||
371 | |||
372 | --- 6.2 INSTALL_MOD_DIR | ||
373 | |||
374 | When installing external modules they are default installed in a | ||
375 | directory under /lib/modules/$(KERNELRELEASE)/extra, but one may wish | ||
376 | to locate modules for a specific functionality in a separate | ||
377 | directory. For this purpose one can use INSTALL_MOD_DIR to specify an | ||
378 | alternative name than 'extra'. | ||
379 | |||
380 | $ make INSTALL_MOD_DIR=gandalf -C KERNELDIR \ | ||
381 | M=`pwd` modules_install | ||
382 | => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf | ||
383 | |||
384 | |||
385 | === 7. Module versioning | ||
386 | |||
387 | Module versioning are enabled by the CONFIG_MODVERSIONS tag. | ||
388 | |||
389 | Module versioning is used as a simple ABI consistency check. The Module | ||
390 | versioning creates a CRC value of the full prototype for an exported symbol and | ||
391 | when a module is loaded/used then the CRC values contained in the kernel are | ||
392 | compared with similar values in the module. If they are not equal then the | ||
393 | kernel refuses to load the module. | ||
394 | |||
395 | During a kernel build a file named Module.symvers will be generated. This | ||
396 | file includes the symbol version of all symbols within the kernel. If the | ||
397 | Module.symvers file is saved from the last full kernel compile one does not | ||
398 | have to do a full kernel compile to build a module version's compatible module. | ||
399 | |||
400 | === 8. Tips & Tricks | ||
401 | |||
402 | --- 8.1 Testing for CONFIG_FOO_BAR | ||
403 | |||
404 | Modules often needs to check for certain CONFIG_ options to decide if | ||
405 | a specific feature shall be included in the module. When kbuild is used | ||
406 | this is done by referencing the CONFIG_ variable directly. | ||
407 | |||
408 | #fs/ext2/Makefile | ||
409 | obj-$(CONFIG_EXT2_FS) += ext2.o | ||
410 | |||
411 | ext2-y := balloc.o bitmap.o dir.o | ||
412 | ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o | ||
413 | |||
414 | External modules have traditionally used grep to check for specific | ||
415 | CONFIG_ settings directly in .config. This usage is broken. | ||
416 | As introduced before external modules shall use kbuild when building | ||
417 | and therefore can use the same methods as in-kernel modules when testing | ||
418 | for CONFIG_ definitions. | ||
419 | |||