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