Functions#

unsigned int Decimal2IEEEFloating(double DecimalNumber)#

Converts a double to an IEEE 754 standard format number. See IEEE 754 for more information.

Parameters:

IEEEFloatingNumber – The double to convert to IEEE 754 standard format.

Returns:

The IEEE 754 representation of the provided double.

double IEEEFloating2Decimal(unsigned int IEEEFloatingNumber)#

Converts an IEEE 754 standard format number to a double. See IEEE 754 for more information.

Parameters:

IEEEFloatingNumber – The IEEE 754 standard format number to convert to a double.

Returns:

The double representation of the provided IEEE 754 formatted number.

int Pixie16AcquireADCTrace(unsigned short ModNum)#

Use this function to acquire ADC traces from Pixie-16 modules. After the successful return of this function, the DSP’s internal memory will be filled with ADC trace data. A user’s application software should then call the function Pixie16ReadSglChanADCTrace() to read the ADC trace data out to the host computer, channel by channel.

unsigned short module_number = 0;
int retval = Pixie16AcquireADCTrace(module_number);
if (retval < 0) {
    // error handling
}

Parameters:

ModNum – Counting starts at 0. If ModNum is greater than or equal to the number of modules in the system, then execute against all modules. Otherwise only execute against the specified module.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16AcquireBaselines(unsigned short ModNum)#

Use this function to acquire baselines from Pixie-16 modules. After the successful return of this function, the DSP’s internal memory will be filled with baselines data. Users should then call Pixie16ReadSglChanBaselines() to read the baselines data out to the host computer, channel by channel.

Warning

This function is unsupported by the Revision H modules.

unsigned short ModNum = 0;
int retval = Pixie16AcquireBaselines(ModNum);
if (retval < 0) {
    // Error handling
}

Parameters:

ModNum – Counting starts at 0. If ModNum is greater than or equal to the number of modules in the system, then execute against all modules. Otherwise only execute against the specified module.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16AdjustOffsets(unsigned short ModNum)#

Use this function to adjust the DC-offsets of Pixie-16 modules. After the DC-offset levels have been adjusted, the baseline level of the digitized input signals will be determined by the DSP parameter BaselinePercent. For instance, if BaselinePercent is set to 10(%), the baseline level of the input signals will be ~ 409 on the 12-bit ADC scale ([0,4095]).

The main purpose of this function is to ensure the input signals fall within the voltage range of the ADCs so that all input signals can be digitized by the ADCs properly.

unsigned short ModNum = 0;
int retval = Pixie16AdjustOffsets(ModNum);
if (retval < 0) {
    // Error handling
}

Parameters:

ModNum – Counting starts at 0. If ModNum is greater than or equal to the number of modules in the system, then execute against all modules. Otherwise only execute against the specified module.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16BLcutFinder(unsigned short ModNum, unsigned short ChanNum, unsigned int *BLcut)#

Use this function to find the Baseline Cut value for one channel of a Pixie-16 module. The baseline cut value is then downloaded to the DSP, where baselines are captured and averaged over time. The cut value would prevent a bad baseline value from being used in the averaging process, i.e., if a baseline value is outside the baseline cut range, it will not be used for computing the baseline average. Averaging baselines over time improves energy resolution measurement.

unsigned short ModNum = 0;
unsigned short ChanNum = 0;
unsigned int BLcut;
int retval = Pixie16BLcutFinder(ModNum, ChanNum, &BLcut);
if (retval < 0) {
    // Error handling
}

Parameters:

ModNum – The module number to work with, starts counting at 0.
ChanNum – The channel number to work with, starts counting at 0.
BLcut – A pointer to the variable that will hold the result of the calculation.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16BootModule(const char *ComFPGAConfigFile, const char *SPFPGAConfigFile, const char *TrigFPGAConfigFile, const char *DSPCodeFile, const char *DSPParFile, const char *DSPVarFile, unsigned short ModNum, unsigned short BootPattern)#

Use this function to boot Pixie modules so that they can be set up for data taking. The function downloads to the Pixie modules the communication (system) FPGA configurations, signal processing FPGA (FIPPI) configurations, trigger FPGA configurations (Revision A modules only), executable code for the digital signal processor (DSP), and DSP parameters. The module’s slot determines which DSP parameter object to load from the file.

The FPGA configurations consist of a fixed number of words depending on the hardware devices. The DSP codes have a length which depends on the actual compiled code; and the set of DSP parameters always consists of 1280 32-bit words for each module. The host software has to make the names of those boot data files on the hard disk available to the boot function.

/*
 * We will assume that there are a total of 5 modules in the system and that
 * they are all the same type. Modules can be booted individually by calling the
 * module's number.
 */
unsigned short ModNum = 5;
// We assume that this is the first time the modules were booted after power-up.
unsigned short BootPattern = 0x7F;
int retval = Pixie16BootModule(
    "C:\\XIA\\Pixie16\\Firmware\\syspixie16.bin", "C:\\XIA\\Pixie16\\Firmware\\fippixie16.bin",
    null, "C:\\XIA\\Pixie16\\DSP\\Pixie16DSP.ldr", "C:\\XIA\\Pixie16\\Configuration\\default.set",
    "C:\\XIA\\Pixie16\\DSP\\Pixie16DSP.var", ModNum, BootPattern);
if (retval < 0) {
    // Error handling
}

Parameters:

ComFPGAConfigFile – Path to communications FPGA configuration file
SPFPGAConfigFile – Path to signal processing FPGA configuration file
(IGNORED) (TrigFPGAConfigFile) – name of trigger FPGA configuration file
DSPCodeFile – Path to executable code file for digital signal processor (DSP)
DSPParFile – Path to DSP parameter file
DSPVarFile – Path to DSP variable names file
ModNum – Counting starts at 0. If ModNum is greater than or equal to the number of modules in the system, then execute against all modules. Otherwise only execute against the specified module.
BootPattern – See Boot Pattern.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16BootModuleFirmware(const char *DSPParFile, unsigned short ModNum, unsigned short BootPattern)#

Use this function to boot Pixie modules after the crate has already found all the firmware files in the system. The module’s slot determines which DSP parameter object to load from the file.

/*
 * We will assume that there are a total of 5 modules in the system and that
 * they are all the same type. Modules can be booted individually by calling the
 * module's number.
 */
unsigned short ModNum = 5;
// We assume that this is the first time the modules were booted after power-up.
unsigned short BootPattern = 0x7F;
int retval = Pixie16BootModuleFirmware(
    "C:\\XIA\\Pixie16\\Configuration\\default.json", ModNum, BootPattern);
if (retval < 0) {
    // Error handling
}

Parameters:

DSPParFile – Path to DSP parameter file
ModNum – Counting starts at 0. If ModNum is greater than or equal to the number of modules in the system, then execute against all modules. Otherwise only execute against the specified module.
BootPattern – See Boot Pattern

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16CheckExternalFIFOStatus(unsigned int *nFIFOWords, unsigned short ModNum)#

Use this function to check the size of the module’s Worker FIFO while a list-mode data acquisition run is in progress. Users may then use this value in Pixie16ReadDataFromExternalFIFO() to read the data from the Worker FIFO.

Note

When running in a synchronous Worker mode (not recommended), this function will report the information directly from the hardware.

unsigned int nFIFOWords = 0;
unsigned short ModNum = 0;
int retval = Pixie16CheckExternalFIFOStatus(&nFIFOWords, ModNum);
if (retval < 0) {
    // Error handling
}

Parameters:

nFIFOWords – A pointer to the variable that will hold the total number of 32-bit words contained in the Worker FIFO.
ModNum – The module number to read from. Numbering starts counting at 0.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16CheckRunStatus(unsigned short ModNum)#

Use this function to check the run status of a Pixie-16 module while a data run is in progress. If the run is still in progress continue polling.

If the return code of this function indicates the run has finished, there might still be some data in the external FIFO (Rev-B, C, D, F modules) that need to be read out to the host computer. In addition, final run statistics and histogram data are available for reading out too.

In MCA histogram run mode, this function can also be called to check if the run is still in progress even though it is normally self-terminating.

unsigned short ModNum = 0;
int retval = Pixie16CheckRunStatus(ModNum);
if (retval < 0) {
    // Error handling
} else if (retval == 1) {
    // run is still in progress
} else if (retval == 0) {
    // run has finished
}

Parameters:

ModNum – The module number to interrogate and counting starts at 0.

Return values:

0 – No run is in progress
1 – Run is still in progress
Any Negative Integer – The value of the xia::pixie::error::code indicating the result of the operation.

double Pixie16ComputeInputCountRate(unsigned int *Statistics, unsigned short ModNum, unsigned short ChanNum)#

Use this function to calculate the input count rate on one channel of a Pixie-16 module in units of triggers per second.

Note

This function does not communicate with Pixie-16 modules.

std::vector<unsigned int> stats(Pixie16GetStatisticsSize(), 0);
unsigned short ModNum = 0;
// First get the statistics data
if (Pixie16ReadStatisticsFromModule(stats.data(), ModNum) < 0) {
    // Error handling
}

unsigned short ChanNum = 0;
double icr = Pixie16ComputeInputCountRate(stats.data(), ModNum, ChanNum);

Parameters:

Statistics – A pointer to the statistics array returned by Pixie16ReadStatisticsFromModule()
ModNum – The module number which starts counting at 0.
ChanNum – The channel number which starts counting at 0.

Return values:

Positive Number – The number of triggers divided by the live time in seconds.
Negative Integer – The value of the xia::pixie::error::code indicating the result of the operation.

double Pixie16ComputeLiveTime(unsigned int *Statistics, unsigned short ModNum, unsigned short ChanNum)#

Use this function to calculate the channel’s live time as measured by the FPGA. This time excludes time during which the input signal was out of the ADC’s voltage range or when the data run was stopped. This value should always be equal to, or less than, the Real time obtained from Pixie16ComputeRealTime().

Note

This function does not communicate with Pixie-16 modules.

std::vector<unsigned int> stats(Pixie16GetStatisticsSize(), 0);
unsigned short ModNum = 0;
// First call Pixie16ReadStatisticsFromModule to get the statistics data
if (Pixie16ReadStatisticsFromModule(stats.data(), ModNum) < 0) {
    // Error handling
}

unsigned short ChanNum = 0;
double livetime = Pixie16ComputeLiveTime(stats.data(), ModNum, ChanNum);

Parameters:

Statistics – A pointer to the statistics array returned by Pixie16ReadStatisticsFromModule()
ModNum – The module number which starts counting at 0.
ChanNum – The channel number which starts counting at 0.

Return values:

Positive Number – The live time in seconds.
Negative Integer – The value of the xia::pixie::error::code indicating the result of the operation.

double Pixie16ComputeOutputCountRate(unsigned int *Statistics, unsigned short ModNum, unsigned short ChanNum)#

Use this function to calculate the output count rate on one channel of a Pixie-16 module in units of triggers per second.

Note

This function does not communicate with Pixie-16 modules.

std::vector<unsigned int> stats(Pixie16GetStatisticsSize(), 0);
unsigned short ModNum = 0;
// First call Pixie16ReadStatisticsFromModule to get the statistics data
if (Pixie16ReadStatisticsFromModule(stats.data(), ModNum) < 0) {
    // Error handling
}

unsigned short ChanNum = 0;
double ocr = Pixie16ComputeOutputCountRate(stats.data(), ModNum, ChanNum);

Parameters:

Statistics – A pointer to the statistics array returned by Pixie16ReadStatisticsFromModule()
ModNum – The module number which starts counting at 0.
ChanNum – The channel number which starts counting at 0.

Return values:

Positive Number – The number of triggers divided by the live time in seconds.
Negative Integer – The value of the xia::pixie::error::code indicating the result of the operation.

double Pixie16ComputeProcessedEvents(unsigned int *Statistics, unsigned short ModNum)#

Warning

This function is not currently implemented.

Use this function to calculate the number of events processed by a Pixie-16 Revision A module during a data acquisition run.

Note

This function does not communicate with Pixie-16 modules.

std::vector<unsigned int> stats(Pixie16GetStatisticsSize(), 0);
unsigned short ModNum = 0;
// First call Pixie16ReadStatisticsFromModule to get the statistics data
if (Pixie16ReadStatisticsFromModule(stats.data(), ModNum) < 0) {
    // Error handling
}

unsigned short ChanNum = 0;
// compute number of processed events
double NumEvents = Pixie16ComputeProcessedEvents(stats.data(), ModNum);

Parameters:

Statistics – A pointer to the statistics array returned by Pixie16ReadStatisticsFromModule()
ModNum – The module number which starts counting at 0.
ChanNum – The channel number which starts counting at 0.

Return values:

-803 – Always returns a not-implemented error.

double Pixie16ComputeRawInputCount(unsigned int *Statistics, unsigned short ModNum, unsigned short ChanNum)#

Compute the number of triggers seen by the FPGA’s trigger filter.

Note

This function does not communicate with Pixie-16 modules.

std::vector<unsigned int> stats(Pixie16GetStatisticsSize(), 0);
unsigned short ModNum = 0;
// First call Pixie16ReadStatisticsFromModule to get the statistics data
if (Pixie16ReadStatisticsFromModule(stats.data(), ModNum) < 0) {
    // Error handling
}

unsigned short ChanNum = 0;
// compute number of processed events
double raw_input_count = Pixie16ComputeRawInputCount(stats.data(), ModNum);

Parameters:

Statistics – A pointer to the statistics array returned by Pixie16ReadStatisticsFromModule()
ModNum – The module number which starts counting at 0.
ChanNum – The channel number which starts counting at 0.

Return values:

Positive Number – The number of fast triggers that the channel observed.
Negative Integer – The value of the xia::pixie::error::code indicating the result of the operation.

double Pixie16ComputeRawOutputCount(unsigned int *Statistics, unsigned short ModNum, unsigned short ChanNum)#

Computes the number of channel events processed by the system. This differs from c:func:Pixie16ComputeRawInputCount in that these events may have additional validation applied. This number should always be equal to or less than the raw input counts.

Note

This function does not communicate with Pixie-16 modules.

std::vector<unsigned int> stats(Pixie16GetStatisticsSize(), 0);
unsigned short ModNum = 0;
// First call Pixie16ReadStatisticsFromModule to get the statistics data
if (Pixie16ReadStatisticsFromModule(stats.data(), ModNum) < 0) {
    // Error handling
}

unsigned short ChanNum = 0;
// compute number of processed events
double raw_output_count = Pixie16ComputeRawOutputCount(stats.data(), ModNum);

Parameters:

Statistics – A pointer to the statistics array returned by Pixie16ReadStatisticsFromModule()
ModNum – The module number which starts counting at 0.
ChanNum – The channel number which starts counting at 0.

Return values:

Positive Number – The number of output counts processed by the system.
Negative Integer – The value of the xia::pixie::error::code indicating the result of the operation.

double Pixie16ComputeRealTime(unsigned int *Statistics, unsigned short ModNum)#

Use this function to calculate the time that a Pixie-16 module has spent on data acquisition.

Note

This function does not communicate with Pixie-16 modules.

std::vector<unsigned int> stats(Pixie16GetStatisticsSize(), 0);
unsigned short ModNum = 0;
// First call Pixie16ReadStatisticsFromModule to get the statistics data
if (Pixie16ReadStatisticsFromModule(stats.data(), ModNum) < 0) {
    // Error handling
}

unsigned short ChanNum = 0;
// compute real time
double realtime = Pixie16ComputeRealTime(stats.data(), ModNum);

@see Pixie16ReadStatisticsFromModule

Parameters:

Statistics – A pointer to the statistics array returned by Pixie16ReadStatisticsFromModule()
ModNum – The module number which starts counting at 0.

Return values:

Positive Number – The total time spent on data acquisition during a data run.
Negative Integer – The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16CopyDSPParameters(unsigned short BitMask, unsigned short SourceModule, unsigned short SourceChannel, unsigned short *DestinationMask)#

Use this function to copy DSP parameters from one module to the others that are installed in the system.

unsigned short BitMask = 0x1FF;
unsigned short SourceModule = 0;
unsigned short SourceChannel = 0;
unsigned short DestinationMask[384];

// Assume there are 6 Pixie-16 modules in the system, and we copy to all of them
for (unsigned short k = 0; k < (6 * NUMBER_OF_CHANNELS); k++)
    DestinationMask[k] = 1;

int retval = Pixie16CopyDSPParameters(BitMask, SourceModule, SourceChannel, DestinationMask);
if (retval < 0) {
    // Error handling
}

Parameters:

BitMask –

A bit pattern that designates what items should be copied from the source module to the destination module(s). For example, a value of 4097 (2⁰ + 2¹²) will copy the filter parameters and QDC.

Bit

Item

0

Filter (energy and trigger)

1

Analog signal conditioning (polarity, dc-offset, gain/attenuation)

2

Histogram control (minimum energy, binning factor)

3

Decay time

4

Pulse shape analysis (trace length and trace delay)

5

Baseline control (baseline cut, baseline percentage)

7

Channel CSRA register (good channel, trigger enabled, etc.)

8

CFD trigger (CFD delay, scaling factor)

9

Trigger stretch lengths (veto, external trigger, etc.)

10

FIFO delays (analog input delay, fast trigger output delay, etc.)

11

Multiplicity (bit masks, thresholds, etc.)

12

QDC (QDC sum lengths)

SourceModule – The module that we’ll read the settings from, starts counting at 0.
SourceChannel – The channel we’ll read settings from, starts counting at 0.
DestinationMask – A pointer to an array that indicates the channel and module whose settings will be copied from the source channel and module. For instance, if there are 5 modules (total 80 channels) in the system, DestinationMask would be defined as DestinationMask[80], where DestinationMask[0] to DestinationMask[15] would select channel 0 to 15 of module 0, DestinationMask[16] to DestinationMask[31] would select channel 0 to 15 of module 1, and so on. If a given channel i is to be copied, then DestinationMask[i] should be set to 1, otherwise, it should be set to 0.

Returns:

Bit	Item
0	Filter (energy and trigger)
1	Analog signal conditioning (polarity, dc-offset, gain/attenuation)
2	Histogram control (minimum energy, binning factor)
3	Decay time
4	Pulse shape analysis (trace length and trace delay)
5	Baseline control (baseline cut, baseline percentage)
7	Channel CSRA register (good channel, trigger enabled, etc.)
8	CFD trigger (CFD delay, scaling factor)
9	Trigger stretch lengths (veto, external trigger, etc.)
10	FIFO delays (analog input delay, fast trigger output delay, etc.)
11	Multiplicity (bit masks, thresholds, etc.)
12	QDC (QDC sum lengths)

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16EndRun(unsigned short ModNum)#

Use this function to end a data run. In a multi-module system, if running synchronously, only the director module needs to be addressed this way. It will immediately stop the run in all other module in the system.

unsigned short ModNum = 0;
if (Pixie16EndRun(ModNum) < 0) {
    // Error handling
}

Parameters:

ModNum – The module number to execute the operation against, which starts counting at 0.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16ExitSystem(unsigned short ModNum)#

This function cleanly shuts down modules when users are finished with them. Closing the module

releases the PCI virtual address,

stops any data run in progress, and

terminates the the worker.

This function should be called before a user’s application exits.

unsigned short ModNum = 0;
if (Pixie16ExitSystem(ModNum) < 0) {
    // Error handling
}

// Assumes that there are 5 modules in the system.
unsigned short ModNum = 5;
if (Pixie16ExitSystem(ModNum) < 0) {
    // Error handling
}

Parameters:

ModNum – Counting starts at 0. If ModNum is greater than or equal to the number of modules in the system, then execute against all modules. Otherwise only execute against the specified module.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

unsigned int Pixie16GetStatisticsSize(void)#

The statistics data block size may vary between Pixie-16 revisions. Use this function to ensure that the statistics data block used with Pixie16ReadStatisticsFromModule() is properly sized.

Returns:: The number of words needed to hold all the statistics data.

int Pixie16InitSystem(unsigned short NumModules, unsigned short *PXISlotMap, unsigned short OfflineMode)#

Use this function to configure the Pixie modules in the PXI chassis. This function must be called as the first step in the boot process. It makes the modules known to the system and opens each module for communication.

The log file “Pixie16Msg.log” will be opened for logging at the beginning of this function. Prior to calling this function. The environment variable PIXIE16_LOG_LEVEL can be set to one of the following logging levels. If PIXIE16_LOG_LEVEL is not set, default logging level is INFO.

Level	Description
DEBUG	All messages, including information only relevant to the developers at XIA
INFO	All messages except for debug messages
WARNING	All warning and error messages
ERROR	Only messages that cause a routine to end its execution early

This function also kicks off a call to find all of the system firmware installed on the system.

std::vector<unsigned short> PXISlotMap = {2, 3, 4, 5, 6};
unsigned short OfflineMode = 0;
if (Pixie16InitSystem(PXISlotMap.size(), PXISlotMap, OfflineMode) < 0) {
    // Error handling
}

Parameters:

NumModules – The total number of Pixie modules in the system provided by the user. If 0 all slots are checked and automatically assigned in increasing slot number.
PXISlotMap –
Serves as a simple mapping of the logical module number and the physical slot number that the modules reside in. The logical module number counts from 0. For instance, in a system with 5 Pixie modules, these 5 modules may occupy slots 3 through 7. The user must fill PXISlotMap as follows: PXISlotMap = {3, 4, 5, 6, 7} since module number 0 resides in slot number 3, etc.

Note

Modules present in the crate but not listed in the slot map will left available for use by another process. This call will hold a module not in the map until the slot assignment process closes the module.
OfflineMode – OfflineMode mode builds a virtual crate that simulates crate functionality. This mode can be enabled using an input value of 1. An input value of 0 indicates that the system should look for a physical crate.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16LoadModuleFirmware(const char *SearchPath)#

Use this function to retrieve firmware files from the file system at the given path. If the path is invalid, an error will be thrown. If no firmware can be found, no firmware will be loaded onto the crate by this function.

Note

The firmware packages pointed to by this search path must be folders extracted from firmware packages released by XIA after 2024-05-27. Older zip archives are not compatible with the automatic firmware management.

if (Pixie16LoadModuleFirmware("C:\\xia\\pixie-16\\firmware") < 0) {
    // Error handling
}

Parameters:

SearchPath – The system path to retrieve the firmware files from.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16SetModuleFirmware(const char *FwFile, unsigned int ModNum, const char *Device)#

Use this function to set or override a chosen module’s firmware file, setting/replacing based on the file extension of the file (.ldr, .var, .bin). Files with .bin are also distinguished as fippi and sys firmware files.

If the module does not have a firmware file for the device type, this function will create a new firmware object with the given firmware filename and add it to the crate’s firmware.

if (Pixie16SetModuleFirmware("C:\\xia\\pixie-16\\firmware\\13-100-12\\1.0.0\\dsp.var", 0, "var") < 0) {
    // Error handling
}

Parameters:

FwFile – The filepath of the firmware.
ModNum – The number of the module to set the firmware of.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16LoadDSPParametersFromFile(const char *FileName)#

Use this function to read DSP parameters from a settings file and then load the settings to Pixie-16 modules that are installed in the system.

if (Pixie16LoadDSPParametersFromFile("C:\\XIA\\Pixie16\\Configuration\\test.json") < 0) {
    // Error handling
}

Parameters:

FileName – Absolute path to the DSP settings file to be loaded.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16ReadDataFromExternalFIFO(unsigned int *ExtFIFO_Data, unsigned int nFIFOWords, unsigned short ModNum)#

This function reads data from the module’s Worker FIFO. The data are 32-bit unsigned integers.

Warning

When running in a synchronous Worker mode (not recommended), this function will report the information directly from the hardware. This mode of operation may lead to data loss!

unsigned short ModNum = 0;
unsigned int nFIFOWords = 0;
// First, check how many words need to be read out of the FIFO.
if (Pixie16CheckExternalFIFOStatus(&nFIFOWords, ModNum) < 0) {
    // Error handling
}

// Second, initialize a storage location large enough to hold all the data.
std::vector<uint32_t> data(nFIFOWords, 0);
// Finally, read the data from the external FIFO.
if (nFIFOWords > 0) {
    if (Pixie16ReadDataFromExternalFIFO(data.data(), nFIFOWords, ModNum) < 0) {
        // Error handling
    }
}

Warning

If you statically allocate your container, you must make sure nFIFOWords does not exceed your allocated space, or you will write past your container.

Parameters:

ExtFIFO_Data – A pointer to a memory block containing enough space for nFIFOWords worth of 32-bit unsigned integers.
nFIFOWords – The number of words to read from the FIFO. We recommend using Pixie16CheckExternalFIFOStatus() to check the amount of data so that the container to hold the data is properly sized.
ModNum – The module number that we’ll read from. Numbering starts at 0.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16ReadHistogramFromModule(unsigned int *Histogram, unsigned int NumWords, unsigned short ModNum, unsigned short ChanNum)#

Use this function to read out the histogram data from a Pixie-16 module’s histogram memory. Each histogram bin is represented by a 32-bit unsigned integer.

unsigned short ModNum = 0;
unsigned short ChanNum = 0;
unsigned int histo_len = 0;
PixieGetHistogramLength(ModNum, ChanNum, &histo_len);
std::vector<unsigned int> Histogram(histo_len, 0);
int retval =
    Pixie16ReadHistogramFromModule(Histogram.data(), histo_len, ModNum, ChanNum);
if (retval < 0) {
    // Error handling
}

Parameters:

Histogram – A pointer to an array large enough to hold the histogram data read from the requested channel.
NumWords – The size of the histogram to read out of the memory.
ModNum – The module number that we want the histogram from
ChanNum – The channel number that we’d like to read from

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16ReadModuleInfo(unsigned short ModNum, unsigned short *ModRev, unsigned int *ModSerNum, unsigned short *ModADCBits, unsigned short *ModADCMSPS)#

Use this function to read information stored on each module, including its revision, serial number, ADC bits and sampling rate. This must be done after calling Pixie16InitSystem(). Information from the module can be used to select the appropriate firmware, DSP, and configuration parameters files before booting the module.

Note

For a more robust implementation please see PixieGetModuleInfo().

unsigned short ModuleNumber;
unsigned short ModRev;
unsigned int ModSerNum;
unsigned short ModADCBits;
unsigned short ModADCMSPS;
if (Pixie16ReadModuleInfo(ModuleNumber, &ModRev, &ModSerNum, &ModADCBits, &ModADCMSPS) < 0) {
    // Error handling
}

Parameters:

ModNum – The module number (counts from 0) that we’ll read information
ModRev – A pointer to the variable that will hold the module’s revision as an integer
ModSerNum – A pointer to the variable that will hold the serial number
ModADCBits – A pointer to the variable that will hold the ADC bit resolution
ModADCMSPS – A pointer to the variable that will hold the ADC sampling frequency

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16ReadSglChanADCTrace(unsigned short *Trace_Buffer, unsigned int Trace_Length, unsigned short ModNum, unsigned short ChanNum)#

Use this function to read ADC trace data from a channel. Before calling this function, Pixie16AcquireADCTrace() should be called to fill the DSP internal memory first.

unsigned short ModNum = 0;
unsigned short ChanNum = 0;

// First, acquire the ADC trace from the hardware
if (Pixie16AcquireADCTrace(ModNum) < 0) {
    // Error handling
}

// Second, allocate a storage object to hold the resulting trace.
int len = 0;
PixieGetTraceLength(ModNum, ChanNum, &len);
std::vector<unsigned short> ADCTrace(len, 0);

// Finally, read the trace from the module object.
if (Pixie16ReadSglChanADCTrace(ADCTrace.data(), len, ModNum, ChanNum) < 0) {
    // Error handling
}

Parameters:

Trace_Buffer – Pointer to the data buffer large enough to hold the trace data.
Trace_Length – The length of the trace as obtained by PixieGetTraceLength()
ModNum – The module that we want to read
ChanNum – The channel that we want to read

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16ReadSglChanBaselines(double *Baselines, double *TimeStamps, unsigned short NumBases, unsigned short ModNum, unsigned short ChanNum)#

Use this function to read baseline data from a module. Before calling this function, Pixie16AcquireBaselines() should be called to fill the DSP internal memory.

In the DSP internal memory, each baseline is a 32-bit IEEE floating point number. After being read out to the host, this function will convert each baseline data to a decimal number. In addition to baseline values, time stamps corresponding to each baseline are also returned after this function call.

unsigned short ModNum = 0;
unsigned short ChanNum = 0;

// First, capture the baseline measurements from the hardware.
if (Pixie16AcquireBaselines(ModNum) < 0) {
    // Error handling
}

int num_baselines = 0;
PixieGetMaxNumBaselines(ModNum, ChanNum, &num_baselines);
std::vector<double> baselines(num_baselines, 0);
std::vector<double> timestamps(num_baselines, 0);

// Finally, read a single channel's baseline from the local memory.
if (Pixie16ReadSglChanBaselines(baselines.data(), timestamps.data(), num_baselines, ModNum, ChanNum) < 0) {
    // Error handling
}

Parameters:

Baselines – An array of doubles to hold the baseline values, whose size matches the value provided in NumBases.
TimeStamps – An array of doubles indicating the time the baseline was collected according to the internal clock. The size must be equal to the value provided in NumBases.
NumBases – The number of baselines to read out of the hardware. Use the PixieGetMaxNumBaselines() function retrieve the maximum number of baselines that can be retrieved.
ModNum – The module number to read the baselines from, counting from 0.
ChanNum – The channel number to read the baselines from, counting from 0.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16ReadSglChanPar(const char *ChanParName, double *ChanParData, unsigned short ModNum, unsigned short ChanNum)#

Read a channel parameter from a module.

unsigned short ModNum = 0;
unsigned short ChanNum = 0;
double ChanParData;
if (Pixie16ReadSglChanPar("ENERGY_RISETIME", &ChanParData, ModNum, ChanNum) < 0) {
    // Error handling
}

Parameters:

ChanParName – The name of the channel parameter that we’ll read
ChanParData – A pointer to the variable to hold the returned value.
ModNum – The module number we’ll read from. Counting starts at 0.
ChanNum – The channel number we’ll read from. Counting starts at 0.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16ReadSglModPar(const char *ModParName, unsigned int *ModParData, unsigned short ModNum)#

Read a module parameter from a Pixie module.

unsigned short ModNum = 0;
unsigned int ModParData;
if (Pixie16ReadSglModPar("SLOW_FILTER_RANGE", &ModParData, ModNum) < 0) {
    // Error handling
}

Parameters:

ModParName – The name of the module parameter that we’ll read
ModParData – A pointer to the variable that will hold the returned value.
ModNum – The module number we’ll read from. Numbering starts counting at 0.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16ReadStatisticsFromModule(unsigned int *Statistics, unsigned short ModNum)#

Use this function to read out statistics data from a Pixie-16 module. The number of statistics data for each module can vary based on the firmware and channel count. Statistics data are 32-bit unsigned integers.

std::vector<unsigned int> stats(Pixie16GetStatisticsSize(), 0);
unsigned short ModNum = 0;
// First call Pixie16ReadStatisticsFromModule to get the statistics data
if (Pixie16ReadStatisticsFromModule(stats.data(), ModNum) < 0) {
    // Error handling
}

Parameters:

Statistics – A pointer to the statistics array containing enough space to hold the statistics data as 32-bit unsigned integers. The necessary size can be obtained from Pixie16GetStatisticsSize().
ModNum – The module number that we want statistics data from.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16SaveDSPParametersToFile(const char *FileName)#

Save DSP parameters to a settings file

Warning

The settings file is an internally managed file and should not be modified by the user.

This function saves the DSP variables to the provided file name in JSON format. The data file now contains only the information necessary to initialize a module’s variables and metadata about the module that was previously used. The metadata contains

the module’s serial number,

the firmware associated with the module,

the ADC information for each channel of the module,

and other information that may be useful to reconstruct a specific setup.

The API will only write out settings for active modules within the system. For example, if a crate has 5 modules (4 online and 1 offline), then the settings file will contain entries for the 4 online modules.

if (Pixie16SaveDSPParametersToFile("C:\\XIA\\Pixie16\\Configuration\\test.json") < 0) {
    // Error handling
}

Parameters:

FileName – Absolute path to where we will write the DSP variable file.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16SetDACs(unsigned short ModNum)#

Use this function to reprogram the on-board DACs of the Pixie-16 modules. In this operation the DSP uses data from the DSP parameters that were previously downloaded.

unsigned short ModNum = 0;
if (Pixie16SetDACs(ModNum) < 0) {
    // Error handling
}

Parameters:

ModNum – The module number, which starts counting at 0.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16StartHistogramRun(unsigned short ModNum, unsigned short mode)#

Use this function to begin a data acquisition run that accumulates energy histograms, one for each channel. It launches a data acquisition run in which only energy information is preserved and histogrammed locally to each channel.

Call this function for each Pixie-16 module in the system to initialize the run in each module. Actual data acquisition will start synchronously in all modules when the last module finished the initialization (requires SYNCH_WAIT to be set). Histogram runs can be self-terminating when the elapsed run time exceeds the preset run time, or the user can prematurely terminate the run by calling Pixie16EndRun(). On completion, final histogram and statistics data will be available.

// We will assume that there are 5 total modules in the system.
unsigned short mode = NEW_RUN;
unsigned short ModNum = 5;
double runtime_in_seconds = 10.0;

// First, write the run time to the hardware as an IEEE 754 formatted number.
if (Pixie16WriteSglModPar("HOST_RT_PRESET", Decimal2IEEEFloating(runtime_in_seconds), ModNum) < 0) {
    // Error handling
}

// Second, start the histogram data run.
if (Pixie16StartHistogramRun(ModNum, mode) < 0) {
    // Error handling
}

Parameters:

ModNum – The module number which starts counting at 0. If ModNum is set to be less than the total number of modules in the system, only the module specified by ModNum will have its histogram run started. But if ModNum is set to be equal to the total number of modules in the system, then all modules in the system will have their runs started together.The module number that we’d like to work against. Starts counting at 0.
mode – How we’ll handle existing data when starting up the run. Use mode NEW_RUN or 1 to erase histograms and statistics information before launching the new run. Use mode RESUME_RUN or 0 to resume an earlier run.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16StartListModeRun(unsigned short ModNum, unsigned short RunType, unsigned short mode)#

Use this function to start a list-mode data acquisition run in Pixie-16 modules. list-mode runs are used to collect data on an event-by-event basis, gathering energies, timestamps, pulse shape analysis values, and waveforms for each event. Runs will continue until the user terminates the run by calling Pixie16EndRun(). To start the data acquisition, this function has to be called for every Pixie-16 module in the system. If all modules are to run synchronously, the last module addressed will release all others and the acquisition starts then. The first module to end the run will immediately stop the run in all other modules if run synchronization has been set up among these modules.

There is only one list-mode run type supported, that is, 0x100. However, different output data options can be chosen by enabling or disabling different CHANNEL_CSRA bits.

// We will assume 5 modules in the system, and will start a run in all modules.
unsigned short mode = NEW_RUN;
unsigned short ModNum = 5;
unsigned short RunType = 0x100;
if (Pixie16StartListModeRun(ModNum, RunType, mode) < 0) {
    // Error handling
}

Parameters:

ModNum – ModNum is the module number which starts counting at 0. If ModNum is set to be less than the total number of modules in the system, only the module specified by ModNum will have its list-mode run started. But if ModNum is set to equal to the total number of modules in the system, then all modules in the system will have their runs started together.
RunType – The type of run that we’re going to be executing. There’s only one 0x100.
mode – How we’ll handle existing data when starting up the run. Use mode NEW_RUN or 1 to erase histograms and statistics information before launching the new run. Note that this will cause a startup delay of up to 1 millisecond. Use mode RESUME_RUN or 0 to resume an earlier run. This mode has a startup delay of only a few microseconds.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16TauFinder(unsigned short ModNum, double *Tau)#

Use this function to find the exponential decay-time constants (TAU) for all channels of a Pixie-16 module.

Warning

This function is disabled in Revision H modules.

unsigned short ModNum = 0;
::module_config mcfg;
PixieGetModuleInfo(mod.number, &mcfg);

vector<double> Tau(mcfg.number_of_channels, 0);
if (Pixie16TauFinder(ModNum, Tau) < 0) {
    // Error handling
}

Parameters:

ModNum – The module number to work with. Starts counting at 0.
Tau – Pointer to an array big enough to hold the calculated tau value for each channel of the module. A value of -1.0 indicates a failed calculation for that channel. Units are microseconds.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16WriteSglChanPar(const char *ChanParName, double ChanParData, unsigned short ModNum, unsigned short ChanNum)#

Write a channel parameter to a module.

unsigned short ModNum = 0;
unsigned short ChanNum = 3;
unsigned int value = 0.123;
if (Pixie16WriteSglChanPar("TAU", value, ModNum, ChanNum) < 0) {
    // Error handling
}

Parameters:

ChanParName – The name of the channel parameter that we’ll write
ChanParData – The value that we’ll write to the provided channel
ModNum – The module number we’ll write to. Counting starts at 0.
ChanNum – The channel number we’ll write to. Counting starts at 0.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int Pixie16WriteSglModPar(const char *ModParName, unsigned int ModParData, unsigned short ModNum)#

Write a module parameter to a Pixie module.

unsigned short ModNum = 0;
unsigned int ModParData = 4;
if (Pixie16WriteSglModPar("SLOW_FILTER_RANGE", ModParData, ModNum) < 0) {
    // Error handling
}

Parameters:

ModParName – The name of the module parameter that we’ll write
ModParData – The value of the module parameter that we’ll write
ModNum – The module number we’ll write to. Numbering starts counting at 0.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieBootCrate(const char *settings_file, const enum PIXIE_BOOT_MODE boot_mode)#

Boot a crate of modules in parallel. This operation is faster than booting modules individually. Registered firmware sets are used to boot the modules. The COMM, FIPPI FPGA and DSP code and variable map files are loaded together.

The provided settings file is loaded after the modules are online. A module is considered offline if it’s unverified and the COMMS, FIPPI or DSP are not loaded and running.

Parameters:

settings_file – The path to a crate’s settings file
boot_mode – PIXIE_BOOT_MODE

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieGetHistogramLength(unsigned short mod_num, unsigned short chan_num, unsigned int *hist_length)#

Gets the maximum histogram buffer size in words (32-bit unsigned integers). The histogram buffer size may vary based on the hardware’s channel configuration This function allows users to determine the specific size of the histogram data block for the specific module/channel combination. This size can then be used to allocate vectors of the correct size for the histogram data.

Parameters:

mod_num – The module that holds the channel we want the size for.
chan_num – The channel that we want the histogram size for.
hist_length – A pointer to the variable to hold the length of the histogram.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieGetMaxNumBaselines(unsigned short mod_num, unsigned short chan_num, unsigned int *max_num_baselines)#

Gets the maximum number of baseline samples for a channel. c:func:Pixie16AcquireBaselines always collects the maximum number of baselines for each channel. Users can then request fewer baselines than that, but upto the maximum provided by this function.

Parameters:

mod_num – The module that holds the channel we want the size for.
chan_num – The channel that we want the histogram size for.
max_num_baselines – Pointer to the variable to store the maximum number of baselines

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieGetModuleInfo(unsigned short mod_num, struct module_config *cfg)#

Use this function to read configuration information about the requested module. This should be done after Pixie16InitSystem(). If this function is called before booting the module, then the firmware information will be unpopulated.

Information from the module can be used to select the appropriate firmware, DSP, and configuration parameters files before booting the module.

unsigned short mod_num = 0;
module_config cfg;
int retval = PixieGetModuleInfo(mod_num, &cfg);
if (retval < 0) {
    // error handling
}

Parameters:

mod_num – The module number (counts from 0) that we’ll read information
cfg – A pointer to the module_config object that will store the retrieved data.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieGetReturnCodeText(int return_code, char *buf, unsigned int buf_size);#

Gets the error string associated with the provided error code. Since exceptions are purely a C++ construct, we wrap all the SDK calls with exception handling. These wrappers catch the exception, transform its integer value to negative, and then return that as the function’s exit code. This keeps us in line with previous functionality.

This function allows users to obtain the return code’s text by providing the return code and a buffer to hold the resulting message. This function will return an error status if the provided buffer isn’t large enough to hold the resulting text.

Parameters:

return_code – The return code that we’d like the error text for.
buf – Pointer to the char buffer that will hold the resultant text. It’s recommended that you provide a buffer of at least 1024. The message are much shorter than this, but that may change in the future.
buf_size – The size of the data buffer to hold the return code text.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation..

int PixieGetTraceLength(unsigned short mod_num, unsigned short chan_num, unsigned int *trace_length)#

The trace buffer size may vary based on the hardware’s channel configuration This function allows users to determine the specific size of the trace data block for the specific module/channel combination. This size can then be used to allocate vectors of the correct size for the trace data.

Parameters:

mod_num – The module that holds the channel we want the size for.
chan_num – The channel that we want the histogram size for.
trace_length – Pointer to the variable to store the trace length.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieGetWorkerConfiguration(unsigned short mod_num, struct fifo_worker_config *worker_config)#: Warning

Deprecated. To be removed November 30, 2024.

See, PixieGetFifoConfiguration().

int PixieGetFifoConfiguration(unsigned short mod_num, struct fifo_worker_config *worker_config)#

Gets a worker configuration from the specified module

Parameters:

mod_num – The module number to get the configuration from.
worker_config – A pointer to the fifo_worker_config to populate

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieReadRunFifoStats(unsigned short mod_num, struct module_fifo_stats *fifo_stats)#

Read the run’s statistics for the module. If a run as finished the statistics are for the last run.

Parameters:

mod_num – The module number to read the statistics from.
fifo_stats – A pointer to the module_fifo_stats to hold the data.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieRegisterCrateFirmware(const unsigned int version, const int revision, const int adc_msps, const int adc_bits, const char *device, const char *path)#

Registers a Firmware with the crate and makes it available as a partial firmware set. For each module number in your system, call this function for each firmware in that module’s firmware set.

Parameters:

version – The firmware version as an integer. Prior to implementing semantic versioning, this was the DSP ldr file’s SVN commit id. It can be obtained from the ldr file name.
revision – The associated hardware revision as an integer. Ex. Rev F = 0xF = 15, Rev H = 0x11 = 17
adc_msps – The ADC sampling frequency associated with the firmware. Ex. 250
adc_bits – The ADC bit resolution associated with the firmware. Ex. 14
device – The device associated with the firmware. One of dsp, var, fippi, sys
path – The absolute path to the firmware file on the host system.

int PixieRegisterFirmware(const unsigned int version, const int revision, const int adc_msps, const int adc_bits, const char *device, const char *path, unsigned short ModNum)#

Registers a Firmware to a specific module and makes it available as a partial firmware set.

Parameters:

version – The firmware version as an integer. Prior to implementing semantic versioning, this was the DSP ldr file’s SVN commit id. It can be obtained from the ldr file name.
revision – The associated hardware revision as an integer. Ex. Rev F = 0xF = 15, Rev H = 0x11 = 17
adc_msps – The ADC sampling frequency associated with the firmware. Ex. 250
adc_bits – The ADC bit resolution associated with the firmware. Ex. 14
device – The device associated with the firmware. One of dsp, var, fippi, sys
path – The absolute path to the firmware file on the host system.
ModNum – The module that will be registered with this firmware.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSetWorkerConfiguration(unsigned short mod_num, struct fifo_worker_config *worker_config)#: Warning

Deprecated. Will be removed on November, 30, 2024

See PixieSetFifoConfiguration()

int PixieSetFifoConfiguration(unsigned short mod_num, struct fifo_worker_config *worker_config)#

Sets a module’s fifo configuration to with the values stored in the config.

Parameters:

mod_num – The module number to set the configuration.
worker_config – A pointer to the fifo_worker_config to set.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

char *PixieGetInstallationPath(const enum PIXIE_INSTALL_PATH opt, ...)#

Parameters:

opt – The PIXIE_INSTALL_PATH that contains the information desired.

Returns:

The path used by the SDK to find the system firmware.

Returns NULL:

If the provided option cannot be matched.

int PixieSysControlClose(void)#

Close the current query and release all allocated resources.

int retval = PixieSysControlClose();
if (retval < 0) {
    // Error handling
}

Returns:: The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSysControlGet(const char *path, char *value, size_t size)#

Get a single MIB variable given a complete path to a variable. The value returned a string representation of the MIB value. The value is truncated and a terminating null character is always appended. If you provide a 64 character buffer and the value string is longer than 64 character only 63 characters are returned with the 64th character being a terminating null character.

// Assumes a Revision H module in Slot 2.
char path[] = {"module.2.revision"};
char rev[3] = {"\0"};
int retval = PixieSysControlGet(path, rev, 3);
// rev array should now contain {'1', '7', '\0'}
if (retval < 0) {
    // error handling
}

char badrev[2] = {"\0"};
int retval = PixieSysControlGet(path, badrev, 2);
// badrev array should now contain {'1', '\0'}
if (retval < 0) {
    // error handling
}

Parameters:

path – An absolute path to a MIB variable. For example, module.2.serial-num.
value – A char array that will be filled with the value contained at the provided path. This value will always be null terminated. It is the caller’s responsibility to allocate an array with enough space to hold the resulting value. Providing an array that is too short may result in data loss.
size – The length of the value array. 2 is the minimum possible array length.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSysControlGetDouble(const char *path, double *value)#

Get a single MIB variable of type real given a complete path to the variable. The value returned is of type double.

// Assumes a booted module in Slot 2.
double val = 0.;
int retval = PixieSysControlGetDouble("module.2.run.bandwidth", &val);
if (retval < 0) {
    // error handling
}

Parameters:

path – The absolute path to the MIB variable.
value – A pointer to a double that will store the value. The provided value is overwritten.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSysControlGetInt(const char *path, int *value)#

Get a single MIB variable of type integer given a complete path to the variable. The value returned is of type integer. If the MIB is of type boolean, then an integer is returned.

// Assumes a booted module in Slot 2.
int val = 0;
int retval = PixieSysControlGetInt("module.2.serial-num", &val);
if (retval < 0) {
    // error handling
}

Parameters:

path – The absolute path to the MIB variable.
value – A pointer to an integer that will store the value. The provided value is overwritten.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSysControlOpen(const char *query, const enum PIXIE_SYSCTL_FORMAT format);#

Opening a system control query takes a MIB snapshot at the time the open call occurred. The contents are not updated until a new query happens. If the call is successful, then you can request the size of the data using PixieSysControlSize(), then read the data using PixieSysControlRead(). The query resources are release when the close call is made.

// Open a new MIB query for all module serial numbers.
int retval = PixieSysControlOpen("module.*.serial-num", PIXIE_SYSCTL_FORMAT_TEXT);
if (retval != 0) {
    //error handling
}

Parameters:

query – A regular expression string using ECMA-262 grammar. If NULL or an empty string is passed in all MIB variables are returned.
format – The returned data format.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSysControlRead(char *buffer, size_t *size)#

Read the report data into the provided buffer. The size of the buffer is passed in and the amount of data read is returned. If the size of data returned is 0 all the data has been read. Used in conjunction with PixieSysControlOpen() and PixieSysControlSize(), and PixieSysControlClose().

// We assume you've already called PixieSysControlOpen with a valid query.
size_t len = 0;
int retval = PixieSysControlSize(&len);
char* buffer = malloc(len);
retval = PixieSysControlRead(buffer, &len);
// Do something with the data
free(buffer);

Parameters:

buffer – A pointer to a buffer the data is read into. The buffer has to be as big as a size pass in by the size argument.
size – Pointer to the size. This must be less than or equal to the size of the memory the buffer argument points too. The call updates the size to amount of data read. The amount of data read will not exceed the size value passed in. If the size is 0 no data is returned and all data in the query has been read.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSysControlSet(const char *path, const char *value)#

Set a single MIB variable given a complete path to the variable. If the MIB variable is not of type string the string value will be converted to the type of the MIB variable. An error will be returned if the string cannot be converted to the type of the MIB variable.

Note

There are currently no user writable MIB variables.

Parameters:

path – The absolute path to the MIB variable to be set.
value – A string containing the value to write to the MIB variable.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSysControlSetDouble(const char *path, const double value)#

Set a single MIB variable of type real given a complete path to the variable.

Note

There are currently no user writable MIB variables.

Parameters:

path – The absolute path to the MIB variable to be set.
value – A string containing the value to write to the MIB variable.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSysControlSetFileValues(const char *filename, const enum PIXIE_SYSCTL_FORMAT format)#

Loads the data contained in a file into a string buffer and sets the MIB variables to the provided values.

Note

There are currently no user writable MIB variables.

Parameters:

filename – A string containing the path to the file to load.
format – The format of the data contained in the file.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSysControlSetInt(const char *path, const int value)#

Set a single MIB variable of type integer given a complete path to the variable.

Note

There are currently no user writable MIB variables.

Parameters:

path – The absolute path to the MIB variable to be set.
value – A string containing the value to write to the MIB variable.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSysControlSetValues(const char *values, const enum PIXIE_SYSCTL_FORMAT format)#

Takes a buffer containing the values to set and sets them based on the format provided.

Note

There are currently no user writable MIB variables.

Parameters:

values – A pointer to a string buffer containing the data formatted using the format specifier.
format – Specifies the format used to parse the data contained in the string buffer.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.

int PixieSysControlSize(size_t *size)#

Return the size of data the query generated and read. This call can be used to allocate a single buffer to read the query string in a single read call. Used in conjunction with PixieSysControlRead() to allocate a buffer with the length necessary to read the MIB data.

// Assumes you've called PixieSysControlOpen with a valid query.
size_t len = 0;
retval = PixieSysControlSize(&len);
if (retval != 0) {
    //error handling
}

Parameters:

size – Pointer to a variable that will store the query size. Any existing value is ignored.

Returns:

The value of the xia::pixie::error::code indicating the result of the operation.