These notes are designed to use with the PCShare executable marked V3.x. PC- Share V3.1 & 3.2 is available for MS-DOS and MS-Windows 3.1, Windows 95 and Windows NT. These notes refer to both versions, any specifics to either DOS or Windows are marked [DOS] or [WIN]. Specific Windows variants are marked [WIN16] - Windows 3.1, [WIN95] - Windows '95 and [WIN32] - Windows NT.
PCShare's object in life is very simple - to share a PC with another computer. In principal that 'other' computer can be any machine under the sun that can interface to the outside world and the software can be written for it. However, in reality the only support software existing to communicate with it runs under OS9, and has only been trialed out on a Dragon 64. Whilst in theory, the software can be written for any platform, in reality it comes down to the feasability of the operating system on that machine. OS9 was designed to be expanded and support additional devices and hardware, and is therefore easy to seamlessly integrate the PC Share software into it, whilst DragonDOS on the other hand was not designed in such a fashion, and the software becomes that much more complex requiring the use of additional commands to implement the interface.
PCShare 3.x offers the sharing of a PC's VDU, keyboard, hard disk, floppy disk and just about any device or drive that MS-DOS (or MS-Windows) can talk to.
Throughout the remainder of these notes, the 'other' computer is assumed to be a Dragon using the PC Share OS9 device drivers.
See the PC-Share FAQ on my web site for help on using PC-Share with another
machine.
PCShare uses a single 8-bit parallel interface to communicate with the outside
world. The following interface options are available:
Any combination of this interface may be utilised, and in addition PC and OS9
development kits are available for the creation of new device drivers.
At present, the drivers to use the Dragon's parallel printer port are not
available, they are currently being developed. The printer port driver
solution should not be used if you intend to use the Dragon's own keyboard
over the PC's one due to it sharing the printer port data lines.
The following signals are required for the link:
PC Intel 8255 - Using 'B' side of chip
Note: Using anything other than the 'B' side will require the software drivers
to be modified.
PC LPT port
Note: Your LPT port must be one of the variety which support 'byte mode'
operation (not to be confused with EPP/ECP). Most of the newer machines do but
early PC/XT machines are not likely to.
MC6821 - Using 'A' side of chip
Note: Using anything other than the A side of the chip will require the OS9
drivers to be re-written.
Dragon Printer Port - click Here for details on the hardware
modifications required
Note 2: OS9 Device drivers for this link are not yet available
A PC-Share link is achieved by wiring the cable as follows:
For example, an 8255 to 6821 link would be achieved as follows:
The PCSHARE3.ZIP file consists of the following:
Create a separate directory on your hard disk, and unzip the files into the
new directory.
The Windows NT version can also run under Windows 95 by using the VXD
described above.
IO Port address - the base address of your parallel card.
No. Of Hard Disks - the number of unique hard drives you wish to have access
to (up to 10). Each one would be treated as a unique drive (eg.in MS-DOS
terms, C:, D:, E: etc.).
Hard Disk sector size - size of each sector on the virtual hard disk - 256 for
OS9.
Path to PCShare - enter the directory name to the PCShare directory.
Terminal Emulation - the default screen emulation PC-Share will perform: None,
DEC VT100 or Dragon OS9/GO51.
[DOS]
[ALL]
The PCShare executable should only be run once the Dragon is powered up - a
blank screen printing out loads of spaces indicates the Dragon's either not
powered up or the connection isn't working. The Windows version will almost
certainly lock your machine up if this occurs.
The PC-Software is now sucessfully installed.
[DOS]
The OS9 software is held in OS9 AR archive format:
Download the appropriate file for your PC interface.
The following software interfaces OS9 to all of PCShare's capabilities:
Programs and Utilities:
Data files/definitions files
The installation procedure mostly involves setting up a new OS9 Boot disk, and
altering the device descriptors to suit your PIA base address.
First, extract all of the files from the archive into a temporary area on your
floppy or RAM disk - assumed to be /D1.
H0 and PC device descriptors need the device base address at offset $0F:10
changing to your PIA address. A binary file modifier such as 'debug' or 'zap'
can be used to accomplish this. The verify with 'U' option can then be used to
correct the CRC. H0 will also need the size of the hard disk edited using the
'dmode' utility. The device descriptor is preset to 256 sectors per track
(64K), and the track count set to 640 (40MB). A binary file editor may also be
used to modify the track count figure at offset $17:$18.
The WIN1 device descriptor will also need the device base address entering
into it, but this should be entered 1 byte earlier at $0E:0F.
[WIN]
[ALL]
The first thing you'll need to do is format your hard drive copy on your
files.
BOOT up OS9 on your existing system, ensuring that you interface to the PC is
made. Launch the PCSHARE executable and under OS9 type:
Formatting will take some time (40MB = aprox an hour) as the format utility
will always verify hard disk sectors after a format.
You can then copy all your files and data onto the disk as you would any
floppy disk.
Next you'll need to create a new floppy boot disk (PC Share doesn't let you
BOOT OS9 from hard disk - yet) which automatically defaults to using /H0 as
your default disk, and includes the new video driver. First pull off all the
modules from your existing boot file that you want to keep, either using SAVE
or RIP and delete the following: SYSGO, KBVDIO, TERM, DDISK.
The following files new files from the PCShare archive should be included:
SYSGO, WINDRV, WIN1, DDISK.
Whether or not you include PCSBF and the associated drivers (BPIA21, PC) which
allow direct MS-DOS file access is up to you - personally I load them when I
want to use them.
Prior to creating your new boot file with OS9GEN, use the GO utility to update
the INIT module with the new one.
This is because INIT is not included in the boot file, OS9GEN will pull it out
of RAM for the new disk.
Use OS9GEN to create the new boot disk. Reset the Dragon, and try booting from
this new disk. If all is succesful the following should occur:
[WIN]
[ALL]
PC-Share is now succesfully installed onto your system. The paths /H0 and
/H0/CMDS are now used as your default data/execution directories and you can
begin setting up your hard disk.
The file 'WinStartup' replaces the 'Startup' procedure on /H0 - although to
all intensive purposes the contents can be the same. Remember to replace all
references of '/TERM' with '/WIN1' however.
It is advisable to copy all the PCShare System Modules, Programs and utilities
into the /H0/CMDS directory and the data files into the /H0/DEFS directory.
This section covers how PC-Share interacts with OS9. As both PC-Share for DOS
and Windows come with on-line help it does not cover the specifics of using
each application.
The DOS version opens with a copyright notice and a blank screen. All OS9 text
is displayed on the screen as per any DOS application. On-screen menus may be
activated by pressing the 'Alt' key and selecting from the menu list
displayed. 'Alt-F1' activates the on-line help which describes each menu
option and it's capabilities in turn.
The Windows version displays the PC-Share control window which allows PC-Share
settings and window management to be controlled. Only when OS9 boots up is a
text window opened, which subsequent text and graphics are displayed in. On-
line help is available from the 'help' menu or by pressing F1 when the Control
Window is selected.
[ALL]
All output from OS9 is now sent to the PC's screen (or window) via the WINDRV
device driver. All terminal emulation and grahics capabilites are performed by
the PC.
To select one of the 2 emulation modes use the PCCFG utility with the -e
option:
Dragon OS9 GO51 emulation provides support for Dragon OS9 utilities which use
the GO51 escape codes for screen emulation such as Stylograph and Dynacalc.
To change the text colour and background, use the PCCFG utility with the -c
option:
The colours available are listed under the following section - 'Graphics
Utilities' under EGA/VGA colours. Note that only the first 8 colours may be
used for background.
[DOS]
A new GFXE modules enables access to the PC's graphics modes, including a VGA
scaled PMODE 4 emulation mode. The command structure is almost identical to
the old GFX/GFXE interface - identified in Appendix D of the Basic09 Dragon
manual, with the following differences:
ALPHA, QUIT, GLOC and JOYSTK are not supported. Neither are the LOAD, SAVE and
HARD options of GFXE.
Two versions of GFXE are contained within the archive: one for DOS and one for
Windows. The relevent one should be renamed to just GFXE and copied to the
CMDS directory.
The MODE command selects the graphics mode from the list below, the colour
parameter is at present ignored, but must be specified in the command:
[DOS]
[WIN]
Once activated, GFXE creates a 256*192 (standard PMODE 4 size) bitmap scaled
in the current window. This means the graphics drawn will be shrunk or
expanded to fit the active window size. Sixteen colours are selectable in this
mode, corresponding aproximately to the 16 VGA colours available in the DOS
version. Whilst GFXE usses 256*192 this is not a limitation of PCShare, the
interface allows any reasonable size bitmap display to be created.
[ALL]
[DOS]
- for monochrome/2 colour modes a palette value of 0 indicates black, and any
other number indicate white or the other colour the card/monitor is capable of
displaying.
- for CGA modes, the colour values available depend on the palette selected
(either C0, C1, C2 or C3 - see Graphics Mode descriptions).
[ALL]
When a graphics mode is selected, text can still be displayed.
[DOS]
[DOS]
The DC utility enables DOS commands to be forked from MS-DOS. The utilty
passes the string specified after the DC command to PCShare which is then
passed to COMMAND.COM for execution eg.
[ALL]
The files PCSBF, BPIA21 and PC must be LOADed in order to access DOS files and
devices. DOS files can then be accessed transparantly using existing OS9
utilities.
Any pathlist prefaced by the /PC device descriptor will identify that the
following pathlist is intended to be passed to the PC for processing. However,
in order to maintain OS9 pathlist conventions, OS9 separators and identifiers
must be used. Fortunatly these are very similar to their MS-DOS counterparts,
the major difference being the use of the '\' character as a directory
separator. So C:\FILES\TESTFILE.DAT should be specified using OS9 naming
conventions as c:/files/testfile.dat.
The 'list' utility may be used to list DOS files eg.
The '/pc' part identifies the PC device descriptor, the remainder the DOS
pathname. The PC's printer may also be used to print OS9 files using the
standard re-direction operators:
Files may be copied using the copy command:
copies the file basic09 to PC and vice-versa:
The OS9 CHD and CHX commands can also be used to change to DOS directories:
Changes to the DOS directory on the C: drive. Now files can be specifed
without using full paths:
provides a hex listing of the PC file command.com. The standard directory
specifiers may also be used eg.
to step back a directory. However the OS9 convention:
to step back 2 directories won't work on a DOS system, instead use the DOS
format of:
Once you are 'on' a DOS device, you no longer need to specify the /pc in any
pathlist for example:
can be used now. Likewise, a DOS file can be copied to another DOS file if so
required:
You can also delete DOS files using the OS9 'del' command and create new
directories using 'makdir':
DOS directories should be deleted using 'del' not 'deldir'. The PCSBF manager
first uses 'delete-file' on the pathlist specified, which if it fails will
then try 'delete-dir'. Like OS9, a DOS directory must be empty for the delete
to succeed.
There are some commands you cannot use, which assume all disks are under
control of the RBF file manager. These require direct access to the disk for
sector read calls which PCSBF cannot support, and even if it did DOS disks are
stored in a completly different manner to OS9 disks. An example of this is the
OS9 'rename' command which cannot be used rename a DOS file. Neither can the
'attr' command be used, to change a files attributes. A special case has been
catered for within PCSBF, that of reading OS9 directory files. This allows
basic directory utilities such as 'dir' and 'd' to be used on DOS disks. It
should also allow 'batch' file copiers to work such as 'dsave' & 'dircopy'. It
will not however support the extended format of dir - 'dir e' which again
requires direct disk access to function correctly.
OS9 File Managers support two operations which correspond to the system
requests OS9I$Write/OS9I$Read to write or read data from a file or device
(binary mode) and OS9I$WritLn/OS9I$ReadLn to write or read a text line with
editing (text mode) and this is maintained within the PCShare program. Binary
mode transfers between DOS and OS9 are straigtforward as the file copied is
identical (using the OS9 copy command). However, DOS and OS9 text files differ
in that OS9 text files are terminated with a carriage return (CR) only, whilst
DOS files use a carriage return/line feed pair (CR/LF). When using text mode
transfers, with ReadLn/WriteLn this difference is not apparant as PCShare will
read a DOS line of text. That way the 'list' utility can successfully display
the AUTOEXEC.BAT file for example. However, if you were to then copy the
AUTOEXEC.BAT file to an OS9 file (using copy) and then list it you would find
a blank line between every line of text, as the line feed characters would be
left in. Going in the opposite direction is worse, and by using the DOS 'type'
command to display an OS9 text file transferred to PC would dump every single
line on top of the previous one as no line feeds are present.
This problem can be avoided, either by performed text file transfers using the
'list' utility and re-directing the output to ensure the Readln or Writln
requests are passed on to PCShare, or by using one of the many OS9 filters to
add or remove line feeds from text files. Ones I have are 'addlf' to add line
feeds and 'lf' to remove them. The modified files can then be copied to DOS.
One of the side effects of the automatic conversion of text files by PCShare
comes with the WritLn request, as PCShare has to effectivly add an extra
character to the file (the line feed). This means that any OS9 utility which
is trying to manually keep track of a file pointer will become confused.
This version of PCShare does not support multiple 'current directories' which
OS9, because of it's multi tasking ability requires. This can be seen if you
use CHD and CHX to change to new directories:
sets the current DOS directory to c:\dos
will re-set the current DOS directory to c:\windows
Attempting to then access a file in the C:\DOS directory via:
will fail as the current directory is now C:\WINDOWS
Problems will also occur if multiple tasks are running and they issue change
directory requests to PCShare. Future versions should remove this limitation.
Long filename are supported within the 32-bit versions of PCShare with some
limitations. Firstly, OS9 is limited to a maximum of 29 characters for a
filename - under 95/NT it is 255 therefore some naming truncation will occur
when a directory displaying files with names greater than 29 characters. The
full name can still be specified when accessing individual files.
Windows supports a far more flexible naming system than does OS9, therefore
filenames and directories not conforming to the OS9 filename syntax will
generate an error. In particular this will include spaces and files starting
with numbers. This is unlikely to change in the future as tradionally spaces
are used to separate command line parameters in OS9.
PCSBF allows access any MS-DOS device besides hard and floppy disk, such that
printer port (LPT) or serial port (COM) devices may be accessable. This is
achieved simply by specifying a COM or LPT device ie.
However, it is a well documented fact that COM port access through MS-DOS is
prone to problems particularly on reading the ports and as such PC-Share
includes dedicated software for using COM ports.
PCShare also adds interfaces for configuring and using COM ports avoiding the
DOS interface and the problems this involves. Up to four COM ports can be
setup within PCShare - through OS9 this is achieved by the PCCFG utility using
the -R option:
c=Port ID (1-4)
COM ports can be opened in two different modes, this is distinguished by the
filename given to PCShare:
- filespec is 'COMn'. Filename is treated as per any other filename and is
opened through DOS. The COM settings used are those from the last DOS MODE
command or equivalent. This is exactly how all prior releases of PCShare will
work and should be sufficient for serial printers.
- filespec is 'COMn:'. PCShare handles data flow to/from the port itself using
the configuration for the port configured by the host PC (as above). The new
serial port handling features become available allowing asyncronous
communications to occur, however only 1 port can be open at a time in this
mode. Changes to the configuration will not take affect until the port is
closed. The port should always be closed prior to quitting PCShare to allow
the interrupt vectors to be restored.
The new PCSBF driver caters for this, and should allow any Comms package to
work with it eg. XCom9 as follows:
The GetStat call SS.RDY is implemented, for serial devices it returns a
ready/not-ready status and for all other files returns a not-ready status.
Problems: Unfortunatly the amount of IO overhead incurred just to receive 1
character from the serial port is such that the throughput on the Dragon is
barely 1200 baud regardless of the PC COM port settings. This of course makes
the link almost useless, not only in terms of buffer overruns on the PC side
but in terms of usability and file transfers. In order to alleviate this
problem, the PCSBF file manager would have to perform larger block transfers
and buffer the data on the OS9 side - involving all sorts of complications and
a substantial piece of extra code. My feeling at the present time is that this
would be a little used feature anyway so I don't intend to make these changes.
However, I will leave the interfaces in the software should the situation
change in the future.
As a 'stop-gap' to this problem, to allow user software fast access to PC COM
ports, the 'Get File Size' GetStat call has been extended in PCShare to return
the number of characters in a COM port queue if a serial device is specified.
This allows for block reads by a dedicated terminal program. I have included a
very simple one as part of the OS9 drivers set called PCTERM. This is of
course not compatible with serial device drivers using SCF.
You are immediately in terminal mode, ie. characters sent/received from the
COM port. Press 'Esc' to exit, CTRL-T to send an ASCII file, CTRL-R to
capture/receive an ASCII file and CTRL-X to fork an OS9 shell.
[WIN]
PC-Share allows direct access to the MS-Windows clipboard as an MS-DOS device
named 'CLIP:'. Files may be copied to/from the clipboard in the usual manner
eg.
The contents of the file startup will be placed onto the Windows clipboard
where it can be pasted into any other windows application.
The contents of the clipboard may also be viewed:
The same rules apply to the CR/LF conversion required for DOS files identified
previously. You should only copy text files to the clipboard, adding the
necessary LF otherwise it will not be pasted correctly into another Windows
application. A maximum file size of 64K is allowed to be copied/pasted.
[ALL]
OS9 can access the PC's internal clock to obtain the current date/time. The
utility PC_CLOCK is provided which reads the PC's system clock and updates the
OS9 clock with this information. This could be built into your 'startup' file
to enable the clock to be initilised automatically every time you boot up.
PCShare V3.2 introduces the ability to use the PC's keyboard which in order to
have installed PCShare correctly you will have been using. However, you may
have found that certain 'special' keys such as the arrow keys do not work as
per your original keyboard. PCShare includes the capability to use a user
defined 'keyboard map' which contains definitions of most of the special keys
on a PC's keyboard (such as the arrow keys, function keys etc.). Keyboard maps
may be entered though the 'Options' menu of PC-Share and saved to disk for
subsequent re-loading. A sample OS9 configuration file 'OS9KEYS.MAP' defines
the Dragon's keyboard layout which may be loaded as saved as the PCSHARE3.CFG
defaults.
[DOS]
[WIN]
[ALL]
Both DOS/Windows versions of PCShare implement Copy/Paste operations to a
clipboard - for Windows it is the Windows clipboard, for DOS it is local to
PC-Share.
The WINDRV device driver makes use of a previously unused byte in the path
descriptor PD.BAU (normally the baud rate) which if set causes Line Feeds to
be stripped from incoming text - this is to enable the Windows Paste/File
Import operations to function correctly as it will automatically provide CR/LF
at the end of each text line. This should not normally cause any problems as
normally you would not want to generate LFs on the keyboard, however if it is
the PD.BAU can be set back to 0 using either TMODE or XMODE.
[WIN]
The PCShare archive file includes the WIN2 and WIN3 device descriptors which
are used as descriptors for additional windows which may be activated. Prior
to using them, the IO port base address needs to be modified as per the WIN1
descriptor and saved in the CMDS directory. PCShare allows up to 10 open
Windows.
To launch a new window use the StartWin utility:
Note the '&' indicating a background task - this ensures WIN1 can continue to
be used normally.
A new window will now be opened with an active OS9 shell, offering the same
capabilities as WIN1.
When you wish to close a window, first quit the application that started it -
in the case of the shell press Esc. This now leaves the window 'dead'.
Windows can now be closed in 2 methods:
- from within Windows in the normal manner (top left icon) or from the 'Close
All' option of the 'Windows' menu on the Control Window. Both these methods
close down the window(s) without notifying OS9 and as such a warning is
displayed prior to actioning the close request. If you agree to close the
window, OS9 will not be able to re-use the device descriptor again. You will
have to UNLINK and reload the descriptor and suffer the subsequent memory
fragmentation this will cause.
- using the OS9 UNUSE and UNLINK utility as follows:
when the 'unuse' command is called, the window will be closed. The unlink
command will then remove the descriptor from memory. This is the recommended
manner to close a window.
[ALL]
Close down PC-Share prior to switching off or closing down OS9. If you
interrupt OS9 part way through a message to PC-Share you will lock the machine
forcing a CTRL-ALT-DEL to get control back causing possible data loss to your
OS9 HDISK files.
This part of the user manual contains details on writing new device drivers
for the PC end of PC-Share and the OS9 operating system. It can also be used
as a reference if you are intending to write drivers for another operating
system. You do not need to read this section if you have a working system
established.
Development of a new interface protocol for PCShare consists of writing a
replacement IO module which is capable of performing byte IO to the main
PCShare program. Each of the downloadable .ZIP files contain the 'C' source
code for the Intel 8255 PIO driver.
This module needs to provide the operations listed in the IO_PORTS.H file,
namely:
The IO_PORTS.H file should not be altered, neither should the compiler
switches and DLL framework in the .C file.
Note about the parallel port protocol: the 8255 driver causes a data strobe to
be issued whenever the chip's data direction is reversed - the OS9 driver
software recognizes this and ignores it, in fact it is used to syncronize the
ports back up again. If you are writing a driver which is to talk to the
existing OS9 drivers then it must manually generate this strobe when the port
direction is altered ( via 'in_port_status' and 'out_port_status').
When PCShare is executed, it will first call set_port_base with the IO port
location. You can also use this function to perform any necessary
initialisation.
Once you have written the driver, it needs to be linked to PCShare:
You need a compiler/linker which can create 16-bit DLLs. The DLL should be
named PCS-IO.DLL and copied into your PC-Share directory.
Other compilers will need to have this library or export list created from the
DLL.
The PCSHARE.LIB file included in the ZIP file needs to be linked with your new
device driver using a Borland C compiler. The resultant DOS executable
comprises your new PCShare program.
There is conceivably no reason to write the driver in C, providing you can
implement the Pascal style calling function used by PCShare. The DOS version
may be more tricky because of the dependency on the Borland library file.
This section discuses how to write new OS9 device drivers for PCShare. It may
also be used as a foundation for other operating systems.
PCShare attempts to identify data at the IO port as either text to be
displayed (or passed through the screen emulation software), or a message
sequence requesting a command to be performed (graphics function, sector
read/write, PC transfer etc). Messages are prefaced by a unique 3 character
code indicating the next set of data recieved forms the message. The target
computer (Dragon) is always the bus master, and performs requests for PCShare
to perform. If the message requires that data be returned from the PC, the
ports are reversed and the PC prefixes the message with the 3 character ident
header in order that the target computer may sync up correctly. Because of the
IO handshaking used, provided the target computer correctly checks for this
header it is impossible to become out of step or loose data. Once the transfer
is complete, the ports are reversed again.
A detailed description of the messages passed to and from PCShare is listed in
the Data Interface Document.
The OS9 drivers PCDISK, BPIA21 and WINDRV perform the I/O interfacing to the
parallel port. If you are using a different IO chip these will all need
replacing. If you are utilising a different operating system, these notes
should prove helpful in designing your drivers.
Unfortunatly, one of the side affects of the Intel 8255 is that when the port
is reversed, it causes all data lines to go active low which the target
computer can see as a data strobe. Therefore your IO has to deal with this. A
typical driver setup is as follows:
PCDISK
PCDISK is an RBF device driver, which receives requests to read and write
logical sectors. It formats up the message, and performs the entire transfer
to PCShare. The OS9 System Programmers Guide covers the interface to RBF
device drivers. The driver should also accept the SetStat request SS.WTK to
format a disk, but just ignore it.
BPIA21
BPIA21 performs block data transfers using the MC6821 PIA. It is a PCSBF
device driver, but the interface to it is much like RBF or SCF device drivers.
There are 6 entries to an OS9 device driver, the function of which is covered
in the System Programmers Guide. PCSBF uses the read/write calls to perform
block transfers, and the GetStat and SetStat calls with the new status code
SS.VSupv to tell the driver to change port direction.
Read 'D' bytes from the IO port into memory starting at address 'X'. DO NOT
change the port configuration. Normal data strobe/acknowledge.
Write 'D' bytes from to the IO port from memory starting at address 'X'. DO
NOT change the port configuration. Normal dat strobe/acknowledge.
Get the 'B' register from the register stack (PD.RGS in the path descriptor).
If the register contains the status code SS.VSupv, configure the port for
input and confirm the 3 character header message (see info on data transfers).
All other codes should return the error code E$UnkSvc.
Get the 'B' register from the register stack. If the register contains the
status code SS.VSupv:
All other codes should return the error code E$UnkSvc.
WINDRV
WINDRV is the Windows terminal/keyboard device driver for OS9. It is a fairly
complex module because it has to manage the OS9 end of the windows system.
However, there are 4 internal subroutines which will need replacing for your
new windrv module:
You should not need to change any other part of the driver.
WINDRV SETSTAT/GETSTAT
The Windrv module supports the new setsta/getsta code SS.VSupv which is used
to allow user access to the messaging system of PCShare. Utilities such as
GFXE and PC_CLOCK use this method to talk to the PC.
When called, it will send the 3 character message code to PCShare, and
retrieve the pointer to the message stored in the X register on the caller's
register stack pointed to by PD.Rgs in the path descriptor. The second byte of
the packet indicates the data length, and WINDRV will then transfer the entire
data packet to PCshare.
This interface is also provided to allow other applications to easily access
PCShare functions. An example of this, may be graphics functions from a C or
assembler program. The PCDEFS definitions file contains assembler equates to
assist in performing PCShare function calls. Commands passed to Windrv consist
of a two byte identifier comprising the command id, followed by the total byte
count. Most commands have fixed byte counts, and the PCDEFS file contains the
code for each function as a V$ equate. Your assembler or C code should:
The GetStat call functions in a similar manner, except a return message is
expected from the PC. This consists of the 3 byte message header followed by a
packet length byte and then the packet data. The driver should store the data
into the same buffer as the source packet pointed to by the X register.
PCSBF will accept all the OS9 I/O system calls and process them correctly. For
I$Create calls, the file attributes parameter is ignored. A file access mode
of 'write' specified by I$Create or I$Open will not prevent read operations.
Directory read access supported but not writes, neither is direct sector
access. The following GetStat and SetStat calls are supported: SS.Opt, SS.Siz,
SS.Pos (Getstat), SS.EOF (Getstat), SS.RDY (Getstat for COM device only). The
structure of PCSBF's option section of the path descriptor is defined in
PCDEFS. PCSBF returns a device class of DT.PCSBF (5).
I do not forsee any particular problems with running most of the drivers on
another OS9 platform (either L1 or L2) as they conform to standard file
manager and device driver definitions. The one driver which may present a
problem though is the windows driver WINDRV.
WINDRV performs several potentially problematical operations which may cause
problems, particularly on a L2 system where the operating system exerts that
much more control over 'bad programs'. These are summarized below:
- IO address is stored at V.Page/MSB of V.Port with the LSB reserved for the
window ident number. This is to ensure a unique IO address is presented to the
OS each time in order to create a new incarnation of the driver for the newly
opened window.
- Several direct page locations are used: D.DMAReq ( 1 byte at $006A) flag is
used to mark the active window to prevent unecessary bus traffic, D.KbdSta
exists on Dragon/CoCo as a 2 byte pointer for the keyboard static storage area
($006D) which may not exist on other machines.
- finally and probably most importantly the clock vector D.Clock ($0081) is
hooked in order to perform regular keyboard polling to the PC. This vectored
routine also examines the D.SvcIRQ, D.UsrIRQ and D.Slice locations to
determine if polling is due and can be accomplished.
Hooking of the D.Clock vector only occurs in the version 2 driver, not the one
shipped with PCShare 3.0a/b copies which used simple sleep calls in the i$read
part of the driver to time it's polling. This change is necessary to enable
process's which do not use stdio to be aborted via keyboard abort/interrupt
which the version 1 driver will not support. However, if this causes problems
on your system and you can live with this limitation just contact me and I
will mail you a copy of the v1 driver.
Hardware Interface
PC Dedicated Intel 8255 Parallel IO Card
PC LPT Parallel Port
connecting to:
Dragon Dedicated Motorola 6821 Parallel Interface Chip
Dragon Parallel Printer Port (forthcoming)
Interface Cables
Signals Description
D0-D7 8-bit data bus
DS~ Data strobe, active low.
DA~ Data acknowledge
GND Ground or 0V
These signals are achieved by each end of the interface link as follows:
Signal i8255 Signal IC pin# Maplin D37W pin#
D0-D7 PB0-PB7 18-26 5,24,6,25,7,26,8,27
DS~ PC2 (STB~) 16 22
DA~ PC1 (IBF) 15 4
GND GND 7 10
Signal LPT Signal pin#
D0-D7 D0-D7 2-9
DS~ STROBE~ 1
DA~ ACK~ 10
GND GND 18-25
Signal M6821 Signal Pin#
D0-D7 PA0-PA7 2-9
DS~ CA2~ 39
DA~ CA1~ 40
GND VSS 1
Making the connection
D0-D7 -> D0-D7
DS~ -> DA~
DA~ -> DS~
GND -> GND
8255 6821
PB0-PB7 -> PA0->PA7
SBF~ -> CA1~
IBF~ -> CA2~
GND -> VSS
Installation - PC Software
[DOS]
PCS3I.EXE - PCShare V3 executable for Intel 8255 IO i/f
PCS3L.EXE - PCshare V3 executable for LPT port i/f
PCSHARE3.LIB - Borland C++ library file for PCShare development kit
PC3270 .BGI - Borland graphics drivers for various video cards
IBM8514 .BGI
HERC .BGI
EGAVGA .BGI
CGA .BGI
ATT .BGI
S_SAVE .TXT - sample screen saver file
PCSHRHLP.TXT - On-line Help
PCSHRHLP.NDX - On-line help index file
[WIN]
PCSHARE3.EXE - PCShare V3.0 executable
8255-IO .DLL - Intel 8255 device driver
PAR-IO .DLL - LPT port device driver
PCSHARE3.HLP - Windows help file
[WIN95]
PORTIO32.H - Header file for 32-bit port IO access
PORTIO32.OBJ - Code module for 32-bit port IO access
BWCC32.DLL - Borland custom controls DLL
[WIN32]
PORTIO32.H - Header file for 32-bit port IO access
IOPORTNT.C - Code module interface to port IO driver
BWCC32.DLL - Borland custom controls DLL
[ALL]
IO_PORTS.H - C header file defining device driver interface
8255-IO .C - Sample 'C' device driver for Intel 8255 chip
OS9KEYS.MAP - OS9 keyboard map
[DOS]
Rename the relevent executable to PCSHARE3.EXE and delete the other one. The
program can be invoked by typeing PCSHARE3 at the command line.
[WIN]
Rename the relevent DLL file to PCS-IO.DLL and delete the other one. The .EXE
file can be added to a Program Manager group or executed from File Manager in
the usual manner.
[WIN95]
The DLL file should be renamed PCS-IO32.DLL. Copy the BWCC32.DLL to your \WINDOWS\SYSTEM
directory.
[WIN32]
The DLL file should be renamed PCS-IONT.DLL. Copy the BWCC32.DLL to your \WINDOWS\SYSTEM
directory.
The Windows NT variant of the
package relies on the addition of a 3rd party shareware device driver in order
to access the parallel port hardware. This device driver is available as
shareware from http://www.entechtaiwan.com/tools.htm
and is called TVICHW32.
Once you have downloaded the software, unzip the following components:
DRIVERS\VICPRT00.VXD --> \WINDOWS\SYSTEM\VICPRT00.VXD (for Windows 95)
DRIVERS\VICPRT00.SYS --> \WINDOWS\SYSTEM\VICPRT00.SYS (for Windows NT)
BASE_DIR\DLL\TVICPORT.DLL --> \PC_SHARE\TVICPORT.DLL (your PCShare directory)
Once you have a working version of PCShare, you must puchase the registered
version of this software from the above website.
[ALL]
When you first run it, the software prompts for the configuration details
which it puts in the file PCSHARE3.CFG. This consists of:
Screen Saver On - Yes or No. The screen saver will activate after about 5
minutes of inactivity.
The PCSHARE DOS environment string can be utilised to ensure that PCShare
always locates it's configuration file. This can be setup in your AUTOEXEC.BAT
file, for example:
SET PCSHARE=C:\PCSHARE
Screen Saver: The screen saver activates after about 5 minutes of inactivity
(if enabled) and is similar to the MS-Windows scrolling message saver. The
text for the saver is in the S_SAVE.TXT file in your PCSHARE directory. This
can be edited by a standard editor to a message of your choice.
OS9 Drivers/Software
PCSHARE3L.AR - drivers for a PC using LPT port access
PCSHARE3I.AR - drivers for a PC using 8255 port access
System Modules:
INIT
New INIT module. Sets shared hard disk 0 as default drive (/H0) and
first window (/WIN1) as default terminal device.
SYSGO
New SYSGO module. Sets shared hard disk 0 as your default data
directory (/H0), and default execution directory (/H0/CMDS).
Initialises floppy disk which has the side affect of stopping the
disk spinning after boot up.
WINDRV New Keyboard/Video driver: Replaces KBVDIO to use the PC's screen
and keyboard instead of the Dragon's. Removes 6K graphics overhead
of GO51 graphics modes Provides a message interface to PCShare via
new SetStat/GetStat calls (see technical info for more detail on
this).
WIN1 Device descriptor for WIN1. Replaces TERM descriptor except will
contain the PIA base address.
WIN2, WIN3 Additional WINDRV device descriptors for supporting multiple
windows. Used in MS-Windows version only.
PC_Disk Device driver for PC mounted hard disk. Allows OS9 format hard disks
to be stored on your PC's hard disk. The hard disk data is stored in
the DOS file HDISKx.BIN in your PCShare directory. Disk sizes up to
128MB can be created, and is controlled by the OS9 Hard disk device
descriptor.
H0 Device descriptor for PC mounted hard disk 0. Will contain the PIA
base address and the size of your hard disk accessable by HDISK.
H1,H2,H3 Additional PC-DISK device descriptors for up to 3 other hard disks
mounted on the PC.
PCSBF Stands for PC Sequential Block File Manager, and is a new file
manager for accessing MS-DOS files, directories and devices via
PCShare. Using this, OS9 programs can transparantly access DOS
devices and files, copying files and information between the two
systems simply and easily.
BPIA21 Block MC6821 device driver for performing block data transfers using
the MC6821 PIA for PCSBF. If needed, this module can be replaced to
use another IO chip without re-writing the PCSBF module.
PC PC interface device descriptor. Contains the PIA base address for
BPIA21 and is used in a path descriptor to indicate that the path
should be passed to PCShare and treated as an MS-DOS filename rather
than an OS9 name.
DDISK Replacement floppy disk device driver for Dragon OS9. Contains
additional code removed from the old KBVDIO driver necessary for
correct disk operation.
GFXE-DOS Replacement GFXE module for BASIC09 allowing access to the PC's
graphics capabilities. A variety of graphics modes are supported
from CGA up to VGA. Rename to GFXE for MS-DOS release of PCShare.
GFXE-WIN Replacement GFXE module for BASIC09 allowing access to the PC's
graphics capabilities within MS-Windows. Rename to GFXE for MS-
Windows release of PCShare.
dc DOS command forker. Passes the parameter string to an MS-DOS command
shell for execution. Used in MS-DOS version only.
pccfg General PCShare configuration utility. Selects various text
attributes, modes, screen emulation and COM port configuration.
StartWin Window launcher application. Used in MS-Windows version only.
PCTerm RS232 Terminal program for use with PC's COM ports.
PC_Clock Utility to read PC's Real Time Clock and update the OS9 clock with
this information.
OS9Defs Replacement OS9Defs file. Includes identification of PCSBF as a file
manager, and new SS.VSupv GetStat/SetStat code. Should be placed in
the DEFS directory of your system disk.
PCDefsV3 Definitions for the PC Share OS9 files. Again should be placed in
the DEFS directory of your system disk.
BPIA21.a source code to BPIA21 device driver.
WINDRV.a source code to windrv device driver.
PC_DISK.a source code to pc_disk device driver.
Installation
The LSB of the port address ie. offet $10 is used to identify the window -
WIN1 has a 0, the additional descriptors WIN2 and WIN3 have 01 and 02
respectively. If you wish to open more than 3 windows using OS9, the WINx
device descriptors must be renamed and modified slighly. Firstly, using a hex
editor, update the descriptor name (remember, the top bit is set on the last
character in the name). Next, you must change the bottom byte of the V.PORT
(offset $10) within the descriptor to make it unique (I have used 0,1,2 for
WIN1,2,3 descriptors so anything else should be fine). Finally, use the VERIFY
command with the U option to update the CRC.
Multiple Hard Drives: PC_DISK can support up to 4 hard drives (H0-H3) provided
the PCSHARE executable configuration has been setup to indicate you require
that many hard drives mounted by the system. OS9 Descriptors H1-H3 are in the
OS9 archive file and will need modifying in a similar manner to the H0
descriptor. Each hard disk mounted is stored in the PCShare directory on your
PC as HDISKx.BIN where x=drive number. Throughout the remainder of the
documentation, H0 can be interchanged with H1, H2 or H3 except for the boot &
SYSGo modules which preset H0 to be the default disk.
Formatting the hard disk.
load /d1/pc_disk
load /d1/h0
format /h0
Creating a new boot disk
GO INIT INIT
A new window is displayed labelled /WIN1.
The following text is displayed:
Dragon OS9 Level I
(c)1985 Microware Corp
SYSGO - PC-Share for Windows V3.x
Jan '97 by J.Bird
Shell
OS9:
Using PC-Share
PC-Share for DOS
PC-Share for Windows
Screen/Video Capabilities
Screen Emulation
pccfg -e=0 (none)
1 (DEC VT100)
2 (Dragon OS9 GO51)
pccfg -c=fore_colour,back_colour
The current text mode may be set using the -m option of PCCFG, where 0=40*25,
1=80*25 and 2=80*43/50 (EGA/VGA only).
[ALL]
Terminal emulation and screen colours may also be set from the PC-Share
'Options' menu.
[DOS]
The emulation/screen colours are saved to the PC-Share configuration file when
they are changed from the menu and are restored next time the system is
activated. Changes made by the PCCFG utility are not saved.
[WIN]
The emulation/screen colours changed within the window are only active whilst
that window is active (either via the window menu or PCCFG). To make a change
to the default settings use the Control Window settings.
[ALL]
Graphics Utilities
Mode ID Description
0 Text mode
1 CGA 320*200 palette C0
2 CGA 320*200 palette C1
3 CGA 320*200 palette C2
4 CGA 320*200 palette C3
5 CGA 640*200 2 colour
6 MCGA 320*200 palette C0
7 MCGA 320*200 palette C1
8 MCGA 320*200 palette C2
9 MCGA 320*200 palette C3
10 MCGA 640*200 2 colour
11 MCGA 640*480 2 colour
12 EGA 640*200 16 colour
13 EGA 640*350 16 colour
14 EGA64 640*200 16 colour
15 EGA64 640*350 4 colour
16 EGAMONO 640*350 2 colour
17 HERC 720*348 2 colour
18 VGA 640*200 16 colour
19 VGA 640*350 16 colour
20 VGA 640*480 16 colour
21 VGA 640*480 16 colour scaled to 256*192 for PMODE emulation.
Mode Id Description
0 Text Mode
1 VGA 16 colour palette 256*192 scaled to window
All X, Y and colour values must be declared as INTEGERs.
Colour palette values depend on the graphics mode selected, and fall into 3
categories:
CGA Palette No. Colour 0 Colour 1 Colour 2 Colour 3
C0 Black L/Green L/Red Yellow
C1 Black L/Cyan L/Magenta White
C2 Black Green Red Brown
C3 Black Cyan Magenta L/Grey
all other palette values are undefined.
- for EGA/VGA/MS-Windows modes the following colours are available:
Colour ID Colour
0 Black
1 Blue
2 Green
3 Cyan
4 Red
5 Magenta
6 Brown
7 L/Grey
8 D/Grey
9 L/Blue
10 L/Green
11 L/Cyan
12 L/Red
13 L/Magenta
14 Yellow
15 White
all other values are undefined.
Screen emulation is disabled and emulation change requests are ignored when in
graphics mode.
Forking MS-DOS commands from OS9
dc DIR C:\DOS
lists the DOS directory.
Accessing DOS files & devices from OS9
list /pc/c:/files/testfile.dat
list /h0/startup >/pc/prn
copy /h0/cmds/basic09 /pc/c:/temp/basic09.bin #32k
copy /pc/c:/dos/command.com /r0/command.com #32k
CHD /PC/C:/DOS
dump command.com
chd ..
chd ...
chd ../..
list /h0/startup >prn
copy command.com test1.dat #32k
del /pc/c:/autoexec.bat
makdir /pc/c:/temp
Text and Binary Mode transfers.
Default Directories
CHD /pc/c:/dos
CHX /pc/c:/windows
dump command.com
[WIN32][WIN95]
Long Filenames
Accessing MS-DOS Devices
list /h0/startup >/pc/lpt:
list /h0/startup >/pc/com1:
-R=c,b,d,p,s PC COM Port Setting
b=Baud Rate ID (0-10 as follows: 0 - 110, 2 - 150, 3 - 1200, 4 - 2400, 5 -
4800, 6 - 9600, 7 - 19200, 8 - 38400, 9 - 57600, 10 - 115200).
d=Data Bits (5-8)
p=Parity Id (0-4 as follows: 0 - none, 1 - odd, 2 - even, 3 - mark, 4 -
space).
s=Stop Bits (1-2)
COM Port Access with OS9
XCOM9 /PC/COM2:
PCTERM Usage:
from OS9: PCTERM /PC/COMn: where n is from 1-4.
Windows Clipboard file access
copy /h0/startup /pc/clip:
list /pc/clip:
PC System Clock accessable from host computer.
Keyboard Use
The DOS menu contains options for entering, saving and loading keyboard maps
along with setting up a default map.
A default keyboard map may be entered through the menus on the Control Window
which is applied to all newly activated windows. Keyboard maps entered or
loaded into display windows are not saved into the default settings unless the
'Save as Default' option is chosen. Therefore, to make the 'OS9KEYS.MAP' file
the default, load it into the current window via the 'Load KeyMap' menu item
and then use 'Save as Default'.
Clipboard Pasting within OS9
Activating more than one display window
STARTWIN [win-descriptor] [command-to-start]
eg.
STARTWIN /WIN2 SHELL &
Closing a display window
UNUSE WIN2
UNLINK WIN2
Shutdown Order
Technical Section
PC Driver Development
set_port_base - maps your IO port at the specified location.
read_data - read a byte of data from your port and return it to PCShare.
write_data - write the provided byte of data to your port
in_port_status - return non-zero if your port has data ready to send
to PC-Share
out_port_status - return non-zero if your port is ready to send data
close_io_port - close and clean up port.
Windows device driver
[WIN95]
The DLL is named PCS-IO32.DLL. If you are using a Borland C compiler you will
also need to include the PORTIO32.OBJ file to enable port io operations to be
performed. Visual C users do not need this file.
[WIN32]
The DLL is named PCS-IONT.DLL. In addition to this, you will also need to
include the IOPORTNT.C file which provides the interface to the shareware
library device driver. You will also need an import library for the DLL to be
included in your project. Several are included in the ZIP file as:
\SAMPLES\BC5\TVICPORT.LIB - for BC
\SAMPLES\MSVC50\TVICPORT.LIB - for MSVC
DOS device driver
Writing the driver in another language
OS9 Device Drivers
Overview of the Message Protocol
New Device Drivers
Initialisation: Configure port as output, with data strobe.
Transfer: Write 3 character message header.
Write message.
Set port to input, no data strobe
Poll for first character of message header.
Enable data strobe, and manually acknowledge 1st character
Read in remainder of message header.
Read in message.
Set port to output, no data strobe.
Poll for strobe caused by 8255 re-configuring
Manually clear down data strobe
Enable data strobe.
INIT (entry as per any device driver)
Initialise your IO chip for data strobe, output.
READ:
Entry: X = Transfer address
D = Block size
Y = Path Descriptor
U = Static Storage
Exit: None
WRITE:
Entry: (as per read)
Exit: None
GETSTA
Entry: Y = Path Descriptor
U = Static Storage
Exit: B = Error Code
CC = C bit set
SETSTA
(as GetSta)
if the port is not in output mode, configure for input and accept
the 8255's data strobe.
if the port is alreay in output, read in the 3 byte message header.
TERM (as any device driver)
recbyte - receive a byte from the port and return it in the 'A' register.
The port address is provided in the 'X' register.
sndbyte - send the byte specified in the 'A' register to the port at 'X'.
setiport - configure port for input operation, perform 'strobe checks'
outlined previously and read, validate and discard the 3 byte message
header. Return with the fourth byte (message length) in the A register.
setoport - configure the port for output, send the 3 byte message header
and do the 'data strobe' check.
1. Allocate a packet buffer, the equate V$BUFSZ is the maximum
permissable size:
messg rmb V$BUFSZ
2. Point the X register to the start of the buffer:
leax messg,u
3. Use the equates in the PCDEFS file to form up the packet offset from
the X register (example shown is for the graphics 'set point' call for an
X position of 20 and a Y position of 40, colour 5.
ldd #V$POINT
std V.Comm,x
ldd #20
std V.PointX,x
ldd #40
std V.PointY,x
lda #5
sta V.PColor,x
4. Issue the SetStat call to STDOUT.
lda #1 stdout
ldb #SS.VSupv
os9 i$setstt
bcs error
Miscellaneous
OS9 Application Software with PCSBF
Portability to other OS9 platforms
Jon Bird [dragon_stuff@onasticksoftware.co.uk]
October 1995, April 1996
August 1997, January 1998