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