as.texinfo revision 33965
1\input texinfo @c -*-Texinfo-*- 2@c Copyright (c) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc. 3@c UPDATE!! On future updates-- 4@c (1) check for new machine-dep cmdline options in 5@c md_parse_option definitions in config/tc-*.c 6@c (2) for platform-specific directives, examine md_pseudo_op 7@c in config/tc-*.c 8@c (3) for object-format specific directives, examine obj_pseudo_op 9@c in config/obj-*.c 10@c (4) portable directives in potable[] in read.c 11@c %**start of header 12@setfilename as.info 13@c ---config--- 14@c defaults, config file may override: 15@set have-stabs 16@c --- 17@include asconfig.texi 18@c --- 19@c common OR combinations of conditions 20@ifset AOUT 21@set aout-bout 22@end ifset 23@ifset BOUT 24@set aout-bout 25@end ifset 26@ifset H8/300 27@set H8 28@end ifset 29@ifset H8/500 30@set H8 31@end ifset 32@ifset SH 33@set H8 34@end ifset 35@ifset HPPA 36@set abnormal-separator 37@end ifset 38@c ------------ 39@ifset GENERIC 40@settitle Using @value{AS} 41@end ifset 42@ifclear GENERIC 43@settitle Using @value{AS} (@value{TARGET}) 44@end ifclear 45@setchapternewpage odd 46@c %**end of header 47 48@c @smallbook 49@c @set SMALL 50@c WARE! Some of the machine-dependent sections contain tables of machine 51@c instructions. Except in multi-column format, these tables look silly. 52@c Unfortunately, Texinfo doesn't have a general-purpose multi-col format, so 53@c the multi-col format is faked within @example sections. 54@c 55@c Again unfortunately, the natural size that fits on a page, for these tables, 56@c is different depending on whether or not smallbook is turned on. 57@c This matters, because of order: text flow switches columns at each page 58@c break. 59@c 60@c The format faked in this source works reasonably well for smallbook, 61@c not well for the default large-page format. This manual expects that if you 62@c turn on @smallbook, you will also uncomment the "@set SMALL" to enable the 63@c tables in question. You can turn on one without the other at your 64@c discretion, of course. 65@ifinfo 66@set SMALL 67@c the insn tables look just as silly in info files regardless of smallbook, 68@c might as well show 'em anyways. 69@end ifinfo 70 71@ifinfo 72@format 73START-INFO-DIR-ENTRY 74* As: (as). The GNU assembler. 75END-INFO-DIR-ENTRY 76@end format 77@end ifinfo 78 79@finalout 80@syncodeindex ky cp 81 82@ifinfo 83This file documents the GNU Assembler "@value{AS}". 84 85Copyright (C) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc. 86 87Permission is granted to make and distribute verbatim copies of 88this manual provided the copyright notice and this permission notice 89are preserved on all copies. 90 91@ignore 92Permission is granted to process this file through Tex and print the 93results, provided the printed document carries copying permission 94notice identical to this one except for the removal of this paragraph 95(this paragraph not being relevant to the printed manual). 96 97@end ignore 98Permission is granted to copy and distribute modified versions of this manual 99under the conditions for verbatim copying, provided that the entire resulting 100derived work is distributed under the terms of a permission notice identical to 101this one. 102 103Permission is granted to copy and distribute translations of this manual 104into another language, under the above conditions for modified versions. 105@end ifinfo 106 107@titlepage 108@title Using @value{AS} 109@subtitle The @sc{gnu} Assembler 110@ifclear GENERIC 111@subtitle for the @value{TARGET} family 112@end ifclear 113@sp 1 114@subtitle January 1994 115@sp 1 116@sp 13 117The Free Software Foundation Inc. thanks The Nice Computer 118Company of Australia for loaning Dean Elsner to write the 119first (Vax) version of @code{as} for Project @sc{gnu}. 120The proprietors, management and staff of TNCCA thank FSF for 121distracting the boss while they got some work 122done. 123@sp 3 124@author Dean Elsner, Jay Fenlason & friends 125@page 126@tex 127{\parskip=0pt 128\hfill {\it Using {\tt @value{AS}}}\par 129\hfill Edited by Cygnus Support\par 130} 131%"boxit" macro for figures: 132%Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3) 133\gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt 134 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil 135#2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline 136\gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box 137@end tex 138 139@vskip 0pt plus 1filll 140Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc. 141 142Permission is granted to make and distribute verbatim copies of 143this manual provided the copyright notice and this permission notice 144are preserved on all copies. 145 146Permission is granted to copy and distribute modified versions of this manual 147under the conditions for verbatim copying, provided that the entire resulting 148derived work is distributed under the terms of a permission notice identical to 149this one. 150 151Permission is granted to copy and distribute translations of this manual 152into another language, under the above conditions for modified versions. 153@end titlepage 154 155@ifinfo 156@node Top 157@top Using @value{AS} 158 159This file is a user guide to the @sc{gnu} assembler @code{@value{AS}}. 160@ifclear GENERIC 161This version of the file describes @code{@value{AS}} configured to generate 162code for @value{TARGET} architectures. 163@end ifclear 164@menu 165* Overview:: Overview 166* Invoking:: Command-Line Options 167* Syntax:: Syntax 168* Sections:: Sections and Relocation 169* Symbols:: Symbols 170* Expressions:: Expressions 171* Pseudo Ops:: Assembler Directives 172* Machine Dependencies:: Machine Dependent Features 173* Reporting Bugs:: Reporting Bugs 174* Acknowledgements:: Who Did What 175* Index:: Index 176@end menu 177@end ifinfo 178 179@node Overview 180@chapter Overview 181@iftex 182This manual is a user guide to the @sc{gnu} assembler @code{@value{AS}}. 183@ifclear GENERIC 184This version of the manual describes @code{@value{AS}} configured to generate 185code for @value{TARGET} architectures. 186@end ifclear 187@end iftex 188 189@cindex invocation summary 190@cindex option summary 191@cindex summary of options 192Here is a brief summary of how to invoke @code{@value{AS}}. For details, 193@pxref{Invoking,,Comand-Line Options}. 194 195@c We don't use deffn and friends for the following because they seem 196@c to be limited to one line for the header. 197@smallexample 198@value{AS} [ -a[cdhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ] 199 [ -f ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ] 200 [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ] [ -version ] 201 [ --version ] [ -W ] [ -w ] [ -x ] [ -Z ] 202@ifset A29K 203@c am29k has no machine-dependent assembler options 204@end ifset 205@ifset D10V 206 [ -O ] 207@end ifset 208 209@ifset H8 210@c Hitachi family chips have no machine-dependent assembler options 211@end ifset 212@ifset HPPA 213@c HPPA has no machine-dependent assembler options (yet). 214@end ifset 215@ifset SPARC 216@c The order here is important. See c-sparc.texi. 217 [ -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite | -Av9 | -Av9a ] 218 [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ] 219@end ifset 220@ifset Z8000 221@c Z8000 has no machine-dependent assembler options 222@end ifset 223@ifset I960 224@c see md_parse_option in tc-i960.c 225 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ] 226 [ -b ] [ -no-relax ] 227@end ifset 228@ifset M680X0 229 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ] 230@end ifset 231@ifset MIPS 232 [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ] 233 [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ] 234 [ --trap ] [ --break ] 235 [ --emulation=@var{name} ] 236@end ifset 237 [ -- | @var{files} @dots{} ] 238@end smallexample 239 240@table @code 241@item -a[dhlns] 242Turn on listings, in any of a variety of ways: 243 244@table @code 245@item -ad 246omit debugging directives 247 248@item -ah 249include high-level source 250 251@item -al 252include assembly 253 254@item -an 255omit forms processing 256 257@item -as 258include symbols 259 260@item =file 261set the name of the listing file 262@end table 263 264You may combine these options; for example, use @samp{-aln} for assembly 265listing without forms processing. The @samp{=file} option, if used, must be 266the last one. By itself, @samp{-a} defaults to @samp{-ahls}---that is, all 267listings turned on. 268 269@item -D 270Ignored. This option is accepted for script compatibility with calls to 271other assemblers. 272 273@item --defsym @var{sym}=@var{value} 274Define the symbol @var{sym} to be @var{value} before assembling the input file. 275@var{value} must be an integer constant. As in C, a leading @samp{0x} 276indicates a hexadecimal value, and a leading @samp{0} indicates an octal value. 277 278@item -f 279``fast''---skip whitespace and comment preprocessing (assume source is 280compiler output). 281 282@item --help 283Print a summary of the command line options and exit. 284 285@item -I @var{dir} 286Add directory @var{dir} to the search list for @code{.include} directives. 287 288@item -J 289Don't warn about signed overflow. 290 291@item -K 292@ifclear DIFF-TBL-KLUGE 293This option is accepted but has no effect on the @value{TARGET} family. 294@end ifclear 295@ifset DIFF-TBL-KLUGE 296Issue warnings when difference tables altered for long displacements. 297@end ifset 298 299@item -L 300Keep (in the symbol table) local symbols, starting with @samp{L}. 301 302@item -o @var{objfile} 303Name the object-file output from @code{@value{AS}} @var{objfile}. 304 305@item -R 306Fold the data section into the text section. 307 308@item --statistics 309Print the maximum space (in bytes) and total time (in seconds) used by 310assembly. 311 312@item -v 313@itemx -version 314Print the @code{as} version. 315 316@item --version 317Print the @code{as} version and exit. 318 319@item -W 320Suppress warning messages. 321 322@item -w 323Ignored. 324 325@item -x 326Ignored. 327 328@item -Z 329Generate an object file even after errors. 330 331@item -- | @var{files} @dots{} 332Standard input, or source files to assemble. 333 334@end table 335 336@ifset ARC 337The following options are available when @value{AS} is configured for 338an ARC processor. 339 340@table @code 341 342@cindex ARC endianness 343@cindex endianness, ARC 344@cindex big endian output, ARC 345@item -mbig-endian 346Generate ``big endian'' format output. 347 348@cindex little endian output, ARC 349@item -mlittle-endian 350Generate ``little endian'' format output. 351 352@end table 353@end ifset 354 355@ifset D10V 356The following options are available when @value{AS} is configured for 357a D10V processor. 358@table @code 359@cindex D10V optimization 360@cindex optimization, D10V 361@item -O 362Optimize output by parallelizing instructions. 363@end table 364@end ifset 365 366@ifset I960 367The following options are available when @value{AS} is configured for the 368Intel 80960 processor. 369 370@table @code 371@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC 372Specify which variant of the 960 architecture is the target. 373 374@item -b 375Add code to collect statistics about branches taken. 376 377@item -no-relax 378Do not alter compare-and-branch instructions for long displacements; 379error if necessary. 380 381@end table 382@end ifset 383 384@ifset M680X0 385The following options are available when @value{AS} is configured for the 386Motorola 68000 series. 387 388@table @code 389 390@item -l 391Shorten references to undefined symbols, to one word instead of two. 392 393@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060 394@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200 395Specify what processor in the 68000 family is the target. The default 396is normally the 68020, but this can be changed at configuration time. 397 398@item -m68881 | -m68882 | -mno-68881 | -mno-68882 399The target machine does (or does not) have a floating-point coprocessor. 400The default is to assume a coprocessor for 68020, 68030, and cpu32. Although 401the basic 68000 is not compatible with the 68881, a combination of the 402two can be specified, since it's possible to do emulation of the 403coprocessor instructions with the main processor. 404 405@item -m68851 | -mno-68851 406The target machine does (or does not) have a memory-management 407unit coprocessor. The default is to assume an MMU for 68020 and up. 408 409@end table 410@end ifset 411 412@ifset SPARC 413The following options are available when @code{@value{AS}} is configured 414for the SPARC architecture: 415 416@table @code 417@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite | -Av9 | -Av9a 418Explicitly select a variant of the SPARC architecture. 419 420@item -xarch=v8plus | -xarch=v8plusa 421For compatibility with the Solaris v9 assembler. These options are 422equivalent to -Av9 and -Av9a, respectively. 423 424@item -bump 425Warn when the assembler switches to another architecture. 426@end table 427@end ifset 428 429@ifset MIPS 430The following options are available when @value{AS} is configured for 431a MIPS processor. 432 433@table @code 434@item -G @var{num} 435This option sets the largest size of an object that can be referenced 436implicitly with the @code{gp} register. It is only accepted for targets that 437use ECOFF format, such as a DECstation running Ultrix. The default value is 8. 438 439@cindex MIPS endianness 440@cindex endianness, MIPS 441@cindex big endian output, MIPS 442@item -EB 443Generate ``big endian'' format output. 444 445@cindex little endian output, MIPS 446@item -EL 447Generate ``little endian'' format output. 448 449@cindex MIPS ISA 450@item -mips1 451@itemx -mips2 452@itemx -mips3 453Generate code for a particular MIPS Instruction Set Architecture level. 454@samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors, 455@samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000} 456processor. 457 458@item -m4650 459@item -no-m4650 460Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept 461the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop} 462instructions around accesses to the @samp{HI} and @samp{LO} registers. 463@samp{-no-m4650} turns off this option. 464 465@item -mcpu=@var{CPU} 466Generate code for a particular MIPS cpu. This has little effect on the 467assembler, but it is passed by @code{@value{GCC}}. 468 469@cindex emulation 470@item --emulation=@var{name} 471This option causes @code{@value{AS}} to emulated @code{@value{AS}} configured 472for some other target, in all respects, including output format (choosing 473between ELF and ECOFF only), handling of pseudo-opcodes which may generate 474debugging information or store symbol table information, and default 475endianness. The available configuration names are: @samp{mipsecoff}, 476@samp{mipself}, @samp{mipslecoff}, @samp{mipsbecoff}, @samp{mipslelf}, 477@samp{mipsbelf}. The first two do not alter the default endianness from that 478of the primary target for which the assembler was configured; the others change 479the default to little- or big-endian as indicated by the @samp{b} or @samp{l} 480in the name. Using @samp{-EB} or @samp{-EL} will override the endianness 481selection in any case. 482 483This option is currently supported only when the primary target 484@code{@value{AS}} is configured for is a MIPS ELF or ECOFF target. 485Furthermore, the primary target or others specified with 486@samp{--enable-targets=@dots{}} at configuration time must include support for 487the other format, if both are to be available. For example, the Irix 5 488configuration includes support for both. 489 490Eventually, this option will support more configurations, with more 491fine-grained control over the assembler's behavior, and will be supported for 492more processors. 493 494@item -nocpp 495@code{@value{AS}} ignores this option. It is accepted for compatibility with 496the native tools. 497 498@need 900 499@item --trap 500@itemx --no-trap 501@itemx --break 502@itemx --no-break 503Control how to deal with multiplication overflow and division by zero. 504@samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception 505(and only work for Instruction Set Architecture level 2 and higher); 506@samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a 507break exception. 508@end table 509@end ifset 510 511@menu 512* Manual:: Structure of this Manual 513* GNU Assembler:: The GNU Assembler 514* Object Formats:: Object File Formats 515* Command Line:: Command Line 516* Input Files:: Input Files 517* Object:: Output (Object) File 518* Errors:: Error and Warning Messages 519@end menu 520 521@node Manual 522@section Structure of this Manual 523 524@cindex manual, structure and purpose 525This manual is intended to describe what you need to know to use 526@sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including 527notation for symbols, constants, and expressions; the directives that 528@code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}. 529 530@ifclear GENERIC 531We also cover special features in the @value{TARGET} 532configuration of @code{@value{AS}}, including assembler directives. 533@end ifclear 534@ifset GENERIC 535This manual also describes some of the machine-dependent features of 536various flavors of the assembler. 537@end ifset 538 539@cindex machine instructions (not covered) 540On the other hand, this manual is @emph{not} intended as an introduction 541to programming in assembly language---let alone programming in general! 542In a similar vein, we make no attempt to introduce the machine 543architecture; we do @emph{not} describe the instruction set, standard 544mnemonics, registers or addressing modes that are standard to a 545particular architecture. 546@ifset GENERIC 547You may want to consult the manufacturer's 548machine architecture manual for this information. 549@end ifset 550@ifclear GENERIC 551@ifset H8/300 552For information on the H8/300 machine instruction set, see @cite{H8/300 553Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H, 554see @cite{H8/300H Series Programming Manual} (Hitachi). 555@end ifset 556@ifset H8/500 557For information on the H8/500 machine instruction set, see @cite{H8/500 558Series Programming Manual} (Hitachi M21T001). 559@end ifset 560@ifset SH 561For information on the Hitachi SH machine instruction set, see 562@cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.). 563@end ifset 564@ifset Z8000 565For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual} 566@end ifset 567@end ifclear 568 569@c I think this is premature---doc@cygnus.com, 17jan1991 570@ignore 571Throughout this manual, we assume that you are running @dfn{GNU}, 572the portable operating system from the @dfn{Free Software 573Foundation, Inc.}. This restricts our attention to certain kinds of 574computer (in particular, the kinds of computers that @sc{gnu} can run on); 575once this assumption is granted examples and definitions need less 576qualification. 577 578@code{@value{AS}} is part of a team of programs that turn a high-level 579human-readable series of instructions into a low-level 580computer-readable series of instructions. Different versions of 581@code{@value{AS}} are used for different kinds of computer. 582@end ignore 583 584@c There used to be a section "Terminology" here, which defined 585@c "contents", "byte", "word", and "long". Defining "word" to any 586@c particular size is confusing when the .word directive may generate 16 587@c bits on one machine and 32 bits on another; in general, for the user 588@c version of this manual, none of these terms seem essential to define. 589@c They were used very little even in the former draft of the manual; 590@c this draft makes an effort to avoid them (except in names of 591@c directives). 592 593@node GNU Assembler 594@section The GNU Assembler 595 596@sc{gnu} @code{as} is really a family of assemblers. 597@ifclear GENERIC 598This manual describes @code{@value{AS}}, a member of that family which is 599configured for the @value{TARGET} architectures. 600@end ifclear 601If you use (or have used) the @sc{gnu} assembler on one architecture, you 602should find a fairly similar environment when you use it on another 603architecture. Each version has much in common with the others, 604including object file formats, most assembler directives (often called 605@dfn{pseudo-ops}) and assembler syntax.@refill 606 607@cindex purpose of @sc{gnu} assembler 608@code{@value{AS}} is primarily intended to assemble the output of the 609@sc{gnu} C compiler @code{@value{GCC}} for use by the linker 610@code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}} 611assemble correctly everything that other assemblers for the same 612machine would assemble. 613@ifset VAX 614Any exceptions are documented explicitly (@pxref{Machine Dependencies}). 615@end ifset 616@ifset M680X0 617@c This remark should appear in generic version of manual; assumption 618@c here is that generic version sets M680x0. 619This doesn't mean @code{@value{AS}} always uses the same syntax as another 620assembler for the same architecture; for example, we know of several 621incompatible versions of 680x0 assembly language syntax. 622@end ifset 623 624Unlike older assemblers, @code{@value{AS}} is designed to assemble a source 625program in one pass of the source file. This has a subtle impact on the 626@kbd{.org} directive (@pxref{Org,,@code{.org}}). 627 628@node Object Formats 629@section Object File Formats 630 631@cindex object file format 632The @sc{gnu} assembler can be configured to produce several alternative 633object file formats. For the most part, this does not affect how you 634write assembly language programs; but directives for debugging symbols 635are typically different in different file formats. @xref{Symbol 636Attributes,,Symbol Attributes}. 637@ifclear GENERIC 638@ifclear MULTI-OBJ 639On the @value{TARGET}, @code{@value{AS}} is configured to produce 640@value{OBJ-NAME} format object files. 641@end ifclear 642@c The following should exhaust all configs that set MULTI-OBJ, ideally 643@ifset A29K 644On the @value{TARGET}, @code{@value{AS}} can be configured to produce either 645@code{a.out} or COFF format object files. 646@end ifset 647@ifset I960 648On the @value{TARGET}, @code{@value{AS}} can be configured to produce either 649@code{b.out} or COFF format object files. 650@end ifset 651@ifset HPPA 652On the @value{TARGET}, @code{@value{AS}} can be configured to produce either 653SOM or ELF format object files. 654@end ifset 655@end ifclear 656 657@node Command Line 658@section Command Line 659 660@cindex command line conventions 661After the program name @code{@value{AS}}, the command line may contain 662options and file names. Options may appear in any order, and may be 663before, after, or between file names. The order of file names is 664significant. 665 666@cindex standard input, as input file 667@kindex -- 668@file{--} (two hyphens) by itself names the standard input file 669explicitly, as one of the files for @code{@value{AS}} to assemble. 670 671@cindex options, command line 672Except for @samp{--} any command line argument that begins with a 673hyphen (@samp{-}) is an option. Each option changes the behavior of 674@code{@value{AS}}. No option changes the way another option works. An 675option is a @samp{-} followed by one or more letters; the case of 676the letter is important. All options are optional. 677 678Some options expect exactly one file name to follow them. The file 679name may either immediately follow the option's letter (compatible 680with older assemblers) or it may be the next command argument (@sc{gnu} 681standard). These two command lines are equivalent: 682 683@smallexample 684@value{AS} -o my-object-file.o mumble.s 685@value{AS} -omy-object-file.o mumble.s 686@end smallexample 687 688@node Input Files 689@section Input Files 690 691@cindex input 692@cindex source program 693@cindex files, input 694We use the phrase @dfn{source program}, abbreviated @dfn{source}, to 695describe the program input to one run of @code{@value{AS}}. The program may 696be in one or more files; how the source is partitioned into files 697doesn't change the meaning of the source. 698 699@c I added "con" prefix to "catenation" just to prove I can overcome my 700@c APL training... doc@cygnus.com 701The source program is a concatenation of the text in all the files, in the 702order specified. 703 704Each time you run @code{@value{AS}} it assembles exactly one source 705program. The source program is made up of one or more files. 706(The standard input is also a file.) 707 708You give @code{@value{AS}} a command line that has zero or more input file 709names. The input files are read (from left file name to right). A 710command line argument (in any position) that has no special meaning 711is taken to be an input file name. 712 713If you give @code{@value{AS}} no file names it attempts to read one input file 714from the @code{@value{AS}} standard input, which is normally your terminal. You 715may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program 716to assemble. 717 718Use @samp{--} if you need to explicitly name the standard input file 719in your command line. 720 721If the source is empty, @code{@value{AS}} produces a small, empty object 722file. 723 724@subheading Filenames and Line-numbers 725 726@cindex input file linenumbers 727@cindex line numbers, in input files 728There are two ways of locating a line in the input file (or files) and 729either may be used in reporting error messages. One way refers to a line 730number in a physical file; the other refers to a line number in a 731``logical'' file. @xref{Errors, ,Error and Warning Messages}. 732 733@dfn{Physical files} are those files named in the command line given 734to @code{@value{AS}}. 735 736@dfn{Logical files} are simply names declared explicitly by assembler 737directives; they bear no relation to physical files. Logical file names 738help error messages reflect the original source file, when @code{@value{AS}} 739source is itself synthesized from other files. 740@xref{App-File,,@code{.app-file}}. 741 742@node Object 743@section Output (Object) File 744 745@cindex object file 746@cindex output file 747@kindex a.out 748@kindex .o 749Every time you run @code{@value{AS}} it produces an output file, which is 750your assembly language program translated into numbers. This file 751is the object file. Its default name is 752@ifclear BOUT 753@code{a.out}. 754@end ifclear 755@ifset BOUT 756@ifset GENERIC 757@code{a.out}, or 758@end ifset 759@code{b.out} when @code{@value{AS}} is configured for the Intel 80960. 760@end ifset 761You can give it another name by using the @code{-o} option. Conventionally, 762object file names end with @file{.o}. The default name is used for historical 763reasons: older assemblers were capable of assembling self-contained programs 764directly into a runnable program. (For some formats, this isn't currently 765possible, but it can be done for the @code{a.out} format.) 766 767@cindex linker 768@kindex ld 769The object file is meant for input to the linker @code{@value{LD}}. It contains 770assembled program code, information to help @code{@value{LD}} integrate 771the assembled program into a runnable file, and (optionally) symbolic 772information for the debugger. 773 774@c link above to some info file(s) like the description of a.out. 775@c don't forget to describe @sc{gnu} info as well as Unix lossage. 776 777@node Errors 778@section Error and Warning Messages 779 780@cindex error messsages 781@cindex warning messages 782@cindex messages from assembler 783@code{@value{AS}} may write warnings and error messages to the standard error 784file (usually your terminal). This should not happen when a compiler 785runs @code{@value{AS}} automatically. Warnings report an assumption made so 786that @code{@value{AS}} could keep assembling a flawed program; errors report a 787grave problem that stops the assembly. 788 789@cindex format of warning messages 790Warning messages have the format 791 792@smallexample 793file_name:@b{NNN}:Warning Message Text 794@end smallexample 795 796@noindent 797@cindex line numbers, in warnings/errors 798(where @b{NNN} is a line number). If a logical file name has been given 799(@pxref{App-File,,@code{.app-file}}) it is used for the filename, 800otherwise the name of the current input file is used. If a logical line 801number was given 802@ifset GENERIC 803(@pxref{Line,,@code{.line}}) 804@end ifset 805@ifclear GENERIC 806@ifclear A29K 807(@pxref{Line,,@code{.line}}) 808@end ifclear 809@ifset A29K 810(@pxref{Ln,,@code{.ln}}) 811@end ifset 812@end ifclear 813then it is used to calculate the number printed, 814otherwise the actual line in the current source file is printed. The 815message text is intended to be self explanatory (in the grand Unix 816tradition). 817 818@cindex format of error messages 819Error messages have the format 820@smallexample 821file_name:@b{NNN}:FATAL:Error Message Text 822@end smallexample 823The file name and line number are derived as for warning 824messages. The actual message text may be rather less explanatory 825because many of them aren't supposed to happen. 826 827@node Invoking 828@chapter Command-Line Options 829 830@cindex options, all versions of assembler 831This chapter describes command-line options available in @emph{all} 832versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific 833@ifclear GENERIC 834to the @value{TARGET}. 835@end ifclear 836@ifset GENERIC 837to particular machine architectures. 838@end ifset 839 840If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2), you 841can use the @samp{-Wa} option to pass arguments through to the 842assembler. The assembler arguments must be separated from each other 843(and the @samp{-Wa}) by commas. For example: 844 845@smallexample 846gcc -c -g -O -Wa,-alh,-L file.c 847@end smallexample 848 849@noindent 850emits a listing to standard output with high-level 851and assembly source. 852 853Usually you do not need to use this @samp{-Wa} mechanism, since many compiler 854command-line options are automatically passed to the assembler by the compiler. 855(You can call the @sc{gnu} compiler driver with the @samp{-v} option to see 856precisely what options it passes to each compilation pass, including the 857assembler.) 858 859@menu 860* a:: -a[cdhlns] enable listings 861* D:: -D for compatibility 862* f:: -f to work faster 863* I:: -I for .include search path 864@ifclear DIFF-TBL-KLUGE 865* K:: -K for compatibility 866@end ifclear 867@ifset DIFF-TBL-KLUGE 868* K:: -K for difference tables 869@end ifset 870 871* L:: -L to retain local labels 872* M:: -M or --mri to assemble in MRI compatibility mode 873* o:: -o to name the object file 874* R:: -R to join data and text sections 875* statistics:: --statistics to see statistics about assembly 876* v:: -v to announce version 877* W:: -W to suppress warnings 878* Z:: -Z to make object file even after errors 879@end menu 880 881@node a 882@section Enable Listings: @code{-a[cdhlns]} 883 884@kindex -a 885@kindex -ac 886@kindex -ad 887@kindex -ah 888@kindex -al 889@kindex -an 890@kindex -as 891@cindex listings, enabling 892@cindex assembly listings, enabling 893 894These options enable listing output from the assembler. By itself, 895@samp{-a} requests high-level, assembly, and symbols listing. 896You can use other letters to select specific options for the list: 897@samp{-ah} requests a high-level language listing, 898@samp{-al} requests an output-program assembly listing, and 899@samp{-as} requests a symbol table listing. 900High-level listings require that a compiler debugging option like 901@samp{-g} be used, and that assembly listings (@samp{-al}) be requested 902also. 903 904Use the @samp{-ac} option to omit false conditionals from a listing. Any lines 905which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any 906other conditional), or a true @code{.if} followed by an @code{.else}, will be 907omitted from the listing. 908 909Use the @samp{-ad} option to omit debugging directives from the 910listing. 911 912Once you have specified one of these options, you can further control 913listing output and its appearance using the directives @code{.list}, 914@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and 915@code{.sbttl}. 916The @samp{-an} option turns off all forms processing. 917If you do not request listing output with one of the @samp{-a} options, the 918listing-control directives have no effect. 919 920The letters after @samp{-a} may be combined into one option, 921@emph{e.g.}, @samp{-aln}. 922 923@node D 924@section @code{-D} 925 926@kindex -D 927This option has no effect whatsoever, but it is accepted to make it more 928likely that scripts written for other assemblers also work with 929@code{@value{AS}}. 930 931@node f 932@section Work Faster: @code{-f} 933 934@kindex -f 935@cindex trusted compiler 936@cindex faster processing (@code{-f}) 937@samp{-f} should only be used when assembling programs written by a 938(trusted) compiler. @samp{-f} stops the assembler from doing whitespace 939and comment preprocessing on 940the input file(s) before assembling them. @xref{Preprocessing, 941,Preprocessing}. 942 943@quotation 944@emph{Warning:} if you use @samp{-f} when the files actually need to be 945preprocessed (if they contain comments, for example), @code{@value{AS}} does 946not work correctly. 947@end quotation 948 949@node I 950@section @code{.include} search path: @code{-I} @var{path} 951 952@kindex -I @var{path} 953@cindex paths for @code{.include} 954@cindex search path for @code{.include} 955@cindex @code{include} directive search path 956Use this option to add a @var{path} to the list of directories 957@code{@value{AS}} searches for files specified in @code{.include} 958directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as 959many times as necessary to include a variety of paths. The current 960working directory is always searched first; after that, @code{@value{AS}} 961searches any @samp{-I} directories in the same order as they were 962specified (left to right) on the command line. 963 964@node K 965@section Difference Tables: @code{-K} 966 967@kindex -K 968@ifclear DIFF-TBL-KLUGE 969On the @value{TARGET} family, this option is allowed, but has no effect. It is 970permitted for compatibility with the @sc{gnu} assembler on other platforms, 971where it can be used to warn when the assembler alters the machine code 972generated for @samp{.word} directives in difference tables. The @value{TARGET} 973family does not have the addressing limitations that sometimes lead to this 974alteration on other platforms. 975@end ifclear 976 977@ifset DIFF-TBL-KLUGE 978@cindex difference tables, warning 979@cindex warning for altered difference tables 980@code{@value{AS}} sometimes alters the code emitted for directives of the form 981@samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}. 982You can use the @samp{-K} option if you want a warning issued when this 983is done. 984@end ifset 985 986@node L 987@section Include Local Labels: @code{-L} 988 989@kindex -L 990@cindex local labels, retaining in output 991Labels beginning with @samp{L} (upper case only) are called @dfn{local 992labels}. @xref{Symbol Names}. Normally you do not see such labels when 993debugging, because they are intended for the use of programs (like 994compilers) that compose assembler programs, not for your notice. 995Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not 996normally debug with them. 997 998This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols 999in the object file. Usually if you do this you also tell the linker 1000@code{@value{LD}} to preserve symbols whose names begin with @samp{L}. 1001 1002By default, a local label is any label beginning with @samp{L}, but each 1003target is allowed to redefine the local label prefix. 1004@ifset HPPA 1005On the HPPA local labels begin with @samp{L$}. 1006@end ifset 1007 1008@node M 1009@section Assemble in MRI Compatibility Mode: @code{-M} 1010 1011@kindex -M 1012@cindex MRI compatibility mode 1013The @code{-M} or @code{--mri} option selects MRI compatibility mode. This 1014changes the syntax and pseudo-op handling of @code{@value{AS}} to make it 1015compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the 1016configured target) assembler from Microtec Research. The exact nature of the 1017MRI syntax will not be documented here; see the MRI manuals for more 1018information. Note in particular that the handling of macros and macro 1019arguments is somewhat different. The purpose of this option is to permit 1020assembling existing MRI assembler code using @code{@value{AS}}. 1021 1022The MRI compatibility is not complete. Certain operations of the MRI assembler 1023depend upon its object file format, and can not be supported using other object 1024file formats. Supporting these would require enhancing each object file format 1025individually. These are: 1026 1027@itemize @bullet 1028@item global symbols in common section 1029 1030The m68k MRI assembler supports common sections which are merged by the linker. 1031Other object file formats do not support this. @code{@value{AS}} handles 1032common sections by treating them as a single common symbol. It permits local 1033symbols to be defined within a common section, but it can not support global 1034symbols, since it has no way to describe them. 1035 1036@item complex relocations 1037 1038The MRI assemblers support relocations against a negated section address, and 1039relocations which combine the start addresses of two or more sections. These 1040are not support by other object file formats. 1041 1042@item @code{END} pseudo-op specifying start address 1043 1044The MRI @code{END} pseudo-op permits the specification of a start address. 1045This is not supported by other object file formats. The start address may 1046instead be specified using the @code{-e} option to the linker, or in a linker 1047script. 1048 1049@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops 1050 1051The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module 1052name to the output file. This is not supported by other object file formats. 1053 1054@item @code{ORG} pseudo-op 1055 1056The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given 1057address. This differs from the usual @code{@value{AS}} @code{.org} pseudo-op, 1058which changes the location within the current section. Absolute sections are 1059not supported by other object file formats. The address of a section may be 1060assigned within a linker script. 1061@end itemize 1062 1063There are some other features of the MRI assembler which are not supported by 1064@code{@value{AS}}, typically either because they are difficult or because they 1065seem of little consequence. Some of these may be supported in future releases. 1066 1067@itemize @bullet 1068 1069@item EBCDIC strings 1070 1071EBCDIC strings are not supported. 1072 1073@item packed binary coded decimal 1074 1075Packed binary coded decimal is not supported. This means that the @code{DC.P} 1076and @code{DCB.P} pseudo-ops are not supported. 1077 1078@item @code{FEQU} pseudo-op 1079 1080The m68k @code{FEQU} pseudo-op is not supported. 1081 1082@item @code{NOOBJ} pseudo-op 1083 1084The m68k @code{NOOBJ} pseudo-op is not supported. 1085 1086@item @code{OPT} branch control options 1087 1088The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB}, 1089@code{BRL}, and @code{BRW}---are ignored. @code{@value{AS}} automatically 1090relaxes all branches, whether forward or backward, to an appropriate size, so 1091these options serve no purpose. 1092 1093@item @code{OPT} list control options 1094 1095The following m68k @code{OPT} list control options are ignored: @code{C}, 1096@code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M}, 1097@code{MEX}, @code{MC}, @code{MD}, @code{X}. 1098 1099@item other @code{OPT} options 1100 1101The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O}, 1102@code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}. 1103 1104@item @code{OPT} @code{D} option is default 1105 1106The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler. 1107@code{OPT NOD} may be used to turn it off. 1108 1109@item @code{XREF} pseudo-op. 1110 1111The m68k @code{XREF} pseudo-op is ignored. 1112 1113@item @code{.debug} pseudo-op 1114 1115The i960 @code{.debug} pseudo-op is not supported. 1116 1117@item @code{.extended} pseudo-op 1118 1119The i960 @code{.extended} pseudo-op is not supported. 1120 1121@item @code{.list} pseudo-op. 1122 1123The various options of the i960 @code{.list} pseudo-op are not supported. 1124 1125@item @code{.optimize} pseudo-op 1126 1127The i960 @code{.optimize} pseudo-op is not supported. 1128 1129@item @code{.output} pseudo-op 1130 1131The i960 @code{.output} pseudo-op is not supported. 1132 1133@item @code{.setreal} pseudo-op 1134 1135The i960 @code{.setreal} pseudo-op is not supported. 1136 1137@end itemize 1138 1139@node o 1140@section Name the Object File: @code{-o} 1141 1142@kindex -o 1143@cindex naming object file 1144@cindex object file name 1145There is always one object file output when you run @code{@value{AS}}. By 1146default it has the name 1147@ifset GENERIC 1148@ifset I960 1149@file{a.out} (or @file{b.out}, for Intel 960 targets only). 1150@end ifset 1151@ifclear I960 1152@file{a.out}. 1153@end ifclear 1154@end ifset 1155@ifclear GENERIC 1156@ifset I960 1157@file{b.out}. 1158@end ifset 1159@ifclear I960 1160@file{a.out}. 1161@end ifclear 1162@end ifclear 1163You use this option (which takes exactly one filename) to give the 1164object file a different name. 1165 1166Whatever the object file is called, @code{@value{AS}} overwrites any 1167existing file of the same name. 1168 1169@node R 1170@section Join Data and Text Sections: @code{-R} 1171 1172@kindex -R 1173@cindex data and text sections, joining 1174@cindex text and data sections, joining 1175@cindex joining text and data sections 1176@cindex merging text and data sections 1177@code{-R} tells @code{@value{AS}} to write the object file as if all 1178data-section data lives in the text section. This is only done at 1179the very last moment: your binary data are the same, but data 1180section parts are relocated differently. The data section part of 1181your object file is zero bytes long because all its bytes are 1182appended to the text section. (@xref{Sections,,Sections and Relocation}.) 1183 1184When you specify @code{-R} it would be possible to generate shorter 1185address displacements (because we do not have to cross between text and 1186data section). We refrain from doing this simply for compatibility with 1187older versions of @code{@value{AS}}. In future, @code{-R} may work this way. 1188 1189@ifset COFF 1190When @code{@value{AS}} is configured for COFF output, 1191this option is only useful if you use sections named @samp{.text} and 1192@samp{.data}. 1193@end ifset 1194 1195@ifset HPPA 1196@code{-R} is not supported for any of the HPPA targets. Using 1197@code{-R} generates a warning from @code{@value{AS}}. 1198@end ifset 1199 1200@node statistics 1201@section Display Assembly Statistics: @code{--statistics} 1202 1203@kindex --statistics 1204@cindex statistics, about assembly 1205@cindex time, total for assembly 1206@cindex space used, maximum for assembly 1207Use @samp{--statistics} to display two statistics about the resources used by 1208@code{@value{AS}}: the maximum amount of space allocated during the assembly 1209(in bytes), and the total execution time taken for the assembly (in @sc{cpu} 1210seconds). 1211 1212@node v 1213@section Announce Version: @code{-v} 1214 1215@kindex -v 1216@kindex -version 1217@cindex assembler version 1218@cindex version of assembler 1219You can find out what version of as is running by including the 1220option @samp{-v} (which you can also spell as @samp{-version}) on the 1221command line. 1222 1223@node W 1224@section Suppress Warnings: @code{-W} 1225 1226@kindex -W 1227@cindex suppressing warnings 1228@cindex warnings, suppressing 1229@code{@value{AS}} should never give a warning or error message when 1230assembling compiler output. But programs written by people often 1231cause @code{@value{AS}} to give a warning that a particular assumption was 1232made. All such warnings are directed to the standard error file. 1233If you use this option, no warnings are issued. This option only 1234affects the warning messages: it does not change any particular of how 1235@code{@value{AS}} assembles your file. Errors, which stop the assembly, are 1236still reported. 1237 1238@node Z 1239@section Generate Object File in Spite of Errors: @code{-Z} 1240@cindex object file, after errors 1241@cindex errors, continuing after 1242After an error message, @code{@value{AS}} normally produces no output. If for 1243some reason you are interested in object file output even after 1244@code{@value{AS}} gives an error message on your program, use the @samp{-Z} 1245option. If there are any errors, @code{@value{AS}} continues anyways, and 1246writes an object file after a final warning message of the form @samp{@var{n} 1247errors, @var{m} warnings, generating bad object file.} 1248 1249@node Syntax 1250@chapter Syntax 1251 1252@cindex machine-independent syntax 1253@cindex syntax, machine-independent 1254This chapter describes the machine-independent syntax allowed in a 1255source file. @code{@value{AS}} syntax is similar to what many other 1256assemblers use; it is inspired by the BSD 4.2 1257@ifclear VAX 1258assembler. 1259@end ifclear 1260@ifset VAX 1261assembler, except that @code{@value{AS}} does not assemble Vax bit-fields. 1262@end ifset 1263 1264@menu 1265* Preprocessing:: Preprocessing 1266* Whitespace:: Whitespace 1267* Comments:: Comments 1268* Symbol Intro:: Symbols 1269* Statements:: Statements 1270* Constants:: Constants 1271@end menu 1272 1273@node Preprocessing 1274@section Preprocessing 1275 1276@cindex preprocessing 1277The @code{@value{AS}} internal preprocessor: 1278@itemize @bullet 1279@cindex whitespace, removed by preprocessor 1280@item 1281adjusts and removes extra whitespace. It leaves one space or tab before 1282the keywords on a line, and turns any other whitespace on the line into 1283a single space. 1284 1285@cindex comments, removed by preprocessor 1286@item 1287removes all comments, replacing them with a single space, or an 1288appropriate number of newlines. 1289 1290@cindex constants, converted by preprocessor 1291@item 1292converts character constants into the appropriate numeric values. 1293@end itemize 1294 1295It does not do macro processing, include file handling, or 1296anything else you may get from your C compiler's preprocessor. You can 1297do include file processing with the @code{.include} directive 1298(@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver 1299to get other ``CPP'' style preprocessing, by giving the input file a 1300@samp{.S} suffix. @xref{Overall Options,, Options Controlling the Kind of 1301Output, gcc.info, Using GNU CC}. 1302 1303Excess whitespace, comments, and character constants 1304cannot be used in the portions of the input text that are not 1305preprocessed. 1306 1307@cindex turning preprocessing on and off 1308@cindex preprocessing, turning on and off 1309@kindex #NO_APP 1310@kindex #APP 1311If the first line of an input file is @code{#NO_APP} or if you use the 1312@samp{-f} option, whitespace and comments are not removed from the input file. 1313Within an input file, you can ask for whitespace and comment removal in 1314specific portions of the by putting a line that says @code{#APP} before the 1315text that may contain whitespace or comments, and putting a line that says 1316@code{#NO_APP} after this text. This feature is mainly intend to support 1317@code{asm} statements in compilers whose output is otherwise free of comments 1318and whitespace. 1319 1320@node Whitespace 1321@section Whitespace 1322 1323@cindex whitespace 1324@dfn{Whitespace} is one or more blanks or tabs, in any order. 1325Whitespace is used to separate symbols, and to make programs neater for 1326people to read. Unless within character constants 1327(@pxref{Characters,,Character Constants}), any whitespace means the same 1328as exactly one space. 1329 1330@node Comments 1331@section Comments 1332 1333@cindex comments 1334There are two ways of rendering comments to @code{@value{AS}}. In both 1335cases the comment is equivalent to one space. 1336 1337Anything from @samp{/*} through the next @samp{*/} is a comment. 1338This means you may not nest these comments. 1339 1340@smallexample 1341/* 1342 The only way to include a newline ('\n') in a comment 1343 is to use this sort of comment. 1344*/ 1345 1346/* This sort of comment does not nest. */ 1347@end smallexample 1348 1349@cindex line comment character 1350Anything from the @dfn{line comment} character to the next newline 1351is considered a comment and is ignored. The line comment character is 1352@ifset A29K 1353@samp{;} for the AMD 29K family; 1354@end ifset 1355@ifset H8/300 1356@samp{;} for the H8/300 family; 1357@end ifset 1358@ifset H8/500 1359@samp{!} for the H8/500 family; 1360@end ifset 1361@ifset HPPA 1362@samp{;} for the HPPA; 1363@end ifset 1364@ifset I960 1365@samp{#} on the i960; 1366@end ifset 1367@ifset SH 1368@samp{!} for the Hitachi SH; 1369@end ifset 1370@ifset SPARC 1371@samp{!} on the SPARC; 1372@end ifset 1373@ifset M680X0 1374@samp{|} on the 680x0; 1375@end ifset 1376@ifset VAX 1377@samp{#} on the Vax; 1378@end ifset 1379@ifset Z8000 1380@samp{!} for the Z8000; 1381@end ifset 1382see @ref{Machine Dependencies}. @refill 1383@c FIXME What about i386, m88k, i860? 1384 1385@ifset GENERIC 1386On some machines there are two different line comment characters. One 1387character only begins a comment if it is the first non-whitespace character on 1388a line, while the other always begins a comment. 1389@end ifset 1390 1391@kindex # 1392@cindex lines starting with @code{#} 1393@cindex logical line numbers 1394To be compatible with past assemblers, lines that begin with @samp{#} have a 1395special interpretation. Following the @samp{#} should be an absolute 1396expression (@pxref{Expressions}): the logical line number of the @emph{next} 1397line. Then a string (@pxref{Strings,, Strings}) is allowed: if present it is a 1398new logical file name. The rest of the line, if any, should be whitespace. 1399 1400If the first non-whitespace characters on the line are not numeric, 1401the line is ignored. (Just like a comment.) 1402 1403@smallexample 1404 # This is an ordinary comment. 1405# 42-6 "new_file_name" # New logical file name 1406 # This is logical line # 36. 1407@end smallexample 1408This feature is deprecated, and may disappear from future versions 1409of @code{@value{AS}}. 1410 1411@node Symbol Intro 1412@section Symbols 1413 1414@cindex characters used in symbols 1415@ifclear SPECIAL-SYMS 1416A @dfn{symbol} is one or more characters chosen from the set of all 1417letters (both upper and lower case), digits and the three characters 1418@samp{_.$}. 1419@end ifclear 1420@ifset SPECIAL-SYMS 1421@ifclear GENERIC 1422@ifset H8 1423A @dfn{symbol} is one or more characters chosen from the set of all 1424letters (both upper and lower case), digits and the three characters 1425@samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in 1426symbol names.) 1427@end ifset 1428@end ifclear 1429@end ifset 1430@ifset GENERIC 1431On most machines, you can also use @code{$} in symbol names; exceptions 1432are noted in @ref{Machine Dependencies}. 1433@end ifset 1434No symbol may begin with a digit. Case is significant. 1435There is no length limit: all characters are significant. Symbols are 1436delimited by characters not in that set, or by the beginning of a file 1437(since the source program must end with a newline, the end of a file is 1438not a possible symbol delimiter). @xref{Symbols}. 1439@cindex length of symbols 1440 1441@node Statements 1442@section Statements 1443 1444@cindex statements, structure of 1445@cindex line separator character 1446@cindex statement separator character 1447@ifclear GENERIC 1448@ifclear abnormal-separator 1449A @dfn{statement} ends at a newline character (@samp{\n}) or at a 1450semicolon (@samp{;}). The newline or semicolon is considered part of 1451the preceding statement. Newlines and semicolons within character 1452constants are an exception: they do not end statements. 1453@end ifclear 1454@ifset abnormal-separator 1455@ifset A29K 1456A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at'' 1457sign (@samp{@@}). The newline or at sign is considered part of the 1458preceding statement. Newlines and at signs within character constants 1459are an exception: they do not end statements. 1460@end ifset 1461@ifset HPPA 1462A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation 1463point (@samp{!}). The newline or exclamation point is considered part of the 1464preceding statement. Newlines and exclamation points within character 1465constants are an exception: they do not end statements. 1466@end ifset 1467@ifset H8 1468A @dfn{statement} ends at a newline character (@samp{\n}); or (for the 1469H8/300) a dollar sign (@samp{$}); or (for the 1470Hitachi-SH or the 1471H8/500) a semicolon 1472(@samp{;}). The newline or separator character is considered part of 1473the preceding statement. Newlines and separators within character 1474constants are an exception: they do not end statements. 1475@end ifset 1476@end ifset 1477@end ifclear 1478@ifset GENERIC 1479A @dfn{statement} ends at a newline character (@samp{\n}) or line 1480separator character. (The line separator is usually @samp{;}, unless 1481this conflicts with the comment character; @pxref{Machine Dependencies}.) The 1482newline or separator character is considered part of the preceding 1483statement. Newlines and separators within character constants are an 1484exception: they do not end statements. 1485@end ifset 1486 1487@cindex newline, required at file end 1488@cindex EOF, newline must precede 1489It is an error to end any statement with end-of-file: the last 1490character of any input file should be a newline.@refill 1491 1492@cindex continuing statements 1493@cindex multi-line statements 1494@cindex statement on multiple lines 1495You may write a statement on more than one line if you put a 1496backslash (@kbd{\}) immediately in front of any newlines within the 1497statement. When @code{@value{AS}} reads a backslashed newline both 1498characters are ignored. You can even put backslashed newlines in 1499the middle of symbol names without changing the meaning of your 1500source program. 1501 1502An empty statement is allowed, and may include whitespace. It is ignored. 1503 1504@cindex instructions and directives 1505@cindex directives and instructions 1506@c "key symbol" is not used elsewhere in the document; seems pedantic to 1507@c @defn{} it in that case, as was done previously... doc@cygnus.com, 1508@c 13feb91. 1509A statement begins with zero or more labels, optionally followed by a 1510key symbol which determines what kind of statement it is. The key 1511symbol determines the syntax of the rest of the statement. If the 1512symbol begins with a dot @samp{.} then the statement is an assembler 1513directive: typically valid for any computer. If the symbol begins with 1514a letter the statement is an assembly language @dfn{instruction}: it 1515assembles into a machine language instruction. 1516@ifset GENERIC 1517Different versions of @code{@value{AS}} for different computers 1518recognize different instructions. In fact, the same symbol may 1519represent a different instruction in a different computer's assembly 1520language.@refill 1521@end ifset 1522 1523@cindex @code{:} (label) 1524@cindex label (@code{:}) 1525A label is a symbol immediately followed by a colon (@code{:}). 1526Whitespace before a label or after a colon is permitted, but you may not 1527have whitespace between a label's symbol and its colon. @xref{Labels}. 1528 1529@ifset HPPA 1530For HPPA targets, labels need not be immediately followed by a colon, but 1531the definition of a label must begin in column zero. This also implies that 1532only one label may be defined on each line. 1533@end ifset 1534 1535@smallexample 1536label: .directive followed by something 1537another_label: # This is an empty statement. 1538 instruction operand_1, operand_2, @dots{} 1539@end smallexample 1540 1541@node Constants 1542@section Constants 1543 1544@cindex constants 1545A constant is a number, written so that its value is known by 1546inspection, without knowing any context. Like this: 1547@smallexample 1548@group 1549.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value. 1550.ascii "Ring the bell\7" # A string constant. 1551.octa 0x123456789abcdef0123456789ABCDEF0 # A bignum. 1552.float 0f-314159265358979323846264338327\ 155395028841971.693993751E-40 # - pi, a flonum. 1554@end group 1555@end smallexample 1556 1557@menu 1558* Characters:: Character Constants 1559* Numbers:: Number Constants 1560@end menu 1561 1562@node Characters 1563@subsection Character Constants 1564 1565@cindex character constants 1566@cindex constants, character 1567There are two kinds of character constants. A @dfn{character} stands 1568for one character in one byte and its value may be used in 1569numeric expressions. String constants (properly called string 1570@emph{literals}) are potentially many bytes and their values may not be 1571used in arithmetic expressions. 1572 1573@menu 1574* Strings:: Strings 1575* Chars:: Characters 1576@end menu 1577 1578@node Strings 1579@subsubsection Strings 1580 1581@cindex string constants 1582@cindex constants, string 1583A @dfn{string} is written between double-quotes. It may contain 1584double-quotes or null characters. The way to get special characters 1585into a string is to @dfn{escape} these characters: precede them with 1586a backslash @samp{\} character. For example @samp{\\} represents 1587one backslash: the first @code{\} is an escape which tells 1588@code{@value{AS}} to interpret the second character literally as a backslash 1589(which prevents @code{@value{AS}} from recognizing the second @code{\} as an 1590escape character). The complete list of escapes follows. 1591 1592@cindex escape codes, character 1593@cindex character escape codes 1594@table @kbd 1595@c @item \a 1596@c Mnemonic for ACKnowledge; for ASCII this is octal code 007. 1597@c 1598@cindex @code{\b} (backspace character) 1599@cindex backspace (@code{\b}) 1600@item \b 1601Mnemonic for backspace; for ASCII this is octal code 010. 1602 1603@c @item \e 1604@c Mnemonic for EOText; for ASCII this is octal code 004. 1605@c 1606@cindex @code{\f} (formfeed character) 1607@cindex formfeed (@code{\f}) 1608@item \f 1609Mnemonic for FormFeed; for ASCII this is octal code 014. 1610 1611@cindex @code{\n} (newline character) 1612@cindex newline (@code{\n}) 1613@item \n 1614Mnemonic for newline; for ASCII this is octal code 012. 1615 1616@c @item \p 1617@c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}. 1618@c 1619@cindex @code{\r} (carriage return character) 1620@cindex carriage return (@code{\r}) 1621@item \r 1622Mnemonic for carriage-Return; for ASCII this is octal code 015. 1623 1624@c @item \s 1625@c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with 1626@c other assemblers. 1627@c 1628@cindex @code{\t} (tab) 1629@cindex tab (@code{\t}) 1630@item \t 1631Mnemonic for horizontal Tab; for ASCII this is octal code 011. 1632 1633@c @item \v 1634@c Mnemonic for Vertical tab; for ASCII this is octal code 013. 1635@c @item \x @var{digit} @var{digit} @var{digit} 1636@c A hexadecimal character code. The numeric code is 3 hexadecimal digits. 1637@c 1638@cindex @code{\@var{ddd}} (octal character code) 1639@cindex octal character code (@code{\@var{ddd}}) 1640@item \ @var{digit} @var{digit} @var{digit} 1641An octal character code. The numeric code is 3 octal digits. 1642For compatibility with other Unix systems, 8 and 9 are accepted as digits: 1643for example, @code{\008} has the value 010, and @code{\009} the value 011. 1644 1645@cindex @code{\@var{xd...}} (hex character code) 1646@cindex hex character code (@code{\@var{xd...}}) 1647@item \@code{x} @var{hex-digits...} 1648A hex character code. All trailing hex digits are combined. Either upper or 1649lower case @code{x} works. 1650 1651@cindex @code{\\} (@samp{\} character) 1652@cindex backslash (@code{\\}) 1653@item \\ 1654Represents one @samp{\} character. 1655 1656@c @item \' 1657@c Represents one @samp{'} (accent acute) character. 1658@c This is needed in single character literals 1659@c (@xref{Characters,,Character Constants}.) to represent 1660@c a @samp{'}. 1661@c 1662@cindex @code{\"} (doublequote character) 1663@cindex doublequote (@code{\"}) 1664@item \" 1665Represents one @samp{"} character. Needed in strings to represent 1666this character, because an unescaped @samp{"} would end the string. 1667 1668@item \ @var{anything-else} 1669Any other character when escaped by @kbd{\} gives a warning, but 1670assembles as if the @samp{\} was not present. The idea is that if 1671you used an escape sequence you clearly didn't want the literal 1672interpretation of the following character. However @code{@value{AS}} has no 1673other interpretation, so @code{@value{AS}} knows it is giving you the wrong 1674code and warns you of the fact. 1675@end table 1676 1677Which characters are escapable, and what those escapes represent, 1678varies widely among assemblers. The current set is what we think 1679the BSD 4.2 assembler recognizes, and is a subset of what most C 1680compilers recognize. If you are in doubt, do not use an escape 1681sequence. 1682 1683@node Chars 1684@subsubsection Characters 1685 1686@cindex single character constant 1687@cindex character, single 1688@cindex constant, single character 1689A single character may be written as a single quote immediately 1690followed by that character. The same escapes apply to characters as 1691to strings. So if you want to write the character backslash, you 1692must write @kbd{'\\} where the first @code{\} escapes the second 1693@code{\}. As you can see, the quote is an acute accent, not a 1694grave accent. A newline 1695@ifclear GENERIC 1696@ifclear abnormal-separator 1697(or semicolon @samp{;}) 1698@end ifclear 1699@ifset abnormal-separator 1700@ifset A29K 1701(or at sign @samp{@@}) 1702@end ifset 1703@ifset H8 1704(or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the 1705Hitachi SH or 1706H8/500) 1707@end ifset 1708@end ifset 1709@end ifclear 1710immediately following an acute accent is taken as a literal character 1711and does not count as the end of a statement. The value of a character 1712constant in a numeric expression is the machine's byte-wide code for 1713that character. @code{@value{AS}} assumes your character code is ASCII: 1714@kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill 1715 1716@node Numbers 1717@subsection Number Constants 1718 1719@cindex constants, number 1720@cindex number constants 1721@code{@value{AS}} distinguishes three kinds of numbers according to how they 1722are stored in the target machine. @emph{Integers} are numbers that 1723would fit into an @code{int} in the C language. @emph{Bignums} are 1724integers, but they are stored in more than 32 bits. @emph{Flonums} 1725are floating point numbers, described below. 1726 1727@menu 1728* Integers:: Integers 1729* Bignums:: Bignums 1730* Flonums:: Flonums 1731@ifclear GENERIC 1732@ifset I960 1733* Bit Fields:: Bit Fields 1734@end ifset 1735@end ifclear 1736@end menu 1737 1738@node Integers 1739@subsubsection Integers 1740@cindex integers 1741@cindex constants, integer 1742 1743@cindex binary integers 1744@cindex integers, binary 1745A binary integer is @samp{0b} or @samp{0B} followed by zero or more of 1746the binary digits @samp{01}. 1747 1748@cindex octal integers 1749@cindex integers, octal 1750An octal integer is @samp{0} followed by zero or more of the octal 1751digits (@samp{01234567}). 1752 1753@cindex decimal integers 1754@cindex integers, decimal 1755A decimal integer starts with a non-zero digit followed by zero or 1756more digits (@samp{0123456789}). 1757 1758@cindex hexadecimal integers 1759@cindex integers, hexadecimal 1760A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or 1761more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}. 1762 1763Integers have the usual values. To denote a negative integer, use 1764the prefix operator @samp{-} discussed under expressions 1765(@pxref{Prefix Ops,,Prefix Operators}). 1766 1767@node Bignums 1768@subsubsection Bignums 1769 1770@cindex bignums 1771@cindex constants, bignum 1772A @dfn{bignum} has the same syntax and semantics as an integer 1773except that the number (or its negative) takes more than 32 bits to 1774represent in binary. The distinction is made because in some places 1775integers are permitted while bignums are not. 1776 1777@node Flonums 1778@subsubsection Flonums 1779@cindex flonums 1780@cindex floating point numbers 1781@cindex constants, floating point 1782 1783@cindex precision, floating point 1784A @dfn{flonum} represents a floating point number. The translation is 1785indirect: a decimal floating point number from the text is converted by 1786@code{@value{AS}} to a generic binary floating point number of more than 1787sufficient precision. This generic floating point number is converted 1788to a particular computer's floating point format (or formats) by a 1789portion of @code{@value{AS}} specialized to that computer. 1790 1791A flonum is written by writing (in order) 1792@itemize @bullet 1793@item 1794The digit @samp{0}. 1795@ifset HPPA 1796(@samp{0} is optional on the HPPA.) 1797@end ifset 1798 1799@item 1800A letter, to tell @code{@value{AS}} the rest of the number is a flonum. 1801@ifset GENERIC 1802@kbd{e} is recommended. Case is not important. 1803@ignore 1804@c FIXME: verify if flonum syntax really this vague for most cases 1805(Any otherwise illegal letter works here, but that might be changed. Vax BSD 18064.2 assembler seems to allow any of @samp{defghDEFGH}.) 1807@end ignore 1808 1809On the H8/300, H8/500, 1810Hitachi SH, 1811and AMD 29K architectures, the letter must be 1812one of the letters @samp{DFPRSX} (in upper or lower case). 1813 1814 1815On the Intel 960 architecture, the letter must be 1816one of the letters @samp{DFT} (in upper or lower case). 1817 1818On the HPPA architecture, the letter must be @samp{E} (upper case only). 1819@end ifset 1820@ifclear GENERIC 1821@ifset A29K 1822One of the letters @samp{DFPRSX} (in upper or lower case). 1823@end ifset 1824@ifset H8 1825One of the letters @samp{DFPRSX} (in upper or lower case). 1826@end ifset 1827@ifset HPPA 1828The letter @samp{E} (upper case only). 1829@end ifset 1830@ifset I960 1831One of the letters @samp{DFT} (in upper or lower case). 1832@end ifset 1833@end ifclear 1834 1835@item 1836An optional sign: either @samp{+} or @samp{-}. 1837 1838@item 1839An optional @dfn{integer part}: zero or more decimal digits. 1840 1841@item 1842An optional @dfn{fractional part}: @samp{.} followed by zero 1843or more decimal digits. 1844 1845@item 1846An optional exponent, consisting of: 1847 1848@itemize @bullet 1849@item 1850An @samp{E} or @samp{e}. 1851@c I can't find a config where "EXP_CHARS" is other than 'eE', but in 1852@c principle this can perfectly well be different on different targets. 1853@item 1854Optional sign: either @samp{+} or @samp{-}. 1855@item 1856One or more decimal digits. 1857@end itemize 1858 1859@end itemize 1860 1861At least one of the integer part or the fractional part must be 1862present. The floating point number has the usual base-10 value. 1863 1864@code{@value{AS}} does all processing using integers. Flonums are computed 1865independently of any floating point hardware in the computer running 1866@code{@value{AS}}. 1867 1868@ifclear GENERIC 1869@ifset I960 1870@c Bit fields are written as a general facility but are also controlled 1871@c by a conditional-compilation flag---which is as of now (21mar91) 1872@c turned on only by the i960 config of GAS. 1873@node Bit Fields 1874@subsubsection Bit Fields 1875 1876@cindex bit fields 1877@cindex constants, bit field 1878You can also define numeric constants as @dfn{bit fields}. 1879specify two numbers separated by a colon--- 1880@example 1881@var{mask}:@var{value} 1882@end example 1883@noindent 1884@code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and 1885@var{value}. 1886 1887The resulting number is then packed 1888@ifset GENERIC 1889@c this conditional paren in case bit fields turned on elsewhere than 960 1890(in host-dependent byte order) 1891@end ifset 1892into a field whose width depends on which assembler directive has the 1893bit-field as its argument. Overflow (a result from the bitwise and 1894requiring more binary digits to represent) is not an error; instead, 1895more constants are generated, of the specified width, beginning with the 1896least significant digits.@refill 1897 1898The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long}, 1899@code{.short}, and @code{.word} accept bit-field arguments. 1900@end ifset 1901@end ifclear 1902 1903@node Sections 1904@chapter Sections and Relocation 1905@cindex sections 1906@cindex relocation 1907 1908@menu 1909* Secs Background:: Background 1910* Ld Sections:: Linker Sections 1911* As Sections:: Assembler Internal Sections 1912* Sub-Sections:: Sub-Sections 1913* bss:: bss Section 1914@end menu 1915 1916@node Secs Background 1917@section Background 1918 1919Roughly, a section is a range of addresses, with no gaps; all data 1920``in'' those addresses is treated the same for some particular purpose. 1921For example there may be a ``read only'' section. 1922 1923@cindex linker, and assembler 1924@cindex assembler, and linker 1925The linker @code{@value{LD}} reads many object files (partial programs) and 1926combines their contents to form a runnable program. When @code{@value{AS}} 1927emits an object file, the partial program is assumed to start at address 0. 1928@code{@value{LD}} assigns the final addresses for the partial program, so that 1929different partial programs do not overlap. This is actually an 1930oversimplification, but it suffices to explain how @code{@value{AS}} uses 1931sections. 1932 1933@code{@value{LD}} moves blocks of bytes of your program to their run-time 1934addresses. These blocks slide to their run-time addresses as rigid 1935units; their length does not change and neither does the order of bytes 1936within them. Such a rigid unit is called a @emph{section}. Assigning 1937run-time addresses to sections is called @dfn{relocation}. It includes 1938the task of adjusting mentions of object-file addresses so they refer to 1939the proper run-time addresses. 1940@ifset H8 1941For the H8/300 and H8/500, 1942and for the Hitachi SH, 1943@code{@value{AS}} pads sections if needed to 1944ensure they end on a word (sixteen bit) boundary. 1945@end ifset 1946 1947@cindex standard assembler sections 1948An object file written by @code{@value{AS}} has at least three sections, any 1949of which may be empty. These are named @dfn{text}, @dfn{data} and 1950@dfn{bss} sections. 1951 1952@ifset COFF 1953@ifset GENERIC 1954When it generates COFF output, 1955@end ifset 1956@code{@value{AS}} can also generate whatever other named sections you specify 1957using the @samp{.section} directive (@pxref{Section,,@code{.section}}). 1958If you do not use any directives that place output in the @samp{.text} 1959or @samp{.data} sections, these sections still exist, but are empty. 1960@end ifset 1961 1962@ifset HPPA 1963@ifset GENERIC 1964When @code{@value{AS}} generates SOM or ELF output for the HPPA, 1965@end ifset 1966@code{@value{AS}} can also generate whatever other named sections you 1967specify using the @samp{.space} and @samp{.subspace} directives. See 1968@cite{HP9000 Series 800 Assembly Language Reference Manual} 1969(HP 92432-90001) for details on the @samp{.space} and @samp{.subspace} 1970assembler directives. 1971 1972@ifset SOM 1973Additionally, @code{@value{AS}} uses different names for the standard 1974text, data, and bss sections when generating SOM output. Program text 1975is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and 1976BSS into @samp{$BSS$}. 1977@end ifset 1978@end ifset 1979 1980Within the object file, the text section starts at address @code{0}, the 1981data section follows, and the bss section follows the data section. 1982 1983@ifset HPPA 1984When generating either SOM or ELF output files on the HPPA, the text 1985section starts at address @code{0}, the data section at address 1986@code{0x4000000}, and the bss section follows the data section. 1987@end ifset 1988 1989To let @code{@value{LD}} know which data changes when the sections are 1990relocated, and how to change that data, @code{@value{AS}} also writes to the 1991object file details of the relocation needed. To perform relocation 1992@code{@value{LD}} must know, each time an address in the object 1993file is mentioned: 1994@itemize @bullet 1995@item 1996Where in the object file is the beginning of this reference to 1997an address? 1998@item 1999How long (in bytes) is this reference? 2000@item 2001Which section does the address refer to? What is the numeric value of 2002@display 2003(@var{address}) @minus{} (@var{start-address of section})? 2004@end display 2005@item 2006Is the reference to an address ``Program-Counter relative''? 2007@end itemize 2008 2009@cindex addresses, format of 2010@cindex section-relative addressing 2011In fact, every address @code{@value{AS}} ever uses is expressed as 2012@display 2013(@var{section}) + (@var{offset into section}) 2014@end display 2015@noindent 2016Further, most expressions @code{@value{AS}} computes have this section-relative 2017nature. 2018@ifset SOM 2019(For some object formats, such as SOM for the HPPA, some expressions are 2020symbol-relative instead.) 2021@end ifset 2022 2023In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset 2024@var{N} into section @var{secname}.'' 2025 2026Apart from text, data and bss sections you need to know about the 2027@dfn{absolute} section. When @code{@value{LD}} mixes partial programs, 2028addresses in the absolute section remain unchanged. For example, address 2029@code{@{absolute 0@}} is ``relocated'' to run-time address 0 by 2030@code{@value{LD}}. Although the linker never arranges two partial programs' 2031data sections with overlapping addresses after linking, @emph{by definition} 2032their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one 2033part of a program is always the same address when the program is running as 2034address @code{@{absolute@ 239@}} in any other part of the program. 2035 2036The idea of sections is extended to the @dfn{undefined} section. Any 2037address whose section is unknown at assembly time is by definition 2038rendered @{undefined @var{U}@}---where @var{U} is filled in later. 2039Since numbers are always defined, the only way to generate an undefined 2040address is to mention an undefined symbol. A reference to a named 2041common block would be such a symbol: its value is unknown at assembly 2042time so it has section @emph{undefined}. 2043 2044By analogy the word @emph{section} is used to describe groups of sections in 2045the linked program. @code{@value{LD}} puts all partial programs' text 2046sections in contiguous addresses in the linked program. It is 2047customary to refer to the @emph{text section} of a program, meaning all 2048the addresses of all partial programs' text sections. Likewise for 2049data and bss sections. 2050 2051Some sections are manipulated by @code{@value{LD}}; others are invented for 2052use of @code{@value{AS}} and have no meaning except during assembly. 2053 2054@node Ld Sections 2055@section Linker Sections 2056@code{@value{LD}} deals with just four kinds of sections, summarized below. 2057 2058@table @strong 2059 2060@ifset COFF 2061@cindex named sections 2062@cindex sections, named 2063@item named sections 2064@end ifset 2065@ifset aout-bout 2066@cindex text section 2067@cindex data section 2068@itemx text section 2069@itemx data section 2070@end ifset 2071These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as 2072separate but equal sections. Anything you can say of one section is 2073true another. 2074@ifset aout-bout 2075When the program is running, however, it is 2076customary for the text section to be unalterable. The 2077text section is often shared among processes: it contains 2078instructions, constants and the like. The data section of a running 2079program is usually alterable: for example, C variables would be stored 2080in the data section. 2081@end ifset 2082 2083@cindex bss section 2084@item bss section 2085This section contains zeroed bytes when your program begins running. It 2086is used to hold unitialized variables or common storage. The length of 2087each partial program's bss section is important, but because it starts 2088out containing zeroed bytes there is no need to store explicit zero 2089bytes in the object file. The bss section was invented to eliminate 2090those explicit zeros from object files. 2091 2092@cindex absolute section 2093@item absolute section 2094Address 0 of this section is always ``relocated'' to runtime address 0. 2095This is useful if you want to refer to an address that @code{@value{LD}} must 2096not change when relocating. In this sense we speak of absolute 2097addresses being ``unrelocatable'': they do not change during relocation. 2098 2099@cindex undefined section 2100@item undefined section 2101This ``section'' is a catch-all for address references to objects not in 2102the preceding sections. 2103@c FIXME: ref to some other doc on obj-file formats could go here. 2104@end table 2105 2106@cindex relocation example 2107An idealized example of three relocatable sections follows. 2108@ifset COFF 2109The example uses the traditional section names @samp{.text} and @samp{.data}. 2110@end ifset 2111Memory addresses are on the horizontal axis. 2112 2113@c TEXI2ROFF-KILL 2114@ifinfo 2115@c END TEXI2ROFF-KILL 2116@smallexample 2117 +-----+----+--+ 2118partial program # 1: |ttttt|dddd|00| 2119 +-----+----+--+ 2120 2121 text data bss 2122 seg. seg. seg. 2123 2124 +---+---+---+ 2125partial program # 2: |TTT|DDD|000| 2126 +---+---+---+ 2127 2128 +--+---+-----+--+----+---+-----+~~ 2129linked program: | |TTT|ttttt| |dddd|DDD|00000| 2130 +--+---+-----+--+----+---+-----+~~ 2131 2132 addresses: 0 @dots{} 2133@end smallexample 2134@c TEXI2ROFF-KILL 2135@end ifinfo 2136@need 5000 2137@tex 2138 2139\line{\it Partial program \#1: \hfil} 2140\line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} 2141\line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil} 2142 2143\line{\it Partial program \#2: \hfil} 2144\line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} 2145\line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil} 2146 2147\line{\it linked program: \hfil} 2148\line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil} 2149\line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt 2150ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt 2151DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil} 2152 2153\line{\it addresses: \hfil} 2154\line{0\dots\hfil} 2155 2156@end tex 2157@c END TEXI2ROFF-KILL 2158 2159@node As Sections 2160@section Assembler Internal Sections 2161 2162@cindex internal assembler sections 2163@cindex sections in messages, internal 2164These sections are meant only for the internal use of @code{@value{AS}}. They 2165have no meaning at run-time. You do not really need to know about these 2166sections for most purposes; but they can be mentioned in @code{@value{AS}} 2167warning messages, so it might be helpful to have an idea of their 2168meanings to @code{@value{AS}}. These sections are used to permit the 2169value of every expression in your assembly language program to be a 2170section-relative address. 2171 2172@table @b 2173@cindex assembler internal logic error 2174@item ASSEMBLER-INTERNAL-LOGIC-ERROR! 2175An internal assembler logic error has been found. This means there is a 2176bug in the assembler. 2177 2178@cindex expr (internal section) 2179@item expr section 2180The assembler stores complex expression internally as combinations of 2181symbols. When it needs to represent an expression as a symbol, it puts 2182it in the expr section. 2183@c FIXME item debug 2184@c FIXME item transfer[t] vector preload 2185@c FIXME item transfer[t] vector postload 2186@c FIXME item register 2187@end table 2188 2189@node Sub-Sections 2190@section Sub-Sections 2191 2192@cindex numbered subsections 2193@cindex grouping data 2194@ifset aout-bout 2195Assembled bytes 2196@ifset COFF 2197conventionally 2198@end ifset 2199fall into two sections: text and data. 2200@end ifset 2201You may have separate groups of 2202@ifset GENERIC 2203data in named sections 2204@end ifset 2205@ifclear GENERIC 2206@ifclear aout-bout 2207data in named sections 2208@end ifclear 2209@ifset aout-bout 2210text or data 2211@end ifset 2212@end ifclear 2213that you want to end up near to each other in the object file, even though they 2214are not contiguous in the assembler source. @code{@value{AS}} allows you to 2215use @dfn{subsections} for this purpose. Within each section, there can be 2216numbered subsections with values from 0 to 8192. Objects assembled into the 2217same subsection go into the object file together with other objects in the same 2218subsection. For example, a compiler might want to store constants in the text 2219section, but might not want to have them interspersed with the program being 2220assembled. In this case, the compiler could issue a @samp{.text 0} before each 2221section of code being output, and a @samp{.text 1} before each group of 2222constants being output. 2223 2224Subsections are optional. If you do not use subsections, everything 2225goes in subsection number zero. 2226 2227@ifset GENERIC 2228Each subsection is zero-padded up to a multiple of four bytes. 2229(Subsections may be padded a different amount on different flavors 2230of @code{@value{AS}}.) 2231@end ifset 2232@ifclear GENERIC 2233@ifset H8 2234On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word 2235boundary (two bytes). 2236The same is true on the Hitachi SH. 2237@end ifset 2238@ifset I960 2239@c FIXME section padding (alignment)? 2240@c Rich Pixley says padding here depends on target obj code format; that 2241@c doesn't seem particularly useful to say without further elaboration, 2242@c so for now I say nothing about it. If this is a generic BFD issue, 2243@c these paragraphs might need to vanish from this manual, and be 2244@c discussed in BFD chapter of binutils (or some such). 2245@end ifset 2246@ifset A29K 2247On the AMD 29K family, no particular padding is added to section or 2248subsection sizes; @value{AS} forces no alignment on this platform. 2249@end ifset 2250@end ifclear 2251 2252Subsections appear in your object file in numeric order, lowest numbered 2253to highest. (All this to be compatible with other people's assemblers.) 2254The object file contains no representation of subsections; @code{@value{LD}} and 2255other programs that manipulate object files see no trace of them. 2256They just see all your text subsections as a text section, and all your 2257data subsections as a data section. 2258 2259To specify which subsection you want subsequent statements assembled 2260into, use a numeric argument to specify it, in a @samp{.text 2261@var{expression}} or a @samp{.data @var{expression}} statement. 2262@ifset COFF 2263@ifset GENERIC 2264When generating COFF output, you 2265@end ifset 2266@ifclear GENERIC 2267You 2268@end ifclear 2269can also use an extra subsection 2270argument with arbitrary named sections: @samp{.section @var{name}, 2271@var{expression}}. 2272@end ifset 2273@var{Expression} should be an absolute expression. 2274(@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0} 2275is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly 2276begins in @code{text 0}. For instance: 2277@smallexample 2278.text 0 # The default subsection is text 0 anyway. 2279.ascii "This lives in the first text subsection. *" 2280.text 1 2281.ascii "But this lives in the second text subsection." 2282.data 0 2283.ascii "This lives in the data section," 2284.ascii "in the first data subsection." 2285.text 0 2286.ascii "This lives in the first text section," 2287.ascii "immediately following the asterisk (*)." 2288@end smallexample 2289 2290Each section has a @dfn{location counter} incremented by one for every byte 2291assembled into that section. Because subsections are merely a convenience 2292restricted to @code{@value{AS}} there is no concept of a subsection location 2293counter. There is no way to directly manipulate a location counter---but the 2294@code{.align} directive changes it, and any label definition captures its 2295current value. The location counter of the section where statements are being 2296assembled is said to be the @dfn{active} location counter. 2297 2298@node bss 2299@section bss Section 2300 2301@cindex bss section 2302@cindex common variable storage 2303The bss section is used for local common variable storage. 2304You may allocate address space in the bss section, but you may 2305not dictate data to load into it before your program executes. When 2306your program starts running, all the contents of the bss 2307section are zeroed bytes. 2308 2309The @code{.lcomm} pseudo-op defines a symbol in the bss section; see 2310@ref{Lcomm,,@code{.lcomm}}. 2311 2312The @code{.comm} pseudo-op may be used to declare a common symbol, which is 2313another form of uninitialized symbol; see @xref{Comm,,@code{.comm}}. 2314 2315@ifset GENERIC 2316When assembling for a target which supports multiple sections, such as ELF or 2317COFF, you may switch into the @code{.bss} section and define symbols as usual; 2318see @ref{Section,,@code{.section}}. You may only assemble zero values into the 2319section. Typically the section will only contain symbol definitions and 2320@code{.skip} directives (@pxref{Skip,,@code{.skip}}). 2321@end ifset 2322 2323@node Symbols 2324@chapter Symbols 2325 2326@cindex symbols 2327Symbols are a central concept: the programmer uses symbols to name 2328things, the linker uses symbols to link, and the debugger uses symbols 2329to debug. 2330 2331@quotation 2332@cindex debuggers, and symbol order 2333@emph{Warning:} @code{@value{AS}} does not place symbols in the object file in 2334the same order they were declared. This may break some debuggers. 2335@end quotation 2336 2337@menu 2338* Labels:: Labels 2339* Setting Symbols:: Giving Symbols Other Values 2340* Symbol Names:: Symbol Names 2341* Dot:: The Special Dot Symbol 2342* Symbol Attributes:: Symbol Attributes 2343@end menu 2344 2345@node Labels 2346@section Labels 2347 2348@cindex labels 2349A @dfn{label} is written as a symbol immediately followed by a colon 2350@samp{:}. The symbol then represents the current value of the 2351active location counter, and is, for example, a suitable instruction 2352operand. You are warned if you use the same symbol to represent two 2353different locations: the first definition overrides any other 2354definitions. 2355 2356@ifset HPPA 2357On the HPPA, the usual form for a label need not be immediately followed by a 2358colon, but instead must start in column zero. Only one label may be defined on 2359a single line. To work around this, the HPPA version of @code{@value{AS}} also 2360provides a special directive @code{.label} for defining labels more flexibly. 2361@end ifset 2362 2363@node Setting Symbols 2364@section Giving Symbols Other Values 2365 2366@cindex assigning values to symbols 2367@cindex symbol values, assigning 2368A symbol can be given an arbitrary value by writing a symbol, followed 2369by an equals sign @samp{=}, followed by an expression 2370(@pxref{Expressions}). This is equivalent to using the @code{.set} 2371directive. @xref{Set,,@code{.set}}. 2372 2373@node Symbol Names 2374@section Symbol Names 2375 2376@cindex symbol names 2377@cindex names, symbol 2378@ifclear SPECIAL-SYMS 2379Symbol names begin with a letter or with one of @samp{._}. On most 2380machines, you can also use @code{$} in symbol names; exceptions are 2381noted in @ref{Machine Dependencies}. That character may be followed by any 2382string of digits, letters, dollar signs (unless otherwise noted in 2383@ref{Machine Dependencies}), and underscores. 2384@end ifclear 2385@ifset A29K 2386For the AMD 29K family, @samp{?} is also allowed in the 2387body of a symbol name, though not at its beginning. 2388@end ifset 2389 2390@ifset SPECIAL-SYMS 2391@ifset H8 2392Symbol names begin with a letter or with one of @samp{._}. On the 2393Hitachi SH or the 2394H8/500, you can also use @code{$} in symbol names. That character may 2395be followed by any string of digits, letters, dollar signs (save on the 2396H8/300), and underscores. 2397@end ifset 2398@end ifset 2399 2400Case of letters is significant: @code{foo} is a different symbol name 2401than @code{Foo}. 2402 2403Each symbol has exactly one name. Each name in an assembly language program 2404refers to exactly one symbol. You may use that symbol name any number of times 2405in a program. 2406 2407@subheading Local Symbol Names 2408 2409@cindex local symbol names 2410@cindex symbol names, local 2411@cindex temporary symbol names 2412@cindex symbol names, temporary 2413Local symbols help compilers and programmers use names temporarily. 2414There are ten local symbol names, which are re-used throughout the 2415program. You may refer to them using the names @samp{0} @samp{1} 2416@dots{} @samp{9}. To define a local symbol, write a label of the form 2417@samp{@b{N}:} (where @b{N} represents any digit). To refer to the most 2418recent previous definition of that symbol write @samp{@b{N}b}, using the 2419same digit as when you defined the label. To refer to the next 2420definition of a local label, write @samp{@b{N}f}---where @b{N} gives you 2421a choice of 10 forward references. The @samp{b} stands for 2422``backwards'' and the @samp{f} stands for ``forwards''. 2423 2424Local symbols are not emitted by the current @sc{gnu} C compiler. 2425 2426There is no restriction on how you can use these labels, but 2427remember that at any point in the assembly you can refer to at most 242810 prior local labels and to at most 10 forward local labels. 2429 2430Local symbol names are only a notation device. They are immediately 2431transformed into more conventional symbol names before the assembler 2432uses them. The symbol names stored in the symbol table, appearing in 2433error messages and optionally emitted to the object file have these 2434parts: 2435 2436@table @code 2437@item L 2438All local labels begin with @samp{L}. Normally both @code{@value{AS}} and 2439@code{@value{LD}} forget symbols that start with @samp{L}. These labels are 2440used for symbols you are never intended to see. If you use the 2441@samp{-L} option then @code{@value{AS}} retains these symbols in the 2442object file. If you also instruct @code{@value{LD}} to retain these symbols, 2443you may use them in debugging. 2444 2445@item @var{digit} 2446If the label is written @samp{0:} then the digit is @samp{0}. 2447If the label is written @samp{1:} then the digit is @samp{1}. 2448And so on up through @samp{9:}. 2449 2450@item @kbd{C-A} 2451This unusual character is included so you do not accidentally invent 2452a symbol of the same name. The character has ASCII value 2453@samp{\001}. 2454 2455@item @emph{ordinal number} 2456This is a serial number to keep the labels distinct. The first 2457@samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the 2458number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:} 2459through @samp{9:}. 2460@end table 2461 2462For instance, the first @code{1:} is named @code{L1@kbd{C-A}1}, the 44th 2463@code{3:} is named @code{L3@kbd{C-A}44}. 2464 2465@node Dot 2466@section The Special Dot Symbol 2467 2468@cindex dot (symbol) 2469@cindex @code{.} (symbol) 2470@cindex current address 2471@cindex location counter 2472The special symbol @samp{.} refers to the current address that 2473@code{@value{AS}} is assembling into. Thus, the expression @samp{melvin: 2474.long .} defines @code{melvin} to contain its own address. 2475Assigning a value to @code{.} is treated the same as a @code{.org} 2476directive. Thus, the expression @samp{.=.+4} is the same as saying 2477@ifclear no-space-dir 2478@samp{.space 4}. 2479@end ifclear 2480@ifset no-space-dir 2481@ifset A29K 2482@samp{.block 4}. 2483@end ifset 2484@end ifset 2485 2486@node Symbol Attributes 2487@section Symbol Attributes 2488 2489@cindex symbol attributes 2490@cindex attributes, symbol 2491Every symbol has, as well as its name, the attributes ``Value'' and 2492``Type''. Depending on output format, symbols can also have auxiliary 2493attributes. 2494@ifset INTERNALS 2495The detailed definitions are in @file{a.out.h}. 2496@end ifset 2497 2498If you use a symbol without defining it, @code{@value{AS}} assumes zero for 2499all these attributes, and probably won't warn you. This makes the 2500symbol an externally defined symbol, which is generally what you 2501would want. 2502 2503@menu 2504* Symbol Value:: Value 2505* Symbol Type:: Type 2506@ifset aout-bout 2507@ifset GENERIC 2508* a.out Symbols:: Symbol Attributes: @code{a.out} 2509@end ifset 2510@ifclear GENERIC 2511@ifclear BOUT 2512* a.out Symbols:: Symbol Attributes: @code{a.out} 2513@end ifclear 2514@ifset BOUT 2515* a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out} 2516@end ifset 2517@end ifclear 2518@end ifset 2519@ifset COFF 2520* COFF Symbols:: Symbol Attributes for COFF 2521@end ifset 2522@ifset SOM 2523* SOM Symbols:: Symbol Attributes for SOM 2524@end ifset 2525@end menu 2526 2527@node Symbol Value 2528@subsection Value 2529 2530@cindex value of a symbol 2531@cindex symbol value 2532The value of a symbol is (usually) 32 bits. For a symbol which labels a 2533location in the text, data, bss or absolute sections the value is the 2534number of addresses from the start of that section to the label. 2535Naturally for text, data and bss sections the value of a symbol changes 2536as @code{@value{LD}} changes section base addresses during linking. Absolute 2537symbols' values do not change during linking: that is why they are 2538called absolute. 2539 2540The value of an undefined symbol is treated in a special way. If it is 25410 then the symbol is not defined in this assembler source file, and 2542@code{@value{LD}} tries to determine its value from other files linked into the 2543same program. You make this kind of symbol simply by mentioning a symbol 2544name without defining it. A non-zero value represents a @code{.comm} 2545common declaration. The value is how much common storage to reserve, in 2546bytes (addresses). The symbol refers to the first address of the 2547allocated storage. 2548 2549@node Symbol Type 2550@subsection Type 2551 2552@cindex type of a symbol 2553@cindex symbol type 2554The type attribute of a symbol contains relocation (section) 2555information, any flag settings indicating that a symbol is external, and 2556(optionally), other information for linkers and debuggers. The exact 2557format depends on the object-code output format in use. 2558 2559@ifset aout-bout 2560@ifclear GENERIC 2561@ifset BOUT 2562@c The following avoids a "widow" subsection title. @group would be 2563@c better if it were available outside examples. 2564@need 1000 2565@node a.out Symbols 2566@subsection Symbol Attributes: @code{a.out}, @code{b.out} 2567 2568@cindex @code{b.out} symbol attributes 2569@cindex symbol attributes, @code{b.out} 2570These symbol attributes appear only when @code{@value{AS}} is configured for 2571one of the Berkeley-descended object output formats---@code{a.out} or 2572@code{b.out}. 2573 2574@end ifset 2575@ifclear BOUT 2576@node a.out Symbols 2577@subsection Symbol Attributes: @code{a.out} 2578 2579@cindex @code{a.out} symbol attributes 2580@cindex symbol attributes, @code{a.out} 2581 2582@end ifclear 2583@end ifclear 2584@ifset GENERIC 2585@node a.out Symbols 2586@subsection Symbol Attributes: @code{a.out} 2587 2588@cindex @code{a.out} symbol attributes 2589@cindex symbol attributes, @code{a.out} 2590 2591@end ifset 2592@menu 2593* Symbol Desc:: Descriptor 2594* Symbol Other:: Other 2595@end menu 2596 2597@node Symbol Desc 2598@subsubsection Descriptor 2599 2600@cindex descriptor, of @code{a.out} symbol 2601This is an arbitrary 16-bit value. You may establish a symbol's 2602descriptor value by using a @code{.desc} statement 2603(@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to 2604@code{@value{AS}}. 2605 2606@node Symbol Other 2607@subsubsection Other 2608 2609@cindex other attribute, of @code{a.out} symbol 2610This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}. 2611@end ifset 2612 2613@ifset COFF 2614@node COFF Symbols 2615@subsection Symbol Attributes for COFF 2616 2617@cindex COFF symbol attributes 2618@cindex symbol attributes, COFF 2619 2620The COFF format supports a multitude of auxiliary symbol attributes; 2621like the primary symbol attributes, they are set between @code{.def} and 2622@code{.endef} directives. 2623 2624@subsubsection Primary Attributes 2625 2626@cindex primary attributes, COFF symbols 2627The symbol name is set with @code{.def}; the value and type, 2628respectively, with @code{.val} and @code{.type}. 2629 2630@subsubsection Auxiliary Attributes 2631 2632@cindex auxiliary attributes, COFF symbols 2633The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl}, 2634@code{.size}, and @code{.tag} can generate auxiliary symbol table 2635information for COFF. 2636@end ifset 2637 2638@ifset SOM 2639@node SOM Symbols 2640@subsection Symbol Attributes for SOM 2641 2642@cindex SOM symbol attributes 2643@cindex symbol attributes, SOM 2644 2645The SOM format for the HPPA supports a multitude of symbol attributes set with 2646the @code{.EXPORT} and @code{.IMPORT} directives. 2647 2648The attributes are described in @cite{HP9000 Series 800 Assembly 2649Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and 2650@code{EXPORT} assembler directive documentation. 2651@end ifset 2652 2653@node Expressions 2654@chapter Expressions 2655 2656@cindex expressions 2657@cindex addresses 2658@cindex numeric values 2659An @dfn{expression} specifies an address or numeric value. 2660Whitespace may precede and/or follow an expression. 2661 2662The result of an expression must be an absolute number, or else an offset into 2663a particular section. If an expression is not absolute, and there is not 2664enough information when @code{@value{AS}} sees the expression to know its 2665section, a second pass over the source program might be necessary to interpret 2666the expression---but the second pass is currently not implemented. 2667@code{@value{AS}} aborts with an error message in this situation. 2668 2669@menu 2670* Empty Exprs:: Empty Expressions 2671* Integer Exprs:: Integer Expressions 2672@end menu 2673 2674@node Empty Exprs 2675@section Empty Expressions 2676 2677@cindex empty expressions 2678@cindex expressions, empty 2679An empty expression has no value: it is just whitespace or null. 2680Wherever an absolute expression is required, you may omit the 2681expression, and @code{@value{AS}} assumes a value of (absolute) 0. This 2682is compatible with other assemblers. 2683 2684@node Integer Exprs 2685@section Integer Expressions 2686 2687@cindex integer expressions 2688@cindex expressions, integer 2689An @dfn{integer expression} is one or more @emph{arguments} delimited 2690by @emph{operators}. 2691 2692@menu 2693* Arguments:: Arguments 2694* Operators:: Operators 2695* Prefix Ops:: Prefix Operators 2696* Infix Ops:: Infix Operators 2697@end menu 2698 2699@node Arguments 2700@subsection Arguments 2701 2702@cindex expression arguments 2703@cindex arguments in expressions 2704@cindex operands in expressions 2705@cindex arithmetic operands 2706@dfn{Arguments} are symbols, numbers or subexpressions. In other 2707contexts arguments are sometimes called ``arithmetic operands''. In 2708this manual, to avoid confusing them with the ``instruction operands'' of 2709the machine language, we use the term ``argument'' to refer to parts of 2710expressions only, reserving the word ``operand'' to refer only to machine 2711instruction operands. 2712 2713Symbols are evaluated to yield @{@var{section} @var{NNN}@} where 2714@var{section} is one of text, data, bss, absolute, 2715or undefined. @var{NNN} is a signed, 2's complement 32 bit 2716integer. 2717 2718Numbers are usually integers. 2719 2720A number can be a flonum or bignum. In this case, you are warned 2721that only the low order 32 bits are used, and @code{@value{AS}} pretends 2722these 32 bits are an integer. You may write integer-manipulating 2723instructions that act on exotic constants, compatible with other 2724assemblers. 2725 2726@cindex subexpressions 2727Subexpressions are a left parenthesis @samp{(} followed by an integer 2728expression, followed by a right parenthesis @samp{)}; or a prefix 2729operator followed by an argument. 2730 2731@node Operators 2732@subsection Operators 2733 2734@cindex operators, in expressions 2735@cindex arithmetic functions 2736@cindex functions, in expressions 2737@dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix 2738operators are followed by an argument. Infix operators appear 2739between their arguments. Operators may be preceded and/or followed by 2740whitespace. 2741 2742@node Prefix Ops 2743@subsection Prefix Operator 2744 2745@cindex prefix operators 2746@code{@value{AS}} has the following @dfn{prefix operators}. They each take 2747one argument, which must be absolute. 2748 2749@c the tex/end tex stuff surrounding this small table is meant to make 2750@c it align, on the printed page, with the similar table in the next 2751@c section (which is inside an enumerate). 2752@tex 2753\global\advance\leftskip by \itemindent 2754@end tex 2755 2756@table @code 2757@item - 2758@dfn{Negation}. Two's complement negation. 2759@item ~ 2760@dfn{Complementation}. Bitwise not. 2761@end table 2762 2763@tex 2764\global\advance\leftskip by -\itemindent 2765@end tex 2766 2767@node Infix Ops 2768@subsection Infix Operators 2769 2770@cindex infix operators 2771@cindex operators, permitted arguments 2772@dfn{Infix operators} take two arguments, one on either side. Operators 2773have precedence, but operations with equal precedence are performed left 2774to right. Apart from @code{+} or @code{-}, both arguments must be 2775absolute, and the result is absolute. 2776 2777@enumerate 2778@cindex operator precedence 2779@cindex precedence of operators 2780 2781@item 2782Highest Precedence 2783 2784@table @code 2785@item * 2786@dfn{Multiplication}. 2787 2788@item / 2789@dfn{Division}. Truncation is the same as the C operator @samp{/} 2790 2791@item % 2792@dfn{Remainder}. 2793 2794@item < 2795@itemx << 2796@dfn{Shift Left}. Same as the C operator @samp{<<}. 2797 2798@item > 2799@itemx >> 2800@dfn{Shift Right}. Same as the C operator @samp{>>}. 2801@end table 2802 2803@item 2804Intermediate precedence 2805 2806@table @code 2807@item | 2808 2809@dfn{Bitwise Inclusive Or}. 2810 2811@item & 2812@dfn{Bitwise And}. 2813 2814@item ^ 2815@dfn{Bitwise Exclusive Or}. 2816 2817@item ! 2818@dfn{Bitwise Or Not}. 2819@end table 2820 2821@item 2822Lowest Precedence 2823 2824@table @code 2825@cindex addition, permitted arguments 2826@cindex plus, permitted arguments 2827@cindex arguments for addition 2828@item + 2829@dfn{Addition}. If either argument is absolute, the result has the section of 2830the other argument. You may not add together arguments from different 2831sections. 2832 2833@cindex subtraction, permitted arguments 2834@cindex minus, permitted arguments 2835@cindex arguments for subtraction 2836@item - 2837@dfn{Subtraction}. If the right argument is absolute, the 2838result has the section of the left argument. 2839If both arguments are in the same section, the result is absolute. 2840You may not subtract arguments from different sections. 2841@c FIXME is there still something useful to say about undefined - undefined ? 2842@end table 2843@end enumerate 2844 2845In short, it's only meaningful to add or subtract the @emph{offsets} in an 2846address; you can only have a defined section in one of the two arguments. 2847 2848@node Pseudo Ops 2849@chapter Assembler Directives 2850 2851@cindex directives, machine independent 2852@cindex pseudo-ops, machine independent 2853@cindex machine independent directives 2854All assembler directives have names that begin with a period (@samp{.}). 2855The rest of the name is letters, usually in lower case. 2856 2857This chapter discusses directives that are available regardless of the 2858target machine configuration for the @sc{gnu} assembler. 2859@ifset GENERIC 2860Some machine configurations provide additional directives. 2861@xref{Machine Dependencies}. 2862@end ifset 2863@ifclear GENERIC 2864@ifset machine-directives 2865@xref{Machine Dependencies} for additional directives. 2866@end ifset 2867@end ifclear 2868 2869@menu 2870* Abort:: @code{.abort} 2871@ifset COFF 2872* ABORT:: @code{.ABORT} 2873@end ifset 2874 2875* Align:: @code{.align @var{abs-expr} , @var{abs-expr}} 2876* App-File:: @code{.app-file @var{string}} 2877* Ascii:: @code{.ascii "@var{string}"}@dots{} 2878* Asciz:: @code{.asciz "@var{string}"}@dots{} 2879* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}} 2880* Byte:: @code{.byte @var{expressions}} 2881* Comm:: @code{.comm @var{symbol} , @var{length} } 2882* Data:: @code{.data @var{subsection}} 2883@ifset COFF 2884* Def:: @code{.def @var{name}} 2885@end ifset 2886@ifset aout-bout 2887* Desc:: @code{.desc @var{symbol}, @var{abs-expression}} 2888@end ifset 2889@ifset COFF 2890* Dim:: @code{.dim} 2891@end ifset 2892 2893* Double:: @code{.double @var{flonums}} 2894* Eject:: @code{.eject} 2895* Else:: @code{.else} 2896@ifset COFF 2897* Endef:: @code{.endef} 2898@end ifset 2899 2900* Endif:: @code{.endif} 2901* Equ:: @code{.equ @var{symbol}, @var{expression}} 2902* Equiv:: @code{.equiv @var{symbol}, @var{expression}} 2903* Err:: @code{.err} 2904* Extern:: @code{.extern} 2905@ifclear no-file-dir 2906* File:: @code{.file @var{string}} 2907@end ifclear 2908 2909* Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}} 2910* Float:: @code{.float @var{flonums}} 2911* Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}} 2912* hword:: @code{.hword @var{expressions}} 2913* Ident:: @code{.ident} 2914* If:: @code{.if @var{absolute expression}} 2915* Include:: @code{.include "@var{file}"} 2916* Int:: @code{.int @var{expressions}} 2917* Irp:: @code{.irp @var{symbol},@var{values}}@dots{} 2918* Irpc:: @code{.irpc @var{symbol},@var{values}}@dots{} 2919* Lcomm:: @code{.lcomm @var{symbol} , @var{length}} 2920* Lflags:: @code{.lflags} 2921@ifclear no-line-dir 2922* Line:: @code{.line @var{line-number}} 2923@end ifclear 2924 2925* Ln:: @code{.ln @var{line-number}} 2926* Linkonce:: @code{.linkonce [@var{type}]} 2927* List:: @code{.list} 2928* Long:: @code{.long @var{expressions}} 2929@ignore 2930* Lsym:: @code{.lsym @var{symbol}, @var{expression}} 2931@end ignore 2932 2933* Macro:: @code{.macro @var{name} @var{args}}@dots{} 2934* MRI:: @code{.mri @var{val}} 2935 2936* Nolist:: @code{.nolist} 2937* Octa:: @code{.octa @var{bignums}} 2938* Org:: @code{.org @var{new-lc} , @var{fill}} 2939* P2align:: @code{.p2align @var{abs-expr} , @var{abs-expr}} 2940* Psize:: @code{.psize @var{lines}, @var{columns}} 2941* Quad:: @code{.quad @var{bignums}} 2942* Rept:: @code{.rept @var{count}} 2943* Sbttl:: @code{.sbttl "@var{subheading}"} 2944@ifset COFF 2945* Scl:: @code{.scl @var{class}} 2946@end ifset 2947@ifset COFF 2948* Section:: @code{.section @var{name}, @var{subsection}} 2949@end ifset 2950 2951* Set:: @code{.set @var{symbol}, @var{expression}} 2952* Short:: @code{.short @var{expressions}} 2953* Single:: @code{.single @var{flonums}} 2954@ifset COFF 2955* Size:: @code{.size} 2956@end ifset 2957 2958* Skip:: @code{.skip @var{size} , @var{fill}} 2959* Space:: @code{.space @var{size} , @var{fill}} 2960@ifset have-stabs 2961* Stab:: @code{.stabd, .stabn, .stabs} 2962@end ifset 2963 2964* String:: @code{.string "@var{str}"} 2965@ifset ELF 2966* Symver:: @code{.symver @var{name},@var{name2@@nodename}} 2967@end ifset 2968@ifset COFF 2969* Tag:: @code{.tag @var{structname}} 2970@end ifset 2971 2972* Text:: @code{.text @var{subsection}} 2973* Title:: @code{.title "@var{heading}"} 2974@ifset COFF 2975* Type:: @code{.type @var{int}} 2976* Val:: @code{.val @var{addr}} 2977@end ifset 2978 2979* Word:: @code{.word @var{expressions}} 2980* Deprecated:: Deprecated Directives 2981@end menu 2982 2983@node Abort 2984@section @code{.abort} 2985 2986@cindex @code{abort} directive 2987@cindex stopping the assembly 2988This directive stops the assembly immediately. It is for 2989compatibility with other assemblers. The original idea was that the 2990assembly language source would be piped into the assembler. If the sender 2991of the source quit, it could use this directive tells @code{@value{AS}} to 2992quit also. One day @code{.abort} will not be supported. 2993 2994@ifset COFF 2995@node ABORT 2996@section @code{.ABORT} 2997 2998@cindex @code{ABORT} directive 2999When producing COFF output, @code{@value{AS}} accepts this directive as a 3000synonym for @samp{.abort}. 3001 3002@ifset BOUT 3003When producing @code{b.out} output, @code{@value{AS}} accepts this directive, 3004but ignores it. 3005@end ifset 3006@end ifset 3007 3008@node Align 3009@section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} 3010 3011@cindex padding the location counter 3012@cindex @code{align} directive 3013Pad the location counter (in the current subsection) to a particular storage 3014boundary. The first expression (which must be absolute) is the alignment 3015required, as described below. 3016 3017The second expression (also absolute) gives the fill value to be stored in the 3018padding bytes. It (and the comma) may be omitted. If it is omitted, the 3019padding bytes are normally zero. However, on some systems, if the section is 3020marked as containing code and the fill value is omitted, the space is filled 3021with no-op instructions. 3022 3023The third expression is also absolute, and is also optional. If it is present, 3024it is the maximum number of bytes that should be skipped by this alignment 3025directive. If doing the alignment would require skipping more bytes than the 3026specified maximum, then the alignment is not done at all. You can omit the 3027fill value (the second argument) entirely by simply using two commas after the 3028required alignment; this can be useful if you want the alignment to be filled 3029with no-op instructions when appropriate. 3030 3031The way the required alignment is specified varies from system to system. 3032For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF 3033format, 3034the first expression is the 3035alignment request in bytes. For example @samp{.align 8} advances 3036the location counter until it is a multiple of 8. If the location counter 3037is already a multiple of 8, no change is needed. 3038 3039For other systems, including the i386 using a.out format, it is the 3040number of low-order zero bits the location counter must have after 3041advancement. For example @samp{.align 3} advances the location 3042counter until it a multiple of 8. If the location counter is already a 3043multiple of 8, no change is needed. 3044 3045This inconsistency is due to the different behaviors of the various 3046native assemblers for these systems which GAS must emulate. 3047GAS also provides @code{.balign} and @code{.p2align} directives, 3048described later, which have a consistent behavior across all 3049architectures (but are specific to GAS). 3050 3051@node App-File 3052@section @code{.app-file @var{string}} 3053 3054@cindex logical file name 3055@cindex file name, logical 3056@cindex @code{app-file} directive 3057@code{.app-file} 3058@ifclear no-file-dir 3059(which may also be spelled @samp{.file}) 3060@end ifclear 3061tells @code{@value{AS}} that we are about to start a new 3062logical file. @var{string} is the new file name. In general, the 3063filename is recognized whether or not it is surrounded by quotes @samp{"}; 3064but if you wish to specify an empty file name is permitted, 3065you must give the quotes--@code{""}. This statement may go away in 3066future: it is only recognized to be compatible with old @code{@value{AS}} 3067programs.@refill 3068 3069@node Ascii 3070@section @code{.ascii "@var{string}"}@dots{} 3071 3072@cindex @code{ascii} directive 3073@cindex string literals 3074@code{.ascii} expects zero or more string literals (@pxref{Strings}) 3075separated by commas. It assembles each string (with no automatic 3076trailing zero byte) into consecutive addresses. 3077 3078@node Asciz 3079@section @code{.asciz "@var{string}"}@dots{} 3080 3081@cindex @code{asciz} directive 3082@cindex zero-terminated strings 3083@cindex null-terminated strings 3084@code{.asciz} is just like @code{.ascii}, but each string is followed by 3085a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''. 3086 3087@node Balign 3088@section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} 3089 3090@cindex padding the location counter given number of bytes 3091@cindex @code{balign} directive 3092Pad the location counter (in the current subsection) to a particular 3093storage boundary. The first expression (which must be absolute) is the 3094alignment request in bytes. For example @samp{.balign 8} advances 3095the location counter until it is a multiple of 8. If the location counter 3096is already a multiple of 8, no change is needed. 3097 3098The second expression (also absolute) gives the fill value to be stored in the 3099padding bytes. It (and the comma) may be omitted. If it is omitted, the 3100padding bytes are normally zero. However, on some systems, if the section is 3101marked as containing code and the fill value is omitted, the space is filled 3102with no-op instructions. 3103 3104The third expression is also absolute, and is also optional. If it is present, 3105it is the maximum number of bytes that should be skipped by this alignment 3106directive. If doing the alignment would require skipping more bytes than the 3107specified maximum, then the alignment is not done at all. You can omit the 3108fill value (the second argument) entirely by simply using two commas after the 3109required alignment; this can be useful if you want the alignment to be filled 3110with no-op instructions when appropriate. 3111 3112@cindex @code{balignw} directive 3113@cindex @code{balignl} directive 3114The @code{.balignw} and @code{.balignl} directives are variants of the 3115@code{.balign} directive. The @code{.balignw} directive treats the fill 3116pattern as a two byte word value. The @code{.balignl} directives treats the 3117fill pattern as a four byte longword value. For example, @code{.balignw 31184,0x368d} will align to a multiple of 4. If it skips two bytes, they will be 3119filled in with the value 0x368d (the exact placement of the bytes depends upon 3120the endianness of the processor). If it skips 1 or 3 bytes, the fill value is 3121undefined. 3122 3123@node Byte 3124@section @code{.byte @var{expressions}} 3125 3126@cindex @code{byte} directive 3127@cindex integers, one byte 3128@code{.byte} expects zero or more expressions, separated by commas. 3129Each expression is assembled into the next byte. 3130 3131@node Comm 3132@section @code{.comm @var{symbol} , @var{length} } 3133 3134@cindex @code{comm} directive 3135@cindex symbol, common 3136@code{.comm} declares a common symbol named @var{symbol}. When linking, a 3137common symbol in one object file may be merged with a defined or common symbol 3138of the same name in another object file. If @code{@value{LD}} does not see a 3139definition for the symbol--just one or more common symbols--then it will 3140allocate @var{length} bytes of uninitialized memory. @var{length} must be an 3141absolute expression. If @code{@value{LD}} sees multiple common symbols with 3142the same name, and they do not all have the same size, it will allocate space 3143using the largest size. 3144 3145@ifset ELF 3146When using ELF, the @code{.comm} directive takes an optional third argument. 3147This is the desired alignment of the symbol, specified as a byte boundary (for 3148example, an alignment of 16 means that the least significant 4 bits of the 3149address should be zero). The alignment must be an absolute expression, and it 3150must be a power of two. If @code{@value{LD}} allocates uninitialized memory 3151for the common symbol, it will use the alignment when placing the symbol. If 3152no alignment is specified, @code{@value{AS}} will set the alignment to the 3153largest power of two less than or equal to the size of the symbol, up to a 3154maximum of 16. 3155@end ifset 3156 3157@ifset HPPA 3158The syntax for @code{.comm} differs slightly on the HPPA. The syntax is 3159@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional. 3160@end ifset 3161 3162@node Data 3163@section @code{.data @var{subsection}} 3164 3165@cindex @code{data} directive 3166@code{.data} tells @code{@value{AS}} to assemble the following statements onto the 3167end of the data subsection numbered @var{subsection} (which is an 3168absolute expression). If @var{subsection} is omitted, it defaults 3169to zero. 3170 3171@ifset COFF 3172@node Def 3173@section @code{.def @var{name}} 3174 3175@cindex @code{def} directive 3176@cindex COFF symbols, debugging 3177@cindex debugging COFF symbols 3178Begin defining debugging information for a symbol @var{name}; the 3179definition extends until the @code{.endef} directive is encountered. 3180@ifset BOUT 3181 3182This directive is only observed when @code{@value{AS}} is configured for COFF 3183format output; when producing @code{b.out}, @samp{.def} is recognized, 3184but ignored. 3185@end ifset 3186@end ifset 3187 3188@ifset aout-bout 3189@node Desc 3190@section @code{.desc @var{symbol}, @var{abs-expression}} 3191 3192@cindex @code{desc} directive 3193@cindex COFF symbol descriptor 3194@cindex symbol descriptor, COFF 3195This directive sets the descriptor of the symbol (@pxref{Symbol Attributes}) 3196to the low 16 bits of an absolute expression. 3197 3198@ifset COFF 3199The @samp{.desc} directive is not available when @code{@value{AS}} is 3200configured for COFF output; it is only for @code{a.out} or @code{b.out} 3201object format. For the sake of compatibility, @code{@value{AS}} accepts 3202it, but produces no output, when configured for COFF. 3203@end ifset 3204@end ifset 3205 3206@ifset COFF 3207@node Dim 3208@section @code{.dim} 3209 3210@cindex @code{dim} directive 3211@cindex COFF auxiliary symbol information 3212@cindex auxiliary symbol information, COFF 3213This directive is generated by compilers to include auxiliary debugging 3214information in the symbol table. It is only permitted inside 3215@code{.def}/@code{.endef} pairs. 3216@ifset BOUT 3217 3218@samp{.dim} is only meaningful when generating COFF format output; when 3219@code{@value{AS}} is generating @code{b.out}, it accepts this directive but 3220ignores it. 3221@end ifset 3222@end ifset 3223 3224@node Double 3225@section @code{.double @var{flonums}} 3226 3227@cindex @code{double} directive 3228@cindex floating point numbers (double) 3229@code{.double} expects zero or more flonums, separated by commas. It 3230assembles floating point numbers. 3231@ifset GENERIC 3232The exact kind of floating point numbers emitted depends on how 3233@code{@value{AS}} is configured. @xref{Machine Dependencies}. 3234@end ifset 3235@ifclear GENERIC 3236@ifset IEEEFLOAT 3237On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers 3238in @sc{ieee} format. 3239@end ifset 3240@end ifclear 3241 3242@node Eject 3243@section @code{.eject} 3244 3245@cindex @code{eject} directive 3246@cindex new page, in listings 3247@cindex page, in listings 3248@cindex listing control: new page 3249Force a page break at this point, when generating assembly listings. 3250 3251@node Else 3252@section @code{.else} 3253 3254@cindex @code{else} directive 3255@code{.else} is part of the @code{@value{AS}} support for conditional 3256assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section 3257of code to be assembled if the condition for the preceding @code{.if} 3258was false. 3259 3260@ignore 3261@node End, Endef, Else, Pseudo Ops 3262@section @code{.end} 3263 3264@cindex @code{end} directive 3265This doesn't do anything---but isn't an s_ignore, so I suspect it's 3266meant to do something eventually (which is why it isn't documented here 3267as "for compatibility with blah"). 3268@end ignore 3269 3270@ifset COFF 3271@node Endef 3272@section @code{.endef} 3273 3274@cindex @code{endef} directive 3275This directive flags the end of a symbol definition begun with 3276@code{.def}. 3277@ifset BOUT 3278 3279@samp{.endef} is only meaningful when generating COFF format output; if 3280@code{@value{AS}} is configured to generate @code{b.out}, it accepts this 3281directive but ignores it. 3282@end ifset 3283@end ifset 3284 3285@node Endif 3286@section @code{.endif} 3287 3288@cindex @code{endif} directive 3289@code{.endif} is part of the @code{@value{AS}} support for conditional assembly; 3290it marks the end of a block of code that is only assembled 3291conditionally. @xref{If,,@code{.if}}. 3292 3293@node Equ 3294@section @code{.equ @var{symbol}, @var{expression}} 3295 3296@cindex @code{equ} directive 3297@cindex assigning values to symbols 3298@cindex symbols, assigning values to 3299This directive sets the value of @var{symbol} to @var{expression}. 3300It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}. 3301 3302@ifset HPPA 3303The syntax for @code{equ} on the HPPA is 3304@samp{@var{symbol} .equ @var{expression}}. 3305@end ifset 3306 3307@node Equiv 3308@section @code{.equiv @var{symbol}, @var{expression}} 3309@cindex @code{equiv} directive 3310The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that 3311the assembler will signal an error if @var{symbol} is already defined. 3312 3313Except for the contents of the error message, this is roughly equivalent to 3314@smallexample 3315.ifdef SYM 3316.err 3317.endif 3318.equ SYM,VAL 3319@end smallexample 3320 3321@node Err 3322@section @code{.err} 3323@cindex @code{err} directive 3324If @code{@value{AS}} assembles a @code{.err} directive, it will print an error 3325message and, unless the @code{-Z} option was used, it will not generate an 3326object file. This can be used to signal error an conditionally compiled code. 3327 3328@node Extern 3329@section @code{.extern} 3330 3331@cindex @code{extern} directive 3332@code{.extern} is accepted in the source program---for compatibility 3333with other assemblers---but it is ignored. @code{@value{AS}} treats 3334all undefined symbols as external. 3335 3336@ifclear no-file-dir 3337@node File 3338@section @code{.file @var{string}} 3339 3340@cindex @code{file} directive 3341@cindex logical file name 3342@cindex file name, logical 3343@code{.file} (which may also be spelled @samp{.app-file}) tells 3344@code{@value{AS}} that we are about to start a new logical file. 3345@var{string} is the new file name. In general, the filename is 3346recognized whether or not it is surrounded by quotes @samp{"}; but if 3347you wish to specify an empty file name, you must give the 3348quotes--@code{""}. This statement may go away in future: it is only 3349recognized to be compatible with old @code{@value{AS}} programs. 3350@ifset A29K 3351In some configurations of @code{@value{AS}}, @code{.file} has already been 3352removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}. 3353@end ifset 3354@end ifclear 3355 3356@node Fill 3357@section @code{.fill @var{repeat} , @var{size} , @var{value}} 3358 3359@cindex @code{fill} directive 3360@cindex writing patterns in memory 3361@cindex patterns, writing in memory 3362@var{result}, @var{size} and @var{value} are absolute expressions. 3363This emits @var{repeat} copies of @var{size} bytes. @var{Repeat} 3364may be zero or more. @var{Size} may be zero or more, but if it is 3365more than 8, then it is deemed to have the value 8, compatible with 3366other people's assemblers. The contents of each @var{repeat} bytes 3367is taken from an 8-byte number. The highest order 4 bytes are 3368zero. The lowest order 4 bytes are @var{value} rendered in the 3369byte-order of an integer on the computer @code{@value{AS}} is assembling for. 3370Each @var{size} bytes in a repetition is taken from the lowest order 3371@var{size} bytes of this number. Again, this bizarre behavior is 3372compatible with other people's assemblers. 3373 3374@var{size} and @var{value} are optional. 3375If the second comma and @var{value} are absent, @var{value} is 3376assumed zero. If the first comma and following tokens are absent, 3377@var{size} is assumed to be 1. 3378 3379@node Float 3380@section @code{.float @var{flonums}} 3381 3382@cindex floating point numbers (single) 3383@cindex @code{float} directive 3384This directive assembles zero or more flonums, separated by commas. It 3385has the same effect as @code{.single}. 3386@ifset GENERIC 3387The exact kind of floating point numbers emitted depends on how 3388@code{@value{AS}} is configured. 3389@xref{Machine Dependencies}. 3390@end ifset 3391@ifclear GENERIC 3392@ifset IEEEFLOAT 3393On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers 3394in @sc{ieee} format. 3395@end ifset 3396@end ifclear 3397 3398@node Global 3399@section @code{.global @var{symbol}}, @code{.globl @var{symbol}} 3400 3401@cindex @code{global} directive 3402@cindex symbol, making visible to linker 3403@code{.global} makes the symbol visible to @code{@value{LD}}. If you define 3404@var{symbol} in your partial program, its value is made available to 3405other partial programs that are linked with it. Otherwise, 3406@var{symbol} takes its attributes from a symbol of the same name 3407from another file linked into the same program. 3408 3409Both spellings (@samp{.globl} and @samp{.global}) are accepted, for 3410compatibility with other assemblers. 3411 3412@ifset HPPA 3413On the HPPA, @code{.global} is not always enough to make it accessible to other 3414partial programs. You may need the HPPA-only @code{.EXPORT} directive as well. 3415@xref{HPPA Directives,, HPPA Assembler Directives}. 3416@end ifset 3417 3418@node hword 3419@section @code{.hword @var{expressions}} 3420 3421@cindex @code{hword} directive 3422@cindex integers, 16-bit 3423@cindex numbers, 16-bit 3424@cindex sixteen bit integers 3425This expects zero or more @var{expressions}, and emits 3426a 16 bit number for each. 3427 3428@ifset GENERIC 3429This directive is a synonym for @samp{.short}; depending on the target 3430architecture, it may also be a synonym for @samp{.word}. 3431@end ifset 3432@ifclear GENERIC 3433@ifset W32 3434This directive is a synonym for @samp{.short}. 3435@end ifset 3436@ifset W16 3437This directive is a synonym for both @samp{.short} and @samp{.word}. 3438@end ifset 3439@end ifclear 3440 3441@node Ident 3442@section @code{.ident} 3443 3444@cindex @code{ident} directive 3445This directive is used by some assemblers to place tags in object files. 3446@code{@value{AS}} simply accepts the directive for source-file 3447compatibility with such assemblers, but does not actually emit anything 3448for it. 3449 3450@node If 3451@section @code{.if @var{absolute expression}} 3452 3453@cindex conditional assembly 3454@cindex @code{if} directive 3455@code{.if} marks the beginning of a section of code which is only 3456considered part of the source program being assembled if the argument 3457(which must be an @var{absolute expression}) is non-zero. The end of 3458the conditional section of code must be marked by @code{.endif} 3459(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the 3460alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}). 3461 3462The following variants of @code{.if} are also supported: 3463@table @code 3464@cindex @code{ifdef} directive 3465@item .ifdef @var{symbol} 3466Assembles the following section of code if the specified @var{symbol} 3467has been defined. 3468 3469@ignore 3470@cindex @code{ifeqs} directive 3471@item .ifeqs 3472Not yet implemented. 3473@end ignore 3474 3475@cindex @code{ifndef} directive 3476@cindex @code{ifnotdef} directive 3477@item .ifndef @var{symbol} 3478@itemx .ifnotdef @var{symbol} 3479Assembles the following section of code if the specified @var{symbol} 3480has not been defined. Both spelling variants are equivalent. 3481 3482@ignore 3483@item ifnes 3484Not yet implemented. 3485@end ignore 3486@end table 3487 3488@node Include 3489@section @code{.include "@var{file}"} 3490 3491@cindex @code{include} directive 3492@cindex supporting files, including 3493@cindex files, including 3494This directive provides a way to include supporting files at specified 3495points in your source program. The code from @var{file} is assembled as 3496if it followed the point of the @code{.include}; when the end of the 3497included file is reached, assembly of the original file continues. You 3498can control the search paths used with the @samp{-I} command-line option 3499(@pxref{Invoking,,Command-Line Options}). Quotation marks are required 3500around @var{file}. 3501 3502@node Int 3503@section @code{.int @var{expressions}} 3504 3505@cindex @code{int} directive 3506@cindex integers, 32-bit 3507Expect zero or more @var{expressions}, of any section, separated by commas. 3508For each expression, emit a number that, at run time, is the value of that 3509expression. The byte order and bit size of the number depends on what kind 3510of target the assembly is for. 3511 3512@ifclear GENERIC 3513@ifset H8 3514On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit 3515integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits 351632-bit integers. 3517@end ifset 3518@end ifclear 3519 3520@node Irp 3521@section @code{.irp @var{symbol},@var{values}}@dots{} 3522 3523@cindex @code{irp} directive 3524Evaluate a sequence of statements assigning different values to @var{symbol}. 3525The sequence of statements starts at the @code{.irp} directive, and is 3526terminated by an @code{.endr} directive. For each @var{value}, @var{symbol} is 3527set to @var{value}, and the sequence of statements is assembled. If no 3528@var{value} is listed, the sequence of statements is assembled once, with 3529@var{symbol} set to the null string. To refer to @var{symbol} within the 3530sequence of statements, use @var{\symbol}. 3531 3532For example, assembling 3533 3534@example 3535 .irp param,1,2,3 3536 move d\param,sp@@- 3537 .endr 3538@end example 3539 3540is equivalent to assembling 3541 3542@example 3543 move d1,sp@@- 3544 move d2,sp@@- 3545 move d3,sp@@- 3546@end example 3547 3548@node Irpc 3549@section @code{.irpc @var{symbol},@var{values}}@dots{} 3550 3551@cindex @code{irpc} directive 3552Evaluate a sequence of statements assigning different values to @var{symbol}. 3553The sequence of statements starts at the @code{.irpc} directive, and is 3554terminated by an @code{.endr} directive. For each character in @var{value}, 3555@var{symbol} is set to the character, and the sequence of statements is 3556assembled. If no @var{value} is listed, the sequence of statements is 3557assembled once, with @var{symbol} set to the null string. To refer to 3558@var{symbol} within the sequence of statements, use @var{\symbol}. 3559 3560For example, assembling 3561 3562@example 3563 .irpc param,123 3564 move d\param,sp@@- 3565 .endr 3566@end example 3567 3568is equivalent to assembling 3569 3570@example 3571 move d1,sp@@- 3572 move d2,sp@@- 3573 move d3,sp@@- 3574@end example 3575 3576@node Lcomm 3577@section @code{.lcomm @var{symbol} , @var{length}} 3578 3579@cindex @code{lcomm} directive 3580@cindex local common symbols 3581@cindex symbols, local common 3582Reserve @var{length} (an absolute expression) bytes for a local common 3583denoted by @var{symbol}. The section and value of @var{symbol} are 3584those of the new local common. The addresses are allocated in the bss 3585section, so that at run-time the bytes start off zeroed. @var{Symbol} 3586is not declared global (@pxref{Global,,@code{.global}}), so is normally 3587not visible to @code{@value{LD}}. 3588 3589@ifset GENERIC 3590Some targets permit a third argument to be used with @code{.lcomm}. This 3591argument specifies the desired alignment of the symbol in the bss section. 3592@end ifset 3593 3594@ifset HPPA 3595The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is 3596@samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional. 3597@end ifset 3598 3599@node Lflags 3600@section @code{.lflags} 3601 3602@cindex @code{lflags} directive (ignored) 3603@code{@value{AS}} accepts this directive, for compatibility with other 3604assemblers, but ignores it. 3605 3606@ifclear no-line-dir 3607@node Line 3608@section @code{.line @var{line-number}} 3609 3610@cindex @code{line} directive 3611@end ifclear 3612@ifset no-line-dir 3613@node Ln 3614@section @code{.ln @var{line-number}} 3615 3616@cindex @code{ln} directive 3617@end ifset 3618@cindex logical line number 3619@ifset aout-bout 3620Change the logical line number. @var{line-number} must be an absolute 3621expression. The next line has that logical line number. Therefore any other 3622statements on the current line (after a statement separator character) are 3623reported as on logical line number @var{line-number} @minus{} 1. One day 3624@code{@value{AS}} will no longer support this directive: it is recognized only 3625for compatibility with existing assembler programs. 3626 3627@ifset GENERIC 3628@ifset A29K 3629@emph{Warning:} In the AMD29K configuration of @value{AS}, this command is 3630not available; use the synonym @code{.ln} in that context. 3631@end ifset 3632@end ifset 3633@end ifset 3634 3635@ifclear no-line-dir 3636Even though this is a directive associated with the @code{a.out} or 3637@code{b.out} object-code formats, @code{@value{AS}} still recognizes it 3638when producing COFF output, and treats @samp{.line} as though it 3639were the COFF @samp{.ln} @emph{if} it is found outside a 3640@code{.def}/@code{.endef} pair. 3641 3642Inside a @code{.def}, @samp{.line} is, instead, one of the directives 3643used by compilers to generate auxiliary symbol information for 3644debugging. 3645@end ifclear 3646 3647@node Linkonce 3648@section @code{.linkonce [@var{type}]} 3649@cindex COMDAT 3650@cindex @code{linkonce} directive 3651@cindex common sections 3652Mark the current section so that the linker only includes a single copy of it. 3653This may be used to include the same section in several different object files, 3654but ensure that the linker will only include it once in the final output file. 3655The @code{.linkonce} pseudo-op must be used for each instance of the section. 3656Duplicate sections are detected based on the section name, so it should be 3657unique. 3658 3659This directive is only supported by a few object file formats; as of this 3660writing, the only object file format which supports it is the Portable 3661Executable format used on Windows NT. 3662 3663The @var{type} argument is optional. If specified, it must be one of the 3664following strings. For example: 3665@smallexample 3666.linkonce same_size 3667@end smallexample 3668Not all types may be supported on all object file formats. 3669 3670@table @code 3671@item discard 3672Silently discard duplicate sections. This is the default. 3673 3674@item one_only 3675Warn if there are duplicate sections, but still keep only one copy. 3676 3677@item same_size 3678Warn if any of the duplicates have different sizes. 3679 3680@item same_contents 3681Warn if any of the duplicates do not have exactly the same contents. 3682@end table 3683 3684@node Ln 3685@section @code{.ln @var{line-number}} 3686 3687@cindex @code{ln} directive 3688@ifclear no-line-dir 3689@samp{.ln} is a synonym for @samp{.line}. 3690@end ifclear 3691@ifset no-line-dir 3692Tell @code{@value{AS}} to change the logical line number. @var{line-number} 3693must be an absolute expression. The next line has that logical 3694line number, so any other statements on the current line (after a 3695statement separator character @code{;}) are reported as on logical 3696line number @var{line-number} @minus{} 1. 3697@ifset BOUT 3698 3699This directive is accepted, but ignored, when @code{@value{AS}} is 3700configured for @code{b.out}; its effect is only associated with COFF 3701output format. 3702@end ifset 3703@end ifset 3704 3705@node MRI 3706@section @code{.mri @var{val}} 3707 3708@cindex @code{mri} directive 3709@cindex MRI mode, temporarily 3710If @var{val} is non-zero, this tells @code{@value{AS}} to enter MRI mode. If 3711@var{val} is zero, this tells @code{@value{AS}} to exit MRI mode. This change 3712affects code assembled until the next @code{.mri} directive, or until the end 3713of the file. @xref{M, MRI mode, MRI mode}. 3714 3715@node List 3716@section @code{.list} 3717 3718@cindex @code{list} directive 3719@cindex listing control, turning on 3720Control (in conjunction with the @code{.nolist} directive) whether or 3721not assembly listings are generated. These two directives maintain an 3722internal counter (which is zero initially). @code{.list} increments the 3723counter, and @code{.nolist} decrements it. Assembly listings are 3724generated whenever the counter is greater than zero. 3725 3726By default, listings are disabled. When you enable them (with the 3727@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}), 3728the initial value of the listing counter is one. 3729 3730@node Long 3731@section @code{.long @var{expressions}} 3732 3733@cindex @code{long} directive 3734@code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}. 3735 3736@ignore 3737@c no one seems to know what this is for or whether this description is 3738@c what it really ought to do 3739@node Lsym 3740@section @code{.lsym @var{symbol}, @var{expression}} 3741 3742@cindex @code{lsym} directive 3743@cindex symbol, not referenced in assembly 3744@code{.lsym} creates a new symbol named @var{symbol}, but does not put it in 3745the hash table, ensuring it cannot be referenced by name during the 3746rest of the assembly. This sets the attributes of the symbol to be 3747the same as the expression value: 3748@smallexample 3749@var{other} = @var{descriptor} = 0 3750@var{type} = @r{(section of @var{expression})} 3751@var{value} = @var{expression} 3752@end smallexample 3753@noindent 3754The new symbol is not flagged as external. 3755@end ignore 3756 3757@node Macro 3758@section @code{.macro} 3759 3760@cindex macros 3761The commands @code{.macro} and @code{.endm} allow you to define macros that 3762generate assembly output. For example, this definition specifies a macro 3763@code{sum} that puts a sequence of numbers into memory: 3764 3765@example 3766 .macro sum from=0, to=5 3767 .long \from 3768 .if \to-\from 3769 sum "(\from+1)",\to 3770 .endif 3771 .endm 3772@end example 3773 3774@noindent 3775With that definition, @samp{SUM 0,5} is equivalent to this assembly input: 3776 3777@example 3778 .long 0 3779 .long 1 3780 .long 2 3781 .long 3 3782 .long 4 3783 .long 5 3784@end example 3785 3786@ftable @code 3787@item .macro @var{macname} 3788@itemx .macro @var{macname} @var{macargs} @dots{} 3789@cindex @code{macro} directive 3790Begin the definition of a macro called @var{macname}. If your macro 3791definition requires arguments, specify their names after the macro name, 3792separated by commas or spaces. You can supply a default value for any 3793macro argument by following the name with @samp{=@var{deflt}}. For 3794example, these are all valid @code{.macro} statements: 3795 3796@table @code 3797@item .macro comm 3798Begin the definition of a macro called @code{comm}, which takes no 3799arguments. 3800 3801@item .macro plus1 p, p1 3802@itemx .macro plus1 p p1 3803Either statement begins the definition of a macro called @code{plus1}, 3804which takes two arguments; within the macro definition, write 3805@samp{\p} or @samp{\p1} to evaluate the arguments. 3806 3807@item .macro reserve_str p1=0 p2 3808Begin the definition of a macro called @code{reserve_str}, with two 3809arguments. The first argument has a default value, but not the second. 3810After the definition is complete, you can call the macro either as 3811@samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to 3812@var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str 3813,@var{b}} (with @samp{\p1} evaluating as the default, in this case 3814@samp{0}, and @samp{\p2} evaluating to @var{b}). 3815@end table 3816 3817When you call a macro, you can specify the argument values either by 3818position, or by keyword. For example, @samp{sum 9,17} is equivalent to 3819@samp{sum to=17, from=9}. 3820 3821@item .endm 3822@cindex @code{endm} directive 3823Mark the end of a macro definition. 3824 3825@item .exitm 3826@cindex @code{exitm} directive 3827Exit early from the current macro definition. 3828 3829@cindex number of macros executed 3830@cindex macros, count executed 3831@item \@@ 3832@code{@value{AS}} maintains a counter of how many macros it has 3833executed in this pseudo-variable; you can copy that number to your 3834output with @samp{\@@}, but @emph{only within a macro definition}. 3835 3836@ignore 3837@item LOCAL @var{name} [ , @dots{} ] 3838@emph{Warning: @code{LOCAL} is only available if you select ``alternate 3839macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,, 3840Alternate macro syntax}. 3841 3842Generate a string replacement for each of the @var{name} arguments, and 3843replace any instances of @var{name} in each macro expansion. The 3844replacement string is unique in the assembly, and different for each 3845separate macro expansion. @code{LOCAL} allows you to write macros that 3846define symbols, without fear of conflict between separate macro expansions. 3847@end ignore 3848@end ftable 3849 3850@node Nolist 3851@section @code{.nolist} 3852 3853@cindex @code{nolist} directive 3854@cindex listing control, turning off 3855Control (in conjunction with the @code{.list} directive) whether or 3856not assembly listings are generated. These two directives maintain an 3857internal counter (which is zero initially). @code{.list} increments the 3858counter, and @code{.nolist} decrements it. Assembly listings are 3859generated whenever the counter is greater than zero. 3860 3861@node Octa 3862@section @code{.octa @var{bignums}} 3863 3864@c FIXME: double size emitted for "octa" on i960, others? Or warn? 3865@cindex @code{octa} directive 3866@cindex integer, 16-byte 3867@cindex sixteen byte integer 3868This directive expects zero or more bignums, separated by commas. For each 3869bignum, it emits a 16-byte integer. 3870 3871The term ``octa'' comes from contexts in which a ``word'' is two bytes; 3872hence @emph{octa}-word for 16 bytes. 3873 3874@node Org 3875@section @code{.org @var{new-lc} , @var{fill}} 3876 3877@cindex @code{org} directive 3878@cindex location counter, advancing 3879@cindex advancing location counter 3880@cindex current address, advancing 3881Advance the location counter of the current section to 3882@var{new-lc}. @var{new-lc} is either an absolute expression or an 3883expression with the same section as the current subsection. That is, 3884you can't use @code{.org} to cross sections: if @var{new-lc} has the 3885wrong section, the @code{.org} directive is ignored. To be compatible 3886with former assemblers, if the section of @var{new-lc} is absolute, 3887@code{@value{AS}} issues a warning, then pretends the section of @var{new-lc} 3888is the same as the current subsection. 3889 3890@code{.org} may only increase the location counter, or leave it 3891unchanged; you cannot use @code{.org} to move the location counter 3892backwards. 3893 3894@c double negative used below "not undefined" because this is a specific 3895@c reference to "undefined" (as SEG_UNKNOWN is called in this manual) 3896@c section. doc@cygnus.com 18feb91 3897Because @code{@value{AS}} tries to assemble programs in one pass, @var{new-lc} 3898may not be undefined. If you really detest this restriction we eagerly await 3899a chance to share your improved assembler. 3900 3901Beware that the origin is relative to the start of the section, not 3902to the start of the subsection. This is compatible with other 3903people's assemblers. 3904 3905When the location counter (of the current subsection) is advanced, the 3906intervening bytes are filled with @var{fill} which should be an 3907absolute expression. If the comma and @var{fill} are omitted, 3908@var{fill} defaults to zero. 3909 3910@node P2align 3911@section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} 3912 3913@cindex padding the location counter given a power of two 3914@cindex @code{p2align} directive 3915Pad the location counter (in the current subsection) to a particular 3916storage boundary. The first expression (which must be absolute) is the 3917number of low-order zero bits the location counter must have after 3918advancement. For example @samp{.p2align 3} advances the location 3919counter until it a multiple of 8. If the location counter is already a 3920multiple of 8, no change is needed. 3921 3922The second expression (also absolute) gives the fill value to be stored in the 3923padding bytes. It (and the comma) may be omitted. If it is omitted, the 3924padding bytes are normally zero. However, on some systems, if the section is 3925marked as containing code and the fill value is omitted, the space is filled 3926with no-op instructions. 3927 3928The third expression is also absolute, and is also optional. If it is present, 3929it is the maximum number of bytes that should be skipped by this alignment 3930directive. If doing the alignment would require skipping more bytes than the 3931specified maximum, then the alignment is not done at all. You can omit the 3932fill value (the second argument) entirely by simply using two commas after the 3933required alignment; this can be useful if you want the alignment to be filled 3934with no-op instructions when appropriate. 3935 3936@cindex @code{p2alignw} directive 3937@cindex @code{p2alignl} directive 3938The @code{.p2alignw} and @code{.p2alignl} directives are variants of the 3939@code{.p2align} directive. The @code{.p2alignw} directive treats the fill 3940pattern as a two byte word value. The @code{.p2alignl} directives treats the 3941fill pattern as a four byte longword value. For example, @code{.p2alignw 39422,0x368d} will align to a multiple of 4. If it skips two bytes, they will be 3943filled in with the value 0x368d (the exact placement of the bytes depends upon 3944the endianness of the processor). If it skips 1 or 3 bytes, the fill value is 3945undefined. 3946 3947@node Psize 3948@section @code{.psize @var{lines} , @var{columns}} 3949 3950@cindex @code{psize} directive 3951@cindex listing control: paper size 3952@cindex paper size, for listings 3953Use this directive to declare the number of lines---and, optionally, the 3954number of columns---to use for each page, when generating listings. 3955 3956If you do not use @code{.psize}, listings use a default line-count 3957of 60. You may omit the comma and @var{columns} specification; the 3958default width is 200 columns. 3959 3960@code{@value{AS}} generates formfeeds whenever the specified number of 3961lines is exceeded (or whenever you explicitly request one, using 3962@code{.eject}). 3963 3964If you specify @var{lines} as @code{0}, no formfeeds are generated save 3965those explicitly specified with @code{.eject}. 3966 3967@node Quad 3968@section @code{.quad @var{bignums}} 3969 3970@cindex @code{quad} directive 3971@code{.quad} expects zero or more bignums, separated by commas. For 3972each bignum, it emits 3973@ifclear bignum-16 3974an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a 3975warning message; and just takes the lowest order 8 bytes of the bignum. 3976@cindex eight-byte integer 3977@cindex integer, 8-byte 3978 3979The term ``quad'' comes from contexts in which a ``word'' is two bytes; 3980hence @emph{quad}-word for 8 bytes. 3981@end ifclear 3982@ifset bignum-16 3983a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a 3984warning message; and just takes the lowest order 16 bytes of the bignum. 3985@cindex sixteen-byte integer 3986@cindex integer, 16-byte 3987@end ifset 3988 3989@node Rept 3990@section @code{.rept @var{count}} 3991 3992@cindex @code{rept} directive 3993Repeat the sequence of lines between the @code{.rept} directive and the next 3994@code{.endr} directive @var{count} times. 3995 3996For example, assembling 3997 3998@example 3999 .rept 3 4000 .long 0 4001 .endr 4002@end example 4003 4004is equivalent to assembling 4005 4006@example 4007 .long 0 4008 .long 0 4009 .long 0 4010@end example 4011 4012@node Sbttl 4013@section @code{.sbttl "@var{subheading}"} 4014 4015@cindex @code{sbttl} directive 4016@cindex subtitles for listings 4017@cindex listing control: subtitle 4018Use @var{subheading} as the title (third line, immediately after the 4019title line) when generating assembly listings. 4020 4021This directive affects subsequent pages, as well as the current page if 4022it appears within ten lines of the top of a page. 4023 4024@ifset COFF 4025@node Scl 4026@section @code{.scl @var{class}} 4027 4028@cindex @code{scl} directive 4029@cindex symbol storage class (COFF) 4030@cindex COFF symbol storage class 4031Set the storage-class value for a symbol. This directive may only be 4032used inside a @code{.def}/@code{.endef} pair. Storage class may flag 4033whether a symbol is static or external, or it may record further 4034symbolic debugging information. 4035@ifset BOUT 4036 4037The @samp{.scl} directive is primarily associated with COFF output; when 4038configured to generate @code{b.out} output format, @code{@value{AS}} 4039accepts this directive but ignores it. 4040@end ifset 4041@end ifset 4042 4043@node Section 4044@section @code{.section @var{name}} 4045 4046@cindex @code{section} directive 4047@cindex named section 4048Use the @code{.section} directive to assemble the following code into a section 4049named @var{name}. 4050 4051This directive is only supported for targets that actually support arbitrarily 4052named sections; on @code{a.out} targets, for example, it is not accepted, even 4053with a standard @code{a.out} section name. 4054 4055@ifset COFF 4056For COFF targets, the @code{.section} directive is used in one of the following 4057ways: 4058@smallexample 4059.section @var{name}[, "@var{flags}"] 4060.section @var{name}[, @var{subsegment}] 4061@end smallexample 4062 4063If the optional argument is quoted, it is taken as flags to use for the 4064section. Each flag is a single character. The following flags are recognized: 4065@table @code 4066@item b 4067bss section (uninitialized data) 4068@item n 4069section is not loaded 4070@item w 4071writable section 4072@item d 4073data section 4074@item r 4075read-only section 4076@item x 4077executable section 4078@end table 4079 4080If no flags are specified, the default flags depend upon the section name. If 4081the section name is not recognized, the default will be for the section to be 4082loaded and writable. 4083 4084If the optional argument to the @code{.section} directive is not quoted, it is 4085taken as a subsegment number (@pxref{Sub-Sections}). 4086@end ifset 4087 4088@ifset ELF 4089For ELF targets, the @code{.section} directive is used like this: 4090@smallexample 4091.section @var{name}[, "@var{flags}"[, @@@var{type}]] 4092@end smallexample 4093The optional @var{flags} argument is a quoted string which may contain any 4094combintion of the following characters: 4095@table @code 4096@item a 4097section is allocatable 4098@item w 4099section is writable 4100@item x 4101section is executable 4102@end table 4103 4104The optional @var{type} argument may contain one of the following constants: 4105@table @code 4106@item @@progbits 4107section contains data 4108@item @@nobits 4109section does not contain data (i.e., section only occupies space) 4110@end table 4111 4112If no flags are specified, the default flags depend upon the section name. If 4113the section name is not recognized, the default will be for the section to have 4114none of the above flags: it will not be allocated in memory, nor writable, nor 4115executable. The section will contain data. 4116 4117For ELF targets, the assembler supports another type of @code{.section} 4118directive for compatibility with the Solaris assembler: 4119@smallexample 4120.section "@var{name}"[, @var{flags}...] 4121@end smallexample 4122Note that the section name is quoted. There may be a sequence of comma 4123separated flags: 4124@table @code 4125@item #alloc 4126section is allocatable 4127@item #write 4128section is writable 4129@item #execinstr 4130section is executable 4131@end table 4132@end ifset 4133 4134@node Set 4135@section @code{.set @var{symbol}, @var{expression}} 4136 4137@cindex @code{set} directive 4138@cindex symbol value, setting 4139Set the value of @var{symbol} to @var{expression}. This 4140changes @var{symbol}'s value and type to conform to 4141@var{expression}. If @var{symbol} was flagged as external, it remains 4142flagged (@pxref{Symbol Attributes}). 4143 4144You may @code{.set} a symbol many times in the same assembly. 4145 4146If you @code{.set} a global symbol, the value stored in the object 4147file is the last value stored into it. 4148 4149@ifset HPPA 4150The syntax for @code{set} on the HPPA is 4151@samp{@var{symbol} .set @var{expression}}. 4152@end ifset 4153 4154@node Short 4155@section @code{.short @var{expressions}} 4156 4157@cindex @code{short} directive 4158@ifset GENERIC 4159@code{.short} is normally the same as @samp{.word}. 4160@xref{Word,,@code{.word}}. 4161 4162In some configurations, however, @code{.short} and @code{.word} generate 4163numbers of different lengths; @pxref{Machine Dependencies}. 4164@end ifset 4165@ifclear GENERIC 4166@ifset W16 4167@code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}. 4168@end ifset 4169@ifset W32 4170This expects zero or more @var{expressions}, and emits 4171a 16 bit number for each. 4172@end ifset 4173@end ifclear 4174 4175@node Single 4176@section @code{.single @var{flonums}} 4177 4178@cindex @code{single} directive 4179@cindex floating point numbers (single) 4180This directive assembles zero or more flonums, separated by commas. It 4181has the same effect as @code{.float}. 4182@ifset GENERIC 4183The exact kind of floating point numbers emitted depends on how 4184@code{@value{AS}} is configured. @xref{Machine Dependencies}. 4185@end ifset 4186@ifclear GENERIC 4187@ifset IEEEFLOAT 4188On the @value{TARGET} family, @code{.single} emits 32-bit floating point 4189numbers in @sc{ieee} format. 4190@end ifset 4191@end ifclear 4192 4193@ifset COFF 4194@node Size 4195@section @code{.size} 4196 4197@cindex @code{size} directive 4198This directive is generated by compilers to include auxiliary debugging 4199information in the symbol table. It is only permitted inside 4200@code{.def}/@code{.endef} pairs. 4201@ifset BOUT 4202 4203@samp{.size} is only meaningful when generating COFF format output; when 4204@code{@value{AS}} is generating @code{b.out}, it accepts this directive but 4205ignores it. 4206@end ifset 4207@end ifset 4208 4209@ifclear no-space-dir 4210@node Skip 4211@section @code{.skip @var{size} , @var{fill}} 4212 4213@cindex @code{skip} directive 4214@cindex filling memory 4215This directive emits @var{size} bytes, each of value @var{fill}. Both 4216@var{size} and @var{fill} are absolute expressions. If the comma and 4217@var{fill} are omitted, @var{fill} is assumed to be zero. This is the same as 4218@samp{.space}. 4219 4220@node Space 4221@section @code{.space @var{size} , @var{fill}} 4222 4223@cindex @code{space} directive 4224@cindex filling memory 4225This directive emits @var{size} bytes, each of value @var{fill}. Both 4226@var{size} and @var{fill} are absolute expressions. If the comma 4227and @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same 4228as @samp{.skip}. 4229 4230@ifset HPPA 4231@quotation 4232@emph{Warning:} @code{.space} has a completely different meaning for HPPA 4233targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800 4234Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the 4235@code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives}, 4236for a summary. 4237@end quotation 4238@end ifset 4239@end ifclear 4240 4241@ifset A29K 4242@ifclear GENERIC 4243@node Space 4244@section @code{.space} 4245@cindex @code{space} directive 4246@end ifclear 4247On the AMD 29K, this directive is ignored; it is accepted for 4248compatibility with other AMD 29K assemblers. 4249 4250@quotation 4251@emph{Warning:} In most versions of the @sc{gnu} assembler, the directive 4252@code{.space} has the effect of @code{.block} @xref{Machine Dependencies}. 4253@end quotation 4254@end ifset 4255 4256@ifset have-stabs 4257@node Stab 4258@section @code{.stabd, .stabn, .stabs} 4259 4260@cindex symbolic debuggers, information for 4261@cindex @code{stab@var{x}} directives 4262There are three directives that begin @samp{.stab}. 4263All emit symbols (@pxref{Symbols}), for use by symbolic debuggers. 4264The symbols are not entered in the @code{@value{AS}} hash table: they 4265cannot be referenced elsewhere in the source file. 4266Up to five fields are required: 4267 4268@table @var 4269@item string 4270This is the symbol's name. It may contain any character except 4271@samp{\000}, so is more general than ordinary symbol names. Some 4272debuggers used to code arbitrarily complex structures into symbol names 4273using this field. 4274 4275@item type 4276An absolute expression. The symbol's type is set to the low 8 bits of 4277this expression. Any bit pattern is permitted, but @code{@value{LD}} 4278and debuggers choke on silly bit patterns. 4279 4280@item other 4281An absolute expression. The symbol's ``other'' attribute is set to the 4282low 8 bits of this expression. 4283 4284@item desc 4285An absolute expression. The symbol's descriptor is set to the low 16 4286bits of this expression. 4287 4288@item value 4289An absolute expression which becomes the symbol's value. 4290@end table 4291 4292If a warning is detected while reading a @code{.stabd}, @code{.stabn}, 4293or @code{.stabs} statement, the symbol has probably already been created; 4294you get a half-formed symbol in your object file. This is 4295compatible with earlier assemblers! 4296 4297@table @code 4298@cindex @code{stabd} directive 4299@item .stabd @var{type} , @var{other} , @var{desc} 4300 4301The ``name'' of the symbol generated is not even an empty string. 4302It is a null pointer, for compatibility. Older assemblers used a 4303null pointer so they didn't waste space in object files with empty 4304strings. 4305 4306The symbol's value is set to the location counter, 4307relocatably. When your program is linked, the value of this symbol 4308is the address of the location counter when the @code{.stabd} was 4309assembled. 4310 4311@cindex @code{stabn} directive 4312@item .stabn @var{type} , @var{other} , @var{desc} , @var{value} 4313The name of the symbol is set to the empty string @code{""}. 4314 4315@cindex @code{stabs} directive 4316@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value} 4317All five fields are specified. 4318@end table 4319@end ifset 4320@c end have-stabs 4321 4322@node String 4323@section @code{.string} "@var{str}" 4324 4325@cindex string, copying to object file 4326@cindex @code{string} directive 4327 4328Copy the characters in @var{str} to the object file. You may specify more than 4329one string to copy, separated by commas. Unless otherwise specified for a 4330particular machine, the assembler marks the end of each string with a 0 byte. 4331You can use any of the escape sequences described in @ref{Strings,,Strings}. 4332 4333@ifset ELF 4334@node Symver 4335@section @code{.symver} 4336@cindex @code{symver} directive 4337@cindex symbol versioning 4338@cindex versions of symbols 4339Use the @code{.symver} directive to bind symbols to specific version nodes 4340within a source file. This is only supported on ELF platforms, and is 4341typically used when assembling files to be linked into a shared library. 4342There are cases where it may make sense to use this in objects to be bound 4343into an application itself so as to override a versioned symbol from a 4344shared library. 4345 4346For ELF targets, the @code{.symver} directive is used like this: 4347@smallexample 4348.symver @var{name}, @var{name2@@nodename} 4349@end smallexample 4350In this case, the symbol @var{name} must exist and be defined within the file 4351being assembled. The @code{.versym} directive effectively creates a symbol 4352alias with the name @var{name2@@nodename}, and in fact the main reason that we 4353just don't try and create a regular alias is that the @var{@@} character isn't 4354permitted in symbol names. The @var{name2} part of the name is the actual name 4355of the symbol by which it will be externally referenced. The name @var{name} 4356itself is merely a name of convenience that is used so that it is possible to 4357have definitions for multiple versions of a function within a single source 4358file, and so that the compiler can unambiguously know which version of a 4359function is being mentioned. The @var{nodename} portion of the alias should be 4360the name of a node specified in the version script supplied to the linker when 4361building a shared library. If you are attempting to override a versioned 4362symbol from a shared library, then @var{nodename} should correspond to the 4363nodename of the symbol you are trying to override. 4364@end ifset 4365 4366@ifset COFF 4367@node Tag 4368@section @code{.tag @var{structname}} 4369 4370@cindex COFF structure debugging 4371@cindex structure debugging, COFF 4372@cindex @code{tag} directive 4373This directive is generated by compilers to include auxiliary debugging 4374information in the symbol table. It is only permitted inside 4375@code{.def}/@code{.endef} pairs. Tags are used to link structure 4376definitions in the symbol table with instances of those structures. 4377@ifset BOUT 4378 4379@samp{.tag} is only used when generating COFF format output; when 4380@code{@value{AS}} is generating @code{b.out}, it accepts this directive but 4381ignores it. 4382@end ifset 4383@end ifset 4384 4385@node Text 4386@section @code{.text @var{subsection}} 4387 4388@cindex @code{text} directive 4389Tells @code{@value{AS}} to assemble the following statements onto the end of 4390the text subsection numbered @var{subsection}, which is an absolute 4391expression. If @var{subsection} is omitted, subsection number zero 4392is used. 4393 4394@node Title 4395@section @code{.title "@var{heading}"} 4396 4397@cindex @code{title} directive 4398@cindex listing control: title line 4399Use @var{heading} as the title (second line, immediately after the 4400source file name and pagenumber) when generating assembly listings. 4401 4402This directive affects subsequent pages, as well as the current page if 4403it appears within ten lines of the top of a page. 4404 4405@ifset COFF 4406@node Type 4407@section @code{.type @var{int}} 4408 4409@cindex COFF symbol type 4410@cindex symbol type, COFF 4411@cindex @code{type} directive 4412This directive, permitted only within @code{.def}/@code{.endef} pairs, 4413records the integer @var{int} as the type attribute of a symbol table entry. 4414@ifset BOUT 4415 4416@samp{.type} is associated only with COFF format output; when 4417@code{@value{AS}} is configured for @code{b.out} output, it accepts this 4418directive but ignores it. 4419@end ifset 4420@end ifset 4421 4422@ifset COFF 4423@node Val 4424@section @code{.val @var{addr}} 4425 4426@cindex @code{val} directive 4427@cindex COFF value attribute 4428@cindex value attribute, COFF 4429This directive, permitted only within @code{.def}/@code{.endef} pairs, 4430records the address @var{addr} as the value attribute of a symbol table 4431entry. 4432@ifset BOUT 4433 4434@samp{.val} is used only for COFF output; when @code{@value{AS}} is 4435configured for @code{b.out}, it accepts this directive but ignores it. 4436@end ifset 4437@end ifset 4438 4439@node Word 4440@section @code{.word @var{expressions}} 4441 4442@cindex @code{word} directive 4443This directive expects zero or more @var{expressions}, of any section, 4444separated by commas. 4445@ifclear GENERIC 4446@ifset W32 4447For each expression, @code{@value{AS}} emits a 32-bit number. 4448@end ifset 4449@ifset W16 4450For each expression, @code{@value{AS}} emits a 16-bit number. 4451@end ifset 4452@end ifclear 4453@ifset GENERIC 4454 4455The size of the number emitted, and its byte order, 4456depend on what target computer the assembly is for. 4457@end ifset 4458 4459@c on amd29k, i960, sparc the "special treatment to support compilers" doesn't 4460@c happen---32-bit addressability, period; no long/short jumps. 4461@ifset DIFF-TBL-KLUGE 4462@cindex difference tables altered 4463@cindex altered difference tables 4464@quotation 4465@emph{Warning: Special Treatment to support Compilers} 4466@end quotation 4467 4468@ifset GENERIC 4469Machines with a 32-bit address space, but that do less than 32-bit 4470addressing, require the following special treatment. If the machine of 4471interest to you does 32-bit addressing (or doesn't require it; 4472@pxref{Machine Dependencies}), you can ignore this issue. 4473 4474@end ifset 4475In order to assemble compiler output into something that works, 4476@code{@value{AS}} occasionlly does strange things to @samp{.word} directives. 4477Directives of the form @samp{.word sym1-sym2} are often emitted by 4478compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a 4479directive of the form @samp{.word sym1-sym2}, and the difference between 4480@code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}} 4481creates a @dfn{secondary jump table}, immediately before the next label. 4482This secondary jump table is preceded by a short-jump to the 4483first byte after the secondary table. This short-jump prevents the flow 4484of control from accidentally falling into the new table. Inside the 4485table is a long-jump to @code{sym2}. The original @samp{.word} 4486contains @code{sym1} minus the address of the long-jump to 4487@code{sym2}. 4488 4489If there were several occurrences of @samp{.word sym1-sym2} before the 4490secondary jump table, all of them are adjusted. If there was a 4491@samp{.word sym3-sym4}, that also did not fit in sixteen bits, a 4492long-jump to @code{sym4} is included in the secondary jump table, 4493and the @code{.word} directives are adjusted to contain @code{sym3} 4494minus the address of the long-jump to @code{sym4}; and so on, for as many 4495entries in the original jump table as necessary. 4496 4497@ifset INTERNALS 4498@emph{This feature may be disabled by compiling @code{@value{AS}} with the 4499@samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse 4500assembly language programmers. 4501@end ifset 4502@end ifset 4503@c end DIFF-TBL-KLUGE 4504 4505@node Deprecated 4506@section Deprecated Directives 4507 4508@cindex deprecated directives 4509@cindex obsolescent directives 4510One day these directives won't work. 4511They are included for compatibility with older assemblers. 4512@table @t 4513@item .abort 4514@item .app-file 4515@item .line 4516@end table 4517 4518@ifset GENERIC 4519@node Machine Dependencies 4520@chapter Machine Dependent Features 4521 4522@cindex machine dependencies 4523The machine instruction sets are (almost by definition) different on 4524each machine where @code{@value{AS}} runs. Floating point representations 4525vary as well, and @code{@value{AS}} often supports a few additional 4526directives or command-line options for compatibility with other 4527assemblers on a particular platform. Finally, some versions of 4528@code{@value{AS}} support special pseudo-instructions for branch 4529optimization. 4530 4531This chapter discusses most of these differences, though it does not 4532include details on any machine's instruction set. For details on that 4533subject, see the hardware manufacturer's manual. 4534 4535@menu 4536@ifset A29K 4537* AMD29K-Dependent:: AMD 29K Dependent Features 4538@end ifset 4539@ifset D10V 4540* D10V-Dependent:: D10V Dependent Features 4541@end ifset 4542@ifset H8/300 4543* H8/300-Dependent:: Hitachi H8/300 Dependent Features 4544@end ifset 4545@ifset H8/500 4546* H8/500-Dependent:: Hitachi H8/500 Dependent Features 4547@end ifset 4548@ifset HPPA 4549* HPPA-Dependent:: HPPA Dependent Features 4550@end ifset 4551@ifset I80386 4552* i386-Dependent:: Intel 80386 Dependent Features 4553@end ifset 4554@ifset I960 4555* i960-Dependent:: Intel 80960 Dependent Features 4556@end ifset 4557@ifset M680X0 4558* M68K-Dependent:: M680x0 Dependent Features 4559@end ifset 4560@ifset MIPS 4561* MIPS-Dependent:: MIPS Dependent Features 4562@end ifset 4563@ifset SH 4564* SH-Dependent:: Hitachi SH Dependent Features 4565@end ifset 4566@ifset SPARC 4567* Sparc-Dependent:: SPARC Dependent Features 4568@end ifset 4569@ifset Z8000 4570* Z8000-Dependent:: Z8000 Dependent Features 4571@end ifset 4572@ifset VAX 4573* Vax-Dependent:: VAX Dependent Features 4574@end ifset 4575@end menu 4576 4577@lowersections 4578@end ifset 4579 4580@c The following major nodes are *sections* in the GENERIC version, *chapters* 4581@c in single-cpu versions. This is mainly achieved by @lowersections. There is a 4582@c peculiarity: to preserve cross-references, there must be a node called 4583@c "Machine Dependencies". Hence the conditional nodenames in each 4584@c major node below. Node defaulting in makeinfo requires adjacency of 4585@c node and sectioning commands; hence the repetition of @chapter BLAH 4586@c in both conditional blocks. 4587 4588 4589@ifset A29K 4590@include c-a29k.texi 4591@end ifset 4592 4593@ifset Hitachi-all 4594@ifclear GENERIC 4595@node Machine Dependencies 4596@chapter Machine Dependent Features 4597 4598The machine instruction sets are different on each Hitachi chip family, 4599and there are also some syntax differences among the families. This 4600chapter describes the specific @code{@value{AS}} features for each 4601family. 4602 4603@menu 4604* H8/300-Dependent:: Hitachi H8/300 Dependent Features 4605* H8/500-Dependent:: Hitachi H8/500 Dependent Features 4606* SH-Dependent:: Hitachi SH Dependent Features 4607@end menu 4608@lowersections 4609@end ifclear 4610@end ifset 4611 4612@ifset D10V 4613@include c-d10v.texi 4614@end ifset 4615 4616@ifset H8/300 4617@include c-h8300.texi 4618@end ifset 4619 4620@ifset H8/500 4621@include c-h8500.texi 4622@end ifset 4623 4624@ifset HPPA 4625@include c-hppa.texi 4626@end ifset 4627 4628@ifset I80386 4629@include c-i386.texi 4630@end ifset 4631 4632@ifset I960 4633@include c-i960.texi 4634@end ifset 4635 4636@ifset M680X0 4637@include c-m68k.texi 4638@end ifset 4639 4640@ifset MIPS 4641@include c-mips.texi 4642@end ifset 4643 4644@ifset NS32K 4645@include c-ns32k.texi 4646@end ifset 4647 4648@ifset SH 4649@include c-sh.texi 4650@end ifset 4651 4652@ifset SPARC 4653@include c-sparc.texi 4654@end ifset 4655 4656@ifset Z8000 4657@include c-z8k.texi 4658@end ifset 4659 4660@ifset VAX 4661@include c-vax.texi 4662@end ifset 4663 4664@ifset GENERIC 4665@c reverse effect of @down at top of generic Machine-Dep chapter 4666@raisesections 4667@end ifset 4668 4669@node Reporting Bugs 4670@chapter Reporting Bugs 4671@cindex bugs in assembler 4672@cindex reporting bugs in assembler 4673 4674Your bug reports play an essential role in making @code{@value{AS}} reliable. 4675 4676Reporting a bug may help you by bringing a solution to your problem, or it may 4677not. But in any case the principal function of a bug report is to help the 4678entire community by making the next version of @code{@value{AS}} work better. 4679Bug reports are your contribution to the maintenance of @code{@value{AS}}. 4680 4681In order for a bug report to serve its purpose, you must include the 4682information that enables us to fix the bug. 4683 4684@menu 4685* Bug Criteria:: Have you found a bug? 4686* Bug Reporting:: How to report bugs 4687@end menu 4688 4689@node Bug Criteria 4690@section Have you found a bug? 4691@cindex bug criteria 4692 4693If you are not sure whether you have found a bug, here are some guidelines: 4694 4695@itemize @bullet 4696@cindex fatal signal 4697@cindex assembler crash 4698@cindex crash of assembler 4699@item 4700If the assembler gets a fatal signal, for any input whatever, that is a 4701@code{@value{AS}} bug. Reliable assemblers never crash. 4702 4703@cindex error on valid input 4704@item 4705If @code{@value{AS}} produces an error message for valid input, that is a bug. 4706 4707@cindex invalid input 4708@item 4709If @code{@value{AS}} does not produce an error message for invalid input, that 4710is a bug. However, you should note that your idea of ``invalid input'' might 4711be our idea of ``an extension'' or ``support for traditional practice''. 4712 4713@item 4714If you are an experienced user of assemblers, your suggestions for improvement 4715of @code{@value{AS}} are welcome in any case. 4716@end itemize 4717 4718@node Bug Reporting 4719@section How to report bugs 4720@cindex bug reports 4721@cindex assembler bugs, reporting 4722 4723A number of companies and individuals offer support for @sc{gnu} products. If 4724you obtained @code{@value{AS}} from a support organization, we recommend you 4725contact that organization first. 4726 4727You can find contact information for many support companies and 4728individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 4729distribution. 4730 4731In any event, we also recommend that you send bug reports for @code{@value{AS}} 4732to @samp{bug-gnu-utils@@prep.ai.mit.edu}. 4733 4734The fundamental principle of reporting bugs usefully is this: 4735@strong{report all the facts}. If you are not sure whether to state a 4736fact or leave it out, state it! 4737 4738Often people omit facts because they think they know what causes the problem 4739and assume that some details do not matter. Thus, you might assume that the 4740name of a symbol you use in an example does not matter. Well, probably it does 4741not, but one cannot be sure. Perhaps the bug is a stray memory reference which 4742happens to fetch from the location where that name is stored in memory; 4743perhaps, if the name were different, the contents of that location would fool 4744the assembler into doing the right thing despite the bug. Play it safe and 4745give a specific, complete example. That is the easiest thing for you to do, 4746and the most helpful. 4747 4748Keep in mind that the purpose of a bug report is to enable us to fix the bug if 4749it is new to us. Therefore, always write your bug reports on the assumption 4750that the bug has not been reported previously. 4751 4752Sometimes people give a few sketchy facts and ask, ``Does this ring a 4753bell?'' Those bug reports are useless, and we urge everyone to 4754@emph{refuse to respond to them} except to chide the sender to report 4755bugs properly. 4756 4757To enable us to fix the bug, you should include all these things: 4758 4759@itemize @bullet 4760@item 4761The version of @code{@value{AS}}. @code{@value{AS}} announces it if you start 4762it with the @samp{--version} argument. 4763 4764Without this, we will not know whether there is any point in looking for 4765the bug in the current version of @code{@value{AS}}. 4766 4767@item 4768Any patches you may have applied to the @code{@value{AS}} source. 4769 4770@item 4771The type of machine you are using, and the operating system name and 4772version number. 4773 4774@item 4775What compiler (and its version) was used to compile @code{@value{AS}}---e.g. 4776``@code{gcc-2.7}''. 4777 4778@item 4779The command arguments you gave the assembler to assemble your example and 4780observe the bug. To guarantee you will not omit something important, list them 4781all. A copy of the Makefile (or the output from make) is sufficient. 4782 4783If we were to try to guess the arguments, we would probably guess wrong 4784and then we might not encounter the bug. 4785 4786@item 4787A complete input file that will reproduce the bug. If the bug is observed when 4788the assembler is invoked via a compiler, send the assembler source, not the 4789high level language source. Most compilers will produce the assembler source 4790when run with the @samp{-S} option. If you are using @code{@value{GCC}}, use 4791the options @samp{-v --save-temps}; this will save the assembler source in a 4792file with an extension of @file{.s}, and also show you exactly how 4793@code{@value{AS}} is being run. 4794 4795@item 4796A description of what behavior you observe that you believe is 4797incorrect. For example, ``It gets a fatal signal.'' 4798 4799Of course, if the bug is that @code{@value{AS}} gets a fatal signal, then we 4800will certainly notice it. But if the bug is incorrect output, we might not 4801notice unless it is glaringly wrong. You might as well not give us a chance to 4802make a mistake. 4803 4804Even if the problem you experience is a fatal signal, you should still say so 4805explicitly. Suppose something strange is going on, such as, your copy of 4806@code{@value{AS}} is out of synch, or you have encountered a bug in the C 4807library on your system. (This has happened!) Your copy might crash and ours 4808would not. If you told us to expect a crash, then when ours fails to crash, we 4809would know that the bug was not happening for us. If you had not told us to 4810expect a crash, then we would not be able to draw any conclusion from our 4811observations. 4812 4813@item 4814If you wish to suggest changes to the @code{@value{AS}} source, send us context 4815diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p} 4816option. Always send diffs from the old file to the new file. If you even 4817discuss something in the @code{@value{AS}} source, refer to it by context, not 4818by line number. 4819 4820The line numbers in our development sources will not match those in your 4821sources. Your line numbers would convey no useful information to us. 4822@end itemize 4823 4824Here are some things that are not necessary: 4825 4826@itemize @bullet 4827@item 4828A description of the envelope of the bug. 4829 4830Often people who encounter a bug spend a lot of time investigating 4831which changes to the input file will make the bug go away and which 4832changes will not affect it. 4833 4834This is often time consuming and not very useful, because the way we 4835will find the bug is by running a single example under the debugger 4836with breakpoints, not by pure deduction from a series of examples. 4837We recommend that you save your time for something else. 4838 4839Of course, if you can find a simpler example to report @emph{instead} 4840of the original one, that is a convenience for us. Errors in the 4841output will be easier to spot, running under the debugger will take 4842less time, and so on. 4843 4844However, simplification is not vital; if you do not want to do this, 4845report the bug anyway and send us the entire test case you used. 4846 4847@item 4848A patch for the bug. 4849 4850A patch for the bug does help us if it is a good one. But do not omit 4851the necessary information, such as the test case, on the assumption that 4852a patch is all we need. We might see problems with your patch and decide 4853to fix the problem another way, or we might not understand it at all. 4854 4855Sometimes with a program as complicated as @code{@value{AS}} it is very hard to 4856construct an example that will make the program follow a certain path through 4857the code. If you do not send us the example, we will not be able to construct 4858one, so we will not be able to verify that the bug is fixed. 4859 4860And if we cannot understand what bug you are trying to fix, or why your 4861patch should be an improvement, we will not install it. A test case will 4862help us to understand. 4863 4864@item 4865A guess about what the bug is or what it depends on. 4866 4867Such guesses are usually wrong. Even we cannot guess right about such 4868things without first using the debugger to find the facts. 4869@end itemize 4870 4871@node Acknowledgements 4872@chapter Acknowledgements 4873 4874If you have contributed to @code{@value{AS}} and your name isn't listed here, 4875it is not meant as a slight. We just don't know about it. Send mail to the 4876maintainer, and we'll correct the situation. Currently 4877@c (January 1994), 4878the maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}). 4879 4880Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any 4881more details?} 4882 4883Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug 4884information and the 68k series machines, most of the preprocessing pass, and 4885extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}. 4886 4887K. Richard Pixley maintained GAS for a while, adding various enhancements and 4888many bug fixes, including merging support for several processors, breaking GAS 4889up to handle multiple object file format back ends (including heavy rewrite, 4890testing, an integration of the coff and b.out back ends), adding configuration 4891including heavy testing and verification of cross assemblers and file splits 4892and renaming, converted GAS to strictly ANSI C including full prototypes, added 4893support for m680[34]0 and cpu32, did considerable work on i960 including a COFF 4894port (including considerable amounts of reverse engineering), a SPARC opcode 4895file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know'' 4896assertions and made them work, much other reorganization, cleanup, and lint. 4897 4898Ken Raeburn wrote the high-level BFD interface code to replace most of the code 4899in format-specific I/O modules. 4900 4901The original VMS support was contributed by David L. Kashtan. Eric Youngdale 4902has done much work with it since. 4903 4904The Intel 80386 machine description was written by Eliot Dresselhaus. 4905 4906Minh Tran-Le at IntelliCorp contributed some AIX 386 support. 4907 4908The Motorola 88k machine description was contributed by Devon Bowen of Buffalo 4909University and Torbjorn Granlund of the Swedish Institute of Computer Science. 4910 4911Keith Knowles at the Open Software Foundation wrote the original MIPS back end 4912(@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support 4913(which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to 4914support a.out format. 4915 4916Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k, 4917tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by 4918Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to 4919use BFD for some low-level operations, for use with the H8/300 and AMD 29k 4920targets. 4921 4922John Gilmore built the AMD 29000 support, added @code{.include} support, and 4923simplified the configuration of which versions accept which directives. He 4924updated the 68k machine description so that Motorola's opcodes always produced 4925fixed-size instructions (e.g. @code{jsr}), while synthetic instructions 4926remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested 4927cross-compilation support, and one bug in relaxation that took a week and 4928required the proverbial one-bit fix. 4929 4930Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the 493168k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix), 4932added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and 4933PowerPC assembler, and made a few other minor patches. 4934 4935Steve Chamberlain made @code{@value{AS}} able to generate listings. 4936 4937Hewlett-Packard contributed support for the HP9000/300. 4938 4939Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) 4940along with a fairly extensive HPPA testsuite (for both SOM and ELF object 4941formats). This work was supported by both the Center for Software Science at 4942the University of Utah and Cygnus Support. 4943 4944Support for ELF format files has been worked on by Mark Eichin of Cygnus 4945Support (original, incomplete implementation for SPARC), Pete Hoogenboom and 4946Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open 4947Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc, 4948and some initial 64-bit support). 4949 4950Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD 4951support for openVMS/Alpha. 4952 4953Several engineers at Cygnus Support have also provided many small bug fixes and 4954configuration enhancements. 4955 4956Many others have contributed large or small bugfixes and enhancements. If 4957you have contributed significant work and are not mentioned on this list, and 4958want to be, let us know. Some of the history has been lost; we are not 4959intentionally leaving anyone out. 4960 4961@node Index 4962@unnumbered Index 4963 4964@printindex cp 4965 4966@contents 4967@bye 4968@c Local Variables: 4969@c fill-column: 79 4970@c End: 4971