$TenDRA: book.xml 2447 2006-03-23
21:15:51Z verm $
Copyright © 2002, 2003, 2004, 2005, 2006 TenDRA Documentation Team
Copyright © 1997, 1998 Defence Evaluation and Research Agency (DERA)
Extensions to this document from the original TenDRA-4.1.2-doc.tar.gz source distribution are covered by the BSDL, while all prior modifications remain under the Crown Copyright.
Berkeley Systems Design License
Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.
Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY THE TENDRA DOCUMENTATION TEAM "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE TENDRA DOCUMENTATION TEAM BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Crown Copyright (c) 1997, 1998
This TenDRA(r) Computer Program is subject to Copyright owned by the United Kingdom Secretary of State for Defence acting through the Defence Evaluation and Research Agency (DERA). It is made available to Recipients with a royalty-free licence for its use, reproduction, transfer to other parties and amendment for any purpose not excluding product development provided that any such use et cetera shall be deemed to be acceptance of the following conditions:
Its Recipients shall ensure that this Notice is reproduced upon any copies or amended versions of it;
Any amended version of it shall be clearly marked to show both the nature of and the organisation responsible for the relevant amendment or amendments;
Its onward transfer from a recipient to another party shall be deemed to be that party's acceptance of these conditions;
DERA gives no warranty or assurance as to its quality or suitability for any purpose and DERA accepts no liability whatsoever in relation to any use to which it may be put.
This document was generated on 2006-09-07 16:03:58
Abstract
Please email us at <docs@ten15.org> if you see any errors or
omissions.
Table of Contents
The TDF 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.
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 Chapter 3, Proposed changes , and would have minimal (if any) impact on C producers.
The diagnostic system introduces one new type of TDF linkable entities, and currently adds two new units to the bitstream representation of TDF.
Much of the actual annotation of procedure bodies is currently done by
reserved TOKENs, which installers recognize
specially. These TOKENs are described in Chapter 2, Reserved
diagnostic TOKENs .
There is a resemblance between the TDF diagnostic information and Unix International's DWARF format. DWARF has similar aims to the TDF diagnostics, and ensuring that complete DWARF 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 DWARF and TDF diagnostics.
Table of Contents
DIAG_TYPEs describe programming language types
(e.g. arrays, structs...). DIAG_TQs are qualifiers
of DIAG_TYPE s used for attributes like volatile
and const.
FILENAMEs and SOURCEMARKs describe source files and locations within
them.
DIAG_TAGs associate integers with DIAG_TYPEs. They are used in a similar manner to normal TDF
TAGs, and are held in a (TDF) linkable unit called
a DIAG_TYPE_UNIT.
DIAG_UNITs hold a collection of DIAG_DESCRIPTORs, used for information outside procedure
bodies.
| Number of encoding bits: | 2 |
| Is coding extendable: | yes |
DIAG_DESCRIPTORs are used to associate names in
the source program with diagnostic items.
| Encoding number: | 1 |
src_name: TDFSTRING(k, n)
whence: SOURCEMARK
found_at: EXP POINTER(al)
type: DIAG_TYPE
-> DIAG_DESCRIPTOR
Generates a descriptor for an identifier (of DIAG_TYPE type), whose
source name was src_name from source
location whence. The EXP found_at describes
how to access the value. Note that the EXP need
not be unique (e.g. FORTRAN EQUIVALENCE might be implemented this way).
| Encoding number: | 2 |
src_name: TDFSTRING(k, n)
whence: SOURCEMARK
new_type: DIAG_TYPE
-> DIAG_DESCRIPTOR
Generates a descriptor whose source name was src_name. new_type must be either a DIAG_STRUCT, DIAG_UNION or DIAG_ENUM.
This construct is obsolete.
| Encoding number: | 3 |
src_name: TDFSTRING(k, n)
whence: SOURCEMARK
new_type: DIAG_TYPE
-> DIAG_DESCRIPTOR
Generates a descriptor for a type new_type whose source name was src_name. Note that diag_desc_typedef 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).
| Number of encoding bits: | 0 |
| Is coding extendable: | 0 |
| Unit identification: | diagdef |
A DIAG_UNIT is a TDF unit containing DIAG_DESCRIPTORs. A DIAG_UNIT is used to contain descriptions of items outside
procedure bodies (e.g. global variables, global type definitions).
| Number of encoding bits: | 1 |
| Is coding extendable: | yes |
| Linkable entity identification: | diagtag |
DIAG_TAGs are used inter alia to break cyclic diagnostic types. They
are (TDF) linkable entities. A DIAG_TAG is made
from a number, and used in use_diag_tag
to obtain the DIAG_TYPE associated with that
number by make_diag_tagdef.
| Number of encoding bits: | 1 |
| Is coding extendable: | yes |
DIAG_TAGDEFs associate DIAG_TAGs with DIAG_TYPE s.
| Number of encoding bits: | 0 |
| Is coding extendable: | no |
| Unit identification: | diagtype |
A DIAG_TYPE_UNIT is a TDF unit containing DIAG_TAGDEFs.
| Number of encoding bits: | 4 |
| Is coding extendable: | yes |
| Sortname: | foreign_sort("diag_type") |
DIAG_TYPEs are used to provide diagnostic
information about data types.
| Encoding number: | 1 |
token_value: TOKEN
token_args: BITSTREAM
-> DIAG_TYPE
The token is applied to the arguments to give a DIAG_TYPE. If there is a definition for token_value in the CAPSULE then token_args
is a BITSTREAM encoding of the SORTs of its parameters, in the order specified.
| Encoding number: | 2 |
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
An array of element_type objects.
stride is the OFFSET between elements of the array (i.e. p is described by element_type). The bounds are in general not runtime
constants, hence the values are EXPs (not say
SIGNED_NAT). The VARIETY v is described
by index_type. As in TDF there is no
multi-dimensional array primitive.
| Encoding number: | 3 |
type: DIAG_TYPE
number_of_bits: NAT
-> DIAG_TYPE
Describes number_of_bits, which when
extracted will have DIAG_TYPE type.
| Encoding number: | 4 |
base_type: DIAG_TYPE
enum_name: TDFSTRING(k, n)
values: LIST(ENUM_VALUES)
-> DIAG_TYPE
An enumeration to be stored in an object of type base_type. If enum_name is a string containing zero characters this signifies no source tag.
| Encoding number: | 5 |
var: FLOATING_VARIETY
-> DIAG_TYPE
Creates a DIAG_TYPE to describe an FLOATING_VARIETY var.
| Encoding number: | 6 |
object: DIAG_TYPE
qualifier: DIAG_TQ
-> DIAG_TYPE
Records the existence of an item of DIAG_TYPE
object, qualified by qualifier. diag_loc is used for variables (which may of course
not actually occupy a memory location).
| Encoding number: | 7 |
params: LIST(DIAG_TYPE)
optional_args: BOOL
result_type: DIAG_TYPE
-> DIAG_TYPE
Describes a procedure taking n parameters. optional_args is true if and only if the make_proc which this diag_proc describes had vartag present.
| Encoding number: | 8 |
object: DIAG_TYPE
qualifier: DIAG_TQ
-> DIAG_TYPE
Describes a pointer to an object of DIAG_TYPE
object. The DIAG_TQ qualifier qualifier qualifies the pointer, not the object
pointed to.
| Encoding number: | 9 |
tdf_shape: SHAPE
src_name: TDFSTRING(k, n)
fields: LIST(DIAG_FIELD)
-> DIAG_TYPE
Describes a structure. If src_name is a string containing zero characters this signifies no source tag for the whole structure. tdf_shape allows the total size to be computed.
| Encoding number: | 11 |
tdf_shape: SHAPE
src_name: TDFSTRING(k, n)
fields: LIST(DIAG_FIELD)
-> DIAG_TYPE
Describes a union. If src_name is a string containing zero characters this signifies no source tag for the whole union. tdf_shape allows the total size to be computed.
| Encoding number: | 12 |
var: VARIETY
-> DIAG_TYPE
Creates a DIAG_TYPE to describe an integer
VARIETY var.
| Number of encoding bits: | 0 |
| Is coding extendable: | no |
| Encoding number: | 0 |
value: EXP sh
src_name: TDFSTRING(k, n)
-> ENUM_VALUES
ENUM_VALUES describe elements of an enumerated
type. src_name is the source language
name. value evaluates to a value of
SHAPE sh.
Note that all members of a LIST(ENUM_VALUES) must
have the same sh.
| Number of encoding bits: | 0 |
| Is coding extendable: | no |
| Encoding number: | 0 |
field_name: TDFSTRING(k, n)
found_at: EXP OFFSET( ALIGNMENT whole, ALIGNMENT this_field )
field_type: DIAG_TYPE
-> DIAG_FIELD
DIAG_FIELDs describe one field of a structure
or union. field_name is the source
language name. found_at is the OFFSET between whole (the enclosing structure or union), and this
field (this_field). field_type is the DIAG_TYPE of the field.
| Number of encoding bits: | 2 |
| Is coding extendable: | yes |
DIAG_TQs are type qualifiers, used to qualify
DIAG_TYPE s. A DIAG_TQ is constructed from diag_tq_null and the various add_diag_XXX operations.
| Encoding number: | 1 |
qual: DIAG_TQ
-> DIAG_TQ
Marks a DIAG_TQ type qualifier as being const in the ANSI C sense.
| Encoding number: | 2 |
qual: DIAG_TQ
-> DIAG_TQ
Marks a DIAG_TQ type qualifier as being volatile in the ANSI C sense.
| Number of encoding bits: | 2 |
| Is coding extendable: | yes |
| Sortname: | foreign_sort("~diag_file") |
FILENAME record details of source files used in
producing a CAPSULE. They can be tokenised for
abbreviation.
| Encoding number: | 1 |
token_value: TOKEN
token_args: BITSTREAM
-> FILENAME
The token is applied to the arguments to give a FILENAME. If there is a definition for token_value in the CAPSULE then token_args
is a BITSTREAM encoding of the SORTs of its parameters, in the order specified.
| Number of encoding bits: | 1 |
| Is coding extendable: | yes |
A SOURCEMARK records a location in the source
program. Present SOURCEMARKs assume that a
location can be described by one or two numbers within a FILENAME.
Table of Contents
Reserved TOKENs were used for diagnostic
extensions to EXPs, to avoid adding new constructs
the contents of an existing UNIT. All other parts
of the diagnostic system occur in other UNITs.
body: EXP sh from: SOURCEMARK to: SOURCEMARK -> EXP sh
Records that the EXP body arose from translating program between SOURCEMARK from
and SOURCEMARK to (inclusive).
body: EXP sh
name: TDFSTRING(k, n)
access: EXP POINTER(al)
type: DIAG_TYPE
-> EXP sh
Within the EXP body a variable named name of DIAG_TYPE type can be accessed via the EXP access.
body: EXP sh
name: TDFSTRING(k, n)
type: DIAG_TYPE
-> EXP sh
Within the EXP body a source language type named name of DIAG_TYPE type is valid.
Table of Contents
It is thought likely that the new TDF entities described above will eventually be incorporated into the main TDF specification.
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.
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.
The reference type is not yet present.
The accessibility attributes (public, private and protected) are not yet present.
No member function information, and no specification of how to deal with name mangling. Pointer to member may need special recognition.
No operations for describing classes and inheritance.
Main PROGRAM attribute missing.
Fortran optional parameters may need special treatment
Use of COMMON is not explicit in TDF.
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).
No standardised method for describing static link info. TDF can express such programs, but the link could be stored in several ways.
No standardised method for describing arrays with either non-constant
bounds, and/or where the bounds are present in the running image. (The upper_bound and lower_bound EXPs are
sufficiently powerful, but needs some rules)
No way to name a lexical block.
Formal parameters with default values cannot have the default made visible.
Variables which are constant, and have been inlined everywhere may be a problem.
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).
The distinction between ANSI prototyped and non-prototyped functions (this is a real problem for functions taking float)
No standardised method for PASCAL sets.
No standardised method for subrange types.
PASCAL and Modula have a WITH construct to change semantics of record field lookup. No standardised method for documenting this.
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.
At present there is no defined link between the fundamental C types and the
VARIETYs etc. used for them. Present installers
for 32 bit machines cannot distinguish between int and long
when generating diagnostics, other than by means of the standard token names
which form part of the C producer language interface.
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.
This chapter describes revisions to this document.
Only major changes are listed in the revision history. Please see http://www.ten15.org/log/trunk/doc/en/diag/book.xml?action=follow_copy&rev=&stop_rev=1&mode=follow_copy&verbose=on for a complete list of changes.
CVS revision numbers are located behind the date in the format rXX
| Revision History | ||
|---|---|---|
| Revision 1.1 | 2004/01/04 r1517 | verm |
| Cross references were fixed. | ||
| Revision 1.0 | 2002/10/07 r42 | verm |
| Converted to SGML from the TenDRA 4.1.2 Documentation. | ||