================
@@ -0,0 +1,162 @@
+================
+TypeSanitizer
+================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+The TypeSanitizer is a detector for strict type aliasing violations. It 
consists of a compiler
+instrumentation module and a run-time library. C/C++ has type-based aliasing 
rules, and LLVM 
+can exploit these for optimizations given the TBAA metadata Clang emits. In 
general, a pointer 
+of a given type cannot access an object of a different type, with only a few 
exceptions. 
+
+These rules aren't always apparent to users, which leads to code that violates 
these rules
+(e.g. for type punning). This can lead to optimization passes introducing bugs 
unless the 
+code is build with ``-fno-strict-aliasing``, sacrificing performance.
+
+TypeSanitizer is built to catch when these strict aliasing rules have been 
violated, helping 
+users find where such bugs originate in their code despite the code looking 
valid at first glance.
+
+As TypeSanitizer is still experimental, it can currently have a large impact 
on runtime speed, 
+memory use, and code size.
+
+How to build
+============
+
+Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_ and enable
+the ``compiler-rt`` runtime. An example CMake configuration that will allow
+for the use/testing of TypeSanitizer:
+
+.. code-block:: console
+
+   $ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang" 
-DLLVM_ENABLE_RUNTIMES="compiler-rt" <path to source>/llvm
+
+Usage
+=====
+
+Compile and link your program with ``-fsanitize=type`` flag.  The
+TypeSanitizer run-time library should be linked to the final executable, so
+make sure to use ``clang`` (not ``ld``) for the final link step. To
+get a reasonable performance add ``-O1`` or higher.
+TypeSanitizer by default doesn't print the full stack trace in error messages. 
Use ``TYSAN_OPTIONS=print_stacktrace=1`` 
+to print the full trace. To get nicer stack traces in error messages add 
``-fno-omit-frame-pointer`` and 
+``-g``.  To get perfect stack traces you may need to disable inlining (just 
use ``-O1``) and tail call elimination 
+(``-fno-optimize-sibling-calls``).
+
+.. code-block:: console
+
+    % cat example_AliasViolation.c
+    int main(int argc, char **argv) {
+      int x = 100;
+      float *y = (float*)&x;
+      *y += 2.0f;          // Strict aliasing violation
+      return 0;
+    }
+
+    # Compile and link
+    % clang++ -g -fsanitize=type example_AliasViolation.cc
+
+The program will print an error message to stderr each time a strict aliasing 
violation is detected. 
+The program won't terminate, which will allow you to detect many strict 
aliasing violations in one 
+run.
+
+.. code-block:: console
+
+    % ./a.out
+    ==1375532==ERROR: TypeSanitizer: type-aliasing-violation on address 
0x7ffeebf1a72c (pc 0x5b3b1145ff41 bp 0x7ffeebf1a660 sp 0x7ffeebf19e08 tid 
1375532)
+    READ of size 4 at 0x7ffeebf1a72c with type float accesses an existing 
object of type int
+        #0 0x5b3b1145ff40 in main example_AliasViolation.c:4:10
+
+    ==1375532==ERROR: TypeSanitizer: type-aliasing-violation on address 
0x7ffeebf1a72c (pc 0x5b3b1146008a bp 0x7ffeebf1a660 sp 0x7ffeebf19e08 tid 
1375532)
+    WRITE of size 4 at 0x7ffeebf1a72c with type float accesses an existing 
object of type int
+        #0 0x5b3b11460089 in main example_AliasViolation.c:4:10
+
+Error terminology
+------------------
+
+There are some terms that may appear in TypeSanitizer errors that are derived 
from 
+`TBAA Metadata <https://llvm.org/docs/LangRef.html#tbaa-metadata>`. This 
section hopes to provide a 
+brief dictionary of these terms.
+
+* ``omnipotent char``: This is a special type which can alias with anything. 
Its name comes from the C/C++ 
+  type ``char``.
+* ``type p[x]``: This signifies pointers to the type. x is the number of 
indirections to reach the final value.
----------------
AaronBallman wrote:

```suggestion
* ``type p[x]``: This signifies pointers to the type. ``x`` is the number of 
indirections to reach the final value.
```

https://github.com/llvm/llvm-project/pull/123595
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

Reply via email to