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