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