X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Flynx.sgml;h=45c429b106e91db47d2931628d49c68def5e6409;hb=6ff1d8314d31096041213263887c9524cfb386f0;hp=a8c2525c2bf341da465a0f32f69e34efb8105802;hpb=f11067e2603d98b1475da308308e3a255dbe072f;p=cc65 diff --git a/doc/lynx.sgml b/doc/lynx.sgml index a8c2525c2..45c429b10 100644 --- a/doc/lynx.sgml +++ b/doc/lynx.sgml @@ -5,7 +5,7 @@ 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>2011-04-01 <abstract> An overview over the Atari Lynx runtime system as it is implemented for the @@ -30,24 +30,119 @@ 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> +extern char lynxtgi[]; + +void main(void) { + tgi_install(&lynxtgi); + 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 +link it in statically. + +This relocatable driver is found in <tt>$(CC65_HOME)/tgi/lynx-160-102-16.tgi</tt>. +Copy it from here. + +The name comes from 160 by 102 pixels (The Lynx LCD size), 16 colors. + +In order to link in this statically we have to make it back to a source +file so that we can compile it. The next command will turn the compiled +driver object file into an assembler source and compile it with the ca65 +assembler. + +<tscreen><verb> +co65 --code-label _lynxtgi lynx-160-102-16.tgi +ca65 -t lynx lynx-160-102-16.s +</verb></tscreen> + +This will create a linkable object file called lynx-160-102-16.o + +Then we need to compile our main file to a linkable object file. + +<tscreen><verb> +cc65 -t lynx main.c +ca65 -t lynx main.s +</verb></tscreen> + +Finally we have to link them together to produce an executable cart. + +<tscreen><verb> +cl65 -t lynx -o game.lnx main.o lynx-160-102-16.o lynx.lib +</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. It is of course possible to change this behaviour by using a -modified startup file and linker config. +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. -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. +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 $400 - $C037. +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/ @@ -153,6 +248,9 @@ 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. + <sect1>Extended memory drivers<p> No extended memory drivers are currently available for the Lynx. @@ -165,9 +263,6 @@ 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 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> No mouse drivers are currently available for the Lynx. @@ -223,10 +318,7 @@ No mouse drivers are currently available for the Lynx. 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. + Both transmit and receive are interrupt driven. </descrip><p> @@ -235,7 +327,7 @@ No mouse drivers are currently available for the Lynx. -<sect>Other hints<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, @@ -277,6 +369,3 @@ freely, subject to the following restrictions: </enum> </article> - - -