60 lines
1.7 KiB
C
Executable File
60 lines
1.7 KiB
C
Executable File
// SPDX-License-Identifier: LGPL-3.0-or-later
|
|
|
|
/**
|
|
* \file sys/dbg.h
|
|
*
|
|
* Debugging utilities to retrieve stack trace and symbol names.
|
|
*
|
|
* \copyright The DoubleFourteen Code Forge (C) All Rights Reserved
|
|
* \author Lorenzo Cogotti
|
|
*/
|
|
|
|
#ifndef DF_SYS_DBG_H_
|
|
#define DF_SYS_DBG_H_
|
|
|
|
#include "sys/con.h"
|
|
|
|
/// Helper union to cast `void *` to function pointer - be sad if you use it.
|
|
typedef union {
|
|
void *sym; ///< Function as a `void *`
|
|
void (*func)(void); ///< Function pointer.
|
|
} Funsym;
|
|
|
|
STATIC_ASSERT(sizeof(void *) == sizeof(void (*)(void)), "Ill-formed Funsym for target platform");
|
|
|
|
/// Test whether the current process is being executed under a debugger.
|
|
Boolean Sys_IsDebuggerPresent(void);
|
|
/**
|
|
* \brief Get a symbol's name, if available.
|
|
*
|
|
* \param [in] sym Symbol whose name is needed.
|
|
*
|
|
* \return A pointer to a statically allocated thread-local buffer containing
|
|
* a `\0` terminated symbol name on success, `NULL` if no name could be
|
|
* retrieved.
|
|
*/
|
|
char *Sys_GetSymbolName(void *sym);
|
|
/**
|
|
* \brief Dump at most `n` backtrace entries to `dest`.
|
|
*
|
|
* Returned backtrace does not include `Sys_GetBacktrace()`
|
|
* itself, and has the caller as the topmost symbol.
|
|
*
|
|
* \return Number of entries actually returned to `dest` on success,
|
|
* 0 when no backtrace information is available.
|
|
*/
|
|
size_t Sys_GetBacktrace(void **dest, size_t n);
|
|
/**
|
|
* \brief Get the caller's caller.
|
|
*
|
|
* Useful for quick debugging:
|
|
* ```c
|
|
* printf("Called by: %s\n", Sys_GetSymbolName(Sys_GetCaller()));
|
|
* ```
|
|
*/
|
|
void *Sys_GetCaller(void);
|
|
/// Dump backtrace to console (typically `STDERR`).
|
|
void Sys_DumpBacktrace(ConHn hn, void **trace, size_t n);
|
|
|
|
#endif
|