Base

This contains a series of base classes which are inherited by the board and protocol classes.

Definitions

exception ska_low_sps_tpm_api.base.definitions.BoardError

Define an exception which occurs when an operation occuring on an FPGA boards returns an error

class ska_low_sps_tpm_api.base.definitions.BoardMake(value)

BoardMake enumeration

Roach2Board = 3

RoachBoard = 2

TpmBoard = 1

UniboardBoard = 4

class ska_low_sps_tpm_api.base.definitions.Device(value)

Device enumeration

Board = 65536

FPGA_1 = 1

FPGA_2 = 2

FPGA_3 = 4

FPGA_4 = 8

FPGA_5 = 16

FPGA_6 = 32

FPGA_7 = 64

FPGA_8 = 128

exception ska_low_sps_tpm_api.base.definitions.InstrumentError

Define an exception which occurs when an operation occuring within the instrument returns an error

exception ska_low_sps_tpm_api.base.definitions.LibraryError

Define an exception which occurs when an operation occuring within the library returns an error

class ska_low_sps_tpm_api.base.definitions.Permission(value)

Permission enumeration

Read = 1

ReadWrite = 3

Write = 2

exception ska_low_sps_tpm_api.base.definitions.PluginError

Define an exception which occurs when an operation occuring within a plugin returns an error

class ska_low_sps_tpm_api.base.definitions.PluginList(iterable=(), /)

class ska_low_sps_tpm_api.base.definitions.RegisterInfo(name, address, reg_type, device, permission, bitmask, bits, shift, value, size, desc)

Class representing REGISTER_INFO struct

__init__(name, address, reg_type, device, permission, bitmask, bits, shift, value, size, desc)

class ska_low_sps_tpm_api.base.definitions.RegisterType(value)

RegisterType enumeration

BoardRegister = 2

Component = 5

FifoRegister = 6

FirmwareRegister = 3

SPIDevice = 4

Sensor = 1

class ska_low_sps_tpm_api.base.definitions.SPIDeviceInfo(name, spi_sclk, spi_en)

Class representing SPI_DEVICE_INFO struct

__init__(name, spi_sclk, spi_en)

class ska_low_sps_tpm_api.base.definitions.Status(value)

Status enumeration

BoardError = -3

ConfigError = -2

FirmwareError = -6

LoadingFirmware = -1

LoadingFirmwareError = -7

NetworkError = -5

NotConnected = -4

OK = 0

class ska_low_sps_tpm_api.base.definitions.Values(values, error)

Class representing VALUES struct

__init__(values, error)

ska_low_sps_tpm_api.base.definitions.compatibleboards(*args)

Add board compatability to funtion.

Parameters:

args – Compatible boards

Returns:

Decorated class

ska_low_sps_tpm_api.base.definitions.firmware(*args)

A plugin can be associated with a particular firmware.

Parameters:

args – Design name string or dictionary containing design and verion

Returns:

Decorated class

ska_low_sps_tpm_api.base.definitions.friendlyname(*args)

Add board compatability to funtion.

Parameters:

args – Compatible boards

Returns:

Decorated class

ska_low_sps_tpm_api.base.definitions.maxinstances(*args)

Maximum number of instances the plugin can be loaded.

Parameters:

args – Number of instances

Returns:

Decorated class

Memory Map

class ska_low_sps_tpm_api.base.memory_map.MemoryMap(logger=None)

Class which represents a Memory Map

__init__(logger=None)

class constructor

Parameters:

logger – Logger instance

add_register_entry(device, register, address, offset)

Add register entry.

Parameters:

• device – Device to which the register belongs to

• register – Register name

• address – Register address

• offset – Offset

clear()

Reset memory map

has_register(register)

Check if memory map contains specified register.

Parameters:

register – Register to check

update_memory_map(xml_string, device, base_address)

Update memory map.

Parameters:

• xml_string – XML string to use to update memory map

• device – Device to use

• base_address – Base address to offset addresses in memory map

Protocol

class ska_low_sps_tpm_api.base.protocol.Protocol(board)

Class representing a communication protocol with an FPGA board

__init__(board)

Class constructor

close_connection()

Close connection

create_connection(ip, port)

Create connection.

Parameters:

• ip – Remote IP

• port – Remote port

get_ip()

get_port()

list_firmware()

Get the list of downloaded firmware

read_register(address, n, offset)

Read register value from board.

Parameters:

• address – Address to read from

• n – Number of values to read

• offset – Offset to read from

write_register(address, values, offset)

Write values to register.

Parameters:

• address – Address to write to

• values – Values to write

• offset – Offset to write to

SPI

class ska_low_sps_tpm_api.base.spi.SPI(xml_string)

A class which handles information on SPI devices

__init__(xml_string)

class constructor.

Parameters:

xml_string – XML string containing SPI device information

clear()

Clear SPI map

has_device(device)

Check if spi map contains specified device.

Parameters:

device – Device to check

Utilities

ska_low_sps_tpm_api.base.utils.add_list(aList, bArg)

Element by element add list b to list a or add value b to each element in list a

ska_low_sps_tpm_api.base.utils.all_equal_to(lst, value)

Returns True if all the list elements equal ‘value’.

ska_low_sps_tpm_api.base.utils.all_the_same(lst)

Returns True if all the list elements are identical.

ska_low_sps_tpm_api.base.utils.bit_list_to_mask(bit_list)

Converts a list of bit indexes to an integer

ska_low_sps_tpm_api.base.utils.ceil_div(num, den)

ska_low_sps_tpm_api.base.utils.ceil_log2(num)

ska_low_sps_tpm_api.base.utils.concat_complex(list_complex, width_in_bits)

Concatenates the real and imaginary part into one integer. The specifed width counts for both the real and imaginary part. Real part is mapped on the LSB. Imaginary part is shifted to the MSB.

ska_low_sps_tpm_api.base.utils.convert_uint_to_string(data)

Convert list of 32-bit unsigned integers to string.

Parameters:

data – input data

Returns:

converted string representation

ska_low_sps_tpm_api.base.utils.deinterleave(input_stream, nof_out, block_size=1)

Deinterleave a stream (=flat list) into nof_out output streams based on block_size. >> deinterleave( [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16], 4, 2 ) >> [ [1,2,9,10], [3,4,11,12], [5,6,13,14], [7,8,15,16] ] Note: len(input_stream)/nof_out/block_size should yield an integer. Note: This method behaves exactly like common_deinterleave.vhd.

ska_low_sps_tpm_api.base.utils.depth(x)

Returns the depth of x. Returns 0 if x is not iterable (not a list or tuple).

ska_low_sps_tpm_api.base.utils.do_until(method, val, op=<built-in function eq>, ms_retry=10, s_timeout=4, **kwargs)

Default: DO [method] UNTIL [method==val] Example: do_until( self.read_status, 0) will execute self.read_status() until all elements in the returned list equal 0. Use **kwargs to pass keyworded arguments to the input method; Use ms_retry to set the time in milliseconds before rerunning the method; Use s_timeout to set the time in seconds before timeout occurs (returns 1). Use s_timeout < 0 to disable the time out All standard Python operators (see operator class) are supported, the default is eq (equal to).

ska_low_sps_tpm_api.base.utils.do_until_eq(method, val, ms_retry=10, s_timeout=4, **kwargs)

ska_low_sps_tpm_api.base.utils.do_until_ge(method, val, ms_retry=10, s_timeout=4, **kwargs)

ska_low_sps_tpm_api.base.utils.do_until_gt(method, val, ms_retry=10, s_timeout=4, **kwargs)

ska_low_sps_tpm_api.base.utils.do_until_le(method, val, ms_retry=10, s_timeout=4, **kwargs)

ska_low_sps_tpm_api.base.utils.do_until_lt(method, val, ms_retry=10, s_timeout=4, **kwargs)

ska_low_sps_tpm_api.base.utils.do_until_ne(method, val, ms_retry=10, s_timeout=4, **kwargs)

ska_low_sps_tpm_api.base.utils.flatten(x)

Flatten lists of lists of any depth. Preserves tuples.

ska_low_sps_tpm_api.base.utils.format_data(B_bytes)

Formats data rate based on size in appropriate units B, KiB, MiB, GiB

ska_low_sps_tpm_api.base.utils.get_octet_from_ip(ip, octet)

Extract an octect from an IP address string. Example: 10.135.0.12, Octet 1 is 10, Octet 4 is 12.

Parameters:

• ip (str) – IP address

• octet (int) – Octet to extract

Returns:

Octet contents

Return type:

int

ska_low_sps_tpm_api.base.utils.greatest_common_div(A, B)

Find the greatest common divisor of A and B.

ska_low_sps_tpm_api.base.utils.high_bits(datum, bits)

Return location of on bits in datum.

Parameters:

• datum – Datum

• bits – Number of bits in datum

Returns:

Array containing locations of high bits

ska_low_sps_tpm_api.base.utils.index_a_in_b(a, b, duplicates=False)

Find the elements of list a in list b and return their indices (relative to b). Does not return duplicates by default.

ska_low_sps_tpm_api.base.utils.index_a_in_multi_b(a, b)

Find a in multi-dimensional list b. Returns first hit only.

ska_low_sps_tpm_api.base.utils.insert(orig, new, pos)

Inserts new (string, element) inside original string or list at pos.

ska_low_sps_tpm_api.base.utils.int_clip(inp, w)

Purpose : Clip an integer value to w bits Input:

• inp = Integer value

• w = Output width in number of bits

Description: Output range -2**(w-1) to +2**(w-1)-1 Return:

• outp = Clipped value

ska_low_sps_tpm_api.base.utils.int_requantize(inp, inp_w, outp_w, lsb_w=0, lsb_round=False, msb_clip=False, gain_w=0)

Purpose : Requantize integer value similar as common_requantize.vhd Input:

• inp = Integer value

• inp_w = Input data width

• outp_w = Output data width

• lsb_w = Number of LSbits to truncate

• lsb_round = when true round else truncate the input LSbits

• msb_clip = when true clip else wrap the input MSbits

• gain_w = Output gain in number of bits

Description: First round or truncate the LSbits, then clip or wrap the MSbits and then apply optional output gain Return:

• outp = Requantized value

ska_low_sps_tpm_api.base.utils.int_round(inp, w, direction='HALF_AWAY')

Purpose : Round the w LSbits of an integer value Input:

• inp = Integer value

• w = Number of LSbits to round

• direction = “HALF_AWAY”, “HALF_UP”

Description: direction = “HALF_AWAY” –> Round half away from zero so +0.5 –> 1, -0.5 –> -1. direction = “HALF_UP” –> Round half to +infinity so +0.5 –> 1, -0.5 –> 0.

Return:

• outp = Rounded value

ska_low_sps_tpm_api.base.utils.int_truncate(inp, w)

Purpose : Truncate the w LSbits of an integer value Input:

• inp = Integer value

• w = Number of LSbits to truncate

Description: Remove LSBits. Return:

• outp = Truncated value

ska_low_sps_tpm_api.base.utils.int_wrap(inp, w)

Purpose: Wrap an integer value to w bits Input:

• inp = Integer value

• w = Output width in number of bits

Description: Remove MSbits, output range -2**(w-1) to +2**(w-1)-1 Return:

• outp = Wrapped value

ska_low_sps_tpm_api.base.utils.interleave(input_streams, block_size=1)

Interleave a list of multiple lists into one based on block size. Note: This method behaves exactly like common_interleave.vhd.

ska_low_sps_tpm_api.base.utils.ip2long(ip)

Convert an IP string to long

ska_low_sps_tpm_api.base.utils.ip_str(ip)

Converts an IP address integer to a human-readable string.

Parameters:

ip (int) – IP address

Returns:

IP address

Return type:

str

ska_low_sps_tpm_api.base.utils.largest(a, b)

ska_low_sps_tpm_api.base.utils.list_duplicates(in_list)

find duplicate list elements

ska_low_sps_tpm_api.base.utils.listify(x)

Can be used to force method input to a list.

ska_low_sps_tpm_api.base.utils.long2ip(ip)

Convert long to IP string

ska_low_sps_tpm_api.base.utils.mac_str(mac)

Converts MAC address integer to the hexadecimal string representation, separated by ‘:’.

Parameters:

mac (int) – MAC address

Returns:

MAC address

Return type:

str

ska_low_sps_tpm_api.base.utils.max_abs(data)

ska_low_sps_tpm_api.base.utils.method_arg_names(method)

Returns the names of the arguments of passed method.

ska_low_sps_tpm_api.base.utils.method_name(caller_depth=0)

Returns the name of the caller method.

ska_low_sps_tpm_api.base.utils.pad(lst, length, padding=' ')

Pad a list up to length with padding

ska_low_sps_tpm_api.base.utils.reinterleave(input_streams, nof_out, block_size_in=1, block_size_out=1)

Re-interleave X input streams across nof_out output streams. The input streams are first deinterleaved with block_size_in, then nof_out interleaved streams are made with block_size_out. Note: This method behaves exactly like common_reinterleave.vhd.

ska_low_sps_tpm_api.base.utils.reverse_byte(byte)

Fast way to reverse a byte on 64-bit platforms.

ska_low_sps_tpm_api.base.utils.reverse_word(word)

Fast way to reverse a word on 64-bit platforms.

ska_low_sps_tpm_api.base.utils.rotate_list(in_list, n)

Rotates the list. Positive numbers rotate left. Negative numbers rotate right.

ska_low_sps_tpm_api.base.utils.sel_a_b(sel, a, b)

ska_low_sps_tpm_api.base.utils.signed32(v)

ska_low_sps_tpm_api.base.utils.signed64(v)

ska_low_sps_tpm_api.base.utils.smallest(a, b)

ska_low_sps_tpm_api.base.utils.split_complex(list_complex)

Returns the real and imaginary part in two separate lists. [list_re, list_im] = split_complex(list_complex)

ska_low_sps_tpm_api.base.utils.split_list(source_list, split_size, sublist_items=None)

Splits a list based on split_size. Optionally, the indices passed in sublist_items are extracted from each sublist.

ska_low_sps_tpm_api.base.utils.straighten(matrix, padding=' ')

Straighten a crooked matrix by padding the shorter lists with the padding up to the same length as the longest list.

ska_low_sps_tpm_api.base.utils.subtract_list(aList, bArg)

Element by element subract list b from list a or subract value b from each element in list a

ska_low_sps_tpm_api.base.utils.swap32(x)

ska_low_sps_tpm_api.base.utils.to_signed(arg, width)

Interpret arg value[width-1:0] or list of arg values as signed (two’s complement)

ska_low_sps_tpm_api.base.utils.to_unsigned(arg, width)

Interpret value[width-1:0] as unsigned

ska_low_sps_tpm_api.base.utils.transpose(matrix)

Transpose by using zip()

ska_low_sps_tpm_api.base.utils.tuplefy(x)

Similar to listify(). This method enables user to iterate through tuples of inconsistent depth by always returning a non-flat tuple. Pushes a flat tuple (depth=1) e.g. (0,1,2) one level deeper: ( (0,1,2), ). Non-flat tuples are returned untouched. A non-tuple (depth=0) is also pushed into a tuple 2 levels deep.

ska_low_sps_tpm_api.base.utils.unique(in_list)

Extract unique list elements (without changing the order like set() does)

ska_low_sps_tpm_api.base.utils.unlistify(x)

Converts 1-element list to x.