* stabs.texinfo: Many changes to include information from the

AIX documentation.

gdb/doc/ChangeLog

@@ -1,5 +1,8 @@
 Thu Apr 29 09:36:25 1993  Jim Kingdon  (kingdon@cygnus.com)
 
+	* stabs.texinfo: Many changes to include information from the
+	AIX documentation.
+
 	* gdb.texinfo (Environment): Mention pitfall with .cshrc.
 
 Tue Apr 27 14:02:57 1993  Jim Kingdon  (kingdon@cygnus.com)

gdb/doc/stabs.texinfo

@@ -67,6 +67,7 @@ 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
+* Constants::			Constants
 * Simple types::
 * Example::                     A comprehensive example in C 
 * Variables::
@@ -156,17 +157,17 @@ 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
+The number in the type field gives some basic information about what
-field.  Each possible type number defines a different stab type.  The
+type of stab this is (or whether it @emph{is} a stab, as opposed to an
-stab type further defines the exact interpretation of, and possible
+ordinary symbol).  Each possible type number defines a different stab
-values for, any remaining @code{"@var{string}"}, @var{desc}, or
+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
+types,,Table A: Symbol types from stabs}) lists in numeric order the
-the possible type field values for stab directives.  The reference
+possible type field values for stab directives.  The reference section
-section that follows Table A describes the meaning of the fields for
+that follows Table A describes the meaning of the fields for each stab
-each stab type in detail.  The examples that follow this overview
+type in detail.  The examples that follow this overview introduce the
-introduce the stab types in terms of the source code elements they
+stab types in terms of the source code elements they describe.
-describe.
 
 For @code{.stabs} the @code{"@var{string}"} field holds the meat of the
 debugging information.  The generally unstructured nature of this field
@@ -182,6 +183,11 @@ The overall format is of the @code{"@var{string}"} field is:
 @end example
 
 @var{name} is the name of the symbol represented by the stab.
+@var{name} can be omitted, which means the stab represents an unnamed
+object.  For example, @code{":t10=*2"} defines type 10 as a pointer to
+type 2, but does not give the type a name.  Omitting the @var{name}
+field is supported by AIX dbx and GDB after about version 4.8, but not
+other debuggers.
 
 The @var{symbol_descriptor} following the @samp{:} is an alphabetic
 character that tells more specifically what kind of symbol the stab
@@ -190,6 +196,9 @@ information follows, then the stab represents a local variable.  For a
 list of symbol_descriptors, see @ref{Symbol descriptors,,Table C: Symbol
 descriptors}.
 
+The @samp{c} symbol descriptor is an exception in that it is not
+followed by type information.  @xref{Constants}.
+
 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.
@@ -208,13 +217,36 @@ 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.
 
+There is an AIX extension for type attributes.  Following the @samp{=}
+is any number of type attributes.  Each one starts with @samp{@@} and
+ends with @samp{;}.  Debuggers, including AIX's dbx, skip any type
+attributes they do not recognize.  The attributes are:
+
+@table @code
+@item a@var{boundary}
+@var{boundary} is an integer specifying the alignment.  I assume that
+applies to all variables of this type.
+
+@item s@var{size}
+Size in bits of a variabe of this type.
+
+@item p@var{integer}
+Pointer class (for checking).  Not sure what this means, or how
+@var{integer} is interpreted.
+
+@item P
+Indicate this is a packed type, meaning that structure fields or array
+elements are placed more closely in memory, to save memory at the
+expense of speed.
+@end table
+
 All this can make the @code{"@var{string}"} field quite long.  All
 versions of GDB, and some versions of DBX, can handle arbitrarily long
 strings.  But many versions of DBX cretinously limit the strings to
 about 80 characters, so compilers which must work with such DBX's need
 to split the @code{.stabs} directive into several @code{.stabs}
 directives.  Each stab duplicates exactly all but the
-@code{"@var{string}"} field.  The @code{"@var{string}"} field of the
+@code{"@var{string}"} field.  The @code{"@var{string}"} field of 
 every stab except the last is marked as continued with a
 double-backslash at the end.  Removing the backslashes and concatenating
 the @code{"@var{string}"} fields of each stab produces the original,
@@ -365,24 +397,43 @@ address for the start of that source line.
 @node Procedures
 @section Procedures
 
-@table @strong
+All of the following stabs use the @samp{N_FUN} symbol type.
-@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
+A function is represented by a @samp{F} symbol descriptor for a global
-descriptor for a procedure is @samp{F} if the procedure is globally
+(extern) function, and @samp{f} for a static (local) function.  The next
-scoped and @samp{f} if the procedure is static (locally scoped).
+@samp{N_SLINE} symbol can be used to find the line number of the start
+of the function.  The value field is the address of the start of the
+function.  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.
 
-The @code{N_FUN} stab representing a procedure is located immediately
+The AIX documentation also defines symbol descriptor @samp{J} as an
-following the code of the procedure.  The @code{N_FUN} stab is in turn
+internal function.  I assume this means a function nested within another
-directly followed by a group of other stabs describing elements of the
+function.  It also says Symbol descriptor @samp{m} is a module in
-procedure.  These other stabs describe the procedure's parameters, its
+Modula-2 or extended Pascal.
-block local variables and its block structure. 
+
+Procedures (functions which do not return values) are represented as
+functions returning the void type in C.  I don't see why this couldn't
+be used for all languages (inventing a void type for this purpose if
+necessary), but the AIX documentation defines @samp{I}, @samp{P}, and
+@samp{Q} for internal, global, and static procedures, respectively.
+These symbol descriptors are unusual in that they are not followed by
+type information.
+
+After the symbol descriptor and the type information, there is
+optionally a comma, followed by the name of the procedure, followed by a
+comma, followed by a name specifying the scope.  The first name is local
+to the scope specified.  I assume then that the name of the symbol
+(before the @samp{:}), if specified, is some sort of global name.  I
+assume the name specifying the scope is the name of a function
+specifying that scope.  This feature is an AIX extension, and this
+information is based on the manual; I haven't actually tried it.
+
+The stab representing a procedure is located immediately following the
+code of the procedure.  This 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
@@ -455,6 +506,61 @@ represents the procedure itself.  The @code{N_LBRAC} uses the
 52 .stabn 224,0,0,LBE2
 @end example
 
+@node Constants
+@chapter Constants
+
+The @samp{c} symbol descriptor indicates that this stab represents a
+constant.  This symbol descriptor is an exception to the general rule
+that symbol descriptors are followed by type information.  Instead, it
+is followed by @samp{=} and one of the following:
+
+@table @code
+@item b@var{value}
+Boolean constant.  @var{value} is a numeric value; I assume it is 0 for
+false or 1 for true.
+
+@item c@var{value}
+Character constant.  @var{value} is the numeric value of the constant.
+
+@item e@var{type-information},@var{value}
+Enumeration constant.  @var{type-information} is the type of the
+constant, as it would appear after a symbol descriptor
+(@pxref{Overview}).  @var{value} is the numeric value of the constant.
+
+@item i@var{value}
+Integer constant.  @var{value} is the numeric value.
+
+@item r@var{value}
+Real constant.  @var{value} is the real value, which can be @samp{INF}
+(optionally preceded by a sign) for infinity, @samp{QNAN} for a quiet
+NaN (not-a-number), or @samp{SNAN} for a signalling NaN.  If it is a
+normal number the format is that accepted by the C library function
+@code{atof}.
+
+@item s@var{string}
+String constant.  @var{string} is a string enclosed in either @samp{'}
+(in which case @samp{'} characters within the string are represented as
+@samp{\'} or @samp{"} (in which case @samp{"} characters within the
+string are represented as @samp{\"}).
+
+@item S@var{type-information},@var{elements},@var{bits},@var{pattern}
+Set constant.  @var{type-information} is the type of the constant, as it
+would appear after a symbol descriptor (@pxref{Overview}).
+@var{elements} is the number of elements in the set (is this just the
+number of bits set in @var{pattern}?  Or redundant with the type?  I
+don't get it), @var{bits} is the number of bits in the constant (meaning
+it specifies the length of @var{pattern}, I think), and @var{pattern} is
+a hexadecimal representation of the set.  AIX documentation refers to a
+limit of 32 bytes, but I see no reason why this limit should exist.
+@end table
+
+The boolean, character, string, and set constants are not supported by
+GDB 4.9, but it will ignore them.  GDB 4.8 and earlier gave an error
+message and refused to read symbols from the file containing the
+constants.
+
+This information is followed by @samp{;}.
+
 @node Simple types
 @chapter Simple types
 
@@ -848,43 +954,27 @@ in the @code{N_GSYM} stab.  The debugger gets this information from the
 external symbol for the global variable.
 
 @node Register variables
-@section Global register variables 
+@section Register variables 
 
-@table @strong
+Register variables have their own stab type, @code{N_RSYM}, and their
-@item Directive:
+own symbol descriptor, @code{r}.  The stab's value field contains the
-@code{.stabs}
+number of the register where the variable data will be stored.
-@item Type:
-@code{N_RSYM}
-@item Symbol Descriptor:
-@code{r}
-@end table
 
-The following source line defines a global variable, @code{g_bar}, which is
+The value is the register number.
-explicitly allocated in global register @code{%g5}.  
+
+AIX defines a separate symbol descriptor @samp{d} for floating point
+registers.  This seems incredibly stupid--why not just just give
+floating point registers different register numbers.
+
+If the register is explicitly allocated to a global variable, but not
+initialized, as in
 
 @example
-2  register int g_bar asm ("%g5");
+register int g_bar asm ("%g5");
-@end example
-
-Register variables have their own stab type, @code{N_RSYM}, and their own
-symbol descriptor, @code{r}.  The stab's value field contains the number of
-the register where the variable data will be stored.  Since the
-variable was not initialized in this compilation unit, the stab is
-emited at the end of the object file, with the stabs for other
-uninitialized globals (@code{bcc}).
-
-@example
-@exdent @code{N_RSYM} (64): register variable
-
-.stabs "@var{name}:
-        @var{descriptor}
-        @var{type-ref}",
-       N_RSYM, NIL, NIL,
-       @var{register}
- 
-133 .stabs "g_bar:r1",64,0,0,5
 @end example
 
+the stab may be emitted at the end of the object file, with
+the other bss symbols.
 
 @node Initialized statics
 @section Initialized static variables 
@@ -1006,6 +1096,12 @@ same thing, the difference is that @samp{P} is a GNU invention and
 handle either one.  Symbol type @samp{C_RPSYM} is used with @samp{R} and
 @samp{N_RSYM} is used with @samp{P}.
 
+AIX, according to the documentation, uses @samp{D} for a parameter
+passed in a floating point register.  This strikes me as incredibly
+bogus---why doesn't it just use @samp{R} with a register number which
+indicates that it's a floating point register.  I haven't verified
+whether the system actually does what the documentation indicates.
+
 There is at least one case where GCC uses a @samp{p}/@samp{r} pair
 rather than @samp{P}; this is where the argument is passed in the
 argument list and then loaded into a register.
@@ -1017,9 +1113,12 @@ sparc, this is also true of a @samp{p}/@samp{r} pair (using Sun cc) or a
 register, @samp{r} is used.  And, to top it all off, on the hppa it
 might be a structure which was passed on the stack and loaded into a
 register and for which there is a @samp{p}/@samp{r} pair!  I believe
-that symbol descriptor @samp{i} is supposed to deal with this case, but
+that symbol descriptor @samp{i} is supposed to deal with this case, (it
-I don't know details or what compilers or debuggers use it, if any (not
+is said to mean "value parameter by reference, indirect access", I don't
-GDB or GCC).
+know the source for this information) but I don't know details or what
+compilers or debuggers use it, if any (not GDB or GCC).  It is not clear
+to me whether this case needs to be dealt with differently than
+parameters passed by reference (see below).
 
 There is another case similar to an argument in a register, which is an
 argument which is actually stored as a local variable.  Sometimes this
@@ -1038,15 +1137,30 @@ symbol is an offset relative to the local variables for that function,
 not relative to the arguments (on some machines those are the same
 thing, but not on all).
 
-The following are said to go with @samp{N_PSYM}:
+If the parameter is passed by reference (e.g. Pascal VAR parameters),
+then type 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 other 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.
+
+@c Is this paragraph correct?  It is based on piecing together patchy
+@c information and some guesswork
+Conformant arrays refer to 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.
+
+The following are also said to go with @samp{N_PSYM}:
 
 @example
 "name" -> "param_name:#type"
-                     # -> p  (value parameter)
-                       -> i  (value parameter by reference, indirect access)
-                       -> v  (variable parameter by reference)
-                       -> C  (read-only parameter, conformant array bound)
-                       -> x  (conformant array value parameter)
                        -> pP (<<??>>)
                        -> pF (<<??>>)
                        -> X  (function result variable)
@@ -2464,11 +2578,23 @@ n_type  n_type  name      used to describe
 @item (empty)
 Local variable, @xref{Automatic variables}.
 
+@item a
+Parameter passed by reference in register, @xref{Parameters}.
+
+@item c
+Constant, @xref{Constants}.
+
 @item C
-@xref{Parameters}.
+Conformant array bound, @xref{Parameters}.
+
+@item d
+Floating point register variable, @xref{Register variables}.
+
+@item D
+Parameter in floating point register, @xref{Parameters}.
 
 @item f
-Local function, @xref{Procedures}.
+Static function, @xref{Procedures}.
 
 @item F
 Global function, @xref{Procedures}.
@@ -2479,6 +2605,18 @@ Global variable, @xref{Global Variables}.
 @item i
 @xref{Parameters}.
 
+@item I
+Internal (nested) procedure, @xref{Procedures}.
+
+@item J
+Internal (nested) function, @xref{Procedures}.
+
+@item L
+Label name (documented by AIX, no further information known).
+
+@item m
+Module, @xref{Procedures}.
+
 @item p
 Argument list parameter @xref{Parameters}.
 
@@ -2489,7 +2627,13 @@ Argument list parameter @xref{Parameters}.
 @xref{Parameters}.
 
 @item P
-@itemx R
+Global Procedure (AIX), @xref{Procedures}.
+Register parameter (GNU), @xref{Parameters}.
+
+@item Q
+Static Procedure, @xref{Procedures}.
+
+@item R
 Register parameter @xref{Parameters}.
 
 @item r
@@ -2512,6 +2656,9 @@ Call by reference, @xref{Parameters}.
 Static procedure scope variable @xref{Initialized statics},
 @xref{Un-initialized statics}.
 
+@item x
+Conformant array, @xref{Parameters}.
+
 @item X
 Function return variable, @xref{Parameters}.
 @end table
@@ -2519,19 +2666,36 @@ Function return variable, @xref{Parameters}.
 @node Type Descriptors
 @section Table D: Type Descriptors 
 
-@example
+@table @code
-descriptor      meaning                         
+@item (digits)
--------------------------------------
+Type reference, @xref{Overview}.
-(empty)         type reference                  
-   a            array type                      
-   e            enumeration type                
-   f            function type                   
-   r            range type                      
-   s            structure type          
-   u            union specifications            
-   *            pointer type                    
-@end example
 
+@item *
+Pointer type.
+
+@item @@
+Type Attributes (AIX), @xref{Overview}.
+Some C++ thing (GNU).
+
+@item a
+Array type.
+
+@item e
+Enumeration type.
+
+@item f
+Function type.
+
+@item r
+Range type.
+
+@item s
+Structure type.
+
+@item u
+Union specifications.
+
+@end table
 
 @node Expanded reference
 @appendix Expanded reference by stab type.
@@ -2625,12 +2789,9 @@ obtained from the corresponding extern symbol.
 
 @node N_FUN
 @section 36 - 0x24 - N_FUN
-Function name or text segment variable for C.
-
-@display
-.stabs "name", N_FUN, NIL, desc, value
-@end display
 
+Function name (@pxref{Procedures}) or text segment variable
+(@pxref{Variables}).
 @example
 @exdent @emph{For functions:}
 "name" -> "proc_name:#return_type"
@@ -3082,6 +3243,9 @@ dbx?
 @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.
+@c Progress report: I have merged all the information from the
+@c "dbx stabstring grammar" section of the AIX documentation into
+@c the main body of this document, except the types.
 (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.