================================================================================
Note 44.0                 VAX/VMS Realtime Programming                No replies
FURILO::PROPPER                                    1235 lines  13-AUG-1986 15:08
--------------------------------------------------------------------------------
      +---------------+                                    +-----------------+
      | d i g i t a l |                                    |  uNOTE # 044    |
      +---------------+                                    +-----------------+

                                                                   
      +----------------------------------------------------+-----------------+
      | Title:    VAX/VMS REALTIME PROGRAMMING             | Date: 10-Jun-86 |
      +----------------------------------------------------+-----------------+
      | Originator:   Bill Forbes                          | Page 1 of 21    |
      +----------------------------------------------------+-----------------+


      The realtime programmer who faces a VAX/VMS system for  the  first  time
      may  feel  intimidated  by  the  seeming  complexity  of  the  system in
      comparison to, say, PDP-11 systems  running  RT-11  SJ.   In  fact,  the
      program  development  environment under VAX/VMS is very rich, comprising
      many tools, utilities and system services  for  developing  and  running
      realtime application programs.

      The material contained in this application note is intended to help  you
      get  started using some basic VAX/VMS services for realtime programming.
      A more informal title might have been "How to Do  Programmed  I/O  under
      VAX/VMS  without  Writing a Device Driver." Specifically, information is
      presented on two relevant techniques:  accessing the VAX  I/O  page  for
      direct  device  control, and using the connect-to-interrupt driver to do
      interrupt programming.  An emphasis has been placed  on  explaining  the
      principles  underlying the use of these services rather than the details
      of their operation.   A  more  detailed  description  may  be  found  in
      Appendix C of the VAX/VMS Release notes for Version 4.0.  For additional
      copies of these notes or for technical assistance, call  the  Laboratory
      Data Products Hotline at (617) 467-5441.


         1  DIRECT PROGRAM CONTROL OF I/O MODULES UNDER MICROVMS

      The most basic level at which realtime devices can be controlled  is  by
      direct manipulation of the contents of device registers.  Direct control
      of device registers is relatively simple in PDP-11 systems and, in fact,
      is  a  common  programming  technique  for  certain  kinds  of  realtime
      applications.   For  example,  the  following  MACRO-11  code   fragment
      illustrates the acquisition of a single data value from an A/D device.

                 ADCSR   = 770400        ;Address of device CSR
                 ADBUF   = ADCSR+2       ;Address of device buffer

                 MTPS    #340            ;Set processor priority level to 7
                 MOV     #1,ADCSR        ;Set the GO bit to start a conversion
         LOOP:   BIT     #200,ADCSR      ;Test the A/D DONE bit
                 BEQ     LOOP            ;If clear, test again
                 MOV     ADBUF,R0        ;If set, move the data to R0
                 MTPS    #0              ;Drop priority level back to 0


                                  413

uNOTE # 044
Page 2 of 21


      In this example, the processor priority level  is  first  raised  to  7.
      This insures that the processor will execute the subsequent instructions
      without interruption.  An A/D conversion is then  initiated  by  setting
      bit  0 of the device control/status register (CSR).  When the conversion
      is complete, bit 7 of the  CSR  is  set  by  the  device.   The  program
      repeatedly  tests  this  bit until it finds it to be set, then moves the
      data value from the device's  buffer  register  into  a  general-purpose
      processor  register  (or  into a storage location in main memory).  This
      technique is called "polled I/O".

      Since many polled I/O operations require that the processor  be  totally
      dedicated  to  the polling loop, this technique has not been widely used
      on VAX/VMS systems, which typically support multiple tasks or users at a
      time.   However,  the  increasing  use of MicroVAX systems for dedicated
      realtime processing has brought about a demand for polled  I/O  routines
      implemented under MicroVMS.

      As with RT-11 based PDP-11  systems,  improper  manipulation  of  device
      registers in the MicroVAX I/O page can lead to undesirable consequences.
      Generally speaking, direct device control techniques should be  used  to
      manipulate  only  process-dedicated  realtime  option  module registers.
      Inadvertently changing other device register contents may cause a system
      crash or the corruption of a mass storage volume.  You should be sure to
      have a secure backup copy of the system whenever debugging direct device
      control routines.

      To develop polled I/O (or other direct control routines) under MicroVMS,
      two special techniques are called for:


         1.  A means of addressing device registers in the I/O page, and

         2.  A means of raising and lowering the processor priority level.

      This  section  illustrates  the  techniques  used  to  accomplish  these
      operations  in  the  context  of  programs for performing single-channel
      clocked analog input using an AXV11-C analog module and a KWV11-C  clock
      module.


         1.1  Accessing Device Registers In The VAX I/O Page

      On PDP-11  systems  running  the  RT-11  Single-Job  monitor,  accessing
      addresses  in the I/O page involves nothing more than supplying a 16-bit
      address  in  the  range  160000  -  177776  (octal).   Those   addresses
      correspond  to  the  portion  of the physical address space within which
      device registers are defined - the I/O page.  As  with  PDP-11  systems,
      the VAX architecture reserves a region of the physical address space for
      device registers.  For MicroVAXes (I and II)  the  I/O  page  starts  at
      address 20000000 (hex), and is 2000 (hex) bytes in length.



                                  414

                                                           uNOTE # 044
                                                          Page 3 of 21


      Under MicroVMS, the 32-bit virtual address space of the system is mapped
      into physical memory, so that a user-supplied address does not


      ordinarily correspond to any particular physical address.  The  problem,
      then,  is  to  establish  a  means  of  addressing a particular range of
      physical addresses - that is, the MicroVAX I/O page.

      This is accomplished by mapping the physical addresses which  constitute
      the I/O page into a portion of the process's virtual address space.  The
      VMS $CRMPSC system service is used.  The following parameters are passed
      to the $CRMPSC service:


         o  The starting and ending virtual addresses into which  the  section
            is  to  be  mapped;  this virtual address block should be 8K bytes
            long and page-aligned

         o  The starting page frame number of the section to be mapped (a page
            frame  is  a  512-byte block of physical memory); computed as <I/O
            page starting physical address>/512

         o  The number of pages in the section (16 in this case)


      In addition, the $CRMPSC system service accepts a flag  mask  specifying
      the  type  of section to be created, as well as its characteristics.  In
      the present context, the essential flags are SEC$M_PFNMAP and SEC$M_WRT,
      which  define  the  section  as a page frame section with the read/write
      attribute.

      Finally, the call to the $CRMPSC system  service  must  specify  storage
      locations  into  which  the  starting  and ending virtual pages actually
      mapped and the channel number assigned by the system to the section  may
      be  written.   Ordinarily, these data are not used by the programmer and
      need not be elaborated on here.  For a fuller discussion of the  $CRMPSC
      system service, see the VAX/VMS System Services Reference Manual.

      Once the mapped section has been  created,  instructions  which  address
      locations  within  the  virtual address space into which the section has
      been mapped will effectively address the corresponding locations in  the
      I/O  page.  To address a particular device register in the I/O page, the
      absolute offset in the I/O page of the register is  added  to  the  base
      address  of  the virtual address block, yielding a virtual address which
      corresponds to the desired physical address.








                                  415

uNOTE # 044
Page 4 of 21


         1.2  Raising And Lowering Processor Priority Level

      VAX architecture defines 32 interrupt priority levels (IPL 0 - IPL  31).
      At  any  point  in  time,  the  processor will be operating at some IPL,
      usually 0 during execution of user code.  Device interrupts occur at IPL
      20  -  23,  corresponding  to  bus request levels 4 - 7.  On MicroVAXes,
      driver code executes at IPL 23, regardless of the  level  at  which  the
      device  interrupted.   For example, a device interrupt on BR 4 would not
      be granted until the processor priority dropped below 20.  However, when
      the request was granted, the processor priority would be

      set to IPL 23, thus blocking ALL  device  interrupts  until  the  driver
      lowered  the  IPL.  The system timer interrupts at IPL 22 and is granted
      at the same level.

      When the processor is executing code at a low  IPL,  device,  timer,  or
      software  interrupts at a higher IPL can pre-empt the system.  When this
      happens, the processor saves the  context  of  the  currently  executing
      image (program counter, processor status longword) and transfers control
      to the interrupt service routine (ISR).   When  the  ISR  completes  the
      context  of  the pre-empted image is restored and it continues executing
      where it left off (assuming there are no new interrupts pending).  Thus,
      an  image executing at a low IPL may be suspended for various periods of
      time due to the occurrence of interrupts.

      When performing polled I/O it may be  desirable  for  the  processor  to
      respond  as  quickly  as  possible  to the availability of data from the
      device  being  polled.   To  prevent  interrupts  from  distracting  the
      processor  from the polling operation, the polling code must be executed
      at an IPL above that of any device which might  generate  a  pre-emptive
      interrupt.   To accomplish this, the code raises the IPL to 30 using the
      DSBINT system macro.  The value of 30 is chosen to enable  a  power-fail
      interrupt (IPL 31) to be processed, should one occur.  This is advisable
      since allowing the power-fail ISR to execute may prevent  corruption  of
      the  system  device.  Besides, blocking the power-fail ISR will probably
      not salvage the application.

      VAX processor design imposes the restriction that IPL cannot  be  raised
      except  while  the  processor  is operating in kernel mode.  The $CHMKNL
      system service must be invoked to change mode to kernel before executing
      the  DSBINT  macro.   The  polling  code  then  executes in kernel mode.
      Whenever the processor is executing above IPL 2, page faults  are  fatal
      (the system will crash).  Thus, before entering kernel mode, the $LCKPAG
      system service must be called to lock any data areas that are  addressed
      in  the  polling routine into physical memory.  When the polling routine
      completes, the program should restore  the  original  IPL  (usually  0),
      return  to user mode, and, optionally, unlock the pages addressed in the
      polling routine.





                                  416

                                                           uNOTE # 044
                                                          Page 5 of 21


      In summary, the sequence of program steps in performing  polled  I/O  at
      elevated IPL is as follows:

         1.  The I/O page is mapped into process virtual address space using
             the $CRMPSC system service.

         2.  Any required device initialization is performed at IPL 0, user
             mode.

         3.  Any pages addressed in the polling routine are locked into
             physical memory using the $LCKPAG system service.

         4.  The processor mode is changed to kernel using the $CHMKNL system
             service.

         5.  In kernel mode, the IPL is raised to 30.

         6.  The polling code executes and data is moved into a process buffer
             which has been locked into memory (step 3, above).

         7.  When data transfer is complete the IPL is returned to its prior
             value (usually 0).

         8.  The processor mode is changed back to user by exiting the kernel
             mode routine.

         9.  The device is reset, if necessary.

        10.  Optionally, the pages addressed in kernel mode are unlocked using
             the $ULKPAG system service.

        11.  Post-processing of the acquired data is performed in user mode 
             at IPL 0.


         The following FORTRAN and MACRO-32 modules  illustrate  this  sequence
         for  single-channel  clocked  analog  input  using AXV11-C and KWV11-C
         modules.

         To execute:
                 $ FORTRAN POLLED_AD
                 $ MACRO FASTAD32
                 $ LINK POLLED_AD,FASTAD32
                 $ SET PROCESS/PRIV=(CMKRNL,PSWAPM,PFNMAP) !Required privileges
                 $ RUN POLLED_AD








                                  417

uNOTE # 044
Page 6 of 21





                 PROGRAM POLLED_AD

                 INCLUDE '($SYSSRVNAM)'

                 INTEGER*2 IOFF, IVAL, IBUF(60000)
                 INTEGER*4 ISTATUS, MAPIOP, NPNTS, LOCKS(2)

         o  Use the $LCKPAG system service to lock the input buffer into 
         o  physical memory.

                 LOCKS(1)=%LOC(IBUF(1))
                 LOCKS(2)=%LOC(IBUF(60000))
                 ISTATUS=SYS$LCKPAG(LOCKS,,)
                 IF(.NOT.ISTATUS) CALL EXIT(ISTATUS)

         o  Call routine MAPIOP to map the I/O page in virtual address space.

                 ISTATUS=MAPIOP()
                 IF(.NOT.ISTATUS) CALL EXIT(ISTATUS)

         o  Input/initialize data acquisition parameters

                 TYPE 9060
         9060    FORMAT('$Base clock rate, clock preset, number of samples?')
                 ACCEPT *, IRATE, KOUNT, NPNTS
                 ICHAN = 0
                 MODE  = 0

         o  Call the sampling routine. Control will return to the main program 
         o  only after I/O is complete. 

                 CALL FASTAD32(ICHAN,KOUNT,IRATE,IBUF,NPNTS,MODE,ISTATUS)

         o  Output data, return status (residual AXV CSR)

                 TYPE 9130, (J, IBUF(J),J=1,NPNTS)
         9130    FORMAT(1X,2I10)
                 TYPE 9140,ISTATUS
         9140    FORMAT(/' ISTATUS =',O10)

                 END









                                  418

                                                           uNOTE # 044
                                                          Page 7 of 21





              .TITLE FASTAD32

              .LIBRARY /SYS$LIBRARY:LIB.MLB/

              .PSECT  MAPIOP_MAIN     RD,WRT,PAGE

      ; NOTE: all subsequent MACRO-32 code in this example is contained in this
      ;       .PSECT.


      VIOP:           .BLKB   8192            ; The virtual pages to which 
      VIOP_END:                               ;  the I/O page will be mapped

      PIOPAGE:        .LONG   VIOP            ; Starting and ending virtual page
                      .LONG   VIOP_END        ;  addresses
      RETPAGE:        .BLKL   2               ; Starting and ending page addrs
                                              ;  used (should be the same)
      SECNAME:        .ASCID  /IOPAG_GLSEC/   ; Name of the section to be 
                                              ;  created
      IOPAGECHAN:     .LONG                   ; Channel # to be associated with 
                                              ;  the created section
      PFNUM:          .LONG   ^X100000        ; Page frame number of the I/O 
                                              ;  page (20000000 hex) /(200 hex)

      ;++
      ; Routine to map the I/O page into process virtual address space
      ;--

              .ENTRY  MAPIOP,^M<>

              $CRMPSC_S-
                      INADR=PIOPAGE,-
                      RETADR=RETPAGE,-
                      FLAGS=#SEC$M_PFNMAP+SEC$M_WRT,-
                      GSDNAM=SECNAME,-
                      CHAN=IOPAGECHAN,-
                      PAGCNT=#16.,-
                      VBN=PFNUM
                RET
        ;++
        ;       FASTAD32 - Performs single channel, polled I/O using AXV11-C 
        ;                  and KWV11-C modules.
        ;
        ;       The FORTRAN calling interface is:
        ;
        ;       CALL FASTAD32(ichan,kount,irate,ibuf,npnts,mode,istatus)




                                  419

uNOTE # 044
Page 8 of 21


        ;
        ;       where:
        ;               ichan   =       AXV11-C A/D channel number
        ;               kount   =       KWV11-C preset value
        ;               irate   =       clock rate:
        ;                                       1 = 1 MHz
        ;                                       2 = 100 KHz
        ;                                       3 = 10 KHz
        ;                                       4 = 1 KHz
        ;                                       5 = 100 Hz
        ;               ibuf    =       array to store data
        ;               npnts   =       number of elements in ibuf
        ;               mode    =       if 0 then start immediately; 
        ;                               if<>0 then start on ST2
        ;               istatus =       return status; if<0 then error
        ;
        ; This routine should be in the same .PSECT as the MAPIOP routine.
        ;
        ; The CLK OVFL pin on the KWV is strapped to the RTC IN pin on the AXV.
        ;
        ;--

                ADCSR   = VIOP+^O10400  ;address of AXV11-C A/D CSR
                ADBUF   = ADCSR+2       ;address of AXV11-C A/D BUFFER
                KWCSR   = VIOP+^O10420  ;address of KWV11-C CSR
                KWPRE   = KWCSR+2       ;address of KWV11-C BUFFER/PRESET

                ; Argument pointer offsets

                ICHAN   =  4
                KOUNT   =  8
                IRATE   = 12
                IBUF    = 16
                NPNTS   = 20
                MODE    = 24
                ISTATUS = 28


                .ENTRY  FASTAD32,^M<R6,R7,R8,R9,R10>

        ; Note that all instructions which address the I/O page are WORD MODE.

                TSTW    @#ADBUF         ;clear A/D DONE flag
                MOVZWL  @ICHAN(AP),R6   ;channel # to sample
                ASHL    #8,R6,R6        ;move channel # to byte 2 of R6
                BISB    #^O40,R6        ;enable clock driven

                MOVW    R6,@#ADCSR      ;load A/D CSR





                                  420

                                                           uNOTE # 044
                                                          Page 9 of 21




                MOVZWL  @IRATE(AP),R6   ;clock rate in R6
                BICL    #^O177770,R6    ;clear excess bits
                ASHL    #3,R6,R6        ;shift rate to bits 3 - 5
                MOVW    R6,@#KWCSR      ;load KW CSR

                MNEGW   @KOUNT(AP), -
                        @#KWPRE         ;load KW preset register

                MOVL    IBUF(AP),R6     ;load address of IBUF into R6
                MOVZWL  @NPNTS(AP),R7   ;load NPNTS into R7
                MOVL    #ADCSR,R8       ;R8 points to A/D CSR
                MOVL    #ADBUF,R9       ;use R9 as pointer to A/D buffer reg
                MOVZWL  @MODE(AP),R10   ;pass MODE arg to POLL in R10

                 $LCKPAG_S -             ;lock polling code into memory
                        INADR=LCKPAG, -
                        RETADR=LCKRET

                $CMKRNL_S POLL          ;execute routine POLL in kernel mode

                CLRW    @#KWCSR         ;zero KWCSR - turns clock off
                MOVZWL  (R8), -         ;return status is residual AXV CSR
                        @ISTATUS(AP)
                CLRW    (R8)            ;clear A/D CSR

                RET                     ;return to fortran

        LCKPAG: .LONG   POLL
                .LONG   POLL_END
        LCKRET: .BLKL   2

                .ENTRY  POLL,^M<R6,R7,R8,R9,R10>

                DSBINT  #30             ;disable all interrupts (except pwrfail)
                TSTW    R10             ;test mode
                BEQL    1$              ;if 0 then trigger immediately
                BISW    #20002,@#KWCSR  ;set clock to wait for ST2
                BRB     2$              ;and skip over next instruction
        1$:     BISW    #3,@#KWCSR      ;trigger immediately

        2$:     BBC     #7,(R8),2$      ;is conversion done?
                MOVW    (R9),(R6)+      ;store A/D value
                SOBGTR  R7,2$           ;decrement NPNTS; if not zero loop again

                ENBINT                  ;restore IPL to prior value

        POLL_END:
                RET

                .END

                                  421

uNOTE # 044
Page 10 of 21




        ;++
        ;  These routines are not used in the present example. They are provided
        ;  only for general reference.
        ;
        ;  FORTRAN calling interface:
        ;
        ;     CALL IPEEK32 ( OFFSET, VALUE )
        ;
        ;     CALL IPOKE32 ( OFFSET, VALUE )
        ;
        ;        where
        ;
        ;           OFFSET    = integer*2 offset in the I/O page
        ;
        ;           VALUE     = integer*2 value from/for the register selected
        ;
        ; These routines should be in the same .PSECT as the MAPIOP routine.
        ;
        ;--

                .ENTRY  IPEEK32,^M<R6>

                MOVZWL  @4(AP),R6               ;put OFFSET in R6
                MOVZWL  L^VIOP(R6),@8(AP)       ;put value from iopage in VALUE

                RET


                .ENTRY  IPOKE32,^M<R6>

                MOVZWL  @4(AP),R6               ;put OFFSET in R6
                MOVW    @8(AP),L^VIOP(R6)       ;put VALUE into iopage

                RET

















                                  422

                                                           uNOTE # 044
                                                         Page 11 of 21


         2  INTERRUPT PROGRAMMING UNDER VMS USING CONNECT-TO-INTERRUPT

      Interrupt service routines on unmapped, single-tasking systems  such  as
      PDP11s  running RT11-SJ are fairly straightforward.  An interrupt occurs
      and control is transfered directly  to  the  interrupt  service  routine
      (ISR).   This  involves  saving  the  current  program  counter (PC) and
      processor status word (PSW) and replacing  them  with  the  PC  and  PSW
      stored  at  the vector address for the interrupting device.  When I/O is
      complete, a completion flag may be set to notify  the  mainline  program
      that  the  data  have  been  stored  (or output).  The interrupt service
      routine returns control to the mainline  program  by  executing  an  RTI
      instruction which restores the saved PC and PSW registers.  The mainline
      program may test the completion flag to detect I/O completion.

      The virtual, multi-tasking, multi-user nature of VAX/VMS makes interrupt
      handling  more  complicated.   Since the process which requested the I/O
      might not be current at the time an interrupt occurred, the ISR code and
      data  must  reside  in  system virtual address space and must execute in
      system context.  If this were not the case, a context switch to that  of
      the  requesting  process  might  be needed before the interrupt could be
      serviced and this would impose too great a  penalty  in  response  time.
      Similarly,    notification   of   I/O   completion   must   be   handled
      asynchronously.  Finally, the sharing of I/O resources  among  multiple,
      possibly  non-cooperating  processes  imposes  additional  architectural
      demands.

      VMS resolves these issues through  the  implementation  of  an  elegant,
      though complex, I/O subsystem.  All VMS device drivers must interface to
      the I/O subsystem to insure the orderly flow of information between  the
      various  users'  processes  and  shareable  I/O  devices.  However, most
      realtime application programmers would prefer to avoid  writing  a  full
      VMS  device  driver  for  controlling  realtime  I/O  modules.   This is
      particularly true in light of the fact that realtime  devices  generally
      need  not  be  shareable among non-cooperating processes, whereas device
      shareability is one of the sources of complexity in the  I/O  subsystem.
      The  connect-to-interrupt  driver  enables  users  to  program interrupt
      service routines and asynchronous I/O completion routines without having
      to write a full VMS device driver.



         2.1  The Connect-to-Interrupt User Interface

      The connect-to-interrupt driver (CONINTERR or CIN)  is  a  template  VMS
      device  driver  into  which blocks of user-supplied code and data may be
      linked.  The user-supplied code and  data  are  contained  in  a  single
      .PSECT  hereafter  referred  to  as the "CIN buffer".  The CIN buffer is
      compiled and linked as part of the application  program.   The  linkages
      between  the  CIN  driver and the user-supplied CIN buffer are formed at
      run-time by the $QIO system service.   As  a  part  of  the  process  of
      building  these  links,  the  CIN  buffer  is mapped into system virtual
      address space (S0) while  preserving  the  mapping  in  process  virtual

                                  423

uNOTE # 044
Page 12 of 21


      address  space (P0).  The result is that the CIN buffer is doubly-mapped
      in S0 and P0 virtual address space.  Thus, code  and  data  in  the  CIN
      buffer are accessible in both system and process context.
        The CIN buffer comprises 5 sections:

        1. A data area containing all data structures to be addressed  during
           the execution of user-supplied CIN code.

        2. A device initialization routine which is executed during  recovery
           from a power failure.

        3. A start I/O routine which is executed at  the  time  the  $QIO  is
           issued.

        4. An interrupt service routine which is executed in  response  to  a
           device interrupt.

        5. A cancel I/O routine which  is  executed  when  the  user  process
           issues a cancel I/O request.

      In addition, the user may specify an  AST  routine  to  be  executed  in
      process  context  on  I/O  completion  (or  partial  completion).  It is
      important to note that any user-supplied code in the CIN buffer may only
      address  data  and  code  contained  within  the CIN buffer.  Code which
      executes in process context, including the user-specified  AST  routine,
      may  also address data and code in the CIN buffer and, of course, in any
      other portion of process virtual address space.   The  sections  of  the
      user-supplied CIN buffer are illustrated diagramatically below.

                   .PSECT  CIN_USER        PIC,USR,CON,REL,LCL,NOSHR,EXE,RD,WRT
                    ________________________________
                   |         Data buffers           |
                   |________________________________|
                   |         INIT routine           |
                   |    Executed after powerfail    |
                   |________________________________|
                   |        START routine           |
                   |       Executed by $QIO         |
                   |________________________________|
                   |         INT routine            |
                   |  Executed on device interrupt  |
                   |________________________________|
                   |       CANCEL routine           |
                   |     Executed by $CANCEL        |
                   |________________________________|

      This application note is intended to provide an  overview  of  CONINTERR
      concepts  for  intermediate  to  advanced  programmers  who  want to get
      started  using  this  facility.   Many  of  the  details  of   CONINTERR
      functionality  and internals have been omitted, though what is presented
      is sufficient for many applications.  For a more detailed description of
      CONINTERR, see the VAX/VMS Release Notes, Appendix C.

                                  424

                                                           uNOTE # 044
                                                         Page 13 of 21


           2.2  Example Code Internals

      The example program performs continuous interrupt-driven analog input to
      a  process  buffer  using  an  AXV11-C analog module and a KWV11-C clock
      module for timebase generation.  Data are sampled into a 4096-word  ring
      buffer  with  2  sub-buffers.   The  ring buffer is contained in the CIN
      buffer and is therefore doubly mapped in S0 and P0.  When  a  sub-buffer
      is  filled, an AST is delivered to the calling process.  The AST routine
      moves the data from the sub-buffer to a process buffer (singly mapped in
      P0  virtual  address space).  It then checks to determine whether I/O is
      complete; that is, whether the process buffer has received all the  data
      requested.   If  it has, the AST issues a $CANCEL system service call to
      terminate I/O and sets a completion flag to notify the  calling  program
      of I/O completion.



                           SYSTEM SETUP FOR CONNECT-TO-INTERRUPT


           1. Log in to SYSTEM account.

           2. Insert the following line in the file SYS$SYSTEM:MODPARAMS.DAT

              REALTIME_SPTS = 20

           3. Enter:

              $ @SYS$UPDATE:AUTOGEN SAVPARAMS REBOOT
                   .
                   .
              (system reboots)

           4. Log in to SYSTEM account or other privileged account and enter:

              $ MCR SYSGEN
              SYSGEN> CONNECT 
                      AXA0:/ADA=0/CSR=%O770400/VEC=%O400/DRIVER=CONINTERR
              SYSGEN> EXIT

              $ MACRO AXV
              $ FORTRAN CALL_AXV
              $ LINK CALL_AXV,AXV
              $ SET PROCESS/PRIV=(PSWAPM,CMKRNL)   !Required privileges
              $ SET PROCESS/PRIORITY=17
              $ RUN CALL_AXV


      .page
      System page table entries for double-mapping of  CONINTERR  buffers  are
      drawn  from  a  pre-allocated  pool.  In steps 1 - 3, above, the size of
      this pool is set by modifying the SYSGEN parameter  REALTIME_SPTS.   The

                                  425

uNOTE # 044
Page 14 of 21


      number  of  page  table  entries allocated must be sufficient to map the
      user buffers (data and code) of all CONINTERR-driven devices  which  are
      connected  at  any  given  time.   In the present example, 20 page table
      entries are allocated, sufficient to map 5120 words of  data  and  code.
      This  step  needs  to  be  taken  only when additional REALTIME_SPTS are
      required for mapping CONINTERR buffers.

      In step 4, above, the device is connected to the system.  In this  case,
      the  device  was  given  the  name  "AXA0"; this is the name used in the
      $ASSIGN system service call.  Switches are used to designate the adapter
      number  (always  0  on  MicroVAXes), the CSR and vector addresses of the
      module, and the driver name (CONINTERR).  This step needs  to  be  taken
      each  time  the system is booted.  The commands may be inserted into the
      file SYS$MANAGER:SYCONFIG.COM, if desired.


                 PROGRAM CALL_AXV        !Calling program for AXV_SAMPLE

                 INCLUDE '($SYSSRVNAM)'

                 BYTE ICMPF
                 INTEGER*2 PBUFF(30000)
                 INTEGER*4 ISTATUS, ICHAN, IPRESET, ICOUNT
                 INTEGER*4 LOCKS(2)
                 INTEGER*4 AXV_SAMPLE

                 COMMON /PROCESS_DATA/ PBUFF, ICMPF

         o  Lock the process buffer into the working set. This is not essential,
         o  but it helps to avoid page faulting in the AST routine.

                 LOCKS(1) = %LOC(PBUFF(1))
                 LOCKS(2) = %LOC(PBUFF(30000))
                 ISTATUS = SYS$LCKPAG (LOCKS,,)
                 IF(.NOT.ISTATUS) CALL EXIT (ISTATUS)

         o  Assign a channel number for the AXV

                 ISTATUS = SYS$ASSIGN ('_AXA0:' ,ICHAN,,)
                 IF(.NOT.ISTATUS) CALL EXIT (ISTATUS)

         o  Input/initialize arguments to be passed to the calling routine

                 TYPE *, 'KWV preset, sample count?'
                 ACCEPT *, IPRESET, ICOUNT








                                  426

                                                           uNOTE # 044
                                                         Page 15 of 21




         o  Routine AXV_SAMPLE handles all of the details of setting up and
         o  executing the I/O operations. When the process buffer is filled,
         o  the completion flag is set.

                 ICMPF = 0       ! Clear the completion flag
                 ISTATUS = AXV_SAMPLE (ICHAN, IPRESET, ICOUNT)
                 IF(.NOT.ISTATUS) CALL EXIT (ISTATUS)

         o  By looping on the completion flag, the process is insured of 
         o  remaining computable throughout the I/O operation.

           100     IF(ICMPF.EQ.0) GO TO 100

         o  For the sake of simplicity in this example, only a few of the 
         o  acquired data values are output. In a real application, the 
         o  following step would be replaced with file/graphic output.

                   TYPE 9000, (J,PBUFF(J),J=1,1000,100)
           9000    FORMAT(2I10)

                   END


                 .TITLE  AXV

                 .LIBRARY /SYS$LIBRARY:LIB.MLB/

                 $IDBDEF                 ; Definition for I/O drivers
                 $UCBDEF                 ; Data structurs
                 $IODEF                  ; I/O function codes
                 $CINDEF                 ; Connect-to-interrupt 
                 $CRBDEF                 ; CRB stuff
                 $VECDEF                 ; more


                 .PSECT PROCESS_ROUTINES   PIC,USR,CON,REL,LCL,NOSHR,EXE,RD,WRT

         ;++
         ; This example routine issues the QIO to connect to the AXV 
         ; interrupts.  It takes care of the internals associated with the 
         ; connect-to-interrupt QIO. 
         ;
         ; FORTRAN calling sequence:
         ;
         ;   STATUS = AXV_SAMPLE ( CHAN, PRESET, COUNT )
         ;
         ;   where
         ;
         ;      CHAN     = longword channel # for device _AXA0
         ;

                                  427

uNOTE # 044
Page 16 of 21


         ;      PRESET   = longword preset value for KWV
         ;                 (positive value <= 32K)
         ;
         ;      COUNT    = longword # of samples
         ;
         ;      STATUS   = longword return status of $QIO call
         ;
         ; In this example, the AXV and KWV CSRs are "firm-wired" for the 
         ; following characteristics:
         ;
         ;       AXV - gain=1, RTC ENABLE, DONE INT ENABLE, channel=0
         ;
         ;       KWV - GO, mode=1, rate=1 (1 MHz)
         ;
         ; Ordinarily, they would be configured according to arguments passed
         ; to this routine from the calling program.
         ;
         ; The CLK OVFL pin on the KWV is strapped to the RTC IN pin on the AXV.
         ;
         ;--

                 .ENTRY  AXV_SAMPLE,^M<>

         ; These values are stored in process address space for use in the AST
         ; routine

                 MOVL    @4(AP),AXV_CHAN         ; Channel # for $CANCEL
                 MOVL    @12(AP),POINT_COUNT     ; Point count


         ; These values are stored in system address space for use in the CIN 
         ; user start routine.

                 MOVW    #^O13,KWV_CSR_VALUE     ; GO, MODE=1, 1MHz
                 MOVW    #^O140,AXV_CSR_VALUE    ; RTC ENABLE, DONE INT ENABLE
                 MNEGW   @8(AP),KWV_PRESET_VALUE ; Negated KWV preset value

                 $QIO_S  CHAN=@4(AP),-           ;Channel
                         FUNC=#IO$_CONINTWRITE,- ;Allow writes to data buffer
                         IOSB=AXV_CIN_IOSB,-     ;I/O status Block
                         P1=AXV_CIN_BUF_DESC,-   ;Buffer descriptor
                         P2=#AXV_CIN_ENTRY,-     ;Entry list
                         P3=#AXV_CIN_MASK,-      ;Status bits,etc
                         P4=#USER_AST,-          ;AST service routine
                         P6=#10                  ;preallocate some AST control
                                                 ; blocks
                 RET                             ;Return to calling routine

         AXV_CIN_BUF_DESC:                       ;Buffer descriptor for CIN
                 .LONG   USER_END - RINGBUF
                 .LONG   RINGBUF


                                  428

                                                           uNOTE # 044
                                                         Page 17 of 21


         AXV_CIN_ENTRY:
                 .LONG   USER_INIT - RINGBUF     ;Init code
                 .LONG   USER_START - RINGBUF    ;Start code
                 .LONG   USER_INT - RINGBUF      ;Interrupt service routine
                 .LONG   USER_CNCL - RINGBUF     ;I/O cancel routine

         AXV_CIN_IOSB:
                 .LONG   0                       ; I/O Status Block
                 .LONG   0

         ; Control mask - see VMS Release Notes, Appendix C for explication

         AXV_CIN_MASK = CIN$M_REPEAT!CIN$M_START!CIN$M_ISR!CIN$M_CANCEL



                 .SBTTL  USER_AST, User AST routine

         ;++
         ; This routine is invoked when I/O complete is signaled by the USER_INT
         ; routine. It is queued to the user's process in the access mode of the
         ; $QIO which initiated the I/O. It executes in process context at
         ; IPL$_ASTDEL (IPL 2).
         ;
         ; I/O completion is signalled by loading SS$_NORMAL (1) into R0 on 
         ; exiting the USER_INT routine. In the present example, this does not 
         ; signal full completion of the I/O, since the CIN$M_REPEAT flag was 
         ; set in the $QIO call.
         ;
         ;--

                 .ENTRY  USER_AST,^M<R2,R3,R4,R5>



                 MOVAL   RINGBUF,R2              ; Get CIN buffer address
                 MOVZWL  RINGBUF_INDEX,R3        ; Get buffer index
                 BBS     #11,R3,10$              ; Is bit 11 set?
                 ADDL    #4096,R2                ; No, xfer the top half
         10$:    MOVAL   PBUFF,R4                ; Get process buffer address
                 ADDL    PBUFF_INDEX,R4          ; Add Index
                 MOVC3   #4096,(R2),(R4)         ; Move data (trashes R0-R5)
                 ADDL    #4096,PBUFF_INDEX       ; Update process buffer "index"
                 SUBL2   #2048,POINT_COUNT       ; Update point count
                 BGTR    20$                     ; Have we moved all the data?
                 JMP     ALL_DONE                ; Yes - Finish up
         20$:    MOVZWL  #SS$_NORMAL,R0          ; Set return status
                 RET                             ; And return

         ALL_DONE:
                 $CANCEL_S -                     ; Cancel the I/O request
                         CHAN=AXV_CHAN
                 CLRL    PBUFF_INDEX             ; Reset index into PBUFF

                                  429

uNOTE # 044
Page 18 of 21


                 MOVB    #1,ICMPF                ; Set the completion flag
                 MOVZWL  #SS$_NORMAL,R0          ; Set return status
                 RET                             ; And return

         PBUFF_INDEX:
                 .LONG   0

         POINT_COUNT:
                 .LONG   0

         AXV_CHAN:
                 .LONG   0


                 .PSECT PROCESS_DATA     PIC,OVR,REL,GBL,SHR,NOEXE,RD,WRT,LONG

         ;++
         ; This is the FORTRAN common block /PROCESS_DATA/ 
         ;--

         PBUFF:  .BLKW   30000

         ICMPF:  .BYTE   0

                 .PSECT CIN_USER         PIC,USR,CON,REL,LCL,NOSHR,EXE,RD,WRT

         ;++
         ; This is the CIN buffer. In the present example, it is contained in
         ; the same source code module as the process routines shown above.
         ;--

                 .SBTTL  DATA STRUCTURES

         DATA_BUF_SIZE  =        4096

         RINGBUF:                .BLKW   DATA_BUF_SIZE
         RINGBUF_END:
         RINGBUF_INDEX:          .WORD

         AXV_CSR_VALUE:          .WORD
         KWV_CSR_VALUE:          .WORD
         KWV_PRESET_VALUE:       .WORD

         ; In the CIN user routines, the system virtual address of the CSR of 
         ; the device is supplied. Other addresses in the I/O page used by the
         ; code must be handled as offsets from the device CSR.

         AXV_ADDRESS     = ^O170400               ;Address of AXV
         KWV_ADDRESS     = ^O170420               ;Address of KWV
         KWV_OFFSET      = KWV_ADDRESS-AXV_ADDRESS ;Offset for KWV CSR
         PRESET_OFFSET   = KWV_OFFSET+2           ;Offset for KWV BPR
         DBR_OFFSET      =2                       ;Offset for AXV DBR 

                                  430

                                                           uNOTE # 044
                                                         Page 19 of 21



                 .SBTTL  USER_INIT       ; Dummy dev intialization routine
         ;++
         ; This routine is invoked after power recovery. It executes in system
         ; context at IPL$_POWER (IPL 31). 
         ;
         ; This routine is not implemented in the present example. However, the
         ; entry point must be defined and included in the entry list of the
         ; $QIO (P2).
         ;
         ; See VAX/VMS Release Notes, Appendix C for inputs.
         ;
         ;--

         USER_INIT::
                 RSB


                 .SBTTL  USER_START, Start I/O routine

         ;++
         ; This routine is invoked by the $QIO system service. It executes in
         ; system context at IPL$_QUEUEAST (IPL 6). 
         ;
         ;   On entry:


         ;
         ;       0(R2)  - arg count of 4
         ;       4(R2)  - Address of the process buffer (system mapped)
         ;       12(R2) - Address of the device's CSR
         ;
         ; See VAX/VMS Release Notes, Appendix C for other inputs.
         ;
         ; The routine must preserve all registers except R0-R4.
         ;
         ;--

         CSR_ADD = 12               ; Argument list offset of CSR addr
                                    ; (only valid in USER_START and USER_INT)

         USER_START::
                 CLRW    RINGBUF_INDEX           ; Clear ring buffer index
                 MOVL    CSR_ADD(R2),R0          ; Get address of the AXV CSR 
                 TSTW    DBR_OFFSET(R0)          ; Clear AD DONE bit, if set,
                                                   ;   by reading AXV DBR
                 MOVW    AXV_CSR_VALUE,(R0)      ; Set up the AXV
                 MOVW    KWV_PRESET_VALUE, -     ; Set KWV preset
                         PRESET_OFFSET(R0)
                 MOVW    KWV_CSR_VALUE, -        ; Set KWV CSR
                         KWV_OFFSET(R0)
                 MOVZWL  #SS$_NORMAL,R0          ; Load a success code into R0.

                                  431

uNOTE # 044
Page 20 of 21


                 RSB                             ; Return


                 .SBTTL  USER_INTERRUPT, Interrupt service routine

         ;++
         ; This routine is invoked on device interrupt. It executes in system
         ; context at IPL$_DIPL (IPL 23 in MicroVMS).
         ;
         ; On entry:
         ;
         ;       0(R2)  - arg count of 5
         ;       4(R2)  - Address of the process buffer
         ;       8(R2)  - Address of the AST parameter
         ;       12(R2) - Address of the device's CSR
         ;
         ; See VAX/VMS Release Notes, Appendix C for other inputs.
         ;
         ; The routine must preserve all registers except R0-R4
         ;
         ;--

         USER_INT::
                 MOVL    CSR_ADD(R2),R0          ; Get AXV CSR address
                 MOVAL   RINGBUF,R1              ; Get CIN buffer address
                 MOVZWL  RINGBUF_INDEX,R3        ; Get buffer index
                 MOVW    DBR_OFFSET(R0),(R1)[R3] ; Read data (assume no error)
                 INCW    R3                      ; Increment buffer index
                 BICW    #^O170000,R3            ; Clear all but bottom 12 bits 
                                                 ; of (ring) buffer index


                 MOVW    R3,RINGBUF_INDEX        ; Put updated index in storage
                 CLRL    R0                      ; Clear return status
                 BICW    #^O174000,R3            ; Now test bottom 11 bits of
                                                 ;   buffer index
                 BNEQ    10$                     ; Skip AST if not zero

         ; The user AST will be queued if the LSB of R0 is set on return

         5$:     MOVZWL  #SS$_NORMAL,R0          ; Queue the AST
         10$:    RSB


                 .SBTTL  USER_CANCEL, Cancel I/O routine

         ;++
         ; This routine is invoked by the $CANCEL system service. It executes in
         ; system context at IPL$_QUEUEAST (IPL 6). 
         ;
         ; On entry:
         ;

                                  432

                                                           uNOTE # 044
                                                         Page 21 of 21


         ;   JSB interface:
         ;
         ;       R3      -  Addr of current IRP
         ;       R4      -  Addr of PCB of cancelling process
         ;       R5      -  Addr of the UCB
         ;
         ;   CALL interface:
         ;
         ;       0(AP)   Arg count 4
         ;       8(AP)   Addr of IRP
         ;       12(AP)  Addr of PCB
         ;       16(AP)  Addr of UCB
         ;
         ; See VAX/VMS Release Notes, Appendix C for other inputs.
         ;
         ; The routine must preserve all registers except R0 and R3.
         ;
         ;--

         USER_CNCL::
                 MOVL    UCB$L_CRB(R5),R0         ; Get Address of the CRB
                 MOVL    CRB$L_INTD+VEC$L_IDB(R0),R0 ; Address of the IDB
                 MOVL    IDB$L_CSR(R0),R0         ; Get addr of AXV
                 CLRW    KWV_OFFSET(R0)           ; Stop clock
                 TSTW    DBR_OFFSET(R0)           ; Clear AD DONE bit
                 CLRW    (R0)                     ; Clear AXV CSR
                 MOVZWL  #SS$_NORMAL,R0           ; Load return status
                 RSB                              ; And return

         ; Label that marks the end of the module

         USER_END:                               ; Last location in module
                 .LONG

                 .END


















                                  433
