System#

Routines for starting the system, loading firmware, and load and save the entire system configuration from and to files.

int xiaBoardOperation(int detChan, char *name, void *value)#

Performs product-specific queries and operations.

Param[in] detChan:

detChan to apply the acquisition value to. May only be a single detChan; sets are not allowed.

Param[in] name:

Type of data to pass or return. Reference the product-specific Handel manuals for complete lists by product.

Param[out] value:

Variable to return the data in, cast into a void *. See the product-specific Handel manuals for the required data type for each name.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is not associated with a known module.

  • XIA_BAD_TYPE – detChan refers to a detChan set, which is not allowed in this routine.

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

  • XIA_BAD_CHANNEL – Internal Handel error. Contact XIA.

Example Usage

int status;
double new_threshold = 1000.0;

/* Set up a valid system here */
status = xiaStartSystem();
if (status != XIA_SUCCESS) {
    /* ERROR starting system */
}

/* Change trigger threshold to 1000 eV */
status = xiaSetAcquisitionValue(0, "trigger_threshold", (void *)&new_threshold);
if (status != XIA_SUCCESS) {
    /* ERROR setting trigger threshold */
}

printf("Trigger threshold now set to: %lf\n", new_threshold);
int xiaDownloadFirmware(int detChan, char *type)#

Downloads the specified firmware type to a detChan. The following firmware types are recognized: “dsp”, “fippi”, “user_dsp”, “user_fippi” and “system_fpga”.

Warning

The task of downloading firmware to the system is typically handled by xiaStartSystem(), so this routine should only be used for situations where special firmware is required.

Param[in] detChan:

detChan to download firmware to. May be either a single detChan or detChan set. -1 is not allowed.

Param[in] type:

The type of firmware to be downloaded. Must be one of “dsp”, “fippi”, “user_dsp”, “user_fippi” and “system_fpga”.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_NO_ALIAS – Internal Handel error. Contact XIA.

  • XIA_BAD_VALUE – Internal Handel error. Contact XIA.

  • XIA_INVALID_DETCHAN – Specified detChan does not exist or is not associated with a known module.

  • XIA_NO_ALIAS – Internal Handel error. Contact XIA.

  • XIA_UNKNOWN_BOARD – Board type corresponding to detChan does not exist in Handel.

  • XIA_NOSUPPORT_FIRM – The specified type of firmware to download is not supported for this board type.

  • XIA_UNKNOWN_FIRM – The specified type of firmware to download is unknown.

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;

/* Set up a valid system here */
status = xiaStartSystem();
if (status != XIA_SUCCESS) {
    /* ERROR starting system */
}

/* Want to start DSP code again */
status = xiaDownloadFirmware(0, "dsp");
if (status != XIA_SUCCESS) {
    /* ERROR downloading DSP to detChan o */
}
int xiaStartSystem(void)#

Starts the system previously defined via an .ini file. Connects to the hardware and downloads the firmware and acquisition values to all active channels in order to set the system up for data acquisition. This routine must be called after configuring the system with a configuration file (see [Initializing Handel]).

This routine also performs several validation steps to insure that all of the configuration information required to run the system is present. Specifically, the firmware and detector information is validated by Handel while the module is verified by the Product Specific Layer. If an inconsistency is found, it will be reported back as an error and should be fixed before attempting to call xiaStartSystem() again.

This routine may block for up to several seconds, depending on the size of the system and timing of firmware downloading.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_FIRM_BOTH – Both a FDD file and PTRR information have been specified in one of the firmware aliases. Please report this error to XIA since this check should be performed at the configuration stage and has only been left in as a redundancy check.

  • XIA_PTR_OVERLAP – A PTRR has a peaking time range that overlaps with another PTRR.

  • XIA_MISSING_FIRM – The DSP and/or FiPPI information is missing for a PTRR.

  • XIA_MISSING_POL – The polarity isn’t defined for a detector.

  • XIA_MISSING_GAIN – The preamplifier gain isn’t defined for at least one detector channel.

  • XIA_MISSING_TYPE – The detector type isn’t defined for a detector.

  • XIA_NO_DETCHANS – No detChans are defined in the system.

  • XIA_INFINITE_LOOP – Problem with detChan and detChan Set definitions such that an infinite loop exists. This prevents against situations where a detChan (or Set) refers to another detChan (or Set) that then refers back to itself.

  • XIA_UNKNOWN – Internal error. Contact XIA.

  • XIA_INVALID_DETCHAN – A detChan in the system does not refer to an existing module.

  • XIA_NO_ALIAS – Internal Handel error. Contact XIA.

  • XIA_BAD_NAME – Internal Handel error. Contact XIA.

  • XIA_WRONG_INTERFACE – Internal Handel error. Contact XIA.

  • XIA_BAD_CHANNEL – Internal Handel error. Contact XIA.

  • XIA_UNKNOWN_BOARD – Board type in system does not exist in Handel.

  • XIA_MISSING_INTERFACE – A module in the system is missing interface information.

  • XIA_MISSING_ADDRESS – (For Saturn/Mercury) EPP address missing from interface information.

  • XIA_INVALID_NUMCHANS – The number of channels set for a board type is incorrect.

  • XIA_BINS_OOR – The bin range is out-of-range for the board type.

  • XIA_BAD_VALUE – Internal Handel error. Contact XIA.

  • XIA_FILEERR – Error getting firmware from FDD file.

Example Usage

/* Assume a system has been created dynamically or loaded from
 * an .ini file.
 */

int status;
status = xiaStartSystem();
if (status != XIA_SUCCESS) {
    /* ERROR Starting system */
}
int xiaLoadSystem(char *type, char *filename)#

Loads a configuration file of the specified type and name. Since only one type is supported (handel_ini), it is typically more convenient to call xiaInit(), which both initializes the library and loads a handel_ini file, instead of xiaInitHandel() and xiaLoadSystem().

Note

xiaLoadSystem() calls many internal routines to initialize the various components of the system and may propagate additional error codes not listed here. Specific error codes are useful for debugging during development, but simply checking against XIA_SUCCESS provides adequate information for control flow in most user programs.

Param[in] type:

Configuration file type to load. Currently only handel_ini is supported. See [INI Files] for a detailed description of the handel_ini format.

Param[in] filename:

Name of file to read configuration from. If the name is specified as NULL, then Handel assumes that the file to be loaded is named xia.ini.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_FILE_TYPE – Specified file type is not a supported or valid format to load.

  • XIA_OPEN_FILE – Error opening file

  • XIA_NOSECTION – Section missing in file

  • XIA_FORMAT_ERROR – File is improperly formatted

  • XIA_FILE_RA – File is missing required information

Example Usage

int status;
status = xiaLoadSystem("handel_ini", "my_config.ini");
if (status != XIA_SUCCESS) {
    /* ERROR loading configuration file */
}
int xiaSaveSystem(char *type, char *filename)#

Saves the current system configuration to the specified file and with the specified format.

Param[in] type:

Configuration file type to save. handel_ini is the only supported format. See [INI Files] for a detailed description of the format.

Param[in] filename:

Name of file to save to.

Returns:

A status code indicating the result of the operation.

Return values:

  • XIA_SUCCESS – The operation completed successfully.

  • XIA_FILE_TYPE – Specified file type is not a supported or valid format to load.

  • XIA_OPEN_FILE – Error opening file

  • XIA_MISSING_TYPE – Unknown detector type

  • XIA_UNKNOWN – Internal Handel error. Contact XIA.

Example Usage

int status;

/* Set up a valid system */

status = xiaSaveSystem("handel_ini", "my_config.ini");
if (status != XIA_SUCCESS) {
    /* ERROR saving system configuration */
}