OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [gdb/] [doc/] [gdb.info-8] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
2
 
3
INFO-DIR-SECTION Programming & development tools.
4
START-INFO-DIR-ENTRY
5
* Gdb: (gdb).                     The GNU debugger.
6
END-INFO-DIR-ENTRY
7
 
8
   This file documents the GNU debugger GDB.
9
 
10
   This is the Ninth Edition, April 2001, of `Debugging with GDB: the
11
GNU Source-Level Debugger' for GDB Version 20010707.
12
 
13
   Copyright (C)
14
1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
15
Free Software Foundation, Inc.
16
 
17
   Permission is granted to copy, distribute and/or modify this document
18
under the terms of the GNU Free Documentation License, Version 1.1 or
19
any later version published by the Free Software Foundation; with the
20
Invariant Sections being "A Sample GDB Session" and "Free Software",
21
with the Front-Cover texts being "A GNU Manual," and with the
22
Back-Cover Texts as in (a) below.
23
 
24
   (a) The FSF's Back-Cover Text is: "You have freedom to copy and
25
modify this GNU Manual, like GNU software.  Copies published by the Free
26
Software Foundation raise funds for GNU development."
27
 
28

29
File: gdb.info,  Node: Protocol,  Next: Server,  Prev: Debug Session,  Up: Remote Serial
30
 
31
Communication protocol
32
......................
33
 
34
   The stub files provided with GDB implement the target side of the
35
communication protocol, and the GDB side is implemented in the GDB
36
source file `remote.c'.  Normally, you can simply allow these
37
subroutines to communicate, and ignore the details.  (If you're
38
implementing your own stub file, you can still ignore the details: start
39
with one of the existing stub files.  `sparc-stub.c' is the best
40
organized, and therefore the easiest to read.)
41
 
42
   However, there may be occasions when you need to know something about
43
the protocol--for example, if there is only one serial port to your
44
target machine, you might want your program to do something special if
45
it recognizes a packet meant for GDB.
46
 
47
   In the examples below, `<-' and `->' are used to indicate
48
transmitted and received data respectfully.
49
 
50
   All GDB commands and responses (other than acknowledgments) are sent
51
as a PACKET.  A PACKET is introduced with the character `$', the actual
52
PACKET-DATA, and the terminating character `#' followed by a two-digit
53
CHECKSUM:
54
 
55
     `$'PACKET-DATA`#'CHECKSUM
56
 
57
The two-digit CHECKSUM is computed as the modulo 256 sum of all
58
characters between the leading `$' and the trailing `#' (an eight bit
59
unsigned checksum).
60
 
61
   Implementors should note that prior to GDB 5.0 the protocol
62
specification also included an optional two-digit SEQUENCE-ID:
63
 
64
     `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
65
 
66
That SEQUENCE-ID was appended to the acknowledgment.  GDB has never
67
output SEQUENCE-IDs.  Stubs that handle packets added since GDB 5.0
68
must not accept SEQUENCE-ID.
69
 
70
   When either the host or the target machine receives a packet, the
71
first response expected is an acknowledgment: either `+' (to indicate
72
the package was received correctly) or `-' (to request retransmission):
73
 
74
     <- `$'PACKET-DATA`#'CHECKSUM
75
     -> `+'
76
 
77
The host (GDB) sends COMMANDs, and the target (the debugging stub
78
incorporated in your program) sends a RESPONSE.  In the case of step
79
and continue COMMANDs, the response is only sent when the operation has
80
completed (the target has again stopped).
81
 
82
   PACKET-DATA consists of a sequence of characters with the exception
83
of `#' and `$' (see `X' packet for additional exceptions).
84
 
85
   Fields within the packet should be separated using `,' `;' or `:'.
86
Except where otherwise noted all numbers are represented in HEX with
87
leading zeros suppressed.
88
 
89
   Implementors should note that prior to GDB 5.0, the character `:'
90
could not appear as the third character in a packet (as it would
91
potentially conflict with the SEQUENCE-ID).
92
 
93
   Response DATA can be run-length encoded to save space.  A `*' means
94
that the next character is an ASCII encoding giving a repeat count
95
which stands for that many repetitions of the character preceding the
96
`*'.  The encoding is `n+29', yielding a printable character where `n
97
>=3' (which is where rle starts to win).  The printable characters `$',
98
`#', `+' and `-' or with a numeric value greater than 126 should not be
99
used.
100
 
101
   Some remote systems have used a different run-length encoding
102
mechanism loosely refered to as the cisco encoding.  Following the `*'
103
character are two hex digits that indicate the size of the packet.
104
 
105
   So:
106
     "`0* '"
107
 
108
means the same as "0000".
109
 
110
   The error response returned for some packets includes a two character
111
error number.  That number is not well defined.
112
 
113
   For any COMMAND not supported by the stub, an empty response
114
(`$#00') should be returned.  That way it is possible to extend the
115
protocol.  A newer GDB can tell if a packet is supported based on that
116
response.
117
 
118
   A stub is required to support the `g', `G', `m', `M', `c', and `s'
119
COMMANDs.  All other COMMANDs are optional.
120
 
121
   Below is a complete list of all currently defined COMMANDs and their
122
corresponding response DATA:
123
 
124
Packet                 Request                Description
125
extended mode          `!'                    Enable extended mode.  In
126
                                              extended mode, the remote
127
                                              server is made persistent.
128
                                              The `R' packet is used to
129
                                              restart the program being
130
                                              debugged.
131
                       reply `OK'             The remote target both
132
                                              supports and has enabled
133
                                              extended mode.
134
last signal            `?'                    Indicate the reason the
135
                                              target halted.  The reply is
136
                                              the same as for step and
137
                                              continue.
138
                       reply                  see below
139
reserved               `a'                    Reserved for future use
140
set program arguments  `A'ARGLEN`,'ARGNUM`,'ARG`,...'
141
*(reserved)*
142
                                              Initialized `argv[]' array
143
                                              passed into program. ARGLEN
144
                                              specifies the number of
145
                                              bytes in the hex encoded
146
                                              byte stream ARG.  See
147
                                              `gdbserver' for more details.
148
                       reply `OK'
149
                       reply `E'NN
150
set baud               `b'BAUD                Change the serial line speed
151
*(deprecated)*                                to BAUD.  JTC: _When does the
152
                                              transport layer state
153
                                              change?  When it's received,
154
                                              or after the ACK is
155
                                              transmitted.  In either
156
                                              case, there are problems if
157
                                              the command or the
158
                                              acknowledgment packet is
159
                                              dropped._ Stan: _If people
160
                                              really wanted to add
161
                                              something like this, and get
162
                                              it working for the first
163
                                              time, they ought to modify
164
                                              ser-unix.c to send some kind
165
                                              of out-of-band message to a
166
                                              specially-setup stub and
167
                                              have the switch happen "in
168
                                              between" packets, so that
169
                                              from remote protocol's point
170
                                              of view, nothing actually
171
                                              happened._
172
set breakpoint         `B'ADDR,MODE           Set (MODE is `S') or clear
173
*(deprecated)*                                (MODE is `C') a breakpoint
174
                                              at ADDR.  _This has been
175
                                              replaced by the `Z' and `z'
176
                                              packets._
177
continue               `c'ADDR                ADDR is address to resume.
178
                                              If ADDR is omitted, resume at
179
                                              current address.
180
                       reply                  see below
181
continue with signal   `C'SIG`;'ADDR          Continue with signal SIG
182
                                              (hex signal number).  If
183
                                              `;'ADDR is omitted, resume
184
                                              at same address.
185
                       reply                  see below
186
toggle debug           `d'                    toggle debug flag.
187
*(deprecated)*
188
detach                 `D'                    Detach GDB from the remote
189
                                              system.  Sent to the remote
190
                                              target before GDB
191
                                              disconnects.
192
                       reply _no response_    GDB does not check for any
193
                                              response after sending this
194
                                              packet.
195
reserved               `e'                    Reserved for future use
196
reserved               `E'                    Reserved for future use
197
reserved               `f'                    Reserved for future use
198
reserved               `F'                    Reserved for future use
199
read registers         `g'                    Read general registers.
200
                       reply XX...            Each byte of register data
201
                                              is described by two hex
202
                                              digits.  The bytes with the
203
                                              register are transmitted in
204
                                              target byte order.  The size
205
                                              of each register and their
206
                                              position within the `g'
207
                                              PACKET are determined by the
208
                                              GDB internal macros
209
                                              REGISTER_RAW_SIZE and
210
                                              REGISTER_NAME macros.  The
211
                                              specification of several
212
                                              standard `g' packets is
213
                                              specified below.
214
                       `E'NN                  for an error.
215
write regs             `G'XX...               See `g' for a description of
216
                                              the XX... data.
217
                       reply `OK'             for success
218
                       reply `E'NN            for an error
219
reserved               `h'                    Reserved for future use
220
set thread             `H'CT...               Set thread for subsequent
221
                                              operations (`m', `M', `g',
222
                                              `G', et.al.).  C = `c' for
223
                                              thread used in step and
224
                                              continue; T... can be -1 for
225
                                              all threads.  C = `g' for
226
                                              thread used in other
227
                                              operations.  If zero, pick a
228
                                              thread, any thread.
229
                       reply `OK'             for success
230
                       reply `E'NN            for an error
231
cycle step *(draft)*   `i'ADDR`,'NNN          Step the remote target by a
232
                                              single clock cycle.  If
233
                                              `,'NNN is present, cycle
234
                                              step NNN cycles.  If ADDR is
235
                                              present, cycle step starting
236
                                              at that address.
237
signal then cycle      `I'                    See `i' and `S' for likely
238
step *(reserved)*                             syntax and semantics.
239
reserved               `j'                    Reserved for future use
240
reserved               `J'                    Reserved for future use
241
kill request           `k'                    FIXME: _There is no
242
                                              description of how operate
243
                                              when a specific thread
244
                                              context has been selected
245
                                              (ie. does 'k' kill only that
246
                                              thread?)_.
247
reserved               `l'                    Reserved for future use
248
reserved               `L'                    Reserved for future use
249
read memory            `m'ADDR`,'LENGTH       Read LENGTH bytes of memory
250
                                              starting at address ADDR.
251
                                              Neither GDB nor the stub
252
                                              assume that sized memory
253
                                              transfers are assumed using
254
                                              word alligned accesses.
255
                                              FIXME: _A word aligned memory
256
                                              transfer mechanism is
257
                                              needed._
258
                       reply XX...            XX... is mem contents. Can
259
                                              be fewer bytes than
260
                                              requested if able to read
261
                                              only part of the data.
262
                                              Neither GDB nor the stub
263
                                              assume that sized memory
264
                                              transfers are assumed using
265
                                              word alligned accesses.
266
                                              FIXME: _A word aligned
267
                                              memory transfer mechanism is
268
                                              needed._
269
                       reply `E'NN            NN is errno
270
write mem              `M'ADDR,LENGTH`:'XX... Write LENGTH bytes of memory
271
                                              starting at address ADDR.
272
                                              XX... is the data.
273
                       reply `OK'             for success
274
                       reply `E'NN            for an error (this includes
275
                                              the case where only part of
276
                                              the data was written).
277
reserved               `n'                    Reserved for future use
278
reserved               `N'                    Reserved for future use
279
reserved               `o'                    Reserved for future use
280
reserved               `O'                    Reserved for future use
281
read reg *(reserved)*  `p'N...                See write register.
282
                       return R....           The hex encoded value of the
283
                                              register in target byte
284
                                              order.
285
write reg              `P'N...`='R...         Write register N... with
286
                                              value R..., which contains
287
                                              two hex digits for each byte
288
                                              in the register (target byte
289
                                              order).
290
                       reply `OK'             for success
291
                       reply `E'NN            for an error
292
general query          `q'QUERY               Request info about QUERY.
293
                                              In general GDB queries have
294
                                              a leading upper case letter.
295
                                              Custom vendor queries
296
                                              should use a company prefix
297
                                              (in lower case) ex:
298
                                              `qfsf.var'.  QUERY may
299
                                              optionally be followed by a
300
                                              `,' or `;' separated list.
301
                                              Stubs must ensure that they
302
                                              match the full QUERY name.
303
                       reply `XX...'          Hex encoded data from query.
304
                                              The reply can not be empty.
305
                       reply `E'NN            error reply
306
                       reply `'               Indicating an unrecognized
307
                                              QUERY.
308
general set            `Q'VAR`='VAL           Set value of VAR to VAL.
309
                                              See `q' for a discussing of
310
                                              naming conventions.
311
reset *(deprecated)*   `r'                    Reset the entire system.
312
remote restart         `R'XX                  Restart the program being
313
                                              debugged.  XX, while needed,
314
                                              is ignored.  This packet is
315
                                              only available in extended
316
                                              mode.
317
                       no reply               The `R' packet has no reply.
318
step                   `s'ADDR                ADDR is address to resume.
319
                                              If ADDR is omitted, resume at
320
                                              same address.
321
                       reply                  see below
322
step with signal       `S'SIG`;'ADDR          Like `C' but step not
323
                                              continue.
324
                       reply                  see below
325
search                 `t'ADDR`:'PP`,'MM      Search backwards starting at
326
                                              address ADDR for a match
327
                                              with pattern PP and mask MM.
328
                                              PP and MM are 4 bytes.
329
                                              ADDR must be at least 3
330
                                              digits.
331
thread alive           `T'XX                  Find out if the thread XX is
332
                                              alive.
333
                       reply `OK'             thread is still alive
334
                       reply `E'NN            thread is dead
335
reserved               `u'                    Reserved for future use
336
reserved               `U'                    Reserved for future use
337
reserved               `v'                    Reserved for future use
338
reserved               `V'                    Reserved for future use
339
reserved               `w'                    Reserved for future use
340
reserved               `W'                    Reserved for future use
341
reserved               `x'                    Reserved for future use
342
write mem (binary)     `X'ADDR`,'LENGTH:XX... ADDR is address, LENGTH is
343
                                              number of bytes, XX... is
344
                                              binary data.  The characters
345
                                              `$', `#', and `0x7d' are
346
                                              escaped using `0x7d'.
347
                       reply `OK'             for success
348
                       reply `E'NN            for an error
349
reserved               `y'                    Reserved for future use
350
reserved               `Y'                    Reserved for future use
351
remove break or        `z'T`,'ADDR`,'LENGTH   See `Z'.
352
watchpoint *(draft)*
353
insert break or        `Z'T`,'ADDR`,'LENGTH   T is type: `0' - software
354
watchpoint *(draft)*                          breakpoint, `1' - hardware
355
                                              breakpoint, `2' - write
356
                                              watchpoint, `3' - read
357
                                              watchpoint, `4' - access
358
                                              watchpoint; ADDR is address;
359
                                              LENGTH is in bytes.  For a
360
                                              software breakpoint, LENGTH
361
                                              specifies the size of the
362
                                              instruction to be patched.
363
                                              For hardware breakpoints and
364
                                              watchpoints LENGTH specifies
365
                                              the memory region to be
366
                                              monitored.  To avoid
367
                                              potential problems with
368
                                              duplicate packets, the
369
                                              operations should be
370
                                              implemented in an idempotent
371
                                              way.
372
                       reply `E'NN            for an error
373
                       reply `OK'             for success
374
                       `'                     If not supported.
375
reserved                               Reserved for future use
376
 
377
   The `C', `c', `S', `s' and `?' packets can receive any of the below
378
as a reply.  In the case of the `C', `c', `S' and `s' packets, that
379
reply is only returned when the target halts.  In the below the exact
380
meaning of `signal number' is poorly defined.  In general one of the
381
UNIX signal numbering conventions is used.
382
 
383
`S'AA                         AA is the signal number
384
`T'AAN...`:'R...`;'N...`:'R...`;'N...`:'R...`;'AA = two hex digit signal number; N... =
385
                              register number (hex), R...  = target byte
386
                              ordered register contents, size defined by
387
                              `REGISTER_RAW_SIZE'; N... = `thread', R...
388
                              = thread process ID, this is a hex
389
                              integer; N... = other string not starting
390
                              with valid hex digit.  GDB should ignore
391
                              this N..., R... pair and go on to the
392
                              next.  This way we can extend the protocol.
393
`W'AA                         The process exited, and AA is the exit
394
                              status.  This is only applicable for
395
                              certains sorts of targets.
396
`X'AA                         The process terminated with signal AA.
397
`N'AA`;'T...`;'D...`;'B...    AA = signal number; T... = address of
398
*(obsolete)*                  symbol "_start"; D... = base of data
399
                              section; B... = base of bss section.
400
                              _Note: only used by Cisco Systems targets.
401
                              The difference between this reply and the
402
                              "qOffsets" query is that the 'N' packet
403
                              may arrive spontaneously whereas the
404
                              'qOffsets' is a query initiated by the host
405
                              debugger._
406
`O'XX...                      XX... is hex encoding of ASCII data.  This
407
                              can happen at any time while the program
408
                              is running and the debugger should
409
                              continue to wait for 'W', 'T', etc.
410
 
411
   The following set and query packets have already been defined.
412
 
413
current thread `q'`C'         Return the current thread id.
414
               reply `QC'PID  Where PID is a HEX encoded 16 bit process
415
                              id.
416
               reply *        Any other reply implies the old pid.
417
all thread ids `q'`fThreadInfo'
418
               `q'`sThreadInfo'Obtain a list of active thread ids from
419
                              the target (OS).  Since there may be too
420
                              many active threads to fit into one reply
421
                              packet, this query works iteratively: it
422
                              may require more than one query/reply
423
                              sequence to obtain the entire list of
424
                              threads.  The first query of the sequence
425
                              will be the `qf'`ThreadInfo' query;
426
                              subsequent queries in the sequence will be
427
                              the `qs'`ThreadInfo' query.
428
                              NOTE: replaces the `qL' query (see below).
429
               reply `m'  A single thread id
430
               reply          a comma-separated list of thread ids
431
               `m',...
432
               reply `l'      (lower case 'el') denotes end of list.
433
                              In response to each query, the target will
434
                              reply with a list of one or more thread
435
                              ids, in big-endian hex, separated by
436
                              commas.  GDB will respond to each reply
437
                              with a request for more thread ids (using
438
                              the `qs' form of the query), until the
439
                              target responds with `l' (lower-case el,
440
                              for `'last'').
441
extra thread   `q'`ThreadExtraInfo'`,'ID
442
info
443
                              Where  is a thread-id in big-endian
444
                              hex.  Obtain a printable string
445
                              description of a thread's attributes from
446
                              the target OS.  This string may contain
447
                              anything that the target OS thinks is
448
                              interesting for GDB to tell the user about
449
                              the thread.  The string is displayed in
450
                              GDB's `info threads' display.  Some
451
                              examples of possible thread extra info
452
                              strings are "Runnable", or "Blocked on
453
                              Mutex".
454
               reply XX...    Where XX... is a hex encoding of ASCII
455
                              data, comprising the printable string
456
                              containing the extra information about the
457
                              thread's attributes.
458
query LIST or  `q'`L'STARTFLAGTHREADCOUNTNEXTTHREAD
459
THREADLIST
460
*(deprecated)*
461
                              Obtain thread information from RTOS.
462
                              Where: STARTFLAG (one hex digit) is one to
463
                              indicate the first query and zero to
464
                              indicate a subsequent query; THREADCOUNT
465
                              (two hex digits) is the maximum number of
466
                              threads the response packet can contain;
467
                              and NEXTTHREAD (eight hex digits), for
468
                              subsequent queries (STARTFLAG is zero), is
469
                              returned in the response as ARGTHREAD.
470
                              NOTE: this query is replaced by the
471
                              `q'`fThreadInfo' query (see above).
472
               reply
473
               `q'`M'COUNTDONEARGTHREADTHREAD...
474
                              Where: COUNT (two hex digits) is the
475
                              number of threads being returned; DONE
476
                              (one hex digit) is zero to indicate more
477
                              threads and one indicates no further
478
                              threads; ARGTHREADID (eight hex digits) is
479
                              NEXTTHREAD from the request packet;
480
                              THREAD... is a sequence of thread IDs from
481
                              the target.  THREADID (eight hex digits).
482
                              See `remote.c:parse_threadlist_response()'.
483
compute CRC    `q'`CRC:'ADDR`,'LENGTH
484
of memory
485
block
486
               reply `E'NN    An error (such as memory fault)
487
               reply `C'CRC32 A 32 bit cyclic redundancy check of the
488
                              specified memory region.
489
query sect     `q'`Offsets'   Get section offsets that the target used
490
offs                          when re-locating the downloaded image.
491
                              _Note: while a `Bss' offset is included in
492
                              the response, GDB ignores this and instead
493
                              applies the `Data' offset to the `Bss'
494
                              section._
495
               reply
496
               `Text='XXX`;Data='YYY`;Bss='ZZZ
497
thread info    `q'`P'MODETHREADID
498
request
499
                              Returns information on THREADID.  Where:
500
                              MODE is a hex encoded 32 bit mode;
501
                              THREADID is a hex encoded 64 bit thread ID.
502
               reply *        See
503
                              `remote.c:remote_unpack_thread_info_response()'.
504
remote command `q'`Rcmd,'COMMAND
505
                              COMMAND (hex encoded) is passed to the
506
                              local interpreter for execution.  Invalid
507
                              commands should be reported using the
508
                              output string.  Before the final result
509
                              packet, the target may also respond with a
510
                              number of intermediate `O'OUTPUT console
511
                              output packets.  _Implementors should note
512
                              that providing access to a stubs's
513
                              interpreter may have security
514
                              implications_.
515
               reply `OK'     A command response with no output.
516
               reply OUTPUT   A command response with the hex encoded
517
                              output string OUTPUT.
518
               reply `E'NN    Indicate a badly formed request.
519
               reply `'       When `q'`Rcmd' is not recognized.
520
symbol lookup  `qSymbol::'    Notify the target that GDB is prepared to
521
                              serve symbol lookup requests.  Accept
522
                              requests from the target for the values of
523
                              symbols.
524
 
525
               reply `OK'     The target does not need to look up any
526
                              (more) symbols.
527
               reply          The target requests the value of symbol
528
               `qSymbol:'SYM_NAMESYM_NAME (hex encoded).  GDB may provide
529
                              the value by using the
530
                              `qSymbol:'SYM_VALUE:SYM_NAME message,
531
                              described below.
532
symbol value   `qSymbol:'SYM_VALUE:SYM_NAMESet the value of SYM_NAME to SYM_VALUE.
533
                              SYM_NAME (hex encoded) is the name of a
534
                              symbol whose value the target has
535
                              previously requested.
536
                              SYM_VALUE (hex) is the value for symbol
537
                              SYM_NAME.  If GDB cannot supply a value
538
                              for SYM_NAME, then this field will be
539
                              empty.
540
               reply `OK'     The target does not need to look up any
541
                              (more) symbols.
542
               reply          The target requests the value of a new
543
               `qSymbol:'SYM_NAMEsymbol SYM_NAME (hex encoded).  GDB will
544
                              continue to supply the values of symbols
545
                              (if available), until the target ceases to
546
                              request them.
547
 
548
   The following `g'/`G' packets have previously been defined.  In the
549
below, some thirty-two bit registers are transferred as sixty-four
550
bits.  Those registers should be zero/sign extended (which?) to fill the
551
space allocated.  Register bytes are transfered in target byte order.
552
The two nibbles within a register byte are transfered most-significant -
553
least-significant.
554
 
555
MIPS32                               All registers are transfered as
556
                                     thirty-two bit quantities in the
557
                                     order: 32 general-purpose; sr; lo;
558
                                     hi; bad; cause; pc; 32
559
                                     floating-point registers; fsr; fir;
560
                                     fp.
561
MIPS64                               All registers are transfered as
562
                                     sixty-four bit quantities (including
563
                                     thirty-two bit registers such as
564
                                     `sr').  The ordering is the same as
565
                                     `MIPS32'.
566
 
567
   Example sequence of a target being re-started.  Notice how the
568
restart does not get any direct output:
569
 
570
     <- `R00'
571
     -> `+'
572
     _target restarts_
573
     <- `?'
574
     -> `+'
575
     -> `T001:1234123412341234'
576
     <- `+'
577
 
578
   Example sequence of a target being stepped by a single instruction:
579
 
580
     <- `G1445...'
581
     -> `+'
582
     <- `s'
583
     -> `+'
584
     _time passes_
585
     -> `T001:1234123412341234'
586
     <- `+'
587
     <- `g'
588
     -> `+'
589
     -> `1455...'
590
     <- `+'
591
 
592

593
File: gdb.info,  Node: Server,  Next: NetWare,  Prev: Protocol,  Up: Remote Serial
594
 
595
Using the `gdbserver' program
596
.............................
597
 
598
   `gdbserver' is a control program for Unix-like systems, which allows
599
you to connect your program with a remote GDB via `target remote'--but
600
without linking in the usual debugging stub.
601
 
602
   `gdbserver' is not a complete replacement for the debugging stubs,
603
because it requires essentially the same operating-system facilities
604
that GDB itself does.  In fact, a system that can run `gdbserver' to
605
connect to a remote GDB could also run GDB locally!  `gdbserver' is
606
sometimes useful nevertheless, because it is a much smaller program
607
than GDB itself.  It is also easier to port than all of GDB, so you may
608
be able to get started more quickly on a new system by using
609
`gdbserver'.  Finally, if you develop code for real-time systems, you
610
may find that the tradeoffs involved in real-time operation make it
611
more convenient to do as much development work as possible on another
612
system, for example by cross-compiling.  You can use `gdbserver' to
613
make a similar choice for debugging.
614
 
615
   GDB and `gdbserver' communicate via either a serial line or a TCP
616
connection, using the standard GDB remote serial protocol.
617
 
618
_On the target machine,_
619
     you need to have a copy of the program you want to debug.
620
     `gdbserver' does not need your program's symbol table, so you can
621
     strip the program if necessary to save space.  GDB on the host
622
     system does all the symbol handling.
623
 
624
     To use the server, you must tell it how to communicate with GDB;
625
     the name of your program; and the arguments for your program.  The
626
     syntax is:
627
 
628
          target> gdbserver COMM PROGRAM [ ARGS ... ]
629
 
630
     COMM is either a device name (to use a serial line) or a TCP
631
     hostname and portnumber.  For example, to debug Emacs with the
632
     argument `foo.txt' and communicate with GDB over the serial port
633
     `/dev/com1':
634
 
635
          target> gdbserver /dev/com1 emacs foo.txt
636
 
637
     `gdbserver' waits passively for the host GDB to communicate with
638
     it.
639
 
640
     To use a TCP connection instead of a serial line:
641
 
642
          target> gdbserver host:2345 emacs foo.txt
643
 
644
     The only difference from the previous example is the first
645
     argument, specifying that you are communicating with the host GDB
646
     via TCP.  The `host:2345' argument means that `gdbserver' is to
647
     expect a TCP connection from machine `host' to local TCP port 2345.
648
     (Currently, the `host' part is ignored.)  You can choose any number
649
     you want for the port number as long as it does not conflict with
650
     any TCP ports already in use on the target system (for example,
651
     `23' is reserved for `telnet').(1)  You must use the same port
652
     number with the host GDB `target remote' command.
653
 
654
_On the GDB host machine,_
655
     you need an unstripped copy of your program, since GDB needs
656
     symbols and debugging information.  Start up GDB as usual, using
657
     the name of the local copy of your program as the first argument.
658
     (You may also need the `--baud' option if the serial line is
659
     running at anything other than 9600bps.)  After that, use `target
660
     remote' to establish communications with `gdbserver'.  Its argument
661
     is either a device name (usually a serial device, like
662
     `/dev/ttyb'), or a TCP port descriptor in the form `HOST:PORT'.
663
     For example:
664
 
665
          (gdb) target remote /dev/ttyb
666
 
667
     communicates with the server via serial line `/dev/ttyb', and
668
 
669
          (gdb) target remote the-target:2345
670
 
671
     communicates via a TCP connection to port 2345 on host
672
     `the-target'.  For TCP connections, you must start up `gdbserver'
673
     prior to using the `target remote' command.  Otherwise you may get
674
     an error whose text depends on the host system, but which usually
675
     looks something like `Connection refused'.
676
 
677
   ---------- Footnotes ----------
678
 
679
   (1) If you choose a port number that conflicts with another service,
680
`gdbserver' prints an error message and exits.
681
 
682

683
File: gdb.info,  Node: NetWare,  Prev: Server,  Up: Remote Serial
684
 
685
Using the `gdbserve.nlm' program
686
................................
687
 
688
   `gdbserve.nlm' is a control program for NetWare systems, which
689
allows you to connect your program with a remote GDB via `target
690
remote'.
691
 
692
   GDB and `gdbserve.nlm' communicate via a serial line, using the
693
standard GDB remote serial protocol.
694
 
695
_On the target machine,_
696
     you need to have a copy of the program you want to debug.
697
     `gdbserve.nlm' does not need your program's symbol table, so you
698
     can strip the program if necessary to save space.  GDB on the host
699
     system does all the symbol handling.
700
 
701
     To use the server, you must tell it how to communicate with GDB;
702
     the name of your program; and the arguments for your program.  The
703
     syntax is:
704
 
705
          load gdbserve [ BOARD=BOARD ] [ PORT=PORT ]
706
                        [ BAUD=BAUD ] PROGRAM [ ARGS ... ]
707
 
708
     BOARD and PORT specify the serial line; BAUD specifies the baud
709
     rate used by the connection.  PORT and NODE default to 0, BAUD
710
     defaults to 9600bps.
711
 
712
     For example, to debug Emacs with the argument `foo.txt'and
713
     communicate with GDB over serial port number 2 or board 1 using a
714
     19200bps connection:
715
 
716
          load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
717
 
718
_On the GDB host machine,_
719
     you need an unstripped copy of your program, since GDB needs
720
     symbols and debugging information.  Start up GDB as usual, using
721
     the name of the local copy of your program as the first argument.
722
     (You may also need the `--baud' option if the serial line is
723
     running at anything other than 9600bps.  After that, use `target
724
     remote' to establish communications with `gdbserve.nlm'.  Its
725
     argument is a device name (usually a serial device, like
726
     `/dev/ttyb').  For example:
727
 
728
          (gdb) target remote /dev/ttyb
729
 
730
     communications with the server via serial line `/dev/ttyb'.
731
 
732

733
File: gdb.info,  Node: KOD,  Prev: Remote,  Up: Targets
734
 
735
Kernel Object Display
736
=====================
737
 
738
   Some targets support kernel object display.  Using this facility,
739
GDB communicates specially with the underlying operating system and can
740
display information about operating system-level objects such as
741
mutexes and other synchronization objects.  Exactly which objects can be
742
displayed is determined on a per-OS basis.
743
 
744
   Use the `set os' command to set the operating system.  This tells
745
GDB which kernel object display module to initialize:
746
 
747
     (gdb) set os cisco
748
 
749
   If `set os' succeeds, GDB will display some information about the
750
operating system, and will create a new `info' command which can be
751
used to query the target.  The `info' command is named after the
752
operating system:
753
 
754
     (gdb) info cisco
755
     List of Cisco Kernel Objects
756
     Object     Description
757
     any        Any and all objects
758
 
759
   Further subcommands can be used to query about particular objects
760
known by the kernel.
761
 
762
   There is currently no way to determine whether a given operating
763
system is supported other than to try it.
764
 
765

766
File: gdb.info,  Node: Configurations,  Next: Controlling GDB,  Prev: Targets,  Up: Top
767
 
768
Configuration-Specific Information
769
**********************************
770
 
771
   While nearly all GDB commands are available for all native and cross
772
versions of the debugger, there are some exceptions.  This chapter
773
describes things that are only available in certain configurations.
774
 
775
   There are three major categories of configurations: native
776
configurations, where the host and target are the same, embedded
777
operating system configurations, which are usually the same for several
778
different processor architectures, and bare embedded processors, which
779
are quite different from each other.
780
 
781
* Menu:
782
 
783
* Native::
784
* Embedded OS::
785
* Embedded Processors::
786
* Architectures::
787
 
788

789
File: gdb.info,  Node: Native,  Next: Embedded OS,  Up: Configurations
790
 
791
Native
792
======
793
 
794
   This section describes details specific to particular native
795
configurations.
796
 
797
* Menu:
798
 
799
* HP-UX::                       HP-UX
800
* SVR4 Process Information::    SVR4 process information
801
 
802

803
File: gdb.info,  Node: HP-UX,  Next: SVR4 Process Information,  Up: Native
804
 
805
HP-UX
806
-----
807
 
808
   On HP-UX systems, if you refer to a function or variable name that
809
begins with a dollar sign, GDB searches for a user or system name
810
first, before it searches for a convenience variable.
811
 
812

813
File: gdb.info,  Node: SVR4 Process Information,  Prev: HP-UX,  Up: Native
814
 
815
SVR4 process information
816
------------------------
817
 
818
   Many versions of SVR4 provide a facility called `/proc' that can be
819
used to examine the image of a running process using file-system
820
subroutines.  If GDB is configured for an operating system with this
821
facility, the command `info proc' is available to report on several
822
kinds of information about the process running your program.  `info
823
proc' works only on SVR4 systems that include the `procfs' code.  This
824
includes OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not
825
HP-UX or Linux, for example.
826
 
827
`info proc'
828
     Summarize available information about the process.
829
 
830
`info proc mappings'
831
     Report on the address ranges accessible in the program, with
832
     information on whether your program may read, write, or execute
833
     each range.
834
 
835
`info proc times'
836
     Starting time, user CPU time, and system CPU time for your program
837
     and its children.
838
 
839
`info proc id'
840
     Report on the process IDs related to your program: its own process
841
     ID, the ID of its parent, the process group ID, and the session ID.
842
 
843
`info proc status'
844
     General information on the state of the process.  If the process is
845
     stopped, this report includes the reason for stopping, and any
846
     signal received.
847
 
848
`info proc all'
849
     Show all the above information about the process.
850
 
851

852
File: gdb.info,  Node: Embedded OS,  Next: Embedded Processors,  Prev: Native,  Up: Configurations
853
 
854
Embedded Operating Systems
855
==========================
856
 
857
   This section describes configurations involving the debugging of
858
embedded operating systems that are available for several different
859
architectures.
860
 
861
* Menu:
862
 
863
* VxWorks::                     Using GDB with VxWorks
864
 
865
   GDB includes the ability to debug programs running on various
866
real-time operating systems.
867
 
868

869
File: gdb.info,  Node: VxWorks,  Up: Embedded OS
870
 
871
Using GDB with VxWorks
872
----------------------
873
 
874
`target vxworks MACHINENAME'
875
     A VxWorks system, attached via TCP/IP.  The argument MACHINENAME
876
     is the target system's machine name or IP address.
877
 
878
   On VxWorks, `load' links FILENAME dynamically on the current target
879
system as well as adding its symbols in GDB.
880
 
881
   GDB enables developers to spawn and debug tasks running on networked
882
VxWorks targets from a Unix host.  Already-running tasks spawned from
883
the VxWorks shell can also be debugged.  GDB uses code that runs on
884
both the Unix host and on the VxWorks target.  The program `gdb' is
885
installed and executed on the Unix host.  (It may be installed with the
886
name `vxgdb', to distinguish it from a GDB for debugging programs on
887
the host itself.)
888
 
889
`VxWorks-timeout ARGS'
890
     All VxWorks-based targets now support the option `vxworks-timeout'.
891
     This option is set by the user, and  ARGS represents the number of
892
     seconds GDB waits for responses to rpc's.  You might use this if
893
     your VxWorks target is a slow software simulator or is on the far
894
     side of a thin network line.
895
 
896
   The following information on connecting to VxWorks was current when
897
this manual was produced; newer releases of VxWorks may use revised
898
procedures.
899
 
900
   To use GDB with VxWorks, you must rebuild your VxWorks kernel to
901
include the remote debugging interface routines in the VxWorks library
902
`rdb.a'.  To do this, define `INCLUDE_RDB' in the VxWorks configuration
903
file `configAll.h' and rebuild your VxWorks kernel.  The resulting
904
kernel contains `rdb.a', and spawns the source debugging task
905
`tRdbTask' when VxWorks is booted.  For more information on configuring
906
and remaking VxWorks, see the manufacturer's manual.
907
 
908
   Once you have included `rdb.a' in your VxWorks system image and set
909
your Unix execution search path to find GDB, you are ready to run GDB.
910
From your Unix host, run `gdb' (or `vxgdb', depending on your
911
installation).
912
 
913
   GDB comes up showing the prompt:
914
 
915
     (vxgdb)
916
 
917
* Menu:
918
 
919
* VxWorks Connection::          Connecting to VxWorks
920
* VxWorks Download::            VxWorks download
921
* VxWorks Attach::              Running tasks
922
 
923

924
File: gdb.info,  Node: VxWorks Connection,  Next: VxWorks Download,  Up: VxWorks
925
 
926
Connecting to VxWorks
927
.....................
928
 
929
   The GDB command `target' lets you connect to a VxWorks target on the
930
network.  To connect to a target whose host name is "`tt'", type:
931
 
932
     (vxgdb) target vxworks tt
933
 
934
   GDB displays messages like these:
935
 
936
     Attaching remote machine across net...
937
     Connected to tt.
938
 
939
   GDB then attempts to read the symbol tables of any object modules
940
loaded into the VxWorks target since it was last booted.  GDB locates
941
these files by searching the directories listed in the command search
942
path (*note Your program's environment: Environment.); if it fails to
943
find an object file, it displays a message such as:
944
 
945
     prog.o: No such file or directory.
946
 
947
   When this happens, add the appropriate directory to the search path
948
with the GDB command `path', and execute the `target' command again.
949
 
950

951
File: gdb.info,  Node: VxWorks Download,  Next: VxWorks Attach,  Prev: VxWorks Connection,  Up: VxWorks
952
 
953
VxWorks download
954
................
955
 
956
   If you have connected to the VxWorks target and you want to debug an
957
object that has not yet been loaded, you can use the GDB `load' command
958
to download a file from Unix to VxWorks incrementally.  The object file
959
given as an argument to the `load' command is actually opened twice:
960
first by the VxWorks target in order to download the code, then by GDB
961
in order to read the symbol table.  This can lead to problems if the
962
current working directories on the two systems differ.  If both systems
963
have NFS mounted the same filesystems, you can avoid these problems by
964
using absolute paths.  Otherwise, it is simplest to set the working
965
directory on both systems to the directory in which the object file
966
resides, and then to reference the file by its name, without any path.
967
For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in
968
VxWorks and in `HOSTPATH/vw/demo/rdb' on the host.  To load this
969
program, type this on VxWorks:
970
 
971
     -> cd "VXPATH/vw/demo/rdb"
972
 
973
Then, in GDB, type:
974
 
975
     (vxgdb) cd HOSTPATH/vw/demo/rdb
976
     (vxgdb) load prog.o
977
 
978
   GDB displays a response similar to this:
979
 
980
     Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
981
 
982
   You can also use the `load' command to reload an object module after
983
editing and recompiling the corresponding source file.  Note that this
984
makes GDB delete all currently-defined breakpoints, auto-displays, and
985
convenience variables, and to clear the value history.  (This is
986
necessary in order to preserve the integrity of debugger's data
987
structures that reference the target system's symbol table.)
988
 
989

990
File: gdb.info,  Node: VxWorks Attach,  Prev: VxWorks Download,  Up: VxWorks
991
 
992
Running tasks
993
.............
994
 
995
   You can also attach to an existing task using the `attach' command as
996
follows:
997
 
998
     (vxgdb) attach TASK
999
 
1000
where TASK is the VxWorks hexadecimal task ID.  The task can be running
1001
or suspended when you attach to it.  Running tasks are suspended at the
1002
time of attachment.
1003
 
1004

1005
File: gdb.info,  Node: Embedded Processors,  Next: Architectures,  Prev: Embedded OS,  Up: Configurations
1006
 
1007
Embedded Processors
1008
===================
1009
 
1010
   This section goes into details specific to particular embedded
1011
configurations.
1012
 
1013
* Menu:
1014
 
1015
* A29K Embedded::               AMD A29K Embedded
1016
* ARM::                         ARM
1017
* H8/300::                      Hitachi H8/300
1018
* H8/500::                      Hitachi H8/500
1019
* i960::                        Intel i960
1020
* M32R/D::                      Mitsubishi M32R/D
1021
* M68K::                        Motorola M68K
1022
* M88K::                        Motorola M88K
1023
* MIPS Embedded::               MIPS Embedded
1024
* PA::                          HP PA Embedded
1025
* PowerPC:                      PowerPC
1026
* SH::                          Hitachi SH
1027
* Sparclet::                    Tsqware Sparclet
1028
* Sparclite::                   Fujitsu Sparclite
1029
* ST2000::                      Tandem ST2000
1030
* Z8000::                       Zilog Z8000
1031
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.