DTH Access Library’s documentation

This library contains a class “DTH” which can be used to access the functionalities of the DTH.

Contents:

Indices and tables

DTH API

class dth.dthlib.DTH(adrtable, vendor=4316, device=437, index=0)

A class with high and low level functionalities for the DTH.

The class is derived from the pyHal PCIDevice. Inherited methods from the PCIDevice are not further documented here. But all methods are listed.

__init__(adrtable, vendor=4316, device=437, index=0)

The constructor of the DTH class

This constructor needs to have all arguments which the constructor of the PCIDevice C++ class, from which it inherits, has. The reason is that the C++ constructor is called immediately when the python constructor is called and not only when “super()” is called as in pure python classes. Default parameters are set to the correct values for board version p1-v2 (the DTH Kit).

The constructor expects a file “DTH_control_parameters.json” in the working directory holding some essential configuration parameters. An example file is shown here. The entries are mostly self explaining:

{
 "sourceIp" : "192.168.01.16", 
 "destIp" : "192.168.1.100",
 "sourcePort0" : 10000,
 "destPort0" : 10000 ,
 "sourcePort1" : 10010,
 "destPort1" : 10000 ,
 "FF_CDR" : 1,
 "SR0" : 1, 
 "SR1" : 1,
 "FED_ID0" : 1230,
 "FED_ID1" : 1231
}

The SRn parameters indicate which of the possible SlinkRocket links are active. For each Slink Rocket link a dedicated TCP/IP stream is set up and hence source and destination ports need to be defined for every link. Each Slink Rocket Link is associated with a FED_ID. FF_CDR stands for FireFly CDR and can be used to explicitely switch on (‘1’) or off (‘0’) the CDR.

reset_global()

Resets the entire DTH logic.

The following components are reset:

  • I2C chains
  • FireFly optics
  • UltraRam logic
  • Monitoring counters
reset_sender()

Reset if the Slink sender logik in the DTH of the DTH-Kit.

The firmware of the DTH-Kit includes some SlinkRocket sender cores for test purposes (with a loopback-connector). These Slink sender blocks are reset by this function. This logic DOES NOT send a reset to Slink sender cores implemented in other boards (e.g. FEDs). No command is sent via the Slink.

read_slinksender(adr, SR_channel)

Read some information from the Slink sender Core.

This function sends a “read” command over the Slink Rocket link to the sender core and sends back the result to the DTH.

Parameters:
  • adr – The address of the item to read from the sender core.
  • SR_channel – The Slink Rocket Channel number to idenfify the link to be read.
write_slinksender(adr, data, SR_channel)

Write some data to the Slink sender Core.

This function sends a “write” command over the Slink Rocket link to the sender core.

Parameters:
  • adr – The address of the item to read from the sender core.
  • data – The 32bit data word to write to the address.
  • SR_channel – The Slink Rocket Channel number to idenfify the link to be read.
loopmode_setup(interactive=False)

Set up the DTH for loop mode with internal Slink Sender. The Receiver part of the DTH is initialised. This includes the TCP/IP link with the MAC, the logic receiving (and checking) the Slink Rocket data and the FireFlies. In addition the internal SlinkRocket sender of the DTH-Kit is reset.

loopmode_start(interactive='False')

Start the event generator feeding the SlinkRocket sender of the DTH Kit.

The internal Slink senders of the DTH Kit which are active according to the configuration file, are initialised. The FED_IDs specified in the configuration file are set. The event size is hardcoded to 8000 (dec) words. The time between 2 fragments is set to 10ns. Then the event generator is started.

loopmode_stop()

Stop the internal event generator which feeds the internal Slink Rocket sender of the DTH Kit.

setup_DAQ_transceiver_base()

Setup the DTH Slink Receivers,

Performs the following actions:

  • Global reset.
  • Reset counters of the Slink receivers.
  • Set the voltage of the 100G MAC Serdes.
  • Enabe the QSFPs for the DAQ links.
  • Reset the Serdes of the 100G MACs.
enable_MAC_IP_base()

Enable the Serdes of the MAC for the TCP/IP link.

TCP_parameters_standard()

Set the main parameters if the TCP configuration.

The functions sets the IP numbers (source and destination) and the port numbers (source and destination for all TCP/IP streams) which are defined in the json configuation file (essentially port numbers of the TCP streams and one IP addresses for the source and one for the destination).

DAQ_serdes_Analog_standard()

Setup the analog parameters of the Serdes of the TCP/IP link.

In particular this function sets the pre and post emphasis and the differential voltage to hardcoded values.

  • Differential Voltags: 24 (873mV)
  • Pre-cursor: 7 (1.67dB)
  • Post-cursor 10 (2.5dB)

Afterwards the function waits for 2 seconds to let the electronics settle with the new parameters.

setup_FED_parameters()

Set the FED_IDs of the built-in the SlinkRocket senders.

The FED_IDs for the data generated in the internal event generator which feeds the internal SlinkRocket sender cores of the DTH Kit are set. The numbers are defined in the json configuration file. Only enabled SlinkRocket links are configured.

send_ARP(interactive=False)

Send an ARP request and wait for the answer.

Up to 5 ARP requests are sent. After each request the program polls for a reply. If a reply is received the program returns with an error code (see below). If no reply is received after some time another ARP request will be sent out (up to 5 request max).

Returns:
  • 0 successfully obtained a MAC adress in the reply.<br>
  • 1 failed: no reply received after 5 trials.
  • 2 failed: received “0” as mac address in the ARP reply.
open_connection(interactive=False)

Opens the TCP/IP connections of the enabled SlinkRocket streams.

It sends a connection request to the receiver and waits for the acknowledgement, If the latter does not come withing approximately 20 seconds the connection attempt fails with an error.

Returns:
  • 0 on success
  • -1 on failure
close_connection()

Close the TCP/IP connections of the enabled SlinkRocket links.

setup_loopback()

Put the SlinkRocket receiver serdes of the disabled links in loopback mode.

This action is necessary for the clock distribution in the serdes quads of the XILINX FPGAs. In order to not use too many clocking resources the serdes in the quads which are not used are put into loopback mode (at the nead end PCs) so that the clock can be easily recovered also from the links not used and the downstream logic can function correctly.

enable_firefly_base()

Set up the FireFly optics.

The following actions are executed:

  • The logic is reset. The I2C switches for the I2C chains going to the FireFly logic are reset.
  • The FireFlys are enabled.
  • The status of al Fireflies is read.
  • For each firefly the use of the CDR is configured according to the json configuration file. (Note: For 16Gbps links the CDR is always disabled.)
check_SR_linkup()

Check if the SlinkRocket links which are enabled are up.

SlinkRocket_DAQ_on(testMode=False, SR_mask=4294967295, interactive=False)

Send the “DAQ-on” command to all SlinkRocket sender IP cores on enabled SlinkRocket links.

Parameters:
  • testMode – If True sets the Link into test mode. A test pattern is sent continuously over the link to the receiver.
  • SR_mask – A 32 bit wide bit mask defining the SlinkRocket links which will receive the command if parameter interactive is False. Note that only enabled SlinkRocket links are considered. (Links are enabled according to the information in the json configuration file.)
  • interactive – If set to True the routine will interactively ask for each enabled SlinkRocket if the command should be sent.
SlinkRocket_DAQ_off()

Send the “DAQ-off” command to all SlinkRocket sender IP cores on enabled SlinkRocket links.

setup_DTH_for_FED_data(interactive=False)

The DTH is configured to receive data from a FED.

Parameters:interactive – if True the program asks the user to hit a key when the FED is configured and ready to send data. Otherwise the method assumes the FED is already configured correctly.

The following steps are executed in sequence:

setup_DAQ_internal_generator(interactive=False)

The DTH is configured to work with the internal event generators.

Parameters:interactive – if True the program asks the user to hit a key when the FED is configured and ready to send data. Otherwise the method assumes the FED is already configured correctly.

The following steps are executed in sequence:

DAQ_int_gen_1_evt(interactive=False, SR_mask=4294967295)

Generate 1 event in the internal event generator (in front of the internal Slink sender).

Parameters:
  • SR_mask – A bit mask. A one in a bit_n indicates that a fragment will be generated in Slink Rocket channel n.
  • interactive – if True the value of the SR_mask argument is ignored and the user is asked for input on the terminal.
DAQ_int_gen_x_evt(interactive=False, SR_mask=1, nwords=256, deltat=1280)

Generate fragments with the event generator in front of the internal SlinkRocket sender in a loop.

Parameters:
  • SR_mask – A bit mask indicating the SlinkRocket channels for which to generate a fragment.
  • nwords – The size of the fragments given in 128bit words.
  • deltat – The time interval between to successive events given in ns. The programme translates this number to clock cycles of an internal 200Mhz clock
DAQ_int_gen_stop(interactive=False, SR_mask=4294967295)

Stop the internal event generator in front of the SlinkRocket sender.

Parameters:
  • SR_mask – A bit mask indicating the SlinkRocket channels for which to stop the generator.
  • interactive – If True the user has to confirm on the console for which SlinkRocket channel the generators are stopped.
setup_SR_internal_generator(interactive=False)

Setup the DTH for usage with the event generators in the SlinkRocket sender IPs connected to the various channels.

The following steps are executed in sequence:

SR_int_gen_1_evt(interactive=False, SR_mask=4294967295)

Generate a single event fragment in the event generators of the SlinkRocket IPs.

The fragment parameters are hard-coded: The fragment length is 256 128-bit words; the event number is 1. The FEDIds are set to the values in the json configuration file.

Parameters:
  • SR_mask – A bit mask indicating the SlinkRocket channels for which to geberate a fragment.
  • interactive – If True the user has to confirm on the console for each SlinkRocket channel if a fragment is generated.
SR_int_gen_x_evt(interactive=False, SR_mask=4294967295)

Generate event fragments in a loop in the event generator of selected SlinkRocket sender cores.

The parameters of the event fragments are hardcoded to a length fo 65538 128 bit words, no waiting time between event fragments, and the first event number is ‘1’. FED IDs are set to the values in the json configuration file.

Parameters:
  • interactive – If True the program asks for confirmation to generate events for every SR channel configured in the configuration file.
  • SR_mask – A bit mask indicating the SlinkRocket channels for which to generate fragments.
SR_int_gen_stop(interactive=False, SR_mask=4294967295)

Stop the event generators of selected SlinkRocket sender cores.

Parameters:
  • interactive – If True the program asks for confirmation to stop the generators for the SR channel configured in the configuration file.
  • SR_mask – A bit mask indicating the SlinkRocket channels for which to stop the generators.
read_multiple_items(itemlist, offset=0, verbose=False, interactive=False)

A utility function used internally to read out items from the hardware and return them in a dictionary.

Parameters:
  • itemlist – A list of items to read from the hardware (containing address table items).
  • offset – An offset to add to each item.
  • verbose – If set to True the status information is logged at level “INFO”.
  • interactive – If set to True The function waits for a keypress before returnnig.
Returns:

A dictionary with the Status information read from the hardware.

read_MAC_IP_status(verbose=False, interactive=False)

Function to read status information for the 100G MAC serdes of the DAQ link.

Parameters:
  • verbose – If set to verbose the status information is logged at level “INFO”.
  • interactive – If set to True The function waits for a keypress before returnnig.
Returns:

A dictionary with the Status information read from the hardware.

TCP_parameters(newParams={}, interactive=False)

Set TCP parameters to specific values or default values.

The default values are hardcoded in the constructor.

Parameters:
  • newParams – a dictionary with key/value pairs to use instead of the defaults (interactive must be False).
  • interactive – If set to True read values for each parameter from the console”
DAQ_serdes_Analog(TX_DiffCtrl=24, TX_post_cur=10, TX_pre_cur=7, interactive=False)

Set some analog parameters of the serdes of the DAQ TCP/IP link.

For more details on these values please refer to the Transceiver data sheets.

Parameters:
  • Tx_DiffCtrl – Differential Voltage swing of the Tx channel (default: 24 or 823 mV)
  • Tx_post_cur – The post-cursor pre-emphasis (default: 10 (2.5 dB))
  • Tx_pre_cur – The pre cursor pre-emphasis (default: 7 (1.67 dB))
  • interactive – If set to True the values are taken from user input at the console.
SR_serdes_Analog_standard(TX_Diff_Ctrl=24, TX_post_cur=0, TX_pre_cur=0, interactive=False)

Set some analog parameters of the serdes of the SR transceiver.

For more details on these values please refer to the transceiver data sheets.

Parameters:
  • Tx_DiffCtrl – Differential Voltage swing of the Tx channel (default: 24 or 823 mV)
  • Tx_post_cur – The post-cursor pre-emphasis (default: 0 (0 dB))
  • Tx_pre_cur – The pre cursor pre-emphasis (default: 0 (0 dB))
  • interactive – If set to True the values are taken from user input at the console.
SlinkRocket_reset()

Resets the serdes of the Slink Rocket receiver core.

send_ping()

Send a ping packet over the DAQ link to the receiver NIC in the PC and wait one second.

generate_synclost_error()

Generate a sync lost error for test purposes.

This function only works in loop back mode with the internal event generator in front of the internal Slink-Sender core. This function sets the event number of the event generator to 8.

generate_fedid_error()

Generate a FED_ID error for test purposes.

This function only works in loop back mode with the internal event generator in front of the internal Slink-Sender core. This function inverts the bits of the FED_ID for the event generator.

generate_crc_errors()

Generate a crc errors for test purposes.

This function only works in loop back mode with the internal event generator in front of the internal Slink-Sender core.

Read data from the SlinkRocket channels and “throw them away”.

This enable the user to send data via the Slink Rocket to the Slink Rocket receiver where the packets are tested for CRC errors. However data is not transferred to the DAQ unit in the DTH but dat is “thrown away” after the Slink receiver. Hence no backpressure is created. This allows some basic Slink checks without having a functional DAQ setup.

resync_seqNum(interactive=False)

Resynchronise the SlinkRocket links.

The sequence numbers are reset to 0 in the connceted SlinkRocket sender IPs.

Parameters:interactive – If True the user is asked for confirmation for each SlinkRocket channel.
monitor_itemarray(marr, offset=0)

Generic routine to read addresstable items from the hardware adn optionally to some simple operation on them.

Parameters:
  • marr – A list of dictionarys with the following content: ‘key’ -> addresstable item; ‘mask’ -> an optional bit mask which can be applied to the result; ‘div’ -> an optional divider which can be be applied; ‘func_div’-> an addresstable item which is used to read out a second value; the value read for the ‘key’ item is then divided by this value.
  • offset – an offset to be applied to all hardware reads.
display_diff(val, val_cmp, text, console=True, logger=False)

Display and color code a value.

A helper function to repetitively display values and mark them in color if they change. A value is compared to a second value and colored differently when the comparsions reveals unequal values.

Parameters:
  • val – The value to display
  • val_cmp – The value to compare with.
  • text – Text to print before the value.
  • console – If True print on the console.
  • logger – If True print into the logger.
display_itemarray(marr, console=True, logger=False)

Helper function to display an array of items and monitor changes.

This function is intended to be used in loops which repetitively read out lists of items from the hardware. The items are displayed and color coded in case the read values change.

Parameters:
  • marr – A list of dictionaries describing values to be displayed. The dictionary need to contain the key ‘value’ and if it contains also ‘old_value’ this value is assumed to be the previous read to use to detect a value change.
  • console – If True print to the console.
  • logger – If true print into the logger.
reset_DAQ_TCP_status_counters()

Reset some counters related to the 100G MAC.

FPGA_sysmon(console=True, logger=False, interactive=False)

Monitor some status information of the FPGA.

Temperature and Voltages are read and displayed.

Parameters:
  • console – If True print to the console.
  • logger – If true print into the logger.
  • interactive – If true waits for a user to press a key.
read_SlinkRocket_sender_status(console=True, logger=True, interactive=False)

Read and display status information for the SlinkRocket sender core.

Parameters:
  • console – If True print to the console.
  • logger – If true print into the logger.
  • interactive – If true waits for a user to press a key.
read_serdes_status_SR(console=True, logger=True, interactive=False)

Read and display status information for the SlinkRocket serdes (receiver and sender).

Parameters:
  • console – If True print to the console.
  • logger – If true print into the logger.
  • interactive – If true waits for a user to press a key.
read_SR_receiver_counters(console=True, logger=True, interactive='False')

Read and display some counters in the SlinkRocket receiver.

Parameters:
  • console – If True print to the console.
  • logger – If true print into the logger.
  • interactive – If True waits for a user to press a key.
read_firefly_registers(console=True, logger=True, interactive=False)

Read and display status information from the FireFly optics.

Parameters:
  • console – If True print to the console.
  • logger – If true print into the logger.
  • interactive – If True asks to reset the counters and waits for a user to press a key. If True enters a loop to read and display the counters every second. If False, the counters are read and displayed once.
check()
check64()
getAddress()
interactive_itemarray_monitoring(marr, offset=0, console=True, logger=False)

Monitor a list of items until the user presses a key.

Parameters:
  • marr – Array of items to monitor.
  • console – If True print to the console.
  • logger – If true print into the logger.
isSet()
isSet64()
pollItem()
pollItem64()
read()
read64()
readBlock()
readBlock64()
readPulse()
readPulse64()
resetBit()
resetBit64()
setBit()
setBit64()
unmaskedRead()
unmaskedRead64()
unmaskedWrite()
unmaskedWrite64()
write()
write64()
writeBlock()
writeBlock64()
writePulse()
writePulse64()
measure_backpressure()

Monitor interactively backpressure.

Table Of Contents