@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
+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.
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{C-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{C-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.
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{C-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
levels are between the two arguments (inclusive). If the two arguments
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 then the
+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
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
@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}
@itemize @bullet
@item
-The user presses @kbd{Ctrl-C}. The behaviour is as explained above, and the
+The user types @kbd{C-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
+The user types @kbd{C-d}. This is treated as end of input. No trailing
character (neither newline nor Ctrl-D) is appended to the input.
@end itemize
<- @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