
*****************************************************************************
*                                                                           
*                             DISCLAIMER
*                                                                          
*  Sun Microsystems, Inc. has intellectual property rights relating to
*  technology mentioned in this document. In particular, and without
*  limitation, these intellectual property rights may include one or more
*  of the U.S. patents listed at http://www.sun.com/patents and one or more
*  additional patents or pending patent applications in the U.S. and other
*  countries. Sun expressly reserves all rights it may have.
*
*
*  Copyright (c) 2003 Sun Microsystems, Inc., 
*  4150 Network Circle, Santa Clara, California 95054, U.S.A. 
*  All rights reserved.
*  
*  U.S. Government Rights - Commercial software. Government users 
*  are subject to the Sun Microsystems, Inc. standard license 
*  agreement and applicable provisions of the FAR and its supplements.
*  
*  Use is subject to license terms. 
*  
*  This distribution may include materials developed by third parties.
*  
*  Sun, Sun Microsystems, the Sun logo, Solaris and Sun[tm] ONE Studio 
*  are trademarks or registered trademarks of Sun Microsystems, Inc. 
*  in the U.S.  and other countries.
*  
*  DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED 
*  CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED 
*  WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
*  NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH 
*  DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
*  
*****************************************************************************


                            Sun Dwarf2 Extensions

This document  describes the Sun extensions made to the Dwarf2 debugging
format.

----------------------------------------------------------------------------

Tags

     DW_TAG_SUN_function_template (0x4201)

          This TAG is what is being used for a C++ function
          template definition.  (It should be similar to the GNU
          extension DW_TAG_function_template, but since we didn't
          have the details on this GNU extension we felt it was
          safer for us to create our own).
          This TAG could get the same attributes as the Standard
          DW_TAG_subprogram.

     DW_TAG_SUN_class_template (0x4202)

          This TAG is being used for a C++ class template
          definition. (It should be similar to the GNU extension
          DW_TAG_class_template tag).
          This TAG should be used only when the keyword "class"
          was used in the template definition.
          This TAG should get the same attributes as the Standard
          DW_TAG_class_type.

     DW_TAG_SUN_struct_template (0x4203)

          This TAG is being used for a C++ struct template
          definition. (It should be similar to the GNU extension
          DW_TAG_class_template tag).
          This TAG should be used only when the keyword "struct"
          was used in the template definition.
          This TAG should get the same attributes as the Standard
          DW_TAG_class_type.

     DW_TAG_SUN_union_template (0x4204)

          This TAG is being used for a C++ union template
          definition. (It should be similar to the GNU extension
          DW_TAG_class_template tag).
          This TAG should be used only when the keyword "union"
          was used in the template definition.
          This TAG should get the same attributes as the Standard
          DW_TAG_class_type.

     DW_TAG_SUN_virtual_inheritance (0x4205)

          This TAG is being used for Sun C++ ABI virtual
          inheritance information.
          This TAG should get the same attributes as the Standard
          DW_TAG_inheritance.

     DW_TAG_SUN_codeflags (0x4206)

          This TAG records one specific boolean logical flag
          associated with any number of instructions in the current
          function.  The instructions are identified by offsets from
          low_pc of the function.  The tag appears only inside functions.

          It has two valid attributes.

          DW_AT_SUN_cf_kind records a code value that represents the
          boolean flag that should be associated with the given
          instructions.  These code values are defined as symbols
          starting with DW_ATCF_SUN_.  For a list of possible
          flags and their meanings, see elsewhere in this document.

          DW_AT_SUN_func_offsets records the offsets of the instructions
          that should be marked with this flag.  The offsets are
          sorted and recording using run length encoding. The first
          number in the value of this attribute is the offset from
          the low_pc of the function to the first instruction with this
          flag.  The second number is the offset between the first
          flagged instruction and the second flagged instruction, and so on.

     DW_TAG_SUN_memop_info (0x4207)

          This information is emitted for the performance analyzer
          and identifies memory operations with the types or
          structure members that they access.  Each tag represents
	  information about one specific memory instruction
	  in the code.
	  
          The attributes are:
	  DW_AT_SUN_func_offset       Unsigned Constant
	  DW_AT_SUN_memop_type_ref    Reference
	  DW_AT_SUN_profile_id        Unsigned Constant
	  DW_AT_SUN_memop_signature   Unsigned Constant

	  DW_AT_SUN_func_offset records the offset of the instruction
	  within the function.

	  DW_AT_SUN_memop_type_ref records a DIE reference
	  that points to the type of the variable that is being
	  referenced by this memory instruction. If a structure
	  member is being accessed, then this is a reference to
	  the DW_AT_member tag for that member.

	  DW_AT_SUN_profile_id records an opaque number used by
	  the performance analyzer system.

	  DW_AT_SUN_memop_signature records an opaque number
	  used by the performance analyzer system.
	  
    DW_TAG_SUN_omp_child_func (0x4208)

	  This tag is used to hold a DW_TAG_SUN_omp_child_func
	  attribute.  You can't have multiple attributes of the
 	  same kind attached to the same tag.  So this tag is attached
	  to a subprogram tag, just so it can hold a single attribute.
		
         
----------------------------------------------------------------------------

Attributes

     DW_AT_SUN_template (0x2201) (Reference)

          This attribute can be given to any C++
          DW_TAG_structure_type, DW_TAG_union_type,
          DW_TAG_class_type,  or  DW_TAG_subprogram tag  that
          represents an instantiation of a C++ template. This
          attribute should have a reference that will refer to the
          template definition, e.g. the attribute should refer to
          one of the tags DW_TAG_SUN_function_template,
          DW_TAG_SUN_class_template, DW_TAG_SUN_struct_template,
          or DW_TAG_SUN_union_template.  This attribute provides
          the connection from the actual  C++ template
          instantiation, and the template definition.
          This TAG can get the same attributes as the Standard
          DW_TAG_class_type.

     DW_AT_SUN_alignment (0x2202) (Unsigned Constant)

          This attribute should be given to any
          DW_TAG_structure_type, DW_TAG_union_type, or
          DW_TAG_class_type tag when the default alignment for a
          variable of this type is non-standard for the hardware.
          The Sun compilers have a directive "#pragma pack(n)"
          which changes the default alignment on a type and forces
          a packing of it's fields to that alignment.  The value
          for this attribute is a constant which represents the
          alignment requested by the user in the #pragma pack
          directive, limited to 1, 2, 4, or 8.

     DW_AT_SUN_vtable (0x2203) (Signed Constant)

          This attribute can be provided on a DW_TAG_class_type
          which is virtual, in order to provide the Sun C++ ABI
          offset into the virtual table for this type. It has a
          constant value which represents a table index.

     DW_AT_SUN_count_guarantee (0x2204) (Unsigned Constant)

          This attribute can be used on a DW_TAG_pointer_type
          which happens to be the type of a formal argument
          declared with the C99 syntax to provide a guaranteed
          number of elements that the pointer refers too. The
          pointer is actually a reference to an array of objects,
          and the count guarantee is on how many elements are
          guaranteed to be available at that address.
          Used in C99 to indicate that the formal was declared
          with the C99 syntax that defines this formal to have an
          array type with a guaranteed minimum number of elements.
          This attribute should only be placed on
          DW_TAG_pointer_type's that are the types of
          DW_TAG_formal_parameter's. Example: void f(int a[static
          5]){}

     DW_AT_SUN_command_line (0x2205) (String)

          This attribute should only be placed on the
          DW_TAG_compile_unit and it contains the compile line
          used to build this compilation unit (object file) as
          supplied by the compiler.

     DW_AT_SUN_vbase (0x2206) (Signed Constant)

          This attribute is similar to the DW_AT_SUN_vtable, but
          will only be used on a DW_TAG_inheritance or
          DW_TAG_SUN_virtual_inheritance and represents an offset
          into the virtual table.

     DW_AT_SUN_compile_options (0x2207) (String)

          This attribute should only be placed on the
          DW_TAG_compile_unit and it contains the same information
          as the Sun Stabs N_OPT stab, a ';' separated series of
          name=value patterns used to detect various
          characteristics of the compilation and generated code.

     DW_AT_SUN_language (0x2208) (Unsigned Constant)

          This attribute is used exactly like the DW_AT_language
          attribute but can be placed on any TAG that needs to be
          flagged as being marked as using a different language
          linkage or semantics than the language setting on the
          DW_TAG_compile_unit.  Normally this will be seen when
          the C++ source contains the use of 'extern "C" { }'
          blocks.

     DW_AT_SUN_browser_file (0x2209) (String)

          This attribute should only be placed on the
          DW_TAG_compile_unit and it contains the same information
          as the Sun Stabs N_BROWS stab.

     DW_AT_SUN_vtable_abi (0x2210) (Unsigned Constant)

          This attribute should only be placed on a
          DW_TAG_structure_type, DW_TAG_union_type, or
          DW_TAG_class_type and will contain the Sun C++ compiler
          virtual table ABI version for this virtual table.

     DW_AT_SUN_func_offsets (0x2211) (Block)

          This attribute is a generic way to record an array
          of signed LEB numbers.  It is used by DW_AT_TAG_codeflags.

     DW_AT_SUN_cf_kind (0x2212) (Unsigned Constant)

          This attribute records the type code for a codeflags
          block.  See DW_TAG_SUN_codeflags.

     DW_AT_SUN_vtable_index (0x2213) (Signed Constant)

          This attribute should only be placed on a DW_TAG_subroutine for a
          C++ virtual function and will contain the Sun C++ compiler virtual
          table index for this method.

     DW_AT_SUN_omp_tpriv_addr (0x2214) (Address)

          This is the address of a pointer-sized variable created
          by the compiler to implement per-thread copies of the
          variable with this attribute.  This address is used in
          an implementation-dependant way by the debugger to access
          per-thread versions of the variable.  Eventually this
          mechanism should be replaced by TLS variables which are
          supported directly by the linker and libthread.
          Attributes of type "address" are rare in dwarf.  The normal
          way to refer to another variable is to refer to the DIE
          (tag) for that variable.  But we don't do it that way
	  because we don't have that handle handy when generating dwarf.
          It would have been better to refer to the DIE,
          then this would be a local DIE reference instead of an addr.
          And it wouldn't require a linker relocation.

     DW_AT_SUN_omp_child_func (0x2215) (Reference)

          This attribute belongs on a DW_TAG_SUN_omp_child_func die
	  which is within a function DIE and points to
          another function DIE that should be considered to have a
          nested scope within the first function.  This is used
          to describe the "outlining" of a parallel region that
          happens as part of OpenMP processing.  The original function
          with an OpenMP parallel region will end up having one of
          these tag/attribute pairs which point at the DIE for the 
 	  artificial function that will be executed by multiple threads.  

          This probably should be implemented by simply
          nesting the DW_TAG_subprogram of the outlined function
          inside the DW_TAG_subprogram of the original function.
          even though that's not the way the source was written.
          But I don't know if that will work properly.  This attribute
          was originally implemented to mimic the way the stabs format
          describes the same information.  Changing the actual scope
          of the artificial function would have impacts in
          the debug generation library and in dbx.

          Since this attribute ocurrs within a DW_TAG_SUN_omp_child_func,
	  it should probably have been called "DW_AT_SUN_func_ref".
	  So the attribute could be reused for other purposes.

     DW_AT_SUN_func_offset (0x2216) (Unsigned Constant)

          This attribute is an offset from the low_pc of the function
	  that contains the tag that contains this attribute.
	  This is used by DW_TAG_SUN_memop_info, and perhaps other tags
	  in the future.
	  
     DW_AT_SUN_memop_type_ref (0x2217) (Reference)

          This attribute is used by DW_TAG_SUN_memop_info.
	  For more information see the description of that tag.
	  
     DW_AT_SUN_profile_id  (0x2218) (Unsigned Constant)
     
          This attribute is used by DW_TAG_SUN_memop_info.
	  For more information see the description of that tag.
	  
     DW_AT_SUN_memop_signature (0x2219) (Unsigned Constant)
     
          This attribute is used by DW_TAG_SUN_memop_info.
	  For more information see the description of that tag.

     DW_AT_SUN_obj_dir (0x2220) (String)
     DW_AT_SUN_obj_file (0x2221) (String)

          These two attributes can be applied to a
          DW_TAG_compilation_unit to describe the location and
          name of the object file that was being created when the
          dwarf information was generated.  This information is
          not normally required by a debugger, but it can
          help to correlate dwarf information between two different
          versions of the same object file.

          The directory name should not contain a trailing slash
          character, and the recommended form is the same as for
          DW_AT_comp_dir, `hostname:path' or `:path'.  In the SUN
          implementation path should always be a full pathname.
          DW_AT_obj_file should not contain any '/' characters.
          The path name might also be relative to the directory
          in DW_AT_comp_dir.

     DW_AT_SUN_original_name (0x2222) (String)

          This attribute is applied to a compilation unit tag when
	  the original source file name is not the same as the
	  source file fed to the compiler.  For example, a user 
	  preprocesses a .c file into a .i file, then compiles the
	  .i file.  In this case, the .i file has #line directives
	  which cause line number information to point to the original
	  .c file.  But the debugger might require both names to
	  be available.  If the source file has two names like this
	  then the DW_AT_name attribute will have the name fed
	  to the compiler (the .i file) and the DW_AT_SUN_original_name
	  will have the original name of the source file (the .c file).
	  The same mechanism should apply to yacc and lex files.
	                 

----------------------------------------------------------------------------

Basic Types

     DW_ATE_SUN_interval_float (0x91)

          This extension allows for the Sun "interval" types.

     DW_ATE_SUN_imaginary_float (0x92)

          This extension allows for the  C99 basic type of
          "imaginary".

----------------------------------------------------------------------------

Languages

     DW_LANG_SUN_Assembler (0x9001)

          This language setting has been made explicit with the
          SUN compilers rather than use the "unknown" language
          value. There has been some indication that the Sun
          assembler might generate source level debug information
          on assembly and it was felt this might be needed.

----------------------------------------------------------------------------

Code Flags

     These type codes (kinds) are used to define different kinds
     of instruction attributes in a codeflags entry.
     See 

     The DW_TAG_SUN_codeflags tag is used to record boolean attributes
     about individual instructions in a function.  Each codeflags tag
     sets a specific boolean attribute on a list of instructions.
     This is a list of possible types for a DW_TAG_SUN_codeflags tag.
     These are possible values for the DW_AT_SUN_cf_kind attribute
     of the DW_TAG_SUN_codeflags tag.

     Note: If DW_TAG_SUN_codeflags is accepted as a dwarf standard, then
     standard dwarf ATCF entries should start at 0x01

     Note: cf_kind names which contain "_mop_" are markers for
     [M]emory [OP]erations.  This information is used for
     memory access checking functionality. (Sun dbx RTC)

     DW_ATCF_SUN_mop_bitfield (0x41)

          Marks a bitfield load which might read data from
          memory that hasn't been initialized to a known value.

     DW_ATCF_SUN_mop_spill (0x42)

          Marks reads and writes that are used to spill scalar
          and floating point registers to the stack.

     DW_ATCF_SUN_mop_scopy (0x43)

          This code flag maps to the Stabs N_PATCH or
          N_CODETAG stabs. It is used to mark the load or store of
          a structure.

     DW_ATCF_SUN_func_start (0x44)

          This code flag maps to the Stabs N_PATCH or
          N_CODETAG stabs. It is used to mark the beginning of the
          user instructions of a function (past all the invisible
          function setup code and frame setup).

     DW_ATCF_SUN_end_ctors (0x45)

          This code flag maps to the Stabs N_PATCH or
          N_CODETAG stabs. It is used to mark the beginning of the
          instructions of a function (past all the super
          constructor calls).

     DW_ATCF_SUN_branch_target (0x46)

          This code flag marks instructions which are the target
          of branch instructions.

     DW_ATCF_SUN_mop_stack_probe (0x47)

          This code flag marks special memory probe instructions
          which are used to check stack boundaries by.


----------------------------------------------------------------------------

Last updated on 02/12/03
