Skip to content

L
linux
Commit 5512128f authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files
Options

Merge branch 'dev-tools' into doc/4.9 

Coalesce development-tool documents into a single directory and sphinxify
them.
parents 44f4ddd1 5f096274
Show whitespace changes
Inline Side-by-side
Showing with 1567 additions and 325 deletions
Documentation/coccinelle.txt → Documentation/dev-tools/coccinelle.rst
View file @ 5512128f
Copyright 2010 Nicolas Palix <npalix@diku.dk> .. Copyright 2010 Nicolas Palix <npalix@diku.dk>
Copyright 2010 Julia Lawall <julia@diku.dk> .. Copyright 2010 Julia Lawall <julia@diku.dk>
Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr> .. Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr>
.. highlight:: none
Getting Coccinelle Coccinelle
~~~~~~~~~~~~~~~~~~~~ ==========
Coccinelle is a tool for pattern matching and text transformation that has
many uses in kernel development, including the application of complex,
tree-wide patches and detection of problematic programming patterns.
Getting Coccinelle
-------------------
The semantic patches included in the kernel use features and options The semantic patches included in the kernel use features and options
which are provided by Coccinelle version 1.0.0-rc11 and above. which are provided by Coccinelle version 1.0.0-rc11 and above.
...@@ -22,24 +30,23 @@ of many distributions, e.g. : ...@@ -22,24 +30,23 @@ of many distributions, e.g. :
- NetBSD - NetBSD
- FreeBSD - FreeBSD
You can get the latest version released from the Coccinelle homepage at You can get the latest version released from the Coccinelle homepage at
http://coccinelle.lip6.fr/ http://coccinelle.lip6.fr/
Information and tips about Coccinelle are also provided on the wiki Information and tips about Coccinelle are also provided on the wiki
pages at http://cocci.ekstranet.diku.dk/wiki/doku.php pages at http://cocci.ekstranet.diku.dk/wiki/doku.php
Once you have it, run the following command: Once you have it, run the following command::
./configure ./configure
make make
as a regular user, and install it with as a regular user, and install it with::
sudo make install sudo make install
Supplemental documentation Supplemental documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
For supplemental documentation refer to the wiki: For supplemental documentation refer to the wiki:
...@@ -47,49 +54,52 @@ https://bottest.wiki.kernel.org/coccicheck ...@@ -47,49 +54,52 @@ https://bottest.wiki.kernel.org/coccicheck
The wiki documentation always refers to the linux-next version of the script. The wiki documentation always refers to the linux-next version of the script.
Using Coccinelle on the Linux kernel Using Coccinelle on the Linux kernel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------
A Coccinelle-specific target is defined in the top level A Coccinelle-specific target is defined in the top level
Makefile. This target is named 'coccicheck' and calls the 'coccicheck' Makefile. This target is named ``coccicheck`` and calls the ``coccicheck``
front-end in the 'scripts' directory. front-end in the ``scripts`` directory.
Four basic modes are defined: patch, report, context, and org. The mode to Four basic modes are defined: ``patch``, ``report``, ``context``, and
use is specified by setting the MODE variable with 'MODE=<mode>'. ``org``. The mode to use is specified by setting the MODE variable with
``MODE=<mode>``.
'patch' proposes a fix, when possible. - ``patch`` proposes a fix, when possible.
'report' generates a list in the following format: - ``report`` generates a list in the following format:
file:line:column-column: message file:line:column-column: message
'context' highlights lines of interest and their context in a - ``context`` highlights lines of interest and their context in a
diff-like style.Lines of interest are indicated with '-'. diff-like style.Lines of interest are indicated with ``-``.
'org' generates a report in the Org mode format of Emacs. - ``org`` generates a report in the Org mode format of Emacs.
Note that not all semantic patches implement all modes. For easy use Note that not all semantic patches implement all modes. For easy use
of Coccinelle, the default mode is "report". of Coccinelle, the default mode is "report".
Two other modes provide some common combinations of these modes. Two other modes provide some common combinations of these modes.
'chain' tries the previous modes in the order above until one succeeds. - ``chain`` tries the previous modes in the order above until one succeeds.
'rep+ctxt' runs successively the report mode and the context mode. - ``rep+ctxt`` runs successively the report mode and the context mode.
It should be used with the C option (described later) It should be used with the C option (described later)
which checks the code on a file basis. which checks the code on a file basis.
Examples: Examples
To make a report for every semantic patch, run the following command: ~~~~~~~~
To make a report for every semantic patch, run the following command::
make coccicheck MODE=report make coccicheck MODE=report
To produce patches, run: To produce patches, run::
make coccicheck MODE=patch make coccicheck MODE=patch
The coccicheck target applies every semantic patch available in the The coccicheck target applies every semantic patch available in the
sub-directories of 'scripts/coccinelle' to the entire Linux kernel. sub-directories of ``scripts/coccinelle`` to the entire Linux kernel.
For each semantic patch, a commit message is proposed. It gives a For each semantic patch, a commit message is proposed. It gives a
description of the problem being checked by the semantic patch, and description of the problem being checked by the semantic patch, and
...@@ -99,15 +109,15 @@ As any static code analyzer, Coccinelle produces false ...@@ -99,15 +109,15 @@ As any static code analyzer, Coccinelle produces false
positives. Thus, reports must be carefully checked, and patches positives. Thus, reports must be carefully checked, and patches
reviewed. reviewed.
To enable verbose messages set the V= variable, for example: To enable verbose messages set the V= variable, for example::
make coccicheck MODE=report V=1 make coccicheck MODE=report V=1
Coccinelle parallelization Coccinelle parallelization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
By default, coccicheck tries to run as parallel as possible. To change By default, coccicheck tries to run as parallel as possible. To change
the parallelism, set the J= variable. For example, to run across 4 CPUs: the parallelism, set the J= variable. For example, to run across 4 CPUs::
make coccicheck MODE=report J=4 make coccicheck MODE=report J=4
...@@ -115,44 +125,47 @@ As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, ...@@ -115,44 +125,47 @@ As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization,
if support for this is detected you will benefit from parmap parallelization. if support for this is detected you will benefit from parmap parallelization.
When parmap is enabled coccicheck will enable dynamic load balancing by using When parmap is enabled coccicheck will enable dynamic load balancing by using
'--chunksize 1' argument, this ensures we keep feeding threads with work ``--chunksize 1`` argument, this ensures we keep feeding threads with work
one by one, so that we avoid the situation where most work gets done by only one by one, so that we avoid the situation where most work gets done by only
a few threads. With dynamic load balancing, if a thread finishes early we keep a few threads. With dynamic load balancing, if a thread finishes early we keep
feeding it more work. feeding it more work.
When parmap is enabled, if an error occurs in Coccinelle, this error When parmap is enabled, if an error occurs in Coccinelle, this error
value is propagated back, the return value of the 'make coccicheck' value is propagated back, the return value of the ``make coccicheck``
captures this return value. captures this return value.
Using Coccinelle with a single semantic patch Using Coccinelle with a single semantic patch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------------
The optional make variable COCCI can be used to check a single The optional make variable COCCI can be used to check a single
semantic patch. In that case, the variable must be initialized with semantic patch. In that case, the variable must be initialized with
the name of the semantic patch to apply. the name of the semantic patch to apply.
For instance: For instance::
make coccicheck COCCI=<my_SP.cocci> MODE=patch make coccicheck COCCI=<my_SP.cocci> MODE=patch
or
or::
make coccicheck COCCI=<my_SP.cocci> MODE=report make coccicheck COCCI=<my_SP.cocci> MODE=report
Controlling Which Files are Processed by Coccinelle Controlling Which Files are Processed by Coccinelle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------------------
By default the entire kernel source tree is checked. By default the entire kernel source tree is checked.
To apply Coccinelle to a specific directory, M= can be used. To apply Coccinelle to a specific directory, ``M=`` can be used.
For example, to check drivers/net/wireless/ one may write: For example, to check drivers/net/wireless/ one may write::
make coccicheck M=drivers/net/wireless/ make coccicheck M=drivers/net/wireless/
To apply Coccinelle on a file basis, instead of a directory basis, the To apply Coccinelle on a file basis, instead of a directory basis, the
following command may be used: following command may be used::
make C=1 CHECK="scripts/coccicheck" make C=1 CHECK="scripts/coccicheck"
To check only newly edited code, use the value 2 for the C flag, i.e. To check only newly edited code, use the value 2 for the C flag, i.e.::
make C=2 CHECK="scripts/coccicheck" make C=2 CHECK="scripts/coccicheck"
...@@ -166,8 +179,8 @@ semantic patch as shown in the previous section. ...@@ -166,8 +179,8 @@ semantic patch as shown in the previous section.
The "report" mode is the default. You can select another one with the The "report" mode is the default. You can select another one with the
MODE variable explained above. MODE variable explained above.
Debugging Coccinelle SmPL patches Debugging Coccinelle SmPL patches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------
Using coccicheck is best as it provides in the spatch command line Using coccicheck is best as it provides in the spatch command line
include options matching the options used when we compile the kernel. include options matching the options used when we compile the kernel.
...@@ -177,8 +190,8 @@ manually run Coccinelle with debug options added. ...@@ -177,8 +190,8 @@ manually run Coccinelle with debug options added.
Alternatively you can debug running Coccinelle against SmPL patches Alternatively you can debug running Coccinelle against SmPL patches
by asking for stderr to be redirected to stderr, by default stderr by asking for stderr to be redirected to stderr, by default stderr
is redirected to /dev/null, if you'd like to capture stderr you is redirected to /dev/null, if you'd like to capture stderr you
can specify the DEBUG_FILE="file.txt" option to coccicheck. For can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For
instance: instance::
rm -f cocci.err rm -f cocci.err
make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err
...@@ -186,7 +199,7 @@ instance: ...@@ -186,7 +199,7 @@ instance:
You can use SPFLAGS to add debugging flags, for instance you may want to You can use SPFLAGS to add debugging flags, for instance you may want to
add both --profile --show-trying to SPFLAGS when debugging. For instance add both --profile --show-trying to SPFLAGS when debugging. For instance
you may want to use: you may want to use::
rm -f err.log rm -f err.log
export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci
...@@ -198,24 +211,24 @@ work. ...@@ -198,24 +211,24 @@ work.
DEBUG_FILE support is only supported when using coccinelle >= 1.2. DEBUG_FILE support is only supported when using coccinelle >= 1.2.
.cocciconfig support .cocciconfig support
~~~~~~~~~~~~~~~~~~~~~~ --------------------
Coccinelle supports reading .cocciconfig for default Coccinelle options that Coccinelle supports reading .cocciconfig for default Coccinelle options that
should be used every time spatch is spawned, the order of precedence for should be used every time spatch is spawned, the order of precedence for
variables for .cocciconfig is as follows: variables for .cocciconfig is as follows:
o Your current user's home directory is processed first - Your current user's home directory is processed first
o Your directory from which spatch is called is processed next - Your directory from which spatch is called is processed next
o The directory provided with the --dir option is processed last, if used - The directory provided with the --dir option is processed last, if used
Since coccicheck runs through make, it naturally runs from the kernel Since coccicheck runs through make, it naturally runs from the kernel
proper dir, as such the second rule above would be implied for picking up a proper dir, as such the second rule above would be implied for picking up a
.cocciconfig when using 'make coccicheck'. .cocciconfig when using ``make coccicheck``.
'make coccicheck' also supports using M= targets.If you do not supply ``make coccicheck`` also supports using M= targets.If you do not supply
any M= target, it is assumed you want to target the entire kernel. any M= target, it is assumed you want to target the entire kernel.
The kernel coccicheck script has: The kernel coccicheck script has::
if [ "$KBUILD_EXTMOD" = "" ] ; then if [ "$KBUILD_EXTMOD" = "" ] ; then
OPTIONS="--dir $srctree $COCCIINCLUDE" OPTIONS="--dir $srctree $COCCIINCLUDE"
...@@ -235,12 +248,12 @@ override any of the kernel's .coccicheck's settings using SPFLAGS. ...@@ -235,12 +248,12 @@ override any of the kernel's .coccicheck's settings using SPFLAGS.
We help Coccinelle when used against Linux with a set of sensible defaults We help Coccinelle when used against Linux with a set of sensible defaults
options for Linux with our own Linux .cocciconfig. This hints to coccinelle options for Linux with our own Linux .cocciconfig. This hints to coccinelle
git can be used for 'git grep' queries over coccigrep. A timeout of 200 git can be used for ``git grep`` queries over coccigrep. A timeout of 200
seconds should suffice for now. seconds should suffice for now.
The options picked up by coccinelle when reading a .cocciconfig do not appear The options picked up by coccinelle when reading a .cocciconfig do not appear
as arguments to spatch processes running on your system, to confirm what as arguments to spatch processes running on your system, to confirm what
options will be used by Coccinelle run: options will be used by Coccinelle run::
spatch --print-options-only spatch --print-options-only
...@@ -252,219 +265,227 @@ carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if ...@@ -252,219 +265,227 @@ carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if
desired. See below section "Additional flags" for more details on how to use desired. See below section "Additional flags" for more details on how to use
idutils. idutils.
Additional flags Additional flags
~~~~~~~~~~~~~~~~~~ ----------------
Additional flags can be passed to spatch through the SPFLAGS Additional flags can be passed to spatch through the SPFLAGS
variable. This works as Coccinelle respects the last flags variable. This works as Coccinelle respects the last flags
given to it when options are in conflict. given to it when options are in conflict. ::
make SPFLAGS=--use-glimpse coccicheck make SPFLAGS=--use-glimpse coccicheck
Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. Coccinelle supports idutils as well but requires coccinelle >= 1.0.6.
When no ID file is specified coccinelle assumes your ID database file When no ID file is specified coccinelle assumes your ID database file
is in the file .id-utils.index on the top level of the kernel, coccinelle is in the file .id-utils.index on the top level of the kernel, coccinelle
carries a script scripts/idutils_index.sh which creates the database with carries a script scripts/idutils_index.sh which creates the database with::
mkid -i C --output .id-utils.index mkid -i C --output .id-utils.index
If you have another database filename you can also just symlink with this If you have another database filename you can also just symlink with this
name. name. ::
make SPFLAGS=--use-idutils coccicheck make SPFLAGS=--use-idutils coccicheck
Alternatively you can specify the database filename explicitly, for Alternatively you can specify the database filename explicitly, for
instance: instance::
make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck
See spatch --help to learn more about spatch options. See ``spatch --help`` to learn more about spatch options.
Note that the '--use-glimpse' and '--use-idutils' options Note that the ``--use-glimpse`` and ``--use-idutils`` options
require external tools for indexing the code. None of them is require external tools for indexing the code. None of them is
thus active by default. However, by indexing the code with thus active by default. However, by indexing the code with
one of these tools, and according to the cocci file used, one of these tools, and according to the cocci file used,
spatch could proceed the entire code base more quickly. spatch could proceed the entire code base more quickly.
SmPL patch specific options SmPL patch specific options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
SmPL patches can have their own requirements for options passed SmPL patches can have their own requirements for options passed
to Coccinelle. SmPL patch specific options can be provided by to Coccinelle. SmPL patch specific options can be provided by
providing them at the top of the SmPL patch, for instance: providing them at the top of the SmPL patch, for instance::
// Options: --no-includes --include-headers // Options: --no-includes --include-headers
SmPL patch Coccinelle requirements SmPL patch Coccinelle requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------
As Coccinelle features get added some more advanced SmPL patches As Coccinelle features get added some more advanced SmPL patches
may require newer versions of Coccinelle. If an SmPL patch requires may require newer versions of Coccinelle. If an SmPL patch requires
at least a version of Coccinelle, this can be specified as follows, at least a version of Coccinelle, this can be specified as follows,
as an example if requiring at least Coccinelle >= 1.0.5: as an example if requiring at least Coccinelle >= 1.0.5::
// Requires: 1.0.5 // Requires: 1.0.5
Proposing new semantic patches Proposing new semantic patches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
New semantic patches can be proposed and submitted by kernel New semantic patches can be proposed and submitted by kernel
developers. For sake of clarity, they should be organized in the developers. For sake of clarity, they should be organized in the
sub-directories of 'scripts/coccinelle/'. sub-directories of ``scripts/coccinelle/``.
Detailed description of the ``report`` mode
-------------------------------------------
Detailed description of the 'report' mode ``report`` generates a list in the following format::
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
'report' generates a list in the following format:
file:line:column-column: message file:line:column-column: message
Example: Example
~~~~~~~
Running Running::
make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci
will execute the following part of the SmPL script. will execute the following part of the SmPL script::
<smpl> <smpl>
@r depends on !context && !patch && (org || report)@ @r depends on !context && !patch && (org || report)@
expression x; expression x;
position p; position p;
@@ @@
ERR_PTR@p(PTR_ERR(x)) ERR_PTR@p(PTR_ERR(x))
@script:python depends on report@ @script:python depends on report@
p << r.p; p << r.p;
x << r.x; x << r.x;
@@ @@
msg="ERR_CAST can be used with %s" % (x) msg="ERR_CAST can be used with %s" % (x)
coccilib.report.print_report(p[0], msg) coccilib.report.print_report(p[0], msg)
</smpl> </smpl>
This SmPL excerpt generates entries on the standard output, as This SmPL excerpt generates entries on the standard output, as
illustrated below: illustrated below::
/home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg
/home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth
/home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg
Detailed description of the 'patch' mode Detailed description of the ``patch`` mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------
When the 'patch' mode is available, it proposes a fix for each problem When the ``patch`` mode is available, it proposes a fix for each problem
identified. identified.
Example: Example
~~~~~~~
Running::
Running
make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci
will execute the following part of the SmPL script. will execute the following part of the SmPL script::
<smpl> <smpl>
@ depends on !context && patch && !org && !report @ @ depends on !context && patch && !org && !report @
expression x; expression x;
@@ @@
- ERR_PTR(PTR_ERR(x)) - ERR_PTR(PTR_ERR(x))
+ ERR_CAST(x) + ERR_CAST(x)
</smpl> </smpl>
This SmPL excerpt generates patch hunks on the standard output, as This SmPL excerpt generates patch hunks on the standard output, as
illustrated below: illustrated below::
diff -u -p a/crypto/ctr.c b/crypto/ctr.c diff -u -p a/crypto/ctr.c b/crypto/ctr.c
--- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200
+++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200
@@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct
alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
CRYPTO_ALG_TYPE_MASK); CRYPTO_ALG_TYPE_MASK);
if (IS_ERR(alg)) if (IS_ERR(alg))
- return ERR_PTR(PTR_ERR(alg)); - return ERR_PTR(PTR_ERR(alg));
+ return ERR_CAST(alg); + return ERR_CAST(alg);
/* Block size must be >= 4 bytes. */ /* Block size must be >= 4 bytes. */
err = -EINVAL; err = -EINVAL;
Detailed description of the 'context' mode Detailed description of the ``context`` mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------
'context' highlights lines of interest and their context ``context`` highlights lines of interest and their context
in a diff-like style. in a diff-like style.
NOTE: The diff-like output generated is NOT an applicable patch. The **NOTE**: The diff-like output generated is NOT an applicable patch. The
intent of the 'context' mode is to highlight the important lines intent of the ``context`` mode is to highlight the important lines
(annotated with minus, '-') and gives some surrounding context (annotated with minus, ``-``) and gives some surrounding context
lines around. This output can be used with the diff mode of lines around. This output can be used with the diff mode of
Emacs to review the code. Emacs to review the code.
Example: Example
~~~~~~~
Running::
Running
make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci
will execute the following part of the SmPL script. will execute the following part of the SmPL script::
<smpl> <smpl>
@ depends on context && !patch && !org && !report@ @ depends on context && !patch && !org && !report@
expression x; expression x;
@@ @@
* ERR_PTR(PTR_ERR(x)) * ERR_PTR(PTR_ERR(x))
</smpl> </smpl>
This SmPL excerpt generates diff hunks on the standard output, as This SmPL excerpt generates diff hunks on the standard output, as
illustrated below: illustrated below::
diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing
--- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200
+++ /tmp/nothing +++ /tmp/nothing
@@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct
alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER,
CRYPTO_ALG_TYPE_MASK); CRYPTO_ALG_TYPE_MASK);
if (IS_ERR(alg)) if (IS_ERR(alg))
- return ERR_PTR(PTR_ERR(alg)); - return ERR_PTR(PTR_ERR(alg));
/* Block size must be >= 4 bytes. */ /* Block size must be >= 4 bytes. */
err = -EINVAL; err = -EINVAL;
Detailed description of the 'org' mode Detailed description of the ``org`` mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------
``org`` generates a report in the Org mode format of Emacs.
'org' generates a report in the Org mode format of Emacs. Example
~~~~~~~
Example: Running::
Running
make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci
will execute the following part of the SmPL script. will execute the following part of the SmPL script::
<smpl> <smpl>
@r depends on !context && !patch && (org || report)@ @r depends on !context && !patch && (org || report)@
expression x; expression x;
position p; position p;
@@ @@
ERR_PTR@p(PTR_ERR(x)) ERR_PTR@p(PTR_ERR(x))
@script:python depends on org@ @script:python depends on org@
p << r.p; p << r.p;
x << r.x; x << r.x;
@@ @@
msg="ERR_CAST can be used with %s" % (x) msg="ERR_CAST can be used with %s" % (x)
msg_safe=msg.replace("[","@(").replace("]",")") msg_safe=msg.replace("[","@(").replace("]",")")
coccilib.org.print_todo(p[0], msg_safe) coccilib.org.print_todo(p[0], msg_safe)
</smpl> </smpl>
This SmPL excerpt generates Org entries on the standard output, as This SmPL excerpt generates Org entries on the standard output, as
illustrated below: illustrated below::
* TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]]
* TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]]
* TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]]
Documentation/gcov.txt → Documentation/dev-tools/gcov.rst
View file @ 5512128f
Using gcov with the Linux kernel Using gcov with the Linux kernel
================================ ================================
1. Introduction
2. Preparation
3. Customization
4. Files
5. Modules
6. Separated build and test machines
7. Troubleshooting
Appendix A: sample script: gather_on_build.sh
Appendix B: sample script: gather_on_test.sh
1. Introduction
===============
gcov profiling kernel support enables the use of GCC's coverage testing gcov profiling kernel support enables the use of GCC's coverage testing
tool gcov [1] with the Linux kernel. Coverage data of a running kernel tool gcov_ with the Linux kernel. Coverage data of a running kernel
is exported in gcov-compatible format via the "gcov" debugfs directory. is exported in gcov-compatible format via the "gcov" debugfs directory.
To get coverage data for a specific file, change to the kernel build To get coverage data for a specific file, change to the kernel build
directory and use gcov with the -o option as follows (requires root): directory and use gcov with the ``-o`` option as follows (requires root)::
# cd /tmp/linux-out # cd /tmp/linux-out
# gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c
This will create source code files annotated with execution counts This will create source code files annotated with execution counts
in the current directory. In addition, graphical gcov front-ends such in the current directory. In addition, graphical gcov front-ends such
as lcov [2] can be used to automate the process of collecting data as lcov_ can be used to automate the process of collecting data
for the entire kernel and provide coverage overviews in HTML format. for the entire kernel and provide coverage overviews in HTML format.
Possible uses: Possible uses:
...@@ -36,25 +22,23 @@ Possible uses: ...@@ -36,25 +22,23 @@ Possible uses:
* minimizing kernel configurations (do I need this option if the * minimizing kernel configurations (do I need this option if the
associated code is never run?) associated code is never run?)
-- .. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php
[1] http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
[2] http://ltp.sourceforge.net/coverage/lcov.php
2. Preparation Preparation
============== -----------
Configure the kernel with: Configure the kernel with::
CONFIG_DEBUG_FS=y CONFIG_DEBUG_FS=y
CONFIG_GCOV_KERNEL=y CONFIG_GCOV_KERNEL=y
select the gcc's gcov format, default is autodetect based on gcc version: select the gcc's gcov format, default is autodetect based on gcc version::
CONFIG_GCOV_FORMAT_AUTODETECT=y CONFIG_GCOV_FORMAT_AUTODETECT=y
and to get coverage data for the entire kernel: and to get coverage data for the entire kernel::
CONFIG_GCOV_PROFILE_ALL=y CONFIG_GCOV_PROFILE_ALL=y
...@@ -63,58 +47,62 @@ larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported ...@@ -63,58 +47,62 @@ larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported
on all architectures. on all architectures.
Profiling data will only become accessible once debugfs has been Profiling data will only become accessible once debugfs has been
mounted: mounted::
mount -t debugfs none /sys/kernel/debug mount -t debugfs none /sys/kernel/debug
3. Customization Customization
================ -------------
To enable profiling for specific files or directories, add a line To enable profiling for specific files or directories, add a line
similar to the following to the respective kernel Makefile: similar to the following to the respective kernel Makefile:
For a single file (e.g. main.o): - For a single file (e.g. main.o)::
GCOV_PROFILE_main.o := y GCOV_PROFILE_main.o := y
For all files in one directory: - For all files in one directory::
GCOV_PROFILE := y GCOV_PROFILE := y
To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL
is specified, use: is specified, use::
GCOV_PROFILE_main.o := n GCOV_PROFILE_main.o := n
and:
and::
GCOV_PROFILE := n GCOV_PROFILE := n
Only files which are linked to the main kernel image or are compiled as Only files which are linked to the main kernel image or are compiled as
kernel modules are supported by this mechanism. kernel modules are supported by this mechanism.
4. Files Files
======== -----
The gcov kernel support creates the following files in debugfs: The gcov kernel support creates the following files in debugfs:
/sys/kernel/debug/gcov ``/sys/kernel/debug/gcov``
Parent directory for all gcov-related files. Parent directory for all gcov-related files.
/sys/kernel/debug/gcov/reset ``/sys/kernel/debug/gcov/reset``
Global reset file: resets all coverage data to zero when Global reset file: resets all coverage data to zero when
written to. written to.
/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda``
The actual gcov data file as understood by the gcov The actual gcov data file as understood by the gcov
tool. Resets file coverage data to zero when written to. tool. Resets file coverage data to zero when written to.
/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno``
Symbolic link to a static data file required by the gcov Symbolic link to a static data file required by the gcov
tool. This file is generated by gcc when compiling with tool. This file is generated by gcc when compiling with
option -ftest-coverage. option ``-ftest-coverage``.
5. Modules Modules
========== -------
Kernel modules may contain cleanup code which is only run during Kernel modules may contain cleanup code which is only run during
module unload time. The gcov mechanism provides a means to collect module unload time. The gcov mechanism provides a means to collect
...@@ -124,7 +112,7 @@ Once the module is loaded again, the associated coverage counters are ...@@ -124,7 +112,7 @@ Once the module is loaded again, the associated coverage counters are
initialized with the data from its previous instantiation. initialized with the data from its previous instantiation.
This behavior can be deactivated by specifying the gcov_persist kernel This behavior can be deactivated by specifying the gcov_persist kernel
parameter: parameter::
gcov_persist=0 gcov_persist=0
...@@ -132,8 +120,8 @@ At run-time, a user can also choose to discard data for an unloaded ...@@ -132,8 +120,8 @@ At run-time, a user can also choose to discard data for an unloaded
module by writing to its data file or the global reset file. module by writing to its data file or the global reset file.
6. Separated build and test machines Separated build and test machines
==================================== ---------------------------------
The gcov kernel profiling infrastructure is designed to work out-of-the The gcov kernel profiling infrastructure is designed to work out-of-the
box for setups where kernels are built and run on the same machine. In box for setups where kernels are built and run on the same machine. In
...@@ -142,36 +130,36 @@ must be made, depending on where the gcov tool is used: ...@@ -142,36 +130,36 @@ must be made, depending on where the gcov tool is used:
a) gcov is run on the TEST machine a) gcov is run on the TEST machine
The gcov tool version on the test machine must be compatible with the The gcov tool version on the test machine must be compatible with the
gcc version used for kernel build. Also the following files need to be gcc version used for kernel build. Also the following files need to be
copied from build to test machine: copied from build to test machine:
from the source tree: from the source tree:
- all C source files + headers - all C source files + headers
from the build tree: from the build tree:
- all C source files + headers - all C source files + headers
- all .gcda and .gcno files - all .gcda and .gcno files
- all links to directories - all links to directories
It is important to note that these files need to be placed into the It is important to note that these files need to be placed into the
exact same file system location on the test machine as on the build exact same file system location on the test machine as on the build
machine. If any of the path components is symbolic link, the actual machine. If any of the path components is symbolic link, the actual
directory needs to be used instead (due to make's CURDIR handling). directory needs to be used instead (due to make's CURDIR handling).
b) gcov is run on the BUILD machine b) gcov is run on the BUILD machine
The following files need to be copied after each test case from test The following files need to be copied after each test case from test
to build machine: to build machine:
from the gcov directory in sysfs: from the gcov directory in sysfs:
- all .gcda files - all .gcda files
- all links to .gcno files - all links to .gcno files
These files can be copied to any location on the build machine. gcov These files can be copied to any location on the build machine. gcov
must then be called with the -o option pointing to that directory. must then be called with the -o option pointing to that directory.
Example directory setup on the build machine: Example directory setup on the build machine::
/tmp/linux: kernel source tree /tmp/linux: kernel source tree
/tmp/out: kernel build directory as specified by make O= /tmp/out: kernel build directory as specified by make O=
...@@ -181,77 +169,88 @@ Example directory setup on the build machine: ...@@ -181,77 +169,88 @@ Example directory setup on the build machine:
[user@build] gcov -o /tmp/coverage/tmp/out/init main.c [user@build] gcov -o /tmp/coverage/tmp/out/init main.c
7. Troubleshooting Troubleshooting
================== ---------------
Problem
Compilation aborts during linker step.
Problem: Compilation aborts during linker step. Cause
Cause: Profiling flags are specified for source files which are not Profiling flags are specified for source files which are not
linked to the main kernel or which are linked by a custom linked to the main kernel or which are linked by a custom
linker procedure. linker procedure.
Solution: Exclude affected source files from profiling by specifying
GCOV_PROFILE := n or GCOV_PROFILE_basename.o := n in the Solution
Exclude affected source files from profiling by specifying
``GCOV_PROFILE := n`` or ``GCOV_PROFILE_basename.o := n`` in the
corresponding Makefile. corresponding Makefile.
Problem: Files copied from sysfs appear empty or incomplete. Problem
Cause: Due to the way seq_file works, some tools such as cp or tar Files copied from sysfs appear empty or incomplete.
Cause
Due to the way seq_file works, some tools such as cp or tar
may not correctly copy files from sysfs. may not correctly copy files from sysfs.
Solution: Use 'cat' to read .gcda files and 'cp -d' to copy links.
Solution
Use ``cat``' to read ``.gcda`` files and ``cp -d`` to copy links.
Alternatively use the mechanism shown in Appendix B. Alternatively use the mechanism shown in Appendix B.
Appendix A: gather_on_build.sh Appendix A: gather_on_build.sh
============================== ------------------------------
Sample script to gather coverage meta files on the build machine Sample script to gather coverage meta files on the build machine
(see 6a): (see 6a)::
#!/bin/bash
#!/bin/bash
KSRC=$1 KSRC=$1
KOBJ=$2 KOBJ=$2
DEST=$3 DEST=$3
if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then
echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2 echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2
exit 1 exit 1
fi fi
KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \
-perm /u+r,g+r | tar cfz $DEST -P -T - -perm /u+r,g+r | tar cfz $DEST -P -T -
if [ $? -eq 0 ] ; then if [ $? -eq 0 ] ; then
echo "$DEST successfully created, copy to test system and unpack with:" echo "$DEST successfully created, copy to test system and unpack with:"
echo " tar xfz $DEST -P" echo " tar xfz $DEST -P"
else else
echo "Could not create file $DEST" echo "Could not create file $DEST"
fi fi
Appendix B: gather_on_test.sh Appendix B: gather_on_test.sh
============================= -----------------------------
Sample script to gather coverage data files on the test machine Sample script to gather coverage data files on the test machine
(see 6b): (see 6b)::
#!/bin/bash -e #!/bin/bash -e
DEST=$1 DEST=$1
GCDA=/sys/kernel/debug/gcov GCDA=/sys/kernel/debug/gcov
if [ -z "$DEST" ] ; then if [ -z "$DEST" ] ; then
echo "Usage: $0 <output.tar.gz>" >&2 echo "Usage: $0 <output.tar.gz>" >&2
exit 1 exit 1
fi fi
TEMPDIR=$(mktemp -d) TEMPDIR=$(mktemp -d)
echo Collecting data.. echo Collecting data..
find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \;
find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \;
find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \;
tar czf $DEST -C $TEMPDIR sys tar czf $DEST -C $TEMPDIR sys
rm -rf $TEMPDIR rm -rf $TEMPDIR
echo "$DEST successfully created, copy to build system and unpack with:" echo "$DEST successfully created, copy to build system and unpack with:"
echo " tar xfz $DEST" echo " tar xfz $DEST"
Documentation/gdb-kernel-debugging.txt → Documentation/dev-tools/gdb-kernel-debugging.rst
View file @ 5512128f
.. highlight:: none
Debugging kernel and modules via gdb Debugging kernel and modules via gdb
==================================== ====================================
...@@ -13,54 +15,58 @@ be transferred to the other gdb stubs as well. ...@@ -13,54 +15,58 @@ be transferred to the other gdb stubs as well.
Requirements Requirements
------------ ------------
o gdb 7.2+ (recommended: 7.4+) with python support enabled (typically true - gdb 7.2+ (recommended: 7.4+) with python support enabled (typically true
for distributions) for distributions)
Setup Setup
----- -----
o Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and - Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and
www.qemu.org for more details). For cross-development, www.qemu.org for more details). For cross-development,
http://landley.net/aboriginal/bin keeps a pool of machine images and http://landley.net/aboriginal/bin keeps a pool of machine images and
toolchains that can be helpful to start from. toolchains that can be helpful to start from.
o Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave - Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave
CONFIG_DEBUG_INFO_REDUCED off. If your architecture supports CONFIG_DEBUG_INFO_REDUCED off. If your architecture supports
CONFIG_FRAME_POINTER, keep it enabled. CONFIG_FRAME_POINTER, keep it enabled.
o Install that kernel on the guest. - Install that kernel on the guest.
Alternatively, QEMU allows to boot the kernel directly using -kernel, Alternatively, QEMU allows to boot the kernel directly using -kernel,
-append, -initrd command line switches. This is generally only useful if -append, -initrd command line switches. This is generally only useful if
you do not depend on modules. See QEMU documentation for more details on you do not depend on modules. See QEMU documentation for more details on
this mode. this mode.
o Enable the gdb stub of QEMU/KVM, either - Enable the gdb stub of QEMU/KVM, either
- at VM startup time by appending "-s" to the QEMU command line - at VM startup time by appending "-s" to the QEMU command line
or or
- during runtime by issuing "gdbserver" from the QEMU monitor - during runtime by issuing "gdbserver" from the QEMU monitor
console console
o cd /path/to/linux-build - cd /path/to/linux-build
o Start gdb: gdb vmlinux - Start gdb: gdb vmlinux
Note: Some distros may restrict auto-loading of gdb scripts to known safe Note: Some distros may restrict auto-loading of gdb scripts to known safe
directories. In case gdb reports to refuse loading vmlinux-gdb.py, add directories. In case gdb reports to refuse loading vmlinux-gdb.py, add::
add-auto-load-safe-path /path/to/linux-build add-auto-load-safe-path /path/to/linux-build
to ~/.gdbinit. See gdb help for more details. to ~/.gdbinit. See gdb help for more details.
o Attach to the booted guest: - Attach to the booted guest::
(gdb) target remote :1234 (gdb) target remote :1234
Examples of using the Linux-provided gdb helpers Examples of using the Linux-provided gdb helpers
------------------------------------------------ ------------------------------------------------
o Load module (and main kernel) symbols: - Load module (and main kernel) symbols::
(gdb) lx-symbols (gdb) lx-symbols
loading vmlinux loading vmlinux
scanning for modules in /home/user/linux/build scanning for modules in /home/user/linux/build
...@@ -72,17 +78,20 @@ Examples of using the Linux-provided gdb helpers ...@@ -72,17 +78,20 @@ Examples of using the Linux-provided gdb helpers
... ...
loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko
o Set a breakpoint on some not yet loaded module function, e.g.: - Set a breakpoint on some not yet loaded module function, e.g.::
(gdb) b btrfs_init_sysfs (gdb) b btrfs_init_sysfs
Function "btrfs_init_sysfs" not defined. Function "btrfs_init_sysfs" not defined.
Make breakpoint pending on future shared library load? (y or [n]) y Make breakpoint pending on future shared library load? (y or [n]) y
Breakpoint 1 (btrfs_init_sysfs) pending. Breakpoint 1 (btrfs_init_sysfs) pending.
o Continue the target - Continue the target::
(gdb) c (gdb) c
o Load the module on the target and watch the symbols being loaded as well as - Load the module on the target and watch the symbols being loaded as well as
the breakpoint hit: the breakpoint hit::
loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko
loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko
loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko
...@@ -91,7 +100,8 @@ Examples of using the Linux-provided gdb helpers ...@@ -91,7 +100,8 @@ Examples of using the Linux-provided gdb helpers
Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36 Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36
36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj); 36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj);
o Dump the log buffer of the target kernel: - Dump the log buffer of the target kernel::
(gdb) lx-dmesg (gdb) lx-dmesg
[ 0.000000] Initializing cgroup subsys cpuset [ 0.000000] Initializing cgroup subsys cpuset
[ 0.000000] Initializing cgroup subsys cpu [ 0.000000] Initializing cgroup subsys cpu
...@@ -102,19 +112,22 @@ Examples of using the Linux-provided gdb helpers ...@@ -102,19 +112,22 @@ Examples of using the Linux-provided gdb helpers
[ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved [ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved
.... ....
o Examine fields of the current task struct: - Examine fields of the current task struct::
(gdb) p $lx_current().pid (gdb) p $lx_current().pid
$1 = 4998 $1 = 4998
(gdb) p $lx_current().comm (gdb) p $lx_current().comm
$2 = "modprobe\000\000\000\000\000\000\000" $2 = "modprobe\000\000\000\000\000\000\000"
o Make use of the per-cpu function for the current or a specified CPU: - Make use of the per-cpu function for the current or a specified CPU::
(gdb) p $lx_per_cpu("runqueues").nr_running (gdb) p $lx_per_cpu("runqueues").nr_running
$3 = 1 $3 = 1
(gdb) p $lx_per_cpu("runqueues", 2).nr_running (gdb) p $lx_per_cpu("runqueues", 2).nr_running
$4 = 0 $4 = 0
o Dig into hrtimers using the container_of helper: - Dig into hrtimers using the container_of helper::
(gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next (gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next
(gdb) p *$container_of($next, "struct hrtimer", "node") (gdb) p *$container_of($next, "struct hrtimer", "node")
$5 = { $5 = {
...@@ -144,7 +157,7 @@ List of commands and functions ...@@ -144,7 +157,7 @@ List of commands and functions
------------------------------ ------------------------------
The number of commands and convenience functions may evolve over the time, The number of commands and convenience functions may evolve over the time,
this is just a snapshot of the initial version: this is just a snapshot of the initial version::
(gdb) apropos lx (gdb) apropos lx
function lx_current -- Return current task function lx_current -- Return current task
......
Documentation/kasan.txt → Documentation/dev-tools/kasan.rst
View file @ 5512128f
KernelAddressSanitizer (KASAN) The Kernel Address Sanitizer (KASAN)
============================== ====================================
0. Overview Overview
=========== --------
KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides
a fast and comprehensive solution for finding use-after-free and out-of-bounds a fast and comprehensive solution for finding use-after-free and out-of-bounds
...@@ -12,12 +12,12 @@ KASAN uses compile-time instrumentation for checking every memory access, ...@@ -12,12 +12,12 @@ KASAN uses compile-time instrumentation for checking every memory access,
therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is
required for detection of out-of-bounds accesses to stack or global variables. required for detection of out-of-bounds accesses to stack or global variables.
Currently KASAN is supported only for x86_64 and arm64 architecture. Currently KASAN is supported only for the x86_64 and arm64 architectures.
1. Usage Usage
======== -----
To enable KASAN configure kernel with: To enable KASAN configure kernel with::
CONFIG_KASAN = y CONFIG_KASAN = y
...@@ -32,26 +32,28 @@ For better bug detection and nicer reporting, enable CONFIG_STACKTRACE. ...@@ -32,26 +32,28 @@ For better bug detection and nicer reporting, enable CONFIG_STACKTRACE.
To disable instrumentation for specific files or directories, add a line To disable instrumentation for specific files or directories, add a line
similar to the following to the respective kernel Makefile: similar to the following to the respective kernel Makefile:
For a single file (e.g. main.o): - For a single file (e.g. main.o)::
KASAN_SANITIZE_main.o := n KASAN_SANITIZE_main.o := n
For all files in one directory: - For all files in one directory::
KASAN_SANITIZE := n KASAN_SANITIZE := n
1.1 Error reports Error reports
================= ~~~~~~~~~~~~~
A typical out of bounds access report looks like this: A typical out of bounds access report looks like this::
================================================================== ==================================================================
BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3 BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3
Write of size 1 by task modprobe/1689 Write of size 1 by task modprobe/1689
============================================================================= =============================================================================
BUG kmalloc-128 (Not tainted): kasan error BUG kmalloc-128 (Not tainted): kasan error
----------------------------------------------------------------------------- -----------------------------------------------------------------------------
Disabling lock debugging due to kernel taint Disabling lock debugging due to kernel taint
INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689 INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689
__slab_alloc+0x4b4/0x4f0 __slab_alloc+0x4b4/0x4f0
kmem_cache_alloc_trace+0x10b/0x190 kmem_cache_alloc_trace+0x10b/0x190
kmalloc_oob_right+0x3d/0x75 [test_kasan] kmalloc_oob_right+0x3d/0x75 [test_kasan]
...@@ -60,26 +62,26 @@ INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689 ...@@ -60,26 +62,26 @@ INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689
load_module+0x2cb3/0x3b20 load_module+0x2cb3/0x3b20
SyS_finit_module+0x76/0x80 SyS_finit_module+0x76/0x80
system_call_fastpath+0x12/0x17 system_call_fastpath+0x12/0x17
INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080 INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080
INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720 INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720
Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ
Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk
Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk. Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk.
Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc ........ Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc ........
Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ
CPU: 0 PID: 1689 Comm: modprobe Tainted: G B 3.18.0-rc1-mm1+ #98 CPU: 0 PID: 1689 Comm: modprobe Tainted: G B 3.18.0-rc1-mm1+ #98
Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014 Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014
ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78 ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78
ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8 ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8
ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558 ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558
Call Trace: Call Trace:
[<ffffffff81cc68ae>] dump_stack+0x46/0x58 [<ffffffff81cc68ae>] dump_stack+0x46/0x58
[<ffffffff811fd848>] print_trailer+0xf8/0x160 [<ffffffff811fd848>] print_trailer+0xf8/0x160
[<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan]
...@@ -101,20 +103,20 @@ Call Trace: ...@@ -101,20 +103,20 @@ Call Trace:
[<ffffffff8110fd70>] ? m_show+0x240/0x240 [<ffffffff8110fd70>] ? m_show+0x240/0x240
[<ffffffff81115f06>] SyS_finit_module+0x76/0x80 [<ffffffff81115f06>] SyS_finit_module+0x76/0x80
[<ffffffff81cd3129>] system_call_fastpath+0x12/0x17 [<ffffffff81cd3129>] system_call_fastpath+0x12/0x17
Memory state around the buggy address: Memory state around the buggy address:
ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc
ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00 ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00
>ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc >ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc
^ ^
ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb
ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb
ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb
================================================================== ==================================================================
The header of the report discribe what kind of bug happened and what kind of The header of the report discribe what kind of bug happened and what kind of
access caused it. It's followed by the description of the accessed slub object access caused it. It's followed by the description of the accessed slub object
...@@ -137,8 +139,8 @@ In the report above the arrows point to the shadow byte 03, which means that ...@@ -137,8 +139,8 @@ In the report above the arrows point to the shadow byte 03, which means that
the accessed address is partially accessible. the accessed address is partially accessible.
2. Implementation details Implementation details
========================= ----------------------
From a high level, our approach to memory error detection is similar to that From a high level, our approach to memory error detection is similar to that
of kmemcheck: use shadow memory to record whether each byte of memory is safe of kmemcheck: use shadow memory to record whether each byte of memory is safe
...@@ -150,15 +152,15 @@ AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory ...@@ -150,15 +152,15 @@ AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory
offset to translate a memory address to its corresponding shadow address. offset to translate a memory address to its corresponding shadow address.
Here is the function which translates an address to its corresponding shadow Here is the function which translates an address to its corresponding shadow
address: address::
static inline void *kasan_mem_to_shadow(const void *addr) static inline void *kasan_mem_to_shadow(const void *addr)
{ {
return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT)
+ KASAN_SHADOW_OFFSET; + KASAN_SHADOW_OFFSET;
} }
where KASAN_SHADOW_SCALE_SHIFT = 3. where ``KASAN_SHADOW_SCALE_SHIFT = 3``.
Compile-time instrumentation used for checking memory accesses. Compiler inserts Compile-time instrumentation used for checking memory accesses. Compiler inserts
function calls (__asan_load*(addr), __asan_store*(addr)) before each memory function calls (__asan_load*(addr), __asan_store*(addr)) before each memory
......
Documentation/kcov.txt → Documentation/dev-tools/kcov.rst
View file @ 5512128f
...@@ -12,38 +12,38 @@ To achieve this goal it does not collect coverage in soft/hard interrupts ...@@ -12,38 +12,38 @@ To achieve this goal it does not collect coverage in soft/hard interrupts
and instrumentation of some inherently non-deterministic parts of kernel is and instrumentation of some inherently non-deterministic parts of kernel is
disbled (e.g. scheduler, locking). disbled (e.g. scheduler, locking).
Usage: Usage
====== -----
Configure kernel with: Configure the kernel with::
CONFIG_KCOV=y CONFIG_KCOV=y
CONFIG_KCOV requires gcc built on revision 231296 or later. CONFIG_KCOV requires gcc built on revision 231296 or later.
Profiling data will only become accessible once debugfs has been mounted: Profiling data will only become accessible once debugfs has been mounted::
mount -t debugfs none /sys/kernel/debug mount -t debugfs none /sys/kernel/debug
The following program demonstrates kcov usage from within a test program: The following program demonstrates kcov usage from within a test program::
#include <stdio.h> #include <stdio.h>
#include <stddef.h> #include <stddef.h>
#include <stdint.h> #include <stdint.h>
#include <stdlib.h> #include <stdlib.h>
#include <sys/types.h> #include <sys/types.h>
#include <sys/stat.h> #include <sys/stat.h>
#include <sys/ioctl.h> #include <sys/ioctl.h>
#include <sys/mman.h> #include <sys/mman.h>
#include <unistd.h> #include <unistd.h>
#include <fcntl.h> #include <fcntl.h>
#define KCOV_INIT_TRACE _IOR('c', 1, unsigned long) #define KCOV_INIT_TRACE _IOR('c', 1, unsigned long)
#define KCOV_ENABLE _IO('c', 100) #define KCOV_ENABLE _IO('c', 100)
#define KCOV_DISABLE _IO('c', 101) #define KCOV_DISABLE _IO('c', 101)
#define COVER_SIZE (64<<10) #define COVER_SIZE (64<<10)
int main(int argc, char **argv) int main(int argc, char **argv)
{ {
int fd; int fd;
unsigned long *cover, n, i; unsigned long *cover, n, i;
...@@ -83,24 +83,24 @@ int main(int argc, char **argv) ...@@ -83,24 +83,24 @@ int main(int argc, char **argv)
if (close(fd)) if (close(fd))
perror("close"), exit(1); perror("close"), exit(1);
return 0; return 0;
} }
After piping through addr2line output of the program looks as follows: After piping through addr2line output of the program looks as follows::
SyS_read SyS_read
fs/read_write.c:562 fs/read_write.c:562
__fdget_pos __fdget_pos
fs/file.c:774 fs/file.c:774
__fget_light __fget_light
fs/file.c:746 fs/file.c:746
__fget_light __fget_light
fs/file.c:750 fs/file.c:750
__fget_light __fget_light
fs/file.c:760 fs/file.c:760
__fdget_pos __fdget_pos
fs/file.c:784 fs/file.c:784
SyS_read SyS_read
fs/read_write.c:562 fs/read_write.c:562
If a program needs to collect coverage from several threads (independently), If a program needs to collect coverage from several threads (independently),
it needs to open /sys/kernel/debug/kcov in each thread separately. it needs to open /sys/kernel/debug/kcov in each thread separately.
......
Documentation/kmemcheck.txt → Documentation/dev-tools/kmemcheck.rst
View file @ 5512128f
GETTING STARTED WITH KMEMCHECK Getting started with kmemcheck
============================== ==============================
Vegard Nossum <vegardno@ifi.uio.no> Vegard Nossum <vegardno@ifi.uio.no>
Contents Introduction
======== ------------
0. Introduction
1. Downloading
2. Configuring and compiling
3. How to use
3.1. Booting
3.2. Run-time enable/disable
3.3. Debugging
3.4. Annotating false positives
4. Reporting errors
5. Technical description
0. Introduction
===============
kmemcheck is a debugging feature for the Linux Kernel. More specifically, it kmemcheck is a debugging feature for the Linux Kernel. More specifically, it
is a dynamic checker that detects and warns about some uses of uninitialized is a dynamic checker that detects and warns about some uses of uninitialized
...@@ -40,21 +26,20 @@ as much memory as normal. For this reason, kmemcheck is strictly a debugging ...@@ -40,21 +26,20 @@ as much memory as normal. For this reason, kmemcheck is strictly a debugging
feature. feature.
1. Downloading Downloading
============== -----------
As of version 2.6.31-rc1, kmemcheck is included in the mainline kernel. As of version 2.6.31-rc1, kmemcheck is included in the mainline kernel.
2. Configuring and compiling Configuring and compiling
============================ -------------------------
kmemcheck only works for the x86 (both 32- and 64-bit) platform. A number of kmemcheck only works for the x86 (both 32- and 64-bit) platform. A number of
configuration variables must have specific settings in order for the kmemcheck configuration variables must have specific settings in order for the kmemcheck
menu to even appear in "menuconfig". These are: menu to even appear in "menuconfig". These are:
o CONFIG_CC_OPTIMIZE_FOR_SIZE=n - ``CONFIG_CC_OPTIMIZE_FOR_SIZE=n``
This option is located under "General setup" / "Optimize for size". This option is located under "General setup" / "Optimize for size".
Without this, gcc will use certain optimizations that usually lead to Without this, gcc will use certain optimizations that usually lead to
...@@ -63,13 +48,11 @@ menu to even appear in "menuconfig". These are: ...@@ -63,13 +48,11 @@ menu to even appear in "menuconfig". These are:
16 bits. kmemcheck sees only the 32-bit load, and may trigger a 16 bits. kmemcheck sees only the 32-bit load, and may trigger a
warning for the upper 16 bits (if they're uninitialized). warning for the upper 16 bits (if they're uninitialized).
o CONFIG_SLAB=y or CONFIG_SLUB=y - ``CONFIG_SLAB=y`` or ``CONFIG_SLUB=y``
This option is located under "General setup" / "Choose SLAB This option is located under "General setup" / "Choose SLAB
allocator". allocator".
o CONFIG_FUNCTION_TRACER=n - ``CONFIG_FUNCTION_TRACER=n``
This option is located under "Kernel hacking" / "Tracers" / "Kernel This option is located under "Kernel hacking" / "Tracers" / "Kernel
Function Tracer" Function Tracer"
...@@ -80,12 +63,11 @@ menu to even appear in "menuconfig". These are: ...@@ -80,12 +63,11 @@ menu to even appear in "menuconfig". These are:
modifies memory that was tracked by kmemcheck, the result is an modifies memory that was tracked by kmemcheck, the result is an
endless recursive page fault. endless recursive page fault.
o CONFIG_DEBUG_PAGEALLOC=n - ``CONFIG_DEBUG_PAGEALLOC=n``
This option is located under "Kernel hacking" / "Memory Debugging" This option is located under "Kernel hacking" / "Memory Debugging"
/ "Debug page memory allocations". / "Debug page memory allocations".
In addition, I highly recommend turning on CONFIG_DEBUG_INFO=y. This is also In addition, I highly recommend turning on ``CONFIG_DEBUG_INFO=y``. This is also
located under "Kernel hacking". With this, you will be able to get line number located under "Kernel hacking". With this, you will be able to get line number
information from the kmemcheck warnings, which is extremely valuable in information from the kmemcheck warnings, which is extremely valuable in
debugging a problem. This option is not mandatory, however, because it slows debugging a problem. This option is not mandatory, however, because it slows
...@@ -95,12 +77,10 @@ Now the kmemcheck menu should be visible (under "Kernel hacking" / "Memory ...@@ -95,12 +77,10 @@ Now the kmemcheck menu should be visible (under "Kernel hacking" / "Memory
Debugging" / "kmemcheck: trap use of uninitialized memory"). Here follows Debugging" / "kmemcheck: trap use of uninitialized memory"). Here follows
a description of the kmemcheck configuration variables: a description of the kmemcheck configuration variables:
o CONFIG_KMEMCHECK - ``CONFIG_KMEMCHECK``
This must be enabled in order to use kmemcheck at all... This must be enabled in order to use kmemcheck at all...
o CONFIG_KMEMCHECK_[DISABLED | ENABLED | ONESHOT]_BY_DEFAULT - ``CONFIG_KMEMCHECK_``[``DISABLED`` | ``ENABLED`` | ``ONESHOT``]``_BY_DEFAULT``
This option controls the status of kmemcheck at boot-time. "Enabled" This option controls the status of kmemcheck at boot-time. "Enabled"
will enable kmemcheck right from the start, "disabled" will boot the will enable kmemcheck right from the start, "disabled" will boot the
kernel as normal (but with the kmemcheck code compiled in, so it can kernel as normal (but with the kmemcheck code compiled in, so it can
...@@ -125,8 +105,7 @@ a description of the kmemcheck configuration variables: ...@@ -125,8 +105,7 @@ a description of the kmemcheck configuration variables:
time overhead is not incurred, and the kernel will be almost as fast time overhead is not incurred, and the kernel will be almost as fast
as normal. as normal.
o CONFIG_KMEMCHECK_QUEUE_SIZE - ``CONFIG_KMEMCHECK_QUEUE_SIZE``
Select the maximum number of error reports to store in an internal Select the maximum number of error reports to store in an internal
(fixed-size) buffer. Since errors can occur virtually anywhere and in (fixed-size) buffer. Since errors can occur virtually anywhere and in
any context, we need a temporary storage area which is guaranteed not any context, we need a temporary storage area which is guaranteed not
...@@ -147,8 +126,7 @@ a description of the kmemcheck configuration variables: ...@@ -147,8 +126,7 @@ a description of the kmemcheck configuration variables:
will get lost in that way instead. Try setting this to 10 or so on will get lost in that way instead. Try setting this to 10 or so on
such a setup. such a setup.
o CONFIG_KMEMCHECK_SHADOW_COPY_SHIFT - ``CONFIG_KMEMCHECK_SHADOW_COPY_SHIFT``
Select the number of shadow bytes to save along with each entry of the Select the number of shadow bytes to save along with each entry of the
error-report queue. These bytes indicate what parts of an allocation error-report queue. These bytes indicate what parts of an allocation
are initialized, uninitialized, etc. and will be displayed when an are initialized, uninitialized, etc. and will be displayed when an
...@@ -161,8 +139,7 @@ a description of the kmemcheck configuration variables: ...@@ -161,8 +139,7 @@ a description of the kmemcheck configuration variables:
The default value should be fine for debugging most problems. It also The default value should be fine for debugging most problems. It also
fits nicely within 80 columns. fits nicely within 80 columns.
o CONFIG_KMEMCHECK_PARTIAL_OK - ``CONFIG_KMEMCHECK_PARTIAL_OK``
This option (when enabled) works around certain GCC optimizations that This option (when enabled) works around certain GCC optimizations that
produce 32-bit reads from 16-bit variables where the upper 16 bits are produce 32-bit reads from 16-bit variables where the upper 16 bits are
thrown away afterwards. thrown away afterwards.
...@@ -171,8 +148,7 @@ a description of the kmemcheck configuration variables: ...@@ -171,8 +148,7 @@ a description of the kmemcheck configuration variables:
some real errors, but disabling it would probably produce a lot of some real errors, but disabling it would probably produce a lot of
false positives. false positives.
o CONFIG_KMEMCHECK_BITOPS_OK - ``CONFIG_KMEMCHECK_BITOPS_OK``
This option silences warnings that would be generated for bit-field This option silences warnings that would be generated for bit-field
accesses where not all the bits are initialized at the same time. This accesses where not all the bits are initialized at the same time. This
may also hide some real bugs. may also hide some real bugs.
...@@ -184,36 +160,36 @@ a description of the kmemcheck configuration variables: ...@@ -184,36 +160,36 @@ a description of the kmemcheck configuration variables:
Now compile the kernel as usual. Now compile the kernel as usual.
3. How to use How to use
============= ----------
3.1. Booting Booting
============ ~~~~~~~
First some information about the command-line options. There is only one First some information about the command-line options. There is only one
option specific to kmemcheck, and this is called "kmemcheck". It can be used option specific to kmemcheck, and this is called "kmemcheck". It can be used
to override the default mode as chosen by the CONFIG_KMEMCHECK_*_BY_DEFAULT to override the default mode as chosen by the ``CONFIG_KMEMCHECK_*_BY_DEFAULT``
option. Its possible settings are: option. Its possible settings are:
o kmemcheck=0 (disabled) - ``kmemcheck=0`` (disabled)
o kmemcheck=1 (enabled) - ``kmemcheck=1`` (enabled)
o kmemcheck=2 (one-shot mode) - ``kmemcheck=2`` (one-shot mode)
If SLUB debugging has been enabled in the kernel, it may take precedence over If SLUB debugging has been enabled in the kernel, it may take precedence over
kmemcheck in such a way that the slab caches which are under SLUB debugging kmemcheck in such a way that the slab caches which are under SLUB debugging
will not be tracked by kmemcheck. In order to ensure that this doesn't happen will not be tracked by kmemcheck. In order to ensure that this doesn't happen
(even though it shouldn't by default), use SLUB's boot option "slub_debug", (even though it shouldn't by default), use SLUB's boot option ``slub_debug``,
like this: slub_debug=- like this: ``slub_debug=-``
In fact, this option may also be used for fine-grained control over SLUB vs. In fact, this option may also be used for fine-grained control over SLUB vs.
kmemcheck. For example, if the command line includes "kmemcheck=1 kmemcheck. For example, if the command line includes
slub_debug=,dentry", then SLUB debugging will be used only for the "dentry" ``kmemcheck=1 slub_debug=,dentry``, then SLUB debugging will be used only
slab cache, and with kmemcheck tracking all the other caches. This is advanced for the "dentry" slab cache, and with kmemcheck tracking all the other
usage, however, and is not generally recommended. caches. This is advanced usage, however, and is not generally recommended.
3.2. Run-time enable/disable Run-time enable/disable
============================ ~~~~~~~~~~~~~~~~~~~~~~~
When the kernel has booted, it is possible to enable or disable kmemcheck at When the kernel has booted, it is possible to enable or disable kmemcheck at
run-time. WARNING: This feature is still experimental and may cause false run-time. WARNING: This feature is still experimental and may cause false
...@@ -221,36 +197,36 @@ positive warnings to appear. Therefore, try not to use this. If you find that ...@@ -221,36 +197,36 @@ positive warnings to appear. Therefore, try not to use this. If you find that
it doesn't work properly (e.g. you see an unreasonable amount of warnings), I it doesn't work properly (e.g. you see an unreasonable amount of warnings), I
will be happy to take bug reports. will be happy to take bug reports.
Use the file /proc/sys/kernel/kmemcheck for this purpose, e.g.: Use the file ``/proc/sys/kernel/kmemcheck`` for this purpose, e.g.::
$ echo 0 > /proc/sys/kernel/kmemcheck # disables kmemcheck $ echo 0 > /proc/sys/kernel/kmemcheck # disables kmemcheck
The numbers are the same as for the kmemcheck= command-line option. The numbers are the same as for the ``kmemcheck=`` command-line option.
3.3. Debugging Debugging
============== ~~~~~~~~~
A typical report will look something like this: A typical report will look something like this::
WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024)
80000000000000000000000000000000000000000088ffff0000000000000000 80000000000000000000000000000000000000000088ffff0000000000000000
i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u
^ ^
Pid: 1856, comm: ntpdate Not tainted 2.6.29-rc5 #264 945P-A Pid: 1856, comm: ntpdate Not tainted 2.6.29-rc5 #264 945P-A
RIP: 0010:[<ffffffff8104ede8>] [<ffffffff8104ede8>] __dequeue_signal+0xc8/0x190 RIP: 0010:[<ffffffff8104ede8>] [<ffffffff8104ede8>] __dequeue_signal+0xc8/0x190
RSP: 0018:ffff88003cdf7d98 EFLAGS: 00210002 RSP: 0018:ffff88003cdf7d98 EFLAGS: 00210002
RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009
RDX: ffff88003e5d6018 RSI: ffff88003e5d6024 RDI: ffff88003cdf7e84 RDX: ffff88003e5d6018 RSI: ffff88003e5d6024 RDI: ffff88003cdf7e84
RBP: ffff88003cdf7db8 R08: ffff88003e5d6000 R09: 0000000000000000 RBP: ffff88003cdf7db8 R08: ffff88003e5d6000 R09: 0000000000000000
R10: 0000000000000080 R11: 0000000000000000 R12: 000000000000000e R10: 0000000000000080 R11: 0000000000000000 R12: 000000000000000e
R13: ffff88003cdf7e78 R14: ffff88003d530710 R15: ffff88003d5a98c8 R13: ffff88003cdf7e78 R14: ffff88003d530710 R15: ffff88003d5a98c8
FS: 0000000000000000(0000) GS:ffff880001982000(0063) knlGS:00000 FS: 0000000000000000(0000) GS:ffff880001982000(0063) knlGS:00000
CS: 0010 DS: 002b ES: 002b CR0: 0000000080050033 CS: 0010 DS: 002b ES: 002b CR0: 0000000080050033
CR2: ffff88003f806ea0 CR3: 000000003c036000 CR4: 00000000000006a0 CR2: ffff88003f806ea0 CR3: 000000003c036000 CR4: 00000000000006a0
DR0: 0000000000000000 DR1: 0000000000000000 DR2: 0000000000000000 DR0: 0000000000000000 DR1: 0000000000000000 DR2: 0000000000000000
DR3: 0000000000000000 DR6: 00000000ffff4ff0 DR7: 0000000000000400 DR3: 0000000000000000 DR6: 00000000ffff4ff0 DR7: 0000000000000400
[<ffffffff8104f04e>] dequeue_signal+0x8e/0x170 [<ffffffff8104f04e>] dequeue_signal+0x8e/0x170
[<ffffffff81050bd8>] get_signal_to_deliver+0x98/0x390 [<ffffffff81050bd8>] get_signal_to_deliver+0x98/0x390
[<ffffffff8100b87d>] do_notify_resume+0xad/0x7d0 [<ffffffff8100b87d>] do_notify_resume+0xad/0x7d0
...@@ -261,8 +237,8 @@ The single most valuable information in this report is the RIP (or EIP on 32- ...@@ -261,8 +237,8 @@ The single most valuable information in this report is the RIP (or EIP on 32-
bit) value. This will help us pinpoint exactly which instruction that caused bit) value. This will help us pinpoint exactly which instruction that caused
the warning. the warning.
If your kernel was compiled with CONFIG_DEBUG_INFO=y, then all we have to do If your kernel was compiled with ``CONFIG_DEBUG_INFO=y``, then all we have to do
is give this address to the addr2line program, like this: is give this address to the addr2line program, like this::
$ addr2line -e vmlinux -i ffffffff8104ede8 $ addr2line -e vmlinux -i ffffffff8104ede8
arch/x86/include/asm/string_64.h:12 arch/x86/include/asm/string_64.h:12
...@@ -270,71 +246,73 @@ is give this address to the addr2line program, like this: ...@@ -270,71 +246,73 @@ is give this address to the addr2line program, like this:
kernel/signal.c:380 kernel/signal.c:380
kernel/signal.c:410 kernel/signal.c:410
The "-e vmlinux" tells addr2line which file to look in. IMPORTANT: This must The "``-e vmlinux``" tells addr2line which file to look in. **IMPORTANT:**
be the vmlinux of the kernel that produced the warning in the first place! If This must be the vmlinux of the kernel that produced the warning in the
not, the line number information will almost certainly be wrong. first place! If not, the line number information will almost certainly be
wrong.
The "-i" tells addr2line to also print the line numbers of inlined functions.
In this case, the flag was very important, because otherwise, it would only The "``-i``" tells addr2line to also print the line numbers of inlined
have printed the first line, which is just a call to memcpy(), which could be functions. In this case, the flag was very important, because otherwise,
called from a thousand places in the kernel, and is therefore not very useful. it would only have printed the first line, which is just a call to
These inlined functions would not show up in the stack trace above, simply ``memcpy()``, which could be called from a thousand places in the kernel, and
because the kernel doesn't load the extra debugging information. This is therefore not very useful. These inlined functions would not show up in
technique can of course be used with ordinary kernel oopses as well. the stack trace above, simply because the kernel doesn't load the extra
debugging information. This technique can of course be used with ordinary
In this case, it's the caller of memcpy() that is interesting, and it can be kernel oopses as well.
found in include/asm-generic/siginfo.h, line 287:
In this case, it's the caller of ``memcpy()`` that is interesting, and it can be
281 static inline void copy_siginfo(struct siginfo *to, struct siginfo *from) found in ``include/asm-generic/siginfo.h``, line 287::
282 {
283 if (from->si_code < 0) 281 static inline void copy_siginfo(struct siginfo *to, struct siginfo *from)
284 memcpy(to, from, sizeof(*to)); 282 {
285 else 283 if (from->si_code < 0)
286 /* _sigchld is currently the largest know union member */ 284 memcpy(to, from, sizeof(*to));
287 memcpy(to, from, __ARCH_SI_PREAMBLE_SIZE + sizeof(from->_sifields._sigchld)); 285 else
288 } 286 /* _sigchld is currently the largest know union member */
287 memcpy(to, from, __ARCH_SI_PREAMBLE_SIZE + sizeof(from->_sifields._sigchld));
288 }
Since this was a read (kmemcheck usually warns about reads only, though it can Since this was a read (kmemcheck usually warns about reads only, though it can
warn about writes to unallocated or freed memory as well), it was probably the warn about writes to unallocated or freed memory as well), it was probably the
"from" argument which contained some uninitialized bytes. Following the chain "from" argument which contained some uninitialized bytes. Following the chain
of calls, we move upwards to see where "from" was allocated or initialized, of calls, we move upwards to see where "from" was allocated or initialized,
kernel/signal.c, line 380: ``kernel/signal.c``, line 380::
359 static void collect_signal(int sig, struct sigpending *list, siginfo_t *info) 359 static void collect_signal(int sig, struct sigpending *list, siginfo_t *info)
360 { 360 {
... ...
367 list_for_each_entry(q, &list->list, list) { 367 list_for_each_entry(q, &list->list, list) {
368 if (q->info.si_signo == sig) { 368 if (q->info.si_signo == sig) {
369 if (first) 369 if (first)
370 goto still_pending; 370 goto still_pending;
371 first = q; 371 first = q;
... ...
377 if (first) { 377 if (first) {
378 still_pending: 378 still_pending:
379 list_del_init(&first->list); 379 list_del_init(&first->list);
380 copy_siginfo(info, &first->info); 380 copy_siginfo(info, &first->info);
381 __sigqueue_free(first); 381 __sigqueue_free(first);
... ...
392 } 392 }
393 } 393 }
Here, it is &first->info that is being passed on to copy_siginfo(). The Here, it is ``&first->info`` that is being passed on to ``copy_siginfo()``. The
variable "first" was found on a list -- passed in as the second argument to variable ``first`` was found on a list -- passed in as the second argument to
collect_signal(). We continue our journey through the stack, to figure out ``collect_signal()``. We continue our journey through the stack, to figure out
where the item on "list" was allocated or initialized. We move to line 410: where the item on "list" was allocated or initialized. We move to line 410::
395 static int __dequeue_signal(struct sigpending *pending, sigset_t *mask, 395 static int __dequeue_signal(struct sigpending *pending, sigset_t *mask,
396 siginfo_t *info) 396 siginfo_t *info)
397 { 397 {
... ...
410 collect_signal(sig, pending, info); 410 collect_signal(sig, pending, info);
... ...
414 } 414 }
Now we need to follow the "pending" pointer, since that is being passed on to Now we need to follow the ``pending`` pointer, since that is being passed on to
collect_signal() as "list". At this point, we've run out of lines from the ``collect_signal()`` as ``list``. At this point, we've run out of lines from the
"addr2line" output. Not to worry, we just paste the next addresses from the "addr2line" output. Not to worry, we just paste the next addresses from the
kmemcheck stack dump, i.e.: kmemcheck stack dump, i.e.::
[<ffffffff8104f04e>] dequeue_signal+0x8e/0x170 [<ffffffff8104f04e>] dequeue_signal+0x8e/0x170
[<ffffffff81050bd8>] get_signal_to_deliver+0x98/0x390 [<ffffffff81050bd8>] get_signal_to_deliver+0x98/0x390
...@@ -351,36 +329,36 @@ kmemcheck stack dump, i.e.: ...@@ -351,36 +329,36 @@ kmemcheck stack dump, i.e.:
Remember that since these addresses were found on the stack and not as the Remember that since these addresses were found on the stack and not as the
RIP value, they actually point to the _next_ instruction (they are return RIP value, they actually point to the _next_ instruction (they are return
addresses). This becomes obvious when we look at the code for line 446: addresses). This becomes obvious when we look at the code for line 446::
422 int dequeue_signal(struct task_struct *tsk, sigset_t *mask, siginfo_t *info) 422 int dequeue_signal(struct task_struct *tsk, sigset_t *mask, siginfo_t *info)
423 { 423 {
... ...
431 signr = __dequeue_signal(&tsk->signal->shared_pending, 431 signr = __dequeue_signal(&tsk->signal->shared_pending,
432 mask, info); 432 mask, info);
433 /* 433 /*
434 * itimer signal ? 434 * itimer signal ?
435 * 435 *
436 * itimers are process shared and we restart periodic 436 * itimers are process shared and we restart periodic
437 * itimers in the signal delivery path to prevent DoS 437 * itimers in the signal delivery path to prevent DoS
438 * attacks in the high resolution timer case. This is 438 * attacks in the high resolution timer case. This is
439 * compliant with the old way of self restarting 439 * compliant with the old way of self restarting
440 * itimers, as the SIGALRM is a legacy signal and only 440 * itimers, as the SIGALRM is a legacy signal and only
441 * queued once. Changing the restart behaviour to 441 * queued once. Changing the restart behaviour to
442 * restart the timer in the signal dequeue path is 442 * restart the timer in the signal dequeue path is
443 * reducing the timer noise on heavy loaded !highres 443 * reducing the timer noise on heavy loaded !highres
444 * systems too. 444 * systems too.
445 */ 445 */
446 if (unlikely(signr == SIGALRM)) { 446 if (unlikely(signr == SIGALRM)) {
... ...
489 } 489 }
So instead of looking at 446, we should be looking at 431, which is the line So instead of looking at 446, we should be looking at 431, which is the line
that executes just before 446. Here we see that what we are looking for is that executes just before 446. Here we see that what we are looking for is
&tsk->signal->shared_pending. ``&tsk->signal->shared_pending``.
Our next task is now to figure out which function that puts items on this Our next task is now to figure out which function that puts items on this
"shared_pending" list. A crude, but efficient tool, is git grep: ``shared_pending`` list. A crude, but efficient tool, is ``git grep``::
$ git grep -n 'shared_pending' kernel/ $ git grep -n 'shared_pending' kernel/
... ...
...@@ -390,109 +368,110 @@ Our next task is now to figure out which function that puts items on this ...@@ -390,109 +368,110 @@ Our next task is now to figure out which function that puts items on this
There were more results, but none of them were related to list operations, There were more results, but none of them were related to list operations,
and these were the only assignments. We inspect the line numbers more closely and these were the only assignments. We inspect the line numbers more closely
and find that this is indeed where items are being added to the list: and find that this is indeed where items are being added to the list::
816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t, 816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t,
817 int group) 817 int group)
818 { 818 {
... ...
828 pending = group ? &t->signal->shared_pending : &t->pending; 828 pending = group ? &t->signal->shared_pending : &t->pending;
... ...
851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && 851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN &&
852 (is_si_special(info) || 852 (is_si_special(info) ||
853 info->si_code >= 0))); 853 info->si_code >= 0)));
854 if (q) { 854 if (q) {
855 list_add_tail(&q->list, &pending->list); 855 list_add_tail(&q->list, &pending->list);
... ...
890 } 890 }
and: and::
1309 int send_sigqueue(struct sigqueue *q, struct task_struct *t, int group) 1309 int send_sigqueue(struct sigqueue *q, struct task_struct *t, int group)
1310 { 1310 {
.... ....
1339 pending = group ? &t->signal->shared_pending : &t->pending; 1339 pending = group ? &t->signal->shared_pending : &t->pending;
1340 list_add_tail(&q->list, &pending->list); 1340 list_add_tail(&q->list, &pending->list);
.... ....
1347 } 1347 }
In the first case, the list element we are looking for, "q", is being returned In the first case, the list element we are looking for, ``q``, is being
from the function __sigqueue_alloc(), which looks like an allocation function. returned from the function ``__sigqueue_alloc()``, which looks like an
Let's take a look at it: allocation function. Let's take a look at it::
187 static struct sigqueue *__sigqueue_alloc(struct task_struct *t, gfp_t flags, 187 static struct sigqueue *__sigqueue_alloc(struct task_struct *t, gfp_t flags,
188 int override_rlimit) 188 int override_rlimit)
189 { 189 {
190 struct sigqueue *q = NULL; 190 struct sigqueue *q = NULL;
191 struct user_struct *user; 191 struct user_struct *user;
192 192
193 /* 193 /*
194 * We won't get problems with the target's UID changing under us 194 * We won't get problems with the target's UID changing under us
195 * because changing it requires RCU be used, and if t != current, the 195 * because changing it requires RCU be used, and if t != current, the
196 * caller must be holding the RCU readlock (by way of a spinlock) and 196 * caller must be holding the RCU readlock (by way of a spinlock) and
197 * we use RCU protection here 197 * we use RCU protection here
198 */ 198 */
199 user = get_uid(__task_cred(t)->user); 199 user = get_uid(__task_cred(t)->user);
200 atomic_inc(&user->sigpending); 200 atomic_inc(&user->sigpending);
201 if (override_rlimit || 201 if (override_rlimit ||
202 atomic_read(&user->sigpending) <= 202 atomic_read(&user->sigpending) <=
203 t->signal->rlim[RLIMIT_SIGPENDING].rlim_cur) 203 t->signal->rlim[RLIMIT_SIGPENDING].rlim_cur)
204 q = kmem_cache_alloc(sigqueue_cachep, flags); 204 q = kmem_cache_alloc(sigqueue_cachep, flags);
205 if (unlikely(q == NULL)) { 205 if (unlikely(q == NULL)) {
206 atomic_dec(&user->sigpending); 206 atomic_dec(&user->sigpending);
207 free_uid(user); 207 free_uid(user);
208 } else { 208 } else {
209 INIT_LIST_HEAD(&q->list); 209 INIT_LIST_HEAD(&q->list);
210 q->flags = 0; 210 q->flags = 0;
211 q->user = user; 211 q->user = user;
212 } 212 }
213 213
214 return q; 214 return q;
215 } 215 }
We see that this function initializes q->list, q->flags, and q->user. It seems We see that this function initializes ``q->list``, ``q->flags``, and
that now is the time to look at the definition of "struct sigqueue", e.g.: ``q->user``. It seems that now is the time to look at the definition of
``struct sigqueue``, e.g.::
14 struct sigqueue {
15 struct list_head list; 14 struct sigqueue {
16 int flags; 15 struct list_head list;
17 siginfo_t info; 16 int flags;
18 struct user_struct *user; 17 siginfo_t info;
19 }; 18 struct user_struct *user;
19 };
And, you might remember, it was a memcpy() on &first->info that caused the
warning, so this makes perfect sense. It also seems reasonable to assume that And, you might remember, it was a ``memcpy()`` on ``&first->info`` that
it is the caller of __sigqueue_alloc() that has the responsibility of filling caused the warning, so this makes perfect sense. It also seems reasonable
out (initializing) this member. to assume that it is the caller of ``__sigqueue_alloc()`` that has the
responsibility of filling out (initializing) this member.
But just which fields of the struct were uninitialized? Let's look at But just which fields of the struct were uninitialized? Let's look at
kmemcheck's report again: kmemcheck's report again::
WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024)
80000000000000000000000000000000000000000088ffff0000000000000000 80000000000000000000000000000000000000000088ffff0000000000000000
i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u
^ ^
These first two lines are the memory dump of the memory object itself, and the These first two lines are the memory dump of the memory object itself, and
shadow bytemap, respectively. The memory object itself is in this case the shadow bytemap, respectively. The memory object itself is in this case
&first->info. Just beware that the start of this dump is NOT the start of the ``&first->info``. Just beware that the start of this dump is NOT the start
object itself! The position of the caret (^) corresponds with the address of of the object itself! The position of the caret (^) corresponds with the
the read (ffff88003e4a2024). address of the read (ffff88003e4a2024).
The shadow bytemap dump legend is as follows: The shadow bytemap dump legend is as follows:
i - initialized - i: initialized
u - uninitialized - u: uninitialized
a - unallocated (memory has been allocated by the slab layer, but has not - a: unallocated (memory has been allocated by the slab layer, but has not
yet been handed off to anybody) yet been handed off to anybody)
f - freed (memory has been allocated by the slab layer, but has been freed - f: freed (memory has been allocated by the slab layer, but has been freed
by the previous owner) by the previous owner)
In order to figure out where (relative to the start of the object) the In order to figure out where (relative to the start of the object) the
uninitialized memory was located, we have to look at the disassembly. For uninitialized memory was located, we have to look at the disassembly. For
that, we'll need the RIP address again: that, we'll need the RIP address again::
RIP: 0010:[<ffffffff8104ede8>] [<ffffffff8104ede8>] __dequeue_signal+0xc8/0x190 RIP: 0010:[<ffffffff8104ede8>] [<ffffffff8104ede8>] __dequeue_signal+0xc8/0x190
$ objdump -d --no-show-raw-insn vmlinux | grep -C 8 ffffffff8104ede8: $ objdump -d --no-show-raw-insn vmlinux | grep -C 8 ffffffff8104ede8:
ffffffff8104edc8: mov %r8,0x8(%r8) ffffffff8104edc8: mov %r8,0x8(%r8)
...@@ -513,36 +492,36 @@ RIP: 0010:[<ffffffff8104ede8>] [<ffffffff8104ede8>] __dequeue_signal+0xc8/0x190 ...@@ -513,36 +492,36 @@ RIP: 0010:[<ffffffff8104ede8>] [<ffffffff8104ede8>] __dequeue_signal+0xc8/0x190
ffffffff8104edf5: mov %r8,%rdi ffffffff8104edf5: mov %r8,%rdi
ffffffff8104edf8: callq ffffffff8104de60 <__sigqueue_free> ffffffff8104edf8: callq ffffffff8104de60 <__sigqueue_free>
As expected, it's the "rep movsl" instruction from the memcpy() that causes As expected, it's the "``rep movsl``" instruction from the ``memcpy()``
the warning. We know about REP MOVSL that it uses the register RCX to count that causes the warning. We know about ``REP MOVSL`` that it uses the register
the number of remaining iterations. By taking a look at the register dump ``RCX`` to count the number of remaining iterations. By taking a look at the
again (from the kmemcheck report), we can figure out how many bytes were left register dump again (from the kmemcheck report), we can figure out how many
to copy: bytes were left to copy::
RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009
By looking at the disassembly, we also see that %ecx is being loaded with the By looking at the disassembly, we also see that ``%ecx`` is being loaded
value $0xc just before (ffffffff8104edd8), so we are very lucky. Keep in mind with the value ``$0xc`` just before (ffffffff8104edd8), so we are very
that this is the number of iterations, not bytes. And since this is a "long" lucky. Keep in mind that this is the number of iterations, not bytes. And
operation, we need to multiply by 4 to get the number of bytes. So this means since this is a "long" operation, we need to multiply by 4 to get the
that the uninitialized value was encountered at 4 * (0xc - 0x9) = 12 bytes number of bytes. So this means that the uninitialized value was encountered
from the start of the object. at 4 * (0xc - 0x9) = 12 bytes from the start of the object.
We can now try to figure out which field of the "struct siginfo" that was not We can now try to figure out which field of the "``struct siginfo``" that
initialized. This is the beginning of the struct: was not initialized. This is the beginning of the struct::
40 typedef struct siginfo { 40 typedef struct siginfo {
41 int si_signo; 41 int si_signo;
42 int si_errno; 42 int si_errno;
43 int si_code; 43 int si_code;
44 44
45 union { 45 union {
.. ..
92 } _sifields; 92 } _sifields;
93 } siginfo_t; 93 } siginfo_t;
On 64-bit, the int is 4 bytes long, so it must the union member that has On 64-bit, the int is 4 bytes long, so it must the union member that has
not been initialized. We can verify this using gdb: not been initialized. We can verify this using gdb::
$ gdb vmlinux $ gdb vmlinux
... ...
...@@ -550,82 +529,83 @@ not been initialized. We can verify this using gdb: ...@@ -550,82 +529,83 @@ not been initialized. We can verify this using gdb:
$1 = (union {...} *) 0x10 $1 = (union {...} *) 0x10
Actually, it seems that the union member is located at offset 0x10 -- which Actually, it seems that the union member is located at offset 0x10 -- which
means that gcc has inserted 4 bytes of padding between the members si_code means that gcc has inserted 4 bytes of padding between the members ``si_code``
and _sifields. We can now get a fuller picture of the memory dump: and ``_sifields``. We can now get a fuller picture of the memory dump::
_----------------------------=> si_code _----------------------------=> si_code
/ _--------------------=> (padding) / _--------------------=> (padding)
| / _------------=> _sifields(._kill._pid) | / _------------=> _sifields(._kill._pid)
| | / _----=> _sifields(._kill._uid) | | / _----=> _sifields(._kill._uid)
| | | / | | | /
-------|-------|-------|-------| -------|-------|-------|-------|
80000000000000000000000000000000000000000088ffff0000000000000000 80000000000000000000000000000000000000000088ffff0000000000000000
i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u
This allows us to realize another important fact: si_code contains the value This allows us to realize another important fact: ``si_code`` contains the
0x80. Remember that x86 is little endian, so the first 4 bytes "80000000" are value 0x80. Remember that x86 is little endian, so the first 4 bytes
really the number 0x00000080. With a bit of research, we find that this is "80000000" are really the number 0x00000080. With a bit of research, we
actually the constant SI_KERNEL defined in include/asm-generic/siginfo.h: find that this is actually the constant ``SI_KERNEL`` defined in
``include/asm-generic/siginfo.h``::
144 #define SI_KERNEL 0x80 /* sent by the kernel from somewhere */
144 #define SI_KERNEL 0x80 /* sent by the kernel from somewhere */
This macro is used in exactly one place in the x86 kernel: In send_signal()
in kernel/signal.c: This macro is used in exactly one place in the x86 kernel: In ``send_signal()``
in ``kernel/signal.c``::
816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t,
817 int group) 816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t,
818 { 817 int group)
... 818 {
828 pending = group ? &t->signal->shared_pending : &t->pending; ...
... 828 pending = group ? &t->signal->shared_pending : &t->pending;
851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && ...
852 (is_si_special(info) || 851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN &&
853 info->si_code >= 0))); 852 (is_si_special(info) ||
854 if (q) { 853 info->si_code >= 0)));
855 list_add_tail(&q->list, &pending->list); 854 if (q) {
856 switch ((unsigned long) info) { 855 list_add_tail(&q->list, &pending->list);
... 856 switch ((unsigned long) info) {
865 case (unsigned long) SEND_SIG_PRIV: ...
866 q->info.si_signo = sig; 865 case (unsigned long) SEND_SIG_PRIV:
867 q->info.si_errno = 0; 866 q->info.si_signo = sig;
868 q->info.si_code = SI_KERNEL; 867 q->info.si_errno = 0;
869 q->info.si_pid = 0; 868 q->info.si_code = SI_KERNEL;
870 q->info.si_uid = 0; 869 q->info.si_pid = 0;
871 break; 870 q->info.si_uid = 0;
... 871 break;
890 } ...
890 }
Not only does this match with the .si_code member, it also matches the place
Not only does this match with the ``.si_code`` member, it also matches the place
we found earlier when looking for where siginfo_t objects are enqueued on the we found earlier when looking for where siginfo_t objects are enqueued on the
"shared_pending" list. ``shared_pending`` list.
So to sum up: It seems that it is the padding introduced by the compiler So to sum up: It seems that it is the padding introduced by the compiler
between two struct fields that is uninitialized, and this gets reported when between two struct fields that is uninitialized, and this gets reported when
we do a memcpy() on the struct. This means that we have identified a false we do a ``memcpy()`` on the struct. This means that we have identified a false
positive warning. positive warning.
Normally, kmemcheck will not report uninitialized accesses in memcpy() calls Normally, kmemcheck will not report uninitialized accesses in ``memcpy()`` calls
when both the source and destination addresses are tracked. (Instead, we copy when both the source and destination addresses are tracked. (Instead, we copy
the shadow bytemap as well). In this case, the destination address clearly the shadow bytemap as well). In this case, the destination address clearly
was not tracked. We can dig a little deeper into the stack trace from above: was not tracked. We can dig a little deeper into the stack trace from above::
arch/x86/kernel/signal.c:805 arch/x86/kernel/signal.c:805
arch/x86/kernel/signal.c:871 arch/x86/kernel/signal.c:871
arch/x86/kernel/entry_64.S:694 arch/x86/kernel/entry_64.S:694
And we clearly see that the destination siginfo object is located on the And we clearly see that the destination siginfo object is located on the
stack: stack::
782 static void do_signal(struct pt_regs *regs) 782 static void do_signal(struct pt_regs *regs)
783 { 783 {
784 struct k_sigaction ka; 784 struct k_sigaction ka;
785 siginfo_t info; 785 siginfo_t info;
... ...
804 signr = get_signal_to_deliver(&info, &ka, regs, NULL); 804 signr = get_signal_to_deliver(&info, &ka, regs, NULL);
... ...
854 } 854 }
And this &info is what eventually gets passed to copy_siginfo() as the And this ``&info`` is what eventually gets passed to ``copy_siginfo()`` as the
destination argument. destination argument.
Now, even though we didn't find an actual error here, the example is still a Now, even though we didn't find an actual error here, the example is still a
...@@ -633,31 +613,30 @@ good one, because it shows how one would go about to find out what the report ...@@ -633,31 +613,30 @@ good one, because it shows how one would go about to find out what the report
was all about. was all about.
3.4. Annotating false positives Annotating false positives
=============================== ~~~~~~~~~~~~~~~~~~~~~~~~~~
There are a few different ways to make annotations in the source code that There are a few different ways to make annotations in the source code that
will keep kmemcheck from checking and reporting certain allocations. Here will keep kmemcheck from checking and reporting certain allocations. Here
they are: they are:
o __GFP_NOTRACK_FALSE_POSITIVE - ``__GFP_NOTRACK_FALSE_POSITIVE``
This flag can be passed to ``kmalloc()`` or ``kmem_cache_alloc()``
(therefore also to other functions that end up calling one of
these) to indicate that the allocation should not be tracked
because it would lead to a false positive report. This is a "big
hammer" way of silencing kmemcheck; after all, even if the false
positive pertains to particular field in a struct, for example, we
will now lose the ability to find (real) errors in other parts of
the same struct.
This flag can be passed to kmalloc() or kmem_cache_alloc() (therefore Example::
also to other functions that end up calling one of these) to indicate
that the allocation should not be tracked because it would lead to
a false positive report. This is a "big hammer" way of silencing
kmemcheck; after all, even if the false positive pertains to
particular field in a struct, for example, we will now lose the
ability to find (real) errors in other parts of the same struct.
Example:
/* No warnings will ever trigger on accessing any part of x */ /* No warnings will ever trigger on accessing any part of x */
x = kmalloc(sizeof *x, GFP_KERNEL | __GFP_NOTRACK_FALSE_POSITIVE); x = kmalloc(sizeof *x, GFP_KERNEL | __GFP_NOTRACK_FALSE_POSITIVE);
o kmemcheck_bitfield_begin(name)/kmemcheck_bitfield_end(name) and - ``kmemcheck_bitfield_begin(name)``/``kmemcheck_bitfield_end(name)`` and
kmemcheck_annotate_bitfield(ptr, name) ``kmemcheck_annotate_bitfield(ptr, name)``
The first two of these three macros can be used inside struct The first two of these three macros can be used inside struct
definitions to signal, respectively, the beginning and end of a definitions to signal, respectively, the beginning and end of a
bitfield. Additionally, this will assign the bitfield a name, which bitfield. Additionally, this will assign the bitfield a name, which
...@@ -667,7 +646,7 @@ they are: ...@@ -667,7 +646,7 @@ they are:
kmemcheck_annotate_bitfield() at the point of allocation, to indicate kmemcheck_annotate_bitfield() at the point of allocation, to indicate
which parts of the allocation is part of a bitfield. which parts of the allocation is part of a bitfield.
Example: Example::
struct foo { struct foo {
int x; int x;
...@@ -685,13 +664,13 @@ they are: ...@@ -685,13 +664,13 @@ they are:
/* No warnings will trigger on accessing the bitfield of x */ /* No warnings will trigger on accessing the bitfield of x */
kmemcheck_annotate_bitfield(x, flags); kmemcheck_annotate_bitfield(x, flags);
Note that kmemcheck_annotate_bitfield() can be used even before the Note that ``kmemcheck_annotate_bitfield()`` can be used even before the
return value of kmalloc() is checked -- in other words, passing NULL return value of ``kmalloc()`` is checked -- in other words, passing NULL
as the first argument is legal (and will do nothing). as the first argument is legal (and will do nothing).
4. Reporting errors Reporting errors
=================== ----------------
As we have seen, kmemcheck will produce false positive reports. Therefore, it As we have seen, kmemcheck will produce false positive reports. Therefore, it
is not very wise to blindly post kmemcheck warnings to mailing lists and is not very wise to blindly post kmemcheck warnings to mailing lists and
...@@ -710,8 +689,8 @@ available) are of course a great help too. ...@@ -710,8 +689,8 @@ available) are of course a great help too.
Happy hacking! Happy hacking!
5. Technical description Technical description
======================== ---------------------
kmemcheck works by marking memory pages non-present. This means that whenever kmemcheck works by marking memory pages non-present. This means that whenever
somebody attempts to access the page, a page fault is generated. The page somebody attempts to access the page, a page fault is generated. The page
......
Documentation/kmemleak.txt → Documentation/dev-tools/kmemleak.rst
View file @ 5512128f
Kernel Memory Leak Detector Kernel Memory Leak Detector
=========================== ===========================
Introduction
------------
Kmemleak provides a way of detecting possible kernel memory leaks in a Kmemleak provides a way of detecting possible kernel memory leaks in a
way similar to a tracing garbage collector way similar to a tracing garbage collector
(https://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29#Tracing_garbage_collectors), (https://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29#Tracing_garbage_collectors),
with the difference that the orphan objects are not freed but only with the difference that the orphan objects are not freed but only
reported via /sys/kernel/debug/kmemleak. A similar method is used by the reported via /sys/kernel/debug/kmemleak. A similar method is used by the
Valgrind tool (memcheck --leak-check) to detect the memory leaks in Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in
user-space applications. user-space applications.
Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390, metag and tile. Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390, metag and tile.
...@@ -19,20 +16,20 @@ Usage ...@@ -19,20 +16,20 @@ Usage
CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel
thread scans the memory every 10 minutes (by default) and prints the thread scans the memory every 10 minutes (by default) and prints the
number of new unreferenced objects found. To display the details of all number of new unreferenced objects found. To display the details of all
the possible memory leaks: the possible memory leaks::
# mount -t debugfs nodev /sys/kernel/debug/ # mount -t debugfs nodev /sys/kernel/debug/
# cat /sys/kernel/debug/kmemleak # cat /sys/kernel/debug/kmemleak
To trigger an intermediate memory scan: To trigger an intermediate memory scan::
# echo scan > /sys/kernel/debug/kmemleak # echo scan > /sys/kernel/debug/kmemleak
To clear the list of all current possible memory leaks: To clear the list of all current possible memory leaks::
# echo clear > /sys/kernel/debug/kmemleak # echo clear > /sys/kernel/debug/kmemleak
New leaks will then come up upon reading /sys/kernel/debug/kmemleak New leaks will then come up upon reading ``/sys/kernel/debug/kmemleak``
again. again.
Note that the orphan objects are listed in the order they were allocated Note that the orphan objects are listed in the order they were allocated
...@@ -40,22 +37,31 @@ and one object at the beginning of the list may cause other subsequent ...@@ -40,22 +37,31 @@ and one object at the beginning of the list may cause other subsequent
objects to be reported as orphan. objects to be reported as orphan.
Memory scanning parameters can be modified at run-time by writing to the Memory scanning parameters can be modified at run-time by writing to the
/sys/kernel/debug/kmemleak file. The following parameters are supported: ``/sys/kernel/debug/kmemleak`` file. The following parameters are supported:
off - disable kmemleak (irreversible) - off
stack=on - enable the task stacks scanning (default) disable kmemleak (irreversible)
stack=off - disable the tasks stacks scanning - stack=on
scan=on - start the automatic memory scanning thread (default) enable the task stacks scanning (default)
scan=off - stop the automatic memory scanning thread - stack=off
scan=<secs> - set the automatic memory scanning period in seconds disable the tasks stacks scanning
- scan=on
start the automatic memory scanning thread (default)
- scan=off
stop the automatic memory scanning thread
- scan=<secs>
set the automatic memory scanning period in seconds
(default 600, 0 to stop the automatic scanning) (default 600, 0 to stop the automatic scanning)
scan - trigger a memory scan - scan
clear - clear list of current memory leak suspects, done by trigger a memory scan
- clear
clear list of current memory leak suspects, done by
marking all current reported unreferenced objects grey, marking all current reported unreferenced objects grey,
or free all kmemleak objects if kmemleak has been disabled. or free all kmemleak objects if kmemleak has been disabled.
dump=<addr> - dump information about the object found at <addr> - dump=<addr>
dump information about the object found at <addr>
Kmemleak can also be disabled at boot-time by passing "kmemleak=off" on Kmemleak can also be disabled at boot-time by passing ``kmemleak=off`` on
the kernel command line. the kernel command line.
Memory may be allocated or freed before kmemleak is initialised and Memory may be allocated or freed before kmemleak is initialised and
...@@ -63,13 +69,14 @@ these actions are stored in an early log buffer. The size of this buffer ...@@ -63,13 +69,14 @@ these actions are stored in an early log buffer. The size of this buffer
is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option. is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option.
If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is
disabled by default. Passing "kmemleak=on" on the kernel command disabled by default. Passing ``kmemleak=on`` on the kernel command
line enables the function. line enables the function.
Basic Algorithm Basic Algorithm
--------------- ---------------
The memory allocations via kmalloc, vmalloc, kmem_cache_alloc and The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
:c:func:`kmem_cache_alloc` and
friends are traced and the pointers, together with additional friends are traced and the pointers, together with additional
information like size and stack trace, are stored in a rbtree. information like size and stack trace, are stored in a rbtree.
The corresponding freeing function calls are tracked and the pointers The corresponding freeing function calls are tracked and the pointers
...@@ -113,13 +120,13 @@ when doing development. To work around these situations you can use the ...@@ -113,13 +120,13 @@ when doing development. To work around these situations you can use the
you can find new unreferenced objects; this should help with testing you can find new unreferenced objects; this should help with testing
specific sections of code. specific sections of code.
To test a critical section on demand with a clean kmemleak do: To test a critical section on demand with a clean kmemleak do::
# echo clear > /sys/kernel/debug/kmemleak # echo clear > /sys/kernel/debug/kmemleak
... test your kernel or modules ... ... test your kernel or modules ...
# echo scan > /sys/kernel/debug/kmemleak # echo scan > /sys/kernel/debug/kmemleak
Then as usual to get your report with: Then as usual to get your report with::
# cat /sys/kernel/debug/kmemleak # cat /sys/kernel/debug/kmemleak
...@@ -131,7 +138,7 @@ disabled by the user or due to an fatal error, internal kmemleak objects ...@@ -131,7 +138,7 @@ disabled by the user or due to an fatal error, internal kmemleak objects
won't be freed when kmemleak is disabled, and those objects may occupy won't be freed when kmemleak is disabled, and those objects may occupy
a large part of physical memory. a large part of physical memory.
In this situation, you may reclaim memory with: In this situation, you may reclaim memory with::
# echo clear > /sys/kernel/debug/kmemleak # echo clear > /sys/kernel/debug/kmemleak
...@@ -140,20 +147,20 @@ Kmemleak API ...@@ -140,20 +147,20 @@ Kmemleak API
See the include/linux/kmemleak.h header for the functions prototype. See the include/linux/kmemleak.h header for the functions prototype.
kmemleak_init - initialize kmemleak - ``kmemleak_init`` - initialize kmemleak
kmemleak_alloc - notify of a memory block allocation - ``kmemleak_alloc`` - notify of a memory block allocation
kmemleak_alloc_percpu - notify of a percpu memory block allocation - ``kmemleak_alloc_percpu`` - notify of a percpu memory block allocation
kmemleak_free - notify of a memory block freeing - ``kmemleak_free`` - notify of a memory block freeing
kmemleak_free_part - notify of a partial memory block freeing - ``kmemleak_free_part`` - notify of a partial memory block freeing
kmemleak_free_percpu - notify of a percpu memory block freeing - ``kmemleak_free_percpu`` - notify of a percpu memory block freeing
kmemleak_update_trace - update object allocation stack trace - ``kmemleak_update_trace`` - update object allocation stack trace
kmemleak_not_leak - mark an object as not a leak - ``kmemleak_not_leak`` - mark an object as not a leak
kmemleak_ignore - do not scan or report an object as leak - ``kmemleak_ignore`` - do not scan or report an object as leak
kmemleak_scan_area - add scan areas inside a memory block - ``kmemleak_scan_area`` - add scan areas inside a memory block
kmemleak_no_scan - do not scan a memory block - ``kmemleak_no_scan`` - do not scan a memory block
kmemleak_erase - erase an old value in a pointer variable - ``kmemleak_erase`` - erase an old value in a pointer variable
kmemleak_alloc_recursive - as kmemleak_alloc but checks the recursiveness - ``kmemleak_alloc_recursive`` - as kmemleak_alloc but checks the recursiveness
kmemleak_free_recursive - as kmemleak_free but checks the recursiveness - ``kmemleak_free_recursive`` - as kmemleak_free but checks the recursiveness
Dealing with false positives/negatives Dealing with false positives/negatives
-------------------------------------- --------------------------------------
......
Documentation/sparse.txt → Documentation/dev-tools/sparse.rst
View file @ 5512128f
Copyright 2004 Linus Torvalds .. Copyright 2004 Linus Torvalds
Copyright 2004 Pavel Machek <pavel@ucw.cz> .. Copyright 2004 Pavel Machek <pavel@ucw.cz>
Copyright 2006 Bob Copeland <me@bobcopeland.com> .. Copyright 2006 Bob Copeland <me@bobcopeland.com>
Sparse
======
Sparse is a semantic checker for C programs; it can be used to find a
number of potential problems with kernel code. See
https://lwn.net/Articles/689907/ for an overview of sparse; this document
contains some kernel-specific sparse information.
Using sparse for typechecking Using sparse for typechecking
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------
"__bitwise" is a type attribute, so you have to do something like this: "__bitwise" is a type attribute, so you have to do something like this::
typedef int __bitwise pm_request_t; typedef int __bitwise pm_request_t;
...@@ -20,13 +29,13 @@ but in this case we really _do_ want to force the conversion). And because ...@@ -20,13 +29,13 @@ but in this case we really _do_ want to force the conversion). And because
the enum values are all the same type, now "enum pm_request" will be that the enum values are all the same type, now "enum pm_request" will be that
type too. type too.
And with gcc, all the __bitwise/__force stuff goes away, and it all ends And with gcc, all the "__bitwise"/"__force stuff" goes away, and it all
up looking just like integers to gcc. ends up looking just like integers to gcc.
Quite frankly, you don't need the enum there. The above all really just Quite frankly, you don't need the enum there. The above all really just
boils down to one special "int __bitwise" type. boils down to one special "int __bitwise" type.
So the simpler way is to just do So the simpler way is to just do::
typedef int __bitwise pm_request_t; typedef int __bitwise pm_request_t;
...@@ -50,7 +59,7 @@ __bitwise - noisy stuff; in particular, __le*/__be* are that. We really ...@@ -50,7 +59,7 @@ __bitwise - noisy stuff; in particular, __le*/__be* are that. We really
don't want to drown in noise unless we'd explicitly asked for it. don't want to drown in noise unless we'd explicitly asked for it.
Using sparse for lock checking Using sparse for lock checking
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------
The following macros are undefined for gcc and defined during a sparse The following macros are undefined for gcc and defined during a sparse
run to use the "context" tracking feature of sparse, applied to run to use the "context" tracking feature of sparse, applied to
...@@ -69,22 +78,22 @@ annotation is needed. The tree annotations above are for cases where ...@@ -69,22 +78,22 @@ annotation is needed. The tree annotations above are for cases where
sparse would otherwise report a context imbalance. sparse would otherwise report a context imbalance.
Getting sparse Getting sparse
~~~~~~~~~~~~~~ --------------
You can get latest released versions from the Sparse homepage at You can get latest released versions from the Sparse homepage at
https://sparse.wiki.kernel.org/index.php/Main_Page https://sparse.wiki.kernel.org/index.php/Main_Page
Alternatively, you can get snapshots of the latest development version Alternatively, you can get snapshots of the latest development version
of sparse using git to clone.. of sparse using git to clone::
git://git.kernel.org/pub/scm/devel/sparse/sparse.git git://git.kernel.org/pub/scm/devel/sparse/sparse.git
DaveJ has hourly generated tarballs of the git tree available at.. DaveJ has hourly generated tarballs of the git tree available at::
http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ http://www.codemonkey.org.uk/projects/git-snapshots/sparse/
Once you have it, just do Once you have it, just do::
make make
make install make install
...@@ -92,7 +101,7 @@ Once you have it, just do ...@@ -92,7 +101,7 @@ Once you have it, just do
as a regular user, and it will install sparse in your ~/bin directory. as a regular user, and it will install sparse in your ~/bin directory.
Using sparse Using sparse
~~~~~~~~~~~~ ------------
Do a kernel make with "make C=1" to run sparse on all the C files that get Do a kernel make with "make C=1" to run sparse on all the C files that get
recompiled, or use "make C=2" to run sparse on the files whether they need to recompiled, or use "make C=2" to run sparse on the files whether they need to
...@@ -101,7 +110,7 @@ have already built it. ...@@ -101,7 +110,7 @@ have already built it.
The optional make variable CF can be used to pass arguments to sparse. The The optional make variable CF can be used to pass arguments to sparse. The
build system passes -Wbitwise to sparse automatically. To perform endianness build system passes -Wbitwise to sparse automatically. To perform endianness
checks, you may define __CHECK_ENDIAN__: checks, you may define __CHECK_ENDIAN__::
make C=2 CF="-D__CHECK_ENDIAN__" make C=2 CF="-D__CHECK_ENDIAN__"
......
Documentation/dev-tools/tools.rst 0 → 100644
View file @ 5512128f
================================
Development tools for the kernel
================================
This document is a collection of documents about development tools that can
be used to work on the kernel. For now, the documents have been pulled
together without any significant effot to integrate them into a coherent
whole; patches welcome!
.. class:: toc-title
Table of contents
.. toctree::
:maxdepth: 2
coccinelle
sparse
kcov
gcov
kasan
ubsan
kmemleak
kmemcheck
gdb-kernel-debugging
Documentation/ubsan.txt → Documentation/dev-tools/ubsan.rst
View file @ 5512128f
Undefined Behavior Sanitizer - UBSAN The Undefined Behavior Sanitizer - UBSAN
========================================
Overview
--------
UBSAN is a runtime undefined behaviour checker. UBSAN is a runtime undefined behaviour checker.
...@@ -10,11 +8,13 @@ Compiler inserts code that perform certain kinds of checks before operations ...@@ -10,11 +8,13 @@ Compiler inserts code that perform certain kinds of checks before operations
that may cause UB. If check fails (i.e. UB detected) __ubsan_handle_* that may cause UB. If check fails (i.e. UB detected) __ubsan_handle_*
function called to print error message. function called to print error message.
GCC has that feature since 4.9.x [1] (see -fsanitize=undefined option and GCC has that feature since 4.9.x [1_] (see ``-fsanitize=undefined`` option and
its suboptions). GCC 5.x has more checkers implemented [2]. its suboptions). GCC 5.x has more checkers implemented [2_].
Report example Report example
--------------- --------------
::
================================================================================ ================================================================================
UBSAN: Undefined behaviour in ../include/linux/bitops.h:110:33 UBSAN: Undefined behaviour in ../include/linux/bitops.h:110:33
...@@ -47,28 +47,32 @@ Report example ...@@ -47,28 +47,32 @@ Report example
Usage Usage
----- -----
To enable UBSAN configure kernel with: To enable UBSAN configure kernel with::
CONFIG_UBSAN=y CONFIG_UBSAN=y
and to check the entire kernel: and to check the entire kernel::
CONFIG_UBSAN_SANITIZE_ALL=y CONFIG_UBSAN_SANITIZE_ALL=y
To enable instrumentation for specific files or directories, add a line To enable instrumentation for specific files or directories, add a line
similar to the following to the respective kernel Makefile: similar to the following to the respective kernel Makefile:
For a single file (e.g. main.o): - For a single file (e.g. main.o)::
UBSAN_SANITIZE_main.o := y UBSAN_SANITIZE_main.o := y
For all files in one directory: - For all files in one directory::
UBSAN_SANITIZE := y UBSAN_SANITIZE := y
To exclude files from being instrumented even if To exclude files from being instrumented even if
CONFIG_UBSAN_SANITIZE_ALL=y, use: ``CONFIG_UBSAN_SANITIZE_ALL=y``, use::
UBSAN_SANITIZE_main.o := n UBSAN_SANITIZE_main.o := n
and:
and::
UBSAN_SANITIZE := n UBSAN_SANITIZE := n
Detection of unaligned accesses controlled through the separate option - Detection of unaligned accesses controlled through the separate option -
...@@ -80,5 +84,5 @@ reports. ...@@ -80,5 +84,5 @@ reports.
References References
---------- ----------
[1] - https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html .. _1: https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html
[2] - https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html .. _2: https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html
Documentation/index.rst
View file @ 5512128f
...@@ -12,6 +12,7 @@ Contents: ...@@ -12,6 +12,7 @@ Contents:
:maxdepth: 2 :maxdepth: 2
kernel-documentation kernel-documentation
dev-tools/tools
media/index media/index
gpu/index gpu/index
......
MAINTAINERS
View file @ 5512128f
...@@ -3124,7 +3124,7 @@ L: cocci@systeme.lip6.fr (moderated for non-subscribers) ...@@ -3124,7 +3124,7 @@ L: cocci@systeme.lip6.fr (moderated for non-subscribers)
T: git git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild.git misc T: git git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild.git misc
W: http://coccinelle.lip6.fr/ W: http://coccinelle.lip6.fr/
S: Supported S: Supported
F: Documentation/coccinelle.txt F: Documentation/dev-tools/coccinelle.rst
F: scripts/coccinelle/ F: scripts/coccinelle/
F: scripts/coccicheck F: scripts/coccicheck
...@@ -5118,7 +5118,7 @@ GCOV BASED KERNEL PROFILING ...@@ -5118,7 +5118,7 @@ GCOV BASED KERNEL PROFILING
M: Peter Oberparleiter <oberpar@linux.vnet.ibm.com> M: Peter Oberparleiter <oberpar@linux.vnet.ibm.com>
S: Maintained S: Maintained
F: kernel/gcov/ F: kernel/gcov/
F: Documentation/gcov.txt F: Documentation/dev-tools/gcov.rst
GDT SCSI DISK ARRAY CONTROLLER DRIVER GDT SCSI DISK ARRAY CONTROLLER DRIVER
M: Achim Leubner <achim_leubner@adaptec.com> M: Achim Leubner <achim_leubner@adaptec.com>
...@@ -6587,7 +6587,7 @@ L: kasan-dev@googlegroups.com ...@@ -6587,7 +6587,7 @@ L: kasan-dev@googlegroups.com
S: Maintained S: Maintained
F: arch/*/include/asm/kasan.h F: arch/*/include/asm/kasan.h
F: arch/*/mm/kasan_init* F: arch/*/mm/kasan_init*
F: Documentation/kasan.txt F: Documentation/dev-tools/kasan.rst
F: include/linux/kasan*.h F: include/linux/kasan*.h
F: lib/test_kasan.c F: lib/test_kasan.c
F: mm/kasan/ F: mm/kasan/
...@@ -6803,7 +6803,7 @@ KMEMCHECK ...@@ -6803,7 +6803,7 @@ KMEMCHECK
M: Vegard Nossum <vegardno@ifi.uio.no> M: Vegard Nossum <vegardno@ifi.uio.no>
M: Pekka Enberg <penberg@kernel.org> M: Pekka Enberg <penberg@kernel.org>
S: Maintained S: Maintained
F: Documentation/kmemcheck.txt F: Documentation/dev-tools/kmemcheck.rst
F: arch/x86/include/asm/kmemcheck.h F: arch/x86/include/asm/kmemcheck.h
F: arch/x86/mm/kmemcheck/ F: arch/x86/mm/kmemcheck/
F: include/linux/kmemcheck.h F: include/linux/kmemcheck.h
...@@ -6812,7 +6812,7 @@ F: mm/kmemcheck.c ...@@ -6812,7 +6812,7 @@ F: mm/kmemcheck.c
KMEMLEAK KMEMLEAK
M: Catalin Marinas <catalin.marinas@arm.com> M: Catalin Marinas <catalin.marinas@arm.com>
S: Maintained S: Maintained
F: Documentation/kmemleak.txt F: Documentation/dev-tools/kmemleak.rst
F: include/linux/kmemleak.h F: include/linux/kmemleak.h
F: mm/kmemleak.c F: mm/kmemleak.c
F: mm/kmemleak-test.c F: mm/kmemleak-test.c
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7