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

Subversion Repositories or1k

[/] [or1k/] [trunk/] [gdb-5.0/] [gdb/] [doc/] [stabs.info-3] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 363 markom
This is stabs.info, produced by makeinfo version 4.0 from
2 106 markom
./stabs.texinfo.
3
 
4
START-INFO-DIR-ENTRY
5
* Stabs: (stabs).                 The "stabs" debugging information format.
6
END-INFO-DIR-ENTRY
7
 
8
   This document describes the stabs debugging symbol tables.
9
 
10
   Copyright 1992, 93, 94, 95, 97, 1998 Free Software Foundation, Inc.
11
Contributed by Cygnus Support.  Written by Julia Menapace, Jim Kingdon,
12
and David MacKenzie.
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: stabs.info,  Node: Class Instance,  Next: Methods,  Prev: Simple Classes,  Up: Cplusplus
24
 
25
Class Instance
26
==============
27
 
28
   As shown above, describing even a simple C++ class definition is
29
accomplished by massively extending the stab format used in C to
30
describe structure types.  However, once the class is defined, C stabs
31
with no modifications can be used to describe class instances.  The
32
following source:
33
 
34
     main () {
35
             baseA AbaseA;
36
     }
37
 
38
yields the following stab describing the class instance.  It looks no
39
different from a standard C stab describing a local variable.
40
 
41
     .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset
42
 
43
     .stabs "AbaseA:20",128,0,0,-20
44
 
45

46
File: stabs.info,  Node: Methods,  Next: Method Type Descriptor,  Prev: Class Instance,  Up: Cplusplus
47
 
48
Method Definition
49
=================
50
 
51
   The class definition shown above declares Ameth.  The C++ source
52
below defines Ameth:
53
 
54
     int
55
     baseA::Ameth(int in, char other)
56
     {
57
             return in;
58
     };
59
 
60
   This method definition yields three stabs following the code of the
61
method.  One stab describes the method itself and following two describe
62
its parameters.  Although there is only one formal argument all methods
63
have an implicit argument which is the `this' pointer.  The `this'
64
pointer is a pointer to the object on which the method was called.  Note
65
that the method name is mangled to encode the class name and argument
66
types.  Name mangling is described in the ARM (`The Annotated C++
67
Reference Manual', by Ellis and Stroustrup, ISBN 0-201-51459-1);
68
`gpcompare.texi' in Cygnus GCC distributions describes the differences
69
between GNU mangling and ARM mangling.
70
 
71
     .stabs "name:symbol_desriptor(global function)return_type(int)",
72
             N_FUN, NIL, NIL, code_addr_of_method_start
73
 
74
     .stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic
75
 
76
   Here is the stab for the `this' pointer implicit argument.  The name
77
of the `this' pointer is always `this'.  Type 19, the `this' pointer is
78
defined as a pointer to type 20, `baseA', but a stab defining `baseA'
79
has not yet been emited.  Since the compiler knows it will be emited
80
shortly, here it just outputs a cross reference to the undefined
81
symbol, by prefixing the symbol name with `xs'.
82
 
83
     .stabs "name:sym_desc(register param)type_def(19)=
84
             type_desc(ptr to)type_ref(baseA)=
85
             type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number
86
 
87
     .stabs "this:P19=*20=xsbaseA:",64,0,0,8
88
 
89
   The stab for the explicit integer argument looks just like a
90
parameter to a C function.  The last field of the stab is the offset
91
from the argument pointer, which in most systems is the same as the
92
frame pointer.
93
 
94
     .stabs "name:sym_desc(value parameter)type_ref(int)",
95
             N_PSYM,NIL,NIL,offset_from_arg_ptr
96
 
97
     .stabs "in:p1",160,0,0,72
98
 
99
   << The examples that follow are based on A1.C >>
100
 
101

102
File: stabs.info,  Node: Method Type Descriptor,  Next: Member Type Descriptor,  Prev: Methods,  Up: Cplusplus
103
 
104
The `#' Type Descriptor
105
=======================
106
 
107
   This is used to describe a class method.  This is a function which
108
takes an extra argument as its first argument, for the `this' pointer.
109
 
110
   If the `#' is immediately followed by another `#', the second one
111
will be followed by the return type and a semicolon.  The class and
112
argument types are not specified, and must be determined by demangling
113
the name of the method if it is available.
114
 
115
   Otherwise, the single `#' is followed by the class type, a comma,
116
the return type, a comma, and zero or more parameter types separated by
117
commas.  The list of arguments is terminated by a semicolon.  In the
118
debugging output generated by gcc, a final argument type of `void'
119
indicates a method which does not take a variable number of arguments.
120
If the final argument type of `void' does not appear, the method was
121
declared with an ellipsis.
122
 
123
   Note that although such a type will normally be used to describe
124
fields in structures, unions, or classes, for at least some versions of
125
the compiler it can also be used in other contexts.
126
 
127

128
File: stabs.info,  Node: Member Type Descriptor,  Next: Protections,  Prev: Method Type Descriptor,  Up: Cplusplus
129
 
130
The `@' Type Descriptor
131
=======================
132
 
133
   The `@' type descriptor is for a member (class and variable) type.
134
It is followed by type information for the offset basetype, a comma, and
135
type information for the type of the field being pointed to.  (FIXME:
136
this is acknowledged to be gibberish.  Can anyone say what really goes
137
here?).
138
 
139
   Note that there is a conflict between this and type attributes
140 363 markom
(*note String Field::); both use type descriptor `@'.  Fortunately, the
141
`@' type descriptor used in this C++ sense always will be followed by a
142
digit, `(', or `-', and type attributes never start with those things.
143 106 markom
 
144

145
File: stabs.info,  Node: Protections,  Next: Method Modifiers,  Prev: Member Type Descriptor,  Up: Cplusplus
146
 
147
Protections
148
===========
149
 
150
   In the simple class definition shown above all member data and
151
functions were publicly accessable.  The example that follows contrasts
152
public, protected and privately accessable fields and shows how these
153
protections are encoded in C++ stabs.
154
 
155
   If the character following the `FIELD-NAME:' part of the string is
156
`/', then the next character is the visibility.  `0' means private, `1'
157
means protected, and `2' means public.  Debuggers should ignore
158
visibility characters they do not recognize, and assume a reasonable
159
default (such as public) (GDB 4.11 does not, but this should be fixed
160
in the next GDB release).  If no visibility is specified the field is
161
public.  The visibility `9' means that the field has been optimized out
162
and is public (there is no way to specify an optimized out field with a
163
private or protected visibility).  Visibility `9' is not supported by
164
GDB 4.11; this should be fixed in the next GDB release.
165
 
166
   The following C++ source:
167
 
168
     class vis {
169
     private:
170
             int   priv;
171
     protected:
172
             char  prot;
173
     public:
174
             float pub;
175
     };
176
 
177
generates the following stab:
178
 
179
     # 128 is N_LSYM
180
     .stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0
181
 
182
   `vis:T19=s12' indicates that type number 19 is a 12 byte structure
183
named `vis' The `priv' field has public visibility (`/0'), type int
184
(`1'), and offset and size `,0,32;'.  The `prot' field has protected
185
visibility (`/1'), type char (`2') and offset and size `,32,8;'.  The
186
`pub' field has type float (`12'), and offset and size `,64,32;'.
187
 
188
   Protections for member functions are signified by one digit embeded
189
in the field part of the stab describing the method.  The digit is 0 if
190
private, 1 if protected and 2 if public.  Consider the C++ class
191
definition below:
192
 
193
     class all_methods {
194
     private:
195
             int   priv_meth(int in){return in;};
196
     protected:
197
             char  protMeth(char in){return in;};
198
     public:
199
             float pubMeth(float in){return in;};
200
     };
201
 
202
   It generates the following stab.  The digit in question is to the
203
left of an `A' in each case.  Notice also that in this case two symbol
204
descriptors apply to the class name struct tag and struct type.
205
 
206
     .stabs "class_name:sym_desc(struct tag&type)type_def(21)=
207
             sym_desc(struct)struct_bytes(1)
208
             meth_name::type_def(22)=sym_desc(method)returning(int);
209
             :args(int);protection(private)modifier(normal)virtual(no);
210
             meth_name::type_def(23)=sym_desc(method)returning(char);
211
             :args(char);protection(protected)modifier(normal)virual(no);
212
             meth_name::type_def(24)=sym_desc(method)returning(float);
213
             :args(float);protection(public)modifier(normal)virtual(no);;",
214
             N_LSYM,NIL,NIL,NIL
215
 
216
     .stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.;
217
             pubMeth::24=##12;:f;2A.;;",128,0,0,0
218
 
219

220
File: stabs.info,  Node: Method Modifiers,  Next: Virtual Methods,  Prev: Protections,  Up: Cplusplus
221
 
222
Method Modifiers (`const', `volatile', `const volatile')
223
========================================================
224
 
225
   << based on a6.C >>
226
 
227
   In the class example described above all the methods have the normal
228
modifier.  This method modifier information is located just after the
229
protection information for the method.  This field has four possible
230
character values.  Normal methods use `A', const methods use `B',
231
volatile methods use `C', and const volatile methods use `D'.  Consider
232
the class definition below:
233
 
234
     class A {
235
     public:
236
             int ConstMeth (int arg) const { return arg; };
237
             char VolatileMeth (char arg) volatile { return arg; };
238
             float ConstVolMeth (float arg) const volatile {return arg; };
239
     };
240
 
241
   This class is described by the following stab:
242
 
243
     .stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1)
244
             meth_name(ConstMeth)::type_def(21)sym_desc(method)
245
             returning(int);:arg(int);protection(public)modifier(const)virtual(no);
246
             meth_name(VolatileMeth)::type_def(22)=sym_desc(method)
247
             returning(char);:arg(char);protection(public)modifier(volatile)virt(no)
248
             meth_name(ConstVolMeth)::type_def(23)=sym_desc(method)
249
             returning(float);:arg(float);protection(public)modifer(const volatile)
250
             virtual(no);;", ...
251
 
252
     .stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.;
253
                  ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0
254
 
255

256
File: stabs.info,  Node: Virtual Methods,  Next: Inheritence,  Prev: Method Modifiers,  Up: Cplusplus
257
 
258
Virtual Methods
259
===============
260
 
261
   << The following examples are based on a4.C >>
262
 
263
   The presence of virtual methods in a class definition adds additional
264
data to the class description.  The extra data is appended to the
265
description of the virtual method and to the end of the class
266
description.  Consider the class definition below:
267
 
268
     class A {
269
     public:
270
             int Adat;
271
             virtual int A_virt (int arg) { return arg; };
272
     };
273
 
274
   This results in the stab below describing class A.  It defines a new
275
type (20) which is an 8 byte structure.  The first field of the class
276
struct is `Adat', an integer, starting at structure offset 0 and
277
occupying 32 bits.
278
 
279
   The second field in the class struct is not explicitly defined by the
280
C++ class definition but is implied by the fact that the class contains
281
a virtual method.  This field is the vtable pointer.  The name of the
282
vtable pointer field starts with `$vf' and continues with a type
283
reference to the class it is part of.  In this example the type
284
reference for class A is 20 so the name of its vtable pointer field is
285
`$vf20', followed by the usual colon.
286
 
287
   Next there is a type definition for the vtable pointer type (21).
288
This is in turn defined as a pointer to another new type (22).
289
 
290
   Type 22 is the vtable itself, which is defined as an array, indexed
291
by a range of integers between 0 and 1, and whose elements are of type
292
17.  Type 17 was the vtable record type defined by the boilerplate C++
293
type definitions, as shown earlier.
294
 
295
   The bit offset of the vtable pointer field is 32.  The number of bits
296
in the field are not specified when the field is a vtable pointer.
297
 
298
   Next is the method definition for the virtual member function
299
`A_virt'.  Its description starts out using the same format as the
300
non-virtual member functions described above, except instead of a dot
301
after the `A' there is an asterisk, indicating that the function is
302
virtual.  Since is is virtual some addition information is appended to
303
the end of the method description.
304
 
305
   The first number represents the vtable index of the method.  This is
306
a 32 bit unsigned number with the high bit set, followed by a
307
semi-colon.
308
 
309
   The second number is a type reference to the first base class in the
310
inheritence hierarchy defining the virtual member function.  In this
311
case the class stab describes a base class so the virtual function is
312
not overriding any other definition of the method.  Therefore the
313
reference is to the type number of the class that the stab is
314
describing (20).
315
 
316
   This is followed by three semi-colons.  One marks the end of the
317
current sub-section, one marks the end of the method field, and the
318
third marks the end of the struct definition.
319
 
320
   For classes containing virtual functions the very last section of the
321
string part of the stab holds a type reference to the first base class.
322
This is preceeded by `~%' and followed by a final semi-colon.
323
 
324
     .stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8)
325
             field_name(Adat):type_ref(int),bit_offset(0),field_bits(32);
326
             field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)=
327
             sym_desc(array)index_type_ref(range of int from 0 to 1);
328
             elem_type_ref(vtbl elem type),
329
             bit_offset(32);
330
             meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int);
331
             :arg_type(int),protection(public)normal(yes)virtual(yes)
332
             vtable_index(1);class_first_defining(A);;;~%first_base(A);",
333
             N_LSYM,NIL,NIL,NIL
334
 
335
     .stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
336
             A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
337
 
338

339
File: stabs.info,  Node: Inheritence,  Next: Virtual Base Classes,  Prev: Virtual Methods,  Up: Cplusplus
340
 
341
Inheritence
342
===========
343
 
344
   Stabs describing C++ derived classes include additional sections that
345
describe the inheritence hierarchy of the class.  A derived class stab
346
also encodes the number of base classes.  For each base class it tells
347
if the base class is virtual or not, and if the inheritence is private
348
or public.  It also gives the offset into the object of the portion of
349
the object corresponding to each base class.
350
 
351
   This additional information is embeded in the class stab following
352
the number of bytes in the struct.  First the number of base classes
353
appears bracketed by an exclamation point and a comma.
354
 
355
   Then for each base type there repeats a series: a virtual character,
356
a visibilty character, a number, a comma, another number, and a
357
semi-colon.
358
 
359
   The virtual character is `1' if the base class is virtual and `0' if
360
not.  The visibility character is `2' if the derivation is public, `1'
361
if it is protected, and `0' if it is private.  Debuggers should ignore
362
virtual or visibility characters they do not recognize, and assume a
363
reasonable default (such as public and non-virtual) (GDB 4.11 does not,
364
but this should be fixed in the next GDB release).
365
 
366
   The number following the virtual and visibility characters is the
367
offset from the start of the object to the part of the object
368
pertaining to the base class.
369
 
370
   After the comma, the second number is a type_descriptor for the base
371
type.  Finally a semi-colon ends the series, which repeats for each
372
base class.
373
 
374
   The source below defines three base classes `A', `B', and `C' and
375
the derived class `D'.
376
 
377
     class A {
378
     public:
379
             int Adat;
380
             virtual int A_virt (int arg) { return arg; };
381
     };
382
 
383
     class B {
384
     public:
385
             int B_dat;
386
             virtual int B_virt (int arg) {return arg; };
387
     };
388
 
389
     class C {
390
     public:
391
             int Cdat;
392
             virtual int C_virt (int arg) {return arg; };
393
     };
394
 
395
     class D : A, virtual B, public C {
396
     public:
397
             int Ddat;
398
             virtual int A_virt (int arg ) { return arg+1; };
399
             virtual int B_virt (int arg)  { return arg+2; };
400
             virtual int C_virt (int arg)  { return arg+3; };
401
             virtual int D_virt (int arg)  { return arg; };
402
     };
403
 
404
   Class stabs similar to the ones described earlier are generated for
405
each base class.
406
 
407
     .stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
408
             A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
409
 
410
     .stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1;
411
             :i;2A*-2147483647;25;;;~%25;",128,0,0,0
412
 
413
     .stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1;
414
             :i;2A*-2147483647;28;;;~%28;",128,0,0,0
415
 
416
   In the stab describing derived class `D' below, the information about
417
the derivation of this class is encoded as follows.
418
 
419
     .stabs "derived_class_name:symbol_descriptors(struct tag&type)=
420
             type_descriptor(struct)struct_bytes(32)!num_bases(3),
421
             base_virtual(no)inheritence_public(no)base_offset(0),
422
             base_class_type_ref(A);
423
             base_virtual(yes)inheritence_public(no)base_offset(NIL),
424
             base_class_type_ref(B);
425
             base_virtual(no)inheritence_public(yes)base_offset(64),
426
             base_class_type_ref(C); ...
427
 
428
     .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:
429
             1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt:
430
             :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;
431
             28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
432
 
433

434
File: stabs.info,  Node: Virtual Base Classes,  Next: Static Members,  Prev: Inheritence,  Up: Cplusplus
435
 
436
Virtual Base Classes
437
====================
438
 
439
   A derived class object consists of a concatenation in memory of the
440
data areas defined by each base class, starting with the leftmost and
441
ending with the rightmost in the list of base classes.  The exception
442
to this rule is for virtual inheritence.  In the example above, class
443
`D' inherits virtually from base class `B'.  This means that an
444
instance of a `D' object will not contain its own `B' part but merely a
445
pointer to a `B' part, known as a virtual base pointer.
446
 
447
   In a derived class stab, the base offset part of the derivation
448
information, described above, shows how the base class parts are
449
ordered.  The base offset for a virtual base class is always given as 0.
450
Notice that the base offset for `B' is given as 0 even though `B' is
451
not the first base class.  The first base class `A' starts at offset 0.
452
 
453
   The field information part of the stab for class `D' describes the
454
field which is the pointer to the virtual base class `B'. The vbase
455
pointer name is `$vb' followed by a type reference to the virtual base
456
class.  Since the type id for `B' in this example is 25, the vbase
457
pointer name is `$vb25'.
458
 
459
     .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1,
460
            160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i;
461
            2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt:
462
            :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
463
 
464
   Following the name and a semicolon is a type reference describing the
465
type of the virtual base class pointer, in this case 24.  Type 24 was
466
defined earlier as the type of the `B' class `this' pointer.  The
467
`this' pointer for a class is a pointer to the class type.
468
 
469
     .stabs "this:P24=*25=xsB:",64,0,0,8
470
 
471
   Finally the field offset part of the vbase pointer field description
472
shows that the vbase pointer is the first field in the `D' object,
473
before any data fields defined by the class.  The layout of a `D' class
474
object is a follows, `Adat' at 0, the vtable pointer for `A' at 32,
475
`Cdat' at 64, the vtable pointer for C at 96, the virtual base pointer
476
for `B' at 128, and `Ddat' at 160.
477
 
478

479
File: stabs.info,  Node: Static Members,  Prev: Virtual Base Classes,  Up: Cplusplus
480
 
481
Static Members
482
==============
483
 
484
   The data area for a class is a concatenation of the space used by the
485
data members of the class.  If the class has virtual methods, a vtable
486
pointer follows the class data.  The field offset part of each field
487
description in the class stab shows this ordering.
488
 
489
   << How is this reflected in stabs?  See Cygnus bug #677 for some
490
info.  >>
491
 
492

493
File: stabs.info,  Node: Stab Types,  Next: Symbol Descriptors,  Prev: Cplusplus,  Up: Top
494
 
495
Table of Stab Types
496
*******************
497
 
498
   The following are all the possible values for the stab type field,
499
for a.out files, in numeric order.  This does not apply to XCOFF, but
500 363 markom
it does apply to stabs in sections (*note Stab Sections::).  Stabs in
501 106 markom
ECOFF use these values but add 0x8f300 to distinguish them from non-stab
502
symbols.
503
 
504
   The symbolic names are defined in the file `include/aout/stabs.def'.
505
 
506
* Menu:
507
 
508
* Non-Stab Symbol Types::       Types from 0 to 0x1f
509
* Stab Symbol Types::           Types from 0x20 to 0xff
510
 
511

512
File: stabs.info,  Node: Non-Stab Symbol Types,  Next: Stab Symbol Types,  Up: Stab Types
513
 
514
Non-Stab Symbol Types
515
=====================
516
 
517
   The following types are used by the linker and assembler, not by stab
518
directives.  Since this document does not attempt to describe aspects of
519
object file format other than the debugging format, no details are
520
given.
521
 
522
`0x0     N_UNDF'
523
     Undefined symbol
524
 
525
`0x2     N_ABS'
526
     File scope absolute symbol
527
 
528
`0x3     N_ABS | N_EXT'
529
     External absolute symbol
530
 
531
`0x4     N_TEXT'
532
     File scope text symbol
533
 
534
`0x5     N_TEXT | N_EXT'
535
     External text symbol
536
 
537
`0x6     N_DATA'
538
     File scope data symbol
539
 
540
`0x7     N_DATA | N_EXT'
541
     External data symbol
542
 
543
`0x8     N_BSS'
544
     File scope BSS symbol
545
 
546
`0x9     N_BSS | N_EXT'
547
     External BSS symbol
548
 
549
`0x0c    N_FN_SEQ'
550
     Same as `N_FN', for Sequent compilers
551
 
552
`0x0a    N_INDR'
553
     Symbol is indirected to another symbol
554
 
555
`0x12    N_COMM'
556
     Common--visible after shared library dynamic link
557
 
558
`0x14 N_SETA'
559
`0x15 N_SETA | N_EXT'
560
     Absolute set element
561
 
562
`0x16 N_SETT'
563
`0x17 N_SETT | N_EXT'
564
     Text segment set element
565
 
566
`0x18 N_SETD'
567
`0x19 N_SETD | N_EXT'
568
     Data segment set element
569
 
570
`0x1a N_SETB'
571
`0x1b N_SETB | N_EXT'
572
     BSS segment set element
573
 
574
`0x1c N_SETV'
575
`0x1d N_SETV | N_EXT'
576
     Pointer to set vector
577
 
578
`0x1e N_WARNING'
579
     Print a warning message during linking
580
 
581
`0x1f    N_FN'
582
     File name of a `.o' file
583
 
584

585
File: stabs.info,  Node: Stab Symbol Types,  Prev: Non-Stab Symbol Types,  Up: Stab Types
586
 
587
Stab Symbol Types
588
=================
589
 
590
   The following symbol types indicate that this is a stab.  This is the
591
full list of stab numbers, including stab types that are used in
592
languages other than C.
593
 
594
`0x20     N_GSYM'
595
     Global symbol; see *Note Global Variables::.
596
 
597
`0x22     N_FNAME'
598
     Function name (for BSD Fortran); see *Note Procedures::.
599
 
600
`0x24     N_FUN'
601 363 markom
     Function name (*note Procedures::) or text segment variable (*note
602
     Statics::).
603 106 markom
 
604
`0x26 N_STSYM'
605
     Data segment file-scope variable; see *Note Statics::.
606
 
607
`0x28 N_LCSYM'
608
     BSS segment file-scope variable; see *Note Statics::.
609
 
610
`0x2a N_MAIN'
611
     Name of main routine; see *Note Main Program::.
612
 
613
`0x2c N_ROSYM'
614
     Variable in `.rodata' section; see *Note Statics::.
615
 
616
`0x30     N_PC'
617
     Global symbol (for Pascal); see *Note N_PC::.
618
 
619
`0x32     N_NSYMS'
620
     Number of symbols (according to Ultrix V4.0); see *Note N_NSYMS::.
621
 
622
`0x34     N_NOMAP'
623
     No DST map; see *Note N_NOMAP::.
624
 
625
`0x38 N_OBJ'
626
     Object file (Solaris2).
627
 
628
`0x3c N_OPT'
629
     Debugger options (Solaris2).
630
 
631
`0x40     N_RSYM'
632
     Register variable; see *Note Register Variables::.
633
 
634
`0x42     N_M2C'
635
     Modula-2 compilation unit; see *Note N_M2C::.
636
 
637
`0x44     N_SLINE'
638
     Line number in text segment; see *Note Line Numbers::.
639
 
640
`0x46     N_DSLINE'
641
     Line number in data segment; see *Note Line Numbers::.
642
 
643
`0x48     N_BSLINE'
644
     Line number in bss segment; see *Note Line Numbers::.
645
 
646
`0x48     N_BROWS'
647
     Sun source code browser, path to `.cb' file; see *Note N_BROWS::.
648
 
649
`0x4a     N_DEFD'
650
     GNU Modula2 definition module dependency; see *Note N_DEFD::.
651
 
652
`0x4c N_FLINE'
653
     Function start/body/end line numbers (Solaris2).
654
 
655
`0x50     N_EHDECL'
656
     GNU C++ exception variable; see *Note N_EHDECL::.
657
 
658
`0x50     N_MOD2'
659
     Modula2 info "for imc" (according to Ultrix V4.0); see *Note
660
     N_MOD2::.
661
 
662
`0x54     N_CATCH'
663
     GNU C++ `catch' clause; see *Note N_CATCH::.
664
 
665
`0x60     N_SSYM'
666
     Structure of union element; see *Note N_SSYM::.
667
 
668
`0x62 N_ENDM'
669
     Last stab for module (Solaris2).
670
 
671
`0x64     N_SO'
672
     Path and name of source file; see *Note Source Files::.
673
 
674
`0x80 N_LSYM'
675 363 markom
     Stack variable (*note Stack Variables::) or type (*note
676
     Typedefs::).
677 106 markom
 
678
`0x82     N_BINCL'
679
     Beginning of an include file (Sun only); see *Note Include Files::.
680
 
681
`0x84     N_SOL'
682
     Name of include file; see *Note Include Files::.
683
 
684
`0xa0     N_PSYM'
685
     Parameter variable; see *Note Parameters::.
686
 
687
`0xa2     N_EINCL'
688
     End of an include file; see *Note Include Files::.
689
 
690
`0xa4     N_ENTRY'
691
     Alternate entry point; see *Note Alternate Entry Points::.
692
 
693
`0xc0     N_LBRAC'
694
     Beginning of a lexical block; see *Note Block Structure::.
695
 
696
`0xc2     N_EXCL'
697
     Place holder for a deleted include file; see *Note Include Files::.
698
 
699
`0xc4     N_SCOPE'
700
     Modula2 scope information (Sun linker); see *Note N_SCOPE::.
701
 
702
`0xe0     N_RBRAC'
703
     End of a lexical block; see *Note Block Structure::.
704
 
705
`0xe2     N_BCOMM'
706
     Begin named common block; see *Note Common Blocks::.
707
 
708
`0xe4     N_ECOMM'
709
     End named common block; see *Note Common Blocks::.
710
 
711
`0xe8     N_ECOML'
712
     Member of a common block; see *Note Common Blocks::.
713
 
714
`0xea N_WITH'
715
     Pascal `with' statement: type,,0,0,offset (Solaris2).
716
 
717
`0xf0     N_NBTEXT'
718
     Gould non-base registers; see *Note Gould::.
719
 
720
`0xf2     N_NBDATA'
721
     Gould non-base registers; see *Note Gould::.
722
 
723
`0xf4     N_NBBSS'
724
     Gould non-base registers; see *Note Gould::.
725
 
726
`0xf6     N_NBSTS'
727
     Gould non-base registers; see *Note Gould::.
728
 
729
`0xf8     N_NBLCS'
730
     Gould non-base registers; see *Note Gould::.
731
 
732

733
File: stabs.info,  Node: Symbol Descriptors,  Next: Type Descriptors,  Prev: Stab Types,  Up: Top
734
 
735
Table of Symbol Descriptors
736
***************************
737
 
738
   The symbol descriptor is the character which follows the colon in
739
many stabs, and which tells what kind of stab it is.  *Note String
740
Field::, for more information about their use.
741
 
742
`DIGIT'
743
`('
744
`-'
745
     Variable on the stack; see *Note Stack Variables::.
746
 
747
`:'
748
     C++ nested symbol; see *Note Nested Symbols::.
749
 
750
`a'
751
     Parameter passed by reference in register; see *Note Reference
752
     Parameters::.
753
 
754
`b'
755
     Based variable; see *Note Based Variables::.
756
 
757
`c'
758
     Constant; see *Note Constants::.
759
 
760
`C'
761
     Conformant array bound (Pascal, maybe other languages); *Note
762
     Conformant Arrays::.  Name of a caught exception (GNU C++).  These
763
     can be distinguished because the latter uses `N_CATCH' and the
764
     former uses another symbol type.
765
 
766
`d'
767
     Floating point register variable; see *Note Register Variables::.
768
 
769
`D'
770
     Parameter in floating point register; see *Note Register
771
     Parameters::.
772
 
773
`f'
774
     File scope function; see *Note Procedures::.
775
 
776
`F'
777
     Global function; see *Note Procedures::.
778
 
779
`G'
780
     Global variable; see *Note Global Variables::.
781
 
782
`i'
783
     *Note Register Parameters::.
784
 
785
`I'
786
     Internal (nested) procedure; see *Note Nested Procedures::.
787
 
788
`J'
789
     Internal (nested) function; see *Note Nested Procedures::.
790
 
791
`L'
792
     Label name (documented by AIX, no further information known).
793
 
794
`m'
795
     Module; see *Note Procedures::.
796
 
797
`p'
798
     Argument list parameter; see *Note Parameters::.
799
 
800
`pP'
801
     *Note Parameters::.
802
 
803
`pF'
804
     Fortran Function parameter; see *Note Parameters::.
805
 
806
`P'
807
     Unfortunately, three separate meanings have been independently
808
     invented for this symbol descriptor.  At least the GNU and Sun
809
     uses can be distinguished by the symbol type.  Global Procedure
810
     (AIX) (symbol type used unknown); see *Note Procedures::.
811
     Register parameter (GNU) (symbol type `N_PSYM'); see *Note
812
     Parameters::.  Prototype of function referenced by this file (Sun
813
     `acc') (symbol type `N_FUN').
814
 
815
`Q'
816
     Static Procedure; see *Note Procedures::.
817
 
818
`R'
819
     Register parameter; see *Note Register Parameters::.
820
 
821
`r'
822
     Register variable; see *Note Register Variables::.
823
 
824
`S'
825
     File scope variable; see *Note Statics::.
826
 
827
`s'
828
     Local variable (OS9000).
829
 
830
`t'
831
     Type name; see *Note Typedefs::.
832
 
833
`T'
834
     Enumeration, structure, or union tag; see *Note Typedefs::.
835
 
836
`v'
837
     Parameter passed by reference; see *Note Reference Parameters::.
838
 
839
`V'
840
     Procedure scope static variable; see *Note Statics::.
841
 
842
`x'
843
     Conformant array; see *Note Conformant Arrays::.
844
 
845
`X'
846
     Function return variable; see *Note Parameters::.
847
 
848

849
File: stabs.info,  Node: Type Descriptors,  Next: Expanded Reference,  Prev: Symbol Descriptors,  Up: Top
850
 
851
Table of Type Descriptors
852
*************************
853
 
854
   The type descriptor is the character which follows the type number
855
and an equals sign.  It specifies what kind of type is being defined.
856
*Note String Field::, for more information about their use.
857
 
858
`DIGIT'
859
`('
860
     Type reference; see *Note String Field::.
861
 
862
`-'
863
     Reference to builtin type; see *Note Negative Type Numbers::.
864
 
865
`#'
866
     Method (C++); see *Note Method Type Descriptor::.
867
 
868
`*'
869
     Pointer; see *Note Miscellaneous Types::.
870
 
871
`&'
872
     Reference (C++).
873
 
874
`@'
875
     Type Attributes (AIX); see *Note String Field::.  Member (class
876
     and variable) type (GNU C++); see *Note Member Type Descriptor::.
877
 
878
`a'
879
     Array; see *Note Arrays::.
880
 
881
`A'
882
     Open array; see *Note Arrays::.
883
 
884
`b'
885
     Pascal space type (AIX); see *Note Miscellaneous Types::.  Builtin
886
     integer type (Sun); see *Note Builtin Type Descriptors::.  Const
887
     and volatile qualfied type (OS9000).
888
 
889
`B'
890
     Volatile-qualified type; see *Note Miscellaneous Types::.
891
 
892
`c'
893
     Complex builtin type (AIX); see *Note Builtin Type Descriptors::.
894
     Const-qualified type (OS9000).
895
 
896
`C'
897
     COBOL Picture type.  See AIX documentation for details.
898
 
899
`d'
900
     File type; see *Note Miscellaneous Types::.
901
 
902
`D'
903
     N-dimensional dynamic array; see *Note Arrays::.
904
 
905
`e'
906
     Enumeration type; see *Note Enumerations::.
907
 
908
`E'
909
     N-dimensional subarray; see *Note Arrays::.
910
 
911
`f'
912
     Function type; see *Note Function Types::.
913
 
914
`F'
915
     Pascal function parameter; see *Note Function Types::
916
 
917
`g'
918
     Builtin floating point type; see *Note Builtin Type Descriptors::.
919
 
920
`G'
921
     COBOL Group.  See AIX documentation for details.
922
 
923
`i'
924
     Imported type (AIX); see *Note Cross-References::.
925
     Volatile-qualified type (OS9000).
926
 
927
`k'
928
     Const-qualified type; see *Note Miscellaneous Types::.
929
 
930
`K'
931
     COBOL File Descriptor.  See AIX documentation for details.
932
 
933
`M'
934
     Multiple instance type; see *Note Miscellaneous Types::.
935
 
936
`n'
937
     String type; see *Note Strings::.
938
 
939
`N'
940
     Stringptr; see *Note Strings::.
941
 
942
`o'
943
     Opaque type; see *Note Typedefs::.
944
 
945
`p'
946
     Procedure; see *Note Function Types::.
947
 
948
`P'
949
     Packed array; see *Note Arrays::.
950
 
951
`r'
952
     Range type; see *Note Subranges::.
953
 
954
`R'
955
     Builtin floating type; see *Note Builtin Type Descriptors:: (Sun).
956
     Pascal subroutine parameter; see *Note Function Types:: (AIX).
957
     Detecting this conflict is possible with careful parsing (hint: a
958
     Pascal subroutine parameter type will always contain a comma, and
959
     a builtin type descriptor never will).
960
 
961
`s'
962
     Structure type; see *Note Structures::.
963
 
964
`S'
965
     Set type; see *Note Miscellaneous Types::.
966
 
967
`u'
968
     Union; see *Note Unions::.
969
 
970
`v'
971
     Variant record.  This is a Pascal and Modula-2 feature which is
972
     like a union within a struct in C.  See AIX documentation for
973
     details.
974
 
975
`w'
976
     Wide character; see *Note Builtin Type Descriptors::.
977
 
978
`x'
979
     Cross-reference; see *Note Cross-References::.
980
 
981
`Y'
982
     Used by IBM's xlC C++ compiler (for structures, I think).
983
 
984
`z'
985
     gstring; see *Note Strings::.
986
 
987

988
File: stabs.info,  Node: Expanded Reference,  Next: Questions,  Prev: Type Descriptors,  Up: Top
989
 
990
Expanded Reference by Stab Type
991
*******************************
992
 
993
   For a full list of stab types, and cross-references to where they are
994
described, see *Note Stab Types::.  This appendix just covers certain
995
stabs which are not yet described in the main body of this document;
996
eventually the information will all be in one place.
997
 
998
   Format of an entry:
999
 
1000
   The first line is the symbol type (see `include/aout/stab.def').
1001
 
1002
   The second line describes the language constructs the symbol type
1003
represents.
1004
 
1005
   The third line is the stab format with the significant stab fields
1006
named and the rest NIL.
1007
 
1008
   Subsequent lines expand upon the meaning and possible values for each
1009
significant stab field.
1010
 
1011
   Finally, any further information.
1012
 
1013
* Menu:
1014
 
1015
* N_PC::                        Pascal global symbol
1016
* N_NSYMS::                     Number of symbols
1017
* N_NOMAP::                     No DST map
1018
* N_M2C::                       Modula-2 compilation unit
1019
* N_BROWS::                     Path to .cb file for Sun source code browser
1020
* N_DEFD::                      GNU Modula2 definition module dependency
1021
* N_EHDECL::                    GNU C++ exception variable
1022
* N_MOD2::                      Modula2 information "for imc"
1023
* N_CATCH::                     GNU C++ "catch" clause
1024
* N_SSYM::                      Structure or union element
1025
* N_SCOPE::                     Modula2 scope information (Sun only)
1026
* Gould::                       non-base register symbols used on Gould systems
1027
* N_LENG::                      Length of preceding entry
1028
 
1029

1030
File: stabs.info,  Node: N_PC,  Next: N_NSYMS,  Up: Expanded Reference
1031
 
1032
N_PC
1033
====
1034
 
1035
 - `.stabs': N_PC
1036
     Global symbol (for Pascal).
1037
 
1038
          "name" -> "symbol_name"  <>
1039
          value  -> supposedly the line number (stab.def is skeptical)
1040
 
1041
          `stabdump.c' says:
1042
 
1043
          global pascal symbol: name,,0,subtype,line
1044
          << subtype? >>
1045
 
1046

1047
File: stabs.info,  Node: N_NSYMS,  Next: N_NOMAP,  Prev: N_PC,  Up: Expanded Reference
1048
 
1049
N_NSYMS
1050
=======
1051
 
1052
 - `.stabn': N_NSYMS
1053
     Number of symbols (according to Ultrix V4.0).
1054
 
1055
                  0, files,,funcs,lines (stab.def)
1056
 
1057

1058
File: stabs.info,  Node: N_NOMAP,  Next: N_M2C,  Prev: N_NSYMS,  Up: Expanded Reference
1059
 
1060
N_NOMAP
1061
=======
1062
 
1063
 - `.stabs': N_NOMAP
1064
     No DST map for symbol (according to Ultrix V4.0).  I think this
1065
     means a variable has been optimized out.
1066
 
1067
                  name, ,0,type,ignored (stab.def)
1068
 
1069

1070
File: stabs.info,  Node: N_M2C,  Next: N_BROWS,  Prev: N_NOMAP,  Up: Expanded Reference
1071
 
1072
N_M2C
1073
=====
1074
 
1075
 - `.stabs': N_M2C
1076
     Modula-2 compilation unit.
1077
 
1078
          "string" -> "unit_name,unit_time_stamp[,code_time_stamp]"
1079
          desc   -> unit_number
1080
          value  -> 0 (main unit)
1081
                    1 (any other unit)
1082
 
1083
     See `Dbx and Dbxtool Interfaces', 2nd edition, by Sun, 1988, for
1084
     more information.
1085
 
1086
 
1087

1088
File: stabs.info,  Node: N_BROWS,  Next: N_DEFD,  Prev: N_M2C,  Up: Expanded Reference
1089
 
1090
N_BROWS
1091
=======
1092
 
1093
 - `.stabs': N_BROWS
1094
     Sun source code browser, path to `.cb' file
1095
 
1096
     <> "path to associated `.cb' file"
1097
 
1098
     Note: N_BROWS has the same value as N_BSLINE.
1099
 
1100

1101
File: stabs.info,  Node: N_DEFD,  Next: N_EHDECL,  Prev: N_BROWS,  Up: Expanded Reference
1102
 
1103
N_DEFD
1104
======
1105
 
1106
 - `.stabn': N_DEFD
1107
     GNU Modula2 definition module dependency.
1108
 
1109
     GNU Modula-2 definition module dependency.  The value is the
1110
     modification time of the definition file.  The other field is
1111
     non-zero if it is imported with the GNU M2 keyword `%INITIALIZE'.
1112
     Perhaps `N_M2C' can be used if there are enough empty fields?
1113
 
1114

1115
File: stabs.info,  Node: N_EHDECL,  Next: N_MOD2,  Prev: N_DEFD,  Up: Expanded Reference
1116
 
1117
N_EHDECL
1118
========
1119
 
1120
 - `.stabs': N_EHDECL
1121
     GNU C++ exception variable <>.
1122
 
1123
     "STRING is variable name"
1124
 
1125
     Note: conflicts with `N_MOD2'.
1126
 
1127

1128
File: stabs.info,  Node: N_MOD2,  Next: N_CATCH,  Prev: N_EHDECL,  Up: Expanded Reference
1129
 
1130
N_MOD2
1131
======
1132
 
1133
 - `.stab?': N_MOD2
1134
     Modula2 info "for imc" (according to Ultrix V4.0)
1135
 
1136
     Note: conflicts with `N_EHDECL'  <>
1137
 
1138

1139
File: stabs.info,  Node: N_CATCH,  Next: N_SSYM,  Prev: N_MOD2,  Up: Expanded Reference
1140
 
1141
N_CATCH
1142
=======
1143
 
1144
 - `.stabn': N_CATCH
1145
     GNU C++ `catch' clause
1146
 
1147
     GNU C++ `catch' clause.  The value is its address.  The desc field
1148
     is nonzero if this entry is immediately followed by a `CAUGHT' stab
1149
     saying what exception was caught.  Multiple `CAUGHT' stabs means
1150
     that multiple exceptions can be caught here.  If desc is 0, it
1151
     means all exceptions are caught here.
1152
 
1153

1154
File: stabs.info,  Node: N_SSYM,  Next: N_SCOPE,  Prev: N_CATCH,  Up: Expanded Reference
1155
 
1156
N_SSYM
1157
======
1158
 
1159
 - `.stabn': N_SSYM
1160
     Structure or union element.
1161
 
1162
     The value is the offset in the structure.
1163
 
1164
     <>
1165
 
1166

1167
File: stabs.info,  Node: N_SCOPE,  Next: Gould,  Prev: N_SSYM,  Up: Expanded Reference
1168
 
1169
N_SCOPE
1170
=======
1171
 
1172
 - `.stab?': N_SCOPE
1173
     Modula2 scope information (Sun linker) <>
1174
 
1175

1176
File: stabs.info,  Node: Gould,  Next: N_LENG,  Prev: N_SCOPE,  Up: Expanded Reference
1177
 
1178
Non-base registers on Gould systems
1179
===================================
1180
 
1181
 - `.stab?': N_NBTEXT
1182
 - `.stab?': N_NBDATA
1183
 - `.stab?': N_NBBSS
1184
 - `.stab?': N_NBSTS
1185
 - `.stab?': N_NBLCS
1186
     These are used on Gould systems for non-base registers syms.
1187
 
1188
     However, the following values are not the values used by Gould;
1189
     they are the values which GNU has been documenting for these
1190
     values for a long time, without actually checking what Gould uses.
1191
     I include these values only because perhaps some someone actually
1192
     did something with the GNU information (I hope not, why GNU
1193
     knowingly assigned wrong values to these in the header file is a
1194
     complete mystery to me).
1195
 
1196
          240    0xf0     N_NBTEXT  ??
1197
          242    0xf2     N_NBDATA  ??
1198
          244    0xf4     N_NBBSS   ??
1199
          246    0xf6     N_NBSTS   ??
1200
          248    0xf8     N_NBLCS   ??
1201
 
1202

1203
File: stabs.info,  Node: N_LENG,  Prev: Gould,  Up: Expanded Reference
1204
 
1205
N_LENG
1206
======
1207
 
1208
 - `.stabn': N_LENG
1209
     Second symbol entry containing a length-value for the preceding
1210
     entry.  The value is the length.
1211
 
1212

1213
File: stabs.info,  Node: Questions,  Next: Stab Sections,  Prev: Expanded Reference,  Up: Top
1214
 
1215
Questions and Anomalies
1216
***********************
1217
 
1218
   * For GNU C stabs defining local and global variables (`N_LSYM' and
1219
     `N_GSYM'), the desc field is supposed to contain the source line
1220
     number on which the variable is defined.  In reality the desc
1221
     field is always 0.  (This behavior is defined in `dbxout.c' and
1222
     putting a line number in desc is controlled by `#ifdef
1223
     WINNING_GDB', which defaults to false). GDB supposedly uses this
1224
     information if you say `list VAR'.  In reality, VAR can be a
1225
     variable defined in the program and GDB says `function VAR not
1226
     defined'.
1227
 
1228
   * In GNU C stabs, there seems to be no way to differentiate tag
1229
     types: structures, unions, and enums (symbol descriptor `T') and
1230
     typedefs (symbol descriptor `t') defined at file scope from types
1231
     defined locally to a procedure or other more local scope.  They
1232
     all use the `N_LSYM' stab type.  Types defined at procedure scope
1233
     are emited after the `N_RBRAC' of the preceding function and
1234
     before the code of the procedure in which they are defined.  This
1235
     is exactly the same as types defined in the source file between
1236
     the two procedure bodies.  GDB overcompensates by placing all
1237
     types in block #1, the block for symbols of file scope.  This is
1238
     true for default, `-ansi' and `-traditional' compiler options.
1239
     (Bugs gcc/1063, gdb/1066.)
1240
 
1241
   * What ends the procedure scope?  Is it the proc block's `N_RBRAC'
1242
     or the next `N_FUN'?  (I believe its the first.)
1243
 
1244

1245
File: stabs.info,  Node: Stab Sections,  Next: Symbol Types Index,  Prev: Questions,  Up: Top
1246
 
1247
Using Stabs in Their Own Sections
1248
*********************************
1249
 
1250
   Many object file formats allow tools to create object files with
1251
custom sections containing any arbitrary data.  For any such object file
1252
format, stabs can be embedded in special sections.  This is how stabs
1253
are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs
1254
are used with COFF.
1255
 
1256
* Menu:
1257
 
1258
* Stab Section Basics::    How to embed stabs in sections
1259
* ELF Linker Relocation::  Sun ELF hacks
1260
 
1261

1262
File: stabs.info,  Node: Stab Section Basics,  Next: ELF Linker Relocation,  Up: Stab Sections
1263
 
1264
How to Embed Stabs in Sections
1265
==============================
1266
 
1267
   The assembler creates two custom sections, a section named `.stab'
1268
which contains an array of fixed length structures, one struct per stab,
1269
and a section named `.stabstr' containing all the variable length
1270
strings that are referenced by stabs in the `.stab' section.  The byte
1271
order of the stabs binary data depends on the object file format.  For
1272
ELF, it matches the byte order of the ELF file itself, as determined
1273
from the `EI_DATA' field in the `e_ident' member of the ELF header.
1274
For SOM, it is always big-endian (is this true??? FIXME).  For COFF, it
1275
matches the byte order of the COFF headers.  The meaning of the fields
1276 363 markom
is the same as for a.out (*note Symbol Table Format::), except that the
1277
`n_strx' field is relative to the strings for the current compilation
1278
unit (which can be found using the synthetic N_UNDF stab described
1279
below), rather than the entire string table.
1280 106 markom
 
1281
   The first stab in the `.stab' section for each compilation unit is
1282
synthetic, generated entirely by the assembler, with no corresponding
1283
`.stab' directive as input to the assembler.  This stab contains the
1284
following fields:
1285
 
1286
`n_strx'
1287
     Offset in the `.stabstr' section to the source filename.
1288
 
1289
`n_type'
1290
     `N_UNDF'.
1291
 
1292
`n_other'
1293
     Unused field, always zero.  This may eventually be used to hold
1294
     overflows from the count in the `n_desc' field.
1295
 
1296
`n_desc'
1297
     Count of upcoming symbols, i.e., the number of remaining stabs for
1298
     this source file.
1299
 
1300
`n_value'
1301
     Size of the string table fragment associated with this source
1302
     file, in bytes.
1303
 
1304
   The `.stabstr' section always starts with a null byte (so that string
1305
offsets of zero reference a null string), followed by random length
1306
strings, each of which is null byte terminated.
1307
 
1308
   The ELF section header for the `.stab' section has its `sh_link'
1309
member set to the section number of the `.stabstr' section, and the
1310
`.stabstr' section has its ELF section header `sh_type' member set to
1311
`SHT_STRTAB' to mark it as a string table.  SOM and COFF have no way of
1312
linking the sections together or marking them as string tables.
1313
 
1314
   For COFF, the `.stab' and `.stabstr' sections may be simply
1315
concatenated by the linker.  GDB then uses the `n_desc' fields to
1316
figure out the extent of the original sections.  Similarly, the
1317
`n_value' fields of the header symbols are added together in order to
1318
get the actual position of the strings in a desired `.stabstr' section.
1319
Although this design obviates any need for the linker to relocate or
1320
otherwise manipulate `.stab' and `.stabstr' sections, it also requires
1321
some care to ensure that the offsets are calculated correctly.  For
1322
instance, if the linker were to pad in between the `.stabstr' sections
1323
before concatenating, then the offsets to strings in the middle of the
1324
executable's `.stabstr' section would be wrong.
1325
 
1326
   The GNU linker is able to optimize stabs information by merging
1327
duplicate strings and removing duplicate header file information (*note
1328 363 markom
Include Files::).  When some versions of the GNU linker optimize stabs
1329 106 markom
in sections, they remove the leading `N_UNDF' symbol and arranges for
1330
all the `n_strx' fields to be relative to the start of the `.stabstr'
1331
section.
1332
 
1333

1334
File: stabs.info,  Node: ELF Linker Relocation,  Prev: Stab Section Basics,  Up: Stab Sections
1335
 
1336
Having the Linker Relocate Stabs in ELF
1337
=======================================
1338
 
1339
   This section describes some Sun hacks for Stabs in ELF; it does not
1340
apply to COFF or SOM.
1341
 
1342
   To keep linking fast, you don't want the linker to have to relocate
1343
very many stabs.  Making sure this is done for `N_SLINE', `N_RBRAC',
1344
and `N_LBRAC' stabs is the most important thing (see the descriptions
1345
of those stabs for more information).  But Sun's stabs in ELF has taken
1346
this further, to make all addresses in the `n_value' field (functions
1347
and static variables) relative to the source file.  For the `N_SO'
1348
symbol itself, Sun simply omits the address.  To find the address of
1349
each section corresponding to a given source file, the compiler puts
1350
out symbols giving the address of each section for a given source file.
1351
Since these are ELF (not stab) symbols, the linker relocates them
1352
correctly without having to touch the stabs section.  They are named
1353
`Bbss.bss' for the bss section, `Ddata.data' for the data section, and
1354
`Drodata.rodata' for the rodata section.  For the text section, there
1355
is no such symbol (but there should be, see below).  For an example of
1356
how these symbols work, *Note Stab Section Transformations::.  GCC does
1357
not provide these symbols; it instead relies on the stabs getting
1358
relocated.  Thus addresses which would normally be relative to
1359
`Bbss.bss', etc., are already relocated.  The Sun linker provided with
1360
Solaris 2.2 and earlier relocates stabs using normal ELF relocation
1361
information, as it would do for any section.  Sun has been threatening
1362
to kludge their linker to not do this (to speed up linking), even
1363
though the correct way to avoid having the linker do these relocations
1364
is to have the compiler no longer output relocatable values.  Last I
1365
heard they had been talked out of the linker kludge.  See Sun point
1366
patch 101052-01 and Sun bug 1142109.  With the Sun compiler this
1367 363 markom
affects `S' symbol descriptor stabs (*note Statics::) and functions
1368
(*note Procedures::).  In the latter case, to adopt the clean solution
1369 106 markom
(making the value of the stab relative to the start of the compilation
1370
unit), it would be necessary to invent a `Ttext.text' symbol, analogous
1371
to the `Bbss.bss', etc., symbols.  I recommend this rather than using a
1372
zero value and getting the address from the ELF symbols.
1373
 
1374
   Finding the correct `Bbss.bss', etc., symbol is difficult, because
1375
the linker simply concatenates the `.stab' sections from each `.o' file
1376
without including any information about which part of a `.stab' section
1377
comes from which `.o' file.  The way GDB does this is to look for an
1378
ELF `STT_FILE' symbol which has the same name as the last component of
1379
the file name from the `N_SO' symbol in the stabs (for example, if the
1380
file name is `../../gdb/main.c', it looks for an ELF `STT_FILE' symbol
1381
named `main.c').  This loses if different files have the same name
1382
(they could be in different directories, a library could have been
1383
copied from one system to another, etc.).  It would be much cleaner to
1384
have the `Bbss.bss' symbols in the stabs themselves.  Having the linker
1385
relocate them there is no more work than having the linker relocate ELF
1386
symbols, and it solves the problem of having to associate the ELF and
1387
stab symbols.  However, no one has yet designed or implemented such a
1388
scheme.
1389
 

powered by: WebSVN 2.1.0

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