<sect1><tt/serial.h/<label id="serial.h"><p>
-<!--
+The <tt/serial.h/ header file contains definitions for initializing serial
+communication.
+
<itemize>
-<item><ref id="ser_load_driver" name="ser_load_driver">
-<item><ref id="ser_unload" name="ser_unload">
-<item><ref id="ser_install" name="ser_install">
-<item><ref id="ser_uninstall" name="ser_uninstall">
-<item><ref id="ser_open" name="ser_open">
<item><ref id="ser_close" name="ser_close">
<item><ref id="ser_get" name="ser_get">
+<item><ref id="ser_install" name="ser_install">
+<item><ref id="ser_ioctl" name="ser_ioctl">
+<item><ref id="ser_load_driver" name="ser_load_driver">
+<item><ref id="ser_open" name="ser_open">
<item><ref id="ser_put" name="ser_put">
<item><ref id="ser_status" name="ser_status">
-<item><ref id="ser_ioctl" name="ser_ioctl">
+<item><ref id="ser_uninstall" name="ser_uninstall">
+<item><ref id="ser_unload" name="ser_unload">
</itemize>
--->
(incomplete)
</quote>
+<sect1>ser_close<label id="ser_close"><p>
+
+<quote>
+<descrip>
+<tag/Function/Close the port and disable interrupts
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_close (const struct ser_params* params);/
+<tag/Description/Open the port by setting the port parameters and enable interrupts.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/
+<verb>
+#include <serial.h>
+
+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);
+}
+</verb>
+</descrip>
+</quote>
+
+
+<sect1>ser_get<label id="ser_get"><p>
+
+<quote>
+<descrip>
+<tag/Function/Read a character from serial port.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_get (char* b);/
+<tag/Description/Get a character from the serial port. If no characters are
+available, the function will return SER_ERR_NO_DATA, so this is not a fatal
+error.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/
+Wait for a character to be available from a serial port.
+<verb>
+char ch;
+while (ser_get(&ch) == SER_ERR_NO_DATA)
+ ;
+</verb>
+</descrip>
+</quote>
+
+
+<sect1>ser_install<label id="ser_install"><p>
+
+<quote>
+<descrip>
+<tag/Function/Install an already loaded driver and return an error code.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_install (void* driver);/
+<tag/Description/The function installs a driver that was already loaded into
+memory (or linked statically to the program). It returns an error code
+(<tt/SER_ERR_OK/ in case of success).
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only be
+used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/
+<ref id="ser_load_driver" name="ser_load_driver">,
+<ref id="ser_uninstall" name="ser_uninstall">,
+<ref id="ser_unload" name="ser_unload">
+<tag/Example/<verb>
+extern char lynxser[]; //Include the driver statically instead of loading it.
+
+ser_install(&lynxser);
+</verb>
+</descrip>
+</quote>
+
+
+<sect1>ser_ioctl<label id="ser_ioctl"><p>
+
+<quote>
+<descrip>
+<tag/Function/Platform dependent code extensions.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned __fastcall__ ser_ioctl (unsigned char code, void* data);/
+<tag/Description/Some platforms have extra serial functions that are not
+supported by standard serial driver functions. You can extend the driver to support
+this extra functionality bt using ser_ioctl functions.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+<item>These functions are not easily portable to other cc65 platforms.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/None
+</descrip>
+</quote>
+
+<sect1>ser_load_driver<label id="ser_load_driver"><p>
+
+<quote>
+<descrip>
+<tag/Function/Load and install a serial driver.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/void __fastcall__ ser_load_driver (const char *name);/
+<tag/Description/Load and install the driver by name.
+Will just load the driver and check if loading was successul.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/None.
+</descrip>
+</quote>
+
+
+<sect1>ser_open<label id="ser_open"><p>
+
+<quote>
+<descrip>
+<tag/Function/Open the port by setting the port parameters and enable interrupts
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_open (const struct ser_params* params);/
+<tag/Description/Open the port by setting the port parameters and enable interrupts.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/
+<verb>
+#include <serial.h>
+
+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);
+}
+</verb>
+</descrip>
+</quote>
+
+
+<sect1>ser_put<label id="ser_put"><p>
+
+<quote>
+<descrip>
+<tag/Function/Write a character to a serial port.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_put (char b);/
+<tag/Description/Send a character via the serial port. There is a transmit
+buffer, but transmitting is not done via interrupt. The function returns
+SER_ERR_OVERFLOW if there is no space left in the transmit buffer.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/
+<verb>
+ser_put('A');
+</verb>
+</descrip>
+</quote>
+
+
+<sect1>ser_status<label id="ser_status"><p>
+
+<quote>
+<descrip>
+<tag/Function/Return the serial port status.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ ser_put (unsigned char* status);/
+<tag/Description/Return the serial port status.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/None
+</descrip>
+</quote>
+
+
+<sect1>ser_uninstall<label id="ser_uninstall"><p>
+
+<quote>
+<descrip>
+<tag/Function/Uninstall the currently loaded driver but do not unload it.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/void __fastcall__ ser_uninstall (void);/
+<tag/Description/Uninstall the currently loaded driver but do not unload it.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/None.
+</descrip>
+</quote>
+
+<sect1>ser_unload<label id="ser_unload"><p>
+
+<quote>
+<descrip>
+<tag/Function/Uninstall, then unload the currently loaded driver.
+<tag/Header/<tt/<ref id="serial.h" name="serial.h">/
+<tag/Declaration/<tt/void __fastcall__ ser_unload (void);/
+<tag/Description/Uninstall, then unload the currently loaded driver.
+<tag/Limits/<itemize>
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/See also/Other serial functions.
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>set_brk<label id="set_brk"><p>
<quote>
<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>2011-04-01
<abstract>
An overview over the Atari Lynx runtime system as it is implemented for the
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/
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.
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.
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>
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,
projects / cc65 / commitdiff