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