Merge branch 'vendor/OPENSSL'
[dragonfly.git] / contrib / binutils-2.24 / gas / doc / as.texinfo
1 \input texinfo @c                               -*-Texinfo-*-
2 @c  Copyright 1991-2013 Free Software Foundation, Inc.
3 @c UPDATE!!  On future updates--
4 @c   (1)   check for new machine-dep cmdline options in
5 @c         md_parse_option definitions in config/tc-*.c
6 @c   (2)   for platform-specific directives, examine md_pseudo_op
7 @c         in config/tc-*.c
8 @c   (3)   for object-format specific directives, examine obj_pseudo_op
9 @c         in config/obj-*.c
10 @c   (4)   portable directives in potable[] in read.c
11 @c %**start of header
12 @setfilename as.info
13 @c ---config---
14 @macro gcctabopt{body}
15 @code{\body\}
16 @end macro
17 @c defaults, config file may override:
18 @set have-stabs
19 @c ---
20 @c man begin NAME
21 @c ---
22 @include asconfig.texi
23 @include bfdver.texi
24 @c ---
25 @c man end
26 @c ---
27 @c common OR combinations of conditions
28 @ifset COFF
29 @set COFF-ELF
30 @end ifset
31 @ifset ELF
32 @set COFF-ELF
33 @end ifset
34 @ifset AOUT
35 @set aout-bout
36 @end ifset
37 @ifset ARM/Thumb
38 @set ARM
39 @end ifset
40 @ifset Blackfin
41 @set Blackfin
42 @end ifset
43 @ifset BOUT
44 @set aout-bout
45 @end ifset
46 @ifset H8/300
47 @set H8
48 @end ifset
49 @ifset SH
50 @set H8
51 @end ifset
52 @ifset HPPA
53 @set abnormal-separator
54 @end ifset
55 @c ------------
56 @ifset GENERIC
57 @settitle Using @value{AS}
58 @end ifset
59 @ifclear GENERIC
60 @settitle Using @value{AS} (@value{TARGET})
61 @end ifclear
62 @setchapternewpage odd
63 @c %**end of header
64
65 @c @smallbook
66 @c @set SMALL
67 @c WARE! Some of the machine-dependent sections contain tables of machine
68 @c instructions.  Except in multi-column format, these tables look silly.
69 @c Unfortunately, Texinfo doesn't have a general-purpose multi-col format, so
70 @c the multi-col format is faked within @example sections.
71 @c
72 @c Again unfortunately, the natural size that fits on a page, for these tables,
73 @c is different depending on whether or not smallbook is turned on.
74 @c This matters, because of order: text flow switches columns at each page
75 @c break.
76 @c
77 @c The format faked in this source works reasonably well for smallbook,
78 @c not well for the default large-page format.  This manual expects that if you
79 @c turn on @smallbook, you will also uncomment the "@set SMALL" to enable the
80 @c tables in question.  You can turn on one without the other at your
81 @c discretion, of course.
82 @ifinfo
83 @set SMALL
84 @c the insn tables look just as silly in info files regardless of smallbook,
85 @c might as well show 'em anyways.
86 @end ifinfo
87
88 @ifnottex
89 @dircategory Software development
90 @direntry
91 * As: (as).                     The GNU assembler.
92 * Gas: (as).                    The GNU assembler.
93 @end direntry
94 @end ifnottex
95
96 @finalout
97 @syncodeindex ky cp
98
99 @copying
100 This file documents the GNU Assembler "@value{AS}".
101
102 @c man begin COPYRIGHT
103 Copyright @copyright{} 1991-2013 Free Software Foundation, Inc.
104
105 Permission is granted to copy, distribute and/or modify this document
106 under the terms of the GNU Free Documentation License, Version 1.3
107 or any later version published by the Free Software Foundation;
108 with no Invariant Sections, with no Front-Cover Texts, and with no
109 Back-Cover Texts.  A copy of the license is included in the
110 section entitled ``GNU Free Documentation License''.
111
112 @c man end
113 @end copying
114
115 @titlepage
116 @title Using @value{AS}
117 @subtitle The @sc{gnu} Assembler
118 @ifclear GENERIC
119 @subtitle for the @value{TARGET} family
120 @end ifclear
121 @ifset VERSION_PACKAGE
122 @sp 1
123 @subtitle @value{VERSION_PACKAGE}
124 @end ifset
125 @sp 1
126 @subtitle Version @value{VERSION}
127 @sp 1
128 @sp 13
129 The Free Software Foundation Inc.@: thanks The Nice Computer
130 Company of Australia for loaning Dean Elsner to write the
131 first (Vax) version of @command{as} for Project @sc{gnu}.
132 The proprietors, management and staff of TNCCA thank FSF for
133 distracting the boss while they got some work
134 done.
135 @sp 3
136 @author Dean Elsner, Jay Fenlason & friends
137 @page
138 @tex
139 {\parskip=0pt
140 \hfill {\it Using {\tt @value{AS}}}\par
141 \hfill Edited by Cygnus Support\par
142 }
143 %"boxit" macro for figures:
144 %Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
145 \gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
146      \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
147 #2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
148 \gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
149 @end tex
150
151 @vskip 0pt plus 1filll
152 Copyright @copyright{} 1991-2013 Free Software Foundation, Inc.
153
154       Permission is granted to copy, distribute and/or modify this document
155       under the terms of the GNU Free Documentation License, Version 1.3
156       or any later version published by the Free Software Foundation;
157       with no Invariant Sections, with no Front-Cover Texts, and with no
158       Back-Cover Texts.  A copy of the license is included in the
159       section entitled ``GNU Free Documentation License''.
160
161 @end titlepage
162 @contents
163
164 @ifnottex
165 @node Top
166 @top Using @value{AS}
167
168 This file is a user guide to the @sc{gnu} assembler @command{@value{AS}}
169 @ifset VERSION_PACKAGE
170 @value{VERSION_PACKAGE}
171 @end ifset
172 version @value{VERSION}.
173 @ifclear GENERIC
174 This version of the file describes @command{@value{AS}} configured to generate
175 code for @value{TARGET} architectures.
176 @end ifclear
177
178 This document is distributed under the terms of the GNU Free
179 Documentation License.  A copy of the license is included in the
180 section entitled ``GNU Free Documentation License''.
181
182 @menu
183 * Overview::                    Overview
184 * Invoking::                    Command-Line Options
185 * Syntax::                      Syntax
186 * Sections::                    Sections and Relocation
187 * Symbols::                     Symbols
188 * Expressions::                 Expressions
189 * Pseudo Ops::                  Assembler Directives
190 @ifset ELF
191 * Object Attributes::           Object Attributes
192 @end ifset
193 * Machine Dependencies::        Machine Dependent Features
194 * Reporting Bugs::              Reporting Bugs
195 * Acknowledgements::            Who Did What
196 * GNU Free Documentation License::  GNU Free Documentation License
197 * AS Index::                    AS Index
198 @end menu
199 @end ifnottex
200
201 @node Overview
202 @chapter Overview
203 @iftex
204 This manual is a user guide to the @sc{gnu} assembler @command{@value{AS}}.
205 @ifclear GENERIC
206 This version of the manual describes @command{@value{AS}} configured to generate
207 code for @value{TARGET} architectures.
208 @end ifclear
209 @end iftex
210
211 @cindex invocation summary
212 @cindex option summary
213 @cindex summary of options
214 Here is a brief summary of how to invoke @command{@value{AS}}.  For details,
215 see @ref{Invoking,,Command-Line Options}.
216
217 @c man title AS the portable GNU assembler.
218
219 @ignore
220 @c man begin SEEALSO
221 gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
222 @c man end
223 @end ignore
224
225 @c We don't use deffn and friends for the following because they seem
226 @c to be limited to one line for the header.
227 @smallexample
228 @c man begin SYNOPSIS
229 @value{AS} [@b{-a}[@b{cdghlns}][=@var{file}]] [@b{--alternate}] [@b{-D}]
230  [@b{--compress-debug-sections}]  [@b{--nocompress-debug-sections}]
231  [@b{--debug-prefix-map} @var{old}=@var{new}]
232  [@b{--defsym} @var{sym}=@var{val}] [@b{-f}] [@b{-g}] [@b{--gstabs}]
233  [@b{--gstabs+}] [@b{--gdwarf-2}] [@b{--gdwarf-sections}]
234  [@b{--help}] [@b{-I} @var{dir}] [@b{-J}]
235  [@b{-K}] [@b{-L}] [@b{--listing-lhs-width}=@var{NUM}]
236  [@b{--listing-lhs-width2}=@var{NUM}] [@b{--listing-rhs-width}=@var{NUM}]
237  [@b{--listing-cont-lines}=@var{NUM}] [@b{--keep-locals}] [@b{-o}
238  @var{objfile}] [@b{-R}] [@b{--reduce-memory-overheads}] [@b{--statistics}]
239  [@b{-v}] [@b{-version}] [@b{--version}] [@b{-W}] [@b{--warn}]
240  [@b{--fatal-warnings}] [@b{-w}] [@b{-x}] [@b{-Z}] [@b{@@@var{FILE}}]
241  [@b{--size-check=[error|warning]}]
242  [@b{--target-help}] [@var{target-options}]
243  [@b{--}|@var{files} @dots{}]
244 @c
245 @c Target dependent options are listed below.  Keep the list sorted.
246 @c Add an empty line for separation.
247 @ifset AARCH64
248
249 @emph{Target AArch64 options:}
250    [@b{-EB}|@b{-EL}]
251    [@b{-mabi}=@var{ABI}]
252 @end ifset
253 @ifset ALPHA
254
255 @emph{Target Alpha options:}
256    [@b{-m@var{cpu}}]
257    [@b{-mdebug} | @b{-no-mdebug}]
258    [@b{-replace} | @b{-noreplace}]
259    [@b{-relax}] [@b{-g}] [@b{-G@var{size}}]
260    [@b{-F}] [@b{-32addr}]
261 @end ifset
262 @ifset ARC
263
264 @emph{Target ARC options:}
265    [@b{-marc[5|6|7|8]}]
266    [@b{-EB}|@b{-EL}]
267 @end ifset
268 @ifset ARM
269
270 @emph{Target ARM options:}
271 @c Don't document the deprecated options
272    [@b{-mcpu}=@var{processor}[+@var{extension}@dots{}]]
273    [@b{-march}=@var{architecture}[+@var{extension}@dots{}]]
274    [@b{-mfpu}=@var{floating-point-format}]
275    [@b{-mfloat-abi}=@var{abi}]
276    [@b{-meabi}=@var{ver}]
277    [@b{-mthumb}]
278    [@b{-EB}|@b{-EL}]
279    [@b{-mapcs-32}|@b{-mapcs-26}|@b{-mapcs-float}|
280     @b{-mapcs-reentrant}]
281    [@b{-mthumb-interwork}] [@b{-k}]
282 @end ifset
283 @ifset Blackfin
284
285 @emph{Target Blackfin options:}
286    [@b{-mcpu}=@var{processor}[-@var{sirevision}]]
287    [@b{-mfdpic}]
288    [@b{-mno-fdpic}]
289    [@b{-mnopic}]
290 @end ifset
291 @ifset CRIS
292
293 @emph{Target CRIS options:}
294    [@b{--underscore} | @b{--no-underscore}]
295    [@b{--pic}] [@b{-N}]
296    [@b{--emulation=criself} | @b{--emulation=crisaout}]
297    [@b{--march=v0_v10} | @b{--march=v10} | @b{--march=v32} | @b{--march=common_v10_v32}]
298 @c Deprecated -- deliberately not documented.
299 @c [@b{-h}] [@b{-H}]
300 @end ifset
301 @ifset D10V
302
303 @emph{Target D10V options:}
304    [@b{-O}]
305 @end ifset
306 @ifset D30V
307
308 @emph{Target D30V options:}
309    [@b{-O}|@b{-n}|@b{-N}]
310 @end ifset
311 @ifset EPIPHANY
312
313 @emph{Target EPIPHANY options:}
314    [@b{-mepiphany}|@b{-mepiphany16}]
315 @end ifset
316 @ifset H8
317
318 @emph{Target H8/300 options:}
319    [-h-tick-hex]
320 @end ifset
321 @ifset HPPA
322 @c HPPA has no machine-dependent assembler options (yet).
323 @end ifset
324 @ifset I80386
325
326 @emph{Target i386 options:}
327    [@b{--32}|@b{--x32}|@b{--64}] [@b{-n}]
328    [@b{-march}=@var{CPU}[+@var{EXTENSION}@dots{}]] [@b{-mtune}=@var{CPU}]
329 @end ifset
330 @ifset I960
331
332 @emph{Target i960 options:}
333 @c see md_parse_option in tc-i960.c
334    [@b{-ACA}|@b{-ACA_A}|@b{-ACB}|@b{-ACC}|@b{-AKA}|@b{-AKB}|
335     @b{-AKC}|@b{-AMC}]
336    [@b{-b}] [@b{-no-relax}]
337 @end ifset
338 @ifset IA64
339
340 @emph{Target IA-64 options:}
341    [@b{-mconstant-gp}|@b{-mauto-pic}]
342    [@b{-milp32}|@b{-milp64}|@b{-mlp64}|@b{-mp64}]
343    [@b{-mle}|@b{mbe}]
344    [@b{-mtune=itanium1}|@b{-mtune=itanium2}]
345    [@b{-munwind-check=warning}|@b{-munwind-check=error}]
346    [@b{-mhint.b=ok}|@b{-mhint.b=warning}|@b{-mhint.b=error}]
347    [@b{-x}|@b{-xexplicit}] [@b{-xauto}] [@b{-xdebug}]
348 @end ifset
349 @ifset IP2K
350
351 @emph{Target IP2K options:}
352    [@b{-mip2022}|@b{-mip2022ext}]
353 @end ifset
354 @ifset M32C
355
356 @emph{Target M32C options:}
357    [@b{-m32c}|@b{-m16c}] [-relax] [-h-tick-hex]
358 @end ifset
359 @ifset M32R
360
361 @emph{Target M32R options:}
362    [@b{--m32rx}|@b{--[no-]warn-explicit-parallel-conflicts}|
363    @b{--W[n]p}]
364 @end ifset
365 @ifset M680X0
366
367 @emph{Target M680X0 options:}
368    [@b{-l}] [@b{-m68000}|@b{-m68010}|@b{-m68020}|@dots{}]
369 @end ifset
370 @ifset M68HC11
371
372 @emph{Target M68HC11 options:}
373    [@b{-m68hc11}|@b{-m68hc12}|@b{-m68hcs12}|@b{-mm9s12x}|@b{-mm9s12xg}]
374    [@b{-mshort}|@b{-mlong}]
375    [@b{-mshort-double}|@b{-mlong-double}]
376    [@b{--force-long-branches}] [@b{--short-branches}]
377    [@b{--strict-direct-mode}] [@b{--print-insn-syntax}]
378    [@b{--print-opcodes}] [@b{--generate-example}]
379 @end ifset
380 @ifset MCORE
381
382 @emph{Target MCORE options:}
383    [@b{-jsri2bsr}] [@b{-sifilter}] [@b{-relax}]
384    [@b{-mcpu=[210|340]}]
385 @end ifset
386 @ifset METAG
387
388 @emph{Target Meta options:}
389    [@b{-mcpu=@var{cpu}}] [@b{-mfpu=@var{cpu}}] [@b{-mdsp=@var{cpu}}]
390 @end ifset
391 @ifset MICROBLAZE
392 @emph{Target MICROBLAZE options:}
393 @c MicroBlaze has no machine-dependent assembler options.
394 @end ifset
395 @ifset MIPS
396
397 @emph{Target MIPS options:}
398    [@b{-nocpp}] [@b{-EL}] [@b{-EB}] [@b{-O}[@var{optimization level}]]
399    [@b{-g}[@var{debug level}]] [@b{-G} @var{num}] [@b{-KPIC}] [@b{-call_shared}]
400    [@b{-non_shared}] [@b{-xgot} [@b{-mvxworks-pic}]
401    [@b{-mabi}=@var{ABI}] [@b{-32}] [@b{-n32}] [@b{-64}] [@b{-mfp32}] [@b{-mgp32}]
402    [@b{-march}=@var{CPU}] [@b{-mtune}=@var{CPU}] [@b{-mips1}] [@b{-mips2}]
403    [@b{-mips3}] [@b{-mips4}] [@b{-mips5}] [@b{-mips32}] [@b{-mips32r2}]
404    [@b{-mips64}] [@b{-mips64r2}]
405    [@b{-construct-floats}] [@b{-no-construct-floats}]
406    [@b{-mnan=@var{encoding}}]
407    [@b{-trap}] [@b{-no-break}] [@b{-break}] [@b{-no-trap}]
408    [@b{-mips16}] [@b{-no-mips16}]
409    [@b{-mmicromips}] [@b{-mno-micromips}]
410    [@b{-msmartmips}] [@b{-mno-smartmips}]
411    [@b{-mips3d}] [@b{-no-mips3d}]
412    [@b{-mdmx}] [@b{-no-mdmx}]
413    [@b{-mdsp}] [@b{-mno-dsp}]
414    [@b{-mdspr2}] [@b{-mno-dspr2}]
415    [@b{-mmt}] [@b{-mno-mt}]
416    [@b{-mmcu}] [@b{-mno-mcu}]
417    [@b{-minsn32}] [@b{-mno-insn32}]
418    [@b{-mfix7000}] [@b{-mno-fix7000}]
419    [@b{-mfix-vr4120}] [@b{-mno-fix-vr4120}]
420    [@b{-mfix-vr4130}] [@b{-mno-fix-vr4130}]
421    [@b{-mdebug}] [@b{-no-mdebug}]
422    [@b{-mpdr}] [@b{-mno-pdr}]
423 @end ifset
424 @ifset MMIX
425
426 @emph{Target MMIX options:}
427    [@b{--fixed-special-register-names}] [@b{--globalize-symbols}]
428    [@b{--gnu-syntax}] [@b{--relax}] [@b{--no-predefined-symbols}]
429    [@b{--no-expand}] [@b{--no-merge-gregs}] [@b{-x}]
430    [@b{--linker-allocated-gregs}]
431 @end ifset
432 @ifset NIOSII
433
434 @emph{Target Nios II options:}
435    [@b{-relax-all}] [@b{-relax-section}] [@b{-no-relax}]
436    [@b{-EB}] [@b{-EL}]
437 @end ifset
438 @ifset PDP11
439
440 @emph{Target PDP11 options:}
441    [@b{-mpic}|@b{-mno-pic}] [@b{-mall}] [@b{-mno-extensions}]
442    [@b{-m}@var{extension}|@b{-mno-}@var{extension}]
443    [@b{-m}@var{cpu}] [@b{-m}@var{machine}]
444 @end ifset
445 @ifset PJ
446
447 @emph{Target picoJava options:}
448    [@b{-mb}|@b{-me}]
449 @end ifset
450 @ifset PPC
451
452 @emph{Target PowerPC options:}
453    [@b{-a32}|@b{-a64}]
454    [@b{-mpwrx}|@b{-mpwr2}|@b{-mpwr}|@b{-m601}|@b{-mppc}|@b{-mppc32}|@b{-m603}|@b{-m604}|@b{-m403}|@b{-m405}|
455     @b{-m440}|@b{-m464}|@b{-m476}|@b{-m7400}|@b{-m7410}|@b{-m7450}|@b{-m7455}|@b{-m750cl}|@b{-mppc64}|
456     @b{-m620}|@b{-me500}|@b{-e500x2}|@b{-me500mc}|@b{-me500mc64}|@b{-me5500}|@b{-me6500}|@b{-mppc64bridge}|
457     @b{-mbooke}|@b{-mpower4}|@b{-mpwr4}|@b{-mpower5}|@b{-mpwr5}|@b{-mpwr5x}|@b{-mpower6}|@b{-mpwr6}|
458     @b{-mpower7}|@b{-mpwr7}|@b{-mpower8}|@b{-mpwr8}|@b{-ma2}|@b{-mcell}|@b{-mspe}|@b{-mtitan}|@b{-me300}|@b{-mcom}]
459    [@b{-many}] [@b{-maltivec}|@b{-mvsx}|@b{-mhtm}|@b{-mvle}]
460    [@b{-mregnames}|@b{-mno-regnames}]
461    [@b{-mrelocatable}|@b{-mrelocatable-lib}|@b{-K PIC}] [@b{-memb}]
462    [@b{-mlittle}|@b{-mlittle-endian}|@b{-le}|@b{-mbig}|@b{-mbig-endian}|@b{-be}]
463    [@b{-msolaris}|@b{-mno-solaris}]
464    [@b{-nops=@var{count}}]
465 @end ifset
466 @ifset RX
467
468 @emph{Target RX options:}
469    [@b{-mlittle-endian}|@b{-mbig-endian}]
470    [@b{-m32bit-doubles}|@b{-m64bit-doubles}]
471    [@b{-muse-conventional-section-names}]
472    [@b{-msmall-data-limit}]
473    [@b{-mpid}]
474    [@b{-mrelax}]
475    [@b{-mint-register=@var{number}}]
476    [@b{-mgcc-abi}|@b{-mrx-abi}]
477 @end ifset
478 @ifset S390
479
480 @emph{Target s390 options:}
481    [@b{-m31}|@b{-m64}] [@b{-mesa}|@b{-mzarch}] [@b{-march}=@var{CPU}]
482    [@b{-mregnames}|@b{-mno-regnames}]
483    [@b{-mwarn-areg-zero}]
484 @end ifset
485 @ifset SCORE
486
487 @emph{Target SCORE options:}
488    [@b{-EB}][@b{-EL}][@b{-FIXDD}][@b{-NWARN}]
489    [@b{-SCORE5}][@b{-SCORE5U}][@b{-SCORE7}][@b{-SCORE3}]
490    [@b{-march=score7}][@b{-march=score3}]
491    [@b{-USE_R1}][@b{-KPIC}][@b{-O0}][@b{-G} @var{num}][@b{-V}]
492 @end ifset
493 @ifset SPARC
494
495 @emph{Target SPARC options:}
496 @c The order here is important.  See c-sparc.texi.
497    [@b{-Av6}|@b{-Av7}|@b{-Av8}|@b{-Asparclet}|@b{-Asparclite}
498     @b{-Av8plus}|@b{-Av8plusa}|@b{-Av9}|@b{-Av9a}]
499    [@b{-xarch=v8plus}|@b{-xarch=v8plusa}] [@b{-bump}]
500    [@b{-32}|@b{-64}]
501 @end ifset
502 @ifset TIC54X
503
504 @emph{Target TIC54X options:}
505  [@b{-mcpu=54[123589]}|@b{-mcpu=54[56]lp}] [@b{-mfar-mode}|@b{-mf}]
506  [@b{-merrors-to-file} @var{<filename>}|@b{-me} @var{<filename>}]
507 @end ifset
508
509 @ifset TIC6X
510
511 @emph{Target TIC6X options:}
512    [@b{-march=@var{arch}}] [@b{-mbig-endian}|@b{-mlittle-endian}]
513    [@b{-mdsbt}|@b{-mno-dsbt}] [@b{-mpid=no}|@b{-mpid=near}|@b{-mpid=far}]
514    [@b{-mpic}|@b{-mno-pic}]
515 @end ifset
516 @ifset TILEGX
517
518 @emph{Target TILE-Gx options:}
519    [@b{-m32}|@b{-m64}][@b{-EB}][@b{-EL}]
520 @end ifset
521 @ifset TILEPRO
522 @c TILEPro has no machine-dependent assembler options
523 @end ifset
524
525 @ifset XTENSA
526
527 @emph{Target Xtensa options:}
528  [@b{--[no-]text-section-literals}] [@b{--[no-]absolute-literals}]
529  [@b{--[no-]target-align}] [@b{--[no-]longcalls}]
530  [@b{--[no-]transform}]
531  [@b{--rename-section} @var{oldname}=@var{newname}]
532 @end ifset
533
534 @ifset Z80
535
536 @emph{Target Z80 options:}
537   [@b{-z80}] [@b{-r800}]
538   [@b{ -ignore-undocumented-instructions}] [@b{-Wnud}]
539   [@b{ -ignore-unportable-instructions}] [@b{-Wnup}]
540   [@b{ -warn-undocumented-instructions}] [@b{-Wud}]
541   [@b{ -warn-unportable-instructions}] [@b{-Wup}]
542   [@b{ -forbid-undocumented-instructions}] [@b{-Fud}]
543   [@b{ -forbid-unportable-instructions}] [@b{-Fup}]
544 @end ifset
545
546 @ifset Z8000
547 @c Z8000 has no machine-dependent assembler options
548 @end ifset
549
550 @c man end
551 @end smallexample
552
553 @c man begin OPTIONS
554
555 @table @gcctabopt
556 @include at-file.texi
557
558 @item -a[cdghlmns]
559 Turn on listings, in any of a variety of ways:
560
561 @table @gcctabopt
562 @item -ac
563 omit false conditionals
564
565 @item -ad
566 omit debugging directives
567
568 @item -ag
569 include general information, like @value{AS} version and options passed
570
571 @item -ah
572 include high-level source
573
574 @item -al
575 include assembly
576
577 @item -am
578 include macro expansions
579
580 @item -an
581 omit forms processing
582
583 @item -as
584 include symbols
585
586 @item =file
587 set the name of the listing file
588 @end table
589
590 You may combine these options; for example, use @samp{-aln} for assembly
591 listing without forms processing.  The @samp{=file} option, if used, must be
592 the last one.  By itself, @samp{-a} defaults to @samp{-ahls}.
593
594 @item --alternate
595 Begin in alternate macro mode.
596 @ifclear man
597 @xref{Altmacro,,@code{.altmacro}}.
598 @end ifclear
599
600 @item --compress-debug-sections
601 Compress DWARF debug sections using zlib.  The debug sections are renamed
602 to begin with @samp{.zdebug}, and the resulting object file may not be
603 compatible with older linkers and object file utilities.
604
605 @item --nocompress-debug-sections
606 Do not compress DWARF debug sections.  This is the default.
607
608 @item -D
609 Ignored.  This option is accepted for script compatibility with calls to
610 other assemblers.
611
612 @item --debug-prefix-map @var{old}=@var{new}
613 When assembling files in directory @file{@var{old}}, record debugging
614 information describing them as in @file{@var{new}} instead.
615
616 @item --defsym @var{sym}=@var{value}
617 Define the symbol @var{sym} to be @var{value} before assembling the input file.
618 @var{value} must be an integer constant.  As in C, a leading @samp{0x}
619 indicates a hexadecimal value, and a leading @samp{0} indicates an octal
620 value.  The value of the symbol can be overridden inside a source file via the
621 use of a @code{.set} pseudo-op.
622
623 @item -f
624 ``fast''---skip whitespace and comment preprocessing (assume source is
625 compiler output).
626
627 @item -g
628 @itemx --gen-debug
629 Generate debugging information for each assembler source line using whichever
630 debug format is preferred by the target.  This currently means either STABS,
631 ECOFF or DWARF2.
632
633 @item --gstabs
634 Generate stabs debugging information for each assembler line.  This
635 may help debugging assembler code, if the debugger can handle it.
636
637 @item --gstabs+
638 Generate stabs debugging information for each assembler line, with GNU
639 extensions that probably only gdb can handle, and that could make other
640 debuggers crash or refuse to read your program.  This
641 may help debugging assembler code.  Currently the only GNU extension is
642 the location of the current working directory at assembling time.
643
644 @item --gdwarf-2
645 Generate DWARF2 debugging information for each assembler line.  This
646 may help debugging assembler code, if the debugger can handle it.  Note---this
647 option is only supported by some targets, not all of them.
648
649 @item --gdwarf-sections
650 Instead of creating a .debug_line section, create a series of
651 .debug_line.@var{foo} sections where @var{foo} is the name of the
652 corresponding code section.  For example a code section called @var{.text.func}
653 will have its dwarf line number information placed into a section called
654 @var{.debug_line.text.func}.  If the code section is just called @var{.text}
655 then debug line section will still be called just @var{.debug_line} without any
656 suffix.
657
658 @item --size-check=error
659 @itemx --size-check=warning
660 Issue an error or warning for invalid ELF .size directive.
661
662 @item --help
663 Print a summary of the command line options and exit.
664
665 @item --target-help
666 Print a summary of all target specific options and exit.
667
668 @item -I @var{dir}
669 Add directory @var{dir} to the search list for @code{.include} directives.
670
671 @item -J
672 Don't warn about signed overflow.
673
674 @item -K
675 @ifclear DIFF-TBL-KLUGE
676 This option is accepted but has no effect on the @value{TARGET} family.
677 @end ifclear
678 @ifset DIFF-TBL-KLUGE
679 Issue warnings when difference tables altered for long displacements.
680 @end ifset
681
682 @item -L
683 @itemx --keep-locals
684 Keep (in the symbol table) local symbols.  These symbols start with
685 system-specific local label prefixes, typically @samp{.L} for ELF systems
686 or @samp{L} for traditional a.out systems.
687 @ifclear man
688 @xref{Symbol Names}.
689 @end ifclear
690
691 @item --listing-lhs-width=@var{number}
692 Set the maximum width, in words, of the output data column for an assembler
693 listing to @var{number}.
694
695 @item --listing-lhs-width2=@var{number}
696 Set the maximum width, in words, of the output data column for continuation
697 lines in an assembler listing to @var{number}.
698
699 @item --listing-rhs-width=@var{number}
700 Set the maximum width of an input source line, as displayed in a listing, to
701 @var{number} bytes.
702
703 @item --listing-cont-lines=@var{number}
704 Set the maximum number of lines printed in a listing for a single line of input
705 to @var{number} + 1.
706
707 @item -o @var{objfile}
708 Name the object-file output from @command{@value{AS}} @var{objfile}.
709
710 @item -R
711 Fold the data section into the text section.
712
713 @kindex --hash-size=@var{number}
714 Set the default size of GAS's hash tables to a prime number close to
715 @var{number}.  Increasing this value can reduce the length of time it takes the
716 assembler to perform its tasks, at the expense of increasing the assembler's
717 memory requirements.  Similarly reducing this value can reduce the memory
718 requirements at the expense of speed.
719
720 @item --reduce-memory-overheads
721 This option reduces GAS's memory requirements, at the expense of making the
722 assembly processes slower.  Currently this switch is a synonym for
723 @samp{--hash-size=4051}, but in the future it may have other effects as well.
724
725 @item --statistics
726 Print the maximum space (in bytes) and total time (in seconds) used by
727 assembly.
728
729 @item --strip-local-absolute
730 Remove local absolute symbols from the outgoing symbol table.
731
732 @item -v
733 @itemx -version
734 Print the @command{as} version.
735
736 @item --version
737 Print the @command{as} version and exit.
738
739 @item -W
740 @itemx --no-warn
741 Suppress warning messages.
742
743 @item --fatal-warnings
744 Treat warnings as errors.
745
746 @item --warn
747 Don't suppress warning messages or treat them as errors.
748
749 @item -w
750 Ignored.
751
752 @item -x
753 Ignored.
754
755 @item -Z
756 Generate an object file even after errors.
757
758 @item -- | @var{files} @dots{}
759 Standard input, or source files to assemble.
760
761 @end table
762 @c man end
763
764 @ifset AARCH64
765
766 @ifclear man
767 @xref{AArch64 Options}, for the options available when @value{AS} is configured
768 for the 64-bit mode of the ARM Architecture (AArch64).
769 @end ifclear
770
771 @ifset man
772 @c man begin OPTIONS
773 The following options are available when @value{AS} is configured for the
774 64-bit mode of the ARM Architecture (AArch64).
775 @c man end
776 @c man begin INCLUDE
777 @include c-aarch64.texi
778 @c ended inside the included file
779 @end ifset
780
781 @end ifset
782
783 @ifset ALPHA
784
785 @ifclear man
786 @xref{Alpha Options}, for the options available when @value{AS} is configured
787 for an Alpha processor.
788 @end ifclear
789
790 @ifset man
791 @c man begin OPTIONS
792 The following options are available when @value{AS} is configured for an Alpha
793 processor.
794 @c man end
795 @c man begin INCLUDE
796 @include c-alpha.texi
797 @c ended inside the included file
798 @end ifset
799
800 @end ifset
801
802 @c man begin OPTIONS
803 @ifset ARC
804 The following options are available when @value{AS} is configured for
805 an ARC processor.
806
807 @table @gcctabopt
808 @item -marc[5|6|7|8]
809 This option selects the core processor variant.
810 @item -EB | -EL
811 Select either big-endian (-EB) or little-endian (-EL) output.
812 @end table
813 @end ifset
814
815 @ifset ARM
816 The following options are available when @value{AS} is configured for the ARM
817 processor family.
818
819 @table @gcctabopt
820 @item -mcpu=@var{processor}[+@var{extension}@dots{}]
821 Specify which ARM processor variant is the target.
822 @item -march=@var{architecture}[+@var{extension}@dots{}]
823 Specify which ARM architecture variant is used by the target.
824 @item -mfpu=@var{floating-point-format}
825 Select which Floating Point architecture is the target.
826 @item -mfloat-abi=@var{abi}
827 Select which floating point ABI is in use.
828 @item -mthumb
829 Enable Thumb only instruction decoding.
830 @item -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant
831 Select which procedure calling convention is in use.
832 @item -EB | -EL
833 Select either big-endian (-EB) or little-endian (-EL) output.
834 @item -mthumb-interwork
835 Specify that the code has been generated with interworking between Thumb and
836 ARM code in mind.
837 @item -k
838 Specify that PIC code has been generated.
839 @end table
840 @end ifset
841 @c man end
842
843 @ifset Blackfin
844
845 @ifclear man
846 @xref{Blackfin Options}, for the options available when @value{AS} is
847 configured for the Blackfin processor family.
848 @end ifclear
849
850 @ifset man
851 @c man begin OPTIONS
852 The following options are available when @value{AS} is configured for
853 the Blackfin processor family.
854 @c man end
855 @c man begin INCLUDE
856 @include c-bfin.texi
857 @c ended inside the included file
858 @end ifset
859
860 @end ifset
861
862 @c man begin OPTIONS
863 @ifset CRIS
864 See the info pages for documentation of the CRIS-specific options.
865 @end ifset
866
867 @ifset D10V
868 The following options are available when @value{AS} is configured for
869 a D10V processor.
870 @table @gcctabopt
871 @cindex D10V optimization
872 @cindex optimization, D10V
873 @item -O
874 Optimize output by parallelizing instructions.
875 @end table
876 @end ifset
877
878 @ifset D30V
879 The following options are available when @value{AS} is configured for a D30V
880 processor.
881 @table @gcctabopt
882 @cindex D30V optimization
883 @cindex optimization, D30V
884 @item -O
885 Optimize output by parallelizing instructions.
886
887 @cindex D30V nops
888 @item -n
889 Warn when nops are generated.
890
891 @cindex D30V nops after 32-bit multiply
892 @item -N
893 Warn when a nop after a 32-bit multiply instruction is generated.
894 @end table
895 @end ifset
896 @c man end
897
898 @ifset EPIPHANY
899 The following options are available when @value{AS} is configured for the
900 Adapteva EPIPHANY series.
901
902 @ifclear man
903 @xref{Epiphany Options}, for the options available when @value{AS} is
904 configured for an Epiphany processor.
905 @end ifclear
906
907 @ifset man
908 @c man begin OPTIONS
909 The following options are available when @value{AS} is configured for
910 an Epiphany processor.
911 @c man end
912 @c man begin INCLUDE
913 @include c-epiphany.texi
914 @c ended inside the included file
915 @end ifset
916
917 @end ifset
918
919 @ifset H8300
920
921 @ifclear man
922 @xref{H8/300 Options}, for the options available when @value{AS} is configured
923 for an H8/300 processor.
924 @end ifclear
925
926 @ifset man
927 @c man begin OPTIONS
928 The following options are available when @value{AS} is configured for an H8/300
929 processor.
930 @c man end
931 @c man begin INCLUDE
932 @include c-h8300.texi
933 @c ended inside the included file
934 @end ifset
935
936 @end ifset
937
938 @ifset I80386
939
940 @ifclear man
941 @xref{i386-Options}, for the options available when @value{AS} is
942 configured for an i386 processor.
943 @end ifclear
944
945 @ifset man
946 @c man begin OPTIONS
947 The following options are available when @value{AS} is configured for
948 an i386 processor.
949 @c man end
950 @c man begin INCLUDE
951 @include c-i386.texi
952 @c ended inside the included file
953 @end ifset
954
955 @end ifset
956
957 @c man begin OPTIONS
958 @ifset I960
959 The following options are available when @value{AS} is configured for the
960 Intel 80960 processor.
961
962 @table @gcctabopt
963 @item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
964 Specify which variant of the 960 architecture is the target.
965
966 @item -b
967 Add code to collect statistics about branches taken.
968
969 @item -no-relax
970 Do not alter compare-and-branch instructions for long displacements;
971 error if necessary.
972
973 @end table
974 @end ifset
975
976 @ifset IP2K
977 The following options are available when @value{AS} is configured for the
978 Ubicom IP2K series.
979
980 @table @gcctabopt
981
982 @item -mip2022ext
983 Specifies that the extended IP2022 instructions are allowed.
984
985 @item -mip2022
986 Restores the default behaviour, which restricts the permitted instructions to
987 just the basic IP2022 ones.
988
989 @end table
990 @end ifset
991
992 @ifset M32C
993 The following options are available when @value{AS} is configured for the
994 Renesas M32C and M16C processors.
995
996 @table @gcctabopt
997
998 @item -m32c
999 Assemble M32C instructions.
1000
1001 @item -m16c
1002 Assemble M16C instructions (the default).
1003
1004 @item -relax
1005 Enable support for link-time relaxations.
1006
1007 @item -h-tick-hex
1008 Support H'00 style hex constants in addition to 0x00 style.
1009
1010 @end table
1011 @end ifset
1012
1013 @ifset M32R
1014 The following options are available when @value{AS} is configured for the
1015 Renesas M32R (formerly Mitsubishi M32R) series.
1016
1017 @table @gcctabopt
1018
1019 @item --m32rx
1020 Specify which processor in the M32R family is the target.  The default
1021 is normally the M32R, but this option changes it to the M32RX.
1022
1023 @item --warn-explicit-parallel-conflicts or --Wp
1024 Produce warning messages when questionable parallel constructs are
1025 encountered.
1026
1027 @item --no-warn-explicit-parallel-conflicts or --Wnp
1028 Do not produce warning messages when questionable parallel constructs are
1029 encountered.
1030
1031 @end table
1032 @end ifset
1033
1034 @ifset M680X0
1035 The following options are available when @value{AS} is configured for the
1036 Motorola 68000 series.
1037
1038 @table @gcctabopt
1039
1040 @item -l
1041 Shorten references to undefined symbols, to one word instead of two.
1042
1043 @item -m68000 | -m68008 | -m68010 | -m68020 | -m68030
1044 @itemx | -m68040 | -m68060 | -m68302 | -m68331 | -m68332
1045 @itemx | -m68333 | -m68340 | -mcpu32 | -m5200
1046 Specify what processor in the 68000 family is the target.  The default
1047 is normally the 68020, but this can be changed at configuration time.
1048
1049 @item -m68881 | -m68882 | -mno-68881 | -mno-68882
1050 The target machine does (or does not) have a floating-point coprocessor.
1051 The default is to assume a coprocessor for 68020, 68030, and cpu32.  Although
1052 the basic 68000 is not compatible with the 68881, a combination of the
1053 two can be specified, since it's possible to do emulation of the
1054 coprocessor instructions with the main processor.
1055
1056 @item -m68851 | -mno-68851
1057 The target machine does (or does not) have a memory-management
1058 unit coprocessor.  The default is to assume an MMU for 68020 and up.
1059
1060 @end table
1061 @end ifset
1062
1063 @ifset NIOSII
1064
1065 @ifclear man
1066 @xref{Nios II Options}, for the options available when @value{AS} is configured
1067 for an Altera Nios II processor.
1068 @end ifclear
1069
1070 @ifset man
1071 @c man begin OPTIONS
1072 The following options are available when @value{AS} is configured for an
1073 Altera Nios II processor.
1074 @c man end
1075 @c man begin INCLUDE
1076 @include c-nios2.texi
1077 @c ended inside the included file
1078 @end ifset
1079 @end ifset
1080
1081 @ifset PDP11
1082
1083 For details about the PDP-11 machine dependent features options,
1084 see @ref{PDP-11-Options}.
1085
1086 @table @gcctabopt
1087 @item -mpic | -mno-pic
1088 Generate position-independent (or position-dependent) code.  The
1089 default is @option{-mpic}.
1090
1091 @item -mall
1092 @itemx -mall-extensions
1093 Enable all instruction set extensions.  This is the default.
1094
1095 @item -mno-extensions
1096 Disable all instruction set extensions.
1097
1098 @item -m@var{extension} | -mno-@var{extension}
1099 Enable (or disable) a particular instruction set extension.
1100
1101 @item -m@var{cpu}
1102 Enable the instruction set extensions supported by a particular CPU, and
1103 disable all other extensions.
1104
1105 @item -m@var{machine}
1106 Enable the instruction set extensions supported by a particular machine
1107 model, and disable all other extensions.
1108 @end table
1109
1110 @end ifset
1111
1112 @ifset PJ
1113 The following options are available when @value{AS} is configured for
1114 a picoJava processor.
1115
1116 @table @gcctabopt
1117
1118 @cindex PJ endianness
1119 @cindex endianness, PJ
1120 @cindex big endian output, PJ
1121 @item -mb
1122 Generate ``big endian'' format output.
1123
1124 @cindex little endian output, PJ
1125 @item -ml
1126 Generate ``little endian'' format output.
1127
1128 @end table
1129 @end ifset
1130
1131 @ifset M68HC11
1132 The following options are available when @value{AS} is configured for the
1133 Motorola 68HC11 or 68HC12 series.
1134
1135 @table @gcctabopt
1136
1137 @item -m68hc11 | -m68hc12 | -m68hcs12 | -mm9s12x | -mm9s12xg
1138 Specify what processor is the target.  The default is
1139 defined by the configuration option when building the assembler.
1140
1141 @item --xgate-ramoffset
1142 Instruct the linker to offset RAM addresses from S12X address space into
1143 XGATE address space.
1144
1145 @item -mshort
1146 Specify to use the 16-bit integer ABI.
1147
1148 @item -mlong
1149 Specify to use the 32-bit integer ABI.
1150
1151 @item -mshort-double
1152 Specify to use the 32-bit double ABI.
1153
1154 @item -mlong-double
1155 Specify to use the 64-bit double ABI.
1156
1157 @item --force-long-branches
1158 Relative branches are turned into absolute ones. This concerns
1159 conditional branches, unconditional branches and branches to a
1160 sub routine.
1161
1162 @item -S | --short-branches
1163 Do not turn relative branches into absolute ones
1164 when the offset is out of range.
1165
1166 @item --strict-direct-mode
1167 Do not turn the direct addressing mode into extended addressing mode
1168 when the instruction does not support direct addressing mode.
1169
1170 @item --print-insn-syntax
1171 Print the syntax of instruction in case of error.
1172
1173 @item --print-opcodes
1174 Print the list of instructions with syntax and then exit.
1175
1176 @item --generate-example
1177 Print an example of instruction for each possible instruction and then exit.
1178 This option is only useful for testing @command{@value{AS}}.
1179
1180 @end table
1181 @end ifset
1182
1183 @ifset SPARC
1184 The following options are available when @command{@value{AS}} is configured
1185 for the SPARC architecture:
1186
1187 @table @gcctabopt
1188 @item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
1189 @itemx -Av8plus | -Av8plusa | -Av9 | -Av9a
1190 Explicitly select a variant of the SPARC architecture.
1191
1192 @samp{-Av8plus} and @samp{-Av8plusa} select a 32 bit environment.
1193 @samp{-Av9} and @samp{-Av9a} select a 64 bit environment.
1194
1195 @samp{-Av8plusa} and @samp{-Av9a} enable the SPARC V9 instruction set with
1196 UltraSPARC extensions.
1197
1198 @item -xarch=v8plus | -xarch=v8plusa
1199 For compatibility with the Solaris v9 assembler.  These options are
1200 equivalent to -Av8plus and -Av8plusa, respectively.
1201
1202 @item -bump
1203 Warn when the assembler switches to another architecture.
1204 @end table
1205 @end ifset
1206
1207 @ifset TIC54X
1208 The following options are available when @value{AS} is configured for the 'c54x
1209 architecture.
1210
1211 @table @gcctabopt
1212 @item -mfar-mode
1213 Enable extended addressing mode.  All addresses and relocations will assume
1214 extended addressing (usually 23 bits).
1215 @item -mcpu=@var{CPU_VERSION}
1216 Sets the CPU version being compiled for.
1217 @item -merrors-to-file @var{FILENAME}
1218 Redirect error output to a file, for broken systems which don't support such
1219 behaviour in the shell.
1220 @end table
1221 @end ifset
1222
1223 @ifset MIPS
1224 The following options are available when @value{AS} is configured for
1225 a MIPS processor.
1226
1227 @table @gcctabopt
1228 @item -G @var{num}
1229 This option sets the largest size of an object that can be referenced
1230 implicitly with the @code{gp} register.  It is only accepted for targets that
1231 use ECOFF format, such as a DECstation running Ultrix.  The default value is 8.
1232
1233 @cindex MIPS endianness
1234 @cindex endianness, MIPS
1235 @cindex big endian output, MIPS
1236 @item -EB
1237 Generate ``big endian'' format output.
1238
1239 @cindex little endian output, MIPS
1240 @item -EL
1241 Generate ``little endian'' format output.
1242
1243 @cindex MIPS ISA
1244 @item -mips1
1245 @itemx -mips2
1246 @itemx -mips3
1247 @itemx -mips4
1248 @itemx -mips5
1249 @itemx -mips32
1250 @itemx -mips32r2
1251 @itemx -mips64
1252 @itemx -mips64r2
1253 Generate code for a particular MIPS Instruction Set Architecture level.
1254 @samp{-mips1} is an alias for @samp{-march=r3000}, @samp{-mips2} is an
1255 alias for @samp{-march=r6000}, @samp{-mips3} is an alias for
1256 @samp{-march=r4000} and @samp{-mips4} is an alias for @samp{-march=r8000}.
1257 @samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, @samp{-mips64}, and
1258 @samp{-mips64r2} correspond to generic MIPS V, MIPS32, MIPS32 Release 2,
1259 MIPS64, and MIPS64 Release 2 ISA processors, respectively.
1260
1261 @item -march=@var{cpu}
1262 Generate code for a particular MIPS CPU.
1263
1264 @item -mtune=@var{cpu}
1265 Schedule and tune for a particular MIPS CPU.
1266
1267 @item -mfix7000
1268 @itemx -mno-fix7000
1269 Cause nops to be inserted if the read of the destination register
1270 of an mfhi or mflo instruction occurs in the following two instructions.
1271
1272 @item -mdebug
1273 @itemx -no-mdebug
1274 Cause stabs-style debugging output to go into an ECOFF-style .mdebug
1275 section instead of the standard ELF .stabs sections.
1276
1277 @item -mpdr
1278 @itemx -mno-pdr
1279 Control generation of @code{.pdr} sections.
1280
1281 @item -mgp32
1282 @itemx -mfp32
1283 The register sizes are normally inferred from the ISA and ABI, but these
1284 flags force a certain group of registers to be treated as 32 bits wide at
1285 all times.  @samp{-mgp32} controls the size of general-purpose registers
1286 and @samp{-mfp32} controls the size of floating-point registers.
1287
1288 @item -mips16
1289 @itemx -no-mips16
1290 Generate code for the MIPS 16 processor.  This is equivalent to putting
1291 @code{.set mips16} at the start of the assembly file.  @samp{-no-mips16}
1292 turns off this option.
1293
1294 @item -mmicromips
1295 @itemx -mno-micromips
1296 Generate code for the microMIPS processor.  This is equivalent to putting
1297 @code{.set micromips} at the start of the assembly file.  @samp{-mno-micromips}
1298 turns off this option.  This is equivalent to putting @code{.set nomicromips}
1299 at the start of the assembly file.
1300
1301 @item -msmartmips
1302 @itemx -mno-smartmips
1303 Enables the SmartMIPS extension to the MIPS32 instruction set. This is
1304 equivalent to putting @code{.set smartmips} at the start of the assembly file.
1305 @samp{-mno-smartmips} turns off this option.
1306
1307 @item -mips3d
1308 @itemx -no-mips3d
1309 Generate code for the MIPS-3D Application Specific Extension.
1310 This tells the assembler to accept MIPS-3D instructions.
1311 @samp{-no-mips3d} turns off this option.
1312
1313 @item -mdmx
1314 @itemx -no-mdmx
1315 Generate code for the MDMX Application Specific Extension.
1316 This tells the assembler to accept MDMX instructions.
1317 @samp{-no-mdmx} turns off this option.
1318
1319 @item -mdsp
1320 @itemx -mno-dsp
1321 Generate code for the DSP Release 1 Application Specific Extension.
1322 This tells the assembler to accept DSP Release 1 instructions.
1323 @samp{-mno-dsp} turns off this option.
1324
1325 @item -mdspr2
1326 @itemx -mno-dspr2
1327 Generate code for the DSP Release 2 Application Specific Extension.
1328 This option implies -mdsp.
1329 This tells the assembler to accept DSP Release 2 instructions.
1330 @samp{-mno-dspr2} turns off this option.
1331
1332 @item -mmt
1333 @itemx -mno-mt
1334 Generate code for the MT Application Specific Extension.
1335 This tells the assembler to accept MT instructions.
1336 @samp{-mno-mt} turns off this option.
1337
1338 @item -mmcu
1339 @itemx -mno-mcu
1340 Generate code for the MCU Application Specific Extension.
1341 This tells the assembler to accept MCU instructions.
1342 @samp{-mno-mcu} turns off this option.
1343
1344 @item -minsn32
1345 @itemx -mno-insn32
1346 Only use 32-bit instruction encodings when generating code for the
1347 microMIPS processor.  This option inhibits the use of any 16-bit
1348 instructions.  This is equivalent to putting @code{.set insn32} at
1349 the start of the assembly file.  @samp{-mno-insn32} turns off this
1350 option.  This is equivalent to putting @code{.set noinsn32} at the
1351 start of the assembly file.  By default @samp{-mno-insn32} is
1352 selected, allowing all instructions to be used.
1353
1354 @item --construct-floats
1355 @itemx --no-construct-floats
1356 The @samp{--no-construct-floats} option disables the construction of
1357 double width floating point constants by loading the two halves of the
1358 value into the two single width floating point registers that make up
1359 the double width register.  By default @samp{--construct-floats} is
1360 selected, allowing construction of these floating point constants.
1361
1362 @item --relax-branch
1363 @itemx --no-relax-branch
1364 The @samp{--relax-branch} option enables the relaxation of out-of-range
1365 branches.  By default @samp{--no-relax-branch} is selected, causing any
1366 out-of-range branches to produce an error.
1367
1368 @item -mnan=@var{encoding}
1369 Select between the IEEE 754-2008 (@option{-mnan=2008}) or the legacy
1370 (@option{-mnan=legacy}) NaN encoding format.  The latter is the default.
1371
1372 @cindex emulation
1373 @item --emulation=@var{name}
1374 This option was formerly used to switch between ELF and ECOFF output
1375 on targets like IRIX 5 that supported both.  MIPS ECOFF support was
1376 removed in GAS 2.24, so the option now serves little purpose.
1377 It is retained for backwards compatibility.
1378
1379 The available configuration names are: @samp{mipself}, @samp{mipslelf} and
1380 @samp{mipsbelf}.  Choosing @samp{mipself} now has no effect, since the output
1381 is always ELF.  @samp{mipslelf} and @samp{mipsbelf} select little- and
1382 big-endian output respectively, but @samp{-EL} and @samp{-EB} are now the
1383 preferred options instead.
1384
1385 @item -nocpp
1386 @command{@value{AS}} ignores this option.  It is accepted for compatibility with
1387 the native tools.
1388
1389 @item --trap
1390 @itemx --no-trap
1391 @itemx --break
1392 @itemx --no-break
1393 Control how to deal with multiplication overflow and division by zero.
1394 @samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception
1395 (and only work for Instruction Set Architecture level 2 and higher);
1396 @samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a
1397 break exception.
1398
1399 @item -n
1400 When this option is used, @command{@value{AS}} will issue a warning every
1401 time it generates a nop instruction from a macro.
1402 @end table
1403 @end ifset
1404
1405 @ifset MCORE
1406 The following options are available when @value{AS} is configured for
1407 an MCore processor.
1408
1409 @table @gcctabopt
1410 @item -jsri2bsr
1411 @itemx -nojsri2bsr
1412 Enable or disable the JSRI to BSR transformation.  By default this is enabled.
1413 The command line option @samp{-nojsri2bsr} can be used to disable it.
1414
1415 @item -sifilter
1416 @itemx -nosifilter
1417 Enable or disable the silicon filter behaviour.  By default this is disabled.
1418 The default can be overridden by the @samp{-sifilter} command line option.
1419
1420 @item -relax
1421 Alter jump instructions for long displacements.
1422
1423 @item -mcpu=[210|340]
1424 Select the cpu type on the target hardware.  This controls which instructions
1425 can be assembled.
1426
1427 @item -EB
1428 Assemble for a big endian target.
1429
1430 @item -EL
1431 Assemble for a little endian target.
1432
1433 @end table
1434 @end ifset
1435 @c man end
1436
1437 @ifset METAG
1438
1439 @ifclear man
1440 @xref{Meta Options}, for the options available when @value{AS} is configured
1441 for a Meta processor.
1442 @end ifclear
1443
1444 @ifset man
1445 @c man begin OPTIONS
1446 The following options are available when @value{AS} is configured for a
1447 Meta processor.
1448 @c man end
1449 @c man begin INCLUDE
1450 @include c-metag.texi
1451 @c ended inside the included file
1452 @end ifset
1453
1454 @end ifset
1455
1456 @c man begin OPTIONS
1457 @ifset MMIX
1458 See the info pages for documentation of the MMIX-specific options.
1459 @end ifset
1460
1461 @c man end
1462 @ifset PPC
1463
1464 @ifclear man
1465 @xref{PowerPC-Opts}, for the options available when @value{AS} is configured
1466 for a PowerPC processor.
1467 @end ifclear
1468
1469 @ifset man
1470 @c man begin OPTIONS
1471 The following options are available when @value{AS} is configured for a
1472 PowerPC processor.
1473 @c man end
1474 @c man begin INCLUDE
1475 @include c-ppc.texi
1476 @c ended inside the included file
1477 @end ifset
1478
1479 @end ifset
1480
1481 @c man begin OPTIONS
1482 @ifset RX
1483 See the info pages for documentation of the RX-specific options.
1484 @end ifset
1485
1486 @ifset S390
1487 The following options are available when @value{AS} is configured for the s390
1488 processor family.
1489
1490 @table @gcctabopt
1491 @item -m31
1492 @itemx -m64
1493 Select the word size, either 31/32 bits or 64 bits.
1494 @item -mesa
1495 @item -mzarch
1496 Select the architecture mode, either the Enterprise System
1497 Architecture (esa) or the z/Architecture mode (zarch).
1498 @item -march=@var{processor}
1499 Specify which s390 processor variant is the target, @samp{g6}, @samp{g6},
1500 @samp{z900}, @samp{z990}, @samp{z9-109}, @samp{z9-ec}, @samp{z10},
1501 @samp{z196}, or @samp{zEC12}.
1502 @item -mregnames
1503 @itemx -mno-regnames
1504 Allow or disallow symbolic names for registers.
1505 @item -mwarn-areg-zero
1506 Warn whenever the operand for a base or index register has been specified
1507 but evaluates to zero.
1508 @end table
1509 @end ifset
1510 @c man end
1511
1512 @ifset TIC6X
1513
1514 @ifclear man
1515 @xref{TIC6X Options}, for the options available when @value{AS} is configured
1516 for a TMS320C6000 processor.
1517 @end ifclear
1518
1519 @ifset man
1520 @c man begin OPTIONS
1521 The following options are available when @value{AS} is configured for a
1522 TMS320C6000 processor.
1523 @c man end
1524 @c man begin INCLUDE
1525 @include c-tic6x.texi
1526 @c ended inside the included file
1527 @end ifset
1528
1529 @end ifset
1530
1531 @ifset TILEGX
1532
1533 @ifclear man
1534 @xref{TILE-Gx Options}, for the options available when @value{AS} is configured
1535 for a TILE-Gx processor.
1536 @end ifclear
1537
1538 @ifset man
1539 @c man begin OPTIONS
1540 The following options are available when @value{AS} is configured for a TILE-Gx
1541 processor.
1542 @c man end
1543 @c man begin INCLUDE
1544 @include c-tilegx.texi
1545 @c ended inside the included file
1546 @end ifset
1547
1548 @end ifset
1549
1550 @ifset XTENSA
1551
1552 @ifclear man
1553 @xref{Xtensa Options}, for the options available when @value{AS} is configured
1554 for an Xtensa processor.
1555 @end ifclear
1556
1557 @ifset man
1558 @c man begin OPTIONS
1559 The following options are available when @value{AS} is configured for an
1560 Xtensa processor.
1561 @c man end
1562 @c man begin INCLUDE
1563 @include c-xtensa.texi
1564 @c ended inside the included file
1565 @end ifset
1566
1567 @end ifset
1568
1569 @c man begin OPTIONS
1570
1571 @ifset Z80
1572 The following options are available when @value{AS} is configured for
1573 a Z80 family processor.
1574 @table @gcctabopt
1575 @item -z80
1576 Assemble for Z80 processor.
1577 @item -r800
1578 Assemble for R800 processor.
1579 @item  -ignore-undocumented-instructions
1580 @itemx -Wnud
1581 Assemble undocumented Z80 instructions that also work on R800 without warning.
1582 @item  -ignore-unportable-instructions
1583 @itemx -Wnup
1584 Assemble all undocumented Z80 instructions without warning.
1585 @item  -warn-undocumented-instructions
1586 @itemx -Wud
1587 Issue a warning for undocumented Z80 instructions that also work on R800.
1588 @item  -warn-unportable-instructions
1589 @itemx -Wup
1590 Issue a warning for undocumented Z80 instructions that do not work on R800.
1591 @item  -forbid-undocumented-instructions
1592 @itemx -Fud
1593 Treat all undocumented instructions as errors.
1594 @item  -forbid-unportable-instructions
1595 @itemx -Fup
1596 Treat undocumented Z80 instructions that do not work on R800 as errors.
1597 @end table
1598 @end ifset
1599
1600 @c man end
1601
1602 @menu
1603 * Manual::                      Structure of this Manual
1604 * GNU Assembler::               The GNU Assembler
1605 * Object Formats::              Object File Formats
1606 * Command Line::                Command Line
1607 * Input Files::                 Input Files
1608 * Object::                      Output (Object) File
1609 * Errors::                      Error and Warning Messages
1610 @end menu
1611
1612 @node Manual
1613 @section Structure of this Manual
1614
1615 @cindex manual, structure and purpose
1616 This manual is intended to describe what you need to know to use
1617 @sc{gnu} @command{@value{AS}}.  We cover the syntax expected in source files, including
1618 notation for symbols, constants, and expressions; the directives that
1619 @command{@value{AS}} understands; and of course how to invoke @command{@value{AS}}.
1620
1621 @ifclear GENERIC
1622 We also cover special features in the @value{TARGET}
1623 configuration of @command{@value{AS}}, including assembler directives.
1624 @end ifclear
1625 @ifset GENERIC
1626 This manual also describes some of the machine-dependent features of
1627 various flavors of the assembler.
1628 @end ifset
1629
1630 @cindex machine instructions (not covered)
1631 On the other hand, this manual is @emph{not} intended as an introduction
1632 to programming in assembly language---let alone programming in general!
1633 In a similar vein, we make no attempt to introduce the machine
1634 architecture; we do @emph{not} describe the instruction set, standard
1635 mnemonics, registers or addressing modes that are standard to a
1636 particular architecture.
1637 @ifset GENERIC
1638 You may want to consult the manufacturer's
1639 machine architecture manual for this information.
1640 @end ifset
1641 @ifclear GENERIC
1642 @ifset H8/300
1643 For information on the H8/300 machine instruction set, see @cite{H8/300
1644 Series Programming Manual}.  For the H8/300H, see @cite{H8/300H Series
1645 Programming Manual} (Renesas).
1646 @end ifset
1647 @ifset SH
1648 For information on the Renesas (formerly Hitachi) / SuperH SH machine instruction set,
1649 see @cite{SH-Microcomputer User's Manual} (Renesas) or
1650 @cite{SH-4 32-bit CPU Core Architecture} (SuperH) and
1651 @cite{SuperH (SH) 64-Bit RISC Series} (SuperH).
1652 @end ifset
1653 @ifset Z8000
1654 For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
1655 @end ifset
1656 @end ifclear
1657
1658 @c I think this is premature---doc@cygnus.com, 17jan1991
1659 @ignore
1660 Throughout this manual, we assume that you are running @dfn{GNU},
1661 the portable operating system from the @dfn{Free Software
1662 Foundation, Inc.}.  This restricts our attention to certain kinds of
1663 computer (in particular, the kinds of computers that @sc{gnu} can run on);
1664 once this assumption is granted examples and definitions need less
1665 qualification.
1666
1667 @command{@value{AS}} is part of a team of programs that turn a high-level
1668 human-readable series of instructions into a low-level
1669 computer-readable series of instructions.  Different versions of
1670 @command{@value{AS}} are used for different kinds of computer.
1671 @end ignore
1672
1673 @c There used to be a section "Terminology" here, which defined
1674 @c "contents", "byte", "word", and "long".  Defining "word" to any
1675 @c particular size is confusing when the .word directive may generate 16
1676 @c bits on one machine and 32 bits on another; in general, for the user
1677 @c version of this manual, none of these terms seem essential to define.
1678 @c They were used very little even in the former draft of the manual;
1679 @c this draft makes an effort to avoid them (except in names of
1680 @c directives).
1681
1682 @node GNU Assembler
1683 @section The GNU Assembler
1684
1685 @c man begin DESCRIPTION
1686
1687 @sc{gnu} @command{as} is really a family of assemblers.
1688 @ifclear GENERIC
1689 This manual describes @command{@value{AS}}, a member of that family which is
1690 configured for the @value{TARGET} architectures.
1691 @end ifclear
1692 If you use (or have used) the @sc{gnu} assembler on one architecture, you
1693 should find a fairly similar environment when you use it on another
1694 architecture.  Each version has much in common with the others,
1695 including object file formats, most assembler directives (often called
1696 @dfn{pseudo-ops}) and assembler syntax.@refill
1697
1698 @cindex purpose of @sc{gnu} assembler
1699 @command{@value{AS}} is primarily intended to assemble the output of the
1700 @sc{gnu} C compiler @code{@value{GCC}} for use by the linker
1701 @code{@value{LD}}.  Nevertheless, we've tried to make @command{@value{AS}}
1702 assemble correctly everything that other assemblers for the same
1703 machine would assemble.
1704 @ifset VAX
1705 Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
1706 @end ifset
1707 @ifset M680X0
1708 @c This remark should appear in generic version of manual; assumption
1709 @c here is that generic version sets M680x0.
1710 This doesn't mean @command{@value{AS}} always uses the same syntax as another
1711 assembler for the same architecture; for example, we know of several
1712 incompatible versions of 680x0 assembly language syntax.
1713 @end ifset
1714
1715 @c man end
1716
1717 Unlike older assemblers, @command{@value{AS}} is designed to assemble a source
1718 program in one pass of the source file.  This has a subtle impact on the
1719 @kbd{.org} directive (@pxref{Org,,@code{.org}}).
1720
1721 @node Object Formats
1722 @section Object File Formats
1723
1724 @cindex object file format
1725 The @sc{gnu} assembler can be configured to produce several alternative
1726 object file formats.  For the most part, this does not affect how you
1727 write assembly language programs; but directives for debugging symbols
1728 are typically different in different file formats.  @xref{Symbol
1729 Attributes,,Symbol Attributes}.
1730 @ifclear GENERIC
1731 @ifclear MULTI-OBJ
1732 For the @value{TARGET} target, @command{@value{AS}} is configured to produce
1733 @value{OBJ-NAME} format object files.
1734 @end ifclear
1735 @c The following should exhaust all configs that set MULTI-OBJ, ideally
1736 @ifset I960
1737 On the @value{TARGET}, @command{@value{AS}} can be configured to produce either
1738 @code{b.out} or COFF format object files.
1739 @end ifset
1740 @ifset HPPA
1741 On the @value{TARGET}, @command{@value{AS}} can be configured to produce either
1742 SOM or ELF format object files.
1743 @end ifset
1744 @end ifclear
1745
1746 @node Command Line
1747 @section Command Line
1748
1749 @cindex command line conventions
1750
1751 After the program name @command{@value{AS}}, the command line may contain
1752 options and file names.  Options may appear in any order, and may be
1753 before, after, or between file names.  The order of file names is
1754 significant.
1755
1756 @cindex standard input, as input file
1757 @kindex --
1758 @file{--} (two hyphens) by itself names the standard input file
1759 explicitly, as one of the files for @command{@value{AS}} to assemble.
1760
1761 @cindex options, command line
1762 Except for @samp{--} any command line argument that begins with a
1763 hyphen (@samp{-}) is an option.  Each option changes the behavior of
1764 @command{@value{AS}}.  No option changes the way another option works.  An
1765 option is a @samp{-} followed by one or more letters; the case of
1766 the letter is important.   All options are optional.
1767
1768 Some options expect exactly one file name to follow them.  The file
1769 name may either immediately follow the option's letter (compatible
1770 with older assemblers) or it may be the next command argument (@sc{gnu}
1771 standard).  These two command lines are equivalent:
1772
1773 @smallexample
1774 @value{AS} -o my-object-file.o mumble.s
1775 @value{AS} -omy-object-file.o mumble.s
1776 @end smallexample
1777
1778 @node Input Files
1779 @section Input Files
1780
1781 @cindex input
1782 @cindex source program
1783 @cindex files, input
1784 We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
1785 describe the program input to one run of @command{@value{AS}}.  The program may
1786 be in one or more files; how the source is partitioned into files
1787 doesn't change the meaning of the source.
1788
1789 @c I added "con" prefix to "catenation" just to prove I can overcome my
1790 @c APL training...   doc@cygnus.com
1791 The source program is a concatenation of the text in all the files, in the
1792 order specified.
1793
1794 @c man begin DESCRIPTION
1795 Each time you run @command{@value{AS}} it assembles exactly one source
1796 program.  The source program is made up of one or more files.
1797 (The standard input is also a file.)
1798
1799 You give @command{@value{AS}} a command line that has zero or more input file
1800 names.  The input files are read (from left file name to right).  A
1801 command line argument (in any position) that has no special meaning
1802 is taken to be an input file name.
1803
1804 If you give @command{@value{AS}} no file names it attempts to read one input file
1805 from the @command{@value{AS}} standard input, which is normally your terminal.  You
1806 may have to type @key{ctl-D} to tell @command{@value{AS}} there is no more program
1807 to assemble.
1808
1809 Use @samp{--} if you need to explicitly name the standard input file
1810 in your command line.
1811
1812 If the source is empty, @command{@value{AS}} produces a small, empty object
1813 file.
1814
1815 @c man end
1816
1817 @subheading Filenames and Line-numbers
1818
1819 @cindex input file linenumbers
1820 @cindex line numbers, in input files
1821 There are two ways of locating a line in the input file (or files) and
1822 either may be used in reporting error messages.  One way refers to a line
1823 number in a physical file; the other refers to a line number in a
1824 ``logical'' file.  @xref{Errors, ,Error and Warning Messages}.
1825
1826 @dfn{Physical files} are those files named in the command line given
1827 to @command{@value{AS}}.
1828
1829 @dfn{Logical files} are simply names declared explicitly by assembler
1830 directives; they bear no relation to physical files.  Logical file names help
1831 error messages reflect the original source file, when @command{@value{AS}} source
1832 is itself synthesized from other files.  @command{@value{AS}} understands the
1833 @samp{#} directives emitted by the @code{@value{GCC}} preprocessor.  See also
1834 @ref{File,,@code{.file}}.
1835
1836 @node Object
1837 @section Output (Object) File
1838
1839 @cindex object file
1840 @cindex output file
1841 @kindex a.out
1842 @kindex .o
1843 Every time you run @command{@value{AS}} it produces an output file, which is
1844 your assembly language program translated into numbers.  This file
1845 is the object file.  Its default name is
1846 @ifclear BOUT
1847 @code{a.out}.
1848 @end ifclear
1849 @ifset BOUT
1850 @ifset GENERIC
1851 @code{a.out}, or
1852 @end ifset
1853 @code{b.out} when @command{@value{AS}} is configured for the Intel 80960.
1854 @end ifset
1855 You can give it another name by using the @option{-o} option.  Conventionally,
1856 object file names end with @file{.o}.  The default name is used for historical
1857 reasons: older assemblers were capable of assembling self-contained programs
1858 directly into a runnable program.  (For some formats, this isn't currently
1859 possible, but it can be done for the @code{a.out} format.)
1860
1861 @cindex linker
1862 @kindex ld
1863 The object file is meant for input to the linker @code{@value{LD}}.  It contains
1864 assembled program code, information to help @code{@value{LD}} integrate
1865 the assembled program into a runnable file, and (optionally) symbolic
1866 information for the debugger.
1867
1868 @c link above to some info file(s) like the description of a.out.
1869 @c don't forget to describe @sc{gnu} info as well as Unix lossage.
1870
1871 @node Errors
1872 @section Error and Warning Messages
1873
1874 @c man begin DESCRIPTION
1875
1876 @cindex error messages
1877 @cindex warning messages
1878 @cindex messages from assembler
1879 @command{@value{AS}} may write warnings and error messages to the standard error
1880 file (usually your terminal).  This should not happen when  a compiler
1881 runs @command{@value{AS}} automatically.  Warnings report an assumption made so
1882 that @command{@value{AS}} could keep assembling a flawed program; errors report a
1883 grave problem that stops the assembly.
1884
1885 @c man end
1886
1887 @cindex format of warning messages
1888 Warning messages have the format
1889
1890 @smallexample
1891 file_name:@b{NNN}:Warning Message Text
1892 @end smallexample
1893
1894 @noindent
1895 @cindex line numbers, in warnings/errors
1896 (where @b{NNN} is a line number).  If a logical file name has been given
1897 (@pxref{File,,@code{.file}}) it is used for the filename, otherwise the name of
1898 the current input file is used.  If a logical line number was given
1899 @ifset GENERIC
1900 (@pxref{Line,,@code{.line}})
1901 @end ifset
1902 then it is used to calculate the number printed,
1903 otherwise the actual line in the current source file is printed.  The
1904 message text is intended to be self explanatory (in the grand Unix
1905 tradition).
1906
1907 @cindex format of error messages
1908 Error messages have the format
1909 @smallexample
1910 file_name:@b{NNN}:FATAL:Error Message Text
1911 @end smallexample
1912 The file name and line number are derived as for warning
1913 messages.  The actual message text may be rather less explanatory
1914 because many of them aren't supposed to happen.
1915
1916 @node Invoking
1917 @chapter Command-Line Options
1918
1919 @cindex options, all versions of assembler
1920 This chapter describes command-line options available in @emph{all}
1921 versions of the @sc{gnu} assembler; see @ref{Machine Dependencies},
1922 for options specific
1923 @ifclear GENERIC
1924 to the @value{TARGET} target.
1925 @end ifclear
1926 @ifset GENERIC
1927 to particular machine architectures.
1928 @end ifset
1929
1930 @c man begin DESCRIPTION
1931
1932 If you are invoking @command{@value{AS}} via the @sc{gnu} C compiler,
1933 you can use the @samp{-Wa} option to pass arguments through to the assembler.
1934 The assembler arguments must be separated from each other (and the @samp{-Wa})
1935 by commas.  For example:
1936
1937 @smallexample
1938 gcc -c -g -O -Wa,-alh,-L file.c
1939 @end smallexample
1940
1941 @noindent
1942 This passes two options to the assembler: @samp{-alh} (emit a listing to
1943 standard output with high-level and assembly source) and @samp{-L} (retain
1944 local symbols in the symbol table).
1945
1946 Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
1947 command-line options are automatically passed to the assembler by the compiler.
1948 (You can call the @sc{gnu} compiler driver with the @samp{-v} option to see
1949 precisely what options it passes to each compilation pass, including the
1950 assembler.)
1951
1952 @c man end
1953
1954 @menu
1955 * a::             -a[cdghlns] enable listings
1956 * alternate::     --alternate enable alternate macro syntax
1957 * D::             -D for compatibility
1958 * f::             -f to work faster
1959 * I::             -I for .include search path
1960 @ifclear DIFF-TBL-KLUGE
1961 * K::             -K for compatibility
1962 @end ifclear
1963 @ifset DIFF-TBL-KLUGE
1964 * K::             -K for difference tables
1965 @end ifset
1966
1967 * L::             -L to retain local symbols
1968 * listing::       --listing-XXX to configure listing output
1969 * M::             -M or --mri to assemble in MRI compatibility mode
1970 * MD::            --MD for dependency tracking
1971 * o::             -o to name the object file
1972 * R::             -R to join data and text sections
1973 * statistics::    --statistics to see statistics about assembly
1974 * traditional-format:: --traditional-format for compatible output
1975 * v::             -v to announce version
1976 * W::             -W, --no-warn, --warn, --fatal-warnings to control warnings
1977 * Z::             -Z to make object file even after errors
1978 @end menu
1979
1980 @node a
1981 @section Enable Listings: @option{-a[cdghlns]}
1982
1983 @kindex -a
1984 @kindex -ac
1985 @kindex -ad
1986 @kindex -ag
1987 @kindex -ah
1988 @kindex -al
1989 @kindex -an
1990 @kindex -as
1991 @cindex listings, enabling
1992 @cindex assembly listings, enabling
1993
1994 These options enable listing output from the assembler.  By itself,
1995 @samp{-a} requests high-level, assembly, and symbols listing.
1996 You can use other letters to select specific options for the list:
1997 @samp{-ah} requests a high-level language listing,
1998 @samp{-al} requests an output-program assembly listing, and
1999 @samp{-as} requests a symbol table listing.
2000 High-level listings require that a compiler debugging option like
2001 @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
2002 also.
2003
2004 Use the @samp{-ag} option to print a first section with general assembly
2005 information, like @value{AS} version, switches passed, or time stamp.
2006
2007 Use the @samp{-ac} option to omit false conditionals from a listing.  Any lines
2008 which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any
2009 other conditional), or a true @code{.if} followed by an @code{.else}, will be
2010 omitted from the listing.
2011
2012 Use the @samp{-ad} option to omit debugging directives from the
2013 listing.
2014
2015 Once you have specified one of these options, you can further control
2016 listing output and its appearance using the directives @code{.list},
2017 @code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
2018 @code{.sbttl}.
2019 The @samp{-an} option turns off all forms processing.
2020 If you do not request listing output with one of the @samp{-a} options, the
2021 listing-control directives have no effect.
2022
2023 The letters after @samp{-a} may be combined into one option,
2024 @emph{e.g.}, @samp{-aln}.
2025
2026 Note if the assembler source is coming from the standard input (e.g.,
2027 because it
2028 is being created by @code{@value{GCC}} and the @samp{-pipe} command line switch
2029 is being used) then the listing will not contain any comments or preprocessor
2030 directives.  This is because the listing code buffers input source lines from
2031 stdin only after they have been preprocessed by the assembler.  This reduces
2032 memory usage and makes the code more efficient.
2033
2034 @node alternate
2035 @section @option{--alternate}
2036
2037 @kindex --alternate
2038 Begin in alternate macro mode, see @ref{Altmacro,,@code{.altmacro}}.
2039
2040 @node D
2041 @section @option{-D}
2042
2043 @kindex -D
2044 This option has no effect whatsoever, but it is accepted to make it more
2045 likely that scripts written for other assemblers also work with
2046 @command{@value{AS}}.
2047
2048 @node f
2049 @section Work Faster: @option{-f}
2050
2051 @kindex -f
2052 @cindex trusted compiler
2053 @cindex faster processing (@option{-f})
2054 @samp{-f} should only be used when assembling programs written by a
2055 (trusted) compiler.  @samp{-f} stops the assembler from doing whitespace
2056 and comment preprocessing on
2057 the input file(s) before assembling them.  @xref{Preprocessing,
2058 ,Preprocessing}.
2059
2060 @quotation
2061 @emph{Warning:} if you use @samp{-f} when the files actually need to be
2062 preprocessed (if they contain comments, for example), @command{@value{AS}} does
2063 not work correctly.
2064 @end quotation
2065
2066 @node I
2067 @section @code{.include} Search Path: @option{-I} @var{path}
2068
2069 @kindex -I @var{path}
2070 @cindex paths for @code{.include}
2071 @cindex search path for @code{.include}
2072 @cindex @code{include} directive search path
2073 Use this option to add a @var{path} to the list of directories
2074 @command{@value{AS}} searches for files specified in @code{.include}
2075 directives (@pxref{Include,,@code{.include}}).  You may use @option{-I} as
2076 many times as necessary to include a variety of paths.  The current
2077 working directory is always searched first; after that, @command{@value{AS}}
2078 searches any @samp{-I} directories in the same order as they were
2079 specified (left to right) on the command line.
2080
2081 @node K
2082 @section Difference Tables: @option{-K}
2083
2084 @kindex -K
2085 @ifclear DIFF-TBL-KLUGE
2086 On the @value{TARGET} family, this option is allowed, but has no effect.  It is
2087 permitted for compatibility with the @sc{gnu} assembler on other platforms,
2088 where it can be used to warn when the assembler alters the machine code
2089 generated for @samp{.word} directives in difference tables.  The @value{TARGET}
2090 family does not have the addressing limitations that sometimes lead to this
2091 alteration on other platforms.
2092 @end ifclear
2093
2094 @ifset DIFF-TBL-KLUGE
2095 @cindex difference tables, warning
2096 @cindex warning for altered difference tables
2097 @command{@value{AS}} sometimes alters the code emitted for directives of the
2098 form @samp{.word @var{sym1}-@var{sym2}}.  @xref{Word,,@code{.word}}.
2099 You can use the @samp{-K} option if you want a warning issued when this
2100 is done.
2101 @end ifset
2102
2103 @node L
2104 @section Include Local Symbols: @option{-L}
2105
2106 @kindex -L
2107 @cindex local symbols, retaining in output
2108 Symbols beginning with system-specific local label prefixes, typically
2109 @samp{.L} for ELF systems or @samp{L} for traditional a.out systems, are
2110 called @dfn{local symbols}.  @xref{Symbol Names}.  Normally you do not see
2111 such symbols when debugging, because they are intended for the use of
2112 programs (like compilers) that compose assembler programs, not for your
2113 notice.  Normally both @command{@value{AS}} and @code{@value{LD}} discard
2114 such symbols, so you do not normally debug with them.
2115
2116 This option tells @command{@value{AS}} to retain those local symbols
2117 in the object file.  Usually if you do this you also tell the linker
2118 @code{@value{LD}} to preserve those symbols.
2119
2120 @node listing
2121 @section Configuring listing output: @option{--listing}
2122
2123 The listing feature of the assembler can be enabled via the command line switch
2124 @samp{-a} (@pxref{a}).  This feature combines the input source file(s) with a
2125 hex dump of the corresponding locations in the output object file, and displays
2126 them as a listing file.  The format of this listing can be controlled by
2127 directives inside the assembler source (i.e., @code{.list} (@pxref{List}),
2128 @code{.title} (@pxref{Title}), @code{.sbttl} (@pxref{Sbttl}),
2129 @code{.psize} (@pxref{Psize}), and
2130 @code{.eject} (@pxref{Eject}) and also by the following switches:
2131
2132 @table @gcctabopt
2133 @item --listing-lhs-width=@samp{number}
2134 @kindex --listing-lhs-width
2135 @cindex Width of first line disassembly output
2136 Sets the maximum width, in words, of the first line of the hex byte dump.  This
2137 dump appears on the left hand side of the listing output.
2138
2139 @item --listing-lhs-width2=@samp{number}
2140 @kindex --listing-lhs-width2
2141 @cindex Width of continuation lines of disassembly output
2142 Sets the maximum width, in words, of any further lines of the hex byte dump for
2143 a given input source line.  If this value is not specified, it defaults to being
2144 the same as the value specified for @samp{--listing-lhs-width}.  If neither
2145 switch is used the default is to one.
2146
2147 @item --listing-rhs-width=@samp{number}
2148 @kindex --listing-rhs-width
2149 @cindex Width of source line output
2150 Sets the maximum width, in characters, of the source line that is displayed
2151 alongside the hex dump.  The default value for this parameter is 100.  The
2152 source line is displayed on the right hand side of the listing output.
2153
2154 @item --listing-cont-lines=@samp{number}
2155 @kindex --listing-cont-lines
2156 @cindex Maximum number of continuation lines
2157 Sets the maximum number of continuation lines of hex dump that will be
2158 displayed for a given single line of source input.  The default value is 4.
2159 @end table
2160
2161 @node M
2162 @section Assemble in MRI Compatibility Mode: @option{-M}
2163
2164 @kindex -M
2165 @cindex MRI compatibility mode
2166 The @option{-M} or @option{--mri} option selects MRI compatibility mode.  This
2167 changes the syntax and pseudo-op handling of @command{@value{AS}} to make it
2168 compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the
2169 configured target) assembler from Microtec Research.  The exact nature of the
2170 MRI syntax will not be documented here; see the MRI manuals for more
2171 information.  Note in particular that the handling of macros and macro
2172 arguments is somewhat different.  The purpose of this option is to permit
2173 assembling existing MRI assembler code using @command{@value{AS}}.
2174
2175 The MRI compatibility is not complete.  Certain operations of the MRI assembler
2176 depend upon its object file format, and can not be supported using other object
2177 file formats.  Supporting these would require enhancing each object file format
2178 individually.  These are:
2179
2180 @itemize @bullet
2181 @item global symbols in common section
2182
2183 The m68k MRI assembler supports common sections which are merged by the linker.
2184 Other object file formats do not support this.  @command{@value{AS}} handles
2185 common sections by treating them as a single common symbol.  It permits local
2186 symbols to be defined within a common section, but it can not support global
2187 symbols, since it has no way to describe them.
2188
2189 @item complex relocations
2190
2191 The MRI assemblers support relocations against a negated section address, and
2192 relocations which combine the start addresses of two or more sections.  These
2193 are not support by other object file formats.
2194
2195 @item @code{END} pseudo-op specifying start address
2196
2197 The MRI @code{END} pseudo-op permits the specification of a start address.
2198 This is not supported by other object file formats.  The start address may
2199 instead be specified using the @option{-e} option to the linker, or in a linker
2200 script.
2201
2202 @item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops
2203
2204 The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module
2205 name to the output file.  This is not supported by other object file formats.
2206
2207 @item @code{ORG} pseudo-op
2208
2209 The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given
2210 address.  This differs from the usual @command{@value{AS}} @code{.org} pseudo-op,
2211 which changes the location within the current section.  Absolute sections are
2212 not supported by other object file formats.  The address of a section may be
2213 assigned within a linker script.
2214 @end itemize
2215
2216 There are some other features of the MRI assembler which are not supported by
2217 @command{@value{AS}}, typically either because they are difficult or because they
2218 seem of little consequence.  Some of these may be supported in future releases.
2219
2220 @itemize @bullet
2221
2222 @item EBCDIC strings
2223
2224 EBCDIC strings are not supported.
2225
2226 @item packed binary coded decimal
2227
2228 Packed binary coded decimal is not supported.  This means that the @code{DC.P}
2229 and @code{DCB.P} pseudo-ops are not supported.
2230
2231 @item @code{FEQU} pseudo-op
2232
2233 The m68k @code{FEQU} pseudo-op is not supported.
2234
2235 @item @code{NOOBJ} pseudo-op
2236
2237 The m68k @code{NOOBJ} pseudo-op is not supported.
2238
2239 @item @code{OPT} branch control options
2240
2241 The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB},
2242 @code{BRL}, and @code{BRW}---are ignored.  @command{@value{AS}} automatically
2243 relaxes all branches, whether forward or backward, to an appropriate size, so
2244 these options serve no purpose.
2245
2246 @item @code{OPT} list control options
2247
2248 The following m68k @code{OPT} list control options are ignored: @code{C},
2249 @code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M},
2250 @code{MEX}, @code{MC}, @code{MD}, @code{X}.
2251
2252 @item other @code{OPT} options
2253
2254 The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O},
2255 @code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}.
2256
2257 @item @code{OPT} @code{D} option is default
2258
2259 The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler.
2260 @code{OPT NOD} may be used to turn it off.
2261
2262 @item @code{XREF} pseudo-op.
2263
2264 The m68k @code{XREF} pseudo-op is ignored.
2265
2266 @item @code{.debug} pseudo-op
2267
2268 The i960 @code{.debug} pseudo-op is not supported.
2269
2270 @item @code{.extended} pseudo-op
2271
2272 The i960 @code{.extended} pseudo-op is not supported.
2273
2274 @item @code{.list} pseudo-op.
2275
2276 The various options of the i960 @code{.list} pseudo-op are not supported.
2277
2278 @item @code{.optimize} pseudo-op
2279
2280 The i960 @code{.optimize} pseudo-op is not supported.
2281
2282 @item @code{.output} pseudo-op
2283
2284 The i960 @code{.output} pseudo-op is not supported.
2285
2286 @item @code{.setreal} pseudo-op
2287
2288 The i960 @code{.setreal} pseudo-op is not supported.
2289
2290 @end itemize
2291
2292 @node MD
2293 @section Dependency Tracking: @option{--MD}
2294
2295 @kindex --MD
2296 @cindex dependency tracking
2297 @cindex make rules
2298
2299 @command{@value{AS}} can generate a dependency file for the file it creates.  This
2300 file consists of a single rule suitable for @code{make} describing the
2301 dependencies of the main source file.
2302
2303 The rule is written to the file named in its argument.
2304
2305 This feature is used in the automatic updating of makefiles.
2306
2307 @node o
2308 @section Name the Object File: @option{-o}
2309
2310 @kindex -o
2311 @cindex naming object file
2312 @cindex object file name
2313 There is always one object file output when you run @command{@value{AS}}.  By
2314 default it has the name
2315 @ifset GENERIC
2316 @ifset I960
2317 @file{a.out} (or @file{b.out}, for Intel 960 targets only).
2318 @end ifset
2319 @ifclear I960
2320 @file{a.out}.
2321 @end ifclear
2322 @end ifset
2323 @ifclear GENERIC
2324 @ifset I960
2325 @file{b.out}.
2326 @end ifset
2327 @ifclear I960
2328 @file{a.out}.
2329 @end ifclear
2330 @end ifclear
2331 You use this option (which takes exactly one filename) to give the
2332 object file a different name.
2333
2334 Whatever the object file is called, @command{@value{AS}} overwrites any
2335 existing file of the same name.
2336
2337 @node R
2338 @section Join Data and Text Sections: @option{-R}
2339
2340 @kindex -R
2341 @cindex data and text sections, joining
2342 @cindex text and data sections, joining
2343 @cindex joining text and data sections
2344 @cindex merging text and data sections
2345 @option{-R} tells @command{@value{AS}} to write the object file as if all
2346 data-section data lives in the text section.  This is only done at
2347 the very last moment:  your binary data are the same, but data
2348 section parts are relocated differently.  The data section part of
2349 your object file is zero bytes long because all its bytes are
2350 appended to the text section.  (@xref{Sections,,Sections and Relocation}.)
2351
2352 When you specify @option{-R} it would be possible to generate shorter
2353 address displacements (because we do not have to cross between text and
2354 data section).  We refrain from doing this simply for compatibility with
2355 older versions of @command{@value{AS}}.  In future, @option{-R} may work this way.
2356
2357 @ifset COFF-ELF
2358 When @command{@value{AS}} is configured for COFF or ELF output,
2359 this option is only useful if you use sections named @samp{.text} and
2360 @samp{.data}.
2361 @end ifset
2362
2363 @ifset HPPA
2364 @option{-R} is not supported for any of the HPPA targets.  Using
2365 @option{-R} generates a warning from @command{@value{AS}}.
2366 @end ifset
2367
2368 @node statistics
2369 @section Display Assembly Statistics: @option{--statistics}
2370
2371 @kindex --statistics
2372 @cindex statistics, about assembly
2373 @cindex time, total for assembly
2374 @cindex space used, maximum for assembly
2375 Use @samp{--statistics} to display two statistics about the resources used by
2376 @command{@value{AS}}: the maximum amount of space allocated during the assembly
2377 (in bytes), and the total execution time taken for the assembly (in @sc{cpu}
2378 seconds).
2379
2380 @node traditional-format
2381 @section Compatible Output: @option{--traditional-format}
2382
2383 @kindex --traditional-format
2384 For some targets, the output of @command{@value{AS}} is different in some ways
2385 from the output of some existing assembler.  This switch requests
2386 @command{@value{AS}} to use the traditional format instead.
2387
2388 For example, it disables the exception frame optimizations which
2389 @command{@value{AS}} normally does by default on @code{@value{GCC}} output.
2390
2391 @node v
2392 @section Announce Version: @option{-v}
2393
2394 @kindex -v
2395 @kindex -version
2396 @cindex assembler version
2397 @cindex version of assembler
2398 You can find out what version of as is running by including the
2399 option @samp{-v} (which you can also spell as @samp{-version}) on the
2400 command line.
2401
2402 @node W
2403 @section Control Warnings: @option{-W}, @option{--warn}, @option{--no-warn}, @option{--fatal-warnings}
2404
2405 @command{@value{AS}} should never give a warning or error message when
2406 assembling compiler output.  But programs written by people often
2407 cause @command{@value{AS}} to give a warning that a particular assumption was
2408 made.  All such warnings are directed to the standard error file.
2409
2410 @kindex -W
2411 @kindex --no-warn
2412 @cindex suppressing warnings
2413 @cindex warnings, suppressing
2414 If you use the @option{-W} and @option{--no-warn} options, no warnings are issued.
2415 This only affects the warning messages: it does not change any particular of
2416 how @command{@value{AS}} assembles your file.  Errors, which stop the assembly,
2417 are still reported.
2418
2419 @kindex --fatal-warnings
2420 @cindex errors, caused by warnings
2421 @cindex warnings, causing error
2422 If you use the @option{--fatal-warnings} option, @command{@value{AS}} considers
2423 files that generate warnings to be in error.
2424
2425 @kindex --warn
2426 @cindex warnings, switching on
2427 You can switch these options off again by specifying @option{--warn}, which
2428 causes warnings to be output as usual.
2429
2430 @node Z
2431 @section Generate Object File in Spite of Errors: @option{-Z}
2432 @cindex object file, after errors
2433 @cindex errors, continuing after
2434 After an error message, @command{@value{AS}} normally produces no output.  If for
2435 some reason you are interested in object file output even after
2436 @command{@value{AS}} gives an error message on your program, use the @samp{-Z}
2437 option.  If there are any errors, @command{@value{AS}} continues anyways, and
2438 writes an object file after a final warning message of the form @samp{@var{n}
2439 errors, @var{m} warnings, generating bad object file.}
2440
2441 @node Syntax
2442 @chapter Syntax
2443
2444 @cindex machine-independent syntax
2445 @cindex syntax, machine-independent
2446 This chapter describes the machine-independent syntax allowed in a
2447 source file.  @command{@value{AS}} syntax is similar to what many other
2448 assemblers use; it is inspired by the BSD 4.2
2449 @ifclear VAX
2450 assembler.
2451 @end ifclear
2452 @ifset VAX
2453 assembler, except that @command{@value{AS}} does not assemble Vax bit-fields.
2454 @end ifset
2455
2456 @menu
2457 * Preprocessing::               Preprocessing
2458 * Whitespace::                  Whitespace
2459 * Comments::                    Comments
2460 * Symbol Intro::                Symbols
2461 * Statements::                  Statements
2462 * Constants::                   Constants
2463 @end menu
2464
2465 @node Preprocessing
2466 @section Preprocessing
2467
2468 @cindex preprocessing
2469 The @command{@value{AS}} internal preprocessor:
2470 @itemize @bullet
2471 @cindex whitespace, removed by preprocessor
2472 @item
2473 adjusts and removes extra whitespace.  It leaves one space or tab before
2474 the keywords on a line, and turns any other whitespace on the line into
2475 a single space.
2476
2477 @cindex comments, removed by preprocessor
2478 @item
2479 removes all comments, replacing them with a single space, or an
2480 appropriate number of newlines.
2481
2482 @cindex constants, converted by preprocessor
2483 @item
2484 converts character constants into the appropriate numeric values.
2485 @end itemize
2486
2487 It does not do macro processing, include file handling, or
2488 anything else you may get from your C compiler's preprocessor.  You can
2489 do include file processing with the @code{.include} directive
2490 (@pxref{Include,,@code{.include}}).  You can use the @sc{gnu} C compiler driver
2491 to get other ``CPP'' style preprocessing by giving the input file a
2492 @samp{.S} suffix.  @xref{Overall Options, ,Options Controlling the Kind of
2493 Output, gcc.info, Using GNU CC}.
2494
2495 Excess whitespace, comments, and character constants
2496 cannot be used in the portions of the input text that are not
2497 preprocessed.
2498
2499 @cindex turning preprocessing on and off
2500 @cindex preprocessing, turning on and off
2501 @kindex #NO_APP
2502 @kindex #APP
2503 If the first line of an input file is @code{#NO_APP} or if you use the
2504 @samp{-f} option, whitespace and comments are not removed from the input file.
2505 Within an input file, you can ask for whitespace and comment removal in
2506 specific portions of the by putting a line that says @code{#APP} before the
2507 text that may contain whitespace or comments, and putting a line that says
2508 @code{#NO_APP} after this text.  This feature is mainly intend to support
2509 @code{asm} statements in compilers whose output is otherwise free of comments
2510 and whitespace.
2511
2512 @node Whitespace
2513 @section Whitespace
2514
2515 @cindex whitespace
2516 @dfn{Whitespace} is one or more blanks or tabs, in any order.
2517 Whitespace is used to separate symbols, and to make programs neater for
2518 people to read.  Unless within character constants
2519 (@pxref{Characters,,Character Constants}), any whitespace means the same
2520 as exactly one space.
2521
2522 @node Comments
2523 @section Comments
2524
2525 @cindex comments
2526 There are two ways of rendering comments to @command{@value{AS}}.  In both
2527 cases the comment is equivalent to one space.
2528
2529 Anything from @samp{/*} through the next @samp{*/} is a comment.
2530 This means you may not nest these comments.
2531
2532 @smallexample
2533 /*
2534   The only way to include a newline ('\n') in a comment
2535   is to use this sort of comment.
2536 */
2537
2538 /* This sort of comment does not nest. */
2539 @end smallexample
2540
2541 @cindex line comment character
2542 Anything from a @dfn{line comment} character up to the next newline is
2543 considered a comment and is ignored.  The line comment character is target
2544 specific, and some targets multiple comment characters.  Some targets also have
2545 line comment characters that only work if they are the first character on a
2546 line.  Some targets use a sequence of two characters to introduce a line
2547 comment.  Some targets can also change their line comment characters depending
2548 upon command line options that have been used.  For more details see the
2549 @emph{Syntax} section in the documentation for individual targets.
2550
2551 If the line comment character is the hash sign (@samp{#}) then it still has the
2552 special ability to enable and disable preprocessing (@pxref{Preprocessing}) and
2553 to specify logical line numbers:
2554
2555 @kindex #
2556 @cindex lines starting with @code{#}
2557 @cindex logical line numbers
2558 To be compatible with past assemblers, lines that begin with @samp{#} have a
2559 special interpretation.  Following the @samp{#} should be an absolute
2560 expression (@pxref{Expressions}): the logical line number of the @emph{next}
2561 line.  Then a string (@pxref{Strings, ,Strings}) is allowed: if present it is a
2562 new logical file name.  The rest of the line, if any, should be whitespace.
2563
2564 If the first non-whitespace characters on the line are not numeric,
2565 the line is ignored.  (Just like a comment.)
2566
2567 @smallexample
2568                           # This is an ordinary comment.
2569 # 42-6 "new_file_name"    # New logical file name
2570                           # This is logical line # 36.
2571 @end smallexample
2572 This feature is deprecated, and may disappear from future versions
2573 of @command{@value{AS}}.
2574
2575 @node Symbol Intro
2576 @section Symbols
2577
2578 @cindex characters used in symbols
2579 @ifclear SPECIAL-SYMS
2580 A @dfn{symbol} is one or more characters chosen from the set of all
2581 letters (both upper and lower case), digits and the three characters
2582 @samp{_.$}.
2583 @end ifclear
2584 @ifset SPECIAL-SYMS
2585 @ifclear GENERIC
2586 @ifset H8
2587 A @dfn{symbol} is one or more characters chosen from the set of all
2588 letters (both upper and lower case), digits and the three characters
2589 @samp{._$}.  (Save that, on the H8/300 only, you may not use @samp{$} in
2590 symbol names.)
2591 @end ifset
2592 @end ifclear
2593 @end ifset
2594 @ifset GENERIC
2595 On most machines, you can also use @code{$} in symbol names; exceptions
2596 are noted in @ref{Machine Dependencies}.
2597 @end ifset
2598 No symbol may begin with a digit.  Case is significant.
2599 There is no length limit: all characters are significant.  Multibyte characters
2600 are supported.  Symbols are delimited by characters not in that set, or by the
2601 beginning of a file (since the source program must end with a newline, the end
2602 of a file is not a possible symbol delimiter).  @xref{Symbols}.
2603 @cindex length of symbols
2604
2605 @node Statements
2606 @section Statements
2607
2608 @cindex statements, structure of
2609 @cindex line separator character
2610 @cindex statement separator character
2611
2612 A @dfn{statement} ends at a newline character (@samp{\n}) or a
2613 @dfn{line separator character}.  The line separator character is target
2614 specific and described in the @emph{Syntax} section of each
2615 target's documentation.  Not all targets support a line separator character.
2616 The newline or line separator character is considered to be part of the
2617 preceding statement.  Newlines and separators within character constants are an
2618 exception: they do not end statements.
2619
2620 @cindex newline, required at file end
2621 @cindex EOF, newline must precede
2622 It is an error to end any statement with end-of-file:  the last
2623 character of any input file should be a newline.@refill
2624
2625 An empty statement is allowed, and may include whitespace.  It is ignored.
2626
2627 @cindex instructions and directives
2628 @cindex directives and instructions
2629 @c "key symbol" is not used elsewhere in the document; seems pedantic to
2630 @c @defn{} it in that case, as was done previously...  doc@cygnus.com,
2631 @c 13feb91.
2632 A statement begins with zero or more labels, optionally followed by a
2633 key symbol which determines what kind of statement it is.  The key
2634 symbol determines the syntax of the rest of the statement.  If the
2635 symbol begins with a dot @samp{.} then the statement is an assembler
2636 directive: typically valid for any computer.  If the symbol begins with
2637 a letter the statement is an assembly language @dfn{instruction}: it
2638 assembles into a machine language instruction.
2639 @ifset GENERIC
2640 Different versions of @command{@value{AS}} for different computers
2641 recognize different instructions.  In fact, the same symbol may
2642 represent a different instruction in a different computer's assembly
2643 language.@refill
2644 @end ifset
2645
2646 @cindex @code{:} (label)
2647 @cindex label (@code{:})
2648 A label is a symbol immediately followed by a colon (@code{:}).
2649 Whitespace before a label or after a colon is permitted, but you may not
2650 have whitespace between a label's symbol and its colon. @xref{Labels}.
2651
2652 @ifset HPPA
2653 For HPPA targets, labels need not be immediately followed by a colon, but
2654 the definition of a label must begin in column zero.  This also implies that
2655 only one label may be defined on each line.
2656 @end ifset
2657
2658 @smallexample
2659 label:     .directive    followed by something
2660 another_label:           # This is an empty statement.
2661            instruction   operand_1, operand_2, @dots{}
2662 @end smallexample
2663
2664 @node Constants
2665 @section Constants
2666
2667 @cindex constants
2668 A constant is a number, written so that its value is known by
2669 inspection, without knowing any context.  Like this:
2670 @smallexample
2671 @group
2672 .byte  74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
2673 .ascii "Ring the bell\7"                  # A string constant.
2674 .octa  0x123456789abcdef0123456789ABCDEF0 # A bignum.
2675 .float 0f-314159265358979323846264338327\
2676 95028841971.693993751E-40                 # - pi, a flonum.
2677 @end group
2678 @end smallexample
2679
2680 @menu
2681 * Characters::                  Character Constants
2682 * Numbers::                     Number Constants
2683 @end menu
2684
2685 @node Characters
2686 @subsection Character Constants
2687
2688 @cindex character constants
2689 @cindex constants, character
2690 There are two kinds of character constants.  A @dfn{character} stands
2691 for one character in one byte and its value may be used in
2692 numeric expressions.  String constants (properly called string
2693 @emph{literals}) are potentially many bytes and their values may not be
2694 used in arithmetic expressions.
2695
2696 @menu
2697 * Strings::                     Strings
2698 * Chars::                       Characters
2699 @end menu
2700
2701 @node Strings
2702 @subsubsection Strings
2703
2704 @cindex string constants
2705 @cindex constants, string
2706 A @dfn{string} is written between double-quotes.  It may contain
2707 double-quotes or null characters.  The way to get special characters
2708 into a string is to @dfn{escape} these characters: precede them with
2709 a backslash @samp{\} character.  For example @samp{\\} represents
2710 one backslash:  the first @code{\} is an escape which tells
2711 @command{@value{AS}} to interpret the second character literally as a backslash
2712 (which prevents @command{@value{AS}} from recognizing the second @code{\} as an
2713 escape character).  The complete list of escapes follows.
2714
2715 @cindex escape codes, character
2716 @cindex character escape codes
2717 @table @kbd
2718 @c      @item \a
2719 @c      Mnemonic for ACKnowledge; for ASCII this is octal code 007.
2720 @c
2721 @cindex @code{\b} (backspace character)
2722 @cindex backspace (@code{\b})
2723 @item \b
2724 Mnemonic for backspace; for ASCII this is octal code 010.
2725
2726 @c      @item \e
2727 @c      Mnemonic for EOText; for ASCII this is octal code 004.
2728 @c
2729 @cindex @code{\f} (formfeed character)
2730 @cindex formfeed (@code{\f})
2731 @item \f
2732 Mnemonic for FormFeed; for ASCII this is octal code 014.
2733
2734 @cindex @code{\n} (newline character)
2735 @cindex newline (@code{\n})
2736 @item \n
2737 Mnemonic for newline; for ASCII this is octal code 012.
2738
2739 @c      @item \p
2740 @c      Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
2741 @c
2742 @cindex @code{\r} (carriage return character)
2743 @cindex carriage return (@code{\r})
2744 @item \r
2745 Mnemonic for carriage-Return; for ASCII this is octal code 015.
2746
2747 @c      @item \s
2748 @c      Mnemonic for space; for ASCII this is octal code 040.  Included for compliance with
2749 @c      other assemblers.
2750 @c
2751 @cindex @code{\t} (tab)
2752 @cindex tab (@code{\t})
2753 @item \t
2754 Mnemonic for horizontal Tab; for ASCII this is octal code 011.
2755
2756 @c      @item \v
2757 @c      Mnemonic for Vertical tab; for ASCII this is octal code 013.
2758 @c      @item \x @var{digit} @var{digit} @var{digit}
2759 @c      A hexadecimal character code.  The numeric code is 3 hexadecimal digits.
2760 @c
2761 @cindex @code{\@var{ddd}} (octal character code)
2762 @cindex octal character code (@code{\@var{ddd}})
2763 @item \ @var{digit} @var{digit} @var{digit}
2764 An octal character code.  The numeric code is 3 octal digits.
2765 For compatibility with other Unix systems, 8 and 9 are accepted as digits:
2766 for example, @code{\008} has the value 010, and @code{\009} the value 011.
2767
2768 @cindex @code{\@var{xd...}} (hex character code)
2769 @cindex hex character code (@code{\@var{xd...}})
2770 @item \@code{x} @var{hex-digits...}
2771 A hex character code.  All trailing hex digits are combined.  Either upper or
2772 lower case @code{x} works.
2773
2774 @cindex @code{\\} (@samp{\} character)
2775 @cindex backslash (@code{\\})
2776 @item \\
2777 Represents one @samp{\} character.
2778
2779 @c      @item \'
2780 @c      Represents one @samp{'} (accent acute) character.
2781 @c      This is needed in single character literals
2782 @c      (@xref{Characters,,Character Constants}.) to represent
2783 @c      a @samp{'}.
2784 @c
2785 @cindex @code{\"} (doublequote character)
2786 @cindex doublequote (@code{\"})
2787 @item \"
2788 Represents one @samp{"} character.  Needed in strings to represent
2789 this character, because an unescaped @samp{"} would end the string.
2790
2791 @item \ @var{anything-else}
2792 Any other character when escaped by @kbd{\} gives a warning, but
2793 assembles as if the @samp{\} was not present.  The idea is that if
2794 you used an escape sequence you clearly didn't want the literal
2795 interpretation of the following character.  However @command{@value{AS}} has no
2796 other interpretation, so @command{@value{AS}} knows it is giving you the wrong
2797 code and warns you of the fact.
2798 @end table
2799
2800 Which characters are escapable, and what those escapes represent,
2801 varies widely among assemblers.  The current set is what we think
2802 the BSD 4.2 assembler recognizes, and is a subset of what most C
2803 compilers recognize.  If you are in doubt, do not use an escape
2804 sequence.
2805
2806 @node Chars
2807 @subsubsection Characters
2808
2809 @cindex single character constant
2810 @cindex character, single
2811 @cindex constant, single character
2812 A single character may be written as a single quote immediately
2813 followed by that character.  The same escapes apply to characters as
2814 to strings.  So if you want to write the character backslash, you
2815 must write @kbd{'\\} where the first @code{\} escapes the second
2816 @code{\}.  As you can see, the quote is an acute accent, not a
2817 grave accent.  A newline
2818 @ifclear GENERIC
2819 @ifclear abnormal-separator
2820 (or semicolon @samp{;})
2821 @end ifclear
2822 @ifset abnormal-separator
2823 @ifset H8
2824 (or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
2825 Renesas SH)
2826 @end ifset
2827 @end ifset
2828 @end ifclear
2829 immediately following an acute accent is taken as a literal character
2830 and does not count as the end of a statement.  The value of a character
2831 constant in a numeric expression is the machine's byte-wide code for
2832 that character.  @command{@value{AS}} assumes your character code is ASCII:
2833 @kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
2834
2835 @node Numbers
2836 @subsection Number Constants
2837
2838 @cindex constants, number
2839 @cindex number constants
2840 @command{@value{AS}} distinguishes three kinds of numbers according to how they
2841 are stored in the target machine.  @emph{Integers} are numbers that
2842 would fit into an @code{int} in the C language.  @emph{Bignums} are
2843 integers, but they are stored in more than 32 bits.  @emph{Flonums}
2844 are floating point numbers, described below.
2845
2846 @menu
2847 * Integers::                    Integers
2848 * Bignums::                     Bignums
2849 * Flonums::                     Flonums
2850 @ifclear GENERIC
2851 @ifset I960
2852 * Bit Fields::                  Bit Fields
2853 @end ifset
2854 @end ifclear
2855 @end menu
2856
2857 @node Integers
2858 @subsubsection Integers
2859 @cindex integers
2860 @cindex constants, integer
2861
2862 @cindex binary integers
2863 @cindex integers, binary
2864 A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
2865 the binary digits @samp{01}.
2866
2867 @cindex octal integers
2868 @cindex integers, octal
2869 An octal integer is @samp{0} followed by zero or more of the octal
2870 digits (@samp{01234567}).
2871
2872 @cindex decimal integers
2873 @cindex integers, decimal
2874 A decimal integer starts with a non-zero digit followed by zero or
2875 more digits (@samp{0123456789}).
2876
2877 @cindex hexadecimal integers
2878 @cindex integers, hexadecimal
2879 A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
2880 more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
2881
2882 Integers have the usual values.  To denote a negative integer, use
2883 the prefix operator @samp{-} discussed under expressions
2884 (@pxref{Prefix Ops,,Prefix Operators}).
2885
2886 @node Bignums
2887 @subsubsection Bignums
2888
2889 @cindex bignums
2890 @cindex constants, bignum
2891 A @dfn{bignum} has the same syntax and semantics as an integer
2892 except that the number (or its negative) takes more than 32 bits to
2893 represent in binary.  The distinction is made because in some places
2894 integers are permitted while bignums are not.
2895
2896 @node Flonums
2897 @subsubsection Flonums
2898 @cindex flonums
2899 @cindex floating point numbers
2900 @cindex constants, floating point
2901
2902 @cindex precision, floating point
2903 A @dfn{flonum} represents a floating point number.  The translation is
2904 indirect: a decimal floating point number from the text is converted by
2905 @command{@value{AS}} to a generic binary floating point number of more than
2906 sufficient precision.  This generic floating point number is converted
2907 to a particular computer's floating point format (or formats) by a
2908 portion of @command{@value{AS}} specialized to that computer.
2909
2910 A flonum is written by writing (in order)
2911 @itemize @bullet
2912 @item
2913 The digit @samp{0}.
2914 @ifset HPPA
2915 (@samp{0} is optional on the HPPA.)
2916 @end ifset
2917
2918 @item
2919 A letter, to tell @command{@value{AS}} the rest of the number is a flonum.
2920 @ifset GENERIC
2921 @kbd{e} is recommended.  Case is not important.
2922 @ignore
2923 @c FIXME: verify if flonum syntax really this vague for most cases
2924 (Any otherwise illegal letter works here, but that might be changed.  Vax BSD
2925 4.2 assembler seems to allow any of @samp{defghDEFGH}.)
2926 @end ignore
2927
2928 On the H8/300, Renesas / SuperH SH,
2929 and AMD 29K architectures, the letter must be
2930 one of the letters @samp{DFPRSX} (in upper or lower case).
2931
2932 On the ARC, the letter must be one of the letters @samp{DFRS}
2933 (in upper or lower case).
2934
2935 On the Intel 960 architecture, the letter must be
2936 one of the letters @samp{DFT} (in upper or lower case).
2937
2938 On the HPPA architecture, the letter must be @samp{E} (upper case only).
2939 @end ifset
2940 @ifclear GENERIC
2941 @ifset ARC
2942 One of the letters @samp{DFRS} (in upper or lower case).
2943 @end ifset
2944 @ifset H8
2945 One of the letters @samp{DFPRSX} (in upper or lower case).
2946 @end ifset
2947 @ifset HPPA
2948 The letter @samp{E} (upper case only).
2949 @end ifset
2950 @ifset I960
2951 One of the letters @samp{DFT} (in upper or lower case).
2952 @end ifset
2953 @end ifclear
2954
2955 @item
2956 An optional sign: either @samp{+} or @samp{-}.
2957
2958 @item
2959 An optional @dfn{integer part}: zero or more decimal digits.
2960
2961 @item
2962 An optional @dfn{fractional part}: @samp{.} followed by zero
2963 or more decimal digits.
2964
2965 @item
2966 An optional exponent, consisting of:
2967
2968 @itemize @bullet
2969 @item
2970 An @samp{E} or @samp{e}.
2971 @c I can't find a config where "EXP_CHARS" is other than 'eE', but in
2972 @c principle this can perfectly well be different on different targets.
2973 @item
2974 Optional sign: either @samp{+} or @samp{-}.
2975 @item
2976 One or more decimal digits.
2977 @end itemize
2978
2979 @end itemize
2980
2981 At least one of the integer part or the fractional part must be
2982 present.  The floating point number has the usual base-10 value.
2983
2984 @command{@value{AS}} does all processing using integers.  Flonums are computed
2985 independently of any floating point hardware in the computer running
2986 @command{@value{AS}}.
2987
2988 @ifclear GENERIC
2989 @ifset I960
2990 @c Bit fields are written as a general facility but are also controlled
2991 @c by a conditional-compilation flag---which is as of now (21mar91)
2992 @c turned on only by the i960 config of GAS.
2993 @node Bit Fields
2994 @subsubsection Bit Fields
2995
2996 @cindex bit fields
2997 @cindex constants, bit field
2998 You can also define numeric constants as @dfn{bit fields}.
2999 Specify two numbers separated by a colon---
3000 @example
3001 @var{mask}:@var{value}
3002 @end example
3003 @noindent
3004 @command{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
3005 @var{value}.
3006
3007 The resulting number is then packed
3008 @ifset GENERIC
3009 @c this conditional paren in case bit fields turned on elsewhere than 960
3010 (in host-dependent byte order)
3011 @end ifset
3012 into a field whose width depends on which assembler directive has the
3013 bit-field as its argument.  Overflow (a result from the bitwise and
3014 requiring more binary digits to represent) is not an error; instead,
3015 more constants are generated, of the specified width, beginning with the
3016 least significant digits.@refill
3017
3018 The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
3019 @code{.short}, and @code{.word} accept bit-field arguments.
3020 @end ifset
3021 @end ifclear
3022
3023 @node Sections
3024 @chapter Sections and Relocation
3025 @cindex sections
3026 @cindex relocation
3027
3028 @menu
3029 * Secs Background::             Background
3030 * Ld Sections::                 Linker Sections
3031 * As Sections::                 Assembler Internal Sections
3032 * Sub-Sections::                Sub-Sections
3033 * bss::                         bss Section
3034 @end menu
3035
3036 @node Secs Background
3037 @section Background
3038
3039 Roughly, a section is a range of addresses, with no gaps; all data
3040 ``in'' those addresses is treated the same for some particular purpose.
3041 For example there may be a ``read only'' section.
3042
3043 @cindex linker, and assembler
3044 @cindex assembler, and linker
3045 The linker @code{@value{LD}} reads many object files (partial programs) and
3046 combines their contents to form a runnable program.  When @command{@value{AS}}
3047 emits an object file, the partial program is assumed to start at address 0.
3048 @code{@value{LD}} assigns the final addresses for the partial program, so that
3049 different partial programs do not overlap.  This is actually an
3050 oversimplification, but it suffices to explain how @command{@value{AS}} uses
3051 sections.
3052
3053 @code{@value{LD}} moves blocks of bytes of your program to their run-time
3054 addresses.  These blocks slide to their run-time addresses as rigid
3055 units; their length does not change and neither does the order of bytes
3056 within them.  Such a rigid unit is called a @emph{section}.  Assigning
3057 run-time addresses to sections is called @dfn{relocation}.  It includes
3058 the task of adjusting mentions of object-file addresses so they refer to
3059 the proper run-time addresses.
3060 @ifset H8
3061 For the H8/300, and for the Renesas / SuperH SH,
3062 @command{@value{AS}} pads sections if needed to
3063 ensure they end on a word (sixteen bit) boundary.
3064 @end ifset
3065
3066 @cindex standard assembler sections
3067 An object file written by @command{@value{AS}} has at least three sections, any
3068 of which may be empty.  These are named @dfn{text}, @dfn{data} and
3069 @dfn{bss} sections.
3070
3071 @ifset COFF-ELF
3072 @ifset GENERIC
3073 When it generates COFF or ELF output,
3074 @end ifset
3075 @command{@value{AS}} can also generate whatever other named sections you specify
3076 using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
3077 If you do not use any directives that place output in the @samp{.text}
3078 or @samp{.data} sections, these sections still exist, but are empty.
3079 @end ifset
3080
3081 @ifset HPPA
3082 @ifset GENERIC
3083 When @command{@value{AS}} generates SOM or ELF output for the HPPA,
3084 @end ifset
3085 @command{@value{AS}} can also generate whatever other named sections you
3086 specify using the @samp{.space} and @samp{.subspace} directives.  See
3087 @cite{HP9000 Series 800 Assembly Language Reference Manual}
3088 (HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
3089 assembler directives.
3090
3091 @ifset SOM
3092 Additionally, @command{@value{AS}} uses different names for the standard
3093 text, data, and bss sections when generating SOM output.  Program text
3094 is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
3095 BSS into @samp{$BSS$}.
3096 @end ifset
3097 @end ifset
3098
3099 Within the object file, the text section starts at address @code{0}, the
3100 data section follows, and the bss section follows the data section.
3101
3102 @ifset HPPA
3103 When generating either SOM or ELF output files on the HPPA, the text
3104 section starts at address @code{0}, the data section at address
3105 @code{0x4000000}, and the bss section follows the data section.
3106 @end ifset
3107
3108 To let @code{@value{LD}} know which data changes when the sections are
3109 relocated, and how to change that data, @command{@value{AS}} also writes to the
3110 object file details of the relocation needed.  To perform relocation
3111 @code{@value{LD}} must know, each time an address in the object
3112 file is mentioned:
3113 @itemize @bullet
3114 @item
3115 Where in the object file is the beginning of this reference to
3116 an address?
3117 @item
3118 How long (in bytes) is this reference?
3119 @item
3120 Which section does the address refer to?  What is the numeric value of
3121 @display
3122 (@var{address}) @minus{} (@var{start-address of section})?
3123 @end display
3124 @item
3125 Is the reference to an address ``Program-Counter relative''?
3126 @end itemize
3127
3128 @cindex addresses, format of
3129 @cindex section-relative addressing
3130 In fact, every address @command{@value{AS}} ever uses is expressed as
3131 @display
3132 (@var{section}) + (@var{offset into section})
3133 @end display
3134 @noindent
3135 Further, most expressions @command{@value{AS}} computes have this section-relative
3136 nature.
3137 @ifset SOM
3138 (For some object formats, such as SOM for the HPPA, some expressions are
3139 symbol-relative instead.)
3140 @end ifset
3141
3142 In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset
3143 @var{N} into section @var{secname}.''
3144
3145 Apart from text, data and bss sections you need to know about the
3146 @dfn{absolute} section.  When @code{@value{LD}} mixes partial programs,
3147 addresses in the absolute section remain unchanged.  For example, address
3148 @code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
3149 @code{@value{LD}}.  Although the linker never arranges two partial programs'
3150 data sections with overlapping addresses after linking, @emph{by definition}
3151 their absolute sections must overlap.  Address @code{@{absolute@ 239@}} in one
3152 part of a program is always the same address when the program is running as
3153 address @code{@{absolute@ 239@}} in any other part of the program.
3154
3155 The idea of sections is extended to the @dfn{undefined} section.  Any
3156 address whose section is unknown at assembly time is by definition
3157 rendered @{undefined @var{U}@}---where @var{U} is filled in later.
3158 Since numbers are always defined, the only way to generate an undefined
3159 address is to mention an undefined symbol.  A reference to a named
3160 common block would be such a symbol: its value is unknown at assembly
3161 time so it has section @emph{undefined}.
3162
3163 By analogy the word @emph{section} is used to describe groups of sections in
3164 the linked program.  @code{@value{LD}} puts all partial programs' text
3165 sections in contiguous addresses in the linked program.  It is
3166 customary to refer to the @emph{text section} of a program, meaning all
3167 the addresses of all partial programs' text sections.  Likewise for
3168 data and bss sections.
3169
3170 Some sections are manipulated by @code{@value{LD}}; others are invented for
3171 use of @command{@value{AS}} and have no meaning except during assembly.
3172
3173 @node Ld Sections
3174 @section Linker Sections
3175 @code{@value{LD}} deals with just four kinds of sections, summarized below.
3176
3177 @table @strong
3178
3179 @ifset COFF-ELF
3180 @cindex named sections
3181 @cindex sections, named
3182 @item named sections
3183 @end ifset
3184 @ifset aout-bout
3185 @cindex text section
3186 @cindex data section
3187 @itemx text section
3188 @itemx data section
3189 @end ifset
3190 These sections hold your program.  @command{@value{AS}} and @code{@value{LD}} treat them as
3191 separate but equal sections.  Anything you can say of one section is
3192 true of another.
3193 @c @ifset aout-bout
3194 When the program is running, however, it is
3195 customary for the text section to be unalterable.  The
3196 text section is often shared among processes: it contains
3197 instructions, constants and the like.  The data section of a running
3198 program is usually alterable: for example, C variables would be stored
3199 in the data section.
3200 @c @end ifset
3201
3202 @cindex bss section
3203 @item bss section
3204 This section contains zeroed bytes when your program begins running.  It
3205 is used to hold uninitialized variables or common storage.  The length of
3206 each partial program's bss section is important, but because it starts
3207 out containing zeroed bytes there is no need to store explicit zero
3208 bytes in the object file.  The bss section was invented to eliminate
3209 those explicit zeros from object files.
3210
3211 @cindex absolute section
3212 @item absolute section
3213 Address 0 of this section is always ``relocated'' to runtime address 0.
3214 This is useful if you want to refer to an address that @code{@value{LD}} must
3215 not change when relocating.  In this sense we speak of absolute
3216 addresses being ``unrelocatable'': they do not change during relocation.
3217
3218 @cindex undefined section
3219 @item undefined section
3220 This ``section'' is a catch-all for address references to objects not in
3221 the preceding sections.
3222 @c FIXME: ref to some other doc on obj-file formats could go here.
3223 @end table
3224
3225 @cindex relocation example
3226 An idealized example of three relocatable sections follows.
3227 @ifset COFF-ELF
3228 The example uses the traditional section names @samp{.text} and @samp{.data}.
3229 @end ifset
3230 Memory addresses are on the horizontal axis.
3231
3232 @c TEXI2ROFF-KILL
3233 @ifnottex
3234 @c END TEXI2ROFF-KILL
3235 @smallexample
3236                       +-----+----+--+
3237 partial program # 1:  |ttttt|dddd|00|
3238                       +-----+----+--+
3239
3240                       text   data bss
3241                       seg.   seg. seg.
3242
3243                       +---+---+---+
3244 partial program # 2:  |TTT|DDD|000|
3245                       +---+---+---+
3246
3247                       +--+---+-----+--+----+---+-----+~~
3248 linked program:       |  |TTT|ttttt|  |dddd|DDD|00000|
3249                       +--+---+-----+--+----+---+-----+~~
3250
3251     addresses:        0 @dots{}
3252 @end smallexample
3253 @c TEXI2ROFF-KILL
3254 @end ifnottex
3255 @need 5000
3256 @tex
3257 \bigskip
3258 \line{\it Partial program \#1: \hfil}
3259 \line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
3260 \line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
3261
3262 \line{\it Partial program \#2: \hfil}
3263 \line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
3264 \line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
3265
3266 \line{\it linked program: \hfil}
3267 \line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
3268 \line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
3269 ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
3270 DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
3271
3272 \line{\it addresses: \hfil}
3273 \line{0\dots\hfil}
3274
3275 @end tex
3276 @c END TEXI2ROFF-KILL
3277
3278 @node As Sections
3279 @section Assembler Internal Sections
3280
3281 @cindex internal assembler sections
3282 @cindex sections in messages, internal
3283 These sections are meant only for the internal use of @command{@value{AS}}.  They
3284 have no meaning at run-time.  You do not really need to know about these
3285 sections for most purposes; but they can be mentioned in @command{@value{AS}}
3286 warning messages, so it might be helpful to have an idea of their
3287 meanings to @command{@value{AS}}.  These sections are used to permit the
3288 value of every expression in your assembly language program to be a
3289 section-relative address.
3290
3291 @table @b
3292 @cindex assembler internal logic error
3293 @item ASSEMBLER-INTERNAL-LOGIC-ERROR!
3294 An internal assembler logic error has been found.  This means there is a
3295 bug in the assembler.
3296
3297 @cindex expr (internal section)
3298 @item expr section
3299 The assembler stores complex expression internally as combinations of
3300 symbols.  When it needs to represent an expression as a symbol, it puts
3301 it in the expr section.
3302 @c FIXME item debug
3303 @c FIXME item transfer[t] vector preload
3304 @c FIXME item transfer[t] vector postload
3305 @c FIXME item register
3306 @end table
3307
3308 @node Sub-Sections
3309 @section Sub-Sections
3310
3311 @cindex numbered subsections
3312 @cindex grouping data
3313 @ifset aout-bout
3314 Assembled bytes
3315 @ifset COFF-ELF
3316 conventionally
3317 @end ifset
3318 fall into two sections: text and data.
3319 @end ifset
3320 You may have separate groups of
3321 @ifset GENERIC
3322 data in named sections
3323 @end ifset
3324 @ifclear GENERIC
3325 @ifclear aout-bout
3326 data in named sections
3327 @end ifclear
3328 @ifset aout-bout
3329 text or data
3330 @end ifset
3331 @end ifclear
3332 that you want to end up near to each other in the object file, even though they
3333 are not contiguous in the assembler source.  @command{@value{AS}} allows you to
3334 use @dfn{subsections} for this purpose.  Within each section, there can be
3335 numbered subsections with values from 0 to 8192.  Objects assembled into the
3336 same subsection go into the object file together with other objects in the same
3337 subsection.  For example, a compiler might want to store constants in the text
3338 section, but might not want to have them interspersed with the program being
3339 assembled.  In this case, the compiler could issue a @samp{.text 0} before each
3340 section of code being output, and a @samp{.text 1} before each group of
3341 constants being output.
3342
3343 Subsections are optional.  If you do not use subsections, everything
3344 goes in subsection number zero.
3345
3346 @ifset GENERIC
3347 Each subsection is zero-padded up to a multiple of four bytes.
3348 (Subsections may be padded a different amount on different flavors
3349 of @command{@value{AS}}.)
3350 @end ifset
3351 @ifclear GENERIC
3352 @ifset H8
3353 On the H8/300 platform, each subsection is zero-padded to a word
3354 boundary (two bytes).
3355 The same is true on the Renesas SH.
3356 @end ifset
3357 @ifset I960
3358 @c FIXME section padding (alignment)?
3359 @c Rich Pixley says padding here depends on target obj code format; that
3360 @c doesn't seem particularly useful to say without further elaboration,
3361 @c so for now I say nothing about it.  If this is a generic BFD issue,
3362 @c these paragraphs might need to vanish from this manual, and be
3363 @c discussed in BFD chapter of binutils (or some such).
3364 @end ifset
3365 @end ifclear
3366
3367 Subsections appear in your object file in numeric order, lowest numbered
3368 to highest.  (All this to be compatible with other people's assemblers.)
3369 The object file contains no representation of subsections; @code{@value{LD}} and
3370 other programs that manipulate object files see no trace of them.
3371 They just see all your text subsections as a text section, and all your
3372 data subsections as a data section.
3373
3374 To specify which subsection you want subsequent statements assembled
3375 into, use a numeric argument to specify it, in a @samp{.text
3376 @var{expression}} or a @samp{.data @var{expression}} statement.
3377 @ifset COFF
3378 @ifset GENERIC
3379 When generating COFF output, you
3380 @end ifset
3381 @ifclear GENERIC
3382 You
3383 @end ifclear
3384 can also use an extra subsection
3385 argument with arbitrary named sections: @samp{.section @var{name},
3386 @var{expression}}.
3387 @end ifset
3388 @ifset ELF
3389 @ifset GENERIC
3390 When generating ELF output, you
3391 @end ifset
3392 @ifclear GENERIC
3393 You
3394 @end ifclear
3395 can also use the @code{.subsection} directive (@pxref{SubSection})
3396 to specify a subsection: @samp{.subsection @var{expression}}.
3397 @end ifset
3398 @var{Expression} should be an absolute expression
3399 (@pxref{Expressions}).  If you just say @samp{.text} then @samp{.text 0}
3400 is assumed.  Likewise @samp{.data} means @samp{.data 0}.  Assembly
3401 begins in @code{text 0}.  For instance:
3402 @smallexample
3403 .text 0     # The default subsection is text 0 anyway.
3404 .ascii "This lives in the first text subsection. *"
3405 .text 1
3406 .ascii "But this lives in the second text subsection."
3407 .data 0
3408 .ascii "This lives in the data section,"
3409 .ascii "in the first data subsection."
3410 .text 0
3411 .ascii "This lives in the first text section,"
3412 .ascii "immediately following the asterisk (*)."
3413 @end smallexample
3414
3415 Each section has a @dfn{location counter} incremented by one for every byte
3416 assembled into that section.  Because subsections are merely a convenience
3417 restricted to @command{@value{AS}} there is no concept of a subsection location
3418 counter.  There is no way to directly manipulate a location counter---but the
3419 @code{.align} directive changes it, and any label definition captures its
3420 current value.  The location counter of the section where statements are being
3421 assembled is said to be the @dfn{active} location counter.
3422
3423 @node bss
3424 @section bss Section
3425
3426 @cindex bss section
3427 @cindex common variable storage
3428 The bss section is used for local common variable storage.
3429 You may allocate address space in the bss section, but you may
3430 not dictate data to load into it before your program executes.  When
3431 your program starts running, all the contents of the bss
3432 section are zeroed bytes.
3433
3434 The @code{.lcomm} pseudo-op defines a symbol in the bss section; see
3435 @ref{Lcomm,,@code{.lcomm}}.
3436
3437 The @code{.comm} pseudo-op may be used to declare a common symbol, which is
3438 another form of uninitialized symbol; see @ref{Comm,,@code{.comm}}.
3439
3440 @ifset GENERIC
3441 When assembling for a target which supports multiple sections, such as ELF or
3442 COFF, you may switch into the @code{.bss} section and define symbols as usual;
3443 see @ref{Section,,@code{.section}}.  You may only assemble zero values into the
3444 section.  Typically the section will only contain symbol definitions and
3445 @code{.skip} directives (@pxref{Skip,,@code{.skip}}).
3446 @end ifset
3447
3448 @node Symbols
3449 @chapter Symbols
3450
3451 @cindex symbols
3452 Symbols are a central concept: the programmer uses symbols to name
3453 things, the linker uses symbols to link, and the debugger uses symbols
3454 to debug.
3455
3456 @quotation
3457 @cindex debuggers, and symbol order
3458 @emph{Warning:} @command{@value{AS}} does not place symbols in the object file in
3459 the same order they were declared.  This may break some debuggers.
3460 @end quotation
3461
3462 @menu
3463 * Labels::                      Labels
3464 * Setting Symbols::             Giving Symbols Other Values
3465 * Symbol Names::                Symbol Names
3466 * Dot::                         The Special Dot Symbol
3467 * Symbol Attributes::           Symbol Attributes
3468 @end menu
3469
3470 @node Labels
3471 @section Labels
3472
3473 @cindex labels
3474 A @dfn{label} is written as a symbol immediately followed by a colon
3475 @samp{:}.  The symbol then represents the current value of the
3476 active location counter, and is, for example, a suitable instruction
3477 operand.  You are warned if you use the same symbol to represent two
3478 different locations: the first definition overrides any other
3479 definitions.
3480
3481 @ifset HPPA
3482 On the HPPA, the usual form for a label need not be immediately followed by a
3483 colon, but instead must start in column zero.  Only one label may be defined on
3484 a single line.  To work around this, the HPPA version of @command{@value{AS}} also
3485 provides a special directive @code{.label} for defining labels more flexibly.
3486 @end ifset
3487
3488 @node Setting Symbols
3489 @section Giving Symbols Other Values
3490
3491 @cindex assigning values to symbols
3492 @cindex symbol values, assigning
3493 A symbol can be given an arbitrary value by writing a symbol, followed
3494 by an equals sign @samp{=}, followed by an expression
3495 (@pxref{Expressions}).  This is equivalent to using the @code{.set}
3496 directive.  @xref{Set,,@code{.set}}.  In the same way, using a double
3497 equals sign @samp{=}@samp{=} here represents an equivalent of the
3498 @code{.eqv} directive.  @xref{Eqv,,@code{.eqv}}.
3499
3500 @ifset Blackfin
3501 Blackfin does not support symbol assignment with @samp{=}.
3502 @end ifset
3503
3504 @node Symbol Names
3505 @section Symbol Names
3506
3507 @cindex symbol names
3508 @cindex names, symbol
3509 @ifclear SPECIAL-SYMS
3510 Symbol names begin with a letter or with one of @samp{._}.  On most
3511 machines, you can also use @code{$} in symbol names; exceptions are
3512 noted in @ref{Machine Dependencies}.  That character may be followed by any
3513 string of digits, letters, dollar signs (unless otherwise noted for a
3514 particular target machine), and underscores.
3515 @end ifclear
3516 @ifset SPECIAL-SYMS
3517 @ifset H8
3518 Symbol names begin with a letter or with one of @samp{._}.  On the
3519 Renesas SH you can also use @code{$} in symbol names.  That
3520 character may be followed by any string of digits, letters, dollar signs (save
3521 on the H8/300), and underscores.
3522 @end ifset
3523 @end ifset
3524
3525 Case of letters is significant: @code{foo} is a different symbol name
3526 than @code{Foo}.
3527
3528 Multibyte characters are supported.  To generate a symbol name containing
3529 multibyte characters enclose it within double quotes and use escape codes. cf
3530 @xref{Strings}.  Generating a multibyte symbol name from a label is not
3531 currently supported.
3532
3533 Each symbol has exactly one name.  Each name in an assembly language program
3534 refers to exactly one symbol.  You may use that symbol name any number of times
3535 in a program.
3536
3537 @subheading Local Symbol Names
3538
3539 @cindex local symbol names
3540 @cindex symbol names, local
3541 A local symbol is any symbol beginning with certain local label prefixes.
3542 By default, the local label prefix is @samp{.L} for ELF systems or
3543 @samp{L} for traditional a.out systems, but each target may have its own
3544 set of local label prefixes.
3545 @ifset HPPA
3546 On the HPPA local symbols begin with @samp{L$}.
3547 @end ifset
3548
3549 Local symbols are defined and used within the assembler, but they are
3550 normally not saved in object files.  Thus, they are not visible when debugging.
3551 You may use the @samp{-L} option (@pxref{L, ,Include Local Symbols:
3552 @option{-L}}) to retain the local symbols in the object files.
3553
3554 @subheading Local Labels
3555
3556 @cindex local labels
3557 @cindex temporary symbol names
3558 @cindex symbol names, temporary
3559 Local labels help compilers and programmers use names temporarily.
3560 They create symbols which are guaranteed to be unique over the entire scope of
3561 the input source code and which can be referred to by a simple notation.
3562 To define a local label, write a label of the form @samp{@b{N}:} (where @b{N}
3563 represents any positive integer).  To refer to the most recent previous
3564 definition of that label write @samp{@b{N}b}, using the same number as when
3565 you defined the label.  To refer to the next definition of a local label, write
3566 @samp{@b{N}f}---the @samp{b} stands for ``backwards'' and the @samp{f} stands
3567 for ``forwards''.
3568
3569 There is no restriction on how you can use these labels, and you can reuse them
3570 too.  So that it is possible to repeatedly define the same local label (using
3571 the same number @samp{@b{N}}), although you can only refer to the most recently
3572 defined local label of that number (for a backwards reference) or the next
3573 definition of a specific local label for a forward reference.  It is also worth
3574 noting that the first 10 local labels (@samp{@b{0:}}@dots{}@samp{@b{9:}}) are
3575 implemented in a slightly more efficient manner than the others.
3576
3577 Here is an example:
3578
3579 @smallexample
3580 1:        branch 1f
3581 2:        branch 1b
3582 1:        branch 2f
3583 2:        branch 1b
3584 @end smallexample
3585
3586 Which is the equivalent of:
3587
3588 @smallexample
3589 label_1:  branch label_3
3590 label_2:  branch label_1
3591 label_3:  branch label_4
3592 label_4:  branch label_3
3593 @end smallexample
3594
3595 Local label names are only a notational device.  They are immediately
3596 transformed into more conventional symbol names before the assembler uses them.
3597 The symbol names are stored in the symbol table, appear in error messages, and
3598 are optionally emitted to the object file.  The names are constructed using
3599 these parts:
3600
3601 @table @code
3602 @item @emph{local label prefix}
3603 All local symbols begin with the system-specific local label prefix.
3604 Normally both @command{@value{AS}} and @code{@value{LD}} forget symbols
3605 that start with the local label prefix.  These labels are
3606 used for symbols you are never intended to see.  If you use the
3607 @samp{-L} option then @command{@value{AS}} retains these symbols in the
3608 object file. If you also instruct @code{@value{LD}} to retain these symbols,
3609 you may use them in debugging.
3610
3611 @item @var{number}
3612 This is the number that was used in the local label definition.  So if the
3613 label is written @samp{55:} then the number is @samp{55}.
3614
3615 @item @kbd{C-B}
3616 This unusual character is included so you do not accidentally invent a symbol
3617 of the same name.  The character has ASCII value of @samp{\002} (control-B).
3618
3619 @item @emph{ordinal number}
3620 This is a serial number to keep the labels distinct.  The first definition of
3621 @samp{0:} gets the number @samp{1}.  The 15th definition of @samp{0:} gets the
3622 number @samp{15}, and so on.  Likewise the first definition of @samp{1:} gets
3623 the number @samp{1} and its 15th definition gets @samp{15} as well.
3624 @end table
3625
3626 So for example, the first @code{1:} may be named @code{.L1@kbd{C-B}1}, and
3627 the 44th @code{3:} may be named @code{.L3@kbd{C-B}44}.
3628
3629 @subheading Dollar Local Labels
3630 @cindex dollar local symbols
3631
3632 @code{@value{AS}} also supports an even more local form of local labels called
3633 dollar labels.  These labels go out of scope (i.e., they become undefined) as
3634 soon as a non-local label is defined.  Thus they remain valid for only a small
3635 region of the input source code.  Normal local labels, by contrast, remain in
3636 scope for the entire file, or until they are redefined by another occurrence of
3637 the same local label.
3638
3639 Dollar labels are defined in exactly the same way as ordinary local labels,
3640 except that they have a dollar sign suffix to their numeric value, e.g.,
3641 @samp{@b{55$:}}.
3642
3643 They can also be distinguished from ordinary local labels by their transformed
3644 names which use ASCII character @samp{\001} (control-A) as the magic character
3645 to distinguish them from ordinary labels.  For example, the fifth definition of
3646 @samp{6$} may be named @samp{.L6@kbd{C-A}5}.
3647
3648 @node Dot
3649 @section The Special Dot Symbol
3650
3651 @cindex dot (symbol)
3652 @cindex @code{.} (symbol)
3653 @cindex current address
3654 @cindex location counter
3655 The special symbol @samp{.} refers to the current address that
3656 @command{@value{AS}} is assembling into.  Thus, the expression @samp{melvin:
3657 .long .} defines @code{melvin} to contain its own address.
3658 Assigning a value to @code{.} is treated the same as a @code{.org}
3659 directive.
3660 @ifclear no-space-dir
3661 Thus, the expression @samp{.=.+4} is the same as saying
3662 @samp{.space 4}.
3663 @end ifclear
3664
3665 @node Symbol Attributes
3666 @section Symbol Attributes
3667
3668 @cindex symbol attributes
3669 @cindex attributes, symbol
3670 Every symbol has, as well as its name, the attributes ``Value'' and
3671 ``Type''.  Depending on output format, symbols can also have auxiliary
3672 attributes.
3673 @ifset INTERNALS
3674 The detailed definitions are in @file{a.out.h}.
3675 @end ifset
3676
3677 If you use a symbol without defining it, @command{@value{AS}} assumes zero for
3678 all these attributes, and probably won't warn you.  This makes the
3679 symbol an externally defined symbol, which is generally what you
3680 would want.
3681
3682 @menu
3683 * Symbol Value::                Value
3684 * Symbol Type::                 Type
3685 @ifset aout-bout
3686 @ifset GENERIC
3687 * a.out Symbols::               Symbol Attributes: @code{a.out}
3688 @end ifset
3689 @ifclear GENERIC
3690 @ifclear BOUT
3691 * a.out Symbols::               Symbol Attributes: @code{a.out}
3692 @end ifclear
3693 @ifset BOUT
3694 * a.out Symbols::               Symbol Attributes: @code{a.out}, @code{b.out}
3695 @end ifset
3696 @end ifclear
3697 @end ifset
3698 @ifset COFF
3699 * COFF Symbols::                Symbol Attributes for COFF
3700 @end ifset
3701 @ifset SOM
3702 * SOM Symbols::                Symbol Attributes for SOM
3703 @end ifset
3704 @end menu
3705
3706 @node Symbol Value
3707 @subsection Value
3708
3709 @cindex value of a symbol
3710 @cindex symbol value
3711 The value of a symbol is (usually) 32 bits.  For a symbol which labels a
3712 location in the text, data, bss or absolute sections the value is the
3713 number of addresses from the start of that section to the label.
3714 Naturally for text, data and bss sections the value of a symbol changes
3715 as @code{@value{LD}} changes section base addresses during linking.  Absolute
3716 symbols' values do not change during linking: that is why they are
3717 called absolute.
3718
3719 The value of an undefined symbol is treated in a special way.  If it is
3720 0 then the symbol is not defined in this assembler source file, and
3721 @code{@value{LD}} tries to determine its value from other files linked into the
3722 same program.  You make this kind of symbol simply by mentioning a symbol
3723 name without defining it.  A non-zero value represents a @code{.comm}
3724 common declaration.  The value is how much common storage to reserve, in
3725 bytes (addresses).  The symbol refers to the first address of the
3726 allocated storage.
3727
3728 @node Symbol Type
3729 @subsection Type
3730
3731 @cindex type of a symbol
3732 @cindex symbol type
3733 The type attribute of a symbol contains relocation (section)
3734 information, any flag settings indicating that a symbol is external, and
3735 (optionally), other information for linkers and debuggers.  The exact
3736 format depends on the object-code output format in use.
3737
3738 @ifset aout-bout
3739 @ifclear GENERIC
3740 @ifset BOUT
3741 @c The following avoids a "widow" subsection title.  @group would be
3742 @c better if it were available outside examples.
3743 @need 1000
3744 @node a.out Symbols
3745 @subsection Symbol Attributes: @code{a.out}, @code{b.out}
3746
3747 @cindex @code{b.out} symbol attributes
3748 @cindex symbol attributes, @code{b.out}
3749 These symbol attributes appear only when @command{@value{AS}} is configured for
3750 one of the Berkeley-descended object output formats---@code{a.out} or
3751 @code{b.out}.
3752
3753 @end ifset
3754 @ifclear BOUT
3755 @node a.out Symbols
3756 @subsection Symbol Attributes: @code{a.out}
3757
3758 @cindex @code{a.out} symbol attributes
3759 @cindex symbol attributes, @code{a.out}
3760
3761 @end ifclear
3762 @end ifclear
3763 @ifset GENERIC
3764 @node a.out Symbols
3765 @subsection Symbol Attributes: @code{a.out}
3766
3767 @cindex @code{a.out} symbol attributes
3768 @cindex symbol attributes, @code{a.out}
3769
3770 @end ifset
3771 @menu
3772 * Symbol Desc::                 Descriptor
3773 * Symbol Other::                Other
3774 @end menu
3775
3776 @node Symbol Desc
3777 @subsubsection Descriptor
3778
3779 @cindex descriptor, of @code{a.out} symbol
3780 This is an arbitrary 16-bit value.  You may establish a symbol's
3781 descriptor value by using a @code{.desc} statement
3782 (@pxref{Desc,,@code{.desc}}).  A descriptor value means nothing to
3783 @command{@value{AS}}.
3784
3785 @node Symbol Other
3786 @subsubsection Other
3787
3788 @cindex other attribute, of @code{a.out} symbol
3789 This is an arbitrary 8-bit value.  It means nothing to @command{@value{AS}}.
3790 @end ifset
3791
3792 @ifset COFF
3793 @node COFF Symbols
3794 @subsection Symbol Attributes for COFF
3795
3796 @cindex COFF symbol attributes
3797 @cindex symbol attributes, COFF
3798
3799 The COFF format supports a multitude of auxiliary symbol attributes;
3800 like the primary symbol attributes, they are set between @code{.def} and
3801 @code{.endef} directives.
3802
3803 @subsubsection Primary Attributes
3804
3805 @cindex primary attributes, COFF symbols
3806 The symbol name is set with @code{.def}; the value and type,
3807 respectively, with @code{.val} and @code{.type}.
3808
3809 @subsubsection Auxiliary Attributes
3810
3811 @cindex auxiliary attributes, COFF symbols
3812 The @command{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
3813 @code{.size}, @code{.tag}, and @code{.weak} can generate auxiliary symbol
3814 table information for COFF.
3815 @end ifset
3816
3817 @ifset SOM
3818 @node SOM Symbols
3819 @subsection Symbol Attributes for SOM
3820
3821 @cindex SOM symbol attributes
3822 @cindex symbol attributes, SOM
3823
3824 The SOM format for the HPPA supports a multitude of symbol attributes set with
3825 the @code{.EXPORT} and @code{.IMPORT} directives.
3826
3827 The attributes are described in @cite{HP9000 Series 800 Assembly
3828 Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
3829 @code{EXPORT} assembler directive documentation.
3830 @end ifset
3831
3832 @node Expressions
3833 @chapter Expressions
3834
3835 @cindex expressions
3836 @cindex addresses
3837 @cindex numeric values
3838 An @dfn{expression} specifies an address or numeric value.
3839 Whitespace may precede and/or follow an expression.
3840
3841 The result of an expression must be an absolute number, or else an offset into
3842 a particular section.  If an expression is not absolute, and there is not
3843 enough information when @command{@value{AS}} sees the expression to know its
3844 section, a second pass over the source program might be necessary to interpret
3845 the expression---but the second pass is currently not implemented.
3846 @command{@value{AS}} aborts with an error message in this situation.
3847
3848 @menu
3849 * Empty Exprs::                 Empty Expressions
3850 * Integer Exprs::               Integer Expressions
3851 @end menu
3852
3853 @node Empty Exprs
3854 @section Empty Expressions
3855
3856 @cindex empty expressions
3857 @cindex expressions, empty
3858 An empty expression has no value: it is just whitespace or null.
3859 Wherever an absolute expression is required, you may omit the
3860 expression, and @command{@value{AS}} assumes a value of (absolute) 0.  This
3861 is compatible with other assemblers.
3862
3863 @node Integer Exprs
3864 @section Integer Expressions
3865
3866 @cindex integer expressions
3867 @cindex expressions, integer
3868 An @dfn{integer expression} is one or more @emph{arguments} delimited
3869 by @emph{operators}.
3870
3871 @menu
3872 * Arguments::                   Arguments
3873 * Operators::                   Operators
3874 * Prefix Ops::                  Prefix Operators
3875 * Infix Ops::                   Infix Operators
3876 @end menu
3877
3878 @node Arguments
3879 @subsection Arguments
3880
3881 @cindex expression arguments
3882 @cindex arguments in expressions
3883 @cindex operands in expressions
3884 @cindex arithmetic operands
3885 @dfn{Arguments} are symbols, numbers or subexpressions.  In other
3886 contexts arguments are sometimes called ``arithmetic operands''.  In
3887 this manual, to avoid confusing them with the ``instruction operands'' of
3888 the machine language, we use the term ``argument'' to refer to parts of
3889 expressions only, reserving the word ``operand'' to refer only to machine
3890 instruction operands.
3891
3892 Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
3893 @var{section} is one of text, data, bss, absolute,
3894 or undefined.  @var{NNN} is a signed, 2's complement 32 bit
3895 integer.
3896
3897 Numbers are usually integers.
3898
3899 A number can be a flonum or bignum.  In this case, you are warned
3900 that only the low order 32 bits are used, and @command{@value{AS}} pretends
3901 these 32 bits are an integer.  You may write integer-manipulating
3902 instructions that act on exotic constants, compatible with other
3903 assemblers.
3904
3905 @cindex subexpressions
3906 Subexpressions are a left parenthesis @samp{(} followed by an integer
3907 expression, followed by a right parenthesis @samp{)}; or a prefix
3908 operator followed by an argument.
3909
3910 @node Operators
3911 @subsection Operators
3912
3913 @cindex operators, in expressions
3914 @cindex arithmetic functions
3915 @cindex functions, in expressions
3916 @dfn{Operators} are arithmetic functions, like @code{+} or @code{%}.  Prefix
3917 operators are followed by an argument.  Infix operators appear
3918 between their arguments.  Operators may be preceded and/or followed by
3919 whitespace.
3920
3921 @node Prefix Ops
3922 @subsection Prefix Operator
3923
3924 @cindex prefix operators
3925 @command{@value{AS}} has the following @dfn{prefix operators}.  They each take
3926 one argument, which must be absolute.
3927
3928 @c the tex/end tex stuff surrounding this small table is meant to make
3929 @c it align, on the printed page, with the similar table in the next
3930 @c section (which is inside an enumerate).
3931 @tex
3932 \global\advance\leftskip by \itemindent
3933 @end tex
3934
3935 @table @code
3936 @item -
3937 @dfn{Negation}.  Two's complement negation.
3938 @item ~
3939 @dfn{Complementation}.  Bitwise not.
3940 @end table
3941
3942 @tex
3943 \global\advance\leftskip by -\itemindent
3944 @end tex
3945
3946 @node Infix Ops
3947 @subsection Infix Operators
3948
3949 @cindex infix operators
3950 @cindex operators, permitted arguments
3951 @dfn{Infix operators} take two arguments, one on either side.  Operators
3952 have precedence, but operations with equal precedence are performed left
3953 to right.  Apart from @code{+} or @option{-}, both arguments must be
3954 absolute, and the result is absolute.
3955
3956 @enumerate
3957 @cindex operator precedence
3958 @cindex precedence of operators
3959
3960 @item
3961 Highest Precedence
3962
3963 @table @code
3964 @item *
3965 @dfn{Multiplication}.
3966
3967 @item /
3968 @dfn{Division}.  Truncation is the same as the C operator @samp{/}
3969
3970 @item %
3971 @dfn{Remainder}.
3972
3973 @item <<
3974 @dfn{Shift Left}.  Same as the C operator @samp{<<}.
3975
3976 @item >>
3977 @dfn{Shift Right}.  Same as the C operator @samp{>>}.
3978 @end table
3979
3980 @item
3981 Intermediate precedence
3982
3983 @table @code
3984 @item |
3985
3986 @dfn{Bitwise Inclusive Or}.
3987
3988 @item &
3989 @dfn{Bitwise And}.
3990
3991 @item ^
3992 @dfn{Bitwise Exclusive Or}.
3993
3994 @item !
3995 @dfn{Bitwise Or Not}.
3996 @end table
3997
3998 @item
3999 Low Precedence
4000
4001 @table @code
4002 @cindex addition, permitted arguments
4003 @cindex plus, permitted arguments
4004 @cindex arguments for addition
4005 @item +
4006 @dfn{Addition}.  If either argument is absolute, the result has the section of
4007 the other argument.  You may not add together arguments from different
4008 sections.
4009
4010 @cindex subtraction, permitted arguments
4011 @cindex minus, permitted arguments
4012 @cindex arguments for subtraction
4013 @item -
4014 @dfn{Subtraction}.  If the right argument is absolute, the
4015 result has the section of the left argument.
4016 If both arguments are in the same section, the result is absolute.
4017 You may not subtract arguments from different sections.
4018 @c FIXME is there still something useful to say about undefined - undefined ?
4019
4020 @cindex comparison expressions
4021 @cindex expressions, comparison
4022 @item  ==
4023 @dfn{Is Equal To}
4024 @item <>
4025 @itemx !=
4026 @dfn{Is Not Equal To}
4027 @item <
4028 @dfn{Is Less Than}
4029 @item >
4030 @dfn{Is Greater Than}
4031 @item >=
4032 @dfn{Is Greater Than Or Equal To}
4033 @item <=
4034 @dfn{Is Less Than Or Equal To}
4035
4036 The comparison operators can be used as infix operators.  A true results has a
4037 value of -1 whereas a false result has a value of 0.   Note, these operators
4038 perform signed comparisons.
4039 @end table
4040
4041 @item Lowest Precedence
4042
4043 @table @code
4044 @item &&
4045 @dfn{Logical And}.
4046
4047 @item ||
4048 @dfn{Logical Or}.
4049
4050 These two logical operations can be used to combine the results of sub
4051 expressions.  Note, unlike the comparison operators a true result returns a
4052 value of 1 but a false results does still return 0.  Also note that the logical
4053 or operator has a slightly lower precedence than logical and.
4054
4055 @end table
4056 @end enumerate
4057
4058 In short, it's only meaningful to add or subtract the @emph{offsets} in an
4059 address; you can only have a defined section in one of the two arguments.
4060
4061 @node Pseudo Ops
4062 @chapter Assembler Directives
4063
4064 @cindex directives, machine independent
4065 @cindex pseudo-ops, machine independent
4066 @cindex machine independent directives
4067 All assembler directives have names that begin with a period (@samp{.}).
4068 The rest of the name is letters, usually in lower case.
4069
4070 This chapter discusses directives that are available regardless of the
4071 target machine configuration for the @sc{gnu} assembler.
4072 @ifset GENERIC
4073 Some machine configurations provide additional directives.
4074 @xref{Machine Dependencies}.
4075 @end ifset
4076 @ifclear GENERIC
4077 @ifset machine-directives
4078 @xref{Machine Dependencies}, for additional directives.
4079 @end ifset
4080 @end ifclear
4081
4082 @menu
4083 * Abort::                       @code{.abort}
4084 @ifset COFF
4085 * ABORT (COFF)::                @code{.ABORT}
4086 @end ifset
4087
4088 * Align::                       @code{.align @var{abs-expr} , @var{abs-expr}}
4089 * Altmacro::                    @code{.altmacro}
4090 * Ascii::                       @code{.ascii "@var{string}"}@dots{}
4091 * Asciz::                       @code{.asciz "@var{string}"}@dots{}
4092 * Balign::                      @code{.balign @var{abs-expr} , @var{abs-expr}}
4093 * Bundle directives::           @code{.bundle_align_mode @var{abs-expr}}, @code{.bundle_lock}, @code{.bundle_unlock}
4094 * Byte::                        @code{.byte @var{expressions}}
4095 * CFI directives::              @code{.cfi_startproc [simple]}, @code{.cfi_endproc}, etc.
4096 * Comm::                        @code{.comm @var{symbol} , @var{length} }
4097 * Data::                        @code{.data @var{subsection}}
4098 @ifset COFF
4099 * Def::                         @code{.def @var{name}}
4100 @end ifset
4101 @ifset aout-bout
4102 * Desc::                        @code{.desc @var{symbol}, @var{abs-expression}}
4103 @end ifset
4104 @ifset COFF
4105 * Dim::                         @code{.dim}
4106 @end ifset
4107
4108 * Double::                      @code{.double @var{flonums}}
4109 * Eject::                       @code{.eject}
4110 * Else::                        @code{.else}
4111 * Elseif::                      @code{.elseif}
4112 * End::                         @code{.end}
4113 @ifset COFF
4114 * Endef::                       @code{.endef}
4115 @end ifset
4116
4117 * Endfunc::                     @code{.endfunc}
4118 * Endif::                       @code{.endif}
4119 * Equ::                         @code{.equ @var{symbol}, @var{expression}}
4120 * Equiv::                       @code{.equiv @var{symbol}, @var{expression}}
4121 * Eqv::                         @code{.eqv @var{symbol}, @var{expression}}
4122 * Err::                         @code{.err}
4123 * Error::                       @code{.error @var{string}}
4124 * Exitm::                       @code{.exitm}
4125 * Extern::                      @code{.extern}
4126 * Fail::                        @code{.fail}
4127 * File::                        @code{.file}
4128 * Fill::                        @code{.fill @var{repeat} , @var{size} , @var{value}}
4129 * Float::                       @code{.float @var{flonums}}
4130 * Func::                        @code{.func}
4131 * Global::                      @code{.global @var{symbol}}, @code{.globl @var{symbol}}
4132 @ifset ELF
4133 * Gnu_attribute::               @code{.gnu_attribute @var{tag},@var{value}}
4134 * Hidden::                      @code{.hidden @var{names}}
4135 @end ifset
4136
4137 * hword::                       @code{.hword @var{expressions}}
4138 * Ident::                       @code{.ident}
4139 * If::                          @code{.if @var{absolute expression}}
4140 * Incbin::                      @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]}
4141 * Include::                     @code{.include "@var{file}"}
4142 * Int::                         @code{.int @var{expressions}}
4143 @ifset ELF
4144 * Internal::                    @code{.internal @var{names}}
4145 @end ifset
4146
4147 * Irp::                         @code{.irp @var{symbol},@var{values}}@dots{}
4148 * Irpc::                        @code{.irpc @var{symbol},@var{values}}@dots{}
4149 * Lcomm::                       @code{.lcomm @var{symbol} , @var{length}}
4150 * Lflags::                      @code{.lflags}
4151 @ifclear no-line-dir
4152 * Line::                        @code{.line @var{line-number}}
4153 @end ifclear
4154
4155 * Linkonce::                    @code{.linkonce [@var{type}]}
4156 * List::                        @code{.list}
4157 * Ln::                          @code{.ln @var{line-number}}
4158 * Loc::                         @code{.loc @var{fileno} @var{lineno}}
4159 * Loc_mark_labels::             @code{.loc_mark_labels @var{enable}}
4160 @ifset ELF
4161 * Local::                       @code{.local @var{names}}
4162 @end ifset
4163
4164 * Long::                        @code{.long @var{expressions}}
4165 @ignore
4166 * Lsym::                        @code{.lsym @var{symbol}, @var{expression}}
4167 @end ignore
4168
4169 * Macro::                       @code{.macro @var{name} @var{args}}@dots{}
4170 * MRI::                         @code{.mri @var{val}}
4171 * Noaltmacro::                  @code{.noaltmacro}
4172 * Nolist::                      @code{.nolist}
4173 * Octa::                        @code{.octa @var{bignums}}
4174 * Offset::                      @code{.offset @var{loc}}
4175 * Org::                         @code{.org @var{new-lc}, @var{fill}}
4176 * P2align::                     @code{.p2align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
4177 @ifset ELF
4178 * PopSection::                  @code{.popsection}
4179 * Previous::                    @code{.previous}
4180 @end ifset
4181
4182 * Print::                       @code{.print @var{string}}
4183 @ifset ELF
4184 * Protected::                   @code{.protected @var{names}}
4185 @end ifset
4186
4187 * Psize::                       @code{.psize @var{lines}, @var{columns}}
4188 * Purgem::                      @code{.purgem @var{name}}
4189 @ifset ELF
4190 * PushSection::                 @code{.pushsection @var{name}}
4191 @end ifset
4192
4193 * Quad::                        @code{.quad @var{bignums}}
4194 * Reloc::                       @code{.reloc @var{offset}, @var{reloc_name}[, @var{expression}]}
4195 * Rept::                        @code{.rept @var{count}}
4196 * Sbttl::                       @code{.sbttl "@var{subheading}"}
4197 @ifset COFF
4198 * Scl::                         @code{.scl @var{class}}
4199 @end ifset
4200 @ifset COFF-ELF
4201 * Section::                     @code{.section @var{name}[, @var{flags}]}
4202 @end ifset
4203
4204 * Set::                         @code{.set @var{symbol}, @var{expression}}
4205 * Short::                       @code{.short @var{expressions}}
4206 * Single::                      @code{.single @var{flonums}}
4207 @ifset COFF-ELF
4208 * Size::                        @code{.size [@var{name} , @var{expression}]}
4209 @end ifset
4210 @ifclear no-space-dir
4211 * Skip::                        @code{.skip @var{size} , @var{fill}}
4212 @end ifclear
4213
4214 * Sleb128::                     @code{.sleb128 @var{expressions}}
4215 @ifclear no-space-dir
4216 * Space::                       @code{.space @var{size} , @var{fill}}
4217 @end ifclear
4218 @ifset have-stabs
4219 * Stab::                        @code{.stabd, .stabn, .stabs}
4220 @end ifset
4221
4222 * String::                      @code{.string "@var{str}"}, @code{.string8 "@var{str}"}, @code{.string16 "@var{str}"}, @code{.string32 "@var{str}"}, @code{.string64 "@var{str}"}
4223 * Struct::                      @code{.struct @var{expression}}
4224 @ifset ELF
4225 * SubSection::                  @code{.subsection}
4226 * Symver::                      @code{.symver @var{name},@var{name2@@nodename}}
4227 @end ifset
4228
4229 @ifset COFF
4230 * Tag::                         @code{.tag @var{structname}}
4231 @end ifset
4232
4233 * Text::                        @code{.text @var{subsection}}
4234 * Title::                       @code{.title "@var{heading}"}
4235 @ifset COFF-ELF
4236 * Type::                        @code{.type <@var{int} | @var{name} , @var{type description}>}
4237 @end ifset
4238
4239 * Uleb128::                     @code{.uleb128 @var{expressions}}
4240 @ifset COFF
4241 * Val::                         @code{.val @var{addr}}
4242 @end ifset
4243
4244 @ifset ELF
4245 * Version::                     @code{.version "@var{string}"}
4246 * VTableEntry::                 @code{.vtable_entry @var{table}, @var{offset}}
4247 * VTableInherit::               @code{.vtable_inherit @var{child}, @var{parent}}
4248 @end ifset
4249
4250 * Warning::                     @code{.warning @var{string}}
4251 * Weak::                        @code{.weak @var{names}}
4252 * Weakref::                     @code{.weakref @var{alias}, @var{symbol}}
4253 * Word::                        @code{.word @var{expressions}}
4254 * Deprecated::                  Deprecated Directives
4255 @end menu
4256
4257 @node Abort
4258 @section @code{.abort}
4259
4260 @cindex @code{abort} directive
4261 @cindex stopping the assembly
4262 This directive stops the assembly immediately.  It is for
4263 compatibility with other assemblers.  The original idea was that the
4264 assembly language source would be piped into the assembler.  If the sender
4265 of the source quit, it could use this directive tells @command{@value{AS}} to
4266 quit also.  One day @code{.abort} will not be supported.
4267
4268 @ifset COFF
4269 @node ABORT (COFF)
4270 @section @code{.ABORT} (COFF)
4271
4272 @cindex @code{ABORT} directive
4273 When producing COFF output, @command{@value{AS}} accepts this directive as a
4274 synonym for @samp{.abort}.
4275
4276 @ifset BOUT
4277 When producing @code{b.out} output, @command{@value{AS}} accepts this directive,
4278 but ignores it.
4279 @end ifset
4280 @end ifset
4281
4282 @node Align
4283 @section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
4284
4285 @cindex padding the location counter
4286 @cindex @code{align} directive
4287 Pad the location counter (in the current subsection) to a particular storage
4288 boundary.  The first expression (which must be absolute) is the alignment
4289 required, as described below.
4290
4291 The second expression (also absolute) gives the fill value to be stored in the
4292 padding bytes.  It (and the comma) may be omitted.  If it is omitted, the
4293 padding bytes are normally zero.  However, on some systems, if the section is
4294 marked as containing code and the fill value is omitted, the space is filled
4295 with no-op instructions.
4296