* Makefile.am (Makefile): Move the dependency on
[deliverable/binutils-gdb.git] / gas / doc / as.texinfo
CommitLineData
252b5132 1\input texinfo @c -*-Texinfo-*-
f7e42eb4 2@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
d88ef7a6 3@c 2001, 2002, 2003
252b5132
RH
4@c Free Software Foundation, Inc.
5@c UPDATE!! On future updates--
6@c (1) check for new machine-dep cmdline options in
7@c md_parse_option definitions in config/tc-*.c
8@c (2) for platform-specific directives, examine md_pseudo_op
9@c in config/tc-*.c
10@c (3) for object-format specific directives, examine obj_pseudo_op
11@c in config/obj-*.c
12@c (4) portable directives in potable[] in read.c
13@c %**start of header
14@setfilename as.info
15@c ---config---
a4fb0134
SC
16@macro gcctabopt{body}
17@code{\body\}
18@end macro
252b5132
RH
19@c defaults, config file may override:
20@set have-stabs
21@c ---
22@include asconfig.texi
23@include gasver.texi
24@c ---
0285c67d
NC
25@c man begin NAME
26@ifset man
27@c Configure for the generation of man pages
28@set AS as
29@set TARGET TARGET
30@set GENERIC
31@set A29K
625e1353 32@set ALPHA
0285c67d
NC
33@set ARC
34@set ARM
328eb32e 35@set CRIS
0285c67d
NC
36@set D10V
37@set D30V
38@set H8/300
39@set H8/500
40@set HPPA
41@set I370
42@set I80386
43@set I860
44@set I960
9e32ca89 45@set IA-64
a40cbfa3 46@set IP2K
0285c67d
NC
47@set M32R
48@set M68HC11
49@set M680X0
81b0b3f1 50@set M880X0
0285c67d
NC
51@set MCORE
52@set MIPS
3c3bdf30 53@set MMIX
0285c67d
NC
54@set PDP11
55@set PJ
418c1742 56@set PPC
0285c67d
NC
57@set SH
58@set SPARC
9418ab9c 59@set TIC54X
0285c67d
NC
60@set V850
61@set VAX
e0001a05 62@set XTENSA
0285c67d
NC
63@end ifset
64@c man end
252b5132 65@c common OR combinations of conditions
c1253627
NC
66@ifset COFF
67@set COFF-ELF
68@end ifset
69@ifset ELF
70@set COFF-ELF
71@end ifset
252b5132
RH
72@ifset AOUT
73@set aout-bout
74@end ifset
75@ifset ARM/Thumb
76@set ARM
77@end ifset
78@ifset BOUT
79@set aout-bout
80@end ifset
81@ifset H8/300
82@set H8
83@end ifset
84@ifset H8/500
85@set H8
86@end ifset
87@ifset SH
88@set H8
89@end ifset
90@ifset HPPA
91@set abnormal-separator
92@end ifset
93@c ------------
94@ifset GENERIC
95@settitle Using @value{AS}
96@end ifset
97@ifclear GENERIC
98@settitle Using @value{AS} (@value{TARGET})
99@end ifclear
100@setchapternewpage odd
101@c %**end of header
102
103@c @smallbook
104@c @set SMALL
105@c WARE! Some of the machine-dependent sections contain tables of machine
106@c instructions. Except in multi-column format, these tables look silly.
107@c Unfortunately, Texinfo doesn't have a general-purpose multi-col format, so
108@c the multi-col format is faked within @example sections.
109@c
110@c Again unfortunately, the natural size that fits on a page, for these tables,
111@c is different depending on whether or not smallbook is turned on.
112@c This matters, because of order: text flow switches columns at each page
113@c break.
114@c
115@c The format faked in this source works reasonably well for smallbook,
116@c not well for the default large-page format. This manual expects that if you
117@c turn on @smallbook, you will also uncomment the "@set SMALL" to enable the
118@c tables in question. You can turn on one without the other at your
119@c discretion, of course.
120@ifinfo
121@set SMALL
122@c the insn tables look just as silly in info files regardless of smallbook,
123@c might as well show 'em anyways.
124@end ifinfo
125
126@ifinfo
127@format
128START-INFO-DIR-ENTRY
129* As: (as). The GNU assembler.
59455fb1 130* Gas: (as). The GNU assembler.
252b5132
RH
131END-INFO-DIR-ENTRY
132@end format
133@end ifinfo
134
135@finalout
136@syncodeindex ky cp
137
138@ifinfo
139This file documents the GNU Assembler "@value{AS}".
140
0285c67d 141@c man begin COPYRIGHT
973eb340 142Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002 Free Software Foundation, Inc.
252b5132 143
0285c67d
NC
144Permission is granted to copy, distribute and/or modify this document
145under the terms of the GNU Free Documentation License, Version 1.1
146or any later version published by the Free Software Foundation;
147with no Invariant Sections, with no Front-Cover Texts, and with no
148Back-Cover Texts. A copy of the license is included in the
c1253627 149section entitled ``GNU Free Documentation License''.
0285c67d
NC
150
151@c man end
252b5132
RH
152
153@ignore
154Permission is granted to process this file through Tex and print the
155results, provided the printed document carries copying permission
156notice identical to this one except for the removal of this paragraph
157(this paragraph not being relevant to the printed manual).
158
159@end ignore
252b5132
RH
160@end ifinfo
161
162@titlepage
163@title Using @value{AS}
164@subtitle The @sc{gnu} Assembler
165@ifclear GENERIC
166@subtitle for the @value{TARGET} family
167@end ifclear
168@sp 1
169@subtitle Version @value{VERSION}
170@sp 1
171@sp 13
172The Free Software Foundation Inc. thanks The Nice Computer
173Company of Australia for loaning Dean Elsner to write the
a4fb0134 174first (Vax) version of @command{as} for Project @sc{gnu}.
252b5132
RH
175The proprietors, management and staff of TNCCA thank FSF for
176distracting the boss while they got some work
177done.
178@sp 3
179@author Dean Elsner, Jay Fenlason & friends
180@page
181@tex
182{\parskip=0pt
183\hfill {\it Using {\tt @value{AS}}}\par
184\hfill Edited by Cygnus Support\par
185}
186%"boxit" macro for figures:
187%Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3)
188\gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt
189 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil
190#2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline
191\gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box
192@end tex
193
194@vskip 0pt plus 1filll
973eb340 195Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002 Free Software Foundation, Inc.
252b5132 196
cf055d54
NC
197 Permission is granted to copy, distribute and/or modify this document
198 under the terms of the GNU Free Documentation License, Version 1.1
199 or any later version published by the Free Software Foundation;
200 with no Invariant Sections, with no Front-Cover Texts, and with no
201 Back-Cover Texts. A copy of the license is included in the
c1253627 202 section entitled ``GNU Free Documentation License''.
252b5132 203
252b5132
RH
204@end titlepage
205
2e64b665 206@ifnottex
252b5132
RH
207@node Top
208@top Using @value{AS}
209
a4fb0134 210This file is a user guide to the @sc{gnu} assembler @command{@value{AS}} version
252b5132
RH
211@value{VERSION}.
212@ifclear GENERIC
a4fb0134 213This version of the file describes @command{@value{AS}} configured to generate
252b5132
RH
214code for @value{TARGET} architectures.
215@end ifclear
cf055d54
NC
216
217This document is distributed under the terms of the GNU Free
218Documentation License. A copy of the license is included in the
c1253627 219section entitled ``GNU Free Documentation License''.
cf055d54 220
252b5132
RH
221@menu
222* Overview:: Overview
223* Invoking:: Command-Line Options
224* Syntax:: Syntax
225* Sections:: Sections and Relocation
226* Symbols:: Symbols
227* Expressions:: Expressions
228* Pseudo Ops:: Assembler Directives
229* Machine Dependencies:: Machine Dependent Features
230* Reporting Bugs:: Reporting Bugs
231* Acknowledgements:: Who Did What
cf055d54 232* GNU Free Documentation License:: GNU Free Documentation License
252b5132
RH
233* Index:: Index
234@end menu
2e64b665 235@end ifnottex
252b5132
RH
236
237@node Overview
238@chapter Overview
239@iftex
a4fb0134 240This manual is a user guide to the @sc{gnu} assembler @command{@value{AS}}.
252b5132 241@ifclear GENERIC
a4fb0134 242This version of the manual describes @command{@value{AS}} configured to generate
252b5132
RH
243code for @value{TARGET} architectures.
244@end ifclear
245@end iftex
246
247@cindex invocation summary
248@cindex option summary
249@cindex summary of options
a4fb0134 250Here is a brief summary of how to invoke @command{@value{AS}}. For details,
8dfa0188 251@pxref{Invoking,,Command-Line Options}.
252b5132 252
0285c67d
NC
253@c man title AS the portable GNU assembler.
254
a4fb0134 255@ignore
0285c67d
NC
256@c man begin SEEALSO
257gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}.
258@c man end
a4fb0134 259@end ignore
0285c67d 260
252b5132
RH
261@c We don't use deffn and friends for the following because they seem
262@c to be limited to one line for the header.
263@smallexample
0285c67d 264@c man begin SYNOPSIS
a4fb0134 265@value{AS} [@b{-a}[@b{cdhlns}][=@var{file}]] [@b{-D}] [@b{--defsym} @var{sym}=@var{val}]
05da4302
NC
266 [@b{-f}] [@b{--gstabs}] [@b{--gstabs+}] [@b{--gdwarf2}] [@b{--help}]
267 [@b{-I} @var{dir}] [@b{-J}] [@b{-K}] [@b{-L}]
a4fb0134
SC
268 [@b{--listing-lhs-width}=@var{NUM}] [@b{--listing-lhs-width2}=@var{NUM}]
269 [@b{--listing-rhs-width}=@var{NUM}] [@b{--listing-cont-lines}=@var{NUM}]
270 [@b{--keep-locals}] [@b{-o} @var{objfile}] [@b{-R}] [@b{--statistics}] [@b{-v}]
271 [@b{-version}] [@b{--version}] [@b{-W}] [@b{--warn}] [@b{--fatal-warnings}]
272 [@b{-w}] [@b{-x}] [@b{-Z}] [@b{--target-help}] [@var{target-options}]
273 [@b{--}|@var{files} @dots{}]
274@c
275@c Target dependent options are listed below. Keep the list sorted.
276@c Add an empty line for separation.
252b5132
RH
277@ifset A29K
278@c am29k has no machine-dependent assembler options
279@end ifset
625e1353
RH
280@ifset ALPHA
281
282@emph{Target Alpha options:}
283 [@b{-m@var{cpu}}]
284 [@b{-mdebug} | @b{-no-mdebug}]
285 [@b{-relax}] [@b{-g}] [@b{-G@var{size}}]
286 [@b{-F}] [@b{-32addr}]
287@end ifset
252b5132 288@ifset ARC
a4fb0134
SC
289
290@emph{Target ARC options:}
291 [@b{-marc[5|6|7|8]}]
292 [@b{-EB}|@b{-EL}]
252b5132
RH
293@end ifset
294@ifset ARM
a4fb0134
SC
295
296@emph{Target ARM options:}
03b1477f 297@c Don't document the deprecated options
92081f48
HPN
298 [@b{-mcpu}=@var{processor}[+@var{extension}@dots{}]]
299 [@b{-march}=@var{architecture}[+@var{extension}@dots{}]]
33a392fb
PB
300 [@b{-mfpu}=@var{floating-point-format}]
301 [@b{-mfloat-abi}=@var{abi}]
03b1477f 302 [@b{-mthumb}]
a4fb0134
SC
303 [@b{-EB}|@b{-EL}]
304 [@b{-mapcs-32}|@b{-mapcs-26}|@b{-mapcs-float}|
305 @b{-mapcs-reentrant}]
306 [@b{-mthumb-interwork}] [@b{-moabi}] [@b{-k}]
252b5132 307@end ifset
328eb32e
HPN
308@ifset CRIS
309
310@emph{Target CRIS options:}
311 [@b{--underscore} | @b{--no-underscore}]
312 [@b{--pic}] [@b{-N}]
313 [@b{--emulation=criself} | @b{--emulation=crisaout}]
314@c Deprecated -- deliberately not documented.
315@c [@b{-h}] [@b{-H}]
316@end ifset
252b5132 317@ifset D10V
a4fb0134
SC
318
319@emph{Target D10V options:}
320 [@b{-O}]
252b5132
RH
321@end ifset
322@ifset D30V
a4fb0134
SC
323
324@emph{Target D30V options:}
325 [@b{-O}|@b{-n}|@b{-N}]
252b5132
RH
326@end ifset
327@ifset H8
c2dcd04e 328@c Renesas family chips have no machine-dependent assembler options
252b5132
RH
329@end ifset
330@ifset HPPA
331@c HPPA has no machine-dependent assembler options (yet).
332@end ifset
a4fb0134
SC
333@ifset I80386
334
335@emph{Target i386 options:}
12b55ccc 336 [@b{--32}|@b{--64}] [@b{-n}]
252b5132
RH
337@end ifset
338@ifset I960
a4fb0134
SC
339
340@emph{Target i960 options:}
252b5132 341@c see md_parse_option in tc-i960.c
a4fb0134
SC
342 [@b{-ACA}|@b{-ACA_A}|@b{-ACB}|@b{-ACC}|@b{-AKA}|@b{-AKB}|
343 @b{-AKC}|@b{-AMC}]
344 [@b{-b}] [@b{-no-relax}]
252b5132 345@end ifset
587fe2b3 346@ifset IA64
a4fb0134 347
9e32ca89
NC
348@emph{Target IA-64 options:}
349 [@b{-mconstant-gp}|@b{-mauto-pic}]
350 [@b{-milp32}|@b{-milp64}|@b{-mlp64}|@b{-mp64}]
351 [@b{-mle}|@b{mbe}]
352 [@b{-x}|@b{-xexplicit}] [@b{-xauto}] [@b{-xdebug}]
353@end ifset
a40cbfa3
NC
354@ifset IP2K
355
356@emph{Target IP2K options:}
357 [@b{-mip2022}|@b{-mip2022ext}]
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:}
d01030e6 373 [@b{-m68hc11}|@b{-m68hc12}|@b{-m68hcs12}]
2f904664
SC
374 [@b{-mshort}|@b{-mlong}]
375 [@b{-mshort-double}|@b{-mlong-double}]
a4fb0134
SC
376 [@b{--force-long-branchs}] [@b{--short-branchs}]
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
252b5132 386@ifset MIPS
a4fb0134
SC
387
388@emph{Target MIPS options:}
437ee9d5
TS
389 [@b{-nocpp}] [@b{-EL}] [@b{-EB}] [@b{-n}] [@b{-O}[@var{optimization level}]]
390 [@b{-g}[@var{debug level}]] [@b{-G} @var{num}] [@b{-KPIC}] [@b{-call_shared}]
391 [@b{-non_shared}] [@b{-xgot}] [@b{--membedded-pic}]
392 [@b{-mabi}=@var{ABI}] [@b{-32}] [@b{-n32}] [@b{-64}] [@b{-mfp32}] [@b{-mgp32}]
393 [@b{-march}=@var{CPU}] [@b{-mtune}=@var{CPU}] [@b{-mips1}] [@b{-mips2}]
af7ee8bf 394 [@b{-mips3}] [@b{-mips4}] [@b{-mips5}] [@b{-mips32}] [@b{-mips32r2}]
5f74bc13 395 [@b{-mips64}] [@b{-mips64r2}]
437ee9d5
TS
396 [@b{-construct-floats}] [@b{-no-construct-floats}]
397 [@b{-trap}] [@b{-no-break}] [@b{-break}] [@b{-no-trap}]
398 [@b{-mfix7000}] [@b{-mno-fix7000}]
399 [@b{-mips16}] [@b{-no-mips16}]
1f25f5d3 400 [@b{-mips3d}] [@b{-no-mips3d}]
deec1734 401 [@b{-mdmx}] [@b{-no-mdmx}]
ecb4347a 402 [@b{-mdebug}] [@b{-no-mdebug}]
dcd410fe 403 [@b{-mpdr}] [@b{-mno-pdr}]
3c3bdf30
NC
404@end ifset
405@ifset MMIX
a4fb0134
SC
406
407@emph{Target MMIX options:}
408 [@b{--fixed-special-register-names}] [@b{--globalize-symbols}]
409 [@b{--gnu-syntax}] [@b{--relax}] [@b{--no-predefined-symbols}]
410 [@b{--no-expand}] [@b{--no-merge-gregs}] [@b{-x}]
973eb340 411 [@b{--linker-allocated-gregs}]
a4fb0134
SC
412@end ifset
413@ifset PDP11
414
415@emph{Target PDP11 options:}
416 [@b{-mpic}|@b{-mno-pic}] [@b{-mall}] [@b{-mno-extensions}]
417 [@b{-m}@var{extension}|@b{-mno-}@var{extension}]
418 [@b{-m}@var{cpu}] [@b{-m}@var{machine}]
419@end ifset
420@ifset PJ
421
422@emph{Target picoJava options:}
423 [@b{-mb}|@b{-me}]
424@end ifset
425@ifset PPC
426
427@emph{Target PowerPC options:}
428 [@b{-mpwrx}|@b{-mpwr2}|@b{-mpwr}|@b{-m601}|@b{-mppc}|@b{-mppc32}|@b{-m603}|@b{-m604}|
429 @b{-m403}|@b{-m405}|@b{-mppc64}|@b{-m620}|@b{-mppc64bridge}|@b{-mbooke}|
430 @b{-mbooke32}|@b{-mbooke64}]
431 [@b{-mcom}|@b{-many}|@b{-maltivec}] [@b{-memb}]
432 [@b{-mregnames}|@b{-mno-regnames}]
433 [@b{-mrelocatable}|@b{-mrelocatable-lib}]
434 [@b{-mlittle}|@b{-mlittle-endian}|@b{-mbig}|@b{-mbig-endian}]
435 [@b{-msolaris}|@b{-mno-solaris}]
436@end ifset
437@ifset SPARC
438
439@emph{Target SPARC options:}
440@c The order here is important. See c-sparc.texi.
441 [@b{-Av6}|@b{-Av7}|@b{-Av8}|@b{-Asparclet}|@b{-Asparclite}
442 @b{-Av8plus}|@b{-Av8plusa}|@b{-Av9}|@b{-Av9a}]
443 [@b{-xarch=v8plus}|@b{-xarch=v8plusa}] [@b{-bump}]
444 [@b{-32}|@b{-64}]
445@end ifset
446@ifset TIC54X
447
448@emph{Target TIC54X options:}
449 [@b{-mcpu=54[123589]}|@b{-mcpu=54[56]lp}] [@b{-mfar-mode}|@b{-mf}]
450 [@b{-merrors-to-file} @var{<filename>}|@b{-me} @var{<filename>}]
451@end ifset
452@ifset Z8000
453@c Z8000 has no machine-dependent assembler options
252b5132 454@end ifset
e0001a05
NC
455@ifset XTENSA
456
457@emph{Target Xtensa options:}
458 [@b{--[no-]density}] [@b{--[no-]relax}] [@b{--[no-]generics}]
459 [@b{--[no-]text-section-literals}]
460 [@b{--[no-]target-align}] [@b{--[no-]longcalls}]
461@end ifset
0285c67d 462@c man end
252b5132
RH
463@end smallexample
464
0285c67d
NC
465@c man begin OPTIONS
466
a4fb0134 467@table @gcctabopt
252b5132
RH
468@item -a[cdhlmns]
469Turn on listings, in any of a variety of ways:
470
a4fb0134 471@table @gcctabopt
252b5132
RH
472@item -ac
473omit false conditionals
474
475@item -ad
476omit debugging directives
477
478@item -ah
479include high-level source
480
481@item -al
482include assembly
483
484@item -am
485include macro expansions
486
487@item -an
488omit forms processing
489
490@item -as
491include symbols
492
493@item =file
494set the name of the listing file
495@end table
496
497You may combine these options; for example, use @samp{-aln} for assembly
498listing without forms processing. The @samp{=file} option, if used, must be
499the last one. By itself, @samp{-a} defaults to @samp{-ahls}.
500
501@item -D
502Ignored. This option is accepted for script compatibility with calls to
503other assemblers.
504
505@item --defsym @var{sym}=@var{value}
506Define the symbol @var{sym} to be @var{value} before assembling the input file.
507@var{value} must be an integer constant. As in C, a leading @samp{0x}
508indicates a hexadecimal value, and a leading @samp{0} indicates an octal value.
509
510@item -f
511``fast''---skip whitespace and comment preprocessing (assume source is
512compiler output).
513
514@item --gstabs
515Generate stabs debugging information for each assembler line. This
516may help debugging assembler code, if the debugger can handle it.
517
05da4302
NC
518@item --gstabs+
519Generate stabs debugging information for each assembler line, with GNU
520extensions that probably only gdb can handle, and that could make other
521debuggers crash or refuse to read your program. This
522may help debugging assembler code. Currently the only GNU extension is
523the location of the current working directory at assembling time.
524
cdf82bcf
NC
525@item --gdwarf2
526Generate DWARF2 debugging information for each assembler line. This
c1253627 527may help debugging assembler code, if the debugger can handle it. Note---this
85a39694 528option is only supported by some targets, not all of them.
cdf82bcf 529
252b5132
RH
530@item --help
531Print a summary of the command line options and exit.
532
ea20a7da
CC
533@item --target-help
534Print a summary of all target specific options and exit.
535
252b5132
RH
536@item -I @var{dir}
537Add directory @var{dir} to the search list for @code{.include} directives.
538
539@item -J
540Don't warn about signed overflow.
541
542@item -K
543@ifclear DIFF-TBL-KLUGE
544This option is accepted but has no effect on the @value{TARGET} family.
545@end ifclear
546@ifset DIFF-TBL-KLUGE
547Issue warnings when difference tables altered for long displacements.
548@end ifset
549
550@item -L
551@itemx --keep-locals
552Keep (in the symbol table) local symbols. On traditional a.out systems
553these start with @samp{L}, but different systems have different local
554label prefixes.
555
c3a27914
NC
556@item --listing-lhs-width=@var{number}
557Set the maximum width, in words, of the output data column for an assembler
558listing to @var{number}.
559
560@item --listing-lhs-width2=@var{number}
561Set the maximum width, in words, of the output data column for continuation
562lines in an assembler listing to @var{number}.
563
564@item --listing-rhs-width=@var{number}
565Set the maximum width of an input source line, as displayed in a listing, to
566@var{number} bytes.
567
568@item --listing-cont-lines=@var{number}
569Set the maximum number of lines printed in a listing for a single line of input
570to @var{number} + 1.
571
252b5132 572@item -o @var{objfile}
a4fb0134 573Name the object-file output from @command{@value{AS}} @var{objfile}.
252b5132
RH
574
575@item -R
576Fold the data section into the text section.
577
578@item --statistics
579Print the maximum space (in bytes) and total time (in seconds) used by
580assembly.
581
582@item --strip-local-absolute
583Remove local absolute symbols from the outgoing symbol table.
584
585@item -v
586@itemx -version
a4fb0134 587Print the @command{as} version.
252b5132
RH
588
589@item --version
a4fb0134 590Print the @command{as} version and exit.
252b5132
RH
591
592@item -W
2bdd6cf5 593@itemx --no-warn
252b5132
RH
594Suppress warning messages.
595
2bdd6cf5
GK
596@item --fatal-warnings
597Treat warnings as errors.
598
599@item --warn
600Don't suppress warning messages or treat them as errors.
601
252b5132
RH
602@item -w
603Ignored.
604
605@item -x
606Ignored.
607
608@item -Z
609Generate an object file even after errors.
610
611@item -- | @var{files} @dots{}
612Standard input, or source files to assemble.
613
614@end table
615
616@ifset ARC
617The following options are available when @value{AS} is configured for
618an ARC processor.
619
a4fb0134 620@table @gcctabopt
0d2bcfaf
NC
621@item -marc[5|6|7|8]
622This option selects the core processor variant.
623@item -EB | -EL
624Select either big-endian (-EB) or little-endian (-EL) output.
252b5132
RH
625@end table
626@end ifset
627
628@ifset ARM
629The following options are available when @value{AS} is configured for the ARM
630processor family.
631
a4fb0134 632@table @gcctabopt
92081f48 633@item -mcpu=@var{processor}[+@var{extension}@dots{}]
cdf82bcf 634Specify which ARM processor variant is the target.
92081f48 635@item -march=@var{architecture}[+@var{extension}@dots{}]
cdf82bcf 636Specify which ARM architecture variant is used by the target.
03b1477f 637@item -mfpu=@var{floating-point-format}
a349d9dd 638Select which Floating Point architecture is the target.
33a392fb
PB
639@item -mfloat-abi=@var{abi}
640Select which floating point ABI is in use.
03b1477f
RE
641@item -mthumb
642Enable Thumb only instruction decoding.
cdf82bcf 643@item -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant | -moabi
252b5132
RH
644Select which procedure calling convention is in use.
645@item -EB | -EL
646Select either big-endian (-EB) or little-endian (-EL) output.
cdf82bcf
NC
647@item -mthumb-interwork
648Specify that the code has been generated with interworking between Thumb and
649ARM code in mind.
650@item -k
651Specify that PIC code has been generated.
252b5132
RH
652@end table
653@end ifset
654
328eb32e
HPN
655@ifset CRIS
656See the info pages for documentation of the CRIS-specific options.
657@end ifset
658
252b5132
RH
659@ifset D10V
660The following options are available when @value{AS} is configured for
661a D10V processor.
a4fb0134 662@table @gcctabopt
252b5132
RH
663@cindex D10V optimization
664@cindex optimization, D10V
665@item -O
666Optimize output by parallelizing instructions.
667@end table
668@end ifset
669
670@ifset D30V
671The following options are available when @value{AS} is configured for a D30V
672processor.
a4fb0134 673@table @gcctabopt
252b5132
RH
674@cindex D30V optimization
675@cindex optimization, D30V
676@item -O
677Optimize output by parallelizing instructions.
678
679@cindex D30V nops
680@item -n
681Warn when nops are generated.
682
683@cindex D30V nops after 32-bit multiply
684@item -N
685Warn when a nop after a 32-bit multiply instruction is generated.
686@end table
687@end ifset
688
689@ifset I960
690The following options are available when @value{AS} is configured for the
691Intel 80960 processor.
692
a4fb0134 693@table @gcctabopt
252b5132
RH
694@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
695Specify which variant of the 960 architecture is the target.
696
697@item -b
698Add code to collect statistics about branches taken.
699
700@item -no-relax
701Do not alter compare-and-branch instructions for long displacements;
702error if necessary.
703
704@end table
705@end ifset
706
a40cbfa3
NC
707@ifset IP2K
708The following options are available when @value{AS} is configured for the
ec88d317 709Ubicom IP2K series.
a40cbfa3
NC
710
711@table @gcctabopt
712
713@item -mip2022ext
714Specifies that the extended IP2022 instructions are allowed.
715
716@item -mip2022
8dfa0188 717Restores the default behaviour, which restricts the permitted instructions to
a40cbfa3
NC
718just the basic IP2022 ones.
719
720@end table
721@end ifset
722
ec694b89
NC
723@ifset M32R
724The following options are available when @value{AS} is configured for the
26597c86 725Renesas M32R (formerly Mitsubishi M32R) series.
ec694b89 726
a4fb0134 727@table @gcctabopt
ec694b89
NC
728
729@item --m32rx
730Specify which processor in the M32R family is the target. The default
731is normally the M32R, but this option changes it to the M32RX.
732
733@item --warn-explicit-parallel-conflicts or --Wp
734Produce warning messages when questionable parallel constructs are
735encountered.
736
737@item --no-warn-explicit-parallel-conflicts or --Wnp
738Do not produce warning messages when questionable parallel constructs are
739encountered.
740
741@end table
742@end ifset
252b5132
RH
743
744@ifset M680X0
745The following options are available when @value{AS} is configured for the
746Motorola 68000 series.
747
a4fb0134 748@table @gcctabopt
252b5132
RH
749
750@item -l
751Shorten references to undefined symbols, to one word instead of two.
752
0285c67d
NC
753@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030
754@itemx | -m68040 | -m68060 | -m68302 | -m68331 | -m68332
755@itemx | -m68333 | -m68340 | -mcpu32 | -m5200
252b5132
RH
756Specify what processor in the 68000 family is the target. The default
757is normally the 68020, but this can be changed at configuration time.
758
759@item -m68881 | -m68882 | -mno-68881 | -mno-68882
760The target machine does (or does not) have a floating-point coprocessor.
761The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
762the basic 68000 is not compatible with the 68881, a combination of the
763two can be specified, since it's possible to do emulation of the
764coprocessor instructions with the main processor.
765
766@item -m68851 | -mno-68851
767The target machine does (or does not) have a memory-management
768unit coprocessor. The default is to assume an MMU for 68020 and up.
769
770@end table
771@end ifset
772
e135f41b
NC
773@ifset PDP11
774
775For details about the PDP-11 machine dependent features options,
776see @ref{PDP-11-Options}.
777
a4fb0134 778@table @gcctabopt
e135f41b
NC
779@item -mpic | -mno-pic
780Generate position-independent (or position-dependent) code. The
a4fb0134 781default is @option{-mpic}.
e135f41b
NC
782
783@item -mall
784@itemx -mall-extensions
785Enable all instruction set extensions. This is the default.
786
787@item -mno-extensions
788Disable all instruction set extensions.
789
790@item -m@var{extension} | -mno-@var{extension}
791Enable (or disable) a particular instruction set extension.
792
793@item -m@var{cpu}
794Enable the instruction set extensions supported by a particular CPU, and
795disable all other extensions.
796
797@item -m@var{machine}
798Enable the instruction set extensions supported by a particular machine
799model, and disable all other extensions.
800@end table
801
802@end ifset
803
041dd5a9
ILT
804@ifset PJ
805The following options are available when @value{AS} is configured for
806a picoJava processor.
807
a4fb0134 808@table @gcctabopt
041dd5a9
ILT
809
810@cindex PJ endianness
811@cindex endianness, PJ
812@cindex big endian output, PJ
813@item -mb
814Generate ``big endian'' format output.
815
816@cindex little endian output, PJ
817@item -ml
818Generate ``little endian'' format output.
819
820@end table
821@end ifset
822
60bcf0fa
NC
823@ifset M68HC11
824The following options are available when @value{AS} is configured for the
825Motorola 68HC11 or 68HC12 series.
826
a4fb0134 827@table @gcctabopt
60bcf0fa 828
d01030e6 829@item -m68hc11 | -m68hc12 | -m68hcs12
60bcf0fa
NC
830Specify what processor is the target. The default is
831defined by the configuration option when building the assembler.
832
2f904664
SC
833@item -mshort
834Specify to use the 16-bit integer ABI.
835
836@item -mlong
837Specify to use the 32-bit integer ABI.
838
839@item -mshort-double
840Specify to use the 32-bit double ABI.
841
842@item -mlong-double
843Specify to use the 64-bit double ABI.
844
60bcf0fa
NC
845@item --force-long-branchs
846Relative branches are turned into absolute ones. This concerns
847conditional branches, unconditional branches and branches to a
848sub routine.
849
850@item -S | --short-branchs
851Do not turn relative branchs into absolute ones
852when the offset is out of range.
853
854@item --strict-direct-mode
855Do not turn the direct addressing mode into extended addressing mode
856when the instruction does not support direct addressing mode.
857
858@item --print-insn-syntax
859Print the syntax of instruction in case of error.
860
861@item --print-opcodes
862print the list of instructions with syntax and then exit.
863
864@item --generate-example
865print an example of instruction for each possible instruction and then exit.
a4fb0134 866This option is only useful for testing @command{@value{AS}}.
60bcf0fa
NC
867
868@end table
869@end ifset
870
252b5132 871@ifset SPARC
a4fb0134 872The following options are available when @command{@value{AS}} is configured
252b5132
RH
873for the SPARC architecture:
874
a4fb0134 875@table @gcctabopt
252b5132
RH
876@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
877@itemx -Av8plus | -Av8plusa | -Av9 | -Av9a
878Explicitly select a variant of the SPARC architecture.
879
880@samp{-Av8plus} and @samp{-Av8plusa} select a 32 bit environment.
881@samp{-Av9} and @samp{-Av9a} select a 64 bit environment.
882
883@samp{-Av8plusa} and @samp{-Av9a} enable the SPARC V9 instruction set with
884UltraSPARC extensions.
885
886@item -xarch=v8plus | -xarch=v8plusa
887For compatibility with the Solaris v9 assembler. These options are
888equivalent to -Av8plus and -Av8plusa, respectively.
889
890@item -bump
891Warn when the assembler switches to another architecture.
892@end table
893@end ifset
894
39bec121
TW
895@ifset TIC54X
896The following options are available when @value{AS} is configured for the 'c54x
897architecture.
898
a4fb0134 899@table @gcctabopt
39bec121
TW
900@item -mfar-mode
901Enable extended addressing mode. All addresses and relocations will assume
902extended addressing (usually 23 bits).
903@item -mcpu=@var{CPU_VERSION}
904Sets the CPU version being compiled for.
905@item -merrors-to-file @var{FILENAME}
906Redirect error output to a file, for broken systems which don't support such
907behaviour in the shell.
908@end table
909@end ifset
910
252b5132
RH
911@ifset MIPS
912The following options are available when @value{AS} is configured for
437ee9d5 913a @sc{mips} processor.
252b5132 914
a4fb0134 915@table @gcctabopt
252b5132
RH
916@item -G @var{num}
917This option sets the largest size of an object that can be referenced
918implicitly with the @code{gp} register. It is only accepted for targets that
919use ECOFF format, such as a DECstation running Ultrix. The default value is 8.
920
921@cindex MIPS endianness
922@cindex endianness, MIPS
923@cindex big endian output, MIPS
924@item -EB
925Generate ``big endian'' format output.
926
927@cindex little endian output, MIPS
928@item -EL
929Generate ``little endian'' format output.
930
931@cindex MIPS ISA
932@item -mips1
933@itemx -mips2
934@itemx -mips3
e7af610e 935@itemx -mips4
437ee9d5 936@itemx -mips5
e7af610e 937@itemx -mips32
af7ee8bf 938@itemx -mips32r2
4058e45f 939@itemx -mips64
5f74bc13 940@itemx -mips64r2
437ee9d5
TS
941Generate code for a particular @sc{mips} Instruction Set Architecture level.
942@samp{-mips1} is an alias for @samp{-march=r3000}, @samp{-mips2} is an
943alias for @samp{-march=r6000}, @samp{-mips3} is an alias for
944@samp{-march=r4000} and @samp{-mips4} is an alias for @samp{-march=r8000}.
5f74bc13
CD
945@samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, @samp{-mips64}, and
946@samp{-mips64r2}
af7ee8bf 947correspond to generic
5f74bc13
CD
948@samp{MIPS V}, @samp{MIPS32}, @samp{MIPS32 Release 2}, @samp{MIPS64},
949and @samp{MIPS64 Release 2}
950ISA processors, respectively.
437ee9d5
TS
951
952@item -march=@var{CPU}
953Generate code for a particular @sc{mips} cpu.
954
955@item -mtune=@var{cpu}
956Schedule and tune for a particular @sc{mips} cpu.
957
958@item -mfix7000
959@itemx -mno-fix7000
960Cause nops to be inserted if the read of the destination register
961of an mfhi or mflo instruction occurs in the following two instructions.
962
ecb4347a
DJ
963@item -mdebug
964@itemx -no-mdebug
965Cause stabs-style debugging output to go into an ECOFF-style .mdebug
966section instead of the standard ELF .stabs sections.
967
dcd410fe
RO
968@item -mpdr
969@itemx -mno-pdr
970Control generation of @code{.pdr} sections.
971
437ee9d5
TS
972@item -mgp32
973@itemx -mfp32
974The register sizes are normally inferred from the ISA and ABI, but these
975flags force a certain group of registers to be treated as 32 bits wide at
976all times. @samp{-mgp32} controls the size of general-purpose registers
977and @samp{-mfp32} controls the size of floating-point registers.
978
979@item -mips16
980@itemx -no-mips16
981Generate code for the MIPS 16 processor. This is equivalent to putting
982@code{.set mips16} at the start of the assembly file. @samp{-no-mips16}
983turns off this option.
252b5132 984
1f25f5d3
CD
985@item -mips3d
986@itemx -no-mips3d
987Generate code for the MIPS-3D Application Specific Extension.
988This tells the assembler to accept MIPS-3D instructions.
989@samp{-no-mips3d} turns off this option.
990
deec1734
CD
991@item -mdmx
992@itemx -no-mdmx
993Generate code for the MDMX Application Specific Extension.
994This tells the assembler to accept MDMX instructions.
995@samp{-no-mdmx} turns off this option.
996
437ee9d5
TS
997@item --construct-floats
998@itemx --no-construct-floats
999The @samp{--no-construct-floats} option disables the construction of
1000double width floating point constants by loading the two halves of the
1001value into the two single width floating point registers that make up
1002the double width register. By default @samp{--construct-floats} is
1003selected, allowing construction of these floating point constants.
252b5132
RH
1004
1005@cindex emulation
1006@item --emulation=@var{name}
a4fb0134 1007This option causes @command{@value{AS}} to emulate @command{@value{AS}} configured
252b5132
RH
1008for some other target, in all respects, including output format (choosing
1009between ELF and ECOFF only), handling of pseudo-opcodes which may generate
1010debugging information or store symbol table information, and default
1011endianness. The available configuration names are: @samp{mipsecoff},
1012@samp{mipself}, @samp{mipslecoff}, @samp{mipsbecoff}, @samp{mipslelf},
1013@samp{mipsbelf}. The first two do not alter the default endianness from that
1014of the primary target for which the assembler was configured; the others change
1015the default to little- or big-endian as indicated by the @samp{b} or @samp{l}
1016in the name. Using @samp{-EB} or @samp{-EL} will override the endianness
1017selection in any case.
1018
1019This option is currently supported only when the primary target
437ee9d5 1020@command{@value{AS}} is configured for is a @sc{mips} ELF or ECOFF target.
252b5132
RH
1021Furthermore, the primary target or others specified with
1022@samp{--enable-targets=@dots{}} at configuration time must include support for
1023the other format, if both are to be available. For example, the Irix 5
1024configuration includes support for both.
1025
1026Eventually, this option will support more configurations, with more
1027fine-grained control over the assembler's behavior, and will be supported for
1028more processors.
1029
1030@item -nocpp
a4fb0134 1031@command{@value{AS}} ignores this option. It is accepted for compatibility with
252b5132
RH
1032the native tools.
1033
252b5132
RH
1034@item --trap
1035@itemx --no-trap
1036@itemx --break
1037@itemx --no-break
1038Control how to deal with multiplication overflow and division by zero.
1039@samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception
1040(and only work for Instruction Set Architecture level 2 and higher);
1041@samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a
1042break exception.
63486801
L
1043
1044@item -n
a4fb0134 1045When this option is used, @command{@value{AS}} will issue a warning every
63486801 1046time it generates a nop instruction from a macro.
252b5132
RH
1047@end table
1048@end ifset
1049
1050@ifset MCORE
1051The following options are available when @value{AS} is configured for
1052an MCore processor.
1053
a4fb0134 1054@table @gcctabopt
252b5132
RH
1055@item -jsri2bsr
1056@itemx -nojsri2bsr
1057Enable or disable the JSRI to BSR transformation. By default this is enabled.
1058The command line option @samp{-nojsri2bsr} can be used to disable it.
1059
1060@item -sifilter
1061@itemx -nosifilter
1062Enable or disable the silicon filter behaviour. By default this is disabled.
a349d9dd 1063The default can be overridden by the @samp{-sifilter} command line option.
252b5132
RH
1064
1065@item -relax
1066Alter jump instructions for long displacements.
1067
ec694b89
NC
1068@item -mcpu=[210|340]
1069Select the cpu type on the target hardware. This controls which instructions
1070can be assembled.
1071
1072@item -EB
1073Assemble for a big endian target.
1074
1075@item -EL
1076Assemble for a little endian target.
252b5132
RH
1077
1078@end table
1079@end ifset
1080
3c3bdf30
NC
1081@ifset MMIX
1082See the info pages for documentation of the MMIX-specific options.
1083@end ifset
1084
e0001a05
NC
1085@ifset XTENSA
1086The following options are available when @value{AS} is configured for
1087an Xtensa processor.
1088
1089@table @gcctabopt
1090@item --density | --no-density
1091Enable or disable use of instructions from the Xtensa code density
1092option. This is enabled by default when the Xtensa processor supports
1093the code density option.
1094
1095@item --relax | --no-relax
1096Enable or disable instruction relaxation. This is enabled by default.
1097Note: In the current implementation, these options also control whether
1098assembler optimizations are performed, making these options equivalent
1099to @option{--generics} and @option{--no-generics}.
1100
1101@item --generics | --no-generics
1102Enable or disable all assembler transformations of Xtensa instructions.
1103The default is @option{--generics};
1104@option{--no-generics} should be used only in the rare cases when the
1105instructions must be exactly as specified in the assembly source.
1106
1107@item --text-section-literals | --no-text-section-literals
1108With @option{--text-@-section-@-literals}, literal pools are interspersed
1109in the text section. The default is
1110@option{--no-@-text-@-section-@-literals}, which places literals in a
1111separate section in the output file.
1112
1113@item --target-align | --no-target-align
1114Enable or disable automatic alignment to reduce branch penalties at the
1115expense of some code density. The default is @option{--target-@-align}.
1116
1117@item --longcalls | --no-longcalls
1118Enable or disable transformation of call instructions to allow calls
1119across a greater range of addresses. The default is
1120@option{--no-@-longcalls}.
1121@end table
1122@end ifset
1123
0285c67d
NC
1124@c man end
1125
252b5132
RH
1126@menu
1127* Manual:: Structure of this Manual
1128* GNU Assembler:: The GNU Assembler
1129* Object Formats:: Object File Formats
1130* Command Line:: Command Line
1131* Input Files:: Input Files
1132* Object:: Output (Object) File
1133* Errors:: Error and Warning Messages
1134@end menu
1135
1136@node Manual
1137@section Structure of this Manual
1138
1139@cindex manual, structure and purpose
1140This manual is intended to describe what you need to know to use
a4fb0134 1141@sc{gnu} @command{@value{AS}}. We cover the syntax expected in source files, including
252b5132 1142notation for symbols, constants, and expressions; the directives that
a4fb0134 1143@command{@value{AS}} understands; and of course how to invoke @command{@value{AS}}.
252b5132
RH
1144
1145@ifclear GENERIC
1146We also cover special features in the @value{TARGET}
a4fb0134 1147configuration of @command{@value{AS}}, including assembler directives.
252b5132
RH
1148@end ifclear
1149@ifset GENERIC
1150This manual also describes some of the machine-dependent features of
1151various flavors of the assembler.
1152@end ifset
1153
1154@cindex machine instructions (not covered)
1155On the other hand, this manual is @emph{not} intended as an introduction
1156to programming in assembly language---let alone programming in general!
1157In a similar vein, we make no attempt to introduce the machine
1158architecture; we do @emph{not} describe the instruction set, standard
1159mnemonics, registers or addressing modes that are standard to a
1160particular architecture.
1161@ifset GENERIC
1162You may want to consult the manufacturer's
1163machine architecture manual for this information.
1164@end ifset
1165@ifclear GENERIC
1166@ifset H8/300
1167For information on the H8/300 machine instruction set, see @cite{H8/300
c2dcd04e
NC
1168Series Programming Manual}. For the H8/300H, see @cite{H8/300H Series
1169Programming Manual} (Renesas).
252b5132
RH
1170@end ifset
1171@ifset H8/500
1172For information on the H8/500 machine instruction set, see @cite{H8/500
c2dcd04e 1173Series Programming Manual} (Renesas M21T001).
252b5132
RH
1174@end ifset
1175@ifset SH
ef230218
JR
1176For information on the Renesas (formerly Hitachi) / SuperH SH machine instruction set,
1177see @cite{SH-Microcomputer User's Manual} (Renesas) or
1178@cite{SH-4 32-bit CPU Core Architecture} (SuperH) and
1179@cite{SuperH (SH) 64-Bit RISC Series} (SuperH).
252b5132
RH
1180@end ifset
1181@ifset Z8000
1182For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual}
1183@end ifset
1184@end ifclear
1185
1186@c I think this is premature---doc@cygnus.com, 17jan1991
1187@ignore
1188Throughout this manual, we assume that you are running @dfn{GNU},
1189the portable operating system from the @dfn{Free Software
1190Foundation, Inc.}. This restricts our attention to certain kinds of
1191computer (in particular, the kinds of computers that @sc{gnu} can run on);
1192once this assumption is granted examples and definitions need less
1193qualification.
1194
a4fb0134 1195@command{@value{AS}} is part of a team of programs that turn a high-level
252b5132
RH
1196human-readable series of instructions into a low-level
1197computer-readable series of instructions. Different versions of
a4fb0134 1198@command{@value{AS}} are used for different kinds of computer.
252b5132
RH
1199@end ignore
1200
1201@c There used to be a section "Terminology" here, which defined
1202@c "contents", "byte", "word", and "long". Defining "word" to any
1203@c particular size is confusing when the .word directive may generate 16
1204@c bits on one machine and 32 bits on another; in general, for the user
1205@c version of this manual, none of these terms seem essential to define.
1206@c They were used very little even in the former draft of the manual;
1207@c this draft makes an effort to avoid them (except in names of
1208@c directives).
1209
1210@node GNU Assembler
1211@section The GNU Assembler
1212
0285c67d
NC
1213@c man begin DESCRIPTION
1214
a4fb0134 1215@sc{gnu} @command{as} is really a family of assemblers.
252b5132 1216@ifclear GENERIC
a4fb0134 1217This manual describes @command{@value{AS}}, a member of that family which is
252b5132
RH
1218configured for the @value{TARGET} architectures.
1219@end ifclear
1220If you use (or have used) the @sc{gnu} assembler on one architecture, you
1221should find a fairly similar environment when you use it on another
1222architecture. Each version has much in common with the others,
1223including object file formats, most assembler directives (often called
1224@dfn{pseudo-ops}) and assembler syntax.@refill
1225
1226@cindex purpose of @sc{gnu} assembler
a4fb0134 1227@command{@value{AS}} is primarily intended to assemble the output of the
252b5132 1228@sc{gnu} C compiler @code{@value{GCC}} for use by the linker
a4fb0134 1229@code{@value{LD}}. Nevertheless, we've tried to make @command{@value{AS}}
252b5132
RH
1230assemble correctly everything that other assemblers for the same
1231machine would assemble.
1232@ifset VAX
1233Any exceptions are documented explicitly (@pxref{Machine Dependencies}).
1234@end ifset
1235@ifset M680X0
1236@c This remark should appear in generic version of manual; assumption
1237@c here is that generic version sets M680x0.
a4fb0134 1238This doesn't mean @command{@value{AS}} always uses the same syntax as another
252b5132
RH
1239assembler for the same architecture; for example, we know of several
1240incompatible versions of 680x0 assembly language syntax.
1241@end ifset
1242
0285c67d
NC
1243@c man end
1244
a4fb0134 1245Unlike older assemblers, @command{@value{AS}} is designed to assemble a source
252b5132
RH
1246program in one pass of the source file. This has a subtle impact on the
1247@kbd{.org} directive (@pxref{Org,,@code{.org}}).
1248
1249@node Object Formats
1250@section Object File Formats
1251
1252@cindex object file format
1253The @sc{gnu} assembler can be configured to produce several alternative
1254object file formats. For the most part, this does not affect how you
1255write assembly language programs; but directives for debugging symbols
1256are typically different in different file formats. @xref{Symbol
1257Attributes,,Symbol Attributes}.
1258@ifclear GENERIC
1259@ifclear MULTI-OBJ
c1253627 1260For the @value{TARGET} target, @command{@value{AS}} is configured to produce
252b5132
RH
1261@value{OBJ-NAME} format object files.
1262@end ifclear
1263@c The following should exhaust all configs that set MULTI-OBJ, ideally
1264@ifset A29K
a4fb0134 1265On the @value{TARGET}, @command{@value{AS}} can be configured to produce either
252b5132
RH
1266@code{a.out} or COFF format object files.
1267@end ifset
1268@ifset I960
a4fb0134 1269On the @value{TARGET}, @command{@value{AS}} can be configured to produce either
252b5132
RH
1270@code{b.out} or COFF format object files.
1271@end ifset
1272@ifset HPPA
a4fb0134 1273On the @value{TARGET}, @command{@value{AS}} can be configured to produce either
252b5132
RH
1274SOM or ELF format object files.
1275@end ifset
1276@end ifclear
1277
1278@node Command Line
1279@section Command Line
1280
1281@cindex command line conventions
0285c67d 1282
a4fb0134 1283After the program name @command{@value{AS}}, the command line may contain
252b5132
RH
1284options and file names. Options may appear in any order, and may be
1285before, after, or between file names. The order of file names is
1286significant.
1287
1288@cindex standard input, as input file
1289@kindex --
1290@file{--} (two hyphens) by itself names the standard input file
a4fb0134 1291explicitly, as one of the files for @command{@value{AS}} to assemble.
252b5132
RH
1292
1293@cindex options, command line
1294Except for @samp{--} any command line argument that begins with a
1295hyphen (@samp{-}) is an option. Each option changes the behavior of
a4fb0134 1296@command{@value{AS}}. No option changes the way another option works. An
252b5132
RH
1297option is a @samp{-} followed by one or more letters; the case of
1298the letter is important. All options are optional.
1299
1300Some options expect exactly one file name to follow them. The file
1301name may either immediately follow the option's letter (compatible
1302with older assemblers) or it may be the next command argument (@sc{gnu}
1303standard). These two command lines are equivalent:
1304
1305@smallexample
1306@value{AS} -o my-object-file.o mumble.s
1307@value{AS} -omy-object-file.o mumble.s
1308@end smallexample
1309
1310@node Input Files
1311@section Input Files
1312
1313@cindex input
1314@cindex source program
1315@cindex files, input
1316We use the phrase @dfn{source program}, abbreviated @dfn{source}, to
a4fb0134 1317describe the program input to one run of @command{@value{AS}}. The program may
252b5132
RH
1318be in one or more files; how the source is partitioned into files
1319doesn't change the meaning of the source.
1320
1321@c I added "con" prefix to "catenation" just to prove I can overcome my
1322@c APL training... doc@cygnus.com
1323The source program is a concatenation of the text in all the files, in the
1324order specified.
1325
0285c67d 1326@c man begin DESCRIPTION
a4fb0134 1327Each time you run @command{@value{AS}} it assembles exactly one source
252b5132
RH
1328program. The source program is made up of one or more files.
1329(The standard input is also a file.)
1330
a4fb0134 1331You give @command{@value{AS}} a command line that has zero or more input file
252b5132
RH
1332names. The input files are read (from left file name to right). A
1333command line argument (in any position) that has no special meaning
1334is taken to be an input file name.
1335
a4fb0134
SC
1336If you give @command{@value{AS}} no file names it attempts to read one input file
1337from the @command{@value{AS}} standard input, which is normally your terminal. You
1338may have to type @key{ctl-D} to tell @command{@value{AS}} there is no more program
252b5132
RH
1339to assemble.
1340
1341Use @samp{--} if you need to explicitly name the standard input file
1342in your command line.
1343
a4fb0134 1344If the source is empty, @command{@value{AS}} produces a small, empty object
252b5132
RH
1345file.
1346
0285c67d
NC
1347@c man end
1348
252b5132
RH
1349@subheading Filenames and Line-numbers
1350
1351@cindex input file linenumbers
1352@cindex line numbers, in input files
1353There are two ways of locating a line in the input file (or files) and
1354either may be used in reporting error messages. One way refers to a line
1355number in a physical file; the other refers to a line number in a
1356``logical'' file. @xref{Errors, ,Error and Warning Messages}.
1357
1358@dfn{Physical files} are those files named in the command line given
a4fb0134 1359to @command{@value{AS}}.
252b5132
RH
1360
1361@dfn{Logical files} are simply names declared explicitly by assembler
1362directives; they bear no relation to physical files. Logical file names help
a4fb0134
SC
1363error messages reflect the original source file, when @command{@value{AS}} source
1364is itself synthesized from other files. @command{@value{AS}} understands the
252b5132
RH
1365@samp{#} directives emitted by the @code{@value{GCC}} preprocessor. See also
1366@ref{File,,@code{.file}}.
1367
1368@node Object
1369@section Output (Object) File
1370
1371@cindex object file
1372@cindex output file
1373@kindex a.out
1374@kindex .o
a4fb0134 1375Every time you run @command{@value{AS}} it produces an output file, which is
252b5132
RH
1376your assembly language program translated into numbers. This file
1377is the object file. Its default name is
1378@ifclear BOUT
1379@code{a.out}.
1380@end ifclear
1381@ifset BOUT
1382@ifset GENERIC
1383@code{a.out}, or
1384@end ifset
a4fb0134 1385@code{b.out} when @command{@value{AS}} is configured for the Intel 80960.
252b5132 1386@end ifset
a4fb0134 1387You can give it another name by using the @option{-o} option. Conventionally,
252b5132
RH
1388object file names end with @file{.o}. The default name is used for historical
1389reasons: older assemblers were capable of assembling self-contained programs
1390directly into a runnable program. (For some formats, this isn't currently
1391possible, but it can be done for the @code{a.out} format.)
1392
1393@cindex linker
1394@kindex ld
1395The object file is meant for input to the linker @code{@value{LD}}. It contains
1396assembled program code, information to help @code{@value{LD}} integrate
1397the assembled program into a runnable file, and (optionally) symbolic
1398information for the debugger.
1399
1400@c link above to some info file(s) like the description of a.out.
1401@c don't forget to describe @sc{gnu} info as well as Unix lossage.
1402
1403@node Errors
1404@section Error and Warning Messages
1405
0285c67d
NC
1406@c man begin DESCRIPTION
1407
a349d9dd 1408@cindex error messages
252b5132
RH
1409@cindex warning messages
1410@cindex messages from assembler
a4fb0134 1411@command{@value{AS}} may write warnings and error messages to the standard error
252b5132 1412file (usually your terminal). This should not happen when a compiler
a4fb0134
SC
1413runs @command{@value{AS}} automatically. Warnings report an assumption made so
1414that @command{@value{AS}} could keep assembling a flawed program; errors report a
252b5132
RH
1415grave problem that stops the assembly.
1416
0285c67d
NC
1417@c man end
1418
252b5132
RH
1419@cindex format of warning messages
1420Warning messages have the format
1421
1422@smallexample
1423file_name:@b{NNN}:Warning Message Text
1424@end smallexample
1425
1426@noindent
1427@cindex line numbers, in warnings/errors
1428(where @b{NNN} is a line number). If a logical file name has been given
1429(@pxref{File,,@code{.file}}) it is used for the filename, otherwise the name of
1430the current input file is used. If a logical line number was given
1431@ifset GENERIC
1432(@pxref{Line,,@code{.line}})
1433@end ifset
1434@ifclear GENERIC
1435@ifclear A29K
1436(@pxref{Line,,@code{.line}})
1437@end ifclear
1438@ifset A29K
1439(@pxref{Ln,,@code{.ln}})
1440@end ifset
1441@end ifclear
1442then it is used to calculate the number printed,
1443otherwise the actual line in the current source file is printed. The
1444message text is intended to be self explanatory (in the grand Unix
1445tradition).
1446
1447@cindex format of error messages
1448Error messages have the format
1449@smallexample
1450file_name:@b{NNN}:FATAL:Error Message Text
1451@end smallexample
1452The file name and line number are derived as for warning
1453messages. The actual message text may be rather less explanatory
1454because many of them aren't supposed to happen.
1455
1456@node Invoking
1457@chapter Command-Line Options
1458
1459@cindex options, all versions of assembler
1460This chapter describes command-line options available in @emph{all}
1461versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific
1462@ifclear GENERIC
c1253627 1463to the @value{TARGET} target.
252b5132
RH
1464@end ifclear
1465@ifset GENERIC
1466to particular machine architectures.
1467@end ifset
1468
0285c67d
NC
1469@c man begin DESCRIPTION
1470
c1253627 1471If you are invoking @command{@value{AS}} via the @sc{gnu} C compiler,
252b5132
RH
1472you can use the @samp{-Wa} option to pass arguments through to the assembler.
1473The assembler arguments must be separated from each other (and the @samp{-Wa})
1474by commas. For example:
1475
1476@smallexample
1477gcc -c -g -O -Wa,-alh,-L file.c
1478@end smallexample
1479
1480@noindent
1481This passes two options to the assembler: @samp{-alh} (emit a listing to
5f5e16be 1482standard output with high-level and assembly source) and @samp{-L} (retain
252b5132
RH
1483local symbols in the symbol table).
1484
1485Usually you do not need to use this @samp{-Wa} mechanism, since many compiler
1486command-line options are automatically passed to the assembler by the compiler.
1487(You can call the @sc{gnu} compiler driver with the @samp{-v} option to see
1488precisely what options it passes to each compilation pass, including the
1489assembler.)
1490
0285c67d
NC
1491@c man end
1492
252b5132
RH
1493@menu
1494* a:: -a[cdhlns] enable listings
1495* D:: -D for compatibility
1496* f:: -f to work faster
1497* I:: -I for .include search path
1498@ifclear DIFF-TBL-KLUGE
1499* K:: -K for compatibility
1500@end ifclear
1501@ifset DIFF-TBL-KLUGE
1502* K:: -K for difference tables
1503@end ifset
1504
1505* L:: -L to retain local labels
c3a27914 1506* listing:: --listing-XXX to configure listing output
252b5132
RH
1507* M:: -M or --mri to assemble in MRI compatibility mode
1508* MD:: --MD for dependency tracking
1509* o:: -o to name the object file
1510* R:: -R to join data and text sections
1511* statistics:: --statistics to see statistics about assembly
1512* traditional-format:: --traditional-format for compatible output
1513* v:: -v to announce version
2bdd6cf5 1514* W:: -W, --no-warn, --warn, --fatal-warnings to control warnings
252b5132
RH
1515* Z:: -Z to make object file even after errors
1516@end menu
1517
1518@node a
a4fb0134 1519@section Enable Listings: @option{-a[cdhlns]}
252b5132
RH
1520
1521@kindex -a
1522@kindex -ac
1523@kindex -ad
1524@kindex -ah
1525@kindex -al
1526@kindex -an
1527@kindex -as
1528@cindex listings, enabling
1529@cindex assembly listings, enabling
1530
1531These options enable listing output from the assembler. By itself,
1532@samp{-a} requests high-level, assembly, and symbols listing.
1533You can use other letters to select specific options for the list:
1534@samp{-ah} requests a high-level language listing,
1535@samp{-al} requests an output-program assembly listing, and
1536@samp{-as} requests a symbol table listing.
1537High-level listings require that a compiler debugging option like
1538@samp{-g} be used, and that assembly listings (@samp{-al}) be requested
1539also.
1540
1541Use the @samp{-ac} option to omit false conditionals from a listing. Any lines
1542which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any
1543other conditional), or a true @code{.if} followed by an @code{.else}, will be
1544omitted from the listing.
1545
1546Use the @samp{-ad} option to omit debugging directives from the
1547listing.
1548
1549Once you have specified one of these options, you can further control
1550listing output and its appearance using the directives @code{.list},
1551@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and
1552@code{.sbttl}.
1553The @samp{-an} option turns off all forms processing.
1554If you do not request listing output with one of the @samp{-a} options, the
1555listing-control directives have no effect.
1556
1557The letters after @samp{-a} may be combined into one option,
1558@emph{e.g.}, @samp{-aln}.
1559
c3a27914
NC
1560Note if the assembler source is coming from the standard input (eg because it
1561is being created by @code{@value{GCC}} and the @samp{-pipe} command line switch
1562is being used) then the listing will not contain any comments or preprocessor
1563directives. This is because the listing code buffers input source lines from
1564stdin only after they have been preprocessed by the assembler. This reduces
1565memory usage and makes the code more efficient.
1566
252b5132 1567@node D
a4fb0134 1568@section @option{-D}
252b5132
RH
1569
1570@kindex -D
1571This option has no effect whatsoever, but it is accepted to make it more
1572likely that scripts written for other assemblers also work with
a4fb0134 1573@command{@value{AS}}.
252b5132
RH
1574
1575@node f
a4fb0134 1576@section Work Faster: @option{-f}
252b5132
RH
1577
1578@kindex -f
1579@cindex trusted compiler
a4fb0134 1580@cindex faster processing (@option{-f})
252b5132
RH
1581@samp{-f} should only be used when assembling programs written by a
1582(trusted) compiler. @samp{-f} stops the assembler from doing whitespace
1583and comment preprocessing on
1584the input file(s) before assembling them. @xref{Preprocessing,
1585,Preprocessing}.
1586
1587@quotation
1588@emph{Warning:} if you use @samp{-f} when the files actually need to be
a4fb0134 1589preprocessed (if they contain comments, for example), @command{@value{AS}} does
252b5132
RH
1590not work correctly.
1591@end quotation
1592
1593@node I
c1253627 1594@section @code{.include} Search Path: @option{-I} @var{path}
252b5132
RH
1595
1596@kindex -I @var{path}
1597@cindex paths for @code{.include}
1598@cindex search path for @code{.include}
1599@cindex @code{include} directive search path
1600Use this option to add a @var{path} to the list of directories
a4fb0134
SC
1601@command{@value{AS}} searches for files specified in @code{.include}
1602directives (@pxref{Include,,@code{.include}}). You may use @option{-I} as
252b5132 1603many times as necessary to include a variety of paths. The current
a4fb0134 1604working directory is always searched first; after that, @command{@value{AS}}
252b5132
RH
1605searches any @samp{-I} directories in the same order as they were
1606specified (left to right) on the command line.
1607
1608@node K
a4fb0134 1609@section Difference Tables: @option{-K}
252b5132
RH
1610
1611@kindex -K
1612@ifclear DIFF-TBL-KLUGE
1613On the @value{TARGET} family, this option is allowed, but has no effect. It is
1614permitted for compatibility with the @sc{gnu} assembler on other platforms,
1615where it can be used to warn when the assembler alters the machine code
1616generated for @samp{.word} directives in difference tables. The @value{TARGET}
1617family does not have the addressing limitations that sometimes lead to this
1618alteration on other platforms.
1619@end ifclear
1620
1621@ifset DIFF-TBL-KLUGE
1622@cindex difference tables, warning
1623@cindex warning for altered difference tables
a4fb0134 1624@command{@value{AS}} sometimes alters the code emitted for directives of the form
252b5132
RH
1625@samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}.
1626You can use the @samp{-K} option if you want a warning issued when this
1627is done.
1628@end ifset
1629
1630@node L
a4fb0134 1631@section Include Local Labels: @option{-L}
252b5132
RH
1632
1633@kindex -L
1634@cindex local labels, retaining in output
1635Labels beginning with @samp{L} (upper case only) are called @dfn{local
1636labels}. @xref{Symbol Names}. Normally you do not see such labels when
1637debugging, because they are intended for the use of programs (like
1638compilers) that compose assembler programs, not for your notice.
a4fb0134 1639Normally both @command{@value{AS}} and @code{@value{LD}} discard such labels, so you do not
252b5132
RH
1640normally debug with them.
1641
a4fb0134 1642This option tells @command{@value{AS}} to retain those @samp{L@dots{}} symbols
252b5132
RH
1643in the object file. Usually if you do this you also tell the linker
1644@code{@value{LD}} to preserve symbols whose names begin with @samp{L}.
1645
1646By default, a local label is any label beginning with @samp{L}, but each
1647target is allowed to redefine the local label prefix.
1648@ifset HPPA
1649On the HPPA local labels begin with @samp{L$}.
1650@end ifset
252b5132 1651
c3a27914 1652@node listing
a4fb0134 1653@section Configuring listing output: @option{--listing}
c3a27914
NC
1654
1655The listing feature of the assembler can be enabled via the command line switch
1656@samp{-a} (@pxref{a}). This feature combines the input source file(s) with a
1657hex dump of the corresponding locations in the output object file, and displays
1658them as a listing file. The format of this listing can be controlled by pseudo
1659ops inside the assembler source (@pxref{List} @pxref{Title} @pxref{Sbttl}
1660@pxref{Psize} @pxref{Eject}) and also by the following switches:
1661
a4fb0134 1662@table @gcctabopt
c3a27914
NC
1663@item --listing-lhs-width=@samp{number}
1664@kindex --listing-lhs-width
1665@cindex Width of first line disassembly output
1666Sets the maximum width, in words, of the first line of the hex byte dump. This
1667dump appears on the left hand side of the listing output.
1668
1669@item --listing-lhs-width2=@samp{number}
1670@kindex --listing-lhs-width2
1671@cindex Width of continuation lines of disassembly output
1672Sets the maximum width, in words, of any further lines of the hex byte dump for
8dfa0188 1673a given input source line. If this value is not specified, it defaults to being
c3a27914
NC
1674the same as the value specified for @samp{--listing-lhs-width}. If neither
1675switch is used the default is to one.
1676
1677@item --listing-rhs-width=@samp{number}
1678@kindex --listing-rhs-width
1679@cindex Width of source line output
1680Sets the maximum width, in characters, of the source line that is displayed
1681alongside the hex dump. The default value for this parameter is 100. The
1682source line is displayed on the right hand side of the listing output.
1683
1684@item --listing-cont-lines=@samp{number}
1685@kindex --listing-cont-lines
1686@cindex Maximum number of continuation lines
1687Sets the maximum number of continuation lines of hex dump that will be
1688displayed for a given single line of source input. The default value is 4.
1689@end table
1690
252b5132 1691@node M
a4fb0134 1692@section Assemble in MRI Compatibility Mode: @option{-M}
252b5132
RH
1693
1694@kindex -M
1695@cindex MRI compatibility mode
a4fb0134
SC
1696The @option{-M} or @option{--mri} option selects MRI compatibility mode. This
1697changes the syntax and pseudo-op handling of @command{@value{AS}} to make it
252b5132
RH
1698compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the
1699configured target) assembler from Microtec Research. The exact nature of the
1700MRI syntax will not be documented here; see the MRI manuals for more
1701information. Note in particular that the handling of macros and macro
1702arguments is somewhat different. The purpose of this option is to permit
a4fb0134 1703assembling existing MRI assembler code using @command{@value{AS}}.
252b5132
RH
1704
1705The MRI compatibility is not complete. Certain operations of the MRI assembler
1706depend upon its object file format, and can not be supported using other object
1707file formats. Supporting these would require enhancing each object file format
1708individually. These are:
1709
1710@itemize @bullet
1711@item global symbols in common section
1712
1713The m68k MRI assembler supports common sections which are merged by the linker.
a4fb0134 1714Other object file formats do not support this. @command{@value{AS}} handles
252b5132
RH
1715common sections by treating them as a single common symbol. It permits local
1716symbols to be defined within a common section, but it can not support global
1717symbols, since it has no way to describe them.
1718
1719@item complex relocations
1720
1721The MRI assemblers support relocations against a negated section address, and
1722relocations which combine the start addresses of two or more sections. These
1723are not support by other object file formats.
1724
1725@item @code{END} pseudo-op specifying start address
1726
1727The MRI @code{END} pseudo-op permits the specification of a start address.
1728This is not supported by other object file formats. The start address may
a4fb0134 1729instead be specified using the @option{-e} option to the linker, or in a linker
252b5132
RH
1730script.
1731
1732@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops
1733
1734The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module
1735name to the output file. This is not supported by other object file formats.
1736
1737@item @code{ORG} pseudo-op
1738
1739The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given
a4fb0134 1740address. This differs from the usual @command{@value{AS}} @code{.org} pseudo-op,
252b5132
RH
1741which changes the location within the current section. Absolute sections are
1742not supported by other object file formats. The address of a section may be
1743assigned within a linker script.
1744@end itemize
1745
1746There are some other features of the MRI assembler which are not supported by
a4fb0134 1747@command{@value{AS}}, typically either because they are difficult or because they
252b5132
RH
1748seem of little consequence. Some of these may be supported in future releases.
1749
1750@itemize @bullet
1751
1752@item EBCDIC strings
1753
1754EBCDIC strings are not supported.
1755
1756@item packed binary coded decimal
1757
1758Packed binary coded decimal is not supported. This means that the @code{DC.P}
1759and @code{DCB.P} pseudo-ops are not supported.
1760
1761@item @code{FEQU} pseudo-op
1762
1763The m68k @code{FEQU} pseudo-op is not supported.
1764
1765@item @code{NOOBJ} pseudo-op
1766
1767The m68k @code{NOOBJ} pseudo-op is not supported.
1768
1769@item @code{OPT} branch control options
1770
1771The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB},
a4fb0134 1772@code{BRL}, and @code{BRW}---are ignored. @command{@value{AS}} automatically
252b5132
RH
1773relaxes all branches, whether forward or backward, to an appropriate size, so
1774these options serve no purpose.
1775
1776@item @code{OPT} list control options
1777
1778The following m68k @code{OPT} list control options are ignored: @code{C},
1779@code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M},
1780@code{MEX}, @code{MC}, @code{MD}, @code{X}.
1781
1782@item other @code{OPT} options
1783
1784The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O},
1785@code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}.
1786
1787@item @code{OPT} @code{D} option is default
1788
1789The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler.
1790@code{OPT NOD} may be used to turn it off.
1791
1792@item @code{XREF} pseudo-op.
1793
1794The m68k @code{XREF} pseudo-op is ignored.
1795
1796@item @code{.debug} pseudo-op
1797
1798The i960 @code{.debug} pseudo-op is not supported.
1799
1800@item @code{.extended} pseudo-op
1801
1802The i960 @code{.extended} pseudo-op is not supported.
1803
1804@item @code{.list} pseudo-op.
1805
1806The various options of the i960 @code{.list} pseudo-op are not supported.
1807
1808@item @code{.optimize} pseudo-op
1809
1810The i960 @code{.optimize} pseudo-op is not supported.
1811
1812@item @code{.output} pseudo-op
1813
1814The i960 @code{.output} pseudo-op is not supported.
1815
1816@item @code{.setreal} pseudo-op
1817
1818The i960 @code{.setreal} pseudo-op is not supported.
1819
1820@end itemize
1821
1822@node MD
c1253627 1823@section Dependency Tracking: @option{--MD}
252b5132
RH
1824
1825@kindex --MD
1826@cindex dependency tracking
1827@cindex make rules
1828
a4fb0134 1829@command{@value{AS}} can generate a dependency file for the file it creates. This
252b5132
RH
1830file consists of a single rule suitable for @code{make} describing the
1831dependencies of the main source file.
1832
1833The rule is written to the file named in its argument.
1834
1835This feature is used in the automatic updating of makefiles.
1836
1837@node o
a4fb0134 1838@section Name the Object File: @option{-o}
252b5132
RH
1839
1840@kindex -o
1841@cindex naming object file
1842@cindex object file name
a4fb0134 1843There is always one object file output when you run @command{@value{AS}}. By
252b5132
RH
1844default it has the name
1845@ifset GENERIC
1846@ifset I960
1847@file{a.out} (or @file{b.out}, for Intel 960 targets only).
1848@end ifset
1849@ifclear I960
1850@file{a.out}.
1851@end ifclear
1852@end ifset
1853@ifclear GENERIC
1854@ifset I960
1855@file{b.out}.
1856@end ifset
1857@ifclear I960
1858@file{a.out}.
1859@end ifclear
1860@end ifclear
1861You use this option (which takes exactly one filename) to give the
1862object file a different name.
1863
a4fb0134 1864Whatever the object file is called, @command{@value{AS}} overwrites any
252b5132
RH
1865existing file of the same name.
1866
1867@node R
a4fb0134 1868@section Join Data and Text Sections: @option{-R}
252b5132
RH
1869
1870@kindex -R
1871@cindex data and text sections, joining
1872@cindex text and data sections, joining
1873@cindex joining text and data sections
1874@cindex merging text and data sections
a4fb0134 1875@option{-R} tells @command{@value{AS}} to write the object file as if all
252b5132
RH
1876data-section data lives in the text section. This is only done at
1877the very last moment: your binary data are the same, but data
1878section parts are relocated differently. The data section part of
1879your object file is zero bytes long because all its bytes are
1880appended to the text section. (@xref{Sections,,Sections and Relocation}.)
1881
a4fb0134 1882When you specify @option{-R} it would be possible to generate shorter
252b5132
RH
1883address displacements (because we do not have to cross between text and
1884data section). We refrain from doing this simply for compatibility with
a4fb0134 1885older versions of @command{@value{AS}}. In future, @option{-R} may work this way.
252b5132 1886
c1253627
NC
1887@ifset COFF-ELF
1888When @command{@value{AS}} is configured for COFF or ELF output,
252b5132
RH
1889this option is only useful if you use sections named @samp{.text} and
1890@samp{.data}.
1891@end ifset
1892
1893@ifset HPPA
a4fb0134
SC
1894@option{-R} is not supported for any of the HPPA targets. Using
1895@option{-R} generates a warning from @command{@value{AS}}.
252b5132
RH
1896@end ifset
1897
1898@node statistics
a4fb0134 1899@section Display Assembly Statistics: @option{--statistics}
252b5132
RH
1900
1901@kindex --statistics
1902@cindex statistics, about assembly
1903@cindex time, total for assembly
1904@cindex space used, maximum for assembly
1905Use @samp{--statistics} to display two statistics about the resources used by
a4fb0134 1906@command{@value{AS}}: the maximum amount of space allocated during the assembly
252b5132
RH
1907(in bytes), and the total execution time taken for the assembly (in @sc{cpu}
1908seconds).
1909
1910@node traditional-format
c1253627 1911@section Compatible Output: @option{--traditional-format}
252b5132
RH
1912
1913@kindex --traditional-format
a4fb0134 1914For some targets, the output of @command{@value{AS}} is different in some ways
252b5132 1915from the output of some existing assembler. This switch requests
a4fb0134 1916@command{@value{AS}} to use the traditional format instead.
252b5132
RH
1917
1918For example, it disables the exception frame optimizations which
a4fb0134 1919@command{@value{AS}} normally does by default on @code{@value{GCC}} output.
252b5132
RH
1920
1921@node v
a4fb0134 1922@section Announce Version: @option{-v}
252b5132
RH
1923
1924@kindex -v
1925@kindex -version
1926@cindex assembler version
1927@cindex version of assembler
1928You can find out what version of as is running by including the
1929option @samp{-v} (which you can also spell as @samp{-version}) on the
1930command line.
1931
1932@node W
a4fb0134 1933@section Control Warnings: @option{-W}, @option{--warn}, @option{--no-warn}, @option{--fatal-warnings}
252b5132 1934
a4fb0134 1935@command{@value{AS}} should never give a warning or error message when
252b5132 1936assembling compiler output. But programs written by people often
a4fb0134 1937cause @command{@value{AS}} to give a warning that a particular assumption was
252b5132 1938made. All such warnings are directed to the standard error file.
2bdd6cf5 1939
c1253627
NC
1940@kindex -W
1941@kindex --no-warn
2bdd6cf5
GK
1942@cindex suppressing warnings
1943@cindex warnings, suppressing
a4fb0134 1944If you use the @option{-W} and @option{--no-warn} options, no warnings are issued.
2bdd6cf5 1945This only affects the warning messages: it does not change any particular of
a4fb0134 1946how @command{@value{AS}} assembles your file. Errors, which stop the assembly,
2bdd6cf5
GK
1947are still reported.
1948
c1253627 1949@kindex --fatal-warnings
2bdd6cf5
GK
1950@cindex errors, caused by warnings
1951@cindex warnings, causing error
a4fb0134 1952If you use the @option{--fatal-warnings} option, @command{@value{AS}} considers
2bdd6cf5
GK
1953files that generate warnings to be in error.
1954
c1253627 1955@kindex --warn
2bdd6cf5 1956@cindex warnings, switching on
a4fb0134 1957You can switch these options off again by specifying @option{--warn}, which
2bdd6cf5 1958causes warnings to be output as usual.
252b5132
RH
1959
1960@node Z
a4fb0134 1961@section Generate Object File in Spite of Errors: @option{-Z}
252b5132
RH
1962@cindex object file, after errors
1963@cindex errors, continuing after
a4fb0134 1964After an error message, @command{@value{AS}} normally produces no output. If for
252b5132 1965some reason you are interested in object file output even after
a4fb0134
SC
1966@command{@value{AS}} gives an error message on your program, use the @samp{-Z}
1967option. If there are any errors, @command{@value{AS}} continues anyways, and
252b5132
RH
1968writes an object file after a final warning message of the form @samp{@var{n}
1969errors, @var{m} warnings, generating bad object file.}
1970
1971@node Syntax
1972@chapter Syntax
1973
1974@cindex machine-independent syntax
1975@cindex syntax, machine-independent
1976This chapter describes the machine-independent syntax allowed in a
a4fb0134 1977source file. @command{@value{AS}} syntax is similar to what many other
252b5132
RH
1978assemblers use; it is inspired by the BSD 4.2
1979@ifclear VAX
1980assembler.
1981@end ifclear
1982@ifset VAX
a4fb0134 1983assembler, except that @command{@value{AS}} does not assemble Vax bit-fields.
252b5132
RH
1984@end ifset
1985
1986@menu
1987* Preprocessing:: Preprocessing
1988* Whitespace:: Whitespace
1989* Comments:: Comments
1990* Symbol Intro:: Symbols
1991* Statements:: Statements
1992* Constants:: Constants
1993@end menu
1994
1995@node Preprocessing
1996@section Preprocessing
1997
1998@cindex preprocessing
a4fb0134 1999The @command{@value{AS}} internal preprocessor:
252b5132
RH
2000@itemize @bullet
2001@cindex whitespace, removed by preprocessor
2002@item
2003adjusts and removes extra whitespace. It leaves one space or tab before
2004the keywords on a line, and turns any other whitespace on the line into
2005a single space.
2006
2007@cindex comments, removed by preprocessor
2008@item
2009removes all comments, replacing them with a single space, or an
2010appropriate number of newlines.
2011
2012@cindex constants, converted by preprocessor
2013@item
2014converts character constants into the appropriate numeric values.
2015@end itemize
2016
2017It does not do macro processing, include file handling, or
2018anything else you may get from your C compiler's preprocessor. You can
2019do include file processing with the @code{.include} directive
2020(@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver
c1253627 2021to get other ``CPP'' style preprocessing by giving the input file a
252b5132
RH
2022@samp{.S} suffix. @xref{Overall Options,, Options Controlling the Kind of
2023Output, gcc.info, Using GNU CC}.
2024
2025Excess whitespace, comments, and character constants
2026cannot be used in the portions of the input text that are not
2027preprocessed.
2028
2029@cindex turning preprocessing on and off
2030@cindex preprocessing, turning on and off
2031@kindex #NO_APP
2032@kindex #APP
2033If the first line of an input file is @code{#NO_APP} or if you use the
2034@samp{-f} option, whitespace and comments are not removed from the input file.
2035Within an input file, you can ask for whitespace and comment removal in
2036specific portions of the by putting a line that says @code{#APP} before the
2037text that may contain whitespace or comments, and putting a line that says
2038@code{#NO_APP} after this text. This feature is mainly intend to support
2039@code{asm} statements in compilers whose output is otherwise free of comments
2040and whitespace.
2041
2042@node Whitespace
2043@section Whitespace
2044
2045@cindex whitespace
2046@dfn{Whitespace} is one or more blanks or tabs, in any order.
2047Whitespace is used to separate symbols, and to make programs neater for
2048people to read. Unless within character constants
2049(@pxref{Characters,,Character Constants}), any whitespace means the same
2050as exactly one space.
2051
2052@node Comments
2053@section Comments
2054
2055@cindex comments
a4fb0134 2056There are two ways of rendering comments to @command{@value{AS}}. In both
252b5132
RH
2057cases the comment is equivalent to one space.
2058
2059Anything from @samp{/*} through the next @samp{*/} is a comment.
2060This means you may not nest these comments.
2061
2062@smallexample
2063/*
2064 The only way to include a newline ('\n') in a comment
2065 is to use this sort of comment.
2066*/
2067
2068/* This sort of comment does not nest. */
2069@end smallexample
2070
2071@cindex line comment character
2072Anything from the @dfn{line comment} character to the next newline
2073is considered a comment and is ignored. The line comment character is
2074@ifset A29K
2075@samp{;} for the AMD 29K family;
2076@end ifset
2077@ifset ARC
2078@samp{;} on the ARC;
2079@end ifset
550262c4
NC
2080@ifset ARM
2081@samp{@@} on the ARM;
2082@end ifset
252b5132
RH
2083@ifset H8/300
2084@samp{;} for the H8/300 family;
2085@end ifset
2086@ifset H8/500
2087@samp{!} for the H8/500 family;
2088@end ifset
2089@ifset HPPA
2090@samp{;} for the HPPA;
2091@end ifset
55b62671
AJ
2092@ifset I80386
2093@samp{#} on the i386 and x86-64;
2094@end ifset
252b5132
RH
2095@ifset I960
2096@samp{#} on the i960;
2097@end ifset
e135f41b
NC
2098@ifset PDP11
2099@samp{;} for the PDP-11;
2100@end ifset
041dd5a9
ILT
2101@ifset PJ
2102@samp{;} for picoJava;
2103@end ifset
418c1742 2104@ifset PPC
3fb9d77f 2105@samp{#} for Motorola PowerPC;
418c1742 2106@end ifset
252b5132 2107@ifset SH
ef230218 2108@samp{!} for the Renesas / SuperH SH;
252b5132
RH
2109@end ifset
2110@ifset SPARC
2111@samp{!} on the SPARC;
2112@end ifset
a40cbfa3
NC
2113@ifset IP2K
2114@samp{#} on the ip2k;
2115@end ifset
252b5132
RH
2116@ifset M32R
2117@samp{#} on the m32r;
2118@end ifset
2119@ifset M680X0
2120@samp{|} on the 680x0;
2121@end ifset
60bcf0fa
NC
2122@ifset M68HC11
2123@samp{#} on the 68HC11 and 68HC12;
2124@end ifset
81b0b3f1
BE
2125@ifset M880X0
2126@samp{;} on the M880x0;
2127@end ifset
252b5132
RH
2128@ifset VAX
2129@samp{#} on the Vax;
2130@end ifset
2131@ifset Z8000
2132@samp{!} for the Z8000;
2133@end ifset
2134@ifset V850
2135@samp{#} on the V850;
2136@end ifset
e0001a05
NC
2137@ifset XTENSA
2138@samp{#} for Xtensa systems;
2139@end ifset
252b5132 2140see @ref{Machine Dependencies}. @refill
81b0b3f1 2141@c FIXME What about i860?
252b5132
RH
2142
2143@ifset GENERIC
2144On some machines there are two different line comment characters. One
2145character only begins a comment if it is the first non-whitespace character on
2146a line, while the other always begins a comment.
2147@end ifset
2148
2149@ifset V850
2150The V850 assembler also supports a double dash as starting a comment that
2151extends to the end of the line.
2152
2153@samp{--};
2154@end ifset
2155
2156@kindex #
2157@cindex lines starting with @code{#}
2158@cindex logical line numbers
2159To be compatible with past assemblers, lines that begin with @samp{#} have a
2160special interpretation. Following the @samp{#} should be an absolute
2161expression (@pxref{Expressions}): the logical line number of the @emph{next}
2162line. Then a string (@pxref{Strings,, Strings}) is allowed: if present it is a
2163new logical file name. The rest of the line, if any, should be whitespace.
2164
2165If the first non-whitespace characters on the line are not numeric,
2166the line is ignored. (Just like a comment.)
2167
2168@smallexample
2169 # This is an ordinary comment.
2170# 42-6 "new_file_name" # New logical file name
2171 # This is logical line # 36.
2172@end smallexample
2173This feature is deprecated, and may disappear from future versions
a4fb0134 2174of @command{@value{AS}}.
252b5132
RH
2175
2176@node Symbol Intro
2177@section Symbols
2178
2179@cindex characters used in symbols
2180@ifclear SPECIAL-SYMS
2181A @dfn{symbol} is one or more characters chosen from the set of all
2182letters (both upper and lower case), digits and the three characters
2183@samp{_.$}.
2184@end ifclear
2185@ifset SPECIAL-SYMS
2186@ifclear GENERIC
2187@ifset H8
2188A @dfn{symbol} is one or more characters chosen from the set of all
2189letters (both upper and lower case), digits and the three characters
2190@samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in
2191symbol names.)
2192@end ifset
2193@end ifclear
2194@end ifset
2195@ifset GENERIC
2196On most machines, you can also use @code{$} in symbol names; exceptions
2197are noted in @ref{Machine Dependencies}.
2198@end ifset
2199No symbol may begin with a digit. Case is significant.
2200There is no length limit: all characters are significant. Symbols are
2201delimited by characters not in that set, or by the beginning of a file
2202(since the source program must end with a newline, the end of a file is
2203not a possible symbol delimiter). @xref{Symbols}.
2204@cindex length of symbols
2205
2206@node Statements
2207@section Statements
2208
2209@cindex statements, structure of
2210@cindex line separator character
2211@cindex statement separator character
2212@ifclear GENERIC
2213@ifclear abnormal-separator
2214A @dfn{statement} ends at a newline character (@samp{\n}) or at a
2215semicolon (@samp{;}). The newline or semicolon is considered part of
2216the preceding statement. Newlines and semicolons within character
2217constants are an exception: they do not end statements.
2218@end ifclear
2219@ifset abnormal-separator
2220@ifset A29K
2221A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at''
2222sign (@samp{@@}). The newline or at sign is considered part of the
2223preceding statement. Newlines and at signs within character constants
2224are an exception: they do not end statements.
2225@end ifset
2226@ifset HPPA
2227A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation
2228point (@samp{!}). The newline or exclamation point is considered part of the
2229preceding statement. Newlines and exclamation points within character
2230constants are an exception: they do not end statements.
2231@end ifset
2232@ifset H8
2233A @dfn{statement} ends at a newline character (@samp{\n}); or (for the
2234H8/300) a dollar sign (@samp{$}); or (for the
c2dcd04e 2235Renesas-SH or the
252b5132
RH
2236H8/500) a semicolon
2237(@samp{;}). The newline or separator character is considered part of
2238the preceding statement. Newlines and separators within character
2239constants are an exception: they do not end statements.
2240@end ifset
2241@end ifset
2242@end ifclear
2243@ifset GENERIC
2244A @dfn{statement} ends at a newline character (@samp{\n}) or line
2245separator character. (The line separator is usually @samp{;}, unless
2246this conflicts with the comment character; @pxref{Machine Dependencies}.) The
2247newline or separator character is considered part of the preceding
2248statement. Newlines and separators within character constants are an
2249exception: they do not end statements.
2250@end ifset
2251
2252@cindex newline, required at file end
2253@cindex EOF, newline must precede
2254It is an error to end any statement with end-of-file: the last
2255character of any input file should be a newline.@refill
2256
2257An empty statement is allowed, and may include whitespace. It is ignored.
2258
2259@cindex instructions and directives
2260@cindex directives and instructions
2261@c "key symbol" is not used elsewhere in the document; seems pedantic to
2262@c @defn{} it in that case, as was done previously... doc@cygnus.com,
2263@c 13feb91.
2264A statement begins with zero or more labels, optionally followed by a
2265key symbol which determines what kind of statement it is. The key
2266symbol determines the syntax of the rest of the statement. If the
2267symbol begins with a dot @samp{.} then the statement is an assembler
2268directive: typically valid for any computer. If the symbol begins with
2269a letter the statement is an assembly language @dfn{instruction}: it
2270assembles into a machine language instruction.
2271@ifset GENERIC
a4fb0134 2272Different versions of @command{@value{AS}} for different computers
252b5132
RH
2273recognize different instructions. In fact, the same symbol may
2274represent a different instruction in a different computer's assembly
2275language.@refill
2276@end ifset
2277
2278@cindex @code{:} (label)
2279@cindex label (@code{:})
2280A label is a symbol immediately followed by a colon (@code{:}).
2281Whitespace before a label or after a colon is permitted, but you may not
2282have whitespace between a label's symbol and its colon. @xref{Labels}.
2283
2284@ifset HPPA
2285For HPPA targets, labels need not be immediately followed by a colon, but
2286the definition of a label must begin in column zero. This also implies that
2287only one label may be defined on each line.
2288@end ifset
2289
2290@smallexample
2291label: .directive followed by something
2292another_label: # This is an empty statement.
2293 instruction operand_1, operand_2, @dots{}
2294@end smallexample
2295
2296@node Constants
2297@section Constants
2298
2299@cindex constants
2300A constant is a number, written so that its value is known by
2301inspection, without knowing any context. Like this:
2302@smallexample
2303@group
2304.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
2305.ascii "Ring the bell\7" # A string constant.
2306.octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
2307.float 0f-314159265358979323846264338327\
230895028841971.693993751E-40 # - pi, a flonum.
2309@end group
2310@end smallexample
2311
2312@menu
2313* Characters:: Character Constants
2314* Numbers:: Number Constants
2315@end menu
2316
2317@node Characters
2318@subsection Character Constants
2319
2320@cindex character constants
2321@cindex constants, character
2322There are two kinds of character constants. A @dfn{character} stands
2323for one character in one byte and its value may be used in
2324numeric expressions. String constants (properly called string
2325@emph{literals}) are potentially many bytes and their values may not be
2326used in arithmetic expressions.
2327
2328@menu
2329* Strings:: Strings
2330* Chars:: Characters
2331@end menu
2332
2333@node Strings
2334@subsubsection Strings
2335
2336@cindex string constants
2337@cindex constants, string
2338A @dfn{string} is written between double-quotes. It may contain
2339double-quotes or null characters. The way to get special characters
2340into a string is to @dfn{escape} these characters: precede them with
2341a backslash @samp{\} character. For example @samp{\\} represents
2342one backslash: the first @code{\} is an escape which tells
a4fb0134
SC
2343@command{@value{AS}} to interpret the second character literally as a backslash
2344(which prevents @command{@value{AS}} from recognizing the second @code{\} as an
252b5132
RH
2345escape character). The complete list of escapes follows.
2346
2347@cindex escape codes, character
2348@cindex character escape codes
2349@table @kbd
2350@c @item \a
2351@c Mnemonic for ACKnowledge; for ASCII this is octal code 007.
2352@c
2353@cindex @code{\b} (backspace character)
2354@cindex backspace (@code{\b})
2355@item \b
2356Mnemonic for backspace; for ASCII this is octal code 010.
2357
2358@c @item \e
2359@c Mnemonic for EOText; for ASCII this is octal code 004.
2360@c
2361@cindex @code{\f} (formfeed character)
2362@cindex formfeed (@code{\f})
2363@item \f
2364Mnemonic for FormFeed; for ASCII this is octal code 014.
2365
2366@cindex @code{\n} (newline character)
2367@cindex newline (@code{\n})
2368@item \n
2369Mnemonic for newline; for ASCII this is octal code 012.
2370
2371@c @item \p
2372@c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}.
2373@c
2374@cindex @code{\r} (carriage return character)
2375@cindex carriage return (@code{\r})
2376@item \r
2377Mnemonic for carriage-Return; for ASCII this is octal code 015.
2378
2379@c @item \s
2380@c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with
2381@c other assemblers.
2382@c
2383@cindex @code{\t} (tab)
2384@cindex tab (@code{\t})
2385@item \t
2386Mnemonic for horizontal Tab; for ASCII this is octal code 011.
2387
2388@c @item \v
2389@c Mnemonic for Vertical tab; for ASCII this is octal code 013.
2390@c @item \x @var{digit} @var{digit} @var{digit}
2391@c A hexadecimal character code. The numeric code is 3 hexadecimal digits.
2392@c
2393@cindex @code{\@var{ddd}} (octal character code)
2394@cindex octal character code (@code{\@var{ddd}})
2395@item \ @var{digit} @var{digit} @var{digit}
2396An octal character code. The numeric code is 3 octal digits.
2397For compatibility with other Unix systems, 8 and 9 are accepted as digits:
2398for example, @code{\008} has the value 010, and @code{\009} the value 011.
2399
2400@cindex @code{\@var{xd...}} (hex character code)
2401@cindex hex character code (@code{\@var{xd...}})
2402@item \@code{x} @var{hex-digits...}
2403A hex character code. All trailing hex digits are combined. Either upper or
2404lower case @code{x} works.
2405
2406@cindex @code{\\} (@samp{\} character)
2407@cindex backslash (@code{\\})
2408@item \\
2409Represents one @samp{\} character.
2410
2411@c @item \'
2412@c Represents one @samp{'} (accent acute) character.
2413@c This is needed in single character literals
2414@c (@xref{Characters,,Character Constants}.) to represent
2415@c a @samp{'}.
2416@c
2417@cindex @code{\"} (doublequote character)
2418@cindex doublequote (@code{\"})
2419@item \"
2420Represents one @samp{"} character. Needed in strings to represent
2421this character, because an unescaped @samp{"} would end the string.
2422
2423@item \ @var{anything-else}
2424Any other character when escaped by @kbd{\} gives a warning, but
2425assembles as if the @samp{\} was not present. The idea is that if
2426you used an escape sequence you clearly didn't want the literal
a4fb0134
SC
2427interpretation of the following character. However @command{@value{AS}} has no
2428other interpretation, so @command{@value{AS}} knows it is giving you the wrong
252b5132
RH
2429code and warns you of the fact.
2430@end table
2431
2432Which characters are escapable, and what those escapes represent,
2433varies widely among assemblers. The current set is what we think
2434the BSD 4.2 assembler recognizes, and is a subset of what most C
2435compilers recognize. If you are in doubt, do not use an escape
2436sequence.
2437
2438@node Chars
2439@subsubsection Characters
2440
2441@cindex single character constant
2442@cindex character, single
2443@cindex constant, single character
2444A single character may be written as a single quote immediately
2445followed by that character. The same escapes apply to characters as
2446to strings. So if you want to write the character backslash, you
2447must write @kbd{'\\} where the first @code{\} escapes the second
2448@code{\}. As you can see, the quote is an acute accent, not a
2449grave accent. A newline
2450@ifclear GENERIC
2451@ifclear abnormal-separator
2452(or semicolon @samp{;})
2453@end ifclear
2454@ifset abnormal-separator
2455@ifset A29K
2456(or at sign @samp{@@})
2457@end ifset
2458@ifset H8
2459(or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the
c2dcd04e 2460Renesas SH or H8/500)
252b5132
RH
2461@end ifset
2462@end ifset
2463@end ifclear
2464immediately following an acute accent is taken as a literal character
2465and does not count as the end of a statement. The value of a character
2466constant in a numeric expression is the machine's byte-wide code for
a4fb0134 2467that character. @command{@value{AS}} assumes your character code is ASCII:
252b5132
RH
2468@kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill
2469
2470@node Numbers
2471@subsection Number Constants
2472
2473@cindex constants, number
2474@cindex number constants
a4fb0134 2475@command{@value{AS}} distinguishes three kinds of numbers according to how they
252b5132
RH
2476are stored in the target machine. @emph{Integers} are numbers that
2477would fit into an @code{int} in the C language. @emph{Bignums} are
2478integers, but they are stored in more than 32 bits. @emph{Flonums}
2479are floating point numbers, described below.
2480
2481@menu
2482* Integers:: Integers
2483* Bignums:: Bignums
2484* Flonums:: Flonums
2485@ifclear GENERIC
2486@ifset I960
2487* Bit Fields:: Bit Fields
2488@end ifset
2489@end ifclear
2490@end menu
2491
2492@node Integers
2493@subsubsection Integers
2494@cindex integers
2495@cindex constants, integer
2496
2497@cindex binary integers
2498@cindex integers, binary
2499A binary integer is @samp{0b} or @samp{0B} followed by zero or more of
2500the binary digits @samp{01}.
2501
2502@cindex octal integers
2503@cindex integers, octal
2504An octal integer is @samp{0} followed by zero or more of the octal
2505digits (@samp{01234567}).
2506
2507@cindex decimal integers
2508@cindex integers, decimal
2509A decimal integer starts with a non-zero digit followed by zero or
2510more digits (@samp{0123456789}).
2511
2512@cindex hexadecimal integers
2513@cindex integers, hexadecimal
2514A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
2515more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
2516
2517Integers have the usual values. To denote a negative integer, use
2518the prefix operator @samp{-} discussed under expressions
2519(@pxref{Prefix Ops,,Prefix Operators}).
2520
2521@node Bignums
2522@subsubsection Bignums
2523
2524@cindex bignums
2525@cindex constants, bignum
2526A @dfn{bignum} has the same syntax and semantics as an integer
2527except that the number (or its negative) takes more than 32 bits to
2528represent in binary. The distinction is made because in some places
2529integers are permitted while bignums are not.
2530
2531@node Flonums
2532@subsubsection Flonums
2533@cindex flonums
2534@cindex floating point numbers
2535@cindex constants, floating point
2536
2537@cindex precision, floating point
2538A @dfn{flonum} represents a floating point number. The translation is
2539indirect: a decimal floating point number from the text is converted by
a4fb0134 2540@command{@value{AS}} to a generic binary floating point number of more than
252b5132
RH
2541sufficient precision. This generic floating point number is converted
2542to a particular computer's floating point format (or formats) by a
a4fb0134 2543portion of @command{@value{AS}} specialized to that computer.
252b5132
RH
2544
2545A flonum is written by writing (in order)
2546@itemize @bullet
2547@item
2548The digit @samp{0}.
2549@ifset HPPA
2550(@samp{0} is optional on the HPPA.)
2551@end ifset
2552
2553@item
a4fb0134 2554A letter, to tell @command{@value{AS}} the rest of the number is a flonum.
252b5132
RH
2555@ifset GENERIC
2556@kbd{e} is recommended. Case is not important.
2557@ignore
2558@c FIXME: verify if flonum syntax really this vague for most cases
2559(Any otherwise illegal letter works here, but that might be changed. Vax BSD
25604.2 assembler seems to allow any of @samp{defghDEFGH}.)
2561@end ignore
2562
2563On the H8/300, H8/500,
ef230218 2564Renesas / SuperH SH,
252b5132
RH
2565and AMD 29K architectures, the letter must be
2566one of the letters @samp{DFPRSX} (in upper or lower case).
2567
2568On the ARC, the letter must be one of the letters @samp{DFRS}
2569(in upper or lower case).
2570
2571On the Intel 960 architecture, the letter must be
2572one of the letters @samp{DFT} (in upper or lower case).
2573
2574On the HPPA architecture, the letter must be @samp{E} (upper case only).
2575@end ifset
2576@ifclear GENERIC
2577@ifset A29K
2578One of the letters @samp{DFPRSX} (in upper or lower case).
2579@end ifset
2580@ifset ARC
2581One of the letters @samp{DFRS} (in upper or lower case).
2582@end ifset
2583@ifset H8
2584One of the letters @samp{DFPRSX} (in upper or lower case).
2585@end ifset
2586@ifset HPPA
2587The letter @samp{E} (upper case only).
2588@end ifset
2589@ifset I960
2590One of the letters @samp{DFT} (in upper or lower case).
2591@end ifset
2592@end ifclear
2593
2594@item
2595An optional sign: either @samp{+} or @samp{-}.
2596
2597@item
2598An optional @dfn{integer part}: zero or more decimal digits.
2599
2600@item
2601An optional @dfn{fractional part}: @samp{.} followed by zero
2602or more decimal digits.
2603
2604@item
2605An optional exponent, consisting of:
2606
2607@itemize @bullet
2608@item
2609An @samp{E} or @samp{e}.
2610@c I can't find a config where "EXP_CHARS" is other than 'eE', but in
2611@c principle this can perfectly well be different on different targets.
2612@item
2613Optional sign: either @samp{+} or @samp{-}.
2614@item
2615One or more decimal digits.
2616@end itemize
2617
2618@end itemize
2619
2620At least one of the integer part or the fractional part must be
2621present. The floating point number has the usual base-10 value.
2622
a4fb0134 2623@command{@value{AS}} does all processing using integers. Flonums are computed
252b5132 2624independently of any floating point hardware in the computer running
a4fb0134 2625@command{@value{AS}}.
252b5132
RH
2626
2627@ifclear GENERIC
2628@ifset I960
2629@c Bit fields are written as a general facility but are also controlled
2630@c by a conditional-compilation flag---which is as of now (21mar91)
2631@c turned on only by the i960 config of GAS.
2632@node Bit Fields
2633@subsubsection Bit Fields
2634
2635@cindex bit fields
2636@cindex constants, bit field
2637You can also define numeric constants as @dfn{bit fields}.
2638specify two numbers separated by a colon---
2639@example
2640@var{mask}:@var{value}
2641@end example
2642@noindent
a4fb0134 2643@command{@value{AS}} applies a bitwise @sc{and} between @var{mask} and
252b5132
RH
2644@var{value}.
2645
2646The resulting number is then packed
2647@ifset GENERIC
2648@c this conditional paren in case bit fields turned on elsewhere than 960
2649(in host-dependent byte order)
2650@end ifset
2651into a field whose width depends on which assembler directive has the
2652bit-field as its argument. Overflow (a result from the bitwise and
2653requiring more binary digits to represent) is not an error; instead,
2654more constants are generated, of the specified width, beginning with the
2655least significant digits.@refill
2656
2657The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long},
2658@code{.short}, and @code{.word} accept bit-field arguments.
2659@end ifset
2660@end ifclear
2661
2662@node Sections
2663@chapter Sections and Relocation
2664@cindex sections
2665@cindex relocation
2666
2667@menu
2668* Secs Background:: Background
2669* Ld Sections:: Linker Sections
2670* As Sections:: Assembler Internal Sections
2671* Sub-Sections:: Sub-Sections
2672* bss:: bss Section
2673@end menu
2674
2675@node Secs Background
2676@section Background
2677
2678Roughly, a section is a range of addresses, with no gaps; all data
2679``in'' those addresses is treated the same for some particular purpose.
2680For example there may be a ``read only'' section.
2681
2682@cindex linker, and assembler
2683@cindex assembler, and linker
2684The linker @code{@value{LD}} reads many object files (partial programs) and
a4fb0134 2685combines their contents to form a runnable program. When @command{@value{AS}}
252b5132
RH
2686emits an object file, the partial program is assumed to start at address 0.
2687@code{@value{LD}} assigns the final addresses for the partial program, so that
2688different partial programs do not overlap. This is actually an
a4fb0134 2689oversimplification, but it suffices to explain how @command{@value{AS}} uses
252b5132
RH
2690sections.
2691
2692@code{@value{LD}} moves blocks of bytes of your program to their run-time
2693addresses. These blocks slide to their run-time addresses as rigid
2694units; their length does not change and neither does the order of bytes
2695within them. Such a rigid unit is called a @emph{section}. Assigning
2696run-time addresses to sections is called @dfn{relocation}. It includes
2697the task of adjusting mentions of object-file addresses so they refer to
2698the proper run-time addresses.
2699@ifset H8
2700For the H8/300 and H8/500,
ef230218 2701and for the Renesas / SuperH SH,
a4fb0134 2702@command{@value{AS}} pads sections if needed to
252b5132
RH
2703ensure they end on a word (sixteen bit) boundary.
2704@end ifset
2705
2706@cindex standard assembler sections
a4fb0134 2707An object file written by @command{@value{AS}} has at least three sections, any
252b5132
RH
2708of which may be empty. These are named @dfn{text}, @dfn{data} and
2709@dfn{bss} sections.
2710
c1253627 2711@ifset COFF-ELF
252b5132 2712@ifset GENERIC
c1253627 2713When it generates COFF or ELF output,
252b5132 2714@end ifset
a4fb0134 2715@command{@value{AS}} can also generate whatever other named sections you specify
252b5132
RH
2716using the @samp{.section} directive (@pxref{Section,,@code{.section}}).
2717If you do not use any directives that place output in the @samp{.text}
2718or @samp{.data} sections, these sections still exist, but are empty.
2719@end ifset
2720
2721@ifset HPPA
2722@ifset GENERIC
a4fb0134 2723When @command{@value{AS}} generates SOM or ELF output for the HPPA,
252b5132 2724@end ifset
a4fb0134 2725@command{@value{AS}} can also generate whatever other named sections you
252b5132
RH
2726specify using the @samp{.space} and @samp{.subspace} directives. See
2727@cite{HP9000 Series 800 Assembly Language Reference Manual}
2728(HP 92432-90001) for details on the @samp{.space} and @samp{.subspace}
2729assembler directives.
2730
2731@ifset SOM
a4fb0134 2732Additionally, @command{@value{AS}} uses different names for the standard
252b5132
RH
2733text, data, and bss sections when generating SOM output. Program text
2734is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and
2735BSS into @samp{$BSS$}.
2736@end ifset
2737@end ifset
2738
2739Within the object file, the text section starts at address @code{0}, the
2740data section follows, and the bss section follows the data section.
2741
2742@ifset HPPA
2743When generating either SOM or ELF output files on the HPPA, the text
2744section starts at address @code{0}, the data section at address
2745@code{0x4000000}, and the bss section follows the data section.
2746@end ifset
2747
2748To let @code{@value{LD}} know which data changes when the sections are
a4fb0134 2749relocated, and how to change that data, @command{@value{AS}} also writes to the
252b5132
RH
2750object file details of the relocation needed. To perform relocation
2751@code{@value{LD}} must know, each time an address in the object
2752file is mentioned:
2753@itemize @bullet
2754@item
2755Where in the object file is the beginning of this reference to
2756an address?
2757@item
2758How long (in bytes) is this reference?
2759@item
2760Which section does the address refer to? What is the numeric value of
2761@display
2762(@var{address}) @minus{} (@var{start-address of section})?
2763@end display
2764@item
2765Is the reference to an address ``Program-Counter relative''?
2766@end itemize
2767
2768@cindex addresses, format of
2769@cindex section-relative addressing
a4fb0134 2770In fact, every address @command{@value{AS}} ever uses is expressed as
252b5132
RH
2771@display
2772(@var{section}) + (@var{offset into section})
2773@end display
2774@noindent
a4fb0134 2775Further, most expressions @command{@value{AS}} computes have this section-relative
252b5132
RH
2776nature.
2777@ifset SOM
2778(For some object formats, such as SOM for the HPPA, some expressions are
2779symbol-relative instead.)
2780@end ifset
2781
2782In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset
2783@var{N} into section @var{secname}.''
2784
2785Apart from text, data and bss sections you need to know about the
2786@dfn{absolute} section. When @code{@value{LD}} mixes partial programs,
2787addresses in the absolute section remain unchanged. For example, address
2788@code{@{absolute 0@}} is ``relocated'' to run-time address 0 by
2789@code{@value{LD}}. Although the linker never arranges two partial programs'
2790data sections with overlapping addresses after linking, @emph{by definition}
2791their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one
2792part of a program is always the same address when the program is running as
2793address @code{@{absolute@ 239@}} in any other part of the program.
2794
2795The idea of sections is extended to the @dfn{undefined} section. Any
2796address whose section is unknown at assembly time is by definition
2797rendered @{undefined @var{U}@}---where @var{U} is filled in later.
2798Since numbers are always defined, the only way to generate an undefined
2799address is to mention an undefined symbol. A reference to a named
2800common block would be such a symbol: its value is unknown at assembly
2801time so it has section @emph{undefined}.
2802
2803By analogy the word @emph{section} is used to describe groups of sections in
2804the linked program. @code{@value{LD}} puts all partial programs' text
2805sections in contiguous addresses in the linked program. It is
2806customary to refer to the @emph{text section} of a program, meaning all
2807the addresses of all partial programs' text sections. Likewise for
2808data and bss sections.
2809
2810Some sections are manipulated by @code{@value{LD}}; others are invented for
a4fb0134 2811use of @command{@value{AS}} and have no meaning except during assembly.
252b5132
RH
2812
2813@node Ld Sections
2814@section Linker Sections
2815@code{@value{LD}} deals with just four kinds of sections, summarized below.
2816
2817@table @strong
2818
c1253627 2819@ifset COFF-ELF
252b5132
RH
2820@cindex named sections
2821@cindex sections, named
2822@item named sections
2823@end ifset
2824@ifset aout-bout
2825@cindex text section
2826@cindex data section
2827@itemx text section
2828@itemx data section
2829@end ifset
a4fb0134 2830These sections hold your program. @command{@value{AS}} and @code{@value{LD}} treat them as
252b5132 2831separate but equal sections. Anything you can say of one section is
c1253627
NC
2832true of another.
2833@c @ifset aout-bout
252b5132
RH
2834When the program is running, however, it is
2835customary for the text section to be unalterable. The
2836text section is often shared among processes: it contains
2837instructions, constants and the like. The data section of a running
2838program is usually alterable: for example, C variables would be stored
2839in the data section.
c1253627 2840@c @end ifset
252b5132
RH
2841
2842@cindex bss section
2843@item bss section
2844This section contains zeroed bytes when your program begins running. It
a349d9dd 2845is used to hold uninitialized variables or common storage. The length of
252b5132
RH
2846each partial program's bss section is important, but because it starts
2847out containing zeroed bytes there is no need to store explicit zero
2848bytes in the object file. The bss section was invented to eliminate
2849those explicit zeros from object files.
2850
2851@cindex absolute section
2852@item absolute section
2853Address 0 of this section is always ``relocated'' to runtime address 0.
2854This is useful if you want to refer to an address that @code{@value{LD}} must
2855not change when relocating. In this sense we speak of absolute
2856addresses being ``unrelocatable'': they do not change during relocation.
2857
2858@cindex undefined section
2859@item undefined section
2860This ``section'' is a catch-all for address references to objects not in
2861the preceding sections.
2862@c FIXME: ref to some other doc on obj-file formats could go here.
2863@end table
2864
2865@cindex relocation example
2866An idealized example of three relocatable sections follows.
c1253627 2867@ifset COFF-ELF
252b5132
RH
2868The example uses the traditional section names @samp{.text} and @samp{.data}.
2869@end ifset
2870Memory addresses are on the horizontal axis.
2871
2872@c TEXI2ROFF-KILL
c1253627 2873@ifnottex
252b5132
RH
2874@c END TEXI2ROFF-KILL
2875@smallexample
2876 +-----+----+--+
2877partial program # 1: |ttttt|dddd|00|
2878 +-----+----+--+
2879
2880 text data bss
2881 seg. seg. seg.
2882
2883 +---+---+---+
2884partial program # 2: |TTT|DDD|000|
2885 +---+---+---+
2886
2887 +--+---+-----+--+----+---+-----+~~
2888linked program: | |TTT|ttttt| |dddd|DDD|00000|
2889 +--+---+-----+--+----+---+-----+~~
2890
2891 addresses: 0 @dots{}
2892@end smallexample
2893@c TEXI2ROFF-KILL
c1253627 2894@end ifnottex
252b5132
RH
2895@need 5000
2896@tex
c1253627 2897\bigskip
252b5132
RH
2898\line{\it Partial program \#1: \hfil}
2899\line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
2900\line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil}
2901
2902\line{\it Partial program \#2: \hfil}
2903\line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil}
2904\line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil}
2905
2906\line{\it linked program: \hfil}
2907\line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil}
2908\line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt
2909ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt
2910DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil}
2911
2912\line{\it addresses: \hfil}
2913\line{0\dots\hfil}
2914
2915@end tex
2916@c END TEXI2ROFF-KILL
2917
2918@node As Sections
2919@section Assembler Internal Sections
2920
2921@cindex internal assembler sections
2922@cindex sections in messages, internal
a4fb0134 2923These sections are meant only for the internal use of @command{@value{AS}}. They
252b5132 2924have no meaning at run-time. You do not really need to know about these
a4fb0134 2925sections for most purposes; but they can be mentioned in @command{@value{AS}}
252b5132 2926warning messages, so it might be helpful to have an idea of their
a4fb0134 2927meanings to @command{@value{AS}}. These sections are used to permit the
252b5132
RH
2928value of every expression in your assembly language program to be a
2929section-relative address.
2930
2931@table @b
2932@cindex assembler internal logic error
2933@item ASSEMBLER-INTERNAL-LOGIC-ERROR!
2934An internal assembler logic error has been found. This means there is a
2935bug in the assembler.
2936
2937@cindex expr (internal section)
2938@item expr section
2939The assembler stores complex expression internally as combinations of
2940symbols. When it needs to represent an expression as a symbol, it puts
2941it in the expr section.
2942@c FIXME item debug
2943@c FIXME item transfer[t] vector preload
2944@c FIXME item transfer[t] vector postload
2945@c FIXME item register
2946@end table
2947
2948@node Sub-Sections
2949@section Sub-Sections
2950
2951@cindex numbered subsections
2952@cindex grouping data
2953@ifset aout-bout
2954Assembled bytes
c1253627 2955@ifset COFF-ELF
252b5132
RH
2956conventionally
2957@end ifset
2958fall into two sections: text and data.
2959@end ifset
2960You may have separate groups of
2961@ifset GENERIC
2962data in named sections
2963@end ifset
2964@ifclear GENERIC
2965@ifclear aout-bout
2966data in named sections
2967@end ifclear
2968@ifset aout-bout
2969text or data
2970@end ifset
2971@end ifclear
2972that you want to end up near to each other in the object file, even though they
a4fb0134 2973are not contiguous in the assembler source. @command{@value{AS}} allows you to
252b5132
RH
2974use @dfn{subsections} for this purpose. Within each section, there can be
2975numbered subsections with values from 0 to 8192. Objects assembled into the
2976same subsection go into the object file together with other objects in the same
2977subsection. For example, a compiler might want to store constants in the text
2978section, but might not want to have them interspersed with the program being
2979assembled. In this case, the compiler could issue a @samp{.text 0} before each
2980section of code being output, and a @samp{.text 1} before each group of
2981constants being output.
2982
2983Subsections are optional. If you do not use subsections, everything
2984goes in subsection number zero.
2985
2986@ifset GENERIC
2987Each subsection is zero-padded up to a multiple of four bytes.
2988(Subsections may be padded a different amount on different flavors
a4fb0134 2989of @command{@value{AS}}.)
252b5132
RH
2990@end ifset
2991@ifclear GENERIC
2992@ifset H8
2993On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word
2994boundary (two bytes).
c2dcd04e 2995The same is true on the Renesas SH.
252b5132
RH
2996@end ifset
2997@ifset I960
2998@c FIXME section padding (alignment)?
2999@c Rich Pixley says padding here depends on target obj code format; that
3000@c doesn't seem particularly useful to say without further elaboration,
3001@c so for now I say nothing about it. If this is a generic BFD issue,
3002@c these paragraphs might need to vanish from this manual, and be
3003@c discussed in BFD chapter of binutils (or some such).
3004@end ifset
3005@ifset A29K
3006On the AMD 29K family, no particular padding is added to section or
3007subsection sizes; @value{AS} forces no alignment on this platform.
3008@end ifset
3009@end ifclear
3010
3011Subsections appear in your object file in numeric order, lowest numbered
3012to highest. (All this to be compatible with other people's assemblers.)
3013The object file contains no representation of subsections; @code{@value{LD}} and
3014other programs that manipulate object files see no trace of them.
3015They just see all your text subsections as a text section, and all your
3016data subsections as a data section.
3017
3018To specify which subsection you want subsequent statements assembled
3019into, use a numeric argument to specify it, in a @samp{.text
3020@var{expression}} or a @samp{.data @var{expression}} statement.
c1253627 3021@ifset COFF-ELF
252b5132 3022@ifset GENERIC
c1253627 3023When generating COFF or ELF output, you
252b5132
RH
3024@end ifset
3025@ifclear GENERIC
3026You
3027@end ifclear
3028can also use an extra subsection
3029argument with arbitrary named sections: @samp{.section @var{name},
3030@var{expression}}.
3031@end ifset
3032@var{Expression} should be an absolute expression.
3033(@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0}
3034is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly
3035begins in @code{text 0}. For instance:
3036@smallexample
3037.text 0 # The default subsection is text 0 anyway.
3038.ascii "This lives in the first text subsection. *"
3039.text 1
3040.ascii "But this lives in the second text subsection."
3041.data 0
3042.ascii "This lives in the data section,"
3043.ascii "in the first data subsection."
3044.text 0
3045.ascii "This lives in the first text section,"
3046.ascii "immediately following the asterisk (*)."
3047@end smallexample
3048
3049Each section has a @dfn{location counter} incremented by one for every byte
3050assembled into that section. Because subsections are merely a convenience
a4fb0134 3051restricted to @command{@value{AS}} there is no concept of a subsection location
252b5132
RH
3052counter. There is no way to directly manipulate a location counter---but the
3053@code{.align} directive changes it, and any label definition captures its
3054current value. The location counter of the section where statements are being
3055assembled is said to be the @dfn{active} location counter.
3056
3057@node bss
3058@section bss Section
3059
3060@cindex bss section
3061@cindex common variable storage
3062The bss section is used for local common variable storage.
3063You may allocate address space in the bss section, but you may
3064not dictate data to load into it before your program executes. When
3065your program starts running, all the contents of the bss
3066section are zeroed bytes.
3067
3068The @code{.lcomm} pseudo-op defines a symbol in the bss section; see
3069@ref{Lcomm,,@code{.lcomm}}.
3070
3071The @code{.comm} pseudo-op may be used to declare a common symbol, which is
3072another form of uninitialized symbol; see @xref{Comm,,@code{.comm}}.
3073
3074@ifset GENERIC
3075When assembling for a target which supports multiple sections, such as ELF or
3076COFF, you may switch into the @code{.bss} section and define symbols as usual;
3077see @ref{Section,,@code{.section}}. You may only assemble zero values into the
3078section. Typically the section will only contain symbol definitions and
3079@code{.skip} directives (@pxref{Skip,,@code{.skip}}).
3080@end ifset
3081
3082@node Symbols
3083@chapter Symbols
3084
3085@cindex symbols
3086Symbols are a central concept: the programmer uses symbols to name
3087things, the linker uses symbols to link, and the debugger uses symbols
3088to debug.
3089
3090@quotation
3091@cindex debuggers, and symbol order
a4fb0134 3092@emph{Warning:} @command{@value{AS}} does not place symbols in the object file in
252b5132
RH
3093the same order they were declared. This may break some debuggers.
3094@end quotation
3095
3096@menu
3097* Labels:: Labels
3098* Setting Symbols:: Giving Symbols Other Values
3099* Symbol Names:: Symbol Names
3100* Dot:: The Special Dot Symbol
3101* Symbol Attributes:: Symbol Attributes
3102@end menu
3103
3104@node Labels
3105@section Labels
3106
3107@cindex labels
3108A @dfn{label} is written as a symbol immediately followed by a colon
3109@samp{:}. The symbol then represents the current value of the
3110active location counter, and is, for example, a suitable instruction
3111operand. You are warned if you use the same symbol to represent two
3112different locations: the first definition overrides any other
3113definitions.
3114
3115@ifset HPPA
3116On the HPPA, the usual form for a label need not be immediately followed by a
3117colon, but instead must start in column zero. Only one label may be defined on
a4fb0134 3118a single line. To work around this, the HPPA version of @command{@value{AS}} also
252b5132
RH
3119provides a special directive @code{.label} for defining labels more flexibly.
3120@end ifset
3121
3122@node Setting Symbols
3123@section Giving Symbols Other Values
3124
3125@cindex assigning values to symbols
3126@cindex symbol values, assigning
3127A symbol can be given an arbitrary value by writing a symbol, followed
3128by an equals sign @samp{=}, followed by an expression
3129(@pxref{Expressions}). This is equivalent to using the @code{.set}
3130directive. @xref{Set,,@code{.set}}.
3131
3132@node Symbol Names
3133@section Symbol Names
3134
3135@cindex symbol names
3136@cindex names, symbol
3137@ifclear SPECIAL-SYMS
3138Symbol names begin with a letter or with one of @samp{._}. On most
3139machines, you can also use @code{$} in symbol names; exceptions are
3140noted in @ref{Machine Dependencies}. That character may be followed by any
3141string of digits, letters, dollar signs (unless otherwise noted in
3142@ref{Machine Dependencies}), and underscores.
3143@end ifclear
3144@ifset A29K
3145For the AMD 29K family, @samp{?} is also allowed in the
3146body of a symbol name, though not at its beginning.
3147@end ifset
3148
3149@ifset SPECIAL-SYMS
3150@ifset H8
3151Symbol names begin with a letter or with one of @samp{._}. On the
c2dcd04e
NC
3152Renesas SH or the H8/500, you can also use @code{$} in symbol names. That
3153character may be followed by any string of digits, letters, dollar signs (save
3154on the H8/300), and underscores.
252b5132
RH
3155@end ifset
3156@end ifset
3157
3158Case of letters is significant: @code{foo} is a different symbol name
3159than @code{Foo}.
3160
3161Each symbol has exactly one name. Each name in an assembly language program
3162refers to exactly one symbol. You may use that symbol name any number of times
3163in a program.
3164
3165@subheading Local Symbol Names
3166
3167@cindex local symbol names
3168@cindex symbol names, local
3169@cindex temporary symbol names
3170@cindex symbol names, temporary
3171Local symbols help compilers and programmers use names temporarily.
2d5aaba0
NC
3172They create symbols which are guaranteed to be unique over the entire scope of
3173the input source code and which can be referred to by a simple notation.
3174To define a local symbol, write a label of the form @samp{@b{N}:} (where @b{N}
3175represents any positive integer). To refer to the most recent previous
3176definition of that symbol write @samp{@b{N}b}, using the same number as when
3177you defined the label. To refer to the next definition of a local label, write
3178@samp{@b{N}f}--- The @samp{b} stands for``backwards'' and the @samp{f} stands
3179for ``forwards''.
3180
3181There is no restriction on how you can use these labels, and you can reuse them
3182too. So that it is possible to repeatedly define the same local label (using
3183the same number @samp{@b{N}}), although you can only refer to the most recently
3184defined local label of that number (for a backwards reference) or the next
3185definition of a specific local label for a forward reference. It is also worth
3186noting that the first 10 local labels (@samp{@b{0:}}@dots{}@samp{@b{9:}}) are
3187implemented in a slightly more efficient manner than the others.
3188
3189Here is an example:
3190
3191@smallexample
31921: branch 1f
31932: branch 1b
31941: branch 2f
31952: branch 1b
3196@end smallexample
3197
3198Which is the equivalent of:
3199
3200@smallexample
3201label_1: branch label_3
3202label_2: branch label_1
3203label_3: branch label_4
3204label_4: branch label_3
3205@end smallexample
3206
3207Local symbol names are only a notational device. They are immediately
3208transformed into more conventional symbol names before the assembler uses them.
3209The symbol names stored in the symbol table, appearing in error messages and
3210optionally emitted to the object file. The names are constructed using these
252b5132
RH
3211parts:
3212
3213@table @code
3214@item L
a4fb0134 3215All local labels begin with @samp{L}. Normally both @command{@value{AS}} and
252b5132
RH
3216@code{@value{LD}} forget symbols that start with @samp{L}. These labels are
3217used for symbols you are never intended to see. If you use the
a4fb0134 3218@samp{-L} option then @command{@value{AS}} retains these symbols in the
252b5132
RH
3219object file. If you also instruct @code{@value{LD}} to retain these symbols,
3220you may use them in debugging.
3221
2d5aaba0
NC
3222@item @var{number}
3223This is the number that was used in the local label definition. So if the
3224label is written @samp{55:} then the number is @samp{55}.
252b5132 3225
2d5aaba0
NC
3226@item @kbd{C-B}
3227This unusual character is included so you do not accidentally invent a symbol
3228of the same name. The character has ASCII value of @samp{\002} (control-B).
252b5132
RH
3229
3230@item @emph{ordinal number}
2d5aaba0
NC
3231This is a serial number to keep the labels distinct. The first definition of
3232@samp{0:} gets the number @samp{1}. The 15th definition of @samp{0:} gets the
3233number @samp{15}, and so on. Likewise the first definition of @samp{1:} gets
3234the number @samp{1} and its 15th defintion gets @samp{15} as well.
252b5132
RH
3235@end table
3236
2d5aaba0
NC
3237So for example, the first @code{1:} is named @code{L1@kbd{C-B}1}, the 44th
3238@code{3:} is named @code{L3@kbd{C-B}44}.
3239
3240@subheading Dollar Local Labels
3241@cindex dollar local symbols
3242
3243@code{@value{AS}} also supports an even more local form of local labels called
3244dollar labels. These labels go out of scope (ie they become undefined) as soon
3245as a non-local label is defined. Thus they remain valid for only a small
3246region of the input source code. Normal local labels, by contrast, remain in
3247scope for the entire file, or until they are redefined by another occurrence of
3248the same local label.
3249
3250Dollar labels are defined in exactly the same way as ordinary local labels,
3251except that instead of being terminated by a colon, they are terminated by a
3252dollar sign. eg @samp{@b{55$}}.
3253
3254They can also be distinguished from ordinary local labels by their transformed
3255name which uses ASCII character @samp{\001} (control-A) as the magic character
3256to distinguish them from ordinary labels. Thus the 5th defintion of @samp{6$}
3257is named @samp{L6@kbd{C-A}5}.
252b5132
RH
3258
3259@node Dot
3260@section The Special Dot Symbol
3261
3262@cindex dot (symbol)
3263@cindex @code{.} (symbol)
3264@cindex current address
3265@cindex location counter
3266The special symbol @samp{.} refers to the current address that
a4fb0134 3267@command{@value{AS}} is assembling into. Thus, the expression @samp{melvin:
252b5132
RH
3268.long .} defines @code{melvin} to contain its own address.
3269Assigning a value to @code{.} is treated the same as a @code{.org}
3270directive. Thus, the expression @samp{.=.+4} is the same as saying
3271@ifclear no-space-dir
3272@samp{.space 4}.
3273@end ifclear
3274@ifset no-space-dir
3275@ifset A29K
3276@samp{.block 4}.
3277@end ifset
3278@end ifset
3279
3280@node Symbol Attributes
3281@section Symbol Attributes
3282
3283@cindex symbol attributes
3284@cindex attributes, symbol
3285Every symbol has, as well as its name, the attributes ``Value'' and
3286``Type''. Depending on output format, symbols can also have auxiliary
3287attributes.
3288@ifset INTERNALS
3289The detailed definitions are in @file{a.out.h}.
3290@end ifset
3291
a4fb0134 3292If you use a symbol without defining it, @command{@value{AS}} assumes zero for
252b5132
RH
3293all these attributes, and probably won't warn you. This makes the
3294symbol an externally defined symbol, which is generally what you
3295would want.
3296
3297@menu
3298* Symbol Value:: Value
3299* Symbol Type:: Type
3300@ifset aout-bout
3301@ifset GENERIC
3302* a.out Symbols:: Symbol Attributes: @code{a.out}
3303@end ifset
3304@ifclear GENERIC
3305@ifclear BOUT
3306* a.out Symbols:: Symbol Attributes: @code{a.out}
3307@end ifclear
3308@ifset BOUT
3309* a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out}
3310@end ifset
3311@end ifclear
3312@end ifset
3313@ifset COFF
3314* COFF Symbols:: Symbol Attributes for COFF
3315@end ifset
3316@ifset SOM
3317* SOM Symbols:: Symbol Attributes for SOM
3318@end ifset
3319@end menu
3320
3321@node Symbol Value
3322@subsection Value
3323
3324@cindex value of a symbol
3325@cindex symbol value
3326The value of a symbol is (usually) 32 bits. For a symbol which labels a
3327location in the text, data, bss or absolute sections the value is the
3328number of addresses from the start of that section to the label.
3329Naturally for text, data and bss sections the value of a symbol changes
3330as @code{@value{LD}} changes section base addresses during linking. Absolute
3331symbols' values do not change during linking: that is why they are
3332called absolute.
3333
3334The value of an undefined symbol is treated in a special way. If it is
33350 then the symbol is not defined in this assembler source file, and
3336@code{@value{LD}} tries to determine its value from other files linked into the
3337same program. You make this kind of symbol simply by mentioning a symbol
3338name without defining it. A non-zero value represents a @code{.comm}
3339common declaration. The value is how much common storage to reserve, in
3340bytes (addresses). The symbol refers to the first address of the
3341allocated storage.
3342
3343@node Symbol Type
3344@subsection Type
3345
3346@cindex type of a symbol
3347@cindex symbol type
3348The type attribute of a symbol contains relocation (section)
3349information, any flag settings indicating that a symbol is external, and
3350(optionally), other information for linkers and debuggers. The exact
3351format depends on the object-code output format in use.
3352
3353@ifset aout-bout
3354@ifclear GENERIC
3355@ifset BOUT
3356@c The following avoids a "widow" subsection title. @group would be
3357@c better if it were available outside examples.
3358@need 1000
3359@node a.out Symbols
3360@subsection Symbol Attributes: @code{a.out}, @code{b.out}
3361
3362@cindex @code{b.out} symbol attributes
3363@cindex symbol attributes, @code{b.out}
a4fb0134 3364These symbol attributes appear only when @command{@value{AS}} is configured for
252b5132
RH
3365one of the Berkeley-descended object output formats---@code{a.out} or
3366@code{b.out}.
3367
3368@end ifset
3369@ifclear BOUT
3370@node a.out Symbols
3371@subsection Symbol Attributes: @code{a.out}
3372
3373@cindex @code{a.out} symbol attributes
3374@cindex symbol attributes, @code{a.out}
3375
3376@end ifclear
3377@end ifclear
3378@ifset GENERIC
3379@node a.out Symbols
3380@subsection Symbol Attributes: @code{a.out}
3381
3382@cindex @code{a.out} symbol attributes
3383@cindex symbol attributes, @code{a.out}
3384
3385@end ifset
3386@menu
3387* Symbol Desc:: Descriptor
3388* Symbol Other:: Other
3389@end menu
3390
3391@node Symbol Desc
3392@subsubsection Descriptor
3393
3394@cindex descriptor, of @code{a.out} symbol
3395This is an arbitrary 16-bit value. You may establish a symbol's
3396descriptor value by using a @code{.desc} statement
3397(@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to
a4fb0134 3398@command{@value{AS}}.
252b5132
RH
3399
3400@node Symbol Other
3401@subsubsection Other
3402
3403@cindex other attribute, of @code{a.out} symbol
a4fb0134 3404This is an arbitrary 8-bit value. It means nothing to @command{@value{AS}}.
252b5132
RH
3405@end ifset
3406
3407@ifset COFF
3408@node COFF Symbols
3409@subsection Symbol Attributes for COFF
3410
3411@cindex COFF symbol attributes
3412@cindex symbol attributes, COFF
3413
3414The COFF format supports a multitude of auxiliary symbol attributes;
3415like the primary symbol attributes, they are set between @code{.def} and
3416@code{.endef} directives.
3417
3418@subsubsection Primary Attributes
3419
3420@cindex primary attributes, COFF symbols
3421The symbol name is set with @code{.def}; the value and type,
3422respectively, with @code{.val} and @code{.type}.
3423
3424@subsubsection Auxiliary Attributes
3425
3426@cindex auxiliary attributes, COFF symbols
a4fb0134 3427The @command{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl},
252b5132
RH
3428@code{.size}, and @code{.tag} can generate auxiliary symbol table
3429information for COFF.
3430@end ifset
3431
3432@ifset SOM
3433@node SOM Symbols
3434@subsection Symbol Attributes for SOM
3435
3436@cindex SOM symbol attributes
3437@cindex symbol attributes, SOM
3438
3439The SOM format for the HPPA supports a multitude of symbol attributes set with
3440the @code{.EXPORT} and @code{.IMPORT} directives.
3441
3442The attributes are described in @cite{HP9000 Series 800 Assembly
3443Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and
3444@code{EXPORT} assembler directive documentation.
3445@end ifset
3446
3447@node Expressions
3448@chapter Expressions
3449
3450@cindex expressions
3451@cindex addresses
3452@cindex numeric values
3453An @dfn{expression} specifies an address or numeric value.
3454Whitespace may precede and/or follow an expression.
3455
3456The result of an expression must be an absolute number, or else an offset into
3457a particular section. If an expression is not absolute, and there is not
a4fb0134 3458enough information when @command{@value{AS}} sees the expression to know its
252b5132
RH
3459section, a second pass over the source program might be necessary to interpret
3460the expression---but the second pass is currently not implemented.
a4fb0134 3461@command{@value{AS}} aborts with an error message in this situation.
252b5132
RH
3462
3463@menu
3464* Empty Exprs:: Empty Expressions
3465* Integer Exprs:: Integer Expressions
3466@end menu
3467
3468@node Empty Exprs
3469@section Empty Expressions
3470
3471@cindex empty expressions
3472@cindex expressions, empty
3473An empty expression has no value: it is just whitespace or null.
3474Wherever an absolute expression is required, you may omit the
a4fb0134 3475expression, and @command{@value{AS}} assumes a value of (absolute) 0. This
252b5132
RH
3476is compatible with other assemblers.
3477
3478@node Integer Exprs
3479@section Integer Expressions
3480
3481@cindex integer expressions
3482@cindex expressions, integer
3483An @dfn{integer expression} is one or more @emph{arguments} delimited
3484by @emph{operators}.
3485
3486@menu
3487* Arguments:: Arguments
3488* Operators:: Operators
3489* Prefix Ops:: Prefix Operators
3490* Infix Ops:: Infix Operators
3491@end menu
3492
3493@node Arguments
3494@subsection Arguments
3495
3496@cindex expression arguments
3497@cindex arguments in expressions
3498@cindex operands in expressions
3499@cindex arithmetic operands
3500@dfn{Arguments} are symbols, numbers or subexpressions. In other
3501contexts arguments are sometimes called ``arithmetic operands''. In
3502this manual, to avoid confusing them with the ``instruction operands'' of
3503the machine language, we use the term ``argument'' to refer to parts of
3504expressions only, reserving the word ``operand'' to refer only to machine
3505instruction operands.
3506
3507Symbols are evaluated to yield @{@var{section} @var{NNN}@} where
3508@var{section} is one of text, data, bss, absolute,
3509or undefined. @var{NNN} is a signed, 2's complement 32 bit
3510integer.
3511
3512Numbers are usually integers.
3513
3514A number can be a flonum or bignum. In this case, you are warned
a4fb0134 3515that only the low order 32 bits are used, and @command{@value{AS}} pretends
252b5132
RH
3516these 32 bits are an integer. You may write integer-manipulating
3517instructions that act on exotic constants, compatible with other
3518assemblers.
3519
3520@cindex subexpressions
3521Subexpressions are a left parenthesis @samp{(} followed by an integer
3522expression, followed by a right parenthesis @samp{)}; or a prefix
3523operator followed by an argument.
3524
3525@node Operators
3526@subsection Operators
3527
3528@cindex operators, in expressions
3529@cindex arithmetic functions
3530@cindex functions, in expressions
3531@dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix
3532operators are followed by an argument. Infix operators appear
3533between their arguments. Operators may be preceded and/or followed by
3534whitespace.
3535
3536@node Prefix Ops
3537@subsection Prefix Operator
3538
3539@cindex prefix operators
a4fb0134 3540@command{@value{AS}} has the following @dfn{prefix operators}. They each take
252b5132
RH
3541one argument, which must be absolute.
3542
3543@c the tex/end tex stuff surrounding this small table is meant to make
3544@c it align, on the printed page, with the similar table in the next
3545@c section (which is inside an enumerate).
3546@tex
3547\global\advance\leftskip by \itemindent
3548@end tex
3549
3550@table @code
3551@item -
3552@dfn{Negation}. Two's complement negation.
3553@item ~
3554@dfn{Complementation}. Bitwise not.
3555@end table
3556
3557@tex
3558\global\advance\leftskip by -\itemindent
3559@end tex
3560
3561@node Infix Ops
3562@subsection Infix Operators
3563
3564@cindex infix operators
3565@cindex operators, permitted arguments
3566@dfn{Infix operators} take two arguments, one on either side. Operators
3567have precedence, but operations with equal precedence are performed left
a4fb0134 3568to right. Apart from @code{+} or @option{-}, both arguments must be
252b5132
RH
3569absolute, and the result is absolute.
3570
3571@enumerate
3572@cindex operator precedence
3573@cindex precedence of operators
3574
3575@item
3576Highest Precedence
3577
3578@table @code
3579@item *
3580@dfn{Multiplication}.
3581
3582@item /
3583@dfn{Division}. Truncation is the same as the C operator @samp{/}
3584
3585@item %
3586@dfn{Remainder}.
3587
3588@item <
3589@itemx <<
3590@dfn{Shift Left}. Same as the C operator @samp{<<}.
3591
3592@item >
3593@itemx >>
3594@dfn{Shift Right}. Same as the C operator @samp{>>}.
3595@end table
3596
3597@item
3598Intermediate precedence
3599
3600@table @code
3601@item |
3602
3603@dfn{Bitwise Inclusive Or}.
3604
3605@item &
3606@dfn{Bitwise And}.
3607
3608@item ^
3609@dfn{Bitwise Exclusive Or}.
3610
3611@item !
3612@dfn{Bitwise Or Not}.
3613@end table
3614
3615@item
b131d4dc 3616Low Precedence
252b5132
RH
3617
3618@table @code
3619@cindex addition, permitted arguments
3620@cindex plus, permitted arguments
3621@cindex arguments for addition
3622@item +
3623@dfn{Addition}. If either argument is absolute, the result has the section of
3624the other argument. You may not add together arguments from different
3625sections.
3626
3627@cindex subtraction, permitted arguments
3628@cindex minus, permitted arguments
3629@cindex arguments for subtraction
3630@item -
3631@dfn{Subtraction}. If the right argument is absolute, the
3632result has the section of the left argument.
3633If both arguments are in the same section, the result is absolute.
3634You may not subtract arguments from different sections.
3635@c FIXME is there still something useful to say about undefined - undefined ?
b131d4dc
NC
3636
3637@cindex comparison expressions
3638@cindex expressions, comparison
3639@item ==
3640@dfn{Is Equal To}
3641@item <>
3642@dfn{Is Not Equal To}
3643@item <
3644@dfn{Is Less Than}
3645@itemx >
3646@dfn{Is Greater Than}
3647@itemx >=
3648@dfn{Is Greater Than Or Equal To}
3649@itemx <=
3650@dfn{Is Less Than Or Equal To}
3651
3652The comparison operators can be used as infix operators. A true results has a
3653value of -1 whereas a false result has a value of 0. Note, these operators
3654perform signed comparisons.
3655@end table
3656
3657@item Lowest Precedence
3658
3659@table @code
3660@item &&
3661@dfn{Logical And}.
3662
3663@item ||
3664@dfn{Logical Or}.
3665
3666These two logical operations can be used to combine the results of sub
3667expressions. Note, unlike the comparison operators a true result returns a
3668value of 1 but a false results does still return 0. Also note that the logical
3669or operator has a slightly lower precedence than logical and.
3670
252b5132
RH
3671@end table
3672@end enumerate
3673
3674In short, it's only meaningful to add or subtract the @emph{offsets} in an
3675address; you can only have a defined section in one of the two arguments.
3676
3677@node Pseudo Ops
3678@chapter Assembler Directives
3679
3680@cindex directives, machine independent
3681@cindex pseudo-ops, machine independent
3682@cindex machine independent directives
3683All assembler directives have names that begin with a period (@samp{.}).
3684The rest of the name is letters, usually in lower case.
3685
3686This chapter discusses directives that are available regardless of the
3687target machine configuration for the @sc{gnu} assembler.
3688@ifset GENERIC
3689Some machine configurations provide additional directives.
3690@xref{Machine Dependencies}.
3691@end ifset
3692@ifclear GENERIC
3693@ifset machine-directives
3694@xref{Machine Dependencies} for additional directives.
3695@end ifset
3696@end ifclear
3697
3698@menu
3699* Abort:: @code{.abort}
3700@ifset COFF
3701* ABORT:: @code{.ABORT}
3702@end ifset
f0dc282c 3703
252b5132
RH
3704* Align:: @code{.align @var{abs-expr} , @var{abs-expr}}
3705* Ascii:: @code{.ascii "@var{string}"}@dots{}
3706* Asciz:: @code{.asciz "@var{string}"}@dots{}
3707* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}}
3708* Byte:: @code{.byte @var{expressions}}
3709* Comm:: @code{.comm @var{symbol} , @var{length} }
54cfded0 3710
cdfbf930 3711* CFI directives:: @code{.cfi_startproc}, @code{.cfi_endproc}, etc.
54cfded0 3712
252b5132
RH
3713* Data:: @code{.data @var{subsection}}
3714@ifset COFF
3715* Def:: @code{.def @var{name}}
3716@end ifset
3717@ifset aout-bout
3718* Desc:: @code{.desc @var{symbol}, @var{abs-expression}}
3719@end ifset
3720@ifset COFF
3721* Dim:: @code{.dim}
3722@end ifset
f0dc282c 3723
252b5132
RH
3724* Double:: @code{.double @var{flonums}}
3725* Eject:: @code{.eject}
3726* Else:: @code{.else}
3fd9f047 3727* Elseif:: @code{.elseif}
252b5132
RH
3728* End:: @code{.end}
3729@ifset COFF
3730* Endef:: @code{.endef}
3731@end ifset
f0dc282c 3732
252b5132
RH
3733* Endfunc:: @code{.endfunc}
3734* Endif:: @code{.endif}
3735* Equ:: @code{.equ @var{symbol}, @var{expression}}
3736* Equiv:: @code{.equiv @var{symbol}, @var{expression}}
3737* Err:: @code{.err}
3738* Exitm:: @code{.exitm}
3739* Extern:: @code{.extern}
3740* Fail:: @code{.fail}
3741@ifclear no-file-dir
3742* File:: @code{.file @var{string}}
3743@end ifclear
f0dc282c 3744
252b5132
RH
3745* Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}}
3746* Float:: @code{.float @var{flonums}}
3747* Func:: @code{.func}
3748* Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}}
c91d2e08
NC
3749@ifset ELF
3750* Hidden:: @code{.hidden @var{names}}
3751@end ifset
f0dc282c 3752
252b5132
RH
3753* hword:: @code{.hword @var{expressions}}
3754* Ident:: @code{.ident}
3755* If:: @code{.if @var{absolute expression}}
7e005732 3756* Incbin:: @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]}
252b5132
RH
3757* Include:: @code{.include "@var{file}"}
3758* Int:: @code{.int @var{expressions}}
c91d2e08
NC
3759@ifset ELF
3760* Internal:: @code{.internal @var{names}}
3761@end ifset
f0dc282c 3762
252b5132
RH
3763* Irp:: @code{.irp @var{symbol},@var{values}}@dots{}
3764* Irpc:: @code{.irpc @var{symbol},@var{values}}@dots{}
3765* Lcomm:: @code{.lcomm @var{symbol} , @var{length}}
3766* Lflags:: @code{.lflags}
3767@ifclear no-line-dir
3768* Line:: @code{.line @var{line-number}}
3769@end ifclear
f0dc282c 3770
252b5132
RH
3771* Ln:: @code{.ln @var{line-number}}
3772* Linkonce:: @code{.linkonce [@var{type}]}
3773* List:: @code{.list}
3774* Long:: @code{.long @var{expressions}}
3775@ignore
3776* Lsym:: @code{.lsym @var{symbol}, @var{expression}}
3777@end ignore
f0dc282c 3778
252b5132
RH
3779* Macro:: @code{.macro @var{name} @var{args}}@dots{}
3780* MRI:: @code{.mri @var{val}}
252b5132
RH
3781* Nolist:: @code{.nolist}
3782* Octa:: @code{.octa @var{bignums}}
3783* Org:: @code{.org @var{new-lc} , @var{fill}}
3784* P2align:: @code{.p2align @var{abs-expr} , @var{abs-expr}}
c91d2e08
NC
3785@ifset ELF
3786* PopSection:: @code{.popsection}
3787* Previous:: @code{.previous}
3788@end ifset
f0dc282c 3789
252b5132 3790* Print:: @code{.print @var{string}}
c91d2e08
NC
3791@ifset ELF
3792* Protected:: @code{.protected @var{names}}
3793@end ifset
f0dc282c 3794
252b5132
RH
3795* Psize:: @code{.psize @var{lines}, @var{columns}}
3796* Purgem:: @code{.purgem @var{name}}
c91d2e08
NC
3797@ifset ELF
3798* PushSection:: @code{.pushsection @var{name}}
3799@end ifset
f0dc282c 3800
252b5132
RH
3801* Quad:: @code{.quad @var{bignums}}
3802* Rept:: @code{.rept @var{count}}
3803* Sbttl:: @code{.sbttl "@var{subheading}"}
3804@ifset COFF
3805* Scl:: @code{.scl @var{class}}
c1253627
NC
3806@end ifset
3807@ifset COFF-ELF
3808* Section:: @code{.section @var{name}}
252b5132 3809@end ifset
f0dc282c 3810
252b5132
RH
3811* Set:: @code{.set @var{symbol}, @var{expression}}
3812* Short:: @code{.short @var{expressions}}
3813* Single:: @code{.single @var{flonums}}
c1253627 3814@ifset COFF-ELF
c91d2e08 3815* Size:: @code{.size [@var{name} , @var{expression}]}
c1253627
NC
3816@end ifset
3817
252b5132
RH
3818* Skip:: @code{.skip @var{size} , @var{fill}}
3819* Sleb128:: @code{.sleb128 @var{expressions}}
3820* Space:: @code{.space @var{size} , @var{fill}}
3821@ifset have-stabs
3822* Stab:: @code{.stabd, .stabn, .stabs}
3823@end ifset
f0dc282c 3824
252b5132
RH
3825* String:: @code{.string "@var{str}"}
3826* Struct:: @code{.struct @var{expression}}
3827@ifset ELF
c91d2e08 3828* SubSection:: @code{.subsection}
252b5132
RH
3829* Symver:: @code{.symver @var{name},@var{name2@@nodename}}
3830@end ifset
f0dc282c 3831
252b5132
RH
3832@ifset COFF
3833* Tag:: @code{.tag @var{structname}}
3834@end ifset
f0dc282c 3835
252b5132
RH
3836* Text:: @code{.text @var{subsection}}
3837* Title:: @code{.title "@var{heading}"}
c1253627 3838@ifset COFF-ELF
c91d2e08 3839* Type:: @code{.type <@var{int} | @var{name} , @var{type description}>}
c1253627
NC
3840@end ifset
3841
c91d2e08 3842* Uleb128:: @code{.uleb128 @var{expressions}}
252b5132 3843@ifset COFF
252b5132
RH
3844* Val:: @code{.val @var{addr}}
3845@end ifset
f0dc282c 3846
2e13b764 3847@ifset ELF
c91d2e08 3848* Version:: @code{.version "@var{string}"}
c91d2e08
NC
3849* VTableEntry:: @code{.vtable_entry @var{table}, @var{offset}}
3850* VTableInherit:: @code{.vtable_inherit @var{child}, @var{parent}}
c91d2e08 3851* Weak:: @code{.weak @var{names}}
2e13b764 3852@end ifset
f0dc282c 3853
252b5132
RH
3854* Word:: @code{.word @var{expressions}}
3855* Deprecated:: Deprecated Directives
3856@end menu
3857
3858@node Abort
3859@section @code{.abort}
3860
3861@cindex @code{abort} directive
3862@cindex stopping the assembly
3863This directive stops the assembly immediately. It is for
3864compatibility with other assemblers. The original idea was that the
3865assembly language source would be piped into the assembler. If the sender
a4fb0134 3866of the source quit, it could use this directive tells @command{@value{AS}} to
252b5132
RH
3867quit also. One day @code{.abort} will not be supported.
3868
3869@ifset COFF
3870@node ABORT
3871@section @code{.ABORT}
3872
3873@cindex @code{ABORT} directive
a4fb0134 3874When producing COFF output, @command{@value{AS}} accepts this directive as a
252b5132
RH
3875synonym for @samp{.abort}.
3876
3877@ifset BOUT
a4fb0134 3878When producing @code{b.out} output, @command{@value{AS}} accepts this directive,
252b5132
RH
3879but ignores it.
3880@end ifset
3881@end ifset
3882
3883@node Align
3884@section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
3885
3886@cindex padding the location counter
3887@cindex @code{align} directive
3888Pad the location counter (in the current subsection) to a particular storage
3889boundary. The first expression (which must be absolute) is the alignment
3890required, as described below.
3891
3892The second expression (also absolute) gives the fill value to be stored in the
3893padding bytes. It (and the comma) may be omitted. If it is omitted, the
3894padding bytes are normally zero. However, on some systems, if the section is
3895marked as containing code and the fill value is omitted, the space is filled
3896with no-op instructions.
3897
3898The third expression is also absolute, and is also optional. If it is present,
3899it is the maximum number of bytes that should be skipped by this alignment
3900directive. If doing the alignment would require skipping more bytes than the
3901specified maximum, then the alignment is not done at all. You can omit the
3902fill value (the second argument) entirely by simply using two commas after the
3903required alignment; this can be useful if you want the alignment to be filled
3904with no-op instructions when appropriate.
3905
3906The way the required alignment is specified varies from system to system.
60946ad0
AM
3907For the a29k, arc, hppa, i386 using ELF, i860, iq2000, m68k, m88k, or32,
3908s390, sparc, tic4x, tic80 and xtensa, the first expression is the
252b5132
RH
3909alignment request in bytes. For example @samp{.align 8} advances
3910the location counter until it is a multiple of 8. If the location counter
60946ad0
AM
3911is already a multiple of 8, no change is needed. For the tic54x, the
3912first expression is the alignment request in words.
252b5132 3913
adcf07e6
NC
3914For other systems, including the i386 using a.out format, and the arm and
3915strongarm, it is the
252b5132
RH
3916number of low-order zero bits the location counter must have after
3917advancement. For example @samp{.align 3} advances the location
3918counter until it a multiple of 8. If the location counter is already a
3919multiple of 8, no change is needed.
3920
3921This inconsistency is due to the different behaviors of the various
3922native assemblers for these systems which GAS must emulate.
3923GAS also provides @code{.balign} and @code{.p2align} directives,
3924described later, which have a consistent behavior across all
3925architectures (but are specific to GAS).
3926
3927@node Ascii
3928@section @code{.ascii "@var{string}"}@dots{}
3929
3930@cindex @code{ascii} directive
3931@cindex string literals
3932@code{.ascii} expects zero or more string literals (@pxref{Strings})
3933separated by commas. It assembles each string (with no automatic
3934trailing zero byte) into consecutive addresses.
3935
3936@node Asciz
3937@section @code{.asciz "@var{string}"}@dots{}
3938
3939@cindex @code{asciz} directive
3940@cindex zero-terminated strings
3941@cindex null-terminated strings
3942@code{.asciz} is just like @code{.ascii}, but each string is followed by
3943a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''.
3944
3945@node Balign
3946@section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
3947
3948@cindex padding the location counter given number of bytes
3949@cindex @code{balign} directive
3950Pad the location counter (in the current subsection) to a particular
3951storage boundary. The first expression (which must be absolute) is the
3952alignment request in bytes. For example @samp{.balign 8} advances
3953the location counter until it is a multiple of 8. If the location counter
3954is already a multiple of 8, no change is needed.
3955
3956The second expression (also absolute) gives the fill value to be stored in the
3957padding bytes. It (and the comma) may be omitted. If it is omitted, the
3958padding bytes are normally zero. However, on some systems, if the section is
3959marked as containing code and the fill value is omitted, the space is filled
3960with no-op instructions.
3961
3962The third expression is also absolute, and is also optional. If it is present,
3963it is the maximum number of bytes that should be skipped by this alignment
3964directive. If doing the alignment would require skipping more bytes than the
3965specified maximum, then the alignment is not done at all. You can omit the
3966fill value (the second argument) entirely by simply using two commas after the
3967required alignment; this can be useful if you want the alignment to be filled
3968with no-op instructions when appropriate.
3969
3970@cindex @code{balignw} directive
3971@cindex @code{balignl} directive
3972The @code{.balignw} and @code{.balignl} directives are variants of the
3973@code{.balign} directive. The @code{.balignw} directive treats the fill
3974pattern as a two byte word value. The @code{.balignl} directives treats the
3975fill pattern as a four byte longword value. For example, @code{.balignw
39764,0x368d} will align to a multiple of 4. If it skips two bytes, they will be
3977filled in with the value 0x368d (the exact placement of the bytes depends upon
3978the endianness of the processor). If it skips 1 or 3 bytes, the fill value is
3979undefined.
3980
3981@node Byte
3982@section @code{.byte @var{expressions}}
3983
3984@cindex @code{byte} directive
3985@cindex integers, one byte
3986@code{.byte} expects zero or more expressions, separated by commas.
3987Each expression is assembled into the next byte.
3988
d88ef7a6
TT
3989@node Comm
3990@section @code{.comm @var{symbol} , @var{length} }
3991
3992@cindex @code{comm} directive
3993@cindex symbol, common
3994@code{.comm} declares a common symbol named @var{symbol}. When linking, a
3995common symbol in one object file may be merged with a defined or common symbol
3996of the same name in another object file. If @code{@value{LD}} does not see a
3997definition for the symbol--just one or more common symbols--then it will
3998allocate @var{length} bytes of uninitialized memory. @var{length} must be an
3999absolute expression. If @code{@value{LD}} sees multiple common symbols with
4000the same name, and they do not all have the same size, it will allocate space
4001using the largest size.
4002
4003@ifset ELF
4004When using ELF, the @code{.comm} directive takes an optional third argument.
4005This is the desired alignment of the symbol, specified as a byte boundary (for
4006example, an alignment of 16 means that the least significant 4 bits of the
4007address should be zero). The alignment must be an absolute expression, and it
4008must be a power of two. If @code{@value{LD}} allocates uninitialized memory
4009for the common symbol, it will use the alignment when placing the symbol. If
4010no alignment is specified, @command{@value{AS}} will set the alignment to the
4011largest power of two less than or equal to the size of the symbol, up to a
4012maximum of 16.
4013@end ifset
4014
4015@ifset HPPA
4016The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
4017@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional.
4018@end ifset
4019
54cfded0
AM
4020@node CFI directives
4021@section @code{.cfi_startproc}
4022@cindex @code{cfi_startproc} directive
4023@code{.cfi_startproc} is used at the beginning of each function that
4024should have an entry in @code{.eh_frame}. It initializes some internal
4025data structures and emits architecture dependent initial CFI instructions.
4026Don't forget to close the function by
4027@code{.cfi_endproc}.
4028
4029@section @code{.cfi_endproc}
4030@cindex @code{cfi_endproc} directive
4031@code{.cfi_endproc} is used at the end of a function where it closes its
4032unwind entry previously opened by
4033@code{.cfi_startproc}. and emits it to @code{.eh_frame}.
4034
4035@section @code{.cfi_def_cfa @var{register}, @var{offset}}
4036@code{.cfi_def_cfa} defines a rule for computing CFA as: @i{take
4037address from @var{register} and add @var{offset} to it}.
4038
4039@section @code{.cfi_def_cfa_register @var{register}}
4040@code{.cfi_def_cfa_register} modifies a rule for computing CFA. From
4041now on @var{register} will be used instead of the old one. Offset
4042remains the same.
4043
4044@section @code{.cfi_def_cfa_offset @var{offset}}
4045@code{.cfi_def_cfa_offset} modifies a rule for computing CFA. Register
4046remains the same, but @var{offset} is new. Note that it is the
4047absolute offset that will be added to a defined register to compute
4048CFA address.
4049
4050@section @code{.cfi_adjust_cfa_offset @var{offset}}
4051Same as @code{.cfi_def_cfa_offset} but @var{offset} is a relative
4052value that is added/substracted from the previous offset.
4053
4054@section @code{.cfi_offset @var{register}, @var{offset}}
4055Previous value of @var{register} is saved at offset @var{offset} from
4056CFA.
4057
17076204
RH
4058@section @code{.cfi_rel_offset @var{register}, @var{offset}}
4059Previous value of @var{register} is saved at offset @var{offset} from
4060the current CFA register. This is transformed to @code{.cfi_offset}
4061using the known displacement of the CFA register from the CFA.
4062This is often easier to use, because the number will match the
4063code it's annotating.
54cfded0 4064
6749011b 4065@section @code{.cfi_window_save}
364b6d8b
JJ
4066SPARC register window has been saved.
4067
cdfbf930
RH
4068@section @code{.cfi_escape} @var{expression}[, @dots{}]
4069Allows the user to add arbitrary bytes to the unwind info. One
4070might use this to add OS-specific CFI opcodes, or generic CFI
4071opcodes that GAS does not yet support.
252b5132 4072
252b5132
RH
4073@node Data
4074@section @code{.data @var{subsection}}
4075
4076@cindex @code{data} directive
a4fb0134 4077@code{.data} tells @command{@value{AS}} to assemble the following statements onto the
252b5132
RH
4078end of the data subsection numbered @var{subsection} (which is an
4079absolute expression). If @var{subsection} is omitted, it defaults
4080to zero.
4081
4082@ifset COFF
4083@node Def
4084@section @code{.def @var{name}}
4085
4086@cindex @code{def} directive
4087@cindex COFF symbols, debugging
4088@cindex debugging COFF symbols
4089Begin defining debugging information for a symbol @var{name}; the
4090definition extends until the @code{.endef} directive is encountered.
4091@ifset BOUT
4092
a4fb0134 4093This directive is only observed when @command{@value{AS}} is configured for COFF
252b5132
RH
4094format output; when producing @code{b.out}, @samp{.def} is recognized,
4095but ignored.
4096@end ifset
4097@end ifset
4098
4099@ifset aout-bout
4100@node Desc
4101@section @code{.desc @var{symbol}, @var{abs-expression}}
4102
4103@cindex @code{desc} directive
4104@cindex COFF symbol descriptor
4105@cindex symbol descriptor, COFF
4106This directive sets the descriptor of the symbol (@pxref{Symbol Attributes})
4107to the low 16 bits of an absolute expression.
4108
4109@ifset COFF
a4fb0134 4110The @samp{.desc} directive is not available when @command{@value{AS}} is
252b5132 4111configured for COFF output; it is only for @code{a.out} or @code{b.out}
a4fb0134 4112object format. For the sake of compatibility, @command{@value{AS}} accepts
252b5132
RH
4113it, but produces no output, when configured for COFF.
4114@end ifset
4115@end ifset
4116
4117@ifset COFF
4118@node Dim
4119@section @code{.dim}
4120
4121@cindex @code{dim} directive
4122@cindex COFF auxiliary symbol information
4123@cindex auxiliary symbol information, COFF
4124This directive is generated by compilers to include auxiliary debugging
4125information in the symbol table. It is only permitted inside
4126@code{.def}/@code{.endef} pairs.
4127@ifset BOUT
4128
4129@samp{.dim} is only meaningful when generating COFF format output; when
a4fb0134 4130@command{@value{AS}} is generating @code{b.out}, it accepts this directive but
252b5132
RH
4131ignores it.
4132@end ifset
4133@end ifset
4134
4135@node Double
4136@section @code{.double @var{flonums}}
4137
4138@cindex @code{double} directive
4139@cindex floating point numbers (double)
4140@code{.double} expects zero or more flonums, separated by commas. It
4141assembles floating point numbers.
4142@ifset GENERIC
4143The exact kind of floating point numbers emitted depends on how
a4fb0134 4144@command{@value{AS}} is configured. @xref{Machine Dependencies}.
252b5132
RH
4145@end ifset
4146@ifclear GENERIC
4147@ifset IEEEFLOAT
4148On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers
4149in @sc{ieee} format.
4150@end ifset
4151@end ifclear
4152
4153@node Eject
4154@section @code{.eject}
4155
4156@cindex @code{eject} directive
4157@cindex new page, in listings
4158@cindex page, in listings
4159@cindex listing control: new page
4160Force a page break at this point, when generating assembly listings.
4161
4162@node Else
4163@section @code{.else}
4164
4165@cindex @code{else} directive
a4fb0134 4166@code{.else} is part of the @command{@value{AS}} support for conditional
252b5132
RH
4167assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section
4168of code to be assembled if the condition for the preceding @code{.if}
4169was false.
4170
3fd9f047
TW
4171@node Elseif
4172@section @code{.elseif}
4173
4174@cindex @code{elseif} directive
a4fb0134 4175@code{.elseif} is part of the @command{@value{AS}} support for conditional
3fd9f047
TW
4176assembly; @pxref{If,,@code{.if}}. It is shorthand for beginning a new
4177@code{.if} block that would otherwise fill the entire @code{.else} section.
4178
252b5132
RH
4179@node End
4180@section @code{.end}
4181
4182@cindex @code{end} directive
a4fb0134 4183@code{.end} marks the end of the assembly file. @command{@value{AS}} does not
252b5132
RH
4184process anything in the file past the @code{.end} directive.
4185
4186@ifset COFF
4187@node Endef
4188@section @code{.endef}
4189
4190@cindex @code{endef} directive
4191This directive flags the end of a symbol definition begun with
4192@code{.def}.
4193@ifset BOUT
4194
4195@samp{.endef} is only meaningful when generating COFF format output; if
a4fb0134 4196@command{@value{AS}} is configured to generate @code{b.out}, it accepts this
252b5132
RH
4197directive but ignores it.
4198@end ifset
4199@end ifset
4200
4201@node Endfunc
4202@section @code{.endfunc}
4203@cindex @code{endfunc} directive
4204@code{.endfunc} marks the end of a function specified with @code{.func}.
4205
4206@node Endif
4207@section @code{.endif}
4208
4209@cindex @code{endif} directive
a4fb0134 4210@code{.endif} is part of the @command{@value{AS}} support for conditional assembly;
252b5132
RH
4211it marks the end of a block of code that is only assembled
4212conditionally. @xref{If,,@code{.if}}.
4213
4214@node Equ
4215@section @code{.equ @var{symbol}, @var{expression}}
4216
4217@cindex @code{equ} directive
4218@cindex assigning values to symbols
4219@cindex symbols, assigning values to
4220This directive sets the value of @var{symbol} to @var{expression}.
4221It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}.
4222
4223@ifset HPPA
4224The syntax for @code{equ} on the HPPA is
4225@samp{@var{symbol} .equ @var{expression}}.
4226@end ifset
4227
4228@node Equiv
4229@section @code{.equiv @var{symbol}, @var{expression}}
4230@cindex @code{equiv} directive
4231The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that
8dfa0188
NC
4232the assembler will signal an error if @var{symbol} is already defined. Note a
4233symbol which has been referenced but not actually defined is considered to be
4234undefined.
252b5132
RH
4235
4236Except for the contents of the error message, this is roughly equivalent to
4237@smallexample
4238.ifdef SYM
4239.err
4240.endif
4241.equ SYM,VAL
4242@end smallexample
4243
4244@node Err
4245@section @code{.err}
4246@cindex @code{err} directive
a4fb0134
SC
4247If @command{@value{AS}} assembles a @code{.err} directive, it will print an error
4248message and, unless the @option{-Z} option was used, it will not generate an
252b5132
RH
4249object file. This can be used to signal error an conditionally compiled code.
4250
4251@node Exitm
4252@section @code{.exitm}
4253Exit early from the current macro definition. @xref{Macro}.
4254
4255@node Extern
4256@section @code{.extern}
4257
4258@cindex @code{extern} directive
4259@code{.extern} is accepted in the source program---for compatibility
a4fb0134 4260with other assemblers---but it is ignored. @command{@value{AS}} treats
252b5132
RH
4261all undefined symbols as external.
4262
4263@node Fail
4264@section @code{.fail @var{expression}}
4265
4266@cindex @code{fail} directive
4267Generates an error or a warning. If the value of the @var{expression} is 500
a4fb0134
SC
4268or more, @command{@value{AS}} will print a warning message. If the value is less
4269than 500, @command{@value{AS}} will print an error message. The message will
252b5132
RH
4270include the value of @var{expression}. This can occasionally be useful inside
4271complex nested macros or conditional assembly.
4272
4273@ifclear no-file-dir
4274@node File
4275@section @code{.file @var{string}}
4276
4277@cindex @code{file} directive
4278@cindex logical file name
4279@cindex file name, logical
a4fb0134 4280@code{.file} tells @command{@value{AS}} that we are about to start a new logical
252b5132
RH
4281file. @var{string} is the new file name. In general, the filename is
4282recognized whether or not it is surrounded by quotes @samp{"}; but if you wish
4283to specify an empty file name, you must give the quotes--@code{""}. This
4284statement may go away in future: it is only recognized to be compatible with
a4fb0134 4285old @command{@value{AS}} programs.
252b5132 4286@ifset A29K
a4fb0134 4287In some configurations of @command{@value{AS}}, @code{.file} has already been
252b5132
RH
4288removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}.
4289@end ifset
4290@end ifclear
4291
4292@node Fill
4293@section @code{.fill @var{repeat} , @var{size} , @var{value}}
4294
4295@cindex @code{fill} directive
4296@cindex writing patterns in memory
4297@cindex patterns, writing in memory
bc64be0c 4298@var{repeat}, @var{size} and @var{value} are absolute expressions.
252b5132
RH
4299This emits @var{repeat} copies of @var{size} bytes. @var{Repeat}
4300may be zero or more. @var{Size} may be zero or more, but if it is
4301more than 8, then it is deemed to have the value 8, compatible with
4302other people's assemblers. The contents of each @var{repeat} bytes
4303is taken from an 8-byte number. The highest order 4 bytes are
4304zero. The lowest order 4 bytes are @var{value} rendered in the
a4fb0134 4305byte-order of an integer on the computer @command{@value{AS}} is assembling for.
252b5132
RH
4306Each @var{size} bytes in a repetition is taken from the lowest order
4307@var{size} bytes of this number. Again, this bizarre behavior is
4308compatible with other people's assemblers.
4309
4310@var{size} and @var{value} are optional.
4311If the second comma and @var{value} are absent, @var{value} is
4312assumed zero. If the first comma and following tokens are absent,
4313@var{size} is assumed to be 1.
4314
4315@node Float
4316@section @code{.float @var{flonums}}
4317
4318@cindex floating point numbers (single)
4319@cindex @code{float} directive
4320This directive assembles zero or more flonums, separated by commas. It
4321has the same effect as @code{.single}.
4322@ifset GENERIC
4323The exact kind of floating point numbers emitted depends on how
a4fb0134 4324@command{@value{AS}} is configured.
252b5132
RH
4325@xref{Machine Dependencies}.
4326@end ifset
4327@ifclear GENERIC
4328@ifset IEEEFLOAT
4329On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers
4330in @sc{ieee} format.
4331@end ifset
4332@end ifclear
4333
4334@node Func
4335@section @code{.func @var{name}[,@var{label}]}
4336@cindex @code{func} directive
4337@code{.func} emits debugging information to denote function @var{name}, and
4338is ignored unless the file is assembled with debugging enabled.
05da4302 4339Only @samp{--gstabs[+]} is currently supported.
252b5132
RH
4340@var{label} is the entry point of the function and if omitted @var{name}
4341prepended with the @samp{leading char} is used.
4342@samp{leading char} is usually @code{_} or nothing, depending on the target.
4343All functions are currently defined to have @code{void} return type.
4344The function must be terminated with @code{.endfunc}.
4345
4346@node Global
4347@section @code{.global @var{symbol}}, @code{.globl @var{symbol}}
4348
4349@cindex @code{global} directive
4350@cindex symbol, making visible to linker
4351@code{.global} makes the symbol visible to @code{@value{LD}}. If you define
4352@var{symbol} in your partial program, its value is made available to
4353other partial programs that are linked with it. Otherwise,
4354@var{symbol} takes its attributes from a symbol of the same name
4355from another file linked into the same program.
4356
4357Both spellings (@samp{.globl} and @samp{.global}) are accepted, for
4358compatibility with other assemblers.
4359
4360@ifset HPPA
4361On the HPPA, @code{.global} is not always enough to make it accessible to other
4362partial programs. You may need the HPPA-only @code{.EXPORT} directive as well.
4363@xref{HPPA Directives,, HPPA Assembler Directives}.
4364@end ifset
4365
c91d2e08
NC
4366@ifset ELF
4367@node Hidden
4368@section @code{.hidden @var{names}}
4369
c1253627
NC
4370@cindex @code{hidden} directive
4371@cindex visibility
c91d2e08 4372This one of the ELF visibility directives. The other two are
a349d9dd
PB
4373@code{.internal} (@pxref{Internal,,@code{.internal}}) and
4374@code{.protected} (@pxref{Protected,,@code{.protected}}).
c91d2e08
NC
4375
4376This directive overrides the named symbols default visibility (which is set by
4377their binding: local, global or weak). The directive sets the visibility to
4378@code{hidden} which means that the symbols are not visible to other components.
4379Such symbols are always considered to be @code{protected} as well.
4380@end ifset
4381
252b5132
RH
4382@node hword
4383@section @code{.hword @var{expressions}}
4384
4385@cindex @code{hword} directive
4386@cindex integers, 16-bit
4387@cindex numbers, 16-bit
4388@cindex sixteen bit integers
4389This expects zero or more @var{expressions}, and emits
4390a 16 bit number for each.
4391
4392@ifset GENERIC
4393This directive is a synonym for @samp{.short}; depending on the target
4394architecture, it may also be a synonym for @samp{.word}.
4395@end ifset
4396@ifclear GENERIC
4397@ifset W32
4398This directive is a synonym for @samp{.short}.
4399@end ifset
4400@ifset W16
4401This directive is a synonym for both @samp{.short} and @samp{.word}.
4402@end ifset
4403@end ifclear
4404
4405@node Ident
4406@section @code{.ident}
4407
4408@cindex @code{ident} directive
4409This directive is used by some assemblers to place tags in object files.
a4fb0134 4410@command{@value{AS}} simply accepts the directive for source-file
252b5132
RH
4411compatibility with such assemblers, but does not actually emit anything
4412for it.
4413
4414@node If
4415@section @code{.if @var{absolute expression}}
4416
4417@cindex conditional assembly
4418@cindex @code{if} directive
4419@code{.if} marks the beginning of a section of code which is only
4420considered part of the source program being assembled if the argument
4421(which must be an @var{absolute expression}) is non-zero. The end of
4422the conditional section of code must be marked by @code{.endif}
4423(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the
4424alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}).
3fd9f047
TW
4425If you have several conditions to check, @code{.elseif} may be used to avoid
4426nesting blocks if/else within each subsequent @code{.else} block.
252b5132
RH
4427
4428The following variants of @code{.if} are also supported:
4429@table @code
4430@cindex @code{ifdef} directive
4431@item .ifdef @var{symbol}
4432Assembles the following section of code if the specified @var{symbol}
8dfa0188
NC
4433has been defined. Note a symbol which has been referenced but not yet defined
4434is considered to be undefined.
252b5132
RH
4435
4436@cindex @code{ifc} directive
4437@item .ifc @var{string1},@var{string2}
4438Assembles the following section of code if the two strings are the same. The
4439strings may be optionally quoted with single quotes. If they are not quoted,
4440the first string stops at the first comma, and the second string stops at the
4441end of the line. Strings which contain whitespace should be quoted. The
4442string comparison is case sensitive.
4443
4444@cindex @code{ifeq} directive
4445@item .ifeq @var{absolute expression}
4446Assembles the following section of code if the argument is zero.
4447
4448@cindex @code{ifeqs} directive
4449@item .ifeqs @var{string1},@var{string2}
4450Another form of @code{.ifc}. The strings must be quoted using double quotes.
4451
4452@cindex @code{ifge} directive
4453@item .ifge @var{absolute expression}
4454Assembles the following section of code if the argument is greater than or
4455equal to zero.
4456
4457@cindex @code{ifgt} directive
4458@item .ifgt @var{absolute expression}
4459Assembles the following section of code if the argument is greater than zero.
4460
4461@cindex @code{ifle} directive
4462@item .ifle @var{absolute expression}
4463Assembles the following section of code if the argument is less than or equal
4464to zero.
4465
4466@cindex @code{iflt} directive
4467@item .iflt @var{absolute expression}
4468Assembles the following section of code if the argument is less than zero.
4469
4470@cindex @code{ifnc} directive
4471@item .ifnc @var{string1},@var{string2}.
4472Like @code{.ifc}, but the sense of the test is reversed: this assembles the
4473following section of code if the two strings are not the same.
4474
4475@cindex @code{ifndef} directive
4476@cindex @code{ifnotdef} directive
4477@item .ifndef @var{symbol}
4478@itemx .ifnotdef @var{symbol}
4479Assembles the following section of code if the specified @var{symbol}
8dfa0188
NC
4480has not been defined. Both spelling variants are equivalent. Note a symbol
4481which has been referenced but not yet defined is considered to be undefined.
252b5132
RH
4482
4483@cindex @code{ifne} directive
4484@item .ifne @var{absolute expression}
4485Assembles the following section of code if the argument is not equal to zero
4486(in other words, this is equivalent to @code{.if}).
4487
4488@cindex @code{ifnes} directive
4489@item .ifnes @var{string1},@var{string2}
4490Like @code{.ifeqs}, but the sense of the test is reversed: this assembles the
4491following section of code if the two strings are not the same.
4492@end table
4493
7e005732
NC
4494@node Incbin
4495@section @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]}
4496
4497@cindex @code{incbin} directive
4498@cindex binary files, including
4499The @code{incbin} directive includes @var{file} verbatim at the current
4500location. You can control the search paths used with the @samp{-I} command-line
4501option (@pxref{Invoking,,Command-Line Options}). Quotation marks are required
4502around @var{file}.
4503
4504The @var{skip} argument skips a number of bytes from the start of the
4505@var{file}. The @var{count} argument indicates the maximum number of bytes to
15dcfbc3
NC
4506read. Note that the data is not aligned in any way, so it is the user's
4507responsibility to make sure that proper alignment is provided both before and
4508after the @code{incbin} directive.
7e005732 4509
252b5132
RH
4510@node Include
4511@section @code{.include "@var{file}"}
4512
4513@cindex @code{include} directive
4514@cindex supporting files, including
4515@cindex files, including
4516This directive provides a way to include supporting files at specified
4517points in your source program. The code from @var{file} is assembled as
4518if it followed the point of the @code{.include}; when the end of the
4519included file is reached, assembly of the original file continues. You
4520can control the search paths used with the @samp{-I} command-line option
4521(@pxref{Invoking,,Command-Line Options}). Quotation marks are required
4522around @var{file}.
4523
4524@node Int
4525@section @code{.int @var{expressions}}
4526
4527@cindex @code{int} directive
4528@cindex integers, 32-bit
4529Expect zero or more @var{expressions}, of any section, separated by commas.
4530For each expression, emit a number that, at run time, is the value of that
4531expression. The byte order and bit size of the number depends on what kind
4532of target the assembly is for.
4533
4534@ifclear GENERIC
4535@ifset H8
4536On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit
c2dcd04e 4537integers. On the H8/300H and the Renesas SH, however, @code{.int} emits
252b5132
RH
453832-bit integers.
4539@end ifset
4540@end ifclear
4541
c91d2e08
NC
4542@ifset ELF
4543@node Internal
4544@section @code{.internal @var{names}}
4545
c1253627
NC
4546@cindex @code{internal} directive
4547@cindex visibility
c91d2e08 4548This one of the ELF visibility directives. The other two are
a349d9dd
PB
4549@code{.hidden} (@pxref{Hidden,,@code{.hidden}}) and
4550@code{.protected} (@pxref{Protected,,@code{.protected}}).
c91d2e08
NC
4551
4552This directive overrides the named symbols default visibility (which is set by
4553their binding: local, global or weak). The directive sets the visibility to
4554@code{internal} which means that the symbols are considered to be @code{hidden}
c1253627 4555(i.e., not visible to other components), and that some extra, processor specific
c91d2e08
NC
4556processing must also be performed upon the symbols as well.
4557@end ifset
4558
252b5132
RH
4559@node Irp
4560@section @code{.irp @var{symbol},@var{values}}@dots{}
4561
4562@cindex @code{irp} directive
4563Evaluate a sequence of statements assigning different values to @var{symbol}.
4564The sequence of statements starts at the @code{.irp} directive, and is
4565terminated by an @code{.endr} directive. For each @var{value}, @var{symbol} is
4566set to @var{value}, and the sequence of statements is assembled. If no
4567@var{value} is listed, the sequence of statements is assembled once, with
4568@var{symbol} set to the null string. To refer to @var{symbol} within the
4569sequence of statements, use @var{\symbol}.
4570
4571For example, assembling
4572
4573@example
4574 .irp param,1,2,3
4575 move d\param,sp@@-
4576 .endr
4577@end example
4578
4579is equivalent to assembling
4580
4581@example
4582 move d1,sp@@-
4583 move d2,sp@@-
4584 move d3,sp@@-
4585@end example
4586
4587@node Irpc
4588@section @code{.irpc @var{symbol},@var{values}}@dots{}
4589
4590@cindex @code{irpc} directive
4591Evaluate a sequence of statements assigning different values to @var{symbol}.
4592The sequence of statements starts at the @code{.irpc} directive, and is
4593terminated by an @code{.endr} directive. For each character in @var{value},
4594@var{symbol} is set to the character, and the sequence of statements is
4595assembled. If no @var{value} is listed, the sequence of statements is
4596assembled once, with @var{symbol} set to the null string. To refer to
4597@var{symbol} within the sequence of statements, use @var{\symbol}.
4598
4599For example, assembling
4600
4601@example
4602 .irpc param,123
4603 move d\param,sp@@-
4604 .endr
4605@end example
4606
4607is equivalent to assembling
4608
4609@example
4610 move d1,sp@@-
4611 move d2,sp@@-
4612 move d3,sp@@-
4613@end example
4614
4615@node Lcomm
4616@section @code{.lcomm @var{symbol} , @var{length}}
4617
4618@cindex @code{lcomm} directive
4619@cindex local common symbols
4620@cindex symbols, local common
4621Reserve @var{length} (an absolute expression) bytes for a local common
4622denoted by @var{symbol}. The section and value of @var{symbol} are
4623those of the new local common. The addresses are allocated in the bss
4624section, so that at run-time the bytes start off zeroed. @var{Symbol}
4625is not declared global (@pxref{Global,,@code{.global}}), so is normally
4626not visible to @code{@value{LD}}.
4627
4628@ifset GENERIC
4629Some targets permit a third argument to be used with @code{.lcomm}. This
4630argument specifies the desired alignment of the symbol in the bss section.
4631@end ifset
4632
4633@ifset HPPA
4634The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
4635@samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
4636@end ifset
4637
4638@node Lflags
4639@section @code{.lflags}
4640
4641@cindex @code{lflags} directive (ignored)
a4fb0134 4642@command{@value{AS}} accepts this directive, for compatibility with other
252b5132
RH
4643assemblers, but ignores it.
4644
4645@ifclear no-line-dir
4646@node Line
4647@section @code{.line @var{line-number}}
4648
4649@cindex @code{line} directive
4650@end ifclear
4651@ifset no-line-dir
4652@node Ln
4653@section @code{.ln @var{line-number}}
4654
4655@cindex @code{ln} directive
4656@end ifset
4657@cindex logical line number
4658@ifset aout-bout
4659Change the logical line number. @var{line-number} must be an absolute
4660expression. The next line has that logical line number. Therefore any other
4661statements on the current line (after a statement separator character) are
4662reported as on logical line number @var{line-number} @minus{} 1. One day
a4fb0134 4663@command{@value{AS}} will no longer support this directive: it is recognized only
252b5132
RH
4664for compatibility with existing assembler programs.
4665
4666@ifset GENERIC
4667@ifset A29K
4668@emph{Warning:} In the AMD29K configuration of @value{AS}, this command is
4669not available; use the synonym @code{.ln} in that context.
4670@end ifset
4671@end ifset
4672@end ifset
4673
4674@ifclear no-line-dir
4675Even though this is a directive associated with the @code{a.out} or
a4fb0134 4676@code{b.out} object-code formats, @command{@value{AS}} still recognizes it
252b5132
RH
4677when producing COFF output, and treats @samp{.line} as though it
4678were the COFF @samp{.ln} @emph{if} it is found outside a
4679@code{.def}/@code{.endef} pair.
4680
4681Inside a @code{.def}, @samp{.line} is, instead, one of the directives
4682used by compilers to generate auxiliary symbol information for
4683debugging.
4684@end ifclear
4685
4686@node Linkonce
4687@section @code{.linkonce [@var{type}]}
4688@cindex COMDAT
4689@cindex @code{linkonce} directive
4690@cindex common sections
4691Mark the current section so that the linker only includes a single copy of it.
4692This may be used to include the same section in several different object files,
4693but ensure that the linker will only include it once in the final output file.
4694The @code{.linkonce} pseudo-op must be used for each instance of the section.
4695Duplicate sections are detected based on the section name, so it should be
4696unique.
4697
4698This directive is only supported by a few object file formats; as of this
4699writing, the only object file format which supports it is the Portable
4700Executable format used on Windows NT.
4701
4702The @var{type} argument is optional. If specified, it must be one of the
4703following strings. For example:
4704@smallexample
4705.linkonce same_size
4706@end smallexample
4707Not all types may be supported on all object file formats.
4708
4709@table @code
4710@item discard
4711Silently discard duplicate sections. This is the default.
4712
4713@item one_only
4714Warn if there are duplicate sections, but still keep only one copy.
4715
4716@item same_size
4717Warn if any of the duplicates have different sizes.
4718
4719@item same_contents
4720Warn if any of the duplicates do not have exactly the same contents.
4721@end table
4722
4723@node Ln
4724@section @code{.ln @var{line-number}}
4725
4726@cindex @code{ln} directive
4727@ifclear no-line-dir
4728@samp{.ln} is a synonym for @samp{.line}.
4729@end ifclear
4730@ifset no-line-dir
a4fb0134 4731Tell @command{@value{AS}} to change the logical line number. @var{line-number}
252b5132
RH
4732must be an absolute expression. The next line has that logical
4733line number, so any other statements on the current line (after a
4734statement separator character @code{;}) are reported as on logical
4735line number @var{line-number} @minus{} 1.
4736@ifset BOUT
4737
a4fb0134 4738This directive is accepted, but ignored, when @command{@value{AS}} is
252b5132
RH
4739configured for @code{b.out}; its effect is only associated with COFF
4740output format.
4741@end ifset
4742@end ifset
4743
4744@node MRI
4745@section @code{.mri @var{val}}
4746
4747@cindex @code{mri} directive
4748@cindex MRI mode, temporarily
a4fb0134
SC
4749If @var{val} is non-zero, this tells @command{@value{AS}} to enter MRI mode. If
4750@var{val} is zero, this tells @command{@value{AS}} to exit MRI mode. This change
252b5132
RH
4751affects code assembled until the next @code{.mri} directive, or until the end
4752of the file. @xref{M, MRI mode, MRI mode}.
4753
4754@node List
4755@section @code{.list}
4756
4757@cindex @code{list} directive
4758@cindex listing control, turning on
4759Control (in conjunction with the @code{.nolist} directive) whether or
4760not assembly listings are generated. These two directives maintain an
4761internal counter (which is zero initially). @code{.list} increments the
4762counter, and @code{.nolist} decrements it. Assembly listings are
4763generated whenever the counter is greater than zero.
4764
4765By default, listings are disabled. When you enable them (with the
4766@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}),
4767the initial value of the listing counter is one.
4768
4769@node Long
4770@section @code{.long @var{expressions}}
4771
4772@cindex @code{long} directive
4773@code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}.
4774
4775@ignore
4776@c no one seems to know what this is for or whether this description is
4777@c what it really ought to do
4778@node Lsym
4779@section @code{.lsym @var{symbol}, @var{expression}}
4780
4781@cindex @code{lsym} directive
4782@cindex symbol, not referenced in assembly
4783@code{.lsym} creates a new symbol named @var{symbol}, but does not put it in
4784the hash table, ensuring it cannot be referenced by name during the
4785rest of the assembly. This sets the attributes of the symbol to be
4786the same as the expression value:
4787@smallexample
4788@var{other} = @var{descriptor} = 0
4789@var{type} = @r{(section of @var{expression})}
4790@var{value} = @var{expression}
4791@end smallexample
4792@noindent
4793The new symbol is not flagged as external.
4794@end ignore
4795
4796@node Macro
4797@section @code{.macro}
4798
4799@cindex macros
4800The commands @code{.macro} and @code{.endm} allow you to define macros that
4801generate assembly output. For example, this definition specifies a macro
4802@code{sum} that puts a sequence of numbers into memory:
4803
4804@example
4805 .macro sum from=0, to=5
4806 .long \from
4807 .if \to-\from
4808 sum "(\from+1)",\to
4809 .endif
4810 .endm
4811@end example
4812
4813@noindent
4814With that definition, @samp{SUM 0,5} is equivalent to this assembly input:
4815
4816@example
4817 .long 0
4818 .long 1
4819 .long 2
4820 .long 3
4821 .long 4
4822 .long 5
4823@end example
4824
4825@ftable @code
4826@item .macro @var{macname}
4827@itemx .macro @var{macname} @var{macargs} @dots{}
4828@cindex @code{macro} directive
4829Begin the definition of a macro called @var{macname}. If your macro
4830definition requires arguments, specify their names after the macro name,
4831separated by commas or spaces. You can supply a default value for any
4832macro argument by following the name with @samp{=@var{deflt}}. For
4833example, these are all valid @code{.macro} statements:
4834
4835@table @code
4836@item .macro comm
4837Begin the definition of a macro called @code{comm}, which takes no
4838arguments.
4839
4840@item .macro plus1 p, p1
4841@itemx .macro plus1 p p1
4842Either statement begins the definition of a macro called @code{plus1},
4843which takes two arguments; within the macro definition, write
4844@samp{\p} or @samp{\p1} to evaluate the arguments.
4845
4846@item .macro reserve_str p1=0 p2
4847Begin the definition of a macro called @code{reserve_str}, with two
4848arguments. The first argument has a default value, but not the second.
4849After the definition is complete, you can call the macro either as
4850@samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to
4851@var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str
4852,@var{b}} (with @samp{\p1} evaluating as the default, in this case
4853@samp{0}, and @samp{\p2} evaluating to @var{b}).
4854@end table
4855
4856When you call a macro, you can specify the argument values either by
4857position, or by keyword. For example, @samp{sum 9,17} is equivalent to
4858@samp{sum to=17, from=9}.
4859
4860@item .endm
4861@cindex @code{endm} directive
4862Mark the end of a macro definition.
4863
4864@item .exitm
4865@cindex @code{exitm} directive
4866Exit early from the current macro definition.
4867
4868@cindex number of macros executed
4869@cindex macros, count executed
4870@item \@@
a4fb0134 4871@command{@value{AS}} maintains a counter of how many macros it has
252b5132
RH
4872executed in this pseudo-variable; you can copy that number to your
4873output with @samp{\@@}, but @emph{only within a macro definition}.
4874
4875@ignore
4876@item LOCAL @var{name} [ , @dots{} ]
4877@emph{Warning: @code{LOCAL} is only available if you select ``alternate
4878macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,,
4879Alternate macro syntax}.
4880
4881Generate a string replacement for each of the @var{name} arguments, and
4882replace any instances of @var{name} in each macro expansion. The
4883replacement string is unique in the assembly, and different for each
4884separate macro expansion. @code{LOCAL} allows you to write macros that
4885define symbols, without fear of conflict between separate macro expansions.
4886@end ignore
4887@end ftable
4888
4889@node Nolist
4890@section @code{.nolist}
4891
4892@cindex @code{nolist} directive
4893@cindex listing control, turning off
4894Control (in conjunction with the @code{.list} directive) whether or
4895not assembly listings are generated. These two directives maintain an
4896internal counter (which is zero initially). @code{.list} increments the
4897counter, and @code{.nolist} decrements it. Assembly listings are
4898generated whenever the counter is greater than zero.
4899
4900@node Octa
4901@section @code{.octa @var{bignums}}
4902
4903@c FIXME: double size emitted for "octa" on i960, others? Or warn?
4904@cindex @code{octa} directive
4905@cindex integer, 16-byte
4906@cindex sixteen byte integer
4907This directive expects zero or more bignums, separated by commas. For each
4908bignum, it emits a 16-byte integer.
4909
4910The term ``octa'' comes from contexts in which a ``word'' is two bytes;
4911hence @emph{octa}-word for 16 bytes.
4912
4913@node Org
4914@section @code{.org @var{new-lc} , @var{fill}}
4915
4916@cindex @code{org} directive
4917@cindex location counter, advancing
4918@cindex advancing location counter
4919@cindex current address, advancing
4920Advance the location counter of the current section to
4921@var{new-lc}. @var{new-lc} is either an absolute expression or an
4922expression with the same section as the current subsection. That is,
4923you can't use @code{.org} to cross sections: if @var{new-lc} has the
4924wrong section, the @code{.org} directive is ignored. To be compatible
4925with former assemblers, if the section of @var{new-lc} is absolute,
a4fb0134 4926@command{@value{AS}} issues a warning, then pretends the section of @var{new-lc}
252b5132
RH
4927is the same as the current subsection.
4928
4929@code{.org} may only increase the location counter, or leave it
4930unchanged; you cannot use @code{.org} to move the location counter
4931backwards.
4932
4933@c double negative used below "not undefined" because this is a specific
4934@c reference to "undefined" (as SEG_UNKNOWN is called in this manual)
4935@c section. doc@cygnus.com 18feb91
a4fb0134 4936Because @command{@value{AS}} tries to assemble programs in one pass, @var{new-lc}
252b5132
RH
4937may not be undefined. If you really detest this restriction we eagerly await
4938a chance to share your improved assembler.
4939
4940Beware that the origin is relative to the start of the section, not
4941to the start of the subsection. This is compatible with other
4942people's assemblers.
4943
4944When the location counter (of the current subsection) is advanced, the
4945intervening bytes are filled with @var{fill} which should be an
4946absolute expression. If the comma and @var{fill} are omitted,
4947@var{fill} defaults to zero.
4948
4949@node P2align
4950@section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}}
4951
4952@cindex padding the location counter given a power of two
4953@cindex @code{p2align} directive
4954Pad the location counter (in the current subsection) to a particular
4955storage boundary. The first expression (which must be absolute) is the
4956number of low-order zero bits the location counter must have after
4957advancement. For example @samp{.p2align 3} advances the location
4958counter until it a multiple of 8. If the location counter is already a
4959multiple of 8, no change is needed.
4960
4961The second expression (also absolute) gives the fill value to be stored in the
4962padding bytes. It (and the comma) may be omitted. If it is omitted, the
4963padding bytes are normally zero. However, on some systems, if the section is
4964marked as containing code and the fill value is omitted, the space is filled
4965with no-op instructions.
4966
4967The third expression is also absolute, and is also optional. If it is present,
4968it is the maximum number of bytes that should be skipped by this alignment
4969directive. If doing the alignment would require skipping more bytes than the
4970specified maximum, then the alignment is not done at all. You can omit the
4971fill value (the second argument) entirely by simply using two commas after the
4972required alignment; this can be useful if you want the alignment to be filled
4973with no-op instructions when appropriate.
4974
4975@cindex @code{p2alignw} directive
4976@cindex @code{p2alignl} directive
4977The @code{.p2alignw} and @code{.p2alignl} directives are variants of the
4978@code{.p2align} directive. The @code{.p2alignw} directive treats the fill
4979pattern as a two byte word value. The @code{.p2alignl} directives treats the
4980fill pattern as a four byte longword value. For example, @code{.p2alignw
49812,0x368d} will align to a multiple of 4. If it skips two bytes, they will be
4982filled in with the value 0x368d (the exact placement of the bytes depends upon
4983the endianness of the processor). If it skips 1 or 3 bytes, the fill value is
4984undefined.
4985
c91d2e08
NC
4986@ifset ELF
4987@node Previous
4988@section @code{.previous}
4989
c1253627 4990@cindex @code{previous} directive
c91d2e08
NC
4991@cindex Section Stack
4992This is one of the ELF section stack manipulation directives. The others are
a349d9dd
PB
4993@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}),
4994@code{.pushsection} (@pxref{PushSection}), and @code{.popsection}
4995(@pxref{PopSection}).
c91d2e08
NC
4996
4997This directive swaps the current section (and subsection) with most recently
4998referenced section (and subsection) prior to this one. Multiple
4999@code{.previous} directives in a row will flip between two sections (and their
5000subsections).
5001
5002In terms of the section stack, this directive swaps the current section with
5003the top section on the section stack.
5004@end ifset
5005
5006@ifset ELF
5007@node PopSection
5008@section @code{.popsection}
5009
c1253627 5010@cindex @code{popsection} directive
c91d2e08
NC
5011@cindex Section Stack
5012This is one of the ELF section stack manipulation directives. The others are
a349d9dd
PB
5013@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}),
5014@code{.pushsection} (@pxref{PushSection}), and @code{.previous}
5015(@pxref{Previous}).
c91d2e08
NC
5016
5017This directive replaces the current section (and subsection) with the top
5018section (and subsection) on the section stack. This section is popped off the
5019stack.
c91d2e08
NC
5020@end ifset
5021
252b5132
RH
5022@node Print
5023@section @code{.print @var{string}}
5024
5025@cindex @code{print} directive
a4fb0134 5026@command{@value{AS}} will print @var{string} on the standard output during
252b5132
RH
5027assembly. You must put @var{string} in double quotes.
5028
c91d2e08
NC
5029@ifset ELF
5030@node Protected
5031@section @code{.protected @var{names}}
5032
c1253627
NC
5033@cindex @code{protected} directive
5034@cindex visibility
c91d2e08 5035This one of the ELF visibility directives. The other two are
a349d9dd 5036@code{.hidden} (@pxref{Hidden}) and @code{.internal} (@pxref{Internal}).
c91d2e08
NC
5037
5038This directive overrides the named symbols default visibility (which is set by
5039their binding: local, global or weak). The directive sets the visibility to
5040@code{protected} which means that any references to the symbols from within the
5041components that defines them must be resolved to the definition in that
5042component, even if a definition in another component would normally preempt
5043this.
5044@end ifset
5045
252b5132
RH
5046@node Psize
5047@section @code{.psize @var{lines} , @var{columns}}
5048
5049@cindex @code{psize} directive
5050@cindex listing control: paper size
5051@cindex paper size, for listings
5052Use this directive to declare the number of lines---and, optionally, the
5053number of columns---to use for each page, when generating listings.
5054
5055If you do not use @code{.psize}, listings use a default line-count
5056of 60. You may omit the comma and @var{columns} specification; the
5057default width is 200 columns.
5058
a4fb0134 5059@command{@value{AS}} generates formfeeds whenever the specified number of
252b5132
RH
5060lines is exceeded (or whenever you explicitly request one, using
5061@code{.eject}).
5062
5063If you specify @var{lines} as @code{0}, no formfeeds are generated save
5064those explicitly specified with @code{.eject}.
5065
5066@node Purgem
5067@section @code{.purgem @var{name}}
5068
5069@cindex @code{purgem} directive
5070Undefine the macro @var{name}, so that later uses of the string will not be
5071expanded. @xref{Macro}.
5072
c91d2e08
NC
5073@ifset ELF
5074@node PushSection
5075@section @code{.pushsection @var{name} , @var{subsection}}
5076
c1253627 5077@cindex @code{pushsection} directive
c91d2e08
NC
5078@cindex Section Stack
5079This is one of the ELF section stack manipulation directives. The others are
a349d9dd
PB
5080@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}),
5081@code{.popsection} (@pxref{PopSection}), and @code{.previous}
5082(@pxref{Previous}).
c91d2e08 5083
a349d9dd 5084This directive is a synonym for @code{.section}. It pushes the current section
c91d2e08
NC
5085(and subsection) onto the top of the section stack, and then replaces the
5086current section and subsection with @code{name} and @code{subsection}.
c91d2e08
NC
5087@end ifset
5088
252b5132
RH
5089@node Quad
5090@section @code{.quad @var{bignums}}
5091
5092@cindex @code{quad} directive
5093@code{.quad} expects zero or more bignums, separated by commas. For
5094each bignum, it emits
5095@ifclear bignum-16
5096an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a
5097warning message; and just takes the lowest order 8 bytes of the bignum.
5098@cindex eight-byte integer
5099@cindex integer, 8-byte
5100
5101The term ``quad'' comes from contexts in which a ``word'' is two bytes;
5102hence @emph{quad}-word for 8 bytes.
5103@end ifclear
5104@ifset bignum-16
5105a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a
5106warning message; and just takes the lowest order 16 bytes of the bignum.
5107@cindex sixteen-byte integer
5108@cindex integer, 16-byte
5109@end ifset
5110
5111@node Rept
5112@section @code{.rept @var{count}}
5113
5114@cindex @code{rept} directive
5115Repeat the sequence of lines between the @code{.rept} directive and the next
5116@code{.endr} directive @var{count} times.
5117
5118For example, assembling
5119
5120@example
5121 .rept 3
5122 .long 0
5123 .endr
5124@end example
5125
5126is equivalent to assembling
5127
5128@example
5129 .long 0
5130 .long 0
5131 .long 0
5132@end example
5133
5134@node Sbttl
5135@section @code{.sbttl "@var{subheading}"}
5136
5137@cindex @code{sbttl} directive
5138@cindex subtitles for listings
5139@cindex listing control: subtitle
5140Use @var{subheading} as the title (third line, immediately after the
5141title line) when generating assembly listings.
5142
5143This directive affects subsequent pages, as well as the current page if
5144it appears within ten lines of the top of a page.
5145
5146@ifset COFF
5147@node Scl
5148@section @code{.scl @var{class}}
5149
5150@cindex @code{scl} directive
5151@cindex symbol storage class (COFF)
5152@cindex COFF symbol storage class
5153Set the storage-class value for a symbol. This directive may only be
5154used inside a @code{.def}/@code{.endef} pair. Storage class may flag
5155whether a symbol is static or external, or it may record further
5156symbolic debugging information.
5157@ifset BOUT
5158
5159The @samp{.scl} directive is primarily associated with COFF output; when
a4fb0134 5160configured to generate @code{b.out} output format, @command{@value{AS}}
252b5132
RH
5161accepts this directive but ignores it.
5162@end ifset
5163@end ifset
5164
c1253627 5165@ifset COFF-ELF
252b5132 5166@node Section
c1253627 5167@section @code{.section @var{name}}
252b5132 5168
252b5132
RH
5169@cindex named section
5170Use the @code{.section} directive to assemble the following code into a section
5171named @var{name}.
5172
5173This directive is only supported for targets that actually support arbitrarily
5174named sections; on @code{a.out} targets, for example, it is not accepted, even
5175with a standard @code{a.out} section name.
5176
c1253627
NC
5177@ifset COFF
5178@ifset ELF
5179@c only print the extra heading if both COFF and ELF are set
5180@subheading COFF Version
5181@end ifset
5182
5183@cindex @code{section} directive (COFF version)
252b5132
RH
5184For COFF targets, the @code{.section} directive is used in one of the following
5185ways:
c91d2e08 5186
252b5132
RH
5187@smallexample
5188.section @var{name}[, "@var{flags}"]
5189.section @var{name}[, @var{subsegment}]
5190@end smallexample
5191
5192If the optional argument is quoted, it is taken as flags to use for the
5193section. Each flag is a single character. The following flags are recognized:
5194@table @code
5195@item b
5196bss section (uninitialized data)
5197@item n
5198section is not loaded
5199@item w
5200writable section
5201@item d
5202data section
5203@item r
5204read-only section
5205@item x
5206executable section
2dcc60be
ILT
5207@item s
5208shared section (meaningful for PE targets)
6ff96af6
NC
5209@item a
5210ignored. (For compatibility with the ELF version)
252b5132
RH
5211@end table
5212
5213If no flags are specified, the default flags depend upon the section name. If
5214the section name is not recognized, the default will be for the section to be
7e84d676
NC
5215loaded and writable. Note the @code{n} and @code{w} flags remove attributes
5216from the section, rather than adding them, so if they are used on their own it
5217will be as if no flags had been specified at all.
252b5132
RH
5218
5219If the optional argument to the @code{.section} directive is not quoted, it is
5220taken as a subsegment number (@pxref{Sub-Sections}).
c1253627 5221@end ifset
252b5132
RH
5222
5223@ifset ELF
c1253627
NC
5224@ifset COFF
5225@c only print the extra heading if both COFF and ELF are set
5226@subheading ELF Version
5227@end ifset
5228
c91d2e08
NC
5229@cindex Section Stack
5230This is one of the ELF section stack manipulation directives. The others are
a349d9dd
PB
5231@code{.subsection} (@pxref{SubSection}), @code{.pushsection}
5232(@pxref{PushSection}), @code{.popsection} (@pxref{PopSection}), and
5233@code{.previous} (@pxref{Previous}).
c91d2e08 5234
c1253627 5235@cindex @code{section} directive (ELF version)
252b5132 5236For ELF targets, the @code{.section} directive is used like this:
c91d2e08 5237
252b5132 5238@smallexample
ec38dd05 5239.section @var{name} [, "@var{flags}"[, @@@var{type}[, @@@var{entsize}]]]
252b5132 5240@end smallexample
c91d2e08 5241
252b5132 5242The optional @var{flags} argument is a quoted string which may contain any
a349d9dd 5243combination of the following characters:
252b5132
RH
5244@table @code
5245@item a
5246section is allocatable
5247@item w
5248section is writable
5249@item x
5250section is executable
ec38dd05
JJ
5251@item M
5252section is mergeable
5253@item S
5254section contains zero terminated strings
252b5132
RH
5255@end table
5256
5257The optional @var{type} argument may contain one of the following constants:
5258@table @code
5259@item @@progbits
5260section contains data
5261@item @@nobits
5262section does not contain data (i.e., section only occupies space)
5263@end table
5264
ececec60
NC
5265Note on targets where the @code{@@} character is the start of a comment (eg
5266ARM) then another character is used instead. For example the ARM port uses the
5267@code{%} character.
5268
ec38dd05
JJ
5269If @var{flags} contains @code{M} flag, @var{type} argument must be specified
5270as well as @var{entsize} argument. Sections with @code{M} flag but not
5271@code{S} flag must contain fixed size constants, each @var{entsize} octets
5272long. Sections with both @code{M} and @code{S} must contain zero terminated
5273strings where each character is @var{entsize} bytes long. The linker may remove
5274duplicates within sections with the same name, same entity size and same flags.
5275
252b5132
RH
5276If no flags are specified, the default flags depend upon the section name. If
5277the section name is not recognized, the default will be for the section to have
5278none of the above flags: it will not be allocated in memory, nor writable, nor
5279executable. The section will contain data.
5280
5281For ELF targets, the assembler supports another type of @code{.section}
5282directive for compatibility with the Solaris assembler:
c91d2e08 5283
252b5132
RH
5284@smallexample
5285.section "@var{name}"[, @var{flags}...]
5286@end smallexample
c91d2e08 5287
252b5132
RH
5288Note that the section name is quoted. There may be a sequence of comma
5289separated flags:
5290@table @code
5291@item #alloc
5292section is allocatable
5293@item #write
5294section is writable
5295@item #execinstr
5296section is executable
5297@end table
c91d2e08
NC
5298
5299This directive replaces the current section and subsection. The replaced
5300section and subsection are pushed onto the section stack. See the contents of
5301the gas testsuite directory @code{gas/testsuite/gas/elf} for some examples of
5302how this directive and the other section stack directives work.
c1253627
NC
5303@end ifset
5304@end ifset
252b5132
RH
5305
5306@node Set
5307@section @code{.set @var{symbol}, @var{expression}}
5308
5309@cindex @code{set} directive
5310@cindex symbol value, setting
5311Set the value of @var{symbol} to @var{expression}. This
5312changes @var{symbol}'s value and type to conform to
5313@var{expression}. If @var{symbol} was flagged as external, it remains
5314flagged (@pxref{Symbol Attributes}).
5315
5316You may @code{.set} a symbol many times in the same assembly.
5317
5318If you @code{.set} a global symbol, the value stored in the object
5319file is the last value stored into it.
5320
5321@ifset HPPA
5322The syntax for @code{set} on the HPPA is
5323@samp{@var{symbol} .set @var{expression}}.
5324@end ifset
5325
5326@node Short
5327@section @code{.short @var{expressions}}
5328
5329@cindex @code{short} directive
5330@ifset GENERIC
5331@code{.short} is normally the same as @samp{.word}.
5332@xref{Word,,@code{.word}}.
5333
5334In some configurations, however, @code{.short} and @code{.word} generate
5335numbers of different lengths; @pxref{Machine Dependencies}.
5336@end ifset
5337@ifclear GENERIC
5338@ifset W16
5339@code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}.
5340@end ifset
5341@ifset W32
5342This expects zero or more @var{expressions}, and emits
5343a 16 bit number for each.
5344@end ifset
5345@end ifclear
5346
5347@node Single
5348@section @code{.single @var{flonums}}
5349
5350@cindex @code{single} directive
5351@cindex floating point numbers (single)
5352This directive assembles zero or more flonums, separated by commas. It
5353has the same effect as @code{.float}.
5354@ifset GENERIC
5355The exact kind of floating point numbers emitted depends on how
a4fb0134 5356@command{@value{AS}} is configured. @xref{Machine Dependencies}.
252b5132
RH
5357@end ifset
5358@ifclear GENERIC
5359@ifset IEEEFLOAT
5360On the @value{TARGET} family, @code{.single} emits 32-bit floating point
5361numbers in @sc{ieee} format.
5362@end ifset
5363@end ifclear
5364
c1253627 5365@ifset COFF-ELF
252b5132 5366@node Size
c1253627 5367@section @code{.size}
c91d2e08 5368
c1253627
NC
5369This directive is used to set the size associated with a symbol.
5370
5371@ifset COFF
5372@ifset ELF
5373@c only print the extra heading if both COFF and ELF are set
5374@subheading COFF Version
5375@end ifset
5376
5377@cindex @code{size} directive (COFF version)
5378For COFF targets, the @code{.size} directive is only permitted inside
5379@code{.def}/@code{.endef} pairs. It is used like this:
5380
5381@smallexample
5382.size @var{expression}
5383@end smallexample
252b5132 5384
c91d2e08 5385@ifset BOUT
252b5132 5386@samp{.size} is only meaningful when generating COFF format output; when
a4fb0134 5387@command{@value{AS}} is generating @code{b.out}, it accepts this directive but
252b5132
RH
5388ignores it.
5389@end ifset
c1253627 5390@end ifset
c91d2e08 5391
c1253627
NC
5392@ifset ELF
5393@ifset COFF
5394@c only print the extra heading if both COFF and ELF are set
5395@subheading ELF Version
5396@end ifset
5397
5398@cindex @code{size} directive (ELF version)
5399For ELF targets, the @code{.size} directive is used like this:
c91d2e08 5400
c1253627
NC
5401@smallexample
5402.size @var{name} , @var{expression}
5403@end smallexample
5404
5405This directive sets the size associated with a symbol @var{name}.
c91d2e08
NC
5406The size in bytes is computed from @var{expression} which can make use of label
5407arithmetic. This directive is typically used to set the size of function
5408symbols.
c1253627
NC
5409@end ifset
5410@end ifset
252b5132
RH
5411
5412@node Sleb128
5413@section @code{.sleb128 @var{expressions}}
5414
5415@cindex @code{sleb128} directive
5416@var{sleb128} stands for ``signed little endian base 128.'' This is a
5417compact, variable length representation of numbers used by the DWARF
5418symbolic debugging format. @xref{Uleb128,@code{.uleb128}}.
5419
5420@ifclear no-space-dir
5421@node Skip
5422@section @code{.skip @var{size} , @var{fill}}
5423
5424@cindex @code{skip} directive
5425@cindex filling memory
5426This directive emits @var{size} bytes, each of value @var{fill}. Both
5427@var{size} and @var{fill} are absolute expressions. If the comma and
5428@var{fill} are omitted, @var{fill} is assumed to be zero. This is the same as
5429@samp{.space}.
5430
5431@node Space
5432@section @code{.space @var{size} , @var{fill}}
5433
5434@cindex @code{space} directive
5435@cindex filling memory
5436This directive emits @var{size} bytes, each of value @var{fill}. Both
5437@var{size} and @var{fill} are absolute expressions. If the comma
5438and @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same
5439as @samp{.skip}.
5440
5441@ifset HPPA
5442@quotation
5443@emph{Warning:} @code{.space} has a completely different meaning for HPPA
5444targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800
5445Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the
5446@code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives},
5447for a summary.
5448@end quotation
5449@end ifset
5450@end ifclear
5451
5452@ifset A29K
5453@ifclear GENERIC
5454@node Space
5455@section @code{.space}
5456@cindex @code{space} directive
5457@end ifclear
5458On the AMD 29K, this directive is ignored; it is accepted for
5459compatibility with other AMD 29K assemblers.
5460
5461@quotation
5462@emph{Warning:} In most versions of the @sc{gnu} assembler, the directive
5463@code{.space} has the effect of @code{.block} @xref{Machine Dependencies}.
5464@end quotation
5465@end ifset
5466
5467@ifset have-stabs
5468@node Stab
5469@section @code{.stabd, .stabn, .stabs}
5470
5471@cindex symbolic debuggers, information for
5472@cindex @code{stab@var{x}} directives
5473There are three directives that begin @samp{.stab}.
5474All emit symbols (@pxref{Symbols}), for use by symbolic debuggers.
a4fb0134 5475The symbols are not entered in the @command{@value{AS}} hash table: they
252b5132
RH
5476cannot be referenced elsewhere in the source file.
5477Up to five fields are required:
5478
5479@table @var
5480@item string
5481This is the symbol's name. It may contain any character except
5482@samp{\000}, so is more general than ordinary symbol names. Some
5483debuggers used to code arbitrarily complex structures into symbol names
5484using this field.
5485
5486@item type
5487An absolute expression. The symbol's type is set to the low 8 bits of
5488this expression. Any bit pattern is permitted, but @code{@value{LD}}
5489and debuggers choke on silly bit patterns.
5490
5491@item other
5492An absolute expression. The symbol's ``other'' attribute is set to the
5493low 8 bits of this expression.
5494
5495@item desc
5496An absolute expression. The symbol's descriptor is set to the low 16
5497bits of this expression.
5498
5499@item value
5500An absolute expression which becomes the symbol's value.
5501@end table
5502
5503If a warning is detected while reading a @code{.stabd}, @code{.stabn},
5504or @code{.stabs} statement, the symbol has probably already been created;
5505you get a half-formed symbol in your object file. This is
5506compatible with earlier assemblers!
5507
5508@table @code
5509@cindex @code{stabd} directive
5510@item .stabd @var{type} , @var{other} , @var{desc}
5511
5512The ``name'' of the symbol generated is not even an empty string.
5513It is a null pointer, for compatibility. Older assemblers used a
5514null pointer so they didn't waste space in object files with empty
5515strings.
5516
5517The symbol's value is set to the location counter,
5518relocatably. When your program is linked, the value of this symbol
5519is the address of the location counter when the @code{.stabd} was
5520assembled.
5521
5522@cindex @code{stabn} directive
5523@item .stabn @var{type} , @var{other} , @var{desc} , @var{value}
5524The name of the symbol is set to the empty string @code{""}.
5525
5526@cindex @code{stabs} directive
5527@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value}
5528All five fields are specified.
5529@end table
5530@end ifset
5531@c end have-stabs
5532
5533@node String
5534@section @code{.string} "@var{str}"
5535
5536@cindex string, copying to object file
5537@cindex @code{string} directive
5538
5539Copy the characters in @var{str} to the object file. You may specify more than
5540one string to copy, separated by commas. Unless otherwise specified for a
5541particular machine, the assembler marks the end of each string with a 0 byte.
5542You can use any of the escape sequences described in @ref{Strings,,Strings}.
5543
5544@node Struct
5545@section @code{.struct @var{expression}}
5546
5547@cindex @code{struct} directive
5548Switch to the absolute section, and set the section offset to @var{expression},
5549which must be an absolute expression. You might use this as follows:
5550@smallexample
5551 .struct 0
5552field1:
5553 .struct field1 + 4
5554field2:
5555 .struct field2 + 4
5556field3:
5557@end smallexample
5558This would define the symbol @code{field1} to have the value 0, the symbol
5559@code{field2} to have the value 4, and the symbol @code{field3} to have the
5560value 8. Assembly would be left in the absolute section, and you would need to
5561use a @code{.section} directive of some sort to change to some other section
5562before further assembly.
5563
c91d2e08
NC
5564@ifset ELF
5565@node SubSection
5566@section @code{.subsection @var{name}}
5567
c1253627 5568@cindex @code{subsection} directive
c91d2e08
NC
5569@cindex Section Stack
5570This is one of the ELF section stack manipulation directives. The others are
a349d9dd
PB
5571@code{.section} (@pxref{Section}), @code{.pushsection} (@pxref{PushSection}),
5572@code{.popsection} (@pxref{PopSection}), and @code{.previous}
5573(@pxref{Previous}).
c91d2e08
NC
5574
5575This directive replaces the current subsection with @code{name}. The current
5576section is not changed. The replaced subsection is put onto the section stack
5577in place of the then current top of stack subsection.
c91d2e08
NC
5578@end ifset
5579
252b5132
RH
5580@ifset ELF
5581@node Symver
5582@section @code{.symver}
5583@cindex @code{symver} directive
5584@cindex symbol versioning
5585@cindex versions of symbols
5586Use the @code{.symver} directive to bind symbols to specific version nodes
5587within a source file. This is only supported on ELF platforms, and is
5588typically used when assembling files to be linked into a shared library.
5589There are cases where it may make sense to use this in objects to be bound
5590into an application itself so as to override a versioned symbol from a
5591shared library.
5592
79082ff0 5593For ELF targets, the @code{.symver} directive can be used like this:
252b5132
RH
5594@smallexample
5595.symver @var{name}, @var{name2@@nodename}
5596@end smallexample
339681c0 5597If the symbol @var{name} is defined within the file
79082ff0 5598being assembled, the @code{.symver} directive effectively creates a symbol
252b5132
RH
5599alias with the name @var{name2@@nodename}, and in fact the main reason that we
5600just don't try and create a regular alias is that the @var{@@} character isn't
5601permitted in symbol names. The @var{name2} part of the name is the actual name
5602of the symbol by which it will be externally referenced. The name @var{name}
5603itself is merely a name of convenience that is used so that it is possible to
5604have definitions for multiple versions of a function within a single source
5605file, and so that the compiler can unambiguously know which version of a
5606function is being mentioned. The @var{nodename} portion of the alias should be
5607the name of a node specified in the version script supplied to the linker when
5608building a shared library. If you are attempting to override a versioned
5609symbol from a shared library, then @var{nodename} should correspond to the
5610nodename of the symbol you are trying to override.
339681c0
L
5611
5612If the symbol @var{name} is not defined within the file being assembled, all
5613references to @var{name} will be changed to @var{name2@@nodename}. If no
5614reference to @var{name} is made, @var{name2@@nodename} will be removed from the
5615symbol table.
79082ff0
L
5616
5617Another usage of the @code{.symver} directive is:
5618@smallexample
5619.symver @var{name}, @var{name2@@@@nodename}
5620@end smallexample
5621In this case, the symbol @var{name} must exist and be defined within
a349d9dd 5622the file being assembled. It is similar to @var{name2@@nodename}. The
79082ff0
L
5623difference is @var{name2@@@@nodename} will also be used to resolve
5624references to @var{name2} by the linker.
5625
5626The third usage of the @code{.symver} directive is:
5627@smallexample
5628.symver @var{name}, @var{name2@@@@@@nodename}
5629@end smallexample
5630When @var{name} is not defined within the
5631file being assembled, it is treated as @var{name2@@nodename}. When
5632@var{name} is defined within the file being assembled, the symbol
5633name, @var{name}, will be changed to @var{name2@@@@nodename}.
252b5132
RH
5634@end ifset
5635
5636@ifset COFF
5637@node Tag
5638@section @code{.tag @var{structname}}
5639
5640@cindex COFF structure debugging
5641@cindex structure debugging, COFF
5642@cindex @code{tag} directive
5643This directive is generated by compilers to include auxiliary debugging
5644information in the symbol table. It is only permitted inside
5645@code{.def}/@code{.endef} pairs. Tags are used to link structure
5646definitions in the symbol table with instances of those structures.
5647@ifset BOUT
5648
5649@samp{.tag} is only used when generating COFF format output; when
a4fb0134 5650@command{@value{AS}} is generating @code{b.out}, it accepts this directive but
252b5132
RH
5651ignores it.
5652@end ifset
5653@end ifset
5654
5655@node Text
5656@section @code{.text @var{subsection}}
5657
5658@cindex @code{text} directive
a4fb0134 5659Tells @command{@value{AS}} to assemble the following statements onto the end of
252b5132
RH
5660the text subsection numbered @var{subsection}, which is an absolute
5661expression. If @var{subsection} is omitted, subsection number zero
5662is used.
5663
5664@node Title
5665@section @code{.title "@var{heading}"}
5666
5667@cindex @code{title} directive
5668@cindex listing control: title line
5669Use @var{heading} as the title (second line, immediately after the
5670source file name and pagenumber) when generating assembly listings.
5671
5672This directive affects subsequent pages, as well as the current page if
5673it appears within ten lines of the top of a page.
5674
c1253627 5675@ifset COFF-ELF
252b5132 5676@node Type
c1253627
NC
5677@section @code{.type}
5678
5679This directive is used to set the type of a symbol.
5680
5681@ifset COFF
5682@ifset ELF
5683@c only print the extra heading if both COFF and ELF are set
5684@subheading COFF Version
5685@end ifset
252b5132
RH
5686
5687@cindex COFF symbol type
5688@cindex symbol type, COFF
c1253627
NC
5689@cindex @code{type} directive (COFF version)
5690For COFF targets, this directive is permitted only within
5691@code{.def}/@code{.endef} pairs. It is used like this:
5692
5693@smallexample
5694.type @var{int}
5695@end smallexample
5696
5697This records the integer @var{int} as the type attribute of a symbol table
5698entry.
252b5132 5699
c91d2e08 5700@ifset BOUT
252b5132 5701@samp{.type} is associated only with COFF format output; when
a4fb0134 5702@command{@value{AS}} is configured for @code{b.out} output, it accepts this
252b5132
RH
5703directive but ignores it.
5704@end ifset
c1253627 5705@end ifset
c91d2e08 5706
c1253627
NC
5707@ifset ELF
5708@ifset COFF
5709@c only print the extra heading if both COFF and ELF are set
5710@subheading ELF Version
5711@end ifset
c91d2e08
NC
5712
5713@cindex ELF symbol type
5714@cindex symbol type, ELF
c1253627
NC
5715@cindex @code{type} directive (ELF version)
5716For ELF targets, the @code{.type} directive is used like this:
5717
5718@smallexample
5719.type @var{name} , @var{type description}
5720@end smallexample
5721
5722This sets the type of symbol @var{name} to be either a
a349d9dd 5723function symbol or an object symbol. There are five different syntaxes
c91d2e08 5724supported for the @var{type description} field, in order to provide
a349d9dd 5725compatibility with various other assemblers. The syntaxes supported are:
c91d2e08
NC
5726
5727@smallexample
5728 .type <name>,#function
5729 .type <name>,#object
5730
5731 .type <name>,@@function
5732 .type <name>,@@object
5733
5734 .type <name>,%function
5735 .type <name>,%object
5736
5737 .type <name>,"function"
5738 .type <name>,"object"
5739
5740 .type <name> STT_FUNCTION
5741 .type <name> STT_OBJECT
5742@end smallexample
c1253627
NC
5743@end ifset
5744@end ifset
c91d2e08
NC
5745
5746@node Uleb128
5747@section @code{.uleb128 @var{expressions}}
5748
5749@cindex @code{uleb128} directive
5750@var{uleb128} stands for ``unsigned little endian base 128.'' This is a
5751compact, variable length representation of numbers used by the DWARF
5752symbolic debugging format. @xref{Sleb128,@code{.sleb128}}.
252b5132
RH
5753
5754@ifset COFF
5755@node Val
5756@section @code{.val @var{addr}}
5757
5758@cindex @code{val} directive
5759@cindex COFF value attribute
5760@cindex value attribute, COFF
5761This directive, permitted only within @code{.def}/@code{.endef} pairs,
5762records the address @var{addr} as the value attribute of a symbol table
5763entry.
5764@ifset BOUT
5765
a4fb0134 5766@samp{.val} is used only for COFF output; when @command{@value{AS}} is
252b5132
RH
5767configured for @code{b.out}, it accepts this directive but ignores it.
5768@end ifset
5769@end ifset
5770
2e13b764 5771@ifset ELF
c91d2e08
NC
5772@node Version
5773@section @code{.version "@var{string}"}
2e13b764 5774
c1253627 5775@cindex @code{version} directive
c91d2e08
NC
5776This directive creates a @code{.note} section and places into it an ELF
5777formatted note of type NT_VERSION. The note's name is set to @code{string}.
9a297610 5778@end ifset
2e13b764 5779
c91d2e08
NC
5780@ifset ELF
5781@node VTableEntry
5782@section @code{.vtable_entry @var{table}, @var{offset}}
2e13b764 5783
c1253627 5784@cindex @code{vtable_entry}
c91d2e08
NC
5785This directive finds or creates a symbol @code{table} and creates a
5786@code{VTABLE_ENTRY} relocation for it with an addend of @code{offset}.
2e13b764 5787
c91d2e08
NC
5788@node VTableInherit
5789@section @code{.vtable_inherit @var{child}, @var{parent}}
2e13b764 5790
c1253627 5791@cindex @code{vtable_inherit}
c91d2e08
NC
5792This directive finds the symbol @code{child} and finds or creates the symbol
5793@code{parent} and then creates a @code{VTABLE_INHERIT} relocation for the
a349d9dd 5794parent whose addend is the value of the child symbol. As a special case the
c91d2e08
NC
5795parent name of @code{0} is treated as refering the @code{*ABS*} section.
5796@end ifset
2e13b764 5797
c91d2e08
NC
5798@ifset ELF
5799@node Weak
5800@section @code{.weak @var{names}}
2e13b764 5801
c1253627 5802@cindex @code{weak} directive
a349d9dd 5803This directive sets the weak attribute on the comma separated list of symbol
c91d2e08 5804@code{names}. If the symbols do not already exist, they will be created.
2e13b764
NC
5805@end ifset
5806
252b5132
RH
5807@node Word
5808@section @code{.word @var{expressions}}
5809
5810@cindex @code{word} directive
5811This directive expects zero or more @var{expressions}, of any section,
5812separated by commas.
5813@ifclear GENERIC
5814@ifset W32
a4fb0134 5815For each expression, @command{@value{AS}} emits a 32-bit number.
252b5132
RH
5816@end ifset
5817@ifset W16
a4fb0134 5818For each expression, @command{@value{AS}} emits a 16-bit number.
252b5132
RH
5819@end ifset
5820@end ifclear
5821@ifset GENERIC
5822
5823The size of the number emitted, and its byte order,
5824depend on what target computer the assembly is for.
5825@end ifset
5826
5827@c on amd29k, i960, sparc the "special treatment to support compilers" doesn't
5828@c happen---32-bit addressability, period; no long/short jumps.
5829@ifset DIFF-TBL-KLUGE
5830@cindex difference tables altered
5831@cindex altered difference tables
5832@quotation
5833@emph{Warning: Special Treatment to support Compilers}
5834@end quotation
5835
5836@ifset GENERIC
5837Machines with a 32-bit address space, but that do less than 32-bit
5838addressing, require the following special treatment. If the machine of
5839interest to you does 32-bit addressing (or doesn't require it;
5840@pxref{Machine Dependencies}), you can ignore this issue.
5841
5842@end ifset
5843In order to assemble compiler output into something that works,
a4fb0134 5844@command{@value{AS}} occasionally does strange things to @samp{.word} directives.
252b5132 5845Directives of the form @samp{.word sym1-sym2} are often emitted by
a4fb0134 5846compilers as part of jump tables. Therefore, when @command{@value{AS}} assembles a
252b5132 5847directive of the form @samp{.word sym1-sym2}, and the difference between
a4fb0134 5848@code{sym1} and @code{sym2} does not fit in 16 bits, @command{@value{AS}}
252b5132
RH
5849creates a @dfn{secondary jump table}, immediately before the next label.
5850This secondary jump table is preceded by a short-jump to the
5851first byte after the secondary table. This short-jump prevents the flow
5852of control from accidentally falling into the new table. Inside the
5853table is a long-jump to @code{sym2}. The original @samp{.word}
5854contains @code{sym1} minus the address of the long-jump to
5855@code{sym2}.
5856
5857If there were several occurrences of @samp{.word sym1-sym2} before the
5858secondary jump table, all of them are adjusted. If there was a
5859@samp{.word sym3-sym4}, that also did not fit in sixteen bits, a
5860long-jump to @code{sym4} is included in the secondary jump table,
5861and the @code{.word} directives are adjusted to contain @code{sym3}
5862minus the address of the long-jump to @code{sym4}; and so on, for as many
5863entries in the original jump table as necessary.
5864
5865@ifset INTERNALS
a4fb0134 5866@emph{This feature may be disabled by compiling @command{@value{AS}} with the
252b5132
RH
5867@samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse
5868assembly language programmers.
5869@end ifset
5870@end ifset
5871@c end DIFF-TBL-KLUGE
5872
5873@node Deprecated
5874@section Deprecated Directives
5875
5876@cindex deprecated directives
5877@cindex obsolescent directives
5878One day these directives won't work.
5879They are included for compatibility with older assemblers.
5880@table @t
5881@item .abort
5882@item .line
5883@end table
5884
5885@ifset GENERIC
5886@node Machine Dependencies
5887@chapter Machine Dependent Features
5888
5889@cindex machine dependencies
5890The machine instruction sets are (almost by definition) different on
a4fb0134
SC
5891each machine where @command{@value{AS}} runs. Floating point representations
5892vary as well, and @command{@value{AS}} often supports a few additional
252b5132
RH
5893directives or command-line options for compatibility with other
5894assemblers on a particular platform. Finally, some versions of
a4fb0134 5895@command{@value{AS}} support special pseudo-instructions for branch
252b5132
RH
5896optimization.
5897
5898This chapter discusses most of these differences, though it does not
5899include details on any machine's instruction set. For details on that
5900subject, see the hardware manufacturer's manual.
5901
5902@menu
5903@ifset A29K
5904* AMD29K-Dependent:: AMD 29K Dependent Features
5905@end ifset
625e1353
RH
5906@ifset ALPHA
5907* Alpha-Dependent:: Alpha Dependent Features
5908@end ifset
252b5132
RH
5909@ifset ARC
5910* ARC-Dependent:: ARC Dependent Features
5911@end ifset
5912@ifset ARM
5913* ARM-Dependent:: ARM Dependent Features
5914@end ifset
8bf549a8 5915@ifset CRIS
328eb32e
HPN
5916* CRIS-Dependent:: CRIS Dependent Features
5917@end ifset
252b5132
RH
5918@ifset D10V
5919* D10V-Dependent:: D10V Dependent Features
5920@end ifset
5921@ifset D30V
5922* D30V-Dependent:: D30V Dependent Features
5923@end ifset
5924@ifset H8/300
c2dcd04e 5925* H8/300-Dependent:: Renesas H8/300 Dependent Features
252b5132
RH
5926@end ifset
5927@ifset H8/500
c2dcd04e 5928* H8/500-Dependent:: Renesas H8/500 Dependent Features
252b5132
RH
5929@end ifset
5930@ifset HPPA
5931* HPPA-Dependent:: HPPA Dependent Features
5932@end ifset
5b93d8bb
AM
5933@ifset I370
5934* ESA/390-Dependent:: IBM ESA/390 Dependent Features
5935@end ifset
252b5132 5936@ifset I80386
55b62671 5937* i386-Dependent:: Intel 80386 and AMD x86-64 Dependent Features
252b5132 5938@end ifset
e3308d0d
JE
5939@ifset I860
5940* i860-Dependent:: Intel 80860 Dependent Features
5941@end ifset
252b5132
RH
5942@ifset I960
5943* i960-Dependent:: Intel 80960 Dependent Features
5944@end ifset
a40cbfa3
NC
5945@ifset IP2K
5946* IP2K-Dependent:: IP2K Dependent Features
5947@end ifset
ec694b89
NC
5948@ifset M32R
5949* M32R-Dependent:: M32R Dependent Features
5950@end ifset
252b5132
RH
5951@ifset M680X0
5952* M68K-Dependent:: M680x0 Dependent Features
5953@end ifset
60bcf0fa
NC
5954@ifset M68HC11
5955* M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features
5956@end ifset
81b0b3f1
BE
5957@ifset M880X0
5958* M88K-Dependent:: M880x0 Dependent Features
5959@end ifset
252b5132
RH
5960@ifset MIPS
5961* MIPS-Dependent:: MIPS Dependent Features
5962@end ifset
3c3bdf30
NC
5963@ifset MMIX
5964* MMIX-Dependent:: MMIX Dependent Features
5965@end ifset
2469cfa2
NC
5966@ifset MSP430
5967* MSP430-Dependent:: MSP430 Dependent Features
5968@end ifset
252b5132 5969@ifset SH
ef230218
JR
5970* SH-Dependent:: Renesas / SuperH SH Dependent Features
5971* SH64-Dependent:: SuperH SH64 Dependent Features
252b5132 5972@end ifset
e135f41b
NC
5973@ifset PDP11
5974* PDP-11-Dependent:: PDP-11 Dependent Features
5975@end ifset
041dd5a9
ILT
5976@ifset PJ
5977* PJ-Dependent:: picoJava Dependent Features
5978@end ifset
418c1742
MG
5979@ifset PPC
5980* PPC-Dependent:: PowerPC Dependent Features
5981@end ifset
252b5132
RH
5982@ifset SPARC
5983* Sparc-Dependent:: SPARC Dependent Features
5984@end ifset
39bec121
TW
5985@ifset TIC54X
5986* TIC54X-Dependent:: TI TMS320C54x Dependent Features
5987@end ifset
252b5132
RH
5988@ifset V850
5989* V850-Dependent:: V850 Dependent Features
5990@end ifset
e0001a05
NC
5991@ifset XTENSA
5992* Xtensa-Dependent:: Xtensa Dependent Features
5993@end ifset
252b5132
RH
5994@ifset Z8000
5995* Z8000-Dependent:: Z8000 Dependent Features
5996@end ifset
5997@ifset VAX
5998* Vax-Dependent:: VAX Dependent Features
5999@end ifset
6000@end menu
6001
6002@lowersections
6003@end ifset
6004
6005@c The following major nodes are *sections* in the GENERIC version, *chapters*
6006@c in single-cpu versions. This is mainly achieved by @lowersections. There is a
6007@c peculiarity: to preserve cross-references, there must be a node called
6008@c "Machine Dependencies". Hence the conditional nodenames in each
6009@c major node below. Node defaulting in makeinfo requires adjacency of
6010@c node and sectioning commands; hence the repetition of @chapter BLAH
6011@c in both conditional blocks.
6012
252b5132
RH
6013@ifset A29K
6014@include c-a29k.texi
6015@end ifset
6016
625e1353
RH
6017@ifset ALPHA
6018@include c-alpha.texi
6019@end ifset
6020
6021@ifset ARC
6022@include c-arc.texi
6023@end ifset
6024
252b5132
RH
6025@ifset ARM
6026@include c-arm.texi
6027@end ifset
6028
328eb32e
HPN
6029@ifset CRIS
6030@include c-cris.texi
6031@end ifset
6032
c2dcd04e 6033@ifset Renesas-all
252b5132
RH
6034@ifclear GENERIC
6035@node Machine Dependencies
6036@chapter Machine Dependent Features
6037
c2dcd04e 6038The machine instruction sets are different on each Renesas chip family,
252b5132 6039and there are also some syntax differences among the families. This
a4fb0134 6040chapter describes the specific @command{@value{AS}} features for each
252b5132
RH
6041family.
6042
6043@menu
c2dcd04e
NC
6044* H8/300-Dependent:: Renesas H8/300 Dependent Features
6045* H8/500-Dependent:: Renesas H8/500 Dependent Features
6046* SH-Dependent:: Renesas SH Dependent Features
252b5132
RH
6047@end menu
6048@lowersections
6049@end ifclear
6050@end ifset
6051
6052@ifset D10V
6053@include c-d10v.texi
6054@end ifset
6055
6056@ifset D30V
6057@include c-d30v.texi
6058@end ifset
6059
6060@ifset H8/300
6061@include c-h8300.texi
6062@end ifset
6063
6064@ifset H8/500
6065@include c-h8500.texi
6066@end ifset
6067
6068@ifset HPPA
6069@include c-hppa.texi
6070@end ifset
6071
5b93d8bb
AM
6072@ifset I370
6073@include c-i370.texi
6074@end ifset
6075
252b5132
RH
6076@ifset I80386
6077@include c-i386.texi
6078@end ifset
6079
e3308d0d
JE
6080@ifset I860
6081@include c-i860.texi
6082@end ifset
6083
252b5132
RH
6084@ifset I960
6085@include c-i960.texi
6086@end ifset
6087
9e32ca89
NC
6088@ifset IA64
6089@include c-ia64.texi
6090@end ifset
6091
a40cbfa3
NC
6092@ifset IP2K
6093@include c-ip2k.texi
6094@end ifset
6095
ec694b89
NC
6096@ifset M32R
6097@include c-m32r.texi
6098@end ifset
252b5132
RH
6099
6100@ifset M680X0
6101@include c-m68k.texi
6102@end ifset
6103
60bcf0fa
NC
6104@ifset M68HC11
6105@include c-m68hc11.texi
6106@end ifset
6107
81b0b3f1
BE
6108@ifset M880X0
6109@include c-m88k.texi
6110@end ifset
6111
252b5132
RH
6112@ifset MIPS
6113@include c-mips.texi
6114@end ifset
6115
3c3bdf30
NC
6116@ifset MMIX
6117@include c-mmix.texi
6118@end ifset
6119
2469cfa2
NC
6120@ifset MSP430
6121@include c-msp430.texi
6122@end ifset
6123
252b5132
RH
6124@ifset NS32K
6125@include c-ns32k.texi
6126@end ifset
6127
e135f41b
NC
6128@ifset PDP11
6129@include c-pdp11.texi
6130@end ifset
6131
041dd5a9
ILT
6132@ifset PJ
6133@include c-pj.texi
6134@end ifset
6135
418c1742
MG
6136@ifset PPC
6137@include c-ppc.texi
6138@end ifset
6139
252b5132
RH
6140@ifset SH
6141@include c-sh.texi
324bfcf3 6142@include c-sh64.texi
252b5132
RH
6143@end ifset
6144
6145@ifset SPARC
6146@include c-sparc.texi
6147@end ifset
6148
39bec121
TW
6149@ifset TIC54X
6150@include c-tic54x.texi
6151@end ifset
6152
252b5132
RH
6153@ifset Z8000
6154@include c-z8k.texi
6155@end ifset
6156
6157@ifset VAX
6158@include c-vax.texi
6159@end ifset
6160
6161@ifset V850
6162@include c-v850.texi
6163@end ifset
6164
e0001a05
NC
6165@ifset XTENSA
6166@include c-xtensa.texi
6167@end ifset
6168
252b5132
RH
6169@ifset GENERIC
6170@c reverse effect of @down at top of generic Machine-Dep chapter
6171@raisesections
6172@end ifset
6173
6174@node Reporting Bugs
6175@chapter Reporting Bugs
6176@cindex bugs in assembler
6177@cindex reporting bugs in assembler
6178
a4fb0134 6179Your bug reports play an essential role in making @command{@value{AS}} reliable.
252b5132
RH
6180
6181Reporting a bug may help you by bringing a solution to your problem, or it may
6182not. But in any case the principal function of a bug report is to help the
a4fb0134
SC
6183entire community by making the next version of @command{@value{AS}} work better.
6184Bug reports are your contribution to the maintenance of @command{@value{AS}}.
252b5132
RH
6185
6186In order for a bug report to serve its purpose, you must include the
6187information that enables us to fix the bug.
6188
6189@menu
6190* Bug Criteria:: Have you found a bug?
6191* Bug Reporting:: How to report bugs
6192@end menu
6193
6194@node Bug Criteria
c1253627 6195@section Have You Found a Bug?
252b5132
RH
6196@cindex bug criteria
6197
6198If you are not sure whether you have found a bug, here are some guidelines:
6199
6200@itemize @bullet
6201@cindex fatal signal
6202@cindex assembler crash
6203@cindex crash of assembler
6204@item
6205If the assembler gets a fatal signal, for any input whatever, that is a
a4fb0134 6206@command{@value{AS}} bug. Reliable assemblers never crash.
252b5132
RH
6207
6208@cindex error on valid input
6209@item
a4fb0134 6210If @command{@value{AS}} produces an error message for valid input, that is a bug.
252b5132
RH
6211
6212@cindex invalid input
6213@item
a4fb0134 6214If @command{@value{AS}} does not produce an error message for invalid input, that
252b5132
RH
6215is a bug. However, you should note that your idea of ``invalid input'' might
6216be our idea of ``an extension'' or ``support for traditional practice''.
6217
6218@item
6219If you are an experienced user of assemblers, your suggestions for improvement
a4fb0134 6220of @command{@value{AS}} are welcome in any case.
252b5132
RH
6221@end itemize
6222
6223@node Bug Reporting
c1253627 6224@section How to Report Bugs
252b5132
RH
6225@cindex bug reports
6226@cindex assembler bugs, reporting
6227
6228A number of companies and individuals offer support for @sc{gnu} products. If
a4fb0134 6229you obtained @command{@value{AS}} from a support organization, we recommend you
252b5132
RH
6230contact that organization first.
6231
6232You can find contact information for many support companies and
6233individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
6234distribution.
6235
a4fb0134 6236In any event, we also recommend that you send bug reports for @command{@value{AS}}
46a04e3a 6237to @samp{bug-binutils@@gnu.org}.
252b5132
RH
6238
6239The fundamental principle of reporting bugs usefully is this:
6240@strong{report all the facts}. If you are not sure whether to state a
6241fact or leave it out, state it!
6242
6243Often people omit facts because they think they know what causes the problem
6244and assume that some details do not matter. Thus, you might assume that the
6245name of a symbol you use in an example does not matter. Well, probably it does
6246not, but one cannot be sure. Perhaps the bug is a stray memory reference which
6247happens to fetch from the location where that name is stored in memory;
6248perhaps, if the name were different, the contents of that location would fool
6249the assembler into doing the right thing despite the bug. Play it safe and
6250give a specific, complete example. That is the easiest thing for you to do,
6251and the most helpful.
6252
6253Keep in mind that the purpose of a bug report is to enable us to fix the bug if
6254it is new to us. Therefore, always write your bug reports on the assumption
6255that the bug has not been reported previously.
6256
6257Sometimes people give a few sketchy facts and ask, ``Does this ring a
c1253627
NC
6258bell?'' This cannot help us fix a bug, so it is basically useless. We
6259respond by asking for enough details to enable us to investigate.
6260You might as well expedite matters by sending them to begin with.
252b5132
RH
6261
6262To enable us to fix the bug, you should include all these things:
6263
6264@itemize @bullet
6265@item
a4fb0134 6266The version of @command{@value{AS}}. @command{@value{AS}} announces it if you start
252b5132
RH
6267it with the @samp{--version} argument.
6268
6269Without this, we will not know whether there is any point in looking for
a4fb0134 6270the bug in the current version of @command{@value{AS}}.
252b5132
RH
6271
6272@item
a4fb0134 6273Any patches you may have applied to the @command{@value{AS}} source.
252b5132
RH
6274
6275@item
6276The type of machine you are using, and the operating system name and
6277version number.
6278
6279@item
a4fb0134 6280What compiler (and its version) was used to compile @command{@value{AS}}---e.g.
252b5132
RH
6281``@code{gcc-2.7}''.
6282
6283@item
6284The command arguments you gave the assembler to assemble your example and
6285observe the bug. To guarantee you will not omit something important, list them
6286all. A copy of the Makefile (or the output from make) is sufficient.
6287
6288If we were to try to guess the arguments, we would probably guess wrong
6289and then we might not encounter the bug.
6290
6291@item
6292A complete input file that will reproduce the bug. If the bug is observed when
6293the assembler is invoked via a compiler, send the assembler source, not the
6294high level language source. Most compilers will produce the assembler source
6295when run with the @samp{-S} option. If you are using @code{@value{GCC}}, use
6296the options @samp{-v --save-temps}; this will save the assembler source in a
6297file with an extension of @file{.s}, and also show you exactly how
a4fb0134 6298@command{@value{AS}} is being run.
252b5132
RH
6299
6300@item
6301A description of what behavior you observe that you believe is
6302incorrect. For example, ``It gets a fatal signal.''
6303
a4fb0134 6304Of course, if the bug is that @command{@value{AS}} gets a fatal signal, then we
252b5132
RH
6305will certainly notice it. But if the bug is incorrect output, we might not
6306notice unless it is glaringly wrong. You might as well not give us a chance to
6307make a mistake.
6308
6309Even if the problem you experience is a fatal signal, you should still say so
6310explicitly. Suppose something strange is going on, such as, your copy of
a4fb0134 6311@command{@value{AS}} is out of synch, or you have encountered a bug in the C
252b5132
RH
6312library on your system. (This has happened!) Your copy might crash and ours
6313would not. If you told us to expect a crash, then when ours fails to crash, we
6314would know that the bug was not happening for us. If you had not told us to
6315expect a crash, then we would not be able to draw any conclusion from our
6316observations.
6317
6318@item
a4fb0134 6319If you wish to suggest changes to the @command{@value{AS}} source, send us context
252b5132
RH
6320diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
6321option. Always send diffs from the old file to the new file. If you even
a4fb0134 6322discuss something in the @command{@value{AS}} source, refer to it by context, not
252b5132
RH
6323by line number.
6324
6325The line numbers in our development sources will not match those in your
6326sources. Your line numbers would convey no useful information to us.
6327@end itemize
6328
6329Here are some things that are not necessary:
6330
6331@itemize @bullet
6332@item
6333A description of the envelope of the bug.
6334
6335Often people who encounter a bug spend a lot of time investigating
6336which changes to the input file will make the bug go away and which
6337changes will not affect it.
6338
6339This is often time consuming and not very useful, because the way we
6340will find the bug is by running a single example under the debugger
6341with breakpoints, not by pure deduction from a series of examples.
6342We recommend that you save your time for something else.
6343
6344Of course, if you can find a simpler example to report @emph{instead}
6345of the original one, that is a convenience for us. Errors in the
6346output will be easier to spot, running under the debugger will take
6347less time, and so on.
6348
6349However, simplification is not vital; if you do not want to do this,
6350report the bug anyway and send us the entire test case you used.
6351
6352@item
6353A patch for the bug.
6354
6355A patch for the bug does help us if it is a good one. But do not omit
6356the necessary information, such as the test case, on the assumption that
6357a patch is all we need. We might see problems with your patch and decide
6358to fix the problem another way, or we might not understand it at all.
6359
a4fb0134 6360Sometimes with a program as complicated as @command{@value{AS}} it is very hard to
252b5132
RH
6361construct an example that will make the program follow a certain path through
6362the code. If you do not send us the example, we will not be able to construct
6363one, so we will not be able to verify that the bug is fixed.
6364
6365And if we cannot understand what bug you are trying to fix, or why your
6366patch should be an improvement, we will not install it. A test case will
6367help us to understand.
6368
6369@item
6370A guess about what the bug is or what it depends on.
6371
6372Such guesses are usually wrong. Even we cannot guess right about such
6373things without first using the debugger to find the facts.
6374@end itemize
6375
6376@node Acknowledgements
6377@chapter Acknowledgements
6378
a4fb0134 6379If you have contributed to @command{@value{AS}} and your name isn't listed here,
252b5132
RH
6380it is not meant as a slight. We just don't know about it. Send mail to the
6381maintainer, and we'll correct the situation. Currently
6382@c (January 1994),
6383the maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}).
6384
6385Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any
6386more details?}
6387
6388Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug
6389information and the 68k series machines, most of the preprocessing pass, and
6390extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}.
6391
6392K. Richard Pixley maintained GAS for a while, adding various enhancements and
6393many bug fixes, including merging support for several processors, breaking GAS
6394up to handle multiple object file format back ends (including heavy rewrite,
6395testing, an integration of the coff and b.out back ends), adding configuration
6396including heavy testing and verification of cross assemblers and file splits
6397and renaming, converted GAS to strictly ANSI C including full prototypes, added
6398support for m680[34]0 and cpu32, did considerable work on i960 including a COFF
6399port (including considerable amounts of reverse engineering), a SPARC opcode
6400file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know''
6401assertions and made them work, much other reorganization, cleanup, and lint.
6402
6403Ken Raeburn wrote the high-level BFD interface code to replace most of the code
6404in format-specific I/O modules.
6405
6406The original VMS support was contributed by David L. Kashtan. Eric Youngdale
6407has done much work with it since.
6408
6409The Intel 80386 machine description was written by Eliot Dresselhaus.
6410
6411Minh Tran-Le at IntelliCorp contributed some AIX 386 support.
6412
6413The Motorola 88k machine description was contributed by Devon Bowen of Buffalo
6414University and Torbjorn Granlund of the Swedish Institute of Computer Science.
6415
6416Keith Knowles at the Open Software Foundation wrote the original MIPS back end
6417(@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support
6418(which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to
6419support a.out format.
6420
c2dcd04e 6421Support for the Zilog Z8k and Renesas H8/300 and H8/500 processors (tc-z8k,
252b5132
RH
6422tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by
6423Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to
6424use BFD for some low-level operations, for use with the H8/300 and AMD 29k
6425targets.
6426
6427John Gilmore built the AMD 29000 support, added @code{.include} support, and
6428simplified the configuration of which versions accept which directives. He
6429updated the 68k machine description so that Motorola's opcodes always produced
c1253627 6430fixed-size instructions (e.g., @code{jsr}), while synthetic instructions
252b5132
RH
6431remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested
6432cross-compilation support, and one bug in relaxation that took a week and
6433required the proverbial one-bit fix.
6434
6435Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the
643668k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix),
6437added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and
6438PowerPC assembler, and made a few other minor patches.
6439
a4fb0134 6440Steve Chamberlain made @command{@value{AS}} able to generate listings.
252b5132
RH
6441
6442Hewlett-Packard contributed support for the HP9000/300.
6443
6444Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM)
6445along with a fairly extensive HPPA testsuite (for both SOM and ELF object
6446formats). This work was supported by both the Center for Software Science at
6447the University of Utah and Cygnus Support.
6448
6449Support for ELF format files has been worked on by Mark Eichin of Cygnus
6450Support (original, incomplete implementation for SPARC), Pete Hoogenboom and
6451Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open
6452Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc,
6453and some initial 64-bit support).
6454
c1253627 6455Linas Vepstas added GAS support for the ESA/390 ``IBM 370'' architecture.
5b93d8bb 6456
252b5132
RH
6457Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD
6458support for openVMS/Alpha.
6459
39bec121
TW
6460Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic*
6461flavors.
6462
e0001a05
NC
6463David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica,
6464Inc. added support for Xtensa processors.
6465
252b5132
RH
6466Several engineers at Cygnus Support have also provided many small bug fixes and
6467configuration enhancements.
6468
6469Many others have contributed large or small bugfixes and enhancements. If
6470you have contributed significant work and are not mentioned on this list, and
6471want to be, let us know. Some of the history has been lost; we are not
6472intentionally leaving anyone out.
6473
c1253627 6474@include fdl.texi
cf055d54 6475
252b5132
RH
6476@node Index
6477@unnumbered Index
6478
6479@printindex cp
6480
6481@contents
6482@bye
6483@c Local Variables:
6484@c fill-column: 79
6485@c End:
This page took 0.530127 seconds and 4 git commands to generate.