Data Types

This section documents the data type entities provided by Tydl and describes the attributes that are applicable to each one. These entities are defined in the Tydl.Data namespace.

Array

Composite Type representing a data array of similarly-typed elements.

The following keyword parameters may be used to specify attributes of this entity:

element_type: Type of elements stored in the array. If this attribute is not specified, then any type of element may be stored in the array.
first_index: The index of the first element in the array. If indices is specified, then the first index will be automatically determined. The default value for this attribute is 0.
indices: Range of possible values for the array index (e.g. 1..10, 0..9, 15..0). If present, this attribute determines the number of elements in the array as well as the indexing convention (e.g. zero or one-based indexing, ascending/descending) used to access the elements.
length: Indicates the number of elements in the array. If indices is specified, then the length will be automatically determined. If no value is specified, then the array length is unconstrained.
of: Alias for element_type.

The following positional parameters are accepted:

Argument Position	Parameter
1st	`element_type`

Bit

Primitive data Type representing a single bit. This is equivalent to an Unsigned Integer with a bit_width of 1.

Boolean Value (Boolean/Bool)

Primitive data Type representing boolean values that are stored as integers of a specific size. A true value is represented as 1 and a false value is represented as 0.

The following keyword parameters may be used to specify attributes of this entity:

bit_width: Alias for bit_count. If specified, this attribute indicates the number of bits used for storage, otherwise the size is unconstrained and an implementation-dependent number of bits may be used. The bit_width for boolean values may range from 1 to 64.

The following positional parameters are accepted:

Argument Position	Parameter
1st	`bit_width`

Enumeration (Enumerated/Enum)

Primitive data Type implementing enumerations. This data type provides a way to encode a set of abstract, symbolic identifiers (i.e. choices) as a set of concrete, numeric (typically integer) values.

The following keyword parameters may be used to specify attributes of this entity:

as: Alias for representation.
bit_width: This attribute determines the number of bits used to store the value representing the encoded choice. In other words, it determines the bit_count of the Type specified via the representation attribute. If not explictly specified, a sufficiently large implementation-dependent value may be chosen.
logical_type: Data Type of the symbolic choices that are represented by the enumeration. This attribute defaults to Identifier and rarely needs to be changed. In some cases, however, enumerations may be used to represent a discrete set of typed values (e.g. Floats).
of: Alias for logical_type.
representation: Concrete Type used to store the encoded values. Typically, the default value for this attribute (Unsigned Integer) is sufficient.
reserved: List of reserved encodings (representation values) that are not explicitly defined, but may be used for undocumented purposes. A range of encoding values is also acceptable.
spare: Explicit list of spare encodings (representation values) that are not currently being used. A range of encoding values is also acceptable.
choices: List of enumerated choices. The data Type of each choice should be compatible with the type specified by the logical_type attribute (usually these values are just symbolic Identifiers). Alternatively, a list of key-value pairs may be specified to explicitly specify how each value is represented/encoded. The key identifies the symbolic choice, and the corresponding value (in the key-value pair) specifies the concrete encoding for that symbolic value.

The following positional parameters are accepted:

Argument Position	Parameter
1st	`logical_type`

Floating Point Value (Float)

Primitive data Type representing binary IEEE 754-formatted floating-point values of a specific size.

The following keyword parameters may be used to specify attributes of this entity:

bit_width: Alias for bit_count. This attribute indicates the number of bits used for storage and should be specified for concrete types. The bit_width for floating point numbers may be 32 or 64.

The following positional parameters are accepted:

Argument Position	Parameter
1st	`bit_width`

Quantity (Quantified)

Adds a units attribute to the specified base Type.

The following keyword parameters may be used to specify attributes of this entity:

numeric_type: The base Type to be extended.
units: The units associated with this data Type. Identifiers corresponding to most standard units may be found in the Tydl.Units namespace. Abbreviations for these units may be found in the Tydl.Units.Abbreviations namespace.

The following positional parameters are accepted:

Argument Position	Parameter
1st	`numeric_type`

Record

Composite Type representing a data record (i.e. C/C++ structure or union) with named Fields.

The following keyword parameters may be used to specify attributes of this entity:

default_for_reserved_bit: Default value (i.e. 0 or 1) to use for reserved bits of this record.
default_for_spare_bit: Default value (i.e. 0 or 1) to use for spare bits of this record.

fields: Ordered list of key-value pairs that define the fields present in the Record, where the key indicates the name of the field and the value specifies the data type and optional field-specific attributes, such as the field location. Each value may be either a Type or Field instance, depending on whether or not field-specific attributes are required. The order in which the fields are listed determines the order they are stored in memory unless a location is explicitly specified. This list attribute is considered appendable by extensions of this entity.

Scaled Value (Scaled)

Represents a scaled data Type that stores data with a scale factor removed. The logical type and stored data representation may also be different.

The following keyword parameters may be used to specify attributes of this entity:

as: Alias for logical_type.
logical_type: The resulting logical data Type. If this attribute is not specified, it is deduced from the other attributes.
lsb: Alias for scale_factor.
max_value: Specifies the maximum possible logical value that can be taken on by an instance of this data type. The max_value of the underlying representation value will differ according to the scale_factor.
min_value: Specifies the minimum possible logical value that can be taken on by an instance of this data type. The min_value of the underlying representation value will differ according to the scale_factor.
range: Specifies the range of possible logical values (i.e. min_value and max_value) for instances of this data type. The range of the underlying representation value will differ according to the scale_factor.
representation: The physical data Type that will be used to store the value.
scale_factor: The scale factor or weighting of the least significant bit of the stored data type. The stored value is multiplied by this value to determine the logical value of the data.

The following positional parameters are accepted:

Argument Position	Parameter
1st	`representation`

Signed Integer (SInt/Int)

Primitive data Type representing signed (two’s complement) integer values of a specific size.

The following keyword parameters may be used to specify attributes of this entity:

bit_width: Alias for bit_count. This attribute indicates the number of bits used for storage and should be specified for concrete types. The bit_width for signed integers typically ranges from 1 to 64.

The following positional parameters are accepted:

Argument Position	Parameter
1st	`bit_width`

Tagged Union

Composite Type representing a tagged data union that can represent multiple kinds of Records. Unlike a standard union, the specific subtype of a tagged union can be determined from a field (or tag) embedded in the data structure itself.

The following keyword parameters may be used to specify attributes of this entity:

kinds: List of Record subtypes that instances of this tagged union can represent. All of the records listed here should be extensions of a common base entity.
of: Alias for kinds.

Type

Extension of Parameterized Entity that serves as a base for all Tydl data types, including composite (e.g. Arrays and Records) and primitive types.

The following keyword parameters may be used to specify attributes of this entity:

bit_count: An unsigned integer indicating the number of bits used to represent (store) the value.
bit_numbering: Indicates the bit numbering convention adopted by this data type. Valid values for this attribute are least_significant_bit_is_0 (aka lsb_0) and most_significant_bit_is_0 (aka msb_0). The default value is least_significant_bit_is_0.
bit_range_order: Indicates the order used to specify bit ranges (e.g. Bits[0..3] or Bits[3..0]. Valid values for this attribute are least_significant_first and most_significant_first. The default value is most_significant_first.
bit_transmission_order: Indicates the order that the individual bits of a byte are transmitted. Valid values for this attribute are least_significant_first and most_significant_first. The default value is least_significant_first. This attribute only makes sense for serial data streams.
default: The default value to use when initializing instances of this data type. Where possible, a zeroish value will be used if this attribute is unspecified.
layout: Specifies the low-level bit/byte layout to be used when storing an instance of this data type in byte-addressable memory. If specified, this attribute should be a Layout instance.
max_value: Specifies the maximum possible value that can be taken on by an instance of this data type. Note that this does not make sense for some data types.
min_value: Specifies the minimum possible value that can be taken on by an instance of this data type. Note that this does not make sense for some data types.
range: Specifies the range of possible values (i.e. min_value and max_value) for instances of this data type. Note that this does not make sense for some data types.

scalar_storage_order

Specifies the storage order (endianness) for scalar (e.g. integer and floating-point) types. Valid values for this attribute are least_significant_first, most_significant_first, parent, and native. The default value is parent, which means that this attribute is inherited from the parent entity (e.g. Record or Array), if applicable. For top-level entities, a value of parent is equivalent to native, which means that the machine’s native byte order should be used for efficiency. Specifying a native scalar_storage_order implies that the storage order is not important and may not be portable between different computing architectures. The name of this attribute (the scalar part, in particular) was chosen for consistency with the equivalent Ada Scalar Storage Order and GCC scalar_storage_order type attribute constructs.

As an example, consider a 16-bit integer value with the following bits (LSB 0 bit numbering) :

If a scalar_storage_order of least_significant_first is specified, this 16-bit value would be stored in byte-addressable memory (e.g. RAM) as shown below:

Little-Endian Layout
Byte Offset	Content
0	Least-Significant Byte (Bits 7-0)
1	Most-Significant Byte (Bits 15-8)

If a scalar_storage_order of most_significant_first is specified, this 16-bit value would be stored in byte-addressable memory as follows:

Big-Endian Layout
Byte Offset	Content
0	Most-Significant Byte (Bits 15-8)
1	Least-Significant Byte (Bits 7-0)

The scalar_storage_order attribute also affects how bit fields are packed into bytes. As an example, consider the following record of bit fields:

Example: Record
  fields:
    First: Field
      type: 'Unsigned Integer'
        bit_width: 5
    Second: Field
      type: 'Unsigned Integer'
        bit_width: 5
    Third: Field
      type: 'Unsigned Integer'
        bit_width: 6

If a scalar_storage_order of least_significant_first is specified, the fields of this record would be stored in byte-addressable memory as shown below:

Little-Endian Bit-Field Layout (LSB 0)
Byte Offset	MSb							LSb
Byte Offset	7	6	5	4	3	2	1	0
0	Bits 2-0 of `Second`			`First`
1	`Third`						Bits 4-3 of `Second`

If a scalar_storage_order of most_significant_first is specified, the fields of this record would be stored in byte-addressable memory as shown below:

Big-Endian Bit-Field Layout (LSB 0)
Byte Offset	MSb							LSb
Byte Offset	7	6	5	4	3	2	1	0
0	`First`					Bits 4-2 of `Second`
1	Bits 1-0 of `Second`		`Third`

stored

Alias for layout.

text_format

Desired Python format string to be used when instances of this data type are converted to a text string for display purposes. Note that this does not make sense for some data types.

value

Specifies a fixed value for instances of this data type. Note that this does not make sense for some data types.

Unsigned Integer (UInt)

Primitive data Type representing unsigned integer values of a specific size.

The following keyword parameters may be used to specify attributes of this entity:

bit_width: Alias for bit_count. This attribute indicates the number of bits used for storage and should be specified for concrete types. The bit_width for unsigned integers typically ranges from 1 to 64.

The following positional parameters are accepted:

Argument Position	Parameter
1st	`bit_width`

Word

Hybrid Unsigned Integer / Bit Array data type with some specialized features. It can be thought of as an extension of Record with a single Field named Bits. A declaration would look something like this:

Word:  Record
  fields:
    Bits: Field
      type: Array
        element_type: Bit
        length: bit_width
      hidden: true

The Bits array, however, is indexed according to the applicable bit_numbering and bit_range_order attributes.

In addition to being used as a Record, this data type also can be used as an Unsigned Integer.

The text_format attribute is also overridden so that Word values are shown as hexadecimal unsigned integers by default.

The following keyword parameters may be used to specify attributes of this entity:

bit_width: Alias for bit_count. This attribute indicates the number of bits used for storage and should be specified for concrete types. The bit_width for words typically ranges from 1 to 64.

Word-Reversed Value

Data Type that stores the data content for a value in word-reversed order. The data content is broken up into chunks of bit_width_of_words bits. These chunks are stored in reverse order, but the order of the bits within a chunk is not reversed.

The following keyword parameters may be used to specify attributes of this entity:

bit_width_of_words: Unsigned Integer representing the number of bits in each chunk.
type: The Type of data to be stored in word-reversed order.

The following positional parameters are accepted:

Argument Position	Parameter
1st	`type`