Callstack tracing and debugging features. More...

#include "gate/gate_core_api.h"
#include "gate/gatetypes.h"

Classes
struct	gate_callstack_context_class
	Data storage to hold context registers for callstack switches. More...

struct	gate_callstack_jmpbuf_class
	Data storage to holds the context of a forked execution path. More...

Macros
#define	GATE_CALLSTACK_CONTEXT_ITEM_COUNT 128

#define	GATE_CALLSTACK_JMPBUF_LENGTH 128

Typedefs
typedef void *	gate_callstack_address_t

typedef struct gate_callstack_context_class	gate_callstack_context_t
	Data storage to hold context registers for callstack switches.

typedef struct gate_callstack_jmpbuf_class	gate_callstack_jmpbuf_t
	Data storage to holds the context of a forked execution path.

Functions
GATE_CORE_API gate_result_t	gate_callstack_trace (gate_callstack_address_t addresses, gate_size_t addresses_count, gate_size_t addresses_used)
	stores function addresses of the current callstack chain

GATE_CORE_API gate_result_t	gate_callstack_print (gate_callstack_address_t address, char buffer, gate_size_t buffer_length, gate_size_t buffer_used)
	print the symbol name of a function address

GATE_CORE_API gate_result_t	gate_callstack_create (gate_size_t stacksize, void *ptr_callstack)
	allocates memory where a new callstack context can be executed

GATE_CORE_API gate_result_t	gate_callstack_destroy (void *ptr_callstack, gate_size_t stacksize)
	deallocates callstack memory allocated with gate_callstack_create

GATE_CORE_API gate_result_t	gate_callstack_run (void ptr_callstack, gate_size_t stacksize, gate_callstack_context_t ptr_caller_ctx_to_save, gate_entrypoint_t entry_func, void param, gate_result_t ptr_returnvalue)
	invokes an entry function on a new allocated callstack

GATE_CORE_API gate_result_t	gate_callstack_switch (gate_callstack_context_t current_to_save, gate_callstack_context_t next_to_load)
	stores current callstack and switches to a previously stored context to continue execution

GATE_CORE_API gate_result_t	gate_callstack_fork (gate_callstack_jmpbuf_t jmpbuffer, gate_entrypoint_t entry, void param, gate_entrypoint_t branch, void *branch_param)
	invokes an entry function and prepares the execution of alternate branch to which a jump can be made

GATE_CORE_API void	gate_callstack_jump (gate_callstack_jmpbuf_t *jmpbuffer)
	jumps to an alternate branch function

Detailed Description

Callstack tracing and debugging features.

Function Documentation

◆ gate_callstack_create()

GATE_CORE_API gate_result_t gate_callstack_create	(	gate_size_t *	stacksize,
		void **	ptr_callstack )

allocates memory where a new callstack context can be executed

Parameters

[in,out]	stacksize	pointer to size of new requested callstack in bytes, will be filled with real allocated stacksize on return
[out]	ptr_callstack	pointer that receives the address of the begin of new callstack

Returns: GATE_RESULT_* result code

◆ gate_callstack_destroy()

GATE_CORE_API gate_result_t gate_callstack_destroy	(	void *	ptr_callstack,
		gate_size_t	stacksize )

deallocates callstack memory allocated with gate_callstack_create

Parameters

[in]	ptr_callstack	callstack pointer to be deallocated
[in]	stacksize	original callstack size (which was used in gate_callstack_create)

Returns: GATE_RESULT_* result code

◆ gate_callstack_fork()

GATE_CORE_API gate_result_t gate_callstack_fork	(	gate_callstack_jmpbuf_t *	jmpbuffer,
		gate_entrypoint_t	entry,
		void *	param,
		gate_entrypoint_t	branch,
		void *	branch_param )

invokes an entry function and prepares the execution of alternate branch to which a jump can be made

forks are an abstraction of std-C setjmp()

Parameters

[out]	jmpbuffer	pointer to storage that saves the context to be jumped to
[in]	entry	entry function of default branch to be executed
[in]	param	parameter to be used in default entry function
[in]	branch	alternate branch function that can be used to jump to
[in]	branch_param	parameter to be used in alternate branch function

Returns: result code of entry function (when no jump occurred) or branch function (when jump occurred)

◆ gate_callstack_jump()

GATE_CORE_API void gate_callstack_jump ( gate_callstack_jmpbuf_t * jmpbuffer )

jumps to an alternate branch function

fork-jumps are an abstraction of std-C longjmp()

Parameters

[in] jmpbuffer pointer to storage of saved context to jump to

◆ gate_callstack_print()

GATE_CORE_API gate_result_t gate_callstack_print	(	gate_callstack_address_t	address,
		char *	buffer,
		gate_size_t	buffer_length,
		gate_size_t *	buffer_used )

print the symbol name of a function address

Parameters

[in]	address	address to be printed
[out]	buffer	pointer to buffer to be filled with symbol name
[in]	buffer_length	capacity of buffer
[out]	buffer_used	pointer to receive amount of name characters

Returns: GATE_RESULT_* result code

◆ gate_callstack_run()

GATE_CORE_API gate_result_t gate_callstack_run	(	void *	ptr_callstack,
		gate_size_t	stacksize,
		gate_callstack_context_t *	ptr_caller_ctx_to_save,
		gate_entrypoint_t	entry_func,
		void *	param,
		gate_result_t *	ptr_returnvalue )

invokes an entry function on a new allocated callstack

Parameters

[in]	ptr_callstack	callstack pointer of allocated callstack
[in]	stacksize	size of callstack in bytes (used in gate_collstack_create)
[out]	ptr_caller_ctx_to_save	pointer to context storage, where the callers context is stored
[in]	entry_func	pointer to entry function to be executed
[in]	param	parameter to be used in entry function
[out]	ptr_returnvalue	pointer that receives the returnvalue of entry_func when it returns

Returns: GATE_RESULT_* result code

◆ gate_callstack_switch()

GATE_CORE_API gate_result_t gate_callstack_switch	(	gate_callstack_context_t *	current_to_save,
		gate_callstack_context_t *	next_to_load )

stores current callstack and switches to a previously stored context to continue execution

Parameters

[out]	current_to_save	pointer to storage that saves the current context
[in]	next_to_load	pointer to storage thats context is loaded and resumed

Returns: GATE_RESULT_* result code

◆ gate_callstack_trace()

GATE_CORE_API gate_result_t gate_callstack_trace	(	gate_callstack_address_t *	addresses,
		gate_size_t	addresses_count,
		gate_size_t *	addresses_used )

stores function addresses of the current callstack chain

Parameters

[out]	addresses	pointer to address array to be filled
[in]	addresses_count	capacity of addresses array
[out]	addresses_used	pointer to store amount of filled addresses

Returns: GATE_RESULT_* result code

Classes

Macros

Typedefs

Functions

Detailed Description

Function Documentation

◆ gate_callstack_create()

◆ gate_callstack_destroy()

◆ gate_callstack_fork()

◆ gate_callstack_jump()

◆ gate_callstack_print()

◆ gate_callstack_run()

◆ gate_callstack_switch()

◆ gate_callstack_trace()