You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

60 lines
1.7 KiB
C

// 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