@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
@b{baz}
-@b{C-d}
+@b{Ctrl-d}
m4: End of input: 0: fatal error: EOF in string
@end smallexample
lengths. We allow @code{m4} exit by giving it an EOF as input:
@smallexample
-@b{C-d}
+@b{Ctrl-d}
Program exited normally.
@end smallexample
@item
type @samp{@value{GDBP}} to start @value{GDBN}.
@item
-type @kbd{quit} or @kbd{C-d} to exit.
+type @kbd{quit} or @kbd{Ctrl-d} to exit.
@end itemize
@menu
@item quit @r{[}@var{expression}@r{]}
@itemx q
To exit @value{GDBN}, use the @code{quit} command (abbreviated
-@code{q}), or type an end-of-file character (usually @kbd{C-d}). If you
+@code{q}), or type an end-of-file character (usually @kbd{Ctrl-d}). If you
do not supply @var{expression}, @value{GDBN} will terminate normally;
otherwise it will terminate using the result of @var{expression} as the
error code.
@end table
@cindex interrupt
-An interrupt (often @kbd{C-c}) does not exit from @value{GDBN}, but rather
+An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather
terminates the action of any @value{GDBN} command that is in progress and
returns to @value{GDBN} command level. It is safe to type the interrupt
character at any time because @value{GDBN} does not allow it to take effect
Files,,Command files}).
@cindex repeating command sequences
-@kindex C-o @r{(operate-and-get-next)}
-The @kbd{C-o} binding is useful for repeating a complex sequence of
-commands. This command accepts the current line, like @kbd{RET}, and
+@kindex Ctrl-o @r{(operate-and-get-next)}
+The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of
+commands. This command accepts the current line, like @key{RET}, and
then fetches the next line relative to the current line from the history
for editing.
A signal is an asynchronous event that can happen in a program. The
operating system defines the possible kinds of signals, and gives each
kind a name and a number. For example, in Unix @code{SIGINT} is the
-signal a program gets when you type an interrupt character (often @kbd{C-c});
+signal a program gets when you type an interrupt character (often @kbd{Ctrl-c});
@code{SIGSEGV} is the signal a program gets from referencing a place in
memory far away from all the areas in use; @code{SIGALRM} occurs when
the alarm clock timer goes off (which happens only if your program has
frames in the stack.
You can stop the backtrace at any time by typing the system interrupt
-character, normally @kbd{C-c}.
+character, normally @kbd{Ctrl-c}.
@item backtrace @var{n}
@itemx bt @var{n}
Similar, but print only the outermost @var{n} frames.
@item backtrace full
-Print the values of the local variables also.
@itemx bt full
+@itemx bt full @var{n}
+@itemx bt full -@var{n}
+Print the values of the local variables also. @var{n} specifies the
+number of frames to print, like described above.
@end table
@kindex where
The search path is used to find both program source files and @value{GDBN}
script files (read using the @samp{-command} option and @samp{source} command).
+In addition to the source path, @value{GDBN} provides a set of commands
+that manage a list of source path substitution rules. A @dfn{substitution
+rule} specifies how to rewrite source directories stored in the program's
+debug information in case the sources were moved to a different
+directory between compilation and debugging. A rule is made of
+two strings, the first specifying what needs to be rewritten in
+the path, and the second specifying how it should be rewritten.
+In @ref{set substitute-path}, we name these two parts @var{from} and
+@var{to} respectively. @value{GDBN} does a simple string replacement
+of @var{from} with @var{to} at the start of the directory part of the
+source file name, and uses that result instead of the original file
+name to look up the sources.
+
+Using the previous example, suppose the @file{foo-1.0} tree has been
+moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
+GDB to replace @file{/usr/src} in all source path names with
+@file{/mnt/cross}. The first lookup will then be
+@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
+of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path
+substitution rule, use the @code{set substitute-path} command
+(@pxref{set substitute-path}).
+
+To avoid unexpected substitution results, a rule is applied only if the
+@var{from} part of the directory name ends at a directory separator.
+For instance, a rule substituting @file{/usr/source} into
+@file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but
+not to @file{/usr/sourceware/foo-2.0}. And because the substitution
+is applied only at the begining of the directory name, this rule will
+not be applied to @file{/root/usr/source/baz.c} either.
+
+In many cases, you can achieve the same result using the @code{directory}
+command. However, @code{set substitute-path} can be more efficient in
+the case where the sources are organized in a complex tree with multiple
+subdirectories. With the @code{directory} command, you need to add each
+subdirectory of your project. If you moved the entire tree while
+preserving its internal organization, then @code{set substitute-path}
+allows you to direct the debugger to all the sources with one single
+command.
+
+@code{set substitute-path} is also more than just a shortcut command.
+The source path is only used if the file at the original location no
+longer exists. On the other hand, @code{set substitute-path} modifies
+the debugger behavior to look at the rewritten location instead. So, if
+for any reason a source file that is not relevant to your executable is
+located at the original location, a substitution rule is the only
+method available to point GDB at the new location.
+
@table @code
@item directory @var{dirname} @dots{}
@item dir @var{dirname} @dots{}
@item show directories
@kindex show directories
Print the source path: show which directories it contains.
+
+@anchor{set substitute-path}
+@item set substitute-path @var{from} @var{to}
+@kindex set substitute-path
+Define a source path substitution rule, and add it at the end of the
+current list of existing substitution rules. If a rule with the same
+@var{from} was already defined, then the old rule is also deleted.
+
+For example, if the file @file{/foo/bar/baz.c} was moved to
+@file{/mnt/cross/baz.c}, then the command
+
+@smallexample
+(@value{GDBP}) set substitute-path /usr/src /mnt/cross
+@end smallexample
+
+@noindent
+will tell @value{GDBN} to replace @samp{/usr/src} with
+@samp{/mnt/cross}, which will allow @value{GDBN} to find the file
+@file{baz.c} even though it was moved.
+
+In the case when more than one substitution rule have been defined,
+the rules are evaluated one by one in the order where they have been
+defined. The first one matching, if any, is selected to perform
+the substitution.
+
+For instance, if we had entered the following commands:
+
+@smallexample
+(@value{GDBP}) set substitute-path /usr/src/include /mnt/include
+(@value{GDBP}) set substitute-path /usr/src /mnt/src
+@end smallexample
+
+@noindent
+@value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into
+@file{/mnt/include/defs.h} by using the first rule. However, it would
+use the second rule to rewrite @file{/usr/src/lib/foo.c} into
+@file{/mnt/src/lib/foo.c}.
+
+
+@item unset substitute-path [path]
+@kindex unset substitute-path
+If a path is specified, search the current list of substitution rules
+for a rule that would rewrite that path. Delete that rule if found.
+A warning is emitted by the debugger if no rule could be found.
+
+If no path is specified, then all substitution rules are deleted.
+
+@item show substitute-path [path]
+@kindex show substitute-path
+If a path is specified, then print the source path substitution rule
+which would rewrite that path, if any.
+
+If no path is specified, then print all existing source path substitution
+rules.
+
@end table
If your source path is cluttered with directories that are no longer of
@cindex memory region attributes
@dfn{Memory region attributes} allow you to describe special handling
-required by regions of your target's memory. @value{GDBN} uses attributes
-to determine whether to allow certain types of memory accesses; whether to
-use specific width accesses; and whether to cache target memory.
+required by regions of your target's memory. @value{GDBN} uses
+attributes to determine whether to allow certain types of memory
+accesses; whether to use specific width accesses; and whether to cache
+target memory. By default the description of memory regions is
+fetched from the target (if the current target supports this), but the
+user can override the fetched regions.
Defined memory regions can be individually enabled and disabled. When a
memory region is disabled, @value{GDBN} uses the default attributes when
case: it is treated as the the target's maximum memory address.
(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
+@item mem auto
+Discard any user changes to the memory regions and use target-supplied
+regions, if available, or no regions if the target does not support.
+
@kindex delete mem
@item delete mem @var{nums}@dots{}
Remove memory regions @var{nums}@dots{} from the list of regions
Many remote targets require you to download the executable's code once
you've successfully established a connection. You may wish to control
-various aspects of this process, such as the size of the data chunks
-used by @value{GDBN} to download program parts to the remote target.
+various aspects of this process.
@table @code
-@kindex set download-write-size
-@item set download-write-size @var{size}
-Set the write size used when downloading a program. Only used when
-downloading a program onto a remote target. Specify zero or a
-negative value to disable blocked writes. The actual size of each
-transfer is also limited by the size of the target packet and the
-memory cache.
-
-@kindex show download-write-size
-@item show download-write-size
-@kindex show download-write-size
-Show the current value of the write size.
@item set hash
@kindex set hash@r{, for remote monitors}
specifies a fixed address.
@c FIXME! This would be a good place for an xref to the GNU linker doc.
+Depending on the remote side capabilities, @value{GDBN} may be able to
+load programs into flash memory.
+
@code{load} does not repeat if you press @key{RET} again after using it.
@end table
@cindex interrupting remote programs
@cindex remote programs, interrupting
Whenever @value{GDBN} is waiting for the remote program, if you type the
-interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
+interrupt character (often @kbd{Ctrl-c}), @value{GDBN} attempts to stop the
program. This may or may not succeed, depending in part on the hardware
and the serial drivers the remote system uses. If you type the
interrupt character once again, @value{GDBN} displays this prompt:
@cindex BREAK signal instead of Ctrl-C
@anchor{set remotebreak}
If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
-when you press the @key{Ctrl-C} key to interrupt the program running
+when you type @kbd{Ctrl-c} to interrupt the program running
on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C}
character instead. The default is off, since most remote systems
expect to see @samp{Ctrl-C} as the interrupt signal.
This boolean value controls whether the debuggee should
start a new group or stay in the same group as the debugger.
This affects the way the Windows OS handles
-Ctrl-C.
+@samp{Ctrl-C}.
@kindex show new-group
@item show new-group
Use the @sc{reset} button on the development board
@itemize @bullet
@item
-to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
+to interrupt your program (don't use @kbd{Ctrl-c} on the DOS host---it has
no way to pass an interrupt signal to the development board); and
@item
Connect the controlling terminal to the STDBUG command monitor. When
you are done interacting with STDBUG, typing either of two character
sequences gets you back to the @value{GDBN} command prompt:
-@kbd{@key{RET}~.} (Return, followed by tilde and period) or
-@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
+@kbd{@key{RET} ~ .} (Return, followed by tilde and period) or
+@kbd{@key{RET} ~ C-d} (Return, followed by tilde and control-D).
@end table
@node Z8000
@end table
+@cindex command tracing
+If you need to debug user-defined commands or sourced files you may find it
+useful to enable @dfn{command tracing}. In this mode each command will be
+printed as it is executed, prefixed with one or more @samp{+} symbols, the
+quantity denoting the call depth of each command.
+
+@table @code
+@kindex set trace-commands
+@cindex command scripts, debugging
+@item set trace-commands on
+Enable command tracing.
+@item set trace-commands off
+Disable command tracing.
+@item show trace-commands
+Display the current state of command tracing.
+@end table
+
@node Debugging Output
@section Optional messages about internal happenings
@cindex optional debugging messages
@table @code
@kindex source
@cindex execute commands from a file
-@item source @var{filename}
+@item source [@code{-v}] @var{filename}
Execute the command file @var{filename}.
@end table
@value{GDBN} searches for @var{filename} in the current directory and then
on the search path (specified with the @samp{directory} command).
+If @code{-v}, for verbose mode, is given then @value{GDBN} displays
+each command as it is executed. The option must be given before
+@var{filename}, and is interpreted as part of the filename anywhere else.
+
Commands that would ask for confirmation if used interactively proceed
without asking when used in a command file. Many @value{GDBN} commands that
normally print messages to say what they are doing omit the messages
for scrolling. This means they are available for readline when the
active window is the command window. When the command window
does not have the focus, it is necessary to use other readline
-key bindings such as @key{C-p}, @key{C-n}, @key{C-b} and @key{C-f}.
+key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b} and @kbd{C-f}.
@node TUI Single Key Mode
@section TUI Single Key Mode
it is possible to type most @value{GDBN} commands without interaction
with the TUI @emph{SingleKey} mode. Once the command is entered the TUI
@emph{SingleKey} mode is restored. The only way to permanently leave
-this mode is by hitting @key{q} or @samp{@key{C-x} @key{s}}.
+this mode is by typing @kbd{q} or @kbd{C-x s}.
@node TUI Commands
@item refresh
@kindex refresh
-Refresh the screen. This is similar to using @key{C-L} key.
+Refresh the screen. This is similar to typing @kbd{C-L}.
@item tui reg float
@kindex tui reg
@value{GDBN} @code{down} command.
@end table
-In any source file, the Emacs command @kbd{C-x SPC} (@code{gud-break})
+In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break})
tells @value{GDBN} to set a breakpoint on the source line point is on.
If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which
Display a list of the arguments for the frames between @var{low-frame}
and @var{high-frame} (inclusive). If @var{low-frame} and
-@var{high-frame} are not provided, list the arguments for the whole call
-stack.
+@var{high-frame} are not provided, list the arguments for the whole
+call stack. If the two arguments are equal, show the single frame
+at the corresponding level. It is an error if @var{low-frame} is
+larger than the actual number of frames. On the other hand,
+@var{high-frame} may be larger than the actual number of frames, in
+which case only existing frames will be returned.
The @var{show-values} argument must have a value of 0 or 1. A value of
0 means that only the names of the arguments are listed, a value of 1
If invoked without arguments, this command prints a backtrace for the
whole stack. If given two integer arguments, it shows the frames whose
levels are between the two arguments (inclusive). If the two arguments
-are equal, it shows the single frame at the corresponding level.
+are equal, it shows the single frame at the corresponding level. It is
+an error if @var{low-frame} is larger than the actual number of
+frames. On the other hand, @var{high-frame} may be larger than the
+actual number of frames, in which case only existing frames will be returned.
@subsubheading @value{GDBN} Command
@node Installing GDB
@appendix Installing @value{GDBN}
-@cindex configuring @value{GDBN}
@cindex installation
-@cindex configuring @value{GDBN}, and source tree subdirectories
+@menu
+* Requirements:: Requirements for building @value{GDBN}
+* Running Configure:: Invoking the @value{GDBN} @code{configure} script
+* Separate Objdir:: Compiling @value{GDBN} in another directory
+* Config Names:: Specifying names for hosts and targets
+* Configure Options:: Summary of options for configure
+@end menu
+
+@node Requirements
+@section Requirements for building @value{GDBN}
+@cindex building @value{GDBN}, requirements for
+
+Building @value{GDBN} requires various tools and packages to be available.
+Other packages will be used only if they are found.
+
+@heading Tools/packages necessary for building @value{GDBN}
+@table @asis
+@item ISO C90 compiler
+@value{GDBN} is written in ISO C90. It should be buildable with any
+working C90 compiler, e.g.@: GCC.
+
+@end table
+
+@heading Tools/packages optional for building @value{GDBN}
+@table @asis
+@item Expat
+@value{GDBN} can use the Expat XML parsing library. This library may be
+included with your operating system distribution; if it is not, you
+can get the latest version from @url{http://expat.sourceforge.net}.
+The @code{configure} script will search for this library in several
+standard locations; if it is installed in an unusual path, you can
+use the @option{--with-libexpat-prefix} option to specify its location.
+
+Expat is used currently only used to implement some remote-specific
+features.
+
+@end table
+
+@node Running Configure
+@section Invoking the @value{GDBN} @code{configure} script
+@cindex configuring @value{GDBN}
@value{GDBN} comes with a @code{configure} script that automates the process
of preparing @value{GDBN} for installation; you can then use @code{make} to
build the @code{gdb} program.
that @value{GDBN} uses the shell to start your program---some systems refuse to
let @value{GDBN} debug child processes whose programs are not readable.
-@menu
-* Separate Objdir:: Compiling @value{GDBN} in another directory
-* Config Names:: Specifying names for hosts and targets
-* Configure Options:: Summary of options for configure
-@end menu
-
@node Separate Objdir
@section Compiling @value{GDBN} in another directory
* Interrupts::
* Examples::
* File-I/O remote protocol extension::
+* Memory map format::
@end menu
@node Overview
Reply:
@table @samp
@item @var{XX@dots{}}
-Memory contents; each byte is transmitted as a two-digit hexidecimal
+Memory contents; each byte is transmitted as a two-digit hexadecimal
number. The reply may contain fewer bytes than requested if the
server was able to read only part of the region of memory.
@item E @var{NN}
@cindex @samp{M} packet
Write @var{length} bytes of memory starting at address @var{addr}.
@var{XX@dots{}} is the data; each byte is transmitted as a two-digit
-hexidecimal number.
+hexadecimal number.
Reply:
@table @samp
@anchor{write register packet}
@cindex @samp{P} packet
Write register @var{n@dots{}} with value @var{r@dots{}}. The register
-number @var{n} is in hexidecimal, and @var{r@dots{}} contains two hex
+number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex
digits for each byte in the register (target byte order).
Reply:
The @samp{vCont} packet is not supported.
@end table
+@item vFlashErase:@var{addr},@var{length}
+@cindex @samp{vFlashErase} packet
+Direct the stub to erase @var{length} bytes of flash starting at
+@var{addr}. The region may enclose any number of flash blocks, but
+its start and end must fall on block boundaries, as indicated by the
+flash block size appearing in the memory map (@pxref{Memory map
+format}). @value{GDBN} groups flash memory programming operations
+together, and sends a @samp{vFlashDone} request after each group; the
+stub is allowed to delay erase operation until the @samp{vFlashDone}
+packet is received.
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashWrite:@var{addr}:@var{XX@dots{}}
+@cindex @samp{vFlashWrite} packet
+Direct the stub to write data to flash address @var{addr}. The data
+is passed in binary form using the same encoding as for the @samp{X}
+packet (@pxref{Binary Data}). The memory ranges specified by
+@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must
+not overlap, and must appear in order of increasing addresses
+(although @samp{vFlashErase} packets for higher addresses may already
+have been received; the ordering is guaranteed only between
+@samp{vFlashWrite} packets). If a packet writes to an address that was
+neither erased by a preceding @samp{vFlashErase} packet nor by some other
+target-specific method, the results are unpredictable.
+
+
+Reply:
+@table @samp
+@item OK
+for success
+@item E.memtype
+for vFlashWrite addressing non-flash memory
+@item E @var{NN}
+for an error
+@end table
+
+@item vFlashDone
+@cindex @samp{vFlashDone} packet
+Indicate to the stub that flash programming operation is finished.
+The stub is permitted to delay or batch the effects of a group of
+@samp{vFlashErase} and @samp{vFlashWrite} packets until a
+@samp{vFlashDone} packet is received. The contents of the affected
+regions of flash memory are unpredictable until the @samp{vFlashDone}
+request is completed.
+
@item X @var{addr},@var{length}:@var{XX@dots{}}
@anchor{X packet}
@cindex @samp{X} packet
@table @samp
@item S @var{AA}
-The program received signal number @var{AA} (a two-digit hexidecimal
-number).
+The program received signal number @var{AA} (a two-digit hexadecimal
+number). This is equivalent to a @samp{T} response with no
+@var{n}:@var{r} pairs.
@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{}
@cindex @samp{T} packet reply
-The program received signal number @var{AA} (a two-digit hexidecimal
-number). Single-step and breakpoint traps are reported this way. The
-@samp{@var{n}:@var{r}} pairs give the values of important registers or
-other information:
+The program received signal number @var{AA} (a two-digit hexadecimal
+number). This is equivalent to an @samp{S} response, except that the
+@samp{@var{n}:@var{r}} pairs can carry values of important registers
+and other information directly in the stop reply packet, reducing
+round-trip latency. Single-step and breakpoint traps are reported
+this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows:
@enumerate
@item
-If @var{n} is a hexidecimal number, it is a register number, and the
+If @var{n} is a hexadecimal number, it is a register number, and the
corresponding @var{r} gives that register's value. @var{r} is a
series of bytes in target byte order, with each byte given by a
two-digit hex number.
Reply:
@table @samp
@item QC @var{pid}
-Where @var{pid} is an unsigned hexidecimal process id.
+Where @var{pid} is an unsigned hexadecimal process id.
@item @r{(anything else)}
Any other reply implies the old pid.
@end table
@tab @samp{-}
@tab Yes
+@item @samp{qXfer:memory-map:read}
+@tab No
+@tab @samp{-}
+@tab Yes
+
@end multitable
These are the currently defined stub features, in more detail:
@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
@cindex read special object, remote request
@cindex @samp{qXfer} packet
+@anchor{qXfer read}
Read uninterpreted bytes from the target's special data area
identified by the keyword @var{object}. Request @var{length} bytes
starting at @var{offset} bytes into the data. The content and
by suppling an appropriate @samp{qSupported} response (@pxref{qSupported}).
@end table
+@table @samp
+@item qXfer:memory-map:read::@var{offset},@var{length}
+@anchor{qXfer memory map read}
+Access the target's @dfn{memory-map}. @xref{Memory map format}. The
+annex part of the generic @samp{qXfer} packet must be empty
+(@pxref{qXfer read}).
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
+@end table
+
Reply:
@table @samp
@item m @var{data}
The following @code{g}/@code{G} packets have previously been defined.
In the below, some thirty-two bit registers are transferred as
sixty-four bits. Those registers should be zero/sign extended (which?)
-to fill the space allocated. Register bytes are transfered in target
-byte order. The two nibbles within a register byte are transfered
+to fill the space allocated. Register bytes are transferred in target
+byte order. The two nibbles within a register byte are transferred
most-significant - least-significant.
@table @r
@item MIPS32
-All registers are transfered as thirty-two bit quantities in the order:
+All registers are transferred as thirty-two bit quantities in the order:
32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
registers; fsr; fir; fp.
@item MIPS64
-All registers are transfered as sixty-four bit quantities (including
+All registers are transferred as sixty-four bit quantities (including
thirty-two bit registers such as @code{sr}). The ordering is the same
as @code{MIPS32}.
@item R @var{mask}
Collect the registers whose bits are set in @var{mask}. @var{mask} is
-a hexidecimal number whose @var{i}'th bit is set if register number
+a hexadecimal number whose @var{i}'th bit is set if register number
@var{i} should be collected. (The least significant bit is numbered
zero.) Note that @var{mask} may be any number of digits long; it may
not fit in a 32-bit word.
number @var{basereg}, plus @var{offset}. If @var{basereg} is
@samp{-1}, then the range has a fixed address: @var{offset} is the
address of the lowest byte to collect. The @var{basereg},
-@var{offset}, and @var{len} parameters are all unsigned hexidecimal
+@var{offset}, and @var{len} parameters are all unsigned hexadecimal
values (the @samp{-1} value for @var{basereg} is a special case).
@item X @var{len},@var{expr}
@table @samp
@item F @var{f}
The selected frame is number @var{n} in the trace frame buffer;
-@var{f} is a hexidecimal number. If @var{f} is @samp{-1}, then there
+@var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there
was no frame matching the criteria in the request packet.
@item T @var{t}
The selected trace frame records a hit of tracepoint number @var{t};
-@var{t} is a hexidecimal number.
+@var{t} is a hexadecimal number.
@end table
@item QTFrame:pc:@var{addr}
Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
currently selected frame whose PC is @var{addr};
-@var{addr} is a hexidecimal number.
+@var{addr} is a hexadecimal number.
@item QTFrame:tdp:@var{t}
Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
currently selected frame that is a hit of tracepoint @var{t}; @var{t}
-is a hexidecimal number.
+is a hexadecimal number.
@item QTFrame:range:@var{start}:@var{end}
Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
currently selected frame whose PC is between @var{start} (inclusive)
-and @var{end} (exclusive); @var{start} and @var{end} are hexidecimal
+and @var{end} (exclusive); @var{start} and @var{end} are hexadecimal
numbers.
@item QTFrame:outside:@var{start}:@var{end}
the target is stopped to allow deterministic access to the target's
memory. Therefore File-I/O is not interruptible by target signals. On
the other hand, it is possible to interrupt File-I/O by a user interrupt
-(Ctrl-C) within @value{GDBN}.
+(@samp{Ctrl-C}) within @value{GDBN}.
The target's request to perform a host system call does not finish
the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means,
@node The Ctrl-C message
-@subsection The Ctrl-C message
+@subsection The @samp{Ctrl-C} message
@cindex ctrl-c message, in file-i/o protocol
-If the Ctrl-C flag is set in the @value{GDBN}
-reply packet (@pxref{The F reply packet}),
+If the @samp{Ctrl-C} flag is set in the @value{GDBN}
+reply packet (@pxref{The F reply packet}),
the target should behave as if it had
gotten a break message. The meaning for the target is ``system call
interrupted by @code{SIGINT}''. Consequentially, the target should actually stop
(as with a break message) and return to @value{GDBN} with a @code{T02}
-packet.
+packet.
It's important for the target to know in which
state the system call was interrupted. There are two possible cases:
@itemize @bullet
@item
-The user presses @kbd{Ctrl-C}. The behaviour is as explained above, and the
+The user types @kbd{Ctrl-c}. The behaviour is as explained above, and the
@code{read}
system call is treated as finished.
@item
-The user presses @kbd{Enter}. This is treated as end of input with a trailing
+The user presses @key{RET}. This is treated as end of input with a trailing
newline.
@item
-The user presses @kbd{Ctrl-D}. This is treated as end of input. No trailing
-character (neither newline nor Ctrl-D) is appended to the input.
+The user types @kbd{Ctrl-d}. This is treated as end of input. No trailing
+character (neither newline nor @samp{Ctrl-D}) is appended to the input.
@end itemize
-> @code{F-1,9}
@end smallexample
-Example sequence of a read call, user presses Ctrl-C before syscall on
+Example sequence of a read call, user presses @kbd{Ctrl-c} before syscall on
host is called:
@smallexample
<- @code{T02}
@end smallexample
-Example sequence of a read call, user presses Ctrl-C after syscall on
+Example sequence of a read call, user presses @kbd{Ctrl-c} after syscall on
host is called:
@smallexample
<- @code{T02}
@end smallexample
+@node Memory map format
+@section Memory map format
+@cindex memory map format
+
+To be able to write into flash memory, @value{GDBN} needs to obtain a
+memory map from the target. This section describes the format of the
+memory map.
+
+The memory map is obtained using the @samp{qXfer:memory-map:read}
+(@pxref{qXfer memory map read}) packet and is an XML document that
+lists memory regions. The top-level structure of the document is shown below:
+
+@smallexample
+<?xml version="1.0"?>
+<!DOCTYPE memory-map
+ PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
+ "http://sourceware.org/gdb/gdb-memory-map.dtd">
+<memory-map>
+ region...
+</memory-map>
+@end smallexample
+
+Each region can be either:
+
+@itemize
+
+@item
+A region of RAM starting at @var{addr} and extending for @var{length}
+bytes from there:
+
+@smallexample
+<memory type="ram" start="@var{addr}" length="@var{length}"/>
+@end smallexample
+
+
+@item
+A region of read-only memory:
+
+@smallexample
+<memory type="rom" start="@var{addr}" length="@var{length}"/>
+@end smallexample
+
+
+@item
+A region of flash memory, with erasure blocks @var{blocksize}
+bytes in length:
+
+@smallexample
+<memory type="flash" start="@var{addr}" length="@var{length}">
+ <property name="blocksize">@var{blocksize}</property>
+</memory>
+@end smallexample
+
+@end itemize
+
+Regions must not overlap. @value{GDBN} assumes that areas of memory not covered
+by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X}
+packets to write to addresses in such ranges.
+
+The formal DTD for memory map format is given below:
+
+@smallexample
+<!-- ................................................... -->
+<!-- Memory Map XML DTD ................................ -->
+<!-- File: memory-map.dtd .............................. -->
+<!-- .................................... .............. -->
+<!-- memory-map.dtd -->
+<!-- memory-map: Root element with versioning -->
+<!ELEMENT memory-map (memory | property)>
+<!ATTLIST memory-map version CDATA #FIXED "1.0.0">
+<!ELEMENT memory (property)>
+<!-- memory: Specifies a memory region,
+ and its type, or device. -->
+<!ATTLIST memory type CDATA #REQUIRED
+ start CDATA #REQUIRED
+ length CDATA #REQUIRED
+ device CDATA #IMPLIED>
+<!-- property: Generic attribute tag -->
+<!ELEMENT property (#PCDATA | property)*>
+<!ATTLIST property name CDATA #REQUIRED>
+@end smallexample
+
@include agentexpr.texi
@include gpl.texi
projects / deliverable / binutils-gdb.git / blobdiff