svn commit: r294011 - head/share/man/man4

[Bruce Evans]

On Thu, 14 Jan 2016, Warner Losh wrote:

> Log:
>  Document how to enter the debugger here. I'm sure there's some better
>  canonical place, and the nit-pickers are welcome to move this
>  information there with a cross reference.
> ...
> Modified: head/share/man/man4/ddb.4
> ==============================================================================
> --- head/share/man/man4/ddb.4	Thu Jan 14 16:21:58 2016	(r294010)
> +++ head/share/man/man4/ddb.4	Thu Jan 14 16:23:07 2016	(r294011)
> @@ -1435,6 +1435,47 @@ The NMI allows one to break into the deb
> ...
> +.Pp
> +For serial consoles, you can break to the debugger by sending a BREAK
> +condition on the serial line if
> +.Cd options BREAK_TO_DEBUGGER
> +is specified in the kernel.
> +Most terminal emulation programs can send a break sequence with a
> +special key sequence or via a menu item.
> +However, in some setups, sending the break can be difficult to arrange
> +or happens spuriously, so if the kernel contains

This is all quite broken, though the above description is almost correct.

The BREAK_TO_DEBUGGER option used to mean: enter (not break into) the
debugger using a serial line break.  This is a good method, except it
is too easy to get serial line breaks.  Unplugging the cable usually
gives on, and turning off the other end might give one.  So this method
is only usable on local systems with secure cables that you don't trip
over or otherwise disconnect).

This option was broken to mean: the default for the sysctl that controls
"breaking into" the debugger using either a serial line break or the console
key for "breaking into" the debugger.  For almost perfection confusion,
this key is normally the "Ctrl-Print Screen" key on PC keyboards and
there is a "Break" key nearby.  Ctrl-Alt-Esc also works.  syscons(4)
misdocuments the latter as Alt-Esc.  Under WinDOS, the Break key normally
needs Ctrl to make it do anything, but under FreeBSD (syscons), Ctrl-
Break is an alias for Scroll Lock.

If you actually have a serial console, then you should normally not
configure BREAK_TO_DEBUGGER since it gives the problems with cables,
but this breaks the console keys.  You can reenable them using the
sysctl, but this also enables entry for serial line breaks since there
is no longer any ifdef to keep the code for that out of the kernel,
and no runtime option to control it independently of other console
drivers.

There is a maze of compile-time options and sysctls to give further
control for non-serial consoles.  These are of course spelled differently
so they are hard to find.  For syscons, DISABLE_KDBKEY removes the code
for all debugger entry keys.  Here KDBKEY has a nice confusing name.  It
looks a bit like KBDKEY (keyboard key) but actual meant
"kernel debugger key" and now means "all key sequences that might lead
to the kernel debugger".  The corresponding runtime option is of course
spelled differently, with kbd instead of kdb.  It is hw.syscons.kbd_debug.

The maze is different and more broken in vt.  There is no option like
DISABLE_KDBKEY.  The 2 different types of key sequences for entering the
debugger are misconfigured differently:
- "alt-break" sequence: this is ifdefed with KDB so it is unreachable unless
   KDB is configured
- "break" key: kdb has a stub that can be called even when KDB is not
   configured.  The stub does a wrong thing (doesn't print a warning if
   KDB is not configured; similarly if KDB is configured but no back end
   is attached).  This is gated by the sysctl, unlike "alt-break".
The sysctl has been partly fixed to have a similar name.  It now has
the same leaf name but is under kern instead of hw (kern.vt.kbd_debug).

The sysctls are gated by each other, so none of them works as documented
and the maze must be understood to turn everything on or off.  Actually
there are separate gates for the 2 kdb sysctls.  The gate for the "break"
key normally defaults to off in kdb (since BREAK_TO_DEBUGGER is normally
not configured), and everthing else defaults to on, so to turn on the
"break" key it suffices to turn on the kdb gate for it, but that also
turns on serial breaks support.

vt also makes all the sysctls tunables and even documents this.  It
documents both "break" keys correctly.  The "alt-break" entries are
not documented in syscons(4) or vt(4).

> +.Cd options ALT_BREAK_TO_DEBUGGER

ALT_BREAK_TO_DEBUGGER was the start of the misnaming.  It means
"alternative method to a serial line break for entering the debugger"
but is usually read as "alternative method for breaking into the
debugger".

Not configuring this used to omit code for doing it.  Now the
configuration s soft.  The code is always there if KDB is, and this
option just gives the default for the sysctl that controls the
feature.

The sysctl for this is separate from the one for the "break" key,
and both are tunables.  These are the only tunables in kdb.  These
sysctls have bad names matching the options (with "break" that is
unrelated to serial line breaks in them) and similar descriptions.
The names and descriptions of the console driver's sysctls never
said "break".

> +then the sequence of CR TILDE CTRL-B enters the debugger;
> +CR TILDE CTRL-P causes a panic instead of entering the
> +debugger; and
> +CR TILDE CTRL-R causes an immediate reboot.

There are excessive knobs to control rebooting keys too.  syscons has
an option and a flag to control its reboot key.

This method of rebooting should never be used because its implementation
is broken.  Many kdb and ddb commands have a broken implementation,
since since it is invalid to call almost any non-ddb function from
ddb context.  The implementation is almost good enough for panic.
Calling panic from within ddb is invalid too, but if you are lucky it
will hang or panic recursively before doing any damage.

The suspend key doesn't have any knobs to control it AFAIK, and works
like the panic keys here.

I sometimes wish for a "signal" key that sends signals to selected
threads, especially to init to go to single user mode.

Bruce