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.
44 We'll see a number of ways that the user context can block interrupts,
45 to become truly non-preemptable.
47 User Context
48 ------------
50 User context is when you are coming in from a system call or other trap:
56     You are always in user context on module load and unload, and on
59 In user context, the ``current`` pointer (indicating the task we are
69 -------------------------------
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
108 dynamically-registrable (meaning you can have as many as you want), and
130     If you corrupt memory, whether in user context or interrupt context,
135     The FPU context is not saved; even in user context the FPU state
137     with some user process' FPU state. If you really want to do this,
144     6K for most 32-bit architectures: it's about 14K on most 64-bit
150     Let's keep it that way. Your code should be 64-bit clean, and
151     endian-independent. You should also minimize CPU specific stuff,
154     architecture-dependent part of the kernel tree.
177 Inside the ioctl you're in user context to a process. When a error
179 ``include/uapi/asm-generic/errno-base.h``,
180 ``include/uapi/asm-generic/errno.h`` and ``include/linux/errno.h``),
185 ``-ERESTARTSYS`` error. The system call entry code will switch back to
186 user context, process the signal handler and then your system call will
187 be restarted (unless the user disabled that). So you should be prepared
194             return -ERESTARTSYS;
213 -  You are in user context.
215 -  You do not own any spinlocks.
217 -  You have interrupts enabled (actually, Andi Kleen says that the
221 Note that some functions may sleep implicitly: common ones are the user
235 ------------------
237 Defined in ``include/linux/printk.h``
263     typoing printf as printk in your user programs :)
269     chit-chat". You should follow that advice.
272 ---------------------------------------------------------------------------------------------------
274 Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h``
281 data should be copied using these routines. Both return ``-EFAULT`` or
294 every year or so. --RR.]
297 user context (it makes no sense), with interrupts disabled, or a
301 -------------------------------------
303 Defined in ``include/linux/slab.h``
307 These routines are used to dynamically request pointer-aligned chunks of
312     May sleep and swap to free memory. Only allowed in user context, but
318     out-of-memory error-handling strategy.
346 Before inventing your own cache of often-used objects consider using a
350 -------------------
352 Defined in ``include/asm/current.h``
355 task structure, so is only valid in user context. For example, when a
360 -------------------------------------
362 Defined in ``include/asm/delay.h`` / ``include/linux/delay.h``
366 overflow - the helper function :c:func:`mdelay()` is useful here, or
370 -----------------------------------------------------------------------------------------------
372 Defined in ``include/asm/byteorder.h``
383 is the "in-situ" family, such as :c:func:`cpu_to_be32s()`, which
387 --------------------------------------------------------
389 Defined in ``include/linux/irqflags.h``
400 --------------------------------------------------------
402 Defined in ``include/linux/bottom_half.h``
411 ----------------------------
413 Defined in ``include/linux/smp.h``
426 ------------------------------------
428 Defined in  ``include/linux/init.h``
437 with :c:func:`EXPORT_SYMBOL()` or :c:func:`EXPORT_SYMBOL_GPL()`- this
441 ----------------------------------------------
443 Defined in  ``include/linux/init.h`` / ``include/linux/module.h``
446 (dynamically-loadable parts of the kernel). Using the
460 into the kernel). This function is called in user context with
464 -----------------------
467 Defined in  ``include/linux/module.h``
476 not be removable (except for 'rmmod -f').
479 -------------------------------------------------
481 Defined in ``include/linux/module.h``
507 ---------
515 -------
522 this expression is true, or ``-ERESTARTSYS`` if a signal is received. The
526 ----------------------
553 ``unsigned long``, defined in ``include/linux/bitops.h``. These
564 ``BITS_PER_LONG``. The resulting behavior is strange on big-endian
577 -------------------------
579 Defined in ``include/linux/export.h``
585 -----------------------------
587 Defined in ``include/linux/export.h``
598 ----------------------------
600 Defined in ``include/linux/export.h``
604 :doc:`../core-api/symbol-namespaces`
607 --------------------------------
609 Defined in ``include/linux/export.h``
613 :doc:`../core-api/symbol-namespaces`
618 Double-linked lists ``include/linux/list.h``
619 --------------------------------------------
621 There used to be three sets of linked-list routines in the kernel
628 ------------------
630 For code called in user context, it's very common to defy C convention,
631 and return 0 for success, and a negative error number (eg. ``-EFAULT``) for
641 --------------------
648 complete note to the linux-kernel mailing list; search the archive.
652 ------------------------------
655 initialisers, as defined by ISO C99, eg::
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 whose pond you've been pissing in. Look at the top of the
736 -  Usually you want a configuration option for your kernel hack. Edit
739    ``Documentation/kbuild/kconfig-language.rst``.
742    expert user and the user who knows nothing about your feature.
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've done something noteworthy,
755    a more-than-passing commitment to some part of the code.
757 -  Finally, don't forget to read
758    ``Documentation/process/submitting-patches.rst`` and possibly
759    ``Documentation/process/submitting-drivers.rst``.
780      * This should be a per-architecture thing, to allow different
785      #define IS_ERR(ptr)     ((unsigned long)(ptr) > (unsigned long)(-1000))
799      * At least we *know* we can't spell, and use a spell-checker.
808     /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */
827 clarity fixes, and some excellent non-obvious points. Werner Almesberger