Fix the block_found refactoring ChangeLog entry
[deliverable/binutils-gdb.git] / gas / doc / as.texinfo
CommitLineData
252b5132 1\input texinfo @c -*-Texinfo-*-
b90efa5b 2@c Copyright (C) 1991-2015 Free Software Foundation, Inc.
252b5132
RH
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
01642c12 9@c in config/obj-*.c
252b5132
RH
10@c (4) portable directives in potable[] in read.c
11@c %**start of header
12@setfilename as.info
13@c ---config---
a4fb0134
SC
14@macro gcctabopt{body}
15@code{\body\}
16@end macro
252b5132
RH
17@c defaults, config file may override:
18@set have-stabs
19@c ---
4a4c4a1d
MR
20@c man begin NAME
21@c ---
252b5132 22@include asconfig.texi
c428fa83 23@include bfdver.texi
252b5132 24@c ---
0285c67d 25@c man end
4a4c4a1d 26@c ---
252b5132 27@c common OR combinations of conditions
c1253627
NC
28@ifset COFF
29@set COFF-ELF
30@end ifset
31@ifset ELF
32@set COFF-ELF
33@end ifset
252b5132
RH
34@ifset AOUT
35@set aout-bout
36@end ifset
37@ifset ARM/Thumb
38@set ARM
39@end ifset
9982501a
JZ
40@ifset Blackfin
41@set Blackfin
42@end ifset
252b5132
RH
43@ifset BOUT
44@set aout-bout
45@end ifset
46@ifset H8/300
47@set H8
48@end ifset
252b5132
RH
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.
01642c12 71@c
252b5132
RH
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.
01642c12 76@c
252b5132
RH
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
01642c12 81@c discretion, of course.
252b5132
RH
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
9160ea82
AM
88@ifnottex
89@dircategory Software development
90@direntry
252b5132 91* As: (as). The GNU assembler.
59455fb1 92* Gas: (as). The GNU assembler.
9160ea82
AM
93@end direntry
94@end ifnottex
252b5132
RH
95
96@finalout
97@syncodeindex ky cp
98
0e9517a9 99@copying
252b5132
RH
100This file documents the GNU Assembler "@value{AS}".
101
0285c67d 102@c man begin COPYRIGHT
b90efa5b 103Copyright @copyright{} 1991-2015 Free Software Foundation, Inc.
252b5132 104
0285c67d 105Permission is granted to copy, distribute and/or modify this document
793c5807 106under the terms of the GNU Free Documentation License, Version 1.3
0285c67d
NC
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
c1253627 110section entitled ``GNU Free Documentation License''.
0285c67d
NC
111
112@c man end
0e9517a9 113@end copying
252b5132
RH
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
e49e529d
JM
121@ifset VERSION_PACKAGE
122@sp 1
123@subtitle @value{VERSION_PACKAGE}
124@end ifset
252b5132
RH
125@sp 1
126@subtitle Version @value{VERSION}
127@sp 1
128@sp 13
b45619c0 129The Free Software Foundation Inc.@: thanks The Nice Computer
252b5132 130Company of Australia for loaning Dean Elsner to write the
a4fb0134 131first (Vax) version of @command{as} for Project @sc{gnu}.
252b5132
RH
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
b90efa5b 152Copyright @copyright{} 1991-2015 Free Software Foundation, Inc.
252b5132 153
cf055d54 154 Permission is granted to copy, distribute and/or modify this document
793c5807 155 under the terms of the GNU Free Documentation License, Version 1.3
cf055d54
NC
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
c1253627 159 section entitled ``GNU Free Documentation License''.
252b5132 160
252b5132 161@end titlepage
4ecceb71 162@contents
252b5132 163
2e64b665 164@ifnottex
252b5132
RH
165@node Top
166@top Using @value{AS}
167
e49e529d
JM
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}.
252b5132 173@ifclear GENERIC
a4fb0134 174This version of the file describes @command{@value{AS}} configured to generate
252b5132
RH
175code for @value{TARGET} architectures.
176@end ifclear
cf055d54
NC
177
178This document is distributed under the terms of the GNU Free
179Documentation License. A copy of the license is included in the
c1253627 180section entitled ``GNU Free Documentation License''.
cf055d54 181
252b5132
RH
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
3a99f02f
DJ
190@ifset ELF
191* Object Attributes:: Object Attributes
192@end ifset
252b5132
RH
193* Machine Dependencies:: Machine Dependent Features
194* Reporting Bugs:: Reporting Bugs
195* Acknowledgements:: Who Did What
cf055d54 196* GNU Free Documentation License:: GNU Free Documentation License
28c9d252 197* AS Index:: AS Index
252b5132 198@end menu
2e64b665 199@end ifnottex
252b5132
RH
200
201@node Overview
202@chapter Overview
203@iftex
a4fb0134 204This manual is a user guide to the @sc{gnu} assembler @command{@value{AS}}.
252b5132 205@ifclear GENERIC
a4fb0134 206This version of the manual describes @command{@value{AS}} configured to generate
252b5132
RH
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
a4fb0134 214Here is a brief summary of how to invoke @command{@value{AS}}. For details,
96e9638b 215see @ref{Invoking,,Command-Line Options}.
252b5132 216
0285c67d
NC
217@c man title AS the portable GNU assembler.
218
a4fb0134 219@ignore
0285c67d
NC
220@c man begin SEEALSO
221gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
222@c man end
a4fb0134 223@end ignore
0285c67d 224
252b5132
RH
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
0285c67d 228@c man begin SYNOPSIS
83f10cb2 229@value{AS} [@b{-a}[@b{cdghlns}][=@var{file}]] [@b{--alternate}] [@b{-D}]
955974c6 230 [@b{--compress-debug-sections}] [@b{--nocompress-debug-sections}]
3d6b762c 231 [@b{--debug-prefix-map} @var{old}=@var{new}]
4bdd3565 232 [@b{--defsym} @var{sym}=@var{val}] [@b{-f}] [@b{-g}] [@b{--gstabs}]
b40bf0a2
NC
233 [@b{--gstabs+}] [@b{--gdwarf-2}] [@b{--gdwarf-sections}]
234 [@b{--help}] [@b{-I} @var{dir}] [@b{-J}]
4bdd3565
NC
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}]
a0b7da79 240 [@b{--fatal-warnings}] [@b{-w}] [@b{-x}] [@b{-Z}] [@b{@@@var{FILE}}]
451133ce 241 [@b{--sectname-subst}] [@b{--size-check=[error|warning]}]
a0b7da79
MM
242 [@b{--target-help}] [@var{target-options}]
243 [@b{--}|@var{files} @dots{}]
a4fb0134
SC
244@c
245@c Target dependent options are listed below. Keep the list sorted.
01642c12 246@c Add an empty line for separation.
a06ea964
NC
247@ifset AARCH64
248
249@emph{Target AArch64 options:}
250 [@b{-EB}|@b{-EL}]
69091a2c 251 [@b{-mabi}=@var{ABI}]
a06ea964 252@end ifset
625e1353
RH
253@ifset ALPHA
254
255@emph{Target Alpha options:}
256 [@b{-m@var{cpu}}]
257 [@b{-mdebug} | @b{-no-mdebug}]
198f1251 258 [@b{-replace} | @b{-noreplace}]
625e1353
RH
259 [@b{-relax}] [@b{-g}] [@b{-G@var{size}}]
260 [@b{-F}] [@b{-32addr}]
261@end ifset
252b5132 262@ifset ARC
a4fb0134
SC
263
264@emph{Target ARC options:}
265 [@b{-marc[5|6|7|8]}]
266 [@b{-EB}|@b{-EL}]
252b5132
RH
267@end ifset
268@ifset ARM
a4fb0134
SC
269
270@emph{Target ARM options:}
03b1477f 271@c Don't document the deprecated options
92081f48
HPN
272 [@b{-mcpu}=@var{processor}[+@var{extension}@dots{}]]
273 [@b{-march}=@var{architecture}[+@var{extension}@dots{}]]
33a392fb
PB
274 [@b{-mfpu}=@var{floating-point-format}]
275 [@b{-mfloat-abi}=@var{abi}]
d507cf36 276 [@b{-meabi}=@var{ver}]
03b1477f 277 [@b{-mthumb}]
a4fb0134
SC
278 [@b{-EB}|@b{-EL}]
279 [@b{-mapcs-32}|@b{-mapcs-26}|@b{-mapcs-float}|
280 @b{-mapcs-reentrant}]
7f266840 281 [@b{-mthumb-interwork}] [@b{-k}]
252b5132 282@end ifset
9982501a
JZ
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
328eb32e
HPN
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}]
ae57792d 297 [@b{--march=v0_v10} | @b{--march=v10} | @b{--march=v32} | @b{--march=common_v10_v32}]
328eb32e
HPN
298@c Deprecated -- deliberately not documented.
299@c [@b{-h}] [@b{-H}]
300@end ifset
252b5132 301@ifset D10V
a4fb0134
SC
302
303@emph{Target D10V options:}
304 [@b{-O}]
252b5132
RH
305@end ifset
306@ifset D30V
a4fb0134
SC
307
308@emph{Target D30V options:}
309 [@b{-O}|@b{-n}|@b{-N}]
252b5132 310@end ifset
cfb8c092
NC
311@ifset EPIPHANY
312
313@emph{Target EPIPHANY options:}
314 [@b{-mepiphany}|@b{-mepiphany16}]
315@end ifset
252b5132 316@ifset H8
6fd4f6cc
DD
317
318@emph{Target H8/300 options:}
319 [-h-tick-hex]
252b5132
RH
320@end ifset
321@ifset HPPA
322@c HPPA has no machine-dependent assembler options (yet).
323@end ifset
a4fb0134
SC
324@ifset I80386
325
326@emph{Target i386 options:}
542385d9 327 [@b{--32}|@b{--x32}|@b{--64}] [@b{-n}]
1ef52f49 328 [@b{-march}=@var{CPU}[+@var{EXTENSION}@dots{}]] [@b{-mtune}=@var{CPU}]
252b5132
RH
329@end ifset
330@ifset I960
a4fb0134
SC
331
332@emph{Target i960 options:}
252b5132 333@c see md_parse_option in tc-i960.c
a4fb0134
SC
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}]
252b5132 337@end ifset
587fe2b3 338@ifset IA64
a4fb0134 339
9e32ca89
NC
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}]
8c2fda1d 344 [@b{-mtune=itanium1}|@b{-mtune=itanium2}]
970d6792 345 [@b{-munwind-check=warning}|@b{-munwind-check=error}]
91d777ee 346 [@b{-mhint.b=ok}|@b{-mhint.b=warning}|@b{-mhint.b=error}]
9e32ca89
NC
347 [@b{-x}|@b{-xexplicit}] [@b{-xauto}] [@b{-xdebug}]
348@end ifset
a40cbfa3
NC
349@ifset IP2K
350
351@emph{Target IP2K options:}
352 [@b{-mip2022}|@b{-mip2022ext}]
353@end ifset
49f58d10
JB
354@ifset M32C
355
356@emph{Target M32C options:}
c54b5932 357 [@b{-m32c}|@b{-m16c}] [-relax] [-h-tick-hex]
49f58d10 358@end ifset
587fe2b3 359@ifset M32R
9e32ca89 360
a4fb0134
SC
361@emph{Target M32R options:}
362 [@b{--m32rx}|@b{--[no-]warn-explicit-parallel-conflicts}|
587fe2b3 363 @b{--W[n]p}]
ec694b89 364@end ifset
252b5132 365@ifset M680X0
a4fb0134
SC
366
367@emph{Target M680X0 options:}
368 [@b{-l}] [@b{-m68000}|@b{-m68010}|@b{-m68020}|@dots{}]
252b5132 369@end ifset
60bcf0fa 370@ifset M68HC11
a4fb0134
SC
371
372@emph{Target M68HC11 options:}
6927f982 373 [@b{-m68hc11}|@b{-m68hc12}|@b{-m68hcs12}|@b{-mm9s12x}|@b{-mm9s12xg}]
2f904664
SC
374 [@b{-mshort}|@b{-mlong}]
375 [@b{-mshort-double}|@b{-mlong-double}]
1370e33d 376 [@b{--force-long-branches}] [@b{--short-branches}]
a4fb0134
SC
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]}]
60bcf0fa 385@end ifset
a3c62988
NC
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
7ba29e2a
NC
391@ifset MICROBLAZE
392@emph{Target MICROBLAZE options:}
393@c MicroBlaze has no machine-dependent assembler options.
394@end ifset
252b5132 395@ifset MIPS
a4fb0134
SC
396
397@emph{Target MIPS options:}
78849248 398 [@b{-nocpp}] [@b{-EL}] [@b{-EB}] [@b{-O}[@var{optimization level}]]
437ee9d5 399 [@b{-g}[@var{debug level}]] [@b{-G} @var{num}] [@b{-KPIC}] [@b{-call_shared}]
0c000745 400 [@b{-non_shared}] [@b{-xgot} [@b{-mvxworks-pic}]
437ee9d5 401 [@b{-mabi}=@var{ABI}] [@b{-32}] [@b{-n32}] [@b{-64}] [@b{-mfp32}] [@b{-mgp32}]
351cdf24
MF
402 [@b{-mfp64}] [@b{-mgp64}] [@b{-mfpxx}]
403 [@b{-modd-spreg}] [@b{-mno-odd-spreg}]
437ee9d5 404 [@b{-march}=@var{CPU}] [@b{-mtune}=@var{CPU}] [@b{-mips1}] [@b{-mips2}]
af7ee8bf 405 [@b{-mips3}] [@b{-mips4}] [@b{-mips5}] [@b{-mips32}] [@b{-mips32r2}]
7361da2c
AB
406 [@b{-mips32r3}] [@b{-mips32r5}] [@b{-mips32r6}] [@b{-mips64}] [@b{-mips64r2}]
407 [@b{-mips64r3}] [@b{-mips64r5}] [@b{-mips64r6}]
437ee9d5 408 [@b{-construct-floats}] [@b{-no-construct-floats}]
ba92f887 409 [@b{-mnan=@var{encoding}}]
437ee9d5 410 [@b{-trap}] [@b{-no-break}] [@b{-break}] [@b{-no-trap}]
437ee9d5 411 [@b{-mips16}] [@b{-no-mips16}]
df58fc94 412 [@b{-mmicromips}] [@b{-mno-micromips}]
e16bfa71 413 [@b{-msmartmips}] [@b{-mno-smartmips}]
1f25f5d3 414 [@b{-mips3d}] [@b{-no-mips3d}]
deec1734 415 [@b{-mdmx}] [@b{-no-mdmx}]
2ef2b9ae 416 [@b{-mdsp}] [@b{-mno-dsp}]
8b082fb1 417 [@b{-mdspr2}] [@b{-mno-dspr2}]
56d438b1 418 [@b{-mmsa}] [@b{-mno-msa}]
7d64c587 419 [@b{-mxpa}] [@b{-mno-xpa}]
ef2e4d86 420 [@b{-mmt}] [@b{-mno-mt}]
dec0624d 421 [@b{-mmcu}] [@b{-mno-mcu}]
833794fc 422 [@b{-minsn32}] [@b{-mno-insn32}]
2babba43 423 [@b{-mfix7000}] [@b{-mno-fix7000}]
a8d14a88 424 [@b{-mfix-rm7000}] [@b{-mno-fix-rm7000}]
2babba43
MR
425 [@b{-mfix-vr4120}] [@b{-mno-fix-vr4120}]
426 [@b{-mfix-vr4130}] [@b{-mno-fix-vr4130}]
ecb4347a 427 [@b{-mdebug}] [@b{-no-mdebug}]
dcd410fe 428 [@b{-mpdr}] [@b{-mno-pdr}]
3c3bdf30
NC
429@end ifset
430@ifset MMIX
a4fb0134
SC
431
432@emph{Target MMIX options:}
433 [@b{--fixed-special-register-names}] [@b{--globalize-symbols}]
434 [@b{--gnu-syntax}] [@b{--relax}] [@b{--no-predefined-symbols}]
435 [@b{--no-expand}] [@b{--no-merge-gregs}] [@b{-x}]
973eb340 436 [@b{--linker-allocated-gregs}]
a4fb0134 437@end ifset
36591ba1
SL
438@ifset NIOSII
439
440@emph{Target Nios II options:}
441 [@b{-relax-all}] [@b{-relax-section}] [@b{-no-relax}]
442 [@b{-EB}] [@b{-EL}]
443@end ifset
35c08157
KLC
444@ifset NDS32
445
446@emph{Target NDS32 options:}
447 [@b{-EL}] [@b{-EB}] [@b{-O}] [@b{-Os}] [@b{-mcpu=@var{cpu}}]
448 [@b{-misa=@var{isa}}] [@b{-mabi=@var{abi}}] [@b{-mall-ext}]
449 [@b{-m[no-]16-bit}] [@b{-m[no-]perf-ext}] [@b{-m[no-]perf2-ext}]
450 [@b{-m[no-]string-ext}] [@b{-m[no-]dsp-ext}] [@b{-m[no-]mac}] [@b{-m[no-]div}]
451 [@b{-m[no-]audio-isa-ext}] [@b{-m[no-]fpu-sp-ext}] [@b{-m[no-]fpu-dp-ext}]
452 [@b{-m[no-]fpu-fma}] [@b{-mfpu-freg=@var{FREG}}] [@b{-mreduced-regs}]
453 [@b{-mfull-regs}] [@b{-m[no-]dx-regs}] [@b{-mpic}] [@b{-mno-relax}]
454 [@b{-mb2bb}]
455@end ifset
a4fb0134
SC
456@ifset PDP11
457
458@emph{Target PDP11 options:}
459 [@b{-mpic}|@b{-mno-pic}] [@b{-mall}] [@b{-mno-extensions}]
460 [@b{-m}@var{extension}|@b{-mno-}@var{extension}]
01642c12 461 [@b{-m}@var{cpu}] [@b{-m}@var{machine}]
a4fb0134
SC
462@end ifset
463@ifset PJ
464
465@emph{Target picoJava options:}
466 [@b{-mb}|@b{-me}]
467@end ifset
468@ifset PPC
469
470@emph{Target PowerPC options:}
b8b738ac
AM
471 [@b{-a32}|@b{-a64}]
472 [@b{-mpwrx}|@b{-mpwr2}|@b{-mpwr}|@b{-m601}|@b{-mppc}|@b{-mppc32}|@b{-m603}|@b{-m604}|@b{-m403}|@b{-m405}|
473 @b{-m440}|@b{-m464}|@b{-m476}|@b{-m7400}|@b{-m7410}|@b{-m7450}|@b{-m7455}|@b{-m750cl}|@b{-mppc64}|
aea77599 474 @b{-m620}|@b{-me500}|@b{-e500x2}|@b{-me500mc}|@b{-me500mc64}|@b{-me5500}|@b{-me6500}|@b{-mppc64bridge}|
b36546d2 475 @b{-mbooke}|@b{-mpower4}|@b{-mpwr4}|@b{-mpower5}|@b{-mpwr5}|@b{-mpwr5x}|@b{-mpower6}|@b{-mpwr6}|
5817ffd1
PB
476 @b{-mpower7}|@b{-mpwr7}|@b{-mpower8}|@b{-mpwr8}|@b{-ma2}|@b{-mcell}|@b{-mspe}|@b{-mtitan}|@b{-me300}|@b{-mcom}]
477 [@b{-many}] [@b{-maltivec}|@b{-mvsx}|@b{-mhtm}|@b{-mvle}]
a4fb0134 478 [@b{-mregnames}|@b{-mno-regnames}]
b8b738ac
AM
479 [@b{-mrelocatable}|@b{-mrelocatable-lib}|@b{-K PIC}] [@b{-memb}]
480 [@b{-mlittle}|@b{-mlittle-endian}|@b{-le}|@b{-mbig}|@b{-mbig-endian}|@b{-be}]
a4fb0134 481 [@b{-msolaris}|@b{-mno-solaris}]
b8b738ac 482 [@b{-nops=@var{count}}]
a4fb0134 483@end ifset
856ea05c
KP
484@ifset RL78
485
486@emph{Target RL78 options:}
487 [@b{-mg10}]
488 [@b{-m32bit-doubles}|@b{-m64bit-doubles}]
489@end ifset
c7927a3c
NC
490@ifset RX
491
492@emph{Target RX options:}
493 [@b{-mlittle-endian}|@b{-mbig-endian}]
c7927a3c 494 [@b{-m32bit-doubles}|@b{-m64bit-doubles}]
708e2187
NC
495 [@b{-muse-conventional-section-names}]
496 [@b{-msmall-data-limit}]
497 [@b{-mpid}]
498 [@b{-mrelax}]
499 [@b{-mint-register=@var{number}}]
500 [@b{-mgcc-abi}|@b{-mrx-abi}]
c7927a3c 501@end ifset
11c19e16
MS
502@ifset S390
503
504@emph{Target s390 options:}
505 [@b{-m31}|@b{-m64}] [@b{-mesa}|@b{-mzarch}] [@b{-march}=@var{CPU}]
506 [@b{-mregnames}|@b{-mno-regnames}]
507 [@b{-mwarn-areg-zero}]
508@end ifset
c3b7224a
NC
509@ifset SCORE
510
511@emph{Target SCORE options:}
512 [@b{-EB}][@b{-EL}][@b{-FIXDD}][@b{-NWARN}]
513 [@b{-SCORE5}][@b{-SCORE5U}][@b{-SCORE7}][@b{-SCORE3}]
514 [@b{-march=score7}][@b{-march=score3}]
515 [@b{-USE_R1}][@b{-KPIC}][@b{-O0}][@b{-G} @var{num}][@b{-V}]
516@end ifset
a4fb0134
SC
517@ifset SPARC
518
519@emph{Target SPARC options:}
520@c The order here is important. See c-sparc.texi.
521 [@b{-Av6}|@b{-Av7}|@b{-Av8}|@b{-Asparclet}|@b{-Asparclite}
522 @b{-Av8plus}|@b{-Av8plusa}|@b{-Av9}|@b{-Av9a}]
523 [@b{-xarch=v8plus}|@b{-xarch=v8plusa}] [@b{-bump}]
524 [@b{-32}|@b{-64}]
525@end ifset
526@ifset TIC54X
527
528@emph{Target TIC54X options:}
01642c12 529 [@b{-mcpu=54[123589]}|@b{-mcpu=54[56]lp}] [@b{-mfar-mode}|@b{-mf}]
a4fb0134
SC
530 [@b{-merrors-to-file} @var{<filename>}|@b{-me} @var{<filename>}]
531@end ifset
40b36596
JM
532@ifset TIC6X
533
534@emph{Target TIC6X options:}
98d23bef
BS
535 [@b{-march=@var{arch}}] [@b{-mbig-endian}|@b{-mlittle-endian}]
536 [@b{-mdsbt}|@b{-mno-dsbt}] [@b{-mpid=no}|@b{-mpid=near}|@b{-mpid=far}]
537 [@b{-mpic}|@b{-mno-pic}]
40b36596 538@end ifset
aa137e4d
NC
539@ifset TILEGX
540
541@emph{Target TILE-Gx options:}
fb6cedde 542 [@b{-m32}|@b{-m64}][@b{-EB}][@b{-EL}]
aa137e4d
NC
543@end ifset
544@ifset TILEPRO
545@c TILEPro has no machine-dependent assembler options
546@end ifset
b6605ddd 547@ifset VISIUM
40b36596 548
b6605ddd
EB
549@emph{Target Visium options:}
550 [@b{-mtune=@var{arch}}]
551@end ifset
2d8b84ae
SA
552@ifset XTENSA
553
554@emph{Target Xtensa options:}
555 [@b{--[no-]text-section-literals}] [@b{--[no-]absolute-literals}]
556 [@b{--[no-]target-align}] [@b{--[no-]longcalls}]
557 [@b{--[no-]transform}]
558 [@b{--rename-section} @var{oldname}=@var{newname}]
a82c7d90 559 [@b{--[no-]trampolines}]
2d8b84ae 560@end ifset
3c9b82ba
NC
561@ifset Z80
562
563@emph{Target Z80 options:}
564 [@b{-z80}] [@b{-r800}]
565 [@b{ -ignore-undocumented-instructions}] [@b{-Wnud}]
566 [@b{ -ignore-unportable-instructions}] [@b{-Wnup}]
567 [@b{ -warn-undocumented-instructions}] [@b{-Wud}]
568 [@b{ -warn-unportable-instructions}] [@b{-Wup}]
569 [@b{ -forbid-undocumented-instructions}] [@b{-Fud}]
570 [@b{ -forbid-unportable-instructions}] [@b{-Fup}]
571@end ifset
a4fb0134 572@ifset Z8000
b6605ddd 573
a4fb0134 574@c Z8000 has no machine-dependent assembler options
252b5132 575@end ifset
e0001a05 576
0285c67d 577@c man end
252b5132
RH
578@end smallexample
579
0285c67d
NC
580@c man begin OPTIONS
581
a4fb0134 582@table @gcctabopt
38fc1cb1 583@include at-file.texi
a0b7da79 584
83f10cb2 585@item -a[cdghlmns]
252b5132
RH
586Turn on listings, in any of a variety of ways:
587
a4fb0134 588@table @gcctabopt
252b5132
RH
589@item -ac
590omit false conditionals
591
592@item -ad
593omit debugging directives
594
83f10cb2
NC
595@item -ag
596include general information, like @value{AS} version and options passed
597
252b5132
RH
598@item -ah
599include high-level source
600
601@item -al
602include assembly
603
604@item -am
605include macro expansions
606
607@item -an
608omit forms processing
609
610@item -as
611include symbols
612
613@item =file
614set the name of the listing file
615@end table
616
617You may combine these options; for example, use @samp{-aln} for assembly
618listing without forms processing. The @samp{=file} option, if used, must be
619the last one. By itself, @samp{-a} defaults to @samp{-ahls}.
620
caa32fe5 621@item --alternate
96e9638b
BW
622Begin in alternate macro mode.
623@ifclear man
624@xref{Altmacro,,@code{.altmacro}}.
625@end ifclear
caa32fe5 626
955974c6 627@item --compress-debug-sections
19a7fe52
L
628Compress DWARF debug sections using zlib with SHF_COMPRESSED from the
629ELF ABI. The resulting object file may not be compatible with older
630linkers and object file utilities. Note if compression would make a
631given section @emph{larger} then it is not compressed.
955974c6 632
151411f8
L
633@ifset ELF
634@cindex @samp{--compress-debug-sections=} option
635@item --compress-debug-sections=none
636@itemx --compress-debug-sections=zlib
637@itemx --compress-debug-sections=zlib-gnu
638@itemx --compress-debug-sections=zlib-gabi
639These options control how DWARF debug sections are compressed.
640@option{--compress-debug-sections=none} is equivalent to
641@option{--nocompress-debug-sections}.
642@option{--compress-debug-sections=zlib} and
19a7fe52 643@option{--compress-debug-sections=zlib-gabi} are equivalent to
151411f8 644@option{--compress-debug-sections}.
19a7fe52
L
645@option{--compress-debug-sections=zlib-gnu} compresses DWARF debug
646sections using zlib. The debug sections are renamed to begin with
647@samp{.zdebug}. Note if compression would make a given section
648@emph{larger} then it is not compressed nor renamed.
649
151411f8
L
650@end ifset
651
955974c6
CC
652@item --nocompress-debug-sections
653Do not compress DWARF debug sections. This is the default.
654
252b5132
RH
655@item -D
656Ignored. This option is accepted for script compatibility with calls to
657other assemblers.
658
3d6b762c
JM
659@item --debug-prefix-map @var{old}=@var{new}
660When assembling files in directory @file{@var{old}}, record debugging
661information describing them as in @file{@var{new}} instead.
662
252b5132
RH
663@item --defsym @var{sym}=@var{value}
664Define the symbol @var{sym} to be @var{value} before assembling the input file.
665@var{value} must be an integer constant. As in C, a leading @samp{0x}
bf083c64
NC
666indicates a hexadecimal value, and a leading @samp{0} indicates an octal
667value. The value of the symbol can be overridden inside a source file via the
668use of a @code{.set} pseudo-op.
252b5132
RH
669
670@item -f
671``fast''---skip whitespace and comment preprocessing (assume source is
672compiler output).
673
329e276d
NC
674@item -g
675@itemx --gen-debug
676Generate debugging information for each assembler source line using whichever
677debug format is preferred by the target. This currently means either STABS,
678ECOFF or DWARF2.
679
252b5132
RH
680@item --gstabs
681Generate stabs debugging information for each assembler line. This
682may help debugging assembler code, if the debugger can handle it.
683
05da4302
NC
684@item --gstabs+
685Generate stabs debugging information for each assembler line, with GNU
686extensions that probably only gdb can handle, and that could make other
687debuggers crash or refuse to read your program. This
688may help debugging assembler code. Currently the only GNU extension is
689the location of the current working directory at assembling time.
690
329e276d 691@item --gdwarf-2
cdf82bcf 692Generate DWARF2 debugging information for each assembler line. This
c1253627 693may help debugging assembler code, if the debugger can handle it. Note---this
85a39694 694option is only supported by some targets, not all of them.
cdf82bcf 695
b40bf0a2
NC
696@item --gdwarf-sections
697Instead of creating a .debug_line section, create a series of
698.debug_line.@var{foo} sections where @var{foo} is the name of the
699corresponding code section. For example a code section called @var{.text.func}
700will have its dwarf line number information placed into a section called
701@var{.debug_line.text.func}. If the code section is just called @var{.text}
702then debug line section will still be called just @var{.debug_line} without any
703suffix.
704
21be61f5
L
705@item --size-check=error
706@itemx --size-check=warning
707Issue an error or warning for invalid ELF .size directive.
708
252b5132
RH
709@item --help
710Print a summary of the command line options and exit.
711
ea20a7da
CC
712@item --target-help
713Print a summary of all target specific options and exit.
714
252b5132
RH
715@item -I @var{dir}
716Add directory @var{dir} to the search list for @code{.include} directives.
717
718@item -J
719Don't warn about signed overflow.
720
721@item -K
722@ifclear DIFF-TBL-KLUGE
723This option is accepted but has no effect on the @value{TARGET} family.
724@end ifclear
725@ifset DIFF-TBL-KLUGE
726Issue warnings when difference tables altered for long displacements.
727@end ifset
728
729@item -L
730@itemx --keep-locals
ba83aca1
BW
731Keep (in the symbol table) local symbols. These symbols start with
732system-specific local label prefixes, typically @samp{.L} for ELF systems
733or @samp{L} for traditional a.out systems.
734@ifclear man
735@xref{Symbol Names}.
736@end ifclear
252b5132 737
c3a27914
NC
738@item --listing-lhs-width=@var{number}
739Set the maximum width, in words, of the output data column for an assembler
740listing to @var{number}.
741
742@item --listing-lhs-width2=@var{number}
743Set the maximum width, in words, of the output data column for continuation
744lines in an assembler listing to @var{number}.
745
746@item --listing-rhs-width=@var{number}
747Set the maximum width of an input source line, as displayed in a listing, to
748@var{number} bytes.
749
750@item --listing-cont-lines=@var{number}
751Set the maximum number of lines printed in a listing for a single line of input
752to @var{number} + 1.
753
252b5132 754@item -o @var{objfile}
a4fb0134 755Name the object-file output from @command{@value{AS}} @var{objfile}.
252b5132
RH
756
757@item -R
758Fold the data section into the text section.
759
4bdd3565
NC
760@kindex --hash-size=@var{number}
761Set the default size of GAS's hash tables to a prime number close to
762@var{number}. Increasing this value can reduce the length of time it takes the
763assembler to perform its tasks, at the expense of increasing the assembler's
764memory requirements. Similarly reducing this value can reduce the memory
765requirements at the expense of speed.
766
767@item --reduce-memory-overheads
768This option reduces GAS's memory requirements, at the expense of making the
769assembly processes slower. Currently this switch is a synonym for
770@samp{--hash-size=4051}, but in the future it may have other effects as well.
771
451133ce
NP
772@ifset ELF
773@item --sectname-subst
774Honor substitution sequences in section names.
775@ifclear man
776@xref{Section Name Substitutions,,@code{.section @var{name}}}.
777@end ifclear
778@end ifset
779
252b5132
RH
780@item --statistics
781Print the maximum space (in bytes) and total time (in seconds) used by
782assembly.
783
784@item --strip-local-absolute
785Remove local absolute symbols from the outgoing symbol table.
786
787@item -v
788@itemx -version
a4fb0134 789Print the @command{as} version.
252b5132
RH
790
791@item --version
a4fb0134 792Print the @command{as} version and exit.
252b5132
RH
793
794@item -W
2bdd6cf5 795@itemx --no-warn
252b5132
RH
796Suppress warning messages.
797
2bdd6cf5
GK
798@item --fatal-warnings
799Treat warnings as errors.
800
801@item --warn
802Don't suppress warning messages or treat them as errors.
803
252b5132
RH
804@item -w
805Ignored.
806
807@item -x
808Ignored.
809
810@item -Z
811Generate an object file even after errors.
812
813@item -- | @var{files} @dots{}
814Standard input, or source files to assemble.
815
816@end table
2a633939
JM
817@c man end
818
a06ea964
NC
819@ifset AARCH64
820
821@ifclear man
822@xref{AArch64 Options}, for the options available when @value{AS} is configured
823for the 64-bit mode of the ARM Architecture (AArch64).
824@end ifclear
825
826@ifset man
827@c man begin OPTIONS
828The following options are available when @value{AS} is configured for the
82964-bit mode of the ARM Architecture (AArch64).
830@c man end
831@c man begin INCLUDE
832@include c-aarch64.texi
833@c ended inside the included file
834@end ifset
835
836@end ifset
837
2a633939
JM
838@ifset ALPHA
839
840@ifclear man
841@xref{Alpha Options}, for the options available when @value{AS} is configured
842for an Alpha processor.
843@end ifclear
844
845@ifset man
846@c man begin OPTIONS
847The following options are available when @value{AS} is configured for an Alpha
848processor.
849@c man end
850@c man begin INCLUDE
851@include c-alpha.texi
852@c ended inside the included file
853@end ifset
854
855@end ifset
252b5132 856
2a633939 857@c man begin OPTIONS
252b5132
RH
858@ifset ARC
859The following options are available when @value{AS} is configured for
860an ARC processor.
861
a4fb0134 862@table @gcctabopt
0d2bcfaf
NC
863@item -marc[5|6|7|8]
864This option selects the core processor variant.
865@item -EB | -EL
866Select either big-endian (-EB) or little-endian (-EL) output.
252b5132
RH
867@end table
868@end ifset
869
870@ifset ARM
871The following options are available when @value{AS} is configured for the ARM
872processor family.
873
a4fb0134 874@table @gcctabopt
92081f48 875@item -mcpu=@var{processor}[+@var{extension}@dots{}]
cdf82bcf 876Specify which ARM processor variant is the target.
92081f48 877@item -march=@var{architecture}[+@var{extension}@dots{}]
cdf82bcf 878Specify which ARM architecture variant is used by the target.
03b1477f 879@item -mfpu=@var{floating-point-format}
a349d9dd 880Select which Floating Point architecture is the target.
33a392fb
PB
881@item -mfloat-abi=@var{abi}
882Select which floating point ABI is in use.
03b1477f
RE
883@item -mthumb
884Enable Thumb only instruction decoding.
7f266840 885@item -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant
252b5132
RH
886Select which procedure calling convention is in use.
887@item -EB | -EL
888Select either big-endian (-EB) or little-endian (-EL) output.
cdf82bcf
NC
889@item -mthumb-interwork
890Specify that the code has been generated with interworking between Thumb and
891ARM code in mind.
2e6976a8
DG
892@item -mccs
893Turns on CodeComposer Studio assembly syntax compatibility mode.
cdf82bcf
NC
894@item -k
895Specify that PIC code has been generated.
252b5132
RH
896@end table
897@end ifset
635fb38d 898@c man end
252b5132 899
9982501a 900@ifset Blackfin
8611b8fd
MF
901
902@ifclear man
903@xref{Blackfin Options}, for the options available when @value{AS} is
904configured for the Blackfin processor family.
905@end ifclear
906
907@ifset man
908@c man begin OPTIONS
9982501a
JZ
909The following options are available when @value{AS} is configured for
910the Blackfin processor family.
8611b8fd
MF
911@c man end
912@c man begin INCLUDE
913@include c-bfin.texi
914@c ended inside the included file
915@end ifset
9982501a 916
9982501a
JZ
917@end ifset
918
635fb38d 919@c man begin OPTIONS
328eb32e
HPN
920@ifset CRIS
921See the info pages for documentation of the CRIS-specific options.
922@end ifset
923
252b5132
RH
924@ifset D10V
925The following options are available when @value{AS} is configured for
926a D10V processor.
a4fb0134 927@table @gcctabopt
252b5132
RH
928@cindex D10V optimization
929@cindex optimization, D10V
930@item -O
931Optimize output by parallelizing instructions.
932@end table
933@end ifset
934
935@ifset D30V
936The following options are available when @value{AS} is configured for a D30V
937processor.
a4fb0134 938@table @gcctabopt
252b5132
RH
939@cindex D30V optimization
940@cindex optimization, D30V
941@item -O
942Optimize output by parallelizing instructions.
943
944@cindex D30V nops
945@item -n
946Warn when nops are generated.
947
948@cindex D30V nops after 32-bit multiply
949@item -N
950Warn when a nop after a 32-bit multiply instruction is generated.
951@end table
952@end ifset
731caf76
L
953@c man end
954
cfb8c092
NC
955@ifset EPIPHANY
956The following options are available when @value{AS} is configured for the
957Adapteva EPIPHANY series.
958
56b13185
JR
959@ifclear man
960@xref{Epiphany Options}, for the options available when @value{AS} is
961configured for an Epiphany processor.
962@end ifclear
cfb8c092 963
56b13185
JR
964@ifset man
965@c man begin OPTIONS
966The following options are available when @value{AS} is configured for
967an Epiphany processor.
968@c man end
969@c man begin INCLUDE
970@include c-epiphany.texi
0c76cae8
AM
971@c ended inside the included file
972@end ifset
973
974@end ifset
975
976@ifset H8300
977
978@ifclear man
979@xref{H8/300 Options}, for the options available when @value{AS} is configured
980for an H8/300 processor.
981@end ifclear
982
983@ifset man
984@c man begin OPTIONS
985The following options are available when @value{AS} is configured for an H8/300
986processor.
987@c man end
988@c man begin INCLUDE
989@include c-h8300.texi
56b13185
JR
990@c ended inside the included file
991@end ifset
cfb8c092 992
cfb8c092
NC
993@end ifset
994
731caf76 995@ifset I80386
252b5132 996
731caf76
L
997@ifclear man
998@xref{i386-Options}, for the options available when @value{AS} is
999configured for an i386 processor.
1000@end ifclear
1001
1002@ifset man
1003@c man begin OPTIONS
1004The following options are available when @value{AS} is configured for
1005an i386 processor.
1006@c man end
1007@c man begin INCLUDE
1008@include c-i386.texi
1009@c ended inside the included file
1010@end ifset
1011
1012@end ifset
1013
1014@c man begin OPTIONS
252b5132
RH
1015@ifset I960
1016The following options are available when @value{AS} is configured for the
1017Intel 80960 processor.
1018
a4fb0134 1019@table @gcctabopt
252b5132
RH
1020@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
1021Specify which variant of the 960 architecture is the target.
1022
1023@item -b
1024Add code to collect statistics about branches taken.
1025
1026@item -no-relax
1027Do not alter compare-and-branch instructions for long displacements;
1028error if necessary.
1029
1030@end table
1031@end ifset
1032
a40cbfa3
NC
1033@ifset IP2K
1034The following options are available when @value{AS} is configured for the
ec88d317 1035Ubicom IP2K series.
a40cbfa3
NC
1036
1037@table @gcctabopt
1038
1039@item -mip2022ext
1040Specifies that the extended IP2022 instructions are allowed.
1041
1042@item -mip2022
8dfa0188 1043Restores the default behaviour, which restricts the permitted instructions to
a40cbfa3
NC
1044just the basic IP2022 ones.
1045
1046@end table
1047@end ifset
1048
49f58d10
JB
1049@ifset M32C
1050The following options are available when @value{AS} is configured for the
1051Renesas M32C and M16C processors.
1052
1053@table @gcctabopt
1054
1055@item -m32c
1056Assemble M32C instructions.
1057
1058@item -m16c
1059Assemble M16C instructions (the default).
1060
c54b5932
DD
1061@item -relax
1062Enable support for link-time relaxations.
1063
1064@item -h-tick-hex
1065Support H'00 style hex constants in addition to 0x00 style.
1066
49f58d10
JB
1067@end table
1068@end ifset
1069
ec694b89
NC
1070@ifset M32R
1071The following options are available when @value{AS} is configured for the
26597c86 1072Renesas M32R (formerly Mitsubishi M32R) series.
ec694b89 1073
a4fb0134 1074@table @gcctabopt
ec694b89
NC
1075
1076@item --m32rx
1077Specify which processor in the M32R family is the target. The default
1078is normally the M32R, but this option changes it to the M32RX.
1079
1080@item --warn-explicit-parallel-conflicts or --Wp
1081Produce warning messages when questionable parallel constructs are
01642c12 1082encountered.
ec694b89
NC
1083
1084@item --no-warn-explicit-parallel-conflicts or --Wnp
01642c12
RM
1085Do not produce warning messages when questionable parallel constructs are
1086encountered.
ec694b89
NC
1087
1088@end table
1089@end ifset
252b5132
RH
1090
1091@ifset M680X0
1092The following options are available when @value{AS} is configured for the
1093Motorola 68000 series.
1094
a4fb0134 1095@table @gcctabopt
252b5132
RH
1096
1097@item -l
1098Shorten references to undefined symbols, to one word instead of two.
1099
0285c67d
NC
1100@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030
1101@itemx | -m68040 | -m68060 | -m68302 | -m68331 | -m68332
1102@itemx | -m68333 | -m68340 | -mcpu32 | -m5200
252b5132
RH
1103Specify what processor in the 68000 family is the target. The default
1104is normally the 68020, but this can be changed at configuration time.
1105
1106@item -m68881 | -m68882 | -mno-68881 | -mno-68882
1107The target machine does (or does not) have a floating-point coprocessor.
1108The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
1109the basic 68000 is not compatible with the 68881, a combination of the
1110two can be specified, since it's possible to do emulation of the
1111coprocessor instructions with the main processor.
1112
1113@item -m68851 | -mno-68851
1114The target machine does (or does not) have a memory-management
1115unit coprocessor. The default is to assume an MMU for 68020 and up.
1116
1117@end table
1118@end ifset
1119
36591ba1
SL
1120@ifset NIOSII
1121
1122@ifclear man
1123@xref{Nios II Options}, for the options available when @value{AS} is configured
1124for an Altera Nios II processor.
1125@end ifclear
1126
1127@ifset man
1128@c man begin OPTIONS
1129The following options are available when @value{AS} is configured for an
1130Altera Nios II processor.
1131@c man end
1132@c man begin INCLUDE
1133@include c-nios2.texi
1134@c ended inside the included file
1135@end ifset
1136@end ifset
1137
e135f41b
NC
1138@ifset PDP11
1139
1140For details about the PDP-11 machine dependent features options,
1141see @ref{PDP-11-Options}.
1142
a4fb0134 1143@table @gcctabopt
e135f41b
NC
1144@item -mpic | -mno-pic
1145Generate position-independent (or position-dependent) code. The
a4fb0134 1146default is @option{-mpic}.
e135f41b
NC
1147
1148@item -mall
1149@itemx -mall-extensions
1150Enable all instruction set extensions. This is the default.
1151
1152@item -mno-extensions
1153Disable all instruction set extensions.
1154
1155@item -m@var{extension} | -mno-@var{extension}
1156Enable (or disable) a particular instruction set extension.
1157
1158@item -m@var{cpu}
1159Enable the instruction set extensions supported by a particular CPU, and
1160disable all other extensions.
1161
1162@item -m@var{machine}
1163Enable the instruction set extensions supported by a particular machine
1164model, and disable all other extensions.
1165@end table
1166
1167@end ifset
1168
041dd5a9
ILT
1169@ifset PJ
1170The following options are available when @value{AS} is configured for
1171a picoJava processor.
1172
a4fb0134 1173@table @gcctabopt
041dd5a9
ILT
1174
1175@cindex PJ endianness
1176@cindex endianness, PJ
1177@cindex big endian output, PJ
1178@item -mb
1179Generate ``big endian'' format output.
1180
1181@cindex little endian output, PJ
1182@item -ml
1183Generate ``little endian'' format output.
1184
1185@end table
1186@end ifset
1187
60bcf0fa
NC
1188@ifset M68HC11
1189The following options are available when @value{AS} is configured for the
1190Motorola 68HC11 or 68HC12 series.
1191
a4fb0134 1192@table @gcctabopt
60bcf0fa 1193
6927f982 1194@item -m68hc11 | -m68hc12 | -m68hcs12 | -mm9s12x | -mm9s12xg
60bcf0fa
NC
1195Specify what processor is the target. The default is
1196defined by the configuration option when building the assembler.
1197
6927f982
NC
1198@item --xgate-ramoffset
1199Instruct the linker to offset RAM addresses from S12X address space into
1200XGATE address space.
1201
2f904664
SC
1202@item -mshort
1203Specify to use the 16-bit integer ABI.
1204
1205@item -mlong
01642c12 1206Specify to use the 32-bit integer ABI.
2f904664
SC
1207
1208@item -mshort-double
01642c12 1209Specify to use the 32-bit double ABI.
2f904664
SC
1210
1211@item -mlong-double
01642c12 1212Specify to use the 64-bit double ABI.
2f904664 1213
1370e33d 1214@item --force-long-branches
60bcf0fa
NC
1215Relative branches are turned into absolute ones. This concerns
1216conditional branches, unconditional branches and branches to a
1217sub routine.
1218
1370e33d
NC
1219@item -S | --short-branches
1220Do not turn relative branches into absolute ones
60bcf0fa
NC
1221when the offset is out of range.
1222
1223@item --strict-direct-mode
1224Do not turn the direct addressing mode into extended addressing mode
1225when the instruction does not support direct addressing mode.
1226
1227@item --print-insn-syntax
1228Print the syntax of instruction in case of error.
1229
1230@item --print-opcodes
6927f982 1231Print the list of instructions with syntax and then exit.
60bcf0fa
NC
1232
1233@item --generate-example
6927f982 1234Print an example of instruction for each possible instruction and then exit.
a4fb0134 1235This option is only useful for testing @command{@value{AS}}.
60bcf0fa
NC
1236
1237@end table
1238@end ifset
1239
252b5132 1240@ifset SPARC
a4fb0134 1241The following options are available when @command{@value{AS}} is configured
252b5132
RH
1242for the SPARC architecture:
1243
a4fb0134 1244@table @gcctabopt
252b5132
RH
1245@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
1246@itemx -Av8plus | -Av8plusa | -Av9 | -Av9a
1247Explicitly select a variant of the SPARC architecture.
1248
1249@samp{-Av8plus} and @samp{-Av8plusa} select a 32 bit environment.
1250@samp{-Av9} and @samp{-Av9a} select a 64 bit environment.
1251
1252@samp{-Av8plusa} and @samp{-Av9a} enable the SPARC V9 instruction set with
1253UltraSPARC extensions.
1254
1255@item -xarch=v8plus | -xarch=v8plusa
1256For compatibility with the Solaris v9 assembler. These options are
1257equivalent to -Av8plus and -Av8plusa, respectively.
1258
1259@item -bump
1260Warn when the assembler switches to another architecture.
1261@end table
1262@end ifset
1263
39bec121
TW
1264@ifset TIC54X
1265The following options are available when @value{AS} is configured for the 'c54x
01642c12 1266architecture.
39bec121 1267
a4fb0134 1268@table @gcctabopt
39bec121
TW
1269@item -mfar-mode
1270Enable extended addressing mode. All addresses and relocations will assume
1271extended addressing (usually 23 bits).
1272@item -mcpu=@var{CPU_VERSION}
1273Sets the CPU version being compiled for.
1274@item -merrors-to-file @var{FILENAME}
1275Redirect error output to a file, for broken systems which don't support such
1276behaviour in the shell.
1277@end table
1278@end ifset
1279
252b5132
RH
1280@ifset MIPS
1281The following options are available when @value{AS} is configured for
98508b2a 1282a MIPS processor.
252b5132 1283
a4fb0134 1284@table @gcctabopt
252b5132
RH
1285@item -G @var{num}
1286This option sets the largest size of an object that can be referenced
1287implicitly with the @code{gp} register. It is only accepted for targets that
1288use ECOFF format, such as a DECstation running Ultrix. The default value is 8.
1289
1290@cindex MIPS endianness
1291@cindex endianness, MIPS
1292@cindex big endian output, MIPS
1293@item -EB
1294Generate ``big endian'' format output.
1295
1296@cindex little endian output, MIPS
1297@item -EL
1298Generate ``little endian'' format output.
1299
1300@cindex MIPS ISA
1301@item -mips1
1302@itemx -mips2
1303@itemx -mips3
e7af610e 1304@itemx -mips4
437ee9d5 1305@itemx -mips5
e7af610e 1306@itemx -mips32
af7ee8bf 1307@itemx -mips32r2
ae52f483
AB
1308@itemx -mips32r3
1309@itemx -mips32r5
7361da2c 1310@itemx -mips32r6
4058e45f 1311@itemx -mips64
5f74bc13 1312@itemx -mips64r2
ae52f483
AB
1313@itemx -mips64r3
1314@itemx -mips64r5
7361da2c 1315@itemx -mips64r6
98508b2a 1316Generate code for a particular MIPS Instruction Set Architecture level.
437ee9d5
TS
1317@samp{-mips1} is an alias for @samp{-march=r3000}, @samp{-mips2} is an
1318alias for @samp{-march=r6000}, @samp{-mips3} is an alias for
1319@samp{-march=r4000} and @samp{-mips4} is an alias for @samp{-march=r8000}.
ae52f483 1320@samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, @samp{-mips32r3},
7361da2c
AB
1321@samp{-mips32r5}, @samp{-mips32r6}, @samp{-mips64}, @samp{-mips64r2},
1322@samp{-mips64r3}, @samp{-mips64r5}, and @samp{-mips64r6} correspond to generic
1323MIPS V, MIPS32, MIPS32 Release 2, MIPS32 Release 3, MIPS32 Release 5, MIPS32
1324Release 6, MIPS64, MIPS64 Release 2, MIPS64 Release 3, MIPS64 Release 5, and
1325MIPS64 Release 6 ISA processors, respectively.
437ee9d5 1326
98508b2a
RS
1327@item -march=@var{cpu}
1328Generate code for a particular MIPS CPU.
437ee9d5
TS
1329
1330@item -mtune=@var{cpu}
98508b2a 1331Schedule and tune for a particular MIPS CPU.
437ee9d5
TS
1332
1333@item -mfix7000
1334@itemx -mno-fix7000
1335Cause nops to be inserted if the read of the destination register
1336of an mfhi or mflo instruction occurs in the following two instructions.
1337
a8d14a88
CM
1338@item -mfix-rm7000
1339@itemx -mno-fix-rm7000
1340Cause nops to be inserted if a dmult or dmultu instruction is
1341followed by a load instruction.
1342
ecb4347a
DJ
1343@item -mdebug
1344@itemx -no-mdebug
1345Cause stabs-style debugging output to go into an ECOFF-style .mdebug
1346section instead of the standard ELF .stabs sections.
1347
dcd410fe
RO
1348@item -mpdr
1349@itemx -mno-pdr
1350Control generation of @code{.pdr} sections.
1351
437ee9d5
TS
1352@item -mgp32
1353@itemx -mfp32
1354The register sizes are normally inferred from the ISA and ABI, but these
1355flags force a certain group of registers to be treated as 32 bits wide at
1356all times. @samp{-mgp32} controls the size of general-purpose registers
1357and @samp{-mfp32} controls the size of floating-point registers.
1358
351cdf24
MF
1359@item -mgp64
1360@itemx -mfp64
1361The register sizes are normally inferred from the ISA and ABI, but these
1362flags force a certain group of registers to be treated as 64 bits wide at
1363all times. @samp{-mgp64} controls the size of general-purpose registers
1364and @samp{-mfp64} controls the size of floating-point registers.
1365
1366@item -mfpxx
1367The register sizes are normally inferred from the ISA and ABI, but using
1368this flag in combination with @samp{-mabi=32} enables an ABI variant
1369which will operate correctly with floating-point registers which are
137032 or 64 bits wide.
1371
1372@item -modd-spreg
1373@itemx -mno-odd-spreg
1374Enable use of floating-point operations on odd-numbered single-precision
1375registers when supported by the ISA. @samp{-mfpxx} implies
1376@samp{-mno-odd-spreg}, otherwise the default is @samp{-modd-spreg}.
1377
437ee9d5
TS
1378@item -mips16
1379@itemx -no-mips16
1380Generate code for the MIPS 16 processor. This is equivalent to putting
1381@code{.set mips16} at the start of the assembly file. @samp{-no-mips16}
1382turns off this option.
252b5132 1383
df58fc94
RS
1384@item -mmicromips
1385@itemx -mno-micromips
1386Generate code for the microMIPS processor. This is equivalent to putting
1387@code{.set micromips} at the start of the assembly file. @samp{-mno-micromips}
1388turns off this option. This is equivalent to putting @code{.set nomicromips}
1389at the start of the assembly file.
1390
e16bfa71
TS
1391@item -msmartmips
1392@itemx -mno-smartmips
1393Enables the SmartMIPS extension to the MIPS32 instruction set. This is
1394equivalent to putting @code{.set smartmips} at the start of the assembly file.
1395@samp{-mno-smartmips} turns off this option.
1396
1f25f5d3
CD
1397@item -mips3d
1398@itemx -no-mips3d
1399Generate code for the MIPS-3D Application Specific Extension.
1400This tells the assembler to accept MIPS-3D instructions.
1401@samp{-no-mips3d} turns off this option.
1402
deec1734
CD
1403@item -mdmx
1404@itemx -no-mdmx
1405Generate code for the MDMX Application Specific Extension.
1406This tells the assembler to accept MDMX instructions.
1407@samp{-no-mdmx} turns off this option.
1408
2ef2b9ae
CF
1409@item -mdsp
1410@itemx -mno-dsp
8b082fb1
TS
1411Generate code for the DSP Release 1 Application Specific Extension.
1412This tells the assembler to accept DSP Release 1 instructions.
2ef2b9ae
CF
1413@samp{-mno-dsp} turns off this option.
1414
8b082fb1
TS
1415@item -mdspr2
1416@itemx -mno-dspr2
1417Generate code for the DSP Release 2 Application Specific Extension.
1418This option implies -mdsp.
1419This tells the assembler to accept DSP Release 2 instructions.
1420@samp{-mno-dspr2} turns off this option.
1421
56d438b1
CF
1422@item -mmsa
1423@itemx -mno-msa
1424Generate code for the MIPS SIMD Architecture Extension.
1425This tells the assembler to accept MSA instructions.
1426@samp{-mno-msa} turns off this option.
1427
7d64c587
AB
1428@item -mxpa
1429@itemx -mno-xpa
1430Generate code for the MIPS eXtended Physical Address (XPA) Extension.
1431This tells the assembler to accept XPA instructions.
1432@samp{-mno-xpa} turns off this option.
1433
ef2e4d86
CF
1434@item -mmt
1435@itemx -mno-mt
1436Generate code for the MT Application Specific Extension.
1437This tells the assembler to accept MT instructions.
1438@samp{-mno-mt} turns off this option.
1439
dec0624d
MR
1440@item -mmcu
1441@itemx -mno-mcu
1442Generate code for the MCU Application Specific Extension.
1443This tells the assembler to accept MCU instructions.
1444@samp{-mno-mcu} turns off this option.
1445
833794fc
MR
1446@item -minsn32
1447@itemx -mno-insn32
1448Only use 32-bit instruction encodings when generating code for the
1449microMIPS processor. This option inhibits the use of any 16-bit
1450instructions. This is equivalent to putting @code{.set insn32} at
1451the start of the assembly file. @samp{-mno-insn32} turns off this
1452option. This is equivalent to putting @code{.set noinsn32} at the
1453start of the assembly file. By default @samp{-mno-insn32} is
1454selected, allowing all instructions to be used.
1455
437ee9d5
TS
1456@item --construct-floats
1457@itemx --no-construct-floats
1458The @samp{--no-construct-floats} option disables the construction of
1459double width floating point constants by loading the two halves of the
1460value into the two single width floating point registers that make up
1461the double width register. By default @samp{--construct-floats} is
1462selected, allowing construction of these floating point constants.
252b5132 1463
3bf0dbfb
MR
1464@item --relax-branch
1465@itemx --no-relax-branch
1466The @samp{--relax-branch} option enables the relaxation of out-of-range
1467branches. By default @samp{--no-relax-branch} is selected, causing any
1468out-of-range branches to produce an error.
1469
ba92f887
MR
1470@item -mnan=@var{encoding}
1471Select between the IEEE 754-2008 (@option{-mnan=2008}) or the legacy
1472(@option{-mnan=legacy}) NaN encoding format. The latter is the default.
1473
252b5132
RH
1474@cindex emulation
1475@item --emulation=@var{name}
e8044f35
RS
1476This option was formerly used to switch between ELF and ECOFF output
1477on targets like IRIX 5 that supported both. MIPS ECOFF support was
1478removed in GAS 2.24, so the option now serves little purpose.
1479It is retained for backwards compatibility.
1480
1481The available configuration names are: @samp{mipself}, @samp{mipslelf} and
1482@samp{mipsbelf}. Choosing @samp{mipself} now has no effect, since the output
1483is always ELF. @samp{mipslelf} and @samp{mipsbelf} select little- and
1484big-endian output respectively, but @samp{-EL} and @samp{-EB} are now the
1485preferred options instead.
252b5132
RH
1486
1487@item -nocpp
a4fb0134 1488@command{@value{AS}} ignores this option. It is accepted for compatibility with
252b5132
RH
1489the native tools.
1490
252b5132
RH
1491@item --trap
1492@itemx --no-trap
1493@itemx --break
1494@itemx --no-break
1495Control how to deal with multiplication overflow and division by zero.
1496@samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception
1497(and only work for Instruction Set Architecture level 2 and higher);
1498@samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a
1499break exception.
63486801
L
1500
1501@item -n
a4fb0134 1502When this option is used, @command{@value{AS}} will issue a warning every
63486801 1503time it generates a nop instruction from a macro.
252b5132
RH
1504@end table
1505@end ifset
1506
1507@ifset MCORE
1508The following options are available when @value{AS} is configured for
1509an MCore processor.
1510
a4fb0134 1511@table @gcctabopt
252b5132
RH
1512@item -jsri2bsr
1513@itemx -nojsri2bsr
1514Enable or disable the JSRI to BSR transformation. By default this is enabled.
1515The command line option @samp{-nojsri2bsr} can be used to disable it.
1516
1517@item -sifilter
1518@itemx -nosifilter
1519Enable or disable the silicon filter behaviour. By default this is disabled.
a349d9dd 1520The default can be overridden by the @samp{-sifilter} command line option.
252b5132
RH
1521
1522@item -relax
1523Alter jump instructions for long displacements.
1524
ec694b89
NC
1525@item -mcpu=[210|340]
1526Select the cpu type on the target hardware. This controls which instructions
1527can be assembled.
1528
1529@item -EB
1530Assemble for a big endian target.
1531
1532@item -EL
1533Assemble for a little endian target.
252b5132
RH
1534
1535@end table
1536@end ifset
a3c62988 1537@c man end
252b5132 1538
a3c62988
NC
1539@ifset METAG
1540
1541@ifclear man
1542@xref{Meta Options}, for the options available when @value{AS} is configured
1543for a Meta processor.
1544@end ifclear
1545
1546@ifset man
1547@c man begin OPTIONS
1548The following options are available when @value{AS} is configured for a
1549Meta processor.
1550@c man end
1551@c man begin INCLUDE
1552@include c-metag.texi
1553@c ended inside the included file
1554@end ifset
1555
1556@end ifset
1557
1558@c man begin OPTIONS
3c3bdf30
NC
1559@ifset MMIX
1560See the info pages for documentation of the MMIX-specific options.
1561@end ifset
1562
35c08157
KLC
1563@ifset NDS32
1564
1565@ifclear man
1566@xref{NDS32 Options}, for the options available when @value{AS} is configured
1567for a NDS32 processor.
1568@end ifclear
1569@c ended inside the included file
1570@end ifset
1571
1572@ifset man
1573@c man begin OPTIONS
1574The following options are available when @value{AS} is configured for a
1575NDS32 processor.
1576@c man end
1577@c man begin INCLUDE
1578@include c-nds32.texi
1579@c ended inside the included file
1580@end ifset
1581
635fb38d 1582@c man end
b8b738ac
AM
1583@ifset PPC
1584
1585@ifclear man
1586@xref{PowerPC-Opts}, for the options available when @value{AS} is configured
1587for a PowerPC processor.
1588@end ifclear
1589
1590@ifset man
1591@c man begin OPTIONS
1592The following options are available when @value{AS} is configured for a
1593PowerPC processor.
1594@c man end
1595@c man begin INCLUDE
1596@include c-ppc.texi
1597@c ended inside the included file
1598@end ifset
1599
1600@end ifset
1601
635fb38d 1602@c man begin OPTIONS
046d31c2
NC
1603@ifset RX
1604See the info pages for documentation of the RX-specific options.
1605@end ifset
1606
11c19e16
MS
1607@ifset S390
1608The following options are available when @value{AS} is configured for the s390
1609processor family.
1610
1611@table @gcctabopt
1612@item -m31
1613@itemx -m64
1614Select the word size, either 31/32 bits or 64 bits.
1615@item -mesa
1616@item -mzarch
1617Select the architecture mode, either the Enterprise System
1618Architecture (esa) or the z/Architecture mode (zarch).
1619@item -march=@var{processor}
1620Specify which s390 processor variant is the target, @samp{g6}, @samp{g6},
cfc72779 1621@samp{z900}, @samp{z990}, @samp{z9-109}, @samp{z9-ec}, @samp{z10},
1e2e8c52 1622@samp{z196}, @samp{zEC12}, or @samp{z13}.
11c19e16
MS
1623@item -mregnames
1624@itemx -mno-regnames
1625Allow or disallow symbolic names for registers.
1626@item -mwarn-areg-zero
1627Warn whenever the operand for a base or index register has been specified
1628but evaluates to zero.
1629@end table
1630@end ifset
2a633939 1631@c man end
11c19e16 1632
40b36596 1633@ifset TIC6X
2a633939
JM
1634
1635@ifclear man
1636@xref{TIC6X Options}, for the options available when @value{AS} is configured
1637for a TMS320C6000 processor.
1638@end ifclear
1639
1640@ifset man
1641@c man begin OPTIONS
40b36596
JM
1642The following options are available when @value{AS} is configured for a
1643TMS320C6000 processor.
2a633939
JM
1644@c man end
1645@c man begin INCLUDE
1646@include c-tic6x.texi
1647@c ended inside the included file
1648@end ifset
40b36596
JM
1649
1650@end ifset
1651
aa137e4d
NC
1652@ifset TILEGX
1653
1654@ifclear man
1655@xref{TILE-Gx Options}, for the options available when @value{AS} is configured
1656for a TILE-Gx processor.
1657@end ifclear
1658
1659@ifset man
1660@c man begin OPTIONS
1661The following options are available when @value{AS} is configured for a TILE-Gx
1662processor.
1663@c man end
1664@c man begin INCLUDE
1665@include c-tilegx.texi
1666@c ended inside the included file
1667@end ifset
1668
1669@end ifset
1670
b6605ddd
EB
1671@ifset VISIUM
1672
1673@ifclear man
1674@xref{Visium Options}, for the options available when @value{AS} is configured
1675for a Visium processor.
1676@end ifclear
1677
1678@ifset man
1679@c man begin OPTIONS
1680The following option is available when @value{AS} is configured for a Visium
1681processor.
1682@c man end
1683@c man begin INCLUDE
1684@include c-visium.texi
1685@c ended inside the included file
1686@end ifset
1687
1688@end ifset
1689
e0001a05 1690@ifset XTENSA
e0001a05 1691
2d8b84ae
SA
1692@ifclear man
1693@xref{Xtensa Options}, for the options available when @value{AS} is configured
1694for an Xtensa processor.
1695@end ifclear
1696
1697@ifset man
1698@c man begin OPTIONS
1699The following options are available when @value{AS} is configured for an
1700Xtensa processor.
1701@c man end
1702@c man begin INCLUDE
1703@include c-xtensa.texi
1704@c ended inside the included file
e0001a05
NC
1705@end ifset
1706
2d8b84ae
SA
1707@end ifset
1708
1709@c man begin OPTIONS
1710
3c9b82ba
NC
1711@ifset Z80
1712The following options are available when @value{AS} is configured for
1713a Z80 family processor.
1714@table @gcctabopt
1715@item -z80
1716Assemble for Z80 processor.
1717@item -r800
1718Assemble for R800 processor.
01642c12 1719@item -ignore-undocumented-instructions
3c9b82ba
NC
1720@itemx -Wnud
1721Assemble undocumented Z80 instructions that also work on R800 without warning.
01642c12 1722@item -ignore-unportable-instructions
3c9b82ba
NC
1723@itemx -Wnup
1724Assemble all undocumented Z80 instructions without warning.
01642c12 1725@item -warn-undocumented-instructions
3c9b82ba
NC
1726@itemx -Wud
1727Issue a warning for undocumented Z80 instructions that also work on R800.
01642c12 1728@item -warn-unportable-instructions
3c9b82ba 1729@itemx -Wup
01642c12
RM
1730Issue a warning for undocumented Z80 instructions that do not work on R800.
1731@item -forbid-undocumented-instructions
3c9b82ba
NC
1732@itemx -Fud
1733Treat all undocumented instructions as errors.
01642c12 1734@item -forbid-unportable-instructions
3c9b82ba 1735@itemx -Fup
b45619c0 1736Treat undocumented Z80 instructions that do not work on R800 as errors.
3c9b82ba
NC
1737@end table
1738@end ifset
1739
0285c67d
NC
1740@c man end
1741
252b5132
RH
1742@menu
1743* Manual:: Structure of this Manual
1744* GNU Assembler:: The GNU Assembler
1745* Object Formats:: Object File Formats
1746* Command Line:: Command Line
1747* Input Files:: Input Files
1748* Object:: Output (Object) File
1749* Errors:: Error and Warning Messages
1750@end menu
1751
1752@node Manual
1753@section Structure of this Manual
1754
1755@cindex manual, structure and purpose
1756This manual is intended to describe what you need to know to use
a4fb0134 1757@sc{gnu} @command{@value{AS}}. We cover the syntax expected in source files, including
252b5132 1758notation for symbols, constants, and expressions; the directives that
a4fb0134 1759@command{@value{AS}} understands; and of course how to invoke @command{@value{AS}}.
252b5132
RH
1760
1761@ifclear GENERIC
1762We also cover special features in the @value{TARGET}
a4fb0134 1763configuration of @command{@value{AS}}, including assembler directives.
252b5132
RH
1764@end ifclear
1765@ifset GENERIC
1766This manual also describes some of the machine-dependent features of
1767various flavors of the assembler.
1768@end ifset
1769
1770@cindex machine instructions (not covered)
1771On the other hand, this manual is @emph{not} intended as an introduction
1772to programming in assembly language---let alone programming in general!
1773In a similar vein, we make no attempt to introduce the machine
1774architecture; we do @emph{not} describe the instruction set, standard
1775mnemonics, registers or addressing modes that are standard to a
1776particular architecture.
1777@ifset GENERIC
1778You may want to consult the manufacturer's
1779machine architecture manual for this information.
1780@end ifset
1781@ifclear GENERIC
1782@ifset H8/300
1783For information on the H8/300 machine instruction set, see @cite{H8/300
c2dcd04e
NC
1784Series Programming Manual}. For the H8/300H, see @cite{H8/300H Series
1785Programming Manual} (Renesas).
252b5132 1786@end ifset
252b5132 1787@ifset SH
ef230218
JR
1788For information on the Renesas (formerly Hitachi) / SuperH SH machine instruction set,
1789see @cite{SH-Microcomputer User's Manual} (Renesas) or
1790@cite{SH-4 32-bit CPU Core Architecture} (SuperH) and
1791@cite{SuperH (SH) 64-Bit RISC Series} (SuperH).
252b5132
RH
1792@end ifset
1793@ifset Z8000
1794For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
1795@end ifset
1796@end ifclear
1797
1798@c I think this is premature---doc@cygnus.com, 17jan1991
1799@ignore
1800Throughout this manual, we assume that you are running @dfn{GNU},
1801the portable operating system from the @dfn{Free Software
1802Foundation, Inc.}. This restricts our attention to certain kinds of
1803computer (in particular, the kinds of computers that @sc{gnu} can run on);
1804once this assumption is granted examples and definitions need less
1805qualification.
1806
a4fb0134 1807@command{@value{AS}} is part of a team of programs that turn a high-level
252b5132
RH
1808human-readable series of instructions into a low-level
1809computer-readable series of instructions. Different versions of
a4fb0134 1810@command{@value{AS}} are used for different kinds of computer.
252b5132
RH
1811@end ignore
1812
1813@c There used to be a section "Terminology" here, which defined
1814@c "contents", "byte", "word", and "long". Defining "word" to any
1815@c particular size is confusing when the .word directive may generate 16
1816@c bits on one machine and 32 bits on another; in general, for the user
1817@c version of this manual, none of these terms seem essential to define.
1818@c They were used very little even in the former draft of the manual;
1819@c this draft makes an effort to avoid them (except in names of
1820@c directives).
1821
1822@node GNU Assembler
1823@section The GNU Assembler
1824
0285c67d
NC
1825@c man begin DESCRIPTION
1826
a4fb0134 1827@sc{gnu} @command{as} is really a family of assemblers.
252b5132 1828@ifclear GENERIC
a4fb0134 1829This manual describes @command{@value{AS}}, a member of that family which is
252b5132
RH
1830configured for the @value{TARGET} architectures.
1831@end ifclear
1832If you use (or have used) the @sc{gnu} assembler on one architecture, you
1833should find a fairly similar environment when you use it on another
1834architecture. Each version has much in common with the others,
1835including object file formats, most assembler directives (often called
1836@dfn{pseudo-ops}) and assembler syntax.@refill
1837
1838@cindex purpose of @sc{gnu} assembler
a4fb0134 1839@command{@value{AS}} is primarily intended to assemble the output of the
252b5132 1840@sc{gnu} C compiler @code{@value{GCC}} for use by the linker
a4fb0134 1841@code{@value{LD}}. Nevertheless, we've tried to make @command{@value{AS}}
252b5132
RH
1842assemble correctly everything that other assemblers for the same
1843machine would assemble.
1844@ifset VAX
1845Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
1846@end ifset
1847@ifset M680X0
1848@c This remark should appear in generic version of manual; assumption
1849@c here is that generic version sets M680x0.
a4fb0134 1850This doesn't mean @command{@value{AS}} always uses the same syntax as another
252b5132
RH
1851assembler for the same architecture; for example, we know of several
1852incompatible versions of 680x0 assembly language syntax.
1853@end ifset
1854
0285c67d
NC
1855@c man end
1856
a4fb0134 1857Unlike older assemblers, @command{@value{AS}} is designed to assemble a source
252b5132
RH
1858program in one pass of the source file. This has a subtle impact on the
1859@kbd{.org} directive (@pxref{Org,,@code{.org}}).
1860
1861@node Object Formats
1862@section Object File Formats
1863
1864@cindex object file format
1865The @sc{gnu} assembler can be configured to produce several alternative
1866object file formats. For the most part, this does not affect how you
1867write assembly language programs; but directives for debugging symbols
1868are typically different in different file formats. @xref{Symbol
1869Attributes,,Symbol Attributes}.
1870@ifclear GENERIC
1871@ifclear MULTI-OBJ
c1253627 1872For the @value{TARGET} target, @command{@value{AS}} is configured to produce
252b5132
RH
1873@value{OBJ-NAME} format object files.
1874@end ifclear
1875@c The following should exhaust all configs that set MULTI-OBJ, ideally
252b5132 1876@ifset I960
a4fb0134 1877On the @value{TARGET}, @command{@value{AS}} can be configured to produce either
252b5132
RH
1878@code{b.out} or COFF format object files.
1879@end ifset
1880@ifset HPPA
a4fb0134 1881On the @value{TARGET}, @command{@value{AS}} can be configured to produce either
252b5132
RH
1882SOM or ELF format object files.
1883@end ifset
1884@end ifclear
1885
1886@node Command Line
1887@section Command Line
1888
1889@cindex command line conventions
0285c67d 1890
a4fb0134 1891After the program name @command{@value{AS}}, the command line may contain
252b5132
RH
1892options and file names. Options may appear in any order, and may be
1893before, after, or between file names. The order of file names is
1894significant.
1895
1896@cindex standard input, as input file
1897@kindex --
1898@file{--} (two hyphens) by itself names the standard input file
a4fb0134 1899explicitly, as one of the files for @command{@value{AS}} to assemble.
252b5132
RH
1900
1901@cindex options, command line
1902Except for @samp{--} any command line argument that begins with a
1903hyphen (@samp{-}) is an option. Each option changes the behavior of
a4fb0134 1904@command{@value{AS}}. No option changes the way another option works. An
252b5132
RH
1905option is a @samp{-} followed by one or more letters; the case of
1906the letter is important. All options are optional.
1907
1908Some options expect exactly one file name to follow them. The file
1909name may either immediately follow the option's letter (compatible
1910with older assemblers) or it may be the next command argument (@sc{gnu}
1911standard). These two command lines are equivalent:
1912
1913@smallexample
1914@value{AS} -o my-object-file.o mumble.s
1915@value{AS} -omy-object-file.o mumble.s
1916@end smallexample
1917
1918@node Input Files
1919@section Input Files
1920
1921@cindex input
1922@cindex source program
1923@cindex files, input
1924We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
a4fb0134 1925describe the program input to one run of @command{@value{AS}}. The program may
252b5132
RH
1926be in one or more files; how the source is partitioned into files
1927doesn't change the meaning of the source.
1928
1929@c I added "con" prefix to "catenation" just to prove I can overcome my
1930@c APL training... doc@cygnus.com
1931The source program is a concatenation of the text in all the files, in the
1932order specified.
1933
0285c67d 1934@c man begin DESCRIPTION
a4fb0134 1935Each time you run @command{@value{AS}} it assembles exactly one source
252b5132
RH
1936program. The source program is made up of one or more files.
1937(The standard input is also a file.)
1938
a4fb0134 1939You give @command{@value{AS}} a command line that has zero or more input file
252b5132
RH
1940names. The input files are read (from left file name to right). A
1941command line argument (in any position) that has no special meaning
1942is taken to be an input file name.
1943
a4fb0134
SC
1944If you give @command{@value{AS}} no file names it attempts to read one input file
1945from the @command{@value{AS}} standard input, which is normally your terminal. You
1946may have to type @key{ctl-D} to tell @command{@value{AS}} there is no more program
252b5132
RH
1947to assemble.
1948
1949Use @samp{--} if you need to explicitly name the standard input file
1950in your command line.
1951
a4fb0134 1952If the source is empty, @command{@value{AS}} produces a small, empty object
252b5132
RH
1953file.
1954
0285c67d
NC
1955@c man end
1956
252b5132
RH
1957@subheading Filenames and Line-numbers
1958
1959@cindex input file linenumbers
1960@cindex line numbers, in input files
1961There are two ways of locating a line in the input file (or files) and
1962either may be used in reporting error messages. One way refers to a line
1963number in a physical file; the other refers to a line number in a
1964``logical'' file. @xref{Errors, ,Error and Warning Messages}.
1965
1966@dfn{Physical files} are those files named in the command line given
a4fb0134 1967to @command{@value{AS}}.
252b5132
RH
1968
1969@dfn{Logical files} are simply names declared explicitly by assembler
1970directives; they bear no relation to physical files. Logical file names help
a4fb0134
SC
1971error messages reflect the original source file, when @command{@value{AS}} source
1972is itself synthesized from other files. @command{@value{AS}} understands the
252b5132
RH
1973@samp{#} directives emitted by the @code{@value{GCC}} preprocessor. See also
1974@ref{File,,@code{.file}}.
1975
1976@node Object
1977@section Output (Object) File
1978
1979@cindex object file
1980@cindex output file
1981@kindex a.out
1982@kindex .o
a4fb0134 1983Every time you run @command{@value{AS}} it produces an output file, which is
252b5132
RH
1984your assembly language program translated into numbers. This file
1985is the object file. Its default name is
1986@ifclear BOUT
1987@code{a.out}.
1988@end ifclear
1989@ifset BOUT
1990@ifset GENERIC
01642c12 1991@code{a.out}, or
252b5132 1992@end ifset
a4fb0134 1993@code{b.out} when @command{@value{AS}} is configured for the Intel 80960.
252b5132 1994@end ifset
a4fb0134 1995You can give it another name by using the @option{-o} option. Conventionally,
252b5132
RH
1996object file names end with @file{.o}. The default name is used for historical
1997reasons: older assemblers were capable of assembling self-contained programs
1998directly into a runnable program. (For some formats, this isn't currently
1999possible, but it can be done for the @code{a.out} format.)
2000
2001@cindex linker
2002@kindex ld
2003The object file is meant for input to the linker @code{@value{LD}}. It contains
2004assembled program code, information to help @code{@value{LD}} integrate
2005the assembled program into a runnable file, and (optionally) symbolic
2006information for the debugger.
2007
2008@c link above to some info file(s) like the description of a.out.
2009@c don't forget to describe @sc{gnu} info as well as Unix lossage.
2010
2011@node Errors
2012@section Error and Warning Messages
2013
0285c67d
NC
2014@c man begin DESCRIPTION
2015
a349d9dd 2016@cindex error messages
252b5132
RH
2017@cindex warning messages
2018@cindex messages from assembler
a4fb0134 2019@command{@value{AS}} may write warnings and error messages to the standard error
252b5132 2020file (usually your terminal). This should not happen when a compiler
a4fb0134
SC
2021runs @command{@value{AS}} automatically. Warnings report an assumption made so
2022that @command{@value{AS}} could keep assembling a flawed program; errors report a
252b5132
RH
2023grave problem that stops the assembly.
2024
0285c67d
NC
2025@c man end
2026
252b5132
RH
2027@cindex format of warning messages
2028Warning messages have the format
2029
2030@smallexample
2031file_name:@b{NNN}:Warning Message Text
2032@end smallexample
2033
2034@noindent
2035@cindex line numbers, in warnings/errors
2036(where @b{NNN} is a line number). If a logical file name has been given
2037(@pxref{File,,@code{.file}}) it is used for the filename, otherwise the name of
2038the current input file is used. If a logical line number was given
2039@ifset GENERIC
2040(@pxref{Line,,@code{.line}})
2041@end ifset
252b5132
RH
2042then it is used to calculate the number printed,
2043otherwise the actual line in the current source file is printed. The
2044message text is intended to be self explanatory (in the grand Unix
2045tradition).
2046
2047@cindex format of error messages
2048Error messages have the format
2049@smallexample
2050file_name:@b{NNN}:FATAL:Error Message Text
2051@end smallexample
2052The file name and line number are derived as for warning
2053messages. The actual message text may be rather less explanatory
2054because many of them aren't supposed to happen.
2055
2056@node Invoking
2057@chapter Command-Line Options
2058
2059@cindex options, all versions of assembler
2060This chapter describes command-line options available in @emph{all}
96e9638b
BW
2061versions of the @sc{gnu} assembler; see @ref{Machine Dependencies},
2062for options specific
252b5132 2063@ifclear GENERIC
c1253627 2064to the @value{TARGET} target.
252b5132
RH
2065@end ifclear
2066@ifset GENERIC
2067to particular machine architectures.
2068@end ifset
2069
0285c67d
NC
2070@c man begin DESCRIPTION
2071
c1253627 2072If you are invoking @command{@value{AS}} via the @sc{gnu} C compiler,
252b5132
RH
2073you can use the @samp{-Wa} option to pass arguments through to the assembler.
2074The assembler arguments must be separated from each other (and the @samp{-Wa})
2075by commas. For example:
2076
2077@smallexample
2078gcc -c -g -O -Wa,-alh,-L file.c
2079@end smallexample
2080
2081@noindent
2082This passes two options to the assembler: @samp{-alh} (emit a listing to
5f5e16be 2083standard output with high-level and assembly source) and @samp{-L} (retain
252b5132
RH
2084local symbols in the symbol table).
2085
2086Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
2087command-line options are automatically passed to the assembler by the compiler.
2088(You can call the @sc{gnu} compiler driver with the @samp{-v} option to see
2089precisely what options it passes to each compilation pass, including the
2090assembler.)
2091
0285c67d
NC
2092@c man end
2093
252b5132 2094@menu
83f10cb2 2095* a:: -a[cdghlns] enable listings
caa32fe5 2096* alternate:: --alternate enable alternate macro syntax
252b5132
RH
2097* D:: -D for compatibility
2098* f:: -f to work faster
2099* I:: -I for .include search path
2100@ifclear DIFF-TBL-KLUGE
2101* K:: -K for compatibility
2102@end ifclear
2103@ifset DIFF-TBL-KLUGE
2104* K:: -K for difference tables
2105@end ifset
2106
ba83aca1 2107* L:: -L to retain local symbols
c3a27914 2108* listing:: --listing-XXX to configure listing output
252b5132
RH
2109* M:: -M or --mri to assemble in MRI compatibility mode
2110* MD:: --MD for dependency tracking
2111* o:: -o to name the object file
2112* R:: -R to join data and text sections
2113* statistics:: --statistics to see statistics about assembly
2114* traditional-format:: --traditional-format for compatible output
2115* v:: -v to announce version
2bdd6cf5 2116* W:: -W, --no-warn, --warn, --fatal-warnings to control warnings
252b5132
RH
2117* Z:: -Z to make object file even after errors
2118@end menu
2119
2120@node a
83f10cb2 2121@section Enable Listings: @option{-a[cdghlns]}
252b5132
RH
2122
2123@kindex -a
2124@kindex -ac
2125@kindex -ad
83f10cb2 2126@kindex -ag
252b5132
RH
2127@kindex -ah
2128@kindex -al
2129@kindex -an
2130@kindex -as
2131@cindex listings, enabling
2132@cindex assembly listings, enabling
2133
2134These options enable listing output from the assembler. By itself,
2135@samp{-a} requests high-level, assembly, and symbols listing.
2136You can use other letters to select specific options for the list:
2137@samp{-ah} requests a high-level language listing,
2138@samp{-al} requests an output-program assembly listing, and
2139@samp{-as} requests a symbol table listing.
2140High-level listings require that a compiler debugging option like
2141@samp{-g} be used, and that assembly listings (@samp{-al}) be requested
2142also.
2143
83f10cb2
NC
2144Use the @samp{-ag} option to print a first section with general assembly
2145information, like @value{AS} version, switches passed, or time stamp.
2146
252b5132
RH
2147Use the @samp{-ac} option to omit false conditionals from a listing. Any lines
2148which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any
2149other conditional), or a true @code{.if} followed by an @code{.else}, will be
2150omitted from the listing.
2151
2152Use the @samp{-ad} option to omit debugging directives from the
2153listing.
2154
2155Once you have specified one of these options, you can further control
2156listing output and its appearance using the directives @code{.list},
2157@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
2158@code{.sbttl}.
2159The @samp{-an} option turns off all forms processing.
2160If you do not request listing output with one of the @samp{-a} options, the
2161listing-control directives have no effect.
2162
2163The letters after @samp{-a} may be combined into one option,
2164@emph{e.g.}, @samp{-aln}.
2165
96e9638b
BW
2166Note if the assembler source is coming from the standard input (e.g.,
2167because it
c3a27914
NC
2168is being created by @code{@value{GCC}} and the @samp{-pipe} command line switch
2169is being used) then the listing will not contain any comments or preprocessor
2170directives. This is because the listing code buffers input source lines from
2171stdin only after they have been preprocessed by the assembler. This reduces
2172memory usage and makes the code more efficient.
2173
caa32fe5
NC
2174@node alternate
2175@section @option{--alternate}
2176
2177@kindex --alternate
2178Begin in alternate macro mode, see @ref{Altmacro,,@code{.altmacro}}.
2179
252b5132 2180@node D
a4fb0134 2181@section @option{-D}
252b5132
RH
2182
2183@kindex -D
2184This option has no effect whatsoever, but it is accepted to make it more
2185likely that scripts written for other assemblers also work with
a4fb0134 2186@command{@value{AS}}.
252b5132
RH
2187
2188@node f
a4fb0134 2189@section Work Faster: @option{-f}
252b5132
RH
2190
2191@kindex -f
2192@cindex trusted compiler
a4fb0134 2193@cindex faster processing (@option{-f})
252b5132
RH
2194@samp{-f} should only be used when assembling programs written by a
2195(trusted) compiler. @samp{-f} stops the assembler from doing whitespace
2196and comment preprocessing on
2197the input file(s) before assembling them. @xref{Preprocessing,
2198,Preprocessing}.
2199
2200@quotation
2201@emph{Warning:} if you use @samp{-f} when the files actually need to be
a4fb0134 2202preprocessed (if they contain comments, for example), @command{@value{AS}} does
252b5132
RH
2203not work correctly.
2204@end quotation
2205
2206@node I
c1253627 2207@section @code{.include} Search Path: @option{-I} @var{path}
252b5132
RH
2208
2209@kindex -I @var{path}
2210@cindex paths for @code{.include}
2211@cindex search path for @code{.include}
2212@cindex @code{include} directive search path
2213Use this option to add a @var{path} to the list of directories
a4fb0134
SC
2214@command{@value{AS}} searches for files specified in @code{.include}
2215directives (@pxref{Include,,@code{.include}}). You may use @option{-I} as
252b5132 2216many times as necessary to include a variety of paths. The current
a4fb0134 2217working directory is always searched first; after that, @command{@value{AS}}
252b5132
RH
2218searches any @samp{-I} directories in the same order as they were
2219specified (left to right) on the command line.
2220
2221@node K
a4fb0134 2222@section Difference Tables: @option{-K}
252b5132
RH
2223
2224@kindex -K
2225@ifclear DIFF-TBL-KLUGE
2226On the @value{TARGET} family, this option is allowed, but has no effect. It is
2227permitted for compatibility with the @sc{gnu} assembler on other platforms,
2228where it can be used to warn when the assembler alters the machine code
2229generated for @samp{.word} directives in difference tables. The @value{TARGET}
2230family does not have the addressing limitations that sometimes lead to this
2231alteration on other platforms.
2232@end ifclear
2233
2234@ifset DIFF-TBL-KLUGE
2235@cindex difference tables, warning
2236@cindex warning for altered difference tables
96e9638b
BW
2237@command{@value{AS}} sometimes alters the code emitted for directives of the
2238form @samp{.word @var{sym1}-@var{sym2}}. @xref{Word,,@code{.word}}.
252b5132
RH
2239You can use the @samp{-K} option if you want a warning issued when this
2240is done.
2241@end ifset
2242
2243@node L
ba83aca1 2244@section Include Local Symbols: @option{-L}
252b5132
RH
2245
2246@kindex -L
ba83aca1
BW
2247@cindex local symbols, retaining in output
2248Symbols beginning with system-specific local label prefixes, typically
2249@samp{.L} for ELF systems or @samp{L} for traditional a.out systems, are
2250called @dfn{local symbols}. @xref{Symbol Names}. Normally you do not see
2251such symbols when debugging, because they are intended for the use of
2252programs (like compilers) that compose assembler programs, not for your
2253notice. Normally both @command{@value{AS}} and @code{@value{LD}} discard
2254such symbols, so you do not normally debug with them.
2255
2256This option tells @command{@value{AS}} to retain those local symbols
252b5132 2257in the object file. Usually if you do this you also tell the linker
ba83aca1 2258@code{@value{LD}} to preserve those symbols.
252b5132 2259
c3a27914 2260@node listing
a4fb0134 2261@section Configuring listing output: @option{--listing}
c3a27914
NC
2262
2263The listing feature of the assembler can be enabled via the command line switch
2264@samp{-a} (@pxref{a}). This feature combines the input source file(s) with a
2265hex dump of the corresponding locations in the output object file, and displays
96e9638b
BW
2266them as a listing file. The format of this listing can be controlled by
2267directives inside the assembler source (i.e., @code{.list} (@pxref{List}),
2268@code{.title} (@pxref{Title}), @code{.sbttl} (@pxref{Sbttl}),
2269@code{.psize} (@pxref{Psize}), and
2270@code{.eject} (@pxref{Eject}) and also by the following switches:
c3a27914 2271
a4fb0134 2272@table @gcctabopt
c3a27914
NC
2273@item --listing-lhs-width=@samp{number}
2274@kindex --listing-lhs-width
2275@cindex Width of first line disassembly output
2276Sets the maximum width, in words, of the first line of the hex byte dump. This
2277dump appears on the left hand side of the listing output.
2278
2279@item --listing-lhs-width2=@samp{number}
2280@kindex --listing-lhs-width2
2281@cindex Width of continuation lines of disassembly output
2282Sets the maximum width, in words, of any further lines of the hex byte dump for
8dfa0188 2283a given input source line. If this value is not specified, it defaults to being
c3a27914
NC
2284the same as the value specified for @samp{--listing-lhs-width}. If neither
2285switch is used the default is to one.
2286
2287@item --listing-rhs-width=@samp{number}
2288@kindex --listing-rhs-width
2289@cindex Width of source line output
2290Sets the maximum width, in characters, of the source line that is displayed
2291alongside the hex dump. The default value for this parameter is 100. The
2292source line is displayed on the right hand side of the listing output.
2293
2294@item --listing-cont-lines=@samp{number}
2295@kindex --listing-cont-lines
2296@cindex Maximum number of continuation lines
2297Sets the maximum number of continuation lines of hex dump that will be
2298displayed for a given single line of source input. The default value is 4.
2299@end table
2300
252b5132 2301@node M
a4fb0134 2302@section Assemble in MRI Compatibility Mode: @option{-M}
252b5132
RH
2303
2304@kindex -M
2305@cindex MRI compatibility mode
a4fb0134
SC
2306The @option{-M} or @option{--mri} option selects MRI compatibility mode. This
2307changes the syntax and pseudo-op handling of @command{@value{AS}} to make it
252b5132
RH
2308compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the
2309configured target) assembler from Microtec Research. The exact nature of the
2310MRI syntax will not be documented here; see the MRI manuals for more
2311information. Note in particular that the handling of macros and macro
2312arguments is somewhat different. The purpose of this option is to permit
a4fb0134 2313assembling existing MRI assembler code using @command{@value{AS}}.
252b5132
RH
2314
2315The MRI compatibility is not complete. Certain operations of the MRI assembler
2316depend upon its object file format, and can not be supported using other object
2317file formats. Supporting these would require enhancing each object file format
2318individually. These are:
2319
2320@itemize @bullet
2321@item global symbols in common section
2322
2323The m68k MRI assembler supports common sections which are merged by the linker.
a4fb0134 2324Other object file formats do not support this. @command{@value{AS}} handles
252b5132
RH
2325common sections by treating them as a single common symbol. It permits local
2326symbols to be defined within a common section, but it can not support global
2327symbols, since it has no way to describe them.
2328
2329@item complex relocations
2330
2331The MRI assemblers support relocations against a negated section address, and
2332relocations which combine the start addresses of two or more sections. These
2333are not support by other object file formats.
2334
2335@item @code{END} pseudo-op specifying start address
2336
2337The MRI @code{END} pseudo-op permits the specification of a start address.
2338This is not supported by other object file formats. The start address may
a4fb0134 2339instead be specified using the @option{-e} option to the linker, or in a linker
252b5132
RH
2340script.
2341
2342@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops
2343
2344The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module
2345name to the output file. This is not supported by other object file formats.
2346
2347@item @code{ORG} pseudo-op
2348
2349The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given
a4fb0134 2350address. This differs from the usual @command{@value{AS}} @code{.org} pseudo-op,
252b5132
RH
2351which changes the location within the current section. Absolute sections are
2352not supported by other object file formats. The address of a section may be
2353assigned within a linker script.
2354@end itemize
2355
2356There are some other features of the MRI assembler which are not supported by
a4fb0134 2357@command{@value{AS}}, typically either because they are difficult or because they
252b5132
RH
2358seem of little consequence. Some of these may be supported in future releases.
2359
2360@itemize @bullet
2361
2362@item EBCDIC strings
2363
2364EBCDIC strings are not supported.
2365
2366@item packed binary coded decimal
2367
2368Packed binary coded decimal is not supported. This means that the @code{DC.P}
2369and @code{DCB.P} pseudo-ops are not supported.
2370
2371@item @code{FEQU} pseudo-op
2372
2373The m68k @code{FEQU} pseudo-op is not supported.
2374
2375@item @code{NOOBJ} pseudo-op
2376
2377The m68k @code{NOOBJ} pseudo-op is not supported.
2378
2379@item @code{OPT} branch control options
2380
2381The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB},
a4fb0134 2382@code{BRL}, and @code{BRW}---are ignored. @command{@value{AS}} automatically
252b5132
RH
2383relaxes all branches, whether forward or backward, to an appropriate size, so
2384these options serve no purpose.
2385
2386@item @code{OPT} list control options
2387
2388The following m68k @code{OPT} list control options are ignored: @code{C},
2389@code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M},
2390@code{MEX}, @code{MC}, @code{MD}, @code{X}.
2391
2392@item other @code{OPT} options
2393
2394The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O},
2395@code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}.
2396
2397@item @code{OPT} @code{D} option is default
2398
2399The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler.
2400@code{OPT NOD} may be used to turn it off.
2401
2402@item @code{XREF} pseudo-op.
2403
2404The m68k @code{XREF} pseudo-op is ignored.
2405
2406@item @code{.debug} pseudo-op
2407
2408The i960 @code{.debug} pseudo-op is not supported.
2409
2410@item @code{.extended} pseudo-op
2411
2412The i960 @code{.extended} pseudo-op is not supported.
2413
2414@item @code{.list} pseudo-op.
2415
2416The various options of the i960 @code{.list} pseudo-op are not supported.
2417
2418@item @code{.optimize} pseudo-op
2419
2420The i960 @code{.optimize} pseudo-op is not supported.
2421
2422@item @code{.output} pseudo-op
2423
2424The i960 @code{.output} pseudo-op is not supported.
2425
2426@item @code{.setreal} pseudo-op
2427
2428The i960 @code{.setreal} pseudo-op is not supported.
2429
2430@end itemize
2431
2432@node MD
c1253627 2433@section Dependency Tracking: @option{--MD}
252b5132
RH
2434
2435@kindex --MD
2436@cindex dependency tracking
2437@cindex make rules
2438
a4fb0134 2439@command{@value{AS}} can generate a dependency file for the file it creates. This
252b5132
RH
2440file consists of a single rule suitable for @code{make} describing the
2441dependencies of the main source file.
2442
2443The rule is written to the file named in its argument.
2444
2445This feature is used in the automatic updating of makefiles.
2446
2447@node o
a4fb0134 2448@section Name the Object File: @option{-o}
252b5132
RH
2449
2450@kindex -o
2451@cindex naming object file
2452@cindex object file name
a4fb0134 2453There is always one object file output when you run @command{@value{AS}}. By
252b5132
RH
2454default it has the name
2455@ifset GENERIC
2456@ifset I960
2457@file{a.out} (or @file{b.out}, for Intel 960 targets only).
2458@end ifset
2459@ifclear I960
2460@file{a.out}.
2461@end ifclear
2462@end ifset
2463@ifclear GENERIC
2464@ifset I960
2465@file{b.out}.
2466@end ifset
2467@ifclear I960
2468@file{a.out}.
2469@end ifclear
2470@end ifclear
2471You use this option (which takes exactly one filename) to give the
2472object file a different name.
2473
a4fb0134 2474Whatever the object file is called, @command{@value{AS}} overwrites any
252b5132
RH
2475existing file of the same name.
2476
2477@node R
a4fb0134 2478@section Join Data and Text Sections: @option{-R}
252b5132
RH
2479
2480@kindex -R
2481@cindex data and text sections, joining
2482@cindex text and data sections, joining
2483@cindex joining text and data sections
2484@cindex merging text and data sections
a4fb0134 2485@option{-R} tells @command{@value{AS}} to write the object file as if all
252b5132
RH
2486data-section data lives in the text section. This is only done at
2487the very last moment: your binary data are the same, but data
2488section parts are relocated differently. The data section part of
2489your object file is zero bytes long because all its bytes are
2490appended to the text section. (@xref{Sections,,Sections and Relocation}.)
2491
a4fb0134 2492When you specify @option{-R} it would be possible to generate shorter
252b5132
RH
2493address displacements (because we do not have to cross between text and
2494data section). We refrain from doing this simply for compatibility with
a4fb0134 2495older versions of @command{@value{AS}}. In future, @option{-R} may work this way.
252b5132 2496
c1253627
NC
2497@ifset COFF-ELF
2498When @command{@value{AS}} is configured for COFF or ELF output,
252b5132
RH
2499this option is only useful if you use sections named @samp{.text} and
2500@samp{.data}.
2501@end ifset
2502
2503@ifset HPPA
a4fb0134
SC
2504@option{-R} is not supported for any of the HPPA targets. Using
2505@option{-R} generates a warning from @command{@value{AS}}.
252b5132
RH
2506@end ifset
2507
2508@node statistics
a4fb0134 2509@section Display Assembly Statistics: @option{--statistics}
252b5132
RH
2510
2511@kindex --statistics
2512@cindex statistics, about assembly
2513@cindex time, total for assembly
2514@cindex space used, maximum for assembly
2515Use @samp{--statistics} to display two statistics about the resources used by
a4fb0134 2516@command{@value{AS}}: the maximum amount of space allocated during the assembly
252b5132
RH
2517(in bytes), and the total execution time taken for the assembly (in @sc{cpu}
2518seconds).
2519
2520@node traditional-format
c1253627 2521@section Compatible Output: @option{--traditional-format}
252b5132
RH
2522
2523@kindex --traditional-format
a4fb0134 2524For some targets, the output of @command{@value{AS}} is different in some ways
252b5132 2525from the output of some existing assembler. This switch requests
a4fb0134 2526@command{@value{AS}} to use the traditional format instead.
252b5132
RH
2527
2528For example, it disables the exception frame optimizations which
a4fb0134 2529@command{@value{AS}} normally does by default on @code{@value{GCC}} output.
252b5132
RH
2530
2531@node v
a4fb0134 2532@section Announce Version: @option{-v}
252b5132
RH
2533
2534@kindex -v
2535@kindex -version
2536@cindex assembler version
2537@cindex version of assembler
2538You can find out what version of as is running by including the
2539option @samp{-v} (which you can also spell as @samp{-version}) on the
2540command line.
2541
2542@node W
a4fb0134 2543@section Control Warnings: @option{-W}, @option{--warn}, @option{--no-warn}, @option{--fatal-warnings}
252b5132 2544
a4fb0134 2545@command{@value{AS}} should never give a warning or error message when
252b5132 2546assembling compiler output. But programs written by people often
a4fb0134 2547cause @command{@value{AS}} to give a warning that a particular assumption was
252b5132 2548made. All such warnings are directed to the standard error file.
2bdd6cf5 2549
c1253627
NC
2550@kindex -W
2551@kindex --no-warn
2bdd6cf5
GK
2552@cindex suppressing warnings
2553@cindex warnings, suppressing
a4fb0134 2554If you use the @option{-W} and @option{--no-warn} options, no warnings are issued.
2bdd6cf5 2555This only affects the warning messages: it does not change any particular of
a4fb0134 2556how @command{@value{AS}} assembles your file. Errors, which stop the assembly,
2bdd6cf5
GK
2557are still reported.
2558
c1253627 2559@kindex --fatal-warnings
2bdd6cf5
GK
2560@cindex errors, caused by warnings
2561@cindex warnings, causing error
a4fb0134 2562If you use the @option{--fatal-warnings} option, @command{@value{AS}} considers
2bdd6cf5
GK
2563files that generate warnings to be in error.
2564
c1253627 2565@kindex --warn
2bdd6cf5 2566@cindex warnings, switching on
a4fb0134 2567You can switch these options off again by specifying @option{--warn}, which
2bdd6cf5 2568causes warnings to be output as usual.
252b5132
RH
2569
2570@node Z
a4fb0134 2571@section Generate Object File in Spite of Errors: @option{-Z}
252b5132
RH
2572@cindex object file, after errors
2573@cindex errors, continuing after
a4fb0134 2574After an error message, @command{@value{AS}} normally produces no output. If for
252b5132 2575some reason you are interested in object file output even after
a4fb0134
SC
2576@command{@value{AS}} gives an error message on your program, use the @samp{-Z}
2577option. If there are any errors, @command{@value{AS}} continues anyways, and
252b5132
RH
2578writes an object file after a final warning message of the form @samp{@var{n}
2579errors, @var{m} warnings, generating bad object file.}
2580
2581@node Syntax
2582@chapter Syntax
2583
2584@cindex machine-independent syntax
2585@cindex syntax, machine-independent
2586This chapter describes the machine-independent syntax allowed in a
a4fb0134 2587source file. @command{@value{AS}} syntax is similar to what many other
252b5132
RH
2588assemblers use; it is inspired by the BSD 4.2
2589@ifclear VAX
2590assembler.
2591@end ifclear
2592@ifset VAX
a4fb0134 2593assembler, except that @command{@value{AS}} does not assemble Vax bit-fields.
252b5132
RH
2594@end ifset
2595
2596@menu
7c31ae13 2597* Preprocessing:: Preprocessing
252b5132
RH
2598* Whitespace:: Whitespace
2599* Comments:: Comments
2600* Symbol Intro:: Symbols
2601* Statements:: Statements
2602* Constants:: Constants
2603@end menu
2604
2605@node Preprocessing
2606@section Preprocessing
2607
2608@cindex preprocessing
a4fb0134 2609The @command{@value{AS}} internal preprocessor:
252b5132
RH
2610@itemize @bullet
2611@cindex whitespace, removed by preprocessor
2612@item
2613adjusts and removes extra whitespace. It leaves one space or tab before
2614the keywords on a line, and turns any other whitespace on the line into
2615a single space.
2616
2617@cindex comments, removed by preprocessor
2618@item
2619removes all comments, replacing them with a single space, or an
2620appropriate number of newlines.
2621
2622@cindex constants, converted by preprocessor
2623@item
2624converts character constants into the appropriate numeric values.
2625@end itemize
2626
2627It does not do macro processing, include file handling, or
2628anything else you may get from your C compiler's preprocessor. You can
2629do include file processing with the @code{.include} directive
2630(@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver
c1253627 2631to get other ``CPP'' style preprocessing by giving the input file a
96e9638b 2632@samp{.S} suffix. @xref{Overall Options, ,Options Controlling the Kind of
252b5132
RH
2633Output, gcc.info, Using GNU CC}.
2634
2635Excess whitespace, comments, and character constants
2636cannot be used in the portions of the input text that are not
2637preprocessed.
2638
2639@cindex turning preprocessing on and off
2640@cindex preprocessing, turning on and off
2641@kindex #NO_APP
2642@kindex #APP
2643If the first line of an input file is @code{#NO_APP} or if you use the
2644@samp{-f} option, whitespace and comments are not removed from the input file.
2645Within an input file, you can ask for whitespace and comment removal in
2646specific portions of the by putting a line that says @code{#APP} before the
2647text that may contain whitespace or comments, and putting a line that says
2648@code{#NO_APP} after this text. This feature is mainly intend to support
2649@code{asm} statements in compilers whose output is otherwise free of comments
2650and whitespace.
2651
2652@node Whitespace
2653@section Whitespace
2654
2655@cindex whitespace
2656@dfn{Whitespace} is one or more blanks or tabs, in any order.
2657Whitespace is used to separate symbols, and to make programs neater for
2658people to read. Unless within character constants
2659(@pxref{Characters,,Character Constants}), any whitespace means the same
2660as exactly one space.
2661
2662@node Comments
2663@section Comments
2664
2665@cindex comments
a4fb0134 2666There are two ways of rendering comments to @command{@value{AS}}. In both
252b5132
RH
2667cases the comment is equivalent to one space.
2668
2669Anything from @samp{/*} through the next @samp{*/} is a comment.
2670This means you may not nest these comments.
2671
2672@smallexample
2673/*
2674 The only way to include a newline ('\n') in a comment
2675 is to use this sort of comment.
2676*/
2677
2678/* This sort of comment does not nest. */
2679@end smallexample
2680
2681@cindex line comment character
7c31ae13
NC
2682Anything from a @dfn{line comment} character up to the next newline is
2683considered a comment and is ignored. The line comment character is target
2684specific, and some targets multiple comment characters. Some targets also have
2685line comment characters that only work if they are the first character on a
2686line. Some targets use a sequence of two characters to introduce a line
2687comment. Some targets can also change their line comment characters depending
2688upon command line options that have been used. For more details see the
2689@emph{Syntax} section in the documentation for individual targets.
2690
2691If the line comment character is the hash sign (@samp{#}) then it still has the
2692special ability to enable and disable preprocessing (@pxref{Preprocessing}) and
2693to specify logical line numbers:
252b5132
RH
2694
2695@kindex #
2696@cindex lines starting with @code{#}
2697@cindex logical line numbers
2698To be compatible with past assemblers, lines that begin with @samp{#} have a
2699special interpretation. Following the @samp{#} should be an absolute
2700expression (@pxref{Expressions}): the logical line number of the @emph{next}
96e9638b 2701line. Then a string (@pxref{Strings, ,Strings}) is allowed: if present it is a
252b5132
RH
2702new logical file name. The rest of the line, if any, should be whitespace.
2703
2704If the first non-whitespace characters on the line are not numeric,
2705the line is ignored. (Just like a comment.)
2706
2707@smallexample
2708 # This is an ordinary comment.
2709# 42-6 "new_file_name" # New logical file name
2710 # This is logical line # 36.
2711@end smallexample
2712This feature is deprecated, and may disappear from future versions
a4fb0134 2713of @command{@value{AS}}.
252b5132
RH
2714
2715@node Symbol Intro
2716@section Symbols
2717
2718@cindex characters used in symbols
2719@ifclear SPECIAL-SYMS
2720A @dfn{symbol} is one or more characters chosen from the set of all
2721letters (both upper and lower case), digits and the three characters
2722@samp{_.$}.
2723@end ifclear
2724@ifset SPECIAL-SYMS
2725@ifclear GENERIC
2726@ifset H8
2727A @dfn{symbol} is one or more characters chosen from the set of all
2728letters (both upper and lower case), digits and the three characters
2729@samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in
2730symbol names.)
2731@end ifset
2732@end ifclear
2733@end ifset
2734@ifset GENERIC
2735On most machines, you can also use @code{$} in symbol names; exceptions
2736are noted in @ref{Machine Dependencies}.
2737@end ifset
2738No symbol may begin with a digit. Case is significant.
7bfd842d
NC
2739There is no length limit: all characters are significant. Multibyte characters
2740are supported. Symbols are delimited by characters not in that set, or by the
2741beginning of a file (since the source program must end with a newline, the end
2742of a file is not a possible symbol delimiter). @xref{Symbols}.
252b5132
RH
2743@cindex length of symbols
2744
2745@node Statements
2746@section Statements
2747
2748@cindex statements, structure of
2749@cindex line separator character
2750@cindex statement separator character
7c31ae13
NC
2751
2752A @dfn{statement} ends at a newline character (@samp{\n}) or a
2753@dfn{line separator character}. The line separator character is target
2754specific and described in the @emph{Syntax} section of each
2755target's documentation. Not all targets support a line separator character.
2756The newline or line separator character is considered to be part of the
2757preceding statement. Newlines and separators within character constants are an
252b5132 2758exception: they do not end statements.
252b5132
RH
2759
2760@cindex newline, required at file end
2761@cindex EOF, newline must precede
2762It is an error to end any statement with end-of-file: the last
2763character of any input file should be a newline.@refill
2764
2765An empty statement is allowed, and may include whitespace. It is ignored.
2766
2767@cindex instructions and directives
2768@cindex directives and instructions
2769@c "key symbol" is not used elsewhere in the document; seems pedantic to
2770@c @defn{} it in that case, as was done previously... doc@cygnus.com,
2771@c 13feb91.
2772A statement begins with zero or more labels, optionally followed by a
2773key symbol which determines what kind of statement it is. The key
2774symbol determines the syntax of the rest of the statement. If the
2775symbol begins with a dot @samp{.} then the statement is an assembler
2776directive: typically valid for any computer. If the symbol begins with
2777a letter the statement is an assembly language @dfn{instruction}: it
2778assembles into a machine language instruction.
2779@ifset GENERIC
a4fb0134 2780Different versions of @command{@value{AS}} for different computers
252b5132
RH
2781recognize different instructions. In fact, the same symbol may
2782represent a different instruction in a different computer's assembly
2783language.@refill
2784@end ifset
2785
2786@cindex @code{:} (label)
2787@cindex label (@code{:})
2788A label is a symbol immediately followed by a colon (@code{:}).
2789Whitespace before a label or after a colon is permitted, but you may not
2790have whitespace between a label's symbol and its colon. @xref{Labels}.
2791
2792@ifset HPPA
01642c12 2793For HPPA targets, labels need not be immediately followed by a colon, but
252b5132
RH
2794the definition of a label must begin in column zero. This also implies that
2795only one label may be defined on each line.
2796@end ifset
2797
2798@smallexample
2799label: .directive followed by something
2800another_label: # This is an empty statement.
2801 instruction operand_1, operand_2, @dots{}
2802@end smallexample
2803
2804@node Constants
2805@section Constants
2806
2807@cindex constants
2808A constant is a number, written so that its value is known by
2809inspection, without knowing any context. Like this:
2810@smallexample
2811@group
2812.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
2813.ascii "Ring the bell\7" # A string constant.
2814.octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
2815.float 0f-314159265358979323846264338327\
281695028841971.693993751E-40 # - pi, a flonum.
2817@end group
2818@end smallexample
2819
2820@menu
2821* Characters:: Character Constants
2822* Numbers:: Number Constants
2823@end menu
2824
2825@node Characters
2826@subsection Character Constants
2827
2828@cindex character constants
2829@cindex constants, character
2830There are two kinds of character constants. A @dfn{character} stands
2831for one character in one byte and its value may be used in
2832numeric expressions. String constants (properly called string
2833@emph{literals}) are potentially many bytes and their values may not be
2834used in arithmetic expressions.
2835
2836@menu
2837* Strings:: Strings
2838* Chars:: Characters
2839@end menu
2840
2841@node Strings
2842@subsubsection Strings
2843
2844@cindex string constants
2845@cindex constants, string
2846A @dfn{string} is written between double-quotes. It may contain
2847double-quotes or null characters. The way to get special characters
2848into a string is to @dfn{escape} these characters: precede them with
2849a backslash @samp{\} character. For example @samp{\\} represents
2850one backslash: the first @code{\} is an escape which tells
a4fb0134
SC
2851@command{@value{AS}} to interpret the second character literally as a backslash
2852(which prevents @command{@value{AS}} from recognizing the second @code{\} as an
252b5132
RH
2853escape character). The complete list of escapes follows.
2854
2855@cindex escape codes, character
2856@cindex character escape codes
2857@table @kbd
2858@c @item \a
2859@c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
2860@c
2861@cindex @code{\b} (backspace character)
2862@cindex backspace (@code{\b})
2863@item \b
2864Mnemonic for backspace; for ASCII this is octal code 010.
2865
2866@c @item \e
2867@c Mnemonic for EOText; for ASCII this is octal code 004.
2868@c
2869@cindex @code{\f} (formfeed character)
2870@cindex formfeed (@code{\f})
2871@item \f
2872Mnemonic for FormFeed; for ASCII this is octal code 014.
2873
2874@cindex @code{\n} (newline character)
2875@cindex newline (@code{\n})
2876@item \n
2877Mnemonic for newline; for ASCII this is octal code 012.
2878
2879@c @item \p
2880@c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
2881@c
2882@cindex @code{\r} (carriage return character)
2883@cindex carriage return (@code{\r})
2884@item \r
2885Mnemonic for carriage-Return; for ASCII this is octal code 015.
2886
2887@c @item \s
2888@c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
2889@c other assemblers.
2890@c
2891@cindex @code{\t} (tab)
2892@cindex tab (@code{\t})
2893@item \t
2894Mnemonic for horizontal Tab; for ASCII this is octal code 011.
2895
2896@c @item \v
2897@c Mnemonic for Vertical tab; for ASCII this is octal code 013.
2898@c @item \x @var{digit} @var{digit} @var{digit}
2899@c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
2900@c
2901@cindex @code{\@var{ddd}} (octal character code)
2902@cindex octal character code (@code{\@var{ddd}})
2903@item \ @var{digit} @var{digit} @var{digit}
2904An octal character code. The numeric code is 3 octal digits.
2905For compatibility with other Unix systems, 8 and 9 are accepted as digits:
2906for example, @code{\008} has the value 010, and @code{\009} the value 011.
2907
2908@cindex @code{\@var{xd...}} (hex character code)
2909@cindex hex character code (@code{\@var{xd...}})
2910@item \@code{x} @var{hex-digits...}
2911A hex character code. All trailing hex digits are combined. Either upper or
2912lower case @code{x} works.
2913
2914@cindex @code{\\} (@samp{\} character)
2915@cindex backslash (@code{\\})
2916@item \\
2917Represents one @samp{\} character.
2918
2919@c @item \'
2920@c Represents one @samp{'} (accent acute) character.
2921@c This is needed in single character literals
2922@c (@xref{Characters,,Character Constants}.) to represent
2923@c a @samp{'}.
2924@c
2925@cindex @code{\"} (doublequote character)
2926@cindex doublequote (@code{\"})
2927@item \"
2928Represents one @samp{"} character. Needed in strings to represent
2929this character, because an unescaped @samp{"} would end the string.
2930
2931@item \ @var{anything-else}
2932Any other character when escaped by @kbd{\} gives a warning, but
2933assembles as if the @samp{\} was not present. The idea is that if
2934you used an escape sequence you clearly didn't want the literal
a4fb0134
SC
2935interpretation of the following character. However @command{@value{AS}} has no
2936other interpretation, so @command{@value{AS}} knows it is giving you the wrong
252b5132
RH
2937code and warns you of the fact.
2938@end table
2939
2940Which characters are escapable, and what those escapes represent,
2941varies widely among assemblers. The current set is what we think
2942the BSD 4.2 assembler recognizes, and is a subset of what most C
2943compilers recognize. If you are in doubt, do not use an escape
2944sequence.
2945
2946@node Chars
2947@subsubsection Characters
2948
2949@cindex single character constant
2950@cindex character, single
2951@cindex constant, single character
2952A single character may be written as a single quote immediately
2953followed by that character. The same escapes apply to characters as
2954to strings. So if you want to write the character backslash, you
2955must write @kbd{'\\} where the first @code{\} escapes the second
2956@code{\}. As you can see, the quote is an acute accent, not a
2957grave accent. A newline
2958@ifclear GENERIC
2959@ifclear abnormal-separator
2960(or semicolon @samp{;})
2961@end ifclear
2962@ifset abnormal-separator
252b5132
RH
2963@ifset H8
2964(or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
7be1c489 2965Renesas SH)
252b5132
RH
2966@end ifset
2967@end ifset
2968@end ifclear
2969immediately following an acute accent is taken as a literal character
2970and does not count as the end of a statement. The value of a character
2971constant in a numeric expression is the machine's byte-wide code for
a4fb0134 2972that character. @command{@value{AS}} assumes your character code is ASCII:
252b5132
RH
2973@kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
2974
2975@node Numbers
2976@subsection Number Constants
2977
2978@cindex constants, number
2979@cindex number constants
a4fb0134 2980@command{@value{AS}} distinguishes three kinds of numbers according to how they
252b5132
RH
2981are stored in the target machine. @emph{Integers} are numbers that
2982would fit into an @code{int} in the C language. @emph{Bignums} are
2983integers, but they are stored in more than 32 bits. @emph{Flonums}
2984are floating point numbers, described below.
2985
2986@menu
2987* Integers:: Integers
2988* Bignums:: Bignums
2989* Flonums:: Flonums
2990@ifclear GENERIC
2991@ifset I960
2992* Bit Fields:: Bit Fields
2993@end ifset
2994@end ifclear
2995@end menu
2996
2997@node Integers
2998@subsubsection Integers
2999@cindex integers
3000@cindex constants, integer
3001
3002@cindex binary integers
3003@cindex integers, binary
3004A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
3005the binary digits @samp{01}.
3006
3007@cindex octal integers
3008@cindex integers, octal
3009An octal integer is @samp{0} followed by zero or more of the octal
3010digits (@samp{01234567}).
3011
3012@cindex decimal integers
3013@cindex integers, decimal
3014A decimal integer starts with a non-zero digit followed by zero or
3015more digits (@samp{0123456789}).
3016
3017@cindex hexadecimal integers
3018@cindex integers, hexadecimal
3019A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
3020more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
3021
3022Integers have the usual values. To denote a negative integer, use
3023the prefix operator @samp{-} discussed under expressions
3024(@pxref{Prefix Ops,,Prefix Operators}).
3025
3026@node Bignums
3027@subsubsection Bignums
3028
3029@cindex bignums
3030@cindex constants, bignum
3031A @dfn{bignum} has the same syntax and semantics as an integer
3032except that the number (or its negative) takes more than 32 bits to
3033represent in binary. The distinction is made because in some places
3034integers are permitted while bignums are not.
3035
3036@node Flonums
3037@subsubsection Flonums
3038@cindex flonums
3039@cindex floating point numbers
3040@cindex constants, floating point
3041
3042@cindex precision, floating point
3043A @dfn{flonum} represents a floating point number. The translation is
3044indirect: a decimal floating point number from the text is converted by
a4fb0134 3045@command{@value{AS}} to a generic binary floating point number of more than
252b5132
RH
3046sufficient precision. This generic floating point number is converted
3047to a particular computer's floating point format (or formats) by a
a4fb0134 3048portion of @command{@value{AS}} specialized to that computer.
252b5132
RH
3049
3050A flonum is written by writing (in order)
3051@itemize @bullet
3052@item
3053The digit @samp{0}.
3054@ifset HPPA
3055(@samp{0} is optional on the HPPA.)
3056@end ifset
3057
3058@item
a4fb0134 3059A letter, to tell @command{@value{AS}} the rest of the number is a flonum.
252b5132
RH
3060@ifset GENERIC
3061@kbd{e} is recommended. Case is not important.
3062@ignore
3063@c FIXME: verify if flonum syntax really this vague for most cases
3064(Any otherwise illegal letter works here, but that might be changed. Vax BSD
30654.2 assembler seems to allow any of @samp{defghDEFGH}.)
3066@end ignore
3067
7be1c489 3068On the H8/300, Renesas / SuperH SH,
252b5132
RH
3069and AMD 29K architectures, the letter must be
3070one of the letters @samp{DFPRSX} (in upper or lower case).
3071
3072On the ARC, the letter must be one of the letters @samp{DFRS}
3073(in upper or lower case).
3074
3075On the Intel 960 architecture, the letter must be
3076one of the letters @samp{DFT} (in upper or lower case).
3077
3078On the HPPA architecture, the letter must be @samp{E} (upper case only).
3079@end ifset
3080@ifclear GENERIC
252b5132
RH
3081@ifset ARC
3082One of the letters @samp{DFRS} (in upper or lower case).
3083@end ifset
3084@ifset H8
3085One of the letters @samp{DFPRSX} (in upper or lower case).
3086@end ifset
3087@ifset HPPA
3088The letter @samp{E} (upper case only).
3089@end ifset
3090@ifset I960
3091One of the letters @samp{DFT} (in upper or lower case).
3092@end ifset
3093@end ifclear
3094
3095@item
3096An optional sign: either @samp{+} or @samp{-}.
3097
3098@item
3099An optional @dfn{integer part}: zero or more decimal digits.
3100
3101@item
3102An optional @dfn{fractional part}: @samp{.} followed by zero
3103or more decimal digits.
3104
3105@item
3106An optional exponent, consisting of:
3107
3108@itemize @bullet
3109@item
3110An @samp{E} or @samp{e}.
3111@c I can't find a config where "EXP_CHARS" is other than 'eE', but in
3112@c principle this can perfectly well be different on different targets.
3113@item
3114Optional sign: either @samp{+} or @samp{-}.
3115@item
3116One or more decimal digits.
3117@end itemize
3118
3119@end itemize
3120
3121At least one of the integer part or the fractional part must be
3122present. The floating point number has the usual base-10 value.
3123
a4fb0134 3124@command{@value{AS}} does all processing using integers. Flonums are computed
252b5132 3125independently of any floating point hardware in the computer running
a4fb0134 3126@command{@value{AS}}.
252b5132
RH
3127
3128@ifclear GENERIC
3129@ifset I960
3130@c Bit fields are written as a general facility but are also controlled
3131@c by a conditional-compilation flag---which is as of now (21mar91)
3132@c turned on only by the i960 config of GAS.
3133@node Bit Fields
3134@subsubsection Bit Fields
3135
3136@cindex bit fields
3137@cindex constants, bit field
3138You can also define numeric constants as @dfn{bit fields}.
b45619c0 3139Specify two numbers separated by a colon---
252b5132
RH
3140@example
3141@var{mask}:@var{value}
3142@end example
3143@noindent
a4fb0134 3144@command{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
252b5132
RH
3145@var{value}.
3146
3147The resulting number is then packed
3148@ifset GENERIC
3149@c this conditional paren in case bit fields turned on elsewhere than 960
3150(in host-dependent byte order)
3151@end ifset
3152into a field whose width depends on which assembler directive has the
3153bit-field as its argument. Overflow (a result from the bitwise and
3154requiring more binary digits to represent) is not an error; instead,
3155more constants are generated, of the specified width, beginning with the
3156least significant digits.@refill
3157
3158The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
3159@code{.short}, and @code{.word} accept bit-field arguments.
3160@end ifset
3161@end ifclear
3162
3163@node Sections
3164@chapter Sections and Relocation
3165@cindex sections
3166@cindex relocation
3167
3168@menu
3169* Secs Background:: Background
3170* Ld Sections:: Linker Sections
3171* As Sections:: Assembler Internal Sections
3172* Sub-Sections:: Sub-Sections
3173* bss:: bss Section
3174@end menu
3175
3176@node Secs Background
3177@section Background
3178
3179Roughly, a section is a range of addresses, with no gaps; all data
3180``in'' those addresses is treated the same for some particular purpose.
3181For example there may be a ``read only'' section.
3182
3183@cindex linker, and assembler
3184@cindex assembler, and linker
3185The linker @code{@value{LD}} reads many object files (partial programs) and
a4fb0134 3186combines their contents to form a runnable program. When @command{@value{AS}}
252b5132
RH
3187emits an object file, the partial program is assumed to start at address 0.
3188@code{@value{LD}} assigns the final addresses for the partial program, so that
3189different partial programs do not overlap. This is actually an
a4fb0134 3190oversimplification, but it suffices to explain how @command{@value{AS}} uses
252b5132
RH
3191sections.
3192
3193@code{@value{LD}} moves blocks of bytes of your program to their run-time
3194addresses. These blocks slide to their run-time addresses as rigid
3195units; their length does not change and neither does the order of bytes
3196within them. Such a rigid unit is called a @emph{section}. Assigning
3197run-time addresses to sections is called @dfn{relocation}. It includes
3198the task of adjusting mentions of object-file addresses so they refer to
3199the proper run-time addresses.
3200@ifset H8
7be1c489 3201For the H8/300, and for the Renesas / SuperH SH,
a4fb0134 3202@command{@value{AS}} pads sections if needed to
252b5132
RH
3203ensure they end on a word (sixteen bit) boundary.
3204@end ifset
3205
3206@cindex standard assembler sections
a4fb0134 3207An object file written by @command{@value{AS}} has at least three sections, any
252b5132
RH
3208of which may be empty. These are named @dfn{text}, @dfn{data} and
3209@dfn{bss} sections.
3210
c1253627 3211@ifset COFF-ELF
252b5132 3212@ifset GENERIC
c1253627 3213When it generates COFF or ELF output,
252b5132 3214@end ifset
a4fb0134 3215@command{@value{AS}} can also generate whatever other named sections you specify
252b5132
RH
3216using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
3217If you do not use any directives that place output in the @samp{.text}
3218or @samp{.data} sections, these sections still exist, but are empty.
3219@end ifset
3220
3221@ifset HPPA
3222@ifset GENERIC
a4fb0134 3223When @command{@value{AS}} generates SOM or ELF output for the HPPA,
252b5132 3224@end ifset
a4fb0134 3225@command{@value{AS}} can also generate whatever other named sections you
252b5132
RH
3226specify using the @samp{.space} and @samp{.subspace} directives. See
3227@cite{HP9000 Series 800 Assembly Language Reference Manual}
3228(HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
3229assembler directives.
3230
3231@ifset SOM
a4fb0134 3232Additionally, @command{@value{AS}} uses different names for the standard
252b5132
RH
3233text, data, and bss sections when generating SOM output. Program text
3234is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
3235BSS into @samp{$BSS$}.
3236@end ifset
3237@end ifset
3238
3239Within the object file, the text section starts at address @code{0}, the
3240data section follows, and the bss section follows the data section.
3241
3242@ifset HPPA
3243When generating either SOM or ELF output files on the HPPA, the text
3244section starts at address @code{0}, the data section at address
3245@code{0x4000000}, and the bss section follows the data section.
3246@end ifset
3247
3248To let @code{@value{LD}} know which data changes when the sections are
a4fb0134 3249relocated, and how to change that data, @command{@value{AS}} also writes to the
252b5132
RH
3250object file details of the relocation needed. To perform relocation
3251@code{@value{LD}} must know, each time an address in the object
3252file is mentioned:
3253@itemize @bullet
3254@item
3255Where in the object file is the beginning of this reference to
3256an address?
3257@item
3258How long (in bytes) is this reference?
3259@item
3260Which section does the address refer to? What is the numeric value of
3261@display
3262(@var{address}) @minus{} (@var{start-address of section})?
3263@end display
3264@item
3265Is the reference to an address ``Program-Counter relative''?
3266@end itemize
3267
3268@cindex addresses, format of
3269@cindex section-relative addressing
a4fb0134 3270In fact, every address @command{@value{AS}} ever uses is expressed as
252b5132
RH
3271@display
3272(@var{section}) + (@var{offset into section})
3273@end display
3274@noindent
a4fb0134 3275Further, most expressions @command{@value{AS}} computes have this section-relative
252b5132
RH
3276nature.
3277@ifset SOM
3278(For some object formats, such as SOM for the HPPA, some expressions are
3279symbol-relative instead.)
3280@end ifset
3281
3282In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset
3283@var{N} into section @var{secname}.''
3284
3285Apart from text, data and bss sections you need to know about the
3286@dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
3287addresses in the absolute section remain unchanged. For example, address
3288@code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
3289@code{@value{LD}}. Although the linker never arranges two partial programs'
3290data sections with overlapping addresses after linking, @emph{by definition}
3291their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one
3292part of a program is always the same address when the program is running as
3293address @code{@{absolute@ 239@}} in any other part of the program.
3294
3295The idea of sections is extended to the @dfn{undefined} section. Any
3296address whose section is unknown at assembly time is by definition
3297rendered @{undefined @var{U}@}---where @var{U} is filled in later.
3298Since numbers are always defined, the only way to generate an undefined
3299address is to mention an undefined symbol. A reference to a named
3300common block would be such a symbol: its value is unknown at assembly
3301time so it has section @emph{undefined}.
3302
3303By analogy the word @emph{section} is used to describe groups of sections in
3304the linked program. @code{@value{LD}} puts all partial programs' text
3305sections in contiguous addresses in the linked program. It is
3306customary to refer to the @emph{text section} of a program, meaning all
3307the addresses of all partial programs' text sections. Likewise for
3308data and bss sections.
3309
3310Some sections are manipulated by @code{@value{LD}}; others are invented for
a4fb0134 3311use of @command{@value{AS}} and have no meaning except during assembly.
252b5132
RH
3312
3313@node Ld Sections
3314@section Linker Sections
3315@code{@value{LD}} deals with just four kinds of sections, summarized below.
3316
3317@table @strong
3318
c1253627 3319@ifset COFF-ELF
252b5132
RH
3320@cindex named sections
3321@cindex sections, named
3322@item named sections
3323@end ifset
3324@ifset aout-bout
3325@cindex text section
3326@cindex data section
3327@itemx text section
3328@itemx data section
3329@end ifset
a4fb0134 3330These sections hold your program. @command{@value{AS}} and @code{@value{LD}} treat them as
252b5132 3331separate but equal sections. Anything you can say of one section is
c1253627
NC
3332true of another.
3333@c @ifset aout-bout
252b5132
RH
3334When the program is running, however, it is
3335customary for the text section to be unalterable. The
3336text section is often shared among processes: it contains
3337instructions, constants and the like. The data section of a running
3338program is usually alterable: for example, C variables would be stored
3339in the data section.
c1253627 3340@c @end ifset
252b5132
RH
3341
3342@cindex bss section
3343@item bss section
3344This section contains zeroed bytes when your program begins running. It
a349d9dd 3345is used to hold uninitialized variables or common storage. The length of
252b5132
RH
3346each partial program's bss section is important, but because it starts
3347out containing zeroed bytes there is no need to store explicit zero
3348bytes in the object file. The bss section was invented to eliminate
3349those explicit zeros from object files.
3350
3351@cindex absolute section
3352@item absolute section
3353Address 0 of this section is always ``relocated'' to runtime address 0.
3354This is useful if you want to refer to an address that @code{@value{LD}} must
3355not change when relocating. In this sense we speak of absolute
3356addresses being ``unrelocatable'': they do not change during relocation.
3357
3358@cindex undefined section
3359@item undefined section
3360This ``section'' is a catch-all for address references to objects not in
3361the preceding sections.
3362@c FIXME: ref to some other doc on obj-file formats could go here.
3363@end table
3364
3365@cindex relocation example
3366An idealized example of three relocatable sections follows.
c1253627 3367@ifset COFF-ELF
252b5132
RH
3368The example uses the traditional section names @samp{.text} and @samp{.data}.
3369@end ifset
3370Memory addresses are on the horizontal axis.
3371
3372@c TEXI2ROFF-KILL
c1253627 3373@ifnottex
252b5132
RH
3374@c END TEXI2ROFF-KILL
3375@smallexample
3376 +-----+----+--+
3377partial program # 1: |ttttt|dddd|00|
3378 +-----+----+--+
3379
3380 text data bss
3381 seg. seg. seg.
3382
3383 +---+---+---+
3384partial program # 2: |TTT|DDD|000|
3385 +---+---+---+
3386
3387 +--+---+-----+--+----+---+-----+~~
3388linked program: | |TTT|ttttt| |dddd|DDD|00000|
3389 +--+---+-----+--+----+---+-----+~~
3390
3391 addresses: 0 @dots{}
3392@end smallexample
3393@c TEXI2ROFF-KILL
c1253627 3394@end ifnottex
252b5132
RH
3395@need 5000
3396@tex
c1253627 3397\bigskip
252b5132
RH
3398\line{\it Partial program \#1: \hfil}
3399\line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
3400\line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
3401
3402\line{\it Partial program \#2: \hfil}
3403\line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
3404\line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
3405
3406\line{\it linked program: \hfil}
3407\line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
3408\line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
3409ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
3410DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
3411
3412\line{\it addresses: \hfil}
3413\line{0\dots\hfil}
3414
3415@end tex
3416@c END TEXI2ROFF-KILL
3417
3418@node As Sections
3419@section Assembler Internal Sections
3420
3421@cindex internal assembler sections
3422@cindex sections in messages, internal
a4fb0134 3423These sections are meant only for the internal use of @command{@value{AS}}. They
252b5132 3424have no meaning at run-time. You do not really need to know about these
a4fb0134 3425sections for most purposes; but they can be mentioned in @command{@value{AS}}
252b5132 3426warning messages, so it might be helpful to have an idea of their
a4fb0134 3427meanings to @command{@value{AS}}. These sections are used to permit the
252b5132
RH
3428value of every expression in your assembly language program to be a
3429section-relative address.
3430
3431@table @b
3432@cindex assembler internal logic error
3433@item ASSEMBLER-INTERNAL-LOGIC-ERROR!
3434An internal assembler logic error has been found. This means there is a
3435bug in the assembler.
3436
3437@cindex expr (internal section)
3438@item expr section
3439The assembler stores complex expression internally as combinations of
3440symbols. When it needs to represent an expression as a symbol, it puts
3441it in the expr section.
3442@c FIXME item debug
3443@c FIXME item transfer[t] vector preload
3444@c FIXME item transfer[t] vector postload
3445@c FIXME item register
3446@end table
3447
3448@node Sub-Sections
3449@section Sub-Sections
3450
3451@cindex numbered subsections
3452@cindex grouping data
3453@ifset aout-bout
3454Assembled bytes
c1253627 3455@ifset COFF-ELF
252b5132
RH
3456conventionally
3457@end ifset
3458fall into two sections: text and data.
3459@end ifset
3460You may have separate groups of
3461@ifset GENERIC
3462data in named sections
3463@end ifset
3464@ifclear GENERIC
3465@ifclear aout-bout
3466data in named sections
3467@end ifclear
3468@ifset aout-bout
3469text or data
3470@end ifset
3471@end ifclear
3472that you want to end up near to each other in the object file, even though they
a4fb0134 3473are not contiguous in the assembler source. @command{@value{AS}} allows you to
252b5132
RH
3474use @dfn{subsections} for this purpose. Within each section, there can be
3475numbered subsections with values from 0 to 8192. Objects assembled into the
3476same subsection go into the object file together with other objects in the same
3477subsection. For example, a compiler might want to store constants in the text
3478section, but might not want to have them interspersed with the program being
3479assembled. In this case, the compiler could issue a @samp{.text 0} before each
3480section of code being output, and a @samp{.text 1} before each group of
3481constants being output.
3482
3483Subsections are optional. If you do not use subsections, everything
3484goes in subsection number zero.
3485
3486@ifset GENERIC
3487Each subsection is zero-padded up to a multiple of four bytes.
3488(Subsections may be padded a different amount on different flavors
a4fb0134 3489of @command{@value{AS}}.)
252b5132
RH
3490@end ifset
3491@ifclear GENERIC
3492@ifset H8
7be1c489 3493On the H8/300 platform, each subsection is zero-padded to a word
252b5132 3494boundary (two bytes).
c2dcd04e 3495The same is true on the Renesas SH.
252b5132
RH
3496@end ifset
3497@ifset I960
3498@c FIXME section padding (alignment)?
3499@c Rich Pixley says padding here depends on target obj code format; that
3500@c doesn't seem particularly useful to say without further elaboration,
3501@c so for now I say nothing about it. If this is a generic BFD issue,
3502@c these paragraphs might need to vanish from this manual, and be
3503@c discussed in BFD chapter of binutils (or some such).
3504@end ifset
252b5132
RH
3505@end ifclear
3506
3507Subsections appear in your object file in numeric order, lowest numbered
3508to highest. (All this to be compatible with other people's assemblers.)
3509The object file contains no representation of subsections; @code{@value{LD}} and
3510other programs that manipulate object files see no trace of them.
3511They just see all your text subsections as a text section, and all your
3512data subsections as a data section.
3513
3514To specify which subsection you want subsequent statements assembled
3515into, use a numeric argument to specify it, in a @samp{.text
3516@var{expression}} or a @samp{.data @var{expression}} statement.
ed9589d4 3517@ifset COFF
252b5132 3518@ifset GENERIC
ed9589d4 3519When generating COFF output, you
252b5132
RH
3520@end ifset
3521@ifclear GENERIC
3522You
3523@end ifclear
3524can also use an extra subsection
3525argument with arbitrary named sections: @samp{.section @var{name},
3526@var{expression}}.
3527@end ifset
ed9589d4
BW
3528@ifset ELF
3529@ifset GENERIC
3530When generating ELF output, you
3531@end ifset
3532@ifclear GENERIC
3533You
3534@end ifclear
3535can also use the @code{.subsection} directive (@pxref{SubSection})
3536to specify a subsection: @samp{.subsection @var{expression}}.
3537@end ifset
96e9638b
BW
3538@var{Expression} should be an absolute expression
3539(@pxref{Expressions}). If you just say @samp{.text} then @samp{.text 0}
252b5132
RH
3540is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
3541begins in @code{text 0}. For instance:
3542@smallexample
3543.text 0 # The default subsection is text 0 anyway.
3544.ascii "This lives in the first text subsection. *"
3545.text 1
3546.ascii "But this lives in the second text subsection."
3547.data 0
3548.ascii "This lives in the data section,"
3549.ascii "in the first data subsection."
3550.text 0
3551.ascii "This lives in the first text section,"
3552.ascii "immediately following the asterisk (*)."
3553@end smallexample
3554
3555Each section has a @dfn{location counter} incremented by one for every byte
3556assembled into that section. Because subsections are merely a convenience
a4fb0134 3557restricted to @command{@value{AS}} there is no concept of a subsection location
252b5132
RH
3558counter. There is no way to directly manipulate a location counter---but the
3559@code{.align} directive changes it, and any label definition captures its
3560current value. The location counter of the section where statements are being
3561assembled is said to be the @dfn{active} location counter.
3562
3563@node bss
3564@section bss Section
3565
3566@cindex bss section
3567@cindex common variable storage
3568The bss section is used for local common variable storage.
3569You may allocate address space in the bss section, but you may
3570not dictate data to load into it before your program executes. When
3571your program starts running, all the contents of the bss
3572section are zeroed bytes.
3573
3574The @code{.lcomm} pseudo-op defines a symbol in the bss section; see
3575@ref{Lcomm,,@code{.lcomm}}.
3576
3577The @code{.comm} pseudo-op may be used to declare a common symbol, which is
96e9638b 3578another form of uninitialized symbol; see @ref{Comm,,@code{.comm}}.
252b5132
RH
3579
3580@ifset GENERIC
3581When assembling for a target which supports multiple sections, such as ELF or
3582COFF, you may switch into the @code{.bss} section and define symbols as usual;
3583see @ref{Section,,@code{.section}}. You may only assemble zero values into the
3584section. Typically the section will only contain symbol definitions and
3585@code{.skip} directives (@pxref{Skip,,@code{.skip}}).
3586@end ifset
3587
3588@node Symbols
3589@chapter Symbols
3590
3591@cindex symbols
3592Symbols are a central concept: the programmer uses symbols to name
3593things, the linker uses symbols to link, and the debugger uses symbols
3594to debug.
3595
3596@quotation
3597@cindex debuggers, and symbol order
a4fb0134 3598@emph{Warning:} @command{@value{AS}} does not place symbols in the object file in
252b5132
RH
3599the same order they were declared. This may break some debuggers.
3600@end quotation
3601
3602@menu
3603* Labels:: Labels
3604* Setting Symbols:: Giving Symbols Other Values
3605* Symbol Names:: Symbol Names
3606* Dot:: The Special Dot Symbol
3607* Symbol Attributes:: Symbol Attributes
3608@end menu
3609
3610@node Labels
3611@section Labels
3612
3613@cindex labels
3614A @dfn{label} is written as a symbol immediately followed by a colon
3615@samp{:}. The symbol then represents the current value of the
3616active location counter, and is, for example, a suitable instruction
3617operand. You are warned if you use the same symbol to represent two
3618different locations: the first definition overrides any other
3619definitions.
3620
3621@ifset HPPA
3622On the HPPA, the usual form for a label need not be immediately followed by a
3623colon, but instead must start in column zero. Only one label may be defined on
a4fb0134 3624a single line. To work around this, the HPPA version of @command{@value{AS}} also
252b5132
RH
3625provides a special directive @code{.label} for defining labels more flexibly.
3626@end ifset
3627
3628@node Setting Symbols
3629@section Giving Symbols Other Values
3630
3631@cindex assigning values to symbols
3632@cindex symbol values, assigning
3633A symbol can be given an arbitrary value by writing a symbol, followed
3634by an equals sign @samp{=}, followed by an expression
3635(@pxref{Expressions}). This is equivalent to using the @code{.set}
9497f5ac
NC
3636directive. @xref{Set,,@code{.set}}. In the same way, using a double
3637equals sign @samp{=}@samp{=} here represents an equivalent of the
3638@code{.eqv} directive. @xref{Eqv,,@code{.eqv}}.
252b5132 3639
f8739b83
JZ
3640@ifset Blackfin
3641Blackfin does not support symbol assignment with @samp{=}.
3642@end ifset
3643
252b5132
RH
3644@node Symbol Names
3645@section Symbol Names
3646
3647@cindex symbol names
3648@cindex names, symbol
3649@ifclear SPECIAL-SYMS
3650Symbol names begin with a letter or with one of @samp{._}. On most
3651machines, you can also use @code{$} in symbol names; exceptions are
3652noted in @ref{Machine Dependencies}. That character may be followed by any
96e9638b
BW
3653string of digits, letters, dollar signs (unless otherwise noted for a
3654particular target machine), and underscores.
252b5132 3655@end ifclear
252b5132
RH
3656@ifset SPECIAL-SYMS
3657@ifset H8
3658Symbol names begin with a letter or with one of @samp{._}. On the
7be1c489 3659Renesas SH you can also use @code{$} in symbol names. That
c2dcd04e
NC
3660character may be followed by any string of digits, letters, dollar signs (save
3661on the H8/300), and underscores.
252b5132
RH
3662@end ifset
3663@end ifset
3664
3665Case of letters is significant: @code{foo} is a different symbol name
3666than @code{Foo}.
3667
ed1fcdd1
NC
3668Symbol names do not start with a digit. An exception to this rule is made for
3669Local Labels. See below.
3670
7bfd842d
NC
3671Multibyte characters are supported. To generate a symbol name containing
3672multibyte characters enclose it within double quotes and use escape codes. cf
3673@xref{Strings}. Generating a multibyte symbol name from a label is not
3674currently supported.
3675
252b5132
RH
3676Each symbol has exactly one name. Each name in an assembly language program
3677refers to exactly one symbol. You may use that symbol name any number of times
3678in a program.
3679
3680@subheading Local Symbol Names
3681
3682@cindex local symbol names
3683@cindex symbol names, local
ba83aca1
BW
3684A local symbol is any symbol beginning with certain local label prefixes.
3685By default, the local label prefix is @samp{.L} for ELF systems or
3686@samp{L} for traditional a.out systems, but each target may have its own
3687set of local label prefixes.
3688@ifset HPPA
3689On the HPPA local symbols begin with @samp{L$}.
3690@end ifset
3691
3692Local symbols are defined and used within the assembler, but they are
3693normally not saved in object files. Thus, they are not visible when debugging.
5c9352f3
AM
3694You may use the @samp{-L} option (@pxref{L, ,Include Local Symbols})
3695to retain the local symbols in the object files.
ba83aca1
BW
3696
3697@subheading Local Labels
3698
3699@cindex local labels
252b5132
RH
3700@cindex temporary symbol names
3701@cindex symbol names, temporary
ed1fcdd1
NC
3702Local labels are different from local symbols. Local labels help compilers and
3703programmers use names temporarily. They create symbols which are guaranteed to
3704be unique over the entire scope of the input source code and which can be
3705referred to by a simple notation. To define a local label, write a label of
3706the form @samp{@b{N}:} (where @b{N} represents any positive integer). To refer
3707to the most recent previous definition of that label write @samp{@b{N}b}, using
3708the same number as when you defined the label. To refer to the next definition
3709of a local label, write @samp{@b{N}f}---the @samp{b} stands for ``backwards''
3710and the @samp{f} stands for ``forwards''.
2d5aaba0
NC
3711
3712There is no restriction on how you can use these labels, and you can reuse them
3713too. So that it is possible to repeatedly define the same local label (using
3714the same number @samp{@b{N}}), although you can only refer to the most recently
3715defined local label of that number (for a backwards reference) or the next
3716definition of a specific local label for a forward reference. It is also worth
3717noting that the first 10 local labels (@samp{@b{0:}}@dots{}@samp{@b{9:}}) are
3718implemented in a slightly more efficient manner than the others.
3719
3720Here is an example:
3721
3722@smallexample
37231: branch 1f
37242: branch 1b
37251: branch 2f
37262: branch 1b
3727@end smallexample
3728
3729Which is the equivalent of:
3730
3731@smallexample
3732label_1: branch label_3
3733label_2: branch label_1
3734label_3: branch label_4
3735label_4: branch label_3
3736@end smallexample
3737
ba83aca1 3738Local label names are only a notational device. They are immediately
2d5aaba0 3739transformed into more conventional symbol names before the assembler uses them.
96e9638b
BW
3740The symbol names are stored in the symbol table, appear in error messages, and
3741are optionally emitted to the object file. The names are constructed using
3742these parts:
252b5132
RH
3743
3744@table @code
ba83aca1
BW
3745@item @emph{local label prefix}
3746All local symbols begin with the system-specific local label prefix.
3747Normally both @command{@value{AS}} and @code{@value{LD}} forget symbols
3748that start with the local label prefix. These labels are
252b5132 3749used for symbols you are never intended to see. If you use the
a4fb0134 3750@samp{-L} option then @command{@value{AS}} retains these symbols in the
252b5132
RH
3751object file. If you also instruct @code{@value{LD}} to retain these symbols,
3752you may use them in debugging.
3753
2d5aaba0
NC
3754@item @var{number}
3755This is the number that was used in the local label definition. So if the
01642c12 3756label is written @samp{55:} then the number is @samp{55}.
252b5132 3757
2d5aaba0
NC
3758@item @kbd{C-B}
3759This unusual character is included so you do not accidentally invent a symbol
3760of the same name. The character has ASCII value of @samp{\002} (control-B).
252b5132
RH
3761
3762@item @emph{ordinal number}
2d5aaba0 3763This is a serial number to keep the labels distinct. The first definition of
01642c12 3764@samp{0:} gets the number @samp{1}. The 15th definition of @samp{0:} gets the
2d5aaba0 3765number @samp{15}, and so on. Likewise the first definition of @samp{1:} gets
b45619c0 3766the number @samp{1} and its 15th definition gets @samp{15} as well.
252b5132
RH
3767@end table
3768
ba83aca1
BW
3769So for example, the first @code{1:} may be named @code{.L1@kbd{C-B}1}, and
3770the 44th @code{3:} may be named @code{.L3@kbd{C-B}44}.
2d5aaba0
NC
3771
3772@subheading Dollar Local Labels
3773@cindex dollar local symbols
3774
ed1fcdd1
NC
3775On some targets @code{@value{AS}} also supports an even more local form of
3776local labels called dollar labels. These labels go out of scope (i.e., they
3777become undefined) as soon as a non-local label is defined. Thus they remain
3778valid for only a small region of the input source code. Normal local labels,
3779by contrast, remain in scope for the entire file, or until they are redefined
3780by another occurrence of the same local label.
2d5aaba0
NC
3781
3782Dollar labels are defined in exactly the same way as ordinary local labels,
77cca80f
NC
3783except that they have a dollar sign suffix to their numeric value, e.g.,
3784@samp{@b{55$:}}.
2d5aaba0
NC
3785
3786They can also be distinguished from ordinary local labels by their transformed
96e9638b
BW
3787names which use ASCII character @samp{\001} (control-A) as the magic character
3788to distinguish them from ordinary labels. For example, the fifth definition of
ba83aca1 3789@samp{6$} may be named @samp{.L6@kbd{C-A}5}.
252b5132
RH
3790
3791@node Dot
3792@section The Special Dot Symbol
3793
3794@cindex dot (symbol)
3795@cindex @code{.} (symbol)
3796@cindex current address
3797@cindex location counter
3798The special symbol @samp{.} refers to the current address that
a4fb0134 3799@command{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
252b5132
RH
3800.long .} defines @code{melvin} to contain its own address.
3801Assigning a value to @code{.} is treated the same as a @code{.org}
884f0d36 3802directive.
252b5132 3803@ifclear no-space-dir
884f0d36 3804Thus, the expression @samp{.=.+4} is the same as saying
252b5132
RH
3805@samp{.space 4}.
3806@end ifclear
252b5132
RH
3807
3808@node Symbol Attributes
3809@section Symbol Attributes
3810
3811@cindex symbol attributes
3812@cindex attributes, symbol
3813Every symbol has, as well as its name, the attributes ``Value'' and
3814``Type''. Depending on output format, symbols can also have auxiliary
3815attributes.
3816@ifset INTERNALS
3817The detailed definitions are in @file{a.out.h}.
3818@end ifset
3819
a4fb0134 3820If you use a symbol without defining it, @command{@value{AS}} assumes zero for
252b5132
RH
3821all these attributes, and probably won't warn you. This makes the
3822symbol an externally defined symbol, which is generally what you
3823would want.
3824
3825@menu
3826* Symbol Value:: Value
3827* Symbol Type:: Type
3828@ifset aout-bout
3829@ifset GENERIC
3830* a.out Symbols:: Symbol Attributes: @code{a.out}
3831@end ifset
3832@ifclear GENERIC
3833@ifclear BOUT
3834* a.out Symbols:: Symbol Attributes: @code{a.out}
3835@end ifclear
3836@ifset BOUT
3837* a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
3838@end ifset
3839@end ifclear
3840@end ifset
3841@ifset COFF
3842* COFF Symbols:: Symbol Attributes for COFF
3843@end ifset
3844@ifset SOM
3845* SOM Symbols:: Symbol Attributes for SOM
3846@end ifset
3847@end menu
3848
3849@node Symbol Value
3850@subsection Value
3851
3852@cindex value of a symbol
3853@cindex symbol value
3854The value of a symbol is (usually) 32 bits. For a symbol which labels a
3855location in the text, data, bss or absolute sections the value is the
3856number of addresses from the start of that section to the label.
3857Naturally for text, data and bss sections the value of a symbol changes
3858as @code{@value{LD}} changes section base addresses during linking. Absolute
3859symbols' values do not change during linking: that is why they are
3860called absolute.
3861
3862The value of an undefined symbol is treated in a special way. If it is
38630 then the symbol is not defined in this assembler source file, and
3864@code{@value{LD}} tries to determine its value from other files linked into the
3865same program. You make this kind of symbol simply by mentioning a symbol
3866name without defining it. A non-zero value represents a @code{.comm}
3867common declaration. The value is how much common storage to reserve, in
3868bytes (addresses). The symbol refers to the first address of the
3869allocated storage.
3870
3871@node Symbol Type
3872@subsection Type
3873
3874@cindex type of a symbol
3875@cindex symbol type
3876The type attribute of a symbol contains relocation (section)
3877information, any flag settings indicating that a symbol is external, and
3878(optionally), other information for linkers and debuggers. The exact
3879format depends on the object-code output format in use.
3880
3881@ifset aout-bout
3882@ifclear GENERIC
3883@ifset BOUT
3884@c The following avoids a "widow" subsection title. @group would be
3885@c better if it were available outside examples.
3886@need 1000
3887@node a.out Symbols
3888@subsection Symbol Attributes: @code{a.out}, @code{b.out}
3889
3890@cindex @code{b.out} symbol attributes
3891@cindex symbol attributes, @code{b.out}
a4fb0134 3892These symbol attributes appear only when @command{@value{AS}} is configured for
252b5132
RH
3893one of the Berkeley-descended object output formats---@code{a.out} or
3894@code{b.out}.
3895
3896@end ifset
3897@ifclear BOUT
3898@node a.out Symbols
3899@subsection Symbol Attributes: @code{a.out}
3900
3901@cindex @code{a.out} symbol attributes
3902@cindex symbol attributes, @code{a.out}
3903
3904@end ifclear
3905@end ifclear
3906@ifset GENERIC
3907@node a.out Symbols
3908@subsection Symbol Attributes: @code{a.out}
3909
3910@cindex @code{a.out} symbol attributes
3911@cindex symbol attributes, @code{a.out}
3912
3913@end ifset
3914@menu
3915* Symbol Desc:: Descriptor
3916* Symbol Other:: Other
3917@end menu
3918
3919@node Symbol Desc
3920@subsubsection Descriptor
3921
3922@cindex descriptor, of @code{a.out} symbol
3923This is an arbitrary 16-bit value. You may establish a symbol's
3924descriptor value by using a @code{.desc} statement
3925(@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
a4fb0134 3926@command{@value{AS}}.
252b5132
RH
3927
3928@node Symbol Other
3929@subsubsection Other
3930
3931@cindex other attribute, of @code{a.out} symbol
a4fb0134 3932This is an arbitrary 8-bit value. It means nothing to @command{@value{AS}}.
252b5132
RH
3933@end ifset
3934
3935@ifset COFF
3936@node COFF Symbols
3937@subsection Symbol Attributes for COFF
3938
3939@cindex COFF symbol attributes
3940@cindex symbol attributes, COFF
3941
3942The COFF format supports a multitude of auxiliary symbol attributes;
3943like the primary symbol attributes, they are set between @code{.def} and
3944@code{.endef} directives.
3945
3946@subsubsection Primary Attributes
3947
3948@cindex primary attributes, COFF symbols
3949The symbol name is set with @code{.def}; the value and type,
3950respectively, with @code{.val} and @code{.type}.
3951
3952@subsubsection Auxiliary Attributes
3953
3954@cindex auxiliary attributes, COFF symbols
a4fb0134 3955The @command{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
c87db184
CF
3956@code{.size}, @code{.tag}, and @code{.weak} can generate auxiliary symbol
3957table information for COFF.
252b5132
RH
3958@end ifset
3959
3960@ifset SOM
3961@node SOM Symbols
3962@subsection Symbol Attributes for SOM
3963
3964@cindex SOM symbol attributes
3965@cindex symbol attributes, SOM
3966
3967The SOM format for the HPPA supports a multitude of symbol attributes set with
3968the @code{.EXPORT} and @code{.IMPORT} directives.
3969
01642c12 3970The attributes are described in @cite{HP9000 Series 800 Assembly
252b5132
RH
3971Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
3972@code{EXPORT} assembler directive documentation.
3973@end ifset
3974
3975@node Expressions
3976@chapter Expressions
3977
3978@cindex expressions
3979@cindex addresses
3980@cindex numeric values
3981An @dfn{expression} specifies an address or numeric value.
3982Whitespace may precede and/or follow an expression.
3983
3984The result of an expression must be an absolute number, or else an offset into
3985a particular section. If an expression is not absolute, and there is not
a4fb0134 3986enough information when @command{@value{AS}} sees the expression to know its
252b5132
RH
3987section, a second pass over the source program might be necessary to interpret
3988the expression---but the second pass is currently not implemented.
a4fb0134 3989@command{@value{AS}} aborts with an error message in this situation.
252b5132
RH
3990
3991@menu
3992* Empty Exprs:: Empty Expressions
3993* Integer Exprs:: Integer Expressions
3994@end menu
3995
3996@node Empty Exprs
3997@section Empty Expressions
3998
3999@cindex empty expressions
4000@cindex expressions, empty
4001An empty expression has no value: it is just whitespace or null.
4002Wherever an absolute expression is required, you may omit the
a4fb0134 4003expression, and @command{@value{AS}} assumes a value of (absolute) 0. This
252b5132
RH
4004is compatible with other assemblers.
4005
4006@node Integer Exprs
4007@section Integer Expressions
4008
4009@cindex integer expressions
4010@cindex expressions, integer
4011An @dfn{integer expression} is one or more @emph{arguments} delimited
4012by @emph{operators}.
4013
4014@menu
4015* Arguments:: Arguments
4016* Operators:: Operators
4017* Prefix Ops:: Prefix Operators
4018* Infix Ops:: Infix Operators
4019@end menu
4020
4021@node Arguments
4022@subsection Arguments
4023
4024@cindex expression arguments
4025@cindex arguments in expressions
4026@cindex operands in expressions
4027@cindex arithmetic operands
4028@dfn{Arguments} are symbols, numbers or subexpressions. In other
4029contexts arguments are sometimes called ``arithmetic operands''. In
4030this manual, to avoid confusing them with the ``instruction operands'' of
4031the machine language, we use the term ``argument'' to refer to parts of
4032expressions only, reserving the word ``operand'' to refer only to machine
4033instruction operands.
4034
4035Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
4036@var{section} is one of text, data, bss, absolute,
4037or undefined. @var{NNN} is a signed, 2's complement 32 bit
4038integer.
4039
4040Numbers are usually integers.
4041
4042A number can be a flonum or bignum. In this case, you are warned
a4fb0134 4043that only the low order 32 bits are used, and @command{@value{AS}} pretends
252b5132
RH
4044these 32 bits are an integer. You may write integer-manipulating
4045instructions that act on exotic constants, compatible with other
4046assemblers.
4047
4048@cindex subexpressions
4049Subexpressions are a left parenthesis @samp{(} followed by an integer
4050expression, followed by a right parenthesis @samp{)}; or a prefix
4051operator followed by an argument.
4052
4053@node Operators
4054@subsection Operators
4055
4056@cindex operators, in expressions
4057@cindex arithmetic functions
4058@cindex functions, in expressions
4059@dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
4060operators are followed by an argument. Infix operators appear
4061between their arguments. Operators may be preceded and/or followed by
4062whitespace.
4063
4064@node Prefix Ops
4065@subsection Prefix Operator
4066
4067@cindex prefix operators
a4fb0134 4068@command{@value{AS}} has the following @dfn{prefix operators}. They each take
252b5132
RH
4069one argument, which must be absolute.
4070
4071@c the tex/end tex stuff surrounding this small table is meant to make
4072@c it align, on the printed page, with the similar table in the next
4073@c section (which is inside an enumerate).
4074@tex
4075\global\advance\leftskip by \itemindent
4076@end tex
4077
4078@table @code
4079@item -
4080@dfn{Negation}. Two's complement negation.
4081@item ~
4082@dfn{Complementation}. Bitwise not.
4083@end table
4084
4085@tex
4086\global\advance\leftskip by -\itemindent
4087@end tex
4088
4089@node Infix Ops
4090@subsection Infix Operators
4091
4092@cindex infix operators
4093@cindex operators, permitted arguments
4094@dfn{Infix operators} take two arguments, one on either side. Operators
4095have precedence, but operations with equal precedence are performed left
a4fb0134 4096to right. Apart from @code{+} or @option{-}, both arguments must be
252b5132
RH
4097absolute, and the result is absolute.
4098
4099@enumerate
4100@cindex operator precedence
4101@cindex precedence of operators
4102
4103@item
4104Highest Precedence
4105
4106@table @code
4107@item *
4108@dfn{Multiplication}.
4109
4110@item /
4111@dfn{Division}. Truncation is the same as the C operator @samp{/}
4112
4113@item %
4114@dfn{Remainder}.
4115
d1eac9d9 4116@item <<
252b5132
RH
4117@dfn{Shift Left}. Same as the C operator @samp{<<}.
4118
d1eac9d9 4119@item >>
252b5132
RH
4120@dfn{Shift Right}. Same as the C operator @samp{>>}.
4121@end table
4122
4123@item
4124Intermediate precedence
4125
4126@table @code
4127@item |
4128
4129@dfn{Bitwise Inclusive Or}.
4130
4131@item &
4132@dfn{Bitwise And}.
4133
4134@item ^
4135@dfn{Bitwise Exclusive Or}.
4136
4137@item !
4138@dfn{Bitwise Or Not}.
4139@end table
4140
4141@item
b131d4dc 4142Low Precedence
252b5132
RH
4143
4144@table @code
4145@cindex addition, permitted arguments
4146@cindex plus, permitted arguments
4147@cindex arguments for addition
4148@item +
4149@dfn{Addition}. If either argument is absolute, the result has the section of
4150the other argument. You may not add together arguments from different
4151sections.
4152
4153@cindex subtraction, permitted arguments
4154@cindex minus, permitted arguments
4155@cindex arguments for subtraction
4156@item -
4157@dfn{Subtraction}. If the right argument is absolute, the
4158result has the section of the left argument.
4159If both arguments are in the same section, the result is absolute.
4160You may not subtract arguments from different sections.
4161@c FIXME is there still something useful to say about undefined - undefined ?
b131d4dc
NC
4162
4163@cindex comparison expressions
4164@cindex expressions, comparison
4165@item ==
4166@dfn{Is Equal To}
4167@item <>
723a8472 4168@itemx !=
b131d4dc
NC
4169@dfn{Is Not Equal To}
4170@item <
4171@dfn{Is Less Than}
d1eac9d9 4172@item >
b131d4dc 4173@dfn{Is Greater Than}
d1eac9d9 4174@item >=
b131d4dc 4175@dfn{Is Greater Than Or Equal To}
d1eac9d9 4176@item <=
b131d4dc
NC
4177@dfn{Is Less Than Or Equal To}
4178
4179The comparison operators can be used as infix operators. A true results has a
4180value of -1 whereas a false result has a value of 0. Note, these operators
4181perform signed comparisons.
4182@end table
4183
4184@item Lowest Precedence
4185
4186@table @code
4187@item &&
4188@dfn{Logical And}.
4189
4190@item ||
4191@dfn{Logical Or}.
4192
4193These two logical operations can be used to combine the results of sub
4194expressions. Note, unlike the comparison operators a true result returns a
4195value of 1 but a false results does still return 0. Also note that the logical
4196or operator has a slightly lower precedence than logical and.
4197
252b5132
RH
4198@end table
4199@end enumerate
4200
4201In short, it's only meaningful to add or subtract the @emph{offsets} in an
4202address; you can only have a defined section in one of the two arguments.
4203
4204@node Pseudo Ops
4205@chapter Assembler Directives
4206
4207@cindex directives, machine independent
4208@cindex pseudo-ops, machine independent
4209@cindex machine independent directives
4210All assembler directives have names that begin with a period (@samp{.}).
7e302352
RS
4211The names are case insensitive for most targets, and usually written
4212in lower case.
252b5132
RH
4213
4214This chapter discusses directives that are available regardless of the
4215target machine configuration for the @sc{gnu} assembler.
4216@ifset GENERIC
4217Some machine configurations provide additional directives.
4218@xref{Machine Dependencies}.
4219@end ifset
4220@ifclear GENERIC
4221@ifset machine-directives
96e9638b 4222@xref{Machine Dependencies}, for additional directives.
252b5132
RH
4223@end ifset
4224@end ifclear
4225
4226@menu
4227* Abort:: @code{.abort}
4228@ifset COFF
38a57ae7 4229* ABORT (COFF):: @code{.ABORT}
252b5132 4230@end ifset
f0dc282c 4231
252b5132 4232* Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
caa32fe5 4233* Altmacro:: @code{.altmacro}
252b5132
RH
4234* Ascii:: @code{.ascii "@var{string}"}@dots{}
4235* Asciz:: @code{.asciz "@var{string}"}@dots{}
4236* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}}
d3b47e2b 4237* Bundle directives:: @code{.bundle_align_mode @var{abs-expr}}, etc
252b5132 4238* Byte:: @code{.byte @var{expressions}}
4b7d318b 4239* CFI directives:: @code{.cfi_startproc [simple]}, @code{.cfi_endproc}, etc.
ccf8a69b 4240* Comm:: @code{.comm @var{symbol} , @var{length} }
252b5132
RH
4241* Data:: @code{.data @var{subsection}}
4242@ifset COFF
4243* Def:: @code{.def @var{name}}
4244@end ifset
4245@ifset aout-bout
4246* Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
4247@end ifset
4248@ifset COFF
4249* Dim:: @code{.dim}
4250@end ifset
f0dc282c 4251
252b5132
RH
4252* Double:: @code{.double @var{flonums}}
4253* Eject:: @code{.eject}
4254* Else:: @code{.else}
3fd9f047 4255* Elseif:: @code{.elseif}
252b5132
RH
4256* End:: @code{.end}
4257@ifset COFF
4258* Endef:: @code{.endef}
4259@end ifset
f0dc282c 4260
252b5132
RH
4261* Endfunc:: @code{.endfunc}
4262* Endif:: @code{.endif}
4263* Equ:: @code{.equ @var{symbol}, @var{expression}}
4264* Equiv:: @code{.equiv @var{symbol}, @var{expression}}
9497f5ac 4265* Eqv:: @code{.eqv @var{symbol}, @var{expression}}
252b5132 4266* Err:: @code{.err}
d190d046 4267* Error:: @code{.error @var{string}}
252b5132
RH
4268* Exitm:: @code{.exitm}
4269* Extern:: @code{.extern}
4270* Fail:: @code{.fail}
14082c76 4271* File:: @code{.file}
252b5132
RH
4272* Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
4273* Float:: @code{.float @var{flonums}}
01642c12 4274* Func:: @code{.func}
252b5132 4275* Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
c91d2e08 4276@ifset ELF
3a99f02f 4277* Gnu_attribute:: @code{.gnu_attribute @var{tag},@var{value}}
c91d2e08
NC
4278* Hidden:: @code{.hidden @var{names}}
4279@end ifset
f0dc282c 4280
252b5132
RH
4281* hword:: @code{.hword @var{expressions}}
4282* Ident:: @code{.ident}
4283* If:: @code{.if @var{absolute expression}}
7e005732 4284* Incbin:: @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]}
252b5132
RH
4285* Include:: @code{.include "@var{file}"}
4286* Int:: @code{.int @var{expressions}}
c91d2e08
NC
4287@ifset ELF
4288* Internal:: @code{.internal @var{names}}
4289@end ifset
f0dc282c 4290
252b5132
RH
4291* Irp:: @code{.irp @var{symbol},@var{values}}@dots{}
4292* Irpc:: @code{.irpc @var{symbol},@var{values}}@dots{}
4293* Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
4294* Lflags:: @code{.lflags}
4295@ifclear no-line-dir
4296* Line:: @code{.line @var{line-number}}
4297@end ifclear
f0dc282c 4298
252b5132
RH
4299* Linkonce:: @code{.linkonce [@var{type}]}
4300* List:: @code{.list}
bd0eb99b 4301* Ln:: @code{.ln @var{line-number}}
14082c76
BW
4302* Loc:: @code{.loc @var{fileno} @var{lineno}}
4303* Loc_mark_labels:: @code{.loc_mark_labels @var{enable}}
4d4175af
BW
4304@ifset ELF
4305* Local:: @code{.local @var{names}}
4306@end ifset
bd0eb99b 4307
252b5132
RH
4308* Long:: @code{.long @var{expressions}}
4309@ignore
4310* Lsym:: @code{.lsym @var{symbol}, @var{expression}}
4311@end ignore
f0dc282c 4312
252b5132
RH
4313* Macro:: @code{.macro @var{name} @var{args}}@dots{}
4314* MRI:: @code{.mri @var{val}}
caa32fe5 4315* Noaltmacro:: @code{.noaltmacro}
252b5132
RH
4316* Nolist:: @code{.nolist}
4317* Octa:: @code{.octa @var{bignums}}
9aec2026 4318* Offset:: @code{.offset @var{loc}}
85234291
L
4319* Org:: @code{.org @var{new-lc}, @var{fill}}
4320* P2align:: @code{.p2align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
c91d2e08
NC
4321@ifset ELF
4322* PopSection:: @code{.popsection}
4323* Previous:: @code{.previous}
4324@end ifset
f0dc282c 4325
252b5132 4326* Print:: @code{.print @var{string}}
c91d2e08
NC
4327@ifset ELF
4328* Protected:: @code{.protected @var{names}}
4329@end ifset
f0dc282c 4330
252b5132
RH
4331* Psize:: @code{.psize @var{lines}, @var{columns}}
4332* Purgem:: @code{.purgem @var{name}}
c91d2e08
NC
4333@ifset ELF
4334* PushSection:: @code{.pushsection @var{name}}
4335@end ifset
f0dc282c 4336
252b5132 4337* Quad:: @code{.quad @var{bignums}}
05e9452c 4338* Reloc:: @code{.reloc @var{offset}, @var{reloc_name}[, @var{expression}]}
252b5132
RH
4339* Rept:: @code{.rept @var{count}}
4340* Sbttl:: @code{.sbttl "@var{subheading}"}
4341@ifset COFF
4342* Scl:: @code{.scl @var{class}}
c1253627
NC
4343@end ifset
4344@ifset COFF-ELF
7337fc21 4345* Section:: @code{.section @var{name}[, @var{flags}]}
252b5132 4346@end ifset
f0dc282c 4347
252b5132
RH
4348* Set:: @code{.set @var{symbol}, @var{expression}}
4349* Short:: @code{.short @var{expressions}}
4350* Single:: @code{.single @var{flonums}}
c1253627 4351@ifset COFF-ELF
c91d2e08 4352* Size:: @code{.size [@var{name} , @var{expression}]}
c1253627 4353@end ifset
884f0d36 4354@ifclear no-space-dir
252b5132 4355* Skip:: @code{.skip @var{size} , @var{fill}}
884f0d36
BW
4356@end ifclear
4357
252b5132 4358* Sleb128:: @code{.sleb128 @var{expressions}}
884f0d36 4359@ifclear no-space-dir
252b5132 4360* Space:: @code{.space @var{size} , @var{fill}}
884f0d36 4361@end ifclear
252b5132
RH
4362@ifset have-stabs
4363* Stab:: @code{.stabd, .stabn, .stabs}
4364@end ifset
f0dc282c 4365
38a57ae7 4366* String:: @code{.string "@var{str}"}, @code{.string8 "@var{str}"}, @code{.string16 "@var{str}"}, @code{.string32 "@var{str}"}, @code{.string64 "@var{str}"}
252b5132
RH
4367* Struct:: @code{.struct @var{expression}}
4368@ifset ELF
c91d2e08 4369* SubSection:: @code{.subsection}
252b5132
RH
4370* Symver:: @code{.symver @var{name},@var{name2@@nodename}}
4371@end ifset
f0dc282c 4372
252b5132
RH
4373@ifset COFF
4374* Tag:: @code{.tag @var{structname}}
4375@end ifset
f0dc282c 4376
252b5132
RH
4377* Text:: @code{.text @var{subsection}}
4378* Title:: @code{.title "@var{heading}"}
c1253627 4379@ifset COFF-ELF
c91d2e08 4380* Type:: @code{.type <@var{int} | @var{name} , @var{type description}>}
c1253627
NC
4381@end ifset
4382
c91d2e08 4383* Uleb128:: @code{.uleb128 @var{expressions}}
252b5132 4384@ifset COFF
252b5132
RH
4385* Val:: @code{.val @var{addr}}
4386@end ifset
f0dc282c 4387
2e13b764 4388@ifset ELF
c91d2e08 4389* Version:: @code{.version "@var{string}"}
c91d2e08
NC
4390* VTableEntry:: @code{.vtable_entry @var{table}, @var{offset}}
4391* VTableInherit:: @code{.vtable_inherit @var{child}, @var{parent}}
2e13b764 4392@end ifset
f0dc282c 4393
d190d046 4394* Warning:: @code{.warning @var{string}}
c87db184 4395* Weak:: @code{.weak @var{names}}
06e77878 4396* Weakref:: @code{.weakref @var{alias}, @var{symbol}}
252b5132 4397* Word:: @code{.word @var{expressions}}
7ce98c16
NC
4398@ifclear no-space-dir
4399* Zero:: @code{.zero @var{size}}
4400@end ifclear
252b5132
RH
4401* Deprecated:: Deprecated Directives
4402@end menu
4403
4404@node Abort
4405@section @code{.abort}
4406
4407@cindex @code{abort} directive
4408@cindex stopping the assembly
4409This directive stops the assembly immediately. It is for
4410compatibility with other assemblers. The original idea was that the
4411assembly language source would be piped into the assembler. If the sender
a4fb0134 4412of the source quit, it could use this directive tells @command{@value{AS}} to
252b5132
RH
4413quit also. One day @code{.abort} will not be supported.
4414
4415@ifset COFF
370b66a1
CD
4416@node ABORT (COFF)
4417@section @code{.ABORT} (COFF)
252b5132
RH
4418
4419@cindex @code{ABORT} directive
a4fb0134 4420When producing COFF output, @command{@value{AS}} accepts this directive as a
252b5132
RH
4421synonym for @samp{.abort}.
4422
4423@ifset BOUT
a4fb0134 4424When producing @code{b.out} output, @command{@value{AS}} accepts this directive,
252b5132
RH
4425but ignores it.
4426@end ifset
4427@end ifset
4428
4429@node Align
4430@section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
4431
4432@cindex padding the location counter
4433@cindex @code{align} directive
4434Pad the location counter (in the current subsection) to a particular storage
4435boundary. The first expression (which must be absolute) is the alignment
4436required, as described below.
4437
4438The second expression (also absolute) gives the fill value to be stored in the
4439padding bytes. It (and the comma) may be omitted. If it is omitted, the
4440padding bytes are normally zero. However, on some systems, if the section is
4441marked as containing code and the fill value is omitted, the space is filled
4442with no-op instructions.
4443
4444The third expression is also absolute, and is also optional. If it is present,
4445it is the maximum number of bytes that should be skipped by this alignment
4446directive. If doing the alignment would require skipping more bytes than the
4447specified maximum, then the alignment is not done at all. You can omit the
4448fill value (the second argument) entirely by simply using two commas after the
4449required alignment; this can be useful if you want the alignment to be filled
4450with no-op instructions when appropriate.
4451
4452The way the required alignment is specified varies from system to system.
73589c9d 4453For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or1k,
60946ad0 4454s390, sparc, tic4x, tic80 and xtensa, the first expression is the
252b5132
RH
4455alignment request in bytes. For example @samp{.align 8} advances
4456the location counter until it is a multiple of 8. If the location counter
60946ad0
AM
4457is already a multiple of 8, no change is needed. For the tic54x, the
4458first expression is the alignment request in words.
252b5132 4459
9e9a9798 4460For other systems, including ppc, i386 using a.out format, arm and
adcf07e6 4461strongarm, it is the
252b5132
RH
4462number of low-order zero bits the location counter must have after
4463advancement. For example @samp{.align 3} advances the location
4464counter until it a multiple of 8. If the location counter is already a
4465multiple of 8, no change is needed.
4466
4467This inconsistency is due to the different behaviors of the various
4468native assemblers for these systems which GAS must emulate.
4469GAS also provides @code{.balign} and @code{.p2align} directives,
4470described later, which have a consistent behavior across all
4471architectures (but are specific to GAS).
4472
ccf8a69b
BW
4473@node Altmacro
4474@section @code{.altmacro}
4475Enable alternate macro mode, enabling:
4476
4477@ftable @code
4478@item LOCAL @var{name} [ , @dots{} ]
4479One additional directive, @code{LOCAL}, is available. It is used to
4480generate a string replacement for each of the @var{name} arguments, and
4481replace any instances of @var{name} in each macro expansion. The
4482replacement string is unique in the assembly, and different for each
4483separate macro expansion. @code{LOCAL} allows you to write macros that
4484define symbols, without fear of conflict between separate macro expansions.
4485
4486@item String delimiters
4487You can write strings delimited in these other ways besides
4488@code{"@var{string}"}:
4489
4490@table @code
4491@item '@var{string}'
4492You can delimit strings with single-quote characters.
4493
4494@item <@var{string}>
4495You can delimit strings with matching angle brackets.
4496@end table
4497
4498@item single-character string escape
4499To include any single character literally in a string (even if the
4500character would otherwise have some special meaning), you can prefix the
4501character with @samp{!} (an exclamation mark). For example, you can
4502write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}.
4503
4504@item Expression results as strings
4505You can write @samp{%@var{expr}} to evaluate the expression @var{expr}
01642c12 4506and use the result as a string.
ccf8a69b
BW
4507@end ftable
4508
252b5132
RH
4509@node Ascii
4510@section @code{.ascii "@var{string}"}@dots{}
4511
4512@cindex @code{ascii} directive
4513@cindex string literals
4514@code{.ascii} expects zero or more string literals (@pxref{Strings})
4515separated by commas. It assembles each string (with no automatic
4516trailing zero byte) into consecutive addresses.
4517
4518@node Asciz
4519@section @code{.asciz "@var{string}"}@dots{}
4520
4521@cindex @code{asciz} directive
4522@cindex zero-terminated strings
4523@cindex null-terminated strings
4524@code{.asciz} is just like @code{.ascii}, but each string is followed by
4525a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
4526
4527@node Balign
4528@section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
4529
4530@cindex padding the location counter given number of bytes
4531@cindex @code{balign} directive
4532Pad the location counter (in the current subsection) to a particular
4533storage boundary. The first expression (which must be absolute) is the
4534alignment request in bytes. For example @samp{.balign 8} advances
4535the location counter until it is a multiple of 8. If the location counter
4536is already a multiple of 8, no change is needed.
4537
4538The second expression (also absolute) gives the fill value to be stored in the
4539padding bytes. It (and the comma) may be omitted. If it is omitted, the
4540padding bytes are normally zero. However, on some systems, if the section is
4541marked as containing code and the fill value is omitted, the space is filled
4542with no-op instructions.
4543
4544The third expression is also absolute, and is also optional. If it is present,
4545it is the maximum number of bytes that should be skipped by this alignment
4546directive. If doing the alignment would require skipping more bytes than the
4547specified maximum, then the alignment is not done at all. You can omit the
4548fill value (the second argument) entirely by simply using two commas after the
4549required alignment; this can be useful if you want the alignment to be filled
4550with no-op instructions when appropriate.
4551
4552@cindex @code{balignw} directive
4553@cindex @code{balignl} directive
4554The @code{.balignw} and @code{.balignl} directives are variants of the
4555@code{.balign} directive. The @code{.balignw} directive treats the fill
4556pattern as a two byte word value. The @code{.balignl} directives treats the
4557fill pattern as a four byte longword value. For example, @code{.balignw
45584,0x368d} will align to a multiple of 4. If it skips two bytes, they will be
4559filled in with the value 0x368d (the exact placement of the bytes depends upon
4560the endianness of the processor). If it skips 1 or 3 bytes, the fill value is
4561undefined.
4562
fa94de6b 4563@node Bundle directives
d3b47e2b
L
4564@section Bundle directives
4565@subsection @code{.bundle_align_mode @var{abs-expr}}
fa94de6b
RM
4566@cindex @code{bundle_align_mode} directive
4567@cindex bundle
4568@cindex instruction bundle
4569@cindex aligned instruction bundle
ec82c18e 4570@code{.bundle_align_mode} enables or disables @dfn{aligned instruction
fa94de6b 4571bundle} mode. In this mode, sequences of adjacent instructions are grouped
ec82c18e 4572into fixed-sized @dfn{bundles}. If the argument is zero, this mode is
27dcf5c0 4573disabled (which is the default state). If the argument it not zero, it
fa94de6b
RM
4574gives the size of an instruction bundle as a power of two (as for the
4575@code{.p2align} directive, @pxref{P2align}).
4576
4577For some targets, it's an ABI requirement that no instruction may span a
ec82c18e 4578certain aligned boundary. A @dfn{bundle} is simply a sequence of
fa94de6b
RM
4579instructions that starts on an aligned boundary. For example, if
4580@var{abs-expr} is @code{5} then the bundle size is 32, so each aligned
4581chunk of 32 bytes is a bundle. When aligned instruction bundle mode is in
4582effect, no single instruction may span a boundary between bundles. If an
4583instruction would start too close to the end of a bundle for the length of
4584that particular instruction to fit within the bundle, then the space at the
4585end of that bundle is filled with no-op instructions so the instruction
4586starts in the next bundle. As a corollary, it's an error if any single
4587instruction's encoding is longer than the bundle size.
4588
d3b47e2b 4589@subsection @code{.bundle_lock} and @code{.bundle_unlock}
fa94de6b
RM
4590@cindex @code{bundle_lock} directive
4591@cindex @code{bundle_unlock} directive
4592The @code{.bundle_lock} and directive @code{.bundle_unlock} directives
4593allow explicit control over instruction bundle padding. These directives
4594are only valid when @code{.bundle_align_mode} has been used to enable
4595aligned instruction bundle mode. It's an error if they appear when
4596@code{.bundle_align_mode} has not been used at all, or when the last
4597directive was @w{@code{.bundle_align_mode 0}}.
4598
4599@cindex bundle-locked
4600For some targets, it's an ABI requirement that certain instructions may
4601appear only as part of specified permissible sequences of multiple
4602instructions, all within the same bundle. A pair of @code{.bundle_lock}
ec82c18e 4603and @code{.bundle_unlock} directives define a @dfn{bundle-locked}
fa94de6b
RM
4604instruction sequence. For purposes of aligned instruction bundle mode, a
4605sequence starting with @code{.bundle_lock} and ending with
4606@code{.bundle_unlock} is treated as a single instruction. That is, the
4607entire sequence must fit into a single bundle and may not span a bundle
4608boundary. If necessary, no-op instructions will be inserted before the
4609first instruction of the sequence so that the whole sequence starts on an
4610aligned bundle boundary. It's an error if the sequence is longer than the
4611bundle size.
4612
d416e51d
RM
4613For convenience when using @code{.bundle_lock} and @code{.bundle_unlock}
4614inside assembler macros (@pxref{Macro}), bundle-locked sequences may be
4615nested. That is, a second @code{.bundle_lock} directive before the next
4616@code{.bundle_unlock} directive has no effect except that it must be
4617matched by another closing @code{.bundle_unlock} so that there is the
4618same number of @code{.bundle_lock} and @code{.bundle_unlock} directives.
fa94de6b 4619
252b5132
RH
4620@node Byte
4621@section @code{.byte @var{expressions}}
4622
4623@cindex @code{byte} directive
4624@cindex integers, one byte
4625@code{.byte} expects zero or more expressions, separated by commas.
4626Each expression is assembled into the next byte.
4627
54cfded0 4628@node CFI directives
d3b47e2b
L
4629@section CFI directives
4630@subsection @code{.cfi_sections @var{section_list}}
38462edf
JJ
4631@cindex @code{cfi_sections} directive
4632@code{.cfi_sections} may be used to specify whether CFI directives
4633should emit @code{.eh_frame} section and/or @code{.debug_frame} section.
4634If @var{section_list} is @code{.eh_frame}, @code{.eh_frame} is emitted,
4635if @var{section_list} is @code{.debug_frame}, @code{.debug_frame} is emitted.
4636To emit both use @code{.eh_frame, .debug_frame}. The default if this
4637directive is not used is @code{.cfi_sections .eh_frame}.
4638
2f0c68f2
CM
4639On targets that support compact unwinding tables these can be generated
4640by specifying @code{.eh_frame_entry} instead of @code{.eh_frame}.
4641
d3b47e2b 4642@subsection @code{.cfi_startproc [simple]}
54cfded0
AM
4643@cindex @code{cfi_startproc} directive
4644@code{.cfi_startproc} is used at the beginning of each function that
4645should have an entry in @code{.eh_frame}. It initializes some internal
4b7d318b 4646data structures. Don't forget to close the function by
54cfded0
AM
4647@code{.cfi_endproc}.
4648
01642c12 4649Unless @code{.cfi_startproc} is used along with parameter @code{simple}
4b7d318b 4650it also emits some architecture dependent initial CFI instructions.
01642c12 4651
d3b47e2b 4652@subsection @code{.cfi_endproc}
54cfded0
AM
4653@cindex @code{cfi_endproc} directive
4654@code{.cfi_endproc} is used at the end of a function where it closes its
4655unwind entry previously opened by
b45619c0 4656@code{.cfi_startproc}, and emits it to @code{.eh_frame}.
54cfded0 4657
d3b47e2b 4658@subsection @code{.cfi_personality @var{encoding} [, @var{exp}]}
2f0c68f2 4659@cindex @code{cfi_personality} directive
9b8ae42e
JJ
4660@code{.cfi_personality} defines personality routine and its encoding.
4661@var{encoding} must be a constant determining how the personality
4662should be encoded. If it is 255 (@code{DW_EH_PE_omit}), second
4663argument is not present, otherwise second argument should be
4664a constant or a symbol name. When using indirect encodings,
4665the symbol provided should be the location where personality
4666can be loaded from, not the personality routine itself.
4667The default after @code{.cfi_startproc} is @code{.cfi_personality 0xff},
4668no personality routine.
4669
2f0c68f2
CM
4670@subsection @code{.cfi_personality_id @var{id}}
4671@cindex @code{cfi_personality_id} directive
4672@code{cfi_personality_id} defines a personality routine by its index as
4673defined in a compact unwinding format.
4674Only valid when generating compact EH frames (i.e.
4675with @code{.cfi_sections eh_frame_entry}.
4676
4677@subsection @code{.cfi_fde_data [@var{opcode1} [, @dots{}]]}
4678@cindex @code{cfi_fde_data} directive
4679@code{cfi_fde_data} is used to describe the compact unwind opcodes to be
4680used for the current function. These are emitted inline in the
4681@code{.eh_frame_entry} section if small enough and there is no LSDA, or
4682in the @code{.gnu.extab} section otherwise.
4683Only valid when generating compact EH frames (i.e.
4684with @code{.cfi_sections eh_frame_entry}.
4685
d3b47e2b 4686@subsection @code{.cfi_lsda @var{encoding} [, @var{exp}]}
9b8ae42e
JJ
4687@code{.cfi_lsda} defines LSDA and its encoding.
4688@var{encoding} must be a constant determining how the LSDA
2f0c68f2
CM
4689should be encoded. If it is 255 (@code{DW_EH_PE_omit}), the second
4690argument is not present, otherwise the second argument should be a constant
9b8ae42e 4691or a symbol name. The default after @code{.cfi_startproc} is @code{.cfi_lsda 0xff},
2f0c68f2
CM
4692meaning that no LSDA is present.
4693
4694@subsection @code{.cfi_inline_lsda} [@var{align}]
4695@code{.cfi_inline_lsda} marks the start of a LSDA data section and
4696switches to the corresponding @code{.gnu.extab} section.
4697Must be preceded by a CFI block containing a @code{.cfi_lsda} directive.
4698Only valid when generating compact EH frames (i.e.
4699with @code{.cfi_sections eh_frame_entry}.
4700
4701The table header and unwinding opcodes will be generated at this point,
4702so that they are immediately followed by the LSDA data. The symbol
4703referenced by the @code{.cfi_lsda} directive should still be defined
4704in case a fallback FDE based encoding is used. The LSDA data is terminated
4705by a section directive.
4706
4707The optional @var{align} argument specifies the alignment required.
4708The alignment is specified as a power of two, as with the
4709@code{.p2align} directive.
9b8ae42e 4710
d3b47e2b 4711@subsection @code{.cfi_def_cfa @var{register}, @var{offset}}
01642c12 4712@code{.cfi_def_cfa} defines a rule for computing CFA as: @i{take
54cfded0
AM
4713address from @var{register} and add @var{offset} to it}.
4714
d3b47e2b 4715@subsection @code{.cfi_def_cfa_register @var{register}}
54cfded0
AM
4716@code{.cfi_def_cfa_register} modifies a rule for computing CFA. From
4717now on @var{register} will be used instead of the old one. Offset
4718remains the same.
4719
d3b47e2b 4720@subsection @code{.cfi_def_cfa_offset @var{offset}}
54cfded0
AM
4721@code{.cfi_def_cfa_offset} modifies a rule for computing CFA. Register
4722remains the same, but @var{offset} is new. Note that it is the
4723absolute offset that will be added to a defined register to compute
4724CFA address.
4725
d3b47e2b 4726@subsection @code{.cfi_adjust_cfa_offset @var{offset}}
54cfded0
AM
4727Same as @code{.cfi_def_cfa_offset} but @var{offset} is a relative
4728value that is added/substracted from the previous offset.
4729
d3b47e2b 4730@subsection @code{.cfi_offset @var{register}, @var{offset}}
54cfded0 4731Previous value of @var{register} is saved at offset @var{offset} from
01642c12 4732CFA.
54cfded0 4733
d3b47e2b 4734@subsection @code{.cfi_rel_offset @var{register}, @var{offset}}
17076204
RH
4735Previous value of @var{register} is saved at offset @var{offset} from
4736the current CFA register. This is transformed to @code{.cfi_offset}
4737using the known displacement of the CFA register from the CFA.
4738This is often easier to use, because the number will match the
4739code it's annotating.
54cfded0 4740
d3b47e2b 4741@subsection @code{.cfi_register @var{register1}, @var{register2}}
4b7d318b
L
4742Previous value of @var{register1} is saved in register @var{register2}.
4743
d3b47e2b 4744@subsection @code{.cfi_restore @var{register}}
01642c12
RM
4745@code{.cfi_restore} says that the rule for @var{register} is now the
4746same as it was at the beginning of the function, after all initial
4b7d318b
L
4747instruction added by @code{.cfi_startproc} were executed.
4748
d3b47e2b 4749@subsection @code{.cfi_undefined @var{register}}
4b7d318b
L
4750From now on the previous value of @var{register} can't be restored anymore.
4751
d3b47e2b 4752@subsection @code{.cfi_same_value @var{register}}
01642c12 4753Current value of @var{register} is the same like in the previous frame,
4b7d318b
L
4754i.e. no restoration needed.
4755
d3b47e2b 4756@subsection @code{.cfi_remember_state},
01642c12
RM
4757First save all current rules for all registers by @code{.cfi_remember_state},
4758then totally screw them up by subsequent @code{.cfi_*} directives and when
4759everything is hopelessly bad, use @code{.cfi_restore_state} to restore
4b7d318b
L
4760the previous saved state.
4761
d3b47e2b 4762@subsection @code{.cfi_return_column @var{register}}
01642c12 4763Change return column @var{register}, i.e. the return address is either
4b7d318b
L
4764directly in @var{register} or can be accessed by rules for @var{register}.
4765
d3b47e2b 4766@subsection @code{.cfi_signal_frame}
63752a75
JJ
4767Mark current function as signal trampoline.
4768
d3b47e2b 4769@subsection @code{.cfi_window_save}
364b6d8b
JJ
4770SPARC register window has been saved.
4771
d3b47e2b 4772@subsection @code{.cfi_escape} @var{expression}[, @dots{}]
cdfbf930
RH
4773Allows the user to add arbitrary bytes to the unwind info. One
4774might use this to add OS-specific CFI opcodes, or generic CFI
4775opcodes that GAS does not yet support.
252b5132 4776
d3b47e2b 4777@subsection @code{.cfi_val_encoded_addr @var{register}, @var{encoding}, @var{label}}
f1c4cc75
RH
4778The current value of @var{register} is @var{label}. The value of @var{label}
4779will be encoded in the output file according to @var{encoding}; see the
4780description of @code{.cfi_personality} for details on this encoding.
4781
4782The usefulness of equating a register to a fixed label is probably
4783limited to the return address register. Here, it can be useful to
4784mark a code segment that has only one return address which is reached
4785by a direct branch and no copy of the return address exists in memory
4786or another register.
4787
ccf8a69b
BW
4788@node Comm
4789@section @code{.comm @var{symbol} , @var{length} }
bd0eb99b 4790
ccf8a69b
BW
4791@cindex @code{comm} directive
4792@cindex symbol, common
4793@code{.comm} declares a common symbol named @var{symbol}. When linking, a
4794common symbol in one object file may be merged with a defined or common symbol
4795of the same name in another object file. If @code{@value{LD}} does not see a
4796definition for the symbol--just one or more common symbols--then it will
4797allocate @var{length} bytes of uninitialized memory. @var{length} must be an
4798absolute expression. If @code{@value{LD}} sees multiple common symbols with
4799the same name, and they do not all have the same size, it will allocate space
4800using the largest size.
07a53e5c 4801
c1711530
DK
4802@ifset COFF-ELF
4803When using ELF or (as a GNU extension) PE, the @code{.comm} directive takes
01642c12 4804an optional third argument. This is the desired alignment of the symbol,
c1711530
DK
4805specified for ELF as a byte boundary (for example, an alignment of 16 means
4806that the least significant 4 bits of the address should be zero), and for PE
4807as a power of two (for example, an alignment of 5 means aligned to a 32-byte
01642c12 4808boundary). The alignment must be an absolute expression, and it must be a
c1711530 4809power of two. If @code{@value{LD}} allocates uninitialized memory for the
01642c12 4810common symbol, it will use the alignment when placing the symbol. If no
c1711530 4811alignment is specified, @command{@value{AS}} will set the alignment to the
ccf8a69b 4812largest power of two less than or equal to the size of the symbol, up to a
c1711530
DK
4813maximum of 16 on ELF, or the default section alignment of 4 on PE@footnote{This
4814is not the same as the executable image file alignment controlled by @code{@value{LD}}'s
4815@samp{--section-alignment} option; image file sections in PE are aligned to
4816multiples of 4096, which is far too large an alignment for ordinary variables.
4817It is rather the default alignment for (non-debug) sections within object
4818(@samp{*.o}) files, which are less strictly aligned.}.
ccf8a69b 4819@end ifset
cd1fcb49 4820
ccf8a69b
BW
4821@ifset HPPA
4822The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
4823@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
4824@end ifset
07a53e5c 4825
252b5132
RH
4826@node Data
4827@section @code{.data @var{subsection}}
4828
4829@cindex @code{data} directive
a4fb0134 4830@code{.data} tells @command{@value{AS}} to assemble the following statements onto the
252b5132
RH
4831end of the data subsection numbered @var{subsection} (which is an
4832absolute expression). If @var{subsection} is omitted, it defaults
4833to zero.
4834
4835@ifset COFF
4836@node Def
4837@section @code{.def @var{name}}
4838
4839@cindex @code{def} directive
4840@cindex COFF symbols, debugging
4841@cindex debugging COFF symbols
4842Begin defining debugging information for a symbol @var{name}; the
4843definition extends until the @code{.endef} directive is encountered.
4844@ifset BOUT
4845
a4fb0134 4846This directive is only observed when @command{@value{AS}} is configured for COFF
252b5132
RH
4847format output; when producing @code{b.out}, @samp{.def} is recognized,
4848but ignored.
4849@end ifset
4850@end ifset
4851
4852@ifset aout-bout
4853@node Desc
4854@section @code{.desc @var{symbol}, @var{abs-expression}}
4855
4856@cindex @code{desc} directive
4857@cindex COFF symbol descriptor
4858@cindex symbol descriptor, COFF
4859This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
4860to the low 16 bits of an absolute expression.
4861
4862@ifset COFF
a4fb0134 4863The @samp{.desc} directive is not available when @command{@value{AS}} is
252b5132 4864configured for COFF output; it is only for @code{a.out} or @code{b.out}
a4fb0134 4865object format. For the sake of compatibility, @command{@value{AS}} accepts
252b5132
RH
4866it, but produces no output, when configured for COFF.
4867@end ifset
4868@end ifset
4869
4870@ifset COFF
4871@node Dim
4872@section @code{.dim}
4873
4874@cindex @code{dim} directive
4875@cindex COFF auxiliary symbol information
4876@cindex auxiliary symbol information, COFF
4877This directive is generated by compilers to include auxiliary debugging
4878information in the symbol table. It is only permitted inside
4879@code{.def}/@code{.endef} pairs.
4880@ifset BOUT
4881
4882@samp{.dim} is only meaningful when generating COFF format output; when
a4fb0134 4883@command{@value{AS}} is generating @code{b.out}, it accepts this directive but
252b5132
RH
4884ignores it.
4885@end ifset
4886@end ifset
4887
4888@node Double
4889@section @code{.double @var{flonums}}
4890
4891@cindex @code{double} directive
4892@cindex floating point numbers (double)
4893@code{.double} expects zero or more flonums, separated by commas. It
4894assembles floating point numbers.
4895@ifset GENERIC
4896The exact kind of floating point numbers emitted depends on how
a4fb0134 4897@command{@value{AS}} is configured. @xref{Machine Dependencies}.
252b5132
RH
4898@end ifset
4899@ifclear GENERIC
4900@ifset IEEEFLOAT
4901On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
4902in @sc{ieee} format.
4903@end ifset
4904@end ifclear
4905
4906@node Eject
4907@section @code{.eject}
4908
4909@cindex @code{eject} directive
4910@cindex new page, in listings
4911@cindex page, in listings
4912@cindex listing control: new page
4913Force a page break at this point, when generating assembly listings.
4914
4915@node Else
4916@section @code{.else}
4917
4918@cindex @code{else} directive
a4fb0134 4919@code{.else} is part of the @command{@value{AS}} support for conditional
96e9638b 4920assembly; see @ref{If,,@code{.if}}. It marks the beginning of a section
252b5132
RH
4921of code to be assembled if the condition for the preceding @code{.if}
4922was false.
4923
3fd9f047
TW
4924@node Elseif
4925@section @code{.elseif}
4926
4927@cindex @code{elseif} directive
a4fb0134 4928@code{.elseif} is part of the @command{@value{AS}} support for conditional
96e9638b 4929assembly; see @ref{If,,@code{.if}}. It is shorthand for beginning a new
3fd9f047
TW
4930@code{.if} block that would otherwise fill the entire @code{.else} section.
4931
252b5132
RH
4932@node End
4933@section @code{.end}
4934
4935@cindex @code{end} directive
a4fb0134 4936@code{.end} marks the end of the assembly file. @command{@value{AS}} does not
252b5132
RH
4937process anything in the file past the @code{.end} directive.
4938
4939@ifset COFF
4940@node Endef
4941@section @code{.endef}
4942
4943@cindex @code{endef} directive
4944This directive flags the end of a symbol definition begun with
4945@code{.def}.
4946@ifset BOUT
4947
4948@samp{.endef} is only meaningful when generating COFF format output; if
a4fb0134 4949@command{@value{AS}} is configured to generate @code{b.out}, it accepts this
252b5132
RH
4950directive but ignores it.
4951@end ifset
4952@end ifset
4953
4954@node Endfunc
4955@section @code{.endfunc}
4956@cindex @code{endfunc} directive
4957@code{.endfunc} marks the end of a function specified with @code{.func}.
4958
4959@node Endif
4960@section @code{.endif}
4961
4962@cindex @code{endif} directive
a4fb0134 4963@code{.endif} is part of the @command{@value{AS}} support for conditional assembly;
252b5132
RH
4964it marks the end of a block of code that is only assembled
4965conditionally. @xref{If,,@code{.if}}.
4966
4967@node Equ
4968@section @code{.equ @var{symbol}, @var{expression}}
4969
4970@cindex @code{equ} directive
4971@cindex assigning values to symbols
4972@cindex symbols, assigning values to
4973This directive sets the value of @var{symbol} to @var{expression}.
96e9638b 4974It is synonymous with @samp{.set}; see @ref{Set,,@code{.set}}.
252b5132
RH
4975
4976@ifset HPPA
01642c12 4977The syntax for @code{equ} on the HPPA is
252b5132
RH
4978@samp{@var{symbol} .equ @var{expression}}.
4979@end ifset
4980
3c9b82ba 4981@ifset Z80
01642c12
RM
4982The syntax for @code{equ} on the Z80 is
4983@samp{@var{symbol} equ @var{expression}}.
3c9b82ba 4984On the Z80 it is an eror if @var{symbol} is already defined,
01642c12 4985but the symbol is not protected from later redefinition.
96e9638b 4986Compare @ref{Equiv}.
3c9b82ba
NC
4987@end ifset
4988
252b5132
RH
4989@node Equiv
4990@section @code{.equiv @var{symbol}, @var{expression}}
4991@cindex @code{equiv} directive
4992The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that
8dfa0188
NC
4993the assembler will signal an error if @var{symbol} is already defined. Note a
4994symbol which has been referenced but not actually defined is considered to be
4995undefined.
252b5132 4996
01642c12 4997Except for the contents of the error message, this is roughly equivalent to
252b5132
RH
4998@smallexample
4999.ifdef SYM
5000.err
5001.endif
5002.equ SYM,VAL
5003@end smallexample
9497f5ac
NC
5004plus it protects the symbol from later redefinition.
5005
5006@node Eqv
5007@section @code{.eqv @var{symbol}, @var{expression}}
5008@cindex @code{eqv} directive
5009The @code{.eqv} directive is like @code{.equiv}, but no attempt is made to
5010evaluate the expression or any part of it immediately. Instead each time
5011the resulting symbol is used in an expression, a snapshot of its current
5012value is taken.
252b5132
RH
5013
5014@node Err
5015@section @code{.err}
5016@cindex @code{err} directive
a4fb0134
SC
5017If @command{@value{AS}} assembles a @code{.err} directive, it will print an error
5018message and, unless the @option{-Z} option was used, it will not generate an
f9eb6721 5019object file. This can be used to signal an error in conditionally compiled code.
252b5132 5020
d190d046
HPN
5021@node Error
5022@section @code{.error "@var{string}"}
5023@cindex error directive
5024
5025Similarly to @code{.err}, this directive emits an error, but you can specify a
5026string that will be emitted as the error message. If you don't specify the
5027message, it defaults to @code{".error directive invoked in source file"}.
5028@xref{Errors, ,Error and Warning Messages}.
5029
5030@smallexample
5031 .error "This code has not been assembled and tested."
5032@end smallexample
5033
252b5132
RH
5034@node Exitm
5035@section @code{.exitm}
5036Exit early from the current macro definition. @xref{Macro}.
5037
5038@node Extern
5039@section @code{.extern}
5040
5041@cindex @code{extern} directive
5042@code{.extern} is accepted in the source program---for compatibility
a4fb0134 5043with other assemblers---but it is ignored. @command{@value{AS}} treats
252b5132
RH
5044all undefined symbols as external.
5045
5046@node Fail
5047@section @code{.fail @var{expression}}
5048
5049@cindex @code{fail} directive
5050Generates an error or a warning. If the value of the @var{expression} is 500
a4fb0134
SC
5051or more, @command{@value{AS}} will print a warning message. If the value is less
5052than 500, @command{@value{AS}} will print an error message. The message will
252b5132
RH
5053include the value of @var{expression}. This can occasionally be useful inside
5054complex nested macros or conditional assembly.
5055
252b5132 5056@node File
14082c76 5057@section @code{.file}
252b5132 5058@cindex @code{file} directive
14082c76
BW
5059
5060@ifclear no-file-dir
5061There are two different versions of the @code{.file} directive. Targets
5062that support DWARF2 line number information use the DWARF2 version of
5063@code{.file}. Other targets use the default version.
5064
5065@subheading Default Version
5066
252b5132
RH
5067@cindex logical file name
5068@cindex file name, logical
14082c76
BW
5069This version of the @code{.file} directive tells @command{@value{AS}} that we
5070are about to start a new logical file. The syntax is:
5071
5072@smallexample
5073.file @var{string}
5074@end smallexample
5075
5076@var{string} is the new file name. In general, the filename is
252b5132
RH
5077recognized whether or not it is surrounded by quotes @samp{"}; but if you wish
5078to specify an empty file name, you must give the quotes--@code{""}. This
5079statement may go away in future: it is only recognized to be compatible with
a4fb0134 5080old @command{@value{AS}} programs.
14082c76
BW
5081
5082@subheading DWARF2 Version
252b5132
RH
5083@end ifclear
5084
14082c76
BW
5085When emitting DWARF2 line number information, @code{.file} assigns filenames
5086to the @code{.debug_line} file name table. The syntax is:
5087
5088@smallexample
5089.file @var{fileno} @var{filename}
5090@end smallexample
5091
5092The @var{fileno} operand should be a unique positive integer to use as the
5093index of the entry in the table. The @var{filename} operand is a C string
5094literal.
5095
5096The detail of filename indices is exposed to the user because the filename
5097table is shared with the @code{.debug_info} section of the DWARF2 debugging
5098information, and thus the user must know the exact indices that table
5099entries will have.
5100
252b5132
RH
5101@node Fill
5102@section @code{.fill @var{repeat} , @var{size} , @var{value}}
5103
5104@cindex @code{fill} directive
5105@cindex writing patterns in memory
5106@cindex patterns, writing in memory
bc64be0c 5107@var{repeat}, @var{size} and @var{value} are absolute expressions.
252b5132
RH
5108This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
5109may be zero or more. @var{Size} may be zero or more, but if it is
5110more than 8, then it is deemed to have the value 8, compatible with
5111other people's assemblers. The contents of each @var{repeat} bytes
5112is taken from an 8-byte number. The highest order 4 bytes are
5113zero. The lowest order 4 bytes are @var{value} rendered in the
a4fb0134 5114byte-order of an integer on the computer @command{@value{AS}} is assembling for.
252b5132
RH
5115Each @var{size} bytes in a repetition is taken from the lowest order
5116@var{size} bytes of this number. Again, this bizarre behavior is
5117compatible with other people's assemblers.
5118
5119@var{size} and @var{value} are optional.
5120If the second comma and @var{value} are absent, @var{value} is
5121assumed zero. If the first comma and following tokens are absent,
5122@var{size} is assumed to be 1.
5123
5124@node Float
5125@section @code{.float @var{flonums}}
5126
5127@cindex floating point numbers (single)
5128@cindex @code{float} directive
5129This directive assembles zero or more flonums, separated by commas. It
5130has the same effect as @code{.single}.
5131@ifset GENERIC
5132The exact kind of floating point numbers emitted depends on how
a4fb0134 5133@command{@value{AS}} is configured.
252b5132
RH
5134@xref{Machine Dependencies}.
5135@end ifset
5136@ifclear GENERIC
5137@ifset IEEEFLOAT
5138On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
5139in @sc{ieee} format.
5140@end ifset
5141@end ifclear
5142
5143@node Func
5144@section @code{.func @var{name}[,@var{label}]}
5145@cindex @code{func} directive
5146@code{.func} emits debugging information to denote function @var{name}, and
5147is ignored unless the file is assembled with debugging enabled.
05da4302 5148Only @samp{--gstabs[+]} is currently supported.
252b5132
RH
5149@var{label} is the entry point of the function and if omitted @var{name}
5150prepended with the @samp{leading char} is used.
5151@samp{leading char} is usually @code{_} or nothing, depending on the target.
5152All functions are currently defined to have @code{void} return type.
5153The function must be terminated with @code{.endfunc}.
5154
5155@node Global
5156@section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
5157
5158@cindex @code{global} directive
5159@cindex symbol, making visible to linker
5160@code{.global} makes the symbol visible to @code{@value{LD}}. If you define
5161@var{symbol} in your partial program, its value is made available to
5162other partial programs that are linked with it. Otherwise,
5163@var{symbol} takes its attributes from a symbol of the same name
5164from another file linked into the same program.
5165
5166Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
5167compatibility with other assemblers.
5168
5169@ifset HPPA
5170On the HPPA, @code{.global} is not always enough to make it accessible to other
5171partial programs. You may need the HPPA-only @code{.EXPORT} directive as well.
96e9638b 5172@xref{HPPA Directives, ,HPPA Assembler Directives}.
252b5132
RH
5173@end ifset
5174
c91d2e08 5175@ifset ELF
3a99f02f
DJ
5176@node Gnu_attribute
5177@section @code{.gnu_attribute @var{tag},@var{value}}
5178Record a @sc{gnu} object attribute for this file. @xref{Object Attributes}.
5179
c91d2e08
NC
5180@node Hidden
5181@section @code{.hidden @var{names}}
5182
c1253627
NC
5183@cindex @code{hidden} directive
5184@cindex visibility
ed9589d4 5185This is one of the ELF visibility directives. The other two are
01642c12 5186@code{.internal} (@pxref{Internal,,@code{.internal}}) and
a349d9dd 5187@code{.protected} (@pxref{Protected,,@code{.protected}}).
c91d2e08
NC
5188
5189This directive overrides the named symbols default visibility (which is set by
5190their binding: local, global or weak). The directive sets the visibility to
5191@code{hidden} which means that the symbols are not visible to other components.
01642c12 5192Such symbols are always considered to be @code{protected} as well.
c91d2e08
NC
5193@end ifset
5194
252b5132
RH
5195@node hword
5196@section @code{.hword @var{expressions}}
5197
5198@cindex @code{hword} directive
5199@cindex integers, 16-bit
5200@cindex numbers, 16-bit
5201@cindex sixteen bit integers
5202This expects zero or more @var{expressions}, and emits
5203a 16 bit number for each.
5204
5205@ifset GENERIC
5206This directive is a synonym for @samp{.short}; depending on the target
5207architecture, it may also be a synonym for @samp{.word}.
5208@end ifset
5209@ifclear GENERIC
5210@ifset W32
5211This directive is a synonym for @samp{.short}.
5212@end ifset
5213@ifset W16
5214This directive is a synonym for both @samp{.short} and @samp{.word}.
5215@end ifset
5216@end ifclear
5217
5218@node Ident
5219@section @code{.ident}
5220
5221@cindex @code{ident} directive
cb4c78d6
BE
5222
5223This directive is used by some assemblers to place tags in object files. The
5224behavior of this directive varies depending on the target. When using the
5225a.out object file format, @command{@value{AS}} simply accepts the directive for
5226source-file compatibility with existing assemblers, but does not emit anything
5227for it. When using COFF, comments are emitted to the @code{.comment} or
5228@code{.rdata} section, depending on the target. When using ELF, comments are
5229emitted to the @code{.comment} section.
252b5132
RH
5230
5231@node If
5232@section @code{.if @var{absolute expression}}
5233
5234@cindex conditional assembly
5235@cindex @code{if} directive
5236@code{.if} marks the beginning of a section of code which is only
5237considered part of the source program being assembled if the argument
5238(which must be an @var{absolute expression}) is non-zero. The end of
5239the conditional section of code must be marked by @code{.endif}
5240(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
5241alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}).
3fd9f047
TW
5242If you have several conditions to check, @code{.elseif} may be used to avoid
5243nesting blocks if/else within each subsequent @code{.else} block.
252b5132
RH
5244
5245The following variants of @code{.if} are also supported:
5246@table @code
5247@cindex @code{ifdef} directive
5248@item .ifdef @var{symbol}
5249Assembles the following section of code if the specified @var{symbol}
8dfa0188
NC
5250has been defined. Note a symbol which has been referenced but not yet defined
5251is considered to be undefined.
252b5132 5252
26aca5f6
JB
5253@cindex @code{ifb} directive
5254@item .ifb @var{text}
5255Assembles the following section of code if the operand is blank (empty).
5256
252b5132
RH
5257@cindex @code{ifc} directive
5258@item .ifc @var{string1},@var{string2}
5259Assembles the following section of code if the two strings are the same. The
5260strings may be optionally quoted with single quotes. If they are not quoted,
5261the first string stops at the first comma, and the second string stops at the
5262end of the line. Strings which contain whitespace should be quoted. The
5263string comparison is case sensitive.
5264
5265@cindex @code{ifeq} directive
5266@item .ifeq @var{absolute expression}
5267Assembles the following section of code if the argument is zero.
5268
5269@cindex @code{ifeqs} directive
5270@item .ifeqs @var{string1},@var{string2}
5271Another form of @code{.ifc}. The strings must be quoted using double quotes.
5272
5273@cindex @code{ifge} directive
5274@item .ifge @var{absolute expression}
5275Assembles the following section of code if the argument is greater than or
5276equal to zero.
5277
5278@cindex @code{ifgt} directive
5279@item .ifgt @var{absolute expression}
5280Assembles the following section of code if the argument is greater than zero.
5281
5282@cindex @code{ifle} directive
5283@item .ifle @var{absolute expression}
5284Assembles the following section of code if the argument is less than or equal
5285to zero.
5286
5287@cindex @code{iflt} directive
5288@item .iflt @var{absolute expression}
5289Assembles the following section of code if the argument is less than zero.
5290
26aca5f6
JB
5291@cindex @code{ifnb} directive
5292@item .ifnb @var{text}
5293Like @code{.ifb}, but the sense of the test is reversed: this assembles the
5294following section of code if the operand is non-blank (non-empty).
5295
252b5132
RH
5296@cindex @code{ifnc} directive
5297@item .ifnc @var{string1},@var{string2}.
5298Like @code{.ifc}, but the sense of the test is reversed: this assembles the
5299following section of code if the two strings are not the same.
5300
5301@cindex @code{ifndef} directive
5302@cindex @code{ifnotdef} directive
5303@item .ifndef @var{symbol}
5304@itemx .ifnotdef @var{symbol}
5305Assembles the following section of code if the specified @var{symbol}
8dfa0188
NC
5306has not been defined. Both spelling variants are equivalent. Note a symbol
5307which has been referenced but not yet defined is considered to be undefined.
252b5132
RH
5308
5309@cindex @code{ifne} directive
5310@item .ifne @var{absolute expression}
5311Assembles the following section of code if the argument is not equal to zero
5312(in other words, this is equivalent to @code{.if}).
5313
5314@cindex @code{ifnes} directive
5315@item .ifnes @var{string1},@var{string2}
5316Like @code{.ifeqs}, but the sense of the test is reversed: this assembles the
5317following section of code if the two strings are not the same.
5318@end table
5319
7e005732
NC
5320@node Incbin
5321@section @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]}
5322
5323@cindex @code{incbin} directive
5324@cindex binary files, including
5325The @code{incbin} directive includes @var{file} verbatim at the current
5326location. You can control the search paths used with the @samp{-I} command-line
5327option (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
5328around @var{file}.
5329
5330The @var{skip} argument skips a number of bytes from the start of the
5331@var{file}. The @var{count} argument indicates the maximum number of bytes to
15dcfbc3
NC
5332read. Note that the data is not aligned in any way, so it is the user's
5333responsibility to make sure that proper alignment is provided both before and
5334after the @code{incbin} directive.
7e005732 5335
252b5132
RH
5336@node Include
5337@section @code{.include "@var{file}"}
5338
5339@cindex @code{include} directive
5340@cindex supporting files, including
5341@cindex files, including
5342This directive provides a way to include supporting files at specified
5343points in your source program. The code from @var{file} is assembled as
5344if it followed the point of the @code{.include}; when the end of the
5345included file is reached, assembly of the original file continues. You
5346can control the search paths used with the @samp{-I} command-line option
5347(@pxref{Invoking,,Command-Line Options}). Quotation marks are required
5348around @var{file}.
5349
5350@node Int
5351@section @code{.int @var{expressions}}
5352
5353@cindex @code{int} directive
5354@cindex integers, 32-bit
5355Expect zero or more @var{expressions}, of any section, separated by commas.
5356For each expression, emit a number that, at run time, is the value of that
5357expression. The byte order and bit size of the number depends on what kind
5358of target the assembly is for.
5359
5360@ifclear GENERIC
5361@ifset H8
7be1c489 5362On most forms of the H8/300, @code{.int} emits 16-bit
c2dcd04e 5363integers. On the H8/300H and the Renesas SH, however, @code{.int} emits
252b5132
RH
536432-bit integers.
5365@end ifset
5366@end ifclear
5367
c91d2e08
NC
5368@ifset ELF
5369@node Internal
5370@section @code{.internal @var{names}}
5371
c1253627
NC
5372@cindex @code{internal} directive
5373@cindex visibility
ed9589d4 5374This is one of the ELF visibility directives. The other two are
01642c12 5375@code{.hidden} (@pxref{Hidden,,@code{.hidden}}) and
a349d9dd 5376@code{.protected} (@pxref{Protected,,@code{.protected}}).
c91d2e08
NC
5377
5378This directive overrides the named symbols default visibility (which is set by
5379their binding: local, global or weak). The directive sets the visibility to
5380@code{internal} which means that the symbols are considered to be @code{hidden}
c1253627 5381(i.e., not visible to other components), and that some extra, processor specific
c91d2e08
NC
5382processing must also be performed upon the symbols as well.
5383@end ifset
5384
252b5132
RH
5385@node Irp
5386@section @code{.irp @var{symbol},@var{values}}@dots{}
5387
5388@cindex @code{irp} directive
5389Evaluate a sequence of statements assigning different values to @var{symbol}.
5390The sequence of statements starts at the @code{.irp} directive, and is
5391terminated by an @code{.endr} directive. For each @var{value}, @var{symbol} is
5392set to @var{value}, and the sequence of statements is assembled. If no
5393@var{value} is listed, the sequence of statements is assembled once, with
5394@var{symbol} set to the null string. To refer to @var{symbol} within the
5395sequence of statements, use @var{\symbol}.
5396
5397For example, assembling
5398
5399@example
5400 .irp param,1,2,3
5401 move d\param,sp@@-
5402 .endr
5403@end example
5404
5405is equivalent to assembling
5406
5407@example
5408 move d1,sp@@-
5409 move d2,sp@@-
5410 move d3,sp@@-
5411@end example
5412
96e9638b 5413For some caveats with the spelling of @var{symbol}, see also @ref{Macro}.
5e75c3ab 5414
252b5132
RH
5415@node Irpc
5416@section @code{.irpc @var{symbol},@var{values}}@dots{}
5417
5418@cindex @code{irpc} directive
5419Evaluate a sequence of statements assigning different values to @var{symbol}.
5420The sequence of statements starts at the @code{.irpc} directive, and is
5421terminated by an @code{.endr} directive. For each character in @var{value},
5422@var{symbol} is set to the character, and the sequence of statements is
5423assembled. If no @var{value} is listed, the sequence of statements is
5424assembled once, with @var{symbol} set to the null string. To refer to
5425@var{symbol} within the sequence of statements, use @var{\symbol}.
5426
5427For example, assembling
5428
5429@example
5430 .irpc param,123
5431 move d\param,sp@@-
5432 .endr
5433@end example
5434
5435is equivalent to assembling
5436
5437@example
5438 move d1,sp@@-
5439 move d2,sp@@-
5440 move d3,sp@@-
5441@end example
5442
5e75c3ab
JB
5443For some caveats with the spelling of @var{symbol}, see also the discussion
5444at @xref{Macro}.
5445
252b5132
RH
5446@node Lcomm
5447@section @code{.lcomm @var{symbol} , @var{length}}
5448
5449@cindex @code{lcomm} directive
5450@cindex local common symbols
5451@cindex symbols, local common
5452Reserve @var{length} (an absolute expression) bytes for a local common
5453denoted by @var{symbol}. The section and value of @var{symbol} are
5454those of the new local common. The addresses are allocated in the bss
5455section, so that at run-time the bytes start off zeroed. @var{Symbol}
5456is not declared global (@pxref{Global,,@code{.global}}), so is normally
5457not visible to @code{@value{LD}}.
5458
5459@ifset GENERIC
5460Some targets permit a third argument to be used with @code{.lcomm}. This
5461argument specifies the desired alignment of the symbol in the bss section.
5462@end ifset
5463
5464@ifset HPPA
5465The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
5466@samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
5467@end ifset
5468
5469@node Lflags
5470@section @code{.lflags}
5471
5472@cindex @code{lflags} directive (ignored)
a4fb0134 5473@command{@value{AS}} accepts this directive, for compatibility with other
252b5132
RH
5474assemblers, but ignores it.
5475
5476@ifclear no-line-dir
5477@node Line
5478@section @code{.line @var{line-number}}
5479
5480@cindex @code{line} directive
252b5132
RH
5481@cindex logical line number
5482@ifset aout-bout
5483Change the logical line number. @var{line-number} must be an absolute
5484expression. The next line has that logical line number. Therefore any other
5485statements on the current line (after a statement separator character) are
5486reported as on logical line number @var{line-number} @minus{} 1. One day
a4fb0134 5487@command{@value{AS}} will no longer support this directive: it is recognized only
252b5132 5488for compatibility with existing assembler programs.
252b5132
RH
5489@end ifset
5490
252b5132 5491Even though this is a directive associated with the @code{a.out} or
a4fb0134 5492@code{b.out} object-code formats, @command{@value{AS}} still recognizes it
252b5132
RH
5493when producing COFF output, and treats @samp{.line} as though it
5494were the COFF @samp{.ln} @emph{if} it is found outside a
5495@code{.def}/@code{.endef} pair.
5496
5497Inside a @code{.def}, @samp{.line} is, instead, one of the directives
5498used by compilers to generate auxiliary symbol information for
5499debugging.
5500@end ifclear
5501
5502@node Linkonce
5503@section @code{.linkonce [@var{type}]}
5504@cindex COMDAT
5505@cindex @code{linkonce} directive
5506@cindex common sections
5507Mark the current section so that the linker only includes a single copy of it.
5508This may be used to include the same section in several different object files,
5509but ensure that the linker will only include it once in the final output file.
5510The @code{.linkonce} pseudo-op must be used for each instance of the section.
5511Duplicate sections are detected based on the section name, so it should be
5512unique.
5513
5514This directive is only supported by a few object file formats; as of this
5515writing, the only object file format which supports it is the Portable
5516Executable format used on Windows NT.
5517
5518The @var{type} argument is optional. If specified, it must be one of the
5519following strings. For example:
5520@smallexample
5521.linkonce same_size
5522@end smallexample
5523Not all types may be supported on all object file formats.
5524
5525@table @code
5526@item discard
5527Silently discard duplicate sections. This is the default.
5528
5529@item one_only
5530Warn if there are duplicate sections, but still keep only one copy.
5531
5532@item same_size
5533Warn if any of the duplicates have different sizes.
5534
5535@item same_contents
5536Warn if any of the duplicates do not have exactly the same contents.
5537@end table
5538
ccf8a69b
BW
5539@node List
5540@section @code{.list}
5541
5542@cindex @code{list} directive
5543@cindex listing control, turning on
5544Control (in conjunction with the @code{.nolist} directive) whether or
5545not assembly listings are generated. These two directives maintain an
5546internal counter (which is zero initially). @code{.list} increments the
5547counter, and @code{.nolist} decrements it. Assembly listings are
5548generated whenever the counter is greater than zero.
5549
5550By default, listings are disabled. When you enable them (with the
5551@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
5552the initial value of the listing counter is one.
5553
252b5132
RH
5554@node Ln
5555@section @code{.ln @var{line-number}}
5556
5557@cindex @code{ln} directive
5558@ifclear no-line-dir
5559@samp{.ln} is a synonym for @samp{.line}.
5560@end ifclear
5561@ifset no-line-dir
a4fb0134 5562Tell @command{@value{AS}} to change the logical line number. @var{line-number}
252b5132
RH
5563must be an absolute expression. The next line has that logical
5564line number, so any other statements on the current line (after a
5565statement separator character @code{;}) are reported as on logical
5566line number @var{line-number} @minus{} 1.
5567@ifset BOUT
5568
a4fb0134 5569This directive is accepted, but ignored, when @command{@value{AS}} is
252b5132
RH
5570configured for @code{b.out}; its effect is only associated with COFF
5571output format.
5572@end ifset
5573@end ifset
5574
ccf8a69b
BW
5575@node Loc
5576@section @code{.loc @var{fileno} @var{lineno} [@var{column}] [@var{options}]}
5577@cindex @code{loc} directive
5578When emitting DWARF2 line number information,
5579the @code{.loc} directive will add a row to the @code{.debug_line} line
5580number matrix corresponding to the immediately following assembly
5581instruction. The @var{fileno}, @var{lineno}, and optional @var{column}
5582arguments will be applied to the @code{.debug_line} state machine before
5583the row is added.
252b5132 5584
ccf8a69b
BW
5585The @var{options} are a sequence of the following tokens in any order:
5586
5587@table @code
5588@item basic_block
5589This option will set the @code{basic_block} register in the
5590@code{.debug_line} state machine to @code{true}.
5591
5592@item prologue_end
5593This option will set the @code{prologue_end} register in the
5594@code{.debug_line} state machine to @code{true}.
5595
5596@item epilogue_begin
5597This option will set the @code{epilogue_begin} register in the
5598@code{.debug_line} state machine to @code{true}.
5599
5600@item is_stmt @var{value}
5601This option will set the @code{is_stmt} register in the
01642c12 5602@code{.debug_line} state machine to @code{value}, which must be
ccf8a69b
BW
5603either 0 or 1.
5604
5605@item isa @var{value}
5606This directive will set the @code{isa} register in the @code{.debug_line}
5607state machine to @var{value}, which must be an unsigned integer.
5608
92846e72
CC
5609@item discriminator @var{value}
5610This directive will set the @code{discriminator} register in the @code{.debug_line}
5611state machine to @var{value}, which must be an unsigned integer.
5612
ccf8a69b
BW
5613@end table
5614
5615@node Loc_mark_labels
5616@section @code{.loc_mark_labels @var{enable}}
5617@cindex @code{loc_mark_labels} directive
5618When emitting DWARF2 line number information,
5619the @code{.loc_mark_labels} directive makes the assembler emit an entry
5620to the @code{.debug_line} line number matrix with the @code{basic_block}
5621register in the state machine set whenever a code label is seen.
5622The @var{enable} argument should be either 1 or 0, to enable or disable
5623this function respectively.
252b5132 5624
4d4175af
BW
5625@ifset ELF
5626@node Local
5627@section @code{.local @var{names}}
5628
5629@cindex @code{local} directive
5630This directive, which is available for ELF targets, marks each symbol in
5631the comma-separated list of @code{names} as a local symbol so that it
5632will not be externally visible. If the symbols do not already exist,
5633they will be created.
5634
5635For targets where the @code{.lcomm} directive (@pxref{Lcomm}) does not
5636accept an alignment argument, which is the case for most ELF targets,
5637the @code{.local} directive can be used in combination with @code{.comm}
5638(@pxref{Comm}) to define aligned local common data.
5639@end ifset
5640
252b5132
RH
5641@node Long
5642@section @code{.long @var{expressions}}
5643
5644@cindex @code{long} directive
96e9638b 5645@code{.long} is the same as @samp{.int}. @xref{Int,,@code{.int}}.
252b5132
RH
5646
5647@ignore
5648@c no one seems to know what this is for or whether this description is
5649@c what it really ought to do
5650@node Lsym
5651@section @code{.lsym @var{symbol}, @var{expression}}
5652
5653@cindex @code{lsym} directive
5654@cindex symbol, not referenced in assembly
5655@code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
5656the hash table, ensuring it cannot be referenced by name during the
5657rest of the assembly. This sets the attributes of the symbol to be
5658the same as the expression value:
5659@smallexample
5660@var{other} = @var{descriptor} = 0
5661@var{type} = @r{(section of @var{expression})}
5662@var{value} = @var{expression}
5663@end smallexample
5664@noindent
5665The new symbol is not flagged as external.
5666@end ignore
5667
5668@node Macro
5669@section @code{.macro}
5670
5671@cindex macros
5672The commands @code{.macro} and @code{.endm} allow you to define macros that
5673generate assembly output. For example, this definition specifies a macro
5674@code{sum} that puts a sequence of numbers into memory:
5675
5676@example
5677 .macro sum from=0, to=5
5678 .long \from
5679 .if \to-\from
5680 sum "(\from+1)",\to
5681 .endif
5682 .endm
5683@end example
5684
5685@noindent
5686With that definition, @samp{SUM 0,5} is equivalent to this assembly input:
5687
5688@example
5689 .long 0
5690 .long 1
5691 .long 2
5692 .long 3
5693 .long 4
5694 .long 5
5695@end example
5696
5697@ftable @code
5698@item .macro @var{macname}
5699@itemx .macro @var{macname} @var{macargs} @dots{}
5700@cindex @code{macro} directive
5701Begin the definition of a macro called @var{macname}. If your macro
5702definition requires arguments, specify their names after the macro name,
6eaeac8a
JB
5703separated by commas or spaces. You can qualify the macro argument to
5704indicate whether all invocations must specify a non-blank value (through
5705@samp{:@code{req}}), or whether it takes all of the remaining arguments
5706(through @samp{:@code{vararg}}). You can supply a default value for any
fffeaa5f
JB
5707macro argument by following the name with @samp{=@var{deflt}}. You
5708cannot define two macros with the same @var{macname} unless it has been
96e9638b 5709subject to the @code{.purgem} directive (@pxref{Purgem}) between the two
fffeaa5f 5710definitions. For example, these are all valid @code{.macro} statements:
252b5132
RH
5711
5712@table @code
5713@item .macro comm
5714Begin the definition of a macro called @code{comm}, which takes no
5715arguments.
5716
6258339f 5717@item .macro plus1 p, p1
252b5132
RH
5718@itemx .macro plus1 p p1
5719Either statement begins the definition of a macro called @code{plus1},
5720which takes two arguments; within the macro definition, write
5721@samp{\p} or @samp{\p1} to evaluate the arguments.
5722
5723@item .macro reserve_str p1=0 p2
5724Begin the definition of a macro called @code{reserve_str}, with two
5725arguments. The first argument has a default value, but not the second.
5726After the definition is complete, you can call the macro either as
5727@samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to
5728@var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str
5729,@var{b}} (with @samp{\p1} evaluating as the default, in this case
5730@samp{0}, and @samp{\p2} evaluating to @var{b}).
252b5132 5731
6eaeac8a
JB
5732@item .macro m p1:req, p2=0, p3:vararg
5733Begin the definition of a macro called @code{m}, with at least three
5734arguments. The first argument must always have a value specified, but
5735not the second, which instead has a default value. The third formal
5736will get assigned all remaining arguments specified at invocation time.
5737
252b5132
RH
5738When you call a macro, you can specify the argument values either by
5739position, or by keyword. For example, @samp{sum 9,17} is equivalent to
5740@samp{sum to=17, from=9}.
5741
6258339f
NC
5742@end table
5743
5e75c3ab
JB
5744Note that since each of the @var{macargs} can be an identifier exactly
5745as any other one permitted by the target architecture, there may be
5746occasional problems if the target hand-crafts special meanings to certain
6258339f 5747characters when they occur in a special position. For example, if the colon
5e75c3ab 5748(@code{:}) is generally permitted to be part of a symbol name, but the
6258339f 5749architecture specific code special-cases it when occurring as the final
5e75c3ab
JB
5750character of a symbol (to denote a label), then the macro parameter
5751replacement code will have no way of knowing that and consider the whole
5752construct (including the colon) an identifier, and check only this
6258339f
NC
5753identifier for being the subject to parameter substitution. So for example
5754this macro definition:
5755
5756@example
5757 .macro label l
5758\l:
5759 .endm
5760@end example
5761
5762might not work as expected. Invoking @samp{label foo} might not create a label
5763called @samp{foo} but instead just insert the text @samp{\l:} into the
5764assembler source, probably generating an error about an unrecognised
5765identifier.
5766
5767Similarly problems might occur with the period character (@samp{.})
5768which is often allowed inside opcode names (and hence identifier names). So
5769for example constructing a macro to build an opcode from a base name and a
5770length specifier like this:
5771
5772@example
5773 .macro opcode base length
5774 \base.\length
5775 .endm
5776@end example
5777
5778and invoking it as @samp{opcode store l} will not create a @samp{store.l}
5779instruction but instead generate some kind of error as the assembler tries to
5780interpret the text @samp{\base.\length}.
5781
5782There are several possible ways around this problem:
5783
5784@table @code
5785@item Insert white space
5786If it is possible to use white space characters then this is the simplest
5787solution. eg:
5788
5789@example
5790 .macro label l
5791\l :
5792 .endm
5793@end example
5794
5795@item Use @samp{\()}
5796The string @samp{\()} can be used to separate the end of a macro argument from
5797the following text. eg:
5798
5799@example
5800 .macro opcode base length
5801 \base\().\length
5802 .endm
5803@end example
5804
5805@item Use the alternate macro syntax mode
5806In the alternative macro syntax mode the ampersand character (@samp{&}) can be
5807used as a separator. eg:
5e75c3ab
JB
5808
5809@example
5810 .altmacro
5811 .macro label l
5812l&:
5813 .endm
5814@end example
6258339f 5815@end table
5e75c3ab 5816
96e9638b 5817Note: this problem of correctly identifying string parameters to pseudo ops
01642c12 5818also applies to the identifiers used in @code{.irp} (@pxref{Irp})
96e9638b 5819and @code{.irpc} (@pxref{Irpc}) as well.
5e75c3ab 5820
252b5132
RH
5821@item .endm
5822@cindex @code{endm} directive
5823Mark the end of a macro definition.
5824
5825@item .exitm
5826@cindex @code{exitm} directive
5827Exit early from the current macro definition.
5828
5829@cindex number of macros executed
5830@cindex macros, count executed
5831@item \@@
a4fb0134 5832@command{@value{AS}} maintains a counter of how many macros it has
252b5132
RH
5833executed in this pseudo-variable; you can copy that number to your
5834output with @samp{\@@}, but @emph{only within a macro definition}.
5835
252b5132
RH
5836@item LOCAL @var{name} [ , @dots{} ]
5837@emph{Warning: @code{LOCAL} is only available if you select ``alternate
caa32fe5
NC
5838macro syntax'' with @samp{--alternate} or @code{.altmacro}.}
5839@xref{Altmacro,,@code{.altmacro}}.
5840@end ftable
252b5132 5841
ccf8a69b
BW
5842@node MRI
5843@section @code{.mri @var{val}}
caa32fe5 5844
ccf8a69b
BW
5845@cindex @code{mri} directive
5846@cindex MRI mode, temporarily
5847If @var{val} is non-zero, this tells @command{@value{AS}} to enter MRI mode. If
5848@var{val} is zero, this tells @command{@value{AS}} to exit MRI mode. This change
5849affects code assembled until the next @code{.mri} directive, or until the end
5850of the file. @xref{M, MRI mode, MRI mode}.
252b5132 5851
caa32fe5
NC
5852@node Noaltmacro
5853@section @code{.noaltmacro}
96e9638b 5854Disable alternate macro mode. @xref{Altmacro}.
caa32fe5 5855
252b5132
RH
5856@node Nolist
5857@section @code{.nolist}
5858
5859@cindex @code{nolist} directive
5860@cindex listing control, turning off
5861Control (in conjunction with the @code{.list} directive) whether or
5862not assembly listings are generated. These two directives maintain an
5863internal counter (which is zero initially). @code{.list} increments the
5864counter, and @code{.nolist} decrements it. Assembly listings are
5865generated whenever the counter is greater than zero.
5866
5867@node Octa
5868@section @code{.octa @var{bignums}}
5869
5870@c FIXME: double size emitted for "octa" on i960, others? Or warn?
5871@cindex @code{octa} directive
5872@cindex integer, 16-byte
5873@cindex sixteen byte integer
5874This directive expects zero or more bignums, separated by commas. For each
5875bignum, it emits a 16-byte integer.
5876
5877The term ``octa'' comes from contexts in which a ``word'' is two bytes;
5878hence @emph{octa}-word for 16 bytes.
5879
9aec2026
NC
5880@node Offset
5881@section @code{.offset @var{loc}}
5882
5883@cindex @code{offset} directive
5884Set the location counter to @var{loc} in the absolute section. @var{loc} must
5885be an absolute expression. This directive may be useful for defining
5886symbols with absolute values. Do not confuse it with the @code{.org}
fa94de6b 5887directive.
9aec2026 5888
252b5132
RH
5889@node Org
5890@section @code{.org @var{new-lc} , @var{fill}}
5891
5892@cindex @code{org} directive
5893@cindex location counter, advancing
5894@cindex advancing location counter
5895@cindex current address, advancing
5896Advance the location counter of the current section to
5897@var{new-lc}. @var{new-lc} is either an absolute expression or an
5898expression with the same section as the current subsection. That is,
5899you can't use @code{.org} to cross sections: if @var{new-lc} has the
5900wrong section, the @code{.org} directive is ignored. To be compatible
5901with former assemblers, if the section of @var{new-lc} is absolute,
a4fb0134 5902@command{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
252b5132
RH
5903is the same as the current subsection.
5904
5905@code{.org} may only increase the location counter, or leave it
5906unchanged; you cannot use @code{.org} to move the location counter
5907backwards.
5908
5909@c double negative used below "not undefined" because this is a specific
5910@c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
5911@c section. doc@cygnus.com 18feb91
a4fb0134 5912Because @command{@value{AS}} tries to assemble programs in one pass, @var{new-lc}
252b5132
RH
5913may not be undefined. If you really detest this restriction we eagerly await
5914a chance to share your improved assembler.
5915
5916Beware that the origin is relative to the start of the section, not
5917to the start of the subsection. This is compatible with other
5918people's assemblers.
5919
5920When the location counter (of the current subsection) is advanced, the
5921intervening bytes are filled with @var{fill} which should be an
5922absolute expression. If the comma and @var{fill} are omitted,
5923@var{fill} defaults to zero.
5924
5925@node P2align
5926@section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
5927
5928@cindex padding the location counter given a power of two
5929@cindex @code{p2align} directive
5930Pad the location counter (in the current subsection) to a particular
5931storage boundary. The first expression (which must be absolute) is the
5932number of low-order zero bits the location counter must have after
5933advancement. For example @samp{.p2align 3} advances the location
5934counter until it a multiple of 8. If the location counter is already a
5935multiple of 8, no change is needed.
5936
5937The second expression (also absolute) gives the fill value to be stored in the
5938padding bytes. It (and the comma) may be omitted. If it is omitted, the
5939padding bytes are normally zero. However, on some systems, if the section is
5940marked as containing code and the fill value is omitted, the space is filled
5941with no-op instructions.
5942
5943The third expression is also absolute, and is also optional. If it is present,
5944it is the maximum number of bytes that should be skipped by this alignment
5945directive. If doing the alignment would require skipping more bytes than the
5946specified maximum, then the alignment is not done at all. You can omit the
5947fill value (the second argument) entirely by simply using two commas after the
5948required alignment; this can be useful if you want the alignment to be filled
5949with no-op instructions when appropriate.
5950
5951@cindex @code{p2alignw} directive
5952@cindex @code{p2alignl} directive
5953The @code{.p2alignw} and @code{.p2alignl} directives are variants of the
5954@code{.p2align} directive. The @code{.p2alignw} directive treats the fill
5955pattern as a two byte word value. The @code{.p2alignl} directives treats the
5956fill pattern as a four byte longword value. For example, @code{.p2alignw
59572,0x368d} will align to a multiple of 4. If it skips two bytes, they will be
5958filled in with the value 0x368d (the exact placement of the bytes depends upon
5959the endianness of the processor). If it skips 1 or 3 bytes, the fill value is
5960undefined.
5961
ccf8a69b
BW
5962@ifset ELF
5963@node PopSection
5964@section @code{.popsection}
5965
5966@cindex @code{popsection} directive
5967@cindex Section Stack
5968This is one of the ELF section stack manipulation directives. The others are
01642c12
RM
5969@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}),
5970@code{.pushsection} (@pxref{PushSection}), and @code{.previous}
ccf8a69b
BW
5971(@pxref{Previous}).
5972
5973This directive replaces the current section (and subsection) with the top
5974section (and subsection) on the section stack. This section is popped off the
01642c12 5975stack.
ccf8a69b
BW
5976@end ifset
5977
c91d2e08
NC
5978@ifset ELF
5979@node Previous
5980@section @code{.previous}
5981
c1253627 5982@cindex @code{previous} directive
c91d2e08
NC
5983@cindex Section Stack
5984This is one of the ELF section stack manipulation directives. The others are
a349d9dd
PB
5985@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}),
5986@code{.pushsection} (@pxref{PushSection}), and @code{.popsection}
5987(@pxref{PopSection}).
c91d2e08
NC
5988
5989This directive swaps the current section (and subsection) with most recently
8b040e0a 5990referenced section/subsection pair prior to this one. Multiple
c91d2e08 5991@code{.previous} directives in a row will flip between two sections (and their
8b040e0a
NC
5992subsections). For example:
5993
5994@smallexample
5995.section A
5996 .subsection 1
5997 .word 0x1234
5998 .subsection 2
5999 .word 0x5678
6000.previous
6001 .word 0x9abc
6002@end smallexample
6003
6004Will place 0x1234 and 0x9abc into subsection 1 and 0x5678 into subsection 2 of
6005section A. Whilst:
6006
6007@smallexample
6008.section A
6009.subsection 1
6010 # Now in section A subsection 1
6011 .word 0x1234
6012.section B
6013.subsection 0
6014 # Now in section B subsection 0
6015 .word 0x5678
6016.subsection 1
6017 # Now in section B subsection 1
6018 .word 0x9abc
6019.previous
6020 # Now in section B subsection 0
6021 .word 0xdef0
6022@end smallexample
6023
6024Will place 0x1234 into section A, 0x5678 and 0xdef0 into subsection 0 of
6025section B and 0x9abc into subsection 1 of section B.
c91d2e08
NC
6026
6027In terms of the section stack, this directive swaps the current section with
6028the top section on the section stack.
6029@end ifset
6030
252b5132
RH
6031@node Print
6032@section @code{.print @var{string}}
6033
6034@cindex @code{print} directive
a4fb0134 6035@command{@value{AS}} will print @var{string} on the standard output during
252b5132
RH
6036assembly. You must put @var{string} in double quotes.
6037
c91d2e08
NC
6038@ifset ELF
6039@node Protected
6040@section @code{.protected @var{names}}
6041
c1253627
NC
6042@cindex @code{protected} directive
6043@cindex visibility
ed9589d4 6044This is one of the ELF visibility directives. The other two are
a349d9dd 6045@code{.hidden} (@pxref{Hidden}) and @code{.internal} (@pxref{Internal}).
c91d2e08
NC
6046
6047This directive overrides the named symbols default visibility (which is set by
6048their binding: local, global or weak). The directive sets the visibility to
6049@code{protected} which means that any references to the symbols from within the
6050components that defines them must be resolved to the definition in that
6051component, even if a definition in another component would normally preempt
01642c12 6052this.
c91d2e08
NC
6053@end ifset
6054
252b5132
RH
6055@node Psize
6056@section @code{.psize @var{lines} , @var{columns}}
6057
6058@cindex @code{psize} directive
6059@cindex listing control: paper size
6060@cindex paper size, for listings
6061Use this directive to declare the number of lines---and, optionally, the
6062number of columns---to use for each page, when generating listings.
6063
6064If you do not use @code{.psize}, listings use a default line-count
6065of 60. You may omit the comma and @var{columns} specification; the
6066default width is 200 columns.
6067
a4fb0134 6068@command{@value{AS}} generates formfeeds whenever the specified number of
252b5132
RH
6069lines is exceeded (or whenever you explicitly request one, using
6070@code{.eject}).
6071
6072If you specify @var{lines} as @code{0}, no formfeeds are generated save
6073those explicitly specified with @code{.eject}.
6074
6075@node Purgem
6076@section @code{.purgem @var{name}}
6077
6078@cindex @code{purgem} directive
6079Undefine the macro @var{name}, so that later uses of the string will not be
6080expanded. @xref{Macro}.
6081
c91d2e08
NC
6082@ifset ELF
6083@node PushSection
9cfc3331 6084@section @code{.pushsection @var{name} [, @var{subsection}] [, "@var{flags}"[, @@@var{type}[,@var{arguments}]]]}
c91d2e08 6085
c1253627 6086@cindex @code{pushsection} directive
c91d2e08
NC
6087@cindex Section Stack
6088This is one of the ELF section stack manipulation directives. The others are
01642c12
RM
6089@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}),
6090@code{.popsection} (@pxref{PopSection}), and @code{.previous}
a349d9dd 6091(@pxref{Previous}).
c91d2e08 6092
e9863d7f
DJ
6093This directive pushes the current section (and subsection) onto the
6094top of the section stack, and then replaces the current section and
9cfc3331
L
6095subsection with @code{name} and @code{subsection}. The optional
6096@code{flags}, @code{type} and @code{arguments} are treated the same
6097as in the @code{.section} (@pxref{Section}) directive.
c91d2e08
NC
6098@end ifset
6099
252b5132
RH
6100@node Quad
6101@section @code{.quad @var{bignums}}
6102
6103@cindex @code{quad} directive
6104@code{.quad} expects zero or more bignums, separated by commas. For
6105each bignum, it emits
6106@ifclear bignum-16
6107an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
6108warning message; and just takes the lowest order 8 bytes of the bignum.
6109@cindex eight-byte integer
6110@cindex integer, 8-byte
6111
6112The term ``quad'' comes from contexts in which a ``word'' is two bytes;
6113hence @emph{quad}-word for 8 bytes.
6114@end ifclear
6115@ifset bignum-16
6116a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
6117warning message; and just takes the lowest order 16 bytes of the bignum.
6118@cindex sixteen-byte integer
6119@cindex integer, 16-byte
6120@end ifset
6121
05e9452c
AM
6122@node Reloc
6123@section @code{.reloc @var{offset}, @var{reloc_name}[, @var{expression}]}
6124
6125@cindex @code{reloc} directive
6126Generate a relocation at @var{offset} of type @var{reloc_name} with value
6127@var{expression}. If @var{offset} is a number, the relocation is generated in
6128the current section. If @var{offset} is an expression that resolves to a
6129symbol plus offset, the relocation is generated in the given symbol's section.
6130@var{expression}, if present, must resolve to a symbol plus addend or to an
6131absolute value, but note that not all targets support an addend. e.g. ELF REL
6132targets such as i386 store an addend in the section contents rather than in the
6133relocation. This low level interface does not support addends stored in the
6134section.
6135
252b5132
RH
6136@node Rept
6137@section @code{.rept @var{count}}
6138
6139@cindex @code{rept} directive
6140Repeat the sequence of lines between the @code{.rept} directive and the next
6141@code{.endr} directive @var{count} times.
6142
6143For example, assembling
6144
6145@example
6146 .rept 3
6147 .long 0
6148 .endr
6149@end example
6150
6151is equivalent to assembling
6152
6153@example
6154 .long 0
6155 .long 0
6156 .long 0
6157@end example
6158
6159@node Sbttl
6160@section @code{.sbttl "@var{subheading}"}
6161
6162@cindex @code{sbttl} directive
6163@cindex subtitles for listings
6164@cindex listing control: subtitle
6165Use @var{subheading} as the title (third line, immediately after the
6166title line) when generating assembly listings.
6167
6168This directive affects subsequent pages, as well as the current page if
6169it appears within ten lines of the top of a page.
6170
6171@ifset COFF
6172@node Scl
6173@section @code{.scl @var{class}}
6174
6175@cindex @code{scl} directive
6176@cindex symbol storage class (COFF)
6177@cindex COFF symbol storage class
6178Set the storage-class value for a symbol. This directive may only be
6179used inside a @code{.def}/@code{.endef} pair. Storage class may flag
6180whether a symbol is static or external, or it may record further
6181symbolic debugging information.
6182@ifset BOUT
6183
6184The @samp{.scl} directive is primarily associated with COFF output; when
a4fb0134 6185configured to generate @code{b.out} output format, @command{@value{AS}}
252b5132
RH
6186accepts this directive but ignores it.
6187@end ifset
6188@end ifset
6189
c1253627 6190@ifset COFF-ELF
252b5132 6191@node Section
c1253627 6192@section @code{.section @var{name}}
252b5132 6193
252b5132
RH
6194@cindex named section
6195Use the @code{.section} directive to assemble the following code into a section
6196named @var{name}.
6197
6198This directive is only supported for targets that actually support arbitrarily
6199named sections; on @code{a.out} targets, for example, it is not accepted, even
6200with a standard @code{a.out} section name.
6201
c1253627
NC
6202@ifset COFF
6203@ifset ELF
6204@c only print the extra heading if both COFF and ELF are set
6205@subheading COFF Version
6206@end ifset
6207
6208@cindex @code{section} directive (COFF version)
252b5132
RH
6209For COFF targets, the @code{.section} directive is used in one of the following
6210ways:
c91d2e08 6211
252b5132
RH
6212@smallexample
6213.section @var{name}[, "@var{flags}"]
4e188d17 6214.section @var{name}[, @var{subsection}]
252b5132
RH
6215@end smallexample
6216
6217If the optional argument is quoted, it is taken as flags to use for the
6218section. Each flag is a single character. The following flags are recognized:
6219@table @code
6220@item b
6221bss section (uninitialized data)
6222@item n
6223section is not loaded
6224@item w
6225writable section
6226@item d
6227data section
70e0ee1a
KT
6228@item e
6229exclude section from linking
252b5132
RH
6230@item r
6231read-only section
6232@item x
6233executable section
2dcc60be
ILT
6234@item s
6235shared section (meaningful for PE targets)
6ff96af6
NC
6236@item a
6237ignored. (For compatibility with the ELF version)
63ad59ae
KT
6238@item y
6239section is not readable (meaningful for PE targets)
31907d5e
DK
6240@item 0-9
6241single-digit power-of-two section alignment (GNU extension)
252b5132
RH
6242@end table
6243
6244If no flags are specified, the default flags depend upon the section name. If
6245the section name is not recognized, the default will be for the section to be
7e84d676
NC
6246loaded and writable. Note the @code{n} and @code{w} flags remove attributes
6247from the section, rather than adding them, so if they are used on their own it
6248will be as if no flags had been specified at all.
252b5132
RH
6249
6250If the optional argument to the @code{.section} directive is not quoted, it is
4e188d17 6251taken as a subsection number (@pxref{Sub-Sections}).
c1253627 6252@end ifset
252b5132
RH
6253
6254@ifset ELF
c1253627
NC
6255@ifset COFF
6256@c only print the extra heading if both COFF and ELF are set
6257@subheading ELF Version
6258@end ifset
6259
c91d2e08
NC
6260@cindex Section Stack
6261This is one of the ELF section stack manipulation directives. The others are
01642c12 6262@code{.subsection} (@pxref{SubSection}), @code{.pushsection}
a349d9dd
PB
6263(@pxref{PushSection}), @code{.popsection} (@pxref{PopSection}), and
6264@code{.previous} (@pxref{Previous}).
c91d2e08 6265
c1253627 6266@cindex @code{section} directive (ELF version)
252b5132 6267For ELF targets, the @code{.section} directive is used like this:
c91d2e08 6268
252b5132 6269@smallexample
7047dd1e 6270.section @var{name} [, "@var{flags}"[, @@@var{type}[,@var{flag_specific_arguments}]]]
252b5132 6271@end smallexample
c91d2e08 6272
451133ce
NP
6273@anchor{Section Name Substitutions}
6274@kindex --sectname-subst
6275@cindex section name substitution
6276If the @samp{--sectname-subst} command-line option is provided, the @var{name}
6277argument may contain a substitution sequence. Only @code{%S} is supported
6278at the moment, and substitutes the current section name. For example:
6279
6280@smallexample
6281.macro exception_code
6282.section %S.exception
6283[exception code here]
6284.previous
6285.endm
6286
6287.text
6288[code]
6289exception_code
6290[...]
6291
6292.section .init
6293[init code]
6294exception_code
6295[...]
6296@end smallexample
6297
6298The two @code{exception_code} invocations above would create the
6299@code{.text.exception} and @code{.init.exception} sections respectively.
6300This is useful e.g. to discriminate between anciliary sections that are
6301tied to setup code to be discarded after use from anciliary sections that
6302need to stay resident without having to define multiple @code{exception_code}
6303macros just for that purpose.
6304
252b5132 6305The optional @var{flags} argument is a quoted string which may contain any
a349d9dd 6306combination of the following characters:
252b5132
RH
6307@table @code
6308@item a
6309section is allocatable
18ae9cc1
L
6310@item e
6311section is excluded from executable and shared library.
252b5132
RH
6312@item w
6313section is writable
6314@item x
6315section is executable
ec38dd05
JJ
6316@item M
6317section is mergeable
6318@item S
6319section contains zero terminated strings
22fe14ad
NC
6320@item G
6321section is a member of a section group
6322@item T
6323section is used for thread-local-storage
01642c12
RM
6324@item ?
6325section is a member of the previously-current section's group, if any
252b5132
RH
6326@end table
6327
6328The optional @var{type} argument may contain one of the following constants:
6329@table @code
6330@item @@progbits
6331section contains data
6332@item @@nobits
6333section does not contain data (i.e., section only occupies space)
22fe14ad
NC
6334@item @@note
6335section contains data which is used by things other than the program
10b016c2
PB
6336@item @@init_array
6337section contains an array of pointers to init functions
6338@item @@fini_array
6339section contains an array of pointers to finish functions
6340@item @@preinit_array
6341section contains an array of pointers to pre-init functions
252b5132
RH
6342@end table
6343
10b016c2
PB
6344Many targets only support the first three section types.
6345
ececec60
NC
6346Note on targets where the @code{@@} character is the start of a comment (eg
6347ARM) then another character is used instead. For example the ARM port uses the
6348@code{%} character.
6349
22fe14ad 6350If @var{flags} contains the @code{M} symbol then the @var{type} argument must
96e9638b 6351be specified as well as an extra argument---@var{entsize}---like this:
22fe14ad
NC
6352
6353@smallexample
6354.section @var{name} , "@var{flags}"M, @@@var{type}, @var{entsize}
6355@end smallexample
6356
6357Sections with the @code{M} flag but not @code{S} flag must contain fixed size
6358constants, each @var{entsize} octets long. Sections with both @code{M} and
6359@code{S} must contain zero terminated strings where each character is
6360@var{entsize} bytes long. The linker may remove duplicates within sections with
6361the same name, same entity size and same flags. @var{entsize} must be an
90dce00a
AM
6362absolute expression. For sections with both @code{M} and @code{S}, a string
6363which is a suffix of a larger string is considered a duplicate. Thus
6364@code{"def"} will be merged with @code{"abcdef"}; A reference to the first
6365@code{"def"} will be changed to a reference to @code{"abcdef"+3}.
22fe14ad
NC
6366
6367If @var{flags} contains the @code{G} symbol then the @var{type} argument must
6368be present along with an additional field like this:
6369
6370@smallexample
6371.section @var{name} , "@var{flags}"G, @@@var{type}, @var{GroupName}[, @var{linkage}]
6372@end smallexample
6373
6374The @var{GroupName} field specifies the name of the section group to which this
6375particular section belongs. The optional linkage field can contain:
6376@table @code
6377@item comdat
6378indicates that only one copy of this section should be retained
6379@item .gnu.linkonce
6380an alias for comdat
6381@end table
6382
96e9638b 6383Note: if both the @var{M} and @var{G} flags are present then the fields for
22fe14ad
NC
6384the Merge flag should come first, like this:
6385
6386@smallexample
6387.section @var{name} , "@var{flags}"MG, @@@var{type}, @var{entsize}, @var{GroupName}[, @var{linkage}]
6388@end smallexample
ec38dd05 6389
01642c12
RM
6390If @var{flags} contains the @code{?} symbol then it may not also contain the
6391@code{G} symbol and the @var{GroupName} or @var{linkage} fields should not be
6392present. Instead, @code{?} says to consider the section that's current before
6393this directive. If that section used @code{G}, then the new section will use
6394@code{G} with those same @var{GroupName} and @var{linkage} fields implicitly.
6395If not, then the @code{?} symbol has no effect.
6396
252b5132
RH
6397If no flags are specified, the default flags depend upon the section name. If
6398the section name is not recognized, the default will be for the section to have
6399none of the above flags: it will not be allocated in memory, nor writable, nor
6400executable. The section will contain data.
6401
6402For ELF targets, the assembler supports another type of @code{.section}
6403directive for compatibility with the Solaris assembler:
c91d2e08 6404
252b5132
RH
6405@smallexample
6406.section "@var{name}"[, @var{flags}...]
6407@end smallexample
c91d2e08 6408
252b5132
RH
6409Note that the section name is quoted. There may be a sequence of comma
6410separated flags:
6411@table @code
6412@item #alloc
6413section is allocatable
6414@item #write
6415section is writable
6416@item #execinstr
6417section is executable
18ae9cc1
L
6418@item #exclude
6419section is excluded from executable and shared library.
22fe14ad
NC
6420@item #tls
6421section is used for thread local storage
252b5132 6422@end table
c91d2e08 6423
e9863d7f
DJ
6424This directive replaces the current section and subsection. See the
6425contents of the gas testsuite directory @code{gas/testsuite/gas/elf} for
6426some examples of how this directive and the other section stack directives
6427work.
c1253627
NC
6428@end ifset
6429@end ifset
252b5132
RH
6430
6431@node Set
6432@section @code{.set @var{symbol}, @var{expression}}
6433
6434@cindex @code{set} directive
6435@cindex symbol value, setting
6436Set the value of @var{symbol} to @var{expression}. This
6437changes @var{symbol}'s value and type to conform to
6438@var{expression}. If @var{symbol} was flagged as external, it remains
6439flagged (@pxref{Symbol Attributes}).
6440
5d239759
NC
6441You may @code{.set} a symbol many times in the same assembly provided that the
6442values given to the symbol are constants. Values that are based on expressions
6443involving other symbols are allowed, but some targets may restrict this to only
6444being done once per assembly. This is because those targets do not set the
6445addresses of symbols at assembly time, but rather delay the assignment until a
6446final link is performed. This allows the linker a chance to change the code in
6447the files, changing the location of, and the relative distance between, various
6448different symbols.
252b5132
RH
6449
6450If you @code{.set} a global symbol, the value stored in the object
6451file is the last value stored into it.
6452
3c9b82ba
NC
6453@ifset Z80
6454On Z80 @code{set} is a real instruction, use
6455@samp{@var{symbol} defl @var{expression}} instead.
6456@end ifset
6457
252b5132
RH
6458@node Short
6459@section @code{.short @var{expressions}}
6460
6461@cindex @code{short} directive
6462@ifset GENERIC
6463@code{.short} is normally the same as @samp{.word}.
6464@xref{Word,,@code{.word}}.
6465
6466In some configurations, however, @code{.short} and @code{.word} generate
96e9638b 6467numbers of different lengths. @xref{Machine Dependencies}.
252b5132
RH
6468@end ifset
6469@ifclear GENERIC
6470@ifset W16
6471@code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
6472@end ifset
6473@ifset W32
6474This expects zero or more @var{expressions}, and emits
6475a 16 bit number for each.
6476@end ifset
6477@end ifclear
6478
6479@node Single
6480@section @code{.single @var{flonums}}
6481
6482@cindex @code{single} directive
6483@cindex floating point numbers (single)
6484This directive assembles zero or more flonums, separated by commas. It
6485has the same effect as @code{.float}.
6486@ifset GENERIC
6487The exact kind of floating point numbers emitted depends on how
a4fb0134 6488@command{@value{AS}} is configured. @xref{Machine Dependencies}.
252b5132
RH
6489@end ifset
6490@ifclear GENERIC
6491@ifset IEEEFLOAT
6492On the @value{TARGET} family, @code{.single} emits 32-bit floating point
6493numbers in @sc{ieee} format.
6494@end ifset
6495@end ifclear
6496
c1253627 6497@ifset COFF-ELF
252b5132 6498@node Size
c1253627 6499@section @code{.size}
c91d2e08 6500
c1253627
NC
6501This directive is used to set the size associated with a symbol.
6502
6503@ifset COFF
6504@ifset ELF
6505@c only print the extra heading if both COFF and ELF are set
6506@subheading COFF Version
6507@end ifset
6508
6509@cindex @code{size} directive (COFF version)
6510For COFF targets, the @code{.size} directive is only permitted inside
6511@code{.def}/@code{.endef} pairs. It is used like this:
6512
6513@smallexample
6514.size @var{expression}
6515@end smallexample
252b5132 6516
c91d2e08 6517@ifset BOUT
252b5132 6518@samp{.size} is only meaningful when generating COFF format output; when
a4fb0134 6519@command{@value{AS}} is generating @code{b.out}, it accepts this directive but
252b5132
RH
6520ignores it.
6521@end ifset
c1253627 6522@end ifset
c91d2e08 6523
c1253627
NC
6524@ifset ELF
6525@ifset COFF
6526@c only print the extra heading if both COFF and ELF are set
6527@subheading ELF Version
6528@end ifset
6529
6530@cindex @code{size} directive (ELF version)
6531For ELF targets, the @code{.size} directive is used like this:
c91d2e08 6532
c1253627
NC
6533@smallexample
6534.size @var{name} , @var{expression}
6535@end smallexample
6536
6537This directive sets the size associated with a symbol @var{name}.
c91d2e08
NC
6538The size in bytes is computed from @var{expression} which can make use of label
6539arithmetic. This directive is typically used to set the size of function
6540symbols.
c1253627
NC
6541@end ifset
6542@end ifset
252b5132 6543
252b5132
RH
6544@ifclear no-space-dir
6545@node Skip
6546@section @code{.skip @var{size} , @var{fill}}
6547
6548@cindex @code{skip} directive
6549@cindex filling memory
6550This directive emits @var{size} bytes, each of value @var{fill}. Both
6551@var{size} and @var{fill} are absolute expressions. If the comma and
6552@var{fill} are omitted, @var{fill} is assumed to be zero. This is the same as
6553@samp{.space}.
884f0d36 6554@end ifclear
252b5132 6555
ccf8a69b
BW
6556@node Sleb128
6557@section @code{.sleb128 @var{expressions}}
6558
6559@cindex @code{sleb128} directive
01642c12 6560@var{sleb128} stands for ``signed little endian base 128.'' This is a
ccf8a69b
BW
6561compact, variable length representation of numbers used by the DWARF
6562symbolic debugging format. @xref{Uleb128, ,@code{.uleb128}}.
6563
884f0d36 6564@ifclear no-space-dir
252b5132
RH
6565@node Space
6566@section @code{.space @var{size} , @var{fill}}
6567
6568@cindex @code{space} directive
6569@cindex filling memory
6570This directive emits @var{size} bytes, each of value @var{fill}. Both
6571@var{size} and @var{fill} are absolute expressions. If the comma
6572and @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same
6573as @samp{.skip}.
6574
6575@ifset HPPA
6576@quotation
6577@emph{Warning:} @code{.space} has a completely different meaning for HPPA
6578targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800
6579Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the
6580@code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives},
6581for a summary.
6582@end quotation
6583@end ifset
6584@end ifclear
6585
252b5132
RH
6586@ifset have-stabs
6587@node Stab
6588@section @code{.stabd, .stabn, .stabs}
6589
6590@cindex symbolic debuggers, information for
6591@cindex @code{stab@var{x}} directives
6592There are three directives that begin @samp{.stab}.
6593All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
a4fb0134 6594The symbols are not entered in the @command{@value{AS}} hash table: they
252b5132
RH
6595cannot be referenced elsewhere in the source file.
6596Up to five fields are required:
6597
6598@table @var
6599@item string
6600This is the symbol's name. It may contain any character except
6601@samp{\000}, so is more general than ordinary symbol names. Some
6602debuggers used to code arbitrarily complex structures into symbol names
6603using this field.
6604
6605@item type
6606An absolute expression. The symbol's type is set to the low 8 bits of
6607this expression. Any bit pattern is permitted, but @code{@value{LD}}
6608and debuggers choke on silly bit patterns.
6609
6610@item other
6611An absolute expression. The symbol's ``other'' attribute is set to the
6612low 8 bits of this expression.
6613
6614@item desc
6615An absolute expression. The symbol's descriptor is set to the low 16
6616bits of this expression.
6617
6618@item value
6619An absolute expression which becomes the symbol's value.
6620@end table
6621
6622If a warning is detected while reading a @code{.stabd}, @code{.stabn},
6623or @code{.stabs} statement, the symbol has probably already been created;
6624you get a half-formed symbol in your object file. This is
6625compatible with earlier assemblers!
6626
6627@table @code
6628@cindex @code{stabd} directive
6629@item .stabd @var{type} , @var{other} , @var{desc}
6630
6631The ``name'' of the symbol generated is not even an empty string.
6632It is a null pointer, for compatibility. Older assemblers used a
6633null pointer so they didn't waste space in object files with empty
6634strings.
6635
6636The symbol's value is set to the location counter,
6637relocatably. When your program is linked, the value of this symbol
6638is the address of the location counter when the @code{.stabd} was
6639assembled.
6640
6641@cindex @code{stabn} directive
6642@item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
6643The name of the symbol is set to the empty string @code{""}.
6644
6645@cindex @code{stabs} directive
6646@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
6647All five fields are specified.
6648@end table
6649@end ifset
6650@c end have-stabs
6651
6652@node String
38a57ae7 6653@section @code{.string} "@var{str}", @code{.string8} "@var{str}", @code{.string16}
01642c12 6654"@var{str}", @code{.string32} "@var{str}", @code{.string64} "@var{str}"
252b5132
RH
6655
6656@cindex string, copying to object file
38a57ae7
NC
6657@cindex string8, copying to object file
6658@cindex string16, copying to object file
6659@cindex string32, copying to object file
6660@cindex string64, copying to object file
252b5132 6661@cindex @code{string} directive
38a57ae7
NC
6662@cindex @code{string8} directive
6663@cindex @code{string16} directive
6664@cindex @code{string32} directive
6665@cindex @code{string64} directive
252b5132
RH
6666
6667Copy the characters in @var{str} to the object file. You may specify more than
6668one string to copy, separated by commas. Unless otherwise specified for a
6669particular machine, the assembler marks the end of each string with a 0 byte.
6670You can use any of the escape sequences described in @ref{Strings,,Strings}.
6671
01642c12 6672The variants @code{string16}, @code{string32} and @code{string64} differ from
38a57ae7
NC
6673the @code{string} pseudo opcode in that each 8-bit character from @var{str} is
6674copied and expanded to 16, 32 or 64 bits respectively. The expanded characters
6675are stored in target endianness byte order.
6676
6677Example:
6678@smallexample
6679 .string32 "BYE"
6680expands to:
6681 .string "B\0\0\0Y\0\0\0E\0\0\0" /* On little endian targets. */
6682 .string "\0\0\0B\0\0\0Y\0\0\0E" /* On big endian targets. */
6683@end smallexample
6684
6685
252b5132
RH
6686@node Struct
6687@section @code{.struct @var{expression}}
6688
6689@cindex @code{struct} directive
6690Switch to the absolute section, and set the section offset to @var{expression},
6691which must be an absolute expression. You might use this as follows:
6692@smallexample
6693 .struct 0
6694field1:
6695 .struct field1 + 4
6696field2:
6697 .struct field2 + 4
6698field3:
6699@end smallexample
6700This would define the symbol @code{field1} to have the value 0, the symbol
6701@code{field2} to have the value 4, and the symbol @code{field3} to have the
6702value 8. Assembly would be left in the absolute section, and you would need to
6703use a @code{.section} directive of some sort to change to some other section
6704before further assembly.
6705
c91d2e08
NC
6706@ifset ELF
6707@node SubSection
6708@section @code{.subsection @var{name}}
6709
c1253627 6710@cindex @code{subsection} directive
c91d2e08
NC
6711@cindex Section Stack
6712This is one of the ELF section stack manipulation directives. The others are
01642c12
RM
6713@code{.section} (@pxref{Section}), @code{.pushsection} (@pxref{PushSection}),
6714@code{.popsection} (@pxref{PopSection}), and @code{.previous}
a349d9dd 6715(@pxref{Previous}).
c91d2e08
NC
6716
6717This directive replaces the current subsection with @code{name}. The current
6718section is not changed. The replaced subsection is put onto the section stack
6719in place of the then current top of stack subsection.
c91d2e08
NC
6720@end ifset
6721
252b5132
RH
6722@ifset ELF
6723@node Symver
6724@section @code{.symver}
6725@cindex @code{symver} directive
6726@cindex symbol versioning
6727@cindex versions of symbols
6728Use the @code{.symver} directive to bind symbols to specific version nodes
6729within a source file. This is only supported on ELF platforms, and is
6730typically used when assembling files to be linked into a shared library.
6731There are cases where it may make sense to use this in objects to be bound
6732into an application itself so as to override a versioned symbol from a
6733shared library.
6734
79082ff0 6735For ELF targets, the @code{.symver} directive can be used like this:
252b5132
RH
6736@smallexample
6737.symver @var{name}, @var{name2@@nodename}
6738@end smallexample
339681c0 6739If the symbol @var{name} is defined within the file
79082ff0 6740being assembled, the @code{.symver} directive effectively creates a symbol
252b5132
RH
6741alias with the name @var{name2@@nodename}, and in fact the main reason that we
6742just don't try and create a regular alias is that the @var{@@} character isn't
6743permitted in symbol names. The @var{name2} part of the name is the actual name
6744of the symbol by which it will be externally referenced. The name @var{name}
6745itself is merely a name of convenience that is used so that it is possible to
6746have definitions for multiple versions of a function within a single source
6747file, and so that the compiler can unambiguously know which version of a
6748function is being mentioned. The @var{nodename} portion of the alias should be
6749the name of a node specified in the version script supplied to the linker when
6750building a shared library. If you are attempting to override a versioned
6751symbol from a shared library, then @var{nodename} should correspond to the
6752nodename of the symbol you are trying to override.
339681c0
L
6753
6754If the symbol @var{name} is not defined within the file being assembled, all
6755references to @var{name} will be changed to @var{name2@@nodename}. If no
6756reference to @var{name} is made, @var{name2@@nodename} will be removed from the
6757symbol table.
79082ff0
L
6758
6759Another usage of the @code{.symver} directive is:
6760@smallexample
6761.symver @var{name}, @var{name2@@@@nodename}
6762@end smallexample
6763In this case, the symbol @var{name} must exist and be defined within
a349d9dd 6764the file being assembled. It is similar to @var{name2@@nodename}. The
79082ff0
L
6765difference is @var{name2@@@@nodename} will also be used to resolve
6766references to @var{name2} by the linker.
6767
6768The third usage of the @code{.symver} directive is:
6769@smallexample
6770.symver @var{name}, @var{name2@@@@@@nodename}
6771@end smallexample
6772When @var{name} is not defined within the
6773file being assembled, it is treated as @var{name2@@nodename}. When
6774@var{name} is defined within the file being assembled, the symbol
6775name, @var{name}, will be changed to @var{name2@@@@nodename}.
252b5132
RH
6776@end ifset
6777
6778@ifset COFF
6779@node Tag
6780@section @code{.tag @var{structname}}
6781
6782@cindex COFF structure debugging
6783@cindex structure debugging, COFF
6784@cindex @code{tag} directive
6785This directive is generated by compilers to include auxiliary debugging
6786information in the symbol table. It is only permitted inside
6787@code{.def}/@code{.endef} pairs. Tags are used to link structure
6788definitions in the symbol table with instances of those structures.
6789@ifset BOUT
6790
6791@samp{.tag} is only used when generating COFF format output; when
a4fb0134 6792@command{@value{AS}} is generating @code{b.out}, it accepts this directive but
252b5132
RH
6793ignores it.
6794@end ifset
6795@end ifset
6796
6797@node Text
6798@section @code{.text @var{subsection}}
6799
6800@cindex @code{text} directive
a4fb0134 6801Tells @command{@value{AS}} to assemble the following statements onto the end of
252b5132
RH
6802the text subsection numbered @var{subsection}, which is an absolute
6803expression. If @var{subsection} is omitted, subsection number zero
6804is used.
6805
6806@node Title
6807@section @code{.title "@var{heading}"}
6808
6809@cindex @code{title} directive
6810@cindex listing control: title line
6811Use @var{heading} as the title (second line, immediately after the
6812source file name and pagenumber) when generating assembly listings.
6813
6814This directive affects subsequent pages, as well as the current page if
6815it appears within ten lines of the top of a page.
6816
c1253627 6817@ifset COFF-ELF
252b5132 6818@node Type
c1253627
NC
6819@section @code{.type}
6820
6821This directive is used to set the type of a symbol.
6822
6823@ifset COFF
6824@ifset ELF
6825@c only print the extra heading if both COFF and ELF are set
6826@subheading COFF Version
6827@end ifset
252b5132
RH
6828
6829@cindex COFF symbol type
6830@cindex symbol type, COFF
c1253627
NC
6831@cindex @code{type} directive (COFF version)
6832For COFF targets, this directive is permitted only within
6833@code{.def}/@code{.endef} pairs. It is used like this:
6834
6835@smallexample
6836.type @var{int}
6837@end smallexample
6838
6839This records the integer @var{int} as the type attribute of a symbol table
6840entry.
252b5132 6841
c91d2e08 6842@ifset BOUT
252b5132 6843@samp{.type} is associated only with COFF format output; when
a4fb0134 6844@command{@value{AS}} is configured for @code{b.out} output, it accepts this
252b5132
RH
6845directive but ignores it.
6846@end ifset
c1253627 6847@end ifset
c91d2e08 6848
c1253627
NC
6849@ifset ELF
6850@ifset COFF
6851@c only print the extra heading if both COFF and ELF are set
6852@subheading ELF Version
6853@end ifset
c91d2e08
NC
6854
6855@cindex ELF symbol type
6856@cindex symbol type, ELF
c1253627
NC
6857@cindex @code{type} directive (ELF version)
6858For ELF targets, the @code{.type} directive is used like this:
6859
6860@smallexample
6861.type @var{name} , @var{type description}
6862@end smallexample
6863
6864This sets the type of symbol @var{name} to be either a
a349d9dd 6865function symbol or an object symbol. There are five different syntaxes
c91d2e08 6866supported for the @var{type description} field, in order to provide
28c9d252 6867compatibility with various other assemblers.
58ab4f3d
MM
6868
6869Because some of the characters used in these syntaxes (such as @samp{@@} and
6870@samp{#}) are comment characters for some architectures, some of the syntaxes
6871below do not work on all architectures. The first variant will be accepted by
6872the GNU assembler on all architectures so that variant should be used for
6873maximum portability, if you do not need to assemble your code with other
6874assemblers.
6875
6876The syntaxes supported are:
c91d2e08
NC
6877
6878@smallexample
5671778d
NC
6879 .type <name> STT_<TYPE_IN_UPPER_CASE>
6880 .type <name>,#<type>
6881 .type <name>,@@<type>
e7c33416 6882 .type <name>,%<type>
5671778d
NC
6883 .type <name>,"<type>"
6884@end smallexample
6885
6886The types supported are:
58ab4f3d 6887
5671778d
NC
6888@table @gcctabopt
6889@item STT_FUNC
6890@itemx function
6891Mark the symbol as being a function name.
c91d2e08 6892
d8045f23
NC
6893@item STT_GNU_IFUNC
6894@itemx gnu_indirect_function
6895Mark the symbol as an indirect function when evaluated during reloc
9c55345c 6896processing. (This is only supported on assemblers targeting GNU systems).
d8045f23 6897
5671778d
NC
6898@item STT_OBJECT
6899@itemx object
6900Mark the symbol as being a data object.
6901
6902@item STT_TLS
6903@itemx tls_object
6904Mark the symbol as being a thead-local data object.
6905
6906@item STT_COMMON
6907@itemx common
6908Mark the symbol as being a common data object.
e7c33416
NC
6909
6910@item STT_NOTYPE
6911@itemx notype
6912Does not mark the symbol in any way. It is supported just for completeness.
6913
3e7a7d11
NC
6914@item gnu_unique_object
6915Marks the symbol as being a globally unique data object. The dynamic linker
6916will make sure that in the entire process there is just one symbol with this
9c55345c
TS
6917name and type in use. (This is only supported on assemblers targeting GNU
6918systems).
3e7a7d11 6919
5671778d
NC
6920@end table
6921
6922Note: Some targets support extra types in addition to those listed above.
c91d2e08 6923
c1253627
NC
6924@end ifset
6925@end ifset
c91d2e08
NC
6926
6927@node Uleb128
6928@section @code{.uleb128 @var{expressions}}
6929
6930@cindex @code{uleb128} directive
01642c12 6931@var{uleb128} stands for ``unsigned little endian base 128.'' This is a
c91d2e08 6932compact, variable length representation of numbers used by the DWARF
96e9638b 6933symbolic debugging format. @xref{Sleb128, ,@code{.sleb128}}.
252b5132
RH
6934
6935@ifset COFF
6936@node Val
6937@section @code{.val @var{addr}}
6938
6939@cindex @code{val} directive
6940@cindex COFF value attribute
6941@cindex value attribute, COFF
6942This directive, permitted only within @code{.def}/@code{.endef} pairs,
6943records the address @var{addr} as the value attribute of a symbol table
6944entry.
6945@ifset BOUT
6946
a4fb0134 6947@samp{.val} is used only for COFF output; when @command{@value{AS}} is
252b5132
RH
6948configured for @code{b.out}, it accepts this directive but ignores it.
6949@end ifset
6950@end ifset
6951
2e13b764 6952@ifset ELF
c91d2e08
NC
6953@node Version
6954@section @code{.version "@var{string}"}
2e13b764 6955
c1253627 6956@cindex @code{version} directive
c91d2e08
NC
6957This directive creates a @code{.note} section and places into it an ELF
6958formatted note of type NT_VERSION. The note's name is set to @code{string}.
9a297610 6959@end ifset
2e13b764 6960
c91d2e08
NC
6961@ifset ELF
6962@node VTableEntry
6963@section @code{.vtable_entry @var{table}, @var{offset}}
2e13b764 6964
653cfe85 6965@cindex @code{vtable_entry} directive
c91d2e08
NC
6966This directive finds or creates a symbol @code{table} and creates a
6967@code{VTABLE_ENTRY} relocation for it with an addend of @code{offset}.
2e13b764 6968
c91d2e08
NC
6969@node VTableInherit
6970@section @code{.vtable_inherit @var{child}, @var{parent}}
2e13b764 6971
653cfe85 6972@cindex @code{vtable_inherit} directive
c91d2e08
NC
6973This directive finds the symbol @code{child} and finds or creates the symbol
6974@code{parent} and then creates a @code{VTABLE_INHERIT} relocation for the
a349d9dd 6975parent whose addend is the value of the child symbol. As a special case the
96e9638b 6976parent name of @code{0} is treated as referring to the @code{*ABS*} section.
c91d2e08 6977@end ifset
2e13b764 6978
d190d046
HPN
6979@node Warning
6980@section @code{.warning "@var{string}"}
6981@cindex warning directive
6982Similar to the directive @code{.error}
6983(@pxref{Error,,@code{.error "@var{string}"}}), but just emits a warning.
6984
c91d2e08
NC
6985@node Weak
6986@section @code{.weak @var{names}}
2e13b764 6987
c1253627 6988@cindex @code{weak} directive
a349d9dd 6989This directive sets the weak attribute on the comma separated list of symbol
c91d2e08 6990@code{names}. If the symbols do not already exist, they will be created.
c87db184 6991
01642c12 6992On COFF targets other than PE, weak symbols are a GNU extension. This
977cdf5a 6993directive sets the weak attribute on the comma separated list of symbol
c87db184
CF
6994@code{names}. If the symbols do not already exist, they will be created.
6995
977cdf5a 6996On the PE target, weak symbols are supported natively as weak aliases.
01642c12 6997When a weak symbol is created that is not an alias, GAS creates an
977cdf5a 6998alternate symbol to hold the default value.
2e13b764 6999
06e77878
AO
7000@node Weakref
7001@section @code{.weakref @var{alias}, @var{target}}
7002
7003@cindex @code{weakref} directive
7004This directive creates an alias to the target symbol that enables the symbol to
7005be referenced with weak-symbol semantics, but without actually making it weak.
7006If direct references or definitions of the symbol are present, then the symbol
7007will not be weak, but if all references to it are through weak references, the
7008symbol will be marked as weak in the symbol table.
7009
7010The effect is equivalent to moving all references to the alias to a separate
7011assembly source file, renaming the alias to the symbol in it, declaring the
7012symbol as weak there, and running a reloadable link to merge the object files
7013resulting from the assembly of the new source file and the old source file that
7014had the references to the alias removed.
7015
7016The alias itself never makes to the symbol table, and is entirely handled
7017within the assembler.
7018
252b5132
RH
7019@node Word
7020@section @code{.word @var{expressions}}
7021
7022@cindex @code{word} directive
7023This directive expects zero or more @var{expressions}, of any section,
7024separated by commas.
7025@ifclear GENERIC
7026@ifset W32
a4fb0134 7027For each expression, @command{@value{AS}} emits a 32-bit number.
252b5132
RH
7028@end ifset
7029@ifset W16
a4fb0134 7030For each expression, @command{@value{AS}} emits a 16-bit number.
252b5132
RH
7031@end ifset
7032@end ifclear
7033@ifset GENERIC
7034
7035The size of the number emitted, and its byte order,
7036depend on what target computer the assembly is for.
7037@end ifset
7038
7039@c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
7040@c happen---32-bit addressability, period; no long/short jumps.
7041@ifset DIFF-TBL-KLUGE
7042@cindex difference tables altered
7043@cindex altered difference tables
7044@quotation
7045@emph{Warning: Special Treatment to support Compilers}
7046@end quotation
7047
7048@ifset GENERIC
7049Machines with a 32-bit address space, but that do less than 32-bit
7050addressing, require the following special treatment. If the machine of
7051interest to you does 32-bit addressing (or doesn't require it;
7052@pxref{Machine Dependencies}), you can ignore this issue.
7053
7054@end ifset
7055In order to assemble compiler output into something that works,
a4fb0134 7056@command{@value{AS}} occasionally does strange things to @samp{.word} directives.
252b5132 7057Directives of the form @samp{.word sym1-sym2} are often emitted by
a4fb0134 7058compilers as part of jump tables. Therefore, when @command{@value{AS}} assembles a
252b5132 7059directive of the form @samp{.word sym1-sym2}, and the difference between
a4fb0134 7060@code{sym1} and @code{sym2} does not fit in 16 bits, @command{@value{AS}}
252b5132
RH
7061creates a @dfn{secondary jump table}, immediately before the next label.
7062This secondary jump table is preceded by a short-jump to the
7063first byte after the secondary table. This short-jump prevents the flow
7064of control from accidentally falling into the new table. Inside the
7065table is a long-jump to @code{sym2}. The original @samp{.word}
7066contains @code{sym1} minus the address of the long-jump to
7067@code{sym2}.
7068
7069If there were several occurrences of @samp{.word sym1-sym2} before the
7070secondary jump table, all of them are adjusted. If there was a
7071@samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
7072long-jump to @code{sym4} is included in the secondary jump table,
7073and the @code{.word} directives are adjusted to contain @code{sym3}
7074minus the address of the long-jump to @code{sym4}; and so on, for as many
7075entries in the original jump table as necessary.
7076
7077@ifset INTERNALS
a4fb0134 7078@emph{This feature may be disabled by compiling @command{@value{AS}} with the
252b5132
RH
7079@samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
7080assembly language programmers.
7081@end ifset
7082@end ifset
7083@c end DIFF-TBL-KLUGE
7084
7ce98c16
NC
7085@ifclear no-space-dir
7086@node Zero
7087@section @code{.zero @var{size}}
7088
7089@cindex @code{zero} directive
7090@cindex filling memory with zero bytes
7091This directive emits @var{size} 0-valued bytes. @var{size} must be an absolute
7092expression. This directive is actually an alias for the @samp{.skip} directive
7093so in can take an optional second argument of the value to store in the bytes
7094instead of zero. Using @samp{.zero} in this way would be confusing however.
7095@end ifclear
7096
252b5132
RH
7097@node Deprecated
7098@section Deprecated Directives
7099
7100@cindex deprecated directives
7101@cindex obsolescent directives
7102One day these directives won't work.
7103They are included for compatibility with older assemblers.
7104@table @t
7105@item .abort
7106@item .line
7107@end table
7108
3a99f02f
DJ
7109@ifset ELF
7110@node Object Attributes
7111@chapter Object Attributes
7112@cindex object attributes
7113
7114@command{@value{AS}} assembles source files written for a specific architecture
7115into object files for that architecture. But not all object files are alike.
7116Many architectures support incompatible variations. For instance, floating
7117point arguments might be passed in floating point registers if the object file
7118requires hardware floating point support---or floating point arguments might be
7119passed in integer registers if the object file supports processors with no
7120hardware floating point unit. Or, if two objects are built for different
7121generations of the same architecture, the combination may require the
7122newer generation at run-time.
7123
7124This information is useful during and after linking. At link time,
7125@command{@value{LD}} can warn about incompatible object files. After link
7126time, tools like @command{gdb} can use it to process the linked file
7127correctly.
7128
7129Compatibility information is recorded as a series of object attributes. Each
7130attribute has a @dfn{vendor}, @dfn{tag}, and @dfn{value}. The vendor is a
7131string, and indicates who sets the meaning of the tag. The tag is an integer,
7132and indicates what property the attribute describes. The value may be a string
7133or an integer, and indicates how the property affects this object. Missing
7134attributes are the same as attributes with a zero value or empty string value.
7135
7136Object attributes were developed as part of the ABI for the ARM Architecture.
7137The file format is documented in @cite{ELF for the ARM Architecture}.
7138
7139@menu
7140* GNU Object Attributes:: @sc{gnu} Object Attributes
7141* Defining New Object Attributes:: Defining New Object Attributes
7142@end menu
7143
7144@node GNU Object Attributes
7145@section @sc{gnu} Object Attributes
7146
7147The @code{.gnu_attribute} directive records an object attribute
7148with vendor @samp{gnu}.
7149
7150Except for @samp{Tag_compatibility}, which has both an integer and a string for
7151its value, @sc{gnu} attributes have a string value if the tag number is odd and
7152an integer value if the tag number is even. The second bit (@code{@var{tag} &
71532} is set for architecture-independent attributes and clear for
7154architecture-dependent ones.
7155
7156@subsection Common @sc{gnu} attributes
7157
7158These attributes are valid on all architectures.
7159
7160@table @r
7161@item Tag_compatibility (32)
7162The compatibility attribute takes an integer flag value and a vendor name. If
7163the flag value is 0, the file is compatible with other toolchains. If it is 1,
7164then the file is only compatible with the named toolchain. If it is greater
7165than 1, the file can only be processed by other toolchains under some private
7166arrangement indicated by the flag value and the vendor name.
7167@end table
7168
7169@subsection MIPS Attributes
7170
7171@table @r
7172@item Tag_GNU_MIPS_ABI_FP (4)
7173The floating-point ABI used by this object file. The value will be:
7174
7175@itemize @bullet
7176@item
71770 for files not affected by the floating-point ABI.
7178@item
f179c512
MF
71791 for files using the hardware floating-point ABI with a standard
7180double-precision FPU.
3a99f02f
DJ
7181@item
71822 for files using the hardware floating-point ABI with a single-precision FPU.
7183@item
71843 for files using the software floating-point ABI.
42554f6a 7185@item
f179c512
MF
71864 for files using the deprecated hardware floating-point ABI which used 64-bit
7187floating-point registers, 32-bit general-purpose registers and increased the
7188number of callee-saved floating-point registers.
7189@item
71905 for files using the hardware floating-point ABI with a double-precision FPU
7191with either 32-bit or 64-bit floating-point registers and 32-bit
7192general-purpose registers.
7193@item
71946 for files using the hardware floating-point ABI with 64-bit floating-point
7195registers and 32-bit general-purpose registers.
7196@item
71977 for files using the hardware floating-point ABI with 64-bit floating-point
7198registers, 32-bit general-purpose registers and a rule that forbids the
7199direct use of odd-numbered single-precision floating-point registers.
3a99f02f
DJ
7200@end itemize
7201@end table
7202
7203@subsection PowerPC Attributes
7204
7205@table @r
7206@item Tag_GNU_Power_ABI_FP (4)
7207The floating-point ABI used by this object file. The value will be:
7208
7209@itemize @bullet
7210@item
72110 for files not affected by the floating-point ABI.
7212@item
3c7b9897 72131 for files using double-precision hardware floating-point ABI.
3a99f02f
DJ
7214@item
72152 for files using the software floating-point ABI.
3c7b9897
AM
7216@item
72173 for files using single-precision hardware floating-point ABI.
3a99f02f
DJ
7218@end itemize
7219
7220@item Tag_GNU_Power_ABI_Vector (8)
7221The vector ABI used by this object file. The value will be:
7222
7223@itemize @bullet
7224@item
72250 for files not affected by the vector ABI.
7226@item
72271 for files using general purpose registers to pass vectors.
7228@item
72292 for files using AltiVec registers to pass vectors.
7230@item
72313 for files using SPE registers to pass vectors.
7232@end itemize
7233@end table
7234
643f7afb
AK
7235@subsection IBM z Systems Attributes
7236
7237@table @r
7238@item Tag_GNU_S390_ABI_Vector (8)
7239The vector ABI used by this object file. The value will be:
7240
7241@itemize @bullet
7242@item
72430 for files not affected by the vector ABI.
7244@item
72451 for files using software vector ABI.
7246@item
72472 for files using hardware vector ABI.
7248@end itemize
7249@end table
7250
3a99f02f
DJ
7251@node Defining New Object Attributes
7252@section Defining New Object Attributes
7253
7254If you want to define a new @sc{gnu} object attribute, here are the places you
7255will need to modify. New attributes should be discussed on the @samp{binutils}
7256mailing list.
7257
7258@itemize @bullet
7259@item
7260This manual, which is the official register of attributes.
7261@item
7262The header for your architecture @file{include/elf}, to define the tag.
7263@item
7264The @file{bfd} support file for your architecture, to merge the attribute
7265and issue any appropriate link warnings.
7266@item
7267Test cases in @file{ld/testsuite} for merging and link warnings.
7268@item
7269@file{binutils/readelf.c} to display your attribute.
7270@item
7271GCC, if you want the compiler to mark the attribute automatically.
7272@end itemize
7273
7274@end ifset
7275
252b5132
RH
7276@ifset GENERIC
7277@node Machine Dependencies
7278@chapter Machine Dependent Features
7279
7280@cindex machine dependencies
7281The machine instruction sets are (almost by definition) different on
a4fb0134
SC
7282each machine where @command{@value{AS}} runs. Floating point representations
7283vary as well, and @command{@value{AS}} often supports a few additional
252b5132
RH
7284directives or command-line options for compatibility with other
7285assemblers on a particular platform. Finally, some versions of
a4fb0134 7286@command{@value{AS}} support special pseudo-instructions for branch
252b5132
RH
7287optimization.
7288
7289This chapter discusses most of these differences, though it does not
7290include details on any machine's instruction set. For details on that
7291subject, see the hardware manufacturer's manual.
7292
7293@menu
a06ea964
NC
7294@ifset AARCH64
7295* AArch64-Dependent:: AArch64 Dependent Features
7296@end ifset
625e1353
RH
7297@ifset ALPHA
7298* Alpha-Dependent:: Alpha Dependent Features
7299@end ifset
252b5132
RH
7300@ifset ARC
7301* ARC-Dependent:: ARC Dependent Features
7302@end ifset
7303@ifset ARM
7304* ARM-Dependent:: ARM Dependent Features
7305@end ifset
8473f7a4
DC
7306@ifset AVR
7307* AVR-Dependent:: AVR Dependent Features
7308@end ifset
3b4e1885
JZ
7309@ifset Blackfin
7310* Blackfin-Dependent:: Blackfin Dependent Features
07c1b327 7311@end ifset
3d3d428f
NC
7312@ifset CR16
7313* CR16-Dependent:: CR16 Dependent Features
7314@end ifset
8bf549a8 7315@ifset CRIS
328eb32e
HPN
7316* CRIS-Dependent:: CRIS Dependent Features
7317@end ifset
252b5132
RH
7318@ifset D10V
7319* D10V-Dependent:: D10V Dependent Features
7320@end ifset
7321@ifset D30V
7322* D30V-Dependent:: D30V Dependent Features
7323@end ifset
cfb8c092
NC
7324@ifset EPIPHANY
7325* Epiphany-Dependent:: EPIPHANY Dependent Features
7326@end ifset
252b5132 7327@ifset H8/300
c2dcd04e 7328* H8/300-Dependent:: Renesas H8/300 Dependent Features
252b5132 7329@end ifset
252b5132
RH
7330@ifset HPPA
7331* HPPA-Dependent:: HPPA Dependent Features
7332@end ifset
5b93d8bb
AM
7333@ifset I370
7334* ESA/390-Dependent:: IBM ESA/390 Dependent Features
7335@end ifset
252b5132 7336@ifset I80386
55b62671 7337* i386-Dependent:: Intel 80386 and AMD x86-64 Dependent Features
252b5132 7338@end ifset
e3308d0d
JE
7339@ifset I860
7340* i860-Dependent:: Intel 80860 Dependent Features
7341@end ifset
252b5132
RH
7342@ifset I960
7343* i960-Dependent:: Intel 80960 Dependent Features
7344@end ifset
5cb53c21
L
7345@ifset IA64
7346* IA-64-Dependent:: Intel IA-64 Dependent Features
7347@end ifset
a40cbfa3
NC
7348@ifset IP2K
7349* IP2K-Dependent:: IP2K Dependent Features
7350@end ifset
84e94c90
NC
7351@ifset LM32
7352* LM32-Dependent:: LM32 Dependent Features
7353@end ifset
49f58d10
JB
7354@ifset M32C
7355* M32C-Dependent:: M32C Dependent Features
7356@end ifset
ec694b89
NC
7357@ifset M32R
7358* M32R-Dependent:: M32R Dependent Features
7359@end ifset
252b5132
RH
7360@ifset M680X0
7361* M68K-Dependent:: M680x0 Dependent Features
7362@end ifset
60bcf0fa
NC
7363@ifset M68HC11
7364* M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features
7365@end ifset
a3c62988
NC
7366@ifset METAG
7367* Meta-Dependent :: Meta Dependent Features
7368@end ifset
7ba29e2a
NC
7369@ifset MICROBLAZE
7370* MicroBlaze-Dependent:: MICROBLAZE Dependent Features
7371@end ifset
252b5132
RH
7372@ifset MIPS
7373* MIPS-Dependent:: MIPS Dependent Features
7374@end ifset
3c3bdf30
NC
7375@ifset MMIX
7376* MMIX-Dependent:: MMIX Dependent Features
7377@end ifset
2469cfa2
NC
7378@ifset MSP430
7379* MSP430-Dependent:: MSP430 Dependent Features
7380@end ifset
35c08157
KLC
7381@ifset NDS32
7382* NDS32-Dependent:: Andes NDS32 Dependent Features
7383@end ifset
36591ba1
SL
7384@ifset NIOSII
7385* NiosII-Dependent:: Altera Nios II Dependent Features
7386@end ifset
7c31ae13
NC
7387@ifset NS32K
7388* NS32K-Dependent:: NS32K Dependent Features
7389@end ifset
e135f41b
NC
7390@ifset PDP11
7391* PDP-11-Dependent:: PDP-11 Dependent Features
7392@end ifset
041dd5a9
ILT
7393@ifset PJ
7394* PJ-Dependent:: picoJava Dependent Features
7395@end ifset
418c1742
MG
7396@ifset PPC
7397* PPC-Dependent:: PowerPC Dependent Features
7398@end ifset
99c513f6
DD
7399@ifset RL78
7400* RL78-Dependent:: RL78 Dependent Features
7401@end ifset
046d31c2
NC
7402@ifset RX
7403* RX-Dependent:: RX Dependent Features
7404@end ifset
11c19e16
MS
7405@ifset S390
7406* S/390-Dependent:: IBM S/390 Dependent Features
7407@end ifset
c0157db4
NC
7408@ifset SCORE
7409* SCORE-Dependent:: SCORE Dependent Features
7410@end ifset
d3b47e2b
L
7411@ifset SH
7412* SH-Dependent:: Renesas / SuperH SH Dependent Features
7413* SH64-Dependent:: SuperH SH64 Dependent Features
7414@end ifset
252b5132
RH
7415@ifset SPARC
7416* Sparc-Dependent:: SPARC Dependent Features
7417@end ifset
39bec121
TW
7418@ifset TIC54X
7419* TIC54X-Dependent:: TI TMS320C54x Dependent Features
7420@end ifset
40b36596
JM
7421@ifset TIC6X
7422* TIC6X-Dependent :: TI TMS320C6x Dependent Features
7423@end ifset
aa137e4d
NC
7424@ifset TILEGX
7425* TILE-Gx-Dependent :: Tilera TILE-Gx Dependent Features
7426@end ifset
7427@ifset TILEPRO
7428* TILEPro-Dependent :: Tilera TILEPro Dependent Features
7429@end ifset
252b5132
RH
7430@ifset V850
7431* V850-Dependent:: V850 Dependent Features
7432@end ifset
b6605ddd
EB
7433@ifset VAX
7434* Vax-Dependent:: VAX Dependent Features
7435@end ifset
7436@ifset VISIUM
7437* Visium-Dependent:: Visium Dependent Features
7438@end ifset
f6c1a2d5
NC
7439@ifset XGATE
7440* XGATE-Dependent:: XGATE Features
7441@end ifset
6753e72f
NC
7442@ifset XSTORMY16
7443* XSTORMY16-Dependent:: XStormy16 Dependent Features
7444@end ifset
e0001a05
NC
7445@ifset XTENSA
7446* Xtensa-Dependent:: Xtensa Dependent Features
7447@end ifset
3c9b82ba
NC
7448@ifset Z80
7449* Z80-Dependent:: Z80 Dependent Features
7450@end ifset
252b5132
RH
7451@ifset Z8000
7452* Z8000-Dependent:: Z8000 Dependent Features
7453@end ifset
252b5132
RH
7454@end menu
7455
7456@lowersections
7457@end ifset
7458
7459@c The following major nodes are *sections* in the GENERIC version, *chapters*
7460@c in single-cpu versions. This is mainly achieved by @lowersections. There is a
7461@c peculiarity: to preserve cross-references, there must be a node called
7462@c "Machine Dependencies". Hence the conditional nodenames in each
7463@c major node below. Node defaulting in makeinfo requires adjacency of
7464@c node and sectioning commands; hence the repetition of @chapter BLAH
7465@c in both conditional blocks.
7466
a06ea964
NC
7467@ifset AARCH64
7468@include c-aarch64.texi
7469@end ifset
7470
625e1353
RH
7471@ifset ALPHA
7472@include c-alpha.texi
7473@end ifset
7474
7475@ifset ARC
7476@include c-arc.texi
7477@end ifset
7478
252b5132
RH
7479@ifset ARM
7480@include c-arm.texi
7481@end ifset
7482
8473f7a4
DC
7483@ifset AVR
7484@include c-avr.texi
7485@end ifset
7486
3b4e1885 7487@ifset Blackfin
07c1b327
CM
7488@include c-bfin.texi
7489@end ifset
7490
3d3d428f
NC
7491@ifset CR16
7492@include c-cr16.texi
7493@end ifset
7494
328eb32e
HPN
7495@ifset CRIS
7496@include c-cris.texi
7497@end ifset
7498
c2dcd04e 7499@ifset Renesas-all
252b5132
RH
7500@ifclear GENERIC
7501@node Machine Dependencies
7502@chapter Machine Dependent Features
7503
c2dcd04e 7504The machine instruction sets are different on each Renesas chip family,
252b5132 7505and there are also some syntax differences among the families. This
a4fb0134 7506chapter describes the specific @command{@value{AS}} features for each
252b5132
RH
7507family.
7508
7509@menu
c2dcd04e 7510* H8/300-Dependent:: Renesas H8/300 Dependent Features
c2dcd04e 7511* SH-Dependent:: Renesas SH Dependent Features
252b5132
RH
7512@end menu
7513@lowersections
7514@end ifclear
7515@end ifset
7516
7517@ifset D10V
7518@include c-d10v.texi
7519@end ifset
7520
7521@ifset D30V
7522@include c-d30v.texi
7523@end ifset
7524
cfb8c092
NC
7525@ifset EPIPHANY
7526@include c-epiphany.texi
7527@end ifset
7528
252b5132
RH
7529@ifset H8/300
7530@include c-h8300.texi
7531@end ifset
7532
252b5132
RH
7533@ifset HPPA
7534@include c-hppa.texi
7535@end ifset
7536
5b93d8bb
AM
7537@ifset I370
7538@include c-i370.texi
7539@end ifset
7540
252b5132
RH
7541@ifset I80386
7542@include c-i386.texi
7543@end ifset
7544
e3308d0d
JE
7545@ifset I860
7546@include c-i860.texi
7547@end ifset
7548
252b5132
RH
7549@ifset I960
7550@include c-i960.texi
7551@end ifset
7552
9e32ca89
NC
7553@ifset IA64
7554@include c-ia64.texi
7555@end ifset
7556
a40cbfa3
NC
7557@ifset IP2K
7558@include c-ip2k.texi
7559@end ifset
7560
84e94c90
NC
7561@ifset LM32
7562@include c-lm32.texi
7563@end ifset
7564
49f58d10
JB
7565@ifset M32C
7566@include c-m32c.texi
7567@end ifset
7568
ec694b89
NC
7569@ifset M32R
7570@include c-m32r.texi
7571@end ifset
252b5132
RH
7572
7573@ifset M680X0
7574@include c-m68k.texi
7575@end ifset
7576
60bcf0fa
NC
7577@ifset M68HC11
7578@include c-m68hc11.texi
7579@end ifset
7580
a3c62988
NC
7581@ifset METAG
7582@include c-metag.texi
7583@end ifset
7584
01642c12 7585@ifset MICROBLAZE
7ba29e2a
NC
7586@include c-microblaze.texi
7587@end ifset
7588
252b5132
RH
7589@ifset MIPS
7590@include c-mips.texi
7591@end ifset
7592
3c3bdf30
NC
7593@ifset MMIX
7594@include c-mmix.texi
7595@end ifset
7596
2469cfa2
NC
7597@ifset MSP430
7598@include c-msp430.texi
7599@end ifset
7600
35c08157
KLC
7601@ifset NDS32
7602@include c-nds32.texi
7603@end ifset
7604
36591ba1
SL
7605@ifset NIOSII
7606@include c-nios2.texi
7607@end ifset
7608
252b5132
RH
7609@ifset NS32K
7610@include c-ns32k.texi
7611@end ifset
7612
e135f41b
NC
7613@ifset PDP11
7614@include c-pdp11.texi
7615@end ifset
7616
041dd5a9
ILT
7617@ifset PJ
7618@include c-pj.texi
7619@end ifset
7620
418c1742
MG
7621@ifset PPC
7622@include c-ppc.texi
7623@end ifset
7624
99c513f6
DD
7625@ifset RL78
7626@include c-rl78.texi
7627@end ifset
7628
046d31c2
NC
7629@ifset RX
7630@include c-rx.texi
7631@end ifset
7632
11c19e16
MS
7633@ifset S390
7634@include c-s390.texi
7635@end ifset
7636
c0157db4
NC
7637@ifset SCORE
7638@include c-score.texi
7639@end ifset
7640
252b5132
RH
7641@ifset SH
7642@include c-sh.texi
324bfcf3 7643@include c-sh64.texi
252b5132
RH
7644@end ifset
7645
7646@ifset SPARC
7647@include c-sparc.texi
7648@end ifset
7649
39bec121
TW
7650@ifset TIC54X
7651@include c-tic54x.texi
7652@end ifset
7653
40b36596
JM
7654@ifset TIC6X
7655@include c-tic6x.texi
7656@end ifset
7657
aa137e4d
NC
7658@ifset TILEGX
7659@include c-tilegx.texi
7660@end ifset
7661
7662@ifset TILEPRO
7663@include c-tilepro.texi
7664@end ifset
7665
b6605ddd
EB
7666@ifset V850
7667@include c-v850.texi
252b5132
RH
7668@end ifset
7669
7670@ifset VAX
7671@include c-vax.texi
7672@end ifset
7673
b6605ddd
EB
7674@ifset VISIUM
7675@include c-visium.texi
252b5132
RH
7676@end ifset
7677
f6c1a2d5
NC
7678@ifset XGATE
7679@include c-xgate.texi
7680@end ifset
7681
6753e72f
NC
7682@ifset XSTORMY16
7683@include c-xstormy16.texi
7684@end ifset
7685
e0001a05
NC
7686@ifset XTENSA
7687@include c-xtensa.texi
7688@end ifset
7689
b6605ddd
EB
7690@ifset Z80
7691@include c-z80.texi
7692@end ifset
7693
7694@ifset Z8000
7695@include c-z8k.texi
7696@end ifset
7697
252b5132
RH
7698@ifset GENERIC
7699@c reverse effect of @down at top of generic Machine-Dep chapter
7700@raisesections
7701@end ifset
7702
7703@node Reporting Bugs
7704@chapter Reporting Bugs
7705@cindex bugs in assembler
7706@cindex reporting bugs in assembler
7707
a4fb0134 7708Your bug reports play an essential role in making @command{@value{AS}} reliable.
252b5132
RH
7709
7710Reporting a bug may help you by bringing a solution to your problem, or it may
7711not. But in any case the principal function of a bug report is to help the
a4fb0134
SC
7712entire community by making the next version of @command{@value{AS}} work better.
7713Bug reports are your contribution to the maintenance of @command{@value{AS}}.
252b5132
RH
7714
7715In order for a bug report to serve its purpose, you must include the
7716information that enables us to fix the bug.
7717
7718@menu
7719* Bug Criteria:: Have you found a bug?
7720* Bug Reporting:: How to report bugs
7721@end menu
7722
7723@node Bug Criteria
c1253627 7724@section Have You Found a Bug?
252b5132
RH
7725@cindex bug criteria
7726
7727If you are not sure whether you have found a bug, here are some guidelines:
7728
7729@itemize @bullet
7730@cindex fatal signal
7731@cindex assembler crash
7732@cindex crash of assembler
7733@item
7734If the assembler gets a fatal signal, for any input whatever, that is a
a4fb0134 7735@command{@value{AS}} bug. Reliable assemblers never crash.
252b5132
RH
7736
7737@cindex error on valid input
7738@item
a4fb0134 7739If @command{@value{AS}} produces an error message for valid input, that is a bug.
252b5132
RH
7740
7741@cindex invalid input
7742@item
a4fb0134 7743If @command{@value{AS}} does not produce an error message for invalid input, that
252b5132
RH
7744is a bug. However, you should note that your idea of ``invalid input'' might
7745be our idea of ``an extension'' or ``support for traditional practice''.
7746
7747@item
7748If you are an experienced user of assemblers, your suggestions for improvement
a4fb0134 7749of @command{@value{AS}} are welcome in any case.
252b5132
RH
7750@end itemize
7751
7752@node Bug Reporting
c1253627 7753@section How to Report Bugs
252b5132
RH
7754@cindex bug reports
7755@cindex assembler bugs, reporting
7756
7757A number of companies and individuals offer support for @sc{gnu} products. If
a4fb0134 7758you obtained @command{@value{AS}} from a support organization, we recommend you
252b5132
RH
7759contact that organization first.
7760
7761You can find contact information for many support companies and
7762individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
7763distribution.
7764
ad22bfe8 7765@ifset BUGURL
a4fb0134 7766In any event, we also recommend that you send bug reports for @command{@value{AS}}
ad22bfe8
JM
7767to @value{BUGURL}.
7768@end ifset
252b5132
RH
7769
7770The fundamental principle of reporting bugs usefully is this:
7771@strong{report all the facts}. If you are not sure whether to state a
7772fact or leave it out, state it!
7773
7774Often people omit facts because they think they know what causes the problem
7775and assume that some details do not matter. Thus, you might assume that the
7776name of a symbol you use in an example does not matter. Well, probably it does
7777not, but one cannot be sure. Perhaps the bug is a stray memory reference which
7778happens to fetch from the location where that name is stored in memory;
7779perhaps, if the name were different, the contents of that location would fool
7780the assembler into doing the right thing despite the bug. Play it safe and
7781give a specific, complete example. That is the easiest thing for you to do,
7782and the most helpful.
7783
7784Keep in mind that the purpose of a bug report is to enable us to fix the bug if
7785it is new to us. Therefore, always write your bug reports on the assumption
7786that the bug has not been reported previously.
7787
7788Sometimes people give a few sketchy facts and ask, ``Does this ring a
c1253627
NC
7789bell?'' This cannot help us fix a bug, so it is basically useless. We
7790respond by asking for enough details to enable us to investigate.
7791You might as well expedite matters by sending them to begin with.
252b5132
RH
7792
7793To enable us to fix the bug, you should include all these things:
7794
7795@itemize @bullet
7796@item
a4fb0134 7797The version of @command{@value{AS}}. @command{@value{AS}} announces it if you start
252b5132
RH
7798it with the @samp{--version} argument.
7799
7800Without this, we will not know whether there is any point in looking for
a4fb0134 7801the bug in the current version of @command{@value{AS}}.
252b5132
RH
7802
7803@item
a4fb0134 7804Any patches you may have applied to the @command{@value{AS}} source.
252b5132
RH
7805
7806@item
7807The type of machine you are using, and the operating system name and
7808version number.
7809
7810@item
a4fb0134 7811What compiler (and its version) was used to compile @command{@value{AS}}---e.g.
252b5132
RH
7812``@code{gcc-2.7}''.
7813
7814@item
7815The command arguments you gave the assembler to assemble your example and
7816observe the bug. To guarantee you will not omit something important, list them
7817all. A copy of the Makefile (or the output from make) is sufficient.
7818
7819If we were to try to guess the arguments, we would probably guess wrong
7820and then we might not encounter the bug.
7821
7822@item
7823A complete input file that will reproduce the bug. If the bug is observed when
7824the assembler is invoked via a compiler, send the assembler source, not the
7825high level language source. Most compilers will produce the assembler source
7826when run with the @samp{-S} option. If you are using @code{@value{GCC}}, use
7827the options @samp{-v --save-temps}; this will save the assembler source in a
7828file with an extension of @file{.s}, and also show you exactly how
a4fb0134 7829@command{@value{AS}} is being run.
252b5132
RH
7830
7831@item
7832A description of what behavior you observe that you believe is
7833incorrect. For example, ``It gets a fatal signal.''
7834
a4fb0134 7835Of course, if the bug is that @command{@value{AS}} gets a fatal signal, then we
252b5132
RH
7836will certainly notice it. But if the bug is incorrect output, we might not
7837notice unless it is glaringly wrong. You might as well not give us a chance to
7838make a mistake.
7839
7840Even if the problem you experience is a fatal signal, you should still say so
7841explicitly. Suppose something strange is going on, such as, your copy of
b45619c0 7842@command{@value{AS}} is out of sync, or you have encountered a bug in the C
252b5132
RH
7843library on your system. (This has happened!) Your copy might crash and ours
7844would not. If you told us to expect a crash, then when ours fails to crash, we
7845would know that the bug was not happening for us. If you had not told us to
7846expect a crash, then we would not be able to draw any conclusion from our
7847observations.
7848
7849@item
a4fb0134 7850If you wish to suggest changes to the @command{@value{AS}} source, send us context
252b5132
RH
7851diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
7852option. Always send diffs from the old file to the new file. If you even
a4fb0134 7853discuss something in the @command{@value{AS}} source, refer to it by context, not
252b5132
RH
7854by line number.
7855
7856The line numbers in our development sources will not match those in your
7857sources. Your line numbers would convey no useful information to us.
7858@end itemize
7859
7860Here are some things that are not necessary:
7861
7862@itemize @bullet
7863@item
7864A description of the envelope of the bug.
7865
7866Often people who encounter a bug spend a lot of time investigating
7867which changes to the input file will make the bug go away and which
7868changes will not affect it.
7869
7870This is often time consuming and not very useful, because the way we
7871will find the bug is by running a single example under the debugger
7872with breakpoints, not by pure deduction from a series of examples.
7873We recommend that you save your time for something else.
7874
7875Of course, if you can find a simpler example to report @emph{instead}
7876of the original one, that is a convenience for us. Errors in the
7877output will be easier to spot, running under the debugger will take
7878less time, and so on.
7879
7880However, simplification is not vital; if you do not want to do this,
7881report the bug anyway and send us the entire test case you used.
7882
7883@item
7884A patch for the bug.
7885
7886A patch for the bug does help us if it is a good one. But do not omit
7887the necessary information, such as the test case, on the assumption that
7888a patch is all we need. We might see problems with your patch and decide
7889to fix the problem another way, or we might not understand it at all.
7890
a4fb0134 7891Sometimes with a program as complicated as @command{@value{AS}} it is very hard to
252b5132
RH
7892construct an example that will make the program follow a certain path through
7893the code. If you do not send us the example, we will not be able to construct
7894one, so we will not be able to verify that the bug is fixed.
7895
7896And if we cannot understand what bug you are trying to fix, or why your
7897patch should be an improvement, we will not install it. A test case will
7898help us to understand.
7899
7900@item
7901A guess about what the bug is or what it depends on.
7902
7903Such guesses are usually wrong. Even we cannot guess right about such
7904things without first using the debugger to find the facts.
7905@end itemize
7906
7907@node Acknowledgements
7908@chapter Acknowledgements
7909
653cfe85 7910If you have contributed to GAS and your name isn't listed here,
252b5132 7911it is not meant as a slight. We just don't know about it. Send mail to the
01642c12 7912maintainer, and we'll correct the situation. Currently
3bfcb652
NC
7913@c (October 2012),
7914the maintainer is Nick Clifton (email address @code{nickc@@redhat.com}).
252b5132
RH
7915
7916Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any
7917more details?}
7918
7919Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
7920information and the 68k series machines, most of the preprocessing pass, and
7921extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}.
7922
7923K. Richard Pixley maintained GAS for a while, adding various enhancements and
7924many bug fixes, including merging support for several processors, breaking GAS
7925up to handle multiple object file format back ends (including heavy rewrite,
7926testing, an integration of the coff and b.out back ends), adding configuration
7927including heavy testing and verification of cross assemblers and file splits
7928and renaming, converted GAS to strictly ANSI C including full prototypes, added
7929support for m680[34]0 and cpu32, did considerable work on i960 including a COFF
7930port (including considerable amounts of reverse engineering), a SPARC opcode
7931file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know''
7932assertions and made them work, much other reorganization, cleanup, and lint.
7933
7934Ken Raeburn wrote the high-level BFD interface code to replace most of the code
7935in format-specific I/O modules.
7936
7937The original VMS support was contributed by David L. Kashtan. Eric Youngdale
7938has done much work with it since.
7939
7940The Intel 80386 machine description was written by Eliot Dresselhaus.
7941
7942Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
7943
7944The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
7945University and Torbjorn Granlund of the Swedish Institute of Computer Science.
7946
7947Keith Knowles at the Open Software Foundation wrote the original MIPS back end
7948(@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support
7949(which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to
7950support a.out format.
7951
7be1c489
AM
7952Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k,
7953tc-h8300), and IEEE 695 object file format (obj-ieee), was written by
252b5132
RH
7954Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
7955use BFD for some low-level operations, for use with the H8/300 and AMD 29k
7956targets.
7957
7958John Gilmore built the AMD 29000 support, added @code{.include} support, and
7959simplified the configuration of which versions accept which directives. He
7960updated the 68k machine description so that Motorola's opcodes always produced
c1253627 7961fixed-size instructions (e.g., @code{jsr}), while synthetic instructions
252b5132
RH
7962remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested
7963cross-compilation support, and one bug in relaxation that took a week and
7964required the proverbial one-bit fix.
7965
7966Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
796768k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
7968added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and
7969PowerPC assembler, and made a few other minor patches.
7970
653cfe85 7971Steve Chamberlain made GAS able to generate listings.
252b5132
RH
7972
7973Hewlett-Packard contributed support for the HP9000/300.
7974
7975Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
7976along with a fairly extensive HPPA testsuite (for both SOM and ELF object
7977formats). This work was supported by both the Center for Software Science at
7978the University of Utah and Cygnus Support.
7979
7980Support for ELF format files has been worked on by Mark Eichin of Cygnus
7981Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
7982Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
7983Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
7984and some initial 64-bit support).
7985
c1253627 7986Linas Vepstas added GAS support for the ESA/390 ``IBM 370'' architecture.
5b93d8bb 7987
252b5132
RH
7988Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD
7989support for openVMS/Alpha.
7990
39bec121
TW
7991Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic*
7992flavors.
7993
e0001a05 7994David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica,
b45619c0 7995Inc.@: added support for Xtensa processors.
e0001a05 7996
252b5132
RH
7997Several engineers at Cygnus Support have also provided many small bug fixes and
7998configuration enhancements.
7999
84e94c90
NC
8000Jon Beniston added support for the Lattice Mico32 architecture.
8001
252b5132
RH
8002Many others have contributed large or small bugfixes and enhancements. If
8003you have contributed significant work and are not mentioned on this list, and
8004want to be, let us know. Some of the history has been lost; we are not
8005intentionally leaving anyone out.
8006
793c5807
NC
8007@node GNU Free Documentation License
8008@appendix GNU Free Documentation License
c1253627 8009@include fdl.texi
cf055d54 8010
370b66a1
CD
8011@node AS Index
8012@unnumbered AS Index
252b5132
RH
8013
8014@printindex cp
8015
252b5132
RH
8016@bye
8017@c Local Variables:
8018@c fill-column: 79
8019@c End:
This page took 1.249295 seconds and 4 git commands to generate.