-
Notifications
You must be signed in to change notification settings - Fork 16
Expand file tree
/
Copy pathapple2.html
More file actions
956 lines (712 loc) · 33.7 KB
/
apple2.html
File metadata and controls
956 lines (712 loc) · 33.7 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
<!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>Apple ][ specific information for cc65</TITLE>
</HEAD>
<BODY>
<H1>Apple ][ specific information for cc65</H1>
<H2>
<A HREF="mailto:ol.sc@web.de">Oliver Schmidt</A></H2>
<HR>
<EM>An overview over the Apple ][ runtime system as it is
implemented for the cc65 C compiler.</EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="apple2.html#s1">Overview</A></H2>
<P>
<H2><A NAME="toc2">2.</A> <A HREF="apple2.html#s2">Binary format</A></H2>
<P>
<H2><A NAME="toc3">3.</A> <A HREF="apple2.html#s3">Memory layout</A></H2>
<P>
<H2><A NAME="toc4">4.</A> <A HREF="apple2.html#s4">Linker configurations</A></H2>
<UL>
<LI><A NAME="toc4.1">4.1</A> <A HREF="apple2.html#ss4.1">default config file (<CODE>apple2.cfg</CODE>)</A>
<LI><A NAME="toc4.2">4.2</A> <A HREF="apple2.html#ss4.2"><CODE>apple2-system.cfg</CODE></A>
<LI><A NAME="toc4.3">4.3</A> <A HREF="apple2.html#ss4.3"><CODE>apple2-hgr.cfg</CODE></A>
<LI><A NAME="toc4.4">4.4</A> <A HREF="apple2.html#ss4.4"><CODE>apple2-overlay.cfg</CODE></A>
<LI><A NAME="toc4.5">4.5</A> <A HREF="apple2.html#ss4.5"><CODE>apple2-asm.cfg</CODE></A>
</UL>
<P>
<H2><A NAME="toc5">5.</A> <A HREF="apple2.html#s5">ProDOS 8 system programs</A></H2>
<UL>
<LI><A NAME="toc5.1">5.1</A> <A HREF="apple2.html#ss5.1">LOADER.SYSTEM</A>
<LI><A NAME="toc5.2">5.2</A> <A HREF="apple2.html#ss5.2">Heap</A>
<LI><A NAME="toc5.3">5.3</A> <A HREF="apple2.html#ss5.3">ProDOS 8 I/O buffers</A>
</UL>
<P>
<H2><A NAME="toc6">6.</A> <A HREF="apple2.html#s6">Platform specific header files</A></H2>
<UL>
<LI><A NAME="toc6.1">6.1</A> <A HREF="apple2.html#ss6.1">Apple ][ specific functions</A>
<LI><A NAME="toc6.2">6.2</A> <A HREF="apple2.html#ss6.2">Apple IIgs specific functions in accelerator.h</A>
<LI><A NAME="toc6.3">6.3</A> <A HREF="apple2.html#ss6.3">Hardware access</A>
</UL>
<P>
<H2><A NAME="toc7">7.</A> <A HREF="apple2.html#s7">Loadable drivers</A></H2>
<UL>
<LI><A NAME="toc7.1">7.1</A> <A HREF="apple2.html#ss7.1">Graphics drivers</A>
<LI><A NAME="toc7.2">7.2</A> <A HREF="apple2.html#ss7.2">Extended memory drivers</A>
<LI><A NAME="toc7.3">7.3</A> <A HREF="apple2.html#ss7.3">Joystick drivers</A>
<LI><A NAME="toc7.4">7.4</A> <A HREF="apple2.html#ss7.4">Mouse drivers</A>
<LI><A NAME="toc7.5">7.5</A> <A HREF="apple2.html#ss7.5">RS232 device drivers</A>
</UL>
<P>
<H2><A NAME="toc8">8.</A> <A HREF="apple2.html#s8">Limitations</A></H2>
<UL>
<LI><A NAME="toc8.1">8.1</A> <A HREF="apple2.html#ss8.1">DOS 3.3</A>
<LI><A NAME="toc8.2">8.2</A> <A HREF="apple2.html#ss8.2">Direct console I/O</A>
<LI><A NAME="toc8.3">8.3</A> <A HREF="apple2.html#ss8.3">Random number generator</A>
<LI><A NAME="toc8.4">8.4</A> <A HREF="apple2.html#ss8.4">Realtime clock</A>
</UL>
<P>
<H2><A NAME="toc9">9.</A> <A HREF="apple2.html#s9">Other hints</A></H2>
<UL>
<LI><A NAME="toc9.1">9.1</A> <A HREF="apple2.html#ss9.1">Passing arguments to the program</A>
<LI><A NAME="toc9.2">9.2</A> <A HREF="apple2.html#ss9.2">Interrupts</A>
<LI><A NAME="toc9.3">9.3</A> <A HREF="apple2.html#ss9.3">ProDOS date/time manipulation</A>
<LI><A NAME="toc9.4">9.4</A> <A HREF="apple2.html#ss9.4">DIO</A>
<LI><A NAME="toc9.5">9.5</A> <A HREF="apple2.html#ss9.5">Specifying file types for fopen</A>
</UL>
<P>
<H2><A NAME="toc10">10.</A> <A HREF="apple2.html#s10">License</A></H2>
<HR>
<H2><A NAME="s1">1.</A> <A HREF="#toc1">Overview</A></H2>
<P>This file contains an overview of the Apple ][ runtime system
as it comes with the cc65 C compiler. It describes the memory layout,
Apple ][ specific header files, available drivers, and any
pitfalls specific to that platform.</P>
<P>Please note that Apple ][ 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 standard binary file format generated by the linker for the
Apple ][ target is an
<A HREF="https://nulib.com/library/AppleSingle_AppleDouble.pdf">AppleSingle</A> file.
The default load address is $803.</P>
<P><B>AppleCommander 1.4.0</B> or later (available at
<A HREF="https://applecommander.github.io/">https://applecommander.github.io/</A>) includes the option <CODE>-as</CODE> that
allows to put AppleSingle files onto disk images containing DOS 3.3 as well
as ProDOS 8.</P>
<H2><A NAME="s3">3.</A> <A HREF="#toc3">Memory layout</A></H2>
<P>In the standard setup, cc65 generated programs use the memory from
$803 to $95FF, so 35.5 KB of RAM are available.</P>
<P>Special locations:</P>
<P>
<DL>
<DT><B>Stack</B><DD>
<P>The C runtime stack is located at HIMEM and grows downwards, regardless of
how your linker config file is setup.</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>
<P>While running <CODE>main()</CODE> the Language Card bank 2 is enabled for read access.
However while running module constructors the Language Card is disabled.</P>
<P>Enabling the Language Card allows to use it as additional memory for cc65
generated code. However code is never automatically placed there. Rather code
needs to be explicitly placed in the Language Card either per file by compiling
with <CODE>--code-name LC</CODE> or per function by enclosing in <CODE>#pragma code-name
(push, "LC")</CODE> and <CODE>#pragma code-name (pop)</CODE>. In either case the cc65 runtime
system takes care of actually moving the code into the Language Card.</P>
<P>The amount of memory available in the Language Card for generated code depends
on the
<A HREF="#link-configs">linker configuration</A> parameters. There are
several useful settings:</P>
<P>
<DL>
<DT><B>LC address: $D400, LC size: $C00</B><DD>
<P>For plain vanilla ProDOS 8 which doesn't actually use the Language Card bank 2
memory from $D400 to $DFFF. This is the default setting.</P>
<DT><B>LC address: $D000, LC size: $1000</B><DD>
<P>For ProDOS 8 together with the function <CODE>rebootafterexit()</CODE>. If a program
doesn't quit to the ProDOS 8 dispatcher but rather reboots the machine after
exit then a plain vanilla ProDOS 8 doesn't make use of the Language Card bank
2 at all.</P>
<DT><B>LC address: $D000, LC size: $2FFC</B><DD>
<P>For plain vanilla DOS 3.3 which doesn't make use of the Language Card at all.</P>
</DL>
</P>
<P>
<DL>
<DT><B>Installing your code in the Language Card</B><DD>
<P>The code in the LC segment will automatically be copied from the end of the
binary into the Language Card at startup, even if the segment is empty (a
0-byte copy). This allows for tighter code. This code will be copied using the
Applesoft BLTU2 function that is available starting with the Apple ][+,
but not in the original Apple ][ with an Integer BASIC ROM. This shows as
a "RANGE ERROR. STOPPING AT ..." message on startup.</P>
<P>If you want to target the Integer BASIC original Apple ][, you can link in an
alternative implementation of the LC segment loading, at the cost of linking
in memcpy (60 bytes):</P>
<P>Using <CODE>apple2-integer-basic-compat.o</CODE> is as simple as placing it on the linker
command line like this:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
cl65 -t apple2 myprog.c apple2-integer-basic-compat.o
</PRE>
</CODE></BLOCKQUOTE>
</P>
</DL>
</P>
<H2><A NAME="link-configs"></A> <A NAME="s4">4.</A> <A HREF="#toc4">Linker configurations</A></H2>
<P>The ld65 linker comes with a default config file for the Apple ][,
which is used via <CODE>-t apple2</CODE>.
The apple2 package comes with additional secondary linker config files, which
are used via <CODE>-t apple2 -C <configfile></CODE>.</P>
<H2><A NAME="apple-def-cfg"></A> <A NAME="ss4.1">4.1</A> <A HREF="#toc4.1">default config file (<CODE>apple2.cfg</CODE>)</A>
</H2>
<P>Default configuration for a binary program.</P>
<P>Parameters:</P>
<P>
<DL>
<DT><B><CODE>STARTADDRESS:</CODE> Program start address</B><DD>
<P>Default: $803. Use <CODE>-S <addr></CODE> to set a different start address.</P>
<DT><B><CODE>__EXEHDR__:</CODE> AppleSingle executable file header</B><DD>
<P>Default: Yes. Use <CODE>-D __EXEHDR__=0</CODE> to omit the AppleSingle header.</P>
<DT><B><CODE>__STACKSIZE__:</CODE> C runtime stack size</B><DD>
<P>Default: $800. Use <CODE>-D __STACKSIZE__=<size></CODE> to set a different
stack size.</P>
<DT><B><CODE>__HIMEM__:</CODE> Highest usable memory address presumed at link time</B><DD>
<P>Default: $9600. Use <CODE>-D __HIMEM__=<addr></CODE> to set a different
highest usable address.</P>
<DT><B><CODE>__LCADDR__:</CODE> Address of code in the Language Card</B><DD>
<P>Default: $D400. Use <CODE>-D __LCADDR__=<addr></CODE> to set a different
code address.</P>
<DT><B><CODE>__LCSIZE__:</CODE> Size of code in the Language Card</B><DD>
<P>Default: $C00. Use <CODE>-D __LCSIZE__=<size></CODE> to set a different
code size.</P>
</DL>
</P>
<H2><A NAME="apple-sys-cfg"></A> <A NAME="ss4.2">4.2</A> <A HREF="#toc4.2"><CODE>apple2-system.cfg</CODE></A>
</H2>
<P>Configuration for a system program running on ProDOS 8 and using the memory from
$2000 to $BEFF.</P>
<P>Parameters:</P>
<P>
<DL>
<DT><B><CODE>__EXEHDR__:</CODE> AppleSingle executable file header</B><DD>
<P>Default: Yes. Use <CODE>-D __EXEHDR__=0</CODE> to omit the AppleSingle header.</P>
<DT><B><CODE>__STACKSIZE__:</CODE> C runtime stack size</B><DD>
<P>Default: $800. Use <CODE>-D __STACKSIZE__=<size></CODE> to set a different
stack size.</P>
<DT><B><CODE>__LCADDR__:</CODE> Address of code in the Language Card</B><DD>
<P>Default: $D400. Use <CODE>-D __LCADDR__=<addr></CODE> to set a different
code address.</P>
<DT><B><CODE>__LCSIZE__:</CODE> Size of code in the Language Card</B><DD>
<P>Default: $C00. Use <CODE>-D __LCSIZE__=<size></CODE> to set a different
code size.</P>
</DL>
</P>
<H2><A NAME="ss4.3">4.3</A> <A HREF="#toc4.3"><CODE>apple2-hgr.cfg</CODE></A>
</H2>
<P>Configuration for a program including a hires page. See <CODE>testcode/lib/apple/hgrtest.c</CODE>
for an example of such a program.</P>
<P>Parameters:</P>
<P>
<DL>
<DT><B><CODE>STARTADDRESS:</CODE> Program start address</B><DD>
<P>Default: $803. Use <CODE>-S <addr></CODE> to set a different start address.</P>
<DT><B><CODE>__EXEHDR__:</CODE> AppleSingle executable file header</B><DD>
<P>Default: Yes. Use <CODE>-D __EXEHDR__=0</CODE> to omit the AppleSingle header.</P>
<DT><B><CODE>__STACKSIZE__:</CODE> C runtime stack size</B><DD>
<P>Default: $800. Use <CODE>-D __STACKSIZE__=<size></CODE> to set a different
stack size.</P>
<DT><B><CODE>__HIMEM__:</CODE> Highest usable memory address presumed at link time</B><DD>
<P>Default: $9600. Use <CODE>-D __HIMEM__=<addr></CODE> to set a different
highest usable address.</P>
<DT><B><CODE>__LCADDR__:</CODE> Address of code in the Language Card</B><DD>
<P>Default: $D400. Use <CODE>-D __LCADDR__=<addr></CODE> to set a different
code address.</P>
<DT><B><CODE>__LCSIZE__:</CODE> Size of code in the Language Card</B><DD>
<P>Default: $C00. Use <CODE>-D __LCSIZE__=<size></CODE> to set a different
code size.</P>
</DL>
</P>
<H2><A NAME="ss4.4">4.4</A> <A HREF="#toc4.4"><CODE>apple2-overlay.cfg</CODE></A>
</H2>
<P>Configuration for an overlay program with up to nine overlays. The overlay files
don't include the AppleSingle header. See <CODE>samples/overlaydemo.c</CODE> for more
information on overlays.</P>
<P>Parameters:</P>
<P>
<DL>
<DT><B><CODE>STARTADDRESS:</CODE> Program start address</B><DD>
<P>Default: $803. Use <CODE>-S <addr></CODE> to set a different start address.</P>
<DT><B><CODE>__EXEHDR__:</CODE> AppleSingle executable file header</B><DD>
<P>Default: Yes. Use <CODE>-D __EXEHDR__=0</CODE> to omit the AppleSingle header.</P>
<DT><B><CODE>__STACKSIZE__:</CODE> C runtime stack size</B><DD>
<P>Default: $800. Use <CODE>-D __STACKSIZE__=<size></CODE> to set a different
stack size.</P>
<DT><B><CODE>__HIMEM__:</CODE> Highest usable memory address presumed at link time</B><DD>
<P>Default: $9600. Use <CODE>-D __HIMEM__=<addr></CODE> to set a different
highest usable address.</P>
<DT><B><CODE>__LCADDR__:</CODE> Address of code in the Language Card</B><DD>
<P>Default: $D400. Use <CODE>-D __LCADDR__=<addr></CODE> to set a different
code address.</P>
<DT><B><CODE>__LCSIZE__:</CODE> Size of code in the Language Card</B><DD>
<P>Default: $C00. Use <CODE>-D __LCSIZE__=<size></CODE> to set a different
code size.</P>
<DT><B><CODE>__OVERLAYSIZE__:</CODE> Size of code in the overlays</B><DD>
<P>Default: $1000. Use <CODE>-D __OVERLAYSIZE__=<size></CODE> to set a different
code size.</P>
</DL>
</P>
<H2><A NAME="ss4.5">4.5</A> <A HREF="#toc4.5"><CODE>apple2-asm.cfg</CODE></A>
</H2>
<P>Configuration for an assembler program that doesn't need a special setup.</P>
<P>Parameters:</P>
<P>
<DL>
<DT><B><CODE>STARTADDRESS:</CODE> Program start address</B><DD>
<P>Default: $803. Use <CODE>-S <addr></CODE> to set a different start address.</P>
<DT><B><CODE>__EXEHDR__:</CODE> AppleSingle executable file header</B><DD>
<P>Default: No. Use <CODE>-u __EXEHDR__ apple2.lib</CODE> to add the AppleSingle header.</P>
</DL>
</P>
<H2><A NAME="s5">5.</A> <A HREF="#toc5">ProDOS 8 system programs</A></H2>
<P>ProDOS 8 system programs are always loaded to the start address $2000.
For cc65 programs this means that the 6 KB from $800 to $2000 are
by default unused. There are however several options to make use of that memory
range.</P>
<H2><A NAME="ss5.1">5.1</A> <A HREF="#toc5.1">LOADER.SYSTEM</A>
</H2>
<P>The easiest (and for really large programs in fact the only) way to have a cc65
program use the memory from $800 to $2000 is to link it as binary
(as opposed to system) program using the default linker configuration
<A HREF="#apple-def-cfg">apple2.cfg</A> with <CODE>__HIMEM__</CODE> set to $BF00
and load it with the LOADER.SYSTEM utility. The program then works like a system
program (i.e. quits to the ProDOS dispatcher).</P>
<P>Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the
program to load under name <program>.SYSTEM as a system program. For
example the program <CODE>MYPROG</CODE> is loaded by <CODE>MYPROG.SYSTEM</CODE>. The right
AppleCommander option to put LOADER.SYSTEM on a ProDOS 8 disk image is <CODE>-p</CODE>.</P>
<H2><A NAME="ss5.2">5.2</A> <A HREF="#toc5.2">Heap</A>
</H2>
<P>If the cc65 program can be successfully linked as system program using the linker
configuration
<A HREF="#apple-sys-cfg">apple2-system.cfg</A>, but
uses the heap either explicitly or implicitly (i.e. by loading a driver) then
the memory from $800 to $1FFF can be added to the heap by calling
<CODE>_heapadd ((void *) 0x0800, 0x1800);</CODE> at the beginning of <CODE>main()</CODE>.</P>
<H2><A NAME="ss5.3">5.3</A> <A HREF="#toc5.3">ProDOS 8 I/O buffers</A>
</H2>
<P>ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default
these buffers are allocated by the cc65 runtime system on the heap using
<A HREF="funcref.html#posix_memalign">posix_memalign()</A>. While this is
generally the best solution it means quite some overhead for (especially rather
small) cc65 programs which do open files but don't make use of the heap otherwise.</P>
<P>The apple2 package comes with the alternative ProDOS 8 I/O buffer allocation
module <CODE>apple2-iobuf-0800.o</CODE> which uses the memory between $800 and
the program start address for the 1 KB I/O buffers. For system programs (with
start address $2000) this results in up to 6 I/O buffers and thus up to 6
concurrently open files.</P>
<P>While using <CODE>_heapadd()</CODE> as described in the section above together with the
default I/O buffer allocation basically yields the same placement of I/O buffers
in memory the primary benefit of <CODE>apple2-iobuf-0800.o</CODE> is a reduction in code
size - and thus program file size - of more than 1400 bytes.</P>
<P>Using <CODE>apple2-iobuf-0800.o</CODE> is as simple as placing it on the linker command
line like this:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
cl65 -t apple2 -C apple2-system.cfg myprog.c apple2-iobuf-0800.o
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="s6">6.</A> <A HREF="#toc6">Platform specific header files</A></H2>
<P>Programs containing Apple ][ specific code may use the
<CODE>apple2.h</CODE> header file.</P>
<H2><A NAME="ss6.1">6.1</A> <A HREF="#toc6.1">Apple ][ specific functions</A>
</H2>
<P>The functions and variables listed below are special for the Apple ][.
See the
<A HREF="funcref.html">function reference</A> for declaration and
usage.</P>
<P>
<UL>
<LI>_auxtype</LI>
<LI>_dos_type</LI>
<LI>_filetype</LI>
<LI>_datetime</LI>
<LI>allow_lowercase</LI>
<LI>beep</LI>
<LI>dir_entry_count</LI>
<LI>file_set_auxtype</LI>
<LI>file_set_type</LI>
<LI>get_tv</LI>
<LI>get_ostype</LI>
<LI>gmtime_dt</LI>
<LI>mktime_dt</LI>
<LI>rebootafterexit</LI>
<LI>ser_apple2_slot</LI>
<LI>tgi_apple2_mix</LI>
<LI>videomode</LI>
</UL>
</P>
<H2><A NAME="ss6.2">6.2</A> <A HREF="#toc6.2">Apple IIgs specific functions in accelerator.h</A>
</H2>
<P>In addition to those, the <CODE>accelerator.h</CODE> header file contains three functions
to help determine whether the program is running on a IIgs, and change the IIgs
CPU speed. See the
<A HREF="funcref.html">function reference</A> for declaration and
usage.</P>
<P>
<UL>
<LI>detect_iigs</LI>
<LI>get_iigs_speed</LI>
<LI>set_iigs_speed</LI>
</UL>
</P>
<H2><A NAME="ss6.3">6.3</A> <A HREF="#toc6.3">Hardware access</A>
</H2>
<P>There's currently no support for direct hardware access. This does not mean
you cannot do it, it just means that there's no help.</P>
<H2><A NAME="s7">7.</A> <A HREF="#toc7">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="ss7.1">7.1</A> <A HREF="#toc7.1">Graphics drivers</A>
</H2>
<P>
<DL>
<DT><B><CODE>a2.lo.tgi (a2_lo_tgi)</CODE></B><DD>
<P>This driver features a resolution of 40×48 with 16 colors.</P>
<P>The function <CODE>tgi_apple2_mix()</CODE> allows to activate 4 lines of text. The
function clears the corresponding area at the bottom of the screen.</P>
<DT><B><CODE>a2.hi.tgi (a2_hi_tgi)</CODE></B><DD>
<P>This driver features a resolution of 280×192 with 8 colors and two
hires pages. Note that programs using this driver will have to be linked
with <CODE>-S $4000</CODE> to reserve the first hires page or with <CODE>-S $6000</CODE>
to reserve both hires pages.</P>
<P>Note that the second hires page is only available if the text display is not in
80 column mode. This can be asserted by calling <CODE>videomode (VIDEOMODE_40COL);</CODE>
before installing the driver.</P>
<P>The function <CODE>tgi_apple2_mix()</CODE> allows to activate 4 lines of text. The
function doesn't clear the corresponding area at the bottom of the screen.</P>
<P>In memory constrained situations the memory from $803 to $1FFF
can be made available to a program by calling <CODE>_heapadd ((void *) 0x0803, 0x17FD);</CODE>
at the beginning of <CODE>main()</CODE>. Doing so is beneficial even if the program
doesn't use the heap explicitly because loading the driver (and in fact
already opening the driver file) uses the heap implicitly.</P>
</DL>
</P>
<H2><A NAME="ss7.2">7.2</A> <A HREF="#toc7.2">Extended memory drivers</A>
</H2>
<P>
<DL>
<DT><B><CODE>a2.auxmem.emd (a2_auxmem_emd)</CODE></B><DD>
<P>Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended
80-Column Text Card.</P>
<P>Note that this driver doesn't check for the actual existence of the memory
and that it doesn't check for ProDOS 8 RAM disk content!</P>
</DL>
</P>
<H2><A NAME="ss7.3">7.3</A> <A HREF="#toc7.3">Joystick drivers</A>
</H2>
<P>
<DL>
<DT><B><CODE>a2.stdjoy.joy (a2_stdjoy_joy)</CODE></B><DD>
<P>Supports up to two standard analog joysticks connected to the game port of
the Apple ][.</P>
</DL>
</P>
<H2><A NAME="ss7.4">7.4</A> <A HREF="#toc7.4">Mouse drivers</A>
</H2>
<P>
<DL>
<DT><B><CODE>a2.stdmou.mou (a2_stdmou_mou)</CODE></B><DD>
<P>Driver for the AppleMouse II Card. Searches all Apple II slots
for an AppleMouse II Card compatible firmware. The default bounding
box is [0..279,0..191].</P>
<P>Programs using this driver will have to be linked with <CODE>-S $4000</CODE>
to reserve the first hires page if they are intended to run on an
Apple ][ (in contrast to an Apple //e) because the
AppleMouse II Card firmware writes to the hires page when initializing
on that machine.</P>
<P>Note that the Apple ][ default mouse callbacks support text
mode only.</P>
</DL>
</P>
<H2><A NAME="ss7.5">7.5</A> <A HREF="#toc7.5">RS232 device drivers</A>
</H2>
<P>
<DL>
<DT><B><CODE>a2.ssc.ser (a2_ssc_ser)</CODE></B><DD>
<P>Driver for the Apple II Super Serial Card.
The SSC is an extension card for the II, II+, IIe; the Apple //c and //c+ have
the same hardware and firmware integrated.
It supports up to 9600 baud, supports no flow control and hardware flow control
(RTS/CTS) and does interrupt driven receives. Speeds faster than 9600 baud
aren't reachable because the ROM and ProDOS IRQ handlers are too slow.
Software flow control (XON/XOFF) is not supported.</P>
<P>Note that because of the peculiarities of the 6551 chip transmits are not
interrupt driven, and the transceiver blocks if the receiver asserts
flow control because of a full buffer.</P>
<P>Note that using the driver at SER_BAUD_115200 will disable IRQs. It will be up
to the users to use the serial port, either by re-enabling IRQs themselves,
or by directly poll-reading the ACIA DATA register without the help of ser_get().</P>
<P>The driver defaults to slot 2. Call <CODE>ser_apple2_slot()</CODE> prior to
<CODE>ser_open()</CODE> in order to select a different slot. <CODE>ser_apple2_slot()</CODE>
succeeds for all Apple II slots, but <CODE>ser_open()</CODE> fails with
<CODE>SER_ERR_NO_DEVICE</CODE> if there's no SSC firmware found in the selected slot.</P>
<P>In the Apple //c and //c+, slot 1 is the printer port, and slot 2 is the modem
port.</P>
<P>Never call <CODE>ser_apple2_slot()</CODE> after <CODE>ser_open()</CODE>.</P>
<DT><B><CODE>a2.gs.ser (a2_gs_ser)</CODE></B><DD>
<P>Driver for the Apple IIgs serial ports (printer and modem).
It supports up to 9600 baud, supports no flow control and hardware flow control
(RTS/CTS) and does interrupt driven receives. Speeds faster than 9600 baud
aren't reachable because the ROM and ProDOS IRQ handlers are too slow.
Software flow control (XON/XOFF) is not supported.
Note that transmits are not interrupt driven, and the transceiver blocks if
the receiver asserts flow control because of a full buffer.</P>
<P>The driver defaults to opening the modem port. Calling <CODE>ser_apple2_slot()</CODE>
prior to <CODE>ser_open()</CODE> allows to select the printer port (1) or the modem
port (0).</P>
<P>Never call <CODE>ser_apple2_slot()</CODE> after <CODE>ser_open()</CODE>.</P>
</DL>
</P>
<H2><A NAME="s8">8.</A> <A HREF="#toc8">Limitations</A></H2>
<H2><A NAME="ss8.1">8.1</A> <A HREF="#toc8.1">DOS 3.3</A>
</H2>
<P>Although the standard binaries generated by the linker for the Apple ][
generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with
BASIC.SYSTEM) there are some limitations for DOS 3.3:</P>
<P>
<DL>
<DT><B>Disk file I/O</B><DD>
<P>There's no disk file I/O support. Any attempt to use it yields an error with
<CODE>errno</CODE> set to <CODE>ENOSYS</CODE>. This implicitly means that loadable drivers
are in general not functional as they depend on disk file I/O. Therefore the statically
linked drivers have to be used instead.</P>
<DT><B>Interrupts</B><DD>
<P>There's no <CODE>interruptor</CODE> support. Any attempt to use it yields the message
'FAILED TO ALLOC INTERRUPT' on program startup. This implicitly means that
mouse and RS232 device drivers are not functional as they depend on interrupts.</P>
</DL>
</P>
<H2><A NAME="ss8.2">8.2</A> <A HREF="#toc8.2">Direct console I/O</A>
</H2>
<P>The Apple ][ has no color text mode. Therefore the functions
<CODE>textcolor()</CODE>, <CODE>bgcolor()</CODE> and <CODE>bordercolor()</CODE> have no effect.</P>
<H2><A NAME="ss8.3">8.3</A> <A HREF="#toc8.3">Random number generator</A>
</H2>
<P>The random number seed is generated from the time the program waits for user input.
Therefore it is necessary to wait for at least one user keypress either via Standard
I/O or via Direct console I/O before initializing the pseudo random number generator.</P>
<H2><A NAME="ss8.4">8.4</A> <A HREF="#toc8.4">Realtime clock</A>
</H2>
<P>There are several types of realtime clocks. It's not desirable to have specific code
for all of them. As ProDOS 8 supports file timestamps, realtime clock owners usually
use ProDOS 8 drivers for their realtime clock. Those drivers read the realtime clock
and write the result to the date/time location in RAM ($BF90 to $BF93).
ProDOS 8 reads the date/time from that RAM location. If there's no realtime clock the
RAM location keeps containing zeros. ProDOS 8 uses those zeros as timestamps and the
files show up in a directory as <CODE><NO DATE></CODE>.</P>
<P>There's no common interface to set realtime clocks so if a realtme clock <B>IS</B>
present there's just nothing to do. However, if there's <B>NO</B> realtime clock present,
the user might very well be interested to "manually" set the RAM location in order to
have timestamps. But he surely doesn't want to manually set the RAM location over and
over again. Rather he wants to set it just once after booting ProDOS 8.</P>
<P>From that perspective it makes most sense to not set both the date and the time but
rather only set the date and have the time just stay zero. Then files show up in a
directory as <CODE>DD-MON-YY 0:00</CODE>.</P>
<P>So <CODE>clock_settime()</CODE> checks if a realtime clock is active. If it is then
<CODE>clock_settime()</CODE> fails with <CODE>ERANGE</CODE>. Otherwise <CODE>clock_settime()</CODE>
sets the date - and completely ignores the time provided as parameter.</P>
<P><CODE>clock_getres()</CODE> too checks if a realtime clock is active. If it is then
<CODE>clock_getres()</CODE> returns a time resolution of one minute. Otherwise
<CODE>clock_getres()</CODE> presumes that the only one who sets the RAM location is
<CODE>clock_settime()</CODE> and therefore returns a time resolution of one day.</P>
<H2><A NAME="s9">9.</A> <A HREF="#toc9">Other hints</A></H2>
<H2><A NAME="ss9.1">9.1</A> <A HREF="#toc9.1">Passing arguments to the program</A>
</H2>
<P>Command line arguments can be passed to <CODE>main()</CODE> after BLOAD. Since this is not
supported by BASIC, the following syntax was chosen:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>
<OL>
<LI>Arguments are separated by spaces.</LI>
<LI>Arguments may be quoted.</LI>
<LI>Leading and trailing spaces around an argument are ignored. Spaces within
a quoted argument are allowed.</LI>
<LI>The first argument passed to <CODE>main</CODE> is the program name.</LI>
<LI>A maximum number of 10 arguments (including the program name) are
supported.</LI>
</OL>
</P>
<H2><A NAME="ss9.2">9.2</A> <A HREF="#toc9.2">Interrupts</A>
</H2>
<P>The runtime for the Apple ][ uses routines marked as
<CODE>.INTERRUPTOR</CODE> for ProDOS 8 interrupt handlers. Such routines must be
written as simple machine language subroutines and will be called
automatically by the interrupt handler code when they are linked into a
program. See the discussion of the <CODE>.CONDES</CODE> feature in the
<A HREF="ca65.html">assembler manual</A>.</P>
<H2><A NAME="ss9.3">9.3</A> <A HREF="#toc9.3">ProDOS date/time manipulation</A>
</H2>
<P>
<DL>
<P>The readdir and stat function return ProDOS timestamps in their file
creation/modification time attributes. You can convert them to more portable
time representations using either:</P>
<DT><B>struct tm</B><DD>
<P><CODE>struct tm* __fastcall__ gmtime_dt (const struct datetime* dt);</CODE></P>
<P>Converts a <CODE>struct datetime</CODE> into a <CODE>struct tm</CODE>. Returns NULL in case
of error and sets errno.</P>
<DT><B>time_t</B><DD>
<P><CODE>time_t __fastcall__ mktime_dt (const struct datetime* dt);</CODE></P>
<P>Parses a <CODE>struct datetime</CODE> and returns a UNIX timestamp. Returns 0 on error and
sets errno.</P>
</DL>
</P>
<H2><A NAME="ss9.4">9.4</A> <A HREF="#toc9.4">DIO</A>
</H2>
<P>
<DL>
<DT><B>Drive ID</B><DD>
<P>The function
<A HREF="dio.html#s1">dio_open()</A> has the single
parameter <CODE>device</CODE> to identify the device to be opened. Therefore an
Apple II slot and drive pair is mapped to that <CODE>device</CODE> according
to the formula</P>
<P>
<BLOCKQUOTE><CODE>
device = slot + (drive - 1) * 8
</CODE></BLOCKQUOTE>
</P>
<P>so that for example slot 6 drive 2 is mapped to <CODE>device</CODE> 14.</P>
<DT><B>Sector count</B><DD>
<P>The function
<A HREF="dio.html#s3">dio_query_sectcount()</A> returns
the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8
disk it simply always returns 280 (which is only correct for a 140 KB disk).
This condition is indicated by the <CODE>_oserror</CODE> value 82.</P>
</DL>
</P>
<H2><A NAME="ss9.5">9.5</A> <A HREF="#toc9.5">Specifying file types for fopen</A>
</H2>
<P>
<DL>
<DT><B>Explanation of File Types</B><DD>
<P>ProDOS 8 associates a file type and an auxiliary type with each file.
These type specifications are separate from the file's name, unlike
Windows which uses the file name's suffix (a.k.a.
extension) to specify the file type. For example, <CODE>.exe</CODE>,
<CODE>.doc</CODE>, or <CODE>.bat</CODE>.
The ProDOS 8 Machine-Language Interface (MLI) function for creating a
file require these types to be specified.</P>
<P>In contrast, the ISO C function <CODE>fopen()</CODE> and the POSIX function
<CODE>open()</CODE> have no parameter to specify either a file type or an
auxiliary type. Therefore, some additional mechanism for specifying
the file types is needed.</P>
<DT><B>Specifying the File Type and Auxiliary Type</B><DD>
<P>There are two global variables provided that allow the file type
and auxiliary type to be specified before a call to <CODE>fopen()</CODE>
or <CODE>open()</CODE>. They are defined in <CODE>apple2_filetype.h</CODE>:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
extern unsigned char _filetype; /* Default: PRODOS_T_BIN */
extern unsigned int _auxtype; /* Default: 0 */
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The header file <CODE>apple2_filetype.h</CODE> also defines many values
that can be used to set these variables. It is included in
<CODE>apple2.h</CODE>.</P>
<P>The global variable <CODE>_datetime</CODE> allows the file creation date/time
to be set before a call to <CODE>fopen()</CODE>
or <CODE>open()</CODE> that creates the file. It is defined in <CODE>apple2.h</CODE>:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
extern struct datetime _datetime;
</PRE>
</CODE></BLOCKQUOTE>
</P>
<DT><B>Example</B><DD>
<P>A text file cannot be created with just the
standard C functions because they default to the binary type
<CODE>PRODOS_T_BIN</CODE>. The <CODE>_filetype</CODE> variable must be set to
<CODE>PRODOS_T_TXT</CODE> to create a text file.</P>
<P>For a text file,
<CODE>_auxtype</CODE> specifies the record length. A zero record
length text file is referred to as a sequential text file.
This is equivalent to text files on
other operating systems, except that the line terminator is a
carriage return instead of a line-feed (Linux/BSD/MacOS) or
carriage return, line-feed pair (Windows).</P>
<P>The 'sequential' text file terminology is in contrast to a
'random-access' text file which would
have a fixed-length, non-zero record length, so that the
file position of any individual record can be calculated.</P>
<P>For this example, the
<CODE>_auxtype</CODE> does not need to be set because it defaults to
the desired value, which is zero. To be more explicit,
<CODE>_auxtype</CODE> can also be set to <CODE>PRODOS_AUX_T_TXT_SEQ</CODE>
which is defined as zero.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <apple2.h>
void main(void)
{
FILE *out;
char *name = "MY.FAVS";
/*-----------------------------*/
_filetype = PRODOS_T_TXT;
_auxtype = PRODOS_AUX_T_TXT_SEQ;
/*-----------------------------*/
if ((out = fopen(name, "w")) != NULL) {
fputs("Jorah Mormont\r", out);
fputs("Brienne of Tarth\r", out);
fputs("Daenerys Targaryen\r", out);
fputs("Sandor Clegane\r", out);
if (fclose(out) == EOF) {
fprintf(stderr, "fclose failed for %s: %s", name, strerror(errno));
}
}
else {
fprintf(stderr, "fopen failed for %s: %s", name, strerror(errno));
}
}
</PRE>
</CODE></BLOCKQUOTE>
</P>
</DL>
</P>
<H2><A NAME="s10">10.</A> <A HREF="#toc10">License</A></H2>
<P>This software is provided 'as-is', without any expressed or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.</P>
<P>Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:</P>
<P>
<OL>
<LI> The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.</LI>
<LI> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.</LI>
<LI> This notice may not be removed or altered from any source
distribution.</LI>
</OL>
</P>
</BODY>
</HTML>