1 # udebug - OpenWrt debugging infrastructure
3 udebug assists whole-system debugging by making it easy to provide ring buffers
4 with debug data and make them accessible through a unified API.
5 Through the CLI, you can either create snapshots of data with a specific duration,
6 or stream data in real time. The data itself is stored in .pcapng files, which can
7 contain a mix of packets and log messages.
9 ## Notes on using Wireshark
11 In order to parse log messages in .pcapng files, you need to change the Wireshark
13 Under `Preferences` -> `Protocols` -> `DLT_USER` -> `Encapsulations Table`,
14 add an entry for `User 0 (DLT=147)` with Payload protocol `syslog`.
18 #### `void udebug_init(struct udebug *ctx)`
20 Initializes the udebug context. Must be called before adding buffers.
22 #### `int udebug_connect(struct udebug *ctx, const char *path)`
24 Connect to udebugd and submit any buffers that were added using `udebug_buf_add`.
26 #### `void udebug_auto_connect(struct udebug *ctx, const char *path)`
28 Connects and automatically reconnects to udebugd. Uses uloop and calls `udebug_add_uloop`.
30 #### `void udebug_free(struct udebug *ctx)`
32 Frees the udebug context and all added created buffers.
34 #### `int udebug_buf_init(struct udebug_buf *buf, size_t entries, size_t size)`
36 Allocates a buffer with a given size. Entries and size are rounded up internally to the
39 #### `int udebug_buf_add(struct udebug *ctx, struct udebug_buf *buf, const struct udebug_buf_meta *meta);`
41 Submits the buffer to udebugd and makes it visible.
43 #### `void udebug_buf_free(struct udebug_buf *buf)`
45 Removes the buffer from udebugd and frees it.
47 #### `void udebug_entry_init(struct udebug_buf *buf)`
49 Initializes a new entry on the ring buffer.
51 #### `void *udebug_entry_append(struct udebug_buf *buf, const void *data, uint32_t len)`
53 Appends data to the ring buffer. When called with data == NULL, space is only
54 reserved, and the return value provides a pointer with len bytes that can be
57 #### `int udebug_entry_printf(struct udebug_buf *buf, const char *fmt, ...)`
59 Appends a string to the buffer, based on format string + arguments (like printf)
61 #### `int udebug_entry_vprintf(struct udebug_buf *buf, const char *fmt, va_list ap)`
63 Like `udebug_entry_printf()`
65 #### `void udebug_entry_add(struct udebug_buf *buf)`
67 Finalizes and publishes the entry on the ring buffer.
72 static struct udebug ud;
73 static struct udebug_buf udb;
79 udebug_auto_connect(&ud, NULL);
81 static const struct udebug_buf_meta buf_meta = {
83 .format = UDEBUG_FORMAT_STRING,
89 udebug_buf_init(&udb, entries, data_size);
90 udebug_buf_add(&ud, &udb, &buf_meta);
94 udebug_entry_init(&udb); // initialize entry
95 udebug_entry_printf(&udb, "count=%d", count++);
96 udebug_entry_add(&udb); // finalize the entry
103 Usage: udebug-cli [<options>] <command> [<args>]
106 -f Ignore errors on opening rings
107 -d <duration>: Only fetch data up to <duration> seconds old
108 -o <file>|- Set output file for snapshot/stream (or '-' for stdout)
109 -i <process>[:<name>] Select debug buffer for snapshot/stream
110 -s <path> Use udebug socket <path>
111 -q Suppress warnings/error messages
114 list: List available debug buffers
115 snapshot: Create a pcapng snapshot of debug buffers
116 set_flag [<name>=0|1 ...] Set ring buffer flags
117 get_flags Get ring buffer flags