DSSLIB
Stimulus Generation and Data Acquisition Routines
Technical Report no. 10 Ravi Kochhar & Jane Sekulski
September 1988 Department of Physiology
Rev. 1.04, June 8 1999 University of Wisconsin
Madison, Wi. 53706
1 INTRODUCTION
Routines to program the Digital Stimulus System (DSS) are now
available for both the VAX/VMS system and the PDP-11/RSX system.
A preliminary description of these routines was provided in an
earlier report (no. 19). This report includes all the routines
described earlier, as well as many new ones.
The DSS routines are available in the library DSSLIB. Note
that DSSLIB also contains routines other than those described
below. The routines not listed here deal with hardware devices
other than the DSS, such as the Unit Event Timer (UET) and the A/D
converter. Those will be described in a separate report.
2 USAGE
The routines in library DSSLIB may be linked to user programs
as follows :
VMS
LINK program,........,L:DSSLIB/L
RSX
TKB program/FP=program,.....,DL1:[202,10]DSSLIB/LB
/
COMMON=DVCOM:RW
//
The library DSSLIB resides in directory L: on the VAX and in
directory DL1:[202,10] on the PDP-11.
In all the routines described below, an error code value NER
is returned. The value of NER indicates whether the routine
completed successfully or whether an error condition was detected.
In all cases, a value of NER=0 indicates successful completion.
If NER is non-zero, it can indicate a variety of problems. A
description of all possible values of NER, and their
interpretation, is attached at the end of this report.
All integer arguments must be declared type INTEGER. On the
VAX this will mean 4-byte integers, while on the PDP-11 this will
mean 2-byte integers. In a few cases the integer arguments must
be explicitly declared as INTEGER*2 or as INTEGER*4. These cases
are mentioned with each routine where applicable.
For reference, a diagram explaining the timers is attached at
the end of this report (reproduced from Ref. no. 1). Examples
of use are provided in a separate section below.
3 DESCRIPTION
3.1 DSS Routines
(1) SUBROUTINE SSCLR(N,NER)
Clear (initialize) the DSS.
N : DSS number (1 or 2)
NER : Error code
N must be supplied by the calling program.
Calling this routine is similar to turning the DSS power
ON for the first time. All registers are set to their default
values. It is recommended that this routine be called first
before any others are called.
(2) SUBROUTINE SSFREQ(N,FREQ,NER)
Set the (carrier) frequency
N : DSS number (1 or 2)
FREQ : Frequency (real value in the range 0. to 65535 Hz)
NER : Error code
N and FREQ must be supplied by the calling program.
The frequency may also include a fractional component.
(3) SUBROUTINE SSINTT(N,MODEX,MODED1,MODED2,MSLAVE,NER)
Initialize the timers.
N : DSS number (1 or 2)
MODEX : If=1 then program start mode,
If=2 then external start
MODED1 : If=1 then Delay-1 will be zero,
If=2 then Delay-1 will be non-zero
MODED2 : If=1 then Delay-2 will be zero,
If=2 then Delay-2 will be non-zero
MSLAVE : If=1 then DSS number N is the master DSS,
If=2 then DSS number N is the slave DSS
NER : Error code
N,MODEX,MODED1,MODED2 and MSLAVE must be supplied, while NER
is returned by this routine.
This routine must be called at least once before any of the
other timer routines are called.
Note that if MSLAVE=2 then MODEX must also be 2.
(4) SUBROUTINE SSDD1(N,DEL1,DUR1,NER)
Set the delay-1 and duration-1 timers
N : DSS number (1 or 2)
DEL1 : Delay-1 time (seconds)
DUR1 : Duration-1 time (seconds)
NER : Error code
N,DEL1 and DUR1 must be supplied by the calling program, while
NER will be returned by this routine.
(5) SUBROUTINE SSDD2(N,DEL2,DUR2,NER)
Set the delay-2 and duration-2 timers
N : DSS number (1 or 2)
DEL2 : Delay-2 time (seconds)
DUR2 : Duration-2 time (seconds)
NER : Error code
N,DEL2 and DUR2 must be supplied by the calling program, while
NER will be returned by this routine.
Do not confuse Duration-2 with the Duration of DSS-2.
See the figure attached at the end of this report.
(6) SUBROUTINE SSREPI(N,RTIME,NER)
Set the Repetition Time
N : DSS number (1 or 2)
RTIME : Repetition time (seconds)
NER : Error code
N and RTIME must be supplied by the calling program, while
NER will be returned by this routine.
(7) SUBROUTINE SSMDEL(N,TIME,NER)
Set the Master Delay Time
N : DSS number (1 or 2)
TIME : Master delay (seconds)
NER : Error code
N and TIME must be supplied by the calling program, while
NER will be returned by this routine.
The value of Master Delay must be greater than zero.
(8) SUBROUTINE SSPRES(N,NREP,NER)
Set the Preset Count (Number of Repetitions)
N : DSS number (1 or 2)
NREP : Number of repetitions
NER : Error code
N and NREP must be supplied by the calling program, while
NER will be returned by this routine.
(9) SUBROUTINE SSATN(N,NDB,NER)
Set the attenuator
N : DSS number (1 or 2)
NDB : Attenuator setting in dB (0-127)
NER : Error code
N and NDB must be supplied by the calling program, while
NER will be returned by this routine.
(10) SUBROUTINE SSRISE(N,RTIME,NER)
Set the stimulus Rise Time
N : DSS number (1 or 2)
RTIME : Rise time (seconds)
NER : Error code
N and RTIME must be supplied by the calling program, while
NER will be returned by this routine.
The Rise Time value must be greater than zero, however it need
not be equal to the Fall Time.
(11) SUBROUTINE SSFALL(N,FTIME,NER)
Set the stimulus Fall Time
N : DSS number (1 or 2)
FTIME : Fall time (seconds)
NER : Error code
N and FTIME must be supplied by the calling program, while
NER will be returned by this routine.
The Fall Time value must be greater than zero, however it need
not be equal to the Rise Time.
(12) SUBROUTINE SSMODE(N,MODE,NER)
Set the output mode for DSS
N : DSS number (1 or 2)
MODE : Mode Value (1,2,3....etc)
NER : Error code
N and MODE must be supplied by the calling program, while
NER will be returned by this routine.
The value of MODE determines the DSS output :
MODE = 1 : Triangle modulated FM (default mode)
= 2 : Sine modulated FM
= 3 : Linear modulated FM
= 4 : Amplitude modulation
= 5 : GEWAB - Single Cycle Mode
= 6 : GEWAB - Repetitive mode
When power is first turned on, or SSCLR is called, the output
mode defaults to 1. It is strongly recommended that you
explicitly call SSMODE at least once no matter which mode you
are selecting.
(13) SUBROUTINE SSSTAT(N,ICSR,IERR,NER)
Fetch the Status Word and Error Register for the DSS
N : DSS number (1 or 2)
ICSR : Status word (CSR contents)
IERR : Error register contents
NER : Error code
N must be supplied by the calling program, while ICSR, IERR and
NER will be returned by this routine.
The Status Word is the contents of the CSR of the interface,
with 16 significant bits, and IERR is the internal error register
of the DSS, presently with only 4 significant bits.
If NER=2 then it means the DSS was busy, and IERR could not be
obtained. ICSR is still valid.
(14) SUBROUTINE SSPHAS(N,PHASE,NER)
Specify initial phase for carrier frequency
N : DSS number (1 or 2)
PHASE : Initial Phase of carrier frequency (0 to 1)
NER : Error code
N and PHASE must be supplied by the calling program, while
NER will be returned by this routine.
PHASE is expressed as a fraction between 0.0 and 1.0
(15) SUBROUTINE SSSTRT(N,NER)
Start the DSS timers
N : DSS number (1 or 2)
NER : Error code
N must be supplied by the calling program, while NER will
be returned by this routine.
(16) SUBROUTINE SSSTOP(N,NER)
Stop the DSS timers
N : DSS number (1 or 2)
NER : Error code
N must be supplied by the calling program, while NER will
be returned by this routine.
Note the difference between SSSTOP and SSCLR.
(17) SUBROUTINE SSEXT(N,NCHAN,NER)
Select an external start input for the master delay timer
(i.e. for all the timers)
N : DSS number (1 or 2)
NCHAN : External start input channel (1 to 7)
NER : Error code
N and NCHAN must be supplied by the calling program, while
NER will be returned by this routine.
Before calling this routine, you must have called SSINTT and
selected external start mode. Do not call SSINTT after calling
SSEXT unless you wish to disable the external start mode.
If you want one DSS to trigger the other, then use NCHAN=1.
SSEXT should always be the last routine called, just before
starting the DSS.
(18) SUBROUTINE SSTFM(N,FLO,FHI,SWTIME,PHASM,NER)
Specify parameters for "Triangle Modulated FM"
N : DSS number (1 or 2)
FLO : Low frequency (Hz)
FHI : High frequency (Hz)
SWTIME : Time for one side of sweep (seconds)
PHASM : Initial Phase of modulating waveform (0 to 1)
NER : Error code
N,FLO,FHI,SWTIME and PHASM must be supplied by the calling
program, while NER will be returned by this routine.
The swept frequency goes low-to-high and then back to low.
SWTIME is the time for one side only.
(19) SUBROUTINE SSSFM(N,FLO,FHI,SWTIME,PHASM,NER)
Specify parameters for "Sine Modulated FM"
N : DSS number (1 or 2)
FLO : Low frequency (Hz)
FHI : High frequency (Hz)
SWTIME : Time for one side of sweep (seconds)
PHASM : Initial phase of modulating sine (0 to 1)
NER : Error code
N,FLO,FHI,SWTIME and PHASM must be supplied by the calling
program, while NER is returned by this routine.
The FM sweep low-to-high as well as high-to-low, SWTIME is
the time for one side only.
(20) SUBROUTINE SSLFM(N,FLO,FHI,TLOHI,THOLD,THILO,NER)
Specify the parameters for "Linear Modulated FM"
N : DSS number (1 or 2)
FLO : Low frequency (Hz)
FHI : High frequency (Hz)
TLOHI : Time for low-to-high frequency transition (seconds)
THOLD : Holding time at low or high frequency (seconds)
THILO : Time for high-to-low frequency transition (seconds)
NER : Error code
N,FLO,FHI,TLOHI,THOLD and THILO must be supplied by the
calling program, while NER will be returned by this routine.
(21) SUBROUTINE SSAM(N,FREQM,PHASM,VALM,NER)
Specify parameters for Amplitude Modulation
N : DSS number (1 or 2)
FREQM : Modulation Frequency (Hz)
PHASM : Modulation Phase (0 to 1)
VALM : Modulation Value (-1 < VALM > 1)
NER : Error code
N,FREQM,PHASM and VALM must be supplied by the calling
program, while NER will be returned by this routine.
In the typical case you must also call SSFREQ and SSPHAS
to set the carrier frequency and phase respectively.
(22) SUBROUTINE SSGWBL(N,NBUF,NADR,NW,NER)
Write into the General Waveform Buffer (GEWAB) memory
N : DSS number (1 or 2)
NBUF : Integer*2 array containing values to be loaded
NADR : GEWAB memory starting address (Integer*4)
NW : Number of values to write (Integer*2)
NER : Error code
N,NBUF,NADR and NW must be supplied by the calling program,
while NER will be returned by this routine.
Note that NBUF and NW must be declared as INTEGER*2
variables and NADR must be INTEGER*4. The maximum number
of values which can be written at one time is 32768.
(23) SUBROUTINE SSGWBR(N,NBUF,NADR,NW,NER)
Read the General Waveform Buffer (GEWAB) memory
N : DSS number (1 or 2)
NBUF : Integer*2 array to hold values read in
NADR : GEWAB memory starting address (Integer*4)
NW : Number of values to read (Integer*2)
NER : Error code
N,NADR and NW must be supplied by the calling program,
while NBUF and NER will be returned by this routine.
Note that NBUF and NW must be declared as INTEGER*2
variables and NADR must be INTEGER*4. The maximum number
of values which can be read at one time is 32768.
(24) SUBROUTINE SSGWA(N,NSA4,NFA4,INC4,RES,NER)
Set the starting address, final address and playback
resolution for the GEWAB
N : DSS number (1 or 2)
NSA4 : GEWAB starting address (Integer*4)
NFA4 : GEWAB final address (Integer*4)
INC4 : Increment address (Integer*4)
RES : Playback resolution (microsecs)
NER : Error code
N,NSA4,NFA4,INC4 and RES must be supplied by the calling
program, while NER will be returned by this routine.
The playback resolution (RES) is defined as the interval
between successive GEWAB points (in microsecs). The
minimum value allowed for RES is 1.91 microsecs.
At this time (March 1986) INC4 is not being used and
should be specified as zero.
(25) SUBROUTINE SSCSPL(N,NBUF,NADR,NW,NER)
Load the "Constant SPL" memory
N : DSS number (1 or 2)
NBUF : Array containing values to be loaded (Integer*2)
NADR : Starting address (Integer*2)
NW : No. of values to load (Integer*2) (4096 max)
NER : Error code
N,NBUF,NADR and NW must be supplied by the calling program,
while NER is returned by this routine.
The CSPL memory is loaded with 16-bit words, and NBUF must
be declared INTEGER*2 along with NADR and NW.
(26) SUBROUTINE SSCSPR(N,NBUF,NADR,NW,NER)
Read the "Constant SPL" memory
N : DSS number (1 or 2)
NBUF : Array to hold values read in (Integer*2)
NADR : Starting address (Integer*2)
NW : No. of words to read in (Integer*2) (4096 max)
NER : Error code
N,NADR and NW must be supplied by the calling program,
while NBUF and NER will be returned by this routine.
Note that NBUF,NADR and NW must all be declared INTEGER*2.
3.2 A/D Routines
Comning Soon
3.3 UET Routines
Comning Soon
4 EXAMPLES OF USE
The following are examples of FORTRAN programs used to
generate typical stimuli from the DSS. In these examples the
checking for error codes (NER) has been omitted for brevity. In a
real case, you should always check the value of NER after every
call to a DSSLIB routine.
(1) Single Tone Experiment
In this example, a series of 25 tone pips will be produced
from DSS number 1. The tone frequency will be 1000 Hz, the
repetition time 1.5 secs and the duration time .75 sec. The
master delay will be set to 1.0 sec.
:
CALL SSCLR(1,NER)
CALL SSINTT(1,1,1,1,1,NER)
CALL SSREPI(1,1.5,NER)
CALL SSDD1(1,0.0,.75,NER)
CALL SSPRES(1,25,NER)
CALL SSFREQ(1,1000.,NER)
CALL SSMDEL(1,1.0,NER)
CALL SSMODE(1,1,NER)
CALL SSATN(1,0,NER)
C START THE STIMULUS
CALL SSSTRT(1,NER)
:
Note that in the above case, values for parameters not
specified such as Rise/Fall time, Initial Phase etc. will be set
to default values.
(2) Two-tone Experiment with Delay
In this example, both channels of the DSS will produce 10
tone pips each. The second DSS will be delayed with respect to
the first DSS by 1200 microsecs. Note that here we use program
start mode for DSS-1 and external start mode for DSS-2. DSS-2 is
also set in slave mode.
:
CALL SSCLR(1,NER)
CALL SSCLR(2,NER)
CALL SSINTT(1,1,1,1,1,NER)
CALL SSINTT(2,2,1,1,2,NER)
CALL SSDD1(1,0.0,.25,NER)
CALL SSDD1(2,0.0,.25,NER)
CALL SSREPI(1,.5,NER)
CALL SSREPI(2,.5,NER)
CALL SSMDEL(1,0.01,NER)
CALL SSMDEL(2,0.0012,NER)
CALL SSPRES(1,10,NER)
CALL SSPRES(2,10,NER)
CALL SSMODE(1,1,NER)
CALL SSMODE(2,1,NER)
CALL SSATN(1,0,NER)
CALL SSATN(2,0,NER)
CALL SSEXT(2,1,NER)
C START THE STIMULUS
CALL SSSTRT(1,NER)
:
Since we wanted one DSS to start the other, we specified the
external start channel number (with SSEXT) as 1.
(3) Sine Modulated FM
In this example, DSS-1 will produce an FM stimulus varying
between 1200 Hz. and 2900 Hz. The time for one side of the sweep
will be 2.3 secs. The total duration of the stimulus will be 50
secs. The attenuator will be set to 10 dB attenuation.
:
CALL SSCLR(1,NER)
CALL SSINTT(1,1,1,1,1,NER)
CALL SSREPI(1,51.0,NER)
CALL SSDD1(1,0.0,50.0,NER)
CALL SSPRES(1,1,NER)
CALL SSSFM(1,1200.,2900.,2.3,0.0,NER)
CALL SSATN(1,10,NER)
CALL SSMODE(1,2,NER)
C START THE STIMULUS
CALL SSSTRT(1,NER)
:
Note that the mode is set to 2 in this case via the call to
SSMODE.
5 REFERENCES
(1) "Digital Stimulus System - Version II", R.E.Olson, D.Yee
and W.S.Rhode, University of Wisconsin, June 1985.
Error Codes
Code Interpretation
0 No error
1 STATUS-A is always zero
2 STATUS-B is always zero (i.e. DSS is busy)
3 Some parameter is out of range
4 Unable to assign DMA channel
5 Timers must be initialized first with SSINTT
6 RGRATE must be called before RGSTRT
7 Slave DSS must be in external start mode
8 At least one DSS must be the Master, and the Master
DSS must be initialized first with SSINTT
9 If SSEXT is called then must have specified
external start mode first with SSINTT
10 Must call SSINTT for Master DSS first
11 Master delay is too large
12 DMA channel is already assigned
13 DMA I/O error
If you have questions or suggestions about this document,
please send e-mail to
kochhar@physiology.wisc.edu
Return to Computing Page
Return to Basement Page