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

Subversion Repositories or1k

[/] [or1k/] [trunk/] [gdb-5.0/] [gdb/] [doc/] [gdbint.info-1] - Blame information for rev 107

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 106 markom
This is gdbint.info, produced by Makeinfo version 3.12f from
2
./gdbint.texinfo.
3
 
4
START-INFO-DIR-ENTRY
5
* Gdb-Internals: (gdbint).      The GNU debugger's internals.
6
END-INFO-DIR-ENTRY
7
 
8
   This file documents the internals of the GNU debugger GDB.
9
 
10
   Copyright 1990-1999 Free Software Foundation, Inc.  Contributed by
11
Cygnus Solutions.  Written by John Gilmore.  Second Edition by Stan
12
Shebs.
13
 
14
   Permission is granted to make and distribute verbatim copies of this
15
manual provided the copyright notice and this permission notice are
16
preserved on all copies.
17
 
18
   Permission is granted to copy or distribute modified versions of this
19
manual under the terms of the GPL (for which purpose this text may be
20
regarded as a program in the language TeX).
21
 
22

23
File: gdbint.info,  Node: Top,  Next: Requirements,  Up: (dir)
24
 
25
Scope of this Document
26
**********************
27
 
28
   This document documents the internals of the GNU debugger, GDB.  It
29
includes description of GDB's key algorithms and operations, as well as
30
the mechanisms that adapt GDB to specific hosts and targets.
31
 
32
* Menu:
33
 
34
* Requirements::
35
* Overall Structure::
36
* Algorithms::
37
* User Interface::
38
* Symbol Handling::
39
* Language Support::
40
* Host Definition::
41
* Target Architecture Definition::
42
* Target Vector Definition::
43
* Native Debugging::
44
* Support Libraries::
45
* Coding::
46
* Porting GDB::
47
* Testsuite::
48
* Hints::
49
 
50

51
File: gdbint.info,  Node: Requirements,  Next: Overall Structure,  Prev: Top,  Up: Top
52
 
53
Requirements
54
************
55
 
56
   Before diving into the internals, you should understand the formal
57
requirements and other expectations for GDB.  Although some of these may
58
seem obvious, there have been proposals for GDB that have run counter to
59
these requirements.
60
 
61
   First of all, GDB is a debugger.  It's not designed to be a front
62
panel for embedded systems.  It's not a text editor.  It's not a shell.
63
It's not a programming environment.
64
 
65
   GDB is an interactive tool.  Although a batch mode is available,
66
GDB's primary role is to interact with a human programmer.
67
 
68
   GDB should be responsive to the user.  A programmer hot on the trail
69
of a nasty bug, and operating under a looming deadline, is going to be
70
very impatient of everything, including the response time to debugger
71
commands.
72
 
73
   GDB should be relatively permissive, such as for expressions.  While
74
the compiler should be picky (or have the option to be made picky),
75
since source code lives for a long time usually, the programmer doing
76
debugging shouldn't be spending time figuring out to mollify the
77
debugger.
78
 
79
   GDB will be called upon to deal with really large programs.
80
Executable sizes of 50 to 100 megabytes occur regularly, and we've
81
heard reports of programs approaching 1 gigabyte in size.
82
 
83
   GDB should be able to run everywhere.  No other debugger is available
84
for even half as many configurations as GDB supports.
85
 
86

87
File: gdbint.info,  Node: Overall Structure,  Next: Algorithms,  Prev: Requirements,  Up: Top
88
 
89
Overall Structure
90
*****************
91
 
92
   GDB consists of three major subsystems: user interface, symbol
93
handling (the "symbol side"), and target system handling (the "target
94
side").
95
 
96
   Ther user interface consists of several actual interfaces, plus
97
supporting code.
98
 
99
   The symbol side consists of object file readers, debugging info
100
interpreters, symbol table management, source language expression
101
parsing, type and value printing.
102
 
103
   The target side consists of execution control, stack frame analysis,
104
and physical target manipulation.
105
 
106
   The target side/symbol side division is not formal, and there are a
107
number of exceptions.  For instance, core file support involves symbolic
108
elements (the basic core file reader is in BFD) and target elements (it
109
supplies the contents of memory and the values of registers).  Instead,
110
this division is useful for understanding how the minor subsystems
111
should fit together.
112
 
113
The Symbol Side
114
===============
115
 
116
   The symbolic side of GDB can be thought of as "everything you can do
117
in GDB without having a live program running".  For instance, you can
118
look at the types of variables, and evaluate many kinds of expressions.
119
 
120
The Target Side
121
===============
122
 
123
   The target side of GDB is the "bits and bytes manipulator".  Although
124
it may make reference to symbolic info here and there, most of the
125
target side will run with only a stripped executable available - or
126
even no executable at all, in remote debugging cases.
127
 
128
   Operations such as disassembly, stack frame crawls, and register
129
display, are able to work with no symbolic info at all.  In some cases,
130
such as disassembly, GDB will use symbolic info to present addresses
131
relative to symbols rather than as raw numbers, but it will work either
132
way.
133
 
134
Configurations
135
==============
136
 
137
   "Host" refers to attributes of the system where GDB runs.  "Target"
138
refers to the system where the program being debugged executes.  In
139
most cases they are the same machine, in which case a third type of
140
"Native" attributes come into play.
141
 
142
   Defines and include files needed to build on the host are host
143
support.  Examples are tty support, system defined types, host byte
144
order, host float format.
145
 
146
   Defines and information needed to handle the target format are target
147
dependent.  Examples are the stack frame format, instruction set,
148
breakpoint instruction, registers, and how to set up and tear down the
149
stack to call a function.
150
 
151
   Information that is only needed when the host and target are the
152
same, is native dependent.  One example is Unix child process support;
153
if the host and target are not the same, doing a fork to start the
154
target process is a bad idea.  The various macros needed for finding the
155
registers in the `upage', running `ptrace', and such are all in the
156
native-dependent files.
157
 
158
   Another example of native-dependent code is support for features that
159
are really part of the target environment, but which require `#include'
160
files that are only available on the host system.  Core file handling
161
and `setjmp' handling are two common cases.
162
 
163
   When you want to make GDB work "native" on a particular machine, you
164
have to include all three kinds of information.
165
 
166

167
File: gdbint.info,  Node: Algorithms,  Next: User Interface,  Prev: Overall Structure,  Up: Top
168
 
169
Algorithms
170
**********
171
 
172
   GDB uses a number of debugging-specific algorithms.  They are often
173
not very complicated, but get lost in the thicket of special cases and
174
real-world issues.  This chapter describes the basic algorithms and
175
mentions some of the specific target definitions that they use.
176
 
177
Frames
178
======
179
 
180
   A frame is a construct that GDB uses to keep track of calling and
181
called functions.
182
 
183
   `FRAME_FP' in the machine description has no meaning to the
184
machine-independent part of GDB, except that it is used when setting up
185
a new frame from scratch, as follows:
186
 
187
           create_new_frame (read_register (FP_REGNUM), read_pc ()));
188
 
189
   Other than that, all the meaning imparted to `FP_REGNUM' is imparted
190
by the machine-dependent code.  So, `FP_REGNUM' can have any value that
191
is convenient for the code that creates new frames.
192
(`create_new_frame' calls `INIT_EXTRA_FRAME_INFO' if it is defined;
193
that is where you should use the `FP_REGNUM' value, if your frames are
194
nonstandard.)
195
 
196
   Given a GDB frame, define `FRAME_CHAIN' to determine the address of
197
the calling function's frame.  This will be used to create a new GDB
198
frame struct, and then `INIT_EXTRA_FRAME_INFO' and `INIT_FRAME_PC' will
199
be called for the new frame.
200
 
201
Breakpoint Handling
202
===================
203
 
204
   In general, a breakpoint is a user-designated location in the program
205
where the user wants to regain control if program execution ever reaches
206
that location.
207
 
208
   There are two main ways to implement breakpoints; either as
209
"hardware" breakpoints or as "software" breakpoints.
210
 
211
   Hardware breakpoints are sometimes available as a builtin debugging
212
features with some chips.  Typically these work by having dedicated
213
register into which the breakpoint address may be stored.  If the PC
214
ever matches a value in a breakpoint registers, the CPU raises an
215
exception and reports it to GDB.  Another possibility is when an
216
emulator is in use; many emulators include circuitry that watches the
217
address lines coming out from the processor, and force it to stop if the
218
address matches a breakpoint's address.  A third possibility is that the
219
target already has the ability to do breakpoints somehow; for instance,
220
a ROM monitor may do its own software breakpoints.  So although these
221
are not literally "hardware breakpoints", from GDB's point of view they
222
work the same; GDB need not do nothing more than set the breakpoint and
223
wait for something to happen.
224
 
225
   Since they depend on hardware resources, hardware breakpoints may be
226
limited in number; when the user asks for more, GDB will start trying to
227
set software breakpoints.
228
 
229
   Software breakpoints require GDB to do somewhat more work.  The basic
230
theory is that GDB will replace a program instruction with a trap,
231
illegal divide, or some other instruction that will cause an exception,
232
and then when it's encountered, GDB will take the exception and stop the
233
program. When the user says to continue, GDB will restore the original
234
instruction, single-step, re-insert the trap, and continue on.
235
 
236
   Since it literally overwrites the program being tested, the program
237
area must be writeable, so this technique won't work on programs in
238
ROM.  It can also distort the behavior of programs that examine
239
themselves, although the situation would be highly unusual.
240
 
241
   Also, the software breakpoint instruction should be the smallest
242
size of instruction, so it doesn't overwrite an instruction that might
243
be a jump target, and cause disaster when the program jumps into the
244
middle of the breakpoint instruction.  (Strictly speaking, the
245
breakpoint must be no larger than the smallest interval between
246
instructions that may be jump targets; perhaps there is an architecture
247
where only even-numbered instructions may jumped to.)  Note that it's
248
possible for an instruction set not to have any instructions usable for
249
a software breakpoint, although in practice only the ARC has failed to
250
define such an instruction.
251
 
252
   The basic definition of the software breakpoint is the macro
253
`BREAKPOINT'.
254
 
255
   Basic breakpoint object handling is in `breakpoint.c'.  However,
256
much of the interesting breakpoint action is in `infrun.c'.
257
 
258
Single Stepping
259
===============
260
 
261
Signal Handling
262
===============
263
 
264
Thread Handling
265
===============
266
 
267
Inferior Function Calls
268
=======================
269
 
270
Longjmp Support
271
===============
272
 
273
   GDB has support for figuring out that the target is doing a
274
`longjmp' and for stopping at the target of the jump, if we are
275
stepping.  This is done with a few specialized internal breakpoints,
276
which are visible in the `maint info breakpoint' command.
277
 
278
   To make this work, you need to define a macro called
279
`GET_LONGJMP_TARGET', which will examine the `jmp_buf' structure and
280
extract the longjmp target address.  Since `jmp_buf' is target
281
specific, you will need to define it in the appropriate `tm-XYZ.h'
282
file.  Look in `tm-sun4os4.h' and `sparc-tdep.c' for examples of how to
283
do this.
284
 
285

286
File: gdbint.info,  Node: User Interface,  Next: Symbol Handling,  Prev: Algorithms,  Up: Top
287
 
288
User Interface
289
**************
290
 
291
   GDB has several user interfaces.  Although the command-line interface
292
is the most common and most familiar, there are others.
293
 
294
Command Interpreter
295
===================
296
 
297
   The command interpreter in GDB is fairly simple.  It is designed to
298
allow for the set of commands to be augmented dynamically, and also has
299
a recursive subcommand capability, where the first argument to a
300
command may itself direct a lookup on a different command list.
301
 
302
   For instance, the `set' command just starts a lookup on the
303
`setlist' command list, while `set thread' recurses to the
304
`set_thread_cmd_list'.
305
 
306
   To add commands in general, use `add_cmd'.  `add_com' adds to the
307
main command list, and should be used for those commands.  The usual
308
place to add commands is in the `_initialize_XYZ' routines at the ends
309
of most source files.
310
 
311
   Before removing commands from the command set it is a good idea to
312
deprecate them for some time.  Use `deprecate_cmd' on commands or
313
aliases to set the deprecated flag.  `deprecate_cmd' takes a `struct
314
cmd_list_element' as it's first argument.  You can use the return value
315
from `add_com' or `add_cmd' to deprecate the command immediately after
316
it is created.
317
 
318
   The first time a comamnd is used the user will be warned and offered
319
a replacement (if one exists). Note that the replacement string passed
320
to `deprecate_cmd' should be the full name of the command, i.e. the
321
entire string the user should type at the command line.
322
 
323
Console Printing
324
================
325
 
326
TUI
327
===
328
 
329
libgdb
330
======
331
 
332
   `libgdb' was an abortive project of years ago.  The theory was to
333
provide an API to GDB's functionality.
334
 
335

336
File: gdbint.info,  Node: Symbol Handling,  Next: Language Support,  Prev: User Interface,  Up: Top
337
 
338
Symbol Handling
339
***************
340
 
341
   Symbols are a key part of GDB's operation.  Symbols include
342
variables, functions, and types.
343
 
344
Symbol Reading
345
==============
346
 
347
   GDB reads symbols from "symbol files".  The usual symbol file is the
348
file containing the program which GDB is debugging.  GDB can be directed
349
to use a different file for symbols (with the `symbol-file' command),
350
and it can also read more symbols via the "add-file" and "load"
351
commands, or while reading symbols from shared libraries.
352
 
353
   Symbol files are initially opened by code in `symfile.c' using the
354
BFD library.  BFD identifies the type of the file by examining its
355
header.  `find_sym_fns' then uses this identification to locate a set
356
of symbol-reading functions.
357
 
358
   Symbol reading modules identify themselves to GDB by calling
359
`add_symtab_fns' during their module initialization.  The argument to
360
`add_symtab_fns' is a `struct sym_fns' which contains the name (or name
361
prefix) of the symbol format, the length of the prefix, and pointers to
362
four functions.  These functions are called at various times to process
363
symbol-files whose identification matches the specified prefix.
364
 
365
   The functions supplied by each module are:
366
 
367
`XYZ_symfile_init(struct sym_fns *sf)'
368
     Called from `symbol_file_add' when we are about to read a new
369
     symbol file.  This function should clean up any internal state
370
     (possibly resulting from half-read previous files, for example)
371
     and prepare to read a new symbol file. Note that the symbol file
372
     which we are reading might be a new "main" symbol file, or might
373
     be a secondary symbol file whose symbols are being added to the
374
     existing symbol table.
375
 
376
     The argument to `XYZ_symfile_init' is a newly allocated `struct
377
     sym_fns' whose `bfd' field contains the BFD for the new symbol
378
     file being read.  Its `private' field has been zeroed, and can be
379
     modified as desired.  Typically, a struct of private information
380
     will be `malloc''d, and a pointer to it will be placed in the
381
     `private' field.
382
 
383
     There is no result from `XYZ_symfile_init', but it can call
384
     `error' if it detects an unavoidable problem.
385
 
386
`XYZ_new_init()'
387
     Called from `symbol_file_add' when discarding existing symbols.
388
     This function need only handle the symbol-reading module's internal
389
     state; the symbol table data structures visible to the rest of GDB
390
     will be discarded by `symbol_file_add'.  It has no arguments and no
391
     result.  It may be called after `XYZ_symfile_init', if a new
392
     symbol table is being read, or may be called alone if all symbols
393
     are simply being discarded.
394
 
395
`XYZ_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)'
396
     Called from `symbol_file_add' to actually read the symbols from a
397
     symbol-file into a set of psymtabs or symtabs.
398
 
399
     `sf' points to the struct sym_fns originally passed to
400
     `XYZ_sym_init' for possible initialization.  `addr' is the offset
401
     between the file's specified start address and its true address in
402
     memory.  `mainline' is 1 if this is the main symbol table being
403
     read, and 0 if a secondary symbol file (e.g. shared library or
404
     dynamically loaded file) is being read.
405
 
406
   In addition, if a symbol-reading module creates psymtabs when
407
XYZ_symfile_read is called, these psymtabs will contain a pointer to a
408
function `XYZ_psymtab_to_symtab', which can be called from any point in
409
the GDB symbol-handling code.
410
 
411
`XYZ_psymtab_to_symtab (struct partial_symtab *pst)'
412
     Called from `psymtab_to_symtab' (or the PSYMTAB_TO_SYMTAB macro) if
413
     the psymtab has not already been read in and had its `pst->symtab'
414
     pointer set.  The argument is the psymtab to be fleshed-out into a
415
     symtab.  Upon return, pst->readin should have been set to 1, and
416
     pst->symtab should contain a pointer to the new corresponding
417
     symtab, or zero if there were no symbols in that part of the
418
     symbol file.
419
 
420
Partial Symbol Tables
421
=====================
422
 
423
   GDB has three types of symbol tables.
424
 
425
   * full symbol tables (symtabs).  These contain the main information
426
     about symbols and addresses.
427
 
428
   * partial symbol tables (psymtabs).  These contain enough
429
     information to know when to read the corresponding part of the full
430
     symbol table.
431
 
432
   * minimal symbol tables (msymtabs).  These contain information
433
     gleaned from non-debugging symbols.
434
 
435
 
436
   This section describes partial symbol tables.
437
 
438
   A psymtab is constructed by doing a very quick pass over an
439
executable file's debugging information.  Small amounts of information
440
are extracted - enough to identify which parts of the symbol table will
441
need to be re-read and fully digested later, when the user needs the
442
information.  The speed of this pass causes GDB to start up very
443
quickly.  Later, as the detailed rereading occurs, it occurs in small
444
pieces, at various times, and the delay therefrom is mostly invisible to
445
the user.
446
 
447
   The symbols that show up in a file's psymtab should be, roughly,
448
those visible to the debugger's user when the program is not running
449
code from that file.  These include external symbols and types, static
450
symbols and types, and enum values declared at file scope.
451
 
452
   The psymtab also contains the range of instruction addresses that the
453
full symbol table would represent.
454
 
455
   The idea is that there are only two ways for the user (or much of the
456
code in the debugger) to reference a symbol:
457
 
458
   * by its address (e.g. execution stops at some address which is
459
     inside a function in this file).  The address will be noticed to
460
     be in the range of this psymtab, and the full symtab will be read
461
     in.  `find_pc_function', `find_pc_line', and other `find_pc_...'
462
     functions handle this.
463
 
464
   * by its name (e.g. the user asks to print a variable, or set a
465
     breakpoint on a function).  Global names and file-scope names will
466
     be found in the psymtab, which will cause the symtab to be pulled
467
     in.  Local names will have to be qualified by a global name, or a
468
     file-scope name, in which case we will have already read in the
469
     symtab as we evaluated the qualifier.  Or, a local symbol can be
470
     referenced when we are "in" a local scope, in which case the first
471
     case applies.  `lookup_symbol' does most of the work here.
472
 
473
 
474
   The only reason that psymtabs exist is to cause a symtab to be read
475
in at the right moment.  Any symbol that can be elided from a psymtab,
476
while still causing that to happen, should not appear in it.  Since
477
psymtabs don't have the idea of scope, you can't put local symbols in
478
them anyway.  Psymtabs don't have the idea of the type of a symbol,
479
either, so types need not appear, unless they will be referenced by
480
name.
481
 
482
   It is a bug for GDB to behave one way when only a psymtab has been
483
read, and another way if the corresponding symtab has been read in.
484
Such bugs are typically caused by a psymtab that does not contain all
485
the visible symbols, or which has the wrong instruction address ranges.
486
 
487
   The psymtab for a particular section of a symbol-file (objfile)
488
could be thrown away after the symtab has been read in.  The symtab
489
should always be searched before the psymtab, so the psymtab will never
490
be used (in a bug-free environment).  Currently, psymtabs are allocated
491
on an obstack, and all the psymbols themselves are allocated in a pair
492
of large arrays on an obstack, so there is little to be gained by
493
trying to free them unless you want to do a lot more work.
494
 
495
Types
496
=====
497
 
498
   Fundamental Types (e.g., FT_VOID, FT_BOOLEAN).
499
 
500
   These are the fundamental types that GDB uses internally.
501
Fundamental types from the various debugging formats (stabs, ELF, etc)
502
are mapped into one of these.  They are basically a union of all
503
fundamental types that gdb knows about for all the languages that GDB
504
knows about.
505
 
506
   Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY).
507
 
508
   Each time GDB builds an internal type, it marks it with one of these
509
types.  The type may be a fundamental type, such as TYPE_CODE_INT, or a
510
derived type, such as TYPE_CODE_PTR which is a pointer to another type.
511
Typically, several FT_* types map to one TYPE_CODE_* type, and are
512
distinguished by other members of the type struct, such as whether the
513
type is signed or unsigned, and how many bits it uses.
514
 
515
   Builtin Types (e.g., builtin_type_void, builtin_type_char).
516
 
517
   These are instances of type structs that roughly correspond to
518
fundamental types and are created as global types for GDB to use for
519
various ugly historical reasons.  We eventually want to eliminate these.
520
Note for example that builtin_type_int initialized in gdbtypes.c is
521
basically the same as a TYPE_CODE_INT type that is initialized in
522
c-lang.c for an FT_INTEGER fundamental type.  The difference is that the
523
builtin_type is not associated with any particular objfile, and only one
524
instance exists, while c-lang.c builds as many TYPE_CODE_INT types as
525
needed, with each one associated with some particular objfile.
526
 
527
Object File Formats
528
===================
529
 
530
a.out
531
-----
532
 
533
   The `a.out' format is the original file format for Unix.  It
534
consists of three sections: text, data, and bss, which are for program
535
code, initialized data, and uninitialized data, respectively.
536
 
537
   The `a.out' format is so simple that it doesn't have any reserved
538
place for debugging information.  (Hey, the original Unix hackers used
539
`adb', which is a machine-language debugger.)  The only debugging
540
format for `a.out' is stabs, which is encoded as a set of normal
541
symbols with distinctive attributes.
542
 
543
   The basic `a.out' reader is in `dbxread.c'.
544
 
545
COFF
546
----
547
 
548
   The COFF format was introduced with System V Release 3 (SVR3) Unix.
549
COFF files may have multiple sections, each prefixed by a header.  The
550
number of sections is limited.
551
 
552
   The COFF specification includes support for debugging.  Although this
553
was a step forward, the debugging information was woefully limited.  For
554
instance, it was not possible to represent code that came from an
555
included file.
556
 
557
   The COFF reader is in `coffread.c'.
558
 
559
ECOFF
560
-----
561
 
562
   ECOFF is an extended COFF originally introduced for Mips and Alpha
563
workstations.
564
 
565
   The basic ECOFF reader is in `mipsread.c'.
566
 
567
XCOFF
568
-----
569
 
570
   The IBM RS/6000 running AIX uses an object file format called XCOFF.
571
The COFF sections, symbols, and line numbers are used, but debugging
572
symbols are dbx-style stabs whose strings are located in the `.debug'
573
section (rather than the string table).  For more information, see
574
*Note Top: (stabs)Top.
575
 
576
   The shared library scheme has a clean interface for figuring out what
577
shared libraries are in use, but the catch is that everything which
578
refers to addresses (symbol tables and breakpoints at least) needs to be
579
relocated for both shared libraries and the main executable.  At least
580
using the standard mechanism this can only be done once the program has
581
been run (or the core file has been read).
582
 
583
PE
584
--
585
 
586
   Windows 95 and NT use the PE (Portable Executable) format for their
587
executables.  PE is basically COFF with additional headers.
588
 
589
   While BFD includes special PE support, GDB needs only the basic COFF
590
reader.
591
 
592
ELF
593
---
594
 
595
   The ELF format came with System V Release 4 (SVR4) Unix.  ELF is
596
similar to COFF in being organized into a number of sections, but it
597
removes many of COFF's limitations.
598
 
599
   The basic ELF reader is in `elfread.c'.
600
 
601
SOM
602
---
603
 
604
   SOM is HP's object file and debug format (not to be confused with
605
IBM's SOM, which is a cross-language ABI).
606
 
607
   The SOM reader is in `hpread.c'.
608
 
609
Other File Formats
610
------------------
611
 
612
   Other file formats that have been supported by GDB include Netware
613
Loadable Modules (`nlmread.c'.
614
 
615
Debugging File Formats
616
======================
617
 
618
   This section describes characteristics of debugging information that
619
are independent of the object file format.
620
 
621
stabs
622
-----
623
 
624
   `stabs' started out as special symbols within the `a.out' format.
625
Since then, it has been encapsulated into other file formats, such as
626
COFF and ELF.
627
 
628
   While `dbxread.c' does some of the basic stab processing, including
629
for encapsulated versions, `stabsread.c' does the real work.
630
 
631
COFF
632
----
633
 
634
   The basic COFF definition includes debugging information.  The level
635
of support is minimal and non-extensible, and is not often used.
636
 
637
Mips debug (Third Eye)
638
----------------------
639
 
640
   ECOFF includes a definition of a special debug format.
641
 
642
   The file `mdebugread.c' implements reading for this format.
643
 
644
DWARF 1
645
-------
646
 
647
   DWARF 1 is a debugging format that was originally designed to be
648
used with ELF in SVR4 systems.
649
 
650
   The DWARF 1 reader is in `dwarfread.c'.
651
 
652
DWARF 2
653
-------
654
 
655
   DWARF 2 is an improved but incompatible version of DWARF 1.
656
 
657
   The DWARF 2 reader is in `dwarf2read.c'.
658
 
659
SOM
660
---
661
 
662
   Like COFF, the SOM definition includes debugging information.
663
 
664
Adding a New Symbol Reader to GDB
665
=================================
666
 
667
   If you are using an existing object file format (a.out, COFF, ELF,
668
etc), there is probably little to be done.
669
 
670
   If you need to add a new object file format, you must first add it to
671
BFD.  This is beyond the scope of this document.
672
 
673
   You must then arrange for the BFD code to provide access to the
674
debugging symbols.  Generally GDB will have to call swapping routines
675
from BFD and a few other BFD internal routines to locate the debugging
676
information.  As much as possible, GDB should not depend on the BFD
677
internal data structures.
678
 
679
   For some targets (e.g., COFF), there is a special transfer vector
680
used to call swapping routines, since the external data structures on
681
various platforms have different sizes and layouts.  Specialized
682
routines that will only ever be implemented by one object file format
683
may be called directly.  This interface should be described in a file
684
`bfd/libxyz.h', which is included by GDB.
685
 
686

687
File: gdbint.info,  Node: Language Support,  Next: Host Definition,  Prev: Symbol Handling,  Up: Top
688
 
689
Language Support
690
****************
691
 
692
   GDB's language support is mainly driven by the symbol reader,
693
although it is possible for the user to set the source language
694
manually.
695
 
696
   GDB chooses the source language by looking at the extension of the
697
file recorded in the debug info; `.c' means C, `.f' means Fortran, etc.
698
It may also use a special-purpose language identifier if the debug
699
format supports it, such as DWARF.
700
 
701
Adding a Source Language to GDB
702
===============================
703
 
704
   To add other languages to GDB's expression parser, follow the
705
following steps:
706
 
707
_Create the expression parser._
708
     This should reside in a file `LANG-exp.y'.  Routines for building
709
     parsed expressions into a `union exp_element' list are in
710
     `parse.c'.
711
 
712
     Since we can't depend upon everyone having Bison, and YACC produces
713
     parsers that define a bunch of global names, the following lines
714
     _must_ be included at the top of the YACC parser, to prevent the
715
     various parsers from defining the same global names:
716
 
717
          #define yyparse       LANG_parse
718
          #define yylex         LANG_lex
719
          #define yyerror       LANG_error
720
          #define yylval        LANG_lval
721
          #define yychar        LANG_char
722
          #define yydebug       LANG_debug
723
          #define yypact        LANG_pact
724
          #define yyr1          LANG_r1
725
          #define yyr2          LANG_r2
726
          #define yydef         LANG_def
727
          #define yychk         LANG_chk
728
          #define yypgo         LANG_pgo
729
          #define yyact         LANG_act
730
          #define yyexca        LANG_exca
731
          #define yyerrflag     LANG_errflag
732
          #define yynerrs       LANG_nerrs
733
 
734
     At the bottom of your parser, define a `struct language_defn' and
735
     initialize it with the right values for your language.  Define an
736
     `initialize_LANG' routine and have it call
737
     `add_language(LANG_language_defn)' to tell the rest of GDB that
738
     your language exists.  You'll need some other supporting variables
739
     and functions, which will be used via pointers from your
740
     `LANG_language_defn'.  See the declaration of `struct
741
     language_defn' in `language.h', and the other `*-exp.y' files, for
742
     more information.
743
 
744
_Add any evaluation routines, if necessary_
745
     If you need new opcodes (that represent the operations of the
746
     language), add them to the enumerated type in `expression.h'.  Add
747
     support code for these operations in `eval.c:evaluate_subexp()'.
748
     Add cases for new opcodes in two functions from `parse.c':
749
     `prefixify_subexp()' and `length_of_subexp()'.  These compute the
750
     number of `exp_element's that a given operation takes up.
751
 
752
_Update some existing code_
753
     Add an enumerated identifier for your language to the enumerated
754
     type `enum language' in `defs.h'.
755
 
756
     Update the routines in `language.c' so your language is included.
757
     These routines include type predicates and such, which (in some
758
     cases) are language dependent.  If your language does not appear
759
     in the switch statement, an error is reported.
760
 
761
     Also included in `language.c' is the code that updates the variable
762
     `current_language', and the routines that translate the
763
     `language_LANG' enumerated identifier into a printable string.
764
 
765
     Update the function `_initialize_language' to include your
766
     language.  This function picks the default language upon startup,
767
     so is dependent upon which languages that GDB is built for.
768
 
769
     Update `allocate_symtab' in `symfile.c' and/or symbol-reading code
770
     so that the language of each symtab (source file) is set properly.
771
     This is used to determine the language to use at each stack frame
772
     level.  Currently, the language is set based upon the extension of
773
     the source file.  If the language can be better inferred from the
774
     symbol information, please set the language of the symtab in the
775
     symbol-reading code.
776
 
777
     Add helper code to `expprint.c:print_subexp()' to handle any new
778
     expression opcodes you have added to `expression.h'.  Also, add the
779
     printed representations of your operators to `op_print_tab'.
780
 
781
_Add a place of call_
782
     Add a call to `LANG_parse()' and `LANG_error' in
783
     `parse.c:parse_exp_1()'.
784
 
785
_Use macros to trim code_
786
     The user has the option of building GDB for some or all of the
787
     languages.  If the user decides to build GDB for the language
788
     LANG, then every file dependent on `language.h' will have the
789
     macro `_LANG_LANG' defined in it.  Use `#ifdef's to leave out
790
     large routines that the user won't need if he or she is not using
791
     your language.
792
 
793
     Note that you do not need to do this in your YACC parser, since if
794
     GDB is not build for LANG, then `LANG-exp.tab.o' (the compiled
795
     form of your parser) is not linked into GDB at all.
796
 
797
     See the file `configure.in' for how GDB is configured for different
798
     languages.
799
 
800
_Edit `Makefile.in'_
801
     Add dependencies in `Makefile.in'.  Make sure you update the macro
802
     variables such as `HFILES' and `OBJS', otherwise your code may not
803
     get linked in, or, worse yet, it may not get `tar'red into the
804
     distribution!
805
 
806

807
File: gdbint.info,  Node: Host Definition,  Next: Target Architecture Definition,  Prev: Language Support,  Up: Top
808
 
809
Host Definition
810
***************
811
 
812
   With the advent of autoconf, it's rarely necessary to have host
813
definition machinery anymore.
814
 
815
Adding a New Host
816
=================
817
 
818
   Most of GDB's host configuration support happens via autoconf.  It
819
should be rare to need new host-specific definitions.  GDB still uses
820
the host-specific definitions and files listed below, but these mostly
821
exist for historical reasons, and should eventually disappear.
822
 
823
   Several files control GDB's configuration for host systems:
824
 
825
`gdb/config/ARCH/XYZ.mh'
826
     Specifies Makefile fragments needed when hosting on machine XYZ.
827
     In particular, this lists the required machine-dependent object
828
     files, by defining `XDEPFILES=...'.  Also specifies the header file
829
     which describes host XYZ, by defining `XM_FILE= xm-XYZ.h'.  You
830
     can also define `CC', `SYSV_DEFINE', `XM_CFLAGS', `XM_ADD_FILES',
831
     `XM_CLIBS', `XM_CDEPS', etc.; see `Makefile.in'.
832
 
833
`gdb/config/ARCH/xm-XYZ.h'
834
     (`xm.h' is a link to this file, created by configure).  Contains C
835
     macro definitions describing the host system environment, such as
836
     byte order, host C compiler and library.
837
 
838
`gdb/XYZ-xdep.c'
839
     Contains any miscellaneous C code required for this machine as a
840
     host.  On most machines it doesn't exist at all.  If it does
841
     exist, put `XYZ-xdep.o' into the `XDEPFILES' line in
842
     `gdb/config/ARCH/XYZ.mh'.
843
 
844
Generic Host Support Files
845
--------------------------
846
 
847
   There are some "generic" versions of routines that can be used by
848
various systems.  These can be customized in various ways by macros
849
defined in your `xm-XYZ.h' file.  If these routines work for the XYZ
850
host, you can just include the generic file's name (with `.o', not
851
`.c') in `XDEPFILES'.
852
 
853
   Otherwise, if your machine needs custom support routines, you will
854
need to write routines that perform the same functions as the generic
855
file.  Put them into `XYZ-xdep.c', and put `XYZ-xdep.o' into
856
`XDEPFILES'.
857
 
858
`ser-unix.c'
859
     This contains serial line support for Unix systems.  This is always
860
     included, via the makefile variable `SER_HARDWIRE'; override this
861
     variable in the `.mh' file to avoid it.
862
 
863
`ser-go32.c'
864
     This contains serial line support for 32-bit programs running
865
     under DOS, using the GO32 execution environment.
866
 
867
`ser-tcp.c'
868
     This contains generic TCP support using sockets.
869
 
870
Host Conditionals
871
=================
872
 
873
   When GDB is configured and compiled, various macros are defined or
874
left undefined, to control compilation based on the attributes of the
875
host system.  These macros and their meanings (or if the meaning is not
876
documented here, then one of the source files where they are used is
877
indicated) are:
878
 
879
`GDBINIT_FILENAME'
880
     The default name of GDB's initialization file (normally
881
     `.gdbinit').
882
 
883
`MEM_FNS_DECLARED'
884
     Your host config file defines this if it includes declarations of
885
     `memcpy' and `memset'.  Define this to avoid conflicts between the
886
     native include files and the declarations in `defs.h'.
887
 
888
`NO_STD_REGS'
889
     This macro is deprecated.
890
 
891
`NO_SYS_FILE'
892
     Define this if your system does not have a `'.
893
 
894
`SIGWINCH_HANDLER'
895
     If your host defines `SIGWINCH', you can define this to be the name
896
     of a function to be called if `SIGWINCH' is received.
897
 
898
`SIGWINCH_HANDLER_BODY'
899
     Define this to expand into code that will define the function
900
     named by the expansion of `SIGWINCH_HANDLER'.
901
 
902
`ALIGN_STACK_ON_STARTUP'
903
     Define this if your system is of a sort that will crash in
904
     `tgetent' if the stack happens not to be longword-aligned when
905
     `main' is called.  This is a rare situation, but is known to occur
906
     on several different types of systems.
907
 
908
`CRLF_SOURCE_FILES'
909
     Define this if host files use `\r\n' rather than `\n' as a line
910
     terminator.  This will cause source file listings to omit `\r'
911
     characters when printing and it will allow \r\n line endings of
912
     files which are "sourced" by gdb.  It must be possible to open
913
     files in binary mode using `O_BINARY' or, for fopen, `"rb"'.
914
 
915
`DEFAULT_PROMPT'
916
     The default value of the prompt string (normally `"(gdb) "').
917
 
918
`DEV_TTY'
919
     The name of the generic TTY device, defaults to `"/dev/tty"'.
920
 
921
`FCLOSE_PROVIDED'
922
     Define this if the system declares `fclose' in the headers included
923
     in `defs.h'.  This isn't needed unless your compiler is unusually
924
     anal.
925
 
926
`FOPEN_RB'
927
     Define this if binary files are opened the same way as text files.
928
 
929
`GETENV_PROVIDED'
930
     Define this if the system declares `getenv' in its headers included
931
     in `defs.h'. This isn't needed unless your compiler is unusually
932
     anal.
933
 
934
`HAVE_MMAP'
935
     In some cases, use the system call `mmap' for reading symbol
936
     tables.  For some machines this allows for sharing and quick
937
     updates.
938
 
939
`HAVE_SIGSETMASK'
940
     Define this if the host system has job control, but does not define
941
     `sigsetmask()'.  Currently, this is only true of the RS/6000.
942
 
943
`HAVE_TERMIO'
944
     Define this if the host system has `termio.h'.
945
 
946
`HOST_BYTE_ORDER'
947
     The ordering of bytes in the host.  This must be defined to be
948
     either `BIG_ENDIAN' or `LITTLE_ENDIAN'.
949
 
950
`INT_MAX'
951
 
952
`INT_MIN'
953
 
954
`LONG_MAX'
955
 
956
`UINT_MAX'
957
 
958
`ULONG_MAX'
959
     Values for host-side constants.
960
 
961
`ISATTY'
962
     Substitute for isatty, if not available.
963
 
964
`LONGEST'
965
     This is the longest integer type available on the host.  If not
966
     defined, it will default to `long long' or `long', depending on
967
     `CC_HAS_LONG_LONG'.
968
 
969
`CC_HAS_LONG_LONG'
970
     Define this if the host C compiler supports "long long".  This is
971
     set by the configure script.
972
 
973
`PRINTF_HAS_LONG_LONG'
974
     Define this if the host can handle printing of long long integers
975
     via the printf format directive "ll". This is set by the configure
976
     script.
977
 
978
`HAVE_LONG_DOUBLE'
979
     Define this if the host C compiler supports "long double".  This is
980
     set by the configure script.
981
 
982
`PRINTF_HAS_LONG_DOUBLE'
983
     Define this if the host can handle printing of long double
984
     float-point numbers via the printf format directive "Lg". This is
985
     set by the configure script.
986
 
987
`SCANF_HAS_LONG_DOUBLE'
988
     Define this if the host can handle the parsing of long double
989
     float-point numbers via the scanf format directive directive "Lg".
990
     This is set by the configure script.
991
 
992
`LSEEK_NOT_LINEAR'
993
     Define this if `lseek (n)' does not necessarily move to byte number
994
     `n' in the file.  This is only used when reading source files.  It
995
     is normally faster to define `CRLF_SOURCE_FILES' when possible.
996
 
997
`L_SET'
998
     This macro is used as the argument to lseek (or, most commonly,
999
     bfd_seek).  FIXME, should be replaced by SEEK_SET instead, which
1000
     is the POSIX equivalent.
1001
 
1002
`MALLOC_INCOMPATIBLE'
1003
     Define this if the system's prototype for `malloc' differs from the
1004
     ANSI definition.
1005
 
1006
`MMAP_BASE_ADDRESS'
1007
     When using HAVE_MMAP, the first mapping should go at this address.
1008
 
1009
`MMAP_INCREMENT'
1010
     when using HAVE_MMAP, this is the increment between mappings.
1011
 
1012
`NEED_POSIX_SETPGID'
1013
     Define this to use the POSIX version of `setpgid' to determine
1014
     whether job control is available.
1015
 
1016
`NORETURN'
1017
     If defined, this should be one or more tokens, such as `volatile',
1018
     that can be used in both the declaration and definition of
1019
     functions to indicate that they never return.  The default is
1020
     already set correctly if compiling with GCC.  This will almost
1021
     never need to be defined.
1022
 
1023
`ATTR_NORETURN'
1024
     If defined, this should be one or more tokens, such as
1025
     `__attribute__ ((noreturn))', that can be used in the declarations
1026
     of functions to indicate that they never return.  The default is
1027
     already set correctly if compiling with GCC.  This will almost
1028
     never need to be defined.
1029
 
1030
`USE_GENERIC_DUMMY_FRAMES'
1031
     Define this to 1 if the target is using the generic inferior
1032
     function call code.  See `blockframe.c' for more information.
1033
 
1034
`USE_MMALLOC'
1035
     GDB will use the `mmalloc' library for memory allocation for symbol
1036
     reading if this symbol is defined.  Be careful defining it since
1037
     there are systems on which `mmalloc' does not work for some
1038
     reason.  One example is the DECstation, where its RPC library
1039
     can't cope with our redefinition of `malloc' to call `mmalloc'.
1040
     When defining `USE_MMALLOC', you will also have to set `MMALLOC'
1041
     in the Makefile, to point to the mmalloc library.  This define is
1042
     set when you configure with -with-mmalloc.
1043
 
1044
`NO_MMCHECK'
1045
     Define this if you are using `mmalloc', but don't want the overhead
1046
     of checking the heap with `mmcheck'.  Note that on some systems,
1047
     the C runtime makes calls to malloc prior to calling `main', and if
1048
     `free' is ever called with these pointers after calling `mmcheck'
1049
     to enable checking, a memory corruption abort is certain to occur.
1050
     These systems can still use mmalloc, but must define NO_MMCHECK.
1051
 
1052
`MMCHECK_FORCE'
1053
     Define this to 1 if the C runtime allocates memory prior to
1054
     `mmcheck' being called, but that memory is never freed so we don't
1055
     have to worry about it triggering a memory corruption abort.  The
1056
     default is 0, which means that `mmcheck' will only install the heap
1057
     checking functions if there has not yet been any memory allocation
1058
     calls, and if it fails to install the functions, gdb will issue a
1059
     warning.  This is currently defined if you configure using
1060
     -with-mmalloc.
1061
 
1062
`NO_SIGINTERRUPT'
1063
     Define this to indicate that siginterrupt() is not available.
1064
 
1065
`R_OK'
1066
     Define if this is not in a system .h file.
1067
 
1068
`SEEK_CUR'
1069
 
1070
`SEEK_SET'
1071
     Define these to appropriate value for the system lseek(), if not
1072
     already defined.
1073
 
1074
`STOP_SIGNAL'
1075
     This is the signal for stopping GDB.  Defaults to SIGTSTP.  (Only
1076
     redefined for the Convex.)
1077
 
1078
`USE_O_NOCTTY'
1079
     Define this if the interior's tty should be opened with the
1080
     O_NOCTTY flag.  (FIXME: This should be a native-only flag, but
1081
     `inflow.c' is always linked in.)
1082
 
1083
`USG'
1084
     Means that System V (prior to SVR4) include files are in use.
1085
     (FIXME: This symbol is abused in `infrun.c', `regex.c',
1086
     `remote-nindy.c', and `utils.c' for other things, at the moment.)
1087
 
1088
`lint'
1089
     Define this to help placate lint in some situations.
1090
 
1091
`volatile'
1092
     Define this to override the defaults of `__volatile__' or `/**/'.
1093
 

powered by: WebSVN 2.1.0

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