| 1 | _dnl__ -*- Texinfo -*- |
| 2 | _dnl__ Copyright (c) 1990 1991 1992 Free Software Foundation, Inc. |
| 3 | _dnl__ This file is part of the source for the GDB manual. |
| 4 | _dnl__ M4 FRAGMENT $Id$ |
| 5 | _dnl__ This text diverted to "Remote Debugging" section in general case; |
| 6 | _dnl__ however, if we're doing a manual specifically for one of these, it |
| 7 | _dnl__ belongs up front (in "Getting In and Out" chapter). |
| 8 | @node Remote Serial |
| 9 | @subsection The _GDBN__ remote serial protocol |
| 10 | |
| 11 | @cindex remote serial debugging, overview |
| 12 | To debug a program running on another machine (the debugging |
| 13 | @dfn{target} machine), you must first arrange for all the usual |
| 14 | prerequisites for the program to run by itself. For example, for a C |
| 15 | program, you need |
| 16 | |
| 17 | @enumerate |
| 18 | @item |
| 19 | A startup routine to set up the C runtime environment; these usually |
| 20 | have a name like @file{crt0}. The startup routine may be supplied by |
| 21 | your hardware supplier, or you may have to write your own. |
| 22 | |
| 23 | @item |
| 24 | You probably need a C subroutine library to support your program's |
| 25 | subroutine calls, notably managing input and output. |
| 26 | |
| 27 | @item |
| 28 | A way of getting your program to the other machine---for example, a |
| 29 | download program. These are often supplied by the hardware |
| 30 | manufacturer, but you may have to write your own from hardware |
| 31 | documentation. |
| 32 | @end enumerate |
| 33 | |
| 34 | The next step is to arrange for your program to use a serial port to |
| 35 | communicate with the machine where _GDBN__ is running (the @dfn{host} |
| 36 | machine). In general terms, the scheme looks like this: |
| 37 | |
| 38 | @table @emph |
| 39 | @item On the host, |
| 40 | _GDBN__ already understands how to use this protocol; when everything |
| 41 | else is set up, you can simply use the @samp{target remote} command |
| 42 | (@pxref{Targets,,Specifying a Debugging Target}). |
| 43 | |
| 44 | @item On the target, |
| 45 | you must link with your program a few special-purpose subroutines that |
| 46 | implement the _GDBN__ remote serial protocol. The file containing these |
| 47 | subroutines is called a @dfn{debugging stub}. |
| 48 | @end table |
| 49 | |
| 50 | The debugging stub is specific to the architecture of the remote |
| 51 | machine; for example, use @file{sparc-stub.c} to debug programs on |
| 52 | @sc{sparc} boards. |
| 53 | |
| 54 | @cindex remote serial stub list |
| 55 | These working remote stubs are distributed with _GDBN__: |
| 56 | |
| 57 | @c FIXME! verify these... |
| 58 | @table @code |
| 59 | @item sparc-stub.c |
| 60 | @kindex sparc-stub.c |
| 61 | For @sc{sparc} architectures. |
| 62 | |
| 63 | @item m68-stub.c |
| 64 | @kindex m68-stub.c |
| 65 | For Motorola 680x0 architectures. |
| 66 | |
| 67 | @item i36-stub.c |
| 68 | @kindex i36-stub.c |
| 69 | For Intel 386 and compatible architectures. |
| 70 | @end table |
| 71 | |
| 72 | The @file{README} file in the _GDBN__ distribution may list other |
| 73 | recently added stubs. |
| 74 | |
| 75 | @menu |
| 76 | * stub contents:: What the stub can do for you |
| 77 | * bootstrapping:: What you must do for the stub |
| 78 | * debug session:: Putting it all together |
| 79 | * protocol:: Outline of the communication protocol |
| 80 | @end menu |
| 81 | |
| 82 | @node stub contents |
| 83 | @subsubsection What the stub can do for you |
| 84 | |
| 85 | @cindex remote serial stub |
| 86 | The debugging stub for your architecture supplies these three |
| 87 | subroutines: |
| 88 | |
| 89 | @table @code |
| 90 | @item handle_exception |
| 91 | @kindex handle_exception |
| 92 | @cindex remote serial stub, main routine |
| 93 | This is the central workhorse, but your program never calls it |
| 94 | explicitly---the setup code arranges for @code{handle_exception} to |
| 95 | run when a trap is triggered. |
| 96 | |
| 97 | @code{handle_exception} takes control when your program stops during |
| 98 | execution (for example, on a breakpoint), and mediates communications |
| 99 | with _GDBN__ on the host machine. This is where the communications |
| 100 | protocol is implemented; @code{handle_exception} acts as the _GDBN__ |
| 101 | representative on the target machine; it begins by sending summary |
| 102 | information on the state of your program, then continues to execute, |
| 103 | retrieving and transmitting any information _GDBN__ needs, until you |
| 104 | execute a _GDBN__ command that makes your program resume; at that point, |
| 105 | @code{handle_exception} returns control to your own code on the target |
| 106 | machine. |
| 107 | |
| 108 | @item set_debug_traps |
| 109 | @kindex set_debug_traps |
| 110 | @cindex remote serial stub, initialization |
| 111 | You must call this subroutine explicitly near the beginning of your |
| 112 | program. This is the routine that arranges to transfer control to |
| 113 | @code{handle_exception} when your program stops. |
| 114 | |
| 115 | @item breakpoint |
| 116 | @cindex @code{breakpoint} subroutine, remote |
| 117 | Use this auxiliary subroutine to make your program contain a |
| 118 | breakpoint. Depending on the particular situation, this may be the only |
| 119 | way for _GDBN__ to get control. For instance, if your target |
| 120 | machine has some sort of interrupt button, you won't need to call this; |
| 121 | pressing the interrupt button will transfer control to |
| 122 | @code{handle_exception}---in efect, to _GDBN__. On some machines, |
| 123 | simply receiving characters on the serial port may also trigger a trap; |
| 124 | again, in that situation, you don't need to call @code{breakpoint} from |
| 125 | your own program---simply running @samp{target remote} from the host |
| 126 | _GDBN__ session will get control. |
| 127 | |
| 128 | Call @code{breakpoint} if none of these is true, or if you simply want |
| 129 | to make certain your program stops at a predetermined point for the |
| 130 | start of your debugging session. |
| 131 | |
| 132 | @quotation |
| 133 | @emph{Warning:} when you set a breakpoint using this subroutine, it's a |
| 134 | little harder than usual to restart your program afterwards---because if |
| 135 | you simply @code{continue}, you will immediately run into the line of |
| 136 | your program that sets the breakpoint! |
| 137 | |
| 138 | To get past this, adjust the program counter manually to get past the |
| 139 | current instruction before issuing the @code{continue} command. For example, |
| 140 | |
| 141 | @example |
| 142 | (_GDBP__) p $pc = 4+$pc |
| 143 | |
| 144 | FIXME!!! Stu, I suspect I don't have this quite right. |
| 145 | Please supply the right incantation... presumably the |
| 146 | constant depends on instruction width, BTW? |
| 147 | Sample output would be nice too, so I don't have to make |
| 148 | up a ridiculous number. |
| 149 | |
| 150 | Nothing simpler works, right? Frinstance, an ignore count on the |
| 151 | continue would just keep stopping at the same place too? |
| 152 | |
| 153 | Whatta bout $pc++ ---does GDB know the instruction width as a "type" size? |
| 154 | |
| 155 | (_GDBP__) continue |
| 156 | @end example |
| 157 | @end quotation |
| 158 | @end table |
| 159 | |
| 160 | @node bootstrapping |
| 161 | @subsubsection What you must do for the stub |
| 162 | |
| 163 | @cindex remote stub, support routines |
| 164 | The debugging stubs that come with _GDBN__ are set up for a particular |
| 165 | chip architecture, but they have no information about the rest of your |
| 166 | debugging target machine. To allow the stub to work, you must supply |
| 167 | three special low-level subroutines, and make sure one library routine |
| 168 | is available. |
| 169 | |
| 170 | @table @code |
| 171 | @item int getDebugChar() |
| 172 | @kindex getDebugChar |
| 173 | Write this subroutine to read a single character from the serial port. |
| 174 | It may be identical to @code{getchar} for your target system; a |
| 175 | different name is used to allow you to distinguish the two if you wish. |
| 176 | |
| 177 | @item void putDebugChar(int) |
| 178 | @kindex putDebugChar |
| 179 | Write this subroutine to write a single character to the serial port. |
| 180 | It may be identical to @code{putchar} for your target system; a |
| 181 | different name is used to allow you to distinguish the two if you wish. |
| 182 | |
| 183 | @item void flush_i_cache() |
| 184 | @kindex flush_i_cache |
| 185 | Write this subroutine to flush the instruction cache, if any, on your |
| 186 | target machine. If there is no instruction cache, this subroutine may |
| 187 | be a no-op. |
| 188 | |
| 189 | On target machines that have instruction caches, _GDBN__ requires this |
| 190 | function to make certain that the state of your program is stable. |
| 191 | |
| 192 | @item void *memset(void *, int, int) |
| 193 | @kindex memset |
| 194 | This is the standard library function @code{memset} that sets an area of |
| 195 | memory to a known value. If you have one of the free versions of |
| 196 | @code{libc.a}, @code{memset} can be found there; otherwise, you must |
| 197 | either obtain it from your hardware manufacturer, or write your own. |
| 198 | @end table |
| 199 | |
| 200 | If you do not use the GNU C compiler, you may also need other standard |
| 201 | library subroutines; this will vary from one stub to another, but in |
| 202 | general the stubs are likely to use any of the common library |
| 203 | subroutines which @code{gcc} generates as inline code. |
| 204 | |
| 205 | |
| 206 | @node debug session |
| 207 | @subsubsection Putting it all together |
| 208 | |
| 209 | @cindex remote serial debugging summary |
| 210 | In summary, when your program is ready to debug, you must follow these |
| 211 | steps. |
| 212 | |
| 213 | @enumerate |
| 214 | @item |
| 215 | Make sure you have the supporting low-level routines: |
| 216 | @code{getDebugChar}, @code{putDebugChar}, @code{flush_i_cache}, |
| 217 | @code{memset}. |
| 218 | |
| 219 | @item |
| 220 | Insert these lines near the top of your program: |
| 221 | |
| 222 | @example |
| 223 | set_debug_traps(); |
| 224 | breakpoint(); |
| 225 | @end example |
| 226 | |
| 227 | @item |
| 228 | Compile and link together: your program, the _GDBN__ debugging stub for |
| 229 | your target architecture, and the supporting subroutines. |
| 230 | |
| 231 | @item |
| 232 | Make sure you have a serial connection between your target machine and |
| 233 | the _GDBN__ host, and identify the serial port used for this on the host. |
| 234 | |
| 235 | @item |
| 236 | Download your program to your target machine (or get it there by |
| 237 | whatever means the manufacturer provides), and start it. |
| 238 | |
| 239 | @item |
| 240 | To start remote debugging, run _GDBN__ on the host machine, and specify |
| 241 | as an executable file the program that is running in the remote machine. |
| 242 | This tells _GDBN__ how to find your program's symbols and the contents |
| 243 | of its pure text. |
| 244 | |
| 245 | Then establish communication using the @code{target remote} command. |
| 246 | Its argument is the name of the device you're using to control the |
| 247 | target machine. For example: |
| 248 | |
| 249 | @example |
| 250 | target remote /dev/ttyb |
| 251 | @end example |
| 252 | |
| 253 | @noindent |
| 254 | if the serial line is connected to the device named @file{/dev/ttyb}. |
| 255 | @ignore |
| 256 | @c this is from the old text, but it doesn't seem to make sense now that I've |
| 257 | @c seen an example... pesch 4sep1992 |
| 258 | This will stop the remote machine if it is not already stopped. |
| 259 | @end ignore |
| 260 | |
| 261 | @end enumerate |
| 262 | |
| 263 | Now you can use all the usual commands to examine and change data and to |
| 264 | step and continue the remote program. |
| 265 | |
| 266 | To resume the remote program and stop debugging it, use the @code{detach} |
| 267 | command. |
| 268 | |
| 269 | @node protocol |
| 270 | @subsubsection Outline of the communication protocol |
| 271 | |
| 272 | @cindex debugging stub, example |
| 273 | @cindex remote stub, example |
| 274 | @cindex stub example, remote debugging |
| 275 | The stub files provided with _GDBN__ implement the target side of the |
| 276 | communication protocol, and the _GDBN__ side is implemented in the |
| 277 | _GDBN__ source file @file{remote.c}. Normally, you can simply allow |
| 278 | these subroutines to communicate, and ignore the details. (If you're |
| 279 | implementing your own stub file, you can still ignore the details: start |
| 280 | with one of the existing stub files. @file{sparc-stub.c} is the best |
| 281 | organized, and therefore the easiest to read.) |
| 282 | |
| 283 | However, there may be occasions when you need to know something about |
| 284 | the protocol---for example, if there is only one serial port to your |
| 285 | target machine, you might want your program to do something special if |
| 286 | it recognizes a packet meant for _GDBN__. |
| 287 | |
| 288 | @cindex protocol, _GDBN__ remote serial |
| 289 | @cindex serial protocol, _GDBN__ remote |
| 290 | @cindex remote serial protocol |
| 291 | All _GDBN__ commands and responses (other than acknowledgements, which |
| 292 | are single characters) are sent as a packet which includes a |
| 293 | checksum. A packet is introduced with the character @samp{$}, and ends |
| 294 | with the character @samp{#} followed by a two-digit checksum: |
| 295 | |
| 296 | @example |
| 297 | $@var{packet info}#@var{checksum} |
| 298 | @end example |
| 299 | |
| 300 | @cindex checksum, for _GDBN__ remote |
| 301 | @noindent |
| 302 | @var{checksum} is computed as the modulo 256 sum of the @var{packet |
| 303 | info} characters. |
| 304 | |
| 305 | When either the host or the target machine receives a packet, the first |
| 306 | response expected is an acknowledgement: a single character, either |
| 307 | @samp{+} (to indicate the package was received correctly) or @samp{-} |
| 308 | (to request retransmission). |
| 309 | |
| 310 | The host (_GDBN__) sends commands, and the target (the debugging stub |
| 311 | incorporated in your program) sends data in response. The target also |
| 312 | sends data when your program stops. |
| 313 | |
| 314 | Command packets are distinguished by their first character, which |
| 315 | identifies the kind of command. |
| 316 | |
| 317 | These are the commands currently supported: |
| 318 | |
| 319 | @table @code |
| 320 | @item g |
| 321 | Requests the values of CPU registers. |
| 322 | |
| 323 | @item G |
| 324 | Sets the values of CPU registers. |
| 325 | |
| 326 | @item m@var{addr},@var{count} |
| 327 | Read @var{count} bytes at location @var{addr}. |
| 328 | |
| 329 | @item M@var{addr},@var{count}:@dots{} |
| 330 | Write @var{count} bytes at location @var{addr}. |
| 331 | |
| 332 | @item c |
| 333 | @itemx c@var{addr} |
| 334 | Resume execution at the current address (or at @var{addr} if supplied). |
| 335 | |
| 336 | @item s |
| 337 | @itemx s@var{addr} |
| 338 | Step the target program for one instruction, from either the current |
| 339 | program counter or from @var{addr} if supplied. |
| 340 | |
| 341 | @item k |
| 342 | Kill the target program. |
| 343 | |
| 344 | @item ? |
| 345 | Report the most recent signal. To allow you to take advantage of the |
| 346 | _GDBN__ signal handling commands, one of the functions of the debugging |
| 347 | stub is to report CPU traps as the corresponding POSIX signal values. |
| 348 | @end table |
| 349 | |
| 350 | @kindex set remotedebug |
| 351 | @kindex show remotedebug |
| 352 | @cindex packets, reporting on stdout |
| 353 | @cindex serial connections, debugging |
| 354 | If you have trouble with the serial connection, you can use the command |
| 355 | @code{set remotedebug}. This makes _GDBN__ report on all packets sent |
| 356 | back and forth across the serial line to the remote machine. The |
| 357 | packet-debugging information is printed on the _GDBN__ standard output |
| 358 | stream. @code{set remotedebug off} turns it off, and @code{show |
| 359 | remotedebug} will show you its current state. |
| 360 | |
| 361 | |
| 362 | _if__(_I960__) |
| 363 | @node i960-Nindy Remote |
| 364 | @subsection _GDBN__ with a Remote i960 (Nindy) |
| 365 | |
| 366 | @cindex Nindy |
| 367 | @cindex i960 |
| 368 | @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When |
| 369 | _GDBN__ is configured to control a remote Intel 960 using Nindy, you can |
| 370 | tell _GDBN__ how to connect to the 960 in several ways: |
| 371 | |
| 372 | @itemize @bullet |
| 373 | @item |
| 374 | Through command line options specifying serial port, version of the |
| 375 | Nindy protocol, and communications speed; |
| 376 | |
| 377 | @item |
| 378 | By responding to a prompt on startup; |
| 379 | |
| 380 | @item |
| 381 | By using the @code{target} command at any point during your _GDBN__ |
| 382 | session. @xref{Target Commands, ,Commands for Managing Targets}. |
| 383 | |
| 384 | @end itemize |
| 385 | |
| 386 | @menu |
| 387 | * Nindy Startup:: Startup with Nindy |
| 388 | * Nindy Options:: Options for Nindy |
| 389 | * Nindy reset:: Nindy Reset Command |
| 390 | @end menu |
| 391 | |
| 392 | @node Nindy Startup |
| 393 | @subsubsection Startup with Nindy |
| 394 | |
| 395 | If you simply start @code{_GDBP__} without using any command-line |
| 396 | options, you are prompted for what serial port to use, @emph{before} you |
| 397 | reach the ordinary _GDBN__ prompt: |
| 398 | |
| 399 | @example |
| 400 | Attach /dev/ttyNN -- specify NN, or "quit" to quit: |
| 401 | @end example |
| 402 | |
| 403 | @noindent |
| 404 | Respond to the prompt with whatever suffix (after @samp{/dev/tty}) |
| 405 | identifies the serial port you want to use. You can, if you choose, |
| 406 | simply start up with no Nindy connection by responding to the prompt |
| 407 | with an empty line. If you do this, and later wish to attach to Nindy, |
| 408 | use @code{target} (@pxref{Target Commands, ,Commands for Managing Targets}). |
| 409 | |
| 410 | @node Nindy Options |
| 411 | @subsubsection Options for Nindy |
| 412 | |
| 413 | These are the startup options for beginning your _GDBN__ session with a |
| 414 | Nindy-960 board attached: |
| 415 | |
| 416 | @table @code |
| 417 | @item -r @var{port} |
| 418 | Specify the serial port name of a serial interface to be used to connect |
| 419 | to the target system. This option is only available when _GDBN__ is |
| 420 | configured for the Intel 960 target architecture. You may specify |
| 421 | @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a |
| 422 | device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique |
| 423 | suffix for a specific @code{tty} (e.g. @samp{-r a}). |
| 424 | |
| 425 | @item -O |
| 426 | (An uppercase letter ``O'', not a zero.) Specify that _GDBN__ should use |
| 427 | the ``old'' Nindy monitor protocol to connect to the target system. |
| 428 | This option is only available when _GDBN__ is configured for the Intel 960 |
| 429 | target architecture. |
| 430 | |
| 431 | @quotation |
| 432 | @emph{Warning:} if you specify @samp{-O}, but are actually trying to |
| 433 | connect to a target system that expects the newer protocol, the connection |
| 434 | will fail, appearing to be a speed mismatch. _GDBN__ will repeatedly |
| 435 | attempt to reconnect at several different line speeds. You can abort |
| 436 | this process with an interrupt. |
| 437 | @end quotation |
| 438 | |
| 439 | @item -brk |
| 440 | Specify that _GDBN__ should first send a @code{BREAK} signal to the target |
| 441 | system, in an attempt to reset it, before connecting to a Nindy target. |
| 442 | |
| 443 | @quotation |
| 444 | @emph{Warning:} Many target systems do not have the hardware that this |
| 445 | requires; it only works with a few boards. |
| 446 | @end quotation |
| 447 | @end table |
| 448 | |
| 449 | The standard @samp{-b} option controls the line speed used on the serial |
| 450 | port. |
| 451 | |
| 452 | @c @group |
| 453 | @node Nindy reset |
| 454 | @subsubsection Nindy Reset Command |
| 455 | |
| 456 | @table @code |
| 457 | @item reset |
| 458 | @kindex reset |
| 459 | For a Nindy target, this command sends a ``break'' to the remote target |
| 460 | system; this is only useful if the target has been equipped with a |
| 461 | circuit to perform a hard reset (or some other interesting action) when |
| 462 | a break is detected. |
| 463 | @end table |
| 464 | @c @end group |
| 465 | _fi__(_I960__) |
| 466 | |
| 467 | _if__(_AMD29K__) |
| 468 | @node EB29K Remote |
| 469 | @subsection _GDBN__ with a Remote EB29K |
| 470 | |
| 471 | @cindex EB29K board |
| 472 | @cindex running 29K programs |
| 473 | |
| 474 | To use _GDBN__ from a Unix system to run programs on AMD's EB29K |
| 475 | board in a PC, you must first connect a serial cable between the PC |
| 476 | and a serial port on the Unix system. In the following, we assume |
| 477 | you've hooked the cable between the PC's @file{COM1} port and |
| 478 | @file{/dev/ttya} on the Unix system. |
| 479 | |
| 480 | @menu |
| 481 | * Comms (EB29K):: Communications Setup |
| 482 | * _GDBP__-EB29K:: EB29K cross-debugging |
| 483 | * Remote Log:: Remote Log |
| 484 | @end menu |
| 485 | |
| 486 | @node Comms (EB29K) |
| 487 | @subsubsection Communications Setup |
| 488 | |
| 489 | The next step is to set up the PC's port, by doing something like the |
| 490 | following in DOS on the PC: |
| 491 | |
| 492 | _0__@example |
| 493 | C:\> MODE com1:9600,n,8,1,none |
| 494 | _1__@end example |
| 495 | |
| 496 | @noindent |
| 497 | This example---run on an MS DOS 4.0 system---sets the PC port to 9600 |
| 498 | bps, no parity, eight data bits, one stop bit, and no ``retry'' action; |
| 499 | you must match the communications parameters when establishing the Unix |
| 500 | end of the connection as well. |
| 501 | @c FIXME: Who knows what this "no retry action" crud from the DOS manual may |
| 502 | @c mean? It's optional; leave it out? ---pesch@cygnus.com, 25feb91 |
| 503 | |
| 504 | To give control of the PC to the Unix side of the serial line, type |
| 505 | the following at the DOS console: |
| 506 | |
| 507 | _0__@example |
| 508 | C:\> CTTY com1 |
| 509 | _1__@end example |
| 510 | |
| 511 | @noindent |
| 512 | (Later, if you wish to return control to the DOS console, you can use |
| 513 | the command @code{CTTY con}---but you must send it over the device that |
| 514 | had control, in our example over the @file{COM1} serial line). |
| 515 | |
| 516 | From the Unix host, use a communications program such as @code{tip} or |
| 517 | @code{cu} to communicate with the PC; for example, |
| 518 | |
| 519 | @example |
| 520 | cu -s 9600 -l /dev/ttya |
| 521 | @end example |
| 522 | |
| 523 | @noindent |
| 524 | The @code{cu} options shown specify, respectively, the linespeed and the |
| 525 | serial port to use. If you use @code{tip} instead, your command line |
| 526 | may look something like the following: |
| 527 | |
| 528 | @example |
| 529 | tip -9600 /dev/ttya |
| 530 | @end example |
| 531 | |
| 532 | @noindent |
| 533 | Your system may define a different name where our example uses |
| 534 | @file{/dev/ttya} as the argument to @code{tip}. The communications |
| 535 | parameters, including which port to use, are associated with the |
| 536 | @code{tip} argument in the ``remote'' descriptions file---normally the |
| 537 | system table @file{/etc/remote}. |
| 538 | @c FIXME: What if anything needs doing to match the "n,8,1,none" part of |
| 539 | @c the DOS side's comms setup? cu can support -o (odd |
| 540 | @c parity), -e (even parity)---apparently no settings for no parity or |
| 541 | @c for character size. Taken from stty maybe...? John points out tip |
| 542 | @c can set these as internal variables, eg ~s parity=none; man stty |
| 543 | @c suggests that it *might* work to stty these options with stdin or |
| 544 | @c stdout redirected... ---pesch@cygnus.com, 25feb91 |
| 545 | |
| 546 | @kindex EBMON |
| 547 | Using the @code{tip} or @code{cu} connection, change the DOS working |
| 548 | directory to the directory containing a copy of your 29K program, then |
| 549 | start the PC program @code{EBMON} (an EB29K control program supplied |
| 550 | with your board by AMD). You should see an initial display from |
| 551 | @code{EBMON} similar to the one that follows, ending with the |
| 552 | @code{EBMON} prompt @samp{#}--- |
| 553 | |
| 554 | _0__@example |
| 555 | C:\> G: |
| 556 | |
| 557 | G:\> CD \usr\joe\work29k |
| 558 | |
| 559 | G:\USR\JOE\WORK29K> EBMON |
| 560 | Am29000 PC Coprocessor Board Monitor, version 3.0-18 |
| 561 | Copyright 1990 Advanced Micro Devices, Inc. |
| 562 | Written by Gibbons and Associates, Inc. |
| 563 | |
| 564 | Enter '?' or 'H' for help |
| 565 | |
| 566 | PC Coprocessor Type = EB29K |
| 567 | I/O Base = 0x208 |
| 568 | Memory Base = 0xd0000 |
| 569 | |
| 570 | Data Memory Size = 2048KB |
| 571 | Available I-RAM Range = 0x8000 to 0x1fffff |
| 572 | Available D-RAM Range = 0x80002000 to 0x801fffff |
| 573 | |
| 574 | PageSize = 0x400 |
| 575 | Register Stack Size = 0x800 |
| 576 | Memory Stack Size = 0x1800 |
| 577 | |
| 578 | CPU PRL = 0x3 |
| 579 | Am29027 Available = No |
| 580 | Byte Write Available = Yes |
| 581 | |
| 582 | # ~. |
| 583 | _1__@end example |
| 584 | |
| 585 | Then exit the @code{cu} or @code{tip} program (done in the example by |
| 586 | typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} will keep |
| 587 | running, ready for _GDBN__ to take over. |
| 588 | |
| 589 | For this example, we've assumed what is probably the most convenient |
| 590 | way to make sure the same 29K program is on both the PC and the Unix |
| 591 | system: a PC/NFS connection that establishes ``drive @code{G:}'' on the |
| 592 | PC as a file system on the Unix host. If you do not have PC/NFS or |
| 593 | something similar connecting the two systems, you must arrange some |
| 594 | other way---perhaps floppy-disk transfer---of getting the 29K program |
| 595 | from the Unix system to the PC; _GDBN__ will @emph{not} download it over the |
| 596 | serial line. |
| 597 | |
| 598 | @node _GDBP__-EB29K |
| 599 | @subsubsection EB29K cross-debugging |
| 600 | |
| 601 | Finally, @code{cd} to the directory containing an image of your 29K |
| 602 | program on the Unix system, and start _GDBN__---specifying as argument the |
| 603 | name of your 29K program: |
| 604 | |
| 605 | @example |
| 606 | cd /usr/joe/work29k |
| 607 | _GDBP__ myfoo |
| 608 | @end example |
| 609 | |
| 610 | Now you can use the @code{target} command: |
| 611 | |
| 612 | @example |
| 613 | target amd-eb /dev/ttya 9600 MYFOO |
| 614 | @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to |
| 615 | @c emphasize that this is the name as seen by DOS (since I think DOS is |
| 616 | @c single-minded about case of letters). ---pesch@cygnus.com, 25feb91 |
| 617 | @end example |
| 618 | |
| 619 | @noindent |
| 620 | In this example, we've assumed your program is in a file called |
| 621 | @file{myfoo}. Note that the filename given as the last argument to |
| 622 | @code{target amd-eb} should be the name of the program as it appears to DOS. |
| 623 | In our example this is simply @code{MYFOO}, but in general it can include |
| 624 | a DOS path, and depending on your transfer mechanism may not resemble |
| 625 | the name on the Unix side. |
| 626 | |
| 627 | At this point, you can set any breakpoints you wish; when you are ready |
| 628 | to see your program run on the 29K board, use the _GDBN__ command |
| 629 | @code{run}. |
| 630 | |
| 631 | To stop debugging the remote program, use the _GDBN__ @code{detach} |
| 632 | command. |
| 633 | |
| 634 | To return control of the PC to its console, use @code{tip} or @code{cu} |
| 635 | once again, after your _GDBN__ session has concluded, to attach to |
| 636 | @code{EBMON}. You can then type the command @code{q} to shut down |
| 637 | @code{EBMON}, returning control to the DOS command-line interpreter. |
| 638 | Type @code{CTTY con} to return command input to the main DOS console, |
| 639 | and type @kbd{~.} to leave @code{tip} or @code{cu}. |
| 640 | |
| 641 | @node Remote Log |
| 642 | @subsubsection Remote Log |
| 643 | @kindex eb.log |
| 644 | @cindex log file for EB29K |
| 645 | |
| 646 | The @code{target amd-eb} command creates a file @file{eb.log} in the |
| 647 | current working directory, to help debug problems with the connection. |
| 648 | @file{eb.log} records all the output from @code{EBMON}, including echoes |
| 649 | of the commands sent to it. Running @samp{tail -f} on this file in |
| 650 | another window often helps to understand trouble with @code{EBMON}, or |
| 651 | unexpected events on the PC side of the connection. |
| 652 | _fi__(_AMD29K__) |
| 653 | |
| 654 | _if__(_VXWORKS__) |
| 655 | @node VxWorks Remote |
| 656 | @subsection _GDBN__ and VxWorks |
| 657 | @cindex VxWorks |
| 658 | |
| 659 | _GDBN__ enables developers to spawn and debug tasks running on networked |
| 660 | VxWorks targets from a Unix host. Already-running tasks spawned from |
| 661 | the VxWorks shell can also be debugged. _GDBN__ uses code that runs on |
| 662 | both the UNIX host and on the VxWorks target. The program |
| 663 | @code{_GDBP__} is installed and executed on the UNIX host. |
| 664 | |
| 665 | The following information on connecting to VxWorks was current when |
| 666 | this manual was produced; newer releases of VxWorks may use revised |
| 667 | procedures. |
| 668 | |
| 669 | The remote debugging interface (RDB) routines are installed and executed |
| 670 | on the VxWorks target. These routines are included in the VxWorks library |
| 671 | @file{rdb.a} and are incorporated into the system image when source-level |
| 672 | debugging is enabled in the VxWorks configuration. |
| 673 | |
| 674 | @kindex INCLUDE_RDB |
| 675 | If you wish, you can define @code{INCLUDE_RDB} in the VxWorks |
| 676 | configuration file @file{configAll.h} to include the RDB interface |
| 677 | routines and spawn the source debugging task @code{tRdbTask} when |
| 678 | VxWorks is booted. For more information on configuring and remaking |
| 679 | _if__(_FSF__) |
| 680 | VxWorks, see the manufacturer's manual. |
| 681 | _fi__(_FSF__) |
| 682 | _if__(!_FSF__) |
| 683 | VxWorks, see the @cite{VxWorks Programmer's Guide}. |
| 684 | _fi__(!_FSF__) |
| 685 | |
| 686 | Once you have included the RDB interface in your VxWorks system image |
| 687 | and set your Unix execution search path to find _GDBN__, you are ready |
| 688 | to run _GDBN__. From your UNIX host, type: |
| 689 | |
| 690 | @smallexample |
| 691 | % _GDBP__ |
| 692 | @end smallexample |
| 693 | |
| 694 | _GDBN__ will come up showing the prompt: |
| 695 | |
| 696 | @smallexample |
| 697 | (_GDBP__) |
| 698 | @end smallexample |
| 699 | |
| 700 | @menu |
| 701 | * VxWorks connection:: Connecting to VxWorks |
| 702 | * VxWorks download:: VxWorks Download |
| 703 | * VxWorks attach:: Running Tasks |
| 704 | @end menu |
| 705 | |
| 706 | @node VxWorks connection |
| 707 | @subsubsection Connecting to VxWorks |
| 708 | |
| 709 | The _GDBN__ command @code{target} lets you connect to a VxWorks target on the |
| 710 | network. To connect to a target whose host name is ``@code{tt}'', type: |
| 711 | |
| 712 | @smallexample |
| 713 | (_GDBP__) target vxworks tt |
| 714 | @end smallexample |
| 715 | |
| 716 | _GDBN__ will display a message similar to the following: |
| 717 | |
| 718 | @smallexample |
| 719 | Attaching remote machine across net... Success! |
| 720 | @end smallexample |
| 721 | |
| 722 | _GDBN__ will then attempt to read the symbol tables of any object modules |
| 723 | loaded into the VxWorks target since it was last booted. _GDBN__ locates |
| 724 | these files by searching the directories listed in the command search |
| 725 | path (@pxref{Environment, ,Your Program's Environment}); if it fails |
| 726 | to find an object file, it will display a message such as: |
| 727 | |
| 728 | @smallexample |
| 729 | prog.o: No such file or directory. |
| 730 | @end smallexample |
| 731 | |
| 732 | This will cause the @code{target} command to abort. When this happens, |
| 733 | you should add the appropriate directory to the search path, with the |
| 734 | _GDBN__ command @code{path}, and execute the @code{target} command |
| 735 | again. |
| 736 | |
| 737 | @node VxWorks download |
| 738 | @subsubsection VxWorks Download |
| 739 | |
| 740 | @cindex download to VxWorks |
| 741 | If you have connected to the VxWorks target and you want to debug an |
| 742 | object that has not yet been loaded, you can use the _GDBN__ @code{load} |
| 743 | command to download a file from UNIX to VxWorks incrementally. The |
| 744 | object file given as an argument to the @code{load} command is actually |
| 745 | opened twice: first by the VxWorks target in order to download the code, |
| 746 | then by _GDBN__ in order to read the symbol table. This can lead to |
| 747 | problems if the current working directories on the two systems differ. |
| 748 | It is simplest to set the working directory on both systems to the |
| 749 | directory in which the object file resides, and then to reference the |
| 750 | file by its name, without any path. Thus, to load a program |
| 751 | @file{prog.o}, residing in @file{wherever/vw/demo/rdb}, on VxWorks type: |
| 752 | |
| 753 | @smallexample |
| 754 | -> cd "wherever/vw/demo/rdb" |
| 755 | @end smallexample |
| 756 | |
| 757 | On _GDBN__ type: |
| 758 | |
| 759 | @smallexample |
| 760 | (_GDBP__) cd wherever/vw/demo/rdb |
| 761 | (_GDBP__) load prog.o |
| 762 | @end smallexample |
| 763 | |
| 764 | _GDBN__ will display a response similar to the following: |
| 765 | |
| 766 | @smallexample |
| 767 | Reading symbol data from wherever/vw/demo/rdb/prog.o... done. |
| 768 | @end smallexample |
| 769 | |
| 770 | You can also use the @code{load} command to reload an object module |
| 771 | after editing and recompiling the corresponding source file. Note that |
| 772 | this will cause _GDBN__ to delete all currently-defined breakpoints, |
| 773 | auto-displays, and convenience variables, and to clear the value |
| 774 | history. (This is necessary in order to preserve the integrity of |
| 775 | debugger data structures that reference the target system's symbol |
| 776 | table.) |
| 777 | |
| 778 | @node VxWorks attach |
| 779 | @subsubsection Running Tasks |
| 780 | |
| 781 | @cindex running VxWorks tasks |
| 782 | You can also attach to an existing task using the @code{attach} command as |
| 783 | follows: |
| 784 | |
| 785 | @smallexample |
| 786 | (_GDBP__) attach @var{task} |
| 787 | @end smallexample |
| 788 | |
| 789 | @noindent |
| 790 | where @var{task} is the VxWorks hexadecimal task ID. The task can be running |
| 791 | or suspended when you attach to it. If running, it will be suspended at |
| 792 | the time of attachment. |
| 793 | _fi__(_VXWORKS__) |
| 794 | |
| 795 | _if__(_H8__) |
| 796 | @node Hitachi H8/300 Remote |
| 797 | @subsection _GDBN__ and the Hitachi H8/300 |
| 798 | _GDBN__ needs to know these things to talk to your H8/300: |
| 799 | |
| 800 | @enumerate |
| 801 | @item |
| 802 | that you want to use @samp{target hms}, the remote debugging |
| 803 | interface for the H8/300 (this is the default when |
| 804 | GDB is configured specifically for the H8/300); |
| 805 | |
| 806 | @item |
| 807 | what serial device connects your host to your H8/300 (the first serial |
| 808 | device available on your host is the default); |
| 809 | |
| 810 | @ignore |
| 811 | @c this is only for Unix hosts, not currently of interest. |
| 812 | @item |
| 813 | what speed to use over the serial device. |
| 814 | @end ignore |
| 815 | @end enumerate |
| 816 | |
| 817 | @kindex device |
| 818 | @cindex serial device for H8/300 |
| 819 | @ignore |
| 820 | @c only for Unix hosts |
| 821 | Use the special @code{gdb83} command @samp{device @var{port}} if you |
| 822 | need to explicitly set the serial device. The default @var{port} is the |
| 823 | first available port on your host. This is only necessary on Unix |
| 824 | hosts, where it is typically something like @file{/dev/ttya}. |
| 825 | |
| 826 | @kindex speed |
| 827 | @cindex serial line speed for H8/300 |
| 828 | @code{gdb83} has another special command to set the communications speed |
| 829 | for the H8/300: @samp{speed @var{bps}}. This command also is only used |
| 830 | from Unix hosts; on DOS hosts, set the line speed as usual from outside |
| 831 | GDB with the DOS @kbd{mode} command (for instance, @w{@samp{mode |
| 832 | com2:9600,n,8,1,p}} for a 9600 bps connection). |
| 833 | @end ignore |
| 834 | |
| 835 | _GDBN__ depends on an auxiliary terminate-and-stay-resident program |
| 836 | called @code{asynctsr} to communicate with the H8/300 development board |
| 837 | through a PC serial port. You must also use the DOS @code{mode} command |
| 838 | to set up the serial port on the DOS side. |
| 839 | |
| 840 | The following sample session illustrates the steps needed to start a |
| 841 | program under _GDBN__ control on your H8/300. The example uses a sample |
| 842 | H8/300 program called @file{t.x}. |
| 843 | |
| 844 | First hook up your H8/300 development board. In this example, we use a |
| 845 | board attached to serial port @code{COM2}; if you use a different serial |
| 846 | port, substitute its name in the argument of the @code{mode} command. |
| 847 | When you call @code{asynctsr}, the auxiliary comms program used by the |
| 848 | degugger, you give it just the numeric part of the serial port's name; |
| 849 | for example, @samp{asyncstr 2} below runs @code{asyncstr} on |
| 850 | @code{COM2}. |
| 851 | |
| 852 | @smallexample |
| 853 | (eg-C:\H8300\TEST) mode com2:9600,n,8,1,p |
| 854 | |
| 855 | Resident portion of MODE loaded |
| 856 | |
| 857 | COM2: 9600, n, 8, 1, p |
| 858 | |
| 859 | (eg-C:\H8300\TEST) asynctsr 2 |
| 860 | @end smallexample |
| 861 | |
| 862 | @quotation |
| 863 | @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with |
| 864 | @code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to |
| 865 | disable it, or even boot without it, to use @code{asynctsr} to control |
| 866 | your H8/300 board. |
| 867 | @end quotation |
| 868 | |
| 869 | Now that serial communications are set up, and the H8/300 is connected, |
| 870 | you can start up _GDBN__. Call @code{_GDBP__} with the name of your |
| 871 | program as the argument. @code{_GDBP__} prompts you, as usual, with the |
| 872 | prompt @samp{(_GDBP__)}. Use two special commands to begin your debugging |
| 873 | session: @samp{target hms} to specify cross-debugging to the Hitachi board, |
| 874 | and the @code{load} command to download your program to the board. |
| 875 | @code{load} displays the names of the |
| 876 | program's sections, and a @samp{*} for each 2K of data downloaded. (If |
| 877 | you want to refresh _GDBN__ data on symbols or on the executable file |
| 878 | without downloading, use the _GDBN__ commands @code{file} or |
| 879 | @code{symbol-file}. These commands, and @code{load} itself, are |
| 880 | described in @ref{Files,,Commands to Specify Files}.) |
| 881 | |
| 882 | @smallexample |
| 883 | (eg-C:\H8300\TEST) _GDBP__ t.x |
| 884 | GDB is free software and you are welcome to distribute copies |
| 885 | of it under certain conditions; type "show copying" to see |
| 886 | the conditions. |
| 887 | There is absolutely no warranty for GDB; type "show warranty" |
| 888 | for details. |
| 889 | GDB _GDB_VN__, Copyright 1992 Free Software Foundation, Inc... |
| 890 | (gdb) target hms |
| 891 | Connected to remote H8/300 HMS system. |
| 892 | (gdb) load t.x |
| 893 | .text : 0x8000 .. 0xabde *********** |
| 894 | .data : 0xabde .. 0xad30 * |
| 895 | .stack : 0xf000 .. 0xf014 * |
| 896 | @end smallexample |
| 897 | |
| 898 | At this point, you're ready to run or debug your program. From here on, |
| 899 | you can use all the usual _GDBN__ commands. The @code{break} command |
| 900 | sets breakpoints; the @code{run} command starts your program; |
| 901 | @code{print} or @code{x} display data; the @code{continue} command |
| 902 | resumes execution after stopping at a breakpoint. You can use the |
| 903 | @code{help} command at any time to find out more about _GDBN__ commands. |
| 904 | |
| 905 | Remember, however, that @emph{operating system} facilities aren't |
| 906 | available on your H8/300; for example, if your program hangs, you can't |
| 907 | send an interrupt---but you can press the @sc{reset} switch! |
| 908 | |
| 909 | Use the @sc{reset} button on the H8/300 board |
| 910 | @itemize @bullet |
| 911 | @item |
| 912 | to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has |
| 913 | no way to pass an interrupt signal to the H8/300); and |
| 914 | |
| 915 | @item |
| 916 | to return to the _GDBN__ command prompt after your program finishes |
| 917 | normally. The communications protocol provides no other way for _GDBN__ |
| 918 | to detect program completion. |
| 919 | @end itemize |
| 920 | |
| 921 | In either case, _GDBN__ will see the effect of a @sc{reset} on the |
| 922 | H8/300 board as a ``normal exit'' of your program. |
| 923 | _fi__(_H8__) |