Merge pull request #17278 from kaspar030/add_ubsan_support

make: Add ubsan support

Makefile.include

@@ -503,6 +503,9 @@ include $(RIOTMAKE)/toolchain/$(TOOLCHAIN).inc.mk
 # overriding the core ldscripts
 LINKFLAGS += -L$(RIOTBASE)/core/ldscripts
 
+# include undefined behaviour sanitizer (UBSAN) support
+include $(RIOTMAKE)/ubsan.inc.mk
+
 # Tell ccache to pass the original file to the compiler, instead of passing the
 # preprocessed code. Without this setting, the compilation will fail with
 # -Wimplicit-fallthrough warnings even when the fall through case is properly

doc/doxygen/riot.doxyfile

@@ -770,6 +770,7 @@ INPUT                  = ../../doc.txt \
                          src/using-cpp.md \
                          src/using-rust.md \
                          src/advanced-build-system-tricks.md \
+                         src/debugging-aids.md \
                          src/emulators.md \
                          src/release-cycle.md \
                          src/changelog.md \

doc/doxygen/src/debugging-aids.md

@@ -0,0 +1,48 @@
+# Debugging Tools {#debugging-tools}
+
+## Undefined Behavior Sanitizer (ubsan) {#ubsan}
+
+RIOT contains makefile convenience support for gcc/clang's undefined
+behaviour sanitizer.
+
+### Overview
+
+Both gcc and clang allow generation on code that does runtime checks for
+undefined behavior (UB).
+
+E.g., the following code might trigger UB for some parameters:
+
+```C
+void test(int foo) {
+    return (foo << 24);
+}
+```
+
+In this case, the signed shift would be alright unless:
+
+- it would "push out" all bits to the left, with undefined runtime result. Here,
+  that happens on architectures with 16-bit integers.
+- `foo` is negative, with implementation defined runtime results.
+
+Using ubsan, these can be caught at runtime.
+
+There are three modes for ubsan that define what happens when the sanitizer
+observed undefined behaviour:
+
+1. `trap` -> cause a trap
+2. `msg_exit` -> print a message and exit
+3. `msg_recover` -> print a message and continue
+
+`trap` is available on all RIOT platforms, whereas `msg_exit` and `msg_recover`
+are currently only available on `native` when building with gcc, as they require runtime support in
+the form of `libubsan`.
+
+The default is `trap`, or `msg_exit` if available (currently, on native:gnu only).
+
+
+### How to use
+
+1. build with `make all-ubsan`.
+
+2. build with `UBSAN_MODE=[trap|msg_exit|msg_recover] make all-ubsan` to
+   override the ubsan mode.

makefiles/ubsan.inc.mk

@@ -0,0 +1,36 @@
+# Copyright (C) 2019 Kaspar Schleiser <kaspar@schleiser.de>
+#
+# This file contains support for UBSan, the undefined behaviour sanitizer
+# provided by gcc and clang.
+#
+# Please see doc/doxygen/src/debugging-aids.md for more info.
+
+# trap, msg_exit, msg_recover
+UBSAN_MODE ?= msg_exit
+
+CFLAGS_UBSAN = -fsanitize=undefined
+
+ifeq (gnu,$(TOOLCHAIN))
+  ifeq (native,$(BOARD))
+    ifneq (,$(filter msg_%,$(UBSAN_MODE)))
+      LINKFLAGS_UBSAN += -lubsan
+      ifneq (msg_recover,$(UBSAN_MODE))
+        CFLAGS_UBSAN += -fno-sanitize-recover=undefined
+      endif
+    else
+      CFLAGS_UBSAN += -fsanitize-undefined-trap-on-error
+    endif
+  else
+    # on real hardware, there's currently no runtime support.
+    # so just crash when undefined behaviour is triggered.
+    CFLAGS_UBSAN += -fsanitize-undefined-trap-on-error
+  endif
+else
+  # libubsan doesn't link properly when using clang.
+  # thus when using llvm as toolchain, always generate traps.
+  CFLAGS_UBSAN += -fsanitize-trap=undefined
+endif
+
+all-ubsan: CFLAGS += $(CFLAGS_UBSAN)
+all-ubsan: LINKFLAGS += $(LINKFLAGS_UBSAN)
+all-ubsan: all