Pull sn-features into release branch
[linux-2.6] / Documentation / DocBook / kernel-hacking.tmpl
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>
11     <firstname>Rusty</firstname>
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>
22    <year>2005</year>
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>
66    Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux
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>
98      not associated with any process, serving a softirq or tasklet;
99     </para>
100    </listitem>
101
102    <listitem>
103     <para>
104      running in kernel space, associated with a process (user context);
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>
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.
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>
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>.
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>
156      Beware that if you have preemption or softirqs disabled
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
171     guarantees that this handler is never re-entered: if the same
172     interrupt arrives, it is queued (or dropped).  Because it
173     disables interrupts, this handler has to be fast: frequently it
174     simply acknowledges the interrupt, marks a 'software interrupt'
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">
191    <title>Software Interrupt Context: Softirqs and Tasklets</title>
192
193    <para>
194     Whenever a system call is about to return to userspace, or a
195     hardware interrupt handler exits, any 'software interrupts'
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
202     the transition to <acronym>SMP</acronym>, there were only 'bottom
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,
205     we abandoned this limitation and switched to 'softirqs'.
206    </para>
207
208    <para>
209     <filename class="headerfile">include/linux/interrupt.h</filename> lists the
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.
215    </para>
216
217    <para>
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.
226    </para>
227    <caution>
228     <para>
229      The name 'tasklet' is misleading: they have nothing to do with 'tasks',
230      and probably more to do with some bad vodka Alexey Kuznetsov had at the 
231      time.
232     </para>
233    </caution>
234
235    <para>
236     You can tell you are in a softirq (or tasklet)
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>
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).
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
333    implementing a <function>sysfs</function> interface instead.
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>
355 if (signal_pending()) 
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>
411    You should always compile your kernel
412    <symbol>CONFIG_DEBUG_SPINLOCK_SLEEP</symbol> on, and it will warn
413    you if you break these rules.  If you <emphasis>do</emphasis> break
414    the rules, you will eventually lock up your box.
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>
452 __u32 ipaddress;
453 printk(KERN_INFO "my ip: %d.%d.%d.%d\n", NIPQUAD(ipaddress));
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>
512     [Yes, this moronic interface makes me cringe.  The flamewar comes up every year or so. --RR.]
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>
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.
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">
636    <title><function>mdelay()</function>/<function>udelay()</function>
637      <filename class="headerfile">include/asm/delay.h</filename>
638      <filename class="headerfile">include/linux/delay.h</filename>
639    </title>
640
641    <para>
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
644     overflow - the helper function <function>mdelay()</function> is useful
645     here, or consider <function>msleep()</function>.
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
695     of functions has been called.  They prevent softirqs and tasklets
696     from running on the current CPU.
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>
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().
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
725     <type>__initdata</type> are dropped after boot is complete: similarly
726     modules discard this memory after initialization.  <type>__exit</type>
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>
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
760     the module is compiled into the kernel).  This function is
761     called in user context with interrupts enabled, so it can sleep.
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>
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>
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
846     <filename class="headerfile">include/linux/wait.h</filename> The
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
872     <filename class="headerfile">include/linux/wait.h</filename>;,
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
875     the remainder of the queue will not be woken.  There are other variants
876     of this basic function available in the same header.
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
889    contains a signed integer (at least 32 bits long), and you must use
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
908    so should not be used unnecessarily.
909   </para>
910
911   <para>
912    The second class of atomic operations is atomic bit operations on an
913    <type>unsigned long</type>, defined in
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
924    particularly useful for atomically setting flags.
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>
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>
948     <filename class="headerfile">include/linux/module.h</filename></title>
949
950    <para>
951     This is the classic method of exporting a symbol: dynamically
952     loaded modules will be able to use the symbol as normal.
953    </para>
954   </sect1>
955
956   <sect1 id="sym-exportsymbols-gpl">
957    <title><function>EXPORT_SYMBOL_GPL()</function>
958     <filename class="headerfile">include/linux/module.h</filename></title>
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
965     compatible license.  It implies that the function is considered
966     an internal implementation issue, and not really an interface.
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>
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.
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
997     unintuitive at first, but it's fairly widespread in the kernel.
998    </para>
999
1000    <para>
1001     Using <function>ERR_PTR()</function>
1002
1003     <filename class="headerfile">include/linux/err.h</filename>; to
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
1057     man page is only a short summary of the stuff in info).
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>
1108       Function names as strings (__func__).
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>&num;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.
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>.
1185     </para>
1186
1187     <para>
1188      You may well want to make your CONFIG option only visible if
1189      <symbol>CONFIG_EXPERIMENTAL</symbol> is enabled: this serves as a
1190      warning to users.  There many other fancy things you can do: see
1191      the various <filename>Kconfig</filename> files for ideas.
1192     </para>
1193
1194     <para>
1195      In your description of the option, make sure you address both the
1196      expert user and the user who knows nothing about your feature.  Mention
1197      incompatibilities and issues here.  <emphasis> Definitely
1198      </emphasis> end your description with <quote> if in doubt, say N
1199      </quote> (or, occasionally, `Y'); this is for people who have no
1200      idea what you are talking about.
1201     </para>
1202    </listitem>
1203
1204    <listitem>
1205     <para>
1206      Edit the <filename>Makefile</filename>: the CONFIG variables are
1207      exported here so you can usually just add a "obj-$(CONFIG_xxx) +=
1208      xxx.o" line.  The syntax is documented in
1209      <filename>Documentation/kbuild/makefiles.txt</filename>.
1210     </para>
1211    </listitem>
1212
1213    <listitem>
1214     <para>
1215      Put yourself in <filename>CREDITS</filename> if you've done
1216      something noteworthy, usually beyond a single file (your name
1217      should be at the top of the source files anyway).
1218      <filename>MAINTAINERS</filename> means you want to be consulted
1219      when changes are made to a subsystem, and hear about bugs; it
1220      implies a more-than-passing commitment to some part of the code.
1221     </para>
1222    </listitem>
1223    
1224    <listitem>
1225     <para>
1226      Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename>
1227      and possibly <filename>Documentation/SubmittingDrivers</filename>.
1228     </para>
1229    </listitem>
1230   </itemizedlist>
1231  </chapter>
1232
1233  <chapter id="cantrips">
1234   <title>Kernel Cantrips</title>
1235
1236   <para>
1237    Some favorites from browsing the source.  Feel free to add to this
1238    list.
1239   </para>
1240
1241   <para>
1242    <filename>include/asm-i386/delay.h:</filename>
1243   </para>
1244   <programlisting>
1245 #define ndelay(n) (__builtin_constant_p(n) ? \
1246         ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
1247         __ndelay(n))
1248   </programlisting>
1249
1250   <para>
1251    <filename>include/linux/fs.h</filename>:
1252   </para>
1253   <programlisting>
1254 /*
1255  * Kernel pointers have redundant information, so we can use a
1256  * scheme where we can return either an error code or a dentry
1257  * pointer with the same return value.
1258  *
1259  * This should be a per-architecture thing, to allow different
1260  * error and pointer decisions.
1261  */
1262  #define ERR_PTR(err)    ((void *)((long)(err)))
1263  #define PTR_ERR(ptr)    ((long)(ptr))
1264  #define IS_ERR(ptr)     ((unsigned long)(ptr) > (unsigned long)(-1000))
1265 </programlisting>
1266
1267   <para>
1268    <filename>include/asm-i386/uaccess.h:</filename>
1269   </para>
1270
1271   <programlisting>
1272 #define copy_to_user(to,from,n)                         \
1273         (__builtin_constant_p(n) ?                      \
1274          __constant_copy_to_user((to),(from),(n)) :     \
1275          __generic_copy_to_user((to),(from),(n)))
1276   </programlisting>
1277
1278   <para>
1279    <filename>arch/sparc/kernel/head.S:</filename>
1280   </para>
1281
1282   <programlisting>
1283 /*
1284  * Sun people can't spell worth damn. "compatability" indeed.
1285  * At least we *know* we can't spell, and use a spell-checker.
1286  */
1287
1288 /* Uh, actually Linus it is I who cannot spell. Too much murky
1289  * Sparc assembly will do this to ya.
1290  */
1291 C_LABEL(cputypvar):
1292         .asciz "compatability"
1293
1294 /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */
1295         .align 4
1296 C_LABEL(cputypvar_sun4m):
1297         .asciz "compatible"
1298   </programlisting>
1299
1300   <para>
1301    <filename>arch/sparc/lib/checksum.S:</filename>
1302   </para>
1303
1304   <programlisting>
1305         /* Sun, you just can't beat me, you just can't.  Stop trying,
1306          * give up.  I'm serious, I am going to kick the living shit
1307          * out of you, game over, lights out.
1308          */
1309   </programlisting>
1310  </chapter>
1311
1312  <chapter id="credits">
1313   <title>Thanks</title>
1314
1315   <para>
1316    Thanks to Andi Kleen for the idea, answering my questions, fixing
1317    my mistakes, filling content, etc.  Philipp Rumpf for more spelling
1318    and clarity fixes, and some excellent non-obvious points.  Werner
1319    Almesberger for giving me a great summary of
1320    <function>disable_irq()</function>, and Jes Sorensen and Andrea
1321    Arcangeli added caveats. Michael Elizabeth Chastain for checking
1322    and adding to the Configure section. <!-- Rusty insisted on this
1323    bit; I didn't do it! --> Telsa Gwynne for teaching me DocBook. 
1324   </para>
1325  </chapter>
1326 </book>
1327