> doc


Parallel device driver within RISC OS 3
---------------------------------------

This module provides the parallel device support within RISC OS 3.  The
module is a client of DeviceFS and can be access via that system.

It will setup PrinterType$1 to point at its DeviceFS object, ie:

        PrinterType$1 => devices:$.Parallel

The "parallel:" device can be opened for output (eg. to a printer) or input
but not for both.  The input stream is only available on machines which use
an 82C710 or 82C711 controller.

The output stream uses standard parallel printer handshaking and can send
data to many types of printer.  In the absence of any standard parallel
input protocol the input stream has been provided mainly as a means of
passing data between one machine and another (eg. downloading data from a
portable to a master machine).  The input device driver behaves like a
printer and can therefore accept data from another machine which is
"printing" from its parallel port.  To enable such data transfer a twisted
cable must be made with the following connections:

        Pin     Signal  Direction               Pin     Signal  Direction
        1       /STROBE O                       10      /ACK    I
        2       DATA 0  I/O                     2       DATA 0  I/O
        3       DATA 1  I/O                     3       DATA 1  I/O
        4       DATA 2  I/O                     4       DATA 2  I/O
        5       DATA 3  I/O                     5       DATA 3  I/O
        6       DATA 4  I/O                     6       DATA 4  I/O
        7       DATA 5  I/O                     7       DATA 5  I/O
        8       DATA 6  I/O                     8       DATA 6  I/O
        9       DATA 7  I/O                     9       DATA 7  I/O
        10      /ACK    I                       1       /STROBE O
        11      BUSY    I                       17      /SLCTIN O
        17      /SLCTIN O                       11      BUSY    I

Either end of such a cable can be connected to a sending or receiving
machine.  Note that sending (ie. "printing") machines do not need to be
Acorn products so the parallel input device can be used to transfer data
from a PC for example.

To send data, the "parallel:" device should be opened for output as if it
were a file.  Data can then be written to the open device which should be
closed when no more data is to be sent (*copy <file> printer#parallel:
already does this).  At the receiving end the "parallel:" device should be
opened for input, the bytes should be read and then the device should be
closed.

The module also supports two SWIs:

SWI Parallel_HardwareAddress (&42EC0)

This call has been superceded by SWI Parallel_Op and should no longer be
used.

On entry:       -

On exit:        r0 = base address of 82C710/82C711 in IOEB space
                     or 0 if no 710/711 is present
                r1 = address of routine which can be called to update the
                     82C710/82C711 control register

Use:            This call was originally provided to allow external authors to
                drive the 82C710 directly.  This call is no longer required but
                remains so that software which already uses it will still work.
                The Parallel_Op SWI should now be used instead.


SWI Parallel_Op (&42EC1)

Low level parallel operations (only available with 82C710/82C711).  This SWI
will return an error if the correct hardware is not available.

On entry:       R0 = reason code
                other input registers as determined by reason code

On exit:        RO preserved
                other registers may return values, as determined by the
                        reason code passed

Interrupts:     Interrupt status is undefined
                Fast interrupts are enabled

Processor Mode: Processor is in SVC mode

Re-entrancy:    Not defined

Use:            This is a single call with many operations within it.  The
                operation required, or reason code, is passed in R0.  It can
                have the following meanings:

                * R0 = 0 - Read data and status registers
                * R0 = 1 - Write data register
                * R0 = 2 - Read/write control register

Related SWIs:   OS_ClaimDeviceVector, OS_ReleaseDeviceVector

Related vectors:None


SWI Parallel_Op 0

Read the parallel data and status registers.

On entry:       R0 = 0

On exit:        R0 preserved
                R1 = contents of the parallel data register
                R2 = contents of the parallel status register

Use:            This call is used to obtain the current state of the parallel
                data lines and the status register.  The bits in the read only
                parallel status register correspond to the following inputs:

                Bits 7-0
                ____    ___                     _____
                BUSY    ACK     PE      SLCT    ERROR   rsvd    rsvd    rsvd

                Bits 8 to 31 of R2 are undefined.  See the 82C710/82C711 data
                sheet for a description of these bits.  If the DIR bit in the
                parallel control register (see below) is 0 (ie. output) then
                the contents of the data register will be the same as the last
                data value written.  The data register is read after the status
                register.


SWI Parallel_Op 1

Write the parallel data register.

On entry:       R0 = 1
                R1 = data

On exit:        R0 preserved
                R1 preserved

Use:            This call is used to write a byte to the parallel data lines.
                This will only have an effect if the DIR bit in the parallel
                control register is 0 (ie. output).


SWI Parallel_Op 2

Read/write the parallel control register.

On entry:       R0 = 2
                R1 = XOR mask
                R2 = AND mask

On exit:        R0 preserved
                R1 = old contents of the parallel control register
                R2 = new contents of the parallel control register

Use:            This call is used to read or write the current state of the
                parallel control register.  The new state is determined by:

                        New state = (Old state AND R2) XOR R1

                The bits in this value correspond to the following outputs:

                Bits 7-0
                                                ______  ____    ______  ______
                rsvd    rsvd    DIR     IRQEN   SLCTIN  INIT    AUTOFD  STROBE

                Bits 8 to 31 are undefined and must not be modified.  See the
                82C710/82C711 data sheet for a description of these bits.
                These lines are output only but their current state can be read
                without changing them by setting R1 = 0 and R2 = &FFFFFFFF.  The
                interrupt enable bit, IRQEN, should normally be 1 and interrupt
                disabling should be done in IOC.
       

This call is provided to allow external authors to drive the 82C710/82C711
for themselves.  If the hardware is to be driven directly using this SWI
then the following should be performed:

        lock = OPENOUT("parallel:")

        .... play around with hardware....

        CLOSE#lock

This will stop any other application opening the parallel device and
altering the values which have been set up.
