rdwarf 0.0.1

data/ext/rdwarf/libdwarf/mips_extensions.mm

@@ -0,0 +1,1266 @@
+\."
+\." the following line may be removed if the ff ligature works on your machine
+.lg 0
+\." set up heading formats
+.ds HF 3 3 3 3 3 2 2
+.ds HP +2 +2 +1 +0 +0
+.nr Hs 5
+.nr Hb 5
+\." ==============================================
+\." Put current date in the following at each rev
+.ds vE rev 1.18, 31 March 2005
+\." ==============================================
+\." ==============================================
+.ds | |
+.ds ~ ~
+.ds ' '
+.if t .ds Cw \&\f(CW
+.if n .ds Cw \fB
+.de Cf          \" Place every other arg in Cw font, beginning with first
+.if \\n(.$=1 \&\*(Cw\\$1\fP
+.if \\n(.$=2 \&\*(Cw\\$1\fP\\$2
+.if \\n(.$=3 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP
+.if \\n(.$=4 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4
+.if \\n(.$=5 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP
+.if \\n(.$=6 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6
+.if \\n(.$=7 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP
+.if \\n(.$=8 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8
+.if \\n(.$=9 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8\
+*(Cw
+..
+.nr Cl 4
+.SA 1
+.TL
+MIPS Extensions to DWARF Version 2.0
+.AF ""
+.AU "Silicon Graphics Computer Systems"
+.PF "'\*(vE'- \\\\nP -''"
+.AS 1
+This document describes the MIPS/Silicon Graphics extensions 
+to the "DWARF Information Format" (version 2.0.0 dated July 27, 1993).
+DWARF3 draft 8 (or draft 9) is out as of 2005, and
+is mentioned below where applicable.
+MIPS/IRIX compilers emit DWARF2 (with extensions).
+.P
+Rather than alter the base documents to describe the extensions
+we provide this separate document.
+.P
+The extensions documented here are subject to change.
+.P
+It also describes known bugs resulting in incorrect dwarf usage.
+.P
+\*(vE
+
+.AE
+.MT 4
+
+.H 1 "INTRODUCTION"
+.P
+This 
+document describes MIPS extensions 
+to the DWARF debugging information format.  
+The extensions documented here are subject to change at
+any time.
+.H 1 "64 BIT DWARF"
+.P
+The DWARF2 spec has no provision for 64 bit offsets.
+SGI-IRIX/MIPS Elf64 objects contain DWARF 2 with all offsets
+(and addresses) as 64bit values.  
+This non-standard extension was adopted in 1992.
+Nothing in the dwarf itself identifies the dwarf as 64bit.
+This extension 64bit-offset dwarf cannot be mixed with 32bit-offset dwarf
+in a single object or executable, and SGI-IRIX/MIPS compilers
+and tools do not mix the sizes.
+.P
+In 2001 DWARF3 adopted a very different 64bit-offset
+format which can be mixed usefully with 32bit-offset DWARF2 or DWARF3.
+It is not very likely SGI-IRIX/MIPS compilers will switch to the 
+now-standard
+DWARF3 64bit-offset scheme, but such a switch is theoretically
+possible and would be a good idea.
+.P
+SGI-IRIX/MIPS Elf32 objects
+contain DWARF2 with all offsets (and addresses) 32 bits.
+.H 1 "How much symbol information is emitted"
+The following standard DWARF V2 sections may be emitted:
+.AL
+.LI 
+Section .debug_abbrev
+contains
+abbreviations supporting the .debug_info section.
+.LI
+Section .debug_info
+contains
+Debug Information Entries (DIEs).
+.LI 
+Section .debug_frame
+contains
+stack frame descriptions.
+.LI 
+Section .debug_line
+contains
+line number information.
+.LI 
+Section .debug_aranges
+contains
+address range descriptions.
+.LI 
+Section .debug_pubnames
+contains
+names of global functions and data.
+.P
+The following
+are MIPS extensions.
+Theses were created to allow debuggers to
+know names without having to look at
+the .debug_info section.
+.LI 
+Section .debug_weaknames
+is a MIPS extension
+containing .debug_pubnames-like entries describing weak
+symbols.
+.LI 
+Section .debug_funcnames
+is a MIPS extension
+containing .debug_pubnames-like entries describing file-static
+functions (C static functions).
+The gcc extension of nested subprograms (like Pascal)
+adds non-global non-static functions.  These should be treated like
+static functions and gcc should add such to this section
+so that IRIX libexc(3C) will work correctly.
+Similarly, Ada functions which are non-global should be here too
+so that libexc(3C) can work.
+Putting it another way, every function (other than inline code)
+belongs either in .debug_pubnames or in .debug_funcnames
+or else libexc(3C) cannot find the function name.
+.LI 
+Section .debug_varnames
+is a MIPS extension
+containing .debug_pubnames-like entries describing file-static
+data symbols (C static variables).
+.LI 
+Section .debug_typenames
+is a MIPS extension
+containing .debug_pubnames-like entries describing file-level
+types.
+.P
+The following are not currently emitted.
+.LI 
+Section .debug_macinfo
+Macro information is not currently emitted.
+.LI 
+Section .debug_loc
+Location lists are not currently emitted.
+.LI
+Section .debug_str
+The string section is not currently emitted.
+.LE
+.H 2 "Overview of information emitted"
+We emit debug information in 3 flavors.
+We mention C here.
+The situation is essentially identical for f77, f90, and C++.
+.AL
+.LI 
+"default C"
+We emit line information and DIEs for each subprogram.
+But no local symbols and no type information.
+Frame information is output.
+The DW_AT_producer string has the optimization level: for example
+"-O2".
+We put so much in the DW_AT_producer that the string
+is a significant user of space in .debug_info --
+this is perhaps a poor use of space.
+When optimizing the IRIX CC/cc option -DEBUG:optimize_space
+eliminates such wasted space.
+Debuggers only currently use the lack of -g
+of DW_AT_producer
+as a hint as to how a 'step' command should be interpreted, and
+the rest of the string is not used for anything (unless
+a human looks at it for some reason), so if space-on-disk
+is an issue, it is quite appropriate to use -DEBUG:optimize_space
+and save disk space.
+Every function definition (not inline instances though) is mentioned
+in either .debug_pubnames or .debug_funcnames.
+This is crucial to allow libexc(3C) stack-traceback to work and
+show function names (for all languages).
+.LI 
+"C with full symbols"
+All possible info is emitted.
+DW_AT_producer string has all options that might be of interest,
+which includes -D's, -U's, and the -g option.
+These options look like they came from the command line.
+We put so much in the DW_AT_producer that the string
+is a significant user of space in .debug_info.
+this is perhaps a poor use of space.
+Debuggers only currently use the -g
+of DW_AT_producer
+as a hint as to how a 'step' command should be interpreted, and
+the rest of the string is not used for anything (unless
+a human looks at it for some reason).
+Every function definition (not inline instances though) is mentioned
+in either .debug_pubnames or .debug_funcnames.
+This is crucial to allow libexc(3C) stack-traceback to work and
+show function names (for all languages).
+.LI 
+"Assembler (-g, non -g are the same)"
+Frame information is output.
+No type information is emitted, but DIEs are prepared
+for globals.
+.LE
+.H 2 "Detecting 'full symbols' (-g)"
+The debugger depends on the existence of
+the DW_AT_producer string to determine if the
+compilation unit has full symbols or not.
+It looks for -g or -g[123] and accepts these as
+full symbols but an absent -g or a present -g0 
+is taken to mean that only basic symbols are defined and there
+are no local symbols and no type information.
+.P
+In various contexts the debugger will think the program  is
+stripped or 'was not compiled with -g' unless the -g
+is in the DW_AT_producer string.
+.H 2 "DWARF and strip(1)"
+The DWARF section ".debug_frame" is marked SHF_MIPS_NOSTRIP
+and is not stripped by the strip(1) program.
+This is because the section is needed for doing
+stack back traces (essential for C++
+and Ada exception handling).
+.P
+All .debug_* sections are marked with elf type
+SHT_MIPS_DWARF.
+Applications needing to access the various DWARF sections
+must use the section name to discriminate between them. 
+
+.H 2 "Evaluating location expressions"
+When the debugger evaluates location expressions, it does so
+in 2 stages. In stage one it simply looks for the trivial
+location expressions and treats those as special cases.
+.P
+If the location expression is not trivial, it enters stage two.
+In this case it uses a stack to evaluate the expression.
+.P
+If the application is a 32-bit application, it does the operations
+on 32-bit values (address size values).  Even though registers
+can be 64 bits in a 32-bit program all evaluations are done in 
+32-bit quantities, so an attempt to calculate a 32-bit quantity
+by taking the difference of 2 64-bit register values will not
+work.  The notion is that the stack machine is, by the dwarf
+definition, working in address size units.
+.P
+These values are then expanded to 64-bit values (addresses or
+offsets).   This extension does not involve sign-extension.
+.P
+If the application is a 64-bit application, then the stack
+values are all 64 bits and all operations are done on 64 bits.
+.H 3 "The fbreg location op"
+Compilers shipped with IRIX 6.0 and 6.1
+do not emit the fbreg location expression
+and never emit the DW_AT_frame_base attribute that it
+depends on. 
+However, this changes
+with release 6.2 and these are now emitted routinely.
+
+.H 1 "Frame Information"
+.H 2 "Initial Instructions"
+The DWARF V2 spec 
+provides for "initial instructions" in each CIE (page 61,
+section 6.4.1).
+However, it does not say whether there are default
+values for each column (register).
+.P
+Rather than force every CIE to have a long list
+of bytes to initialize all 32 integer registers,
+we define that the default values of all registers
+(as returned by libdwarf in the frame interface)
+are 'same value'.
+This is a good choice for many non-register-windows
+implementations.
+.H 2 "Augmentation string in debug_frame"
+The augmentation string we use in shipped compilers (up thru
+irix6.2) is the empty string.
+IRIX6.2 and later has an augmentation string 
+the empty string ("")
+or "z" or "mti v1" 
+where the "v1" is a version number (version 1).
+.P
+We do not believe that "mti v1" was emitted  as the
+augmentation string in any shipped compiler.
+.P
+.H 3 "CIE processing based on augmentation string:"
+If the augmentation string begins with 'z', then it is followed
+immediately by a unsigned_leb_128 number giving the code alignment factor.
+Next is a signed_leb_128 number giving the data alignment factor.
+Next is a unsigned byte giving the number of the return address register.
+Next is an unsigned_leb_128 number giving the length of the 'augmentation'
+fields  (the length of augmentation bytes, not
+including the unsigned_leb_128 length itself).
+As of release 6.2, the length of the CIE augmentation fields is 0.
+What this means is that it is possible to add new
+augmentations, z1, z2, etc and yet an old consumer to
+understand the entire CIE as it can bypass the
+augmentation it does not understand because the
+length of the augmentation fields is present.
+Presuming of course that all augmentation fields are
+simply additional information, 
+not some 'changing of the meaning of 
+an existing field'.
+Currently there is no CIE data in the augmentation for things
+beginning with 'z'.
+.P
+If the augmentation string is "mti v1" or "" then it is followed
+immediately by a unsigned_leb_128 number giving the code alignment factor.
+Next is a signed_leb_128 number giving the data alignment factor.
+Next is a unsigned byte giving the number of the return address register.
+.P
+If the augmentation string is something else, then the
+code alignment factor is assumed to be 4 and the data alignment
+factor is assumed to be -1 and the return
+address register is assumed to be 31. Arbitrarily.
+The library (libdwarf) assumes it does not understand the rest of the CIE.
+.P
+.H 3 "FDE processing based on augmentation"
+If the CIE augmentation string 
+for an fde begins with 'z'
+then the next FDE field after the address_range field
+is an 
+unsigned_leb_128 number giving the length of the 'augmentation'
+fields, and those fields follow immediately.
+
+.H 4 "FDE augmentation fields"
+.P
+If the CIE augmentation string is "mti v1" or ""
+then the FDE is exactly as described in the Dwarf Document section 6.4.1.
+.P
+Else, if the CIE augmentation string begins with "z"
+then the next field after the FDE augmentation length field
+is a Dwarf_Sword size offset into
+exception tables.
+If the CIE augmentation string does not begin with "z"
+(and is neither "mti v1" nor "")
+the FDE augmentation fields are skipped (not understood).
+Note that libdwarf actually (as of MIPSpro7.3 and earlier)
+only tests that the initial character of the augmentation
+string is 'z', and ignores the rest of the string, if any.
+So in reality the test is for a _prefix_ of 'z'.
+.P
+If the CIE augmentation string neither starts with 'z' nor is ""
+nor is "mti v1" then libdwarf (incorrectly) assumes that the
+table defining instructions start next.  
+Processing (in libdwarf) will be incorrect.
+.H 2 "Stack Pointer recovery from debug_frame"
+There is no identifiable means in
+DWARF2 to say that the stack register is
+recovered by any particular operation.
+A 'register rule' works if the caller's
+stack pointer was copied to another
+register.
+An 'offset(N)' rule works if the caller's
+stack pointer was stored on the stack.
+However if the stack pointer is
+some register value plus/minus some offset,
+there is no means to say this in an FDE.
+For MIPS/IRIX, the recovered stack pointer
+of the next frame up the stack (towards main())
+is simply the CFA value of the current
+frame, and the CFA value is
+precisely a register (value of a register)
+or a register plus offset (value of a register
+plus offset).  This is a software convention.
+.H 1 "egcs dwarf extensions (egcs-1.1.2 extensions)"
+This and following egcs sections describe
+the extensions currently shown in egcs dwarf2.
+Note that egcs has chosen to adopt tag and
+attribute naming as if their choices were
+standard dwarf, not as if they were extensions.
+However, they are properly numbered as extensions.
+
+.H 2 "DW_TAG_format_label             0x4101" 
+For FORTRAN 77, Fortran 90.
+Details of use not defined in egcs source, so
+unclear if used.
+.H 2 "DW_TAG_function_template        0x4102"
+For C++.
+Details of use not defined in egcs source, so
+unclear if used.
+.H 2 "DW_TAG_class_template           0x4103" 
+For C++.
+Details of use not defined in egcs source, so
+unclear if used.
+.H 2 "DW_AT_sf_names                          0x2101"
+Apparently only output in DWARF1, not DWARF2.
+.H 2 "DW_AT_src_info                          0x2102"
+Apparently only output in DWARF1, not DWARF2.
+.H 2 "DW_AT_mac_info                          0x2103"
+Apparently only output in DWARF1, not DWARF2.
+.H 2 "DW_AT_src_coords                        0x2104"
+Apparently only output in DWARF1, not DWARF2.
+.H 2 "DW_AT_body_begin                        0x2105"
+Apparently only output in DWARF1, not DWARF2.
+.H 2 "DW_AT_body_end                          0x2106"
+Apparently only output in DWARF1, not DWARF2.
+
+.H 1 "egcs .eh_frame (non-sgi) (egcs-1.1.2 extensions)"
+egcs-1.1.2 (and earlier egcs)
+emits by default a section named .eh_frame 
+for ia32 (and possibly other platforms) which
+is nearly identical to .debug_frame in format and content.
+This section is used for helping handle C++ exceptions.
+.P
+Because after linking there are sometimes zero-ed out bytes
+at the end of the eh_frame section, the reader code in
+dwarf_frame.c considers a zero cie/fde length as an indication
+that it is the end of the section.
+.P
+.H 2 "CIE_id 0"
+The section is an ALLOCATED section in an executable, and
+is therefore mapped into memory at run time.
+The CIE_pointer (aka CIE_id, section 6.4.1
+of the DWARF2 document) is the field that 
+distinguishes a CIE from an FDE.
+The designers of the egcs .eh_frame section
+decided to make the CIE_id
+be 0 as the CIE_pointer definition is
+.in +2
+the number of bytes from the CIE-pointer in the FDE back to the
+applicable CIE.
+.in -2
+In a dwarf .debug_frame section, the CIE_pointer is the
+offset in .debug_frame of the CIE for this fde, and
+since an offset can be zero of some CIE, the CIE_id
+cannot be 0, but must be all 1 bits .
+Note that the dwarf2.0 spec does specify the value of CIE_id
+as 0xffffffff
+(see section 7.23 of v2.0.0),
+though earlier versions of this extensions document
+incorrectly said it was not specified in the dwarf
+document.
+.H 2 "augmentation eh"
+The augmentation string in each CIE is "eh"
+which, with its following NUL character, aligns
+the following word to a 32bit boundary.
+Following the augmentation string is a 32bit
+word with the address of the __EXCEPTION_TABLE__,
+part of the exception handling data for egcs.
+.H 2 "DW_CFA_GNU_window_save   0x2d"
+This is effectively a flag for architectures with
+register windows, and tells the unwinder code that
+it must look to a previous frame for the
+correct register window set.
+As of this writing, egcs  gcc/frame.c
+indicates this is for SPARC register windows.
+.H 2 "DW_CFA_GNU_args_size     0x2e"
+DW_CFA_GNU_args_size has a single uleb128 argument
+which is the size, in bytes, of the function's stack
+at that point in the function.
+.H 2 "__EXCEPTION_TABLE__"
+A series of 3 32bit word entries by default:
+0 word: low pc address
+1 word: high pc address
+2 word: pointer to exception handler code
+The end of the table is 
+signaled by 2 words  of -1 (not 3 words!).
+.H 1 "Interpretations of the DWARF V2 spec"
+.H 2 "template TAG spellings"
+The DWARF V2 spec spells two attributes in two ways.
+DW_TAG_template_type_param 
+(listed in Figure 1, page 7)
+is spelled DW_TAG_template_type_parameter
+in the body of the document (section 3.3.7, page 28).
+We have adopted the spelling 
+DW_TAG_template_type_param.
+.P
+DW_TAG_template_value_param
+(listed in Figure 1, page 7)
+is spelled DW_TAG_template_value_parameter
+in the body of the document (section 3.3.7, page 28).
+We have adopted the spelling 
+DW_TAG_template_value_parameter.
+.P
+We recognize that the choices adopted are neither consistently
+the longer nor the shorter name.
+This inconsistency was an accident.
+.H 2 DW_FORM_ref_addr confusing
+Section 7.5.4, Attribute Encodings, describes
+DW_FORM_ref_addr.
+The description says the reference is the size of an address
+on the target architecture.
+This is surely a mistake, because on a 16bit-pointer-architecture
+it would mean that the reference could not exceed
+16 bits, which makes only
+a limited amount of  sense as the reference is from one
+part of the dwarf to another, and could (in theory)
+be *on the disk* and not limited to what fits in memory.
+Since MIPS is 32 bit pointers (at the smallest) 
+the restriction is not a problem for MIPS/SGI.
+The 32bit pointer ABIs are limited to 32 bit section sizes
+anyway (as a result of implementation details).
+And the 64bit pointer ABIs currently have the same limit
+as a result of how the compilers and tools are built
+(this has not proven to be a limit in practice, so far).
+.P
+This has been clarified in the DWARF3 spec and the IRIX use
+of DW_FORM_ref_addr being an offset is correct.
+.H 2 "Section .debug_macinfo in a debugger"
+It seems quite difficult, in general, to
+tie specific text(code) addresses to points in the
+stream of macro information for a particular compilation unit.
+So it's been difficult to see how to design a consumer
+interface to libdwarf for macro information.
+.P
+The best (simple to implement, easy for a debugger user to
+understand) candidate seems to be that
+the debugger asks for macros of a given name in a compilation
+unit, and the debugger responds with *all* the macros of that name.
+.H 3 "only a single choice exists"
+If there is exactly one, that is usable in expressions, if the
+debugger is able to evaluate such.
+.H 3 "multiple macros with same name".
+If there are multiple macros with the same name
+in a compilation unit, 
+the debugger (and the debugger user and the application
+programmer) have
+a problem: confusion is quite possible.
+If the macros are simple the
+debugger  user can simply substitute by hand in an expression.
+If the macros are complicated hand substitution will be
+impractical, and the debugger will have to identify the
+choices and let the debugger user choose an interpretation.
+.H 2 "Section 6.1.2 Lookup by address problem"
+Each entry is a beginning-address followed by a length.
+And the distinguished entry 0,0 is used to denote
+the end of a range of entries.
+.P
+This means that one must be careful not to emit a zero length,
+as in a .o (object file) the beginning address of
+a normal entry might be 0 (it is a section offset after all),
+and the resulting 0,0 would be taken as end-of-range, not
+as a valid entry.
+A dwarf dumper would have trouble with such data
+in an object file.
+.P
+In an a.out or shared object (dynamic shared object, DSO)
+no text will be at address zero so in such this problem does
+not arise.
+.H 2 "Section 5.10 Subrange Type Entries problem"
+It is specified that  DW_AT_upper_bound (and lower bound)
+must be signed entries if there is no object type
+info to specify the bound type (Sec 5.10, end of section). 
+One cannot tell (with some
+dwarf constant types) what the signedness is from the
+form itself (like DW_FORM_data1), so it is necessary
+to determine the object and type according to the rules 
+in 5.10 and then if all that fails, the type is signed.
+It's a bit complicated and earlier versions of  mips_extensions
+incorrectly said signedness was not defined.
+.H 2 "Section 5.5.6 Class Template Instantiations problem"
+Lots of room for implementor to canonicalize
+template declarations.  Ie various folks won't agree.
+This is not serious since a given compiler
+will be consistent with itself and  debuggers
+will have to cope!
+.H 2 "Section 2.4.3.4  # 11. operator spelling"  
+DW_OP_add should be DW_OP_plus (page 14)
+(this mistake just one place on the page).
+.H 2 "No clear specification of C++ static funcs"
+There is no clear way to tell if a C++ member function
+is a static member or a non-static member function.
+(dwarf2read.c in gdb 4.18, for example, has this observation)
+.H 2 "Misspelling of DW_AT_const_value"
+Twice in appendix 1, DW_AT_const_value is misspelled
+as DW_AT_constant_value.
+.H 2 "Mistake in Atribute Encodings"
+Section 7.5.4, "Attribute Encodings"
+has a brief discussion of "constant"
+which says there are 6 forms of constants.
+It is incorrect in that it fails to mention (or count)
+the block forms, which are clearly allowed by
+section 4.1 "Data Object Entries" (see entry number 9 in
+the numbered list, on constants).
+.H 2 "DW_OP_bregx"
+The description of DW_OP_bregx in 2.4.3.2 (Register Based
+Addressing) is slightly misleading, in that it
+lists the offset first.
+As section 7.7.1 (Location Expression)
+makes clear, in the encoding the register number
+comes first.
+.H 1 "MIPS attributes"
+.H 2 "DW_AT_MIPS_fde"
+This extension to Dwarf appears only on subprogram TAGs and has as
+its value the offset, in the .debug_frame section, of the fde which
+describes the frame of this function.  It is an optimization of
+sorts to have this present.
+
+.H 2 "DW_CFA_MIPS_advance_loc8 0x1d"
+This obvious extension to dwarf line tables enables encoding of 8 byte
+advance_loc values (for cases when such must be relocatable, 
+and thus must be full length).  Applicable only to 64-bit objects.
+
+.H 2 "DW_TAG_MIPS_loop        0x4081"
+For future use. Not currently emitted.
+Places to be emitted and attributes that this might own
+not finalized.
+
+.H 2 "DW_AT_MIPS_loop_begin   0x2002"
+For future use. Not currently emitted.
+Attribute form and content not finalized.
+
+.H 2 "DW_AT_MIPS_tail_loop_begin  0x2003"
+For future use. Not currently emitted.
+Attribute form and content not finalized.
+
+.H 2 "DW_AT_MIPS_epilog_begin     0x2004"
+For future use. Not currently emitted.
+Attribute form and content not finalized.
+
+.H 2 "DW_AT_MIPS_loop_unroll_factor  0x2005"
+For future use. Not currently emitted.
+Attribute form and content not finalized.
+
+.H 2 "DW_AT_MIPS_software_pipeline_depth   0x2006"
+For future use. Not currently emitted.
+Attribute form and content not finalized.
+.H 2 "DW_AT_MIPS_linkage_name                 0x2007"
+The rules for mangling C++ names are not part of the
+C++ standard and are different for different versions
+of C++.  With this extension, the compiler emits
+both the DW_AT_name for things with mangled names 
+(recall that DW_AT_name is NOT the mangled form)
+and also emits DW_AT_MIPS_linkage_name whose value
+is the mangled name.
+.P
+This makes looking for the mangled name in other linker
+information straightforward.
+It also is passed (by the debugger) to the
+libmangle routines to generate names to present to the
+debugger user.
+.H 2 "DW_AT_MIPS_stride            0x2008"
+F90 allows assumed shape arguments and pointers to describe
+non-contiguous memory. A (runtime) descriptor contains address,
+bounds and stride information - rank and element size is known
+during compilation. The extent in each dimension is given by the
+bounds in a DW_TAG_subrange_type, but the stride cannot be
+represented in conventional dwarf. DW_AT_MIPS_stride was added as
+an attribute of a DW_TAG_subrange_type to describe the
+location of the stride.
+Used in the MIPSpro 7.2 (7.2.1 etc) compilers.
+.P
+If the stride is constant (ie: can be inferred from the type in the
+usual manner) DW_AT_MIPS_stride is absent. 
+.P
+If DW_AT_MIPS_stride is present, the attribute contains a reference
+to a DIE which describes the location holding the stride, and the
+DW_AT_stride_size field of DW_TAG_array_type is ignored if
+present.  The value of the stride is the number of 
+4 byte words between
+elements along that axis.
+.P
+This applies to 
+.nf
+a) Intrinsic types whose size is greater 
+   or equal to 4bytes ie: real*4,integer*8 
+   complex etc, but not character types.
+
+b) Derived types (ie: structs) of any size, 
+   unless all components are of type character.
+.fi
+
+.H 2 "DW_AT_MIPS_abstract_name              0x2009"
+This attribute only appears in a DA_TAG_inlined_subroutine DIE.
+The value of this attribute is a string.
+When IPA inlines a routine and the abstract origin is
+in another compilation unit, there is a problem with putting
+in a reference, since the ordering and timing of the 
+creation of references is unpredicatable with reference to
+the DIE and compilation unit the reference refers to. 
+.P
+Since there may be NO ordering of the compilation units that
+allows a correct reference to be done without some kind of patching,
+and since even getting the information from one place to another
+is a problem, the compiler simply passes the problem on to the debugger.
+.P
+The debugger must match the DW_AT_MIPS_abstract_name 
+in the concrete
+inlined instance DIE 
+with the  DW_AT_MIPS_abstract_name
+in the abstract inlined subroutine DIE.
+.P
+A dwarf-consumer-centric view of this  and other inline
+issues could be expressed as follows:
+.nf
+If DW_TAG_subprogram
+  If has DW_AT_inline is abstract instance root
+  If has DW_AT_abstract_origin, is out-of-line instance
+    of function (need abstract origin for some data)
+    (abstract root in same CU (conceptually anywhere
+    a ref can reach, but reaching outside of CU is
+    a problem for ipa: see DW_AT_MIPS_abstract_name))
+  If has DW_AT_MIPS_abstract_name is abstract instance
+    root( must have DW_AT_inline) and this name is used to
+    match with the abstract root
+
+If DW_TAG_inline_subroutine
+  Is concrete inlined subprogram instance.
+  If has DW_AT_abstract_origin, it is a CU-local inline.
+  If it has DW_AT_MIPS_abstract_name it is an
+    inline whose abstract root is in another file (CU).
+.fi
+
+.H 2 "DW_AT_MIPS_clone_origin               0x200a"
+This attribute appears only in a cloned subroutine.
+The procedure is cloned from the same compilation unit.
+The value of this attribute is a reference to 
+the original routine in this compilation unit.
+.P
+The 'original' routine means the routine which has all the
+original code.  The cloned routines will always have
+been 'specialized' by IPA.   
+A routine with DW_AT_MIPS_clone_origin
+will also have the DW_CC_nocall value of the DW_AT_calling_convention
+attribute.
+
+.H 2 "DW_AT_MIPS_has_inlines               0x200b"
+This attribute  may appear in a DW_TAG_subprogram DIE.
+If present and it has the value True, then the subprogram
+has inlined functions somewhere in the body.
+.P
+By default, at startup, the debugger may not look for 
+inlined functions in scopes inside the outer function.
+.P
+This is a hint to the debugger to look for the inlined functions
+so the debugger can set breakpoints on these in case the user
+requests 'stop in foo' and foo is inlined.
+.H 2 "DW_AT_MIPS_stride_byte                  0x200c"
+Created for f90 pointer and assumed shape
+arrays.
+Used in the MIPSpro 7.2 (7.2.1 etc) compilers.
+A variant of DW_AT_MIPS_stride. 
+This stride is interpreted as a byte count. 
+Used for integer*1 and character arrays
+and arrays of derived type
+whose components are all character.
+.H 2 "DW_AT_MIPS_stride_elem                  0x200d"
+Created for f90 pointer and assumed shape
+arrays.
+Used in the MIPSpro 7.2 (7.2.1 etc) compilers.
+A variant of DW_AT_MIPS_stride. 
+This stride is interpreted as a byte-pair (2 byte) count. 
+Used for integer*2 arrays.
+.H 2 "DW_AT_MIPS_ptr_dopetype                 0x200e"
+See following.
+.H 2 "DW_AT_MIPS_allocatable_dopetype         0x200f"
+See following.
+.H 2 "DW_AT_MIPS_assumed_shape_dopetype       0x2010"
+DW_AT_MIPS_assumed_shape_dopetype, DW_AT_MIPS_allocatable_dopetype,
+and DW_AT_MIPS_ptr_dopetype have an attribute value
+which is a reference to a Fortran 90 Dope Vector.
+These attributes are introduced in MIPSpro7.3.
+They only apply to f90 arrays (where they are
+needed to describe arrays never properly described
+before in debug information).
+C, C++, f77, and most f90 arrays continue to be described
+in standard dwarf.
+.P
+The distinction between these three attributes is the f90 syntax
+distinction: keywords 'pointer' and 'allocatable' with the absence
+of these keywords on an assumed shape array being the third case.
+.P
+A "Dope Vector" is a struct (C struct) which describes
+a dynamically-allocatable array.
+In objects with full debugging the C struct will be
+in the dwarf information (of the f90 object, represented like C).
+A debugger will use the link to find the main struct DopeVector
+and will use that information to decode the dope vector.
+At the outer allocatable/assumed-shape/pointer
+the DW_AT_location points at the dope vector (so debugger
+calculations use that as a base).
+.H 2 "Overview of debugger use of dope vectors"
+Fundamentally, we build two distinct
+representations of the arrays and pointers.
+One, in dwarf, represents the statically-representable
+information (the types and
+variable/type-names, without type size information).
+The other, using dope vectors in memory, represents
+the run-time data of sizes.
+A debugger must process the two representations
+in parallel (and merge them) to deal with  user expressions in
+a debugger.
+.H 2 "Example f90 code for use in explanation"
+[Note
+We want dwarf output with *exactly* 
+this little (arbitrary) example.
+Not yet available.
+end Note]
+Consider the following code.
+.nf
+       type array_ptr
+	  real   :: myvar
+          real, dimension (:), pointer :: ap
+       end type array_ptr
+
+       type (array_ptr), allocatable, dimension (:) :: arrays
+
+       allocate (arrays(20))
+       do i = 1,20
+          allocate (arrays(i)%ap(i))
+       end do
+.fi
+arrays is an allocatable array (1 dimension) whose size is
+not known at compile time (it has
+a Dope Vector).  At run time, the
+allocate statement creats 20 array_ptr dope vectors
+and marks the base arrays dopevector as allocated.
+The myvar variable is just there to add complexity to
+the example :-)
+.nf
+In the loop, arrays(1)%ap(1) 
+    is allocated as a single element array of reals.
+In the loop, arrays(2)%ap(2) 
+    is allocated as an array of two reals.
+...
+In the loop, arrays(20)%ap(20) 
+    is allocated as an array of twenty reals.
+.fi
+.H 2 "the problem with standard dwarf and this example"
+.sp
+In dwarf, there is no way to find the array bounds of arrays(3)%ap,
+for example, (which are 1:3 in f90 syntax)
+since any location expression in an ap array lower bound
+attribute cannot involve the 3 (the 3 is known at debug time and
+does not appear in the running binary, so no way for the
+location expression to get to it).
+And of course the 3 must actually index across the array of
+dope vectors in 'arrays' in our implementation, but that is less of
+a problem than the problem with the '3'.
+.sp
+Plus dwarf has no way to find the 'allocated' flag in the
+dope vector (so the debugger can know when the allocate is done
+for a particular arrays(j)%ap).
+.sp
+Consequently, the calculation of array bounds and indices
+for these dynamically created f90 arrays
+is now pushed of into the debugger, which must know the
+field names and usages of the dope vector C structure and
+use the field offsets etc to find data arrays.
+C, C++, f77, and most f90 arrays continue to be described
+in standard dwarf.
+At the outer allocatable/assumed-shape/pointer
+the DW_AT_location points at the dope vector (so debugger
+calculations use that as a base).
+.P
+It would have been nice to design a dwarf extension
+to handle the above problems, but
+the methods considered to date were not
+any more consistent with standard dwarf than
+this dope vector centric approach: essentially just
+as much work in the debugger appeared necessary either way.
+A better (more dwarf-ish) 
+design would be welcome information.
+
+.H 2 "A simplified sketch of the dwarf information"
+[Note:
+Needs to be written.
+end Note]
+
+.H 2 "A simplified sketch of the dope vector information"
+[Note:
+This one is simplified.
+Details left out that should be here. Amplify.
+end Note]
+This is an overly simplified version of a dope vector,
+presented as an initial hint.
+Full details presented later.
+.nf
+struct simplified{
+  void *base; // pointer to the data this describes
+  long  el_len;
+  int   assoc:1
+  int   ptr_alloc:1
+  int   num_dims:3;
+  struct dims_s {
+    long lb;
+    long ext;
+    long str_m;
+  } dims[7];
+};
+.fi
+Only 'num_dims' elements of dims[] are actually used.
+
+.H 2 "The dwarf information"
+
+Here is dwarf information from the compiler for
+the example above, as printed by dwarfdump(1)
+.nf
+[Note:
+The following may not be the test.
+Having field names with '.' in the name is 
+not such a good idea, as it conflicts with the
+use of '.' in dbx extended naming.
+Something else, like _$, would be much easier
+to work with in dbx (customers won't care about this,
+for the most part, 
+but folks working on dbx will, and in those
+rare circumstances when a customer cares,
+the '.' will be a real problem in dbx.).
+Note that to print something about .base., in dbx one
+would have to do
+	whatis `.base.`
+where that is the grave accent, or back-quote I am using.
+With extended naming one do
+	whatis `.dope.`.`.base.`
+which is hard to type and hard to read.
+end Note]
+
+<2><  388>      DW_TAG_array_type
+                DW_AT_name                  .base.
+                DW_AT_type                  <815>
+                DW_AT_declaration           yes(1)
+<3><  401>      DW_TAG_subrange_type
+                DW_AT_lower_bound           0
+                DW_AT_upper_bound           0
+<2><  405>      DW_TAG_pointer_type
+                DW_AT_type                  <388>
+                DW_AT_byte_size             4
+                DW_AT_address_class         0
+<2><  412>      DW_TAG_structure_type
+                DW_AT_name                  .flds.
+                DW_AT_byte_size             28
+<3><  421>      DW_TAG_member
+                DW_AT_name                  el_len
+                DW_AT_type                  <815>
+                DW_AT_data_member_location  DW_OP_consts 0
+<3><  436>      DW_TAG_member
+                DW_AT_name                  assoc
+                DW_AT_type                  <841>
+                DW_AT_byte_size             0
+                DW_AT_bit_offset            0
+                DW_AT_bit_size              1
+                DW_AT_data_member_location  DW_OP_consts 4
+<3><  453>      DW_TAG_member
+                DW_AT_name                  ptr_alloc
+                DW_AT_type                  <841>
+                DW_AT_byte_size             0
+                DW_AT_bit_offset            1
+                DW_AT_bit_size              1
+                DW_AT_data_member_location  DW_OP_consts 4
+<3><  474>      DW_TAG_member
+                DW_AT_name                  p_or_a
+                DW_AT_type                  <841>
+                DW_AT_byte_size             0
+                DW_AT_bit_offset            2
+                DW_AT_bit_size              2
+                DW_AT_data_member_location  DW_OP_consts 4
+<3><  492>      DW_TAG_member
+                DW_AT_name                  a_contig
+                DW_AT_type                  <841>
+                DW_AT_byte_size             0
+                DW_AT_bit_offset            4
+                DW_AT_bit_size              1
+                DW_AT_data_member_location  DW_OP_consts 4
+<3><  532>      DW_TAG_member
+                DW_AT_name                  num_dims
+                DW_AT_type                  <841>
+                DW_AT_byte_size             0
+                DW_AT_bit_offset            29
+                DW_AT_bit_size              3
+                DW_AT_data_member_location  DW_OP_consts 8
+<3><  572>      DW_TAG_member
+                DW_AT_name                  type_code
+                DW_AT_type                  <841>
+                DW_AT_byte_size             0
+                DW_AT_bit_offset            0
+                DW_AT_bit_size              32
+                DW_AT_data_member_location  DW_OP_consts 16
+<3><  593>      DW_TAG_member
+                DW_AT_name                  orig_base
+                DW_AT_type                  <841>
+                DW_AT_data_member_location  DW_OP_consts 20
+<3><  611>      DW_TAG_member
+                DW_AT_name                  orig_size
+                DW_AT_type                  <815>
+                DW_AT_data_member_location  DW_OP_consts 24
+<2><  630>      DW_TAG_structure_type
+                DW_AT_name                  .dope_bnd.
+                DW_AT_byte_size             12
+<3><  643>      DW_TAG_member
+                DW_AT_name                  lb
+                DW_AT_type                  <815>
+                DW_AT_data_member_location  DW_OP_consts 0
+<3><  654>      DW_TAG_member
+                DW_AT_name                  ext
+                DW_AT_type                  <815>
+                DW_AT_data_member_location  DW_OP_consts 4
+<3><  666>      DW_TAG_member
+                DW_AT_name                  str_m
+                DW_AT_type                  <815>
+                DW_AT_data_member_location  DW_OP_consts 8
+<2><  681>      DW_TAG_array_type
+                DW_AT_name                  .dims.
+                DW_AT_type                  <630>
+                DW_AT_declaration           yes(1)
+<3><  694>      DW_TAG_subrange_type
+                DW_AT_lower_bound           0
+                DW_AT_upper_bound           0
+<2><  698>      DW_TAG_structure_type
+                DW_AT_name                  .dope.
+                DW_AT_byte_size             44
+<3><  707>      DW_TAG_member
+                DW_AT_name                  base
+                DW_AT_type                  <405>
+                DW_AT_data_member_location  DW_OP_consts 0
+<3><  720>      DW_TAG_member
+                DW_AT_name                  .flds
+                DW_AT_type                  <412>
+                DW_AT_data_member_location  DW_OP_consts 4
+<3><  734>      DW_TAG_member
+                DW_AT_name                  .dims.
+                DW_AT_type                  <681>
+                DW_AT_data_member_location  DW_OP_consts 32
+<2><  750>      DW_TAG_variable
+                DW_AT_type                  <815>
+                DW_AT_location              DW_OP_fbreg -32
+                DW_AT_artificial            yes(1)
+<2><  759>      DW_TAG_variable
+                DW_AT_type                  <815>
+                DW_AT_location              DW_OP_fbreg -28
+                DW_AT_artificial            yes(1)
+<2><  768>      DW_TAG_variable
+                DW_AT_type                  <815>
+                DW_AT_location              DW_OP_fbreg -24
+                DW_AT_artificial            yes(1)
+<2><  777>      DW_TAG_array_type
+                DW_AT_type                  <815>
+                DW_AT_declaration           yes(1)
+<3><  783>      DW_TAG_subrange_type
+                DW_AT_lower_bound           <750>
+                DW_AT_count                 <759>
+                DW_AT_MIPS_stride           <768>
+<2><  797>      DW_TAG_variable
+                DW_AT_decl_file             1
+                DW_AT_decl_line             1
+                DW_AT_name                  ARRAY
+                DW_AT_type                  <698>
+                DW_AT_location              DW_OP_fbreg -64 DW_OP_deref
+<1><  815>      DW_TAG_base_type
+                DW_AT_name                  INTEGER_4
+                DW_AT_encoding              DW_ATE_signed
+                DW_AT_byte_size             4
+<1><  828>      DW_TAG_base_type
+                DW_AT_name                  INTEGER_8
+                DW_AT_encoding              DW_ATE_signed
+                DW_AT_byte_size             8
+<1><  841>      DW_TAG_base_type
+                DW_AT_name                  INTEGER*4
+                DW_AT_encoding              DW_ATE_unsigned
+                DW_AT_byte_size             4
+<1><  854>      DW_TAG_base_type
+                DW_AT_name                  INTEGER*8
+                DW_AT_encoding              DW_ATE_unsigned
+                DW_AT_byte_size             8
+
+.fi
+.H 2 "The dope vector structure details"
+A dope vector is the following C struct, "dopevec.h".
+Not all the fields are of use to a debugger.
+It may be that not all fields will show up
+in the f90 dwarf (since not all are of interest to debuggers).
+.nf
+[Note:
+Need details on the use of each field.
+And need to know which are really 32 bits and which
+are 32 or 64.
+end Note]
+The following
+struct 
+is a representation of all the dope vector fields.
+It suppresses irrelevant detail and may not
+exactly match the layout in memory (a debugger must
+examine the dwarf to find the fields, not
+compile this structure into the debugger!).
+.nf
+struct .dope. {
+ void *base;   // pointer to data
+ struct .flds. {
+  long el_len; // length of element in bytes?
+  unsigned int assoc:1;     //means?
+  unsigned int ptr_alloc:1;     //means?
+  unsigned int p_or_a:2;    //means?
+  unsigned int a_contig:1;  // means?
+  unsigned int num_dims: 3; // 0 thru 7
+  unsigned int type_code:32; //values?
+  unsigned int orig_base; //void *? means?
+  long         orig_size; // means?
+ } .flds;
+ 
+ struct .dope_bnd. {
+   long lb   ; // lower bound 
+   long ext  ;  // means?
+   long str_m; // means?
+ } .dims[7];
+}
+.fi
+
+.H 2 "DW_AT_MIPS_assumed_size       0x2011"
+This flag was invented to deal with f90 arrays.
+For example:
+
+.nf
+      pointer (rptr, axx(1))
+      pointer (iptr, ita(*))
+      rptr = malloc (100*8)
+      iptr = malloc (100*4)
+.fi
+
+This flag attribute has the value 'yes' (true, on) if and only if
+the size is unbounded, as iptr is.
+Both may show an explicit upper bound of 1 in the dwarf,
+but this flag notifies the debugger that there is explicitly
+no user-provided size.
+
+So if a user asks for a printout of  the rptr allocated
+array, the default will be of a single entry (as
+there is a user slice bound in the source).
+In contrast, there is no explicit upper bound on the iptr
+(ita) array so the default slice will use the current bound
+(a value calculated from the malloc size, see the dope vector).
+
+Given explicit requests, more of rptr(axx) can me shown
+than the default.
+
+.H 1 "Line information and Source Position"
+DWARF does not define the meaning of the term 'source statement'.
+Nor does it define any way to find the first user-written
+executable code in a function.
+.P
+It does define that a source statement  has a file name,
+a line number, and a column position (see Sec 6.2, Line Number
+Information of the Dwarf Version 2 document).
+We will call those 3 source coordinates a 'source position'
+in this document.  We'll try not to accidentally call the
+source position a 'line number' since that is ambiguous
+as to what it means.
+
+.H 2 "Definition of Statement"
+.P
+A function prolog is a statement.
+.P
+A C, C++, Pascal, or Fortran statement is a statement.
+.P
+Each initialized local variable in C,C++ is a statement
+in that its initialization generates a source position.
+This means that
+	x =3, y=4;
+is two statements.
+.P
+For C, C++:
+The 3 parts a,b,c in for(a;b;c) {d;} are individual statements.
+The condition portion of a while() and do {} while() is
+a statement.  (of course d; can be any number of statements)
+.P
+For Fortran, the controlling expression of a DO loop is a statement.
+Is a 'continue' statement in Fortran a DWARF statement?
+.P
+Each function return, whether user coded or generated by the
+compiler, is a statement.  This is so one can step over (in
+a debugger) the final user-coded statement 
+(exclusive of the return statement if any) in a function
+wile not leaving the function scope.
+.P
+
+.H 2 "Finding The First User Code in a Function"
+
+.nf
+Consider:
+int func(int a)
+{                    /* source position 1 */
+	float b = a; /* source position 2 */
+	int x;       
+	x = b + 2;   /* source position 3 */
+}                    /* source position 4 */
+.fi
+.P
+The DIE for a function gives the address range of the function,
+including function prolog(s) and epilog(s)
+.P
+Since there is no scope block for the outer user scope of a
+function (and thus no beginning address range for the outer
+user scope:  the DWARF committee explicitly rejected the idea
+of having a user scope block)
+it is necessary to use the source position information to find
+the first user-executable statement.
+.P
+This means that the user code for a function must be presumed
+to begin at the code location of the second source position in
+the function address range.
+.P
+If a function has exactly one source position, the function
+presumably consists solely of a return.
+.P
+If a function has exactly two source positions, the function
+may consist of a function prolog and a return or a single user
+statement and a return (there may be no prolog code needed in a
+leaf function).  In this case, there is no way to be sure which
+is the first source position of user code, so the rule is to
+presume that the first address is user code.
+.P
+If a function consists of 3 or more source positions, one
+should assume that the first source position is function prolog and
+the second is the first user executable code.
+
+.H 2 "Using debug_frame Information to find first user statement"
+In addition to the line information, the debug_frame information
+can be
+useful in determining the first user source line.
+.P
+Given that a function has more than 1 source position,
+Find the code location of the second source position, then
+examine the debug_frame information to determine if the Canonical
+Frame Address (cfa) is updated before the second source position
+code location.
+If the cfa is updated, then one can be pretty sure that the
+code for the first source position is function prolog code.
+.P
+Similarly, if the cfa is restored in the code for
+a source position, the source position is likely to
+represent a function exit block.
+
+.H 2 "Debugger Use Of Source Position"
+Command line debuggers, such as dbx and gdb, will ordinarily
+want to consider multiple statements on one line to be a single
+statement: doing otherwise is distressing to users since it
+causes a 'step' command to appear to have no effect.
+.P
+An exception for command line debuggers is in determining the
+first user statement: as detailed above, there one wants to
+consider the full  source position and will want to consider
+the function return a separate statement.  It is difficult to
+make the function return a separate statement 'step' reliably
+however if a function is coded all on one line or if the last
+line of user code before the return  is on the same line as the
+return.
+.P
+A graphical debugger has none of these problems if it simply
+highlights the portion of the line being executed.  In that
+case, stepping will appear natural even stepping within a
+line.
+.H 1 "Known Bugs"
+Up through at least MIPSpro7.2.1
+the compiler has been emitting form DW_FORM_DATA1,2, or 4
+for DW_AT_const_value in DW_TAG_enumerator.
+And dwarfdump and debuggers have read this with dwarf_formudata()
+or form_sdata() and gotten some values incorrect.
+For example, a value of 128 was printed by debuggers as a negative value.
+Since dwarfdump and the compilers were not written to use the
+value the same way, their output differed.
+For negative enumerator values the compiler has been emitting 32bit values
+in a DW_FORM_DATA4.
+The compiler should probably be emitting a DW_FORM_sdata for
+enumerator values.
+And consumers of enumerator values should then call form_sdata().
+However, right now, debuggers should call form_udata() and only if
+it fails, call form_sdata().
+Anything else will break backward compatibility with
+the objects produced earlier.
+.SK
+.S
+.TC 1 1 4
+.CS