Date: Thu, 4 Oct 2012 11:04:11 +0000 (UTC) From: Isabell Long <issyl0@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r39652 - head/en_US.ISO8859-1/books/developers-handbook/kerneldebug Message-ID: <201210041104.q94B4Bpa037858@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 <command>where</command>.</para> </sect1> + <sect1 id="kerneldebug-dcons"> + <title>Kernel debugging with Dcons</title> + + <para>&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;.</para> + + <sect2> + <title>Dcons over &firewire;</title> + + <para>Most &firewire; (IEEE1394) host controllers are + based on the <acronym>OHCI</acronym> 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 <acronym>DDB</acronym>, the other for + <acronym>GDB</acronym>. Because remote memory access is fully + handled by the hardware, the &man.dcons.4; buffer is + accessible even when the system crashes.</para> + + <para>&firewire; devices are not limited to those + integrated into motherboards. <acronym>PCI</acronym> cards + exist for desktops, and a cardbus interface can be purchased + for laptops.</para> + + <sect3> + <title>Enabling &firewire; and Dcons support on the target + machine</title> + + <para>To enable &firewire; and Dcons support in the kernel of + the <emphasis>target machine</emphasis>:</para> + + <itemizedlist> + <listitem> + <para>Make sure your kernel supports + <literal>dcons</literal>, <literal>dcons_crom</literal> + and <literal>firewire</literal>. + <literal>Dcons</literal> should be statically linked + with the kernel. For <literal>dcons_crom</literal> and + <literal>firewire</literal>, modules should be + OK.</para> + </listitem> + <listitem> + <para>Make sure physical <acronym>DMA</acronym> is enabled. + You may need to add + <literal>hw.firewire.phydma_enable=1</literal> to + <filename>/boot/loader.conf</filename>.</para> + </listitem> + <listitem> + <para>Add options for debugging.</para> + </listitem> + <listitem> + <para>Add <literal>dcons_gdb=1</literal> in + <filename>/boot/loader.conf</filename> if you use GDB + over &firewire;.</para> + </listitem> + <listitem> + <para>Enable <literal>dcons</literal> in + <filename>/etc/ttys</filename>.</para> + </listitem> + <listitem> + <para>Optionally, to force <literal>dcons</literal> to + be the high-level console, add + <literal>hw.firewire.dcons_crom.force_console=1</literal> + to <filename>loader.conf</filename>.</para> + </listitem> + </itemizedlist> + + <para>To enable &firewire; and Dcons support in &man.loader.8; + on i386 or amd64:</para> + + <para>Add + <literal>LOADER_FIREWIRE_SUPPORT=YES</literal> in + <filename>/etc/make.conf</filename> and rebuild + &man.loader.8;:</para> + + <screen>&prompt.root; <userinput>cd /sys/boot/i386 && make clean && make && make install</userinput></screen> + + <para>To enable &man.dcons.4; as an active low-level + console, add <literal>boot_multicons="YES"</literal> to + <filename>/boot/loader.conf</filename>.</para> + + <para>Here are a few configuration examples. A sample kernel + configuration file would contain:</para> + + <screen>device dcons +device dcons_crom +options KDB +options DDB +options GDB +options ALT_BREAK_TO_DEBUGGER</screen> + + <para>And a sample <filename>/boot/loader.conf</filename> + would contain:</para> + + <screen>dcons_crom_load="YES" +dcons_gdb=1 +boot_multicons="YES" +hw.firewire.phydma_enable=1 +hw.firewire.dcons_crom.force_console=1</screen> + + </sect3> + + <sect3> + <title>Enabling &firewire; and Dcons support on the host + machine</title> + + <para>To enable &firewire; support in the kernel on the + <emphasis>host machine</emphasis>:</para> + + <screen>&prompt.root; <userinput>kldload firewire</userinput></screen> + + <para>Find out the <acronym>EUI64</acronym> (the unique 64 + bit identifier) of the &firewire; host controller, and + use &man.fwcontrol.8; or <command>dmesg</command> to + find the <acronym>EUI64</acronym> of the target machine.</para> + + <para>Run &man.dconschat.8;, with:</para> + + <screen>&prompt.root; <userinput>dconschat -e \# -br -G 12345 -t <replaceable>00-11-22-33-44-55-66-77</replaceable></userinput></screen> + + <para>The following key combinations can be used once + &man.dconschat.8; is running:</para> + + <informaltable pgwide="1"> + <tgroup cols="2"> + <tbody> + <row> + <entry> + <keycombo action="seq"> + <keycap>~</keycap> + <keycap>.</keycap> + </keycombo> + </entry> + <entry>Disconnect</entry> + </row> + <row> + <entry> + <keycombo action="seq"> + <keycap>~</keycap> + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>B</keycap> + </keycombo> + </keycombo> + </entry> + <entry>ALT BREAK</entry> + </row> + <row> + <entry> + <keycombo action="seq"> + <keycap>~</keycap> + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>R</keycap> + </keycombo> + </keycombo> + </entry> + <entry>RESET target</entry> + </row> + <row> + <entry> + <keycombo action="seq"> + <keycap>~</keycap> + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>Z</keycap> + </keycombo> + </keycombo> + </entry> + <entry>Suspend dconschat</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Attach remote <acronym>GDB</acronym> by starting + &man.kgdb.1; with a remote debugging session:</para> + + <screen><userinput>kgdb -r :12345 kernel</userinput></screen> + + </sect3> + <sect3> + <title>Some general tips</title> + + <para>Here are some general tips:</para> + + <para>To take full advantage of the speed of &firewire;, + disable other slow console drivers:</para> + + <screen>&prompt.root; conscontrol delete ttyd0 # serial console +&prompt.root; conscontrol delete consolectl # video/keyboard</screen> + + <para>There exists a <acronym>GDB</acronym> mode for + &man.emacs.1;; this is what you will need to add to your + <filename>.emacs</filename>:</para> + + <screen><userinput>(setq gud-gdba-command-name "kgdb -a -a -a -r :12345") +(setq gdb-many-windows t) +(xterm-mouse-mode 1) +M-x gdba</userinput></screen> + + <para>And for <acronym>DDD</acronym> (<filename>devel/ddd</filename>):</para> + + <screen># remote serial protocol +LANG=C ddd --debugger kgdb -r :12345 kernel +# live core debug +LANG=C ddd --debugger kgdb kernel /dev/fwmem0.2</screen> + </sect3> + </sect2> + + <sect2> + <title>Dcons with KVM</title> + + <para>We can directly read the &man.dcons.4; buffer via + <filename>/dev/mem</filename> for live systems, and in the + core dump for crashed systems. These give you similar output + to <command>dmesg -a</command>, but the &man.dcons.4; buffer + includes more information.</para> + + <sect3> + <title>Using Dcons with KVM</title> + + <para>To use &man.dcons.4; with <acronym>KVM</acronym>:</para> + + <para>Dump a &man.dcons.4; buffer of a live system:</para> + + <screen>&prompt.root; <userinput>dconschat -1</userinput></screen> + + <para>Dump a &man.dcons.4; buffer of a crash dump:</para> + + <screen>&prompt.root; <userinput>dconschat -1 -M vmcore.XX</userinput></screen> + + <para>Live core debugging can be done via:</para> + + <screen>&prompt.root; <userinput>fwcontrol -m target_eui64</userinput> +&prompt.root; <userinput>kgdb kernel /dev/fwmem0.2</userinput></screen> + </sect3> + </sect2> + </sect1> + <sect1 id="kerneldebug-options"> <title>Glossary of Kernel Options for Debugging</title>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201210041104.q94B4Bpa037858>