lws-backtrace.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	lws_backtrace_info_t
struct	lws_backtrace_comp_t

Macros
#define	_lws_alloc_metadata_dump_lws(_a, _b)

Functions
LWS_VISIBLE LWS_EXTERN int	lws_backtrace (lws_backtrace_info_t *si, uint8_t pre, uint8_t post)
LWS_VISIBLE LWS_EXTERN void	lws_backtrace_compression_stream_init (lws_backtrace_comp_t *c, uint8_t *comp, size_t comp_len)
LWS_VISIBLE LWS_EXTERN int	lws_backtrace_compression_stream (lws_backtrace_comp_t *c, uintptr_t v, unsigned int bits)
LWS_VISIBLE LWS_EXTERN int	lws_backtrace_compression_destream (lws_backtrace_comp_t *c, uintptr_t *_v, unsigned int bits)
LWS_VISIBLE LWS_EXTERN int	lws_backtrace_compress_backtrace (lws_backtrace_info_t *si, lws_backtrace_comp_t *c)
LWS_VISIBLE LWS_EXTERN void	lws_alloc_metadata_gen (size_t size, uint8_t *comp, size_t comp_len, size_t *adj, size_t *cl)
LWS_VISIBLE LWS_EXTERN void	_lws_alloc_metadata_adjust (lws_dll2_owner_t *active, void **v, size_t adj, uint8_t *comp, unsigned int cl)
LWS_VISIBLE LWS_EXTERN void	_lws_alloc_metadata_trim (void **ptr, uint8_t **comp, uint16_t *complen)
LWS_VISIBLE LWS_EXTERN int	lws_alloc_metadata_parse (lws_backtrace_info_t *si, const uint8_t *adjusted_alloc)
LWS_VISIBLE LWS_EXTERN int	lws_alloc_metadata_dump_stdout (struct lws_dll2 *d, void *user)
LWS_VISIBLE LWS_EXTERN void	_lws_alloc_metadata_dump (lws_dll2_owner_t *active, lws_dll2_foreach_cb_t cb, void *arg)

---

Data Structure Documentation

lws_backtrace_info_t

struct lws_backtrace_info_t

Definition at line 37 of file lws-backtrace.h.

Collaboration diagram for lws_backtrace_info_t:

Data Fields
uintptr_t	st[32]
uintptr_t	asize
uint8_t	sp
uint8_t	pre
uint8_t	post

lws_backtrace_comp_t

struct lws_backtrace_comp_t

Definition at line 46 of file lws-backtrace.h.

Collaboration diagram for lws_backtrace_comp_t:

Data Fields
uint8_t *	comp
size_t	pos
size_t	len

Macro Definition Documentation

_lws_alloc_metadata_dump_lws

#define _lws_alloc_metadata_dump_lws	(		_a,
			_b
	)

Definition at line 277 of file lws-backtrace.h.

Function Documentation

lws_backtrace()

LWS_VISIBLE LWS_EXTERN int lws_backtrace	(	lws_backtrace_info_t *	si,
		uint8_t	pre,
		uint8_t	post
	)

lws_backtrace_compression_stream_init()

LWS_VISIBLE LWS_EXTERN void lws_backtrace_compression_stream_init	(	lws_backtrace_comp_t *	c,
		uint8_t *	comp,
		size_t	comp_len
	)

lws_backtrace_compression_stream()

LWS_VISIBLE LWS_EXTERN int lws_backtrace_compression_stream	(	lws_backtrace_comp_t *	c,
		uintptr_t	v,
		unsigned int	bits
	)

lws_backtrace_compression_destream()

LWS_VISIBLE LWS_EXTERN int lws_backtrace_compression_destream	(	lws_backtrace_comp_t *	c,
		uintptr_t *	_v,
		unsigned int	bits
	)

lws_backtrace_compress_backtrace()

LWS_VISIBLE LWS_EXTERN int lws_backtrace_compress_backtrace	(	lws_backtrace_info_t *	si,
		lws_backtrace_comp_t *	c
	)

lws_alloc_metadata_gen()

LWS_VISIBLE LWS_EXTERN void lws_alloc_metadata_gen	(	size_t	size,
		uint8_t *	comp,
		size_t	comp_len,
		size_t *	adj,
		size_t *	cl
	)

lws_alloc_metadata_gen() - generate metadata blob (with compressed backtrace)

Parameters

size	the allocation size
comp	buffer for compressed backtrace
comp_len	number of bytes available in the compressed backtrace
adj	takes the count of additional bytes needed for metadata behind the allocation we tell the user about
cl	takes the count of bytes used in comp

This helper creates the compressed part of the alloc metadata blob and calculates the total overallocation that is needed in adj.

This doesn't need any locking.

If comp_len is too small for the whole result, or it was not possible to get the backtrace information, the compressed part is set to empty (total length 2 to carry the 00 00 length).

6 or 10 (64-bit) bytes per backtrace IP allowed (currently 16) should always be enough, typically the compression reduces this very significantly.

_lws_alloc_metadata_adjust()

LWS_VISIBLE LWS_EXTERN void _lws_alloc_metadata_adjust	(	lws_dll2_owner_t *	active,
		void **	v,
		size_t	adj,
		uint8_t *	comp,
		unsigned int	cl
	)

_lws_alloc_metadata_adjust() - helper to inject metadata and list as active

Parameters

active	the allocation owner
v	Original, true allocation pointer, adjusted on exit
adj	Total size of metadata overallocation
comp	The compressed metadata
cl	takes the count of bytes used in comp

THIS MUST BE LOCKED BY THE CALLER IF YOUR ALLOCATOR MAY BE CALLED BY OTHER THREADS. You can call it from an existing mutex or similar -protected critical section in your allocator if there is one already, or you will have to protect the caller of it with your own mutex so it cannot reenter.

This is a helper that adjusts the allocation past the metadata part so the caller of the allocator using this sees what he asked for. The deallocator must call _lws_alloc_metadata_trim() to balance this before actual deallocation.

_lws_alloc_metadata_trim()

LWS_VISIBLE LWS_EXTERN void _lws_alloc_metadata_trim	(	void **	ptr,
		uint8_t **	comp,
		uint16_t *	complen
	)

_lws_alloc_metadata_trim() - helper to trim metadata and remove from active

Parameters

ptr	Adjusted allocation pointer on entry, true allocation ptr on exit
comp	NULL, or set on exit to point to start of compressed area
complen	NULL, or set on exit to length of compressed area in bytes

THIS MUST BE LOCKED BY THE CALLER IF YOUR DEALLOCATOR MAY BE CALLED BY OTHER THREADS. You can call it from an existing mutex or similar -protected critical section in your deallocator if there is one already, or you will have to protect that caller of it with your own mutex so it cannot reenter.

lws_alloc_metadata_parse()

LWS_VISIBLE LWS_EXTERN int lws_alloc_metadata_parse	(	lws_backtrace_info_t *	si,
		const uint8_t *	adjusted_alloc
	)

lws_alloc_metadata_parse() - parse compressed metadata into struct

Parameters

si	Struct to take the backtrace results from decompression
adjusted_alloc	pointer to adjusted, user allocation start

This api parses and decompresses the blob behind the adjusted_alloc address into si.

Returns 0 for success.

lws_alloc_metadata_dump_stdout()

LWS_VISIBLE LWS_EXTERN int lws_alloc_metadata_dump_stdout	(	struct lws_dll2 *	d,
		void *	user
	)

lws_alloc_metadata_dump_stdout() - helper to print base64 blob on stdout

Parameters

d	the current list item
user	the optional arg given to the dump api (ignored)

Generic helper that can be given to _lws_alloc_metadata_dump() as the callback that will emit a standardized base64 blob for the alloc metadata

_lws_alloc_metadata_dump()

LWS_VISIBLE LWS_EXTERN void _lws_alloc_metadata_dump	(	lws_dll2_owner_t *	active,
		lws_dll2_foreach_cb_t	cb,
		void *	arg
	)

lws_alloc_metadata_dump_stdout() - dump all live allocs in instrumented heap

Parameters

active	the owner of the active allocation list for this heap
cb	the callback to receive information
arg	optional arg devivered to the callback

THIS MUST BE LOCKED BY THE CALLER IF YOUR ALLOCATOR MAY BE CALLED BY OTHER THREADS. You can call it from an existing mutex or similar -protected critical section in your allocator if there is one already, or you will have to protect the caller of it with your own mutex so it cannot reenter.

Iterates through the list of instrumented allocations calling the given callback for each one.