1.\" $NetBSD: ddb.9,v 1.3 2020/10/31 10:48:17 wiz Exp $ 2.\" 3.\" Copyright (c) 2020 Valery Ushakov 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 20.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 22.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 23.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd October 30, 2020 28.Dt DDB 9 29.Os 30.\" 31.\" 32.Sh NAME 33.Nm ddb 34.Nd in-kernel debugger 35.\" 36.\" 37.Sh SYNOPSIS 38.\" 39.In ddb/ddb.h 40.\" 41.Ft int 42.Fn db_register_tbl "uint8_t type" "const struct db_command *commands" 43.\" 44.Ft int 45.Fn db_unregister_tbl "uint8_t type" "const struct db_command *commands" 46.\" 47.\" XXX: there's no typedef defined for this 48.Ft void 49.Fo "(*pf)" \" it seems there's no way to format this differently 50.Fa "db_expr_t addr" 51.Fa "bool have_addr" 52.Fa "db_expr_t count" 53.Fa "const char *modif" 54.Fc 55.\" 56.\" - a macro, but document the types here 57.Fo DDB_ADD_CMD 58.Fa "const char *name" 59.Fa "void (*pf)(db_expr_t, bool, db_expr_t, const char *)" 60.Fa "uint16_t flags" 61.Fa "const char *cmd_descr" 62.Fa "const char *cmd_arg" 63.Fa "const char *arg_desc" 64.Fc 65.\" 66.Sh DESCRIPTION 67Devices and kernel modules can add new commands to the 68.Xr ddb 4 69in-kernel debugger with 70.Fn db_register_tbl 71and remove previously added commands with 72.Fn db_unregister_tbl 73respectively. 74.Pp 75The 76.Fa type 77argument is one of: 78.Bl -tag -offset indent -width Dv 79.\" 80.It Dv DDB_BASE_CMD 81top-level commands; 82.\" 83.It Dv DDB_MACH_CMD 84sub-commands of the top-level 85.Ic mach 86command; 87.\" 88.It Dv DDB_SHOW_CMD 89sub-commands of the top-level 90.Ic show 91command. 92.\" 93.El 94.\" 95.Pp 96The 97.Fa commands 98argument is an array of 99.Vt struct db_command\| 100entries. 101The initializer list for the array should use the 102.Fn DDB_ADD_CMD 103macro for its entries. 104The 105.Fa name 106argument is the name of the debugger command. 107An entry with 108.Dv NULL 109.Fa name 110terminates the array. 111.Pp 112The 113.Fa pf 114argument is the function that implements the command. 115The debugger's 116.Tn REPL 117parses the usual command format documented in 118.Xr ddb 4 119and invokes the implementation with the values obtained. 120.Pp 121The 122.Fa flags 123argument is a bitwise 124.Tn OR 125of the following values: 126.Bl -tag -offset indent -width Dv 127.\" 128.It Dv CS_MORE 129The command takes the usual arguments but may additionally parse the 130remainder of its command line. 131.\" 132.It Dv CS_NOREPEAT 133The command should not be automatically repeated by the 134.Tn REPL 135when the user enters an empty command after it. 136.\" 137.It Dv CS_OWN 138The command doesn't follow the normal 139.Xr ddb 4 140conventions and parses its command line itself. 141The 142.Tn REPL 143doesn't try to parse the command line. 144The values passed to its implementation are dummies. 145.\" 146.It Dv CS_SET_DOT 147The command sets the 148.Va dot . 149.\" 150.El 151.\" 152.Pp 153The remaining parameters are strings that provide documentation for 154the command and its arguments. 155That documentation is available to the user via the 156.Ic help 157command if the kernel was compiled with the 158.Dv DDB_VERBOSE_HELP 159option. 160.\" 161.Sh SEE ALSO 162.Xr ddb 4 163