<title>Atari Lynx specific information for cc65
<author>Karri Kaksonen, <htmlurl url="mailto:karri@sipo.fi" name="karri@sipo.fi">
Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>2004-10.14
+<date>2004-10-14
<abstract>
An overview over the Atari Lynx runtime system as it is implemented for the
<sect>Binary format<p>
-The standard binary output format generated by the linker for the VIC20 target
-is a machine language program with a one line BASIC stub. This means that a
-program can be loaded as BASIC program and started with RUN. It is of course
+The standard binary output format generated by the linker for the Lynx target
+is a machine language program with an executable header. It is of course
possible to change this behaviour by using a modified startup file and linker
config.
+You can also produce real carts with directory structures and encrypted
+headers by modifying the startup and linker config files. There is a simple
+example archive called <tt/lynx-cart-demo/ in the <htmlurl
+url="ftp://ftp.musoftware.de/pub/uz/cc65/contrib/" name="contrib directory">
+that shows how to create a complete bootable Lynx cart.
<sect>Memory layout<p>
cc65 generated programs with the default setup run with the I/O area and the
-kernal and BASIC ROM enabled (RAM at $A000 - $BFFF may be used
-for the heap), which gives a usable memory range of $1000 - $1DFF.
-All ROM entry points may be called directly without additional code.
+kernal enabled, which gives a usable memory range of $400 - $BE3F.
+All boot ROM entry points may be called directly without additional code.
Special locations:
<descrip>
<tag/Text screen/
- The text screen is located at $1E00 (as in the standard setup).
+ No conio support is currently available for the Lynx.
+
+ <tag/Keyboard/
+ The Lynx "flabode" keys, Opt 1, Pause and Opt 2 are implemented using the
+ conio interface. The only characters the keyboard is able to produce are
+ 'R' for Restart (Opt 1 + Pause), 'F' for flip (Opt 2 + Pause),
+ 'P' for pause, '1' for Opt 1, '2' for Opt 2, '3' for Opt 1 + Opt 2 and
+ '?' for all keys down at the same time.
<tag/Stack/
- The C runtime stack is located at $1DFF and growing downwards.
+ The C runtime stack is located at $BE3F and growing downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C
<sect1>Graphics drivers<p>
-A TGI driver for the standard graphics mode (160*102 in 16 colors) is
+A TGI driver for the standard graphics mode (160×102 in 16 colors) is
available, but must be statically linked, because no file I/O is available.
See the documentation for the <htmlurl url="co65.html" name="co65 utility">
for information on how to do that.
+The TGI driver is implemented as a dual buffering device. To use it as a
+single-buffer device set draw page and view page to the same value 0 or 1;
+
+The TGI driver has a few Lynx-specific extensions.
+
+Calling tgi_sprite(spr) or tgi_ioctl(0, spr) will display a standard Lynx
+sprite on screen.
+
+Calling tgi_flip() or tgi_ioctl(1, 0) will do a flip screen.
+
+Calling tgi_setbgcolor(bgcolor) or tgi_ioctl(2, bgindex) will set the text
+background color to the index defined by bgindex. If bgindex is 0 then the
+background color is transparent.
+
+To set the framerate of the display hardware call tgi_setframerate(rate) or
+tgi_ioctl(3, rate). The supported framerates are 50, 60 and 75 frames per
+second. Actually there is no real reason to use anything else than 75 frames
+per second.
+
+To check if the drawing engine is busy with the previous swap you can
+call tgi_busy or tgi_ioctl(4, 0). It returns 0 if idle and 1 if busy
+
+To update displays you can call tgi_updatedisplay() or tgi_ioctl(4, 1) it
+will wait for the next VBL interrupt and set the draw buffer to the
+view buffer. The draw buffer is also changed to (drawbuffer xor 1).
<sect1>Extended memory drivers<p>
the <htmlurl url="co65.html" name="co65 utility"> for information on how to do
that.
+The joystick will check to see if the screen is flipped or not in the install
+routine and adapt itself to the correct state.
<sect1>Mouse drivers<p>
<sect1>RS232 device drivers<p>
-No serial drivers are currently available for the Lynx.
+<descrip>
+ The ComLynx port has Tx and Rx wired together. Every byte is sent
+ to all connected Lynxes. Only one Lynx can send at a time. There is no
+ protocol created for communication. You are on your own.
+
+ If the Lynx returns framing error then it is likely that another Lynx is
+ sending data at the same time.
+
+ The Lynx can also send a break and receive a break. The Lynx break is
+ recognized if the bit is down for 24 bit cycles or more.
+
+ To send a break you just set the break bit. The length of the break depends
+ on how long this bit is down.
+
+ The driver supports the baudrates:
+ <itemize>
+ <item>62500
+ <item>31250
+ <item>9600
+ <item>7200
+ <item>4800
+ <item>3600
+ <item>2400
+ <item>1800
+ <item>1200
+ <item>600
+ <item>300
+ <item>150
+ <item>134.5
+ <item>110
+ <item>75
+ </itemize>
+ The parity bit supports MARK and SPACE. It also supports EVEN and ODD parity
+ but the parity bit is included in the calculation. Most of us don't want it
+ this way. But there is nothing we can do about it. Just don't use EVEN or ODD
+ when communicating to other equipment than the Lynx.
+
+ There is always only one stop bit. And the data length is always 8 bits.
+
+ We have no handshaking available. Even software handshake is impossible
+ as ComLynx has only one wire for the data.
+
+ Both transmit and receive are interrupt driven. The driver reserves a fixed
+ area $200-$2ff for the transmit ring buffer and $300-$3ff for the receive
+ ring buffer. This area can not be used at startup for anything as the Lynx
+ ROM needs this area for decryption purposes.
+</descrip><p>
<sect>Limitations<p>
<sect>Other hints<p>
+At this point in time there is no support for the cart filesystem yet. I have
+a <tt/lynx-cart-demo/ example project that uses an interrupt driven display,
+has support for the cart filesystem and an abcmusic sound module.
+
+At some point in time we may find a way to rewrite these to fit the way the
+cc65 drivers require. But for the time being you can create less portable
+applications using these Lynx specific modules in <tt/lynx-cart-demo/.
<sect>Bugs/Feedback<p>
projects / cc65 / blobdiff