rda/HOWTO.old

   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>
   6
   7 Introduction
   8 ------------
   9
  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.
  15
  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.
  20
  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.
  26
  27 Architecture
  28 ------------
  29
  30 The following diagram shows the components of RDA.
  31
  32         (GDB) <---"remote"---> CLIENT <--> SERVER <--> TARGET
  33        -------                 ------------------------------
  34      The client.                         The server.
  35
  36 Where:
  37
  38         CLIENT  Provides the raw interface between
  39                 GDB and the internal SERVER
  40                 mechanism.
  41
  42                 The client passes on any data relevant
  43                 to the server.  The SERVER presents
  44                 CLIENT with raw output to be returned
  45                 to GDB.
  46
  47         SERVER  Implements the state-machine that
  48                 is capable of decoding / processing
  49                 various GDB remote protocol requests.
  50
  51         TARGET  The embedded system proper.  SERVER
  52                 passes decoded requests onto the TARGET
  53                 while TARGET notifies the SERVER of any
  54                 target state changes.
  55
  56
  57 Looking at SERVER in more detail, that component consists of three sub
  58 components INPUT, OUTPUT and STATE.  Visually:
  59
  60                                      .------------ fromtarget_*
  61                                     \|/
  62         fromclient_*   -> INPUT -> STATE (M/C) -> target->*
  63                            /|\         |
  64                             |
  65                            \|/         |
  66         client->write  <- OUTPUT <----'
  67
  68 Where:
  69
  70         INPUT   Filters the raw input stream from the client
  71                 breaking it up into complete packets and
  72                 passing them onto STATE.
  73
  74                 This component co-operates with OUTPUT for
  75                 the ACK/NAK of input packets.
  76
  77         OUTPUT  Wraps up and then passes onto the client
  78                 raw output packets ready for transmission
  79                 on the output stream.
  80
  81                 This component  co-operates with INPUT for
  82                 the ACK/NAK of output packets.
  83
  84         STATE   The state machine proper.
  85
  86
  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.
  90
  91
  92 Adding the target dependent code
  93 --------------------------------
  94
  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.
  99
 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).
 105
 106
 107 Handling the connection:
 108
 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).
 116
 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.
 120
 121 You must provide a routine like (please see the precise API in the header file
 122 include/gdbserv-client.h):
 123
 124 typedef struct gdbserv_target *(gdbserv_target_attach) (struct gdbserv *gdbserv,                                                        void *attatch_data);
 125
 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.
 129
 130 The recommended way to create your gdbserv_target object is:
 131
 132 struct gdbserv_target *gdbtarget = malloc (sizeof (struct gdbserv_target));
 133 memset (gdbtarget, 0, sizeof (*gdbtarget));
 134 gdbtarget->process_get_gen = process_get_gen;
 135 (...)
 136
 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.
 139
 140
 141 Handling target events:
 142
 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
 150 calls later.
 151
 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
 157 polling code.
 158
 159
 160 The main loop:
 161
 162 At some point you must get things going by:
 163
 164 1) looking for connection requests from gdb and
 165 2) causing remote protocol commands to be read from the input port (socket).
 166
 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.
 172
 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.
 177
 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.
 181
 182
 183 The callbacks:
 184
 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.
 192
 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.
 195
 196 Have fun!
 197
 198
 199
 200 Appendix
 201 --------
 202
 203 SCENARIOS
 204
 205
 206 ATTACH: Creating a connection into the server/target.
 207
 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.
 211
 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.
 216
 217         struct gdbserv_client *client;
 218         ...
 219         client->write = client_write_to_output_port;
 220         client->data = ... local state ...
 221         server = gdbserv_fromclient_attach (client, to_target_attach,
 222                                             target_data);
 223
 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.
 227
 228 Finally gdbserv_fromclient_attach() returns a SERVER state object that
 229 should be passed to all client->server calls.
 230
 231
 232 DATA-IN: Data being sent to the client from the remote GDB
 233
 234 The client passes the data vis:
 235
 236         len = read (fd, buf, sizeof (buf));
 237         gdbserv_fromclient_data (server, buf, len);
 238
 239
 240 BREAK-IN: Request to stop sent to the client from the remote GDB
 241
 242 The client passes the request to SERVER:
 243
 244         server.c:
 245
 246         volatile
 247         break_handler ()
 248         {
 249           gdbserv_fromclient_break (server);
 250         }
 251
 252 If the target is currently running, the server will in turn pass the
 253 request onto the TARGET:
 254
 255         ->target->break_program (server);
 256
 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.
 259
 260 Later, once the target has halted, the SERVER is notified of the state
 261 change vis:
 262
 263         target.c:
 264
 265           gdbserv_fromtarget_break (server);
 266
 267
 268 NB: Often ``break'' is sent across the stream interface as a special
 269 character sequence.
 270
 271 FIXME: gdbserv-input.c should be able to parse such character
 272 sequences.
 273
 274
 275 DATA-OUT: Data for the remote GDB from SERVER
 276
 277 The ``write'' function specified in the ``struct gdbserv_client''
 278 object is called.
 279
 280
 281 DETACH: Remote GDB disconnects from the SERVER
 282
 283 The CLIENT notifies SERVER via the gdbserv_fromclient_detach() call.
 284
 285
 286 HARD-RESET:  A hard reset is performed on a serial board.
 287
 288 Assuming a standalone system, the client/target side sequences would
 289 be performed:
 290
 291         /* create the server */
 292         server = gdbserv_fromclient_attach (...);
 293         /* notify the server that the target was just reset */
 294         gdbserv_fromtarget_reset (server);
 295
 296
 297 WRITE-MEMORY: GDB sends the server a write-memory packet.
 298
 299 Eventually SERVER passes the request onto the TARGET with the call:
 300
 301         ->target->process_set_mem (server, addr, len);
 302
 303 where ADDR and LEN contain the uninterpreted address/length of the
 304 data to follow.  target_process_set_mem() might be implemented as:
 305
 306         long long addr;
 307         long int;
 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);
 312
 313
 314 READ-MEMORY: GDB requests memory from the target.
 315
 316 Eventually target_process_get_mem() function is called.  An
 317 implementation may look like:
 318
 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);
 323
 324
 325 TARGET-RESUME: GDB requests that the target resume execution.
 326
 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.
 330
 331 --
 332