Current (non-) state of gdbserver

Current (non-) state of gdbserver

[Daniel Jacobowitz]

Based on the lack of response I got last time I inquired about gdbserver,
I'd say that no one has really picked it up since Stan stepped back.  It
hasn't built in a while; the multiarch support completely stops it from
working, on the targets I tried at least (ppc-linux and mips-linux).

Unless someone steps up with something already done (if you're out there,
we're waiting...), I'm going to start working on this.  I'm not sure how
multiarch will fit in to gdbserver in the future, but for now my intent is
to bloat it somewhat with the necessary support code.  It'll probably
involve splitting a lot of tdep files into two pieces.

I'd also like to start building gdbserver by default on platforms which
support it (and I have patches to extend the list a bit).  That way we can
at least notice this sort of thing...


-- 
Daniel Jacobowitz                           Carnegie Mellon University
MontaVista Software                         Debian GNU/Linux Developer

Re: Current (non-) state of gdbserver

[Andrew Cagney]

> Based on the lack of response I got last time I inquired about gdbserver,
> I'd say that no one has really picked it up since Stan stepped back.  It
> hasn't built in a while; the multiarch support completely stops it from
> working, on the targets I tried at least (ppc-linux and mips-linux).


That is a fair assesment.


> Unless someone steps up with something already done (if you're out there,
> we're waiting...), I'm going to start working on this.  I'm not sure how
> multiarch will fit in to gdbserver in the future, but for now my intent is
> to bloat it somewhat with the necessary support code.  It'll probably
> involve splitting a lot of tdep files into two pieces.


 From memory, gdbserver uses very little from tm-*.h and *-tdep.c.  The 
main thing is the description of the remote protocol G packet.  I think 
that protocol packet should be published (it is a GDB interface) in a 
way that lets both GDBSERVER and the *-tdep.c files use it.

I don't know that trying to split the tdep file will actually help that 
much.  I've tried building GDBSERVER using the bloat technique - gave up 
when I found something was trying to suck in top.c ....


> I'd also like to start building gdbserver by default on platforms which
> support it (and I have patches to extend the list a bit).  That way we can
> at least notice this sort of thing...


Check the threads:

disable gdbserver for cross builds

http://sources.redhat.com/ml/gdb-patches/2000-09/msg00170.html


[RFA]: Add gdbserver to configdirs for several targets
http://sources.redhat.com/ml/gdb-patches/2000-11/msg00393.html

	Andrew

Re: Current (non-) state of gdbserver

[Stan Shebs]

Daniel Jacobowitz wrote:
> 
> Based on the lack of response I got last time I inquired about gdbserver,
> I'd say that no one has really picked it up since Stan stepped back.  It
> hasn't built in a while; the multiarch support completely stops it from
> working, on the targets I tried at least (ppc-linux and mips-linux).
> 
> Unless someone steps up with something already done (if you're out there,
> we're waiting...), I'm going to start working on this.  I'm not sure how
> multiarch will fit in to gdbserver in the future, but for now my intent is
> to bloat it somewhat with the necessary support code.  It'll probably
> involve splitting a lot of tdep files into two pieces.

As Andrew observes, you'll probably get tangled up in dependencies,
but those are likely to be mistakes in GDB's architecture - there's
no good reason why lowest-level native and target support (which is
all that gdbserver needs) has to be making references to user-interface
code and the like.

Thought 1: split the arch vector into a general vector and a nano-vector
with only the register definitions and such.  If we really don't care
about the extra footprint from unused arch code (either because it's
small, or we know linker will discard), then instead you could have
an optional <arch>-ui.c to be a home for target-specific commands.

Thought 2: foo-nat.c will probably need to be split, again foo-ui.c
could be a home for higher-level and symbolic stuff.

Thought 3: AIX is especially ugly to handle, because you need to make
a ptrace call and pick apart OS-supplied structures even to find the
entry point.  Might even need a protocol addition to get it to work.

> I'd also like to start building gdbserver by default on platforms which
> support it (and I have patches to extend the list a bit).  That way we can
> at least notice this sort of thing...

An excellent idea.  One thing I wanted to do as part of this was to
move gdbserver out of its subdirectory, since by the time you're
done integrating with the rest of GDB sources, you should only have
one file unique to gdbserver (main()), and the semi-duplicated
Makefile.in make trouble.

Stan

Re: Current (non-) state of gdbserver

[J.T. Conklin]

>>>>> "Daniel" == Daniel Jacobowitz <dmj+@andrew.cmu.edu> writes:
Daniel> Unless someone steps up with something already done (if you're
Daniel> out there, we're waiting...), I'm going to start working on
Daniel> this.

As far as I know, you're the first with both the time and inclination
to address this.  

Daniel> I'd also like to start building gdbserver by default on
Daniel> platforms which support it (and I have patches to extend the
Daniel> list a bit).  That way we can at least notice this sort of
Daniel> thing...

Ideally, you'd want to build a cross gdbserver when you build a cross
debugger, but that involves all sorts of mess figuring out what tools
to use to build gdbserver.  That could be pretty tricky to figure out.
In the mean time, just building gdbserver for native configs would
catch a lot of the bitrot that's occured from time to time over the
years.

But until you/we come up with a multi-arch strategy, we may run into
conflicts when an existing/working gdbserver port breaks when gdb is
multi-arched (for a new architecture).  Up till now, we've accepted
(for the most part implicitly, since usually we didn't realize that
gdbserver had broken until much later) that breakage as the price of
progress.

        --jtc

-- 
J.T. Conklin
RedBack Networks

Re: Current (non-) state of gdbserver

[J.T. Conklin]

Daniel> Unless someone steps up with something already done (if you're
Daniel> out there, we're waiting...), I'm going to start working on
Daniel> this.  I'm not sure how multiarch will fit in to gdbserver in
Daniel> the future, but for now my intent is to bloat it somewhat with
Daniel> the necessary support code.  It'll probably involve splitting
Daniel> a lot of tdep files into two pieces.

Stan> As Andrew observes, you'll probably get tangled up in
Stan> dependencies, but those are likely to be mistakes in GDB's
Stan> architecture - there's no good reason why lowest-level native
Stan> and target support (which is all that gdbserver needs) has to be
Stan> making references to user-interface code and the like.

Stan> Thought 1: split the arch vector into a general vector and a
Stan> nano-vector with only the register definitions and such.  If we
Stan> really don't care about the extra footprint from unused arch
Stan> code (either because it's small, or we know linker will
Stan> discard), then instead you could have an optional <arch>-ui.c to
Stan> be a home for target-specific commands.

There are a small set of a primitives that GDB and gdbserver use to
control the target.  In GDB, they're scattered amongst *-tdep.c files,
inf*.c, etc.; while in gdbserver they are centralized in each low-*.c
file.  If we split a nano-vector out of the target vector, I think it
should contain only these functions.

Of the top of my head we have:

        * fetch/store memory
        * fetch/store registers
        * stop
        * kill 
        * resume
        * insert/remove break/watchpoint

While you're correct that most of the functions in *-tdep.c files
probably wouldn't bloat gdbserver too much if linked in, I prefer that
the split out files only contain the functions that implement the
nano-vector.  This delination clearly defines which functions go in
which file.

>> I'd also like to start building gdbserver by default on platforms which
>> support it (and I have patches to extend the list a bit).  That way we can
>> at least notice this sort of thing...

Stan> An excellent idea.  One thing I wanted to do as part of this was to
Stan> move gdbserver out of its subdirectory, since by the time you're
Stan> done integrating with the rest of GDB sources, you should only have
Stan> one file unique to gdbserver (main()), and the semi-duplicated
Stan> Makefile.in make trouble.

While we're talking of splitting things, I'd like to split things so
that gdbserver and the sample debug stubs shared as much as possible;
as well as making sure there are clean lines between the packet i/o,
command/response, and "nanovector" functions.  One complication is
that stubs have traditionally been public domain.

This would also make it trivial to prototype new high-level protocols
or data transports.

        --jtc

-- 
J.T. Conklin
RedBack Networks

Re: Current (non-) state of gdbserver

[Andrew Cagney]

> 
> As Andrew observes, you'll probably get tangled up in dependencies,
> but those are likely to be mistakes in GDB's architecture - there's
> no good reason why lowest-level native and target support (which is
> all that gdbserver needs) has to be making references to user-interface
> code and the like.


Just FYI, it isn't just multi-arch.  ui-out/ui-file/.... are also having 
an impact effect.  In their case a little re-aranging would certainly 
help (create cleanups.[hc]?, file-utils.[hc]?, ...).


> Thought 1: split the arch vector into a general vector and a nano-vector
> with only the register definitions and such.  If we really don't care
> about the extra footprint from unused arch code (either because it's
> small, or we know linker will discard), then instead you could have
> an optional <arch>-ui.c to be a home for target-specific commands.


Here, I think trying to split things up would be roughly equivalent to 
re-aranging those brand new deck chairs(1) :-)  This is because 
everything depends on the single macro REGISTER_RAW_SIZE().  As I noted 
in another e-mail, I think there needs to be something that specifies 
the protocol register numbering [rawnum] and the G packet layout that is 
completly independant of multi-arch and, for the G packet, GDB.

On a normal GDB, the conversion sequence:

   nat-register layout
     |
     |(*-nat.c)
     |
   raw register layout
     |
     |(*frame*)
     |
   cooked register layout

occures.  (nat layout is what is on the HOST OS IF, raw layout is what 
is used by GDB's register cache and target vector, cooked layout is what 
is used by read_register_frame(frame, ...) et.al.)

If you introduce the remote protocol into the picture then the sequence 
is changed to either:

   nat-register layout
     |
     |(gdbserv/*nat*)
     |
   G packet layout
     |
     |(remote.c)
     |
   raw reg layout
     |
     |(*frame*)
     |
   cooked reg layout

or

   nat-register layout
     |
     |(*-nat.c)
     |
   raw register layout
     |
     |(gdbserver)
     |
   G packet layout
     |
     |(remote.c)
     |
   raw register layout
     |
     |(frame*.c)
     |
   cooked register layout

depending on how ``pure'' you want things :-)

Anyway, within the above, I think the `G packet' and possibly the `raw 
register layout' need to be defined out side of *-tdep.c.  If this is 
done then the rest of the problem becomes managable.

See also:
http://sources.redhat.com/cgi-bin/gnatsweb.pl?cmd=view&pr=122&database=gdb

Anyway, to throw a spanner in the works, (given some comments from Eli) 
IRIX could easily end up with a *-nat.c that supports two different 
architectures.  Solaris is similar.  I suspect the i386-64 chip could be 
the same.

	enjoy,
		Andrew

--

(1) Rearanging deck chairs on the titanic.

Re: Current (non-) state of gdbserver

[Andrew Cagney]

> Of the top of my head we have:
> 
>         * fetch/store memory
>         * fetch/store registers
>         * stop
>         * kill 
>         * resume
>         * insert/remove break/watchpoint
> 


With care, this has the potential for being a decent, stackable, event 
driven, target vector.

	Andrew

Re: Current (non-) state of gdbserver

[Quality Quorum]

> 
>         * fetch/store memory
>         * fetch/store registers
>         * stop
>         * kill 
>         * resume
>         * insert/remove break/watchpoint
>

It will be nice to add thread support rightaway.

 
> J.T. Conklin

Thanks,

Aleksey

Re: Current (non-) state of gdbserver

[J.T. Conklin]

>>>>> "Quality" == Quality Quorum <qqi@world.std.com> writes:
>> * fetch/store memory
>> * fetch/store registers
>> * stop
>> * kill 
>> * resume
>> * insert/remove break/watchpoint

Quality> It will be nice to add thread support rightaway.

Indeed.  All of these primitives need to be context/process/thread aware.

        --jtc

-- 
J.T. Conklin
RedBack Networks

Re: Current (non-) state of gdbserver

[Andrew Cagney]

> 
> Quality> It will be nice to add thread support rightaway.
> 
> Indeed.  All of these primitives need to be context/process/thread aware.


Starting at the frame we have:

	a frame has a thread
	a thread has a target

so a target could potentially manage one or more threads.
Makeing sense?  Sounding good in theory?

	Andrew

Re: Current (non-) state of gdbserver

[Andrew Cagney]

Since people are posting wishlists on GDBserver, I'll post mine.  It 
contains one item:

	o	get it to talk to its self

That is, a GDBserver talking to a GDBserver talking to a GDBserver.  The 
foundation for each layer being a target object/stack-entry/...

As John Kallal has rightly pointed out, this is hard, really hard.  It 
means GDBserver gets an event-loop.  It means GDBserver has to do 
non-blocking reads and writes, it means ....

However, it also offers a glimmer of hope on one of GDB's problems - its 
  very blocking centric behavour.  GDBserver could be small enough, yet 
applicable enough, to allow the development of a proper target stack.

Using sufficient glue, gaffer tape and spac-filler, (and a re-entrant 
event-loop) it could even be bolted onto GDB's current target interface. 
Maybe.

----

With regard to modifying the remote protocol, to be honest, for all its 
warts, beginning to think it isn't that bad.  If you think about it, 
consider a memory read:

	-> $M<addr>#CC
	<- +$<hex-data>#CC
	-> +

then, apart from assuming a reliable channel (and remove the ``+'') 
there isn't much more you can extract out of this.  Bigger gains can be 
made by making better use of that channel (combining reads/writes, ...) 
all of which are changes to GDB.

This isn't to say that a replacement protocol wouldn't be more welcome 
though.

	Andrew

Re: Current (non-) state of gdbserver

[Quality Quorum]

On Thu, 12 Jul 2001, Andrew Cagney wrote:

> > 
> > Quality> It will be nice to add thread support rightaway.
> > 
> > Indeed.  All of these primitives need to be context/process/thread aware.
> 
> 
> Starting at the frame we have:
> 
> 	a frame has a thread
> 	a thread has a target
> 
> so a target could potentially manage one or more threads.
> Makeing sense?  Sounding good in theory?

My thoughts (and experience) are summarized in the document below

> 
> 	Andrew
> 

Thanks,

Aleksey

=====================================================================

.

A. Romanov

The GDB Remote Serial Protocol Specification
(rev 1.3)

0. Changes to Previous Version
 o Changes to versin 1.2

   GDB internals does not allow for per thread break points on the
   stub side, spec reflects this sad truth.

   Cleaned up z-packet descriptions

   Added description of 'zz' packet.

   Restored acidently deleted 'writeSingleRegister'.

   Clarified length valuess in many instances.

 o Changes to version 1.1

   Removed run-length encoding: queries can contain '*', so there
   is not way of reliable detection

   'Z' protocol clarified: minimum amount of supported break points
   and error codes

 o Changes to version 1.0

   Depreciated 'isThreadAlive'

   Fixed wrong descritpion of 'addBWPoint' and 'removeBWPoint'

 o Changes to version 0.4

   Added 'waitForEvent', improved description of 'setControlThread' and
   'setGeneralThread'

 o Changes to version 0.3

   Expanded description of stub operating environment

   Fixed thread description

   Fixed signal range

   Split thread support into thread information and thread control

   Resurrected address part of continue and step signals, due to popular
   demand

   Added description of 'Z' and 'z' requests

   Added section on gdb side (self-) configuration.

 o Changes to version 0.2

   Added section on backward compatibility.

 o Changes to version 0.1

   Low case hex encoding is mandatory for byte arrays.

   Added section on signals.

   Added comment about retrying requests returned unexpected reply.

   Added 'restart', 'remoteCmd', 'rawQuery', 'userQuery'

   Dropped 'FromAddr' from all continue and step requests - it is
   not used by gdb anyway.

   Restructured description of optional elements.


1. Introduction

This is a first attempt to formally specify the GDB Remote Serial Protocol
(the protocol). This protocol is used by various gdb implementations to
communicate with target resident software called stub over serial line
or TCP stream. There is a well established way in making oneself familiar
with the protocol by reading/porting/developing source code implementing
both sides of the connection. However, it seems apparent that absence of
formal specification negatively affects development and interoperability
along with support for advanced features on the stub side.

2. Remote GDB Stub Execution Environment

Let us start from describing environment where remote stub is executed.
Threads comprising the system under debugging (the system) can have
common data and text sections (e.g. embedded environments or
user space threads), can share data segments only (e.g. Linux threads)
and  can have both data and text separate (e.g. Unix like processes).

It seems that the only thread model which could be supported by gdb-4.18
is one with common data and text sections. In this case a stub is
executed in exception handling context with all threads in the system
stopped until stub receives a command from gdb to continue. Stubs
optionally supports thread information functions allowing to retrieve
inforamtion about threads: list, thread name and information strings,
thread registers. It is highly desirable for this environment to support
optional step operation. Break points are always not thread specific
due to internal gdb limitations.

When processor exception happens, stub enters 'exception entry state' where
register operations are performed on registers associtated with stopped
thread.

3. Data Types And Formats

3.1. Byte Arrays

3.1.1. Byte Array (ba)

Byte array is used to transfer memory and register data and to
send printable message to gdb console. It is encoded as a sequence
of hex digits represented by ASCII characters [0-9a-f]. Each byte
is represented by two characters with most significant nibble coming
fist. In all cases order of bytes in the array are ordered in the
byte order of the target. In all cases this stream is delimited by
protocol elements represented by non-hex-digit characters. Character
sequences of odd length or shorter than 2 are considered invalid.
We will use 'ba' to designate protocol data in this format.

This format is mandatory for both gdb and stub sides.

Note: this specification required low case encoding. It is generally
established practice so there are no compatibility problems here.


3.1.2. Partially Available Byte Arrays (bp)

It is conceivable that in some system stub will not be able to
access all registers requested by gdb. In this case unavailable
bytes of byte array are encoded as 'xx'. This is the only difference
between Byte Array and Partially available byte array. We will
use 'bp' to  designate protocol data in this format. Gdb never
sends data in this format. Stub uses this format for register
data only, unaccessible memory or other data should be reported as
error condition or unsupported feature.

This format is mandatory for gdb side.

Note: this format is not supported by gdb-4.17 and earlier.

3.1.3. Binary Data Array (bx)

The name tells all, this byte array is binary encoded with characters
'$', '#' and 0x7d escaped by inserting 0x7d before them. Note: byte
arrays require 8-bit clean communication channel. Stub never uses
this format. Gdb uses it to speed up big downloads. We designate
this format 'bx'.

This format is optional for both gdb and stub sides. Gdb has a reliable
way to detect whether this format is supported by stub.

3.1.4. String (ls)

Stream of ASCII characters, the length is provided as a part of
the message. We designate this format as (ls). It is mandatory
on the gdb side, it is mandatory on stub size if Thread Info
Query is implemented.


3.2. Integers

GDB uses unsigned integers to convey information about address,
length, register numbers, signals and other parameters.

3.2.1. Fixed Width Integers (0wx)

These integers are encoded by sprintf(out_buf, "%0wx", value)
or its equivalent (w is width). For example, signals are usually
encoded as sprintf(out_buf, "%02x", value). GDB never uses this format
to encode more than 32-bit unsigned integer and it never uses width
greater than 8.  This format is designated as '0wx', e.g. '08x'.

This format is required on the gdb side, it is required on the stub
side only if stub supports requests utilizing this format.

3.2.2. Normal Integers  (x)

These integers are encoded by sprintf(out_buf, "%Lx", value) or its
equivalent. It acceptable to pad the output with zeros on the left.
This format is used primarily to pass address, length and register
number information. We designate this format as (x).

This format is mandatory for both gdb and stub sides.

Gdb will under no conditions will send anything more than 32-bit
unsigned integer to the 32-bit stub.

64-bit stubs are interoperable with pre-5.0 implementations as long
as they do not address memory beyond  4GB. 64-bit stubs with higher
requirements should be debugged by gdb-5.0 or newer.

32-bit stubs are interoperable both with old and new implementations.

3.3. Threads

Gdb allows stub to select its own way of identifying threads. It allocates
64-bit unsigned integers for thread representation. There is an internal
restriction in current gdb implementations to use thread id below
0x80000000.

Thread_id 0 should not be used, gdb reserves it to set special case of
generic thread.

Gdb also reserves threads 0xffffffff and 0xffffffffffffffff for its
internal use. These values should never be seen on the wire.

3.3.1 Variable Length Tread_Id (vt)

Thread id 0 is encoded as '0' in this format, all other
threads are encoded by sprintf(out_buf, "%Lx", thread_id) or
its equivalent. It is acceptable to pad values with zeros on
the left, however, it is strongly discouraged. We designate this
format 'vt'.

This format is required on gdb side and it is required on the stub
side if it supports threads.

3.3.2. Fixed Length Thread_Id (ft)

Thread id 0 is never used in this format, all other threads are encoded
as sprintf(out_buf, "%016Lx", thread_id) or its equivalent.

The format is required on gdb side and it is required on the stub
side it supports threads and thread query operations.

3.4. Signals

Signals are unsigned integers with 1-255 range. They are always
encoded by sprintf(out_buf, "%02x", signal) or its equivalent.
Gdb follows standard Unix signal definitions and interpretation,
normally both gdb and stub sides are aware about peer signal
interpretation. We will not use format designation when describing signals.

3.5. Packet Formats

Packet format is '$data#csum', where data is a sequence of ASCII
characters, a csum is  single byte checksum encoded as two
hex digits. Receiver acknowledges properly received packet with
'+' and corrupted packet with '-'.  This packet format is mandatory
for both gdb and stub side.

Packet '$Xdata#csum' may contain non-ASCII data. This packet format is
optional.

Packet '$ss:data#csum' adds two byte sequence 'ss' to the picture,
receiver acknowledges properly received packet with '+ss' and
corrupted packet with '-'. This format is implemented by receivers
but is not used by senders.

Packet length is limited to 400 bytes, there are attempts to
allow 400 bytes of data, there are number of bugs there, so
the safe bet is to accept 407 bytes and never send more than
400 bytes for the whole packet. The only exception are cases
where stub needs more than 400 bytes to to pack all its registers.
Gdb has a reliable method to detect this case.

Stubs supporting threads should be able to support packets of
1000 bytes.

4. Protocol Operations

Protocol operations are asymmetric gdb side issues requests and
stub side responds. There is only one unsolicited message defined
so far, which could be sent by stub side. All elements are packed
into ASCII encoded packet, unless noted otherwise.

We will use '<v-f>' notation to designate value 'v' in format 'f'.
For example '<address-x>' means address encoded in format 'x',
described in  section 3.2.2. Angle brackets are used as delimiters and
are not part of the packet. For example, if we have format
described as 'm<address-x>,<length-x>' then for address 0x1234 and length
0x20, the packet will look like '$m1234,20#c5'. Optional parts will be
placed in square brackets, e.g. 'C<signal-02x>[;<address-x>]'.
We will use '...' to designate optional more of the same.

It seems reasonable for gdb side to retry operations which yielded
unexpected response: simple checksum used in the protocol
is not strong enough, however, combined with 3 retries it
will be quite reliable to eliminate any spurious errors introduced
by line noise.

4.1. Mandatory Elements

There is a small but extremely powerful set of mandatory features.

4.1.1. Standard Responses

  o 'noSupport': tells gdb that last request is not supported.

     Format: Empty packet

  o 'error': tells gdb that last request caused some error.

     Format: EXX

             'XX' could be anything and of any length:
             usually XX is two hex-characters or two 'N' characters.

             Gdb side considers any packet starting from 'E' an error
             indication.

  o 'ok': tells gdb that last request was successful

     Format: OK

  o 'statusString': there are four status string formats defined. Two of them
    are mandatory and two are optional in the sense that at least one of them
    of them should be implemented.

    Format: W<exit_status-02x>   system under debugging exited with status
                                 'exit_status'

    Format: X<signal>            system under debugging was terminated by
                                 signal 'signal'

    Format: S<signal>            system under debugging was stopped
                                 by signal where signal is the value of
                                 signal

            or

            T<signal><reg_no-02x>:<reg_val-ba>;...[thread:<thread_id-vt>;]

            if thread is present, it means that thread identified
            by 'thread_id' was stopped by signal 'signal'. If thread
            is not present, it means that some thread was stopped by
            signal 'signal'. In all cases <reg_no-02x>:<reg_val-ba>;
            provide value 'reg_val' of a relevant register 'reg_no'.

     Note:  'thread' should not be present if threads are not
            supported by stub.

   o 'displayOutput': unsolicited message from the running system requesting
                      to display the string on the gdb console.

     Format: O<string-ba>

             This one is mandatory only on gdb side.

4.1.2 Mandatory Requests

Note: receiving something beyond reply listed below is considered
fatal by gdb. For gdb side step support is a configuration time
parameter. So, gdb assumes that target should support steps, then
'step' is mandatory.

  o 'getLastStatus': retrieve current status from the system

     Format: ?

     Reply:  'statusString'


  o  'readAllRegisters': retrieve data from all available registers

     Format: g

     Reply:  <register_data-bx>

     Note:   Register data are packed in the byte order of target.

             This is the only known use of format 'bx'.


   o 'writeAllRegisters': set registers

     Format: G<register_data-ba>

     Reply:  OK

      Note:  It is fine to have register_data, shorter than
             full register block.

  o 'readMemory': read memory

     Format: m<address-x>,<length-x>

     Reply:  <memory_data-ba>  or  'error'

     Note:   Memory data are packed in the byte order of the target.

             Gdb considers any error to be a memory access ones.

             Note: stub can return a smaller chunk of memory than was
             requested, it is a responsibility of the stub to ensure
             that response will fit into 400 bytes.

             Length could not be 0 and it could not be greater than
             0x7fffffff, so stub implementors can safely use integer to
             hold it.

  o 'writeMemory': write memory

    Format: M<address-x>,<length-x>:<memory_data-ba>

    Reply:  'ok' or 'error'

             Memory data are packed in the byte order of the target.

             Gdb considers any error to be a memory access ones.

  o 'continue': continue from current address

    Format: c

    Reply:  'statusString'

    Note:   No reply until system will be stopped again by
            breakpoint, signal or interrupt from the debugger (if
            supported). Between request and response running system
            may issue unlimited number of 'displayString' messages.

  o 'step': step from current address

    Format: s

    Reply:  'statusString'

    Note:   no reply until system will be stopped again by
            breakpoint, signal or interrupt from the debugger (if
            supported). Between request and response running system
            may issue unlimited number of 'displayString' messages.

   o 'kill' : kill request. in many cases it is no-op for embedded systems,
              it has to be supported because gdb does not expect any response
              in the case, hence it requires special attention.

     Format: k

     Reply:

     Note:   No response indeed. If z-breaks are supported, stub have to
             remove all existing breakpoints


And these are all mandatory requests, isn't it amazing ?

4.2. Optional Elements

'noSupport' or response listed below are fine, anything else
is a fatal error.

4.2.1. Extended Operations Requests

These requests should be either both supported or both unsupported.

  o 'setExtendedOps':

    Format: !

    Reply:  'ok' or 'statusString'

    Note:   accepting extended operation is a promise to honor
            'restart' request.

  o 'restart': restart the system under debugging

    Format: r00

    Reply:  'statusString'

4.2.2. Thread Information Requests

These requests should be either all supported or all unsupported. It assumed
that gdb issuing such request knows what it is doing and is able to accept
long messages associated with 'threadInfoQuery' and 'threadListQuery'.

   o 'currentThreadQuery': get thread which is stopped

      Format: qC

      Reply:  QC<thread_id-vt>

      Notes:  Gdb uses this request in order to figure out
              whether thread information is supported or not

   o  'threadInfoQuery': get information about specified thread

      Format: qP<mask-08x><thread_id-ft>

      Reply:  qQ<mask-08x><thread_id-ft>[<tag-08x><length-02x><value>...]

              or 'error'

              Note: mask is or-ed combination of following the tags,
                    each tag has its own meaning and value.

                    tag   value            meaning

                    0x1     <thread_id-ft>    id of the thread
                    0x2     <exits-1x>        exists is 1 if thread exists
                    0x4     <display-ls>      human readable info to display
                    0x8     <name-ls>         name of the thread
                    0x10    <more_display-ls> more information to display

   o 'threadListQuery': suck a list of threads, starting from the
                        first one if first is not 0, of from the thread
                        after the arg_thread.

     Format: qL<first-01x><max_count-02x><arg_thread_id-ft>

     Reply:  qM<count-02x><done-01x><arg_thread_id-ft>[<found_thread_id-ft>...]

             or 'error'

   o 'setGeneralTrhead': registers and breakpoints will be related to this
                         thread.

     Format: Hg<thread_id-vt>

     Reply:  'ok'

     Note:   It is a responsibility of a gdb side to ensure that thread
             being set does exist.

             This operation is not sticky: it will not survive over
             'continue', 'step', 'waitForEvent' etc operations.

             "Hg0" is a switch to 'exception entry state': register operations
             are performed on registers of the stopped thread.

4.2.3. Other Optional Requests

  o 'writeSingleRegister': set single register

     Format: P<register-x>=<value-ba>

     Reply:  OK

  o 'continueFromAddr': continue from specified address

    Format: c<address-x>

    Reply:  'statusString'

    Note:   no reply until system will be stopped again by
            breakpoint, signal or interrupt from the debugger (if
            supported). Between request and response running system
            may issue unlimited number of 'displayString' messages.

  o 'continueWithSignal': continue with signal delivered, if address
                          is not specified it will continue from
                          current address

    Format: Csig[;<address-x>]

    Reply:  'statusString'

    Note:   no reply until system will be stopped again by
            breakpoint, signal or interrupt from the debugger (if
            supported). Between request and response running system
            may issue unlimited number of 'displayString' messages.

  o 'stepFromAddr': step from address

    Format: s<address-x>

    Reply:  'statusString'

    Note:   no reply until system will be stopped again by
            breakpoint, signal or interrupt from the debugger (if
            supported). Between request and response running system
            may issue unlimited number of 'displayString' messages.

  o 'stepWithSignal': step with signal delivered, if address
                      not specified it will start from current address.

    Format: Ssig[;<address-x>]

    Reply:  'statusString'

    Note:   no reply until system will be stopped again by
            breakpoint, signal or interrupt from the debugger (if
            supported). Between request and response running system
            may issue unlimited number of 'displayString' messages.


   o 'offsetsQuery': get offsets of program segments

     Format: qOffsets

     Reply:  Text=<address-x>;Data=<address-x>;Bss=<address-x>


   o 'crcQuery': get CRC32 of specified memory area

     Format: qCRC:<address-x>,<length-x>

     Reply:  'error' or C<crc32-x>

     Note:   Gdb considers any error to be memory access one.
             Length could be really big here.

   o 'writeSingleRegister': write single register

     Format: P<reg_no-x>=<reg_val-ba>

     Reply:  'ok'


  o 'writeMemoryBin': use binary format to write memory

    Format: X<address-x>,<length-x>:<data-bb>

    Reply:  'ok' or 'error'

    Note:    Memory data are packed in the byte order of the target.
             Gdb considers any error to be a memory access ones.

             Length could not be 0 and it could not be greater than
             0x7fffffff, so stub implementors can safely use integer to
             hold it.

   o 'remoteCommand': send command to the stub and print out out
                      on the console

      Format: qRcmd,<command-ba>

      Reply:  sequence of zero or more 'displayString' packets,
              zero or more <data-ba> packets terminated by 'ok'
              or 'error'

   o 'addBWPoint': add break/watch-point

      Format: Z<type-1x>,<address-x>,<length-x>

              type: 0  - add software breakpoint, at address,
                         length is the number of bytes to be
                         replaced.

              type: 1  - add hardware break point at address,
                         length is the length of breakpoint.

              type: 2  - add read watchpoint for address, length
                         combination.

              type: 3  - add write watchpoint for address, length
                         combination.

              type: 4  - add  access watchpoint for address, length
                         combination.

       Reply: 'ok' or 'error' if out of resources

       Note: 'noSupport' means that particular type is not supported,
             for example target can support software break points and
             not support hardware break points.

             Amount of possible hardware break/watch points is usually
             detemined by the target type and is known by the gdb.

             Gdb can theoretically set unlimited number of
             software break points.  Any `non-special-case' stub
             has to have capacity to set 1024 software break points.
             It is expected that gdb side is always informed
             about `special-case' limitations either through
             target configuration or through user input.

             Length should match stub expectations. For example,
             i386-stub expects type 0 length to be 1.


   o 'removeBWPoint': remove break point

      Format: z<type-1x>,<address-x>,<length-x>

              type: 0  - remove software breakpoint, at address,
                         length is the number of bytes to be
                         replaced.

              type: 1  - remove hardware break point at address,
                         length is the length of breakpoint.

              type: 2  - remove read watchpoint for address, length
                         combination.

              type: 3  - remove write watchpoint for address, length
                         combination.

              type: 4  - remove access watchpoint for address, length
                         combination.

       Reply: 'ok' or 'error' if there is no such break.

   o 'removeAllBWPoints': remove all break points

      Format: zz

      Reply:  'ok'

      Note:   removes all currently inserted break point. It is supposed to be
              issued at the very beginning of the new session.

4.2.4. Proposed Optional Elements

    o 'rawQuery': a mechanism to extend current protocols

       Format:    qz<id-2x>[<request_data-ba>]

       Reply:     QZ<id-2x>[<response_data-ba>] or 'ok' or 'error'

       Note:      ids are assigned by new versions of GDB protocol specs

    o 'userQuery': a mechanism to provide user specific extensions

       Format:     qu<id-2x>[<request_data-ba>]

       Reply:      QU<id-2x>[<request_data-ba>] or 'ok' or 'error'

       Note:       It is similar to qRcmd, however, it is expected that
                   Rcmd will interpreted mostly by user, and this
                   response will be interpreted by interpreted by
                   local gdb extensions


4.2.5. Depreciated Elements

   o  'isTheadAlive': check whether thread in question still exist

       Format: T<thread_id-vt>

       Reply:  'ok', 'error'

       Note:   'ok' means alive, 'error' means not alive.

               This command is depreciated recently, however, a lot
               of gdbs will still emit it.


Who cares ? Just make sure that gdb will never send a depreciated
request.

<List will be added here>

4.2.5. Obsolete Elements

Who cares ?

<List will be added here>

5. Backward Compatibility Issues

5.1. Old Gdb and New Stub

This is a less important issue, it seems reasonably simple for anybody
to update gdb. Moreover, it seems like there are not going to be any
interoperability problems between new stubs and pre-4.19 gdbs.

Note: all pre-4.18 gdbs are not able to process partially available
byte arrays (bp).


5.2. New Gdb and Old Stub

<TBD>

Re: Current (non-) state of gdbserver

[Eli Zaretskii]

On Fri, 13 Jul 2001, Quality Quorum wrote:

> My thoughts (and experience) are summarized in the document below
> 
> A. Romanov
> 
> The GDB Remote Serial Protocol Specification
> (rev 1.3)

If this is an accurate description of the current state of affairs,
perhaps we should add this to gdbint.texinfo.  Comments?

Re: Current (non-) state of gdbserver

[Fabrice Gautier]

On Sun, 15 Jul 2001 10:32:11 +0300 (IDT)
Eli Zaretskii <eliz@is.elta.co.il> wrote:
> 
> On Fri, 13 Jul 2001, Quality Quorum wrote:
> > 
> > The GDB Remote Serial Protocol Specification
> > (rev 1.3)
> 
> If this is an accurate description of the current state of affairs,
> perhaps we should add this to gdbint.texinfo.  Comments?

My previous source for this was the Cygnus/Redhat GNUPro manuals:

http://www.cygnus.com/pubs/gnupro/3_dbug/b_Debugging_with_GDB/gdbThe_GDB_remote_serial_protocol.html


-- 
Fabrice Gautier <gautier@email.enstfr>

Re: Current (non-) state of gdbserver

[Eli Zaretskii]

On Sun, 15 Jul 2001, Fabrice Gautier wrote:

> My previous source for this was the Cygnus/Redhat GNUPro manuals:
> 
> http://www.cygnus.com/pubs/gnupro/3_dbug/b_Debugging_with_GDB/gdbThe_GDB_remote_serial_protocol.html

Since that's a Cygnus material, I expect some difficulty in getting it 
into gdbint.texinfo, due to copyright issues.

Re: Current (non-) state of gdbserver

[Fabrice Gautier]

On Sun, 15 Jul 2001 13:15:54 +0300 (IDT)
Eli Zaretskii <eliz@is.elta.co.il> wrote:

> 
> On Sun, 15 Jul 2001, Fabrice Gautier wrote:
> 
> > My previous source for this was the Cygnus/Redhat GNUPro manuals:
> > 
> > http://www.cygnus.com/pubs/gnupro/3_dbug/b_Debugging_with_GDB/gdbThe_GDB_remote_serial_protocol.html
> 
> Since that's a Cygnus material, I expect some difficulty in getting it 
> into gdbint.texinfo, due to copyright issues.

Come on, http://www.cygnus.com/pubs/gnupro/3_dbug/b_Debugging_with_GDB/gdb.html
makes it pretty clear that this documentation is under some kind of free
license. Just add the copyright notice where it should be, but i don't
think anybody at Redhat will object including this page.

Including this paper http://www.redhat.com/devnet/articles/embedrem.htm
on the same subject will be a different story ...


-- 
Fabrice Gautier <gautier@email.enstfr>

Re: Current (non-) state of gdbserver

[Quality Quorum]

On Sun, 15 Jul 2001, Eli Zaretskii wrote:

> 
> On Fri, 13 Jul 2001, Quality Quorum wrote:
> 
> > My thoughts (and experience) are summarized in the document below
> > 
> > A. Romanov
> > 
> > The GDB Remote Serial Protocol Specification
> > (rev 1.3)
> 
> If this is an accurate description of the current state of affairs,
> perhaps we should add this to gdbint.texinfo.  Comments?
> 

I would like to have it discussed first - it has quite a few 
clarifications and bug fixes. Also, I have a reference implementation
of both sides with a few improvements.

Thanks,

Aleksey