libwebsockets
Lightweight C library for HTML5 websockets
lws-backtrace.h
Go to the documentation of this file.
1 /*
2  * libwebsockets - small server side websockets and web server implementation
3  *
4  * Copyright (C) 2010 - 2022 Andy Green <andy@warmcat.com>
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22  * IN THE SOFTWARE.
23  */
24 
25 /** \defgroup lws_backtrace generic and compressed backtrace acquisition
26  * ##Backtrace apis
27  * \ingroup lwsbacktrace
28  *
29  * lws_backtrace
30  *
31  * These apis abstract acquisition and optionally compressed on binary back-
32  * traces, effectively build-specific signatures for where in the code you are
33  * and how you got there.
34  */
35 //@{
36 
37 typedef struct {
40 
44 } lws_backtrace_info_t;
45 
46 typedef struct {
50 } lws_backtrace_comp_t;
51 
52 /*
53  * lws_backtrace() - init and fiull a backtrace struct
54  *
55  * \param si: the backtrace struct to populate
56  * \param pre: the number of call levels to snip from the top
57  * \param post: the number of call levels to snip from the bottom
58  *
59  * This describes the call stack into \p si. \p si doesn't need preparing
60  * before the call. \p pre levels of the call stack at the top will be snipped,
61  * this will usually want to be 1 or 2 to conceal the helpers that are making
62  * the call stack, such as lws_backtrace itself.
63  *
64  * \p post levels of the call stack at the bottom will be snipped, this is to
65  * conceal loaders or other machinery that was used to start your application,
66  * otherwise those entries will bloat all call stacks results on that platform.
67  *
68  * Returns 0 for success.
69  */
70 LWS_VISIBLE LWS_EXTERN int
71 lws_backtrace(lws_backtrace_info_t *si, uint8_t pre, uint8_t post);
72 
73 /*
74  * lws_backtrace_compression_stream_init() - init and fiull a backtrace struct
75  *
76  * \param c: the backtrace compression struct
77  * \param comp: the buffer to take the compressed bytes
78  * \param comp_len: the number of bytes available at \p comp
79  *
80  * This initializes the caller's lws_backtrace_comp_t. Because it's expected
81  * the caller will want to put his own compressed data after the compressed
82  * backtrace, he is responsible for the compression context.
83  */
84 LWS_VISIBLE LWS_EXTERN void
85 lws_backtrace_compression_stream_init(lws_backtrace_comp_t *c,
86  uint8_t *comp, size_t comp_len);
87 
88 /*
89  * lws_backtrace_compression_stream() - add bitfields to compression stream
90  *
91  * \param c: the backtrace compression context struct
92  * \param v: the bitfield to add to the stream
93  * \param bits: the number of bits of v to add
94  *
95  * This inserts bits from the LSB end of v to the compression stream.
96  *
97  * This is used by the backtrace compression, user code can use this to add
98  * its own bitfields into the compression stream after the compressed backtrace.
99  *
100  * User data should be added after, so that the backtrace can be processed even
101  * if the additional data is not understood by the processing script.
102  *
103  * Returns 0 for success or nonzero if ran out of compression output buffer.
104  */
105 LWS_VISIBLE LWS_EXTERN int
106 lws_backtrace_compression_stream(lws_backtrace_comp_t *c, uintptr_t v,
107  unsigned int bits);
108 
109 /*
110  * lws_backtrace_compression_destream() - add bitfields to compression stream
111  *
112  * \param c: the backtrace compression context struct
113  * \param _v: pointer to take the bitfield result
114  * \param bits: the number of bits to bring out into _v
115  *
116  * This reads the compression stream and creates a bitfield from it in \p _v.
117  *
118  * Returns 0 for success (with \p _v set to the value), or nonzero if ran out
119  * of compression output buffer.
120  */
121 LWS_VISIBLE LWS_EXTERN int
122 lws_backtrace_compression_destream(lws_backtrace_comp_t *c, uintptr_t *_v,
123  unsigned int bits);
124 
125 /*
126  * lws_backtrace_compress_backtrace() - compress backtrace si into c
127  *
128  * \param si: the backtrace struct to compress
129  * \param c: the backtrace compression context struct
130  *
131  * This compresses backtrace information acquired in \p si into the compression
132  * context \p c. It compresses first the call stack length and then each IP
133  * address in turn.
134  *
135  * Returns 0 for success.
136  */
137 LWS_VISIBLE LWS_EXTERN int
138 lws_backtrace_compress_backtrace(lws_backtrace_info_t *si,
139  lws_backtrace_comp_t *c);
140 
141 //@}
142 
143 /** \defgroup lws_alloc_metadata helpers for allocator instrumentation
144  * ##Alloc Metadata APIs
145  * \ingroup lwsallocmetadata
146  *
147  * lws_alloc_metadata
148  *
149  * These helpers let you rapidly instrument your libc or platform memory
150  * allocator so that you can later dump details, including a backtrace of where
151  * the allocation was made, for every live heap allocation.
152  *
153  * You would use it at peak memory usage, to audit who is using what at that
154  * time.
155  *
156  * Effective compression is used to keep the metadata overhead to ~48 bytes
157  * per active allocation on 32-bit systems.
158  */
159 //@{
160 
161 /**
162  * lws_alloc_metadata_gen() - generate metadata blob (with compressed backtrace)
163  *
164  * \param size: the allocation size
165  * \param comp: buffer for compressed backtrace
166  * \param comp_len: number of bytes available in the compressed backtrace
167  * \param adj: takes the count of additional bytes needed for metadata behind
168  * the allocation we tell the user about
169  * \param cl: takes the count of bytes used in comp
170  *
171  * This helper creates the compressed part of the alloc metadata blob and
172  * calculates the total overallocation that is needed in \p adj.
173  *
174  * This doesn't need any locking.
175  *
176  * If \p comp_len is too small for the whole result, or it was not possible to
177  * get the backtrace information, the compressed part is set to empty (total
178  * length 2 to carry the 00 00 length).
179  *
180  * 6 or 10 (64-bit) bytes per backtrace IP allowed (currently 16) should always
181  * be enough, typically the compression reduces this very significantly.
182  */
183 LWS_VISIBLE LWS_EXTERN void
184 lws_alloc_metadata_gen(size_t size, uint8_t *comp, size_t comp_len, size_t *adj,
185  size_t *cl);
186 
187 /**
188  * _lws_alloc_metadata_adjust() - helper to inject metadata and list as active
189  *
190  * \param active: the allocation owner
191  * \param v: Original, true allocation pointer, adjusted on exit
192  * \param adj: Total size of metadata overallocation
193  * \param comp: The compressed metadata
194  * \param cl: takes the count of bytes used in comp
195  *
196  * THIS MUST BE LOCKED BY THE CALLER IF YOUR ALLOCATOR MAY BE CALLED BY OTHER
197  * THREADS. You can call it from an existing mutex or similar -protected
198  * critical section in your allocator if there is one already, or you will have
199  * to protect the caller of it with your own mutex so it cannot reenter.
200  *
201  * This is a helper that adjusts the allocation past the metadata part so the
202  * caller of the allocator using this sees what he asked for. The deallocator
203  * must call _lws_alloc_metadata_trim() to balance this before actual
204  * deallocation.
205  */
206 LWS_VISIBLE LWS_EXTERN void
207 _lws_alloc_metadata_adjust(lws_dll2_owner_t *active, void **v, size_t adj, uint8_t *comp, unsigned int cl);
208 
209 /**
210  * _lws_alloc_metadata_trim() - helper to trim metadata and remove from active
211  *
212  * \param ptr: Adjusted allocation pointer on entry, true allocation ptr on exit
213  * \param comp: NULL, or set on exit to point to start of compressed area
214  * \param complen: NULL, or set on exit to length of compressed area in bytes
215  *
216  * THIS MUST BE LOCKED BY THE CALLER IF YOUR DEALLOCATOR MAY BE CALLED BY OTHER
217  * THREADS. You can call it from an existing mutex or similar -protected
218  * critical section in your deallocator if there is one already, or you will
219  * have to protect that caller of it with your own mutex so it cannot reenter.
220  */
221 LWS_VISIBLE LWS_EXTERN void
222 _lws_alloc_metadata_trim(void **ptr, uint8_t **comp, uint16_t *complen);
223 
224 /**
225  * lws_alloc_metadata_parse() - parse compressed metadata into struct
226  *
227  * \param si: Struct to take the backtrace results from decompression
228  * \param adjusted_alloc: pointer to adjusted, user allocation start
229  *
230  * This api parses and decompresses the blob behind the \p adjusted_alloc
231  * address into \p si.
232  *
233  * Returns 0 for success.
234  */
235 LWS_VISIBLE LWS_EXTERN int
236 lws_alloc_metadata_parse(lws_backtrace_info_t *si, const uint8_t *adjusted_alloc);
237 
238 /**
239  * lws_alloc_metadata_dump_stdout() - helper to print base64 blob on stdout
240  *
241  * \param d: the current list item
242  * \param user: the optional arg given to the dump api (ignored)
243  *
244  * Generic helper that can be given to _lws_alloc_metadata_dump() as the
245  * callback that will emit a standardized base64 blob for the alloc metadata
246  */
247 LWS_VISIBLE LWS_EXTERN int
249 
250 /**
251  * lws_alloc_metadata_dump_stdout() - dump all live allocs in instrumented heap
252  *
253  * \param active: the owner of the active allocation list for this heap
254  * \param cb: the callback to receive information
255  * \param arg: optional arg devivered to the callback
256  *
257  * THIS MUST BE LOCKED BY THE CALLER IF YOUR ALLOCATOR MAY BE CALLED BY OTHER
258  * THREADS. You can call it from an existing mutex or similar -protected
259  * critical section in your allocator if there is one already, or you will have
260  * to protect the caller of it with your own mutex so it cannot reenter.
261  *
262  * Iterates through the list of instrumented allocations calling the given
263  * callback for each one.
264  */
265 LWS_VISIBLE LWS_EXTERN void
266 _lws_alloc_metadata_dump(lws_dll2_owner_t *active, lws_dll2_foreach_cb_t cb,
267  void *arg);
268 
269 #if defined(LWS_WITH_ALLOC_METADATA_LWS)
270 /*
271  * Wrapper for _lws_alloc_metadata_dump() that uses the list owner that tracks
272  *
273  */
274 LWS_VISIBLE LWS_EXTERN void
275 _lws_alloc_metadata_dump_lws(lws_dll2_foreach_cb_t cb, void *arg);
276 #else
277 #define _lws_alloc_metadata_dump_lws(_a, _b)
278 #endif
279 
280 //@}