OpenE2K
/
binutils-gdb
12
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

* stabs.texinfo (String Field): Document type number pairs here, 

instead of in the Sun specific section.
	(Include Files): The GNU linker supports the N_BINCL
	optimization.  Clarify the N_BINCL value, and what it is used
	for.
	(Procedures): Document N_FUN with an empty string to mark the end
	of a function.
	(Typedefs): Mention that Sun compilers may use N_GSYM for a type.
	(Sun Differences): Remove this node, as the information is now
	elsewhere in the main document.
	(Stab Section Basics): Mention that the GNU linker may optimize
	stabs and remove the leading N_UNDF symbol.
This commit is contained in:
Ian Lance Taylor 1997-02-27 22:48:47 +00:00
parent 99cd62ed9c
commit b434a5b9d3
2 changed files with 66 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
gdb/doc/ChangeLog
View File

@ -1,3 +1,18 @@
Thu Feb 27 17:45:19 1997 Ian Lance Taylor <ian@cygnus.com>
* stabs.texinfo (String Field): Document type number pairs here,
instead of in the Sun specific section.
(Include Files): The GNU linker supports the N_BINCL
optimization. Clarify the N_BINCL value, and what it is used
for.
(Procedures): Document N_FUN with an empty string to mark the end
of a function.
(Typedefs): Mention that Sun compilers may use N_GSYM for a type.
(Sun Differences): Remove this node, as the information is now
elsewhere in the main document.
(Stab Section Basics): Mention that the GNU linker may optimize
stabs and remove the leading N_UNDF symbol.
Mon Dec 9 12:23:32 1996 Roland Pesch <roland@wrs.com>
* gdb.texinfo, refcard.tex: Restore author credit

92
gdb/doc/stabs.texinfo
View File

@ -14,7 +14,7 @@ END-INFO-DIR-ENTRY
@ifinfo
This document describes the stabs debugging symbol tables.
Copyright 1992, 1993 Free Software Foundation, Inc.
Copyright 1992, 93, 94, 95, 1997 Free Software Foundation, Inc.
Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon,
and David MacKenzie.
@ -52,7 +52,7 @@ regarded as a program in the language TeX).
@end tex
@vskip 0pt plus 1filll
Copyright @copyright{} 1992, 1993 Free Software Foundation, Inc.
Copyright @copyright{} 1992, 93, 94, 95, 1997 Free Software Foundation, Inc.
Contributed by Cygnus Support.
Permission is granted to make and distribute verbatim copies of
@ -80,8 +80,6 @@ This document describes the stabs debugging format.
* Type Descriptors:: Table of type descriptors
* Expanded Reference:: Reference information by stab type
* Questions:: Questions and anomolies
* Sun Differences:: Differences between GNU stabs and Sun
native stabs
* Stab Sections:: In some object file formats, stabs are
in sections.
* Symbol Types Index:: Index of symbolic stab symbol type names.
@ -240,6 +238,18 @@ type is about to be defined. Any other values following the
a number follows the @samp{=} then the number is a @var{type-reference}.
For a full description of types, @ref{Types}.
A @var{type-number} is often a single number. The GNU and Sun tools
additionally permit a @var{type-number} to be a pair
(@var{file-number},@var{filetype-number}) (the parentheses appear in the
string, and serve to distinguish the two cases). The @var{file-number}
is a number starting with 1 which is incremented for each seperate
source file in the compilation (e.g., in C, each header file gets a
different number). The @var{filetype-number} is a number starting with
1 which is incremented for each new type defined in the file.
(Separating the file number and the type number permits the
@code{N_BINCL} optimization to succeed more often; see @ref{Include
Files}).
There is an AIX extension for type attributes. Following the @samp{=}
are any number of type attributes. Each one starts with @samp{@@} and
ends with @samp{;}. Debuggers, including AIX's dbx and GDB 4.10, skip
@ -463,7 +473,7 @@ the start of this one. To specify the main source file again, use an
@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 Sun linker puts data into some of the other
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
@ -473,16 +483,17 @@ 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 occurance is replaced by an @code{N_EXCL} symbol. I believe
the Sun (SunOS4, not sure about Solaris) linker is the only one which
supports this feature.
the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only
ones which supports this feature.
The SunOS4 linker sets 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 the file number. The value of an @code{N_EXCL} symbol is the
same as the value of the @code{N_BINCL} symbol it replaces. I do not
know if this information is used by anything. The @code{N_EINCL} value,
and the values of the other and description fields for all three, appear
to always be zero.
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
@ -632,6 +643,15 @@ 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.
If functions can appear in different sections, then the debugger may not
be able to find the end of a function. Recent versions of GCC will mark
the end of a function with an @code{N_FUN} symbol with an empty string
for the name. The value is the address of the end of the current
function. Without such a symbol, there is no indication of the address
of the end of a function, and you must assume that it ended at the
starting address of the next function or at the end of the text section
for the program.
@node Nested Procedures
@section Nested Procedures
@ -2060,7 +2080,8 @@ For example,
@end example
specifies that @code{s_typedef} refers to type number 16. Such stabs
have symbol type @code{N_LSYM} (or @code{C_DECL} for XCOFF).
have symbol type @code{N_LSYM} (or @code{C_DECL} for XCOFF). (The Sun
documentation mentions using @code{N_GSYM} in some cases).
If you are specifying the tag name for a structure, union, or
enumeration, use the @samp{T} symbol descriptor instead. I believe C is
@ -3841,25 +3862,6 @@ What ends the procedure scope? Is it the proc block's @code{N_RBRAC} or the
next @code{N_FUN}? (I believe its the first.)
@end itemize
@node Sun Differences
@appendix Differences Between GNU Stabs and Sun Native Stabs
@c FIXME: Merge all this stuff into the main body of the document.
@itemize @bullet
@item
GNU C stabs define @emph{all} types, file or procedure scope, as
@code{N_LSYM}. Sun doc talks about using @code{N_GSYM} too.
@item
Sun C stabs use type number pairs in the format
(@var{file-number},@var{type-number}) where @var{file-number} is a
number starting with 1 and incremented for each sub-source file in the
compilation. @var{type-number} is a number starting with 1 and
incremented for each new type defined in the compilation. GNU C stabs
use the type number alone, with no source file number.
@end itemize
@node Stab Sections
@appendix Using Stabs in Their Own Sections
@ -3928,17 +3930,25 @@ header @code{sh_type} member set to @code{SHT_STRTAB} to mark it as a
string table. SOM and COFF have no way of linking the sections together
or marking them as string tables.
For COFF, the @code{.stab} and @code{.stabstr} sections are simply
For COFF, the @code{.stab} and @code{.stabstr} sections may be simply
concatenated by the linker. GDB then uses the @code{n_desc} fields to
figure out the extent of the original sections. Similarly, the
@code{n_value} fields of the header symbols are added together in order
to get the actual position of the strings in a desired @code{.stabstr}
section. Although this design obviates any need for the linker to relocate
or otherwise manipulate @code{.stab} and @code{.stabstr} sections, it also
requires some care to ensure that the offsets are calculated correctly.
For instance, if the linker were to pad in between the @code{.stabstr}
sections before concatenating, then the offsets to strings in the middle
of the executable's @code{.stabstr} section would be wrong.
section. Although this design obviates any need for the linker to
relocate or otherwise manipulate @code{.stab} and @code{.stabstr}
sections, it also requires some care to ensure that the offsets are
calculated correctly. For instance, if the linker were to pad in
between the @code{.stabstr} sections before concatenating, then the
offsets to strings in the middle of the executable's @code{.stabstr}
section would be wrong.
The GNU linker is able to optimize stabs information by merging
duplicate strings and removing duplicate header file information
(@pxref{Include Files}). When the GNU linker optimizes stabs in
sections, it removes the leading @code{N_UNDF} symbol, and arranges for
all the @code{n_strx} fields to be relative to the start of the
@code{.stabstr} section.
@node ELF Linker Relocation
@appendixsec Having the Linker Relocate Stabs in ELF