stabs.texinfo

这个是LINUX下的GDB调度工具的源码

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

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

@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

@node Program Structure
@chapter Encoding the Structure of the Program

The elements of the program structure that stabs encode include the name
of the main function, the names of the source and include files, the
line numbers, procedure names and types, and the beginnings and ends of
blocks of code.

@menu
* Main Program::		Indicate what the main program is
* Source Files::		The path and name of the source file
* Include Files::               Names of include files
* Line Numbers::
* Procedures::
* Nested Procedures::
* Block Structure::
* Alternate Entry Points::      Entering procedures except at the beginning.
@end menu

@node Main Program
@section Main Program

@findex N_MAIN
Most languages allow the main program to have any name.  The
@code{N_MAIN} stab type tells the debugger the name that is used in this
program.  Only the string field is significant; it is the name of
a function which is the main program.  Most C compilers do not use this
stab (they expect the debugger to assume that the name is @code{main}),
but some C compilers emit an @code{N_MAIN} stab for the @code{main}
function.  I'm not sure how XCOFF handles this.

@node Source Files
@section Paths and Names of the Source Files

@findex N_SO
Before any other stabs occur, there must be a stab specifying the source
file.  This information is contained in a symbol of stab type
@code{N_SO}; the string field contains the name of the file.  The
value of the symbol is the start address of the portion of the
text section corresponding to that file.

Some compilers use the desc field to indicate the language of the
source file.  Sun's compilers started this usage, and the first
constants are derived from their documentation.  Languages added
by gcc/gdb start at 0x32 to avoid conflict with languages Sun may
add in the future.  A desc field with a value 0 indicates that no
language has been specified via this mechanism.

@table @asis
@item @code{N_SO_AS} (0x1)
Assembly language
@item @code{N_SO_C}  (0x2)
K&R traditional C
@item @code{N_SO_ANSI_C} (0x3)
ANSI C
@item @code{N_SO_CC}  (0x4)
C++
@item @code{N_SO_FORTRAN} (0x5)
Fortran
@item @code{N_SO_PASCAL} (0x6)
Pascal
@item @code{N_SO_FORTRAN90} (0x7)
Fortran90
@item @code{N_SO_OBJC} (0x32)
Objective-C
@item @code{N_SO_OBJCPLUS} (0x33)
Objective-C++
@end table

Some compilers (for example, GCC2 and SunOS4 @file{/bin/cc}) also
include the directory in which the source was compiled, in a second
@code{N_SO} symbol preceding the one containing the file name.  This
symbol can be distinguished by the fact that it ends in a slash.  Code
from the @code{cfront} C@t{++} compiler can have additional @code{N_SO} symbols for
nonexistent source files after the @code{N_SO} for the real source file;
these are believed to contain no useful information.

For example:

@example
.stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0     # @r{100 is N_SO}
.stabs "hello.c",100,0,0,Ltext0
        .text
Ltext0:
@end example

@findex C_FILE
Instead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler
directive which assembles to a @code{C_FILE} symbol; explaining this in
detail is outside the scope of this document.

@c FIXME: Exactly when should the empty N_SO be used?  Why?
If it is useful to indicate the end of a source file, this is done with
an @code{N_SO} symbol with an empty string for the name.  The value is
the address of the end of the text section for the file.  For some
systems, there is no indication of the end of a source file, and you
just need to figure it ended when you see an @code{N_SO} for a different
source file, or a symbol ending in @code{.o} (which at least some
linkers insert to mark the start of a new @code{.o} file).

@node Include Files
@section Names of Include Files

There are several schemes for dealing with include files: the
traditional @code{N_SOL} approach, Sun's @code{N_BINCL} approach, and the
XCOFF @code{C_BINCL} approach (which despite the similar name has little in
common with @code{N_BINCL}).

@findex N_SOL
An @code{N_SOL} symbol specifies which include file subsequent symbols
refer to.  The string field is the name of the file and the value is the
text address corresponding to the end of the previous include file and
the start of this one.  To specify the main source file again, use an
@code{N_SOL} symbol with the name of the main source file.

@findex N_BINCL
@findex N_EINCL
@findex N_EXCL
The @code{N_BINCL} approach works as follows.  An @code{N_BINCL} symbol
specifies the start of an include file.  In an object file, only the
string is significant; the linker puts data into some of the other
fields.  The end of the include file is marked by an @code{N_EINCL}
symbol (which has no string field).  In an object file, there is no
significant data in the @code{N_EINCL} symbol.  @code{N_BINCL} and
@code{N_EINCL} can be nested.

If the linker detects that two source files have identical stabs between
an @code{N_BINCL} and @code{N_EINCL} pair (as will generally be the case
for a header file), then it only puts out the stabs once.  Each
additional occurrence is replaced by an @code{N_EXCL} symbol.  I believe
the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only
ones which supports this feature.

A linker which supports this feature will set the value of a
@code{N_BINCL} symbol to the total of all the characters in the stabs
strings included in the header file, omitting any file numbers.  The
value of an @code{N_EXCL} symbol is the same as the value of the
@code{N_BINCL} symbol it replaces.  This information can be used to
match up @code{N_EXCL} and @code{N_BINCL} symbols which have the same
filename.  The @code{N_EINCL} value, and the values of the other and
description fields for all three, appear to always be zero.

@findex C_BINCL
@findex C_EINCL
For the start of an include file in XCOFF, use the @file{.bi} assembler
directive, which generates a @code{C_BINCL} symbol.  A @file{.ei}
directive, which generates a @code{C_EINCL} symbol, denotes the end of
the include file.  Both directives are followed by the name of the
source file in quotes, which becomes the string for the symbol.
The value of each symbol, produced automatically by the assembler
and linker, is the offset into the executable of the beginning
(inclusive, as you'd expect) or end (inclusive, as you would not expect)
of the portion of the COFF line table that corresponds to this include
file.  @code{C_BINCL} and @code{C_EINCL} do not nest.

@node Line Numbers
@section Line Numbers

@findex N_SLINE
An @code{N_SLINE} symbol represents the start of a source line.  The
desc field contains the line number and the value contains the code
address for the start of that source line.  On most machines the address
is absolute; for stabs in sections (@pxref{Stab Sections}), it is
relative to the function in which the @code{N_SLINE} symbol occurs.

@findex N_DSLINE
@findex N_BSLINE
GNU documents @code{N_DSLINE} and @code{N_BSLINE} symbols for line
numbers in the data or bss segments, respectively.  They are identical
to @code{N_SLINE} but are relocated differently by the linker.  They
were intended to be used to describe the source location of a variable
declaration, but I believe that GCC2 actually puts the line number in
the desc field of the stab for the variable itself.  GDB has been
ignoring these symbols (unless they contain a string field) since
at least GDB 3.5.

For single source lines that generate discontiguous code, such as flow
of control statements, there may be more than one line number entry for
the same source line.  In this case there is a line number entry at the
start of each code range, each with the same line number.

XCOFF does not use stabs for line numbers.  Instead, it uses COFF line
numbers (which are outside the scope of this document).  Standard COFF
line numbers cannot deal with include files, but in XCOFF this is fixed
with the @code{C_BINCL} method of marking include files (@pxref{Include
Files}).

@node Procedures
@section Procedures

@findex N_FUN, for functions
@findex N_FNAME
@findex N_STSYM, for functions (Sun acc)
@findex N_GSYM, for functions (Sun acc)
All of the following stabs normally use the @code{N_FUN} symbol type.
However, Sun's @code{acc} compiler on SunOS4 uses @code{N_GSYM} and
@code{N_STSYM}, which means that the value of the stab for the function
is useless and the debugger must get the address of the function from
the non-stab symbols instead.  On systems where non-stab symbols have
leading underscores, the stabs will lack underscores and the debugger
needs to know about the leading underscore to match up the stab and the
non-stab symbol.  BSD Fortran is said to use @code{N_FNAME} with the
same restriction; the value of the symbol is not useful (I'm not sure it
really does use this, because GDB doesn't handle this and no one has
complained).

@findex C_FUN
A function is represented by an @samp{F} symbol descriptor for a global
(extern) function, and @samp{f} for a static (local) function.  For
a.out, the value of the symbol is the address of the start of the
function; it is already relocated.  For stabs in ELF, the SunPRO
compiler version 2.0.1 and GCC put out an address which gets relocated
by the linker.  In a future release SunPRO is planning to put out zero,
in which case the address can be found from the ELF (non-stab) symbol.
Because looking things up in the ELF symbols would probably be slow, I'm
not sure how to find which symbol of that name is the right one, and
this doesn't provide any way to deal with nested functions, it would
probably be better to make the value of the stab an address relative to
the start of the file, or just absolute.  See @ref{ELF Linker
Relocation} for more information on linker relocation of stabs in ELF
files.  For XCOFF, the stab uses the @code{C_FUN} storage class and the
value of the stab is meaningless; the address of the function can be
found from the csect symbol (XTY_LD/XMC_PR).

The type information of the stab represents the return type of the
function; thus @samp{foo:f5} means that foo is a function returning type
5.  There is no need to try to get the line number of the start of the
function from the stab for the function; it is in the next
@code{N_SLINE} symbol.

@c FIXME: verify whether the "I suspect" below is true or not.
Some compilers (such as Sun's Solaris compiler) support an extension for
specifying the types of the arguments.  I suspect this extension is not
used for old (non-prototyped) function definitions in C.  If the
extension is in use, the type information of the stab for the function
is followed by type information for each argument, with each argument
preceded by @samp{;}.  An argument type of 0 means that additional
arguments are being passed, whose types and number may vary (@samp{...}
in ANSI C).  GDB has tolerated this extension (parsed the syntax, if not
necessarily used the information) since at least version 4.8; I don't
know whether all versions of dbx tolerate it.  The argument types given
here are not redundant with the symbols for the formal parameters
(@pxref{Parameters}); they are the types of the arguments as they are
passed, before any conversions might take place.  For example, if a C
function which is declared without a prototype takes a @code{float}
argument, the value is passed as a @code{double} but then converted to a
@code{float}.  Debuggers need to use the types given in the arguments
when printing values, but when calling the function they need to use the
types given in the symbol defining the function.

If the return type and types of arguments of a function which is defined