    


Version 0.93  Dec. 1995


    
                     --OS/2 PI Card Driver Docs-- 

                    by Dale A. Heatherington, WA4DSY   
    			wa4dsy@wa4dsy.radio.org
                      http://www.wa4dsy.radio.org
    
    
    PI2DRVR.SYS is an OS/2 physical device driver (PDD) for the Ottawa PI high 
    speed packet interface card.  It provides automatic detection and support 
    of both the original PI card and the newer PI2 card.  This driver supports 
    both the A and B channels.  The A channel transfers data by DMA and will 
    run at speeds of 56 KB and higher.  The B channel is interrupt driven 
    which limits the maximum speed to about 19200 bps on a 486-33.  Some 
    transmitter underruns will occur at 19200.  This driver is all you need to 
    run PMNOS 1.2 or higher.    
    
    VPI2.SYS is an OS/2 virtual device driver (VDD).  It allows DOS programs 
    access to the physical device driver, PI2DRVR.SYS.  Only one PI card is 
    supported in this mode.    
    
    PI.C is a modified PI card driver for JNOS which allows it to access the 
    virtual device driver VPI2.SYS.  It must be compiled into JNOS as a 
    replacement for the original JNOS PI.C.    
    
    
    Quick start examples:    
    
    1.Copy PI2DRVR.SYS and VPI2.SYS to your hard drive.    
    I suggest putting them in the directory with your    
    other tcp/ip software.    
    
    
    2.Add the following lines to your config.sys, assuming    
    the PI card is jumpered for IRQ 5, port 0x300,    
    DMA channel 1, you want 512 byte buffers and the    
    drivers are in your c:\nos directory.    
    
    DEVICE=C:\NOS\PI2DRVR.SYS PI0 5 0x300 1 512    
    DEVICE=C:\NOS\VPI2.SYS    
    
    The syntax of the parameter list is:    
    
    PI2DRVR.SYS <name | name1$name2> <IRQ> <I/O port> <DMA>    
                      <Buffer size> [<Number of buffers>]    
                   [<A ch. Speed>] [<A ch. clk mode>]    
                   [<B ch. Speed>] [<B ch. clk mode>]    
    
    note: Items in <> must be supplied. Items in [] are optional.    
              If a single name is supplied the driver will append    
              "A" and "B" to the name.  If two independent names    
              are desired enter them with a "$" as a separator.    
              The names must match the names supplied in the attach    
              pi statement in AUTOEXEC.NOS.  The other parameters    
              are described in more detail later in this document.    
    
    
    3.Add the following line to you AUTOEXEC.NOS file.    
    
    attach pi 0x300 5 1 ax25 pi0 512 512 0 9600    
    
    assumes: A channel set for external clock.    
                 B channel set for 9600 bps internal clock    

    





                 Interface names are pi0a and pi0b.    
                 There are several other PI related parameters    
                 in autoexec.nos.  See NOS and PI card    
                 documentation for details.    
    
    4.Reboot.    
    
    5.You may now run PMNOS 1.2 or higher or JNOS110i which has    
    been compiled with a PI driver modified for use with VPI2.SYS.    
    
    
                          --Technical Notes--    
    
    When loaded, the driver looks like a file named "pi0a" or "pi0b" to the 
    operating system.  Any C language functions which read or write files can 
    send and receive data to and from the driver.  The receive routines must 
    be a separate thread because the driver blocks until a packet is received.  
    A non-blocking mode is provided for use with DOS applications which may 
    access the driver through the virtual device driver VPI2.SYS.  See source 
    code for details.    
    
    Data written to the driver will be transmitted as soon as the channel is 
    idle and the txdelay has expired. Writes don't block unless all the buff-
    ers are in use. When this happens the write operation will block until a    
    buffer becomes available.    
    
    The driver can be crudely tested by doing a copy from console to pi0a.    
    
    C:>copy con: pi0a <cr>    
    This is a test ^Z <cr>    
    
    That should send out a frame containing "This is a test"    
    
    
    C programmers take note:    
    In C the buffer must be flushed after each write else    
    several writes will be placed in one packet.    
    
    fwrite(&data,1,datasize,f);    
    fflush(f);    
    
    OS/2 system call DosWrite() doesn't need a flush.    
    
    
    
    
    
                  --Command Line Parameter Details--    
    
    
    
    
    Example from config.sys:    
    
    device=C:\nos\pi2drvr.sys pi0 5 0x300 1 512 12 9600 1 1200 0    
    
    There are 10 parameters.  You must supply the 1st 4. The last 6 are 
    optional if defaults are acceptable. The last 4, speed and clock mode, are 
    usually supplied by the application program. The number of buffers an 
    buffer size can't be changed after OS/2 boots.    
    
    1. pi0    
       Device driver name.  The length must be 7 characters or less.    
       This is the base name the system will use to access the driver.  If    
       two drivers are installed they must have different names as well    
       as interrupts, ports and DMA channels.  An A or B will be appended.    

    





    
       example: device=pi2drvr.sys pi0 5 0x300 1 9600 1 1200 0    
                device=pi2drvr.sys pi1 7 0x320 3 0 0 1200 0    
    
       If one name is supplied as in the above examples, then "A" and "B"    
       will be appended.  The A channel driver will be "PI0A" and B will    
       be "PI0B".  If you enter "pi0a" the name will be "pi0aa".    
    
       If you want to have independent names enter them with a "$"    
       between them.    
    
    device=C:\pi2drvr.sys hispeed$lospeed 5 0x300 1 0 512 12 9600 1 1200 0    
    
    Creates two names - "hispeed" for A channel and "lospeed" for B channel.    
    The A or B suffix will not be appended.    
    
    2. 5    
       The hardware IRQ for the PI card.    
       valid range: 2 to 7    
       default: 5    
    
    3. 0x300    
       The I/O port base address for the PI card.    
       valid range: 0x300 to 0x380 in steps of 0x20    
       default: 0x380    
    
    4. 1    
       DMA channel for PI card    
       valid range: 1 to 3    
       default: 1    
    
    5.   512    
         Buffer size    
         valid range: 128 to 3072    
         default:     2088    
    
    6.  12    
    Number of buffers.  They are divided between the A and B channels.    
          The receiver and transmitter use the same buffers. If number is    
    odd the A channel will have one more buffer than the B channel.    
    
              valid range: 8 to 15    
       default:     15    
    
    Items below are optional if set by application program.    
    
    7.  9600    
         Baud rate for channel A.  Set to ZERO for external clocking for    
         the WA4DSY 56KB modem.    
         Valid range 0 to 57600    
    
    8.  1    
         Clocking mode for channel A.    
         "0" is normal.  "1" is G3RUH 32x clock mode.    
    
    9.  1200    
         Baud rate for channel B.    
    
    10  0    
              Clocking mode for channel B.    
    "0" is normal.  "1" is G3RUH 32x clock mode.    
    
    If no value is given the default is used.    
    
    ***Note:  If the "B" channel is not used, you should
              set the speed to either 1200 or 9600 but not zero.
              Setting the speed to zero enables external clock
              which is not connected and noise on the clock
              line can cause strange symptoms such as lockups.
    

    





    
    
    
                    --Virtual Device Driver Docs--    
    
    
    
    VPI2.SYS is a virtual device driver which enables DOS programs to access 
    the physical device driver using software interrupt calls.  All calls use 
    INT 7D hex.  See VPI2.C and PI.C source code for more details.  Only one 
    DOS session at a time can use the driver. It DOES NOT virtualize PI card 
    hardware.  If you plan to use JNOS you must replace the DOS PI card driver 
    with a version designed for use with this driver.   I've included a  
    replacement driver with this package.  See PI.C and PI.H .    
    
    By not virtualizing PI card hardware I both saved a lot of development 
    time and produced a driver which is much more efficient, generating only 
    one DOS interrupt for each received packet.  The IRQ number is the same as 
    the IRQ parameter passed to the PDD in the device= statement in config.sys 
    but has no other logical connection.    
    
    This driver only supports a single PI card.  It may be possible to support 
    two cards using two sets of drivers, one set for each card.  The second 
    Physical Device Driver needs to have a different internal name to prevent 
    any conflicts with the first driver.  See the PddName variable in 
    PI2DRVR.ASM and szPDDName in VPI2.C . This is the name used by the VDD to 
    find the mating PDD.  The Virtual Device Driver will also need to be 
    assigned a different software interrupt number.  If this is done, PI.C 
    needs to be changed to support two cards/drivers.    
    
    
    The replacement PI driver for JNOS does everything the original does plus 
    it can change the speed of the interface using the param 10 command.    
    
    Example:  param pi0b 10 9600    set pi0b to 9600 bps.    
    
    
    
    
    3-9-95    
    
    Dale Heatherington, WA4DSY    
    wa4dsy@wa4dsy.radio.org    
    daheath@ibm.net    
    
