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
This page last modified on : June 8, 1999