From d72b4f5e1e27701a6350e41705bbc50386b58758 Mon Sep 17 00:00:00 2001 From: uz Date: Wed, 6 Apr 2011 19:50:26 +0000 Subject: [PATCH] Docs for the serial functions by Karri Kaksonen. git-svn-id: svn://svn.cc65.org/cc65/trunk@4980 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- doc/funcref.sgml | 267 +++++++++++++++++++++++++++++++++++++++++++++-- doc/lynx.sgml | 118 ++++++++++++++++++--- 2 files changed, 360 insertions(+), 25 deletions(-) diff --git a/doc/funcref.sgml b/doc/funcref.sgml index ec32ebf0c..5b8138bc9 100644 --- a/doc/funcref.sgml +++ b/doc/funcref.sgml @@ -329,20 +329,21 @@ It does not declare any functions.

- (incomplete) @@ -4165,6 +4166,256 @@ be used in presence of a prototype. +ser_close

+ + + +/ + +The function is only available as fastcall function, so it may only +be used in presence of a prototype. + + +#include + +extern char comlynx[]; + +static void initialize(){ + struct ser_params params = { + SER_BAUD_9600, + SER_BITS_8, + SER_STOP_1, + SER_PAR_MARK, + SER_HS_NONE + }; + ser_install(&comlynx); // This will activate the ComLynx + CLI(); + ser_open(&params); +} + + + + + +ser_get

+ + + +/ + +The function is only available as fastcall function, so it may only +be used in presence of a prototype. + + +char ch; +while (ser_get(&ch) == SER_ERR_NO_DATA) + ; + + + + + +ser_install

+ + + +/ + +The function is only available as fastcall function, so it may only be +used in presence of a prototype. + +, +, + + +extern char lynxser[]; //Include the driver statically instead of loading it. + +ser_install(&lynxser); + + + + + +ser_ioctl

+ + + +/ + +The function is only available as fastcall function, so it may only +be used in presence of a prototype. +These functions are not easily portable to other cc65 platforms. + + + + +ser_load_driver

+ + + +/ + +The function is only available as fastcall function, so it may only +be used in presence of a prototype. + + + + + +ser_open

+ + + +/ + +The function is only available as fastcall function, so it may only +be used in presence of a prototype. + + +#include + +extern char comlynx[]; + +static void initialize(){ + struct ser_params params = { + SER_BAUD_9600, + SER_BITS_8, + SER_STOP_1, + SER_PAR_MARK, + SER_HS_NONE + }; + ser_install(&comlynx); // This will activate the ComLynx + CLI(); + ser_open(&params); +} + + + + + +ser_put

+ + + +/ + +The function is only available as fastcall function, so it may only +be used in presence of a prototype. + + +ser_put('A'); + + + + + +ser_status

+ + + +/ + +The function is only available as fastcall function, so it may only +be used in presence of a prototype. + + + + + +ser_uninstall

+ + + +/ + +The function is only available as fastcall function, so it may only +be used in presence of a prototype. + + + + +ser_unload

+ + + +/ + +The function is only available as fastcall function, so it may only +be used in presence of a prototype. + + + + + set_brk

diff --git a/doc/lynx.sgml b/doc/lynx.sgml index a8c2525c2..40110b644 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,111 @@ more than one platform. Please see the function reference for more information. +<sect>Building you 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 $(CC65_HOME)/tgi/lynx-160-102-16.tgi. 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. -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. +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 $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 +240,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 +255,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 +310,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 +319,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,