From owner-svn-src-all@freebsd.org Thu Jan 14 19:27:17 2016 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id E779EA82215; Thu, 14 Jan 2016 19:27:16 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail105.syd.optusnet.com.au (mail105.syd.optusnet.com.au [211.29.132.249]) by mx1.freebsd.org (Postfix) with ESMTP id B0A9919C5; Thu, 14 Jan 2016 19:27:16 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from c211-30-166-197.carlnfd1.nsw.optusnet.com.au (c211-30-166-197.carlnfd1.nsw.optusnet.com.au [211.30.166.197]) by mail105.syd.optusnet.com.au (Postfix) with ESMTPS id 0B0CB1043102; Fri, 15 Jan 2016 06:27:07 +1100 (AEDT) Date: Fri, 15 Jan 2016 06:27:05 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Warner Losh cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r294011 - head/share/man/man4 In-Reply-To: <201601141623.u0EGN7me063431@repo.freebsd.org> Message-ID: <20160115044315.T9902@besplex.bde.org> References: <201601141623.u0EGN7me063431@repo.freebsd.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Optus-CM-Score: 0 X-Optus-CM-Analysis: v=2.1 cv=cK4dyQqN c=1 sm=1 tr=0 a=KA6XNC2GZCFrdESI5ZmdjQ==:117 a=PO7r1zJSAAAA:8 a=L9H7d07YOLsA:10 a=9cW_t1CCXrUA:10 a=s5jvgZ67dGcA:10 a=JzwRw_2MAAAA:8 a=kj9zAlcOel0A:10 a=ZLDtgeUadiggRli_pP4A:9 a=CjuIK1q_8ugA:10 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 14 Jan 2016 19:27:17 -0000 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