lkml.org 
[lkml]   [2018]   [Dec]   [17]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH 1/1] docs: Revamp tainted-kernels.rst to make it more comprehensible
    Date
    Add a section about /proc/sys/kernel/tainted and a command that decodes it to
    Documentation/admin-guide/tainted-kernels.rst. While at it introduce a table
    that shows the various bits as well as the letters used in oops and panic
    messages. Make the document more user focused and easier to understand, too.

    Backstory: While working updating reporting-bugs.rst I noticed there is no easy
    comprehensible document showing how to check if or why the running kernel might
    be tainted. That's why I wrote a section with a small python command to decodes
    /proc/sys/kernel/tainted. I suspect there is a more elegant and shorter command
    to archive the same, which still works on common machines out of the box;
    please let me know if you know such a command.

    While putting that section in place I ended up writing an easier understandable
    intro and a hopefully better explanation for the tainted flags in bugs, oops or
    panics messages. Only thing missing then was a table that quickly describes the
    various bits and the taint flags before going into more detail, so I added that
    as well.

    Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
    ---
    Documentation/admin-guide/tainted-kernels.rst | 105 ++++++++++++++++--
    1 file changed, 96 insertions(+), 9 deletions(-)

    diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst
    index 28a869c509a0..aabd307a178a 100644
    --- a/Documentation/admin-guide/tainted-kernels.rst
    +++ b/Documentation/admin-guide/tainted-kernels.rst
    @@ -1,10 +1,102 @@
    Tainted kernels
    ---------------

    -Some oops reports contain the string **'Tainted: '** after the program
    -counter. This indicates that the kernel has been tainted by some
    -mechanism. The string is followed by a series of position-sensitive
    -characters, each representing a particular tainted value.
    +The kernel will mark itself as 'tainted' when something occurs that
    +might be relevant later when investigating problems. Don't worry
    +yourself too much about this, most of the time it's not a problem to run
    +a tainted kernel; the information is mainly of interest once someone
    +wants to investigate some problem, as its real cause might be the event
    +that got the kernel tainted. That's why the kernel will remain tainted
    +even after you undo what caused the taint (i.e. unload a proprietary
    +kernel module), to indicate the kernel remains not trustworthy. That's
    +also why the kernel will print the tainted state when it noticed
    +ainternal problem (a 'kernel bug'), a recoverable error ('kernel oops')
    +or a nonrecoverable error ('kernel panic') and writes debug information
    +about this to the logs ``dmesg`` outputs. It's also possible to check
    +the tainted state at runtime through a file in ``/proc/``.
    +
    +
    +Tainted flag in bugs, oops or panics messages
    +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    +
    +You find the tainted state near the top after the list of loaded
    +modules. The state is part of the line that begins with mentioning CPU
    +('CPU:'), Process ID ('PID:'), and a shorted name of the executed
    +command ('Comm:') that triggered the event. When followed by **'Not
    +tainted: '** the kernel was not tainted at the time of the event; if it
    +was, then it will print **'Tainted: '** and characters either letters or
    +blanks. The meaning of those characters is explained in below table. The
    +output for example might state '``Tainted: P WO``' when the kernel got
    +tainted earlier because a proprietary Module (``P``) was loaded, a
    +warning occurred (``W``), and an externally-built module was loaded
    +(``O``). To decode other letters use below table.
    +
    +
    +Decoding tainted state at runtime
    +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    +
    +At runtime, you can query the tainted state by reading
    +``/proc/sys/kernel/tainted``. If that returns ``0``, the kernel is not
    +tainted; any other number indicates the reasons why it is. You might
    +find that number in below table if there was only one reason that got
    +the kernel tainted. If there were multiple reasons you need to decode
    +the number, as it is a bitfield, where each bit indicates the absence or
    +presence of a particular type of taint. You can use the following python
    +command to decode::
    +
    + $ python3 -c 'from pprint import pprint; from itertools import zip_longest; pprint(list(zip_longest(range(1,17), reversed(bin(int(open("/proc/sys/kernel/tainted").read()))[2:]),fillvalue="0")))'
    + [(1, '1'),
    + (2, '0'),
    + (3, '0'),
    + (4, '0'),
    + (5, '0'),
    + (6, '0'),
    + (7, '0'),
    + (8, '0'),
    + (9, '0'),
    + (10, '1'),
    + (11, '0'),
    + (12, '0'),
    + (13, '1'),
    + (14, '0'),
    + (15, '0'),
    + (16, '0')]
    +
    +In this case ``/proc/sys/kernel/tainted`` contained ``4609``, as the
    +kernel got tainted because a proprietary Module (Bit 1) got loaded, a
    +warning occurred (Bit 10), and an externally-built module got loaded
    +(Bit 13). To decode other bits use below table.
    +
    +
    +Table for decoding tainted state
    +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    +
    +=== === ====== ========================================================
    +Bit Log Int Reason that got the kernel tainted
    +=== === ====== ========================================================
    + 1) G/P 0 proprietary module got loaded
    + 2) _/F 2 module was force loaded
    + 3) _/S 4 SMP kernel oops on a officially SMP incapable processor
    + 4) _/R 8 module was force unloaded
    + 5) _/M 16 processor reported a Machine Check Exception (MCE)
    + 6) _/B 32 bad page referenced or some unexpected page flags
    + 7) _/U 64 taint requested by userspace application
    + 8) _/D 128 kernel died recently, i.e. there was an OOPS or BUG
    + 9) _/A 256 ACPI table overridden by user
    +10) _/W 512 kernel issued warning
    +11) _/C 1024 staging driver got loaded
    +12) _/I 2048 workaround for bug in platform firmware in use
    +13) _/O 4096 externally-built ("out-of-tree") module got loaded
    +14) _/E 8192 unsigned module was loaded
    +15) _/L 16384 soft lockup occurred
    +16) _/K 32768 Kernel live patched
    +=== === ====== ========================================================
    +
    +Note: To make reading easier ``_`` is representing a blank in this
    +table.
    +
    +More detailed explanation for tainting
    +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1) ``G`` if all modules loaded have a GPL or compatible license, ``P`` if
    any proprietary module has been loaded. Modules without a
    @@ -52,8 +144,3 @@ characters, each representing a particular tainted value.

    16) ``K`` if the kernel has been live patched.

    -The primary reason for the **'Tainted: '** string is to tell kernel
    -debuggers if this is a clean kernel or if anything unusual has
    -occurred. Tainting is permanent: even if an offending module is
    -unloaded, the tainted value remains to indicate that the kernel is not
    -trustworthy.
    --
    2.18.1
    \
     
     \ /
      Last update: 2018-12-17 16:21    [W:4.426 / U:0.284 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site