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