Documentation/kernel-hacking/hacking.rst

20 this document, being grossly under-qualified, but I always wanted to
30 -  not associated with any process, serving a hardware interrupt;
32 -  not associated with any process, serving a softirq or tasklet;
34 -  running in kernel space, associated with a process (user context);
36 -  running a process in user space.
40 by the ones above it. For example, while a softirq is running on a CPU,
45 to become truly non-preemptable.
48 ------------
69 -------------------------------
71 Timer ticks, network cards and keyboard are examples of real hardware
74 handler is never re-entered: if the same interrupt arrives, it is queued
88 -------------------------------------------------
96 take advantage of multiple CPUs. Shortly after we switched from wind-up
97 computers made of match-sticks and snot, we abandoned this limitation
101 important softirq is the timer softirq (``include/linux/timer.h``): you
106 simultaneously on more than one CPU. For this reason, tasklets
108 dynamically-registrable (meaning you can have as many as you want), and
109 they also guarantee that any tasklet will only run on one CPU at any
143     6K for most 32-bit architectures: it's about 14K on most 64-bit
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,
153     architecture-dependent part of the kernel tree.
178 ``include/uapi/asm-generic/errno-base.h``,
179 ``include/uapi/asm-generic/errno.h`` and ``include/linux/errno.h``),
184 ``-ERESTARTSYS`` error. The system call entry code will switch back to
193             return -ERESTARTSYS;
198 to give up the CPU (remember there is cooperative multitasking per CPU).
210 You cannot call any routines which may sleep, unless:
212 -  You are in user context.
214 -  You do not own any spinlocks.
216 -  You have interrupts enabled (actually, Andi Kleen says that the
234 ------------------
268     chit-chat". You should follow that advice.
271 ---------------------------------------------------------------------------------------------------
280 data should be copied using these routines. Both return ``-EFAULT`` or
293 up every year or so. --RR.]
300 -------------------------------------
306 These routines are used to dynamically request pointer-aligned chunks of
317     out-of-memory error-handling strategy.
345 Before inventing your own cache of often-used objects consider using a
349 ------------------
359 -------------------------------------
365 overflow - the helper function :c:func:`mdelay()` is useful here, or
369 -----------------------------------------------------------------------------------------------
382 is the "in-situ" family, such as :c:func:`cpu_to_be32s()`, which
386 --------------------------------------------------------
390 These routines disable hard interrupts on the local CPU, and restore
399 --------------------------------------------------------
404 These routines disable soft interrupts on the local CPU, and restore
407 They prevent softirqs and tasklets from running on the current CPU.
410 ----------------------------
415 moved to another CPU) and returns the current processor number, between
416 0 and ``NR_CPUS``. Note that the CPU numbers are not necessarily
420 If you know you cannot be preempted by another task (ie. you are in
425 ------------------------------------
436 with :c:func:`EXPORT_SYMBOL()` or :c:func:`EXPORT_SYMBOL_GPL()`- this
440 ----------------------------------------------
445 (dynamically-loadable parts of the kernel). Using the
463 -----------------------
471 also sleep, but cannot fail: everything must be cleaned up by the time
475 not be removable (except for 'rmmod -f').
478 -------------------------------------------------
499 A wait queue is used to wait for someone to wake you up when a certain
506 ---------
514 -------
521 this expression is true, or ``-ERESTARTSYS`` if a signal is received. The
525 ----------------------
527 Call :c:func:`wake_up()` (``include/linux/wait.h``), which will wake
563 ``BITS_PER_LONG``. The resulting behavior is strange on big-endian
576 -------------------------
584 -----------------------------
597 ----------------------------
603 Documentation/core-api/symbol-namespaces.rst
606 --------------------------------
612 Documentation/core-api/symbol-namespaces.rst
617 Double-linked lists ``include/linux/list.h``
618 --------------------------------------------
620 There used to be three sets of linked-list routines in the kernel
627 ------------------
630 and return 0 for success, and a negative error number (eg. ``-EFAULT``) for
640 --------------------
652 ------------------------------
669 --------------
674 info page section "C Extensions" for more details - Yes, really the info
677 -  Inline functions
679 -  Statement expressions (ie. the ({ and }) constructs).
681 -  Declaring attributes of a function / variable / type
684 -  typeof
686 -  Zero length arrays
688 -  Macro varargs
690 -  Arithmetic on void pointers
692 -  Non-Constant initializers
694 -  Assembler Instructions (not outside arch/ and include/asm/)
696 -  Function names as strings (__func__).
698 -  __builtin_constant_p()
706 ---
714 ---
718 pre-processor statements throughout the source code.
726 -  Figure out who are the owners of the code you've been modifying. Look
736 -  Usually you want a configuration option for your kernel hack. Edit
739    ``Documentation/kbuild/kconfig-language.rst``.
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
751 -  Put yourself in ``CREDITS`` if you consider what you've done
755    it implies a more-than-passing commitment to some part of the code.
757 -  Finally, don't forget to read
758    ``Documentation/process/submitting-patches.rst``
779      * This should be a per-architecture thing, to allow different
784      #define IS_ERR(ptr)     ((unsigned long)(ptr) > (unsigned long)(-1000))
798      * At least we *know* we can't spell, and use a spell-checker.
801     /* Uh, actually Linus it is I who cannot spell. Too much murky
807     /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */
826 clarity fixes, and some excellent non-obvious points. Werner Almesberger