[TySan] Add initial documentation for Type Sanitizer #123595

gbMattN · 2025-01-20T11:50:56Z

Add some initial documentation for type sanitizer [From issue #122522]

llvmbot · 2025-01-20T11:51:31Z

@llvm/pr-subscribers-clang

Author: None (gbMattN)

Changes

Add some initial documentation for type sanitizer [From issue #122522]

Full diff: https://github.com/llvm/llvm-project/pull/123595.diff

1 Files Affected:

(added) clang/docs/TypeSanitizer.rst (+152)

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00000000000000..ceb2fca37df904
--- /dev/null
+++ b/clang/docs/TypeSanitizer.rst
@@ -0,0 +1,152 @@
+================
+TypeSanitizer
+================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+TypeSanitizer is a detector for strict type aliasing violations. It consists of a compiler
+instrumentation module and a run-time library. The tool detects violations such as the use 
+of an illegally cast pointer, or misuse of a union.
+
+The violations TypeSanitizer catches may cause the compiler to emit incorrect code.
+
+Typical slowdown introduced by TypeSanitizer is about **4x** [[CHECK THIS]]. Typical memory overhead introduced by TypeSanitizer is about **9x**. 
+
+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 on 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
+
+If a strict aliasing violation is detected, the program will print an error message to stderr. 
+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]``: Sometimes a program could generate distinct TBAA metadata that resolve to the same name. 
+  To make them unique, they have the character 'p' and a number prepended to their name.
+
+These terms are a result of non-user-facing processes, and not always self-explanatory. There is some 
+interest in changing TypeSanitizer in the future to translate these terms before printing them to users.
+
+Sanitizer features
+==================
+
+``__has_feature(type_sanitizer)``
+------------------------------------
+
+In some cases one may need to execute different code depending on whether
+TypeSanitizer is enabled.
+:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
+this purpose.
+
+.. code-block:: c
+
+    #if defined(__has_feature)
+    #  if __has_feature(type_sanitizer)
+    // code that builds only under TypeSanitizer
+    #  endif
+    #endif
+
+``__attribute__((no_sanitize("type")))``
+-----------------------------------------------
+
+Some code you may not want to be instrumented by TypeSanitizer.  One may use the
+function attribute ``no_sanitize("type")`` to disable instrumenting type aliasing. 
+It is possible, depending on what happens in non-instrumented code, that instrumented code 
+emits false-positives/ false-negatives. This attribute may not be supported by other 
+compilers, so we suggest to use it together with ``__has_feature(type_sanitizer)``.
+
+``__attribute__((disable_sanitizer_instrumentation))``
+--------------------------------------------------------
+
+The ``disable_sanitizer_instrumentation`` attribute can be applied to functions
+to prevent all kinds of instrumentation. As a result, it may introduce false
+positives and incorrect stack traces. Therefore, it should be used with care,
+and only if absolutely required; for example for certain code that cannot
+tolerate any instrumentation and resulting side-effects. This attribute
+overrides ``no_sanitize("type")``.
+
+Ignorelist
+----------
+
+TypeSanitizer supports ``src`` and ``fun`` entity types in
+:doc:`SanitizerSpecialCaseList`, that can be used to suppress aliasing 
+violation reports in the specified source files or functions. Like 
+with other methods of ignoring instrumentation, this can result in false 
+positives/ false-negatives.
+
+Limitations
+-----------
+
+* TypeSanitizer uses more real memory than a native run. It uses 8 bytes of
+  shadow memory for each byte of user memory.
+* There are transformation passes which run before TypeSanitizer. If these 
+  passes optimize out an aliasing violation, TypeSanitizer cannot catch it.
+* Currently, all instrumentation is inlined. This can result in a **15x** 
+  (on average) increase in generated file size, and **3x** to **7x** increase 
+  in compile time. In some documented cases this can cause the compiler to hang.
+  There are plans to improve this in the future.
+* Codebases that use unions and struct-initialized variables can see incorrect 
+  results, as TypeSanitizer doesn't yet instrument these reliably.
+
+Current Status
+--------------
+
+TypeSanitizer is brand new, and still in development. There are some known 
+issues, especially in areas where clang doesn't generate valid TBAA metadata. 
+
+We are actively working on enhancing the tool --- stay tuned.  Any help, 
+issues, pull requests, ideas, is more than welcome.

fhahn

Thanks for putting this up!

fhahn · 2025-01-20T16:29:59Z

clang/docs/TypeSanitizer.rst

+
+TypeSanitizer is a detector for strict type aliasing violations. It consists of a compiler
+instrumentation module and a run-time library. The tool detects violations such as the use 
+of an illegally cast pointer, or misuse of a union.


I think this should say something about accessing memory with a different type than the dynamic type of the object or something like that?

fhahn · 2025-01-20T16:30:41Z

clang/docs/TypeSanitizer.rst

+
+The violations TypeSanitizer catches may cause the compiler to emit incorrect code.
+
+Typical slowdown introduced by TypeSanitizer is about **4x** [[CHECK THIS]]. Typical memory overhead introduced by TypeSanitizer is about **9x**. 


Might be good to just say that TypeSanitizer is still experimental and currently can have a very large runtime, memory and code size overhead :)

It also seems to have a sizable compile-time overhead.

clang/docs/TypeSanitizer.rst

fhahn · 2025-01-20T16:33:16Z

clang/docs/TypeSanitizer.rst

+
+* ``omnipotent char``: This is a special type which can alias with anything. Its name comes from the C/C++ 
+  type ``char``.
+* ``type p[x]``: Sometimes a program could generate distinct TBAA metadata that resolve to the same name. 


p2 int means int **, the number indicates the number of indirections (not sure what the best terminology would be here

Ah! My mistake, will change that

fhahn · 2025-01-20T16:34:05Z

clang/docs/TypeSanitizer.rst

+These terms are a result of non-user-facing processes, and not always self-explanatory. There is some 
+interest in changing TypeSanitizer in the future to translate these terms before printing them to users.


Might be worth just saying that it is still experimental and the user-facing error messages should be improved in the future to remove LLVM IR specific references

clang/docs/TypeSanitizer.rst

fhahn · 2025-01-20T16:35:50Z

clang/docs/TypeSanitizer.rst

+--------------
+
+TypeSanitizer is brand new, and still in development. There are some known 
+issues, especially in areas where clang doesn't generate valid TBAA metadata. 


Suggested change

issues, especially in areas where clang doesn't generate valid TBAA metadata.

issues, especially in areas where Clang doesn't generate valid TBAA metadata.

I am not sure saying Clang doesn't generate valid TBAA metadata is correct here. It may not generate TBAA metadata that TySan suspects in some cases, but what Clang emits should be conservatively correct.

Aha right, its not that it isn't valid, it just isn't descriptive/extensive enough for the sanitizer. Will change that

clang/docs/TypeSanitizer.rst

erichkeane

The language here is a little bit staccato for my taste, but its probably a good enough start. A few suggestions, else I'm happy whenever @fhahn and the others are.

clang/docs/TypeSanitizer.rst

erichkeane · 2025-01-21T15:50:56Z

clang/docs/TypeSanitizer.rst

+============
+
+TypeSanitizer is a detector for strict type aliasing violations. It consists of a compiler
+instrumentation module and a run-time library. The tool detects violations where you access 


violations of what? Would love another sentence or two here just explaining what it is detecting better. Something like (please don't use unless it is correct!):

"This tool detects violations of the strict-aliasing rule, which prohibits access of a memory location as a type that is different from the dynamic type of the object at that location."

Or something?

I added some more text based off Florian's original pitch

clang/docs/TypeSanitizer.rst

AaronBallman

Thank you for working on these docs!

clang/docs/TypeSanitizer.rst

AaronBallman · 2025-01-22T17:42:36Z

clang/docs/TypeSanitizer.rst

+Usage
+=====
+
+Compile and link your program with ``-fsanitize=type`` flag.  The


Can the type sanitizer be enabled along with other sanitizers, or is it mutually exclusive with some? (If it's mutually exclusive with some, then we should document which ones, otherwise I think the docs are fine as-is.)

From a check, I think its mutually exclusive with all of them currently. I will put this in the Limitations section

clang/docs/TypeSanitizer.rst

@fhahn

TySan supports some preprocessor checks and ignorelists, but they are currently untested. This PR adds some tests to make sure they all work. @fhahn @AaronBallman, this is based off the discussion in the documentation PR [#123595]

AaronBallman

LGTM assuming @fhahn is happy as well. Thank you for the docs!

vitalybuka · 2025-01-25T06:45:07Z

Maybe paragraph or link to a doc about how it works can be useful?
Basic understanding of algorithm may help users to avoid false expectations.

fhahn

LGTM thanks!

I think it would be great to add a paragraph or link to a doc about how it works as suggested by @vitalybuka but this could also be done as follow-up

gbMattN · 2025-01-28T12:55:03Z

I could add a link to your initial pull request? You have a decent writeup there on how it works.

fhahn · 2025-01-28T13:16:47Z

I could add a link to your initial pull request? You have a decent writeup there on how it works.

It's probably better to add a paragraph instead of linking to a PR. Of course the description can be taken from the PR

MattPD · 2025-02-04T01:42:26Z

clang/docs/TypeSanitizer.rst

+The TypeSanitizer Algorithm
+===========================
+For each TBAA type-access descriptor, encoded in LLVM IR using TBAA Metadata, the instrumentation 
+pass generates descriptor tales. Thus there is a unique pointer to each type (and access descriptor).


Small typo: s/tales/tables/

Thanks, will fix!

llvmbot added the clang Clang issues not falling into any other category label Jan 20, 2025

cor3ntin requested review from fhahn, AaronBallman and erichkeane January 20, 2025 16:08

fhahn reviewed Jan 20, 2025

View reviewed changes

gbMattN requested a review from fhahn January 20, 2025 17:05

erichkeane reviewed Jan 21, 2025

View reviewed changes

AaronBallman reviewed Jan 22, 2025

View reviewed changes

gbMattN mentioned this pull request Jan 23, 2025

[TySan] Added tests for methods of ignoring instrumentation #124125

Merged

AaronBallman approved these changes Jan 24, 2025

View reviewed changes

fhahn approved these changes Jan 28, 2025

View reviewed changes

fhahn mentioned this pull request Jan 28, 2025

[TBAA] Don't emit pointer-tbaa for void pointers. #122116

Merged

gbMattN force-pushed the users/nagym/tysan-initial-documentation branch from 33ed4a2 to a27e1b7 Compare January 28, 2025 16:18

[TySan] Add initial documentation

b9e542b

gbMattN force-pushed the users/nagym/tysan-initial-documentation branch from a27e1b7 to b9e542b Compare January 28, 2025 16:30

goussepi merged commit 822954b into llvm:main Jan 28, 2025
6 of 8 checks passed

MattPD reviewed Feb 4, 2025

View reviewed changes


		The violations TypeSanitizer catches may cause the compiler to emit incorrect code.

		Typical slowdown introduced by TypeSanitizer is about 4x [[CHECK THIS]]. Typical memory overhead introduced by TypeSanitizer is about 9x.

		These terms are a result of non-user-facing processes, and not always self-explanatory. There is some
		interest in changing TypeSanitizer in the future to translate these terms before printing them to users.

	issues, especially in areas where clang doesn't generate valid TBAA metadata.
	issues, especially in areas where Clang doesn't generate valid TBAA metadata.

[TySan] Add initial documentation for Type Sanitizer #123595

[TySan] Add initial documentation for Type Sanitizer #123595

Uh oh!

Conversation

gbMattN commented Jan 20, 2025

Uh oh!

llvmbot commented Jan 20, 2025

Uh oh!

fhahn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

erichkeane left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AaronBallman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AaronBallman left a comment

Choose a reason for hiding this comment

Uh oh!

vitalybuka commented Jan 25, 2025

Uh oh!

fhahn left a comment

Choose a reason for hiding this comment

Uh oh!

gbMattN commented Jan 28, 2025

Uh oh!

fhahn commented Jan 28, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!