merge b_devel into HEAD, which will become 0.7.3

[fs/lustre-release.git] / lustre / kernel_patches / patches / kgdb-ga-docco-fixes-2.5.73.patch

From: "Randy.Dunlap" <rddunlap@osdl.org>

Just some readability fixes.



 Documentation/i386/kgdb/kgdb.txt |  135 +++++++++++++++++++--------------------
 1 files changed, 68 insertions(+), 67 deletions(-)

diff -puN Documentation/i386/kgdb/kgdb.txt~kgdb-gs-docco-fixes Documentation/i386/kgdb/kgdb.txt
--- 25/Documentation/i386/kgdb/kgdb.txt~kgdb-gs-docco-fixes     2003-06-26 17:32:25.000000000 -0700
+++ 25-akpm/Documentation/i386/kgdb/kgdb.txt    2003-06-26 17:32:25.000000000 -0700
@@ -6,10 +6,10 @@ New features: 
 ============
 20030505.1827.27
 We are starting to align with the sourceforge version, at least in 
-commands.  To this end, the boot command sting to start kgdb at
+commands.  To this end, the boot command string to start kgdb at
 boot time has been changed from "kgdb" to "gdb".
 
-Andrew Morton sent a couple of patchs which are now included as follows:
+Andrew Morton sent a couple of patches which are now included as follows:
 1.) We now return a flag to the interrupt handler.
 2.) We no longer use smp_num_cpus (a conflict with the lock meter).
 3.) And from William Lee Irwin III <wli@holomorphy.com> code to make
@@ -27,18 +27,18 @@ This is currently the version for the 2.
 
 We have several new "features" beginning with this version:
  
-1.) Kgdb now syncs the "other" cpus with a cross cpu NMI.  No more
-    waiting and it will pull that guy out of an irq off spin lock :)
+1.) Kgdb now syncs the "other" CPUs with a cross-CPU NMI.  No more
+    waiting and it will pull that guy out of an IRQ off spin lock :)
 
 2.) We doctored up the code that tells where a task is waiting and
     included it so that the "info thread" command will show a bit more
     than "schedule()".  Try it...
 
 3.) Added the ability to call a function from gdb.  All the standard gdb
-    issues apply, i.e. if you hit a break point in the function you are
-    not allowed to call another (gdb limitation, not kgdb).  T0 help
+    issues apply, i.e. if you hit a breakpoint in the function, you are
+    not allowed to call another (gdb limitation, not kgdb).  To help
     this capability we added a memory allocation function.  Gdb does not
-    return this memory (it is used for stings you pass to that function
+    return this memory (it is used for strings that you pass to that function
     you are calling from gdb) so we fixed up a way to allow you to
     manually return the memory (see below).
 
@@ -61,23 +61,23 @@ $2 = {used_malloc = 0, called_from = 0xc
     Things to note here: a.) used_malloc is the amount of memory that
     has been malloc'ed to do calls from gdb.  You can reclaim this
     memory like this: "p kgdb_info.used_malloc=0" Cool, huh?  b.)
-    cpus_waiting is now "sized" by the number of cpus you enter at
-    configure time in the kgdb configure section.  This is NOT used any
-    where else in the system, but it is "nice" here.  c.)  The tasks
+    cpus_waiting is now "sized" by the number of CPUs you enter at
+    configure time in the kgdb configure section.  This is NOT used
+    anywhere else in the system, but it is "nice" here.  c.)  The task's
     "pid" is now in the structure.  This is the pid you will need to use
     to decode to the thread id to get gdb to look at that thread.
     Remember that the "info thread" command prints a list of threads
-    where in it numbers each thread with its reference number followed
-    by the threads pid.  Note that the per cpu idle threads actually
-    have pids of 0 (yes there is more than one pid 0 in an SMP system).
+    wherein it numbers each thread with its reference number followed
+    by the thread's pid.  Note that the per-CPU idle threads actually
+    have pids of 0 (yes, there is more than one pid 0 in an SMP system).
     To avoid confusion, kgdb numbers these threads with numbers beyond
-    the MAX_PID.  That is why you see 32768 above.
+    the MAX_PID.  That is why you see 32768 and above.
 
 6.) A subtle change, we now provide the complete register set for tasks
-    that are active on the other cpus.  This allows better trace back on
+    that are active on the other CPUs.  This allows better trace back on
     those tasks.
 
-    And, lets mention what we could not fix.  Back-trace from all but the
+    And, let's mention what we could not fix.  Back-trace from all but the
     thread that we trapped will, most likely, have a bogus entry in it.
     The problem is that gdb does not recognize the entry code for
     functions that use "current" near (at all?) the entry.  The compiler
@@ -88,9 +88,9 @@ $2 = {used_malloc = 0, called_from = 0xc
 
 20011220.0050.35
 Major enhancement with this version is the ability to hold one or more
-cpus in an SMP system while allowing the others to continue.  Also, by
-default only the current cpu is enabled on single step commands (please
-note that gdb issues single step commands at times other than when you
+CPUs in an SMP system while allowing the others to continue.  Also, by
+default only the current CPU is enabled on single-step commands (please
+note that gdb issues single-step commands at times other than when you
 use the si command).
  
 Another change is to collect some useful information in
@@ -111,14 +111,14 @@ $4 = {called_from = 0xc010732c, entry_ts
 
 "Called_from" is the return address from the current entry into kgdb.  
 Sometimes it is useful to know why you are in kgdb, for example, was 
-it an NMI or a real break point?  The simple way to interrogate this 
+it an NMI or a real breakpoint?  The simple way to interrogate this
 return address is:
 
 l *0xc010732c
 
 which will print the surrounding few lines of source code.
 
-"Entry_tsc" is the cpu TSC on entry to kgdb (useful to compare to the
+"Entry_tsc" is the CPU TSC on entry to kgdb (useful to compare to the
 kgdb_ts entries).
 
 "errcode" and "vector" are other entry parameters which may be helpful on
@@ -139,34 +139,34 @@ $7 = {called_from = 0xc0112739, entry_ts
       hold = 0, regs = 0x0}, {task = 0x0, hold = 0, regs = 0x0}, {task = 0x0, 
       hold = 0, regs = 0x0}}}
 
-"Cpus_waiting" has an entry for each cpu other than the current one that 
+"Cpus_waiting" has an entry for each CPU other than the current one that
 has been stopped.  Each entry contains the task_struct address for that
-cpu, the address of the regs for that task and a hold flag.  All these
+CPU, the address of the regs for that task and a hold flag.  All these
 have the proper typing so that, for example:
 
 p *kgdb_info.cpus_waiting[1].regs
 
-will print the registers for cpu 1.
+will print the registers for CPU 1.
 
 "Hold_on_sstep" is a new feature with this version and comes up set or
-true.  What is means is that whenever kgdb is asked to single step all
-other cpus are held (i.e. not allowed to execute).  The flag applies to
-all but the current cpu and, again, can be changed:
+true.  What this means is that whenever kgdb is asked to single-step all
+other CPUs are held (i.e. not allowed to execute).  The flag applies to
+all but the current CPU and, again, can be changed:
 
 p kgdb_info.hold_on_sstep=0
 
-restores the old behavior of letting all cpus run during single stepping.
+restores the old behavior of letting all CPUs run during single-stepping.
 
-Likewise, each cpu has a "hold" flag, which if set, locks that cpu out
-of execution.  Note that this has some risk in cases where the cpus need
-to communicate with each other.  If kgdb finds no cpu available on exit,
+Likewise, each CPU has a "hold" flag, which if set, locks that CPU out
+of execution.  Note that this has some risk in cases where the CPUs need
+to communicate with each other.  If kgdb finds no CPU available on exit,
 it will push a message thru gdb and stay in kgdb.  Note that it is legal
-to hold the current cpu as long as at least one cpu can execute.
+to hold the current CPU as long as at least one CPU can execute.
 
 20010621.1117.09
 This version implements an event queue.  Events are signaled by calling
 a function in the kgdb stub and may be examined from gdb.  See EVENTS 
-below for details.  This version also tighten up the interrupt and SMP
+below for details.  This version also tightens up the interrupt and SMP
 handling to not allow interrupts on the way to kgdb from a breakpoint 
 trap.  It is fine to allow these interrupts for user code, but not
 system debugging.
@@ -190,18 +190,18 @@ machine.  This is the machine that will 
 kernel.
 
 The two machines will be connected together via a serial line out
-one or the other of the COM ports of the PC.  You will need a modem
-eliminator and the appropriate cables.
+one or the other of the COM ports of the PC.  You will need the
+appropriate modem eliminator (null modem) cable(s) for this.
 
 Decide on which tty port you want the machines to communicate, then
-cable them up back-to-back using the null modem.  COM1 is /dev/ttyS0 and
-COM2 is /dev/ttyS1. You should test this connection with the two
-machines prior to trying to debug a kernel.  Once you have it working,
-on the TARGET machine, enter:
+connect them up back-to-back using the null modem cable.  COM1 is
+/dev/ttyS0 and COM2 is /dev/ttyS1. You should test this connection
+with the two machines prior to trying to debug a kernel.  Once you
+have it working, on the TARGET machine, enter:
 
 setserial /dev/ttyS0 (or what ever tty you are using)
 
-and record the port and the irq addresses. 
+and record the port address and the IRQ number.
 
 On the DEVELOPMENT machine you need to apply the patch for the kgdb
 hooks.  You have probably already done that if you are reading this
@@ -212,7 +212,7 @@ On your DEVELOPMENT machine, go to your 
 configuring in the standard serial driver, it must not be a module.
 Either yes or no is ok, but making the serial driver a module means it
 will initialize after kgdb has set up the UART interrupt code and may
-cause a failure of the control C option discussed below.  The configure
+cause a failure of the control-C option discussed below.  The configure
 question for the serial driver is under the "Character devices" heading
 and is:
 
@@ -231,16 +231,16 @@ The baud rate.  Default is 115200.  What
 the host machine is set to the same speed.  I recommend the default.
 
 The port.  This is the I/O address of the serial UART that you should
-have gotten using setserial as described above.  The standard com1 port
-(3f8) using irq 4 is default .  Com2 is 2f8 which by convention uses irq
+have gotten using setserial as described above.  The standard COM1 port
+(3f8) using IRQ 4 is default.  COM2 is 2f8 which by convention uses IRQ
 3.
 
-The port irq (see above).
+The port IRQ (see above).
 
 Stack overflow test.  This option makes a minor change in the trap,
 system call and interrupt code to detect stack overflow and transfer
-control to kgdb if it happens.  (Some platforms have this in the base
-line code, but the i386 does not.)
+control to kgdb if it happens.  (Some platforms have this in the
+baseline code, but the i386 does not.)
 
 You can also configure the system to recognize the boot option
 "console=kgdb" which if given will cause all console output during
@@ -251,9 +251,9 @@ This will happen before any kernel outpu
 and will stall the boot until the connection is made.
 
 You can also configure in a patch to SysRq to enable the kGdb SysRq.
-This request generates a breakpoint.  Since the serial port irq line is
+This request generates a breakpoint.  Since the serial port IRQ line is
 set up after any serial drivers, it is possible that this command will
-work when the control C will not.
+work when the control-C will not.
 
 Save and exit the Xconfig program.  Then do "make clean" , "make dep"
 and "make bzImage" (or whatever target you want to make).  This gets the
@@ -360,11 +360,11 @@ Triggering kgdbstub at other times
 Often you don't need to enter the debugger until much later in the boot
 or even after the machine has been running for some time.  Once the
 kernel is booted and interrupts are on, you can force the system to
-enter the debugger by sending a control C to the debug port. This is
+enter the debugger by sending a control-C to the debug port. This is
 what the first line of the recommended .gdbinit file does.  This allows
 you to start gdb any time after the system is up as well as when the
-system is already at a break point.  (In the case where the system is
-already at a break point the control C is not needed, however, it will
+system is already at a breakpoint.  (In the case where the system is
+already at a breakpoint the control-C is not needed, however, it will
 be ignored by the target so no harm is done.  Also note the the echo
 command assumes that the port speed is already set.  This will be true
 once gdb has connected, but it is best to set the port speed before you
@@ -442,7 +442,7 @@ turn on a debug switch with the followin
 This will print out the protocol messages that gdb is exchanging with
 the target machine.
 
-Another place to look is /usr/src/arch/i386/lib/kgdb_serial.c This is
+Another place to look is /usr/src/arch/i386/lib/kgdb_serial.c. This is
 the code that talks to the serial port on the target side.  There might
 be a problem there.  In particular there is a section of this code that
 tests the UART which will tell you what UART you have if you define
@@ -454,7 +454,7 @@ it finds.  (You need to wait so that the
 printed.  Early in the boot they are cached, waiting for the console to
 be enabled.  Also, if kgdb is entered thru a breakpoint it is possible
 to cause a dead lock by calling printk when the console is locked.  The
-stub, thus avoids doing printks from break points especially in the
+stub thus avoids doing printks from breakpoints, especially in the
 serial code.)  At this time, if the UART fails to do the expected thing,
 kgdb will print out (using printk) information on what failed.  (These
 messages will be buried in all the other boot up messages.  Look for
@@ -464,7 +464,7 @@ don't connect, review your answers for t
 
 setserial /dev/ttyS0 
 
-to get the current port and irq information.  This command will also
+to get the current port and IRQ information.  This command will also
 tell you what the system found for the UART type. The stub recognizes
 the following UART types:
 
@@ -581,11 +581,11 @@ When a breakpoint occurs or user issues 
 client, all the processors are forced to enter the debugger. Current
 thread corresponds to the thread running on the processor where
 breakpoint occurred.  Threads running on other processor(s) appear
-similar to other non running threads in the 'info threads' output.  With
-in the kgdb stub there is a structure "waiting_cpus" in which kgdb
-records the values of "current" and "regs" for each cpu other than the
+similar to other non-running threads in the 'info threads' output.
+Within the kgdb stub there is a structure "waiting_cpus" in which kgdb
+records the values of "current" and "regs" for each CPU other than the
 one that hit the breakpoint.  "current" is a pointer to the task
-structure for the task that cpu is running, while "regs" points to the
+structure for the task that CPU is running, while "regs" points to the
 saved registers for the task.  This structure can be examined with the
 gdb "p" command.
 
@@ -601,22 +601,23 @@ Kill it. restart gdb. Connect to target 
 2. gdb cannot connect to target machine (after killing a gdb and
 restarting another) If the target machine was not inside debugger when
 you killed gdb, gdb cannot connect because the target machine won't
-respond.  In this case echo "Ctrl+C"(ASCII 3) in the serial line.
-e.g. echo -e "\003" > /dev/ttyS1 This forces that target machine into
-debugger after which you can connect.
+respond.  In this case echo "Ctrl+C"(ASCII 3) to the serial line.
+e.g. echo -e "\003" > /dev/ttyS1
+This forces that target machine into the debugger, after which you
+can connect.
 
 3. gdb cannot connect even after echoing Ctrl+C into serial line
 Try changing serial line settings min to 1 and time to 0
 e.g. stty min 1 time 0 < /dev/ttyS1
 Try echoing again
 
-check serial line speed and set it to correct value if required
+Check serial line speed and set it to correct value if required
 e.g. stty ispeed 115200 ospeed 115200 < /dev/ttyS1
 
 EVENTS
 ======
 
-Ever want to know the order of things happening?  Which cpu did what and
+Ever want to know the order of things happening?  Which CPU did what and
 when?  How did the spinlock get the way it is?  Then events are for
 you.  Events are defined by calls to an event collection interface and
 saved for later examination.  In this case, kgdb events are saved by a
@@ -631,7 +632,7 @@ Events are signaled to kgdb by calling:
 kgdb_ts(data0,data1)
 
 For each call kgdb records each call in an array along with other info.
-Here is the array def:
+Here is the array definition:
 
 struct kgdb_and_then_struct {
 #ifdef CONFIG_SMP
@@ -646,7 +647,7 @@ struct kgdb_and_then_struct {
        int     data1;
 };
 
-For SMP machines the cpu is recorded, for all machines the TSC is
+For SMP machines the CPU is recorded, for all machines the TSC is
 recorded (gets a time stamp) as well as the line number and source file
 the call was made from.  The address of the (from), the "if" (interrupt
 flag) and the two data items are also recorded.  The macro kgdb_ts casts
@@ -709,7 +710,7 @@ Amit S. Kale
     Extended threads to include the idle threads.
     Enhancements to allow breakpoint() at first C code.
     Use of module_init() and __setup() to automate the configure.
-    Enhanced the cpu "collection" code to work in early bring up.
+    Enhanced the cpu "collection" code to work in early bring-up.
     Added ability to call functions from gdb
     Print info thread stuff without going back to schedule()
-    Now collect the "other" cpus with a IPI/ NMI.
\ No newline at end of file
+    Now collect the "other" cpus with an IPI/ NMI.

_