Blame | Last modification | View Log | RSS feed
<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
$Id$
-->
<book>
<bookinfo>
<title>TDF Diagnostic Specification, Issue 3.0</title>
<corpauthor>The TenDRA Project</corpauthor>
<author>
<firstname>Jeroen</firstname>
<surname>Ruigrok van der Werven</surname>
</author>
<authorinitials>JRvdW</authorinitials>
<pubdate>2004</pubdate>
<copyright>
<year>2004</year>
<year>2005</year>
<holder>The TenDRA Project</holder>
</copyright>
<copyright>
<year>1998</year>
<holder>DERA</holder>
</copyright>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<para>The <acronym>TDF</acronym> diagnostic information is intended to
convey all that information, used by current source level debuggers,
which would conventionally be part of an object file. Any particular
installer will only use those parts of this information which its native
object format can represent.</para>
<para>The version of the diagnostics described here is the first version.
It has only been tested with TDF produced from C programs. There are
known to be certain deficiencies relative to other languages (in
particular to FORTRAN). A later version will correct these
deficiencies. The changes already envisaged are detailed in
<xref linkend="proposed-changes"/>, and would have minimal (if any)
impact on C producers.</para>
<para>The diagnostic system introduces one new type of TDF linkable
entities, and currently adds two new units to the bitstream
representation of TDF.</para>
<para>Much of the actual annotation of procedure bodies is currently done
by reserved <code>TOKEN</code>s, which installers recognize specially.
These <code>TOKEN</code>s are described in
<xref linkend="reserved-diagnostic-tokens"/>.</para>
<para>There is a resemblance between the TDF diagnostic information and
Unix International's <acronym>DWARF</acronym> format.
<acronym>DWARF</acronym> has similar aims to the TDF diagnostics, and
ensuring that complete <acronym>DWARF</acronym> information could be
generated provided a useful check during the development of the TDF
diagnostics. However the TDF diagnostics are intended to be
architecture (and format) neutral. No inference should be made about
any link (present or future) between <acronym>DWARF</acronym> and TDF
diagnostics.</para>
</chapter>
<chapter id="diagnostic-sorts">
<title>Diagnostic SORTs</title>
<para>As a summary of this section:</para>
<itemizedlist>
<listitem>
<para><code>DIAG_TYPE</code>s describe programming language types
(e.g. arrays, structs...). <code>DIAG_TQ</code>s are qualifiers
of <code>DIAG_TYPE</code>s used for attributes like volatile
and const.</para>
</listitem>
<listitem>
<para><code>FILENAME</code>s and <code>SOURCEMARK</code>s describe
source files and locations within them.</para>
</listitem>
<listitem>
<para><code>DIAG_TAG</code>s associate integers with
<code>DIAG_TYPE</code>s. They are used in a similar manner to
normal TDF <code>TAG</code>s, and are held in a (TDF) linkable
unit called a <code>DIAG_TYPE_UNIT</code>.</para>
</listitem>
<listitem>
<para><code>DIAG_UNIT</code>s hold a collection of
<code>DIAG_DESCRIPTOR</code>s, used for information outside
procedure bodies.</para>
</listitem>
</itemizedlist>
<sect1 id="diag_descriptor">
<title>DIAG_DESCRIPTOR</title>
<informaltable frame="none">
<textobject>
<phrase>DIAG_DESCRIPTOR encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Number of encoding bits:</entry>
<entry>2</entry>
</row>
<row>
<entry>Is coding extendable:</entry>
<entry>yes</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para><code>DIAG_DESCRIPTOR</code>s are used to associate names in the
source program with diagnostic items.</para>
<sect2 id="diag_desc_id">
<title>diag_desc_id</title>
<informaltable frame="none">
<textobject>
<phrase>diag_desc_id encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>1</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
src_name: TDFSTRING(k, n)
whence: SOURCEMARK
found_at: EXP POINTER(al)
type: DIAG_TYPE
-> DIAG_DESCRIPTOR
</programlisting>
<para>Generates a descriptor for an identifier (of
<code>DIAG_TYPE</code> <varname>type</varname>), whose source name
was <varname>src_name</varname> from source location
<varname>whence</varname>. The <code>EXP</code>
<varname>found_at</varname> describes how to access the value. Note
that the <code>EXP</code> need not be unique (e.g. FORTRAN
EQUIVALENCE might be implemented this way).</para>
</sect2>
<sect2 id="diag_desc_struct">
<title>diag_desc_struct</title>
<informaltable frame="none">
<textobject>
<phrase>diag_desc_struct encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>2</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
src_name: TDFSTRING(k, n)
whence: SOURCEMARK
new_type: DIAG_TYPE
-> DIAG_DESCRIPTOR
</programlisting>
<para>Generates a descriptor whose source name was
<varname>src_name</varname>. <varname>new_type</varname> must be
either a <code>DIAG_STRUCT</code>, <code>DIAG_UNION</code> or
<code>DIAG_ENUM</code>.</para>
<para><note>This construct is obsolete.</note></para>
</sect2>
<sect2 id="diag_desc_typedef">
<title>diag_desc_typedef</title>
<informaltable frame="none">
<textobject>
<phrase>diag_desc_typedef encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>3</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
src_name: TDFSTRING(k, n)
whence: SOURCEMARK
new_type: DIAG_TYPE
-> DIAG_DESCRIPTOR
</programlisting>
<para>Generates a descriptor for a type <varname>new_type</varname>
whose source name was <varname>src_name</varname>. Note that
<varname>diag_desc_typedef</varname> is used for associating a name
with a type, rather than for any name given in the initial
description of the type (e.g. in C this is used for typedef, not for
struct/union/enum tags).</para>
</sect2>
</sect1>
<sect1 id="diag_unit">
<title>DIAG_UNIT</title>
<informaltable frame="none">
<textobject>
<phrase>DIAG_UNIT encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Number of encoding bits:</entry>
<entry>0</entry>
</row>
<row>
<entry>Is coding extendable:</entry>
<entry>no</entry>
</row>
<row>
<entry>Unit identification:</entry>
<entry><varname>diagdef</varname></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>A <code>DIAG_UNIT</code> is a TDF unit containing
<code>DIAG_DESCRIPTOR</code>s. A <code>DIAG_UNIT</code> is used to
contain descriptions of items outside procedure bodies (e.g. global
variables, global type definitions).</para>
<sect2 id="build_diag_unit">
<title>build_diag_unit</title>
<informaltable frame="none">
<textobject>
<phrase>build_diag_unit encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>0</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
no_labels: TDFINT
descriptors: SLIST(DIAG_DESCRIPTOR)
-> DIAG_UNIT
</programlisting>
<para>Create a <code>DIAG_UNIT</code> containing
<code>DIAG_DESCRIPTOR</code>s. <varname>no_labels</varname> is the
number of local labels used in <varname>descriptors</varname> (for
conditionals).</para>
</sect2>
</sect1>
<sect1 id="diag_tag">
<title>DIAG_TAG</title>
<informaltable frame="none">
<textobject>
<phrase>DIAG_TAG encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Number of encoding bits:</entry>
<entry>1</entry>
</row>
<row>
<entry>Is coding extendable:</entry>
<entry>yes</entry>
</row>
<row>
<entry>Linkable entity identification:</entry>
<entry><varname>diagtag</varname></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para><code>DIAG_TAG</code>s are used inter alia to break cyclic
diagnostic types. They are (TDF) linkable entities. A
<code>DIAG_TAG</code> is made from a number, and used in
<varname>use_diag_tag</varname> to obtain the <code>DIAG_TYPE</code>
associated with that number by
<varname>make_diag_tagdef</varname>.</para>
<sect2 id="make_diag_tag">
<title>make_diag_tag</title>
<informaltable frame="none">
<textobject>
<phrase>make_diag_tag encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>1</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
num: TDFINT
-> DIAG_TAG
</programlisting>
<para>Create a <code>DIAG_TAG</code> from
<varname>num</varname>.</para>
</sect2>
</sect1>
<sect1 id="diag_tagder">
<title>DIAG_TAGDEF</title>
<informaltable frame="none">
<textobject>
<phrase>DIAG_TAGDEF encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Number of encoding bits:</entry>
<entry>1</entry>
</row>
<row>
<entry>Is coding extendable:</entry>
<entry>yes</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para><code>DIAG_TAGDEF</code>s associate <code>DIAG_TAG</code>s with
<code>DIAG_TYPE</code> s.</para>
<sect2 id="make_diag_tagdef">
<title>make_diag_tagdef</title>
<informaltable frame="none">
<textobject>
<phrase>make_diag_tagdef encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>1</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
tno: TDFINT
dtype: DIAG_TYPE
-> DIAG_TAGDEF
</programlisting>
<para>Associates tag number <varname>tno</varname> with
<varname>dtype</varname>.
</para>
</sect2>
</sect1>
<sect1 id="diag_type_unit">
<title>DIAG_TYPE_UNIT</title>
<informaltable frame="none">
<textobject>
<phrase>DIAG_TYPE_UNIT encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Number of encoding bits:</entry>
<entry>0</entry>
</row>
<row>
<entry>Is coding extendable:</entry>
<entry>no</entry>
</row>
<row>
<entry>Unit identification:</entry>
<entry><varname>diagtype</varname></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>A <code>DIAG_TYPE_UNIT</code> is a TDF unit containing
<code>DIAG_TAGDEF</code>s.</para>
<sect2 id="build_diagtype_unit">
<title>build_diagtype_unit</title>
<informaltable frame="none">
<textobject>
<phrase>build_diagtype_unit encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>0</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
no_labels: TDFINT
tagdefs: SLIST(DIAG_TAGDEF)
-> DIAG_TYPEUNIT
</programlisting>
<para>Create a <code>DIAG_TYPEUNIT</code> containing
<code>DIAG_TAGDEF</code>s. <varname>no_labels</varname> is the number
of local labels used in <varname>tagdefs</varname> (for
conditionals).</para>
</sect2>
</sect1>
<sect1 id="diag_type">
<title>DIAG_TYPE</title>
<informaltable frame="none">
<textobject>
<phrase>DIAG_TYPE encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Sortname:</entry>
<entry><varname>foreign_sort("diag_type")</varname></entry>
</row>
<row>
<entry>Number of encoding bits:</entry>
<entry>4</entry>
</row>
<row>
<entry>Is coding extendable:</entry>
<entry>yes</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para><code>DIAG_TYPE</code>s are used to provide diagnostic
information about data types.</para>
<sect2 id="diag_type_apply_token">
<title>diag_type_apply_token</title>
<informaltable frame="none">
<textobject>
<phrase>diag_type_apply_token encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>1</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
token_value: TOKEN
token_args: BITSTREAM
-> DIAG_TYPE
</programlisting>
<para>The token is applied to the arguments to give a
<code>DIAG_TYPE</code>. If there is a definition for
<varname>token_value</varname> in the <code>CAPSULE</code> then
<varname>token_args</varname> is a <code>BITSTREAM</code> encoding of
the <code>SORT</code>s of its parameters, in the order
specified.</para>
</sect2>
<sect2 id="diag_array">
<title>diag_array</title>
<informaltable frame="none">
<textobject>
<phrase>diag_array encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>2</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
element_type: DIAG_TYPE
stride: EXP OFFSET(p,p)
lower_bound: EXP INTEGER(v)
upper_bound: EXP INTEGER(v)
index_type: DIAG_TYPE
-> DIAG_TYPE
</programlisting>
<para>An array of <varname>element_type</varname> objects.
<varname>stride</varname> is the <code>OFFSET</code> between elements
of the array (i.e. <varname>p</varname> is described by
<varname>element_type</varname>). The bounds are in general not
runtime constants, hence the values are <code>EXP</code>s (not say
<code>SIGNED_NAT</code>). The <code>VARIETY</code>
<varname>v</varname> is described by <varname>index_type</varname>. As
in TDF there is no multi-dimensional array primitive.</para>
</sect2>
<sect2 id="diag_bitfield">
<title>diag_bitfield</title>
<informaltable frame="none">
<textobject>
<phrase>diag_bitfield encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>3</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
type: DIAG_TYPE
number_of_bits: NAT
-> DIAG_TYPE
</programlisting>
<para>Describes <varname>number_of_bits</varname>, which when extracted
will have <code>DIAG_TYPE</code> <varname>type</varname>.</para>
</sect2>
<sect2 id="diag_enum">
<title>diag_enum</title>
<informaltable frame="none">
<textobject>
<phrase>diag_enum encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>4</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
base_type: DIAG_TYPE
enum_name: TDFSTRING(k, n)
values: LIST(ENUM_VALUES)
-> DIAG_TYPE
</programlisting>
<para>An enumeration to be stored in an object of type
<varname>base_type</varname>. If <varname>enum_name</varname> is a
string contining zero characters this signifies no source tag.</para>
</sect2>
<sect2 id="diag_floating_variety">
<title>diag_floating_variety</title>
<informaltable frame="none">
<textobject>
<phrase>diag_floating_variety encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>5</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
var: FLOATING_VARIETY
-> DIAG_TYPE
</programlisting>
<para>Creates a <code>DIAG_TYPE</code> to describe an
<code>FLOATING_VARIETY</code> <varname>var</varname>.</para>
</sect2>
<sect2 id="diag_loc">
<title>diag_loc</title>
<informaltable frame="none">
<textobject>
<phrase>diag_loc encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>6</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
object: DIAG_TYPE
qualifier: DIAG_TQ
-> DIAG_TYPE
</programlisting>
<para>Records the existence of an item of <code>DIAG_TYPE</code>
<varname>object</varname>, qualified by <varname>qualifier</varname>.
<varname>diag_loc</varname> is used for variables (which may of course
not actually occupy a memory location).</para>
</sect2>
<sect2 id="diag_proc">
<title>diag_proc</title>
<informaltable frame="none">
<textobject>
<phrase>diag_proc encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>7</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
params: LIST(DIAG_TYPE)
optional_args: BOOL
result_type: DIAG_TYPE
-> DIAG_TYPE
</programlisting>
<para>Describes a procedure taking <varname>n</varname> parameters.
<varname>optional_args</varname> is true if and only if the
<varname>make_proc</varname> which this <varname>diag_proc</varname>
describes had <varname>vartag</varname> present.</para>
</sect2>
<sect2 id="diag_ptr">
<title>diag_ptr</title>
<informaltable frame="none">
<textobject>
<phrase>diag_ptr encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>8</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
object: DIAG_TYPE
qualifier: DIAG_TQ
-> DIAG_TYPE
</programlisting>
<para>Describes a pointer to an object of <code>DIAG_TYPE</code>
<varname>object</varname>. The <code>DIAG_TQ</code> qualifier
<varname>qualifier</varname> qualifies the pointer, not the object
pointed to.</para>
</sect2>
<sect2 id="diag_struct">
<title>diag_struct</title>
<informaltable frame="none">
<textobject>
<phrase>diag_struct encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>9</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
tdf_shape: SHAPE
src_name: TDFSTRING(k, n)
fields: LIST(DIAG_FIELD)
-> DIAG_TYPE
</programlisting>
<para>Describes a structure. If <varname>src_name</varname> is a string
contining zero characters this signifies no source tag for the whole
structure. <varname>tdf_shape</varname> allows the total size to be
computed.</para>
</sect2>
<sect2 id="diag_type_null">
<title>diag_type_null</title>
<informaltable frame="none">
<textobject>
<phrase>diag_type_null encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>10</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
-> DIAG_TYPE
</programlisting>
<para>A null <code>DIAG_TYPE</code>.</para>
</sect2>
<sect2 id="diag_union">
<title>diag_union</title>
<informaltable frame="none">
<textobject>
<phrase>diag_union encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>11</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
tdf_shape: SHAPE
src_name: TDFSTRING(k, n)
fields: LIST(DIAG_FIELD)
-> DIAG_TYPE
</programlisting>
<para>Describes a union. If <varname>src_name</varname> is a string
contining zero characters this signifies no source tag for the whole
union. <varname>tdf_shape</varname> allows the total size to be
computed.</para>
</sect2>
<sect2 id="diag_variety">
<title>diag_variety</title>
<informaltable frame="none">
<textobject>
<phrase>diag_variety encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>12</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
var: VARIETY
-> DIAG_TYPE
</programlisting>
<para>Creates a <code>DIAG_TYPE</code> to describe an integer
<code>VARIETY</code> <varname>var</varname>.</para>
</sect2>
<sect2 id="use_diag_tag">
<title>use_diag_tag</title>
<informaltable frame="none">
<textobject>
<phrase>use_diag_tag encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>13</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
dtag: DIAG_TAG
-> DIAG_TYPE
</programlisting>
<para>Obtains the <code>DIAG_TYPE</code> associated with
<code>DIAG_TAG</code> <varname>dtag</varname>.</para>
</sect2>
</sect1>
<sect1 id="enum_values">
<title>ENUM_VALUES</title>
<informaltable frame="none">
<textobject>
<phrase>ENUM_VALUES encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Number of encoding bits:</entry>
<entry>0</entry>
</row>
<row>
<entry>Is coding extendable:</entry>
<entry>no</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect2 id="make_enum_values_list">
<title>make_enum_values_list</title>
<informaltable frame="none">
<textobject>
<phrase>make_enum_values_list encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>0</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
value: EXP <varname>sh</varname>
src_name: TDFSTRING(k, n)
-> ENUM_VALUES
</programlisting>
<para><code>ENUM_VALUES</code> describe elements of an enumerated type.
<varname>src_name</varname> is the source language name.
<varname>value</varname> evaluates to a value of <code>SHAPE</code>
<varname>sh</varname>. Note that all members of a
<code>LIST(ENUM_VALUES</code>) must have the same
<varname>sh</varname>.</para>
</sect2>
</sect1>
<sect1 id="diag_field">
<title>DIAG_FIELD</title>
<informaltable frame="none">
<textobject>
<phrase>DIAG_FIELD encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Number of encoding bits:</entry>
<entry>0</entry>
</row>
<row>
<entry>Is coding extendable:</entry>
<entry>no</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect2 id="make_diag_field">
<title>make_diag_field</title>
<informaltable frame="none">
<textobject>
<phrase>make_diag_field encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>0</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
field_name: TDFSTRING(k, n)
found_at: EXP OFFSET(ALIGNMENT whole, ALIGNMENT this_field)
field_type: DIAG_TYPE
-> DIAG_FIELD
</programlisting>
<para><code>DIAG_FIELD</code>s describe one field of a structure or
union. <varname>field_name</varname> is the source language name.
<varname>found_at</varname> is the <code>OFFSET</code> between
<varname>whole</varname> (the enclosing structure or union), and this
field (<varname>this_field</varname>). <varname>field_type</varname>
is the <code>DIAG_TYPE</code> of the field.</para>
</sect2>
</sect1>
<sect1 id="diag_tq">
<title>DIAG_TQ</title>
<informaltable frame="none">
<textobject>
<phrase>DIAG_TQ encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Number of encoding bits:</entry>
<entry>2</entry>
</row>
<row>
<entry>Is coding extendable:</entry>
<entry>yes</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para><code>DIAG_TQ</code>s are type qualifiers, used to qualify
<code>DIAG_TYPE</code>s. A <code>DIAG_TQ</code> is constructed from
<type>diag_tq_null</type> and the various <type>add_diag_XXX</type>
operations.</para>
<sect2 id="add_diag_const">
<title>add_diag_const</title>
<informaltable frame="none">
<textobject>
<phrase>add_diag_const encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>1</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
<varname>qual</varname>: DIAG_TQ
-> DIAG_TQ
</programlisting>
<para>Marks a <code>DIAG_TQ</code> type qualifier as being
<token>const</token> in the ANSI C sense.</para>
</sect2>
<sect2 id="add_diag_volatile">
<title>add_diag_volatile</title>
<informaltable frame="none">
<textobject>
<phrase>add_diag_volatile encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>2</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
<varname>qual</varname>: DIAG_TQ
-> DIAG_TQ
</programlisting>
<para>Marks a <code>DIAG_TQ</code> type qualifier as being
<token>volatile</token> in the ANSI C sense.</para>
</sect2>
<sect2 id="diag_tq_null">
<title>diag_tq_null</title>
<informaltable frame="none">
<textobject>
<phrase>diag_tq_null encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>3</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
-> DIAG_TQ
</programlisting>
<para>Create a null <code>DIAG_TQ</code> type qualifier.</para>
</sect2>
</sect1>
<sect1 id="filename">
<title>FILENAME</title>
<informaltable frame="none">
<textobject>
<phrase>FILENAME encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Sortname:</entry>
<entry><function>foreign_sort("~diag_file")</function></entry>
</row>
<row>
<entry>Number of encoding bits:</entry>
<entry>2</entry>
</row>
<row>
<entry>Is coding extendable:</entry>
<entry>yes</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para><code>FILENAME</code> record details of source files used in
producing a <code>CAPSULE</code>. They can be tokenised for
abbreviation.</para>
<sect2 id="filename_apply_token">
<title>filename_apply_token</title>
<informaltable frame="none">
<textobject>
<phrase>filename_apply_token encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>1</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
<varname>token_value</varname>: TOKEN
<varname>token_args</varname>: BITSTREAM
-> FILENAME
</programlisting>
<para>The token is applied to the arguments to give a
<code>FILENAME</code>. If there is a definition for
<varname>token_value</varname> in the <code>CAPSULE</code> then
<varname>token_args</varname> is a <code>BITSTREAM</code> encoding of
the <code>SORT</code>s of its parameters, in the order
specified.</para>
</sect2>
<sect2 id="make_filename">
<title>make_filename</title>
<informaltable frame="none">
<textobject>
<phrase>make_filename</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>2</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
<varname>date</varname>: NAT
<varname>machine</varname>: TDFSTRING(k1, n1)
<varname>file</varname>: TDFSTRING(k2, n2)
-> FILENAME
</programlisting>
<para>Create a <code>FILENAME</code> for file <varname>file</varname>,
dated <varname>date</varname> (a UNIX timestamp; seconds since 1 Jan
1970) on machine <varname>machine</varname>.</para>
</sect2>
</sect1>
<sect1 id="sourcemark">
<title>SOURCEMARK</title>
<informaltable frame="none">
<textobject>
<phrase>SOURCEMARK encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Number of encoding bits:</entry>
<entry>1</entry>
</row>
<row>
<entry>Is coding extendable:</entry>
<entry>yes</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>A <code>SOURCEMARK</code> records a location in the source
program. Present <code>SOURCEMARK</code>s assume that a location can
be described by one or two numbers within a
<code>FILENAME</code>.</para>
<sect2 id="make_sourcemark">
<title>make_sourcemark</title>
<informaltable frame="none">
<textobject>
<phrase>make_sourcemark encoding</phrase>
</textobject>
<tgroup cols="2">
<tbody>
<row>
<entry>Encoding number:</entry>
<entry>1</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<programlisting>
<varname>file</varname>: FILENAME
<varname>line_no</varname>: NAT
<varname>char_offset</varname>: NAT
-> SOURCEMARK
</programlisting>
<para>Create a <code>SOURCEMARK</code> referencing the
<varname>char_offset</varname>'th character on line
<varname>line_no</varname> in file <varname> file</varname>.</para>
<para><varname>char_offset</varname> is counted from 1, 0 meaning that
no character offset is available.</para>
</sect2>
</sect1>
</chapter>
<chapter id="reserved-diagnostic-tokens">
<title>Reserved diagnostic TOKENs</title>
<para>Reserved <code>TOKEN</code>s were used for diagnostic extensions
to <code>EXP</code>s, to avoid adding new constructs the contents of
an existing <code>UNIT</code>. All other parts of the diagnostic
system occur in other <code>UNIT</code>s.</para>
<sect1 id="exp_to_source">
<title>~exp_to_source</title>
<programlisting>
<varname>body</varname>: EXP sh
<varname>from</varname>: SOURCEMARK
<varname>to</varname>: SOURCEMARK
-> EXP sh
</programlisting>
<para>Records that the <code>EXP</code> <varname>body</varname> arose
from translating program between <code>SOURCEMARK</code>
<varname>from</varname> and <code>SOURCEMARK</code>
<varname>to</varname> (inclusive). </para>
</sect1>
<sect1 id="diag_id_source">
<title>~diag_id_source</title>
<programlisting>
<varname>body</varname>: EXP sh
<varname>name</varname>: TDFSTRING(k, n)
<varname>access</varname>: EXP POINTER(al)
<varname>type</varname>: DIAG_TYPE
-> EXP sh
</programlisting>
<para>Within the <code>EXP</code> <varname>body</varname> a variable
named <varname> name</varname> of <code>DIAG_TYPE</code>
<varname>type</varname> can be accessed via the <code>EXP</code>
<varname>access</varname>.</para>
</sect1>
<sect1 id="diag_type_scope">
<title>~diag_type_scope</title>
<programlisting>
<varname>body</varname>: EXP sh
<varname>name</varname>: TDFSTRING(k, n)
<varname>type</varname>: DIAG_TYPE
-> EXP sh
</programlisting>
<para>Within the <code>EXP</code> <varname>body</varname> a source
language type named <varname>name</varname> of <code>DIAG_TYPE</code>
<varname>type</varname> is valid.</para>
</sect1>
<sect1 id="diag_tag_scope">
<title>~diag_tag_scope</title>
<programlisting>
<varname>body</varname>: EXP sh
<varname>name</varname>: TDFSTRING(k, n)
<varname>type</varname>: DIAG_TYPE
-> EXP sh
</programlisting>
<para><note>This <code>TOKEN</code> is obsolete.</note></para>
</sect1>
</chapter>
<chapter id="proposed-changes">
<title>Proposed changes</title>
<para>It is thought likely that the new TDF entities described above
will eventually be incorporated into the main TDF
specification.</para>
<para>In several places below the absence of "standardised methods" is
noted. These are cases where TDF can express some operation in several
ways, and the installer cannot be expected to spot all of them and
generate new diagnostic info.</para>
<sect1 id="missing-features">
<title>Language features currently missing</title>
<para>The following sections list some of the language features known
not to be supported by the current specification. It is not intended
to be exhaustive.</para>
<sect2 id="data-types">
<title>Data types</title>
<itemizedlist>
<listitem>Complex numbers.</listitem>
<listitem>Fortran alternate <token>RETURN</token>s.</listitem>
</itemizedlist>
</sect2>
<sect2 id="cplusplus-requirements">
<title>C++ requirements</title>
<itemizedlist>
<listitem>
<para>The <type>reference</type> type is not yet present.</para>
</listitem>
<listitem>
<para>The accessibility attributes (<token>public</token>,
<token>private</token> and <token>protected</token>) are not yet
present.</para>
</listitem>
<listitem>
<para>No <token>member</token> function information, and no
specification of how to deal with name mangling. Pointer to
<token>member</token> may need special recognition.</para>
</listitem>
<listitem>No operations for describing <token>class</token>es and
inheritance.</listitem>
</itemizedlist>
</sect2>
<sect2 id="fortran-requirements">
<title>FORTRAN requirements</title>
<itemizedlist>
<listitem>Main <token>PROGRAM</token> attribute missing.</listitem>
<listitem>
<para>Fortran optional parameters may need special
treatment</para>
</listitem>
<listitem>Use of <token>COMMON</token> is not explicit in
TDF.</listitem>
<listitem>Fortran77 etc. has a string type, which could be
implemented in several ways (other languages need this, but
they may differ on the same machine).</listitem>
</itemizedlist>
</sect2>
<sect2 id="other-requirements">
<title>Other requirements</title>
<itemizedlist>
<listitem>No standardised method for describing static link info.
TDF can express such programs, but the link could be stored in
several ways.</listitem>
<listitem>No standardised method for describing arrays with either
non-constant bounds, and/or where the bounds are present in the
running image. (The <varname>upper_bound</varname> and
<varname>lower_bound</varname> <code>EXP</code>s are sufficiently
powerful, but needs some rules)</listitem>
<listitem>No way to name a lexical block.</listitem>
<listitem>Formal parameters with default values cannot have the
default made visible.</listitem>
<listitem>Variables which are constant, and have been inlined
everywhere may be a problem.</listitem>
<listitem>No standardised method of describing the discriminant part
of a discriminated union (in TDF probably represented by a
struct containing the discriminant and the union).</listitem>
<listitem>The distinction between ANSI prototyped and non-prototyped
functions (this is a real problem for functions taking
<type>float</type>)</listitem>
<listitem>No standardised method for PASCAL sets.</listitem>
<listitem>No standardised method for subrange types.</listitem>
<listitem>PASCAL and Modula have a <token>WITH</token> construct to
change semantics of record field lookup. No standardised method
for documenting this.</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="further-abstraction">
<title>Areas for further abstraction</title>
<sect2 id="compilation-related">
<title>Compilation related</title>
<para>How a running program has been created from several components
is of interest when debugging. The present system cannot record
all details of how a program has been created. In particular there
is no indication of the source language of any piece of TDF, nor
of the full name of any of the source files.</para>
</sect2>
<sect2 id="c-related">
<title>C related</title>
<para>At present there is no defined link between the fundamental C
types and the <code>VARIETY</code>s etc. used for them. Present
installers for 32 bit machines cannot distinguish between
<type>int</type> and <type>long</type> when generating diagnostics,
other than by means of the standard token names which form part of
the C producer language interface.</para>
</sect2>
<sect2 id="naming-types">
<title>Naming of types</title>
<para>At present various <code>DIAG_TYPE</code>s have names, some
don't. I suspect we should make a separate
<function>is_named</function> operation and remove the other
names.</para>
</sect2>
</sect1>
<sect1 id="andf-de">
<title>Postscript - ANDF-DE</title>
<para>As this section makes clear, the TDF Diagnostic Specification
was only ever really intended to deal with C. As of 1997, a more
extensive diagnostic extension to TDF, ANDF-DE, is under development
by DDC-I. This has been designed with the requirements of C, C++ and
Ada in mind. It is intended that eventually ANDF-DE will be
incorporated into the TDF specification, and the diagnostic format
described here will be denegrated.</para>
</sect1>
</chapter>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="../common/colophon-dera.xml"/>
</book>