1 How to implement a stub or server using RDA
2 ===========================================
4 Andrew Cagney <cagney@redhat.com>
5 Fernando Nasser <fnasser@redhat.com>
6 Frank Eigler <fche@redhat.com>
7 Kevin Buettner <kevinb@redhat.com>
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.)
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.
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
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.
39 Note: Users of this software should take the usual precautions with
40 regard to security of TCP/IP ports.
45 The following diagram shows the components of an RDA application
46 communicating with GDB:
48 (GDB) <---"remote"---> CLIENT <--> SERVER <--> TARGET
49 ------- ------------------------------
50 The client. The RDA application (server).
54 CLIENT Provides the raw interface between
55 GDB and the internal SERVER
58 The client passes on any data relevant
59 to the server. The SERVER presents
60 CLIENT with raw output to be returned
63 SERVER Implements the state-machine that
64 is capable of decoding / processing
65 various GDB remote protocol requests.
67 TARGET The embedded system proper. SERVER
68 passes decoded requests onto the TARGET
69 while TARGET notifies the SERVER of any
73 Adding Target Dependent Code
74 ----------------------------
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.
86 The "target" is a simulator, hardware device, board, program, or
87 whatever you are interfacing to your stub/server.
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
99 The function gdbsocket_startup() might be invoked as
102 gdbsocket_startup (portnum, my_attach_func, my_attach_data)
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.)
111 Callback Registration:
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.
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.
130 A skeleton of my_attach_func() might look something like this:
132 struct gdbserv_target *
133 my_attach_func (struct gdbserv *serv, void *context)
135 struct gdbserv_target *my_target;
137 if (!new_connection_okay ())
140 my_target = malloc (sizeof (struct gdbserv_target));
143 memset (my_target, 0, sizeof (struct gdbserv_target));
145 my_target->get_reg = my_get_reg;
146 my_target->set_reg = my_set_reg;
149 perform_other_initializations ();
154 Handling target events:
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:
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);
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).
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.
181 The RDA library uses an event driven model. The function gdbloop_poll()
182 causes the library to:
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.
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.
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.
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).
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.
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):
218 http://sourceware.org/gdb/current/onlinedocs/gdb_33.html#SEC691
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.)
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.
228 Register Related Callbacks
229 --------------------------
231 The register related callbacks are probably the most confusing because
232 there are many of them. Moreover, not all of them should be
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
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.
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.
251 The thread aware register related callbacks are as follows:
253 int (*next_gg_reg) (struct gdbserv *, struct gdbserv_thread *,
255 int (*next_expedited_reg) (struct gdbserv *, struct gdbserv_thread *,
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);
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.)
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.)
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.
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
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.
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.
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.
328 The non-threaded register related callbacks are as follows:
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);
338 Each of these methods is passed passed a pointer to a gdbserv
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.
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.
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.
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''.
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
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.
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,
386 Dealing with gdbserv_reg * values
387 ---------------------------------
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.
395 These functions which put an array of bytes into a gdbserv_reg
396 struct are as follows:
398 void gdbserv_be_bytes_to_reg (struct gdbserv *gdbserv,
401 struct gdbserv_reg *reg,
404 void gdbserv_le_bytes_to_reg (struct gdbserv *gdbserv,
407 struct gdbserv_reg *reg,
410 void gdbserv_host_bytes_to_reg (struct gdbserv *gdbserv,
413 struct gdbserv_reg *reg,
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.)
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.
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:
439 unsigned long regval;
440 struct gdbserv_reg regval_as_reg;
444 gdbserv_host_bytes_to_reg (serv, ®val, sizeof(regval),
445 &addr_as_reg), sizeof(regval), 0);
447 Conversely, these functions (below) convert the value found in a
448 gdbserv_reg struct into an array of bytes:
450 void gdbserv_be_bytes_from_reg (struct gdbserv *gdbserv,
453 const struct gdbserv_reg *reg,
456 void gdbserv_le_bytes_from_reg (struct gdbserv *gdbserv,
459 const struct gdbserv_reg *reg,
462 void gdbserv_host_bytes_from_reg (struct gdbserv *gdbserv,
465 const struct gdbserv_reg *reg,
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.
475 Memory Related Callbacks
476 ------------------------
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.
483 Here are the thread aware versions of the memory callbacks:
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);
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.
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.
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.
507 Here are the non-thread-aware memory callbacks:
509 long (*get_mem) (struct gdbserv *, struct gdbserv_reg *addr, void *data,
511 long (*set_mem) (struct gdbserv *, struct gdbserv_reg *addr, void *data,
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
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
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.
531 General Query Packets / General Set Packets
532 -------------------------------------------
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
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.
547 When a unrecognized 'q' packet is received from the client, the
548 ``process_get_gen'' method is called. Here's the prototype:
550 void (*process_get_gen) (struct gdbserv *);
552 When any 'Q' packet is received from the client, the ``process_set_gen''
553 method is called. Here's the prototype:
555 void (*process_set_gen) (struct gdbserv *);
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:
562 void (*process_rcmd) (struct gdbserv *, const char *cmd,
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
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):
575 int gdbserv_input_string_match (struct gdbserv *gdbserv,
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.
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():
588 int gdbserv_input_hex_long (struct gdbserv *gdbserv, long *val);
590 int gdbserv_input_hex_ulong (struct gdbserv *gdbserv,
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.
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:
600 void gdbserv_output_string (struct gdbserv *gdbserv, const char *buf);
602 void gdbserv_output_string_as_bytes (struct gdbserv *gdbserv,
605 void gdbserv_output_bytes (struct gdbserv *gdbserv, const char *buf,
606 unsigned sizeof_buf);
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.
614 There exist several other "gdbserv_input_" and "gdb_serv_output_"
615 prefixed functions. Declarations for these may be found in
618 Callback for Setting Program Arguments
619 --------------------------------------
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
625 void (*process_set_args) (struct gdbserv *);
627 Notice that the library does not decode the arguments. Suitable calls
628 to the various "gdbserv_input_" functions must be called to parse
631 Callback for setting the PC
632 ---------------------------
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:
638 void (*process_set_pc) (struct gdbserv *, const struct gdbserv_reg *val);
640 The ``val'' parameter species the PC value to set.
642 Callback for Flushing the Instruction Cache
643 -------------------------------------------
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.
650 void (*flush_i_cache) (struct gdbserv *);
652 Signal Related Callbacks
653 ------------------------
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:
661 int (*process_signal) (struct gdbserv *, int sigval);
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:
669 void (*sigkill_program) (struct gdbserv *);
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.
675 Target State/Control Callbacks
676 --------------------------------
678 The ``exit_program'' callback is invoked when a 'k' (kill) packet is
679 received from the client. It's prototype is as follows:
681 void (*exit_program) (struct gdbserv *);
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:
691 void (*break_program) (struct gdbserv *);
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:
698 int (*reset_program) (struct gdbserv *);
699 void (*restart_program) (struct gdbserv *);
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:
712 void (*singlestep_thread) (struct gdbserv *, struct gdbserv_thread *,
713 const struct gdbserv_reg *signnal);
714 void (*singlestep_program) (struct gdbserv *);
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:
721 void (*cyclestep_thread) (struct gdbserv *, struct gdbserv_thread *,
722 const struct gdbserv_reg *signnal);
723 void (*cyclestep_program) (struct gdbserv *);
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:
735 void (*continue_thread) (struct gdbserv *, struct gdbserv_thread *,
736 const struct gdbserv_reg *signnal);
737 void (*continue_program) (struct gdbserv *);
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:
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);
758 The return status codes (of type enum gdbserv_target_rc) for these methods
759 may be one of the following:
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.
771 The ``type'' parameter for these methods (of type enum gdbserv_target_bp)
772 may be one of the following:
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.
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.
786 Thread Related Callbacks
787 ------------------------
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:
795 char *(*thread_info) (struct gdbserv *, struct gdbserv_thread *thread);
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:
802 char *(*thread_info) (struct gdbserv *, struct gdbserv_thread *thread);
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:
812 int (*thread_lookup_by_id) (struct gdbserv *,
813 const struct gdbserv_reg *id,
814 struct gdbserv_thread **thread);
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:
827 struct gdbserv_thread *(*thread_next) (struct gdbserv *,
828 struct gdbserv_thread *thread_last);
830 Unknown Packet Callback
831 -----------------------
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:
837 void (*process_target_packet) (struct gdbserv *);
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.
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:
853 void (*detach) (struct gdbserv *, struct gdbserv_target *target);