Skip to content

Animation APIs

The following APIs can be called within SingleIsaScene and MultiIsaScene.

Please reference Animation for ISA Behaviors for the details about animation.

APIs for Registers and Elements

decl_register

Declare one register with a specified name (text) and bit width (width) and add it to the scene.

Parameters:

Name Type Description Default
text str

Name of this register.

required
width int

Width of this register width, in bit.

required
elements int

Elements count in this register, or horizontal size of this register.

1
nreg int

Number of registers, or vertical size of this register.

1
value List[List[Any]]

Value of this register, single element or 1-D/2-D array. If not specified, assign None.

None
font_size int

Font size of register name. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
value_format str

Format to print data value. If not specified, take the value from global configuration elem_value_format.

None
align_with Union[RegUnit, FunctionUnit, MemoryUnit]

Align with specified element when placement. If not specified, placement follows automatic strategy.

None

Returns:

Type Description
RegUnit

Generated register unit.

decl_register has three overloading methods for different shapes of registers:

# Scalar register.
@overload
def decl_register(
    self, text: str, width: int,
    value: Any = None, font_size: int = DEFAULT_FONT_SIZE, value_format: str = None,
    align_with = None) -> RegUnit: ...

# Vector register
@overload
def decl_register(
    self, text: str, width: int, elements: int,
    value: List[Any] = None, font_size: int = DEFAULT_FONT_SIZE,
    value_format: str = None, align_with = None) -> RegUnit: ...

# Matrix register or a list of regsiters.
@overload
def decl_register(
    self, text: str, width: int, elements: int, nreg: int,
    value: List[List[Any]] = None, font_size: int = DEFAULT_FONT_SIZE,
    value_format: str = None, align_with = None) -> RegUnit: ...

read_elem

Read one element from the specified position (reg_idx and index) of the specified register vector and return one element unit.

Parameters:

Name Type Description Default
vector RegUnit

Register.

required
index int

Element index.

0
reg_idx int

Regsiter index.

0
offset int

Offset of LSB.

0
width int

Width of element in bit.

0
color_hash Union[int, str]

Hash to get color from color scheme.

None
value_color bool

Assign different colors for different values.

False
value Any

Value of this register, single element or 1-D/2-D array. If not specified, assign None.

None
fill_opacity float

Fill opacity. If not specified, take the value from global configuration elem_fill_opacity.

None
font_size int

Font size of element value. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
value_format str

Format to print data value. If not specified, take the value from global configuration elem_value_format.

None

Returns:

Type Description
ElemUnit

Generated element unit.

read_elem has three overloading methods for different shapes of registers:

# Scalar register.
@overload
def read_elem(
    self, vector: RegUnit, offset: int = 0, width: int = -1,
    value = None, color_hash = None, fill_opacity: float = None,
    font_size: int = DEFAULT_FONT_SIZE, value_format: str = None) -> ElemUnit: ...

# Vector register
@overload
def read_elem(
    self, vector: RegUnit, index: int, offset: int = 0, width: int = -1,
    value = None, color_hash = None, fill_opacity: float = None,
    font_size: int = DEFAULT_FONT_SIZE, value_format: str = None) -> ElemUnit: ...

# Matrix register or a list of regsiters.
@overload
def read_elem(
    self, vector: RegUnit, index: int, reg_idx: int, offset: int = 0, width: int = -1,
    value = None, color_hash = None, fill_opacity: float = None,
    font_size: int = DEFAULT_FONT_SIZE, value_format: str = None) -> ElemUnit: ...

read_elem_value

Read one element from the specified position (reg_idx and index) of the specified register vector and return the value of this element unit.

The color of element unit is selected according to the value of the element.

Parameters:

Name Type Description Default
vector RegUnit

Register.

required
index int

Element index.

0
reg_idx int

Regsiter index.

0
offset int

Offset of LSB.

0
width int

Width of element in bit.

0
color_hash Union[int, str]

Hash to get color from color scheme.

None
value Any

Value of this register, single element or 1-D/2-D array. If not specified, assign None.

None
fill_opacity float

Fill opacity. If not specified, take the value from global configuration elem_fill_opacity.

None
font_size int

Font size of element value. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
value_format str

Format to print data value. If not specified, take the value from global configuration elem_value_format.

None

Returns:

Type Description
Any

The value of accessed element unit.

read_elem has three overloading methods for different shapes of registers:

# Scalar register.
@overload
def read_elem_value(
    self, vector: RegUnit, offset: int = 0, width: int = -1,
    value = None, color_hash = None, fill_opacity: float = None,
    font_size: int = DEFAULT_FONT_SIZE, value_format: str = None) -> Any: ...

# Vector register
@overload
def read_elem_value(
    self, vector: RegUnit, index: int, offset: int = 0, width: int = -1,
    value = None, color_hash = None, fill_opacity: float = None,
    font_size: int = DEFAULT_FONT_SIZE, value_format: str = None) -> Any: ...

# Matrix register or a list of regsiters.
@overload
def read_elem_value(
    self, vector: RegUnit, index: int, reg_idx: int, offset: int = 0, width: int = -1,
    value = None, color_hash = None, fill_opacity: float = None,
    font_size: int = DEFAULT_FONT_SIZE, value_format: str = None) -> Any: ...

move_elem

Aassign one element elem to the specified position (reg_idx and index) of the specified register vector.

Parameters:

Name Type Description Default
elem ElemUnit

Element object.

required
vector RegUnit

Register unit.

required
index int

Element index.

0
reg_idx int

Regsiter index.

0
offset int

Offset of LSB.

0
width int

Width of element in bit.

0

Returns:

Type Description
ElemUnit

Element unit after move.

If there are further animations on this element unit, must replace variables of this element unit with return value.

move_elem has three overloading methods for different shapes of registers:

# Scalar register.
@overload
def move_elem(
    self, elem: ElemUnit, vector: RegUnit,
    offset: int = 0, width: int = 0): ...

# Vector register
@overload
def move_elem(
    self, elem: ElemUnit, vector: RegUnit, index: int,
    offset: int = 0, width: int = 0): ...

# Matrix register or a list of regsiters.
@overload
def move_elem(
    self, elem: ElemUnit, vector: RegUnit, index: int, reg_idx: int,
    offset: int = 0, width: int = 0): ...

data_extend

Signaled extend or zero-extend element elem to bitwidth `width. Return the new element after extension.

Parameters:

Name Type Description Default
elem ElemUnit

Origin element unit.

required
width float

Target width for extend.

required
zero_extend bool

True means zero extension. The extend part will be assign with zero.

False
value Any

New value of the element unit. If not specified, inherent value from the origin element.

None

Returns:

Type Description
ElemUnit

Element unit after extension.

The width can be lower than the width of original element, as a narrow convert.

If there are further animations on this element unit, must replace variables of this element unit with return value.

APIs for Function Units

decl_function

Declare one function unit with a specified hash (isa_hash), arguments (arg_width), and return values (res_width) and add it to the scene.

Parameters:

Name Type Description Default
isa_hash str

Hash value of this function unit, used by function_call.

required
args_width List[float]

A list of bit-width of arguments.

required
res_width Union[int, List[int]]

Bit-width of return values. If there is only one return value, one single interger is required.

required
name str

Function name. If not specified, take isa_hash as function name.

None
args_name List[str]

A list of name of arguments. The number of elements should be same as args_width.

None
res_name Union[str, List[str]]

Name of return value. The number of elements should be same as res_name.

None
font_size int

Font size of register name. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
value_format str

Format to print data value. If not specified, take the value from global configuration elem_value_format.

None
align_with Union[RegUnit, FunctionUnit, MemoryUnit]

Align with specified element when placement. If not specified, placement follows automatic strategy.

None
func_callee Callable

Pointer to a function to perform the functionality.

None

Returns:

Type Description
FunctionUnit

Generated function unit.

Hash values identify function units because some may share the same name. For example, one instruction applies multiple adders (name is "Adder"). If the option name is not provided, the generated function unit applies isa_hash as the name.

args_width and args_name should have the same number of elements. res_width and res_name also should have the same number of elements. If there is only one return value, res_width and res_name can be single elements. For example:

# Adder without carry bit.
self.decl_function("adder", [16, 16], 16, args_name=["a", "b"], res_name="sum")

# Adder with carry bit
self.decl_function(
    "adder", [16, 16, 1], [1, 16], args_name=["a", "b", "cin"],
    res_name=["cout", "sum"])

If one instruction apply multiple heterogenous function units, apply decl_function to generate each function unit and apply option align_with to guide the layout of function units.

If one instruction apply multiple homogenous function unit, apply decl_func_group as below.

decl_func_group

Declare a group of function units with a sequential of specified hash (isa_hash), arguments (arg_width), and return values (res_width) and add them to the scene as a group.

Parameters:

Name Type Description Default
num_unit Union[int, List[int]]

The number of units. More than one hierachy level is accepted.

required
isa_hash Union[str, List[str]]

Hash value of this function unit, used by function_call. Both a single hash and a sequence of hash are accepted.

required
args_width List[float]

A list of bit-width of arguments.

required
res_width Union[int, List[int]]

Bit-width of return values. If there is only one return value, one single interger is required.

required
func_name Union[str, List[str]]

Function name. If not specified, take isa_hash as function name.

None
args_name List[str]

A list of name of arguments. The number of elements should be same as args_width.

None
res_name Union[str, List[str]]

Name of return value. The number of elements should be same as res_name.

None
font_size int

Font size of register name. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
value_format str

Format to print data value. If not specified, take the value from global configuration elem_value_format.

None
force_hw_ratio bool

If force_hw_ratio is true, the number of units in one row is forced by the last item in num_unit. If force_hw_ratio is false, the shape of function groups is auto-adjusted according to the scene h/w ratio.

False
func_callee Callable

Pointer to a function to perform the functionality.

None

Returns:

Type Description
List[FunctionUnit]

A list of generated function unit.

Generated function units share the args_width, res_width, args_name, res_name, font_size, value_format and func_callee. args_width and args_name should have the same number of elements. res_width and res_name also should have the same number of elements. If there is only one return value, res_width and res_name can be single elements.

num_unit specifies the number of units. If one single integer is provided, the integer presents the number of units. If a list of integers is provided, the list presents the hierarchy of units. For example, [2, 4] means 2 groups of units, and each group has 4 units.

The hash value of each function unit is specified by isa_hash. If one single string is provided, decl_func_group will generate one individual hash for each element. Take isa_hash is "Addr" as an example:

  • If num_unit is 8, the hash values are Addr0, Addr1, Addr2, ..., Addr7.
  • If num_unit is [8, 8], the hash value are Addr0_0, Addr0_1, ..., Addr_1_0, Addr_1_1, ..., Addr7_7

If a list is provided to the option isa_hash, the list must follow the hierarchy defined by num_unit. So that isa_hash can be assigned to each function unit.

The option func_name specifies names for function units. If func_name is not specified, take isa_hash as the name. If one single string is provided, all function units share the same function name. Otherwise, func_name should follow the hierarchy defined by num_unit.

The shape of a function group is auto-adjusted if force_hw_ratio is False. See Objects Placement as an example.

It is recommand to provide one single element to num_unit, isa_hash and func_name. decl_func_group will generate one individual hash for each element.

function_call

Function call.

Parameters:

Name Type Description Default
isa_hash str

Hash value of the specified function unit.

required
args List[ElemUnit]

Element units as arguments.

required
args_offset List[int]

LSB offset for the argument elements. If not specified, 0 for each argument elements.

None
color_hash Union[int, str]

Specified hash to get color from scheme.

None
res_width Union[int, List[int]]

Bit-width of return values. If there is only one return value, one single interger is required.

None
res_offset Union[int, List[int]]

LSB offset for the result element units. If not specified, 0 for each result element units.

None
res_value Union[Any, List[Any]]

Value of the result element units. If not specified, assign None or calculate by inline function.

None
res_fill_opacity float

Fill opacity. If not specified, take the value from global configuration elem_fill_opacity.

None
res_font_size int

Font size of result element unit. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
res_value_format str

Format to print result value. If not specified, take the value from global configuration elem_value_format.

None

Returns:

Type Description
Union[ElemUnit, List[ElemUnit]]

Result element units. If only one result value, only one element unit returns.

function_call provides the capacity to perform the functionality. If one callable function has been provided to the function unit through option func_callee and all the argument element units have assigned value (elem_value), function_call performs the functionality by calling func_callee with value from all args. An example is shown below:

mbytes = 4

# Registers
rn_reg = self.decl_register("rn", addrlen, value=0x100)
rm_reg = self.decl_register("rm", addrlen, value=0x100, align_with=rn_reg)

# Function unit
self.decl_function(
    "addrgen", [addrlen, addrlen], addrlen, name="base+offset",
    args_name=["base", "offset"], func_callee=lambda x, y: x + y)
self.decl_function(
    "scale", [addrlen], addrlen, name=f"offset*{mbytes}", args_name=["offset"],
    func_callee=lambda x: x * mbytes)

# Behaviors
base = self.read_elem(rn_reg)
# element value of `base` is 0x100
offset = self.read_elem(rm_reg)
# element value of `offset` is 0x100
offset = self.function_call("scale", [offset])
# element value of `offset` is 0x100 * 4 = 0x400
base = self.function_call("addrgen", [base, offset])
# element value of `base` is 0x100 + 0x400 = 0x500

In some situations, element units used as source and destination operands may not cover all bits as the bit-width of arguments and results. For example, some multiply instructions only return the high-half of the product. For such situations, args_offset and res_offset specify the LSB offset of element units. An example is shown below:

# Registers
rn_reg = self.decl_register("rn", 32)
rm_reg = self.decl_register("rm", 32, align_with=rn_reg)

# Function unit
self.decl_function("multiply", [32, 32], 64)

# Behaviors
rn = self.read_elem(rn_reg)
rm = self.read_elem(rm_reg)
result = self.function_call("multiply", [rn, rm], res_width=32, res_offset=32)

func_group_call

Function call among a parallel function group. The function unit is specified by grp_isa_hash and para_index.

Parameters:

Name Type Description Default
grp_isa_hash str

Hash value of the specified function unit.

required
para_index Union[int, List[int]]

Index of unit in parallel function group.

required
args List[ElemUnit]

Element units as arguments.

required
args_offset List[int]

LSB offset for the argument elements. If not specified, 0 for each argument elements.

None
color_hash Union[int, str]

Specified hash to get color from scheme.

None
res_width Union[int, List[int]]

Bit-width of return values. If there is only one return value, one single interger is required.

None
res_offset Union[int, List[int]]

LSB offset for the result element units. If not specified, 0 for each result element units.

None
res_value Union[Any, List[Any]]

Value of the result element units. If not specified, assign None or calculate by inline function.

None
res_fill_opacity float

Fill opacity. If not specified, take the value from global configuration elem_fill_opacity.

None
res_font_size int

Font size of result element unit. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
res_value_format str

Format to print result value. If not specified, take the value from global configuration elem_value_format.

None

Returns:

Type Description
Union[ElemUnit, List[ElemUnit]]

Result element units. If only one result value, only one element unit returns.

func_group_call performs the same function as function_call, except func_group_call can select the function unit from a group of units. The function unit is specified by grp_isa_hash and para_index. grp_isa_hash is the same as the value specified by isa_hash in decl_func_group.

read_func_imm

Generate immediate operand for function calling.

Parameters:

Name Type Description Default
width float

Bit width.

required
color_hash Union[int, str]

Specified hash to get color from scheme.

None
value Any

Value of the immediate element units. If not specified, assign None or calculate by inline function.

None
fill_opacity float

Fill opacity. If not specified, take the value from global configuration elem_fill_opacity.

None
font_size int

Font size of result element unit. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
value_format str

Format to print result value. If not specified, take the value from global configuration elem_value_format.

None

Returns:

Type Description
Tuple[ElemUnit, Animation]

A tuple of element unit and fade-in animation.

The function of read_func_imm does not register animation directly. Instead, the tuple of element unit and fade-in animation is delivered to funcion_call so that the fade-in animation can be integrated into the animation of function_call.

During the first step of the animation to call a function, the immediate operands fade in at the position of function arguments. In contrast, other operands move to the position of function arguments.

If directly deliver the return value of read_func_imm to the argument of function_call, it is not necessary to unpack the return value of read_func_imm.

It is recommand that only deliver the return value of read_func_imm to the argument of function_call.

APIs for Memory Units

decl_memory

Declare one memory unit with a specified address width (addr_width), data width (data_width), and memory range (mem_range) and add it to the scene.

Parameters:

Name Type Description Default
addr_width int

Bit-width of the address port.

required
data_width int

Bit-width of the data port.

required
mem_range List[Tuple[int, int]]

Range of memory map. Each tuple in mem_range presents the range of one memory map. The first element in tuple is the lowest address and the second element is the highest address.

required
isa_hash str

Hash value of this memory unit. Used to declare more than one memory unit.

None
addr_align int

Align requirement of memory range. If not specified, take the value from global configuration mem_align.

None
status_width int

Bit width of the status port. If not specified, the memory unit does not have status port.

0
font_size int

Font size of register name. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
value_format str

Format to print data value. If not specified, take the value from global configuration elem_value_format.

None
para_enable bool

True means memory unit allow parallel animations. False means animations with this memory unit must be serialized.

False
dual_port bool

True means the memory unit has two data ports. Otherwise, only one data port is present.

False

Returns:

Type Description
MemoryUnit

Generated memory unit.

In most situations, there is only one memory unit in the animation. The hash of this memory unit is Memory. Users can still declare more than one memory unit using the option isa_hash.

read_memory

Read data from the specified address.

Parameters:

Name Type Description Default
addr ElemUnit

Address element unit.

required
width int

Bit width of read data.

required
offset int

LSB offset of read data.

0
color_hash Union[int, str]

Hash value to get color from color scheme.

None
res_value Any

Value of data element.

None
res_fill_opacity float

Fill opacity. If not specified, take the value from global configuration elem_fill_opacity.

None
res_font_size int

Font size of result element unit. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
res_value_format str

Format to print result value. If not specified, take the value from global configuration elem_value_format.

None
has_status_output bool

True means output of the status port is required. If the memory unit does not have a status port, has_status_output is ignored.

False
status_width int

Bit width of output status. If not specified, the width of the generated status element unit is as same as the status port.

None
status_value Any

Value of status element.

None
status_fill_opacity float

Fill opacity. If not specified, take the value from global configuration elem_fill_opacity.

None
status_font_size int

Font size of result element unit. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
status_value_format str

Format to print result value. If not specified, take the value from global configuration elem_value_format.

None
port2 bool

Read data to port2 if the memory unit has dual ports.

False
mem_isa_hash str

Hash to idenify memory unit. If not specified, operate on the memory unit with the hash of "Memory".

None

Returns:

Type Description
Union[Tuple[ElemUnit, ElemUnit], ElemUnit]

If having status output, return a tuple of the data and status element units. Otherwise, return the data element unit.

write_memory

Write data to the specified address.

Parameters:

Name Type Description Default
addr ElemUnit

Address element unit.

required
data ElemUnit

Data element unit.

required
offset int

LSB offset of read data.

0
color_hash Union[int, str]

Hash value to get color from color scheme.

None
has_status_output bool

True means output of the status port is required. If the memory unit does not have a status port, has_status_output is ignored.

False
status_width int

Bit width of output status. If not specified, the width of the generated status element unit is as same as the status port.

None
status_value Any

Value of status element.

None
status_fill_opacity float

Fill opacity. If not specified, take the value from global configuration elem_fill_opacity.

None
status_font_size int

Font size of result element unit. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
status_value_format str

Format to print result value. If not specified, take the value from global configuration elem_value_format.

None
port2 bool

Write data from port2 if the memory unit has dual ports.

False
mem_isa_hash str

Hash to idenify memory unit. If not specified, operate on the memory unit with the hash of "Memory".

None

Returns:

Type Description
Union[ElemUnit, None]

If having status output, return status element unit. Otherwise, return None.

read_memory_pair

Read data from the specified address.

Parameters:

Name Type Description Default
addr ElemUnit

Address element unit.

required
width int

Bit width of read data.

required
offset int

LSB offset of read data.

0
color_hash Union[int, str]

Hash value to get color from color scheme.

None
res_value Tuple[Any, Any]

Value of data element.

None
res_fill_opacity float

Fill opacity. If not specified, take the value from global configuration elem_fill_opacity.

None
res_font_size int

Font size of result element unit. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
res_value_format str

Format to print result value. If not specified, take the value from global configuration elem_value_format.

None
has_status_output bool

True means output of the status port is required. If the memory unit does not have a status port, has_status_output is ignored.

False
status_width int

Bit width of output status. If not specified, the width of the generated status element unit is as same as the status port.

None
status_value Any

Value of status element.

None
status_fill_opacity float

Fill opacity. If not specified, take the value from global configuration elem_fill_opacity.

None
status_font_size int

Font size of result element unit. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
status_value_format str

Format to print result value. If not specified, take the value from global configuration elem_value_format.

None
mem_isa_hash str

Hash to idenify memory unit. If not specified, operate on the memory unit with the hash of "Memory".

None

Returns:

Type Description
Union[Tuple[ElemUnit, ElemUnit, ElemUnit], Tuple[ElemUnit, ElemUnit]]

If having status output, return a tuple of two data element units and status element units. Otherwise, return a tuple of two data element units.

write_memory_pair

Write data to the specified address.

Parameters:

Name Type Description Default
addr ElemUnit

Address element unit.

required
data Tuple[ElemUnit, ElemUnit]

Data element unit.

required
offset int

LSB offset of read data.

0
color_hash Union[int, str]

Hash value to get color from color scheme.

None
has_status_output bool

True means output of the status port is required. If the memory unit does not have a status port, has_status_output is ignored.

False
status_width int

Bit width of output status. If not specified, the width of the generated status element unit is as same as the status port.

None
status_value Any

Value of status element.

None
status_fill_opacity float

Fill opacity. If not specified, take the value from global configuration elem_fill_opacity.

None
status_font_size int

Font size of result element unit. If not specified, take the value of DEFAULT_FONT_SIZE.

DEFAULT_FONT_SIZE
status_value_format str

Format to print result value. If not specified, take the value from global configuration elem_value_format.

None
mem_isa_hash str

Hash to idenify memory unit. If not specified, operate on the memory unit with the hash of "Memory".

None

Returns:

Type Description
Union[ElemUnit, None]

If having status output, return status element unit. Otherwise, return None.

The option has_status_output determines whether read_memory and write_memory generate status output. If the memory unit does not have a status port, option has_status_output is ignored. When the memory unit has a status port:

  • If has_status_output is False, read_memory and write_memory do not generate the status output.
    • read_memory returns the data element unit. write_memory returns None.
  • If has_status_output is True, read_memory and write_memory generate the status output.
    • read_memory returns the tuple of the data and status element unit. write_memory returns the status element unit.

The attributes of the generated data element unit are specified by res_value, res_fill_opacity, res_font_size, and res_value_format. The attributes of the status element unit are specified by another group of options, i.e., status_width, status_value, status_fill_opacity, status_font_size, and status_value_format.

By default, read_memory and write_memory operate on the memory unit with the hash of "Memory". Still, users can specify a specified memory unit by the option of mem_isa_hash.