History

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

Remove the useless :c:func: annotations.

Thorsten Blum committed 10 months ago

Commit 736ea811 parent bb51cf41 file · +84 −85Browse files

Unified · Split

Documentation/kernel-hacking/hacking.rst+84−85
@@ -49,7 +49,7 @@ User Context · 48 unmodified lines
4949
5050 User context is when you are coming in from a system call or other trap:
5151 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().
5353
5454 .. note::
5555
@@ -57,13 +57,13 @@ interrupts. You can sleep by calling :c:func:`schedule()`. · 1 unmodified line
5757 operations on the block device layer.
5858
5959 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()
6161 (``include/linux/preempt.h``) is false.
6262
6363 .. warning::
6464
6565 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.
6767
6868 Hardware Interrupts (Hard IRQs)
6969 -------------------------------
@@ -115,7 +115,7 @@ time, although different tasklets can run simultaneously. · 45 unmodified lines
115115 'tasks'.
116116
117117 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``).
119119
120120 .. warning::
121121
@@ -171,7 +171,7 @@ in every architecture's ``include/asm/unistd.h`` and · 49 unmodified lines
171171 Linus.
172172
173173 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.
175175
176176 Inside the ioctl you're in user context to a process. When a error
177177 occurs you return a negated errno (see
@@ -230,12 +230,12 @@ Really. · 52 unmodified lines
230230 Common Routines
231231 ===============
232232
233−:c:func:`printk()`
234−------------------
233+printk()
234+--------
235235
236236 Defined in ``include/linux/printk.h``
237237
238−:c:func:`printk()` feeds kernel messages to the console, dmesg, and
238+printk() feeds kernel messages to the console, dmesg, and
239239 the syslog daemon. It is useful for debugging and reporting errors, and
240240 can be used inside interrupt context, but use with caution: a machine
241241 which has its console flooded with printk messages is unusable. It uses
@@ -253,7 +253,7 @@ address use:: · 11 unmodified lines
253253 printk(KERN_INFO "my ip: %pI4\n", &ipaddress);
254254
255255
256−:c:func:`printk()` internally uses a 1K buffer and does not catch
256+printk() internally uses a 1K buffer and does not catch
257257 overruns. Make sure that will be enough.
258258
259259 .. note::
@@ -267,26 +267,26 @@ overruns. Make sure that will be enough. · 7 unmodified lines
267267 on top of its printf function: "Printf should not be used for
268268 chit-chat". You should follow that advice.
269269
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+-----------------------------------------------------------
272272
273273 Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h``
274274
275275 **[SLEEPS]**
276276
277−:c:func:`put_user()` and :c:func:`get_user()` are used to get
277+put_user() and get_user() are used to get
278278 and put single values (such as an int, char, or long) from and to
279279 userspace. A pointer into userspace should never be simply dereferenced:
280280 data should be copied using these routines. Both return ``-EFAULT`` or
281281 0.
282282
283−:c:func:`copy_to_user()` and :c:func:`copy_from_user()` are
283+copy_to_user() and copy_from_user() are
284284 more general: they copy an arbitrary amount of data to and from
285285 userspace.
286286
287287 .. warning::
288288
289− Unlike :c:func:`put_user()` and :c:func:`get_user()`, they
289+ Unlike put_user() and get_user(), they
290290 return the amount of uncopied data (ie. 0 still means success).
291291
292292 [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
296296 user context (it makes no sense), with interrupts disabled, or a
297297 spinlock held.
298298
299−:c:func:`kmalloc()`/:c:func:`kfree()`
300−-------------------------------------
299+kmalloc()/kfree()
300+-----------------
301301
302302 Defined in ``include/linux/slab.h``
303303
@@ -305,7 +305,7 @@ Defined in ``include/linux/slab.h`` · 1 unmodified line
305305
306306 These routines are used to dynamically request pointer-aligned chunks of
307307 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:
309309
310310 ``GFP_KERNEL``
311311 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
326326 Run, don't walk.
327327
328328 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()
330330 (``include/linux/gfp.h``). It takes an order argument (0 for page sized,
331331 1 for double page, 2 for four pages etc.) and the same memory priority
332332 flag word as above.
333333
334334 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
336336 map. This block is not contiguous in physical memory, but the MMU makes
337337 it look like it is for you (so it'll only look contiguous to the CPUs,
338338 not to external device drivers). If you really need large physically
339339 contiguous memory for some weird device, you have a problem: it is
340340 poorly supported in Linux because after some time memory fragmentation
341341 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()
343343 routine.
344344
345345 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
355355 process makes a system call, this will point to the task structure of
356356 the calling process. It is **not NULL** in interrupt context.
357357
358−:c:func:`mdelay()`/:c:func:`udelay()`
359−-------------------------------------
358+mdelay()/udelay()
359+-----------------
360360
361361 Defined in ``include/asm/delay.h`` / ``include/linux/delay.h``
362362
363−The :c:func:`udelay()` and :c:func:`ndelay()` functions can be
363+The udelay() and ndelay() functions can be
364364 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().
367367
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+-------------------------------------------------------
370370
371371 Defined in ``include/asm/byteorder.h``
372372
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
374374 by 64 or 16, and the "be" can be replaced by "le") are the general way
375375 to do endian conversions in the kernel: they return the converted value.
376376 All variations supply the reverse as well:
377−:c:func:`be32_to_cpu()`, etc.
377+be32_to_cpu(), etc.
378378
379379 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
381381 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
383383 convert value referred to by the pointer, and return void.
384384
385−:c:func:`local_irq_save()`/:c:func:`local_irq_restore()`
386−--------------------------------------------------------
385+local_irq_save()/local_irq_restore()
386+------------------------------------
387387
388388 Defined in ``include/linux/irqflags.h``
389389
390390 These routines disable hard interrupts on the local CPU, and restore
391391 them. They are reentrant; saving the previous state in their one
392392 ``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().
395395
396396 .. _local_bh_disable:
397397
398−:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()`
399−--------------------------------------------------------
398+local_bh_disable()/local_bh_enable()
399+------------------------------------
400400
401401 Defined in ``include/linux/bottom_half.h``
402402
@@ -406,15 +406,15 @@ them. They are reentrant; if soft interrupts were disabled before, they · 3 unmodified lines
406406 will still be disabled after this pair of functions has been called.
407407 They prevent softirqs and tasklets from running on the current CPU.
408408
409−:c:func:`smp_processor_id()`
410−----------------------------
409+smp_processor_id()
410+------------------
411411
412412 Defined in ``include/linux/smp.h``
413413
414−:c:func:`get_cpu()` disables preemption (so you won't suddenly get
414+get_cpu() disables preemption (so you won't suddenly get
415415 moved to another CPU) and returns the current processor number, between
416416 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
418418 are done.
419419
420420 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
433433 required on exit: the function will be dropped if this file is not
434434 compiled as a module. See the header file for use. Note that it makes no
435435 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
437437 will break.
438438
439−:c:func:`__initcall()`/:c:func:`module_init()`
440−----------------------------------------------
439+__initcall()/module_init()
440+--------------------------
441441
442442 Defined in ``include/linux/init.h`` / ``include/linux/module.h``
443443
444444 Many parts of the kernel are well served as a module
445445 (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
447447 is easy to write code without #ifdefs which can operate both as a module
448448 or built into the kernel.
449449
450−The :c:func:`module_init()` macro defines which function is to be
450+The module_init() macro defines which function is to be
451451 called at module insertion time (if the file is compiled as a module),
452452 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
455455 the function is called on boot.
456456
457457 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
459459 into the kernel). This function is called in user context with
460460 interrupts enabled, so it can sleep.
461461
462−:c:func:`module_exit()`
463−-----------------------
464−
462+module_exit()
463+-------------
465464
466465 Defined in ``include/linux/module.h``
467466
@@ -474,18 +473,18 @@ it returns. · 6 unmodified lines
474473 Note that this macro is optional: if it is not present, your module will
475474 not be removable (except for 'rmmod -f').
476475
477−:c:func:`try_module_get()`/:c:func:`module_put()`
478−-------------------------------------------------
476+try_module_get()/module_put()
477+-----------------------------
479478
480479 Defined in ``include/linux/module.h``
481480
482481 These manipulate the module usage count, to protect against removal (a
483482 module also can't be removed if another module uses one of its exported
484483 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
486485 module is being removed and you should act as if it wasn't there.
487486 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.
489488
490489 Most registerable structures have an owner field, such as in the
491490 :c:type:`struct file_operations <file_operations>` structure.
@@ -506,8 +505,8 @@ Declaring · 14 unmodified lines
506505 ---------
507506
508507 You declare a ``wait_queue_head_t`` using the
509−:c:func:`DECLARE_WAIT_QUEUE_HEAD()` macro, or using the
510−:c:func:`init_waitqueue_head()` routine in your initialization
508+DECLARE_WAIT_QUEUE_HEAD() macro, or using the
509+init_waitqueue_head() routine in your initialization
511510 code.
512511
513512 Queuing
@@ -515,16 +514,16 @@ Queuing · 1 unmodified line
515514
516515 Placing yourself in the waitqueue is fairly complex, because you must
517516 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()
519518 (``include/linux/wait.h``) The first argument is the wait queue head, and
520519 the second is an expression which is evaluated; the macro returns 0 when
521520 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.
523522
524523 Waking Up Queued Tasks
525524 ----------------------
526525
527−Call :c:func:`wake_up()` (``include/linux/wait.h``), which will wake
526+Call wake_up() (``include/linux/wait.h``), which will wake
528527 up every process in the queue. The exception is if one has
529528 ``TASK_EXCLUSIVE`` set, in which case the remainder of the queue will
530529 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
537536 class of operations work on :c:type:`atomic_t` (``include/asm/atomic.h``);
538537 this contains a signed integer (at least 32 bits long), and you must use
539538 these functions to manipulate or read :c:type:`atomic_t` variables.
540−:c:func:`atomic_read()` and :c:func:`atomic_set()` get and set
541−the counter, :c:func:`atomic_add()`, :c:func:`atomic_sub()`,
542−:c:func:`atomic_inc()`, :c:func:`atomic_dec()`, and
543−:c:func:`atomic_dec_and_test()` (returns true if it was
539+atomic_read() and atomic_set() get and set
540+the counter, atomic_add(), atomic_sub(),
541+atomic_inc(), atomic_dec(), and
542+atomic_dec_and_test() (returns true if it was
544543 decremented to zero).
545544
546545 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
551550 The second class of atomic operations is atomic bit operations on an
552551 ``unsigned long``, defined in ``include/linux/bitops.h``. These
553552 operations generally take a pointer to the bit pattern, and a bit
554−number: 0 is the least significant bit. :c:func:`set_bit()`,
555−:c:func:`clear_bit()` and :c:func:`change_bit()` set, clear,
556−and flip the given bit. :c:func:`test_and_set_bit()`,
557−:c:func:`test_and_clear_bit()` and
558−:c:func:`test_and_change_bit()` do the same thing, except return
553+number: 0 is the least significant bit. set_bit(),
554+clear_bit() and change_bit() set, clear,
555+and flip the given bit. test_and_set_bit(),
556+test_and_clear_bit() and
557+test_and_change_bit() do the same thing, except return
559558 true if the bit was previously set; these are particularly useful for
560559 atomically setting flags.
561560
@@ -572,29 +571,29 @@ be used anywhere in the kernel). However, for modules, a special · 10 unmodified lines
572571 exported symbol table is kept which limits the entry points to the
573572 kernel proper. Modules can also export symbols.
574573
575−:c:func:`EXPORT_SYMBOL()`
576−-------------------------
574+EXPORT_SYMBOL()
575+---------------
577576
578577 Defined in ``include/linux/export.h``
579578
580579 This is the classic method of exporting a symbol: dynamically loaded
581580 modules will be able to use the symbol as normal.
582581
583−:c:func:`EXPORT_SYMBOL_GPL()`
584−-----------------------------
582+EXPORT_SYMBOL_GPL()
583+-------------------
585584
586585 Defined in ``include/linux/export.h``
587586
588−Similar to :c:func:`EXPORT_SYMBOL()` except that the symbols
589−exported by :c:func:`EXPORT_SYMBOL_GPL()` can only be seen by
590−modules with a :c:func:`MODULE_LICENSE()` that specifies a GPLv2
587+Similar to EXPORT_SYMBOL() except that the symbols
588+exported by EXPORT_SYMBOL_GPL() can only be seen by
589+modules with a MODULE_LICENSE() that specifies a GPLv2
591590 compatible license. It implies that the function is considered an
592591 internal implementation issue, and not really an interface. Some
593592 maintainers and developers may however require EXPORT_SYMBOL_GPL()
594593 when adding any new APIs or functionality.
595594
596−:c:func:`EXPORT_SYMBOL_NS()`
597−----------------------------
595+EXPORT_SYMBOL_NS()
596+------------------
598597
599598 Defined in ``include/linux/export.h``
600599
@@ -602,8 +601,8 @@ This is the variant of EXPORT_SYMBOL() that allows specifying a symbol · 1 unmodified line
602601 namespace. Symbol Namespaces are documented in
603602 Documentation/core-api/symbol-namespaces.rst
604603
605−:c:func:`EXPORT_SYMBOL_NS_GPL()`
606−--------------------------------
604+EXPORT_SYMBOL_NS_GPL()
605+----------------------
607606
608607 Defined in ``include/linux/export.h``
609608
@@ -621,7 +620,7 @@ There used to be three sets of linked-list routines in the kernel · 11 unmodified lines
621620 headers, but this one is the winner. If you don't have some particular
622621 pressing need for a single list, it's a good choice.
623622
624−In particular, :c:func:`list_for_each_entry()` is useful.
623+In particular, list_for_each_entry() is useful.
625624
626625 Return Conventions
627626 ------------------
@@ -631,9 +630,9 @@ and return 0 for success, and a negative error number (eg. ``-EFAULT``) for · 3 unmodified lines
631630 failure. This can be unintuitive at first, but it's fairly widespread in
632631 the kernel.
633632
634−Using :c:func:`ERR_PTR()` (``include/linux/err.h``) to encode a
635−negative error number into a pointer, and :c:func:`IS_ERR()` and
636−:c:func:`PTR_ERR()` to get it back out again: avoids a separate
633+Using ERR_PTR() (``include/linux/err.h``) to encode a
634+negative error number into a pointer, and IS_ERR() and
635+PTR_ERR() to get it back out again: avoids a separate
637636 pointer parameter for the error number. Icky, but in a good way.
638637
639638 Breaking Compilation
@@ -824,7 +823,7 @@ Thanks · 184 unmodified lines
824823 Thanks to Andi Kleen for the idea, answering my questions, fixing my
825824 mistakes, filling content, etc. Philipp Rumpf for more spelling and
826825 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
828827 Sorensen and Andrea Arcangeli added caveats. Michael Elizabeth Chastain
829828 for checking and adding to the Configure section. Telsa Gwynne for
830829 teaching me DocBook.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t