Received-SPF: softfail (google.com: domain of transitioning linux-kernel-owner@vger.kernel.org does not designate 23.128.96.19 as permitted sender) client-ip=23.128.96.19;
Date:   Mon, 28 Mar 2022 18:19:56 -0300
From:   Marcelo Schmitt <marcelo.schmitt1@gmail.com>
To:     corbet@lwn.net, mchehab+huawei@kernel.org, dlatypov@google.com,
        davidgow@google.com
Cc:     linux-doc@vger.kernel.org, linux-sparse@vger.kernel.org,
        cocci@inria.fr, smatch@vger.kernel.org,
        linux-kernel@vger.kernel.org, skhan@linuxfoundation.org
Subject: [PATCH] Documentation: dev-tools: Add a section for static analysis
 tools
Message-ID: <YkImfPbNOzQBq5ZD@marsc.168.1.7>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Precedence: bulk

Complement the Kernel Testing Guide documentation page by adding a
section about static analysis tools.

Signed-off-by: Marcelo Schmitt <marcelo.schmitt1@gmail.com>
---
Hey everyone,

I think this patch can be a good addition to the documentation as
discussed in the thread for the testing guide documentation page:
Link: https://lore.kernel.org/linux-doc/CABVgOS=2iYtqTVdxwH=mcFpcSuLP4cpJ4s6PKP4Gc-SH6jidgQ@mail.gmail.com/

If you think it would be worth it, I can try making something more
elaborated. Maybe provide some guidance on when to use each tool.
I've been studying how Linux device drivers are tested.
Here's a post I wrote talking about some testing tools.
Link: https://marcelosc.gitlab.io/how-is-linux-tested/

Best regards,
Marcelo

 Documentation/dev-tools/testing-overview.rst | 29 ++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/Documentation/dev-tools/testing-overview.rst b/Documentation/dev-tools/testing-overview.rst
index 65feb81edb14..b00511109a9d 100644
--- a/Documentation/dev-tools/testing-overview.rst
+++ b/Documentation/dev-tools/testing-overview.rst
@@ -115,3 +115,32 @@ that none of these errors are occurring during the test.
 Some of these tools integrate with KUnit or kselftest and will
 automatically fail tests if an issue is detected.
 
+Static Analysis Tools
+======================
+
+In addition to testing a running kernel, one may also scout for bugs by
+analyzing the source code semantics. Three tools are well known for serving this
+purpose.
+
+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.
+
+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/.
+
+We also have Coccinelle as an option within static analyzers. Coccinelle is
+often used to aid collateral evolution of source code, but it can also help to
+avoid certain bugs that have been expressed semantically. 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.
+
+These static analysis tools support running tests on the whole source tree or
+over a specific file or directory.
-- 
2.35.1