linux/Documentation/DocBook/kernel-hacking.tmpl
<<
>>
Prefs
   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>
 315asmlinkage 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>
 355if (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>
 367cond_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>
 442printk(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;
 453printk(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>
1034static 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>arch/x86/include/asm/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>arch/x86/include/asm/uaccess_32.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 */
1291C_LABEL(cputypvar):
1292        .asciz "compatability"
1293
1294/* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */
1295        .align 4
1296C_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
1328