\."

\." 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"