€•xp      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ./translations/zh_CN/dev-tools/testing-overview”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ./translations/zh_TW/dev-tools/testing-overview”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ./translations/it_IT/dev-tools/testing-overview”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ./translations/ja_JP/dev-tools/testing-overview”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ./translations/ko_KR/dev-tools/testing-overview”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ./translations/sp_SP/dev-tools/testing-overview”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒH/var/lib/git/docbuild/linux/Documentation/dev-tools/testing-overview.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒKernel Testing Guide”h]”hŒKernel Testing Guide”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hŒÔThere are a number of different tools for testing the Linux kernel, so knowing
when to use each of them can be a challenge. This document provides a rough
overview of their differences, and how they fit together.”h]”hŒÔThere are a number of different tools for testing the Linux kernel, so knowing
when to use each of them can be a challenge. This document provides a rough
overview of their differences, and how they fit together.”…””}”(hhËhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhµ)”}”(hhh]”(hº)”}”(hŒWriting and Running Tests”h]”hŒWriting and Running Tests”…””}”(hhÜhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhÙhžhhŸh³h KubhÊ)”}”(hŒçThe bulk of kernel tests are written using either the kselftest or KUnit
frameworks. These both provide infrastructure to help make running tests and
groups of tests easier, as well as providing helpers to aid in writing new
tests.”h]”hŒçThe bulk of kernel tests are written using either the kselftest or KUnit
frameworks. These both provide infrastructure to help make running tests and
groups of tests easier, as well as providing helpers to aid in writing new
tests.”…””}”(hhêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhhÙhžhubhÊ)”}”(hŒ•If you're looking to verify the behaviour of the Kernel â€” particularly specific
parts of the kernel â€” then you'll want to use KUnit or kselftest.”h]”hŒ™If youâ€™re looking to verify the behaviour of the Kernel â€” particularly specific
parts of the kernel â€” then youâ€™ll want to use KUnit or kselftest.”…””}”(hhøhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhhÙhžhubhµ)”}”(hhh]”(hº)”}”(hŒ*The Difference Between KUnit and kselftest”h]”hŒ*The Difference Between KUnit and kselftest”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h KubhÊ)”}”(hŒäKUnit (Documentation/dev-tools/kunit/index.rst) is an entirely in-kernel system
for "white box" testing: because test code is part of the kernel, it can access
internal structures and functions which aren't exposed to userspace.”h]”hŒêKUnit (Documentation/dev-tools/kunit/index.rst) is an entirely in-kernel system
for â€œwhite boxâ€ testing: because test code is part of the kernel, it can access
internal structures and functions which arenâ€™t exposed to userspace.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj  hžhubhÊ)”}”(hŒ°KUnit tests therefore are best written against small, self-contained parts
of the kernel, which can be tested in isolation. This aligns well with the
concept of 'unit' testing.”h]”hŒ´KUnit tests therefore are best written against small, self-contained parts
of the kernel, which can be tested in isolation. This aligns well with the
concept of â€˜unitâ€™ testing.”…””}”(hj%  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K hj  hžhubhÊ)”}”(hŒ´For example, a KUnit test might test an individual kernel function (or even a
single codepath through a function, such as an error handling case), rather
than a feature as a whole.”h]”hŒ´For example, a KUnit test might test an individual kernel function (or even a
single codepath through a function, such as an error handling case), rather
than a feature as a whole.”…””}”(hj3  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K$hj  hžhubhÊ)”}”(hŒ~This also makes KUnit tests very fast to build and run, allowing them to be
run frequently as part of the development process.”h]”hŒ~This also makes KUnit tests very fast to build and run, allowing them to be
run frequently as part of the development process.”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K(hj  hžhubhÊ)”}”(hŒlThere is a KUnit test style guide which may give further pointers in
Documentation/dev-tools/kunit/style.rst”h]”hŒlThere is a KUnit test style guide which may give further pointers in
Documentation/dev-tools/kunit/style.rst”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K+hj  hžhubhÊ)”}”(hŒžkselftest (Documentation/dev-tools/kselftest.rst), on the other hand, is
largely implemented in userspace, and tests are normal userspace scripts or
programs.”h]”hŒžkselftest (Documentation/dev-tools/kselftest.rst), on the other hand, is
largely implemented in userspace, and tests are normal userspace scripts or
programs.”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K/hj  hžhubhÊ)”}”(hX[  This makes it easier to write more complicated tests, or tests which need to
manipulate the overall system state more (e.g., spawning processes, etc.).
However, it's not possible to call kernel functions directly from kselftest.
This means that only kernel functionality which is exposed to userspace somehow
(e.g. by a syscall, device, filesystem, etc.) can be tested with kselftest.  To
work around this, some tests include a companion kernel module which exposes
more information or functionality. If a test runs mostly or entirely within the
kernel, however,  KUnit may be the more appropriate tool.”h]”hX]  This makes it easier to write more complicated tests, or tests which need to
manipulate the overall system state more (e.g., spawning processes, etc.).
However, itâ€™s not possible to call kernel functions directly from kselftest.
This means that only kernel functionality which is exposed to userspace somehow
(e.g. by a syscall, device, filesystem, etc.) can be tested with kselftest.  To
work around this, some tests include a companion kernel module which exposes
more information or functionality. If a test runs mostly or entirely within the
kernel, however,  KUnit may be the more appropriate tool.”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K3hj  hžhubhÊ)”}”(hŒÛkselftest is therefore suited well to tests of whole features, as these will
expose an interface to userspace, which can be tested, but not implementation
details. This aligns well with 'system' or 'end-to-end' testing.”h]”hŒãkselftest is therefore suited well to tests of whole features, as these will
expose an interface to userspace, which can be tested, but not implementation
details. This aligns well with â€˜systemâ€™ or â€˜end-to-endâ€™ testing.”…””}”(hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K<hj  hžhubhÊ)”}”(hŒKFor example, all new system calls should be accompanied by kselftest tests.”h]”hŒKFor example, all new system calls should be accompanied by kselftest tests.”…””}”(hj‡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K@hj  hžhubeh}”(h]”Œ*the-difference-between-kunit-and-kselftest”ah ]”h"]”Œ*the difference between kunit and kselftest”ah$]”h&]”uh1h´hhÙhžhhŸh³h Kubeh}”(h]”Œwriting-and-running-tests”ah ]”h"]”Œwriting and running tests”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒCode Coverage Tools”h]”hŒCode Coverage Tools”…””}”(hj¨  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj¥  hžhhŸh³h KCubhÊ)”}”(hX7  The Linux Kernel supports two different code coverage measurement tools. These
can be used to verify that a test is executing particular functions or lines
of code. This is useful for determining how much of the kernel is being tested,
and for finding corner-cases which are not covered by the appropriate test.”h]”hX7  The Linux Kernel supports two different code coverage measurement tools. These
can be used to verify that a test is executing particular functions or lines
of code. This is useful for determining how much of the kernel is being tested,
and for finding corner-cases which are not covered by the appropriate test.”…””}”(hj¶  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KEhj¥  hžhubhÊ)”}”(hX  Documentation/dev-tools/gcov.rst is GCC's coverage testing tool, which can be
used with the kernel to get global or per-module coverage. Unlike KCOV, it
does not record per-task coverage. Coverage data can be read from debugfs,
and interpreted using the usual gcov tooling.”h]”hX  Documentation/dev-tools/gcov.rst is GCCâ€™s coverage testing tool, which can be
used with the kernel to get global or per-module coverage. Unlike KCOV, it
does not record per-task coverage. Coverage data can be read from debugfs,
and interpreted using the usual gcov tooling.”…””}”(hjÄ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KJhj¥  hžhubhÊ)”}”(hX  Documentation/dev-tools/kcov.rst is a feature which can be built in to the
kernel to allow capturing coverage on a per-task level. It's therefore useful
for fuzzing and other situations where information about code executed during,
for example, a single syscall is useful.”h]”hX  Documentation/dev-tools/kcov.rst is a feature which can be built in to the
kernel to allow capturing coverage on a per-task level. Itâ€™s therefore useful
for fuzzing and other situations where information about code executed during,
for example, a single syscall is useful.”…””}”(hjÒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KOhj¥  hžhubeh}”(h]”Œcode-coverage-tools”ah ]”h"]”Œcode coverage tools”ah$]”h&]”uh1h´hh¶hžhhŸh³h KCubhµ)”}”(hhh]”(hº)”}”(hŒDynamic Analysis Tools”h]”hŒDynamic Analysis Tools”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjè  hžhhŸh³h KVubhÊ)”}”(hXA  The kernel also supports a number of dynamic analysis tools, which attempt to
detect classes of issues when they occur in a running kernel. These typically
each look for a different class of bugs, such as invalid memory accesses,
concurrency issues such as data races, or other undefined behaviour like
integer overflows.”h]”hXA  The kernel also supports a number of dynamic analysis tools, which attempt to
detect classes of issues when they occur in a running kernel. These typically
each look for a different class of bugs, such as invalid memory accesses,
concurrency issues such as data races, or other undefined behaviour like
integer overflows.”…””}”(hjù  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KXhjè  hžhubhÊ)”}”(hŒ%Some of these tools are listed below:”h]”hŒ%Some of these tools are listed below:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K^hjè  hžhubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒPkmemleak detects possible memory leaks. See
Documentation/dev-tools/kmemleak.rst”h]”hÊ)”}”(hŒPkmemleak detects possible memory leaks. See
Documentation/dev-tools/kmemleak.rst”h]”hŒPkmemleak detects possible memory leaks. See
Documentation/dev-tools/kmemleak.rst”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K`hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  hžhhŸh³h Nubj  )”}”(hŒ|KASAN detects invalid memory accesses such as out-of-bounds and
use-after-free errors. See Documentation/dev-tools/kasan.rst”h]”hÊ)”}”(hŒ|KASAN detects invalid memory accesses such as out-of-bounds and
use-after-free errors. See Documentation/dev-tools/kasan.rst”h]”hŒ|KASAN detects invalid memory accesses such as out-of-bounds and
use-after-free errors. See Documentation/dev-tools/kasan.rst”…””}”(hj8  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kbhj4  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  hžhhŸh³h Nubj  )”}”(hŒzUBSAN detects behaviour that is undefined by the C standard, like integer
overflows. See Documentation/dev-tools/ubsan.rst”h]”hÊ)”}”(hŒzUBSAN detects behaviour that is undefined by the C standard, like integer
overflows. See Documentation/dev-tools/ubsan.rst”h]”hŒzUBSAN detects behaviour that is undefined by the C standard, like integer
overflows. See Documentation/dev-tools/ubsan.rst”…””}”(hjP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KdhjL  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  hžhhŸh³h Nubj  )”}”(hŒ?KCSAN detects data races. See Documentation/dev-tools/kcsan.rst”h]”hÊ)”}”(hjf  h]”hŒ?KCSAN detects data races. See Documentation/dev-tools/kcsan.rst”…””}”(hjh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kfhjd  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  hžhhŸh³h Nubj  )”}”(hŒ™KFENCE is a low-overhead detector of memory issues, which is much faster than
KASAN and can be used in production. See Documentation/dev-tools/kfence.rst”h]”hÊ)”}”(hŒ™KFENCE is a low-overhead detector of memory issues, which is much faster than
KASAN and can be used in production. See Documentation/dev-tools/kfence.rst”h]”hŒ™KFENCE is a low-overhead detector of memory issues, which is much faster than
KASAN and can be used in production. See Documentation/dev-tools/kfence.rst”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kghj{  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  hžhhŸh³h Nubj  )”}”(hŒXlockdep is a locking correctness validator. See
Documentation/locking/lockdep-design.rst”h]”hÊ)”}”(hŒXlockdep is a locking correctness validator. See
Documentation/locking/lockdep-design.rst”h]”hŒXlockdep is a locking correctness validator. See
Documentation/locking/lockdep-design.rst”…””}”(hj—  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kihj“  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  hžhhŸh³h Nubj  )”}”(hŒŠRuntime Verification (RV) supports checking specific behaviours for a given
subsystem. See Documentation/trace/rv/runtime-verification.rst”h]”hÊ)”}”(hŒŠRuntime Verification (RV) supports checking specific behaviours for a given
subsystem. See Documentation/trace/rv/runtime-verification.rst”h]”hŒŠRuntime Verification (RV) supports checking specific behaviours for a given
subsystem. See Documentation/trace/rv/runtime-verification.rst”…””}”(hj¯  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kkhj«  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  hžhhŸh³h Nubj  )”}”(hŒwThere are several other pieces of debug instrumentation in the kernel, many
of which can be found in lib/Kconfig.debug
”h]”hÊ)”}”(hŒvThere are several other pieces of debug instrumentation in the kernel, many
of which can be found in lib/Kconfig.debug”h]”hŒvThere are several other pieces of debug instrumentation in the kernel, many
of which can be found in lib/Kconfig.debug”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KmhjÃ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ*”uh1j  hŸh³h K`hjè  hžhubhÊ)”}”(hX  These tools tend to test the kernel as a whole, and do not "pass" like
kselftest or KUnit tests. They can be combined with KUnit or kselftest by
running tests on a kernel with these tools enabled: you can then be sure
that none of these errors are occurring during the test.”h]”hX  These tools tend to test the kernel as a whole, and do not â€œpassâ€ like
kselftest or KUnit tests. They can be combined with KUnit or kselftest by
running tests on a kernel with these tools enabled: you can then be sure
that none of these errors are occurring during the test.”…””}”(hjã  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kphjè  hžhubhÊ)”}”(hŒpSome of these tools integrate with KUnit or kselftest and will
automatically fail tests if an issue is detected.”h]”hŒpSome of these tools integrate with KUnit or kselftest and will
automatically fail tests if an issue is detected.”…””}”(hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kuhjè  hžhubeh}”(h]”Œdynamic-analysis-tools”ah ]”h"]”Œdynamic analysis tools”ah$]”h&]”uh1h´hh¶hžhhŸh³h KVubhµ)”}”(hhh]”(hº)”}”(hŒStatic Analysis Tools”h]”hŒStatic Analysis Tools”…””}”(hj
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h KyubhÊ)”}”(hXR  In addition to testing a running kernel, one can also analyze kernel source code
directly (**at compile time**) using **static analysis** tools. The tools
commonly used in the kernel allow one to inspect the whole source tree or just
specific files within it. They make it easier to detect and fix problems during
the development process.”h]”(hŒ[In addition to testing a running kernel, one can also analyze kernel source code
directly (”…””}”(hj  hžhhŸNh NubhŒstrong”“”)”}”(hŒ**at compile time**”h]”hŒat compile time”…””}”(hj"  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j   hj  ubhŒ) using ”…””}”(hj  hžhhŸNh Nubj!  )”}”(hŒ**static analysis**”h]”hŒstatic analysis”…””}”(hj4  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j   hj  ubhŒÉ tools. The tools
commonly used in the kernel allow one to inspect the whole source tree or just
specific files within it. They make it easier to detect and fix problems during
the development process.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K{hj  hžhubhÊ)”}”(hX  Sparse can help test the kernel by performing type-checking, lock checking,
value range checking, in addition to reporting various errors and warnings while
examining the code. See the Documentation/dev-tools/sparse.rst documentation
page for details on how to use it.”h]”hX  Sparse can help test the kernel by performing type-checking, lock checking,
value range checking, in addition to reporting various errors and warnings while
examining the code. See the Documentation/dev-tools/sparse.rst documentation
page for details on how to use it.”…””}”(hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj  hžhubhÊ)”}”(hXŸ  Smatch extends Sparse and provides additional checks for programming logic
mistakes such as missing breaks in switch statements, unused return values on
error checking, forgetting to set an error code in the return of an error path,
etc. Smatch also has tests against more serious issues such as integer
overflows, null pointer dereferences, and memory leaks. See the project page at
http://smatch.sourceforge.net/.”h]”(hX€  Smatch extends Sparse and provides additional checks for programming logic
mistakes such as missing breaks in switch statements, unused return values on
error checking, forgetting to set an error code in the return of an error path,
etc. Smatch also has tests against more serious issues such as integer
overflows, null pointer dereferences, and memory leaks. See the project page at
”…””}”(hjZ  hžhhŸNh NubhŒ	reference”“”)”}”(hŒhttp://smatch.sourceforge.net/”h]”hŒhttp://smatch.sourceforge.net/”…””}”(hjd  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”jf  uh1jb  hjZ  ubhŒ.”…””}”(hjZ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K†hj  hžhubhÊ)”}”(hX  Coccinelle is another static analyzer at our disposal. Coccinelle is often used
to aid refactoring and collateral evolution of source code, but it can also help
to avoid certain bugs that occur in common code patterns. The types of tests
available include API tests, tests for correct usage of kernel iterators, checks
for the soundness of free operations, analysis of locking behavior, and further
tests known to help keep consistent kernel usage. See the
Documentation/dev-tools/coccinelle.rst documentation page for details.”h]”hX  Coccinelle is another static analyzer at our disposal. Coccinelle is often used
to aid refactoring and collateral evolution of source code, but it can also help
to avoid certain bugs that occur in common code patterns. The types of tests
available include API tests, tests for correct usage of kernel iterators, checks
for the soundness of free operations, analysis of locking behavior, and further
tests known to help keep consistent kernel usage. See the
Documentation/dev-tools/coccinelle.rst documentation page for details.”…””}”(hj}  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj  hžhubhÊ)”}”(hŒšBeware, though, that static analysis tools suffer from **false positives**.
Errors and warns need to be evaluated carefully before attempting to fix them.”h]”(hŒ7Beware, though, that static analysis tools suffer from ”…””}”(hj‹  hžhhŸNh Nubj!  )”}”(hŒ**false positives**”h]”hŒfalse positives”…””}”(hj“  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j   hj‹  ubhŒP.
Errors and warns need to be evaluated carefully before attempting to fix them.”…””}”(hj‹  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K•hj  hžhubhµ)”}”(hhh]”(hº)”}”(hŒWhen to use Sparse and Smatch”h]”hŒWhen to use Sparse and Smatch”…””}”(hj®  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj«  hžhhŸh³h K™ubhÊ)”}”(hŒÕSparse does type checking, such as verifying that annotated variables do not
cause endianness bugs, detecting places that use ``__user`` pointers improperly,
and analyzing the compatibility of symbol initializers.”h]”(hŒ~Sparse does type checking, such as verifying that annotated variables do not
cause endianness bugs, detecting places that use ”…””}”(hj¼  hžhhŸNh NubhŒliteral”“”)”}”(hŒ
``__user``”h]”hŒ__user”…””}”(hjÆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÄ  hj¼  ubhŒM pointers improperly,
and analyzing the compatibility of symbol initializers.”…””}”(hj¼  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K›hj«  hžhubhÊ)”}”(hX  Smatch does flow analysis and, if allowed to build the function database, it
also does cross function analysis. Smatch tries to answer questions like where
is this buffer allocated? How big is it? Can this index be controlled by the
user? Is this variable larger than that variable?”h]”hX  Smatch does flow analysis and, if allowed to build the function database, it
also does cross function analysis. Smatch tries to answer questions like where
is this buffer allocated? How big is it? Can this index be controlled by the
user? Is this variable larger than that variable?”…””}”(hjÞ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KŸhj«  hžhubhÊ)”}”(hŒIt's generally easier to write checks in Smatch than it is to write checks in
Sparse. Nevertheless, there are some overlaps between Sparse and Smatch checks.”h]”hŒŸItâ€™s generally easier to write checks in Smatch than it is to write checks in
Sparse. Nevertheless, there are some overlaps between Sparse and Smatch checks.”…””}”(hjì  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¤hj«  hžhubeh}”(h]”Œwhen-to-use-sparse-and-smatch”ah ]”h"]”Œwhen to use sparse and smatch”ah$]”h&]”uh1h´hj  hžhhŸh³h K™ubhµ)”}”(hhh]”(hº)”}”(hŒ&Strong points of Smatch and Coccinelle”h]”hŒ&Strong points of Smatch and Coccinelle”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h K¨ubhÊ)”}”(hŒØCoccinelle is probably the easiest for writing checks. It works before the
pre-processor so it's easier to check for bugs in macros using Coccinelle.
Coccinelle also creates patches for you, which no other tool does.”h]”hŒÚCoccinelle is probably the easiest for writing checks. It works before the
pre-processor so itâ€™s easier to check for bugs in macros using Coccinelle.
Coccinelle also creates patches for you, which no other tool does.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kªhj  hžhubhÊ)”}”(hXd  For example, with Coccinelle you can do a mass conversion from
``kmalloc(x * size, GFP_KERNEL)`` to ``kmalloc_array(x, size, GFP_KERNEL)``, and
that's really useful. If you just created a Smatch warning and try to push the
work of converting on to the maintainers they would be annoyed. You'd have to
argue about each warning if can really overflow or not.”h]”(hŒ?For example, with Coccinelle you can do a mass conversion from
”…””}”(hj!  hžhhŸNh NubjÅ  )”}”(hŒ!``kmalloc(x * size, GFP_KERNEL)``”h]”hŒkmalloc(x * size, GFP_KERNEL)”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÄ  hj!  ubhŒ to ”…””}”(hj!  hžhhŸNh NubjÅ  )”}”(hŒ&``kmalloc_array(x, size, GFP_KERNEL)``”h]”hŒ"kmalloc_array(x, size, GFP_KERNEL)”…””}”(hj;  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÄ  hj!  ubhŒÞ, and
thatâ€™s really useful. If you just created a Smatch warning and try to push the
work of converting on to the maintainers they would be annoyed. Youâ€™d have to
argue about each warning if can really overflow or not.”…””}”(hj!  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K®hj  hžhubhÊ)”}”(hŒ¢Coccinelle does no analysis of variable values, which is the strong point of
Smatch. On the other hand, Coccinelle allows you to do simple things in a simple
way.”h]”hŒ¢Coccinelle does no analysis of variable values, which is the strong point of
Smatch. On the other hand, Coccinelle allows you to do simple things in a simple
way.”…””}”(hjS  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K´hj  hžhubeh}”(h]”Œ&strong-points-of-smatch-and-coccinelle”ah ]”h"]”Œ&strong points of smatch and coccinelle”ah$]”h&]”uh1h´hj  hžhhŸh³h K¨ubeh}”(h]”Œstatic-analysis-tools”ah ]”h"]”Œstatic analysis tools”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kyubeh}”(h]”Œkernel-testing-guide”ah ]”h"]”Œkernel testing guide”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jœ  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jv  js  j¢  jŸ  jš  j—  jå  jâ  j  j  jn  jk  jÿ  jü  jf  jc  uŒ	nametypes”}”(jv  ‰j¢  ‰jš  ‰jå  ‰j  ‰jn  ‰jÿ  ‰jf  ‰uh}”(js  h¶jŸ  hÙj—  j  jâ  j¥  j  jè  jk  j  jü  j«  jc  j  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.