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 80:c:func:`in_irq()` returns true. 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', and probably more to do with some bad vodka Alexey 116 Kuznetsov had at the time. 117 118You can tell you are in a softirq (or tasklet) using the 119:c:func:`in_softirq()` macro (``include/linux/preempt.h``). 120 121.. warning:: 122 123 Beware that this will return a false positive if a 124 :ref:`botton half lock <local_bh_disable>` is held. 125 126Some Basic Rules 127================ 128 129No memory protection 130 If you corrupt memory, whether in user context or interrupt context, 131 the whole machine will crash. Are you sure you can't do what you 132 want in userspace? 133 134No floating point or MMX 135 The FPU context is not saved; even in user context the FPU state 136 probably won't correspond with the current process: you would mess 137 with some user process' FPU state. If you really want to do this, 138 you would have to explicitly save/restore the full FPU state (and 139 avoid context switches). It is generally a bad idea; use fixed point 140 arithmetic first. 141 142A rigid stack limit 143 Depending on configuration options the kernel stack is about 3K to 144 6K for most 32-bit architectures: it's about 14K on most 64-bit 145 archs, and often shared with interrupts so you can't use it all. 146 Avoid deep recursion and huge local arrays on the stack (allocate 147 them dynamically instead). 148 149The Linux kernel is portable 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, 152 e.g. inline assembly should be cleanly encapsulated and minimized to 153 ease porting. Generally it should be restricted to the 154 architecture-dependent part of the kernel tree. 155 156ioctls: Not writing a new system call 157===================================== 158 159A system call generally looks like this:: 160 161 asmlinkage long sys_mycall(int arg) 162 { 163 return 0; 164 } 165 166 167First, in most cases you don't want to create a new system call. You 168create a character device and implement an appropriate ioctl for it. 169This is much more flexible than system calls, doesn't have to be entered 170in every architecture's ``include/asm/unistd.h`` and 171``arch/kernel/entry.S`` file, and is much more likely to be accepted by 172Linus. 173 174If all your routine does is read or write some parameter, consider 175implementing a :c:func:`sysfs()` interface instead. 176 177Inside the ioctl you're in user context to a process. When a error 178occurs you return a negated errno (see 179``include/uapi/asm-generic/errno-base.h``, 180``include/uapi/asm-generic/errno.h`` and ``include/linux/errno.h``), 181otherwise you return 0. 182 183After you slept you should check if a signal occurred: the Unix/Linux 184way of handling signals is to temporarily exit the system call with the 185``-ERESTARTSYS`` error. The system call entry code will switch back to 186user context, process the signal handler and then your system call will 187be restarted (unless the user disabled that). So you should be prepared 188to process the restart, e.g. if you're in the middle of manipulating 189some data structure. 190 191:: 192 193 if (signal_pending(current)) 194 return -ERESTARTSYS; 195 196 197If you're doing longer computations: first think userspace. If you 198**really** want to do it in kernel you should regularly check if you need 199to give up the CPU (remember there is cooperative multitasking per CPU). 200Idiom:: 201 202 cond_resched(); /* Will sleep */ 203 204 205A short note on interface design: the UNIX system call motto is "Provide 206mechanism not policy". 207 208Recipes for Deadlock 209==================== 210 211You cannot call any routines which may sleep, unless: 212 213- You are in user context. 214 215- You do not own any spinlocks. 216 217- You have interrupts enabled (actually, Andi Kleen says that the 218 scheduling code will enable them for you, but that's probably not 219 what you wanted). 220 221Note that some functions may sleep implicitly: common ones are the user 222space access functions (\*_user) and memory allocation functions 223without ``GFP_ATOMIC``. 224 225You should always compile your kernel ``CONFIG_DEBUG_ATOMIC_SLEEP`` on, 226and it will warn you if you break these rules. If you **do** break the 227rules, you will eventually lock up your box. 228 229Really. 230 231Common Routines 232=============== 233 234:c:func:`printk()` 235------------------ 236 237Defined in ``include/linux/printk.h`` 238 239:c:func:`printk()` feeds kernel messages to the console, dmesg, and 240the syslog daemon. It is useful for debugging and reporting errors, and 241can be used inside interrupt context, but use with caution: a machine 242which has its console flooded with printk messages is unusable. It uses 243a format string mostly compatible with ANSI C printf, and C string 244concatenation to give it a first "priority" argument:: 245 246 printk(KERN_INFO "i = %u\n", i); 247 248 249See ``include/linux/kern_levels.h``; for other ``KERN_`` values; these are 250interpreted by syslog as the level. Special case: for printing an IP 251address use:: 252 253 __be32 ipaddress; 254 printk(KERN_INFO "my ip: %pI4\n", &ipaddress); 255 256 257:c:func:`printk()` internally uses a 1K buffer and does not catch 258overruns. Make sure that will be enough. 259 260.. note:: 261 262 You will know when you are a real kernel hacker when you start 263 typoing printf as printk in your user programs :) 264 265.. note:: 266 267 Another sidenote: the original Unix Version 6 sources had a comment 268 on top of its printf function: "Printf should not be used for 269 chit-chat". You should follow that advice. 270 271:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()` 272--------------------------------------------------------------------------------------------------- 273 274Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h`` 275 276**[SLEEPS]** 277 278:c:func:`put_user()` and :c:func:`get_user()` are used to get 279and put single values (such as an int, char, or long) from and to 280userspace. A pointer into userspace should never be simply dereferenced: 281data should be copied using these routines. Both return ``-EFAULT`` or 2820. 283 284:c:func:`copy_to_user()` and :c:func:`copy_from_user()` are 285more general: they copy an arbitrary amount of data to and from 286userspace. 287 288.. warning:: 289 290 Unlike :c:func:`put_user()` and :c:func:`get_user()`, they 291 return the amount of uncopied data (ie. 0 still means success). 292 293[Yes, this moronic interface makes me cringe. The flamewar comes up 294every year or so. --RR.] 295 296The functions may sleep implicitly. This should never be called outside 297user context (it makes no sense), with interrupts disabled, or a 298spinlock held. 299 300:c:func:`kmalloc()`/:c:func:`kfree()` 301------------------------------------- 302 303Defined in ``include/linux/slab.h`` 304 305**[MAY SLEEP: SEE BELOW]** 306 307These routines are used to dynamically request pointer-aligned chunks of 308memory, like malloc and free do in userspace, but 309:c:func:`kmalloc()` takes an extra flag word. Important values: 310 311``GFP_KERNEL`` 312 May sleep and swap to free memory. Only allowed in user context, but 313 is the most reliable way to allocate memory. 314 315``GFP_ATOMIC`` 316 Don't sleep. Less reliable than ``GFP_KERNEL``, but may be called 317 from interrupt context. You should **really** have a good 318 out-of-memory error-handling strategy. 319 320``GFP_DMA`` 321 Allocate ISA DMA lower than 16MB. If you don't know what that is you 322 don't need it. Very unreliable. 323 324If you see a sleeping function called from invalid context warning 325message, then maybe you called a sleeping allocation function from 326interrupt context without ``GFP_ATOMIC``. You should really fix that. 327Run, don't walk. 328 329If you are allocating at least ``PAGE_SIZE`` (``asm/page.h`` or 330``asm/page_types.h``) bytes, consider using :c:func:`__get_free_pages()` 331(``include/linux/gfp.h``). It takes an order argument (0 for page sized, 3321 for double page, 2 for four pages etc.) and the same memory priority 333flag word as above. 334 335If you are allocating more than a page worth of bytes you can use 336:c:func:`vmalloc()`. It'll allocate virtual memory in the kernel 337map. This block is not contiguous in physical memory, but the MMU makes 338it look like it is for you (so it'll only look contiguous to the CPUs, 339not to external device drivers). If you really need large physically 340contiguous memory for some weird device, you have a problem: it is 341poorly supported in Linux because after some time memory fragmentation 342in a running kernel makes it hard. The best way is to allocate the block 343early in the boot process via the :c:func:`alloc_bootmem()` 344routine. 345 346Before inventing your own cache of often-used objects consider using a 347slab cache in ``include/linux/slab.h`` 348 349:c:func:`current()` 350------------------- 351 352Defined in ``include/asm/current.h`` 353 354This global variable (really a macro) contains a pointer to the current 355task structure, so is only valid in user context. For example, when a 356process makes a system call, this will point to the task structure of 357the calling process. It is **not NULL** in interrupt context. 358 359:c:func:`mdelay()`/:c:func:`udelay()` 360------------------------------------- 361 362Defined in ``include/asm/delay.h`` / ``include/linux/delay.h`` 363 364The :c:func:`udelay()` and :c:func:`ndelay()` functions can be 365used for small pauses. Do not use large values with them as you risk 366overflow - the helper function :c:func:`mdelay()` is useful here, or 367consider :c:func:`msleep()`. 368 369:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` 370----------------------------------------------------------------------------------------------- 371 372Defined in ``include/asm/byteorder.h`` 373 374The :c:func:`cpu_to_be32()` family (where the "32" can be replaced 375by 64 or 16, and the "be" can be replaced by "le") are the general way 376to do endian conversions in the kernel: they return the converted value. 377All variations supply the reverse as well: 378:c:func:`be32_to_cpu()`, etc. 379 380There are two major variations of these functions: the pointer 381variation, such as :c:func:`cpu_to_be32p()`, which take a pointer 382to the given type, and return the converted value. The other variation 383is the "in-situ" family, such as :c:func:`cpu_to_be32s()`, which 384convert value referred to by the pointer, and return void. 385 386:c:func:`local_irq_save()`/:c:func:`local_irq_restore()` 387-------------------------------------------------------- 388 389Defined in ``include/linux/irqflags.h`` 390 391These routines disable hard interrupts on the local CPU, and restore 392them. They are reentrant; saving the previous state in their one 393``unsigned long flags`` argument. If you know that interrupts are 394enabled, you can simply use :c:func:`local_irq_disable()` and 395:c:func:`local_irq_enable()`. 396 397.. _local_bh_disable: 398 399:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()` 400-------------------------------------------------------- 401 402Defined in ``include/linux/bottom_half.h`` 403 404 405These routines disable soft interrupts on the local CPU, and restore 406them. They are reentrant; if soft interrupts were disabled before, they 407will still be disabled after this pair of functions has been called. 408They prevent softirqs and tasklets from running on the current CPU. 409 410:c:func:`smp_processor_id()` 411---------------------------- 412 413Defined in ``include/linux/smp.h`` 414 415:c:func:`get_cpu()` disables preemption (so you won't suddenly get 416moved to another CPU) and returns the current processor number, between 4170 and ``NR_CPUS``. Note that the CPU numbers are not necessarily 418continuous. You return it again with :c:func:`put_cpu()` when you 419are done. 420 421If you know you cannot be preempted by another task (ie. you are in 422interrupt context, or have preemption disabled) you can use 423smp_processor_id(). 424 425``__init``/``__exit``/``__initdata`` 426------------------------------------ 427 428Defined in ``include/linux/init.h`` 429 430After boot, the kernel frees up a special section; functions marked with 431``__init`` and data structures marked with ``__initdata`` are dropped 432after boot is complete: similarly modules discard this memory after 433initialization. ``__exit`` is used to declare a function which is only 434required on exit: the function will be dropped if this file is not 435compiled as a module. See the header file for use. Note that it makes no 436sense for a function marked with ``__init`` to be exported to modules 437with :c:func:`EXPORT_SYMBOL()` or :c:func:`EXPORT_SYMBOL_GPL()`- this 438will break. 439 440:c:func:`__initcall()`/:c:func:`module_init()` 441---------------------------------------------- 442 443Defined in ``include/linux/init.h`` / ``include/linux/module.h`` 444 445Many parts of the kernel are well served as a module 446(dynamically-loadable parts of the kernel). Using the 447:c:func:`module_init()` and :c:func:`module_exit()` macros it 448is easy to write code without #ifdefs which can operate both as a module 449or built into the kernel. 450 451The :c:func:`module_init()` macro defines which function is to be 452called at module insertion time (if the file is compiled as a module), 453or at boot time: if the file is not compiled as a module the 454:c:func:`module_init()` macro becomes equivalent to 455:c:func:`__initcall()`, which through linker magic ensures that 456the function is called on boot. 457 458The function can return a negative error number to cause module loading 459to fail (unfortunately, this has no effect if the module is compiled 460into the kernel). This function is called in user context with 461interrupts enabled, so it can sleep. 462 463:c:func:`module_exit()` 464----------------------- 465 466 467Defined in ``include/linux/module.h`` 468 469This macro defines the function to be called at module removal time (or 470never, in the case of the file compiled into the kernel). It will only 471be called if the module usage count has reached zero. This function can 472also sleep, but cannot fail: everything must be cleaned up by the time 473it returns. 474 475Note that this macro is optional: if it is not present, your module will 476not be removable (except for 'rmmod -f'). 477 478:c:func:`try_module_get()`/:c:func:`module_put()` 479------------------------------------------------- 480 481Defined in ``include/linux/module.h`` 482 483These manipulate the module usage count, to protect against removal (a 484module also can't be removed if another module uses one of its exported 485symbols: see below). Before calling into module code, you should call 486:c:func:`try_module_get()` on that module: if it fails, then the 487module is being removed and you should act as if it wasn't there. 488Otherwise, you can safely enter the module, and call 489:c:func:`module_put()` when you're finished. 490 491Most registerable structures have an owner field, such as in the 492:c:type:`struct file_operations <file_operations>` structure. 493Set this field to the macro ``THIS_MODULE``. 494 495Wait Queues ``include/linux/wait.h`` 496==================================== 497 498**[SLEEPS]** 499 500A wait queue is used to wait for someone to wake you up when a certain 501condition is true. They must be used carefully to ensure there is no 502race condition. You declare a :c:type:`wait_queue_head_t`, and then processes 503which want to wait for that condition declare a :c:type:`wait_queue_entry_t` 504referring to themselves, and place that in the queue. 505 506Declaring 507--------- 508 509You declare a ``wait_queue_head_t`` using the 510:c:func:`DECLARE_WAIT_QUEUE_HEAD()` macro, or using the 511:c:func:`init_waitqueue_head()` routine in your initialization 512code. 513 514Queuing 515------- 516 517Placing yourself in the waitqueue is fairly complex, because you must 518put yourself in the queue before checking the condition. There is a 519macro to do this: :c:func:`wait_event_interruptible()` 520(``include/linux/wait.h``) The first argument is the wait queue head, and 521the second is an expression which is evaluated; the macro returns 0 when 522this expression is true, or ``-ERESTARTSYS`` if a signal is received. The 523:c:func:`wait_event()` version ignores signals. 524 525Waking Up Queued Tasks 526---------------------- 527 528Call :c:func:`wake_up()` (``include/linux/wait.h``), which will wake 529up every process in the queue. The exception is if one has 530``TASK_EXCLUSIVE`` set, in which case the remainder of the queue will 531not be woken. There are other variants of this basic function available 532in the same header. 533 534Atomic Operations 535================= 536 537Certain operations are guaranteed atomic on all platforms. The first 538class of operations work on :c:type:`atomic_t` (``include/asm/atomic.h``); 539this contains a signed integer (at least 32 bits long), and you must use 540these functions to manipulate or read :c:type:`atomic_t` variables. 541:c:func:`atomic_read()` and :c:func:`atomic_set()` get and set 542the counter, :c:func:`atomic_add()`, :c:func:`atomic_sub()`, 543:c:func:`atomic_inc()`, :c:func:`atomic_dec()`, and 544:c:func:`atomic_dec_and_test()` (returns true if it was 545decremented to zero). 546 547Yes. It returns true (i.e. != 0) if the atomic variable is zero. 548 549Note that these functions are slower than normal arithmetic, and so 550should not be used unnecessarily. 551 552The second class of atomic operations is atomic bit operations on an 553``unsigned long``, defined in ``include/linux/bitops.h``. These 554operations generally take a pointer to the bit pattern, and a bit 555number: 0 is the least significant bit. :c:func:`set_bit()`, 556:c:func:`clear_bit()` and :c:func:`change_bit()` set, clear, 557and flip the given bit. :c:func:`test_and_set_bit()`, 558:c:func:`test_and_clear_bit()` and 559:c:func:`test_and_change_bit()` do the same thing, except return 560true if the bit was previously set; these are particularly useful for 561atomically setting flags. 562 563It is possible to call these operations with bit indices greater than 564``BITS_PER_LONG``. The resulting behavior is strange on big-endian 565platforms though so it is a good idea not to do this. 566 567Symbols 568======= 569 570Within the kernel proper, the normal linking rules apply (ie. unless a 571symbol is declared to be file scope with the ``static`` keyword, it can 572be used anywhere in the kernel). However, for modules, a special 573exported symbol table is kept which limits the entry points to the 574kernel proper. Modules can also export symbols. 575 576:c:func:`EXPORT_SYMBOL()` 577------------------------- 578 579Defined in ``include/linux/export.h`` 580 581This is the classic method of exporting a symbol: dynamically loaded 582modules will be able to use the symbol as normal. 583 584:c:func:`EXPORT_SYMBOL_GPL()` 585----------------------------- 586 587Defined in ``include/linux/export.h`` 588 589Similar to :c:func:`EXPORT_SYMBOL()` except that the symbols 590exported by :c:func:`EXPORT_SYMBOL_GPL()` can only be seen by 591modules with a :c:func:`MODULE_LICENSE()` that specifies a GPL 592compatible license. It implies that the function is considered an 593internal implementation issue, and not really an interface. Some 594maintainers and developers may however require EXPORT_SYMBOL_GPL() 595when adding any new APIs or functionality. 596 597:c:func:`EXPORT_SYMBOL_NS()` 598---------------------------- 599 600Defined in ``include/linux/export.h`` 601 602This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol 603namespace. Symbol Namespaces are documented in 604``Documentation/kbuild/namespaces.rst``. 605 606:c:func:`EXPORT_SYMBOL_NS_GPL()` 607-------------------------------- 608 609Defined in ``include/linux/export.h`` 610 611This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol 612namespace. Symbol Namespaces are documented in 613``Documentation/kbuild/namespaces.rst``. 614 615Routines and Conventions 616======================== 617 618Double-linked lists ``include/linux/list.h`` 619-------------------------------------------- 620 621There used to be three sets of linked-list routines in the kernel 622headers, but this one is the winner. If you don't have some particular 623pressing need for a single list, it's a good choice. 624 625In particular, :c:func:`list_for_each_entry()` is useful. 626 627Return Conventions 628------------------ 629 630For code called in user context, it's very common to defy C convention, 631and return 0 for success, and a negative error number (eg. ``-EFAULT``) for 632failure. This can be unintuitive at first, but it's fairly widespread in 633the kernel. 634 635Using :c:func:`ERR_PTR()` (``include/linux/err.h``) to encode a 636negative error number into a pointer, and :c:func:`IS_ERR()` and 637:c:func:`PTR_ERR()` to get it back out again: avoids a separate 638pointer parameter for the error number. Icky, but in a good way. 639 640Breaking Compilation 641-------------------- 642 643Linus and the other developers sometimes change function or structure 644names in development kernels; this is not done just to keep everyone on 645their toes: it reflects a fundamental change (eg. can no longer be 646called with interrupts on, or does extra checks, or doesn't do checks 647which were caught before). Usually this is accompanied by a fairly 648complete note to the linux-kernel mailing list; search the archive. 649Simply doing a global replace on the file usually makes things **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 whose pond you've been pissing in. Look at the top of the 727 source files, inside the ``MAINTAINERS`` file, and last of all in the 728 ``CREDITS`` file. You should coordinate with this person to make sure 729 you're not duplicating effort, or trying something that's already 730 been rejected. 731 732 Make sure you put your name and EMail address at the top of any files 733 you create or mangle 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've done something noteworthy, 752 usually beyond a single file (your name should be at the top of the 753 source files anyway). ``MAINTAINERS`` means you want to be consulted 754 when changes are made to a subsystem, and hear about bugs; it implies 755 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`` and possibly 759 ``Documentation/process/submitting-drivers.rst``. 760 761Kernel Cantrips 762=============== 763 764Some favorites from browsing the source. Feel free to add to this list. 765 766``arch/x86/include/asm/delay.h``:: 767 768 #define ndelay(n) (__builtin_constant_p(n) ? \ 769 ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \ 770 __ndelay(n)) 771 772 773``include/linux/fs.h``:: 774 775 /* 776 * Kernel pointers have redundant information, so we can use a 777 * scheme where we can return either an error code or a dentry 778 * pointer with the same return value. 779 * 780 * This should be a per-architecture thing, to allow different 781 * error and pointer decisions. 782 */ 783 #define ERR_PTR(err) ((void *)((long)(err))) 784 #define PTR_ERR(ptr) ((long)(ptr)) 785 #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000)) 786 787``arch/x86/include/asm/uaccess_32.h:``:: 788 789 #define copy_to_user(to,from,n) \ 790 (__builtin_constant_p(n) ? \ 791 __constant_copy_to_user((to),(from),(n)) : \ 792 __generic_copy_to_user((to),(from),(n))) 793 794 795``arch/sparc/kernel/head.S:``:: 796 797 /* 798 * Sun people can't spell worth damn. "compatability" indeed. 799 * At least we *know* we can't spell, and use a spell-checker. 800 */ 801 802 /* Uh, actually Linus it is I who cannot spell. Too much murky 803 * Sparc assembly will do this to ya. 804 */ 805 C_LABEL(cputypvar): 806 .asciz "compatibility" 807 808 /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */ 809 .align 4 810 C_LABEL(cputypvar_sun4m): 811 .asciz "compatible" 812 813 814``arch/sparc/lib/checksum.S:``:: 815 816 /* Sun, you just can't beat me, you just can't. Stop trying, 817 * give up. I'm serious, I am going to kick the living shit 818 * out of you, game over, lights out. 819 */ 820 821 822Thanks 823====== 824 825Thanks to Andi Kleen for the idea, answering my questions, fixing my 826mistakes, filling content, etc. Philipp Rumpf for more spelling and 827clarity fixes, and some excellent non-obvious points. Werner Almesberger 828for giving me a great summary of :c:func:`disable_irq()`, and Jes 829Sorensen and Andrea Arcangeli added caveats. Michael Elizabeth Chastain 830for checking and adding to the Configure section. Telsa Gwynne for 831teaching me DocBook. 832