Publish VCC Plus OSS source distribution for 3.6.2 build 60
This commit is contained in:
commit
c652a5276d
1192 files changed
+272368
No files matched your search
@@ -0,0 +1,328 @@
|
||||
========================================================================
|
||||
DYNAMIC LINK LIBRARY : acia Project Overview
|
||||
========================================================================
|
||||
|
||||
Acia.dll is a Vcc add-on that attempts to emulate the Deluxe RS232
|
||||
program pack. It allows connection to windows serial ports and a
|
||||
tcpip server. It also allows reading/writing windows files and
|
||||
interaction with the Vcc console.
|
||||
|
||||
Issues
|
||||
------
|
||||
1) Baud rates are not very accurate.
|
||||
2) No hardware flow control other than RxF and TxE signals
|
||||
3) DLL does not exit if Vcc crashes. (Issue with all Vcc Dll's)
|
||||
4) No detection of serial port "modem" events when reading:
|
||||
Break, ring, CTS, DSR, RX and DX changes, etc.
|
||||
|
||||
Would be nice
|
||||
-------------
|
||||
1) Support for second sc6551 device
|
||||
|
||||
Acia Quick Start
|
||||
----------------
|
||||
To use acia.dll insert it in the cartridge slot or a MPI slot.
|
||||
This will cause "Acia Config" to be added to the Cartridge menu.
|
||||
Clicking on this menu item allows selection of one of the acia
|
||||
modes: Console, File read, File write, TCPIP (client), and COMx.
|
||||
The Name and Port fields are used to set parameters for modes
|
||||
that require them. The text mode check box when checked causes
|
||||
acia.dll to do CR <-> CRLF translations when using the file
|
||||
read and write modes. The default mode is CONSOLE.
|
||||
|
||||
For a quick test leave the ACIA config mode set to console
|
||||
and enter and run the following basic program. (You can cut
|
||||
and paste using Vcc Edit -> Paste Basic Code)
|
||||
|
||||
10 POKE &HFF6A,1
|
||||
20 IF (PEEK(&HFF69) AND 8)=0 THEN 20
|
||||
30 PRINT CHR$(PEEK(&HFF68));
|
||||
40 GOTO20
|
||||
|
||||
The Vcc console should come up. The console is a CMD type window
|
||||
that is connected to the ACIA. Anything typed in the console
|
||||
will be read and printed by the basic program. To close the
|
||||
console POKE &FF6A,0 or press F5 from the Vcc window.
|
||||
|
||||
The following program does the opposite, characters typed in the
|
||||
Vcc window are written to the console and CR writes CRLF:
|
||||
|
||||
10 POKE &HFF6A,1
|
||||
20 K$=INKEY$: IF K$="" THEN 20
|
||||
30 C=ASC(K$)
|
||||
40 IF (PEEK(&HFF69) AND 16)=0 THEN 40
|
||||
50 POKE &HFF68,C
|
||||
60 IF C<>13 THEN 20
|
||||
70 C=10: GOTO 40
|
||||
|
||||
Console mode is most useful when using Os9 which is described later.
|
||||
|
||||
Radio Shack Deluxe RS232 program Pak
|
||||
-------------------------------------
|
||||
|
||||
If the file "rs232.rom" is in the Vcc execution directory it will
|
||||
be automatically loaded when acia.dll is selected but not started.
|
||||
To start it do "EXEC &HE010" from RSDOS command prompt. The rom
|
||||
is a copy of the 4K rom from the Radio Shack Deluxe RS232 program
|
||||
Pack. If a different ROM is used it must be 4096 bytes long. Note
|
||||
that if acia.dll is in a MPI slot but not selected it can still be
|
||||
used but the pack rom will not be accessible. To exec the rom
|
||||
type EXEC&HE010 at the basic prompt. Note that the pak currently
|
||||
has trouble with the "goto basic" function on Vcc which limits its
|
||||
usefulness. Suggestions for a solution would be appreciated.
|
||||
|
||||
SC6551 Operation
|
||||
----------------
|
||||
|
||||
The sc6551 emulation is controlled one of two blocks of port addresses,
|
||||
0xFF68-0xFF6B or 0xFF68-0xFF6F, the block used is selected by a Acia
|
||||
config dialog Radio button. The CPU controls the sc6551 by writing
|
||||
to these addresses and gets status and data from the sc6551 by reading
|
||||
them. A sc6551 datasheet will explain these in detail - what follows is
|
||||
a brief explaination of the most important bits to acia.dll.
|
||||
|
||||
0xFF68 (0xFF6C) is the data register. A write to the address will transmit
|
||||
a byte of data and a read will receive a byte of data.
|
||||
|
||||
0xFF69 (0xFF6D) is the status byte. The CPU reads this port to determine
|
||||
the status of the sc6551. Bits 0, 1, and 2 of the status byte are
|
||||
error indicators. Bit 3 indicates that a data byte is ready to read.
|
||||
Bit 4 indicates that the sc6551 is ready to transmit a byte. Bits
|
||||
5 and 6 are modem and data set ready bits, and Bit 7 indicates the
|
||||
sc6551 has asserted and IRQ. Acia.dll does not set the error bits and
|
||||
bits 5 and 6 are always clear to indicate mode and data ready states.
|
||||
|
||||
Data flow is controlled by status bit 3 (RxF) and bit 4 (TxE). When
|
||||
the CPU wants to send data it first must verify bit 4 (TxE) is set before
|
||||
writing to the data register, and when it wants to recieve data it must
|
||||
first check that bit 3 (RxF) is set before reading the data register.
|
||||
|
||||
Acia.dll will assert an IRQ and set status bit 7 when data becomes ready
|
||||
to read if Bit 1 of the command register (0xFF6A (0xFF6E)) is clear. The coco can
|
||||
use the interrupt to reduce input polling.
|
||||
|
||||
0xFF6A (0xFF6E) is the command register. Bit 0 of the command register is the
|
||||
DTR bit. This bit enables or disables the sc6551. If this bit is set
|
||||
by the coco CPU then communications are active (open) and if it is
|
||||
cleared communications are inactive (closed). Other command register
|
||||
bits set IRQ behavior and parity. Refer to data sheet for details.
|
||||
|
||||
0xFF6B (0xFF6F) is the control register. Bits 0-3 of the control register set
|
||||
the baud rate according to the following table. Datasheet rates that
|
||||
are not supported by acia.dll have replaced by the next higher value.
|
||||
Acia.dll uses screen sync signal to time the input speeds. These
|
||||
are only approximate and if F8 is toggled (Screen refresh throttle)
|
||||
the rates are invalid.
|
||||
|
||||
val rate val rate
|
||||
0 MAX 8 1200
|
||||
1 75 9 2400
|
||||
2 75 10 2400
|
||||
3 110 11 4800
|
||||
4 300 12 4899
|
||||
5 300 13 9600
|
||||
6 300 14 9600
|
||||
7 600 15 19200
|
||||
|
||||
Bits 5 and 6 of 0xFF6B (0xFF6F) set the data length and Bit 7 sets the number
|
||||
of stop bits. B5-6: 00=8 01=7 10=6 11=5 len. B7 0=1, 1=2 stops.
|
||||
|
||||
Basic programs can enable acia by poking 1 to &HFF6A and disable it by
|
||||
poking 0. They can then peek &HFF69 and test the result for RxF by
|
||||
anding 8 or test for TxE by anding 16. Then peek &HFF68 to read data
|
||||
and poke &HFF68 to write it.
|
||||
|
||||
To demonstrate here is a simple Basic program that will read data
|
||||
from the emulated acia:
|
||||
|
||||
10 POKE &HFF6A,1
|
||||
20 S=PEEK(&HFF69) AND 8
|
||||
30 IF S=0 THEN 20
|
||||
40 PRINT CHR$(PEEK(&HFF68));
|
||||
50 GOTO20
|
||||
|
||||
To test it set the Acia Config dialog to read a text file from the PC.
|
||||
(Filename is relative to user directory). When the program is run
|
||||
Basic will print it's contents. If you press break and then continue
|
||||
the program will resume printing where it left off. If you poke 0 to
|
||||
&HFF6A acia will close the file and when the program is run again it
|
||||
will reopen and start from the file's beginning.
|
||||
|
||||
Since the baud rate has not been set acia defaults to 0 which is max
|
||||
speed. In this case the program's output is throttled by the PRINT
|
||||
rate. If F8 is toggled it runs much faster.
|
||||
|
||||
This simple program does not check for end of file so you have to use
|
||||
break to end it because acia.dll will endlessly send EOF and CR
|
||||
sequences as basic attempts to read past the end of file.
|
||||
|
||||
More detail on file read mode can be found later in this document.
|
||||
|
||||
RS232.ROM
|
||||
---------
|
||||
|
||||
If the file "rs232.rom" is in the Vcc execution directory it will
|
||||
be automatically loaded when acia.dll is selected but not started.
|
||||
(make sure Autostart Cart in Misc Config dialog is unchecked)
|
||||
To start it do "EXEC &HE010" from RSDOS command prompt. The rom
|
||||
is a copy of the 4K rom from the Radio Shack Deluxe RS232 program
|
||||
Pack. The RS232 rom is only usefull if FF68 (RS-232 Pak) is selected
|
||||
in the config dialog. If a different ROM is used it must be 4096
|
||||
bytes long. Note that if acia.dll is in a MPI slot but not selected
|
||||
it can still be used but the pack rom will not be accessible.
|
||||
|
||||
Communications Modes
|
||||
--------------------
|
||||
|
||||
Communications modes are set using the Acia Interface config dialog
|
||||
which can be reached from the Vcc Cartridge menu when the DLL is
|
||||
loaded. The dialog has radio buttons for Console, File read,
|
||||
File write, TCPIP, and COMx modes of operation. When activated
|
||||
Console mode brings up the Vcc console window. File write mode
|
||||
causes all data output to go to a file. File read mode does the
|
||||
reverse; data is input from a file. TCPIP mode establishes a
|
||||
client connection with a network server and Comx mode establishes
|
||||
a connection with a windows serial port. When File read or Write
|
||||
mode is selected the filename relative to user home directory
|
||||
must be inserted into the Name field. When COMx mode is selected
|
||||
the port name (eg: COM3) must be placed in the Name field with no
|
||||
leading blanks. When TCPIP mode is selected the server address
|
||||
must be in the Name field and the port number in the Port field.
|
||||
Additional detail of these modes follows.
|
||||
|
||||
Console mode
|
||||
------------
|
||||
|
||||
Console mode can be useful when using (Nitr)Os9 and the t2 device
|
||||
and associated sc6551 driver. t2 and sc6551 must both be loaded at
|
||||
boot (in the boot track) to work properly. The t2 device can also
|
||||
be used for testing purposes, which is why it was originally created.
|
||||
Note that the stock t2 driver assumes the Acia Address is FF68.
|
||||
|
||||
Caution: There can only be one console associated with Vcc. Conflicts
|
||||
will occur is the console is used for other purposes, such as for
|
||||
debug logging.
|
||||
|
||||
/t2 settings for Windows conso1le should be as follows:
|
||||
|
||||
xmode /t2
|
||||
-upc -bsb bsl echo lf null=0 pause pag=32 bsp=08
|
||||
del=18 eor=0D eof=1B reprint=09 dup=19 psc=17 abort=03
|
||||
quit=05 bse=08 bell=07 type=80 baud=06 xon=11 xoff=13
|
||||
|
||||
Some of these settings are not honored by the sc6551 driver.
|
||||
Xon, Xoff, and baud xmode settings seem to have no effect.
|
||||
|
||||
The console uses standard OS9 text window settings. Acia.dll
|
||||
will translate many OS9 text screen control codes to do the
|
||||
proper console functions. Colors default to white on black.
|
||||
Only colors 0-7 are supported.
|
||||
|
||||
To launch a shell simply do: shell i=/t2 and the console
|
||||
will come up. Typing "ex" in the console window causes the
|
||||
console to close.
|
||||
|
||||
The console handles scrolling fairly well. The windows system
|
||||
automatically moves the console window within the screen buffer
|
||||
to keep the cursor visible. This causes text to appear to scroll
|
||||
as long as the cursor is within the boundaries of the buffer.
|
||||
|
||||
By default the windows screen buffer is large but eventually it
|
||||
becomes full. To handle this acia.dll deletes lines from the top of
|
||||
the buffer when the cursor tries to move to a line below the bottom.
|
||||
This affects full screen editors. They use cursor move sequences
|
||||
to control positioning within the screen boundaries but must scroll
|
||||
text when the cursor tries to move beyond the screen boundaries.
|
||||
|
||||
Vim (fixed tsedit) works pretty well. It takes care of deleting lines
|
||||
from the top of the screen when the cursor nears the bottom and
|
||||
replaces the lines when scrolling up. Vim seems to be hard coded to
|
||||
24 lines so the screen must be at least 24 lines long. (changing
|
||||
tspars or typing v to set the screen type does not work for me)
|
||||
|
||||
Scred assumes the terminal will delete lines from the top of the
|
||||
screen when the cursor is at the bottom of the screen. (emphasis on
|
||||
screen) This means screen length must match what scred thinks for
|
||||
it to work properly. Since acia.dll console does the delete based
|
||||
on buffer size it actually is that size that scred must be aware of.
|
||||
Fix it to set the screen buffer to a reasonable size and use scred's
|
||||
-l=<screen buffer len> argument. (500 lines still seems to work
|
||||
but I don't use scred much). The size of the buffer can be changed
|
||||
from the windows properties menu in the console title bar.
|
||||
|
||||
I did a brief check of uemacs. It seems to work okay except I find
|
||||
the lack of support of arrow keys annoying and I am too used to
|
||||
vi's use of hjkl for cursor position to adapt to emacs.
|
||||
|
||||
|
||||
File Read and File Write Modes
|
||||
------------------------------
|
||||
|
||||
File modes allow reading or writing to/from a windows file. After
|
||||
selecting the appropriate radio button in the Acia Interface config
|
||||
dialog the file name relative to user home directory should be
|
||||
entered in the Name field. For example: "test\myfile.txt" in the
|
||||
name field refers to %USERPROFILE%\test\myfile.txt
|
||||
|
||||
There are two file modes, File Read and File Write. Read mode
|
||||
causes acia to receive characters from the file specified and
|
||||
write mode sends charactes. Writes in read mode are ignored
|
||||
and reads in write mode returns nulls.
|
||||
|
||||
It is sometimes best to turn off local echo and pause on the
|
||||
os9 /t2 device to avoid I/O errors, eg: xmode /t2 -echo -pause
|
||||
|
||||
Text mode. When text mode is checked end of line translations
|
||||
(CR <-> CRLF). This is recommended when using /t2 in os9 unless
|
||||
attempting to write binary files to windows. Reading binary files
|
||||
is difficult under os9 because the sc6551 driver does not report
|
||||
end of file conditions. To avoid hangs acia.dll returns a <CR><ESC>
|
||||
sequence when an attempt is made to read past the end of a file
|
||||
regardless of text mode settings.
|
||||
|
||||
Sending command output to a file can be done with something like
|
||||
'dir -e > /t2' If doing a long listing it is better to place the
|
||||
output in a os9 file and copy that to /t2, for example:
|
||||
|
||||
dir -e -x > cmds.list
|
||||
copy cmds.list /t2
|
||||
|
||||
When using other programs to read or write files it is important
|
||||
to note that setting DTR opens the file and clearing DTR closes
|
||||
it. The NitrOS9 driver takes care of this but many terminal
|
||||
programs do not. DTR is controlled by bit 0 in 0xFF6A (0xFF6E).
|
||||
|
||||
TCPIP Mode
|
||||
----------
|
||||
|
||||
TCPIP mode causes acia to do a client connection to a tcpip server.
|
||||
After selecting TCPIP radio button on the Acia config dialog the
|
||||
server hostname or IP address should be entered in the Name field
|
||||
(default is localhost) and the server port in the Port field. Setting
|
||||
bit 0 in 0xFF6A (0xFF6E) opens the connection and clearing it closes it.
|
||||
|
||||
Testing tcpip mode was done using netcat on Linux as a server.
|
||||
On Linux ' nc -l -p 48000' 48000 is the port number I am using.
|
||||
After launching a shell connected to /t2 on (Nitr)Os9 the Linux
|
||||
session becomes a terminal connected to Os9.
|
||||
|
||||
Also Twilight Term (TWI-TERM.BIN) was used to test connection with
|
||||
a telnet BBS on the internet. (Set the address on the BBS in the
|
||||
acia interface config name field and 23 in the port field)
|
||||
|
||||
COMx Serial Port Mode
|
||||
----------------------
|
||||
|
||||
After selecting COMx radio button the port name should be entered
|
||||
in the Name field, for example "COM3". Leading blanks will not
|
||||
work, port name must be left justified.
|
||||
|
||||
Valid baud rates are 110,300,600,1200,2400,4800,9600,19200
|
||||
|
||||
Testing of the COM port mode was done using a com0com port emulator
|
||||
in windows along with putty. com0com is used to 'wire' two psuedo
|
||||
port COM20 and COM21 together. I used acia.dll to connect to COM20
|
||||
and PuTTy to connect to COM21. This allowed me to simulate connecting
|
||||
with a terminal. Also tested with a USRobotics faxmodem via a Radio
|
||||
Shack USB to serial adapter and the legacy USBSER driver.
|
||||
|
||||
Reference in new issue
Block a user