[PATCH] Naming dwarves

[PATCH] Naming dwarves

[Mark Kettenis]

Andrew already made a side-remark in an earlier message: how are we
going to name our files and functions related to DWARF?

There are basically two generations of the DWARF Debugging Information
Format.  The first generation is usually referred to as DWARF Version
1.  There is a 1.1.0 revision of the DWARF standard, but this revision
is supposed to be fully binary compatible with the origional DWARF
definition.  The second generation is referred to as DWARF Version 2,
or simply DWARF-2.  Although the basic structure of Version 2 format
is the very similar to Version 1, the encoding is different.
Therefore these two formats are not binary compatible, which is why we
have seperate DWARF and DWARF-2 symbol readers in GDB.  There are also
many new features in DWARF-2.

There is also a public draft for DWARF Version 3, which should be
largely binary compatible with Version 2.  Standardization of Version
3 seems to have stopped, but some of the proposed extensions are
already in use.  I believe our DWARF-2 reader supports these.  Since
the Version 3 format is largely binary compatible with Version 2, I
don't think we'll ever have a seperate DWARF-3 reader in GDB.  The
number of new features in the proposed standard is rather limited.

Currently we have the following files dealing with DWARF:

DWARF Version 1:
  dwarfread.c

DWARF Version 2:
  dwarf2read.c
  dwarf2expr.c dwarf2expr.h
  dwarf2loc.c dwarf2loc.h
  dwarf2cfi.c dwarf2cfi.h (consider these deprecated)
  dwarf-frame.c dwarf-frame.h (on the i386newframe branch)

The dwarfread.c module exports only one function:
dwarf_build_psymtabs().  The dwarf2*.c modules export several
functions, some with the dwarf2_ prefix, some with the dwarf_ prefix,
and some with no prefix at all.  I think Andrew would like to see that
we use dwarf2 in the names of files implementing DWARF-2 things, and
the dwarf2_ prefix for public function names.  Is that right?  If
people agree, I'll rename my DWARF CFI bits before I move things over
to mainline.

Mark

Re: [PATCH] Naming dwarves

[Daniel Jacobowitz]

On Sat, May 17, 2003 at 02:53:29PM +0200, Mark Kettenis wrote:
> Andrew already made a side-remark in an earlier message: how are we
> going to name our files and functions related to DWARF?
> 
> There are basically two generations of the DWARF Debugging Information
> Format.  The first generation is usually referred to as DWARF Version
> 1.  There is a 1.1.0 revision of the DWARF standard, but this revision
> is supposed to be fully binary compatible with the origional DWARF
> definition.  The second generation is referred to as DWARF Version 2,
> or simply DWARF-2.  Although the basic structure of Version 2 format
> is the very similar to Version 1, the encoding is different.
> Therefore these two formats are not binary compatible, which is why we
> have seperate DWARF and DWARF-2 symbol readers in GDB.  There are also
> many new features in DWARF-2.
> 
> There is also a public draft for DWARF Version 3, which should be
> largely binary compatible with Version 2.  Standardization of Version
> 3 seems to have stopped, but some of the proposed extensions are
> already in use.  I believe our DWARF-2 reader supports these.  Since
> the Version 3 format is largely binary compatible with Version 2, I
> don't think we'll ever have a seperate DWARF-3 reader in GDB.  The
> number of new features in the proposed standard is rather limited.
> 
> Currently we have the following files dealing with DWARF:
> 
> DWARF Version 1:
>   dwarfread.c
> 
> DWARF Version 2:
>   dwarf2read.c
>   dwarf2expr.c dwarf2expr.h
>   dwarf2loc.c dwarf2loc.h
>   dwarf2cfi.c dwarf2cfi.h (consider these deprecated)
>   dwarf-frame.c dwarf-frame.h (on the i386newframe branch)
> 
> The dwarfread.c module exports only one function:
> dwarf_build_psymtabs().  The dwarf2*.c modules export several
> functions, some with the dwarf2_ prefix, some with the dwarf_ prefix,
> and some with no prefix at all.  I think Andrew would like to see that
> we use dwarf2 in the names of files implementing DWARF-2 things, and
> the dwarf2_ prefix for public function names.  Is that right?  If
> people agree, I'll rename my DWARF CFI bits before I move things over
> to mainline.

I'd certainly prefer it to be a dwarf2frame or dwarf2-frame rather than
dwarf.

I'm thinking about running through dwarf2read.c and renaming dwarf_*
there...

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

Re: [PATCH] Naming dwarves

[James Cownie]

Mark Kettenis wrote :-

> There is also a public draft for DWARF Version 3, which should be
> largely binary compatible with Version 2.  Standardization of Version
> 3 seems to have stopped, but some of the proposed extensions are
> already in use. 

It's about to start up again (there was a hiatus when the dot com bust
happened, since at that point none of the companies wanted to pay any
money to have a "real" standard produced).

This message from Michael Eager gives the current status

  Date: Thu, 08 May 2003 12:12:15 -0700
  From: Michael Eager <eager@eagercon.com>
  To: Dwarf 2 <dwarf2@els.sgi.com>
  Cc: Scott McNeil <mcneil@freestandards.org>
  Subject: DWARF Standard becoming part of Free Standards Group
  Sender: owner-dwarf2@els.sgi.com

  As you may know, for some time I've been working on finding a
  standards organization with which to affiliate the DWARF standard.

  I've looked into a variety of organizations, ranging from the
  "heavy weight's" of ANSI or IEEE, and the lighter weight organization
  like IEEE-ISTO.  I believe that the Free Standards Group offers
  us an excellent combination of stability and public visiblity.

  You may be familiar with Free Standards Group because it is the
  home of the Linux Standards Base (FSG and LSB, respectively, for
  those who like TLAs).  You can find more info about FSG at
  http://www.freestandardsgroup.org.  While FSG has been closely
  associated with Linux in the past, its charter is broader and
  does encompass architecture-independent standards like DWARF.

  In the next few weeks, we will create a web page at FSG for
  DWARF which will include the Public Review Draft which has
  been languishing on my system for a long while.  We will arrange
  for public comments to be collected and evaluated.  I also hope
  to be able to add a FAQ and perhaps some other materials to
  the web site which will make using DWARF easier.  FSG also
  has facilities for spam-filtered mailing lists.

  -- 
  Michael Eager	 Eager Consulting     eager@eagercon.com
  1960 Park Blvd., Palo Alto, CA 94306  650-325-8077

The DWARF 3 site is at http://www.eagercon.com/dwarf/dwarf3std.htm
I'm not sure how you get on the mailing list, but talking to Mike
Eager seems a good start...

-- Jim 

James Cownie	<jcownie@etnus.com>
Etnus, LLC.     +44 117 9071438
http://www.etnus.com

Re: [PATCH] Naming dwarves

[Elena Zannoni]

Mark Kettenis writes:
 > Andrew already made a side-remark in an earlier message: how are we
 > going to name our files and functions related to DWARF?
 > 
 > There are basically two generations of the DWARF Debugging Information
 > Format.  The first generation is usually referred to as DWARF Version
 > 1.  There is a 1.1.0 revision of the DWARF standard, but this revision
 > is supposed to be fully binary compatible with the origional DWARF
 > definition.  The second generation is referred to as DWARF Version 2,
 > or simply DWARF-2.  Although the basic structure of Version 2 format
 > is the very similar to Version 1, the encoding is different.
 > Therefore these two formats are not binary compatible, which is why we
 > have seperate DWARF and DWARF-2 symbol readers in GDB.  There are also
 > many new features in DWARF-2.
 > 
 > There is also a public draft for DWARF Version 3, which should be
 > largely binary compatible with Version 2.  Standardization of Version
 > 3 seems to have stopped, but some of the proposed extensions are
 > already in use.  I believe our DWARF-2 reader supports these.  Since
 > the Version 3 format is largely binary compatible with Version 2, I
 > don't think we'll ever have a seperate DWARF-3 reader in GDB.  The
 > number of new features in the proposed standard is rather limited.
 > 
 > Currently we have the following files dealing with DWARF:
 > 
 > DWARF Version 1:
 >   dwarfread.c
 > 
 > DWARF Version 2:
 >   dwarf2read.c
 >   dwarf2expr.c dwarf2expr.h
 >   dwarf2loc.c dwarf2loc.h
 >   dwarf2cfi.c dwarf2cfi.h (consider these deprecated)
 >   dwarf-frame.c dwarf-frame.h (on the i386newframe branch)
 > 
 > The dwarfread.c module exports only one function:
 > dwarf_build_psymtabs().  The dwarf2*.c modules export several
 > functions, some with the dwarf2_ prefix, some with the dwarf_ prefix,
 > and some with no prefix at all.  I think Andrew would like to see that
 > we use dwarf2 in the names of files implementing DWARF-2 things, and
 > the dwarf2_ prefix for public function names.  Is that right?  If
 > people agree, I'll rename my DWARF CFI bits before I move things over
 > to mainline.

yes please, that would be super.

thanks
elena


 > 
 > Mark

Re: [PATCH] Naming dwarves

[Andrew Cagney]

> Andrew already made a side-remark in an earlier message: how are we
> going to name our files and functions related to DWARF?
> 
> There are basically two generations of the DWARF Debugging Information
> Format.  The first generation is usually referred to as DWARF Version
> 1.  There is a 1.1.0 revision of the DWARF standard, but this revision
> is supposed to be fully binary compatible with the origional DWARF
> definition.  The second generation is referred to as DWARF Version 2,
> or simply DWARF-2.  Although the basic structure of Version 2 format
> is the very similar to Version 1, the encoding is different.
> Therefore these two formats are not binary compatible, which is why we
> have seperate DWARF and DWARF-2 symbol readers in GDB.  There are also
> many new features in DWARF-2.
> 
> There is also a public draft for DWARF Version 3, which should be
> largely binary compatible with Version 2.  Standardization of Version
> 3 seems to have stopped, but some of the proposed extensions are
> already in use.  I believe our DWARF-2 reader supports these.  Since
> the Version 3 format is largely binary compatible with Version 2, I
> don't think we'll ever have a seperate DWARF-3 reader in GDB.  The
> number of new features in the proposed standard is rather limited.
> 
> Currently we have the following files dealing with DWARF:
> 
> DWARF Version 1:
>   dwarfread.c
> 
> DWARF Version 2:
>   dwarf2read.c
>   dwarf2expr.c dwarf2expr.h
>   dwarf2loc.c dwarf2loc.h
>   dwarf2cfi.c dwarf2cfi.h (consider these deprecated)
>   dwarf-frame.c dwarf-frame.h (on the i386newframe branch)
> 
> The dwarfread.c module exports only one function:
> dwarf_build_psymtabs().  The dwarf2*.c modules export several
> functions, some with the dwarf2_ prefix, some with the dwarf_ prefix,
> and some with no prefix at all.  I think Andrew would like to see that
> we use dwarf2 in the names of files implementing DWARF-2 things, and
> the dwarf2_ prefix for public function names.  Is that right?  If
> people agree, I'll rename my DWARF CFI bits before I move things over
> to mainline.

Yes, all correct, except ``DWARF 2'' (which appears in the spec once) 
rather than ``DWARF-2'' :-)

Andrew

Re: [PATCH] Naming dwarves

[Jim Blandy]

What Elena and Andrew said about the current naming convention
(dwarf2) is my understanding, too.

But it's a bit confusing to talk about the modern Dwarf reader this
way.  If I say "the Dwarf reader", it's not clear that I don't mean
Dwarf 1.  (Which I never do.)  If I say "the Dwarf 2 reader", then it
sounds like I want to exclude the extensions in Dwarf 3.  (Which I
almost never do.)  And I end up saying odd-sounding things like "the
modern Dwarf reader".

The major distinction between Dwarf 1 and Dwarf 2 was the introduction
of the abbreviation table, introduced because Dwarf 1 was even more
enormous than Dwarf 2 is.  But since that change, Dwarf has been able
to grow pretty well, and incorporate major improvements like duplicate
suppression, without breaking compatibility again.  So I wonder if we
won't eventually have a reader named dwarf2 that handles Dwarf 2, 3,
and 4.

Would it make sense to, at some point (not today) adopt "dwarf1" as
the prefix for the dwarf1 reader, and simply "dwarf" for the modern
Dwarf reader?

For what it's worth, the latest Dwarf spec usually just calls it
"DWARF".