Functions

Top level functions that form the prefered API.

Functions

int xsp3_config (int ncards, int num_tf, char *baseIPaddress, int basePort, char *baseMACaddress, int num_chan, int create_module, char *modname, int debug, int card_index)
 Configure and initialise the complete xspress3 system.
char * xsp3_get_error_message ()
 Get the last error message that was generated by the xspress3 system.
int xsp3_close (int path)
 Close all open paths in the system.
int xsp3_get_revision (int path)
 Get firmware revision.
int xsp3_get_num_chan (int path)
 Get the number of channels currently configured in the system.
int xsp3_get_num_cards (int path)
 Get the number of xspress3 cards currently configured in the system.
int xsp3_get_chans_per_card (int path)
 Get the number of channels available per xspress3 card.
int xsp3_get_bins_per_mca (int path)
 Get the number of bins per MCA configured in the xspress3 system.
int xsp3_get_max_num_chan (int path)
 Get the maxmimum number of channels currently available in system.
int xsp3_format_run (int path, int chan, int aux1_mode, int aux1_thres, int aux2_cont, int flags, int aux2_mode, int nbits_eng)
 Set format of the data to be histogrammed.
int xsp3_get_format (int path, int chan, int *nbins_eng, int *nbins_aux1, int *nbins_aux2, int *nbins_tf)
 Get the format control parameters.
int xsp3_set_window (int path, int chan, int win, int low, int high)
 Set the scaler windows.
int xsp3_set_good_thres (int path, int chan, u_int32_t good_thres)
 Set the threshold for the good event scaler.
int xsp3_get_window (int path, int chan, int win, u_int32_t *low, u_int32_t *high)
 Get the scaler window settings.
int xsp3_set_glob_timeA (int path, int card, u_int32_t time)
 Setup the triggering or time frame control register.
int xsp3_set_glob_timeFixed (int path, int card, u_int32_t time)
 Set the fixed time frame register.
int xsp3_get_glob_timeA (int path, int card, u_int32_t *time)
 Get the time frame register.
int xsp3_get_glob_timeFixed (int path, int card, u_int32_t *time)
 Get fixed time frame register.
int xsp3_init_roi (int path, int chan)
 Initialise the regions of interest.
int xsp3_set_roi (int path, int chan, int num_roi, XSP3Roi *roi)
 Sets the regions of interest.
int xsp3_get_disable_threading (int path)
 Get Disable multi threading flags.
int xsp3_set_disable_threading (int path, int flags)
 Set Disable multi threading flags.
int xsp3_clocks_setup (int path, int card, int clk_src, int flags, int tp_type)
 Set up ADC data processing clocks source.
int xsp3_dma_config_memory (int path, int card, int layout)
 Configure the memory.
int xsp3_set_run_flags (int path, int flags)
 Set the run mode flags.
int xsp3_get_run_flags (int path)
 Get the run mode flags.
int xsp3_scope_wait (int path, int card)
 This function polls the DMA descriptors for the two scope DMA streams to check whether all the data has been transfered.
double xsp3_getDeadtimeCalculationEnergy (int path)
 Get the energy for dead time correction.
int xsp3_setDeadtimeCalculationEnergy (int path, double energy)
 Set the energy for dead time energy correction.
int xsp3_scaler_dtc_read (int path, double *dest, unsigned scaler, unsigned chan, unsigned t, unsigned n_scalers, unsigned n_chan, unsigned dt)
 Read a block of dead time corrected scaler data.
int xsp3_hist_dtc_read4d (int path, double *hist_buff, double *scal_buff, unsigned eng, unsigned aux, unsigned chan, unsigned tf, unsigned num_eng, unsigned num_aux, unsigned num_chan, unsigned num_tf)
 Read a 4 dimensional block of dead time corrected histogram data and optionally return the dead time corrected scaler data.
int xsp3_has_itfg (int path, int card)
 Determine whether firmware includes an internal TFG.
int xsp3_has_reset_det (int path, int card)
 Determine whether firmware includes a Reset detector.
int xsp3_has_glitch_det (int path, int card, int *min_thres)
 Determine whether firmware includes a glitch detector.
int xsp3_has_scope_dig_alt0 (int path, int card)
 Determine whether firmware Alternatebit 3..0 controlling scope stream 0.
int xsp3_histogram_start (int path, int card)
 Start system and enable counting.
int xsp3_histogram_arm (int path, int card)
 Start system ready for histogramming but do not software enable histogramming.
int xsp3_histogram_continue (int path, int card)
 Continue counting from armed or paused when time framing is in software controlled (FIXED) mode.
int xsp3_histogram_pause (int path, int card)
 Pause counting in seriesof software timed frames.
int xsp3_histogram_stop (int path, int card)
 Stop histogramming.
int xsp3_histogram_clear (int path, int first_chan, int num_chan, int first_frame, int num_frames)
 Clears a section of the histogramming data buffer.
int xsp3_histogram_is_any_busy (int path)
 Check if any histogarmming thread for this system is busy or waiting for data.
int xsp3_histogram_read4d (int path, u_int32_t *buffer, unsigned eng, unsigned aux, unsigned chan, unsigned tf, unsigned num_eng, unsigned num_aux, unsigned num_chan, unsigned num_tf)
 Read a 4 dimensional block of histogram data.
int xsp3_histogram_read3d (int path, u_int32_t *buffer, unsigned x, unsigned y, unsigned t, unsigned dx, unsigned dy, unsigned dt)
 Read a 3 dimensional block of histogram data with aux and chan combined into "y" to suit da.server.
int xsp3_histogram_read_chan (int path, u_int32_t *buffer, unsigned chan, unsigned eng, unsigned aux, unsigned tf, unsigned num_eng, unsigned num_aux, unsigned num_tf)
 Read a channel of histogram data.
int xsp3_i2c_read_adc_temp (int path, int card, float *temp)
 Read Temperature from all 4 LM75s on 1 or all ADC boards.
int xsp3_i2c_set_adc_temp_limit (int path, int card, int critTemp)
 Set over Temperature threshold for all 4 LM75s on 1 or all ADC boards.
int xsp3_itfg_setup (int path, int card, int num_tf, u_int32_t col_time, int trig_mode, int gap_mode)
 Setup Internal time frame generator (TFG) for a series of equal length frames.
int xsp3_itfg_get_setup (int path, int card, int *num_tf, u_int32_t *col_time, int *trig_mode, int *gap_mode)
 Retrieve settings of the Internal time frame generator (TFG).
int xsp3_itfg_stop (int path, int card)
 Stop the Internal time frame generator (TFG).
int xsp3_save_settings (int path, char *dir_name)
 Save all xspress3 settings into a series of files.
int xsp3_restore_settings (int path, char *dir_name, int force_mismatch)
 Restore all xspress3 settings from series of files.
int xsp3_scaler_get_num_tf (int path)
 Read the maximum number of time frames of scaler data that can be stored with the current memory allocation within the FEM.
int xsp3_scaler_read (int path, u_int32_t *dest, unsigned scaler, unsigned chan, unsigned t, unsigned n_scalers, unsigned n_chan, unsigned dt)
 Read a block of scaler data.
int xsp3_scaler_check_progress (int path)
 This function checks how many time frames have been processed.
int xsp3_scaler_check_desc (int path, int card)
 This function checks the DMA descriptors for the Scaler stream to check how many time frames of scalers have been successfuly transfered to memeory.
int xsp3_read_scope_data (int path, int card)
 Read scope data from 10G ethernet using UDP protocol.
int xsp3_write_playback_data (int path, int card, u_int32_t *buffer, size_t nbytes)
 Write playback data into DRAM via the 10G ethernet link.

Function Documentation

int xsp3_clocks_setup ( int  path,
int  card,
int  clk_src,
int  flags,
int  tp_type 
)

Set up ADC data processing clocks source.

The clock source can come from various places. At power up and from some debugging teh clock source can be from the FPGA board clocks. However, for normal operation the data processing clock has to be from the ADC board. This is setup by this command. It shouldbedoneafter xsp3_config, but before anything else. Note that xsp3_restore_settings cannot resotore the clock configuration.

The following definitions describe the valid values for the parameter clk_src xspress3.h XSP3_CLOCK_SRC The following definitions describe the valid values for flags which are or'ed together to make the flags parameter. xspress3.h XSP3_CLOCK_FLAGS

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration. If card is less than 0 then all cards are selected.
clk_src clock source
flags setup flags (see definition)
tp_type test pattern type in the IO spartan FPGAs
Returns:
XSP3_OK or a negative error code.
int xsp3_close ( int  path  ) 

Close all open paths in the system.

Currently full details of tidying various shared objects and threads are not fully supported so this function is a place holder for future work.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
XSP3_OK or a negative error code.
int xsp3_config ( int  ncards,
int  num_tf,
char *  baseIPaddress,
int  basePort,
char *  baseMACaddress,
int  num_chan,
int  create_module,
char *  modname,
int  debug,
int  card_index 
)

Configure and initialise the complete xspress3 system.

This is the normal configuration entry point for XSPRESS3. The number of cards and number of time frames parameters must be specified. The debug and create_module parameters are boolean and should be specified as 0 or 1. All other parameters can be used as default by specifying either NULL or -1.
The functions checks if the parameters of this configuration have been previously used. If so the system is re-inialised and the existing path is returned. Otherwise if its a unique set of cards to configure allow the configuration. Nb. If a different debug flag is set for the case where the same parameters are used this may overwrite another connections debug preference.
This function normally creates all the shared memory objects and starts the histogramming thread(s).

 * Using the default baseIPaddress, for the host server, of 192.168.0.1 the following values are calculated for the complete xspress3 system.
 *
 * xspress3 1Gb tcp IP address 		card 1		192.168.0.2
 * 									card 2		192.168.0.3
 * 									card 3		192.168.0.4
 * 									...
 *
 * host 10Gb udp IP address 		card 1		192.168.0.65
 * 									card 2		192.168.0.69
 * 									card 3		192.168.0.73
 * 									...
 *
 * xspress3 10Gb udp IP address 	card 1		192.168.0.66
 * 									card 2		192.168.0.70
 * 									card 3		192.168.0.74
 * 									...
 *
 * Using the default MAC address of 02.00.00.00.00.00 the following values are calculated for the complete xspress3 system.
 *
 * xspress3 MAC address 			card 1		02.00.00.00.00.00
 * 									card 2		02.00.00.00.00.02
 * 									card 3		02.00.00.00.00.04
 * 									...
 *
 * For all xspress3 cards the default basePort for the tcp connection is 30123 and for the udp connection 30124.
 *
 *
Parameters:
ncards the number of xspress3 cards that constitute the xspress3 system, between 1 and XSP3_MAX_CARDS.
num_tf the maximum number of time frames when used as 4096 energy bins and no auxiliary data. If the memory is arranged differently (using RoI or Auxiliary data) then the actual number of tf that will fit can go up or down
baseIPaddress the IP address of the host server in dotted quad format (e.g. 192.168.0.1) from which all other address's are calculated or NULL to use the default
basePort the IP port number or -1 to use the default
baseMACaddress the base MAC address (e.g. 02.00.00.00.00) for card 1, from which all other card MAC address's are calculated or NULL to use the default
num_chan the number of channels to be configured in the xspress3 system. between 1 and (ncards * XSP3_MAX_CHANS_PER_CARD) or -1 to configure all available channels.
create_module a boolean flag to determine whether to create a data module
modname the module name or NULL to use the default.
debug a integer flag to turn debug messages off/on/verbose.
card_index starting card number ie 0 = card1, 1 = card2 etc. -1 assumes card_index 0)
Returns:
a handle to the top level of the xspress3 system or a negative error code.
int xsp3_dma_config_memory ( int  path,
int  card,
int  layout 
)

Configure the memory.

At present it is a fixed layout so there is little point calling this. Consider future expansion.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration.
layout Not used. Reserved for future expansion
Returns:
XSP3_OK or a negative error code.
int xsp3_format_run ( int  path,
int  chan,
int  aux1_mode,
int  aux1_thres,
int  aux2_cont,
int  flags,
int  aux2_mode,
int  nbits_eng 
)

Set format of the data to be histogrammed.

The output histogram format is a multi-dimesional space. The first dimension is the photon energy. The second dimension (if present) is the auxilliary data 1 aux1. The third dimension (if present) is the auxilliary data 2 aux2. The fourth dimension is the time frame.

The following definitions describe the aux1 mode options xspress3.h XSP3_AUX1_MODE The following definitions describe the aux2 mode options xspress3.h XSP3_AUX2_MODE

The flags shared the settings with the format register. Currently the only bit which can be set here is XSP3_FORMAT_PILEUP_REJECT. If set, events whcih are identified as pileup from either the trigger hardware or by event width (see xsp3_build_pileup_time) are discarded from the in-window scalers and MCA spectra.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
chan is the number of the channel in the xspress3 system, 0 to (xsp3_get_num_chan() - 1) if chan is less than 0 then all channels are selected
aux1_mode special debug mode (set to 0 for user operation)
aux1_thres threshold special debug value (set to 0 for user operation)
aux2_cont set bits for ADC range (set to 0 for user operation)
flags for pileup rejection (set to 0 for user operation)
aux2_mode (set to 0 for user operation)
nbits_eng number bits of energy (default 12)
Returns:
The number of time frames of the requested configuration that fits into memory.
int xsp3_get_bins_per_mca ( int  path  ) 

Get the number of bins per MCA configured in the xspress3 system.

The correct value is stored in the top level path of the system.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
the number of bins per MCA for the current configuration of the xspress3 system or a negative error code. FIXME : Returns default number of bins, does not report any ROI settings.
int xsp3_get_chans_per_card ( int  path  ) 

Get the number of channels available per xspress3 card.

The correct value is stored in the top level path of the system.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
the number of channels available per xspress3 card or a negative error code.
int xsp3_get_disable_threading ( int  path  ) 

Get Disable multi threading flags.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
the Disable multi threading flags. See XSP3_MT_FLAGS or a negative error code.
char* xsp3_get_error_message (  ) 

Get the last error message that was generated by the xspress3 system.

Whenever an function returs an error code a deatiled error messages is sprintfed into the error_message buffer. It can be retrieved using this call. The maximum length of this message is XSP3_MAX_MSG_LEN.

Returns:
A pointer to the statically allocated error message, which will remain valid only until the next error occurs.
int xsp3_get_format ( int  path,
int  chan,
int *  nbins_eng,
int *  nbins_aux1,
int *  nbins_aux2,
int *  nbins_tf 
)

Get the format control parameters.

Retrieves the parameters set by xsp3_format_run.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
chan is the number of the channel in the xspress3 system, 0 to (xsp3_get_num_chan() - 1)
nbins_eng 
nbins_aux1 
nbins_aux2 
nbins_tf 
Returns:
XSP3_OK or a negative error code.
int xsp3_get_glob_timeA ( int  path,
int  card,
u_int32_t *  time 
)

Get the time frame register.



The following definitions describe the layout of the global time A register xspress3.h XSP3_GLOBAL_TIMEA_REGISTER

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration.
time the time frame register
Returns:
XSP3_OK or a negative error code.
int xsp3_get_glob_timeFixed ( int  path,
int  card,
u_int32_t *  time 
)

Get fixed time frame register.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration.
time fixed time frame register
Returns:
XSP3_OK or a negative error code.
int xsp3_get_max_num_chan ( int  path  ) 

Get the maxmimum number of channels currently available in system.

The correct value is stored in the top level path of the system.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
the maximum number of channels for the current configuration of the xspress3 system or a negative error code.
int xsp3_get_num_cards ( int  path  ) 

Get the number of xspress3 cards currently configured in the system.

The correct value is stored in the top level path of the system.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
the number of cards currently configured in the xspress3 system or a negative error code.
int xsp3_get_num_chan ( int  path  ) 

Get the number of channels currently configured in the system.

This value is passed into the xsp3_config routine. The correct value is stored in the top level path of the system.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
the number of configured channels in the xspress3 system or a negative error code.
int xsp3_get_revision ( int  path  ) 

Get firmware revision.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
the revision a negative error code.
int xsp3_get_run_flags ( int  path  ) 

Get the run mode flags.

Retrieve run mode flags as set by xsp3_set_run_flags.

The following definitions describe the valid values for the stream xspress3.h XSP3_RUN_FLAGS

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
the value of run flags
int xsp3_get_window ( int  path,
int  chan,
int  win,
u_int32_t *  low,
u_int32_t *  high 
)

Get the scaler window settings.

Retrieve the in-window scalers limits as set by xsp3_set_window

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
chan is the number of the channel in the xspress3 system, 0 to (xsp3_get_num_chan() - 1)
win the window (0 or 1)
low returned low window thresholds
high returned high window threshold
Returns:
XSP3_OK or a negative error code.
double xsp3_getDeadtimeCalculationEnergy ( int  path  ) 

Get the energy for dead time correction.

The user code should tell the library at approximately what energy the system is operating. TODO: May calculate from the MCA.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
the energy or negative error code.
int xsp3_has_glitch_det ( int  path,
int  card,
int *  min_thres 
)

Determine whether firmware includes a glitch detector.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card Card number.
feaures Pointer to Xspress3_features to return a copy of the feature structure into.
Returns:
Glitch detector code as defined by XSP_FEATURE_GDET or <0 => ERROR
int xsp3_has_itfg ( int  path,
int  card 
)

Determine whether firmware includes an internal TFG.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card Card number.
Returns:
Internal TFG code as defined by XSP3_FEATURS_TIMING_GEN or <0 => ERROR
int xsp3_has_reset_det ( int  path,
int  card 
)

Determine whether firmware includes a Reset detector.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card Card number.
Returns:
Internal TFG code as defined by XSP3_FEATURS_TIMING_GEN or <0 => ERROR
int xsp3_has_scope_dig_alt0 ( int  path,
int  card 
)

Determine whether firmware Alternatebit 3..0 controlling scope stream 0.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card Card number.
Returns:
Internal TFG code as defined by XSP3_FEATURS_TIMING_GEN or <0 => ERROR
int xsp3_hist_dtc_read4d ( int  path,
double *  hist_buff,
double *  scal_buff,
unsigned  eng,
unsigned  aux,
unsigned  chan,
unsigned  tf,
unsigned  num_eng,
unsigned  num_aux,
unsigned  num_chan,
unsigned  num_tf 
)

Read a 4 dimensional block of dead time corrected histogram data and optionally return the dead time corrected scaler data.

This is the usual method to access dead time corrected data. Both MCA and scaler data can be returned.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
hist_buff buffer pointer to receive the histogram data.
scal_buff buffer pointer to receive the scaler data or NULL if not required.
eng is the start energy
aux is the starting aux point (should be 0)
chan is the number of the channel in the xspress3 system, 0 to (xsp3_get_num_chan() - 1).
tf is the starting time frame
num_eng number of energies
num_aux number of aux data (should be 1)
num_chan number of channels
num_tf number of time frames
Returns:
XSP3_OK or a negative error code.
int xsp3_histogram_arm ( int  path,
int  card 
)

Start system ready for histogramming but do not software enable histogramming.

For non-farm mode UDP core versions the UDP port and frame numbers are reset as the scope mode also uses the UDP connection on a different port. In software timing mode, counting is left disabled, start with xsp3_histogram_continue()

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration. card == -1 causes all cards in a multi card system to start.
Returns:
XSP3_OK or a negative error code.
int xsp3_histogram_clear ( int  path,
int  first_chan,
int  num_chan,
int  first_frame,
int  num_frames 
)

Clears a section of the histogramming data buffer.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
first_chan first channel to start clearing from.
num_chan number of channels to clear.
first_frame first frame number to start clearing from.
num_frames number of frames to clear.
Returns:
XSP3_OK or a negative error code.
int xsp3_histogram_continue ( int  path,
int  card 
)

Continue counting from armed or paused when time framing is in software controlled (FIXED) mode.

The System must have started first with xsp3_histogram_start() or xsp3_histogram_arm()

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration. If card is less than 0 then all cards are selected.
Returns:
XSP3_OK or a negative error code.
int xsp3_histogram_is_any_busy ( int  path  ) 

Check if any histogarmming thread for this system is busy or waiting for data.

Usually the histogramming thread will keep up with the list of events and will idle in a blocking read. If the system is used at high rate and CPU load or page faults stall the histogram thread may take some time to finish processing data from the network stack byffers. To safely stop the system, the supply of histogram data should be stopped either by the external timing generator negating the count enable input or by calling xsp3_histogram_stop() to negate the Run bit in the timing control register. After this the calling program should repeat sleeping 10 ms and checking this busy flag until it is seen to be not busy twice on the run.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
1 if busy 0 idle or a negative error code.
int xsp3_histogram_pause ( int  path,
int  card 
)

Pause counting in seriesof software timed frames.

The next xsp3_histogram_continue will increment time frame andcontinue counting. This leaves DMAs running ready for next frame. The System must have started first with xsp3_histogram_start()

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration. If card is less than 0 then all cards are selected.
Returns:
XSP3_OK or a negative error code.
int xsp3_histogram_read3d ( int  path,
u_int32_t *  buffer,
unsigned  x,
unsigned  y,
unsigned  t,
unsigned  dx,
unsigned  dy,
unsigned  dt 
)

Read a 3 dimensional block of histogram data with aux and chan combined into "y" to suit da.server.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
buffer a pointer to the buffer for the returned data
x is the start energy
y is the channel and aux combined, converting aux and then channel
t is the start time frame
dx is the number of energies
dy is the number of the combined channel & aux
dt is the number of time frames
Returns:
XSP3_OK or a negative error code.
int xsp3_histogram_read4d ( int  path,
u_int32_t *  buffer,
unsigned  eng,
unsigned  aux,
unsigned  chan,
unsigned  tf,
unsigned  num_eng,
unsigned  num_aux,
unsigned  num_chan,
unsigned  num_tf 
)

Read a 4 dimensional block of histogram data. 

 * Data set is 4 dimensional. Read any 4d cuboid from this 4d data volume
 * Dimension 1: Energy typically 0..4095 unless RoI are used to reduce volume
 * Dimension 2: Any auxilary data, srta 0, num1 for normal operation, can be position on ADC ramp
 * Dimension 3: Channel number
 * Dimension 4: Time frame
 *
 *					<------- Dim1 ------ Energy -------------------->
 * 0	1	2	3	....		4093	4094	4095
 * T=0	Chan 0 Aux 0	0	1	2	3	....		4093	4094	4095
 * 		Chan 0 Aux 1	4096			....						8191
 * 		Chan 0 Aux 2	8192			....						12287
 * 		Chan 0 Aux ...	12288			...							16383
 *
 * T=0	Chan 1 Aux 0	nbins_aux1*nbin_aux2+0		....	nbins_aux1*nbin_aux2+4095
 * 		Chan 1 Aux 1	nbins_aux1*nbin_aux2+4096	....	nbins_aux1*nbin_aux2+8191
 * 		Chan 1 Aux 2
 * 		Chan 1 Aux ...
 *
 * T=0	Chan 2 Aux 0	2*nbins_aux1*nbin_aux2+0	....	2*nbins_aux1*nbin_aux2+4095
 * 		Chan 2 Aux 1	2*nbins_aux1*nbin_aux2+4096	....	2*nbins_aux1*nbin_aux2+8191
 * 		Chan 2 Aux 2
 * 		Chan 2 Aux ...
 *
 * 	.....
 * T=1	Chan 0 Aux 0	1*num_chan*nbins_aux1*nbin_aux2+0	....	1*num_chan*nbins_aux1*nbin_aux2+4095
 * 		Chan 0 Aux 1
 * 		Chan 0 Aux 2
 * 		Chan 0 Aux ...
 *
Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
buffer buffer pointer to receive the histogram data.
eng is the start energy
aux is the starting aux point
chan is the number of the channel in the xspress3 system, 0 to (xsp3_get_num_chan() - 1).
tf is the starting time frame
num_eng number of energies
num_aux number of aux data
num_chan number of channels
num_tf number of time frames
Returns:
XSP3_OK or a negative error code.
int xsp3_histogram_read_chan ( int  path,
u_int32_t *  buffer,
unsigned  chan,
unsigned  eng,
unsigned  aux,
unsigned  tf,
unsigned  num_eng,
unsigned  num_aux,
unsigned  num_tf 
)

Read a channel of histogram data. 

 * The raw data arrangement is stored in a /dev/shm shared data area per channel.
 * Each channel's data region is a 3 d volume: energy, aux and time.
 * The module header and imgd display program only understand this as  2d : energy , aux and time combined
 *
 * This interface supports the native format of the data from xspress3.
 * Data set is 3 dimensional. Read any 3d cuboid from this 3d data volume
 * Dimension 1: Energy typically 0..4095 unless RoI are used to reduce volume
 * Dimension 2: Any auxiliary data, start=0, num=1 for normal operation, can be position on ADC ramp
 * Dimension 3: Time frame
 *
 * 					<--------- Dim1 -------- Energy -------------------->
 * 						0	1	2	3	....		4093	4094	4095
 * T=0	Aux 0			0	1	2	3	....		4093	4094	4095
 *		Aux 1			4096			....						8191
 *		Aux 2			8192			....						12287
 *		Aux ...			12288			...							16383
 *
 * T=1	Aux 0		nbins_aux1*nbin_aux2+0		....	nbins_aux1*nbin_aux2+4095
 *		Aux 1		nbins_aux1*nbin_aux2+4096	....	nbins_aux1*nbin_aux2+8191
 *		Aux 2
 *
 * T=2	Aux 0		2*nbins_aux1*nbin_aux2+0	....	2*nbins_aux1*nbin_aux2+4095
 *		Aux 1		2*nbins_aux1*nbin_aux2+4096	....	2*nbins_aux1*nbin_aux2+8191
 *		Aux 2
 *		Aux ...
 *
Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
buffer a pointer to the buffer for the returned data
eng is the start energy
aux is the starting aux point
chan is the number of the channel in the xspress3 system, 0 to (xsp3_get_num_chan() - 1).
tf is the starting time frame
num_eng number of energies
num_aux number of aux data
num_tf number of time frames
Returns:
XSP3_OK or a negative error code.
int xsp3_histogram_start ( int  path,
int  card 
)

Start system and enable counting.

Start histogramming after resetting the UDP port and frame numbers. The UDP port reset is only required when it is not in farm mode as the scope mode also uses the UDP connection on a different port. In software timing mode, start counting immediately.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration. card == -1 causes all cards in a multi card system to start.
Returns:
XSP3_OK or a negative error code.
int xsp3_histogram_stop ( int  path,
int  card 
)

Stop histogramming.

Clears the run bit and count enable bit in the global timing register. The system will need to be fully restarted using xsp3_histogram_start etc. after stopping like this.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration.
Returns:
XSP3_OK or a negative error code.
int xsp3_i2c_read_adc_temp ( int  path,
int  card,
float *  temp 
)

Read Temperature from all 4 LM75s on 1 or all ADC boards.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration.
temp Pointer to array to store data.
Returns:
XSP3_OK
int xsp3_i2c_set_adc_temp_limit ( int  path,
int  card,
int  critTemp 
)

Set over Temperature threshold for all 4 LM75s on 1 or all ADC boards.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration.
critTemp temperature in degrees to turn off power.
Returns:
XSP3_OK
int xsp3_init_roi ( int  path,
int  chan 
)

Initialise the regions of interest.

Removes any existing regions of interest.

This needs to be done if the RoI has been set and the user wishes to switch back to seeing the full spectra. It would be combined with a call to xsp3_format_run with nbits_eng=12.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
chan is the number of the channel in the xspress3 system, 0 to (xsp3_get_num_chan() - 1)
Returns:
XSP3_OK or a negative error code.
int xsp3_itfg_get_setup ( int  path,
int  card,
int *  num_tf,
u_int32_t *  col_time,
int *  trig_mode,
int *  gap_mode 
)

Retrieve settings of the Internal time frame generator (TFG).

The minimal internal TFG (currently the only version designed) can create a series of time frames all of the same length. This functions allows the settings as last set by xsp3_itfg_setup() to be read back.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card Card of the system containing the ITFG
num_tf Pointer to return the number of time frames.
col_time Pointer to return the collection time per frame in 80 MHz clock cycles.
trig_mode Pointer to return the trigger modes defined by XSP3_ITFG_TRIG_MODE.
gap_mode Pointer to return frame to Frame gap moed defined by XSP3_ITFG_GAP_MODE
Returns:
XSP3_OK or a negative error code.
int xsp3_itfg_setup ( int  path,
int  card,
int  num_tf,
u_int32_t  col_time,
int  trig_mode,
int  gap_mode 
)

Setup Internal time frame generator (TFG) for a series of equal length frames.

The minimal internal TFG (currently the only version designed) can create a series of time frames all of the same length. To use the ITFG, set timing source using xsp3_set_glob_timeA() with XSP3_GTIMA_SRC_INTERNAL. The ITFG can run a burst of frames immediate from start or can wait for the trigger to start each frame. This trigger can from software or hardware.
From software start the system calling xsp3_histogram_arm() then trigger by calling xsp3_histogram_continue() then xsp3_histogram_pause(). Note it is necessary to pulse the Count enb signal high and low calling both functions, but the time between the 2 calls does not give the collection time when using the ITFG.
For hardware, the system is started using xsp3_histogram_start() and then triggers on the rising edge of TTL_IN(1). This can be switched to the falling edge using XSP3_GLOB_TIMA_VETO_INV in xsp3_set_glob_timeA(). The debounce time can also be used to clean the trigger pulse to the internal TFG.
In a multi card system, it would be usual to make one card the master and distribute the veto signal (from TTFG_OUT(0..3) to the other cards, so the software does not broadcast settings to all cards. The other cards are set with XSP3_GTIMA_SRC_TTL_VETO_ONLY with the debounce time set to ignore any ringing but the cleanly detect the gaps between frames, see gap_mode and XSP3_ITFG_GAP_MODE.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card Card of the system containing the ITFG.
num_tf Number of time frames.
col_time Collection time per frame in 80 MHz clock cycles.
trig_mode Trigger modes defined by XSP3_ITFG_TRIG_MODE.
gap_mode Frame to Frame gap moed defined by XSP3_ITFG_GAP_MODE
Returns:
XSP3_OK or a negative error code.
int xsp3_itfg_stop ( int  path,
int  card 
)

Stop the Internal time frame generator (TFG).

This stops the Internal TFG mid experiment. Any end of expermiment procesing is not stopped, so the histogram threads will run to completion.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card Card of the system containing the ITFG.
Returns:
XSP3_OK or a negative error code.
int xsp3_read_scope_data ( int  path,
int  card 
)

Read scope data from 10G ethernet using UDP protocol.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration.
Returns:
number of frames greater than 0 is success else 0 or negative error code is fail.
int xsp3_restore_settings ( int  path,
char *  dir_name,
int  force_mismatch 
)

Restore all xspress3 settings from series of files.

All register, and BRAM settings are restored FIXME: Also Sofware LUTs to be done.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
dir_name directory with saved settings file.
force_mismatch force restore if major revision of saved file does not match the firmware revision.
Returns:
XSP3_OK or a negative error code.
int xsp3_save_settings ( int  path,
char *  dir_name 
)

Save all xspress3 settings into a series of files.

The directory specifed must exist. Any existing files will be overwritten.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
dir_name directory to save settings file.
Returns:
XSP3_OK or a negative error code.
int xsp3_scaler_check_desc ( int  path,
int  card 
)

This function checks the DMA descriptors for the Scaler stream to check how many time frames of scalers have been successfuly transfered to memeory.

Now recommend using xsp3_scaler_check_progress as this checks full system.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration.
Returns:
The number of complete time frames or a negative error code.
int xsp3_scaler_check_progress ( int  path  ) 

This function checks how many time frames have been processed.

For hardware scalers, it check the DMA descriptors for the Scaler stream to check how many time frames of scalers have been successfuly transfered to memeory. For a multi card system it checks all cards and returns the smalleset number of completed frames.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
The number of complete time frames or a negative error code.
int xsp3_scaler_dtc_read ( int  path,
double *  dest,
unsigned  scaler,
unsigned  chan,
unsigned  t,
unsigned  n_scalers,
unsigned  n_chan,
unsigned  dt 
)

Read a block of dead time corrected scaler data.

If only scalers are required, this the the normal entry point for scalers. However, due to the overhead of reading the scalers from the FPGA board, if both scalers and spectra are required, please use xsp3_hist_dtc_read4d.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
dest a pointer to the data buffer to receive scaler data
scaler is the first scaler number to read
chan is the first channel to read
t the first time frame to read
n_scalers the number of scaler to read
n_chan number of channels to read
dt number of time frame to read
Returns:
XSP3_OK or a negative error code.
int xsp3_scaler_get_num_tf ( int  path  ) 

Read the maximum number of time frames of scaler data that can be stored with the current memory allocation within the FEM.

The number of time frames may be limited by the scalers or by the MCA memory (see xsp3_get_format).

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
Returns:
number of time frames or a negative error code.
int xsp3_scaler_read ( int  path,
u_int32_t *  dest,
unsigned  scaler,
unsigned  chan,
unsigned  t,
unsigned  n_scalers,
unsigned  n_chan,
unsigned  dt 
)

Read a block of scaler data.

This is the normal entry point to read scaler data without dead time correction. 

 * The data block will comprise of
 * time frame[t]		channel[chan]			scaler[scaler]				data[0]
 *																			...
 * 												scaler[scaler+n_scaler-1]	data[n_scaler-1]
 * 																			...
 * 						channel[chan+n_chan-1]	scaler[scaler]				data[(n_chan-1)*n_scaler]
 * 																			...
 * 												scaler[n_scaler]			data[n_chan*n_scaler-1]
 * 																			...
 * time frame[t+dt-1]	channel[chan]			scaler[scaler]				data[(dt-1)*n_chan*n_scaler]
 *																			...
 * 												scaler[scaler+n_scaler-1]	data[dt*(nchan-1)*n_scaler-1]
 * 																			...
 * 						channel[chan+n_chan-1]	scaler[scaler]				data[(dt*nchan-1)*n_scaler]
 * 																			...
 * 												scaler[scaler+n_scaler-1]	data[dt*n_chan*n_scaler-1]
 *
 * where the scalers are defined as:
 * scaler 0 - Time
 * scaler 1 - ResetTicks
 * scaler 2 - ResetCount
 * scaler 3 - AllEvent
 * scaler 4 - AllGood
 * scaler 5 - InWIn 0
 * scaler 6 - In Win 1
 * scaler 7 - PileUp
 * scaler 8 - Total Time
 *
Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
dest a pointer to the data buffer to receive scaler data
scaler is the first scaler number to read
chan is the first channel to read
t the first time frame to read
n_scalers the number of scaler to read
n_chan number of channels to read
dt number of time frame to read
Returns:
XSP3_OK or a negative error code.
int xsp3_scope_wait ( int  path,
int  card 
)

This function polls the DMA descriptors for the two scope DMA streams to check whether all the data has been transfered.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration. If card <0 the function waits until all cards in the system have finished.
Returns:
XSP3_OK or a negative error code.
int xsp3_set_disable_threading ( int  path,
int  flags 
)

Set Disable multi threading flags.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
flags Replacement disable multi threading flags. See XSP3_MT_FLAGS
Returns:
0 on success or a negative error code.
int xsp3_set_glob_timeA ( int  path,
int  card,
u_int32_t  time 
)

Setup the triggering or time frame control register.

This register should be set to control how the system is to be triggered. Some bits are under user control, others are set/cleared by xsp3_system_start. The timing control can either be from software (XSP3_GTIMA_SRC_SOFTWARE) or from the various hardware inputs. The most common hardware input is to use TTL input 1 to control exposure so the system counts while this input is high. (XSP3_GTIMA_SRC_TTL_VETO_ONLY). The polarity of the selected Veto (and frame0) signals can be inverted using XSP3_GLOB_TIMA_VETO_INV or XSP3_GLOB_TIMA_F0_INV respectively. For hardware testing and potentially to daisy chain cards the TTL inputs can be looped to the TTL output using XSP3_GLOB_TIMA_LOOP_IO. There is a debounce circuit on the Veto and Frame 0 input which digitally ignores pulses (high or low going) below a minimum width specifeid in 80 MHz clock cylces 0..255. This is set using XSP3_GLOB_TIMA_DEBOUNCE(time) . This is very useful to help with reflections on long cables with questioanable termination so is recommended.

For demonstration and easy integration into systems with existing scalers, some pulse outputs can be multiplexed onto the TTL outputs. See XSP3_GLOB_TIMA_ALT_TTL(). The following bits should be overwritten by the xsp3_system_start and associated xsp3_histogram_* functions and should not be set by the user code: XSP3_GLOB_TIMA_ENB_SCALER, XSP3_GLOB_TIMA_ENB_HIST, XSP3_GLOB_TIMA_NUM_SCAL_CHAN(x), XSP3_GLOB_TIMA_RUN, XSP3_GLOB_TIMA_PB_RST, XSP3_GLOB_TIMA_COUNT_ENB
The following definitions describe the layout of the global time A register xspress3.h XSP3_GLOBAL_TIMEA_REGISTER The time frame source bits are defined as: xspress3.h XSP3_GLOBAL_TIMEA_BITS 0..2 The Alternate TTL output modes are defined as: xspress3.h XSP3_GLOBAL_TIMEA_ALT_TTL

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration. If card is less than 0 then all cards are selected.
time the time frame register
Returns:
XSP3_OK or a negative error code.
int xsp3_set_glob_timeFixed ( int  path,
int  card,
u_int32_t  time 
)

Set the fixed time frame register.

Whenever the time frame is reset, at the beginning of a run or using the frame 0 input, thetime frame resets to this value.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration. If card is less than 0 then all cards are selected.
time the fixed time frame register
Returns:
XSP3_OK or a negative error code.
int xsp3_set_good_thres ( int  path,
int  chan,
u_int32_t  good_thres 
)

Set the threshold for the good event scaler.

The system provides 2 versions of all event scaler. The AllGood scaler only counts events above a noise threshold, specified here.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
chan is the number of the channel in the xspress3 system, 0 to (xsp3_get_num_chan() - 1) if chan is less than 0 then all channels are selected.
good_thres the threshold for the good event scaler
Returns:
XSP3_OK or a negative error code.
int xsp3_set_roi ( int  path,
int  chan,
int  num_roi,
XSP3Roi *  roi 
)

Sets the regions of interest.

This sets the region of interest BRAM to output only selected region(s0 of the spectra, placing all other counts into the last bin. It will usually follow a call to xsp3_format_run with nbits_eng<12.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
chan is the number of the channel in the xspress3 system, 0 to (xsp3_get_num_chan() - 1) if chan is less than 0 then all channels are selected.
num_roi the number of regions of interest.
roi a pointer to an array of XSP3Roi structures describing the details the region.
Returns:
total number of bins used or a negative error code.
int xsp3_set_run_flags ( int  path,
int  flags 
)

Set the run mode flags.

The run mode flags control which DMA engines are started by xsp3_system_start usually called from xsp3_histogram_start. The default run flags are XSP3_RUN_FLAGS_SCALERS | XSP3_RUN_FLAGS_HIST which should be enabled unless these features are specifically to be turned off to reduce data in special experiments. Note this is not fully supported. If playback of test data into the system is required, then flags must include XSP3_RUN_FLAGS_PLAYBACK. If saving of scope mode data to DRAM is required, then flags must include XSP3_RUN_FLAGS_SCOPE. Enabling either of theswe not required will still work, but xsp3_system_start will take longer to run.



The following definitions describe the valid values for the stream xspress3.h XSP3_RUN_FLAGS

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
flags 
Returns:
XSP3_OK or a negative error code.
int xsp3_set_window ( int  path,
int  chan,
int  win,
int  low,
int  high 
)

Set the scaler windows.

The system provides in firmware or emulates 2 in-window scalers per channel to count typically fluorescence data. The upper and lower limits are specifed in energy bins using this function. They are stored independently on each channel, though this function can copy the same settings tor all channels. Events are counted as in window provided low <= eng <= high

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
chan is the number of the channel in the xspress3 system, 0 to (xsp3_get_num_chan() - 1) if chan is less than 0 then all channels are selected.
win the window scaler (0 or 1)
low the low window threshold (0 ... 4095)
high the high window threshold (0 ... 409)
Returns:
XSP3_OK or a negative error code.
int xsp3_setDeadtimeCalculationEnergy ( int  path,
double  energy 
)

Set the energy for dead time energy correction.

The user code should tell the library at approximately what energy the system is operating. TODO: May calculate from the MCA.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
energy the energy in keV
Returns:
XSP3_OK or a negative error code.
int xsp3_write_playback_data ( int  path,
int  card,
u_int32_t *  buffer,
size_t  nbytes 
)

Write playback data into DRAM via the 10G ethernet link.

Parameters:
path a handle to the top level of the xspress3 system returned from xsp3_config().
card is the number of the card in the xspress3 system, 0 for a single card system and up to (xsp3_get_num_cards() - 1) for a multi-card system, where this value has been passed to xsp3_config() at xspress3 system configuration.
buffer buffer containing playback data
nbytes number of bytes of data in buffer
Returns:
greater or equal to 0 for success else negative error code
Generated on Wed Oct 29 2014 09:17:10 for xspress3api by  doxygen 1.7.1