Copy Link
Add to Bookmark
Report
Commodore Hacking Issue 10
########
##################
###### ######
#####
##### #### #### ## ##### #### #### #### #### #### #####
##### ## ## #### ## ## ## ### ## #### ## ## ##
##### ######## ## ## ## ##### ## ## ## ## ##
##### ## ## ######## ## ## ## ### ## ## #### ## ##
##### #### #### #### #### ##### #### #### #### #### #### ######
##### ##
###### ###### Issue #10
################## June 30, 1995
########
------------------------------------------------------------------------------
Editor's Notes
by Craig Taylor
This is my last issue of Commodore Hacking (having finally gotten out the
door, but I couldn't break tradition and get it out on time :-) ). I'm having
to give it up because I've gradually lost interest in Commodore computers over
the years and with the search for a job (anyone wanna hire a csc graduate?)
and as I get older I seem to have less and less time.
I'm gonna be handing the reigns of Commodore Hacking over to Jim Brain, who is
a very active member of the Commodore Internet community. He will also be
running a mailserver that will take the place of mine (Mine will become
unavailable after July 1st and will send pointers to Jim Brain's mailserver).
It's been interesting to watch the Commodore computers evolve, take off like a
rocket and then have Commodore go into liquidation. Commodore computers have
been and still are, (with some exceptions - 1541 head-banging comes to mind),
technologically sound. For a "hacking" machine they're wonderful.
My email address has changed to duck@nando.net. I periodically still check
mail at duck@pembvax1.pembroke.edu but only every 2 weeks or so. I am still
going to try to be in the Commodore community but time will govern my ability
to do that. I'm going to miss editing this rag....
And here is Jim Brain:
Mail Server Changes:
With Issue 10, the address for the Commodore Hacking mail server has changed.
The new address is brain@mail.msen.com The commands are the same as before.
Not all of the files have been moved yet, so please email the administrator
(Jim Brain, brain@mail.msen.com) if a file you need is not on the new site.
Howdy:
Howdy, my name is Jim Brain, and I will be taking over the position of
editor for Commodore Hacking starting with Issue 11. Some of you may know
me as the Commodore Trivia Contest administrator, the USENET newsgroup
comp.sys.cbm FAQ Manitainer, or the keeper of a Commodore Information
WWW Site at http://www.msen.com/~brain/cbmhome.html. Wherever you have
heard of me from, or even if you haven't, I will state that I plan on
handling Commodore Hacking in the following way. The next issue will
possibly look different cosmetically, as I edit somewhat differently than
Craig, but the content and basic layout will remain the same. The types
of material will not change, and the structure for submitting articles will
change only in the address to mail them to: brain@mail.msen.com. However,
I do have a few changes in mind:
1) Try to stabilize the issue generation so that Commodore Hacking will
become a quarterly publication.
2) Attempt a fully "HTML"ized version of the magazine, while still providing a
text version.
3) Pursue the possibility of providing a printed version of these issues
for those who have no online access to them.
4) Encourage User Groups and other CBM related organizations to carry this
magazine for their members.
So, again I say howdy. As always, Commodore Hacking will accept your
articles at any time, so please help us keep this quality magazine running.
If you have any questions or comments about the change in editorship, the
possible changes, or other matters, please feel free to drop me a note.
I look forward to hearing from you and publishing your articles.
Jim Brain
brain@mail.msen.com
===========================================================================
Legal Mumbo-Jumbo
Permission is granted to re-distribute this "net-magazine", in whole,
freely for non-profit use. However, please contact individual authors for
permission to publish or re-distribute articles separately. A charge of no
greater than 5 US dollars or equivlent may be charged for library service /
diskettte costs for this "net-magazine".
-------------------------------------------------------------------------------
Please note that this issue and prior ones are available via anonymous FTP
from ccnga.uwaterloo.ca (among others) under /pub/cbm/hacking.mag and via a
mailserver which documentation can be obtained by sending mail to
"brain@mail.msen.com" with a subject line of "mailserver" and the
lines of "help" and "catalog" in the body of the message.
-------------------------------------------------------------------------------
In This Issue:
Commodore Trivia
Trivia Edition #13-18 are in this article. As you may know, these questions
form part of a contest in which the monthly winner gets a prize (Thanks to my
various prize donators). The whole thing is mainly just for fun, so please
enjoy. Try your hand at Commodore trivia!!
BFLI - New graphics modes 2
FLI gave us more color to the screen, AFLI increased the horizontal
resolution and color selection by using the hires mode. BFLI stands
for 'Big FLI' and gives us 400 lines instead of the usual two
hundred. AFLI and BFLI can be combined, but we are not going into
that.
Making stable raster routines (C64 and VIC-20)
In this article, I document two methods of creating stable raster
routines on Commodore computers. The principles apply for most 8-bit
computers, not only Commodores, but raster effects are very rarely
seen on other computers.
A Differant Perspective - Part III.
Yes!!! It's yet another article on 3D graphics! Even if you
haven't been following this series, you can use this program. This
time around we will write a completely general polygon plotter --
if you can type basic data statements, you can create a three-dimensional
object out of polygons and rotate and project it to your heart's content.
For the more technically inclined we will look at optimizations to the
line routine, EOR-buffer filling, and more! Yow!
Second SID Chip Installation
This article describes how to add a second sid chip for use in SidPlayer and
other programs. As always, be extra careful when making modifications to your
computer.
Solving Large Systems of Linear Equations on a C64 Without Memory
OK, now that I have your attention, I lied. You can't solve dense
linear systems of equations by direct methods without using memory to
store the problem data. However, I'll come back to this memory free
assertion later. The main purpose of this article is to rescue a
usefull numerical algorithm, "Quartersolve", and also to provide a brief
look at the COMAL programming language and BLAS routines.
The World of IRC - A New Life for the C64/128
I've heard people talking about IRC. What is it? Why is it useful to me as a
Commodore user? Bill "Coolhand" Lueck explains the hows and whys in this
article.
SwiftLink-232 Application Notes (version 1.0b)
This information is made available from a paper document published by CMD,
with CMD's permission.
Design and Implementation of a Simple/Efficient Upload/Download Protocol
This article details how to implement a custom upload/download protocol that
is faster than most of the ones common to the C64/128 computers.
Design and Implementation of a 'Real' Operating System for the 128: Part II
There has been a slight change in plans. I originally intended this
article to give the design of a theoretical distributed multitasking
microkernel operating systemfor the C128. I have decided to go a
different route: to take out the distributed component for now and implement
a real multitasking microkernel OS for a single machine and extend the system
to be distributed later. The implementation so far is, of course, only in
the prototype stage and the application for it is only a demo. Part III of
this series will extend this demo system into, perhaps, a usable distributed
operating system.
========================================================================
Trivia
by Jim Brain (brain@mail.msen.com)
Well, summer is upon the Brain household, and things are moving at a fast
clip at the house. However, the trivia still keeps coming. I appreciate
all the people who contribute to the trivia and all the people who take
part in the monthly contest. I have collected Trivia Edition #13-18 in this
article. As you may know, these questions form part of a contest in which
the monthly winner gets a prize (Thanks to my various prize donators).
The whole thing is mainly just for fun, so please enjoy.
As the summer months start up, news on the trivia includes:
1) I now have access to some more orphan machines (C65, C116), so expect
some trivia questions on those models.
2) The new home now has a number of machines set up, so testing answers to
the trivia is even easier. I am still trying to get the old PET
machines in house, but the others are here.
3) The Commodore World Wide Web Pages (http://www.msen.com/~brain/cbmhome.html)
that I maintain and place the trivia on caught the eye of USA Today and
the Pheonix Gazette. I was interviewed for both articles. Look in the
June 20th edition of USA Today for the segment, and possibly a picture of
Jim Brain and the machines he uses to create the trivia.
As always, I welcome any questions (with answers), and encourage people
to enter their responses to the trivia, now at #18.
Jim.
The following article contains the answers to the December edition of trivia
($0C0 - $0CF), the questions and answers for January ($0D0 - $0DF),
February ($0E0 - $0EF), March ($0F0 - $0FF), April ($100 - $10F), and the
questions for the May edition ($110 - $11F). Enjoy them!
Here are the answers to Commodore Trivia Edition #13 for December, 1994
Q $0C0) The early 1541 drives used a mechanism developed by ______. Name
the company.
A $0C0) Alps.
Q $0C1) On later models, Commodore subsequently changed manufacturers
for the 1541 drive mechanism. Name the new manufacturer.
A $0C1) Newtronics.
Q $0C2) What is the most obvious difference(s). (Only one difference is
necessary)
A $0C2) Alps: push-type latch, round LED.
Newtronics: lever-type latch, rectangular LED.
Q $0C3) On Commodore BASIC V2.0, what answer does the following give:
PRINT (SQR(9)=3)
A $0C3) 0. According to Commodore BASIC, the answer should bby -1, which
is the BASIC value of TRUE. However, the above equation is NOT
true. Doing PRINT SQR(9) yields 3, but doing PRINT (SQR(9)-3)
yields 9.31322575E-10 (C64). This anomaly can be attributed to
roundoff errors in the floating point math routines in Commodore BASIC.
Q $0C4) In Commodore BASIC (Any version) what does B equal after the following
runs: C=0:B=C=0
A $0C4) B = -1. The second statement is the one to look at. The second
equals sign is treated as a comparison, while the first is treated
as a assignment. B gets set to the outcome of the comparison, which
is TRUE (-1).
Q $0C5) The first PET cassette decks were actually _______ brand cassette
players, modified for the PET computers. Name the comapny.
A $0C5) Sanyo. Specifically, Model M1540A. What a model number!
Q $0C6) In Commodore BASIC (Any version), what happens if the following
program is run:
10 J=0
20 IF J=0 GO TO 40
30 PRINT "J<>0"
40 PRINT "J=0"
A $0C6) On BASIC 2.0 or greater:
?SYNTAX ERROR IN 20
READY.
On BASIC 1.0: (found on the PET 2001 series)
J=0
READY.
BASIC 1.0 totally ignored spaces, so line 20 became "IFJ=0GOTO40".
That statement would be correctly parsed, sicne it contains the "GOTO"
keyword.
However, on BASIC 2.0 or greater, spaces weren't ignored so
completely, and the "TO" in "GO TO" would be tokenized separately, so
some code was added to BASIC to check to "GO". As the code that
accepts GOTO as a special case for THEN after an IF statement wasn't
patched this way, the above fails, because GO is not a valid keyword
after IF. The statement SHOULD work correctly, but does not because
of this failure to fix the IF command parsing.
On BASIC 2.0 or greater, substituting the following line for line 20
will cause the program to work:
20 IF J=0 THEN GO TO 40
Q $0C7) In question $068, we learned how Jack Tramiel first happened upon the
name "COMMODORE". According to the story, though, in what country
was he in when he first saw it?
A $0C7) Germany.
Q $0C8) On the Commodore user port connector, how many edge contacts are
there?
A $0C8) 24. Two rows of 12 contacts each.
Q $0C9) On most Commodore computers, a logical BASIC screen line can contain
up to 80 characters. On what Commodore computer(s) is this not true?
A $0C9) According to Commodore documentation, a _physical_ screen line is
defined as one screen line of characters. A _logical_ screen line is
defined as how many _physical_ lines can be chained together to
create a valid BASIC program line.
With that in mind, most Commodore computers chose a _logical_
screen line that was a multiple of the screen width. This works fine
for 40 and 80 column screens, but what do we do with the VIC-20, with
its 22 column screen. Solution: make the _logical_ line length equal
to 4 _physical_ lines, or 88 columns.
When the Commdore 128 was introduced, the number rose to 160
characters, which is 4 _physical_ lines in 40 column mode, or
2 _physical_ lines in 80 column mode. However, you can only take
advantage of this in 128 mode. 64 mode is limited to 80 characters.
To add to all this confusion, a valid BASIC program line (in memory)
can actually be 255 (tokenized) characters long, but creating such
a long line cannot be done from the built-in editor in direct mode.
The AmigaBASIC, available on the Amiga, also does not have the 80
column line limit. However, that BASIC is SOOO much different that
I am not surprised. The older CBM BASICs, on the other hand, were
all derivatives of the original Level 1 BASIC for the PET.
Q $0CA) If a file is saved to a Commodore Disk Drive with the following
characters: chr$(65);chr$(160);chr$(66), what will the directory
entry look like?
A $0CA) The filename will show up as "A"B, with the 'B' showing up to the
right of the '"' mark. This could be used to make program loading
easier. A file that showed up as "filename",8,1 could be loaded
by simply hitting shift-run/stop on that line.
Q $0CB) What is the maximum length (in characters) of a CBM datasette
filename?
A $0CB) References I have on hand say 128 characters. However, the actual
code on the 8032 and the C64 acts as though 187 characters can
actually be sent (tape buffer-5 control bytes = 192-5=187). The
references that claim 128 characters are Nick Hampshire's
_The VIC Revealed_ and _The PET Revealed_. ANyone care to lay
this one to rest?
Q $0CC) How many keys are on a stock Commodore 64 keyboard?
A $0CC) 66 keys. This is the same number as found on the VIC-20 and the
Commodore 16.
Q $0CD) Commodore BASIC uses keyword "tokens" to save program space. Token
129 becomes "FOR". What two tokens expand to include a left
parenthesis as well as a BASIC keyword?
A $0CD) TAB( (163) and SPC( (166).
Q $0CE) There are 6 wires in the Commodore serial bus. Name the 6 wires.
A $0CE) 1) Serial /SRQIN
2) GND
3) Serial ATN IN/OUT
4) Serial CLK IN/OUT
5) Serial DATA IN/OUT
6) /RESET
Q $0CF) On the Commodore datasette connector, how many logical connections are
there?
A $0CF) 6. Opposing pins on the connector are hooked together electrically.
Here are the answers to Commodore Trivia Edition #14 for January, 1995
Q $0D0) How many keys were there on the "original" PET and what was special
about them?
A $0D0) the original PET had 73 calculator-style keys that were laid out
in a rectangular matrix, not typewriter-style.
Q $0D1) How do you produce the "hidden" message(s) on the Commodore 128?
A $0D1) SYS 32800,123,45,6. The screen will clear, and the software
and hardware developers on the 128 project will be named.
The exact text is as follows:
[RVS] Brought to you by...
Software:
Fred Bowen
Terry Ryan
Von Ertwine
Herdware:
Bil Herd
Dave Haynie
Frank Palaia
[RVS]Link arms,don't make them.
Q $0D2) How much memory did the "original" PET show on bootup?
A $0D2) The "original" PET came in two configurations, 4K and 8K, so:
The PET 2001-4 had 3071 bytes.
The PET 2001-8 had 7167 bytes.
Q $0D3) We all know the "reboot" sys for the 64 is sys 64738, but who knows
the same sys location to reboot the CBM 8032?
A $0D3) sys 64790
Q $0D4) Which computer(s) beeped at bootup? (May be more than one, but only
one required)
A $0D4) I know some of these are corect, but the sheer size of the
list prevents me from checking them ALL out.
FAT 40XX series
80XX series
PC-10 (I suspect a number of IBM clones did, and these things have
no consistent naming convention across country boundaries.)
PC-20
Amiga 1000
SP9000 (SuperPET)
Q $0D5) How much memory did the CBM 8032 show on bootup?
A $0D5) 31743 bytes.
Q $0D6) Certain Commodore computers provided emtpy EPROM sockets on the
motherboard. Give me the number of empty sockets on the following
machines:
a) CBM 30XX.
b) CBM 8XXX.
c) CBM C128.
d) Plus/4.
A $0D6) a) 3 sockets.
b) 2 sockets.
c) 1 socket.
d) 1 socket.
Q $0D7) In Germany, the CBM 8032 came with a 4kB EPROM for the EXXX area,
while the US version only had a 2kB EPROM. Why?
A $0D7) The German version had additional keybaord drivers for umlaut
characters and dead keys.
Q $0D8) Who published the first PET memory map in the "PET Gazette"?
A $0D8) None other than the infamous Jim Butterfield.
Q $0D9) Which is faster to move the sursor on a PET/CBM or C64: SYS or
PRINT?
A $0D9) PRINT is faster, since the sys approach must process the pokes
before the sys, which are very slow.
Q $0DA) On the Amiga 1000, where are the signatures of the first Amiga
developers located?
A $0DA) Inside the top case of the Amiga (1000).
There is an interesting footnote to this question. It seems
that at least some original Amiga machines were labeled as
Amiga (with nu number). Then, at some later point, the number was
added. In addition, Commodore produced some Amiga 1000 machines
without the signatures, but most had the telltale handwriting on
the inside of the case.
Q $0DB) On the 6502, what does the accumulator contain after the following
is executed:
lda #$aa
sed
adc #01
A $0DB) Assume carry was clear. If so, then $11 is the correct answer.
Q $0DC) What is the model number of the US NTSC VIC-II chip?
A $0DC) Its first number was 6567, and that is the number most people know
it by, but Commodore produced a VIC-II using a new manufacturing
process that was numbered the 8562.
Q $0DD) What is the European PAL VIC-II chip's model number?
(Not sure if that's its rightful term, but I hope you understand).
A $0DD) Same here. The part number 6569 is the most remembered number, but
an 8565 will work as well.
Q $0DE) Assume you have two computers, one with each of the above chips inside.
Which chip draws more pixels on the screen per second?
A $0DE) Note, for the purposes of the calculation I am performing, "pixels"
refers to picture elements that can be adddress and modified using
normal VIC modes, so there are 320*200 "pixels" on both the PAL
and NTSC screens. (I probably should have stated this, but it is
too late now.) Also, the screen refresh rates used in the
calculations are those defined by the respective television
standards (60Hz U.S., 50Hz European), even though the actual
frequencies are off by a small percentage. (for example, the actual
50Hz refresh rate on European VIC-II chips was calculates as
50.124567Hz by Andreas Boose)
So, the PAL draws 320*200*50 pixels per second = 3200000 pixels/s
NTSC draws 320*200*60 pixels per second = 3840000 pixles/s
Now, some people thought I meant the whole screen, not just the
display area provided by the VIC-II chip. Well, I am not sure
exactly you calculate pixels on a screen, since the numbers could
vary from display to display, but if we measure in scanlines:
PAL = 312 scanlines * 50 = 15600 scanlines/s
NTSC = 262 scanlines * 60 = 15720 scanlines/s
The NTSC machines wins both ways.
Q $0DF) In Commodore BASIC, which statement executes faster:
a = 2--2
or
a = 2+2
A $0DF) b is the correct answer, and there are a couple of reasons why:
1) 2--2 takes longer to parse in the BASIC interpreter.
2) Commodore BASIC subtracts by complementing the sign of the
second number and adding. This incurs extra time.
There are even more subtle ones, but I leave them as an
exercise for the reader. Send me your reason why.
Here are the answers to Commodore Trivia Edition #15 for February, 1995
Q $0E0) What is the difference(s) between the Newtronics 1541 and the 1541C?
(only one difference is needed)
A $0E0) (George Page, a noted authority on CBM Drives, indicated that Commodore
made this a tough question to answer.) By the time the 1541C was
introduced, Commodore threw a number of drives together and called
them 1541Cs. The theoretical 1541C exhibited the following
features:
No head banging, and other problems fixed by modified ROMs.
Case color matches C64C and C128 computers.
Q $0E1) What happens when you type 35072121 in direct mode on the C64 and
hit return?
A $0E1) Simple answer: Most likely, the screen clears and the word READY.
is printed at screen top. This is the behavior seen when pressing
RUN-STOP/RESTORE. Alternately, nothing could happen, or the computer
could lock up.
Involved answer: There is a bug in BASIC 2.0. Easily fixed, but
destined to live life immortal. (long)
The bug is in the PETSCII number to binary conversion routine at
$a69b (LINGET). The routine basically reads in a character from the
line, multiplies a partial result by 10 and adds the new character
to the partial result. Here is a code snippet:
a96a rts
a96b ldx #$00 ; zero out partial result
a96d stx $14
a96f stx $15
a971 bcs $a96a ; not a number, return
a973 sbc #$2f ; PETSCII to binary
a975 sta $07
a977 lda $15 ; get hi byte or partial result
a979 sta $22
a97b cmp #$19 ; partial > 6399
a97d bcs $a953 ; yes, goto error
a97f lda $14 ; load lo byte of result
a981 asl ; lo*2
a982 rol $22 ; hi*2 + c
a984 asl ; lo*2
a985 rol $22 ; hi*2 + c
a987 adc $14 ; complete lo*5
a989 sta $14
a98b lda $22
a98d adc $15 ; complete hi*5
a98f sta $15
a991 asl $14 ; lo*2 complete lo*10
a993 rol $15 ; hi*2 complete hi*10
a995 lda $14
a997 adc $07 ; add new char
a999 sta $14
a99b bcc $a99f ; did lo overflow?
a99d inc $15 ; yes, inc hi
a99f jsr $0073 ; get next char
a9a2 jmp $a971 ; go through it again.
The problem is at $a97d. when the partial result is greater than 6399,
(if partial > 6399, then new partial result will be over 63999)
the routine needs to get to $af08 to print an error, but can't due to
branch restrictions. However, a branch that will get there is in the
preceding function, which handles the ON GOTO/GOSUB keywords ($a94b,
ONGOTO).
So, the BASIC writers just branched to the code in ONGOTO; specifically
$a953:
a94b jsr $b79e
a94e pha
a94f cmp #$8d ; is the keyword GOSUB ($8d)
a951 beq $a957 ; yes
a953 cmp #$89 ; is the keyword GOTO ($89)
a955 bne $a8e8 ; no, print SYNTAX ERROR.
a957 ... ; handle ON GOTO/GOSUB
This code is checking to make sure the ON (var) is followed with a
GOTO or GOSUB keyword.
The LINGET error handler branches to $a953, which compares
.A (which holds hi byte of partial result) to $89. Normally, this
fails, and the normal SYNTAX ERROR code is reached through the branch
to $a8e8. However, for partial results of the form $89XX, the check
succeeds, and BASIC tries to execute an ON GOTO/GOSUB call.
By the way, it is no coincidence that this error occurs on 35072121,
since one of the partial results is $8900 (hi byte is $89). In fact,
350721 will achieve the same result.
If the check succeeds, the code limps along until $a96a:
a969 pla ; complement to $a94e
a96a rts ; return
But we never executed $a94e, the push, so the stack is now
messed up. Since the stack held $9e, $79, $a5 before the PLA,
(The stack could hold other values, but I always saw these)
the RTS gets address $a579 to return to, which usually holds a BRK
opcode. The break handler is invoked, and the screen clears with the
READY. at the top.
Now, the BASIC 2.0 authors were justified in reusing the error
handler code in ONGOTO for LINGET, but they calculated the branch
offset wrong, according to my tests. If you have the LINGET error
handler branch to $a955, all these troubles disappear. You can
verify this procedure with the following BASIC program on a 64:
10 for t=57344 to 65535:poke t,peek(t):next
20 for t=40960 to 49151:poke t,peek(t):next
30 poke 43390, 214
40 poke 1, peek(1) and 254
Just to be complete, this error occurs when a 6 digit or greater line
number is entered and the first 6 digits indicate a number in the
range 35072-35327 ($8900-$89ff). Also, it appears the error occurs
on the VIC-20, but I didn't completely verify it. It would be
interesting to note if the error is found on all version of CBM BASIC.
Whew, what a mouthful.
Q $0E2) If a SID chip is producing a "sawtooth waveform", does the waveform look
like:
a) "/|/|/|/|" or
b) "|\|\|\|\" ?
A $0E2) a is the correct answer.
Q $0E3) On BASIC 2.0, what special precaution(s) must one take when working with
relative files? (only one is needed)
A $0E3) Because BASIC 2.0 doesn't handle positioning in relative files quite
right, one must position the relative file pointer before AND AFTER
a read or write to a relative file.
Q $0E4) What incompatibility existed between C128 Rev. 0 ROMS and the REU?
A $0E4) OK, I admit it. I placed this answer and its discussion somewhere
in my store of information, and it must have fallen behind the
cabinet, because I cannot find it. I will post an answer to this
as soon as I can find it, but the answers really must go out, as
they have been held up long enough.
Q $0E5) What can trigger an NMI interrupt? (count all sources on one chip as
one)
A $0E5) The following sources can trigger an NMI interrupt:
1) The expansion port.
2) CIA #2.
3) The RESTORE key.
Q $0E6) What can trigger an IRQ interrupt? (count all sources on one chip as
one)
A $0E6) The following sources can trigger an IRQ interrupt:
1) The VIC-II chip.
2) CIA #1.
3) The expansion port.
Q $0E7) Where is the ROM in a 1541 located in the 64K memory map?
A $0E7) The ROM is located from $C000 to $FFFF, yet the ROM code does not
begin until $C100.
Q $0E8) Which VIA on the 1541 is hooked to the read/write head?
A $0E8) VIA #2, located in memory from $1C00 to $1C0E.
Q $0E9) In the Commodore DOS, what bit in the file type byte denotes a "locked"
file?
A $0E9) bit 6.
Q $0EA) If files are "locked" under Commodore DOS, under what condition(s) may
the file be changed?
A $0EA) Depending on the file, the following operations can be done on a
locked file:
1) Rename will change file name, although not contents of file.
2) Random access can be used to alter file.
3) Formatting the disk will alter the file. (duh!)
4) Save-with-replace (@0:) will replace file and unlock it.
5) Opening file in append mode will allow it to be changed, and
unlock it.
6) Opening a relative file and adding or changing a record will
succeed and unlock file.
Q $0EB) How big can a program file be on a 1541 or similar?
A $0EB) The file can be as large as a sequential file, since both are stored
in the same way: 168656 bytes. However, since a program contains its
load address as bytes 0 and 1, the largest program size is 168654
bytes.
Q $0EC) Under BASIC 2.0, how does one open a random access file on a disk
drive?
A $0EC) Random access (or direct access) files are a misnomer. What you
really doing is opening the disk for reading and writing. You need
two open command to access a random file: (assume drive 8)
open 15,8,15 and
open 1,8,4,"#1" will open a random access file using buffer 1.
open 1,8,4,"#" will open a random access file using the first
available buffer
Now, by using B-R, B-W, B-A or their replacements, you can write
data to sectors on the disk.
Note that Random access files are different from relative files.
Q $0ED) A file that has a '*' immediately before the filetype is called
a _________ file.
A $0ED) a splat file. This is its correct term, believe it or not.
Q $0EE) We know the 1541 and similar drives have 5 internal buffer areas, but
how many does an 8050 drive have?
A $0EE) Since the 8050 has twice the on-board RAM (4kB), it has 16 buffers, but
only 13 are available. (All CBM drives use one buffer for zero-page
memory, one for stack memory, and one for temporary variables.)
Q $0EF) On a "save-with-replace", where is the location of the first track and
sector of the new copy of the program saved in the directory entry for
the old copy?
A $0EF) The new first track is stored at location 26, and the new first sector
is stored at location 27. These values are copied to their
correct locations after the save is completed.
Here are the answers to Commodore Trivia Edition #16 for March, 1995
Q $0F0) What size matrix of pixels comprises a character on a PET 2001
computer?
A $0F0) The matrix was 8 by 8.
Q $0F1) How many bytes did the opening screen on a CBM 4016 show as
available for use by BASIC?
A $0F1) 15359 bytes free.
Q $0F2) The character set that produces uppercase letters on unshifted keys
is the ________________ character set.
A $0F2) "standard mode".
Q $0F3) The character set that produces lowercase letters on unshifted keys
is the ________________ character set.
A $0F3) "alternate mode"
Q $0F4) To get to the set mentioned in $F2, what character code would be
printed to the screen?
A $0F4) chr$(142)
Q $0F5) What character code would one print to the screen to invoke the
chararacter set in $F3?
A $0F5) chr$(14)
Q $0F6) If one does LIST 60-100, will line 100 get "listed"?
A $0F6) Yes. The above translates as: LIST 60 through to and including 100.
Q $0F7) The abbreviation for the BASIC 4.0 command "COLLECT" is ________.
A $0F7) coL. "C" "O" "SHIFT-L". For those who are interested, the
COLLECT command is analogous to the VALIDATE operation.
Q $0F8) When you use a subscripted variable in BASIC, how many elements
are created by default if no DIM statement is issued?
A $0F8) 11 elements. A(0) - A(10). Almost everyone who has ever programmed
in Commodore BASIC has seen the "BAD SUBSCRIPT" error when they try
to use the 12th element in a un-DIMensioned array.
Q $0F9) How large is the keyboard buffer in CBM computers?
A $0F9) 10 bytes. Since this area could be POKEd to, many boot programs
would poke characters into this buffer to simulate keypresses.
Q $0FA) On the Commodore 1581, how large is a physical sector in bytes?
A $0FA) A physical sector is 512 bytes in length. Internally, the 1581
creates 2 256 "logical" sectors in a physical sector, to maintain
compatibility with older Commodore drives.
Q $0FB) You'll find BASIC 3.5 on the _____________ line of CBM computers.
A $0FB) The X64 series. That includes the Commodore 16, the Commodore 116,
and the Commodore Plus/4.
Q $0FC) On the Commodore 1351 mouse, what registers in the Commodore
computer would the X and Y proportional information be read
from?
A $0FC) Even though you are looking for digital information (how far the
mouse has traveled since the last movement in a particular axis),
the information is read from the "paddle" or potentiometer (POT)
registers. On the C64, the POT registers are part of the SID
chip, and are at 54297 ($D419) for POTX, and 54298 ($D41A) for
POTY.
Q $0FD) What is the maximum size of a sequential file on a 1581 drive?
A $0FD) 802640 bytes.
Q $0FE) What flaw exists in the early Commodore 1670 modems?
A $0FE) When the 1670 modem was first introduced, it powered up in auto-
answer mode, which means it would answer incoming calls after
the phong rang. You could turn this feature off through software
control, but if the power was reset, the modem would answer the
phone. So many people complained to Commodore that CBM revised
the 1670 to include an extra DIP switch that turned this feature
off.
Q $0FF) What is the model number of the first modem for the VIC and C64?
A $0FF) The 1600 manual dial/manual answer 0-300 bps modem. The author
owns one, and used it for many years. To operate, you must use
a phone with a detachable handset cord. You dialed the number
on the phone, waited for the answer, unplugged the handset, and
plugged the cord into the 1600. A switch toggled between using
originate or answer frequencies. The 1600 was manufactured by
Anchor Automation for Commodore. (As an aside, this unit claimed
300 bps, but I never could get 300 to work well. Most of my
telecommunications happened at 150 bps.)
-------Commodore Trivia Edition #17 Questions and Answers (BEGIN)--------
Q $100) On the MOS Technology's KIM-1, how many keys were on the keypad?
A $100) 23 keys. The keypad has room for 24, but one spot is taken by
a switch that puts the system into single-step mode. Interestingly,
some pictures have the switch on the upper left, some on the upper
right.
Q $101) The KIM-1 keypad had the common 0-9A-F keys on the keypad, but
also had some special keys. Name them.
A $101) GO (Go) Executes an instruction and displays the address of next,
ST (Stop) Stops execution of program and return control to monitor,
RS (Reset),
AD (Address) Address entry mode,
DA (Data) Data entry mode,
PC (Program Counter) Displays and restores program counter to values
in PCL and PCH,
+ (Increment) Increments the address without changing the entry mode.
Q $102) The KIM-1 was a set of modules that could be plugged together to
expand the system. Each module had a model number. What was the
model number of the KIM-1 motherboard?
A $102) The KIM-4.
Q $103) On the 1525 line of printers, if you wanted to create the following
graphic, what bytes would you send to the printer after turning on
graphics mode?
****
* *
* *
* *
* *
* *
****
A $103) I guess I should have stipulated that this is a bitmap. ASCII just
has a few limitations. Anyway, the correct bytes to send are:
255, 193, 193, 255. You got these by assigning each bit in a column
a value, and adding 128 to the result for each column.
Q $104) What is the horizontal resolution of the 1525 line of printers?
A $104) Character resolution: 80 chars, or 10 chars/inch (cpi).
Graphics resolution: 480 dots, or 60 dots/inch (dpi).
Q $105) On Commodore drives, explain the difference between the B-R command
and the U1 command.
A $105) The two commands read in data from a disk sector. However, the
U1 command always reads a full sector (255 bytes). The B-R
command reads the number of bytes specified in the first byte of
the sector. If the first byte is a 15, B-R will read 15 bytes
from the sector. (From the 1581 manual)
Q $106) On the Commodore 1541 drive, what does the U: command do?
A $106) This command has been traditionally used to reset Commodore drives,
including the CBM 1541. However, some early versions of the Drive
DOS did not correctly handle this command. In these versions, the
drive and computer failed to complete the command transaction
successfully, and what looked like a hung machine resulted.
Commodore later fixed this problem. If U: seems to not work on
your drive, try U; instead.
Q $107) What does the first routine in the 1541 drive ROM actually do?
A $107) The function, called SETLDA and residing at $C100, turns on the
drive active LED for the current drive. The routine loads the
current drive from $7F and sets bit 3 of DSKCNT ($1C00).
Q $108) How many files will a 1581 disk drive hold?
A $108) 296 files. Note that it is not a multiple of 144.
Q $109) Commodore 1581 drives have a special "autoboot" feature that enables
the drive to load and run a program off a disk upon drive bootup.
What is the required name of the file?
A $109) COPYRIGHT CBM 86
Q $10A) What filetype must the file mentioned in $109 be?
A $10A) USR.
Q $10B) To power up a 1351 mouse in "joystick mode", what must the user do?
A $10B) If one depresses the right mouse button during power-up, the 1351
will behave just like a joystick.
Q $10C) Describe the contents of the POTX or POTY registers when using a
1351 mouse.
A $10C) Each register holds the same type of information, just for a
separate axis, so we will describe just one register:
Bit: Function
7 Don't care
6-1 Mouse axis position mod 64.
0 Noise Bit. (check this bit to see whether mouse has moved)
Q $10D) Commodore computers typically use most of zero page for temporary
variables and other items. However, both the VIC-20 and the 64
reserve 4 bytes for user programs that need zero page memory. Where
are these locations?
A $10D) $FB-$FE (251-254). I am not sure these were "reserved" for
programmers as much as they were just not utilized by the
CBM programmers.
Q $10E) Name the 16 colors available on the 64.
A $10E) Black
White
Red
Cyan (Light Blue-Green)
Purple
Green
Blue
Yellow
Orange
Brown
Light Red
Dark Gray (Gray 1)
Medium Grey (Gray 2)
Light Green
Light Blue
Light Gray (Gray 3)
Q $10F) Both the VIC-20 and the C64 emulate the operation of the 6551 UART.
How many "mock 6551" registers are mapped into the memory map?
A $10F) 5, from $293-$297 (659-663). The register contents:
$293 6551 Control Register
$294 6551 Command Register
$295-6 6551 User Defined Baud Rate value.
$297 6551 Status Register
------------Commodore Trivia Edition #18 Questions (BEGIN)--------------
Q $110) What is the name of the company that recently purchased the
liquidated Commodore assets?
Q $111) At one time, Commodore attempted to manufacture a dual drive
version of the 1571 called the 1572. For what technical reason
did it utimately fail?
Q $112) Over what computer system did a User Group sue Commodore and win?
Q $113) In $103, the question asked how to create a graphic of a small box
on the 1525. In this quesrtion, we have made a different design.
If you wanted to create the following graphic using individual
dots on the printer, what bytes would you send to the printer after
turning on graphics mode?
** * *
* ***
* ** ***
* * * * *
** ** * *
* *
**
Q $114) (Some C65 questions) How many SID chips does the the development
Commodore 65 machine contain?
Q $115) What CPU does the Commodore 65 use?
Q $116) What is the alternate name for the Commodore 65?
Q $117) How many processors does the internal 1581-compatible drive
on the C65 contain?
Q $118) In the tradition of naming certian ICs after famous cartoon
characters, one of the ICs in the C65 is named after a Warner
Brothers cartoon character. Which one?
Q $119) What version of BASIC is included on the Commodore 65 in C65 mode?
Q $11A) How many I/O ports does a Commodore 65 contain?
Q $11B) What common Commodore 64 I/O port does the C65 NOT have?
Q $11C) How many function keys are on a Commodore 65?
Q $11D) What CBM disk drive DOS was used as the template for the internal
C65 drive DOS?
Q $11E) What resolution of text screen does the C65 power up in? (Please
give answers in characters).
Q $11F) What distinguishing non-textual characteristic in the C65 is not
present in othe Commodore 8-bit computers?
The information in this between the lines marked by (BEGIN) and (END)
is copyright 1995 by Jim Brain. Provided that the information
between the (BEGIN) and (END) lines is not changed except to correct
typographical errors, the so marked copyrighted information may be
reproduced in its entirety on other networks or in other mediums. For
more information about using this file, please contact the address
shown below.
Jim Brain
brain@mail.msen.com
602 North Lemen
Fenton, MI 48430
(810) 737-7300 x8528
Some are easy, some are hard, try your hand at:
Commodore Trivia #18!
========================================================================
BFLI - New graphics modes 2
by Pasi 'Albert' Ojala <albert@cs.tut.fi>
One day I was watching some demos that used linecrunch routines for
whole-screen multicolor-graphics upscrollers. I already had my
theories about how and why linecrunch worked, but because I had not
used it anywhere, the details were a bit vague. In fact, I have
many times accidentally created linecrunch effects when trying to do
something else with $D011. Probably every demo coder has.
But you learn by doing. I had the idea of using linecrunch for FLI
instead of a simple multicolor picture as it always seemed to be
used. However, this has probably been done before and because I
don't like to do things that have been done before, I decided to use
linecrunch to show a two-screen-tall FLI picture.
_Linecrunch Basics_
For those not familiar with linecrunch routines: linecrunch is used
to scroll the screen UPWARDS by convincing VIC-II that it has
already showed more character rows than it in reality has shown.
Surprisingly (or then, maybe not :) this consists of fiddling with
$D011. The timing is critical as always.
Linecrunch works by setting $D011 equal the line before the current
line and VIC-II will happily think that it is time to move on to the
next character row - add 40 to the video matrix counter, 320 to the
graphics memory counter and be ready to start a bad line. Or, maybe
'NOT to go back to the current row' would be a more suitable
description. (Programming VIC-II is slowly becoming a science.)
The required timing also does not cause bad lines so that you can
skip another line immediately on the successive line. In addition,
lines can be skipped only after the first character row and half of
the second character row have been displayed. This has something to
do with the way VIC-II decides when there is a bad line.
Because linecrunch causes VIC-II to skip rows, it will run out of
video matrix and color memory (and graphics memory) before reaching
the end of the screen. However, VIC-II does not stop displaying the
graphics nor does it reset the internal counters. The counters keep
on running and wrap around instead.
Normally, when VIC-II is displaying the last character row, it is
showing the memory from offsets $3c0 to $3e7. If VIC-II has skipped
one character row, it is displaying from $3e8 to $40f instead. But,
there are only 10 bits for the video matrix counter (0..1023), so it
wraps around to zero after $3ff. This means that the beginning of
the video matrix is displayed at the bottom of the screen. The
character rows become shifted by 24 character positions to the right
because there were originally 24 unused memory locations at the end
of the memory (1000..1023). (To be honest, sprite image pointers
are not unused memory, but they are not used with normal FLI.)
____________________ ____________________
|abcdefghijklmnopqrst| |abcdefghijklmnopqrst|
| | |--------------------| <- Skipped row
: : : :
: : : :
: : : :
| | |normally last line |
|normally last line | |XXXXXXXXZZZZabcdefgh|
`--------------------' `--------------------'
X = unused mem (1000..1015)
Z = sprite pointers (1016..1023)
Figure 1: Linecrunch
The same thing happens for color memory because it uses the same
counter for addressing the memory (in fact, color memory access and
character data access are performed simultaneosly, 12 bits at a
time). The graphics memory behaves the same way, except that the
counter has three bits more and it counts at eight times the speed,
so that it wraps at the exact same time as the other counter.
The first character row can't be used for linecrunch and the second
one is also lost in the process. The first usable line to display
is the third character row. However, those two lost rows can still
be used as an extension at the end of the first screen. You must
notice, however, that the alignment has been changed. After these
two rows have been displayed, the video bank is switched to get new
fresh data on the screen.
_Back to BFLI_
Wrapped data is nothing difficult to work with. It is just the
matter of writing the right conversion program. Also, the normal
FLI routine can be used, we just have to make sure VIC always has
the right bank visible - simple LDA bank,x:sta $DD00 can accomplish
that. The more difficult aspect is to make the display freely
locatable. We have 32 kilobytes of graphics data, this is the main
reason we can't even think about using copying. Linecrunch combined
with the bad line delaying technique will do the job much more
nicely.
Figure 2 shows the principles. To make things simpler I have chosen
location 0 to mean that the top of the picture is visible, 1 means
that the picture is scrolled one line upwards and so on. We can see
that linecrunch is not used at all for the location 0. To make the
picture start at the same point whether linecrunch has crunched
lines or not we compensate the non-lost raster lines by delaying the
next bad line. When the location is n*8 (n=0,1,2..), the sum of the
linecrunched and delayed lines is constant - the graphics display
always starts at the same point.
Then how do we deal with the location values that are not evenly
dividable by eight ? Now, lets assume that the location is L, and
we have C, which is the location divided by eight (C = L/8), and R,
which is the remainder (R = L%8). To make the picture scroll to the
right position, we need to delay the bad line less than before - R
lines less for location L than for location C*8. E.g. for location
2 we delay the bad line two lines less than for location 0. This
also shows that we need 7 lines more than is needed for to
compensate for the linecrunch.
Determining the number of linecrunch lines is a recursive process,
because when you use more linecrunch lines, that decreases the
number of lines you have available for the display and you need
bigger range for the location value. The linecrunch can be started
after 12 lines, and we need at least 7 lines to use the soft
y-scroll. This makes 181 lines available for the display
originally.
Because we need to show 400 lines of graphics, we would need
(400-181)/8=28 linecrunch lines. However, this in turn reduces the
number of lines we have for graphics to 181-28=153 and we need
(400-153)/8=31 linecrunch lines. Again, 181-31 is 150. We get
(400-150)/8=32 and there it finally converges and we have 149 lines
for graphics, which makes location values 0..251 valid.
Location 0 1 2 .. 8 9 .. 251
___________________.. ___________.. ________
___________________.. ___________.. ________
Linecrunch -------------------.. ___________..
^ ^ ^
| | | ^ ^
| | | | |
Bad line delayed| | | | |
| | | | | ========
| | v | | 244
| v ___.. | v :
v ________0 v ___.. :
Gfx Enabled ________0_______1__.. ________8__.. 250_____
0 1 2 8 9 251
1 2 3 9 10 252
2 3 4 10 11 253
3 4 5 11 12 254
4 5 6 12 13 255
5 6 7 13 14 256
6 7 8 14 15 257
7 8 9 15 16 258
: : : : : :
: : : : : :
148 149 150.. 156 157.. 399
Figure 2: Linecrunch and DMA delay in BFLI
(Graphics lines not in scale)
_Clipping added_
Now we can scroll the picture to any location we want, but the top
of the picture is not clipped and it is very annoying to watch. We
need to enable the graphics at the same point regardless of the
y-scroll value. The answer is in the extended color mode (ECM).
When both ECM and multicolor mode (MCM) are selected, VIC-II will
turn the display to black. This is because there is a conflicting
situation and it just can't decide which color scheme to use. The
video accesses will continue to happen just like before, the data is
just not displayed. When the ECM bit is cleared again, the normal
multicolor graphics is shown.
So, we set the ECM bit and start to display the first eight lines of
the FLI. Because the FLI routine already writes to $D011, we just
make sure the ECM bit is set in the first R number of writes to
$D011 and zero in all other.
The viewer is now 'complete'. You can take a look at the code below
or you can get C64Gfx1_4.lha and see it in action yourself and not
just rely on my word. The package includes converter programs for
BFLI, FLI and Koala (ANSI-C), couple of example pictures and viewers
for PAL and NTSC machines.
-Pasi 'Albert' Ojala albert@cs.tut.fi
--------------------------------------------------------------------------
BFLI viewer program for PAL machines
UPOS = $C00 ; temporary area for tables
BANK = $D00 ; UPOS for linecrunch, BANK for FLI bank select
RASTER = 29 ; where to position the sprite -> IRQ 20 lines later
DUMMY = $FFF ; dummy location for timing purposes
FLISZ = 19-1 ; visible FLI size in character rows - 1
*= $810
SEI
LDA #$7F:STA $DC0D ; IRQ setup
LDA #1:STA $D01A
STA $D015:STA KEYW+1
LDA #<IRQ:STA $314
LDA #>IRQ:STA $315
LDA #RASTER:STA $D001:CLC:ADC #20:STA $D012
LDA #0:STA $D017
LDA #0:STA 2
JSR NEWPOS ; Init the FLI routines
LDA #$A:STA $D011 ; Blank screen
LDX #23 ; Init tables
BLOOP LDA #$94:STA BANK,X
LDA #$96:STA BANK+24,X
DEX:BPL BLOOP
LDX #15
LOOP0 LDA YINIT,X:AND #$77 ; Change to $37 to better see the
STA UPOS,X ; workings of the routines
STA UPOS+16,X
STA UPOS+32,X
DEX:BPL LOOP0
LDA #$34:STA 1 ; Copy to the last video bank
LDA #$80:STA SRC+2 ; from $8000-$BFFF to $C000-$FFFF
LDA #$C0:STA DST+2
LDX #0:LDY #$40
SRC LDA $8000,X
DST STA $C000,X
INX:BNE SRC
INC SRC+2:INC DST+2
DEY:BNE SRC
LDA #$37:STA 1
LDX #0 ; Init color memory
LP LDA $3C00,X:STA $D800,X ; All 1024 bytes are used
LDA $3D00,X:STA $D900,X ; - some even twice!
LDA $3E00,X:STA $DA00,X
LDA $3F00,X:STA $DB00,X
INX:BNE LP
LDA $DC0D:CLI
KEYW LDX #0:BNE KEYW ; Wait for space to be pressed
SEI ; System to normal
LDA #$37:STA 1
JSR $FDA3
LDA #$97:STA $DD00
JSR $E5A0
LDY #3
IRQL LDA $FD30,Y:STA $314,Y
DEY:BPL IRQL
LDX #0:LDA #1 ; Clear color memory
CLL STA $D800,X:STA $D900,X
STA $DA00,X:STA $DB00,X
INX:BNE CLL
CLI:RTS
YINIT BYT $78,$79,$7A,$7B,$7C,$7D,$7E,$7F
BYT $78,$79,$7A,$7B,$7C,$7D,$7E,$7F
*=*-<*+256
IRQ LDA #$18:STA $D016:LDX #0:LDA #$5A
INC DUMMY:DEC DUMMY ; Synchronization
STX $D020:STX $D021:STA $D011
LDA #$15:STA $D018
LDA #$97:STA $DD00
LDX #44 ; Wait for the 4th line
LL DEX:BPL LL:NOP
LDX #0
LOOP3 NOP ; Linecrunch-part routine
LDA UPOS+6,X:INC DUMMY:STA $D011
NOP:NOP:INC DUMMY
NOP:NOP:NOP:NOP:NOP
NOP:NOP:NOP:NOP:NOP
NOP:NOP:NOP:NOP:NOP
INX
E1 CPX #$10:BNE LOOP3 ; Skip that many character rows-4
BIT $EA
LOOP4 LDA UPOS,X:INC DUMMY:STA $D011
NOP:NOP:NOP:INC DUMMY
NOP:NOP:NOP:NOP:NOP
NOP:NOP:NOP:NOP:NOP
NOP:NOP:NOP:NOP:LDA #0
INX
E2 CPX #$1F:BNE LOOP4 ; Delay DMA until we are at the
; 'same place' each time
LDA #0:STA $D020 ; Now wait for the bad line and start FLI
BIT $EA:NOP
NOP:NOP:NOP:NOP
NOP:NOP:NOP:NOP
NOP:NOP:NOP:NOP
B0 LDA #$92:STA $DD00:NOP ; The right video bank
; Wait for 0-7 lines to set the ECM mode off
; (makes the graphics visible)
F0 LDA #0:STA $D011:LDA #$08:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
F1 LDA #0:STA $D011:LDA #$18:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
F2 LDA #0:STA $D011:LDA #$28:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
F3 LDA #0:STA $D011:LDA #$38:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
F4 LDA #0:STA $D011:LDA #$48:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
F5 LDA #0:STA $D011:LDA #$58:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
F6 LDA #0:STA $D011:LDA #$68:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
F7 LDA #0:STA $D011:LDA #$78:STA $D018
LDX #FLISZ:NOP:NOP:NOP:BIT $EA
; Do FLI 18 more character rows
F8 LDA #0:STA $D011:LDA #$08:STA $D018
B1 LDA BANK,X:STA $DD00:BIT $EA
F9 LDA #0:STA $D011:LDA #$18:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
FA LDA #0:STA $D011:LDA #$28:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
FB LDA #0:STA $D011:LDA #$38:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
FC LDA #0:STA $D011:LDA #$48:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
FD LDA #0:STA $D011:LDA #$58:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
FE LDA #0:STA $D011:LDA #$68:STA $D018:NOP:NOP:NOP:NOP:BIT $EA
FF LDA #0:STA $D011:LDA #$78:STA $D018:NOP:NOP:DEX:BMI EFLI:JMP F8
EFLI NOP
LDA #$FC
WL CMP $D012:BNE WL
INC DUMMY:INC DUMMY:INC DUMMY:INC DUMMY
INC DUMMY:INC DUMMY:INC DUMMY:INC DUMMY
INC DUMMY:INC DUMMY:STA $D020
JSR NEWPOS ; Update the location
JSR CHPOS ; Change to a new location
LDA $DC01:AND #$10:BNE OV3 ; Check for the space bar
LDA #0:STA KEYW+1
OV3 LDX #$53:STX $D011:INC $D019:JMP $EA81
NEWPOS LDA #0 ; Init the IRQ routine for this position
LSR:LSR:LSR:CLC:ADC #4:STA E1+1
LDA #7:SEC:SBC NEWPOS+1:AND #7:TAX:TAY:CLC:ADC #35:STA E2+1
LDA UPOS+3+7,Y:DEX:BMI J0:AND #$3F
J0 STA F7+1:AND #$3F:STA FF+1
LDA UPOS+3+6,Y:DEX:BMI J1:AND #$3F
J1 STA F6+1:AND #$3F:STA FE+1
LDA UPOS+3+5,Y:DEX:BMI J2:AND #$3F
J2 STA F5+1:AND #$3F:STA FD+1
LDA UPOS+3+4,Y:DEX:BMI J3:AND #$3F
J3 STA F4+1:AND #$3F:STA FC+1
LDA UPOS+3+3,Y:DEX:BMI J4:AND #$3F
J4 STA F3+1:AND #$3F:STA FB+1
LDA UPOS+3+2,Y:DEX:BMI J5:AND #$3F
J5 STA F2+1:AND #$3F:STA FA+1
LDA UPOS+3+1,Y:DEX:BMI J6:AND #$3F
J6 STA F1+1:AND #$3F:STA F9+1
LDA UPOS+3+0,Y:DEX:BMI J7:AND #$3F
J7 STA F0+1:AND #$3F:STA F8+1
LDA #$96:STA B0+1:LDA #199:SEC:SBC NEWPOS+1:BCC OV2
LSR:LSR:LSR:CLC:ADC #5:STA B1+1
RTS
OV2 LDA #0:STA B1+1:LDX #$94:STX B0+1:RTS
CHPOS LDX NEWPOS+1
LDA $DC00:TAY ; Get joystick
AND #$10:BNE DIR ; If no button pressed
TYA:AND #1:BEQ UP ; If joy up
TYA:AND #2:BEQ DOWN ; If joy down
RTS
DIR LDA #0:BEQ UP
DOWN DEX:CPX #$FF:BNE DOK
LDX #0:STX DIR+1 ; Change direction
DOK STX NEWPOS+1:RTS
UP INX:CPX #$FD:BCC UOK ; 251(locations)+149(visible)=400
LDX #$FC:STX DIR+1 ; Change direction
UOK STX NEWPOS+1:RTS
--------------------------------------------------------------------------
The BFLI file format:
File BFLI Display
Lines Offset Offset Lines Size
Colors 0-1.3 0..55 944..999 22.7-24 56
I 1.3-2 56..79 - 24
2-24 80..999 0..919 0-22 920
24-24.7 1000..1023 920..943 22-22.7 24
II 0-1.3 0..55 1968..2024 49.3-50.6 56
1.3-24.7 56..1023 1000..1967 24-49.3 968
Gfx 0-1.3 0..447 7552..7999 22.7-24 448
I 1.3-2 448..639 - 192
2-24 640..7999 0..7359 0-22 7360
24-24.7 8000..8191 7360..7551 22-22.7 192
II 0-1.3 0..447 15744..16192 49.3-50.6 448
1.3-24.7 448..8191 8000..15743 24-49.3 7744
========================================================================
Making stable raster routines (C64 and VIC-20)
by Marko Makela (Marko.Makela@HUT.FI)
Preface
Too many graphical effects, also called raster effects, have been
coded in a very sloppy way. For instance, if there are any color bars
on the screen in a game or demo, the colors often jitter a bit,
e.g. they are not stable. And also, it is far too easy to make
virtually any demo crash by hitting the Restore key, or at least cause
visual distortions on the screen.
As late as a year ago I still hadn't coded a stable raster interrupt
routine myself. But then I had to do it, since I was researching the
video chip timing details together with my German friend Andreas
Boose. It was ashaming that we had the same level of knowledge when
it came to the hardware, but he was the only of us who had written a
stable raster routine. Well, finally I made me to start coding. I
used the same double-interrupt idea as Andreas used in his routine.
After a couple of errors my routine worked, and I understood how it
works exactly. (This is something that separates us normal coders
from demo people: They often code by instinct; by patching the routine
until it works, without knowing exactly what is happening. That's why
demos often rely on weird things, like crash if the memory is not
initialized properly.)
In this article, I document two methods of creating stable raster
routines on Commodore computers. The principles apply for most 8-bit
computers, not only Commodores, but raster effects are very rarely
seen on other computers.
Background
What are raster effects? They are effects, where you change the
screen appearance while it is being drawn. For instance, you can set
the screen color to white in the top of the screen, and to black in
the middle of the screen. In that way, you will get a picture whose
top half is white and bottom half black. Normally such effects are
implemented with interrupt routines that are executed synchronized
with the screen refresh.
The video chip on the Commodore 64 and many other videochips have a
special interrupt feature called the Raster interrupt. It will
generate an IRQ in the beginning of a specified raster line. On other
computers, like the VIC-20, there is no Raster interrupt, but you can
generate the interrupts with a timer, provided that the timer and the
videoch
ip are clocked from the same source.
Even if the processor gets an interrupt signal at the same position on
each video frame, it won't always be executing the first instruction
of the interrupt routine at the same screen position. The NMOS 6502
machine instructions can take 2 to 9 machine cycles to execute, and if
the main program contains instructions of very varying lengths, the
beginning position of the interrupt can jump between 7 different
positions. This is why you need to synchronize the raster routine
when doing serious effects.
Also, executing the interrupt sequence will take 7 additional cycles,
and the interrupt sequence will only start after the current
instruction if the interrupt arrived at least two cycles before the
end of the current instruction. It is even possible that an interrupt
arrives while interrupts are disabled and the processor is just
starting to execute a CLI instruction. Alas, the processor will not
jump to the interrupt right after the CLI, but it will execute the
next instruction before jumping to it. This is natural, since the CLI
takes only two cycles. But anyway, this is only a constant in our
equation, and actually out of the scope of this article.
How to synchronize a raster interrupt routine? The only way is to
check the current screen position and delay appropriately many cycles.
There are several ways of doing this, some of which are very awful and
inefficient. The ugliest ways of doing this on the Commodore 64 I
know are busy-waiting several raster lines and polling the raster line
value, or using the Light pen feature, which will fail if the user
presses the fire button on Joystick port 1. Here I will present two
ways, both very elegant in my opinion.
Using an auxiliary timer
On the VIC-20, there is no Raster interrupt feature in the video chip.
All you can do is to use a timer for generating raster interrupts.
And if you use two timers running at a constant phase difference, you
can get full synchronization. The first timer generates the raster
interrupt, and the second timer, the auxiliary timer, tells the raster
routine where it is running. Actually you could even use the first
timer also for the checking, but the code will look nicer in the way I
will be presenting now. Besides, you can use the auxiliary timer idea
even when real raster interrupts are available.
The major drawback of using an auxiliary timer is initializing it.
The initialization routine must synchronize with the screen, that is,
wait for the beginning of the wanted raster line. To accomplish this,
the routine must first wait for a raster line that occurs a bit
earlier. About the only way to do this is with a loop like
LDA #value
loop CMP raster
BNE loop
One round of this loop will take 4+3=7 cycles to execute, assuming
that absolute addressing is being used. The loop will be finished if
the raster register contains the wanted value while the processor
reads it on the last cycle of the CMP instruction. The raster
register can actually have changed already on the first cycle of the
BNE instruction on the previous run of the loop, that is 7 cycles
earlier!
Because of this, the routine must poll the raster register for several
raster lines, always consuming one cycle more if the raster register
changed too early. As the synchronization can be off at most by 7
cycles, a loop of 7 raster register value changes would do, but I made
the loop a bit longer in my VIC-20 routine. (Well, I have to admit it,
I was too lazy to make it work only with 7 rounds.)
After the initialization routine is fully synchronized the screen, it
can set up the timer(s) and interrupts and exit. The auxiliary timer
in my VIC-20 demo routine is several dozens of cycles after the
primary timer, see the source code for comments. It is arranged so
that the auxiliary timer will be at least 0 when it is being read in
the raster routine. The raster routine will wait as many extra cycles
as the auxiliary timer reads, however at most 15 cycles.
Using double raster interrupt
On the Commodore 64, I have never seen the auxiliary timer scheme
being used. Actually I haven't seen it being used anywhere, I was
probably the first one who made a stable raster interrupt routine on
the VIC-20. Instead, the double interrupt method is becoming the
standard on the C64 side.
The double interrupt method is based entirely on the Raster interrupt
feature of the video chip. In the first raster interrupt routine, the
program sets up another raster interrupt on a further line, changes
the interrupt vector and enables interrupts.
In the place where the second raster interrupt will occur, there will
be 2-byte instructions in the first interrupt routine. In this way,
the beginning of the next raster interrupt will be off at most by one
cycle. Some coders might not care about this one cycle, but if you
can do it right, why wouldn't you do it right until the end?
At the beginning of the second raster interrupt routine, you will read
the raster line counter register at the point where it is about to
change. When the raster routine is being executed, there are two
possibilities: Either the raster counter has just changed, or it will
change on the next cycle. So, you just need to compare if the
register changed one cycle too early or not, and delay a cycle when
needed. This is easily accomplished with a branch to the next address.
Of course, somewhere in your second raster interrupt routine you must
restore the original raster interrupt position and set the interrupt
vector to point to the first interrupt routine.
Applying in practice
I almost forgot my complaints about demos crashing when you actively
hit the Restore key. On the VIC-20, you can disable NMI interrupts
generated by the Restore key, and on the C64, you can generate an NMI
interrupt with the CIA2 timer and leave the NMI-line low, so that no
further high-to-low transitions will be recognized on the line. The
example programs demonstrate how to do this.
So far, this article has been pretty theoretical. To apply these
results in practice, you must definitely know how many CPU clock
cycles the video chip consumes while drawing a scan line. This is
fairly easy to measure with a timer interrupt, if you patch the
interrupt handler so that it changes the screen color on each run.
Set the timer interval to LINES*COLUMNS cycles, where LINES is the
amount of raster lines and COLUMNS is your guess for the amount of
clock cycles spent in a raster line.
If your guess is right, the color will always be changed in the same
screen position (neglecting the 7-cycle jitter). When adjusting the
timer, remember that the timers on the 6522 VIA require 2 cycles for
re-loading, and the ones on the 6526 CIA need one extra cycle. Keep
trying different timer values until you the screen color changes at
one fixed position.
Commodore used several different values for LINES and COLUMNS on its
videochips. They never managed to make the screen refresh rate
exactly 50 or 60 Hertz, but they didn't hesitate to claim that their
computers comply with the PAL-B or NTSC-M standards. In the following
tables I have gathered some information of some Commodore video chips.
NTSC-M systems:
Chip Crystal Dot Processor Cycles/ Lines/
Host ID freq/Hz clock/Hz clock/Hz line frame
------ -------- -------- -------- --------- ------- ------
VIC-20 6560-101 14318181 4090909 1022727 65 261
C64 6567R56A 14318181 8181818 1022727 64 262
C64 6567R8 14318181 8181818 1022727 65 263
Later NTSC-M video chips were most probably like the 6567R8. Note
that the processor clock is a 14th of the crystal frequency on all
NTSC-M systems.
PAL-B systems:
Chip Crystal Dot Processor Cycles/ Lines/
Host ID freq/Hz clock/Hz clock/Hz line frame
------ -------- -------- -------- --------- ------- ------
VIC-20 6561-101 4433618 4433618 1108405 71 312
C64 6569 17734472 7881988 985248 63 312
On the PAL-B VIC-20, the crystal frequency is simultaneously the dot
clock, which is BTW a 4th of the crystal frequency used on the C64.
On the C64, the crystal frequency is divided by 18 to generate the
processor clock, which in turn is multiplied by 8 to generate the
dot clock.
The basic timings are the same on all 6569 revisions, and also on
any later C64 and C128 video chips. If I remember correctly, these
values were the same on the C16 videochip TED as well.
Note that the dot clock is 4 times the processor clock on the VIC-20,
and 8 times that on the C64. That is, one processor cycle is half a
character wide on the VIC-20, and a full character on a C64. I don't
have exact measurements of the VIC-20 timing, but it seems that while
the VIC-20 videochips draw the characters on the screen, it first
reads the character code, and then, on the following video cycle, the
appearance on the current character line. There are no bad lines,
like on the C64, where the character codes (and colors) are fetched on
every 8th raster line.
Those ones who got upset when I said that Commodore has never managed
to make a fully PAL-B or NTSC-M compliant 8-bit computer should take a
closer look at the "Lines/frame" columns. If that does not convince
you, calculate the raster line rate and the screen refresh rate from
the values in the table and see that they don't comply with the
standards. To calculate the line rate, divide the processor clock
frequency by the amount of cycles per line. To get the screen refresh
rate, divide that frequency by the amount of raster lines.
The Code
OK, enough theory and background. Here are the two example programs,
one for the VIC-20 and one for the C64. In order to fully understand
them, you need to know the exact execution times of NMOS 6502
instructions. (All 8-bit Commodore computers use the NMOS 6502
processor core, except the C65 prototype, which used a inferior CMOS
version with all nice poorly-documented features removed.) You should
check the 64doc document, available on my WWW pages at
http://www.hut.fi/~msmakela/cbm/emul/x64/64doc.html, or via FTP at
ftp.funet.fi:/pub/cbm/documents/64doc. I can also e-mail it to you on
request.
Also, I have written a complete description of the video timing on the
6567R56A, 6567R8 and 6569 video chips, which could maybe be turned
into another C=Hacking article. The document is currently partially
in English and partially in German. The English part is available
from ftp.funet.fi as /pub/cbm/documents/pal.timing, and I can send
copies of the German part (screen resolution, sprite disturbance
measurements, and more precise timing information) via e-mail.
The code is written for the DASM assembler, or more precisely for a
extended ANSI C port of it made by Olaf Seibert. This excellent
cross-assembler is available at ftp.funet.fi in /pub/cbm/programming.
First the raster demo for the VIC-20. Note that on the VIC-20, the
$9004 register contains the upper 8 bits of the raster counter. So,
this register changes only on every second line. I have tested the
program on my 6561-101-based VIC-20, but not on an NTSC-M system.
It was hard to get in contact with NTSC-M VIC-20 owners. Daniel
Dallmann, who has a NTSC-M VIC-20, although he lives in Germany, ran
my test to determine the amount of cycles per line and lines per frame
on the 6560-101. Unfortunately, the second VIA of his VIC-20 is
partially broken, and because of this, this program did not work on
his computer. Craig Bruce ran the program once, and he reported that
it almost worked. I corrected a little bug in the code, so that now
the display should be stable on an NTSC-M system, too. But the actual
raster effect, six 16*16-pixel boxes centered at the top border, are
very likely to be off their position.
processor 6502
NTSC = 1
PAL = 2
;SYSTEM = NTSC ; 6560-101: 65 cycles per raster line, 261 lines
SYSTEM = PAL ; 6561-101: 71 cycles per raster line, 312 lines
#if SYSTEM & PAL
LINES = 312
CYCLES_PER_LINE = 71
#endif
#if SYSTEM & NTSC
LINES = 261
CYCLES_PER_LINE = 65
#endif
TIMER_VALUE = LINES * CYCLES_PER_LINE - 2
.org $1001 ; for the unexpanded Vic-20
; The BASIC line
basic:
.word 0$ ; link to next line
.word 1995 ; line number
.byte $9E ; SYS token
; SYS digits
.if (* + 8) / 10000
.byte $30 + (* + 8) / 10000
.endif
.if (* + 7) / 1000
.byte $30 + (* + 7) % 10000 / 1000
.endif
.if (* + 6) / 100
.byte $30 + (* + 6) % 1000 / 100
.endif
.if (* + 5) / 10
.byte $30 + (* + 5) % 100 / 10
.endif
.byte $30 + (* + 4) % 10
0$:
.byte 0,0,0 ; end of BASIC program
start:
lda #$7f
sta $912e ; disable and acknowledge interrupts
sta $912d
sta $911e ; disable NMIs (Restore key)
;synchronize with the screen
sync:
ldx #28 ; wait for this raster line (times 2)
0$:
cpx $9004
bne 0$ ; at this stage, the inaccuracy is 7 clock cycles
; the processor is in this place 2 to 9 cycles
; after $9004 has changed
ldy #9
bit $24
1$:
ldx $9004
txa
bit $24
#if SYSTEM & PAL
ldx #24
#endif
#if SYSTEM & NTSC
bit $24
ldx #21
#endif
dex
bne *-1 ; first spend some time (so that the whole
cmp $9004 ; loop will be 2 raster lines)
bcs *+2 ; save one cycle if $9004 changed too late
dey
bne 1$
; now it is fully synchronized
; 6 cycles have passed since last $9004 change
; and we are on line 2(28+9)=74
;initialize the timers
timers:
lda #$40 ; enable Timer A free run of both VIAs
sta $911b
sta $912b
lda #<TIMER_VALUE
ldx #>TIMER_VALUE
sta $9116 ; load the timer low byte latches
sta $9126
#if SYSTEM & PAL
ldy #7 ; make a little delay to get the raster effect to the
dey ; right place
bne *-1
nop
nop
#endif
#if SYSTEM & NTSC
ldy #6
dey
bne *-1
bit $24
#endif
stx $9125 ; start the IRQ timer A
; 6560-101: 65 cycles from $9004 change
; 6561-101: 77 cycles from $9004 change
ldy #10 ; spend some time (1+5*9+4=55 cycles)
dey ; before starting the reference timer
bne *-1
stx $9115 ; start the reference timer
pointers:
lda #<irq ; set the raster IRQ routine pointer
sta $314
lda #>irq
sta $315
lda #$c0
sta $912e ; enable Timer A underflow interrupts
rts ; return
irq:
; irq (event) ; > 7 + at least 2 cycles of last instruction (9 to 16 total)
; pha ; 3
; txa ; 2
; pha ; 3
; tya ; 2
; pha ; 3
; tsx ; 2
; lda $0104,x ; 4
; and #xx ; 2
; beq ; 3
; jmp ($314) ; 5
; ---
; 38 to 45 cycles delay at this stage
lda $9114 ; get the NMI timer A value
; (42 to 49 cycles delay at this stage)
; sta $1e00 ; uncomment these if you want to monitor
; ldy $9115 ; the reference timer on the screen
; sty $1e01
cmp #8 ; are we more than 7 cycles ahead of time?
bcc 0$
pha ; yes, spend 8 extra cycles
pla
and #7 ; and reset the high bit
0$:
cmp #4
bcc 1$
bit $24 ; waste 4 cycles
and #3
1$:
cmp #2 ; spend the rest of the cycles
bcs *+2
bcs *+2
lsr
bcs *+2 ; now it has taken 82 cycles from the beginning of the IRQ
effect:
ldy #16 ; perform amazing video effect
lda $900f
tax
eor #$f7
0$:
sta $900f
stx $900f
sta $900f
stx $900f
sta $900f
stx $900f
sta $900f
stx $900f
sta $900f
stx $900f
sta $900f
stx $900f
pha
pla
#if SYSTEM & PAL
pha
pla
nop
#endif
#if SYSTEM & NTSC
bit $24
#endif
nop
dey
bne 0$ ; end of amazing video effect
jmp $eabf ; return to normal IRQ
And after you have recovered from the schock of seeing a VIC-20
program, here is an example for the C64. It does also something
noteworthy; it removes the side borders on a normal screen while
displaying all eight sprites. Well, it cannot remove the borders on
bad lines, and the bad lines look pretty bad. But I could use the
program for what I wanted: I measured the sprite distortions on all
videochip types I had at hand. (FYI: the sprites 0-2 get distorted at
the very right of the screen, and the sprites 6 and 7 are invisible at
the very left of the screen. You will need a monitor with horizontal
size controls to witness these effects.)
This program is really robust, it installs itself nicely to the
interrupt routine chain. It even has an entry point for deinstalling
itself. But in its robustness it uses self-modifying code to store
the original interrupt routine address. :-)
The code also relies on the page boundaries in being where they are.
The cycles are counted so that the branches "irqloop" must take 4
cycles. If the "irqloop" comes to the same CPU page with the branch
instructions, you must add one cycle to the loop in a way or another.
When coding the routine, I noticed again how stupid assembly coding
can be, especially conditional assembling. In a machine language
monitor you have far better control on page boundaries. BTW, you
might wonder why I disable the Restore key in a subroutine at the end
and not in the beginning of the program. Well, the routine was so
long that it would have affected the "irqloop" page boundaries. And I
didn't want to risk the modified programs working on all three
different videochip types on the first try.
In the code, there are some comments that document the video timing,
like this one:
;3s4s5s6s7srrrrrgggggggggggggggggggggggggggggggggggggggg--||0s1s2s Phi-1 VIC-II
;ssssssssss ||ssssss Phi-2 VIC-II
;==========xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx||XXX====== Phi-2 6510
; ^ now we are here
The two vertical bars "|" denote optional cycles. On PAL-B systems
(63 cycles per line), they are not present. On 6567R56A, which has 64
cycles per line, there is one additional cycle on this position, and
the 6567R8 has two additional cycles there.
The numbers 0 through 7 are sprite pointer fetches (from the end of
the character matrix, e.g. the text screen), the "s" characters denote
sprite image fetches, the "r"s are memory refresh, and the "g" are
graphics fetches. The two idle video chip cycles are marked with "-".
On the processor timing line, the "=" signs show halted CPU, "x" means
free bus, and "X" means that the processor will be halted at once,
unless it is performing write cycles.
processor 6502
; Select the video timing (processor clock cycles per raster line)
CYCLES = 65 ; 6567R8 and above, NTSC-M
;CYCLES = 64 ; 6567R5 6A, NTSC-M
;CYCLES = 63 ; 6569 (all revisions), PAL-B
cinv = $314
cnmi = $318
raster = 52 ; start of raster interrupt
m = $fb ; zero page variable
.org $801
basic:
.word 0$ ; link to next line
.word 1995 ; line number
.byte $9E ; SYS token
; SYS digits
.if (* + 8) / 10000
.byte $30 + (* + 8) / 10000
.endif
.if (* + 7) / 1000
.byte $30 + (* + 7) % 10000 / 1000
.endif
.if (* + 6) / 100
.byte $30 + (* + 6) % 1000 / 100
.endif
.if (* + 5) / 10
.byte $30 + (* + 5) % 100 / 10
.endif
.byte $30 + (* + 4) % 10
0$:
.byte 0,0,0 ; end of BASIC program
start:
jmp install
jmp deinstall
install: ; install the raster routine
jsr restore ; Disable the Restore key (disable NMI interrupts)
checkirq:
lda cinv ; check the original IRQ vector
ldx cinv+1 ; (to avoid multiple installation)
cmp #<irq1
bne irqinit
cpx #>irq1
beq skipinit
irqinit:
sei
sta oldirq ; store the old IRQ vector
stx oldirq+1
lda #<irq1
ldx #>irq1
sta cinv ; set the new interrupt vector
stx cinv+1
skipinit:
lda #$1b
sta $d011 ; set the raster interrupt location
lda #raster
sta $d012
ldx #$e
clc
adc #3
tay
lda #0
sta m
0$:
lda m
sta $d000,x ; set the sprite X
adc #24
sta m
tya
sta $d001,x ; and Y coordinates
dex
dex
bpl 0$
lda #$7f
sta $dc0d ; disable timer interrupts
sta $dd0d
ldx #1
stx $d01a ; enable raster interrupt
lda $dc0d ; acknowledge CIA interrupts
lsr $d019 ; and video interrupts
ldy #$ff
sty $d015 ; turn on all sprites
cli
rts
deinstall:
sei ; disable interrupts
lda #$1b
sta $d011 ; restore text screen mode
lda #$81
sta $dc0d ; enable Timer A interrupts on CIA 1
lda #0
sta $d01a ; disable video interrupts
lda oldirq
sta cinv ; restore old IRQ vector
lda oldirq+1
sta cinv+1
bit $dd0d ; re-enable NMI interrupts
cli
rts
; Auxiliary raster interrupt (for syncronization)
irq1:
; irq (event) ; > 7 + at least 2 cycles of last instruction (9 to 16 total)
; pha ; 3
; txa ; 2
; pha ; 3
; tya ; 2
; pha ; 3
; tsx ; 2
; lda $0104,x ; 4
; and #xx ; 2
; beq ; 3
; jmp ($314) ; 5
; ---
; 38 to 45 cycles delay at this stage
lda #<irq2
sta cinv
lda #>irq2
sta cinv+1
nop ; waste at least 12 cycles
nop ; (up to 64 cycles delay allowed here)
nop
nop
nop
nop
inc $d012 ; At this stage, $d012 has already been incremented by one.
lda #1
sta $d019 ; acknowledge the first raster interrupt
cli ; enable interrupts (the second interrupt can now occur)
ldy #9
dey
bne *-1 ; delay
nop ; The second interrupt will occur while executing these
nop ; two-cycle instructions.
nop
nop
nop
oldirq = * + 1 ; Placeholder for self-modifying code
jmp * ; Return to the original interrupt
; Main raster interrupt
irq2:
; irq (event) ; 7 + 2 or 3 cycles of last instruction (9 or 10 total)
; pha ; 3
; txa ; 2
; pha ; 3
; tya ; 2
; pha ; 3
; tsx ; 2
; lda $0104,x ; 4
; and #xx ; 2
; beq ; 3
; jmp (cinv) ; 5
; ---
; 38 or 39 cycles delay at this stage
lda #<irq1
sta cinv
lda #>irq1
sta cinv+1
ldx $d012
nop
#if CYCLES - 63
#if CYCLES - 64
nop ; 6567R8, 65 cycles/line
bit $24
#else
nop ; 6567R56A, 64 cycles/line
nop
#endif
#else
bit $24 ; 6569, 63 cycles/line
#endif
cpx $d012 ; The comparison cycle is executed CYCLES or CYCLES+1 cycles
; after the interrupt has occurred.
beq *+2 ; Delay by one cycle if $d012 hadn't changed.
; Now exactly CYCLES+3 cycles have passed since the interrupt.
dex
dex
stx $d012 ; restore original raster interrupt position
ldx #1
stx $d019 ; acknowledge the raster interrupt
ldx #2
dex
bne *-1
nop
nop
lda #20 ; set the amount of raster lines-1 for the loop
sta m
ldx #$c8
irqloop:
ldy #2
dey
bne *-1 ; delay
dec $d016 ; narrow the screen (exact timing required)
;3s4s5s6s7srrrrrgggggggggggggggggggggggggggggggggggggggg--||0s1s2s Phi-1 VIC-II
;ssssssssss ||ssssss Phi-2 VIC-II
;==========xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx||XXX====== Phi-2 6510
; ^ now we are here
stx $d016 ; expand the screen
#if CYCLES - 63
#if CYCLES - 64
bit $24 ; 6567R8
#else
nop ; 6567R56A
#endif
#else
nop ; 6569
#endif
dec m
bmi endirq
clc
lda $d011
sbc $d012
and #7
bne irqloop ; This instruction takes 4 cycles instead of 3,
; because the page boundary is crossed.
badline:
dec m
nop
nop
nop
nop
dec $d016
;3s4s5s6s7srrrrrgggggggggggggggggggggggggggggggggggggggg--||0s1s2s Phi-1 VIC-II
;ssssssssss cccccccccccccccccccccccccccccccccccccccc ||ssssss Phi-2 VIC-II
;==========xXXX========================================||***====== Phi-2 6510
; ^ we are here
stx $d016
;3s4s5s6s7srrrrrgggggggggggggggggggggggggggggggggggggggg--||0s1s2s Phi-1 VIC-II
;ssssssssss ||ssssss Phi-2 VIC-II
;==========xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx||XXX====== Phi-2 6510
; ^ ^^- we are here (6569)
; | \- or here (6567R56A)
; \- or here (6567R8)
ldy #2
dey
bne *-1
nop
nop
#if CYCLES - 63
#if CYCLES - 64
nop ; 6567R8, 65 cycles/line
nop
nop
#else
bit $24 ; 6567R56A, 64 cycles/line
#endif
#else
nop ; 6569, 63 cycles/line
#endif
dec m
bpl irqloop ; This is a 4-cycle branch (page boundary crossed)
endirq:
jmp $ea81 ; return to the auxiliary raster interrupt
restore: ; disable the Restore key
lda cnmi
ldy cnmi+1
pha
lda #<nmi ; Set the NMI vector
sta cnmi
lda #>nmi
sta cnmi+1
ldx #$81
stx $dd0d ; Enable CIA 2 Timer A interrupt
ldx #0
stx $dd05
inx
stx $dd04 ; Prepare Timer A to count from 1 to 0.
ldx #$dd
stx $dd0e ; Cause an interrupt.
nmi = * + 1
lda #$40 ; RTI placeholder
pla
sta cnmi
sty cnmi+1 ; restore original NMI vector (although it won't be used)
rts
Binaries
Here are the programs in uuencoded format. First the VIC-20 programs:
Color boxes for the VIC-20, NTSC-M version (probably distorted display):
begin 644 copper.6560
M`1`*$,L'GC0Q,#D```"I?XTND8TMD8T>D:(<[`20T/N@"20DK@20BB0D)"2B
M%<K0_<T$D+``B-#KJ4"-&Y&-*Y&I0Z)"C1:1C2:1H`:(T/TD)(XED:`*B-#]
MCA61J6R-%`.I$(T5`ZG`C2Z18*T4D<D(D`1(:"D'R020!"0D*0/)`K``L`!*
ML`"@$*T/D*I)]XT/D(X/D(T/D(X/D(T/D(X/D(T/D(X/D(T/D(X/D(T/D(X/
,D$AH)"3JB-#43+_J
`
end
Color boxes for the VIC-20, PAL-B version:
begin 644 copper.6561
M`1`*$,L'GC0Q,#D```"I?XTND8TMD8T>D:(<[`20T/N@"20DK@20BB0DHAC*
MT/W-!)"P`(C0[:E`C1N1C2N1J8:B5HT6D8TFD:`'B-#]ZNJ.)9&@"HC0_8X5
MD:EJC10#J1"-%0.IP(TND6"M%)')")`$2&@I!\D$D`0D)"D#R0*P`+``2K``
MH!"M#Y"J2?>-#Y".#Y"-#Y".#Y"-#Y".#Y"-#Y".#Y"-#Y".#Y"-#Y".#Y!(
+:$AHZNJ(T--,O^J.
`
end
Removed sideborders with 8 sprites and bad lines, PAL-B version:
begin 644 raster.63
M`0@*",L'GC(P-C$```!,$PA,=`@@'0FM%`.N%0/)E=`$X`CP$7B-N0B.N@BI
ME:((C10#CA4#J1N-$="I-(T2T*(.&&D#J*D`A?NE^YT`T&D8A?N8G0'0RLH0
M[ZE_C0W<C0W=H@&.&M"M#=Q.&="@_XP5T%A@>*D;C1'0J8&-#=RI`(T:T*VY
M"(T4`ZVZ"(T5`RP-W5A@J;N-%`.I"(T5`^KJZNKJZNX2T*D!C1G06*`)B-#]
MZNKJZNI,N`BIE8T4`ZD(C14#KA+0ZB0D[!+0\`#*RHX2T*(!CAG0H@+*T/WJ
MZJD4A?NBR*`"B-#]SA;0CA;0ZL;[,",8K1'0[1+0*0?0Y<;[ZNKJZLX6T(X6
MT*`"B-#]ZNKJQOL0S4R!ZJT8`ZP9`TBI0HT8`ZD)C1D#HH&.#=VB`(X%W>B.
1!-VBW8X.W:E`:(T8`XP9`V`8
`
end
Removed sideborders with 8 sprites and bad lines, 6567R56A version
(very old NTSC-M C64s):
begin 644 raster.64
M`0@*",L'GC(P-C$```!,$PA,=`@@'@FM%`.N%0/)E=`$X`CP$7B-N0B.N@BI
ME:((C10#CA4#J1N-$="I-(T2T*(.&&D#J*D`A?NE^YT`T&D8A?N8G0'0RLH0
M[ZE_C0W<C0W=H@&.&M"M#=Q.&="@_XP5T%A@>*D;C1'0J8&-#=RI`(T:T*VY
M"(T4`ZVZ"(T5`RP-W5A@J;N-%`.I"(T5`^KJZNKJZNX2T*D!C1G06*`)B-#]
MZNKJZNI,N`BIE8T4`ZD(C14#KA+0ZNKJ[!+0\`#*RHX2T*(!CAG0H@+*T/WJ
MZJD4A?NBR*`"B-#]SA;0CA;0ZL;[,"08K1'0[1+0*0?0Y<;[ZNKJZLX6T(X6
MT*`"B-#]ZNHD),;[$,Q,@>JM&`.L&0-(J4.-&`.I"8T9`Z*!C@W=H@".!=WH
2C@3=HMV.#MVI0&B-&`.,&0-@
`
end
Removed sideborders with 8 sprites and bad lines, 6567R8 and above
(not too old NTSC-M C64s and all C128s)
begin 644 raster.65
M`0@*",L'GC(P-C$```!,$PA,=`@@(0FM%`.N%0/)E=`$X`CP$7B-N0B.N@BI
ME:((C10#CA4#J1N-$="I-(T2T*(.&&D#J*D`A?NE^YT`T&D8A?N8G0'0RLH0
M[ZE_C0W<C0W=H@&.&M"M#=Q.&="@_XP5T%A@>*D;C1'0J8&-#=RI`(T:T*VY
M"(T4`ZVZ"(T5`RP-W5A@J;N-%`.I"(T5`^KJZNKJZNX2T*D!C1G06*`)B-#]
MZNKJZNI,N`BIE8T4`ZD(C14#KA+0ZNHD).P2T/``RLJ.$M"B`8X9T*("RM#]
MZNJI%(7[HLB@`HC0_<X6T(X6T"0DQOLP)1BM$=#M$M`I!]#DQOOJZNKJSA;0
MCA;0H`*(T/WJZNKJZL;[$,I,@>JM&`.L&0-(J4:-&`.I"8T9`Z*!C@W=H@".
5!=WHC@3=HMV.#MVI0&B-&`.,&0-@
`
end
That was all, folks! I hope you learned something from this article.
Feel free to e-mail me at Marko.Makela@HUT.FI, should anything remain
unclear.
========================================================================
A Different Perspective, part III
by Stephen Judd --- sjudd@nwu.edu
George Taylor --- aa601@cfn.cs.dal.ca
Whew! What a busy time it's been -- research to get done,
conferences, classes... between getting things done and blowing other
things off, I one day reflected for a moment and realized that I had
three days left to get the next article together for C=Hacking! So
everything has been slapped together at the last minute, and I hope
you'll forgive any bugs or unclear concepts.
>>> ANECDOTE ALERT <<<
And that reminds me: I just got JiffyDOS and an FD-2000 drive --
what a wonderful device. I have a 1.6 megabyte disk formatted into
three partitions. The first contains my Merlin 128 assembler, the
second is some 4000 blocks large and I use it for all my various
versions of code while debugging, and the third is maybe 1000 blocks,
and contains only finished code -- no more swapping disks, no more
deleting old versions that I hope I don't need to make room on the
disk. Also, when I installed JiffyDOS I found a serious bug in my
128D -- a cricket, dead among the IC's.
This time we will cover a lot of ground which isn't so much
cutting-edge as it is very useful. Let's face it: cubes are getting
more than a little dull. A worthy end goal is to have a completely
general routine for plotting a series of polygons -- that is, you supply
a list of (x,y,z) coordinates from which the program can form a list of
polygons. These polygons may then be displayed in 2D, rotated, magnified,
filled, etc. And, much to my three-day astonishment, that is exactly
what we are going to do.
But first, a little excursion. One thing we are of course always
thinking about is optimization possibilities: in the shower, while
sleeping/dreaming, out on dates, etc. So, where to begin? The biggest
cycle hogs in the program are line drawing and face filling -- well,
filling faces is pretty straightforward. What about line drawing?
Well, one downer of the routine is that every single pixel is
plotted. But as we know, on a computer any given line is made up of
several smaller vertical and horizontal lines -- wouldn't it be neat
if we could think of a way to plot these line chunks all at once,
instead of a pixel at a time?
Heck yes it would! So here we go:
Neat-o Enhanced Chunky Line Drawing Routine
-------------------------------------------
First we need to be in the right mindframe. Let's say you're
drawing a line where you move three pixels in x before it's time to take
a step in y. Instead of plotting all three pixels it would of course
be much more efficient to just stick a number like %00011100 in the
drawing buffer. But somehow we need to keep track of a) how large the
chunk needs to be, and b) where exactly the chunk is.
In the above example, we started at a particular x-value:
%00010000
and we want to keep adding ones to the right of the starting point; three,
to be exact. Hmmm... we need to somehow rotate the starting bit in a way
that leaves a trail of ones behind it. Maybe rotate and ORA with the
original bit? But what happens when you take a step in Y?
No, we need something far sneakier. Let's say that instead of
%00010000 we start with
x = %00011111
Now, with each step in the x direction, we do an arithmetic shift on x. So
after one step we have
x = %00001111
and after two steps
x = %00000111
and at the third step of course
x = %00000011
Now it is time to take a step in Y. But now look: if we EOR x with its
original value xold = %00011111, we get
x EOR xold = %00011100
which is exactly the chunk we wanted. Moreover, x still remembers where it
is, so we don't have to do anything special each time a step is taken in
the y-direction.
So here is the algorithm for drawing a line in the x-direction:
initialize x, dx, etc.
xold = x
take a step in x: LSR X
have we hit the end of a column? If so, then plot and check on y
is it time to take a step in y?
if not, take another step in x
if it is, then let a=x EOR xold
plot a into the buffer
let xold=x
keep on going until we're finished
This simple modification gives us a substantial speed increase --
on the old filled hires cube3d program, I measured a gain of one frame per
second. Not earth-shattering, but not bad either! When faces are not
filled, the difference is of course much more noticable.
There are a few things to be careful of. There was a bug in the
old routine when the line was a single point. In that case dx=dy=0, and
the program would draw a vertical line on the screen. There are probably
some other things to be careful of, but since I wrote this part of the
code three months ago I really don't remember any of them!
This takes care of horizontal line chunks -- what about vertical
chunks? Well, because of the way points are plotted there is nothing
we can do about them. But, as we shall soon see, if we use an EOR-buffer
to fill faces we will be forced to take care of the vertical chunks!
General Polygon Routine
-----------------------
Now we can begin thinking about a general polygon routine. First
we need a list of sets of points, where each set corresponds to a
polygon. The first number in a set could be the number of (x,y,z) points
in that set, and the points could then follow. So a triangle could
be given by the data set:
3 -1 0 0 0 1 0 1 0 0
This would be a triangle with vertices at (-1,0,0), (0,1,0), and (1,0,0).
We can mash a bunch of these sets together, but somehow we have to know
when we've hit the end -- for this we can use a zero, since we don't
want to plot polygons with zero points in them.
For that matter, how many points should there be in a polygon?
There must be at least three, otherwise it makes no sense. Since we
want our polygons to be closed, the computer should be smart enough to
connect the last point to the first point -- in our triangle above,
the computer would join (-1,0,0) to (0,1,0), (0,1,0) to (1,0,0), and
(1,0,0) to (-1,0,0).
Now that we have a polygon, we want to rotate it. You will
recall that we have calculated a rotation matrix M, which acts on
points. So we need apply our rotation transform to each of the
points in the polygon, i.e. multiply M times each point of the
polygon. Furthermore, we need to project each of these points.
Uh-oh: matrix multiplication. In the past we have avoided this
issue by putting the vertices of our cube at 1 or -1. So we need to
use our multiplication routine from last time. But wait! As you recall,
the last program used a specially modified multiplication table. To get
a wider range of numbers to multiply we will need another set of
multiplication tables -- no big whoop.
Now, if you review the multiplication routine from last time,
it adds two numbers and subtracts two numbers. What kinds of numbers
will we be dealing with? The matrix elements vary between -64..64.
This then fixes our range of polygon coordinates from -64..64. Why?
If the matrix element is 64, and we multiply it by 64, the multiplication
routine will add 64 and 64 and get 128, which is right on the edge of
our multiplication table.
Can we improve this rotation process in any way? In fact, we can
cut down on the number of multiplications (i.e. do eight or even seven
instead of nine multiplications). However, there is a fair amount of
overhead involved in doing so, and our multiply routine is fast enough
that the extra overhead and complexity really gain us very little in all
but the most complicated of polygons. In other words, I didn't bother.
What about hidden faces? Again, from last time you may recall
that a method was described which used the cross-product of the projected
vectors. How do we implement this in the program? Well, if we take
the first three points of the polygon, we have two vectors. Let's say
these points are P1 P2 and P3. Then V1=P1-P2 and V2=P3-P2 are two
vectors in the plane of the polygon which are connected at the point P2
(this analysis will of course only work if the polygon lies in some plane).
Depending on how we take the cross product, the sign will be positive or
negative, and this will tell us if the polygon is visible.
Depending on how we take the cross product? Absolutely.
v1 x v2 = -v2 x v1. What it really boils down to is how you define the
points in your polygon. Specifically, what order they are in. Points
that are specified in a clockwise manner will give a face pointing in
the opposite direction of a polygon with the same points specified in
a counter-clockwise order. In my program, the polygons must be entered
in counter-clockwise order (with you facing the polygon) for hidden
faces to work the way you want them to ;-).
One other neat thing to have is the ability to zoom in and out.
We know from the very first article that zooming corresponds to multiplying
the projected points by a number, so that's what we'll do. The multiplication
routine returns A=A*Y/64, so a zoom factor of 64 would be like multiplying
the point by one. All the program does is multiply the projected points
by a number zoom, unless zoom=64, in which case the program skips the
zoom multiply. Be warned! No checks of any sort are made in the program,
so you can zoom at your own risk!
The important things to remember are: when entering polygons,
make sure the numbers range from -64 to 64, and that you enter points
in counterclockwise. Our triangle example above really should have been
entered as, say,
3 -64 0 0 64 0 0 0 64 0
Filled Faces -- Using an EOR buffer
-----------------------------------
Well we still have one thing left, which was alluded to in the
previous article: using EOR to make a filled face. Some possible
difficulties were raised, but when you plot a single polygon at a
time, the problem becomes vastly simplified.
First I should perhaps remind you what exclusive-or is: either
A or B, but not both. So 1 EOR 0 = 1, as does 0 EOR 1, but 0 EOR 0 = 0
and 1 EOR 1 = 0. As a simple introduction to using this for filling
faces, consider the following piece of the drawing buffer:
00001011 M1
00000000 M2
00000001 M3
00001010 M4
Lets say we move down memory, EORing as we go. Let M2 = M1 EOR M2. Then
let M3 = M2 EOR M3. Then let M4 = M3 EOR M4. Our little piece of memory
is now:
00001011 M1
00001011 M2
00001010 M3
00000000 M4
What just happened? Imagine that the original memory was a series of
pieces of line segments. We have just filled in the area between the
two line segments, like magic!
If you still aren't getting it, draw a large section of memory,
and then draw an object in it, like a triangle, or a trapazoid, and
EOR the memory by hand, starting from the top and moving downwards.
EOR flips bits. If you start with a zero, it stays zero until
it hits a one. It will then stay one until it hits another one. So
you can see that if you have an object bounded by ones, EORing
successive memory locations will automagically fill the object.
Right? Well, we have to be careful. One major problem is
a vertical line:
1 1
1 goes to 0
1 1
1 0
Not only is the resultant line dashed, but if there are an odd number of
points in the line segment, the last one will happily move downwards in
memory, and give you a much longer vertical line than you expected! Since
any line with slope greater than one is made up of a series of line
segments, this is a major consideration.
Another problem arises with single points: a one just sitting all
by itself will also generate a nice streak down your drawing area.
If you think about it, what we ideally want to have is an object
that at any given value of x there are exactly two points, one defining
the top of the object, and the other defining the bottom. This gives us
the insight to solve the above two problems.
First let's think about vertical lines. In principle we could
plot the first and last endpoints of each vertical line chunk, but that
is exactly what we don't want! Remember that these are closed polygons,
which means that there are _two_ lines we need to think about. If I
plot just a single point in each vertical line segment, there must
be another point somehwere, either above or below it, from another
line segment, which will close the point to EOR-filling. Remember, we
want exactly two points at each value of x: one will come from the
line, and the other will come from the other line which must lie above
or below the current one.
Furthermore, with any convex polygon there are exactly two
lines which come together at each vertex of the polygon. This means
that there are only certain cases which we need to worry about.
For instance, two lines might join in any of the following ways:
\ / \ /
\ / \ /
\_____ _____/ \/ etc.
If you draw out the different cases involving vertical lines, you can see
that you have to be careful about plotting the lines. One tricky one
is where two vertical lines with different slopes overlap at the point
of intersection.
So after staring at these pictures for a while, you can find
a consistent method which solves these difficulties. As long as you
follow the following rules, the problems all disappear; the line routine
needs to be modified slightly:
1) When plotting a vertical line (i.e. big steps in Y direction),
don't plot the endpoints (i.e. x1,y1 and x2,y2).
2) When plotting a vertical line, consistently plot either the
first part of each chunk or the last part of each chunk
(excluding the endpoints of course). In other words, only
plot a point when you take a step in x, and then plot one
and only one point.
Now I deduced these by staring at pictures for a few hours and trying
different things like top/bottom of chunk, left/right, first/last, etc.
You can see that in some cases this ensures that only one point appears
on a given line segment. But to me the only way to convince yourself
that this really does work is to draw a bunch of pictures, and try it
out! You have cases where two vertical lines intersect, and where
a vertical line intersects a horizontal line.
But there is still one thing which we have forgotten -- the
case of a single point. This can happen in, for instance, a pointy
triangle, pointing in the x-direction. How do we fix this? By
simply avoiding the point: in the line drawing routine, use EOR
to plot the points instead of ORA. Since vertical lines skip the
endpoints, vertical-horizontal intersections are OK. Horizontal-
horizontal intersections will force the point of intersection to
be zero.
Uh-oh, what about intersections like -----*------. Quite frankly
I just thought of it, and I think my program will fail on intersections
like these. Drat. Well, that just gives us something for next time!
One other thing needs to be mentioned: for EOR-filling to be useful
you need to draw the polygon in a special buffer, and then EOR this buffer
into the main display buffer. If you try to EOR the display buffer directly
you are going to have a whole heap of trouble, such as the concerns raised
last time.
Finally, this gives a simple way of filling with patterns instead
of boring monocolor. Instead of EOR (EORBUF),Y : ORA (DRAWBUF),Y you can
use EOR (EORBUF),Y : AND PATTERN,Y : ORA (DRAWBUF),Y (as long as you
preserve the original EOR (EORBUF),Y).
Well I am extremely tired and I hope Craig hasn't sent out C=Hacking
without me! I hope you have fun playing with the program, and I would be
very interested in seeing any neat geometric shapes you might design!
Program notes:
--------------
- Hidden faces defaults to "on". If you enter a shape and a black
screen comes up, hit 'h' to turn off hidden faces (you probably
entered the polygon clockwise).
- There is no pattern filling -- just simple EOR with a twist:
the EOR buffer is EOR'd into the drawing buffer.
- You might start hosing memory if you zoom too large.
SLJ 6/15/95
Addendum
--------
Stephen Judd sjudd@nwu.edu
Last time we put a circle into the 2D graphics toolbox. Chris
McBride has pointed something out to me about the algorithm, which makes
it complete. As you may recall, the algorithm gave a very squarish
circle for small radii. Chris told me that setting the initial counter
value to R/2, instead of R, gave a perfect circle. What is going on?
If you recall the algorithm, we are computing a fractional quantity,
and when that quantity becomes larger than one, we decrease X. Wouldn't
it be a whole lot smarter to round off that fraction instead of
truncate it? Of course it would, and that is what starting the counter
at R/2 does.
So, to update the previous algorithm, A should be initialized to
R/2 instead of R, which means that we change
LDA R
to
LDA R
LSR
for a perfect circle every time.
begin 666 cube3d3.2.s
M ' J*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*@TJH*"@H*"@H*"@
MH*"@H*"@H*"@H*"@H*"@H*"@H*"@*@TJH'-415!(14Z@:E5$1*"@H*"@H*"@
MH*"@H*"@H*"@*@TJH&=%3U)'1:!T05E,3U*@H*"@H*"@H*"@H*"@H*"@*@TJ
MH'-405)4140ZH#<O,3$O.32@H*"@H*"@H*"@H*"@*@TJH&9)3DE32$5$.J W
M+S$Y+SDTH*"@H*"@H*"@H*"@*@TJH%8R+C"@8T]-4$Q%5$5$.J Q,B\Q-R\Y
M-*"@H*"@*@TJH%8S+C"@8T]-4$Q%5$5$.J S+S(P+SDUH*"@H*"@*@TJH%8S
M+C&@8T]-4$Q%5$5$.J V+S$T+SDUH*"@H*"@*@TJH%8S+C*@8T]-4$Q%5$5$
M.J V+S$U+SDUH*"@H*"@*@TJH*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@
MH*"@*@TJH'=%3$PLH$E&H$%,3*!'3T53H%=%3$R@5$A)4Z"@*@TJH%!23T=2
M04V@5TE,3*!23U1!5$6@0:!#54)%+J"@*@TJH*"@H*"@H*"@H*"@H*"@H*"@
MH*"@H*"@H*"@H*"@*@TJH%8R+C"@*Z!N15>@04Y$H&E-4%)/5D5$(:"@H*"@
M*@TJH&Y/5Z!7251(H$9!4U1%4J!23U5424Y%4RR@H*"@*@TJH$A)1$1%3J!3
M55)&04-%4RR@1DE,3$5$H*"@H*"@*@TJH$9!0T53+*!!3D2@15A44D&@5$]0
MH%-%0U)%5*"@*@TJH%1%6%2@34534T%'15,AH*"@H*"@H*"@H*"@H*"@*@TJ
MH*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@*@TJH%8S+C"@*Z!F05-4
MH$-(54Y+6:!,24Y%H*"@H*"@*@TJH%)/551)3D4NH*"@H*"@H*"@H*"@H*"@
MH*"@H*"@*@TJH*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@*@TJH%8S
M+C&@*Z!G14Y%4D%,H%!/3%E'3TZ@4$Q/5*"@*@TJH%=)5$B@2$E$1$5.H$9!
M0T53H"AX+5!23T150U0I*@TJH$%.1*!:3T]-H$9%05154D4NH*"@H*"@H*"@
MH*"@*@TJH*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@*@TJH%8S+C*@
M*Z!E;W(M0E5&1D52H$9)3$Q)3D>@H*"@*@TJH*"@H*"@H*"@H*"@H*"@H*"@
MH*"@H*"@H*"@H*"@*@TJH'1(25.@4%)/1U)!3:!)4Z!)3E1%3D1%1*!43Z"@
M*@TJH$%#0T]-4$%.6:!42$6@05)424-,1:!)3J"@H*"@*@TJH&,]:$%#2TE.
M1RR@:E5.+J Y-:!)4U-512Z@H*"@*@TJH&9/4J!$151!24Q3H$].H%1(25.@
M4%)/1U)!32R@*@TJH%)%042@5$A%H$%25$E#3$4AH*"@H*"@H*"@H*"@*@TJ
MH*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@*@TJH'=2251%H%1/H%53
M(:"@H*"@H*"@H*"@H*"@H*"@*@TJH*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@
MH*"@H*"@*@TJH&U94T5,1J!72$5.H%E/54Y'H$1)1*"@H*"@H*"@*@TJH$5!
M1T523%F@1E)%455%3E2@H*"@H*"@H*"@H*"@*@TJH&1/0U1/4J!!3D2@<T%)
M3E0LH$%.1*!(14%21*"@*@TJH$=214%4H&%21U5-14Y4H*"@H*"@H*"@H*"@
MH*"@*@TJH*!A0D]55*!)5*!!3D2@04)/550ZH$)55*"@H*"@*@TJH*!%5D52
M34]21:"@H*"@H*"@H*"@H*"@H*"@H*"@*@TJH&-!346@3U54H$)9H%1(1:!3
M04U%H&1/3U*@H*"@*@TJH$%3H$E.H&F@5T5.5"Z@H*"@H*"@H*"@H*"@H*"@
M*@TJH*"@H"V@<E5"04E9052@H*"@H*"@H*"@H*"@H*"@*@TJH*"@H*"@H*"@
MH*"@H*"@H*"@H*"@H*"@H*"@H*"@*@TJH'1(3U5'2*!IH%-014%+H%=)5$B@
M5$A%H*"@H*"@*@TJH%1/3D=515.@3T:@345.H$%.1*!/1J!!3D=,15.@*@TJ
MH$%.1*!(059%H$Y/5*!,3U9%+*!IH$%-H*"@H*"@*@TJH$)%0T]-1:!!4Z!3
M3U5.1$E.1Z!"4D%34RR@3U*@*@TJH$&@5$E.2TQ)3D>@0UE-0D%,+J"@H*"@
MH*"@H*"@*@TJH*"@H"V@,:!C3U))3E1(24%.4Z Q,Z"@H*"@H*"@*@TJH*"@
MH*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@H*"@*@TJH' N<RZ@=$A)4Z!705.@
M5U))5%1%3J!54TE.1Z"@*@TJH*"@H*"@;4523$E.H#$R."Z@H*"@H*"@H*"@
MH*"@*@TJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*@T-(&]R9R D
M.# P, T-*J!C3TY35$%.5%,-#6)U9F8Q(&5Q=2 D,S P," [9DE24U2@0TA!
M4D%#5$52H%-%5 UB=69F,B!E<74@)#,X,# @.W-%0T].1*!#2$%204-415*@
M4T54#65O<F)U9B!E<74@)#0P,# @.V5O<BU"549&15(-8G5F9F5R(&5Q=2 D
M83,@.W!215-534%"3%F@5$A%H%1!4$6@5T].)U2@0D6@4E5.3DE.1PUX,2!E
M<74@)&9B(#MP3TE.5%.@1D]2H$1205=)3D>@0:!,24Y%#7DQ(&5Q=2 D9F,@
M.W1(15-%H%I%4D^@4$%'1:!!1$1215-315,->#(@97%U("1F9" [1$].)U2@
M0T].1DQ)0U2@5TE42*!B87-I8PUY,B!E<74@)&9E#6]L9'@@97%U("1F9 UC
M:'5N:R!E<74@)&9E#61X(&5Q=2 D-C<@.W1(25.@25.@4TA!4D5$H%=)5$B@
M=#&@0D5,3U<-9'D@97%U("0V. UT96UP,2!E<74@)&9B(#MO1J!#3U524T4L
MH$-/54Q$H$-/3D9,24-4H%=)5$B@6#$-=&5M<#(@97%U("1F8R [=$5-4$]2
M05)9H%9!4DE!0DQ%4PUZ=&5M<"!E<74@)# R(#MU4T5$H$9/4J!"549&15*@
M4U=!4"Z@H&1/3B=4H%1/54-(+@UZ,2!E<74@)#(R(#MU4T5$H$)9H$U!5$B@
M4D]55$E.10UZ,B!E<74@)#(T(#MD3TXG5*!43U5#2*!42$531:!%251(15(A
M#7HS(&5Q=2 D,C8->C0@97%U("0R. UK(&5Q=2 D8C8@.V-/3E-404Y4H%53
M142@1D]2H$A)1$1%3@T@(" [4U521D%#1:!$151%0U1)3TZ@+:!$3TXG5*!4
M3U5#2 UH:61E(&5Q=2 D8C4@.V%21:!355)&04-%4Z!(241$14X_#69I;&P@
M97%U("0U," [85)%H%=%H%5324Y'H&5O<BU&24Q,/PUA;F=M87@@97%U(#$R
M," [=$A%4D6@05)%H#(J4$DO04Y'34%8H$%.1TQ%4PT-*J!V:6,-#79M8W-B
M(&5Q=2 D9# Q. UB:V=N9"!E<74@)&0P,C -8F]R9&5R(&5Q=2 D9# R,0US
M<W1A<G0@97%U(#$S-#0@.U)/5Z YH$E.H%-#4D5%3J!-14U/4EF@052@,3 R
M- T-#2J@:T523D%,#0UC:')O=70@97%U("1F9F0R#6=E=&EN(&5Q=2 D9F9E
M- T-*J!S3TU%H%9!4DE!0DQ%4PT-9VQO8GAM:6X@/2 D,V8@.W1(15-%H$%2
M1:!54T5$H$E.H$-,14%224Y'H%1(10UG;&]B>&UA>" ]("0T," [1%)!5TE.
M1Z H1TQ/0D%,*:!"549&15(-9VQO8GEM:6X@/2 D-#$-9VQO8GEM87@@/2 D
M-#(-;&]C>&UI;B ]("0U-R [=$A%4T6@05)%H%53142@24Z@0TQ%05))3D>@
M5$A%#6QO8WAM87@@/2 D-3@@.V5O<J H3$]#04PIH$)51D9%4@UL;V-Y;6EN
M(#T@)#4Y#6QO8WEM87@@/2 D-C -<#%X(#T@)#DR(#MT2$531:!!4D6@5$5-
M4$]205)9H%-43U)!1T4-<#%Y(#T@)#DS(#MU4T5$H$E.H%!,3U1424Y'H%1(
M1:!04D]*14-424].#7 Q>B ]("0Y- UP,G@@/2 D.34@.W1(15F@05)%H$A%
M4D6@4T^@5$A!5*!710UP,GD@/2 D.38@.T1/3B=4H$A!5D6@5$^@4D5#04Q#
M54Q!5$6@5$A%32X-<#)Z(#T@)&%E#7 S>" ]("1A9B [=$A%6:!-04M%H$Q)
M1D6@14%362X-<#-Y(#T@)&(P#7 S>B ]("1B,2 [=TA9H$%21:!93U6@3$]/
M2TE.1Z!!5*!-1:!,24M%H%1(050_#7 Q=" ]("1B,B [9$].)U2@64]5H%12
M55-4H$U%/PUP,G0@/2 D8C,-<#-T(#T@)&(T(#MH059)3D>@04Y/5$A%4J!#
M2$E,1*!705-.)U2@35F@241%02X-:6YD97@@/2 D-3$-8V]U;G1P=',@/2 D
M-3(->F]O;2 ]("0W,2 [>D]/3:!&04-43U(-9'-X(#T@)#8Q(#MD<WB@25.@
M5$A%H$E.0U)%345.5*!&3U(-(" @.U)/5$%424Y'H$%23U5.1*!8#61S>2 ]
M("0V,B [<TE-24Q!4J!&3U*@9'-Y+*!D<WH-9'-Z(#T@)#8S#7-X(#T@)#8T
M(#MT2$531:!!4D6@5$A%H$%#5%5!3*!!3D=,15.@24Z@6*!9H$%.1*!:#7-Y
M(#T@)#8U#7-Z(#T@)#8V#70Q(#T@)#8W(#MT2$531:!!4D6@55-%1*!)3J!4
M2$6@4D]4051)3TX-=#(@/2 D-C@-=#,@/2 D-CD@.W-%1:!42$6@05)424-,
M1:!&3U*@34]21:!$151!24Q3#70T(#T@)#9A#70U(#T@)#9B#70V(#T@)#9C
M#70W(#T@)#9D#70X(#T@)#9E#70Y(#T@)#9F#70Q," ]("0W, UA,3$@/2 D
M834@.W1(15-%H$%21:!42$6@14Q%345.5%.@3T:@5$A%H%)/5$%424].H$U!
M5%))6 UB,3(@/2 D838@.WAY>@UC,3,@/2 D83<-9#(Q(#T@)&$X(#MT2$6@
M3E5-0D52H$1%3D]415.@*%)/5RQ#3TQ534XI#64R,B ]("1A.0UF,C,@/2 D
M86$-9S,Q(#T@)&%B#6@S,B ]("1A8PUI,S,@/2 D860-#0TJ*BJ@;4%#4D]3
M#0UM;W9E(&UA8PT@;&1A(%TQ#2!S=&$@73(-(#P\/ T-9V5T:V5Y(&UA8R @
M.W=!252@1D]2H$&@2T594%)%4U,-=V%I="!J<W(@9V5T:6X-(&-M<" C,# -
M(&)E<2!W86ET#2 \/#P-#61E8G5G(&UA8R @.W!224Y4H$&@0TA!4D%#5$52
M#2!D;Z PH* [9$].)U2@05-314U"3$4-#2!L9&&@(UTQ#2!J<W*@8VAR;W5T
M#2!C;&D-(#X^/B!G971K97D@.V%.1*!704E4H%1/H$-/3E1)3E5%#2!C;7 @
M(R=3)R [;5F@4T5#4D5#5*!35TE40TB@2T59#2!B;F4@;#$-(&IS<B!C;&5A
M;G5P#2!J;7 @9&]N90UL,2!C;7 @(R=8)R [;5F@4T5#4D54H$%"3U)4H$M%
M60T@8FYE(&1O;F4-(&IM<"!C;&5A;G5P#2!F:6X-9&]N92 \/#P-#61E8G5G
M82!M86,-(&1OH# -(&QD82!=,0T@<W1A(#$P,C0-(&9I;@UD;VYE82 \/#P-
M#2HM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM#0T@;&1A(",D,# -
M('-T82!B:V=N9 T@<W1A(&)O<F1E<@T@;&1A('9M8W-B#2!A;F0@(R4P,# P
M,3$Q,2 [<T-2145.H$U%34]26:!43Z Q,#(T#2!O<F$@(R4P,# Q,# P, T@
M<W1A('9M8W-B#0T@;&1Y(",P, T@;&1A(",\='1E>'0-('-T82!T96UP,0T@
M;&1A(",^='1E>'0-('-T82!T96UP,@T@:FUP('1I=&QE#71T97AT(&AE>" Y
M,S U,3$Q,3$Q(#M#3$5!4J!30U)%14XLH%=(251%+*!#4E-2H$1.#2!T>'0@
M)Z"@H*"@H*"@H*"@H*!#54)%,T2@5C,N,B<L,$0L,$0-('1X=" GH*"@H*"@
MH*"@H*"@H*"@H*"@0EDG+#!$#2!H97@@.68@.T-904X-('1X=" GH*"@H%-4
M15!(14Z@2E5$1"<-(&AE>" Y.0T@='AT(">@H*"@1T5/4D=%H%1!64Q/4B<L
M,$0L,$0-(&AE>" Y8@T@='AT(">@H$-(14-+H$]55*!42$6@2D%.+J Y-:!)
M4U-51:!/1B<L,$0-(&AE>" Y-@T@='AT(">@H$,]2$%#2TE.1R<-(&AE>" Y
M8@T@='AT(">@1D]2H$U/4D6@1$5404E,4R$G+#!$#2!H97@@,&0Q9#%D.64Q
M,@T@='AT("=&,2]&,B<L.3(-('1X=" GH"V@24Y#+T1%0Z!8+5)/5$%424].
M)RPP1 T@:&5X(#%D,60Q,@T@='AT("=&,R]&-"<L.3(-('1X=" GH"V@24Y#
M+T1%0Z!9+5)/5$%424].)RPP1 T@:&5X(#%D,60Q,@T@='AT("=&-2]&-B<L
M.3(-('1X=" GH"V@24Y#+T1%0Z!:+5)/5$%424].)RPP1 T@:&5X(#%D,60Q
M,@T@='AT(">@1C>@H"<L.3(-('1X=" GH"V@4D53150G+#!$#2!H97@@,60Q
M9#$R#2!T>'0@)Z K+RV@)RPY,@T@='AT(">@+:!:3T]-H$E.+T]55"<L,$0-
M(&AE>" Q9#%D,3(-('1X=" GH*!(H* G+#DR#2!T>'0@)Z MH%1/1T=,1:!(
M241$14Z@4U521D%#15,G+#!$#2!H97@@,60Q9#$R#2!T>'0@)U-004-%)RPY
M,@T@='AT(">@+:!43T='3$6@4U521D%#1:!&24Q,24Y')RPP1"PP1 T@='AT
M(">@H%!215-3H%&@5$^@455)5"<L,$0-(&AE>" P9# U#2!T>'0@)Z"@H*"@
MH%!215-3H$%.6:!+15F@5$^@0D5'24XG+#!$#2!H97@@,# -=&ET;&4@;&1A
M("AT96UP,2DL>0T@8F5Q(#IC;VYT#2!J<W(@8VAR;W5T#2!I;GD-(&)N92!T
M:71L90T@:6YC('1E;7 R#2!J;7 @=&ET;&4-.F-O;G0@/CX^(&=E=&ME>0T-
M*BHJ*J!S152@55"@5$%"3$53*#\I#0TJH'1!0DQ%4Z!!4D6@0U524D5.5$Q9
MH%-%5*!54*!)3J!B87-I8PTJH$%.1*!"6:!42$6@05-314U"3$52+@T-=&%B
M;&5S(&QD82 C/G1M871H,0T@<W1A('HQ*S$-('-T82!Z,BLQ#2!L9&$@(SYT
M;6%T:#(-('-T82!Z,RLQ#2!S=&$@>C0K,0T-*BHJ*J!C3$5!4J!30U)%14Z@
M04Y$H%-%5*!54* B0DE434%0(@US971U<"!L9&$@(R0P,2 [=TA)5$4-('-T
M82 D9# R,2 [=$A)4Z!)4Z!$3TY%H%-/H%1(052@3TQ$15(-(&QD82 C,30W
M(#M-04-(24Y%4Z!724Q,H%-%5*!54 T@:G-R(&-H<F]U= T@;&1A(",D,# @
M.T-/4E)%0U1,60T@<W1A("1D,#(Q#2!L9&$@(SQS<W1A<G0-(&%D8R C,3(@
M.W1(1:!'3T%,H$E3H%1/H$-%3E1%4J!42$6@1U)!4$A)0U,-('-T82!T96UP
M,2 [8T],54U.H#$R#2!L9&$@(SYS<W1A<G0@.W)/5Z Y#2!S=&$@=&5M<#$K
M,2 [<W-T87)TH%!/24Y44Z!43Z!23U>@.0T@;&1A(",P, T@;&1Y(",P, T@
M;&1X(",P," [6*!724Q,H$-/54Y4H#$VH%)/5U.@1D]2H%53#2!C;&,-#3IL
M;V]P('-T82 H=&5M<#$I+'D-(&EN>0T@861C(",Q-@T@8F-C(#IL;V]P#2!C
M;&,-(&QD82!T96UP,0T@861C(",T," [;D5%1*!43Z!!1$2@-#"@5$^@5$A%
MH$)!4T6@4$])3E1%4@T@<W1A('1E;7 Q(#MT3Z!*54U0H%1/H%1(1:!.15A4
MH%)/5PT@;&1A('1E;7 Q*S$-(&%D8R C,# @.W1!2T6@0T%21:!/1J!#05)2
M2453#2!S=&$@=&5M<#$K,0T@;&1Y(",P, T@:6YX#2!T>&$@(#MXH$E3H$%,
M4T^@04Z@24Y$15B@24Y43Z!42$6@0TA!4D%#5$52H$Y534)%4@T@8W!X(",Q
M-@T@8FYE(#IL;V]P(#MN145$H%1/H$1/H$E4H#$VH%1)3453#0TJ*BHJH&-,
M14%2H$)51D9%4E,-#2!L9&$@(SQB=69F,0T@<W1A(&)U9F9E<@T@;&1A(",^
M8G5F9C$-('-T82!B=69F97(K,0T@;&1Y(",D,# -(&QD>" C,C0@.V%34U5-
M24Y'H$%,3*!42%)%1:!"549&15)3H$%210T@;&1A(",D,# @.T)!0TLM5$\M
M0D%#2PTZ8FQO;W @<W1A("AB=69F97(I+'D-(&EN>0T@8FYE(#IB;&]O< T@
M:6YC(&)U9F9E<BLQ#2!D97@-(&)N92 Z8FQO;W -#2HJ*BJ@<T54H%50H$)5
M1D9%4E,-#2!L9&$@(SQB=69F,0T@<W1A(&)U9F9E<@T@;&1A(",^8G5F9C$-
M('-T82!B=69F97(K,0T@<W1A('IT96UP(#M:5$5-4*!724Q,H$U!2T6@3$E&
M1:!324U03$6@1D]2H%53#2!L9&$@=FUC<V(-(&%N9" C)3$Q,3$P,# Q(#MS
M5$%25*!(15)%H%-/H%1(052@4U=!4*!"549&15)3H%=)3$R@5T]22Z!224=(
M5 T@;W)A(",E,# P,#$Q,3 -('-T82!V;6-S8@T-*BHJ*J!S152@55"@24Y)
M5$E!3*!604Q515,-#6EN:70@;&1A(",P, T@<W1A(&QO8WAM:6X-('-T82!L
M;V-X;6%X#2!S=&$@;&]C>6UI;@T@<W1A(&QO8WEM87@-('-T82!G;&]B>&UI
M;@T@<W1A(&=L;V)Y;6EN#2!S=&$@9VQO8GAM87@-('-T82!G;&]B>6UA> T@
M<W1A(&1S> T@<W1A(&1S>0T@<W1A(&1S>@T@<W1A('-X#2!S=&$@<WD-('-T
M82!S>@T@<W1A(&9I;&P-(&QD82 C,#$-('-T82!H:61E#2!L9&$@(S8T#2!S
M=&$@>F]O;0T-*BTM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2T-*J!M
M04E.H$Q/3U -#2HJ*BJ@9T54H$M%65!215-3#0UM86EN#2!C;&D-:W!R97-S
M(&IS<B!G971I;@T@8VUP(",Q,S,@.V8Q/PT@8FYE(#IF,@T@;&1A(&1S> T@
M8VUP("-A;F=M87@O,B [;D^@34]21:!42$%.H%!)#2!B97$@.F-O;G0Q#2!I
M;F,@9'-X(#M/5$A%4E=)4T6@24Y#4D5!4T6@6"U23U1!5$E/3@T@:FUP(#IC
M;VYT#3IF,B!C;7 @(S$S-R [9C(_#2!B;F4@.F8S#2!L9&$@9'-X#2!B97$@
M.F-O;G0Q#2!D96,@9'-X#2!J;7 @.F-O;G0-.F8S(&-M<" C,3,T#2!B;F4@
M.F8T#2!L9&$@9'-Y#2!C;7 @(V%N9VUA>"\R#2!B97$@.F-O;G0Q#2!I;F,@
M9'-Y(#MI3D-214%31:!9+5)/5$%424].#2!J;7 @.F-O;G0-.F8T(&-M<" C
M,3,X#2!B;F4@.F8U#2!L9&$@9'-Y#2!B97$@.F-O;G0Q#2!D96,@9'-Y#2!J
M;7 @.F-O;G0-.F8U(&-M<" C,3,U#2!B;F4@.F8V#2!L9&$@9'-Z#2!C;7 @
M(V%N9VUA>"\R#2!B97$@.F-O;G0Q#2!I;F,@9'-Z(#M:+5)/5$%424].#2!J
M;7 @.F-O;G0-.F8V(&-M<" C,3,Y#2!B;F4@.F8W#2!L9&$@9'-Z#2!B97$@
M.F-O;G0Q#2!D96,@9'-Z#2!J;7 @.F-O;G0-.F8W(&-M<" C,3,V#2!B;F4@
M.G!L=7,-(&IM<"!I;FET#3IC;VYT,2!J;7 @.F-O;G0-.G!L=7,@8VUP(",G
M*R<-(&)N92 Z;6EN=7,-(&EN8R!Z;V]M(#MB04@LH%=(3Z!.145$4Z!%4E)/
M4J!#2$5#2TE.1S\-(&EN8R!Z;V]M#2!J;7 @.F-O;G0-.FUI;G5S(&-M<" C
M)RTG#2!B;F4@.F@-(&1E8R!Z;V]M#2!D96,@>F]O;0T@8G!L(#IC;VYT#2!I
M;F,@>F]O;0T@:6YC('IO;VT-(&IM<" Z8V]N= TZ:"!C;7 @(R=()PT@8FYE
M(#IS<&%C90T@;&1A(&AI9&4-(&5O<B C)# Q#2!S=&$@:&ED90T@:FUP(#IC
M;VYT#3IS<&%C92!C;7 @(R>@)PT@8FYE(#IQ#2!L9&$@9FEL; T@96]R(",D
M,#$-('-T82!F:6QL#2!J;7 @.F-O;G0-.G$@8VUP(",G42<@.U&@455)5%,-
M(&)N92 Z8V]N= T@:FUP(&-L96%N=7 -#3IC;VYT('-E:2 @.W-0145$H%1(
M24Y'4Z!54*!!H$))5 T-*BHJ*J!U4$1!5$6@04Y'3$53#0UU<&1A=&4@8VQC
M#2!L9&$@<W@-(&%D8R!D<W@-(&-M<" C86YG;6%X(#MA4D6@5T6@/CV@34%8
M24U53:!!3D=,13\-(&)C8R Z8V]N=#$-('-B8R C86YG;6%X(#II1B!33RP@
M4D53150-.F-O;G0Q('-T82!S> T@8VQC#2!L9&$@<WD-(&%D8R!D<WD-(&-M
M<" C86YG;6%X#2!B8V,@.F-O;G0R#2!S8F,@(V%N9VUA>" [<T%-1:!$14%,
M#3IC;VYT,B!S=&$@<WD-(&-L8PT@;&1A('-Z#2!A9&,@9'-Z#2!C;7 @(V%N
M9VUA> T@8F-C(#IC;VYT,PT@<V)C("-A;F=M87@-.F-O;G0S('-T82!S>@T-
M*BHJ*J!R3U1!5$6@0T]/4D1)3D%415,-#7)O=&%T90T-*BHJH&9)4E-4+*!#
M04Q#54Q!5$6@5#$L5#(L+BXN+%0Q, T-*BJ@=%=/H$U!0U)/4Z!43Z!324U0
M3$E&6:!/55*@3$E&10UA9&1A(&UA8R @.V%$1*!45T^@04Y'3$53H%1/1T54
M2$52#2!C;&,-(&QD82!=,0T@861C(%TR#2!C;7 @(V%N9VUA>" [:5.@5$A%
MH%-53: ^H#(J4$D_#2!B8V,@9&]N90T@<V)C("-A;F=M87@@.VE&H%-/+*!3
M54)44D%#5* R*E!)#61O;F4@/#P\#0US=6)A(&UA8R @.W-50E1204-4H%17
M3Z!!3D=,15,-('-E8PT@;&1A(%TQ#2!S8F,@73(-(&)C<R!D;VYE#2!A9&,@
M(V%N9VUA>" [;T]04RR@5T6@3D5%1*!43Z!!1$2@,BI020UD;VYE(#P\/ T-
M*BJ@;D]7H$-!3$-53$%41:!4,2Q4,BQ%5$,N#0T@/CX^('-U8F$L<WD[<WH-
M('-T82!T,2 [5#$]4UDM4UH-(#X^/B!A9&1A+'-Y.W-Z#2!S=&$@=#(@.U0R
M/5-9*U-:#2 ^/CX@861D82QS>#MS>@T@<W1A('0S(#M4,SU36"M36@T@/CX^
M('-U8F$L<W@[<WH-('-T82!T-" [5#0]4U@M4UH-(#X^/B!A9&1A+'-X.W0R
M#2!S=&$@=#4@.U0U/5-8*U0R#2 ^/CX@<W5B82QS>#MT,0T@<W1A('0V(#M4
M-CU36"U4,0T@/CX^(&%D9&$L<W@[=#$-('-T82!T-R [5#<]4U@K5#$-(#X^
M/B!S=6)A+'0R.W-X#2!S=&$@=#@@.U0X/50R+5-8#2 ^/CX@<W5B82QS>3MS
M> T@<W1A('0Y(#M4.3U362U36 T@/CX^(&%D9&$L<W@[<WD-('-T82!T,3 @
M.U0Q,#U36"M360T-*J!E5*!63TE,02$-#2HJ*J!N15A4+*!#04Q#54Q!5$6@
M82QB+&,L+BXN+&D-#2HJH&%.3U1(15*@55-%1E5,H$Q)5%1,1:!-04-23PUD
M:78R(&UA8R @.V1)5DE$1:!!H%-)1TY%1*!.54U"15*@0EF@,@T[:52@25.@
M05-354U%1*!42$%4H%1(1:!.54U"15(-(&)P;"!P;W,@.TE3H$E.H%1(1:!!
M0T-5355,051/4@T@8VQC#2!E;W(@(R1F9B [=T6@3D5%1*!43Z!53BU.14=!
M5$E61:!42$6@3E5-0D52#2!A9&,@(S Q(#M"6:!404M)3D>@250G4Z!#3TU0
M3$5-14Y4#2!L<W(@(#M$259)1$6@0EF@5%=/#2!C;&,-(&5O<B C)&9F#2!A
M9&,@(S Q(#MM04M%H$E4H$Y%1T%4259%H$%'04E.#2!J;7 @9&]N961I=@UP
M;W,@;'-R(" [;E5-0D52H$E3H%!/4TE4259%#61O;F5D:78@/#P\#0UM=6PR
M(&UA8R @.VU53%1)4$Q9H$&@4TE'3D5$H$Y534)%4J!"6: R#2!B<&P@<&]S
M;0T@8VQC#2!E;W(@(R1F9@T@861C(",D,#$-(&%S; T@8VQC#2!E;W(@(R1F
M9@T@861C(",D,#$-(&IM<"!D;VYE;75L#7!O<VT@87-L#61O;F5M=6P@/#P\
M#0TJ*J!N3U1%H%1(052@5T6@05)%H$-54E)%3E1,6:!-04M)3D>@0:!-24Y/
M4J!,14%0#2HJH$]&H$9!251(H%1(052@3D^@3U9%4D9,3U=3H%=)3$R@3T-#
M55(N#0TZ8V%L8V$@8VQC#2!L9'@@=#$-(&QD82!C;W,L> T@;&1X('0R#2!A
M9&,@8V]S+'@-('-T82!A,3$@.V$]*$-/4RA4,2DK0T]3*%0R*2DO,@TZ8V%L
M8V(@;&1X('0Q#2!L9&$@<VEN+'@-('-E8PT@;&1X('0R#2!S8F,@<VEN+'@-
M('-T82!B,3(@.V(]*%-)3BA4,2DM4TE.*%0R*2DO,@TZ8V%L8V,@;&1X('-Y
M#2!L9&$@<VEN+'@-(#X^/B!M=6PR#2!S=&$@8S$S(#MC/5-)3BA362D-.F-A
M;&-D('-E8PT@;&1X('0X#2!L9&$@8V]S+'@-(&QD>"!T-PT@<V)C(&-O<RQX
M#2!S96,-(&QD>"!T-0T@<V)C(&-O<RQX#2!C;&,-(&QD>"!T-@T@861C(&-O
M<RQX(#MD23TH0T]3*%0X*2U#3U,H5#<I*T-/4RA4-BDM0T]3*%0U*2DO,@T@
M/CX^(&1I=C(-(&-L8PT@;&1X('0S#2!A9&,@<VEN+'@-('-E8PT@;&1X('0T
M#2!S8F,@<VEN+'@-('-T82!D,C$@.V0]*%-)3BA4,RDM4TE.*%0T*2MD22DO
M,@TZ8V%L8V4@<V5C#2!L9'@@=#4-(&QD82!S:6XL> T@;&1X('0V#2!S8F,@
M<VEN+'@-('-E8PT@;&1X('0W#2!S8F,@<VEN+'@-('-E8PT@;&1X('0X#2!S
M8F,@<VEN+'@@.V5)/2A324XH5#4I+5-)3BA4-BDM4TE.*%0W*2U324XH5#@I
M*2\R#2 ^/CX@9&EV,@T@8VQC#2!L9'@@=#,-(&%D8R!C;W,L> T@8VQC#2!L
M9'@@=#0-(&%D8R!C;W,L> T@<W1A(&4R,B [93TH0T]3*%0S*2M#3U,H5#0I
M*V5)*2\R#3IC86QC9B!L9'@@=#D-(&QD82!S:6XL> T@<V5C#2!L9'@@=#$P
M#2!S8F,@<VEN+'@-('-T82!F,C,@.V8]*%-)3BA4.2DM4TE.*%0Q,"DI+S(-
M.F-A;&-G(&QD>"!T-@T@;&1A('-I;BQX#2!S96,-(&QD>"!T. T@<V)C('-I
M;BQX#2!S96,-(&QD>"!T-PT@<V)C('-I;BQX#2!S96,-(&QD>"!T-0T@<V)C
M('-I;BQX(#MG23TH4TE.*%0V*2U324XH5#@I+5-)3BA4-RDM4TE.*%0U*2DO
M,@T@/CX^(&1I=C(-(&-L8PT@;&1X('0T#2!A9&,@8V]S+'@-('-E8PT@;&1X
M('0S#2!S8F,@8V]S+'@-('-T82!G,S$@.V<]*$-/4RA4-"DM0T]3*%0S*2MG
M22DO,@TZ8V%L8V@@8VQC#2!L9'@@=#8-(&QD82!C;W,L> T@;&1X('0W#2!A
M9&,@8V]S+'@-('-E8PT@;&1X('0U#2!S8F,@8V]S+'@-('-E8PT@;&1X('0X
M#2!S8F,@8V]S+'@@.VA)/2A#3U,H5#8I*T-/4RA4-RDM0T]3*%0U*2U#3U,H
M5#@I*2\R#2 ^/CX@9&EV,@T@8VQC#2!L9'@@=#,-(&%D8R!S:6XL> T@8VQC
M#2!L9'@@=#0-(&%D8R!S:6XL> T@<W1A(&@S,B [:#TH4TE.*%0S*2M324XH
M5#0I*VA)*2\R#3IW:&5W(&-L8PT@;&1X('0Y#2!L9&$@8V]S+'@-(&QD>"!T
M,3 -(&%D8R!C;W,L> T@<W1A(&DS,R [:3TH0T]3*%0Y*2M#3U,H5#$P*2DO
M,@T-*BJ@:50G4Z!!3$R@1$]73DA)3$R@1E)/3:!(15)%+@T-9&]W;FAI;&P-
M*BHJ*J!C3$5!4J!"549&15(-*J!AH$Q)5%1,1:!-04-23PT-<V5T8G5F(&UA
M8R @.W!55*!"549&15)3H%=(15)%H%1(15F@0T%.H$)%H$A54E0-(&QD82 C
M,# -('-T82!B=69F97(-(&QD82!Z=&5M<" [:$E'2*!"651%#7-T86)U9B!S
M=&$@8G5F9F5R*S$-(#P\/ T-(#X^/B!S971B=68-8VQR9')A=R!L9'@@(S X
M#2!L9&$@(S P#3IF;V]L(&QD>2 C,# -.F1O<&4@<W1A("AB=69F97(I+'D-
M(&EN>0T@8FYE(#ID;W!E#2!I;F,@8G5F9F5R*S$-(&1E> T@8FYE(#IF;V]L
M#0TJ*BHJH&U9H$=/3T1.15-3H$)55*!I)TV@0:!$3U!%#2IC;')D<F%WH&QD
M8:!G;&]B>&UI;@TJH&QS<J"@.VY%142@5$^@1T54H$E.5$^@5$A%H%))1TA4
MH$-/3%5-3@TJH&)C8Z Z979E;J [95A03$%)3D5$H$E.H$U/4D6@1$5404E,
MH$)%3$]7#2J@;&1YH",D.# -*J!S='F@8G5F9F5RH#MP4D5354U!0DQ9H%1(
M25.@5TE,3*!"1:!!H$Q)5%1,10TJH&-L8Z"@.TU/4D6@149&24-)14Y4+@TJ
M.F5V96Z@861CH&)U9F9E<BLQ#2J@<W1AH&)U9F9E<BLQ#2J@;&1AH&=L;V)X
M;6%X#2J@<V5C#2J@<V)CH&=L;V)X;6EN#2J@=&%X#2J@:6YX#2J@;&1YH&=L
M;V)Y;6%X#2J@8F5QH#IR97-E= TJ.GEA>:!L9&&@(R0P, TJH&QD>:!G;&]B
M>6UA> TJ.F)L86B@<W1AH"AB=69F97(I+'D-*J!D97D-*J!C<'F@9VQO8GEM
M:6X-*J!B8W.@.F)L86@-*J!L9&&@8G5F9F5R#2J@96]RH",D.# -*J!S=&&@
M8G5F9F5R#2J@8FYEH#IW:&]P964-*J!I;F.@8G5F9F5R*S$-*CIW:&]P966@
M9&5X#2J@8FYEH#IY87D-*CIR97-E=*!L9&&@(S"@.VY%142@5$^@4D53152@
M5$A%4T6@1U594PTJH'-T8:!G;&]B>&UA> TJH'-T8:!G;&]B>6UA> TJH&QD
M8: C)&9F#2J@<W1AH&=L;V)X;6EN#2J@<W1AH&=L;V)Y;6EN#0TJ
*BHJH&Y%
M6%0LH%)%042@04Y$H$1205>@4$],64=/3E,-#7)E861D<F%W(&QD>2 C,# -
M('-T>2!I;F1E> UO8FIL;V]P(&QD>2!I;F1E> T@;&1A('!O;'EL:7-T+'D@
M.V9)4E-4+*!42$6@3E5-0D52H$]&H%!/24Y44PT@8FYE(#IC;VYT(#MB552@
M24:@3E5-4$])3E13H$E3H%I%4D^@5$A%3@T@:FUP(&]B:F1O;F4@.U=%H$%2
M1:!!5*!42$6@14Y$H$]&H%1(1:!,25-4#3IC;VYT('-T82!C;W5N='!T<PT@
M:6YC(&EN9&5X#0TJH')/5$%41:!04D]*14-4H$%.1*!$4D%7H%1(1:!03TQ9
M1T].#2J@;4%+1:!355)%H$)51D9%4J!"14E.1Z!$4D%73J!43Z!)4Z!#3$5!
M4B$-#3ID;VET(&IS<B!R;W1P<F]J#0TJH&-/3E9%4E2@6$U)3J!!3D2@6$U!
M6*!43Z!#3TQ534Y3#0T@;&1A(&QO8WAM:6X-(&QS<@T@;'-R#2!L<W(@(#M8
MH$U/1* X#2!S=&$@;&]C>&UI;@T@8VUP(&=L;V)X;6EN#2!B8W,@.FYA: T@
M<W1A(&=L;V)X;6EN#3IN86@@;&1A(&QO8WEM:6X-(&-M<"!G;&]B>6UI;@T@
M8F-S(#IU:'5H#2!S=&$@9VQO8GEM:6X-.G5H=6@@;&1A(&QO8WAM87@-(&QS
M<@T@;'-R#2!L<W(-('-T82!L;V-X;6%X#2!C;7 @9VQO8GAM87@-(&)C8R Z
M;F]W87D-('-T82!G;&]B>&UA> TZ;F]W87D@;&1A(&QO8WEM87@-(&-M<"!G
M;&]B>6UA> T@8F-C(&5O<F9I;&P-('-T82!G;&]B>6UA> T-*J!I1J!54TE.
M1Z!42$6@96]R+4)51D9%4BR@0T]06:!)3E1/H$1205=)3D>@0E5&1D52#2J@
M84Y$H%1(14Z@0TQ%05*@5$A%H&5O<BU"549&15(-#65O<F9I;&P@;&1A(&9I
M;&P-(&)E<2!O8FIL;V]P#0T@/CX^('-E=&)U9@T@;&1A(",\96]R8G5F#2!S
M=&$@=&5M<#$-(&QD82 C/F5O<F)U9@T@<W1A('1E;7 Q*S$-#2!L9&$@;&]C
M>&UI;B [;&]C>&UI;J!.3U>@0T].5$%)3E.@0T],54U.#2!L<W(@(#ME04-(
MH$-/3%5-3J!)4Z Q,CB@0EE415,-(&)C8R Z979E;B [<T^@5$A%4D6@34E'
M2%2@0D6@0:!#05)260T@;&1Y(",D.# -('-T>2!B=69F97(-('-T>2!T96UP
M,0T@8VQC#3IE=F5N('-T82!T,@T@861C(&)U9F9E<BLQ#2!S=&$@8G5F9F5R
M*S$@.V5!0TB@0T],54U.H$E3H#$R.*!"651%4PT@;&1A('0R#2!A9&,@=&5M
M<#$K,2 [;D]7H%=%H%=)3$R@4U1!4E2@052@5$A%#2!S=&$@=&5M<#$K,2 [
M0T],54U.#0T@;&1A(&QO8WAM87@-('-E8PT@<V)C(&QO8WAM:6X-('1A>" [
M=$]404R@3E5-0D52H$]&H$-/3%5-3E.@5$^@1$\-(&EN>" @.T4N1RZ@1DE,
M3*!#3TQ534Y3H#$N+C,-(&QD>2!L;V-Y;6%X#2!B;F4@.F9O;W -(&EN8R!L
M;V-Y;6%X#3IF;V]P(&QD>2!L;V-Y;6%X#2!L9&$@(S P#3IG;V]P(&5O<B H
M=&5M<#$I+'D@.V5O<BU"549&15(-('!H80TJH&U!64)%H%!55*!!3J!E;W*@
M0D5,3U<_#2!E;W(@*&)U9F9E<BDL>0T@<W1A("AB=69F97(I+'D-(&QD82 C
M,# @.VU)1TA4H$%3H%=%3$R@0TQ%05*@252@3D]7#2!S=&$@*'1E;7 Q*2QY
M#2!P;&$-(&1E>0T@8W!Y(&QO8WEM:6X-(&)C<R Z9V]O< T@;&1A(&)U9F9E
M<@T@96]R(",D.# -('-T82!B=69F97(-('-T82!T96UP,0T@8FYE(#IB;V]P
M#2!I;F,@8G5F9F5R*S$-(&EN8R!T96UP,2LQ#3IB;V]P(&1E> T@8FYE(#IF
M;V]P#2!J;7 @;V)J;&]O< T-;V)J9&]N90TJ*BHJH'-705"@0E5&1D524PT-
M<W=A<&)U9B!L9&$@=FUC<V(-(&5O<B C)# R(#MP4D545%F@5%))0TM9+*!%
M2#\-('-T82!V;6-S8@T@;&1A(",D,#@-(&5O<B!Z=&5M<" [6E1%35 ]2$E'
M2*!"651%H$I54U2@1DQ)4%,-('-T82!Z=&5M<" [0D545T5%3J D,S"@04Y$
MH"0S. T-(&IM<"!M86EN(#MA4D]53D2@04Y$H$%23U5.1*!71:!'3RXN+@T-
M('1X=" G9T5%H&)204E.+*!72$%4H$1/H%E/5:!704Y4H%1/H$1/H"<-('1X
M=" G5$].24=(5#\G#0TJ*J!R3U1!5$4LH%!23TI%0U0LH$%.1*!35$]21:!4
M2$6@4$])3E13#2H-*J!T2$E3H%!!4E2@25.@0:!324=.249)0T%.5*!#2$%.
M1T6@4TE.0T4-*J!6,BXP+J"@;D]7H$E4H$E3H$&@0T]-4$Q%5$5,6:!'14Y%
M4D%,H%!/3%E'3TZ@4$Q/5%1%4BX-*J!AH%-%5*!/1J!03TE.5%.@25.@4D5!
M1*!)3BR@4D]4051%1*!!3D2@4%)/2D5#5$5$+*!!3D0-*J!03$]45$5$H$E.
M5$^@5$A%H$1205=)3D>@0E5&1D52H"AE;W*@3U*@3D]234%,*2X-#7)O='!R
M;VH-#2J@8:!.14%4H$U!0U)/#6YE9R!M86,@(#MC2$%.1T6@5$A%H%-)1TZ@
M3T:@0:!45T\G4Z!#3TU03$5-14Y4#2!C;&,-(&QD82!=,2 [3E5-0D52+@T@
M96]R(",D9F8-(&%D8R C)# Q#2 \/#P-#2HM+2TM+2TM+2TM+2TM+2TM+2TM
M+2TM+2TM+2TM+2TM#2J@=$A%4T6@34%#4D]3H%)%4$Q!0T6@5$A%H%!2159)
M3U53H%!23TI%0U1)3TX-*J!354)23U5424Y%+@T-<VUU;'2@;6%CH#MM54Q4
M25!,6:!45T^@4TE'3D5$H#@M0DE4#2 [3E5-0D524SJ@82IY+S8TH"T^H&$-
M('-T8:!Z,PT@8VQCH* [=$A)4Z!-54Q425!,6:!)4Z!&3U*@3D]234%,#2!E
M;W*@(R1F9J [3E5-0D524RR@22Y%+J!8/2TV-"XN-C0-(&%D8Z C)# Q#2!S
M=&&@>C0-(&QD8: H>C,I+'D-('-E8PT@<V)CH"AZ-"DL>0T@/#P\H* [84Q,
MH$1/3D6@.BD-#7-M=6QT>B!M86,@.VU53%1)4$Q9H%173Z!324=.142@."U"
M250-(" @.TY534)%4E,ZH&$J>2\V-* M/J!A#2!S=&$@>C$-(&-L8R @.V%.
M1*!42$E3H$U53%1)4$Q9H$E3H%-014-)1DE#04Q,60T@96]R(",D9F8@.T9/
M4J!42$6@4%)/2D5#5$E/3J!005)4+*!72$5210T@861C(",D,#$@.TY534)%
M4E.@05)%H"TQ,3 N+C$Q,*!!3D2@,"XN-# -('-T82!Z,@T@;&1A("AZ,2DL
M>0T@<V5C#2!S8F,@*'HR*2QY#2 \/#P@(#MA3$R@1$].1: Z*0T-<')O:F5C
M="!M86,@(#MT2$6@04-454%,H%!23TI%0U1)3TZ@4D]55$E.10T[=$A%H%)/
M551)3D6@5$%+15.@5$A%H%!/24Y4#3M=,:!=,J!=,RR@4D]4051%4Z!!3D0-
M.U!23TI%0U13H$E4+*!!3D2@4U1/4D53H%1(10T[4D5354Q4H$E.H%TQH%TR
MH%TS+@T-(&QD>2!=,2 [;55,5$E03%F@1DE24U2@4D]4051)3TZ@0T],54U.
M#2!L9&$@83$Q#2 ^/CX@<VUU;'0-('-T82!P,70-(&QD82!D,C$-(#X^/B!S
M;75L= T@<W1A(' R= T@;&1A(&<S,0T@/CX^('-M=6QT#2!S=&$@<#-T#2!L
M9'D@73(@.W-%0T].1*!#3TQ534X-(&QD82!B,3(-(#X^/B!S;75L= T@8VQC
M#2!A9&,@<#%T#2!S=&$@<#%T#2!L9&$@93(R#2 ^/CX@<VUU;'0-(&-L8PT@
M861C(' R= T@<W1A(' R= T@;&1A(&@S,@T@/CX^('-M=6QT#2!C;&,-(&%D
M8R!P,W0-('-T82!P,W0-(&QD>2!=,R [=$A)4D2@0T],54U.#2!L9&$@8S$S
M#2 ^/CX@<VUU;'0-(&-L8PT@861C(' Q= T@<W1A(' Q= T@;&1A(&8R,PT@
M/CX^('-M=6QT#2!C;&,-(&%D8R!P,G0-('-T82!P,G0-(&QD82!I,S,-(#X^
M/B!S;75L= T@8VQC#2!A9&,@<#-T#2!S=&$@73,@.W)/5$%4142@>@T@=&%X
M#2!L9'D@>F1I=BQX(#MT04),1:!/1J!$+RA:*UHP*0T@(" [;D]7H'F@0T].
M5$%)3E.@4%)/2D5#5$E/3J!#3TY35 T-(&QD82!P,70-(#X^/B!S;75L='H-
M(&QD>"!Z;V]M#2!C<'@@(S8T#2!B97$@8V]N='@-('-T>2!T96UP,0T@;&1Y
M('IO;VT-(#X^/B!S;75L= T@;&1Y('1E;7 Q#6-O;G1X(&-L8PT@861C(",V
M-" [;T9&4T54H%1(1:!#3T]21$E.051%#2!S=&$@73$@.W)/5$%4142@04Y$
MH%!23TI%0U1%1 T@8VUP(&QO8WAM:6X@.W-%1:!)1J!)5*!)4Z!!H$Q/0T%,
MH$U)3DE-54T-(&)C<R!N;W1X;6EN#2!S=&$@;&]C>&UI;@UN;W1X;6EN(&-M
M<"!L;V-X;6%X#2!B8V,@;F]T>&UA> T@<W1A(&QO8WAM87@-#6YO='AM87@@
M;&1A(' R= T@/CX^('-M=6QT>@T@8W!X(",V- T@8F5Q(&-O;G1Y#2!L9'D@
M>F]O;0T@/CX^('-M=6QT#6-O;G1Y(&-L8PT@861C(",V- T@<W1A(%TR(#MR
M3U1!5$5$H$%.1*!04D]*14-4142@>0T@8VUP(&QO8WEM:6X-(&)C<R!N;W1Y
M;6EN#2!S=&$@;&]C>6UI;@UN;W1Y;6EN(&-M<"!L;V-Y;6%X#2!B8V,@;F]T
M>6UA> T@<W1A(&QO8WEM87@-#6YO='EM87@@/#P\(" [84Q,H$1/3D4-#2J@
M;&1AH",\96]R8G5FH#MF25)35*!71:!.145$H%1/H$-,14%2H%1(10TJH'-T
M8:!B=69F97*@.V5O<J!"549&15(-*J!L9&&@(SYE;W)B=68-*J!S=&&@8G5F
M9F5R*S$-#2!L9&$@(S @.W)%4T54H'E-24Z@04Y$H'E-05@-('-T82!L;V-Y
M;6%X#2!S=&$@;&]C>&UA> T@;&1A(",D9F8-('-T82!L;V-Y;6EN#2!S=&$@
M;&]C>&UI;@T-<F5A9'!T<R!L9'D@:6YD97@-(&QD82!P;VQY;&ES="QY#2!S
M=&$@<#%X#2!I;GD-(&QD82!P;VQY;&ES="QY#2!S=&$@<#%Y#2!I;GD-(&QD
M82!P;VQY;&ES="QY#2!S=&$@<#%Z#2!I;GD-(&1E8R!C;W5N='!T<PT@;&1A
M('!O;'EL:7-T+'D-('-T82!P,G@-(&EN>0T@;&1A('!O;'EL:7-T+'D-('-T
M82!P,GD-(&EN>0T@;&1A('!O;'EL:7-T+'D-('-T82!P,GH-(&EN>0T@9&5C
M(&-O=6YT<'1S#2!L9&$@<&]L>6QI<W0L>0T@<W1A(' S> T@:6YY#2!L9&$@
M<&]L>6QI<W0L>0T@<W1A(' S>0T@:6YY#2!L9&$@<&]L>6QI<W0L>0T@<W1A
M(' S>@T@:6YY#2!S='D@:6YD97@-(#X^/B!P<F]J96-T+' Q>#MP,7D[<#%Z
M#2 ^/CX@<')O:F5C="QP,G@[<#)Y.W R>@T@/CX^('!R;VIE8W0L<#-X.W S
M>3MP,WH-#2!L9&$@:&ED90T@8F5Q(#ID;VET#2!L9&$@<#)X(#MH241$14Z@
M1D%#1:!#2$5#2PT@<V5C#2!S8F,@<#%X#2!T87D@(#MY/2A8,BU8,2D-(&QD
M82!P,WD-('-E8PT@<V)C(' R>2 [83TH63,M63(I#2 ^/CX@<VUU;'0-('-T
M82!T96UP,0T@;&1A(' S> T@<V5C#2!S8F,@<#)X#2!T87D-(&QD82!P,GD-
M('-E8PT@<V)C(' Q>0T@/CX^('-M=6QT#2!C;7 @=&5M<#$@.VE&H%@Q*EDR
M+5DQ*E@RH#Z@,*!42$5.H$9!0T4-(&)M:2 Z9&]I=" [25.@5DE324),10T@
M9&5C(&-O=6YT<'1S(#MO5$A%4E=)4T6@4D5!1*!)3J!214U!24Y)3D<-(&)E
M<2 Z86)O<G0@.U!/24Y44Z!!3D2@4D5455).#3IP;V]P(&EN8R!I;F1E> T@
M:6YC(&EN9&5X#2!I;F,@:6YD97@-(&1E8R!C;W5N='!T<PT@8FYE(#IP;V]P
M#3IA8F]R="!R=',-#3ID;VET(&QD82!P,7@-('-T82!X,0T@;&1A(' Q>0T@
M<W1A('DQ#2!L9&$@<#)X#2!S=&$@>#(-(&QD82!P,GD-('-T82!Y,@T@:G-R
M(&1R87<-(&QD82!P,G@-('-T82!X,0T@;&1A(' R>0T@<W1A('DQ#2!L9&$@
M<#-X#2!S=&$@>#(-(&QD82!P,WD-('-T82!Y,@T@:G-R(&1R87<-#2!D96,@
M8V]U;G1P=',-(&)N92!P;VQY;&]O<" [:5.@252@2E535*!!H%1224%.1TQ%
M/PT@:FUP('!O;'ED;VYE#0UP;VQY;&]O<"!L9'D@:6YD97@-(&QD82!P;VQY
M;&ES="QY#2!S=&$@<#)X#2!I;GD-(&QD82!P;VQY;&ES="QY#2!S=&$@<#)Y
M#2!I;GD-(&QD82!P;VQY;&ES="QY#2!S=&$@<#)Z#2!I;GD-('-T>2!I;F1E
M> T@/CX^('!R;VIE8W0L<#)X.W R>3MP,GH-#2!L9&$@<#)X#2!S=&$@>#$-
M(&QD82!P,GD-('-T82!Y,0T@;&1A(' S> T@<W1A('@R#2!L9&$@<#-Y#2!S
M=&$@>3(-(&IS<B!D<F%W#0T@;&1A(' R> T@<W1A(' S> T@;&1A(' R>0T@
M<W1A(' S>0T@9&5C(&-O=6YT<'1S#2!B97$@<&]L>61O;F4-(&IM<"!P;VQY
M;&]O< UP;VQY9&]N92!L9&$@<#%X(#MC3$]31:!42$6@4$],64=/3@T@<W1A
M('@R#2!L9&$@<#%Y#2!S=&$@>3(-(&QD82!P,W@-('-T82!X,0T@;&1A(' S
M>0T@<W1A('DQ#2!J<W(@9')A=PT@<G1S#0T@='AT("=S04U%H%1(24Y'H%=%
MH$1/H$5615)9H$Y)1TA4+*!P24Y+63J@)PT@='AT("=44EF@5$^@5$%+1:!/
M5D52H%1(1:!73U),1"$G#0T-*BTM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM
M+2TM+2T-*J!G14Y%4D%,H%%515-424].04),12U604Q51:!%4E)/4J!04D]#
M14154D4-#2IC:&]K9:!L9'B@(S P#2HZ;&]O<*!L9&&@.F-T97AT+'@-*J!B
M97&@.F1O;F4-*J!J<W*@8VAR;W5T#2J@:6YX#2J@:FUPH#IL;V]P#2HZ9&]N
M9:!R=',-*CIC=&5X=*!H97B@,&2@.V-R#2J@='ATH"=33TU%5$A)3D>@0TA/
M2T5$H#HH)PTJH&AE>* P9# P#2H-('1X=" G;D%21B$G#0TJ+2TM+2TM+2TM
M+2TM+2TM+2TM+2TM+2TM+2TM+2TM+0TJH&1205=)3B>@0:!,24Y%+J"@8:!&
M04A.H$Q!2$XN#0TJ*BJ@<T]-1:!54T5&54R@34%#4D]3#0UC:6YI="!M86,@
M(#MM04-23Z!43Z!)3DE424%,25I%H%1(1:!#3U5.5$52#2!L9&$@73$@.T18
MH$]2H$19#2!L<W(-(#P\/" @.W1(1:!$6"\RH$U!2T53H$&@3DE#15*@3$]/
M2TE.1Z!,24Y%#0TJ*BHJ*J!M04-23Z!43Z!404M%H$&@4U1%4*!)3J!X#0UX
M<W1E<"!M86,-(&QD>"!D>" [;E5-0D52H$]&H$Q/3U"@251%4D%424].4PT@
M/CX^(&-I;FET+&1X#7AL;V]P(&QS<B!C:'5N:PT@8F5Q(&9I>&,@.W501$%4
M1:!#3TQ534X-('-B8R!D>0T@8F-C(&9I>'D@.W1)346@5$^@4U1%4*!)3J!Y
M#2!D97@-(&)N92!X;&]O< UD;VYE(&QD82!O;&1X(#MP3$]4H%1(1:!,05-4
MH$-(54Y+#2!E;W(@8VAU;FL-(&]R82 H8G5F9F5R*2QY#2!S=&$@*&)U9F9E
M<BDL>0T@<G1S#0UF:7AC('!H80T@;&1A(&]L9'@-(&]R82 H8G5F9F5R*2QY
M(#MP3$]4#2!S=&$@*&)U9F9E<BDL>0T@;&1A(",D9F8@.W501$%41:!#2%5.
M2PT@<W1A(&]L9'@-('-T82!C:'5N:PT@;&1A(",D.# @.VE.0U)%05-%H%1(
M1:!#3TQ534X-(&5O<B!B=69F97(-('-T82!B=69F97(-(&)N92!C,@T@:6YC
M(&)U9F9E<BLQ#6,R#2!P;&$-('-B8R!D>0T@8F-S(&-O;G0-(&%D8R!D> T@
M:68@:2Q=,2 [9$^@5T6@55-%H&EN>:!/4J!D97D_#2!I;GD-(&5L<V4-(&1E
M>0T@9FEN#6-O;G0@9&5X#2!B;F4@>&QO;W -(&IM<"!D;VYE#0UF:7AY(&%D
M8R!D> T@<&AA#2!L9&$@;VQD> T@96]R(&-H=6YK#2!O<F$@*&)U9F9E<BDL
M>0T@<W1A("AB=69F97(I+'D-(&QD82!C:'5N:PT@<W1A(&]L9'@-('!L80T@
M:68@:2Q=,2 [=5!$051%H'D-(&EN>0T@96QS90T@9&5Y#2!F:6X-(&1E> T@
M8FYE('AL;V]P#2!R=',-(#P\/" @.V5.1*!/1J!M04-23Z!84U1%4 T-*BHJ
M*BJ@=$%+1:!!H%-415"@24Z@>0T->7-T97 @;6%C#2!L9'@@9'D@.VY534)%
M4J!/1J!,3T]0H$E415)!5$E/3E,-(&)E<2!D;VYE(#MI1J!$63TPH$E4)U.@
M2E535*!!H%!/24Y4#2 ^/CX@8VEN:70L9'D-('-E8PUY;&]O<"!P:&$-(&QD
M82!O;&1X#2!O<F$@*&)U9F9E<BDL>0T@<W1A("AB=69F97(I+'D-('!L80T@
M:68@:2Q=,0T@:6YY#2!E;'-E#2!D97D-(&9I;@T@<V)C(&1X#2!B8V,@9FEX
M> T@9&5X#2!B;F4@>6QO;W -9&]N92!L9&$@;VQD> T@;W)A("AB=69F97(I
M+'D-('-T82 H8G5F9F5R*2QY#2!R=',-#69I>'@@861C(&1Y#2!L<W(@;VQD
M> T@<V5C(" [:4U03U)404Y4(0T@8F5Q(&9I>&,-(&1E> T@8FYE('EL;V]P
M#2!J;7 @9&]N90T-9FEX8R!P:&$-(&QD82 C)#@P#2!S=&$@;VQD> T@96]R
M(&)U9F9E<@T@<W1A(&)U9F9E<@T@8FYE(&,R#2!I;F,@8G5F9F5R*S$-8S(@
M<&QA#2!D97@-(&)N92!Y;&]O< T@:FUP(&1O;F4-(#P\/" @.V5.1*!/1J!M
M04-23Z!94U1%4 T-*J!T04M%H$%.H%B@4U1%4*!)3J!42$6@96]RH$)51D9%
M4@TJH'1(1:!33TQ%H$-(04Y'1:!)4Z!43Z!54T6@96]RH$E.4U1%042@3T:@
M;W)A#0UE;W)X<W1E<"!M86,-(&QD>"!D>" [;E5-0D52H$]&H$Q/3U"@251%
M4D%424].4PT@/CX^(&-I;FET+&1X#7AL;V]P(&QS<B!C:'5N:PT@8F5Q(&9I
M>&,@.W501$%41:!#3TQ534X-('-B8R!D>0T@8F-C(&9I>'D@.W1)346@5$^@
M4U1%4*!)3J!Y#2!D97@-(&)N92!X;&]O< UD;VYE(&QD82!O;&1X(#MP3$]4
MH%1(1:!,05-4H$-(54Y+#2!E;W(@8VAU;FL-(&5O<B H8G5F9F5R*2QY#2!S
M=&$@*&)U9F9E<BDL>0T@<G1S#0UF:7AC('!H80T@;&1A(&]L9'@-(&5O<B H
M8G5F9F5R*2QY(#MP3$]4#2!S=&$@*&)U9F9E<BDL>0T@;&1A(",D9F8@.W50
M1$%41:!#2%5.2PT@<W1A(&]L9'@-('-T82!C:'5N:PT@;&1A(",D.# @.VE.
M0U)%05-%H%1(1:!#3TQ534X-(&5O<B!B=69F97(-('-T82!B=69F97(-(&)N
M92!C,@T@:6YC(&)U9F9E<BLQ#6,R#2!P;&$-('-B8R!D>0T@8F-S(&-O;G0-
M(&%D8R!D> T@:68@:2Q=,2 [9$^@5T6@55-%H&EN>:!/4J!D97D_#2!I;GD-
M(&5L<V4-(&1E>0T@9FEN#6-O;G0@9&5X#2!B;F4@>&QO;W -(&IM<"!D;VYE
M#0UF:7AY(&%D8R!D> T@<&AA#2!L9&$@;VQD> T@96]R(&-H=6YK#2!E;W(@
M*&)U9F9E<BDL>0T@<W1A("AB=69F97(I+'D-(&QD82!C:'5N:PT@<W1A(&]L
M9'@-('!L80T@:68@:2Q=,2 [=5!$051%H'D-(&EN>0T@96QS90T@9&5Y#2!F
M:6X-(&1E> T@8FYE('AL;V]P#2!R=',-(#P\/" @.V5.1*!/1J!M04-23Z!8
M4U1%4 T-#2J@=$%+1:!!H%DM4U1%4*!)3J!42$6@96]R+4)51D9%4@TJH&-(
M04Y'15.@1E)/3:!!0D]61:!!4D4ZH$].3%F@4$Q/5*!,05-4H%!!4E2@3T:@
M14%#2 TJH%9%4E1)0T%,H$-(54Y++*!$3TXG5*!03$]4H$Q!4U2@4$])3E0L
MH%!,3U2@5TE42*!E;W(-#65O<GES=&5P(&UA8PT@;&1X(&1Y(#MN54U"15*@
M3T:@3$]/4*!)5$52051)3TY3#2!B97$@9&]N92 [:4:@1%D],*!)5"=3H$I5
M4U2@0:!03TE.5 T@/CX^(&-I;FET+&1Y#2!S96,-*GEL;V]PH'!H80TJH&QD
M8:!O;&1X#2J@;W)AH"AB=69F97(I+'D-*J!S=&&@*&)U9F9E<BDL>0TJH'!L
M80UY;&]O<"!I9B!I+%TQ#2!I;GD-(&5L<V4-(&1E>0T@9FEN#2!S8F,@9'@-
M(&)C8R!F:7AX#2!D97@-(&)N92!Y;&]O< TJ9&]N9:!L9&&@;VQD> TJH&]R
M8: H8G5F9F5R*2QY#2J@<W1AH"AB=69F97(I+'D-9&]N92!R=',-#69I>'@@
M861C(&1Y#2!P:&$@(#MW1:!/3DQ9H%!,3U2@5$A%H$Q!4U2@4$%25*!/1J!%
M04-(H$-(54Y+#2!L9&$@;VQD> T@96]R("AB=69F97(I+'D-('-T82 H8G5F
M9F5R*2QY#2!P;&$-(&QS<B!O;&1X#2!S96,@(#MI35!/4E1!3E0A#2!B97$@
M9FEX8PT@9&5X#2!B;F4@>6QO;W -(&IM<"!D;VYE#0UF:7AC('!H80T@;&1A
M(",D.# -('-T82!O;&1X#2!E;W(@8G5F9F5R#2!S=&$@8G5F9F5R#2!B;F4@
M8S(-(&EN8R!B=69F97(K,0UC,B!P;&$-(&1E> T@8FYE('EL;V]P#2!J;7 @
M9&]N90T@/#P\(" [94Y$H$]&H&U!0U)/H%E35$50#2HJ*BJ@:4Y)5$E!3*!,
M24Y%H%-%5%50#0TJ*J!T2$6@0T]-345.5$5$H$Q)3D53H$)%3$]7H$%21:!.
M3U>@5$%+14Z@0T%21:!/1J!"6:!42$4-*BJ@0T%,3$E.1Z!23U5424Y%+@TJ
M9')A=Z ^/CZ@;6]V92QT>#$[>#&@H#MM3U9%H%-4549&H$E.5$^@6D523Z!0
M04=%#2J@/CX^H&UO=F4L='@R.W@RH* [=TA%4D6@252@0T%.H$)%H$U/1$E&
M245$#2J@/CX^H&UO=F4L='DQ.WDQ#2J@/CX^H&UO=F4L='DR.WDR#0UD<F%W
M(&QD82!F:6QL#2!B;F4@.G-E=&5O<@T@/CX^('-E=&)U9@T@:FUP(#IS971U
M< TZ<V5T96]R(&QD82 C/&5O<F)U9B [=5-%H&5O<J!"549&15*@24Y35$5!
M1*!/1@T@<W1A(&)U9F9E<B [1$E34$Q!6:!"549&15*@1D]2H$1205=)3D<-
M(&QD82 C/F5O<F)U9@T@<W1A(&)U9F9E<BLQ#0TZ<V5T=7 @<V5C(" [;4%+
M1:!355)%H%@Q/%@R#2!L9&$@>#(-('-B8R!X,0T@8F-S(#IC;VYT#2!L9&$@
M>3(@.VE&H$Y/5"R@4U=!4*!P,:!!3D2@<#(-(&QD>2!Y,0T@<W1A('DQ#2!S
M='D@>3(-(&QD82!X,0T@;&1Y('@R#2!S='D@>#$-('-T82!X,@T-('-E8PT@
M<V)C('@Q(#MN3U>@83U$6 TZ8V]N="!S=&$@9'@-(&QD>"!X,2 [<%54H%@Q
MH$E.5$^@>"R@3D]7H%=%H$-!3J!44D%32*!X,0T-8V]L=6UN('1X82 [9DE.
M1*!42$6@1DE24U2@0T],54U.H$9/4J!X#2!L<W(-(&QS<B @.W1(15)%H$%2
M1:!8,2\XH#$R.*!"651%H$),3T-+4PT@;'-R(" [=TA)0TB@345!3E.@6#$O
M,3:@,C4VH$)95$6@0DQ/0TM3#2!L<W(-(&)C8R Z979E;B [=TE42*!!H%!/
M4U-)0DQ%H$585%)!H#$R.*!"651%H$),3T-+#2!L9'D@(R0X," [24:@4T\L
MH%-%5*!42$6@2$E'2*!"250-('-T>2!B=69F97(-(&-L8PTZ979E;B!A9&,@
M8G5F9F5R*S$@.V%$1*!)3J!42$6@3E5-0D52H$]&H#(U-J!"651%H$),3T-+
M4PT@<W1A(&)U9F9E<BLQ#0T@<V5C#2!L9&$@>3(@.V-!3$-53$%41:!$60T@
M<V)C('DQ#2!B8W,@.F-O;G0R(#MI4Z!9,CY9,3\-(&5O<B C)&9F(#MO5$A%
M4E=)4T6@1%D]63$M63(-(&%D8R C)# Q#3IC;VYT,B!S=&$@9'D-(&-M<"!D
M>" [=TA/)U.@0DE'1T52.J!$6:!/4J!$6#\-(&)C8R!S=&5P:6YX(#MI1J!$
M6"R@5$A%3BXN+@T@:FUP('-T97!I;GD-#7-T97!I;G@@;&1Y('DQ#2!C<'D@
M>3(-(&QD82!B:71P+'@@.WB@0U524D5.5$Q9H$-/3E1!24Y3H%@Q#2!S=&$@
M;VQD> T@<W1A(&-H=6YK#2!B8V,@>&EN8WD@.V1/H%=%H%-415"@1D]25T%2
M1%.@3U*@0D%#2U=!4D13H$E.H'D_#2!J;7 @>&1E8WD-#7AI;F-Y(&QD82!F
M:6QL#2!B97$@;F]R;7AI;F,-(#X^/B!E;W)X<W1E<"QI;GD-;F]R;7AI;F,@
M/CX^('AS=&5P+&EN>0T->&1E8WD@;&1A(&9I;&P-(&)E<2!N;W)M>&1E8PT@
M/CX^(&5O<GAS=&5P+&1E>0UN;W)M>&1E8R ^/CX@>'-T97 L9&5Y#0US=&5P
M:6YY(&QD>2!Y,0T@;&1A(&)I=' L>" [>#U8,0T@<W1A(&]L9'@-(&QS<B @
M.WF@1$]%4TXG5*!54T6@0TA53DM3#2!E;W(@;VQD>" [<T^@5T6@2E535*!7
M04Y4H%1(1:!"250-('-T82!O;&1X#2!C<'D@>3(-(&)C<R!Y9&5C>0T->6EN
M8WD@;&1A(&9I;&P-(&)E<2!N;W)M:6YC#2 ^/CX@96]R>7-T97 L:6YY#6YO
M<FUI;F,@/CX^('ES=&5P+&EN>0T->61E8WD@;&1A(&9I;&P-(&)E<2!N;W)M
M9&5C#2 ^/CX@96]R>7-T97 L9&5Y#6YO<FUD96,@/CX^('ES=&5P+&1E>0T-
M#2HM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM#2J@8TQ%04Z@55 -
M#6-L96%N=7 @;&1A('9M8W-B(#MS5TE40TB@0TA!4J!23TV@0D%#2Z!)3@T@
M86YD(",E,3$Q,3 Q,#$@.T1%1D%53%0-('-T82!V;6-S8@T-(')T<R @.T)9
M12$-#2!T>'0@)U-024Y!3*!#4D%#2T52H"<-('1X=" G4TQ*H#8O.34G#0TJ
M+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+0TJH'-%5*!54*!"252@
M5$%"3$4-#2!D<R!>(#MC3$5!4J!43Z!%3D2@3T:@4$%'10T@(" [<T^@5$A!
M5*!404),15.@4U1!4E2@3TZ@0:!004=%H$)/54Y$05)9#6)I=' @;'5P(#$V
M(#LQ,CB@94Y44DE%4Z!&3U*@> T@9&9B("4Q,3$Q,3$Q,0T@9&9B("4P,3$Q
M,3$Q,0T@9&9B("4P,#$Q,3$Q,0T@9&9B("4P,# Q,3$Q,0T@9&9B("4P,# P
M,3$Q,0T@9&9B("4P,# P,#$Q,0T@9&9B("4P,# P,# Q,0T@9&9B("4P,# P
M,# P,0T@+2U>#0US:6X@.W1!0DQ%H$]&H%-)3D53+* Q,C"@0EE415,-8V]S
M(&5Q=2!S:6XK,3(X(#MT04),1:!/1J!#3U-)3D53#2 @(#MB3U1(H$]&H%1(
M15-%H%1224>@5$%"3$53H$%210T@(" [0U524D5.5$Q9H%-%5*!54*!&4D]-
MH&)A<VEC#7ID:78@97%U(&-O<RLQ,C@@.V1)5DE324].H%1!0DQ%#71M871H
M,2!E<74@>F1I=BLS.#0@.VU!5$B@5$%"3$6@3T:@1BA8*3U8*E@O,C4V#71M
M871H,B!E<74@=&UA=&@Q*S4Q,B [<T5#3TY$H$U!5$B@5$%"3$4-<&]L>6QI
M<W0@97%U('1M871H,BLU,3(@.VQ)4U2@3T:@4$],64=/3E,-&AH:&AH:&AH:
8&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:
end
begin 666 cube3d3.2.o
M ("I (T@T(TAT*T8T"D/"1"-&-"@ *D?A?NI@(7\3+R!DP41$1$@(" @(" @
M(" @(" @0U5"13-$(%8S+C(-#2 @(" @(" @(" @(" @(" @($)9#9\@(" @
M4U1%4$A%3B!*541$F2 @("!'14]21T4@5$%93$]2#0V;("!#2$5#2R!/550@
M5$A%($I!3BX@.34@25-3544@3T8-EB @0SU(04-+24Y'FR!&3U(@34]212!$
M151!24Q3(0T-'1V>$D8Q+T8RDB M($E.0R]$14,@6"U23U1!5$E/3@T='1)&
M,R]&-)(@+2!)3D,O1$5#(%DM4D]4051)3TX-'1T21C4O1C:2("T@24Y#+T1%
M0R!:+5)/5$%424].#1T=$B!&-R @DB M(%)%4T54#1T=$B K+RT@DB M(%I/
M3TT@24XO3U54#1T=$B @2" @DB M(%1/1T=,12!(241$14X@4U521D%#15,-
M'1T24U!!0T62("T@5$]'1TQ%(%-54D9!0T4@1DE,3$E.1PT-("!04D534R!1
M(%1/(%%5250-#04@(" @("!04D534R!!3ED@2T59(%1/($)%1TE.#0"Q^_ +
M(-+_R-#VYOQ,O($@Y/_) /#YJ9*%(X4EJ92%)X4IJ0&-(="IDR#2_ZD C2'0
MJ4!I#(7[J06%_*D H "B !B1^\AI$)#Y&*7[:2B%^Z7\:0"%_* Z(K@$-#D
MJ0"%HZDPA:2@ *(8J0"1H\C0^^:DRM#VJ0"%HZDPA:2% JT8T"GQ"0Z-&-"I
M (57A5B%685@A3^%085 A4*%885BA6.%9(5EA6:%4*D!A;6I0(5Q6"#D_\F%
MT NE8<D\\%'F84P-@\F)T FE8?!$QF%,#8/)AM +I6+)// UYF),#8/)BM )
MI6+P*,9B3 V#R8?0"Z5CR3SP&>9C3 V#R8O0":5C\ S&8TP-@\F(T 9,1H),
M#8/)*] 'YG'F<4P-@\DMT W&<<9Q$"CF<>9Q3 V#R4C0":6U20&%M4P-@\D@
MT FE4$D!A5!,#8/)4= #3)F.>!BE9&5AR7B0 NEXA608I65E8LEXD +I>(5E
M&*5F96/)>) "Z7B%9CBE9>5FL )I>(5G&*5E96;)>) "Z7B%:!BE9&5FR7B0
M NEXA6DXI63E9K ":7B%:ABE9&5HR7B0 NEXA6LXI63E9[ ":7B%;!BE9&5G
MR7B0 NEXA6TXI6CE9+ ":7B%;CBE9>5DL )I>(5O&*5D967)>) "Z7B%<!BF
M9[T D*9H?0"0A:6F9[V CSBF:/V CX6FIF6]@(\0#AA)_VD!"AA)_VD!3-V#
M"H6G.*9NO0"0IFW] ) XIFO] ) 8IFQ] ) 0#AA)_VD!2AA)_VD!3 >$2ABF
M:7V CSBF:OV CX6H.*9KO8"/IFS]@(\XIFW]@(\XIF[]@(\0#AA)_VD!2AA)
M_VD!3#V$2ABF:7T D!BF:GT D(6IIF^]@(\XIG#]@(^%JJ9LO8"/.*9N_8"/
M.*9M_8"/.*9K_8"/$ X82?]I 4H82?]I 4R A$H8IFI] ) XIFG] )"%JQBF
M;+T D*9M?0"0.*9K_0"0.*9N_0"0$ X82?]I 4H82?]I 4RVA$H8IFE]@(\8
MIFI]@(^%K!BF;[T D*9P?0"0A:VI (6CI0*%I*((J0"@ )&CR-#[YJ3*T/2@
M (11I%&Y );0 TR*A852YE$@Q86E5TI*2H57Q3^P H4_I5G%0; "A4&E6$I*
M2H58Q4"0 H5 I6#%0I "A4*E4/#!J0"%HZ4"A:2I (7[J4"%_*572I 'H("$
MHX3[&(5H9:2%I*5H9?R%_*58..57JNBD8- "YF"D8*D 4?M(4:.1HZD D?MH
MB,19L.^EHTF A:.%^] $YJ3F_,K0VDSMA*T8T$D"C1C0J0A% H4"3&Z"9T5%
M(&)204E.+"!72$%4($1/(%E/52!704Y4(%1/($1/(%1/3DE'2%0_J0"%8(58
MJ?^%6857I%&Y ):%DLBY ):%D\BY ):%E,C&4KD EH65R+D EH66R+D EH6N
MR,92N0"6A:_(N0"6A;#(N0"6A;'(A%&DDJ6EA2882?]I 84HL28X\2B%LJ6H
MA2882?]I 84HL28X\2B%LZ6KA2882?]I 84HL28X\2B%M*23I::%)AA)_VD!
MA2BQ)CCQ*!AELH6RI:F%)AA)_VD!A2BQ)CCQ*!AELX6SI:R%)AA)_VD!A2BQ
M)CCQ*!AEM(6TI)2EIX4F&$G_:0&%*+$F./$H&&6RA;*EJH4F&$G_:0&%*+$F
M./$H&&6SA;.EK84F&$G_:0&%*+$F./$H&&6TA92JO("0I;*%(AA)_VD!A22Q
M(CCQ)*9QX$#P%(3[I'&%)AA)_VD!A2BQ)CCQ**3[&&E A9+%5[ "A5?%6) "
MA5BELX4B&$G_:0&%)+$B./$DX$#P$*1QA2882?]I 84HL28X\2@8:4"%D\59
ML *%6<5@D *%8*25I:6%)AA)_VD!A2BQ)CCQ*(6RI:B%)AA)_VD!A2BQ)CCQ
M*(6SI:N%)AA)_VD!A2BQ)CCQ*(6TI):EIH4F&$G_:0&%*+$F./$H&&6RA;*E
MJ84F&$G_:0&%*+$F./$H&&6SA;.EK(4F&$G_:0&%*+$F./$H&&6TA;2DKJ6G
MA2882?]I 84HL28X\2@89;*%LJ6JA2882?]I 84HL28X\2@89;.%LZ6MA288
M2?]I 84HL28X\2@89;2%KJJ\@)"ELH4B&$G_:0&%)+$B./$DIG'@0/ 4A/ND
M<84F&$G_:0&%*+$F./$HI/L8:4"%E<57L *%5\58D *%6*6SA2(82?]I 84D
ML2(X\23@0/ 0I'&%)AA)_VD!A2BQ)CCQ*!AI0(66Q5FP H59Q6"0 H5@I*^E
MI84F&$G_:0&%*+$F./$HA;*EJ(4F&$G_:0&%*+$F./$HA;.EJX4F&$G_:0&%
M*+$F./$HA;2DL*6FA2882?]I 84HL28X\2@89;*%LJ6IA2882?]I 84HL28X
M\2@89;.%LZ6LA2882?]I 84HL28X\2@89;2%M*2QI:>%)AA)_VD!A2BQ)CCQ
M*!AELH6RI:J%)AA)_VD!A2BQ)CCQ*!AELX6SI:V%)AA)_VD!A2BQ)CCQ*!AE
MM(6QJKR D*6RA2(82?]I 84DL2(X\22F<>! \!2$^Z1QA2882?]I 84HL28X
M\2BD^QAI0(6OQ5>P H57Q5B0 H58I;.%(AA)_VD!A22Q(CCQ).! \!"D<84F
M&$G_:0&%*+$F./$H&&E A;#%6; "A5G%8) "A6"EM?!'I94XY9*HI; XY9:%
M)AA)_VD!A2BQ)CCQ*(7[I:\XY96HI98XY9.%)AA)_VD!A2BQ)CCQ*,7[, _&
M4O *YE'F4>91QE+0]F"EDH7[I9.%_*65A?VEEH7^(-"+I96%^Z66A?REKX7]
MI;"%_B#0B\92T -,=XND4;D EH65R+D EH66R+D EH6NR(11I)6EI84F&$G_
M:0&%*+$F./$HA;*EJ(4F&$G_:0&%*+$F./$HA;.EJX4F&$G_:0&%*+$F./$H
MA;2DEJ6FA2882?]I 84HL28X\2@89;*%LJ6IA2882?]I 84HL28X\2@89;.%
MLZ6LA2882?]I 84HL28X\2@89;2%M*2NI:>%)AA)_VD!A2BQ)CCQ*!AELH6R
MI:J%)AA)_VD!A2BQ)CCQ*!AELX6SI:V%)AA)_VD!A2BQ)CCQ*!AEM(6NJKR
MD*6RA2(82?]I 84DL2(X\22F<>! \!2$^Z1QA2882?]I 84HL28X\2BD^QAI
M0(65Q5>P H57Q5B0 H58I;.%(AA)_VD!A22Q(CCQ).! \!"D<84F&$G_:0&%
M*+$F./$H&&E A9;%6; "A5G%8) "A6"EE87[I9:%_*6OA?VEL(7^(-"+I96%
MKZ66A;#&4O #3!&*I9*%_:63A?ZEKX7[I;"%_"#0BV!S04U%(%1(24Y'(%=%
M($1/($5615)9($Y)1TA4+"!P24Y+63H@5%)9(%1/(%1!2T4@3U9%4B!42$4@
M5T]23$0A;D%21B&E4- +J0"%HZ4"A:1,YXNI (6CJ4"%I#BE_>7[L!.E_J3\
MA?R$_J7[I/V$^X7]..7[A6>F^XI*2DI*D 6@@(2C&&6DA:0XI?[E_+ $2?]I
M 85HQ6>0 TR-C:3\Q/Z] (^%_87^D -,XXRE4/!3IF>E9TI&_O 0Y6B0,<K0
M]:7]1?Y1HY&C8$BE_5&CD:.I_X7]A?ZI@$6CA:/0 N:D:.5HL -E9\C*T,I,
M38QE9TBE_47^4:.1HZ7^A?UHR,K0LV"F9Z5G2D;^\!#E:) QRM#UI?U%_A&C
MD:-@2*7]$:.1HZG_A?V%_JF 1:.%H] "YJ1HY6BP V5GR,K0RDR@C&5G2*7]
M1?X1HY&CI?Z%_6C(RM"S8*50\%.F9Z5G2D;^\!#E:) QRM#UI?U%_E&CD:-@
M2*7]4:.1HZG_A?V%_JF 1:.%H] "YJ1HY6BP V5GB,K0RDSWC&5G2*7]1?Y1
MHY&CI?Z%_6B(RM"S8*9GI6=*1O[P$.5HD#'*T/6E_47^$:.1HV!(I?T1HY&C
MJ?^%_87^J8!%HX6CT +FI&CE:+ #96>(RM#*3$J-96=(I?U%_A&CD:.E_H7]
M:(C*T+-@I/R] (^%_4I%_87]Q/ZP?J50\#JF:/ ,I6A*.,CE9Y $RM#X8&5H
M2*7]4:.1HVA&_3CP!LK0Y4RQC4BI@(7]1:.%H] "YJ1HRM#13+&-IFCP%*5H
M2CA(I?T1HY&C:,CE9Y *RM#PI?T1HY&C8&5H1OTX\ ;*T-],\XU(J8"%_46C
MA:/0 N:D:,K0RTSSC:50\#JF:/ ,I6A*.(CE9Y $RM#X8&5H2*7]4:.1HVA&
M_3CP!LK0Y4POCDBI@(7]1:.%H] "YJ1HRM#13"^.IFCP%*5H2CA(I?T1HY&C
M:(CE9Y *RM#PI?T1HY&C8&5H1OTX\ ;*T-],<8Y(J8"%_46CA:/0 N:D:,K0
MRTQQCJT8T"GUC1C08%-024Y!3"!#4D%#2T52(%-,2B V+SDU
M
M #_?S\?#P<# ?]_/Q\/!P,!_W\_'P\' P'_?S\?
M#P<# ?]_/Q\/!P,!_W\_'P\' P'_?S\?#P<# ?]_/Q\/!P,!_W\_'P\' P'_
M?S\?#P<# ?]_/Q\/!P,!_W\_'P\' P'_?S\?#P<# ?]_/Q\/!P,!_W\_'P\'
M P'_?S\?#P<# 1H:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:
M&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:
M&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:
!&AH:
end
begin 666 shape3.2
M 1PA' CR!#54)%,T0@4TA!4$4@24Y)5"!04D]'4D%- $<<!0"7-3$L,C4U
M.I<U,BPQ,C<ZES4U+#(U-3J7-38L,3(W.IP ;AQB (\@34%)3B!04D]'4D%-
M(%-405)44R!!5"!,24Y%(#4P,# =!QC #H B!QD (\@4%)/1U)!32!.3U1%
M4P":'&X CR!33$H@-B\Q-B\Y-0"P''@ CR!$051!($9/4DU!5"!)4SH UAQ]
M (\@3E5-4$])3E13+%@Q+%DQ+%HQ+%@R+%DR+%HR+"XN+@#W'(( CR!42$4@
M4$],64=/3B!,25-4("I-55-4*B!"10 5'8< CR!415)-24Y!5$5$(%=)5$@@
M02!:15)/(0 ;'8D .@ ^'8P CR!/1B!#3U524T4L(%1(15)%($E3($$@3$]4
M($]& %X=D0"/($154$Q)0T%424].($1205=)3D<@3$E.15, @QV3 (\@5TA%
M3B!&04-%4R!!4D5.)U0@0D5)3D<@1DE,3$5$ *8=E@"/($$@1D%35"!04D]'
M4D%-(%=/54Q$3B=4($1205< RAV@ (\@5$A%(%-!344@3$E.12!45TE#12P@
M0E54(%1(25, Z!VE (\@25,@1T]/1"!%3D]51T@@1D]2($Y/5R$ "AZG (\@
M3T8@0T]54E-%+"!&3U(@1DE,3$5$($9!0T53 "L>J "/(%1(25,@25,@3D\@
M3$].1T52($%.($E34U5% #$>J@ Z %8>M "/($9%14P@1E)%12!43R!0550@
M64]54B!/5TX@1$%400!\'KD CR!)3BP@0E54($-(04Y'12!42$4@4$]+12!)
M3B!,24Y% )@>O@"/(#4P,#4@5$\@55-%($,Q($%.1"!#,@">'L@ .@##'M(
MCR!33U)262!!0D]55"!33TU%($]&(%1(12!,25143$4 WA[7 (\@0E5'4RP@
M15(N+BX@1D5!5%5215, _A[< (\@5$A)4R!705,@02!214%,(%)54T@@2D]"
M+@ $'^8 .@ G'_ CR!!3D0@248@64]5($9%14P@4T\@24Y#3$E.140L $0?
M^@"/(%=2251%(%1/(%-*541$0$Y752Y%1%4 2A\$ 3H :1\. 8\@04Y$($%"
M3U9%($%,3"P@2$%612!&54XA &\?& $Z ($?Y@./($9)4E-4(%-(05!% )<?
MYP-!,;+"*#8Q*3I!,K+"*#8R*0#''^@#@R T+"TR-BPM,C8L-C0L,C8L+3(V
M+#8T+#(V+#8T+#8T+"TR-BPV-"PV- #S'_(#@R T+"TR-BPM,C8L,"PR-BPM
M,C8L,"PR-BPV-"PP+"TR-BPV-"PP !<@_ .#(#,L,"PM,C8L,S(L,38L,S(L
M,S(L+3$V+#,R+#,R !\@!@2#(# ,B!*!(\@4T5#3TY$(%-(05!% $@@2P1"
M,;+"*#8Q*3I",K+"*#8R*0!\($P$@R T+"TQ-2PS,"PM,3(L+3$U+"TS,"PM
M,3(L+34W+"TS,"PM,RPM-3$L+38L+3, K"!6!(,@-"PQ-2PS,"PM,3(L-3$L
M+38L+3,L-3<L+3,P+"TS+#$U+"TS,"PM,3( X"!@!(,@-"PQ-2PS,"PM,3(L
M,34L+3,P+"TQ,BPM,34L+3,P+"TQ,BPM,34L,S L+3$R "0A:@2#(#<L,34L
M+3,P+"TQ,BPU-RPM,S L+3,L,S,L+3,P+#8L,"PM,S L,3(L+3,S+"TS,"PV
M+"TU-RPM,S L+3, -B%L!(,@+3$U+"TS,"PM,3( 6R%T!(,@,RPS,RPM,S L
M,"PS,RPM,S L+30L,SDL+3,P+"TR (,A?@2#(#,L+3,S+"TS,"PP+"TS.2PM
M,S L+3(L+3,S+"TS,"PM- "O(8@$@R T+#8L+3,P+#,L-BPM,S L+38L,3@L
M+3,P+"TT+#$X+"TS,"PQ -\AD@2#(#0L+38L+3,P+#,L+3$X+"TS,"PQ+"TQ
M."PM,S L+30L+38L+3,P+"TV <BG 2#(#,L+34W+"TS,"PM,RPM,S,L+3,P
M+#8L+34Q+"TQ,BPM,P O(J8$@R S+"TS,RPM,S L-BPM,34L,S L+3$R+"TU
M,2PM,3(L+3, 4R*P!(,@,RPM,34L,S L+3$R+"TS,RPM,S L-BPP+#8L,3(
M=2*Z!(,@,RPP+#8L,3(L+3,S+"TS,"PV+# L+3,P+#$R )DBQ 2#(#,L,34L
M,S L+3$R+"TQ-2PS,"PM,3(L,"PV+#$R +HBS@2#(#,L,"PM,S L,3(L,S,L
M+3,P+#8L,"PV+#$R -PBV 2#(#,L,"PV+#$R+#,S+"TS,"PV+#$U+#,P+"TQ
M,@ !(^($@R S+#$U+#,P+"TQ,BPS,RPM,S L-BPU,2PM,3(L+3, )B/L!(,@
M,RPS,RPM,S L-BPU-RPM,S L+3,L-3$L+3$R+"TS "XC]@2#(# 0",2!8\@
M5$A)4D0@4TA!4$4 5B,3!4,QLL(H-C$I.D,RLL(H-C(I ' C% 6/(%E/55(@
M1$%402!'3T53($A%4D4 >"/0!X,@, ",(X@30E"R,C4VK"@YK#$VJC8I + C
MC!./($-(04Y'12!"14Q/5R!43R!03TE.5"!43R!$051! ,(CC1.7-C4L0C$Z
MES8V+$(R .$CDA.'3CJ70E L3CI"4+)"4*HQ.HM.LC"G-3 U, #I(Y<3F2!.
M 8DG!.!2;(QI#.L3CJ'4#J+4+,PIU"R,C4VJE &"2F$Y="4"Q0.D)0LD)0
MJC$ (B2K$YDB+B([ "XDL!.".HDU,#$P #\DNA.>,S(W-C@ZG#J,.H :
M&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:
0&AH:&AH:&AH:&AH:&AH:&AH:
end
begin 666 tables$8f80-$95ff
M@(\ @,%!P@*"PT/$!$3%!47&!D:&QP='1X>'Q\@(" @(" @'Q\>'AT='!L:
M&1@7%103$1 /#0L*" <% P( _OW[^?CV]?/Q\._M[.OIZ.?FY>3CX^+BX>'@
MX.#@X.#@X>'BXN/CY.7FY^CIZ^SM[_#Q\_7V^/G[_?X _P #_\" @(" ?
M'QX>'1T<&QH9&!<5%!,1$ \-"PH(!P4# @#^_?OY^/;U\_'P[^WLZ^GHY^;E
MY./CXN+AX>#@X.#@X.#AX>+BX^/DY>;GZ.GK[.WO\/'S]?;X^?O]_@ " P4'
M" H+#0\0$1,4%1<8&1H;'!T='AX?'R @(" _____P (B(B(B(C(R,C(R,C
M(R,D)"0D)"0D)"4E)24E)24E)B8F)B8F)B8G)R<G)R<G*"@H*"@H*"DI*2DI
M*2HJ*BHJ*BLK*RLK*RPL+"PL+"TM+2TM+BXN+BXN+R\O+S P,# P,3$Q,3$R
M,C(R,S,S,S0T-#0U-34U-C8V-C<W-S@X.#@8&!@8&1D9&1D9&1D9&1D9&1D9
M&1D9&AH:&AH:&AH:&AH:&AH:&AL;&QL;&QL;&QL;&QL;&QP<'!P<'!P<'!P<
M'!P<'1T='1T='1T='1T='1X>'AX>'AX>'AX>'A\?'Q\?'Q\?'Q\?(" @(" @
M(" @(" A(2$A(2$A(2$A(B(B(O__ /____\ \ _P#__P #_____
M /____\ _____P #_ /__ /_P__\ _____P #_
M____ /____\ _____P #_____ /____\ _____P
M #_____ /_P 0$! 0$! 0$" @(" @(# P,#! 0$
M! 4%!04&!@8'!P<(" @)"0D*"@L+"PP,#0T.#@\/$! 1$1(2$Q,4%!45%A<7
M&!@9&AH;'!P='AX?(" A(B,C)"4F)B<H*2DJ*RPM+BXO,#$R,S0U-38W.#DZ
M.SP]/C] 04)#1$5&1TA)2DM-3D]045)35%976"LJ*2DH)R8F)20C(R(A(" ?
M'AX='!P;&AH9&!@7%Q85%104$Q,2$A$1$! /#PX.#0T,# L+"PH*"0D)" @(
M!P<'!@8&!04%!00$! 0# P,# @(" @(" 0$! 0$! 0$
M $! 0$! 0$! @(" @(" P,# P0$! 0%!04%!@8&!P<'" @(
M"0D)"@H+"PL,# T-#@X/#Q 0$1$2$A,3%!05%187%Q@8&1H:&QP<'1X>'R @
M(2(C(R0E)B8G*"DI*BLL+2XN+S Q,C,T-34V-S@Y.CL\/3X_0$%"0T1%1D=(
M24I+34Y/4%%24U165U@K*BDI*"<F)B4D(R,B(2 @'QX>'1P<&QH:&1@8%Q<6
M%144%!,3$A(1$1 0#P\.#@T-# P+"PL*"@D)"0@(" <'!P8&!@4%!04$! 0$
M P,# P(" @(" @$! 0$! 0$! ! 0$!
M 0$! 0(" @(" @,# P,$! 0$!04%!08&!@<'!P@(" D)"0H*"PL+# P-#0X.
M#P\0$!$1$A(3$Q04%146%Q<8&!D:&AL<'!T>'A\@("$B(R,D)28F)R@I*2HK
M+"TN+B\P,3(S-#4U-C<X.3H[/#T^/T _/CT\.SHY.#<V-34T,S(Q,"\N+BTL
M*RHI*2@G)B8E)",C(B$@(!\>'AT<'!L:&AD8&!<7%A45%!03$Q(2$1$0$ \/
M#@X-#0P,"PL+"@H)"0D(" @'!P<&!@8%!04%! 0$! ,# P," @(" @(! 0$!
M 0$! 0 0$! 0$! 0$" @(" @(# P,#
M! 0$! 4%!04&!@8'!P<(" @)"0D*"@L+"PP,#0T.#@\/$! 1$1(2$Q,4%!45
M%A<7&!@9&AH;'!P='AX?(" A(B,C)"4F)B<H*2DJ*RPM+BXO,#$R,S0U-38W
M.#DZ.SP]/C] /SX]/#LZ.3@W-C4U-#,R,3 O+BXM+"LJ*2DH)R8F)20C(R(A
M(" ?'AX='!P;&AH9&!@7%Q85%104$Q,2$A$1$! /#PX.#0T,# L+"PH*"0D)
M" @(!P<'!@8&!04%!00$! 0# P,# @(" @(" 0$! 0$! 0$
M !H:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:
M&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:
E&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:&AH:
end
********************************
*``````````````````````````````*
*`Stephen`Judd`````````````````*
*`George`Taylor````````````````*
*`Started:`7/11/94`````````````*
*`Finished:`7/19/94````````````*
*`v2.0`Completed:`12/17/94`````*
*`v3.0`Completed:`3/20/95``````*
*`v3.1`Completed:`6/14/95``````*
*`v3.2`Completed:`6/15/95``````*
*``````````````````````````````*
*`Well,`if`all`goes`well`this``*
*`program`will`rotate`a`cube.``*
*``````````````````````````````*
*`v2.0`+`New`and`Improved!`````*
*`Now`with`faster`routines,````*
*`hidden`surfaces,`filled``````*
*`faces,`and`extra`top`secret``*
*`text`messages!```````````````*
*``````````````````````````````*
*`v3.0`+`Fast`chunky`line``````*
*`routine.`````````````````````*
*``````````````````````````````*
*`v3.1`+`General`polygon`plot``*
*`with`hidden`faces`(X-product)*
*`and`zoom`feature.````````````*
*``````````````````````````````*
*`v3.2`+`EOR-buffer`filling````*
*``````````````````````````````*
*`This`program`is`intended`to``*
*`accompany`the`article`in`````*
*`C=Hacking,`Jun.`95`issue.````*
*`For`details`on`this`program,`*
*`read`the`article!````````````*
*``````````````````````````````*
*`Write`to`us!`````````````````*
*``````````````````````````````*
*`Myself`when`young`did````````*
*`eagerly`frequent`````````````*
*`Doctor`and`Saint,`and`heard``*
*`great`Argument```````````````*
*``About`it`and`about:`but`````*
*``evermore````````````````````*
*`Came`out`by`the`same`Door````*
*`as`in`I`went.````````````````*
*````-`Rubaiyat````````````````*
*``````````````````````````````*
*`Though`I`speak`with`the``````*
*`tongues`of`men`and`of`angles`*
*`and`have`not`love,`I`am``````*
*`become`as`sounding`brass,`or`*
*`a`tinkling`cymbal.```````````*
*````-`1`Corinthians`13````````*
*``````````````````````````````*
*`P.S.`This`was`written`using``*
*``````Merlin`128.`````````````*
********************************
ORG $8000
*`Constants
BUFF1 EQU $3000 ;First`character`set
BUFF2 EQU $3800 ;Second`character`set
EORBUF EQU $4000 ;EOR-buffer
BUFFER EQU $A3 ;Presumably`the`tape`won't`be`running
X1 EQU $FB ;Points`for`drawing`a`line
Y1 EQU $FC ;These`zero`page`addresses
X2 EQU $FD ;don't`conflict`with`BASIC
Y2 EQU $FE
OLDX EQU $FD
CHUNK EQU $FE
DX EQU $67 ;This`is`shared`with`T1`below
DY EQU $68
TEMP1 EQU $FB ;Of`course,`could`conflict`with`x1
TEMP2 EQU $FC ;Temporary`variables
ZTEMP EQU $02 ;Used`for`buffer`swap.``Don't`touch.
Z1 EQU $22 ;Used`by`math`routine
Z2 EQU $24 ;Don't`touch`these`either!
Z3 EQU $26
Z4 EQU $28
K EQU $B6 ;Constant`used`for`hidden
;surface`detection`-`don't`touch
HIDE EQU $B5 ;Are`surfaces`hidden?
FILL EQU $50 ;Are`we`using`EOR-fill?
ANGMAX EQU 120 ;There`are`2*pi/angmax`angles
*`VIC
VMCSB EQU $D018
BKGND EQU $D020
BORDER EQU $D021
SSTART EQU 1344 ;row`9`in`screen`memory`at`1024
*`Kernal
CHROUT EQU $FFD2
GETIN EQU $FFE4
*`Some`variables
GLOBXMIN = $3F ;These`are`used`in`clearing`the
GLOBXMAX = $40 ;drawing`(global)`buffer
GLOBYMIN = $41
GLOBYMAX = $42
LOCXMIN = $57 ;These`are`used`in`clearing`the
LOCXMAX = $58 ;EOR`(local)`buffer
LOCYMIN = $59
LOCYMAX = $60
P1X = $92 ;These`are`temporary`storage
P1Y = $93 ;Used`in`plotting`the`projection
P1Z = $94
P2X = $95 ;They`are`here`so`that`we
P2Y = $96 ;don't`have`to`recalculate`them.
P2Z = $AE
P3X = $AF ;They`make`life`easy.
P3Y = $B0
P3Z = $B1 ;Why`are`you`looking`at`me`like`that?
P1T = $B2 ;Don't`you`trust`me?
P2T = $B3
P3T = $B4 ;Having`another`child`wasn't`my`idea.
INDEX = $51
COUNTPTS = $52
ZOOM = $71 ;Zoom`factor
DSX = $61 ;DSX`is`the`increment`for
;rotating`around`x
DSY = $62 ;Similar`for`DSY,`DSZ
DSZ = $63
SX = $64 ;These`are`the`actual`angles`in`x`y`and`z
SY = $65
SZ = $66
T1 = $67 ;These`are`used`in`the`rotation
T2 = $68
T3 = $69 ;See`the`article`for`more`details
T4 = $6A
T5 = $6B
T6 = $6C
T7 = $6D
T8 = $6E
T9 = $6F
T10 = $70
A11 = $A5 ;These`are`the`elements`of`the`rotation`matrix
B12 = $A6 ;XYZ
C13 = $A7
D21 = $A8 ;The`number`denotes`(row,column)
E22 = $A9
F23 = $AA
G31 = $AB
H32 = $AC
I33 = $AD
***`Macros
MOVE MAC
LDA ]1
STA ]2
<<<
GETKEY MAC ;Wait`for`a`keypress
WAIT JSR GETIN
CMP #00
BEQ WAIT
<<<
DEBUG MAC ;Print`a`character
DO`0``;Don't`assemble
LDA`#]1
JSR`CHROUT
CLI
>>> GETKEY ;And`wait`to`continue
CMP #'s' ;My`secrect`switch`key
BNE L1
JSR CLEANUP
JMP DONE
L1 CMP #'x' ;My`secret`abort`key
BNE DONE
JMP CLEANUP
FIN
DONE <<<
DEBUGA MAC
DO`0
LDA ]1
STA 1024
FIN
DONEA <<<
*-------------------------------
LDA #$00
STA BKGND
STA BORDER
LDA VMCSB
AND #%00001111 ;Screen`memory`to`1024
ORA #%00010000
STA VMCSB
LDY #00
LDA #<TTEXT
STA TEMP1
LDA #>TTEXT
STA TEMP2
JMP TITLE
TTEXT HEX 9305111111 ;clear`screen,`white,`crsr`dn
TXT '`````````````cube3d`v3.2',0d,0d
TXT '``````````````````by',0d
HEX 9F ;cyan
TXT '````stephen`judd'
HEX 99
TXT '````george`taylor',0d,0d
HEX 9B
TXT '``check`out`the`jan.`95`issue`of',0d
HEX 96
TXT '``c=hacking'
HEX 9B
TXT '`for`more`details!',0d
HEX 0D1D1D9E12
TXT 'f1/f2',92
TXT '`-`inc/dec`x-rotation',0d
HEX 1D1D12
TXT 'f3/f4',92
TXT '`-`inc/dec`y-rotation',0d
HEX 1D1D12
TXT 'f5/f6',92
TXT '`-`inc/dec`z-rotation',0d
HEX 1D1D12
TXT '`f7``',92
TXT '`-`reset',0d
HEX 1D1D12
TXT '`+/-`',92
TXT '`-`zoom`in/out',0d
HEX 1D1D12
TXT '``h``',92
TXT '`-`toggle`hidden`surfaces',0d
HEX 1D1D12
TXT 'space',92
TXT '`-`toggle`surface`filling',0d,0d
TXT '``press`q`to`quit',0d
HEX 0D05
TXT '``````press`any`key`to`begin',0d
HEX 00
TITLE LDA (TEMP1),Y
BEQ :CONT
JSR CHROUT
INY
BNE TITLE
INC TEMP2
JMP TITLE
:CONT >>> GETKEY
****`Set`up`tables(?)
*`Tables`are`currently`set`up`in`BASIC
*`and`by`the`assembler.
TABLES LDA #>TMATH1
STA Z1+1
STA Z2+1
LDA #>TMATH2
STA Z3+1
STA Z4+1
****`Clear`screen`and`set`up`"bitmap"
SETUP LDA #$01 ;White
STA $D021 ;This`is`done`so`that`older
LDA #147 ;machines`will`set`up
JSR CHROUT
LDA #$00 ;correctly
STA $D021
LDA #<SSTART
ADC #12 ;The`goal`is`to`center`the`graphics
STA TEMP1 ;Column`12
LDA #>SSTART ;Row`9
STA TEMP1+1 ;SSTART`points`to`row`9
LDA #00
LDY #00
LDX #00 ;x`will`count`16`rows`for`us
CLC
:LOOP STA (TEMP1),Y
INY
ADC #16
BCC :LOOP
CLC
LDA TEMP1
ADC #40 ;Need`to`add`40`to`the`base`pointer
STA TEMP1 ;To`jump`to`the`next`row
LDA TEMP1+1
ADC #00 ;Take`care`of`carries
STA TEMP1+1
LDY #00
INX
TXA ;X`is`also`an`index`into`the`character`number
CPX #16
BNE :LOOP ;Need`to`do`it`16`times
****`Clear`buffers
LDA #<BUFF1
STA BUFFER
LDA #>BUFF1
STA BUFFER+1
LDY #$00
LDX #24 ;Assuming`all`three`buffers`are
LDA #$00 ;back-to-back
:BLOOP STA (BUFFER),Y
INY
BNE :BLOOP
INC BUFFER+1
DEX
BNE :BLOOP
****`Set`up`buffers
LDA #<BUFF1
STA BUFFER
LDA #>BUFF1
STA BUFFER+1
STA ZTEMP ;ztemp`will`make`life`simple`for`us
LDA VMCSB
AND #%11110001 ;Start`here`so`that`swap`buffers`will`work`right
ORA #%00001110
STA VMCSB
****`Set`up`initial`values
INIT LDA #00
STA LOCXMIN
STA LOCXMAX
STA LOCYMIN
STA LOCYMAX
STA GLOBXMIN
STA GLOBYMIN
STA GLOBXMAX
STA GLOBYMAX
STA DSX
STA DSY
STA DSZ
STA SX
STA SY
STA SZ
STA FILL
LDA #01
STA HIDE
LDA #64
STA ZOOM
*-------------------------------
*`Main`loop
****`Get`keypress
MAIN
CLI
KPRESS JSR GETIN
CMP #133 ;F1?
BNE :F2
LDA DSX
CMP #ANGMAX/2 ;No`more`than`pi
BEQ :CONT1
INC DSX ;otherwise`increase`x-rotation
JMP :CONT
:F2 CMP #137 ;F2?
BNE :F3
LDA DSX
BEQ :CONT1
DEC DSX
JMP :CONT
:F3 CMP #134
BNE :F4
LDA DSY
CMP #ANGMAX/2
BEQ :CONT1
INC DSY ;Increase`y-rotation
JMP :CONT
:F4 CMP #138
BNE :F5
LDA DSY
BEQ :CONT1
DEC DSY
JMP :CONT
:F5 CMP #135
BNE :F6
LDA DSZ
CMP #ANGMAX/2
BEQ :CONT1
INC DSZ ;z-rotation
JMP :CONT
:F6 CMP #139
BNE :F7
LDA DSZ
BEQ :CONT1
DEC DSZ
JMP :CONT
:F7 CMP #136
BNE :PLUS
JMP INIT
:CONT1 JMP :CONT
:PLUS CMP #'+'
BNE :MINUS
INC ZOOM ;Bah,`who`needs`error`checking?
INC ZOOM
JMP :CONT
:MINUS CMP #'-'
BNE :H
DEC ZOOM
DEC ZOOM
BPL :CONT
INC ZOOM
INC ZOOM
JMP :CONT
:H CMP #'h'
BNE :SPACE
LDA HIDE
EOR #$01
STA HIDE
JMP :CONT
:SPACE CMP #'`'
BNE :Q
LDA FILL
EOR #$01
STA FILL
JMP :CONT
:Q CMP #'q' ;q`quits
BNE :CONT
JMP CLEANUP
:CONT SEI ;Speed`things`up`a`bit
****`Update`angles
UPDATE CLC
LDA SX
ADC DSX
CMP #ANGMAX ;Are`we`>=`maximum`angle?
BCC :CONT1
SBC #ANGMAX :If so, reset
:CONT1 STA SX
CLC
LDA SY
ADC DSY
CMP #ANGMAX
BCC :CONT2
SBC #ANGMAX ;Same`deal
:CONT2 STA SY
CLC
LDA SZ
ADC DSZ
CMP #ANGMAX
BCC :CONT3
SBC #ANGMAX
:CONT3 STA SZ
****`Rotate`coordinates
ROTATE
***`First,`calculate`t1,t2,...,t10
**`Two`macros`to`simplify`our`life
ADDA MAC ;Add`two`angles`together
CLC
LDA ]1
ADC ]2
CMP #ANGMAX ;Is`the`sum`>`2*pi?
BCC DONE
SBC #ANGMAX ;If`so,`subtract`2*pi
DONE <<<
SUBA MAC ;Subtract`two`angles
SEC
LDA ]1
SBC ]2
BCS DONE
ADC #ANGMAX ;Oops,`we`need`to`add`2*pi
DONE <<<
**`Now`calculate`t1,t2,etc.
>>> SUBA,SY;SZ
STA T1 ;t1=sy-sz
>>> ADDA,SY;SZ
STA T2 ;t2=sy+sz
>>> ADDA,SX;SZ
STA T3 ;t3=sx+sz
>>> SUBA,SX;SZ
STA T4 ;t4=sx-sz
>>> ADDA,SX;T2
STA T5 ;t5=sx+t2
>>> SUBA,SX;T1
STA T6 ;t6=sx-t1
>>> ADDA,SX;T1
STA T7 ;t7=sx+t1
>>> SUBA,T2;SX
STA T8 ;t8=t2-sx
>>> SUBA,SY;SX
STA T9 ;t9=sy-sx
>>> ADDA,SX;SY
STA T10 ;t10=sx+sy
*`Et`voila!
***`Next,`calculate`A,B,C,...,I
**`Another`useful`little`macro
DIV2 MAC ;Divide`a`signed`number`by`2
;It`is`assumed`that`the`number
BPL POS ;is`in`the`accumulator
CLC
EOR #$FF ;We`need`to`un-negative`the`number
ADC #01 ;by`taking`it's`complement
LSR ;divide`by`two
CLC
EOR #$FF
ADC #01 ;Make`it`negative`again
JMP DONEDIV
POS LSR ;Number`is`positive
DONEDIV <<<
MUL2 MAC ;Multiply`a`signed`number`by`2
BPL POSM
CLC
EOR #$FF
ADC #$01
ASL
CLC
EOR #$FF
ADC #$01
JMP DONEMUL
POSM ASL
DONEMUL <<<
**`Note`that`we`are`currently`making`a`minor`leap
**`of`faith`that`no`overflows`will`occur.
:CALCA CLC
LDX T1
LDA COS,X
LDX T2
ADC COS,X
STA A11 ;A=(cos(t1)+cos(t2))/2
:CALCB LDX T1
LDA SIN,X
SEC
LDX T2
SBC SIN,X
STA B12 ;B=(sin(t1)-sin(t2))/2
:CALCC LDX SY
LDA SIN,X
>>> MUL2
STA C13 ;C=sin(sy)
:CALCD SEC
LDX T8
LDA COS,X
LDX T7
SBC COS,X
SEC
LDX T5
SBC COS,X
CLC
LDX T6
ADC COS,X ;Di=(cos(t8)-cos(t7)+cos(t6)-cos(t5))/2
>>> DIV2
CLC
LDX T3
ADC SIN,X
SEC
LDX T4
SBC SIN,X
STA D21 ;D=(sin(t3)-sin(t4)+Di)/2
:CALCE SEC
LDX T5
LDA SIN,X
LDX T6
SBC SIN,X
SEC
LDX T7
SBC SIN,X
SEC
LDX T8
SBC SIN,X ;Ei=(sin(t5)-sin(t6)-sin(t7)-sin(t8))/2
>>> DIV2
CLC
LDX T3
ADC COS,X
CLC
LDX T4
ADC COS,X
STA E22 ;E=(cos(t3)+cos(t4)+Ei)/2
:CALCF LDX T9
LDA SIN,X
SEC
LDX T10
SBC SIN,X
STA F23 ;F=(sin(t9)-sin(t10))/2
:CALCG LDX T6
LDA SIN,X
SEC
LDX T8
SBC SIN,X
SEC
LDX T7
SBC SIN,X
SEC
LDX T5
SBC SIN,X ;Gi=(sin(t6)-sin(t8)-sin(t7)-sin(t5))/2
>>> DIV2
CLC
LDX T4
ADC COS,X
SEC
LDX T3
SBC COS,X
STA G31 ;G=(cos(t4)-cos(t3)+Gi)/2
:CALCH CLC
LDX T6
LDA COS,X
LDX T7
ADC COS,X
SEC
LDX T5
SBC COS,X
SEC
LDX T8
SBC COS,X ;Hi=(cos(t6)+cos(t7)-cos(t5)-cos(t8))/2
>>> DIV2
CLC
LDX T3
ADC SIN,X
CLC
LDX T4
ADC SIN,X
STA H32 ;H=(sin(t3)+sin(t4)+Hi)/2
:WHEW CLC
LDX T9
LDA COS,X
LDX T10
ADC COS,X
STA I33 ;I=(cos(t9)+cos(t10))/2
**`It's`all`downhill`from`here.
DOWNHILL
****`Clear`buffer
*`A`little`macro
SETBUF MAC ;Put`buffers`where`they`can`be`hurt
LDA #00
STA BUFFER
LDA ZTEMP ;High`byte
STABUF STA BUFFER+1
<<<
>>> SETBUF
CLRDRAW LDX #08
LDA #00
:FOOL LDY #00
:DOPE STA (BUFFER),Y
INY
BNE :DOPE
INC BUFFER+1
DEX
BNE :FOOL
****`My`goodness`but`I'm`a`dope
*CLRDRAW`LDA`GLOBXMIN
*`LSR``;Need`to`get`into`the`right`column
*`BCC`:EVEN`;Explained`in`more`detail`below
*`LDY`#$80
*`STY`BUFFER`;Presumably`this`will`be`a`little
*`CLC``;more`efficient.
*:EVEN`ADC`BUFFER+1
*`STA`BUFFER+1
*`LDA`GLOBXMAX
*`SEC
*`SBC`GLOBXMIN
*`TAX
*`INX
*`LDY`GLOBYMAX
*`BEQ`:RESET
*:YAY`LDA`#$00
*`LDY`GLOBYMAX
*:BLAH`STA`(BUFFER),Y
*`DEY
*`CPY`GLOBYMIN
*`BCS`:BLAH
*`LDA`BUFFER
*`EOR`#$80
*`STA`BUFFER
*`BNE`:WHOPEE
*`INC`BUFFER+1
*:WHOPEE`DEX
*`BNE`:YAY
*:RESET`LDA`#0`;Need`to`reset`these`guys
*`STA`GLOBXMAX
*`STA`GLOBYMAX
*`LDA`#$FF
*`STA`GLOBXMIN
*`STA`GLOBYMIN
****`Next,`read`and`draw`polygons
READDRAW LDY #00
STY INDEX
OBJLOOP LDY INDEX
LDA POLYLIST,Y ;First,`the`number`of`points
BNE :CONT ;But`if`numpoints`is`zero`then
JMP OBJDONE ;we`are`at`the`end`of`the`list
:CONT STA COUNTPTS
INC INDEX
*`Rotate`project`and`draw`the`polygon
*`Make`sure`buffer`being`drawn`to`is`clear!
:DOIT JSR ROTPROJ
*`Convert`xmin`and`xmax`to`columns
LDA LOCXMIN
LSR
LSR
LSR ;x`mod`8
STA LOCXMIN
CMP GLOBXMIN
BCS :NAH
STA GLOBXMIN
:NAH LDA LOCYMIN
CMP GLOBYMIN
BCS :UHUH
STA GLOBYMIN
:UHUH LDA LOCXMAX
LSR
LSR
LSR
STA LOCXMAX
CMP GLOBXMAX
BCC :NOWAY
STA GLOBXMAX
:NOWAY LDA LOCYMAX
CMP GLOBYMAX
BCC EORFILL
STA GLOBYMAX
*`If`using`the`EOR-buffer,`copy`into`drawing`buffer
*`And`then`clear`the`EOR-buffer
EORFILL LDA FILL
BEQ OBJLOOP
>>> SETBUF
LDA #<EORBUF
STA TEMP1
LDA #>EORBUF
STA TEMP1+1
LDA LOCXMIN ;LOCXMIN`now`contains`column
LSR ;Each`column`is`128`bytes
BCC :EVEN ;So`there`might`be`a`carry
LDY #$80
STY BUFFER
STY TEMP1
CLC
:EVEN STA T2
ADC BUFFER+1
STA BUFFER+1 ;Each`column`is`128`bytes
LDA T2
ADC TEMP1+1 ;Now`we`will`start`at`the
STA TEMP1+1 ;column
LDA LOCXMAX
SEC
SBC LOCXMIN
TAX ;Total`number`of`columns`to`do
INX ;e.g.`fill`columns`1..3
LDY LOCYMAX
BNE :FOOP
INC LOCYMAX
:FOOP LDY LOCYMAX
LDA #00
:GOOP EOR (TEMP1),Y ;EOR-buffer
PHA
*`Maybe`put`an`EOR`below?
EOR (BUFFER),Y
STA (BUFFER),Y
LDA #00 ;Might`as`well`clear`it`now
STA (TEMP1),Y
PLA
DEY
CPY LOCYMIN
BCS :GOOP
LDA BUFFER
EOR #$80
STA BUFFER
STA TEMP1
BNE :BOOP
INC BUFFER+1
INC TEMP1+1
:BOOP DEX
BNE :FOOP
JMP OBJLOOP
OBJDONE
****`Swap`buffers
SWAPBUF LDA VMCSB
EOR #$02 ;Pretty`tricky,`eh?
STA VMCSB
LDA #$08
EOR ZTEMP ;ztemp=high`byte`just`flips
STA ZTEMP ;between`$30`and`$38
JMP MAIN ;Around`and`around`we`go...
TXT 'Gee`Brain,`what`do`you`want`to`do`'
TXT 'tonight?'
**`Rotate,`project,`and`store`the`points
*
*`This`part`is`a`significant`change`since
*`v2.0.``Now`it`is`a`completely`general`polygon`plotter.
*`A`set`of`points`is`read`in,`rotated`and`projected,`and
*`plotted`into`the`drawing`buffer`(EOR`or`normal).
ROTPROJ
*`A`neat`macro
NEG MAC ;Change`the`sign`of`a`two's`complement
CLC
LDA ]1 ;number.
EOR #$FF
ADC #$01
<<<
*-------------------------------
*`These`macros`replace`the`previous`projection
*`subroutine.
SMULT`MAC`;Multiply`two`signed`8-bit
;numbers:`A*Y/64`->`A
STA`Z3
CLC``;This`multiply`is`for`normal
EOR`#$FF`;numbers,`i.e.`x=-64..64
ADC`#$01
STA`Z4
LDA`(Z3),Y
SEC
SBC`(Z4),Y
<<<``;All`done`:)
SMULTZ MAC ;Multiply`two`signed`8-bit
;numbers:`A*Y/64`->`A
STA Z1
CLC ;And`this`multiply`is`specifically
EOR #$FF ;for`the`projection`part,`where
ADC #$01 ;numbers`are`-110..110`and`0..40
STA Z2
LDA (Z1),Y
SEC
SBC (Z2),Y
<<< ;All`done`:)
PROJECT MAC ;The`actual`projection`routine
;The`routine`takes`the`point
;]1`]2`]3,`rotates`and
;projects`it,`and`stores`the
;result`in`]1`]2`]3.
LDY ]1 ;Multiply`first`rotation`column
LDA A11
>>> SMULT
STA P1T
LDA D21
>>> SMULT
STA P2T
LDA G31
>>> SMULT
STA P3T
LDY ]2 ;Second`column
LDA B12
>>> SMULT
CLC
ADC P1T
STA P1T
LDA E22
>>> SMULT
CLC
ADC P2T
STA P2T
LDA H32
>>> SMULT
CLC
ADC P3T
STA P3T
LDY ]3 ;Third`column
LDA C13
>>> SMULT
CLC
ADC P1T
STA P1T
LDA F23
>>> SMULT
CLC
ADC P2T
STA P2T
LDA I33
>>> SMULT
CLC
ADC P3T
STA ]3 ;Rotated`Z
TAX
LDY ZDIV,X ;Table`of`d/(z+z0)
;Now`Y`contains`projection`const
LDA P1T
>>> SMULTZ
LDX ZOOM
CPX #64
BEQ CONTX
STY TEMP1
LDY ZOOM
>>> SMULT
LDY TEMP1
CONTX CLC
ADC #64 ;Offset`the`coordinate
STA ]1 ;Rotated`and`projected
CMP LOCXMIN ;See`if`it`is`a`local`minimum
BCS NOTXMIN
STA LOCXMIN
NOTXMIN CMP LOCXMAX
BCC NOTXMAX
STA LOCXMAX
NOTXMAX LDA P2T
>>> SMULTZ
CPX #64
BEQ CONTY
LDY ZOOM
>>> SMULT
CONTY CLC
ADC #64
STA ]2 ;Rotated`and`projected`Y
CMP LOCYMIN
BCS NOTYMIN
STA LOCYMIN
NOTYMIN CMP LOCYMAX
BCC NOTYMAX
STA LOCYMAX
NOTYMAX <<< ;All`done
*`LDA`#<EORBUF`;First`we`need`to`clear`the
*`STA`BUFFER`;EOR`buffer
*`LDA`#>EORBUF
*`STA`BUFFER+1
LDA #0 ;Reset`Ymin`and`Ymax
STA LOCYMAX
STA LOCXMAX
LDA #$FF
STA LOCYMIN
STA LOCXMIN
READPTS LDY INDEX
LDA POLYLIST,Y
STA P1X
INY
LDA POLYLIST,Y
STA P1Y
INY
LDA POLYLIST,Y
STA P1Z
INY
DEC COUNTPTS
LDA POLYLIST,Y
STA P2X
INY
LDA POLYLIST,Y
STA P2Y
INY
LDA POLYLIST,Y
STA P2Z
INY
DEC COUNTPTS
LDA POLYLIST,Y
STA P3X
INY
LDA POLYLIST,Y
STA P3Y
INY
LDA POLYLIST,Y
STA P3Z
INY
STY INDEX
>>> PROJECT,P1X;P1Y;P1Z
>>> PROJECT,P2X;P2Y;P2Z
>>> PROJECT,P3X;P3Y;P3Z
LDA HIDE
BEQ :DOIT
LDA P2X ;Hidden`face`check
SEC
SBC P1X
TAY ;Y=(x2-x1)
LDA P3Y
SEC
SBC P2Y ;A=(y3-y2)
>>> SMULT
STA TEMP1
LDA P3X
SEC
SBC P2X
TAY
LDA P2Y
SEC
SBC P1Y
>>> SMULT
CMP TEMP1 ;If`x1*y2-y1*x2`>`0`then`face
BMI :DOIT ;is`visible
DEC COUNTPTS ;Otherwise`read`in`remaining
BEQ :ABORT ;points`and`return
:POOP INC INDEX
INC INDEX
INC INDEX
DEC COUNTPTS
BNE :POOP
:ABORT RTS
:DOIT LDA P1X
STA X1
LDA P1Y
STA Y1
LDA P2X
STA X2
LDA P2Y
STA Y2
JSR DRAW
LDA P2X
STA X1
LDA P2Y
STA Y1
LDA P3X
STA X2
LDA P3Y
STA Y2
JSR DRAW
DEC COUNTPTS
BNE POLYLOOP ;Is`it`just`a`triangle?
JMP POLYDONE
POLYLOOP LDY INDEX
LDA POLYLIST,Y
STA P2X
INY
LDA POLYLIST,Y
STA P2Y
INY
LDA POLYLIST,Y
STA P2Z
INY
STY INDEX
>>> PROJECT,P2X;P2Y;P2Z
LDA P2X
STA X1
LDA P2Y
STA Y1
LDA P3X
STA X2
LDA P3Y
STA Y2
JSR DRAW
LDA P2X
STA P3X
LDA P2Y
STA P3Y
DEC COUNTPTS
BEQ POLYDONE
JMP POLYLOOP
POLYDONE LDA P1X ;Close`the`polygon
STA X2
LDA P1Y
STA Y2
LDA P3X
STA X1
LDA P3Y
STA Y1
JSR DRAW
RTS
TXT 'Same`thing`we`do`every`night,`Pinky:`'
TXT 'try`to`take`over`the`world!'
*-------------------------------
*`General`questionable-value`error`procedure
*CHOKE`LDX`#00
*:LOOP`LDA`:CTEXT,X
*`BEQ`:DONE
*`JSR`CHROUT
*`INX
*`JMP`:LOOP
*:DONE`RTS
*:CTEXT`HEX`0D`;CR
*`TXT`'something`choked`:('
*`HEX`0D00
*
TXT 'Narf!'
*-------------------------------
*`Drawin'`a`line.``A`fahn`lahn.
***`Some`useful`macros
CINIT MAC ;Macro`to`initialize`the`counter
LDA ]1 ;dx`or`dy
LSR
<<< ;The`dx/2`makes`a`nicer`looking`line
*****`Macro`to`take`a`step`in`X
XSTEP MAC
LDX DX ;Number`of`loop`iterations
>>> CINIT,DX
XLOOP LSR CHUNK
BEQ FIXC ;Update`column
SBC DY
BCC FIXY ;Time`to`step`in`Y
DEX
BNE XLOOP
DONE LDA OLDX ;Plot`the`last`chunk
EOR CHUNK
ORA (BUFFER),Y
STA (BUFFER),Y
RTS
FIXC PHA
LDA OLDX
ORA (BUFFER),Y ;Plot
STA (BUFFER),Y
LDA #$FF ;Update`chunk
STA OLDX
STA CHUNK
LDA #$80 ;Increase`the`column
EOR BUFFER
STA BUFFER
BNE C2
INC BUFFER+1
C2
PLA
SBC DY
BCS CONT
ADC DX
IF I,]1 ;Do`we`use`INY`or`DEY?
INY
ELSE
DEY
FIN
CONT DEX
BNE XLOOP
JMP DONE
FIXY ADC DX
PHA
LDA OLDX
EOR CHUNK
ORA (BUFFER),Y
STA (BUFFER),Y
LDA CHUNK
STA OLDX
PLA
IF I,]1 ;Update`Y
INY
ELSE
DEY
FIN
DEX
BNE XLOOP
RTS
<<< ;End`of`Macro`xstep
*****`Take`a`step`in`Y
YSTEP MAC
LDX DY ;Number`of`loop`iterations
BEQ DONE ;If`dy=0`it's`just`a`point
>>> CINIT,DY
SEC
YLOOP PHA
LDA OLDX
ORA (BUFFER),Y
STA (BUFFER),Y
PLA
IF I,]1
INY
ELSE
DEY
FIN
SBC DX
BCC FIXX
DEX
BNE YLOOP
DONE LDA OLDX
ORA (BUFFER),Y
STA (BUFFER),Y
RTS
FIXX ADC DY
LSR OLDX
SEC ;Important!
BEQ FIXC
DEX
BNE YLOOP
JMP DONE
FIXC PHA
LDA #$80
STA OLDX
EOR BUFFER
STA BUFFER
BNE C2
INC BUFFER+1
C2 PLA
DEX
BNE YLOOP
JMP DONE
<<< ;End`of`Macro`ystep
*`Take`an`x`step`in`the`EOR`buffer
*`The`sole`change`is`to`use`EOR`instead`of`ORA
EORXSTEP MAC
LDX DX ;Number`of`loop`iterations
>>> CINIT,DX
XLOOP LSR CHUNK
BEQ FIXC ;Update`column
SBC DY
BCC FIXY ;Time`to`step`in`Y
DEX
BNE XLOOP
DONE LDA OLDX ;Plot`the`last`chunk
EOR CHUNK
EOR (BUFFER),Y
STA (BUFFER),Y
RTS
FIXC PHA
LDA OLDX
EOR (BUFFER),Y ;Plot
STA (BUFFER),Y
LDA #$FF ;Update`chunk
STA OLDX
STA CHUNK
LDA #$80 ;Increase`the`column
EOR BUFFER
STA BUFFER
BNE C2
INC BUFFER+1
C2
PLA
SBC DY
BCS CONT
ADC DX
IF I,]1 ;Do`we`use`INY`or`DEY?
INY
ELSE
DEY
FIN
CONT DEX
BNE XLOOP
JMP DONE
FIXY ADC DX
PHA
LDA OLDX
EOR CHUNK
EOR (BUFFER),Y
STA (BUFFER),Y
LDA CHUNK
STA OLDX
PLA
IF I,]1 ;Update`Y
INY
ELSE
DEY
FIN
DEX
BNE XLOOP
RTS
<<< ;End`of`Macro`xstep
*`Take`a`y-step`in`the`EOR-buffer
*`Changes`from`above`are:`only`plot`last`part`of`each
*`vertical`chunk,`don't`plot`last`point,`plot`with`EOR
EORYSTEP MAC
LDX DY ;Number`of`loop`iterations
BEQ DONE ;If`dy=0`it's`just`a`point
>>> CINIT,DY
SEC
*YLOOP`PHA
*`LDA`OLDX
*`ORA`(BUFFER),Y
*`STA`(BUFFER),Y
*`PLA
YLOOP IF I,]1
INY
ELSE
DEY
FIN
SBC DX
BCC FIXX
DEX
BNE YLOOP
*DONE`LDA`OLDX
*`ORA`(BUFFER),Y
*`STA`(BUFFER),Y
DONE RTS
FIXX ADC DY
PHA ;We`only`plot`the`last`part`of`each`chunk
LDA OLDX
EOR (BUFFER),Y
STA (BUFFER),Y
PLA
LSR OLDX
SEC ;Important!
BEQ FIXC
DEX
BNE YLOOP
JMP DONE
FIXC PHA
LDA #$80
STA OLDX
EOR BUFFER
STA BUFFER
BNE C2
INC BUFFER+1
C2 PLA
DEX
BNE YLOOP
JMP DONE
<<< ;End`of`Macro`ystep
****`Initial`line`setup
**`The`commented`lines`below`are`now`taken`care`of`by`the
**`calling`routine.
*DRAW`>>>`MOVE,TX1;X1``;Move`stuff`into`zero`page
*`>>>`MOVE,TX2;X2``;Where`it`can`be`modified
*`>>>`MOVE,TY1;Y1
*`>>>`MOVE,TY2;Y2
DRAW LDA FILL
BNE :SETEOR
>>> SETBUF
JMP :SETUP
:SETEOR LDA #<EORBUF ;Use`EOR`buffer`instead`of
STA BUFFER ;display`buffer`for`drawing
LDA #>EORBUF
STA BUFFER+1
:SETUP SEC ;Make`sure`x1<x2
LDA X2
SBC X1
BCS :CONT
LDA Y2 ;If`not,`swap`P1`and`P2
LDY Y1
STA Y1
STY Y2
LDA X1
LDY X2
STY X1
STA X2
SEC
SBC X1 ;Now`A=dx
:CONT STA DX
LDX X1 ;Put`x1`into`X,`now`we`can`trash`X1
COLUMN TXA ;Find`the`first`column`for`X
LSR
LSR ;There`are`x1/8`128`byte`blocks
LSR ;Which`means`x1/16`256`byte`blocks
LSR
BCC :EVEN ;With`a`possible`extra`128`byte`block
LDY #$80 ;if`so,`set`the`high`bit
STY BUFFER
CLC
:EVEN ADC BUFFER+1 ;Add`in`the`number`of`256`byte`blocks
STA BUFFER+1
SEC
LDA Y2 ;Calculate`dy
SBC Y1
BCS :CONT2 ;Is`y2>y1?
EOR #$FF ;Otherwise`dy=y1-y2
ADC #$01
:CONT2 STA DY
CMP DX ;Who's`bigger:`dy`or`dx?
BCC STEPINX ;If`dx,`then...
JMP STEPINY
STEPINX LDY Y1
CPY Y2
LDA BITP,X ;X`currently`contains`x1
STA OLDX
STA CHUNK
BCC XINCY ;Do`we`step`forwards`or`backwards`in`Y?
JMP XDECY
XINCY LDA FILL
BEQ NORMXINC
>>> EORXSTEP,INY
NORMXINC >>> XSTEP,INY
XDECY LDA FILL
BEQ NORMXDEC
>>> EORXSTEP,DEY
NORMXDEC >>> XSTEP,DEY
STEPINY LDY Y1
LDA BITP,X ;X=x1
STA OLDX
LSR ;Y`doesn't`use`chunks
EOR OLDX ;So`we`just`want`the`bit
STA OLDX
CPY Y2
BCS YDECY
YINCY LDA FILL
BEQ NORMINC
>>> EORYSTEP,INY
NORMINC >>> YSTEP,INY
YDECY LDA FILL
BEQ NORMDEC
>>> EORYSTEP,DEY
NORMDEC >>> YSTEP,DEY
*-------------------------------
*`Clean`up
CLEANUP LDA VMCSB ;Switch`char`rom`back`in
AND #%11110101 ;default
STA VMCSB
RTS ;bye!
TXT 'spinal`cracker`'
TXT 'slj`6/95'
*-------------------------------
*`Set`up`bit`table
DS ^ ;Clear`to`end`of`page
;So`that`tables`start`on`a`page`boundary
BITP LUP 16 ;128`Entries`for`X
DFB %11111111
DFB %01111111
DFB %00111111
DFB %00011111
DFB %00001111
DFB %00000111
DFB %00000011
DFB %00000001
--^
SIN ;Table`of`sines,`120`bytes
COS EQU SIN+128 ;Table`of`cosines
;Both`of`these`trig`tables`are
;currently`set`up`from`BASIC
ZDIV EQU COS+128 ;Division`table
TMATH1 EQU ZDIV+384 ;Math`table`of`f(x)=x*x/256
TMATH2 EQU TMATH1+512 ;Second`math`table
POLYLIST EQU TMATH2+512 ;List`of`polygons
========================================================================
Second SID Chip Installation
Copyright 1988 Mark A. Dickenson
This information and software is COPYRIGHTED and made available on a
SHAREWARE basis. This file can be freely copied and distributed as long
as it is not SOLD. This information cannot be used to construct and sell a
hardware device without receiving prior permission from the author. There is
not a set fee for the use of this information. Just send in whatever you feel
the information is worth.
If you have any gripes, complaints, suggestions, COMPLIMENTS or DONATIONS of
any sort please send them to:
Mark Dickenson
600 South West Street
Nevada, Missouri 64772
Adding an extra SID 6581/6582 chip
This is not a project to be tackled by the sqeamish or people who are deathly
afraid of opening their computer just to take a peek inside.
Now let's get rid of the nasty stuff first. No liability is assumed with
respect to the use of the following information. In other words if you
screw-up trying to install this modification, then it's your responsability.
YOU DO THIS AT YOUR OWN RISK!!!!
If you do not feel up to it PLEASE take it to a Commodore repair center
or a repair service that can work on computers and let them do the
installation. I will warn you that most Commodore Repair Centers will not or
do not like to do this modification. When they do, it can be expensive. If
you belong to a Users Group, tell them about the project and ask if there is
anyone there that could perform the operation. This modification will NOT
hurt the computer in any way, unless it is installed WRONG.
You can make your own piggy back board or you can do what I am going to
describe (since it is a little hard to put a schematic in a text file).
You should ground yourself with a static guard wristband (such as what
Radio Shack sells). Even though the chip is quite durable, just the right
static discharge can ruin all or part of the SID chip.
For those of you that are not familier with the way pins are numbered on an
IC chip here is a short explanation. On one end of the IC you should find a
little notch, looking at the chip with the notch at the top the numbering goes
this way. The upper left corner of the chip is pin 1 and they are numbered
consecutively, counter-clockwise around the chip. Some chips do not have a
notch in one end, but instead dot is placed in one of the chip corners to
designate that pin 1 starts in that location.
notch
----,,----
1-!. !-8
2-! dot !-7
3-! !-6
4-! !-5
----------
I have included the information that is needed to install this modification
on the Commodore 64, 64C and 128. I haven't been able to look inside the
128D, so I cannot provide the information with any accuracy.
There are TWO different 64C circuit boards and both use DIFFERENT SID
chips. You can tell the difference by opening the 64C. If you see a 64-pin
chip on the board and the board is only 5.5-6 inches wide then you have the
narrow board 64C and must use the 9 volt 6582 SID chip. The number of the
chip in the 64C narrow is an 8520 and is the same as the 6582.
----------------------------------
Parts Commodore 64, 64C (wide) & 128
1 - 6581 SID chip from Jamco or Kassara Microsystems
1 - 2N2222 transistor Radio Shack 276-1617
2 - 220pf capacitors Radio Shack 272-124
-----------------------------------
Parts Commodore 64C Narrow Board
1 - 6582 SID Chip From Jamco or Kassara Microsystems
1 - 2222A transistor Radio Shack 276-2009
2 - .022uf capacitors Radio Shack 272-1066
2 - 1k ohm 1/4 watt resistors Radio Shack 271-1321
-----------------------------------
Parts 64, 64C (all) & 128
2 - 1k ohm 1/4 watt resistors Radio Shack 271-1321
1 - 1000 pf capacitor Radio Shack 272-126 listed as .001 mf this is
the same as 1000pf
1 - 10k ohm 1/4 watt resistor Radio Shack 271-1335
1 - 10 uf electrolitic capacitor Radio Shack 272-1025
1 - 5 inch length of wire
1 - 5 inch length of shielded cable
1 - surface mount female RCA plug (this is what you normally find on the back
of your stereo.
On the C-64 and 64C (wide) the SID is IC U18 (the IC number will be marked in
white on the circuit board). It is usually located in the middle of the
circuit board, next to the metal video chip case or up between and just
below the serial and monitor jacks.
On the C-64C (narrow board) the SID chip is IC U9. It is located in the
middle of the board, just a little to the right of center) and called 520.
On the C-128 the SID is IC U5. It is located at the back of the circuit
board just to the right of the metal housing for the 40 and 80 column video
chips.
First bend out pins 23, 24 and 26 and cut them off of the 6581/6582 SID
chip. These are for the two analog and one audio input lines. They will
cause problems if connected and since they will not be used it is best to
remove them.
Now bend out pins 1, 2, 3, 4, 8, and 27.
Solder one of the 220pf capacitors (64C narrow uses .022 uf) to pins 1
and 2 then solder the other 220pf (64C narrow - .022uf) capacitor to pins 3
and 4. The capacitors control the upper and lower frequency range and
filters of the SID chip.
The reason I am using 220pf capacitors is because of problems with the
filters in the SID chip. The C-64 first came out with 2200pf capacitors, but
they were changed to 470pf. The reason for this was because the filters of
the SID vary from chip to chip and using 2200pf caused a lot of them to sound
muffeled when the filters were on. I have found that by lowering the
capacitor value to 220 pf helps even more. If you wish, you can use 470s if
you feel it would be better, but DO NOT use 2200pf.
The 6582 SID chip for the 64C narrow must use the .022uf capacitors, as the
filter range is much different.
Solder one end of your wire to pin 8 of the SID chip. This is for the chip
select line. We will connect this to the cartridge port. This tells the
computer where in memory the chip resides (described later).
Now solder the remaining pins (excluding the ones we have bent out
and/or removed 1, 2, 3, 4, 8, 23, 24, 26 and 27) to the sid chip currently in
your computer. You may have to bend those pins inward just a little for them
to get a good grip on the SID chip. Be very careful not leave the soldering
iron on the chip TOO long as you could ruin BOTH SID chips. I would put some
heat sink (silicon grease) between the two chips before soldering them
together. This will provide better heat dispersal on the bottom chip.
Now that you have the chips soldered together (place the SID chips back in
the socket if you removed them), solder the wire from pin 8 (on the SID chip)
to pin 7 of the cartridge port on the back of the computer. Set the computer
infront of you like to are getting ready to type, with the back of the
computer away from you. Look at the cartridge port (located in the upper
right corner of the circuit board). You will see two rows of pins connecting
the cartridge port to the circuit board. You want the row of pins closest to
the front of the computer. Now, count the pins starting at the LEFT side and
counting to the right. You want to solder the wire from pin 8 of the extra
SID chip to pin number 7 of the cartridge port. This is the same place on all
of the models C-64, 64C and 128.
This will tell the computer that the extra SID chip is at address $DE00 hex
or 56832 decimal. You will access it just like you would the regular sid
chip but starting at this address.
I am no longer describing how to connect for address $DF00. This
address causes problems with the RAM Expansion Units and numerous other
cartridges. From now on address $DE00 is the ONLY address for the SID chip.
Now partially reassemble your computer (be careful that nothing shorts out
the pins still sticking out). Turn the computer on and load the player
program provided and tell it to load in 'TEST'. If you get sound then so far
so good. Turn off the computer and disassemble the case.
Drill a hole in the back end of the computer just large enough to anchor
the RCA plug. Then solder the center wire of the shielded cable to the
center post of the RCA plug. Insert the wire through the hole you have
just drilled and anchor the plug to the case. Now solder the ground wire to
the ground tab on the RCA plug.
Here comes the difficult part to explain. This is the coupling circuit
for the audio output. Here is a rough schematic.
Pin 27 on 12volts dc,
9volts 64C (narrow)
SID chip resistor
!--. 10k ohm !collector
27!----.--/!/!/--.-----O 2n2222 or 2222A
--' ! ! !emitter
! ! !
<resistor ! !
>1k ! ! +
===========================================================================
SOLVING LARGE SYSTEMS OF LINEAR EQUATIONS ON A C64 WITHOUT MEMORY
by Alan Jones (alan.jones@qcs.org)
OK, now that I have your attention, I lied. You can't solve dense
linear systems of equations by direct methods without using memory to
store the problem data. However, I'll come back to this memory free
assertion later. The main purpose of this article is to rescue a
usefull numerical algorithm, "Quartersolve", and also to provide a brief
look at the COMAL programming language and BLAS routines.
Linear systems of equations, A(,)*x()=b(), where A is a square matrix
and x and b are vectors (or arrays), must often be solved for x in the
solution of a variety of problems. The size or dimension of the problem
is n and just storing A requires 5*n*n bytes of memory, assuming C64/128
5 byte real variables. The prefered solution method is a form of
Gaussian Elimination which requires 1/3 n*n*n multiplications. I'll
ignore the additional n*n and n multiplies. For large problems our C64
has two serious limitations, small memory size and slow floating point
arithmetic. Problems with n=10 can be computed easily. Problems with
n=100 will require 100 times more memory and 1000 times more computing
time. The computing time is not a real problem. I don't mind letting
my computer run while I watch a movie, sleep, or go on a trip.
Calculating or setting up the problem may take much longer than its
solution anyway. Available memory is the practical limiting factor.
After we use up available RAM we have to resort to other algorithms that
will use the disk drive to move data in and out of the computer. The
1541 drive is particularly slow and I would not want to subject it to
undue wear and tear.
How big a problem do we need to be able to solve? In many cases the
problem itself will fix n and there is no way to reduce it. In other
cases you might be modeling a real continuous problem with a discrete
number of elements. N should be infinity but for problem solution n=50
might be big
enough. Consider calculating the aerodynamic potential
flowfield around a body of revolution. You could fix points on the
surface of the body (a meridian) and have a series of sort line segments
make up elements to approximate the shape. The lager n is the closer
the smooth shape is aproximated and the more accurate the computed
solution becomes. n=100 might be a good choice for a simple shape. We
could also use a "higher order" menthod. In this case we can substitute
a curved line element for the straight line segment. Calculating the
matrix elements will be more difficult but n=40 curved elements might
give a more accurate solution than 100 flat elements. Another
consideration is the resolution of the solution. You might want to plot
the solution on the 200 x 320 pixel hi-res C64 screen. 40 points might
be too coarse and 320 might be overkill. We might also need to
calculate the slope or derivatives from the calculated solution which
will require more closely spaced solution points. There are often
choices that you can make in modeling a system and selecting a solution
algorithm so that a problem can be solved within the limits of a C64.
There are often interesting tradeoffs in memory requirements and
execution speed.
How big a problem can we solve with a C64? Using Quartersolve with
assembly language we can probably do n=200 or more. If we are going to
store the problem data on a single 1541 diskette and read it in a row at
time we can only do n=182 or so. Actually I think n should be well
under 100. Different operating systems and languages limit the amount
of useable RAM; BASIC 40K, COMAL 2.0 30K, GEOS 23K, the initial disk
loaded COMAL 0.14 10K... Solving a linear system may only be a small
subproblem inside a large application program. The idea is to be able
to solve reasonable sized problems using your prefered computing
environment without having to do a lot of chaining or loading of
separate programs. Quartersolve can free up a lot of memory for other
routines or allow n to be doubled.
SPEED
There are a few things that we can do to speed up the calculations.
First we can select a fast programming language. I prefere COMAL 2.0
which is a fast three pass interpreter. Using an assembler could be the
fastest and provide the most useable memory. A true compiler such as C
or Pascal could also be a good choice. BASIC is a poor choice except
that it is built in and free. In most cases execution can be sped up
with some machine language routines like the BLAS (Basic Linear Algebra
Subroutines). Calculation speed is measured in FLOPS/sec (Floating
Point OPerationS) where, c(i#,j#):=c(i#,j#) + a(i#,k#)*b(k#,j#) is the
operation. It is one FP multiply, one FP add, and some indexing
overhead. With some interpreters the indexing and interpreting overhead
can far exceed the actual FP multiply time. With assembled code the FP
multiply time should dominate. I use a ML level 1 BLAS package with
COMAL 2.0. For example:
c(i#,J#):+sdot(n#,a(i#,1),1,b(1,j#),sdb#)
FOR k#:=1 to n# do c(i#,j#):+a(i#,k#)*b(k#,j#)
both calculate the same thing, a dot product with n# FLOPS. For large
n# on a C64 the BLAS approach about 320 FLOPS/sec., The overhead of
calling the procedure from the interpreter is about the equivalent of 4
FLOPS. Of course modern computer performance is measured in
MegaFLOPS/sec. with 8 byte reals (super computers run hundreds or
thousands of MFLOPS/sec.). They also inflate the performance by
counting the multiply and add as two FLOPS. In his article I use the
"old flops" or number of multiplies.
It may also be possible to code 6502 FP arithmetic routines using lookup
tables that may perform faster than the built in routines. We could
also use the CPU in the disk drives to do distributed processing. But
this is beyond the scope of this article.
SOLUTION METHODS
Consider the following choices for numerical solution algorithms:
METHOD MEMORY FLOPS
Gaussian Elimination n*n 1/3 n*n*n
Cholesky Decomposition 1/2 n*n 1/6 n*n*n
QR decomposition n*n 2/3 n*n*n
QR updating 1/2 n*n 2 n*n*n
Gauss-Jordan n*n 1/2 n*n*n
Quartersolve 1/4 n*n 1/2 n*n*n
Gaussian Elimination is the prefered method when enough memory is
available. In modern terminology this is LU decomposition where A is
decomposed or factored into a lower triangular matrix and an upper
triangular matrix. Partial pivoting of rows or columns is an additional
complication often required for a stable solution. After the LU
decompostion you can readily solve for any number of right hand side
vectors in n*n flops each. In addition you can calculate matrix
condition number estimates and use iterative improvement techniques.
The LU decomposition is done in place overwriting the problem matrix A.
Cholesky Decomposition is a specialized version of Gaussian Elimination
for symetric positive definite matrices only. Since A is symetric we
only need n*(n+1)/2 memory storage locations. The L and U triangular
matrices are simply transposes of the other so only one needs to be
stored and is computed in place overwriting the original storage used
for A. No pivoting is required. This algorithm cannot solve general
nonsymetric problems and is included only for comparison.
QR decomposition factors A into an orthogonal matrix Q and a triangular
matrix R. QR decomposition is very stable and can be performed without
pivoting. Since Q is orthogonal its inverse is just Q transpose. To
solve the linear system we multiply the right hand side vector by Q
transpose then solve the triangular system R. Q is computed in a
special compact form and stored in the space below R. The decomposition
is done in place in the storage used for A, plus an additional n storage
locations. QR decomposition requires about twice as many flops as
Gaussian Elimination.
There is a variation of the QR solution known as QR updating. The
problem is solved a row at a time. A Row of A can be read in from disk
storage or calculated as needed. Only R needs to be stored in main
memory, n*(n+1)/2 memory locations. R is initialy the identity matrix
and is updated as each row of A and its right hand side element are
processed. Q is not stored, but the right hand side vector is
sequentialy multiplied by Q transpose. After all n rows have been
processed the solution is found by simply solving the triangular system
R. Since this method only needs half as much memory storage as LU
decomposition, we can solve problems 40% larger in a limited memory
space. However, the cost in flops is high. Actually QR updating is
best used for solving large overdetermined least squares problems.
Gauss-Jordan is a variation of Gaussian Elimination that reduces A to
the Identity matrix instead of to LU factors. By applying the same
transformations to to the right hand side that reduce A to the identity
matrix, the right hand side becomes the solution at completion.
Pivoting is requiered. Gauss-Jordan requires about 50% more flops than
Gaussian Elimination and most codes use n*n memory storage. Since the
LU factors are not computed we can't solve additional right hand side
vectors later, or estimate the matrix condition number, or use iterative
improvement techniques. It will solve multiple right hand sides that
are available from the start.
Quartersolve is a clever implementation of Gauss-Jordan(?) that solves
the problem a row at a time like QR updating but only requires 1/4 n*n
memory storage. With fixed available memory Quartersolve can solve a
problem twice as large as Gaussian Elimination but with a modest
performance penalty. Solving a 2n problem with Quartersolve would take
12 times longer (instead of 8) than Gaussian Elimination on a size n
problem.
My recommendation is to use Gaussian elimination for solving dense
general systems of linear equations when enough main memory is available
and switch to Quartersolve for larger problems. For solving huge
problems requiering external storage a blocked version of QR
decomposition might work best. Cholesky decomposition should be used
for symetric positive definite problems. Large problems are often
sparse, containing lots of zeros that need not be stored. Specialized
code exists for solving many sparce problems, particularly banded
matrices, and many of these methods can be used on a C64. Codes for
solving unstructured sparce problems are not very suitable for the C64
since they are complex and reduce the amount of memory available for
solving the problem. However, large sparce problems can also be solved
on the C64 by iterative methods such as Gauss-Siedel and Conjugate
Gradient algorithms.
QUARTERSOLVE
Quartersolve is a useful method for solving general dense systems of
linear equations that I discovered almost by accident while doing random
research in the library. I have not seen any recent texts or papers
mentioning this algorithm. I have not seen any reference to it in the
C64 literature either. At least one older text mentioned it in passing
saying that the code was too long or complex. This is a valid point
since usualy the code size directly subtracts from the problem storage.
The code is longer than the Gaussian Elimination code but in my
implementation it only takes about 2K of main memory storage and it is a
real advantage on the C64. With a C64 we can also put the entire code
in an EPROM on a cartridge so the code size is of little concern.
I found Quartersolve in Ref. 1 (R. A. Zamberdino, 1974), which credited
the algorithm to Ref. 2 (A. Orden, 1960). I am a little uneasy
describing the algorithm since I have not seen Ref. 2 or analyzed the
algorithm. I have coded the algorithm, tested it, and used it to solve
some large problems on a C64, up to n=90. Zambardino makes two
interesting statements in Ref 1. "The number of arithmetic operations
is the same as for the Gaussian Elimination method." I am reasonably
sure from the description that he meant Gauss-Jordan which requires
about 50% more arithmetic than Gaussian Elimination. After processing
the ith row only i(n-i) storage locations are required to store the
reduced matrix. Max[i(n-i)] = n*n/4. This maximum memory requirement
occurs at i = n/2. As i increases further memory required is reduced.
Although n*n/4 memory locations must be allocated and dimensioned in an
array at the start, Quartersolve always uses the first portion of the
array continuously and does not free up memory in holes scattered
throughout the array. The C language could possibly use "heap storage"
and release the memory for any other use as the procedure advances.
Now back to my initial memory free claim. The large problem that I
actually wanted to solve was: A*x=b, B*x=r, for r given b and the square
matrices A and B. Elements of A and B are most efficiently calculated
at the same time. I could write B to the drive and read it back in
after x is computed to calculate r, but I actually wanted to solve this
repeatedly inside another loop and I did not want to read and write to a
lousy 1541 that much. Using Gaussian elimination would require 2n*n
storage. Using Quartersolve could require 1.25n*n storage. However,
only n*n storage is needed, that for B. At the ith step the ith row of
A and B are calculated. The row of A is processed into the the n*n
dimensioned array B filling it from the front. The corresponding row of
B is stored in the same array B filling from from the end of array B.
As the process continues Quartersolve "dissuses" array B so that rows of
B never overwrite storage needed by Quartersolve. At the end we have
computed x and all of B is stored in the array B. Simple
multiplication produces r. So I can say with pride, at the expense of
honesty, that I have solved A*x=b without any additional memory storage
for A.
PROC slv(n#,nr#,i#,REF a(),REF c(),REF b(,),sdb#,REF sw#(),REF fail#) CLOSED
// This routine solves a system of equations using the quartersolve
// algorithm with partial pivoting.
// It is called a "line at a time" and uses only
// 0.25*nn memory locations which enables larger problems to be solved.
// The LU factorization is not available, nor a condition estimate.
// n# is the dimension of the problem
// nr# is the number of right hand vectors to be solved for.
// b(,) is the right hand side columns
// sdb# is the second dimension of the array b(,)
USE blas
USE strings
q#:=i#-1; m#:=n#-q#; mm1#:=m#-1; fail#:=TRUE; ip1#:=i#+1
IF i#=1 THEN //initialize pivot array
FOR j#:=1 TO n# DO sw#(j#):=j#
ENDIF
FOR j#:=1 TO q# DO //adjust for previous pivoting
k#:=sw#(j#)
WHILE k#<j# DO k#:=sw#(k#)
IF k#>j# THEN swap'real(c(j#),c(k#))
ENDFOR j#
FOR j#:=i# TO n# DO c(j#):-sdot(q#,c(1),1,a(j#-q#),m#)
p#:=q#+isamax#(m#,c(i#),1)
r:=ABS(c(p#))
IF r=0 THEN RETURN
fail#:=FALSE
IF p#<>i# THEN
swap'real(c(i#),c(p#))
swap'integer(sw#(i#),sw#(p#))
sswap(q#,a(1),m#,a(p#-q#),m#)
ENDIF
r:=1/c(i#)
IF mm1#<>0 THEN sscal(mm1#,r,c(ip1#),1)
FOR j#:=1 TO nr# DO b(i#,j#):=r*(b(i#,j#)-sdot(q#,c(1),1,b(1,j#),sdb#))
FOR k#:=1 TO nr# DO saxpy(q#,-b(i#,k#),a(1),m#,b(1,k#),sdb#)
IF mm1#>0 THEN
t#:=1
FOR j#:=1 TO q# DO
r:=a(t#); t#:+1
scopy(mm1#,a(t#),1,a(t#-j#),1)
saxpy(mm1#,-r,c(ip1#),1,a(t#-j#),1)
t#:+mm1#
ENDFOR j#
scopy(mm1#,c(ip1#),1,a(mm1#*q#+1),1)
ELSE //unscramble solution from pivoting
FOR j#:=1 TO nr# DO
FOR k#:=1 TO n# DO c(sw#(k#)):=b(k#,j#)
scopy(n#,c(1),1,b(1,j#),sdb#)
ENDFOR j#
ENDIF
ENDPROC slv
//
n#:=8; sdrh#:=1; nrh#:=1; nr#:=1
// a is of dimension n*n/4
DIM a(16), b(n#), rhs(n#,nrh#), sw#(n#)
FOR i#:=1 TO n# DO
FOR j#:=1 TO n# DO b(j#):=2297295/(i#+j#-1)
s:=0
FOR j#:=n# TO 1 STEP -1 DO s:+b(j#)
rhs(i#,1):=s
slv(n#,nr#,i#,a(),b(),rhs(,),sdrh#,sw#(),fail#)
IF fail# THEN
PRINT "singularity detected at i=";i#
STOP
ENDIF
ENDFOR i#
FOR j#:=1 TO n# DO PRINT rhs(j#,1);
END
The Quartersolve algorithm is presented here as a COMAL 2.0 procedure
"slv". COMAL is pretty much a dead language and I don't expect anyone
to run this code. However, COMAL is a structured algorithmic language
that is easy to read. You can readily translate it into the programming
language of your choice. Slv is coded as a CLOSED procedure as a
personal matter of style. An open procedure would execute faster. The
arrays are passed by REFERENCE and do not allocate additional local
storage. The main program is just an example for testing. It calls slv
n times to solve the linear system. The test problem solves a scaled
Hilbert matrix which is ill conditioned. In the absence of roundoff
error the solution should be a vector of ones. I usually dimension a()
to n#*(n#+1)/4. Slv is presented in its full generality, but you may
want to make some simplifications.
Slv can handle multiple right hand side vectors with the two dimensional
array b(,) in most applications you will only use a single vector,
nr#=1, and you can make some simplifications by just using a one
dimensional array.
Pivoting also complicates the code. Problems which are positive
definite, or diagonally dominant, or sometimes just well conditioned
can be safely solved without pivoting. Stripping out the pivoting code
is straight forward and will shorten the code and speed execution.
Anything following // is a comment and can be deleted from your running
code.
In COMAL 2.0 you can also "protect" the code which will strip out
comments and other information to make a shorter running version.
The remaining discussion will concern COMAL 2.0 and the BLAS.
COMAL 2.0
COMAL 2.0 is an excellent programming language for the C64/128 and I
can't describe all of its virtues here. It has one serious limitation.
It does not use "continuation" lines, so line length is limited. This
is most restrictive in function and procedure lines where it limits the
number of parameters that can be passed. Line length is limited to 80
characters. However, if you use a separate text editor or word
processor you can enter 120 character lines. Comal will actually
execute tokenized lines up to 256 characters so the limitation is really
in the editor rather than COMAL. Procedure and variable names can be
quite long in Comal, but are kept short because of the line length
limitation. "Quartersolve" was shortened to "slv" for this reason.
a:+t is a shorter faster version a:=a+t, and a:-t is a shorter faster
version of a:=a-t. This is most usefull when "a" is an array element or
an integer.
Comal 2.0 supports ML packages. A package is a collection of functions
or procedures that can be called and executed. A packaged can be ROMMED
and stored in EPROM on the Comal 2.0 cartridge. A package can also be
loaded from disk and will normally be stored in a RAM location that
COMAL does not use for normal programs. LINK "filename" will load and
link the ML package to a Comal program. It will stay attached to the
program when the program is saved and loaded, unless it is marked as
ROMMED. The entire slv procedure could be coded in assembly language
and be placed in a package. The slv procedure uses two packages,
strings and blas. The command USE packagename makes all of the
functions and procedures of the package known. Alternatively, you could
place the USE packagename command in the main program and put IMPORT
procedurename inside all of the closed procedures that call
procedurename.
Slv calls the swap'real and swap'integer proocedures from the strings
package. The strings package is a ROMMED package on the Super Chip ROM.
It does exactly what it says, e.g. swap'real(a,b) is the same as:
t:=a; a:=b; b:=t.
Slv calls the sdot, isamax#, sswap, sscal, saxpy, and scopy routines
from the blas package. The blas package is LINKed to the program, but
it could, and should, be placed on EPROM.
Basic Linear Algebra Subroutines, BLAS
The BLAS were originally written for the Fortran language to speed
execution and streamline code used for solving linear algebra and other
matrix problems. The LINPACK routines, Ref. 3, use the BLAS and are
perhaps the best known. The idea is that the BLAS routines will be
highly optimized for a particular computer, coded in ML or a High Order
Language. Some operating systems even include BLAS like routines.
Writing fast efficient programs is then a simple matter of selecting the
best solution algorithm and coding it in a manner that makes best use of
the blas routines. There are blas routines for single precision, double
precision, and complex numbers. The level 1 BLAS perform operations on
rows or columns of an array and typicaly do n scalar operations
replacing the inner most loop of code. There are also level 2 BLAS that
perform n*n operations and Level 3 BLAS that perform n*n*n operations.
Nicholas Higham has coded most of the single precision level 1 blas
routines and put them in a Comal 2.0 package. The Comal blas package is
included on the Packages Library Volume 2 disk. I am not aware of ML
blas routines coded for any other C64/128 languages although this is
certainly possible and recommended.
The Comal blas routines behave exactly the same way that the Fortran
blas routines do except that Fortran can pass the starting address of an
array with just "a", while Comal requires "a(1)". The Comal blas will
allow you pass an array, by reference, of single or multiple dimensions
and start from any position in the array. If you code the blas routines
as ordinary Comal routines you have to pass additional parameters and
have separate routines for single dimensioned arrays and two dimensional
arrays. Note also that Fortran stores two dimensional arrays by
columns, and Comal (like many other languages) stores two dimensional
arrays by rows. If you translate code between Fortran and Comal using
blas routines you will have to change the increment variables.
Fortran Comal
dimension c(n), a(ilda,isda) DIM c(n#), a(lda#,sda#)
scopy(n,c,1,a(i,1),ilda) scopy(n#,c(1),1,a(i#,1),1)
scopy(n,c,1,a(1,j),1) scopy(n#,c(1),1,a(1,j#),sda#)
The first scopy copies array c into the ith row of array a. The second
scopy copies array c into the jth column of array a.
This is what scopy does in Fortran:
subroutine scopy(n,sx,incx,sy,incy)
real sx(1),sy(1)
ix=1
iy=1
do 10 i = 1,n
sy(iy) = sx(ix)
ix = ix + incx
iy = iy + incy
10 continue
return
end
The Comal BLAS does exactly the same thing. If coded entirely in COMAL
rather than as a package it would have to be different. The call would
change.
scopy(n#,c(1),1,a(1,j#),sda#) would have to become,
scopy(n#,c(),1,1,a(,),1,j#,sda#,sda#) and the Comal procedure might be:
PROC scopy(n#, REF x(), ix#, incx#, REF y(,), iy#, jy#, sdy#, incy#) CLOSED
iyinc#:=incy# DIV sdy# //assuming y is dimensioned y(?,sdy#)
jyinc#:=incy# MOD sdy#
FOR i#=1 TO n# DO
y(iy#,jy#):=x(ix#)
ix#:+incx#; iy#:+iyinc#; jy#:+jyinc#
ENDFOR
ENDPROC scopy
Note that more information has to be passed to the procedure and used
that the ML blas picks up automatically. Also we would need separate
procedures to handle every combination of single and multi dimensional
arrays. The Comal ML blas are indeed wonderful. For speed
considerations this should also be left as an open procedure or better
yet just use in line code.
Here is a very simplified description of what each of the routines in
the Comal BLAS package does.
sum:=sasum(n#,x(1),1) Returns sum of absolute values in x().
sum:=0
FOR i#:=1 TO n# DO sum:+ABS(x(i#))
saxpy(n#,sa,x(1),1,y(1),1) Add a multiple of x() to y().
FOR i#:=1 TO n# DO y(i#):+sa*x(i#)
prod:=sdot(n#,x(1),1,y(1),1) Returns dot product of x() and y().
prod:=0
FOR i#:=1 TO n# DO prod:+x(i#)*y(i#)
sswap(n#,x(1),1,y(1),1) Swaps x() and y().
FOR i#:=1 TO n# DO t:=x(i#); x(i#):=y(i#); y(i#):=t
scopy(n#,x(1),1,y(1),1) Copy x() to y().
For i#:=1 TO n# DO y(i#):=x(i#)
max#:=isamax#(n,x(1),1) Returns index of the element of x() with the
largest absolute value.
t:=0; max#:=1
FOR i#:=1 TO n#
IF ABS(x(i#))>t THEN t:=ABS(x(i#)); max#:=i#
ENDFOR i#
sscal(n#,sa,x(1),1) Scale x() by a constant sa.
FOR i#:=1 TO n# DO x(i#):=sa*x(i#)
snrm2(n#,x(1),1) Returns the 2 norm of x().
norm2:=0
FOR i#:=1 TO n# DO norm2:+x(i#)*x(i#)
norm2:=SQR(norm2)
srot(n#,x(1),1,y(1),1,c,s) Apply Givens rotation.
FOR i#:=1 TO n# DO
t:=c*x(i#) + s*y(i#)
y(i#):=s*x(i#) + c*y(i#)
x(i#):=t
ENDFOR i#
Bear in mind that each of these simple examples can be more complex as
was given for scopy. You now have enough information to write your own
BLAS routines in ML or the programming language of your choice, or to
expand the BLAS routine calls in slv to ordinary in line code.
You can also apply the BLAS routines in creative ways besides just
operating on rows or columns. For example you could create the identity
matrix with:
DIM a(n#,n#)
a(1,1):=1; a(1,2):=0
scopy(n#*n#-2,a(1,2),0,a(1,3),1) // zero the rest of the matrix
scopy(n#-1,a(1,1),0,a(2,2),n#+1) // copy ones to the diagonal.
References
1. Zambardino, R. A., "Solutions of Systems of Linear Equations with
Partial Pivoting and Reduced Storage Requirements", The Computer Journal
Vol. 17, No. 4, 1974, pp. 377-378.
2. Orden A., "Matrix Inversion and Related Topics by Direct Methods",
in Mathematical Methods for Digital Computers, Vol. 1, Edited by A.
Ralston and H. Wilf, John Wiley and Sons Inc., 1960.
3. Dongarra, J. J., Moeler, C. B., Bunch, J. R., Stewart, G. W.,
Linpack Users' Guide, SIAM Press, Philadelphia, 1979.
========================================================================
The World of IRC - A New Life for the C64/128
by Bill Lueck (coolhand on IRC)
1) Introduction
With the mysterious and magnificent world of the Internet growing
at an astounding rate - like doubling every year - readers of this
magazine should find that the Internet is actually available to them now -
or at least very soon. In fact, most readers of C= Hacking probably
get there copies of this magazine on the Internet.
The Internet is not simple. It has complexities and intricacies that
can baffle the most erudite and experienced computer scientists in the
world. But, for the purposes of this article, maybe you can just accept
that the Internet is a worldwide connection of data lines that let
computers all over the world talk to each other.. and more importantly,
that allow the PEOPLE using the computers all over the world to talk to
other computers.. and to talk to other PEOPLE! Here, then, lies the
foundation for IRC: it is the mechanism on the Internet that allows
PEOPLE to talk to other PEOPLE.
2) Getting on the Net
If you obtained this magazine via the Internet, then you have passed
Step 1 (finding a site)! If you do not have access to the Internet
(and have not tried), then you need to look around. Possible sites may
be a college/university, your employer (use with care), or a commercial
provider.
If you are enrolled in college, then you probably have an account, or
you may be entitled to one, with no or little cost. The policies on
student accounts vary a lot from institution to institution, and from
country to country. But check into it.. it is one of the most common
methods of Internet access.
If you are employed, and your company has access to the Internet, it
may be possible for you to use their facilities. Just a word of
caution - make sure that it is ok with your employer to use his
facilities... and not on "company time".
Another way that is becoming increasingly more common is to use
commercial "Internet providers". These are companies whose sole
purpose is to offer you an "account" and give you access to the
Internet. The cost, time on line, storage, access, etc., can vary
greatly.. you must shop around a bit.. if you have this choice at
all.. for the best deal.
These commercial sites are not always easy to find. There may be
several commercial providers in an area, but, strangely, they tend not
to advertise. Word-of-mouth through friends, BBSs, or User Groups seem
to be the best way to locate the site possibilities. But they CAN
provide a very good solution.
Another variation on commercial sites are national companies such as
Compuserve, Genie, America Online and Delphi. They provide varying degrees of
access.. and possibly at somewhat higher costs than local providers.
But, again, it is another option.
There is MUCH to do on the Internet, once you have access to it: telnet,
ftp, usenet, archie, gopher, www... These may be just names to you
now.. but the are all fascinating parts of the Internet. But this
article is intended as an introduction to IRC - a fabulous Internet
resource which allows users who have access to a client program called
IRCII (most often invoked as "irc") to talk to each other (and often to
exchange files) in world-wide conversational "channels" (like "party
lines", often called "rooms" on some BBSs). Why is this important to
readers of this magazine? Well, there is a channel for c64/128 users on
IRC called #c-64, a place where c64/128 users are able to meet and
exchange all sorts of information, opinions, and files. More on this
later.
3) The IRC Client
First, to use IRC it is necessary to have access to an IRC client. A
client is a program, usually available on your local site, which
actually interprets and responds to your commands, accepts your typing,
and shows you the conversation on the channel(s) you have joined.
The most common way to access IRC from a site is to use the IRCII
client that your site makes available. This is most often done by
simply typing "irc" at your prompt or invoking the irc option from your
menu if you don't have a shell account. The first thing you will
notice is that your client is attempting to connect to a "server". A
server is a special program, run only on certain sites, that actually
provides the backbone of the IRC network.
Most sites have several servers pre-defined. You should see the client
trying one or more servers until it connects with one.
With Unix irc clients you can define your own unique set of servers by
starting IRC with:
irc nick server1 server2 ... serverN
where "serverX" is the alpha or numeric IP address of the server. This
will automatically set your irc nick (handle) and will establish a
series of servers that your client will switch to if your connection to
IRC gets broken (or if a server is not available when you invoke
"irc").
What is an IP address, you ask? Well, a basic premise of the Internet
is that each computer on the net (at all sites) has a UNIQUE address -
a computer code - that allows other computers to send specific data
just to that computer. In that way, computers can make sure that the
messages and data files that they want (and YOU want) to send to
certain places get to their proper destinations.
IP addresses may be used in an alphabetic or numeric form. In most
cases they can be used interchangeably. So, all irc servers have a
unique alphabetic (and an equivalent numeric) IP address.
Once an IRC session is in progress, Unix users can change servers by
typing:/server newserver where "newserver" is as above, the alpha or
numeric IP address of the server you want to switch to. More on servers
later; but just to mention few now: irc.indiana.edu (midwest);
irc.virginia.edu (east); irc.ctr.columbia.edu (east); irc.math.byu.edu
(west); irc.colorado.edu (midwest); irc.texas.net (southwest). There
are dozens more. Just ask someone on IRC...or do a few /whois nick
commands. You will spot many more.
If your site does not have an irc client, it should be possible to
install one yourself. This means that you need to ftp the source code
for an irc client to your account on your site, make some usually minor
edits, then compile the code in your home directory or a subdirectory
below it.
One good site for obtaining the necessary irc client code is
cs.bu.edu. cd to /irc/clients. Unix users will find the IRCII client
source code in two forms: IRC2.2.9.tar.Z (Unix tar and compress at
471k) or IRC2.2.9.tar.gz (Unix tar and GNU compress at 306k). Both
files are the same (except for the compression). Be sure to use
"BINARY" mode for the ftp transfer.
Move the file to its own subdirectory if you have not ftp'd it to one
already. Then uncompress and untar the file. You should now find a
small subdirectory tree of files. Be sure and read the INSTALL file in
the top subdirectory.
Also in the main subdirectory, there should be two files that need
editing to make the client work with you site. One is "Makefile". In
it there are at least two edits. Make INSTALL_EXECUTABLE the path name
that u want the executable to reside in. This is most often your home
directory or the "bin" subdirectory under your home directory. The
other is IRCII_LIBRARY. Set this to the top subdirectory where the
IRCII code resides. You also must read through the computer system
options and set them for the type of computer and Operating System that
your site uses.
The other file is "config.h". Change the #define DEFAULT_SERVER line
to the alpha or numeric addy of your primary default server. Be sure
to enclose the server in quotes ("server").
For VMS users, there is a subdirectory in "clients" named vms. cd to
it. There are two versions - irc176 and ircII-for-vms. The first is
a more native VMS version, the second is a Unix-like version. They are
both executables, and should run on VMS systems. Try both.. see which
you like best.
Another fairly new area of IRC clients is the personal client, running
on your own computer which would be connected to the Internet through a
version of SLIP or PPP, protocols that move much of the overhead of a
normal Internet provider down to your own machine. There are IRC clients
available for the PC, Amiga, MAC... and even the rumor of one to be
produced for the c64/128. This type of client is expanding very
rapidly and will be a significant option for an ever increasing number
of Internet users.
If you have Telnet only access from your site, there are some sites
which offer a "public" irc client, ones which you can use without
having an account at that site.. sorta like anonymous ftp for those of
you who know what that is. There are drawbacks, though. There are not
many of these public clients, they are often slow in response time, you
cannot exchange files with other users (DCC), and many of the sites are
not always up. Still, it is one possibility that might work for
certain situations. Actually, it is the way that I started on IRC and
used it for several months (my site did not have a local client, and I
did not know how to install one myself).
The public IRC sites I know about now are tiger.itc.univie.ac.at 6668,
sci.dixie.edu 6667, irc.nsysu.edu.tw, and irc.demon.co.uk. They are
not available from all sites, and usage is limited. But try them if
you need to.
Another variation of the "public" options is to apply for a free Unix
account at nyx.cs.du.edu. You will have to be validated, which involves
a little paperwork. But once completed, you will have a FREE Unix
account with full IRC privileges, including DCC file exchange. Of
course, you need a "local" account somewhere with telnet and ftp
privileges, but this is often easier to obtain than an account with all
options locally.
4) Basics of IRC
Well, hopefully, you will now have an Internet site with a method of
accessing IRC. Next, we want to give some tips on using and enjoying
IRC and introduce DCC, the command for transferring files between people
on IRC... and between "bots" and people.
A "bot", you say? Some of you may laugh; sure of course, a bot. What
else is new? But... I remember that it was ages before I finally
figured out.. or someone gave me a clue.. as to what a "bot" really was.
Before we go on, let me give you a VERY brief description of a bot. We
can say that a bot may be a "script", a series of IRC language
statements understood by your IRC client; or it may be a separate
program (typically written in "C"); which, in either case, runs without
any help from its "owner" - YOU.
Instead, a bot is intended to respond to others on IRC who "talk" to it
by "/msg", "/dcc chat", or even "on-channel" commands like "!list" or
"&help". One bot even lists the c64 files it has on-line in response to
someone typing "load "$",8".
What a bot does and how you command it varies a LOT. There really is no
standard way to talk to a bot. Try "/msg <botname>" help as a starting
point and see what happens. Most often there will be instructions that
tell you what to do next. Experiment a little - you will get the hang
of it.
Back to the main plot. The first thing to do after you get connected to
IRC is to choose a "nick". This is the handle that you will be known by
and talked to on IRC. Do this by typing:
/nick <nick>
It's your choice.. unless someone else is already using it. IRC does
not let two people use the same nick at the same time. It will tell you
about this if you try - sometimes in a rather active way - like "kick"
you off. Don't worry - just reconnect.. but try a different nick. Try
just changing the nick a little - like even putting a "1" or "2" behind
it.
Any number of people, however, can use the same nick at different times.
This CAN cause a little confusion.. make sure you know you are talking
to who you think you are.. check a nick's whole address with:
/whois <nick>
Next, you will want to join a channel. Do this by typing:
/join #<channel>
A channel is a logical connection of all IRC users anywhere in the world
that have typed the same /join command. All lines typed to the channel
by anyone on the channel are spread by IRC to all other people who are
on the channel. This is the real power of IRC... a world-wide
"conference" or "party line", where people with the same interests can
communicate with each other.
Because of different delays in different parts of the Internet, all the
lines typed by everyone will not always appear at the same time or even
in the same order at everyone's terminal. This usually does not cause
much of a problem - just be aware that it happens.
If the channel name does not exist at the time you type /join, it will
be created for you! Yes, anyone can "create" a channel. But #c-64 is
almost always there. Give it a try!
After you get on a channel, you can type:
/who *
This will give you a list of who (which nicks) is on the channel and
what their home sites are. This address may or may not be the correct
email address for the nick - so check with the person first (perhaps a
"/msg <nick>" - see below) if you want to email him.
As mentioned before, normal channel conversation is seen by everyone who
has joined the channel. This is great most of the time. Occasionally,
though, you may want to tell just one person (or bot) something that the
entire channel would not want to hear. In this case, use the command:
/msg <nick> <message>
Type it on a line of its own, and just <nick> will see your <message>.
Quite handy for the more "personal" or "specialized" conversations.
Careful, though... use the wrong <nick> or leave out the "/" and people
other than you intended will see your <message>.
If you find you are doing a lot of /msg's to the same nick, try:
/query <nick>
This will put you in a sort of 'permanent' /msg <nick> mode, so that
everything you type that would normally go to the channel will not act
like a "/msg <nick>" preceded it, and it will go just to <nick>. Type
just "/query" to cancel this mode.
Let's jump, now, to /dcc, the command that allows most IRC users to
transfer files. DCC stands for "Direct Client to Client". What it does
is allow two nicks to transfer files *directly* between their sites, not
going through either of their servers. One of the nicks can even be a
bot; IRC does not make a distinction.
When two nicks exchange files, the sender must always start by typing:
/dcc send <nick> <filename>
The recipient will get a message telling what file is being offered and must
type:
/dcc get <nick> [filename]
The [filename] is optional, but must be used if more than one file is to
be transferred simultaneously. Yes, simultaneous transfer of multiple
files CAN be done. Many people do not realize this. Just use the
[filename] option with the "/dcc get" command.
The files that you send and the files that you receive with DCC are
always in the directory you are in when you start IRC. You can type "/cd"
to see what that directory is and you can type:
/cd <pathname>
to change that directory. Or, you can give the absolute or relative
pathname of the file you want to send if it is not in your "local"
directory.
There are often a couple of bots on #c-64 that can give you c-64 files.
"coolhand" is partly a script bot that currently has a lot of c-64 files
available for DCC. If coolhand is on IRC, type:
/msg coolhand xdcc list
to see a list of lists (of files). To see the individual files on list n,
type:
/msg coolhand xdcc list #n
To have coolhand's script dcc you file #n, type:
/msg coolhand xdcc send #n
followed by:
/dcc get coolhand
when you get the dcc offer message.
There are many scripts that you can use that will autoget a file that is
DCC'd to you. The xdcc script that coolhand uses is one such script.
(Yes, coolhand will also autoget a file that you send to it.)
5) What/Who is on IRC?
Ok, now you are on IRC. So what will you find? Who is on the #c-64?
The answers are quite varied.. and constantly changing. I personally
have been on IRC for over 2 years.. (or is it 3?) And I have yet to
ascertain an absolute pattern of people or topics. Frustrating? Well,
maybe to some. But interesting? Yes, most certainly. IRC, and the
#c-64 channel, is a microcosm of the world, with all its variety of
people, personalities, projects, propaganda, and priorities. It is a
capability, a tool for communications, that is unexcelled in its scope
and possibilities.
IRC is totally international, and so is the #c-64 channel. Besides the
U.S. and Canada, Europe is very well represented. There is also a
smaller but increasingly active contingent in Australia, as the net
becomes more accessible there. You will also find a few c-64 users in
S. America, Africa, and Asia. Russia and other former Soviet Union
countries also have a presence. English is the accepted language for
use on #c-64, although you will occasionally see a few other language
used for brief times.
What is the channel used for? Just about anything you can imagine that
normal conversation would be used for. With a special emphasis for the
special interest of most channel participants - the c64/128. For the
most part, almost everyone on the channel has had or still has a c64 or
c128. Some are active users on a real c64/128, while others use one of
the several emulators that exist for various platforms. Many former and
current 64 "scene" members are finding their way to the channel, but all
members of the c64 community are always welcome, and all are treated
equally.
Many people find IRC and #c-64 a very useful way to exchange information
quickly without having to wait for email to pass back and forth. As was
mentioned before, the DCC capability allows for immediate transfer of
files, another quick and effective way to pass information and things
like utilities and coding examples. Such capabilities have encouraged
many people to either return to the c64 or take up using and programming
it for the first time. Yes, the c64 community is actually growing
again, thanks in part to the growing presence of the Internet, IRC, and
#c-64!
So, when you first get on the channel for the first time, don't be
afraid to ask for help. You will probably find that the people on there
are either new themselves, or were once new at one time and had the same
uncertainties and questions that you do. Most everyone is very willing
to help new people. So ask. Also, if you have knowledge or a talent to
offer or a willingness to help somehow, just make that known. The
channel is full of people, some of whom probably need exactly what you
have to give.
A key thing: be patient! When you are new on the channel, you may not
be noticed right away, especially if there are several conversations
already going on. In other cases, you may find that there is really no
one on the channel, except maybe a few bots. So hang in there or come
back a bit later. Believe me, the IS a lot of action on #c-64 most of
the time.
Besides being patient yourself, be patient with other people on the
channel. Like in the non-cyber world, misunderstandings CAN occur, since
your total communication with other people is via the typed word. But
the same rules of courteousness that common society utilizes also apply
on IRC. Treat people with respect and kindness, and they will most
likely respond in a like manner. Sounds like the golden rule? I think
so, and I think you will find that its works pretty well on IRC as it
does in other life.
Hopefully, this article will help you get started enjoying IRC and
particularly #c-64. There's a lot to be gained there... information,
files, and even new friends. It's a way to give our c64 community new
life and spirit. Give it a try! See you there.
*****************
Some of the material in this article was previously published in "Driven"
and is used here by permission.
========================================================================
SwiftLink-232 Application Notes (version 1.0b)
This information is made available from a paper document published by CMD,
with CMD's express written permission. [This version includes a couple of
grammatical corrections and minor changes, plus, the source code has been
debugged and extended by Craig Bruce <csbruce@ccnga.uwaterloo.ca>.]
1. INTRODUCTION
The SwiftLink-232 ACIA cartridge replaces the Commodore Kernal RS-232 routines
with a hardware chip. The chip handles all the bit-level processing now done
in software by the Commodore Kernal. The ACIA may be accessed by polling
certain memory locations in the I/O block ($D000 - $DFFF) or through
interrupts. The ACIA may be programmed to generate interrupts in the
following situations:
1) when a byte of data is received
2) when a byte of data may be transmitted (i.e., the data register is empty)
3) both (1) and (2)
4) never
The sample code below sets up the ACIA to generate an interrupt each time a
byte of data is received. For transmitting, two techniques are shown. The
first technique consists of an interrupt handler which enables transmit
interrupts when there are bytes ready to be sent from a transmit buffer.
There is a separate routine given that manages the transmit buffer. In the
second technique, which can be found at the very end of the sample code,
neither a transmit buffer or transmit interrupts are used. Instead, bytes of
data are sent to the ACIA directly as they are generated by the terminal
program.
NOTE: The ACIA will _always_ generate an interrupt when a change of state
occurs on either the DCD or DSR line (unless the lines are not connected in
the device's cable).
The 6551 ACIA was chosen for several reasons, including the low cost and
compatibility with other Commodore (MOS) integrated circuits. Commodore used
the 6551 as a model for the Kernal software. Control, Command, and Status
registers in the Kernal routines partially mimic their hardware counterparts
in the ACIA.
NOTE: If you're using the Kernal software registers in your program, be sure
to review the enclosed 6551 data sheet carefully. Several of the hardware-
register locations do _not_ perform the same function as their software
counterparts. You may need to make a few changes in your program to
accommodate the differences.
2. BUFFERS
Bytes received are placed in "circular" or "ring" buffers by the sample
routine below, and also by the first sample transmit routine. To keep things
similar to the Kernal RS-232 implementation, we've shown 256-byte buffers.
You may want to use larger buffers for file transfers or to allow more
screen-processing time. Bypassing the Kernal routines free many zero-page
locations, which could improve performance of pointers to large buffers.
If your program already directly manipulates the Kernal RS-232 buffers, you'll
find it very easy to adapt to the ACIA. If you use calls to the Kernal RS-232
file routines instead, you'll need to implement lower-level code to get and
store buffer data.
Briefly, each buffer has a "head" and "tail" pointer. The head points to the
next byte to be removed from the buffer. The tail points to the next free
location in which to store a byte. If the head and tail both point to the
same location, the buffer is empty. If (tail+1)==head, the buffer is full.
The interrupt handler described below will place received bytes at the tail of
the receive buffer. Your program should monitor the buffer, either by
comparing the head and tail pointers (as the Commodore Kernal routines do), or
by maintaining a byte count through the interrupt handler (as the attached
sample does). When bytes are available, your program can process them, move
the head pointer to the next character, and decrement the counter if you use
one.
You should send a "Ctrl-S" (ASCII 19) to the host when the buffer is nearing
capacity. At higher baud rates, this "maximum size" point may need to be
lowered. We found 50 to 100 bytes worked fairly well at 9600 baud. You can
probably do things more efficiently (we were using a _very_ rough
implementation) and set a higher maximum size. At some "maximum size", a
"Ctrl-Q" (ASCII 17) can be sent to the host to resume transmission.
To transmit a byte using the logic of the first transmit routine below, first
make sure that the transmit buffer isn't full. Then store the byte at the
tail of the transmit buffer, point the tail to the next available location,
and increment the transmit buffer counter (if used).
The 6551 transmit interrupt occurs when the transmit register is empty and
available for transmitting another byte. Unless there are bytes to transmit,
this creates unnecessary interrupts and wastes a lot of time. So, when the
last byte is removed from the buffer, the interrupt handler in the first
transmit routine below disables transmit interrupts.
Your program's code that stuffs new bytes into the transmit buffer must
re-enable transmit interrupts, or your bytes may never be sent. A model for a
main code routine for placing bytes into the transmit buffer follows the
sample interrupt handler.
Using a transmit buffer allows your main program to perform other takes while
the NMI interrupt routine takes care of sending bytes to the ACIA. If the
buffer has more than a few characters, however, you may find that most of the
processor time is spent servicing the interrupt. Since the ACIA generates NMI
interrupts, you can't "mask" them from the processor, and you may have timing
difficulties in your program.
One solution is to eliminate the transmit buffer completely. Your program can
decide when to send each byte and perform any other necessary tasks in between
bytes as needed. A model for the main-code routine for transmitting bytes
without a transmit buffer is also shown following the sample interrupt-handler
code. Feedback from developers to date is that many of them have better luck
_not_ using transmit interrupts or a transmit buffer.
Although it's possible to eliminate the receive buffer also, we strongly
advise that you don't. The host computer, not your program, decides when
a new byte will arrive. Polling the ACIA for received bytes instead of
using an interrupt-driven buffer just waste's your program's time and
risks missing data.
For a thorough discussion of the use of buffers, the Kernal RS-232 routines,
and the Commodore NMI handler, see "COMPUTE!'s VIC-20 and Commodore 64 Tool
Kit: Kernal", by Dan Heeb (COMPUTE! Books) and "What's Really Inside the
Commodore 64", by Milton Bathurst (distributed in the US by Schnedler
Systems).
3. ACIA REGISTERS
The four ACIA registers are explained in detail in the enclosed data sheets.
The default location for them in our cartridge is address $DE00--$DE03
(56832--56836).
3.1. DATA REGISTER ($DE00)
This register has dual functionality: it is used to receive and transmit all
data bytes (i.e., it is a read/write register).
Data received by the ACIA is placed in this register. If receive interrupts
are enabled, an interrupt will be generated when all bits for a received
byte have been assembled and the byte is ready to read.
Transmit interrupts, if enabled, are generated when this register is empty
(available for transmitting). A byte to be transmitted can be placed in this
register.
3.2. STATUS REGISTER ($DE01)
This register has dual functionality: it shows the various ACIA settings when
read, but when written to (data = anything [i.e., don't care]), this register
triggers a reset of the chip.
As the enclosed data sheet shows, the ACIA uses bits in this register to
indicate data flow and errors.
If the ACIA generates an interrupt, bit #7 is set. There are four possible
sources of interrupts:
1) receive (if programmed)
2) transmit (if programmed)
3) if a connected device changes the state of the DCD line
4) if a connected device changes the state of the DSR line
Some programmers have reported problems with using bit #7 to verify ACIA
interrupts. At 9600 bps and higher, the ACIA generates interrupts properly,
and bits #3--#6 (described below) are set to reflect the cause of the
interrupt, as they should. But, bit #7 is not consistently set. At speeds
under 9600 bps, bit #7 seems to work as designed. To avoid any difficulties,
the sample code below ignores bit #7 and tests the four interrupt source bits
directly.
Bit #5 indicates the status of the DSR line connected to the RS-232 device
(modem, printer, etc.), while bit #6 indicates the status of the DCD line.
NOTE: The function of these two bits is _reversed_ from the standard
implementation. Unlike many ACIAs, the 6551 was designed to use the DCD
(Data Carrier Detect) signal from the modem to activate the receiver section
of the chip. If DCD is inactive (no carrier detected), the modem messages
and echos of commands would not appear on the user's screen. We wanted the
receiver active at all times. We also wanted to give the you access to the
DCD signal from the modem. So, we exchanged the DCD and DSR signals at the
ACIA. Both lines are pulled active internally by the cartridge if left
unconnected by the user (i.e., in an null-modem cable possibility).
Bit #4 is set if the transmit register is empty. Your program must monitor
this bit and not write to the data register until the bit i sset (see the
sample XMIT code below).
Bit #3 is set if the receive register is full.
Bits #2, #1, and #0, when set, indicate overrun, framing, and parity errors in
received bytes. The next data byte received erases the error information for
the preceding byte. If you wish to use these bits, store them for processing
by your program. The sample code below does not implement any error checking,
but the Kernal software routines do, so adding features to your code might be
a good idea.
3.3. COMMAND REGISTER ($DE02)
The Command Register control parity checking, echo mode, and transmit/receive
interrupts. It is a read/write register, but reading the register simply
tells you what the settings of the various parameters are.
You use bits #7, #6, and #5 to choose the parity checking desired.
Bit #4 should normally be cleared (i.e., no echo)
Bits #3 and #2 should reflect whether or not you are using transmit
interrupts, and if so, what kind. In the first sample transmit routine below,
bit #3 is set and bit #2 is cleared to disable transmit interrupts (with RTS
low [active]) on startup. However, when a byte is placed in the transmit
buffer, bit #3 is cleared and bit #2 is set to enable transmit interrupts
(with RTS low). When all bytes in the buffer have been transmitted, the
interrupt handler disables transmit interrupts. NOTE: If you are connected to
a RS-232 device that uses CTS/RTS handshaking, you can tell the device to stop
temporarily by bringing RTS high (inactive): clear both bits #2 and #3.
Bit #1 should reflect whether or not you are using receive interrupts. In
the sample code below, it is set to enable receive interrupts.
Bit #0 acts as a "master control switch" for all interrupts on the chip
itself. It _must_ be set to enable any interrupts -- if it is cleared, all
interrupts are turned off and the receiver section of the chip is disabled.
This bit also pulls the DTR line low to enable communication with the
connected RS-232 device. Clearing this bit causes most Hayes-compatible
modems to hang up (by bringing DTR high). This bit should be cleared when a
session is over and the user exits the terminal program to insure that no
spurious interrupts are generated. One fairly elegant way to do this is to
perform a software reset of the chip (writing any value to the Status
register).
NOTE: In the figures on the 6551 data sheet, there are small charts at the
bottom of each of the labelled "Hardware Reset/Program Reset". These charts
indicate what values the bits of these registers contain after a hardware
reset (like toggling the computer's power) and a program reset (a write to the
Status register).
3.4. CONTROL REGISTER ($DE03)
You use this register to control the number of stop bits, the word length,
switch on the internal baud-rate generator, and set the baud rate. It is a
read/write register, but reading the register simply tells you what the
various parameters are. See the figure in the data sheet for a complete list
of parameters.
Be sure that bit #4, the "clock source" bit, is always set to use the on-chip
crystal-controlled baud-rate generator.
You use the other bits to choose the baud rate, word length, and number of
stop bits. Note that our cartridge uses a double-speed crystal, so values
given on the data sheet are doubled [this is how they are shown below] (the
minimum speed is 100 bps and the maximum speed is 38,400 bps).
4. ACIA HARDWARE INTERFACING
The ACIA is mounted on a circuit board designed to plug into the expansion
(cartridge) port. The board is housed in a cartridge shell with a male DB-9
connector at the rear. The "IBM(R) PC/AT(TM) standard" DB-9 RS-232 pinout is
implemented. Commercial DB-9 to DB-25 patch cords are readily available, and
are sold by us as well.
Eight of the nine lines from the AT serial port are implemented: TxD, RxD,
DTR, DSR, RTS, CTS, DCD, & GND. RI (Ring Indicator) is not implemented
because the 6551 does not have a pin to handle it. CTS and RTS are not
normally used by 2400 bps or slower Hayes-compatible modems, but these lines
are being used by several newer, faster modems (MNP modems in particular).
Note that although CTS is connected to the 6551, there is no way to monitor
what state it is -- the value does not appear in any register. The 6551
handles CTS automatically: if it is pulled high (inactive) by the connected
RS-232 device, the 6551 stops transmitting (clears the "transmit data register
empty" bit [#4] in the status register).
The output signals are standard RS-232 level compatible. We've tested units
with several commercial modems and with various computers using null-modem
cables up to 38,400 bps without difficulties. In addition, there are pull-up
resistors on three of the four input lines (DCD, DSR, CTS) so that if these
pins are not connected in a cable, those three lines will pull to the active
state. For example, if you happen to use a cable that is missing the DCD
line, the pull-up resistor will pull the line active, so that bit #6 in the
status register would be cleared (DCD is active low).
An on-board crystal provides the baud rate clock signal, with a maximum of
38.4 Kbaud, because we are using a double-speed crystal. If possible, test
your program at 38.4 Kbaud as well as lower baud rates. Users may find this
helpful for local file transfers using the C-64/C-128 as a dumb terminal on
larger systems. And, after all, low-cost 28.8 Kb modems for the masses are
just around the corner.
Default decoding for the ACIA addresses is done by the I/O #1 line (pin 7) on
the cartridge port. This line is infrequently used on either the C-64 or
C-128 and should allow compatibility with most other cartridge products,
including the REU. The circuit board also has pads for users with special
needs to change the decoding to I/O #2 (pin 10). This change moves the ACIA
base address to $DF00, making it incompatible with the REU.
C-128 users may also elect to decode the ACIA at $D700 (this is a SID-chip
mirror on the C-64). Since a $D700 decoding line is not available at the
expansion port, the user would need to run a clip lead into the computer and
connect to pin 12 of U2 (a 74LS138). We have tried this and it works. $D700
is an especially attractive location for C-128 BBS authors, because putting
the SwiftLink there will free up the other two memory slots for devices that
many BBS sysops use: IEEE and hard-drive interfaces.
Although we anticipate relatively few people changing ACIA decoding, you
should allow your software to work with a SwiftLink at any of the three
locations. You could either (1) test for the ACIA automatically by writing a
value to the control register and then attempting to read it back or (2)
provide a user-configurable switch/poke/menu option.
The Z80 CPU used for CP/M mode in the C-128 is not connected to the NMI line,
which poses a problem since the cleanest software interface for C-64/C-128-
mode programming is with this interrupt. We have added a switch to allow the
ACIA interrupt to be connected to either NMI or IRQ, which the Z80 does use.
The user can move this switch without opening the cartridge.
5. SAMPLE CODE
This section has been translated into ACE-assembler format. Cut on the dotted
lines to extract the code, and assemble it using the ACE assembler (ACE is a
public-domain program). This program will work on both the C64 and C128.
To use from BASIC:
LOAD"SAMPLE",8,1
SYS8192
It is a very simple terminal program. Press the STOP key to exit from it.
%%%---8<---cut-here---8<---%%%
;Sample NMI interrupt handler for 6551 ACIA on Commodore 64/128
;(c) 1990 by Noel Nyman, Kent Sullivan, Brian Minugh,
;Geoduck Development Systems, and Dr. Evil Labs.
; ---=== EQUATES ===---
base = $DE00 ;base ACIA address
data = base
status = base+1
command = base+2
control = base+3
;Using the ACIA frees many addresses in zero page normally used by
;Kernel RS-232 routines. The addresses for the buffer pointers were
;chosen arbitrarily. The buffer vector addresses are those used by
;the Kernal routines.
rhead = $A7 ;pointer to next byte to be removed from
;receive buffer
rtail = $A8 ;pointer to location to store next byte received
rbuff = $F7 ;receive-buffer vector
thead = $A9 ;pointer to next byte to be removed from
;transmit buffer
ttail = $AA ;pointer to location to store next byte
;in transmit buffer
tbuff = $F9 ;transmit buffer
xmitcount = $AB ;count of bytes remaining in transmit (xmit) buffer
recvcount = $B4 ;count of bytes remaining in receive buffer
errors = $B5 ;DSR, DCD, and received data errors information
xmiton = $B6 ;storage location for model of command register
;which turn both receive and transmit interrupts on
xmitoff = $BD ;storage location for model of command register
;which turns the receive interrupt on and the
;transmit interrupts off
NMINV = $0318 ;Commodore Non-Maskable Interrupt vector
OLDVEC = $03fe ;innocuous location to store old NMI vector (two bytes)
; ---=== INITIALIZATION ===---
;Call the following code as part of system initialization.
;clear all buffer pointers, buffer counters, and errors location
org $2000 ;change to suit your needs
lda #$00
sta rhead
sta rtail
sta thead
sta ttail
sta xmitcount
sta recvcount
sta errors
;store the addresses of the buffers in the zero-page vectors
lda #<TRANSMIT_BUFFER
sta tbuff
lda #>TRANSMIT_BUFFER
sta tbuff + 1
lda #<RECEIVE_BUFFER
sta rbuff
lda #>RECEIVE_BUFFER
sta rbuff + 1
;the next four instructions initialize the ACIA to arbitrary values.
;These could be program defaults, or replaced by code that picks up
;the user's requirements for baud rate, parity, etc.
;The ACIA "control" register controls stop bits, word length, the
;choice of internal or external baud-rate generat
or, and the baud
;rate when the internal generator is used. The value below sets the
;ACIA for one stop bit, eight-bit word length, and 4800 baud using the
;internal generator.
; .------------------------- 0 = one stop bit
; :
; :.-------------------- word length, bits 6-7
; ::.------------------- 00 = eight-bit word
; :::
; :::.------------- clock source, 1 = internal generator
; ::::
; :::: .----- baud
; :::: :.---- rate
; :::: ::.--- bits ;1010 == 4800 baud, change to what you want
; :::: :::.-- 0-3
lda #%0001_1010
sta control
;The ACIA "command" register controls the parity, echo mode, transmit and
;receive interrupt enabling, hardware "BRK", and (indirectly) the "RTS"
;and "DTR" lines. The value below sets the ACIA for no parity check,
;no echo, disables transmit interrupts, and enables receive interrupts
;(RTS and DTR low).
; .------------------------- parity control,
; :.------------------------ bits 5-7
; ::.----------------------- 000 = no parity
; :::
; :::.------------------- echo mode, 0 = normal (no echo)
; ::::
; :::: .----------- transmit interrupt control, bits 2-3
; :::: :.---------- 10 = xmit interrupt off, RTS low
; :::: ::
; :::: ::.------ receive interrupt control, 0 = enabled
; :::: :::
; :::: :::.--- DTR control, 1=DTR low
lda #%0000_1001
sta command
;Besides initialization, also call the following code whenever the user
;changes parity of echo mode.
;It creates the "xmitoff" and "xmiton" models used by the interrupt
;handler and main-program transmit routine to control the ACIA
;interrupt enabling. If you don't change the models' parity bits,
;you'll revert to "default" parity on the next NMI.
;initialize with transmit interrupts off since
;buffer will be empty
sta xmitoff ;store as a model for future use
and #%1111_0000 ;mask off interrupt bits, keep parity/echo bits
ora #%0000_0101 ;and set bits to enable both transmit and
;receive interrupts
sta xmiton ;store also for future use
;The standard NMI routine tests th <RESTORE> key, CIA #2, and checks
;for the presence of an autostart cartridge.
;You can safely bypass the normal routine unless:
; * you want to keep the user port active
; * you want to use the TOD clock in CIA #2
; * you want to detect an autostart cartridge
; * you want to detect the RESTOR key
;
;If you need any of these functions, you can wedge the ACIA
;interrupt handler in ahead of the Kernal routines. It's probably
;safer to replicate in your own program only the Kernal NMI functions
;that you need. We'll illustrate bypassing all Kernal tests.
;BE SURE THE "NEWNMI" ROUTINE IS IN PLACE BEFORE EXITING THIS CODE!
;A "stray" NMI that occurs after the vector is changed to NEWNMI's address
;will probably cause a system crash if NEWNMI isn't there. Also, it would
;be best to initialize the ACIA to a "no interrupts" state until the
;new vector is stored. Although a power-on reset should disable all
;ACIA interrupts, it pays to be sure.
;If the user turns the modem off and on, an interrupt will probably be
;generated. At worst, this may leave a stray character in teh receive
;buffer, unless you don't have NEWNMI in place.
NEWVEC:
sei ;A stray IRQ shouldn't cause any problems
;while we're changing the NMI vector, but
;why take chances?
;If you want all the normal NMI tests to occur after the ACIA check,
;save the old vector. If you don't need the regular stuff, you can
;skip the next four lines. Note that the Kernal NMI routine pushes
;the CPU registers to the stack. If you call it at the normal address,
;you should pop the registers first (see EXITINT below).
lda NMINV ;get low byte of present vector
sta OLDVEC ;and store it for future use
lda NMINV+1 ;do the same
sta OLDVEC+1 ;with the high byte
;come here from the SEI if you're not saving
;the old vector
lda #<NEWNMI ;get low byte of new NMI routine
sta NMINV ;store in vector
lda #>NEWNMI ;and do the same with
sta NMINV+1 ;the high byte
cli ;allow IRQs again
;continue initializing your program
; ::: :::::: ;program initialization continues
jmp TERMINAL ;go to the example dumb-terminal subroutine
;Save two bytes to store the old vector only if you need it
; ---=== New NMI Routine Starts Here ===---
;The code below is a simple interrupt patch to control the ACIA. When
;the ACIA generates an interrupt, this routine examines the status
;register which contains the following data.
; .---------------------------- high if ACIA caused interrupt;
; : not used in code below
; :
; :.------------------------- reflects state of DCD line
; ::
; ::.---------------------- reflects state of DSR line
; :::
; :::.------------------ high if xmit-data register is empty
; ::::
; :::: .--------------- high if receive-data register full
; :::: :
; :::: :.----------- high if overrun error
; :::: ::
; :::: ::.------- high if framing error
; :::: :::
; :::: :::.--- high if parity error
; status xxxx_xxxx
NEWNMI:
; sei ;the Kernal routine already does this before jumping
;through the NMINV vector
pha ;save A register
txa
pha ;save X register
tya
pha ;save Y register
;As discussed above, the ACIA can generate an interrupt from one of four
;different sources. We'll first check to see if the interrupt was
;caused by the receive register being full (bit #3) or the transmit
;register being empty (bit #4) since these two activities should receive
;priority. A BEQ (Branch if EQual) tests the status register and branches
;if the interrupt was not caused by the data register.
;Before testing for the source of the interrupt, we'll prevent more
;interrupts from the ACIA by disabling them at the chip. This prevents
;another NMI from interrupting this one. (SEI won't work because the
;CPU can't disable non-maskable interrupts).
;At lower baud rates (2400 baud and lower) this may not be necessary. But,
;it's safe and doesn't take much time, either.
;The same technique should be used in parts of your program where timing
;is critical. Disk access, for example, uses SEI to mask IRQ interrupts.
;You should turn off the ACIA interrupts during disk access also to prevent
;disk errors and system crashes.
;First, we'll load the status register which contains all the interrupt
;and any received-data error information in the 'A' register.
lda status
;Now prevent any more NMIs from the ACIA
ldx #%0000_0011 ;disable all interrupts, bring RTS inactive, and
;leave DTR active
stx command ;send to ACIA-- code at end of interrupt handler
;will re-enable interrupts
;Store the status-register data only if needed for error checking.
;The next received byte will clear the error flags.
; sta errors ;only if error checking implemented
and #%0001_1000 ;mask out all but transmit and
;receive interrupt indicators
;If you don't use a transmit buffer you can use
;
; and #%0000_1000
;
;to test for receive interrupts only and skip the receive test shown
;below.
beq TEST_DCD_DSR
;if the 'A' register=0, either the interrupt was not caused by the
;ACIA or the ACIA interrupt was caused by a change in the DCD or
;DSR lines, so we'll branch to check those sources.
;If your program ignores DCD and DSR, you can branch to
;the end of the interrupt handler instead:
;
; beq NMIEXIT
;
;Test the status register information to see if a received byte is ready
;If you don't use a transmit buffer, skip the next two instructions.
RECEIVE: ;process received byte
and #%0000_1000 ;mask all but bit #3
beq XMITCHAR ;if not set, no received byte - if you're using
;a transmit buffer, the interrupt must have been
;caused by transmit. So, branch to handle.
lda data ;get received byte
ldy rtail ;index to buffer
sta (rbuff),y ;and store it
inc rtail ;move index to next slot
inc recvcount ;increment count of bytes in receive buffer
;(if used by your program)
;Skip the "XMIT" routines below if you decide not to use a transmit buffer.
;In that case, the next code executed starts at TEST_DCD_DSR or NMIEXIT.
;After processing a received byte, this sample code tests for bytes
;in the transmit buffer and sends on if present. Note that, in this
;sample, receive interrupts take precedence. You may want to reverse the
;order in your program.
;If the ACIA generated a transmit interrupt and no received byte was
;ready, status bit #4 is already set. The ACIA is ready to accept
;the byte to be transmitted and we've branched directly to XMITCHAR below.
;If only bit #3 was set on entry to the interrupt handler, the ACIA may have
;been in the process of transmitting the last byte, and there may still be
;characters in the transmit buffer. We'll check for that now, and send the
;next character if there is one. Before sending a character to the ACIA to
;be transmitted, we must wait until bit #4 of the status register is set.
XMIT:
lda xmitcount ;if not zero, characters still in buffer
;fall through to process xmit buffer
beq TEST_DCD_DSR ;no characters in buffer-- go to next check
;or
;
; beq NMIEXIT
;
;if you don't check DCD or DSR in your program.
XMITBYTE:
lda status ;test bit #4
and #%00010000
beq TEST_DCD_DSR ;skip if transmitter still busy
XMITCHAR: ;transmit a character
ldy thead
lda (tbuff),y ;get character at head of buffer
sta data ;place in ACIA for transmit
;point to next character in buffer
inc thead ;and store new index
dec xmitcount ;subtract one from count of bytes
;in xmit buffer
lda xmitcount
beq TEST_DCD_DSR
;or
;
; beq NMIEXIT
;
;if you don't check DCD or DSR in your program
;If xmitcount decrements to zero, there are no more characters to
;transmit. The code at NMIEXIT turns ACIA transmit interrupts off.
;If there are more bytes in the buffer, set up the 'A' register with
;the model that turns both transmit and receive interrupts on. We felt
;that was safer, and not much slower, than EORing bits #3 and #4. Note
;that the status of the parity/echo bits is preserved in the way "xmiton"
;and "xmitoff" were initialized earlier.
lda xmiton ;model to leave both interrupts enabled
;If you don't use DCD or DSR
bne NMICOMMAND ;branch always to store model in command register
;If your program uses DCD and/or DSR, you'll want to know when the state
;of those lines changes. You can do that outside the interrupt handler
;by polling the ACIA status register, but if either of the lines changes,
;the chip will generate an NMI anyway. So, you can let the interrupt
;handler do teh work for you. The cost is the added time required to
;execute the DCD_DSR code on each NMI.
TEST_DCD_DSR:
; pha ;only if you use a transmit buffer, 'A' holds
;the proper mask to re-enable interrupts on
;the ACIA
; ::
; :: ;appropriate code here to compare bit #6 (DCD)
; :: ;and/or bit #5 (DSR) with their previous states
; :: ;which you've already stored in memory and take
; :: ;appropriate action
; ::
; pla ;only if you pushed it at the start of the
;DCD/DSR routine
; bne NMICOMMAND ;'A' holds the xmiton mask if it's not zero,
;implying that we arrived here from xmit routine
;not used if you're not using a transmit buffer.
;If the test for ACIA interrupt failed on entry to the handler, we branch
;directly to here. If you don't use additional handlers, the RESTORE key
;(for example) will fall through here and have no effect on your program
;or the machine, except for some wasted cycles.
NMIEXIT:
lda xmitoff ;load model to turn transmit interrupts off
;and this line sets the interrupt status to whatever is in the 'A' register.
NMICOMMAND:
sta command
;That's all we need for the ACIA interrupt handler. Since we've pushed the
;CPU registers to the stack, we need to pop them off. Note that you must
;do this EVEN IF YOU JUMP TO THE KERNAL HANDLER NEXT, since it will push
;them again immediately. You can skip this step only if you're proceeding
;to a custom handler.
EXITINT: ;restore things and exit
pla ;restore 'Y' register
tay
pla ;restore 'X' register
tax
pla ;restore 'A' register
;If you want to continue processing the interrupt with the Kernal routines,
jmp (OLDVEC) ;continue processing interrupt with Kernal handler
;Or, if you add your own interrupt routine,
; jmp YOURCODE ;continue with your own handler
;If you use your own routine, or if you don't add anything, BE SURE to do
;this last (C64 only):
; rti ;return from interrupt instruction
;to restore the flags register the CPU pushes to the stack before jumping
;to the Kernal code. It also returns you to the interrupted part of
;your program
;-----------------------------------------------------------------------------
;Sample routine to store a character in the buffer to be transmitted
;by the ACIA.
;(c) 1990 by Noel Nyman, Kent Sullivan, Brian Minugh,
;Geoduck Developmental Systems, and Dr. Evil Labs.
;Assumes the character is in the 'A' register on entry. Destroys 'Y'--
;push to stack if you need to preserve it.
SENDBYTE: ;adds a byte to the xmit buffer and sets
;the ACIA to enable transmit interrupts (the
;interrupt handler will disable them again
;when the buffer is empty)
ldy xmitcount ;count of bytes in transmit buffer
cpy #255 ;max buffer size
beq NOTHING ;buffer is full, don't add byte
ldy ttail ;pointer to end of buffer
sta (tbuff),y ;store byte in 'A' at end of buffer
inc ttail ;point to next slot in buffer
inc xmitcount ;and add one to count of bytes in buffer
lda xmiton ;get model for turning on transmit interrupts
sta command ;tell ACIA to do it
rts ;return to your program
NOTHING:
lda #$00 ;or whatever flag your program uses to tell that the
;byte was not transmitted
rts ;and return
;Alternative routine to transmit a character from main program when not using
;a transmit buffer.
;
;(c) 1990 by Noel Nyman, Kent Sullivan, Brian Minugh,
;Geoduck Developmental Systems, and Dr. Evil Labs.
;
;Assumes the character to be transmitted is in the 'A' register on entry.
;Destroys 'Y'; push to stack if you need to preserve it.
;
;SENDBYTE:
; tay ;remember byte to be transmitted
;
;TESTACIA:
; lda status ;bit #4 of the status register is set if
; ;the ACIA is ready to transmit another byte,
; ;even if transmit interrupts are disabled.
; and #%0001_0000
; beq TESTACIA ;wait for bit #4 to be set
; sty data ;give byte to ACIA
; rts
;Sample routine to fetch a character that has been received, from the
;receive buffer.
;by Craig Bruce, 1995, adapted from above
;Will return the character in the 'A' register and the carry flag cleared if
;a character was available. If no character was available, will return with
;the carry flag set. Destroys the 'Y' register.
RECVBYTE: ;fetches a byte from the receive buffer.
;there is no need to fiddle with any interrupts
lda recvcount ;count of bytes in receive buffer
beq RECVEMPTY ;buffer is empty, indicate to caller
ldy rhead ;pointer to start of buffer
lda (rbuff),y ;fetch byte out of buffer into 'A' register
inc rhead ;point to next slot in buffer
dec recvcount ;and add one to count of bytes in buffer
clc ;indicate that we have a character
rts ;return to your program
RECVEMPTY:
sec ;or whatever flag your program uses to tell that the
;receive buffer was empty
rts ;and return
;-----------------------------------------------------------------------------
;Dumb -- very dumb -- terminal emulator. Simply polls the receive buffer and
;the keyboard and puts received data to the screen and typed data to the send
;buffer (thus, it assumes a full-duplex, echoing link). There is no
;PETSCII->ASCII conversion, no cursor, nor any other fancy features. Press
;STOP to exit.
;
;by Craig Bruce, 1995.
TERMINAL:
jsr RECVBYTE ;see if there is a received byte in the recv buffer
bcs TERMTRYSEND ;if not, continue
jsr $FFD2 ;if received byte, print it to the screen (CHROUT)
TERMTRYSEND:
jsr $FFE4 ;try to get a character from the keyboard (GETIN)
cmp #$00 ;was there a keystroke available?
beq TERMINAL ;no--go back to top of polling loop
cmp #$03 ;check for STOP key
beq TERMEXIT ; exit if pressed
jsr SENDBYTE ;have char--put it into the transmit buffer and then
jmp TERMINAL ; go back to top of polling loop
TERMEXIT:
lda #%0000_0010 ;disable transmitter and receiver and all interrupts
sta command
sei
lda OLDVEC ;restore the NMI vector to its original value
sta NMINV
lda OLDVEC+1
sta NMINV+1
cli
rts ;exit
TRANSMIT_BUFFER = *+0
RECEIVE_BUFFER = *+256
%%%---8<---cut-here---8<---%%%
------------------------------------------------------------------------------
APPENDIX: 6551 ACIA HARDWARE SPECS (DATA SHEET)
C= Commodore Semiconductor Group
a division of Commodore Business Machines, Inc.
950 Rittenhouse Road, Nornstown, PA 19400 * 215/666-7950 * TWX 510-660-4168
(July 1987)
6551 ASYNCHRONOUS COMMUNICATION INTERFACE ADAPTER
CONCEPT:
The 6551 is an Asynchronous Communication Adapter (ACIA) intended to provide
for interfacing the 6500/6800 microprocessor families to serial communication
data sets and modems. A unique feature is the inclusion of an on-chip
programmable baud-rate generator, with a crystal being the only external
component required.
FEATURES:
* On-chip baud-rate generator: 15 programmable baud rates derived from a
standard standard 1.8432 MHz external crystal (50 to 19,200 baud) [these
rates are doubled in the SwiftLink].
* Programmable interrupt and status register to simplify software design.
* Single +5 volt power supply.
* Serial echo mode.
* False start bit detection.
* 8-bit bi-directional data bus for direct communication with the
microprocessor.
* External 16x clock input for non-standard baud rates (up to 125 Kbaud).
* Programmable: word lengths; number of stop bits; and parity-bit generation
and detection.
* Data set and modem control signals provided.
* Parity: (odd, even, none, mark, space).
* Full-duplex or half-duplex operation.
* 5,6,7 and 8-bit transmission.
* 1-MHz, 2-MHz, and 3-MHz operation.
ORDER NUMBER
MXS 6551 ___
- |
| +---- Frequency range
| Plain = 1 MHz
| A = 2 MHz
| B = 3 MHz
|
+----------- Package Designator
C = Ceramic
P = Plastic
6551 PIN CONFIGURATION
+---------------+
GND --| 1 28 |-- R-/W
CS0 --| 2 27 |-- o2
/CS1 --| 3 26 |-- /IRQ
/RES --| 4 25 |-- DB7
RxC --| 5 24 |-- DB6
XTAL1 --| 6 23 |-- DB5
XTAL2 --| 7 22 |-- DB4
/RTS --| 8 21 |-- DB3
/CTS --| 9 20 |-- DB2
TxD --| 10 19 |-- DB1
/DTR --| 11 18 |-- DB0
RxD --| 12 17 |-- /DSR
RS0 --| 13 16 |-- /DCD
RS1 --| 14 15 |-- Vcc
+---------------+
BLOCK DIAGRAM +----------+
| TRANSMIT |
| CONTROL |<------- CTS
+----------+
|
v
+----------+ +----------+
| TRANSMIT | | TRANSMIT |
/|===>| DATA |=========>| SHIFT |-------> TxD
|| | REGISTER | | REGISTER |
|| +----------+ +----------+
+---------+ ||
o2 --->| | || +----------+ +----------+
R-/W --->| SELECT | ||====| STATUS | | INTERRUPT|-------> /IRQ
CS0 --->| AND | || | REGISTER |<-------->| LOGIC |<------- /DCD
/CS1 --->| CONTROL | || +----------+ +----------+<------- /DSR
RS0 --->| LOGIC | ||
RS1 --->| | || +----------+ +----------+
/RES --->| | ||===>| CONTROL | | BAUD-RATE|<------> RxC
+---------+ || | REGISTER | | GENERATOR|<------- XTAL1
|| +----------+ +----------+<------- XTAL2
||
+---------+ || +----------+ +----------+
DB0 <-->| DATA- | || | RECEIVE | | RECEIVE |
... | BUS |<===||====| DATA |<=========| SHIFT |<---+--- RxD
DB7 <-->| BUFFERS | || | REGISTER | | REGISTER | |
+---------+ || +----------+ +-----.----+ |
|| | |
|| +----------+ +----------+ |
LEGEND: \|===>| COMMAND | | RECEIVE | |
| REGISTER | | CONTROL |<---+
===> : 8-bit line +----------+ +----------+
| |
---> : 1-bit line | +--------------------------------> /DTR
+-------------------------------------> /RTS
MAXIMUM RATINGS
<not included here>
ELECTRICAL CHARACTERISTICS
<not included here>
POWER DISSIPATION vs TEMPERATURE
<not included here>
TIMING CHARACTERISTICS
<not included here>
INTERFACE SIGNAL DESCRIPTION
/RES (Reset)
During system initialization a low on the /RES input will cause internal
registers to be cleared.
o2 (Input Clock)
The input clock is the system o2 clock and is used to trigger all data
transfers between the system microprocessor and the 6551.
R-/W (Read/Write)
The R-/W is generated by the microprocessor and is used to control the
direction of data transfers. A high on the R-/W pin allows the processor
to read the data supplied by the 6551. A low on the R-/W pin allows a write
to the 6551.
/IRQ (Interrupt Request)
The /IRQ pin is an interrupt signal from the interrupt-control logic. It is
an open drain output, permitting several devices to be connected to the common
/IRQ microprocessor input. Normally a high level, /IRQ goes low when an
interrupt occurs.
DB0--DB7 (Data Bus)
The DB0--DB7 pins are the eight data lines used for transfer of data between
the processor and the 6551. These lines are bi-directional and are normally
high-impedance except during Read cycles when selected.
CS0, /CS1 (Chip Selects)
The two chip-select inputs are normally connected to the processor-address
lines either directly or through decoders. The 6551 is selected when CS0 is
high and /CS1 is low.
RS0, RS1 (Register Selects)
The two register-select lines are normally connected to the processor-address
lines to allow the processor to select the various 6551 internal registers.
The following table indicates the internal register-select coding:
RS1 RS0 WRITE READ SL-Addr
--- --- ---------------------- --------------------- -------
0 0 Transmit Data Register Receive Data Register $DE00
0 1 Programmed Reset* Status Register $DE01
1 0 Command Register Command Register $DE02
1 1 Control Register Control Register $DE03
* for programmed reset, data is "don't care".
The table shows that only the Command and Control registers are read/write.
The Programmed Reset operation does not cause any data transfer, but is used
to clear the 6551 registers. The Programmed Reset is slightly different from
the Hardware Reset (/RES) and these differences are described in the
individual register definitions.
ACIA/MODEM INTERFACE SIGNAL DESCRIPTION
XTAL1, XTAL2 (Crystal Pins)
These pins are normally directly connected to the external crystal (1.8432
MHz) used to derive the various baud rates. Alternatively, an externally
generated clock may be used to drive the XTAL1 pin, in which case the XTAL2
pin must float. XTAL1 is the input pin for the transmit clock.
TxD (Transmit Data)
The TxD output line is used to transfer serial NRZ (non-return-to-zero) data
to the modem. The LSB (least-significant bit) of the Transmit Data Register
is the first data bit transmitted and the reate of data transmission is
determined by the baud rate selected.
RxD (Receive Data)
The RxD input line is used to transfer serial NRZ data into the ACIA from the
modem, LSB first. The receiver data rate is either the programmed baud rate
or the rate of an externally generated receiver clock. This selection is made
by programming the Control Register.
RxC (Receive Clock)
The RxC is a bi-directional pin which serves as either the receiver 16x clock
input or the receiver 16x clock output. The latter mode results if the
internal baud rate generator is selected for receiver data clocking.
/RTS (Request to Send)
The /RTS output pin is used to control the modem from the processor. The
state of the /RTS pin is determined by the contents of the Command Register.
/CTS (Clear to Send)
The /CTS input pin is used to control the transmitter operation. The enable
state is with /CTS low. The transmitter is automatically disabled if /CTS is
high.
/DTR (Data Terminal Ready)
The output pin is used to indicate the status of the 6551 to the modem. A low
of /DTR indicates the 6551 is enabled and a high indicates it is disabled.
The processor controls this pin via bit 0 of the Command Register.
/DSR (Data Set Ready)
The /DSR input pin is used to indicate to the 6551 the status of the modem. A
low indicates the "ready" state and a high, "not-ready". /DSR is a high-
impedance input and must not be a no-connect. If unused, it should be driven
high or low, but not switched.
Note: If Command Register Bit #0 = 1 and a change of state on /DSR occurs,
/IRQ will be set and Status Register Bit #[5] will reflect the new level. The
state of /DSR does not affect Transmitter operation [but must be low for the
Receiver to operate]. [This statement reflects the SwiftLink implementation].
/DCD (Data Carrier Detect)
The /DCD input pin is used to indicate to the 6551 the status of the carrier-
detect output of the modem. A low indicates that the modem carrier signal is
present and a high, that it is not. /DCD, like /DSR, is a high-impedance
input and must not be a no-connect.
Note: If Command Register Bit #0 = 1 and a change of state on /DSR occurs,
/IRQ will be set and Status Register Bit #[6] will reflect the new level. The
state of /DCD does not affect either Transmitter or Receiver operation.
INTERNAL ORGANIZATION
<not included here>
TRANSMIT AND RECEIVE DATA REGISTERS (SL-Addr: $DE00 / 56832)
These registers are used as temporary data storage for the 6551 Transmit and
Receive circuits. The Transmit Data Register is characterized as follows:
* Bit 0 is the leading bit to be transmitted.
* Unused data bits are the high-order bits and are "don't care" for
transmission.
The Receive Data Register is characterized in a similar fashion:
* Bit 0 is the leading bit received.
* Unused data bits are the high-order bits and are "0" for the receiver.
* Parity bits are not contained in the Receive Data Register, but are stripped
off after being used for external parity checking. Parity and all unused
high-order bits are "0".
Transmit / Receive Data Register
+-----+-----+-----+-----+-----+-----+-----+-----+
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+-----+-----+-----+-----+-----+-----+-----+-----+
| data |
The following figure illustrates a single transmitted or received data
word, for the example of 8 data bits, parity, and 1 stop bit:
"MARK"____ ___________________________________________________"MARK"
| | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | P | S .
|____|____|____|____|____|____|____|____|____|____|
start parity stop
bit ...data bits... bit bit
STATUS REGISTER (SL-Addr: $DE01 / 56833)
The Status Register is used to indicate to the processor the status of various
6551 functions and is outlined here:
Command Register
+-----+-----+-----+-----+-----+-----+-----+-----+
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+-----+-----+-----+-----+-----+-----+-----+-----+
| irq | dcd | dsr | txr | rxr | ovr | fe | pe |
+---+
| 7 | /IRQ*** : cleared by reading status register
+---+ --------------------------------------------
0 No interrupt
1 Interrupt
+---+
| 6 | /DCD : non-resetable, indicates /DCD status
+---+ --------------------------------------------
0 /DCD low
1 /DCD high
+---+
| 5 | /DSR : non-resetable, indicates /DSR status
+---+ --------------------------------------------
0 /DSR low
1 /DSR high
+---+
| 4 | Transmit Data Register Empty: Cleared by write to Tx Data reg
+---+ -------------------------------------------------------------
0 Not empty
1 Empty
+---+
| 3 | Receive Data Register Full: Cleared by read from Rx Data reg
+---+ -------------------------------------------------------------
0 Not full
1 Full
+---+
| 2 | Overrun*: Self-clearing**
+---+ -------------------------
0 No error
1 Error
+---+
| 1 | Framing Error*: Self-clearing**
+---+ -------------------------------
0 No error
1 Error
+---+
| 0 | Parity Error*: Self-clearing**
+---+ ------------------------------
0 No error
1 Error
Notes: * No interrupt generated for these conditions
** Cleared automatically after a read of RDR and the next error-
free receipt of data
*** Reading status reg. will clear the /IRQ bit except when
transmit intr. enabled
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
| 0 | x | x | 1 | 0 | 0 | 0 | 0 | After Hardware reset
+---+---+---+---+---+---+---+---+
| x | x | x | x | x | 0 | x | x | After Software reset
+---+---+---+---+---+---+---+---+
COMMAND REGISTER (SL-Addr: $DE02 / 56834)
The Command Register is used to control specific Transmit/Receive functions
and is shown here:
Command Register
+-----+-----+-----+-----+-----+-----+-----+-----+
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+-----+-----+-----+-----+-----+-----+-----+-----+
| parity | echo| tx ctrl | rxi | dtr |
+---+---+---+
| 7 | 6 | 5 | PARITY CHECK CONTROLS
+---+---+---+ ----------------------
x x 0 parity disabled--no parity bit generated or received
0 0 1 odd parity receiver and transmitter
0 1 1 even parity receiver and transmitter
1 0 1 mark parity transmitted, parity check disabled
1 1 1 space parity transmitted, parity check disabled
+---+
| 4 | NORMAL/ECHO MODE FOR RECEIVER
+---+ ------------------------------
0 Normal
1 Echo (bits 2 and 3 must be "0")
+---+---+
| 3 | 2 | Tx INTERRUPT RTS LEVEL TRANSMITTER
+---+---+ ------------ --------- ------------
0 0 Disabled High Off
0 1 Enabled Low On
1 0 Disabled Low On
1 1 Disabled Low Transmit BRK
+---+
| 1 | RECEIVE INTERRUPT ENABLE
+---+ -------------------------
0 /IRQ interrupt Enabled from bit 3 of Status Register
1 /IRQ interrupt Disabled
+---+
| 0 | DATA TERMINAL READY
+---+ --------------------
0 Disable Receiver and all interrupts (/DTR high)
1 Enable Receiver and all interrupts (/DTR low)
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | After Hardware reset
+---+---+---+---+---+---+---+---+
| x | x | x | 0 | 0 | 0 | 0 | 0 | After Software reset
+---+---+---+---+---+---+---+---+
CONTROL REGISTER (SL-Addr: $DE03 / 56835 / cpm: 0001xxxx)
The Control Register is used to select the desired mode for the 6551. The
word length, number of stop bits, and clock controls are all determined
by the Control Register, which is shown here:
Control Register
+-----+-----+-----+-----+-----+-----+-----+-----+
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+-----+-----+-----+-----+-----+-----+-----+-----+
|stops| word len | src | baud rate |
+---+
| 7 | STOP BITS
+---+ ----------
0 1 stop bit
1 2 stop bits
1 1 stop bit if word length== 8 bits and parity
this allows for 9-bit transmission (8 data bits plus parity)
1 1.5 stop bits if word length== 5 bits and no parity
+---+---+
| 6 | 5 | WORD LENGTH
+---+---+ ------------
0 0 8 bits
0 1 7 bits
1 0 6 bits
1 1 5 bits
+---+
| 4 | RECEIVER CLOCK SOURCE
+---+ ----------
0 external receiver clock
1 baud rate generator
+---+---+---+---+
| 3 | 2 | 1 | 0 | BAUD RATE GENERATOR
+---+---+---+---+ --------------------
0 0 0 0 16x external clock
0 0 0 1 100 baud
0 0 1 0 150 baud
0 0 1 1 219.84 baud
0 1 0 0 269.16 baud
0 1 0 1 300 baud
0 1 1 0 600 baud
0 1 1 1 1200 baud
1 0 0 0 2400 baud
1 0 0 1 3600 baud
1 0 1 0 4800 baud
1 0 1 1 7200 baud
1 1 0 0 9600 baud
1 1 0 1 14400 baud
1 1 1 0 19200 baud
1 1 1 1 38400 baud
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | After Hardware reset
+---+---+---+---+---+---+---+---+
| x | x | x | x | x | x | x | x | After Software reset
+---+---+---+---+---+---+---+---+
========================================================================
Design and Implementation of a Simple/Efficient Upload/Download Protocol
by Craig Bruce <csbruce@ccnga.uwaterloo.ca>
1. INTRODUCTION
If you use your Commodore for telecommunications, then you are basically
interested in two things: using your C= to emulate a terminal for interactive
stuff, and using modem-file-transfer protocols to upload and download files
from and to your Commodore.
This document describes a custom upload/download protocol that was designed
for use with the ACE-128/64 system and is freely available to anyone who wants
it (well, when I finish with the Release #14 of ACE). While this protocol
non-standard, it blows the doors off of all other protocols available for
Commodore computers, even though it uses a simple "stop-and-wait"
acknowledgement scheme. There are two reasons for its speed: the fast device
drivers available with ACE, and its large packet size, up to about 18K
(although this could be significantly larger is ACE's memory usage were
reorganized).
The name of the protocol is "Craig's File eXchange Protocol", or just "FX" for
short. It is "file exchange" rather than "upload" or "download" because you
will use the same activation of the program to both upload and download all of
the files you name.
2. USAGE
The current implementation of FX consists of a "client" program for you to run
on your Commodore computer and a "server" program that you run on your Unix
host. There is currently no server program for any other platform, but the
necessary changes to the C-language program wouldn't be too hard. The client
program is written in 6502 assembler, of course (for the ACE-assembler to be
specific).
FX is an external program from the terminal program, so (for now) to activate
FX, you have to exit from the terminal program and enter the FX command line,
exchange the files, and then re-enter the terminal program from the command
line.
When you run FX, you will activate the Server program first on your Unix host
and then exit the terminal program and run the Client program on your
Commodore. You run the command "fx" on both the client and server machines,
which may be a little confusing (but I think you'll get used to it), and name
the files that you want to have transferred as arguments to the command on the
machine that you want to transfer the files FROM. The usage of the "fx"
command is as follows:
fx [-dlvV7] [-m maximums] [-f argfile] [[-b] binfile ...] [-t textfile ...]
-d = debug mode
-l = write to log file ("fx.log")
-v = verbose log/debug mode
-V = extremely verbose log/debug mode
-7 = use seven-bit encoding
-m = set maximum packet sizes; maximums = ulbin/ultxt/dlbin/dltxt (bytes)
-f = take arguments one-per-line from given argfile
-b = binary files prefix
-t = text files prefix
-help = help
well, for the server, anyway. The client program doesn't have the more
exotic options. The "-d", "-l", "-v", and "-V" options are available only
on the Server program, and are for debugging purposes only.
The "-7" option tells the protocol to use only 7-bit data. I.e., it tells it
to not use the 8th bit position in the data is transmitted. This is useful if
you are forced into the humiliation of only being able to use a 7-bit channel
to your Unix host. You need only need to give this option on either the
client or the host command line and the other side will be informed. It may
be useful to create an alias for this command with all of your options set to
what you want them to be.
The protocol has the capacity to use different packet sizes for four types of
file-transfer situations: uploading binary data, uploading text, downloading
binary data, and downloading text. These are useful distinctions, since your
host may or may not be able to handle the larger packet sizes without losing
bytes (your Commodore, of course, can handle the larger packet sizes with no
problems).
In determining which packet size to use for a file transfer (where the type of
transfer is known), the protocol finds that largest packet size that both the
client and the server can handle and then take the minimum of these two
values. The defaults for the client are all the same: the maximum amount of
program-area memory that it can use, about 18K. For the server program, I
have programmed in default maximum uploading packet sizes of 1K and maximum
downloading packet sizes of 64K-1. You can change these defaults in the C
program easily by changing some "#define"s.
The "-m" option allows you to manually set the default packet sizes for a
transfer. The argument following the "-m" flag should have four numbers with
slashes between them, which give the maximum ulbin/ultxt/dlbin/dltxt packet
sizes, respectively. Note that the packet sizes only include the size of the
user data encoded into packets and not the control or quoting information
(below).
The "-f" option on the server allows you to read arguments from a file rather
than the command line. This is useful if want to generate and edit the list
of files to download before you run the FX command. It's also useful if you
don't want other users to see the names of the files that you are
downloading. The name of the file comes in the first argument following the
"-f" flag and the arguments are put into this file one-per-line. You can put
in "-" options in addition to filenames if you wish (like "-t" and "-b").
This option is not supported on the client program.
Finally come the "-b", "-t", and filename arguments. The "-b" argument tells
FX that all of the following filenames (until the next "-t" option) are binary
files and the "-t" argument says that the following filenames are all of text
files. You can use as many "-b" and "-t" arguments as you want. If you don't
use any, then all of the files you name will be assumed to be binary files.
For each filename you give on a command line, that file will be transferred
from that machine to the other machine. On both Unix and ACE, you can use
wildcards in your filenames, of course, to transfer groups of files.
The client program controls the file exchange, and it uploads all of its files
first and then asks the server if the server has any files to be downloaded.
When the exchange is completed, both the client and server FX programs will
exit and you will find yourself back on the command lines in both
environments. Re-enter the terminal program to continue with your online
session. If something goes very wrong during a transfer or if you decide that
you don't really want to transfer any files after activating the server
program, you can type three Ctrl-X's to abort the server. This is the same as
for the X-modem protocol.
3. DESIGN DECISIONS
There are a number of design decisions to be made about our protocol. But
first, we want to recognize and appreciate that since we have a license to
design a completely new protocol, we are not bound, shackled, gagged, and
tortured by the "hysterical raisins" and bad design decisions of existing
compromised and bloated standard protocols... such as Z-modem.
We want the protocol to understand whether a file is text or binary data and
to translate them appropriately during downloading. We want the protocol to
be aware of filenames, dates, permissions, and we do not want our file
contents to get mangled like they do with X-modem (it pads them with Ctrl-Z's,
since it was designed for CP/M), and we want it to translate to/from PETSCII
if the file is text. We will require that the user tell us whether the file
is binary or text (although we may be able to statistically determine this
from snooping through the file), and we will use a "canonical form" for
encoding the text data during transfer. A convenient canonical form to use is
Unix-ASCII (ASCII-LF).
We want our protocol to be simultaneously simple and fast. To make it simple,
we will use a stop-and-wait acknowledgement scheme. This means that after
each packet is uploaded or downloaded, the transfer will pause and wait for
the receiving host to acknowledge that the packet has been transferred
correctly, and only then will the protocol continue to transfer more data.
In fact, this scheme fits well with the Commodore hardware, since it is not
possible to send or receive serial data while doing disk I/O (in the general
case), so we would have to stop listening anyway; the protocol makes it so
that there will be no bytes that we end up ignoring while doing I/O.
To make the protocol be fast even though we are using a stop-and-wait
acknowledgement scheme, we will use the largest data-packet sizes that we
possibly can. In the (current) ACE environment, this means about 18K. This
will maximize the amount of time of transferring data over the modem between
pauses to do I/O. If the I/O is to the ACE ramdisk, then the length of this
pause will be very short and we will achieve a very high link utilization.
(The ACE ramdisk can process an 18K read/write request in about 20
milliseconds on a Fast-mode C128 using an REU --- RAMDOS in the same
environment would require about 9 _seconds_ (450x slower)).
To allow for future use with other platforms, we will make the protocol define
the packet sizes using 32-bit fields. There isn't much data overhead, and
this allows us to change implementations to be able to transfer entire files
in one large packet. Also, the size of an individual packet should be
flexible: be from one to N bytes. This eliminates the X-modem padding problem
and the Y-modem crufty hack of using the small packet size when less than 1K
of user data remains to be transferred.
We also want our data to be well protected against corruption. Detecting
transmission errors efficiently on Commodore computers is already a well
solved problem: we will use a table-driven CRC-32 algorithm, the same one that
ZMODEM, PKZIP, and CRC32 use. To hide the computation costs of the CRC even
more (the cost is very low anyway), we will compute it WHILE sending or
receiving packets. Oh, actually, I guess that I forgot to mention an a-priori
design decision: we will be using a packet-oriented approach for transferring
data (described below); packetization offers so many advantages that this
decision is really a no-brainer.
Also, to make the process interaction as straightforward as possible, we want
to use the Client/Server programming paradigm. This paradigm combines well
with the stop-and-wait acknowledgement scheme to produce a Remote Procedure
Call (RPC) type of interaction between the machines. For those not familiar
with this Interprocess Communication (IPC) scheme, you can read a couple
issues of C= hacking ago where I talked about it for use with a multitasking
operation system. RPC is a very useful, powerful, simple, and widely
applicable IPC scheme.
To recover from packet corruption, we will be using a timeout+retransmission
scheme, and to be consistent with the RPC scheme, the client will do all
timeouts and retransmissions. This means that after sending a request RPC
packet out, if we don't receive the reply within a certain period of time, we
will timeout and send the request again. Or, to be more precise, since we
will be working with large packet sizes, we will timeout if we don't receive
any bytes from the server for a certain period of time, say 5 seconds, while
we are expecting more bytes from him.
The way that corrupted packets are dealt with is very simple: they are
ignored. The server could possibly send back a negative acknowledgement,
but we won't try that for now.
In order to make retransmissions work out correctly, we will be using sequence
numbers and internal-state variables inside of the server to insure that
requests aren't carried out more than once. We need these mechanisms because
when an RPC fails, we won't know if we got no response because the original
request was lost and the operations wasn't carried out, or whether the request
was received and carried out but the reply message was lost.
For example, if we request that packet #123 be downloaded and the server
carries out that request but the reply message is lost, then the client will
time out and retransmit the request. The server remembers the last request
number that the client sent it (123 here), so if the client asks for packet
#123 again, the server will simply retransmit the reply that it gave last
time. If, on the other hand, the client were to request packet #124 (or
simply "not 123"), then the server reads the next chunk of data from the file
and sends it as the reply. Our protocol will use an 8-bit sequence number
even though it only needs a 1-bit sequence number (since eight bits will allow
for the future expansion of having multiple requests being processed
concurrently: asynchronous RPC).
We also want to be able to both upload and download as conveniently as
possible. To me, this means doing both operations by calling only one command
(as described in the previous section). This arrangement also allows for the
future expansion of uploading and downloading files _simultaneously_ (the
protocol as designed places no restrictions on this possibility).
We also want to make use of an eight-bit clean link between the Unix host and
your Commodore, but this may not always be possible. Sometimes you may have
only a 7-bit connection, and even if you do have an 8-bit connection, there
may still be some software-flow-control problems with intermediate devices
between your Commodore and your Unix host. So, we want our protocol to not
make use of the X-on and X-off characters, and to use only 7-bit characters if
it cannot use eight. The way to achieve this is called "escaping", "quoting"
or "byte stuffing", and will be discussed in the next section. It turns out
that supporting 7-bit characters is pretty simple and the mechanism is
required by other aspects of the packetization.
There, that should take care of most of the major design decisions.
4. PACKETIZATION
Packetization refers to the process of taking a stream of data and breaking it
up into discrete chunks of data. Each packet is easily identified and is
processed as a single unit. There are many general advantages to using
packets. If there is a transmission error, then only a single packet is
corrupted, and the recovery will be easier since the packet is well
identified, and only it needs to be recovered. Packetization also means that
a link can be shared between multiple (logical) communication streams fairly
and efficiently, and means that a single communication stream can utilize
multiple physical links where facilities exist.
Packets also integrate well with many IPC schemes, including Remote Procedure
Calls. In fact, you end up emulating a packet-oriented scheme even if you are
using RPC over a stream-oriented transport system. Packets also take into
account the limited buffering capacity of both end systems and intermediate
systems, and allow for the convenient implementation of flow control (even if
said flow control consists of simply dropping packets on the floor). Packets
are very useful things indeed! And just think that back in the early 1970s
packets were dismissed as being infeasible and unusable.
Each packet used in the FX system has four parts to it: the start character,
the user data (payload), the error-check characters, and the end character.
Graphically, a packet has the following format:
+------------------------+-----------+--------------+----------------------+
| Start-of-packet Char | Payload | ErrorCheck | End-of-packet Char |
+------------------------+-----------+--------------+----------------------+
The payload can be arbitrarily long, up to whatever limit the two computers
involved in the transfer can handle.
The error check is a 32-bit (4-byte) Cyclic-Redundancy-Check value that
occupies the last four bytes before the End-of-packet character. The
implementation, which is based on a table-lookup method, is so efficient that
it is as fast as a simple add-up checksum, except much more reliable. Using
this error check, there will be approximately a one-in-4,000,000,000 chance
that a packet with an error in it will be accepted has being error-free.
These are pretty good odds for our purposes. The CRC is calculated
exclusively on the raw payload data.
The following special characters used by packets are defined:
NAME HEX DEC Control Meaning
--------- ---- --- ------- --------
CHR_START 0x01 1 Ctrl-A Packet-start indicator
CHR_END 0x19 25 Ctrl-Y Packet-end indicator
CHR_ESC 0x05 5 Ctrl-E Escape character for next code
CHR_ABORT 0x18 24 Ctrl-X Abort transfer if repeated three times
CHR_XON 0x11 17 Ctrl-Q Software flow-start: avoided
CHR_XOFF 0x13 19 Ctrl-S Software flow-stop: avoided
CHR_QUOTE8 0x14 20 Ctrl-T Quote-8 the next 7-bit sequence
CHR_START is used to signify the start of a new packet. This character is
not allowed to be used anywhere else for any other purpose.
CHR_END is used to signify the end of the current packet, and cannot be used
anywhere else. The reason for using special characters to mark the beginning
and the ending of a packet is to allow for easy error recovery after a
communication failure. All you do is search for the next CHR_START character
after you toss away a garbled packet and you're back in business. I am
unaware of any reasonable alternatives to framing packets with a CHR_START
character. Using a CHR_END special character is a convenience.
CHR_ESC is used to "escape" the next character. Since there are special
character codes that cannot be used in any other way than their intended
function (including CHR_START and CHR_ESC itself), this character is needed.
The character following the CHR_ESC character must be between "@" and "_"
(0x40 and 0x5f) in the ASCII chart, or be the character "?" (0x3f). The
character following the CHR_ESC is then "and"ed with the value 0x1f to mask
off the "letter" bits and turn it into a control character in the range of
0x00 to 0x1f (the same range as the special control characters) and the
"escape sequence" is treated as a single character of user data. If the
character following the CHR_ESC is a "?", then a code of 0x7f is interpreted
instead. Using a character following the escape that is different from the
character being represented allows for greater resiliance of the protocol in
the presence of bits being garbled or bytes being dropped. All special
characters in a packet except for the starting and ending characters are
escaped as described above.
CHR_ABORT can be typed by the user into a terminal program at any time to shut
down the server.
CHR_XON and CHR_XOFF can cause problems with intermediate devices on some
systems, so the FX protocol does not use these character codes at all; it
purposely avoids them and uses escape sequences (CHR_ESC) for them instead.
CHR_QUOTE8 is used to re-generate 8-bit data over a 7-bit link. Kermit uses
this same technique. When this character is encountered in the receive
stream, the next character is extracted and is "or"ed with a value of 0x80 to
give it a "1" in the high-bit position. The CHR_QUOTE8 character can also be
followed by a CHR_ESC code, which is interpreted as above and then "or"ed with
the 0x80 value.
One of the disadvantages of using this scheme is that each byte in the range
of 0x80 and 0xff takes at least two bytes to transmit and some of them three.
If fact, for many binary files it may be faster to uuencode the file and
transfer the resulting text, since uucode has a static encoding overhead of
33% whereas this quoting scheme has an expected overhead of 50% (plus the
CHR_ESC overhead). Of course, this feature is intended to be used as a last
resort if you cannot get an 8-bit connection.
So there you have it. Every message sent between the client and the server
is encapsulated in a packet as specified above. Packetization allows for
convenient error detection and recovery and works well with our interprocess
communication scheme.
One implementation note about the packetization has to do with buffering. On
the Unix host, it is advantageous to encode a packet into a memory buffer and
then send out that buffer in a single "write" operation. This less operating-
system overhead (which may or may not be significant) but more importantly,
it means that the packet will be sent between intermediate communication
devices as efficiently as possible. On my local Unix system, I connect to
a terminal server and to my Unix host through that. Performing single-byte
writes on the Unix host means that the bytes are sent in individual Ethernet
packets between the Unix host and the terminal server, and encounter more
overhead and communication delays. When I changed the program to send the
FX packet in a single operation, a significant performance gain was realized.
For receiving data on the Unix host, there isn't much you can do other than
reading one byte at a time, since the receiver doesn't know when a packet is
going to end. However, the same problem is not encountered here that was
encountered with sending data because data that is received by the Unix host
but not "read" by the user program are buffered and collected, smoothing out
the system overhead, which is insignificant compared to the modem speed. The
Unix program used the "stdin" and "stdout" file streams for receiving and
transmitting data, and sets the tty driver to turn off all line-editing
features to get at the raw bytes.
On the Commodore end, it is advantageous to read data from the modem driver in
chunks, since the system overhead is significant compared to the modem speed.
These are small computers that we are driving to the max, you know. Data is
read from the modem in chunks of up to 255 bytes (whatever is available at the
time) and processed a byte at a time from the read buffer. The CRC is
calculated during processing, to avoid doing this on the critical path. The
CRC calculation is performed as an operation by itself since the overhead is
very small on fast processors. The character-set translation for text files
will be performed on the critical path (on the Commodore) since it is more
convenient to do it at a higher layer in the IPC scheme. The packet- handling
software is logically at a distinct layer that doesn't have to worry about
higher layers. The next layer up is logically the RPC layer and then the
file-transfer layer.
5. CLIENT/SERVER OPERATION
As discussed previously, the client/server interaction is based on a Remote
Procedure Call paradigm. Thus, for each operation, the client sends a request
packet (message) to the server, and the server performs the requested
operation and sends back a reply (acknowledgement) message to the client.
There are eight request/ack interactions that are defined for the protocol:
two for connection management, three for uploading files, and three for
downloading files. The client is in charge of the file-exchange session
and of the error handling.
4.1. CONNECTION MANAGEMENT
When the client starts up, the first thing that it does is connect to the
server. The format of the message that it sends is as follows:
OFF SIZ DESC
--- --- -----
0 1 code: REQ_CONNECT ('C')
1 1 protocol version := 0x01
2 1 transmit byte size: '7' or '8' bits
3 - SIZE
This is what gets put into the the "payload" portion of the packet. All of
the messages used in the protocol have an ASCII letter in the first byte that
identifies what the message type is. Each request has an uppercase letter and
each acknowledgement has the corresponding lowercase letter.
The connection-request message is fairly simple: it includes the protocol
version number and the number of bits wide that the client thinks that the
communication channel is. The version number is currently always 0x01 and is
included for cross-compatibility with future versions of the protocol. The
channel width is encoded into either a '7' or an '8' ASCII character. The
client will think that the channel width is seven bits only if you tell it
this on the command line.
When the server receives the connection request, it replies with the following
message:
OFF SIZ DESC
--- --- -----
0 1 code: ACK_CONNECT ('c')
1 1 protocol version := 0x01
2 1 transmit byte size: '7' or '8' bits
3 1 recommended request byte size: '7' or '8' bits
4 4 server maximum text-upload data size: H/M/M/L word
8 4 server maximum binary-upload data size: H/M/M/L word
12 4 server maximum text-download data size: H/M/M/L word
16 4 server maximum binary-download data size: H/M/M/L word
20 - SIZE
The "protocol version" is what the server is using, currently always 0x01.
The "transmit byte size" is the size that the user has specified on the
command line that activated the server, and the "recommended request byte
size" is a '7' if either the "transmit byte size" of the either the client or
server is seven bits, or '8' otherwise. This is what should be used for the
all subsequent messages that are exchanged.
The server's reply also includes the maximum packet sizes that it can handle
for uploading and downloading binary and text files. The client then takes
the "min" of the server's maximum packet sizes and its own, and uses the
resulting maximum packet sizes for the rest of the file exchange session. The
maximum packet sizes in the server's reply are all 32-bit unsigned integers
that are stored from most-significant to least-significant bytes (big endian
order). I picked big-endian order because that is the order used most
commonly in inter-machine protocols.
The reason that the client doesn't have to inform the server of the client's
maximum packet sizes in its connection message is that the maximum packet
size to use is included with each request to get the next packet of a download
file. It is sufficient that the client knows the full max-packet information.
Really, the "transmit byte size" field isn't needed in the server reply
message either, but I wanted the packet-size fields to be size-aligned.
After all of the file exchanging is completed, the client sends the following
message to terminate the connection and return the server back to its command-
li
ne mode:
OFF SIZ DESC
--- --- -----
0 1 code: REQ_DISCONNECT ('Q')
1 - SIZE
When the server receives this request, it replies with:
OFF SIZ DESC
--- --- -----
0 1 code: ACK_DISCONNECT ('q')
1 - SIZE
And then exits like it should. Note that once the server exits, it cannot
accept any more packets, since they would be sent to whatever command shell
you use on your Unix system, and wouldn't do anything useful, so if the client
sends the disconnect message but doesn't receive any reply, it will time out
and tell the user that it couldn't disconnect cleanly from the server. This
should be a rare occurrence. Anyway, what the user would do then is re-enter
his terminal program and send Ctrl-X's at the server until it exits like it
should have.
This arrangement allows us to avoid the famous(?) "two armies" problem that is
inherent in disconnecting two connected processes: there is no "clean" way to
do it. What systems like Z-Modem and Berkeley Sockets do is to have the
server wait for a period of time that is longer than N times the timeout
period of the client so that if there is a retransmission of the disconnection
request, it likely that it will be received and processed correctly by the
server. This is the reason (presumably) that Z-Modem does an annoying pause
of 15 seconds or so after you finish transferring files. I think that my
solution is much nicer, since the server can exit immediately (even though my
server delays for 1 second, just so that your shell prompt will be cleanly in
your modem's ARQ buffer when you re-enter your terminal program, if you have a
hardware-flow-control modem).
4.2. FILE UPLOADING
Okay, so between connecting to and disconnecting from the server, actual
useful stuff happens, including uploading and downloading files. The
uploading and downloading requests operate much like the regular file
operations of open, close, read, and write. Really, the FX protocol makes the
server program a special kind of file server.
When the client decides that it wants to upload a file, it first informs the
server about this by sending the following message:
OFF SIZ DESC
--- --- -----
0 1 code: REQ_UPLOAD_OPEN ('U')
1 1 data type: 't'=text file, 'b'=binary file: 'd'=directory
2 4 estimated file size: H/M/M/L word
6 2 permissions ("-----sgr:wxrwxrwx"), like Unix, H:L
8 12 modified date: BCD format: <YY:YY:MM:DD:hh:mm:ss:tt:tw:GG:gg:aa>
20 n filename, null-terminated
20+n - SIZE
The "data type" field tells whether a text or binary file will be uploaded.
There is a provision for "uploading" a directory entry (as part of uploading
and downloading entire directory hierarchies), but support for this is not
implemented yet. Also, it makes no difference to a Unix system whether a file
contains text or binary data, but it may make a difference to other operating
systems (like Mess-DOS). The "estimated file size" field isn't really used
either, but it allows the server to make intelligent decisions about
pre-allocating space, buffering, etc., if it needed to. However, it is
currently not filled in by the client, since file-size information is
difficult to extract from Commodore-DOS. The file size is an unsigned 32-bit
quantity.
The permissions field is currently not supported by the server, but it is
intended to allow file permissions to be preserved when passing files from one
system to another. The interpretation of the 16 bits of this field is like it
is with the Unix operating system: "rwx" bits for the owner, group, and other,
and execute-as-owner, execute-as-group bits. The owner-id and group-id fields
aren't included since they are generally not portable across systems, and even
if they were, we usually want to receive files as our own owner-id and our own
group-id.
The "modification date" field is not currently filled in either, since this
information is even harder to come across with Commodore-DOS, but when it is,
it will have a 12-byte BCD format. The "YY:YY:MM:DD:hh:mm:ss" sub-fields
should be easy enough to figure out, and the "tt:t" fields contain thousandths
of seconds. The "w" field contains the day of the week, coded as 0-6 for
Sunday to Saturday, and 7 for "unknown". The "GG:gg" fields contain the
number of hours and minutes that your time zone is off from GMT. If the
number is negative (in the western hemisphere), then the regular positive
number of hours will be used, execept that the 0x80 bit of the hours byte will
be set. Finally, the "aa" sub-field is used to encode the accuracy of the
timestamp. The way that it is interpreted is that the time value is accurate
to plus/minus 2^aa milliseconds. For example, if my clock were accurate to
within one second, then this field would be set to 10 in BCD (2^10 ==
1024ms). A value of 99 means "unknown" (or that the clock could be off by
many billions of billions of years).
I decided to go all out in defining the date field so that it will be useful
in the future when "world consciousness" will be much more important than
it is today.
And last but certainly not least, the filename is encoded in ASCII with a
trailing zero byte.
Upon receiving this request, the server will attempt to create a file
according to your specifications, and will send back a reply of the form:
OFF SIZ DESC
--- --- -----
0 1 code: ACK_UPLOAD_OPEN ('u')
1 1 error code: 'y'=successful, 'n'=open unsuccessful
2 - SIZE
The "error code" field tells whether the open operation was successful or
not. If it was, then the client can continue with uploading its file; if not,
then that file cannot be uploaded (and that the upload channel doesn't need to
be closed). It's up to the client whether to go on to the next file, abort,
or ask the user for help. The client will currently report an error to the
user and then go onto the next file. Of course, it's likely that whatever
caused the error in creating the current file will also cause an error in
creating subsequent files (insufficient access permissions on the current
directory, disk full, etc.). The server will overwrite any existing file
with the same name (since asking permission, etc., would require extra
mechanism, and would probably be a nuisance anyway).
If the upload channel is opened successfully, then the packets of upload
data should be sent to the server one at a time, until all of the data is
uploaded. The client sends the following message to the server to upload
a packet of data:
OFF SIZ DESC
--- --- -----
0 1 code; REQ_UPLOAD_PACKET ('R')
1 1 upload sequence number
2 4 data length: H/M/M/L word
6 n data
6+n - SIZE
The "upload sequence number", which was described before, is used to make sure
that retransmissions of packets are detected and handled properly, so that
each packet of data only appears in the file once. The "data length" field
tells the number of user data bytes that follow in the packet, and then the
actual user data bytes appear. The "data length" field is actually redundant,
but I figured that it would make programming a little easier, and allows
additional error checking. Normally, each upload-data packet will contain
the maximum-packet-size number of bytes of user data (according to whether
text or binary data is being uploaded), except for the last packet, which
will contain the number of data bytes that are left in the file. However,
each packet is allowed to contain anywhere from 1 to the maximum-packet-
size number of bytes: whatever the client wishes to use. Variable-sized
packets are a Good Thing (TM, Pat. Pend.). You will note that the data-
size values are also what will be used for the "read" and "write" system
calls on the client and server, respectively. I/O will be done in big,
efficient chunks.
Upon receiving each upload packet, the server replies with the following
acknowledgement message:
OFF SIZ DESC
--- --- -----
0 1 code: ACK_UPLOAD_PACKET ('r')
1 1 upload sequence number
2 - SIZE
I don't think that the "sequence number" field is actually necessary here, but
it is included to allow for future expansion and to provide redundancy for
protocol-error checking.
When the client has uploaded all of the packets of the file currently being
uploaded, it then sends the following message:
OFF SIZ DESC
--- --- -----
0 1 code: REQ_UPLOAD_CLOSE ('V')
1 - SIZE
This will close the upload channel and will finish writing the uploaded file
to the Unix file system. The server will then respond with the following
message to acknowledge the request:
OFF SIZ DESC
--- --- -----
0 1 code: ACK_UPLOAD_CLOSE ('v')
1 4 number of bytes uploaded: H/M/M/L word
5 - SIZE
The "number of bytes" field is actually redundant, but is used for additional
error checking.
4.3. FILE DOWNLOADING
Downloading files is analogous to uploading them: first we open the download
channel/file, then we download the packets, and then we close the download
channel.
To open the download channel, the client sends the following request to the
server:
OFF SIZ DESC
--- --- -----
0 1 code: REQ_DOWNLOAD_OPEN ('D')
1 - SIZE
To which the server replies with:
OFF SIZ DESC
--- --- -----
0 1 code: ACK_DOWNLOAD_OPEN ('d')
1 1 data type: '0'=no more files (eom),'t'=text,'b'=bin,'e'=err,'d'=dir
2 4 estimated file size: H/M/M/L word
6 2 permissions ("-----sgr:wxrwxrwx"), like Unix, H:L
8 12 modified date: BCD format: <YY:YY:MM:DD:hh:mm:ss:tt:tw:GG:gg:aa>
20 n filename, null-terminated
20+n - SIZE
The file information is the same as for opening an upload file, except that
there are more possible return conditions, and all of the "meta data" fields
are actually filled in by the Unix host (since this information is actually
conveniently available via the "stat" system call).
If the server replies with a '0' "data type" code, then this means that the
server has no more files to offer for downloading. The filenames to download
are taken one at a time, from left to right, from the command line that was
used to start the server. When the server runs out, then the downloading
session is complete and the client disconnects (since the client uploads
its files first).
Alternatively, the server could reply with a 'e' code, which means that
it could not open the next filename given on its command line. An error
return is generated so that the client can inform the user that the file
could not be downloaded. This will normally result from the user giving
a bad filename on the command line. The client will continue the downloading
process by closing the download channel (below) asking for the next file by
re-opening the download channel. The download channel needs to be closed
on this condition since otherwise there would be no way of distinguishing
retransmissions from new requests at the server.
Finally, the server can reply with a 't' or 'b' code ('d' for directories is
not currently implemented) indicating that the file was correctly opened and
is either text or binary (as specified on the server's command line). Of the
meta information about the file, only the filename and file size are currently
used: the file is named according to the given name, translated to PETSCII and
truncated to 16 characters, and the file size is reported to the user so that
he can monitor downloading progress. I am not sure what to do yet about name
collisions on the Commodore end: either ask the user whether to overwrite the
file, automatically overwrite the file anyway, or automatically give the file
a slightly different name and download normally. I think that for the time
being, I will just overwrite the existing file. This will mean that you'll
want to be extra careful in putting the filenames onto the correct command
line (the client's or the server's), although there won't be a problem if the
file doesn't exist on the machine whose command line you put the name on.
When the file handling is all squared away and the download channel is opened,
the client then sucks packets out of the file until the end of the file is
reached. The packets are sucked out with the following request:
OFF SIZ DESC
--- --- -----
0 1 code: REQ_DOWNLOAD_PACKET ('S')
1 1 download sequence number
2 4 maximum acceptable data length: H/M/M/L word
6 - SIZE
The "download sequence number" is used to distinguish retransmissions from
requests for new packets, and the client tells the server the "maximum
acceptable data length" for the reply packet. Although the max-packet
information is actually static during the connection, I included it here in
every "read" request since I didn't really want the server to keep that
particular bit of "state" internally.
The server replies to the download-packet request with the following message:
OFF SIZ DESC
--- --- -----
0 1 code: ACK_DOWNLOAD_PACKET ('s')
1 1 download sequence number
2 4 data length: H/M/M/L word, 0==EOF
6 n data
6+n - SIZE
This is the only "large" message that the server can produce. It includes the
sequence number, the number of bytes that are actually included, and the user
data. The number of data bytes in the packet is allowed to be smaller than
the number of bytes requested, but this is normally only the case for the last
packet of the file.
To indicate that the end of file has been reached and that no more user data
is available, the server will return a download packet with zero bytes of user
data in it. Upon receiving this, the client will close the download channel
with the following message:
OFF SIZ DESC
--- --- -----
0 1 code: REQ_DOWNLOAD_CLOSE ('E')
1 - SIZE
And the server will reply with:
OFF SIZ DESC
--- --- -----
0 1 code: ACK_DOWNLOAD_CLOSE ('e')
1 4 number of file bytes downloaded: H/M/M/L word
5 - SIZE
The "number of file bytes downloaded" field is redundant but included for
additional error checking. After closing a file, the client will then ask
for the next file, or will disconnect if the last file to download was just
closed.
4.4. ERROR HANDLING
With all of the server calls except for disconnecting (discussed earlier), the
is the possibility that either the request message from the client or the
reply message from the server will become garbled and be dropped by the
packet-delivery layer of the software. To recover from this, if the client
detects an extended period of inactivity on the serial line for received data
(where "extended period" is defined as being "about five seconds"), then the
client will assume that something went wrong and it will retransmit the
request.
As pointed out way above, there are two possible reasons for a retransmission
being needed: either the request packet was corrupted and dropped, or the
reply packet was corrupted and dropped. In the format case, the request
wasn't processed by the server, but in the latter case, it was. Since we
don't want the server to perform an file operation twice (this is really
what the six file-transfer client operations really boil down to from the
server's perspective), the server must keep four pieces of internal state:
the last upload sequence number, the last download sequence number, whether
the upload file is open, and whether the download file is open.
If an upload-open request is received and the file to be uploaded is not open,
the the request must be a new one and the server processes it and sends back a
reply like normal. If an upload-open request is receive and the upload file
IS currently open, then it must be the case that the current request is a
retransmission, so all theat the server needs to do is to give a positive
reply without performing any internal file operations. The same holds true
for the download-open call and for both of the close calls (except that the
operation has already been processed if the file is CLOSED).
For the packet-upload and packet-download requests, sequence numbers are used
to detect duplicates. You will note that these sequence numbers are distinct
from one another, and, in fact, that the entire upload and download file-
transfer channels are distinct and independent from each another. This is to
allow for the future possibility of simultaneous file uploading and
downloading. In fact, if stream numbers (file descriptors) were added to the
open/read/write/close requests, then we could have us a full-blown remote-host
over-the-phone interactive file server. But anywho, sequence numbers start
from 0x00 for the first packet transferred and increment modulo 256 from
there.
Note that for high-speed data-compression modems (like I have) that already
include error detection and recovery at a level hidden from the user, the FX
protocol will work particularly well: there will never be an error, never be a
timeout delay, and never be a retransmission. And, really, the CRC-32 error
computation and checking is pretty much a zero cost. But, if something does
go wrong, outside of the modem-to-modem connection, the FX protocol is right
there to pick up the pieces and carry on.
6. CONCLUSION
You'll have to wait to get your hands on the program. The Unix Server
program is almost 100% (except for a few design changes that I made while
writing this document), and the ACE program is implemented except for
the error handling and text conversion. Both programs will be released
with the next release of ACE, which will be Real Soon Now (TM).
Here is my performance testing so far, using my USR Sportster modem over a
14.4-kbps phone connection, with a 38.4-kbps link to my modem from my C128, to
my usual Unix host:
Using FX to/from the ACE ramdisk, REU:
Download 156,260 bytes of ~text: time= 54.1 sec, rate=2888 cps.
Download 151,267 bytes of tabular text: time= 45.9 sec, rate=3296 cps.
Download 141,299 bytes of JPEG image: time= 92.5 sec, rate=1528 cps.
Upload 156,260 bytes of ~text: time= 57.4 sec, rate=2722 cps.
Upload 151,267 bytes of tabular text: time= 45.3 sec, rate=3339 cps.
Upload 141,299 bytes of JPEG image: time= 95.0 sec, rate=1487 cps.
Using FX to/from my CMD Hard Drive:
Download 156,260 bytes of ~text: time= 83.4 sec, rate=1874 cps.
Download 151,267 bytes of tabular text: time= 75.4 sec, rate=2006 cps.
Download 141,299 bytes of JPEG image: time=118.2 sec, rate=1195 cps.
Upload 156,260 bytes of ~text: time= 77.9 sec, rate=2006 cps.
Upload 151,267 bytes of tabular text: time= 66.2 sec, rate=2285 cps.
Upload 141,299 bytes of JPEG image: time=114.2 sec, rate=1237 cps.
Using DesTerm-128 v2.00 to/from my CMD Hard Drive, Y-Modem:
Download 156,260 bytes of ~text: time=189.5 sec, rate= 824 cps.
Download 151,267 bytes of tabular text: time=180.4 sec, rate= 839 cps.
Download 141,299 bytes of JPEG image: time=199.9 sec, rate= 707 cps.
Upload 156,260 bytes of ~text: time=255.1 sec, rate= 611 cps.
Upload 151,267 bytes of tabular text: time=238.6 sec, rate= 634 cps.
Upload 141,299 bytes of JPEG image: time=233.0 sec, rate= 606 cps.
Using NovaTerm-64 v9.5 to my CMD Hard Drive, Z-Modem, C64 mode:
Download 156,260 bytes of ~text: time=245.8 sec, rate= 636 cps.
Download 151,267 bytes of tabular text: time=230.0 sec, rate= 658 cps.
Download 141,299 bytes of JPEG image: time=262.6 sec, rate= 538 cps.
(There is no Z-Modem uploading support)
So there you have it: my simple protocol blows the others away. QED.
========================================================================
DESIGN AND IMPLEMENTATION OF A 'REAL' OPERATING SYSTEM FOR THE 128: PART II
by Craig S. Bruce <csbruce@ccnga.uwaterloo.ca>
0. PREFACE
There has been a slight change in plans. I originally intended this article
to give the design of a theoretical distributed multitasking microkernel
operating system for the C128. I have decided to go a different route: to
take out the distributed component for now and implement a real multitasking
microkernel OS for a single machine and extend the system to be distributed
later. The implementation so far is, of course, only in the prototype stage
and the application for it is only a demo. Part III of this series will
extend this demo system into, perhaps, a usable distributed operating system.
1. INTRODUCTION
The previous article talked about the general approach to building a
multitasking microkernel OS for the C128. It is assumed here that you have
read and understood the previous article. This article goes into the grungy
details of implementing such a beast. The prototype kernel implementation
provides system calls to create and "exit" user processes, obtain status
information, delay execution of a process for a specified period of time,
and to perform message-passing interprocess communication.
Currently, there is no real memory management, no real device drivers, and no
process-resource reclamation. More "infrastructure" features need to be added
before a command-shell environment or any such thing could be supported,
though not toooo many more; the Commodore-Kernal Server in the demo system
makes the $FFD2 (CHROUT) routine of the Commodore Kernal available to all
other processes in the demo system. It could easily be modified to provide
all of the Commodore-Kernal features to the other processes, thereby giving
us a basic I/O sub-system.
There is also no way to dynamically load external programs, so the test
programs have to be assembled with the kernel code. Loading external programs
in this type of environment has the requirement that the program will have to
be relocated upon being loaded to an address that would only be known at load
time. There are two ways to go on this: load all programs to a fixed address
or load them to dynamic addresses. If you load them to a fixed address, then
you can only have one processes loaded and concurrently running on each bank
of internal memory of the C128 and then demand-swap all of the other processes
into and out of these (two) slots, presumably from REU memory (any other type
would be much too slow). IHMO, even with REU memory, this would be too slow,
especially for a microkernel environment. So, programs will need to be
loaded to dynamic addresses. Fortunately, I have a program-relocation
mechanism in the works.
The entire kernel and the demo program fits in C128 memory in the slot between
$1300 and $1BFF of RAM0. The kernel uses storage from $C00-$CFF and
$2000-$BFFF. The latter section of memory is used up in 768-byte chunks by
each new process, so there can be a total of 53 concurrently executing user
processes in the system.
2. TEST PROGRAM
The test program includes no provisions for user interaction, so it may not
be something that you can impress your friends with, but I can assure you
that all kinds multitasking stuff is going on behind the scenes to make
everything happen.
The demo test program creates ten processes. There are five "delay"
processes, two "blabbering" processes, a Commodore-Kernal-Server process, one
SID-banging process, and the Null process. (Note that when I use the word
"kernel" I am referring to the OS that I have written, and when I use the word
"Kernal", I am referring to the Commodore Kernal in ROM).
The purpose of the Commodore-Kernal Server is to receive requests from the
worker processes to call the CHROUT routine to print a given line of text out
to the screen. The Kernal server is the only processes that is allowed to
call the Commodore-Kernal routines. Since it can only process one request
from a client process at a time, calls to the Commodore Kernal are effectively
"serialized" (made to happen one after another in time), which is good, since
things would blow up pretty badly if two accesses the Commodore Kernal were to
happen concurrently.
The "delay" processes, numbered from 1 to 5, each delay for a period of N
seconds and then request the Kernal Server to print a "I'm alive" message to
the screen. The number N of seconds to delay is the number of the process.
You should be able to observe from watching the execution that each delay
process prints a message to the screen with approximately the correct period
between messages. Note that while these processes are delaying, they don't
use any CPU time, so the CPU time is allocated to other processes. If you
try holding down the C= key to slow the scrolling or run the system in Slow
mode, you will still notice that the delay processes generate their output
at approximately the right time.
The two "blabbering" processes, named "blabber" and "spinner", continually
send print messages to the Commodore-Server process. You will observe that
the messages from each comes pretty much prefectly interleaved with each
other, and with the output of the delay process, because of the interprocess
communication scheduling policy: FIFO (first-in, first-out).
The SID-banging process runs continuously in the background. It increments
the 16-bit frequency of voice #1 from $0000 to $ffff and then suspends its
execution for two seconds and then repeats. A square wave with even pulse
widths is used. When the SID process delays for two seconds, you will notice
that the printing operation of the other processes speeds up a bit. This is
because the SID process is a heavy CPU user while it is active. The amount of
slow-down of the rest of the system is limited a bit because the SID process
runs with a slightly lower priority than the other processes in the system
(which makes the sound increment slightly slower than it otherwise would --
there's only so much CPU to go around).
The Null process is not actually needed in this exercise, but it would
normally be used to insure that the system always had some process to
schedule. All that it does is increment the binary value in locations
$0400-$0403 (on the 40-column screen) whenever it is active. It has the
lowest priority in the system and never gets to execute unless all of the
other processes are blocked (i.e., are suspended for some reason).
When you get tired of watching the demo, you can just hit the RESTORE key.
This will cause an NMI which will make the system exit back to BASIC. The
system does not have the ability to handle external events (like key strokes)
at this time. A couple of locations on the 40-column screen are used for
status information, so you will want to run the demo on the 80-column screen.
3. PROCESS CONTROL
A process is a user program that is in an active state of execution. A
process is periodically given a certain amount of CPU time to execute its
code, and then CPU attention is taken away from it to execute other
processes. This may sound like you're simply making N processes run N times
slower, and this is true in the worst case, but the normal case is that many
processes in the system will be blocked (for whatever reason) and will not
require any more CPU time until they wake up again (for whatever reason).
Therefore, multitasking is a "winnable" proposition.
In our system, the process that the CPU is currently executing is changed
every 1/60 of a second. This is a convenient "quantum" period for a number of
reasons, including the fact that, thanks to the MMU of the C128, "context
switching" can be efficiently performed this quickly.
3.1. PROCESS-CONTROL CALLS
There are six kernel calls that deal with process control:
CALL NAME INPUT ARGUMENTS RETURN VALUES
----------- ------------------------------ -------------------------------
Create ( .AY=address, .X=priority ) .AY=newPid, .CS=err(.A=errcode)
Exit ( .A=code, .X=$00 ) <none>
MyPid ( ) .AY=pid
MyParentPid ( ) .AY=parentPid
Suspend ( ) <none>
Delay ( .AY=jiffies ) <none>
3.1.1. CREATE
The Create() kernel call is used to create a new process. The first input
argument is the code address, and it is passed in the .AY register (.A is
loaded with the low byte of the address, and the .Y register is loaded with
the high byte of the address--.AY for short). The code must be present in
memory and be ready to be executed, since there is no facility for loading
external programs. Also, if the code is not re-entrant, then there must be no
other process already executing it or things will likely blow up. Re-entrant
code is code that can be executed by multiple processes simultaneously without
conflicts, essentially because there are no global variables that could be
banged on by more than one process at a time.
The priority argument is the priority to execute the new process at. Valid
values for this argument are on the range 0 to 127. The system keeps a list
at all times of all the processes that are ready to execute, called the "ready
list". The way that the scheduling works is that a pointer to the "active"
process is kept (the one that is currently executing) and this pointer cycles
through the ready list, trying to activate each process in turn, every 1/60 of
a second. This is roundrobin scheduling. The priority of a process
determines the number of cycles that the active-process pointer has to take
through the list before the process is activated. So, if a process has
priority 1, then it will be activated on every round; if it has a priority of
2, then it will be activated on every second round; and if it has a priority
of 86, then it will be activated only on every 86th round through the ready
list. The higher the priority value, the slower the process executes. This
policy gives a fair allocation of the CPU to the various processes in the
system.
Normally, foreground processes (ones that perform actions right in front of
the user's face) should have a priority of 1, and background processes should
have a relatively lower priority. A priority value of 0 for a process means
that when the process is activated, it will not be deactivated again until it
blocks for some reason. This priority level should be reserved for urgent
computations that block often, since it has the potential to starve out the
rest of the system. The Null process executes at a special priority level
(255) that makes it so that it will only be activated if there are no other
processes in the ready list.
The Create() call returns with the carry flag clear and the process id of the
newly created process in the .AY register upon success, or returns with the
carry flag set and an error code in the .A register upon failure. I do not
have the complete list of error conditions figured out a this time, but errors
will usually happen on a call like this because of a lack of resources
(memory) for the kernel's internal data structures. Upon successful return,
the child process is created, made ready, and may be activated by the system
at any time. The first instruction to be executed by the child will be at the
value given for the code address.
The newly created process will have a clear individual stack, except for a
couple of bytes on the very bottom of it (high addresses), and a clear
individual zeropage. Processes are allowed to make full use of every location
in their zeropage, except for the I/O registers at locations 0 and 1, and full
use of their stack, except that they must make sure that about a dozen bytes
are available on the stack at all times in case an interrupt happens.
3.1.2. EXIT
The Exit() kernel call is used to remove the current process from the system.
There are two input arguments: the .A register contains the return code that
will be made available to the parent process if it is interested (though not
in the current implementation), and a value in the .X register, which must
currently be $00. I haven't figured out exactly how the exit mechanism should
work yet and it currently only has a minimal implementation. The call does
make the kernel reclaim the resources that were allocated to the process yet,
although this functionality will be needed in any real operating system.
There is no return value from the Exit() call, because the call never returns.
The semantics of the call is the the process calling Exit() will never be made
active again. All processes should call Exit() when they are finished
executing, or they can achieve the same result by executing an RTS instruction
at the end of their main routine. The kernel pushes the address of an Exit()
stub routine onto the top of the stack of a user process when it is created,
and the user process will exit with a return code of $00 in this case.
3.1.3. MY_PID
The MyPid() kernel call is used to return the process identifier of the
current process. This call is very simple, takes no arguments, and executes
very quickly. The return value is the process id of the calling process and
is returned in the .AY register. This call cannot fail, because the current
process must exist in order to make the call in the first place, so there is
no error-return condition.
3.1.4. MY_PARENT_PID
The MyParentPid() kernel call is used to return the process identifier of the
parent process of the current process (i.e., the process that created the
current process). This call is simple, takes no arguments, and executes
quickly, very much like the MyPid() call. No error returns are possible, and
the process id of the parent to the current process is returned in the .AY
register. But note: it is not guaranteed that the parent process will still
exist either before or after the current process makes this call; it may have
Exit()ed. I may re-think this semantic.
This call is useful for setting up interprocess communication between a child
process and its parent.
3.1.5. SUSPEND
The Suspend() kernel call is used to suspend the execution of the currently
executing process for an indefinite period of time. Currently, this period of
time is forever, since there is no corresponding "Resume" system call that
another process can call in order to wake up the process that suspended
itself. The reason that this call is made available is because the guts of
what it does is required by other kernel operations, and the cost of making
this call user-accessible was three 6502 instructions. This call may be
retracted in the future, since it may cause programmers to do bad things.
The call takes no arguments, returns no values, and currently, will never
return at all, much like Exit().
3.1.6. DELAY
The Delay() kernel call is used to suspend the execution of the current
process for a user-specified period of time. The delay period is given in
units of jiffies (1/60ths of a second). The unsigned 16-bit delay period is
passed in in the .AY registers, giving a maximum possible delay period of
about 18 minutes. If a user process requests to delay for a period of zero
jiffies, its execution will not be suspended at all and the Delay() primitive
will return immediately.
Since there may be other processes in the system doing things when the current
processes wakes up after doing a delay, you can think of the process delaying
for "at least" the period of time that you specify. Actually, to muddy things
even more, your process will always go to sleep at a moment in time that is
inbetween two ticks of the jiffy clock, so the first "jiffy" that your process
waits may actually be any period between a couple of microseconds to almost a
full jiffy, with a statistical average of half a jiffy. This is an artifact
of any coarse-tick-based mechanism.
To muddy things again, the jiffy ticks, which are currently based on VIC
raster interrupts (one per screen update), may not be processed immediately
when they occur, since the IRQ may be delayed by a small period of time if
interrupts are disabled in the processor status register when the jiffy tick
happens. And finally, you should note that you will have a difficult time
using this call for true "real time" periodic operations, like performing some
specific task precisely every tenth of a second, since the call specifies a
period to delay for, rather than a time to wake up at. The actual period of
your process' activations will be determined by the waiting time plus the time
skew caused by the processing that your process does. A DelayUntil() call
easily could be implemented, if I figure that it will be needed for anything.
Currently, the scheduling policy is to make processes active immediately after
they are awakened, so this makes the activities of other processes less of a
worry to accurate timing. Unix does a similar thing by giving a freshly
awakened process a temporarily high priority, since it is probably likely that
the process will do some small think and then block again. This policy
statistically improves concurrency.
3.2. PROCESS CONTROL BLOCKS
A Process Control Block (PCB) is the data structure that the kernel keeps the
information that it needs to know about a process in. A Process identifier
(pid) is actually the RAM0 address of the process control block of a process,
for convenience, though this will have to change later. The fields of the
process control block are shown here, organized into classes:
OFF SIZ CLASS LABEL
--- --- ----- ------
0 2 queue pcbNext
2 2 queue pcbPrev
4 1 queue pcbIsHead
5 1 queue pcbQCount
6 1 ctxt pcbSP
7 1 ctxt pcbStackPage
8 1 ctxt pcbZeroPage
9 1 ctxt pcbD506
10 1 sched pcbPriority
11 1 sched pcbCountdown
12 2 sched pcbWakeupTime
12 2 ipc pcbSendMsgPtr (overlap)
12 2 ipc pcbRecvMsgPtr (overlap)
14 2 ipc/q pcbSendQHead
16 2 ipc/q pcbSendQTail
18 1 ipc/q pcbSendQFlag
19 1 ipc/q pcbSendQCount
20 2 ipc pcbBlockedOn
22 2 ipc pcbReceiveFrom
24 2 proc pcbParent
26 1 proc pcbState
27 - - SIZE
3.2.1. QUEUE-CLASS FIELDS
The first four fields, of the class "queue" are used for maintaining a process
control block in queues with other PCBs. Some general-purpose queue-handling
routines have been written to make queue management easier: QueueInit(),
QueueInsert(), and QueueUnlink(). Each queue has a head node, and the nodes
in a doubly linked circular order. This means that each node in the queue has
a forward ("pcbNext") and a backward ("pcbPrev") pointer and that the first
node points back to the head and the last node in a list points forward to the
head. This organization removes all of the quirks of handling null pointers
from the code. Using a doubly linked organization makes it easy to remove an
arbitrary node from the middle of a queue.
Each node also has a "pcbIsHead" field which is always False (zero) and a
"pcbQCount" field which is always zero. The head is the same as an entry in
the queue, except that its "pcbIsHead" field is set to True ($ff) and its
"pcbQCount" field records the number of nodes that are in the queue at any
time. The "pcbIsHead" field is checked when scanning a list to tell if you've
bumped back into the head node again, indicating the end of the list. The
"pcbQCount" field is very convenient to check to see whether the queue is
empty or not.
All of the processes that are ready to execute in the system are kept in the
ready queue. The PCB of the Null process acts as the head for this queue, and
is also an active node in the queue (a small but harmless kluge). The pointer
to the active process is kept in a kernel-zero-page variable, and sweeps
through the circularly linked ready-process list to activate new processes.
The active PCB is not removed from the ready list while it is active.
3.2.2. CONTEXT-CLASS FIELDS
The next four fields, of the class "ctxt", store the "context" of a process
that is not stored on the process' stack when it is not executing. These
fields include space for the stack pointer, the stack page, the zeropage, and
the contents of the MMU register at location $d506. The stack pointer is
what was in the SP register of the CPU when the process last paused. The
stack page and the zeropage values are the values in MMU registers $d505 and
$d507, respectively; these are the page numbers of the pages in RAM0 memory
that are allocated to a process. These pages can only be in RAM0 unless
common memory is disabled, for hardware reasons. I may allow these pages to
be in either RAM0 or RAM1 if there is a need later. The $d506 register of
the MMU stores the most-significant bits of the RAM bank that is selected if
you have expanded internal memory on your 128 (a la TwinCities-128) and the
bank selection for REU (DMA) operations.
The rest of a process' context is stored on its stack. Here is what a
process' stack looks like just after it has been created:
ADDR SP-REL DESCRIPTION
---- ------ ------------
$ff sp+09 exitaddr-1.h
$fe sp+08 exitaddr-1.l
$fd sp+07 pc.h
$fc sp+06 pc.l
$fb sp+05 status register
$fa sp+04 .A
$f9 sp+03 .X
$f8 sp+02 .Y
$f7 sp+01 $ff00 save
$f6 sp+00 -empty-
The "exitaddr" is the address of the routine in the kernel that will terminate
a process if it executes an RTS from its main routine. The address is in the
regular low-high order (although it is pushed on high-low since the stack
grows downward in memory) but the value pushed is actually one less than the
address of the routine, because this is what JSR pushes onto the stack and
this is what RTS expects to find. The "pc" low and high fields give the
address of the next instruction to be executed by the process when it is
activated. When the process is first created, this will be the address of the
first instruction. The "pc" value is the actual address, not one before,
because this is what a hardware interrupt pushes onto the stack, and this is
what the RTI instruction expects to find.
The "status register", ".A", ".X", and ".Y" fields contain the values to be
loaded into the corresponding registers inside of the CPU when the process is
activated. For a new process, these values are all zero.
The "$ff00 save" is the value to be loaded into the $ff00 "shadow" register of
the MMU when the process is activated. This gives the memory context that the
process is to execute in. As the kernel currently only works with one bank
configuration (RAM0, NO BASIC ROM, I/O enabled, KERNAL ROM enabled), this is
the value put here when a process is created.
The final field is "-empty-" because the stack pointer in the 6502 points to
the next location in stack memory that will be used. All other values in the
stack are relative to this. Upon startup, the stack-pointer field of the
process control block will be set to $f6, which is what the table above
shows.
The stack contents look exactly the same after a process has been interrupted
by a hardware interrupt, except that the stack pointer will likely be lower in
the stack memory, so the absolute addresses in stack memory in the above table
no longer apply and the "exitaddr" bytes are not part of the interrupt
context. That things look the same is no coincidence; on startup, we set up
the stack to make things look as if an interrupt had just occurred, and to
start a process executing, we execute the code that returns from an interrupt,
which loads the "context" that is on the stack into the process registers, and
we are ready to rock.
The above stack organization is exactly the same as it is for processing
interrupts normally using the Commodore-Kernal environment on the 128, and
this too is no coincidence because the code that sets up the stack like this
upon an interrupt is burned into the Kernal ROM and there is very little that
I can do about it. Fortunately, the organization is just fine for our
purposes.
3.2.3. SCHEDULE-CLASS FIELDS
The next three fields, of class "sched", are used to schedule the process.
The "pcbPriority" field gives the relative priority of the process according
to the scheme already discussed. The "pcbCountdown" field is used to keep
count of the number of remaining times that the process will have to be
bypassed in cycling through the ready queue before the process will be
activated again. When a process gives up the CPU upon the expiration of its
time quantum, the "pcbCountdown" field is loaded with the pcbPriority of the
process. When the "pcbCountdown" value reaches zero, the process is selected
for activation.
The "pcbWakeupTime" field is used with the Delay() kernel call to indicate the
absolute system time when the process should be activated again. The current
time in the system is kept in a 16-bit kernel variable, and wraps around every
18.2 minutes. If the process is not currently time-delayed, then the
WakeupTime field is not used (in fact, the memory may be used to record other
status information).
3.2.4. IPC-CLASS FIELDS
The eight eight fields, of classes "ipc" and "ipc/q" are used for interprocess
communication (message passing). The first two fields, "pcbSendMsgPtr" and
"pcbRecvMsgPtr", are used for storing temporary values for handling message
requests; the four "ipc/q"-class fields are used to implement the head of a
queue of processes that are waiting to communicate with the current process,
and the "pcbBlockedOn" field indicates which process this process is waiting
to communicate with, if the current process is waiting. The first two fields
actually overlap with each other and with the "pcbWakeupTime" field discussed
earlier. This is okay since none of the fields will store active status
information at the same time. The last field, "pcbReceiveFrom" is not used at
this time, but will be used in the future for an primitive to receive a
message only from a specific process. The interprocess communication is
discussed in much greater detail later.
3.2.5. PROC-CLASS FIELDS
The final two fields, of class "proc", store information about the status of
the process. I guess the same can be said of all the other fields. Anyway,
the "pcbParent" field indicates which process is the process that created the
current process, and the return value for the MyParentPid() kernel call is
taken from this field.
The "pcbState" field gives the current state of the process. Here are the
different possible process states:
STATE NAME CODE
--------------- ----
STATE_READY $c0
STATE_SEND $c1
STATE_RECEIVE $c2
STATE_REPLY $c3
STATE_DELAY $c4
STATE_SUSPENDED $c5
The STATE_READY state means that the process is in the ready queue. The
STATE_SEND, STATE_RECEIVE, and STATE_REPLY states mean that a process is
waiting for some interprocess communication primitive to be called by the
process that it is communicating with. The STATE_DELAY state means that the
process has called the Delay() primitive and is waiting for some period of
real time to pass before it can be activated again. The STATE_SUSPENDED state
means that a process has called the Suspend() or Exit() primitive and will
never be made active again (currently, Suspend() and Exit() mean the same
thing).
The state information is needed for some operations, and will definitely be
needed by a Kill()-process operation, to find out what state a process is in
so that it can be removed from any queue or whatever it is in, in order to
obliterate all information about the process from the system. Currently,
there is no Kill() call.
3.3. TASK CREATION
When the user calls for the creation of a new process in the system, lots of
stuff has to happen. First, memory for the process control block, zero page,
and stack page must be allocated. Currently, this allocation is performed
very simply, by keeping a page pointer and incrementing it every time a page
is allocated. The process control block ends up getting allocated 256 bytes
even though it actually requires much less than that. Thus, each new process
chews up 768 bytes of memory space (plus code). Also, there is currently no
mechanism for recovering the memory allocated to a process, which is okay
since the mechanism for Exit()ing a process is incomplete too.
The address that a PCB gets allocated at is used for the process' PID (process
identifier). This is particularly useful since the real purpose of a PID is
to conveniently locate the process control block. This will have to change
in the future, however, since the PIDs will also have to locate the machine
that a process is on.
Then the process control block must be initialized. It is initialized as
follows:
FIELD SIZ CLASS INITIAL VALUE
-------------- --- ----- --------------
pcbNext 2 queue 0
pcbPrev 2 queue 0
pcbIsHead 1 queue 0
pcbQCount 1 queue 0
pcbSP 1 ctxt $f6
pcbStackPage 1 ctxt set to newly allocated space
pcbZeroPage 1 ctxt set to newly allocated space
pcbD506 1 ctxt $04
pcbPriority 1 sched set to the given argument
pcbCountdown 1 sched set to the same value as "pcbPriority"
pcbWakeupTime 2 sched 0 (overloaded field)
pcbSendQHead 2 ipc/q set by the QueueInit() function for empty queue
pcbSendQTail 2 ipc/q set by the QueueInit() function for empty queue
pcbSendQFlag 1 ipc/q set by the QueueInit() function for empty queue
pcbSendQCount 1 ipc/q set by the QueueInit() function for empty queue
pcbBlockedOn 2 ipc 0
pcbReceiveFrom 2 ipc 0
pcbParent 2 proc set to the id of the creator process
pcbState 1 proc STATE_SUSPENDED
The values on the top of the stack page are also initialized for the new
process, as follows:
ADDR SP-REL DESCRIPTION INITIAL VALUE
---- ------ --------------- --------------
$ff sp+09 exitaddr-1.h high byte of ExitAddr-1: the exit routine
$fe sp+08 exitaddr-1.l low byte of ExitAddr-1: the exit routine
$fd sp+07 pc.h high byte of the code-execution address
$fc sp+06 pc.l high byte of the code-execution address
$fb sp+05 status register $00
$fa sp+04 .A $00
$f9 sp+03 .X $00
$f8 sp+02 .Y $00
$f7 sp+01 $ff00 save $0e (Kernal ROM, I/O, rest RAM0)
$f6 sp+00 -empty- --
And now, the new process is ready for action. We insert it into the ready
queue in the next position after the current process, set its state to
STATE_READY (actually, both of these operations are performed by the
MakeReady() function, which is generally useful and is called from a number of
places) and then we exit back to the calling process, returning the process id
of the calling process. I should change this a little bit in the future, to
make it exit to the newly created child process if the priority of the child
process is greater than the priority of the parent.
3.4. CONTEXT SWITCHING
Context switching describes the procedure of switching control of the
processor from a user process to the kernel and then switching control back to
a user process. Normally, there is only one "style" of context switching in a
system, but for a couple of design reasons, BOS actually has three "styles" of
context switching: IRQ switching, JSR switching, and quick JSR switching.
IRQ-style switching is the one type normally implemented in operating systems
for other architectures, so it will be the one that we cover first.
IRQ-style context switching involves saving the full context of a process onto
its stack and into its process control block, switching into the kernel, doing
work, switching back out of the kernel, and reloading the full context of a
user process and activating to it. All of the work of saving and restoring
the the stack portion of a process' context is handled by the ROM routines for
IRQ (and NMI and BRK) handling. All we have to do is locate the current
process control block, save the zero-page, stack-page, stack-pointer, and
$d506 registers into the PCB, and load a $00 into the zero-page MMU register
to switch to the kernel's zeropage (where some of the kernel's variables are
stored). Note that the interrupt will be executed using the user process'
stack; therefore, enough space should always be available on user stacks to
handle this system overhead.
When we are done processing the interrupt, we execute the priority-management
algorithm that was described earlier to select the next process to activate,
and then restore the zero-page, stack-page, stack-pointer, and $d506 registers
and execute the ROM stack-handling code for exiting from an interrupt. Note
that there's a chance that we might well be exiting to a different user
process from the one that was active when the interrupt occurred. There
aren't many registers to save and restore, so context switching has a fairly
low overhead, so there is no problem in doing it (at least) sixty times a
second.
JSR-style context switching is pretty much the same as IRQ-style context
switching, except that the stack will not have most of the processor registers
already saved on it; it will only have the return address that performed the
JSR. Immediately upon entering the kernel, interrupts are disabled to prevent
all sorts of bad things from happening. Then a function is called,
EnterKernel(), which will pull the return address of the process that called
the JSR off the stack and increment it by one (since we will be exiting by
using an RTI instruction rather than an RTS) and saves the other processor
registers onto the stack in the same way that the interrupt-handling code in
ROM would. Then we save the four additional registers into the PCB as before,
activate the kernel zeropage, and we are switched in.
This style of context switching is used for kernel calls that will cause the
calling process to block (like a non-zero Delay()). It would have been
possible to organize the kernel calls to be entered by executing a BRK
instruction, which would have caused the stack to be already set up in the
same way as with IRQ interrupts, but I decided against this for two reasons:
efficiency, it would have been slower to do this, and debugging (security?),
since I only want the BRK condition to signal a bug in the code. The exit
from this type of context switch is the same as for the IRQ style of context
switch, since things are rigged to end up looking the same on the stack. This
is a good thing, since the action that will cause a Delay()ed process to be
re-activated will, in fact, be an IRQ interrupt.
Quick JSR-style context switching is used for kernel calls that will not block
or cause a new process to be activated when they finish, such as MyPid() or
(currently) Create(). No context has to be saved since the function will get
in and out very quickly; all we have to do is switch to the kernel's zeropage
and then switch back to the user's zeropage before exit.
There's one more note to make about return values. For the quick JSR-style
context switch, there is no problem with return values, since we just have to
load them into the processor registers and exit. With the full JSR-style
context switch, the return values have to be put onto the user stack into the
positions in the stack memory the hold the processor register contents, since
these values will be what are restored into the processor immediately upon the
return to the user process. There are no return values associated with the
IRQ style of context switching (and there'd better not be), since an interrupt
can happen at any point in the execution of a user process.
3.5. DELAY PRIMITIVE
There are two complementary halves to the implemention of the Delay()
primitive: the half that is called by the user and causes a process to go to
sleep, and the half that wakes up a sleeping process at the correct time.
This latter half is executed by the 60-Hz system interrupt.
3.5.1. USER HALF OF THE DELAY PRIMITIVE
The first thing that the user half of the Delay() primitive does is check to
see if the delay period is zero jiffies. If it is, then the primitive returns
immediately to the calling process without rescheduling (without skipping to
the next ready process in line). I may change this semantic, because it is
often useful to have a primitive that yeilds process execution to the next
ready process without actually blocking the current process.
If the delay period is longer than zero jiffies, then the current process is
suspended and removed from the ready queue, and the absolute time that the
process is to be reawakened is calculated and put into the "pcbWakeupTime"
field of the PCB for the current process. The absolute wakeup time is
calculated, of course, by adding the number of jiffies to delay to the current
absolute time, which is maintained by the system and incremented on every
(60 Hz) system interrupt.
Then the current process control block is inserted into the delay queue at the
correct position. The delay queue is a queue (implemented in the standard
way) of process control blocks for processes which are asleep, ordered by the
absolute wakeup time of each process such that the process that will be
awakened at the nearest time in the future is at the head of the list and that
the process which will be awakened at the farthest point in the future is at
the tail. The following diagram gives an example:
CurrentTime = 2016
+---------+ +---------+ +---------+ +---------+
--->| Proc A |----->| Proc B |----->| Proc C |----->| Proc D |
| wakeup: | | wakeup: | | wakeup: | | wakeup: |
<---| @ 2345 |<-----| @ 2765 |<-----| @ 54999 |<-----| @ 441 |
+---------+ +---------+ +---------+ +---------+
(ct+5.5sec) (ct+12.5sec) (ct+14.7min) (ct+17.8min)
There is a rub here: only 16 bits are used for storing times, which equals
about 18.2 minutes, so we have to worry about time quantities overflowing and
wrapping around. For example, if the current time is 48232 and a process
wants to sleep for 18000 jiffies (5 minutes), then its wakeup time would be at
696 jiffies, accounting for the 16-bit wraparound, which is a lower numerical
value than the current time, or than the wakeup time of any other process that
will wake up before the current-time wraparound. In fact, all timers have
this wraparound problem (although with 64-bit times, wraparound periods would
be expressed in millions of millennia rather than in minutes). Sixteen bits
is a good number of bits to use, however, because that is the maximum delay
period (2^16-1).
When we insert a new process into the delay queue, we scan the delay queue
from the head and continue until we find a record that has a time that is
higher than or equal to the wakeup time of the new process (or we hit the end
of the queue). Then, we insert the new process immediately before this
point. To handle the wraparound problem, all comparisons of wakeup times are
done using 17 bits (well, really 24 bits). For each value in the comparison,
we add 65536 to it (set its 17th bit) if the value is less than the current
time. We don't have to worry about the current time changing while we are
doing this, because interrupts will be disabled for the entire time that
we are executing the system call, as per usual. Things could go horribly
wrong anyway if interrupts were not disabled.
Okay, so now our delaying process is removed from the ready queue, its
complete context is saved, and it is put into the delay queue at the right
spot. So, set the active process pointer to the next ready process in the
system and finish by activating the next ready process.
3.5.2. SYSTEM HALF OF THE DELAY PRIMITIVE
During each 60-Hz system interrupt, the current time (jiffy counter) is
incremented by one. Note that since this timer is only 16 bits wide, it is
not suitable for keeping track of the current time of day; for this purpose,
the TOD clocks in the CIA chips should (and will) be used. The jiffy counter
may also be inaccurate if interrupts are disabled for a long period of time,
such as they are during some Commodore-Kernal I/O operations.
After incrementing the time, the kernel checks to see if any Delay()ed
processes need to be woken up. If there are no processes in the delay queue,
then this is a quick check. If there are any processes in the queue, then if
the wakeup time of the head process is equal to the current time, then that
process is woken up and this check is performed repeatedly until the condition
fails, since there may be multiple processes that want to be woken up at the
same jiffy of absolute time. Note that because of the scheduling for a
freshly unblocked process, the process that Delay()ed first will be the
first one activated after it is woken up, if there are multiple processes
woken up at the start of the same jiffy.
3.6. SYSTEM BOOTSTRAPPING
Operating systems always have a bootstrapping problem, because you always need
to use the services of the operating system in order to start it up, but, of
course, it's not started up yet, chicken and egg, catch-22. So, what usually
ends up happening is that you just "fake it", start from somewhere, get the
ball rolling, and snowball up to a fully running system.
The first thing that the kernel does is change all of the interrupt vectors
(IRQ, NMI, and BRK) to my custom routines. I need to cover all of the
interrupts, since I chave the zero page during the execution of the system,
and if a BRK or NMI were to happen and be serviced by the Commodore-Kernal ROM
routines, all hell would break loose. Currently, the NMI and BRK routines
just clean things up and return to BASIC.
Then we initialize the kernel variables, including the delay queue and the
jiffy counter.
And then we fake the creation of the Null process. For the purposes of
bootstrapping, the Null process doubles as the "Boot" process. Its process
control block is not allocated in the normal way, either; it is at a fixed
location, and its PCB doubles as the head of the process list. A kluge here
and a hack there and the Null process is initialized and "joined in
progress". Then, the Null process creates the Init process, using a standard
call to the Create() primitive, and then the Null process goes into an endless
loop of incrementing the 32-bit value at addresses $400-$403, the first four
locations of the 40-column screen memory. It doesn't matter whether you run
BOS with the clock in Fast or Slow mode, except in terms of performance.
It is the responsibility of the Init process to start up all of the user
processes in the user application after Init starts running. In the current
implementation, Init starts up all of the other processes in the test
application and then becomes the Commodore-Kernal Server, which is a
convenient organization, since all of the other processes can find out the pid
of the Kernal Server merely by calling MyParentPid().
4. INTERPROCESS COMMUNICATION
In this system, processes are not strictly independent and competitive; many
must cooperate and comunicate to get work done. To facilitiate this
interprocess communication (IPC), a particular paradigm was chosen: the Remote
Procedure Call (RPC) paradigm. RPC is a message-passing scheme that is used
with the much-hyped Client/Server system-architecture model. Its operation
parallels the implicit operations that take place whe
n you call a local
procedure (a subroutine).
The RPC message-passing paradigm is also coupled with a shared-memory paradigm
to offer greater performance for passing around massive amounts of data. All
processes in the system (and in the entire distributed system when this OS is
extended) have global access to all of the memory in the system. The coupling
of the two paradigms is such that you get the best of both worlds: the
convenence and natural interprocess *coordination* (synchronization) semantics
of RPC and the convenience and raw performance of shared storage.
4.1. MESSAGE-PASSING CALLS
The kernel provides three primitives for message passing:
CALL NAME INPUT ARGUMENTS RETURN VALUES
----------- ------------------------------ -------------------------------
Send ( .AY=msgHead ) .CS=err(.A=errcode)
Receive ( .AY=msgHead ) .AY=senderPid
Reply ( .AY=msgHead[msgRet,msgData] ) .CS=err(.A=errcode)
These calls will send a message from one process (the client) to another
process (the server) and wait for a reply, receive a message from another
process (a client), and reply to a message sent from another process (a
client) that has been received, respectively.
4.1.1. MESSAGE-HEADER DATA STRUCTURE
Each of the message-passing primitives requires a pointer to a message-header
data structure that is stored in the user program's data space. The message
header must be initialized with appropriate values before a message can be
sent. Note that this scheme of passing a pointer to a message header allows
you to have multiple message headers lying around, initialized and ready for
action, and you can easily pick between them. Here is what a message header
looks like:
OFF SIZ CLASS LABEL
--- --- ----- ------
0 2 pid msgTo
2 2 pid msgFrom
4 4 buf msgBuf
8 2 buf msgLen
10 4 buf msgRepBuf
14 2 buf msgRepLen
16 1 data msgOp
17 1 data msgRet
18 2 data msgObj
20 4 data msgData
24 - - SIZE
You should not put too much faith in the offsets of the fields in the data
structure remaining static; you should always use the label to access the
fields of the structure, as in:
sta myMessageHeader+msgTo+0
sty myMessageHeader+msgTo+1
4.1.1.1. PID-CLASS FIELDS
The first two fields, of class "pid", are used to identify the processes
involved in an RPC interaction. The "msgTo" field is the pid of the process
that a message is to be/has been sent to, and the "pcbFrom" field is the id of
the process which a message has been received from. For security reasons, the
sender does not fill in the "pcbFrom" field; the kernel does after the message
has been sent and the sender is blocked. (Or else the sender could fake being
someone else). The "pcbTo" field is used as the destination for when a
message is being sent and must be filled in with a legitimate value on a send
operation, and the "pcbFrom" field is used as the destination when a message
is being replied to, and must be filled in with a legitimate value on a reply
operation. The "pcbTo" field is the only field of the message header that
actually needs to have a legitimate value before a message can be sent.
4.1.1.1. BUF-CLASS FIELDS
The next four fields, of class "buf", point out the send and reply buffers in
memory and the sizes of each. The send buffer ("msgBuf"/"msgLen") is expected
to point to a region of near/far memory that contains valid data for a send
operation, and the reply buffer ("msgRepBuf"/"msgRepLen") is expected to point
to a valid area of memory for the server to fill in with any bulky result data
from an RPC request. Each of the message-buffer pointers is four bytes in
size to allow for future expansion when the kernel will support "far" memory
that will be accessed through 32-bit pointers. User processes are expected to
access these "far" buffers directly themselves, through the global shared
memory. This eliminates the system overhead of uselessly copying bulky data
from place to place.
There are two special notes to make about there "buf" fields. First, they
don't actually have to be used how they're intended to be used. as long as
both the client and the server agree on what the contents of these fields are
supposed to mean. In this respect, the fields can be used to quickly pass
twelve bytes of completely arbitrary information. This is useful because many
RPCs only require that a small amount of information be transferred from one
process to another, or at least that bulky data be passed in only one
direction (like read or write), so that one of the buffer pointers is free to
be used quick, tiny data.
Second, on the sending side, the "buffer" that is pointed to does not have to
be a "buffer" at all; it can be an arbitrary data structure that has an
arbitrary number of pieces, scattered throughout the global memory of the
system. The only responsibility of the sender is to insure that no one else
will be attempting to modify the shared data simultaneously while the server
is accessing it. This scheme is quite ingenious, I think (thank you, thank
you). (The scheme may appear to have a security leak in the design, but our
system has no real hardware security anyway).
The expected usage of buffers will be for the sender to use near memory for
the request and reply buffers and access them as regular near memory to
construct and interpret request and reply messages. The receiver will (in the
future) access the buffers as far memory (which they may very well be since
processes will be allowed to execute on different banks of internal memory and
even on different machines), and may wish to fetch parts of messages into near
memory for processing. The use of far pointers makes it so that data is
copied only when necessary, and copied only once.
4.1.1.3. DATA-CLASS FIELDS
The final four fields, of class "data", are intended to be used to
conveniently pass small amounts of arbitrary data. This data can be
arbitrary, but the fields do have a convention that should usually be
followed, unless both parties agree to an alternative usage.
The "msgOp" field is intended to be the "operation code" that a client process
wishes a server to execute. The "msgRet" field is intended to be the return/
error code that is returned from the server to the client upon completion of
an operation. The "msgObj" field is intended to be used by the client to
indicate which of the server's "objects" the client wishes to perform the
operation on. And the "msgData" field is intended to contain four bytes of
arbitrary user data that is passed in with an operation and is passed back
from the server to give return values. In the spirit of these semantics, the
data in all of the fields is send with a request, but only the data in the
"msgRet" and "msgData" fields is passed back in a reply operation. None of
the other fields are passed back in a reply operation (the field values will
remain how they were before the send, for the sender). Take special note that
the "msgRepLen" field will not be passed back; if there is less data returned
than was asked for by an operation, you will have to encode the "actual"
reply-buffer length into the "msgData" field.
4.1.2. SEND
Send() is used to transmit a message to a remote process and get back a reply
message. The .AY register contains the near-memory address of the message
header, which must have its "msgTo" field filled in to be the pid of the
process that the message is being sent to. The sending process will suspend
its execution while it is waiting for remote process to process its request.
If there is to be bulky reply data for the request (such as there would be for
a "read" request to a file server), then space for the reply buffer must be
allocated and indicated in the message header. The reply-buffer space should
normally be owned by the sender.
If there is an error in passing the message, the the error return will be
indicated by the carry flag being set and the error code will be returned in
the .A register. Some possible errors will be, in the future: destination
process is not valid, and that destination process died before receiving/
replying to your message. (These conditions are not currently checked). Also
in the future, this call will work completely transparently for passing
messages between machines in a network.
4.1.3. RECEIVE
Receive() is used to receive a message transmitted by a remote process to the
current process. The receiver will block until another process does a
corresponding Send() operation, and then the message header sent by the sender
will be retrieved into the message-header buffer pointed to by the .AY
register, for this call. No error returns are possible. The pid of the
sending process will be returned in the .AY register as well as in the
"msgFrom" field of the receive-message-header buffer. The receiver is then
expected to eventually call the Reply() primitive to re-awaken the sender.
The receiver is free to do anything it wants to after receiving a message from
a process, including receiving messages from other processes. Messages are
received from other processes in FIFO order.
A similar ReceiveSpecific() primitive may be provided in the future. It would
only accept a message from a specifically named process and would enqueue all
other messages that are received before the specific message, to be received
later.
4.1.4. REPLY
Reply() is used to re-awaken a process that sent a message that was Receive()d
by the current process. The current process is expected to have set up the
return information in the reply-message-header buffer and the reply buffer
area according to the client's wishes before calling the Reply() primitive.
The near address of the reply-message-header buffer is loaded into the .AY
register as an argument to the call. Only the "msgFrom", "msgRet", and
"msgData" fields need to have values. The "msgFrom" field identifies the
process to send the reply message to, and that process must be in the state of
waiting for a reply from the Reply()ing process, or an error will be
returned. An error is indicated by the carry flag being set on return and the
error code is loaded in the .A register. In the case of an error, no action
will have been performed by the system.
4.2. IMPLEMENTATION
The fields of the process control block that are used for message passing
are restated here:
OFF SIZ CLASS LABEL
--- --- ----- ------
12 2 ipc pcbSendMsgPtr (overlap)
12 2 ipc pcbRecvMsgPtr (overlap)
14 2 ipc/q pcbSendQHead
16 2 ipc/q pcbSendQTail
18 1 ipc/q pcbSendQFlag
19 1 ipc/q pcbSendQCount
20 2 ipc pcbBlockedOn
22 2 ipc pcbReceiveFrom
The "pcbBlockedOn" field is used to allow Reply() to verify that the pid it is
instructed to send a reply message to is indeed waiting for a reply from the
task calling Reply(). The "pcbSendQ*" fields constitute a queue head for a
list of process control blocks that are waiting to send a message to the
current process. The "pcbSendMsgPtr" and "pcbRecvMsgPtr" fields are used to
save the message data parameters of a Send() or Receive() call, respectively,
when it has to be suspended without a transfer of the message header. When
the other process involved performs the corresponding operation, the first
process' header buffer pointer is recovered from its process control block.
The "pcbReceiveFrom" field is unused at this time.
The process states of STATE_SEND, STATE_REPLY, and STATE_RECEIVE are used with
message passing. The STATE_SEND state means that the current process has sent
a message to a server process and is waiting for it to do a Receive(). The
STATE_REPLY state means that the current process has sent a message to a
server process, the message has been Receive()d, and that the current process
is waiting for the server process to perform a Reply(). The STATE_RECEIVE
state means that the current process has performed a Receive() and is waiting
for some other process to perform a corresponding Send(). These state
names/meanings may be a bit inconsistent; deal with it.
The implementation of the actual Send(), Receive(), and Reply() operations is
actually quite straight-forward. Both Send() and Receive() have to handle two
possibile situations: either the other process involved has already performed
its corresponding operation and is waiting, or it has not. Reply() is
simplified in that it knows that the sender is already waiting for its reply
so it can proceed to copy the reply-message-header contents directly.
The Send() primitive (will) checks the given destination pid for validity and
then checks the state of the recipient process. If the recipient process is
in STATE_RECEIVE, the Send() function copies the message-header contents
directly to the receive-header buffer of the recipient. The address of the
receive-header buffer is taken from the "pcbRecvMsgPtr" field of the
receiver's process control block in this case. The receiver's return value
(the sending process' pid) is set up (on the receiving process' stack) and the
receiver is awakened while the sender is put to sleep, in STATE_REPLY state
(since the receive has already happened, it is waiting for the corresponding
Reply()).
If the recipient process is not in the STATE_RECEIVE state, then the sending
process will have to wait for the recipient to perform a Receive(). The
sender's message-header buffer address is stored into its process control
block, the sender's process control block is linked into the recipient
process' "pcbSendQ*", and the sender is put to sleep, in the STATE_SEND
state.
The Send() function does not set up the return value for the user's
system call since that will not be known until another process performs the
corresponding Reply(). A return value is set up immediately only in the case
of an error. The possible error returns from Send() are: invalid pid and
reply too long (in which case the reply is truncated).
The Receive() primitive first checks its "pcbSendQ*" to see if any processes
have already tried to send a message to the receiver. If there is a process
there, the sender's process control block is removed from the head of the send
queue then the sender process' state is changed to STATE_REPLY and the sent
message-header contents (dereferenced by the sender's "pcbSendMsgPtr" pointer)
are copied into the receiver's message-header buffer. The Receive() primitive
then exits returning the pid of the sender. No error returns are possible.
If there is no process enqueued in the recipient process' "pcbSendQ*", then
the receiving process is put to sleep in the STATE_RECEIVE state and its
message-header buffer pointer is copied into its process control block.
The Reply() primitive verifies that the destination process is valid (but not
in the current implementation) and is actually awaiting a reply from the
replying process. If not, it craps out. Otherwise, it copies the two
message-header fields and awakens the sender. The return value of the sender
is (already) set up to be carry-clear (no error) and the Reply() primitive
returns error-free too.
The Exit() kernel call does not currently recover from a process performing a
Receive() and then Exit()ing before performing the corresponding Reply().
Some care will have to be taken to insure that all process involved in IPC can
consistently recover if one of the processes gets blown away, for whatever
reason (including Exit()). Such consistent recovery has to be carefully
thought out for any kind of operating system; however, since there are only a
small number of kernel concepts in this one, consistent recovery is that much
easier to insure.
5. CONCLUSION
So there ya have it; the start of a real operating system for the Commodore
128. What the operating system needs in terms of features is to be extended
to execute processes on any bank of internal memory, to access far memory, and
to be distributed so that it will work across multiple hosts. What it needs
in terms of software is: device drivers, a command shell, utility programs,
and an assembler that can produce relocatable code. Oh where, oh where shall
I ever find such software??? ;-)
------------------------------------------------------------------------------
APPENDIX A. SOURCE-CODE LISTING
The source code follows. Extract everything between the "-----=-----" lines
and save into a file named "bos.s" (or whatever) and then run it through the
ACE assembler to generate the executable program (which is also included below
for your convenience). The ACE assembler is available for free with the
ACE-128/64 system.
I have not gone through and fully documented the source code, since I have
been sitting on this program for quite a while and am in a rush to get it out
the door. Besides, the functionality of each important component has already
been discussed.
-----=-----
;simple multitasking kernel by Craig Bruce, started 25-Oct-1994.
;This program is written in the ACE-Assembler format.
org $1300
jmp main
;======== declarations ========
pcbNext = 00 ;(2) mgmt
pcbPrev = 02 ;(2) mgmt
pcbIsHead = 04 ;(1) mgmt
pcbQCount = 05 ;(1) mgmt
pcbSP = 06 ;(1) ctxt
pcbStackPage = 07 ;(1) ctxt
pcbZeroPage = 08 ;(1) ctxt
pcbD506 = 09 ;(1) ctxt
pcbPriority = 10 ;(1) sche
pcbCountdown = 11 ;(1) sche
pcbWakeupTime = 12 ;(2) sche (overlap)
pcbWaitEvent = 12 ;(1) sche (overlap)
pcbSendMsgPtr = 12 ;(2) sche (overlap)
pcbRecvMsgPtr = 12 ;(2) sche (overlap)
pcbSendQHead = 14 ;(2) ipc
pcbSendQTail = 16 ;(2) ipc
pcbSendQFlag = 18 ;(1) ipc
pcbSendQCount = 19 ;(1) ipc
pcbBlockedOn = 20 ;(2) ipc
pcbReceiveFrom = 22 ;(2) ipc
pcbParent = 24 ;(2) proc
pcbState = 26 ;(1) proc
pcbSize = 27
STATE_READY = $c0
STATE_SEND = $c1
STATE_RECEIVE = $c2
STATE_REPLY = $c3
STATE_DELAY = $c4
STATE_SUSPENDED = $c5
STATE_EVENT = $c6
KERN_ERR_OK = $e0
KERN_ERR_PID_NOT_REPLY = $e1
msgTo = 0 ;(2)
msgFrom = 2 ;(2)
msgBuf = 4 ;(4)
msgLen = 8 ;(2)
msgRepBuf = 10 ;(4)
msgRepLen = 14 ;(2)
msgOp = 16 ;(1)
msgRet = 17 ;(1)
msgObj = 18 ;(2)
msgData = 20 ;(4)
msgSize = 24
queueHeadSize = 6
nullPcb : buf pcbSize
delayQueue : buf queueHeadSize
jiffyTime : buf 2
activePid = 02 ;(2)
p = 04 ;(2)
q = 06 ;(2)
pcbPtr = 08 ;(2)
msgPtr = 10 ;(2)
pageAlloc = 12 ;(1)
;Stack: ($ff) : exitaddr-1.h
; ($fe) : exitaddr-1.l
; ($fd) sp+07: pc.h
; ($fc) sp+06: pc.l
; ($fb) sp+05: status register
; ($fa) sp+04: .A
; ($f9) sp+03: .X
; ($f8) sp+02: .Y
; ($f7) sp+01: $ff00 save
; ($f6) sp+00: -empty-
bkBOS = $0e
bkUser = $0e
bkSelect = $ff00
vic = $d000
sid = $d400
mmuZeroPage = $d507
mmuStackPage = $d509
IrqExit = $ff33
; Create ( .AY=address, .X=priority ) : .AY=pid
; Exit ( .A=code, .X=$00 )
; MyPid ( ) : .AY=pid
; MyParentPid ( ) : .AY=parentPid
; Suspend ( )
; Delay ( .AY=jiffies ) : .CS=err
; Send ( .AY=msgBuf ) : .CS:.A=err
; Receive ( .AY=msgBuf ) : .AY=senderPid
; Reply ( .AY=msgBuf[msgRet,msgData] ) : .CS:.A=err
;======== kernel code ========
main = *
sei
;** entry
lda #bkBOS
sta bkSelect
;** set interrupt vectors
lda #<IrqHandler
ldy #>IrqHandler
sta $0314
sty $0315
lda #<BrkHandler
ldy #>BrkHandler
sta $0316
sty $0317
lda #<NmiHandler
ldy #>NmiHandler
sta $0318
sty $0319
;** initialize delay queue
lda #0
sta jiffyTime+0
sta jiffyTime+1
lda #<delayQueue
ldy #>delayQueue
sta q+0
sty q+1
jsr QueueInit
;** initialize null/boot process
lda #<nullPcb
ldy #>nullPcb
sta nullPcb+pcbNext+0
sty nullPcb+pcbNext+1
sta nullPcb+pcbPrev+0
sty nullPcb+pcbPrev+1
sta activePid+0
sty activePid+1
lda #$ff
sta nullPcb+pcbIsHead
lda #0
sta nullPcb+pcbQCount
lda #>$2000
sta pageAlloc
lda #STATE_READY
sta nullPcb+pcbState
lda #2
sta nullPcb+pcbPriority
cli
jmp Null
Null = *
;** create init process
lda #<Init
ldy #>Init
ldx #1
jsr Create
;** go into endless loop
- inc $0400
bne +
inc $0401
bne +
inc $0402
bne +
inc $0403
+ jmp -
NmiHandler = *
BrkHandler = *
Shutdown = *
;** restore interrupt vectors
sei
lda #<$fa65
ldy #>$fa65
sta $0314
sty $0315
lda #<$fa40
ldy #>$fa40
sta $0318
sty $0319
ldx #250
txs
lda #$00
sta mmuZeroPage
sta mmuZeroPage+1
ldx #$01
stx mmuStackPage
sta mmuStackPage+1
lda #%00000100
sta $d506
cli
jmp $4db7
zpSave : buf 1
createAddr : buf 2
createPriority : buf 1
createZeropage : buf 1
createStack : buf 1
createPcb : buf pcbSize
Create = * ;( .AY=address, .X=priority ) : .AY=pid
sei
;** switch in
sta createAddr+0
sty createAddr+1
stx createPriority
lda mmuZeroPage
sta zpSave
lda #$00
sta mmuZeroPage
;** allocate resources
lda #$00
ldy pageAlloc
sta pcbPtr+0
sty pcbPtr+1
iny
sty createZeropage
iny
sty createStack
iny
sty pageAlloc
cpy #>$c000
bcc +
brk ; recover gracefully from the condition of running out of memory
+
;** initialize pcb
;** pcbNext ;(2) mgmt := 0
;** pcbPrev ;(2) mgmt := 0
;** pcbIsHead ;(1) mgmt := 0
;** pcbQCount ;(1) mgmt := 0
;** pcbSP ;(1) ctxt := $f6
;** pcbStackPage ;(1) ctxt := new
;** pcbZeroPage ;(1) ctxt := new
;** pcbD506 ;(1) ctxt := $04
;** pcbPriority ;(1) sche := given
;** pcbCountdown ;(1) sche := priority
;** pcbWakeupTime ;(2) sche := 0
;** pcbSendQHead ;(2) ipc := QueueInit
;** pcbSendQTail ;(2) ipc := QueueInit
;** pcbSendQFlag ;(1) ipc := QueueInit
;** pcbSendQCount ;(1) ipc := QueueInit
;** pcbBlockedOn ;(2) ipc := 0
;** pcbReceiveFrom ;(2) ipc := 0
;** pcbParent ;(2) proc := creator
;** pcbState ;(1) proc := STATE_SUSPENDED
ldx #pcbSize-1
lda #$00
- sta createPcb,x
dex
bpl -
lda #$f6
sta createPcb+pcbSP
lda createStack
sta createPcb+pcbStackPage
lda createZeropage
sta createPcb+pcbZeroPage
lda #$04
sta createPcb+pcbD506
lda createPriority
sta createPcb+pcbPriority
sta createPcb+pcbCountdown
lda activePid+0
ldy activePid+1
sta createPcb+pcbParent+0
sty createPcb+pcbParent+1
lda #STATE_SUSPENDED
sta createPcb+pcbState
ldy #pcbSize-1
- lda createPcb,y
sta (pcbPtr),y
dey
bpl -
lda pcbPtr+0
clc
adc #pcbSendQHead
sta q+0
lda pcbPtr+1
adc #0
sta q+1
jsr QueueInit
;** initialize new stack
;** Stack: ($ff) : exitaddr-1.h := >ExitAddr
;** ($fe) : exitaddr-1.l := <ExitAddr
;** ($fd) sp+07: pc.h := >Addr
;** ($fc) sp+06: pc.l := <Addr
;** ($fb) sp+05: status register := $00
;** ($fa) sp+04: .A := $00
;** ($f9) sp+03: .X := $00
;** ($f8) sp+02: .Y := $00
;** ($f7) sp+01: $ff00 save := $0e
;** ($f6) sp+00: -empty-
lda #$00
ldy createStack
sta p+0
sty p+1
ldy #$f6+1
lda #bkUser
sta (p),y ;$ff00
iny
ldx #4
lda #$00
- sta (p),y
iny
dex
bne -
lda createAddr+0
sta (p),y
iny
lda createAddr+1
sta (p),y
iny
lda #<DefaultExit-1
sta (p),y
iny
lda #>DefaultExit-1
sta (p),y
;** make new process ready
jsr MakeReady
;** switch out
lda pcbPtr+0
ldy pcbPtr+1
ldx zpSave
stx mmuZeroPage
clc
cli
rts
MakeReady = * ;( (pcbPtr)=pcb ) ;after activePid
ldy #pcbState
lda #STATE_READY
sta (pcbPtr),y
lda #<nullPcb
ldy #>nullPcb
sta q+0
sty q+1
lda activePid+0
ldy activePid+1
sta p+0
sty p+1
jsr QueueInsert
rts
QueueInit = * ;( (q)=queueHead )
lda q+0
ldy q+1
sta queueInitVals+pcbNext+0
sty queueInitVals+pcbNext+1
sta queueInitVals+pcbPrev+0
sty queueInitVals+pcbPrev+1
lda #$ff
sta queueInitVals+pcbIsHead
lda #0
sta queueInitVals+pcbQCount
ldy #queueHeadSize-1
- lda queueInitVals,y
sta (q),y
dey
bpl -
rts
queueInitVals : buf queueHeadSize
QueueInsert = * ;( (q)=queueHead, (p)=nodeToInsertAfter, (pcbPtr)=newItem )
;** q->count +:= 1
clc
ldy #pcbQCount
lda (q),y
adc #1
sta (q),y
;** pcbPtr->next := p->next
ldy #pcbNext
lda (p),y
sta (pcbPtr),y
iny
lda (p),y
sta (pcbPtr),y
;** pcbPtr->prev := p
iny
lda p+0
sta (pcbPtr),y
iny
lda p+1
sta (pcbPtr),y
;** p->next->prev := pcbPtr
ldy #pcbNext
lda (p),y
sta q+0
iny
lda (p),y
sta q+1
ldy #pcbPrev
lda pcbPtr+0
sta (q),y
iny
lda pcbPtr+1
sta (q),y
;** p->next := pcbPtr
ldy #pcbNext
lda pcbPtr+0
sta (p),y
iny
lda pcbPtr+1
sta (p),y
rts
QueueUnlink = * ;( (q)=queueHead, (pcbPtr)=node ) ;uses p
;** pcbPtr->next->prev := pcbPtr->prev
ldy #pcbNext
lda (pcbPtr),y
sta p+0
iny
lda (pcbPtr),y
sta p+1
ldy #pcbPrev
lda (pcbPtr),y
sta (p),y
iny
lda (pcbPtr),y
sta (p),y
;** pcbPtr->prev->next := pcbPtr->next
ldy #pcbPrev
lda (pcbPtr),y
sta p+0
iny
lda (pcbPtr),y
sta p+1
ldy #pcbNext
lda (pcbPtr),y
sta (p),y
iny
lda (pcbPtr),y
sta (p),y
;** q->count -:= 1
ldy #pcbQCount
lda (q),y
sec
sbc #1
sta (q),y
rts
IrqHandler = *
cld
lda #bkBOS
sta bkSelect
lda vic+$19
bpl +
and #1
bne Sixty
+ lda $dc0d
Sixty = *
sta vic+$19
;** save full context
lda mmuZeroPage
ldx #$00
stx mmuZeroPage
ldy #pcbZeroPage
sta (activePid),y
ldy #pcbSP
tsx
txa
sta (activePid),y
ldy #pcbStackPage
lda mmuStackPage
sta (activePid),y
ldy #pcbD506
lda $d506
sta (activePid),y
;** process interrupt
inc jiffyTime+0
bne +
inc jiffyTime+1
+ lda delayQueue+pcbQCount
beq +
jsr DelayIrqAwake
+ nop
;** select new process
- ldy #pcbPriority ;give cur full count
lda (activePid),y
iny
sta (activePid),y
beq ++
- ldy #pcbNext ;find next proc
lda (activePid),y
tax
iny
lda (activePid),y
stx activePid+0
sta activePid+1
ExitKernel = *
ldy #pcbCountdown
lda (activePid),y
beq ++
sec
sbc #1
sta (activePid),y
beq +
jmp -
+ ;check if null process
ldy #pcbIsHead
lda (activePid),y
bpl +
iny
lda (activePid),y ;only run null if only proc
bne --
+ ;we've got a winner
;** restore full context and exit
ldy #pcbD506
lda (activePid),y
sta $d506
ldy #pcbStackPage
lda (activePid),y
sta mmuStackPage
ldy #pcbSP
lda (activePid),y
tax
txs
ldy #pcbZeroPage
lda (activePid),y
sta mmuZeroPage
jmp IrqExit
DefaultExit = *
lda #$00
ldx #$00
Exit = * ;( .A=code, .X=$00 )
jmp Suspend
brk
MyPid = * ;( ) : .AY=pid
lda #$00
ldx mmuZeroPage
sta mmuZeroPage
lda activePid+0
ldy activePid+1
stx mmuZeroPage
clc
rts
MyParentPid = * ;( ) : .AY=parentPid
lda #$00
ldx mmuZeroPage
sta mmuZeroPage
ldy #pcbParent
lda (activePid),y
pha
iny
lda (activePid),y
tay
pla
stx mmuZeroPage
clc
rts
enterKernSave : buf 4
EnterKernel = *
;** set up process stack as if it had performed an interrupt
;** necessary if process will block
;** called as a one-level-deep subroutine of the system call
sta enterKernSave+2
;** save system-call return address
pla
sta enterKernSave+0
pla
sta enterKernSave+1
;** increment user-process return address (rts -> rti)
pla
clc
adc #1
sta enterKernSave+3
pla
adc #0
pha
lda enterKernSave+3
pha
;** set up processor registers as-is, status $00
lda #$00
pha
lda enterKernSave+2
pha
txa
pha
tya
pha
lda $ff00 ;xxx change for multi-banks
pha
;** save info into pcb
lda mmuZeroPage
ldx #$00
stx mmuZeroPage
ldy #pcbZeroPage
sta (activePid),y
dey
lda mmuStackPage
sta (activePid),y
dey
tsx
txa
sta (activePid),y
ldy #pcbD506
lda $d506
sta (activePid),y
;** restore system-call return address
;** (continue to use user-process stack)
lda enterKernSave+1
pha
lda enterKernSave+0
pha
rts
Suspend = * ;( ) ;suspend self
sei
jsr EnterKernel
jsr SuspendSub
jmp ExitKernel
SuspendSub = * ;( activePid ) : activePid, pcbPtr, q=nullPcb
;** Remove the active pid from the ready queue and set another pid to
;** active; set pcbPtr to point to the suspended process; and set the
;** process state to "suspended".
lda activePid+0
sta pcbPtr+0
lda activePid+1
sta pcbPtr+1
lda #<nullPcb
ldy #>nullPcb
sta q+0
sty q+1
jsr QueueUnlink
ldy #pcbNext
lda (pcbPtr),y
sta activePid+0
iny
lda (pcbPtr),y
sta activePid+1
ldy #pcbState
lda #STATE_SUSPENDED
sta (pcbPtr),y
rts
Delay = * ;( .AY=jiffies ) : .CS=err
cmp #0
bne +
cpy #0
bne +
clc
rts
+ sei
sta delayTime+0
sty delayTime+1
jsr EnterKernel
jsr SuspendSub
ldy #pcbState
lda #STATE_DELAY
ldy #pcbWakeupTime
clc
lda delayTime+0
adc jiffyTime+0
sta delayTime+0
sta (pcbPtr),y
iny
lda delayTime+1
adc jiffyTime+1
sta delayTime+1
sta (pcbPtr),y
lda #0
rol
sta delayTime+2
lda #<delayQueue
ldy #>delayQueue
sta q+0
sty q+1
sta p+0
sty p+1
jsr DelayFindSpot
jsr QueueInsert
jmp ExitKernel
delayTime : buf 3
pTimeHi : buf 1
DelayFindSpot = * ;( (q)=queue, (p)=queueHead, (pcbPtr) ) : p=prevNode
jsr IncPtrP
ldy #pcbIsHead
lda (p),y
bne DelayFindSpotExit
ldy #pcbWakeupTime
lda (p),y
cmp jiffyTime+0
iny
lda (p),y
sbc jiffyTime+1
ldx #0
bcs +
inx
+ stx pTimeHi
dey
lda delayTime+0
cmp (p),y
iny
lda delayTime+1
sbc (p),y
lda delayTime+2
sbc pTimeHi
bcs DelayFindSpot
DelayFindSpotExit = *
;xx fall through
DecPtrP = * ;( (p) ) : (p):=(p)->prev
ldy #pcbPrev
lda (p),y
tax
iny
lda (p),y
stx p+0
sta p+1
rts
IncPtrP = * ;( (p) ) : (p):=(p)->next
ldy #pcbNext
lda (p),y
tax
iny
lda (p),y
stx p+0
sta p+1
rts
DelayIrqAwake = *
lda delayQueue+pcbNext+0
ldy delayQueue+pcbNext+1
sta pcbPtr+0
sty pcbPtr+1
ldy #pcbWakeupTime
lda (pcbPtr),y
cmp jiffyTime+0
beq +
rts
+ iny
lda (pcbPtr),y
cmp jiffyTime+1
beq +
rts
+ lda #<delayQueue
ldy #>delayQueue
sta q+0
sty q+1
jsr QueueUnlink
jsr MakeReady
jmp DelayIrqAwake
msgPtrSave : buf 2
Send = * ;( .AY=msgBuf ) : .CS:.A=err
sei
sta msgPtrSave+0
sty msgPtrSave+1
jsr EnterKernel
jsr SuspendSub
lda msgPtrSave+0
ldy msgPtrSave+1
sta msgPtr+0
sty msgPtr+1
ldy #msgTo
lda (msgPtr),y
sta q+0
iny
lda (msgPtr),y
sta q+1
;xx should verify that receiver is a process
ldy #pcbSendMsgPtr
lda msgPtr+0
sta (pcbPtr),y
iny
lda msgPtr+1
sta (pcbPtr),y
ldy #pcbBlockedOn
lda q+0
sta (pcbPtr),y
iny
lda q+1
sta (pcbPtr),y
ldy #pcbState
lda (q),y
cmp #STATE_RECEIVE
beq SendToReceiverBlocked
lda #STATE_SEND
sta (pcbPtr),y
clc
lda q+0
adc #pcbSendQHead
sta q+0
bcc +
inc q+1
+ ldy #pcbPrev
lda (q),y
sta p+0
iny
lda (q),y
sta p+1
jsr QueueInsert
jmp ExitKernel
SendToReceiverBlocked = *
lda #STATE_REPLY
sta (pcbPtr),y
ldy #pcbRecvMsgPtr
lda (q),y
sta p+0
iny
lda (q),y
sta p+1
jsr CopyMessage
lda pcbPtr+0
ldy pcbPtr+1
ldx q+0
stx pcbPtr+0
ldx q+1
stx pcbPtr+1
ldx #$00
clc
jsr SetReturn
jsr MakeReady
jmp ExitKernel
setretSave : buf 4
SetReturn = * ;( (pcbPtr)=proc, .AXY=regvals, .C=cval ) : (p)=junk
sta setretSave+2
stx setretSave+1
sty setretSave+0
php
pla
and #$01
sta setretSave+3
ldy #pcbStackPage
lda (pcbPtr),y
sta p+1
ldy #pcbSP
lda (pcbPtr),y
clc
adc #2
sta p+0
ldy #3
- lda setretSave,y
sta (p),y
dey
bpl -
rts
CopyMessage = * ;( (pcbPtr)=sender, (msgPtr)=sendmsg, (p)=recvmsg )
ldy #msgFrom
lda pcbPtr+0
sta (msgPtr),y
iny
lda pcbPtr+1
sta (msgPtr),y
ldy #msgSize-1
- lda (msgPtr),y
sta (p),y
dey
bpl -
rts
Receive = * ;( .AY=msgBuf ) : .AY=senderPid
sei
sta msgPtrSave+0
sty msgPtrSave+1
lda mmuZeroPage
pha
lda #$00
sta mmuZeroPage
ldy #pcbSendQCount
lda (activePid),y
bne ReceiveFromSender
pla
sta mmuZeroPage
jsr EnterKernel
jsr SuspendSub
lda #STATE_RECEIVE
sta (pcbPtr),y
ldy #pcbRecvMsgPtr
lda msgPtrSave+0
sta (pcbPtr),y
iny
lda msgPtrSave+1
sta (pcbPtr),y
jmp ExitKernel
ReceiveFromSender = * ;( (activePid), (msgPtrSave) )
lda activePid+0
ldy activePid+1
clc
adc #pcbSendQHead
bcc +
iny
+ sta q+0
sty q+1
ldy #pcbSendQHead
lda (activePid),y
sta pcbPtr+0
iny
lda (activePid),y
sta pcbPtr+1
jsr QueueUnlink ;( (q)=queueHead, (pcbPtr)=node ) ;uses p
ldy #pcbSendMsgPtr
lda (pcbPtr),y
sta msgPtr+0
iny
lda (pcbPtr),y
sta msgPtr+1
lda msgPtrSave+0
ldy msgPtrSave+1
sta p+0
sty p+1
jsr CopyMessage ;( (pcbPtr)=sender, (msgPtr)=sendmsg, (p)=recvmsg )
ldy #pcbState
lda #STATE_REPLY
sta (pcbPtr),y
ldx pcbPtr+0
ldy pcbPtr+1
pla
sta mmuZeroPage
txa
cli
clc
rts
zpPtrSave : buf 1
Reply = * ;( .AY=msgBuf[msgRet,msgData] ) : .CS:.A=err
sei
;** switch to kernel
ldx mmuZeroPage
stx zpPtrSave
ldx #$00
stx mmuZeroPage
sta msgPtr+0
sty msgPtr+1
;** find and check the sender
ldy #msgFrom
lda (msgPtr),y
sta pcbPtr+0
iny
lda (msgPtr),y
sta pcbPtr+1
;xx verify that receiver is a pcb here
ldy #pcbState
lda (pcbPtr),y
cmp #STATE_REPLY
beq +
- lda #KERN_ERR_PID_NOT_REPLY
ldx zpPtrSave
stx mmuZeroPage
sec
cli
rts
+ ldy #pcbBlockedOn
lda (pcbPtr),y
cmp activePid+0
bne -
iny
lda (pcbPtr),y
cmp activePid+1
bne -
;** copy the reply contents
ldy #pcbSendMsgPtr
lda (pcbPtr),y
sta p+0
iny
lda (pcbPtr),y
sta p+1
ldy #msgRet
lda (msgPtr),y
sta (p),y
ldy #msgData
- lda (msgPtr),y
sta (p),y
iny
cpy #msgData+4
bcc -
;** wake up the sender and exit
jsr MakeReady
ldx zpPtrSave
stx mmuZeroPage
clc
cli
rts
;======== test application ========
testNumber : buf 1
Init = *
lda #1
sta testNumber
lda #<TestSid1
ldy #>TestSid1
ldx #2
jsr Create
lda #<TestDelay1
ldy #>TestDelay1
ldx #1
jsr Create
lda #<TestDelay2
ldy #>TestDelay2
ldx #1
jsr Create
lda #<TestDelay3
ldy #>TestDelay3
ldx #1
jsr Create
lda #<TestDelay4
ldy #>TestDelay4
ldx #1
jsr Create
lda #<TestDelay5
ldy #>TestDelay5
ldx #1
jsr Create
lda #<Blabber1
ldy #>Blabber1
ldx #1
jsr Create
lda #<Spinner1
ldy #>Spinner1
ldx #1
jsr Create
jmp KernelServer
TestSid1 = *
ldx #$1c-1
lda #$00
- sta $d400,x
dex
bpl -
lda #$50
sta 2
sta 3
lda #$08
sta $d418
lda #$00
ldy #$08
sta $d402
sty $d403
lda #$41
sta $d404
lda #$00
sta $d405
lda #$f0
sta $d406
- lda 2
ldy 3
sta $d400
sty $d401
lda 2
ora 3
bne +
lda #120
ldy #0
jsr Delay
+ inc 2
bne +
inc 3
+ inc $d020
tsx
jmp -
TestDelay1 = *
jsr MyParentPid
sta testDelay1Msg+msgTo+0
sty testDelay1Msg+msgTo+1
lda #<testDelay1Txt
ldy #>testDelay1Txt
sta testDelay1Msg+msgBuf+0
sty testDelay1Msg+msgBuf+1
- lda #<60
ldy #>60
jsr Delay
inc $581
lda #<testDelay1Msg
ldy #>testDelay1Msg
jsr Send
jmp -
testDelay1Txt : db "Hi, this is delay process 1 *\n",0
TestDelay2 = *
jsr MyParentPid
sta testDelay2Msg+msgTo+0
sty testDelay2Msg+msgTo+1
lda #<testDelay2Txt
ldy #>testDelay2Txt
sta testDelay2Msg+msgBuf+0
sty testDelay2Msg+msgBuf+1
- lda #<120
ldy #>120
jsr Delay
inc $582
lda #<testDelay2Msg
ldy #>testDelay2Msg
jsr Send
jmp -
testDelay2Txt : db "Hi, this is delay process 2\n",0
TestDelay3 = *
jsr MyParentPid
sta testDelay3Msg+msgTo+0
sty testDelay3Msg+msgTo+1
lda #<testDelay3Txt
ldy #>testDelay3Txt
sta testDelay3Msg+msgBuf+0
sty testDelay3Msg+msgBuf+1
- lda #<180
ldy #>180
jsr Delay
inc $583
lda #<testDelay3Msg
ldy #>testDelay3Msg
jsr Send
jmp -
testDelay3Txt : db "Hi, this is delay process 3\n",0
TestDelay4 = *
jsr MyParentPid
sta testDelay4Msg+msgTo+0
sty testDelay4Msg+msgTo+1
lda #<testDelay4Txt
ldy #>testDelay4Txt
sta testDelay4Msg+msgBuf+0
sty testDelay4Msg+msgBuf+1
- lda #<240
ldy #>240
jsr Delay
inc $584
lda #<testDelay4Msg
ldy #>testDelay4Msg
jsr Send
jmp -
testDelay4Txt : db "Hi, this is delay process 4\n",0
TestDelay5 = *
jsr MyParentPid
sta testDelay5Msg+msgTo+0
sty testDelay5Msg+msgTo+1
lda #<testDelay5Txt
ldy #>testDelay5Txt
sta testDelay5Msg+msgBuf+0
sty testDelay5Msg+msgBuf+1
- lda #<300
ldy #>300
jsr Delay
inc $585
lda #<testDelay5Msg
ldy #>testDelay5Msg
jsr Send
jmp -
testDelay5Txt : db "Hi, this is delay process 5\n",0
Blabber1 = *
jsr MyParentPid
sta blabber1Msg+msgTo+0
sty blabber1Msg+msgTo+1
lda #<blabber1Txt
ldy #>blabber1Txt
sta blabber1Msg+msgBuf+0
sty blabber1Msg+msgBuf+1
- inc $580
lda #<blabber1Msg
ldy #>blabber1Msg
jsr Send
jmp -
blabber1Txt : db "Hi, this is blabber\n",0
Spinner1 = *
jsr MyParentPid
sta spinner1Msg+msgTo+0
sty spinner1Msg+msgTo+1
lda #<spinner1Txt
ldy #>spinner1Txt
sta spinner1Msg+msgBuf+0
sty spinner1Msg+msgBuf+1
- inc $580
lda #<spinner1Msg
ldy #>spinner1Msg
jsr Send
jmp -
spinner1Txt : db "Hi, this is spinner +\n",0
KernelServer = *
lda #$00
sta mmuZeroPage
lda #14
jsr $ffd2
- lda #<ksMsg
ldy #>ksMsg
jsr Receive
lda ksMsg+msgBuf+0
ldy ksMsg+msgBuf+1
sta $80
sty $81
ldy #0
- lda ($80),y
beq +
jsr $ffd2
iny
bne -
+ lda #<ksMsg
ldy #>ksMsg
jsr Reply
jmp --
bss = *
testDelay1Msg = $c00 ;** put these here to save pgm memory
testDelay2Msg = testDelay1Msg+msgSize
testDelay3Msg = testDelay2Msg+msgSize
testDelay4Msg = testDelay3Msg+msgSize
testDelay5Msg = testDelay4Msg+msgSize
blabber1Msg = testDelay5Msg+msgSize
spinner1Msg = blabber1Msg+msgSize
ksMsg = spinner1Msg+msgSize
-----=-----
APPENDIX B. UUENCODED DEMO PROGRAM
The uuencoded demo system follows. You can extract it with any uudecoder or
with version 2.00 or higher of "unbcode" (ACE has only version 1.00).
-nucode-begin 1 bos
begin 640 bos
M`!-,)A,``````````````````````````````````````````````'BI#HT`
M_ZEVH!6-%`.,%0.IJZ`3C18#C!<#J:N@$XT8`XP9`ZD`C203C243J1Z@$X4&
MA`<@U12I`Z`3C0,3C`03C043C`83A0*$`ZG_C0<3J0"-"!.I((4,J<"-'1.I
M`HT-$UA,C1.I.Z`9H@$@_1/N``30#>X!!-`([@($T`/N`P1,EA-XJ66@^HT4
M`XP5`ZE`H/J-&`.,&0.B^IJI`(T'U8T(U:(!C@G5C0K5J02-!M583+=-````
M````````````````````````````````````````>(W=$XS>$X[?$ZT'U8W<
M$ZD`C0?5J0"D#(4(A`G(C.`3R(SA$\B$#,#`D`$`HAJI`)WB$\H0^JGVC>@3
MK>$3C>D3K>`3C>H3J02-ZQ.MWQ.-[!.-[1.E`J0#C?H3C/L3J<6-_!.@&KGB
M$Y$(B!#XI0@8:0Z%!J4):0"%!R#5%*D`K.$3A02$!:#WJ0Z1!,BB!*D`D03(
MRM#ZK=T3D03(K=X3D03(J0F1!,BI%I$$(+L4I0BD":[<$XX'U1A88*`:J<"1
M"*D#H!.%!H0'I0*D`X4$A`4@`!5@I0:D!XWZ%(S[%(W\%(S]%*G_C?X4J0"-
M_Q2@!;GZ%)$&B!#X8````````!B@!;$&:0&1!J``L021",BQ!)$(R*4$D0C(
MI061"*``L02%!LBQ!(4'H`*E")$&R*4)D0:@`*4(D03(I0F1!&"@`+$(A03(
ML0B%!:`"L0B1!,BQ")$$H`*Q"(4$R+$(A06@`+$(D03(L0B1!*`%L08XZ0&1
M!F#8J0Z-`/^M&=`0!"D!T`.M#=R-&="M!]6B`(X'U:`(D0*@!KJ*D0*@!ZT)
MU9$"H`FM!M61`NXD$]`#[B43K2,3\`,@71?JH`JQ`LB1`O`GH`"Q`JK(L0*&
M`H4#H`NQ`O`5..D!D0+P`TS%%:`$L0(0!<BQ`M#0H`FQ`HT&U:`'L0*-"=6@
M!K$"JIJ@"+$"C0?53#/_J0"B`$R.%@"I`*X'U8T'U:4"I`..!]488*D`K@?5
MC0?5H!BQ`DC(L0*H:(X'U1A@`````(T\%FB-.A9HC3L6:!AI`8T]%FAI`$BM
M/19(J0!(K3P62(I(F$BM`/](K0?5H@".!]6@")$"B*T)U9$"B+J*D0*@":T&
MU9$"K3L62*TZ%DA@>"`^%B"8%DS1%:4"A0BE`X4)J0.@$X4&A`<@0!6@`+$(
MA0+(L0B%`Z`:J<61"&#)`-`&P`#0`AA@>(T-%XP.%R`^%B"8%J`:J<2@#!BM
M#1=M)!.-#1>1",BM#A=M)1.-#A>1"*D`*HT/%ZD>H!.%!H0'A02$!2`1%R``
M%4S1%0`````@4!>@!+$$T"F@#+$$S203R+$$[243H@"P`>B.$!>(K0T7T03(
MK0X7\02M#Q?M$!>PSJ`"L02JR+$$A@2%!6"@`+$$JLBQ!(8$A05@K1X3K!\3
MA0B$":`,L0C-)!/P`6#(L0C-)1/P`6"I'J`3A0:$!R!`%2"[%$Q=%P``>(V+
M%XR,%R`^%B"8%JV+%ZR,%X4*A`N@`+$*A0;(L0J%!Z`,I0J1",BE"Y$(H!2E
M!I$(R*4'D0B@&K$&R<+P(*G!D0@8I09I#H4&D`+F!Z`"L0:%!,BQ!H4%(``5
M3-$5J<.1"*`,L0:%!,BQ!H4%($48I0BD":8&A@BF!X8)H@`8(!L8(+L43-$5
M`````(T9&(X8&(P7&`AH*0&-&AB@![$(A06@!K$(&&D"A02@`[D7&)$$B!#X
M8*`"I0B1"LBE"9$*H!>Q"I$$B!#Y8'B-BQ>,C!>M!]5(J0"-!]6@$[$"T!YH
MC0?5(#X6()@6J<*1"*`,K8L7D0C(K8P7D0A,T16E`J0#&&D.D`'(A0:$!Z`.
ML0*%",BQ`H4)($`5H`RQ"(4*R+$(A0NMBQ>LC!>%!(0%($48H!JIPY$(I@BD
M"6B-!]6*6!A@`'BN!]6.U!BB`(X'U84*A`N@`K$*A0C(L0J%":`:L0C)P_`+
MJ>&NU!B.!]4X6&"@%+$(Q0+0[<BQ",4#T.:@#+$(A03(L0B%!:`1L0J1!*`4
ML0J1!,C`&)#W(+L4KM08C@?5&%A@`*D!C3H9J8N@&:("(/T3J=V@&:(!(/T3
MJ2.@&J(!(/T3J6>@&J(!(/T3J:N@&J(!(/T3J>^@&J(!(/T3J3.@&Z(!(/T3
MJ6B@&Z(!(/T33)\;HANI`)T`U,H0^JE0A0*%`ZD(C1C4J0"@"(T"U(P#U*E!
MC034J0"-!=2I\(T&U*4"I`.-`-2,`=2E`@4#T`>I>*``(+T6Y@+0`N8#[B#0
MNDRY&2`C%HT`#(P!#*D$H!J-!`R,!0RI/*``(+T6[H$%J0"@#""-%TSP&<A)
M+"!42$E3($E3($1%3$%9(%!23T-%4U,@,2`J#0`@(Q:-&`R,&0RI2J`:C1P,
MC!T,J7B@`""]%NZ"!:D8H`P@C1=,-AK(22P@5$A)4R!)4R!$14Q!62!04D]#
M15-3(#(-`"`C%HTP#(PQ#*F.H!J--`R,-0RIM*``(+T6[H,%J3"@#""-%TQZ
M&LA)+"!42$E3($E3($1%3$%9(%!23T-%4U,@,PT`(",6C4@,C$D,J=*@&HU,
M#(Q-#*GPH``@O1;NA`6I2*`,((T73+X:R$DL(%1(25,@25,@1$5,05D@4%)/
M0T534R`T#0`@(Q:-8`R,80RI%J`;C60,C&4,J2R@`2"]%NZ%!:E@H`P@C1=,
M`AO(22P@5$A)4R!)4R!$14Q!62!04D]#15-3(#4-`"`C%HUX#(QY#*E3H!N-
M?`R,?0SN@`6I>*`,((T73$8;R$DL(%1(25,@25,@0DQ!0D)%4@T`(",6C9`,
MC)$,J8B@&XV4#(R5#.Z`!:F0H`P@C1=,>QO(22P@5$A)4R!)4R!34$E.3D52
M("L-`*D`C0?5J0X@TO^IJ*`,(%H8K:P,K*T,A8"$@:``L8#P!B#2_\C0]JFH
(H`P@U1A,J1L`
`
end
-nucode-end 1 2258 1430bdc2
========================================================================END===
