These notes are designed to use with the PCShare executable marked V4.1. PC- Share V4.1 is available for 32-bit MS-Windows platforms only - that is Windows 95/98, Windows NT and Windows 2K.
Any specifics to Windows variants are marked [WINNT] - Windows NT only.
PCShare is also available for 16-bit versions of Windows (3.1) and for MS-DOS. If you require these versions, go to the main PCShare page and choose PCShare v3.2.
For information pertinent to using PCShare with the PCDragon emulator, see the Using PCShare v4.1 with PCDragon emulator page.
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 practice 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 4 offers the sharing of a PC's VDU, keyboard, hard disk, floppy disk and just about any device or drive that 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:
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)
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:
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:
PC Intel 8255 - Using 'B' side of chip
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
Note: Using anything other than the 'B' side will require the software drivers to be modified.
PC LPT port
Signal LPT Signal pin#
D0-D7 D0-D7 2-9
DS~ STROBE~ 1
DA~ ACK~ 10
GND GND 18-25
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
Signal M6821 Signal Pin#
D0-D7 PA0-PA7 2-9
DS~ CA2~ 39
DA~ CA1~ 40
GND VSS 1
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:
D0-D7 -> D0-D7
DS~ -> DA~
DA~ -> DS~
GND -> GND
For example, an 8255 to 6821 link would be achieved as follows:
8255 6821
PB0-PB7 -> PA0->PA7
SBF~ -> CA1~
IBF~ -> CA2~
GND -> VSS
The PCSHARE4.ZIP file consists of the following:
PCSHARE4.EXE - PCShare V4.0 executable
8255-IO .DLL - Intel 8255 device driver
PAR-IO .DLL - LPT port device driver
PCSHARE4.HLP - Windows help file
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
8255-IO_NT.DLL - Windows NT 8255 device driver
PAR-IO_NT.DLL - Windows NT LPT port device driver
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
IOPORTNT.C - NT Code module interface to port IO driver
Create a separate directory on your hard disk, and unzip the files into the new directory. Copy the BWCC32.DLL to your \WINDOWS\SYSTEM directory.
On Windows 9x platforms, rename the relevent DLL (either 8255-IO.DLL or PAR_IO.DLL)
to PCS-IO32.DLL.
On WinNT platforms, rename the relevent DLL (either 8255-IO_NT.DLL or PAR_IO_NT.DLL)
to PCS-IO32.DLL.
Windows NT 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.
The Windows NT drivers can also run under Windows 95 by using the VXD
described above.
When you first run it, the software prompts for the configuration details
which it puts in the file PCSHARE4.CFG. This consists of:
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.
Command Prompt - enter the standard command prompt for your host machine's operating system eg. 'OS9:'. When this is detected, any command following it is added to the command history listbox on the toolbar (see help file for further details.)
Delete Character - enter the ASCII code used for the delete key. On most systems this is '8'.
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
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.
The OS9 software is held in OS9 AR archive format:
PCSHARE4L.AR - drivers for a PC using LPT port access PCSHARE4I.AR - drivers for a PC using 8255 port access
Download the appropriate file for your PC interface.
The following software interfaces OS9 to all of PCShare's capabilities:
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.
Programs and Utilities:
GFXE Replacement GFXE module for BASIC09 allowing access to the PC's
graphics capabilities within MS-Windows.
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.
Data files/definitions files
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.
PCDefsV4 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.
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.
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.
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:
load /d1/pc_disk load /d1/h0 format /h0
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.
GO INIT INIT
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:
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:
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 PC-Share comes with on-line help it does not cover the specifics of using each application.
The main PCShare program remains as a permanently minimized icon at the base of the screen (or on the taskbar). The system menu of this icon has menu items which allows PC-Share settings and window management to be controlled. To activate the menu, right click the mouse over the icon (Win9x, NT) or left click the mouse over the icon (Win3.1). 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.
All output from OS9 is now sent to this default 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:
pccfg -e=0 (none)
1 (DEC VT100)
2 (Dragon OS9 GO51)
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:
pccfg -c=fore_colour,back_colour
The colours available are listed under the following section - 'Graphics Utilities' under EGA/VGA colours.
Terminal emulation and screen colours may also be set from the PC-Share 'Options' menu. 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.
A new GFXE modules enables access to the PC's graphics modes, including a 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.
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:
Mode Id Description 0 Text Mode 1 256 colour palette 256*192 scaled to window
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. 256 colours are selectable in this mode, the first 16 are defined to correspond to the VGA colours set. Whilst GFXE usses 256*192 this is not a limitation of PCShare, the interface allows any reasonable size bitmap display to be created.
All X, Y and colour values must be declared as INTEGERs.
The following colours are predefined:
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 set to black. The GFXE module does not at present allow the remaining palette entries to be defined, although this capability is possible via the data interface to PCShare.
When a graphics mode is selected, text can still be displayed.
PCShare V4 offers some enhanced graphics features which are accessable via the GFXE module. In essence these features are variable width lines & line styles. These can be specified via the gfxe 'line' and 'circle' commands. To utilise these features you must use the full command syntax of both the 'line' & 'circle' commands ie. all parameters are specified, then the following parameters must be specified:
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.
list /pc/c:/files/testfile.dat
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:
list /h0/startup >/pc/prn
Files may be copied using the copy command:
copy /h0/cmds/basic09 /pc/c:/temp/basic09.bin #32k
copies the file basic09 to PC and vice-versa:
copy /pc/c:/dos/command.com /r0/command.com #32k
The OS9 CHD and CHX commands can also be used to change to DOS directories:
CHD /PC/C:/DOS
Changes to the DOS directory on the C: drive. Now files can be specifed without using full paths:
dump command.com
provides a hex listing of the PC file command.com. The standard directory specifiers may also be used eg.
chd ..
to step back a directory. However the OS9 convention:
chd ...
to step back 2 directories won't work on a DOS system, instead use the DOS format of:
chd ../..
Once you are 'on' a DOS device, you no longer need to specify the /pc in any pathlist for example:
list /h0/startup >prn
can be used now. Likewise, a DOS file can be copied to another DOS file if so required:
copy command.com test1.dat #32k
You can also delete DOS files using the OS9 'del' command and create new directories using 'makdir':
del /pc/c:/autoexec.bat makdir /pc/c:/temp
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:
CHD /pc/c:/dos
sets the current DOS directory to c:\dos
CHX /pc/c:/windows
will re-set the current DOS directory to c:\windows
Attempting to then access a file in the C:\DOS directory via:
dump command.com
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.
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.
list /h0/startup >/pc/lpt:
list /h0/startup >/pc/com1:
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:
-R=c,b,d,p,s PC COM Port Setting
c=Port ID (1-4)
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 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:
XCOM9 /PC/COM2:
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.
PCTERM Usage: from OS9: PCTERM /PC/COMn: where n is from 1-4.
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.
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.
copy /h0/startup /pc/clip:
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:
list /pc/clip:
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.
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 V4 allows 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.
A default keyboard map may be entered through the menus on the System Menu 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'.
The Copy/Paste functions on the command window allow text data to be transferred to/from the Windows clipboard.
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.
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:
STARTWIN [win-descriptor] [command-to-start]
eg.
STARTWIN /WIN2 SHELL &
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:
UNUSE WIN2
UNLINK WIN2
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.
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:
set_port_base - maps your IO port at the specified location.
read_data - read a block of data from your port and return it to PCShare.
write_data - write a block 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.
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 32-bit DLLs. The DLL should be
named PCS-IO32.DLL and copied into your PC-Share directory. 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.
[WINNT]
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
Other compilers will need to have this library or export list created from the DLL.
There is conceivably no reason to write the driver in C, providing you can implement the Pascal style calling function used by PCShare.
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:
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.
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.
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
Read 'D' bytes from the IO port into memory starting at address 'X'. DO NOT change the port configuration. Normal data strobe/acknowledge.
WRITE: Entry: (as per read) Exit: None
Write 'D' bytes from to the IO port from memory starting at address 'X'. DO NOT change the port configuration. Normal dat strobe/acknowledge.
GETSTA
Entry: Y = Path Descriptor
U = Static Storage
Exit: B = Error Code
CC = C bit set
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.
SETSTA (as GetSta)
Get the 'B' register from the register stack. If the register contains the status code SS.VSupv:
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.
All other codes should return the error code E$UnkSvc.
TERM (as any device driver)
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:
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.
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:
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
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.
Jon Bird [dragon_stuff@onasticksoftware.co.uk]
October 1995, April 1996
August 1997, January 1998
August 1999, August 2001