FreeBSD/Linux Kernel Cross Reference
sys/ddb/db_script.c
1 /*-
2 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
3 *
4 * Copyright (c) 2007 Robert N. M. Watson
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 * SUCH DAMAGE.
27 */
28
29 /*-
30 * Simple DDB scripting mechanism. Each script consists of a named list of
31 * DDB commands to execute sequentially. A more sophisticated scripting
32 * language might be desirable, but would be significantly more complex to
33 * implement. A more interesting syntax might allow general use of variables
34 * and extracting of useful values, such as a thread's process identifier,
35 * for passing into further DDB commands. Certain scripts are run
36 * automatically at kdb_enter(), if defined, based on how the debugger is
37 * entered, allowing scripted responses to panics, break signals, etc.
38 *
39 * Scripts may be managed from within DDB using the script, scripts, and
40 * unscript commands. They may also be managed from userspace using ddb(8),
41 * which operates using a set of sysctls.
42 *
43 * TODO:
44 * - Allow scripts to be defined using tunables so that they can be defined
45 * before boot and be present in single-user mode without boot scripts
46 * running.
47 * - Memory allocation is not possible from within DDB, so we use a set of
48 * statically allocated buffers to hold defined scripts. However, when
49 * scripts are being defined from userspace via sysctl, we could in fact be
50 * using malloc(9) and therefore not impose a static limit, giving greater
51 * flexibility and avoiding hard-defined buffer limits.
52 * - When scripts run automatically on entrance to DDB, placing "continue" at
53 * the end still results in being in the debugger, as we unconditionally
54 * run db_command_loop() after the script. There should be a way to avoid
55 * this.
56 */
57
58 #include <sys/cdefs.h>
59 __FBSDID("$FreeBSD$");
60
61 #include <sys/param.h>
62 #include <sys/kdb.h>
63 #include <sys/kernel.h>
64 #include <sys/libkern.h>
65 #include <sys/lock.h>
66 #include <sys/malloc.h>
67 #include <sys/mutex.h>
68 #include <sys/sbuf.h>
69 #include <sys/sysctl.h>
70 #include <sys/systm.h>
71
72 #include <ddb/ddb.h>
73 #include <ddb/db_command.h>
74 #include <ddb/db_lex.h>
75
76 #include <machine/setjmp.h>
77
78 /*
79 * struct ddb_script describes an individual script.
80 */
81 struct ddb_script {
82 char ds_scriptname[DB_MAXSCRIPTNAME];
83 char ds_script[DB_MAXSCRIPTLEN];
84 };
85
86 /*
87 * Global list of scripts -- defined scripts have non-empty name fields.
88 */
89 static struct ddb_script db_script_table[DB_MAXSCRIPTS];
90
91 /*
92 * While executing a script, we parse it using strsep(), so require a
93 * temporary buffer that may be used destructively. Since we support weak
94 * recursion of scripts (one may reference another), we need one buffer for
95 * each concurrently executing script.
96 */
97 static struct db_recursion_data {
98 char drd_buffer[DB_MAXSCRIPTLEN];
99 } db_recursion_data[DB_MAXSCRIPTRECURSION];
100 static int db_recursion = -1;
101
102 /*
103 * We use a separate static buffer for script validation so that it is safe
104 * to validate scripts from within a script. This is used only in
105 * db_script_valid(), which should never be called reentrantly.
106 */
107 static char db_static_buffer[DB_MAXSCRIPTLEN];
108
109 /*
110 * Synchronization is not required from within the debugger, as it is
111 * singe-threaded (although reentrance must be carefully considered).
112 * However, it is required when interacting with scripts from user space
113 * processes. Sysctl procedures acquire db_script_mtx before accessing the
114 * global script data structures.
115 */
116 static struct mtx db_script_mtx;
117 MTX_SYSINIT(db_script_mtx, &db_script_mtx, "db_script_mtx", MTX_DEF);
118
119 /*
120 * Some script names have special meaning, such as those executed
121 * automatically when KDB is entered.
122 */
123 #define DB_SCRIPT_KDBENTER_PREFIX "kdb.enter" /* KDB has entered. */
124 #define DB_SCRIPT_KDBENTER_DEFAULT "kdb.enter.default"
125
126 /*
127 * Find the existing script slot for a named script, if any.
128 */
129 static struct ddb_script *
130 db_script_lookup(const char *scriptname)
131 {
132 int i;
133
134 for (i = 0; i < DB_MAXSCRIPTS; i++) {
135 if (strcmp(db_script_table[i].ds_scriptname, scriptname) ==
136 0)
137 return (&db_script_table[i]);
138 }
139 return (NULL);
140 }
141
142 /*
143 * Find a new slot for a script, if available. Does not mark as allocated in
144 * any way--this must be done by the caller.
145 */
146 static struct ddb_script *
147 db_script_new(void)
148 {
149 int i;
150
151 for (i = 0; i < DB_MAXSCRIPTS; i++) {
152 if (strlen(db_script_table[i].ds_scriptname) == 0)
153 return (&db_script_table[i]);
154 }
155 return (NULL);
156 }
157
158 /*
159 * Perform very rudimentary validation of a proposed script. It would be
160 * easy to imagine something more comprehensive. The script string is
161 * validated in a static buffer.
162 */
163 static int
164 db_script_valid(const char *scriptname, const char *script)
165 {
166 char *buffer, *command;
167
168 if (strlen(scriptname) == 0)
169 return (EINVAL);
170 if (strlen(scriptname) >= DB_MAXSCRIPTNAME)
171 return (EINVAL);
172 if (strlen(script) >= DB_MAXSCRIPTLEN)
173 return (EINVAL);
174 buffer = db_static_buffer;
175 strcpy(buffer, script);
176 while ((command = strsep(&buffer, ";")) != NULL) {
177 if (strlen(command) >= DB_MAXLINE)
178 return (EINVAL);
179 }
180 return (0);
181 }
182
183 /*
184 * Modify an existing script or add a new script with the specified script
185 * name and contents. If there are no script slots available, an error will
186 * be returned.
187 */
188 static int
189 db_script_set(const char *scriptname, const char *script)
190 {
191 struct ddb_script *dsp;
192 int error;
193
194 error = db_script_valid(scriptname, script);
195 if (error)
196 return (error);
197 dsp = db_script_lookup(scriptname);
198 if (dsp == NULL) {
199 dsp = db_script_new();
200 if (dsp == NULL)
201 return (ENOSPC);
202 strlcpy(dsp->ds_scriptname, scriptname,
203 sizeof(dsp->ds_scriptname));
204 }
205 strlcpy(dsp->ds_script, script, sizeof(dsp->ds_script));
206 return (0);
207 }
208
209 /*
210 * Delete an existing script by name, if found.
211 */
212 static int
213 db_script_unset(const char *scriptname)
214 {
215 struct ddb_script *dsp;
216
217 dsp = db_script_lookup(scriptname);
218 if (dsp == NULL)
219 return (ENOENT);
220 strcpy(dsp->ds_scriptname, "");
221 strcpy(dsp->ds_script, "");
222 return (0);
223 }
224
225 /*
226 * Trim leading/trailing white space in a command so that we don't pass
227 * carriage returns, etc, into DDB command parser.
228 */
229 static int
230 db_command_trimmable(char ch)
231 {
232
233 switch (ch) {
234 case ' ':
235 case '\t':
236 case '\n':
237 case '\r':
238 return (1);
239
240 default:
241 return (0);
242 }
243 }
244
245 static void
246 db_command_trim(char **commandp)
247 {
248 char *command;
249
250 command = *commandp;
251 while (db_command_trimmable(*command))
252 command++;
253 while ((strlen(command) > 0) &&
254 db_command_trimmable(command[strlen(command) - 1]))
255 command[strlen(command) - 1] = 0;
256 *commandp = command;
257 }
258
259 /*
260 * Execute a script, breaking it up into individual commands and passing them
261 * sequentially into DDB's input processing. Use the KDB jump buffer to
262 * restore control to the main script loop if things get too wonky when
263 * processing a command -- i.e., traps, etc. Also, make sure we don't exceed
264 * practical limits on recursion.
265 *
266 * XXXRW: If any individual command is too long, it will be truncated when
267 * injected into the input at a lower layer. We should validate the script
268 * before configuring it to avoid this scenario.
269 */
270 static int
271 db_script_exec(const char *scriptname, int warnifnotfound)
272 {
273 struct db_recursion_data *drd;
274 struct ddb_script *dsp;
275 char *buffer, *command;
276 void *prev_jb;
277 jmp_buf jb;
278
279 dsp = db_script_lookup(scriptname);
280 if (dsp == NULL) {
281 if (warnifnotfound)
282 db_printf("script '%s' not found\n", scriptname);
283 return (ENOENT);
284 }
285
286 if (db_recursion >= DB_MAXSCRIPTRECURSION) {
287 db_printf("Script stack too deep\n");
288 return (E2BIG);
289 }
290 db_recursion++;
291 drd = &db_recursion_data[db_recursion];
292
293 /*
294 * Parse script in temporary buffer, since strsep() is destructive.
295 */
296 buffer = drd->drd_buffer;
297 strcpy(buffer, dsp->ds_script);
298 while ((command = strsep(&buffer, ";")) != NULL) {
299 db_printf("db:%d:%s> %s\n", db_recursion, dsp->ds_scriptname,
300 command);
301 db_command_trim(&command);
302 prev_jb = kdb_jmpbuf(jb);
303 if (setjmp(jb) == 0)
304 db_command_script(command);
305 else
306 db_printf("Script command '%s' returned error\n",
307 command);
308 kdb_jmpbuf(prev_jb);
309 }
310 db_recursion--;
311 return (0);
312 }
313
314 /*
315 * Wrapper for exec path that is called on KDB enter. Map reason for KDB
316 * enter to a script name, and don't whine if the script doesn't exist. If
317 * there is no matching script, try the catch-all script.
318 */
319 void
320 db_script_kdbenter(const char *eventname)
321 {
322 char scriptname[DB_MAXSCRIPTNAME];
323
324 snprintf(scriptname, sizeof(scriptname), "%s.%s",
325 DB_SCRIPT_KDBENTER_PREFIX, eventname);
326 if (db_script_exec(scriptname, 0) == ENOENT)
327 (void)db_script_exec(DB_SCRIPT_KDBENTER_DEFAULT, 0);
328 }
329
330 /*-
331 * DDB commands for scripting, as reached via the DDB user interface:
332 *
333 * scripts - lists scripts
334 * run <scriptname> - run a script
335 * script <scriptname> - prints script
336 * script <scriptname> <script> - set a script
337 * unscript <scriptname> - remove a script
338 */
339
340 /*
341 * List scripts and their contents.
342 */
343 void
344 db_scripts_cmd(db_expr_t addr, bool have_addr, db_expr_t count,
345 char *modif)
346 {
347 int i;
348
349 for (i = 0; i < DB_MAXSCRIPTS; i++) {
350 if (strlen(db_script_table[i].ds_scriptname) != 0) {
351 db_printf("%s=%s\n",
352 db_script_table[i].ds_scriptname,
353 db_script_table[i].ds_script);
354 }
355 }
356 }
357
358 /*
359 * Execute a script.
360 */
361 void
362 db_run_cmd(db_expr_t addr, bool have_addr, db_expr_t count, char *modif)
363 {
364 int t;
365
366 /*
367 * Right now, we accept exactly one argument. In the future, we
368 * might want to accept flags and arguments to the script itself.
369 */
370 t = db_read_token();
371 if (t != tIDENT)
372 db_error("?\n");
373
374 if (db_read_token() != tEOL)
375 db_error("?\n");
376
377 db_script_exec(db_tok_string, 1);
378 }
379
380 /*
381 * Print or set a named script, with the set portion broken out into its own
382 * function. We must directly access the remainder of the DDB line input as
383 * we do not wish to use db_lex's token processing.
384 */
385 void
386 db_script_cmd(db_expr_t addr, bool have_addr, db_expr_t count,
387 char *modif)
388 {
389 char *buf, scriptname[DB_MAXSCRIPTNAME];
390 struct ddb_script *dsp;
391 int error, t;
392
393 t = db_read_token();
394 if (t != tIDENT) {
395 db_printf("usage: script scriptname=script\n");
396 db_skip_to_eol();
397 return;
398 }
399
400 if (strlcpy(scriptname, db_tok_string, sizeof(scriptname)) >=
401 sizeof(scriptname)) {
402 db_printf("scriptname too long\n");
403 db_skip_to_eol();
404 return;
405 }
406
407 t = db_read_token();
408 if (t == tEOL) {
409 dsp = db_script_lookup(scriptname);
410 if (dsp == NULL) {
411 db_printf("script '%s' not found\n", scriptname);
412 db_skip_to_eol();
413 return;
414 }
415 db_printf("%s=%s\n", scriptname, dsp->ds_script);
416 } else if (t == tEQ) {
417 buf = db_get_line();
418 if (buf[strlen(buf)-1] == '\n')
419 buf[strlen(buf)-1] = '\0';
420 error = db_script_set(scriptname, buf);
421 if (error != 0)
422 db_printf("Error: %d\n", error);
423 } else
424 db_printf("?\n");
425 db_skip_to_eol();
426 }
427
428 /*
429 * Remove a named script.
430 */
431 void
432 db_unscript_cmd(db_expr_t addr, bool have_addr, db_expr_t count,
433 char *modif)
434 {
435 int error, t;
436
437 t = db_read_token();
438 if (t != tIDENT) {
439 db_printf("?\n");
440 db_skip_to_eol();
441 return;
442 }
443
444 error = db_script_unset(db_tok_string);
445 if (error == ENOENT) {
446 db_printf("script '%s' not found\n", db_tok_string);
447 db_skip_to_eol();
448 return;
449 }
450 db_skip_to_eol();
451 }
452
453 /*
454 * Sysctls for managing DDB scripting:
455 *
456 * debug.ddb.scripting.script - Define a new script
457 * debug.ddb.scripting.scripts - List of names *and* scripts
458 * debug.ddb.scripting.unscript - Remove an existing script
459 *
460 * Since we don't want to try to manage arbitrary extensions to the sysctl
461 * name space from the debugger, the script/unscript sysctls are a bit more
462 * like RPCs and a bit less like normal get/set requests. The ddb(8) command
463 * line tool wraps them to make things a bit more user-friendly.
464 */
465 static SYSCTL_NODE(_debug_ddb, OID_AUTO, scripting,
466 CTLFLAG_RW | CTLFLAG_MPSAFE, 0,
467 "DDB script settings");
468
469 static int
470 sysctl_debug_ddb_scripting_scripts(SYSCTL_HANDLER_ARGS)
471 {
472 struct sbuf sb;
473 int error, i, len;
474 char *buffer;
475
476 /*
477 * Make space to include a maximum-length name, = symbol,
478 * maximum-length script, and carriage return for every script that
479 * may be defined.
480 */
481 len = DB_MAXSCRIPTS * (DB_MAXSCRIPTNAME + 1 + DB_MAXSCRIPTLEN + 1);
482 buffer = malloc(len, M_TEMP, M_WAITOK);
483 (void)sbuf_new(&sb, buffer, len, SBUF_FIXEDLEN);
484 mtx_lock(&db_script_mtx);
485 for (i = 0; i < DB_MAXSCRIPTS; i++) {
486 if (strlen(db_script_table[i].ds_scriptname) == 0)
487 continue;
488 (void)sbuf_printf(&sb, "%s=%s\n",
489 db_script_table[i].ds_scriptname,
490 db_script_table[i].ds_script);
491 }
492 mtx_unlock(&db_script_mtx);
493 sbuf_finish(&sb);
494 error = SYSCTL_OUT(req, sbuf_data(&sb), sbuf_len(&sb) + 1);
495 sbuf_delete(&sb);
496 free(buffer, M_TEMP);
497 return (error);
498 }
499 SYSCTL_PROC(_debug_ddb_scripting, OID_AUTO, scripts,
500 CTLTYPE_STRING | CTLFLAG_RD | CTLFLAG_MPSAFE, 0, 0,
501 sysctl_debug_ddb_scripting_scripts, "A",
502 "List of defined scripts");
503
504 static int
505 sysctl_debug_ddb_scripting_script(SYSCTL_HANDLER_ARGS)
506 {
507 char *buffer, *script, *scriptname;
508 int error, len;
509
510 /*
511 * Maximum length for an input string is DB_MAXSCRIPTNAME + '='
512 * symbol + DB_MAXSCRIPT.
513 */
514 len = DB_MAXSCRIPTNAME + DB_MAXSCRIPTLEN + 1;
515 buffer = malloc(len, M_TEMP, M_WAITOK | M_ZERO);
516 error = sysctl_handle_string(oidp, buffer, len, req);
517 if (error)
518 goto out;
519
520 /*
521 * Argument will be in form scriptname=script, so split into the
522 * scriptname and script.
523 */
524 script = buffer;
525 scriptname = strsep(&script, "=");
526 if (script == NULL) {
527 error = EINVAL;
528 goto out;
529 }
530 mtx_lock(&db_script_mtx);
531 error = db_script_set(scriptname, script);
532 mtx_unlock(&db_script_mtx);
533 out:
534 free(buffer, M_TEMP);
535 return (error);
536 }
537 SYSCTL_PROC(_debug_ddb_scripting, OID_AUTO, script,
538 CTLTYPE_STRING | CTLFLAG_RW | CTLFLAG_MPSAFE, 0, 0,
539 sysctl_debug_ddb_scripting_script, "A",
540 "Set a script");
541
542 /*
543 * debug.ddb.scripting.unscript has somewhat unusual sysctl semantics -- set
544 * the name of the script that you want to delete.
545 */
546 static int
547 sysctl_debug_ddb_scripting_unscript(SYSCTL_HANDLER_ARGS)
548 {
549 char name[DB_MAXSCRIPTNAME];
550 int error;
551
552 bzero(name, sizeof(name));
553 error = sysctl_handle_string(oidp, name, sizeof(name), req);
554 if (error)
555 return (error);
556 if (req->newptr == NULL)
557 return (0);
558 mtx_lock(&db_script_mtx);
559 error = db_script_unset(name);
560 mtx_unlock(&db_script_mtx);
561 if (error == ENOENT)
562 return (EINVAL); /* Don't confuse sysctl consumers. */
563 return (0);
564 }
565 SYSCTL_PROC(_debug_ddb_scripting, OID_AUTO, unscript,
566 CTLTYPE_STRING | CTLFLAG_RW | CTLFLAG_MPSAFE, 0, 0,
567 sysctl_debug_ddb_scripting_unscript, "A",
568 "Unset a script");
Cache object: 6b75f9b1ec475be04181a906bab716e1
|