1 How to implement a stub or server using RDA (Red Hat Debug Agent and library).
2 ==================================================
3 Andrew Cagney <cagney@cygnus.com>
4 Fernando Nasser <fnasser@cygnus.com>
5 Frank Eigler <fche@cygnus.com>
10 This is the implementation of a server for the gdb remote protocol.
11 It is available as a host library that provides most of the common code
12 required. By adding a relatively small amount of target dependent code,
13 one can build a server that allows gdb to connect to that target using
14 the gdb "target remote" command.
16 Gdb connects to this server through a TCP/IP connection. The server
17 waits for a connection from GDB by listening to a non-restricted TCP port.
18 Anyone with GDB (or even telnet) network connectivity to the machine
19 running the server can initiate a connection to it.
21 Note: The user of this software is advised to ensure
22 that access to the TCP port being used is restricted to
23 secure siblings. For instance, the user may need to take
24 action that ensures that `The Internet' is not able to access
25 the TCP port being used.
30 The following diagram shows the components of RDA.
32 (GDB) <---"remote"---> CLIENT <--> SERVER <--> TARGET
33 ------- ------------------------------
34 The client. The server.
38 CLIENT Provides the raw interface between
39 GDB and the internal SERVER
42 The client passes on any data relevant
43 to the server. The SERVER presents
44 CLIENT with raw output to be returned
47 SERVER Implements the state-machine that
48 is capable of decoding / processing
49 various GDB remote protocol requests.
51 TARGET The embedded system proper. SERVER
52 passes decoded requests onto the TARGET
53 while TARGET notifies the SERVER of any
57 Looking at SERVER in more detail, that component consists of three sub
58 components INPUT, OUTPUT and STATE. Visually:
60 .------------ fromtarget_*
62 fromclient_* -> INPUT -> STATE (M/C) -> target->*
66 client->write <- OUTPUT <----'
70 INPUT Filters the raw input stream from the client
71 breaking it up into complete packets and
72 passing them onto STATE.
74 This component co-operates with OUTPUT for
75 the ACK/NAK of input packets.
77 OUTPUT Wraps up and then passes onto the client
78 raw output packets ready for transmission
81 This component co-operates with INPUT for
82 the ACK/NAK of output packets.
84 STATE The state machine proper.
87 The Appendix provides various scenarios showing in some detail how typical
88 operations are handled by these components. It may be convenient to read the
89 next section first before turning to the Appendix.
92 Adding the target dependent code
93 --------------------------------
95 In the following discussion, assume your debugger (gdb) is using
96 the remote protocol to communicate with the code you are building here.
97 The "target" is a simulator, hardware device, board, program or whatever you
98 are interfacing to with your stub/server.
100 The library provides gdbsocket_*() and gdbserv_fromtarget_*() routines that
101 must be called and requires you to set a series of callback routines.
102 You make these callbacks known/available to the library by filling the entries
103 of a "gdbserv_target" object. You must also provide an extra function that
104 will be invoked when a new connection is detected on the input port (a socket).
107 Handling the connection:
109 The server is capable of handling several connections (named, sessions)
110 simultaneously. This is possible because each session data is kept on
111 an instance of a GDBSERV object. A routine called gdbserv_fromclient_attach()
112 is called when a connection request is received by the socket.
113 If the connection is accepted, a new instance of a GDBSERV object is returned,
114 otherwise NULL is returned indicating that it has been rejected (a EOF will be
115 sensed on the other end).
117 The server will, in turn, pass the request onto the target. The target can
118 either reject the connection (returning NULL) or accept the connection
119 (returning a target object). That is where you come in.
121 You must provide a routine like (please see the precise API in the header file
122 include/gdbserv-client.h):
124 typedef struct gdbserv_target *(gdbserv_target_attach) (struct gdbserv *gdbserv, void *attatch_data);
126 This will be called by the server to notify that the client has initiated a
127 connection. You must return a GDBSERV_TARGET struct for the session or null
128 if your target has rejected the connection.
130 The recommended way to create your gdbserv_target object is:
132 struct gdbserv_target *gdbtarget = malloc (sizeof (struct gdbserv_target));
133 memset (gdbtarget, 0, sizeof (*gdbtarget));
134 gdbtarget->process_get_gen = process_get_gen;
137 If you initialize it like this, you will not have to change your code even if
138 new entries are added to this struct.
141 Handling target events:
143 The fromtarget_* routines may be called by your target. Before you
144 despair, let me tell you that they are only three: reset, break and
145 exit. They indicate that some interesting condition happened in your
146 target that requires debugger attention. Reset and exit are quite
147 obvious and break is for everything else. These routines must *not*
148 be called from within a gdbserv_target callback function, so it may be
149 necessary for your target to set some flags to signal state change
152 If your target is a simulator, call those when the corresponding
153 condition arises in your simulated target. If it is a board, it will
154 probably be called from your ISRs. A special case occurs if your
155 target is a device that has to be polled in order to detect state
156 changes. If this is the case, you will call these routines from the
162 At some point you must get things going by:
164 1) looking for connection requests from gdb and
165 2) causing remote protocol commands to be read from the input port (socket).
167 You must (repeatedly) call a function called gdbloop_poll(). This
168 will be in your main loop. If it is a server it will be in your
169 main() function. If it is a simulator that also accepts input from
170 other sources, it will have to be added to the existing main loop. If
171 it is a board, it will probably be called from the timer ISR.
173 Before doing that you must initialize your socket interface. Look in
174 the main() routine of the sample program to see what to call. When
175 calling gdbsocket_startup() you must give the address of the callback
176 that handles connection requests for your target.
178 If your target has to be polled for state changes, you will have to alternate
179 calls to poll() and to check your target status. As I mentioned before,
180 your status checking routine must call the appropriate fromtarget_* function.
185 All that is left now is to implement your callbacks, which are, directly or
186 indirectly, called as a result of a remote protocol packet being received and
187 processed by some fromclient_* routine. I will assume that the remote
188 protocol packets are known. If not, please refer to the "Remote Protocol"
189 section of the gdb manual. There you will find how your target should be
190 affected by each packet and what the response should be. It is always
191 useful to look at what some other remote targets do as well.
193 The list of all callbacks with the situation in which they are invoked can be
194 found in the header file lib/gdbserv-target.h.
206 ATTACH: Creating a connection into the server/target.
208 Client receives a connect request from the remote GDB. A socket
209 interface would see this as an attach. For Cygmon this is the
210 ``transfer'' command.
212 The client creates an output object (struct gdbserv_client) and passes
213 that and the target side attach function onto GDBSERV. SERVER will
214 then initialize itself and call ``to_target_attach'' for final
215 approval of the request.
217 struct gdbserv_client *client;
219 client->write = client_write_to_output_port;
220 client->data = ... local state ...
221 server = gdbserv_fromclient_attach (client, to_target_attach,
224 The target_attach() function is expected to either create and return a
225 gdbserv_target object or return NULL. The latter indicates that the
226 connection request is rejected.
228 Finally gdbserv_fromclient_attach() returns a SERVER state object that
229 should be passed to all client->server calls.
232 DATA-IN: Data being sent to the client from the remote GDB
234 The client passes the data vis:
236 len = read (fd, buf, sizeof (buf));
237 gdbserv_fromclient_data (server, buf, len);
240 BREAK-IN: Request to stop sent to the client from the remote GDB
242 The client passes the request to SERVER:
249 gdbserv_fromclient_break (server);
252 If the target is currently running, the server will in turn pass the
253 request onto the TARGET:
255 ->target->break_program (server);
257 and the target will record the break request and then return control
258 back to the SERVER. The server returning control to the client.
260 Later, once the target has halted, the SERVER is notified of the state
265 gdbserv_fromtarget_break (server);
268 NB: Often ``break'' is sent across the stream interface as a special
271 FIXME: gdbserv-input.c should be able to parse such character
275 DATA-OUT: Data for the remote GDB from SERVER
277 The ``write'' function specified in the ``struct gdbserv_client''
281 DETACH: Remote GDB disconnects from the SERVER
283 The CLIENT notifies SERVER via the gdbserv_fromclient_detach() call.
286 HARD-RESET: A hard reset is performed on a serial board.
288 Assuming a standalone system, the client/target side sequences would
291 /* create the server */
292 server = gdbserv_fromclient_attach (...);
293 /* notify the server that the target was just reset */
294 gdbserv_fromtarget_reset (server);
297 WRITE-MEMORY: GDB sends the server a write-memory packet.
299 Eventually SERVER passes the request onto the TARGET with the call:
301 ->target->process_set_mem (server, addr, len);
303 where ADDR and LEN contain the uninterpreted address/length of the
304 data to follow. target_process_set_mem() might be implemented as:
308 gdbserv_reg_to_ulonglong (server, reg_addr, &addr);
309 gdbserv_reg_to_ulong (server, reg_len, &len);
310 /* just blat local memory */
311 len = gdbserv_input_bytes (server, addr, len);
314 READ-MEMORY: GDB requests memory from the target.
316 Eventually target_process_get_mem() function is called. An
317 implementation may look like:
319 gdbserv_reg_to_ulonglong (gdbserv, reg_addr, &addr);
320 gdbserv_reg_to_ulong (gdbserv, reg_len, &len);
321 /* assume we're reading raw memory from the local mc */
322 gdbserv_output_bytes (gdbserv, addr, len);
325 TARGET-RESUME: GDB requests that the target resume execution.
327 Eventually ->target->continue_program() is called. That function
328 should record the request and then wait for SERVER to exit before
329 actually continuing the target.