From owner-svn-doc-head@FreeBSD.ORG Thu Oct 4 11:04:11 2012 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id E11E41065672; Thu, 4 Oct 2012 11:04:11 +0000 (UTC) (envelope-from issyl0@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id CA99C8FC27; Thu, 4 Oct 2012 11:04:11 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q94B4B6O037860; Thu, 4 Oct 2012 11:04:11 GMT (envelope-from issyl0@svn.freebsd.org) Received: (from issyl0@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q94B4Bpa037858; Thu, 4 Oct 2012 11:04:11 GMT (envelope-from issyl0@svn.freebsd.org) Message-Id: <201210041104.q94B4Bpa037858@svn.freebsd.org> From: Isabell Long Date: Thu, 4 Oct 2012 11:04:11 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r39652 - head/en_US.ISO8859-1/books/developers-handbook/kerneldebug X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 04 Oct 2012 11:04:12 -0000 Author: issyl0 Date: Thu Oct 4 11:04:11 2012 New Revision: 39652 URL: http://svn.freebsd.org/changeset/doc/39652 Log: Add a new section to the developer's handbook about kernel debugging with Dcons. Converted from the wiki page [1] by myself as part of Google Code-In 2011. [1] http://wiki.freebsd.org/DebugWithDcons Reviewed by: gavin Approved by: gabor (mentor) Modified: head/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml Modified: head/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml Thu Oct 4 01:21:04 2012 (r39651) +++ head/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml Thu Oct 4 11:04:11 2012 (r39652) @@ -786,6 +786,254 @@ Debugger (msg=0xf01b0383 "Boot flags req stack, and do a backtrace with where. + + Kernel debugging with Dcons + + &man.dcons.4; is a very simple console driver that is + not directly connected with any physical devices. It just reads + and writes characters from and to a buffer in a kernel or + loader. Due to its simple nature, it is very useful for kernel + debugging, especially with a &firewire; device. Currently, &os; + provides two ways to interact with the buffer from outside of + the kernel using &man.dconschat.8;. + + + Dcons over &firewire; + + Most &firewire; (IEEE1394) host controllers are + based on the OHCI specification that + supports physical access to the host memory. This means that + once the host controller is initialized, we can access the + host memory without the help of software (kernel). We can + exploit this facility for interaction with &man.dcons.4;. + &man.dcons.4; provides similar functionality as a serial + console. It emulates two serial ports, one for the console + and DDB, the other for + GDB. Because remote memory access is fully + handled by the hardware, the &man.dcons.4; buffer is + accessible even when the system crashes. + + &firewire; devices are not limited to those + integrated into motherboards. PCI cards + exist for desktops, and a cardbus interface can be purchased + for laptops. + + + Enabling &firewire; and Dcons support on the target + machine + + To enable &firewire; and Dcons support in the kernel of + the target machine: + + + + Make sure your kernel supports + dcons, dcons_crom + and firewire. + Dcons should be statically linked + with the kernel. For dcons_crom and + firewire, modules should be + OK. + + + Make sure physical DMA is enabled. + You may need to add + hw.firewire.phydma_enable=1 to + /boot/loader.conf. + + + Add options for debugging. + + + Add dcons_gdb=1 in + /boot/loader.conf if you use GDB + over &firewire;. + + + Enable dcons in + /etc/ttys. + + + Optionally, to force dcons to + be the high-level console, add + hw.firewire.dcons_crom.force_console=1 + to loader.conf. + + + + To enable &firewire; and Dcons support in &man.loader.8; + on i386 or amd64: + + Add + LOADER_FIREWIRE_SUPPORT=YES in + /etc/make.conf and rebuild + &man.loader.8;: + + &prompt.root; cd /sys/boot/i386 && make clean && make && make install + + To enable &man.dcons.4; as an active low-level + console, add boot_multicons="YES" to + /boot/loader.conf. + + Here are a few configuration examples. A sample kernel + configuration file would contain: + + device dcons +device dcons_crom +options KDB +options DDB +options GDB +options ALT_BREAK_TO_DEBUGGER + + And a sample /boot/loader.conf + would contain: + + dcons_crom_load="YES" +dcons_gdb=1 +boot_multicons="YES" +hw.firewire.phydma_enable=1 +hw.firewire.dcons_crom.force_console=1 + + + + + Enabling &firewire; and Dcons support on the host + machine + + To enable &firewire; support in the kernel on the + host machine: + + &prompt.root; kldload firewire + + Find out the EUI64 (the unique 64 + bit identifier) of the &firewire; host controller, and + use &man.fwcontrol.8; or dmesg to + find the EUI64 of the target machine. + + Run &man.dconschat.8;, with: + + &prompt.root; dconschat -e \# -br -G 12345 -t 00-11-22-33-44-55-66-77 + + The following key combinations can be used once + &man.dconschat.8; is running: + + + + + + + + ~ + . + + + Disconnect + + + + + ~ + + Ctrl + B + + + + ALT BREAK + + + + + ~ + + Ctrl + R + + + + RESET target + + + + + ~ + + Ctrl + Z + + + + Suspend dconschat + + + + + + Attach remote GDB by starting + &man.kgdb.1; with a remote debugging session: + + kgdb -r :12345 kernel + + + + Some general tips + + Here are some general tips: + + To take full advantage of the speed of &firewire;, + disable other slow console drivers: + + &prompt.root; conscontrol delete ttyd0 # serial console +&prompt.root; conscontrol delete consolectl # video/keyboard + + There exists a GDB mode for + &man.emacs.1;; this is what you will need to add to your + .emacs: + + (setq gud-gdba-command-name "kgdb -a -a -a -r :12345") +(setq gdb-many-windows t) +(xterm-mouse-mode 1) +M-x gdba + + And for DDD (devel/ddd): + + # remote serial protocol +LANG=C ddd --debugger kgdb -r :12345 kernel +# live core debug +LANG=C ddd --debugger kgdb kernel /dev/fwmem0.2 + + + + + Dcons with KVM + + We can directly read the &man.dcons.4; buffer via + /dev/mem for live systems, and in the + core dump for crashed systems. These give you similar output + to dmesg -a, but the &man.dcons.4; buffer + includes more information. + + + Using Dcons with KVM + + To use &man.dcons.4; with KVM: + + Dump a &man.dcons.4; buffer of a live system: + + &prompt.root; dconschat -1 + + Dump a &man.dcons.4; buffer of a crash dump: + + &prompt.root; dconschat -1 -M vmcore.XX + + Live core debugging can be done via: + + &prompt.root; fwcontrol -m target_eui64 +&prompt.root; kgdb kernel /dev/fwmem0.2 + + + + Glossary of Kernel Options for Debugging