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