sys/ddb/ddb.h

   1 /*-
   2  * SPDX-License-Identifier: BSD-3-Clause
   3  *
   4  * Copyright (c) 1993, Garrett A. Wollman.
   5  * Copyright (c) 1993, University of Vermont and State Agricultural College.
   6  * All rights reserved.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  * 1. Redistributions of source code must retain the above copyright
  12  *    notice, this list of conditions and the following disclaimer.
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in the
  15  *    documentation and/or other materials provided with the distribution.
  16  * 3. Neither the name of the University nor the names of its contributors
  17  *    may be used to endorse or promote products derived from this software
  18  *    without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  21  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  24  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30  * SUCH DAMAGE.
  31  */
  32
  33 /*
  34  * Necessary declarations for the `ddb' kernel debugger.
  35  */
  36
  37 #ifndef _DDB_DDB_H_
  38 #define _DDB_DDB_H_
  39
  40 #ifdef SYSCTL_DECL
  41 SYSCTL_DECL(_debug_ddb);
  42 #endif
  43
  44 #include <machine/db_machdep.h>         /* type definitions */
  45
  46 #include <sys/queue.h>                  /* LIST_* */
  47 #include <sys/kernel.h>                 /* SYSINIT */
  48
  49 #ifndef DB_MAXARGS
  50 #define DB_MAXARGS      10
  51 #endif
  52
  53 #ifndef DB_MAXLINE
  54 #define DB_MAXLINE      120
  55 #endif
  56
  57 #ifndef DB_MAXSCRIPTS
  58 #define DB_MAXSCRIPTS   8
  59 #endif
  60
  61 #ifndef DB_MAXSCRIPTNAME
  62 #define DB_MAXSCRIPTNAME        32
  63 #endif
  64
  65 #ifndef DB_MAXSCRIPTLEN
  66 #define DB_MAXSCRIPTLEN 128
  67 #endif
  68
  69 #ifndef DB_MAXSCRIPTRECURSION
  70 #define DB_MAXSCRIPTRECURSION   3
  71 #endif
  72
  73 #ifndef DB_CALL
  74 #define DB_CALL db_fncall_generic
  75 #else
  76 int     DB_CALL(db_expr_t, db_expr_t *, int, db_expr_t[]);
  77 #endif
  78
  79 /*
  80  * Extern variables to set the address and size of the symtab and strtab.
  81  * Most users should use db_fetch_symtab in order to set them from the
  82  * boot loader provided values.
  83  */
  84 extern vm_offset_t ksymtab, kstrtab, ksymtab_size, ksymtab_relbase;
  85
  86 /* Command tables contain a list of commands. */
  87 struct db_command;
  88 LIST_HEAD(db_command_table, db_command);
  89
  90 #define _DB_TABLE_NAME(table)   db_##table##_table
  91
  92 #define DB_DEFINE_TABLE(parent, name, table)                            \
  93         struct db_command_table _DB_TABLE_NAME(table) =                 \
  94             LIST_HEAD_INITIALIZER(_DB_TABLE_NAME(table));               \
  95         _DB_SET(parent, name, NULL, 0, &_DB_TABLE_NAME(table))
  96
  97 #define DB_DECLARE_TABLE(table)                                         \
  98         extern struct db_command_table _DB_TABLE_NAME(table)
  99
 100 /*
 101  * Builtin command tables:
 102  * - cmd: Top-level command table; a list of these is displayed
 103  *   by typing 'help' at the debugger prompt.
 104  * - show: Sub-commands of 'show'
 105  * - show_all: Sub-commands of 'show all'
 106  * - show_active: Sub-commands of 'show active'
 107  */
 108 DB_DECLARE_TABLE(cmd);
 109 DB_DECLARE_TABLE(show);
 110 DB_DECLARE_TABLE(show_all);
 111 DB_DECLARE_TABLE(show_active);
 112
 113 /*
 114  * Type signature for a function implementing a ddb command.
 115  */
 116 typedef void db_cmdfcn_t(db_expr_t addr, bool have_addr, db_expr_t count,
 117             char *modif);
 118
 119 /*
 120  * Command table entry.
 121  */
 122 struct db_command {
 123         char *name;             /* command name */
 124         db_cmdfcn_t *fcn;       /* function to call */
 125         int flag;
 126 #define CS_OWN          0x1     /* non-standard syntax */
 127 #define CS_MORE         0x2     /* standard syntax, but may have other words
 128                                  * at end */
 129 #define CS_SET_DOT      0x100   /* set dot after command */
 130 #define DB_CMD_MEMSAFE  0x1000  /* Command does not allow reads or writes to
 131                                  * arbitrary memory. */
 132 #define DB_MAC1         0x10000 /* For MAC policy use */
 133 #define DB_MAC2         0x20000
 134         struct db_command_table *more; /* another level of command */
 135         LIST_ENTRY(db_command) next; /* next entry in the command table */
 136         void *mac_priv;         /* For MAC policy use */
 137 };
 138
 139 /*
 140  * Arrange for the specified ddb command to be defined and
 141  * bound to the specified function.  Commands can be defined
 142  * in modules in which case they will be available only when
 143  * the module is loaded.
 144  */
 145 #define _DB_SET(_table, _name, _func, _flag, _more)             \
 146 static struct db_command db_##_table##_##_name##_cmd = {        \
 147         .name   = __STRING(_name),                              \
 148         .fcn    = _func,                                        \
 149         .flag   = _flag,                                        \
 150         .more   = _more                                         \
 151 };                                                              \
 152                                                                 \
 153 static void                                                     \
 154 db##_table##_##_name##_add(void *arg __unused)                  \
 155 {                                                               \
 156         db_command_register(&_DB_TABLE_NAME(_table),            \
 157             &db_##_table##_##_name##_cmd);                      \
 158 }                                                               \
 159 SYSINIT(db_##_table##_##_name, SI_SUB_KLD, SI_ORDER_ANY,        \
 160     db##_table##_##_name##_add, NULL);                          \
 161                                                                 \
 162 static void                                                     \
 163 db##_table##_##_name##_del(void *arg __unused)                  \
 164 {                                                               \
 165         db_command_unregister(&_DB_TABLE_NAME(_table),          \
 166             &db_##_table##_##_name##_cmd);                      \
 167 }                                                               \
 168 SYSUNINIT(db_##_table##_##_name, SI_SUB_KLD, SI_ORDER_ANY,      \
 169     db##_table##_##_name##_del, NULL)
 170
 171 /*
 172  * Like _DB_SET but also create the function declaration which
 173  * must be followed immediately by the body; e.g.
 174  *   DB_TABLE_COMMAND_FLAGS(_cmd, panic, db_panic, 0)
 175  *   {
 176  *      ...panic implementation...
 177  *   }
 178  *
 179  * This macro is mostly used to define commands placed in one of
 180  * the ddb command tables; see DB_COMMAND, etc. below.
 181  */
 182 #define DB_TABLE_COMMAND_FLAGS(_table, _name, _func, _flag)     \
 183 static db_cmdfcn_t _func;                                       \
 184 _DB_SET(_table, _name, _func, _flag, NULL);                     \
 185 static void                                                     \
 186 _func(db_expr_t addr, bool have_addr, db_expr_t count, char *modif)
 187
 188 #define DB_TABLE_COMMAND(_table, _name, _func)                  \
 189         DB_TABLE_COMMAND_FLAGS(_table, _name, _func, 0)
 190
 191 /* Wrappers around _DB_SET used for aliases. */
 192 #define DB_TABLE_ALIAS_FLAGS(_table, _name, _func, _flag)       \
 193         _DB_SET(_table, _name, _func, _flag, NULL)
 194 #define DB_TABLE_ALIAS(_table, _name, _func)                    \
 195         DB_TABLE_ALIAS_FLAGS(_table, _name, _func, 0)
 196
 197 #define DB_COMMAND_FLAGS(cmd_name, func_name, flags) \
 198         DB_TABLE_COMMAND_FLAGS(cmd, cmd_name, func_name, flags)
 199 #define DB_COMMAND(cmd_name, func_name) \
 200         DB_COMMAND_FLAGS(cmd_name, func_name, 0)
 201 #define DB_ALIAS_FLAGS(alias_name, func_name, flags) \
 202         DB_TABLE_ALIAS_FLAGS(cmd, alias_name, func_name, flags)
 203 #define DB_ALIAS(alias_name, func_name) \
 204         DB_ALIAS_FLAGS(alias_name, func_name, 0)
 205 #define DB_SHOW_COMMAND_FLAGS(cmd_name, func_name, flags) \
 206         DB_TABLE_COMMAND_FLAGS(show, cmd_name, func_name, flags)
 207 #define DB_SHOW_COMMAND(cmd_name, func_name) \
 208         DB_SHOW_COMMAND_FLAGS(cmd_name, func_name, 0)
 209 #define DB_SHOW_ALIAS_FLAGS(alias_name, func_name, flags) \
 210         DB_TABLE_ALIAS_FLAGS(show, alias_name, func_name, flags)
 211 #define DB_SHOW_ALIAS(alias_name, func_name) \
 212         DB_SHOW_ALIAS_FLAGS(alias_name, func_name, 0)
 213 #define DB_SHOW_ALL_COMMAND(cmd_name, func_name)                        \
 214         DB_TABLE_COMMAND_FLAGS(show_all, cmd_name, func_name, DB_CMD_MEMSAFE)
 215 #define DB_SHOW_ALL_ALIAS(alias_name, func_name)                        \
 216         DB_TABLE_ALIAS_FLAGS(show_all, alias_name, func_name, DB_CMD_MEMSAFE)
 217
 218 extern db_expr_t db_maxoff;
 219 extern int db_indent;
 220 extern int db_inst_count;
 221 extern int db_load_count;
 222 extern int db_store_count;
 223 extern volatile int db_pager_quit;
 224 extern db_expr_t db_radix;
 225 extern db_expr_t db_max_width;
 226 extern db_expr_t db_tab_stop_width;
 227 extern db_expr_t db_lines_per_page;
 228
 229 struct thread;
 230 struct vm_map;
 231
 232 void            db_check_interrupt(void);
 233 void            db_clear_watchpoints(void);
 234 db_addr_t       db_disasm(db_addr_t loc, bool altfmt);
 235                                 /* instruction disassembler */
 236 void            db_error(const char *s);
 237 int             db_expression(db_expr_t *valuep);
 238 int             db_getc(void);
 239 int             db_get_variable(db_expr_t *valuep);
 240 void            db_iprintf(const char *,...) __printflike(1, 2);
 241 struct proc     *db_lookup_proc(db_expr_t addr);
 242 struct thread   *db_lookup_thread(db_expr_t addr, bool check_pid);
 243 struct vm_map   *db_map_addr(vm_offset_t);
 244 bool            db_map_current(struct vm_map *);
 245 bool            db_map_equal(struct vm_map *, struct vm_map *);
 246 void            db_md_list_watchpoints(void);
 247 void            db_print_loc_and_inst(db_addr_t loc);
 248 void            db_print_thread(void);
 249 int             db_printf(const char *fmt, ...) __printflike(1, 2);
 250 int             db_read_bytes(vm_offset_t addr, size_t size, char *data);
 251                                 /* machine-dependent */
 252 int             db_readline(char *lstart, int lsize);
 253 void            db_restart_at_pc(bool watchpt);
 254 int             db_set_variable(db_expr_t value);
 255 void            db_set_watchpoints(void);
 256 void            db_skip_to_eol(void);
 257 bool            db_stop_at_pc(int type, int code, bool *is_breakpoint,
 258                     bool *is_watchpoint);
 259 #define         db_strcpy       strcpy
 260 void            db_trace_self(void);
 261 int             db_trace_thread(struct thread *, int);
 262 bool            db_value_of_name(const char *name, db_expr_t *valuep);
 263 bool            db_value_of_name_pcpu(const char *name, db_expr_t *valuep);
 264 bool            db_value_of_name_vnet(const char *name, db_expr_t *valuep);
 265 int             db_write_bytes(vm_offset_t addr, size_t size, char *data);
 266 void            db_command_register(struct db_command_table *,
 267                     struct db_command *);
 268 void            db_command_unregister(struct db_command_table *,
 269                     struct db_command *);
 270 int             db_fetch_ksymtab(vm_offset_t ksym_start, vm_offset_t ksym_end,
 271                     vm_offset_t relbase);
 272
 273 db_cmdfcn_t     db_breakpoint_cmd;
 274 db_cmdfcn_t     db_capture_cmd;
 275 db_cmdfcn_t     db_continue_cmd;
 276 db_cmdfcn_t     db_delete_cmd;
 277 db_cmdfcn_t     db_deletehwatch_cmd;
 278 db_cmdfcn_t     db_deletewatch_cmd;
 279 db_cmdfcn_t     db_examine_cmd;
 280 db_cmdfcn_t     db_findstack_cmd;
 281 db_cmdfcn_t     db_hwatchpoint_cmd;
 282 db_cmdfcn_t     db_listbreak_cmd;
 283 db_cmdfcn_t     db_scripts_cmd;
 284 db_cmdfcn_t     db_print_cmd;
 285 db_cmdfcn_t     db_ps;
 286 db_cmdfcn_t     db_run_cmd;
 287 db_cmdfcn_t     db_script_cmd;
 288 db_cmdfcn_t     db_search_cmd;
 289 db_cmdfcn_t     db_set_cmd;
 290 db_cmdfcn_t     db_set_thread;
 291 db_cmdfcn_t     db_show_regs;
 292 db_cmdfcn_t     db_show_threads;
 293 db_cmdfcn_t     db_single_step_cmd;
 294 db_cmdfcn_t     db_textdump_cmd;
 295 db_cmdfcn_t     db_trace_until_call_cmd;
 296 db_cmdfcn_t     db_trace_until_matching_cmd;
 297 db_cmdfcn_t     db_unscript_cmd;
 298 db_cmdfcn_t     db_watchpoint_cmd;
 299 db_cmdfcn_t     db_write_cmd;
 300
 301 /*
 302  * Interface between DDB and the DDB output capture facility.
 303  */
 304 struct dumperinfo;
 305 void    db_capture_dump(struct dumperinfo *di);
 306 void    db_capture_enterpager(void);
 307 void    db_capture_exitpager(void);
 308 void    db_capture_write(char *buffer, u_int buflen);
 309 void    db_capture_writech(char ch);
 310
 311 /*
 312  * Interface between DDB  and the script facility.
 313  */
 314 void    db_script_kdbenter(const char *eventname);      /* KDB enter event. */
 315
 316 /*
 317  * Interface between DDB and the textdump facility.
 318  *
 319  * Text dump blocks are of a fixed size; textdump_block_buffer is a
 320  * statically allocated buffer that code interacting with textdumps can use
 321  * to prepare and hold a pending block in when calling writenextblock().
 322  */
 323 #define TEXTDUMP_BLOCKSIZE      512
 324 extern char     textdump_block_buffer[TEXTDUMP_BLOCKSIZE];
 325
 326 void    textdump_mkustar(char *block_buffer, const char *filename,
 327             u_int size);
 328 void    textdump_restoreoff(off_t offset);
 329 void    textdump_saveoff(off_t *offsetp);
 330 int     textdump_writenextblock(struct dumperinfo *di, char *buffer);
 331
 332 /*
 333  * Interface between the kernel and textdumps.
 334  */
 335 extern int      textdump_pending;       /* Call textdump_dumpsys() instead. */
 336 void    textdump_dumpsys(struct dumperinfo *di);
 337
 338 #endif /* !_DDB_DDB_H_ */