as.texinfo revision 1.3
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 205@ifset H8 206@c Hitachi family chips have no machine-dependent assembler options 207@end ifset 208@ifset HPPA 209@c HPPA has no machine-dependent assembler options (yet). 210@end ifset 211@ifset SPARC 212@c The order here is important. See c-sparc.texi. 213 [ -Av6 | -Av7 | -Av8 | -Asparclite | -Av9 | -Av9a ] 214 [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ] 215@end ifset 216@ifset Z8000 217@c Z8000 has no machine-dependent assembler options 218@end ifset 219@ifset I960 220@c see md_parse_option in tc-i960.c 221 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ] 222 [ -b ] [ -no-relax ] 223@end ifset 224@ifset M680X0 225 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ] 226@end ifset 227@ifset MIPS 228 [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ] 229 [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ] 230 [ --trap ] [ --break ] 231 [ --emulation=@var{name} ] 232@end ifset 233 [ -- | @var{files} @dots{} ] 234@end smallexample 235 236@table @code 237@item -a[dhlns] 238Turn on listings, in any of a variety of ways: 239 240@table @code 241@item -ad 242omit debugging directives 243 244@item -ah 245include high-level source 246 247@item -al 248include assembly 249 250@item -an 251omit forms processing 252 253@item -as 254include symbols 255 256@item =file 257set the name of the listing file 258@end table 259 260You may combine these options; for example, use @samp{-aln} for assembly 261listing without forms processing. The @samp{=file} option, if used, must be 262the last one. By itself, @samp{-a} defaults to @samp{-ahls}---that is, all 263listings turned on. 264 265@item -D 266Ignored. This option is accepted for script compatibility with calls to 267other assemblers. 268 269@item --defsym @var{sym}=@var{value} 270Define the symbol @var{sym} to be @var{value} before assembling the input file. 271@var{value} must be an integer constant. As in C, a leading @samp{0x} 272indicates a hexadecimal value, and a leading @samp{0} indicates an octal value. 273 274@item -f 275``fast''---skip whitespace and comment preprocessing (assume source is 276compiler output). 277 278@item --help 279Print a summary of the command line options and exit. 280 281@item -I @var{dir} 282Add directory @var{dir} to the search list for @code{.include} directives. 283 284@item -J 285Don't warn about signed overflow. 286 287@item -K 288@ifclear DIFF-TBL-KLUGE 289This option is accepted but has no effect on the @value{TARGET} family. 290@end ifclear 291@ifset DIFF-TBL-KLUGE 292Issue warnings when difference tables altered for long displacements. 293@end ifset 294 295@item -L 296Keep (in the symbol table) local symbols, starting with @samp{L}. 297 298@item -o @var{objfile} 299Name the object-file output from @code{@value{AS}} @var{objfile}. 300 301@item -R 302Fold the data section into the text section. 303 304@item --statistics 305Print the maximum space (in bytes) and total time (in seconds) used by 306assembly. 307 308@item -v 309@itemx -version 310Print the @code{as} version. 311 312@item --version 313Print the @code{as} version and exit. 314 315@item -W 316Suppress warning messages. 317 318@item -w 319Ignored. 320 321@item -x 322Ignored. 323 324@item -Z 325Generate an object file even after errors. 326 327@item -- | @var{files} @dots{} 328Standard input, or source files to assemble. 329 330@end table 331 332@ifset ARC 333The following options are available when @value{AS} is configured for 334an ARC processor. 335 336@table @code 337 338@cindex ARC endianness 339@cindex endianness, ARC 340@cindex big endian output, ARC 341@item -mbig-endian 342Generate ``big endian'' format output. 343 344@cindex little endian output, ARC 345@item -mlittle-endian 346Generate ``little endian'' format output. 347 348@end table 349@end ifset 350 351 352@ifset I960 353The following options are available when @value{AS} is configured for the 354Intel 80960 processor. 355 356@table @code 357@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC 358Specify which variant of the 960 architecture is the target. 359 360@item -b 361Add code to collect statistics about branches taken. 362 363@item -no-relax 364Do not alter compare-and-branch instructions for long displacements; 365error if necessary. 366 367@end table 368@end ifset 369 370@ifset M680X0 371The following options are available when @value{AS} is configured for the 372Motorola 68000 series. 373 374@table @code 375 376@item -l 377Shorten references to undefined symbols, to one word instead of two. 378 379@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060 380@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200 381Specify what processor in the 68000 family is the target. The default 382is normally the 68020, but this can be changed at configuration time. 383 384@item -m68881 | -m68882 | -mno-68881 | -mno-68882 385The target machine does (or does not) have a floating-point coprocessor. 386The default is to assume a coprocessor for 68020, 68030, and cpu32. Although 387the basic 68000 is not compatible with the 68881, a combination of the 388two can be specified, since it's possible to do emulation of the 389coprocessor instructions with the main processor. 390 391@item -m68851 | -mno-68851 392The target machine does (or does not) have a memory-management 393unit coprocessor. The default is to assume an MMU for 68020 and up. 394 395@end table 396@end ifset 397 398@ifset SPARC 399The following options are available when @code{@value{AS}} is configured 400for the SPARC architecture: 401 402@table @code 403@item -Av6 | -Av7 | -Av8 | -Asparclite | -Av9 | -Av9a 404Explicitly select a variant of the SPARC architecture. 405 406@item -xarch=v8plus | -xarch=v8plusa 407For compatibility with the Solaris v9 assembler. These options are 408equivalent to -Av9 and -Av9a, respectively. 409 410@item -bump 411Warn when the assembler switches to another architecture. 412@end table 413@end ifset 414 415@ifset MIPS 416The following options are available when @value{AS} is configured for 417a MIPS processor. 418 419@table @code 420@item -G @var{num} 421This option sets the largest size of an object that can be referenced 422implicitly with the @code{gp} register. It is only accepted for targets that 423use ECOFF format, such as a DECstation running Ultrix. The default value is 8. 424 425@cindex MIPS endianness 426@cindex endianness, MIPS 427@cindex big endian output, MIPS 428@item -EB 429Generate ``big endian'' format output. 430 431@cindex little endian output, MIPS 432@item -EL 433Generate ``little endian'' format output. 434 435@cindex MIPS ISA 436@item -mips1 437@itemx -mips2 438@itemx -mips3 439Generate code for a particular MIPS Instruction Set Architecture level. 440@samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors, 441@samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000} 442processor. 443 444@item -m4650 445@item -no-m4650 446Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept 447the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop} 448instructions around accesses to the @samp{HI} and @samp{LO} registers. 449@samp{-no-m4650} turns off this option. 450 451@item -mcpu=@var{CPU} 452Generate code for a particular MIPS cpu. This has little effect on the 453assembler, but it is passed by @code{@value{GCC}}. 454 455@cindex emulation 456@item --emulation=@var{name} 457This option causes @code{@value{AS}} to emulated @code{@value{AS}} configured 458for some other target, in all respects, including output format (choosing 459between ELF and ECOFF only), handling of pseudo-opcodes which may generate 460debugging information or store symbol table information, and default 461endianness. The available configuration names are: @samp{mipsecoff}, 462@samp{mipself}, @samp{mipslecoff}, @samp{mipsbecoff}, @samp{mipslelf}, 463@samp{mipsbelf}. The first two do not alter the default endianness from that 464of the primary target for which the assembler was configured; the others change 465the default to little- or big-endian as indicated by the @samp{b} or @samp{l} 466in the name. Using @samp{-EB} or @samp{-EL} will override the endianness 467selection in any case. 468 469This option is currently supported only when the primary target 470@code{@value{AS}} is configured for is a MIPS ELF or ECOFF target. 471Furthermore, the primary target or others specified with 472@samp{--enable-targets=@dots{}} at configuration time must include support for 473the other format, if both are to be available. For example, the Irix 5 474configuration includes support for both. 475 476Eventually, this option will support more configurations, with more 477fine-grained control over the assembler's behavior, and will be supported for 478more processors. 479 480@item -nocpp 481@code{@value{AS}} ignores this option. It is accepted for compatibility with 482the native tools. 483 484@need 900 485@item --trap 486@itemx --no-trap 487@itemx --break 488@itemx --no-break 489Control how to deal with multiplication overflow and division by zero. 490@samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception 491(and only work for Instruction Set Architecture level 2 and higher); 492@samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a 493break exception. 494@end table 495@end ifset 496 497@menu 498* Manual:: Structure of this Manual 499* GNU Assembler:: @value{AS}, the GNU Assembler 500* Object Formats:: Object File Formats 501* Command Line:: Command Line 502* Input Files:: Input Files 503* Object:: Output (Object) File 504* Errors:: Error and Warning Messages 505@end menu 506 507@node Manual 508@section Structure of this Manual 509 510@cindex manual, structure and purpose 511This manual is intended to describe what you need to know to use 512@sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including 513notation for symbols, constants, and expressions; the directives that 514@code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}. 515 516@ifclear GENERIC 517We also cover special features in the @value{TARGET} 518configuration of @code{@value{AS}}, including assembler directives. 519@end ifclear 520@ifset GENERIC 521This manual also describes some of the machine-dependent features of 522various flavors of the assembler. 523@end ifset 524 525@cindex machine instructions (not covered) 526On the other hand, this manual is @emph{not} intended as an introduction 527to programming in assembly language---let alone programming in general! 528In a similar vein, we make no attempt to introduce the machine 529architecture; we do @emph{not} describe the instruction set, standard 530mnemonics, registers or addressing modes that are standard to a 531particular architecture. 532@ifset GENERIC 533You may want to consult the manufacturer's 534machine architecture manual for this information. 535@end ifset 536@ifclear GENERIC 537@ifset H8/300 538For information on the H8/300 machine instruction set, see @cite{H8/300 539Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H, 540see @cite{H8/300H Series Programming Manual} (Hitachi). 541@end ifset 542@ifset H8/500 543For information on the H8/500 machine instruction set, see @cite{H8/500 544Series Programming Manual} (Hitachi M21T001). 545@end ifset 546@ifset SH 547For information on the Hitachi SH machine instruction set, see 548@cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.). 549@end ifset 550@ifset Z8000 551For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual} 552@end ifset 553@end ifclear 554 555@c I think this is premature---doc@cygnus.com, 17jan1991 556@ignore 557Throughout this manual, we assume that you are running @dfn{GNU}, 558the portable operating system from the @dfn{Free Software 559Foundation, Inc.}. This restricts our attention to certain kinds of 560computer (in particular, the kinds of computers that @sc{gnu} can run on); 561once this assumption is granted examples and definitions need less 562qualification. 563 564@code{@value{AS}} is part of a team of programs that turn a high-level 565human-readable series of instructions into a low-level 566computer-readable series of instructions. Different versions of 567@code{@value{AS}} are used for different kinds of computer. 568@end ignore 569 570@c There used to be a section "Terminology" here, which defined 571@c "contents", "byte", "word", and "long". Defining "word" to any 572@c particular size is confusing when the .word directive may generate 16 573@c bits on one machine and 32 bits on another; in general, for the user 574@c version of this manual, none of these terms seem essential to define. 575@c They were used very little even in the former draft of the manual; 576@c this draft makes an effort to avoid them (except in names of 577@c directives). 578 579@node GNU Assembler 580@section @value{AS}, the GNU Assembler 581 582@sc{gnu} @code{as} is really a family of assemblers. 583@ifclear GENERIC 584This manual describes @code{@value{AS}}, a member of that family which is 585configured for the @value{TARGET} architectures. 586@end ifclear 587If you use (or have used) the @sc{gnu} assembler on one architecture, you 588should find a fairly similar environment when you use it on another 589architecture. Each version has much in common with the others, 590including object file formats, most assembler directives (often called 591@dfn{pseudo-ops}) and assembler syntax.@refill 592 593@cindex purpose of @sc{gnu} @code{@value{AS}} 594@code{@value{AS}} is primarily intended to assemble the output of the 595@sc{gnu} C compiler @code{@value{GCC}} for use by the linker 596@code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}} 597assemble correctly everything that other assemblers for the same 598machine would assemble. 599@ifset VAX 600Any exceptions are documented explicitly (@pxref{Machine Dependencies}). 601@end ifset 602@ifset M680X0 603@c This remark should appear in generic version of manual; assumption 604@c here is that generic version sets M680x0. 605This doesn't mean @code{@value{AS}} always uses the same syntax as another 606assembler for the same architecture; for example, we know of several 607incompatible versions of 680x0 assembly language syntax. 608@end ifset 609 610Unlike older assemblers, @code{@value{AS}} is designed to assemble a source 611program in one pass of the source file. This has a subtle impact on the 612@kbd{.org} directive (@pxref{Org,,@code{.org}}). 613 614@node Object Formats 615@section Object File Formats 616 617@cindex object file format 618The @sc{gnu} assembler can be configured to produce several alternative 619object file formats. For the most part, this does not affect how you 620write assembly language programs; but directives for debugging symbols 621are typically different in different file formats. @xref{Symbol 622Attributes,,Symbol Attributes}. 623@ifclear GENERIC 624@ifclear MULTI-OBJ 625On the @value{TARGET}, @code{@value{AS}} is configured to produce 626@value{OBJ-NAME} format object files. 627@end ifclear 628@c The following should exhaust all configs that set MULTI-OBJ, ideally 629@ifset A29K 630On the @value{TARGET}, @code{@value{AS}} can be configured to produce either 631@code{a.out} or COFF format object files. 632@end ifset 633@ifset I960 634On the @value{TARGET}, @code{@value{AS}} can be configured to produce either 635@code{b.out} or COFF format object files. 636@end ifset 637@ifset HPPA 638On the @value{TARGET}, @code{@value{AS}} can be configured to produce either 639SOM or ELF format object files. 640@end ifset 641@end ifclear 642 643@node Command Line 644@section Command Line 645 646@cindex command line conventions 647After the program name @code{@value{AS}}, the command line may contain 648options and file names. Options may appear in any order, and may be 649before, after, or between file names. The order of file names is 650significant. 651 652@cindex standard input, as input file 653@kindex -- 654@file{--} (two hyphens) by itself names the standard input file 655explicitly, as one of the files for @code{@value{AS}} to assemble. 656 657@cindex options, command line 658Except for @samp{--} any command line argument that begins with a 659hyphen (@samp{-}) is an option. Each option changes the behavior of 660@code{@value{AS}}. No option changes the way another option works. An 661option is a @samp{-} followed by one or more letters; the case of 662the letter is important. All options are optional. 663 664Some options expect exactly one file name to follow them. The file 665name may either immediately follow the option's letter (compatible 666with older assemblers) or it may be the next command argument (@sc{gnu} 667standard). These two command lines are equivalent: 668 669@smallexample 670@value{AS} -o my-object-file.o mumble.s 671@value{AS} -omy-object-file.o mumble.s 672@end smallexample 673 674@node Input Files 675@section Input Files 676 677@cindex input 678@cindex source program 679@cindex files, input 680We use the phrase @dfn{source program}, abbreviated @dfn{source}, to 681describe the program input to one run of @code{@value{AS}}. The program may 682be in one or more files; how the source is partitioned into files 683doesn't change the meaning of the source. 684 685@c I added "con" prefix to "catenation" just to prove I can overcome my 686@c APL training... doc@cygnus.com 687The source program is a concatenation of the text in all the files, in the 688order specified. 689 690Each time you run @code{@value{AS}} it assembles exactly one source 691program. The source program is made up of one or more files. 692(The standard input is also a file.) 693 694You give @code{@value{AS}} a command line that has zero or more input file 695names. The input files are read (from left file name to right). A 696command line argument (in any position) that has no special meaning 697is taken to be an input file name. 698 699If you give @code{@value{AS}} no file names it attempts to read one input file 700from the @code{@value{AS}} standard input, which is normally your terminal. You 701may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program 702to assemble. 703 704Use @samp{--} if you need to explicitly name the standard input file 705in your command line. 706 707If the source is empty, @code{@value{AS}} produces a small, empty object 708file. 709 710@subheading Filenames and Line-numbers 711 712@cindex input file linenumbers 713@cindex line numbers, in input files 714There are two ways of locating a line in the input file (or files) and 715either may be used in reporting error messages. One way refers to a line 716number in a physical file; the other refers to a line number in a 717``logical'' file. @xref{Errors, ,Error and Warning Messages}. 718 719@dfn{Physical files} are those files named in the command line given 720to @code{@value{AS}}. 721 722@dfn{Logical files} are simply names declared explicitly by assembler 723directives; they bear no relation to physical files. Logical file names 724help error messages reflect the original source file, when @code{@value{AS}} 725source is itself synthesized from other files. 726@xref{App-File,,@code{.app-file}}. 727 728@node Object 729@section Output (Object) File 730 731@cindex object file 732@cindex output file 733@kindex a.out 734@kindex .o 735Every time you run @code{@value{AS}} it produces an output file, which is 736your assembly language program translated into numbers. This file 737is the object file. Its default name is 738@ifclear BOUT 739@code{a.out}. 740@end ifclear 741@ifset BOUT 742@ifset GENERIC 743@code{a.out}, or 744@end ifset 745@code{b.out} when @code{@value{AS}} is configured for the Intel 80960. 746@end ifset 747You can give it another name by using the @code{-o} option. Conventionally, 748object file names end with @file{.o}. The default name is used for historical 749reasons: older assemblers were capable of assembling self-contained programs 750directly into a runnable program. (For some formats, this isn't currently 751possible, but it can be done for the @code{a.out} format.) 752 753@cindex linker 754@kindex ld 755The object file is meant for input to the linker @code{@value{LD}}. It contains 756assembled program code, information to help @code{@value{LD}} integrate 757the assembled program into a runnable file, and (optionally) symbolic 758information for the debugger. 759 760@c link above to some info file(s) like the description of a.out. 761@c don't forget to describe @sc{gnu} info as well as Unix lossage. 762 763@node Errors 764@section Error and Warning Messages 765 766@cindex error messsages 767@cindex warning messages 768@cindex messages from @code{@value{AS}} 769@code{@value{AS}} may write warnings and error messages to the standard error 770file (usually your terminal). This should not happen when a compiler 771runs @code{@value{AS}} automatically. Warnings report an assumption made so 772that @code{@value{AS}} could keep assembling a flawed program; errors report a 773grave problem that stops the assembly. 774 775@cindex format of warning messages 776Warning messages have the format 777 778@smallexample 779file_name:@b{NNN}:Warning Message Text 780@end smallexample 781 782@noindent 783@cindex line numbers, in warnings/errors 784(where @b{NNN} is a line number). If a logical file name has been given 785(@pxref{App-File,,@code{.app-file}}) it is used for the filename, 786otherwise the name of the current input file is used. If a logical line 787number was given 788@ifset GENERIC 789(@pxref{Line,,@code{.line}}) 790@end ifset 791@ifclear GENERIC 792@ifclear A29K 793(@pxref{Line,,@code{.line}}) 794@end ifclear 795@ifset A29K 796(@pxref{Ln,,@code{.ln}}) 797@end ifset 798@end ifclear 799then it is used to calculate the number printed, 800otherwise the actual line in the current source file is printed. The 801message text is intended to be self explanatory (in the grand Unix 802tradition). 803 804@cindex format of error messages 805Error messages have the format 806@smallexample 807file_name:@b{NNN}:FATAL:Error Message Text 808@end smallexample 809The file name and line number are derived as for warning 810messages. The actual message text may be rather less explanatory 811because many of them aren't supposed to happen. 812 813@node Invoking 814@chapter Command-Line Options 815 816@cindex options, all versions of @code{@value{AS}} 817This chapter describes command-line options available in @emph{all} 818versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific 819@ifclear GENERIC 820to the @value{TARGET}. 821@end ifclear 822@ifset GENERIC 823to particular machine architectures. 824@end ifset 825 826If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2), you 827can use the @samp{-Wa} option to pass arguments through to the 828assembler. The assembler arguments must be separated from each other 829(and the @samp{-Wa}) by commas. For example: 830 831@smallexample 832gcc -c -g -O -Wa,-alh,-L file.c 833@end smallexample 834 835@noindent 836emits a listing to standard output with high-level 837and assembly source. 838 839Usually you do not need to use this @samp{-Wa} mechanism, since many compiler 840command-line options are automatically passed to the assembler by the compiler. 841(You can call the @sc{gnu} compiler driver with the @samp{-v} option to see 842precisely what options it passes to each compilation pass, including the 843assembler.) 844 845@menu 846* a:: -a[dhlns] enable listings 847* D:: -D for compatibility 848* f:: -f to work faster 849* I:: -I for .include search path 850@ifclear DIFF-TBL-KLUGE 851* K:: -K for compatibility 852@end ifclear 853@ifset DIFF-TBL-KLUGE 854* K:: -K for difference tables 855@end ifset 856 857* L:: -L to retain local labels 858* M:: -M or --mri to assemble in MRI compatibility mode 859* o:: -o to name the object file 860* R:: -R to join data and text sections 861* statistics:: --statistics to see statistics about assembly 862* v:: -v to announce version 863* W:: -W to suppress warnings 864* Z:: -Z to make object file even after errors 865@end menu 866 867@node a 868@section Enable Listings: @code{-a[dhlns]} 869 870@kindex -a 871@kindex -ad 872@kindex -ah 873@kindex -al 874@kindex -an 875@kindex -as 876@cindex listings, enabling 877@cindex assembly listings, enabling 878 879These options enable listing output from the assembler. By itself, 880@samp{-a} requests high-level, assembly, and symbols listing. 881You can use other letters to select specific options for the list: 882@samp{-ah} requests a high-level language listing, 883@samp{-al} requests an output-program assembly listing, and 884@samp{-as} requests a symbol table listing. 885High-level listings require that a compiler debugging option like 886@samp{-g} be used, and that assembly listings (@samp{-al}) be requested 887also. 888 889Use the @samp{-ad} option to omit debugging directives from the 890listing. 891 892Once you have specified one of these options, you can further control 893listing output and its appearance using the directives @code{.list}, 894@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and 895@code{.sbttl}. 896The @samp{-an} option turns off all forms processing. 897If you do not request listing output with one of the @samp{-a} options, the 898listing-control directives have no effect. 899 900The letters after @samp{-a} may be combined into one option, 901@emph{e.g.}, @samp{-aln}. 902 903@node D 904@section @code{-D} 905 906@kindex -D 907This option has no effect whatsoever, but it is accepted to make it more 908likely that scripts written for other assemblers also work with 909@code{@value{AS}}. 910 911@node f 912@section Work Faster: @code{-f} 913 914@kindex -f 915@cindex trusted compiler 916@cindex faster processing (@code{-f}) 917@samp{-f} should only be used when assembling programs written by a 918(trusted) compiler. @samp{-f} stops the assembler from doing whitespace 919and comment preprocessing on 920the input file(s) before assembling them. @xref{Preprocessing, 921,Preprocessing}. 922 923@quotation 924@emph{Warning:} if you use @samp{-f} when the files actually need to be 925preprocessed (if they contain comments, for example), @code{@value{AS}} does 926not work correctly. 927@end quotation 928 929@node I 930@section @code{.include} search path: @code{-I} @var{path} 931 932@kindex -I @var{path} 933@cindex paths for @code{.include} 934@cindex search path for @code{.include} 935@cindex @code{include} directive search path 936Use this option to add a @var{path} to the list of directories 937@code{@value{AS}} searches for files specified in @code{.include} 938directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as 939many times as necessary to include a variety of paths. The current 940working directory is always searched first; after that, @code{@value{AS}} 941searches any @samp{-I} directories in the same order as they were 942specified (left to right) on the command line. 943 944@node K 945@section Difference Tables: @code{-K} 946 947@kindex -K 948@ifclear DIFF-TBL-KLUGE 949On the @value{TARGET} family, this option is allowed, but has no effect. It is 950permitted for compatibility with the @sc{gnu} assembler on other platforms, 951where it can be used to warn when the assembler alters the machine code 952generated for @samp{.word} directives in difference tables. The @value{TARGET} 953family does not have the addressing limitations that sometimes lead to this 954alteration on other platforms. 955@end ifclear 956 957@ifset DIFF-TBL-KLUGE 958@cindex difference tables, warning 959@cindex warning for altered difference tables 960@code{@value{AS}} sometimes alters the code emitted for directives of the form 961@samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}. 962You can use the @samp{-K} option if you want a warning issued when this 963is done. 964@end ifset 965 966@node L 967@section Include Local Labels: @code{-L} 968 969@kindex -L 970@cindex local labels, retaining in output 971Labels beginning with @samp{L} (upper case only) are called @dfn{local 972labels}. @xref{Symbol Names}. Normally you do not see such labels when 973debugging, because they are intended for the use of programs (like 974compilers) that compose assembler programs, not for your notice. 975Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not 976normally debug with them. 977 978This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols 979in the object file. Usually if you do this you also tell the linker 980@code{@value{LD}} to preserve symbols whose names begin with @samp{L}. 981 982By default, a local label is any label beginning with @samp{L}, but each 983target is allowed to redefine the local label prefix. 984@ifset HPPA 985On the HPPA local labels begin with @samp{L$}. 986@end ifset 987 988@node M 989@section Assemble in MRI Compatibility Mode: @code{-M} 990 991@kindex -M 992@cindex MRI compatibility mode 993The @code{-M} or @code{--mri} option selects MRI compatibility mode. This 994changes the syntax and pseudo-op handling of @code{@value{AS}} to make it 995compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the 996configured target) assembler from Microtec Research. The exact nature of the 997MRI syntax will not be documented here; see the MRI manuals for more 998information. The purpose of this option is to permit assembling existing MRI 999assembler code using @code{@value{AS}}. 1000 1001The MRI compatibility is not complete. Certain operations of the MRI assembler 1002depend upon its object file format, and can not be supported using other object 1003file formats. Supporting these would require enhancing each object file format 1004individually. These are: 1005 1006@itemize @bullet 1007@item global symbols in common section 1008 1009The m68k MRI assembler supports common sections which are merged by the linker. 1010Other object file formats do not support this. @code{@value{AS}} handles 1011common sections by treating them as a single common symbol. It permits local 1012symbols to be defined within a common section, but it can not support global 1013symbols, since it has no way to describe them. 1014 1015@item complex relocations 1016 1017The MRI assemblers support relocations against a negated section address, and 1018relocations which combine the start addresses of two or more sections. These 1019are not support by other object file formats. 1020 1021@item @code{END} pseudo-op specifying start address 1022 1023The MRI @code{END} pseudo-op permits the specification of a start address. 1024This is not supported by other object file formats. The start address may 1025instead be specified using the @code{-e} option to the linker, or in a linker 1026script. 1027 1028@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops 1029 1030The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module 1031name to the output file. This is not supported by other object file formats. 1032 1033@item @code{ORG} pseudo-op 1034 1035The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given 1036address. This differs from the usual @code{@value{AS}} @code{.org} pseudo-op, 1037which changes the location within the current section. Absolute sections are 1038not supported by other object file formats. The address of a section may be 1039assigned within a linker script. 1040@end itemize 1041 1042There are some other features of the MRI assembler which are not supported by 1043@code{@value{AS}}, typically either because they are difficult or because they 1044seem of little consequence. Some of these may be supported in future releases. 1045 1046@itemize @bullet 1047 1048@item EBCDIC strings 1049 1050EBCDIC strings are not supported. 1051 1052@item packed binary coded decimal 1053 1054Packed binary coded decimal is not supported. This means that the @code{DC.P} 1055and @code{DCB.P} pseudo-ops are not supported. 1056 1057@item @code{FEQU} pseudo-op 1058 1059The m68k @code{FEQU} pseudo-op is not supported. 1060 1061@item @code{NOOBJ} pseudo-op 1062 1063The m68k @code{NOOBJ} pseudo-op is not supported. 1064 1065@item @code{OPT} branch control options 1066 1067The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB}, 1068@code{BRL}, and @code{BRW}---are ignored. @code{@value{AS}} automatically 1069relaxes all branches, whether forward or backward, to an appropriate size, so 1070these options serve no purpose. 1071 1072@item @code{OPT} list control options 1073 1074The following m68k @code{OPT} list control options are ignored: @code{C}, 1075@code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M}, 1076@code{MEX}, @code{MC}, @code{MD}, @code{X}. 1077 1078@item other @code{OPT} options 1079 1080The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O}, 1081@code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}. 1082 1083@item @code{OPT} @code{D} option is default 1084 1085The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler. 1086@code{OPT NOD} may be used to turn it off. 1087 1088@item @code{XREF} pseudo-op. 1089 1090The m68k @code{XREF} pseudo-op is ignored. 1091 1092@item @code{.debug} pseudo-op 1093 1094The i960 @code{.debug} pseudo-op is not supported. 1095 1096@item @code{.extended} pseudo-op 1097 1098The i960 @code{.extended} pseudo-op is not supported. 1099 1100@item @code{.list} pseudo-op. 1101 1102The various options of the i960 @code{.list} pseudo-op are not supported. 1103 1104@item @code{.optimize} pseudo-op 1105 1106The i960 @code{.optimize} pseudo-op is not supported. 1107 1108@item @code{.output} pseudo-op 1109 1110The i960 @code{.output} pseudo-op is not supported. 1111 1112@item @code{.setreal} pseudo-op 1113 1114The i960 @code{.setreal} pseudo-op is not supported. 1115 1116@end itemize 1117 1118@node o 1119@section Name the Object File: @code{-o} 1120 1121@kindex -o 1122@cindex naming object file 1123@cindex object file name 1124There is always one object file output when you run @code{@value{AS}}. By 1125default it has the name 1126@ifset GENERIC 1127@ifset I960 1128@file{a.out} (or @file{b.out}, for Intel 960 targets only). 1129@end ifset 1130@ifclear I960 1131@file{a.out}. 1132@end ifclear 1133@end ifset 1134@ifclear GENERIC 1135@ifset I960 1136@file{b.out}. 1137@end ifset 1138@ifclear I960 1139@file{a.out}. 1140@end ifclear 1141@end ifclear 1142You use this option (which takes exactly one filename) to give the 1143object file a different name. 1144 1145Whatever the object file is called, @code{@value{AS}} overwrites any 1146existing file of the same name. 1147 1148@node R 1149@section Join Data and Text Sections: @code{-R} 1150 1151@kindex -R 1152@cindex data and text sections, joining 1153@cindex text and data sections, joining 1154@cindex joining text and data sections 1155@cindex merging text and data sections 1156@code{-R} tells @code{@value{AS}} to write the object file as if all 1157data-section data lives in the text section. This is only done at 1158the very last moment: your binary data are the same, but data 1159section parts are relocated differently. The data section part of 1160your object file is zero bytes long because all its bytes are 1161appended to the text section. (@xref{Sections,,Sections and Relocation}.) 1162 1163When you specify @code{-R} it would be possible to generate shorter 1164address displacements (because we do not have to cross between text and 1165data section). We refrain from doing this simply for compatibility with 1166older versions of @code{@value{AS}}. In future, @code{-R} may work this way. 1167 1168@ifset COFF 1169When @code{@value{AS}} is configured for COFF output, 1170this option is only useful if you use sections named @samp{.text} and 1171@samp{.data}. 1172@end ifset 1173 1174@ifset HPPA 1175@code{-R} is not supported for any of the HPPA targets. Using 1176@code{-R} generates a warning from @code{@value{AS}}. 1177@end ifset 1178 1179@node statistics 1180@section Display Assembly Statistics: @code{--statistics} 1181 1182@kindex --statistics 1183@cindex statistics, about assembly 1184@cindex time, total for assembly 1185@cindex space used, maximum for assembly 1186Use @samp{--statistics} to display two statistics about the resources used by 1187@code{@value{AS}}: the maximum amount of space allocated during the assembly 1188(in bytes), and the total execution time taken for the assembly (in @sc{cpu} 1189seconds). 1190 1191@node v 1192@section Announce Version: @code{-v} 1193 1194@kindex -v 1195@kindex -version 1196@cindex @code{@value{AS}} version 1197@cindex version of @code{@value{AS}} 1198You can find out what version of as is running by including the 1199option @samp{-v} (which you can also spell as @samp{-version}) on the 1200command line. 1201 1202@node W 1203@section Suppress Warnings: @code{-W} 1204 1205@kindex -W 1206@cindex suppressing warnings 1207@cindex warnings, suppressing 1208@code{@value{AS}} should never give a warning or error message when 1209assembling compiler output. But programs written by people often 1210cause @code{@value{AS}} to give a warning that a particular assumption was 1211made. All such warnings are directed to the standard error file. 1212If you use this option, no warnings are issued. This option only 1213affects the warning messages: it does not change any particular of how 1214@code{@value{AS}} assembles your file. Errors, which stop the assembly, are 1215still reported. 1216 1217@node Z 1218@section Generate Object File in Spite of Errors: @code{-Z} 1219@cindex object file, after errors 1220@cindex errors, continuing after 1221After an error message, @code{@value{AS}} normally produces no output. If for 1222some reason you are interested in object file output even after 1223@code{@value{AS}} gives an error message on your program, use the @samp{-Z} 1224option. If there are any errors, @code{@value{AS}} continues anyways, and 1225writes an object file after a final warning message of the form @samp{@var{n} 1226errors, @var{m} warnings, generating bad object file.} 1227 1228@node Syntax 1229@chapter Syntax 1230 1231@cindex machine-independent syntax 1232@cindex syntax, machine-independent 1233This chapter describes the machine-independent syntax allowed in a 1234source file. @code{@value{AS}} syntax is similar to what many other 1235assemblers use; it is inspired by the BSD 4.2 1236@ifclear VAX 1237assembler. 1238@end ifclear 1239@ifset VAX 1240assembler, except that @code{@value{AS}} does not assemble Vax bit-fields. 1241@end ifset 1242 1243@menu 1244* Preprocessing:: Preprocessing 1245* Whitespace:: Whitespace 1246* Comments:: Comments 1247* Symbol Intro:: Symbols 1248* Statements:: Statements 1249* Constants:: Constants 1250@end menu 1251 1252@node Preprocessing 1253@section Preprocessing 1254 1255@cindex preprocessing 1256The @code{@value{AS}} internal preprocessor: 1257@itemize @bullet 1258@cindex whitespace, removed by preprocessor 1259@item 1260adjusts and removes extra whitespace. It leaves one space or tab before 1261the keywords on a line, and turns any other whitespace on the line into 1262a single space. 1263 1264@cindex comments, removed by preprocessor 1265@item 1266removes all comments, replacing them with a single space, or an 1267appropriate number of newlines. 1268 1269@cindex constants, converted by preprocessor 1270@item 1271converts character constants into the appropriate numeric values. 1272@end itemize 1273 1274It does not do macro processing, include file handling, or 1275anything else you may get from your C compiler's preprocessor. You can 1276do include file processing with the @code{.include} directive 1277(@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver 1278to get other ``CPP'' style preprocessing, by giving the input file a 1279@samp{.S} suffix. @xref{Overall Options,, Options Controlling the Kind of 1280Output, gcc.info, Using GNU CC}. 1281 1282Excess whitespace, comments, and character constants 1283cannot be used in the portions of the input text that are not 1284preprocessed. 1285 1286@cindex turning preprocessing on and off 1287@cindex preprocessing, turning on and off 1288@kindex #NO_APP 1289@kindex #APP 1290If the first line of an input file is @code{#NO_APP} or if you use the 1291@samp{-f} option, whitespace and comments are not removed from the input file. 1292Within an input file, you can ask for whitespace and comment removal in 1293specific portions of the by putting a line that says @code{#APP} before the 1294text that may contain whitespace or comments, and putting a line that says 1295@code{#NO_APP} after this text. This feature is mainly intend to support 1296@code{asm} statements in compilers whose output is otherwise free of comments 1297and whitespace. 1298 1299@node Whitespace 1300@section Whitespace 1301 1302@cindex whitespace 1303@dfn{Whitespace} is one or more blanks or tabs, in any order. 1304Whitespace is used to separate symbols, and to make programs neater for 1305people to read. Unless within character constants 1306(@pxref{Characters,,Character Constants}), any whitespace means the same 1307as exactly one space. 1308 1309@node Comments 1310@section Comments 1311 1312@cindex comments 1313There are two ways of rendering comments to @code{@value{AS}}. In both 1314cases the comment is equivalent to one space. 1315 1316Anything from @samp{/*} through the next @samp{*/} is a comment. 1317This means you may not nest these comments. 1318 1319@smallexample 1320/* 1321 The only way to include a newline ('\n') in a comment 1322 is to use this sort of comment. 1323*/ 1324 1325/* This sort of comment does not nest. */ 1326@end smallexample 1327 1328@cindex line comment character 1329Anything from the @dfn{line comment} character to the next newline 1330is considered a comment and is ignored. The line comment character is 1331@ifset A29K 1332@samp{;} for the AMD 29K family; 1333@end ifset 1334@ifset H8/300 1335@samp{;} for the H8/300 family; 1336@end ifset 1337@ifset H8/500 1338@samp{!} for the H8/500 family; 1339@end ifset 1340@ifset HPPA 1341@samp{;} for the HPPA; 1342@end ifset 1343@ifset I960 1344@samp{#} on the i960; 1345@end ifset 1346@ifset SH 1347@samp{!} for the Hitachi SH; 1348@end ifset 1349@ifset SPARC 1350@samp{!} on the SPARC; 1351@end ifset 1352@ifset M680X0 1353@samp{|} on the 680x0; 1354@end ifset 1355@ifset VAX 1356@samp{#} on the Vax; 1357@end ifset 1358@ifset Z8000 1359@samp{!} for the Z8000; 1360@end ifset 1361see @ref{Machine Dependencies}. @refill 1362@c FIXME What about i386, m88k, i860? 1363 1364@ifset GENERIC 1365On some machines there are two different line comment characters. One 1366character only begins a comment if it is the first non-whitespace character on 1367a line, while the other always begins a comment. 1368@end ifset 1369 1370@kindex # 1371@cindex lines starting with @code{#} 1372@cindex logical line numbers 1373To be compatible with past assemblers, lines that begin with @samp{#} have a 1374special interpretation. Following the @samp{#} should be an absolute 1375expression (@pxref{Expressions}): the logical line number of the @emph{next} 1376line. Then a string (@pxref{Strings,, Strings}) is allowed: if present it is a 1377new logical file name. The rest of the line, if any, should be whitespace. 1378 1379If the first non-whitespace characters on the line are not numeric, 1380the line is ignored. (Just like a comment.) 1381 1382@smallexample 1383 # This is an ordinary comment. 1384# 42-6 "new_file_name" # New logical file name 1385 # This is logical line # 36. 1386@end smallexample 1387This feature is deprecated, and may disappear from future versions 1388of @code{@value{AS}}. 1389 1390@node Symbol Intro 1391@section Symbols 1392 1393@cindex characters used in symbols 1394@ifclear SPECIAL-SYMS 1395A @dfn{symbol} is one or more characters chosen from the set of all 1396letters (both upper and lower case), digits and the three characters 1397@samp{_.$}. 1398@end ifclear 1399@ifset SPECIAL-SYMS 1400@ifclear GENERIC 1401@ifset H8 1402A @dfn{symbol} is one or more characters chosen from the set of all 1403letters (both upper and lower case), digits and the three characters 1404@samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in 1405symbol names.) 1406@end ifset 1407@end ifclear 1408@end ifset 1409@ifset GENERIC 1410On most machines, you can also use @code{$} in symbol names; exceptions 1411are noted in @ref{Machine Dependencies}. 1412@end ifset 1413No symbol may begin with a digit. Case is significant. 1414There is no length limit: all characters are significant. Symbols are 1415delimited by characters not in that set, or by the beginning of a file 1416(since the source program must end with a newline, the end of a file is 1417not a possible symbol delimiter). @xref{Symbols}. 1418@cindex length of symbols 1419 1420@node Statements 1421@section Statements 1422 1423@cindex statements, structure of 1424@cindex line separator character 1425@cindex statement separator character 1426@ifclear GENERIC 1427@ifclear abnormal-separator 1428A @dfn{statement} ends at a newline character (@samp{\n}) or at a 1429semicolon (@samp{;}). The newline or semicolon is considered part of 1430the preceding statement. Newlines and semicolons within character 1431constants are an exception: they do not end statements. 1432@end ifclear 1433@ifset abnormal-separator 1434@ifset A29K 1435A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at'' 1436sign (@samp{@@}). The newline or at sign is considered part of the 1437preceding statement. Newlines and at signs within character constants 1438are an exception: they do not end statements. 1439@end ifset 1440@ifset HPPA 1441A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation 1442point (@samp{!}). The newline or exclamation point is considered part of the 1443preceding statement. Newlines and exclamation points within character 1444constants are an exception: they do not end statements. 1445@end ifset 1446@ifset H8 1447A @dfn{statement} ends at a newline character (@samp{\n}); or (for the 1448H8/300) a dollar sign (@samp{$}); or (for the 1449Hitachi-SH or the 1450H8/500) a semicolon 1451(@samp{;}). The newline or separator character is considered part of 1452the preceding statement. Newlines and separators within character 1453constants are an exception: they do not end statements. 1454@end ifset 1455@end ifset 1456@end ifclear 1457@ifset GENERIC 1458A @dfn{statement} ends at a newline character (@samp{\n}) or line 1459separator character. (The line separator is usually @samp{;}, unless 1460this conflicts with the comment character; @pxref{Machine Dependencies}.) The 1461newline or separator character is considered part of the preceding 1462statement. Newlines and separators within character constants are an 1463exception: they do not end statements. 1464@end ifset 1465 1466@cindex newline, required at file end 1467@cindex EOF, newline must precede 1468It is an error to end any statement with end-of-file: the last 1469character of any input file should be a newline.@refill 1470 1471@cindex continuing statements 1472@cindex multi-line statements 1473@cindex statement on multiple lines 1474You may write a statement on more than one line if you put a 1475backslash (@kbd{\}) immediately in front of any newlines within the 1476statement. When @code{@value{AS}} reads a backslashed newline both 1477characters are ignored. You can even put backslashed newlines in 1478the middle of symbol names without changing the meaning of your 1479source program. 1480 1481An empty statement is allowed, and may include whitespace. It is ignored. 1482 1483@cindex instructions and directives 1484@cindex directives and instructions 1485@c "key symbol" is not used elsewhere in the document; seems pedantic to 1486@c @defn{} it in that case, as was done previously... doc@cygnus.com, 1487@c 13feb91. 1488A statement begins with zero or more labels, optionally followed by a 1489key symbol which determines what kind of statement it is. The key 1490symbol determines the syntax of the rest of the statement. If the 1491symbol begins with a dot @samp{.} then the statement is an assembler 1492directive: typically valid for any computer. If the symbol begins with 1493a letter the statement is an assembly language @dfn{instruction}: it 1494assembles into a machine language instruction. 1495@ifset GENERIC 1496Different versions of @code{@value{AS}} for different computers 1497recognize different instructions. In fact, the same symbol may 1498represent a different instruction in a different computer's assembly 1499language.@refill 1500@end ifset 1501 1502@cindex @code{:} (label) 1503@cindex label (@code{:}) 1504A label is a symbol immediately followed by a colon (@code{:}). 1505Whitespace before a label or after a colon is permitted, but you may not 1506have whitespace between a label's symbol and its colon. @xref{Labels}. 1507 1508@ifset HPPA 1509For HPPA targets, labels need not be immediately followed by a colon, but 1510the definition of a label must begin in column zero. This also implies that 1511only one label may be defined on each line. 1512@end ifset 1513 1514@smallexample 1515label: .directive followed by something 1516another_label: # This is an empty statement. 1517 instruction operand_1, operand_2, @dots{} 1518@end smallexample 1519 1520@node Constants 1521@section Constants 1522 1523@cindex constants 1524A constant is a number, written so that its value is known by 1525inspection, without knowing any context. Like this: 1526@smallexample 1527@group 1528.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value. 1529.ascii "Ring the bell\7" # A string constant. 1530.octa 0x123456789abcdef0123456789ABCDEF0 # A bignum. 1531.float 0f-314159265358979323846264338327\ 153295028841971.693993751E-40 # - pi, a flonum. 1533@end group 1534@end smallexample 1535 1536@menu 1537* Characters:: Character Constants 1538* Numbers:: Number Constants 1539@end menu 1540 1541@node Characters 1542@subsection Character Constants 1543 1544@cindex character constants 1545@cindex constants, character 1546There are two kinds of character constants. A @dfn{character} stands 1547for one character in one byte and its value may be used in 1548numeric expressions. String constants (properly called string 1549@emph{literals}) are potentially many bytes and their values may not be 1550used in arithmetic expressions. 1551 1552@menu 1553* Strings:: Strings 1554* Chars:: Characters 1555@end menu 1556 1557@node Strings 1558@subsubsection Strings 1559 1560@cindex string constants 1561@cindex constants, string 1562A @dfn{string} is written between double-quotes. It may contain 1563double-quotes or null characters. The way to get special characters 1564into a string is to @dfn{escape} these characters: precede them with 1565a backslash @samp{\} character. For example @samp{\\} represents 1566one backslash: the first @code{\} is an escape which tells 1567@code{@value{AS}} to interpret the second character literally as a backslash 1568(which prevents @code{@value{AS}} from recognizing the second @code{\} as an 1569escape character). The complete list of escapes follows. 1570 1571@cindex escape codes, character 1572@cindex character escape codes 1573@table @kbd 1574@c @item \a 1575@c Mnemonic for ACKnowledge; for ASCII this is octal code 007. 1576@c 1577@cindex @code{\b} (backspace character) 1578@cindex backspace (@code{\b}) 1579@item \b 1580Mnemonic for backspace; for ASCII this is octal code 010. 1581 1582@c @item \e 1583@c Mnemonic for EOText; for ASCII this is octal code 004. 1584@c 1585@cindex @code{\f} (formfeed character) 1586@cindex formfeed (@code{\f}) 1587@item \f 1588Mnemonic for FormFeed; for ASCII this is octal code 014. 1589 1590@cindex @code{\n} (newline character) 1591@cindex newline (@code{\n}) 1592@item \n 1593Mnemonic for newline; for ASCII this is octal code 012. 1594 1595@c @item \p 1596@c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}. 1597@c 1598@cindex @code{\r} (carriage return character) 1599@cindex carriage return (@code{\r}) 1600@item \r 1601Mnemonic for carriage-Return; for ASCII this is octal code 015. 1602 1603@c @item \s 1604@c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with 1605@c other assemblers. 1606@c 1607@cindex @code{\t} (tab) 1608@cindex tab (@code{\t}) 1609@item \t 1610Mnemonic for horizontal Tab; for ASCII this is octal code 011. 1611 1612@c @item \v 1613@c Mnemonic for Vertical tab; for ASCII this is octal code 013. 1614@c @item \x @var{digit} @var{digit} @var{digit} 1615@c A hexadecimal character code. The numeric code is 3 hexadecimal digits. 1616@c 1617@cindex @code{\@var{ddd}} (octal character code) 1618@cindex octal character code (@code{\@var{ddd}}) 1619@item \ @var{digit} @var{digit} @var{digit} 1620An octal character code. The numeric code is 3 octal digits. 1621For compatibility with other Unix systems, 8 and 9 are accepted as digits: 1622for example, @code{\008} has the value 010, and @code{\009} the value 011. 1623 1624@cindex @code{\@var{xd...}} (hex character code) 1625@cindex hex character code (@code{\@var{xd...}}) 1626@item \@code{x} @var{hex-digits...} 1627A hex character code. All trailing hex digits are combined. Either upper or 1628lower case @code{x} works. 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 HPPA 1807The letter @samp{E} (upper case only). 1808@end ifset 1809@ifset I960 1810One of the letters @samp{DFT} (in upper or lower case). 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. 2984For the alpha, if the section is marked as containing code and the 2985padding expression is omitted, then the space is filled with no-ops. 2986 2987The way the required alignment is specified varies from system to system. 2988For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF 2989format, 2990the first expression is the 2991alignment request in bytes. For example @samp{.align 8} advances 2992the location counter until it is a multiple of 8. If the location counter 2993is already a multiple of 8, no change is needed. 2994 2995For other systems, including the i386 using a.out format, it is the 2996number of low-order zero bits the location counter must have after 2997advancement. For example @samp{.align 3} advances the location 2998counter until it a multiple of 8. If the location counter is already a 2999multiple of 8, no change is needed. 3000 3001This inconsistency is due to the different behaviors of the various 3002native assemblers for these systems which GAS must emulate. 3003GAS also provides @code{.balign} and @code{.p2align} directives, 3004described later, which have a consistent behavior across all 3005architectures (but are specific to GAS). 3006 3007@node App-File 3008@section @code{.app-file @var{string}} 3009 3010@cindex logical file name 3011@cindex file name, logical 3012@cindex @code{app-file} directive 3013@code{.app-file} 3014@ifclear no-file-dir 3015(which may also be spelled @samp{.file}) 3016@end ifclear 3017tells @code{@value{AS}} that we are about to start a new 3018logical file. @var{string} is the new file name. In general, the 3019filename is recognized whether or not it is surrounded by quotes @samp{"}; 3020but if you wish to specify an empty file name is permitted, 3021you must give the quotes--@code{""}. This statement may go away in 3022future: it is only recognized to be compatible with old @code{@value{AS}} 3023programs.@refill 3024 3025@node Ascii 3026@section @code{.ascii "@var{string}"}@dots{} 3027 3028@cindex @code{ascii} directive 3029@cindex string literals 3030@code{.ascii} expects zero or more string literals (@pxref{Strings}) 3031separated by commas. It assembles each string (with no automatic 3032trailing zero byte) into consecutive addresses. 3033 3034@node Asciz 3035@section @code{.asciz "@var{string}"}@dots{} 3036 3037@cindex @code{asciz} directive 3038@cindex zero-terminated strings 3039@cindex null-terminated strings 3040@code{.asciz} is just like @code{.ascii}, but each string is followed by 3041a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''. 3042 3043@node Balign 3044@section @code{.balign[wl] @var{abs-expr} , @var{abs-expr}} 3045 3046@cindex padding the location counter given number of bytes 3047@cindex @code{balign} directive 3048Pad the location counter (in the current subsection) to a particular 3049storage boundary. The first expression (which must be absolute) is the 3050alignment request in bytes. For example @samp{.balign 8} advances 3051the location counter until it is a multiple of 8. If the location counter 3052is already a multiple of 8, no change is needed. 3053 3054The second expression (also absolute) gives the value to be stored in 3055the padding bytes. It (and the comma) may be omitted. If it is 3056omitted, the padding bytes are zero. 3057 3058@cindex @code{balignw} directive 3059@cindex @code{balignl} directive 3060The @code{.balignw} and @code{.balignl} directives are variants of the 3061@code{.balign} directive. The @code{.balignw} directive treats the fill 3062pattern as a two byte word value. The @code{.balignl} directives treats the 3063fill pattern as a four byte longword value. For example, @code{.balignw 30644,0x368d} will align to a multiple of 4. If it skips two bytes, they will be 3065filled in with the value 0x368d (the exact placement of the bytes depends upon 3066the endianness of the processor). If it skips 1 or 3 bytes, the fill value is 3067undefined. 3068 3069@node Byte 3070@section @code{.byte @var{expressions}} 3071 3072@cindex @code{byte} directive 3073@cindex integers, one byte 3074@code{.byte} expects zero or more expressions, separated by commas. 3075Each expression is assembled into the next byte. 3076 3077@node Comm 3078@section @code{.comm @var{symbol} , @var{length} } 3079 3080@cindex @code{comm} directive 3081@cindex symbol, common 3082@code{.comm} declares a named common area in the bss section. Normally 3083@code{@value{LD}} reserves memory addresses for it during linking, so no partial 3084program defines the location of the symbol. Use @code{.comm} to tell 3085@code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}} 3086allocates space for each @code{.comm} symbol that is at least as 3087long as the longest @code{.comm} request in any of the partial programs 3088linked. @var{length} is an absolute expression. 3089 3090@ifset HPPA 3091The syntax for @code{.comm} differs slightly on the HPPA. The syntax is 3092@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional. 3093@end ifset 3094 3095@node Data 3096@section @code{.data @var{subsection}} 3097 3098@cindex @code{data} directive 3099@code{.data} tells @code{@value{AS}} to assemble the following statements onto the 3100end of the data subsection numbered @var{subsection} (which is an 3101absolute expression). If @var{subsection} is omitted, it defaults 3102to zero. 3103 3104@ifset COFF 3105@node Def 3106@section @code{.def @var{name}} 3107 3108@cindex @code{def} directive 3109@cindex COFF symbols, debugging 3110@cindex debugging COFF symbols 3111Begin defining debugging information for a symbol @var{name}; the 3112definition extends until the @code{.endef} directive is encountered. 3113@ifset BOUT 3114 3115This directive is only observed when @code{@value{AS}} is configured for COFF 3116format output; when producing @code{b.out}, @samp{.def} is recognized, 3117but ignored. 3118@end ifset 3119@end ifset 3120 3121@ifset aout-bout 3122@node Desc 3123@section @code{.desc @var{symbol}, @var{abs-expression}} 3124 3125@cindex @code{desc} directive 3126@cindex COFF symbol descriptor 3127@cindex symbol descriptor, COFF 3128This directive sets the descriptor of the symbol (@pxref{Symbol Attributes}) 3129to the low 16 bits of an absolute expression. 3130 3131@ifset COFF 3132The @samp{.desc} directive is not available when @code{@value{AS}} is 3133configured for COFF output; it is only for @code{a.out} or @code{b.out} 3134object format. For the sake of compatibility, @code{@value{AS}} accepts 3135it, but produces no output, when configured for COFF. 3136@end ifset 3137@end ifset 3138 3139@ifset COFF 3140@node Dim 3141@section @code{.dim} 3142 3143@cindex @code{dim} directive 3144@cindex COFF auxiliary symbol information 3145@cindex auxiliary symbol information, COFF 3146This directive is generated by compilers to include auxiliary debugging 3147information in the symbol table. It is only permitted inside 3148@code{.def}/@code{.endef} pairs. 3149@ifset BOUT 3150 3151@samp{.dim} is only meaningful when generating COFF format output; when 3152@code{@value{AS}} is generating @code{b.out}, it accepts this directive but 3153ignores it. 3154@end ifset 3155@end ifset 3156 3157@node Double 3158@section @code{.double @var{flonums}} 3159 3160@cindex @code{double} directive 3161@cindex floating point numbers (double) 3162@code{.double} expects zero or more flonums, separated by commas. It 3163assembles floating point numbers. 3164@ifset GENERIC 3165The exact kind of floating point numbers emitted depends on how 3166@code{@value{AS}} is configured. @xref{Machine Dependencies}. 3167@end ifset 3168@ifclear GENERIC 3169@ifset IEEEFLOAT 3170On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers 3171in @sc{ieee} format. 3172@end ifset 3173@end ifclear 3174 3175@node Eject 3176@section @code{.eject} 3177 3178@cindex @code{eject} directive 3179@cindex new page, in listings 3180@cindex page, in listings 3181@cindex listing control: new page 3182Force a page break at this point, when generating assembly listings. 3183 3184@node Else 3185@section @code{.else} 3186 3187@cindex @code{else} directive 3188@code{.else} is part of the @code{@value{AS}} support for conditional 3189assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section 3190of code to be assembled if the condition for the preceding @code{.if} 3191was false. 3192 3193@ignore 3194@node End, Endef, Else, Pseudo Ops 3195@section @code{.end} 3196 3197@cindex @code{end} directive 3198This doesn't do anything---but isn't an s_ignore, so I suspect it's 3199meant to do something eventually (which is why it isn't documented here 3200as "for compatibility with blah"). 3201@end ignore 3202 3203@ifset COFF 3204@node Endef 3205@section @code{.endef} 3206 3207@cindex @code{endef} directive 3208This directive flags the end of a symbol definition begun with 3209@code{.def}. 3210@ifset BOUT 3211 3212@samp{.endef} is only meaningful when generating COFF format output; if 3213@code{@value{AS}} is configured to generate @code{b.out}, it accepts this 3214directive but ignores it. 3215@end ifset 3216@end ifset 3217 3218@node Endif 3219@section @code{.endif} 3220 3221@cindex @code{endif} directive 3222@code{.endif} is part of the @code{@value{AS}} support for conditional assembly; 3223it marks the end of a block of code that is only assembled 3224conditionally. @xref{If,,@code{.if}}. 3225 3226@node Equ 3227@section @code{.equ @var{symbol}, @var{expression}} 3228 3229@cindex @code{equ} directive 3230@cindex assigning values to symbols 3231@cindex symbols, assigning values to 3232This directive sets the value of @var{symbol} to @var{expression}. 3233It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}. 3234 3235@ifset HPPA 3236The syntax for @code{equ} on the HPPA is 3237@samp{@var{symbol} .equ @var{expression}}. 3238@end ifset 3239 3240@node Extern 3241@section @code{.extern} 3242 3243@cindex @code{extern} directive 3244@code{.extern} is accepted in the source program---for compatibility 3245with other assemblers---but it is ignored. @code{@value{AS}} treats 3246all undefined symbols as external. 3247 3248@ifclear no-file-dir 3249@node File 3250@section @code{.file @var{string}} 3251 3252@cindex @code{file} directive 3253@cindex logical file name 3254@cindex file name, logical 3255@code{.file} (which may also be spelled @samp{.app-file}) tells 3256@code{@value{AS}} that we are about to start a new logical file. 3257@var{string} is the new file name. In general, the filename is 3258recognized whether or not it is surrounded by quotes @samp{"}; but if 3259you wish to specify an empty file name, you must give the 3260quotes--@code{""}. This statement may go away in future: it is only 3261recognized to be compatible with old @code{@value{AS}} programs. 3262@ifset A29K 3263In some configurations of @code{@value{AS}}, @code{.file} has already been 3264removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}. 3265@end ifset 3266@end ifclear 3267 3268@node Fill 3269@section @code{.fill @var{repeat} , @var{size} , @var{value}} 3270 3271@cindex @code{fill} directive 3272@cindex writing patterns in memory 3273@cindex patterns, writing in memory 3274@var{result}, @var{size} and @var{value} are absolute expressions. 3275This emits @var{repeat} copies of @var{size} bytes. @var{Repeat} 3276may be zero or more. @var{Size} may be zero or more, but if it is 3277more than 8, then it is deemed to have the value 8, compatible with 3278other people's assemblers. The contents of each @var{repeat} bytes 3279is taken from an 8-byte number. The highest order 4 bytes are 3280zero. The lowest order 4 bytes are @var{value} rendered in the 3281byte-order of an integer on the computer @code{@value{AS}} is assembling for. 3282Each @var{size} bytes in a repetition is taken from the lowest order 3283@var{size} bytes of this number. Again, this bizarre behavior is 3284compatible with other people's assemblers. 3285 3286@var{size} and @var{value} are optional. 3287If the second comma and @var{value} are absent, @var{value} is 3288assumed zero. If the first comma and following tokens are absent, 3289@var{size} is assumed to be 1. 3290 3291@node Float 3292@section @code{.float @var{flonums}} 3293 3294@cindex floating point numbers (single) 3295@cindex @code{float} directive 3296This directive assembles zero or more flonums, separated by commas. It 3297has the same effect as @code{.single}. 3298@ifset GENERIC 3299The exact kind of floating point numbers emitted depends on how 3300@code{@value{AS}} is configured. 3301@xref{Machine Dependencies}. 3302@end ifset 3303@ifclear GENERIC 3304@ifset IEEEFLOAT 3305On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers 3306in @sc{ieee} format. 3307@end ifset 3308@end ifclear 3309 3310@node Global 3311@section @code{.global @var{symbol}}, @code{.globl @var{symbol}} 3312 3313@cindex @code{global} directive 3314@cindex symbol, making visible to linker 3315@code{.global} makes the symbol visible to @code{@value{LD}}. If you define 3316@var{symbol} in your partial program, its value is made available to 3317other partial programs that are linked with it. Otherwise, 3318@var{symbol} takes its attributes from a symbol of the same name 3319from another file linked into the same program. 3320 3321Both spellings (@samp{.globl} and @samp{.global}) are accepted, for 3322compatibility with other assemblers. 3323 3324@ifset HPPA 3325On the HPPA, @code{.global} is not always enough to make it accessible to other 3326partial programs. You may need the HPPA-only @code{.EXPORT} directive as well. 3327@xref{HPPA Directives,, HPPA Assembler Directives}. 3328@end ifset 3329 3330@node hword 3331@section @code{.hword @var{expressions}} 3332 3333@cindex @code{hword} directive 3334@cindex integers, 16-bit 3335@cindex numbers, 16-bit 3336@cindex sixteen bit integers 3337This expects zero or more @var{expressions}, and emits 3338a 16 bit number for each. 3339 3340@ifset GENERIC 3341This directive is a synonym for @samp{.short}; depending on the target 3342architecture, it may also be a synonym for @samp{.word}. 3343@end ifset 3344@ifclear GENERIC 3345@ifset W32 3346This directive is a synonym for @samp{.short}. 3347@end ifset 3348@ifset W16 3349This directive is a synonym for both @samp{.short} and @samp{.word}. 3350@end ifset 3351@end ifclear 3352 3353@node Ident 3354@section @code{.ident} 3355 3356@cindex @code{ident} directive 3357This directive is used by some assemblers to place tags in object files. 3358@code{@value{AS}} simply accepts the directive for source-file 3359compatibility with such assemblers, but does not actually emit anything 3360for it. 3361 3362@node If 3363@section @code{.if @var{absolute expression}} 3364 3365@cindex conditional assembly 3366@cindex @code{if} directive 3367@code{.if} marks the beginning of a section of code which is only 3368considered part of the source program being assembled if the argument 3369(which must be an @var{absolute expression}) is non-zero. The end of 3370the conditional section of code must be marked by @code{.endif} 3371(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the 3372alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}). 3373 3374The following variants of @code{.if} are also supported: 3375@table @code 3376@cindex @code{ifdef} directive 3377@item .ifdef @var{symbol} 3378Assembles the following section of code if the specified @var{symbol} 3379has been defined. 3380 3381@ignore 3382@cindex @code{ifeqs} directive 3383@item .ifeqs 3384Not yet implemented. 3385@end ignore 3386 3387@cindex @code{ifndef} directive 3388@cindex @code{ifnotdef} directive 3389@item .ifndef @var{symbol} 3390@itemx .ifnotdef @var{symbol} 3391Assembles the following section of code if the specified @var{symbol} 3392has not been defined. Both spelling variants are equivalent. 3393 3394@ignore 3395@item ifnes 3396Not yet implemented. 3397@end ignore 3398@end table 3399 3400@node Include 3401@section @code{.include "@var{file}"} 3402 3403@cindex @code{include} directive 3404@cindex supporting files, including 3405@cindex files, including 3406This directive provides a way to include supporting files at specified 3407points in your source program. The code from @var{file} is assembled as 3408if it followed the point of the @code{.include}; when the end of the 3409included file is reached, assembly of the original file continues. You 3410can control the search paths used with the @samp{-I} command-line option 3411(@pxref{Invoking,,Command-Line Options}). Quotation marks are required 3412around @var{file}. 3413 3414@node Int 3415@section @code{.int @var{expressions}} 3416 3417@cindex @code{int} directive 3418@cindex integers, 32-bit 3419Expect zero or more @var{expressions}, of any section, separated by commas. 3420For each expression, emit a number that, at run time, is the value of that 3421expression. The byte order and bit size of the number depends on what kind 3422of target the assembly is for. 3423 3424@ifclear GENERIC 3425@ifset H8 3426On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit 3427integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits 342832-bit integers. 3429@end ifset 3430@end ifclear 3431 3432@node Irp 3433@section @code{.irp @var{symbol},@var{values}}@dots{} 3434 3435@cindex @code{irp} directive 3436Evaluate a sequence of statements assigning different values to @var{symbol}. 3437The sequence of statements starts at the @code{.irp} directive, and is 3438terminated by an @code{.endr} directive. For each @var{value}, @var{symbol} is 3439set to @var{value}, and the sequence of statements is assembled. If no 3440@var{value} is listed, the sequence of statements is assembled once, with 3441@var{symbol} set to the null string. To refer to @var{symbol} within the 3442sequence of statements, use @var{\symbol}. 3443 3444For example, assembling 3445 3446@example 3447 .irp param,1,2,3 3448 move d\param,sp@@- 3449 .endr 3450@end example 3451 3452is equivalent to assembling 3453 3454@example 3455 move d1,sp@@- 3456 move d2,sp@@- 3457 move d3,sp@@- 3458@end example 3459 3460@node Irpc 3461@section @code{.irpc @var{symbol},@var{values}}@dots{} 3462 3463@cindex @code{irpc} directive 3464Evaluate a sequence of statements assigning different values to @var{symbol}. 3465The sequence of statements starts at the @code{.irpc} directive, and is 3466terminated by an @code{.endr} directive. For each character in @var{value}, 3467@var{symbol} is set to the character, and the sequence of statements is 3468assembled. If no @var{value} is listed, the sequence of statements is 3469assembled once, with @var{symbol} set to the null string. To refer to 3470@var{symbol} within the sequence of statements, use @var{\symbol}. 3471 3472For example, assembling 3473 3474@example 3475 .irpc param,123 3476 move d\param,sp@@- 3477 .endr 3478@end example 3479 3480is equivalent to assembling 3481 3482@example 3483 move d1,sp@@- 3484 move d2,sp@@- 3485 move d3,sp@@- 3486@end example 3487 3488@node Lcomm 3489@section @code{.lcomm @var{symbol} , @var{length}} 3490 3491@cindex @code{lcomm} directive 3492@cindex local common symbols 3493@cindex symbols, local common 3494Reserve @var{length} (an absolute expression) bytes for a local common 3495denoted by @var{symbol}. The section and value of @var{symbol} are 3496those of the new local common. The addresses are allocated in the bss 3497section, so that at run-time the bytes start off zeroed. @var{Symbol} 3498is not declared global (@pxref{Global,,@code{.global}}), so is normally 3499not visible to @code{@value{LD}}. 3500 3501@ifset HPPA 3502The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is 3503@samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional. 3504@end ifset 3505 3506@node Lflags 3507@section @code{.lflags} 3508 3509@cindex @code{lflags} directive (ignored) 3510@code{@value{AS}} accepts this directive, for compatibility with other 3511assemblers, but ignores it. 3512 3513@ifclear no-line-dir 3514@node Line 3515@section @code{.line @var{line-number}} 3516 3517@cindex @code{line} directive 3518@end ifclear 3519@ifset no-line-dir 3520@node Ln 3521@section @code{.ln @var{line-number}} 3522 3523@cindex @code{ln} directive 3524@end ifset 3525@cindex logical line number 3526@ifset aout-bout 3527Change the logical line number. @var{line-number} must be an absolute 3528expression. The next line has that logical line number. Therefore any other 3529statements on the current line (after a statement separator character) are 3530reported as on logical line number @var{line-number} @minus{} 1. One day 3531@code{@value{AS}} will no longer support this directive: it is recognized only 3532for compatibility with existing assembler programs. 3533 3534@ifset GENERIC 3535@ifset A29K 3536@emph{Warning:} In the AMD29K configuration of @value{AS}, this command is 3537not available; use the synonym @code{.ln} in that context. 3538@end ifset 3539@end ifset 3540@end ifset 3541 3542@ifclear no-line-dir 3543Even though this is a directive associated with the @code{a.out} or 3544@code{b.out} object-code formats, @code{@value{AS}} still recognizes it 3545when producing COFF output, and treats @samp{.line} as though it 3546were the COFF @samp{.ln} @emph{if} it is found outside a 3547@code{.def}/@code{.endef} pair. 3548 3549Inside a @code{.def}, @samp{.line} is, instead, one of the directives 3550used by compilers to generate auxiliary symbol information for 3551debugging. 3552@end ifclear 3553 3554@node Linkonce 3555@section @code{.linkonce [@var{type}]} 3556@cindex COMDAT 3557@cindex @code{linkonce} directive 3558@cindex common sections 3559Mark the current section so that the linker only includes a single copy of it. 3560This may be used to include the same section in several different object files, 3561but ensure that the linker will only include it once in the final output file. 3562The @code{.linkonce} pseudo-op must be used for each instance of the section. 3563Duplicate sections are detected based on the section name, so it should be 3564unique. 3565 3566This directive is only supported by a few object file formats; as of this 3567writing, the only object file format which supports it is the Portable 3568Executable format used on Windows NT. 3569 3570The @var{type} argument is optional. If specified, it must be one of the 3571following strings. For example: 3572@smallexample 3573.linkonce same_size 3574@end smallexample 3575Not all types may be supported on all object file formats. 3576 3577@table @code 3578@item discard 3579Silently discard duplicate sections. This is the default. 3580 3581@item one_only 3582Warn if there are duplicate sections, but still keep only one copy. 3583 3584@item same_size 3585Warn if any of the duplicates have different sizes. 3586 3587@item same_contents 3588Warn if any of the duplicates do not have exactly the same contents. 3589@end table 3590 3591@node Ln 3592@section @code{.ln @var{line-number}} 3593 3594@cindex @code{ln} directive 3595@ifclear no-line-dir 3596@samp{.ln} is a synonym for @samp{.line}. 3597@end ifclear 3598@ifset no-line-dir 3599Tell @code{@value{AS}} to change the logical line number. @var{line-number} 3600must be an absolute expression. The next line has that logical 3601line number, so any other statements on the current line (after a 3602statement separator character @code{;}) are reported as on logical 3603line number @var{line-number} @minus{} 1. 3604@ifset BOUT 3605 3606This directive is accepted, but ignored, when @code{@value{AS}} is 3607configured for @code{b.out}; its effect is only associated with COFF 3608output format. 3609@end ifset 3610@end ifset 3611 3612@node MRI 3613@section @code{.mri @var{val}} 3614 3615@cindex @code{mri} directive 3616@cindex MRI mode, temporarily 3617If @var{val} is non-zero, this tells @code{@value{AS}} to enter MRI mode. If 3618@var{val} is zero, this tells @code{@value{AS}} to exit MRI mode. This change 3619affects code assembled until the next @code{.mri} directive, or until the end 3620of the file. @xref{M, MRI mode, MRI mode}. 3621 3622@node List 3623@section @code{.list} 3624 3625@cindex @code{list} directive 3626@cindex listing control, turning on 3627Control (in conjunction with the @code{.nolist} directive) whether or 3628not assembly listings are generated. These two directives maintain an 3629internal counter (which is zero initially). @code{.list} increments the 3630counter, and @code{.nolist} decrements it. Assembly listings are 3631generated whenever the counter is greater than zero. 3632 3633By default, listings are disabled. When you enable them (with the 3634@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}), 3635the initial value of the listing counter is one. 3636 3637@node Long 3638@section @code{.long @var{expressions}} 3639 3640@cindex @code{long} directive 3641@code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}. 3642 3643@ignore 3644@c no one seems to know what this is for or whether this description is 3645@c what it really ought to do 3646@node Lsym 3647@section @code{.lsym @var{symbol}, @var{expression}} 3648 3649@cindex @code{lsym} directive 3650@cindex symbol, not referenced in assembly 3651@code{.lsym} creates a new symbol named @var{symbol}, but does not put it in 3652the hash table, ensuring it cannot be referenced by name during the 3653rest of the assembly. This sets the attributes of the symbol to be 3654the same as the expression value: 3655@smallexample 3656@var{other} = @var{descriptor} = 0 3657@var{type} = @r{(section of @var{expression})} 3658@var{value} = @var{expression} 3659@end smallexample 3660@noindent 3661The new symbol is not flagged as external. 3662@end ignore 3663 3664@node Macro 3665@section @code{.macro} 3666 3667@cindex macros 3668The commands @code{.macro} and @code{.endm} allow you to define macros that 3669generate assembly output. For example, this definition specifies a macro 3670@code{sum} that puts a sequence of numbers into memory: 3671 3672@example 3673 .macro sum from=0, to=5 3674 .long \from 3675 .if \to-\from 3676 sum "(\from+1)",\to 3677 .endif 3678 .endm 3679@end example 3680 3681@noindent 3682With that definition, @samp{SUM 0,5} is equivalent to this assembly input: 3683 3684@example 3685 .long 0 3686 .long 1 3687 .long 2 3688 .long 3 3689 .long 4 3690 .long 5 3691@end example 3692 3693@ftable @code 3694@item .macro @var{macname} 3695@itemx .macro @var{macname} @var{macargs} @dots{} 3696@cindex @code{macro} directive 3697Begin the definition of a macro called @var{macname}. If your macro 3698definition requires arguments, specify their names after the macro name, 3699separated by commas or spaces. You can supply a default value for any 3700macro argument by following the name with @samp{=@var{deflt}}. For 3701example, these are all valid @code{.macro} statements: 3702 3703@table @code 3704@item .macro comm 3705Begin the definition of a macro called @code{comm}, which takes no 3706arguments. 3707 3708@item .macro plus1 p, p1 3709@itemx .macro plus1 p p1 3710Either statement begins the definition of a macro called @code{plus1}, 3711which takes two arguments; within the macro definition, write 3712@samp{\p} or @samp{\p1} to evaluate the arguments. 3713 3714@item .macro reserve_str p1=0 p2 3715Begin the definition of a macro called @code{reserve_str}, with two 3716arguments. The first argument has a default value, but not the second. 3717After the definition is complete, you can call the macro either as 3718@samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to 3719@var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str 3720,@var{b}} (with @samp{\p1} evaluating as the default, in this case 3721@samp{0}, and @samp{\p2} evaluating to @var{b}). 3722@end table 3723 3724When you call a macro, you can specify the argument values either by 3725position, or by keyword. For example, @samp{sum 9,17} is equivalent to 3726@samp{sum to=17, from=9}. 3727 3728@item .endm 3729@cindex @code{endm} directive 3730Mark the end of a macro definition. 3731 3732@item .exitm 3733@cindex @code{exitm} directive 3734Exit early from the current macro definition. 3735 3736@cindex number of macros executed 3737@cindex macros, count executed 3738@item \@@ 3739@code{@value{AS}} maintains a counter of how many macros it has 3740executed in this pseudo-variable; you can copy that number to your 3741output with @samp{\@@}, but @emph{only within a macro definition}. 3742 3743@ignore 3744@item LOCAL @var{name} [ , @dots{} ] 3745@emph{Warning: @code{LOCAL} is only available if you select ``alternate 3746macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,, 3747Alternate macro syntax}. 3748 3749Generate a string replacement for each of the @var{name} arguments, and 3750replace any instances of @var{name} in each macro expansion. The 3751replacement string is unique in the assembly, and different for each 3752separate macro expansion. @code{LOCAL} allows you to write macros that 3753define symbols, without fear of conflict between separate macro expansions. 3754@end ignore 3755@end ftable 3756 3757@node Nolist 3758@section @code{.nolist} 3759 3760@cindex @code{nolist} directive 3761@cindex listing control, turning off 3762Control (in conjunction with the @code{.list} directive) whether or 3763not assembly listings are generated. These two directives maintain an 3764internal counter (which is zero initially). @code{.list} increments the 3765counter, and @code{.nolist} decrements it. Assembly listings are 3766generated whenever the counter is greater than zero. 3767 3768@node Octa 3769@section @code{.octa @var{bignums}} 3770 3771@c FIXME: double size emitted for "octa" on i960, others? Or warn? 3772@cindex @code{octa} directive 3773@cindex integer, 16-byte 3774@cindex sixteen byte integer 3775This directive expects zero or more bignums, separated by commas. For each 3776bignum, it emits a 16-byte integer. 3777 3778The term ``octa'' comes from contexts in which a ``word'' is two bytes; 3779hence @emph{octa}-word for 16 bytes. 3780 3781@node Org 3782@section @code{.org @var{new-lc} , @var{fill}} 3783 3784@cindex @code{org} directive 3785@cindex location counter, advancing 3786@cindex advancing location counter 3787@cindex current address, advancing 3788Advance the location counter of the current section to 3789@var{new-lc}. @var{new-lc} is either an absolute expression or an 3790expression with the same section as the current subsection. That is, 3791you can't use @code{.org} to cross sections: if @var{new-lc} has the 3792wrong section, the @code{.org} directive is ignored. To be compatible 3793with former assemblers, if the section of @var{new-lc} is absolute, 3794@code{@value{AS}} issues a warning, then pretends the section of @var{new-lc} 3795is the same as the current subsection. 3796 3797@code{.org} may only increase the location counter, or leave it 3798unchanged; you cannot use @code{.org} to move the location counter 3799backwards. 3800 3801@c double negative used below "not undefined" because this is a specific 3802@c reference to "undefined" (as SEG_UNKNOWN is called in this manual) 3803@c section. doc@cygnus.com 18feb91 3804Because @code{@value{AS}} tries to assemble programs in one pass, @var{new-lc} 3805may not be undefined. If you really detest this restriction we eagerly await 3806a chance to share your improved assembler. 3807 3808Beware that the origin is relative to the start of the section, not 3809to the start of the subsection. This is compatible with other 3810people's assemblers. 3811 3812When the location counter (of the current subsection) is advanced, the 3813intervening bytes are filled with @var{fill} which should be an 3814absolute expression. If the comma and @var{fill} are omitted, 3815@var{fill} defaults to zero. 3816 3817@node P2align 3818@section @code{.p2align[wl] @var{abs-expr} , @var{abs-expr}} 3819 3820@cindex padding the location counter given a power of two 3821@cindex @code{p2align} directive 3822Pad the location counter (in the current subsection) to a particular 3823storage boundary. The first expression (which must be absolute) is the 3824number of low-order zero bits the location counter must have after 3825advancement. For example @samp{.p2align 3} advances the location 3826counter until it a multiple of 8. If the location counter is already a 3827multiple of 8, no change is needed. 3828 3829The second expression (also absolute) gives the value to be stored in 3830the padding bytes. It (and the comma) may be omitted. If it is 3831omitted, the padding bytes are zero. 3832 3833@cindex @code{p2alignw} directive 3834@cindex @code{p2alignl} directive 3835The @code{.p2alignw} and @code{.p2alignl} directives are variants of the 3836@code{.p2align} directive. The @code{.p2alignw} directive treats the fill 3837pattern as a two byte word value. The @code{.p2alignl} directives treats the 3838fill pattern as a four byte longword value. For example, @code{.p2alignw 38392,0x368d} will align to a multiple of 4. If it skips two bytes, they will be 3840filled in with the value 0x368d (the exact placement of the bytes depends upon 3841the endianness of the processor). If it skips 1 or 3 bytes, the fill value is 3842undefined. 3843 3844@node Psize 3845@section @code{.psize @var{lines} , @var{columns}} 3846 3847@cindex @code{psize} directive 3848@cindex listing control: paper size 3849@cindex paper size, for listings 3850Use this directive to declare the number of lines---and, optionally, the 3851number of columns---to use for each page, when generating listings. 3852 3853If you do not use @code{.psize}, listings use a default line-count 3854of 60. You may omit the comma and @var{columns} specification; the 3855default width is 200 columns. 3856 3857@code{@value{AS}} generates formfeeds whenever the specified number of 3858lines is exceeded (or whenever you explicitly request one, using 3859@code{.eject}). 3860 3861If you specify @var{lines} as @code{0}, no formfeeds are generated save 3862those explicitly specified with @code{.eject}. 3863 3864@node Quad 3865@section @code{.quad @var{bignums}} 3866 3867@cindex @code{quad} directive 3868@code{.quad} expects zero or more bignums, separated by commas. For 3869each bignum, it emits 3870@ifclear bignum-16 3871an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a 3872warning message; and just takes the lowest order 8 bytes of the bignum. 3873@cindex eight-byte integer 3874@cindex integer, 8-byte 3875 3876The term ``quad'' comes from contexts in which a ``word'' is two bytes; 3877hence @emph{quad}-word for 8 bytes. 3878@end ifclear 3879@ifset bignum-16 3880a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a 3881warning message; and just takes the lowest order 16 bytes of the bignum. 3882@cindex sixteen-byte integer 3883@cindex integer, 16-byte 3884@end ifset 3885 3886@node Rept 3887@section @code{.rept @var{count}} 3888 3889@cindex @code{rept} directive 3890Repeat the sequence of lines between the @code{.rept} directive and the next 3891@code{.endr} directive @var{count} times. 3892 3893For example, assembling 3894 3895@example 3896 .rept 3 3897 .long 0 3898 .endr 3899@end example 3900 3901is equivalent to assembling 3902 3903@example 3904 .long 0 3905 .long 0 3906 .long 0 3907@end example 3908 3909@node Sbttl 3910@section @code{.sbttl "@var{subheading}"} 3911 3912@cindex @code{sbttl} directive 3913@cindex subtitles for listings 3914@cindex listing control: subtitle 3915Use @var{subheading} as the title (third line, immediately after the 3916title line) when generating assembly listings. 3917 3918This directive affects subsequent pages, as well as the current page if 3919it appears within ten lines of the top of a page. 3920 3921@ifset COFF 3922@node Scl 3923@section @code{.scl @var{class}} 3924 3925@cindex @code{scl} directive 3926@cindex symbol storage class (COFF) 3927@cindex COFF symbol storage class 3928Set the storage-class value for a symbol. This directive may only be 3929used inside a @code{.def}/@code{.endef} pair. Storage class may flag 3930whether a symbol is static or external, or it may record further 3931symbolic debugging information. 3932@ifset BOUT 3933 3934The @samp{.scl} directive is primarily associated with COFF output; when 3935configured to generate @code{b.out} output format, @code{@value{AS}} 3936accepts this directive but ignores it. 3937@end ifset 3938@end ifset 3939 3940@ifset COFF 3941@node Section 3942@section @code{.section @var{name}, @var{subsection}} 3943 3944@cindex @code{section} directive 3945@cindex named section (COFF) 3946@cindex COFF named section 3947Assemble the following code into end of subsection numbered 3948@var{subsection} in the COFF named section @var{name}. If you omit 3949@var{subsection}, @code{@value{AS}} uses subsection number zero. 3950@samp{.section .text} is equivalent to the @code{.text} directive; 3951@samp{.section .data} is equivalent to the @code{.data} directive. 3952@ifset GENERIC 3953This directive is only supported for targets that actually support arbitrarily 3954named sections; on @code{a.out} targets, for example, it is not accepted, even 3955with a standard @code{a.out} section name as its parameter. 3956@end ifset 3957@end ifset 3958 3959@node Set 3960@section @code{.set @var{symbol}, @var{expression}} 3961 3962@cindex @code{set} directive 3963@cindex symbol value, setting 3964Set the value of @var{symbol} to @var{expression}. This 3965changes @var{symbol}'s value and type to conform to 3966@var{expression}. If @var{symbol} was flagged as external, it remains 3967flagged. (@xref{Symbol Attributes}.) 3968 3969You may @code{.set} a symbol many times in the same assembly. 3970 3971If you @code{.set} a global symbol, the value stored in the object 3972file is the last value stored into it. 3973 3974@ifset HPPA 3975The syntax for @code{set} on the HPPA is 3976@samp{@var{symbol} .set @var{expression}}. 3977@end ifset 3978 3979@node Short 3980@section @code{.short @var{expressions}} 3981 3982@cindex @code{short} directive 3983@ifset GENERIC 3984@code{.short} is normally the same as @samp{.word}. 3985@xref{Word,,@code{.word}}. 3986 3987In some configurations, however, @code{.short} and @code{.word} generate 3988numbers of different lengths; @pxref{Machine Dependencies}. 3989@end ifset 3990@ifclear GENERIC 3991@ifset W16 3992@code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}. 3993@end ifset 3994@ifset W32 3995This expects zero or more @var{expressions}, and emits 3996a 16 bit number for each. 3997@end ifset 3998@end ifclear 3999 4000@node Single 4001@section @code{.single @var{flonums}} 4002 4003@cindex @code{single} directive 4004@cindex floating point numbers (single) 4005This directive assembles zero or more flonums, separated by commas. It 4006has the same effect as @code{.float}. 4007@ifset GENERIC 4008The exact kind of floating point numbers emitted depends on how 4009@code{@value{AS}} is configured. @xref{Machine Dependencies}. 4010@end ifset 4011@ifclear GENERIC 4012@ifset IEEEFLOAT 4013On the @value{TARGET} family, @code{.single} emits 32-bit floating point 4014numbers in @sc{ieee} format. 4015@end ifset 4016@end ifclear 4017 4018@ifset COFF 4019@node Size 4020@section @code{.size} 4021 4022@cindex @code{size} directive 4023This directive is generated by compilers to include auxiliary debugging 4024information in the symbol table. It is only permitted inside 4025@code{.def}/@code{.endef} pairs. 4026@ifset BOUT 4027 4028@samp{.size} is only meaningful when generating COFF format output; when 4029@code{@value{AS}} is generating @code{b.out}, it accepts this directive but 4030ignores it. 4031@end ifset 4032@end ifset 4033 4034@ifclear no-space-dir 4035@node Skip 4036@section @code{.skip @var{size} , @var{fill}} 4037 4038@cindex @code{skip} directive 4039@cindex filling memory 4040This directive emits @var{size} bytes, each of value @var{fill}. Both 4041@var{size} and @var{fill} are absolute expressions. If the comma and 4042@var{fill} are omitted, @var{fill} is assumed to be zero. This is the same as 4043@samp{.space}. 4044 4045@node Space 4046@section @code{.space @var{size} , @var{fill}} 4047 4048@cindex @code{space} directive 4049@cindex filling memory 4050This directive emits @var{size} bytes, each of value @var{fill}. Both 4051@var{size} and @var{fill} are absolute expressions. If the comma 4052and @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same 4053as @samp{.skip}. 4054 4055@ifset HPPA 4056@quotation 4057@emph{Warning:} @code{.space} has a completely different meaning for HPPA 4058targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800 4059Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the 4060@code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives}, 4061for a summary. 4062@end quotation 4063@end ifset 4064@end ifclear 4065 4066@ifset A29K 4067@ifclear GENERIC 4068@node Space 4069@section @code{.space} 4070@cindex @code{space} directive 4071@end ifclear 4072On the AMD 29K, this directive is ignored; it is accepted for 4073compatibility with other AMD 29K assemblers. 4074 4075@quotation 4076@emph{Warning:} In most versions of the @sc{gnu} assembler, the directive 4077@code{.space} has the effect of @code{.block} @xref{Machine Dependencies}. 4078@end quotation 4079@end ifset 4080 4081@ifset have-stabs 4082@node Stab 4083@section @code{.stabd, .stabn, .stabs} 4084 4085@cindex symbolic debuggers, information for 4086@cindex @code{stab@var{x}} directives 4087There are three directives that begin @samp{.stab}. 4088All emit symbols (@pxref{Symbols}), for use by symbolic debuggers. 4089The symbols are not entered in the @code{@value{AS}} hash table: they 4090cannot be referenced elsewhere in the source file. 4091Up to five fields are required: 4092 4093@table @var 4094@item string 4095This is the symbol's name. It may contain any character except 4096@samp{\000}, so is more general than ordinary symbol names. Some 4097debuggers used to code arbitrarily complex structures into symbol names 4098using this field. 4099 4100@item type 4101An absolute expression. The symbol's type is set to the low 8 bits of 4102this expression. Any bit pattern is permitted, but @code{@value{LD}} 4103and debuggers choke on silly bit patterns. 4104 4105@item other 4106An absolute expression. The symbol's ``other'' attribute is set to the 4107low 8 bits of this expression. 4108 4109@item desc 4110An absolute expression. The symbol's descriptor is set to the low 16 4111bits of this expression. 4112 4113@item value 4114An absolute expression which becomes the symbol's value. 4115@end table 4116 4117If a warning is detected while reading a @code{.stabd}, @code{.stabn}, 4118or @code{.stabs} statement, the symbol has probably already been created; 4119you get a half-formed symbol in your object file. This is 4120compatible with earlier assemblers! 4121 4122@table @code 4123@cindex @code{stabd} directive 4124@item .stabd @var{type} , @var{other} , @var{desc} 4125 4126The ``name'' of the symbol generated is not even an empty string. 4127It is a null pointer, for compatibility. Older assemblers used a 4128null pointer so they didn't waste space in object files with empty 4129strings. 4130 4131The symbol's value is set to the location counter, 4132relocatably. When your program is linked, the value of this symbol 4133is the address of the location counter when the @code{.stabd} was 4134assembled. 4135 4136@cindex @code{stabn} directive 4137@item .stabn @var{type} , @var{other} , @var{desc} , @var{value} 4138The name of the symbol is set to the empty string @code{""}. 4139 4140@cindex @code{stabs} directive 4141@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value} 4142All five fields are specified. 4143@end table 4144@end ifset 4145@c end have-stabs 4146 4147@node String 4148@section @code{.string} "@var{str}" 4149 4150@cindex string, copying to object file 4151@cindex @code{string} directive 4152 4153Copy the characters in @var{str} to the object file. You may specify more than 4154one string to copy, separated by commas. Unless otherwise specified for a 4155particular machine, the assembler marks the end of each string with a 0 byte. 4156You can use any of the escape sequences described in @ref{Strings,,Strings}. 4157 4158@ifset COFF 4159@node Tag 4160@section @code{.tag @var{structname}} 4161 4162@cindex COFF structure debugging 4163@cindex structure debugging, COFF 4164@cindex @code{tag} directive 4165This directive is generated by compilers to include auxiliary debugging 4166information in the symbol table. It is only permitted inside 4167@code{.def}/@code{.endef} pairs. Tags are used to link structure 4168definitions in the symbol table with instances of those structures. 4169@ifset BOUT 4170 4171@samp{.tag} is only used when generating COFF format output; when 4172@code{@value{AS}} is generating @code{b.out}, it accepts this directive but 4173ignores it. 4174@end ifset 4175@end ifset 4176 4177@node Text 4178@section @code{.text @var{subsection}} 4179 4180@cindex @code{text} directive 4181Tells @code{@value{AS}} to assemble the following statements onto the end of 4182the text subsection numbered @var{subsection}, which is an absolute 4183expression. If @var{subsection} is omitted, subsection number zero 4184is used. 4185 4186@node Title 4187@section @code{.title "@var{heading}"} 4188 4189@cindex @code{title} directive 4190@cindex listing control: title line 4191Use @var{heading} as the title (second line, immediately after the 4192source file name and pagenumber) when generating assembly listings. 4193 4194This directive affects subsequent pages, as well as the current page if 4195it appears within ten lines of the top of a page. 4196 4197@ifset COFF 4198@node Type 4199@section @code{.type @var{int}} 4200 4201@cindex COFF symbol type 4202@cindex symbol type, COFF 4203@cindex @code{type} directive 4204This directive, permitted only within @code{.def}/@code{.endef} pairs, 4205records the integer @var{int} as the type attribute of a symbol table entry. 4206@ifset BOUT 4207 4208@samp{.type} is associated only with COFF format output; when 4209@code{@value{AS}} is configured for @code{b.out} output, it accepts this 4210directive but ignores it. 4211@end ifset 4212@end ifset 4213 4214@ifset COFF 4215@node Val 4216@section @code{.val @var{addr}} 4217 4218@cindex @code{val} directive 4219@cindex COFF value attribute 4220@cindex value attribute, COFF 4221This directive, permitted only within @code{.def}/@code{.endef} pairs, 4222records the address @var{addr} as the value attribute of a symbol table 4223entry. 4224@ifset BOUT 4225 4226@samp{.val} is used only for COFF output; when @code{@value{AS}} is 4227configured for @code{b.out}, it accepts this directive but ignores it. 4228@end ifset 4229@end ifset 4230 4231@node Word 4232@section @code{.word @var{expressions}} 4233 4234@cindex @code{word} directive 4235This directive expects zero or more @var{expressions}, of any section, 4236separated by commas. 4237@ifclear GENERIC 4238@ifset W32 4239For each expression, @code{@value{AS}} emits a 32-bit number. 4240@end ifset 4241@ifset W16 4242For each expression, @code{@value{AS}} emits a 16-bit number. 4243@end ifset 4244@end ifclear 4245@ifset GENERIC 4246 4247The size of the number emitted, and its byte order, 4248depend on what target computer the assembly is for. 4249@end ifset 4250 4251@c on amd29k, i960, sparc the "special treatment to support compilers" doesn't 4252@c happen---32-bit addressability, period; no long/short jumps. 4253@ifset DIFF-TBL-KLUGE 4254@cindex difference tables altered 4255@cindex altered difference tables 4256@quotation 4257@emph{Warning: Special Treatment to support Compilers} 4258@end quotation 4259 4260@ifset GENERIC 4261Machines with a 32-bit address space, but that do less than 32-bit 4262addressing, require the following special treatment. If the machine of 4263interest to you does 32-bit addressing (or doesn't require it; 4264@pxref{Machine Dependencies}), you can ignore this issue. 4265 4266@end ifset 4267In order to assemble compiler output into something that works, 4268@code{@value{AS}} occasionlly does strange things to @samp{.word} directives. 4269Directives of the form @samp{.word sym1-sym2} are often emitted by 4270compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a 4271directive of the form @samp{.word sym1-sym2}, and the difference between 4272@code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}} 4273creates a @dfn{secondary jump table}, immediately before the next label. 4274This secondary jump table is preceded by a short-jump to the 4275first byte after the secondary table. This short-jump prevents the flow 4276of control from accidentally falling into the new table. Inside the 4277table is a long-jump to @code{sym2}. The original @samp{.word} 4278contains @code{sym1} minus the address of the long-jump to 4279@code{sym2}. 4280 4281If there were several occurrences of @samp{.word sym1-sym2} before the 4282secondary jump table, all of them are adjusted. If there was a 4283@samp{.word sym3-sym4}, that also did not fit in sixteen bits, a 4284long-jump to @code{sym4} is included in the secondary jump table, 4285and the @code{.word} directives are adjusted to contain @code{sym3} 4286minus the address of the long-jump to @code{sym4}; and so on, for as many 4287entries in the original jump table as necessary. 4288 4289@ifset INTERNALS 4290@emph{This feature may be disabled by compiling @code{@value{AS}} with the 4291@samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse 4292assembly language programmers. 4293@end ifset 4294@end ifset 4295@c end DIFF-TBL-KLUGE 4296 4297@node Deprecated 4298@section Deprecated Directives 4299 4300@cindex deprecated directives 4301@cindex obsolescent directives 4302One day these directives won't work. 4303They are included for compatibility with older assemblers. 4304@table @t 4305@item .abort 4306@item .app-file 4307@item .line 4308@end table 4309 4310@ifset GENERIC 4311@node Machine Dependencies 4312@chapter Machine Dependent Features 4313 4314@cindex machine dependencies 4315The machine instruction sets are (almost by definition) different on 4316each machine where @code{@value{AS}} runs. Floating point representations 4317vary as well, and @code{@value{AS}} often supports a few additional 4318directives or command-line options for compatibility with other 4319assemblers on a particular platform. Finally, some versions of 4320@code{@value{AS}} support special pseudo-instructions for branch 4321optimization. 4322 4323This chapter discusses most of these differences, though it does not 4324include details on any machine's instruction set. For details on that 4325subject, see the hardware manufacturer's manual. 4326 4327@menu 4328@ifset A29K 4329* AMD29K-Dependent:: AMD 29K Dependent Features 4330@end ifset 4331@ifset H8/300 4332* H8/300-Dependent:: Hitachi H8/300 Dependent Features 4333@end ifset 4334@ifset H8/500 4335* H8/500-Dependent:: Hitachi H8/500 Dependent Features 4336@end ifset 4337@ifset HPPA 4338* HPPA-Dependent:: HPPA Dependent Features 4339@end ifset 4340@ifset I80386 4341* i386-Dependent:: Intel 80386 Dependent Features 4342@end ifset 4343@ifset I960 4344* i960-Dependent:: Intel 80960 Dependent Features 4345@end ifset 4346@ifset M680X0 4347* M68K-Dependent:: M680x0 Dependent Features 4348@end ifset 4349@ifset MIPS 4350* MIPS-Dependent:: MIPS Dependent Features 4351@end ifset 4352@ifset SH 4353* SH-Dependent:: Hitachi SH Dependent Features 4354@end ifset 4355@ifset SPARC 4356* Sparc-Dependent:: SPARC Dependent Features 4357@end ifset 4358@ifset Z8000 4359* Z8000-Dependent:: Z8000 Dependent Features 4360@end ifset 4361@ifset VAX 4362* Vax-Dependent:: VAX Dependent Features 4363@end ifset 4364@end menu 4365 4366@lowersections 4367@end ifset 4368 4369@c The following major nodes are *sections* in the GENERIC version, *chapters* 4370@c in single-cpu versions. This is mainly achieved by @lowersections. There is a 4371@c peculiarity: to preserve cross-references, there must be a node called 4372@c "Machine Dependencies". Hence the conditional nodenames in each 4373@c major node below. Node defaulting in makeinfo requires adjacency of 4374@c node and sectioning commands; hence the repetition of @chapter BLAH 4375@c in both conditional blocks. 4376 4377 4378@ifset A29K 4379@include c-a29k.texi 4380@end ifset 4381 4382@ifset Hitachi-all 4383@ifclear GENERIC 4384@node Machine Dependencies 4385@chapter Machine Dependent Features 4386 4387The machine instruction sets are different on each Hitachi chip family, 4388and there are also some syntax differences among the families. This 4389chapter describes the specific @code{@value{AS}} features for each 4390family. 4391 4392@menu 4393* H8/300-Dependent:: Hitachi H8/300 Dependent Features 4394* H8/500-Dependent:: Hitachi H8/500 Dependent Features 4395* SH-Dependent:: Hitachi SH Dependent Features 4396@end menu 4397@lowersections 4398@end ifclear 4399@end ifset 4400 4401 4402@ifset H8/300 4403@include c-h8300.texi 4404@end ifset 4405 4406@ifset H8/500 4407@include c-h8500.texi 4408@end ifset 4409 4410@ifset HPPA 4411@include c-hppa.texi 4412@end ifset 4413 4414@ifset I80386 4415@include c-i386.texi 4416@end ifset 4417 4418@ifset I960 4419@include c-i960.texi 4420@end ifset 4421 4422@ifset M680X0 4423@include c-m68k.texi 4424@end ifset 4425 4426@ifset MIPS 4427@include c-mips.texi 4428@end ifset 4429 4430@ifset NS32K 4431@include c-ns32k.texi 4432@end ifset 4433 4434@ifset SH 4435@include c-sh.texi 4436@end ifset 4437 4438@ifset SPARC 4439@include c-sparc.texi 4440@end ifset 4441 4442@ifset Z8000 4443@include c-z8k.texi 4444@end ifset 4445 4446@ifset VAX 4447@include c-vax.texi 4448@end ifset 4449 4450@ifset GENERIC 4451@c reverse effect of @down at top of generic Machine-Dep chapter 4452@raisesections 4453@end ifset 4454 4455@node Acknowledgements 4456@chapter Acknowledgements 4457 4458If you have contributed to @code{@value{AS}} and your name isn't listed here, 4459it is not meant as a slight. We just don't know about it. Send mail to the 4460maintainer, and we'll correct the situation. Currently 4461@c (January 1994), 4462the maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}). 4463 4464Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any 4465more details?} 4466 4467Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug 4468information and the 68k series machines, most of the preprocessing pass, and 4469extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}. 4470 4471K. Richard Pixley maintained GAS for a while, adding various enhancements and 4472many bug fixes, including merging support for several processors, breaking GAS 4473up to handle multiple object file format back ends (including heavy rewrite, 4474testing, an integration of the coff and b.out back ends), adding configuration 4475including heavy testing and verification of cross assemblers and file splits 4476and renaming, converted GAS to strictly ANSI C including full prototypes, added 4477support for m680[34]0 and cpu32, did considerable work on i960 including a COFF 4478port (including considerable amounts of reverse engineering), a SPARC opcode 4479file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know'' 4480assertions and made them work, much other reorganization, cleanup, and lint. 4481 4482Ken Raeburn wrote the high-level BFD interface code to replace most of the code 4483in format-specific I/O modules. 4484 4485The original VMS support was contributed by David L. Kashtan. Eric Youngdale 4486has done much work with it since. 4487 4488The Intel 80386 machine description was written by Eliot Dresselhaus. 4489 4490Minh Tran-Le at IntelliCorp contributed some AIX 386 support. 4491 4492The Motorola 88k machine description was contributed by Devon Bowen of Buffalo 4493University and Torbjorn Granlund of the Swedish Institute of Computer Science. 4494 4495Keith Knowles at the Open Software Foundation wrote the original MIPS back end 4496(@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support 4497(which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to 4498support a.out format. 4499 4500Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k, 4501tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by 4502Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to 4503use BFD for some low-level operations, for use with the H8/300 and AMD 29k 4504targets. 4505 4506John Gilmore built the AMD 29000 support, added @code{.include} support, and 4507simplified the configuration of which versions accept which directives. He 4508updated the 68k machine description so that Motorola's opcodes always produced 4509fixed-size instructions (e.g. @code{jsr}), while synthetic instructions 4510remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested 4511cross-compilation support, and one bug in relaxation that took a week and 4512required the proverbial one-bit fix. 4513 4514Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the 451568k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix), 4516added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and 4517PowerPC assembler, and made a few other minor patches. 4518 4519Steve Chamberlain made @code{@value{AS}} able to generate listings. 4520 4521Hewlett-Packard contributed support for the HP9000/300. 4522 4523Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) 4524along with a fairly extensive HPPA testsuite (for both SOM and ELF object 4525formats). This work was supported by both the Center for Software Science at 4526the University of Utah and Cygnus Support. 4527 4528Support for ELF format files has been worked on by Mark Eichin of Cygnus 4529Support (original, incomplete implementation for SPARC), Pete Hoogenboom and 4530Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open 4531Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc, 4532and some initial 64-bit support). 4533 4534Richard Henderson rewrote the Alpha assembler. 4535 4536Several engineers at Cygnus Support have also provided many small bug fixes and 4537configuration enhancements. 4538 4539Many others have contributed large or small bugfixes and enhancements. If 4540you have contributed significant work and are not mentioned on this list, and 4541want to be, let us know. Some of the history has been lost; we are not 4542intentionally leaving anyone out. 4543 4544@node Index 4545@unnumbered Index 4546 4547@printindex cp 4548 4549@contents 4550@bye 4551@c Local Variables: 4552@c fill-column: 79 4553@c End: 4554