Documentation: kernel-hacking: Remove :c:func: annotations

+84 -85

1 changed file

expand all

Documentation

kernel-hacking

hacking.rst

+84 -85

Documentation/kernel-hacking/hacking.rst

··· 49 49 50 50 User context is when you are coming in from a system call or other trap: 51 51 like userspace, you can be preempted by more important tasks and by 52 - interrupts. You can sleep by calling :c:func:`schedule()`. 52 + interrupts. You can sleep by calling schedule(). 53 53 54 54 .. note:: 55 55 ··· 57 57 operations on the block device layer. 58 58 59 59 In user context, the ``current`` pointer (indicating the task we are 60 - currently executing) is valid, and :c:func:`in_interrupt()` 60 + currently executing) is valid, and in_interrupt() 61 61 (``include/linux/preempt.h``) is false. 62 62 63 63 .. warning:: 64 64 65 65 Beware that if you have preemption or softirqs disabled (see below), 66 - :c:func:`in_interrupt()` will return a false positive. 66 + in_interrupt() will return a false positive. 67 67 68 68 Hardware Interrupts (Hard IRQs) 69 69 ------------------------------- ··· 115 115 'tasks'. 116 116 117 117 You can tell you are in a softirq (or tasklet) using the 118 - :c:func:`in_softirq()` macro (``include/linux/preempt.h``). 118 + in_softirq() macro (``include/linux/preempt.h``). 119 119 120 120 .. warning:: 121 121 ··· 171 171 Linus. 172 172 173 173 If all your routine does is read or write some parameter, consider 174 - implementing a :c:func:`sysfs()` interface instead. 174 + implementing a sysfs() interface instead. 175 175 176 176 Inside the ioctl you're in user context to a process. When a error 177 177 occurs you return a negated errno (see ··· 230 230 Common Routines 231 231 =============== 232 232 233 - :c:func:`printk()` 234 - ------------------ 233 + printk() 234 + -------- 235 235 236 236 Defined in ``include/linux/printk.h`` 237 237 238 - :c:func:`printk()` feeds kernel messages to the console, dmesg, and 238 + printk() feeds kernel messages to the console, dmesg, and 239 239 the syslog daemon. It is useful for debugging and reporting errors, and 240 240 can be used inside interrupt context, but use with caution: a machine 241 241 which has its console flooded with printk messages is unusable. It uses ··· 253 253 printk(KERN_INFO "my ip: %pI4\n", &ipaddress); 254 254 255 255 256 - :c:func:`printk()` internally uses a 1K buffer and does not catch 256 + printk() internally uses a 1K buffer and does not catch 257 257 overruns. Make sure that will be enough. 258 258 259 259 .. note:: ··· 267 267 on top of its printf function: "Printf should not be used for 268 268 chit-chat". You should follow that advice. 269 269 270 - :c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()` 271 - --------------------------------------------------------------------------------------------------- 270 + copy_to_user() / copy_from_user() / get_user() / put_user() 271 + ----------------------------------------------------------- 272 272 273 273 Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h`` 274 274 275 275 **[SLEEPS]** 276 276 277 - :c:func:`put_user()` and :c:func:`get_user()` are used to get 277 + put_user() and get_user() are used to get 278 278 and put single values (such as an int, char, or long) from and to 279 279 userspace. A pointer into userspace should never be simply dereferenced: 280 280 data should be copied using these routines. Both return ``-EFAULT`` or 281 281 0. 282 282 283 - :c:func:`copy_to_user()` and :c:func:`copy_from_user()` are 283 + copy_to_user() and copy_from_user() are 284 284 more general: they copy an arbitrary amount of data to and from 285 285 userspace. 286 286 287 287 .. warning:: 288 288 289 - Unlike :c:func:`put_user()` and :c:func:`get_user()`, they 289 + Unlike put_user() and get_user(), they 290 290 return the amount of uncopied data (ie. 0 still means success). 291 291 292 292 [Yes, this objectionable interface makes me cringe. The flamewar comes ··· 296 296 user context (it makes no sense), with interrupts disabled, or a 297 297 spinlock held. 298 298 299 - :c:func:`kmalloc()`/:c:func:`kfree()` 300 - ------------------------------------- 299 + kmalloc()/kfree() 300 + ----------------- 301 301 302 302 Defined in ``include/linux/slab.h`` 303 303 ··· 305 305 306 306 These routines are used to dynamically request pointer-aligned chunks of 307 307 memory, like malloc and free do in userspace, but 308 - :c:func:`kmalloc()` takes an extra flag word. Important values: 308 + kmalloc() takes an extra flag word. Important values: 309 309 310 310 ``GFP_KERNEL`` 311 311 May sleep and swap to free memory. Only allowed in user context, but ··· 326 326 Run, don't walk. 327 327 328 328 If you are allocating at least ``PAGE_SIZE`` (``asm/page.h`` or 329 - ``asm/page_types.h``) bytes, consider using :c:func:`__get_free_pages()` 329 + ``asm/page_types.h``) bytes, consider using __get_free_pages() 330 330 (``include/linux/gfp.h``). It takes an order argument (0 for page sized, 331 331 1 for double page, 2 for four pages etc.) and the same memory priority 332 332 flag word as above. 333 333 334 334 If 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 335 + vmalloc(). It'll allocate virtual memory in the kernel 336 336 map. This block is not contiguous in physical memory, but the MMU makes 337 337 it look like it is for you (so it'll only look contiguous to the CPUs, 338 338 not to external device drivers). If you really need large physically 339 339 contiguous memory for some weird device, you have a problem: it is 340 340 poorly supported in Linux because after some time memory fragmentation 341 341 in a running kernel makes it hard. The best way is to allocate the block 342 - early in the boot process via the :c:func:`alloc_bootmem()` 342 + early in the boot process via the alloc_bootmem() 343 343 routine. 344 344 345 345 Before inventing your own cache of often-used objects consider using a ··· 355 355 process makes a system call, this will point to the task structure of 356 356 the calling process. It is **not NULL** in interrupt context. 357 357 358 - :c:func:`mdelay()`/:c:func:`udelay()` 359 - ------------------------------------- 358 + mdelay()/udelay() 359 + ----------------- 360 360 361 361 Defined in ``include/asm/delay.h`` / ``include/linux/delay.h`` 362 362 363 - The :c:func:`udelay()` and :c:func:`ndelay()` functions can be 363 + The udelay() and ndelay() functions can be 364 364 used for small pauses. Do not use large values with them as you risk 365 - overflow - the helper function :c:func:`mdelay()` is useful here, or 366 - consider :c:func:`msleep()`. 365 + overflow - the helper function mdelay() is useful here, or 366 + consider msleep(). 367 367 368 - :c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` 369 - ----------------------------------------------------------------------------------------------- 368 + cpu_to_be32()/be32_to_cpu()/cpu_to_le32()/le32_to_cpu() 369 + ------------------------------------------------------- 370 370 371 371 Defined in ``include/asm/byteorder.h`` 372 372 373 - The :c:func:`cpu_to_be32()` family (where the "32" can be replaced 373 + The cpu_to_be32() family (where the "32" can be replaced 374 374 by 64 or 16, and the "be" can be replaced by "le") are the general way 375 375 to do endian conversions in the kernel: they return the converted value. 376 376 All variations supply the reverse as well: 377 - :c:func:`be32_to_cpu()`, etc. 377 + be32_to_cpu(), etc. 378 378 379 379 There are two major variations of these functions: the pointer 380 - variation, such as :c:func:`cpu_to_be32p()`, which take a pointer 380 + variation, such as cpu_to_be32p(), which take a pointer 381 381 to the given type, and return the converted value. The other variation 382 - is the "in-situ" family, such as :c:func:`cpu_to_be32s()`, which 382 + is the "in-situ" family, such as cpu_to_be32s(), which 383 383 convert value referred to by the pointer, and return void. 384 384 385 - :c:func:`local_irq_save()`/:c:func:`local_irq_restore()` 386 - -------------------------------------------------------- 385 + local_irq_save()/local_irq_restore() 386 + ------------------------------------ 387 387 388 388 Defined in ``include/linux/irqflags.h`` 389 389 390 390 These routines disable hard interrupts on the local CPU, and restore 391 391 them. They are reentrant; saving the previous state in their one 392 392 ``unsigned long flags`` argument. If you know that interrupts are 393 - enabled, you can simply use :c:func:`local_irq_disable()` and 394 - :c:func:`local_irq_enable()`. 393 + enabled, you can simply use local_irq_disable() and 394 + local_irq_enable(). 395 395 396 396 .. _local_bh_disable: 397 397 398 - :c:func:`local_bh_disable()`/:c:func:`local_bh_enable()` 399 - -------------------------------------------------------- 398 + local_bh_disable()/local_bh_enable() 399 + ------------------------------------ 400 400 401 401 Defined in ``include/linux/bottom_half.h`` 402 402 ··· 406 406 will still be disabled after this pair of functions has been called. 407 407 They prevent softirqs and tasklets from running on the current CPU. 408 408 409 - :c:func:`smp_processor_id()` 410 - ---------------------------- 409 + smp_processor_id() 410 + ------------------ 411 411 412 412 Defined in ``include/linux/smp.h`` 413 413 414 - :c:func:`get_cpu()` disables preemption (so you won't suddenly get 414 + get_cpu() disables preemption (so you won't suddenly get 415 415 moved to another CPU) and returns the current processor number, between 416 416 0 and ``NR_CPUS``. Note that the CPU numbers are not necessarily 417 - continuous. You return it again with :c:func:`put_cpu()` when you 417 + continuous. You return it again with put_cpu() when you 418 418 are done. 419 419 420 420 If you know you cannot be preempted by another task (ie. you are in ··· 433 433 required on exit: the function will be dropped if this file is not 434 434 compiled as a module. See the header file for use. Note that it makes no 435 435 sense for a function marked with ``__init`` to be exported to modules 436 - with :c:func:`EXPORT_SYMBOL()` or :c:func:`EXPORT_SYMBOL_GPL()`- this 436 + with EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()- this 437 437 will break. 438 438 439 - :c:func:`__initcall()`/:c:func:`module_init()` 440 - ---------------------------------------------- 439 + __initcall()/module_init() 440 + -------------------------- 441 441 442 442 Defined in ``include/linux/init.h`` / ``include/linux/module.h`` 443 443 444 444 Many parts of the kernel are well served as a module 445 445 (dynamically-loadable parts of the kernel). Using the 446 - :c:func:`module_init()` and :c:func:`module_exit()` macros it 446 + module_init() and module_exit() macros it 447 447 is easy to write code without #ifdefs which can operate both as a module 448 448 or built into the kernel. 449 449 450 - The :c:func:`module_init()` macro defines which function is to be 450 + The module_init() macro defines which function is to be 451 451 called at module insertion time (if the file is compiled as a module), 452 452 or 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 453 + module_init() macro becomes equivalent to 454 + __initcall(), which through linker magic ensures that 455 455 the function is called on boot. 456 456 457 457 The function can return a negative error number to cause module loading ··· 459 459 into the kernel). This function is called in user context with 460 460 interrupts enabled, so it can sleep. 461 461 462 - :c:func:`module_exit()` 463 - ----------------------- 464 - 462 + module_exit() 463 + ------------- 465 464 466 465 Defined in ``include/linux/module.h`` 467 466 ··· 473 474 Note that this macro is optional: if it is not present, your module will 474 475 not be removable (except for 'rmmod -f'). 475 476 476 - :c:func:`try_module_get()`/:c:func:`module_put()` 477 - ------------------------------------------------- 477 + try_module_get()/module_put() 478 + ----------------------------- 478 479 479 480 Defined in ``include/linux/module.h`` 480 481 481 482 These manipulate the module usage count, to protect against removal (a 482 483 module also can't be removed if another module uses one of its exported 483 484 symbols: see below). Before calling into module code, you should call 484 - :c:func:`try_module_get()` on that module: if it fails, then the 485 + try_module_get() on that module: if it fails, then the 485 486 module is being removed and you should act as if it wasn't there. 486 487 Otherwise, you can safely enter the module, and call 487 - :c:func:`module_put()` when you're finished. 488 + module_put() when you're finished. 488 489 489 490 Most registerable structures have an owner field, such as in the 490 491 :c:type:`struct file_operations <file_operations>` structure. ··· 505 506 --------- 506 507 507 508 You 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 509 + DECLARE_WAIT_QUEUE_HEAD() macro, or using the 510 + init_waitqueue_head() routine in your initialization 510 511 code. 511 512 512 513 Queuing ··· 514 515 515 516 Placing yourself in the waitqueue is fairly complex, because you must 516 517 put yourself in the queue before checking the condition. There is a 517 - macro to do this: :c:func:`wait_event_interruptible()` 518 + macro to do this: wait_event_interruptible() 518 519 (``include/linux/wait.h``) The first argument is the wait queue head, and 519 520 the second is an expression which is evaluated; the macro returns 0 when 520 521 this expression is true, or ``-ERESTARTSYS`` if a signal is received. The 521 - :c:func:`wait_event()` version ignores signals. 522 + wait_event() version ignores signals. 522 523 523 524 Waking Up Queued Tasks 524 525 ---------------------- 525 526 526 - Call :c:func:`wake_up()` (``include/linux/wait.h``), which will wake 527 + Call wake_up() (``include/linux/wait.h``), which will wake 527 528 up every process in the queue. The exception is if one has 528 529 ``TASK_EXCLUSIVE`` set, in which case the remainder of the queue will 529 530 not be woken. There are other variants of this basic function available ··· 536 537 class of operations work on :c:type:`atomic_t` (``include/asm/atomic.h``); 537 538 this contains a signed integer (at least 32 bits long), and you must use 538 539 these functions to manipulate or read :c:type:`atomic_t` variables. 539 - :c:func:`atomic_read()` and :c:func:`atomic_set()` get and set 540 - the 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 540 + atomic_read() and atomic_set() get and set 541 + the counter, atomic_add(), atomic_sub(), 542 + atomic_inc(), atomic_dec(), and 543 + atomic_dec_and_test() (returns true if it was 543 544 decremented to zero). 544 545 545 546 Yes. It returns true (i.e. != 0) if the atomic variable is zero. ··· 550 551 The second class of atomic operations is atomic bit operations on an 551 552 ``unsigned long``, defined in ``include/linux/bitops.h``. These 552 553 operations generally take a pointer to the bit pattern, and a bit 553 - number: 0 is the least significant bit. :c:func:`set_bit()`, 554 - :c:func:`clear_bit()` and :c:func:`change_bit()` set, clear, 555 - and 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 554 + number: 0 is the least significant bit. set_bit(), 555 + clear_bit() and change_bit() set, clear, 556 + and flip the given bit. test_and_set_bit(), 557 + test_and_clear_bit() and 558 + test_and_change_bit() do the same thing, except return 558 559 true if the bit was previously set; these are particularly useful for 559 560 atomically setting flags. 560 561 ··· 571 572 exported symbol table is kept which limits the entry points to the 572 573 kernel proper. Modules can also export symbols. 573 574 574 - :c:func:`EXPORT_SYMBOL()` 575 - ------------------------- 575 + EXPORT_SYMBOL() 576 + --------------- 576 577 577 578 Defined in ``include/linux/export.h`` 578 579 579 580 This is the classic method of exporting a symbol: dynamically loaded 580 581 modules will be able to use the symbol as normal. 581 582 582 - :c:func:`EXPORT_SYMBOL_GPL()` 583 - ----------------------------- 583 + EXPORT_SYMBOL_GPL() 584 + ------------------- 584 585 585 586 Defined in ``include/linux/export.h`` 586 587 587 - Similar to :c:func:`EXPORT_SYMBOL()` except that the symbols 588 - exported by :c:func:`EXPORT_SYMBOL_GPL()` can only be seen by 589 - modules with a :c:func:`MODULE_LICENSE()` that specifies a GPLv2 588 + Similar to EXPORT_SYMBOL() except that the symbols 589 + exported by EXPORT_SYMBOL_GPL() can only be seen by 590 + modules with a MODULE_LICENSE() that specifies a GPLv2 590 591 compatible license. It implies that the function is considered an 591 592 internal implementation issue, and not really an interface. Some 592 593 maintainers and developers may however require EXPORT_SYMBOL_GPL() 593 594 when adding any new APIs or functionality. 594 595 595 - :c:func:`EXPORT_SYMBOL_NS()` 596 - ---------------------------- 596 + EXPORT_SYMBOL_NS() 597 + ------------------ 597 598 598 599 Defined in ``include/linux/export.h`` 599 600 ··· 601 602 namespace. Symbol Namespaces are documented in 602 603 Documentation/core-api/symbol-namespaces.rst 603 604 604 - :c:func:`EXPORT_SYMBOL_NS_GPL()` 605 - -------------------------------- 605 + EXPORT_SYMBOL_NS_GPL() 606 + ---------------------- 606 607 607 608 Defined in ``include/linux/export.h`` 608 609 ··· 620 621 headers, but this one is the winner. If you don't have some particular 621 622 pressing need for a single list, it's a good choice. 622 623 623 - In particular, :c:func:`list_for_each_entry()` is useful. 624 + In particular, list_for_each_entry() is useful. 624 625 625 626 Return Conventions 626 627 ------------------ ··· 630 631 failure. This can be unintuitive at first, but it's fairly widespread in 631 632 the kernel. 632 633 633 - Using :c:func:`ERR_PTR()` (``include/linux/err.h``) to encode a 634 - negative error number into a pointer, and :c:func:`IS_ERR()` and 635 - :c:func:`PTR_ERR()` to get it back out again: avoids a separate 634 + Using ERR_PTR() (``include/linux/err.h``) to encode a 635 + negative error number into a pointer, and IS_ERR() and 636 + PTR_ERR() to get it back out again: avoids a separate 636 637 pointer parameter for the error number. Icky, but in a good way. 637 638 638 639 Breaking Compilation ··· 823 824 Thanks to Andi Kleen for the idea, answering my questions, fixing my 824 825 mistakes, filling content, etc. Philipp Rumpf for more spelling and 825 826 clarity fixes, and some excellent non-obvious points. Werner Almesberger 826 - for giving me a great summary of :c:func:`disable_irq()`, and Jes 827 + for giving me a great summary of disable_irq(), and Jes 827 828 Sorensen and Andrea Arcangeli added caveats. Michael Elizabeth Chastain 828 829 for checking and adding to the Configure section. Telsa Gwynne for 829 830 teaching me DocBook.

Configure Feed

Configure Feed