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