[PATCH] Documentation for sanitizer special case list

[Alexey Samsonov]

samsonov added you to the CC list for the revision "Documentation for sanitizer special case list".

Hi eugenis, silvas,

This documents the usage of -f(no)?sanitize-blacklist flags,
and the generic format of this file. Note, that although the original
name is "blacklist", we start to rename it into "special case list",
as newer tools (DataFlowSanitizer, which is under development) may use
to alter instrumentation instead of disabling it completely.

http://llvm-reviews.chandlerc.com/D1268

Files:
  docs/UsersManual.rst
  docs/SanitizerSpecialCaseList.rst
  docs/index.rst
  docs/AddressSanitizer.rst

Index: docs/UsersManual.rst
===================================================================
--- docs/UsersManual.rst
+++ docs/UsersManual.rst
@@ -940,6 +940,15 @@
       it is of the wrong dynamic type, or that its lifetime has not
       begun or has ended. Incompatible with ``-fno-rtti``.
 
+   You can turn off or modify checks for certain source files, functions
+   or even variables by providing a special file:
+
+   -  ``-fsanitize-blacklist=/path/to/blacklist/file``: disable or modify
+      sanitizer checks for objects listed in the file. See
+      :doc:`SanitizerSpecialCaseList` for file format description.
+   -  ``-fno-sanitize-blacklist``: don't use blacklist file, if it was
+      specified earlier in the command line.
+
    Experimental features of AddressSanitizer (not ready for widespread
    use, require explicit ``-fsanitize=address``):
 
Index: docs/SanitizerSpecialCaseList.rst
===================================================================
--- /dev/null
+++ docs/SanitizerSpecialCaseList.rst
@@ -0,0 +1,49 @@
+===========================
+Sanitizer special case list
+===========================
+
+.. contents::
+   :local:
+
+Goal
+====
+
+User of sanitizer tools, such as :doc:`AddressSanitizer`, :doc:`ThreadSanitizer`
+or :doc:`MemorySanitizer` may want to disable or alter some checks for
+certain objects to:
+
+* speedup hot function, which is known to be correct;
+* ignore a function that does some low-level magic (e.g. walks through the
+  thread stack, bypassing the frame boundaries);
+* ignore a known problem.
+
+To achieve this, user may provide a file listing the objects he wants to
+ignore, and provide it to clang at compile-time.
+
+Generally, the use of this file is **discouraged**, in most cases it's better
+to fix the reported issue in the source code.
+
+Format
+======
+
+Each special case list entry occupies a single line.
+
+.. code-block:: bash
+
+    # Empty lines, and lines starting with # are ignored.
+    # Turn off checks for the source file:
+    src:/path/to/source/file.c
+    # Turn off checks for a particular functions (use mangled names):
+    fun:MyFooBar
+    fun:_Z8MyFooBarv
+    # Wildcards are supported:
+    src:bad/sources/*
+    fun:*BadFunction*
+
+Some sanitizer tools may introduce custom entry types - see the tool-specific docs.
+
+Usage
+=====
+
+Create a file and provide it to the compiler using ``-fsanitize-blacklist`` flag.
+See :doc:`UsersManual` for details.
Index: docs/index.rst
===================================================================
--- docs/index.rst
+++ docs/index.rst
@@ -21,6 +21,7 @@
    AddressSanitizer
    ThreadSanitizer
    MemorySanitizer
+   SanitizerSpecialCaseList
    Modules
    FAQ
 
Index: docs/AddressSanitizer.rst
===================================================================
--- docs/AddressSanitizer.rst
+++ docs/AddressSanitizer.rst
@@ -126,6 +126,24 @@
 you should set environment variable
 ``ASAN_OPTIONS=check_initialization_order=1``.
 
+Blacklist
+---------
+
+You may use sanitizer special case list to disable AddressSanizier checks for
+certain source files, functions and global variables. See
+:doc:`SanitizerSpecialCaseList` for general file format description.
+AddressSanitizer-specific entry formats are:
+
+.. code-block:: bash
+
+    # Disable checks for globals with certain names or types:
+    global:bad_array
+    type:*Namespace::BadClassName*
+    # Disable initialization-order checks for globals:
+    global:bad_init_global=init
+    type:*Namespace::BadInitClassName*=init
+    src:bad/init/files/*=init
+
 Supported Platforms
 ===================
-------------- next part --------------
A non-text attachment was scrubbed...
Name: D1268.1.patch
Type: text/x-patch
Size: 3634 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20130802/73dd2816/attachment.bin>