debug.cpp File Reference

#include "precompiled.h"
#include "lib/debug.h"
#include <cstdarg>
#include <cstring>
#include <cstdio>
#include "lib/alignment.h"
#include "lib/app_hooks.h"
#include "lib/fnv_hash.h"
#include "lib/sysdep/vm.h"
#include "lib/sysdep/cpu.h"
#include "lib/sysdep/sysdep.h"

Go to the source code of this file.

Classes
class	PrintfWriter

Enumerations
enum	SkipStatus { INVALID, VALID, BUSY }

Functions
	STATUS_ADD_DEFINITIONS (debugStatusDefinitions)
void	debug_filter_add (const wchar_t *tag)
	debug output is very useful, but "too much of a good thing can kill you". More...
void	debug_filter_remove (const wchar_t *tag)
	in future, discard output with the given tag. More...
void	debug_filter_clear ()
	clear all filter state; equivalent to debug_filter_remove for each tag that was debug_filter_add-ed. More...
bool	debug_filter_allows (const wchar_t *text)
	indicate if the given text would be printed. More...
void	debug_printf (const wchar_t *fmt,...)
	write a formatted string to the debug channel, subject to filtering (see below). More...
Status	debug_WriteCrashlog (const wchar_t *text)
	write an error description and all logs into crashlog.txt (in unicode format). More...
void	debug_FreeErrorMessage (ErrorMessageMem *emm)
	free memory from the error message. More...
const wchar_t *	debug_BuildErrorMessage (const wchar_t *description, const wchar_t *filename, int line, const char *func, void *context, const wchar_t *lastFuncToSkip, ErrorMessageMem *emm)
	build a string describing the given error. More...
void	debug_DisplayMessage (const wchar_t *caption, const wchar_t *msg)
	translates and displays the given strings in a dialog. More...
static bool	ShouldSuppressError (atomic_bool *suppress)
static ErrorReactionInternal	CallDisplayError (const wchar_t *text, size_t flags)
static ErrorReaction	PerformErrorReaction (ErrorReactionInternal er, size_t flags, atomic_bool *suppress)
ErrorReaction	debug_DisplayError (const wchar_t *description, size_t flags, void *context, const wchar_t *lastFuncToSkip, const wchar_t *pathname, int line, const char *func, atomic_bool *suppress)
	display an error dialog with a message and stack trace. More...
void	debug_SkipErrors (Status err)
	suppress (prevent from showing) the error dialog from subsequent debug_OnError for the given Status. More...
size_t	debug_StopSkippingErrors ()
static bool	ShouldSkipError (Status err)
ErrorReaction	debug_OnError (Status err, atomic_bool *suppress, const wchar_t *file, int line, const char *func)
	called when a DEBUG_WARN_ERR indicates an error occurred; notifies the user via debug_DisplayError. More...
ErrorReaction	debug_OnAssertionFailure (const wchar_t *expr, atomic_bool *suppress, const wchar_t *file, int line, const char *func)
	called when a ENSURE/ASSERT fails; notifies the user via debug_DisplayError. More...

Variables
static const StatusDefinition	debugStatusDefinitions []
static const size_t	MAX_TAGS = 20
static u32	tags [MAX_TAGS]
static size_t	num_tags
static const size_t	messageSize = 512*KiB
static atomic_bool	isExiting
static intptr_t	skipStatus = INVALID
static Status	errorToSkip
static size_t	numSkipped

Enumeration Type Documentation

enum SkipStatus

Enumerator
INVALID
VALID
BUSY

Definition at line 483 of file debug.cpp.

Function Documentation

static ErrorReactionInternal CallDisplayError ( const wchar_t *  text, size_t  flags  )

static

Definition at line 372 of file debug.cpp.

const wchar_t* debug_BuildErrorMessage	(	const wchar_t *	description,
		const wchar_t *	fn_only,
		int	line,
		const char *	func,
		void *	context,
		const wchar_t *	lastFuncToSkip,
		ErrorMessageMem *	emm
	)

build a string describing the given error.

this is a helper function used by debug_DumpStack and is made available so that the self-test doesn't have to display the error dialog.

Parameters

description,:	general description of the problem.
fn_only	filename (no path) of source file that triggered the error.
line,func,:	exact position of the error.
context,lastFuncToSkip,:	see debug_DumpStack.
emm	memory for the error message. caller should allocate stack memory and set alloc_buf*; if not, there will be no fallback in case heap alloc fails. should be freed via debug_FreeErrorMessage when no longer needed.

Definition at line 262 of file debug.cpp.

ErrorReaction debug_DisplayError	(	const wchar_t *	description,
		size_t	flags,
		void *	context,
		const wchar_t *	lastFuncToSkip,
		const wchar_t *	file,
		int	line,
		const char *	func,
		atomic_bool *	suppress
	)

display an error dialog with a message and stack trace.

Parameters

description	text to show.
flags,:	see DebugDisplayErrorFlags.
context,lastFuncToSkip,:	see debug_DumpStack.
file,line,func,:	location of the error (typically passed as WIDEN(FILE), LINE, func from a macro)
suppress	pointer to a caller-allocated flag that can be used to suppress this error. if NULL, this functionality is skipped and the "Suppress" dialog button will be disabled. note: this flag is read and written exclusively here; caller only provides the storage. values: see DEBUG_SUPPRESS above.

Returns

ErrorReaction (user's choice: continue running or stop?)

Definition at line 426 of file debug.cpp.

void debug_DisplayMessage	(	const wchar_t *	caption,
		const wchar_t *	msg
	)

translates and displays the given strings in a dialog.

this is typically only used when debug_DisplayError has failed or is unavailable because that function is much more capable. implemented via sys_display_msg; see documentation there.

Definition at line 344 of file debug.cpp.

void debug_filter_add

(

const wchar_t *

tag

)

debug output is very useful, but "too much of a good thing can kill you".

we don't want to require different LOGn() macros that are enabled depending on "debug level", because changing that entails lengthy compiles and it's too coarse-grained. instead, we require all strings to start with "tag_string|" (exact case and no quotes; the alphanumeric-only <tag_string> identifies output type). they are then subject to filtering: only if the tag has been "added" via debug_filter_add is the appendant string displayed.

this approach is easiest to implement and is fine because we control all logging code. LIMODS falls from consideration since it's not portable and too complex.

notes:

• filter changes only affect subsequent debug_*printf calls; output that didn't pass the filter is permanently discarded.
• strings not starting with a tag are always displayed.
• debug_filter_* can be called at any time and from the debugger, but are not reentrant.

in future, allow output with the given tag to proceed. no effect if already added.

Definition at line 77 of file debug.cpp.

bool debug_filter_allows

(

const wchar_t *

text

)

indicate if the given text would be printed.

useful for a series of debug_printfs - avoids needing to add a tag to each of their format strings.

Definition at line 119 of file debug.cpp.

void debug_filter_clear

(

)

clear all filter state; equivalent to debug_filter_remove for each tag that was debug_filter_add-ed.

Definition at line 114 of file debug.cpp.

void debug_filter_remove

(

const wchar_t *

tag

)

in future, discard output with the given tag.

no effect if not currently added.

Definition at line 96 of file debug.cpp.

void debug_FreeErrorMessage

(

ErrorMessageMem *

emm

)

free memory from the error message.

Parameters

emm	ErrorMessageMem*

Definition at line 209 of file debug.cpp.

ErrorReaction debug_OnAssertionFailure	(	const wchar_t *	assert_expr,
		atomic_bool *	suppress,
		const wchar_t *	file,
		int	line,
		const char *	func
	)

called when a ENSURE/ASSERT fails; notifies the user via debug_DisplayError.

Parameters

assert_expr	the expression that failed; typically passed as #expr in the assert macro.
suppress	see debug_DisplayError.
file,line	source file name and line number of the spot that failed
func	name of the function containing it

Returns

ErrorReaction (user's choice: continue running or stop?)

Definition at line 550 of file debug.cpp.

ErrorReaction debug_OnError	(	Status	err,
		atomic_bool *	suppress,
		const wchar_t *	file,
		int	line,
		const char *	func
	)

called when a DEBUG_WARN_ERR indicates an error occurred; notifies the user via debug_DisplayError.

Parameters

err	Status value indicating the error that occurred
suppress	see debug_DisplayError.
file,line	source file name and line number of the spot that failed
func	name of the function containing it

Returns

ErrorReaction (user's choice: continue running or stop?)

Definition at line 534 of file debug.cpp.

void debug_printf	(	const wchar_t *	fmt,
			...
	)

write a formatted string to the debug channel, subject to filtering (see below).

implemented via debug_puts - see performance note there.

Parameters

fmt	Format string and varargs; see printf.

Definition at line 142 of file debug.cpp.

void debug_SkipErrors

(

Status

err

)

suppress (prevent from showing) the error dialog from subsequent debug_OnError for the given Status.

rationale: for edge cases in some functions, warnings are raised in addition to returning an error code. self-tests deliberately trigger these cases and check for the latter but shouldn't cause the former. we therefore need to squelch them.

Parameters

err	the Status to skip.

note: only one concurrent skip request is allowed; call debug_StopSkippingErrors before the next debug_SkipErrors.

Definition at line 491 of file debug.cpp.

size_t debug_StopSkippingErrors

(

)

Returns

how many errors were skipped since the call to debug_SkipErrors()

Definition at line 504 of file debug.cpp.

Status debug_WriteCrashlog

(

const wchar_t *

text

)

write an error description and all logs into crashlog.txt (in unicode format).

Parameters

text	description of the error (including stack trace); typically generated by debug_BuildErrorMessage.

Returns

Status; ERR::REENTERED if reentered via recursion or multithreading (not allowed since an infinite loop may result).

Definition at line 160 of file debug.cpp.

static ErrorReaction PerformErrorReaction ( ErrorReactionInternal  er, size_t  flags, atomic_bool *  suppress  )

static

Definition at line 383 of file debug.cpp.

static bool ShouldSkipError ( Status  err )

static

Definition at line 520 of file debug.cpp.

static bool ShouldSuppressError ( atomic_bool *  suppress )

static

Definition at line 358 of file debug.cpp.

STATUS_ADD_DEFINITIONS

(

debugStatusDefinitions

)

Variable Documentation

const StatusDefinition debugStatusDefinitions[]

static

Initial value:

= {
    { ERR::SYM_NO_STACK_FRAMES_FOUND, L"No stack frames found" },
    { ERR::SYM_UNRETRIEVABLE_STATIC, L"Value unretrievable (stored in external module)" },
    { ERR::SYM_UNRETRIEVABLE, L"Value unretrievable" },
    { ERR::SYM_TYPE_INFO_UNAVAILABLE, L"Error getting type_info" },
    { ERR::SYM_INTERNAL_ERROR, L"Exception raised while processing a symbol" },
    { ERR::SYM_UNSUPPORTED, L"Symbol type not (fully) supported" },
    { ERR::SYM_CHILD_NOT_FOUND, L"Symbol does not have the given child" },
    { ERR::SYM_NESTING_LIMIT, L"Symbol nesting too deep or infinite recursion" },
    { ERR::SYM_SINGLE_SYMBOL_LIMIT, L"Symbol has produced too much output" },
    { INFO::SYM_SUPPRESS_OUTPUT, L"Symbol was suppressed" }
}

Definition at line 45 of file debug.cpp.

Status errorToSkip

static

Definition at line 488 of file debug.cpp.

atomic_bool isExiting

static

Definition at line 354 of file debug.cpp.

const size_t MAX_TAGS = 20

static

Definition at line 73 of file debug.cpp.

const size_t messageSize = 512*KiB

static

Definition at line 207 of file debug.cpp.

size_t num_tags

static

Definition at line 75 of file debug.cpp.

size_t numSkipped

static

Definition at line 489 of file debug.cpp.

intptr_t skipStatus = INVALID

static

Definition at line 487 of file debug.cpp.

u32 tags[MAX_TAGS]

static

Definition at line 74 of file debug.cpp.