1 /*- 2 * Copyright (c) 2007 Robert N. M. Watson 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 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. 13 * 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 24 * SUCH DAMAGE. 25 */ 26 27 /*- 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. 36 * 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. 40 * 41 * TODO: 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 44 * running. 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 53 * this. 54 */ 55 56 #include <sys/cdefs.h> 57 __FBSDID("$FreeBSD$"); 58 59 #include <sys/param.h> 60 #include <sys/kdb.h> 61 #include <sys/kernel.h> 62 #include <sys/libkern.h> 63 #include <sys/lock.h> 64 #include <sys/malloc.h> 65 #include <sys/mutex.h> 66 #include <sys/sbuf.h> 67 #include <sys/sysctl.h> 68 #include <sys/systm.h> 69 70 #include <ddb/ddb.h> 71 #include <ddb/db_command.h> 72 #include <ddb/db_lex.h> 73 74 #include <machine/setjmp.h> 75 76 /* 77 * struct ddb_script describes an individual script. 78 */ 79 struct ddb_script { 80 char ds_scriptname[DB_MAXSCRIPTNAME]; 81 char ds_script[DB_MAXSCRIPTLEN]; 82 }; 83 84 /* 85 * Global list of scripts -- defined scripts have non-empty name fields. 86 */ 87 static struct ddb_script db_script_table[DB_MAXSCRIPTS]; 88 89 /* 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. 94 */ 95 static struct db_recursion_data { 96 char drd_buffer[DB_MAXSCRIPTLEN]; 97 } db_recursion_data[DB_MAXSCRIPTRECURSION]; 98 static int db_recursion = -1; 99 100 /* 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. 104 */ 105 static char db_static_buffer[DB_MAXSCRIPTLEN]; 106 107 /* 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. 113 */ 114 static struct mtx db_script_mtx; 115 MTX_SYSINIT(db_script_mtx, &db_script_mtx, "db_script_mtx", MTX_DEF); 116 117 /* 118 * Some script names have special meaning, such as those executed 119 * automatically when KDB is entered. 120 */ 121 #define DB_SCRIPT_KDBENTER_PREFIX "kdb.enter" /* KDB has entered. */ 122 #define DB_SCRIPT_KDBENTER_DEFAULT "kdb.enter.default" 123 124 /* 125 * Find the existing script slot for a named script, if any. 126 */ 127 static struct ddb_script * 128 db_script_lookup(const char *scriptname) 129 { 130 int i; 131 132 for (i = 0; i < DB_MAXSCRIPTS; i++) { 133 if (strcmp(db_script_table[i].ds_scriptname, scriptname) == 134 0) 135 return (&db_script_table[i]); 136 } 137 return (NULL); 138 } 139 140 /* 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. 143 */ 144 static struct ddb_script * 145 db_script_new(void) 146 { 147 int i; 148 149 for (i = 0; i < DB_MAXSCRIPTS; i++) { 150 if (strlen(db_script_table[i].ds_scriptname) == 0) 151 return (&db_script_table[i]); 152 } 153 return (NULL); 154 } 155 156 /* 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. 160 */ 161 static int 162 db_script_valid(const char *scriptname, const char *script) 163 { 164 char *buffer, *command; 165 166 if (strlen(scriptname) == 0) 167 return (EINVAL); 168 if (strlen(scriptname) >= DB_MAXSCRIPTNAME) 169 return (EINVAL); 170 if (strlen(script) >= DB_MAXSCRIPTLEN) 171 return (EINVAL); 172 buffer = db_static_buffer; 173 strcpy(buffer, script); 174 while ((command = strsep(&buffer, ";")) != NULL) { 175 if (strlen(command) >= DB_MAXLINE) 176 return (EINVAL); 177 } 178 return (0); 179 } 180 181 /* 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 184 * be returned. 185 */ 186 static int 187 db_script_set(const char *scriptname, const char *script) 188 { 189 struct ddb_script *dsp; 190 int error; 191 192 error = db_script_valid(scriptname, script); 193 if (error) 194 return (error); 195 dsp = db_script_lookup(scriptname); 196 if (dsp == NULL) { 197 dsp = db_script_new(); 198 if (dsp == NULL) 199 return (ENOSPC); 200 strlcpy(dsp->ds_scriptname, scriptname, 201 sizeof(dsp->ds_scriptname)); 202 } 203 strlcpy(dsp->ds_script, script, sizeof(dsp->ds_script)); 204 return (0); 205 } 206 207 /* 208 * Delete an existing script by name, if found. 209 */ 210 static int 211 db_script_unset(const char *scriptname) 212 { 213 struct ddb_script *dsp; 214 215 dsp = db_script_lookup(scriptname); 216 if (dsp == NULL) 217 return (ENOENT); 218 strcpy(dsp->ds_scriptname, ""); 219 strcpy(dsp->ds_script, ""); 220 return (0); 221 } 222 223 /* 224 * Trim leading/trailing white space in a command so that we don't pass 225 * carriage returns, etc, into DDB command parser. 226 */ 227 static int 228 db_command_trimmable(char ch) 229 { 230 231 switch (ch) { 232 case ' ': 233 case '\t': 234 case '\n': 235 case '\r': 236 return (1); 237 238 default: 239 return (0); 240 } 241 } 242 243 static void 244 db_command_trim(char **commandp) 245 { 246 char *command; 247 248 command = *commandp; 249 while (db_command_trimmable(*command)) 250 command++; 251 while ((strlen(command) > 0) && 252 db_command_trimmable(command[strlen(command) - 1])) 253 command[strlen(command) - 1] = 0; 254 *commandp = command; 255 } 256 257 /* 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. 263 * 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. 267 */ 268 static int 269 db_script_exec(const char *scriptname, int warnifnotfound) 270 { 271 struct db_recursion_data *drd; 272 struct ddb_script *dsp; 273 char *buffer, *command; 274 void *prev_jb; 275 jmp_buf jb; 276 277 dsp = db_script_lookup(scriptname); 278 if (dsp == NULL) { 279 if (warnifnotfound) 280 db_printf("script '%s' not found\n", scriptname); 281 return (ENOENT); 282 } 283 284 if (db_recursion >= DB_MAXSCRIPTRECURSION) { 285 db_printf("Script stack too deep\n"); 286 return (E2BIG); 287 } 288 db_recursion++; 289 drd = &db_recursion_data[db_recursion]; 290 291 /* 292 * Parse script in temporary buffer, since strsep() is destructive. 293 */ 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, 298 command); 299 db_command_trim(&command); 300 prev_jb = kdb_jmpbuf(jb); 301 if (setjmp(jb) == 0) 302 db_command_script(command); 303 else 304 db_printf("Script command '%s' returned error\n", 305 command); 306 kdb_jmpbuf(prev_jb); 307 } 308 db_recursion--; 309 return (0); 310 } 311 312 /* 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. 316 */ 317 void 318 db_script_kdbenter(const char *eventname) 319 { 320 char scriptname[DB_MAXSCRIPTNAME]; 321 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); 326 } 327 328 /*- 329 * DDB commands for scripting, as reached via the DDB user interface: 330 * 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 336 */ 337 338 /* 339 * List scripts and their contents. 340 */ 341 void 342 db_scripts_cmd(db_expr_t addr, bool have_addr, db_expr_t count, 343 char *modif) 344 { 345 int i; 346 347 for (i = 0; i < DB_MAXSCRIPTS; i++) { 348 if (strlen(db_script_table[i].ds_scriptname) != 0) { 349 db_printf("%s=%s\n", 350 db_script_table[i].ds_scriptname, 351 db_script_table[i].ds_script); 352 } 353 } 354 } 355 356 /* 357 * Execute a script. 358 */ 359 void 360 db_run_cmd(db_expr_t addr, bool have_addr, db_expr_t count, char *modif) 361 { 362 int t; 363 364 /* 365 * Right now, we accept exactly one argument. In the future, we 366 * might want to accept flags and arguments to the script itself. 367 */ 368 t = db_read_token(); 369 if (t != tIDENT) 370 db_error("?\n"); 371 372 if (db_read_token() != tEOL) 373 db_error("?\n"); 374 375 db_script_exec(db_tok_string, 1); 376 } 377 378 /* 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. 382 */ 383 void 384 db_script_cmd(db_expr_t addr, bool have_addr, db_expr_t count, 385 char *modif) 386 { 387 char *buf, scriptname[DB_MAXSCRIPTNAME]; 388 struct ddb_script *dsp; 389 int error, t; 390 391 t = db_read_token(); 392 if (t != tIDENT) { 393 db_printf("usage: script scriptname=script\n"); 394 db_skip_to_eol(); 395 return; 396 } 397 398 if (strlcpy(scriptname, db_tok_string, sizeof(scriptname)) >= 399 sizeof(scriptname)) { 400 db_printf("scriptname too long\n"); 401 db_skip_to_eol(); 402 return; 403 } 404 405 t = db_read_token(); 406 if (t == tEOL) { 407 dsp = db_script_lookup(scriptname); 408 if (dsp == NULL) { 409 db_printf("script '%s' not found\n", scriptname); 410 db_skip_to_eol(); 411 return; 412 } 413 db_printf("%s=%s\n", scriptname, dsp->ds_script); 414 } else if (t == tEQ) { 415 buf = db_get_line(); 416 if (buf[strlen(buf)-1] == '\n') 417 buf[strlen(buf)-1] = '\0'; 418 error = db_script_set(scriptname, buf); 419 if (error != 0) 420 db_printf("Error: %d\n", error); 421 } else 422 db_printf("?\n"); 423 db_skip_to_eol(); 424 } 425 426 /* 427 * Remove a named script. 428 */ 429 void 430 db_unscript_cmd(db_expr_t addr, bool have_addr, db_expr_t count, 431 char *modif) 432 { 433 int error, t; 434 435 t = db_read_token(); 436 if (t != tIDENT) { 437 db_printf("?\n"); 438 db_skip_to_eol(); 439 return; 440 } 441 442 error = db_script_unset(db_tok_string); 443 if (error == ENOENT) { 444 db_printf("script '%s' not found\n", db_tok_string); 445 db_skip_to_eol(); 446 return; 447 } 448 db_skip_to_eol(); 449 } 450 451 /* 452 * Sysctls for managing DDB scripting: 453 * 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 457 * 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. 462 */ 463 static SYSCTL_NODE(_debug_ddb, OID_AUTO, scripting, CTLFLAG_RW, 0, 464 "DDB script settings"); 465 466 static int 467 sysctl_debug_ddb_scripting_scripts(SYSCTL_HANDLER_ARGS) 468 { 469 struct sbuf sb; 470 int error, i, len; 471 char *buffer; 472 473 /* 474 * Make space to include a maximum-length name, = symbol, 475 * maximum-length script, and carriage return for every script that 476 * may be defined. 477 */ 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) 484 continue; 485 (void)sbuf_printf(&sb, "%s=%s\n", 486 db_script_table[i].ds_scriptname, 487 db_script_table[i].ds_script); 488 } 489 mtx_unlock(&db_script_mtx); 490 sbuf_finish(&sb); 491 error = SYSCTL_OUT(req, sbuf_data(&sb), sbuf_len(&sb) + 1); 492 sbuf_delete(&sb); 493 free(buffer, M_TEMP); 494 return (error); 495 } 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"); 499 500 static int 501 sysctl_debug_ddb_scripting_script(SYSCTL_HANDLER_ARGS) 502 { 503 char *buffer, *script, *scriptname; 504 int error, len; 505 506 /* 507 * Maximum length for an input string is DB_MAXSCRIPTNAME + '=' 508 * symbol + DB_MAXSCRIPT. 509 */ 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); 513 if (error) 514 goto out; 515 516 /* 517 * Argument will be in form scriptname=script, so split into the 518 * scriptname and script. 519 */ 520 script = buffer; 521 scriptname = strsep(&script, "="); 522 if (script == NULL) { 523 error = EINVAL; 524 goto out; 525 } 526 mtx_lock(&db_script_mtx); 527 error = db_script_set(scriptname, script); 528 mtx_unlock(&db_script_mtx); 529 out: 530 free(buffer, M_TEMP); 531 return (error); 532 } 533 SYSCTL_PROC(_debug_ddb_scripting, OID_AUTO, script, CTLTYPE_STRING | 534 CTLFLAG_RW, 0, 0, sysctl_debug_ddb_scripting_script, "A", 535 "Set a script"); 536 537 /* 538 * debug.ddb.scripting.unscript has somewhat unusual sysctl semantics -- set 539 * the name of the script that you want to delete. 540 */ 541 static int 542 sysctl_debug_ddb_scripting_unscript(SYSCTL_HANDLER_ARGS) 543 { 544 char name[DB_MAXSCRIPTNAME]; 545 int error; 546 547 bzero(name, sizeof(name)); 548 error = sysctl_handle_string(oidp, name, sizeof(name), req); 549 if (error) 550 return (error); 551 if (req->newptr == NULL) 552 return (0); 553 mtx_lock(&db_script_mtx); 554 error = db_script_unset(name); 555 mtx_unlock(&db_script_mtx); 556 if (error == ENOENT) 557 return (EINVAL); /* Don't confuse sysctl consumers. */ 558 return (0); 559 } 560 SYSCTL_PROC(_debug_ddb_scripting, OID_AUTO, unscript, CTLTYPE_STRING | 561 CTLFLAG_RW, 0, 0, sysctl_debug_ddb_scripting_unscript, "A", 562 "Unset a script"); 563