Documentation/kernel-hacking/hacking.rst

Source file repositories/reference/linux-study-clean/Documentation/kernel-hacking/hacking.rst

File Facts

System
Linux kernel
Corpus path
Documentation/kernel-hacking/hacking.rst
Extension
.rst
Size
29865 bytes
Lines
830
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: operation-table or driver-model contract
Status
pattern implementation candidate

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

:c:type:`struct file_operations <file_operations>` structure.
Set this field to the macro ``THIS_MODULE``.

Wait Queues ``include/linux/wait.h``
====================================

**[SLEEPS]**

A wait queue is used to wait for someone to wake you up when a certain
condition is true. They must be used carefully to ensure there is no
race condition. You declare a :c:type:`wait_queue_head_t`, and then processes
which want to wait for that condition declare a :c:type:`wait_queue_entry_t`
referring to themselves, and place that in the queue.

Declaring
---------

You declare a ``wait_queue_head_t`` using the
DECLARE_WAIT_QUEUE_HEAD() macro, or using the
init_waitqueue_head() routine in your initialization
code.

Queuing
-------

Placing yourself in the waitqueue is fairly complex, because you must
put yourself in the queue before checking the condition. There is a
macro to do this: wait_event_interruptible()
(``include/linux/wait.h``) The first argument is the wait queue head, and
the second is an expression which is evaluated; the macro returns 0 when
this expression is true, or ``-ERESTARTSYS`` if a signal is received. The
wait_event() version ignores signals.

Waking Up Queued Tasks
----------------------

Call wake_up() (``include/linux/wait.h``), which will wake
up every process in the queue. The exception is if one has
``TASK_EXCLUSIVE`` set, in which case the remainder of the queue will
not be woken. There are other variants of this basic function available
in the same header.

Atomic Operations
=================

Certain operations are guaranteed atomic on all platforms. The first
class of operations work on :c:type:`atomic_t` (``include/asm/atomic.h``);
this contains a signed integer (at least 32 bits long), and you must use
these functions to manipulate or read :c:type:`atomic_t` variables.
atomic_read() and atomic_set() get and set
the counter, atomic_add(), atomic_sub(),
atomic_inc(), atomic_dec(), and
atomic_dec_and_test() (returns true if it was
decremented to zero).

Yes. It returns true (i.e. != 0) if the atomic variable is zero.

Note that these functions are slower than normal arithmetic, and so
should not be used unnecessarily.

The second class of atomic operations is atomic bit operations on an
``unsigned long``, defined in ``include/linux/bitops.h``. These
operations generally take a pointer to the bit pattern, and a bit
number: 0 is the least significant bit. set_bit(),
clear_bit() and change_bit() set, clear,
and flip the given bit. test_and_set_bit(),
test_and_clear_bit() and
test_and_change_bit() do the same thing, except return
true if the bit was previously set; these are particularly useful for
atomically setting flags.

Annotation

Implementation Notes