git: 94f6ee56e316 - main - ddb(4): misc updates
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Fri, 11 Nov 2022 18:26:26 UTC
The branch main has been updated by mhorne:
URL: https://cgit.FreeBSD.org/src/commit/?id=94f6ee56e316be5648054e15f58dde9bd2c1c2c6
commit 94f6ee56e316be5648054e15f58dde9bd2c1c2c6
Author: Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2022-11-11 18:21:29 +0000
Commit: Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2022-11-11 18:25:38 +0000
ddb(4): misc updates
- Describe optional 'addr' argument to many show commands
- Remove obsolete commands (show cbstat)
- 'show jails' was renamed to 'show prison'
- Remove superfluous commentary about sleepqueues
- Fix an xref to gdb(4)
- Fix issues reported by mandoc -Tlint
- Plus a couple other inaccuracies/inconsistencies
Reviewed by: pauamma, markj, jhb
MFC after: 1 week
Sponsored by: The FreeBSD Foundation (in part)
Differential Revision: https://reviews.freebsd.org/D37332
---
share/man/man4/ddb.4 | 146 +++++++++++++++++++++++----------------------------
1 file changed, 65 insertions(+), 81 deletions(-)
diff --git a/share/man/man4/ddb.4 b/share/man/man4/ddb.4
index f8bf45c62c73..cd7cecca4d61 100644
--- a/share/man/man4/ddb.4
+++ b/share/man/man4/ddb.4
@@ -26,7 +26,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd March 14, 2021
+.Dd November 10, 2022
.Dt DDB 4
.Os
.Sh NAME
@@ -58,7 +58,7 @@ representation, define:
.Ed
.Pp
To enable the
-.Xr gdb 1 Pq Pa ports/devel/gdb
+.Xr gdb 4
backend, so that remote debugging with
.Xr kgdb 1 Pq Pa ports/devel/gdb
is possible, include:
@@ -182,11 +182,8 @@ command line editing capabilities.
In addition to
the
.Nm emacs
-control keys, the usual
-.Tn ANSI
-arrow keys may be used to
-browse through the history buffer, and move the cursor within the
-current line.
+control keys, the usual ANSI arrow keys may be used to browse through the
+history buffer, and move the cursor within the current line.
.Sh COMMANDS
.Ss COMMON DEBUGGER COMMANDS
.Bl -tag -width indent -compact
@@ -246,8 +243,8 @@ The location is also displayed in hex at the beginning of each line.
.It Cm i
display as a disassembled instruction
.It Cm I
-display as an disassembled instruction with possible alternate formats depending on the
-machine.
+display as a disassembled instruction with possible alternate formats
+depending on the machine.
On i386, this selects the alternate format for the instruction decoding
(16 bits in a 32-bit code segment and vice versa).
.It Cm S
@@ -548,11 +545,9 @@ otherwise.
.Ic findstack
.Ar addr
.Xc
-Prints the thread address for a thread kernel-mode stack of which contains the
-specified address.
-If the thread is not found, search the thread stack cache and prints the
-cached stack address.
-Otherwise, prints nothing.
+Prints the address of the thread whose kernel-mode stack contains
+.Ar addr ,
+if any.
.Pp
.It Ic show Cm all procs Ns Op Li / Ns Cm a
.It Ic ps Ns Op Li / Ns Cm a
@@ -640,19 +635,18 @@ present at
.Ar addr .
.\"
.Pp
-.It Ic show Cm cbstat
-Show brief information about the TTY subsystem.
-.\"
-.Pp
-.It Ic show Cm cdev
-Without argument, show the list of all created cdev's, consisting of devfs
-node name and struct cdev address.
-When address of cdev is supplied, show some internal devfs state of the cdev.
+.It Ic show Cm cdev Op Ar addr
+Show the internal devfs state of the cdev structure located at
+.Ar addr .
+If no argument is provided, show the list of all created cdevs, consisting of
+the devfs node name and the
+.Vt struct cdev
+address.
.\"
.Pp
.It Ic show Cm conifhk
Lists hooks currently waiting for completion in
-run_interrupt_driven_config_hooks().
+.Fn run_interrupt_driven_config_hooks .
.\"
.Pp
.It Ic show Cm cpusets
@@ -756,15 +750,6 @@ Dump the interrupt statistics.
Show interrupt lines and their respective kernel threads.
.\"
.Pp
-.It Ic show Cm jails
-Show the list of
-.Xr jail 8
-instances.
-In addition to what
-.Xr jls 8
-shows, also list kernel internal details.
-.\"
-.Pp
.It Ic show Cm lapic
Show information from the local APIC registers for this CPU.
.\"
@@ -773,24 +758,24 @@ Show information from the local APIC registers for this CPU.
Show lock structure.
The output format is as follows:
.Bl -tag -width "flags"
-.It Ic class:
+.It Ic class :
Class of the lock.
Possible types include
.Xr mutex 9 ,
.Xr rmlock 9 ,
.Xr rwlock 9 ,
.Xr sx 9 .
-.It Ic name:
+.It Ic name :
Name of the lock.
-.It Ic flags:
+.It Ic flags :
Flags passed to the lock initialization function.
.Em flags
values are lock class specific.
-.It Ic state:
+.It Ic state :
Current state of a lock.
.Em state
values are lock class specific.
-.It Ic owner:
+.It Ic owner :
Lock owner.
.El
.\"
@@ -870,11 +855,14 @@ It is useful if you got a kernel panic, attached a serial cable
to the machine and want to get the boot messages from before the
system hang.
.\"
-.It Ic show Cm mount
-Displays short info about all currently mounted file systems.
.Pp
-.It Ic show Cm mount Ar addr
-Displays details about the given mount point.
+.It Ic show Cm mount Op Ar addr
+Displays details about the mount point located at
+.Ar addr .
+If no
+.Ar addr
+is specified,
+displays short info about all currently mounted file systems.
.\"
.Pp
.It Ic show Cm object Ns Oo Li / Ns Cm f Oc Ar addr
@@ -932,16 +920,24 @@ Names of spin locks held.
Dump process groups present within the system.
.\"
.Pp
-.It Ic show Cm proc Op Ar addr
-If no
-.Op Ar addr
-is specified, print information about the current process.
-Otherwise, show information about the process at address
+.It Ic show Cm prison Op Ar addr
+Show the prison structure located at
.Ar addr .
+If no
+.Ar addr
+argument is specified, show information about all prisons in the system.
.\"
.Pp
-.It Ic show Cm procvm
-Show process virtual memory layout.
+.It Ic show Cm proc Op Ar addr
+Show information about the process structure located at address
+.Ar addr ,
+or the current process if no argument is specified.
+.\"
+.Pp
+.It Ic show Cm procvm Op Ar addr
+Show process virtual memory layout for the process located at
+.Ar addr ,
+or the current process if no argument is specified.
.\"
.Pp
.It Ic show Cm protosw Ar addr
@@ -994,36 +990,26 @@ Now an alias for
.Ic show Cm lockchain .
.\"
.Pp
-.It Ic show Cm sleepq
-.It Ic show Cm sleepqueue
-Both commands provide the same functionality.
-They show sleepqueue
-.Vt struct sleepqueue
-structure.
-Sleepqueues are used within the
-.Fx
-kernel to implement sleepable
-synchronization primitives (thread holding a lock might sleep or
-be context switched), which at the time of writing are:
-.Xr condvar 9 ,
-.Xr sx 9
-and standard
-.Xr msleep 9
-interface.
+.It Ic show Cm sleepq Ar addr
+.It Ic show Cm sleepqueue Ar addr
+Show the
+.Xr sleepqueue 9
+structure located at
+.Ar addr .
.\"
.Pp
.It Ic show Cm sockbuf Ar addr
+Show the socket buffer
+.Va struct sockbuf
+located at
+.Ar addr .
+.\"
+.Pp
.It Ic show Cm socket Ar addr
-Those commands print
-.Vt struct sockbuf
-and
+Show the socket object
.Vt struct socket
-objects placed at
+located at
.Ar addr .
-Output consists of all values present in structures mentioned.
-For exact interpretation and more details, visit
-.Pa sys/socket.h
-header file.
.\"
.Pp
.It Ic show Cm sysregs
@@ -1141,11 +1127,8 @@ and none have zero ref counts.
.\"
.Pp
.It Ic show Cm vmopag
-This is supposed to show physical addresses consumed by a
-VM object.
-Currently, it is not possible to use this command when
-.Xr witness 4
-is compiled in the kernel.
+Walk the list of VM objects in the system, printing the indices and physical
+addresses of the VM pages belonging to each object.
.\"
.Pp
.It Ic show Cm vnet Ar addr
@@ -1155,11 +1138,11 @@ structure present at the address
.Ar addr .
.\"
.Pp
-.It Ic show Cm vnode Op Ar addr
+.It Ic show Cm vnode Ar addr
Prints vnode
.Vt struct vnode
structure lying at
-.Op Ar addr .
+.Ar addr .
For the exact interpretation of the output, look at the
.Pa sys/vnode.h
header file.
@@ -1552,8 +1535,8 @@ CR TILDE CTRL-R causes an immediate reboot.
In all these sequences, CR represents Carriage Return and is usually
sent by pressing the Enter or Return key.
TILDE is the ASCII tilde character (~).
-CTRL-x is Control x, send by pressing the Control key, then x, then releasing both.
-and then releasing both.
+CTRL-x is Control x, sent by pressing the Control key, then x, then releasing
+both.
.Pp
The break-to-debugger behavior can be enabled by setting
.Xr sysctl 8
@@ -1602,6 +1585,7 @@ directory.
.Xr kgdb 1 Pq Pa ports/devel/gdb ,
.Xr acpi 4 ,
.Xr CAM 4 ,
+.Xr gdb 4 ,
.Xr mac_ddb 4 ,
.Xr mac_test 4 ,
.Xr netgraph 4 ,