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
37typedef struct {
38 uintptr_t st[32];
39 uintptr_t asize;
40
41 uint8_t sp;
42 uint8_t pre;
43 uint8_t post;
44} lws_backtrace_info_t;
45
46typedef struct {
47 uint8_t *comp;
48 size_t pos;
49 size_t len;
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 */
70LWS_VISIBLE LWS_EXTERN int
71lws_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 */
84LWS_VISIBLE LWS_EXTERN void
85lws_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 */
105LWS_VISIBLE LWS_EXTERN int
106lws_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 */
121LWS_VISIBLE LWS_EXTERN int
122lws_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 */
137LWS_VISIBLE LWS_EXTERN int
138lws_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 */
183LWS_VISIBLE LWS_EXTERN void
184lws_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 */
206LWS_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 */
221LWS_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 */
235LWS_VISIBLE LWS_EXTERN int
236lws_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 */
247LWS_VISIBLE LWS_EXTERN int
248lws_alloc_metadata_dump_stdout(struct lws_dll2 *d, void *user);
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 */
265LWS_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 */
274LWS_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//@}
281