Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1458319 > unrolled thread

[PATCH 00/10] [RFC] Sphinxify and coalesce development-tool documents

Back to article view | Back to linux.kernel

Contents

  [PATCH 00/10] [RFC] Sphinxify and coalesce development-tool documents Jonathan Corbet <corbet@lwn.net> - 2016-08-09 01:40 +0200
    [PATCH 05/10] docs: sphinixfy gcov.txt and move to dev-tools Jonathan Corbet <corbet@lwn.net> - 2016-08-09 01:40 +0200
    [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Jonathan Corbet <corbet@lwn.net> - 2016-08-09 01:40 +0200
      Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Christoph Hellwig <hch@infradead.org> - 2016-08-09 10:10 +0200
        Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-08-09 10:30 +0200
          Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Christoph Hellwig <hch@infradead.org> - 2016-08-09 10:40 +0200
            Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-08-09 12:10 +0200
            Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Jonathan Corbet <corbet@lwn.net> - 2016-08-10 01:00 +0200
        Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Christoph Hellwig <hch@infradead.org> - 2016-08-09 10:30 +0200
        Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools Jani Nikula <jani.nikula@intel.com> - 2016-08-09 10:30 +0200
    Re: [PATCH 09/10] docs: sphinxify kmemcheck.txt and move to dev-tools Vegard Nossum <vegard.nossum@gmail.com> - 2016-08-09 09:10 +0200
    Re: [PATCH 00/10] [RFC] Sphinxify and coalesce development-tool documents Jani Nikula <jani.nikula@intel.com> - 2016-08-09 11:00 +0200

#1458319 — [PATCH 00/10] [RFC] Sphinxify and coalesce development-tool documents

This series of patches collects a number of documents related to kernel
development tools, converts them to the Sphinx format, and puts them
together into the dev-tools directory.  The resulting formatted
documentation can be seen at:

	http://static.lwn.net/kerneldoc/dev-tools/tools.html

I've not made any textual changes, so this is far from having created a
truly coherent document, but it is a step in the right direction and shows
the sort of change I have in mind for the documentation directory in
general.

FWIW, the sphinx conversion was trivially easy - these documents were
nearly in reStructuredText already!

Cc: Jan Kiszka <jan.kiszka@siemens.com>
Cc: Vegard Nossum <vegardno@ifi.uio.no>
Cc: Pekka Enberg <penberg@kernel.org>
Cc: Catalin Marinas <catalin.marinas@arm.com>
Cc: Andrey Ryabinin <aryabinin@virtuozzo.com>
Cc: Alexander Potapenko <glider@google.com>
Cc: Dmitry Vyukov <dvyukov@google.com>
Cc: Michal Marek <mmarek@suse.com>
Cc: Gilles Muller <Gilles.Muller@lip6.fr>
Cc: Nicolas Palix <nicolas.palix@imag.fr>
Cc: Julia Lawall <julia.lawall@lip6.fr>
Cc: Jani Nikula <jani.nikula@intel.com>

Jonathan Corbet (10):
  docs: create a new dev-tools directory
  docs: sphinxify coccinelle.txt and add it to dev-tools
  docs: sphinxify sparse.txt and move to dev-tools
  docs: sphinxify kcov.txt and move to dev-tools
  docs: sphinixfy gcov.txt and move to dev-tools
  docs: sphinxify kasan.txt and move to dev-tools
  docs: sphinxify ubsan.txt and move it to dev-tools
  docs: sphinxify kmemleak.txt and move it to dev-tools
  docs: sphinxify kmemcheck.txt and move to dev-tools
  docs: Sphinxify gdb-kernel-debugging.txt and move to dev-tools

 .../{coccinelle.txt => dev-tools/coccinelle.rst}   | 359 +++++-----
 Documentation/dev-tools/gcov.rst                   | 256 +++++++
 .../gdb-kernel-debugging.rst}                      |  77 ++-
 Documentation/dev-tools/kasan.rst                  | 173 +++++
 Documentation/dev-tools/kcov.rst                   | 111 +++
 Documentation/dev-tools/kmemcheck.rst              | 733 ++++++++++++++++++++
 .../{kmemleak.txt => dev-tools/kmemleak.rst}       |  93 +--
 Documentation/{sparse.txt => dev-tools/sparse.rst} |  61 +-
 Documentation/dev-tools/tools.rst                  |  25 +
 Documentation/{ubsan.txt => dev-tools/ubsan.rst}   |  42 +-
 Documentation/gcov.txt                             | 257 -------
 Documentation/index.rst                            |   1 +
 Documentation/kasan.txt                            | 171 -----
 Documentation/kcov.txt                             | 111 ---
 Documentation/kmemcheck.txt                        | 754 ---------------------
 MAINTAINERS                                        |  10 +-
 16 files changed, 1647 insertions(+), 1587 deletions(-)
 rename Documentation/{coccinelle.txt => dev-tools/coccinelle.rst} (56%)
 create mode 100644 Documentation/dev-tools/gcov.rst
 rename Documentation/{gdb-kernel-debugging.txt => dev-tools/gdb-kernel-debugging.rst} (73%)
 create mode 100644 Documentation/dev-tools/kasan.rst
 create mode 100644 Documentation/dev-tools/kcov.rst
 create mode 100644 Documentation/dev-tools/kmemcheck.rst
 rename Documentation/{kmemleak.txt => dev-tools/kmemleak.rst} (73%)
 rename Documentation/{sparse.txt => dev-tools/sparse.rst} (61%)
 create mode 100644 Documentation/dev-tools/tools.rst
 rename Documentation/{ubsan.txt => dev-tools/ubsan.rst} (78%)
 delete mode 100644 Documentation/gcov.txt
 delete mode 100644 Documentation/kasan.txt
 delete mode 100644 Documentation/kcov.txt
 delete mode 100644 Documentation/kmemcheck.txt

-- 
2.9.2

[toc] | [next] | [standalone]

#1458320 — [PATCH 05/10] docs: sphinixfy gcov.txt and move to dev-tools

No textual changes beyond formatting.

Cc: Peter Oberparleiter <oberpar@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/dev-tools/gcov.rst  | 256 +++++++++++++++++++++++++++++++++++++
 Documentation/dev-tools/tools.rst |   1 +
 Documentation/gcov.txt            | 257 --------------------------------------
 MAINTAINERS                       |   2 +-
 4 files changed, 258 insertions(+), 258 deletions(-)
 create mode 100644 Documentation/dev-tools/gcov.rst
 delete mode 100644 Documentation/gcov.txt

diff --git a/Documentation/dev-tools/gcov.rst b/Documentation/dev-tools/gcov.rst
new file mode 100644
index 0000000..19eedfe
--- /dev/null
+++ b/Documentation/dev-tools/gcov.rst
@@ -0,0 +1,256 @@
+Using gcov with the Linux kernel
+================================
+
+gcov profiling kernel support enables the use of GCC's coverage testing
+tool gcov_ with the Linux kernel. Coverage data of a running kernel
+is exported in gcov-compatible format via the "gcov" debugfs directory.
+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)::
+
+    # cd /tmp/linux-out
+    # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c
+
+This will create source code files annotated with execution counts
+in the current directory. In addition, graphical gcov front-ends such
+as lcov_ can be used to automate the process of collecting data
+for the entire kernel and provide coverage overviews in HTML format.
+
+Possible uses:
+
+* debugging (has this line been reached at all?)
+* test improvement (how do I change my test to cover these lines?)
+* minimizing kernel configurations (do I need this option if the
+  associated code is never run?)
+
+.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
+.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php
+
+
+Preparation
+-----------
+
+Configure the kernel with::
+
+        CONFIG_DEBUG_FS=y
+        CONFIG_GCOV_KERNEL=y
+
+select the gcc's gcov format, default is autodetect based on gcc version::
+
+        CONFIG_GCOV_FORMAT_AUTODETECT=y
+
+and to get coverage data for the entire kernel::
+
+        CONFIG_GCOV_PROFILE_ALL=y
+
+Note that kernels compiled with profiling flags will be significantly
+larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported
+on all architectures.
+
+Profiling data will only become accessible once debugfs has been
+mounted::
+
+        mount -t debugfs none /sys/kernel/debug
+
+
+Customization
+-------------
+
+To enable profiling for specific files or directories, add a line
+similar to the following to the respective kernel Makefile:
+
+- For a single file (e.g. main.o)::
+
+	GCOV_PROFILE_main.o := y
+
+- For all files in one directory::
+
+	GCOV_PROFILE := y
+
+To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL
+is specified, use::
+
+	GCOV_PROFILE_main.o := n
+
+and::
+
+	GCOV_PROFILE := n
+
+Only files which are linked to the main kernel image or are compiled as
+kernel modules are supported by this mechanism.
+
+
+Files
+-----
+
+The gcov kernel support creates the following files in debugfs:
+
+``/sys/kernel/debug/gcov``
+	Parent directory for all gcov-related files.
+
+``/sys/kernel/debug/gcov/reset``
+	Global reset file: resets all coverage data to zero when
+        written to.
+
+``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda``
+	The actual gcov data file as understood by the gcov
+        tool. Resets file coverage data to zero when written to.
+
+``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno``
+	Symbolic link to a static data file required by the gcov
+        tool. This file is generated by gcc when compiling with
+        option ``-ftest-coverage``.
+
+
+Modules
+-------
+
+Kernel modules may contain cleanup code which is only run during
+module unload time. The gcov mechanism provides a means to collect
+coverage data for such code by keeping a copy of the data associated
+with the unloaded module. This data remains available through debugfs.
+Once the module is loaded again, the associated coverage counters are
+initialized with the data from its previous instantiation.
+
+This behavior can be deactivated by specifying the gcov_persist kernel
+parameter::
+
+        gcov_persist=0
+
+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.
+
+
+Separated build and test machines
+---------------------------------
+
+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
+cases where the kernel runs on a separate machine, special preparations
+must be made, depending on where the gcov tool is used:
+
+a) gcov is run on the TEST machine
+
+    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
+    copied from build to test machine:
+
+    from the source tree:
+      - all C source files + headers
+
+    from the build tree:
+      - all C source files + headers
+      - all .gcda and .gcno files
+      - all links to directories
+
+    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
+    machine. If any of the path components is symbolic link, the actual
+    directory needs to be used instead (due to make's CURDIR handling).
+
+b) gcov is run on the BUILD machine
+
+    The following files need to be copied after each test case from test
+    to build machine:
+
+    from the gcov directory in sysfs:
+      - all .gcda files
+      - all links to .gcno files
+
+    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.
+
+    Example directory setup on the build machine::
+
+      /tmp/linux:    kernel source tree
+      /tmp/out:      kernel build directory as specified by make O=
+      /tmp/coverage: location of the files copied from the test machine
+
+      [user@build] cd /tmp/out
+      [user@build] gcov -o /tmp/coverage/tmp/out/init main.c
+
+
+Troubleshooting
+---------------
+
+Problem
+    Compilation aborts during linker step.
+
+Cause
+    Profiling flags are specified for source files which are not
+    linked to the main kernel or which are linked by a custom
+    linker procedure.
+
+Solution
+    Exclude affected source files from profiling by specifying
+    ``GCOV_PROFILE := n`` or ``GCOV_PROFILE_basename.o := n`` in the
+    corresponding Makefile.
+
+Problem
+    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.
+
+Solution
+    Use ``cat``' to read ``.gcda`` files and ``cp -d`` to copy links.
+    Alternatively use the mechanism shown in Appendix B.
+
+
+Appendix A: gather_on_build.sh
+------------------------------
+
+Sample script to gather coverage meta files on the build machine
+(see 6a)::
+
+    #!/bin/bash
+
+    KSRC=$1
+    KOBJ=$2
+    DEST=$3
+
+    if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then
+      echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2
+      exit 1
+    fi
+
+    KSRC=$(cd $KSRC; 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 \
+                     -perm /u+r,g+r | tar cfz $DEST -P -T -
+
+    if [ $? -eq 0 ] ; then
+      echo "$DEST successfully created, copy to test system and unpack with:"
+      echo "  tar xfz $DEST -P"
+    else
+      echo "Could not create file $DEST"
+    fi
+
+
+Appendix B: gather_on_test.sh
+-----------------------------
+
+Sample script to gather coverage data files on the test machine
+(see 6b)::
+
+    #!/bin/bash -e
+
+    DEST=$1
+    GCDA=/sys/kernel/debug/gcov
+
+    if [ -z "$DEST" ] ; then
+      echo "Usage: $0 <output.tar.gz>" >&2
+      exit 1
+    fi
+
+    TEMPDIR=$(mktemp -d)
+    echo Collecting data..
+    find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \;
+    find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \;
+    find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \;
+    tar czf $DEST -C $TEMPDIR sys
+    rm -rf $TEMPDIR
+
+    echo "$DEST successfully created, copy to build system and unpack with:"
+    echo "  tar xfz $DEST"
diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst
index 9dcd023..404d044 100644
--- a/Documentation/dev-tools/tools.rst
+++ b/Documentation/dev-tools/tools.rst
@@ -17,3 +17,4 @@ whole; patches welcome!
    coccinelle
    sparse
    kcov
+   gcov
diff --git a/Documentation/gcov.txt b/Documentation/gcov.txt
deleted file mode 100644
index 7b72778..0000000
--- a/Documentation/gcov.txt
+++ /dev/null
@@ -1,257 +0,0 @@
-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
-tool gcov [1] with the Linux kernel. Coverage data of a running kernel
-is exported in gcov-compatible format via the "gcov" debugfs directory.
-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):
-
-# cd /tmp/linux-out
-# gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c
-
-This will create source code files annotated with execution counts
-in the current directory. In addition, graphical gcov front-ends such
-as lcov [2] can be used to automate the process of collecting data
-for the entire kernel and provide coverage overviews in HTML format.
-
-Possible uses:
-
-* debugging (has this line been reached at all?)
-* test improvement (how do I change my test to cover these lines?)
-* minimizing kernel configurations (do I need this option if the
-  associated code is never run?)
-
---
-
-[1] http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
-[2] http://ltp.sourceforge.net/coverage/lcov.php
-
-
-2. Preparation
-==============
-
-Configure the kernel with:
-
-        CONFIG_DEBUG_FS=y
-        CONFIG_GCOV_KERNEL=y
-
-select the gcc's gcov format, default is autodetect based on gcc version:
-
-        CONFIG_GCOV_FORMAT_AUTODETECT=y
-
-and to get coverage data for the entire kernel:
-
-        CONFIG_GCOV_PROFILE_ALL=y
-
-Note that kernels compiled with profiling flags will be significantly
-larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported
-on all architectures.
-
-Profiling data will only become accessible once debugfs has been
-mounted:
-
-        mount -t debugfs none /sys/kernel/debug
-
-
-3. Customization
-================
-
-To enable profiling for specific files or directories, add a line
-similar to the following to the respective kernel Makefile:
-
-        For a single file (e.g. main.o):
-                GCOV_PROFILE_main.o := y
-
-        For all files in one directory:
-                GCOV_PROFILE := y
-
-To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL
-is specified, use:
-
-                GCOV_PROFILE_main.o := n
-        and:
-                GCOV_PROFILE := n
-
-Only files which are linked to the main kernel image or are compiled as
-kernel modules are supported by this mechanism.
-
-
-4. Files
-========
-
-The gcov kernel support creates the following files in debugfs:
-
-        /sys/kernel/debug/gcov
-                Parent directory for all gcov-related files.
-
-        /sys/kernel/debug/gcov/reset
-                Global reset file: resets all coverage data to zero when
-                written to.
-
-        /sys/kernel/debug/gcov/path/to/compile/dir/file.gcda
-                The actual gcov data file as understood by the gcov
-                tool. Resets file coverage data to zero when written to.
-
-        /sys/kernel/debug/gcov/path/to/compile/dir/file.gcno
-                Symbolic link to a static data file required by the gcov
-                tool. This file is generated by gcc when compiling with
-                option -ftest-coverage.
-
-
-5. Modules
-==========
-
-Kernel modules may contain cleanup code which is only run during
-module unload time. The gcov mechanism provides a means to collect
-coverage data for such code by keeping a copy of the data associated
-with the unloaded module. This data remains available through debugfs.
-Once the module is loaded again, the associated coverage counters are
-initialized with the data from its previous instantiation.
-
-This behavior can be deactivated by specifying the gcov_persist kernel
-parameter:
-
-        gcov_persist=0
-
-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.
-
-
-6. Separated build and test machines
-====================================
-
-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
-cases where the kernel runs on a separate machine, special preparations
-must be made, depending on where the gcov tool is used:
-
-a) gcov is run on the TEST machine
-
-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
-copied from build to test machine:
-
-from the source tree:
-  - all C source files + headers
-
-from the build tree:
-  - all C source files + headers
-  - all .gcda and .gcno files
-  - all links to directories
-
-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
-machine. If any of the path components is symbolic link, the actual
-directory needs to be used instead (due to make's CURDIR handling).
-
-b) gcov is run on the BUILD machine
-
-The following files need to be copied after each test case from test
-to build machine:
-
-from the gcov directory in sysfs:
-  - all .gcda files
-  - all links to .gcno files
-
-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.
-
-Example directory setup on the build machine:
-
-  /tmp/linux:    kernel source tree
-  /tmp/out:      kernel build directory as specified by make O=
-  /tmp/coverage: location of the files copied from the test machine
-
-  [user@build] cd /tmp/out
-  [user@build] gcov -o /tmp/coverage/tmp/out/init main.c
-
-
-7. Troubleshooting
-==================
-
-Problem:  Compilation aborts during linker step.
-Cause:    Profiling flags are specified for source files which are not
-          linked to the main kernel or which are linked by a custom
-          linker procedure.
-Solution: Exclude affected source files from profiling by specifying
-          GCOV_PROFILE := n or GCOV_PROFILE_basename.o := n in the
-          corresponding Makefile.
-
-Problem:  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.
-Solution: Use 'cat' to read .gcda files and 'cp -d' to copy links.
-          Alternatively use the mechanism shown in Appendix B.
-
-
-Appendix A: gather_on_build.sh
-==============================
-
-Sample script to gather coverage meta files on the build machine
-(see 6a):
-#!/bin/bash
-
-KSRC=$1
-KOBJ=$2
-DEST=$3
-
-if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then
-  echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2
-  exit 1
-fi
-
-KSRC=$(cd $KSRC; 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 \
-                 -perm /u+r,g+r | tar cfz $DEST -P -T -
-
-if [ $? -eq 0 ] ; then
-  echo "$DEST successfully created, copy to test system and unpack with:"
-  echo "  tar xfz $DEST -P"
-else
-  echo "Could not create file $DEST"
-fi
-
-
-Appendix B: gather_on_test.sh
-=============================
-
-Sample script to gather coverage data files on the test machine
-(see 6b):
-
-#!/bin/bash -e
-
-DEST=$1
-GCDA=/sys/kernel/debug/gcov
-
-if [ -z "$DEST" ] ; then
-  echo "Usage: $0 <output.tar.gz>" >&2
-  exit 1
-fi
-
-TEMPDIR=$(mktemp -d)
-echo Collecting data..
-find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \;
-find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \;
-find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \;
-tar czf $DEST -C $TEMPDIR sys
-rm -rf $TEMPDIR
-
-echo "$DEST successfully created, copy to build system and unpack with:"
-echo "  tar xfz $DEST"
diff --git a/MAINTAINERS b/MAINTAINERS
index 1e5460c..bb53779 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -5118,7 +5118,7 @@ GCOV BASED KERNEL PROFILING
 M:	Peter Oberparleiter <oberpar@linux.vnet.ibm.com>
 S:	Maintained
 F:	kernel/gcov/
-F:	Documentation/gcov.txt
+F:	Documentation/dev-tools/gcov.rst
 
 GDT SCSI DISK ARRAY CONTROLLER DRIVER
 M:	Achim Leubner <achim_leubner@adaptec.com>
-- 
2.9.2

[toc] | [prev] | [next] | [standalone]

#1458321 — [PATCH 03/10] 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 <corbet@lwn.net>
---
 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%)

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 <pavel@ucw.cz>
-Copyright 2006 Bob Copeland <me@bobcopeland.com>
+.. Copyright 2004 Linus Torvalds
+.. Copyright 2004 Pavel Machek <pavel@ucw.cz>
+.. 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
-"__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
-- 
2.9.2

[toc] | [prev] | [next] | [standalone]

#1458484 — Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools

The ugly format is a major regression over a proper simple text
file.  What's the point?

[toc] | [prev] | [next] | [standalone]

#1458491 — Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools

On Tue, Aug 9, 2016 at 10:22 AM, Christoph Hellwig <hch@infradead.org> wrote:
> On Tue, Aug 09, 2016 at 11:19:50AM +0300, Jani Nikula wrote:
>> On Tue, 09 Aug 2016, Christoph Hellwig <hch@infradead.org> wrote:
>> > The ugly format is a major regression over a proper simple text
>> > file.  What's the point?
>>
>> Major regression? Please be reasonable.
>>
>> I think the changes are rather small, and it's a fair compromise between
>> a simple text file and one that can be used to generate pretty
>> documentation [1].
>
> It's a lot less pretty to read - it look like a cat threw up to be
> specific.  The point of the Document is to read it quickly in the kernel
> tree.  If you want fancy websites write a separate document.
>
>> [1] http://static.lwn.net/kerneldoc/dev-tools/sparse.html
>
> And I wouldn't exactly call that pretty.  There is no value add
> over a simple text file here, and it requires a browser to not look
> ugly instead of a text editor, which is a giant usablity regression.

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. And yes I want that, at
least for everything that's at least half-relevant to drm/gpu/i915
topics. And given that we just started on a large-scale effort to roll
out rcu in our driver (besides all the other bits we're using) that's
pretty much everything.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

[toc] | [prev] | [next] | [standalone]

#1458512 — Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools

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.

[toc] | [prev] | [next] | [standalone]

#1458564 — Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools

On Tue, Aug 9, 2016 at 10:31 AM, Christoph Hellwig <hch@infradead.org> 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.

We've been bikeshedding on the exact kind of light markup since over a
year now. Current one is rst, with pretty much uniform support among
the folks who cared that it's the least offensive of the bunch. I
think it can be made slightly less invasive by trading in a bit of the
noise in the sourc for warnings from the html generators (and less
pretty html output), but that's pretty close to nothing already.

The only other option with less markup is markdown, but the only
reason it's less invasive is that I can't really do anything at all.
Definitely no sensible way to pull in things like kernel-doc or the
uapi headers media needs.

Jon, can you please try to respin the patch with fewer changes, but
(probably) more rst warnings?
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

[toc] | [prev] | [next] | [standalone]

#1459166 — Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools

On Tue, 9 Aug 2016 01:31:06 -0700
Christoph Hellwig <hch@infradead.org> 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.

As others have noted, the long-term goal is to turn our disorganized
documentation hairball into something more approachable, maintainable, and
integrated; this is a step in that direction.

I take it you object to the ``literal quotes`` which render in a monospace
font?  That's the bulk of the changes there.  I can certainly take them
out if you really think "__bitwise" looks better than ``__bitwise``; it
will adversely affect the resulting pages, but so be it.

jon

[toc] | [prev] | [next] | [standalone]

#1458493 — Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools

On Tue, Aug 09, 2016 at 11:19:50AM +0300, Jani Nikula wrote:
> On Tue, 09 Aug 2016, Christoph Hellwig <hch@infradead.org> wrote:
> > The ugly format is a major regression over a proper simple text
> > file.  What's the point?
> 
> Major regression? Please be reasonable.
> 
> I think the changes are rather small, and it's a fair compromise between
> a simple text file and one that can be used to generate pretty
> documentation [1].

It's a lot less pretty to read - it look like a cat threw up to be
specific.  The point of the Document is to read it quickly in the kernel
tree.  If you want fancy websites write a separate document.

> [1] http://static.lwn.net/kerneldoc/dev-tools/sparse.html

And I wouldn't exactly call that pretty.  There is no value add
over a simple text file here, and it requires a browser to not look
ugly instead of a text editor, which is a giant usablity regression.

[toc] | [prev] | [next] | [standalone]

#1458497 — Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools

On Tue, 09 Aug 2016, Christoph Hellwig <hch@infradead.org> wrote:
> The ugly format is a major regression over a proper simple text
> file.  What's the point?

Major regression? Please be reasonable.

I think the changes are rather small, and it's a fair compromise between
a simple text file and one that can be used to generate pretty
documentation [1].

BR,
Jani.


[1] http://static.lwn.net/kerneldoc/dev-tools/sparse.html


-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1458461 — Re: [PATCH 09/10] docs: sphinxify kmemcheck.txt and move to dev-tools

Hi,

On 9 August 2016 at 01:35, Jonathan Corbet <corbet@lwn.net> wrote:
> +The shadow bytemap dump legend is as follows:
> +
> +- i: initialized
> +- u: uninitialized
> +- a: unallocated (memory has been allocated by the slab layer, but has not
> +  yet been handed off to anybody)
> +- f: freed (memory has been allocated by the slab layer, but has been freed
> +  by the previous owner)

Maybe you want ``i``, ``u``, etc. here? The rest looks good to me. Thanks!

Although I'm not sure how relevant kmemcheck is anymore with KASAN
being able to do almost all (if not all) that kmemcheck does, and
better. Oh well, I thought the doc wasn't bad in any case ;-)


Vegard

[toc] | [prev] | [next] | [standalone]

#1458527

On Tue, 09 Aug 2016, Jonathan Corbet <corbet@lwn.net> wrote:
> This series of patches collects a number of documents related to kernel
> development tools, converts them to the Sphinx format, and puts them
> together into the dev-tools directory.  The resulting formatted
> documentation can be seen at:
>
> 	http://static.lwn.net/kerneldoc/dev-tools/tools.html
>
> I've not made any textual changes, so this is far from having created a
> truly coherent document, but it is a step in the right direction and shows
> the sort of change I have in mind for the documentation directory in
> general.

FWIW, the whole series is wholeheartedly

Acked-by: Jani Nikula <jani.nikula@intel.com>


-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web