From patchwork Mon Aug 8 23:34:59 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 73493 Delivered-To: patch@linaro.org Received: by 10.140.29.52 with SMTP id a49csp210281qga; Mon, 8 Aug 2016 16:36:55 -0700 (PDT) X-Received: by 10.66.142.105 with SMTP id rv9mr47688288pab.33.1470699412556; Mon, 08 Aug 2016 16:36:52 -0700 (PDT) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id g4si39333939pax.227.2016.08.08.16.36.52; Mon, 08 Aug 2016 16:36:52 -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 S1752647AbcHHXgs (ORCPT + 27 others); Mon, 8 Aug 2016 19:36:48 -0400 Received: from tex.lwn.net ([70.33.254.29]:44618 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752258AbcHHXf1 (ORCPT ); Mon, 8 Aug 2016 19:35:27 -0400 Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by vena.lwn.net (Postfix) with ESMTP id 4FAB0154004B; Mon, 8 Aug 2016 17:35:26 -0600 (MDT) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jani Nikula , Jonathan Corbet , Andrey Ryabinin Subject: [PATCH 07/10] docs: sphinxify ubsan.txt and move it to dev-tools Date: Mon, 8 Aug 2016 17:34:59 -0600 Message-Id: <20160808233502.16950-8-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 Cc: Andrey Ryabinin Signed-off-by: Jonathan Corbet --- Documentation/dev-tools/tools.rst | 1 + Documentation/{ubsan.txt => dev-tools/ubsan.rst} | 42 +++++++++++++----------- 2 files changed, 24 insertions(+), 19 deletions(-) rename Documentation/{ubsan.txt => dev-tools/ubsan.rst} (78%) -- 2.9.2 diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst index 0500e65..2d11297 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/tools.rst @@ -19,3 +19,4 @@ whole; patches welcome! kcov gcov kasan + ubsan diff --git a/Documentation/ubsan.txt b/Documentation/dev-tools/ubsan.rst similarity index 78% rename from Documentation/ubsan.txt rename to Documentation/dev-tools/ubsan.rst index f58215e..655e6b6 100644 --- a/Documentation/ubsan.txt +++ b/Documentation/dev-tools/ubsan.rst @@ -1,7 +1,5 @@ -Undefined Behavior Sanitizer - UBSAN - -Overview --------- +The Undefined Behavior Sanitizer - UBSAN +======================================== UBSAN is a runtime undefined behaviour checker. @@ -10,11 +8,13 @@ Compiler inserts code that perform certain kinds of checks before operations that may cause UB. If check fails (i.e. UB detected) __ubsan_handle_* function called to print error message. -GCC has that feature since 4.9.x [1] (see -fsanitize=undefined option and -its suboptions). GCC 5.x has more checkers implemented [2]. +GCC has that feature since 4.9.x [1_] (see ``-fsanitize=undefined`` option and +its suboptions). GCC 5.x has more checkers implemented [2_]. Report example ---------------- +-------------- + +:: ================================================================================ UBSAN: Undefined behaviour in ../include/linux/bitops.h:110:33 @@ -47,29 +47,33 @@ Report example Usage ----- -To enable UBSAN configure kernel with: +To enable UBSAN configure kernel with:: CONFIG_UBSAN=y -and to check the entire kernel: +and to check the entire kernel:: CONFIG_UBSAN_SANITIZE_ALL=y To enable instrumentation 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): - UBSAN_SANITIZE_main.o := y +- For a single file (e.g. main.o):: + + UBSAN_SANITIZE_main.o := y - For all files in one directory: - UBSAN_SANITIZE := y +- For all files in one directory:: + + UBSAN_SANITIZE := y To exclude files from being instrumented even if -CONFIG_UBSAN_SANITIZE_ALL=y, use: +``CONFIG_UBSAN_SANITIZE_ALL=y``, use:: + + UBSAN_SANITIZE_main.o := n + +and:: - UBSAN_SANITIZE_main.o := n - and: - UBSAN_SANITIZE := n + UBSAN_SANITIZE := n Detection of unaligned accesses controlled through the separate option - CONFIG_UBSAN_ALIGNMENT. It's off by default on architectures that support @@ -80,5 +84,5 @@ reports. References ---------- -[1] - https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html -[2] - https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html +.. _1: https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html +.. _2: https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html