patch-2.3.10 linux/scripts/ksymoops/README

Next file: linux/scripts/ksymoops/io.c
Previous file: linux/scripts/ksymoops/Makefile
Back to the patch index
Back to the overall index

diff -u --recursive --new-file v2.3.9/linux/scripts/ksymoops/README linux/scripts/ksymoops/README
@@ -1,399 +1,7 @@
-  ksymoops.
+ksymoops has been removed from the kernel.  It was always meant to be a
+free standing utility, not linked to any particular kernel version.
+The latest version can be found in ftp://ftp.ocs.com.au/pub/ksymoops,
+together with patches to other utilities in order to give more accurate
+Oops debugging.
 
-  Read a kernel Oops file and make the best stab at converting the code to
-  instructions and mapping stack values to kernel symbols.
-
-  Copyright Keith Owens <kaos@ocs.com.au>.
-  Released under the GNU Public Licence, Version 2.
-
-  To compile, simply type "make" in the ksymoops directory.
-
-  TESTERS WANTED.
-
-  ksymoops handles ix86.  It appears to handle Alpha, Sparc, M68K, PPC,
-  MIPS but I have no machine to test on.  I would appreciate feedback
-  from users of non ix86 machines.  In particular, it would be nice if
-  you could run
-
-   ksymoops -VMO -k /proc/ksyms -dd <oops.file >/tmp/ksymoops.log 2>&1
-
-  and mail /tmp/ksymoops.log to kaos@ocs.com.au
-
-  TODO:
-  Clean up these docs.
-  Tweak System.map to include arch information.
-  Tweak modutils to log at least one symbol for each module loaded,
-  otherwise they are invisible to ksymoops.  Also arch and version data.
-  Include sparc/sparc64 patches from Jakub Jelinek <jj@sunsite.mff.cuni.cz>.
-  Add object format override for sparc/soparc64 or any cross platform
-  oops debugging.
-
-  Mon Jan  4 09:48:13 EST 1999
-  Version 0.6e
-  Added to kernel.
-  Add ARM support.
-  Typo in oops_code.
-  Add -c option.
-  Add -1 option.
-  Report if options were specified or defaulted.
-  Remove false warnings when comparing ksyms and lsmod.
-  Performance inprovements.
-
-  Wed Oct 28 23:14:55 EST 1998
-  Version 0.5
-  No longer read vmlinux by default, it only duplicates System.map.
-
-  Wed Oct 28 13:46:39 EST 1998
-  Version 0.4
-  Split into separate sources.
-
-  Mon Oct 26 00:01:47 EST 1998
-  Version 0.3c
-  Add alpha (arm) processing.
-
-  Mon Oct 26 00:01:47 EST 1998
-  Version 0.3b
-  Add sparc processing.
-  Handle kernel symbol versions.
-
-  Fri Oct 23 13:11:20 EST 1998
-  Version 0.3
-  Add -follow to find command for people who use symlinks to modules.
-  Add Version_ checking.
-
-  Thu Oct 22 22:28:30 EST 1998
-  Version 0.2.
-  Generalise text prefix handling.
-  Handle messages on Code: line.
-  Format addresses with leading zeroes.
-  Minor bug fixes.
-
-  Wed Oct 21 23:28:48 EST 1998
-  Version 0.1.  Rewrite from scratch in C.
-
-  CREDITS.
-  Oops disassembly based on ksymoops.cc,
-    Copyright (C) 1995 Greg McGary <gkm@magilla.cichlid.com>
-  m68k code based on ksymoops.cc changes by
-    Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
-
-  This code subsumes the Perl script make_System.map.pl which is no longer
-  supported.
-
-  Why another ksymoops I hear you ask?  Various complaints about
-  ksymoops.cc -
-
-  * It requires C++.
-  * It has hard wired limitations on the number of symbols.
-  * It does not handle modules at all.
-  * Very rigid requirements on the format of input, especially the Oops
-    log.
-  * No cross checking between ksyms, modules, System.map etc.
-  * Very little error checking, diagnostics are not suitable for
-    beginners.
-  * It only prints the trace and decoded code, users have to manually
-    extract the other lines from the Oops.
-  * Gives up on the slightest problem.
-  * Only handles i386 and possibly m68k.  The code is difficult to extend
-    to other architectures.
-  * Stops after the first Oops, you have to manually extract each one and
-    run through ksymoops one at a time.
-
-  This version is -
-  * C.
-  * No hard wired limitations (malloc as far as the eye can see).
-  * Handles modules by default.
-  * Uses regular pattern matching so it is a lot more forgiving about
-    input formats.
-  * By default, cross checks ksyms, modules, System.map and vmlinux.
-  * Lots of diagnostics and error checking.
-  * Prints all relevant lines for a complete Oops report.
-  * Tries to provide output no matter how bad the input is.  The level of
-     progress and error reporting is aimed at beginners.
-  * Handles i386, alpha, sparc, sparc64, m68k.  It is a lot easier to extend
-    to other architectures (patches and/or sample data gratefully accepted).
-  * Handles all Oops in the input file(s).
-
-
-  Usage:	ksymoops
-		  [-v vmlinux]	Where to read vmlinux
-		  [-V]		No vmlinux is available
-		  [-o object_dir]	Directory containing modules
-		  [-O]		No modules is available
-		  [-k ksyms]	Where to read ksyms
-		  [-K]		No ksyms is available
-		  [-l lsmod]	Where to read lsmod
-		  [-L]		No lsmod is available
-		  [-m system.map]	Where to read System.map
-		  [-M]		No System.map is available
-		  [-s save.map]	Save consolidated map
-		  [-c code_bytes]	How many bytes in each unit of code
-		  [-1]		One shot toggle (exit after first Oops)
-		  [-d]		Increase debug level by 1
-		  [-h]		Print help text
-		  Oops.file	Oops to decode
-
-	  All flags can occur more than once.  With the exception of -o
-	  and -d which are cumulative, the last occurrence of each flag is
-	  used.  Note that "-v my.vmlinux -V" will be taken as "No vmlinux
-	  available" but "-V -v my.vmlinux" will read my.vmlinux.  You
-	  will be warned about such combinations.
-
-	  Each occurrence of -d increases the debug level.
-
-	  Each -o flag can refer to a directory or to a single object
-	  file.  If a directory is specified then all *.o files in that
-	  directory and its subdirectories are assumed to be modules.
-
-	  If any of the vmlinux, object_dir, ksyms or system.map options
-	  contain the string *r (*m, *n, *s) then it is replaced at run time
-	  by the current value of `uname -r` (-m, -n, -s).
-
-	  The defaults can be changed in the Makefile, typical options are
-
-	  Defaults:	  -V
-			  -o /lib/modules/%r
-			  -k /proc/ksyms
-			  -l /proc/modules
-			  -m /usr/src/linux/System.map
-			  -c 1
-			  Oops report is read from stdin
-
-  Note:	  Unless you tell ksymoops *NOT* to read a particular file, it
-	  will try to read and reconcile almost all possible sources of kernel
-	  symbol information.  This is intended for beginners, they just
-	  type
-
-	    ksymoops < /var/log/syslog
-
-	  no thinking required.  Experts can point at different files or
-	  suppress the input from selected files.  For example, if you
-	  save /proc/ksyms before doing a test that creates an Oops, you
-	  can point ksymoops at the saved ksyms instead of using
-	  /proc/ksyms.
-
-	  vmlinux is not read by default, it only duplicates the
-	  information in System.map.  If you want to read vmlinux as well
-	  as or instead of System.map, use -v.
-
-	  To get the equivalent of the old ksymoops.cc (no vmlinux, no
-	  modules objects, no ksyms, no System.map) just do ksymoops
-	  -VOKLM.  Or to just read System.map, ksymoops -VOKL -m mapfile.
-
-
-  Return codes:	  0 - normal.
-		  1 - error(s) or warning(s) issued, results may not be
-		      reliable.
-		  2 - fatal error, no useful results.
-		  3 - One shot mode, end of input reached.
-
-  Supported architectures
-
-	  i386 tested.
-          m68k code derived from ksymoops.cc and reading traps.c, untested.
-	  MIPS tested.
-	  Sparc tested.
-	  Sparc64 tested.
-	  Alpha tested.
-	  ARM tested.
-
-	  The term "eip" is generic, for example it includes the i386 EIP
-	  and the m68k PC.  Remember that objdump output always says EIP,
-	  no matter what the architecture, see objfile_head.
-
-	  To support another arch, check the Oops_ procedures between
-	  'Start architecture sensitive code' and 'End architecture
-	  sensitive code'.
-
-	  The pattern matching should take care of different lengths for
-	  the address, i.e. addresses should not be arch sensitive.  I
-	  assume that all addresses are at least 4 characters.
-
-	  If nm output has a different format on your arch, check for uses
-	  of re_nm.
-
-
-
-  Because ksymoops reads kernel information from multiple sources, there
-  could be mismatches.  ksymoops does the following cross checks, but only
-  if the specified files exist -
-
-  * Compare Version_nnn numbers from all sources against each other.  Pity
-    that only vmlinux and System.map have these symbols (as at 2.1.125),
-    however I check ksyms, modules and Oops as well.  If somebody adds
-    symbol Version_nnn to ksyms or modules or adds a Version_nnn line to
-    the Oops log, this code is ready.
-
-  * Compare kernel ksyms against vmlinux.  vmlinux takes precedence.
-
-  * Compare System.map against vmlinux.   vmlinux takes precedence.
-
-  * Compare vmlinux against System.map.   vmlinux takes precedence.
-
-  * Compare kernel ksyms against System.map.  System.map takes precedence.
-
-  * Compare modules against module ksyms.  modules take precedence.  Only
-    if at least one module appears in ksyms.
-
-  * Compare module names in ksyms against lsmod.  Warn if a module
-    appears in lsmod but not in ksyms.  Error if a modules appears in
-    ksyms but is not in lsmod.  Only if both ksyms and lsmod have being
-    read.
-
-  The precedence order is somewhat arbitrary, however it only applies if
-  there is any difference between the various sources.
-
-  Handling modules is awkward.  They can be loaded under different names
-  (insmod -o dummy1 dummy.o) and the text, data and read only data are
-  loaded at different offsets.  Although you can give the -m option to
-  insmod which will output the module map when it is loaded, this has a
-  few problems -
-
-  * No equivalent for removing a module.  If you load and remove a lot of
-    modules, you end up with multiple sets of symbols around the same
-    offsets, which set is correct?
-
-  * "insmod -o dummy1 dummy.o" still reports as dummy.  That is, there is
-     no way of telling which particular version of a multiply loaded
-     module the insmod output refers to.  Therefore there is no way of
-     telling which instantiation failed.
-
-  * Even if the above problems are fixed, how do you tell what the module
-    environment looked like when the Oops occurred?  What if a module is
-    loaded or removed just after Oops, how is the user expected to edit
-    the insmod log?  Rule 1 - make ksymoops easy for beginners.
-
-  Although those problems could be fixed, they require changes to
-  modutils.  Working from ksyms and the module objects can be done without
-  changing modutils and without confusing beginners.
-  
-  Alas the ksyms plus object approach has another problem - matching ksyms
-  to module objects.  Nowhere does the kernel say that module dummy1 came
-  from module /lib/modules/2.1.215/net/dummy.o, ksyms just says dummy1.  I
-  have to match ksyms to the relevant object by finding a globally unique
-  external symbol in each module that can be used to map to the external
-  symbols in ksyms.  This assumes that each module exports at least one
-  text symbol that is unique amongst all modules.
-
-  It may not be possible to correctly map other sections such as data and
-  readonly data for modules because they may not have exported symbols.
-  Since the main aim of ksymoops is to map a code Oops, this should not be
-  a problem.
-
-  Unfortunately some modules export no symbols.  They are marked as
-  EXPORT_NO_SYMBOLS are simply do not export anything.  It is
-  impossible to detect these in ksyms because, by definition, ksyms
-  only contains exported symbols for modules.  Since all modules appear
-  in lsmod (/proc/modules), a cross check of lsmod against the module
-  names will find loaded modules with no symbols, at least I can warn
-  about these.
-
-  After merging the various sources, ksymoops has a (hopefully) accurate
-  map including modules.  The -s option lets you save the merged
-  System.map, but remember that module data and readonly data sections may
-  not be correctly relocated, see above.
-
-  Environment Variables.
-  KSYMOOPS_NM		path for nm, defaults to /usr/bin/nm.
-  KSYMOOPS_FIND		path for find, defaults to /usr/bin/find.
-  KSYMOOPS_OBJDUMP	path for objdump, defaults to /usr/bin/objdump.
-
-
-  Input Oops data.
-
-  The ideal input is to feed the syslog straight into this program.  If
-  you cannot do that, you need to know what the program looks for.
-  Especially if you are typing in the Oops by hand :(.  All input is case
-  insensitive.
-
-  * White space in this context means space or tab.  It does not include
-    newline.
-
-  * Oops in syslog has a syslog prefix.  Leading text up to and including
-    ' kernel: ' is always ignored, there is no need to edit syslog first.
-    This leading text need not exist but if it does, it must end in
-    ' kernel: '.
-
-  * An alternative prefix is <n> where n is the kernel print level.  Also
-    ignored if present.
-
-  * Leading white space is treated as a prefix and ignored, the input is
-    not indentation sensitive.
-
-  * In the following paragraphs, assume that any prefixes have been
-    skipped.  If there is more than one prefix, all are skipped, no matter
-    which order they appear in.
-
-  * A bracketed address is optional '[', required '<', at least 4 hex
-    digits, required '>', optional ']'.  For example [<01234567>] or
-    <1234>.
-
-  * The ix86 EIP line is identified by optional white space followed by
-    'EIP:', followed by a least one white space, followed by a bracketed
-    address.
-
-  * The m68k PC line is identified by optional white space followed by
-    'PC', optionally followed by white space, followed by '=', optionally
-    followed by white space, followed by a bracketed address.
-
-  * The sparc PC line starts with PSR and PC is the second hex value, not
-    bracketed.
-
-  * The sparc64 TPC line starts with TSTATE and TPC is the second hex value,
-    not bracketed.
-
-  * A call trace line is identified by 'Call Trace:' followed by at least
-    one white space.  Or it is a line starting with a bracketed address,
-    but only if the previous line was a call trace line (I hate multi line
-    output that relies on identation for recognition, especially when
-    lines can have a variable prefix).
-
-  * The Code line is identified by 'Code:' followed by a least one white
-    space character followed by at least one hex value.  The line can
-    contain multiple hex values, each separated by at least one white
-    space.  Each hex value must be 2 to 8 digits and must be a multiple of
-    2 digits.
-
-    On some architectures the Code: data is a stream of single bytes,
-    in machine order.  On other architectures, it is a stream of shorts
-    or ints in human readable order which does not always match the
-    machine order, endianess raises its ugly head.  We are consistently
-    inconsistent.
-
-    To cater for these architecture inconsistencies, use the -c option.
-    If the Code: line is already in machine order, use -c 1.  If the
-    Code: data is a stream of shorts or ints which do not match the
-    machine order, use -c 2 or -c 4.  Each set of 'c' bytes are swapped
-    to (hopefully) reflect the machine order.
-
-    Special cases where Code: can be followed by text.
-      'Code: general protection'
-      'Code: <n>'
-    Dump the data anyway, the code was unavailable.
-
-  * Formatted data is only output when the Code: line is seen.  If any
-    data has been stored and more than 5 lines other than Oops text (see
-    Oops_print) or end of file are encountered then ksymoops assumes that
-    the Code: line is missing or garbled and dumps the formatted data
-    anyway.  Fail safe, I hope.
-
-  * By default, ksymoops reads its entire input file.  If the -1 toggle
-    is set, it will run in one shot mode and exit after the first Oops.
-    This is useful for automatically mailing reports as they happen,
-    like this :-
-
-    #!/bin/sh
-    # ksymoops1
-    while (true)
-    do
-    	ksymoops -1 > $HOME/oops1
-	if [ $? -eq 3 ]
-	then
-	   exit 0
-	fi
-	mail -s Oops admin < $HOME/oops1
-    done
-
-    tail -f /var/log/messages | ksymoops1
-
-    Restarting after log rotation is left as an exercise for the reader.
+Keith Owens <kaos@ocs.com.au> Sat Jun 19 10:30:34 EST 1999
FUNET's LINUX-ADM group, linux-adm@nic.funet.fi
TCL-scripts by Sam Shen (who was at: slshen@lbl.gov)