mirror of
https://github.com/cc65/cc65.git
synced 2024-12-25 17:29:50 +00:00
Docs for the serial functions by Karri Kaksonen.
git-svn-id: svn://svn.cc65.org/cc65/trunk@4980 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
uz
parent
00a11e642c
commit
d72b4f5e1e
267
doc/funcref.sgml
267
doc/funcref.sgml
@ -329,20 +329,21 @@ It does not declare any functions.
|
||||
|
||||
<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)
|
||||
|
||||
@ -4165,6 +4166,256 @@ be used in presence of a prototype.
|
||||
</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>
|
||||
|
||||
118
doc/lynx.sgml
118
doc/lynx.sgml
@ -5,7 +5,7 @@
|
||||
<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
|
||||
@ -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,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user