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(current))
 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_ATOMIC_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 __be32 ipaddress;
 453 printk(KERN_INFO "my ip: %pI4\n", &amp;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/linux/irqflags.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
 854   </sect1>
 855
 856   <sect1 id="queue-waking">
 857    <title>Waking Up Queued Tasks</title>
 858
 859    <para>
 860     Call <function>wake_up()</function>
 861
 862     <filename class="headerfile">include/linux/wait.h</filename>;,
 863     which will wake up every process in the queue.  The exception is
 864     if one has <constant>TASK_EXCLUSIVE</constant> set, in which case
 865     the remainder of the queue will not be woken.  There are other variants
 866     of this basic function available in the same header.
 867    </para>
 868   </sect1>
 869  </chapter>
 870
 871  <chapter id="atomic-ops">
 872   <title>Atomic Operations</title>
 873
 874   <para>
 875    Certain operations are guaranteed atomic on all platforms.  The
 876    first class of operations work on <type>atomic_t</type>
 877
 878    <filename class="headerfile">include/asm/atomic.h</filename>; this
 879    contains a signed integer (at least 32 bits long), and you must use
 880    these functions to manipulate or read atomic_t variables.
 881    <function>atomic_read()</function> and
 882    <function>atomic_set()</function> get and set the counter,
 883    <function>atomic_add()</function>,
 884    <function>atomic_sub()</function>,
 885    <function>atomic_inc()</function>,
 886    <function>atomic_dec()</function>, and
 887    <function>atomic_dec_and_test()</function> (returns
 888    <returnvalue>true</returnvalue> if it was decremented to zero).
 889   </para>
 890
 891   <para>
 892    Yes.  It returns <returnvalue>true</returnvalue> (i.e. != 0) if the
 893    atomic variable is zero.
 894   </para>
 895
 896   <para>
 897    Note that these functions are slower than normal arithmetic, and
 898    so should not be used unnecessarily.
 899   </para>
 900
 901   <para>
 902    The second class of atomic operations is atomic bit operations on an
 903    <type>unsigned long</type>, defined in
 904
 905    <filename class="headerfile">include/linux/bitops.h</filename>.  These
 906    operations generally take a pointer to the bit pattern, and a bit
 907    number: 0 is the least significant bit.
 908    <function>set_bit()</function>, <function>clear_bit()</function>
 909    and <function>change_bit()</function> set, clear, and flip the
 910    given bit.  <function>test_and_set_bit()</function>,
 911    <function>test_and_clear_bit()</function> and
 912    <function>test_and_change_bit()</function> do the same thing,
 913    except return true if the bit was previously set; these are
 914    particularly useful for atomically setting flags.
 915   </para>
 916
 917   <para>
 918    It is possible to call these operations with bit indices greater
 919    than BITS_PER_LONG.  The resulting behavior is strange on big-endian
 920    platforms though so it is a good idea not to do this.
 921   </para>
 922  </chapter>
 923
 924  <chapter id="symbols">
 925   <title>Symbols</title>
 926
 927   <para>
 928    Within the kernel proper, the normal linking rules apply
 929    (ie. unless a symbol is declared to be file scope with the
 930    <type>static</type> keyword, it can be used anywhere in the
 931    kernel).  However, for modules, a special exported symbol table is
 932    kept which limits the entry points to the kernel proper.  Modules
 933    can also export symbols.
 934   </para>
 935
 936   <sect1 id="sym-exportsymbols">
 937    <title><function>EXPORT_SYMBOL()</function>
 938     <filename class="headerfile">include/linux/export.h</filename></title>
 939
 940    <para>
 941     This is the classic method of exporting a symbol: dynamically
 942     loaded modules will be able to use the symbol as normal.
 943    </para>
 944   </sect1>
 945
 946   <sect1 id="sym-exportsymbols-gpl">
 947    <title><function>EXPORT_SYMBOL_GPL()</function>
 948     <filename class="headerfile">include/linux/export.h</filename></title>
 949
 950    <para>
 951     Similar to <function>EXPORT_SYMBOL()</function> except that the
 952     symbols exported by <function>EXPORT_SYMBOL_GPL()</function> can
 953     only be seen by modules with a
 954     <function>MODULE_LICENSE()</function> that specifies a GPL
 955     compatible license.  It implies that the function is considered
 956     an internal implementation issue, and not really an interface.
 957     Some maintainers and developers may however
 958     require EXPORT_SYMBOL_GPL() when adding any new APIs or functionality.
 959    </para>
 960   </sect1>
 961  </chapter>
 962
 963  <chapter id="conventions">
 964   <title>Routines and Conventions</title>
 965
 966   <sect1 id="conventions-doublelinkedlist">
 967    <title>Double-linked lists
 968     <filename class="headerfile">include/linux/list.h</filename></title>
 969
 970    <para>
 971     There used to be three sets of linked-list routines in the kernel
 972     headers, but this one is the winner.  If you don't have some
 973     particular pressing need for a single list, it's a good choice.
 974    </para>
 975
 976    <para>
 977     In particular, <function>list_for_each_entry</function> is useful.
 978    </para>
 979   </sect1>
 980
 981   <sect1 id="convention-returns">
 982    <title>Return Conventions</title>
 983
 984    <para>
 985     For code called in user context, it's very common to defy C
 986     convention, and return <returnvalue>0</returnvalue> for success,
 987     and a negative error number
 988     (eg. <returnvalue>-EFAULT</returnvalue>) for failure.  This can be
 989     unintuitive at first, but it's fairly widespread in the kernel.
 990    </para>
 991
 992    <para>
 993     Using <function>ERR_PTR()</function>
 994
 995     <filename class="headerfile">include/linux/err.h</filename>; to
 996     encode a negative error number into a pointer, and
 997     <function>IS_ERR()</function> and <function>PTR_ERR()</function>
 998     to get it back out again: avoids a separate pointer parameter for
 999     the error number.  Icky, but in a good way.
1000    </para>
1001   </sect1>
1002
1003   <sect1 id="conventions-borkedcompile">
1004    <title>Breaking Compilation</title>
1005
1006    <para>
1007     Linus and the other developers sometimes change function or
1008     structure names in development kernels; this is not done just to
1009     keep everyone on their toes: it reflects a fundamental change
1010     (eg. can no longer be called with interrupts on, or does extra
1011     checks, or doesn't do checks which were caught before).  Usually
1012     this is accompanied by a fairly complete note to the linux-kernel
1013     mailing list; search the archive.  Simply doing a global replace
1014     on the file usually makes things <emphasis>worse</emphasis>.
1015    </para>
1016   </sect1>
1017
1018   <sect1 id="conventions-initialising">
1019    <title>Initializing structure members</title>
1020
1021    <para>
1022     The preferred method of initializing structures is to use
1023     designated initialisers, as defined by ISO C99, eg:
1024    </para>
1025    <programlisting>
1026 static struct block_device_operations opt_fops = {
1027         .open               = opt_open,
1028         .release            = opt_release,
1029         .ioctl              = opt_ioctl,
1030         .check_media_change = opt_media_change,
1031 };
1032    </programlisting>
1033    <para>
1034     This makes it easy to grep for, and makes it clear which
1035     structure fields are set.  You should do this because it looks
1036     cool.
1037    </para>
1038   </sect1>
1039
1040   <sect1 id="conventions-gnu-extns">
1041    <title>GNU Extensions</title>
1042
1043    <para>
1044     GNU Extensions are explicitly allowed in the Linux kernel.
1045     Note that some of the more complex ones are not very well
1046     supported, due to lack of general use, but the following are
1047     considered standard (see the GCC info page section "C
1048     Extensions" for more details - Yes, really the info page, the
1049     man page is only a short summary of the stuff in info).
1050    </para>
1051    <itemizedlist>
1052     <listitem>
1053      <para>
1054       Inline functions
1055      </para>
1056     </listitem>
1057     <listitem>
1058      <para>
1059       Statement expressions (ie. the ({ and }) constructs).
1060      </para>
1061     </listitem>
1062     <listitem>
1063      <para>
1064       Declaring attributes of a function / variable / type
1065       (__attribute__)
1066      </para>
1067     </listitem>
1068     <listitem>
1069      <para>
1070       typeof
1071      </para>
1072     </listitem>
1073     <listitem>
1074      <para>
1075       Zero length arrays
1076      </para>
1077     </listitem>
1078     <listitem>
1079      <para>
1080       Macro varargs
1081      </para>
1082     </listitem>
1083     <listitem>
1084      <para>
1085       Arithmetic on void pointers
1086      </para>
1087     </listitem>
1088     <listitem>
1089      <para>
1090       Non-Constant initializers
1091      </para>
1092     </listitem>
1093     <listitem>
1094      <para>
1095       Assembler Instructions (not outside arch/ and include/asm/)
1096      </para>
1097     </listitem>
1098     <listitem>
1099      <para>
1100       Function names as strings (__func__).
1101      </para>
1102     </listitem>
1103     <listitem>
1104      <para>
1105       __builtin_constant_p()
1106      </para>
1107     </listitem>
1108    </itemizedlist>
1109
1110    <para>
1111     Be wary when using long long in the kernel, the code gcc generates for
1112     it is horrible and worse: division and multiplication does not work
1113     on i386 because the GCC runtime functions for it are missing from
1114     the kernel environment.
1115    </para>
1116
1117     <!-- FIXME: add a note about ANSI aliasing cleanness -->
1118   </sect1>
1119
1120   <sect1 id="conventions-cplusplus">
1121    <title>C++</title>
1122
1123    <para>
1124     Using C++ in the kernel is usually a bad idea, because the
1125     kernel does not provide the necessary runtime environment
1126     and the include files are not tested for it.  It is still
1127     possible, but not recommended.  If you really want to do
1128     this, forget about exceptions at least.
1129    </para>
1130   </sect1>
1131
1132   <sect1 id="conventions-ifdef">
1133    <title>&num;if</title>
1134
1135    <para>
1136     It is generally considered cleaner to use macros in header files
1137     (or at the top of .c files) to abstract away functions rather than
1138     using `#if' pre-processor statements throughout the source code.
1139    </para>
1140   </sect1>
1141  </chapter>
1142
1143  <chapter id="submitting">
1144   <title>Putting Your Stuff in the Kernel</title>
1145
1146   <para>
1147    In order to get your stuff into shape for official inclusion, or
1148    even to make a neat patch, there's administrative work to be
1149    done:
1150   </para>
1151   <itemizedlist>
1152    <listitem>
1153     <para>
1154      Figure out whose pond you've been pissing in.  Look at the top of
1155      the source files, inside the <filename>MAINTAINERS</filename>
1156      file, and last of all in the <filename>CREDITS</filename> file.
1157      You should coordinate with this person to make sure you're not
1158      duplicating effort, or trying something that's already been
1159      rejected.
1160     </para>
1161
1162     <para>
1163      Make sure you put your name and EMail address at the top of
1164      any files you create or mangle significantly.  This is the
1165      first place people will look when they find a bug, or when
1166      <emphasis>they</emphasis> want to make a change.
1167     </para>
1168    </listitem>
1169
1170    <listitem>
1171     <para>
1172      Usually you want a configuration option for your kernel hack.
1173      Edit <filename>Kconfig</filename> in the appropriate directory.
1174      The Config language is simple to use by cut and paste, and there's
1175      complete documentation in
1176      <filename>Documentation/kbuild/kconfig-language.txt</filename>.
1177     </para>
1178
1179     <para>
1180      In your description of the option, make sure you address both the
1181      expert user and the user who knows nothing about your feature.  Mention
1182      incompatibilities and issues here.  <emphasis> Definitely
1183      </emphasis> end your description with <quote> if in doubt, say N
1184      </quote> (or, occasionally, `Y'); this is for people who have no
1185      idea what you are talking about.
1186     </para>
1187    </listitem>
1188
1189    <listitem>
1190     <para>
1191      Edit the <filename>Makefile</filename>: the CONFIG variables are
1192      exported here so you can usually just add a "obj-$(CONFIG_xxx) +=
1193      xxx.o" line.  The syntax is documented in
1194      <filename>Documentation/kbuild/makefiles.txt</filename>.
1195     </para>
1196    </listitem>
1197
1198    <listitem>
1199     <para>
1200      Put yourself in <filename>CREDITS</filename> if you've done
1201      something noteworthy, usually beyond a single file (your name
1202      should be at the top of the source files anyway).
1203      <filename>MAINTAINERS</filename> means you want to be consulted
1204      when changes are made to a subsystem, and hear about bugs; it
1205      implies a more-than-passing commitment to some part of the code.
1206     </para>
1207    </listitem>
1208
1209    <listitem>
1210     <para>
1211      Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename>
1212      and possibly <filename>Documentation/SubmittingDrivers</filename>.
1213     </para>
1214    </listitem>
1215   </itemizedlist>
1216  </chapter>
1217
1218  <chapter id="cantrips">
1219   <title>Kernel Cantrips</title>
1220
1221   <para>
1222    Some favorites from browsing the source.  Feel free to add to this
1223    list.
1224   </para>
1225
1226   <para>
1227    <filename>arch/x86/include/asm/delay.h:</filename>
1228   </para>
1229   <programlisting>
1230 #define ndelay(n) (__builtin_constant_p(n) ? \
1231         ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
1232         __ndelay(n))
1233   </programlisting>
1234
1235   <para>
1236    <filename>include/linux/fs.h</filename>:
1237   </para>
1238   <programlisting>
1239 /*
1240  * Kernel pointers have redundant information, so we can use a
1241  * scheme where we can return either an error code or a dentry
1242  * pointer with the same return value.
1243  *
1244  * This should be a per-architecture thing, to allow different
1245  * error and pointer decisions.
1246  */
1247  #define ERR_PTR(err)    ((void *)((long)(err)))
1248  #define PTR_ERR(ptr)    ((long)(ptr))
1249  #define IS_ERR(ptr)     ((unsigned long)(ptr) > (unsigned long)(-1000))
1250 </programlisting>
1251
1252   <para>
1253    <filename>arch/x86/include/asm/uaccess_32.h:</filename>
1254   </para>
1255
1256   <programlisting>
1257 #define copy_to_user(to,from,n)                         \
1258         (__builtin_constant_p(n) ?                      \
1259          __constant_copy_to_user((to),(from),(n)) :     \
1260          __generic_copy_to_user((to),(from),(n)))
1261   </programlisting>
1262
1263   <para>
1264    <filename>arch/sparc/kernel/head.S:</filename>
1265   </para>
1266
1267   <programlisting>
1268 /*
1269  * Sun people can't spell worth damn. "compatability" indeed.
1270  * At least we *know* we can't spell, and use a spell-checker.
1271  */
1272
1273 /* Uh, actually Linus it is I who cannot spell. Too much murky
1274  * Sparc assembly will do this to ya.
1275  */
1276 C_LABEL(cputypvar):
1277         .asciz "compatibility"
1278
1279 /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */
1280         .align 4
1281 C_LABEL(cputypvar_sun4m):
1282         .asciz "compatible"
1283   </programlisting>
1284
1285   <para>
1286    <filename>arch/sparc/lib/checksum.S:</filename>
1287   </para>
1288
1289   <programlisting>
1290         /* Sun, you just can't beat me, you just can't.  Stop trying,
1291          * give up.  I'm serious, I am going to kick the living shit
1292          * out of you, game over, lights out.
1293          */
1294   </programlisting>
1295  </chapter>
1296
1297  <chapter id="credits">
1298   <title>Thanks</title>
1299
1300   <para>
1301    Thanks to Andi Kleen for the idea, answering my questions, fixing
1302    my mistakes, filling content, etc.  Philipp Rumpf for more spelling
1303    and clarity fixes, and some excellent non-obvious points.  Werner
1304    Almesberger for giving me a great summary of
1305    <function>disable_irq()</function>, and Jes Sorensen and Andrea
1306    Arcangeli added caveats. Michael Elizabeth Chastain for checking
1307    and adding to the Configure section. <!-- Rusty insisted on this
1308    bit; I didn't do it! --> Telsa Gwynne for teaching me DocBook.
1309   </para>
1310  </chapter>
1311 </book>
1312