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

Subversion Repositories or1k

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

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
This is stabs.info, produced by makeinfo version 4.0 from
2
./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,1993,1994,1995,1997,1998,2000,2001    Free Software
11
Foundation, Inc.  Contributed by Cygnus Support.  Written by Julia
12
Menapace, Jim Kingdon, and David MacKenzie.
13
 
14
   Permission is granted to copy, distribute and/or modify this document
15
under the terms of the GNU Free Documentation License, Version 1.1 or
16
any later version published by the Free Software Foundation; with the
17
Invariant Sections being "Stabs Types" and "Stabs Sections", with the
18
Front-Cover texts being "A GNU Manual," and with the Back-Cover Texts
19
as in (a) below.
20
 
21
   (a) The FSF's Back-Cover Text is: "You have freedom to copy and
22
modify this GNU Manual, like GNU software.  Copies published by the Free
23
Software Foundation raise funds for GNU development."
24
 
25

26
File: stabs.info,  Node: Class Instance,  Next: Methods,  Prev: Simple Classes,  Up: Cplusplus
27
 
28
Class Instance
29
==============
30
 
31
   As shown above, describing even a simple C++ class definition is
32
accomplished by massively extending the stab format used in C to
33
describe structure types.  However, once the class is defined, C stabs
34
with no modifications can be used to describe class instances.  The
35
following source:
36
 
37
     main () {
38
             baseA AbaseA;
39
     }
40
 
41
yields the following stab describing the class instance.  It looks no
42
different from a standard C stab describing a local variable.
43
 
44
     .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset
45
 
46
     .stabs "AbaseA:20",128,0,0,-20
47
 
48

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

powered by: WebSVN 2.1.0

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