This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: Formatting of packet descriptions in GDB manual
- From: Jim Blandy <jimb at red-bean dot com>
- To: gdb-patches at sources dot redhat dot com
- Date: Tue, 15 Nov 2005 21:52:06 -0800
- Subject: Re: Formatting of packet descriptions in GDB manual
- References: <8f2776cb0511111624h4d646cd9i1f86824c5edc613f@mail.gmail.com> <ubr0q2vl9.fsf@gnu.org> <8f2776cb0511120047y50b3a273pe17ddd5c53342be1@mail.gmail.com> <u4q6h32bk.fsf@gnu.org> <20051113171247.GA1945@nevyn.them.org> <ur79ki4h7.fsf@gnu.org> <20051114022955.GA10567@nevyn.them.org> <uoe4nj1ih.fsf@gnu.org> <20051114134924.GB21373@nevyn.them.org> <8f2776cb0511152147i4c24e43aue46a54332fd4c0f3@mail.gmail.com>
Here's a patch that implements the formatting changes to the
description of the remote protocol packets we've been discussing on
gdb@.
This uses @code for the packet templates, even though in my last
message there I said I thought @samp was more appropriate; @code is
what I've got right now, and I didn't want to go and change everything
twice if the conclusion was that @code was better. But you can see
what was done.
gdb/doc/ChangeLog:
2005-11-15 Jim Blandy <jimb@redhat.com>
* gdb.texinfo (Packets): Use @code for packet contents. Drop
summaries from packet @item lines; the same information appears
immediately below in the description. Delete paragraph breaks
after packet @item commands, so that the description appears
directly to the right of the packet prototype in the printed
manual, if it fits. Place spaces in packet prototypes between
@vars and non-@var letters, and explain that they're just for
formatting. Use @dots{} instead of '...'.
gdb/doc/ChangeLog:
2005-11-15 Jim Blandy <jimb@redhat.com>
* gdb.texinfo (Packets): Use @code for packet contents. Drop
summaries from packet @item lines; the same information appears
immediately below in the description. Delete paragraph breaks
after packet @item commands, so that the description appears
directly to the right of the packet prototype in the printed
manual, if it fits. Place spaces in packet prototypes between
@vars and non-@var letters, and explain that they're just for
formatting. Use @dots{} instead of '...'.
Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.290
diff -c -p -r1.290 gdb.texinfo
*** gdb/doc/gdb.texinfo 15 Nov 2005 19:58:30 -0000 1.290
--- gdb/doc/gdb.texinfo 16 Nov 2005 05:48:35 -0000
*************** The following table provides a complete
*** 22128,22176 ****
@xref{File-I/O remote protocol extension}, for details about the File
I/O extension of the remote protocol.
Note that all packet forms beginning with an upper- or lower-case
letter, other than those described here, are reserved for future use.
! @table @r
! @item @code{!} --- extended mode
! @cindex @code{!} packet
Enable extended mode. In extended mode, the remote server is made
! persistent. The @samp{R} packet is used to restart the program being
debugged.
Reply:
! @table @samp
@item OK
The remote target both supports and has enabled extended mode.
@end table
! @item @code{?} --- last signal
@cindex @code{?} packet
-
Indicate the reason the target halted. The reply is the same as for
step and continue.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,@dots{}} --- set program arguments @strong{(reserved)}
@cindex @code{A} packet
!
! Initialized @samp{argv[]} array passed into program. @var{arglen}
specifies the number of bytes in the hex encoded byte stream @var{arg}.
See @code{gdbserver} for more details.
Reply:
! @table @samp
@item OK
! @item E@var{NN}
@end table
! @item @code{b}@var{baud} --- set baud @strong{(deprecated)}
@cindex @code{b} packet
!
Change the serial line speed to @var{baud}.
JTC: @emph{When does the transport layer state change? When it's
--- 22128,22187 ----
@xref{File-I/O remote protocol extension}, for details about the File
I/O extension of the remote protocol.
+ Each packet's description has a template showing the packet's overall
+ syntax, followed by an explanation of the packet's meaning. We
+ include spaces in some of the templates for clarity; these are not
+ part of the packet's syntax. No @value{GDBN} packet uses spaces to
+ separate its components. For example, a template like @code{foo
+ @var{bar} @var{baz}} describes a packet beginning with the three ASCII
+ bytes @samp{foo}, followed by a @var{bar}, followed directly by a
+ @var{baz}. GDB does not transmit a space character between the
+ @code{foo} and the @var{bar}, or between the @var{bar} and the
+ @var{baz}.
+
Note that all packet forms beginning with an upper- or lower-case
letter, other than those described here, are reserved for future use.
! Here are the packet descriptions.
! @table @code
+ @item !
+ @cindex @code{!} packet
Enable extended mode. In extended mode, the remote server is made
! persistent. The @code{R} packet is used to restart the program being
debugged.
Reply:
! @table @code
@item OK
The remote target both supports and has enabled extended mode.
@end table
! @item ?
@cindex @code{?} packet
Indicate the reason the target halted. The reply is the same as for
step and continue.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item A @var{arglen},@var{argnum},@var{arg},@dots{}
@cindex @code{A} packet
! @strong{(reserved)}
! Initialized @code{argv[]} array passed into program. @var{arglen}
specifies the number of bytes in the hex encoded byte stream @var{arg}.
See @code{gdbserver} for more details.
Reply:
! @table @code
@item OK
! @item E @var{NN}
@end table
! @item b @var{baud}
@cindex @code{b} packet
! @strong{(deprecated)}
Change the serial line speed to @var{baud}.
JTC: @emph{When does the transport layer state change? When it's
*************** some kind of out-of-band message to a sp
*** 22183,22288 ****
switch happen "in between" packets, so that from remote protocol's point
of view, nothing actually happened.}
! @item @code{B}@var{addr},@var{mode} --- set breakpoint @strong{(deprecated)}
@cindex @code{B} packet
!
Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
breakpoint at @var{addr}.
This packet has been replaced by the @samp{Z} and @samp{z} packets
(@pxref{insert breakpoint or watchpoint packet}).
! @item @code{c}@var{addr} --- continue
@cindex @code{c} packet
!
! @var{addr} is address to resume. If @var{addr} is omitted, resume at
! current address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item @code{C}@var{sig}@code{;}@var{addr} --- continue with signal
@cindex @code{C} packet
-
Continue with signal @var{sig} (hex signal number). If
! @code{;}@var{addr} is omitted, resume at same address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item @code{d} --- toggle debug @strong{(deprecated)}
@cindex @code{d} packet
!
Toggle debug flag.
! @item @code{D} --- detach
@cindex @code{D} packet
-
Detach @value{GDBN} from the remote system. Sent to the remote target
before @value{GDBN} disconnects via the @code{detach} command.
Reply:
! @table @samp
@item OK
for success
! @item E@var{NN}
for an error
@end table
! @item @code{F}@var{RC}@code{,}@var{EE}@code{,}@var{CF}@code{;}@var{XX} --- Reply to target's F packet.
@cindex @code{F} packet
! This packet is send by @value{GDBN} as reply to a @code{F} request packet
! sent by the target. This is part of the File-I/O protocol extension.
! @xref{File-I/O remote protocol extension}, for the specification.
!
! @item @code{g} --- read registers
@anchor{read registers packet}
@cindex @code{g} packet
-
Read general registers.
Reply:
! @table @samp
@item @var{XX@dots{}}
Each byte of register data is described by two hex digits. The bytes
with the register are transmitted in target byte order. The size of
! each register and their position within the @samp{g} @var{packet} are
determined by the @value{GDBN} internal macros
! @var{DEPRECATED_REGISTER_RAW_SIZE} and @var{REGISTER_NAME} macros. The
specification of several standard @code{g} packets is specified below.
! @item E@var{NN}
for an error.
@end table
! @item @code{G}@var{XX@dots{}} --- write regs
@cindex @code{G} packet
!
! @xref{read registers packet}, for a description of the @var{XX@dots{}}
! data.
Reply:
! @table @samp
@item OK
for success
! @item E@var{NN}
for an error
@end table
! @item @code{H}@var{c}@var{t@dots{}} --- set thread
@cindex @code{H} packet
!
! Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
! @samp{G}, et.al.). @var{c} depends on the operation to be performed: it
! should be @samp{c} for step and continue operations, @samp{g} for other
! operations. The thread designator @var{t@dots{}} may be -1, meaning all
! the threads, a thread number, or zero which means pick any thread.
Reply:
! @table @samp
@item OK
for success
! @item E@var{NN}
for an error
@end table
--- 22194,22292 ----
switch happen "in between" packets, so that from remote protocol's point
of view, nothing actually happened.}
! @item B @var{addr},@var{mode}
@cindex @code{B} packet
! @strong{(deprecated)}
Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
breakpoint at @var{addr}.
This packet has been replaced by the @samp{Z} and @samp{z} packets
(@pxref{insert breakpoint or watchpoint packet}).
! @item c @var{addr}
@cindex @code{c} packet
! Continue. @var{addr} is address to resume. If @var{addr} is omitted,
! resume at current address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item C @var{sig};@var{addr}
@cindex @code{C} packet
Continue with signal @var{sig} (hex signal number). If
! @code{;@var{addr}} is omitted, resume at same address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item d
@cindex @code{d} packet
! @strong{(deprecated)}
Toggle debug flag.
! @item D
@cindex @code{D} packet
Detach @value{GDBN} from the remote system. Sent to the remote target
before @value{GDBN} disconnects via the @code{detach} command.
Reply:
! @table @code
@item OK
for success
! @item E @var{NN}
for an error
@end table
! @item F @var{RC},@var{EE},@var{CF};@var{XX}
@cindex @code{F} packet
+ A reply from @value{GDBN} to an @code{F} packet sent by the target.
+ This is part of the File-I/O protocol extension. @xref{File-I/O
+ remote protocol extension}, for the specification.
! @item g
@anchor{read registers packet}
@cindex @code{g} packet
Read general registers.
Reply:
! @table @code
@item @var{XX@dots{}}
Each byte of register data is described by two hex digits. The bytes
with the register are transmitted in target byte order. The size of
! each register and their position within the @code{g} packet are
determined by the @value{GDBN} internal macros
! @code{DEPRECATED_REGISTER_RAW_SIZE} and @code{REGISTER_NAME} macros. The
specification of several standard @code{g} packets is specified below.
! @item E @var{NN}
for an error.
@end table
! @item G @var{XX@dots{}}
@cindex @code{G} packet
! Write general registers. @xref{read registers packet}, for a
! description of the @var{XX@dots{}} data.
Reply:
! @table @code
@item OK
for success
! @item E @var{NN}
for an error
@end table
! @item H @var{c} @var{t}
@cindex @code{H} packet
! Set thread for subsequent operations (@code{m}, @code{M}, @code{g},
! @code{G}, et.al.). @var{c} depends on the operation to be performed: it
! should be @code{c} for step and continue operations, @code{g} for other
! operations. The thread designator @var{t} may be @code{-1}, meaning all
! the threads, a thread number, or @code{0} which means pick any thread.
Reply:
! @table @code
@item OK
for success
! @item E @var{NN}
for an error
@end table
*************** for an error
*** 22301,22329 ****
@c selected, sets the registers of the register block of
@c that thread; otherwise sets current registers.
! @item @code{i}@var{addr}@code{,}@var{nnn} --- cycle step @strong{(draft)}
@anchor{cycle step packet}
@cindex @code{i} packet
!
Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
step starting at that address.
! @item @code{I} --- signal then cycle step @strong{(reserved)}
@cindex @code{I} packet
! @xref{step with signal packet}. @xref{cycle step packet}.
!
! @item @code{k} --- kill request
@cindex @code{k} packet
FIXME: @emph{There is no description of how to operate when a specific
thread context has been selected (i.e.@: does 'k' kill only that
thread?)}.
! @item @code{m}@var{addr}@code{,}@var{length} --- read memory
@cindex @code{m} packet
-
Read @var{length} bytes of memory starting at address @var{addr}.
Note that @var{addr} may not be aligned to any particular boundary.
--- 22305,22333 ----
@c selected, sets the registers of the register block of
@c that thread; otherwise sets current registers.
! @item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]}
@anchor{cycle step packet}
@cindex @code{i} packet
! @strong{(draft)}
Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
step starting at that address.
! @item I
@cindex @code{I} packet
+ @strong{(reserved)} Signal, then cycle step. @xref{step with signal
+ packet}. @xref{cycle step packet}.
! @item k
@cindex @code{k} packet
+ Kill request.
FIXME: @emph{There is no description of how to operate when a specific
thread context has been selected (i.e.@: does 'k' kill only that
thread?)}.
! @item m @var{addr},@var{length}
@cindex @code{m} packet
Read @var{length} bytes of memory starting at address @var{addr}.
Note that @var{addr} may not be aligned to any particular boundary.
*************** use byte accesses, or not. For this rea
*** 22334,22484 ****
suitable for accessing memory-mapped I/O devices.
Reply:
! @table @samp
@item @var{XX@dots{}}
! @var{XX@dots{}} is mem contents. Can be fewer bytes than requested if able
! to read only part of the data.
! @item E@var{NN}
@var{NN} is errno
@end table
! @item @code{M}@var{addr},@var{length}@code{:}@var{XX@dots{}} --- write mem
@cindex @code{M} packet
-
Write @var{length} bytes of memory starting at address @var{addr}.
! @var{XX@dots{}} is the data.
Reply:
! @table @samp
@item OK
for success
! @item E@var{NN}
for an error (this includes the case where only part of the data was
written).
@end table
! @item @code{p}@var{hex number of register} --- read register packet
@cindex @code{p} packet
!
@xref{read registers packet}, for a description of how the returned
register value is encoded.
Reply:
! @table @samp
@item @var{XX@dots{}}
the register's value
! @item E@var{NN}
for an error
@item
Indicating an unrecognized @var{query}.
@end table
! @item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register
@anchor{write register packet}
@cindex @code{P} packet
!
! Write register @var{n@dots{}} with value @var{r@dots{}}, which contains two hex
digits for each byte in the register (target byte order).
Reply:
! @table @samp
@item OK
for success
! @item E@var{NN}
for an error
@end table
! @item @code{q}@var{query} --- general query
@anchor{general query packet}
@cindex @code{q} packet
!
! Request info about @var{query}. In general @value{GDBN} queries have a
! leading upper case letter. Custom vendor queries should use a company
! prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may optionally
! be followed by a @samp{,} or @samp{;} separated list. Stubs must ensure
! that they match the full @var{query} name.
Reply:
! @table @samp
@item @var{XX@dots{}}
! Hex encoded data from query. The reply can not be empty.
! @item E@var{NN}
error reply
! @item
Indicating an unrecognized @var{query}.
@end table
! @item @code{Q}@var{var}@code{=}@var{val} --- general set
@cindex @code{Q} packet
!
! Set value of @var{var} to @var{val}.
!
@xref{general query packet}, for a discussion of naming conventions.
! @item @code{r} --- reset @strong{(deprecated)}
@cindex @code{r} packet
! Reset the entire system.
!
! @item @code{R}@var{XX} --- remote restart
@cindex @code{R} packet
-
Restart the program being debugged. @var{XX}, while needed, is ignored.
This packet is only available in extended mode.
! Reply:
! @table @samp
! @item @emph{no reply}
! The @samp{R} packet has no reply.
! @end table
! @item @code{s}@var{addr} --- step
@cindex @code{s} packet
!
! @var{addr} is address to resume. If @var{addr} is omitted, resume at
! same address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item @code{S}@var{sig}@code{;}@var{addr} --- step with signal
@anchor{step with signal packet}
@cindex @code{S} packet
!
! Like @samp{C} but step not continue.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search
@cindex @code{t} packet
-
Search backwards starting at address @var{addr} for a match with pattern
@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
@var{addr} must be at least 3 digits.
! @item @code{T}@var{XX} --- thread alive
@cindex @code{T} packet
-
Find out if the thread XX is alive.
Reply:
! @table @samp
@item OK
thread is still alive
! @item E@var{NN}
thread is dead
@end table
! @item @code{v} --- verbose packet prefix
!
Packets starting with @code{v} are identified by a multi-letter name,
up to the first @code{;} or @code{?} (or the end of the packet).
! @item @code{vCont}[;@var{action}[@code{:}@var{tid}]]... --- extended resume
@cindex @code{vCont} packet
!
! Resume the inferior. Different actions may be specified for each thread.
If an action is specified with no @var{tid}, then it is applied to any
threads that don't have a specific action specified; if no default action is
specified then other threads should remain stopped. Specifying multiple
--- 22338,22476 ----
suitable for accessing memory-mapped I/O devices.
Reply:
! @table @code
@item @var{XX@dots{}}
! Memory contents; each byte is transmitted as a two-digit hexidecimal
! 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}
@var{NN} is errno
@end table
! @item M @var{addr},@var{length}:@var{XX@dots{}}
@cindex @code{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.
Reply:
! @table @code
@item OK
for success
! @item E @var{NN}
for an error (this includes the case where only part of the data was
written).
@end table
! @item p @var{n}
@cindex @code{p} packet
! Read the value of register @var{n}; @var{n} is in hex.
@xref{read registers packet}, for a description of how the returned
register value is encoded.
Reply:
! @table @code
@item @var{XX@dots{}}
the register's value
! @item E @var{NN}
for an error
@item
Indicating an unrecognized @var{query}.
@end table
! @item P @var{n@dots{}}=@var{r@dots{}}
@anchor{write register packet}
@cindex @code{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
digits for each byte in the register (target byte order).
Reply:
! @table @code
@item OK
for success
! @item E @var{NN}
for an error
@end table
! @item q @var{query}
@anchor{general query packet}
@cindex @code{q} packet
! General query. Request info about @var{query}. In general
! @value{GDBN} queries have a leading upper case letter. Custom vendor
! queries should use a company prefix (in lower case) ex:
! @code{qfsf.var}. @var{query} may optionally be followed by a @code{,}
! or @code{;} separated list. Stubs must ensure that they match the
! full @var{query} name.
Reply:
! @table @code
@item @var{XX@dots{}}
! Hex encoded data from query. The reply must not be empty.
! @item E @var{NN}
error reply
! @item @r{(empty)}
Indicating an unrecognized @var{query}.
@end table
! @item Q @var{var}=@var{val}
@cindex @code{Q} packet
! General set. Set value of @var{var} to @var{val}.
@xref{general query packet}, for a discussion of naming conventions.
! @item r
@cindex @code{r} packet
+ @strong{(deprecated)} Reset the entire system.
! @item R @var{XX}
@cindex @code{R} packet
Restart the program being debugged. @var{XX}, while needed, is ignored.
This packet is only available in extended mode.
! The @code{R} packet has no reply.
! @item s @var{addr}
@cindex @code{s} packet
! Single step. @var{addr} is the address at which to resume. If
! @var{addr} is omitted, resume at same address.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item S @var{sig};@var{addr}
@anchor{step with signal packet}
@cindex @code{S} packet
! Step with signal. This is analogous to the @code{C} packet, but
! requests a single-step, rather than a normal resumption of execution.
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item t @var{addr}:@var{PP},@var{MM}
@cindex @code{t} packet
Search backwards starting at address @var{addr} for a match with pattern
@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
@var{addr} must be at least 3 digits.
! @item T @var{XX}
@cindex @code{T} packet
Find out if the thread XX is alive.
Reply:
! @table @code
@item OK
thread is still alive
! @item E @var{NN}
thread is dead
@end table
! @item v
Packets starting with @code{v} are identified by a multi-letter name,
up to the first @code{;} or @code{?} (or the end of the packet).
! @item vCont@r{[};@var{action}@r{[}:@var{tid}@r{]]}@dots{}
@cindex @code{vCont} packet
! Resume the inferior, specifying different actions for each thread.
If an action is specified with no @var{tid}, then it is applied to any
threads that don't have a specific action specified; if no default action is
specified then other threads should remain stopped. Specifying multiple
*************** Thread IDs are specified in hexadecimal.
*** 22488,22498 ****
@table @code
@item c
Continue.
! @item C@var{sig}
Continue with signal @var{sig}. @var{sig} should be two hex digits.
@item s
Step.
! @item S@var{sig}
Step with signal @var{sig}. @var{sig} should be two hex digits.
@end table
--- 22480,22490 ----
@table @code
@item c
Continue.
! @item C @var{sig}
Continue with signal @var{sig}. @var{sig} should be two hex digits.
@item s
Step.
! @item S @var{sig}
Step with signal @var{sig}. @var{sig} should be two hex digits.
@end table
*************** not supported in @code{vCont}.
*** 22502,22543 ****
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item @code{vCont?} --- extended resume query
@cindex @code{vCont?} packet
!
! Query support for the @code{vCont} packet.
Reply:
! @table @samp
! @item @code{vCont}[;@var{action}]...
The @code{vCont} packet is supported. Each @var{action} is a supported
command in the @code{vCont} packet.
! @item
The @code{vCont} packet is not supported.
@end table
! @item @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX@dots{}} --- write mem (binary)
@cindex @code{X} packet
!
@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}}
is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
escaped using @code{0x7d}, and then XORed with @code{0x20}.
For example, @code{0x7d} would be transmitted as @code{0x7d 0x5d}.
Reply:
! @table @samp
@item OK
for success
! @item E@var{NN}
for an error
@end table
! @item @code{z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- remove breakpoint or watchpoint @strong{(draft)}
! @itemx @code{Z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- insert breakpoint or watchpoint @strong{(draft)}
@anchor{insert breakpoint or watchpoint packet}
@cindex @code{z} packet
@cindex @code{Z} packets
!
Insert (@code{Z}) or remove (@code{z}) a @var{type} breakpoint or
watchpoint starting at address @var{address} and covering the next
@var{length} bytes.
--- 22494,22534 ----
Reply:
@xref{Stop Reply Packets}, for the reply specifications.
! @item vCont?
@cindex @code{vCont?} packet
! Request a list of actions supporetd by the @code{vCont} packet.
Reply:
! @table @code
! @item vCont@r{[};@var{action}@dots{}@r{]}
The @code{vCont} packet is supported. Each @var{action} is a supported
command in the @code{vCont} packet.
! @item @r{(empty)}
The @code{vCont} packet is not supported.
@end table
! @item X @var{addr},@var{length}:@var{XX@dots{}}
@cindex @code{X} packet
! Write data to memory, where the data is transmitted in binary.
@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}}
is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
escaped using @code{0x7d}, and then XORed with @code{0x20}.
For example, @code{0x7d} would be transmitted as @code{0x7d 0x5d}.
Reply:
! @table @code
@item OK
for success
! @item E @var{NN}
for an error
@end table
! @item z @var{type},@var{addr},@var{length}
! @itemx Z @var{type},@var{addr},@var{length}
@anchor{insert breakpoint or watchpoint packet}
@cindex @code{z} packet
@cindex @code{Z} packets
! @strong{(draft)}
Insert (@code{Z}) or remove (@code{z}) a @var{type} breakpoint or
watchpoint starting at address @var{address} and covering the next
@var{length} bytes.
*************** separately.
*** 22548,22562 ****
@emph{Implementation notes: A remote target shall return an empty string
for an unrecognized breakpoint or watchpoint packet @var{type}. A
remote target shall support either both or neither of a given
! @code{Z}@var{type}@dots{} and @code{z}@var{type}@dots{} packet pair. To
avoid potential problems with duplicate packets, the operations should
be implemented in an idempotent way.}
! @item @code{z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- remove memory breakpoint @strong{(draft)}
! @item @code{Z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- insert memory breakpoint @strong{(draft)}
@cindex @code{z0} packet
@cindex @code{Z0} packet
!
Insert (@code{Z0}) or remove (@code{z0}) a memory breakpoint at address
@code{addr} of size @code{length}.
--- 22539,22553 ----
@emph{Implementation notes: A remote target shall return an empty string
for an unrecognized breakpoint or watchpoint packet @var{type}. A
remote target shall support either both or neither of a given
! @code{Z@var{type}@dots{}} and @code{z@var{type}@dots{}} packet pair. To
avoid potential problems with duplicate packets, the operations should
be implemented in an idempotent way.}
! @item z0,@var{addr},@var{length}
! @item Z0,@var{addr},@var{length}
@cindex @code{z0} packet
@cindex @code{Z0} packet
! @strong{(draft)}
Insert (@code{Z0}) or remove (@code{z0}) a memory breakpoint at address
@code{addr} of size @code{length}.
*************** overlays). The behavior of this packet,
*** 22572,22591 ****
target, is not defined.}
Reply:
! @table @samp
@item OK
success
! @item
not supported
! @item E@var{NN}
for an error
@end table
! @item @code{z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- remove hardware breakpoint @strong{(draft)}
! @item @code{Z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- insert hardware breakpoint @strong{(draft)}
@cindex @code{z1} packet
@cindex @code{Z1} packet
!
Insert (@code{Z1}) or remove (@code{z1}) a hardware breakpoint at
address @code{addr} of size @code{length}.
--- 22563,22582 ----
target, is not defined.}
Reply:
! @table @code
@item OK
success
! @item @r{(empty)}
not supported
! @item E @var{NN}
for an error
@end table
! @item z1,@var{addr},@var{length}
! @item Z1,@var{addr},@var{length}
@cindex @code{z1} packet
@cindex @code{Z1} packet
! @strong{(draft)}
Insert (@code{Z1}) or remove (@code{z1}) a hardware breakpoint at
address @code{addr} of size @code{length}.
*************** dependant on being able to modify the ta
*** 22596,22658 ****
movement.}
Reply:
! @table @samp
@item OK
success
! @item
not supported
! @item E@var{NN}
for an error
@end table
! @item @code{z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- remove write watchpoint @strong{(draft)}
! @item @code{Z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- insert write watchpoint @strong{(draft)}
@cindex @code{z2} packet
@cindex @code{Z2} packet
!
Insert (@code{Z2}) or remove (@code{z2}) a write watchpoint.
Reply:
! @table @samp
@item OK
success
! @item
not supported
! @item E@var{NN}
for an error
@end table
! @item @code{z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- remove read watchpoint @strong{(draft)}
! @item @code{Z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- insert read watchpoint @strong{(draft)}
@cindex @code{z3} packet
@cindex @code{Z3} packet
!
Insert (@code{Z3}) or remove (@code{z3}) a read watchpoint.
Reply:
! @table @samp
@item OK
success
! @item
not supported
! @item E@var{NN}
for an error
@end table
! @item @code{z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- remove access watchpoint @strong{(draft)}
! @item @code{Z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- insert access watchpoint @strong{(draft)}
@cindex @code{z4} packet
@cindex @code{Z4} packet
!
Insert (@code{Z4}) or remove (@code{z4}) an access watchpoint.
Reply:
! @table @samp
@item OK
success
! @item
not supported
! @item E@var{NN}
for an error
@end table
--- 22587,22649 ----
movement.}
Reply:
! @table @code
@item OK
success
! @item @r{(empty)}
not supported
! @item E @var{NN}
for an error
@end table
! @item z2,@var{addr},@var{length}
! @item Z2,@var{addr},@var{length}
@cindex @code{z2} packet
@cindex @code{Z2} packet
! @strong{(draft)}
Insert (@code{Z2}) or remove (@code{z2}) a write watchpoint.
Reply:
! @table @code
@item OK
success
! @item @r{(empty)}
not supported
! @item E @var{NN}
for an error
@end table
! @item z3,@var{addr},@var{length}
! @item Z3,@var{addr},@var{length}
@cindex @code{z3} packet
@cindex @code{Z3} packet
! @strong{(draft)}
Insert (@code{Z3}) or remove (@code{z3}) a read watchpoint.
Reply:
! @table @code
@item OK
success
! @item @r{(empty)}
not supported
! @item E @var{NN}
for an error
@end table
! @item z4,@var{addr},@var{length}
! @item Z4,@var{addr},@var{length}
@cindex @code{z4} packet
@cindex @code{Z4} packet
! @strong{(draft)}
Insert (@code{Z4}) or remove (@code{z4}) an access watchpoint.
Reply:
! @table @code
@item OK
success
! @item @r{(empty)}
not supported
! @item E @var{NN}
for an error
@end table
*************** for an error
*** 22662,22675 ****
@section Stop Reply Packets
@cindex stop reply packets
! The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can
! receive any of the below as a reply. In the case of the @samp{C},
! @samp{c}, @samp{S} and @samp{s} packets, that reply is only returned
! when the target halts. In the below the exact meaning of @samp{signal
! number} is poorly defined. In general one of the UNIX signal numbering
! conventions is used.
! @table @samp
@item S@var{AA}
@var{AA} is the signal number
--- 22653,22666 ----
@section Stop Reply Packets
@cindex stop reply packets
! The @code{C}, @code{c}, @code{S}, @code{s} and @code{?} packets can
! receive any of the below as a reply. In the case of the @code{C},
! @code{c}, @code{S} and @code{s} packets, that reply is only returned
! when the target halts. In the below the exact meaning of ``signal
! number'' is poorly defined. In general one of the UNIX signal
! numbering conventions is used.
! @table @code
@item S@var{AA}
@var{AA} is the signal number
*************** conventions is used.
*** 22679,22687 ****
@var{AA} = two hex digit signal number; @var{n...} = register number
(hex), @var{r...} = target byte ordered register contents, size defined
! by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @samp{thread},
@var{r...} = thread process ID, this is a hex integer; @var{n...} =
! (@samp{watch} | @samp{rwatch} | @samp{awatch}, @var{r...} = data
address, this is a hex integer; @var{n...} = other string not starting
with valid hex digit. @value{GDBN} should ignore this @var{n...},
@var{r...} pair and go on to the next. This way we can extend the
--- 22670,22678 ----
@var{AA} = two hex digit signal number; @var{n...} = register number
(hex), @var{r...} = target byte ordered register contents, size defined
! by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @code{thread},
@var{r...} = thread process ID, this is a hex integer; @var{n...} =
! (@code{watch} | @code{rwatch} | @code{awatch}, @var{r...} = data
address, this is a hex integer; @var{n...} = other string not starting
with valid hex digit. @value{GDBN} should ignore this @var{n...},
@var{r...} pair and go on to the next. This way we can extend the
*************** The process terminated with signal @var{
*** 22700,22706 ****
@var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at
any time while the program is running and the debugger should continue
! to wait for @samp{W}, @samp{T}, etc.
@item F@var{call-id}@code{,}@var{parameter@dots{}}
--- 22691,22697 ----
@var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at
any time while the program is running and the debugger should continue
! to wait for @code{W}, @code{T}, etc.
@item F@var{call-id}@code{,}@var{parameter@dots{}}
*************** system call.
*** 22716,22723 ****
The target replies with this packet when it expects @value{GDBN} to call
a host system call on behalf of the target. @value{GDBN} replies with
an appropriate @code{F} packet and keeps up waiting for the next reply
! packet from the target. The latest @samp{C}, @samp{c}, @samp{S} or
! @samp{s} action is expected to be continued.
@xref{File-I/O remote protocol extension}, for more details.
@end table
--- 22707,22714 ----
The target replies with this packet when it expects @value{GDBN} to call
a host system call on behalf of the target. @value{GDBN} replies with
an appropriate @code{F} packet and keeps up waiting for the next reply
! packet from the target. The latest @code{C}, @code{c}, @code{S} or
! @code{s} action is expected to be continued.
@xref{File-I/O remote protocol extension}, for more details.
@end table
*************** The following set and query packets have
*** 22736,22742 ****
Return the current thread id.
Reply:
! @table @samp
@item @code{QC}@var{pid}
Where @var{pid} is an unsigned hexidecimal process id.
@item *
--- 22727,22733 ----
Return the current thread id.
Reply:
! @table @code
@item @code{QC}@var{pid}
Where @var{pid} is an unsigned hexidecimal process id.
@item *
*************** Any other reply implies the old pid.
*** 22747,22753 ****
@cindex CRC of memory block, remote request
@cindex @code{qCRC} packet
Reply:
! @table @samp
@item @code{E}@var{NN}
An error (such as memory fault)
@item @code{C}@var{CRC32}
--- 22738,22744 ----
@cindex CRC of memory block, remote request
@cindex @code{qCRC} packet
Reply:
! @table @code
@item @code{E}@var{NN}
An error (such as memory fault)
@item @code{C}@var{CRC32}
*************** sequence will be the @code{qs}@code{Thre
*** 22769,22775 ****
NOTE: replaces the @code{qL} query (see below).
Reply:
! @table @samp
@item @code{m}@var{id}
A single thread id
@item @code{m}@var{id},@var{id}@dots{}
--- 22760,22766 ----
NOTE: replaces the @code{qL} query (see below).
Reply:
! @table @code
@item @code{m}@var{id}
A single thread id
@item @code{m}@var{id},@var{id}@dots{}
*************** NOTE: this query is replaced by the @cod
*** 22834,22840 ****
(see above).
Reply:
! @table @samp
@item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@dots{}}
Where: @var{count} (two hex digits) is the number of threads being
returned; @var{done} (one hex digit) is zero to indicate more threads
--- 22825,22831 ----
(see above).
Reply:
! @table @code
@item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@dots{}}
Where: @var{count} (two hex digits) is the number of threads being
returned; @var{done} (one hex digit) is zero to indicate more threads
*************** response, @value{GDBN} ignores this and
*** 22853,22859 ****
offset to the @code{Bss} section.}
Reply:
! @table @samp
@item @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
@end table
--- 22844,22850 ----
offset to the @code{Bss} section.}
Reply:
! @table @code
@item @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
@end table
*************** Returns information on @var{threadid}.
*** 22864,22870 ****
encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
Reply:
! @table @samp
@item *
@end table
--- 22855,22861 ----
encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
Reply:
! @table @code
@item *
@end table
*************** The content and encoding of @var{annex}
*** 22880,22886 ****
it can supply additional details about what data to access.
Here are the specific requests of this form defined so far.
! All @samp{@code{qPart}:@var{object}:@code{read}:@dots{}}
requests use the same reply formats, listed below.
@table @asis
--- 22871,22877 ----
it can supply additional details about what data to access.
Here are the specific requests of this form defined so far.
! All @code{@code{qPart}:@var{object}:@code{read}:@dots{}}
requests use the same reply formats, listed below.
@table @asis
*************** number of intermediate @code{O}@var{outp
*** 22960,22974 ****
interpreter may have security implications}.
Reply:
! @table @samp
@item OK
A command response with no output.
@item @var{OUTPUT}
A command response with the hex encoded output string @var{OUTPUT}.
@item @code{E}@var{NN}
Indicate a badly formed request.
! @item @samp{}
! When @samp{q}@samp{Rcmd} is not recognized.
@end table
@item @code{qSymbol::} --- symbol lookup
--- 22951,22965 ----
interpreter may have security implications}.
Reply:
! @table @code
@item OK
A command response with no output.
@item @var{OUTPUT}
A command response with the hex encoded output string @var{OUTPUT}.
@item @code{E}@var{NN}
Indicate a badly formed request.
! @item @code{}
! When @code{q}@code{Rcmd} is not recognized.
@end table
@item @code{qSymbol::} --- symbol lookup
*************** Notify the target that @value{GDBN} is p
*** 22978,22984 ****
requests. Accept requests from the target for the values of symbols.
Reply:
! @table @samp
@item @code{OK}
The target does not need to look up any (more) symbols.
@item @code{qSymbol:}@var{sym_name}
--- 22969,22975 ----
requests. Accept requests from the target for the values of symbols.
Reply:
! @table @code
@item @code{OK}
The target does not need to look up any (more) symbols.
@item @code{qSymbol:}@var{sym_name}
*************** target has previously requested.
*** 22999,23005 ****
will be empty.
Reply:
! @table @samp
@item @code{OK}
The target does not need to look up any (more) symbols.
@item @code{qSymbol:}@var{sym_name}
--- 22990,22996 ----
will be empty.
Reply:
! @table @code
@item @code{OK}
The target does not need to look up any (more) symbols.
@item @code{qSymbol:}@var{sym_name}
*************** Where @var{id} is a thread-id in big-end
*** 23015,23026 ****
string description of a thread's attributes from the target OS. This
string may contain anything that the target OS thinks is interesting for
@value{GDBN} to tell the user about the thread. The string is displayed
! in @value{GDBN}'s @samp{info threads} display. Some examples of
possible thread extra info strings are ``Runnable'', or ``Blocked on
Mutex''.
Reply:
! @table @samp
@item @var{XX@dots{}}
Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising
the printable string containing the extra information about the thread's
--- 23006,23017 ----
string description of a thread's attributes from the target OS. This
string may contain anything that the target OS thinks is interesting for
@value{GDBN} to tell the user about the thread. The string is displayed
! in @value{GDBN}'s @code{info threads} display. Some examples of
possible thread extra info strings are ``Runnable'', or ``Blocked on
Mutex''.
Reply:
! @table @code
@item @var{XX@dots{}}
Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising
the printable string containing the extra information about the thread's
*************** attributes.
*** 23032,23038 ****
@node Register Packet Format
@section Register Packet Format
! The following @samp{g}/@samp{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
--- 23023,23029 ----
@node Register Packet Format
@section Register Packet Format
! 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