TDF Diagnostic Specification, Issue 3.0

January 1998

2.1 - DIAG_DESCRIPTOR

2.1.1 - diag_desc_id
2.1.2 - diag_desc_struct
2.1.3 - diag_desc_typedef

2.2 - DIAG_UNIT

2.2.1 - build_diag_unit

2.3 - DIAG_TAG

2.3.1 - make_diag_tag

2.4 - DIAG_TAGDEF

2.4.1 - make_diag_tagdef

2.5 - DIAG_TYPE_UNIT

2.5.1 - build_diagtype_unit

2.6 - DIAG_TYPE

2.6.1 - diag_type_apply_token
2.6.2 - diag_array
2.6.3 - diag_bitfield
2.6.4 - diag_enum
2.6.5 - diag_floating_variety
2.6.6 - diag_loc
2.6.7 - diag_proc
2.6.8 - diag_ptr
2.6.9 - diag_struct
2.6.10 - diag_type_null
2.6.11 - diag_union
2.6.12 - diag_variety
2.6.13 - use_diag_tag

2.7 - ENUM_VALUES

2.7.1 - make_enum_values_list

2.8 - DIAG_FIELD

2.8.1 - make_diag_field

2.9 - DIAG_TQ

2.9.1 - add_diag_const
2.9.2 - add_diag_volatile
2.9.3 - diag_tq_null

2.10 - FILENAME

2.10.1 - filename_apply_token
2.10.2 - make_filename

2.11 - SOURCEMARK

2.11.1 - make_sourcemark

2. Diagnostic SORTs

As a summary of this section

DIAG_TYPEs describe programming language types (e.g. arrays, structs...). DIAG_TQs are qualifiers of DIAG_TYPEs 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.

2.1. DIAG_DESCRIPTOR

Number of encoding bits: 2
Is coding extendable: yes

DIAG_DESCRIPTORs are used to associate names in the source program with diagnostic items.

2.1.1. diag_desc_id

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).

2.1.2. diag_desc_struct

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.

2.1.3. diag_desc_typedef

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).

2.2. DIAG_UNIT

Number of encoding bits: 0
Is coding extendable: no
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).

2.2.1. build_diag_unit

Encoding number: 0

	no_labels:	TDFINT
	descriptors:	SLIST(DIAG_DESCRIPTOR)
		   -> DIAG_UNIT

Create a DIAG_UNIT containing DIAG_DESCRIPTORs. no_labels is the number of local labels used in descriptors (for conditionals).

2.3. DIAG_TAG

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.

2.3.1. make_diag_tag

Encoding number: 1

	num:		TDFINT
		   -> DIAG_TAG

Create a DIAG_TAG from num.

2.4. DIAG_TAGDEF

Number of encoding bits: 1
Is coding extendable: yes

DIAG_TAGDEFs associate DIAG_TAGs with DIAG_TYPEs.

2.4.1. make_diag_tagdef

Encoding number: 1

	tno:		TDFINT
	dtype:		DIAG_TYPE
		   -> DIAG_TAGDEF

Associates tag number tno with dtype.

2.5. DIAG_TYPE_UNIT

Number of encoding bits: 0
Is coding extendable: no
Unit identification: diagtype

A DIAG_TYPE_UNIT is a TDF unit containing DIAG_TAGDEFs.

2.5.1. build_diagtype_unit

Encoding number: 0

	no_labels:	TDFINT
	tagdefs:	SLIST(DIAG_TAGDEF)
		   -> DIAG_TYPEUNIT

Create a DIAG_TYPEUNIT containing DIAG_TAGDEFs. no_labels is the number of local labels used in tagdefs (for conditionals).

2.6. DIAG_TYPE

Sortname: foreign_sort("diag_type")
Number of encoding bits: 4
Is coding extendable: yes

DIAG_TYPEs are used to provide diagnostic information about data types.

2.6.1. diag_type_apply_token

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.

2.6.2. diag_array

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.

2.6.3. diag_bitfield

Encoding number: 3

	type:		DIAG_TYPE
	number_of_bits:	NAT
		   -> DIAG_TYPE

Describes number_of_bits, which when extracted will have

DIAG_TYPE

type.

2.6.4. diag_enum

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 contining zero characters this signifies no source tag.

2.6.5. diag_floating_variety

Encoding number: 5

	var:		FLOATING_VARIETY
		   -> DIAG_TYPE

Creates a DIAG_TYPE to describe an FLOATING_VARIETY var.

2.6.6. diag_loc

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).

2.6.7. diag_proc

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.

2.6.8. diag_ptr

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.

2.6.9. diag_struct

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 contining zero characters this signifies no source tag for the whole structure. tdf_shape allows the total size to be computed.

2.6.10. diag_type_null

Encoding number: 10

		   -> DIAG_TYPE

A null DIAG_TYPE.

2.6.11. diag_union

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 contining zero characters this signifies no source tag for the whole union. tdf_shape allows the total size to be computed.

2.6.12. diag_variety

Encoding number: 12

	var:		VARIETY
		   -> DIAG_TYPE

Creates a DIAG_TYPE to describe an integer VARIETY var.

2.6.13. use_diag_tag

Encoding number: 13

	dtag:		DIAG_TAG
		   -> DIAG_TYPE

Obtains the DIAG_TYPE associated with DIAG_TAG dtag.

2.7. ENUM_VALUES

Number of encoding bits: 0
Is coding extendable: no

2.7.1. make_enum_values_list

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.

2.8. DIAG_FIELD

Number of encoding bits: 0
Is coding extendable: no

2.8.1. make_diag_field

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.

2.9. DIAG_TQ

Number of encoding bits: 2
Is coding extendable: yes

DIAG_TQs are type qualifiers, used to qualify DIAG_TYPEs. A DIAG_TQ is constructed from diag_tq_null and the various add_diag_XXX operations.

2.9.1. add_diag_const

Encoding number: 1

	qual:		DIAG_TQ
		   -> DIAG_TQ

Marks a DIAG_TQ type qualifier as being const in the ANSI C sense.

2.9.2. add_diag_volatile

Encoding number: 2

	qual:		DIAG_TQ
		   -> DIAG_TQ

Marks a DIAG_TQ type qualifier as being volatile in the ANSI C sense.

2.9.3. diag_tq_null

Encoding number: 3

		   -> DIAG_TQ

Create a null DIAG_TQ type qualifier.

2.10. FILENAME

Sortname: foreign_sort("~diag_file")
Number of encoding bits: 2
Is coding extendable: yes

FILENAME record details of source files used in producing a CAPSULE. They can be tokenised for abbreviation.

2.10.1. filename_apply_token

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.

2.10.2. make_filename

Encoding number: 2

	date:		NAT
	machine:	TDFSTRING(k1, n1)
	file:		TDFSTRING(k2, n2)
		   -> FILENAME

Create a FILENAME for file file, dated date (a UNIX timestamp; seconds since 1 Jan 1970) on machine machine.

2.11. SOURCEMARK

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.

2.11.1. make_sourcemark

Encoding number: 1

	file:		FILENAME
	line_no:	NAT
	char_offset:	NAT
		   -> SOURCEMARK

Create a SOURCEMARK referencing the char_offset'th character on line line_no in file file.

char_offset is counted from 1, 0 meaning that no character offset is available.