espressif/binutils-gdb
1
0
Fork 0
mirror of https://github.com/espressif/binutils-gdb.git synced 2025-06-22 11:00:01 +08:00
Code Issues Packages Projects Releases Wiki Activity

2008-08-11 Sandra Loosemore <sandra@codesourcery.com>

Browse Source 
Pedro Alves  <pedro@codesourcery.com>

	gdb/doc
	* gdb.texinfo (Threads): Move paragraph about automatic thread
	selection to All-Stop Mode subsection.
	(Thread Stops): Reorganize existing material into subsections.
	Add introductory blurb and menu.
	(Non-Stop Mode): New subsection.
	(Background Execution): New subsection.
	(Maintenance Commands): Add cross-references from async mode
	commands to the new Background Execution section.
This commit is contained in:
Sandra Loosemore
2008-08-12 01:00:49 +00:00
parent 8ab3d180b1
commit 0606b73b11
2 changed files with 282 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
gdb/doc/ChangeLog
View File

@ -1,3 +1,15 @@
2008-08-11 Sandra Loosemore <sandra@codesourcery.com>
Pedro Alves <pedro@codesourcery.com>
* gdb.texinfo (Threads): Move paragraph about automatic thread
selection to All-Stop Mode subsection.
(Thread Stops): Reorganize existing material into subsections.
Add introductory blurb and menu.
(Non-Stop Mode): New subsection.
(Background Execution): New subsection.
(Maintenance Commands): Add cross-references from async mode
commands to the new Background Execution section.
2008-08-06 Tom Tromey <tromey@redhat.com> 2008-08-06 Tom Tromey <tromey@redhat.com>
* gdb.texinfo (Extending GDB): New chapter. * gdb.texinfo (Extending GDB): New chapter.

330
gdb/doc/gdb.texinfo
View File

@ -2591,15 +2591,6 @@ Show whether messages will be printed when @value{GDBN} detects that threads
have started and exited. have started and exited.
@end table @end table
@cindex automatic thread selection
@cindex switching threads automatically
@cindex threads, automatic switching
Whenever @value{GDBN} stops your program, due to a breakpoint or a
signal, it automatically selects the thread where that breakpoint or
signal happened. @value{GDBN} alerts you to the context switch with a
message of the form @samp{[Switching to @var{systag}]} to identify the
thread.
@xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for @xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for
more information about how @value{GDBN} behaves when you stop and start more information about how @value{GDBN} behaves when you stop and start
programs with multiple threads. programs with multiple threads.
@ -4459,6 +4450,268 @@ Program a Signal}.
@node Thread Stops @node Thread Stops
@section Stopping and Starting Multi-thread Programs @section Stopping and Starting Multi-thread Programs
@cindex stopped threads
@cindex threads, stopped
@cindex continuing threads
@cindex threads, continuing
@value{GDBN} supports debugging programs with multiple threads
(@pxref{Threads,, Debugging Programs with Multiple Threads}). There
are two modes of controlling execution of your program within the
debugger. In the default mode, referred to as @dfn{all-stop mode},
when any thread in your program stops (for example, at a breakpoint
or while being stepped), all other threads in the program are also stopped by
@value{GDBN}. On some targets, @value{GDBN} also supports
@dfn{non-stop mode}, in which other threads can continue to run freely while
you examine the stopped thread in the debugger.
@menu
* All-Stop Mode:: All threads stop when GDB takes control
* Non-Stop Mode:: Other threads continue to execute
* Background Execution:: Running your program asynchronously
* Thread-Specific Breakpoints:: Controlling breakpoints
* Interrupted System Calls:: GDB may interfere with system calls
@end menu
@node All-Stop Mode
@subsection All-Stop Mode
@cindex all-stop mode
In all-stop mode, whenever your program stops under @value{GDBN} for any reason,
@emph{all} threads of execution stop, not just the current thread. This
allows you to examine the overall state of the program, including
switching between threads, without worrying that things may change
underfoot.
Conversely, whenever you restart the program, @emph{all} threads start
executing. @emph{This is true even when single-stepping} with commands
like @code{step} or @code{next}.
In particular, @value{GDBN} cannot single-step all threads in lockstep.
Since thread scheduling is up to your debugging target's operating
system (not controlled by @value{GDBN}), other threads may
execute more than one statement while the current thread completes a
single step. Moreover, in general other threads stop in the middle of a
statement, rather than at a clean statement boundary, when the program
stops.
You might even find your program stopped in another thread after
continuing or even single-stepping. This happens whenever some other
thread runs into a breakpoint, a signal, or an exception before the
first thread completes whatever you requested.
@cindex automatic thread selection
@cindex switching threads automatically
@cindex threads, automatic switching
Whenever @value{GDBN} stops your program, due to a breakpoint or a
signal, it automatically selects the thread where that breakpoint or
signal happened. @value{GDBN} alerts you to the context switch with a
message such as @samp{[Switching to Thread @var{n}]} to identify the
thread.
On some OSes, you can modify @value{GDBN}'s default behavior by
locking the OS scheduler to allow only a single thread to run.
@table @code
@item set scheduler-locking @var{mode}
@cindex scheduler locking mode
@cindex lock scheduler
Set the scheduler locking mode. If it is @code{off}, then there is no
locking and any thread may run at any time. If @code{on}, then only the
current thread may run when the inferior is resumed. The @code{step}
mode optimizes for single-stepping; it prevents other threads
from preempting the current thread while you are stepping, so that
the focus of debugging does not change unexpectedly.
Other threads only rarely (or never) get a chance to run
when you step. They are more likely to run when you @samp{next} over a
function call, and they are completely free to run when you use commands
like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
thread hits a breakpoint during its timeslice, @value{GDBN} does not change
the current thread away from the thread that you are debugging.
@item show scheduler-locking
Display the current scheduler locking mode.
@end table
@node Non-Stop Mode
@subsection Non-Stop Mode
@cindex non-stop mode
@c This section is really only a place-holder, and needs to be expanded
@c with more details.
For some multi-threaded targets, @value{GDBN} supports an optional
mode of operation in which you can examine stopped program threads in
the debugger while other threads continue to execute freely. This
minimizes intrusion when debugging live systems, such as programs
where some threads have real-time constraints or must continue to
respond to external events. This is referred to as @dfn{non-stop} mode.
In non-stop mode, when a thread stops to report a debugging event,
@emph{only} that thread is stopped; @value{GDBN} does not stop other
threads as well, in contrast to the all-stop mode behavior. Additionally,
execution commands such as @code{continue} and @code{step} apply by default
only to the current thread in non-stop mode, rather than all threads as
in all-stop mode. This allows you to control threads explicitly in
ways that are not possible in all-stop mode --- for example, stepping
one thread while allowing others to run freely, stepping
one thread while holding all others stopped, or stepping several threads
independently and simultaneously.
To enter non-stop mode, use this sequence of commands before you run
or attach to your program:
@c FIXME: can we fix this recipe to avoid the linux-async/remote-async details?
@smallexample
# Enable the async interface.
# For target remote, use remote-async instead of linux-async.
maint set linux-async 1
# With non-stop, breakpoints have to be always inserted.
set breakpoint always-inserted 1
# If using the CLI, pagination breaks non-stop.
set pagination off
# Finally, turn it on!
set non-stop on
@end smallexample
You can use these commands to manipulate the non-stop mode setting:
@table @code
@kindex set non-stop
@item set non-stop on
Enable selection of non-stop mode.
@item set non-stop off
Disable selection of non-stop mode.
@kindex show non-stop
@item show non-stop
Show the current non-stop enablement setting.
@end table
Note these commands only reflect whether non-stop mode is enabled,
not whether the currently-executing program is being run in non-stop mode.
In particular, the @code{set non-stop} preference is only consulted when
@value{GDBN} starts or connects to the target program, and it is generally
not possible to switch modes once debugging has started. Furthermore,
since not all targets support non-stop mode, even when you have enabled
non-stop mode, @value{GDBN} may still fall back to all-stop operation by
default.
In non-stop mode, all execution commands apply only to the current thread
by default. That is, @code{continue} only continues one thread.
To continue all threads, issue @code{continue -a} or @code{c -a}.
You can use @value{GDBN}'s background execution commands
(@pxref{Background Execution}) to run some threads in the background
while you continue to examine or step others from @value{GDBN}.
The MI execution commands (@pxref{GDB/MI Program Execution}) are
always executed asynchronously in non-stop mode.
Suspending execution is done with the @code{interrupt} command when
running in the background, or @kbd{Ctrl-c} during foreground execution.
In all-stop mode, this stops the whole process;
but in non-stop mode the interrupt applies only to the current thread.
To stop the whole program, use @code{interrupt -a}.
Other execution commands do not currently support the @code{-a} option.
In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make
that thread current, as it does in all-stop mode. This is because the
thread stop notifications are asynchronous with respect to @value{GDBN}'s
command interpreter, and it would be confusing if @value{GDBN} unexpectedly
changed to a different thread just as you entered a command to operate on the
previously current thread.
@node Background Execution
@subsection Background Execution
@cindex foreground execution
@cindex background execution
@cindex asynchronous execution
@cindex execution, foreground, background and asynchronous
@value{GDBN}'s execution commands have two variants: the normal
foreground (synchronous) behavior, and a background
(asynchronous) behavior. In foreground execution, @value{GDBN} waits for
the program to report that some thread has stopped before prompting for
another command. In background execution, @value{GDBN} immediately gives
a command prompt so that you can issue other commands while your program runs.
To specify background execution, add a @code{&} to the command. For example,
the background form of the @code{continue} command is @code{continue&}, or
just @code{c&}. The execution commands that accept background execution
are:
@table @code
@kindex run&
@item run
@xref{Starting, , Starting your Program}.
@item attach
@kindex attach&
@xref{Attach, , Debugging an Already-running Process}.
@item step
@kindex step&
@xref{Continuing and Stepping, step}.
@item stepi
@kindex stepi&
@xref{Continuing and Stepping, stepi}.
@item next
@kindex next&
@xref{Continuing and Stepping, next}.
@item continue
@kindex continue&
@xref{Continuing and Stepping, continue}.
@item finish
@kindex finish&
@xref{Continuing and Stepping, finish}.
@item until
@kindex until&
@xref{Continuing and Stepping, until}.
@end table
Background execution is especially useful in conjunction with non-stop
mode for debugging programs with multiple threads; see @ref{Non-Stop Mode}.
However, you can also use these commands in the normal all-stop mode with
the restriction that you cannot issue another execution command until the
previous one finishes. Examples of commands that are valid in all-stop
mode while the program is running include @code{help} and @code{info break}.
You can interrupt your program while it is running in the background by
using the @code{interrupt} command.
@table @code
@kindex interrupt
@item interrupt
@itemx interrupt -a
Suspend execution of the running program. In all-stop mode,
@code{interrupt} stops the whole process, but in non-stop mode, it stops
only the current thread. To stop the whole program in non-stop mode,
use @code{interrupt -a}.
@end table
You may need to explicitly enable async mode before you can use background
execution commands. @xref{Maintenance Commands}, for details. If the
target doesn't support async mode, @value{GDBN} issues an error message
if you attempt to use the background execution commands.
@node Thread-Specific Breakpoints
@subsection Thread-Specific Breakpoints
When your program has multiple threads (@pxref{Threads,, Debugging When your program has multiple threads (@pxref{Threads,, Debugging
Programs with Multiple Threads}), you can choose whether to set Programs with Multiple Threads}), you can choose whether to set
breakpoints on all threads, or on a particular thread. breakpoints on all threads, or on a particular thread.
@ -4493,18 +4746,14 @@ breakpoint condition, like this:
@end table @end table
@cindex stopped threads @node Interrupted System Calls
@cindex threads, stopped @subsection Interrupted System Calls
Whenever your program stops under @value{GDBN} for any reason,
@emph{all} threads of execution stop, not just the current thread. This
allows you to examine the overall state of the program, including
switching between threads, without worrying that things may change
underfoot.
@cindex thread breakpoints and system calls @cindex thread breakpoints and system calls
@cindex system calls and thread breakpoints @cindex system calls and thread breakpoints
@cindex premature return from system calls @cindex premature return from system calls
There is an unfortunate side effect. If one thread stops for a There is an unfortunate side effect when using @value{GDBN} to debug
multi-threaded programs. If one thread stops for a
breakpoint, or for some other reason, and another thread is blocked in a breakpoint, or for some other reason, and another thread is blocked in a
system call, then the system call may return prematurely. This is a system call, then the system call may return prematurely. This is a
consequence of the interaction between multiple threads and the signals consequence of the interaction between multiple threads and the signals
@ -4542,47 +4791,6 @@ monitor certain events such as thread creation and thread destruction.
When such an event happens, a system call in another thread may return When such an event happens, a system call in another thread may return
prematurely, even though your program does not appear to stop. prematurely, even though your program does not appear to stop.
@cindex continuing threads
@cindex threads, continuing
Conversely, whenever you restart the program, @emph{all} threads start
executing. @emph{This is true even when single-stepping} with commands
like @code{step} or @code{next}.
In particular, @value{GDBN} cannot single-step all threads in lockstep.
Since thread scheduling is up to your debugging target's operating
system (not controlled by @value{GDBN}), other threads may
execute more than one statement while the current thread completes a
single step. Moreover, in general other threads stop in the middle of a
statement, rather than at a clean statement boundary, when the program
stops.
You might even find your program stopped in another thread after
continuing or even single-stepping. This happens whenever some other
thread runs into a breakpoint, a signal, or an exception before the
first thread completes whatever you requested.
On some OSes, you can lock the OS scheduler and thus allow only a single
thread to run.
@table @code
@item set scheduler-locking @var{mode}
@cindex scheduler locking mode
@cindex lock scheduler
Set the scheduler locking mode. If it is @code{off}, then there is no
locking and any thread may run at any time. If @code{on}, then only the
current thread may run when the inferior is resumed. The @code{step}
mode optimizes for single-stepping. It stops other threads from
``seizing the prompt'' by preempting the current thread while you are
stepping. Other threads will only rarely (or never) get a chance to run
when you step. They are more likely to run when you @samp{next} over a
function call, and they are completely free to run when you use commands
like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
thread hits a breakpoint during its timeslice, they will never steal the
@value{GDBN} prompt away from the thread that you are debugging.
@item show scheduler-locking
Display the current scheduler locking mode.
@end table
@node Stack @node Stack
@ -23849,7 +24057,8 @@ compiled with the @samp{-pg} compiler option.
@cindex asynchronous support @cindex asynchronous support
@item maint set linux-async @item maint set linux-async
@itemx maint show linux-async @itemx maint show linux-async
Control the GNU/Linux native asynchronous support of @value{GDBN}. Control the GNU/Linux native asynchronous support
(@pxref{Background Execution}) of @value{GDBN}.
GNU/Linux native asynchronous support will be disabled until you use GNU/Linux native asynchronous support will be disabled until you use
the @samp{maint set linux-async} command to enable it. the @samp{maint set linux-async} command to enable it.
@ -23859,7 +24068,8 @@ the @samp{maint set linux-async} command to enable it.
@cindex asynchronous support @cindex asynchronous support
@item maint set remote-async @item maint set remote-async
@itemx maint show remote-async @itemx maint show remote-async
Control the remote asynchronous support of @value{GDBN}. Control the remote asynchronous support
(@pxref{Background Execution}) of @value{GDBN}.
Remote asynchronous support will be disabled until you use Remote asynchronous support will be disabled until you use
the @samp{maint set remote-async} command to enable it. the @samp{maint set remote-async} command to enable it.