CHAPTER 3 IR_Kind Basic Structure and Data Types

A small set of basic data types, specified in this chapter, lend precision to constructing, getting and setting FIR values.

3.1 Basic File Structure

The working assumption is that the FIR is a logical file that is a stream of bytes. Bytes are assumed to be able to assume 256 different states (i.e consist of eight bits). Ordering of bytes of larger data elements are architecture dependent and follow the writing architecures' convention. The reader must extract this ordering information from the header and transpose all data types to match the reading architecture.

3.1.1 Prototype Reader/Writer

3.1.2 Partitioning of Logical Files

A writer supporting partitioned FIR must know the maximum file length supported by the writer's environment. (This maximum size is the lesser of the operating system file length limit and the file transfer agent length limit, as appropriate.) The writer must not exceed the length limit when writing a record. (A record may not be split across different physical files.) Likewise, a reader must be capable of accepting a sequence of files, concatenating them as they are read.

The end of a physical file must be reached at or before alignment is satisfied for what would be the next record. (That is end-of-file will be encountered trying to read the IR_Kind of the next record.)

Since the FIR file header is not easily partitioned, as a minimum requirement the computing and transfer environment must be capable of handling the entire header in a single file. Since the smallest file quantum in common use today is a 1.44M diskette, this requirement should not be a limitation in practice.

3.1.3 Ordering of FIR Records

There is only one constraint on the order of FIR records. If the source locator is used (exists) for any FIR record type in the FIR then a FIR_DesignFile record must be forward of its constituents, so the format of the source locator (FIR_Source) can be determined.

A single pass will often be impossible. Either because of cycles in the graph of the IIR, or difficulty in removing forward reference in writing an FIR. In order to accommodate these structures this FIR paradigm, one may take one of three approaches: a multi-pass paradigm, the maintenance of intermediate patch information held in memory, or the use of proxy records within the FIR.

Multi-pass approaches trade increased reading and writing time for decrease ancillary memory requirements. When reading an FIR description using a multi-pass approach, the reader ignores any records that have references to records not (yet) present in memory (self-referential records are assumed to already be "in memory"). The reader must iteratively read the file until all records can be read. If there are IR records not yet read into memory and the reader cycles through the entire file without adding at least one record to memory, the file contains an error or a cycle. {what about two records that refer to each other. i.e. two VHDL record types that have access types to each other. The access types refer to the base types, so they cannot be written until the bases, but the bases cannot be written until the bases? This would imply the necessity for patching or proxy records.-RNN}

Alternatively, using the patch approach, the reader may use memory to record unresolved references within records that have already been read. After the entire FIR has been read (or incrementally as new records are read), patches are resolved by updating the FIR structures. If, at the end of the FIR, a patch cannot be resolved the FIR contains an error.

A proxy record, sometimes know as a deferred record, is a partially formed record containing sufficient information to allocate storage for the record. It acts as a place-holder until the reader reaches the full record later in the FIR. Proxy records are not currently supported by the FIR specification.

3.1.4 Bit and Byte Ordering.

Bit numbering is usually not important, as within a byte the high order bit is preserved in its position, whether the architecture specifies that bit number as 0 or not. Byte ordering is important as our atom for file transfer is assumed to be a byte. (Note, this byte is not a character. Characters may be multiple bytes as will be described in the datatypes section.)

Some records will be composite records. These records need to include the size of the contained records in their size. Also these contained records are not referable by other records, so the count of FIR_Ref is not incremented for them. These contained records are not of variable length.

3.1.5 Variable Length Records

Since the FIR is to be sequentially written and read, variable-length fields are not a problem as long as the length can be determined. Acceptable methods include an explicit description of the length or the use of a distinct terminator; such a terminator must be distinct from any legal field value. For performance and orthogonality, AIRE uses an explicit length of the variable field.

However, variation in header and record sizes complicates the representation of headers and records as C structures or C++ classes. Neither ANSI.ISO C nor draft ANSI/ISO C++ allow sizing of on structure element, such as an array, based on the value of another element. Thus, pseudo-C struct representation of FIR record structures is only documentation.

3.2 Basic Data Types

FIR readers will be responsible for identifying any byte switching that is necessary to handle endian conversion on these basic types. The endian information for the writing architecture is in the header. {Endian discussion continues -RNN}

The basic data types that are used to read and write an FIR are:

boolean,

character,

32-bit integers,

64-bit integers,

single precision floating point,

double precision floating point,

IR_Kind,

FIR_Ref.

3.2.1 IR_Boolean

3.2.2 IR_Character

3.2.3 32-bit Integer

3.2.4 64-bit Integer

3.2.5 Single Precision Floating Point

3.2.6 Double Precision Floating Point

3.2.7 IR_Kind

IR_DESIGN_FILE,

IR_COMMENT,

IR_IDENTIFIER,

IR_INTEGER_LITERAL,

IR_INTEGER_LITERAL32,

IR_INTEGER_LITERAL64,

IR_FLOATING_POINT_LITERAL

IR_FLOATING_POINT_LITERAL32,

IR_FLOATING_POINT_LITERAL64,

IR_CHARACTER_LITERAL,

IR_BIT_STRING_LITERAL,

IR_STRING_LITERAL,

IR_ASSOCIATION_ELEMENT,

IR_ASSOCIATION_ELEMENT_BY_EXPRESSION,

IR_ASSOCIATION_ELEMENT_OPEN,

IR_BREAK_ELEMENT,

IR_CASE_STATEMENT_ALTERNATIVE_BY_EXPRESSION,

IR_CASE_STATEMENT_ALTERNATIVE_BY_CHOICES,

IR_CASE_STATEMENT_ALTERNATIVE_BY_OTHERS,

IR_CHOICE,

IR_CONDITIONAL_WAVEFORM,

IR_BLOCK_CONFIGURATION,

IR_COMPONENT_CONFIGURATION,

IR_DESIGNATOR_EXPLICIT,

IR_DESIGNATOR_BY_OTHERS,

IR_DESIGNATOR_BY_ALL,

IR_ENTITY_CLASS_ENTRY,

IR_ELSIF,

IR_GROUP_CONSTITUENT,

IR_SELECTED_WAVEFORM,

IR_SIMULTANEOUS_ALTERNATIVE_BY_EXPRESSION,

IR_SIMULTANEOUS_ALTERNATIVE_BY_CHOICES,

IR_SIMULTANEOUS_ALTERNATIVE_BY_OTHERS,

IR_SIMULTANEOUS_ELSIF,

IR_WAVEFORM_ELEMENT,

IR_ASSOCIATION_LIST,

IR_ATTRIBUTE_SPECIFICATION_LIST,

IR_BREAK_LIST,

IR_CASE_ALTERNATIVE_LIST,

IR_CHOICE_LIST,

IR_COMMENT_LIST,

IR_CONCURRENT_STATEMENT_LIST,

IR_CONDITIONAL_WAVEFORM_LIST,

IR_CONFIGURATION_ITEM_LIST,

IR_DECLARATION_LIST,

IR_DESIGN_FILE_LIST,

IR_DESIGNATOR_LIST,

IR_ELEMENT_DECLARATION_LIST,

IR_ENTITY_CLASS_ENTRY_LIST,

IR_ENUMERATION_LITERAL_LIST,

IR_GENERIC_LIST,

IR_INTERFACE_LIST,

IR_LIBRARY_UNIT_LIST,

IR_PORT_LIST,

IR_SELECTED_WAVEFORM_LIST,

IR_SEQUENTIAL_STATEMENT_LIST,

IR_SIMULTANEOUS_ALTERNATIVE_LIST,

IR_SIMULTANEOUS_STATEMENT_LIST,

IR_UNIT_LIST,

IR_WAVEFORM_LIST,

IR_ENUMERATION_TYPE_DEFINITION,

IR_ENUMERATION_SUBTYPE_DEFINITION,

IR_INTEGER_TYPE_DEFINITION,

IR_INTEGER_SUBTYPE_DEFINITION,

IR_FLOATING_TYPE_DEFINITION,

IR_FLOATING_SUBTYPE_DEFINITION,

IR_PHYSICAL_TYPE_DEFINITION,

IR_PHYSICAL_SUBTYPE_DEFINITION,

IR_RANGE_TYPE_DEFINITION,

IR_ARRAY_TYPE_DEFINITION,

IR_ARRAY_SUBTYPE_DEFINITION,

IR_RECORD_TYPE_DEFINITION,

IR_ACCESS_TYPE_DEFINITION,

IR_ACCESS_SUBTYPE_DEFINTION,

IR_FILE_TYPE_DEFINITION,

IR_SIGNATURE,

IR_FUNCTION_DECLARATION,

IR_PROCEDURE_DECLARATION,

IR_ELEMENT_DECLARATION,

IR_TYPE_DECLARATION,

IR_SUBTYPE_DECLARATION,

IR_CONSTANT_DECLARATION,

IR_FILE_DECLARATION,

IR_SIGNAL_DECLARATION,

IR_SHARED_VARIABLE_DECLARATION,

IR_VARIABLE_DECLARATION,

IR_TERMINAL_DECLARATION,

IR_FREE_QUANTITY_DECLARATION

IR_BRANCH_QUANTITY_DECLARATION,

IR_CONSTANT_INTERFACE_DECLARATION,

IR_FILE_INTERFACE_DECLARATION,

IR_SIGNAL_INTERFACE_DECLARATION,

IR_VARIABLE_INTERFACE_DECLARATION,

IR_TERMINAL_INTERFACE_DECLARATION,

IR_QUANTITY_INTERFACE_DECLARATION,

IR_ALIAS_DECLARATION,

IR_ATTRIBUTE_DECLARATION,

IR_COMPONENT_DECLARATION,

IR_GROUP_DECLARATION,

IR_GROUP_TEMPLATE_DECLARATION,

IR_LIBRARY_DECLARATION,

IR_ENTITY_DECLARATION,

IR_ARCHITECTURE_DECLARATION,

IR_PACKAGE_DECLARATION,

IR_PACKAGE_BODY_DECLARATION,

IR_CONFIGURATION_DECLARATION,

IR_PHYSICAL_UNIT,

IR_ATTRIBUTE_SPECIFICATION,

IR_CONFIGURATION_SPECIFICATION,

IR_DISCONNECTION_SPECIFICATION,

IR_LABEL,

IR_LIBRARY_CLAUSE,

IR_USE_CLAUSE,

IR_SELECTED_NAME,

IR_SELECTED_NAME_BY_ALL,

IR_INDEXED_NAME,

IR_SLICE_NAME,

IR_USER_ATTRIBUTE,

IR_BASE_ATTRIBUTE,

IR_LEFT_ATTRIBUTE,

IR_RIGHT_ATTRIBUTE,

IR_LOW_ATTRIBUTE,

IR_HIGH_ATTRIBUTE,

IR_ASCENDING_ATTRIBUTE,

IR_IMAGE_ATTRIBUTE,

IR_VALUE_ATTRIBUTE,

IR_POS_ATTRIBUTE,

IR_VAL_ATTRIBUTE,

IR_SUCC_ATTRIBUTE,

IR_PRED_ATTRIBUTE,

IR_LEFT_OF_ATTRIBUTE,

IR_RIGHT_OF_ATTRIBUTE,

IR_RANGE_ATTRIBUTE,

IR_REVERSE_RANGE_ATTRIBUTE,

IR_LENGTH_ATTRIBUTE,

IR_DELAYED_ATTRIBUTE,

IR_STABLE_ATTRIBUTE,

IR_QUIET_ATTRIBUTE,

IR_TRANSACTION_ATTRIBUTE,

IR_ASCENDING_ATTRIBUTE,

IR_EVENT_ATTRIBUTE,

IR_ACTIVE_ATTRIBUTE,

IR_LAST_EVENT_ATTRIBUTE,

IR_LAST_ACTIVE_ATTRIBUTE,

IR_LAST_VALUE_ATTRIBUTE,

IR_DRIVING_ATTRIBUTE,

IR_DRIVING_VALUE_ATTRIBUTE,

IR_SIMPLE_NAME_ATTRIBUTE,

IR_INSTANCE_NAME_ATTRIBUTE,

IR_PATH_NAME_ATTRIBUTE,

IR_ACROSS_ATTRIBUTE,

IR_THROUGH_ATTRIBUTE,

IR_REFERENCE_ATTRIBUTE,

IR_CONTRIBUTION_ATTRIBUTE,

IR_DOT_ATTRIBUTE,

IR_INTEG_ATTRIBUTE,

IR_ABOVE_ATTRIBUTE,

IR_IDENTITY_OPERATOR,

IR_NEGATION_OPERATOR,

IR_ABSOLUTE_OPERATOR,

IR_NOT_OPERATOR,

IR_AND_OPERATOR,

IR_OR_OPERATOR,

IR_NAND_OPERATOR,

IR_NOR_OPERATOR,

IR_XOR_OPERATOR,

IR_XNOR_OPERATOR,

IR_EQUALITY_OPERATOR,

IR_INEQUALITY_OPERATOR,

IR_LESS_THAN_OPERATOR,

IR_LESS_THAN_OR_EQUAL_OPERATOR,

IR_GREATER_THAN_OPERATOR,

IR_GREATER_THAN_OR_EQUAL_OPERATOR,

IR_SLL_OPERATOR,

IR_SRL_OPERATOR,

IR_SLA_OPERATOR,

IR_SRA_OPERATOR,

IR_ROL_OPERATOR,

IR_ROR_OPERATOR,

IR_ADDITION_OPERATOR,

IR_SUBTRACTION_OPERATOR,

IR_CONCATENATION_OPERATOR,

IR_MULTIPLICATION_OPERATOR,

IR_DIVISION_OPERATOR,

IR_MODULUS_OPERATOR,

IR_REMAINDER_OPERATOR,

IR_EXPONENTIATION_OPERATOR,

IR_FUNCTION_CALL,

IR_PHYSICAL_LITERAL,

IR_AGGREGATE,

IR_OTHERS_INITIALIZATION,

IR_QUALIFIED_EXPRESSION,

IR_TYPE_CONVERSION,

IR_ALLOCATOR,

IR_WAIT_STATEMENT,

IR_ASSERTION_STATEMENT,

IR_REPORT_STATEMENT,

IR_SIGNAL_ASSIGNMENT_STATEMENT,

IR_VARIABLE_ASSIGNMENT_STATEMENT,

IR_PROCEDURE_CALL_STATEMENT,

IR_IF_STATEMENT,

IR_CASE_STATEMENT,

IR_FOR_LOOP_STATEMENT,

IR_WHILE_LOOP_STATEMENT,

IR_NEXT_STATEMENT,

IR_EXIT_STATEMENT,

IR_RETURN_STATEMENT,

IR_NULL_STATEMENT,

IR_BLOCK_STATEMENT,

IR_PROCESS_STATEMENT,

IR_SENSITIZED_PROCESS_STATEMENT,

IR_CONCURRENT_PROCEDURE_CALL_STATEMENT,

IR_CONCURRENT_ASSERTION_STATEMENT,

IR_CONCURRENT_CONDITIONAL_SIGNAL_STATEMENT,

IR_CONCURRENT_SELECTED_SIGNAL_STATEMENT,

IR_COMPONENT_INSTANTIATION_STATEMENT,

IR_CONCURRENT_GENERATE_FOR_STATEMENT,

IR_CONCURRENT_GENERATE_IF_STATEMENT,

IR_SIMPLE_SIMULTANEOUS_STATEMENT,

IR_SIMULTANEOUS_IF_STATEMENT,

IR_SIMULTANEOUS_CASE_STATEMENT,

IR_SIMULTANEOUS_PROCEDURAL_STATEMENT,

IR_SIMULTANEOUS_NULL_STATEMENT,

FIR_PROXY_REF,

FIR_PROXY_INDICATOR

where IR_DESIGN_FILE=1 and IR_SIMULTANEOUS_NULL_STATEMENT=????.

3.2.8 IR_SignalKind

enum IR_SignalKind {
	IR_NO_SIGNAL_KIND,
	IR_REGISTER_KIND,
	IR_BUS_KIND 
};

enum IR_Mode {
	IR_UNKNOWN_MODE,
	IR_IN_MODE,
	IR_OUT_MODE,
	IR_INOUT_MODE,
	IR_BUFFER_MODE,
	IR_LINKAGE_MODE
};

enum IR_Pure {
	IR_PURE_FUNCTION,
	IR_IMPURE_FUNCTION 
};

enum IR_DelayMechanism {
	IR_INERTIAL_DELAY,
	IR_TRANSPORT_DELAY
};

3.2.13 FIR_ProxyRef and FIR_ProxyIndicator

The FIR_ProxyIndicator is placed immediately before an actual record that has a proxy reference. It contains a reference to the original FIR_ProxyReference.

It is erroneous to have a proxy of a proxy.

struct FIR_ProxyReference {
	IR_Kind		kind; /* FIR_PROXY_REF */
	IR_Kind		targetkind;
	IR_Int32		size1; /* of first variable data */
	IR_Int32		size2; /* of second variable data */
		.
		.
		.
};
struct FIR_ProxyIndicator {
	IR_Kind		kind;  /* FIR_PROXY_INDICATOR */
	FIR_Ref		proxy; /* to FIR_ProxyRefeference/
};

The FIR header contains a field that designates whether an FIR record class has a source locator. The forms of FIR_Source map to the enumeration FIR_SourceKind. Each form of FIR_Source starts with an FIR_Ref to a FIR_DesignFile. FIR_DesignFile will have a FIR_SourceType field to indicate the type of FIR_Source can take for records that have a source locator that references that file.

Even if a FIR_DesignFile has a FIR_SourceKind of FIR_NO_SOURCE, the records that correspond to that file still have a source locator if they are so marked in the FIR header. The data is undefined.

enum FIR_SourceKind {
	FIR_NO_SOURCE, 
	FIR_CHAR_SOURCE,
	FIR_LINE_CHAR_SOURCE,
	FIR_X_Y_SOURCE
};
struct FIR_CharSource  { 
	FIR_Ref			source_file; /* FIR_DesignFile */
	IR_Int32			character_offset;
};
struct FIR_LineCharSource {
	FIR_Ref			source_file; /* FIR_DesignFile */
	IR_Int32			line_number;
	IR_Int32			character_offset;
};
struct FIR_XYSource  {
	FIR_Ref			source_file; /* FIR_DesignFile */
	IR_Int32			x;
	IR_Int32			y;
};

struct FIR_Header {
	IR_Int32    _magic_number;
	IR_Int32    _guard;
	IR_Int32    _version_number;
	IR_Int32    _number_of_bytes_in_header;
	IR_Int32    _number_of_basic_types;
	IR_Int32    _number_of_bytes_in_basic_types[];
	IR_Int32    _byte_alignment_of_basic_types[];
	IR_Int32    _number_of_ir_kinds;
	IR_Int32    _number_of_bytes_in_ir_kind[];
	IR_Int32    _ir_kind_has_source_locator[];
	IR_Int32    _lenth_of_extension_id;
	IR_Int32    _extension_id[];
	IR_Int32    _number_of_predefined_records;
};

Currently defined magic numbers are:

· IEEE Std 1076-1987 (VHDL): 0xFFA43703,

· IEEE Std 1076-1993 (VHDL): 0xFFA43709,

· IEEE Std 1364-1995 (Verilog): 0xFFD0290B,

· ANSI>ISO Standard TBD (C++): 0xF53432B0.

3.3.2 Guard

3.3.3 FIR Version

The Version number corresponding to a particular revision of this document is given on the title page of the document and is 3.0 (0x03000000).

3.3.4 Header size

Extensions are added at the end of the header. The presence of extensions can be detected by a larger than expected header size.

3.3.5 Basic types

The size of basic types is an array of the different number of bytes each type uses in the FIR.

The alignment of basic types describes the byte alignment in the FIR by each of the basic types. If a structure requires extra bytes between fields to match alignment, a reader may make no assumptions about the data in those extra bytes. These extra bytes may be used for extension data if desired by an application.

The basic type entries in these arrays follows the order of the enumeration: IR_boolean, IR_character, IR_Int32, IR_Int64, IR_FP32, IRFP64, IR_Kind, FIR_Ref.

3.3.6 IR Kinds

3.3.7 Extension Self Identification

3.3.8 Predefined FIR records

enum FIR_Predefined_Records { 
	PD_DesignFileList=1,
};

struct FIR_Trailer {
	IR_Kind		id;
	IR_Int32		checksum;
};