.\"	$NetBSD: ddb.9,v 1.3 2020/10/31 10:48:17 wiz 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
argument 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
argument 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 the 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 the
.Ic help
command if the kernel was compiled with the
.Dv DDB_VERBOSE_HELP
option.
.\"
.Sh SEE ALSO
.Xr ddb 4