lws-backtrace.h

Go to the documentation of this file.

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2022 Andy Green <andy@warmcat.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 */

 
typedef struct {
        uintptr_t       st[32];
        uintptr_t       asize;
 
        uint8_t         sp;
        uint8_t         pre;
        uint8_t         post;
} lws_backtrace_info_t;
 
typedef struct {
        uint8_t         *comp;
        size_t          pos;
        size_t          len;
} lws_backtrace_comp_t;
 
/*
 * lws_backtrace() - init and fiull a backtrace struct
 *
 * \param si: the backtrace struct to populate
 * \param pre: the number of call levels to snip from the top
 * \param post: the number of call levels to snip from the bottom
 *
 * This describes the call stack into \p si.  \p si doesn't need preparing
 * before the call.  \p pre levels of the call stack at the top will be snipped,
 * this will usually want to be 1 or 2 to conceal the helpers that are making
 * the call stack, such as lws_backtrace itself.
 *
 * \p post levels of the call stack at the bottom will be snipped, this is to
 * conceal loaders or other machinery that was used to start your application,
 * otherwise those entries will bloat all call stacks results on that platform.
 *
 * Returns 0 for success.
 */
LWS_VISIBLE LWS_EXTERN int
lws_backtrace(lws_backtrace_info_t *si, uint8_t pre, uint8_t post);
 
/*
 * lws_backtrace_compression_stream_init() - init and fiull a backtrace struct
 *
 * \param c: the backtrace compression struct
 * \param comp: the buffer to take the compressed bytes
 * \param comp_len: the number of bytes available at \p comp
 *
 * This initializes the caller's lws_backtrace_comp_t.  Because it's expected
 * the caller will want to put his own compressed data after the compressed
 * backtrace, he is responsible for the compression context.
 */
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() - add bitfields to compression stream
 *
 * \param c: the backtrace compression context struct
 * \param v: the bitfield to add to the stream
 * \param bits: the number of bits of v to add
 *
 * This inserts bits from the LSB end of v to the compression stream.
 *
 * This is used by the backtrace compression, user code can use this to add
 * its own bitfields into the compression stream after the compressed backtrace.
 *
 * User data should be added after, so that the backtrace can be processed even
 * if the additional data is not understood by the processing script.
 *
 * Returns 0 for success or nonzero if ran out of compression output buffer.
 */
LWS_VISIBLE LWS_EXTERN int
lws_backtrace_compression_stream(lws_backtrace_comp_t *c, uintptr_t v,
                                 unsigned int bits);
 
/*
 * lws_backtrace_compression_destream() - add bitfields to compression stream
 *
 * \param c: the backtrace compression context struct
 * \param _v: pointer to take the bitfield result
 * \param bits: the number of bits to bring out into _v
 *
 * This reads the compression stream and creates a bitfield from it in \p _v.
 *
 * Returns 0 for success (with \p _v set to the value), or nonzero if ran out
 * of compression output buffer.
 */
LWS_VISIBLE LWS_EXTERN int
lws_backtrace_compression_destream(lws_backtrace_comp_t *c, uintptr_t *_v,
                                   unsigned int bits);
 
/*
 * lws_backtrace_compress_backtrace() - compress backtrace si into c
 *
 * \param si: the backtrace struct to compress
 * \param c: the backtrace compression context struct
 *
 * This compresses backtrace information acquired in \p si into the compression
 * context \p c.  It compresses first the call stack length and then each IP
 * address in turn.
 *
 * Returns 0 for success.
 */
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);
 
#if defined(LWS_WITH_ALLOC_METADATA_LWS)
/*
 * Wrapper for _lws_alloc_metadata_dump() that uses the list owner that tracks
 *
 */
LWS_VISIBLE LWS_EXTERN void
_lws_alloc_metadata_dump_lws(lws_dll2_foreach_cb_t cb, void *arg);
#else
#define _lws_alloc_metadata_dump_lws(_a, _b)
#endif