+++ /dev/null
-<!doctype linuxdoc system>
-
-<article>
-
-<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>2011-04-01
-
-<abstract>
-An overview over the Atari Lynx runtime system as it is implemented for the
-cc65 C compiler.
-</abstract>
-
-<!-- Table of contents -->
-<toc>
-
-<!-- Begin the document -->
-
-<sect>Overview<p>
-
-This file contains an overview of the Atari Lynx runtime system as it comes
-with the cc65 C compiler. It describes the memory layout, Lynx specific header
-files, available drivers, and any pitfalls specific to that platform.
-
-Please note that Lynx specific functions are just mentioned here, they are
-described in detail in the separate <htmlurl url="funcref.html" name="function
-reference">. Even functions marked as "platform dependent" may be available on
-more than one platform. Please see the function reference for more
-information.
-
-
-<sect>Building your first Hello World application<p>
-
-Here is a small traditional Hello World program for the Atari Lynx.
-
-<tscreen><verb>
-#include <lynx.h>
-#include <tgi.h>
-#include <6502.h>
-
-void main(void) {
- tgi_install(tgi_static_stddrv);
- tgi_init();
- CLI();
- while (tgi_busy())
- ;
- tgi_clear();
- tgi_setcolor(COLOR_GREEN);
- tgi_outtextxy(0, 0, "Hello World");
- tgi_updatedisplay();
- while (1)
- ;
-}
-</verb></tscreen>
-
-The lynx.h contains all kind of system dependent things.
-
-The tgi.h contains the graphics driver functions.
-
-The 6502.h is needed for executing the CLI() command.
-
-As the Atari Lynx does not have ASCII characters available you need to use
-the Tiny Graphics Interface library for producing letters on the screen.
-
-The cc65 compiler suite has a graphics library called "Tiny Graphics
-Interface". This interface has some relocatable code. In order to use this
-in your own program you need to load it at run time.
-
-Unfortunately the Lynx does not have a disk drive from where to load it.
-Therefore you must already load it at compile time. The easiest way is to
-automatically link it in statically from the Lynx C library.
-
-<tscreen><verb>
-cl65 -t lynx -o game.lnx main.c
-</verb></tscreen>
-
-This will create a bootable cart image called game.lnx
-
-
-<sect>Binary format<p>
-
-The standard binary output format generated by the linker for the Lynx target
-is a cart image. By specifying the config file lynx-bll.cfg the linker will
-generate BLL download compatible binary files.
-
-It is of course possible to change this behaviour by using a modified startup
-file and linker config.
-
-The bootloader used in the cc65 lynx library uses a very minimal bootloader
-that does not check the cart or show a title screen.
-
-The advantage of this bootloader is that it allows creation of cart images to
-many common formats.
-
-Cart sizes
-<tscreen><verb>
-Block size Rom size Description
-512 bytes 128k Standard old games like Warbirds
-1024 bytes 256k Most common format for homebrew. Also newer games like Lemmings
-2048 bytes 512k Largest games like EOTB
-</verb></tscreen>
-
-<sect>Memory layout<p>
-
-cc65 generated programs with the default setup run with the I/O area and the
-kernal enabled, which gives a usable memory range of $200 - $C037.
-
-Special locations:
-<tscreen><verb>
- 0000 - 00FF Zero page
- 0100 - 01FF Machine stack
-
- A058 - C037 Collision buffer
- C038 - E017 Screen buffer 1
- E018 - FFF7 Screen buffer 0
- FFF8 - FFFF Hardware vectors
-</verb></tscreen>
-
-<descrip>
- <tag/Text screen/
- 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 $C037 (or $A057 if collision
- detection is enabled) and growing downwards.
-
- <tag/Heap/
- The C heap is located at the end of the program and grows towards the C
- runtime stack.
-
- <tag/Screen/
- The collision detection screen is at $A058 if it is enabled. The
- double buffered screens are at $C038 and $E018.
-
-</descrip><p>
-
-
-
-<sect>Platform specific header files<p>
-
-Programs containing Lynx specific code may use the <tt/lynx.h/ header file.
-
-
-<sect1>Lynx specific functions<p>
-
-<itemize>
-<item>lynx_eeprom_erase
-<item>lynx_eeprom_read
-<item>lynx_eeprom_write
-<item>lynx_eeread
-<item>lynx_eewrite
-<item>lynx_exec
-<item>lynx_load
-</itemize>
-
-
-
-<sect1>Hardware access<p>
-
-The following pseudo variables declared in the <tt/lynx.h/ header file do
-allow access to hardware located in the address space. Some variables are
-structures, accessing the struct fields will access the chip registers.
-
-<descrip>
-
- <tag><tt/MIKEY/</tag>
- The <tt/MIKEY/ structure allows access to MIKEY chip. See the <tt/_mikey.h/
- header file located in the include directory for the declaration of the
- structure.
-
- <tag><tt/SUZY/</tag>
- The <tt/SUZY/ structure allows access to SUZY chip. See the <tt/_suzy.h/
- header file located in the include directory for the declaration of the
- structure.
-
-</descrip><p>
-
-
-
-<sect>Loadable drivers<p>
-
-The names in the parentheses denote the symbols to be used for static linking of the drivers.
-
-
-<sect1>Graphics drivers<p>
-
-<descrip>
-
- <tag><tt/lynx-160-102-16.tgi (lynx_160_102_16)/</tag>
- A TGI driver for the standard graphics mode (160×102 in 16 colors).
-
- The TGI driver is implemented as an interrupt driven 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).
-
- You can also enable or disable collision detection by a call to
- tgi_setcollisiondetection(active) or tgi_ioctl(5, active). The collision
- result is located before the sprite structure by default in this driver.
-
- In order to reserve memory for the collision detection buffer you need to
- specify lynx-coll.cfg as the configuration file to the linker.
-
-</descrip><p>
-
-
-<sect1>Extended memory drivers<p>
-
-No extended memory drivers are currently available for the Lynx.
-
-
-<sect1>Joystick drivers<p>
-
-<descrip>
-
- <tag><tt/lynx-stdjoy.joy (lynx_stdjoy)/</tag>
- A joystick driver for the standard buttons.
-
-</descrip><p>
-
-
-<sect1>Mouse drivers<p>
-
-No mouse drivers are currently available for the Lynx.
-
-
-<sect1>RS232 device drivers<p>
-
-<descrip>
-
- <tag><tt/lynx-comlynx.ser (lynx_comlynx)/</tag>
- A serial driver for the ComLynx port.
-
- 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.
-
- The Lynx hardware will always check parity on incoming traffic. Currently
- the driver cannot receive data from standard PC's due to this parity bug.
- For working with Lynx to Lynx communication use EVEN parity.
-
- To send data to standard PC's use MARK or SPACE as parity setting.
-
- 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.
-
-</descrip><p>
-
-
-<sect>Limitations<p>
-
-
-
-<sect>Cart access<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>
-
-If you have problems using the library, if you find any bugs, or if you're
-doing something interesting with it, I would be glad to hear from you. Feel
-free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
-name="uz@cc65.org">).
-
-
-
-<sect>License<p>
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-<enum>
-<item> The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-</article>
projects / cc65 / blobdiff