rda/HOWTO

   1 How to implement a stub or server using RDA
   2 ===========================================
   3
   4 Andrew Cagney <cagney@redhat.com>
   5 Fernando Nasser <fnasser@redhat.com>
   6 Frank Eigler <fche@redhat.com>
   7 Kevin Buettner <kevinb@redhat.com>
   8
   9 Introduction
  10 ------------
  11
  12 RDA is a "Remote Debugger Agent" for GDB.  It provides a library of
  13 commonly used routines which may be used to construct a "debugger
  14 stub" or "debug agent".  The RDA package also includes several
  15 applications which use the RDA library.  It is useful to examine these
  16 examples when creating a new RDA application.  (One of the
  17 applications provides functionality similar to that of "gdbserver"
  18 found in the GDB sources.)
  19
  20 The RDA library provides an implementation of the "server" end of
  21 the GDB remote protocol.  An application which uses the RDA library
  22 will typically start up and then wait for GDB to connect to the
  23 the application via GDB's "target remote" command.  Once communication
  24 between the RDA application and GDB has been established, the
  25 RDA application translates GDB's remote protocol requests into queries
  26 against the target environment.  When results from these queries are
  27 known, the results are communicated back to GDB in a response packet.
  28
  29 The RDA library has been designed so that a relatively small amount of
  30 target dependent code is required in order to create a new RDA
  31 application.
  32
  33 GDB connects to the RDA application via either a TCP/IP connection
  34 or a connection on a serial port.  When TCP/IP is used, the RDA
  35 application waits for a connection from GDB by listening on a
  36 non-restricted TCP port.  A serial connection behaves in a similar
  37 fashion except that (obviously) no initial listen is needed.
  38
  39 Note: Users of this software should take the usual precautions with
  40 regard to security of TCP/IP ports.
  41
  42 Architecture
  43 ------------
  44
  45 The following diagram shows the components of an RDA application
  46 communicating with GDB:
  47
  48         (GDB) <---"remote"---> CLIENT <--> SERVER <--> TARGET
  49        -------                 ------------------------------
  50      The client.                The RDA application (server).
  51
  52 Where:
  53
  54         CLIENT  Provides the raw interface between
  55                 GDB and the internal SERVER
  56                 mechanism.
  57
  58                 The client passes on any data relevant
  59                 to the server.  The SERVER presents
  60                 CLIENT with raw output to be returned
  61                 to GDB.
  62
  63         SERVER  Implements the state-machine that
  64                 is capable of decoding / processing
  65                 various GDB remote protocol requests.
  66
  67         TARGET  The embedded system proper.  SERVER
  68                 passes decoded requests onto the TARGET
  69                 while TARGET notifies the SERVER of any
  70                 target state changes.
  71
  72
  73 Adding Target Dependent Code
  74 ----------------------------
  75
  76 An RDA application communicates with a debugger, such as GDB, using
  77 the GDB Remote Serial Protocol.  The RDA library performs the high
  78 level I/O management for the debugger connections, watches for new
  79 connections, and looks for protocol requests from existing
  80 connections.  The RDA library packages up suitable responses to
  81 protocol requests after invoking target specific callbacks which
  82 collect the necessary information.  In short, the RDA library manages
  83 communication with the debugger.  You are responsible for implementing
  84 target specific support.
  85
  86 The "target" is a simulator, hardware device, board, program, or
  87 whatever you are interfacing to your stub/server.
  88
  89 Starting up:
  90
  91 The function gdbsocket_startup() is used to register a TCP/IP port
  92 number upon which to listen.  It is called with the port number upon
  93 which to listen, a callback function to be invoked when a connection
  94 is made, and a pointer to target specific data which will be passed to
  95 the callback function.  The callback will be referred to as the
  96 "attach callback", perhaps due to the fact that GDB is attaching to
  97 RDA.
  98
  99 The function gdbsocket_startup() might be invoked as
 100 follows:
 101
 102     gdbsocket_startup (portnum, my_attach_func, my_attach_data)
 103
 104 The RDA library is capable of handling several connections (sessions)
 105 simultaneously.  If listening on several ports is desired, it is
 106 permitted to make several calls to gdbsocket_startup() in order to
 107 register the various sockets upon which the RDA application should
 108 listen.  (Note that it is still possible to have several connections
 109 at a time even without monitoring more than one port number.)
 110
 111 Callback Registration:
 112
 113 The library requires that you implement a set of callback routines for
 114 reading and writing memory, reading and writing registers, controlling
 115 the target, etc.  These callbacks are made available by filling in
 116 members of a gdbserv_target struct.  Registration of these callbacks
 117 is performed via the attach function passed as the second argument
 118 to gdbsocket_startup().  This function will be invoked when a new
 119 connection is detected upon the input port.
 120
 121 When a new connection is received on one of the sockets registered by
 122 gdbsocket_startup(), the corresponding attach routine is invoked.  The
 123 attach routine can reject the connection attempt by returning NULL.
 124 Otherwise, it is the responsibility of the attach function to allocate
 125 a gdbserv_target struct, fill in the various callback members, and
 126 perhaps perform some other initializations.  If all of this
 127 successfully completes, the attach function should return a pointer to
 128 the gdbserv_target struct that's been initialized.
 129
 130 A skeleton of my_attach_func() might look something like this:
 131
 132     struct gdbserv_target *
 133     my_attach_func (struct gdbserv *serv, void *context)
 134     {
 135       struct gdbserv_target *my_target;
 136
 137       if (!new_connection_okay ())
 138         return NULL;
 139
 140       my_target = malloc (sizeof (struct gdbserv_target));
 141       if (!my_target)
 142         return NULL;
 143       memset (my_target, 0, sizeof (struct gdbserv_target));
 144
 145       my_target->get_reg = my_get_reg;
 146       my_target->set_reg = my_set_reg;
 147       ...
 148
 149       perform_other_initializations ();
 150
 151       return my_target;
 152     }
 153
 154 Handling target events:
 155
 156 The "gdbserv_fromtarget" prefixed routines are called by your
 157 target-specific code, however they must not be called from any of the
 158 gdbserv_target callback functions.  (Use of a flag or flags for
 159 indicating a state change that is checked at some later time is
 160 recommended.)  There are essentially only three of these routines that
 161 you need to be concerned with.  They are:
 162
 163     void gdbserv_fromtarget_reset (struct gdbserv *gdbserv, int sigval);
 164     void gdbserv_fromtarget_exit (struct gdbserv *gdbserv, int sigval);
 165     void gdbserv_fromtarget_break (struct gdbserv *gdbserv, int sigval);
 166
 167 The first two (gdbserv_fromtarget_reset and gdbserv_fromtarget_exit)
 168 are used to indicate target reset and program exit.  The latter,
 169 gdbserv_fromtarget_break, is used in all other situations to indicate
 170 that the target has stopped for some reason (indicated by sigval).
 171
 172 If your target is a simulator, these "gdbserv_fromtarget" prefixed
 173 routines should be called when the corresponding condition arises in
 174 your simulated target.  If your target is a board, these functions
 175 might be invoked from your interrupt service routines.  If you target
 176 is a device that has to be polled to detect state changes, you'll call
 177 these routines from the polling code.
 178
 179 The Event Loop:
 180
 181 The RDA library uses an event driven model.  The function gdbloop_poll()
 182 causes the library to:
 183
 184     1) Look for and handle new connection requests from a debugger.
 185     2) Read remote protocol commands from a stream associated with an
 186        already connected debugger and invoke one or more of the
 187        callbacks that you have registered.
 188
 189 A single argument is passed to gdbloop_poll() indicating the length of
 190 time to wait for an event to occur.  A negative value will cause
 191 gdbloop_poll() to block as long as needed for something to happen.
 192 Otherwise, the integer passed to gdbloop_poll is the time in
 193 milliseconds to wait for an event to occur.
 194
 195 If your RDA application is structured as a server, then gdbloop_poll()
 196 will be called repeatedly in the main loop.  If the RDA application is
 197 part of a simulator, then a call to gdbloop_poll() should be added to
 198 the existing main loop.  If a debugging stub for a board is being
 199 implemented, then gdbloop_poll() should be invoked periodically,
 200 perhaps in response to a timer interrupt.
 201
 202 If your target has to be polled for state changes, you will have to
 203 alternate calls to gdbloop_poll() with polls of the target status.
 204 As noted earlier, one of the "gdbserv_fromtarget" prefixed functions
 205 is called to indicate a change of state (stop, exit, or reset).
 206
 207 Callbacks:
 208
 209 Recall that gdbsocket_startup() is given, as one of its arguments,
 210 the address of a function which is called to register a set of
 211 callbacks via a gdbserv_target struct.  You will, of course, have
 212 to implement each these callbacks.
 213
 214 Some knowledge of the GDB remote protocol will be required.  Refer to
 215 the appendix of the GDB manual entitled "GDB Remote Serial Protocol"
 216 for these details.  Here is a link (which may or may not work):
 217
 218   http://sourceware.org/gdb/current/onlinedocs/gdb_33.html#SEC691
 219
 220 The layout of the gdbserv_target struct is defined in the RDA
 221 source tree in the header file include/gdbserv-target.h.  (Most
 222 of the callbacks are discussed below.)
 223
 224 Finally, it should prove useful to examine samples/demo-target.c,
 225 unix/thread-db.c, and unix/linux-target.c to see how these RDA
 226 applications implement the various callbacks.
 227
 228 Register Related Callbacks
 229 --------------------------
 230
 231 The register related callbacks are probably the most confusing because
 232 there are many of them.  Moreover, not all of them should be
 233 implemented.
 234
 235 If your target has a concept of threads and you want GDB to be able to
 236 debug these threads, you should implement the threaded register
 237 processing callbacks.  These are next_gg_reg, next_expedited_reg,
 238 reg_format, set_thread_reg and get_thread_reg.  Even if your
 239 target is single-threaded, you should consider using these
 240 methods anyway.
 241
 242 If you target does not use threads you may instead implement the
 243 following methods:  input_reg, output_reg, gg_reg_nr,
 244 expedited_reg_nr, sizeof_reg, set_reg, and get_reg.
 245
 246 Finally, there are an older set of register related callbacks that
 247 should be avoided.  These are:  process_set_reg, process_get_reg,
 248 process_set_regs, and process_get_regs.  These older callbacks will
 249 not be discussed further.
 250
 251 The thread aware register related callbacks are as follows:
 252
 253     int (*next_gg_reg) (struct gdbserv *, struct gdbserv_thread *,
 254                         int reg_nr);
 255     int (*next_expedited_reg) (struct gdbserv *, struct gdbserv_thread *,
 256                                int reg_nr);
 257     int (*reg_format) (struct gdbserv *, struct gdbserv_thread *,
 258                        int reg_nr, int *size, int *padding);
 259     int (*set_thread_reg) (struct gdbserv *, struct gdbserv_thread *,
 260                            int regnr, const struct gdbserv_reg *reg);
 261     int (*get_thread_reg) (struct gdbserv *, struct gdbserv_thread *,
 262                            int regnr, struct gdbserv_reg *reg);
 263
 264     All of these thread aware register related callbacks are passed a
 265     pointer to a gdbserv object, as well as a pointer to a target
 266     defined thread object (struct gdbserv_thread *).  (You will need
 267     to define the layout of struct gdbserv_thread.)
 268
 269     The ``next_gg_reg'' callback is used by the RDA library to iterate
 270     over the registers in a 'G' or 'g' packet.  (A 'g' packet is used
 271     to read general purpose registers.  A 'G' packet is used to write
 272     them.) Thus, the ``next_gg_reg'' callback effectively defines
 273     the registers that are in a 'G' or 'g' packet and their order.
 274     This function is initially called with the reg_nr parameter set to
 275     -1.  This callback should be implemented to return the register
 276     number of the first register when reg_nr is -1.  After that, it is
 277     called successively with its previous return value in order to
 278     obtain successive register numbers.  next_gg_reg() should return a
 279     negative value (such as -1) when the end of the list is reached.
 280     (Technically, the end of list is reached on the call prior to the
 281     one that returns -1.)
 282
 283     The ``next_expedited_reg'' callback is optional.  It is used to
 284     construct the list of values to include in a 'T' (stop reply)
 285     packet.  The RDA library will initially call next_expedited_reg()
 286     with reg_nr set to -1 in order to obtain the first register (as
 287     the return value of the callback), and will, on successive calls,
 288     be called with the previous return value.  A negative value should
 289     be returned when there are no more values to return.
 290
 291     Although the ``next_expedited_reg'' callback is optional, it is
 292     strongly recommended that you implement it.  Defining this method
 293     will permit the RDA library to send register values to GDB that it
 294     will almost certainly need.  Examples of registers that should be
 295     included in the 'T' packet include the stack pointer and program
 296     counter.  If this callback is not defined, RDA will not send any
 297     registers to GDB in the stop reply packet.  GDB will then need to
 298     use a 'g' packet to retrieve all values (even if all values aren't
 299     required).
 300
 301     The ``reg_format'' method describes format of the register given
 302     by reg_nr in the 'g' and 'G' packets.  This method should set
 303     ``size'' to the width (in bytes) of the register given by
 304     ``reg_nr''.  (Due to the representation of bytes in the remote
 305     protocol, 2*size bytes will actually be input or output.)  If
 306     padding is required in the 'g' or 'G' packet, then ``padding''
 307     should be set to the number of bytes of padding required.  Again,
 308     2*size bytes will be actually be output.  A negative value of
 309     padding indicates that the padding should preceded the register
 310     value.  A positive value places the padding after the register
 311     value.  Note that the ``size'' and ``padding'' parameters are
 312     actually pointers, and that suitable pointer dereferencing is
 313     required when setting these as return values.
 314
 315     The ``set_thread_reg'' method is used to change the value of the
 316     register specified by ``regnr'' to that of the value specified in
 317     ``reg'' parameter.  (The new register value does not actually need
 318     to be set until the target is made to run again (in some fashion).
 319     Thus, it is permissible for your target specific code to
 320     accumulate the changes to be made to the registers and update them
 321     all at once if that is more efficient or convenient.)  Return
 322     0 if successful, or -1 if not.
 323
 324     The ``get_thread_reg'' method is used to retrieve the value of
 325     the register specified by ``regnr''.  The value should be placed
 326     in ``reg''.  Return 0 if successful, or -1 if not.
 327
 328 The non-threaded register related callbacks are as follows:
 329
 330     int (*input_reg) (struct gdbserv *gdbserv, struct gdbserv_reg *reg, int len);
 331     void (*output_reg) (struct gdbserv *gdbserv, struct gdbserv_reg *reg, int len);
 332     int (*gg_reg_nr) (struct gdbserv *, int index);
 333     int (*expedited_reg_nr) (struct gdbserv *, int index);
 334     long (*sizeof_reg) (struct gdbserv *, int regnr);
 335     int (*set_reg) (struct gdbserv *, int regnr, struct gdbserv_reg *reg);
 336     int (*get_reg) (struct gdbserv *, int regnr, struct gdbserv_reg *reg);
 337
 338     Each of these methods is passed passed a pointer to a gdbserv
 339     object.
 340
 341     The ``input_reg'' method should be set to one of two predefined
 342     methods, either gdbserv_input_reg_beb(), for reading big endian
 343     data, or gdbserv_input_reg_leb(), for reading little endian data.
 344     It is unlikely that you'll need to define some custom method for
 345     reading or writing data.
 346
 347     Likewise, the ``output_reg'' method should be set to one of two
 348     predefined methods, either gdbserv_output_reg_beb() or
 349     gdbserv_output_leb().  Again, it is unlikely that you'll need to
 350     define some custom method for reading or writing data.
 351
 352     The ``gg_reg_nr'' method is used by the RDA library to obtain
 353     register numbers for 'G' or 'g' packets.  (A 'g' packet is used to
 354     read general purpose registers.  A 'G' packet is used to write
 355     them.)  The library will initially invoke this method with index
 356     set to 0 and will successively increase the value passed as
 357     index by 1 until gg_reg_nr returns a negative value.  This method
 358     should return the register number associated with the given index
 359     (in the 'g' or 'G' packet).  It should do so even if there is a
 360     hole or undefined register in the packet, and only return -1 when
 361     there truly are no more registers.
 362
 363     The ``expedited_reg_nr'' method works the same as ``gg_reg_nr''
 364     except that it specifies the registers in a 'T' (stop reply)
 365     packet.  See the discussion above for ``next_expedited_reg''.
 366
 367     The ``sizeof_reg'' method is used to return the size in bytes
 368     of the register specified by ``regnr''.  (The ``regnr'' value
 369     passed to sizeof_reg() is obtained from either gg_reg_nr() or
 370     expedited_reg_nr().  See above.) Due to the way that register
 371     values are transmitted using the GDB remote protocol, 2*size bytes
 372     are actually output.  Finally, a negative size (return) value
 373     indicates a hole in the 'G' or 'g' packet, i.e. space is allocated
 374     in the packet, but there's no corresponding register in your
 375     target.
 376
 377     The ``set_reg'' method is used to update the value specified
 378     by ``regnr'' in your target to that of the value specified
 379     by the ``reg'' parameter.  Return 0 if successful, -1 if not.
 380
 381     The ``get_reg'' method is used to fetch the value specified by
 382     ``regrn'' from your target.  It should be placed in the
 383     gdbserv_reg struct specified by ``reg''.  Return 0 if successful,
 384     -1 if not.
 385
 386 Dealing with gdbserv_reg * values
 387 ---------------------------------
 388
 389 Some of the callbacks have parameters of type `struct gdbserv_reg *'.
 390 This type is used to specify the value of registers, and is quite
 391 often used to specify addresses and other integral values as well.
 392 The RDA library provides several functions for converting to/from
 393 this type and an array of bytes.
 394
 395 These functions which put an array of bytes into a gdbserv_reg
 396 struct are as follows:
 397
 398     void gdbserv_be_bytes_to_reg (struct gdbserv *gdbserv,
 399                                   const void *buf,
 400                                   int buflen,
 401                                   struct gdbserv_reg *reg,
 402                                   int reglen,
 403                                   int sign_extend);
 404     void gdbserv_le_bytes_to_reg (struct gdbserv *gdbserv,
 405                                   const void *buf,
 406                                   int buflen,
 407                                   struct gdbserv_reg *reg,
 408                                   int reglen,
 409                                   int sign_extend);
 410     void gdbserv_host_bytes_to_reg (struct gdbserv *gdbserv,
 411                                     const void *buf,
 412                                     int buflen,
 413                                     struct gdbserv_reg *reg,
 414                                     int reglen,
 415                                     int sign_extend);
 416
 417     In each case, `gdbserv' represents the gdbserv object, `buf' is
 418     the array of bytes to to convert, `buflen' is the number of bytes
 419     in the buffer `buf', `reg' is the gdbserv_reg struct into which
 420     the value should be placed, `reglen' is the size of the register,
 421     and `sign_extend' is non-zero iff the value should be
 422     sign-extended.  (To the best of my knowledge, the only
 423     architecture which requires sign extension is MIPS.)
 424
 425     Each of these methods handles a different byte order.  The
 426     ``gdbserv_be_bytes_to_reg'' method converts a buffer of big-endian
 427     bytes to the gdbserv_reg format.  Likewise,
 428     ``gdbserv_le_bytes_to_reg'' and ``gdbserv_host_bytes_to_reg''
 429     convert little endian and host format bytes.  The latter method is
 430     really a convenience function which just picks either the big
 431     endian or little endian formatter based on the endianess of the
 432     host that the RDA application is being built upon.
 433
 434     For example, suppose you are interfacing the RDA library to a
 435     simulator which resides in the same process.  If the variable
 436     ``regval'' has a register's value, this value may be put into
 437     the gdbserv_reg format as follows:
 438
 439         unsigned long regval;
 440         struct gdbserv_reg regval_as_reg;
 441
 442         regval = ...
 443
 444         gdbserv_host_bytes_to_reg (serv, &regval, sizeof(regval),
 445                                    &addr_as_reg), sizeof(regval), 0);
 446
 447 Conversely, these functions (below) convert the value found in a
 448 gdbserv_reg struct into an array of bytes:
 449
 450     void gdbserv_be_bytes_from_reg (struct gdbserv *gdbserv,
 451                                     void *buf,
 452                                     int buflen,
 453                                     const struct gdbserv_reg *reg,
 454                                     int sign_extend);
 455
 456     void gdbserv_le_bytes_from_reg (struct gdbserv *gdbserv,
 457                                     void *buf,
 458                                     int buflen,
 459                                     const struct gdbserv_reg *reg,
 460                                     int sign_extend);
 461
 462     void gdbserv_host_bytes_from_reg (struct gdbserv *gdbserv,
 463                                       void *buf,
 464                                       int buflen,
 465                                       const struct gdbserv_reg *reg,
 466                                       int sign_extend);
 467
 468     In each of these functions, ``gdbserv'' is a pointer o the gdbserv
 469     object, ``buf'' is a pointer to the array of bytes into which to place
 470     a value, ``buflen'' is the length of the buffer ``buf'', ``reg'' is
 471     a pointer to the gdbserv_reg struct to convert from, and ``sign_extend''
 472     is non-zero iff sign-extension should be performed in the event that
 473     ``buf'' is bigger than the size of the register.
 474
 475 Memory Related Callbacks
 476 ------------------------
 477
 478 Like the register related callbacks, the memory related callbacks come in
 479 two varieties, threaded and non-threaded.  You only need to implement one
 480 set of these callbacks.  The only difference between these callbacks is
 481 the fact that a thread object is passed to the threaded-version.
 482
 483 Here are the thread aware versions of the memory callbacks:
 484
 485     long (*get_thread_mem) (struct gdbserv *, struct gdbserv_thread *,
 486                             struct gdbserv_reg *addr, void *data, long len);
 487     long (*set_thread_mem) (struct gdbserv *, struct gdbserv_thread *,
 488                             struct gdbserv_reg *addr, void *data, long len);
 489
 490     Both of these functions are passed both the gdbserv object and
 491     a thread object.  The ``addr'' parameter represents the target
 492     memory address to either read or write.  The ``data'' parameter is
 493     a pointer to the buffer to either deposit data into or from which
 494     data is written.  The ``len'' parameter is the number of bytes
 495     that should be read or written.
 496
 497     The ``get_thread_mem'' callback attempts to read the specified
 498     number of bytes from the target and place them into the buffer.
 499     It returns the number of bytes successfully read, or -1 if the
 500     memory read completely fails.
 501
 502     The ``set_thread_mem'' callback attempts to write the specified
 503     number of bytes from the buffer provided to the target's memory.
 504     It returns the number of bytes successfully written, or -1 if
 505     the memory write completely fails.
 506
 507 Here are the non-thread-aware memory callbacks:
 508
 509     long (*get_mem) (struct gdbserv *, struct gdbserv_reg *addr, void *data,
 510                      long len);
 511     long (*set_mem) (struct gdbserv *, struct gdbserv_reg *addr, void *data,
 512                      long len);
 513
 514     The gdbserv object is passed to these functions.  The ``addr''
 515     parameter represents the target memory address to either read or
 516     write.  The ``data'' parameter is a pointer to the buffer to
 517     either deposit data into or from which data is written.  The
 518     ``len'' parameter is the number of bytes that should be read or
 519     written.
 520
 521     The ``get_mem'' callback attempts to read the specified number of
 522     bytes from the target and place them into the buffer.  It returns
 523     the number of bytes successfully read, or -1 if the memory read
 524     completely fails.
 525
 526     The ``set_mem'' callback attempts to write the specified number of
 527     bytes from the buffer provided to the target's memory.  It returns
 528     the number of bytes successfully written, or -1 if the memory
 529     write completely fails.
 530
 531 General Query Packets / General Set Packets
 532 -------------------------------------------
 533
 534 General query packets start with a 'q' prefix and general set packets
 535 begin with a 'Q' prefix.  In recent years, nearly all new extensions
 536 to the remote protocol have added either a new 'q' or 'Q' packet, or
 537 both.
 538
 539 There are a number of general query packets defined by the remote
 540 protocol.  The RDA library currently recognizes the 'qRcmd', 'qCRC:',
 541 'qC', 'qfThreadInfo', 'qsThreadInfo', and 'qThreadExtraInfo' packets.
 542 For all other 'q' and 'Q' packets, you will need to implement a
 543 callback which parses everything after the 'q' or 'Q', including the
 544 packet's parameters (if any), queries the target in an appropriate
 545 manner, and then formats and outputs the response.
 546
 547 When a unrecognized 'q' packet is received from the client, the
 548 ``process_get_gen'' method is called.  Here's the prototype:
 549
 550     void (*process_get_gen) (struct gdbserv *);
 551
 552 When any 'Q' packet is received from the client, the ``process_set_gen''
 553 method is called.   Here's the prototype:
 554
 555     void (*process_set_gen) (struct gdbserv *);
 556
 557 The 'qRcmd' packet is used to invoke arbitrary target specific
 558 commands.  Results from these commands are usually directly printed
 559 out to GDB's console.  Reciept of the qRcmd packet causes
 560 ``process_rcmd'' callback to be invoked.  Here's the prototype:
 561
 562     void (*process_rcmd) (struct gdbserv *, const char *cmd,
 563           int sizeof_cmd);
 564
 565 Each of these callbacks is passed a pointer to a gdbserv object.  The
 566 ``process_rcmd'' callback is passed two additional parameters, ``cmd'',
 567 a string representing the target specific command, and ``sizeof_cmd'' which
 568 represents the length of ``cmd''.  (Do not assume that ``cmd'' will be
 569 null-terminated.)
 570
 571 When implementing either the ``process_get_gen'' or ``process_set_gen''
 572 callbacks, the following function is useful for parsing reset of the
 573 packet name (and delimiters associated with any arguments):
 574
 575     int gdbserv_input_string_match (struct gdbserv *gdbserv,
 576                                     const char *string);
 577
 578 gdbserv_input_string_match() will attempt to compare the next portion
 579 of the input packet against the characters in ``string''.  If an
 580 exact match is found, the number of characters matched is returned
 581 and that number of characters is advanced in the input packet.  If
 582 the characters in ``string'' are not matched exactly, and in their
 583 entirety, -1 is returned.
 584
 585 Hex encoded numeric arguments may be parsed from the 'q' or 'Q' packet
 586 by invoking gdbserv_input_hex_long() or gdbserv_input_hex_ulong():
 587
 588     int gdbserv_input_hex_long (struct gdbserv *gdbserv, long *val);
 589
 590     int gdbserv_input_hex_ulong (struct gdbserv *gdbserv,
 591                                  unsigned long *val);
 592
 593 In both of these functions, the ``val'' parameter is a pointer to either
 594 a long or unsigned long into which to put the decoded integer.  If no
 595 number could be matched, a -1 is returned.
 596
 597 There are a number of functions which may be used to compose and
 598 output a reply.  Here are several of the more useful ones:
 599
 600     void gdbserv_output_string (struct gdbserv *gdbserv, const char *buf);
 601
 602     void gdbserv_output_string_as_bytes (struct gdbserv *gdbserv,
 603                                          const char *buf);
 604
 605     void gdbserv_output_bytes (struct gdbserv *gdbserv, const char *buf,
 606                                unsigned sizeof_buf);
 607
 608 gdbserv_output_string() outputs the string specified by ``buf''
 609 verbatim.  gdbserv_output_string_as_bytes() outputs a string, ``buf'',
 610 as a hex encoded value.  Finally, gdbserv_output_bytes(), outputs an
 611 abitrary sequence of bytes given by ``buf'' with length ``sizeof_buf''
 612 as a hex encoded value.
 613
 614 There exist several other "gdbserv_input_" and "gdb_serv_output_"
 615 prefixed functions.  Declarations for these may be found in
 616 include/gdbserv.h.
 617
 618 Callback for Setting Program Arguments
 619 --------------------------------------
 620
 621 The 'A' packet is used to set program arguments.  When the 'A' packet is
 622 recognized, the process_set_args() callback is invoked.  It has the following
 623 prototype:
 624
 625     void (*process_set_args) (struct gdbserv *);
 626
 627 Notice that the library does not decode the arguments.  Suitable calls
 628 to the various "gdbserv_input_" functions must be called to parse
 629 these arguments.
 630
 631 Callback for setting the PC
 632 ---------------------------
 633
 634 When a 'c' or 's' (continue or singlestep) packet is received with the
 635 address to continue from the ``process_set_pc'' callback is invoked.
 636 Its prototype is as follows:
 637
 638     void (*process_set_pc) (struct gdbserv *, const struct gdbserv_reg *val);
 639
 640 The ``val'' parameter species the PC value to set.
 641
 642 Callback for Flushing the Instruction Cache
 643 -------------------------------------------
 644
 645 The ``flush_i_cache'' callback is invoked prior to continuing or
 646 singlestepping the program.  This callback should do whatever
 647 operations are required in order to invalidate the instruction cache.
 648 Its prototype is:
 649
 650     void (*flush_i_cache) (struct gdbserv *);
 651
 652 Signal Related Callbacks
 653 ------------------------
 654
 655 Non-threaded targets should define the ``process_signal'' callback.  This
 656 callback specifies the signal to deliver to the target when either a
 657 'C' or 'S' packet is used.  (The 'C' packet continues the program with a
 658 given signal; the 'S' packet singlesteps the program with the given signal.)
 659 The prototype for ``process_signal'' is:
 660
 661     int (*process_signal) (struct gdbserv *, int sigval);
 662
 663 The ``sigkill_program'' method is invoked if ``process_signal'' fails
 664 to deliver a signal.  This method will not deliver the desired signal,
 665 but should instead kill the program.  This method should not really be
 666 needed so long as the ``process_signal'' exists and works properly.
 667 Here's the prototype:
 668
 669     void (*sigkill_program) (struct gdbserv *);
 670
 671 There are two other signal related callbacks, ``compute_signal'' and
 672 ``get_trap_number''.  Neither of these are called by the RDA library
 673 though.  New RDA applications do not need to define these callbacks.
 674
 675 Target State/Control Callbacks
 676 --------------------------------
 677
 678 The ``exit_program'' callback is invoked when a 'k' (kill) packet is
 679 received from the client.  It's prototype is as follows:
 680
 681     void (*exit_program) (struct gdbserv *);
 682
 683 The ``break_program'' callback is invoked when a request to halt,
 684 suspend, or break the target is received from the client.  This
 685 callback should do whatever is necessary to direct the target to stop.
 686 Later, when the target has actually stopped, the function
 687 gdbserv_fromtarget_break() should be called to indicate that it has
 688 indeed stopped.  The ``break_program'' callback must NOT call
 689 gdbserv_fromtarget_break().  Here's the prototype:
 690
 691     void (*break_program) (struct gdbserv *);
 692
 693 The ``reset_program'' callback is invoked when an 'r' (reset system)
 694 packet is recieved from the client.  The ``reset_program'' callback
 695 is invoked when an 'R' (reset program) packet is received.  The
 696 prototypes for these methods are as follows:
 697
 698     int (*reset_program) (struct gdbserv *);
 699     void (*restart_program) (struct gdbserv *);
 700
 701 The ``singlestep_thread'' or ``singlestep_program'' callbacks are
 702 invoked for 's' (singlestep) or 'S' (singlestep with signal) packets.
 703 Only one of these methods needs to be implemented.  If the
 704 ``singlestep_thread'' method is defined, it will be tried before the
 705 ``singlestep_program'' is invoked.  The ``singlestep_thread'' method
 706 is passed a pointer to a gdbserv object, a pointer to a thread object,
 707 as well as the signal, ``siggnal'' to continue with.  The
 708 ``singlestep_program'' method is only passed the gdbserv object.  Care
 709 must be taken to also define ``process_signal'' when only
 710 ``singlestep_program'' is defined.  Here are the prototypes:
 711
 712     void (*singlestep_thread) (struct gdbserv *, struct gdbserv_thread *,
 713                                const struct gdbserv_reg *signnal);
 714     void (*singlestep_program) (struct gdbserv *);
 715
 716 The ``cyclestep_thread'' and ``cyclestep_program'' callbacks are invoked
 717 in response to an 'i' (cycle step) packet.  Only one of these methods
 718 need to be define, and as before, the thread-specific method is tried
 719 first.  The prototypes are as follows:
 720
 721     void (*cyclestep_thread) (struct gdbserv *, struct gdbserv_thread *,
 722                               const struct gdbserv_reg *signnal);
 723     void (*cyclestep_program) (struct gdbserv *);
 724
 725 The ``continue_thread'' or ``continue_program'' callbacks are invoked
 726 in response to either a 'c' (continue) or 'C' (continue with signal)
 727 packet.  As before, only one of these methods needs to be defined.
 728 The thread-specific method is tried first.  The ``continue_thread''
 729 method is passed the signal, ``signnal'', to continue with (in
 730 addition to the gdbserv object and the gdbserv_thread object).  The
 731 ``continue_program'' method is not passed a signal, thus the
 732 ``process_signal'' must be defined in order for the signal to be
 733 delivered to the target.  Here are the prototypes:
 734
 735     void (*continue_thread) (struct gdbserv *, struct gdbserv_thread *,
 736                              const struct gdbserv_reg *signnal);
 737     void (*continue_program) (struct gdbserv *);
 738
 739 Breakpoint Callbacks
 740 --------------------
 741
 742 The ``set_breakpoint'' and ``remove_breakpoint'' callbacks are invoked
 743 in response to the 'z' (set breakpoint) and 'Z' (remove breakpoint)
 744 packets respectively.  If these operations do are not defined here,
 745 that fact will be reported to GDB and GDB will attempt to set software
 746 breakpoints via reads and writes to memory.  The prototypes for these
 747 callbacks are as follows:
 748
 749     enum gdbserv_target_rc (*set_breakpoint) (struct gdbserv *,
 750                                               enum gdbserv_target_bp type,
 751                                               struct gdbserv_reg *addr,
 752                                               struct gdbserv_reg *len);
 753     enum gdbserv_target_rc (*remove_breakpoint) (struct gdbserv *,
 754                                                  enum gdbserv_target_bp type,
 755                                                  struct gdbserv_reg *addr,
 756                                                  struct gdbserv_reg *len);
 757
 758 The return status codes (of type enum gdbserv_target_rc) for these methods
 759 may be one of the following:
 760
 761     GDBSERV_TARGET_RC_ERROR     - Operation failed; reply with an 'Enn' error.
 762                                   (The breakpoint methods reply with 'E03'.)
 763     GDBSERV_TARGET_RC_OK        - Operation succeeded; reply with 'OK'.
 764     GDBSERV_TARGET_RC_UNKNOWN   - Operation not supported; send no reply.
 765                                   This null reply signals to GDB that the
 766                                   operation is not supported.  For many
 767                                   operations, GDB will attempt to find
 768                                   an alternate mechanism to use, or will
 769                                   continue on as best as it can.
 770
 771 The ``type'' parameter for these methods (of type enum gdbserv_target_bp)
 772 may be one of the following:
 773
 774     GDBSERV_TARGET_BP_SOFTWARE  - Software breakpoint.
 775     GDBSERV_TARGET_BP_HARDWARE  - Hardware breakpoint.
 776     GDBSERV_TARGET_BP_WRITE     - Write watchpoint.
 777     GDBSERV_TARGET_BP_READ      - Read watchpoint.
 778     GDBSERV_TARGET_BP_ACCESS    - Access (read or write) watchpoint.
 779
 780 Note too that the address, ``addr'', at which to set the breakpoint or
 781 watchpoint is specified using a gdbserv_reg struct.  The length,
 782 ``len'', is also specified using this type.  See the section entitled
 783 "Dealing with gdbserv_reg * values" for a list of functions which
 784 may be used for accessing the values stored in these containers.
 785
 786 Thread Related Callbacks
 787 ------------------------
 788
 789 The ``thread_info'' callback is called in response to the
 790 'qThreadExtraInfo' packet.  It allocates and returns a string
 791 containing printable information about the thread specified by the
 792 parameter ``thread''.  This information is returned to GDB for use in
 793 its "info threads" command.  Its prototype is as follows:
 794
 795     char *(*thread_info) (struct gdbserv *, struct gdbserv_thread *thread);
 796
 797 The ``thread_id'' callback is used to map the thread specified by
 798 ``thread'' to a unique identifier (an integer) shared between GDB and
 799 the RDA application.  The integer needs to be placed into a gdbserv_reg
 800 container.  Its prototype is as follows:
 801
 802     char *(*thread_info) (struct gdbserv *, struct gdbserv_thread *thread);
 803
 804 The ``thread_lookup_by_id'' callback is used to map a thread id, ``id'',
 805 to a thread, ``thread'', of type ``struct gdbserv_thread *''.  It
 806 should return a positive integer if ``id'' uniquely identifies a
 807 thread.  It should return 0 and select an arbitrary thread if the
 808 thread ID is zero.  Otherwise, it should return -1 and select an
 809 arbitrary thread if the ID does not uniquely identify a thread or if
 810 the thread id is invalid.  Here's the prototype:
 811
 812     int (*thread_lookup_by_id) (struct gdbserv *,
 813                                 const struct gdbserv_reg *id,
 814                                 struct gdbserv_thread **thread);
 815
 816 The ``thread_next'' callback is used to iterate over all threads known
 817 to the RDA application.  The GDB library will start off by calling the
 818 ``thread_next'' callback with the ``thread_last'' parameter set to
 819 NULL and expect the first thread to be returned.  (It doesn't really
 820 matter which thread is first, so long as all threads are eventually
 821 enumerated.)  On successive calls, ``thread_next'' will be called with
 822 the previous thread returned as the value of ``thread_last'', with the
 823 expectation that the next (for some suitable meaning of "next") thread
 824 be returned.  When there are no more threads, NULL is returned.
 825 Here's the prototype:
 826
 827     struct gdbserv_thread *(*thread_next) (struct gdbserv *,
 828                                            struct gdbserv_thread *thread_last);
 829
 830 Unknown Packet Callback
 831 -----------------------
 832
 833 The ``process_target_packet'' callback is invoked when a packet is
 834 seen that does not start with one of the letters used by the remote
 835 protocol.  Here's the prototype:
 836
 837     void (*process_target_packet) (struct gdbserv *);
 838
 839 Note:  This method is probably not all that useful given that the
 840 leading packet character is consumed by the the caller of the
 841 ``process_target_packet'' callback.
 842
 843 Shutdown Callback
 844 -----------------
 845
 846 The ``detach'' callback is invoked when an end-of-file condition is
 847 sensed on the input stream.  Note that the second parameter,
 848 ``target'' is a pointer to the data structure containing the list of
 849 callbacks originally allocated by the ``attach'' method.  It is passed
 850 to the ``detach'' callback so that the callback struct can be
 851 deallocated.  Here's the prototype:
 852
 853     void (*detach) (struct gdbserv *, struct gdbserv_target *target);