This is the mail archive of the gdb@sourceware.cygnus.com mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

protoc spec




Hi, 


I have updated GDB remote  protocol specs with a few things which are 
making it possible to do real develpment on its base. Latest spec 
is attached to this mail, also I put it on the net:

http://www.std.com/qqi/ftp/protocol.txt
ftp://www.std.com/Newbury/qqi/protocol.txt

Few highlights:

1. It seems possible to fix all issues I was concerned about
   in such a way that properly developed application will 
   be backward comaptible without any additonal efforts.

   And all quirks could be covered by just three configuration 
   variables on the gdb side.

2. Proposed mechanism for future extensions seems 
   more promising than raw query as it exists now.

I am very eager to submit appropriate remote.c and I already 
signed copyright transfer papers.

I am looking of for an advise how to synchronize my 
environment with remote cvs considering the fact that 
I have pretty recent snapshot on CD and slow link to 
internet.

Also, after 7 years of heavy involvment with network protocol 
development I am kind of attached to internet-drafts and RFCs.
Does it seem as a good idea to publish final spec as RFC ?
It seems to me that applicaton management area of IETF
would provide a very good review at least. At the same time 
it introduces noticeable delays into process. So, I am not
quite sure.


Thanks,

Aleksey

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

A. Romanov

The GDB Remote Serial Protocol Specification
(rev 0.3)

0. Changes to Previous Version
 
 o Changes to version 0.2

   Added section on backward comaptibility.

   Added 'interrupt'.

 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.
It is generally assumed that stub is executed in exception handling 
context with all other processes in the system under debugging
(the system) frozen until stub receives command from gdb to continue.
Even if the stub supports per thread breakpoints, all threads of 
execution in the system are frozen when breakpoint/exception
is taken by any one of them

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, "%x", 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 under no conditions will send anything more than 32-bit
unsigned integer to the 32-bit stub. 

64-bit stubs are interoperable with pre-4.19 implementations as long 
as they do not address memory beyond  4GB. 64-bit stubs with higher
requirements should be debugged by gdb-4.19 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. It worth noting, however,
it worth noting that pre-4.19 would not properly process 64-bit 
thread_ids >= 0x80000000. 

Thread_id 0xffffffffffffffff should not be used, gdb reserves it for 
ALL_THREADS thread id. This is a thread designation for all threads 
on the remote system. It is used in cases where stub does not support
threads or to specify command/condition applicable to all threads.


3.3.1 Variable Length Tread_Id (vt)

ALL_THREADS value is encoded as '-1' 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.

Both 32-bit and 64-bit stubs are interoperable with pre-4.19 
implementations as long as they do not use thread id >= 0x80000000. 
Stubs with higher requirements should be debugged by gdb-4.19 or newer. 


3.3.2. Fixed Length Thread_Id (ft)

ALL_THREADS is encoded as 'ffffffffffffffff', 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.

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

Both 32-bit and 64-bit stubs are interoperable with gdb-4.18 
implementations as long as they do not use thread id >= 0x80000000. 
Stubs with higher requirements should be debugged by gdb-4.19 or newer. 


3.4. Signals

Signals are unisgned integers with 0-255 range. They are always
encoded by sprintf(out_buf, "%02x", signal) or its equivalent.
Gdb follows standard unix signal definitions and 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. 

There is run length encoding scheme defined for ASCII encoded packets,
it is implemented by many receivers, however, it is not used.

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.


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.

  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>

             Register data are packed in the byte order of target.
            
	     Note: 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'

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

	     Gdb considers any error to be a memory access one.

             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.

  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 one.
   
  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 '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:  

             No response indeed.


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 unsuported.

  o 'setExtendedOps':

    Format: !

    Reply:  'ok' or 'statusString'

            Note: some widely distributed stubs will send 'error' or 
            'noSupport' to tell that extended ops are fine with them.
	    One has to set 'forceextended' to 1 in post-4.18 gdbs to 
            account for this deviation (see more details in section 5).

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

  o 'restart': restart the system under debugging

    Format: r00

    Reply:  'statusString'

4.2.2. Thread Requests

These requests should be either all supported or all unsupported.

   o 'setControlTrhead': all break points, continue and steps will
                         related to the thread

     Format: Hc<thread_id-vt>

     Reply:  'ok'

             It is a responsibility of gdb to insure that thread being
             set does exist before issuing this request.

   o 'setGeneralTrhead': all data operations will be related to this
                         thread ????? whatever does it mean

     Format: Hg<thread_id-vt>

     Reply:  'ok'

             It is a responsibility of gdb to insure that thread being
             set does exist before issuing this request.

   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.

   o 'currentThreadQuery': get thread which is stopped

      Format: qC

      Reply:  QC<thread_id-vt>

   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_if-ft>[<found_thread_id-ft>...]

             or 'error'

             First qM request after stop should contain non-zeor 'first'
             field, request with  zero 'first' thread should contain
             existing arg thread  (ALL_THREADS is not considered an
             existing thread).

4.2.3. Other Optional Requests

  o 'continueWithSignal': continue with signal delivered to a current
                          control thread
                          trhead

    Format: C<signal>

    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 

    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 'stepWithSignal': step with signal delivered to the control thread

    Format: S<signal>

    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 'interrupt': interrupt running system under debugging

     Format: ^C or BREAK sent to the debugger without packet
             framing

     Reply:  stopped system will reply to last received 'continue',
             'continueWithSignal', 'step' or 'stepWithSignal' request.

             Note: default is ^C, BREAK is used if gdb variable 
             'remotebreak' is set. BREAK is no-op if TCP stream 
             is used. 

   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>

             Gdb considers any error to be memory access one.

   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'

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

	     Gdb considers any error to be a memory access one.

   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 'intr
  
 
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'

                   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

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

<List will be added here>

4.2.6. Obsolete Elements

Who cares ?

<List will be added here>

5. Backward Comaptibility Issues

5.1. Old Gdb and New Stub

This is a less important issue, it seems reasonably simple of anybody
to update its gdb. Morever, it seems like there are not going to be any 
interoperability problems between new stubs and pre-4.19 gdbs as long 
as stub uses thread ids below 0x80000000.

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

5.2. New Gdb and Old Stub

It is highly desireable to provide interoprability between pre-4.19 
stubs an newer gdbs. 

There are few issues here to be resolved

  o  Post-4.19 gdbs are much pickier with regard to the response
     checking.  Also, many pre-4.19 stubd do not properly support 
     'kill'. 

     It seems reasonable to provide backward compatibility mode
     accounting for these differences, for example this mode could be 
     enabled by setting gdb variable 'pre419comaptible'. 
   
  o  Some stubs developed in pre-4.19 times are not able to properly 
     respond to '!' due to documentation bug. These stubs will respond 
     'noSupport' even if they are able to support extended operations.

     It seems reasonable to cover this popular deviation with another
     settable variable, e.g. 'forceextended' .

  o  Some stubs developed in per-4.19 times are not able to properly 
     support per thread debugging. 

     It seems reasonable to cover this popular deviation with another
     settable variable, e.g. 'forcenothreads'
    

         
  
 














Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]