diff options
| -rw-r--r-- | gdb/doc/ChangeLog | 5 | ||||
| -rw-r--r-- | gdb/doc/stabs.texinfo | 210 |
2 files changed, 81 insertions, 134 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 7fb748f..8328785 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,8 @@ +Mon May 8 09:30:36 1995 Jim Kingdon (kingdon@lioth.cygnus.com) + + * stabs.texinfo: Remove node `XCOFF differences'. Describe value of + C_FUN stab. Other cleanups. + Wed Apr 19 07:02:19 1995 Jim Kingdon (kingdon@lioth.cygnus.com) * remote.texi (Bootstrapping): Clarify that flush_i_cache is only diff --git a/gdb/doc/stabs.texinfo b/gdb/doc/stabs.texinfo index 27d6d65..ca01bb7 100644 --- a/gdb/doc/stabs.texinfo +++ b/gdb/doc/stabs.texinfo @@ -74,14 +74,12 @@ This document describes the stabs debugging format. * Variables:: * Types:: Type definitions * Symbol Tables:: Symbol information in symbol tables -* Cplusplus:: Appendixes: +* Cplusplus:: Stabs specific to C++ * Stab Types:: Symbol types in a.out files * Symbol Descriptors:: Table of symbol descriptors * Type Descriptors:: Table of type descriptors * 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 * Stab Sections:: In some object file formats, stabs are @@ -398,7 +396,7 @@ 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. +function. I'm not sure how XCOFF handles this. @node Source Files @section Paths and Names of the Source Files @@ -431,9 +429,10 @@ For example: Ltext0: @end example +@findex C_FILE Instead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler -directive which assembles to a standard COFF @code{.file} symbol; -explaining this in detail is outside the scope of this document. +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 @@ -535,24 +534,31 @@ 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. 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). - +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. The -value is the address of the start of the function. For a.out, 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. +(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 @@ -690,18 +696,27 @@ Sun documents the desc field of @code{N_LBRAC} and However, dbx seems to not care, and GCC always sets desc to zero. +@findex .bb +@findex .be +@findex C_BLOCK +For XCOFF, block scope is indicated with @code{C_BLOCK} symbols. If the +name of the symbol is @samp{.bb}, then it is the beginning of the block; +if the name of the symbol is @samp{.be}; it is the end of the block. + @node Alternate Entry Points @section Alternate Entry Points +@findex N_ENTRY +@findex C_ENTRY Some languages, like Fortran, have the ability to enter procedures at some place other than the beginning. One can declare an alternate entry -point. The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN compiler -doesn't use it. According to AIX documentation, only the name of a -@code{C_ENTRY} stab is significant; the address of the alternate entry -point comes from the corresponding external symbol. A previous revision -of this document said that the value of an @code{N_ENTRY} stab was the -address of the alternate entry point, but I don't know the source for -that information. +point. The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN +compiler doesn't use it. According to AIX documentation, only the name +of a @code{C_ENTRY} stab is significant; the address of the alternate +entry point comes from the corresponding external symbol. A previous +revision of this document said that the value of an @code{N_ENTRY} stab +was the address of the alternate entry point, but I don't know the +source for that information. @node Constants @chapter Constants @@ -795,7 +810,8 @@ long as that function executes (C calls such variables @dfn{automatic}), it can be allocated in a register (@pxref{Register Variables}) or on the stack. -@findex N_LSYM +@findex N_LSYM, for stack variables +@findex C_LSYM Each variable allocated on the stack has a stab with the symbol descriptor omitted. Since type information should begin with a digit, @samp{-}, or @samp{(}, only those characters precluded from being used @@ -803,7 +819,8 @@ for symbol descriptors. However, the Acorn RISC machine (ARM) is said to get this wrong: it puts out a mere type definition here, without the preceding @samp{@var{type-number}=}. This is a bad idea; there is no guarantee that type descriptors are distinct from symbol descriptors. -Stabs for stack variables use the @code{N_LSYM} stab type. +Stabs for stack variables use the @code{N_LSYM} stab type, or +@code{C_LSYM} for XCOFF. The value of the stab is the offset of the variable within the local variables. On most machines this is an offset from the frame @@ -837,10 +854,12 @@ produces the following stabs: @section Global Variables @findex N_GSYM +@findex C_GSYM +@c FIXME: verify for sure that it really is C_GSYM on XCOFF A variable whose scope is not specific to just one source file is represented by the @samp{G} symbol descriptor. These stabs use the -@code{N_GSYM} stab type. The type information for the stab -(@pxref{String Field}) gives the type of the variable. +@code{N_GSYM} stab type (C_GSYM for XCOFF). The type information for +the stab (@pxref{String Field}) gives the type of the variable. For example, the following source code: @@ -874,11 +893,13 @@ variable. @section Register Variables @findex N_RSYM +@findex C_RSYM @c According to an old version of this manual, AIX uses C_RPSYM instead @c of C_RSYM. I am skeptical; this should be verified. -Register variables have their own stab type, @code{N_RSYM}, and their -own symbol descriptor, @samp{r}. The stab's value is the -number of the register where the variable data will be stored. +Register variables have their own stab type, @code{N_RSYM} +(@code{C_RSYM} for XCOFF), and their own symbol descriptor, @samp{r}. +The stab's value is the number of the register where the variable data +will be stored. @c .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc) AIX defines a separate symbol descriptor @samp{d} for floating point @@ -970,6 +991,9 @@ yield the following stabs: .stabs "var_noinit:S1",40,0,0,_var_noinit # @r{40 is N_LCSYM} @end example +@findex C_STSYM +@findex C_BSTAT +@findex C_ESTAT In XCOFF files, the stab type need not indicate the section; @code{C_STSYM} can be used for all statics. Also, each static variable is enclosed in a static block. A @code{C_BSTAT} (emitted with a @@ -1045,11 +1069,12 @@ parameters are declared in the source file). The exact form of the stab depends on how the parameter is being passed. @findex N_PSYM +@findex C_PSYM Parameters passed on the stack use the symbol descriptor @samp{p} and -the @code{N_PSYM} symbol type. The value of the symbol is an offset -used to locate the parameter on the stack; its exact meaning is -machine-dependent, but on most machines it is an offset from the frame -pointer. +the @code{N_PSYM} symbol type (or @code{C_PSYM} for XCOFF). The value +of the symbol is an offset used to locate the parameter on the stack; +its exact meaning is machine-dependent, but on most machines it is an +offset from the frame pointer. As a simple example, the code: @@ -1107,11 +1132,11 @@ know that it is an argument. @findex N_RSYM, for parameters Because that approach is kind of ugly, some compilers use symbol descriptor @samp{P} or @samp{R} to indicate an argument which is in a -register. Symbol type @code{C_RPSYM} is used with @samp{R} and -@code{N_RSYM} is used with @samp{P}. The symbol's value is -the register number. @samp{P} and @samp{R} mean the same thing; the -difference is that @samp{P} is a GNU invention and @samp{R} is an IBM -(XCOFF) invention. As of version 4.9, GDB should handle either one. +register. Symbol type @code{C_RPSYM} is used in XCOFF and @code{N_RSYM} +is used otherwise. The symbol's value is the register number. @samp{P} +and @samp{R} mean the same thing; the difference is that @samp{P} is a +GNU invention and @samp{R} is an IBM (XCOFF) invention. As of version +4.9, GDB should handle either one. There is at least one case where GCC uses a @samp{p} and @samp{r} pair rather than @samp{P}; this is where the argument is passed in the @@ -2018,6 +2043,8 @@ fields; see @ref{Cplusplus}. @node Typedefs @section Giving a Type a Name +@findex N_LSYM, for types +@findex C_DECL, for types To give a type a name, use the @samp{t} symbol descriptor. The type is specified by the type information (@pxref{String Field}) for the stab. For example, @@ -3552,9 +3579,9 @@ gstring; see @ref{Strings}. @c FIXME: This appendix should go away; see N_PSYM or N_SO for an example. For a full list of stab types, and cross-references to where they are -described, see @ref{Stab Types}. This appendix just duplicates certain -information from the main body of this document; eventually the -information will all be in one place. +described, see @ref{Stab Types}. This appendix just covers certain +stabs which are not yet described in the main body of this document; +eventually the information will all be in one place. Format of an entry: @@ -3806,93 +3833,8 @@ symbols of file scope. This is true for default, @samp{-ansi} and @item 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.) - -@item -@c FIXME: This should go with the other stuff about global variables. -Global variable stabs don't have location information. This comes -from the external symbol for the same variable. The external symbol -has a leading underbar on the _name of the variable and the stab does -not. How do we know these two symbol table entries are talking about -the same symbol when their names are different? (Answer: the debugger -knows that external symbols have leading underbars). - -@c FIXME: This is absurdly vague; there all kinds of differences, some -@c of which are the same between gnu & sun, and some of which aren't. -@c In particular, I'm pretty sure GCC works with Sun dbx by default. -@c @item -@c Can GCC be configured to output stabs the way the Sun compiler -@c does, so that their native debugging tools work? <NO?> It doesn't by -@c default. GDB reads either format of stab. (GCC or SunC). How about -@c dbx? @end itemize -@node XCOFF Differences -@appendix Differences Between GNU Stabs in a.out and GNU Stabs in XCOFF - -@c FIXME: Merge *all* these into the main body of the document. -The AIX/RS6000 native object file format is XCOFF with stabs. This -appendix only covers those differences which are not covered in the main -body of this document. - -@itemize @bullet -@item -BSD a.out stab types correspond to AIX XCOFF storage classes. In general -the mapping is @code{N_@var{stabtype}} becomes @code{C_@var{stabtype}}. -Some stab types in a.out are not supported in XCOFF; most of these use -@code{C_DECL}. - -@c FIXME: I think they are trying to say something about whether the -@c assembler defaults the value to the location counter. -@item -If the XCOFF stab is an @code{N_FUN} (@code{C_FUN}) then follow the -string field with @samp{,.} instead of just @samp{,}. -@end itemize - -I think that's it for @file{.s} file differences. They could stand to be -better presented. This is just a list of what I have noticed so far. -There are a @emph{lot} of differences in the information in the symbol -tables of the executable and object files. - -Mapping of a.out stab types to XCOFF storage classes: - -@example -stab type storage class -------------------------------- -N_GSYM C_GSYM -N_FNAME unused -N_FUN C_FUN -N_STSYM C_STSYM -N_LCSYM C_STSYM -N_MAIN unknown -N_PC unknown -N_RSYM C_RSYM -unknown C_RPSYM -N_M2C unknown -N_SLINE unknown -N_DSLINE unknown -N_BSLINE unknown -N_BROWSE unchanged -N_CATCH unknown -N_SSYM unknown -N_SO unknown -N_LSYM C_LSYM -various C_DECL -N_BINCL unknown -N_SOL unknown -N_PSYM C_PSYM -N_EINCL unknown -N_ENTRY C_ENTRY -N_LBRAC unknown -N_EXCL unknown -N_SCOPE unknown -N_RBRAC unknown -N_BCOMM C_BCOMM -N_ECOMM C_ECOMM -N_ECOML C_ECOML - -N_LENG unknown -@end example - @node Sun Differences @appendix Differences Between GNU Stabs and Sun Native Stabs |