-
Notifications
You must be signed in to change notification settings - Fork 16
/
gnuasm.html
2856 lines (2677 loc) · 144 KB
/
gnuasm.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 GNU 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 GNU Assembler</B></FONT>
<HR>
<P>This part of the documentation is a modified version of the <A HREF="http://sources.redhat.com/binutils/docs-2.12/as.info/">GNU Assembler Manual</A>.
Therefore it is licensed under the <A HREF="gnugpl.html#gnufdl">GNU Free Documentation License</A>.
<BR><BR>
The GNU assembler <CODE>as</CODE> is primarily intended to assemble the output
of the GNU C compiler for use by the linker, so it may be regarded as an internal
part of GCC4TI package.
However, it may be called as a standalone program, and the GNU team
tried to make <CODE>as</CODE> assemble everything correctly that other assemblers
for the same machine would assemble. Any exceptions are documented explicitly.
This doesn't mean <CODE>as</CODE> always uses the same syntax as other
assemblers for the same architecture; for example, there exist several
incompatible versions of the MC 68000 assembly language syntax, so the syntax used
in the GNU assembler is not exactly the same as in some other assemblers
(like the <A HREF="a68k.html">A68k Assembler</A>, which is the most frequently
used assembler for the TI-89 and TI-92+, and which is also included in the GCC4TI
package as a standalone program).
<BR><BR>
This documentation will cover <CODE>as</CODE> features which are applicable
to GCC4TI. The most frequent use of <CODE>as</CODE> is probably as
an <A HREF="gnuexts.html#SEC94">inline assembler</A>, which allows mixing assembly
statements with C code using the <CODE>asm</CODE> keyword.
<BR><BR>
This documentation is <I>not</I>
intended as an introduction to programming in assembly language. In a similar
vein, you will not find here details about machine architecture: here you can not
expect detailed description of the instruction set, standard mnemonics, registers
or addressing modes. You may want to consult the Motorola manufacturer's machine
architecture manual for such information.
<BR><BR>
<B>Note:</B> It is possible to use source files for the GNU Assembler
together with C source files in GCC4TI projects.</P>
<UL>
<LI><B><A HREF="#SEC9">GNU Assembler Command Line</A></B>
<LI><B><A HREF="#SEC20">GNU Assembler Input and Output</A></B>
<LI><B><A HREF="#SEC25">GNU Assembler Syntax</A></B>
<LI><B><A HREF="#SEC39">Sections and Relocation</A></B>
<LI><B><A HREF="#SEC45">Assembler Symbols</A></B>
<LI><B><A HREF="#SEC60">Assembler Expressions</A></B>
<LI><B><A HREF="#SEC67">Assembler Directives</A></B>
<LI><B><A HREF="#acknowledge">Acknowledgements</A></B>
<LI><B><A HREF="#history">History</A></B>
<LI><B><A HREF="gnugpl.html">GNU General Public License</A></B>
<LI><B><A HREF="gnugpl.html#gnufdl">GNU Free Documentation License</A></B>
<LI><B><A HREF="gnugpl.html#funding">Funding Free Software</A></B>
</UL>
<P>Original author: Free Software Foundation, Inc.
<BR>
Authors of the modifications: Zeljko Juric, Sebastian Reichelt, and Kevin Kofler
<BR>
Published by the TIGCC Team, and now the GCC4TI project.
<BR>
See the <A HREF="#history">History</A> section for details and copyright information.
<BR><BR>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or any
later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled "<A HREF="gnugpl.html#gnufdl">GNU Free Documentation License</A>".</P>
<HR>
<H2><A NAME="SEC9"><U>GNU Assembler Command Line</U></A></H2>
<P>After the program name <CODE>as</CODE>, the command line may contain
options and file names. Options may appear in any order, and may be
before, after, or between file names. The order of file names is
significant.
<BR><BR>
<CODE>--</CODE> (two hyphens) by itself names the standard input file
explicitly, as one of the files for <CODE>as</CODE> to assemble.
<BR><BR>
Except for <CODE>--</CODE> any command line argument that begins with a
hyphen (<CODE>-</CODE>) is an option. Each option changes the behavior of
<CODE>as</CODE>. No option changes the way another option works. An
option is a <CODE>-</CODE> followed by one or more letters; the case of
the letter is important. All options are optional.
<BR><BR>
Some options expect exactly one file name to follow them. The file
name may either immediately follow the option's letter (compatible
with older assemblers) or it may be the next command argument (GNU
standard). These two command lines are equivalent:</P>
<PRE>as -o my-object-file.o mumble.s
as -omy-object-file.o mumble.s
</PRE>
<UL>
<LI><B><A HREF="#SEC10">Invoking the GNU Assembler from GCC4TI</A></B>
<LI><B><A HREF="#SEC11">GNU Assembler Command-Line Options</A></B>
</UL>
<H3><A NAME="SEC10"><U>Invoking the GNU Assembler from GCC4TI</U></A></H3>
<P>If you are invoking <CODE>as</CODE> via <CODE>tigcc</CODE>,
you can use the <B>'-Wa'</B> option to pass arguments through to the assembler.
The assembler arguments must be separated from each other (and the <B>'-Wa'</B>)
by commas. For example:</P>
<PRE>tigcc -c -g -O -Wa,-alh,-L file.c
</PRE>
<P>This passes two options to the assembler: <B>'-alh'</B> (emit a listing to
standard output with high-level and assembly source) and <B>'-L'</B> (retain
local symbols in the symbol table).
<BR><BR>
Usually you do not need to use this <B>'-Wa'</B> mechanism, since many compiler
command-line options are automatically passed to the assembler by the compiler.
(You can call the GNU compiler driver with the <B>'-v'</B> option to see
precisely what options it passes to each compilation pass, including the
assembler.)</P>
<H3><A NAME="SEC11"><U>GNU Assembler Command-Line Options</U></A></H3>
<P>Here is a brief summary of how to invoke <CODE>as</CODE>.</P>
<DL>
<DT><P><B>-a[cdhlmns]</B></P><DD><P>Turn on listings, in any of a variety of ways:
</P>
<DL>
<DT><P><B>-ac</B></P><DD><P>omit false conditionals
</P><DT><P><B>-ad</B></P><DD><P>omit debugging directives
</P><DT><P><B>-ah</B></P><DD><P>include high-level source
</P><DT><P><B>-al</B></P><DD><P>include assembly
</P><DT><P><B>-am</B></P><DD><P>include macro expansions
</P><DT><P><B>-an</B></P><DD><P>omit forms processing
</P><DT><P><B>-as</B></P><DD><P>include symbols
</P><DT><P><B>=file</B></P><DD><P>set the name of the listing file</P>
</DL>
<P>
You may combine these options; for example, use <B>'-aln'</B> for assembly
listing without forms processing. The <B>'=file'</B> option, if used, must be
the last one. By itself, <B>'-a'</B> defaults to <B>'-ahls'</B>.
<BR><BR>
For more information, see <A HREF="#SEC13">Enabling Listings</A>.
</P><DT><P><B>--all-relocs</B></P><DD><P>Output all references to non-absolute symbols in the assembled file as
relocation items in the object file, even if the form of a reference would
permit the assembler to resolve it. This especially affects pc-relative
references to symbols defined in the same section, and certain calculations
with symbols. For some calculations, this requires special GCC4TI-specific
support for negative relocation items. If a calculation cannot be output
without being resolved, an error message is generated. This option implies
'--keep-locals'. The assembler also outputs a special symbol
<CODE>__ld_all_relocs</CODE> to tell the linker that there are no implicit
dependencies between different locations inside the sections.
</P><DT><P><B>-D</B></P><DD><P>Ignored. This option is accepted for script compatibility with calls to
other assemblers.
</P><DT><P><B>--defsym <I>sym</I>=<I>value</I></B></P><DD><P>Define the symbol <I>sym</I> to be <I>value</I> before assembling the input file.
<I>value</I> must be an integer constant. As in C, a leading <CODE>0x</CODE>
indicates a hexadecimal value, and a leading <CODE>0</CODE> indicates an octal value.
</P><DT><P><B>-f</B></P><DD><P>"fast" - skip whitespace and comment preprocessing (assume source is
compiler output).
<BR><BR>
This option should only be used when assembling programs written by a
(trusted) compiler. It stops the assembler from doing whitespace
and comment preprocessing on the input file(s) before assembling them.
See <A HREF="#SEC26">Preprocessing</A>.
<BR><BR>
<B>Warning:</B> if you use <B>'-f'</B> when the files actually need to be
preprocessed (if they contain comments, for example), <CODE>as</CODE> does
not work correctly.
</P><DT><P><B>--gdwarf2</B></P><DD><P>Generate DWARF 2 debugging information for each assembler line. This
may help debugging assembler code, if the debugger can handle it.
</P><DT><P><B>--gstabs</B></P><DD><P>Generate stabs debugging information for each assembler line. This
may help debugging assembler code, if the debugger can handle it.
</P><DT><P><B>--help</B></P><DD><P>Print a summary of the command line options and exit.
</P><DT><P><B>--target-help</B></P><DD><P>Print a summary of all target specific options and exit.
</P><DT><P><B>-I <I>dir</I></B></P><DD><P>Add directory <I>dir</I> to the search list for <CODE><A HREF="#SEC97">.include</A></CODE> directives.
</P><DT><P><B>-J</B></P><DD><P>Don't warn about signed overflow.
</P><DT><P><B>-K</B></P><DD><P>This option is accepted but has no effect on the 680x0 family.
</P><DT><P><B>-L</B>
<BR><B>--keep-locals</B></P><DD><P>Keep (in the symbol table) local symbols. On traditional a.out systems
these start with <CODE>L</CODE>, but different systems have different local
label prefixes. See <A HREF="#SEC18">Including Local Labels</A>.
</P><DT><P><B>--listing-lhs-width=<I>number</I></B></P><DD><P>Set the maximum width, in words, of the output data column for an assembler
listing to <I>number</I>.
<BR><BR>
For more information, see <A HREF="#SEC14">Configuring Listing Output</A>.
</P><DT><P><B>--listing-lhs-width2=<I>number</I></B></P><DD><P>Set the maximum width, in words, of the output data column for continuation
lines in an assembler listing to <I>number</I>.
</P><DT><P><B>--listing-rhs-width=<I>number</I></B></P><DD><P>Set the maximum width of an input source line, as displayed in a listing, to
<I>number</I> bytes.
</P><DT><P><B>--listing-cont-lines=<I>number</I></B></P><DD><P>Set the maximum number of lines printed in a listing for a single line of input
to <I>number</I>+1.
</P><DT><P><B>-M</B>
<BR><B>--mri</B></P><DD><P>Use MRI compatibility mode. See <A HREF="#SEC19a">Assembling in MRI Compatibility Mode</A>.
</P><DT><P><B>--MD <I>depfile</I></B></P><DD><P>Generate a dependency file. This file consists of a single rule suitable for
<CODE>make</CODE> describing the dependencies of the main source file. The rule
is written to the file named in its argument. This feature is used in the automatic
updating of makefiles. It is not particulary useful for GCC4TI.
</P><DT><P><B>-o <I>objfile</I></B></P><DD><P>Name the object-file output from <CODE>as</CODE> <I>objfile</I>.
See <A HREF="#SEC15">Naming the Output File</A>.
</P><DT><P><B>-R</B></P><DD><P>Fold the data section into the text section. See <A HREF="#SEC17">Joining the Data and Text Sections</A>.
</P><DT><P><B>--statistics</B></P><DD><P>Print the maximum space (in bytes) and total time (in seconds) used by
assembly.
</P><DT><P><B>--strip-local-absolute</B></P><DD><P>Remove local absolute symbols from the outgoing symbol table.
</P><DT><P><B>--traditional-format</B></P><DD><P>Use a more traditional output format. See <A HREF="#SEC19">Traditional Assembler Output Format</A>.
</P><DT><P><B>-v</B>
<BR><B>-version</B></P><DD><P>Print the <CODE>as</CODE> version.
</P><DT><P><B>--version</B></P><DD><P>Print the <CODE>as</CODE> version and exit.
</P><DT><P><B>-W</B>
<BR><B>--no-warn</B></P><DD><P>Suppress warning messages.
<BR><BR>
See <A HREF="#SEC16">Controlling Warnings</A> for more information about warning switches.
</P><DT><P><B>--fatal-warnings</B></P><DD><P>Treat warnings as errors.
</P><DT><P><B>--warn</B></P><DD><P>Don't suppress warning messages or treat them as errors.
</P><DT><P><B>-w</B></P><DD><P>Ignored.
</P><DT><P><B>-x</B></P><DD><P>Ignored.
</P><DT><P><B>-Z</B></P><DD><P>Generate an object file even after errors.
</P><DT><P><B>-- | <I>files</I> </B></P><DD><P>Standard input, or source files to assemble.</P>
</DL>
<UL>
<LI><B><A HREF="#SEC12">M680x0 Options</A></B>
<LI><B><A HREF="#SEC13">Enabling Listings</A></B>
<LI><B><A HREF="#SEC15">Naming the Object File</A></B>
<LI><B><A HREF="#SEC16">Controlling Warnings</A></B>
<LI><B><A HREF="#SEC17">Joining the Data and Text Sections</A></B>
<LI><B><A HREF="#SEC18">Including Local Labels</A></B>
<LI><B><A HREF="#SEC19">Traditional Assembler Output Format</A></B>
<LI><B><A HREF="#SEC19a">Assembling in MRI Compatibility Mode</A></B>
</UL>
<H4><A NAME="SEC12"><U>M680x0 Options</U></A></H4>
<P>The Motorola 680x0 version of <CODE>as</CODE> has a few machine
dependent options:</P>
<DL>
<DT><P><B>-l</B></P><DD><P>You can use the <B>'-l'</B> option to shorten the size of references to undefined
symbols. If you do not use the <B>'-l'</B> option, references to undefined
symbols are wide enough for a full <CODE>long</CODE> (32 bits). (Since
<CODE>as</CODE> cannot know where these symbols end up, <CODE>as</CODE> can
only allocate space for the linker to fill in later. Since <CODE>as</CODE>
does not know how far away these symbols are, it allocates as much space as it
can.) If you use this option, the references are only one word wide (16 bits).
This may be useful if you want the object file to be as small as possible, and
you know that the relevant symbols are always less 32 KB away. This option
implies '--short-jumps'.
</P><DT><P><B>--short-jumps</B></P><DD><P>The <B>'--short-jumps'</B> option shortens the size of branches to
undefined symbols. Unlike <B>'-l'</B>, other references to undefined symbols
are kept wide enough for a full <CODE>long</CODE> (32 bits), unless an
explicit size is specified. This enables you to optimize a modular program
that is smaller than 32 KB as well as possible, while still being able to
reference an external BSS or data section (since no jumps can point into
these sections). Previously (and in non-TIGCC assemblers), the <B>'-l'</B>
option acted like this, but the documentation did not say this.
</P><DT><P><B>--register-prefix-optional</B></P><DD><P>Since the compiler as configured for GCC4TI
does not prepend an underscore to the names of user variables, the
assembler requires a <CODE>%</CODE> before any use of a register name. This
is intended to let the assembler distinguish between C variables and
functions named <CODE>a0</CODE> through <CODE>a7</CODE>, and so on.
The <B>'--register-prefix-optional'</B> option may be used
to permit omitting the <CODE>%</CODE> even in GCC4TI.
If this is done, it will generally be impossible to
refer to C variables and functions with the same names as register
names.
</P><DT><P><B>--bitwise-or</B></P><DD><P>Normally the character <CODE>|</CODE> is treated as a comment character, which
means that it can not be used in expressions. The <B>'--bitwise-or'</B>
option turns <CODE>|</CODE> into a normal character. In this mode, you must
either use C style comments, or start comments with a <CODE>#</CODE> character
at the beginning of a line.
</P><DT><P><B>--base-size-default-16</B>
<BR><B>--base-size-default-32</B></P><DD><P>If you use an addressing mode with a base register without specifying
the size, <CODE>as</CODE> will normally use the full 32 bit value.
For example, the addressing mode <CODE>%a0@(%d0)</CODE> is equivalent to
<CODE>%a0@(%d0:l)</CODE>. You may use the <B>'--base-size-default-16'</B>
option to tell <CODE>as</CODE> to default to using the 16 bit value.
In this case, <CODE>%a0@(%d0)</CODE> is equivalent to <CODE>%a0@(%d0:w)</CODE>.
You may use the <B>'--base-size-default-32'</B> option to restore the
default behaviour.
</P><DT><P><B>--disp-size-default-16</B>
<BR><B>--disp-size-default-32</B></P><DD><P>If you use an addressing mode with a displacement, and the value of the
displacement is not known, <CODE>as</CODE> will normally assume that
the value is 32 bits. For example, if the symbol <CODE>disp</CODE> has not
been defined, <CODE>as</CODE> will assemble the addressing mode
<CODE>%a0@(disp,%d0)</CODE> as though <CODE>disp</CODE> is a 32 bit value. You may
use the <B>'--disp-size-default-16'</B> option to tell <CODE>as</CODE>
to instead assume that the displacement is 16 bits. In this case,
<CODE>as</CODE> will assemble <CODE>%a0@(disp,%d0)</CODE> as though
<CODE>disp</CODE> is a 16 bit value. You may use the
<B>'--disp-size-default-32'</B> option to restore the default behaviour.
</P><DT><P><B>--pcrel</B></P><DD><P>Always keep branches PC-relative. In the M680x0 architecture all branches
are defined as PC-relative. However, on some processors
(including the M68000 used in calculators) they are limited
to word displacements maximum. When <CODE>as</CODE> needs a long branch
that is not available, it normally emits an absolute jump instead. This
option disables this substitution. When this option is given and no long
branches are available, only word branches will be emitted. An error
message will be generated if a word branch cannot reach its target.
See <A HREF="#SEC221">Branch Improvement</A>.
</P><DT><P><B>-m680<I>x</I>0</B></P><DD><P><CODE>as</CODE> can assemble code for several different members of the
Motorola 680x0 family. The default in GCC4TI is to assemble
code for the 68000 microprocessor. The following options may be used to
change the default. These options control which instructions and
addressing modes are permitted. The members of the 680x0 family are
very similar. For detailed information about the differences, see the
Motorola manuals. (These options are not very useful for GCC4TI.)
</P>
<DL>
<DT><P><B>-m68000</B>
<BR><B>-m68ec000</B>
<BR><B>-m68hc000</B>
<BR><B>-m68hc001</B>
<BR><B>-m68008</B>
<BR><B>-m68302</B>
<BR><B>-m68306</B>
<BR><B>-m68307</B>
<BR><B>-m68322</B>
<BR><B>-m68356</B></P><DD><P>Assemble for the 68000. <B>'-m68008'</B>, <B>'-m68302'</B>, and so on are synonyms
for <B>'-m68000'</B>, since the chips are the same from the point of view
of the assembler.
</P><DT><P><B>-m68010</B></P><DD><P>Assemble for the 68010.
</P><DT><P><B>-m68020</B>
<BR><B>-m68ec020</B></P><DD><P>Assemble for the 68020.
</P><DT><P><B>-m68030</B>
<BR><B>-m68ec030</B></P><DD><P>Assemble for the 68030.
</P><DT><P><B>-m68040</B>
<BR><B>-m68ec040</B></P><DD><P>Assemble for the 68040.
</P><DT><P><B>-m68060</B>
<BR><B>-m68ec060</B></P><DD><P>Assemble for the 68060.
</P><DT><P><B>-mcpu32</B>
<BR><B>-m68330</B>
<BR><B>-m68331</B>
<BR><B>-m68332</B>
<BR><B>-m68333</B>
<BR><B>-m68334</B>
<BR><B>-m68336</B>
<BR><B>-m68340</B>
<BR><B>-m68341</B>
<BR><B>-m68349</B>
<BR><B>-m68360</B></P><DD><P>Assemble for the CPU32 family of chips.
</P><DT><P><B>-m5200</B></P><DD><P>Assemble for the ColdFire family of chips.
</P><DT><P><B>-m68881</B>
<BR><B>-m68882</B></P><DD><P>Assemble 68881 floating point instructions. This is the default for the
68020, 68030, and the CPU32. The 68040 and 68060 always support
floating point instructions.
</P><DT><P><B>-mno-68881</B></P><DD><P>Do not assemble 68881 floating point instructions. This is the default
for 68000 and the 68010. The 68040 and 68060 always support floating
point instructions, even if this option is used.
</P><DT><P><B>-m68851</B></P><DD><P>Assemble 68851 MMU instructions. This is the default for the 68020,
68030, and 68060. The 68040 accepts a somewhat different set of MMU
instructions; <B>'-m68851'</B> and <B>'-m68040'</B> should not be used
together.
</P><DT><P><B>-mno-68851</B></P><DD><P>Do not assemble 68851 MMU instructions. This is the default for the
68000, 68010, and the CPU32. The 68040 accepts a somewhat different set
of MMU instructions.</P>
</DL>
<P></P>
</DL>
<H4><A NAME="SEC13"><U>Enabling Listings</U></A></H4>
<P>The options starting with <B>'-a'</B> enable listing output from the assembler. By itself,
<B>'-a'</B> requests high-level, assembly, and symbols listing.
You can use other letters to select specific options for the list:
<B>'-ah'</B> requests a high-level language listing,
<B>'-al'</B> requests an output-program assembly listing, and
<B>'-as'</B> requests a symbol table listing.
High-level listings require that a compiler debugging option like
<B>'-g'</B> be used, and that assembly listings (<B>'-al'</B>) be requested
also.
<BR><BR>
Use the <B>'-ac'</B> option to omit false conditionals from a listing. Any lines
which are not assembled because of a false <CODE><A HREF="#SEC96">.if</A></CODE> (or <CODE>.ifdef</CODE>, or any
other conditional), or a true <CODE><A HREF="#SEC96">.if</A></CODE> followed by an <CODE><A HREF="#SEC83">.else</A></CODE>, will be
omitted from the listing.
<BR><BR>
Use the <B>'-ad'</B> option to omit debugging directives from the
listing.
<BR><BR>
Once you have specified one of these options, you can further control
listing output and its appearance using the directives <CODE><A HREF="#SEC107">.list</A></CODE>,
<CODE><A HREF="#SEC110">.nolist</A></CODE>, <CODE><A HREF="#SEC114">.psize</A></CODE>, <CODE><A HREF="#SEC82">.eject</A></CODE>, <CODE><A HREF="#SEC132">.title</A></CODE>, and
<CODE><A HREF="#SEC117">.sbttl</A></CODE>.
The <B>'-an'</B> option turns off all forms processing.
If you do not request listing output with one of the <B>'-a'</B> options, the
listing-control directives have no effect.
<BR><BR>
The letters after <B>'-a'</B> may be combined into one option,
<I>e.g.</I>, <B>'-aln'</B>.
<BR><BR>
Note if the assembler source is coming from the standard input (e.g. because it
is being created by <CODE>gcc</CODE> and the <B>'-pipe'</B> command line switch
is being used) then the listing will not contain any comments or preprocessor
directives. This is because the listing code buffers input source lines from
stdin only after they have been preprocessed by the assembler. This reduces
memory usage and makes the code more efficient.</P>
<UL>
<LI><B><A HREF="#SEC14">Configuring Listing Output</A></B>
</UL>
<H5><A NAME="SEC14"><U>Configuring Listing Output</U></A></H5>
<P>The listing feature of the assembler can be enabled via the command line switch
<B>'-a'</B> (see <A HREF="#SEC13">Enabling Listings</A>). This feature combines the input source file(s) with a
hex dump of the corresponding locations in the output object file, and displays
them as a listing file. The format of this listing can be controlled by pseudo
ops inside the assembler source (see <A HREF="#SEC13">Enabling Listings</A> for details) and also by the following switches:</P>
<DL>
<DT><P><B>--listing-lhs-width=number</B></P><DD><P>Sets the maximum width, in words, of the first line of the hex byte dump. This
dump appears on the left hand side of the listing output.
</P><DT><P><B>--listing-lhs-width2=number</B></P><DD><P>Sets the maximum width, in words, of any further lines of the hex byte dump for
a given input source line. If this value is not specified, it defaults to being
the same as the value specified for <B>'--listing-lhs-width'</B>. If neither
switch is used the default is to one.
</P><DT><P><B>--listing-rhs-width=number</B></P><DD><P>Sets the maximum width, in characters, of the source line that is displayed
alongside the hex dump. The default value for this parameter is 100. The
source line is displayed on the right hand side of the listing output.
</P><DT><P><B>--listing-cont-lines=number</B></P><DD><P>Sets the maximum number of continuation lines of hex dump that will be
displayed for a given single line of source input. The default value is 4.</P>
</DL>
<H4><A NAME="SEC15"><U>Naming the Object File</U></A></H4>
<P>There is always one object file output when you run <CODE>as</CODE>. By
default it has the name
<CODE>a.out</CODE>.
You can use the <B>'-o'</B> option (which takes exactly one filename) to give the
object file a different name.
<BR><BR>
Whatever the object file is called, <CODE>as</CODE> overwrites any
existing file of the same name.</P>
<H4><A NAME="SEC16"><U>Controlling Warnings</U></A></H4>
<P><CODE>as</CODE> should never give a warning or error message when
assembling compiler output. But programs written by people often
cause <CODE>as</CODE> to give a warning that a particular assumption was
made. All such warnings are directed to the standard error file.
<BR><BR>
If you use the <B>'-W'</B> and <B>'--no-warn'</B> options, no warnings are issued.
This only affects the warning messages: it does not change any particular of
how <CODE>as</CODE> assembles your file. Errors, which stop the assembly,
are still reported.
<BR><BR>
If you use the <B>'--fatal-warnings'</B> option, <CODE>as</CODE> considers
files that generate warnings to be in error.
<BR><BR>
You can switch these options off again by specifying <B>'--warn'</B>, which
causes warnings to be output as usual.</P>
<H4><A NAME="SEC17"><U>Joining the Data and Text Sections</U></A></H4>
<P>The <B>'-R'</B> option tells <CODE>as</CODE> to write the object file as if all
data-section data lives in the text section. This is only done at
the very last moment: your binary data are the same, but data
section parts are relocated differently. The data section part of
your object file is zero bytes long because all its bytes are
appended to the text section. (see <A HREF="#SEC39">Sections and Relocation</A>).
<BR><BR>
When you specify <B>'-R'</B>, it would be possible to generate shorter
address displacements (because we do not have to cross between text and
data section). We refrain from doing this simply for compatibility with
older versions of <CODE>as</CODE>. In the future, <B>'-R'</B> may work this way.
<BR><BR>
When <CODE>as</CODE> is configured for COFF output (which is the case in GCC4TI),
this option is only useful if you use sections named <CODE>.text</CODE> and
<CODE>.data</CODE>.</P>
<H4><A NAME="SEC18"><U>Including Local Labels</U></A></H4>
<P>Labels beginning with <CODE>L</CODE> (upper case only) are called <U>local
labels</U>. See <A HREF="#SEC48">Symbol Names</A>. Normally you do not see such labels when
debugging, because they are intended for the use of programs (like
compilers) that compose assembler programs, not for your notice.
Normally both <CODE>as</CODE> and <CODE>ld</CODE> discard such labels, so you do not
normally debug with them.
<BR><BR>
The <B>'-L'</B> option tells <CODE>as</CODE> to retain those <CODE>L...</CODE> symbols
in the object file. Usually, if you do this, you also tell the linker
<CODE>ld</CODE> to preserve symbols whose names begin with <CODE>L</CODE>.
<BR><BR>
By default, a local label is any label beginning with <CODE>L</CODE>, but each
target is allowed to redefine the local label prefix.</P>
<H4><A NAME="SEC19"><U>Traditional Assembler Output Format</U></A></H4>
<P>For some targets, the output of <CODE>as</CODE> is different in some ways
from the output of some existing assembler. The <B>'--traditional-format'</B> switch requests
<CODE>as</CODE> to use the traditional format instead.
<BR><BR>
For example, it disables the exception frame optimizations which
<CODE>as</CODE> normally does by default on <CODE>gcc</CODE> output.</P>
<H4><A NAME="SEC19a"><U>Assembling in MRI Compatibility Mode</U></A></H4>
<P>The <B>'-M'</B> or <B>'--mri'</B> option selects MRI compatibility mode. This
changes the syntax and pseudo-op handling of <CODE>as</CODE> to make it
compatible with the <CODE>ASM68K</CODE> assembler from Microtec Research. The exact nature of the
MRI syntax will not be documented here; see the MRI manuals for more
information. Note in particular that the handling of macros and macro
arguments is somewhat different. The purpose of this option is to permit
assembling existing MRI assembler code using <CODE>as</CODE>.
<BR><BR>
The MRI compatibility is not complete. Certain operations of the MRI assembler
depend upon its object file format, and can not be supported using other object
file formats. Supporting these would require enhancing each object file format
individually. These are:</P>
<UL>
<LI><P>global symbols in common section
The m68k MRI assembler supports common sections which are merged by the linker.
Other object file formats do not support this. <CODE>as</CODE> handles
common sections by treating them as a single common symbol. It permits local
symbols to be defined within a common section, but it can not support global
symbols, since it has no way to describe them.
</P></LI>
<LI><P>complex relocations
The MRI assemblers support relocations against a negated section address, and
relocations which combine the start addresses of two or more sections. These
are not support by other object file formats.
</P></LI>
<LI><P><CODE>END</CODE> pseudo-op specifying start address
The MRI <CODE>END</CODE> pseudo-op permits the specification of a start address.
This is not supported by other object file formats. The start address may
instead be specified using the <B>'-e'</B> option to the linker, or in a linker
script.
</P></LI>
<LI><P><CODE>IDNT</CODE>, <CODE>.ident</CODE> and <CODE>NAME</CODE> pseudo-ops
The MRI <CODE>IDNT</CODE>, <CODE>.ident</CODE> and <CODE>NAME</CODE> pseudo-ops assign a module
name to the output file. This is not supported by other object file formats.
</P></LI>
<LI><P><CODE>ORG</CODE> pseudo-op
The m68k MRI <CODE>ORG</CODE> pseudo-op begins an absolute section at a given
address. This differs from the usual <CODE>as</CODE> <CODE>.org</CODE> pseudo-op,
which changes the location within the current section. Absolute sections are
not supported by other object file formats. The address of a section may be
assigned within a linker script.</P></LI>
</UL>
<P>There are some other features of the MRI assembler which are not supported by
<CODE>as</CODE>, typically either because they are difficult or because they
seem of little consequence. Some of these may be supported in future releases.</P>
<UL>
<LI><P>EBCDIC strings
EBCDIC strings are not supported.
</P></LI>
<LI><P>packed binary coded decimal
Packed binary coded decimal is not supported. This means that the <CODE>DC.P</CODE>
and <CODE>DCB.P</CODE> pseudo-ops are not supported.
</P></LI>
<LI><P><CODE>FEQU</CODE> pseudo-op
The m68k <CODE>FEQU</CODE> pseudo-op is not supported.
</P></LI>
<LI><P><CODE>NOOBJ</CODE> pseudo-op
The m68k <CODE>NOOBJ</CODE> pseudo-op is not supported.
</P></LI>
<LI><P><CODE>OPT</CODE> branch control options
The m68k <CODE>OPT</CODE> branch control options - <CODE>B</CODE>, <CODE>BRS</CODE>, <CODE>BRB</CODE>,
<CODE>BRL</CODE>, and <CODE>BRW</CODE> - are ignored. <CODE>as</CODE> automatically
relaxes all branches, whether forward or backward, to an appropriate size, so
these options serve no purpose.
</P></LI>
<LI><P><CODE>OPT</CODE> list control options
The following m68k <CODE>OPT</CODE> list control options are ignored: <CODE>C</CODE>,
<CODE>CEX</CODE>, <CODE>CL</CODE>, <CODE>CRE</CODE>, <CODE>E</CODE>, <CODE>G</CODE>, <CODE>I</CODE>, <CODE>M</CODE>,
<CODE>MEX</CODE>, <CODE>MC</CODE>, <CODE>MD</CODE>, <CODE>X</CODE>.
</P></LI>
<LI><P>other <CODE>OPT</CODE> options
The following m68k <CODE>OPT</CODE> options are ignored: <CODE>NEST</CODE>, <CODE>O</CODE>,
<CODE>OLD</CODE>, <CODE>OP</CODE>, <CODE>P</CODE>, <CODE>PCO</CODE>, <CODE>PCR</CODE>, <CODE>PCS</CODE>, <CODE>R</CODE>.
</P></LI>
<LI><P><CODE>OPT</CODE> <CODE>D</CODE> option is default
The m68k <CODE>OPT</CODE> <CODE>D</CODE> option is the default, unlike the MRI assembler.
<CODE>OPT NOD</CODE> may be used to turn it off.
</P></LI>
<LI><P><CODE>XREF</CODE> pseudo-op.
The m68k <CODE>XREF</CODE> pseudo-op is ignored.
</P></LI>
<LI><P><CODE>.debug</CODE> pseudo-op
The i960 <CODE>.debug</CODE> pseudo-op is not supported.
</P></LI>
<LI><P><CODE>.extended</CODE> pseudo-op
The i960 <CODE>.extended</CODE> pseudo-op is not supported.
</P></LI>
<LI><P><CODE>.list</CODE> pseudo-op.
The various options of the i960 <CODE>.list</CODE> pseudo-op are not supported.
</P></LI>
<LI><P><CODE>.optimize</CODE> pseudo-op
The i960 <CODE>.optimize</CODE> pseudo-op is not supported.
</P></LI>
<LI><P><CODE>.output</CODE> pseudo-op
The i960 <CODE>.output</CODE> pseudo-op is not supported.
</P></LI>
<LI><P><CODE>.setreal</CODE> pseudo-op
The i960 <CODE>.setreal</CODE> pseudo-op is not supported.</P></LI>
</UL>
<HR>
<H2><A NAME="SEC20"><U>GNU Assembler Input and Output</U></A></H2>
<UL>
<LI><B><A HREF="#SEC21">Input Files</A></B>
<LI><B><A HREF="#SEC23">Output (Object) File</A></B>
<LI><B><A HREF="#SEC24">Assembler Error and Warning Messages</A></B>
</UL>
<H3><A NAME="SEC21"><U>Input Files</U></A></H3>
<P>We use the phrase <U>source program</U>, abbreviated <U>source</U>, to
describe the program input to one run of <CODE>as</CODE>. The program may
be in one or more files; how the source is partitioned into files
doesn't change the meaning of the source.
<BR><BR>
The source program is a concatenation of the text in all the files, in the
order specified.
<BR><BR>
Each time you run <CODE>as</CODE> it assembles exactly one source
program. The source program is made up of one or more files.
(The standard input is also a file.)
<BR><BR>
You give <CODE>as</CODE> a command line that has zero or more input file
names. The input files are read (from left file name to right). A
command line argument (in any position) that has no special meaning
is taken to be an input file name.
<BR><BR>
If you give <CODE>as</CODE> no file names it attempts to read one input file
from the <CODE>as</CODE> standard input, which is normally your terminal. You
may have to type <CODE>Ctrl-D</CODE> to tell <CODE>as</CODE> there is no more program
to assemble.
<BR><BR>
Use <CODE>--</CODE> if you need to explicitly name the standard input file
in your command line.
<BR><BR>
If the source is empty, <CODE>as</CODE> produces a small, empty object
file.</P>
<UL>
<LI><B><A HREF="#SEC22">Assembler File Names and Line Numbers</A></B>
</UL>
<H4><A NAME="SEC22"><U>Assembler File Names and Line Numbers</U></A></H4>
<P>There are two ways of locating a line in the input file (or files) and
either may be used in reporting error messages. One way refers to a line
number in a physical file; the other refers to a line number in a
"logical" file. See <A HREF="#SEC24">Error and Warning Messages</A>.
<BR><BR>
<U>Physical files</U> are those files named in the command line given
to <CODE>as</CODE>.
<BR><BR>
<U>Logical files</U> are simply names declared explicitly by assembler
directives; they bear no relation to physical files. Logical file names help
error messages reflect the original source file, when <CODE>as</CODE> source
is itself synthesized from other files. <CODE>as</CODE> understands the
<CODE>#</CODE> directives emitted by the <CODE>gcc</CODE> preprocessor. See also
<CODE><A HREF="#SEC90">.file</A></CODE>.</P>
<H3><A NAME="SEC23"><U>Output (Object) File</U></A></H3>
<P>Every time you run <CODE>as</CODE>, it produces an output file, which is
your assembly language program translated into numbers. This file
is the object file. Its default name is
<CODE>a.out</CODE>.
You can give it another name by using the <B>'-o'</B> option. Conventionally,
object file names end with <CODE>.o</CODE>. The default name is used for historical
reasons: older assemblers were capable of assembling self-contained programs
directly into a runnable program. (For some formats, this isn't currently
possible, but it can be done for the <CODE>a.out</CODE> format.)
<BR><BR>
The object file is meant for input to the linker <CODE>ld</CODE>. It contains
assembled program code, information to help <CODE>ld</CODE> integrate
the assembled program into a runnable file, and (optionally) symbolic
information for the debugger.</P>
<H3><A NAME="SEC24"><U>Assembler Error and Warning Messages</U></A></H3>
<P><CODE>as</CODE> may write warnings and error messages to the standard error
file (usually your terminal). This should not happen when a compiler
runs <CODE>as</CODE> automatically. Warnings report an assumption made so
that <CODE>as</CODE> could keep assembling a flawed program; errors report a
grave problem that stops the assembly.
<BR><BR>
Warning messages have the format</P>
<PRE>file_name:<I>NNN</I>:Warning Message Text
</PRE>
<P>(where <I>NNN</I> is a line number). If a logical file name has been given
(see <CODE><A HREF="#SEC90">.file</A></CODE>) it is used for the filename, otherwise the name of
the current input file is used. If a logical line number was given
(see <CODE><A HREF="#SEC103">.line</A></CODE>)
then it is used to calculate the number printed,
otherwise the actual line in the current source file is printed. The
message text is intended to be self explanatory (in the grand Unix
tradition).
<BR><BR>
Error messages have the format</P>
<PRE>file_name:<I>NNN</I>:FATAL:Error Message Text
</PRE>
<P>The file name and line number are derived as for warning
messages. The actual message text may be rather less explanatory
because many of them aren't supposed to happen.</P>
<HR>
<H2><A NAME="SEC25"><U>GNU Assembler Syntax</U></A></H2>
<P>The machine-independent syntax used by the GNU assembler is similar to what many other
assemblers use; it is inspired by the BSD 4.2
assembler.
Motorola-specific features are explained at the end of this chapter.</P>
<UL>
<LI><B><A HREF="#SEC26">Preprocessing</A></B>
<LI><B><A HREF="#SEC27">Whitespace</A></B>
<LI><B><A HREF="#SEC28">Comments</A></B>
<LI><B><A HREF="#SEC29">Symbols</A></B>
<LI><B><A HREF="#SEC30">Statements</A></B>
<LI><B><A HREF="#SEC31">Constants</A></B>
<LI><B><A HREF="#SEC214">Motorola 680x0 Dependent Features</A></B>
</UL>
<H3><A NAME="SEC26"><U>Preprocessing</U></A></H3>
<P>The <CODE>as</CODE> internal preprocessor:</P>
<UL>
<LI><P>adjusts and removes extra whitespace. It leaves one space or tab before
the keywords on a line, and turns any other whitespace on the line into
a single space.
</P></LI>
<LI><P>removes all comments, replacing them with a single space, or an
appropriate number of newlines.
</P></LI>
<LI><P>converts character constants into the appropriate numeric values.</P></LI>
</UL>
<P>It does not do macro processing, include file handling, or
anything else you may get from your C compiler's preprocessor. You can
do include file processing with the <CODE>.include</CODE> directive
(see <CODE><A HREF="#SEC97">.include</A></CODE>). You can use the GNU C compiler driver
to get other "CPP" style preprocessing by giving the input file a
<CODE>.S</CODE> suffix. See <A HREF="comopts.html#SEC4">Options Controlling the Kind of
Output, gcc.info, Using GNU CC</A>.
<BR><BR>
Excess whitespace, comments, and character constants
cannot be used in the portions of the input text that are not
preprocessed.
<BR><BR>
If the first line of an input file is <CODE>#NO_APP</CODE> or if you use the
<B>'-f'</B> option, whitespace and comments are not removed from the input file.
Within an input file, you can ask for whitespace and comment removal in
specific portions of the by putting a line that says <CODE>#APP</CODE> before the
text that may contain whitespace or comments, and putting a line that says
<CODE>#NO_APP</CODE> after this text. This feature is mainly intend to support
<CODE>asm</CODE> statements in compilers whose output is otherwise free of comments
and whitespace.</P>
<H3><A NAME="SEC27"><U>Whitespace</U></A></H3>
<P><U>Whitespace</U> is one or more blanks or tabs, in any order.
Whitespace is used to separate symbols, and to make programs neater for
people to read. Unless within character constants
(see <A HREF="#SEC32">Character Constants</A>), any whitespace means the same
as exactly one space.</P>
<H3><A NAME="SEC28"><U>Comments</U></A></H3>
<P>There are two ways of rendering comments to <CODE>as</CODE>. In both
cases the comment is equivalent to one space.
<BR><BR>
Anything from <CODE>/*</CODE> through the next <CODE>*/</CODE> is a comment.
This means you may not nest these comments.</P>
<PRE>/*
The only way to include a newline ('\n') in a comment
is to use this sort of comment.
*/
/* This sort of comment does not nest. */
</PRE>
<P>Anything from the <U>line comment</U> character to the next newline
is considered a comment and is ignored. The line comment character is
<CODE>|</CODE> on the 680x0 family of processors.
<BR><BR>
To be compatible with past assemblers, lines that begin with <CODE>#</CODE> have a
special interpretation. Following the <CODE>#</CODE> should be an absolute
expression (see <A HREF="#SEC60">Expressions</A>): the logical line number of the <I>next</I>
line. Then a string (see <A HREF="#SEC33">Strings</A>) is allowed: if present it is a
new logical file name. The rest of the line, if any, should be whitespace.
<BR><BR>
If the first non-whitespace characters on the line are not numeric,
the line is ignored. (Just like a comment.)</P>
<PRE> # This is an ordinary comment.
# 42-6 "new_file_name" # New logical file name
# This is logical line # 36.
</PRE>
<P>This feature is deprecated, and may disappear from future versions
of <CODE>as</CODE>.</P>
<H3><A NAME="SEC29"><U>Symbols</U></A></H3>
<P>A <U>symbol</U> is one or more characters chosen from the set of all
letters (both upper and lower case), digits and the three characters
<CODE>_.$</CODE>.
No symbol may begin with a digit. Case is significant.
There is no length limit: all characters are significant. Symbols are
delimited by characters not in that set, or by the beginning of a file
(since the source program must end with a newline, the end of a file is
not a possible symbol delimiter). See <A HREF="#SEC45">Symbols</A>.</P>
<H3><A NAME="SEC30"><U>Statements</U></A></H3>
<P>A <U>statement</U> ends at a newline character (<CODE>\n</CODE>) or at a
semicolon (<CODE>;</CODE>). The newline or semicolon is considered part of
the preceding statement. Newlines and semicolons within character
constants are an exception: they do not end statements.
<BR><BR>
It is an error to end any statement with end-of-file: the last
character of any input file should be a newline.
An empty statement is allowed, and may include whitespace. It is ignored.
<BR><BR>
A statement begins with zero or more labels, optionally followed by a
key symbol which determines what kind of statement it is. The key
symbol determines the syntax of the rest of the statement. If the
symbol begins with a dot <CODE>.</CODE> then the statement is an assembler
directive: typically valid for any computer. If the symbol begins with
a letter the statement is an assembly language <U>instruction</U>: it
assembles into a machine language instruction.
A label is a symbol immediately followed by a colon (<CODE>:</CODE>).
Whitespace before a label or after a colon is permitted, but you may not
have whitespace between a label's symbol and its colon. See <A HREF="#SEC46">Labels</A>.</P>
<PRE>label: .directive followed by something
another_label: # This is an empty statement.
instruction operand_1, operand_2, ...
</PRE>
<H3><A NAME="SEC31"><U>Constants</U></A></H3>
<P>A constant is a number, written so that its value is known by
inspection, without knowing any context. Like this:</P>
<PRE>.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
.ascii "Ring the bell\7" # A string constant.
.octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
.float 0f-314159265358979323846264338327\
95028841971.693993751E-40 # - pi, a flonum.
</PRE>
<UL>
<LI><B><A HREF="#SEC32">Character Constants</A></B>
<LI><B><A HREF="#SEC35">Number Constants</A></B>
</UL>
<H4><A NAME="SEC32"><U>Character Constants</U></A></H4>
<P>There are two kinds of character constants. A <U>character</U> stands
for one character in one byte and its value may be used in
numeric expressions. String constants (properly called string
<I>literals</I>) are potentially many bytes and their values may not be
used in arithmetic expressions.</P>
<UL>
<LI><B><A HREF="#SEC33">Strings</A></B>
<LI><B><A HREF="#SEC34">Characters</A></B>
</UL>
<H5><A NAME="SEC33"><U>Strings</U></A></H5>
<P>A <U>string</U> is written between double-quotes. It may contain
double-quotes or null characters. The way to get special characters
into a string is to <U>escape</U> these characters: precede them with
a backslash <CODE>\</CODE> character. For example <CODE>\\</CODE> represents
one backslash: the first <CODE>\</CODE> is an escape which tells
<CODE>as</CODE> to interpret the second character literally as a backslash
(which prevents <CODE>as</CODE> from recognizing the second <CODE>\</CODE> as an
escape character). The complete list of escapes follows.</P>
<DL>
<DT><P><B>\b</B></P><DD><P>Mnemonic for backspace; for ASCII this is octal code 010.
</P><DT><P><B>\f</B></P><DD><P>Mnemonic for FormFeed; for ASCII this is octal code 014.
</P><DT><P><B>\n</B></P><DD><P>Mnemonic for newline; for ASCII this is octal code 012.
</P><DT><P><B>\r</B></P><DD><P>Mnemonic for carriage-Return; for ASCII this is octal code 015.
</P><DT><P><B>\t</B></P><DD><P>Mnemonic for horizontal Tab; for ASCII this is octal code 011.
</P><DT><P><B>\ <I>digit</I> <I>digit</I> <I>digit</I></B></P><DD><P>An octal character code. The numeric code is 3 octal digits.
For compatibility with other Unix systems, 8 and 9 are accepted as digits:
for example, <CODE>\008</CODE> has the value 010, and <CODE>\009</CODE> the value 011.
</P><DT><P><B>\x <I>hex-digits...</I></B></P><DD><P>A hex character code. All trailing hex digits are combined. Either upper or
lower case <CODE>x</CODE> works.
</P><DT><P><B>\\</B></P><DD><P>Represents one <CODE>\</CODE> character.
</P><DT><P><B>\"</B></P><DD><P>Represents one <CODE>"</CODE> character. Needed in strings to represent
this character, because an unescaped <CODE>"</CODE> would end the string.
</P><DT><P><B>\ <I>anything-else</I></B></P><DD><P>Any other character when escaped by <CODE>\</CODE> gives a warning, but
assembles as if the <CODE>\</CODE> was not present. The idea is that if
you used an escape sequence you clearly didn't want the literal
interpretation of the following character. However <CODE>as</CODE> has no
other interpretation, so <CODE>as</CODE> knows it is giving you the wrong
code and warns you of the fact.</P>
</DL>
<P>Which characters are escapable, and what those escapes represent,
varies widely among assemblers. The current set is what we think
the BSD 4.2 assembler recognizes, and is a subset of what most C
compilers recognize. If you are in doubt, do not use an escape
sequence.</P>
<H5><A NAME="SEC34"><U>Characters</U></A></H5>
<P>A single character may be written as a single quote immediately
followed by that character. The same escapes apply to characters as
to strings. So if you want to write the character backslash, you
must write <CODE>'\\</CODE> where the first <CODE>\</CODE> escapes the second
<CODE>\</CODE>. As you can see, the quote is an acute accent, not a
grave accent. A newline
(or semicolon <CODE>;</CODE>)
immediately following an acute accent is taken as a literal character
and does not count as the end of a statement. The value of a character
constant in a numeric expression is the machine's byte-wide code for
that character. <CODE>as</CODE> assumes your character code is ASCII:
<CODE>'A</CODE> means 65, <CODE>'B</CODE> means 66, and so on.</P>
<H4><A NAME="SEC35"><U>Number Constants</U></A></H4>
<P><CODE>as</CODE> distinguishes three kinds of numbers according to how they
are stored in the target machine. <I>Integers</I> are numbers that
would fit into an <CODE>int</CODE> in the C language. <I>Bignums</I> are
integers, but they are stored in more than 32 bits. <I>Flonums</I>
are floating point numbers, described below.</P>
<UL>
<LI><B><A HREF="#SEC36">Integers</A></B>
<LI><B><A HREF="#SEC37">Bignums</A></B>
<LI><B><A HREF="#SEC38">Flonums</A></B>
</UL>
<H5><A NAME="SEC36"><U>Integers</U></A></H5>
<P>A binary integer is <CODE>0b</CODE> or <CODE>0B</CODE> followed by zero or more of
the binary digits <CODE>01</CODE>.
<BR><BR>
An octal integer is <CODE>0</CODE> followed by zero or more of the octal
digits (<CODE>01234567</CODE>).
<BR><BR>
A decimal integer starts with a non-zero digit followed by zero or
more digits (<CODE>0123456789</CODE>).
<BR><BR>
A hexadecimal integer is <CODE>0x</CODE> or <CODE>0X</CODE> followed by one or
more hexadecimal digits chosen from <CODE>0123456789abcdefABCDEF</CODE>.
<BR><BR>
Integers have the usual values. To denote a negative integer, use
the prefix operator <CODE>-</CODE> discussed under expressions
(see <A HREF="#SEC65">Prefix Operators</A>).</P>
<H5><A NAME="SEC37"><U>Bignums</U></A></H5>
<P>A <U>bignum</U> has the same syntax and semantics as an integer
except that the number (or its negative) takes more than 32 bits to
represent in binary. The distinction is made because in some places
integers are permitted while bignums are not.</P>
<H5><A NAME="SEC38"><U>Flonums</U></A></H5>
<P>A <U>flonum</U> represents a floating point number. The translation is
indirect: a decimal floating point number from the text is converted by
<CODE>as</CODE> to a generic binary floating point number of more than
sufficient precision. This generic floating point number is converted
to a particular computer's floating point format (or formats) by a
portion of <CODE>as</CODE> specialized to that computer.
The version of <CODE>as</CODE> used by GCC4TI does not use TI's SMAP II BCD
format; it emits standard IEEE floating point numbers.
It would be pointless to implement the correct behavior, since the appropriate
numbers are easy to write, and converting between base 2 and 10 can
decrease precision.
<BR><BR>
A flonum is written by writing (in order)</P>
<UL>
<LI><P>The digit <CODE>0</CODE>.
</P></LI>
<LI><P>A letter, to tell <CODE>as</CODE> the rest of the number is a flonum.
</P></LI>
<LI><P>An optional sign: either <CODE>+</CODE> or <CODE>-</CODE>.
</P></LI>
<LI><P>An optional <U>integer part</U>: zero or more decimal digits.
</P></LI>
<LI><P>An optional <U>fractional part</U>: <CODE>.</CODE> followed by zero
or more decimal digits.
</P></LI>
<LI><P>An optional exponent, consisting of:</P>
<UL>
<LI><P>An <CODE>E</CODE> or <CODE>e</CODE>.
</P></LI>
<LI><P>Optional sign: either <CODE>+</CODE> or <CODE>-</CODE>.
</P></LI>
<LI><P>One or more decimal digits.</P></LI>
</UL>
</LI>
</UL>
<P>At least one of the integer part or the fractional part must be
present. The floating point number has the usual base-10 value.
<BR><BR>
<CODE>as</CODE> does all processing using integers. Flonums are computed
independently of any floating point hardware in the computer running
<CODE>as</CODE>.</P>
<H3><A NAME="SEC214"><U>Motorola 680x0 Dependent Features</U></A></H3>
<P>In this configuration of <CODE>as</CODE> (which does not prepend
an underscore to the names of user variables), the
assembler requires a <CODE>'%'</CODE> before any use of a register name. This
is intended to let the assembler distinguish between C variables and
functions named <CODE>'a0'</CODE> through <CODE>'a7'</CODE>, and so on.
<BR><BR>
Two different syntaxes for the Motorola 680x0 are widely used.
The first one was developed at MIT. The second one is the
standard Motorola syntax for this chip, and it differs from the MIT syntax.
<CODE>as</CODE> can accept Motorola syntax for operands, even if MIT syntax
is used for other operands in the same instruction. The two kinds of syntax are
fully compatible.</P>
<UL>
<LI><B><A HREF="#SEC216">MIT Syntax</A></B>
<LI><B><A HREF="#SEC217">Motorola Syntax</A></B>
<LI><B><A HREF="#SEC221">Branch Improvement</A></B>
<LI><B><A HREF="#SEC222">Special Characters</A></B>
</UL>
<H4><A NAME="SEC216"><U>MIT Syntax</U></A></H4>
<P>The MIT syntax uses instructions names and
syntax compatible with the Sun assembler. Intervening periods are
ignored; for example, <CODE>movl</CODE> is equivalent to <CODE>mov.l</CODE>.
<BR><BR>
In the following table, <I>apc</I> stands for any of the address registers