84

In MSVC, DebugBreak() or __debugbreak cause a debugger to break. On x86 it is equivalent to writing "_asm int 3", on x64 it is something different. When compiling with gcc (or any other standard compiler) I want to do a break into debugger, too. Is there a platform independent function or intrinsic? I saw the XCode question about that, but it doesn't seem portable enough.

Sidenote: I mainly want to implement ASSERT with that, and I understand I can use assert() for that, but I also want to write DEBUG_BREAK or something into the code.

Community
  • 1
  • 1
vividos
  • 6,468
  • 9
  • 43
  • 53

11 Answers11

66

A method that is portable to most POSIX systems is:

raise(SIGTRAP);
caf
  • 233,326
  • 40
  • 323
  • 462
40

I just added a module to portable-snippets (a collection of public domain snippets of portable code) to do this. It's not 100% portable, but it should be pretty robust:

  • __builtin_debugtrap for some versions of clang (identified with __has_builtin(__builtin_debugtrap))
  • On MSVC and Intel C/C++ Compiler: __debugbreak
  • For ARM C/C++ Compiler: __breakpoint(42)
  • For x86/x86_64, assembly: int3
  • For ARM Thumb, assembly: .inst 0xde01
  • For ARM AArch64, assembly: .inst 0xd4200000
  • For other ARM, assembly: .inst 0xe7f001f0
  • For Alpha, assembly: bpt
  • For non-hosted C with GCC (or something which masquerades as it), __builtin_trap
  • Otherwise, include signal.h and
    • If defined(SIGTRAP) (i.e., POSIX), raise(SIGTRAP)
    • Otherwise, raise(SIGABRT)

In the future the module in portable-snippets may expand to include other logic and I'll probably forget to update this answer, so you should look there for updates. It's public domain (CC0), so feel free to steal the code.

nemequ
  • 16,623
  • 1
  • 43
  • 62
  • 1
    For x86 (including x86-64) GAS syntax, it's better to write `int3` to make it explicit that you want the special case debug-break instruction, one byte `CC` not `CD 03`, for the rare cases where that matter (code size, and v8086 mode). (https://www.felixcloutier.com/x86/intn:into:int3:int1). With NASM they actually assemble differently, GAS optimizes both to `int3`. – Peter Cordes Aug 26 '20 at 07:28
  • `__builtin_trap` typically compiles to `ud2` (x86) or other illegal instruction, not a debug breakpoint, and is also treated noreturn you can't continue after it even with a debugger. It does not belong in this list. e.g. there's no `ret` instruction after the `ud2` in a simple function that uses it before a C `return x` statement. – Peter Cordes Aug 26 '20 at 07:32
  • Thanks @PeterCordes, I have updated both this answer and my code to use `int3`. FWIW, both GCC and clang generate `int3`, too (at least with -O3), which is what really matters here since it's about C++ not assembly. It sounds like `int3` is more correct, though, so no reason not to "fix" it :) – nemequ Aug 29 '20 at 01:16
  • For `__debug_trap`, I'm not sure there is really anything that can be done here. In both the comment and the linked code it is deep in fallback territory, only called if everything else has failed *and* it's a non-hosted environment (in which case signal.h won't be available). AFAICT alternative is either nothing or a compile-time error. If you have a suggestion about other possible alternatives I'd certainly be open; I agree that it's sub-optimal (hence its position as the last resort). – nemequ Aug 29 '20 at 01:22
  • 1
    `-O3` should be irrelevant, even for clang's built-in assembler. That's the optimization level in translating C++ to asm. Asm to machine code (including for asm coming from an `asm("")` template string) is a truly separate process for gcc, and logically separate for clang. But yes, `int3` is a good idea; that's how `0xCC` disassembles, and it's a more accurate representation of what you want. – Peter Cordes Aug 29 '20 at 01:23
  • Clang `__debug_trap` should be fine. The 2nd comment was about GNU C `__builtin_trap`. Depending on the use case (whether you want to be able to continue after), a compile time error like `#error "FIXME: implement psnip_trap with inline asm for your ISA"` would be more appropriate than an illegal instruction that compilers treat as noreturn. Maybe you'd want fallback to GNUC `__builtin_trap` to be optional, controlled by a macro that can be defined, perhaps on by default if the intended use-case is for something like assert. – Peter Cordes Aug 29 '20 at 01:29
  • Did you have a look at `__asm__("bkpt #0");` / `__asm__("brk #0");` / __asm__("BKPT 0")? If my quick reading on those are correct they are reasonable for ARM and some "embedded" chips. – Simon Sobisch Dec 15 '21 at 21:23
19

What about defining a conditional macro based on #ifdef that expands to different constructs based on the current architecture or platform.

Something like:

#ifdef _MSC_VER
#define DEBUG_BREAK __debugbreak()
#else
...
#endif

This would be expanded by the preprocessor the correct debugger break instruction based on the platform where the code is compiled. This way you always use DEBUG_BREAK in your code.

Jorge Ferreira
  • 96,051
  • 25
  • 122
  • 132
15

GCC has a builtin function named __builtin_trap which you can see here, however it is assumed that code execution halts once this is reached.

you should ensure that the __builtin_trap() call is conditional, otherwise no code will be emitted after it.

this post fueled by all of 5 minutes of testing, YMMV.

Hasturkun
  • 35,395
  • 6
  • 71
  • 104
  • 4
    `__builtin_trap` typically compiles to `ud2` (x86) or other illegal instruction, not a debug breakpoint, and is also treated noreturn you can't continue after it even with a debugger. – Peter Cordes Aug 26 '20 at 07:31
14

This looks like an appropriate compat library https://github.com/scottt/debugbreak

pixelbeat
  • 30,615
  • 9
  • 51
  • 60
6

This seems to be a very good, portable solution to this question: https://github.com/scottt/debugbreak

The header provided in the repository cited (debugbreak.h) encapsulates MSVC's

    __debugbreak,

and 

    __asm__ volatile("int $0x03");

on i386 and x86_64, and on ARM it implements

    __asm__ volatile(".inst 0xe7f001f0");

as well as documenting some workarounds for problems noted in the header for single-stepping past the breakpoint in GDB plus a Python script for extending GDB on those platforms where stepi or cont get stuck. The script adds debugbreak-step and debugbreak-continue to GDB.

QwazyWabbit
  • 149
  • 2
  • 6
3

If you consider assert(x) portable enough, assert(false) seems to be the obvious portable solution to your problem.

Suma
  • 33,181
  • 16
  • 123
  • 191
  • 5
    Good in most cases but not so helpful in release code. Yeah, sometimes I have to debug release code... –  Oct 25 '11 at 13:54
  • 6
    `assert` is not a suitable solution at all since it typically does not allow program to continue executing. – user7860670 Jan 03 '20 at 08:57
0

If you are trying to debug a crash-related condition, good old fashioned abort() will give you a call stack on most platforms. Downside is that you can't continue from the current PC, which you probably don't want to do anyway.

http://www.cplusplus.com/reference/cstdlib/abort/

johnwbyrd
  • 3,432
  • 2
  • 29
  • 25
0

FWIW, none of these solutions worked on a nRF9160 using the NRF Connect SDK. That's a SEGGER Embedded Studio for ARM (Nordic Edition) environment, using the arm-none-eabi-gcc compiler.

The debug-trap.h, debugbreak.h and __builtin_trap() mentioned in other answers all resulted in "undefined opcode" and a hard-fault (or a debug monitor fault, but the result is the same) and there no useful program counter, stack frame or other debuggable information.

In the end, this alternate did work. I derived it from some other mysterious Nordic library, where it is referred to as NRF_BREAKPOINT:

#if defined(__GNUC__)
    __asm__("BKPT 0");
#else
    __BKPT(0)
#endif

At build time, it is the __GNUC__ path which gets included, so __asm__("BKPT 0") is all that is required.

Heath Raftery
  • 3,643
  • 17
  • 34
-7

Instead of using 'normal' debug breaks, why not use one of the following, like a divide by zero:

int iCrash = 13 / 0;

or dereference a NULL pointer:

BYTE bCrash = *(BYTE *)(NULL);

At least this is portable accross many platforms/architectures.

In many debuggers you can specify what action you want to perform on what exceptions so you can act accordingly when one of the above is hit (like pause execution, ala an "int 3" instruction) and an exception is generated.

QAZ
  • 4,870
  • 6
  • 36
  • 50
  • 10
    I actually have a board here that will happily do a NULL pointer dereference. divide by zero may be safer. – Hasturkun Oct 06 '08 at 09:24
  • Interesting. How would continue from such exception when it hits? With int 3 the VS debugger knows how to continue, all I need is to press Go (F5), or if I want to disable the assert on that location, I can use the trick http://stackoverflow.com/questions/115237 - anything similar here? – Suma Oct 06 '08 at 10:38
  • 8
    Dereferencing NULL (== 0) is not actually an error on most embedded systems, since address 0 is usually a real memory location. On an ARM core, it's the vector table. – Mark Lakata Jun 26 '13 at 21:41
  • 4
    DO AVOID THIS SOLUTION METHOD. It's an incredible security risk, it leaves the stack in an inconsistent state and depending on the application it can be used for exploits! – koda Mar 19 '14 at 10:01
-8
#define __debugbreak() \
do \
{       static bool b; \
        while (!b) \
                sleep(1); \
        b = false; \
} while (false)

When the process is sleeping, you can attach a debugger to the process, change the variable b to break the loop and do your thing. This code might not work in an optimized build!

  • 1
    this is the only solution which allows one to attach a debugger to the process blocked in the debugbreak() -- the rest of the solutions all cause the program to abort. –  Dec 11 '20 at 18:09