From patchwork Thu Aug 18 23:46:30 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 74211 Delivered-To: patch@linaro.org Received: by 10.140.29.52 with SMTP id a49csp89261qga; Thu, 18 Aug 2016 19:25:37 -0700 (PDT) X-Received: by 10.98.87.90 with SMTP id l87mr9754614pfb.133.1471573537360; Thu, 18 Aug 2016 19:25:37 -0700 (PDT) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id i67si2367374pfg.136.2016.08.18.19.25.35; Thu, 18 Aug 2016 19:25:37 -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 S1754624AbcHSCZI convert rfc822-to-8bit (ORCPT + 27 others); Thu, 18 Aug 2016 22:25:08 -0400 Received: from tex.lwn.net ([70.33.254.29]:34653 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753461AbcHSAsj (ORCPT ); Thu, 18 Aug 2016 20:48:39 -0400 Received: from lwn.net (localhost.localdomain [127.0.0.1]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by vena.lwn.net (Postfix) with ESMTP id B43B81540057; Thu, 18 Aug 2016 17:46:31 -0600 (MDT) Date: Thu, 18 Aug 2016 17:46:30 -0600 From: Jonathan Corbet To: Christoph Hellwig Cc: Daniel Vetter , Jani Nikula , linux-doc@vger.kernel.org, Linux Kernel Mailing List Subject: Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Message-ID: <20160818174630.4abdf25d@lwn.net> In-Reply-To: <20160809083106.GA25504@infradead.org> References: <20160808233502.16950-1-corbet@lwn.net> <20160808233502.16950-4-corbet@lwn.net> <20160809080736.GA15461@infradead.org> <87lh06xsk9.fsf@intel.com> <20160809082209.GA7553@infradead.org> <20160809083106.GA25504@infradead.org> Organization: LWN.net MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Tue, 9 Aug 2016 01:31:06 -0700 Christoph Hellwig wrote: > On Tue, Aug 09, 2016 at 10:28:38AM +0200, Daniel Vetter wrote: > > The point is to make the docs more discoverable by being able to > > cross-link them. Old hats like us don't need that, but it definitely > > has value in bringing new folks on board. > > But do that in a way that keeps the old hats happy. The crazy use of > punctuation and the weird quotes is an absolute no-go. So would the old hats be happier with a patch that looks like this? The quality of the formatted output suffers slightly, but it's not a big deal... Thanks, jon >From d228af5bcb60fda50f8b3a100c0539c4994df040 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sun, 7 Aug 2016 15:09:14 -0600 Subject: [PATCH] docs: sphinxify sparse.txt and move to dev-tools 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} | 39 +++++++++++++--------- Documentation/dev-tools/tools.rst | 1 + 2 files changed, 25 insertions(+), 15 deletions(-) rename Documentation/{sparse.txt => dev-tools/sparse.rst} (82%) -- 2.9.3 diff --git a/Documentation/sparse.txt b/Documentation/dev-tools/sparse.rst similarity index 82% rename from Documentation/sparse.txt rename to Documentation/dev-tools/sparse.rst index eceab13..8c250e8 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; @@ -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 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. -So the simpler way is to just do +So the simpler way is to just do:: typedef int __bitwise pm_request_t; @@ -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. 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 @@ -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,7 +101,7 @@ 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 @@ -101,7 +110,7 @@ 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