From: Linus Torvalds Date: Tue, 4 Jul 2017 04:13:25 +0000 (-0700) Subject: Merge tag 'docs-4.13' of git://git.lwn.net/linux X-Git-Tag: v4.14-rc1~619 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=650fc870a2ef35b83397eebd35b8c8df211bff78;p=platform%2Fkernel%2Flinux-rpi.git Merge tag 'docs-4.13' of git://git.lwn.net/linux Pull documentation updates from Jonathan Corbet: "There has been a fair amount of activity in the docs tree this time around. Highlights include: - Conversion of a bunch of security documentation into RST - The conversion of the remaining DocBook templates by The Amazing Mauro Machine. We can now drop the entire DocBook build chain. - The usual collection of fixes and minor updates" * tag 'docs-4.13' of git://git.lwn.net/linux: (90 commits) scripts/kernel-doc: handle DECLARE_HASHTABLE Documentation: atomic_ops.txt is core-api/atomic_ops.rst Docs: clean up some DocBook loose ends Make the main documentation title less Geocities Docs: Use kernel-figure in vidioc-g-selection.rst Docs: fix table problems in ras.rst Docs: Fix breakage with Sphinx 1.5 and upper Docs: Include the Latex "ifthen" package doc/kokr/howto: Only send regression fixes after -rc1 docs-rst: fix broken links to dynamic-debug-howto in kernel-parameters doc: Document suitability of IBM Verse for kernel development Doc: fix a markup error in coding-style.rst docs: driver-api: i2c: remove some outdated information Documentation: DMA API: fix a typo in a function name Docs: Insert missing space to separate link from text doc/ko_KR/memory-barriers: Update control-dependencies example Documentation, kbuild: fix typo "minimun" -> "minimum" docs: Fix some formatting issues in request-key.rst doc: ReSTify keys-trusted-encrypted.txt doc: ReSTify keys-request-key.txt ... --- 650fc870a2ef35b83397eebd35b8c8df211bff78 diff --cc Documentation/admin-guide/index.rst index 6d99a7c,e14c374..5bb9161 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@@ -61,7 -61,7 +61,8 @@@ configure specific aspects of kernel be java ras pm/index + thunderbolt + LSM/index .. only:: subproject and html diff --cc Documentation/driver-api/w1.rst index 0000000,c1da8f0..9963cca mode 000000,100644..100644 --- a/Documentation/driver-api/w1.rst +++ b/Documentation/driver-api/w1.rst @@@ -1,0 -1,70 +1,70 @@@ + ====================== + W1: Dallas' 1-wire bus + ====================== + + :Author: David Fries + + W1 API internal to the kernel + ============================= + + W1 API internal to the kernel + ----------------------------- + -drivers/w1/w1.h -~~~~~~~~~~~~~~~ ++include/linux/w1.h ++~~~~~~~~~~~~~~~~~~ + -W1 core functions. ++W1 kernel API functions. + -.. kernel-doc:: drivers/w1/w1.h ++.. kernel-doc:: include/linux/w1.h + :internal: + + drivers/w1/w1.c + ~~~~~~~~~~~~~~~ + + W1 core functions. + + .. kernel-doc:: drivers/w1/w1.c + :internal: + -drivers/w1/w1_family.h -~~~~~~~~~~~~~~~~~~~~~~~ - -Allows registering device family operations. - -.. kernel-doc:: drivers/w1/w1_family.h - :internal: - + drivers/w1/w1_family.c + ~~~~~~~~~~~~~~~~~~~~~~~ + + Allows registering device family operations. + + .. kernel-doc:: drivers/w1/w1_family.c + :export: + ++drivers/w1/w1_internal.h ++~~~~~~~~~~~~~~~~~~~~~~~~ ++ ++W1 internal initialization for master devices. ++ ++.. kernel-doc:: drivers/w1/w1_internal.h ++ :internal: ++ + drivers/w1/w1_int.c + ~~~~~~~~~~~~~~~~~~~~ + + W1 internal initialization for master devices. + + .. kernel-doc:: drivers/w1/w1_int.c + :export: + + drivers/w1/w1_netlink.h + ~~~~~~~~~~~~~~~~~~~~~~~~ + + W1 external netlink API structures and commands. + + .. kernel-doc:: drivers/w1/w1_netlink.h + :internal: + + drivers/w1/w1_io.c + ~~~~~~~~~~~~~~~~~~~ + + W1 input/output. + + .. kernel-doc:: drivers/w1/w1_io.c + :export: + + .. kernel-doc:: drivers/w1/w1_io.c + :internal: diff --cc Documentation/kernel-hacking/hacking.rst index 0000000,1a456b6..daf3883 mode 000000,100644..100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@@ -1,0 -1,811 +1,811 @@@ + ============================================ + Unreliable Guide To Hacking The Linux Kernel + ============================================ + + :Author: Rusty Russell + + Introduction + ============ + + 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. + + 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. + + The Players + =========== + + At any time each of the CPUs in a system can be: + + - not associated with any process, serving a hardware interrupt; + + - not associated with any process, serving a softirq or tasklet; + + - running in kernel space, associated with a process (user context); + + - running a process in user space. + + 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. + + We'll see a number of ways that the user context can block interrupts, + to become truly non-preemptable. + + User Context + ------------ + + 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 :c:func:`schedule()`. + + .. note:: + + You are always in user context on module load and unload, and on + operations on the block device layer. + + In user context, the ``current`` pointer (indicating the task we are + currently executing) is valid, and :c:func:`in_interrupt()` + (``include/linux/preempt.h``) is false. + + .. warning:: + + Beware that if you have preemption or softirqs disabled (see below), + :c:func:`in_interrupt()` will return a false positive. + + Hardware Interrupts (Hard IRQs) + ------------------------------- + + Timer ticks, network cards and keyboard 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. + + You can tell you are in a hardware interrupt, because + :c:func:`in_irq()` returns true. + + .. warning:: + + Beware that this will return a false positive if interrupts are + disabled (see below). + + Software Interrupt Context: Softirqs and Tasklets + ------------------------------------------------- + + 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 (``kernel/softirq.c``). + + Much of the real interrupt handling work is done here. Early in the + transition to SMP, 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'. + + ``include/linux/interrupt.h`` lists the different softirqs. A very + important softirq is the timer softirq (``include/linux/timer.h``): you + can register to have it call functions for you in a given length of + time. + + Softirqs are often a pain to deal with, since the same softirq will run + simultaneously on more than one CPU. For this reason, tasklets + (``include/linux/interrupt.h``) 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. + + .. warning:: + + 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. + + You can tell you are in a softirq (or tasklet) using the + :c:func:`in_softirq()` macro (``include/linux/preempt.h``). + + .. warning:: + + Beware that this will return a false positive if a + :ref:`botton half lock ` is held. + + Some Basic Rules + ================ + + No memory protection + 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? + + No floating point or MMX + The FPU context is not saved; even in user context the FPU state + probably won't correspond with the current process: you would mess + with some user process' FPU state. If you really want to do this, + you would have to explicitly save/restore the full FPU state (and + avoid context switches). It is generally a bad idea; use fixed point + arithmetic first. + + A rigid stack limit + 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). + + The Linux kernel is portable + 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. + + ioctls: Not writing a new system call + ===================================== + + A system call generally looks like this:: + + asmlinkage long sys_mycall(int arg) + { + return 0; + } + + + 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 ``include/asm/unistd.h`` and + ``arch/kernel/entry.S`` file, and is much more likely to be accepted by + Linus. + + If all your routine does is read or write some parameter, consider + implementing a :c:func:`sysfs()` interface instead. + + Inside the ioctl you're in user context to a process. When a error + occurs you return a negated errno (see + ``include/uapi/asm-generic/errno-base.h``, + ``include/uapi/asm-generic/errno.h`` and ``include/linux/errno.h``), + otherwise you return 0. + + 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 + ``-ERESTARTSYS`` 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. + + :: + + if (signal_pending(current)) + return -ERESTARTSYS; + + + If you're doing longer computations: first think userspace. If you + **really** 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:: + + cond_resched(); /* Will sleep */ + + + A short note on interface design: the UNIX system call motto is "Provide + mechanism not policy". + + Recipes for Deadlock + ==================== + + You cannot call any routines which may sleep, unless: + + - You are in user context. + + - You do not own any spinlocks. + + - 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). + + Note that some functions may sleep implicitly: common ones are the user + space access functions (\*_user) and memory allocation functions + without ``GFP_ATOMIC``. + + You should always compile your kernel ``CONFIG_DEBUG_ATOMIC_SLEEP`` on, + and it will warn you if you break these rules. If you **do** break the + rules, you will eventually lock up your box. + + Really. + + Common Routines + =============== + + :c:func:`printk()` + ------------------ + + Defined in ``include/linux/printk.h`` + + :c:func:`printk()` 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:: + + printk(KERN_INFO "i = %u\n", i); + + + See ``include/linux/kern_levels.h``; for other ``KERN_`` values; these are + interpreted by syslog as the level. Special case: for printing an IP + address use:: + + __be32 ipaddress; + printk(KERN_INFO "my ip: %pI4\n", &ipaddress); + + + :c:func:`printk()` internally uses a 1K buffer and does not catch + overruns. Make sure that will be enough. + + .. note:: + + You will know when you are a real kernel hacker when you start + typoing printf as printk in your user programs :) + + .. note:: + + 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. + + :c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()` + --------------------------------------------------------------------------------------------------- + + Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h`` + + **[SLEEPS]** + + :c:func:`put_user()` and :c:func:`get_user()` 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 ``-EFAULT`` or + 0. + + :c:func:`copy_to_user()` and :c:func:`copy_from_user()` are + more general: they copy an arbitrary amount of data to and from + userspace. + + .. warning:: + + Unlike :c:func:`put_user()` and :c:func:`get_user()`, they + return the amount of uncopied data (ie. 0 still means success). + + [Yes, this moronic interface makes me cringe. The flamewar comes up + every year or so. --RR.] + + The functions may sleep implicitly. This should never be called outside + user context (it makes no sense), with interrupts disabled, or a + spinlock held. + + :c:func:`kmalloc()`/:c:func:`kfree()` + ------------------------------------- + + Defined in ``include/linux/slab.h`` + + **[MAY SLEEP: SEE BELOW]** + + These routines are used to dynamically request pointer-aligned chunks of + memory, like malloc and free do in userspace, but + :c:func:`kmalloc()` takes an extra flag word. Important values: + + ``GFP_KERNEL`` + May sleep and swap to free memory. Only allowed in user context, but + is the most reliable way to allocate memory. + + ``GFP_ATOMIC`` + Don't sleep. Less reliable than ``GFP_KERNEL``, but may be called + from interrupt context. You should **really** have a good + out-of-memory error-handling strategy. + + ``GFP_DMA`` + Allocate ISA DMA lower than 16MB. If you don't know what that is you + don't need it. Very unreliable. + + If you see a sleeping function called from invalid context warning + message, then maybe you called a sleeping allocation function from + interrupt context without ``GFP_ATOMIC``. You should really fix that. + Run, don't walk. + + If you are allocating at least ``PAGE_SIZE`` (``asm/page.h`` or + ``asm/page_types.h``) bytes, consider using :c:func:`__get_free_pages()` + (``include/linux/gfp.h``). 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. + + If you are allocating more than a page worth of bytes you can use + :c:func:`vmalloc()`. It'll allocate virtual memory in the kernel + map. This block is not contiguous in physical memory, but the MMU 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 :c:func:`alloc_bootmem()` + routine. + + Before inventing your own cache of often-used objects consider using a + slab cache in ``include/linux/slab.h`` + + :c:func:`current()` + ------------------- + + Defined in ``include/asm/current.h`` + + 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 **not NULL** in interrupt context. + + :c:func:`mdelay()`/:c:func:`udelay()` + ------------------------------------- + + Defined in ``include/asm/delay.h`` / ``include/linux/delay.h`` + + The :c:func:`udelay()` and :c:func:`ndelay()` functions can be + used for small pauses. Do not use large values with them as you risk + overflow - the helper function :c:func:`mdelay()` is useful here, or + consider :c:func:`msleep()`. + + :c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` + ----------------------------------------------------------------------------------------------- + + Defined in ``include/asm/byteorder.h`` + + The :c:func:`cpu_to_be32()` 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: + :c:func:`be32_to_cpu()`, etc. + + There are two major variations of these functions: the pointer + variation, such as :c:func:`cpu_to_be32p()`, which take a pointer + to the given type, and return the converted value. The other variation + is the "in-situ" family, such as :c:func:`cpu_to_be32s()`, which + convert value referred to by the pointer, and return void. + + :c:func:`local_irq_save()`/:c:func:`local_irq_restore()` + -------------------------------------------------------- + + Defined in ``include/linux/irqflags.h`` + + These routines disable hard interrupts on the local CPU, and restore + them. They are reentrant; saving the previous state in their one + ``unsigned long flags`` argument. If you know that interrupts are + enabled, you can simply use :c:func:`local_irq_disable()` and + :c:func:`local_irq_enable()`. + + .. _local_bh_disable: + + :c:func:`local_bh_disable()`/:c:func:`local_bh_enable()` + -------------------------------------------------------- + + Defined in ``include/linux/bottom_half.h`` + + + 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. + + :c:func:`smp_processor_id()` + ---------------------------- + + Defined in ``include/linux/smp.h`` + + :c:func:`get_cpu()` disables preemption (so you won't suddenly get + moved to another CPU) and returns the current processor number, between + 0 and ``NR_CPUS``. Note that the CPU numbers are not necessarily + continuous. You return it again with :c:func:`put_cpu()` when you + are done. + + 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(). + + ``__init``/``__exit``/``__initdata`` + ------------------------------------ + + Defined in ``include/linux/init.h`` + + After boot, the kernel frees up a special section; functions marked with + ``__init`` and data structures marked with ``__initdata`` are dropped + after boot is complete: similarly modules discard this memory after + initialization. ``__exit`` 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 ``__init`` to be exported to modules + with :c:func:`EXPORT_SYMBOL()` or :c:func:`EXPORT_SYMBOL_GPL()`- this + will break. + + :c:func:`__initcall()`/:c:func:`module_init()` + ---------------------------------------------- + + Defined in ``include/linux/init.h`` / ``include/linux/module.h`` + + Many parts of the kernel are well served as a module + (dynamically-loadable parts of the kernel). Using the + :c:func:`module_init()` and :c:func:`module_exit()` macros it + is easy to write code without #ifdefs which can operate both as a module + or built into the kernel. + + The :c:func:`module_init()` 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 + :c:func:`module_init()` macro becomes equivalent to + :c:func:`__initcall()`, which through linker magic ensures that + the function is called on boot. + + 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. + + :c:func:`module_exit()` + ----------------------- + + + Defined in ``include/linux/module.h`` + + 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. + + Note that this macro is optional: if it is not present, your module will + not be removable (except for 'rmmod -f'). + + :c:func:`try_module_get()`/:c:func:`module_put()` + ------------------------------------------------- + + Defined in ``include/linux/module.h`` + + 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 + :c:func:`try_module_get()` 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 + :c:func:`module_put()` when you're finished. + + Most registerable structures have an owner field, such as in the + :c:type:`struct file_operations ` structure. + Set this field to the macro ``THIS_MODULE``. + + Wait Queues ``include/linux/wait.h`` + ==================================== + + **[SLEEPS]** + + 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 :c:type:`wait_queue_head_t`, and then processes -which want to wait for that condition declare a :c:type:`wait_queue_t` ++which want to wait for that condition declare a :c:type:`wait_queue_entry_t` + referring to themselves, and place that in the queue. + + Declaring + --------- + + You declare a ``wait_queue_head_t`` using the + :c:func:`DECLARE_WAIT_QUEUE_HEAD()` macro, or using the + :c:func:`init_waitqueue_head()` routine in your initialization + code. + + Queuing + ------- + + 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: :c:func:`wait_event_interruptible()` + (``include/linux/wait.h``) The first argument is the wait queue head, and + the second is an expression which is evaluated; the macro returns 0 when + this expression is true, or ``-ERESTARTSYS`` if a signal is received. The + :c:func:`wait_event()` version ignores signals. + + Waking Up Queued Tasks + ---------------------- + + Call :c:func:`wake_up()` (``include/linux/wait.h``);, which will wake + up every process in the queue. The exception is if one has + ``TASK_EXCLUSIVE`` 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. + + Atomic Operations + ================= + + Certain operations are guaranteed atomic on all platforms. The first + class of operations work on :c:type:`atomic_t` (``include/asm/atomic.h``); + this contains a signed integer (at least 32 bits long), and you must use + these functions to manipulate or read :c:type:`atomic_t` variables. + :c:func:`atomic_read()` and :c:func:`atomic_set()` get and set + the counter, :c:func:`atomic_add()`, :c:func:`atomic_sub()`, + :c:func:`atomic_inc()`, :c:func:`atomic_dec()`, and + :c:func:`atomic_dec_and_test()` (returns true if it was + decremented to zero). + + Yes. It returns true (i.e. != 0) if the atomic variable is zero. + + Note that these functions are slower than normal arithmetic, and so + should not be used unnecessarily. + + The second class of atomic operations is atomic bit operations on an + ``unsigned long``, defined in ``include/linux/bitops.h``. These + operations generally take a pointer to the bit pattern, and a bit + number: 0 is the least significant bit. :c:func:`set_bit()`, + :c:func:`clear_bit()` and :c:func:`change_bit()` set, clear, + and flip the given bit. :c:func:`test_and_set_bit()`, + :c:func:`test_and_clear_bit()` and + :c:func:`test_and_change_bit()` do the same thing, except return + true if the bit was previously set; these are particularly useful for + atomically setting flags. + + 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. + + Symbols + ======= + + Within the kernel proper, the normal linking rules apply (ie. unless a + symbol is declared to be file scope with the ``static`` 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. + + :c:func:`EXPORT_SYMBOL()` + ------------------------- + + Defined in ``include/linux/export.h`` + + This is the classic method of exporting a symbol: dynamically loaded + modules will be able to use the symbol as normal. + + :c:func:`EXPORT_SYMBOL_GPL()` + ----------------------------- + + Defined in ``include/linux/export.h`` + + Similar to :c:func:`EXPORT_SYMBOL()` except that the symbols + exported by :c:func:`EXPORT_SYMBOL_GPL()` can only be seen by + modules with a :c:func:`MODULE_LICENSE()` 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. + + Routines and Conventions + ======================== + + Double-linked lists ``include/linux/list.h`` + -------------------------------------------- + + 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. + + In particular, :c:func:`list_for_each_entry()` is useful. + + Return Conventions + ------------------ + + For code called in user context, it's very common to defy C convention, + and return 0 for success, and a negative error number (eg. ``-EFAULT``) for + failure. This can be unintuitive at first, but it's fairly widespread in + the kernel. + + Using :c:func:`ERR_PTR()` (``include/linux/err.h``) to encode a + negative error number into a pointer, and :c:func:`IS_ERR()` and + :c:func:`PTR_ERR()` to get it back out again: avoids a separate + pointer parameter for the error number. Icky, but in a good way. + + Breaking Compilation + -------------------- + + 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 **worse**. + + Initializing structure members + ------------------------------ + + The preferred method of initializing structures is to use designated + initialisers, as defined by ISO C99, eg:: + + static struct block_device_operations opt_fops = { + .open = opt_open, + .release = opt_release, + .ioctl = opt_ioctl, + .check_media_change = opt_media_change, + }; + + + This makes it easy to grep for, and makes it clear which structure + fields are set. You should do this because it looks cool. + + GNU Extensions + -------------- + + 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). + + - Inline functions + + - Statement expressions (ie. the ({ and }) constructs). + + - Declaring attributes of a function / variable / type + (__attribute__) + + - typeof + + - Zero length arrays + + - Macro varargs + + - Arithmetic on void pointers + + - Non-Constant initializers + + - Assembler Instructions (not outside arch/ and include/asm/) + + - Function names as strings (__func__). + + - __builtin_constant_p() + + 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. + + C++ + --- + + 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. + + NUMif + ----- + + 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. + + Putting Your Stuff in the Kernel + ================================ + + 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: + + - Figure out whose pond you've been pissing in. Look at the top of the + source files, inside the ``MAINTAINERS`` file, and last of all in the + ``CREDITS`` file. You should coordinate with this person to make sure + you're not duplicating effort, or trying something that's already + been rejected. + + 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 **they** want to make a change. + + - Usually you want a configuration option for your kernel hack. Edit + ``Kconfig`` in the appropriate directory. The Config language is + simple to use by cut and paste, and there's complete documentation in + ``Documentation/kbuild/kconfig-language.txt``. + + 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. **Definitely** end your + description with “if in doubt, say N” (or, occasionally, \`Y'); this + is for people who have no idea what you are talking about. + + - Edit the ``Makefile``: the CONFIG variables are exported here so you + can usually just add a "obj-$(CONFIG_xxx) += xxx.o" line. The syntax + is documented in ``Documentation/kbuild/makefiles.txt``. + + - Put yourself in ``CREDITS`` if you've done something noteworthy, + usually beyond a single file (your name should be at the top of the + source files anyway). ``MAINTAINERS`` 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. + + - Finally, don't forget to read + ``Documentation/process/submitting-patches.rst`` and possibly + ``Documentation/process/submitting-drivers.rst``. + + Kernel Cantrips + =============== + + Some favorites from browsing the source. Feel free to add to this list. + + ``arch/x86/include/asm/delay.h``:: + + #define ndelay(n) (__builtin_constant_p(n) ? \ + ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \ + __ndelay(n)) + + + ``include/linux/fs.h``:: + + /* + * 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)) + + ``arch/x86/include/asm/uaccess_32.h:``:: + + #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))) + + + ``arch/sparc/kernel/head.S:``:: + + /* + * 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" + + + ``arch/sparc/lib/checksum.S:``:: + + /* 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. + */ + + + Thanks + ====== + + 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 :c:func:`disable_irq()`, and Jes + Sorensen and Andrea Arcangeli added caveats. Michael Elizabeth Chastain + for checking and adding to the Configure section. Telsa Gwynne for + teaching me DocBook.