2 * Copyright (c) 2007 Robert N. M. Watson
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 * notice, this list of conditions and the following disclaimer in the
12 * documentation and/or other materials provided with the distribution.
14 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 * Simple DDB scripting mechanism. Each script consists of a named list of
29 * DDB commands to execute sequentially. A more sophisticated scripting
30 * language might be desirable, but would be significantly more complex to
31 * implement. A more interesting syntax might allow general use of variables
32 * and extracting of useful values, such as a thread's process identifier,
33 * for passing into further DDB commands. Certain scripts are run
34 * automatically at kdb_enter(), if defined, based on how the debugger is
35 * entered, allowing scripted responses to panics, break signals, etc.
37 * Scripts may be managed from within DDB using the script, scripts, and
38 * unscript commands. They may also be managed from userspace using ddb(8),
39 * which operates using a set of sysctls.
42 * - Allow scripts to be defined using tunables so that they can be defined
43 * before boot and be present in single-user mode without boot scripts
45 * - Memory allocation is not possible from within DDB, so we use a set of
46 * statically allocated buffers to hold defined scripts. However, when
47 * scripts are being defined from userspace via sysctl, we could in fact be
48 * using malloc(9) and therefore not impose a static limit, giving greater
49 * flexibility and avoiding hard-defined buffer limits.
50 * - When scripts run automatically on entrance to DDB, placing "continue" at
51 * the end still results in being in the debugger, as we unconditionally
52 * run db_command_loop() after the script. There should be a way to avoid
56 #include <sys/cdefs.h>
57 __FBSDID("$FreeBSD$");
59 #include <sys/param.h>
61 #include <sys/kernel.h>
62 #include <sys/libkern.h>
64 #include <sys/malloc.h>
65 #include <sys/mutex.h>
67 #include <sys/sysctl.h>
68 #include <sys/systm.h>
71 #include <ddb/db_command.h>
72 #include <ddb/db_lex.h>
74 #include <machine/setjmp.h>
77 * struct ddb_script describes an individual script.
80 char ds_scriptname[DB_MAXSCRIPTNAME];
81 char ds_script[DB_MAXSCRIPTLEN];
85 * Global list of scripts -- defined scripts have non-empty name fields.
87 static struct ddb_script db_script_table[DB_MAXSCRIPTS];
90 * While executing a script, we parse it using strsep(), so require a
91 * temporary buffer that may be used destructively. Since we support weak
92 * recursion of scripts (one may reference another), we need one buffer for
93 * each concurrently executing script.
95 static struct db_recursion_data {
96 char drd_buffer[DB_MAXSCRIPTLEN];
97 } db_recursion_data[DB_MAXSCRIPTRECURSION];
98 static int db_recursion = -1;
101 * We use a separate static buffer for script validation so that it is safe
102 * to validate scripts from within a script. This is used only in
103 * db_script_valid(), which should never be called reentrantly.
105 static char db_static_buffer[DB_MAXSCRIPTLEN];
108 * Synchronization is not required from within the debugger, as it is
109 * singe-threaded (although reentrance must be carefully considered).
110 * However, it is required when interacting with scripts from user space
111 * processes. Sysctl procedures acquire db_script_mtx before accessing the
112 * global script data structures.
114 static struct mtx db_script_mtx;
115 MTX_SYSINIT(db_script_mtx, &db_script_mtx, "db_script_mtx", MTX_DEF);
118 * Some script names have special meaning, such as those executed
119 * automatically when KDB is entered.
121 #define DB_SCRIPT_KDBENTER_PREFIX "kdb.enter" /* KDB has entered. */
122 #define DB_SCRIPT_KDBENTER_DEFAULT "kdb.enter.default"
125 * Find the existing script slot for a named script, if any.
127 static struct ddb_script *
128 db_script_lookup(const char *scriptname)
132 for (i = 0; i < DB_MAXSCRIPTS; i++) {
133 if (strcmp(db_script_table[i].ds_scriptname, scriptname) ==
135 return (&db_script_table[i]);
141 * Find a new slot for a script, if available. Does not mark as allocated in
142 * any way--this must be done by the caller.
144 static struct ddb_script *
149 for (i = 0; i < DB_MAXSCRIPTS; i++) {
150 if (strlen(db_script_table[i].ds_scriptname) == 0)
151 return (&db_script_table[i]);
157 * Perform very rudimentary validation of a proposed script. It would be
158 * easy to imagine something more comprehensive. The script string is
159 * validated in a static buffer.
162 db_script_valid(const char *scriptname, const char *script)
164 char *buffer, *command;
166 if (strlen(scriptname) == 0)
168 if (strlen(scriptname) >= DB_MAXSCRIPTNAME)
170 if (strlen(script) >= DB_MAXSCRIPTLEN)
172 buffer = db_static_buffer;
173 strcpy(buffer, script);
174 while ((command = strsep(&buffer, ";")) != NULL) {
175 if (strlen(command) >= DB_MAXLINE)
182 * Modify an existing script or add a new script with the specified script
183 * name and contents. If there are no script slots available, an error will
187 db_script_set(const char *scriptname, const char *script)
189 struct ddb_script *dsp;
192 error = db_script_valid(scriptname, script);
195 dsp = db_script_lookup(scriptname);
197 dsp = db_script_new();
200 strlcpy(dsp->ds_scriptname, scriptname,
201 sizeof(dsp->ds_scriptname));
203 strlcpy(dsp->ds_script, script, sizeof(dsp->ds_script));
208 * Delete an existing script by name, if found.
211 db_script_unset(const char *scriptname)
213 struct ddb_script *dsp;
215 dsp = db_script_lookup(scriptname);
218 strcpy(dsp->ds_scriptname, "");
219 strcpy(dsp->ds_script, "");
224 * Trim leading/trailing white space in a command so that we don't pass
225 * carriage returns, etc, into DDB command parser.
228 db_command_trimmable(char ch)
244 db_command_trim(char **commandp)
249 while (db_command_trimmable(*command))
251 while ((strlen(command) > 0) &&
252 db_command_trimmable(command[strlen(command) - 1]))
253 command[strlen(command) - 1] = 0;
258 * Execute a script, breaking it up into individual commands and passing them
259 * sequentially into DDB's input processing. Use the KDB jump buffer to
260 * restore control to the main script loop if things get too wonky when
261 * processing a command -- i.e., traps, etc. Also, make sure we don't exceed
262 * practical limits on recursion.
264 * XXXRW: If any individual command is too long, it will be truncated when
265 * injected into the input at a lower layer. We should validate the script
266 * before configuring it to avoid this scenario.
269 db_script_exec(const char *scriptname, int warnifnotfound)
271 struct db_recursion_data *drd;
272 struct ddb_script *dsp;
273 char *buffer, *command;
277 dsp = db_script_lookup(scriptname);
280 db_printf("script '%s' not found\n", scriptname);
284 if (db_recursion >= DB_MAXSCRIPTRECURSION) {
285 db_printf("Script stack too deep\n");
289 drd = &db_recursion_data[db_recursion];
292 * Parse script in temporary buffer, since strsep() is destructive.
294 buffer = drd->drd_buffer;
295 strcpy(buffer, dsp->ds_script);
296 while ((command = strsep(&buffer, ";")) != NULL) {
297 db_printf("db:%d:%s> %s\n", db_recursion, scriptname,
299 db_command_trim(&command);
300 prev_jb = kdb_jmpbuf(jb);
302 db_command_script(command);
304 db_printf("Script command '%s' returned error\n",
313 * Wrapper for exec path that is called on KDB enter. Map reason for KDB
314 * enter to a script name, and don't whine if the script doesn't exist. If
315 * there is no matching script, try the catch-all script.
318 db_script_kdbenter(const char *eventname)
320 char scriptname[DB_MAXSCRIPTNAME];
322 snprintf(scriptname, sizeof(scriptname), "%s.%s",
323 DB_SCRIPT_KDBENTER_PREFIX, eventname);
324 if (db_script_exec(scriptname, 0) == ENOENT)
325 (void)db_script_exec(DB_SCRIPT_KDBENTER_DEFAULT, 0);
329 * DDB commands for scripting, as reached via the DDB user interface:
331 * scripts - lists scripts
332 * run <scriptname> - run a script
333 * script <scriptname> - prints script
334 * script <scriptname> <script> - set a script
335 * unscript <scriptname> - remove a script
339 * List scripts and their contents.
342 db_scripts_cmd(db_expr_t addr, bool have_addr, db_expr_t count,
347 for (i = 0; i < DB_MAXSCRIPTS; i++) {
348 if (strlen(db_script_table[i].ds_scriptname) != 0) {
350 db_script_table[i].ds_scriptname,
351 db_script_table[i].ds_script);
360 db_run_cmd(db_expr_t addr, bool have_addr, db_expr_t count, char *modif)
365 * Right now, we accept exactly one argument. In the future, we
366 * might want to accept flags and arguments to the script itself.
372 if (db_read_token() != tEOL)
375 db_script_exec(db_tok_string, 1);
379 * Print or set a named script, with the set portion broken out into its own
380 * function. We must directly access the remainder of the DDB line input as
381 * we do not wish to use db_lex's token processing.
384 db_script_cmd(db_expr_t addr, bool have_addr, db_expr_t count,
387 char *buf, scriptname[DB_MAXSCRIPTNAME];
388 struct ddb_script *dsp;
393 db_printf("usage: script scriptname=script\n");
398 if (strlcpy(scriptname, db_tok_string, sizeof(scriptname)) >=
399 sizeof(scriptname)) {
400 db_printf("scriptname too long\n");
407 dsp = db_script_lookup(scriptname);
409 db_printf("script '%s' not found\n", scriptname);
413 db_printf("%s=%s\n", scriptname, dsp->ds_script);
414 } else if (t == tEQ) {
416 if (buf[strlen(buf)-1] == '\n')
417 buf[strlen(buf)-1] = '\0';
418 error = db_script_set(scriptname, buf);
420 db_printf("Error: %d\n", error);
427 * Remove a named script.
430 db_unscript_cmd(db_expr_t addr, bool have_addr, db_expr_t count,
442 error = db_script_unset(db_tok_string);
443 if (error == ENOENT) {
444 db_printf("script '%s' not found\n", db_tok_string);
452 * Sysctls for managing DDB scripting:
454 * debug.ddb.scripting.script - Define a new script
455 * debug.ddb.scripting.scripts - List of names *and* scripts
456 * debug.ddb.scripting.unscript - Remove an existing script
458 * Since we don't want to try to manage arbitrary extensions to the sysctl
459 * name space from the debugger, the script/unscript sysctls are a bit more
460 * like RPCs and a bit less like normal get/set requests. The ddb(8) command
461 * line tool wraps them to make things a bit more user-friendly.
463 static SYSCTL_NODE(_debug_ddb, OID_AUTO, scripting, CTLFLAG_RW, 0,
464 "DDB script settings");
467 sysctl_debug_ddb_scripting_scripts(SYSCTL_HANDLER_ARGS)
474 * Make space to include a maximum-length name, = symbol,
475 * maximum-length script, and carriage return for every script that
478 len = DB_MAXSCRIPTS * (DB_MAXSCRIPTNAME + 1 + DB_MAXSCRIPTLEN + 1);
479 buffer = malloc(len, M_TEMP, M_WAITOK);
480 (void)sbuf_new(&sb, buffer, len, SBUF_FIXEDLEN);
481 mtx_lock(&db_script_mtx);
482 for (i = 0; i < DB_MAXSCRIPTS; i++) {
483 if (strlen(db_script_table[i].ds_scriptname) == 0)
485 (void)sbuf_printf(&sb, "%s=%s\n",
486 db_script_table[i].ds_scriptname,
487 db_script_table[i].ds_script);
489 mtx_unlock(&db_script_mtx);
491 error = SYSCTL_OUT(req, sbuf_data(&sb), sbuf_len(&sb) + 1);
493 free(buffer, M_TEMP);
496 SYSCTL_PROC(_debug_ddb_scripting, OID_AUTO, scripts, CTLTYPE_STRING |
497 CTLFLAG_RD, 0, 0, sysctl_debug_ddb_scripting_scripts, "A",
498 "List of defined scripts");
501 sysctl_debug_ddb_scripting_script(SYSCTL_HANDLER_ARGS)
503 char *buffer, *script, *scriptname;
507 * Maximum length for an input string is DB_MAXSCRIPTNAME + '='
508 * symbol + DB_MAXSCRIPT.
510 len = DB_MAXSCRIPTNAME + DB_MAXSCRIPTLEN + 1;
511 buffer = malloc(len, M_TEMP, M_WAITOK | M_ZERO);
512 error = sysctl_handle_string(oidp, buffer, len, req);
517 * Argument will be in form scriptname=script, so split into the
518 * scriptname and script.
521 scriptname = strsep(&script, "=");
522 if (script == NULL) {
526 mtx_lock(&db_script_mtx);
527 error = db_script_set(scriptname, script);
528 mtx_unlock(&db_script_mtx);
530 free(buffer, M_TEMP);
533 SYSCTL_PROC(_debug_ddb_scripting, OID_AUTO, script, CTLTYPE_STRING |
534 CTLFLAG_RW, 0, 0, sysctl_debug_ddb_scripting_script, "A",
538 * debug.ddb.scripting.unscript has somewhat unusual sysctl semantics -- set
539 * the name of the script that you want to delete.
542 sysctl_debug_ddb_scripting_unscript(SYSCTL_HANDLER_ARGS)
544 char name[DB_MAXSCRIPTNAME];
547 bzero(name, sizeof(name));
548 error = sysctl_handle_string(oidp, name, sizeof(name), req);
551 if (req->newptr == NULL)
553 mtx_lock(&db_script_mtx);
554 error = db_script_unset(name);
555 mtx_unlock(&db_script_mtx);
557 return (EINVAL); /* Don't confuse sysctl consumers. */
560 SYSCTL_PROC(_debug_ddb_scripting, OID_AUTO, unscript, CTLTYPE_STRING |
561 CTLFLAG_RW, 0, 0, sysctl_debug_ddb_scripting_unscript, "A",