stabs.texinfo

早期freebsd实现

@example
136 .stabs "g_an_s:G16",32,0,0,0
137     .common _g_an_s,20,"bss"
@end example

Notice that the structure tag has the same type number as the typedef
for the structure tag.  It is impossible to distinguish between a
variable of the struct type and one of its typedef by looking at the
debugging information.


@node Unions
@section Unions 

@table @strong
@item Directive:
@code{.stabs}
@item Type:
@code{N_LSYM}
@item Symbol Descriptor:
@code{T}
@item Type Descriptor:
@code{u}
@end table

Next let's look at unions.  In example2 this union type is declared
locally to a procedure and an instance of the union is defined.

@example
36   union u_tag @{
37     int  u_int;
38     float u_float;
39     char* u_char;
40   @} an_u;
@end example

This code generates a stab for the union tag and a stab for the union
variable.  Both use the N_LSYM stab type.  Since the union variable is
scoped locally to the procedure in which it is defined, its stab is
located immediately preceding the N_LBRAC for the procedure's block
start.

The stab for the union tag, however is located preceding the code for
the procedure in which it is defined.  The stab type is N_LSYM.  This
would seem to imply that the union type is file scope, like the struct
type s_tag.  This is not true.  The contents and position of the stab
for u_type do not convey any infomation about its procedure local
scope.

@display
     <128> N_LSYM - type
     .stabs "name:sym_desc(union tag)type_def(22)=type_desc(union)
     byte_size(4)
     elem_name:type_ref(int),bit_offset(0),bit_size(32);
     elem_name:type_ref(float),bit_offset(0),bit_size(32);
     elem_name:type_ref(ptr to char),bit_offset(0),bit_size(32);;"
     N_LSYM, NIL, NIL, NIL
@end display

@smallexample
105 .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
           128,0,0,0
@end smallexample

The symbol descriptor, T, following the name: means that the stab
describes an enumeration struct or type tag.  The type descriptor u,
following the 23= of the type definition, narrows it down to a union
type definition.  Following the u is the number of bytes in the union.
After that is a list of union element descriptions.  Their format is
name:type, bit offset into the union, and number of bytes for the
element;.

The stab for the union variable follows.  Notice that the frame
pointer offset for local variables is negative.

@display
    <128> N_LSYM - local variable (with no symbol descriptor)
    .stabs "name:type_ref(u_tag)", N_LSYM, NIL, NIL, frame_ptr_offset
@end display

@example
130 .stabs "an_u:23",128,0,0,-20
@end example

@node Function types
@section Function types

@display
type descriptor f
@end display

The last type descriptor in C which remains to be described is used
for function types.  Consider the following source line defining a
global function pointer.

@example
4  int (*g_pf)();
@end example

It generates the following code.  Since the variable is not
initialized, the code is located in the common area at the end of the
file.

@display
    <32> N_GSYM - global variable
    .stabs "name:sym_desc(global)type_def(24)=ptr_to(25)=
                                 type_def(func)type_ref(int)
@end display

@example
134 .stabs "g_pf:G24=*25=f1",32,0,0,0
135     .common _g_pf,4,"bss"
@end example

Since the variable is global, the stab type is N_GSYM and the symbol
descriptor is G.  The variable defines a new type, 24, which is a
pointer to another new type, 25, which is defined as a function
returning int.

@node Symbol tables
@chapter Symbol information in symbol tables

This section examines more closely the format of symbol table entries
and how stab assembler directives map to them.  It also describes what
transformations the assembler and linker make on data from stabs.

Each time the assembler encounters a stab in its input file it puts
each field of the stab into corresponding fields in a symbol table
entry of its output file.  If the stab contains a string field, the
symbol table entry for that stab points to a string table entry
containing the string data from the stab.  Assembler labels become
relocatable addresses.  Symbol table entries in a.out have the format:

@example
struct internal_nlist @{
  unsigned long n_strx;         /* index into string table of name */
  unsigned char n_type;         /* type of symbol */
  unsigned char n_other;        /* misc info (usually empty) */
  unsigned short n_desc;        /* description field */
  bfd_vma n_value;              /* value of symbol */
@};
@end example

For .stabs directives, the n_strx field holds the character offset
from the start of the string table to the string table entry
containing the "string" field.  For other classes of stabs (.stabn and
.stabd) this field is null.

Symbol table entries with n_type fields containing a value greater or
equal to 0x20 originated as stabs generated by the compiler (with one
random exception).  Those with n_type values less than 0x20 were
placed in the symbol table of the executable by the assembler or the
linker.

The linker concatenates object files and does fixups of externally
defined symbols.  You can see the transformations made on stab data by
the assembler and linker by examining the symbol table after each pass
of the build, first the assemble and then the link.

To do this use nm with the -ap options.  This dumps the symbol table,
including debugging information, unsorted.  For stab entries the
columns are: value, other, desc, type, string.  For assembler and
linker symbols, the columns are: value, type, string.

There are a few important things to notice about symbol tables.  Where
the value field of a stab contains a frame pointer offset, or a
register number, that value is unchanged by the rest of the build.

Where the value field of a stab contains an assembly language label,
it is transformed by each build step.  The assembler turns it into a
relocatable address and the linker turns it into an absolute address.
This source line defines a static variable at file scope:

@example
3  static int s_g_repeat
@end example

@noindent
The following stab describes the symbol.

@example
26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
@end example

@noindent
The assembler transforms the stab into this symbol table entry in the
@file{.o} file.  The location is expressed as a data segment offset.

@example
21 00000084 - 00 0000 STSYM s_g_repeat:S1
@end example

@noindent
in the symbol table entry from the executable, the linker has made the
relocatable address absolute.

@example
22 0000e00c - 00 0000 STSYM s_g_repeat:S1
@end example

Stabs for global variables do not contain location information. In
this case the debugger finds location information in the assembler or
linker symbol table entry describing the variable.  The source line:

@example
1 char g_foo = 'c';
@end example

@noindent
generates the stab:

@example
21 .stabs "g_foo:G2",32,0,0,0
@end example

The variable is represented by the following two symbol table entries
in the object file.  The first one originated as a stab.  The second
one is an external symbol.  The upper case D signifies that the n_type
field of the symbol table contains 7, N_DATA with local linkage (see
Table B).  The value field following the file's line number is empty
for the stab entry.  For the linker symbol it contains the
rellocatable address corresponding to the variable.

@example
19 00000000 - 00 0000  GSYM g_foo:G2
20 00000080 D _g_foo
@end example

@noindent
These entries as transformed by the linker.  The linker symbol table
entry now holds an absolute address.

@example
21 00000000 - 00 0000  GSYM g_foo:G2
@dots{}
215 0000e008 D _g_foo
@end example

@node GNU C++ stabs
@chapter GNU C++ stabs

@menu
* Basic C++ types::
* Simple classes::
* Class instance::
* Methods:: Method definition
* Protections::
* Method Modifiers:: (const, volatile, const volatile)
* Virtual Methods::
* Inheritence::
* Virtual Base Classes::
* Static Members::
@end menu


@subsection Symbol descriptors added for C++ descriptions:

@display
P - register parameter.
@end display

@subsection type descriptors added for C++ descriptions

@table @code
@item #
method type (two ## if minimal debug)

@item xs
cross-reference
@end table


@node Basic C++ types
@section Basic types for C++

<< the examples that follow are based on a01.C >>


C++ adds two more builtin types to the set defined for C.  These are
the unknown type and the vtable record type.  The unknown type, type
16, is defined in terms of itself like the void type.

The vtable record type, type 17, is defined as a structure type and
then as a structure tag.  The structure has four fields, delta, index,
pfn, and delta2.  pfn is the function pointer.

<< In boilerplate $vtbl_ptr_type, what are the fields delta,
index, and delta2 used for? >>

This basic type is present in all C++ programs even if there are no
virtual methods defined.

@display
.stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8)
        elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16);
        elem_name(index):type_ref(short int),bit_offset(16),field_bits(16);
        elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void),
                                    bit_offset(32),field_bits(32);
        elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;"
        N_LSYM, NIL, NIL
@end display
        
@smallexample
.stabs "$vtbl_ptr_type:t17=s8
        delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;"
        ,128,0,0,0
@end smallexample

@display
.stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL
@end display

@example
.stabs "$vtbl_ptr_type:T17",128,0,0,0
@end example

@node Simple classes
@section Simple class definition 

The stabs describing C++ language features are an extension of the
stabs describing C.  Stabs representing C++ class types elaborate
extensively on the stab format used to describe structure types in C.
Stabs representing class type variables look just like stabs
representing C language variables.

Consider the following very simple class definition.

@example
class baseA @{
public:
        int Adat;
        int Ameth(int in, char other);
@};
@end example

The class baseA is represented by two stabs.  The first stab describes
the class as a structure type.  The second stab describes a structure
tag of the class type.  Both stabs are of stab type N_LSYM.  Since the
stab is not located between an N_FUN and a N_LBRAC stab this indicates
that the class is defined at file scope.  If it were, then the N_LSYM
would signify a local variable.

A stab describing a C++ class type is similar in format to a stab
describing a C struct, with each class member shown as a field in the
structure.  The part of the struct format describing fields is
expanded to include extra information relevent to C++ class members.
In addition, if the class has multiple base classes or virtual
functions the struct format outside of the field parts is also
augmented.

In this simple example the field part of the C++ class stab
representing member data looks just like the field part of a C struct
stab.  The section on protections describes how its format is
sometimes extended for member data.

The field part of a C++ class stab representing a member function
differs substantially from the field part of a C struct stab.  It
still begins with `name:' but then goes on to define a new type number
for the member function, describe its return type, its argument types,
its protection level, any qualifiers applied to the method definition,
and whether the method is virtual or not.  If the method is virtual
then the method description goes on to give the vtable index of the
method, and the type number of the first base class defining the
method. 

When the field name is a method name it is followed by two colons
rather than one.  This is followed by a new type definition for the
method.  This is a number followed by an equal sign and then the
symbol descriptor `##', indicating a method type.  This is followed by
a type reference showing the return type of the method and a
semi-colon.

The format of an overloaded operator method name differs from that
of other methods.  It is "op$::XXXX." where XXXX is the operator name
such as + or +=.  The name ends with a period, and any characters except
the period can occur in the XXXX string.

The next part of the method description represents the arguments to
the method, preceeded by a colon and ending with a semi-colon.  The
types of the arguments are expressed in the same way argument types
are expressed in C++ name mangling.  In this example an int and a char
map to `ic'.

This is followed by a number, a letter, and an asterisk or period,
followed by another semicolon.  The number indicates the protections
that apply to the member function.  Here the 2 means public.  The
letter encodes any qualifier applied to the method definition.  In
this case A means that it is a normal function definition.  The dot
shows that the method is not virtual.  The sections that follow
elaborate further on these fields and describe the additional
information present for virtual methods.


@display
.stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4)
        field_name(Adat):type(int),bit_offset(0),field_bits(32);

        method_name(Ameth)::type_def(21)=type_desc(method)return_type(int);
        :arg_types(int char); 
        protection(public)qualifier(normal)virtual(no);;"
        N_LSYM,NIL,NIL,NIL
@end display

@smallexample
.stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0

.stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL

.stabs "baseA:T20",128,0,0,0
@end smallexample

@node Class instance
@section Class instance

As shown above, describing even a simple C++ class definition is
accomplished by massively extending the stab format used in C to