<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN" > -->

<!--  This is part of the lcrash HOWTO. -->
<!--  Copyright (C) 2001, 2002 IBM Deutschland Entwicklung GmbH, -->
<!--                           IBM Corporation -->
<!--  See the file lcrash.sgml for copying conditions. -->

<chapter id="cha.samplesessions">
  <title>Sample <command>lcrash</command> Sessions</title>
<!--   <section id="sec.firststeps"> -->
<!--     <title>First Steps</title> -->
<!--     <itemizedlist> -->
<!--       <listitem> -->
<!-- 	<para>invoking lcrash</para> -->
<!--       </listitem> -->
<!--       <listitem> -->
<!-- 	<para>what was/is going on in the system</para> -->
<!--       </listitem> -->
<!--     </itemizedlist> -->
<!--   </section> -->

  <section id="sec.analyzekernelmodules">
    <title>Analyze Kernel Modules</title>

<!--     <itemizedlist> -->
<!--       <listitem> -->
<!-- 	<para>basics about stack traces</para> -->
<!--       </listitem> -->
<!--       <listitem> -->
<!-- 	<para>add type information for kernel module</para> -->
<!--       </listitem> -->
<!--       <listitem> -->
<!-- 	<para>add symbol table for kernel module</para> -->
<!--       </listitem> -->
<!--     </itemizedlist> -->
    <para>
      This session should describe how to use lcrash in analyzing kernel
      modules. First of all we make use of lcrash commands
      <command>namelist</command> and <command>symtab</command>.
    </para>
    <para>
      We have a kernel module <filename>my_dummy.o</filename> containing a
      locale variable <parameter>DUMMY</parameter> of type
      <structname>dummy_t</structname>. The corresponding code fragment is
      as follows:
      <screen><![CDATA[

typedef struct dummy_s{
        int member1;
        char *member2;
        struct dummy_s *member3;
} dummy_t;

static dummy_t DUMMY={0, "just a demonstration", &DUMMY};
	]]>
      </screen>
    </para>
    <para>
      Our intention will be to examine this local data with lcrash.
      To make it little more tricky we analyze a live dump and the module
      will be loaded while lcrash is running.
    </para>
    <para>
      Our module was compiled using <command>gcc</command> option
      <option>-gstabs</option> to create type information. The symbol table
      of the module was generated using a command line like
      <command>nm <filename>my_dummy.o</filename> > 
	<filename>/tmp/my_dummy.map</filename></command>.
    </para>
    <para>
      The file <filename>my_dummy.o</filename> was also copied to
      <filename>/tmp</filename>.
    </para>
    <orderedlist>
      <listitem>
	<para>Start lcrash.</para>
	<screen>
bash# lcrash /boot/System.map-2.2.18 /dev/mem /boot/Kerntypes 
map = /boot/System.map-2.2.18, vmdump = /dev/mem, outfile = stdout, kerntypes =
 /boot/Kerntypes

Please wait...
        Loading system map ........................... Done.
        Loading type info (Kerntypes) ... Done.
        Loading ksyms from dump ........ Done.
>> 
	</screen>
      </listitem>
      <listitem>
	<para>Look what modules are loaded.</para>
	<screen>
>> module
    ADDR      SIZE USED NAME                               REFS 
===========================================================================
d0103000     17928    1 ibmtr_cs                      []
d00fe000      6608    2 ds                            [ibmtr_cs]
d00f3000     23408    2 i82365                        []
d00e6000     46848    0 pcmcia_core                   [ibmtr_cs
                                                       ds
                                                       i82365]
c02ad0e0         0    1 kernel_module                 []
===========================================================================
	</screen>
      </listitem>
      <listitem>
	<para>From another shell, load module <parameter>my_dummy</parameter>.
	</para>
	<screen>
bash# insmod my_dummy.o
bash#
	</screen>
      </listitem>
      <listitem>
	<para>Verify the former action with lcrash.
	</para>
	<screen>
>> module
    ADDR      SIZE USED NAME                               REFS 
===========================================================================
d0000000      1120    0 my_dummy                      []
d0103000     17928    1 ibmtr_cs                      []
d00fe000      6608    2 ds                            [ibmtr_cs]
d00f3000     23408    2 i82365                        []
d00e6000     46848    0 pcmcia_core                   [ibmtr_cs
                                                       ds
                                                       i82365]
c02ad0e0         0    1 kernel_module                 []
===========================================================================
	</screen>
      </listitem>
      <listitem>
	<para>Look which symbols of the new module are exported.
	</para>
	<screen>
>> module -f my_dummy
EXPORTED MODULE SYMBOLS: 
===========================================================================
        Module: my_dummy
        Number of exported symbols: 6

            ADDR NAME [MODULE]

        d0000000 __insmod_my_dummy_O/home/aherrman/CPP/crash_ex/my_dummy.o_
M3B1CDF3B_V131602 [my_dummy]
        d0000060 dummy_init                           [my_dummy]
        d0000060 __insmod_my_dummy_S.text_L447        [my_dummy]
        d000021f __insmod_my_dummy_S.rodata_L29       [my_dummy]
        d000041c __insmod_my_dummy_S.bss_L16          [my_dummy]
        d0000240 __insmod_my_dummy_S.data_L260        [my_dummy]

===========================================================================
	</screen>
      </listitem>
      <listitem>
	<para>Load type information of the module.
	</para>
	<screen>
>> namelist -a /tmp/my_dummy.o
.The current namelist is /tmp/my_dummy.o (1)
>> namelist
INDEX  NAMELIST
=================================================
    0  /boot/Kerntypes
    1  /tmp/my_dummy.o
=================================================

The current namelist is /tmp/my_dummy.o (1)
	</screen>
      </listitem>
      <listitem>
	<para>Load symbol table of the module.
	</para>
	<screen>
>> symtab -a /tmp/my_dummy.map my_dummy
Adding symbol table.
           filename: /tmp/my_dummy.map
        text_offset:        0
        data_offset:        0
      rodata_offset:        0
         bss_offset:        0
        module size:     1120
..Done.
	</screen>
	<para>
	  Something went wrong, offsets of text and data sections of the module
	  should not be zero.
	  This is caused by the fact, that we added our module after lcrash was
	  started. We have to remove the loaded symbol table and we have to
	  recreate the table <parameter>__ksymtab__</parameter>.
	</para>
      </listitem>
      <listitem>
	<para>Remove our new symbol table and
	  <parameter>__ksymtab__</parameter>.
	</para>
	<screen>
>> symtab -l
Loaded symbol tables:
===========================================================================
#SYMS:     7803 /boot/System.map-2.2.18
 TEXT:        0 DATA:        0 RODATA:        0 BSS:        0
#SYMS:     1163 __ksymtab__
 TEXT:        0 DATA:        0 RODATA:        0 BSS:        0
#SYMS:       14 /tmp/my_dummy.map [my_dummy]
 TEXT:        0 DATA:        0 RODATA:        0 BSS:        0
===========================================================================
>> symtab -r /tmp/my_dummy.map
Removing symbol table.
Done.
>> symtab -r __ksymtab__
Removing symbol table.
Done.
	</screen>
      </listitem>
      <listitem>
	<para>Recreate symbol table <parameter>__ksymtab__</parameter>.
	</para>
	<screen>
 >> symtab -a __ksymtab__
Adding symbol table.

        Loading ksyms from dump ........
Done.
	</screen>
      </listitem>
      <listitem>
	<para>Load our new symbol table again.
	</para>
	<screen>
>> symtab -a /tmp/my_dummy.map my_dummy
Adding symbol table.
           filename: /tmp/my_dummy.map
        text_offset: d0000060
        data_offset: d0000240
      rodata_offset: d000021f
         bss_offset: d000041c
        module size:     1120
..Done.
>> symtab -l 
Loaded symbol tables:
===========================================================================
#SYMS:     7803 /boot/System.map-2.2.18
 TEXT:        0 DATA:        0 RODATA:        0 BSS:        0
#SYMS:     1169 __ksymtab__
 TEXT:        0 DATA:        0 RODATA:        0 BSS:        0
#SYMS:       14 /tmp/my_dummy.map [my_dummy]
 TEXT: d0000060 DATA: d0000240 RODATA: d000021f BSS: d000041c
===========================================================================
	</screen>
      </listitem>
      <listitem>
	<para>Look which symbols are available in module
	  <parameter>my_dummy</parameter>.
	</para>
	<screen>
>> symtab -l -f /tmp/my_dummy.map
===========================================================================
#SYMS:       14 /tmp/my_dummy.map [my_dummy]
 TEXT: d0000060 DATA: d0000240 RODATA: d000021f BSS: d000041c

    ADDR  OFFSET  TYPE         NAME
------------------------------------------------------------
d0000060       0  GLOBAL_TEXT  dummy_init
d00000f0       0  LOCAL_TEXT   dummy_xmit
d0000130       0  LOCAL_TEXT   dummy_get_stats
d0000140       0  LOCAL_TEXT   dummy_open
d0000160       0  LOCAL_TEXT   dummy_close
d0000180       0  LOCAL_TEXT   set_multicast_list
d0000190       0  LOCAL_TEXT   dummy_probe
d00001b0       0  GLOBAL_TEXT  init_module
d00001f0       0  GLOBAL_TEXT  cleanup_module
d000021f       0  LOCAL_TEXT   Letext
d0000240       0  LOCAL_DATA   DUMMY
d0000260       0  LOCAL_DATA   dev_dummy
d000041c       0  LOCAL_DATA   dummy_name
d00004c0       0  ABS          /tmp/my_dummy.map_END
------------------------------------------------------------
===========================================================================
	</screen>
      </listitem>
      <listitem>
	<para>Try to examine the local variable <parameter>DUMMY</parameter>
	  of our module.
	</para>
	<screen>
>> whatis DUMMY
    ADDR  OFFSET  TYPE         NAME
============================================================
d0000240       0  LOCAL_DATA   DUMMY
>> whatis dummy_t
struct dummy_s 
struct dummy_s {
        int member1;
        char *member2;
        struct dummy_s *member3;
};
>> print *(dummy_t*) d0000240
struct dummy_s {
        member1 = 0
        member2 = 0xd000021f
        member3 = 0xd0000240
}

>> whatis dummy_s.member2
char *
>> print (char*) 0xd000021f
0xd000021f "just a demonstration"
	</screen>
      </listitem>
    </orderedlist>
    <para>
      Furthermore an additional symbol table of a kernel module provides you 
      function names when setting up stack back-traces with 
      <command>trace</command> or <command>strace</command> and when using
      disassembling routine <command>dis</command>.
    </para>
  </section>

<!--   <section id="sec.ifnothingworks"> -->
<!--     <title>If Nothing Works</title> -->
<!--     <itemizedlist> -->
<!--       <listitem> -->
<!-- 	<para>no task struct available ...</para> -->
<!--       </listitem> -->
<!--       <listitem> -->
<!-- 	<para>strace</para> -->
<!--       </listitem> -->
<!--       <listitem> -->
<!-- 	<para>lowcore_ptr</para> -->
<!--       </listitem> -->
<!--     </itemizedlist> -->
<!--   </section> -->

</chapter>


<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-always-quote-attributes:t
sgml-auto-insert-required-elements:t
sgml-balanced-tag-edit:t
sgml-exposed-tags:nil
sgml-general-insert-case:lower
sgml-indent-data:t
sgml-indent-step:2
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
sgml-minimize-attributes:nil
sgml-namecase-general:t
sgml-omittag:t
sgml-parent-document:("lcrash.sgml" "book" "chapter")
sgml-shorttag:t
sgml-tag-region-if-active:t
End:
-->
