README.md

   1 # udebug - OpenWrt debugging infrastructure
   2
   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.
   8
   9 ## Notes on using Wireshark
  10
  11 In order to parse log messages in .pcapng files, you need to change the Wireshark
  12 configuration.
  13 Under `Preferences` -> `Protocols` -> `DLT_USER` -> `Encapsulations Table`,
  14 add an entry for `User 0 (DLT=147)` with Payload protocol `syslog`.
  15
  16 ## libudebug C API
  17
  18 #### `void udebug_init(struct udebug *ctx)`
  19
  20 Initializes the udebug context. Must be called before adding buffers.
  21
  22 #### `int udebug_connect(struct udebug *ctx, const char *path)`
  23
  24 Connect to udebugd and submit any buffers that were added using `udebug_buf_add`.
  25
  26 #### `void udebug_auto_connect(struct udebug *ctx, const char *path)`
  27
  28 Connects and automatically reconnects to udebugd. Uses uloop and calls `udebug_add_uloop`.
  29
  30 #### `void udebug_free(struct udebug *ctx)`
  31
  32 Frees the udebug context and all added created buffers.
  33
  34 #### `int udebug_buf_init(struct udebug_buf *buf, size_t entries, size_t size)`
  35
  36 Allocates a buffer with a given size. Entries and size are rounded up internally to the
  37 nearest power-of-2.
  38
  39 #### `int udebug_buf_add(struct udebug *ctx, struct udebug_buf *buf, const struct udebug_buf_meta *meta);`
  40
  41 Submits the buffer to udebugd and makes it visible.
  42
  43 #### `void udebug_buf_free(struct udebug_buf *buf)`
  44
  45 Removes the buffer from udebugd and frees it.
  46
  47 #### `void udebug_entry_init(struct udebug_buf *buf)`
  48
  49 Initializes a new entry on the ring buffer.
  50
  51 #### `void *udebug_entry_append(struct udebug_buf *buf, const void *data, uint32_t len)`
  52
  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
  55 written to.
  56
  57 #### `int udebug_entry_printf(struct udebug_buf *buf, const char *fmt, ...)`
  58
  59 Appends a string to the buffer, based on format string + arguments (like printf)
  60
  61 #### `int udebug_entry_vprintf(struct udebug_buf *buf, const char *fmt, va_list ap)`
  62
  63 Like `udebug_entry_printf()`
  64
  65 #### `void udebug_entry_add(struct udebug_buf *buf)`
  66
  67 Finalizes and publishes the entry on the ring buffer.
  68
  69 ### Simple example
  70
  71 ```
  72 static struct udebug ud;
  73 static struct udebug_buf udb;
  74
  75 /* ... */
  76
  77 uloop_init();
  78 udebug_init(&ud);
  79 udebug_auto_connect(&ud, NULL);
  80
  81 static const struct udebug_buf_meta buf_meta = {
  82         .name = "counter",
  83         .format = UDEBUG_FORMAT_STRING,
  84 };
  85
  86 int entries = 128;
  87 int data_size = 1024;
  88
  89 udebug_buf_init(&udb, entries, data_size);
  90 udebug_buf_add(&ud, &udb, &buf_meta);
  91
  92 /* ... */
  93
  94 udebug_entry_init(&udb); // initialize entry
  95 udebug_entry_printf(&udb, "count=%d", count++);
  96 udebug_entry_add(&udb); // finalize the entry
  97
  98 ```
  99
 100 ## udebug CLI
 101
 102 ```
 103 Usage: udebug-cli [<options>] <command> [<args>]
 104
 105   Options:
 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
 112
 113   Commands:
 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
 118
 119 ```
 120