Firmware#

Routines for querying information about firmware sets, firmware files, and mappings between peaking time ranges and firmware.

int xiaGetFirmwareItem(char *alias, unsigned short ptrr, char *name, void *value)#

Retrieves information from a firmware set’s configuration. All of the names that are listed below may be retrieved. If you get the “filename” item for a firmware alias that uses PTRRs, a blank string will be returned.

Param[in] alias:

A valid firmware alias

Param[in] ptrr:

The PTRR that corresponds to the information to be retrieved. Not all names to be retrieved require a PTRR, in which case it may be set to NULL.

Param[in] name:

Name of value to retrieve

Param[out] value:

Void pointer to variable in which the returned data will be stored. It is very important that the type of this variable is appropriate for the data to be retrieved. See the tables above for more information. See the Usage section for more information on how to use void pointers in this context.

Returns:

A status code indicating the result of the operation.

Return values:

XIA_NO_ALIAS – Specified alias does not exist
XIA_BAD_VALUE – No PTRRs defined for this alias
XIA_BAD_PTRR – Specified PTRR does not exist
XIA_BAD_NAME – Specified name is invalid

Firmware Items

Name	FDD?	Type	Description
filename	y	null-terminated string	Name of FDD file to be used. This file will be searched for using the standard methods described in [Files].
keyword	y	null-terminated string	(Optional) Each time keyword is used as a name, another keyword is appended to the list associated with this firmware. CAUTION: Keywords may not be removed from the list once they are added. These keywords will be used by Handel when searching the FDD file for the proper firmware. Handel always adds a keyword associated with the detector type.
mmu	n	null-terminated string	(Optional) The filename of the memory management unit, if present.
ptrr	n	unsigned short	A unique identifier for a Peaking Time Range Reference. Each firmware should have several PTRRs to cover the full peaking time range.
min_peaking_time	n	double	The minimum peaking time value for the current PTRR in microseconds.
max_peaking_time	n	double	The maximum peaking time value for the current PTRR in microseconds.
fippi	n	null-terminated string	The filename of the FiPPI program to be downloaded for this PTRR.
dsp	n	null-terminated string	The filename of the DSP program to be downloaded for this PTRR
user_fippi	n	null-terminated string	(Optional) The filename of the user-defined FiPPI program to be downloaded for the PTRR. Not available with all products.
filter_info	n	unsigned short	Add another filter information value to the existing information. Currently, there is no way to remove filter information selectively after it has been added.
num_filter	any	unsigned short	The number of elements in the filter_info array for the specified PTRR. The typical use of this value is for allocating enough memory to retrieve the entire filter_info array using the filter_info parameter.
filter_info	any	unsigned short

Example Usage

int status;
double min_ptime;

/* Create a firmware w/ alias "firmware1" using PTRRs and add all of
 * the necessary information to it. We will only retrieve the minimum
 * peaking time for PTRR 0 here. Retrieving other values should follow
 * similar patterns.
 */

status = xiaGetFirmwareItem("firmware1", 0, "min_peaking_time", (void *)&min_ptime);

if (status != XIA_SUCCESS) {
    /* ERROR Getting PTRR 0 minimum peaking time */
}

printf("Minimum peaking time (PTRR 0) = %lf\n", min_ptime);

int xiaGetFirmwareSets(char *firmware[])#

Returns a list of the aliases of the firmware sets defined in the system. The caller must allocate memory for firmware.

Param[out] firmware:: A string array of the proper length: numFirmware by MAXALIAS_LEN (defined in handel_generic.h) Typically this is done by calling xiaGetNumFirmwareSets() and using the number of firmware sets to initialize a string array. Allocate a char * of length MAXALIAS_LEN for each firmware set.
Returns:: A status code indicating the result of the operation.

Example Usage

int status;
unsigned int numFirmware = 0;
unsigned int i;
char **firmware = NULL;

/* Assume that a system has already been loaded. */
status = xiaGetNumFirmwareSets(&numFirmware);
if (status != XIA_SUCCESS) {
    /* ERROR getting number of firmware sets */
}

/* Allocate the memory we need for the string array */
firmware = (char **)malloc(numFirmware * sizeof(char *));
if (firmware == NULL) {
    /* ERROR allocating memory for firmware sets */
}

for (i = 0; i < numFirmware; i++) {
    firmware[i] = (char *)malloc(MAXALIAS_LEN * sizeof(char));
    if (firmware[i] == NULL) {
        /* ERROR allocating memory for firmware[i] */
    }
}

status = xiaGetFirmwareSets(firmware);
if (status != XIA_SUCCESS) {
    /* ERROR getting firmware set list */
}

for (i = 0; i < numFirmware; i++) {
    printf("firmware[%u] = %sn", i, firmware[i]);
}

for (i = 0; i < numFirmware; i++) {
    free((void *)firmware[i]);
}

free((void *)firmware);
firmware = NULL;

int xiaGetFirmwareSets_VB(unsigned int index, char *alias)#

Gets a firmware set alias by index. This routine serves as a replacement of the routine xiaGetFirmwareSets() for use with Visual Basic or other languages that will not allow an array of strings to be passed into the Handel DLL. xiaGetFirmwareSets_VB() returns a single firmware alias, where index ranges from 0 to numFirmware – 1. The standard idiom is to get the number of firmware sets in the system with a call to :c:func`xiaGetNumFirmwareSets` and to then loop from 0 to numFirmware –1 in order to get all of the firmware aliases in the system.

The caller must allocate memory for alias.

Param[in] index:: Position of firmware alias in system where index ranges from 0 to numFirmware – 1. For instance, if you have a system where 3 firmware sets are defined, the valid values for index are 0, 1 and 2.
Param[out] alias:: Alias of the firmware located at the specified index. The caller must allocate memory a char * of length MAXALIAS_LEN (defined handel_generic.h).
Returns:: A status code indicating the result of the operation.
Return values:: XIA_BAD_INDEX – The specified index is out-of-range

Example Usage

int status;
unsigned int numFirmware = 0;
unsigned int i;
char **aliases = NULL;

/* Assume that a valid system has been setup
 * here.
 */
status = xiaGetNumFirmwareSets(&numFirmware);
if (status != XIA_SUCCESS) {
    /* ERROR getting # of firmware sets in system */
}

/* Must allocate proper amount of memory */
aliases = (char **)malloc(numFirmware * sizeof(char *));
if (aliases == NULL) {
    /* ERROR allocating memory for aliases array */
}

for (i = 0; i < numFirmware; i++) {
    aliases[i] = (char *)malloc(MAXALIAS_LEN * sizeof(char));
    if (aliases[i] == NULL) {
        /* ERROR allocating memory for aliases[i] */
    }
}

for (i = 0; i < numFirmware; i++) {
    status = xiaGetFirmwareSets(i, aliases[i]);
    if (status != XIA_SUCCESS) {
        /* ERROR getting firmware alias at index i */
    }
}

for (i = 0; i < numFirmware; i++) {
    printf("Firmware alias at index = %u: %s", i, aliases[i]);
}

for (i = 0; i < numFirmware; i++) {
    free((void *)aliases[i]);
}

free(aliases);

int xiaGetNumFirmwareSets(unsigned int *numFirmware)#

Returns the number of firmware sets defined in the system.

Param[out] numFirmware:: Pointer to a variable to store the returned number of firmware sets in
Returns:: A status code indicating the result of the operation.

Example Usage

int status;
unsigned int numFirmware = 0;

/* Assume that a system has already been
 * created or loaded and that it defines
 * two firmware sets.
 */
status = xiaGetNumFirmwareSets(&numFirmware);

if (status != XIA_SUCCESS) {
    /* ERROR getting number of firmware sets */
}

printf("There are currently %u firmware set(s) defined.\n", numFirmware);

int xiaGetNumPTRRs(char *alias, unsigned int numPTRR)#

Returns the number of PTRRs that are defined for the firmware set with the specified alias. If the firmware has an FDD defined instead of PTRRs an error will be returned.

Param[in] alias:

A valid firmware alias

Param[out] numPTRR:

A pointer to a variable to store the number of PTRRs in.

Returns:

A status code indicating the result of the operation.

Return values:

XIA_NO_ALIAS – Specified alias does not exist
XIA_LOOKING_PTRR – The specified firmware has an FDD defined

Example Usage

int status;
unsigned int numPTRR = 0;

/* Assume firmware with alias "firmware1" already
 * exists in the system.
 */
status = xiaGetNumPTRRs("firmware1", &numPTRR);
if (status != XIA_SUCCESS) {
    /* ERROR getting number of PTRRs */
}

printf("firmware1 has %u PTRR(s).\n", numPTRR);