 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
;                       VMS OPdriver Redesign Specification
  
 
4                              Pass 1 - July 8, 1996
  -                                    CONTENTS
  
H         1       INTRODUCTION . . . . . . . . . . . . . . . . . . . . 1
H         1.1       Goals  . . . . . . . . . . . . . . . . . . . . . . 1
H         1.2       Overview Of Design Plans . . . . . . . . . . . . . 1
H         1.3       Project Scope  . . . . . . . . . . . . . . . . . . 2
H         1.4       Assumptions  . . . . . . . . . . . . . . . . . . . 2
H         1.5       Release Plans  . . . . . . . . . . . . . . . . . . 3
H         1.6       Team . . . . . . . . . . . . . . . . . . . . . . . 3
H         2       DESIGN CONSIDERATIONS  . . . . . . . . . . . . . . . 3
H         2.1       Configurations . . . . . . . . . . . . . . . . . . 3
H         2.1.1     Graphics Configuration . . . . . . . . . . . . . . 4
H         2.1.2     Serial Configuration . . . . . . . . . . . . . . . 4
H         2.2       OPdriver Unit Numbers  . . . . . . . . . . . . . . 4
H         2.3       I/O Modes  . . . . . . . . . . . . . . . . . . . . 4
H         2.3.1     Polled I/O . . . . . . . . . . . . . . . . . . . . 5
H         2.3.2     Interrupt-Driven I/O . . . . . . . . . . . . . . . 5
H         2.3.3     Synchronous I/O  . . . . . . . . . . . . . . . . . 5
H         2.4       Scan Code Translation  . . . . . . . . . . . . . . 5
H         2.5       DECwindows . . . . . . . . . . . . . . . . . . . . 5
H         3       DESIGN DISCUSSION  . . . . . . . . . . . . . . . . . 6
H         3.1       Image Loading And Initialization . . . . . . . . . 6
H         3.2       Device Control . . . . . . . . . . . . . . . . . . 7
H         3.2.1     Modem Control  . . . . . . . . . . . . . . . . . . 7
H         3.2.1.1   SET_MODEM_CTL  . . . . . . . . . . . . . . . . . . 7
H         3.2.2     Interrupt Control  . . . . . . . . . . . . . . . . 8
H         3.2.2.1   SET_INT_SERIAL   . . . . . . . . . . . . . . . . . 8
H         3.2.2.2   SET_INT_GRAPHICS   . . . . . . . . . . . . . . . . 9
H         3.3       Polled I/O . . . . . . . . . . . . . . . . . . . . 9
H         3.3.1     Polled Input . . . . . . . . . . . . . . . . . . . 9
H         3.3.1.1   GETC_GRAPHICS  . . . . . . . . . . . . . . . . . . 9
H         3.3.1.2   GETC_SERIAL  . . . . . . . . . . . . . . . . . .  10
H         3.3.1.3   TRANSLATE_KEY  . . . . . . . . . . . . . . . . .  10
H         3.3.2     Polled Output  . . . . . . . . . . . . . . . . .  11
H         3.3.2.1   PUTS_GRAPHICS  . . . . . . . . . . . . . . . . .  11
H         3.3.2.2   PUTS_SERIAL  . . . . . . . . . . . . . . . . . .  11
H         3.4       Interrupt-Driven I/O . . . . . . . . . . . . . .  11
H         3.4.1     Interrupt-Driven Input . . . . . . . . . . . . .  12
H         3.4.2     Interrupt-Driven Output  . . . . . . . . . . . .  13
H         3.5       Synchronous I/O  . . . . . . . . . . . . . . . .  13
H         3.6       Initial Preparation And Cleanup Work . . . . . .  13
  R                                                                           Page 1
 
 
        1  INTRODUCTION
 
O        The purpose of this  specification  is  to  describe  and  define  the
 O        proposed  redesign  of  the  VMS OPdriver component.  It also includes
 O        information on how the existing OPdriver operates in order to  provide
 .        the necessary background information.
 
 
 
        1.1  Goals
  
O        OPdriver is the VMS  driver  that  enables  the  operating  system  to
 O        communicate with and control the console terminal devices.  It accepts
 O        input from the terminal keyboard and writes  output  to  the  terminal
 O        graphics  screen,  whether  those  components  are locally or remotely
 O        located.  This allows the console terminal to be used by  VMS  in  the
 @        booting, debugging, and normal operation of the system.
 
O        The problem being addressed by the redesign of OPdriver  is  that  the
 O        console firmware of the system is, by design, intimately involved in a
 O        significant amount of the work that the driver performs.  Unlike  most
 O        VMS   drivers,   OPdriver  does  not  communicate  directly  with  its
 O        associated hardware.  Instead, it makes callbacks to routines  in  the
 O        system's  console  which  perform  this  task.   The intention of this
 O        design was to make the VMS driver less susceptable to changes  in  the
 O        hardware  design;  the  console for each system would accomodate these
 O        changes and VMS would just continue to make a standard set of software
         callbacks.
  
O        However, unforeseen problems in this scheme have turned up  along  the
 O        way  which  are  seen  to out-weigh the benefits of the original plan.
 O        The bulk of these problems are traceable to the console  firmware  now
 O        being  in the critical path for resolving a number of issues affecting
 O        VMS.  (See the OPdriver Investigation Report for  a  detailed  problem
 O        statement.)  Also,  the necessity of updating the VMS OPdriver to keep
 O        up with hardware changes seems to be less of an issue now, as we  have
 O        seen  the  hardware  used  to implement the console terminal interface
 ,        undergoing little change over time.
 
O        In summary, the principal goal of this project is to eliminate console
 O        involvement  from  OPdriver  as  much  as possible, thereby making the
 O        driver maintainable by a  single  design  group  having  a  consistent
 "        vision for its operation.
 
 
 
&        1.2  Overview Of Design Plans
 
O        Most of the original OPdriver code will be reused for the new  design.
 O        It  will  be  ported  to  the  C  programming  language and cleaned up
 O        wherever possible in the initial stage of the design.  The bulk of the
 O        work will involve writing new routines to communicate with the control
 O        and status registers of the console  terminal  port  devices:   serial
 O        line,  keyboard,  mouse, and graphics terminal.  Another task formerly
 O        handled by the  console  is  the  translation  of  keycodes  from  the
 G        keyboard.  This also will have to by done within OPdriver now.
   R                                                                           Page 2
 
 
O        The initial plan for this redesign was to write three separate  driver
 O        modules   to  handle  1)  the  serial  line  OPdriver  connection,  2)
 O        keyboard/mouse input in graphics mode, and 3)  graphics  mode  output.
 O        After  some study and testing of this plan, it was decided that it was
 O        considerably more complex to implement than necessary to  satisfy  the
 O        goals  of this project.  Instead, it was decided to reuse the existing
 O        OPdriver structure, replacing only  the  console  callbacks  with  new
 =        hardware interface routines and keycode translation.
  
O        Only those callbacks that reference the console terminal devices  will
 O        be  replaced  by  this  redesign  of  OPdriver.  The following console
 O        callbacks are used in a number of  VMS  facilities  and  will  not  be
         replaced:
 
1          GET_ENV - Read an environment variable
 2          SET_ENV - Write an environment variable
8          SAVE_ENV - Save current environment variables
/          OPEN - Open sn I/O device for access
 &          READ - Read from I/O device
&          WRITE - Write to I/O device
.          CLOSE - Close I/O device for access
1          PSWITCH - Switch the primary processor
 C          SAVE_ERROR_LOG - write error log to non-volatile storage
  
 
 
        1.3  Project Scope
  
O        The first release of the new OPdriver will support Alpha systems  that
 O        use  the console terminal interface hardware most recently implemented

O        in Digital's Alpha systems.  This hardware uses a common protocol that
PO        will  allow  the  same  OPdriver  code  to  be  used with any of these
uO        systems.  Examples of this hardware are the  PC87312  Combo  chip  and
 6        8242 keyboard/mouse controller used on Sable.
 
O        Specifically, the new OPdriver design will support all  Alpha  systems
 O        except  for  Cobra,  Ruby,  Jensen,  Sandpiper, Flamingo, and Pelican.
 O        [Are there any others?] These earlier systems will continue to use the
uO        originally   designed   OPdriver  image,  SYS$OPDRIVER.   Later  Alpha
nO        systems, from Sable to the present, will use the  new  OPdriver  image
.O        whose  design  is specified here.  (See section 3.1, Image Loading and
.C        Initialization, for how these images will be coordinated.)
. 
O        Early testing of the new  OPdriver  is  being  done  on  Sable  family
.O        systems.   Once this work has been completed, testing will be expanded
.O        to all other systems to be supported.  This  may  require  changes  to
4B        system-specific code (e.g.  in SYS$CPUxxxx_ROUTINES.EXE).
 
 
 
        1.4  Assumptions
. 
O        As  stated  above,  an  important  assumption  is  that  the  hardware
.O        components  selected  to  interface  with the console terminal devices
.O        will remain stable over a reasonably lengthy period of time.  We  have
.O        seen  this  be the case over the past several years with the selection
.O        of console terminal interface hardware whose internal registers can be
   R                                                                           Page 3
 
 
>        accessed using a consistent set of software routines.
 
O        However, there will undoubtedly come a point in the future where it is
OO        deemed  necessary  to select a different family of interface hardware.
tO        At this point, it will be necessary to update the  OPdriver  interface
.O        routines  defined  in this specification to be compatible with the new
.O        hardware.   Again,  it  is  assumed  that  selections   of   new   and
.O        incompatible  families  of console terminal interface hardware will be
.        few and far between.
C 
 
 
        1.5  Release Plans
. 
O        The new OPdriver is expected to be released with the  OpenVMS  Tsunami
 O        release  in  the  second  half  of  calendar  year  1997.  The changes
.O        required to implement this version of OPdriver will not be  propogated
 O        to  earlier versions of OpenVMS.  These earlier versions will continue
RO        to support only the original OPdriver  design  that  relies  upon  the
n        console.
. 
 
 
        1.6  Team
 
G        Yonyuth Hongsakphadana will handle most of the C porting work.
  
O        Vince Husovsky  will  be  providing  the  spec,  coding,  and  testing
u4        relating to graphics output and DECwindows.
 
O        Bob Silver will be providing  the  overall  design  spec;  coding  and
 O        testing  relating  to  serial  mode  I/O,  graphics  mode  input,  and
 O        translation of keyboard scan  codes;  porting  of  the  initialization
bO        code;  changes  to  OPdriver  loading  and initialization; and general
t&        cleanup of the existing code.
 
 
 
!        2  DESIGN CONSIDERATIONS
e 
O        The following section describes a few features unique to OPdriver that
15        need to be considered in this design effort.
h 
 
 
        2.1  Configurations
 
O        There are essentially two configurations of the console terminal  that
 O        need to be addressed in this redesign.  Most systems may be configured
 O        with terminal devices that are an integral part of the system  running
 O        VMS or may use devices that are remotely connected over a serial line.
 O        The former is enabled by setting the console environment  to  GRAPHICS
oO        mode  and  will  be  referred  to  as a "graphics" configuration.  The
eO        latter is enabled by setting the console  environment  to  SERIAL  and
i1        will be called a "serial" configuration.
U kR                                                                           Page 4
 
 
O        2.1.1  Graphics Configuration - When the console environment is set up
 O        with  CONSOLE=GRAPHICS,  the system gets configured in such a way that
 O        the attached keyboard and graphics terminal are considered to  be  the
 O        console  terminal  devices.   Input  comes  into  the  system from the
 O        keyboard and mouse port devices.  Output goes to the system's graphics
 O        adapter  out  on  one  of the main I/O busses.  I/O through the serial
vO        line COM ports has nothing to do with the console terminal.   And,  as
tO        of  VMS  V7.1,  I/O  through  these ports will no longer be handled by
e        OPdriver.
 
 
 
O        2.1.2  Serial Configuration - When the console environment is  set  up
 O        with  CONSOLE=SERIAL,  the  system gets configured so that the console
 O        terminal devices are accessed over the computer's serial line.   Input
 O        comes  from  a remote keyboard into a serial port device.  Output goes
 O        through the same device out to a remote graphics terminal.  The  local
 O        keyboard  and  graphics  terminal are not involved in console terminal
a=        operation although their I/O is handled by OPdriver.
t 
 
 
#        2.2  OPdriver Unit Numbers
m 
O        The console terminal devices  are  labelled  with  unit  numbers  zero
iO        through  three and prefixed with the label OPA.  The table below shows
 O        how these unit numbers are distributed to the various devices.  As  of
tO        VMS  V7.1,  the  COM1  serial port in a graphics configuration will be
eO        handled by a terminal port driver such as  YSdriver.   Previously,  it
 O        was  called  OPA1  in  this  configuration  with  OPdriver as its port
w        driver.
 
"            Serial configuration:
"                 OPA0        COM1
!                 OPA1        N/A
uD                 OPA2        Keyboard (inactive without DECwindows)
A                 OPA3        Mouse (inactive without DECwindows)
 "                 TTA0        COM2
 
$            Graphics configuration:
;                 OPA0-in     Keyboard (without DECwindows)
 +                 OPA0-out    Graphics head
l!                 OPA1        N/A
e8                 OPA2        Keyboard (with DECwindows)
#                 OPA3        Mouse
c"                 TTA1        COM2
"                 TTB1        COM1
 
 
 
        2.3  I/O Modes
  
O        When the system is up and running, the operating  system  will  depend
lO        upon   interrupts   from   the  console  terminal  in  scheduling  I/O
tO        transactions with the terminal devices.  When the  system  is  in  the
tO        process  of booting, being debugged, or handling errors, interrupts to
nO        OPdriver will be disabled and the operating system will have  to  poll
t fR                                                                           Page 5
 
 
O        bits  in  the  hardware  registers  to  coordinate I/O to the terminal
 O        devices.  Like the existing OPdriver design, the new driver will  have
aO        to  provide  both  a  polling  and  an  interrupt-driven mechanism for
 1        communicating with the console terminal.
l 
 
 
O        2.3.1  Polled I/O - OPdriver  provides  routines  to  read  and  write

O        characters to the console terminal device when interrupt I/O cannot be
cO        used.  To synchronize these operations, read and write  routines  poll
OO        bits  in  the  port  hardware  registers to see when characters may be
cO        transferred.  These routines may be called in either a wait or  nowait
mO        mode (i.e.  keep trying until the device is ready or try once and quit
lO        if the device isn't ready).  These polled routines  are  available  to
c        all VMS facilities.
 
 
 
O        2.3.2  Interrupt-Driven I/O - When the use of interrupts is available,
tO        the  coordination  of  asynchronous OPdriver I/O is controlled by that
nO        mechanism instead of polling.  Interrupts from  the  console  terminal
uO        devices  are  handled in several stages.  From the SCB vector, control
eO        is first passed to a generic  I/O  interrupt  routine  (IO_INTERRUPT),
sO        then  to  a  system-specific interrupt handler (such as INTR_DISP_ICIC
SO        for Lynx),  then  to  a  device-specific  dispatch  routine  (such  as
 O        COM1_DISPATCH  for  the  COM1 serial port), and finally to an input or
iO        output routine in OPdriver itself  (CON$INTINP  or  CON$INTOUT).   See
 4        section 3.4 for further discussion on this.
 
 
 
O        2.3.3  Synchronous I/O - Output  to  the  attached  graphics  terminal
oO        screen  is  done  synchronously  and  does  not  require  the  use  of
.O        interrupts.  In this case,  the  class  driver  references  OPdriver's
PO        vector  table  and branches to its port startio and synchronous output
a        routines.
 
 
 
#        2.4  Scan Code Translation
  
O        Another  important  function  now  handled  by  the  console  callback
 O        functions  is  the  translation  of  keyboard input scan codes (binary
 O        representations of the keyboard keys).  A GETC  function  executed  by
 O        the firmware will not only fetch the next available character from the
 O        keyboard but will also translate it into the  representation  expected
 O        by  VMS.   In  the absence of console callbacks, OPdriver will have to
 '        provide this function instead.
o 
 
 
        2.5  DECwindows
 
O        There are some notable differences in the operation of  OPdriver  when
AO        the   console   terminal   is  running  DECwindows.   Among  the  more
rO        significant differences are the  following:   the  class  driver  that
hO        handles  keyboard and mouse input is changed from TTdriver to IKdriver
i mR                                                                           Page 6
 
 
O        (keyboard) and IMdriver (mouse), scan code input from the keyboard  is
sO        passed  untranslated  to  DECwindows which does the conversion itself,
sO        output to the graphics terminal is  passed  off  to  one  of  the  VMS
e@        graphics drivers rather than being handled by OPdriver.
 
 
 
        3  DESIGN DISCUSSION
r 
O        This  section  describes  the  proposed  changes  to  OPdriver.   Each
tO        subsection  will  briefly summarize the existing OPdriver behavior and
 O        then explain the proposed new behavior.  This  discussion  covers  the
         following topics:
 
/            - Image Loading and Initialization
             - Device Control
d            - Polled I/O
B#            - Interrupt-Driven I/O
r            - Synchronous I/O
3            - Initial Preparation and Cleanup Work
  
O        The structure of the majority of OPdriver's  routines  is  as  follows
         (see example below):
  
O        There  exists  one  OPdriver  routine  per  major  function,  labelled
cO        CON$<function>.   This  CON$  routine  includes  execution  of  a more

O        specific function implemented within a macro labelled CTSR$<function>.
1O        In  the  existing  OPdriver  design,  the CTSR$ macro makes a callback
 O        request to the console.  In the new OPdriver, this macro will  call  a
oO        new  OPdriver  routine  to talk directly to console terminal hardware.
 <        This is illustrated below for the GETCHAR function.
 
=           Existing OPdriver                    New OPdriver
i=           =================                    ============
TA          CON$GETCHAR routine                CON$GETCHAR routine
C5                |                                  |
r?            CTSR$GETC macro                    CTSR$GETC macro
n7                  |                                  |
lQ              Dispatch callback to console       Call hardware interface routine
  
O        In the  new  OPdriver,  the  higher-level  CON$  routine  will  remain
aO        unchanged  so  that calls made from other VMS facilities will not have
 O        to be altered.  The contents of the  CTSR$  macro  that  implements  a
dO        specific  function  will  be  changed  so that a new OPdriver hardware
eE        interface routine gets called instead of a console callback.
o 
O        OPdriver's hardware interface will be implemented using VMS  calls  to
o0        IOC$MAPIO, IOC$WRITEIO, and IOC$READIO.
 
 
 
.        3.1  Image Loading And Initialization
 
O        OPdriver initialization is quite different  from  that  of  other  VMS
lO        drivers.  It is necessary to load the image very early in the VMS boot
iO        process, link it to a  class  driver  differently,  set  up  a  unique
A/        interrupt vectoring scheme, and so on.
l  R                                                                           Page 7
 
 
O        The SYS$OPDRIVER image  is  loaded  by  SYSBOOT  as  one  of  the  VMS
tO        execlets.    Most   of   its   data  structures  get  defined  by  the
kO        initialization  routine  for  the  SYSTEM_PRIMITIVES  image  (in   the
oO        Permanent_Device_Database   module).Its  class  driver,  TTdriver,  is
PO        loaded at the start of Exec_Init and  gets  linked  up  with  OPdriver
iO        through  its  data  structures.   During  initialization  of  the  I/O
.O        database, OPdriver's Ctrl_Init and Unit_Init routines (CON$INITIAL and
vO        CON$INITLINE)   are   executed.   These  routines  set  up  OPdriver's
cO        interrupt linkage, set key flags such  as  ALT_CONSOLE  (indicating  a
rO        serial console configuration), initialize more data structures such as
tO        the SYSG data block and UCB, and enable interrupts  from  the  console
:        terminal devices.
 
O        Very little is expected to change in the initialization  of  OPdriver.
(O        The  most  important  change  is  how  the  execlet is to be loaded by
uO        SYSBOOT.  To start with, the VMS kit will have to contain at least two
fO        OPdriver  images:   one  being the original OPdriver, supporting older
 O        Alpha systems and one being the redesigned OPdriver, supporting  Sable
 O        and  beyond.   The  former will continue to be named SYS$OPDRIVER.EXE.
oO        The latter will be named SYS$OPADRIVER.EXE.  When, in the future,  VMS

O        is  required  to  update  OPdriver's  hardware  interface  routines to
 O        accomodate new interface hardware,  then  additional  OPdriver  images
n0        (SYS$OPBDRIVER, etc.) will be required.
 
O        Since not all platforms will be supported by the new  design,  SYSBOOT
sO        will  need  to check the platform type and load the correct driver.  A
eO        change will be made to the code in SYSBOOT so that it  will  read  the
 O        SYSTYPE  field  in  the  HWRPB  structure  and compare it to a list of
 O        platforms that are not supported with the new  OPdriver  (see  Project
 O        Scope  section  of this spec).  If the system type is supported by the
 O        new OPdriver,  then  the  new  SYS$OPADRIVER  image  will  be  loaded.
 =        Otherwise, the original SYS$OPDRIVER will be loaded.
  
 
 
        3.2  Device Control
 
O        The console has also assisted OPdriver by  interfacing  with  a  modem
iO        device  attached  to  the  COM1 serial port and by providing interrupt
,:        control for the various console terminal devices.
 
 
 
O        3.2.1  Modem Control - The  current  OPdriver  uses  the  SET_TERM_CTL
 O        callback  to  set  the  modem's  output  signals  and  line parameters
lO        (character size, baud rate, etc.).  This will now be done by a  direct
 O        interface  within  OPdriver  to  the COM1 port registers.  The present

O        CTSR$SET_TERM_CTL macro will now  call  a  new  routine  in  OPdriver,
e        SET_MODEM_CTL.
a 
 
 
!        3.2.1.1  SET_MODEM_CTL -
e        Purpose:
 O          Set the modem device characteristics to agree with  those  specified
 /          in the Console Terminal Block (CTB).
h CR                                                                           Page 8
 
 
        Parameters:
          CTB (input) -
2            Address of the Console Terminal Block
 
        Description:
eO          Write to the Modem and Line Control Registers in the Combo  chip  to
OO          set  the  requested  characteristics.   Available  control bits are:
 O          word length, stop bits,  parity  select,  set  break,  DTR  and  RTS
s"          forcing, and baud rate.
 
        Returns:
/          STATUS -
a/            R0<0> = 1 on success, 0 on failure
 O            [NOTE:  The current OPdriver does not check the  pass/fail  status
.O            of any of the console callbacks.  Was there a good reason for this
b6            or did we just not know what to do here?]
 
 
 
O        3.2.2  Interrupt  Control - The  OPdriver  routines   CON$OWNCTY   and
hO        CON$RELEASECTY  provide  the means to turn interrupts from the console
tO        terminal devices  off  and  on.   OPdriver  disables  interrupts  when
eO        initiating  its polled mode of I/O and enables them in order to switch
fO        into interrupt-driven I/O.  Other facilities also use  these  routines
oC        when they need to control the console terminal interrupts.
  
O        In the current OPdriver,  the  CTSR$SET_TERM_INT  macro  dispatches  a
 O        request  to  the  console  to  change the interrupt state.  In the new
 O        OPdriver, CTSR$SET_TERM_INT will check which OPA unit number is  being
 O        referrenced  and  then  call  the  appropriate new OPdriver routine to
 O        service the request.  If the unit number is zero and the configuration
 O        serial,  then  OPdriver  will write to the device controlling the COM1
mO        serial port in the SET_INT_SERIAL routine.  Otherwise it will write to
6O        the  separate  device that controls the keyboard and mouse ports using
o&        the SET_INT_GRAPHICS routine.
 
 
 
"        3.2.2.1  SET_INT_SERIAL -
        Purpose:
 O          Enable or disable the Received Data Available or Transmitter Holding
cD          Register Empty interrupts from the COM1 port to OPdriver.
 
        Parameters:
          MASK (input) -
e-            00 = disable transmit interrupts
 ,            01 = disable receive interrupts
,            10 = enable transmit interrupts
+            11 = enable receive interrupts
. 
        Description:
 O          Control enabling of interrupts from COM1 port by writing to  bits  0
tC          or 1 of the Interrupt Enable Register in the Combo chip.
  
        Returns:
i          STATUS -
 /            R0<0> = 1 on success, 0 on failure
a nR                                                                           Page 9
 
 
$        3.2.2.2  SET_INT_GRAPHICS -
        Purpose:
 O          Enable or  disable  the  Output  Buffer  Full  interrupts  from  the
 /          keyboard or mouse ports to OPdriver.
  
        Parameters:
!          same as SET_INT_SERIAL
d 
        Description:
SO          Control enabling of interrupts from the keyboard by writing  bits  0
kO          or  1  of  the  Keyboard  Controller  Command  Byte  (KCCB)  in  the
 *          keyboard/mouse port controller.
 
        Returns:
o!          Same as SET_INT_SERIAL
  
 
 
        3.3  Polled I/O
 
O        For polled I/O, the current OPdriver sends a callback request  to  the
iO        console   which  then  attempts  the  desired  Get  or  Put  character
TO        operation.  If the returned  status  is  unsuccessful,  OPdriver  will
 O        usually  continue to issue the callbacks until the operation succeeds.
 O        In the new OPdriver, status bits can be checked directly  from  within
DJ        the driver and polled on until the operation is able to complete.
 
 
 
O        3.3.1  Polled Input - Polled input  is  provided  by  CON$GETCHAR  and
gO        CON$GETCHAR_NOWAIT.   In  the current OPdriver, these routines use the
aO        CTSR$GETC macro to dispatch a GETC callback to the  console.   In  the
iO        new OPdriver, CTSR$GETC will check the console configuration using the
aO        ALT_CONSOLE flag in the SYSG data block.  If it is found to be in  the
aO        graphics  configuration,  then GETC_GRAPHICS will be called, otherwise
O!        it will use GETC_SERIAL.

 
O        Incoming scan codes will need to be translated either by DECwindows or
iO        by  OPdriver.  Within the GETC_GRAPHICS routine, the state of the SYSG
sO        WIND_SYS_CONSOLE flag will be checked to see if DECwindows is up.   If
aO        so,  then the scan codes will be handed off to DECwindows as they are.
sO        Otherwise, OPdriver will call a new routine, TRANSLATE_KEY, to perform
 O        the  translation.   Within the GETC_SERIAL routine, TRANSLATE_KEY will
 9        be called regardless of the state of DECwindows.
t 
 
 
!        3.3.1.1  GETC_GRAPHICS -
y        Purpose:
iO          Attempt to get one character  from  either  the  keyboard  or  mouse
rH          ports.  Return status so that it can be checked when polling.
 
        Parameters:
          UNIT (input) -
e%            OPdriver OPA unit number
h          CODE (output) -
0            Address of scan code to be returned
 sR                                                                          Page 10
 
 
        Description:
 O          If UNIT=keyboard, check the Output Buffer  Full  (OBF)  bit  of  the
sO          Status  Register.   If  set  and  no  error bits are set, return the
e2          character from the data port (Port 60).
O          If UNIT=mouse, check the Auxiliary Device Output Buffer Full bit  of
eO          the  Status  Register.  If set and no error bits are set, return the
 2          character from the data port (Port 60).
 
        Returns:
           STATUS -
 @            R0<0> = 1 on character received, 0 on none received
3            R0<1> = 1 on read error, 0 on no error
h 
 
 
        3.3.1.2  GETC_SERIAL -
         Purpose:
dO          Attempt to get one character from  the  COM1  serial  port.   Return
h9          status so that it can be checked when polling.
  
        Parameters:
          CODE (output) -
0            Address of scan code to be returned
 
        Description:
rO          Check the Data Ready bit of serial port's Line Status Register.   If
dO          set and no error bits are set in that register, return the character

-          from the Receiver Buffer Register.
t 
        Returns:
           Same as GETC_SERIAL.
  
 
 
!        3.3.1.3  TRANSLATE_KEY -
i        Purpose:
cE          Translate the scan code received from the keyboard device.
  
        Parameters:
          CODE (input) -
n6            Address of the scan code to be translated
          CHAR (output) -
;            Address of translated character to be returned
e 
        Description:
sO          Not much detailed work has been done on this yet.  VMS has a copy of
iO          the  source  code for scan code translation done by the Digital UNIX
 O          group.  Hopefully, much of this code  can  be  reused  for  the  VMS
t          OPdriver.
 
        Returns:
i          STATUS -
c/            R0<0> = 1 on success, 0 on failure
n rR                                                                          Page 11
 
 
O        3.3.2  Polled Output - Polled output is provided  by  CON$PUTCHAR  and
bO        CON$PUTCHAR_NOWAIT.   In  the current OPdriver, these routines use the
rO        CTSR$PUTS macro to dispatch a PUTS callback to the  console.   In  the
rO        new  OPdriver,  CTSR$PUTS  macro  will check the console configuration
$O        using the ALT_CONSOLE flag in the SYSG data block.  If it is found  to
MO        be  Graphics  and  DECwindows  is  not  up, then PUTS_GRAPHICS will be
 4        called, otherwise it will call PUTS_SERIAL.
 
 
 
O        3.3.2.1  PUTS_GRAPHICS - To be specified at  a  later  date  by  Vince
         Husovsky.
 
 
 
        3.3.2.2  PUTS_SERIAL -
e        Purpose:
 O          Attempt to send a character or  string  to  the  COM1  serial  port.
n@          Return status so that it can be checked when polling.
 
        Parameters:
          STRING (input) -
 ,            Pointer to the character string
          LENGTH (input) -
e+            Length of the character string
y          COUNT (output) -
a9            Number of characters that were actually sent
R 
        Description:
 O          Check the Transmitter Holding Register Empty bit in the Combo chip's
rO          Line  Status  Register.If  set,  write  a  character  to  the port's
cO          Transmitter Holding Register.  Keep writing the remaining characters
 >          as long as THRE is set.  If not set, return status.
 
        Returns:
v          STATUS -
NO            R0<0> = 1 on character sent, 0 on not ready to send R0<1> =  1  on
h'            write error, 0 on no error
f 
 
 
"        3.4  Interrupt-Driven I/O
 
O        Interrupts to OPdriver are of an indirect type and, for the most part,
fO        are  handled  nearly the same as interrupts to other VMS drivers.  The
oO        main difference is that the OPdriver interrupt vectoring contains  one
 3        additional level (see illustration below).
c 
 pR                                                                          Page 12
 
 
                +-SCB--+
E                |      |
 0                |VECTOR|--------> IO_INTERRUPT:
                |PARAM |--.
'                |      |  |  +-ADP--+ 
r&                +------+  |  |      |
)                          |  |VECTOR|--.
a)                          |  |      |  |
e?                          `->| $VEC |--|-----> INTR_DISP_ICIC:
L)                             +------+  |
 3                                       |    VECTOR
 4                                       |  +-TABLE-+
4                                       `->|       |
4                                          |       |
G                                          | COM1  |---> COM1_DISPATCH:
mM                                          |       |       Check IIR register
 Q                                          |       |       If recv, JMP to @OP_RX
0Q                                          +-------+       If xmit, JMP to @OP_TX
 F                                                                    |
F                                                .-------------------'
5                                                |   
iB                                                |        +-CRB--+
B                                                |        |      |
B                                                v        |      |
B                                                         |      |
R                                              OP_RX: --->| INTD |---> CON$INTINP:
R                                              OP_TX: --->| INTD2|---> CON$INTOUT:
B                                                         +------+
 
 
 
O        OPdriver's interrupts are vectored through  one  additional  level,  a
KO        device-specific   dispatch   routine  such  as  COM1_DISPATCH  in  the
oO        illustration.  The dispatch routine checks  a  hardware  register  for
 O        specific  information about the interrupt, sets some flags in the SYSG
 O        data block, and then branches to  either  the  input  (CON$INTINP)  or
 9        output (CON$INTOUT) service routine in OPdriver.
  
 
 
O        3.4.1  Interrupt-Driven Input - When the interrupt comes into  INTINP,
 O        OPdriver  first  checks  the  SYSG flags that were set by the dispatch
sO        routine and determines the correct unit number  for  the  device.   It
nO        then  makes a callback to the console through CTSR$GETC.  As in polled
-O        I/O, the console also translates the received scan codes  if  it  sees
 3        that DECwindows is not available to do so.
  
O        The  new  OPdriver  will  also  route  interrupts  through  the   same
 O        device-specific  dispatch  routines  into  CON$INTINP,  determine  the
 O        correct OPA unit to fetch the input characters from, and then transfer
 O        control  to  the appropriate OPdriver GETC routine, either GETC_SERIAL
 O        if input is expected from the serial port or GETC_GRAPHICS if expected
aO        from  the  attached  keyboard (see sections 3.3.1.1 and 3.3.1.2).  The
SO        diagram below shows the flow for the handling of input  interrupts  in
t        the new OPdriver.
 
  R                                                                          Page 13
 
 
N               COM1_Dispatch         Keybd_Dispatch            Mouse_Dispatch
G                    |                      |                         |
 J                  INTINP                 INTINP                    INTINP
G                    |                      |                         |
eG                    |                   DECwin?------.               |
sG                    |                      |N        |Y              |
rG                    |                      |         |               |
eG                 config?-----.          config?-SER->|               |
eG                    |SER     |GRA          |GRA      |               |
 G                    |        |             |         |               |
kJ                  unit=0   error         unit=0    unit=2          unit=3
G                    |                      |         |               |
 G                    |                      |<------------------------'
h3                 COM1_GETC              KEYBD_GETC
e-                    |                      |
o-                    `--------------------->|
a?                              unit<3 & !(unit=2 & DECwin)?---.
 @                                           |Y                |N
?                                           |                 |
r?                                      TRANSLATE_KEY          |
o?                                           |                 |
r?                                           |<----------------'
 /                                          etc.
  
 
 
 
O        3.4.2  Interrupt-Driven Output - The only output to OPdriver  that  is
rO        driven  by  interrupts is to the COM1 serial port.  COM1_DISPATCH sets
dO        flags in the SYSG data block to indicate that the serial port is ready

O        for  output from OPdriver.  The CON$INTOUT routine in OPdriver figures
 O        out the specific type of operation desired and uses CTSR$PUTS to  have
PO        the console execute it.  The new OPdriver will have CTSR$PUTS call the
 ?        new PUTS_SERIAL routine instead (see section 3.3.2.2).
  
 
 
        3.5  Synchronous I/O

 
O        In the graphics console configuration, output to the console  terminal
eO        device is synchronous and does not require the use of interrupts.  The
nO        entry point into OPdriver is at CON$STARTIO which is retrieved by  the
aO        class driver from OPdriver's port vector table.  This then branches to
cO        DO_SYNC_OUT in OPdriver to handle the synchronous  output  of  one  or
 O        more  characters.   CTSR$PUTS is called from DO_SYNC_OUT which, in the
 O        new OPdriver, will call the  new  output  routine  PUTS_GRAPHICS  (see

        section 3.3.2.1).
 
 
 
2        3.6  Initial Preparation And Cleanup Work
 
O        Since the OPdriver facility has had numerous maintainers over time, it
$O        has  acquired  a  somewhat interesting but not all too clear structure
 O        and  content  in  some  places.   This  could  do  with   a   bit   of
gO        reorganization  and  cleanup,  most  of  which should not require much
GO        significant labor.  Also, the majority of the facility will be  ported
e oR                                                                          Page 14
 
 
O        from  Bliss  to  C.   What  follows  is  a  list of suggested redesign
3        preparation tasks.
  
 
O        - Port all OPdriver code to the  C  language  with  the  exception  of
tO        jacket  routines  needed  to  specify explicit linkage.  These will be
 :        done in Macro.  This work is already in progress.
 
O        - OPdriver currently consists of two variants within the  main  source
eO        module.   To add clarity to the code, the CONIO variant will be made a
rO        separate module instead.   This  module,  when  compiled,  will  still
sO        produce  the  CONIO object file which will be linked directly into the
R5        APB and SYSBOOT images, as it is done today.
c 
O        - There are a number of routines in OPdriver that appear to be  either
 O        null  or  unused.   These  should be evaluated and then removed if not

7        needed.  How many of these do anything useful?
e 
O          CON$SENDCONSCMD - Used by [ERRFMT]ERRSNAP to "send  command  to  the
oF          logical console." Routine just includes a RETURN statement.
 
O          CON$STOP - OPdriver's vectored STOP routine to "stop all  output  to
eO          the  console  terminal".   Routine just includes a RETURN statement.
rO          CON$STOP2 - Same as CON$STOP, except it is supposed to  stop  output
 K          for just two seconds.  Routine just includes a RETURN statement.
  
O          CON$OPWINVISIBLE/CON$OPWINUPDOWN - Just does  a  RETURN  SS$_NORMAL.
 /          Are these used in the graphics code?
R 
O          CON$OPSAVETERM/CON$OPRESTORETERM   -   They're   supposed   to    be
 O          save/restore  state  routines,  but  all  they  do  is  a  PAL_HALT.
 K          Routines are commented as, "This is a null routine for present."
  
4          OPdriver macro CTSR$RESET_TERM is unused.
 
 
O        - For CPU0302 (Ruby) and CPU0C05  (TLaser)  ,  the  *LSBPOWER  modules
 O        define   their   own  versions  of  the  OPdriver  CTSR$SET_TERM_INTR,
 O        CTSR$PUTS, and CTSR$GETC macros for power event logging.  Whatever the
 O        reason  was  for creating two versions of these macros, can we now use
 O        just one common set?  Otherwise, TLaser will still be relying  on  the
 #        console callback routines.
  
O        - There are also some instances of two routines that perform the  same
 O        operation.   For  example, CON$OWNCTY and CON$SAVECTY perform the same
 O        function.  Modules in the SYS facility use CON$OWNCTY while modules in
-O        DELTA  and DDTM use CON$SAVECTY.  Duplicate routines should be removed
 #        and calls made consistent.
  
O        - The handling of OPA unit  numbers  within  OPdriver  is  done  in  a
 O        confusing  manner  in  a  number of places.  This should be cleared up
         wherever possible.
  
O        - There are four separate OPdriver routines to handle  output  to  the
-O        console  terminal devices and there is a good deal of code duplication
|O        within these modules.  This should be simplified wherever possible  so
-5        that the procedure is more straight-forward.
o  R                                                                          Page 15
 
 
O        - There is conditional support for specific systems in some places  in
aO        the  code.   This includes the Flamingo, Jensen, Cobra platforms, none
eO        of which are not to be supported in the new OPdriver.  These  specific
e/        platform statements should be removed.
I 
O        - References to the Mannequin simulator should all be removed from the
p        code.
