Add ThreadSanitizer usage note under Linux (#8908)

* Add ThreadSanitizer usage note under Linux --------- Co-authored-by: Max Hilbrunner <[email protected]>
godotengine · Nov 17, 2024 · feeea91 · feeea91
1 parent 5e8062d
commit feeea91
Showing 1 changed file with 34 additions and 0 deletions.
diff --git a/contributing/development/debugging/using_sanitizers.rst b/contributing/development/debugging/using_sanitizers.rst
@@ -140,6 +140,40 @@ slower, while also multiplying memory usage by an approximately 8× factor.
     the address, memory and thread sanitizers are mutually exclusive. This means
     you can only use one of those sanitizers in a given binary.
 
+.. note::
+
+    On Linux, if you stumble upon the following error:
+
+    ``FATAL: ThreadSanitizer: unexpected memory mapping``
+
+    You may need to temporarily lower the Address Space Layout Randomization (ASLR) entropy in your system with:
+
+    .. code:: sh
+
+        sudo sysctl vm.mmap_rnd_bits=28
+
+    Or preferably disable it entirely with:
+
+    .. code:: sh
+
+        sudo sysctl kernel.randomize_va_space=0
+
+    And as soon as you are done with the thread sanitizer, increase the ASLR entropy with:
+
+    .. code:: sh
+
+        sudo sysctl vm.mmap_rnd_bits=32
+
+    Or re-enable ASLR with:
+
+    .. code:: sh
+
+        sudo sysctl kernel.randomize_va_space=2
+
+    Rebooting your machine will also revert the ASLR state to its default values.
+
+    It's important to revert the changes as soon as possible because lowering the ASLR entropy or disabling ASLR entirely can be a security risk.
+
 Undefined behavior sanitizer (UBSAN)
 ------------------------------------