^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. _kernel_hacking_hack:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Unreliable Guide To Hacking The Linux Kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) :Author: Rusty Russell
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) Kernel Hacking. This document describes the common routines and general
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) requirements for kernel code: its goal is to serve as a primer for Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) kernel development for experienced C programmers. I avoid implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) details: that's what the code is for, and I ignore whole tracts of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) useful routines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Before you read this, please understand that I never wanted to write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) this document, being grossly under-qualified, but I always wanted to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) read it, and this was the only way. I hope it will grow into a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) compendium of best practice, common starting points and random
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) The Players
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) At any time each of the CPUs in a system can be:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) - not associated with any process, serving a hardware interrupt;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) - not associated with any process, serving a softirq or tasklet;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) - running in kernel space, associated with a process (user context);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) - running a process in user space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) There is an ordering between these. The bottom two can preempt each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) other, but above that is a strict hierarchy: each can only be preempted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) by the ones above it. For example, while a softirq is running on a CPU,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) no other softirq will preempt it, but a hardware interrupt can. However,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) any other CPUs in the system execute independently.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) We'll see a number of ways that the user context can block interrupts,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) to become truly non-preemptable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) User Context
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) User context is when you are coming in from a system call or other trap:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) like userspace, you can be preempted by more important tasks and by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) interrupts. You can sleep, by calling :c:func:`schedule()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) You are always in user context on module load and unload, and on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) operations on the block device layer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) In user context, the ``current`` pointer (indicating the task we are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) currently executing) is valid, and :c:func:`in_interrupt()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) (``include/linux/preempt.h``) is false.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) Beware that if you have preemption or softirqs disabled (see below),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) :c:func:`in_interrupt()` will return a false positive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Hardware Interrupts (Hard IRQs)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) Timer ticks, network cards and keyboard are examples of real hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) which produce interrupts at any time. The kernel runs interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) handlers, which services the hardware. The kernel guarantees that this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) handler is never re-entered: if the same interrupt arrives, it is queued
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) (or dropped). Because it disables interrupts, this handler has to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) fast: frequently it simply acknowledges the interrupt, marks a 'software
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) interrupt' for execution and exits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) You can tell you are in a hardware interrupt, because
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) :c:func:`in_irq()` returns true.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) Beware that this will return a false positive if interrupts are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) disabled (see below).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) Software Interrupt Context: Softirqs and Tasklets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) -------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) Whenever a system call is about to return to userspace, or a hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) interrupt handler exits, any 'software interrupts' which are marked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) pending (usually by hardware interrupts) are run (``kernel/softirq.c``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) Much of the real interrupt handling work is done here. Early in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) transition to SMP, there were only 'bottom halves' (BHs), which didn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) take advantage of multiple CPUs. Shortly after we switched from wind-up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) computers made of match-sticks and snot, we abandoned this limitation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) and switched to 'softirqs'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) ``include/linux/interrupt.h`` lists the different softirqs. A very
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) important softirq is the timer softirq (``include/linux/timer.h``): you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) can register to have it call functions for you in a given length of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) Softirqs are often a pain to deal with, since the same softirq will run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) simultaneously on more than one CPU. For this reason, tasklets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) (``include/linux/interrupt.h``) are more often used: they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) dynamically-registrable (meaning you can have as many as you want), and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) they also guarantee that any tasklet will only run on one CPU at any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) time, although different tasklets can run simultaneously.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) The name 'tasklet' is misleading: they have nothing to do with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) 'tasks', and probably more to do with some bad vodka Alexey
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) Kuznetsov had at the time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) You can tell you are in a softirq (or tasklet) using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) :c:func:`in_softirq()` macro (``include/linux/preempt.h``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) Beware that this will return a false positive if a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) :ref:`botton half lock <local_bh_disable>` is held.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) Some Basic Rules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) No memory protection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) If you corrupt memory, whether in user context or interrupt context,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) the whole machine will crash. Are you sure you can't do what you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) want in userspace?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) No floating point or MMX
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) The FPU context is not saved; even in user context the FPU state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) probably won't correspond with the current process: you would mess
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) with some user process' FPU state. If you really want to do this,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) you would have to explicitly save/restore the full FPU state (and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) avoid context switches). It is generally a bad idea; use fixed point
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) arithmetic first.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) A rigid stack limit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) Depending on configuration options the kernel stack is about 3K to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 6K for most 32-bit architectures: it's about 14K on most 64-bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) archs, and often shared with interrupts so you can't use it all.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) Avoid deep recursion and huge local arrays on the stack (allocate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) them dynamically instead).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) The Linux kernel is portable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Let's keep it that way. Your code should be 64-bit clean, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) endian-independent. You should also minimize CPU specific stuff,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) e.g. inline assembly should be cleanly encapsulated and minimized to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) ease porting. Generally it should be restricted to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) architecture-dependent part of the kernel tree.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) ioctls: Not writing a new system call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) =====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) A system call generally looks like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) asmlinkage long sys_mycall(int arg)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) First, in most cases you don't want to create a new system call. You
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) create a character device and implement an appropriate ioctl for it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) This is much more flexible than system calls, doesn't have to be entered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) in every architecture's ``include/asm/unistd.h`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) ``arch/kernel/entry.S`` file, and is much more likely to be accepted by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) Linus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) If all your routine does is read or write some parameter, consider
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) implementing a :c:func:`sysfs()` interface instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) Inside the ioctl you're in user context to a process. When a error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) occurs you return a negated errno (see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) ``include/uapi/asm-generic/errno-base.h``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) ``include/uapi/asm-generic/errno.h`` and ``include/linux/errno.h``),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) otherwise you return 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) After you slept you should check if a signal occurred: the Unix/Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) way of handling signals is to temporarily exit the system call with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) ``-ERESTARTSYS`` error. The system call entry code will switch back to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) user context, process the signal handler and then your system call will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) be restarted (unless the user disabled that). So you should be prepared
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) to process the restart, e.g. if you're in the middle of manipulating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) some data structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) if (signal_pending(current))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) return -ERESTARTSYS;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) If you're doing longer computations: first think userspace. If you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) **really** want to do it in kernel you should regularly check if you need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) to give up the CPU (remember there is cooperative multitasking per CPU).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) Idiom::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) cond_resched(); /* Will sleep */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) A short note on interface design: the UNIX system call motto is "Provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) mechanism not policy".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) Recipes for Deadlock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) You cannot call any routines which may sleep, unless:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) - You are in user context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) - You do not own any spinlocks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) - You have interrupts enabled (actually, Andi Kleen says that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) scheduling code will enable them for you, but that's probably not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) what you wanted).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) Note that some functions may sleep implicitly: common ones are the user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) space access functions (\*_user) and memory allocation functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) without ``GFP_ATOMIC``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) You should always compile your kernel ``CONFIG_DEBUG_ATOMIC_SLEEP`` on,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) and it will warn you if you break these rules. If you **do** break the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) rules, you will eventually lock up your box.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) Really.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) Common Routines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) :c:func:`printk()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) Defined in ``include/linux/printk.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) :c:func:`printk()` feeds kernel messages to the console, dmesg, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) the syslog daemon. It is useful for debugging and reporting errors, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) can be used inside interrupt context, but use with caution: a machine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) which has its console flooded with printk messages is unusable. It uses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) a format string mostly compatible with ANSI C printf, and C string
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) concatenation to give it a first "priority" argument::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) printk(KERN_INFO "i = %u\n", i);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) See ``include/linux/kern_levels.h``; for other ``KERN_`` values; these are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) interpreted by syslog as the level. Special case: for printing an IP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) address use::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) __be32 ipaddress;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) printk(KERN_INFO "my ip: %pI4\n", &ipaddress);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) :c:func:`printk()` internally uses a 1K buffer and does not catch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) overruns. Make sure that will be enough.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) You will know when you are a real kernel hacker when you start
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) typoing printf as printk in your user programs :)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) Another sidenote: the original Unix Version 6 sources had a comment
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) on top of its printf function: "Printf should not be used for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) chit-chat". You should follow that advice.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) :c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) ---------------------------------------------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) **[SLEEPS]**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) :c:func:`put_user()` and :c:func:`get_user()` are used to get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) and put single values (such as an int, char, or long) from and to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) userspace. A pointer into userspace should never be simply dereferenced:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) data should be copied using these routines. Both return ``-EFAULT`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) :c:func:`copy_to_user()` and :c:func:`copy_from_user()` are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) more general: they copy an arbitrary amount of data to and from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) Unlike :c:func:`put_user()` and :c:func:`get_user()`, they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) return the amount of uncopied data (ie. 0 still means success).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) [Yes, this moronic interface makes me cringe. The flamewar comes up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) every year or so. --RR.]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) The functions may sleep implicitly. This should never be called outside
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) user context (it makes no sense), with interrupts disabled, or a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) spinlock held.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) :c:func:`kmalloc()`/:c:func:`kfree()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) -------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) Defined in ``include/linux/slab.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) **[MAY SLEEP: SEE BELOW]**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) These routines are used to dynamically request pointer-aligned chunks of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) memory, like malloc and free do in userspace, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) :c:func:`kmalloc()` takes an extra flag word. Important values:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) ``GFP_KERNEL``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) May sleep and swap to free memory. Only allowed in user context, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) is the most reliable way to allocate memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) ``GFP_ATOMIC``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) Don't sleep. Less reliable than ``GFP_KERNEL``, but may be called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) from interrupt context. You should **really** have a good
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) out-of-memory error-handling strategy.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) ``GFP_DMA``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) Allocate ISA DMA lower than 16MB. If you don't know what that is you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) don't need it. Very unreliable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) If you see a sleeping function called from invalid context warning
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) message, then maybe you called a sleeping allocation function from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) interrupt context without ``GFP_ATOMIC``. You should really fix that.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) Run, don't walk.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) If you are allocating at least ``PAGE_SIZE`` (``asm/page.h`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) ``asm/page_types.h``) bytes, consider using :c:func:`__get_free_pages()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) (``include/linux/gfp.h``). It takes an order argument (0 for page sized,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) 1 for double page, 2 for four pages etc.) and the same memory priority
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) flag word as above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) If you are allocating more than a page worth of bytes you can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) :c:func:`vmalloc()`. It'll allocate virtual memory in the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) map. This block is not contiguous in physical memory, but the MMU makes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) it look like it is for you (so it'll only look contiguous to the CPUs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) not to external device drivers). If you really need large physically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) contiguous memory for some weird device, you have a problem: it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) poorly supported in Linux because after some time memory fragmentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) in a running kernel makes it hard. The best way is to allocate the block
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) early in the boot process via the :c:func:`alloc_bootmem()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) routine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) Before inventing your own cache of often-used objects consider using a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) slab cache in ``include/linux/slab.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) :c:func:`current()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) Defined in ``include/asm/current.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) This global variable (really a macro) contains a pointer to the current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) task structure, so is only valid in user context. For example, when a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) process makes a system call, this will point to the task structure of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) the calling process. It is **not NULL** in interrupt context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) :c:func:`mdelay()`/:c:func:`udelay()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) -------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) Defined in ``include/asm/delay.h`` / ``include/linux/delay.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) The :c:func:`udelay()` and :c:func:`ndelay()` functions can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) used for small pauses. Do not use large values with them as you risk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) overflow - the helper function :c:func:`mdelay()` is useful here, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) consider :c:func:`msleep()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) :c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) -----------------------------------------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) Defined in ``include/asm/byteorder.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) The :c:func:`cpu_to_be32()` family (where the "32" can be replaced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) by 64 or 16, and the "be" can be replaced by "le") are the general way
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) to do endian conversions in the kernel: they return the converted value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) All variations supply the reverse as well:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) :c:func:`be32_to_cpu()`, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) There are two major variations of these functions: the pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) variation, such as :c:func:`cpu_to_be32p()`, which take a pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) to the given type, and return the converted value. The other variation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) is the "in-situ" family, such as :c:func:`cpu_to_be32s()`, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) convert value referred to by the pointer, and return void.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) :c:func:`local_irq_save()`/:c:func:`local_irq_restore()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) --------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) Defined in ``include/linux/irqflags.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) These routines disable hard interrupts on the local CPU, and restore
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) them. They are reentrant; saving the previous state in their one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) ``unsigned long flags`` argument. If you know that interrupts are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) enabled, you can simply use :c:func:`local_irq_disable()` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) :c:func:`local_irq_enable()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) .. _local_bh_disable:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) :c:func:`local_bh_disable()`/:c:func:`local_bh_enable()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) --------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) Defined in ``include/linux/bottom_half.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) These routines disable soft interrupts on the local CPU, and restore
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) them. They are reentrant; if soft interrupts were disabled before, they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) will still be disabled after this pair of functions has been called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) They prevent softirqs and tasklets from running on the current CPU.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) :c:func:`smp_processor_id()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) Defined in ``include/linux/smp.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) :c:func:`get_cpu()` disables preemption (so you won't suddenly get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) moved to another CPU) and returns the current processor number, between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) 0 and ``NR_CPUS``. Note that the CPU numbers are not necessarily
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) continuous. You return it again with :c:func:`put_cpu()` when you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) are done.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) If you know you cannot be preempted by another task (ie. you are in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) interrupt context, or have preemption disabled) you can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) smp_processor_id().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) ``__init``/``__exit``/``__initdata``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) ------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) Defined in ``include/linux/init.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) After boot, the kernel frees up a special section; functions marked with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) ``__init`` and data structures marked with ``__initdata`` are dropped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) after boot is complete: similarly modules discard this memory after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) initialization. ``__exit`` is used to declare a function which is only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) required on exit: the function will be dropped if this file is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) compiled as a module. See the header file for use. Note that it makes no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) sense for a function marked with ``__init`` to be exported to modules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) with :c:func:`EXPORT_SYMBOL()` or :c:func:`EXPORT_SYMBOL_GPL()`- this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) will break.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) :c:func:`__initcall()`/:c:func:`module_init()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) ----------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) Defined in ``include/linux/init.h`` / ``include/linux/module.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) Many parts of the kernel are well served as a module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) (dynamically-loadable parts of the kernel). Using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) :c:func:`module_init()` and :c:func:`module_exit()` macros it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) is easy to write code without #ifdefs which can operate both as a module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) or built into the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) The :c:func:`module_init()` macro defines which function is to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) called at module insertion time (if the file is compiled as a module),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) or at boot time: if the file is not compiled as a module the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) :c:func:`module_init()` macro becomes equivalent to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) :c:func:`__initcall()`, which through linker magic ensures that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) the function is called on boot.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) The function can return a negative error number to cause module loading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) to fail (unfortunately, this has no effect if the module is compiled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) into the kernel). This function is called in user context with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) interrupts enabled, so it can sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) :c:func:`module_exit()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) Defined in ``include/linux/module.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) This macro defines the function to be called at module removal time (or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) never, in the case of the file compiled into the kernel). It will only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) be called if the module usage count has reached zero. This function can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) also sleep, but cannot fail: everything must be cleaned up by the time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) it returns.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) Note that this macro is optional: if it is not present, your module will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) not be removable (except for 'rmmod -f').
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) :c:func:`try_module_get()`/:c:func:`module_put()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) -------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) Defined in ``include/linux/module.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) These manipulate the module usage count, to protect against removal (a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) module also can't be removed if another module uses one of its exported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) symbols: see below). Before calling into module code, you should call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) :c:func:`try_module_get()` on that module: if it fails, then the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) module is being removed and you should act as if it wasn't there.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) Otherwise, you can safely enter the module, and call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) :c:func:`module_put()` when you're finished.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) Most registerable structures have an owner field, such as in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) :c:type:`struct file_operations <file_operations>` structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) Set this field to the macro ``THIS_MODULE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) Wait Queues ``include/linux/wait.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) ====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) **[SLEEPS]**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) A wait queue is used to wait for someone to wake you up when a certain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) condition is true. They must be used carefully to ensure there is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) race condition. You declare a :c:type:`wait_queue_head_t`, and then processes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) which want to wait for that condition declare a :c:type:`wait_queue_entry_t`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) referring to themselves, and place that in the queue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) Declaring
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) ---------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) You declare a ``wait_queue_head_t`` using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) :c:func:`DECLARE_WAIT_QUEUE_HEAD()` macro, or using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) :c:func:`init_waitqueue_head()` routine in your initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) Queuing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) Placing yourself in the waitqueue is fairly complex, because you must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) put yourself in the queue before checking the condition. There is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) macro to do this: :c:func:`wait_event_interruptible()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) (``include/linux/wait.h``) The first argument is the wait queue head, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) the second is an expression which is evaluated; the macro returns 0 when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) this expression is true, or ``-ERESTARTSYS`` if a signal is received. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) :c:func:`wait_event()` version ignores signals.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) Waking Up Queued Tasks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) Call :c:func:`wake_up()` (``include/linux/wait.h``), which will wake
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) up every process in the queue. The exception is if one has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) ``TASK_EXCLUSIVE`` set, in which case the remainder of the queue will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) not be woken. There are other variants of this basic function available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) in the same header.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) Atomic Operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) Certain operations are guaranteed atomic on all platforms. The first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) class of operations work on :c:type:`atomic_t` (``include/asm/atomic.h``);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) this contains a signed integer (at least 32 bits long), and you must use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) these functions to manipulate or read :c:type:`atomic_t` variables.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) :c:func:`atomic_read()` and :c:func:`atomic_set()` get and set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) the counter, :c:func:`atomic_add()`, :c:func:`atomic_sub()`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) :c:func:`atomic_inc()`, :c:func:`atomic_dec()`, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) :c:func:`atomic_dec_and_test()` (returns true if it was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) decremented to zero).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) Yes. It returns true (i.e. != 0) if the atomic variable is zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) Note that these functions are slower than normal arithmetic, and so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) should not be used unnecessarily.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) The second class of atomic operations is atomic bit operations on an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) ``unsigned long``, defined in ``include/linux/bitops.h``. These
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) operations generally take a pointer to the bit pattern, and a bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) number: 0 is the least significant bit. :c:func:`set_bit()`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) :c:func:`clear_bit()` and :c:func:`change_bit()` set, clear,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) and flip the given bit. :c:func:`test_and_set_bit()`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) :c:func:`test_and_clear_bit()` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) :c:func:`test_and_change_bit()` do the same thing, except return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) true if the bit was previously set; these are particularly useful for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) atomically setting flags.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) It is possible to call these operations with bit indices greater than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) ``BITS_PER_LONG``. The resulting behavior is strange on big-endian
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) platforms though so it is a good idea not to do this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) Symbols
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) Within the kernel proper, the normal linking rules apply (ie. unless a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) symbol is declared to be file scope with the ``static`` keyword, it can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) be used anywhere in the kernel). However, for modules, a special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) exported symbol table is kept which limits the entry points to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) kernel proper. Modules can also export symbols.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) :c:func:`EXPORT_SYMBOL()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) Defined in ``include/linux/export.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) This is the classic method of exporting a symbol: dynamically loaded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) modules will be able to use the symbol as normal.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) :c:func:`EXPORT_SYMBOL_GPL()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) Defined in ``include/linux/export.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) Similar to :c:func:`EXPORT_SYMBOL()` except that the symbols
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) exported by :c:func:`EXPORT_SYMBOL_GPL()` can only be seen by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) modules with a :c:func:`MODULE_LICENSE()` that specifies a GPL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) compatible license. It implies that the function is considered an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) internal implementation issue, and not really an interface. Some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) maintainers and developers may however require EXPORT_SYMBOL_GPL()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) when adding any new APIs or functionality.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) :c:func:`EXPORT_SYMBOL_NS()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) Defined in ``include/linux/export.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) namespace. Symbol Namespaces are documented in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) :doc:`../core-api/symbol-namespaces`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) :c:func:`EXPORT_SYMBOL_NS_GPL()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) Defined in ``include/linux/export.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) namespace. Symbol Namespaces are documented in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) :doc:`../core-api/symbol-namespaces`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) Routines and Conventions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) Double-linked lists ``include/linux/list.h``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) --------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) There used to be three sets of linked-list routines in the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) headers, but this one is the winner. If you don't have some particular
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) pressing need for a single list, it's a good choice.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) In particular, :c:func:`list_for_each_entry()` is useful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) Return Conventions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) For code called in user context, it's very common to defy C convention,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) and return 0 for success, and a negative error number (eg. ``-EFAULT``) for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) failure. This can be unintuitive at first, but it's fairly widespread in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) Using :c:func:`ERR_PTR()` (``include/linux/err.h``) to encode a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) negative error number into a pointer, and :c:func:`IS_ERR()` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) :c:func:`PTR_ERR()` to get it back out again: avoids a separate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) pointer parameter for the error number. Icky, but in a good way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) Breaking Compilation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) Linus and the other developers sometimes change function or structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) names in development kernels; this is not done just to keep everyone on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) their toes: it reflects a fundamental change (eg. can no longer be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) called with interrupts on, or does extra checks, or doesn't do checks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) which were caught before). Usually this is accompanied by a fairly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) complete note to the linux-kernel mailing list; search the archive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) Simply doing a global replace on the file usually makes things **worse**.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) Initializing structure members
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) The preferred method of initializing structures is to use designated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) initialisers, as defined by ISO C99, eg::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) static struct block_device_operations opt_fops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) .open = opt_open,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659) .release = opt_release,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) .ioctl = opt_ioctl,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) .check_media_change = opt_media_change,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665) This makes it easy to grep for, and makes it clear which structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) fields are set. You should do this because it looks cool.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) GNU Extensions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) GNU Extensions are explicitly allowed in the Linux kernel. Note that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) some of the more complex ones are not very well supported, due to lack
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) of general use, but the following are considered standard (see the GCC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674) info page section "C Extensions" for more details - Yes, really the info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) page, the man page is only a short summary of the stuff in info).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) - Inline functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) - Statement expressions (ie. the ({ and }) constructs).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) - Declaring attributes of a function / variable / type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) (__attribute__)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) - typeof
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) - Zero length arrays
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) - Macro varargs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) - Arithmetic on void pointers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) - Non-Constant initializers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) - Assembler Instructions (not outside arch/ and include/asm/)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) - Function names as strings (__func__).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) - __builtin_constant_p()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) Be wary when using long long in the kernel, the code gcc generates for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) it is horrible and worse: division and multiplication does not work on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) i386 because the GCC runtime functions for it are missing from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) kernel environment.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) C++
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) ---
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) Using C++ in the kernel is usually a bad idea, because the kernel does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) not provide the necessary runtime environment and the include files are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) not tested for it. It is still possible, but not recommended. If you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) really want to do this, forget about exceptions at least.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) #if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) ---
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) It is generally considered cleaner to use macros in header files (or at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) the top of .c files) to abstract away functions rather than using \`#if'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) pre-processor statements throughout the source code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) Putting Your Stuff in the Kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) ================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723) In order to get your stuff into shape for official inclusion, or even to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) make a neat patch, there's administrative work to be done:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) - Figure out whose pond you've been pissing in. Look at the top of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) source files, inside the ``MAINTAINERS`` file, and last of all in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) ``CREDITS`` file. You should coordinate with this person to make sure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) you're not duplicating effort, or trying something that's already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) been rejected.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) Make sure you put your name and EMail address at the top of any files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) you create or mangle significantly. This is the first place people
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) will look when they find a bug, or when **they** want to make a change.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) - Usually you want a configuration option for your kernel hack. Edit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) ``Kconfig`` in the appropriate directory. The Config language is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) simple to use by cut and paste, and there's complete documentation in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) ``Documentation/kbuild/kconfig-language.rst``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741) In your description of the option, make sure you address both the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) expert user and the user who knows nothing about your feature.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) Mention incompatibilities and issues here. **Definitely** end your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) description with “if in doubt, say N” (or, occasionally, \`Y'); this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745) is for people who have no idea what you are talking about.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747) - Edit the ``Makefile``: the CONFIG variables are exported here so you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) can usually just add a "obj-$(CONFIG_xxx) += xxx.o" line. The syntax
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749) is documented in ``Documentation/kbuild/makefiles.rst``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751) - Put yourself in ``CREDITS`` if you've done something noteworthy,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) usually beyond a single file (your name should be at the top of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753) source files anyway). ``MAINTAINERS`` means you want to be consulted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754) when changes are made to a subsystem, and hear about bugs; it implies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) a more-than-passing commitment to some part of the code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) - Finally, don't forget to read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758) ``Documentation/process/submitting-patches.rst`` and possibly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) ``Documentation/process/submitting-drivers.rst``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) Kernel Cantrips
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764) Some favorites from browsing the source. Feel free to add to this list.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766) ``arch/x86/include/asm/delay.h``::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768) #define ndelay(n) (__builtin_constant_p(n) ? \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) __ndelay(n))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) ``include/linux/fs.h``::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776) * Kernel pointers have redundant information, so we can use a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777) * scheme where we can return either an error code or a dentry
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778) * pointer with the same return value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) * This should be a per-architecture thing, to allow different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781) * error and pointer decisions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) #define ERR_PTR(err) ((void *)((long)(err)))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) #define PTR_ERR(ptr) ((long)(ptr))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785) #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787) ``arch/x86/include/asm/uaccess_32.h:``::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789) #define copy_to_user(to,from,n) \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) (__builtin_constant_p(n) ? \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791) __constant_copy_to_user((to),(from),(n)) : \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792) __generic_copy_to_user((to),(from),(n)))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) ``arch/sparc/kernel/head.S:``::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798) * Sun people can't spell worth damn. "compatability" indeed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799) * At least we *know* we can't spell, and use a spell-checker.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802) /* Uh, actually Linus it is I who cannot spell. Too much murky
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) * Sparc assembly will do this to ya.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) C_LABEL(cputypvar):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806) .asciz "compatibility"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809) .align 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) C_LABEL(cputypvar_sun4m):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) .asciz "compatible"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) ``arch/sparc/lib/checksum.S:``::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) /* Sun, you just can't beat me, you just can't. Stop trying,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) * give up. I'm serious, I am going to kick the living shit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) * out of you, game over, lights out.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) Thanks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) ======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825) Thanks to Andi Kleen for the idea, answering my questions, fixing my
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826) mistakes, filling content, etc. Philipp Rumpf for more spelling and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827) clarity fixes, and some excellent non-obvious points. Werner Almesberger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828) for giving me a great summary of :c:func:`disable_irq()`, and Jes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829) Sorensen and Andrea Arcangeli added caveats. Michael Elizabeth Chastain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) for checking and adding to the Configure section. Telsa Gwynne for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) teaching me DocBook.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags