-
Notifications
You must be signed in to change notification settings - Fork 16
Expand file tree
/
Copy pathatari.html
More file actions
1343 lines (1106 loc) · 55.2 KB
/
atari.html
File metadata and controls
1343 lines (1106 loc) · 55.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<LINK REL="stylesheet" TYPE="text/css" HREF="doc.css">
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.83">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>Atari specific information for cc65</TITLE>
</HEAD>
<BODY>
<H1>Atari specific information for cc65</H1>
<H2>
<A HREF="mailto:shawnjefferson@24fightingchickens.com">Shawn Jefferson</A> and<BR>
<A HREF="mailto:chris@groessler.org">Christian Groessler</A></H2>
<HR>
<EM>An overview over the Atari runtime system as it is implemented for the cc65 C
compiler.</EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="atari.html#s1">Overview</A></H2>
<P>
<H2><A NAME="toc2">2.</A> <A HREF="atari.html#s2">Binary format</A></H2>
<P>
<H2><A NAME="toc3">3.</A> <A HREF="atari.html#s3">Memory layout</A></H2>
<UL>
<LI><A NAME="toc3.1">3.1</A> <A HREF="atari.html#ss3.1"><CODE>atari</CODE> target</A>
<LI><A NAME="toc3.2">3.2</A> <A HREF="atari.html#ss3.2"><CODE>atarixl</CODE> target</A>
</UL>
<P>
<H2><A NAME="toc4">4.</A> <A HREF="atari.html#s4">Linker configurations</A></H2>
<UL>
<LI><A NAME="toc4.1">4.1</A> <A HREF="atari.html#ss4.1"><CODE>atari</CODE> config files</A>
<LI><A NAME="toc4.2">4.2</A> <A HREF="atari.html#ss4.2"><CODE>atarixl</CODE> config files</A>
</UL>
<P>
<H2><A NAME="toc5">5.</A> <A HREF="atari.html#s5">Platform specific header files</A></H2>
<UL>
<LI><A NAME="toc5.1">5.1</A> <A HREF="atari.html#ss5.1">Atari specific functions</A>
<LI><A NAME="toc5.2">5.2</A> <A HREF="atari.html#ss5.2">Hardware access</A>
<LI><A NAME="toc5.3">5.3</A> <A HREF="atari.html#ss5.3">Display lists</A>
<LI><A NAME="toc5.4">5.4</A> <A HREF="atari.html#ss5.4">Character mapping</A>
<LI><A NAME="toc5.5">5.5</A> <A HREF="atari.html#ss5.5">Keyboard codes</A>
</UL>
<P>
<H2><A NAME="toc6">6.</A> <A HREF="atari.html#s6">Loadable drivers</A></H2>
<UL>
<LI><A NAME="toc6.1">6.1</A> <A HREF="atari.html#ss6.1">Graphics drivers</A>
<LI><A NAME="toc6.2">6.2</A> <A HREF="atari.html#ss6.2">Extended memory drivers</A>
<LI><A NAME="toc6.3">6.3</A> <A HREF="atari.html#ss6.3">Joystick drivers</A>
<LI><A NAME="toc6.4">6.4</A> <A HREF="atari.html#ss6.4">Mouse drivers</A>
<LI><A NAME="toc6.5">6.5</A> <A HREF="atari.html#ss6.5">RS232 device drivers</A>
</UL>
<P>
<H2><A NAME="toc7">7.</A> <A HREF="atari.html#s7">Limitations</A></H2>
<UL>
<LI><A NAME="toc7.1">7.1</A> <A HREF="atari.html#ss7.1"><CODE>Realtime clock</CODE></A>
<LI><A NAME="toc7.2">7.2</A> <A HREF="atari.html#ss7.2"><CODE>atarixl target</CODE></A>
</UL>
<P>
<H2><A NAME="toc8">8.</A> <A HREF="atari.html#s8">DIO implementation</A></H2>
<P>
<H2><A NAME="toc9">9.</A> <A HREF="atari.html#s9">CONIO implementation</A></H2>
<P>
<H2><A NAME="toc10">10.</A> <A HREF="atari.html#s10">Technical details</A></H2>
<UL>
<LI><A NAME="toc10.1">10.1</A> <A HREF="atari.html#ss10.1"><CODE>atari</CODE></A>
<LI><A NAME="toc10.2">10.2</A> <A HREF="atari.html#ss10.2"><CODE>atarixl</CODE></A>
</UL>
<P>
<H2><A NAME="toc11">11.</A> <A HREF="atari.html#s11">Other hints</A></H2>
<UL>
<LI><A NAME="toc11.1">11.1</A> <A HREF="atari.html#ss11.1">Function keys</A>
<LI><A NAME="toc11.2">11.2</A> <A HREF="atari.html#ss11.2">Passing arguments to the program</A>
<LI><A NAME="toc11.3">11.3</A> <A HREF="atari.html#ss11.3">Interrupts</A>
<LI><A NAME="toc11.4">11.4</A> <A HREF="atari.html#ss11.4">Reserving a memory area inside a program</A>
<LI><A NAME="toc11.5">11.5</A> <A HREF="atari.html#ss11.5">Upgrading from an older cc65 version</A>
<LI><A NAME="toc11.6">11.6</A> <A HREF="atari.html#ss11.6">Getting rid of the "system check" load chunk</A>
</UL>
<P>
<H2><A NAME="toc12">12.</A> <A HREF="atari.html#s12">License</A></H2>
<HR>
<H2><A NAME="s1">1.</A> <A HREF="#toc1">Overview</A></H2>
<P>This file contains an overview of the Atari runtime system as it comes
with the cc65 C compiler. It describes the memory layout, Atari specific
header files, available drivers, and any pitfalls specific to that
platform.</P>
<P>The Atari runtime support comes in two flavors: <CODE>atari</CODE> and <CODE>atarixl</CODE>.
The <CODE>atari</CODE> target supports all Atari 8-bit computers, the <CODE>atarixl</CODE> only
supports XL type or newer machines (excluding the 600XL).</P>
<P>The <CODE>atarixl</CODE> runtime makes the whole 64K of memory available, with the
exception of the I/O area at $D000 - $D7FF. Since the
<CODE>atarixl</CODE> runtime has some
<A HREF="#xllimitations">limitations</A>, it is
recommended to use the <CODE>atari</CODE> target unless lack of memory dictates the
use of the <CODE>atarixl</CODE> target.</P>
<P>Please note that Atari specific functions are just mentioned here, they are
described in detail in the separate
<A HREF="funcref.html">function reference</A>. Even functions marked as "platform dependent" may be available on
more than one platform. Please see the function reference for more
information.</P>
<H2><A NAME="s2">2.</A> <A HREF="#toc2">Binary format</A></H2>
<P>The Atari DOS executable file format supports more than one load block (<I>chunk</I>).</P>
<P>The default binary output format generated by the linker for the
Atari target is a machine language program with a standard executable
header (FF FF <load chunk #1> ... <load chunk #n>).
A load chunk has the format [<2 byte start address> <2 bytes end address>
<chunk data>].
A run vector is added to the end of the
file ($02E0 $02E1 <run vector>) and is calculated using
the <CODE>start</CODE> label in crt0.s. (Technically the run vector is also a load chunk,
but is not regarded as such here.)</P>
<P>An <CODE>atari</CODE> program has two load chunks, an <CODE>atarixl</CODE> program has three load
chunks. The load chunks are defined in the linker configuration files. For more
detailed information about the load chunks see the chapter
<A HREF="#techdetail">Technical details</A>. For the discussion here it's
sufficient to know that the first load chunk(s) do preparation work and the
main part of the program is in the last load chunk.</P>
<P>The values determining the size of the main part of the program (the second load
chunk for <CODE>atari</CODE>, the third load chunk for <CODE>atarixl</CODE>) are calculated in
the crt0.s file from the __STARTUP_LOAD__ and __BSS_LOAD__ values.
Be aware of that if you create a custom linker config file and start moving segments around (see section
<A HREF="#memhole">Reserving a memory area inside the program</A>).</P>
<H2><A NAME="s3">3.</A> <A HREF="#toc3">Memory layout</A></H2>
<H2><A NAME="ss3.1">3.1</A> <A HREF="#toc3.1"><CODE>atari</CODE> target</A>
</H2>
<P>The default linker config file assumes that the BASIC ROM is disabled (or
the BASIC cartridge unplugged). This gives a usable memory range of
[$2000-$BC1F]. The library startup code examines the
current memory configuration, which depends on the size of the
installed memory and cartridges. It does so by using the value in
the MEMTOP ($2E5) variable as highest memory address the program
can use. The initial stack pointer, which is the upper bound of
memory used by the program, is set to this value, minus an optionally
defined __RESERVED_MEMORY__ value.</P>
<P>The default load address of $2000 can be changed by creating a custom
linker config file or by using the "--start-addr" cl65 command line
argument or the "--start-addr" or "-S" ld65 command line arguments.</P>
<P>Please note that the first load chunk (which checks the available memory)
will always be loaded at $2E00, regardless of the specified start
address. This address can only be changed by a custom linker config file.</P>
<P>Special locations:</P>
<P>
<DL>
<DT><B>Text screen</B><DD>
<P>The text screen depends on the installed memory size and cartridges
and can be obtained from the SAVMSC variable ($58).</P>
<DT><B>Stack</B><DD>
<P>The C runtime stack is located at MEMTOP and grows downwards,
regardless of how your linker config file is setup. This
accommodates the different memory configurations of the Atari
machines, as well as having a cartridge installed. You can override
this behaviour by writing your own crt0.s file and linking it to
your program (see also
<A HREF="#memhole_final_note">Final note</A>).</P>
<DT><B>Heap</B><DD>
<P>The C heap is located at the end of the program and grows towards the C
runtime stack.</P>
</DL>
</P>
<H2><A NAME="ss3.2">3.2</A> <A HREF="#toc3.2"><CODE>atarixl</CODE> target</A>
</H2>
<P>The startup code rearranges the memory as follows:</P>
<P>
<OL>
<LI>Screen memory and display list are moved below the program start address.</LI>
<LI>The ROM is disabled, making the memory in the areas [$C000-$CFFF]
and [$D800-$FFF9] available.</LI>
<LI>Character generator data is copied from ROM to the CHARGEN location specified in the
linker config file. This is (in the default <CODE>atarixl.cfg</CODE> file) at the same address as
where it is in ROM ($E000, it can be changed, see
<A HREF="#chargenloc">atarixl chargen location</A>). With the character generator at $E000, there are two upper memory
areas available, [$D800-$DFFF] and [$E400-$FFF9].</LI>
</OL>
</P>
<P>With the default load address of $2400 this gives a usable memory range of
[$2400-$CFFF].</P>
<P>Please note that the first load chunk (which checks the system
compatibility and available memory) will always be loaded at
$2E00, regardless of the specified start address. This address
can only be changed by a custom linker config file.</P>
<P>Special locations:</P>
<P>
<DL>
<DT><B>Text screen</B><DD>
<P>The text screen depends on the selected load address ($2400
by default), and resides directly before that address, rounded to the next
lower page boundary.
The screen memory's start address can be obtained from the SAVMSC variable
($58).</P>
<DT><B>Stack</B><DD>
<P>The C runtime stack is located at end of the MAIN memory area ($CFFF)
and grows downwards.</P>
<DT><B>Heap</B><DD>
<P>The C heap is located at the end of the program (end of BSS segment) and
grows towards the C runtime stack.</P>
</DL>
</P>
<H2><A NAME="s4">4.</A> <A HREF="#toc4">Linker configurations</A></H2>
<P>The ld65 linker comes with default config files for the Atari. There
are two targets for the Atari, <CODE>atari</CODE> and <CODE>atarixl</CODE>.
The default config file for <CODE>atari</CODE> is selected with
<CODE>-t atari</CODE>, and the default config file for <CODE>atarixl</CODE> is selected with
<CODE>-t atarixl</CODE>.
The Atari package comes with additional secondary linker config files which
can be used via <CODE>-t atari -C <configfile></CODE> (for <CODE>atari</CODE> target) or
<CODE>-t atarixl -C <configfile></CODE> (for <CODE>atarixl</CODE> target).</P>
<H2><A NAME="ss4.1">4.1</A> <A HREF="#toc4.1"><CODE>atari</CODE> config files</A>
</H2>
<H3>default config file (<CODE>atari.cfg</CODE>)</H3>
<P>The default configuration is tailored to C programs. It creates files
which have a default load address of $2000.</P>
<P>The files generated by this config file include the
<A HREF="#syschk">"system check"</A> load chunk. It can
optionally be left out, see
<A HREF="#nosyschk">Getting rid of the "system check" load chunk</A>.</P>
<H3><CODE>atari-asm.cfg</CODE></H3>
<P>This config file aims to give the assembler programmer maximum
flexibility. All program segments (<CODE>CODE</CODE>, <CODE>DATA</CODE>, etc.) are
optional.</P>
<P>By default it creates regular DOS executable files, which have a default
load address of $2E00. It's also possible to generate an image of
just the program data without EXE header, load address, or (auto-)start address.
To you so, you have to define the symbols <CODE>__AUTOSTART__</CODE> and <CODE>__EXEHDR__</CODE>
when linking the program. Therefore, to generate a "plain" binary file, pass the
options "<CODE>-D__AUTOSTART__=1 -D__EXEHDR__=1</CODE>" to the linker.
It's also possible to create a non auto-starting program file, by defining
only the <CODE>__AUTOSTART__</CODE> symbol. Such a program has to be run manually
after being loaded by DOS (for example by using the "M" option of DOS 2.5).
Defining only the <CODE>__EXEHDR__</CODE> symbol will create a (useless) file which
doesn't conform to the DOS executable file format (like a "plain" binary file)
but still has the "autostart" load chunk appended.</P>
<P>The sections of the file which the defines refer to (<CODE>__AUTOSTART__</CODE> for
the autostart trailer, <CODE>__EXEHDR__</CODE> for the EXE header and load address)
is <I>left out</I>, keep this in mind.</P>
<P>The values you assign to the two symbols <CODE>__AUTOSTART__</CODE> and <CODE>__EXEHDR__</CODE>
don't matter.</P>
<H3><CODE>atari-asm-xex.cfg</CODE></H3>
<P>This config file allows writing multi segment binaries easily, without having to
write the header explicitly on each segment.</P>
<P>It is similar to the <CODE>atari-asm.cfg</CODE> above, but uses the ATARI (xex) file
format support on LD65 instead of the standard binary output, so it does not
have the <CODE>__AUTOSTART</CODE> nor the <CODE>__EXEHDR__</CODE> symbols.</P>
<P>Note that each <CODE>MEMORY</CODE> area in the configuration file will have it's own
segment in the output file with the correct headers, and you can specify and
init address INITAD) for each memory area.</P>
<H3><CODE>atari-cart.cfg</CODE></H3>
<P>This config file can be used to create 8K or 16K cartridges. It's suited both
for C and assembly language programs.</P>
<P>By default, an 8K cartridge is generated. To create a 16K cartridge, pass the
size of the cartridge to the linker, like "<CODE>-D__CARTSIZE__=0x4000</CODE>".
The only valid values for <CODE>__CARTSIZE__</CODE> are 0x2000 and 0x4000.</P>
<P>The option byte of the cartridge can be set with the <CODE>__CARTFLAGS__</CODE>
value, passed to the linker. The default value is $01, which means
that the cartridge doesn't prevent the booting of DOS.</P>
<P>The option byte will be located at address $BFFD. For more information
about its use, see e.g. "Mapping the Atari".</P>
<H3><CODE>atari-cassette.cfg</CODE></H3>
<P>This config file can be used to create cassette boot files. It's suited both
for C and assembly language programs.</P>
<P>The size of a cassette boot file is restricted to 32K. Larger programs
would need to be split in more parts and the parts to be loaded manually.</P>
<P>To write the generated file to a cassette, a utility (<CODE>w2cas.com</CODE>) to run
on an Atari is provided in the <CODE>util</CODE> directory of <CODE>atari</CODE> target dir.</P>
<H3><CODE>atari-xex.cfg</CODE></H3>
<P>This config file shows how to write a binary using the ATARI (xex) file format
support on LD65, this simplifies the memory areas and allows to add new memory
areas easily without writing new headers and trailers.</P>
<P>Note that the default C library includes the system-check chunk, so in this
linker configuration we suppress the importing of the header and trailer for
this chunk by defining the standard import symbols to a 0 value. For the
initialization address of the system-check chunk, the INITAD is set directly in
the configuration.</P>
<H2><A NAME="ss4.2">4.2</A> <A HREF="#toc4.2"><CODE>atarixl</CODE> config files</A>
</H2>
<H3>default config file (<CODE>atarixl.cfg</CODE>)</H3>
<P>The default configuration is tailored to C programs. It creates files
which have a default load address of $2400.</P>
<P>The files generated by this config file include the
<A HREF="#syschkxl">"system check"</A> load chunk. It can
optionally be left out, see
<A HREF="#nosyschk">Getting rid of the "system check" load chunk</A>.</P>
<H3><CODE>atarixl-largehimem.cfg</CODE></H3>
<P>This is the same as the default config file, but it rearranges the
high memory beneath the ROM into one large block. In order for this
config file to work, the runtime library has to be recompiled with a
special define. See the file <CODE>libsrc/atari/Makefile.inc</CODE> in the
source distribution.</P>
<P>The files generated by this config file include the
<A HREF="#syschkxl">"system check"</A> load chunk. It can
optionally be left out, see
<A HREF="#nosyschk">Getting rid of the "system check" load chunk</A>.</P>
<H3><CODE>atarixl-xex.cfg</CODE></H3>
<P>Similar to the <CODE>atari-xex.cfg</CODE> above, this config file shows how to write a
binary using the ATARI (xex) file format support on LD65.</P>
<P>In addition to the suppressing of the system-check headers and trailers, this
also suppresses the shadow-ram-preparation headers and trailers, but does this
by defining an "UNUSED" memory area that is not written to the output file.</P>
<H2><A NAME="s5">5.</A> <A HREF="#toc5">Platform specific header files</A></H2>
<P>Programs containing Atari specific code may use the <CODE>atari.h</CODE>
header file.</P>
<P>This also includes access to operating system locations (e.g. hardware shadow registers) by a structure called
"<CODE>OS</CODE>".
The names are the usual ones you can find in system reference manuals. Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
...
OS.savmsc = ScreenMemory;
OS.color4 = 14; // white frame
if (OS.stick0 != 15 || OS.ch != 255) // key or stick input?
...
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Please note that memory location 762/$2FA is called "<CODE>char_</CODE>" while the original name "<CODE>char</CODE>" conflicts with the C keyword.</P>
<P>If you like to use the OS names and locations for the original Atari 800 operating system, please "<CODE>#define OSA</CODE>" before including the
<CODE>atari.h</CODE> header file.
If you like to target the floating point register model of revision 2 machines, put a "<CODE>#define OS_REV2</CODE>" before including <CODE>atari.h</CODE>.</P>
<P>Access to the Basic programming language zero page variables is established by the structure "<CODE>BASIC</CODE>".</P>
<H2><A NAME="ss5.1">5.1</A> <A HREF="#toc5.1">Atari specific functions</A>
</H2>
<P>The functions and global variable listed below are special for the Atari.
See the
<A HREF="funcref.html">function reference</A> for declaration and usage.</P>
<P>
<UL>
<LI>get_ostype</LI>
<LI>get_tv</LI>
<LI>_dos_type</LI>
<LI>_gtia_mkcolor</LI>
<LI>_getcolor</LI>
<LI>_getdefdev</LI>
<LI>_graphics</LI>
<LI>_is_cmdline_dos</LI>
<LI>_rest_vecs</LI>
<LI>_save_vecs</LI>
<LI>_scroll</LI>
<LI>_setcolor</LI>
<LI>_setcolor_low</LI>
<LI>_sound</LI>
<LI>waitvsync</LI>
</UL>
</P>
<H2><A NAME="ss5.2">5.2</A> <A HREF="#toc5.2">Hardware access</A>
</H2>
<P>The following pseudo variables declared in the <CODE>atari.h</CODE> header
file do allow access to hardware located in the address space. Some
variables are structures, accessing the struct fields will access the
chip registers.</P>
<P>
<DL>
<DT><B><CODE>GTIA_READ</CODE> and <CODE>GTIA_WRITE</CODE></B><DD>
<P>The <CODE>GTIA_READ</CODE> structure allows read access to the GTIA. The
<CODE>GTIA_WRITE</CODE> structure allows write access to the GTIA.
See the <CODE>_gtia.h</CODE> header file located in the include directory
for the declaration of the structure.</P>
<DT><B><CODE>POKEY_READ</CODE> and <CODE>POKEY_WRITE</CODE></B><DD>
<P>The <CODE>POKEY_READ</CODE> structure allows read access to the POKEY. The
<CODE>POKEY_WRITE</CODE> structure allows write access to the POKEY.
See the <CODE>_pokey.h</CODE> header file located in the include directory
for the declaration of the structure.</P>
<DT><B><CODE>ANTIC</CODE></B><DD>
<P>The <CODE>ANTIC</CODE> structure allows read access to the ANTIC.
See the <CODE>_antic.h</CODE> header file located in the include directory
for the declaration of the structure.</P>
<DT><B><CODE>PIA</CODE></B><DD>
<P>The <CODE>PIA</CODE> structure allows read access to the PIA 6520.
See the <CODE>_pia.h</CODE> header file located in the include directory
for the declaration of the structure.</P>
</DL>
</P>
<H2><A NAME="ss5.3">5.3</A> <A HREF="#toc5.3">Display lists</A>
</H2>
<P>A major feature of the Atari graphics chip "ANTIC" is to
process instructions for the display generation.
cc65 supports constructing these display lists by offering defines
for the instructions. In conjunction with the "void"-variable extension
of cc65, display lists can be created quite comfortable:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
...
unsigned char ScreenMemory[100];
void DisplayList =
{
DL_BLK8,
DL_BLK8,
DL_BLK8,
DL_LMS(DL_CHR20x8x2),
ScreenMemory,
DL_CHR20x8x2,
DL_CHR20x8x2,
DL_CHR20x8x2,
DL_BLK4,
DL_CHR20x8x2,
DL_JVB,
&DisplayList
};
...
OS.sdlst = &DisplayList;
...
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Please inspect the <CODE>_antic.h</CODE> header file to determine the supported
instruction names. Modifiers on instructions can be nested without need
for an order:</P>
<P><CODE>DL_LMS(DL_HSCROL(DL_VSCROL(DL_DLI(DL_MAP80x4x2))))</CODE></P>
<P>Please mind that ANTIC has memory alignment requirements for "player
missile graphics"-data, font data, display lists and screen memory. Creation
of a special linker configuration with appropriate aligned segments and
switching to that segment in the c-code is usually necessary. A more memory
hungry solution consists in using the
<A HREF="funcref.html#posix_memalign">posix_memalign()</A> function in conjunction with copying your data to the
allocated memory.</P>
<H2><A NAME="ss5.4">5.4</A> <A HREF="#toc5.4">Character mapping</A>
</H2>
<P>The Atari has two representations for characters:
<OL>
<LI> ATASCII is character mapping which is similar to ASCII and used
by the CIO system of the OS. This is the default mapping of cc65 when
producing code for the atari target.</LI>
<LI> The internal/screen mapping represents the real value of the
screen ram when showing a character.</LI>
</OL>
</P>
<P>For direct memory access (simplicity and speed) enabling the internal
mapping can be useful. This can be achieved by including the
"<CODE>atari_screen_charmap.h</CODE>" header.</P>
<P>A word of caution: Since the <CODE>0x00</CODE> character has to be mapped in an
incompatible way to the C-standard, the usage of string functions in
conjunction with internal character mapped strings delivers unexpected
results regarding the string length. The end of strings are detected where
you may not expect them (too early or (much) too late). Internal mapped
strings typically support the "<CODE>mem...()</CODE>" functions.</P>
<P><EM>For assembler sources the macro "<CODE>scrcode</CODE>" from the "<CODE>atari.mac</CODE>"
package delivers the same feature.</EM></P>
<P>You can switch back to the ATASCII mapping by including
"<CODE>atari_atascii_charmap.h</CODE>".</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
#include <atari_screen_charmap.h>
char* pcScreenMappingString = "Hello Atari!";
#include <atari_atascii_charmap.h>
char* pcAtasciiMappingString = "Hello Atari!";
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss5.5">5.5</A> <A HREF="#toc5.5">Keyboard codes</A>
</H2>
<P>For direct keyboard scanning in conjunction with e.g. the OS location "CH" (764/$2FC),
all keyboard codes are available as defined values on C and assembler side.</P>
<P>Example:
<BLOCKQUOTE><CODE>
<PRE>
...
while (!kbhit());
switch (OS.ch)
{
case KEY_RETURN:
...
case KEY_SPACE:
...
case KEY_1:
...
}
...
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>You can find the C defines in the file "<CODE>atari.h</CODE>" or "<CODE>atari.inc</CODE>" for the assembler variant.</P>
<H2><A NAME="s6">6.</A> <A HREF="#toc6">Loadable drivers</A></H2>
<P>The names in the parentheses denote the symbols to be used for static linking of the drivers.</P>
<H2><A NAME="ss6.1">6.1</A> <A HREF="#toc6.1">Graphics drivers</A>
</H2>
<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
<CODE>atari</CODE></TD><TD><CODE>atarixl</CODE></TD><TD>screen resolution</TD><TD>display pages</TD></TR><TR><TD>
<CODE>atr3.tgi (atr3_tgi)</CODE></TD><TD><CODE>atrx3.tgi (atrx3_tgi)</CODE></TD><TD>40x24x4 (CIO mode 3, ANTIC mode 8)</TD><TD>1</TD></TR><TR><TD>
<CODE>atr4.tgi (atr4_tgi)</CODE></TD><TD><CODE>atrx4.tgi (atrx4_tgi)</CODE></TD><TD>80x48x2 (CIO mode 4, ANTIC mode 9)</TD><TD>1</TD></TR><TR><TD>
<CODE>atr5.tgi (atr5_tgi)</CODE></TD><TD><CODE>atrx5.tgi (atrx5_tgi)</CODE></TD><TD>80x48x4 (CIO mode 5, ANTIC mode A)</TD><TD>1</TD></TR><TR><TD>
<CODE>atr6.tgi (atr6_tgi)</CODE></TD><TD><CODE>atrx6.tgi (atrx6_tgi)</CODE></TD><TD>160x96x2 (CIO mode 6, ANTIC mode B)</TD><TD>1</TD></TR><TR><TD>
<CODE>atr7.tgi (atr7_tgi)</CODE></TD><TD><CODE>atrx7.tgi (atrx7_tgi)</CODE></TD><TD>160x96x4 (CIO mode 7, ANTIC mode D)</TD><TD>1</TD></TR><TR><TD>
<CODE>atr8.tgi (atr8_tgi)</CODE></TD><TD><CODE>atrx8.tgi (atrx8_tgi)</CODE></TD><TD>320x192x2 (CIO mode 8, ANTIC mode F)</TD><TD>1</TD></TR><TR><TD>
<CODE>atr8p2.tgi (atr8p2_tgi)</CODE></TD><TD><CODE>atrx8p2.tgi (atrx8p2_tgi)</CODE></TD><TD>320x192x2 (CIO mode 8, ANTIC mode F)</TD><TD>2</TD></TR><TR><TD>
<CODE>atr9.tgi (atr9_tgi)</CODE></TD><TD><CODE>atrx9.tgi (atrx9_tgi)</CODE></TD><TD>80x192x16b (CIO mode 9, ANTIC mode F, GTIA mode $40)</TD><TD>1</TD></TR><TR><TD>
<CODE>atr9p2.tgi (atr9p2_tgi)</CODE></TD><TD><CODE>atrx9p2.tgi (atrx9p2_tgi)</CODE></TD><TD>80x192x16b (CIO mode 9, ANTIC mode F, GTIA mode $40)</TD><TD>2</TD></TR><TR><TD>
<CODE>atr10.tgi (atr10_tgi)</CODE></TD><TD><CODE>atrx10.tgi (atrx10_tgi)</CODE></TD><TD>80x192x9 (CIO mode 10, ANTIC mode F, GTIA mode $80)</TD><TD>1</TD></TR><TR><TD>
<CODE>atr10p2.tgi (atr10p2_tgi)</CODE></TD><TD><CODE>atrx10p2.tgi (atrx10p2_tgi)</CODE></TD><TD>80x192x9 (CIO mode 10, ANTIC mode F, GTIA mode $80)</TD><TD>2</TD></TR><TR><TD>
<CODE>atr11.tgi (atr11_tgi)</CODE></TD><TD><CODE>atrx11.tgi (atrx11_tgi)</CODE></TD><TD>80x192x16h (CIO mode 11, ANTIC mode F, GTIA mode $C0)</TD><TD>1</TD></TR><TR><TD>
<CODE>atr14.tgi (atr14_tgi)</CODE></TD><TD><CODE>atrx14.tgi (atrx14_tgi)</CODE></TD><TD>160x192x2 (CIO mode 14, ANTIC mode C)</TD><TD>1</TD></TR><TR><TD>
<CODE>atr15.tgi (atr15_tgi)</CODE></TD><TD><CODE>atrx15.tgi (atrx15_tgi)</CODE></TD><TD>160x192x4 (CIO mode 15, ANTIC mode E)</TD><TD>1</TD></TR><TR><TD>
<CODE>atr15p2.tgi (atr15p2_tgi)</CODE></TD><TD><CODE>atrx15p2.tgi (atrx15p2_tgi)</CODE></TD><TD>160x192x4 (CIO mode 15, ANTIC mode E)</TD><TD>2
</TD></TR></TABLE>
</CENTER><BR>
</P>
<P>Many graphics modes require more memory than the text screen which is
in effect when the program starts up. Therefore the programmer has to
tell the program beforehand the memory requirements of the graphics
modes the program intends to use.</P>
<P>On the <CODE>atari</CODE> target his can be done by using the __RESERVED_MEMORY__
linker config variable. The number specified there describes the number
of bytes to subtract from the top of available memory as seen from the
runtime library. This memory is then used by the screen buffer.</P>
<P>On the <CODE>atarixl</CODE> target the screen memory resides below the program
load address. In order to reserve memory for a graphics mode, one
simply uses a higher program load address. There are restrictions on
selectable load addresses,
see
<A HREF="#loadaddr">Selecting a good program load address</A>.</P>
<P>The numbers for the different graphics modes presented below should
only be seen as a rule of thumb. Since the screen buffer memory needs
to start at specific boundaries, the numbers depend on the current top
of available memory.
The following numbers were determined by a BASIC program.</P>
<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
graphics mode</TD><TD>reserved memory</TD></TR><TR><TD>
0</TD><TD>1</TD></TR><TR><TD>
1</TD><TD>1</TD></TR><TR><TD>
2</TD><TD>1</TD></TR><TR><TD>
3</TD><TD>1</TD></TR><TR><TD>
4</TD><TD>1</TD></TR><TR><TD>
5</TD><TD>182</TD></TR><TR><TD>
6</TD><TD>1182</TD></TR><TR><TD>
7</TD><TD>3198</TD></TR><TR><TD>
8</TD><TD>7120</TD></TR><TR><TD>
9</TD><TD>7146</TD></TR><TR><TD>
10</TD><TD>7146</TD></TR><TR><TD>
11</TD><TD>7146</TD></TR><TR><TD>
12</TD><TD>162</TD></TR><TR><TD>
13</TD><TD>1</TD></TR><TR><TD>
14</TD><TD>3278</TD></TR><TR><TD>
15</TD><TD>7120</TD></TR><TR><TD>
16</TD><TD>1</TD></TR><TR><TD>
17</TD><TD>1</TD></TR><TR><TD>
18</TD><TD>1</TD></TR><TR><TD>
19</TD><TD>1</TD></TR><TR><TD>
20</TD><TD>1</TD></TR><TR><TD>
21</TD><TD>184</TD></TR><TR><TD>
22</TD><TD>1192</TD></TR><TR><TD>
23</TD><TD>3208</TD></TR><TR><TD>
24</TD><TD>7146</TD></TR><TR><TD>
25</TD><TD>7146</TD></TR><TR><TD>
26</TD><TD>7146</TD></TR><TR><TD>
27</TD><TD>7146</TD></TR><TR><TD>
28</TD><TD>162</TD></TR><TR><TD>
29</TD><TD>1</TD></TR><TR><TD>
30</TD><TD>3304</TD></TR><TR><TD>
31</TD><TD>7146
</TD></TR></TABLE>
<CAPTION>reserved memory required for different graphics modes</CAPTION>
</CENTER><BR>
</P>
<P>The values of "1" are needed because the graphics command crashes if
it doesn't have at least one byte available. This seems to be a bug of
the Atari ROM code.</P>
<P>Default drivers: <CODE>atr8.tgi (atr8_tgi)</CODE> and <CODE>atrx8.tgi (atrx8_tgi)</CODE>.</P>
<H2><A NAME="ss6.2">6.2</A> <A HREF="#toc6.2">Extended memory drivers</A>
</H2>
<P>Currently there is only one extended memory driver. It manages the second 64K of a 130XE.</P>
<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
<CODE>atari</CODE></TD><TD><CODE>atarixl</CODE></TD></TR><TR><TD>
<CODE>atr130.emd (atr130_emd)</CODE></TD><TD><CODE>atrx130.emd (atrx130_emd)</CODE>
</TD></TR></TABLE>
</CENTER><BR>
</P>
<H2><A NAME="ss6.3">6.3</A> <A HREF="#toc6.3">Joystick drivers</A>
</H2>
<P>Currently there are two joystick drivers available:</P>
<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
<CODE>atari</CODE></TD><TD><CODE>atarixl</CODE></TD><TD>description</TD></TR><TR><TD>
<CODE>atrstd.joy (atrstd_joy)</CODE></TD><TD><CODE>atrxstd.joy (atrxstd_joy)</CODE></TD><TD>Supports up to two/four standard joysticks connected to the joystick ports of the Atari. (Four on the pre-XL systems, two on XL or newer.)</TD></TR><TR><TD>
<CODE>atrmj8.joy (atrmj8_joy)</CODE></TD><TD><CODE>atrxmj8.joy (atrxmj8_joy)</CODE></TD><TD>Supports up to eight standard joysticks connected to a MultiJoy adapter.
</TD></TR></TABLE>
</CENTER><BR>
</P>
<P>Default drivers: <CODE>atrstd.joy (atrstd_joy)</CODE> and <CODE>atrxstd.joy (atrxstd_joy)</CODE>.</P>
<H2><A NAME="ss6.4">6.4</A> <A HREF="#toc6.4">Mouse drivers</A>
</H2>
<P>Currently there are five mouse drivers available:</P>
<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
<CODE>atari</CODE></TD><TD><CODE>atarixl</CODE></TD><TD>description</TD></TR><TR><TD>
<CODE>atrjoy.mou (atrjoy_mou)</CODE></TD><TD><CODE>atrxjoy.mou (atrxjoy_mou)</CODE></TD><TD>Supports a mouse emulated by a standard joystick.</TD></TR><TR><TD>
<CODE>atrst.mou (atrst_mou)</CODE></TD><TD><CODE>atrxst.mou (atrxst_mou)</CODE></TD><TD>Supports an Atari ST mouse.</TD></TR><TR><TD>
<CODE>atrami.mou (atrami_mou)</CODE></TD><TD><CODE>atrxami.mou (atrxami_mou)</CODE></TD><TD>Supports an Amiga mouse.</TD></TR><TR><TD>
<CODE>atrtrk.mou (atrtrk_mou)</CODE></TD><TD><CODE>atrxtrk.mou (atrxtrk_mou)</CODE></TD><TD>Supports an Atari trakball.</TD></TR><TR><TD>
<CODE>atrtt.mou (atrtt_mou)</CODE></TD><TD><CODE>atrxtt.mou (atrxtt_mou)</CODE></TD><TD>Supports an Atari touch tablet.
</TD></TR></TABLE>
</CENTER><BR>
</P>
<P>All mouse devices connect to joystick port #0.</P>
<P>Default drivers: <CODE>atrst.mou (atrst_mou)</CODE> and <CODE>atrxst.mou (atrxst_mou)</CODE>.</P>
<H3>Mouse callbacks</H3>
<P>There are two mouse callbacks available.</P>
<P>The "text mode" callbacks (<CODE>mouse_txt_callbacks</CODE>) display the mouse cursor as a "diamond" character
on the standard "GRAPHICS 0" text mode screen. The mouse cursor character can be changed by an
assembly file defining the character by exporting the zeropage symbol <CODE>mouse_txt_char</CODE>.
The default file looks like this:
<BLOCKQUOTE><CODE>
<PRE>
.export mouse_txt_char : zp = 96 ; 'diamond' screen code
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The "P/M" callbacks (<CODE>mouse_pm_callbacks</CODE>) use Player-Missile graphics for the mouse cursor.
The cursor shape can be changed, too, by an assembly file. Here's the default shape definition:
<BLOCKQUOTE><CODE>
<PRE>
.export mouse_pm_bits
.export mouse_pm_height : zeropage
.export mouse_pm_hotspot_x : zeropage
.export mouse_pm_hotspot_y : zeropage
.rodata
mouse_pm_bits:
.byte %11110000
.byte %11000000
.byte %10100000
.byte %10010000
.byte %10001000
.byte %00000100
.byte %00000010
mouse_pm_height = * - mouse_pm_bits
; hot spot is upper left corner
mouse_pm_hotspot_x = 0
mouse_pm_hotspot_y = 0
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P><CODE>mouse_pm_bits</CODE> defines the shape of the cursor, <CODE>mouse_pm_height</CODE> defines the number of
bytes in <CODE>mouse_pm_bits</CODE>. <CODE>mouse_pm_hotspot_x</CODE> and <CODE>mouse_pm_hotspot_y</CODE> define the
position in the shape where "the mouse points to". When using this callback page #6 ($600
- $6FF) is used for the P/M graphics data and no P/M graphics can otherwise be used
by the program. The height of the shape (<CODE>mouse_pm_height</CODE>)
must not exceed 32 lines since the callback routines cannot handle more than 32 lines.</P>
<P>The default callbacks definition (<CODE>mouse_def_callbacks</CODE>) is an alias for the "P/M" callbacks.</P>
<H2><A NAME="ss6.5">6.5</A> <A HREF="#toc6.5">RS232 device drivers</A>
</H2>
<P>Currently there is one RS232 driver. It supports up to 9600 baud, requires hardware flow control
(RTS/CTS) and uses the R: device (therefore an R: driver needs to be installed). It was tested
with the 850 interface module.</P>
<P>
<BR><CENTER>
<TABLE BORDER><TR><TD>
<CODE>atari</CODE></TD><TD><CODE>atarixl</CODE></TD></TR><TR><TD>
<CODE>atrrdev.ser (atrrdev_ser)</CODE></TD><TD><CODE>atrxrdev.ser (atrxrdev_ser)</CODE>
</TD></TR></TABLE>
</CENTER><BR>
</P>
<H2><A NAME="s7">7.</A> <A HREF="#toc7">Limitations</A></H2>
<H2><A NAME="realtimeclock"></A> <A NAME="ss7.1">7.1</A> <A HREF="#toc7.1"><CODE>Realtime clock</CODE></A>
</H2>
<P>Access to the realtime clock is supported only when running on SpartaDOS-X.
There needs to be a realtime clock driver installed. This is normally the case
in the default installation (CONFIG.SYS) of SpartaDOS-X.
A missing realtime clock driver in SpartaDOS-X is not supported, and the program
may crash when calling the <CODE>clock_settime()</CODE> or <CODE>clock_gettime()</CODE>
functions.</P>
<P>The resolution of the realtime clock driver is 1 second.</P>
<H2><A NAME="xllimitations"></A> <A NAME="ss7.2">7.2</A> <A HREF="#toc7.2"><CODE>atarixl target</CODE></A>
</H2>
<P>
<UL>
<LI>The display is cleared at program start and at program termination. This is a side
effect of relocating the display memory below the program start address.</LI>
<LI>Not all possible CIO and SIO functions are handled by the runtime stub code which banks
the ROM in and out. All functions used by the runtime library are handled, though.</LI>
<LI>The <CODE>_sys()</CODE> function is not supported.</LI>
<LI>It is not compatible with DOSes or other programs using the memory below the ROM.</LI>
</UL>
</P>
<H2><A NAME="dio"></A> <A NAME="s8">8.</A> <A HREF="#toc8">DIO implementation</A></H2>
<P>The Atari supports disk drives with either 128 or 256 byte sectors.
The first three sectors of any disk are always 128 bytes long though. This is
because the system can only boot from 128 bytes sectors.</P>
<P>Therefore the DIO read and write functions transfer only 128 bytes
for sectors 1 to 3, regardless of the type of diskette.</P>
<H2><A NAME="conio"></A> <A NAME="s9">9.</A> <A HREF="#toc9">CONIO implementation</A></H2>
<P>The console I/O is speed optimized therefore support for XEP80 hardware
or f80.com software is missing. Of course you may use stdio.h functions.</P>
<P><CODE>cprintf</CODE> targets a 40 character line. On a 20-column display this has
the unexpected effect of a blank line after your text. On such displays you can either
use for example <CODE>gotoxy(20,0)</CODE> to target the "next" line, or you can switch to <CODE>write()</CODE>
function which does not have this side effect.</P>
<H2><A NAME="techdetail"></A> <A NAME="s10">10.</A> <A HREF="#toc10">Technical details</A></H2>
<H2><A NAME="ss10.1">10.1</A> <A HREF="#toc10.1"><CODE>atari</CODE></A>
</H2>
<H3>Load chunks</H3>
<P>An <CODE>atari</CODE> program contains two load chunks.</P>
<P>
<OL>
<LI>"system check"
<A NAME="syschk"></A> <BR>
This load chunk is always loaded at address $2E00, and checks if the system has
enough memory to run the program. It also checks if the program start address is not
below MEMLO. If any of the checks return false, the loading of the program is aborted.<BR>
The contents of this chunk come from the SYSCHKCHNK memory area of the linker config file.</LI>
<LI>main program<BR>
This load chunk is loaded at the selected program start address (default $2000) and
contains all of the code and data of the program.<BR>
The contents of this chunk come from the MAIN memory area of the linker config file.</LI>
</OL>
</P>
<H2><A NAME="ss10.2">10.2</A> <A HREF="#toc10.2"><CODE>atarixl</CODE></A>
</H2>
<H3>General operation</H3>
<P>The <CODE>atarixl</CODE> target banks out the ROM while the program is running in
order to make more memory available to the program.</P>
<P>The screen memory is by default located at the top of available memory,
$BFFF if BASIC is not enabled, $9FFF if BASIC is enabled.
Therefore, in order to create a largest possible continuous memory area,
the screen memory is moved below the program load address. This gives
a memory area from <program load addr> to $CFFF.</P>
<P>The startup code installs wrappers for interrupt handlers and ROM routines.
When an interrupt or call to a ROM routine happens, the wrappers enable the
ROM, call the handler or routine, and disable the ROM again.</P>
<P>The "wrapping" of the ROM routines is done by changing the ROM entry
point symbols in <CODE>atari.inc</CODE> to point to the wrapper functions.</P>
<P>For ROM functions which require input or output buffers, the wrappers
copy the data as required to buffers in low memory.</P>
<H3><A NAME="xlchunks"></A> Load chunks</H3>
<P>An <CODE>atarixl</CODE> program contains three load chunks.</P>
<P>
<OL>
<LI>"system check"
<A NAME="syschkxl"></A> <BR>
This load chunk is always loaded at address $2E00, and checks if the system is
suitable for running the program. It also checks if there is enough room between MEMLO
and the program start address to move the text mode screen buffer there. If any of the
checks return false, the loading of the program is aborted.<BR>
The contents of this chunk come from the SYSCHKCHNK memory area of the linker config file.</LI>
<LI>"shadow RAM prepare"<BR>
The second load chunk gets loaded to the selected program load address (default $2400).
It moves the screen memory below the program load address, copies the character generator
from ROM to its new place in RAM, and copies the parts of the program which reside in
high memory below the ROM to their place. The high memory parts are included in this load chunk.<BR>
At the beginning of this load chunk there is a .bss area, which is not part of the
EXE file. Therefore the on-disk start address of this load chunk will be higher than the
selected start address. This .bss area (segment LOWBSS) contains the buffers for the
double buffering of ROM input and output data. If you add contents to this segment be aware
that the contents won't be zero initialized by the startup code.<BR>
The contents of this chunk come from the SRPREPCHNK memory area of the linker config file.</LI>
<LI>main program<BR>
This load chunk is loaded just above the LOWBSS segment, replacing the code of
the previous load chunk. It contains all remaining code and data sections of the program,
including the startup code.<BR>
The contents of this chunk come from the RAM memory area of the linker config file.</LI>
</OL>
</P>
<H3>Moving screen memory below the program start address</H3>
<P>When setting a graphics mode, the ROM looks at the RAMTOP location. RAMTOP
describes the amount of installed memory in pages (RAMTOP is only one byte).
The screen memory and display list are placed immediately below RAMTOP.</P>
<P>Now in order to relocate the screen memory to lower memory, the startup code
puts a value into RAMTOP which causes the ROM routines to allocate the display
memory below the program start address and then it issues a ROM call to setup
the regular text mode.</P>
<H3><A NAME="loadaddr"></A> Selecting a good program load address</H3>
<P>Due to the movement of the screen memory below the program start, there are some
load addresses which are sub-optimal because they waste memory or prevent a
higher resolution graphics mode from being enabled.</P>
<P>There are restrictions at which addresses screen memory (display buffer and display
list) can be placed. The display buffer cannot cross a 4K boundary and a display
list cannot cross a 1K boundary.</P>
<P>The startup code takes this into account when moving the screen memory down.
If the program start address (aligned to the next lower page boundary) minus
the screen buffer size would result in a screen buffer which spans a 4K
boundary, the startup code lowers RAMTOP to this 4K boundary.<BR>
The size of the screen buffer in text mode is 960 ($3C0) bytes. So, for
example, a selected start address of $2300 would span the 4K boundary
at $2000. The startup code would adjust the RAMTOP value in such way that
the screen memory would be located just below this boundary (at $1C40).
This results in the area [$2000-$22FF] being wasted.
Additionally, the program might fail to load since the lowest address used
by the screen memory could be below MEMLO. (The lowest address used in this
example would be at $1C20, where the display list would allocated.)</P>
<P>These calculations are performed by the startup code (in the first two
load chunks), but the startup code only takes the default 40x24 text mode
into account. If the program later wants to load TGI drivers which set
a more memory consuming graphics mode, the user has to pick a higher
load address.
Using higher resolution modes there is a restriction in the ROM that it
doesn't expect RAMTOP to be at arbitrary values. The Atari memory modules
came only in 8K or 16K sizes, so the ROM expects RAMTOP to only have
values in 8K steps. Therefore, when using the highest resolution modes
the program start address must be at an 8K boundary.</P>
<H3><A NAME="chargenloc"></A> Character generator location</H3>
<P>The default <CODE>atarixl</CODE> linker config file (<CODE>atarixl.cfg</CODE>) leaves the
character generator location at the same address where it is in ROM
($E000). This has the disadvatage to split the upper memory into
two parts ([$D800-$DFFF] and
[$E400-$FFF9]). For applications which
require a large continuous upper memory area, an alternative linker
config file (<CODE>atarixl-largehimem.cfg</CODE>) is provided. It relocates the
character generator to $D800, providing a single big upper
memory area at [$DC00-$FFF9].</P>
<P>With the character generator at a different address than in ROM, the routines
which enable and disable the ROM also have to update the chargen pointer.
This code is not enabled by default. In order to enable it,
uncomment the line which sets CHARGEN_RELOC in <CODE>libsrc/atari/Makefile.inc</CODE>
and recompile the <CODE>atarixl</CODE> runtime library.</P>
<H2><A NAME="s11">11.</A> <A HREF="#toc11">Other hints</A></H2>
<H2><A NAME="ss11.1">11.1</A> <A HREF="#toc11.1">Function keys</A>
</H2>
<P>Function keys are mapped to Atari + number key.</P>
<H2><A NAME="ss11.2">11.2</A> <A HREF="#toc11.2">Passing arguments to the program</A>
</H2>