Union

Union is a generic type somewhat similar to the unions in other HDLs and C language for an example, with an important differences. Unions in these languages only act as different views to the underlying data, allowing user to read the same data in different formats, called subtypes here. However, the data of the PyGears Union type can represent only one of its subtypes, and it carries the information which of the subtypes it represents.

A concrete Union type is created by listing the subtypes that it can represent. For an example a Union type that represents either a an integer or a fixed-point number can be specified like this:

FixpInt = Union[Uint[16], Tuple[Uint[8], Uint[8]]]

This is same as if the tuple of types were supplied:

fields = (Uint[16], Tuple[Uint[8], Uint[8]])
FixpInt = Union[fields]

If we want to create a type that is generic in terms of the integer width, we can provide a template parameter name instead of the concrete widths:

FixpInt = Union[Uint['w_int'], Tuple[Uint['w_fixp_q'], Uint['w_fixp_p']]]

FixpInt is now a generic template type, represented by a Union with two subtypes, which is not yet fully specified. The FixpInt template has a three parameters (w_int, w_fixp_q and w_fixp_p), which need to be specified to get a concrete type. So if we want to obtain a FixpInt with 16 bit integer type and Q8.8 fixed-point type, we can write:

FixpIntQ8_8 = FixpInt[16, 8, 8]

We can also be explicit which template parameter is assigned a concrete type:

FixpIntQ8_8 = FixpInt[{
    'w_int':    16,
    'w_fixp_q': 8,
    'w_fixp_p': 8
}]

Once a concrete type has been formed it can be instantiated, which is useful for the verification. Type instance is obtained by specifying two arguments: a value and and the ID of the active subtype. The ID of the subtypes is its index in the subtype list provided when defining the Union:

uint_val = FixpIntQ8_8(0xbeef, 0)
fixp_val = FixpIntQ8_8((0xbe, 0xef), 1)

We can now check the contents of the created data, via their data and ctrl fields:

>>> uint_val.data
Uint[16](48879)
>>> uint_val.ctrl
Uint[1](0)

>>> fixp_val.data
(Uint[8](190), Uint[8](239))
>>> fixp_val.ctrl
Uint[1](1)

class UnionType

Bases: pygears.typing.base.EnumerableGenericMeta

Implements the Union generic type.

All operations on the Union type are implemented here in the UnionType class. Operations on the Union type instances are defined in the Union class.

property args

Returns a list of values supplied for each generic parameter.

>>> Tuple[Uint[1], Uint[2]].args
[Uint[1], Uint[2]]

property base

Returns base generic class of the type.

>>> assert Uint[16].base == Uint

property ctrl

Returns the type of the Union ctrl field, which contains the index of the subtype represented by a Union instance. This field is of type Uint, large enough to contain the all Union subtype indices.

property data

Returns the type of the Union data field. This field is of type Uint, large enough to contain the largest subtype of the Union.

property fields

Returns the names of the generic parameters.

>>> Tuple[Uint[1], Uint[2]].fields
('f0', 'f1')

>>> Tuple[{'u1': Uint[1], 'u2': Uint[2]}].fields
('u0', 'u1')

is_generic()

Return True if no values have been supplied for the generic parameters.

>>> Uint.is_generic()
True

>>> Uint['template'].is_generic()
False

items()

Generator that yields (key, element) pairs.

keys()

Returns a list of keys that can be used for indexing the type.

property specified

Return True if all generic parameters were supplied concrete values.

>>> Uint['template'].specified
False

>>> Uint[16].specified
True

property templates

Returns a list of templated generic variables within the type. The type is searched recursively. Each template is reported only once.

>>> Tuple[Tuple['T1', 'T2'], 'T1'].templates
['T1', 'T2']

property types

Returns a list of subtypes.

property width

Calculates the bit width of the type.

>>> int(Tuple[Uint[1], Uint[2]])
3

class Union

Bases: tuple

__int__()

Returns a packed integer representation of the Union instance.

code()

Returns a packed integer representation of the Union instance.

ctrl

alias of Union

data

alias of Union

classmethod decode(val)

Returns a Union instance from its packed integer representation.