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