Functions in Dss4lib

This library contains functions that control the DSS 4 (Digital Stimulus System 4). The functions are divided into the following categories:

Waveform Generation Functions
Timer Functions
NI-DAQ Rate Generator Functions
FPGA Rate Generator Functions
Unit Event Timer (UET) Functions
Matrix Selector Funtions

To compile and link a program using these functions, it is necessary to include:

dss4lib.h
dss4lib.lib
piodio.h
piodio.lib
nidaq32.lib

Most of these can be found in c:\Audstuff\L, but you can also look for them in

c:\PIODIO\Driver
c:\Ni-Dac
The header files for the NI-DAQ definitions are already included in DSS4lib, and are specified in:

c:\Ni-Dac\include\nidaqex.h

*******************************************************************************

Waveform Generation Functions

These functions are used to specify the characteristics of waveforms that are generated using the VC33 digital signal processor. 

	long dss4setdevnumbers (long *devnumbarray, long devcount)
	long dss4setdacmcodefile (char *filename)
	long dss4initc33dsp (long channumb)
	long dss4setsamplerate (long channumb, double rate)
	long dss4mode (long channumb, long mode)
	long dss4dur (long channumb, double dur)
	long dss4freq (long channumb, double freq)
	long dss4phase (long channumb, double phase)
	long dss4rise (long channumb, double trise,
	long dss4fall (long channumb, double tfall,
	long dss4lfm (long channumb, double freq1, double freq2, double thold1,
		double tramp1, double thold2, double tramp2)
	long dss4am (long channumb, double fmod, double amphase, double ampmod,
		double offsetdc)
	long dss4loadgewab (long channumb, long offset, long npoints, double gwbuffer)
	long dss4readgewab (long channumb, long offset, long npoints, double gwbuffer)
	long dss4setgewab (long channumb, long gewabpoints, unsigned long ratemult,
		long gwmode)
	long dss4noisedur  (long channumb, double tfall)
	long dss4noiseband(long channumb, double dur)
	long dss4noiserise (long channumb, double trise)
	long dss4noisefall (long channumb, double freqlow, double freqhigh)
	long dss4noiseamplitude (long channumb, double amplitude)
	long dss4toneamplitude (long channumb, double amplitude)
	long dss4armdsp (long channumb)
	long dss4stopdsp (long channumb)
	long dss4attnold (long channumb, float attenset)
	long dss4attn (long channumb, float attenset, long relaytype, long padcode)
	long dss4closec33dsp (long channumb)

(back to top)

long dss4setdevnumbers (long *devnumbarray, long devcount)
long *devnumbarray address of an array of device numbers (up to 16 elements)
long devcount the number of devices that are to be defined (max is 16)

This function sets up the current hardware device numbers of the available VC33 DSP devices. It allows the user to define which hardware device will be accessed when the user program chooses a DSS channel number. The user channel numbers are assumed to be 1, 2, 3, etc. up to a maximum of 16. The user specifies an array of up to 16 long integers, the contents of which define the hardware devices corresponding to the user channel numbers. The user also specifies the number of hardware devices that are being defined. This count is used by subsequent routines to check that a channel number points to a device that has been defined here.

The currently available hardware devices are: 0, 1, and 2. So, to define the channel numbers 1, 2, and 3 with the available hardware, the contents of the first 3 elements of devnumbarray should be 0, 1, and 2, respectively.

The function dss4setdevnumbers ( ) must be called before calling any of the other dss4 VC33 DSP functions.

Return values:
1 Normal return, no errors
0 The argument devcount is out of range (must be 16 or less)
other Other error setting up device numbers.

long dss4setdacmcodefile (char *filename)
char *filename name of file containing the DAC dsp microcode program

This function allows the user to specify a file containing a DAC dsp microcode program that is different from the default microcode. The default file is "C:\\Audstuff\\D\\digigen.out". If this function is not called, the default file is used.

Return values:
1 Normal return, no errors
0 Error specifying the microcode filename.

long dss4initc33dsp (long channumb)
long channumb the DSS channel to be set up (1 or 2)

This function initializes the VC33 DSP device, loads its memory with software needed for generation of tones, AM, FM, noise, and gewab waveforms. After calling this routine, the DSP mode of operation and various waveform parameters can be set up. To close the C33 DSP device, see dss4closec33dsp( ).

Return values:
1 Normal return, no errors
102 The argument channumb is out of range.
103 Error accessing the VC33 DSP device.
104 Error loading the DAC microcode file (default file is "C:\\Audstuff\\D\\digigen.out").
other Error initializing the C33 DSP board.

long dss4setsamplerate (long channumb, double rate)
long channumb the DSS channel to be set up (1 or 2)
double rate the desired sample rate (samples/sec)

This function sets the sample rate that will be used to compute parameters used by the C33 DSP. It is a parameter known to the C33 functions like dss4freq( ), dss4rise( ), etc. Its value MUST MATCH the value of the sample rate that is specified for the rate generator that is connected to the C33 channel being used.

If this function is not called, the system will use the default sample rate of 800000 Hz. (The user still must set the appropriate rate generator to 800000 Hz).

The C33 functions will use the most recent value that is specified for the dss4 sample rate. For example, if 2 separate C33 channels are being used, and a different sample rate is needed for each one, it is necessary to call dss4setsamplerate( ) before calling the C33 waveform functions for one of the channels, and then call dss4setsamplerate( ) again (with a new rate) before calling the C33 waveform functions for the other channel.

Return values:
1 Normal return, no errors
other Error setting the sample rate parameter.

long dss4mode (long channumb, long mode)
long channumb the DSS channel to be set up (1 or 2)
long mode the mode with which the DSS waveform is to be generated

This function sets up the mode of waveform generation. Possible modes are:
0 Pure tone
1 FM (Sawtooth)
2 FM (Trapizoid)
16 AM
32 Gewab
64 Noise (generated on the fly by C33 DSP processor)

Return values:
1 Normal return, no errors
other Error specifying the mode.

long dss4dur (long channumb, double dur)
long channumb the DSS channel to be set up (1 or 2)
double dur the duration (only) of the output waveform (seconds)

This function sets up the duration of the waveform. It does NOT include either the rise or fall time.

Return values:
1 Normal return, no errors
other Error specifying the duration.

long dss4freq (long channumb, double freq)
long channumb the DSS channel to be set up (1 or 2)
double freq the frequency of the output waveform (Hz)

This function sets up the frequency used in the following waveform modes:
pure tone Frequency of the tone
FM Starting frequency of the FM sweep (used during rise envelope)
AM Carrier frequency
Note that for FM, the starting frequency is specified separately, and it should equal the frequency specified here.

Return values:
1 Normal return, no errors
other Error specifying the waveform frequency.

long dss4phase (long channumb, double phase)
long channumb the DSS channel to be set up (1 or 2)
double phase the starting phase of the output waveform (0 to 1.0)

This function sets up the starting phase of the waveform. As with dss4freq( ), it is used for pure tones, FM, and AM waveforms. If a rise envelope is used, it should be the starting phase of the sinusoid within the rise envelope.

Return values:
1 Normal return, no errors
other Error specifying the waveform starting phase.

long dss4rise (long channumb, double trise, long type)
long channumb the DSS channel to be set up (1 or 2)
double trise the duration of the rise envelope (seconds)
long type the type of rise envelope (0=none, 1=linear, 2=cosine)

This function sets up the rise envelope of the waveform. There are 3 possible types (0=none, 1=linear, 2=cosine). The duration is specified in seconds.

Return values:
1 Normal return, no errors
other Error specifying the waveform rise envelope.

long dss4fall (long channumb, double tfall, long type)
long channumb the DSS channel to be set up (1 or 2)
double tfall the duration of the fall envelope (seconds)
long type the type of fall envelope (0=none, 1=linear, 2=cosine)

This function sets up the fall envelope of the waveform. There are 3 possible types (0=none, 1=linear, 2=cosine). The duration is specified in seconds.

Return values:
1 Normal return, no errors
other Error specifying the waveform fall envelope.

long dss4lfm (long channumb, double freq1, double freq2, double thold1, double tramp1, double thold2, double tramp2)
long channumb the DSS channel to be set up (1 or 2)
double freq1 the starting frequency of the FM sweep (Hz)
double freq2 the ending frequency of the FM sweep (Hz)
double thold1 the time for which the starting frequency is to be held unchanged (seconds)
double tramp1 the time for which the frequency sweeps from freq1 to freq2 (seconds)
double thold2 the time for which the ending frequency is to be held unchanged (seconds)
double tramp2 the time for which the frequency sweeps from freq2 to freq1 (seconds)

This function sets up the linear Trapizoid FM sweep mode. (Trapizoid means there is an optional holding time for both the starting and ending frequencies, in addition to the time periods for ramping up and down in frequency.) Either of the holding time periods can be set to zero. Note that the waveform STARTS with thold1.

Return values:
1 Normal return, no errors
other Error setting up the linear FM sweep in trapizoid mode.

long dss4am (long channumb, double fmod, double amphase, double ampmod, double offsetdc)
long channumb the DSS channel to be set up (1 or 2)
double fmod modulation frequency (Hz)
double amphase starting phase of amplitude modulation (0 - 1.0)
double ampmod modulation amplitude (0 - 1.0)
double offsetdc DC offset of modulation (0 - 1.0)

This function sets up the amplitude modulation mode. The carrier frequency is specified with dss4freq( ). Note that the modulation amplitude can "off center" with respect to the amplitude of the carrier waveform. This is controlled with the offsetdc argument along with the ampmod argument.

Return values:
1 Normal return, no errors
other Error setting up the amplitude modulation mode.

long dss4loadgewab (long channumb, long offset, long npoints, float *gwbuffer)
long channumb the DSS channel to be set up (1 or 2)
long offset the offset in the gewab memory space where data is to be loaded
long npoints number of data points to be loaded (must include 5 extra)
float *gwbuffer address of (float) array containing waveform

This function loads a gewab waveform into DSP memory. Note that the data array itself must already contain the gewab waveform with 5 extra data points at the end of this, which are equal to the first 5 data points in the waveform. So, the number of points to be loaded into the DSP is 5 more than the actual number of points in the gewab waveform.

Return values:
1 Normal return, no errors
other Error loading the waveform into DSP memory.

long dss4readgewab (long channumb, long offset, long npoints, float *gwbuffer)
long channumb the DSS channel to be set up (1 or 2)
long offset the offset in the gewab memory space from which data is to be read
Note: This offset MUST be within the range of the previous call to dss4loadgewab( ). If not, or if you try to read from gewab memory that has not been written into, it will cause the program to crash.
long npoints number of data points to be read
Note: This number of points MUST NOT be greater than the # of points written in the previous call to dss4loadgewab( ). If it is, or if you try to read from gewab memory that has not been written into, it will cause the program to crash.
float *gwbuffer address of (float) array containing waveform

This function reads data from the gewab memory of the DSP to a user array. It is used only to test if the gewab memory contains the data it is supposed to contain.

REMEMBER: The function dss4readgewab( ) can crash your program if not used correctly. You must always write specific data to the gewab buffer, with dss4loadgewab( ), before calling dss4readgewab( ) to read data back from the buffer. If you try to read data from buffer locations that have not been written into, it will crash your program, and possibly damage current data.

Return values:
1 Normal return, no errors
other Error reading data from DSP memory.

long dss4setgewab (long channumb, long gewabpoints, unsigned long ratemult, long gwmode)
long channumb the DSS channel to be set up (1 or 2)
long gewabpoints number of data points in gewab waveform (NOT including the 5 extra)
unsigned long ratemult sample rate multiplier (desired output rate/actual rate of waveform)
long gwmode gewab output mode (reserved for future options)

This function sets up the gewab output mode of the DSP. A gewab waveform must exist, with a known number of data points and sampling frequency. There must be 5 extra data points stored at the end of this waveform, equal to the first 5 data points in the waveform. (These are used by the DSP gewab algorithm.) The argument gewabpoints, used in this function, should NOT INCLUDE these 5 extra points. If the argument ratemult is set to 1, then the actual output sampling rate (the rate generator) should be set to equal the actual sampling frequency of the gewab waveform. Any other value of ratemult will require a sampling rate that is ratemult times the original waveform sampling frequency. The gwmode argument is not yet implemented.

Return values:
1 Normal return, no errors
other Error setting up the gewab output mode of the DSP

long dss4noisedur (long channumb, double dur)
long channumb the DSS channel to be set up (1 or 2)
double dur the duration (only) of the noise part of the output waveform (seconds)

This function sets up the duration of the noise waveform. It does NOT include either the rise or fall time.

Return values:
1 Normal return, no errors
other Error specifying the duration.

long dss4noiserise (long channumb, double trise)
long channumb the DSS channel to be set up (1 or 2)
double trise the duration of the rise envelope of the noise waveform (seconds)

This function sets up the rise envelope of the noise waveform. Only a linear envelope is allowed. This is separate from the tone rise envelope. The duration is specified in seconds.

Return values:
1 Normal return, no errors
other Error specifying the waveform rise envelope.

long dss4noisefall (long channumb, double tfall)
long channumb the DSS channel to be set up (1 or 2)
double tfall the duration of the fall envelope of the noise waveform (seconds)

This function sets up the fall envelope of the noise waveform. Only a linear envelope is allowed. This is separate from the tone rise envelope. The duration is specified in seconds.

Return values:
1 Normal return, no errors
other Error specifying the waveform fall envelope.

long dss4noiseband (long channumb, double freqlow, double freqhigh)
long channumb the DSS channel to be set up (1 or 2)
double freqlow the low frequency limit of the pass band being specified
double freqhigh the high frequency limit of the pass band being specified

This function sets up the cutoff frequencies of the pass band of the noise waveform. It MUST be called in order to generate noise. If broad band noise (all frequencies) is desired, specify the cutoff frequencies as 1 Hz and 1/2 the sample rate.

The sample rate for noise waveforms can not be as high as that for tones. The maximum rate is somewhere above 400000 Hz, and is still being determined.

Return values:
1 Normal return, no errors
other Error specifying the cutoff frequencies.

long dss4noiseamplitude (long channumb, double amplitude)
long channumb the DSS channel to be set up (1 or 2)
double amplitude the amplitude of the noise waveform (seconds)

This function sets up the amplitude of the noise waveform. Possible values are 0 to 1.0.

Return values:
1 Normal return, no errors
other Error specifying the noise waveform amplitude

long dss4toneamplitude (long channumb, double amplitude)
long channumb the DSS channel to be set up (1 or 2)
double amplitude the amplitude of the tone waveform (seconds)

This function sets up the amplitude of the tone waveform. Possible values are 0 to 1.0.

Return values:
1 Normal return, no errors
other Error specifying the tone waveform amplitude

long dss4armdsp (long channumb)
long channumb the DSS channel to be set up (1 or 2)

This function arms the C33 DSP after having specified all necessary waveform parameters. The DSP then waits for the timers to start the stimulus. Note that setting the attenuator with dss4attn( ) also has the effect of arming the DSP. It is ok to call both dss4armdsp( ) and dss4attn( ), provided the DSS4 timers are not on, and no new parameters need to be set up before running the timers.

Return values:
1 Normal return, no errors
other Error arming the C33 DSP.

long dss4stopdsp (long channumb)
long channumb the DSS channel to be stopped (1 or 2)

This function stops the C33 DSP. Once the DSP has been armed, this function stop any output going to the DAC, and return the C33 to the mode where it expects to be armed, either with the function dss4armdsp( ) or dss4attn( ). Even if the stimulus has finished, the function dss4stopdsp( ) should be called before any DSP parameters are changed.

Return values:
1 Normal return, no errors
other Error stopping the C33 DSP.

long dss4attnold (long channumb, float attenset)
long channumb the DSS channel to be set up (1 or 2)
float attenset attenuation value (0 to 127.5), in dB

This function is used to set an older version of the DSS4 attenuator -- used before March 10, 2003. To set up the newer attenuator, use the function dss4attn( ).

Here, the specified attenuation is a floating point value, and the output should be accurate to the nearest 0.5 dB. This function also arms the DSP (puts the DSP in the mode of waiting for the timers to start).

Return values:
1 Normal return, no errors
101 Attenuation value out of range (0 to 127.5)
other Error setting attenuator.

long dss4attn (long channumb, double attenset, long relaytype, long padcode)
long channumb the DSS channel to be set up (1 or 2)
double attenset attenuation value (0 to 95) in dB that will either be used directly or added to an optional 40 dB 'pad' (see below)
long relaytype code for the type of relay being used (0=mechanical, 1=solid state). NOTE: to change from one to the other requires a hardware change. Specifying the wrong type here will result in the padcode argument being interpreted differently, so be careful.
long padcode code for whether the 40 dB 'pad' is used or not (0=without pad, 1=with pad)

This function sets up the attenuator of one DSS4 channel, and it uses the hardware that was installed on March 10, 2003. This device differs from the older hardware and it provides a wider range of attenuations. There are 2 modes of operation for it:

1. Without its internal pad. Here the range is 0 - 95 dB.
2. With its internal pad. Here the range is 40 dB - 135 dB.

Without the pad, the attenuation will equal attenset. The pad adds 40 dB of attenuation to the signal, so the resulting attenuation is 40 dB plus the value specified in attenset. In both modes output should be accurate to the nearest 0.5 dB. This function also arms the DSP (puts the DSP in the mode of waiting for the timers to start).

There is also an option for the type of relay being used. (To switch to a different type of relay, you must physically change the hardware chip.) So, use the argument relaytype to tell the DSP which configuration you are using. A value of 0 means the Mechanical relay, and a value of 1 means the Solid State relay. The DSP software needs to know which one is connected in order to interpret the value of padcode properly.

Return values:
1 Normal return, no errors
101 Attenuation value out of range (0 to 127.5)
other Error setting attenuator.

long dss4closec33dsp (long channumb)
long channumb the DSS channel to be stopped (1 or 2)

This function closes the device channel of the C33 DSP. It should only be called when stopping all activity on the C33 DSP card of the DSS4.

Return values:
1 Normal return, no errors
other Error closing the C33 DSP.

(back to top)

*******************************************************************************

Timer Functions

	long dss4resettimer (long timernumb)
	long dss4inittimer (long timernumb,long startmode)
	long dss4settimer (long timernumb, double rint, double dur,
		double del, long nreps)
	long dss4armtimer (long timernumb)
	long dss4disarmtimer (long timernumb)
	long dss4timerstat (long timernumb, unsigned long *pulsestate,
		unsigned long *gatestate, unsigned long *gatecount)

The Timer Functions are used to control the duration timers of the DSS 4 system. These timers are used to gate the stimuli on and off, provide precise repetition intervals, and produce the desired number of repetitions of the stimuli. The timers are generated with a National Instruments NI-DAQ 6602 timer board, with 4 timers per board. Each of them can be started independently, either with a software start or a hardware trigger.

long dss4resettimer (long timernumb)
long timernumb the NI-DAQ timer to be reset (1 - n)

This function resets one of the NI-DAQ timers. It stops the timer and clears its parameters.

Return values:
1 Normal return, no errors
1003 Invalid timer number.
other Error resetting timer

long dss4inittimer (long timernumb,long startmode)
long timernumb the NI-DAQ timer to be initialized (1 - n)
long startmode the start mode for the timer (1 = software, 2 = hardware trigger)

This function initializes a NI-DAQ timer. It must be called before any of the other NI-DAQ functions for an individual timer. If startmode is set to 1, the timer will expect a software start (see the function dss4armtimer( )). If startmode is 2, the timer will be started by a low-to-high signal on its trigger input. Note that dss4inittimer( ) configures a timer, but it does not arm the timer to wait for a hardware input trigger. The function dss4armtimer( ) must be called to do this.

Return values:
1 Normal return, no errors
1003 Invalid timer number.
1004 Invalid start mode.
other Error initializing timer.

long dss4settimer (long timernumb, double rint, double dur, double del, long nreps)
long timernumb the timer to be set (1 - n)
double rint the repetition time of the timer (sec)
double dur the duration time of the timer (sec)
double del the delay of the timer (sec)
long nreps the number of repetitions to be generated

This function sets the parameters to be used by a NI-DAQ timer. The timer produces an output which starts out in the low state, and goes high after a time equal to 'del'. It then produces a series of pulses, which are in the high state for a time equal to 'dur', and in a low state for a time equal to 'rint' - 'dur'. The number of pulses in the series is equal to 'nreps'.

This output can be connected to the gate input of the C33 DSP, to produce 'nreps' repetitions of the waveform produced by the C33. The 'dur' argument of dss4settimer( ) must equal the true duration of whatever waveform is being generated by the DSP and gated by the NI-DAQ timer, which includes any rise or fall envelope that the waveform has.

The output of the timer can also be used to trigger a different timer. In this case, the trigger produced by the timer will occur after the 'del' time has passed, and when the first pulse starts.

Here are the limitations on the timer parameters:

Mininum value of any argument -- .000002 sec
Maximum value of 'dur' or 'del' -- 4294.96 sec
Maximum value of ('rint'*'nreps') - 4294.96 sec
'rint-dur' must be greater than .000002 sec
'rint-dur' must be less than 4294.96 sec

Return values:
1 Normal return, no errors
1003 Invalid timer number.
1005 (rint*nreps) too large
1006 (rint*nreps) too small
1007 dur too large
1008 dur too small
1009 del too large
1010 del too small
1011 off time (rint-dur) too large
1012 off time (rint-dur) too small
other Error setting timer parameters

long dss4armtimer (long timernumb)
long timernumb the timer to be armed (1 - n)

This function arms a timer of the NI-DAQ 6602. If the timer is in external start mode, it arms it to wait for its hardware trigger. If the timer is in program start mode, it is started. So, this function acts as the program start itself.

The function dss4settimer( ) must be called before calling dss4armtimer( ).

Return values:
1 Normal return, no errors
1003 Invalid timer number.
other Error arming timer

long dss4disarmtimer (long timernumb)
long timernumb the timer to be disarmed (stopped) (1 - n)

This function returns a timer of the NI-DAQ 6602 to the state it was in before it was armed. Its counters are stopped, thus stopping the timer. Its parameters should be retained. Any other timers will continue timing.

Return values:
1 Normal return, no errors
1003 Invalid timer number.
other Error disarming timer

long dss4timerstat (long timernumb, unsigned long *pulsestate, unsigned long *gatestate, unsigned long *gatecount)
long timernumb the timer for which the status is to be determined (1 - n)
unsigned long *pulsestate address of the word into which the pulse state will be written (possible states are: 1=HIGH, 0=LOW)
unsigned long *gatestate address of the word into which the gate state will be written (possible states are: 1=HIGH, 0=LOW)
unsigned long *gatecount address of the word into which the gate count will be written (the count remaining for the current gate state)

This function is used to find out the status of a given timer of the NI-DAQ 6602. Each timer has a pulse output and a gate output. The pulse output generates the pulses used to create the repetition of the stimulus. The pulse output state is HIGH for a time specified by 'dur', while the stimulus is on. (See dss4settimer (long timernumb, double rint, double dur, double del, long nreps) ). It is LOW for a time equal to 'rint'-'dur', while the stimulus is off.

The pulse output will only generate pulses if the gate output is in the high state. The gate output state starts out LOW and stays LOW for a time equal to 'del'. It is then HIGH for a time equal to 'rint'*'nreps'.

Note that the pulse output state is HIGH whenever pulses are not being generated -- when the gate output state is LOW. To determine if the stimulus is actually on, the output states of the gate and pulse can be AND'ed together -- if they are both HIGH, the stimulus is on.

The value returned in gatecount is the number of counts remaining to go during the current gate output state. If the current gate state is LOW, then gatecount equals the number of counts remaining for the time 'del' to finish. If the timer is waiting for its start trigger, gatecount will equal the full number of counts in the time 'del'. If the gate state is HIGH, gatecount equals the number of counts remaining for the time 'rint'*'nreps' to finish. The value in gatecount can be converted to seconds by dividing by the timebase of the NI-DAQ counter in question.

Return values:
1 Normal return, no errors
1003 Invalid timer number.
other Error fetching status of timer

(back to top)

*******************************************************************************

NI-DAQ Rate Generator Functions


	long dss4rgreset (long rgnumb)
	long dss4rgrate (long rgnumb, double rate, double phase, long startmode)
	long dss4rgrateact (double rate,double *rateact)
	long dss4rgarm (long rgnumb)
	long dss4rgdisarm (long rgnumb)

These functions are used to control the rate generators of the DSS4 system. These rate generators are produced by a National Instruments NI-DAQ 6602 timer board. They are numbered from 0 to 7, with the following rate generators connected directly to specific hardware:
0 The timebase of the DSS4 duration timers. This rate generator MUST be set to 1000000 Hz, because the duration timers are programmed to use this timebase.
1 The sample rate of the waveform generated by DSS4, channel 1. It MUST match the sample rate specified for channel 1 in the function dss4setsamplerate ( ), or be equal to the default value of 800000 Hz. Dss4rgrate( ) must be called in either case.
2 The sample rate of the waveform generated by DSS4, channel 2. It MUST match the sample rate specified for channel 2 in the function dss4setsamplerate ( ), or be equal to the default value of 800000 Hz. Dss4rgrate( ) must be called in either case.
3 The sample rate of the A/D converter.
Rate generators 4-7 are available for use, via the connectors on the front panel.

long dss4rgreset (long rgnumb)
long rgnumb the rate generator to be reset (0 - 7)

This function resets one of the rate generators. It stops the its counter and resets internal NI-DAQ parameters to default values.

Return values:
1 Normal return, no errors
303 Invalid rate generator number
other NI-DAQ error resetting the counter

long dss4rgrate (long rgnumb, double rate, double phase, long startmode)
long rgnumb the rate generator to be setup (0 - 7)
double rate the desired rate (.009 Hz to 20000000 Hz)
double phase the phase of the rate generator (not being used for now)
long startmode the startmode of the rate generator
1 = software start (starts when armed)
2 = external start on a single hardware edge
3 = external start via a hardware gate signal, where the rate gen runs only when the gate signal is high

This function sets up one of the rate generators. It must be called before arming the rate generator.

Return values:
1 Normal return, no errors
303 Invalid rate generator number
304 Rate out of range
305 Invalid start mode
other NI-DAQ error setting up the rate generator

long dss4rgrateact (double rate,double *rateact)
double rate the specified rate to be checked
double rateact the actual rate that would be generated by the device -- note that this argument is a pointer to double, and will be written to by this function

This function computes the actual rate that will be generated by the rate generator when the specified rate, rate, is used in the function dss4rgrate( ). It does not access any of the rate generators, it just returns a theorectical calculation of the actual rate that would be generated. This actual rate is written to the argument rateact.

Return values:
1 Normal return, no errors
other Error computing the actual rate generated by the device.

long dss4rgarm (long rgnumb)
long rgnumb the rate generator to be armed (0 - 7)

This function arms one of the rate generators. If the rate generator is in mode 1 (software start), it is started. So, this function acts as a start command. If the rate generator is in mode 2 or 3 (external start), it is armed to wait for its external trigger input.

Return values:
1 Normal return, no errors
303 Invalid rate generator number
other NI-DAQ error arming the rate generator

long dss4rgdisarm (long rgnumb)
long rgnumb the rate generator to be disarmed (0 - 7)

This function disarms a rate generator. The rate generator is returned to the state it was in before it was armed. Parameters are retained. Use this function to stop the rate generator.

Return values:
1 Normal return, no errors
303 Invalid rate generator number
other NI-DAQ error disarming the rate generator

(back to top)

********************************************************************************

FPGA Rate Generator Functions

	Clock Input for FPGA Rate Generators
	long dss4rginit_fpga ( )
	long dss4rgrate_fpga (long rgnumb, double rate,
			long globalstart, long globalstop, long npulse)
	long dss4rgstart_fpga (long channumb)
	long dss4rgstop_fpga (long channumb)
	long dss4rgglobalstart_fpga (long channumb)
	long dss4rgglobalstop_fpga (long channumb)
	long dss4rgclose_fpga ( )

These functions are used to control the FPGA rate generators. These 8 rate generators use the PIO-D24 board installed in the computer. They are separate from the NI-DAQ rate generators (described above). They can replace any of the NI-DAQ rate generators, EXCEPT that one of the NI-DAQ rate generators MUST be used to supply the external clock rate for the FPGA device. To use any of the FPGA functions, the library piodio.lib must be included in the link input of the Project settings

Clock Input for FPGA Rate Generators

The FPGA rate generators require an external clock input, which is connected to the device front panel. This clock input MUST be a 20 MHz signal. It can come from one of the NI-DAQ rate generators, described above.

long dss4rginit_fpga ( )

This function initializes the FPGA rate generator device. It should be called once before accessing any of the new rate generators.

Return values:
1 Normal return, no errors
240 Error opening and initializing the PIO-D24 device

long dss4rgrate_fpga (long rgnumb, double rate, long globalstart, long globalstop, long npulse)
long rgnumb the rate generator to be setup (0 - 7)
double rate the desired rate (0 to 10000000 Hz)
long globalstart describes the mode of starting the rate gen. 0 means that it is started individually, either with a software start command or a hardware trigger pulse; 1 means that it is started via a global software command or a global hardware trigger pulse
long globalstop describes the mode of stopping the rate gen. 0 means that it is stopped individually, either with a software stop command or a hardware trigger pulse; 1 means that it is stopped via a global software command or a global hardware trigger pulse
long npulse number of pulses of the rate generator to be generated; 0 means lots max is (2**48)/2

This function sets up one of the fpga rate generators. It must be called before starting the rate generator. Note that the globalstart and globalstop arguments define whether or not the start or stop event for that rate generator will be a global one or an individual one. The mode for start can be different than the mode for stop.

There is a single global start and a single global stop hardware input. They will only start or stop a specific rate generator if it is set up to use a global start or stop. The same goes for the global start command and the global stop command.

Each rate generator that is set up in 'individual' start or 'individual' stop mode will be started or stopped by either an individual hardware trigger, or an individual command. There is an individual hardware input for both start and stop, for each rate generator.

See the functions used for software start and stop, described below.

Return values:
1 Normal return, no errors
241 Invalid rate generator number
242 Rate out of range
243 Invalid globalstart mode
244 Invalid globalstop mode
245 Invalid npulse (number of pulses out of range)
other other error setting up the FPGA rate generator

long dss4rgstart_fpga (long channumb)
long channumb channel number of the rate generator to be individually started (0 - 7)

This function is the software start command for an individual rate generator. It starts only the rate generator specified by channumb. Before calling it, the functions dss4rginit_fpga ( ) and dss4rgrate_fpga ( ) must have been called.

Note that, once a rate generator has been set up with dss4rgrate_fpga ( ), it responds to either a software or hardware start signal, whichever comes first. If a hardware start is not desired, is up to the user to see that no hardware signal reaches the hardware start input.

Return values:
1 Normal return, no errors
other Error starting individual rate generator

long dss4rgstop_fpga (long channumb)
long channumb channel number of the rate generator to be individually stopped (0 - 7)

This function is the software stop command for an individual rate generator. It stops only the rate generator specified by channumb. Before calling it, the functions dss4rginit_fpga ( ) and dss4rgrate_fpga ( ) must have been called.

Note that, once a rate generator has been started, it responds to either a software or hardware stop signal, whichever comes first. If a hardware stop is not desired, is up to the user to see that no hardware signal reaches the hardware stop input.

Return values:
1 Normal return, no errors
other Error stopping individual rate generator

long dss4rgglobalstart_fpga ( )

This function is the global software start command for all rate generator which have been programmed to be started globally. (See the globalstart argument of dss4rgrate_fpga ( ).) It is similar to the individual start function, dss4rgstart_fpga ( ), but it is used to start more than one rate generator simultaneously. Before calling it, the functions dss4rginit_fpga ( ) and dss4rgrate_fpga ( ) must have been called, for all rate generators in question.

Note that, once a rate generator has been set up with dss4rgrate_fpga ( ), it responds to either a software or hardware start signal, whichever comes first. If a hardware start is not desired, is up to the user to see that no hardware signal reaches the hardware start input.

Return values:
1 Normal return, no errors
other Error starting rate generators via a global start

long dss4rgglobalstop_fpga ( )

This function is the global software stop command for all rate generator which have been programmed to be stopped globally. (See the globalstop argument of dss4rgrate_fpga ( ).) It is similar to the individual stop function, dss4rgstop_fpga ( ), but it is used to stop more than one rate generator simultaneously. Before calling it, the functions dss4rginit_fpga ( ) and dss4rgrate_fpga ( ) must have been called, for all rate generators in question.

Note that, once a rate generator has been started, it responds to either a software or hardware stop signal, whichever comes first. If a hardware stop is not desired, is up to the user to see that no hardware signal reaches the hardware stop input.

Return values:
1 Normal return, no errors
other Error stopping rate generators via a global stop

long dss4rgclose_fpga ( )

This function closes the FPGA rate generator device. It should be called once when access to the FPGA rate generators is no longer needed. It closes the device driver for the PIO-D24 board.

Return values:
1 Normal return, no errors
other Error closing the PIO-D24 device

(back to top)

*******************************************************************************

Unit Event Timer (UET) Functions

	long dss4uetboot (long devnumb)
	long dss4uetclose (long devnumb)
	long dss4setuetmcodefile (char *filename)
	long dss4uetena (long devnumb,unsigned long chanmask,unsigned long chanmode,
		unsigned long chanedge,long strtmode)
	long dss4uetstopmask (long devnumb,unsigned long stopbitmask)
	long dss4uetinit (long devnumb)
	HANDLE dss4uetrd (long devnumb,unsigned long *inputbuffer, unsigned long nsamples,
		HANDLE eventflag, unsigned long *statusblock)
	long dss4uetrdcancel (long devnumb)

These functions are used to control the Unit Event Timer and collect sample data. The UET is generated on a VC33 dsp board. It has 32 input channels, and stores each data event as 2 longwords -- a 32-bit time (in microseconds), and a 32-bit mask reporting the state (low or high) of each of the 32 channels at that time. It can record inputs on more than one channel at the same time, if they occur. It records an event whenever the state of one of the input channels changes.

Note that the first argument in each function is a device number. This is required because the VC33 board of the UET is one of several such boards in the system. Each of these uses the same device driver and the device number is required as a unique identifier. The device number is determined by where the board is installed in the PCI bus. For the current DSS4 system (Oct 2003), the UET device number is 3. This will remain the same, provided the hardware configuration is the same.


Summary of UET functions:

dss4uetboot( ) open the device, start the processor
dss4uetclose( ) close the device
dss4setuetmcodefile( ) specify a file containing UET microcode program
dss4uetena( ) configure the data collection process -- enable channels and startmode
dss4uetstopmask( ) specify an input channel that will detect a stop event (optional)
dss4uetinit( ) start or restart the timer, reset the buffer and arm data collection process (software start)
dss4uetrd( ) read a specified number of samples from UET buffer (which is a FIFO)
dss4uetrdcancel( ) terminate a previous call to dss4uetrd( ) (saving data up to the termination)

long dss4uetboot (long devnumb)
long devnumb device number of the UET VC33 board (currently 0)

This function creates a HANDLE to the UET device. It also loads the necessary microcode into the processor and starts it. It then waits for the user to set up UET operating parameters and start the actual data storage.

Note that dss4uetboot( ) is meant to be called only once during an experimental run. It can take well over 1 second to complete its boot process. The other UET functions (see dss4uetena( ), dss4uetinit( ), etc.) can be used to control data collection during a run.

To close the UET device and its HANDLE, call dss4uetclose( ).

Return values:
1 Normal return, no errors
103 Error accessing the VC33 UET device.
104 Error loading the UET microcode file (default file is "C:\\Audstuff\\D\\uet.out").
105 Error resetting the UET device.
106 Error booting the UET device.
107 Error starting the UET microcode program.
0 Error initializing and starting the UET processor

long dss4uetclose (long devnumb)
long devnumb device number of the UET VC33 board (currently 0)

This function stops the UET processor, deallocates resources used to transfer data, and closes the HANDLE on the UET device. It should be called only after the UET device is no longer needed. It is generally called by the same user program that callsdss4uetboot( ) to open the UET device.

Return values:
1 Normal return, no errors
0 Error stopping the UET processor and deallocating resources

long dss4setuetmcodefile (char *filename)
char *filename name of file containing the UET microcode program

This function allows the user to specify a file containing a UET microcode program that is different from the default microcode. The default file is "C:\\Audstuff\\D\\uet.out". If this function is not called, the default file is used.

Return values:
1 Normal return, no errors
0 Error specifying the microcode filename.

long dss4uetena (long devnumb,unsigned long chanmask,unsigned long chanmode,unsigned long chanedge,long strtmode)
long devnumb device number of the UET VC33 board (currently 0)
unsigned long chanmask bitmask of all the uet input channels to be enabled
unsigned long chanmode bitmask of the data mode of all the enabled uet input channels (0=edge, 1=level)
unsigned long chanedge for edge detection mode, the bitmask of the edge code for input channels (0=rising, 1=falling)
long strtmode start mode of UET data collection (0=software, 1=external (hardware))

This function enables 1 or more input channels of the Unit Event Timer. There are 32 input channels, and the mask is the inclusive OR of the bitmasks of all channels to be enabled. So, for example, the mask 0xa0000001 would enable channels 0, 29 and 31.

For each enabled input channel, there are 2 possible modes for data collection: 0 means edge detection (event is recorded when an edge occurs), and 1 means level detection (event is recorded when the level changes, for either a rising or falling transitions). So, if channels 0 and 17 are to both be set up for level detection, the chanmode value would be 0x20001. If channel 17 is to be level and channel 0 is to be edge detection, then chanmode is 0x20000.

If edge detection is chosen for any of the channels, the chanedge argument must be set up. Here, 0 means rising edge and 1 means falling edge.

Note that dss4uetena( ) does not start the data collection process -- it loads the UET operating parameters. The function dss4uetinit( ) (see description) must be called before any data collection can take place.

The input channels 31 and 30 are reserved -- they are each used for an external start signal. If either is used, it must be set to edge detection mode (and level mode will cause faulty data collection). When strtmode is set to 1, the device will start data collection when an event is recorded on channel 30 or channel 31. The timer is zeroed when this event occurs, and if more events occur on either channel 30 or 31 the timer will again be zeroed at the time of these events. The events on channels 30 and 31 are stored in the data buffer, except for the very first external start event that occurs after having called dss4uetinit( ).

Note that all input channels, MUST be enabled with dss4uetena( ) -- INCLUDING channels 30 or 31, and also including any channel used as a stop event (see dss4uetstopmask( )).

Before calling dss4uetena( ), the function dss4uetboot( ) must be called.

Return values:
1 Normal return, no errors
17 Error enabling input channels

long dss4uetstopmask (long devnumb,unsigned long stopbitmask)
long devnumb device number of the UET VC33 board (currently 0)
unsigned long stopbitmask bitmask of the uet input channel to be used to detect a stop event

This function specifies the mask of a channel that is to be used to detect an event that will stop the function dss4uetrd( ) from collecting data from the UET. This routine need not be called unless an external stop event is to be used during data collection. If so, it should be called before calling dss4uetinit( ) and dss4uetrd( ). The stop channel must be enabled with dss4uetena( ).

The user program must set up the source of the UET stop signal, and see that it is connected to the channel defined by stopbitmask. The type of edge (rising or falling) that is expected must correspond to the edge detection mode of the stop channel (as specified in dss4uetena( )).

Note that dss4uetstopmask( ) can be called either before or after calling dss4uetena( ).

Return values:
1 Normal return, no errors
0 Error setting up stop channel

long dss4uetinit (long devnumb)
long devnumb device number of the UET VC33 board (currently 0)

This function zeroes the UET timer and starts it. It also clears all UET data buffers and starts the data collection process anew. Before calling dss4uetinit( ), the functions dss4uetboot( ) and dss4uetena( ) must have been called. If the UET is configured for an external stop event, then dss4uetstopmask( ) must have been called also.

If the UET is in software start mode, then dss4uetinit( ) acts as a software start. In external start mode, dss4uetinit( ) arms the device to start collecting data when an external start event takes place.

The function dss4uetinit( ) can also be used to restart the data collection process after a previous set of data has been collected. Before doing this, the dss4uetrd( ) process must be ended (its event flag set), either via an external stop event, the collection of the full count of data samples, or a call to dss4uetrdcancel( ). Whenever dss4uetinit( ) is called, the device uses the configuration information from the most recent call to dss4uetena( ).

Return values:
1 Normal return, no errors
0 Error starting UET data collection

HANDLE dss4uetrd (long devnumb, unsigned long *inputbuffer, unsigned long nsamples, HANDLE eventflag, unsigned long *statusblock)
long devnumb device number of the UET VC33 board (currently 0)
unsigned long inputbuffer pointer to buffer in which the uet data will be stored -- it must be large enough to hold (2 * nsamples) longwords
unsigned long nsamples the maximum number of 2-longword events to be collected
HANDLE eventflag event flag that will be set when the UET data collection has stopped
unsigned long statusblock pointer to a status buffer of 2 unsigned long integers, to be set by the processing thread of dss4uetrd ( ) after it has stopped data collection. The first word will contain the number of uet events actually collected. The second status word contains a completion status code. Possible completion codes are:
2 completion because of an event on the stopbit channel, no errors
4 completion because of a call of the function dss4uetrdcancel ( ), no errors
5 completion because nsamples events have been collected, no errors
9 the number of samples requested may not be negative
10 error transferring data from Hostram to user buffer
65 completion because of a Hostram buffer (FIFO) overflow
66 error pausing data transfers from VC33 to Hostram
67 error in Hostram buffer pointer
0 completion because of an unexpected abortion of the processing thread created by dss4uetrd ( )
other error sending a command or information to VC33 from host

This function starts an independent thread which monitors the data coming into the UET (VC33) device, and transfers it to inputbuffer. It checks for the external stop condition defined by the arguments stopbit and stopmode of the function dss4uetini ( ). It also checks if nsamples have been collected, and if the calling program has executed the dss4uetrdcancel ( ) function. If any of these conditions are met, or if an error occurs, the thread created by dss4uetrd ( ) will finish its data transfer, write the appropriate values into the statusblock array, and set the eventflag. It is eventflag that the calling program must check to see if the uet processing thread has completed.

The function dss4uetrd ( ) itself returns as soon as it has created the processing thread. Its return value is not related to the actual collection of the uet data, but rather to the creation of the uet processing thread.

Return value:
HANDLE the HANDLE of the processing thread created by dss4uetrd ( ). It is the actual return value of the function CreateThread( ). If there was an error creating the thread, this return value will reflect that error. The calling program can perform any functions on this return value that it can on any valid HANDLE.

long dss4uetrdcancel (long devnumb)
long devnumb device number of the UET VC33 board (currently 0)

This function sends a software stop command to the uet processing thread created by dss4uetrd ( ). It waits for the eventflag of the dss4uetrd ( ) function to be set. It also stops data from being transfered from the UET to the host buffer. It retains all of the setup information specified by dss4uetena ( ) and dss4uetstopmask ( ).

Return values:
1 Normal return, no errors
19 Timeout waiting for event flag to be set by uet processing thread
0 other error waiting for event flag to be set by uet processing thread

(back to top)

********************************************************************************

Matrix Selector Funtions

The functions used to control the Matrix Selector of the DSS 4: 
	long dss4initmatrixselector ( )
	long dss4signalconnect (long source, long destination)

These functions are used to control the matrix selector. This device allows the user to establish a connection between 2 different hardware signals via a software command. There are 8 possible 'source' signals which can each be connected to one of 16 possible 'destination' signals, all of which are digital i/o lines. Of these signals, some of them are physically connected to the output or input of certain DSS4 devices within the device circuitry, and others are available to the user as BNC connections on the front panel of the device. So, the user could plug in any outside signal to one of the BNC connections and then tell the matrix to map that particular source or destination to another signal. And, some of the internal connections to the signals are also routed to BNC connectors on the front panel, so that the experimenter can have access to these signals. 

The 8 possible source signals are :

	1	BNC 1  (on front panel, one of the "TRIGGERS")
	2	BNC 2  (on front panel, one of the "TRIGGERS")
	3	BNC 3  (on front panel, one of the "TRIGGERS")
	4	BNC 4  (on front panel, one of the "TRIGGERS")
	5	The output of Duration Timer 4 (internally connected)
	6	The output of Duration Timer 3		"
	7	The output of Duration Timer 2		"
	8	The output of Duration Timer 1		"


The 16 possible destination signals are :

	1	The gate for Duration Timer 1 (internally connected)
	2	The gate for Duration Timer 2		"
	3	The gate for Duration Timer 3		"
	4	The gate for Duration Timer 4		"
	5	The gate for Rate Generator 3		"
	6	The gate for Rate Generator 4		"
	7	The gate for Rate Generator 5		"
	8	The gate for Rate Generator 6		"
	9	The gate for Rate Generator 7		"
	10	BNC labeled "UET" (on front panel, one of "EXPANSION FROM MATRIX")
	11	BNC labeled   1   (on front panel, one of "EXPANSION FROM MATRIX")
	12	BNC labeled   2   (on front panel, one of "EXPANSION FROM MATRIX")
	13	BNC labeled   3   (on front panel, one of "EXPANSION FROM MATRIX")
	14	BNC labeled   4   (on front panel, one of "EXPANSION FROM MATRIX")
	15	BNC labeled   5   (on front panel, one of "EXPANSION FROM MATRIX")
	16	BNC labeled   6   (on front panel, one of "EXPANSION FROM MATRIX")

For example, to connect the output of Duration Timer 1 to the gate signal for Rate Generator 5, one would program the matrix to connect source 8 with destination 7. (The gate signals for the Duration timers are used to trigger them.)

long dss4initmatrixselector ( )

This function sets up control lines for the matrix selector. It sets up specific output lines on both NI-DAQ 6602 devices, which are used to communicate with the matrix. It also resets all data lines of the matrix.

Return values:
1 Normal return, no errors
other Error initializing matrix selector.

long dss4signalconnect (long source, long destination)

This function establishes a hardware connection between source and destination. The definition of the possible values for source and destination are listed above.

long source digital signal (1 - 8) that is to be connected to destination
long destination digital i/o line (1 - 16), that is to be connected to source

Return values:
1 Normal return, no errors
10 Source channel out of range (must be between 1 and 8)
11 Destination channel out of range (must be between 1 and 16)
other Error setting a connection within the matrix selector.

(back to top)

********************************************************************************

If you have questions or comments about this documentation, please send email to jane@physiology.wisc.edu

This page last modified on : Oct 30, 2003