@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
@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
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
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
* 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