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