lkml.org 
[lkml]   [2017]   [May]   [16]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v2 02/53] kernel-hacking: update document
    Date
    This document is fairly updated. Yet, some stuff moved to
    other kernel headers. So, update to point to the right
    places.

    While here, adjust some minor ReST markups.

    Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
    ---
    Documentation/kernel-hacking/hacking.rst | 179 +++++++++++++++++--------------
    1 file changed, 98 insertions(+), 81 deletions(-)

    diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst
    index 75597e627791..1a456b60a7cf 100644
    --- a/Documentation/kernel-hacking/hacking.rst
    +++ b/Documentation/kernel-hacking/hacking.rst
    @@ -56,7 +56,7 @@ interrupts. You can sleep, by calling :c:func:`schedule()`.

    In user context, the ``current`` pointer (indicating the task we are
    currently executing) is valid, and :c:func:`in_interrupt()`
    -(``include/linux/interrupt.h``) is false.
    +(``include/linux/preempt.h``) is false.

    .. warning::

    @@ -114,12 +114,12 @@ time, although different tasklets can run simultaneously.
    Kuznetsov had at the time.

    You can tell you are in a softirq (or tasklet) using the
    -:c:func:`in_softirq()` macro (``include/linux/interrupt.h``).
    +:c:func:`in_softirq()` macro (``include/linux/preempt.h``).

    .. warning::

    - Beware that this will return a false positive if a bh lock (see
    - below) is held.
    + Beware that this will return a false positive if a
    + :ref:`botton half lock <local_bh_disable>` is held.

    Some Basic Rules
    ================
    @@ -154,9 +154,7 @@ The Linux kernel is portable
    ioctls: Not writing a new system call
    =====================================

    -A system call generally looks like this
    -
    -::
    +A system call generally looks like this::

    asmlinkage long sys_mycall(int arg)
    {
    @@ -175,7 +173,9 @@ If all your routine does is read or write some parameter, consider
    implementing a :c:func:`sysfs()` interface instead.

    Inside the ioctl you're in user context to a process. When a error
    -occurs you return a negated errno (see ``include/linux/errno.h``),
    +occurs you return a negated errno (see
    +``include/uapi/asm-generic/errno-base.h``,
    +``include/uapi/asm-generic/errno.h`` and ``include/linux/errno.h``),
    otherwise you return 0.

    After you slept you should check if a signal occurred: the Unix/Linux
    @@ -195,9 +195,7 @@ some data structure.
    If you're doing longer computations: first think userspace. If you
    **really** want to do it in kernel you should regularly check if you need
    to give up the CPU (remember there is cooperative multitasking per CPU).
    -Idiom:
    -
    -::
    +Idiom::

    cond_resched(); /* Will sleep */

    @@ -231,26 +229,24 @@ Really.
    Common Routines
    ===============

    -:c:func:`printk()` ``include/linux/kernel.h``
    ----------------------------------------------
    +:c:func:`printk()`
    +------------------
    +
    +Defined in ``include/linux/printk.h``

    :c:func:`printk()` feeds kernel messages to the console, dmesg, and
    the syslog daemon. It is useful for debugging and reporting errors, and
    can be used inside interrupt context, but use with caution: a machine
    which has its console flooded with printk messages is unusable. It uses
    a format string mostly compatible with ANSI C printf, and C string
    -concatenation to give it a first "priority" argument:
    -
    -::
    +concatenation to give it a first "priority" argument::

    printk(KERN_INFO "i = %u\n", i);


    -See ``include/linux/kernel.h``; for other ``KERN_`` values; these are
    +See ``include/linux/kern_levels.h``; for other ``KERN_`` values; these are
    interpreted by syslog as the level. Special case: for printing an IP
    -address use
    -
    -::
    +address use::

    __be32 ipaddress;
    printk(KERN_INFO "my ip: %pI4\n", &ipaddress);
    @@ -270,8 +266,10 @@ overruns. Make sure that will be enough.
    on top of its printf function: "Printf should not be used for
    chit-chat". You should follow that advice.

    -:c:func:`copy_[to/from]_user()` / :c:func:`get_user()` / :c:func:`put_user()` ``include/linux/uaccess.h``
    ----------------------------------------------------------------------------------------------------------
    +:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()`
    +---------------------------------------------------------------------------------------------------
    +
    +Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h``

    **[SLEEPS]**

    @@ -297,8 +295,10 @@ The functions may sleep implicitly. This should never be called outside
    user context (it makes no sense), with interrupts disabled, or a
    spinlock held.

    -:c:func:`kmalloc()`/:c:func:`kfree()` ``include/linux/slab.h``
    ---------------------------------------------------------------
    +:c:func:`kmalloc()`/:c:func:`kfree()`
    +-------------------------------------
    +
    +Defined in ``include/linux/slab.h``

    **[MAY SLEEP: SEE BELOW]**

    @@ -324,9 +324,9 @@ message, then maybe you called a sleeping allocation function from
    interrupt context without ``GFP_ATOMIC``. You should really fix that.
    Run, don't walk.

    -If you are allocating at least ``PAGE_SIZE`` (``include/asm/page.h``)
    -bytes, consider using :c:func:`__get_free_pages()`
    -(``include/linux/mm.h``). It takes an order argument (0 for page sized,
    +If you are allocating at least ``PAGE_SIZE`` (``asm/page.h`` or
    +``asm/page_types.h``) bytes, consider using :c:func:`__get_free_pages()`
    +(``include/linux/gfp.h``). It takes an order argument (0 for page sized,
    1 for double page, 2 for four pages etc.) and the same memory priority
    flag word as above.

    @@ -344,24 +344,30 @@ routine.
    Before inventing your own cache of often-used objects consider using a
    slab cache in ``include/linux/slab.h``

    -:c:func:`current()` ``include/asm/current.h``
    ----------------------------------------------
    +:c:func:`current()`
    +-------------------
    +
    +Defined in ``include/asm/current.h``

    This global variable (really a macro) contains a pointer to the current
    task structure, so is only valid in user context. For example, when a
    process makes a system call, this will point to the task structure of
    the calling process. It is **not NULL** in interrupt context.

    -:c:func:`mdelay()`/:c:func:`udelay()` ``include/asm/delay.h`` ``include/linux/delay.h``
    ----------------------------------------------------------------------------------------
    +:c:func:`mdelay()`/:c:func:`udelay()`
    +-------------------------------------
    +
    +Defined in ``include/asm/delay.h`` / ``include/linux/delay.h``

    The :c:func:`udelay()` and :c:func:`ndelay()` functions can be
    used for small pauses. Do not use large values with them as you risk
    overflow - the helper function :c:func:`mdelay()` is useful here, or
    consider :c:func:`msleep()`.

    -:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` ``include/asm/byteorder.h``
    ----------------------------------------------------------------------------------------------------------------------------
    +:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()`
    +-----------------------------------------------------------------------------------------------
    +
    +Defined in ``include/asm/byteorder.h``

    The :c:func:`cpu_to_be32()` family (where the "32" can be replaced
    by 64 or 16, and the "be" can be replaced by "le") are the general way
    @@ -375,8 +381,10 @@ to the given type, and return the converted value. The other variation
    is the "in-situ" family, such as :c:func:`cpu_to_be32s()`, which
    convert value referred to by the pointer, and return void.

    -:c:func:`local_irq_save()`/:c:func:`local_irq_restore()` ``include/linux/irqflags.h``
    --------------------------------------------------------------------------------------
    +:c:func:`local_irq_save()`/:c:func:`local_irq_restore()`
    +--------------------------------------------------------
    +
    +Defined in ``include/linux/irqflags.h``

    These routines disable hard interrupts on the local CPU, and restore
    them. They are reentrant; saving the previous state in their one
    @@ -384,16 +392,23 @@ them. They are reentrant; saving the previous state in their one
    enabled, you can simply use :c:func:`local_irq_disable()` and
    :c:func:`local_irq_enable()`.

    -:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()` ``include/linux/interrupt.h``
    ---------------------------------------------------------------------------------------
    +.. _local_bh_disable:
    +
    +:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()`
    +--------------------------------------------------------
    +
    +Defined in ``include/linux/bottom_half.h``
    +

    These routines disable soft interrupts on the local CPU, and restore
    them. They are reentrant; if soft interrupts were disabled before, they
    will still be disabled after this pair of functions has been called.
    They prevent softirqs and tasklets from running on the current CPU.

    -:c:func:`smp_processor_id()`() ``include/asm/smp.h``
    -----------------------------------------------------
    +:c:func:`smp_processor_id()`
    +----------------------------
    +
    +Defined in ``include/linux/smp.h``

    :c:func:`get_cpu()` disables preemption (so you won't suddenly get
    moved to another CPU) and returns the current processor number, between
    @@ -405,8 +420,10 @@ If you know you cannot be preempted by another task (ie. you are in
    interrupt context, or have preemption disabled) you can use
    smp_processor_id().

    -``__init``/``__exit``/``__initdata`` ``include/linux/init.h``
    --------------------------------------------------------------
    +``__init``/``__exit``/``__initdata``
    +------------------------------------
    +
    +Defined in ``include/linux/init.h``

    After boot, the kernel frees up a special section; functions marked with
    ``__init`` and data structures marked with ``__initdata`` are dropped
    @@ -415,10 +432,13 @@ initialization. ``__exit`` is used to declare a function which is only
    required on exit: the function will be dropped if this file is not
    compiled as a module. See the header file for use. Note that it makes no
    sense for a function marked with ``__init`` to be exported to modules
    -with :c:func:`EXPORT_SYMBOL()` - this will break.
    +with :c:func:`EXPORT_SYMBOL()` or :c:func:`EXPORT_SYMBOL_GPL()`- this
    +will break.

    -:c:func:`__initcall()`/:c:func:`module_init()` ``include/linux/init.h``
    ------------------------------------------------------------------------
    +:c:func:`__initcall()`/:c:func:`module_init()`
    +----------------------------------------------
    +
    +Defined in ``include/linux/init.h`` / ``include/linux/module.h``

    Many parts of the kernel are well served as a module
    (dynamically-loadable parts of the kernel). Using the
    @@ -438,8 +458,11 @@ to fail (unfortunately, this has no effect if the module is compiled
    into the kernel). This function is called in user context with
    interrupts enabled, so it can sleep.

    -:c:func:`module_exit()` ``include/linux/init.h``
    -------------------------------------------------
    +:c:func:`module_exit()`
    +-----------------------
    +
    +
    +Defined in ``include/linux/module.h``

    This macro defines the function to be called at module removal time (or
    never, in the case of the file compiled into the kernel). It will only
    @@ -450,8 +473,10 @@ it returns.
    Note that this macro is optional: if it is not present, your module will
    not be removable (except for 'rmmod -f').

    -:c:func:`try_module_get()`/:c:func:`module_put()` ``include/linux/module.h``
    -----------------------------------------------------------------------------
    +:c:func:`try_module_get()`/:c:func:`module_put()`
    +-------------------------------------------------
    +
    +Defined in ``include/linux/module.h``

    These manipulate the module usage count, to protect against removal (a
    module also can't be removed if another module uses one of its exported
    @@ -472,8 +497,8 @@ Wait Queues ``include/linux/wait.h``

    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 ``wait_queue_head_t``, and then processes
    -which want to wait for that condition declare a ``wait_queue_t``
    +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_t`
    referring to themselves, and place that in the queue.

    Declaring
    @@ -490,15 +515,15 @@ 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: :c:func:`wait_event_interruptible()`
    -``include/linux/wait.h`` The first argument is the wait queue head, and
    +(``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
    +this expression is true, or ``-ERESTARTSYS`` if a signal is received. The
    :c:func:`wait_event()` version ignores signals.

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

    -Call :c:func:`wake_up()` ``include/linux/wait.h``;, which will wake
    +Call :c:func:`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
    @@ -508,9 +533,9 @@ Atomic Operations
    =================

    Certain operations are guaranteed atomic on all platforms. The first
    -class of operations work on ``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 atomic_t variables.
    +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.
    :c:func:`atomic_read()` and :c:func:`atomic_set()` get and set
    the counter, :c:func:`atomic_add()`, :c:func:`atomic_sub()`,
    :c:func:`atomic_inc()`, :c:func:`atomic_dec()`, and
    @@ -534,7 +559,7 @@ true if the bit was previously set; these are particularly useful for
    atomically setting flags.

    It is possible to call these operations with bit indices greater than
    -BITS_PER_LONG. The resulting behavior is strange on big-endian
    +``BITS_PER_LONG``. The resulting behavior is strange on big-endian
    platforms though so it is a good idea not to do this.

    Symbols
    @@ -546,14 +571,18 @@ be used anywhere in the kernel). However, for modules, a special
    exported symbol table is kept which limits the entry points to the
    kernel proper. Modules can also export symbols.

    -:c:func:`EXPORT_SYMBOL()` ``include/linux/export.h``
    -----------------------------------------------------
    +:c:func:`EXPORT_SYMBOL()`
    +-------------------------
    +
    +Defined in ``include/linux/export.h``

    This is the classic method of exporting a symbol: dynamically loaded
    modules will be able to use the symbol as normal.

    -:c:func:`EXPORT_SYMBOL_GPL()` ``include/linux/export.h``
    ---------------------------------------------------------
    +:c:func:`EXPORT_SYMBOL_GPL()`
    +-----------------------------
    +
    +Defined in ``include/linux/export.h``

    Similar to :c:func:`EXPORT_SYMBOL()` except that the symbols
    exported by :c:func:`EXPORT_SYMBOL_GPL()` can only be seen by
    @@ -579,11 +608,11 @@ Return Conventions
    ------------------

    For code called in user context, it's very common to defy C convention,
    -and return 0 for success, and a negative error number (eg. -EFAULT) for
    +and return 0 for success, and a negative error number (eg. ``-EFAULT``) for
    failure. This can be unintuitive at first, but it's fairly widespread in
    the kernel.

    -Using :c:func:`ERR_PTR()` ``include/linux/err.h``; to encode a
    +Using :c:func:`ERR_PTR()` (``include/linux/err.h``) to encode a
    negative error number into a pointer, and :c:func:`IS_ERR()` and
    :c:func:`PTR_ERR()` to get it back out again: avoids a separate
    pointer parameter for the error number. Icky, but in a good way.
    @@ -603,9 +632,7 @@ Initializing structure members
    ------------------------------

    The preferred method of initializing structures is to use designated
    -initialisers, as defined by ISO C99, eg:
    -
    -::
    +initialisers, as defined by ISO C99, eg::

    static struct block_device_operations opt_fops = {
    .open = opt_open,
    @@ -716,18 +743,14 @@ Kernel Cantrips

    Some favorites from browsing the source. Feel free to add to this list.

    -``arch/x86/include/asm/delay.h:``
    -
    -::
    +``arch/x86/include/asm/delay.h``::

    #define ndelay(n) (__builtin_constant_p(n) ? \
    ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
    __ndelay(n))


    -``include/linux/fs.h``:
    -
    -::
    +``include/linux/fs.h``::

    /*
    * Kernel pointers have redundant information, so we can use a
    @@ -741,9 +764,7 @@ Some favorites from browsing the source. Feel free to add to this list.
    #define PTR_ERR(ptr) ((long)(ptr))
    #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000))

    -``arch/x86/include/asm/uaccess_32.h:``
    -
    -::
    +``arch/x86/include/asm/uaccess_32.h:``::

    #define copy_to_user(to,from,n) \
    (__builtin_constant_p(n) ? \
    @@ -751,9 +772,7 @@ Some favorites from browsing the source. Feel free to add to this list.
    __generic_copy_to_user((to),(from),(n)))


    -``arch/sparc/kernel/head.S:``
    -
    -::
    +``arch/sparc/kernel/head.S:``::

    /*
    * Sun people can't spell worth damn. "compatability" indeed.
    @@ -772,9 +791,7 @@ Some favorites from browsing the source. Feel free to add to this list.
    .asciz "compatible"


    -``arch/sparc/lib/checksum.S:``
    -
    -::
    +``arch/sparc/lib/checksum.S:``::

    /* Sun, you just can't beat me, you just can't. Stop trying,
    * give up. I'm serious, I am going to kick the living shit
    --
    2.9.3
    \
     
     \ /
      Last update: 2017-05-16 14:25    [W:2.487 / U:0.424 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site