DataSpecification

Used to generate memory images for a SpiNNaker CPU core from a set of instructions.

The main part of this package is the DataSpecificationGenerator class. This is used to generate a “Data Specification”, which can then be executed to produce a memory image. This package also handles this function if required, through the DataSpecificationExecutor class.

Functional Requirements

Creation of a Data Specification Language file which can be executed to produce a memory image.

  • Any errors that can be checked during the creation of the specification should throw an exception.
  • It will be impossible to detect all errors at creation time.
  • There should be no assumption of where the data specification will be stored, although a default provision of a way to write the specification to a file is acceptable.

Execution of a Data Specification Language file, producing a memory image.

  • This should detect any errors during execution and report them, halting the execution.
  • There should be no assumption of where the data specification is read from, although a default provision of a way to read the specification from a file is acceptable.

Use Cases

There are a number of use-cases of this library:

  • DataSpecificationGenerator is used to create a compressed memory image which can be expanded later, to reduce the amount of data that needs to be transferred over a slow connection.
  • DataSpecificationExecutor is used to execute a previously generated specification at the receiving end of a slow connection.

Main API

class data_specification.DataSpecificationExecutor(spec_reader, memory_space)[source]

Used to execute a SpiNNaker data specification language file to produce a memory image.

Parameters:
  • spec_reader (RawIOBase) – The object to read the specification language file from
  • memory_space (int) – memory available on the destination architecture
Raises:

IOError – If a read or write fails

dsef

The executor functions themselves.

execute()[source]

Executes the specification. This will result in a configuration of memory regions being done.

Raises:
get_constructed_data_size()[source]

Return the size of the data that will be written to memory.

Returns:size of the data that will be written to memory
Return type:int
get_header()[source]

Get the header of the data as a numpy array.

Return type:numpy.ndarray
get_pointer_table(start_address)[source]

Get the pointer table as a numpy array.

Parameters:start_address (int) – The base address of the data to be written
Return type:numpy.ndarray
get_region(region_id)[source]

Get a region with a given ID.

Parameters:region_id (int) – The ID of the region to get
Returns:The region, or None if the region was not allocated
Return type:MemoryRegion or None
mem_regions

An enumeration of the mapping from region ID to region holder.

Return type:iterable(tuple(int, MemoryRegion or None))
class data_specification.DataSpecificationExecutorFunctions(spec_reader, memory_space)[source]

This class includes the function related to each of the commands of the data specification file.

Note

DSG operations not mentioned in this class will cause an error during DSE if used.

Parameters:
  • spec_reader (RawIOBase) – The object to read the specification language file from
  • memory_space (int) – Memory space available for the data to be generated per region
execute_break(cmd)[source]

This command raises an exception to stop the execution of the data spec executor (DSE).

Implements BREAK

Parameters:

cmd (int) – the command which triggered the function call

Returns:

No value returned

Raises:
execute_end_spec(cmd)[source]

This command marks the end of the specification program.

Implements END_SPEC

Parameters:

cmd (int) – the command which triggered the function call

Returns:

A special marker to signal the end.

Raises:
execute_mv(cmd)[source]

This command moves an immediate value to a register or copies the value of a register to another register.

Implements MV

Parameters:

cmd (int) – the command which triggered the function call

Returns:

No value returned

Raises:
execute_reserve(cmd)[source]

This command reserves a region and assigns some memory space to it.

Implements RESERVE

Parameters:

cmd (int) – the command which triggered the function call

Returns:

No value returned

Raises:
execute_set_wr_ptr(cmd)[source]

This command sets the current write pointer.

Implements SET_WR_PTR

Parameters:

cmd (int) – the command which triggered the function call

Returns:

No value returned

Raises:
execute_switch_focus(cmd)[source]

This command switches the focus to the desired, already allocated, memory region.

Implements SWITCH_FOCUS

Parameters:

cmd (int) – the command which triggered the function call

Returns:

No value returned

Raises:
execute_write(cmd)[source]

This command writes the given value in the specified region a number of times as identified by either a value in the command or a register value.

Implements WRITE

Parameters:

cmd (int) – the command which triggered the function call

Returns:

No value returned

Raises:
execute_write_array(cmd)[source]

This command writes an array of values in the specified region.

Implements WRITE_ARRAY

Parameters:

cmd (int) – the command which triggered the function call

Returns:

No value returned

Raises:
mem_regions

The collection of memory regions that can be written to.

Return type:MemoryRegionCollection
class data_specification.DataSpecificationGenerator(spec_writer, report_writer=None)[source]

Used to generate a SpiNNaker data specification language file that can be executed to produce a memory image.

Parameters:
  • spec_writer (RawIOBase) – The object to write the specification to
  • report_writer (TextIOBase or None) – Determines if a text version of the specification is to be written and, if so, where. No report is written if this is None.
Raises:

IOError – If a write to external storage fails

align_write_pointer(log_block_size, log_block_size_is_register=False, return_register_id=None)[source]

Insert command to align the write pointer against a power-of-2 block size in bytes. Zeros are inserted in the intervening space

Parameters:
  • log_block_size (int) –
    • If log_block_size_is_register is False, log to base 2 of the block size (e.g. The write pointer will be moved so that it is a multiple of 2log_block_size), between 0 and 32
    • If log_block_size_is_register is True, the ID of the register containing log to the base 2 of the block size, between 0 and 15
  • log_block_size_is_register (bool) – Indicates if log_block_size is a register ID
  • return_register_id (int or None) – The ID of a register where the write pointer will be written to once it has been updated, between 0 and 15, or None if no such writing is to be done
Raises:
break_loop()[source]

Insert command to break out of a loop before it has completed

Raises:
call_arithmetic_operation(register_id, operand_1, operation, operand_2, signed, operand_1_is_register=False, operand_2_is_register=False)[source]

Insert command to perform an arithmetic operation on two signed or unsigned values and store the result in a register

Parameters:
  • register_id (int) – The ID of the register to store the result in
  • operand_1 (int) –
    • If operand_1_is_register is True, the ID of a register where the first operand can be found, between 0 and 15
    • If operand_1_is_register is False, a 32-bit value
  • operation (ArithmeticOperation) – The operation to perform
  • operand_2 (int) –
    • If operand_2_is_register is True, the ID of a register where the second operand can be found, between 0 and 15
    • If operand_2_is_register is False, a 32-bit value
  • signed (bool) – Indicates if the values should be considered signed
  • operand_1_is_register (bool) – Indicates if operand_1 is a register ID
  • operand_2_is_register (bool) – Indicates if operand_2 is a register ID
Raises:
call_function(function_id, structure_ids)[source]

Insert command to call a function

Parameters:
  • function_id (int) – The ID of a previously defined function, between 0 and 31
  • structure_ids (list(int)) – A list of structure IDs that will be passed into the function, each between 0 and 15
Raises:
call_random_distribution(distribution_id, register_id)[source]

Insert command to get the next random number from a random distribution, placing the result in a register to be used in a future call

Parameters:
  • distribution_id (int) – The ID of the random distribution to call between 0 and 63
  • register_id (int) – The ID of the register to store the result in between 0 and 15
Raises:
comment(comment)[source]

Write a comment to the text version of the specification. Note that this is ignored by the binary file

Parameters:

comment (str) – The comment to write

Raises:
copy_structure(source_structure_id, destination_structure_id, source_id_is_register=False, destination_id_is_register=False)[source]

Insert command to copy a structure, possibly overwriting another structure

Parameters:
  • source_structure_id (int) –
    • If source_id_is_register is True, the ID of the register holding the source structure ID, between 0 and 15
    • Otherwise, the ID of the source structure, between 0 and 15
  • destination_structure_id (int) –
    • If destination_id_is_register is True, the ID of the register holding the destination structure ID, between 0 and 15
    • If destination_id_is_register is False, the ID of the destination structure, between 0 and 15
  • source_id_is_register (bool) – Indicates if source_structure_id is a register ID
  • destination_id_is_register (bool) – Indicates if destination_structure_id is a register ID
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If source_id_is_register is True and source_structure_id is not a valid register ID
    • If destination_id_is_register is True and destination_structure_id is not a valid register ID
    • If source_id_is_register is False and source_structure_id is not a valid structure ID
    • If destination_id_is_register is False and destination_structure_id is not a valid structure ID
  • NotAllocatedException
    • If no structure with ID source_structure_id has been allocated
copy_structure_parameter(source_structure_id, source_parameter_index, destination_id, destination_parameter_index=None, destination_is_register=False)[source]

Insert command to copy the value of a parameter from one structure to another.

Parameters:
  • source_structure_id (int) – The ID of the source structure, between 0 and 15
  • source_parameter_index (int) – The index of the parameter in the source structure
  • destination_id (int) – The ID of the destination structure, or the ID of the destination register, between 0 and 15
  • destination_parameter_index (int) – The index of the parameter in the destination structure. Ignored when writing to a register.
  • destination_is_register (bool) – Indicates whether the destination is a structure or a register.
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If source_structure_id is not a valid structure ID
    • If destination_id is not a valid structure ID
    • If source_parameter_index is not a valid parameter index in the source structure
    • If destination_parameter_index is not a valid parameter index in the destination structure
  • NotAllocatedException
    • If no structure with ID destination_id has been allocated
    • If no structure with ID source_structure_id has been allocated
create_cmd(data, data_type=<DataType.UINT32: 2>)[source]

Creates command to write a value to the current write pointer, causing the write pointer to move on by the number of bytes required to represent the data type. The data is passed as a parameter to this function.

Note

This does not actually insert the WRITE command in the spec; that is done by write_cmd().

Parameters:
  • data (int or float) – the data to write.
  • data_type (DataType) – the type to convert data to
Returns:

cmd_word_list (binary data to be added to the binary data specification file), and cmd_string (string describing the command to be added to the report for the data specification file)

Return type:

tuple(bytearray, str)

Raises:
current_region

The ID of the current DSG region we’re writing to. If not yet writing to any region, None.

Return type:int or None
declare_random_number_generator(rng_id, rng_type, seed)[source]

Insert command to declare a random number generator

Parameters:
  • rng_id (int) – The ID of the random number generator
  • rng_type (RandomNumberGenerator) – The type of the random number generator
  • seed (int) – The seed of the random number generator >= 0
Raises:
declare_uniform_random_distribution(distribution_id, structure_id, rng_id, min_value, max_value)[source]

Insert commands to declare a uniform random distribution

Parameters:
  • distribution_id (int) – ID of the distribution being set up
  • structure_id (int) – ID of an empty structure slot to fill with the uniform random distribution data
  • rng_id (int) – The ID of the random number generator, between 0 and 15
  • min_value (float) – The minimum value that should be returned from the distribution between -32768.0 and max_value
  • max_value (float) – The maximum value that should be returned from the distribution between min_value and 32767.9999847
Raises:
define_break()[source]

Insert command to stop execution with an exception (for debugging)

Raises:
define_structure(structure_id, parameters)[source]

Insert commands to define a data structure

Parameters:
  • structure_id (int) – the ID of the structure to create, between 0 and 15
  • parameters (list(tuple(str, DataType, float))) –

    A list of between 1 and 255 tuples of (label, data_type, value) where:

    • label is the label of the element (for debugging)
    • data_type is the data type of the element
    • value is the value of the element, or None if no value is to
      be assigned
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • NoMoreException – If there are no more spaces for new structures
  • ParameterOutOfBoundsException
    • If there are an incorrect number of parameters
    • If the size of one of the tuples is incorrect
    • If one of the values to be assigned has an integer data_type but has a fractional part
    • If one of the values to be assigned would overflow its data_type
  • UnknownTypeException – If one of the data types in the structure is unknown
else_conditional()[source]

Insert command for the else of an if…then…else construct. If the condition of the conditional evaluates to false, the statements up between the conditional and the insertion of this “else” are skipped, and the statements from this point until the end of the conditional are executed.

Raises:
end_conditional()[source]

Insert command to mark the end of an if…then…else construct

Raises:
end_function()[source]

Insert command to mark the end of a function definition

Raises:InvalidCommandException – If there is no function being defined at this point
end_loop()[source]

Insert command to indicate that this is the end of the loop. Commands between the start of the loop and this command will be repeated.

Raises:
end_specification(close_writer=True)[source]

Insert a command to indicate that the specification has finished and finish writing

Parameters:

close_writer (bool) – Indicates whether to close the underlying writer(s)

Raises:
free_memory_region(region)[source]

Insert command to free a previously reserved memory region

Parameters:

region (int) – The number of the region to free, from 0 to 15

Raises:
get_structure_value(destination_id, structure_id, parameter_index, parameter_index_is_register=False)[source]

Insert command to get a value from a structure. The value is copied in a register.

Parameters:
  • destination_id (int) – The ID of the destination register
  • structure_id (int) – The ID of the source structure
  • parameter_index (int) – The ID of the parameter/element to copy
  • parameter_index_is_register (bool) – True if parameter_index is a register ID containing the ID of the parameter/element to copy
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If structure_id is not in the allowed range
    • If parameter_index is larger than the number of parameters declared in the original structure
    • If destination_id is not the ID of a valid register
    • If parameter_index_is_register is True and parameter_index is not a valid register ID
  • NotAllocatedException – If the structure requested has not been declared
logical_and(register_id, operand_1, operand_2, operand_1_is_register=False, operand_2_is_register=False)[source]

Insert command to perform a logical AND operation.

Parameters:
  • register_id (int) – The ID of the register to store the result in
  • operand_1 (int) –
    • If operand_1_is_register is True, the ID of a register where the first operand can be found, between 0 and 15
    • If operand_1_is_register is False, a 32-bit value
  • operand_2 (int) –
    • If operand_2_is_register is True, the ID of a register where the second operand can be found. between 0 and 15
    • If operand_2_is_register is False, a 32-bit value
  • operand_1_is_register (bool) – Indicates if operand_1 is a register ID
  • operand_2_is_register (bool) – Indicates if operand_2 is a register ID
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If register_id is not a valid register ID
    • If operand_1_is_register is True and operand_1 is not a valid register ID
    • If operand_2_is_register is True and operand_2 is not a valid register ID
logical_left_shift(register_id, operand_1, operand_2, operand_1_is_register=False, operand_2_is_register=False)[source]

Insert command to perform a logical left shift operation.

Parameters:
  • register_id (int) – The ID of the register to store the result in
  • operand_1 (int) –
    • If operand_1_is_register is True, the ID of a register where the first operand can be found, between 0 and 15
    • If operand_1_is_register is False, a 32-bit value
  • operand_2 (int) –
    • If operand_2_is_register is True, the ID of a register where the second operand can be found. between 0 and 15
    • If operand_2_is_register is False, a 32-bit value
  • operand_1_is_register (bool) – Indicates if operand_1 is a register ID
  • operand_2_is_register (bool) – Indicates if operand_2 is a register ID
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If register_id is not a valid register ID
    • If operand_1_is_register is True and operand_1 is not a valid register ID
    • If operand_2_is_register is True and operand_2 is not a valid register ID
logical_not(register_id, operand, operand_is_register=False)[source]

Insert command to perform a logical not operation.

Parameters:
  • register_id (int) – The ID of the register to store the result in
  • operand (int) –
    • If operand_is_register is True, the ID of a register where the first operand can be found, between 0 and 15
    • If operand_is_register is False, a 32-bit value
  • operand_is_register (bool) – Indicates if operand is a register ID
Raises:
logical_or(register_id, operand_1, operand_2, operand_1_is_register=False, operand_2_is_register=False)[source]

Insert command to perform a logical OR operation.

Parameters:
  • register_id (int) – The ID of the register to store the result in
  • operand_1 (int) –
    • If operand_1_is_register is True, the ID of a register where the first operand can be found, between 0 and 15
    • If operand_1_is_register is False, a 32-bit value
  • operand_2 (int) –
    • If operand_2_is_register is True, the ID of a register where the second operand can be found. between 0 and 15
    • If operand_2_is_register is False, a 32-bit value
  • operand_1_is_register (bool) – Indicates if operand_1 is a register ID
  • operand_2_is_register (bool) – Indicates if operand_2 is a register ID
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If register_id is not a valid register ID
    • If operand_1_is_register is True and operand_1 is not a valid register ID
    • If operand_2_is_register is True and operand_2 is not a valid register ID
logical_right_shift(register_id, operand_1, operand_2, operand_1_is_register=False, operand_2_is_register=False)[source]

Insert command to perform a logical right shift operation.

Parameters:
  • register_id (int) – The ID of the register to store the result in
  • operand_1 (int) –
    • If operand_1_is_register is True, the ID of a register where the first operand can be found, between 0 and 15
    • If operand_1_is_register is False, a 32-bit value
  • operand_2 (int) –
    • If operand_2_is_register is True, the ID of a register where the second operand can be found. between 0 and 15
    • If operand_2_is_register is False, a 32-bit value
  • operand_1_is_register (bool) – Indicates if operand_1 is a register ID
  • operand_2_is_register (bool) – Indicates if operand_2 is a register ID
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If register_id is not a valid register ID
    • If operand_1_is_register is True and operand_1 is not a valid register ID
    • If operand_2_is_register is True and operand_2 is not a valid register ID
logical_xor(register_id, operand_1, operand_2, operand_1_is_register=False, operand_2_is_register=False)[source]

Insert command to perform a logical xor operation.

Parameters:
  • register_id (int) – The ID of the register to store the result in
  • operand_1 (int) –
    • If operand_1_is_register is True, the ID of a register where the first operand can be found, between 0 and 15
    • If operand_1_is_register is False, a 32-bit value
  • operand_2 (int) –
    • If operand_2_is_register is True, the ID of a register where the second operand can be found. between 0 and 15
    • If operand_2_is_register is False, a 32-bit value
  • operand_1_is_register (bool) – Indicates if operand_1 is a register ID
  • operand_2_is_register (bool) – Indicates if operand_2 is a register ID
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If register_id is not a valid register ID
    • If operand_1_is_register is True and operand_1 is not a valid register ID
    • If operand_2_is_register is True and operand_2 is not a valid register ID
no_operation()[source]

Insert command to execute nothing

Raises:
print_struct(structure_id, structure_id_is_register=False)[source]

Insert command to print out a structure (for debugging)

Parameters:
  • structure_id (int) –
    • If structure_id_is_register is True, the ID of the register containing the ID of the structure to print, between 0 and 15
    • If structure_id_is_register is False, the ID of the structure to print, between 0 and 15
  • structure_id_is_register (bool) – Indicates if the structure_id is a register
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If structure_id_is_register is True and structure_id is not a valid register ID
    • If structure_id_is_register is False and structure_id is not a valid structure ID
  • NotAllocatedException – If structure_id_is_register is False and structure_id is the ID of a structure that has not been allocated
print_text(text, encoding='ASCII')[source]

Insert command to print some text (for debugging)

Parameters:
  • text (str) – The text to write (max 12 bytes once encoded)
  • encoding (str) – The character encoding to use for the string. Defaults to ASCII.
Raises:
print_value(value, value_is_register=False, data_type=<DataType.UINT32: 2>)[source]

Insert command to print out a value (for debugging)

Parameters:
  • value (float or int) –
    • If value_is_register is True, the ID of the register containing the value to print
    • If value_is_register is False, the value to print as a value of type given by data_type
  • value_is_register (bool) – Indicates if value is a register
  • data_type (DataType) – The type of the data to be printed
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If value_is_register is True and value is not a valid register ID
    • If value_is_register is False, the data_type is an integer type and value has a fractional part
    • If value_is_register is False and the value would overflow the data type
  • UnknownTypeException – If data_type is not a valid data type
read_value(dest_id, data_type)[source]

Insert command to read a value from the current write pointer, causing the write pointer to move by the number of bytes read. The data is stored in a register passed as argument.

Parameters:
  • dest_id (int) – The ID of the destination register.
  • data_type (DataType) – The type of the data to be read.
Raises:

ParameterOutOfBoundsException – If dest_id is out of range for a register ID

region_sizes

A list of sizes of each region that has been reserved.

Note

The list will include 0 for each non-reserved region.

Return type:list(int)
reserve_memory_region(region, size, label=None, empty=False, shrink=True)[source]

Insert command to reserve a memory region

Parameters:
  • region (int) – The number of the region to reserve, from 0 to 15
  • size (int) – The size to reserve for the region, in bytes
  • label (str or None) – An optional label for the region
  • empty (bool) – Specifies if the region will be left empty
  • shrink (bool) – Specifies if the region will be compressed
Raises:
save_write_pointer(register_id)[source]

Insert command to save the write pointer to a register

Parameters:

register_id (int) – The ID of the register to assign, between 0 and 15

Raises:
set_register_value(register_id, data, data_is_register=False, data_type=<DataType.UINT32: 2>)[source]

Insert command to set the value of a register

Parameters:
  • register_id (int) – The ID of the register to assign, between 0 and 15
  • data (int or float) –
    • If data_is_register is True, the register ID containing the data to set, between 0 and 15
    • If data_is_register is False, the data is a value of the type given by data_type
  • data_is_register (bool) – Indicates if data is a register ID
  • data_type (DataType) – The type of the data to be assigned
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If register_id is not a valid register ID
    • If data_is_register is True, and data is not a valid register ID
    • If data_is_register is False, data_type is an integer type and data has a fractional part
    • If data_is_register if False, and data would overflow the data type
  • UnknownTypeException – If the data type is not known
set_structure_value(structure_id, parameter_index, value, data_type, value_is_register=False)[source]

Insert command to set a value in a structure

Parameters:
  • structure_id (int) –
    • If called outside of a function, the ID of the structure, between 0 and 15
    • If called within a function, the ID of the structure argument, between 0 and 4
  • parameter_index (int) – The index of the value to assign in the structure, between 0 and the number of parameters declared in the structure
  • value (float) –
    • If value_is_register is False, the value to assign at the selected position as a float or int
    • If value_is_register is True, the ID of the register containing the value to assign to the position, between 0 and 15
  • data_type (DataType) – type of the data to be stored in the structure. If parameter value_is_register is set to true, this variable is disregarded
  • value_is_register (bool) – Identifies if value identifies a register
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If structure_id is not in the allowed range
    • If parameter_index is larger than the number of parameters declared in the original structure
    • If value_is_register is False, and the data type of the structure value is an integer, and value has a fractional part
    • If value_is_register is False, and value would overflow the position in the structure
    • If value_is_register is True, and value is not a valid register ID
  • NotAllocatedException – If the structure requested has not been declared
  • UnknownTypeException – If the data type is unknown
set_write_pointer(address, address_is_register=False, relative_to_current=False)[source]

Insert command to set the position of the write pointer within the current region

Parameters:
  • address (int) –
    • If address_is_register is True, the ID of the register containing the address to move to
    • If address_is_register is False, the address to move the write pointer to
  • address_is_register (bool) – Indicates if address is a register ID
  • relative_to_current (bool) – Indicates if address (or the value read from that register when address_is_register is True) is to be added to the current address, or used as an absolute address from the start of the current region
Raises:
start_conditional(register_id, condition, value, value_is_register=False)[source]

Insert command to start a conditional if…then…else construct. If the condition evaluates to true, the statement is executed up to the next else statement, or the end of the conditional, whichever comes first.

Parameters:
  • register_id (int) – The ID of a register to compare the value of
  • condition (Condition) – The condition which must be true to execute the following commands
  • value (int) –
    • If value_is_register is False, the value to compare to the value in the register
    • If value_is_register is True, the ID of the register containing the value to compare, between 0 and 15
  • value_is_register (bool) – Indicates if value is a register ID
Raises:
start_function(function_id, argument_by_value)[source]

Insert command to start a function definition, with up to 5 arguments, which are the IDs of structures to be used within the function, each of which can be passed by reference or by value. In the commands following this command up to the end_function() command, structures can only be referenced using the numbers 1 to 5 which address the arguments, rather than the original structure IDs

Parameters:
  • function_id (int) – The ID of the function currently defined.
  • argument_by_value (list(bool)) – A list of up to 5 booleans indicating if the structure to be passed as an argument is to be passed by reference (i.e., changes made within the function are persisted) or by value (i.e., changes made within the function are lost when the function exits. The number of arguments is determined by the length of this list.
Raises:
start_loop(counter_register_id, start, end, increment=1, start_is_register=False, end_is_register=False, increment_is_register=False)[source]

Insert command to start a loop

Parameters:
  • counter_register_id (int) – The ID of the register to use as the loop counter, between 0 and 15
  • start (int) –
    • If start_is_register is False, the number at which to start the loop counter, >= 0
    • If start_is_register is True, the ID of the register containing the number at which to start the loop counter, between 0 and 15
  • end (int) –
    • If end_is_register is False, the number which the loop counter must reach to stop the loop i.e. the loop will run while the contents of counter_register < end, >= 0
    • If end_is_register is True, the ID of the register containing the number at which to stop the loop, between 0 and 15
  • increment (int) –
    • If increment_is_register is False, the amount by which to increment the loop counter on each run of the loop, >= 0
    • If increment_is_register is True, the ID of the register containing the amount by which to increment the loop counter on each run of the loop, between 0 and 15
  • start_is_register (bool) – Indicates if start is a register ID
  • end_is_register (bool) – Indicates if end is a register ID
  • increment_is_register (bool) – Indicates if increment is a register ID
Raises:
  • DataUndefinedWriterException – If the binary specification file writer has not been initialised
  • IOError – If a write to external storage fails
  • ParameterOutOfBoundsException
    • If counter_register_id is not a valid register ID
    • If start_is_register is True and start is not a valid register ID
    • If end_is_register is True and end is not a valid register ID
    • If increment_is_register is True, and increment is not a valid register ID
    • If start_is_register is False and ``start is not in the allowed range
    • If end_is_register is False and ``end is not in the allowed range
    • If increment_is_register is False and increment is not in the allowed range
switch_write_focus(region)[source]

Insert command to switch the region being written to

Parameters:

region (int) – The ID of the region to switch to, between 0 and 15

Raises:
write_array(array_values, data_type=<DataType.UINT32: 2>)[source]

Insert command to write an array, causing the write pointer to move on by (data type size * the array size), in bytes.

Parameters:
Raises:
write_cmd(cmd_word_list, cmd_string)[source]

Applies write commands created previously created (and cached).

Note

See create_cmd() for how to create the arguments to this method.

Parameters:
  • cmd_word_list (bytearray) – list of binary words to be added to the binary data specification file
  • cmd_string (str) – string describing the command to be added to the report for the data specification file
Raises:
write_repeated_value(data, repeats=1, repeats_is_register=False, data_type=<DataType.UINT32: 2>)[source]

Insert command to write a value one or more times to the current write pointer, causing the write pointer to move on by the number of bytes required to represent the data type. The data is passed as a parameter to this function

Parameters:
  • data (float or int) – the data to write as a float.
  • repeats (int) –
    • If repeats_is_register is False, this parameter identifies the number of times to repeat the data, between 1 and 255 (default 1)
    • If repeats_is_register is True, this parameter identifies the register that contains the number of repeats.
  • repeats_is_register (bool) – Indicates if the parameter repeats identifies the register containing the number of repeats of the value to write
  • data_type (DataType) – the type to convert data to
Raises:
write_structure(structure_id, repeats=1, repeats_is_register=False)[source]

Insert command to write a structure to the current write pointer, causing the current write pointer to move on by the number of bytes needed to represent the structure

Parameters:
  • structure_id (int) –
    • If called within a function, the ID of the structure to write, between 0 and 15
    • If called outside of a function, the ID of the structure argument, between 0 and 5
  • repeats (int) –
    • If repeats_is_register is True, the ID of the register containing the number of repeats, between 0 and 15
    • If repeats_is_register is False, the number of repeats to write, between 0 and 255
  • repeats_is_register (bool) – Whether repeats identifies a register
Raises:
write_value(data, data_type=<DataType.UINT32: 2>)[source]

Insert command to write a value (once) to the current write pointer, causing the write pointer to move on by the number of bytes required to represent the data type. The data is passed as a parameter to this function

Note

This method used to have two extra parameters repeats and repeats_is_register. They have been removed here. If you need them, use write_repeated_value()

Parameters:
  • data (int or float) – the data to write as a float.
  • data_type (DataType) – the type to convert data to
Raises:
write_value_from_register(data_register, repeats=1, repeats_is_register=False, data_type=<DataType.UINT32: 2>)[source]

Insert command to write a value one or more times at the write pointer of the current memory region, causing it to move. The data is contained in a register whose ID is passed to the function

Parameters:
  • data_register (int) – Identifies the register in which the data is stored.
  • repeats (int) –
    • If repeats_is_register is None, this parameter identifies the number of times to repeat the data, between 1 and 255 (default 1)
    • If repeats_is_register is not None (i.e. has an integer value), the content of this parameter is disregarded
  • repeats_is_register (bool) – Identifies if repeats is the register containing the number of repeats of the value to write
  • data_type (DataType) – the type of the data held in the register
Raises:
class data_specification.MemoryRegion(unfilled, size)[source]

Memory region storage object.

Parameters:
  • unfilled (bool) – if the region should not be written to by the data specification (i.e., because the vertex uses it as a working data region or an output region)
  • size (int) – the size of the region, in bytes
allocated_size

The size of the region.

Return type:int
increment_write_pointer(n_bytes)[source]

Advance the write pointer.

Parameters:n_bytes (int) – The number of bytes to advance the pointer by.
max_write_pointer

The max point where if written over, it will cause an error.

Return type:int
region_data

The buffer which holds the data written in this region.

Return type:bytearray
remaining_space

The space between the current write pointer and the end of the region, which is the number of bytes remaining in the region that can be written.

Return type:int
unfilled

Whether the region is marked as not fillable; unfilled regions will not contain any data at write time.

Return type:bool
write_pointer

The position in the buffer where data will be written to next.

Return type:int
class data_specification.MemoryRegionCollection(n_regions)[source]

Collection of memory regions.

Parameters:n_regions (int) – The number of regions in the collection.
count_used_regions()[source]

The number of regions in the collection that are used.

Return type:int
is_empty(region)[source]
Parameters:region (int) – The ID of the region
Return type:bool
is_unfilled(region)[source]
Parameters:region (int) – The ID of the region
Return type:bool
needs_to_write_region(region)[source]

Helper method which determines if a unfilled region actually needs to be written (optimisation to stop large data files).

Parameters:region (int) – the region ID to which the test is being ran on
Returns:whether the region needs to be written
Return type:bool
Raises:NoRegionSelectedException – when the ID is beyond the expected region range
regions

The regions in the collection.

Return type:iterable(MemoryRegion)

Indices and tables