Module Name: src Committed By: uwe Date: Fri Oct 30 22:14:03 UTC 2020
Added Files: src/share/man/man9: ddb.9 Log Message: ddb(9) - first cut at the documentation for writing and adding new DDB commands. Not yet complete and not hooked into the build. To generate a diff of this commit: cvs rdiff -u -r0 -r1.1 src/share/man/man9/ddb.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Added files: Index: src/share/man/man9/ddb.9 diff -u /dev/null src/share/man/man9/ddb.9:1.1 --- /dev/null Fri Oct 30 22:14:03 2020 +++ src/share/man/man9/ddb.9 Fri Oct 30 22:14:03 2020 @@ -0,0 +1,162 @@ +.\" $NetBSD: ddb.9,v 1.1 2020/10/30 22:14:03 uwe Exp $ +.\" +.\" Copyright (c) 2020 Valery Ushakov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 30, 2020 +.Dt DDB 9 +.Os +.\" +.\" +.Sh NAME +.Nm ddb +.Nd in-kernel debugger +.\" +.\" +.Sh SYNOPSIS +.\" +.In ddb/ddb.h +.\" +.Ft int +.Fn db_register_tbl "uint8_t type" "const struct db_command *commands" +.\" +.Ft int +.Fn db_unregister_tbl "uint8_t type" "const struct db_command *commands" +.\" +.\" XXX: there's no typedef defined for this +.Ft void +.Fo "(*pf)" \" it seems there's no way to format this differently +.Fa "db_expr_t addr" +.Fa "bool have_addr" +.Fa "db_expr_t count" +.Fa "const char *modif" +.Fc +.\" +.\" - a macro, but document the types here +.Fo DDB_ADD_CMD +.Fa "const char *name" +.Fa "void (*pf)(db_expr_t, bool, db_expr_t, const char *)" +.Fa "uint16_t flags" +.Fa "const char *cmd_descr" +.Fa "const char *cmd_arg" +.Fa "const char *arg_desc" +.Fc +.\" +.Sh DESCRIPTION +Devices and kernel modules can add new commands to the +.Xr ddb 4 +in-kernel debugger with +.Fn db_register_tbl +and remove previously added commands with +.Fn db_unregister_tbl +respectively. +.Pp +The +.Fa type +argument is one of: +.Bl -tag -offset indent -width Dv +.\" +.It Dv DDB_BASE_CMD +top-level commands; +.\" +.It Dv DDB_MACH_CMD +sub-commands of the top-level +.Ic mach +command; +.\" +.It Dv DDB_SHOW_CMD +sub-commands of the top-level +.Ic show +command. +.\" +.El +.\" +.Pp +The +.Fa commands +is an array of +.Vt struct db_command\| +entries. +The initializer list for the array should use the +.Fn DDB_ADD_CMD +macro for its entries. +The +.Fa name +is the name of the debugger command. +An entry with +.Dv NULL +.Fa name +terminates the array. +.Pp +The +.Fa pf +argument is the function that implements the command. +The debugger's +.Tn REPL +parses the usual command format documented in +.Xr ddb 4 +and invokes the implementation with the values obtained. +.Pp +The +.Fa flags +argument is a bitwise +.Tn OR +of the following values: +.Bl -tag -offset indent -width Dv +.\" +.It Dv CS_MORE +The command takes the usual arguments but may additionally parse the +remainder of its command line. +.\" +.It Dv CS_NOREPEAT +The command should not be automatically repeated by the +.Tn REPL +when user enters an empty command after it. +.\" +.It Dv CS_OWN +The command doesn't follow the normal +.Xr ddb 4 +conventions and parses its command line itself. +The +.Tn REPL +doesn't try to parse the command line. +The values passed to its implementation are dummies. +.\" +.It Dv CS_SET_DOT +The command sets the +.Va dot . +.\" +.El +.\" +.Pp +The remaining parameters are strings that provide documentation for +the command and its arguments. +That documentation is available to the user via +.Ic help +command if the kernel was compiled with +.Dv DDB_VERBOSE_HELP +option. +.\" +.Sh SEE ALSO +.Xr ddb 4