notes on Nov 30 draft

[David B Anderson <davea at quasar dot engr dot sgi dot com>]

The 1130 draft 5 document seems very good to me.
In this review I remark on the _very_ few items I noted that
seemed to merit attention.


Very well done, Ron.


==================
Sec 1.2

"The informational content is described in sections two through
six. Section two describes the overall structure of the
information and attributes that is common to many or all of the
different debugging information entries. Sections three, four
and five describe the specific debugging information entries
and how they communicate the necessary information about the
source program to a debugger. Section six describes debugging
information contained outside of the debugging information
entries, themselves. The encoding of the DWARF information is
presented in Section seven."

A new version of that one sentence, removing the 'themselves'word:
...
Section six describes debugging
information contained outside of the debugging information
entries. ...

==================
Following section 1.5.1, Upward Compatibility

a completely blank page page 4 prints.  
This is sort of ok and sort of alarming:
one wonders if the printer goofed or if the page is supposed to be blank.


==================
Section 2.2, Attribute Types.

The entry in the table for 
DW_AT_trampoline says
		"Target subroutine"

This is hard to grasp. I would suggest
	Identify target subroutine"

Indeed the column title 'Use" in 2.2 could be
called
	 Identifies or Specifies
perhaps?   It is tricky to identify each
in a couple of words.


==================
Section 2.4.1.4

DW_OP_abs
Perhaps add something like
"If the absolute value of the signed value cannot be represented,
the result of the operation is undefined."

==================
2.16.2, Contiguous Address Range

"The high PC value may be beyond the last valid instruction in the 
execuatable. "
^^^^^^^^^^^

misspelled.


==================
2.16.3 Non-Contiguous Address Ranges
"When the set of addresses of a debugging information entry
cannot be described as a single contiguous range, the entry has
a DW_AT_ranges attribute whose value is of class rangeptr and
indicates the beginning of a range list."


At times
	rangeptr
and other times
	rangelistptr
is used.

This inconsistency should be removed.
I don't care which spelling is used, I'd just  prefer
to see a single spelling.



And then just a few lines down:

"Each entry in a range list consists of:
1. A beginning address. This address is relative to the base
address of the compilation unit referencing this range list."

The problem here is that the definition of 'base adddress'
of the CU does not appear till the end of the CompilationUnitEntries
section, and it's very hard to find that, there
being no section header or anything to help.  The good news
is that the *definition* does appear in the index!
It would be nice if the reference did too, and it would be nice if
 there was a little header Or something.. Or perhaps not.



===================
2.16
"The end of any given range list is marked by a 0 for the
beginning address and a 0 for the ending address."

Would it be good to add a "Therefore a
zero-length range is not advisable as it may make
some compilation unit entries indistinguisable from and end-marker."


===================
3.3.9

"If the value is of class string, then the value is the
(possibly mangled) name of the target subprogram."


This is correct as written.  I worry it's so vague as
to be useless. It says what the proposal said and I
don't know how to improve it.


====================

5.6.6 Data Member Entries

"For a location description, the implicit push on the DWARF
expression stack of the base address of the containing
construct is equivalent to execution of the
DW_OP_push_object_address operation (see Section 2.4.1.3);
DW_OP_push_object_address therefore is not needed at the
beginning of a location expression for a data member. The
result of the evaluation is a location-- either an address or
the name of a register, not an offset to the member."


The "name of a register" is what concerns me.

On first reading I was puzzled by it.

The result is a register identifier.

I don't know what to say about this, as on typing this,
I wonder what bothered me when I noted the 'problem'!


================
5.12
"3. Evaluate the DW_AT_use_location expression for the type of mbr_ptr."

This sentence puzzles me. What does 
	'for the type of mbr_ptr' mean?

=============
6.1.1 Lookup By Name
"This header is followed by a variable number of offset/name
pairs. Each pair consists of the section offset from the
beginning of the compilation unit corresponding to the current
set to the debugging information entry for the given object,
followed by a null-terminated character string representing the
name of the object as given by the DW_AT_name attribute of the
referenced debugging entry. Each set of names is terminated by
zero "

That last sentence should perhaps be more wordy :-)
  Each set of names is terminated by a section-offset field
  containing zero.

Or something.


==================
7.5.4 Attribute Encodings
"The forms DW_FORM_data4 and DW_FORM_data8 continue to be usable
as constants when this does not conflict with their possible
role as pointers. Even without them, there are no limitations
in the value of constants that can be represented using the
other forms in class constant (consider especially
DW_FORM_sdata and DW_FORM_udata)."

That last should perhaps mention DW_FORM_block<n>
as such is appropriate for floating point and other non-integer
constants.


=======================
"Appendix A -- Attributes by T ag Value"

The Tag word has some, well, odd spacing between characters.
Don't know if that is intentional or something done to you.

========================

"Appendix C - Variable Length Data: Encoding/Decoding"

Another oddity in the 'Length' word character spacing.

And the first algorigthm has no  indentation, making
it hard to read.


===============
D.2 Aggregate Examples
"Having acquired all the necessary data, perform the indexing
operation in the usual manner which has nothing to do with any
of the attributes involved up to now. Those just provides the
actual uses used in the indexing step."


The last sentence could possibly be:
Those just provide the actual values used in the indexing step.


9$: DW_TAG_member
	DW_AT_name("VEC")
		DW_AT_type(reference to array type at 8$)
		DW_AT_data_member_location(machine=
		    DW_OP_lit<n> ! where n == offset(REC2, VEC2)
		    DW_OP_plus)

I suspect this particular entry refers to
	VEC2
and to
		7$
not VEC or 8$. 

========================
more on the examples:

40$: DW_TAG_namespace
	DW_AT_name("Y")
	DW_TAG_imported_declaration // (1) using-declaration
		DW_AT_import(reference to 30$)
	DW_TAG_variable
		DW_AT_name("foo")
		DW_AT_type(reference to 1$)
		DW_AT_location ...
		...

Before this, I suggest a page break, so the stuff following 40$
in the example all falls on one page. Else it's impossible
to really 'get' the indentation as the example crosses a page break.

The stuff before need not be on the same page as the stuff in 40$
and what follows it.


======end


Regards,
David B. Anderson davea@sgi.com danderson@acm.org http://reality.sgi.com/davea/