From e5b76b3fb1b7dcb2885065703936a1fb10c50106 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9ophile=20Bastian?= Date: Fri, 6 Apr 2018 16:51:55 +0200 Subject: [PATCH] Update documentation accordingly --- Doxyfile | 2 +- include/dwarfinterpret/DwarfInterpret.hpp | 36 +++++++++++++++++++++-- src/DwarfInterpret.cpp | 5 ---- 3 files changed, 35 insertions(+), 8 deletions(-) diff --git a/Doxyfile b/Doxyfile index e486aa5..3ac33e8 100644 --- a/Doxyfile +++ b/Doxyfile @@ -791,7 +791,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = "include/" "src/" +INPUT = "include/dwarfinterpret/" "src/" # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/include/dwarfinterpret/DwarfInterpret.hpp b/include/dwarfinterpret/DwarfInterpret.hpp index 1a9bd44..014a1dd 100644 --- a/include/dwarfinterpret/DwarfInterpret.hpp +++ b/include/dwarfinterpret/DwarfInterpret.hpp @@ -92,7 +92,14 @@ class DwarfInterpret { typedef uintptr_t reg_content_t; - /// An unwind context, holding registers + /** An unwind context, holding registers. + * + * The registers kept here should be enough for most of the unwinding + * processes. To fully emulate libunwind, we would have to save every + * register that is overwritten and not caller-saved. + * + * You'll most probably want to instanciate such a structure using + * #DwarfInterpret::get_current_unwind_context. */ struct UnwindContext { // Let's pretend this is enough uintptr_t rip; @@ -137,7 +144,32 @@ class DwarfInterpret { const UnwindContext& ctx ) const; - /// Get the current UnwindContext (from the caller's point of view) + /** Get the current UnwindContext (from the caller's point of view) + * + * **WARNING!** This context will be valid within the call frame of the + * caller, and within descendant calls from this function, but will + * most probably be invalid and result in weird behaviours if there is + * only a single `return` made! + * + * This is supposed to work: + * ``` + * void foo() { + * UnwindContext context = get_current_unwind_context(); + * // have fun with context + * } + * ``` + * + * While this will probably crash: + * ``` + * UnwindContext wrap_get_context() { + * return f(get_current_unwind_context()); + * } + * void foo() { + * UnwindContext context = wrap_get_context(); + * // have fun with context + * } + * ``` + */ static UnwindContext get_current_unwind_context(); /// Unwinds once the given context diff --git a/src/DwarfInterpret.cpp b/src/DwarfInterpret.cpp index a2a733f..cd676b0 100644 --- a/src/DwarfInterpret.cpp +++ b/src/DwarfInterpret.cpp @@ -189,11 +189,6 @@ DwarfInterpret::reg_content_t DwarfInterpret::interpret_dw_register( } DwarfInterpret::UnwindContext DwarfInterpret::get_current_unwind_context() { - // FIXME for now this returns SOME unwind context (actually, the unwind - // context snapshot naively taken from inside this function). Unwinding - // it some number of times should yield the expected context - - UnwindContext ctx; get_cpu_register(REG_RIP, ctx.rip); get_cpu_register(REG_RSP, ctx.rsp);