[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/goussepi closed 
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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From b9e542bf4d8b8bdb4e0416cd020a9339a4800db4 Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Tue, 28 Jan 2025 16:29:59 +
Subject: [PATCH] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 205 +++
 clang/docs/UsersManual.rst   |   3 +
 clang/docs/index.rst |   1 +
 3 files changed, 209 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..8b815d8804fa8f
--- /dev/null
+++ b/clang/docs/TypeSanitizer.rst
@@ -0,0 +1,205 @@
+=
+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. It also has a large compile-time overhead. Work is 
being done to 
+reduce these impacts.
+
+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).
+These tables are comdat (except for anonymous-namespace types), so the pointer 
values are unique 
+across the program.
+
+The descriptors refer to other descriptors to form a type aliasing tree, like 
how LLVM's TBAA data 
+does.
+
+The runtime uses 8 bytes of shadow memory, the size of the pointer to the type 
descriptor, for 
+every byte of accessed data in the program. The first byte of a type will have 
its shadow memory 
+be set to the pointer to its type descriptor. Aside from that, there are some 
other values it may be.
+
+* 0 is used to represent an unknown type
+* Negative numbers represent an interior byte: A byte inside a type that is 
not the first one. As an 
+  example, a value of -2 means you are in the third byte of a type.
+
+The Instrumentation first checks for an exact match between the type of the 
current access and the 
+type for that address in the shadow memory. This can quickly be done by 
checking pointer values. If 
+it matches, it checks the remaining shadow memory of the type to ensure they 
are the correct negative 
+numbers. If this fails, it calls the "slow path" check. If the exact match 
fails, we check to see if 
+the value, and the remainder of the shadow bytes, is 0. If they are, we can 
set the shadow memory to 
+the correct type descriptor pointer for the first byte, and the correct 
negative numbers for the rest 
+of the type's shadow.
+
+If the type in shadow memory is neither an exact match nor 0, we call the 
slower runtime check. It 
+uses the full TBAA algorithm, just as the compiler does, to determine when two 
types are permitted to 
+alias.
+
+The instrumentation pass inserts calls to the memset intrinsic to set the 
memory updated by memset, 
+memcpy, and memmove, as well as allocas/byval (and for lifetime.start/end) to 
reset the shadow memory 
+to reflect that the type is now unknown. The runtime intercepts memset, 
memcpy, etc. to perform the 
+same function for the library calls.
+
+How to build
+
+
+Build LLVM/Clang with `CMake `_ 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" /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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 01/12] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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")`` t

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 01/12] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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")`` t

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

fhahn wrote:

> 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 

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

gbMattN wrote:

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

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

https://github.com/fhahn approved this pull request.

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

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Vitaly Buka via cfe-commits]

vitalybuka wrote:

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.


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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Aaron Ballman via cfe-commits]

https://github.com/AaronBallman approved this pull request.

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

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 01/11] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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")`` t

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Oliver Stöneberg via cfe-commits]

@@ -0,0 +1,153 @@
+
+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**. 

firewave wrote:

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

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

@@ -0,0 +1,153 @@
+
+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 `_ 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" /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 `. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 01/10] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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")`` t

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

@@ -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 `_ 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" /llvm
+
+Usage
+=
+
+Compile and link your program with ``-fsanitize=type`` flag.  The

gbMattN wrote:

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

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 1/9] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

@@ -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 `_ 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" /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 `. 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.
+  As an example, a pointer to a pointer to an integer would be ``type p2 int``.
+
+TypeSanitizer is still experimental. User-facing error messages should be 
improved in the future to remove 
+references to LLVM IR specific terms.
+
+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 ` 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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Aaron Ballman via cfe-commits]

@@ -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 `_ 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" /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. 

AaronBallman wrote:

```suggestion
The program will print an error message to ``stderr`` each time a strict 
aliasing violation is detected. 
```

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Aaron Ballman via cfe-commits]

https://github.com/AaronBallman commented:

Thank you for working on these docs!

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Aaron Ballman via cfe-commits]

@@ -0,0 +1,162 @@
+
+TypeSanitizer
+

AaronBallman wrote:

```suggestion
=
TypeSanitizer
=
```

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Aaron Ballman via cfe-commits]

@@ -0,0 +1,153 @@
+
+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 `_ 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" /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 `. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Aaron Ballman via cfe-commits]

@@ -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 `_ 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" /llvm
+
+Usage
+=
+
+Compile and link your program with ``-fsanitize=type`` flag.  The

AaronBallman wrote:

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.)

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Aaron Ballman via cfe-commits]

@@ -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 `_ 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" /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 `. 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.
+  As an example, a pointer to a pointer to an integer would be ``type p2 int``.
+
+TypeSanitizer is still experimental. User-facing error messages should be 
improved in the future to remove 
+references to LLVM IR specific terms.
+
+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 ` 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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Aaron Ballman via cfe-commits]

@@ -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 `_ 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" /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 `. 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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Aaron Ballman via cfe-commits]

https://github.com/AaronBallman edited 
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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

@@ -0,0 +1,156 @@
+
+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 
where you access 

gbMattN wrote:

I added some more text based off Florian's [original 
pitch](https://reviews.llvm.org/D32198)

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 1/8] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 1/7] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Erich Keane via cfe-commits]

https://github.com/erichkeane edited 
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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Erich Keane via cfe-commits]

@@ -0,0 +1,156 @@
+
+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 
where you access 

erichkeane wrote:

`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?  

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Erich Keane via cfe-commits]

@@ -0,0 +1,156 @@
+
+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 
where you access 
+memory under a different type than the dynamic type of the object.
+
+The violations TypeSanitizer catches may cause the compiler to emit incorrect 
code.
+
+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 `_ 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" /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`` 

erichkeane wrote:

```suggestion
TypeSanitizer by default doesn't print the full stack trace in error messages. 
Use ``TYSAN_OPTIONS=print_stacktrace=1`` 
```

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Erich Keane via cfe-commits]

@@ -0,0 +1,156 @@
+
+TypeSanitizer
+
+
+.. contents::
+   :local:
+
+Introduction
+
+
+TypeSanitizer is a detector for strict type aliasing violations. It consists 
of a compiler

erichkeane wrote:

```suggestion
The TypeSanitizer is a detector for strict type aliasing violations. It 
consists of a compiler
```

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Erich Keane via cfe-commits]

https://github.com/erichkeane commented:

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.

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 1/6] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

@@ -0,0 +1,153 @@
+
+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 `_ 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" /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 `. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

@@ -0,0 +1,153 @@
+
+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 `_ 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" /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 `. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

@@ -0,0 +1,153 @@
+
+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 `_ 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" /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 `. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

@@ -0,0 +1,153 @@
+
+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 `_ 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" /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 `. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

@@ -0,0 +1,153 @@
+
+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 `_ 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" /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 `. 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. 

gbMattN wrote:

Ah! My mistake, will change that

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

@@ -0,0 +1,153 @@
+
+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 `_ 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" /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 `. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 1/5] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

@@ -0,0 +1,153 @@
+
+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 `_ 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" /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 `. 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. 

fhahn wrote:

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

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

@@ -0,0 +1,153 @@
+
+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 `_ 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" /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. 

fhahn wrote:

```suggestion
The program will print an error message to stderr each time a strict aliasing 
violation is detected. 
```

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

@@ -0,0 +1,153 @@
+
+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 `_ 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" /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 `. 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.

fhahn wrote:

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

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

https://github.com/fhahn edited 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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

@@ -0,0 +1,153 @@
+
+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.

fhahn wrote:

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

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

@@ -0,0 +1,153 @@
+
+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**. 

fhahn wrote:

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

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[Florian Hahn via cfe-commits]

https://github.com/fhahn commented:

Thanks for putting this up!

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

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 1/4] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN updated 
https://github.com/llvm/llvm-project/pull/123595

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 1/3] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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 

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

llvmbot wrote:




@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
diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..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 `_ 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" /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 `. 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 ` 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-negati

[clang] [TySan] Add initial documentation for Type Sanitizer (PR #123595)

[via cfe-commits]

https://github.com/gbMattN created 
https://github.com/llvm/llvm-project/pull/123595

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

>From 807c2c8be0517cbb1b9db890f48baeb6f226ba2f Mon Sep 17 00:00:00 2001
From: gbMattN 
Date: Mon, 20 Jan 2025 11:02:06 +
Subject: [PATCH 1/2] [TySan] Add initial documentation

---
 clang/docs/TypeSanitizer.rst | 152 +++
 1 file changed, 152 insertions(+)
 create mode 100644 clang/docs/TypeSanitizer.rst

diff --git a/clang/docs/TypeSanitizer.rst b/clang/docs/TypeSanitizer.rst
new file mode 100644
index 00..6b320f3bb1773d
--- /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 `_ 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" /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 
+(`This may currently lead to false-negatives 
`). 
+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. 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 ` 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 TypeSani