stabs.texinfo

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

least) uses the parameter symbols to keep track of whether it needs to
print nameless arguments in addition to the formal parameters which it
has printed because each one has a stab.  For example, in 

@example
extern int fprintf (FILE *stream, char *format, @dots{});
@dots{}
fprintf (stdout, "%d\n", x);
@end example

there are stabs for @code{stream} and @code{format}.  On most machines,
the debugger can only print those two arguments (because it has no way
of knowing that additional arguments were passed), but on the VAX or
other machines with a calling convention which indicates the number of
words of arguments, the debugger can print all three arguments.  To do
so, the parameter symbol (symbol descriptor @samp{p}) (not necessarily
@samp{r} or symbol descriptor omitted symbols) needs to contain the
actual type as passed (for example, @code{double} not @code{float} if it
is passed as a double and converted to a float).

@node Reference Parameters
@subsection Passing Parameters by Reference

If the parameter is passed by reference (e.g., Pascal @code{VAR}
parameters), then the symbol descriptor is @samp{v} if it is in the
argument list, or @samp{a} if it in a register.  Other than the fact
that these contain the address of the parameter rather than the
parameter itself, they are identical to @samp{p} and @samp{R},
respectively.  I believe @samp{a} is an AIX invention; @samp{v} is
supported by all stabs-using systems as far as I know.

@node Conformant Arrays
@subsection Passing Conformant Array Parameters

@c Is this paragraph correct?  It is based on piecing together patchy
@c information and some guesswork
Conformant arrays are a feature of Modula-2, and perhaps other
languages, in which the size of an array parameter is not known to the
called function until run-time.  Such parameters have two stabs: a
@samp{x} for the array itself, and a @samp{C}, which represents the size
of the array.  The value of the @samp{x} stab is the offset in the
argument list where the address of the array is stored (it this right?
it is a guess); the value of the @samp{C} stab is the offset in the
argument list where the size of the array (in elements? in bytes?) is
stored.

@node Types
@chapter Defining Types

The examples so far have described types as references to previously
defined types, or defined in terms of subranges of or pointers to
previously defined types.  This chapter describes the other type
descriptors that may follow the @samp{=} in a type definition.

@menu
* Builtin Types::		Integers, floating point, void, etc.
* Miscellaneous Types::		Pointers, sets, files, etc.
* Cross-References::		Referring to a type not yet defined.
* Subranges::			A type with a specific range.
* Arrays::			An aggregate type of same-typed elements.
* Strings::			Like an array but also has a length.
* Enumerations::		Like an integer but the values have names.
* Structures::			An aggregate type of different-typed elements.
* Typedefs::			Giving a type a name.
* Unions::			Different types sharing storage.
* Function Types::
@end menu

@node Builtin Types
@section Builtin Types

Certain types are built in (@code{int}, @code{short}, @code{void},
@code{float}, etc.); the debugger recognizes these types and knows how
to handle them.  Thus, don't be surprised if some of the following ways
of specifying builtin types do not specify everything that a debugger
would need to know about the type---in some cases they merely specify
enough information to distinguish the type from other types.

The traditional way to define builtin types is convoluted, so new ways
have been invented to describe them.  Sun's @code{acc} uses special
builtin type descriptors (@samp{b} and @samp{R}), and IBM uses negative
type numbers.  GDB accepts all three ways, as of version 4.8; dbx just
accepts the traditional builtin types and perhaps one of the other two
formats.  The following sections describe each of these formats.

@menu
* Traditional Builtin Types::	Put on your seat belts and prepare for kludgery
* Builtin Type Descriptors::	Builtin types with special type descriptors
* Negative Type Numbers::	Builtin types using negative type numbers
@end menu

@node Traditional Builtin Types
@subsection Traditional Builtin Types

This is the traditional, convoluted method for defining builtin types.
There are several classes of such type definitions: integer, floating
point, and @code{void}.

@menu
* Traditional Integer Types::
* Traditional Other Types::
@end menu

@node Traditional Integer Types
@subsubsection Traditional Integer Types

Often types are defined as subranges of themselves.  If the bounding values
fit within an @code{int}, then they are given normally.  For example:

@example
.stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0    # @r{128 is N_LSYM}
.stabs "char:t2=r2;0;127;",128,0,0,0
@end example

Builtin types can also be described as subranges of @code{int}:

@example
.stabs "unsigned short:t6=r1;0;65535;",128,0,0,0
@end example

If the lower bound of a subrange is 0 and the upper bound is -1,
the type is an unsigned integral type whose bounds are too
big to describe in an @code{int}.  Traditionally this is only used for
@code{unsigned int} and @code{unsigned long}:

@example
.stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
@end example

For larger types, GCC 2.4.5 puts out bounds in octal, with one or more
leading zeroes.  In this case a negative bound consists of a number
which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in
the number (except the sign bit), and a positive bound is one which is a
1 bit for each bit in the number (except possibly the sign bit).  All
known versions of dbx and GDB version 4 accept this (at least in the
sense of not refusing to process the file), but GDB 3.5 refuses to read
the whole file containing such symbols.  So GCC 2.3.3 did not output the
proper size for these types.  As an example of octal bounds, the string
fields of the stabs for 64 bit integer types look like:

@c .stabs directives, etc., omitted to make it fit on the page.
@example
long int:t3=r1;001000000000000000000000;000777777777777777777777;
long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777;
@end example

If the lower bound of a subrange is 0 and the upper bound is negative,
the type is an unsigned integral type whose size in bytes is the
absolute value of the upper bound.  I believe this is a Convex
convention for @code{unsigned long long}.

If the lower bound of a subrange is negative and the upper bound is 0,
the type is a signed integral type whose size in bytes is
the absolute value of the lower bound.  I believe this is a Convex
convention for @code{long long}.  To distinguish this from a legitimate
subrange, the type should be a subrange of itself.  I'm not sure whether
this is the case for Convex.

@node Traditional Other Types
@subsubsection Traditional Other Types

If the upper bound of a subrange is 0 and the lower bound is positive,
the type is a floating point type, and the lower bound of the subrange
indicates the number of bytes in the type:

@example
.stabs "float:t12=r1;4;0;",128,0,0,0
.stabs "double:t13=r1;8;0;",128,0,0,0
@end example

However, GCC writes @code{long double} the same way it writes
@code{double}, so there is no way to distinguish.

@example
.stabs "long double:t14=r1;8;0;",128,0,0,0
@end example

Complex types are defined the same way as floating-point types; there is
no way to distinguish a single-precision complex from a double-precision
floating-point type.

The C @code{void} type is defined as itself:

@example
.stabs "void:t15=15",128,0,0,0
@end example

I'm not sure how a boolean type is represented.

@node Builtin Type Descriptors
@subsection Defining Builtin Types Using Builtin Type Descriptors

This is the method used by Sun's @code{acc} for defining builtin types.
These are the type descriptors to define builtin types:

@table @code
@c FIXME: clean up description of width and offset, once we figure out
@c what they mean
@item b @var{signed} @var{char-flag} @var{width} ; @var{offset} ; @var{nbits} ;
Define an integral type.  @var{signed} is @samp{u} for unsigned or
@samp{s} for signed.  @var{char-flag} is @samp{c} which indicates this
is a character type, or is omitted.  I assume this is to distinguish an
integral type from a character type of the same size, for example it
might make sense to set it for the C type @code{wchar_t} so the debugger
can print such variables differently (Solaris does not do this).  Sun
sets it on the C types @code{signed char} and @code{unsigned char} which
arguably is wrong.  @var{width} and @var{offset} appear to be for small
objects stored in larger ones, for example a @code{short} in an
@code{int} register.  @var{width} is normally the number of bytes in the
type.  @var{offset} seems to always be zero.  @var{nbits} is the number
of bits in the type.

Note that type descriptor @samp{b} used for builtin types conflicts with
its use for Pascal space types (@pxref{Miscellaneous Types}); they can
be distinguished because the character following the type descriptor
will be a digit, @samp{(}, or @samp{-} for a Pascal space type, or
@samp{u} or @samp{s} for a builtin type.

@item w
Documented by AIX to define a wide character type, but their compiler
actually uses negative type numbers (@pxref{Negative Type Numbers}).

@item R @var{fp-type} ; @var{bytes} ;
Define a floating point type.  @var{fp-type} has one of the following values:

@table @code
@item 1 (NF_SINGLE)
IEEE 32-bit (single precision) floating point format.

@item 2 (NF_DOUBLE)
IEEE 64-bit (double precision) floating point format.

@item 3 (NF_COMPLEX)
@item 4 (NF_COMPLEX16)
@item 5 (NF_COMPLEX32)
@c "GDB source" really means @file{include/aout/stab_gnu.h}, but trying
@c to put that here got an overfull hbox.
These are for complex numbers.  A comment in the GDB source describes
them as Fortran @code{complex}, @code{double complex}, and
@code{complex*16}, respectively, but what does that mean?  (i.e., Single
precision?  Double precision?).

@item 6 (NF_LDOUBLE)
Long double.  This should probably only be used for Sun format
@code{long double}, and new codes should be used for other floating
point formats (@code{NF_DOUBLE} can be used if a @code{long double} is
really just an IEEE double, of course).
@end table

@var{bytes} is the number of bytes occupied by the type.  This allows a
debugger to perform some operations with the type even if it doesn't
understand @var{fp-type}.

@item g @var{type-information} ; @var{nbits}
Documented by AIX to define a floating type, but their compiler actually
uses negative type numbers (@pxref{Negative Type Numbers}).

@item c @var{type-information} ; @var{nbits}
Documented by AIX to define a complex type, but their compiler actually
uses negative type numbers (@pxref{Negative Type Numbers}).
@end table

The C @code{void} type is defined as a signed integral type 0 bits long:
@example
.stabs "void:t19=bs0;0;0",128,0,0,0
@end example
The Solaris compiler seems to omit the trailing semicolon in this case.
Getting sloppy in this way is not a swift move because if a type is
embedded in a more complex expression it is necessary to be able to tell
where it ends.

I'm not sure how a boolean type is represented.

@node Negative Type Numbers
@subsection Negative Type Numbers

This is the method used in XCOFF for defining builtin types.
Since the debugger knows about the builtin types anyway, the idea of
negative type numbers is simply to give a special type number which
indicates the builtin type.  There is no stab defining these types.

There are several subtle issues with negative type numbers.

One is the size of the type.  A builtin type (for example the C types
@code{int} or @code{long}) might have different sizes depending on
compiler options, the target architecture, the ABI, etc.  This issue
doesn't come up for IBM tools since (so far) they just target the
RS/6000; the sizes indicated below for each size are what the IBM
RS/6000 tools use.  To deal with differing sizes, either define separate
negative type numbers for each size (which works but requires changing
the debugger, and, unless you get both AIX dbx and GDB to accept the
change, introduces an incompatibility), or use a type attribute
(@pxref{String Field}) to define a new type with the appropriate size
(which merely requires a debugger which understands type attributes,
like AIX dbx or GDB).  For example,

@example
.stabs "boolean:t10=@@s8;-16",128,0,0,0
@end example

defines an 8-bit boolean type, and

@example
.stabs "boolean:t10=@@s64;-16",128,0,0,0
@end example

defines a 64-bit boolean type.

A similar issue is the format of the type.  This comes up most often for
floating-point types, which could have various formats (particularly
extended doubles, which vary quite a bit even among IEEE systems).
Again, it is best to define a new negative type number for each
different format; changing the format based on the target system has
various problems.  One such problem is that the Alpha has both VAX and
IEEE floating types.