/
a68k.html
1987 lines (1967 loc) · 113 KB
/
a68k.html
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 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>The A68k Assembler</TITLE>
<STYLE TYPE="TEXT/CSS">
<!--
.IE3-DUMMY { CONT-SIZE: 100%; }
BODY { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; }
P { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H1 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H2 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H3 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H4 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H5 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
H6 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
UL { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #FFFFFF; }
.NOBORDER { BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
.NOBORDER TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
.CODE { FONT-FAMILY: Courier New; }
-->
</STYLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#E0E0E0">
<FONT SIZE="5"><B>The A68k Assembler</B></FONT>
<HR>
<P>In addition to the <A HREF="gnuasm.html">GNU Assembler</A>, the GCC4TI package also includes
the A68k assembler by Charlie Gibbs (slightly modified Amiga version). Although GCC4TI also includes
the GNU assembler used by GCC, A68k is included here because many old assembly programs for the
TI-89 and TI-92+ are created with this assembler (so including it in the package allows compiling
existing ASM programs as well), and because, while it is inferior to the GNU assembler in some
aspects, it also has advantages, mainly easier syntax, but also support for binary include files for
example.
The A68k assembler was developed long before the TIGCC and GCC4TI projects were even started, so it
is somewhat inconsistent with the rest of the project, though some effort has been made to integrate
it into TIGCC/GCC4TI. For example, you can now call a function from a static library using a simple
<CODE>bsr</CODE> or <CODE>jsr</CODE> instruction.
<BR><BR>
This assembler comes with its own set of header files. All of them are included mainly for
compatibility reasons (note that some of them are deprecated, obsolete, inconsistent
or even obscure), so they will not be described here. Information about them may be
found in various ASM tutorials for TI-89 and TI-92+ (also deprecated, but note that
nearly 95% of all ASM programs for TI-89 and TI-92+ are written using a now deprecated
way, because a lot of information about the system was not available at the time
when these programs were created). We recommend using only <CODE>OS.h</CODE>, which contains a
list of equates for <CODE>ROM_CALL</CODE>s (but the <CODE>ROM_CALL</CODE> macros are not very
optimized and should thus be avoided), and functions from TIGCCLIB, which need no header file at all
(for example, <CODE>bsr GrayOn</CODE> is enough to call the <A HREF="gray.html#GrayOn">GrayOn</A> function). What will be presented here is the original A68k documentation, written by Charlie Gibbs himself. We have however annotated it in some places
to reflect the changes made in recent versions, and we have added 2 chapters: the list of
supported assembler directives, which was missing, and the history, which was kept in a separate file.</P>
<UL>
<LI><B><A HREF="#intro">Introduction - About A68k</A></B>
<LI><B><A HREF="#restrictions">Restrictions</A></B>
<LI><B><A HREF="#exts">Extensions</A></B>
<LI><B><A HREF="#directives">A68k Assembler Directives</A></B>
<LI><B><A HREF="#smallcode">The Small Code/Data model</A></B>
<LI><B><A HREF="#files">Files</A></B>
<LI><B><A HREF="#filenames">File Names</A></B>
<LI><B><A HREF="#usage">A68k Command-Line Parameters (How to use A68k)</A></B>
<LI><B><A HREF="#tech">Technical Information</A></B>
<LI><B><A HREF="#contact">A68k Contact Information and Bug Reports</A></B>
<LI><B><A HREF="#history">History of A68k</A></B>
</UL>
<HR>
<H2><A NAME="intro"><U>Introduction - About A68k</U></A></H2>
<P><CENTER><B>
A68k - a freely distributable assembler for the Amiga<BR>
by Charlie Gibbs<BR>
with special thanks to<BR>
Brian R. Anderson and Jeff Lydiatt<BR>
The current versions are now part of the GCC4TI project.
As such, they will be aimed much more at development for the TI-89, TI-89T,
TI-92+ and V200 calculators than at the Amiga.
Modifications of this document are marked with <B>(TIGCC/GCC4TI)</B><BR>
(Version 2.71.F3z - July 29, 2009)
</B></CENTER>
<BR><BR>
<B>Note:</B> This program is Freely Distributable, as opposed to Public
Domain. Permission is given to freely distribute this program provided no
fee is charged, and this documentation file is included with the program.
<BR><BR>
This assembler is based on Brian R. Anderson's 68000 cross-
assembler published in Dr. Dobb's Journal, April through June 1986.
I have converted it to produce AmigaDOS-format object modules, and
have made many enhancements, such as macros and INCLUDE files.
<BR><BR>
My first step was to convert the original Modula-2 code into C.
I did this for two reasons. First, I had access to a C compiler, but
not a Modula-2 compiler. Second, I like C better anyway.
<BR><BR>
The executable code generator code (GetObjectCode and MergeModes)
is essentially the same as in the original article, aside from its
translation into C. I have almost completely rewritten the remainder
of the code, however, in order to remove restrictions, add enhancements,
and adapt it to the AmigaDOS environment. Since the only reference book
available to me was the AmigaDOS Developer's Manual (Bantam, February
1986), this document describes the assembler in terms of that book.</P>
<HR>
<H2><A NAME="restrictions"><U>Restrictions</U></A></H2>
<P>Let's get these out of the way first:</P>
<UL>
<LI><P>The verification file <B>'-v'</B> option is not supported. Diagnostic
messages always appear on the console. They also appear in the
listing file, however (see extensions below). You can produce
an error file by redirecting console output to a file - the
line number counter and final summary are displayed on stderr
so you can still see what's happening.
<TABLE><TR><TD><B>(TIGCC/GCC4TI)</B></TD><TD>
<B>WARNING:</B> The new -v switch introduced in v.2.71.F3c is <B>NOT</B> the same as this one!</TD></TR></TABLE></P></LI>
<LI><P>The file names in the <CODE>INCLUDE</CODE> directory list <B>'-i'</B> must be
separated by commas. The list may not be enclosed in quotes.</P></LI>
<LI><P>Labels assigned by <CODE>EQUR</CODE> and <CODE>REG</CODE> directives are case-sensitive.</P></LI>
<LI><P>Strange things will happen if your source code (including
<CODE>INCLUDE</CODE> files and macro expansions) exceeds 32,766 lines.
Tough darts. Break up your source file. Can you actually
read that monster?
<TABLE><TR><TD><B>(TIGCC/GCC4TI)</B></TD><TD>
The maximum has been increased from 32,766 to 2,147,483,646 for
32-bit operating systems starting from version 2.71.F3s.</TD></TR></TABLE></P></LI>
<LI><P>Directives <CODE>OFFSET</CODE>, <CODE>NOPAGE</CODE>, <CODE>LLEN</CODE>, <CODE>PLEN</CODE>,
<CODE>NOOBJ</CODE>, <CODE>FAIL</CODE>, <CODE>FORMAT</CODE>, <CODE>NOFORMAT</CODE> and
<CODE>MASK2</CODE> are not supported, and will be flagged
as invalid op-codes.
I feel that <CODE>NOPAGE</CODE>, <CODE>LLEN</CODE>, and <CODE>PLEN</CODE> should not be
defined within a source module. It doesn't make sense to me to have to change
your program just because you want to print your listings on
different paper. The command-line switch <B>'-p'</B> (see below) can
be used as a replacement for <CODE>PLEN</CODE>; setting it to a high value
(like 32767) is a good substitute for <CODE>NOPAGE</CODE>. The effect of
<CODE>LLEN</CODE> can be obtained by running the listing file through an
appropriate filter.</P></LI>
</UL>
<HR>
<H2><A NAME="exts"><U>Extensions</U></A></H2>
<P>Now for the good stuff:</P>
<UL>
<LI><P>Labels can be any length that will fit onto one source line
(currently 127 characters maximum). Since labels are stored
on the heap, the number of labels that can be processed is
limited only by available memory.
<TABLE><TR><TD><B>(TIGCC/GCC4TI)</B></TD><TD>
The maximum has been increased from 127 to 256 (for
Win32, starting from 2.71.F3a, for GNU/Linux,
starting from 2.71.F3c, for all other platforms,
starting from 2.71.F3s).</TD></TR></TABLE></P></LI>
<LI><P>The first character of a label can be <CODE>'@'</CODE> if the next character
is not numeric (this avoids confusion with octal constants).
This provides compatibility with the Lattice C compiler.</P></LI>
<LI><P>Since section data and user macro definitions are stored in
the symbol table (see above), they too are limited only by
available memory (actually, there is a hard-coded limit of
32,767 sections, but I doubt anyone will run into that one).</P></LI>
<LI><P>The only values a label cannot take are the register names -
A68k can distinguish between the same name used as a label,
instruction name or directive, macro name, or section name.</P></LI>
<LI><P>Section and user macro names appear in the symbol table dump,
and will also be cross-referenced. Their names can be the same
as any label (see above); they will be listed separately.</P></LI>
<LI><P><CODE>INCLUDE</CODE>s and macro calls can be nested indefinitely, limited
only by available memory. The message "Secondary heap
overflow - assembly terminated" will be displayed if memory
is exhausted. You can increase the size of this heap using
the <B>'-w'</B> switch (see below). Recursive macros are supported;
recursive <CODE>INCLUDE</CODE>s will, of course, result in a loop that
will be broken only when the heap overflows.</P></LI>
<LI><P>The <CODE>EVEN</CODE> directive forces alignment on a word (2-byte)
boundary. It does the same thing as <CODE>CNOP 0,2</CODE>
(this one is left over from the original code).</P></LI>
<LI><P>Backward references to labels within the current <CODE>CODE</CODE> section
will be converted to PC-relative addressing with displacement
if this mode is legal for the instruction. This feature is
disabled by the <B>'-n'</B> switch.</P></LI>
<LI><P>If a <CODE>MOVEM</CODE> instruction only specifies one register, it is
converted to the corresponding <CODE>MOVE</CODE> instruction. Instructions
such as <CODE>MOVEM D0-D0,<I>label</I></CODE> will not be converted, however.
This feature is disabled by the <B>'-n'</B> switch.
<TABLE><TR><TD><B>(TIGCC/GCC4TI)</B></TD><TD>
Starting from v.2.71.F3c, this feature can now also be
disabled by using the <B>'-rm'</B> switch.</TD></TR></TABLE></P></LI>
<LI><P><CODE>ADD</CODE>, <CODE>SUB</CODE>, and <CODE>MOVE</CODE> instructions will be converted to
<CODE>ADDQ</CODE>, <CODE>SUBQ</CODE>, and <CODE>MOVEQ</CODE> respectively if possible.
Instructions coded explicitly (e.g. <CODE>ADDA</CODE> or <CODE>ADDI</CODE>) will not be converted. This
feature is disabled by the <B>'-n'</B> switch.</P></LI>
<LI><P><CODE>ADD</CODE>, <CODE>CMP</CODE>, <CODE>SUB</CODE>, and <CODE>MOVE</CODE> to an address register are
converted to <CODE>ADDA</CODE>, <CODE>CMPA</CODE>, <CODE>SUBA</CODE>, and <CODE>MOVEA</CODE>
respectively, unless (for <CODE>ADD</CODE>, <CODE>SUB</CODE>, or <CODE>MOVE</CODE>)
they have already been converted to quick form.</P></LI>
<LI><P><CODE>ADD</CODE>, <CODE>AND</CODE>, <CODE>CMP</CODE>, <CODE>EOR</CODE>, <CODE>OR</CODE>, and
<CODE>SUB</CODE> of an immediate value are
converted to <CODE>ADDI</CODE>, <CODE>ANDI</CODE>, <CODE>CMPI</CODE>, <CODE>EORI</CODE>,
<CODE>ORI</CODE>, and <CODE>SUBI</CODE> respectively (unless the address register or quick
conversion above has already been done).</P></LI>
<LI><P>
<TABLE><TR><TD><B>(TIGCC/GCC4TI)</B></TD><TD>
Starting from v.2.71.F3c, <CODE>ADDA</CODE> and <CODE>SUBA</CODE> (or <CODE>ADD</CODE> and <CODE>SUB</CODE>
to an address register) will now be converted to <CODE>LEA</CODE> if
possible. This feature can be disabled using the <B>'-n'</B>
switch (disables all optimizations) or the <B>'-ra'</B> switch
(disables just this single optimization).</TD></TR></TABLE></P></LI>
<LI><P>
<TABLE><TR><TD><B>(TIGCC/GCC4TI)</B></TD><TD>
Starting from v.2.71.F3c, <CODE>LEA n(an),an</CODE> will now be converted to <CODE>ADDQ</CODE> or <CODE>SUBQ</CODE> if
possible. This feature can be disabled using the <B>'-n'</B>
switch (disables all optimizations) or the <B>'-rl'</B> switch
(disables just this single optimization).</TD></TR></TABLE></P></LI>
<LI><P>If both operands of a <CODE>CMP</CODE> instruction are postincrement mode,
the instruction is converted to <CODE>CMPM</CODE>.</P></LI>
<LI><P>Operands of the form <CODE>'0(An)'</CODE> will be treated as <CODE>'(An)'</CODE> except for
the <CODE>MOVEP</CODE> instruction, which always requires a displacement.
This feature is disabled by the <B>'-n'</B> switch.</P></LI>
<LI><P>The <CODE>SECTION</CODE> directive allows a third parameter. This can be
specified as either <CODE>CHIP</CODE> or <CODE>FAST</CODE> (upper or lower case). If
this parameter is present, the hunk will be written with the
<CODE>MEMF_CHIP</CODE> or <CODE>MEMF_FAST</CODE> bit set. This allows you to produce
"pre-ATOMized" object modules.</P></LI>
<LI><P>The synonyms <CODE>DATA</CODE> and <CODE>BSS</CODE> are accepted for <CODE>SECTION</CODE> directives
starting data or <CODE>BSS</CODE> hunks. The <CODE>CHIP</CODE> and <CODE>FAST</CODE> options (see
above) can also be used, e.g. <CODE>BSS <I>name</I>,CHIP</CODE>.</P></LI>
<LI><P>The following synonyms have been implemented for compatibility
with the Aztec assembler:
</P>
<UL>
<LI><P><CODE>CSEG</CODE> is treated the same as <CODE>CODE</CODE> or <CODE>SECTION <I>name</I>,CODE</CODE>.</P></LI>
<LI><P><CODE>DSEG</CODE> is treated the same as <CODE>DATA</CODE> or <CODE>SECTION <I>name</I>,DATA</CODE>.</P></LI>
<LI><P><CODE>PUBLIC</CODE> is treated as either <CODE>XDEF</CODE> or <CODE>XREF</CODE>, depending on
whether or not the symbol in question has been defined in the current source module.
A single <CODE>PUBLIC</CODE> directive can name a mixture of internally- and externally-defined symbols.</P></LI>
</UL>
</LI>
<LI><P>The ability to produce Motorola S-records is retained from the
original code. The <B>'-s'</B> switch causes the assembler to produce
S-format instead of AmigaDOS format. Relocatable code cannot
be produced in this format.</P></LI>
<LI><P>Error messages consist of three parts.
The position of the offending line is given as a line
number within the current module. If the line is within a
macro expansion or <CODE>INCLUDE</CODE> file, the position of the macro
call or <CODE>INCLUDE</CODE> statement in the outer module is given as
well. This process is repeated until the outermost source
module is reached.
Next, the offending source line itself is listed.
Finally, the errors for that line are displayed. A flag
<CODE>'^'</CODE> is placed under the column where the error was detected.</P></LI>
<LI><P>Named local labels are supported. These work the same as the
local labels supported by the Metacomco assembler (<CODE><I>nnn</I>$</CODE>) but
are formed in the same manner as normal labels, except that
they must be preceded by a backslash (<CODE>'\'</CODE>).</P></LI>
<LI><P>The following synonyms have been implemented for compatibility
with the Assempro assembler:
</P>
<UL>
<LI><P><CODE>ENDIF</CODE> is treated the same as <CODE>ENDC</CODE>.</P></LI>
<LI><P><CODE>'='</CODE> is treated the same as <CODE>EQU</CODE>.</P></LI>
<LI><P><CODE>'|'</CODE> is treated the same as <CODE>'!'</CODE> (logical OR).</P></LI>
</UL>
</LI>
<LI><P>Quotation marks (<CODE>"</CODE>) can be used as string delimiters
as well as apostrophes (<CODE>'</CODE>). Any given string must begin
and end with the same delimiter. This allows such statements
as the following:</P>
<PRE> MOVEQ "'",D0
DC.B "This is Charlie's assembler."
</PRE>
<P>Note that you can still define an apostrophe within a string
delimited by apostrophes if you double it, e.g.</P>
<PRE> MOVEQ '''',D0
DC.B 'This is Charlie''s assembler.'
</PRE>
</LI>
<LI><P>If any errors are found in the assembly, the object code file
will be scratched, unless you include the <B>'-k'</B> (keep) flag on
the command line.</P></LI>
<LI><P>The symbols <CODE>.A68K</CODE>, <CODE>.a68k</CODE>, <CODE>.a68K</CODE>, and <CODE>.A68k</CODE> are automatically
defined as <CODE>SET</CODE> symbols having absolute values of 1.
This enables a source program to determine whether it is
being assembled by this assembler, and is effectively
insensitive as to whether or not it is checked in upper case.</P></LI>
<LI><P>A zeroth positional macro parameter <CODE>'\0'</CODE> is supported. It
is replaced by the length of the macro call (<CODE>B</CODE>, <CODE>W</CODE>, or <CODE>L</CODE>,
defaulting to <CODE>W</CODE>). For instance, given the macro:</P>
<PRE>moov MACRO
move.\0 \1,\2
ENDM
</PRE>
<P>the macro call</P>
<PRE> moov.l d0,d1
</PRE>
<P>would be expanded as</P>
<PRE> move.l d0,d1
</PRE>
</LI>
<LI><P>If an <CODE>INCLUDE</CODE> file doesn't generate any code and no listing
file is required (including suppression of the listing using
<CODE>NOLIST</CODE>), it won't be read again in pass 2. The statement
numbers will be bumped to keep in proper alignment. This
can really speed up assemblies that <CODE>INCLUDE</CODE> lots of <CODE>EQU</CODE>ates.</P></LI>
<LI><P>The <CODE>ORG</CODE> directive is supported. It works like <CODE>RORG</CODE>, except
that it takes the actual address to be jumped to, rather
than an offset from the start of the current section.
The given address must be in the current section.
As far as A68k is concerned, the only real difference
between <CODE>ORG</CODE> and <CODE>RORG</CODE> is that the <CODE>ORG</CODE> value must be
relocatable, while the RORG value must be absolute.</P></LI>
<LI><P>Branch (<CODE>B<I>cc</I></CODE>, including <CODE>BRA</CODE> and <CODE>BSR</CODE>) instructions will be
converted to short form if possible. Shortening a branch
may bring other branches within range of shortening - this
can set up a ripple effect, and A68k may not catch all
branches that could theoretically be optimized. Any branches
which A68k misses (there shouldn't be too many under normal
circumstances) can be displayed by specifying the <B>'-f'</B> switch
(see below). Branch optimization is disabled by the <B>'-n'</B> switch.</P></LI>
<LI><P>The <CODE>INCBIN</CODE> directive allows the contents of any file to be
included in A68k's object code output. Its format is the same
as the <CODE>INCLUDE</CODE> directive, but the file can contain any data
at all, printable or not. Rather than being processed as
source code by the assembler, the entire contents of the file
is copied directly to the current position in the object code
output file with no reformatting whatsoever. The effect is
the same as if <CODE>DC</CODE> statements whose constants represent the
file's contents were inserted in place of the <CODE>INCBIN</CODE> directive.</P></LI>
<LI><P>The opcode <CODE>TTL</CODE> is accepted as a synonym for <CODE>TITLE</CODE>.</P></LI>
<LI><P>A command-line option <B>'-g'</B> causes A68k to treat any undefined
symbol as <CODE>XREF</CODE>.</P></LI>
<LI><P>The register list in a <CODE>MOVEM</CODE> instruction can be an
immediate operand which specifies the actual mask bits.</P></LI>
<LI><P>
<TABLE><TR><TD><B>(TIGCC/GCC4TI)</B></TD><TD>
The following synonyms are also supported:<BR>
Starting from 2.71.F3a:</P>
<UL><LI><P><CODE>BLO</CODE> = <CODE>BCS</CODE></P></LI>
<LI><P><CODE>BHS</CODE> = <CODE>BCC</CODE></P></LI>
<LI><P><CODE>DBLO</CODE> = <CODE>DBCS</CODE></P></LI>
<LI><P><CODE>DBHS</CODE> = <CODE>DBCC</CODE></P></LI>
<LI><P><CODE>ROLX</CODE> = <CODE>ROXL</CODE></P></LI>
<LI><P><CODE>RORX</CODE> = <CODE>ROXR</CODE></P></LI></UL>
<P>Starting from 2.71.F3c:</P>
<UL><LI><P><CODE>SLO</CODE> = <CODE>SCS</CODE></P></LI>
<LI><P><CODE>SHS</CODE> = <CODE>SCC</CODE></P></LI></UL>
<P></TD></TR></TABLE></P></LI>
</UL>
<HR>
<H2><A NAME="directives"><U>A68k Assembler Directives</U></A></H2>
<P><B>Note:</B> This section has been written entirely by the TIGCC Team. Part of the information comes from <CODE>direct.txt</CODE> by Mathieu Lacage, but the whole text is completely rewritten and contains more details. Also, some of the directives listed here are not documented in <CODE>direct.txt</CODE>.
<BR><BR>
The <CODE>A68k</CODE> assembler supports the following assembler directives:
<BR><BR>
<TABLE>
<TR><TD VALIGN="TOP">arithmetic operators</TD><TD>
Arithmetic operators can be used exactly like their C counterparts, except that spaces are not allowed in an expression. But <CODE>((1+2)>>3)/4</CODE> is a perfectly legitimate <CODE>A68k</CODE> expression. Of course, you can not use anything other than <CODE>+</CODE> or <CODE>-</CODE> on labels
and you cannot use arithmetic on registers at all - you will have to use the corresponding
assembly instructions.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>INCLUDE "<I>filename.h</I>"</CODE></TD><TD>
Includes the file given as a parameter at the current source position. The file is read in as assembly source code, as if it was part of the current assembly source.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>INCBIN "<I>filename.bin</I>"</CODE></TD><TD>
Includes the binary content of the file given as a parameter as-is at the current location in the object file output. The file will <B>NOT</B> be assembled, but included as binary data.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>EVEN</CODE></TD><TD>
Forces alignment on an even address. The next instruction will be guaranteed to be placed at an even address. This is especially important for <CODE>dc.w</CODE> or <CODE>dc.l</CODE> directives, since accessing a word or longword at an odd address causes an address error.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>CNOP <I>displacement</I>,<I>alignment</I></CODE></TD><TD>
Forces alignment on an address which is the sum of <I>displacement</I>, which has to be even, and a multiple of <I>alignment</I>, which has to be a power of 2.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>XDEF <I>label</I></CODE></TD><TD>
Exports the label given as an argument to other object files or to the linker. This also allows linker directives like <CODE>xdef _nostub</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>XREF <I>label</I></CODE></TD><TD>
Imports the label given as an argument. This allows to access variables
from other object files even if the <B>'-g'</B> switch is not specified. Since GCC4TI specifies <B>'-g'</B> by default, there
is no real need for this directive.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>PUBLIC <I>label</I></CODE></TD><TD>
Imports or exports the label given as an argument, depending on whether it is part of the current source file or not. We recommend using <CODE>XDEF</CODE> or <CODE>XREF</CODE> instead when possible, since they clearly specify what is meant. But <CODE>PUBLIC</CODE> is useful when used in a common header file for multiple source files.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>SECTION "<I>sectname</I>"</CODE></TD><TD>
Sets the section the following code will be written to. This is especially useful to make <CODE>A68k</CODE> use the same section as <CODE>GCC</CODE>: <CODE>.data</CODE>, in order to make sure the linking order of <CODE>GCC</CODE> files first is respected. (<B>Note:</B> You can deliberately <B>NOT</B> specify <CODE>SECTION ".data"</CODE> if you want the <CODE>A68k</CODE> file to be the main file.)
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>BSS</CODE></TD><TD>
Specifies the section the following code will be written to as a "BSS section", a section which will not be initialized at runtime, so it can contain only storage place which does not need to be initialized. Also, BSS sections are <B>not</B> allowed in <CODE>_nostub</CODE> mode.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>CSEG</CODE></TD><TD>
Creates a section called "<CODE>CODE</CODE>" where the code will be written to. This directive is not really useful in GCC4TI, since both code and data are written to the <CODE>.data</CODE> section by <CODE>GCC</CODE> and <CODE>GNU as</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>DSEG</CODE></TD><TD>
Creates a section called "<CODE>DATA</CODE>" where the code will be written to. Do not use this directive in GCC4TI. Instead, specify <CODE>SECTION .data</CODE>, which is the section name used by <CODE>GCC</CODE> and <CODE>GNU as</CODE> for data sections.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>END</CODE></TD><TD>
Marks the end of the source file. This directive is now optional since v.2.71.F3c.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>DC.{B|W|L} <I>data1</I>,<I>data2</I>,<I>...</I></CODE></TD><TD>
(<B>D</B>efine <B>C</B>onstant(s)) Will insert all the arguments as immediate data into the object file. For example, <CODE>DC.L $12345678</CODE> will insert the bytes <CODE>0x12</CODE>, <CODE>0x34</CODE>, <CODE>0x56</CODE> and <CODE>0x78</CODE> into the resulting object file. <CODE>DC.B 'Hello, World!',0</CODE> will insert the null-terminated string <CODE>"Hello, World!"</CODE> into the resulting object file.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>DS.{B|W|L} <I>n</I></CODE></TD><TD>
(<B>D</B>efine <B>S</B>torage) Will insert <I>n</I> bytes, words or longwords (depending on the size specified) of zeros (<CODE>0</CODE>, <B>NOT</B> <CODE>'0'</CODE>) into the resulting object file.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>DCB.{B|W|L} <I>n</I>,<I>data</I></CODE></TD><TD>
(<B>D</B>efine <B>C</B>onstant <B>B</B>lock) Will act as <I>n</I> times the <CODE>DC.B <I>data</I></CODE> instruction. It will insert the immediated data specified by <I>data</I> <I>n</I> times into the resulting object file.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE><I>macroName</I> MACRO<BR> <I>instructions</I><BR> ENDM</CODE></TD><TD>
This declares a macro so that <CODE>macroName</CODE> can be used as if it was an instruction, with
the difference that unlike opcodes, macro names are <B>case-sensitive</B>. You can also pass
arguments to a macro. Those are referenced by a macro as <CODE>\<I>n</I></CODE>, where <I>n</I>
is the number of the argument, starting from 1. <CODE>\0</CODE> indicates the instruction size. <CODE>\@</CODE> indicates the number of the current macro, which is useful to create unique labels of the form <CODE>\@<I>label</I></CODE> or <CODE>\\@<I>localLbl</I></CODE>.
Therefore:</P>
<PRE>PUSH MACRO
MOVE.\0 \1,-(a7)
ENDM</PRE>
<P>(defined in "OS.h") allows you to use: <CODE>PUSH.L #1</CODE> when in fact you mean: <CODE>MOVE.L #1,-(a7)</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE><<I>expression</I>></CODE></TD><TD>
Makes sure <I>expression</I> will be treated as a single macro parameter, even if it contains separators like commas, semicolons or whitespace.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE><I>constant</I> EQU <I>value</I></CODE><BR><B>OR:</B> <CODE><I>constant</I> = <I>value</I></CODE></TD><TD>
Defines a symbolic constant. Wherever <I>constant</I> is encountered in the code, it will be
replaced by <I>value</I>. Note that value can also be an expression, not only a single number.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE><I>regAlias</I> EQUR <I>register</I></CODE></TD><TD>
Defines an alias for a register. For example, if you are using <CODE>a5</CODE> to hold the address
of the jump table in your whole program, you can write <CODE>jumpTbl EQUR a5</CODE>, and then
use <CODE>jumpTbl</CODE> wherever you would use <CODE>a5</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE><I>regListAlias</I> EQUR <I>regList</I></CODE></TD><TD>
Defines an alias for a list of registers, for use in the <CODE>MOVEM</CODE> instruction. The syntax of <I>regList</I> is the same as in the <CODE>MOVEM</CODE> instruction.
For example, if you are frequently using <CODE>MOVEM.L d0-d7/a0-a6,-(a7)</CODE> and <CODE>MOVEM.L (a7)+,d0-d7/a0-a6</CODE>, you might define: <CODE>all REG d0-d7/a0-a6</CODE>, and then
use <CODE>all</CODE> wherever you would use <CODE>d0-d7/a0-a6</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE><I>variable</I> SET <I>value</I></CODE></TD><TD>
Defines a symbolic variable. Wherever <I>variable</I> is encountered in the code, it will be
replaced by <I>value</I>. But contrary to an <CODE>EQU</CODE> constant, a <CODE>SET</CODE>
variable can be modified. It can therefore be used as a counter for example, as in: <CODE>counter SET counter+1</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>IFEQ <I>value</I><BR><I>instructions</I><BR>ENDC</CODE></TD><TD>
The <I>instructions</I> in the block will be parsed and assembled if and only if <I>value</I> equals 0. You can also write <CODE>ENDIF</CODE> as a synonym for <CODE>ENDC</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>IFNE <I>value</I><BR><I>instructions</I><BR>ENDC</CODE></TD><TD>
The <I>instructions</I> in the block will be parsed and assembled if and only if <I>value</I> does not equal 0. You can also write <CODE>ENDIF</CODE> as a synonym for <CODE>ENDC</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>IFGE <I>value</I><BR><I>instructions</I><BR>ENDC</CODE></TD><TD>
The <I>instructions</I> in the block will be parsed and assembled if and only if <I>value</I> is greater than or equal to 0. You can also write <CODE>ENDIF</CODE> as a synonym for <CODE>ENDC</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>IFGT <I>value</I><BR><I>instructions</I><BR>ENDC</CODE></TD><TD>
The <I>instructions</I> in the block will be parsed and assembled if and only if <I>value</I> is greater than 0. You can also write <CODE>ENDIF</CODE> as a synonym for <CODE>ENDC</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>IFLE <I>value</I><BR><I>instructions</I><BR>ENDC</CODE></TD><TD>
The <I>instructions</I> in the block will be parsed and assembled if and only if <I>value</I> is less than or equal to 0. You can also write <CODE>ENDIF</CODE> as a synonym for <CODE>ENDC</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>IFLT <I>value</I><BR><I>instructions</I><BR>ENDC</CODE></TD><TD>
The <I>instructions</I> in the block will be parsed and assembled if and only if <I>value</I> is less than 0. You can also write <CODE>ENDIF</CODE> as a synonym for <CODE>ENDC</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>IFC <I>string1</I>,<I>string2</I><BR><I>instructions</I><BR>ENDC</CODE></TD><TD>
The <I>instructions</I> in the block will be parsed and assembled if and only if <I>string1</I> and <I>string2</I> are identical (after expansion of <CODE>EQU</CODE> constants). You can also write <CODE>ENDIF</CODE> as a synonym for <CODE>ENDC</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>IFNC <I>string1</I>,<I>string2</I><BR><I>instructions</I><BR>ENDC</CODE></TD><TD>
The <I>instructions</I> in the block will be parsed and assembled if and only if <I>string1</I> and <I>string2</I> are different (after expansion of <CODE>EQU</CODE> constants). You can also write <CODE>ENDIF</CODE> as a synonym for <CODE>ENDC</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>IFD <I>value</I><BR><I>instructions</I><BR>ENDC</CODE></TD><TD>
The <I>instructions</I> in the block will be parsed and assembled if and only if <I>value</I> is a defined symbol. You can also write <CODE>ENDIF</CODE> as a synonym for <CODE>ENDC</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>IFND <I>value</I><BR><I>instructions</I><BR>ENDC</CODE></TD><TD>
The <I>instructions</I> in the block will be parsed and assembled if and only if <I>value</I> is not a defined symbol. You can also write <CODE>ENDIF</CODE> as a synonym for <CODE>ENDC</CODE>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>NEAR [<I>register</I>]</CODE></TD><TD>
Enables the <A HREF="#smallcode">small code and data model</A>.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>FAR</CODE></TD><TD>
Disables the <A HREF="#smallcode">small code and data model</A> after a <CODE>NEAR</CODE> directive.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>ORG <I>expression</I></CODE></TD><TD>
Places the code following the directive at the address specified by <I>expression</I>, which must be relocatable (that is, of the form <CODE><I>label</I>+<I>number</I></CODE>, where <I>label</I> is a backward reference, not a forward reference). If that address is located before the current position, the code previously generated there will be overwritten. If that adress is located after the current position, the space will be filled with zeros (<CODE>0</CODE>, <B>NOT</B> <CODE>'0'</CODE>).
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>RORG <I>offset</I></CODE></TD><TD>
Places the code following the directive at the offset <I>offset</I>, which must be a number, from the beginning of the current object file section. If that address is located before the current position, the code previously generated there will be overwritten. If that adress is located after the current position, the space will be filled with zeros (<CODE>0</CODE>, <B>NOT</B> <CODE>'0'</CODE>). However, if <CODE>RORG</CODE> is specified before the first executable instruction and in the default section (before any <CODE>SECTION</CODE>, <CODE>BSS</CODE>, <CODE>CSEG</CODE> or <CODE>DSEG</CODE> directive), no spacing will be generated, so it has the effect of adding the number <I>address</I> to all absolute references, thereby pre-relocating the code to that fixed address. But such an use of this directive is not useful in GCC4TI, as assembly programs on the TI-89/92+ can be at any place in memory, and the linker always generates a relocation table which allows AMS to take care of the relocation automatically.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>NOLIST</CODE></TD><TD>
The code following this directive will not appear in the listing file created when the <B>'-l'</B> or <B>'-x'</B> switch is specified.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>LIST</CODE></TD><TD>
Reenables the listing of code after a <CODE>NOLIST</CODE> directive.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>PAGE</CODE></TD><TD>
Inserts a form feed into the listing file created when the <B>'-l'</B> or <B>'-x'</B> switch is specified.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>SPC [<I>n</I>]</CODE></TD><TD>
Skips <I>n</I> lines, or 1 line if <I>n</I> is omitted, in the listing file created when the <B>'-l'</B> or <B>'-x'</B> switch is specified.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>TTL <I>string</I></CODE><BR><B>OR:</B> <CODE>TITLE <I>string</I></CODE></TD><TD>
Sets the title on the pages of the listing file created when the <B>'-l'</B> or <B>'-x'</B> switch is specified to <I>string</I>. Also begins a new page when specified on the middle of a page.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>IDNT "<I>name</I>"</CODE></TD><TD>
Sets the program unit name in the S-record generated when the <B>'-s'</B> switch is specified, to <I>name</I>. The quotes can be omitted. This directive is not useful in GCC4TI, since GCC4TI does not use S-records.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>\<I>localLbl</I></CODE></TD><TD>
Defines a local label, a label which can be accessed only in the space between the 2 global labels surrounding it. This mainly serves to avoid name conflicts: 2 or more local labels can have the same name as long as they are separated by a global label.
</TD></TR>
<TR><TD VALIGN="TOP"><CODE>\<I>localLbl</I>@<I>labelNum</I></CODE></TD><TD>
Defines a local enumeration label, invented mainly for use in macros. The idea is that <I>labelNum</I> can be a variable name which can be expanded while keeping <I>localLbl</I> unchanged. But it is usually a better idea to use <CODE>\@<I>label</I></CODE> or <CODE>\\@<I>localLbl</I></CODE> instead, which will automatically generate unique labels.
</TD></TR>
</TABLE></P>
<HR>
<H2><A NAME="smallcode"><U>The Small Code/Data model</U></A></H2>
<P>Version 2.4 implements a rudimentary small code/data model.
It consists of converting any data reference to one of the following
three addressing modes:
</P>
<UL>
<LI><P> address register indirect with displacement using a
specified address register, defaulting to <CODE>A4</CODE>
(for references to the <CODE>DATA</CODE> or <CODE>BSS</CODE> section);</P></LI>
<LI><P> program counter indirect with displacement
(for references to the <CODE>CODE</CODE> section);</P></LI>
<LI><P> absolute word
(for absolute and 16-bit relocatable values).</P></LI>
</UL>
<P>These conversions do not take place unless a <CODE>NEAR</CODE> directive is
encountered. The <CODE>NEAR</CODE> directive can take one operand, which
must be either an address register or a symbol which has been
equated (using <CODE>EQUR</CODE>) to an address register. Register <CODE>A7</CODE> (<CODE>SP</CODE>)
may not be used. If no register is given, <CODE>A4</CODE> is assumed.
<BR><BR>
Conversion is done for all operands until a <CODE>FAR</CODE> directive
is encountered. <CODE>NEAR</CODE> and <CODE>FAR</CODE> directives can occur any number
of times, enabling conversion to be turned on and off at will.
<BR><BR>
Backward references which cannot be converted (e.g. external
labels declared as <CODE>XREF</CODE>) will remain as absolute long addressing.
All forward references are assumed to be convertible, since during
pass 1 <CODE>A68k</CODE> has no way of telling whether conversion is possible.
If conversion turns out to be impossible, invalid object code will
be generated - an error message ("Invalid forward reference") will
indicate when this occurs.
<BR><BR>
Although the small code/data model can greatly reduce the
size of assembled programs, several restrictions apply:</P>
<UL>
<LI><P>Small code and small data models are active simultaneously.
You can't have one without the other, since during pass 1
A68k doesn't know whether forward references are to <CODE>CODE</CODE>
or to <CODE>DATA</CODE>/<CODE>BSS</CODE>.</P></LI>
<LI><P>Programs can consist of a maximum of two sections,
one <CODE>CODE</CODE>, the other <CODE>DATA</CODE> or <CODE>BSS</CODE>. If you try to define
a third section, the message "Too many SECTIONs" will
be displayed. The <CODE>NEAR</CODE> directive is active only within
the <CODE>CODE</CODE> section.</P></LI>
<LI><P>While the <CODE>NEAR</CODE> directive is active, external labels (<CODE>XREF</CODE>)
must be declared before they are used, <CODE>CODE</CODE> section references
must be with 32K of the current position (i.e. expressible as
PC-relative), and <CODE>DATA</CODE>/<CODE>BSS</CODE> section references must be in the
first 64K of the <CODE>DATA</CODE>/<CODE>BSS</CODE> section (i.e. expressible as
address register indirect with displacement). Any instructions
which do not satisfy these requirements cannot be detected in
pass 1, so A68k has no choice but to display an error message
in pass 2 ("Invalid forward reference") which in this case
indicates that invalid code has been generated. To properly
assemble such instructions, you can temporarily disable
conversion with a <CODE>FAR</CODE> directive, then resume afterwards
with another <CODE>NEAR</CODE> directive.</P></LI>
<LI><P>Conversion cannot be done for references between modules.
All external references must be left as absolute long.</P></LI>
<LI><P><CODE>A68k</CODE> assumes that the base register (normally <CODE>A4</CODE>) points to
the start of the <CODE>DATA</CODE>/<CODE>BSS</CODE> section plus 32768 bytes (this
assumed offset can be changed by the <B>'-m'</B> command-line parameter).
The register must be preloaded with this value before executing
any code converted by the <CODE>NEAR</CODE> directive. One way to do this
is to code the instruction that loads the register prior to
the <CODE>NEAR</CODE> directive. Another way is to use a <CODE>MOVE.L</CODE> with
immediate mode, which is never converted. Here are examples
of the two methods:</P>
<PRE> LEA data+32768,a4 NEAR
NEAR ;defaults to A4 MOVE.L #data+32768,a4
<remainder of code> <remainder of code>
BSS BSS
data: data:
<data areas> <data areas>
END END
</PRE>
</LI>
</UL>
<P>I'll be the first to admit that this is a very crude and ugly
implementation. I hope to improve it in future versions.</P>
<HR>
<H2><A NAME="files"><U>Files</U></A></H2>
<P><CODE>A68k</CODE> uses the following files:</P>
<UL>
<LI><P>The source code file - this file contains the program to be
assembled. This file is an ASCII text file whose last line
must be an <CODE>END</CODE> statement.
<TABLE><TR><TD><B>(TIGCC/GCC4TI)</B></TD><TD>
This <CODE>END</CODE> statement is no longer necessary starting
from v.2.71.F3c.<BR>
Moreover, the assembler will no longer accept an <CODE>END</CODE>
statement in include files or macros, since it did
never expect that and caused bugs.</TD></TR></TABLE></P></LI>
<LI><P>The object code file - this file is created by <CODE>A68k</CODE>, replacing
any previous version which may exist. If any errors are
encountered during the assembly, this file will be scratched,
unless the <B>'-k'</B> (keep) switch is specified (see below).
Although this file is normally written in AmigaDOS format,
the <B>'-s'</B> switch (see below) will cause it to be written in
Motorola S-record format instead.</P></LI>
<LI><P>The listing file - this file is optionally created by <CODE>A68k</CODE>
and contains a listing complete with page headings (including
form feeds), generated object code, and error messages if any.
It is suitable for feeding to a printer.</P></LI>
<LI><P>An equate file - this file is optionally created by <CODE>A68k</CODE>
and consists of a leading comment line followed by <CODE>EQU</CODE>
statements, one for each symbol encountered by <CODE>A68k</CODE> whose
value is absolute. This file is only created if the <B>'-e'</B>
command-line switch is specified (see below).</P></LI>
<LI><P>A header file - if requested, this file is read by <CODE>A68k</CODE>
immediately prior to the source code file. It treated
exactly as if it were requested by an <CODE>INCLUDE</CODE> statement
at the front of the source file, but is selected only if
the <B>'-h'</B> command-line switch is specified (see below).</P></LI>
<LI><P>Include files are selected by <CODE>INCLUDE</CODE> directives within the
source file, and are inserted in the source code in place
of the <CODE>INCLUDE</CODE> directive itself. <CODE>A68k</CODE> first searches the
current directory for <CODE>INCLUDE</CODE> files; the <B>'-i'</B> command-line
switch (see below) specifies additional directories which
can be searched.</P></LI>
</UL>
<HR>
<H2><A NAME="filenames"><U>File Names</U></A></H2>
<P>The names of the above files can be explicitly specified.
However, <CODE>A68k</CODE> will generate default file names in the following cases:</P>
<UL>
<LI><P>If the <B>'-o'</B> switch is omitted, a default name will be assigned
to the object code file.</P></LI>
<LI><P>If the <B>'-e'</B> switch is specified with no file name, a default
name will be assigned to the equate file.</P></LI>
<LI><P>If the <B>'-l'</B> or <B>'-x'</B> switch is specified with no file name, a
default name will be assigned to the listing file.</P></LI>
</UL>
<P>A default name is generated by deriving a stem name from the source
code file name, and appending <CODE>'.o'</CODE> for an object code file name (<CODE>'.s'</CODE>
if the <B>'-s'</B> switch is specified to produce Motorola S-records), <CODE>'.equ'</CODE>
for an equate file name, or <CODE>'.lst'</CODE> for a listing file name. The stem
name consists of all characters of the source file name up to the
last period (or the entire source file name if it contains no period).
Here are some examples of default names:
<BR><BR>
<TABLE BORDER CELLPADDING="5">
<TR><TD><B>Source file</B></TD><TD><B>Object file</B></TD><TD><B>Equate file</B></TD><TD><B>Listing file</B></TD></TR>
<TR><TD>myprog.asm</TD><TD>myprog.o</TD><TD>myprog.equ</TD><TD>myprog.lst</TD></TR>
<TR><TD>myprog</TD><TD>myprog.o</TD><TD>myprog.equ</TD><TD>myprog.lst</TD></TR>
<TR><TD>new.prog.asm</TD><TD>new.prog.o</TD><TD>new.prog.equ</TD><TD>new.prog.lst</TD></TR>
</TABLE></P>
<HR>
<H2><A NAME="usage"><U>A68k Command-Line Parameters (How to use A68k)</U></A></H2>
<P>The command-line syntax to run the assembler is as follows:</P>
<PRE> a68k <<I>source file name</I>>
[<<I>object file name</I>>]
[<<I>listing file name</I>>]
<B>(TIGCC/GCC4TI)</B> [-a]
[-d[[!]<<I>prefix</I>>]]
[-e[<<I>equate file name</I>>]]
[-f]
[-g]
[-h<<I>header file name</I>>]
[-i<<I>include directory list</I>>]
[-k]
[-l[<<I>listing file name</I>>]]
[-m<<I>small data offset</I>>]
[-n]
[-o<<I>object file name</I>>]
[-p<<I>page depth</I>>]
[-q[<<I>quiet interval</I>>]]
<B>(TIGCC/GCC4TI)</B> [-r[a][l][m]]
[-s]
[-t]
<B>(TIGCC/GCC4TI)</B> [-u]
<B>(TIGCC/GCC4TI)</B> [-v<<I>name</I>>[,<<I>value</I>>]
[-w[<<I>hash table size</I>>][,<<I>secondary heap size</I>>]]
[-x[<<I>listing file name</I>>]]
[-y]
[-z[<<I>debug start line</I>>][,<<I>debug end line</I>>]]
</PRE>
<P>
These options can be given in any order. Any parameter which is not
a switch (denoted by a leading hyphen) is assumed to be a file name;
up to three file names (assumed to be source, object, and listing file
names respectively) can be given. A source file name is always required.
If a switch is being given a value, that value must immediately follow
the switch letter with no intervening spaces. For instance, to specify
a page depth of 40 lines, the specification <B>'-p40'</B> should be used;
<B>'-p 40'</B> will be rejected.
<BR><BR>
Switches perform the following actions:</P>
<DL>
<DT><P><B>-a</B></P><DD><P>Causes all relocs to be emitted, even PC-relative relocs
within a section. It also emits address differences in a
special TIGCC/GCC4TI-specific format. This will allow more
aggressive linker-side optimization.
</P><DT><P><B>-d</B></P><DD><P>Causes symbol table entries (hunk_symbol) to be written
to the object module for the use of symbolic debuggers.
If the switch is followed by a string of characters, only
those symbols beginning with that prefix string will be
written. This can be used to suppress internal symbols
generated by compilers. If the first character is an
exclamation mark (<CODE>'!'</CODE>), only symbols which do <B>not</B> begin
with the following characters are written out. Here are some examples:
<BR><BR>
<TABLE CLASS="NOBORDER">
<TR><TD CLASS="NOBORDER"><CODE>-d</CODE></TD><TD CLASS="NOBORDER">writes all symbols</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-dabc </CODE></TD><TD CLASS="NOBORDER">writes only symbols beginning with "abc"</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-d!x</CODE></TD><TD CLASS="NOBORDER">writes symbols which do not begin with "x"</TD></TR>
</TABLE>
</P><DT><P><B>-e</B></P><DD><P>Causes an equate file (see above) to be produced. A file
name can be specified; otherwise a default name will be used.
</P><DT><P><B>-f</B></P><DD><P>Causes any branches (<CODE>B<I>cc</I></CODE>, <CODE>BRA</CODE>, <CODE>BSR</CODE>) that could be converted
to short form to be flagged. <CODE>A68k</CODE> will convert as many
branches as possible to short form (unless the <B>'-n'</B> switch is
is specified), but certain combinations of instructions may
set up a ripple effect where shortening one branch brings
another one into range. This switch will cause <CODE>A68k</CODE> to
flag any branches that it may have missed; during pass 2
it is possible to tell this, although during pass 1 it might
not be. If the <B>'-n'</B> switch (see below) is specified along
with this switch (suppressing all optimization), no branches
will be shortened, but all branches which could be shortened
will be flagged.
</P><DT><P><B>-g</B></P><DD><P>Causes any undefined symbols to be treated as if they were
externally defined (<CODE>XREF</CODE>), rather than being flagged as errors.
</P><DT><P><B>-h</B></P><DD><P>Causes a header file to be read prior to the source code file.
A file name must be given. The action is the same as if the
first statement of the source file were an <CODE>INCLUDE</CODE> statement
naming the header file. To find the header file, the same
directories will be searched as for <CODE>INCLUDE</CODE> files (see the
<B>'-i'</B> switch below).
</P><DT><P><B>-i</B></P><DD><P>Specifies directories to be searched for <CODE>INCLUDE</CODE> files in
addition to the current directory. Several names, separated
by commas, may be specified. No embedded blanks are allowed.
For example, the specification</P>
<PRE>-imylib,df1:another.lib
</PRE>
<P>will cause <CODE>INCLUDE</CODE> files to be searched for first in the
current directory, then in "mylib", then in "df1:another.lib".
</P><DT><P><B>-k</B></P><DD><P>Causes the object file to be kept even if any errors were
found. Otherwise, it will be scratched if any errors occur.
</P><DT><P><B>-l</B></P><DD><P>Causes a listing file to be produced. If you want the listing
file to include a symbol table dump and cross-reference, use
the <B>'-x'</B> switch instead (see below).
</P><DT><P><B>-m</B></P><DD><P>Changes the assumed offset from the start of the <CODE>DATA</CODE>/<CODE>BSS</CODE>
section to the base register used when the small code/data
option is activated by the <CODE>NEAR</CODE> directive.
If this parameter is not specified, the offset defaults
to 32768.
</P><DT><P><B>-n</B></P><DD><P>Causes all object code optimization (see above) to be disabled.
</P><DT><P><B>-o</B></P><DD><P>Allows the default name for the object code file (see above)
to be overridden.
</P><DT><P><B>-p</B></P><DD><P>Causes the page depth to be set to the specified value.
This takes the place of the <CODE>PLEN</CODE> directive in the Metacomco
assembler. Page depth defaults to 60 lines (<B>'-p60'</B>).
</P><DT><P><B>-q</B></P><DD><P>Changes the interval at which <CODE>A68k</CODE> displays the line number
it has reached in its progress through the assembly. The
default is to display every 100 lines (<B>'-q100'</B>). Specifying
larger values reduces console I/O, making assemblies run
slightly faster.
<BR><BR>
If you specify a negative number (e.g. <B>'-q-10'</B>), line numbers
will be displayed at an interval equal to the absolute value
of the specified number, but will be given as positions
within the current module (source, macro, or <CODE>INCLUDE</CODE>) rather
than as a total statement count - the module name will also
be displayed.
<BR><BR>
A special case is the value zero (<B>'-q0'</B> or just <B>'-q'</B>) - this
will cause all console output, except for error messages,
to be suppressed.
</P><DT><P><B>(TIGCC/GCC4TI)</B> <B>-r</B></P><DD><P>Allows to disable specific optimizations:<BR>
<B>-rm</B> Disable the <CODE>MOVEM</CODE> -> <CODE>MOVE</CODE> optimization<BR>
<B>-ra</B> Disable the <CODE>ADD(A)/SUB(A)</CODE> -> <CODE>LEA</CODE> optimization<BR>
<B>-rl</B> Disable the <CODE>LEA</CODE> -> <CODE>ADDQ/SUBQ</CODE> optimization<BR>
You might use more than one <B>-r</B> switch (as in "<B>-rm -ra</B>") or combine them into a single switch (as in "<B>-rma</B>").
</P><DT><P><B>-s</B></P><DD><P>Causes the object file to be written in Motorola S-record
format, rather than AmigaDOS format. The default name for
an S-record file ends with <CODE>'.s'</CODE> rather than <CODE>'.o</CODE>; this can
still be overridden with the <B>'-o'</B> switch, though.
</P><DT><P><B>-t</B></P><DD><P>Allows tabs in the source file to be passed through to the
listing file, rather than being expanded. In addition, tabs
will be generated in the listing file to skip from the object
code to the source statement, etc. This can greatly reduce
the size of the listing file, as well as making it quicker to
produce. Do not use this option if you will be displaying or
listing the list file on a device which does not assume a tab
stop at every 8th position.
</P><DT><P><B>(TIGCC/GCC4TI)</B> <B>-u</B></P><DD><P>Disables automatic alignment of <CODE>DC.W</CODE>,
<CODE>DC.L</CODE>, <CODE>DCB.W</CODE>, <CODE>DCB.L</CODE>,
<CODE>DS.W</CODE>, <CODE>DS.L</CODE> and code.
</P><DT><P><B>(TIGCC/GCC4TI)</B> <B>-v</B></P><DD><P>Allows to set a variable in the command line (like <B>-d</B> with
<CODE>GCC</CODE>). The variable will be a <CODE>SET</CODE>, not <CODE>EQU</CODE> variable. Syntax:
"<B>-v</B><<I>name</I>>[,<<I>value</I>>]" (without spaces, and without the
quotes). Note that <<I>value</I>> can only be a <B>NUMBER</B> at the
moment. (We might support symbols as values in a future
version.) The default value of <<I>value</I>> is 1.
</P><DT><P><B>-w</B></P><DD><P>Specifies the sizes of fixed memory areas that <CODE>A68k</CODE> allocates
for its own use. You should normally never have to specify
this switch, but it may be useful for tuning.
<BR><BR>
The first parameter gives the number of entries that the hash
table (used for searching the symbol table) will contain.
The default value of 2047 should be enough for all but the
very largest programs. The assembly will not fail if this
value is too small, but may slow down if too many long hash
chains must be searched. The hashing statistics displayed by
the <B>'-y'</B> switch (see below) can be used to tune this parameter.
I've heard that you should really specify a prime number for
this parameter, but I haven't gone into hashing theory enough
to know whether it's actually necessary.
<BR><BR>
The second parameter of the <B>'-w'</B> switch specifies the size (in
bytes) of the secondary heap, which is used to store nested
macro and <CODE>INCLUDE</CODE> file information (see below). It defaults
to 1024, which should be enough unless you use very deeply
nested macros and/or <CODE>INCLUDE</CODE> files with long path names.
<BR><BR>
<TABLE><TR><TD><B>(TIGCC/GCC4TI)</B></TD><TD>
The default sizes are 4095,2048 in the Win32 (since
v.2.71.F3a) and GNU/Linux (since v.2.71.F3c) versions.</TD></TR></TABLE>
<BR><BR>
You can specify either or both parameters. For example:
<BR><BR>
<TABLE CLASS="NOBORDER">
<TR><TD CLASS="NOBORDER"><CODE>-w4093</CODE></TD><TD CLASS="NOBORDER">secondary heap size remains at 1024 bytes</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-w,2000</CODE></TD><TD CLASS="NOBORDER">hash table size remains at 2047 entries</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-w4093,2000 </CODE></TD><TD CLASS="NOBORDER">increases the size of both areas</TD></TR>
</TABLE>
<BR>
If you're really tight for memory, and are assembling small
modules, you can use this switch to shrink these areas below
their default sizes. At the end of an assembly, a message
will be displayed giving the sizes actually used, in the form
of the <B>'-w'</B> command you would have to enter to allocate that much
space. This is primarily useful to see how much secondary
heap space was used.
<BR><BR>
<B>Note:</B> All other memory used by <CODE>A68k</CODE> (e.g. the actual symbol
table) is allocated as required (currently in 8K chunks).
</P><DT><P><B>-x</B></P><DD><P>Works the same as <B>'-l'</B> (see above), except that a symbol table
dump, including cross-reference information, will be added
to the end of the listing file.
</P><DT><P><B>-y</B></P><DD><P>Causes hashing statistics to be displayed at the end of the
assembly. First the number of symbols in the table is given,
followed by a summary of hash chains by length. Chains with
length zero denote unused hash table entries. Ideally (i.e.
if there were no collisions) there should be as many chains
with length 1 as there are symbols, and there should be no
chains of length 2 or greater. I added this option to help
me tune my hashing algorithm, but you can also use it to see
whether you should allocate a larger hash table (using the
first parameter of the <B>'-w'</B> switch, see above).
</P><DT><P><B>-z</B></P><DD><P>This switch was provided to help debug <CODE>A68k</CODE> itself. It causes <CODE>A68k</CODE> to
list a range of source lines, complete with line number and
current location counter value, during both passes. Lines
are listed immediately after they have been read from the
source file, before any processing occurs. Here are some examples of the <B>'-z'</B> switch:
<BR><BR>
<TABLE CLASS="NOBORDER">
<TR><TD CLASS="NOBORDER"><CODE>-z</CODE></TD><TD CLASS="NOBORDER">lists all source lines</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-z100,200 </CODE></TD><TD CLASS="NOBORDER">lists lines 100 through 200</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-z100</CODE></TD><TD CLASS="NOBORDER">lists all lines starting at 100</TD></TR>
<TR><TD CLASS="NOBORDER"><CODE>-z,100</CODE></TD><TD CLASS="NOBORDER">lists the first 100 lines</TD></TR>
</TABLE></P>
</DL>
<HR>
<H2><A NAME="tech"><U>Technical Information</U></A></H2>
<P>The actual symbol table entries (pointed to by the hash table,
colliding entries are linked together) are stored in 8K chunks which
are allocated as required. The first entry of each chunk is reserved
as a link to the next chunk (or NULL in the last chunk) - this makes
it easy to find all the chunks to free them when we're finished. All
symbol table entries are stored in pass 1. During pass 2, cross-
reference table entries are built in the same group of chunks,
immediately following the last symbol table entry. Additional chunks
will continue to be linked in if necessary.
<BR><BR>
Symbol names and macro text are stored in another series of linked
chunks. These chunks consist of a link pointer followed by strings
(terminated by nulls) laid end to end. Symbols are independent entries,
linked from the corresponding symbol table entry. Macros are stored as
consecutive strings, one per line - the end of the macro is indicated by
an <CODE>ENDM</CODE> statement. If a macro spans two chunks, the last line in the
original chunk is followed by a newline character to indicate that the
macro is continued in the next chunk.
<BR><BR>
Relocation information is built during pass 2 in yet another
series of linked chunks. If more than one chunk is needed to hold one
section's relocation information, all additional chunks are released
at the end of the section.
<BR><BR>
The secondary heap is built from both ends, and it grows and
shrinks according to how many macros and <CODE>INCLUDE</CODE> files are currently
open. At all times there will be at least one entry on the heap, for
the original source code file. The expression parser also uses the
secondary heap to store its working stacks - this space is freed as
soon as an expression has been evaluated.
<BR><BR>
The bottom of the heap holds the names of the source code file
and any macro or <CODE>INCLUDE</CODE> files that are currently open. The full path
is given. A null string is stored for user macros. Macro arguments
are stored by additional strings, one for each argument in the macro
call line. All strings are stored in minimum space, similar to the
labels and user macro text on the primary heap. File names are
pointed to by the fixed table entries (see below) - macro arguments
are accessed by stepping past the macro name to the desired argument,
unless NARG would be exceeded.
<BR><BR>
The fixed portion of the heap is built down from the top. Each
entry occupies 16 bytes. Enough information is stored to return to
the proper position in the outer file once the current macro or
<CODE>INCLUDE</CODE> file has been completely processed.
<BR><BR>
The diagram below illustrates the layout of the secondary heap.</P>
<PRE>
Heap2 + maxheap2 -----------> ___________________________
| |
| Input file table |
struct InFCtl *InF ---------> |___________________________|
| |
| Parser operator stack |
struct OpStack *Ops --------> |___________________________|
| |
| (unused space) |
struct TermStack *Term -----> |___________________________|
| |
| Parser term stack |
char *NextFNS --------------> |___________________________|
| |
| Input file name stack |
char *Heap2 ----------------> |___________________________|
</PRE>
<P>The "high-water mark" for <CODE>NextFNS</CODE> is stored in <CODE>char *High2</CODE>,
and the "low-water mark" (to stretch a metaphor) for <CODE>InF</CODE> is stored
in <CODE>struct InFCtl *LowInF</CODE>. These figures are used only to determine
the maximum heap usage.</P>
<HR>
<H2><A NAME="contact"><U>A68k Contact Information and Bug Reports</U></A></H2>
<P>And Finally...
<BR><BR>
<S> Please send me any bug reports, flames, etc. I can be reached
on Mind Link (604/533-2312), at any meeting of the Commodore
Computer Club / Panorama (PAcific NORthwest AMiga Association),
or via Jeff Lydiatt or Larry Phillips. I don't have the time
or money to live on Compuserve or BIX, but my Usenet address is
Charlie_Gibbs@mindlink.UUCP (...uunet!van-bc!rsoft!mindlink!a218).
<BR><BR>
<B>
Charlie Gibbs<BR>
2121 Rindall Avenue<BR>
Port Coquitlam, B.C.<BR>
Canada<BR>
V3C 1T9<BR>
</B></S>
<BR><BR>
<TABLE><TR><TD><B>(GCC4TI)</B></TD><TD>
Since, as far as we can tell, Charlie Gibbs is no longer
maintaining A68k since 1991, you are better off filing a bug report
to the GCC4TI project:
<A HREF="http://trac.godzil.net/gcc4ti/">http://trac.godzil.net/gcc4ti/</A></TD></TR></TABLE></P>
<HR>
<H2><A NAME="history"><U>History of A68k</U></A></H2>
<P><B>Note:</B> This section has been added to the documentation by the TIGCC Team. It was in <I>history.txt</I> before.
<BR><BR>
<B>Version 2.71.F3z (Lionel Debroux, July 29, 2009)</B></P>
<UL><LI><P>Bugfix: Fix moveq #$FFFFFFFE,dn on 64-bit platforms.</P></LI></UL>
<P><B>Version 2.71.F3y (Patrick Pelissier, June 27, 2009)</B></P>
<UL><LI><P>Improved: the maximum length of a line has been raised from 256 to 65536.</P></LI></UL>
<UL><LI><P>Bugfix: don't compile A68k statically, as it fails on multiple platforms in their
out of the box configuration (Lionel Debroux).</P></LI></UL>
<P><B>Version 2.71.F3x (Manoel Trapier, December 23, 2008)</B></P>
<UL><LI><P>Added: OS X Makefile that generate an Universal Binary version.</P></LI></UL>
<P><B>Version 2.71.F3w (Kevin Kofler, July 27, 2006)</B></P>
<UL><LI><P>Bugfix: Fixed compilation on *BSD and recent versions of OS X.</P></LI></UL>
<P><B>Version 2.71.F3v (Kevin Kofler, July 31, 2005)</B></P>
<UL><LI><P>Bugfix: Don't crash on EQUs doing arithmetic with other EQUs which do
arithmetic with undefined symbols, print an error instead.</P></LI></UL>
<P><B>Version 2.71.F3u (Kevin Kofler, February 2, 2005)</B></P>
<UL><LI><P>Bugfix: Fixed compilation with GCC 3.4.</P></LI></UL>
<P><B>Version 2.71.F3t (Kevin Kofler, January 31, 2005)</B></P>
<UL><LI><P>Added: NO_UNOPTIMIZABLE_RELOCS compile-time define (disabled by default)
to allow generating AmigaOS-compatible object files again.</P></LI>