kaspar/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2025-12-15 17:43:51 +01:00
Code Releases Activity

doc/guides: migrate debugging aids

Browse Source 
Co-authored-by: crasbe <crasbe@gmail.com>
This commit is contained in:
AnnsAnn 2025-09-17 17:51:37 +02:00
parent d0acf6c08b
commit ebe71d1ee7
2 changed files with 54 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
doc/doxygen/src/debugging-aids.md
View File

@ -1,48 +1,4 @@
# Debugging Tools {#debugging-tools}
# Debugging Tools (Deprecated) {#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.
@deprecated Guides have moved to the [Guide Site](https://guide.riot-os.org/build-system/debugging_aids/).
This page will be removed after release 2026.04.

51
doc/guides/build-system/debugging_aids.md Normal file
View File

@ -0,0 +1,51 @@
---
title: Debugging Tools
description: Overview of debugging tools supported in RIOT-OS
---
## Undefined Behavior Sanitizer (ubsan)
RIOT contains Makefile convenience support for gcc/clang's undefined
behaviour sanitizer.
### Overview
Both gcc and clang allow generation of 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-specific 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.