]> git.sur5r.net Git - cc65/blob - doc/lynx.sgml
Update cbm510.sgml
[cc65] / doc / lynx.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4 <title>Atari Lynx specific information for cc65
5 <author>
6 <url url="mailto:karri@sipo.fi" name="Karri Kaksonen">,<newline>
7 <url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
8
9 <abstract>
10 An overview over the Atari Lynx runtime system as it is implemented for the
11 cc65 C compiler.
12 </abstract>
13
14 <!-- Table of contents -->
15 <toc>
16
17 <!-- Begin the document -->
18
19 <sect>Overview<p>
20
21 This file contains an overview of the Atari Lynx runtime system as it comes
22 with the cc65 C compiler. It describes the memory layout, Lynx specific header
23 files, available drivers, and any pitfalls specific to that platform.
24
25 Please note that Lynx specific functions are just mentioned here, they are
26 described in detail in the separate <url url="funcref.html" name="function
27 reference">. Even functions marked as "platform dependent" may be available on
28 more than one platform. Please see the function reference for more
29 information.
30
31
32 <sect>Building your first Hello World application<p>
33
34 Here is a small traditional Hello World program for the Atari Lynx.
35
36 <tscreen><verb>
37 #include <lynx.h>
38 #include <tgi.h>
39 #include <6502.h> 
40
41 void main(void) {
42   tgi_install(tgi_static_stddrv);
43   tgi_init();
44   CLI();
45   while (tgi_busy())
46     ;
47   tgi_clear();
48   tgi_setcolor(COLOR_GREEN);
49   tgi_outtextxy(0, 0, "Hello World");
50   tgi_updatedisplay();
51   while (1)
52     ;
53 }
54 </verb></tscreen>
55
56 The lynx.h contains all kind of system dependent things.
57
58 The tgi.h contains the graphics driver functions.
59
60 The 6502.h is needed for executing the CLI() command.
61
62 As the Atari Lynx does not have ASCII characters available you need to use
63 the Tiny Graphics Interface library for producing letters on the screen.
64
65 The cc65 compiler suite has a graphics library called "Tiny Graphics
66 Interface". This interface has some relocatable code. In order to use this
67 in your own program you need to load it at run time.
68
69 Unfortunately the Lynx does not have a disk drive from where to load it.
70 Therefore you must already load it at compile time. The easiest way is to
71 automatically link it in statically from the Lynx C library.
72
73 <tscreen><verb>
74 cl65 -t lynx -o game.lnx main.c
75 </verb></tscreen>
76
77 This will create a bootable cart image called game.lnx
78
79
80 <sect>Binary format<p>
81
82 The standard binary output format generated by the linker for the Lynx target
83 is a cart image. By specifying the config file lynx-bll.cfg the linker will
84 generate BLL download compatible binary files.
85
86 It is of course possible to change this behaviour by using a modified startup
87 file and linker config.
88
89 The bootloader used in the cc65 lynx library uses a very minimal bootloader
90 that does not check the cart or show a title screen.
91
92 The advantage of this bootloader is that it allows creation of cart images to
93 many common formats.
94
95 Cart sizes
96 <tscreen><verb>
97 Block size Rom size Description
98 512 bytes  128k     Standard old games like Warbirds
99 1024 bytes 256k     Most common format for homebrew. Also newer games like Lemmings
100 2048 bytes 512k     Largest games like EOTB
101 </verb></tscreen>
102
103 <sect>Memory layout<p>
104
105 cc65 generated programs with the default setup run with the I/O area and the
106 kernal enabled, which gives a usable memory range of &dollar;200 - &dollar;C037.
107
108 Special locations:
109 <tscreen><verb>
110   0000 - 00FF Zero page
111   0100 - 01FF Machine stack
112
113   A058 - C037 Collision buffer
114   C038 - E017 Screen buffer 1
115   E018 - FFF7 Screen buffer 0
116   FFF8 - FFFF Hardware vectors
117 </verb></tscreen>
118
119 <descrip>
120   <tag/Text screen/
121   No conio support is currently available for the Lynx.
122
123   <tag/Keyboard/
124   The Lynx "flabode" keys, Opt 1, Pause and Opt 2 are implemented using the
125   conio interface. The only characters the keyboard is able to produce are
126   'R' for Restart (Opt 1 + Pause), 'F' for flip (Opt 2 + Pause),
127   'P' for pause, '1' for Opt 1, '2' for Opt 2, '3' for Opt 1 + Opt 2 and
128   '?' for all keys down at the same time.
129
130   <tag/Stack/
131   The C runtime stack is located at &dollar;C037 (or &dollar;A057 if collision
132   detection is enabled) and growing downwards.
133
134   <tag/Heap/
135   The C heap is located at the end of the program and grows towards the C
136   runtime stack.
137
138   <tag/Screen/
139   The collision detection screen is at &dollar;A058 if it is enabled. The
140   double buffered screens are at &dollar;C038 and &dollar;E018.
141
142 </descrip><p>
143
144
145
146 <sect>Platform specific header files<p>
147
148 Programs containing Lynx specific code may use the <tt/lynx.h/ header file.
149
150
151 <sect1>Lynx specific functions<p>
152
153 <itemize>
154 <item>lynx_eeprom_erase
155 <item>lynx_eeprom_read
156 <item>lynx_eeprom_write
157 <item>lynx_eeread
158 <item>lynx_eewrite
159 <item>lynx_exec
160 <item>lynx_load
161 </itemize>
162
163
164
165 <sect1>Hardware access<p>
166
167 The following pseudo variables declared in the <tt/lynx.h/ header file do
168 allow access to hardware located in the address space. Some variables are
169 structures, accessing the struct fields will access the chip registers.
170
171 <descrip>
172
173   <tag><tt/MIKEY/</tag>
174   The <tt/MIKEY/ structure allows access to MIKEY chip. See the <tt/_mikey.h/
175   header file located in the include directory for the declaration of the
176   structure.
177
178   <tag><tt/SUZY/</tag>
179   The <tt/SUZY/ structure allows access to SUZY chip. See the <tt/_suzy.h/
180   header file located in the include directory for the declaration of the
181   structure.
182
183 </descrip><p>
184
185
186
187 <sect>Loadable drivers<p>
188
189 The names in the parentheses denote the symbols to be used for static linking of the drivers.
190
191
192 <sect1>Graphics drivers<p>
193
194 <descrip>
195
196   <tag><tt/lynx-160-102-16.tgi (lynx_160_102_16_tgi)/</tag>
197   A TGI driver for the standard graphics mode (160&times;102 in 16 colors).
198
199   The TGI driver is implemented as an interrupt driven dual buffering device.
200   To use it as a single-buffer device set draw page and view page to the same
201   value 0 or 1;
202
203   The TGI driver has a few Lynx-specific extensions.
204
205   Calling tgi_sprite(spr) or tgi_ioctl(0, spr) will display a standard Lynx
206   sprite on screen.
207
208   Calling tgi_flip() or tgi_ioctl(1, 0) will do a flip screen.
209
210   Calling tgi_setbgcolor(bgcolor) or tgi_ioctl(2, bgindex) will set the text
211   background color to the index defined by bgindex. If bgindex is 0 then the
212   background color is transparent.
213
214   To set the framerate of the display hardware call tgi_setframerate(rate) or
215   tgi_ioctl(3, rate). The supported framerates are 50, 60 and 75 frames per
216   second. Actually there is no real reason to use anything else than 75 frames
217   per second.
218
219   To check if the drawing engine is busy with the previous swap you can
220   call tgi_busy or tgi_ioctl(4, 0). It returns 0 if idle and 1 if busy
221
222   To update displays you can call tgi_updatedisplay() or tgi_ioctl(4, 1) it
223   will wait for the next VBL interrupt and set the draw buffer to the
224   view buffer. The draw buffer is also changed to (drawbuffer xor 1).
225
226   You can also enable or disable collision detection by a call to
227   tgi_setcollisiondetection(active) or tgi_ioctl(5, active). The collision
228   result is located before the sprite structure by default in this driver.
229
230   In order to reserve memory for the collision detection buffer you need to
231   specify lynx-coll.cfg as the configuration file to the linker.
232
233 </descrip><p>
234
235
236 <sect1>Extended memory drivers<p>
237
238 No extended memory drivers are currently available for the Lynx.
239
240
241 <sect1>Joystick drivers<p>
242
243 <descrip>
244
245   <tag><tt/lynx-stdjoy.joy (lynx_stdjoy_joy)/</tag>
246   A joystick driver for the standard buttons.
247
248 </descrip><p>
249
250
251 <sect1>Mouse drivers<p>
252
253 No mouse drivers are currently available for the Lynx.
254
255
256 <sect1>RS232 device drivers<p>
257
258 <descrip>
259
260   <tag><tt/lynx-comlynx.ser (lynx_comlynx_ser)/</tag>
261   A serial driver for the ComLynx port.
262
263   The ComLynx port has Tx and Rx wired together. Every byte is sent
264   to all connected Lynxes. Only one Lynx can send at a time. There is no
265   protocol created for communication. You are on your own.
266
267   If the Lynx returns framing error then it is likely that another Lynx is
268   sending data at the same time.
269
270   The Lynx can also send a break and receive a break. The Lynx break is
271   recognized if the bit is down for 24 bit cycles or more.
272
273   To send a break you just set the break bit. The length of the break depends
274   on how long this bit is down.
275
276   The driver supports the baudrates:
277   <itemize>
278   <item>62500
279   <item>31250
280   <item>9600
281   <item>7200
282   <item>4800
283   <item>3600
284   <item>2400
285   <item>1800
286   <item>1200
287   <item>600
288   <item>300
289   <item>150
290   <item>134.5
291   <item>110
292   <item>75
293   </itemize>
294   The parity bit supports MARK and SPACE. It also supports EVEN and ODD parity
295   but the parity bit is included in the calculation. Most of us don't want it
296   this way. But there is nothing we can do about it.
297
298   The Lynx hardware will always check parity on incoming traffic. Currently
299   the driver cannot receive data from standard PC's due to this parity bug.
300   For working with Lynx to Lynx communication use EVEN parity.
301
302   To send data to standard PC's use MARK or SPACE as parity setting.
303
304   There is always only one stop bit. And the data length is always 8 bits.
305
306   We have no handshaking available. Even software handshake is impossible
307   as ComLynx has only one wire for the data.
308
309   Both transmit and receive are interrupt driven.
310
311 </descrip><p>
312
313
314 <sect>Limitations<p>
315
316
317
318 <sect>Cart access<p>
319
320 At this point in time there is no support for the cart filesystem yet. I have
321 a <tt/lynx-cart-demo/ example project that uses an interrupt driven display,
322 has support for the cart filesystem and an abcmusic sound module.
323
324 At some point in time we may find a way to rewrite these to fit the way the
325 cc65 drivers require. But for the time being you can create less portable
326 applications using these Lynx specific modules in <tt/lynx-cart-demo/.
327
328
329 <sect>License<p>
330
331 This software is provided 'as-is', without any expressed or implied
332 warranty.  In no event will the authors be held liable for any damages
333 arising from the use of this software.
334
335 Permission is granted to anyone to use this software for any purpose,
336 including commercial applications, and to alter it and redistribute it
337 freely, subject to the following restrictions:
338
339 <enum>
340 <item>  The origin of this software must not be misrepresented; you must not
341         claim that you wrote the original software. If you use this software
342         in a product, an acknowledgment in the product documentation would be
343         appreciated but is not required.
344 <item>  Altered source versions must be plainly marked as such, and must not
345         be misrepresented as being the original software.
346 <item>  This notice may not be removed or altered from any source
347         distribution.
348 </enum>
349
350 </article>