stabs.texinfo

早期freebsd实现

\input texinfo
@setfilename stabs.info

@ifinfo
@format
START-INFO-DIR-ENTRY
* Stabs: (stabs).               The "stabs" debugging information format.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
This document describes GNU stabs (debugging symbol tables) in a.out files.

Copyright 1992 Free Software Foundation, Inc.
Contributed by Cygnus Support.  Written by Julia Menapace.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy or distribute modified versions of this
manual under the terms of the GPL (for which purpose this text may be
regarded as a program in the language TeX).
@end ifinfo

@setchapternewpage odd
@settitle STABS
@titlepage
@title The ``stabs'' debug format
@author Julia Menapace
@author Cygnus Support
@page
@tex
\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
\xdef\manvers{\$Revision: 2.10 $}  % For use in headers, footers too
{\parskip=0pt
\hfill Cygnus Support\par
\hfill \manvers\par
\hfill \TeX{}info \texinfoversion\par
}
@end tex

@vskip 0pt plus 1filll
Copyright @copyright{} 1992 Free Software Foundation, Inc.
Contributed by Cygnus Support.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@end titlepage

@ifinfo
@node Top
@top The "stabs" representation of debugging information

This document describes the GNU stabs debugging format in a.out files.

@menu
* Overview::                    Overview of stabs
* Program structure::           Encoding of the structure of the program
* Simple types::
* Example::                     A comprehensive example in C 
* Variables::
* Aggregate types::
* Symbol tables::               Symbol information in symbol tables
* GNU C++ stabs::

Appendixes:
* Example2.c::                  Source code for extended example
* Example2.s::                  Assembly code for extended example
* Quick reference::             Various refernce tables
* Expanded reference::          Reference information by stab type
* Questions::                   Questions and anomolies
* xcoff-differences::           Differences between GNU stabs in a.out
                                and GNU stabs in xcoff
* Sun-differences::             Differences between GNU stabs and Sun
                                native stabs
@end menu
@end ifinfo


@node Overview
@chapter Overview of stabs

@dfn{Stabs} refers to a format for information that describes a program
to a debugger.  This format was apparently invented by
@c FIXME! <<name of inventor>> at
the University of California at Berkeley, for the @code{pdx} Pascal
debugger; the format has spread widely since then.

@menu
* Flow:: Overview of debugging information flow
* Stabs format:: Overview of stab format
* C example:: A simple example in C source
* Assembly code:: The simple example at the assembly level
@end menu

@node Flow
@section Overview of debugging information flow

The GNU C compiler compiles C source in a @file{.c} file into assembly
language in a @file{.s} file, which is translated by the assembler into
a @file{.o} file, and then linked with other @file{.o} files and
libraries to produce an executable file.

With the @samp{-g} option, GCC puts additional debugging information in
the @file{.s} file, which is slightly transformed by the assembler and
linker, and carried through into the final executable.  This debugging
information describes features of the source file like line numbers,
the types and scopes of variables, and functions, their parameters and
their scopes.

For some object file formats, the debugging information is
encapsulated in assembler directives known collectively as `stab' (symbol
table) directives, interspersed with the generated code.  Stabs are
the native format for debugging information in the a.out and xcoff
object file formats.  The GNU tools can also emit stabs in the coff
and ecoff object file formats.

The assembler adds the information from stabs to the symbol information
it places by default in the symbol table and the string table of the
@file{.o} file it is building.  The linker consolidates the @file{.o}
files into one executable file, with one symbol table and one string
table.  Debuggers use the symbol and string tables in the executable as
a source of debugging information about the program.

@node Stabs format
@section Overview of stab format

There are three overall formats for stab assembler directives
differentiated by the first word of the stab.  The name of the directive
describes what combination of four possible data fields will follow.  It
is either @code{.stabs} (string), @code{.stabn} (number), or
@code{.stabd} (dot).

The overall format of each class of stab is:

@example
.stabs "@var{string}",@var{type},0,@var{desc},@var{value}
.stabn          @var{type},0,@var{desc},@var{value}
.stabd          @var{type},0,@var{desc}
@end example

In general, in @code{.stabs} the @var{string} field contains name and type
information.  For @code{.stabd} the value field is implicit and has the value
of the current file location.  Otherwise the value field often
contains a relocatable address, frame pointer offset, or register
number, that maps to the source code element described by the stab.

The real key to decoding the meaning of a stab is the number in its type
field.  Each possible type number defines a different stab type.  The
stab type further defines the exact interpretation of, and possible
values for, any remaining @code{"@var{string}"}, @var{desc}, or
@var{value} fields present in the stab.  Table A (@pxref{Stab
types,,Table A: Symbol types from stabs}) lists in numeric order
the possible type field values for stab directives.  The reference
section that follows Table A describes the meaning of the fields for
each stab type in detail.  The examples that follow this overview
introduce the stab types in terms of the source code elements they
describe.

For @code{.stabs} the @code{"@var{string}"} field holds the meat of the
debugging information.  The generally unstructured nature of this field
is what makes stabs extensible.  For some stab types the string field
contains only a name.  For other stab types the contents can be a great
deal more complex.

The overall format is of the @code{"@var{string}"} field is:

@example
"@var{name}@r{[}:@var{symbol_descriptor}@r{]}
     @r{[}@var{type_number}@r{[}=@var{type_descriptor} @r{@dots{}]]}"
@end example

@var{name} is the name of the symbol represented by the stab.

The @var{symbol_descriptor} following the @samp{:} is an alphabetic
character that tells more specifically what kind of symbol the stab
represents. If the @var{symbol_descriptor} is omitted, but type
information follows, then the stab represents a local variable.  For a
list of symbol_descriptors, see @ref{Symbol descriptors,,Table C: Symbol
descriptors}.

Type information is either a @var{type_number}, or a
@samp{@var{type_number}=}.  The @var{type_number} alone is a type
reference, referring directly to a type that has already been defined.

The @samp{@var{type_number}=} is a type definition, where the number
represents a new type which is about to be defined.  The type definition
may refer to other types by number, and those type numbers may be
followed by @samp{=} and nested definitions.

In a type definition, if the character that follows the equals sign is
non-numeric then it is a @var{type_descriptor}, and tells what kind of
type is about to be defined.  Any other values following the
@var{type_descriptor} vary, depending on the @var{type_descriptor}.  If
a number follows the @samp{=} then the number is a @var{type_reference}.
This is described more thoroughly in the section on types.  @xref{Type
Descriptors,,Table D: Type Descriptors}, for a list of
@var{type_descriptor} values.

@c FIXME! "too long" below introduced at J Gilmore's request; used to
@c say "more than 80 chars".  Why is vaguer better?
All this can make the @code{"@var{string}"} field quite long.  When the
@code{"@var{string}"} part of a stab is too long, the compiler splits
the @code{.stabs} directive into two @code{.stabs} directives.  Both
stabs duplicate exactly all but the @code{"@var{string}"} field.  The
@code{"@var{string}"} field of the first stab contains the first part of
the overlong string, marked as continued with a double-backslash at the
end.  The @code{"@var{string}"} field of the second stab holds the
second half of the overlong string.

@node C example
@section A simple example in C source

To get the flavor of how stabs describe source information for a C
program, let's look at the simple program:

@example
main() 
@{
        printf("Hello world");
@}
@end example

When compiled with @samp{-g}, the program above yields the following
@file{.s} file.  Line numbers have been added to make it easier to refer
to parts of the @file{.s} file in the description of the stabs that
follows.

@node Assembly code
@section The simple example at the assembly level

@example
1  gcc2_compiled.:
2  .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
3  .stabs "hello.c",100,0,0,Ltext0
4  .text
5  Ltext0:
6  .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
7  .stabs "char:t2=r2;0;127;",128,0,0,0
8  .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
9  .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
17 .stabs "float:t12=r1;4;0;",128,0,0,0
18 .stabs "double:t13=r1;8;0;",128,0,0,0
19 .stabs "long double:t14=r1;8;0;",128,0,0,0
20 .stabs "void:t15=15",128,0,0,0
21      .align 4
22 LC0:
23      .ascii "Hello, world!\12\0"
24      .align 4
25      .global _main
26      .proc 1
27 _main:
28 .stabn 68,0,4,LM1
29 LM1:
30      !#PROLOGUE# 0
31      save %sp,-136,%sp
32      !#PROLOGUE# 1
33      call ___main,0
34      nop
35 .stabn 68,0,5,LM2
36 LM2:
37 LBB2:
38      sethi %hi(LC0),%o1
39      or %o1,%lo(LC0),%o0
40      call _printf,0
41      nop
42 .stabn 68,0,6,LM3
43 LM3:
44 LBE2:
45 .stabn 68,0,6,LM4
46 LM4:
47 L1:
48      ret
49      restore
50 .stabs "main:F1",36,0,0,_main
51 .stabn 192,0,0,LBB2
52 .stabn 224,0,0,LBE2
@end example

This simple ``hello world'' example demonstrates several of the stab
types used to describe C language source files.  

@node Program structure
@chapter Encoding for the structure of the program

@menu
* Source file:: The path and name of the source file
* Line numbers::
* Procedures::
* Block structure::
@end menu

@node Source file
@section The path and name of the source file

@table @strong
@item Directive:
@code{.stabs}
@item Type:
@code{N_SO} 
@end table      

The first stabs in the .s file contain the name and path of the source
file that was compiled to produce the .s file.  This information is
contained in two records of stab type N_SO (100).
 
@example
   .stabs "path_name", N_SO, NIL, NIL, Code_address_of_program_start
   .stabs "file_name:", N_SO, NIL, NIL, Code_address_of_program_start
@end example

@example
2  .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
3  .stabs "hello.c",100,0,0,Ltext0
4       .text
5  Ltext0:
@end example

@node Line numbers
@section Line Numbers 

@table @strong
@item Directive:
@code{.stabn}
@item Type:
@code{N_SLINE}
@end table

The start of source lines is represented by the @code{N_SLINE} (68) stab
type.

@example
.stabn N_SLINE, NIL, @var{line}, @var{address}
@end example

@var{line} is a source line number; @var{address} represents the code
address for the start of that source line.

@example
27 _main:
28 .stabn 68,0,4,LM1
29 LM1:
30      !#PROLOGUE# 0
@end example

@node Procedures
@section Procedures 

@table @strong
@item Directive:
@code{.stabs}
@item Type:
@code{N_FUN}
@item Symbol Descriptors:
@code{f} (local), @code{F} (global)
@end table

Procedures are described by the @code{N_FUN} stab type.  The symbol
descriptor for a procedure is @samp{F} if the procedure is globally
scoped and @samp{f} if the procedure is static (locally scoped).

The @code{N_FUN} stab representing a procedure is located immediately
following the code of the procedure.  The @code{N_FUN} stab is in turn
directly followed by a group of other stabs describing elements of the
procedure.  These other stabs describe the procedure's parameters, its
block local variables and its block structure. 

@example
48      ret
49      restore
@end example

The @code{.stabs} entry after this code fragment shows the @var{name} of
the procedure (@code{main}); the type descriptor @var{desc} (@code{F},
for a global procedure); a reference to the predefined type @code{int}
for the return type; and the starting @var{address} of the procedure.

Here is an exploded summary (with whitespace introduced for clarity),
followed by line 50 of our sample assembly output, which has this form:

@example
.stabs "@var{name}:
        @var{desc}  @r{(global proc @samp{F})}
        @var{return_type_ref}  @r{(int)}
       ",N_FUN, NIL, NIL,
       @var{address}
@end example

@example
50 .stabs "main:F1",36,0,0,_main
@end example

@node Block Structure
@section Block Structure

@table @strong
@item Directive:
@code{.stabn}