Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> | |
4 | ||
5 | <book id="lk-hacking-guide"> | |
6 | <bookinfo> | |
7 | <title>Unreliable Guide To Hacking The Linux Kernel</title> | |
8 | ||
9 | <authorgroup> | |
10 | <author> | |
b6c17ea4 | 11 | <firstname>Rusty</firstname> |
1da177e4 LT |
12 | <surname>Russell</surname> |
13 | <affiliation> | |
14 | <address> | |
15 | <email>rusty@rustcorp.com.au</email> | |
16 | </address> | |
17 | </affiliation> | |
18 | </author> | |
19 | </authorgroup> | |
20 | ||
21 | <copyright> | |
b6c17ea4 | 22 | <year>2005</year> |
1da177e4 LT |
23 | <holder>Rusty Russell</holder> |
24 | </copyright> | |
25 | ||
26 | <legalnotice> | |
27 | <para> | |
28 | This documentation is free software; you can redistribute | |
29 | it and/or modify it under the terms of the GNU General Public | |
30 | License as published by the Free Software Foundation; either | |
31 | version 2 of the License, or (at your option) any later | |
32 | version. | |
33 | </para> | |
34 | ||
35 | <para> | |
36 | This program is distributed in the hope that it will be | |
37 | useful, but WITHOUT ANY WARRANTY; without even the implied | |
38 | warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
39 | See the GNU General Public License for more details. | |
40 | </para> | |
41 | ||
42 | <para> | |
43 | You should have received a copy of the GNU General Public | |
44 | License along with this program; if not, write to the Free | |
45 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, | |
46 | MA 02111-1307 USA | |
47 | </para> | |
48 | ||
49 | <para> | |
50 | For more details see the file COPYING in the source | |
51 | distribution of Linux. | |
52 | </para> | |
53 | </legalnotice> | |
54 | ||
55 | <releaseinfo> | |
56 | This is the first release of this document as part of the kernel tarball. | |
57 | </releaseinfo> | |
58 | ||
59 | </bookinfo> | |
60 | ||
61 | <toc></toc> | |
62 | ||
63 | <chapter id="introduction"> | |
64 | <title>Introduction</title> | |
65 | <para> | |
b6c17ea4 | 66 | Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux |
1da177e4 LT |
67 | Kernel Hacking. This document describes the common routines and |
68 | general requirements for kernel code: its goal is to serve as a | |
69 | primer for Linux kernel development for experienced C | |
70 | programmers. I avoid implementation details: that's what the | |
71 | code is for, and I ignore whole tracts of useful routines. | |
72 | </para> | |
73 | <para> | |
74 | Before you read this, please understand that I never wanted to | |
75 | write this document, being grossly under-qualified, but I always | |
76 | wanted to read it, and this was the only way. I hope it will | |
77 | grow into a compendium of best practice, common starting points | |
78 | and random information. | |
79 | </para> | |
80 | </chapter> | |
81 | ||
82 | <chapter id="basic-players"> | |
83 | <title>The Players</title> | |
84 | ||
85 | <para> | |
86 | At any time each of the CPUs in a system can be: | |
87 | </para> | |
88 | ||
89 | <itemizedlist> | |
90 | <listitem> | |
91 | <para> | |
92 | not associated with any process, serving a hardware interrupt; | |
93 | </para> | |
94 | </listitem> | |
95 | ||
96 | <listitem> | |
97 | <para> | |
b6c17ea4 | 98 | not associated with any process, serving a softirq or tasklet; |
1da177e4 LT |
99 | </para> |
100 | </listitem> | |
101 | ||
102 | <listitem> | |
103 | <para> | |
b6c17ea4 | 104 | running in kernel space, associated with a process (user context); |
1da177e4 LT |
105 | </para> |
106 | </listitem> | |
107 | ||
108 | <listitem> | |
109 | <para> | |
110 | running a process in user space. | |
111 | </para> | |
112 | </listitem> | |
113 | </itemizedlist> | |
114 | ||
115 | <para> | |
b6c17ea4 RR |
116 | There is an ordering between these. The bottom two can preempt |
117 | each other, but above that is a strict hierarchy: each can only be | |
118 | preempted by the ones above it. For example, while a softirq is | |
119 | running on a CPU, no other softirq will preempt it, but a hardware | |
120 | interrupt can. However, any other CPUs in the system execute | |
121 | independently. | |
1da177e4 LT |
122 | </para> |
123 | ||
124 | <para> | |
125 | We'll see a number of ways that the user context can block | |
126 | interrupts, to become truly non-preemptable. | |
127 | </para> | |
128 | ||
129 | <sect1 id="basics-usercontext"> | |
130 | <title>User Context</title> | |
131 | ||
132 | <para> | |
b6c17ea4 RR |
133 | User context is when you are coming in from a system call or other |
134 | trap: like userspace, you can be preempted by more important tasks | |
135 | and by interrupts. You can sleep, by calling | |
136 | <function>schedule()</function>. | |
1da177e4 LT |
137 | </para> |
138 | ||
139 | <note> | |
140 | <para> | |
141 | You are always in user context on module load and unload, | |
142 | and on operations on the block device layer. | |
143 | </para> | |
144 | </note> | |
145 | ||
146 | <para> | |
147 | In user context, the <varname>current</varname> pointer (indicating | |
148 | the task we are currently executing) is valid, and | |
149 | <function>in_interrupt()</function> | |
150 | (<filename>include/linux/interrupt.h</filename>) is <returnvalue>false | |
151 | </returnvalue>. | |
152 | </para> | |
153 | ||
154 | <caution> | |
155 | <para> | |
b6c17ea4 | 156 | Beware that if you have preemption or softirqs disabled |
1da177e4 LT |
157 | (see below), <function>in_interrupt()</function> will return a |
158 | false positive. | |
159 | </para> | |
160 | </caution> | |
161 | </sect1> | |
162 | ||
163 | <sect1 id="basics-hardirqs"> | |
164 | <title>Hardware Interrupts (Hard IRQs)</title> | |
165 | ||
166 | <para> | |
167 | Timer ticks, <hardware>network cards</hardware> and | |
168 | <hardware>keyboard</hardware> are examples of real | |
169 | hardware which produce interrupts at any time. The kernel runs | |
170 | interrupt handlers, which services the hardware. The kernel | |
b6c17ea4 | 171 | guarantees that this handler is never re-entered: if the same |
1da177e4 LT |
172 | interrupt arrives, it is queued (or dropped). Because it |
173 | disables interrupts, this handler has to be fast: frequently it | |
b6c17ea4 | 174 | simply acknowledges the interrupt, marks a 'software interrupt' |
1da177e4 LT |
175 | for execution and exits. |
176 | </para> | |
177 | ||
178 | <para> | |
179 | You can tell you are in a hardware interrupt, because | |
180 | <function>in_irq()</function> returns <returnvalue>true</returnvalue>. | |
181 | </para> | |
182 | <caution> | |
183 | <para> | |
184 | Beware that this will return a false positive if interrupts are disabled | |
185 | (see below). | |
186 | </para> | |
187 | </caution> | |
188 | </sect1> | |
189 | ||
190 | <sect1 id="basics-softirqs"> | |
b6c17ea4 | 191 | <title>Software Interrupt Context: Softirqs and Tasklets</title> |
1da177e4 LT |
192 | |
193 | <para> | |
194 | Whenever a system call is about to return to userspace, or a | |
b6c17ea4 | 195 | hardware interrupt handler exits, any 'software interrupts' |
1da177e4 LT |
196 | which are marked pending (usually by hardware interrupts) are |
197 | run (<filename>kernel/softirq.c</filename>). | |
198 | </para> | |
199 | ||
200 | <para> | |
201 | Much of the real interrupt handling work is done here. Early in | |
b6c17ea4 | 202 | the transition to <acronym>SMP</acronym>, there were only 'bottom |
1da177e4 LT |
203 | halves' (BHs), which didn't take advantage of multiple CPUs. Shortly |
204 | after we switched from wind-up computers made of match-sticks and snot, | |
b6c17ea4 | 205 | we abandoned this limitation and switched to 'softirqs'. |
1da177e4 LT |
206 | </para> |
207 | ||
208 | <para> | |
209 | <filename class="headerfile">include/linux/interrupt.h</filename> lists the | |
b6c17ea4 RR |
210 | different softirqs. A very important softirq is the |
211 | timer softirq (<filename | |
212 | class="headerfile">include/linux/timer.h</filename>): you can | |
213 | register to have it call functions for you in a given length of | |
214 | time. | |
1da177e4 LT |
215 | </para> |
216 | ||
217 | <para> | |
b6c17ea4 RR |
218 | Softirqs are often a pain to deal with, since the same softirq |
219 | will run simultaneously on more than one CPU. For this reason, | |
220 | tasklets (<filename | |
221 | class="headerfile">include/linux/interrupt.h</filename>) are more | |
222 | often used: they are dynamically-registrable (meaning you can have | |
223 | as many as you want), and they also guarantee that any tasklet | |
224 | will only run on one CPU at any time, although different tasklets | |
225 | can run simultaneously. | |
1da177e4 LT |
226 | </para> |
227 | <caution> | |
228 | <para> | |
b6c17ea4 | 229 | The name 'tasklet' is misleading: they have nothing to do with 'tasks', |
1da177e4 LT |
230 | and probably more to do with some bad vodka Alexey Kuznetsov had at the |
231 | time. | |
232 | </para> | |
233 | </caution> | |
234 | ||
235 | <para> | |
b6c17ea4 | 236 | You can tell you are in a softirq (or tasklet) |
1da177e4 LT |
237 | using the <function>in_softirq()</function> macro |
238 | (<filename class="headerfile">include/linux/interrupt.h</filename>). | |
239 | </para> | |
240 | <caution> | |
241 | <para> | |
242 | Beware that this will return a false positive if a bh lock (see below) | |
243 | is held. | |
244 | </para> | |
245 | </caution> | |
246 | </sect1> | |
247 | </chapter> | |
248 | ||
249 | <chapter id="basic-rules"> | |
250 | <title>Some Basic Rules</title> | |
251 | ||
252 | <variablelist> | |
253 | <varlistentry> | |
254 | <term>No memory protection</term> | |
255 | <listitem> | |
256 | <para> | |
257 | If you corrupt memory, whether in user context or | |
258 | interrupt context, the whole machine will crash. Are you | |
259 | sure you can't do what you want in userspace? | |
260 | </para> | |
261 | </listitem> | |
262 | </varlistentry> | |
263 | ||
264 | <varlistentry> | |
265 | <term>No floating point or <acronym>MMX</acronym></term> | |
266 | <listitem> | |
267 | <para> | |
268 | The <acronym>FPU</acronym> context is not saved; even in user | |
269 | context the <acronym>FPU</acronym> state probably won't | |
270 | correspond with the current process: you would mess with some | |
271 | user process' <acronym>FPU</acronym> state. If you really want | |
272 | to do this, you would have to explicitly save/restore the full | |
273 | <acronym>FPU</acronym> state (and avoid context switches). It | |
274 | is generally a bad idea; use fixed point arithmetic first. | |
275 | </para> | |
276 | </listitem> | |
277 | </varlistentry> | |
278 | ||
279 | <varlistentry> | |
280 | <term>A rigid stack limit</term> | |
281 | <listitem> | |
282 | <para> | |
b6c17ea4 RR |
283 | Depending on configuration options the kernel stack is about 3K to 6K for most 32-bit architectures: it's |
284 | about 14K on most 64-bit archs, and often shared with interrupts | |
285 | so you can't use it all. Avoid deep recursion and huge local | |
286 | arrays on the stack (allocate them dynamically instead). | |
1da177e4 LT |
287 | </para> |
288 | </listitem> | |
289 | </varlistentry> | |
290 | ||
291 | <varlistentry> | |
292 | <term>The Linux kernel is portable</term> | |
293 | <listitem> | |
294 | <para> | |
295 | Let's keep it that way. Your code should be 64-bit clean, | |
296 | and endian-independent. You should also minimize CPU | |
297 | specific stuff, e.g. inline assembly should be cleanly | |
298 | encapsulated and minimized to ease porting. Generally it | |
299 | should be restricted to the architecture-dependent part of | |
300 | the kernel tree. | |
301 | </para> | |
302 | </listitem> | |
303 | </varlistentry> | |
304 | </variablelist> | |
305 | </chapter> | |
306 | ||
307 | <chapter id="ioctls"> | |
308 | <title>ioctls: Not writing a new system call</title> | |
309 | ||
310 | <para> | |
311 | A system call generally looks like this | |
312 | </para> | |
313 | ||
314 | <programlisting> | |
315 | asmlinkage long sys_mycall(int arg) | |
316 | { | |
317 | return 0; | |
318 | } | |
319 | </programlisting> | |
320 | ||
321 | <para> | |
322 | First, in most cases you don't want to create a new system call. | |
323 | You create a character device and implement an appropriate ioctl | |
324 | for it. This is much more flexible than system calls, doesn't have | |
325 | to be entered in every architecture's | |
326 | <filename class="headerfile">include/asm/unistd.h</filename> and | |
327 | <filename>arch/kernel/entry.S</filename> file, and is much more | |
328 | likely to be accepted by Linus. | |
329 | </para> | |
330 | ||
331 | <para> | |
332 | If all your routine does is read or write some parameter, consider | |
b6c17ea4 | 333 | implementing a <function>sysfs</function> interface instead. |
1da177e4 LT |
334 | </para> |
335 | ||
336 | <para> | |
337 | Inside the ioctl you're in user context to a process. When a | |
338 | error occurs you return a negated errno (see | |
339 | <filename class="headerfile">include/linux/errno.h</filename>), | |
340 | otherwise you return <returnvalue>0</returnvalue>. | |
341 | </para> | |
342 | ||
343 | <para> | |
344 | After you slept you should check if a signal occurred: the | |
345 | Unix/Linux way of handling signals is to temporarily exit the | |
346 | system call with the <constant>-ERESTARTSYS</constant> error. The | |
347 | system call entry code will switch back to user context, process | |
348 | the signal handler and then your system call will be restarted | |
349 | (unless the user disabled that). So you should be prepared to | |
350 | process the restart, e.g. if you're in the middle of manipulating | |
351 | some data structure. | |
352 | </para> | |
353 | ||
354 | <programlisting> | |
2770f189 | 355 | if (signal_pending(current)) |
1da177e4 LT |
356 | return -ERESTARTSYS; |
357 | </programlisting> | |
358 | ||
359 | <para> | |
360 | If you're doing longer computations: first think userspace. If you | |
361 | <emphasis>really</emphasis> want to do it in kernel you should | |
362 | regularly check if you need to give up the CPU (remember there is | |
363 | cooperative multitasking per CPU). Idiom: | |
364 | </para> | |
365 | ||
366 | <programlisting> | |
367 | cond_resched(); /* Will sleep */ | |
368 | </programlisting> | |
369 | ||
370 | <para> | |
371 | A short note on interface design: the UNIX system call motto is | |
372 | "Provide mechanism not policy". | |
373 | </para> | |
374 | </chapter> | |
375 | ||
376 | <chapter id="deadlock-recipes"> | |
377 | <title>Recipes for Deadlock</title> | |
378 | ||
379 | <para> | |
380 | You cannot call any routines which may sleep, unless: | |
381 | </para> | |
382 | <itemizedlist> | |
383 | <listitem> | |
384 | <para> | |
385 | You are in user context. | |
386 | </para> | |
387 | </listitem> | |
388 | ||
389 | <listitem> | |
390 | <para> | |
391 | You do not own any spinlocks. | |
392 | </para> | |
393 | </listitem> | |
394 | ||
395 | <listitem> | |
396 | <para> | |
397 | You have interrupts enabled (actually, Andi Kleen says | |
398 | that the scheduling code will enable them for you, but | |
399 | that's probably not what you wanted). | |
400 | </para> | |
401 | </listitem> | |
402 | </itemizedlist> | |
403 | ||
404 | <para> | |
405 | Note that some functions may sleep implicitly: common ones are | |
406 | the user space access functions (*_user) and memory allocation | |
407 | functions without <symbol>GFP_ATOMIC</symbol>. | |
408 | </para> | |
409 | ||
410 | <para> | |
b6c17ea4 | 411 | You should always compile your kernel |
d902db1e | 412 | <symbol>CONFIG_DEBUG_ATOMIC_SLEEP</symbol> on, and it will warn |
b6c17ea4 RR |
413 | you if you break these rules. If you <emphasis>do</emphasis> break |
414 | the rules, you will eventually lock up your box. | |
1da177e4 LT |
415 | </para> |
416 | ||
417 | <para> | |
418 | Really. | |
419 | </para> | |
420 | </chapter> | |
421 | ||
422 | <chapter id="common-routines"> | |
423 | <title>Common Routines</title> | |
424 | ||
425 | <sect1 id="routines-printk"> | |
426 | <title> | |
427 | <function>printk()</function> | |
428 | <filename class="headerfile">include/linux/kernel.h</filename> | |
429 | </title> | |
430 | ||
431 | <para> | |
432 | <function>printk()</function> feeds kernel messages to the | |
433 | console, dmesg, and the syslog daemon. It is useful for debugging | |
434 | and reporting errors, and can be used inside interrupt context, | |
435 | but use with caution: a machine which has its console flooded with | |
436 | printk messages is unusable. It uses a format string mostly | |
437 | compatible with ANSI C printf, and C string concatenation to give | |
438 | it a first "priority" argument: | |
439 | </para> | |
440 | ||
441 | <programlisting> | |
442 | printk(KERN_INFO "i = %u\n", i); | |
443 | </programlisting> | |
444 | ||
445 | <para> | |
446 | See <filename class="headerfile">include/linux/kernel.h</filename>; | |
447 | for other KERN_ values; these are interpreted by syslog as the | |
448 | level. Special case: for printing an IP address use | |
449 | </para> | |
450 | ||
451 | <programlisting> | |
2a8aaacd TK |
452 | __be32 ipaddress; |
453 | printk(KERN_INFO "my ip: %pI4\n", &ipaddress); | |
1da177e4 LT |
454 | </programlisting> |
455 | ||
456 | <para> | |
457 | <function>printk()</function> internally uses a 1K buffer and does | |
458 | not catch overruns. Make sure that will be enough. | |
459 | </para> | |
460 | ||
461 | <note> | |
462 | <para> | |
463 | You will know when you are a real kernel hacker | |
464 | when you start typoing printf as printk in your user programs :) | |
465 | </para> | |
466 | </note> | |
467 | ||
468 | <!--- From the Lions book reader department --> | |
469 | ||
470 | <note> | |
471 | <para> | |
472 | Another sidenote: the original Unix Version 6 sources had a | |
473 | comment on top of its printf function: "Printf should not be | |
474 | used for chit-chat". You should follow that advice. | |
475 | </para> | |
476 | </note> | |
477 | </sect1> | |
478 | ||
479 | <sect1 id="routines-copy"> | |
480 | <title> | |
481 | <function>copy_[to/from]_user()</function> | |
482 | / | |
483 | <function>get_user()</function> | |
484 | / | |
485 | <function>put_user()</function> | |
486 | <filename class="headerfile">include/asm/uaccess.h</filename> | |
487 | </title> | |
488 | ||
489 | <para> | |
490 | <emphasis>[SLEEPS]</emphasis> | |
491 | </para> | |
492 | ||
493 | <para> | |
494 | <function>put_user()</function> and <function>get_user()</function> | |
495 | are used to get and put single values (such as an int, char, or | |
496 | long) from and to userspace. A pointer into userspace should | |
497 | never be simply dereferenced: data should be copied using these | |
498 | routines. Both return <constant>-EFAULT</constant> or 0. | |
499 | </para> | |
500 | <para> | |
501 | <function>copy_to_user()</function> and | |
502 | <function>copy_from_user()</function> are more general: they copy | |
503 | an arbitrary amount of data to and from userspace. | |
504 | <caution> | |
505 | <para> | |
506 | Unlike <function>put_user()</function> and | |
507 | <function>get_user()</function>, they return the amount of | |
508 | uncopied data (ie. <returnvalue>0</returnvalue> still means | |
509 | success). | |
510 | </para> | |
511 | </caution> | |
b6c17ea4 | 512 | [Yes, this moronic interface makes me cringe. The flamewar comes up every year or so. --RR.] |
1da177e4 LT |
513 | </para> |
514 | <para> | |
515 | The functions may sleep implicitly. This should never be called | |
516 | outside user context (it makes no sense), with interrupts | |
517 | disabled, or a spinlock held. | |
518 | </para> | |
519 | </sect1> | |
520 | ||
521 | <sect1 id="routines-kmalloc"> | |
522 | <title><function>kmalloc()</function>/<function>kfree()</function> | |
523 | <filename class="headerfile">include/linux/slab.h</filename></title> | |
524 | ||
525 | <para> | |
526 | <emphasis>[MAY SLEEP: SEE BELOW]</emphasis> | |
527 | </para> | |
528 | ||
529 | <para> | |
530 | These routines are used to dynamically request pointer-aligned | |
531 | chunks of memory, like malloc and free do in userspace, but | |
532 | <function>kmalloc()</function> takes an extra flag word. | |
533 | Important values: | |
534 | </para> | |
535 | ||
536 | <variablelist> | |
537 | <varlistentry> | |
538 | <term> | |
539 | <constant> | |
540 | GFP_KERNEL | |
541 | </constant> | |
542 | </term> | |
543 | <listitem> | |
544 | <para> | |
545 | May sleep and swap to free memory. Only allowed in user | |
546 | context, but is the most reliable way to allocate memory. | |
547 | </para> | |
548 | </listitem> | |
549 | </varlistentry> | |
550 | ||
551 | <varlistentry> | |
552 | <term> | |
553 | <constant> | |
554 | GFP_ATOMIC | |
555 | </constant> | |
556 | </term> | |
557 | <listitem> | |
558 | <para> | |
559 | Don't sleep. Less reliable than <constant>GFP_KERNEL</constant>, | |
560 | but may be called from interrupt context. You should | |
561 | <emphasis>really</emphasis> have a good out-of-memory | |
562 | error-handling strategy. | |
563 | </para> | |
564 | </listitem> | |
565 | </varlistentry> | |
566 | ||
567 | <varlistentry> | |
568 | <term> | |
569 | <constant> | |
570 | GFP_DMA | |
571 | </constant> | |
572 | </term> | |
573 | <listitem> | |
574 | <para> | |
575 | Allocate ISA DMA lower than 16MB. If you don't know what that | |
576 | is you don't need it. Very unreliable. | |
577 | </para> | |
578 | </listitem> | |
579 | </varlistentry> | |
580 | </variablelist> | |
581 | ||
582 | <para> | |
b6c17ea4 RR |
583 | If you see a <errorname>sleeping function called from invalid |
584 | context</errorname> warning message, then maybe you called a | |
585 | sleeping allocation function from interrupt context without | |
586 | <constant>GFP_ATOMIC</constant>. You should really fix that. | |
587 | Run, don't walk. | |
1da177e4 LT |
588 | </para> |
589 | ||
590 | <para> | |
591 | If you are allocating at least <constant>PAGE_SIZE</constant> | |
592 | (<filename class="headerfile">include/asm/page.h</filename>) bytes, | |
593 | consider using <function>__get_free_pages()</function> | |
594 | ||
595 | (<filename class="headerfile">include/linux/mm.h</filename>). It | |
596 | takes an order argument (0 for page sized, 1 for double page, 2 | |
597 | for four pages etc.) and the same memory priority flag word as | |
598 | above. | |
599 | </para> | |
600 | ||
601 | <para> | |
602 | If you are allocating more than a page worth of bytes you can use | |
603 | <function>vmalloc()</function>. It'll allocate virtual memory in | |
604 | the kernel map. This block is not contiguous in physical memory, | |
605 | but the <acronym>MMU</acronym> makes it look like it is for you | |
606 | (so it'll only look contiguous to the CPUs, not to external device | |
607 | drivers). If you really need large physically contiguous memory | |
608 | for some weird device, you have a problem: it is poorly supported | |
609 | in Linux because after some time memory fragmentation in a running | |
610 | kernel makes it hard. The best way is to allocate the block early | |
611 | in the boot process via the <function>alloc_bootmem()</function> | |
612 | routine. | |
613 | </para> | |
614 | ||
615 | <para> | |
616 | Before inventing your own cache of often-used objects consider | |
617 | using a slab cache in | |
618 | <filename class="headerfile">include/linux/slab.h</filename> | |
619 | </para> | |
620 | </sect1> | |
621 | ||
622 | <sect1 id="routines-current"> | |
623 | <title><function>current</function> | |
624 | <filename class="headerfile">include/asm/current.h</filename></title> | |
625 | ||
626 | <para> | |
627 | This global variable (really a macro) contains a pointer to | |
628 | the current task structure, so is only valid in user context. | |
629 | For example, when a process makes a system call, this will | |
630 | point to the task structure of the calling process. It is | |
631 | <emphasis>not NULL</emphasis> in interrupt context. | |
632 | </para> | |
633 | </sect1> | |
634 | ||
635 | <sect1 id="routines-udelay"> | |
b6c17ea4 | 636 | <title><function>mdelay()</function>/<function>udelay()</function> |
1da177e4 LT |
637 | <filename class="headerfile">include/asm/delay.h</filename> |
638 | <filename class="headerfile">include/linux/delay.h</filename> | |
639 | </title> | |
640 | ||
641 | <para> | |
b6c17ea4 RR |
642 | The <function>udelay()</function> and <function>ndelay()</function> functions can be used for small pauses. |
643 | Do not use large values with them as you risk | |
1da177e4 | 644 | overflow - the helper function <function>mdelay()</function> is useful |
b6c17ea4 | 645 | here, or consider <function>msleep()</function>. |
1da177e4 LT |
646 | </para> |
647 | </sect1> | |
648 | ||
649 | <sect1 id="routines-endian"> | |
650 | <title><function>cpu_to_be32()</function>/<function>be32_to_cpu()</function>/<function>cpu_to_le32()</function>/<function>le32_to_cpu()</function> | |
651 | <filename class="headerfile">include/asm/byteorder.h</filename> | |
652 | </title> | |
653 | ||
654 | <para> | |
655 | The <function>cpu_to_be32()</function> family (where the "32" can | |
656 | be replaced by 64 or 16, and the "be" can be replaced by "le") are | |
657 | the general way to do endian conversions in the kernel: they | |
658 | return the converted value. All variations supply the reverse as | |
659 | well: <function>be32_to_cpu()</function>, etc. | |
660 | </para> | |
661 | ||
662 | <para> | |
663 | There are two major variations of these functions: the pointer | |
664 | variation, such as <function>cpu_to_be32p()</function>, which take | |
665 | a pointer to the given type, and return the converted value. The | |
666 | other variation is the "in-situ" family, such as | |
667 | <function>cpu_to_be32s()</function>, which convert value referred | |
668 | to by the pointer, and return void. | |
669 | </para> | |
670 | </sect1> | |
671 | ||
672 | <sect1 id="routines-local-irqs"> | |
673 | <title><function>local_irq_save()</function>/<function>local_irq_restore()</function> | |
674 | <filename class="headerfile">include/asm/system.h</filename> | |
675 | </title> | |
676 | ||
677 | <para> | |
678 | These routines disable hard interrupts on the local CPU, and | |
679 | restore them. They are reentrant; saving the previous state in | |
680 | their one <varname>unsigned long flags</varname> argument. If you | |
681 | know that interrupts are enabled, you can simply use | |
682 | <function>local_irq_disable()</function> and | |
683 | <function>local_irq_enable()</function>. | |
684 | </para> | |
685 | </sect1> | |
686 | ||
687 | <sect1 id="routines-softirqs"> | |
688 | <title><function>local_bh_disable()</function>/<function>local_bh_enable()</function> | |
689 | <filename class="headerfile">include/linux/interrupt.h</filename></title> | |
690 | ||
691 | <para> | |
692 | These routines disable soft interrupts on the local CPU, and | |
693 | restore them. They are reentrant; if soft interrupts were | |
694 | disabled before, they will still be disabled after this pair | |
b6c17ea4 RR |
695 | of functions has been called. They prevent softirqs and tasklets |
696 | from running on the current CPU. | |
1da177e4 LT |
697 | </para> |
698 | </sect1> | |
699 | ||
700 | <sect1 id="routines-processorids"> | |
701 | <title><function>smp_processor_id</function>() | |
702 | <filename class="headerfile">include/asm/smp.h</filename></title> | |
703 | ||
704 | <para> | |
b6c17ea4 RR |
705 | <function>get_cpu()</function> disables preemption (so you won't |
706 | suddenly get moved to another CPU) and returns the current | |
707 | processor number, between 0 and <symbol>NR_CPUS</symbol>. Note | |
708 | that the CPU numbers are not necessarily continuous. You return | |
709 | it again with <function>put_cpu()</function> when you are done. | |
710 | </para> | |
711 | <para> | |
712 | If you know you cannot be preempted by another task (ie. you are | |
713 | in interrupt context, or have preemption disabled) you can use | |
714 | smp_processor_id(). | |
1da177e4 LT |
715 | </para> |
716 | </sect1> | |
717 | ||
718 | <sect1 id="routines-init"> | |
719 | <title><type>__init</type>/<type>__exit</type>/<type>__initdata</type> | |
720 | <filename class="headerfile">include/linux/init.h</filename></title> | |
721 | ||
722 | <para> | |
723 | After boot, the kernel frees up a special section; functions | |
724 | marked with <type>__init</type> and data structures marked with | |
b6c17ea4 RR |
725 | <type>__initdata</type> are dropped after boot is complete: similarly |
726 | modules discard this memory after initialization. <type>__exit</type> | |
1da177e4 LT |
727 | is used to declare a function which is only required on exit: the |
728 | function will be dropped if this file is not compiled as a module. | |
729 | See the header file for use. Note that it makes no sense for a function | |
730 | marked with <type>__init</type> to be exported to modules with | |
731 | <function>EXPORT_SYMBOL()</function> - this will break. | |
732 | </para> | |
1da177e4 LT |
733 | |
734 | </sect1> | |
735 | ||
736 | <sect1 id="routines-init-again"> | |
737 | <title><function>__initcall()</function>/<function>module_init()</function> | |
738 | <filename class="headerfile">include/linux/init.h</filename></title> | |
739 | <para> | |
740 | Many parts of the kernel are well served as a module | |
741 | (dynamically-loadable parts of the kernel). Using the | |
742 | <function>module_init()</function> and | |
743 | <function>module_exit()</function> macros it is easy to write code | |
744 | without #ifdefs which can operate both as a module or built into | |
745 | the kernel. | |
746 | </para> | |
747 | ||
748 | <para> | |
749 | The <function>module_init()</function> macro defines which | |
750 | function is to be called at module insertion time (if the file is | |
751 | compiled as a module), or at boot time: if the file is not | |
752 | compiled as a module the <function>module_init()</function> macro | |
753 | becomes equivalent to <function>__initcall()</function>, which | |
754 | through linker magic ensures that the function is called on boot. | |
755 | </para> | |
756 | ||
757 | <para> | |
758 | The function can return a negative error number to cause | |
759 | module loading to fail (unfortunately, this has no effect if | |
b6c17ea4 RR |
760 | the module is compiled into the kernel). This function is |
761 | called in user context with interrupts enabled, so it can sleep. | |
1da177e4 LT |
762 | </para> |
763 | </sect1> | |
764 | ||
765 | <sect1 id="routines-moduleexit"> | |
766 | <title> <function>module_exit()</function> | |
767 | <filename class="headerfile">include/linux/init.h</filename> </title> | |
768 | ||
769 | <para> | |
770 | This macro defines the function to be called at module removal | |
771 | time (or never, in the case of the file compiled into the | |
772 | kernel). It will only be called if the module usage count has | |
773 | reached zero. This function can also sleep, but cannot fail: | |
774 | everything must be cleaned up by the time it returns. | |
775 | </para> | |
b6c17ea4 RR |
776 | |
777 | <para> | |
778 | Note that this macro is optional: if it is not present, your | |
779 | module will not be removable (except for 'rmmod -f'). | |
780 | </para> | |
781 | </sect1> | |
782 | ||
783 | <sect1 id="routines-module-use-counters"> | |
784 | <title> <function>try_module_get()</function>/<function>module_put()</function> | |
785 | <filename class="headerfile">include/linux/module.h</filename></title> | |
786 | ||
787 | <para> | |
788 | These manipulate the module usage count, to protect against | |
789 | removal (a module also can't be removed if another module uses one | |
790 | of its exported symbols: see below). Before calling into module | |
791 | code, you should call <function>try_module_get()</function> on | |
792 | that module: if it fails, then the module is being removed and you | |
793 | should act as if it wasn't there. Otherwise, you can safely enter | |
794 | the module, and call <function>module_put()</function> when you're | |
795 | finished. | |
796 | </para> | |
797 | ||
798 | <para> | |
799 | Most registerable structures have an | |
800 | <structfield>owner</structfield> field, such as in the | |
801 | <structname>file_operations</structname> structure. Set this field | |
802 | to the macro <symbol>THIS_MODULE</symbol>. | |
803 | </para> | |
1da177e4 LT |
804 | </sect1> |
805 | ||
806 | <!-- add info on new-style module refcounting here --> | |
807 | </chapter> | |
808 | ||
809 | <chapter id="queues"> | |
810 | <title>Wait Queues | |
811 | <filename class="headerfile">include/linux/wait.h</filename> | |
812 | </title> | |
813 | <para> | |
814 | <emphasis>[SLEEPS]</emphasis> | |
815 | </para> | |
816 | ||
817 | <para> | |
818 | A wait queue is used to wait for someone to wake you up when a | |
819 | certain condition is true. They must be used carefully to ensure | |
820 | there is no race condition. You declare a | |
821 | <type>wait_queue_head_t</type>, and then processes which want to | |
822 | wait for that condition declare a <type>wait_queue_t</type> | |
823 | referring to themselves, and place that in the queue. | |
824 | </para> | |
825 | ||
826 | <sect1 id="queue-declaring"> | |
827 | <title>Declaring</title> | |
828 | ||
829 | <para> | |
830 | You declare a <type>wait_queue_head_t</type> using the | |
831 | <function>DECLARE_WAIT_QUEUE_HEAD()</function> macro, or using the | |
832 | <function>init_waitqueue_head()</function> routine in your | |
833 | initialization code. | |
834 | </para> | |
835 | </sect1> | |
836 | ||
837 | <sect1 id="queue-waitqueue"> | |
838 | <title>Queuing</title> | |
839 | ||
840 | <para> | |
841 | Placing yourself in the waitqueue is fairly complex, because you | |
842 | must put yourself in the queue before checking the condition. | |
843 | There is a macro to do this: | |
844 | <function>wait_event_interruptible()</function> | |
845 | ||
b6c17ea4 | 846 | <filename class="headerfile">include/linux/wait.h</filename> The |
1da177e4 LT |
847 | first argument is the wait queue head, and the second is an |
848 | expression which is evaluated; the macro returns | |
849 | <returnvalue>0</returnvalue> when this expression is true, or | |
850 | <returnvalue>-ERESTARTSYS</returnvalue> if a signal is received. | |
851 | The <function>wait_event()</function> version ignores signals. | |
852 | </para> | |
853 | <para> | |
854 | Do not use the <function>sleep_on()</function> function family - | |
855 | it is very easy to accidentally introduce races; almost certainly | |
856 | one of the <function>wait_event()</function> family will do, or a | |
857 | loop around <function>schedule_timeout()</function>. If you choose | |
858 | to loop around <function>schedule_timeout()</function> remember | |
859 | you must set the task state (with | |
860 | <function>set_current_state()</function>) on each iteration to avoid | |
861 | busy-looping. | |
862 | </para> | |
863 | ||
864 | </sect1> | |
865 | ||
866 | <sect1 id="queue-waking"> | |
867 | <title>Waking Up Queued Tasks</title> | |
868 | ||
869 | <para> | |
870 | Call <function>wake_up()</function> | |
871 | ||
b6c17ea4 | 872 | <filename class="headerfile">include/linux/wait.h</filename>;, |
1da177e4 LT |
873 | which will wake up every process in the queue. The exception is |
874 | if one has <constant>TASK_EXCLUSIVE</constant> set, in which case | |
b6c17ea4 RR |
875 | the remainder of the queue will not be woken. There are other variants |
876 | of this basic function available in the same header. | |
1da177e4 LT |
877 | </para> |
878 | </sect1> | |
879 | </chapter> | |
880 | ||
881 | <chapter id="atomic-ops"> | |
882 | <title>Atomic Operations</title> | |
883 | ||
884 | <para> | |
885 | Certain operations are guaranteed atomic on all platforms. The | |
886 | first class of operations work on <type>atomic_t</type> | |
887 | ||
888 | <filename class="headerfile">include/asm/atomic.h</filename>; this | |
b6c17ea4 | 889 | contains a signed integer (at least 32 bits long), and you must use |
1da177e4 LT |
890 | these functions to manipulate or read atomic_t variables. |
891 | <function>atomic_read()</function> and | |
892 | <function>atomic_set()</function> get and set the counter, | |
893 | <function>atomic_add()</function>, | |
894 | <function>atomic_sub()</function>, | |
895 | <function>atomic_inc()</function>, | |
896 | <function>atomic_dec()</function>, and | |
897 | <function>atomic_dec_and_test()</function> (returns | |
898 | <returnvalue>true</returnvalue> if it was decremented to zero). | |
899 | </para> | |
900 | ||
901 | <para> | |
902 | Yes. It returns <returnvalue>true</returnvalue> (i.e. != 0) if the | |
903 | atomic variable is zero. | |
904 | </para> | |
905 | ||
906 | <para> | |
907 | Note that these functions are slower than normal arithmetic, and | |
b6c17ea4 | 908 | so should not be used unnecessarily. |
1da177e4 LT |
909 | </para> |
910 | ||
911 | <para> | |
b6c17ea4 RR |
912 | The second class of atomic operations is atomic bit operations on an |
913 | <type>unsigned long</type>, defined in | |
1da177e4 LT |
914 | |
915 | <filename class="headerfile">include/linux/bitops.h</filename>. These | |
916 | operations generally take a pointer to the bit pattern, and a bit | |
917 | number: 0 is the least significant bit. | |
918 | <function>set_bit()</function>, <function>clear_bit()</function> | |
919 | and <function>change_bit()</function> set, clear, and flip the | |
920 | given bit. <function>test_and_set_bit()</function>, | |
921 | <function>test_and_clear_bit()</function> and | |
922 | <function>test_and_change_bit()</function> do the same thing, | |
923 | except return true if the bit was previously set; these are | |
b6c17ea4 | 924 | particularly useful for atomically setting flags. |
1da177e4 LT |
925 | </para> |
926 | ||
927 | <para> | |
928 | It is possible to call these operations with bit indices greater | |
929 | than BITS_PER_LONG. The resulting behavior is strange on big-endian | |
930 | platforms though so it is a good idea not to do this. | |
931 | </para> | |
1da177e4 LT |
932 | </chapter> |
933 | ||
934 | <chapter id="symbols"> | |
935 | <title>Symbols</title> | |
936 | ||
937 | <para> | |
938 | Within the kernel proper, the normal linking rules apply | |
939 | (ie. unless a symbol is declared to be file scope with the | |
940 | <type>static</type> keyword, it can be used anywhere in the | |
941 | kernel). However, for modules, a special exported symbol table is | |
942 | kept which limits the entry points to the kernel proper. Modules | |
943 | can also export symbols. | |
944 | </para> | |
945 | ||
946 | <sect1 id="sym-exportsymbols"> | |
947 | <title><function>EXPORT_SYMBOL()</function> | |
df63447f | 948 | <filename class="headerfile">include/linux/export.h</filename></title> |
1da177e4 LT |
949 | |
950 | <para> | |
b6c17ea4 RR |
951 | This is the classic method of exporting a symbol: dynamically |
952 | loaded modules will be able to use the symbol as normal. | |
1da177e4 LT |
953 | </para> |
954 | </sect1> | |
955 | ||
956 | <sect1 id="sym-exportsymbols-gpl"> | |
957 | <title><function>EXPORT_SYMBOL_GPL()</function> | |
df63447f | 958 | <filename class="headerfile">include/linux/export.h</filename></title> |
1da177e4 LT |
959 | |
960 | <para> | |
961 | Similar to <function>EXPORT_SYMBOL()</function> except that the | |
962 | symbols exported by <function>EXPORT_SYMBOL_GPL()</function> can | |
963 | only be seen by modules with a | |
964 | <function>MODULE_LICENSE()</function> that specifies a GPL | |
b6c17ea4 RR |
965 | compatible license. It implies that the function is considered |
966 | an internal implementation issue, and not really an interface. | |
1da177e4 LT |
967 | </para> |
968 | </sect1> | |
969 | </chapter> | |
970 | ||
971 | <chapter id="conventions"> | |
972 | <title>Routines and Conventions</title> | |
973 | ||
974 | <sect1 id="conventions-doublelinkedlist"> | |
975 | <title>Double-linked lists | |
976 | <filename class="headerfile">include/linux/list.h</filename></title> | |
977 | ||
978 | <para> | |
b6c17ea4 RR |
979 | There used to be three sets of linked-list routines in the kernel |
980 | headers, but this one is the winner. If you don't have some | |
981 | particular pressing need for a single list, it's a good choice. | |
982 | </para> | |
983 | ||
984 | <para> | |
985 | In particular, <function>list_for_each_entry</function> is useful. | |
1da177e4 LT |
986 | </para> |
987 | </sect1> | |
988 | ||
989 | <sect1 id="convention-returns"> | |
990 | <title>Return Conventions</title> | |
991 | ||
992 | <para> | |
993 | For code called in user context, it's very common to defy C | |
994 | convention, and return <returnvalue>0</returnvalue> for success, | |
995 | and a negative error number | |
996 | (eg. <returnvalue>-EFAULT</returnvalue>) for failure. This can be | |
b6c17ea4 | 997 | unintuitive at first, but it's fairly widespread in the kernel. |
1da177e4 LT |
998 | </para> |
999 | ||
1000 | <para> | |
b6c17ea4 | 1001 | Using <function>ERR_PTR()</function> |
1da177e4 | 1002 | |
b6c17ea4 | 1003 | <filename class="headerfile">include/linux/err.h</filename>; to |
1da177e4 LT |
1004 | encode a negative error number into a pointer, and |
1005 | <function>IS_ERR()</function> and <function>PTR_ERR()</function> | |
1006 | to get it back out again: avoids a separate pointer parameter for | |
1007 | the error number. Icky, but in a good way. | |
1008 | </para> | |
1009 | </sect1> | |
1010 | ||
1011 | <sect1 id="conventions-borkedcompile"> | |
1012 | <title>Breaking Compilation</title> | |
1013 | ||
1014 | <para> | |
1015 | Linus and the other developers sometimes change function or | |
1016 | structure names in development kernels; this is not done just to | |
1017 | keep everyone on their toes: it reflects a fundamental change | |
1018 | (eg. can no longer be called with interrupts on, or does extra | |
1019 | checks, or doesn't do checks which were caught before). Usually | |
1020 | this is accompanied by a fairly complete note to the linux-kernel | |
1021 | mailing list; search the archive. Simply doing a global replace | |
1022 | on the file usually makes things <emphasis>worse</emphasis>. | |
1023 | </para> | |
1024 | </sect1> | |
1025 | ||
1026 | <sect1 id="conventions-initialising"> | |
1027 | <title>Initializing structure members</title> | |
1028 | ||
1029 | <para> | |
1030 | The preferred method of initializing structures is to use | |
1031 | designated initialisers, as defined by ISO C99, eg: | |
1032 | </para> | |
1033 | <programlisting> | |
1034 | static struct block_device_operations opt_fops = { | |
1035 | .open = opt_open, | |
1036 | .release = opt_release, | |
1037 | .ioctl = opt_ioctl, | |
1038 | .check_media_change = opt_media_change, | |
1039 | }; | |
1040 | </programlisting> | |
1041 | <para> | |
1042 | This makes it easy to grep for, and makes it clear which | |
1043 | structure fields are set. You should do this because it looks | |
1044 | cool. | |
1045 | </para> | |
1046 | </sect1> | |
1047 | ||
1048 | <sect1 id="conventions-gnu-extns"> | |
1049 | <title>GNU Extensions</title> | |
1050 | ||
1051 | <para> | |
1052 | GNU Extensions are explicitly allowed in the Linux kernel. | |
1053 | Note that some of the more complex ones are not very well | |
1054 | supported, due to lack of general use, but the following are | |
1055 | considered standard (see the GCC info page section "C | |
1056 | Extensions" for more details - Yes, really the info page, the | |
b6c17ea4 | 1057 | man page is only a short summary of the stuff in info). |
1da177e4 LT |
1058 | </para> |
1059 | <itemizedlist> | |
1060 | <listitem> | |
1061 | <para> | |
1062 | Inline functions | |
1063 | </para> | |
1064 | </listitem> | |
1065 | <listitem> | |
1066 | <para> | |
1067 | Statement expressions (ie. the ({ and }) constructs). | |
1068 | </para> | |
1069 | </listitem> | |
1070 | <listitem> | |
1071 | <para> | |
1072 | Declaring attributes of a function / variable / type | |
1073 | (__attribute__) | |
1074 | </para> | |
1075 | </listitem> | |
1076 | <listitem> | |
1077 | <para> | |
1078 | typeof | |
1079 | </para> | |
1080 | </listitem> | |
1081 | <listitem> | |
1082 | <para> | |
1083 | Zero length arrays | |
1084 | </para> | |
1085 | </listitem> | |
1086 | <listitem> | |
1087 | <para> | |
1088 | Macro varargs | |
1089 | </para> | |
1090 | </listitem> | |
1091 | <listitem> | |
1092 | <para> | |
1093 | Arithmetic on void pointers | |
1094 | </para> | |
1095 | </listitem> | |
1096 | <listitem> | |
1097 | <para> | |
1098 | Non-Constant initializers | |
1099 | </para> | |
1100 | </listitem> | |
1101 | <listitem> | |
1102 | <para> | |
1103 | Assembler Instructions (not outside arch/ and include/asm/) | |
1104 | </para> | |
1105 | </listitem> | |
1106 | <listitem> | |
1107 | <para> | |
653c0316 | 1108 | Function names as strings (__func__). |
1da177e4 LT |
1109 | </para> |
1110 | </listitem> | |
1111 | <listitem> | |
1112 | <para> | |
1113 | __builtin_constant_p() | |
1114 | </para> | |
1115 | </listitem> | |
1116 | </itemizedlist> | |
1117 | ||
1118 | <para> | |
1119 | Be wary when using long long in the kernel, the code gcc generates for | |
1120 | it is horrible and worse: division and multiplication does not work | |
1121 | on i386 because the GCC runtime functions for it are missing from | |
1122 | the kernel environment. | |
1123 | </para> | |
1124 | ||
1125 | <!-- FIXME: add a note about ANSI aliasing cleanness --> | |
1126 | </sect1> | |
1127 | ||
1128 | <sect1 id="conventions-cplusplus"> | |
1129 | <title>C++</title> | |
1130 | ||
1131 | <para> | |
1132 | Using C++ in the kernel is usually a bad idea, because the | |
1133 | kernel does not provide the necessary runtime environment | |
1134 | and the include files are not tested for it. It is still | |
1135 | possible, but not recommended. If you really want to do | |
1136 | this, forget about exceptions at least. | |
1137 | </para> | |
1138 | </sect1> | |
1139 | ||
1140 | <sect1 id="conventions-ifdef"> | |
1141 | <title>#if</title> | |
1142 | ||
1143 | <para> | |
1144 | It is generally considered cleaner to use macros in header files | |
1145 | (or at the top of .c files) to abstract away functions rather than | |
1146 | using `#if' pre-processor statements throughout the source code. | |
1147 | </para> | |
1148 | </sect1> | |
1149 | </chapter> | |
1150 | ||
1151 | <chapter id="submitting"> | |
1152 | <title>Putting Your Stuff in the Kernel</title> | |
1153 | ||
1154 | <para> | |
1155 | In order to get your stuff into shape for official inclusion, or | |
1156 | even to make a neat patch, there's administrative work to be | |
1157 | done: | |
1158 | </para> | |
1159 | <itemizedlist> | |
1160 | <listitem> | |
1161 | <para> | |
1162 | Figure out whose pond you've been pissing in. Look at the top of | |
1163 | the source files, inside the <filename>MAINTAINERS</filename> | |
1164 | file, and last of all in the <filename>CREDITS</filename> file. | |
1165 | You should coordinate with this person to make sure you're not | |
1166 | duplicating effort, or trying something that's already been | |
1167 | rejected. | |
1168 | </para> | |
1169 | ||
1170 | <para> | |
1171 | Make sure you put your name and EMail address at the top of | |
1172 | any files you create or mangle significantly. This is the | |
1173 | first place people will look when they find a bug, or when | |
1174 | <emphasis>they</emphasis> want to make a change. | |
1175 | </para> | |
1176 | </listitem> | |
1177 | ||
1178 | <listitem> | |
1179 | <para> | |
1180 | Usually you want a configuration option for your kernel hack. | |
b6c17ea4 RR |
1181 | Edit <filename>Kconfig</filename> in the appropriate directory. |
1182 | The Config language is simple to use by cut and paste, and there's | |
1183 | complete documentation in | |
1184 | <filename>Documentation/kbuild/kconfig-language.txt</filename>. | |
1da177e4 LT |
1185 | </para> |
1186 | ||
1da177e4 | 1187 | <para> |
b6c17ea4 RR |
1188 | In your description of the option, make sure you address both the |
1189 | expert user and the user who knows nothing about your feature. Mention | |
1190 | incompatibilities and issues here. <emphasis> Definitely | |
1191 | </emphasis> end your description with <quote> if in doubt, say N | |
1192 | </quote> (or, occasionally, `Y'); this is for people who have no | |
1193 | idea what you are talking about. | |
1da177e4 LT |
1194 | </para> |
1195 | </listitem> | |
1196 | ||
1197 | <listitem> | |
1198 | <para> | |
b6c17ea4 RR |
1199 | Edit the <filename>Makefile</filename>: the CONFIG variables are |
1200 | exported here so you can usually just add a "obj-$(CONFIG_xxx) += | |
1201 | xxx.o" line. The syntax is documented in | |
1202 | <filename>Documentation/kbuild/makefiles.txt</filename>. | |
1da177e4 LT |
1203 | </para> |
1204 | </listitem> | |
1205 | ||
1206 | <listitem> | |
1207 | <para> | |
1208 | Put yourself in <filename>CREDITS</filename> if you've done | |
1209 | something noteworthy, usually beyond a single file (your name | |
1210 | should be at the top of the source files anyway). | |
1211 | <filename>MAINTAINERS</filename> means you want to be consulted | |
1212 | when changes are made to a subsystem, and hear about bugs; it | |
1213 | implies a more-than-passing commitment to some part of the code. | |
1214 | </para> | |
1215 | </listitem> | |
1216 | ||
1217 | <listitem> | |
1218 | <para> | |
1219 | Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename> | |
1220 | and possibly <filename>Documentation/SubmittingDrivers</filename>. | |
1221 | </para> | |
1222 | </listitem> | |
1223 | </itemizedlist> | |
1224 | </chapter> | |
1225 | ||
1226 | <chapter id="cantrips"> | |
1227 | <title>Kernel Cantrips</title> | |
1228 | ||
1229 | <para> | |
1230 | Some favorites from browsing the source. Feel free to add to this | |
1231 | list. | |
1232 | </para> | |
1233 | ||
1234 | <para> | |
a1a739c5 | 1235 | <filename>arch/x86/include/asm/delay.h:</filename> |
1da177e4 LT |
1236 | </para> |
1237 | <programlisting> | |
b6c17ea4 RR |
1238 | #define ndelay(n) (__builtin_constant_p(n) ? \ |
1239 | ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \ | |
1240 | __ndelay(n)) | |
1da177e4 LT |
1241 | </programlisting> |
1242 | ||
1243 | <para> | |
1244 | <filename>include/linux/fs.h</filename>: | |
1245 | </para> | |
1246 | <programlisting> | |
1247 | /* | |
1248 | * Kernel pointers have redundant information, so we can use a | |
1249 | * scheme where we can return either an error code or a dentry | |
1250 | * pointer with the same return value. | |
1251 | * | |
1252 | * This should be a per-architecture thing, to allow different | |
1253 | * error and pointer decisions. | |
1254 | */ | |
1255 | #define ERR_PTR(err) ((void *)((long)(err))) | |
1256 | #define PTR_ERR(ptr) ((long)(ptr)) | |
1257 | #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000)) | |
1258 | </programlisting> | |
1259 | ||
1260 | <para> | |
a1a739c5 | 1261 | <filename>arch/x86/include/asm/uaccess_32.h:</filename> |
1da177e4 LT |
1262 | </para> |
1263 | ||
1264 | <programlisting> | |
1265 | #define copy_to_user(to,from,n) \ | |
1266 | (__builtin_constant_p(n) ? \ | |
1267 | __constant_copy_to_user((to),(from),(n)) : \ | |
1268 | __generic_copy_to_user((to),(from),(n))) | |
1269 | </programlisting> | |
1270 | ||
1271 | <para> | |
1272 | <filename>arch/sparc/kernel/head.S:</filename> | |
1273 | </para> | |
1274 | ||
1275 | <programlisting> | |
1276 | /* | |
1277 | * Sun people can't spell worth damn. "compatability" indeed. | |
1278 | * At least we *know* we can't spell, and use a spell-checker. | |
1279 | */ | |
1280 | ||
1281 | /* Uh, actually Linus it is I who cannot spell. Too much murky | |
1282 | * Sparc assembly will do this to ya. | |
1283 | */ | |
1284 | C_LABEL(cputypvar): | |
c94bed8e | 1285 | .asciz "compatibility" |
1da177e4 LT |
1286 | |
1287 | /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */ | |
1288 | .align 4 | |
1289 | C_LABEL(cputypvar_sun4m): | |
1290 | .asciz "compatible" | |
1291 | </programlisting> | |
1292 | ||
1293 | <para> | |
1294 | <filename>arch/sparc/lib/checksum.S:</filename> | |
1295 | </para> | |
1296 | ||
1297 | <programlisting> | |
1298 | /* Sun, you just can't beat me, you just can't. Stop trying, | |
1299 | * give up. I'm serious, I am going to kick the living shit | |
1300 | * out of you, game over, lights out. | |
1301 | */ | |
1302 | </programlisting> | |
1303 | </chapter> | |
1304 | ||
1305 | <chapter id="credits"> | |
1306 | <title>Thanks</title> | |
1307 | ||
1308 | <para> | |
1309 | Thanks to Andi Kleen for the idea, answering my questions, fixing | |
1310 | my mistakes, filling content, etc. Philipp Rumpf for more spelling | |
1311 | and clarity fixes, and some excellent non-obvious points. Werner | |
1312 | Almesberger for giving me a great summary of | |
1313 | <function>disable_irq()</function>, and Jes Sorensen and Andrea | |
1314 | Arcangeli added caveats. Michael Elizabeth Chastain for checking | |
1315 | and adding to the Configure section. <!-- Rusty insisted on this | |
1316 | bit; I didn't do it! --> Telsa Gwynne for teaching me DocBook. | |
1317 | </para> | |
1318 | </chapter> | |
1319 | </book> | |
1320 |