010228.1 A T. Allen Representation Generalize DW_AT_specification

The Ada language is composed of program units (e.g. packages, subprograms,
tasks, etc.). These units may be declared in such a way that they require
completions. The most straightforward is a simple package:

    package foo is
        procedure action;
    end foo;

    package body foo is
        procedure action is
        begin
        ...
        end action;
    end foo;

The first declaration of foo just described the interface, but was
incomplete. The second (body) declaration of foo completed it. Likewise,
for the action procedure declared within. There can also be chains of
incomplete declarations terminated by a final complete declaration:

    package foo is
        procedure action;
    end foo;

    package body foo is
        procedure action is separate;
    end foo;

    separate (foo)
    procedure action
    begin
        ...
    end action;

The first declaration of action declares the interface. The second completes
the first and indicates that the proper body is elsewhere (but provides a
logical place for it to be nested, for visibility purposes). Although the
second declaration completes the first, it is itself incomplete. The third
declaration of action completes it.

The DW_AT_declaration and DW_AT_specification attributes are used for other
entities (e.g. types and objects) for just this purpose. We decided it made
a lot of sense to expand their use to include units and, generally, any
entity that might have an incomplete declaration, or might complete another
declaration.

Also, in Ada, any type can be declared incomplete and then later completed.
The wording of the main part of the document encompasses this, but the table
in Appendix A doesn't allow for it. I'm updating the table for any type that
Ada might use.

Ada also has Altogether Different Things which can be declared incomplete,
and later completed. More vague wording seems appropriate to allow for
language/vendor extensions more easily.

WORDING CHANGES:

  [From table, page 13]:

   -------------------------------------------------------------------------
| | DW_AT_declaration      | Incomplete, non-defining, or separate entity  |
| |                         | declaration                                   |
   -------------------------------------------------------------------------
      :
   -------------------------------------------------------------------------
| | DW_AT_specification    | Incomplete, non-defining, or separate entity  |
| |                         | declaration corresponding to this declaration |
   -------------------------------------------------------------------------

| 2.13 Non-defining Declarations and Completions
|
| A debugging information entry representing a program entity typically
| represents the defining declaration of that entity. In certain contexts,
| however, a debugger might need information about a declaration of an
| entity that is not also a definition, or is otherwise incomplete, to
| evaluate an expression correctly.

    :

  ANSI C scoping rules require that the value of the variable x passed to
  the function g is the value of the global variable x rather than of the
  local version

| 2.13.1 Non-defining Declarations
|
| Debugging information entries that represent non-defining or otherwise
| incomplete declarations of a program entity have a DW_AT_declaration
| attribute, whose value is a flag.
|
| 2.13.1 Declarations completing non-defining declarations
|
| If an entity declaration completes another, earlier declaration, then its
| debugging information entry has a DW_AT_specification attribute whose
| value is a reference to the debugging information entry representing the
| earlier, completed declaration. Debugging information entries with a
| DW_AT_specification attribute do not need to duplicate information
| provided by the declaration entry referenced by the specification
| attribute.

3.2.2
4.1(5.)
5.6.1
5.6.7

    [Each of these sections contains text about DW_AT_specification which is
    somewhat redundant now, but they are interesting special cases because the
    completion is nested within a different scope than the completed
    declaration. So, I think their text should be retained.]

Appendix A

   ---------------------------------------------------------------------------
   | DW_TAG_array_type        | DECL                                          |
   |                               :                                          |
   |                          | DW_AT_sibling                                 |
|  |                          | DW_AT_specification                            |
   |                          | DW_AT_start_scope                             |
   |                               :                                          |
   ---------------------------------------------------------------------------
      :
   ---------------------------------------------------------------------------
   | DW_TAG_class_type        | DECL                                          |
   |                              :                                           |
   |                          | DW_AT_sibling                                 |
|  |                          | DW_AT_specification                           |
   |                          | DW_AT_start_scope                             |
   |                               :                                          |
   ---------------------------------------------------------------------------
      :
   ---------------------------------------------------------------------------
   | DW_TAG_enumeration_type  | DECL                                          |
   |                              :                                           |
   |                          | DW_AT_sibling                                 |
|  |                          | DW_AT_specification                           |
   |                          | DW_AT_start_scope                             |
   |                               :                                          |
   ---------------------------------------------------------------------------
      :
   ---------------------------------------------------------------------------
   | DW_TAG_module            | DECL                                          |
   |                               :                                          |
   |                          | DW_AT_sibling                                 |
|  |                          | DW_AT_specification                           |
   |                          | DW_AT_visibility                              |
   ---------------------------------------------------------------------------
      :
   ---------------------------------------------------------------------------
   | DW_TAG_pointer_type      | DECL                                          |
   |                               :                                          |
   |                          | DW_AT_sibling                                 |
|  |                          | DW_AT_specification                           |
   |                          | DW_AT_start_scope                             |
   |                               :                                          |
   ---------------------------------------------------------------------------
      :
   ---------------------------------------------------------------------------
   | DW_TAG_structure_type    | DECL                                          |
   |                               :                                          |
   |                          | DW_AT_sibling                                 |
|  |                          | DW_AT_specification                           |
   |                          | DW_AT_start_scope                             |
   |                               :                                          |
   ---------------------------------------------------------------------------


Adopted with the clarification that text under 2.13.1 should read "may have an DW_AT_specification" instead of "has an DW_AT_specification".