Merge branch 'vendor/GCC50'
[dragonfly.git] / contrib / binutils-2.24 / gas / doc / as.texinfo
CommitLineData
f40e693d
JM
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
100This file documents the GNU Assembler "@value{AS}".
101
102@c man begin COPYRIGHT
103Copyright @copyright{} 1991-2013 Free Software Foundation, Inc.
104
105Permission is granted to copy, distribute and/or modify this document
106under the terms of the GNU Free Documentation License, Version 1.3
107or any later version published by the Free Software Foundation;
108with no Invariant Sections, with no Front-Cover Texts, and with no
109Back-Cover Texts. A copy of the license is included in the
110section 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
129The Free Software Foundation Inc.@: thanks The Nice Computer
130Company of Australia for loaning Dean Elsner to write the
131first (Vax) version of @command{as} for Project @sc{gnu}.
132The proprietors, management and staff of TNCCA thank FSF for
133distracting the boss while they got some work
134done.
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
152Copyright @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
168This file is a user guide to the @sc{gnu} assembler @command{@value{AS}}
169@ifset VERSION_PACKAGE
170@value{VERSION_PACKAGE}
171@end ifset
172version @value{VERSION}.
173@ifclear GENERIC
174This version of the file describes @command{@value{AS}} configured to generate
175code for @value{TARGET} architectures.
176@end ifclear
177
178This document is distributed under the terms of the GNU Free
179Documentation License. A copy of the license is included in the
180section 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
204This manual is a user guide to the @sc{gnu} assembler @command{@value{AS}}.
205@ifclear GENERIC
206This version of the manual describes @command{@value{AS}} configured to generate
207code for @value{TARGET} architectures.
208@end ifclear
209@end iftex
210
211@cindex invocation summary
212@cindex option summary
213@cindex summary of options
214Here is a brief summary of how to invoke @command{@value{AS}}. For details,
215see @ref{Invoking,,Command-Line Options}.
216
217@c man title AS the portable GNU assembler.
218
219@ignore
220@c man begin SEEALSO
221gcc(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]
559Turn on listings, in any of a variety of ways:
560
561@table @gcctabopt
562@item -ac
563omit false conditionals
564
565@item -ad
566omit debugging directives
567
568@item -ag
569include general information, like @value{AS} version and options passed
570
571@item -ah
572include high-level source
573
574@item -al
575include assembly
576
577@item -am
578include macro expansions
579
580@item -an
581omit forms processing
582
583@item -as
584include symbols
585
586@item =file
587set the name of the listing file
588@end table
589
590You may combine these options; for example, use @samp{-aln} for assembly
591listing without forms processing. The @samp{=file} option, if used, must be
592the last one. By itself, @samp{-a} defaults to @samp{-ahls}.
593
594@item --alternate
595Begin in alternate macro mode.
596@ifclear man
597@xref{Altmacro,,@code{.altmacro}}.
598@end ifclear
599
600@item --compress-debug-sections
601Compress DWARF debug sections using zlib. The debug sections are renamed
602to begin with @samp{.zdebug}, and the resulting object file may not be
603compatible with older linkers and object file utilities.
604
605@item --nocompress-debug-sections
606Do not compress DWARF debug sections. This is the default.
607
608@item -D
609Ignored. This option is accepted for script compatibility with calls to
610other assemblers.
611
612@item --debug-prefix-map @var{old}=@var{new}
613When assembling files in directory @file{@var{old}}, record debugging
614information describing them as in @file{@var{new}} instead.
615
616@item --defsym @var{sym}=@var{value}
617Define 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}
619indicates a hexadecimal value, and a leading @samp{0} indicates an octal
620value. The value of the symbol can be overridden inside a source file via the
621use of a @code{.set} pseudo-op.
622
623@item -f
624``fast''---skip whitespace and comment preprocessing (assume source is
625compiler output).
626
627@item -g
628@itemx --gen-debug
629Generate debugging information for each assembler source line using whichever
630debug format is preferred by the target. This currently means either STABS,
631ECOFF or DWARF2.
632
633@item --gstabs
634Generate stabs debugging information for each assembler line. This
635may help debugging assembler code, if the debugger can handle it.
636
637@item --gstabs+
638Generate stabs debugging information for each assembler line, with GNU
639extensions that probably only gdb can handle, and that could make other
640debuggers crash or refuse to read your program. This
641may help debugging assembler code. Currently the only GNU extension is
642the location of the current working directory at assembling time.
643
644@item --gdwarf-2
645Generate DWARF2 debugging information for each assembler line. This
646may help debugging assembler code, if the debugger can handle it. Note---this
647option is only supported by some targets, not all of them.
648
649@item --gdwarf-sections
650Instead of creating a .debug_line section, create a series of
651.debug_line.@var{foo} sections where @var{foo} is the name of the
652corresponding code section. For example a code section called @var{.text.func}
653will 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}
655then debug line section will still be called just @var{.debug_line} without any
656suffix.
657
658@item --size-check=error
659@itemx --size-check=warning
660Issue an error or warning for invalid ELF .size directive.
661
662@item --help
663Print a summary of the command line options and exit.
664
665@item --target-help
666Print a summary of all target specific options and exit.
667
668@item -I @var{dir}
669Add directory @var{dir} to the search list for @code{.include} directives.
670
671@item -J
672Don't warn about signed overflow.
673
674@item -K
675@ifclear DIFF-TBL-KLUGE
676This option is accepted but has no effect on the @value{TARGET} family.
677@end ifclear
678@ifset DIFF-TBL-KLUGE
679Issue warnings when difference tables altered for long displacements.
680@end ifset
681
682@item -L
683@itemx --keep-locals
684Keep (in the symbol table) local symbols. These symbols start with
685system-specific local label prefixes, typically @samp{.L} for ELF systems
686or @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}
692Set the maximum width, in words, of the output data column for an assembler
693listing to @var{number}.
694
695@item --listing-lhs-width2=@var{number}
696Set the maximum width, in words, of the output data column for continuation
697lines in an assembler listing to @var{number}.
698
699@item --listing-rhs-width=@var{number}
700Set 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}
704Set the maximum number of lines printed in a listing for a single line of input
705to @var{number} + 1.
706
707@item -o @var{objfile}
708Name the object-file output from @command{@value{AS}} @var{objfile}.
709
710@item -R
711Fold the data section into the text section.
712
713@kindex --hash-size=@var{number}
714Set 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
716assembler to perform its tasks, at the expense of increasing the assembler's
717memory requirements. Similarly reducing this value can reduce the memory
718requirements at the expense of speed.
719
720@item --reduce-memory-overheads
721This option reduces GAS's memory requirements, at the expense of making the
722assembly 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
726Print the maximum space (in bytes) and total time (in seconds) used by
727assembly.
728
729@item --strip-local-absolute
730Remove local absolute symbols from the outgoing symbol table.
731
732@item -v
733@itemx -version
734Print the @command{as} version.
735
736@item --version
737Print the @command{as} version and exit.
738
739@item -W
740@itemx --no-warn
741Suppress warning messages.
742
743@item --fatal-warnings
744Treat warnings as errors.
745
746@item --warn
747Don't suppress warning messages or treat them as errors.
748
749@item -w
750Ignored.
751
752@item -x
753Ignored.
754
755@item -Z
756Generate an object file even after errors.
757
758@item -- | @var{files} @dots{}
759Standard 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
768for the 64-bit mode of the ARM Architecture (AArch64).
769@end ifclear
770
771@ifset man
772@c man begin OPTIONS
773The following options are available when @value{AS} is configured for the
77464-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
787for an Alpha processor.
788@end ifclear
789
790@ifset man
791@c man begin OPTIONS
792The following options are available when @value{AS} is configured for an Alpha
793processor.
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
804The following options are available when @value{AS} is configured for
805an ARC processor.
806
807@table @gcctabopt
808@item -marc[5|6|7|8]
809This option selects the core processor variant.
810@item -EB | -EL
811Select either big-endian (-EB) or little-endian (-EL) output.
812@end table
813@end ifset
814
815@ifset ARM
816The following options are available when @value{AS} is configured for the ARM
817processor family.
818
819@table @gcctabopt
820@item -mcpu=@var{processor}[+@var{extension}@dots{}]
821Specify which ARM processor variant is the target.
822@item -march=@var{architecture}[+@var{extension}@dots{}]
823Specify which ARM architecture variant is used by the target.
824@item -mfpu=@var{floating-point-format}
825Select which Floating Point architecture is the target.
826@item -mfloat-abi=@var{abi}
827Select which floating point ABI is in use.
828@item -mthumb
829Enable Thumb only instruction decoding.
830@item -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant
831Select which procedure calling convention is in use.
832@item -EB | -EL
833Select either big-endian (-EB) or little-endian (-EL) output.
834@item -mthumb-interwork
835Specify that the code has been generated with interworking between Thumb and
836ARM code in mind.
837@item -k
838Specify 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
847configured for the Blackfin processor family.
848@end ifclear
849
850@ifset man
851@c man begin OPTIONS
852The following options are available when @value{AS} is configured for
853the 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
864See the info pages for documentation of the CRIS-specific options.
865@end ifset
866
867@ifset D10V
868The following options are available when @value{AS} is configured for
869a D10V processor.
870@table @gcctabopt
871@cindex D10V optimization
872@cindex optimization, D10V
873@item -O
874Optimize output by parallelizing instructions.
875@end table
876@end ifset
877
878@ifset D30V
879The following options are available when @value{AS} is configured for a D30V
880processor.
881@table @gcctabopt
882@cindex D30V optimization
883@cindex optimization, D30V
884@item -O
885Optimize output by parallelizing instructions.
886
887@cindex D30V nops
888@item -n
889Warn when nops are generated.
890
891@cindex D30V nops after 32-bit multiply
892@item -N
893Warn 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
899The following options are available when @value{AS} is configured for the
900Adapteva EPIPHANY series.
901
902@ifclear man
903@xref{Epiphany Options}, for the options available when @value{AS} is
904configured for an Epiphany processor.
905@end ifclear
906
907@ifset man
908@c man begin OPTIONS
909The following options are available when @value{AS} is configured for
910an 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
923for an H8/300 processor.
924@end ifclear
925
926@ifset man
927@c man begin OPTIONS
928The following options are available when @value{AS} is configured for an H8/300
929processor.
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
942configured for an i386 processor.
943@end ifclear
944
945@ifset man
946@c man begin OPTIONS
947The following options are available when @value{AS} is configured for
948an 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
959The following options are available when @value{AS} is configured for the
960Intel 80960 processor.
961
962@table @gcctabopt
963@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
964Specify which variant of the 960 architecture is the target.
965
966@item -b
967Add code to collect statistics about branches taken.
968
969@item -no-relax
970Do not alter compare-and-branch instructions for long displacements;
971error if necessary.
972
973@end table
974@end ifset
975
976@ifset IP2K
977The following options are available when @value{AS} is configured for the
978Ubicom IP2K series.
979
980@table @gcctabopt
981
982@item -mip2022ext
983Specifies that the extended IP2022 instructions are allowed.
984
985@item -mip2022
986Restores the default behaviour, which restricts the permitted instructions to
987just the basic IP2022 ones.
988
989@end table
990@end ifset
991
992@ifset M32C
993The following options are available when @value{AS} is configured for the
994Renesas M32C and M16C processors.
995
996@table @gcctabopt
997
998@item -m32c
999Assemble M32C instructions.
1000
1001@item -m16c
1002Assemble M16C instructions (the default).
1003
1004@item -relax
1005Enable support for link-time relaxations.
1006
1007@item -h-tick-hex
1008Support H'00 style hex constants in addition to 0x00 style.
1009
1010@end table
1011@end ifset
1012
1013@ifset M32R
1014The following options are available when @value{AS} is configured for the
1015Renesas M32R (formerly Mitsubishi M32R) series.
1016
1017@table @gcctabopt
1018
1019@item --m32rx
1020Specify which processor in the M32R family is the target. The default
1021is normally the M32R, but this option changes it to the M32RX.
1022
1023@item --warn-explicit-parallel-conflicts or --Wp
1024Produce warning messages when questionable parallel constructs are
1025encountered.
1026
1027@item --no-warn-explicit-parallel-conflicts or --Wnp
1028Do not produce warning messages when questionable parallel constructs are
1029encountered.
1030
1031@end table
1032@end ifset
1033
1034@ifset M680X0
1035The following options are available when @value{AS} is configured for the
1036Motorola 68000 series.
1037
1038@table @gcctabopt
1039
1040@item -l
1041Shorten 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
1046Specify what processor in the 68000 family is the target. The default
1047is normally the 68020, but this can be changed at configuration time.
1048
1049@item -m68881 | -m68882 | -mno-68881 | -mno-68882
1050The target machine does (or does not) have a floating-point coprocessor.
1051The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
1052the basic 68000 is not compatible with the 68881, a combination of the
1053two can be specified, since it's possible to do emulation of the
1054coprocessor instructions with the main processor.
1055
1056@item -m68851 | -mno-68851
1057The target machine does (or does not) have a memory-management
1058unit 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
1067for an Altera Nios II processor.
1068@end ifclear
1069
1070@ifset man
1071@c man begin OPTIONS
1072The following options are available when @value{AS} is configured for an
1073Altera 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
1083For details about the PDP-11 machine dependent features options,
1084see @ref{PDP-11-Options}.
1085
1086@table @gcctabopt
1087@item -mpic | -mno-pic
1088Generate position-independent (or position-dependent) code. The
1089default is @option{-mpic}.
1090
1091@item -mall
1092@itemx -mall-extensions
1093Enable all instruction set extensions. This is the default.
1094
1095@item -mno-extensions
1096Disable all instruction set extensions.
1097
1098@item -m@var{extension} | -mno-@var{extension}
1099Enable (or disable) a particular instruction set extension.
1100
1101@item -m@var{cpu}
1102Enable the instruction set extensions supported by a particular CPU, and
1103disable all other extensions.
1104
1105@item -m@var{machine}
1106Enable the instruction set extensions supported by a particular machine
1107model, and disable all other extensions.
1108@end table
1109
1110@end ifset
1111
1112@ifset PJ
1113The following options are available when @value{AS} is configured for
1114a picoJava processor.
1115
1116@table @gcctabopt
1117
1118@cindex PJ endianness
1119@cindex endianness, PJ
1120@cindex big endian output, PJ
1121@item -mb
1122Generate ``big endian'' format output.
1123
1124@cindex little endian output, PJ
1125@item -ml
1126Generate ``little endian'' format output.
1127
1128@end table
1129@end ifset
1130
1131@ifset M68HC11
1132The following options are available when @value{AS} is configured for the
1133Motorola 68HC11 or 68HC12 series.
1134
1135@table @gcctabopt
1136
1137@item -m68hc11 | -m68hc12 | -m68hcs12 | -mm9s12x | -mm9s12xg
1138Specify what processor is the target. The default is
1139defined by the configuration option when building the assembler.
1140
1141@item --xgate-ramoffset
1142Instruct the linker to offset RAM addresses from S12X address space into
1143XGATE address space.
1144
1145@item -mshort
1146Specify to use the 16-bit integer ABI.
1147
1148@item -mlong
1149Specify to use the 32-bit integer ABI.
1150
1151@item -mshort-double
1152Specify to use the 32-bit double ABI.
1153
1154@item -mlong-double
1155Specify to use the 64-bit double ABI.
1156
1157@item --force-long-branches
1158Relative branches are turned into absolute ones. This concerns
1159conditional branches, unconditional branches and branches to a
1160sub routine.
1161
1162@item -S | --short-branches
1163Do not turn relative branches into absolute ones
1164when the offset is out of range.
1165
1166@item --strict-direct-mode
1167Do not turn the direct addressing mode into extended addressing mode
1168when the instruction does not support direct addressing mode.
1169
1170@item --print-insn-syntax
1171Print the syntax of instruction in case of error.
1172
1173@item --print-opcodes
1174Print the list of instructions with syntax and then exit.
1175
1176@item --generate-example
1177Print an example of instruction for each possible instruction and then exit.
1178This option is only useful for testing @command{@value{AS}}.
1179
1180@end table
1181@end ifset
1182
1183@ifset SPARC
1184The following options are available when @command{@value{AS}} is configured
1185for the SPARC architecture:
1186
1187@table @gcctabopt
1188@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
1189@itemx -Av8plus | -Av8plusa | -Av9 | -Av9a
1190Explicitly 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
1196UltraSPARC extensions.
1197
1198@item -xarch=v8plus | -xarch=v8plusa
1199For compatibility with the Solaris v9 assembler. These options are
1200equivalent to -Av8plus and -Av8plusa, respectively.
1201
1202@item -bump
1203Warn when the assembler switches to another architecture.
1204@end table
1205@end ifset
1206
1207@ifset TIC54X
1208The following options are available when @value{AS} is configured for the 'c54x
1209architecture.
1210
1211@table @gcctabopt
1212@item -mfar-mode
1213Enable extended addressing mode. All addresses and relocations will assume
1214extended addressing (usually 23 bits).
1215@item -mcpu=@var{CPU_VERSION}
1216Sets the CPU version being compiled for.
1217@item -merrors-to-file @var{FILENAME}
1218Redirect error output to a file, for broken systems which don't support such
1219behaviour in the shell.
1220@end table
1221@end ifset
1222
1223@ifset MIPS
1224The following options are available when @value{AS} is configured for
1225a MIPS processor.
1226
1227@table @gcctabopt
1228@item -G @var{num}
1229This option sets the largest size of an object that can be referenced
1230implicitly with the @code{gp} register. It is only accepted for targets that
1231use 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
1237Generate ``big endian'' format output.
1238
1239@cindex little endian output, MIPS
1240@item -EL
1241Generate ``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
1253Generate code for a particular MIPS Instruction Set Architecture level.
1254@samp{-mips1} is an alias for @samp{-march=r3000}, @samp{-mips2} is an
1255alias 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,
1259MIPS64, and MIPS64 Release 2 ISA processors, respectively.
1260
1261@item -march=@var{cpu}
1262Generate code for a particular MIPS CPU.
1263
1264@item -mtune=@var{cpu}
1265Schedule and tune for a particular MIPS CPU.
1266
1267@item -mfix7000
1268@itemx -mno-fix7000
1269Cause nops to be inserted if the read of the destination register
1270of an mfhi or mflo instruction occurs in the following two instructions.
1271
1272@item -mdebug
1273@itemx -no-mdebug
1274Cause stabs-style debugging output to go into an ECOFF-style .mdebug
1275section instead of the standard ELF .stabs sections.
1276
1277@item -mpdr
1278@itemx -mno-pdr
1279Control generation of @code{.pdr} sections.
1280
1281@item -mgp32
1282@itemx -mfp32
1283The register sizes are normally inferred from the ISA and ABI, but these
1284flags force a certain group of registers to be treated as 32 bits wide at
1285all times. @samp{-mgp32} controls the size of general-purpose registers
1286and @samp{-mfp32} controls the size of floating-point registers.
1287
1288@item -mips16
1289@itemx -no-mips16
1290Generate 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}
1292turns off this option.
1293
1294@item -mmicromips
1295@itemx -mno-micromips
1296Generate code for the microMIPS processor. This is equivalent to putting
1297@code{.set micromips} at the start of the assembly file. @samp{-mno-micromips}
1298turns off this option. This is equivalent to putting @code{.set nomicromips}
1299at the start of the assembly file.
1300
1301@item -msmartmips
1302@itemx -mno-smartmips
1303Enables the SmartMIPS extension to the MIPS32 instruction set. This is
1304equivalent 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
1309Generate code for the MIPS-3D Application Specific Extension.
1310This tells the assembler to accept MIPS-3D instructions.
1311@samp{-no-mips3d} turns off this option.
1312
1313@item -mdmx
1314@itemx -no-mdmx
1315Generate code for the MDMX Application Specific Extension.
1316This tells the assembler to accept MDMX instructions.
1317@samp{-no-mdmx} turns off this option.
1318
1319@item -mdsp
1320@itemx -mno-dsp
1321Generate code for the DSP Release 1 Application Specific Extension.
1322This 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
1327Generate code for the DSP Release 2 Application Specific Extension.
1328This option implies -mdsp.
1329This 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
1334Generate code for the MT Application Specific Extension.
1335This tells the assembler to accept MT instructions.
1336@samp{-mno-mt} turns off this option.
1337
1338@item -mmcu
1339@itemx -mno-mcu
1340Generate code for the MCU Application Specific Extension.
1341This tells the assembler to accept MCU instructions.
1342@samp{-mno-mcu} turns off this option.
1343
1344@item -minsn32
1345@itemx -mno-insn32
1346Only use 32-bit instruction encodings when generating code for the
1347microMIPS processor. This option inhibits the use of any 16-bit
1348instructions. This is equivalent to putting @code{.set insn32} at
1349the start of the assembly file. @samp{-mno-insn32} turns off this
1350option. This is equivalent to putting @code{.set noinsn32} at the
1351start of the assembly file. By default @samp{-mno-insn32} is
1352selected, allowing all instructions to be used.
1353
1354@item --construct-floats
1355@itemx --no-construct-floats
1356The @samp{--no-construct-floats} option disables the construction of
1357double width floating point constants by loading the two halves of the
1358value into the two single width floating point registers that make up
1359the double width register. By default @samp{--construct-floats} is
1360selected, allowing construction of these floating point constants.
1361
1362@item --relax-branch
1363@itemx --no-relax-branch
1364The @samp{--relax-branch} option enables the relaxation of out-of-range
1365branches. By default @samp{--no-relax-branch} is selected, causing any
1366out-of-range branches to produce an error.
1367
1368@item -mnan=@var{encoding}
1369Select 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}
1374This option was formerly used to switch between ELF and ECOFF output
1375on targets like IRIX 5 that supported both. MIPS ECOFF support was
1376removed in GAS 2.24, so the option now serves little purpose.
1377It is retained for backwards compatibility.
1378
1379The available configuration names are: @samp{mipself}, @samp{mipslelf} and
1380@samp{mipsbelf}. Choosing @samp{mipself} now has no effect, since the output
1381is always ELF. @samp{mipslelf} and @samp{mipsbelf} select little- and
1382big-endian output respectively, but @samp{-EL} and @samp{-EB} are now the
1383preferred options instead.
1384
1385@item -nocpp
1386@command{@value{AS}} ignores this option. It is accepted for compatibility with
1387the native tools.
1388
1389@item --trap
1390@itemx --no-trap
1391@itemx --break
1392@itemx --no-break
1393Control 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
1397break exception.
1398
1399@item -n
1400When this option is used, @command{@value{AS}} will issue a warning every
1401time it generates a nop instruction from a macro.
1402@end table
1403@end ifset
1404
1405@ifset MCORE
1406The following options are available when @value{AS} is configured for
1407an MCore processor.
1408
1409@table @gcctabopt
1410@item -jsri2bsr
1411@itemx -nojsri2bsr
1412Enable or disable the JSRI to BSR transformation. By default this is enabled.
1413The command line option @samp{-nojsri2bsr} can be used to disable it.
1414
1415@item -sifilter
1416@itemx -nosifilter
1417Enable or disable the silicon filter behaviour. By default this is disabled.
1418The default can be overridden by the @samp{-sifilter} command line option.
1419
1420@item -relax
1421Alter jump instructions for long displacements.
1422
1423@item -mcpu=[210|340]
1424Select the cpu type on the target hardware. This controls which instructions
1425can be assembled.
1426
1427@item -EB
1428Assemble for a big endian target.
1429
1430@item -EL
1431Assemble 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
1441for a Meta processor.
1442@end ifclear
1443
1444@ifset man
1445@c man begin OPTIONS
1446The following options are available when @value{AS} is configured for a
1447Meta 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
1458See 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
1466for a PowerPC processor.
1467@end ifclear
1468
1469@ifset man
1470@c man begin OPTIONS
1471The following options are available when @value{AS} is configured for a
1472PowerPC 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
1483See the info pages for documentation of the RX-specific options.
1484@end ifset
1485
1486@ifset S390
1487The following options are available when @value{AS} is configured for the s390
1488processor family.
1489
1490@table @gcctabopt
1491@item -m31
1492@itemx -m64
1493Select the word size, either 31/32 bits or 64 bits.
1494@item -mesa
1495@item -mzarch
1496Select the architecture mode, either the Enterprise System
1497Architecture (esa) or the z/Architecture mode (zarch).
1498@item -march=@var{processor}
1499Specify 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
1504Allow or disallow symbolic names for registers.
1505@item -mwarn-areg-zero
1506Warn whenever the operand for a base or index register has been specified
1507but 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
1516for a TMS320C6000 processor.
1517@end ifclear
1518
1519@ifset man
1520@c man begin OPTIONS
1521The following options are available when @value{AS} is configured for a
1522TMS320C6000 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
1535for a TILE-Gx processor.
1536@end ifclear
1537
1538@ifset man
1539@c man begin OPTIONS
1540The following options are available when @value{AS} is configured for a TILE-Gx
1541processor.
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
1554for an Xtensa processor.
1555@end ifclear
1556
1557@ifset man
1558@c man begin OPTIONS
1559The following options are available when @value{AS} is configured for an
1560Xtensa 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
1572The following options are available when @value{AS} is configured for
1573a Z80 family processor.
1574@table @gcctabopt
1575@item -z80
1576Assemble for Z80 processor.
1577@item -r800
1578Assemble for R800 processor.
1579@item -ignore-undocumented-instructions
1580@itemx -Wnud
1581Assemble undocumented Z80 instructions that also work on R800 without warning.
1582@item -ignore-unportable-instructions
1583@itemx -Wnup
1584Assemble all undocumented Z80 instructions without warning.
1585@item -warn-undocumented-instructions
1586@itemx -Wud
1587Issue a warning for undocumented Z80 instructions that also work on R800.
1588@item -warn-unportable-instructions
1589@itemx -Wup
1590Issue a warning for undocumented Z80 instructions that do not work on R800.
1591@item -forbid-undocumented-instructions
1592@itemx -Fud
1593Treat all undocumented instructions as errors.
1594@item -forbid-unportable-instructions
1595@itemx -Fup
1596Treat 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
1616This 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
1618notation 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
1622We also cover special features in the @value{TARGET}
1623configuration of @command{@value{AS}}, including assembler directives.
1624@end ifclear
1625@ifset GENERIC
1626This manual also describes some of the machine-dependent features of
1627various flavors of the assembler.
1628@end ifset
1629
1630@cindex machine instructions (not covered)
1631On the other hand, this manual is @emph{not} intended as an introduction
1632to programming in assembly language---let alone programming in general!
1633In a similar vein, we make no attempt to introduce the machine
1634architecture; we do @emph{not} describe the instruction set, standard
1635mnemonics, registers or addressing modes that are standard to a
1636particular architecture.
1637@ifset GENERIC
1638You may want to consult the manufacturer's
1639machine architecture manual for this information.
1640@end ifset
1641@ifclear GENERIC
1642@ifset H8/300
1643For information on the H8/300 machine instruction set, see @cite{H8/300
1644Series Programming Manual}. For the H8/300H, see @cite{H8/300H Series
1645Programming Manual} (Renesas).
1646@end ifset
1647@ifset SH
1648For information on the Renesas (formerly Hitachi) / SuperH SH machine instruction set,
1649see @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
1654For 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
1660Throughout this manual, we assume that you are running @dfn{GNU},
1661the portable operating system from the @dfn{Free Software
1662Foundation, Inc.}. This restricts our attention to certain kinds of
1663computer (in particular, the kinds of computers that @sc{gnu} can run on);
1664once this assumption is granted examples and definitions need less
1665qualification.
1666
1667@command{@value{AS}} is part of a team of programs that turn a high-level
1668human-readable series of instructions into a low-level
1669computer-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
1689This manual describes @command{@value{AS}}, a member of that family which is
1690configured for the @value{TARGET} architectures.
1691@end ifclear
1692If you use (or have used) the @sc{gnu} assembler on one architecture, you
1693should find a fairly similar environment when you use it on another
1694architecture. Each version has much in common with the others,
1695including 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}}
1702assemble correctly everything that other assemblers for the same
1703machine would assemble.
1704@ifset VAX
1705Any 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.
1710This doesn't mean @command{@value{AS}} always uses the same syntax as another
1711assembler for the same architecture; for example, we know of several
1712incompatible versions of 680x0 assembly language syntax.
1713@end ifset
1714
1715@c man end
1716
1717Unlike older assemblers, @command{@value{AS}} is designed to assemble a source
1718program 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
1725The @sc{gnu} assembler can be configured to produce several alternative
1726object file formats. For the most part, this does not affect how you
1727write assembly language programs; but directives for debugging symbols
1728are typically different in different file formats. @xref{Symbol
1729Attributes,,Symbol Attributes}.
1730@ifclear GENERIC
1731@ifclear MULTI-OBJ
1732For 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
1737On 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
1741On the @value{TARGET}, @command{@value{AS}} can be configured to produce either
1742SOM 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
1751After the program name @command{@value{AS}}, the command line may contain
1752options and file names. Options may appear in any order, and may be
1753before, after, or between file names. The order of file names is
1754significant.
1755
1756@cindex standard input, as input file
1757@kindex --
1758@file{--} (two hyphens) by itself names the standard input file
1759explicitly, as one of the files for @command{@value{AS}} to assemble.
1760
1761@cindex options, command line
1762Except for @samp{--} any command line argument that begins with a
1763hyphen (@samp{-}) is an option. Each option changes the behavior of
1764@command{@value{AS}}. No option changes the way another option works. An
1765option is a @samp{-} followed by one or more letters; the case of
1766the letter is important. All options are optional.
1767
1768Some options expect exactly one file name to follow them. The file
1769name may either immediately follow the option's letter (compatible
1770with older assemblers) or it may be the next command argument (@sc{gnu}
1771standard). 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
1784We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
1785describe the program input to one run of @command{@value{AS}}. The program may
1786be in one or more files; how the source is partitioned into files
1787doesn'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
1791The source program is a concatenation of the text in all the files, in the
1792order specified.
1793
1794@c man begin DESCRIPTION
1795Each time you run @command{@value{AS}} it assembles exactly one source
1796program. The source program is made up of one or more files.
1797(The standard input is also a file.)
1798
1799You give @command{@value{AS}} a command line that has zero or more input file
1800names. The input files are read (from left file name to right). A
1801command line argument (in any position) that has no special meaning
1802is taken to be an input file name.
1803
1804If you give @command{@value{AS}} no file names it attempts to read one input file
1805from the @command{@value{AS}} standard input, which is normally your terminal. You
1806may have to type @key{ctl-D} to tell @command{@value{AS}} there is no more program
1807to assemble.
1808
1809Use @samp{--} if you need to explicitly name the standard input file
1810in your command line.
1811
1812If the source is empty, @command{@value{AS}} produces a small, empty object
1813file.
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
1821There are two ways of locating a line in the input file (or files) and
1822either may be used in reporting error messages. One way refers to a line
1823number 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
1827to @command{@value{AS}}.
1828
1829@dfn{Logical files} are simply names declared explicitly by assembler
1830directives; they bear no relation to physical files. Logical file names help
1831error messages reflect the original source file, when @command{@value{AS}} source
1832is 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
1843Every time you run @command{@value{AS}} it produces an output file, which is
1844your assembly language program translated into numbers. This file
1845is 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
1855You can give it another name by using the @option{-o} option. Conventionally,
1856object file names end with @file{.o}. The default name is used for historical
1857reasons: older assemblers were capable of assembling self-contained programs
1858directly into a runnable program. (For some formats, this isn't currently
1859possible, but it can be done for the @code{a.out} format.)
1860
1861@cindex linker
1862@kindex ld
1863The object file is meant for input to the linker @code{@value{LD}}. It contains
1864assembled program code, information to help @code{@value{LD}} integrate
1865the assembled program into a runnable file, and (optionally) symbolic
1866information 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
1880file (usually your terminal). This should not happen when a compiler
1881runs @command{@value{AS}} automatically. Warnings report an assumption made so
1882that @command{@value{AS}} could keep assembling a flawed program; errors report a
1883grave problem that stops the assembly.
1884
1885@c man end
1886
1887@cindex format of warning messages
1888Warning messages have the format
1889
1890@smallexample
1891file_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
1898the current input file is used. If a logical line number was given
1899@ifset GENERIC
1900(@pxref{Line,,@code{.line}})
1901@end ifset
1902then it is used to calculate the number printed,
1903otherwise the actual line in the current source file is printed. The
1904message text is intended to be self explanatory (in the grand Unix
1905tradition).
1906
1907@cindex format of error messages
1908Error messages have the format
1909@smallexample
1910file_name:@b{NNN}:FATAL:Error Message Text
1911@end smallexample
1912The file name and line number are derived as for warning
1913messages. The actual message text may be rather less explanatory
1914because 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
1920This chapter describes command-line options available in @emph{all}
1921versions of the @sc{gnu} assembler; see @ref{Machine Dependencies},
1922for options specific
1923@ifclear GENERIC
1924to the @value{TARGET} target.
1925@end ifclear
1926@ifset GENERIC
1927to particular machine architectures.
1928@end ifset
1929
1930@c man begin DESCRIPTION
1931
1932If you are invoking @command{@value{AS}} via the @sc{gnu} C compiler,
1933you can use the @samp{-Wa} option to pass arguments through to the assembler.
1934The assembler arguments must be separated from each other (and the @samp{-Wa})
1935by commas. For example:
1936
1937@smallexample
1938gcc -c -g -O -Wa,-alh,-L file.c
1939@end smallexample
1940
1941@noindent
1942This passes two options to the assembler: @samp{-alh} (emit a listing to
1943standard output with high-level and assembly source) and @samp{-L} (retain
1944local symbols in the symbol table).
1945
1946Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
1947command-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
1949precisely what options it passes to each compilation pass, including the
1950assembler.)
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
1994These options enable listing output from the assembler. By itself,
1995@samp{-a} requests high-level, assembly, and symbols listing.
1996You 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.
2000High-level listings require that a compiler debugging option like
2001@samp{-g} be used, and that assembly listings (@samp{-al}) be requested
2002also.
2003
2004Use the @samp{-ag} option to print a first section with general assembly
2005information, like @value{AS} version, switches passed, or time stamp.
2006
2007Use the @samp{-ac} option to omit false conditionals from a listing. Any lines
2008which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any
2009other conditional), or a true @code{.if} followed by an @code{.else}, will be
2010omitted from the listing.
2011
2012Use the @samp{-ad} option to omit debugging directives from the
2013listing.
2014
2015Once you have specified one of these options, you can further control
2016listing output and its appearance using the directives @code{.list},
2017@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
2018@code{.sbttl}.
2019The @samp{-an} option turns off all forms processing.
2020If you do not request listing output with one of the @samp{-a} options, the
2021listing-control directives have no effect.
2022
2023The letters after @samp{-a} may be combined into one option,
2024@emph{e.g.}, @samp{-aln}.
2025
2026Note if the assembler source is coming from the standard input (e.g.,
2027because it
2028is being created by @code{@value{GCC}} and the @samp{-pipe} command line switch
2029is being used) then the listing will not contain any comments or preprocessor
2030directives. This is because the listing code buffers input source lines from
2031stdin only after they have been preprocessed by the assembler. This reduces
2032memory usage and makes the code more efficient.
2033
2034@node alternate
2035@section @option{--alternate}
2036
2037@kindex --alternate
2038Begin in alternate macro mode, see @ref{Altmacro,,@code{.altmacro}}.
2039
2040@node D
2041@section @option{-D}
2042
2043@kindex -D
2044This option has no effect whatsoever, but it is accepted to make it more
2045likely 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
2056and comment preprocessing on
2057the 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
2062preprocessed (if they contain comments, for example), @command{@value{AS}} does
2063not 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
2073Use this option to add a @var{path} to the list of directories
2074@command{@value{AS}} searches for files specified in @code{.include}
2075directives (@pxref{Include,,@code{.include}}). You may use @option{-I} as
2076many times as necessary to include a variety of paths. The current
2077working directory is always searched first; after that, @command{@value{AS}}
2078searches any @samp{-I} directories in the same order as they were
2079specified (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
2086On the @value{TARGET} family, this option is allowed, but has no effect. It is
2087permitted for compatibility with the @sc{gnu} assembler on other platforms,
2088where it can be used to warn when the assembler alters the machine code
2089generated for @samp{.word} directives in difference tables. The @value{TARGET}
2090family does not have the addressing limitations that sometimes lead to this
2091alteration 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
2098form @samp{.word @var{sym1}-@var{sym2}}. @xref{Word,,@code{.word}}.
2099You can use the @samp{-K} option if you want a warning issued when this
2100is 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
2108Symbols beginning with system-specific local label prefixes, typically
2109@samp{.L} for ELF systems or @samp{L} for traditional a.out systems, are
2110called @dfn{local symbols}. @xref{Symbol Names}. Normally you do not see
2111such symbols when debugging, because they are intended for the use of
2112programs (like compilers) that compose assembler programs, not for your
2113notice. Normally both @command{@value{AS}} and @code{@value{LD}} discard
2114such symbols, so you do not normally debug with them.
2115
2116This option tells @command{@value{AS}} to retain those local symbols
2117in 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
2123The 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
2125hex dump of the corresponding locations in the output object file, and displays
2126them as a listing file. The format of this listing can be controlled by
2127directives 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
2136Sets the maximum width, in words, of the first line of the hex byte dump. This
2137dump 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
2142Sets the maximum width, in words, of any further lines of the hex byte dump for
2143a given input source line. If this value is not specified, it defaults to being
2144the same as the value specified for @samp{--listing-lhs-width}. If neither
2145switch 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
2150Sets the maximum width, in characters, of the source line that is displayed
2151alongside the hex dump. The default value for this parameter is 100. The
2152source 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
2157Sets the maximum number of continuation lines of hex dump that will be
2158displayed 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
2166The @option{-M} or @option{--mri} option selects MRI compatibility mode. This
2167changes the syntax and pseudo-op handling of @command{@value{AS}} to make it
2168compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the
2169configured target) assembler from Microtec Research. The exact nature of the
2170MRI syntax will not be documented here; see the MRI manuals for more
2171information. Note in particular that the handling of macros and macro
2172arguments is somewhat different. The purpose of this option is to permit
2173assembling existing MRI assembler code using @command{@value{AS}}.
2174
2175The MRI compatibility is not complete. Certain operations of the MRI assembler
2176depend upon its object file format, and can not be supported using other object
2177file formats. Supporting these would require enhancing each object file format
2178individually. These are:
2179
2180@itemize @bullet
2181@item global symbols in common section
2182
2183The m68k MRI assembler supports common sections which are merged by the linker.
2184Other object file formats do not support this. @command{@value{AS}} handles
2185common sections by treating them as a single common symbol. It permits local
2186symbols to be defined within a common section, but it can not support global
2187symbols, since it has no way to describe them.
2188
2189@item complex relocations
2190
2191The MRI assemblers support relocations against a negated section address, and
2192relocations which combine the start addresses of two or more sections. These
2193are not support by other object file formats.
2194
2195@item @code{END} pseudo-op specifying start address
2196
2197The MRI @code{END} pseudo-op permits the specification of a start address.
2198This is not supported by other object file formats. The start address may
2199instead be specified using the @option{-e} option to the linker, or in a linker
2200script.
2201
2202@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops
2203
2204The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module
2205name to the output file. This is not supported by other object file formats.
2206
2207@item @code{ORG} pseudo-op
2208
2209The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given
2210address. This differs from the usual @command{@value{AS}} @code{.org} pseudo-op,
2211which changes the location within the current section. Absolute sections are
2212not supported by other object file formats. The address of a section may be
2213assigned within a linker script.
2214@end itemize
2215
2216There 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
2218seem of little consequence. Some of these may be supported in future releases.
2219
2220@itemize @bullet
2221
2222@item EBCDIC strings
2223
2224EBCDIC strings are not supported.
2225
2226@item packed binary coded decimal
2227
2228Packed binary coded decimal is not supported. This means that the @code{DC.P}
2229and @code{DCB.P} pseudo-ops are not supported.
2230
2231@item @code{FEQU} pseudo-op
2232
2233The m68k @code{FEQU} pseudo-op is not supported.
2234
2235@item @code{NOOBJ} pseudo-op
2236
2237The m68k @code{NOOBJ} pseudo-op is not supported.
2238
2239@item @code{OPT} branch control options
2240
2241The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB},
2242@code{BRL}, and @code{BRW}---are ignored. @command{@value{AS}} automatically
2243relaxes all branches, whether forward or backward, to an appropriate size, so
2244these options serve no purpose.
2245
2246@item @code{OPT} list control options
2247
2248The 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
2254The 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
2259The 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
2264The m68k @code{XREF} pseudo-op is ignored.
2265
2266@item @code{.debug} pseudo-op
2267
2268The i960 @code{.debug} pseudo-op is not supported.
2269
2270@item @code{.extended} pseudo-op
2271
2272The i960 @code{.extended} pseudo-op is not supported.
2273
2274@item @code{.list} pseudo-op.
2275
2276The various options of the i960 @code{.list} pseudo-op are not supported.
2277
2278@item @code{.optimize} pseudo-op
2279
2280The i960 @code{.optimize} pseudo-op is not supported.
2281
2282@item @code{.output} pseudo-op
2283
2284The i960 @code{.output} pseudo-op is not supported.
2285
2286@item @code{.setreal} pseudo-op
2287
2288The 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
2300file consists of a single rule suitable for @code{make} describing the
2301dependencies of the main source file.
2302
2303The rule is written to the file named in its argument.
2304
2305This 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
2313There is always one object file output when you run @command{@value{AS}}. By
2314default 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
2331You use this option (which takes exactly one filename) to give the
2332object file a different name.
2333
2334Whatever the object file is called, @command{@value{AS}} overwrites any
2335existing 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
2346data-section data lives in the text section. This is only done at
2347the very last moment: your binary data are the same, but data
2348section parts are relocated differently. The data section part of
2349your object file is zero bytes long because all its bytes are
2350appended to the text section. (@xref{Sections,,Sections and Relocation}.)
2351
2352When you specify @option{-R} it would be possible to generate shorter
2353address displacements (because we do not have to cross between text and
2354data section). We refrain from doing this simply for compatibility with
2355older versions of @command{@value{AS}}. In future, @option{-R} may work this way.
2356
2357@ifset COFF-ELF
2358When @command{@value{AS}} is configured for COFF or ELF output,
2359this 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
2375Use @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}
2378seconds).
2379
2380@node traditional-format
2381@section Compatible Output: @option{--traditional-format}
2382
2383@kindex --traditional-format
2384For some targets, the output of @command{@value{AS}} is different in some ways
2385from the output of some existing assembler. This switch requests
2386@command{@value{AS}} to use the traditional format instead.
2387
2388For 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
2398You can find out what version of as is running by including the
2399option @samp{-v} (which you can also spell as @samp{-version}) on the
2400command 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
2406assembling compiler output. But programs written by people often
2407cause @command{@value{AS}} to give a warning that a particular assumption was
2408made. 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
2414If you use the @option{-W} and @option{--no-warn} options, no warnings are issued.
2415This only affects the warning messages: it does not change any particular of
2416how @command{@value{AS}} assembles your file. Errors, which stop the assembly,
2417are still reported.
2418
2419@kindex --fatal-warnings
2420@cindex errors, caused by warnings
2421@cindex warnings, causing error
2422If you use the @option{--fatal-warnings} option, @command{@value{AS}} considers
2423files that generate warnings to be in error.
2424
2425@kindex --warn
2426@cindex warnings, switching on
2427You can switch these options off again by specifying @option{--warn}, which
2428causes 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
2434After an error message, @command{@value{AS}} normally produces no output. If for
2435some 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}
2437option. If there are any errors, @command{@value{AS}} continues anyways, and
2438writes an object file after a final warning message of the form @samp{@var{n}
2439errors, @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
2446This chapter describes the machine-independent syntax allowed in a
2447source file. @command{@value{AS}} syntax is similar to what many other
2448assemblers use; it is inspired by the BSD 4.2
2449@ifclear VAX
2450assembler.
2451@end ifclear
2452@ifset VAX
2453assembler, 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
2469The @command{@value{AS}} internal preprocessor:
2470@itemize @bullet
2471@cindex whitespace, removed by preprocessor
2472@item
2473adjusts and removes extra whitespace. It leaves one space or tab before
2474the keywords on a line, and turns any other whitespace on the line into
2475a single space.
2476
2477@cindex comments, removed by preprocessor
2478@item
2479removes all comments, replacing them with a single space, or an
2480appropriate number of newlines.
2481
2482@cindex constants, converted by preprocessor
2483@item
2484converts character constants into the appropriate numeric values.
2485@end itemize
2486
2487It does not do macro processing, include file handling, or
2488anything else you may get from your C compiler's preprocessor. You can
2489do include file processing with the @code{.include} directive
2490(@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver
2491to get other ``CPP'' style preprocessing by giving the input file a
2492@samp{.S} suffix. @xref{Overall Options, ,Options Controlling the Kind of
2493Output, gcc.info, Using GNU CC}.
2494
2495Excess whitespace, comments, and character constants
2496cannot be used in the portions of the input text that are not
2497preprocessed.
2498
2499@cindex turning preprocessing on and off
2500@cindex preprocessing, turning on and off
2501@kindex #NO_APP
2502@kindex #APP
2503If 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.
2505Within an input file, you can ask for whitespace and comment removal in
2506specific portions of the by putting a line that says @code{#APP} before the
2507text 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
2510and 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.
2517Whitespace is used to separate symbols, and to make programs neater for
2518people to read. Unless within character constants
2519(@pxref{Characters,,Character Constants}), any whitespace means the same
2520as exactly one space.
2521
2522@node Comments
2523@section Comments
2524
2525@cindex comments
2526There are two ways of rendering comments to @command{@value{AS}}. In both
2527cases the comment is equivalent to one space.
2528
2529Anything from @samp{/*} through the next @samp{*/} is a comment.
2530This 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
2542Anything from a @dfn{line comment} character up to the next newline is
2543considered a comment and is ignored. The line comment character is target
2544specific, and some targets multiple comment characters. Some targets also have
2545line comment characters that only work if they are the first character on a
2546line. Some targets use a sequence of two characters to introduce a line
2547comment. Some targets can also change their line comment characters depending
2548upon command line options that have been used. For more details see the
2549@emph{Syntax} section in the documentation for individual targets.
2550
2551If the line comment character is the hash sign (@samp{#}) then it still has the
2552special ability to enable and disable preprocessing (@pxref{Preprocessing}) and
2553to specify logical line numbers:
2554
2555@kindex #
2556@cindex lines starting with @code{#}
2557@cindex logical line numbers
2558To be compatible with past assemblers, lines that begin with @samp{#} have a
2559special interpretation. Following the @samp{#} should be an absolute
2560expression (@pxref{Expressions}): the logical line number of the @emph{next}
2561line. Then a string (@pxref{Strings, ,Strings}) is allowed: if present it is a
2562new logical file name. The rest of the line, if any, should be whitespace.
2563
2564If the first non-whitespace characters on the line are not numeric,
2565the 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
2572This feature is deprecated, and may disappear from future versions
2573of @command{@value{AS}}.
2574
2575@node Symbol Intro
2576@section Symbols
2577
2578@cindex characters used in symbols
2579@ifclear SPECIAL-SYMS
2580A @dfn{symbol} is one or more characters chosen from the set of all
2581letters (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
2587A @dfn{symbol} is one or more characters chosen from the set of all
2588letters (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
2590symbol names.)
2591@end ifset
2592@end ifclear
2593@end ifset
2594@ifset GENERIC
2595On most machines, you can also use @code{$} in symbol names; exceptions
2596are noted in @ref{Machine Dependencies}.
2597@end ifset
2598No symbol may begin with a digit. Case is significant.
2599There is no length limit: all characters are significant. Multibyte characters
2600are supported. Symbols are delimited by characters not in that set, or by the
2601beginning of a file (since the source program must end with a newline, the end
2602of 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
2612A @dfn{statement} ends at a newline character (@samp{\n}) or a
2613@dfn{line separator character}. The line separator character is target
2614specific and described in the @emph{Syntax} section of each
2615target's documentation. Not all targets support a line separator character.
2616The newline or line separator character is considered to be part of the
2617preceding statement. Newlines and separators within character constants are an
2618exception: they do not end statements.
2619
2620@cindex newline, required at file end
2621@cindex EOF, newline must precede
2622It is an error to end any statement with end-of-file: the last
2623character of any input file should be a newline.@refill
2624
2625An 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.
2632A statement begins with zero or more labels, optionally followed by a
2633key symbol which determines what kind of statement it is. The key
2634symbol determines the syntax of the rest of the statement. If the
2635symbol begins with a dot @samp{.} then the statement is an assembler
2636directive: typically valid for any computer. If the symbol begins with
2637a letter the statement is an assembly language @dfn{instruction}: it
2638assembles into a machine language instruction.
2639@ifset GENERIC
2640Different versions of @command{@value{AS}} for different computers
2641recognize different instructions. In fact, the same symbol may
2642represent a different instruction in a different computer's assembly
2643language.@refill
2644@end ifset
2645
2646@cindex @code{:} (label)
2647@cindex label (@code{:})
2648A label is a symbol immediately followed by a colon (@code{:}).
2649Whitespace before a label or after a colon is permitted, but you may not
2650have whitespace between a label's symbol and its colon. @xref{Labels}.
2651
2652@ifset HPPA
2653For HPPA targets, labels need not be immediately followed by a colon, but
2654the definition of a label must begin in column zero. This also implies that
2655only one label may be defined on each line.
2656@end ifset
2657
2658@smallexample
2659label: .directive followed by something
2660another_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
2668A constant is a number, written so that its value is known by
2669inspection, 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\
267695028841971.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
2690There are two kinds of character constants. A @dfn{character} stands
2691for one character in one byte and its value may be used in
2692numeric expressions. String constants (properly called string
2693@emph{literals}) are potentially many bytes and their values may not be
2694used 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
2706A @dfn{string} is written between double-quotes. It may contain
2707double-quotes or null characters. The way to get special characters
2708into a string is to @dfn{escape} these characters: precede them with
2709a backslash @samp{\} character. For example @samp{\\} represents
2710one 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
2713escape 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
2724Mnemonic 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
2732Mnemonic for FormFeed; for ASCII this is octal code 014.
2733
2734@cindex @code{\n} (newline character)
2735@cindex newline (@code{\n})
2736@item \n
2737Mnemonic 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
2745Mnemonic 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
2754Mnemonic 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}
2764An octal character code. The numeric code is 3 octal digits.
2765For compatibility with other Unix systems, 8 and 9 are accepted as digits:
2766for 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...}
2771A hex character code. All trailing hex digits are combined. Either upper or
2772lower case @code{x} works.
2773
2774@cindex @code{\\} (@samp{\} character)
2775@cindex backslash (@code{\\})
2776@item \\
2777Represents 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 \"
2788Represents one @samp{"} character. Needed in strings to represent
2789this character, because an unescaped @samp{"} would end the string.
2790
2791@item \ @var{anything-else}
2792Any other character when escaped by @kbd{\} gives a warning, but
2793assembles as if the @samp{\} was not present. The idea is that if
2794you used an escape sequence you clearly didn't want the literal
2795interpretation of the following character. However @command{@value{AS}} has no
2796other interpretation, so @command{@value{AS}} knows it is giving you the wrong
2797code and warns you of the fact.
2798@end table
2799
2800Which characters are escapable, and what those escapes represent,
2801varies widely among assemblers. The current set is what we think
2802the BSD 4.2 assembler recognizes, and is a subset of what most C
2803compilers recognize. If you are in doubt, do not use an escape
2804sequence.
2805
2806@node Chars
2807@subsubsection Characters
2808
2809@cindex single character constant
2810@cindex character, single
2811@cindex constant, single character
2812A single character may be written as a single quote immediately
2813followed by that character. The same escapes apply to characters as
2814to strings. So if you want to write the character backslash, you
2815must write @kbd{'\\} where the first @code{\} escapes the second
2816@code{\}. As you can see, the quote is an acute accent, not a
2817grave 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
2825Renesas SH)
2826@end ifset
2827@end ifset
2828@end ifclear
2829immediately following an acute accent is taken as a literal character
2830and does not count as the end of a statement. The value of a character
2831constant in a numeric expression is the machine's byte-wide code for
2832that 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
2841are stored in the target machine. @emph{Integers} are numbers that
2842would fit into an @code{int} in the C language. @emph{Bignums} are
2843integers, but they are stored in more than 32 bits. @emph{Flonums}
2844are 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
2864A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
2865the binary digits @samp{01}.
2866
2867@cindex octal integers
2868@cindex integers, octal
2869An octal integer is @samp{0} followed by zero or more of the octal
2870digits (@samp{01234567}).
2871
2872@cindex decimal integers
2873@cindex integers, decimal
2874A decimal integer starts with a non-zero digit followed by zero or
2875more digits (@samp{0123456789}).
2876
2877@cindex hexadecimal integers
2878@cindex integers, hexadecimal
2879A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
2880more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
2881
2882Integers have the usual values. To denote a negative integer, use
2883the 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
2891A @dfn{bignum} has the same syntax and semantics as an integer
2892except that the number (or its negative) takes more than 32 bits to
2893represent in binary. The distinction is made because in some places
2894integers 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
2903A @dfn{flonum} represents a floating point number. The translation is
2904indirect: 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
2906sufficient precision. This generic floating point number is converted
2907to a particular computer's floating point format (or formats) by a
2908portion of @command{@value{AS}} specialized to that computer.
2909
2910A flonum is written by writing (in order)
2911@itemize @bullet
2912@item
2913The digit @samp{0}.
2914@ifset HPPA
2915(@samp{0} is optional on the HPPA.)
2916@end ifset
2917
2918@item
2919A 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
29254.2 assembler seems to allow any of @samp{defghDEFGH}.)
2926@end ignore
2927
2928On the H8/300, Renesas / SuperH SH,
2929and AMD 29K architectures, the letter must be
2930one of the letters @samp{DFPRSX} (in upper or lower case).
2931
2932On the ARC, the letter must be one of the letters @samp{DFRS}
2933(in upper or lower case).
2934
2935On the Intel 960 architecture, the letter must be
2936one of the letters @samp{DFT} (in upper or lower case).
2937
2938On the HPPA architecture, the letter must be @samp{E} (upper case only).
2939@end ifset
2940@ifclear GENERIC
2941@ifset ARC
2942One of the letters @samp{DFRS} (in upper or lower case).
2943@end ifset
2944@ifset H8
2945One of the letters @samp{DFPRSX} (in upper or lower case).
2946@end ifset
2947@ifset HPPA
2948The letter @samp{E} (upper case only).
2949@end ifset
2950@ifset I960
2951One of the letters @samp{DFT} (in upper or lower case).
2952@end ifset
2953@end ifclear
2954
2955@item
2956An optional sign: either @samp{+} or @samp{-}.
2957
2958@item
2959An optional @dfn{integer part}: zero or more decimal digits.
2960
2961@item
2962An optional @dfn{fractional part}: @samp{.} followed by zero
2963or more decimal digits.
2964
2965@item
2966An optional exponent, consisting of:
2967
2968@itemize @bullet
2969@item
2970An @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
2974Optional sign: either @samp{+} or @samp{-}.
2975@item
2976One or more decimal digits.
2977@end itemize
2978
2979@end itemize
2980
2981At least one of the integer part or the fractional part must be
2982present. The floating point number has the usual base-10 value.
2983
2984@command{@value{AS}} does all processing using integers. Flonums are computed
2985independently 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
2998You can also define numeric constants as @dfn{bit fields}.
2999Specify 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
3007The 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
3012into a field whose width depends on which assembler directive has the
3013bit-field as its argument. Overflow (a result from the bitwise and
3014requiring more binary digits to represent) is not an error; instead,
3015more constants are generated, of the specified width, beginning with the
3016least significant digits.@refill
3017
3018The 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
3039Roughly, a section is a range of addresses, with no gaps; all data
3040``in'' those addresses is treated the same for some particular purpose.
3041For example there may be a ``read only'' section.
3042
3043@cindex linker, and assembler
3044@cindex assembler, and linker
3045The linker @code{@value{LD}} reads many object files (partial programs) and
3046combines their contents to form a runnable program. When @command{@value{AS}}
3047emits 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
3049different partial programs do not overlap. This is actually an
3050oversimplification, but it suffices to explain how @command{@value{AS}} uses
3051sections.
3052
3053@code{@value{LD}} moves blocks of bytes of your program to their run-time
3054addresses. These blocks slide to their run-time addresses as rigid
3055units; their length does not change and neither does the order of bytes
3056within them. Such a rigid unit is called a @emph{section}. Assigning
3057run-time addresses to sections is called @dfn{relocation}. It includes
3058the task of adjusting mentions of object-file addresses so they refer to
3059the proper run-time addresses.
3060@ifset H8
3061For the H8/300, and for the Renesas / SuperH SH,
3062@command{@value{AS}} pads sections if needed to
3063ensure they end on a word (sixteen bit) boundary.
3064@end ifset
3065
3066@cindex standard assembler sections
3067An object file written by @command{@value{AS}} has at least three sections, any
3068of which may be empty. These are named @dfn{text}, @dfn{data} and
3069@dfn{bss} sections.
3070
3071@ifset COFF-ELF
3072@ifset GENERIC
3073When it generates COFF or ELF output,
3074@end ifset
3075@command{@value{AS}} can also generate whatever other named sections you specify
3076using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
3077If you do not use any directives that place output in the @samp{.text}
3078or @samp{.data} sections, these sections still exist, but are empty.
3079@end ifset
3080
3081@ifset HPPA
3082@ifset GENERIC
3083When @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
3086specify 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}
3089assembler directives.
3090
3091@ifset SOM
3092Additionally, @command{@value{AS}} uses different names for the standard
3093text, data, and bss sections when generating SOM output. Program text
3094is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
3095BSS into @samp{$BSS$}.
3096@end ifset
3097@end ifset
3098
3099Within the object file, the text section starts at address @code{0}, the
3100data section follows, and the bss section follows the data section.
3101
3102@ifset HPPA
3103When generating either SOM or ELF output files on the HPPA, the text
3104section 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
3108To let @code{@value{LD}} know which data changes when the sections are
3109relocated, and how to change that data, @command{@value{AS}} also writes to the
3110object file details of the relocation needed. To perform relocation
3111@code{@value{LD}} must know, each time an address in the object
3112file is mentioned:
3113@itemize @bullet
3114@item
3115Where in the object file is the beginning of this reference to
3116an address?
3117@item
3118How long (in bytes) is this reference?
3119@item
3120Which 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
3125Is the reference to an address ``Program-Counter relative''?
3126@end itemize
3127
3128@cindex addresses, format of
3129@cindex section-relative addressing
3130In 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
3135Further, most expressions @command{@value{AS}} computes have this section-relative
3136nature.
3137@ifset SOM
3138(For some object formats, such as SOM for the HPPA, some expressions are
3139symbol-relative instead.)
3140@end ifset
3141
3142In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset
3143@var{N} into section @var{secname}.''
3144
3145Apart from text, data and bss sections you need to know about the
3146@dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
3147addresses 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'
3150data sections with overlapping addresses after linking, @emph{by definition}
3151their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one
3152part of a program is always the same address when the program is running as
3153address @code{@{absolute@ 239@}} in any other part of the program.
3154
3155The idea of sections is extended to the @dfn{undefined} section. Any
3156address whose section is unknown at assembly time is by definition
3157rendered @{undefined @var{U}@}---where @var{U} is filled in later.
3158Since numbers are always defined, the only way to generate an undefined
3159address is to mention an undefined symbol. A reference to a named
3160common block would be such a symbol: its value is unknown at assembly
3161time so it has section @emph{undefined}.
3162
3163By analogy the word @emph{section} is used to describe groups of sections in
3164the linked program. @code{@value{LD}} puts all partial programs' text
3165sections in contiguous addresses in the linked program. It is
3166customary to refer to the @emph{text section} of a program, meaning all
3167the addresses of all partial programs' text sections. Likewise for
3168data and bss sections.
3169
3170Some sections are manipulated by @code{@value{LD}}; others are invented for
3171use 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
3190These sections hold your program. @command{@value{AS}} and @code{@value{LD}} treat them as
3191separate but equal sections. Anything you can say of one section is
3192true of another.
3193@c @ifset aout-bout
3194When the program is running, however, it is
3195customary for the text section to be unalterable. The
3196text section is often shared among processes: it contains
3197instructions, constants and the like. The data section of a running
3198program is usually alterable: for example, C variables would be stored
3199in the data section.
3200@c @end ifset
3201
3202@cindex bss section
3203@item bss section
3204This section contains zeroed bytes when your program begins running. It
3205is used to hold uninitialized variables or common storage. The length of
3206each partial program's bss section is important, but because it starts
3207out containing zeroed bytes there is no need to store explicit zero
3208bytes in the object file. The bss section was invented to eliminate
3209those explicit zeros from object files.
3210
3211@cindex absolute section
3212@item absolute section
3213Address 0 of this section is always ``relocated'' to runtime address 0.
3214This is useful if you want to refer to an address that @code{@value{LD}} must
3215not change when relocating. In this sense we speak of absolute
3216addresses being ``unrelocatable'': they do not change during relocation.
3217
3218@cindex undefined section
3219@item undefined section
3220This ``section'' is a catch-all for address references to objects not in
3221the 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
3226An idealized example of three relocatable sections follows.
3227@ifset COFF-ELF
3228The example uses the traditional section names @samp{.text} and @samp{.data}.
3229@end ifset
3230Memory addresses are on the horizontal axis.
3231
3232@c TEXI2ROFF-KILL
3233@ifnottex
3234@c END TEXI2ROFF-KILL
3235@smallexample
3236 +-----+----+--+
3237partial program # 1: |ttttt|dddd|00|
3238 +-----+----+--+
3239
3240 text data bss
3241 seg. seg. seg.
3242
3243 +---+---+---+
3244partial program # 2: |TTT|DDD|000|
3245 +---+---+---+
3246
3247 +--+---+-----+--+----+---+-----+~~
3248linked 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
3269ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
3270DDDD}\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
3283These sections are meant only for the internal use of @command{@value{AS}}. They
3284have no meaning at run-time. You do not really need to know about these
3285sections for most purposes; but they can be mentioned in @command{@value{AS}}
3286warning messages, so it might be helpful to have an idea of their
3287meanings to @command{@value{AS}}. These sections are used to permit the
3288value of every expression in your assembly language program to be a
3289section-relative address.
3290
3291@table @b
3292@cindex assembler internal logic error
3293@item ASSEMBLER-INTERNAL-LOGIC-ERROR!
3294An internal assembler logic error has been found. This means there is a
3295bug in the assembler.
3296
3297@cindex expr (internal section)
3298@item expr section
3299The assembler stores complex expression internally as combinations of
3300symbols. When it needs to represent an expression as a symbol, it puts
3301it 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
3314Assembled bytes
3315@ifset COFF-ELF
3316conventionally
3317@end ifset
3318fall into two sections: text and data.
3319@end ifset
3320You may have separate groups of
3321@ifset GENERIC
3322data in named sections
3323@end ifset
3324@ifclear GENERIC
3325@ifclear aout-bout
3326data in named sections
3327@end ifclear
3328@ifset aout-bout
3329text or data
3330@end ifset
3331@end ifclear
3332that you want to end up near to each other in the object file, even though they
3333are not contiguous in the assembler source. @command{@value{AS}} allows you to
3334use @dfn{subsections} for this purpose. Within each section, there can be
3335numbered subsections with values from 0 to 8192. Objects assembled into the
3336same subsection go into the object file together with other objects in the same
3337subsection. For example, a compiler might want to store constants in the text
3338section, but might not want to have them interspersed with the program being
3339assembled. In this case, the compiler could issue a @samp{.text 0} before each
3340section of code being output, and a @samp{.text 1} before each group of
3341constants being output.
3342
3343Subsections are optional. If you do not use subsections, everything
3344goes in subsection number zero.
3345
3346@ifset GENERIC
3347Each subsection is zero-padded up to a multiple of four bytes.
3348(Subsections may be padded a different amount on different flavors
3349of @command{@value{AS}}.)
3350@end ifset
3351@ifclear GENERIC
3352@ifset H8
3353On the H8/300 platform, each subsection is zero-padded to a word
3354boundary (two bytes).
3355The 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
3367Subsections appear in your object file in numeric order, lowest numbered
3368to highest. (All this to be compatible with other people's assemblers.)
3369The object file contains no representation of subsections; @code{@value{LD}} and
3370other programs that manipulate object files see no trace of them.
3371They just see all your text subsections as a text section, and all your
3372data subsections as a data section.
3373
3374To specify which subsection you want subsequent statements assembled
3375into, 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
3379When generating COFF output, you
3380@end ifset
3381@ifclear GENERIC
3382You
3383@end ifclear
3384can also use an extra subsection
3385argument with arbitrary named sections: @samp{.section @var{name},
3386@var{expression}}.
3387@end ifset
3388@ifset ELF
3389@ifset GENERIC
3390When generating ELF output, you
3391@end ifset
3392@ifclear GENERIC
3393You
3394@end ifclear
3395can also use the @code{.subsection} directive (@pxref{SubSection})
3396to 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}
3400is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
3401begins 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
3415Each section has a @dfn{location counter} incremented by one for every byte
3416assembled into that section. Because subsections are merely a convenience
3417restricted to @command{@value{AS}} there is no concept of a subsection location
3418counter. There is no way to directly manipulate a location counter---but the
3419@code{.align} directive changes it, and any label definition captures its
3420current value. The location counter of the section where statements are being
3421assembled 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
3428The bss section is used for local common variable storage.
3429You may allocate address space in the bss section, but you may
3430not dictate data to load into it before your program executes. When
3431your program starts running, all the contents of the bss
3432section are zeroed bytes.
3433
3434The @code{.lcomm} pseudo-op defines a symbol in the bss section; see
3435@ref{Lcomm,,@code{.lcomm}}.
3436
3437The @code{.comm} pseudo-op may be used to declare a common symbol, which is
3438another form of uninitialized symbol; see @ref{Comm,,@code{.comm}}.
3439
3440@ifset GENERIC
3441When assembling for a target which supports multiple sections, such as ELF or
3442COFF, you may switch into the @code{.bss} section and define symbols as usual;
3443see @ref{Section,,@code{.section}}. You may only assemble zero values into the
3444section. 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
3452Symbols are a central concept: the programmer uses symbols to name
3453things, the linker uses symbols to link, and the debugger uses symbols
3454to 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
3459the 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
3474A @dfn{label} is written as a symbol immediately followed by a colon
3475@samp{:}. The symbol then represents the current value of the
3476active location counter, and is, for example, a suitable instruction
3477operand. You are warned if you use the same symbol to represent two
3478different locations: the first definition overrides any other
3479definitions.
3480
3481@ifset HPPA
3482On the HPPA, the usual form for a label need not be immediately followed by a
3483colon, but instead must start in column zero. Only one label may be defined on
3484a single line. To work around this, the HPPA version of @command{@value{AS}} also
3485provides 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
3493A symbol can be given an arbitrary value by writing a symbol, followed
3494by an equals sign @samp{=}, followed by an expression
3495(@pxref{Expressions}). This is equivalent to using the @code{.set}
3496directive. @xref{Set,,@code{.set}}. In the same way, using a double
3497equals sign @samp{=}@samp{=} here represents an equivalent of the
3498@code{.eqv} directive. @xref{Eqv,,@code{.eqv}}.
3499
3500@ifset Blackfin
3501Blackfin 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
3510Symbol names begin with a letter or with one of @samp{._}. On most
3511machines, you can also use @code{$} in symbol names; exceptions are
3512noted in @ref{Machine Dependencies}. That character may be followed by any
3513string of digits, letters, dollar signs (unless otherwise noted for a
3514particular target machine), and underscores.
3515@end ifclear
3516@ifset SPECIAL-SYMS
3517@ifset H8
3518Symbol names begin with a letter or with one of @samp{._}. On the
3519Renesas SH you can also use @code{$} in symbol names. That
3520character may be followed by any string of digits, letters, dollar signs (save
3521on the H8/300), and underscores.
3522@end ifset
3523@end ifset
3524
3525Case of letters is significant: @code{foo} is a different symbol name
3526than @code{Foo}.
3527
3528Multibyte characters are supported. To generate a symbol name containing
3529multibyte characters enclose it within double quotes and use escape codes. cf
3530@xref{Strings}. Generating a multibyte symbol name from a label is not
3531currently supported.
3532
3533Each symbol has exactly one name. Each name in an assembly language program
3534refers to exactly one symbol. You may use that symbol name any number of times
3535in a program.
3536
3537@subheading Local Symbol Names
3538
3539@cindex local symbol names
3540@cindex symbol names, local
3541A local symbol is any symbol beginning with certain local label prefixes.
3542By 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
3544set of local label prefixes.
3545@ifset HPPA
3546On the HPPA local symbols begin with @samp{L$}.
3547@end ifset
3548
3549Local symbols are defined and used within the assembler, but they are
3550normally not saved in object files. Thus, they are not visible when debugging.
3551You 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
3559Local labels help compilers and programmers use names temporarily.
3560They create symbols which are guaranteed to be unique over the entire scope of
3561the input source code and which can be referred to by a simple notation.
3562To define a local label, write a label of the form @samp{@b{N}:} (where @b{N}
3563represents any positive integer). To refer to the most recent previous
3564definition of that label write @samp{@b{N}b}, using the same number as when
3565you 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
3567for ``forwards''.
3568
3569There is no restriction on how you can use these labels, and you can reuse them
3570too. So that it is possible to repeatedly define the same local label (using
3571the same number @samp{@b{N}}), although you can only refer to the most recently
3572defined local label of that number (for a backwards reference) or the next
3573definition of a specific local label for a forward reference. It is also worth
3574noting that the first 10 local labels (@samp{@b{0:}}@dots{}@samp{@b{9:}}) are
3575implemented in a slightly more efficient manner than the others.
3576
3577Here is an example:
3578
3579@smallexample
35801: branch 1f
35812: branch 1b
35821: branch 2f
35832: branch 1b
3584@end smallexample
3585
3586Which is the equivalent of:
3587
3588@smallexample
3589label_1: branch label_3
3590label_2: branch label_1
3591label_3: branch label_4
3592label_4: branch label_3
3593@end smallexample
3594
3595Local label names are only a notational device. They are immediately
3596transformed into more conventional symbol names before the assembler uses them.
3597The symbol names are stored in the symbol table, appear in error messages, and
3598are optionally emitted to the object file. The names are constructed using
3599these parts:
3600
3601@table @code
3602@item @emph{local label prefix}
3603All local symbols begin with the system-specific local label prefix.
3604Normally both @command{@value{AS}} and @code{@value{LD}} forget symbols
3605that start with the local label prefix. These labels are
3606used 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
3608object file. If you also instruct @code{@value{LD}} to retain these symbols,
3609you may use them in debugging.
3610
3611@item @var{number}
3612This is the number that was used in the local label definition. So if the
3613label is written @samp{55:} then the number is @samp{55}.
3614
3615@item @kbd{C-B}
3616This unusual character is included so you do not accidentally invent a symbol
3617of the same name. The character has ASCII value of @samp{\002} (control-B).
3618
3619@item @emph{ordinal number}
3620This 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
3622number @samp{15}, and so on. Likewise the first definition of @samp{1:} gets
3623the number @samp{1} and its 15th definition gets @samp{15} as well.
3624@end table
3625
3626So for example, the first @code{1:} may be named @code{.L1@kbd{C-B}1}, and
3627the 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
3633dollar labels. These labels go out of scope (i.e., they become undefined) as
3634soon as a non-local label is defined. Thus they remain valid for only a small
3635region of the input source code. Normal local labels, by contrast, remain in
3636scope for the entire file, or until they are redefined by another occurrence of
3637the same local label.
3638
3639Dollar labels are defined in exactly the same way as ordinary local labels,
3640except that they have a dollar sign suffix to their numeric value, e.g.,
3641@samp{@b{55$:}}.
3642
3643They can also be distinguished from ordinary local labels by their transformed
3644names which use ASCII character @samp{\001} (control-A) as the magic character
3645to 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)