X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Flynx.sgml;h=0eef70535793d9861fe35aded81770f248d5de48;hb=df80d071e8eeb799bd1d8ec55acd1ee92714c752;hp=e7c8f01cb12af687ded87f8a5fe5ced2a8f45d0f;hpb=361bfdde2d74b038bf46ccb91f21186c9a9ae4c5;p=cc65 diff --git a/doc/lynx.sgml b/doc/lynx.sgml index e7c8f01cb..0eef70535 100644 --- a/doc/lynx.sgml +++ b/doc/lynx.sgml @@ -1,11 +1,10 @@
- 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 +<author> +<url url="mailto:karri@sipo.fi" name="Karri Kaksonen">,<newline> +<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz"> <abstract> An overview over the Atari Lynx runtime system as it is implemented for the @@ -24,32 +23,98 @@ 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 +described in detail in the separate <url 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 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. +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. -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/cart_template.zip/ 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 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 $400 - $BE3F. -All boot ROM entry points may be called directly without additional code. +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/ @@ -63,12 +128,17 @@ Special locations: '?' for all keys down at the same time. <tag/Stack/ - The C runtime stack is located at $BE3F and growing downwards. + 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> @@ -81,10 +151,13 @@ Programs containing Lynx specific code may use the <tt/lynx.h/ header file. <sect1>Lynx specific functions<p> <itemize> -<item>lynx_change_framerate <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> @@ -113,26 +186,52 @@ structures, accessing the struct fields will access the chip registers. <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> -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. +<descrip> + + <tag><tt/lynx-160-102-16.tgi (lynx_160_102_16_tgi)/</tag> + A TGI driver for the standard graphics mode (160×102 in 16 colors). -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 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. + The TGI driver has a few Lynx-specific extensions. -Calling tgi_ioctl(0, spr) will display a standard Lynx sprite on screen. + Calling tgi_sprite(spr) or tgi_ioctl(0, spr) will display a standard Lynx + sprite on screen. -Calling tgi_ioctl(1, 0) will do a flip screen. If you decide to flip the -screen then it may be a good idea to call the install-routine for the -joystick to get that flipped too. + 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> -Calling 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. <sect1>Extended memory drivers<p> @@ -141,13 +240,13 @@ No extended memory drivers are currently available for the Lynx. <sect1>Joystick drivers<p> -A joystick driver for the standard buttons 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. +<descrip> + + <tag><tt/lynx-stdjoy.joy (lynx_stdjoy_joy)/</tag> + A joystick driver for the standard buttons. + +</descrip><p> -The joystick will check to see if the screen is flipped or not in the install -routine and adapt itself to the currect state. <sect1>Mouse drivers<p> @@ -156,34 +255,75 @@ No mouse drivers are currently available for the Lynx. <sect1>RS232 device drivers<p> -No serial drivers are currently available for the Lynx. - - - -<sect>Limitations<p> +<descrip> + <tag><tt/lynx-comlynx.ser (lynx_comlynx_ser)/</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>Other hints<p> -At this point in time there is no support for the cart filesystem yet. -I have a cart_template example project that uses an interrupt driven -display, has support for the cart filesystem and an abcmusic sound -module. +<sect>Limitations<p> -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 -cart_template. -<sect>Bugs/Feedback<p> +<sect>Cart access<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">). +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>License<p> @@ -197,17 +337,14 @@ 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. +<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> - - -