Documentation/DocBook/kernel-hacking.tmpl

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