Low-level software tools¶
Note that most or all of the tools described below, likely have python equivalents, which are described elsewhere (?).
tpx4item¶
Description¶
The tpx4item tool allows a user to read or write an item in a Timepix4 device connected to a SPIDR4. An item is a register address or name, or the name of a bit field.
Item names adhere to the ‘official’ naming in the Timepix4 manual.
The names are case insensitive and ‘_’ and ‘-‘
characters in the name are treated identically.
Register names have to start with “reg_” followed by the name
as presented in the manual, while bit field names are preceded
by their register name, but without “reg_”.
To see a full list of registers and bit fields, including meta-information
on each such as address and size, type tpx4item list.
A name does not have to be the ‘complete’ name, but must be unique
in the list of Timepix4 item names;
for example: “pixel-bo” is sufficient to select the bit field
named in full by the tool as: “PIXEL_BOT_PIXEL_COLUMN_CONFIG”.
In case the name given does not uniquely match a single named register or bit field
a list of names is shown (either registers or bit fields) that match
with the given name string.
In the case of bit fields this can be a list of names that contain
the given item string anywhere in their full name (try for example tpx4item top).
If no SPIDR4 controller address (option -c) is given, information about the item is displayed, such as full name, (base) address, size in bits and a description. After being read out from a Timepix4 device, registers and bit fields are displayed most-significant part first. If a value is provided in addition to item name or address, that value is written into the Timepix4 item, if the value is valid and within the item’s value range. Multiple registers or bit fields of the same ‘type’ may be read or written in one operation.
This is the ‘usage’ of tpx4item, listing the available options:
Usage: tpx4item [-h|E|v] [-c <addr>] [-r <index>|-R] [-s <size> -i <index>]
[-I<stride>] <item_name>|<addr>|list [val]
Options:
-h : Show this help text.
-E : Show a number of examples using tpx4item.
-v : Show the version number.
-c <addr> : (IP) address of the SPIDR4 Controller,
or select by number from this list:
0 = 192.168.1.10
1 = 192.168.100.10
2 = 192.16.192.232
-r <index> : Register index (in case of multiple registers),
in case a register name or bitfield name is given.
-R : Read or write *all* registers or bitfields
with the given name (instead of option -r).
-s <size> : Separate a bitfield into sub-fields of <size> bits each.
-i <index> : Single sub-field index to read or write
(in combination with option -s).
-I <stride>: The 'stride' or increment, in number of sub-fields with a size
as defined by option -s: write each 'stride'-th field.
Reading is always with 'stride'=1 (read all sub-fields).
(in combination with option -s; instead of option -i; default: 0).
<item_name> : A name such as REG_ROUTER_BOT or reg-router-b,
or ROUTER_BOT_CHAN_ENABLE or router-bot-chan, etc.
(bitfields are named preceeded by their register 'abbreviation')
(names are case-insensitive, use 'list' to see all known names).
<addr> : A register address (hexadecimal; "0x" not required).
list : (as literal string) Display meta-info on all known registers followed
by all known bitfields, one line per register or bitfield,
in a column-wise fashion.
<val> : if provided the value is written to the item on the Timepix4 device
(bitfield, register of sub-field; hex (with 0x) or decimal);
if no value is given the item value is read out and displayed.
If *no* SPIDR4 Controller address is provided,
only meta-information about the item is displayed.
Examples with tpx4item¶
Below find some examples of tpx4item tool usage, all with option “-c 2”, meaning a SPIDR4 Controller at IP address 192.16.192.232 is addressed.
Read a register by address, register name or field name, respectively:
# tpx4item -c 2 6100
SPIDR4 Controller @ 192.16.192.232
->Info: name=REG_PIXEL_GR_BOT (base)address=0x6100 (3584x) bytes=32 "PixelGroupBottom"
Register 0x6100: (MSByte first)
30 28 A0 A3 69 20 29 A8 70 00 31 4B 11 20 A4 B1 08 01 6D 21 60 67 20 23 4B 6C 20 22 ED 30 4B 24
# tpx4item -c 2 reg-pixel-gr-bot
SPIDR4 Controller @ 192.16.192.232
->Info: name=REG_PIXEL_GR_BOT (base)address=0x6100 (3584x) bytes=32 "PixelGroupBottom"
Register 0x6100: (MSByte first)
30 28 A0 A3 69 20 29 A8 70 00 31 4B 11 20 A4 B1 08 01 6D 21 60 67 20 23 4B 6C 20 22 ED 30 4B 24
# tpx4item -c 2 pixel-gr-bot
SPIDR4 Controller @ 192.16.192.232
->Info: name=PIXEL_GR_BOT_PIXEL_GROUP_CONFIG (base)address=0x6100 (3584x) R/W bits=256 [255:0]
"Pixel configuration data"
Bitfield in Register 0x6100: (MSByte first)
30 28 A0 A3 69 20 29 A8 70 00 31 4B 11 20 A4 B1 08 01 6D 21 60 67 20 23 4B 6C 20 22 ED 30 4B 24
Read third byte (“-s 8 -i 2”) of this register:
# tpx4item -c 2 -s 8 -i 2 pixel-gr-bot
SPIDR4 Controller @ 192.16.192.232
->Info: name=PIXEL_GR_BOT_PIXEL_GROUP_CONFIG (base)address=0x6100 (3584x) R/W bits=256 [255:0]
"Pixel configuration data"
Bitfield in Register 0x6100 (subfield=8bits,index=2,stride=0):
30
Write 0 to 3rd byte (“-i 2”) in the register:
# tpx4item -c 2 -s 8 -i 2 pixel-gr-bot 0
Write 0 to all bytes (“-s 8 -I 1”) in the register:
# tpx4item -c 2 -s 8 -I 1 pixel-gr-bot 0
Write 0x34 to all bytes in the register starting from byte 10 (“-i 10”):
# tpx4item -c 2 -s 8 -I 1 -i 10 pixel-gr-bot 0x33
Reading back the result of this operation (note the least-significant byte is the right-most displayed byte):
# tpx4item -c 2 pixel-gr-bot
SPIDR4 Controller @ 192.16.192.232
->Info: name=PIXEL_GR_BOT_PIXEL_GROUP_CONFIG (base)address=0x6100 (3584x) R/W bits=256 [255:0]
"Pixel configuration data"
Bitfield in Register 0x6100: (MSByte first)
33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 00 00 00 00 00 00 00 00 00 00
Set every 8th bit (“-s 1 -I 8”) in the register starting from bit 7 (“-i 7”) to 1:
# tpx4item -c 2 -s 1 -I 8 -i 7 pixel-gr-bot 1
Reading back the result of this operation:
# tpx4item -c 2 pixel-gr-bot
SPIDR4 Controller @ 192.16.192.232
->Info: name=PIXEL_GR_BOT_PIXEL_GROUP_CONFIG (base)address=0x6100 (3584x) R/W bits=256 [255:0]
"Pixel configuration data"
Bitfield in Register 0x6100: (MSByte first)
B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 80 80 80 80 80 80 80 80 80 80
To do the same in a selected register of the 3584 registers of this type use option “-r <index>”. To do the same to all 3584 registers at once use option “-R”.
tpx4reset¶
Tool tpx4reset instructs the SPIDR4 to execute either a pixel matrix reset or a ‘full’ reset (including various configuration actions) on the (for the time being, single) connected Timepix4 chip:
$ tpx4reset -c 2
SPIDR4 Controller @ 192.16.192.232
Matrix reset TPX4 OKAY
$ tpx4reset -c 2 -F
SPIDR4 Controller @ 192.16.192.232
Reset TPX4 OKAY
spidr4reg¶
Description¶
The spidr4reg tool allows a user to read and write the 32-bit registers defined in the SPIDR4 board.
This is the ‘usage’ of spidr4reg:
$ spidr4reg -h
Usage: spidr4reg [-h|v] [-c <addr>] [-R] <reg_name>|<address>|list [val]
-h : Show this help text.
-v : Show the version number.
-c <addr> : (IP) address of the SPIDR4 Controller,
or select by number from this list:
0 = 192.168.1.10
1 = 192.168.100.10
2 = 192.16.192.232
-R : Reads and displays all registers.
<reg_name> : a name such as TriggerControl or TRIGGERC
<address> : a register address (hexadecimal).
list : (as literal string) Display meta-info on all known registers,
one line per register, in a column-wise fashion.
<val> : if provided the value is written to the register,
if no value is given the item value is read out and displayed.
If *no* SPIDR4 controller address is provided,
only meta-information about the register is displayed.
Examples with spidr4reg¶
Write a value to register TRIGGER_CONTROL:
$ spidr4reg -c 2 trigger-c 1234
SPIDR4 Controller @ 192.16.192.232
Register 0x43C00004: Write 0x4D2 OKAY
Reading back register TRIGGER_CONTROL gives both information about the register and the register contents:
$ spidr4reg -c 2 trigger-c
SPIDR4 Controller @ 192.16.192.232
->Info: name=TRIGGER_CONTROL address=0x0004 "Trigger mode, reset, start/stop auto, etc"
Register 0x43C00004: 0x000004D2
Read all known (named) SPIDR4 registers:
$ spidr4reg -R -c 2
SPIDR4 Controller @ 192.16.192.232
0x43C00000: 00000BA5 FIRMWARE_VERSION
0x43C00004: 00000000 TRIGGER_CONTROL
0x43C00008: 00000000 TRIGGER_FREQUENCY
0x43C0000C: 00000000 TRIGGER_PERIOD
0x43C00010: AAAAAAAA EXTERNAL_TRIGGER_COUNTER
0x43C00014: BBBBBBBB EXTERNAL_SHUTTER_COUNTER
0x43C00018: 00002BA8 FAN_CONTROL
0x43C0001C: 00000000 FAN_READ
0x43C00020: 00000000 MAC_SRC1_MSB
0x43C00024: 00000000 MAC_SRC1_LSB
0x43C00028: 00000000 MAC_SRC2_MSB
0x43C0002C: 00000000 MAC_SRC2_LSB
0x43C00030: 00000000 MAC_DST1_MSB
0x43C00034: 00000000 MAC_DST1_LSB
0x43C00038: 00000000 MAC_DST2_MSB
0x43C0003C: 00000000 MAC_DST2_LSB
0x43C00040: 00000000 IP_SRC1
0x43C00044: 00000000 IP_SRC2
0x43C00048: 00000000 IP_DST1
0x43C0004C: 00000000 IP_DST2
0x43C00050: 00000000 PORT_SRC1
0x43C00054: 00000000 PORT_SRC2
0x43C00058: 00000000 PORT_DST1
0x43C0005C: 00000000 PORT_DST2
0x43C00060: 00000000 SFP_CONFIG
0x43C00064: 00000000 EMULATOR_CTRL
0x43C00068: 00000000 SC_TX_DATA
0x43C0006C: 00000000 SC_RX_DATA
0x43C00070: 000000C0 SC_CTRL
0x43C00074: 00000005 SC_STATUS
0x43C00078: 00000000 DELAY_CONTROL
0x43C0007C: 99A8CC14 FPGA_BITFILE_DATE
spidr4restart¶
Tool spidr4restart allows a user to restart the control application on the SPIDR4:
$ spidr4restart -c 2
SPIDR4 Controller @ 192.16.192.232
Restart OKAY
spidr4version¶
Tool spidr4version displays version and commit info about the SPIDR4 controller application software, plus a serial number of the module:
$ spidr4version -c 2
SPIDR4 Controller @ 192.16.192.232
Version: 'SPIDR4 Control', Version: 0.0.0, Build: 2021-08-30T10:16:37Z
Commit : master-cfcf437-dirty
Serial : 1000801F12C356E9