diff options
Diffstat (limited to 'Documentation/DocBook/kernel-hacking.tmpl')
| -rw-r--r-- | Documentation/DocBook/kernel-hacking.tmpl | 1312 |
1 files changed, 0 insertions, 1312 deletions
diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl deleted file mode 100644 index da5c087462b1..000000000000 --- a/Documentation/DocBook/kernel-hacking.tmpl +++ /dev/null @@ -1,1312 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="lk-hacking-guide"> - <bookinfo> - <title>Unreliable Guide To Hacking The Linux Kernel</title> - - <authorgroup> - <author> - <firstname>Rusty</firstname> - <surname>Russell</surname> - <affiliation> - <address> - <email>rusty@rustcorp.com.au</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2005</year> - <holder>Rusty Russell</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - - <releaseinfo> - This is the first release of this document as part of the kernel tarball. - </releaseinfo> - - </bookinfo> - - <toc></toc> - - <chapter id="introduction"> - <title>Introduction</title> - <para> - Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux - Kernel Hacking. This document describes the common routines and - general requirements for kernel code: its goal is to serve as a - primer for Linux kernel development for experienced C - programmers. I avoid implementation details: that's what the - code is for, and I ignore whole tracts of useful routines. - </para> - <para> - Before you read this, please understand that I never wanted to - write this document, being grossly under-qualified, but I always - wanted to read it, and this was the only way. I hope it will - grow into a compendium of best practice, common starting points - and random information. - </para> - </chapter> - - <chapter id="basic-players"> - <title>The Players</title> - - <para> - At any time each of the CPUs in a system can be: - </para> - - <itemizedlist> - <listitem> - <para> - not associated with any process, serving a hardware interrupt; - </para> - </listitem> - - <listitem> - <para> - not associated with any process, serving a softirq or tasklet; - </para> - </listitem> - - <listitem> - <para> - running in kernel space, associated with a process (user context); - </para> - </listitem> - - <listitem> - <para> - running a process in user space. - </para> - </listitem> - </itemizedlist> - - <para> - There is an ordering between these. The bottom two can preempt - each other, but above that is a strict hierarchy: each can only be - preempted by the ones above it. For example, while a softirq is - running on a CPU, no other softirq will preempt it, but a hardware - interrupt can. However, any other CPUs in the system execute - independently. - </para> - - <para> - We'll see a number of ways that the user context can block - interrupts, to become truly non-preemptable. - </para> - - <sect1 id="basics-usercontext"> - <title>User Context</title> - - <para> - User context is when you are coming in from a system call or other - trap: like userspace, you can be preempted by more important tasks - and by interrupts. You can sleep, by calling - <function>schedule()</function>. - </para> - - <note> - <para> - You are always in user context on module load and unload, - and on operations on the block device layer. - </para> - </note> - - <para> - In user context, the <varname>current</varname> pointer (indicating - the task we are currently executing) is valid, and - <function>in_interrupt()</function> - (<filename>include/linux/interrupt.h</filename>) is <returnvalue>false - </returnvalue>. - </para> - - <caution> - <para> - Beware that if you have preemption or softirqs disabled - (see below), <function>in_interrupt()</function> will return a - false positive. - </para> - </caution> - </sect1> - - <sect1 id="basics-hardirqs"> - <title>Hardware Interrupts (Hard IRQs)</title> - - <para> - Timer ticks, <hardware>network cards</hardware> and - <hardware>keyboard</hardware> are examples of real - hardware which produce interrupts at any time. The kernel runs - interrupt handlers, which services the hardware. The kernel - guarantees that this handler is never re-entered: if the same - interrupt arrives, it is queued (or dropped). Because it - disables interrupts, this handler has to be fast: frequently it - simply acknowledges the interrupt, marks a 'software interrupt' - for execution and exits. - </para> - - <para> - You can tell you are in a hardware interrupt, because - <function>in_irq()</function> returns <returnvalue>true</returnvalue>. - </para> - <caution> - <para> - Beware that this will return a false positive if interrupts are disabled - (see below). - </para> - </caution> - </sect1> - - <sect1 id="basics-softirqs"> - <title>Software Interrupt Context: Softirqs and Tasklets</title> - - <para> - Whenever a system call is about to return to userspace, or a - hardware interrupt handler exits, any 'software interrupts' - which are marked pending (usually by hardware interrupts) are - run (<filename>kernel/softirq.c</filename>). - </para> - - <para> - Much of the real interrupt handling work is done here. Early in - the transition to <acronym>SMP</acronym>, there were only 'bottom - halves' (BHs), which didn't take advantage of multiple CPUs. Shortly - after we switched from wind-up computers made of match-sticks and snot, - we abandoned this limitation and switched to 'softirqs'. - </para> - - <para> - <filename class="headerfile">include/linux/interrupt.h</filename> lists the - different softirqs. A very important softirq is the - timer softirq (<filename - class="headerfile">include/linux/timer.h</filename>): you can - register to have it call functions for you in a given length of - time. - </para> - - <para> - Softirqs are often a pain to deal with, since the same softirq - will run simultaneously on more than one CPU. For this reason, - tasklets (<filename - class="headerfile">include/linux/interrupt.h</filename>) are more - often used: they are dynamically-registrable (meaning you can have - as many as you want), and they also guarantee that any tasklet - will only run on one CPU at any time, although different tasklets - can run simultaneously. - </para> - <caution> - <para> - The name 'tasklet' is misleading: they have nothing to do with 'tasks', - and probably more to do with some bad vodka Alexey Kuznetsov had at the - time. - </para> - </caution> - - <para> - You can tell you are in a softirq (or tasklet) - using the <function>in_softirq()</function> macro - (<filename class="headerfile">include/linux/interrupt.h</filename>). - </para> - <caution> - <para> - Beware that this will return a false positive if a bh lock (see below) - is held. - </para> - </caution> - </sect1> - </chapter> - - <chapter id="basic-rules"> - <title>Some Basic Rules</title> - - <variablelist> - <varlistentry> - <term>No memory protection</term> - <listitem> - <para> - If you corrupt memory, whether in user context or - interrupt context, the whole machine will crash. Are you - sure you can't do what you want in userspace? - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>No floating point or <acronym>MMX</acronym></term> - <listitem> - <para> - The <acronym>FPU</acronym> context is not saved; even in user - context the <acronym>FPU</acronym> state probably won't - correspond with the current process: you would mess with some - user process' <acronym>FPU</acronym> state. If you really want - to do this, you would have to explicitly save/restore the full - <acronym>FPU</acronym> state (and avoid context switches). It - is generally a bad idea; use fixed point arithmetic first. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>A rigid stack limit</term> - <listitem> - <para> - Depending on configuration options the kernel stack is about 3K to 6K for most 32-bit architectures: it's - about 14K on most 64-bit archs, and often shared with interrupts - so you can't use it all. Avoid deep recursion and huge local - arrays on the stack (allocate them dynamically instead). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The Linux kernel is portable</term> - <listitem> - <para> - Let's keep it that way. Your code should be 64-bit clean, - and endian-independent. You should also minimize CPU - specific stuff, e.g. inline assembly should be cleanly - encapsulated and minimized to ease porting. Generally it - should be restricted to the architecture-dependent part of - the kernel tree. - </para> - </listitem> - </varlistentry> - </variablelist> - </chapter> - - <chapter id="ioctls"> - <title>ioctls: Not writing a new system call</title> - - <para> - A system call generally looks like this - </para> - - <programlisting> -asmlinkage long sys_mycall(int arg) -{ - return 0; -} - </programlisting> - - <para> - First, in most cases you don't want to create a new system call. - You create a character device and implement an appropriate ioctl - for it. This is much more flexible than system calls, doesn't have - to be entered in every architecture's - <filename class="headerfile">include/asm/unistd.h</filename> and - <filename>arch/kernel/entry.S</filename> file, and is much more - likely to be accepted by Linus. - </para> - - <para> - If all your routine does is read or write some parameter, consider - implementing a <function>sysfs</function> interface instead. - </para> - - <para> - Inside the ioctl you're in user context to a process. When a - error occurs you return a negated errno (see - <filename class="headerfile">include/linux/errno.h</filename>), - otherwise you return <returnvalue>0</returnvalue>. - </para> - - <para> - After you slept you should check if a signal occurred: the - Unix/Linux way of handling signals is to temporarily exit the - system call with the <constant>-ERESTARTSYS</constant> error. The - system call entry code will switch back to user context, process - the signal handler and then your system call will be restarted - (unless the user disabled that). So you should be prepared to - process the restart, e.g. if you're in the middle of manipulating - some data structure. - </para> - - <programlisting> -if (signal_pending(current)) - return -ERESTARTSYS; - </programlisting> - - <para> - If you're doing longer computations: first think userspace. If you - <emphasis>really</emphasis> want to do it in kernel you should - regularly check if you need to give up the CPU (remember there is - cooperative multitasking per CPU). Idiom: - </para> - - <programlisting> -cond_resched(); /* Will sleep */ - </programlisting> - - <para> - A short note on interface design: the UNIX system call motto is - "Provide mechanism not policy". - </para> - </chapter> - - <chapter id="deadlock-recipes"> - <title>Recipes for Deadlock</title> - - <para> - You cannot call any routines which may sleep, unless: - </para> - <itemizedlist> - <listitem> - <para> - You are in user context. - </para> - </listitem> - - <listitem> - <para> - You do not own any spinlocks. - </para> - </listitem> - - <listitem> - <para> - You have interrupts enabled (actually, Andi Kleen says - that the scheduling code will enable them for you, but - that's probably not what you wanted). - </para> - </listitem> - </itemizedlist> - - <para> - Note that some functions may sleep implicitly: common ones are - the user space access functions (*_user) and memory allocation - functions without <symbol>GFP_ATOMIC</symbol>. - </para> - - <para> - You should always compile your kernel - <symbol>CONFIG_DEBUG_ATOMIC_SLEEP</symbol> on, and it will warn - you if you break these rules. If you <emphasis>do</emphasis> break - the rules, you will eventually lock up your box. - </para> - - <para> - Really. - </para> - </chapter> - - <chapter id="common-routines"> - <title>Common Routines</title> - - <sect1 id="routines-printk"> - <title> - <function>printk()</function> - <filename class="headerfile">include/linux/kernel.h</filename> - </title> - - <para> - <function>printk()</function> feeds kernel messages to the - console, dmesg, and the syslog daemon. It is useful for debugging - and reporting errors, and can be used inside interrupt context, - but use with caution: a machine which has its console flooded with - printk messages is unusable. It uses a format string mostly - compatible with ANSI C printf, and C string concatenation to give - it a first "priority" argument: - </para> - - <programlisting> -printk(KERN_INFO "i = %u\n", i); - </programlisting> - - <para> - See <filename class="headerfile">include/linux/kernel.h</filename>; - for other KERN_ values; these are interpreted by syslog as the - level. Special case: for printing an IP address use - </para> - - <programlisting> -__be32 ipaddress; -printk(KERN_INFO "my ip: %pI4\n", &ipaddress); - </programlisting> - - <para> - <function>printk()</function> internally uses a 1K buffer and does - not catch overruns. Make sure that will be enough. - </para> - - <note> - <para> - You will know when you are a real kernel hacker - when you start typoing printf as printk in your user programs :) - </para> - </note> - - <!--- From the Lions book reader department --> - - <note> - <para> - Another sidenote: the original Unix Version 6 sources had a - comment on top of its printf function: "Printf should not be - used for chit-chat". You should follow that advice. - </para> - </note> - </sect1> - - <sect1 id="routines-copy"> - <title> - <function>copy_[to/from]_user()</function> - / - <function>get_user()</function> - / - <function>put_user()</function> - <filename class="headerfile">include/linux/uaccess.h</filename> - </title> - - <para> - <emphasis>[SLEEPS]</emphasis> - </para> - - <para> - <function>put_user()</function> and <function>get_user()</function> - are used to get and put single values (such as an int, char, or - long) from and to userspace. A pointer into userspace should - never be simply dereferenced: data should be copied using these - routines. Both return <constant>-EFAULT</constant> or 0. - </para> - <para> - <function>copy_to_user()</function> and - <function>copy_from_user()</function> are more general: they copy - an arbitrary amount of data to and from userspace. - <caution> - <para> - Unlike <function>put_user()</function> and - <function>get_user()</function>, they return the amount of - uncopied data (ie. <returnvalue>0</returnvalue> still means - success). - </para> - </caution> - [Yes, this moronic interface makes me cringe. The flamewar comes up every year or so. --RR.] - </para> - <para> - The functions may sleep implicitly. This should never be called - outside user context (it makes no sense), with interrupts - disabled, or a spinlock held. - </para> - </sect1> - - <sect1 id="routines-kmalloc"> - <title><function>kmalloc()</function>/<function>kfree()</function> - <filename class="headerfile">include/linux/slab.h</filename></title> - - <para> - <emphasis>[MAY SLEEP: SEE BELOW]</emphasis> - </para> - - <para> - These routines are used to dynamically request pointer-aligned - chunks of memory, like malloc and free do in userspace, but - <function>kmalloc()</function> takes an extra flag word. - Important values: - </para> - - <variablelist> - <varlistentry> - <term> - <constant> - GFP_KERNEL - </constant> - </term> - <listitem> - <para> - May sleep and swap to free memory. Only allowed in user - context, but is the most reliable way to allocate memory. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <constant> - GFP_ATOMIC - </constant> - </term> - <listitem> - <para> - Don't sleep. Less reliable than <constant>GFP_KERNEL</constant>, - but may be called from interrupt context. You should - <emphasis>really</emphasis> have a good out-of-memory - error-handling strategy. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <constant> - GFP_DMA - </constant> - </term> - <listitem> - <para> - Allocate ISA DMA lower than 16MB. If you don't know what that - is you don't need it. Very unreliable. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para> - If you see a <errorname>sleeping function called from invalid - context</errorname> warning message, then maybe you called a - sleeping allocation function from interrupt context without - <constant>GFP_ATOMIC</constant>. You should really fix that. - Run, don't walk. - </para> - - <para> - If you are allocating at least <constant>PAGE_SIZE</constant> - (<filename class="headerfile">include/asm/page.h</filename>) bytes, - consider using <function>__get_free_pages()</function> - - (<filename class="headerfile">include/linux/mm.h</filename>). It - takes an order argument (0 for page sized, 1 for double page, 2 - for four pages etc.) and the same memory priority flag word as - above. - </para> - - <para> - If you are allocating more than a page worth of bytes you can use - <function>vmalloc()</function>. It'll allocate virtual memory in - the kernel map. This block is not contiguous in physical memory, - but the <acronym>MMU</acronym> makes it look like it is for you - (so it'll only look contiguous to the CPUs, not to external device - drivers). If you really need large physically contiguous memory - for some weird device, you have a problem: it is poorly supported - in Linux because after some time memory fragmentation in a running - kernel makes it hard. The best way is to allocate the block early - in the boot process via the <function>alloc_bootmem()</function> - routine. - </para> - - <para> - Before inventing your own cache of often-used objects consider - using a slab cache in - <filename class="headerfile">include/linux/slab.h</filename> - </para> - </sect1> - - <sect1 id="routines-current"> - <title><function>current</function> - <filename class="headerfile">include/asm/current.h</filename></title> - - <para> - This global variable (really a macro) contains a pointer to - the current task structure, so is only valid in user context. - For example, when a process makes a system call, this will - point to the task structure of the calling process. It is - <emphasis>not NULL</emphasis> in interrupt context. - </para> - </sect1> - - <sect1 id="routines-udelay"> - <title><function>mdelay()</function>/<function>udelay()</function> - <filename class="headerfile">include/asm/delay.h</filename> - <filename class="headerfile">include/linux/delay.h</filename> - </title> - - <para> - The <function>udelay()</function> and <function>ndelay()</function> functions can be used for small pauses. - Do not use large values with them as you risk - overflow - the helper function <function>mdelay()</function> is useful - here, or consider <function>msleep()</function>. - </para> - </sect1> - - <sect1 id="routines-endian"> - <title><function>cpu_to_be32()</function>/<function>be32_to_cpu()</function>/<function>cpu_to_le32()</function>/<function>le32_to_cpu()</function> - <filename class="headerfile">include/asm/byteorder.h</filename> - </title> - - <para> - The <function>cpu_to_be32()</function> family (where the "32" can - be replaced by 64 or 16, and the "be" can be replaced by "le") are - the general way to do endian conversions in the kernel: they - return the converted value. All variations supply the reverse as - well: <function>be32_to_cpu()</function>, etc. - </para> - - <para> - There are two major variations of these functions: the pointer - variation, such as <function>cpu_to_be32p()</function>, which take - a pointer to the given type, and return the converted value. The - other variation is the "in-situ" family, such as - <function>cpu_to_be32s()</function>, which convert value referred - to by the pointer, and return void. - </para> - </sect1> - - <sect1 id="routines-local-irqs"> - <title><function>local_irq_save()</function>/<function>local_irq_restore()</function> - <filename class="headerfile">include/linux/irqflags.h</filename> - </title> - - <para> - These routines disable hard interrupts on the local CPU, and - restore them. They are reentrant; saving the previous state in - their one <varname>unsigned long flags</varname> argument. If you - know that interrupts are enabled, you can simply use - <function>local_irq_disable()</function> and - <function>local_irq_enable()</function>. - </para> - </sect1> - - <sect1 id="routines-softirqs"> - <title><function>local_bh_disable()</function>/<function>local_bh_enable()</function> - <filename class="headerfile">include/linux/interrupt.h</filename></title> - - <para> - These routines disable soft interrupts on the local CPU, and - restore them. They are reentrant; if soft interrupts were - disabled before, they will still be disabled after this pair - of functions has been called. They prevent softirqs and tasklets - from running on the current CPU. - </para> - </sect1> - - <sect1 id="routines-processorids"> - <title><function>smp_processor_id</function>() - <filename class="headerfile">include/asm/smp.h</filename></title> - - <para> - <function>get_cpu()</function> disables preemption (so you won't - suddenly get moved to another CPU) and returns the current - processor number, between 0 and <symbol>NR_CPUS</symbol>. Note - that the CPU numbers are not necessarily continuous. You return - it again with <function>put_cpu()</function> when you are done. - </para> - <para> - If you know you cannot be preempted by another task (ie. you are - in interrupt context, or have preemption disabled) you can use - smp_processor_id(). - </para> - </sect1> - - <sect1 id="routines-init"> - <title><type>__init</type>/<type>__exit</type>/<type>__initdata</type> - <filename class="headerfile">include/linux/init.h</filename></title> - - <para> - After boot, the kernel frees up a special section; functions - marked with <type>__init</type> and data structures marked with - <type>__initdata</type> are dropped after boot is complete: similarly - modules discard this memory after initialization. <type>__exit</type> - is used to declare a function which is only required on exit: the - function will be dropped if this file is not compiled as a module. - See the header file for use. Note that it makes no sense for a function - marked with <type>__init</type> to be exported to modules with - <function>EXPORT_SYMBOL()</function> - this will break. - </para> - - </sect1> - - <sect1 id="routines-init-again"> - <title><function>__initcall()</function>/<function>module_init()</function> - <filename class="headerfile">include/linux/init.h</filename></title> - <para> - Many parts of the kernel are well served as a module - (dynamically-loadable parts of the kernel). Using the - <function>module_init()</function> and - <function>module_exit()</function> macros it is easy to write code - without #ifdefs which can operate both as a module or built into - the kernel. - </para> - - <para> - The <function>module_init()</function> macro defines which - function is to be called at module insertion time (if the file is - compiled as a module), or at boot time: if the file is not - compiled as a module the <function>module_init()</function> macro - becomes equivalent to <function>__initcall()</function>, which - through linker magic ensures that the function is called on boot. - </para> - - <para> - The function can return a negative error number to cause - module loading to fail (unfortunately, this has no effect if - the module is compiled into the kernel). This function is - called in user context with interrupts enabled, so it can sleep. - </para> - </sect1> - - <sect1 id="routines-moduleexit"> - <title> <function>module_exit()</function> - <filename class="headerfile">include/linux/init.h</filename> </title> - - <para> - This macro defines the function to be called at module removal - time (or never, in the case of the file compiled into the - kernel). It will only be called if the module usage count has - reached zero. This function can also sleep, but cannot fail: - everything must be cleaned up by the time it returns. - </para> - - <para> - Note that this macro is optional: if it is not present, your - module will not be removable (except for 'rmmod -f'). - </para> - </sect1> - - <sect1 id="routines-module-use-counters"> - <title> <function>try_module_get()</function>/<function>module_put()</function> - <filename class="headerfile">include/linux/module.h</filename></title> - - <para> - These manipulate the module usage count, to protect against - removal (a module also can't be removed if another module uses one - of its exported symbols: see below). Before calling into module - code, you should call <function>try_module_get()</function> on - that module: if it fails, then the module is being removed and you - should act as if it wasn't there. Otherwise, you can safely enter - the module, and call <function>module_put()</function> when you're - finished. - </para> - - <para> - Most registerable structures have an - <structfield>owner</structfield> field, such as in the - <structname>file_operations</structname> structure. Set this field - to the macro <symbol>THIS_MODULE</symbol>. - </para> - </sect1> - - <!-- add info on new-style module refcounting here --> - </chapter> - - <chapter id="queues"> - <title>Wait Queues - <filename class="headerfile">include/linux/wait.h</filename> - </title> - <para> - <emphasis>[SLEEPS]</emphasis> - </para> - - <para> - A wait queue is used to wait for someone to wake you up when a - certain condition is true. They must be used carefully to ensure - there is no race condition. You declare a - <type>wait_queue_head_t</type>, and then processes which want to - wait for that condition declare a <type>wait_queue_t</type> - referring to themselves, and place that in the queue. - </para> - - <sect1 id="queue-declaring"> - <title>Declaring</title> - - <para> - You declare a <type>wait_queue_head_t</type> using the - <function>DECLARE_WAIT_QUEUE_HEAD()</function> macro, or using the - <function>init_waitqueue_head()</function> routine in your - initialization code. - </para> - </sect1> - - <sect1 id="queue-waitqueue"> - <title>Queuing</title> - - <para> - Placing yourself in the waitqueue is fairly complex, because you - must put yourself in the queue before checking the condition. - There is a macro to do this: - <function>wait_event_interruptible()</function> - - <filename class="headerfile">include/linux/wait.h</filename> The - first argument is the wait queue head, and the second is an - expression which is evaluated; the macro returns - <returnvalue>0</returnvalue> when this expression is true, or - <returnvalue>-ERESTARTSYS</returnvalue> if a signal is received. - The <function>wait_event()</function> version ignores signals. - </para> - - </sect1> - - <sect1 id="queue-waking"> - <title>Waking Up Queued Tasks</title> - - <para> - Call <function>wake_up()</function> - - <filename class="headerfile">include/linux/wait.h</filename>;, - which will wake up every process in the queue. The exception is - if one has <constant>TASK_EXCLUSIVE</constant> set, in which case - the remainder of the queue will not be woken. There are other variants - of this basic function available in the same header. - </para> - </sect1> - </chapter> - - <chapter id="atomic-ops"> - <title>Atomic Operations</title> - - <para> - Certain operations are guaranteed atomic on all platforms. The - first class of operations work on <type>atomic_t</type> - - <filename class="headerfile">include/asm/atomic.h</filename>; this - contains a signed integer (at least 32 bits long), and you must use - these functions to manipulate or read atomic_t variables. - <function>atomic_read()</function> and - <function>atomic_set()</function> get and set the counter, - <function>atomic_add()</function>, - <function>atomic_sub()</function>, - <function>atomic_inc()</function>, - <function>atomic_dec()</function>, and - <function>atomic_dec_and_test()</function> (returns - <returnvalue>true</returnvalue> if it was decremented to zero). - </para> - - <para> - Yes. It returns <returnvalue>true</returnvalue> (i.e. != 0) if the - atomic variable is zero. - </para> - - <para> - Note that these functions are slower than normal arithmetic, and - so should not be used unnecessarily. - </para> - - <para> - The second class of atomic operations is atomic bit operations on an - <type>unsigned long</type>, defined in - - <filename class="headerfile">include/linux/bitops.h</filename>. These - operations generally take a pointer to the bit pattern, and a bit - number: 0 is the least significant bit. - <function>set_bit()</function>, <function>clear_bit()</function> - and <function>change_bit()</function> set, clear, and flip the - given bit. <function>test_and_set_bit()</function>, - <function>test_and_clear_bit()</function> and - <function>test_and_change_bit()</function> do the same thing, - except return true if the bit was previously set; these are - particularly useful for atomically setting flags. - </para> - - <para> - It is possible to call these operations with bit indices greater - than BITS_PER_LONG. The resulting behavior is strange on big-endian - platforms though so it is a good idea not to do this. - </para> - </chapter> - - <chapter id="symbols"> - <title>Symbols</title> - - <para> - Within the kernel proper, the normal linking rules apply - (ie. unless a symbol is declared to be file scope with the - <type>static</type> keyword, it can be used anywhere in the - kernel). However, for modules, a special exported symbol table is - kept which limits the entry points to the kernel proper. Modules - can also export symbols. - </para> - - <sect1 id="sym-exportsymbols"> - <title><function>EXPORT_SYMBOL()</function> - <filename class="headerfile">include/linux/export.h</filename></title> - - <para> - This is the classic method of exporting a symbol: dynamically - loaded modules will be able to use the symbol as normal. - </para> - </sect1> - - <sect1 id="sym-exportsymbols-gpl"> - <title><function>EXPORT_SYMBOL_GPL()</function> - <filename class="headerfile">include/linux/export.h</filename></title> - - <para> - Similar to <function>EXPORT_SYMBOL()</function> except that the - symbols exported by <function>EXPORT_SYMBOL_GPL()</function> can - only be seen by modules with a - <function>MODULE_LICENSE()</function> that specifies a GPL - compatible license. It implies that the function is considered - an internal implementation issue, and not really an interface. - Some maintainers and developers may however - require EXPORT_SYMBOL_GPL() when adding any new APIs or functionality. - </para> - </sect1> - </chapter> - - <chapter id="conventions"> - <title>Routines and Conventions</title> - - <sect1 id="conventions-doublelinkedlist"> - <title>Double-linked lists - <filename class="headerfile">include/linux/list.h</filename></title> - - <para> - There used to be three sets of linked-list routines in the kernel - headers, but this one is the winner. If you don't have some - particular pressing need for a single list, it's a good choice. - </para> - - <para> - In particular, <function>list_for_each_entry</function> is useful. - </para> - </sect1> - - <sect1 id="convention-returns"> - <title>Return Conventions</title> - - <para> - For code called in user context, it's very common to defy C - convention, and return <returnvalue>0</returnvalue> for success, - and a negative error number - (eg. <returnvalue>-EFAULT</returnvalue>) for failure. This can be - unintuitive at first, but it's fairly widespread in the kernel. - </para> - - <para> - Using <function>ERR_PTR()</function> - - <filename class="headerfile">include/linux/err.h</filename>; to - encode a negative error number into a pointer, and - <function>IS_ERR()</function> and <function>PTR_ERR()</function> - to get it back out again: avoids a separate pointer parameter for - the error number. Icky, but in a good way. - </para> - </sect1> - - <sect1 id="conventions-borkedcompile"> - <title>Breaking Compilation</title> - - <para> - Linus and the other developers sometimes change function or - structure names in development kernels; this is not done just to - keep everyone on their toes: it reflects a fundamental change - (eg. can no longer be called with interrupts on, or does extra - checks, or doesn't do checks which were caught before). Usually - this is accompanied by a fairly complete note to the linux-kernel - mailing list; search the archive. Simply doing a global replace - on the file usually makes things <emphasis>worse</emphasis>. - </para> - </sect1> - - <sect1 id="conventions-initialising"> - <title>Initializing structure members</title> - - <para> - The preferred method of initializing structures is to use - designated initialisers, as defined by ISO C99, eg: - </para> - <programlisting> -static struct block_device_operations opt_fops = { - .open = opt_open, - .release = opt_release, - .ioctl = opt_ioctl, - .check_media_change = opt_media_change, -}; - </programlisting> - <para> - This makes it easy to grep for, and makes it clear which - structure fields are set. You should do this because it looks - cool. - </para> - </sect1> - - <sect1 id="conventions-gnu-extns"> - <title>GNU Extensions</title> - - <para> - GNU Extensions are explicitly allowed in the Linux kernel. - Note that some of the more complex ones are not very well - supported, due to lack of general use, but the following are - considered standard (see the GCC info page section "C - Extensions" for more details - Yes, really the info page, the - man page is only a short summary of the stuff in info). - </para> - <itemizedlist> - <listitem> - <para> - Inline functions - </para> - </listitem> - <listitem> - <para> - Statement expressions (ie. the ({ and }) constructs). - </para> - </listitem> - <listitem> - <para> - Declaring attributes of a function / variable / type - (__attribute__) - </para> - </listitem> - <listitem> - <para> - typeof - </para> - </listitem> - <listitem> - <para> - Zero length arrays - </para> - </listitem> - <listitem> - <para> - Macro varargs - </para> - </listitem> - <listitem> - <para> - Arithmetic on void pointers - </para> - </listitem> - <listitem> - <para> - Non-Constant initializers - </para> - </listitem> - <listitem> - <para> - Assembler Instructions (not outside arch/ and include/asm/) - </para> - </listitem> - <listitem> - <para> - Function names as strings (__func__). - </para> - </listitem> - <listitem> - <para> - __builtin_constant_p() - </para> - </listitem> - </itemizedlist> - - <para> - Be wary when using long long in the kernel, the code gcc generates for - it is horrible and worse: division and multiplication does not work - on i386 because the GCC runtime functions for it are missing from - the kernel environment. - </para> - - <!-- FIXME: add a note about ANSI aliasing cleanness --> - </sect1> - - <sect1 id="conventions-cplusplus"> - <title>C++</title> - - <para> - Using C++ in the kernel is usually a bad idea, because the - kernel does not provide the necessary runtime environment - and the include files are not tested for it. It is still - possible, but not recommended. If you really want to do - this, forget about exceptions at least. - </para> - </sect1> - - <sect1 id="conventions-ifdef"> - <title>#if</title> - - <para> - It is generally considered cleaner to use macros in header files - (or at the top of .c files) to abstract away functions rather than - using `#if' pre-processor statements throughout the source code. - </para> - </sect1> - </chapter> - - <chapter id="submitting"> - <title>Putting Your Stuff in the Kernel</title> - - <para> - In order to get your stuff into shape for official inclusion, or - even to make a neat patch, there's administrative work to be - done: - </para> - <itemizedlist> - <listitem> - <para> - Figure out whose pond you've been pissing in. Look at the top of - the source files, inside the <filename>MAINTAINERS</filename> - file, and last of all in the <filename>CREDITS</filename> file. - You should coordinate with this person to make sure you're not - duplicating effort, or trying something that's already been - rejected. - </para> - - <para> - Make sure you put your name and EMail address at the top of - any files you create or mangle significantly. This is the - first place people will look when they find a bug, or when - <emphasis>they</emphasis> want to make a change. - </para> - </listitem> - - <listitem> - <para> - Usually you want a configuration option for your kernel hack. - Edit <filename>Kconfig</filename> in the appropriate directory. - The Config language is simple to use by cut and paste, and there's - complete documentation in - <filename>Documentation/kbuild/kconfig-language.txt</filename>. - </para> - - <para> - In your description of the option, make sure you address both the - expert user and the user who knows nothing about your feature. Mention - incompatibilities and issues here. <emphasis> Definitely - </emphasis> end your description with <quote> if in doubt, say N - </quote> (or, occasionally, `Y'); this is for people who have no - idea what you are talking about. - </para> - </listitem> - - <listitem> - <para> - Edit the <filename>Makefile</filename>: the CONFIG variables are - exported here so you can usually just add a "obj-$(CONFIG_xxx) += - xxx.o" line. The syntax is documented in - <filename>Documentation/kbuild/makefiles.txt</filename>. - </para> - </listitem> - - <listitem> - <para> - Put yourself in <filename>CREDITS</filename> if you've done - something noteworthy, usually beyond a single file (your name - should be at the top of the source files anyway). - <filename>MAINTAINERS</filename> means you want to be consulted - when changes are made to a subsystem, and hear about bugs; it - implies a more-than-passing commitment to some part of the code. - </para> - </listitem> - - <listitem> - <para> - Finally, don't forget to read <filename>Documentation/process/submitting-patches.rst</filename> - and possibly <filename>Documentation/process/submitting-drivers.rst</filename>. - </para> - </listitem> - </itemizedlist> - </chapter> - - <chapter id="cantrips"> - <title>Kernel Cantrips</title> - - <para> - Some favorites from browsing the source. Feel free to add to this - list. - </para> - - <para> - <filename>arch/x86/include/asm/delay.h:</filename> - </para> - <programlisting> -#define ndelay(n) (__builtin_constant_p(n) ? \ - ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \ - __ndelay(n)) - </programlisting> - - <para> - <filename>include/linux/fs.h</filename>: - </para> - <programlisting> -/* - * Kernel pointers have redundant information, so we can use a - * scheme where we can return either an error code or a dentry - * pointer with the same return value. - * - * This should be a per-architecture thing, to allow different - * error and pointer decisions. - */ - #define ERR_PTR(err) ((void *)((long)(err))) - #define PTR_ERR(ptr) ((long)(ptr)) - #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000)) -</programlisting> - - <para> - <filename>arch/x86/include/asm/uaccess_32.h:</filename> - </para> - - <programlisting> -#define copy_to_user(to,from,n) \ - (__builtin_constant_p(n) ? \ - __constant_copy_to_user((to),(from),(n)) : \ - __generic_copy_to_user((to),(from),(n))) - </programlisting> - - <para> - <filename>arch/sparc/kernel/head.S:</filename> - </para> - - <programlisting> -/* - * Sun people can't spell worth damn. "compatability" indeed. - * At least we *know* we can't spell, and use a spell-checker. - */ - -/* Uh, actually Linus it is I who cannot spell. Too much murky - * Sparc assembly will do this to ya. - */ -C_LABEL(cputypvar): - .asciz "compatibility" - -/* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */ - .align 4 -C_LABEL(cputypvar_sun4m): - .asciz "compatible" - </programlisting> - - <para> - <filename>arch/sparc/lib/checksum.S:</filename> - </para> - - <programlisting> - /* Sun, you just can't beat me, you just can't. Stop trying, - * give up. I'm serious, I am going to kick the living shit - * out of you, game over, lights out. - */ - </programlisting> - </chapter> - - <chapter id="credits"> - <title>Thanks</title> - - <para> - Thanks to Andi Kleen for the idea, answering my questions, fixing - my mistakes, filling content, etc. Philipp Rumpf for more spelling - and clarity fixes, and some excellent non-obvious points. Werner - Almesberger for giving me a great summary of - <function>disable_irq()</function>, and Jes Sorensen and Andrea - Arcangeli added caveats. Michael Elizabeth Chastain for checking - and adding to the Configure section. <!-- Rusty insisted on this - bit; I didn't do it! --> Telsa Gwynne for teaching me DocBook. - </para> - </chapter> -</book> - |
