ee163aas@sdcc18.ucsd.EDU (James Hayes) (05/01/87)
FINALLY! They're here. I've corrected most of the spelling mistakes
and checked it again for correctness, but that (as we all know so
well) doesn't make it error free. :-(
Each page is separated by a formfeed. (So printing is as
painless as possible.) My apologies if your host strips control
characters from news...
Have fun, and as always, let me know if you netlandians come up with
anything great. (As you have in the past...)
-Jim Hayes, Somewhere in California...
(Oh, best reply to my real account which is created by taking
the return path and changing 'sdcc18!ee163aas' to 'hayes'
so it looks like ...!ucsdhub!sdcsvax!hayes or equivalent...)
ARPA: hayes@ucsd.ucsd.edu {Yes, ucsd.ucsd.edu. Ain't domains fun?}
----Sniparoony---- (66 Lines/Page)
Terminal Program Applications Notes
This document covers writing your own hardware drivers to work
with the DCOM 3.3 vt100 emulator.
Overview:
The vt100 emulator is broken up into several modules:
The standard (non hardware specific) modules:
1) The main terminal driver. (It uses all drivers)
2) The keyboard driver (Maps what you type to what gets
sent.)
3) The control panel (The "set up", dialing, and modem menus)
The non-standard (hardware specific) modules:
1) The video driver
2) The serial card driver
3) The modem personality (Defines dialing and on/off hook
characteristics.)
4) The printer driver
Each driver is allocated a segment of memory, and all the driver
functions are handled through standardized entry points.
Terminal Program Applications Notes
DCOM.MAIN:
This is the main controller for the terminal emulator. It
handles all aspects of the emulation. (Decoding, translating,
and interpretation)
It lives at $2000 and is allocated 4096 bytes for the program +
any buffers it might need to perform its duties.
Standardized calls to the main module:
$2000 - Begin emulation. This initializes all the hardware,
clears the screen, and becomes a terminal.
$2003 - Not presently used, BUT.. May be used to return when
there is a need to exit for some reason. (To another
program {e.g. BASIC} that can perform higher level
functions such as saving buffers, files, etc.)
$2006 - WARNING! WARNING! (Just a trick to get you to read this.)
This routine is the HEART of the terminal program. This
call polls the modem for a character, and if one exists,
the character is stored in a queue. If the queue is near
full, an X-OFF (Ctrl-S) is sent. When the queue empties,
an X-ON (Ctrl-Q) is sent. This routine is used by all
drivers to keep checking the modem. If you write a
driver and any particular routine has a loop, BY ALL
MEANS, call $2006 (STUFFBUF) every few milliseconds.
$2009 - This call simulates the input of a character from the
modem. (This might be used to "play-back" a terminal
session stored on disk.) It is presently used to output
characters to the screen from the control panel.
$200C - This call clears the incoming character queue. This is
used in the phone dialing routines, so the dialing
commands aren't echoed back.
Unless there are glaring bugs in the main driver, the source for
the main driver should never have to be touched. (I know someone
out there will make me eat my words. I just know it...)
The main driver should have at least 257 bytes free in its 4K block
to house the character i/o buffer.
Terminal Program Applications Notes
Global variables used by the main program and all drivers:
$2FF - This is the return flag. When you type @ from the
set up menu, this flag gets set (to tell the main
program that you want to exit) to $F0. If before
you exited, you selected S, then the flag would by $FF
indicating that you want to save all the defaults when
you exit.
$300 - Development flag. This is used during the course of
debugging the program. Please do not use this for
anything but testing purposes. I guess you can call it
reserved. That has a nice ring to it... "reserved"
$301 - MODEINS. This is the "insert character" mode flag.
Real life vt100's have no clue as how to insert
characters, so I gave my program the ability to do
so using standard ANSI (American National Standards
institute) codes. Therefore, this emulator can also
look like a vt125, vt220, and practically anything made
by microterm and other companies.
The insert mode is "on" when the high-bit is set.
$302 - MODESCRL. This flag determines whether or not the
emulator will scroll when a cursor movement (e.g. up,
down, left, right) is going to go off the screen. Real
vt100's don't have this flag, but it was included as
part of the added ANSI control sequences mentioned
above.
The screen will scroll on cursor movements when the
high bit is set.
$303 - MODELFNL. MODE LineFeed->NewLine. When the high bit of
this puppy is set, any linefeeds received will
automatically be converted to "New line"s (CR+LF)
sequences.
$304 - MODECRNL. MODE Carriage Return->NewLine. When the high
bit of this is set, any carriage returns that are
received are mapped to "New line" (CR+LF) sequences.
$305 - MODEWRAP. Wraparound mode. A high bit here indicates
that incoming characters will not be truncated once
they bang into the right edge of the screen. (I.E. any
line longer than 80 columns will be wrapped.)
$306 - MODEKEY. This mode determines whether your apple will
let you know (via a click) every time you type a key.
If the high bit is set, it will do so.
$307 - MODEECHO. When the high bit is set, anything typed will
Terminal Program Applications Notes
be echoed to the screen (except escape sequences).
$308 - MODEBACK. This is really misnamed. It contains the
current background clear character. $20 for normal
screen, and $A0 for reversed image screen.
$309 - MODEDBL. High bit indicates that the emulator is in the
"double wide" mode on the current line. When this
happens, Each character takes up two character
positions, (the character + space). The line is
effectively 40 columns wide, and subsequent cursor
positions will reflect a 40 column line.
$30A - MODETOP. When in the double wide mode is set, there
is another thing to worry about.. The double wide,
double high mode. This flag takes care of that. When
the high bit is not set, all is normal. BUT WHEN IT IS
SET, it means that the emulator wants to display the
lower portions of the letters. Since no Apple 80 column
card today has the capability of double high letters
mixed in with regular text, the lower portions of the
letters are just converted to "--" which adds a nice
accenting touch to the letters.
$30B - MODECHR. This flag determines what character set the
emulator is using. If the highbit is set, the emulator
will use the substitute line drawing character set, if
the 80 column card can handle it.
$30C - MODEINV. As usual "This flag bs bs bs bs" It controls
the status of the character output. If the high bit is
set, the screen driver will output inverted characters.
BE CAREFUL TO NOTE THAT THE BACKGROUND CHOICE (MODEBACK)
INVERTS THE ABOVE STATEMENT.
$30D - MODEVT52. When this flag is set, the terminal will only
respond to vt52 command strings.
$30E - XOFF. When the high-bit of this flag is set, it means
that the buffer is near full, and an X-OFF was sent.
(When the buffer depletes, an X-ON will be sent.)
$30F - CX. This is the current cursor position as known to all
the routines. This is the formost authority of the X
coordinate of the cursor. (0-79)
$310 - CY. This is the current cursor position as known to all
the routines. This is the formost authority of the Y
coordinate of the cursor. (0-23)
$311 - BLINK. This is the current cursor blink rate. 0=no
blink, while 1 is fast and 9 is slow.
$312 - SCRLTOP. This number represents the top of the current
Terminal Program Applications Notes
scrolling region. (0-23). The scrolling region is
the active text region. Usually it starts on line 0
and extends to line 23. Some programs however, like to
use a smaller scrolling window, while using the rest
of the screen for other data. Any data written to the
screen will only appear in the scrolling region, so it
will not affect the rest of the display.
$313 - SCRLBOT. This is the bottom line of the scrolling
region. (0-23) See above.
$314 - MODEKAM. KAM is the ANSI term for Keyboard
Applications Mode. When this mode is set (via the
high bit) different vt100 keypad codes will be used
instead of the standard codes that are normally used.
(See real vt100 manual)
$315 - MODECURS. This is used (why I don't know) to indicate
that an alternate set of codes should be used when the
arrow keys are hit. As usual, a high bit indicates that
these alternate codes should be used. Please see a real
vt100 manual for more information.
$316 - G0MODE. This selects the character set used for the g0
character set. The high bit indicates the graphic
character set.
$317 - G1MODE. This selects the character set used for the g1
character set. The high bit indicates the graphic
character set.
$318 - MODEORIG. This is the ANSI related flag that tell the
terminal that cursor positioning should be done with
respect to the scrolling region's home position instead
of the display's home position.
$319 - GOG1TOg. G-Oh-G-1. High bit here indicates that the
alternate character set (inverse or graphic) should be
used. (See MODECHR and MODEINV for the specific set
that we're looking for...)
$31A - MSLOT. This contains the current slot of the serial
card. (1-7), except 3 and 6
$31B - PRECHO. HB=Echo output to printer.
$31C - MODE. This is the state of the current command
sequence parser. 0=No escape sequence in progress.
1=Escape sequence started.
2=wait for next. If "[" set mode 3,
otherwise, interpret single letter
escape code.
3=<ESC> [ received, collect parameters
and act on command wishes.
Terminal Program Applications Notes
4=Transparency mode, ANSI CRM.
Control Representation Mode. All
characters are sent to screen and
no escape codes are interpreted.
Must be reset via the R option on
the setup menu.
5=vt52 escape sequence started, this
current character will end the
code sequence.
6=vt52 cursor positioning sequence
is on it's way. read two characters
in this mode and position the
cursor.
$31D - BAUD. Current serial card Baud Rate. 0=300
1=1200, 2=2400
$31E - PARITY. Current serial card parity method.
7=None, 8=Even, 9=Odd, 10=Mark, 11=Space
$31F - STOP. Current serial card stop bits setting.
3=8 bits, 1 stop 4=8 bits, 2 stop
5=7 bits, 1 stop 6=7 bits, 2 stop
$320 - TABTABL. Starting at $320 and extending 79 bytes, is the
image of the terminal's tabstops. 320=column 0. A high
bit indicates a tab is set there.
$380 - LNMODES. Starting at $380 and extending 23 bytes, is the
image of the terminal's "line modes" Bit 7=1 when Double
wide is selected for that particular line, Bit 6=1 when
the line refers to the bottom half of the double wide
characters.
$8100 - This 255 byte area holds a copy of the terminals
-$8200 defaults when the screen is saved.
$8200 - Holds a copy of the terminal parameters when the save
-$83FF cursor mode is selected.
$8400 - Holds a memory image of the saved screen. You have
-$9400 roughly 4K to play with here. Use it wisely.
Terminal Program Applications Notes
The printer driver lives at $3000 and is allocated a meager 2K for it
to do its business. There is one kernel call to the printer driver:
$3000 - Output a character to the driver. If it is the first
character output, initialize the card before printing it.
The driver should respond to all printable ascii characters, and
should execute a carriage return/line feed sequence on receipt of
a carriage return ($0d)
Terminal Program Applications Notes
DCOM.MODEM.xxxx:
The DCOM modem driver lives at $4000 and is alotted 2048 bytes.
DON'T Panic. The modem driver usually takes about 200 bytes.
The established calling conventions:
$4000 - Initialize the serial card/modem here.
This should do the following:
Reset the page 3 values of MODE, BAUD, and PARITY from
the default table DCOM.MODEM.xxxx.D.
Reset the AICA port on the card/modem.
Hang up the phone (in cases when this is not
a serial card but something like a
Apple-Cat or Micro-Modem)
$4003 - Sense the status of the serial card. It returns the
carry set if something is waiting to be read in.
$4006 - Get a character from the modem. (Use the above to make
sure one is waiting. (The character will be put into
the 6502 ACCUMULATOR)
$4009 - Output a character on the modem. The character must be
in the accumulator. No stripping of high bits is
performed here.
$400C - Change the transmission characteristics. The
characteristic is in the accumulator:
0 = 300 Baud 3 = 8 data, 1 stop
1 = 1200 Baud 4 = 8 data, 2 stop
2 = 2400 Baud 5 = 7 data, 1 stop
6 = 7 data, 2 stop
7 = No parity
8 = Even parity
9 = Odd parity
A = Mark parity
B = Space parity
$400F - Send a break "character"
$4012 - Compatibility table; If a member of the table is $FF,
then the equipment is capable of "doing it". The meaning of each
entry corresponds to the above transmission characteristics. If
an entry is $F0, then then this is the default mode for the card.
If the member is $00 then the hardware is incapable of inheriting
that characteristic. There is one capability in the table that is
not listed above, index $C which is the break signal. The
default table is the responsibility of the user to set. The
modem's default parameter list is 13 bytes long and is overlayed
at $4012. works. All in all, it should not be difficult to write
Terminal Program Applications Notes
your own driver for your serial card. Please see also, the
dialing personality module in upcoming pages.
NOTES:
Remember that the defaults are overlayed starting at $4012
for 13 bytes. Please choose the defaults carefully. Failure to
understand that particular portion of the code and what it does
and how it works can lead to months and months of dispair.
Enough Warnings!
Terminal Program Applications Notes
DCOM.SCREEN.xxxx:
The screen driver lives at $5000 and is alotted 2048 bytes to do
it's work. The kernel jumps are:
$5000 - Initialize the screen. This should initialize any display
INIT- hardware, soft-switches, etc. It should in no way clear
SCRN the screen.
$5003 - Zap the screen clean! Does not reset the cursor to the
ZAP home position.
$5006 - Clear the line number contained in the Y reg.
CLRLINE
$5009 - Move the line in the x-reg to the line in the y-reg.
MOVELINE
$500C - Store the contents of the accumulator to the screen
STORE- location (x-reg,y-reg) This routine should not care what
XY it gets fed. It should just deposit anything.
$500F - Clear from the current cursor position to the end of the
CLEAR- line.
EOL
$5012 - Clear from the current cursor to the end of the screen.
CLEAR-
EOS
$5015 - Scroll the screen up. (With respect to the scrolling
SCROLL- window.
UP
$5018 - Scroll the screen down. (With respect to the scrolling
SCROLL- region.
DO
$501B - HIDE the cursor from sight. This call is VITAL to the
HCP health and well being of the terminal program. Follow
this rule of thumb: BEFORE YOU DO ANYTHING TO THE
SCREEN, REMOVE THE CURSOR, MUCK WITH THE SCREEN, AND PUT
THE CURSOR BACK. This routine saves what ever was under
the cursor in order to put it back. See SHOW routine
below.
$501E - Cycle the cursor blink counter through one cycle. If
CCHECK counter reaches it's blink threshold, ("BLINK" times
$100) then invert the cursor. This is done to get the
damn thing to blink.
$5021 - SHOW the cursor (After a remove) Opposite of $501B
SCP
Terminal Program Applications Notes
$5024 - Pickup the character from (x-reg,y-reg) and stuff it into
PICKUP the accumulator. The screen remains unblemished.
$5027 - Output the accumulator to the screen at the current
CHOUT cursor location. Scroll if necessary, display as inverse
if necessary, use double wide double high modes. etc.
$502A - Insert a line at the present cursor position and return
INSERT- the cursor to the left edge.
LN
$502D - Delete a line at the present cursor position and return
DELETE- the cursor to the left edge.
LN
$5030 - Clear from the beginning of the line to the cursor.
CLEAR- (Inclusive)
BLC
$5033 - Clear from the home (0,0) position to the cursor.
CLEAR- (Inclusive)
HC
$5036 - Delete the character under the cursor and move the
DELT- rest of the line over one position. (Clears the last
CHAR column on that line.)
$5039 - Insert a blank under the cursor and move the rest of
INST- the line over one position.
CHAR
$503C - Fill the screen with E's, (Video Alignment Pattern.)
FILLE (invoked by <ESC>#8)
$503F - INVERT the whole screen. For example, white on black
FIX- becomes black on white and vice versa.
SCRN
$5042 - Do a carriage return and a line feed.
DOCR
$5045 - Do a line feed.
DOLF
$5048 - Save the screen in memory. $8400-$9400 is reserved for
SAVE- this. This also saves the video defaults so we can come
SCRN back without damaging anything.
$504B - Restore the screen from the memory save to by the above
REST- routine. Also restore any video flags that might have
SCRN been altered.
$504E - Reset the line (make single width from double width)
$5051 - Make Double (make double width from single width)
Terminal Program Applications Notes
NOTES FOR WRITING A SCREEN DRIVER:
You DO NOT have to rewrite all the above routines! YEA! There
are only a few that need to be adapted to your own hardware.
They are:
INITSCRN (for obvious reasons)
CLRLINE
MOVELINE (allows for scrolling)
STOREXY (to put characters on the screen.)
PICKUP (to get the character under the cursor)
FIXSCRN (to invert the screen.)
SAVESCRN (save the screen to memory)
RESTSCRN (..and bring it back.)
You see, all the other routines can use combinations of the above
"CORE" routines. Even some of the core routines can use other
core routines. For example: SAVESCRN can use PICKUP. It will be
slow, but it will work. FIXSCRN can also use PICKUP. Again, it
will be slower, but it will work. Restscrn can use STOREXY. As
usual, it will be slower. MOVELINE can use PICKUP and STOREXY to
do it's work. (THIS IS ONLY RECOMMENDED FOR TESTING PURPOSES. IT
IS A DANGER TO SPEED CONCERNS TO LEAVE IT THAT WAY.)
So you see, only a few routines need to be written.
Since speed is so critical, the routines should never assume
that the calling routine wants registers returned intact. So,
don't keep pushing and popping stuff on and off the stack. That
REALLY slows things down.
During a scroll and "looping" routines, poll the "STUFFBUF"
routine so characters coming into the computer get read and are
not thrown away. I.E., after every CLRLINE, MOVELINE, etc. This
will insure that characters will not be "dropped" because the
program is not reading them fast enough.
That about exhausts the Video Driver section...
Terminal Program Applications Notes:
DCOM.KEYBOARD.xxxx
The Keyboard Interpreter lives at $6000 and is allotted a meager
1024 byte spread in the memory map. This is true. (It's really a
small piece of code!)
Anyway it does the following:
$6000 - Interpret keyboard character in the accumulator and send.
This will intercept open/closed apple commands and
interpret them.
$6003- This is the Key Table. This is a table of the ASCII
$6033 representation of the special keys we want to redefine
as vt100 keypad/function keys. For example: Q and q are
defined to be the PF1 key... So Q and q would appear in
this table as special characters that are to be
intercepted when the open/close apple key is struck. How
do we translate them? NEXT....
$6034- Key Dispatch Table. Here the key's special purpose is
$6064 defined. The order in which the one byte definition
appears is the same order that the one byte key code
appears in the above Key Table.
The one byte codes that are used are:
1 - vt100 UP arrow 9 - vt100 keypad 7
2 - vt100 DOWN arrow 10 - vt100 keypad 8
3 - vt100 RIGHT arrow 11 - vt100 keypad 9
4 - vt100 LEFT arrow 12 - vt100 keypad -
5 - vt100 Pf1 13 - vt100 keypad 4
6 - vt100 Pf2 14 - vt100 keypad 5
7 - vt100 Pf3 15 - vt100 keypad 6
8 - vt100 Pf4 16 - vt100 keypad ,
17 - vt100 keypad 1
18 - vt100 keypad 2
19 - vt100 keypad 3
20 - vt100 keypad <ENTER>
21 - vt100 keypad 0
22 - vt100 keypad .
23 - vt100 BREAK KEY
$6070- Translate table. The single byte translate table. Here
$6090 is where the the function key is mapped to the character
to send to the host.
An example to clear up all this confusion:
Let's say you type an open-apple W. "W" appears as the third
element in the Key Table. So, look at the 3rd byte in the
Terminal Program Applications Notes:
Dispatch Table. It is 6 (meaning pf2), so look at the 6th
element in the Translate table. Here we find that an S is to be
sent. (So the sequence looks like "<ESC>?S".)
This wonderful method means that your own preferences in keys can
be mapped into the program.
Terminal Program Applications Notes:
Modem Personality Description:
DCOM.PERSONALITY.xxxx lives at $6800 and is alotted 1024 bytes.
It controls the modem dialing aspects.
$6800 - This byte contains the "ability" flag for the equipment's
ability to dial the phone. It has these meanings:
0 - YES -- This equipment can dial the phone.
1 - NO -- This equipment is directly wired to its host
and does not need a modem.
2 - NO -- The equipment is a modem but can't dial the
phone
3 - YES -- The equipment is not a phone, but a hardwired
network. It can "connect" to other machines.
In this case, the menu asks for the machine
name you want to connect to.
$6801 - Dial/connect to the phone number/system name with the
string of ASCII characters starting at $200. The string
is terminated (as are the conventions) by a ZERO. There
is a 40 character maximum.
$6804 - Hangs up the phone. (If the modem/network is capable.)
$6007 - Wait for carrier. (Return if detected, return if time
runs out.)
The control panel does all the controlling. These routines are
used just to do the dirty work.
(See the source code for a look at what it all means...)
Terminal Program Applications Notes:
The control panel:
DCOM.CONTROL lives at $7000 and occupies 2048 bytes. This my
change in the near future if things tend to get as large as they
are starting to. Anyway, this is the simple part.
$7000 - The set up menu
$7003 - The serial card menu.
$7006 - The dialing menu
$7009 - Re-dial/connect to the last number/system
dialed/connected to.
$700C - Disconnect
$700F - Print a message to the screen. (Low byte in x, high in y)
Basically all these do is save the screen, do their bits of
business on a fresh screen, and cover it up when finished. (Using
the saved screen to restore everything.) There is really nothing
to play with here unless you are curious and want to muck with
the internal things.
Terminal Program Applications Notes:
The BASIC program: 'CONFIGURE TERMINAL'
The CONFIGURE TERMINAL program is a very simple piece of code
that just asks 4 or 5 questions and saves the results to a text
file "CONFIG.TERM"
The DATA statements in the program consist of all the possible
screen, serial and 80-column cards. They are divided up by
sections. Which look like this:
xxx DATA TYPE-OF-DRIVER-WE-WANT-TO-INSTALL
xxx DATA SHORT-NAME-OF-CARD
xxx DATA DCOM.xxxx.xxxx (NAME OF DRIVER ON DISK)
xxx DATA LONG NAME (USED WHEN LOADING THE TERMINAL)
--- Repeat the above 3 data statements until all the cards of
that category are exhausted.
xxx DATA *,XX,XX (Indicates the end of a "card section")
--- Start over with the name of the next type of driver to be
installed.
xxx DATA ** (indicates the end of the cards to be installed.)
The file looks like this:
DCOM.MAIN
MAIN DRIVER
DCOM.KEYBOARD.IIE
KEYBOARD DRIVER
DCOM.CONTROL
CONTROL PANEL
DCOM.SCREEN.xxxx
NAME-OF-VIDEO-DRIVER
DCOM.MODEM.xxxx
NAME-OF-SERIAL-DRIVER
DCOM.PERSONALITY.xxxx
NAME-Of-DIALING PERSONALITY
n <-- The slot number of the serial card.
{EOF}
The order of the modules within the file is not important.
The 'HELLO' program just reads the file, and loads each named
file while it prints its name on the screen.
Terminal Program Applications Notes:
Notes on writing your own drivers:
1) Video drivers should use the DCOM.SCREEN.DVISION as the
"reference" driver. You should examine this driver carefully
by printing it out first.
2) Serial card drivers should use the DCOM.MODEM.SSC (Super
Serial Card) driver. This driver is pretty characteristic
of a serial driver. Again print it out first.
3) Avoid using built in ROM as much as possible, as ROM usually
contains very unwanted side-effects. (Did _I_ just say this?)
HERESY! Heresy! Heresy.. Ahh, shedup...
4) BEWARE of the Apple's wonder system of peripheral card
expansion ROM. Some cards enable the $C800-$CFFF space but
don't disable it until another card SPECIFICALLY REQUESTS that
it be disabled. The standard Apple convention to disable the
card occupying the space is to reference the $CFFF location.
So, before you do anything to a peripheral card, read (or
write) to $CFFF and then reference a memory location within
the 256 byte ROM space on the card you want to talk to. If
you don't do this STRANGE things may happen.
5) Don't make any assumptions about using registers. Do not save
any registers because no routine assumes that they are saved.
If ever a section of the terminal dies after adding a new
chunk, just save the registers of the new chunk. If the
program works after that, then I'll have to eat my words.
The video driver has the saved/killed registers in a routine
by routine format in the source listings.
Terminal Program Applications Notes:
That's about it. I do think 18 some-odd pages of documentation
is enough! I've done all the hand-holding I can do. You're on
your own.
Jim Hayes
P.O. Box 221044
University City, CA
92122-1044
(619) 452-0451 (619) 944-3475
^^^^Phone-invalid after June '87 ^^^^SHOULD BE RELIABLE THROUGH
SUMMER of 1990
ARPA: hayes@ucsd.UCSD.edu -or-
hayes@sdcsvax.ucsd.edu
UUCP: [ihnp4, ucbvax]!sdcsvax!hayes