ddb(9) - first cut at the documentation for writing and adding new DDB
commands. Not yet complete and not hooked into the build.
This commit is contained in:
uwe
parent
74ce69e5d7
commit
ed38e3002e
|
|
@ -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
|
||||
Loading…
Reference in New Issue