From patchwork Mon Aug 8 23:34:55 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 73494 Delivered-To: patch@linaro.org Received: by 10.140.29.52 with SMTP id a49csp210497qga; Mon, 8 Aug 2016 16:37:43 -0700 (PDT) X-Received: by 10.98.108.3 with SMTP id h3mr161678947pfc.162.1470699463596; Mon, 08 Aug 2016 16:37:43 -0700 (PDT) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id ef8si39332905pac.240.2016.08.08.16.37.43; Mon, 08 Aug 2016 16:37:43 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752696AbcHHXhe (ORCPT + 27 others); Mon, 8 Aug 2016 19:37:34 -0400 Received: from tex.lwn.net ([70.33.254.29]:44602 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752238AbcHHXfZ (ORCPT ); Mon, 8 Aug 2016 19:35:25 -0400 Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by vena.lwn.net (Postfix) with ESMTP id 914181540046; Mon, 8 Aug 2016 17:35:24 -0600 (MDT) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Jonathan Corbet Subject: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Date: Mon, 8 Aug 2016 17:34:55 -0600 Message-Id: <20160808233502.16950-4-corbet@lwn.net> X-Mailer: git-send-email 2.9.2 In-Reply-To: <20160808233502.16950-1-corbet@lwn.net> References: <20160808233502.16950-1-corbet@lwn.net> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Fold the sparse document into the development tools set; no changes to the text itself beyond formatting. Signed-off-by: Jonathan Corbet --- Documentation/{sparse.txt => dev-tools/sparse.rst} | 61 +++++++++++++--------- Documentation/dev-tools/tools.rst | 1 + 2 files changed, 36 insertions(+), 26 deletions(-) rename Documentation/{sparse.txt => dev-tools/sparse.rst} (61%) -- 2.9.2 diff --git a/Documentation/sparse.txt b/Documentation/dev-tools/sparse.rst similarity index 61% rename from Documentation/sparse.txt rename to Documentation/dev-tools/sparse.rst index eceab13..ebb6087 100644 --- a/Documentation/sparse.txt +++ b/Documentation/dev-tools/sparse.rst @@ -1,11 +1,20 @@ -Copyright 2004 Linus Torvalds -Copyright 2004 Pavel Machek -Copyright 2006 Bob Copeland +.. Copyright 2004 Linus Torvalds +.. Copyright 2004 Pavel Machek +.. Copyright 2006 Bob Copeland + +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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- -"__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; @@ -14,19 +23,19 @@ Using sparse for typechecking PM_RESUME = (__force pm_request_t) 2 }; -which makes PM_SUSPEND and PM_RESUME "bitwise" integers (the "__force" is +which makes PM_SUSPEND and PM_RESUME ``bitwise`` integers (the ``__force`` is there because sparse will complain about casting to/from a bitwise type, 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. -And with gcc, all the __bitwise/__force stuff goes away, and it all ends -up looking just like integers to gcc. +And with gcc, all the ``__bitwise``/``__force stuff`` goes away, and it all +ends up looking just like integers to gcc. 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; @@ -35,11 +44,11 @@ So the simpler way is to just do and you now have all the infrastructure needed for strict typechecking. -One small note: the constant integer "0" is special. You can use a +One small note: the constant integer ``0`` is special. You can use a constant zero as a bitwise integer type without sparse ever complaining. -This is because "bitwise" (as the name implies) was designed for making +This is because ``bitwise`` (as the name implies) was designed for making sure that bitwise types don't get mixed up (little-endian vs big-endian -vs cpu-endian vs whatever), and there the constant "0" really _is_ +vs cpu-endian vs whatever), and there the constant ``0`` really _is_ special. __bitwise__ - to be used for relatively compact stuff (gfp_t, etc.) that @@ -50,18 +59,18 @@ __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. Using sparse for lock checking -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------ The following macros are undefined for gcc and defined during a sparse run to use the "context" tracking feature of sparse, applied to locking. These annotations tell sparse when a lock is held, with regard to the annotated function's entry and exit. -__must_hold - The specified lock is held on function entry and exit. +``__must_hold`` - The specified lock is held on function entry and exit. -__acquires - The specified lock is held on function exit, but not entry. +``__acquires`` - The specified lock is held on function exit, but not entry. -__releases - The specified lock is held on function entry, but not exit. +``__releases`` - The specified lock is held on function entry, but not exit. If the function enters and exits without the lock held, acquiring and releasing the lock inside the function in a balanced way, no @@ -69,22 +78,22 @@ annotation is needed. The tree annotations above are for cases where sparse would otherwise report a context imbalance. Getting sparse -~~~~~~~~~~~~~~ +-------------- You can get latest released versions from the Sparse homepage at https://sparse.wiki.kernel.org/index.php/Main_Page 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 -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/ -Once you have it, just do +Once you have it, just do:: make make install @@ -92,16 +101,16 @@ Once you have it, just do as a regular user, and it will install sparse in your ~/bin directory. Using sparse -~~~~~~~~~~~~ +------------ -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 +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 be recompiled or not. The latter is a fast way to check the whole tree if you have already built it. The optional make variable CF can be used to pass arguments to sparse. The 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__" diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index ae0c58c..d4bbda3 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -15,3 +15,4 @@ whole; patches welcome! :maxdepth: 2 coccinelle + sparse