1.Dd 2015-03-02 2.Dt AS 7 3.Os 4.Sh NAME 5.Nm as 6.Nd Using as (machine specific) 7.Sh Using as 8This file is a user guide to the GNU assembler 9.Xr as 10version "2.17.50 [FreeBSD] 2007-07-03". This version of the file describes 11.Xr as 12configured to generate code for machine specific architectures. 13.Pp 14This document is distributed under the terms of the GNU Free Documentation 15License. A copy of the license is included in the section entitled \(lqGNU Free 16Documentation License\(rq. 17.Pp 18.Sh Overview 19Here is a brief summary of how to invoke 20.Xr as . 21For details, see Invoking,,Command-Line Options. 22.Pp 23.Bd -literal -offset indent 24as [-a[cdhlns][=file]] [--alternate] [-D] 25 [--defsym sym=val] [-f] [-g] [--gstabs] 26 [--gstabs+] [--gdwarf-2] [--help] [-I dir] [-J] 27 [-K] [-L] [--listing-lhs-width=NUM] 28 [--listing-lhs-width2=NUM] [--listing-rhs-width=NUM] 29 [--listing-cont-lines=NUM] [--keep-locals] [-o 30 objfile] [-R] [--reduce-memory-overheads] [--statistics] 31 [-v] [-version] [--version] [-W] [--warn] 32 [--fatal-warnings] [-w] [-x] [-Z] [@FILE] 33 [--target-help] [target-options] 34 [--|files ...] 35 36Target ARM options: 37 [-mcpu=processor[+extension...]] 38 [-march=architecture[+extension...]] 39 [-mfpu=floating-point-format] 40 [-mfloat-abi=abi] 41 [-meabi=ver] 42 [-mthumb] 43 [-EB|-EL] 44 [-mapcs-32|-mapcs-26|-mapcs-float| 45 -mapcs-reentrant] 46 [-mthumb-interwork] [-k] 47 48 49Target i386 options: 50 [--32|--64] [-n] 51 [-march=CPU] [-mtune=CPU] 52 53 54Target IA-64 options: 55 [-mconstant-gp|-mauto-pic] 56 [-milp32|-milp64|-mlp64|-mp64] 57 [-mle|mbe] 58 [-mtune=itanium1|-mtune=itanium2] 59 [-munwind-check=warning|-munwind-check=error] 60 [-mhint.b=ok|-mhint.b=warning|-mhint.b=error] 61 [-x|-xexplicit] [-xauto] [-xdebug] 62 63 64Target MIPS options: 65 [-nocpp] [-EL] [-EB] [-O[optimization level]] 66 [-g[debug level]] [-G num] [-KPIC] [-call_shared] 67 [-non_shared] [-xgot [-mvxworks-pic] 68 [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32] 69 [-march=CPU] [-mtune=CPU] [-mips1] [-mips2] 70 [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2] 71 [-mips64] [-mips64r2] 72 [-construct-floats] [-no-construct-floats] 73 [-trap] [-no-break] [-break] [-no-trap] 74 [-mfix7000] [-mno-fix7000] 75 [-mips16] [-no-mips16] 76 [-msmartmips] [-mno-smartmips] 77 [-mips3d] [-no-mips3d] 78 [-mdmx] [-no-mdmx] 79 [-mdsp] [-mno-dsp] 80 [-mdspr2] [-mno-dspr2] 81 [-mmt] [-mno-mt] 82 [-mdebug] [-no-mdebug] 83 [-mpdr] [-mno-pdr] 84 85 86Target PowerPC options: 87 [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604| 88 -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke| 89 -mbooke32|-mbooke64] 90 [-mcom|-many|-maltivec] [-memb] 91 [-mregnames|-mno-regnames] 92 [-mrelocatable|-mrelocatable-lib] 93 [-mlittle|-mlittle-endian|-mbig|-mbig-endian] 94 [-msolaris|-mno-solaris] 95 96 97Target SPARC options: 98 [-Av6|-Av7|-Av8|-Asparclet|-Asparclite 99 -Av8plus|-Av8plusa|-Av9|-Av9a] 100 [-xarch=v8plus|-xarch=v8plusa] [-bump] 101 [-32|-64] 102 103 104 105.Ed 106.Pp 107.Bl -tag -width Ds 108.It @ Va file 109Read command-line options from 110.Va file . 111The options read are inserted in place of the original @ 112.Va file 113option. If 114.Va file 115does not exist, or cannot be read, then the option will be treated literally, 116and not removed. 117.Pp 118Options in 119.Va file 120are separated by whitespace. A whitespace character may be included in an 121option by surrounding the entire option in either single or double quotes. 122Any character (including a backslash) may be included by prefixing the character 123to be included with a backslash. The 124.Va file 125may itself contain additional @ 126.Va file 127options; any such options will be processed recursively. 128.Pp 129.It -a[cdhlmns] 130Turn on listings, in any of a variety of ways: 131.Pp 132.Bl -tag -width Ds 133.It -ac 134omit false conditionals 135.Pp 136.It -ad 137omit debugging directives 138.Pp 139.It -ah 140include high-level source 141.Pp 142.It -al 143include assembly 144.Pp 145.It -am 146include macro expansions 147.Pp 148.It -an 149omit forms processing 150.Pp 151.It -as 152include symbols 153.Pp 154.It =file 155set the name of the listing file 156.El 157.Pp 158You may combine these options; for example, use 159.Li -aln 160for assembly listing without forms processing. The 161.Li =file 162option, if used, must be the last one. By itself, 163.Li -a 164defaults to 165.Li -ahls . 166.Pp 167.It --alternate 168Begin in alternate macro mode.See Section 169.Dq Altmacro . 170.Pp 171.It -D 172Ignored. This option is accepted for script compatibility with calls to other 173assemblers. 174.Pp 175.It --defsym Va sym= Va value 176Define the symbol 177.Va sym 178to be 179.Va value 180before assembling the input file. 181.Va value 182must be an integer constant. As in C, a leading 183.Li 0x 184indicates a hexadecimal value, and a leading 185.Li 0 186indicates an octal value. The value of the symbol can be overridden inside 187a source file via the use of a 188.Li .set 189pseudo-op. 190.Pp 191.It -f 192\(lqfast\(rq---skip whitespace and comment preprocessing (assume source is compiler 193output). 194.Pp 195.It -g 196.It --gen-debug 197Generate debugging information for each assembler source line using whichever 198debug format is preferred by the target. This currently means either STABS, 199ECOFF or DWARF2. 200.Pp 201.It --gstabs 202Generate stabs debugging information for each assembler line. This may help 203debugging assembler code, if the debugger can handle it. 204.Pp 205.It --gstabs+ 206Generate stabs debugging information for each assembler line, with GNU extensions 207that probably only gdb can handle, and that could make other debuggers crash 208or refuse to read your program. This may help debugging assembler code. Currently 209the only GNU extension is the location of the current working directory at 210assembling time. 211.Pp 212.It --gdwarf-2 213Generate DWARF2 debugging information for each assembler line. This may help 214debugging assembler code, if the debugger can handle it. Note---this option 215is only supported by some targets, not all of them. 216.Pp 217.It --help 218Print a summary of the command line options and exit. 219.Pp 220.It --target-help 221Print a summary of all target specific options and exit. 222.Pp 223.It -I Va dir 224Add directory 225.Va dir 226to the search list for 227.Li .include 228directives. 229.Pp 230.It -J 231Don't warn about signed overflow. 232.Pp 233.It -K 234This option is accepted but has no effect on the machine specific family. 235.Pp 236.It -L 237.It --keep-locals 238Keep (in the symbol table) local symbols. These symbols start with system-specific 239local label prefixes, typically 240.Li .L 241for ELF systems or 242.Li L 243for traditional a.out systems.See Section 244.Dq Symbol Names . 245.Pp 246.It --listing-lhs-width= Va number 247Set the maximum width, in words, of the output data column for an assembler 248listing to 249.Va number . 250.Pp 251.It --listing-lhs-width2= Va number 252Set the maximum width, in words, of the output data column for continuation 253lines in an assembler listing to 254.Va number . 255.Pp 256.It --listing-rhs-width= Va number 257Set the maximum width of an input source line, as displayed in a listing, 258to 259.Va number 260bytes. 261.Pp 262.It --listing-cont-lines= Va number 263Set the maximum number of lines printed in a listing for a single line of 264input to 265.Va number 266+ 1. 267.Pp 268.It -o Va objfile 269Name the object-file output from 270.Xr as 271.Va objfile . 272.Pp 273.It -R 274Fold the data section into the text section. 275.Pp 276Set the default size of GAS's hash tables to a prime number close to 277.Va number . 278Increasing this value can reduce the length of time it takes the assembler 279to perform its tasks, at the expense of increasing the assembler's memory 280requirements. Similarly reducing this value can reduce the memory requirements 281at the expense of speed. 282.Pp 283.It --reduce-memory-overheads 284This option reduces GAS's memory requirements, at the expense of making the 285assembly processes slower. Currently this switch is a synonym for 286.Li --hash-size=4051 , 287but in the future it may have other effects as well. 288.Pp 289.It --statistics 290Print the maximum space (in bytes) and total time (in seconds) used by assembly. 291.Pp 292.It --strip-local-absolute 293Remove local absolute symbols from the outgoing symbol table. 294.Pp 295.It -v 296.It -version 297Print the 298.Xr as 299version. 300.Pp 301.It --version 302Print the 303.Xr as 304version and exit. 305.Pp 306.It -W 307.It --no-warn 308Suppress warning messages. 309.Pp 310.It --fatal-warnings 311Treat warnings as errors. 312.Pp 313.It --warn 314Don't suppress warning messages or treat them as errors. 315.Pp 316.It -w 317Ignored. 318.Pp 319.It -x 320Ignored. 321.Pp 322.It -Z 323Generate an object file even after errors. 324.Pp 325.It -- | Va files ... 326Standard input, or source files to assemble. 327.Pp 328.El 329The following options are available when as is configured for the ARM processor 330family. 331.Pp 332.Bl -tag -width Ds 333.It -mcpu= Va processor[+ Va extension...] 334Specify which ARM processor variant is the target. 335.It -march= Va architecture[+ Va extension...] 336Specify which ARM architecture variant is used by the target. 337.It -mfpu= Va floating-point-format 338Select which Floating Point architecture is the target. 339.It -mfloat-abi= Va abi 340Select which floating point ABI is in use. 341.It -mthumb 342Enable Thumb only instruction decoding. 343.It -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant 344Select which procedure calling convention is in use. 345.It -EB | -EL 346Select either big-endian (-EB) or little-endian (-EL) output. 347.It -mthumb-interwork 348Specify that the code has been generated with interworking between Thumb and 349ARM code in mind. 350.It -k 351Specify that PIC code has been generated. 352.El 353.Pp 354The following options are available when 355.Xr as 356is configured for the SPARC architecture: 357.Pp 358.Bl -tag -width Ds 359.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite 360.It -Av8plus | -Av8plusa | -Av9 | -Av9a 361Explicitly select a variant of the SPARC architecture. 362.Pp 363.Li -Av8plus 364and 365.Li -Av8plusa 366select a 32 bit environment. 367.Li -Av9 368and 369.Li -Av9a 370select a 64 bit environment. 371.Pp 372.Li -Av8plusa 373and 374.Li -Av9a 375enable the SPARC V9 instruction set with UltraSPARC extensions. 376.Pp 377.It -xarch=v8plus | -xarch=v8plusa 378For compatibility with the Solaris v9 assembler. These options are equivalent 379to -Av8plus and -Av8plusa, respectively. 380.Pp 381.It -bump 382Warn when the assembler switches to another architecture. 383.El 384.Pp 385The following options are available when as is configured for a mips processor. 386.Pp 387.Bl -tag -width Ds 388.It -G Va num 389This option sets the largest size of an object that can be referenced implicitly 390with the 391.Li gp 392register. It is only accepted for targets that use ECOFF format, such as a 393DECstation running Ultrix. The default value is 8. 394.Pp 395.It -EB 396Generate \(lqbig endian\(rq format output. 397.Pp 398.It -EL 399Generate \(lqlittle endian\(rq format output. 400.Pp 401.It -mips1 402.It -mips2 403.It -mips3 404.It -mips4 405.It -mips5 406.It -mips32 407.It -mips32r2 408.It -mips64 409.It -mips64r2 410Generate code for a particular mips Instruction Set Architecture level. 411.Li -mips1 412is an alias for 413.Li -march=r3000 , 414.Li -mips2 415is an alias for 416.Li -march=r6000 , 417.Li -mips3 418is an alias for 419.Li -march=r4000 420and 421.Li -mips4 422is an alias for 423.Li -march=r8000 . 424.Li -mips5 , 425.Li -mips32 , 426.Li -mips32r2 , 427.Li -mips64 , 428and 429.Li -mips64r2 430correspond to generic 431.Li MIPS V , 432.Li MIPS32 , 433.Li MIPS32 Release 2 , 434.Li MIPS64 , 435and 436.Li MIPS64 Release 2 437ISA processors, respectively. 438.Pp 439.It -march= Va CPU 440Generate code for a particular mips cpu. 441.Pp 442.It -mtune= Va cpu 443Schedule and tune for a particular mips cpu. 444.Pp 445.It -mfix7000 446.It -mno-fix7000 447Cause nops to be inserted if the read of the destination register of an mfhi 448or mflo instruction occurs in the following two instructions. 449.Pp 450.It -mdebug 451.It -no-mdebug 452Cause stabs-style debugging output to go into an ECOFF-style .mdebug section 453instead of the standard ELF .stabs sections. 454.Pp 455.It -mpdr 456.It -mno-pdr 457Control generation of 458.Li .pdr 459sections. 460.Pp 461.It -mgp32 462.It -mfp32 463The register sizes are normally inferred from the ISA and ABI, but these flags 464force a certain group of registers to be treated as 32 bits wide at all times. 465.Li -mgp32 466controls the size of general-purpose registers and 467.Li -mfp32 468controls the size of floating-point registers. 469.Pp 470.It -mips16 471.It -no-mips16 472Generate code for the MIPS 16 processor. This is equivalent to putting 473.Li .set mips16 474at the start of the assembly file. 475.Li -no-mips16 476turns off this option. 477.Pp 478.It -msmartmips 479.It -mno-smartmips 480Enables the SmartMIPS extension to the MIPS32 instruction set. This is equivalent 481to putting 482.Li .set smartmips 483at the start of the assembly file. 484.Li -mno-smartmips 485turns off this option. 486.Pp 487.It -mips3d 488.It -no-mips3d 489Generate code for the MIPS-3D Application Specific Extension. This tells the 490assembler to accept MIPS-3D instructions. 491.Li -no-mips3d 492turns off this option. 493.Pp 494.It -mdmx 495.It -no-mdmx 496Generate code for the MDMX Application Specific Extension. This tells the 497assembler to accept MDMX instructions. 498.Li -no-mdmx 499turns off this option. 500.Pp 501.It -mdsp 502.It -mno-dsp 503Generate code for the DSP Release 1 Application Specific Extension. This tells 504the assembler to accept DSP Release 1 instructions. 505.Li -mno-dsp 506turns off this option. 507.Pp 508.It -mdspr2 509.It -mno-dspr2 510Generate code for the DSP Release 2 Application Specific Extension. This option 511implies -mdsp. This tells the assembler to accept DSP Release 2 instructions. 512.Li -mno-dspr2 513turns off this option. 514.Pp 515.It -mmt 516.It -mno-mt 517Generate code for the MT Application Specific Extension. This tells the assembler 518to accept MT instructions. 519.Li -mno-mt 520turns off this option. 521.Pp 522.It --construct-floats 523.It --no-construct-floats 524The 525.Li --no-construct-floats 526option disables the construction of double width floating point constants 527by loading the two halves of the value into the two single width floating 528point registers that make up the double width register. By default 529.Li --construct-floats 530is selected, allowing construction of these floating point constants. 531.Pp 532.It --emulation= Va name 533This option causes 534.Xr as 535to emulate 536.Xr as 537configured for some other target, in all respects, including output format 538(choosing between ELF and ECOFF only), handling of pseudo-opcodes which may 539generate debugging information or store symbol table information, and default 540endianness. The available configuration names are: 541.Li mipsecoff , 542.Li mipself , 543.Li mipslecoff , 544.Li mipsbecoff , 545.Li mipslelf , 546.Li mipsbelf . 547The first two do not alter the default endianness from that of the primary 548target for which the assembler was configured; the others change the default 549to little- or big-endian as indicated by the 550.Li b 551or 552.Li l 553in the name. Using 554.Li -EB 555or 556.Li -EL 557will override the endianness selection in any case. 558.Pp 559This option is currently supported only when the primary target 560.Xr as 561is configured for is a mips ELF or ECOFF target. Furthermore, the primary 562target or others specified with 563.Li --enable-targets=... 564at configuration time must include support for the other format, if both are 565to be available. For example, the Irix 5 configuration includes support for 566both. 567.Pp 568Eventually, this option will support more configurations, with more fine-grained 569control over the assembler's behavior, and will be supported for more processors. 570.Pp 571.It -nocpp 572.Xr as 573ignores this option. It is accepted for compatibility with the native tools. 574.Pp 575.It --trap 576.It --no-trap 577.It --break 578.It --no-break 579Control how to deal with multiplication overflow and division by zero. 580.Li --trap 581or 582.Li --no-break 583(which are synonyms) take a trap exception (and only work for Instruction 584Set Architecture level 2 and higher); 585.Li --break 586or 587.Li --no-trap 588(also synonyms, and the default) take a break exception. 589.Pp 590.It -n 591When this option is used, 592.Xr as 593will issue a warning every time it generates a nop instruction from a macro. 594.El 595.Pp 596.Ss Structure of this Manual 597This manual is intended to describe what you need to know to use GNU 598.Xr as . 599We cover the syntax expected in source files, including notation for symbols, 600constants, and expressions; the directives that 601.Xr as 602understands; and of course how to invoke 603.Xr as . 604.Pp 605We also cover special features in the machine specific configuration of 606.Xr as , 607including assembler directives. 608.Pp 609On the other hand, this manual is 610.Em not 611intended as an introduction to programming in assembly language---let alone 612programming in general! In a similar vein, we make no attempt to introduce 613the machine architecture; we do 614.Em not 615describe the instruction set, standard mnemonics, registers or addressing 616modes that are standard to a particular architecture. 617.Pp 618.Ss The GNU Assembler 619GNU 620.Xr as 621is really a family of assemblers. This manual describes 622.Xr as , 623a member of that family which is configured for the machine specific architectures. 624If you use (or have used) the GNU assembler on one architecture, you should 625find a fairly similar environment when you use it on another architecture. 626Each version has much in common with the others, including object file formats, 627most assembler directives (often called 628.Em pseudo-ops ) 629and assembler syntax. 630.Pp 631.Xr as 632is primarily intended to assemble the output of the GNU C compiler 633.Li gcc 634for use by the linker 635.Li ld . 636Nevertheless, we've tried to make 637.Xr as 638assemble correctly everything that other assemblers for the same machine would 639assemble. 640.Pp 641Unlike older assemblers, 642.Xr as 643is designed to assemble a source program in one pass of the source file. This 644has a subtle impact on the 645.Li .org 646directive (see Section 647.Dq Org ) . 648.Pp 649.Ss Object File Formats 650The GNU assembler can be configured to produce several alternative object 651file formats. For the most part, this does not affect how you write assembly 652language programs; but directives for debugging symbols are typically different 653in different file formats.See Section 654.Dq Symbol Attributes . 655For the machine specific target, 656.Xr as 657is configured to produce ELF format object files. 658.Pp 659.Ss Command Line 660After the program name 661.Xr as , 662the command line may contain options and file names. Options may appear in 663any order, and may be before, after, or between file names. The order of file 664names is significant. 665.Pp 666.Pa -- 667(two hyphens) by itself names the standard input file explicitly, as one of 668the files for 669.Xr as 670to assemble. 671.Pp 672Except for 673.Li -- 674any command line argument that begins with a hyphen ( 675.Li - ) 676is an option. Each option changes the behavior of 677.Xr as . 678No option changes the way another option works. An option is a 679.Li - 680followed by one or more letters; the case of the letter is important. All 681options are optional. 682.Pp 683Some options expect exactly one file name to follow them. The file name may 684either immediately follow the option's letter (compatible with older assemblers) 685or it may be the next command argument (GNU standard). These two command lines 686are equivalent: 687.Pp 688.Bd -literal -offset indent 689as -o my-object-file.o mumble.s 690as -omy-object-file.o mumble.s 691.Ed 692.Pp 693.Ss Input Files 694We use the phrase 695.Em source program , 696abbreviated 697.Em source , 698to describe the program input to one run of 699.Xr as . 700The program may be in one or more files; how the source is partitioned into 701files doesn't change the meaning of the source. 702.Pp 703The source program is a concatenation of the text in all the files, in the 704order specified. 705.Pp 706Each time you run 707.Xr as 708it assembles exactly one source program. The source program is made up of 709one or more files. (The standard input is also a file.) 710.Pp 711You give 712.Xr as 713a command line that has zero or more input file names. The input files are 714read (from left file name to right). A command line argument (in any position) 715that has no special meaning is taken to be an input file name. 716.Pp 717If you give 718.Xr as 719no file names it attempts to read one input file from the 720.Xr as 721standard input, which is normally your terminal. You may have to type ctl-D 722to tell 723.Xr as 724there is no more program to assemble. 725.Pp 726Use 727.Li -- 728if you need to explicitly name the standard input file in your command line. 729.Pp 730If the source is empty, 731.Xr as 732produces a small, empty object file. 733.Pp 734.Em Filenames and Line-numbers 735.Pp 736There are two ways of locating a line in the input file (or files) and either 737may be used in reporting error messages. One way refers to a line number in 738a physical file; the other refers to a line number in a \(lqlogical\(rq file.See Section 739.Dq Errors . 740.Pp 741.Em Physical files 742are those files named in the command line given to 743.Xr as . 744.Pp 745.Em Logical files 746are simply names declared explicitly by assembler directives; they bear no 747relation to physical files. Logical file names help error messages reflect 748the original source file, when 749.Xr as 750source is itself synthesized from other files. 751.Xr as 752understands the 753.Li # 754directives emitted by the 755.Li gcc 756preprocessor. See also File,, 757.Li .file 758\&. 759.Pp 760.Ss Output (Object) File 761Every time you run 762.Xr as 763it produces an output file, which is your assembly language program translated 764into numbers. This file is the object file. Its default name is 765.Li a.out . 766You can give it another name by using the 767.Op -o 768option. Conventionally, object file names end with 769.Pa .o . 770The default name is used for historical reasons: older assemblers were capable 771of assembling self-contained programs directly into a runnable program. (For 772some formats, this isn't currently possible, but it can be done for the 773.Li a.out 774format.) 775.Pp 776The object file is meant for input to the linker 777.Li ld . 778It contains assembled program code, information to help 779.Li ld 780integrate the assembled program into a runnable file, and (optionally) symbolic 781information for the debugger. 782.Pp 783.Ss Error and Warning Messages 784.Xr as 785may write warnings and error messages to the standard error file (usually 786your terminal). This should not happen when a compiler runs 787.Xr as 788automatically. Warnings report an assumption made so that 789.Xr as 790could keep assembling a flawed program; errors report a grave problem that 791stops the assembly. 792.Pp 793Warning messages have the format 794.Pp 795.Bd -literal -offset indent 796file_name:NNN:Warning Message Text 797.Ed 798.Pp 799(where 800.Sy NNN 801is a line number). If a logical file name has been given (see Section 802.Dq File ) 803it is used for the filename, otherwise the name of the current input file 804is used. If a logical line number was given then it is used to calculate the 805number printed, otherwise the actual line in the current source file is printed. 806The message text is intended to be self explanatory (in the grand Unix tradition). 807.Pp 808Error messages have the format 809.Bd -literal -offset indent 810file_name:NNN:FATAL:Error Message Text 811.Ed 812The file name and line number are derived as for warning messages. The actual 813message text may be rather less explanatory because many of them aren't supposed 814to happen. 815.Pp 816.Sh Command-Line Options 817This chapter describes command-line options available in 818.Em all 819versions of the GNU assembler; see Machine Dependencies, for options specific 820to the machine specific target. 821.Pp 822If you are invoking 823.Xr as 824via the GNU C compiler, you can use the 825.Li -Wa 826option to pass arguments through to the assembler. The assembler arguments 827must be separated from each other (and the 828.Li -Wa ) 829by commas. For example: 830.Pp 831.Bd -literal -offset indent 832gcc -c -g -O -Wa,-alh,-L file.c 833.Ed 834.Pp 835This passes two options to the assembler: 836.Li -alh 837(emit a listing to standard output with high-level and assembly source) and 838.Li -L 839(retain local symbols in the symbol table). 840.Pp 841Usually you do not need to use this 842.Li -Wa 843mechanism, since many compiler command-line options are automatically passed 844to the assembler by the compiler. (You can call the GNU compiler driver with 845the 846.Li -v 847option to see precisely what options it passes to each compilation pass, including 848the assembler.) 849.Pp 850.Ss Enable Listings: Op -a[cdhlns] 851These options enable listing output from the assembler. By itself, 852.Li -a 853requests high-level, assembly, and symbols listing. You can use other letters 854to select specific options for the list: 855.Li -ah 856requests a high-level language listing, 857.Li -al 858requests an output-program assembly listing, and 859.Li -as 860requests a symbol table listing. High-level listings require that a compiler 861debugging option like 862.Li -g 863be used, and that assembly listings ( 864.Li -al ) 865be requested also. 866.Pp 867Use the 868.Li -ac 869option to omit false conditionals from a listing. Any lines which are not 870assembled because of a false 871.Li .if 872(or 873.Li .ifdef , 874or any other conditional), or a true 875.Li .if 876followed by an 877.Li .else , 878will be omitted from the listing. 879.Pp 880Use the 881.Li -ad 882option to omit debugging directives from the listing. 883.Pp 884Once you have specified one of these options, you can further control listing 885output and its appearance using the directives 886.Li .list , 887.Li .nolist , 888.Li .psize , 889.Li .eject , 890.Li .title , 891and 892.Li .sbttl . 893The 894.Li -an 895option turns off all forms processing. If you do not request listing output 896with one of the 897.Li -a 898options, the listing-control directives have no effect. 899.Pp 900The letters after 901.Li -a 902may be combined into one option, 903.Em e.g. , 904.Li -aln . 905.Pp 906Note if the assembler source is coming from the standard input (e.g., because 907it is being created by 908.Li gcc 909and the 910.Li -pipe 911command line switch is being used) then the listing will not contain any comments 912or preprocessor directives. This is because the listing code buffers input 913source lines from stdin only after they have been preprocessed by the assembler. 914This reduces memory usage and makes the code more efficient. 915.Pp 916.Ss Op --alternate 917Begin in alternate macro mode, see Altmacro,, 918.Li .altmacro 919\&. 920.Pp 921.Ss Op -D 922This option has no effect whatsoever, but it is accepted to make it more likely 923that scripts written for other assemblers also work with 924.Xr as . 925.Pp 926.Ss Work Faster: Op -f 927.Li -f 928should only be used when assembling programs written by a (trusted) compiler. 929.Li -f 930stops the assembler from doing whitespace and comment preprocessing on the 931input file(s) before assembling them.See Section 932.Dq Preprocessing . 933.Pp 934.Qo 935.Em Warning: 936if you use 937.Li -f 938when the files actually need to be preprocessed (if they contain comments, 939for example), 940.Xr as 941does not work correctly. 942.Qc 943.Pp 944.Ss Li .include Search Path: Op -I Va path 945Use this option to add a 946.Va path 947to the list of directories 948.Xr as 949searches for files specified in 950.Li .include 951directives (see Section 952.Dq Include ) . 953You may use 954.Op -I 955as many times as necessary to include a variety of paths. The current working 956directory is always searched first; after that, 957.Xr as 958searches any 959.Li -I 960directories in the same order as they were specified (left to right) on the 961command line. 962.Pp 963.Ss Difference Tables: Op -K 964On the machine specific family, this option is allowed, but has no effect. 965It is permitted for compatibility with the GNU assembler on other platforms, 966where it can be used to warn when the assembler alters the machine code generated 967for 968.Li .word 969directives in difference tables. The machine specific family does not have 970the addressing limitations that sometimes lead to this alteration on other 971platforms. 972.Pp 973.Ss Include Local Symbols: Op -L 974Symbols beginning with system-specific local label prefixes, typically 975.Li .L 976for ELF systems or 977.Li L 978for traditional a.out systems, are called 979.Em local symbols . 980See Section.Dq Symbol Names . 981Normally you do not see such symbols when debugging, because they are intended 982for the use of programs (like compilers) that compose assembler programs, 983not for your notice. Normally both 984.Xr as 985and 986.Li ld 987discard such symbols, so you do not normally debug with them. 988.Pp 989This option tells 990.Xr as 991to retain those local symbols in the object file. Usually if you do this you 992also tell the linker 993.Li ld 994to preserve those symbols. 995.Pp 996.Ss Configuring listing output: Op --listing 997The listing feature of the assembler can be enabled via the command line switch 998.Li -a 999(see Section 1000.Dq a ) . 1001This feature combines the input source file(s) with a hex dump of the corresponding 1002locations in the output object file, and displays them as a listing file. 1003The format of this listing can be controlled by directives inside the assembler 1004source (i.e., 1005.Li .list 1006(see Section 1007.Dq List ) , 1008.Li .title 1009(see Section 1010.Dq Title ) , 1011.Li .sbttl 1012(see Section 1013.Dq Sbttl ) , 1014.Li .psize 1015(see Section 1016.Dq Psize ) , 1017and 1018.Li .eject 1019(see Section 1020.Dq Eject ) 1021and also by the following switches: 1022.Pp 1023.Bl -tag -width Ds 1024.It --listing-lhs-width= Li number 1025Sets the maximum width, in words, of the first line of the hex byte dump. 1026This dump appears on the left hand side of the listing output. 1027.Pp 1028.It --listing-lhs-width2= Li number 1029Sets the maximum width, in words, of any further lines of the hex byte dump 1030for a given input source line. If this value is not specified, it defaults 1031to being the same as the value specified for 1032.Li --listing-lhs-width . 1033If neither switch is used the default is to one. 1034.Pp 1035.It --listing-rhs-width= Li number 1036Sets the maximum width, in characters, of the source line that is displayed 1037alongside the hex dump. The default value for this parameter is 100. The source 1038line is displayed on the right hand side of the listing output. 1039.Pp 1040.It --listing-cont-lines= Li number 1041Sets the maximum number of continuation lines of hex dump that will be displayed 1042for a given single line of source input. The default value is 4. 1043.El 1044.Pp 1045.Ss Assemble in MRI Compatibility Mode: Op -M 1046The 1047.Op -M 1048or 1049.Op --mri 1050option selects MRI compatibility mode. This changes the syntax and pseudo-op 1051handling of 1052.Xr as 1053to make it compatible with the 1054.Li ASM68K 1055or the 1056.Li ASM960 1057(depending upon the configured target) assembler from Microtec Research. The 1058exact nature of the MRI syntax will not be documented here; see the MRI manuals 1059for more information. Note in particular that the handling of macros and macro 1060arguments is somewhat different. The purpose of this option is to permit assembling 1061existing MRI assembler code using 1062.Xr as . 1063.Pp 1064The MRI compatibility is not complete. Certain operations of the MRI assembler 1065depend upon its object file format, and can not be supported using other object 1066file formats. Supporting these would require enhancing each object file format 1067individually. These are: 1068.Pp 1069.Bl -bullet 1070.It 1071global symbols in common section 1072.Pp 1073The m68k MRI assembler supports common sections which are merged by the linker. 1074Other object file formats do not support this. 1075.Xr as 1076handles common sections by treating them as a single common symbol. It permits 1077local symbols to be defined within a common section, but it can not support 1078global symbols, since it has no way to describe them. 1079.Pp 1080.It 1081complex relocations 1082.Pp 1083The MRI assemblers support relocations against a negated section address, 1084and relocations which combine the start addresses of two or more sections. 1085These are not support by other object file formats. 1086.Pp 1087.It 1088.Li END 1089pseudo-op specifying start address 1090.Pp 1091The MRI 1092.Li END 1093pseudo-op permits the specification of a start address. This is not supported 1094by other object file formats. The start address may instead be specified using 1095the 1096.Op -e 1097option to the linker, or in a linker script. 1098.Pp 1099.It 1100.Li IDNT , 1101.Li .ident 1102and 1103.Li NAME 1104pseudo-ops 1105.Pp 1106The MRI 1107.Li IDNT , 1108.Li .ident 1109and 1110.Li NAME 1111pseudo-ops assign a module name to the output file. This is not supported 1112by other object file formats. 1113.Pp 1114.It 1115.Li ORG 1116pseudo-op 1117.Pp 1118The m68k MRI 1119.Li ORG 1120pseudo-op begins an absolute section at a given address. This differs from 1121the usual 1122.Xr as 1123.Li .org 1124pseudo-op, which changes the location within the current section. Absolute 1125sections are not supported by other object file formats. The address of a 1126section may be assigned within a linker script. 1127.El 1128.Pp 1129There are some other features of the MRI assembler which are not supported 1130by 1131.Xr as , 1132typically either because they are difficult or because they seem of little 1133consequence. Some of these may be supported in future releases. 1134.Pp 1135.Bl -bullet 1136.It 1137EBCDIC strings 1138.Pp 1139EBCDIC strings are not supported. 1140.Pp 1141.It 1142packed binary coded decimal 1143.Pp 1144Packed binary coded decimal is not supported. This means that the 1145.Li DC.P 1146and 1147.Li DCB.P 1148pseudo-ops are not supported. 1149.Pp 1150.It 1151.Li FEQU 1152pseudo-op 1153.Pp 1154The m68k 1155.Li FEQU 1156pseudo-op is not supported. 1157.Pp 1158.It 1159.Li NOOBJ 1160pseudo-op 1161.Pp 1162The m68k 1163.Li NOOBJ 1164pseudo-op is not supported. 1165.Pp 1166.It 1167.Li OPT 1168branch control options 1169.Pp 1170The m68k 1171.Li OPT 1172branch control options--- 1173.Li B , 1174.Li BRS , 1175.Li BRB , 1176.Li BRL , 1177and 1178.Li BRW 1179---are ignored. 1180.Xr as 1181automatically relaxes all branches, whether forward or backward, to an appropriate 1182size, so these options serve no purpose. 1183.Pp 1184.It 1185.Li OPT 1186list control options 1187.Pp 1188The following m68k 1189.Li OPT 1190list control options are ignored: 1191.Li C , 1192.Li CEX , 1193.Li CL , 1194.Li CRE , 1195.Li E , 1196.Li G , 1197.Li I , 1198.Li M , 1199.Li MEX , 1200.Li MC , 1201.Li MD , 1202.Li X . 1203.Pp 1204.It 1205other 1206.Li OPT 1207options 1208.Pp 1209The following m68k 1210.Li OPT 1211options are ignored: 1212.Li NEST , 1213.Li O , 1214.Li OLD , 1215.Li OP , 1216.Li P , 1217.Li PCO , 1218.Li PCR , 1219.Li PCS , 1220.Li R . 1221.Pp 1222.It 1223.Li OPT 1224.Li D 1225option is default 1226.Pp 1227The m68k 1228.Li OPT 1229.Li D 1230option is the default, unlike the MRI assembler. 1231.Li OPT NOD 1232may be used to turn it off. 1233.Pp 1234.It 1235.Li XREF 1236pseudo-op. 1237.Pp 1238The m68k 1239.Li XREF 1240pseudo-op is ignored. 1241.Pp 1242.It 1243.Li .debug 1244pseudo-op 1245.Pp 1246The i960 1247.Li .debug 1248pseudo-op is not supported. 1249.Pp 1250.It 1251.Li .extended 1252pseudo-op 1253.Pp 1254The i960 1255.Li .extended 1256pseudo-op is not supported. 1257.Pp 1258.It 1259.Li .list 1260pseudo-op. 1261.Pp 1262The various options of the i960 1263.Li .list 1264pseudo-op are not supported. 1265.Pp 1266.It 1267.Li .optimize 1268pseudo-op 1269.Pp 1270The i960 1271.Li .optimize 1272pseudo-op is not supported. 1273.Pp 1274.It 1275.Li .output 1276pseudo-op 1277.Pp 1278The i960 1279.Li .output 1280pseudo-op is not supported. 1281.Pp 1282.It 1283.Li .setreal 1284pseudo-op 1285.Pp 1286The i960 1287.Li .setreal 1288pseudo-op is not supported. 1289.Pp 1290.El 1291.Ss Dependency Tracking: Op --MD 1292.Xr as 1293can generate a dependency file for the file it creates. This file consists 1294of a single rule suitable for 1295.Li make 1296describing the dependencies of the main source file. 1297.Pp 1298The rule is written to the file named in its argument. 1299.Pp 1300This feature is used in the automatic updating of makefiles. 1301.Pp 1302.Ss Name the Object File: Op -o 1303There is always one object file output when you run 1304.Xr as . 1305By default it has the name 1306.Pa a.out . 1307You use this option (which takes exactly one filename) to give the object 1308file a different name. 1309.Pp 1310Whatever the object file is called, 1311.Xr as 1312overwrites any existing file of the same name. 1313.Pp 1314.Ss Join Data and Text Sections: Op -R 1315.Op -R 1316tells 1317.Xr as 1318to write the object file as if all data-section data lives in the text section. 1319This is only done at the very last moment: your binary data are the same, 1320but data section parts are relocated differently. The data section part of 1321your object file is zero bytes long because all its bytes are appended to 1322the text section. (See Section 1323.Dq Sections . ) 1324.Pp 1325When you specify 1326.Op -R 1327it would be possible to generate shorter address displacements (because we 1328do not have to cross between text and data section). We refrain from doing 1329this simply for compatibility with older versions of 1330.Xr as . 1331In future, 1332.Op -R 1333may work this way. 1334.Pp 1335When 1336.Xr as 1337is configured for COFF or ELF output, this option is only useful if you use 1338sections named 1339.Li .text 1340and 1341.Li .data . 1342.Pp 1343.Ss Display Assembly Statistics: Op --statistics 1344Use 1345.Li --statistics 1346to display two statistics about the resources used by 1347.Xr as : 1348the maximum amount of space allocated during the assembly (in bytes), and 1349the total execution time taken for the assembly (in cpu seconds). 1350.Pp 1351.Ss Compatible Output: Op --traditional-format 1352For some targets, the output of 1353.Xr as 1354is different in some ways from the output of some existing assembler. This 1355switch requests 1356.Xr as 1357to use the traditional format instead. 1358.Pp 1359For example, it disables the exception frame optimizations which 1360.Xr as 1361normally does by default on 1362.Li gcc 1363output. 1364.Pp 1365.Ss Announce Version: Op -v 1366You can find out what version of as is running by including the option 1367.Li -v 1368(which you can also spell as 1369.Li -version ) 1370on the command line. 1371.Pp 1372.Ss Control Warnings: Op -W, Op --warn, Op --no-warn, Op --fatal-warnings 1373.Xr as 1374should never give a warning or error message when assembling compiler output. 1375But programs written by people often cause 1376.Xr as 1377to give a warning that a particular assumption was made. All such warnings 1378are directed to the standard error file. 1379.Pp 1380If you use the 1381.Op -W 1382and 1383.Op --no-warn 1384options, no warnings are issued. This only affects the warning messages: it 1385does not change any particular of how 1386.Xr as 1387assembles your file. Errors, which stop the assembly, are still reported. 1388.Pp 1389If you use the 1390.Op --fatal-warnings 1391option, 1392.Xr as 1393considers files that generate warnings to be in error. 1394.Pp 1395You can switch these options off again by specifying 1396.Op --warn , 1397which causes warnings to be output as usual. 1398.Pp 1399.Ss Generate Object File in Spite of Errors: Op -Z 1400After an error message, 1401.Xr as 1402normally produces no output. If for some reason you are interested in object 1403file output even after 1404.Xr as 1405gives an error message on your program, use the 1406.Li -Z 1407option. If there are any errors, 1408.Xr as 1409continues anyways, and writes an object file after a final warning message 1410of the form 1411.Li Va n errors, Va m warnings, generating bad object file. 1412.Pp 1413.Sh Syntax 1414This chapter describes the machine-independent syntax allowed in a source 1415file. 1416.Xr as 1417syntax is similar to what many other assemblers use; it is inspired by the 1418BSD 4.2 assembler. 1419.Pp 1420.Ss Preprocessing 1421The 1422.Xr as 1423internal preprocessor: 1424.Bl -bullet 1425.It 1426adjusts and removes extra whitespace. It leaves one space or tab before the 1427keywords on a line, and turns any other whitespace on the line into a single 1428space. 1429.Pp 1430.It 1431removes all comments, replacing them with a single space, or an appropriate 1432number of newlines. 1433.Pp 1434.It 1435converts character constants into the appropriate numeric values. 1436.El 1437.Pp 1438It does not do macro processing, include file handling, or anything else you 1439may get from your C compiler's preprocessor. You can do include file processing 1440with the 1441.Li .include 1442directive (see Section 1443.Dq Include ) . 1444You can use the GNU C compiler driver to get other \(lqCPP\(rq style preprocessing 1445by giving the input file a 1446.Li .S 1447suffix.See Section 1448.Dq Overall Options . 1449.Pp 1450Excess whitespace, comments, and character constants cannot be used in the 1451portions of the input text that are not preprocessed. 1452.Pp 1453If the first line of an input file is 1454.Li #NO_APP 1455or if you use the 1456.Li -f 1457option, whitespace and comments are not removed from the input file. Within 1458an input file, you can ask for whitespace and comment removal in specific 1459portions of the by putting a line that says 1460.Li #APP 1461before the text that may contain whitespace or comments, and putting a line 1462that says 1463.Li #NO_APP 1464after this text. This feature is mainly intend to support 1465.Li asm 1466statements in compilers whose output is otherwise free of comments and whitespace. 1467.Pp 1468.Ss Whitespace 1469.Em Whitespace 1470is one or more blanks or tabs, in any order. Whitespace is used to separate 1471symbols, and to make programs neater for people to read. Unless within character 1472constants (see Section 1473.Dq Characters ) , 1474any whitespace means the same as exactly one space. 1475.Pp 1476.Ss Comments 1477There are two ways of rendering comments to 1478.Xr as . 1479In both cases the comment is equivalent to one space. 1480.Pp 1481Anything from 1482.Li /* 1483through the next 1484.Li */ 1485is a comment. This means you may not nest these comments. 1486.Pp 1487.Bd -literal -offset indent 1488/* 1489 The only way to include a newline ('\en') in a comment 1490 is to use this sort of comment. 1491*/ 1492 1493/* This sort of comment does not nest. */ 1494.Ed 1495.Pp 1496Anything from the 1497.Em line comment 1498character to the next newline is considered a comment and is ignored. The 1499line comment character is 1500.Li @ 1501on the ARM; 1502.Li # 1503on the i386 and x86-64; 1504.Li # 1505for Motorola PowerPC; 1506.Li ! 1507on the SPARC; see Machine Dependencies. 1508.Pp 1509To be compatible with past assemblers, lines that begin with 1510.Li # 1511have a special interpretation. Following the 1512.Li # 1513should be an absolute expression (see Section 1514.Dq Expressions ) : 1515the logical line number of the 1516.Em next 1517line. Then a string (see Section 1518.Dq Strings ) 1519is allowed: if present it is a new logical file name. The rest of the line, 1520if any, should be whitespace. 1521.Pp 1522If the first non-whitespace characters on the line are not numeric, the line 1523is ignored. (Just like a comment.) 1524.Pp 1525.Bd -literal -offset indent 1526 # This is an ordinary comment. 1527# 42-6 "new_file_name" # New logical file name 1528 # This is logical line # 36. 1529.Ed 1530This feature is deprecated, and may disappear from future versions of 1531.Xr as . 1532.Pp 1533.Ss Symbols 1534A 1535.Em symbol 1536is one or more characters chosen from the set of all letters (both upper and 1537lower case), digits and the three characters 1538.Li _.$ . 1539No symbol may begin with a digit. Case is significant. There is no length 1540limit: all characters are significant. Symbols are delimited by characters 1541not in that set, or by the beginning of a file (since the source program must 1542end with a newline, the end of a file is not a possible symbol delimiter).See Section 1543.Dq Symbols . 1544.Pp 1545.Ss Statements 1546A 1547.Em statement 1548ends at a newline character ( 1549.Li \en ) 1550or at a semicolon ( 1551.Li ; ) . 1552The newline or semicolon is considered part of the preceding statement. Newlines 1553and semicolons within character constants are an exception: they do not end 1554statements. 1555.Pp 1556It is an error to end any statement with end-of-file: the last character of 1557any input file should be a newline. 1558.Pp 1559An empty statement is allowed, and may include whitespace. It is ignored. 1560.Pp 1561A statement begins with zero or more labels, optionally followed by a key 1562symbol which determines what kind of statement it is. The key symbol determines 1563the syntax of the rest of the statement. If the symbol begins with a dot 1564.Li . 1565then the statement is an assembler directive: typically valid for any computer. 1566If the symbol begins with a letter the statement is an assembly language 1567.Em instruction : 1568it assembles into a machine language instruction. 1569.Pp 1570A label is a symbol immediately followed by a colon ( 1571.Li : ) . 1572Whitespace before a label or after a colon is permitted, but you may not have 1573whitespace between a label's symbol and its colon.See Section 1574.Dq Labels . 1575.Pp 1576.Bd -literal -offset indent 1577label: .directive followed by something 1578another_label: # This is an empty statement. 1579 instruction operand_1, operand_2, ... 1580.Ed 1581.Pp 1582.Ss Constants 1583A constant is a number, written so that its value is known by inspection, 1584without knowing any context. Like this: 1585.Bd -literal -offset indent 1586 1587\&.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\eJ # All the same value. 1588\&.ascii "Ring the bell\e7" # A string constant. 1589\&.octa 0x123456789abcdef0123456789ABCDEF0 # A biGNUm. 1590\&.float 0f-314159265358979323846264338327\e 159195028841971.693993751E-40 # - pi, a flonum. 1592 1593.Ed 1594.Pp 1595.Em Character Constants 1596.Pp 1597There are two kinds of character constants. A 1598.Em character 1599stands for one character in one byte and its value may be used in numeric 1600expressions. String constants (properly called string 1601.Em literals ) 1602are potentially many bytes and their values may not be used in arithmetic 1603expressions. 1604.Pp 1605.No Strings 1606.Pp 1607A 1608.Em string 1609is written between double-quotes. It may contain double-quotes or null characters. 1610The way to get special characters into a string is to 1611.Em escape 1612these characters: precede them with a backslash 1613.Li \e 1614character. For example 1615.Li \e\e 1616represents one backslash: the first 1617.Li \e 1618is an escape which tells 1619.Xr as 1620to interpret the second character literally as a backslash (which prevents 1621.Xr as 1622from recognizing the second 1623.Li \e 1624as an escape character). The complete list of escapes follows. 1625.Pp 1626.Bl -tag -width Ds 1627.It \eb 1628Mnemonic for backspace; for ASCII this is octal code 010. 1629.Pp 1630.It \ef 1631Mnemonic for FormFeed; for ASCII this is octal code 014. 1632.Pp 1633.It \en 1634Mnemonic for newline; for ASCII this is octal code 012. 1635.Pp 1636.It \er 1637Mnemonic for carriage-Return; for ASCII this is octal code 015. 1638.Pp 1639.It \et 1640Mnemonic for horizontal Tab; for ASCII this is octal code 011. 1641.Pp 1642.It \e Va digit Va digit Va digit 1643An octal character code. The numeric code is 3 octal digits. For compatibility 1644with other Unix systems, 8 and 9 are accepted as digits: for example, 1645.Li \e008 1646has the value 010, and 1647.Li \e009 1648the value 011. 1649.Pp 1650.It \e Li x Va hex-digits... 1651A hex character code. All trailing hex digits are combined. Either upper or 1652lower case 1653.Li x 1654works. 1655.Pp 1656.It \e\e 1657Represents one 1658.Li \e 1659character. 1660.Pp 1661.It \e" 1662Represents one 1663.Li " 1664character. Needed in strings to represent this character, because an unescaped 1665.Li " 1666would end the string. 1667.Pp 1668.It \e Va anything-else 1669Any other character when escaped by 1670.Li \e 1671gives a warning, but assembles as if the 1672.Li \e 1673was not present. The idea is that if you used an escape sequence you clearly 1674didn't want the literal interpretation of the following character. However 1675.Xr as 1676has no other interpretation, so 1677.Xr as 1678knows it is giving you the wrong code and warns you of the fact. 1679.El 1680.Pp 1681Which characters are escapable, and what those escapes represent, varies widely 1682among assemblers. The current set is what we think the BSD 4.2 assembler recognizes, 1683and is a subset of what most C compilers recognize. If you are in doubt, do 1684not use an escape sequence. 1685.Pp 1686.No Characters 1687.Pp 1688A single character may be written as a single quote immediately followed by 1689that character. The same escapes apply to characters as to strings. So if 1690you want to write the character backslash, you must write 1691.Li '\e\e 1692where the first 1693.Li \e 1694escapes the second 1695.Li \e . 1696As you can see, the quote is an acute accent, not a grave accent. A newline 1697(or semicolon 1698.Li ; ) 1699immediately following an acute accent is taken as a literal character and 1700does not count as the end of a statement. The value of a character constant 1701in a numeric expression is the machine's byte-wide code for that character. 1702.Xr as 1703assumes your character code is ASCII: 1704.Li 'A 1705means 65, 1706.Li 'B 1707means 66, and so on. 1708.Pp 1709.Em Number Constants 1710.Pp 1711.Xr as 1712distinguishes three kinds of numbers according to how they are stored in the 1713target machine. 1714.Em Integers 1715are numbers that would fit into an 1716.Li int 1717in the C language. 1718.Em BiGNUms 1719are integers, but they are stored in more than 32 bits. 1720.Em Flonums 1721are floating point numbers, described below. 1722.Pp 1723.No Integers 1724.Pp 1725A binary integer is 1726.Li 0b 1727or 1728.Li 0B 1729followed by zero or more of the binary digits 1730.Li 01 . 1731.Pp 1732An octal integer is 1733.Li 0 1734followed by zero or more of the octal digits ( 1735.Li 01234567 ) . 1736.Pp 1737A decimal integer starts with a non-zero digit followed by zero or more digits 1738( 1739.Li 0123456789 ) . 1740.Pp 1741A hexadecimal integer is 1742.Li 0x 1743or 1744.Li 0X 1745followed by one or more hexadecimal digits chosen from 1746.Li 0123456789abcdefABCDEF . 1747.Pp 1748Integers have the usual values. To denote a negative integer, use the prefix 1749operator 1750.Li - 1751discussed under expressions (see Section 1752.Dq Prefix Ops ) . 1753.Pp 1754.No BiGNUms 1755.Pp 1756A 1757.Em biGNUm 1758has the same syntax and semantics as an integer except that the number (or 1759its negative) takes more than 32 bits to represent in binary. The distinction 1760is made because in some places integers are permitted while biGNUms are not. 1761.Pp 1762.No Flonums 1763.Pp 1764A 1765.Em flonum 1766represents a floating point number. The translation is indirect: a decimal 1767floating point number from the text is converted by 1768.Xr as 1769to a generic binary floating point number of more than sufficient precision. 1770This generic floating point number is converted to a particular computer's 1771floating point format (or formats) by a portion of 1772.Xr as 1773specialized to that computer. 1774.Pp 1775A flonum is written by writing (in order) 1776.Bl -bullet 1777.It 1778The digit 1779.Li 0 . 1780.Pp 1781.It 1782A letter, to tell 1783.Xr as 1784the rest of the number is a flonum. 1785.Pp 1786.It 1787An optional sign: either 1788.Li + 1789or 1790.Li - . 1791.Pp 1792.It 1793An optional 1794.Em integer part : 1795zero or more decimal digits. 1796.Pp 1797.It 1798An optional 1799.Em fractional part : 1800.Li . 1801followed by zero or more decimal digits. 1802.Pp 1803.It 1804An optional exponent, consisting of: 1805.Pp 1806.Bl -bullet 1807.It 1808An 1809.Li E 1810or 1811.Li e . 1812.It 1813Optional sign: either 1814.Li + 1815or 1816.Li - . 1817.It 1818One or more decimal digits. 1819.El 1820.Pp 1821.El 1822At least one of the integer part or the fractional part must be present. The 1823floating point number has the usual base-10 value. 1824.Pp 1825.Xr as 1826does all processing using integers. Flonums are computed independently of 1827any floating point hardware in the computer running 1828.Xr as . 1829.Pp 1830.Sh Sections and Relocation 1831.Ss Background 1832Roughly, a section is a range of addresses, with no gaps; all data \(lqin\(rq those 1833addresses is treated the same for some particular purpose. For example there 1834may be a \(lqread only\(rq section. 1835.Pp 1836The linker 1837.Li ld 1838reads many object files (partial programs) and combines their contents to 1839form a runnable program. When 1840.Xr as 1841emits an object file, the partial program is assumed to start at address 0. 1842.Li ld 1843assigns the final addresses for the partial program, so that different partial 1844programs do not overlap. This is actually an oversimplification, but it suffices 1845to explain how 1846.Xr as 1847uses sections. 1848.Pp 1849.Li ld 1850moves blocks of bytes of your program to their run-time addresses. These blocks 1851slide to their run-time addresses as rigid units; their length does not change 1852and neither does the order of bytes within them. Such a rigid unit is called 1853a 1854.Em section . 1855Assigning run-time addresses to sections is called 1856.Em relocation . 1857It includes the task of adjusting mentions of object-file addresses so they 1858refer to the proper run-time addresses. 1859.Pp 1860An object file written by 1861.Xr as 1862has at least three sections, any of which may be empty. These are named 1863.Em text , 1864.Em data 1865and 1866.Em bss 1867sections. 1868.Pp 1869.Xr as 1870can also generate whatever other named sections you specify using the 1871.Li .section 1872directive (see Section 1873.Dq Section ) . 1874If you do not use any directives that place output in the 1875.Li .text 1876or 1877.Li .data 1878sections, these sections still exist, but are empty. 1879.Pp 1880Within the object file, the text section starts at address 1881.Li 0 , 1882the data section follows, and the bss section follows the data section. 1883.Pp 1884To let 1885.Li ld 1886know which data changes when the sections are relocated, and how to change 1887that data, 1888.Xr as 1889also writes to the object file details of the relocation needed. To perform 1890relocation 1891.Li ld 1892must know, each time an address in the object file is mentioned: 1893.Bl -bullet 1894.It 1895Where in the object file is the beginning of this reference to an address? 1896.It 1897How long (in bytes) is this reference? 1898.It 1899Which section does the address refer to? What is the numeric value of 1900.Bd -filled -offset indent 1901( 1902.Va address ) 1903\-( 1904.Va start-address of section ) ? 1905.Ed 1906.It 1907Is the reference to an address \(lqProgram-Counter relative\(rq? 1908.El 1909.Pp 1910In fact, every address 1911.Xr as 1912ever uses is expressed as 1913.Bd -filled -offset indent 1914( 1915.Va section ) 1916+ ( 1917.Va offset into section ) 1918.Ed 1919Further, most expressions 1920.Xr as 1921computes have this section-relative nature. 1922.Pp 1923In this manual we use the notation { 1924.Va secname 1925.Va N 1926}to mean \(lqoffset 1927.Va N 1928into section 1929.Va secname 1930\&.\(rq 1931.Pp 1932Apart from text, data and bss sections you need to know about the 1933.Em absolute 1934section. When 1935.Li ld 1936mixes partial programs, addresses in the absolute section remain unchanged. 1937For example, address 1938.Li {absolute 0} 1939is \(lqrelocated\(rq to run-time address 0 by 1940.Li ld . 1941Although the linker never arranges two partial programs' data sections with 1942overlapping addresses after linking, 1943.Em by definition 1944their absolute sections must overlap. Address 1945.Li {absolute 239} 1946in one part of a program is always the same address when the program is running 1947as address 1948.Li {absolute 239} 1949in any other part of the program. 1950.Pp 1951The idea of sections is extended to the 1952.Em undefined 1953section. Any address whose section is unknown at assembly time is by definition 1954rendered {undefined 1955.Va U 1956}---where 1957.Va U 1958is filled in later. Since numbers are always defined, the only way to generate 1959an undefined address is to mention an undefined symbol. A reference to a named 1960common block would be such a symbol: its value is unknown at assembly time 1961so it has section 1962.Em undefined . 1963.Pp 1964By analogy the word 1965.Em section 1966is used to describe groups of sections in the linked program. 1967.Li ld 1968puts all partial programs' text sections in contiguous addresses in the linked 1969program. It is customary to refer to the 1970.Em text section 1971of a program, meaning all the addresses of all partial programs' text sections. 1972Likewise for data and bss sections. 1973.Pp 1974Some sections are manipulated by 1975.Li ld ; 1976others are invented for use of 1977.Xr as 1978and have no meaning except during assembly. 1979.Pp 1980.Ss Linker Sections 1981.Li ld 1982deals with just four kinds of sections, summarized below. 1983.Pp 1984.Bl -tag -width Ds 1985.It named sections 1986These sections hold your program. 1987.Xr as 1988and 1989.Li ld 1990treat them as separate but equal sections. Anything you can say of one section 1991is true of another. When the program is running, however, it is customary 1992for the text section to be unalterable. The text section is often shared among 1993processes: it contains instructions, constants and the like. The data section 1994of a running program is usually alterable: for example, C variables would 1995be stored in the data section. 1996.Pp 1997.It bss section 1998This section contains zeroed bytes when your program begins running. It is 1999used to hold uninitialized variables or common storage. The length of each 2000partial program's bss section is important, but because it starts out containing 2001zeroed bytes there is no need to store explicit zero bytes in the object file. 2002The bss section was invented to eliminate those explicit zeros from object 2003files. 2004.Pp 2005.It absolute section 2006Address 0 of this section is always \(lqrelocated\(rq to runtime address 0. This is 2007useful if you want to refer to an address that 2008.Li ld 2009must not change when relocating. In this sense we speak of absolute addresses 2010being \(lqunrelocatable\(rq: they do not change during relocation. 2011.Pp 2012.It undefined section 2013This \(lqsection\(rq is a catch-all for address references to objects not in the preceding 2014sections. 2015.El 2016.Pp 2017An idealized example of three relocatable sections follows. The example uses 2018the traditional section names 2019.Li .text 2020and 2021.Li .data . 2022Memory addresses are on the horizontal axis. 2023.Pp 2024.Bd -literal -offset indent 2025 +-----+----+--+ 2026partial program # 1: |ttttt|dddd|00| 2027 +-----+----+--+ 2028 2029 text data bss 2030 seg. seg. seg. 2031 2032 +---+---+---+ 2033partial program # 2: |TTT|DDD|000| 2034 +---+---+---+ 2035 2036 +--+---+-----+--+----+---+-----+~~ 2037linked program: | |TTT|ttttt| |dddd|DDD|00000| 2038 +--+---+-----+--+----+---+-----+~~ 2039 2040 addresses: 0 ... 2041.Ed 2042.Pp 2043.Ss Assembler Internal Sections 2044These sections are meant only for the internal use of 2045.Xr as . 2046They have no meaning at run-time. You do not really need to know about these 2047sections for most purposes; but they can be mentioned in 2048.Xr as 2049warning messages, so it might be helpful to have an idea of their meanings 2050to 2051.Xr as . 2052These sections are used to permit the value of every expression in your assembly 2053language program to be a section-relative address. 2054.Pp 2055.Bl -tag -width Ds 2056.It ASSEMBLER-INTERNAL-LOGIC-ERROR! 2057An internal assembler logic error has been found. This means there is a bug 2058in the assembler. 2059.Pp 2060.It expr section 2061The assembler stores complex expression internally as combinations of symbols. 2062When it needs to represent an expression as a symbol, it puts it in the expr 2063section. 2064.El 2065.Pp 2066.Ss Sub-Sections 2067You may have separate groups of data in named sections that you want to end 2068up near to each other in the object file, even though they are not contiguous 2069in the assembler source. 2070.Xr as 2071allows you to use 2072.Em subsections 2073for this purpose. Within each section, there can be numbered subsections with 2074values from 0 to 8192. Objects assembled into the same subsection go into 2075the object file together with other objects in the same subsection. For example, 2076a compiler might want to store constants in the text section, but might not 2077want to have them interspersed with the program being assembled. In this case, 2078the compiler could issue a 2079.Li .text 0 2080before each section of code being output, and a 2081.Li .text 1 2082before each group of constants being output. 2083.Pp 2084Subsections are optional. If you do not use subsections, everything goes in 2085subsection number zero. 2086.Pp 2087Subsections appear in your object file in numeric order, lowest numbered to 2088highest. (All this to be compatible with other people's assemblers.) The object 2089file contains no representation of subsections; 2090.Li ld 2091and other programs that manipulate object files see no trace of them. They 2092just see all your text subsections as a text section, and all your data subsections 2093as a data section. 2094.Pp 2095To specify which subsection you want subsequent statements assembled into, 2096use a numeric argument to specify it, in a 2097.Li .text Va expression 2098or a 2099.Li .data Va expression 2100statement. You can also use the 2101.Li .subsection 2102directive (see Section 2103.Dq SubSection ) 2104to specify a subsection: 2105.Li .subsection Va expression . 2106.Va Expression 2107should be an absolute expression (see Section 2108.Dq Expressions ) . 2109If you just say 2110.Li .text 2111then 2112.Li .text 0 2113is assumed. Likewise 2114.Li .data 2115means 2116.Li .data 0 . 2117Assembly begins in 2118.Li text 0 . 2119For instance: 2120.Bd -literal -offset indent 2121\&.text 0 # The default subsection is text 0 anyway. 2122\&.ascii "This lives in the first text subsection. *" 2123\&.text 1 2124\&.ascii "But this lives in the second text subsection." 2125\&.data 0 2126\&.ascii "This lives in the data section," 2127\&.ascii "in the first data subsection." 2128\&.text 0 2129\&.ascii "This lives in the first text section," 2130\&.ascii "immediately following the asterisk (*)." 2131.Ed 2132.Pp 2133Each section has a 2134.Em location counter 2135incremented by one for every byte assembled into that section. Because subsections 2136are merely a convenience restricted to 2137.Xr as 2138there is no concept of a subsection location counter. There is no way to directly 2139manipulate a location counter---but the 2140.Li .align 2141directive changes it, and any label definition captures its current value. 2142The location counter of the section where statements are being assembled is 2143said to be the 2144.Em active 2145location counter. 2146.Pp 2147.Ss bss Section 2148The bss section is used for local common variable storage. You may allocate 2149address space in the bss section, but you may not dictate data to load into 2150it before your program executes. When your program starts running, all the 2151contents of the bss section are zeroed bytes. 2152.Pp 2153The 2154.Li .lcomm 2155pseudo-op defines a symbol in the bss section; see Lcomm,, 2156.Li .lcomm 2157\&. 2158.Pp 2159The 2160.Li .comm 2161pseudo-op may be used to declare a common symbol, which is another form of 2162uninitialized symbol; see Comm,, 2163.Li .comm 2164\&. 2165.Pp 2166.Sh Symbols 2167Symbols are a central concept: the programmer uses symbols to name things, 2168the linker uses symbols to link, and the debugger uses symbols to debug. 2169.Pp 2170.Qo 2171.Em Warning: 2172.Xr as 2173does not place symbols in the object file in the same order they were declared. 2174This may break some debuggers. 2175.Qc 2176.Pp 2177.Ss Labels 2178A 2179.Em label 2180is written as a symbol immediately followed by a colon 2181.Li : . 2182The symbol then represents the current value of the active location counter, 2183and is, for example, a suitable instruction operand. You are warned if you 2184use the same symbol to represent two different locations: the first definition 2185overrides any other definitions. 2186.Pp 2187.Ss Giving Symbols Other Values 2188A symbol can be given an arbitrary value by writing a symbol, followed by 2189an equals sign 2190.Li = , 2191followed by an expression (see Section 2192.Dq Expressions ) . 2193This is equivalent to using the 2194.Li .set 2195directive.See Section 2196.Dq Set . 2197In the same way, using a double equals sign 2198.Li = 2199.Li = 2200here represents an equivalent of the 2201.Li .eqv 2202directive.See Section 2203.Dq Eqv . 2204.Pp 2205.Ss Symbol Names 2206Symbol names begin with a letter or with one of 2207.Li ._ . 2208On most machines, you can also use 2209.Li $ 2210in symbol names; exceptions are noted in Machine Dependencies. That character 2211may be followed by any string of digits, letters, dollar signs (unless otherwise 2212noted for a particular target machine), and underscores. 2213.Pp 2214Case of letters is significant: 2215.Li foo 2216is a different symbol name than 2217.Li Foo . 2218.Pp 2219Each symbol has exactly one name. Each name in an assembly language program 2220refers to exactly one symbol. You may use that symbol name any number of times 2221in a program. 2222.Pp 2223.Em Local Symbol Names 2224.Pp 2225A local symbol is any symbol beginning with certain local label prefixes. 2226By default, the local label prefix is 2227.Li .L 2228for ELF systems or 2229.Li L 2230for traditional a.out systems, but each target may have its own set of local 2231label prefixes. 2232.Pp 2233Local symbols are defined and used within the assembler, but they are normally 2234not saved in object files. Thus, they are not visible when debugging. You 2235may use the 2236.Li -L 2237option (see Section 2238.Dq L ) 2239to retain the local symbols in the object files. 2240.Pp 2241.Em Local Labels 2242.Pp 2243Local labels help compilers and programmers use names temporarily. They create 2244symbols which are guaranteed to be unique over the entire scope of the input 2245source code and which can be referred to by a simple notation. To define a 2246local label, write a label of the form 2247.Li Sy N: 2248(where 2249.Sy N 2250represents any positive integer). To refer to the most recent previous definition 2251of that label write 2252.Li Sy Nb , 2253using the same number as when you defined the label. To refer to the next 2254definition of a local label, write 2255.Li Sy Nf 2256---the 2257.Li b 2258stands for \(lqbackwards\(rq and the 2259.Li f 2260stands for \(lqforwards\(rq. 2261.Pp 2262There is no restriction on how you can use these labels, and you can reuse 2263them too. So that it is possible to repeatedly define the same local label 2264(using the same number 2265.Li Sy N ) , 2266although you can only refer to the most recently defined local label of that 2267number (for a backwards reference) or the next definition of a specific local 2268label for a forward reference. It is also worth noting that the first 10 local 2269labels ( 2270.Li Sy 0: 2271\&....Li Sy 9: ) 2272are implemented in a slightly more efficient manner than the others. 2273.Pp 2274Here is an example: 2275.Pp 2276.Bd -literal -offset indent 22771: branch 1f 22782: branch 1b 22791: branch 2f 22802: branch 1b 2281.Ed 2282.Pp 2283Which is the equivalent of: 2284.Pp 2285.Bd -literal -offset indent 2286label_1: branch label_3 2287label_2: branch label_1 2288label_3: branch label_4 2289label_4: branch label_3 2290.Ed 2291.Pp 2292Local label names are only a notational device. They are immediately transformed 2293into more conventional symbol names before the assembler uses them. The symbol 2294names are stored in the symbol table, appear in error messages, and are optionally 2295emitted to the object file. The names are constructed using these parts: 2296.Pp 2297.Bl -tag -width Ds 2298.It Em local label prefix 2299All local symbols begin with the system-specific local label prefix. Normally 2300both 2301.Xr as 2302and 2303.Li ld 2304forget symbols that start with the local label prefix. These labels are used 2305for symbols you are never intended to see. If you use the 2306.Li -L 2307option then 2308.Xr as 2309retains these symbols in the object file. If you also instruct 2310.Li ld 2311to retain these symbols, you may use them in debugging. 2312.Pp 2313.It Va number 2314This is the number that was used in the local label definition. So if the 2315label is written 2316.Li 55: 2317then the number is 2318.Li 55 . 2319.Pp 2320.It Li C-B 2321This unusual character is included so you do not accidentally invent a symbol 2322of the same name. The character has ASCII value of 2323.Li \e002 2324(control-B). 2325.Pp 2326.It Em ordinal number 2327This is a serial number to keep the labels distinct. The first definition 2328of 2329.Li 0: 2330gets the number 2331.Li 1 . 2332The 15th definition of 2333.Li 0: 2334gets the number 2335.Li 15 , 2336and so on. Likewise the first definition of 2337.Li 1: 2338gets the number 2339.Li 1 2340and its 15th definition gets 2341.Li 15 2342as well. 2343.El 2344.Pp 2345So for example, the first 2346.Li 1: 2347may be named 2348.Li .L1 Li C-B1 , 2349and the 44th 2350.Li 3: 2351may be named 2352.Li .L3 Li C-B44 . 2353.Pp 2354.Em Dollar Local Labels 2355.Pp 2356.Li as 2357also supports an even more local form of local labels called dollar labels. 2358These labels go out of scope (i.e., they become undefined) as soon as a non-local 2359label is defined. Thus they remain valid for only a small region of the input 2360source code. Normal local labels, by contrast, remain in scope for the entire 2361file, or until they are redefined by another occurrence of the same local 2362label. 2363.Pp 2364Dollar labels are defined in exactly the same way as ordinary local labels, 2365except that instead of being terminated by a colon, they are terminated by 2366a dollar sign, e.g., 2367.Li Sy 55$ . 2368.Pp 2369They can also be distinguished from ordinary local labels by their transformed 2370names which use ASCII character 2371.Li \e001 2372(control-A) as the magic character to distinguish them from ordinary labels. 2373For example, the fifth definition of 2374.Li 6$ 2375may be named 2376.Li .L6 Li C-A5 . 2377.Pp 2378.Ss The Special Dot Symbol 2379The special symbol 2380.Li . 2381refers to the current address that 2382.Xr as 2383is assembling into. Thus, the expression 2384.Li melvin: .long . 2385defines 2386.Li melvin 2387to contain its own address. Assigning a value to 2388.Li . 2389is treated the same as a 2390.Li .org 2391directive. Thus, the expression 2392.Li .=.+4 2393is the same as saying 2394.Li .space 4 . 2395.Pp 2396.Ss Symbol Attributes 2397Every symbol has, as well as its name, the attributes \(lqValue\(rq and \(lqType\(rq. Depending 2398on output format, symbols can also have auxiliary attributes. The detailed 2399definitions are in 2400.Pa a.out.h . 2401.Pp 2402If you use a symbol without defining it, 2403.Xr as 2404assumes zero for all these attributes, and probably won't warn you. This makes 2405the symbol an externally defined symbol, which is generally what you would 2406want. 2407.Pp 2408.Em Value 2409.Pp 2410The value of a symbol is (usually) 32 bits. For a symbol which labels a location 2411in the text, data, bss or absolute sections the value is the number of addresses 2412from the start of that section to the label. Naturally for text, data and 2413bss sections the value of a symbol changes as 2414.Li ld 2415changes section base addresses during linking. Absolute symbols' values do 2416not change during linking: that is why they are called absolute. 2417.Pp 2418The value of an undefined symbol is treated in a special way. If it is 0 then 2419the symbol is not defined in this assembler source file, and 2420.Li ld 2421tries to determine its value from other files linked into the same program. 2422You make this kind of symbol simply by mentioning a symbol name without defining 2423it. A non-zero value represents a 2424.Li .comm 2425common declaration. The value is how much common storage to reserve, in bytes 2426(addresses). The symbol refers to the first address of the allocated storage. 2427.Pp 2428.Em Type 2429.Pp 2430The type attribute of a symbol contains relocation (section) information, 2431any flag settings indicating that a symbol is external, and (optionally), 2432other information for linkers and debuggers. The exact format depends on the 2433object-code output format in use. 2434.Pp 2435.Sh Expressions 2436An 2437.Em expression 2438specifies an address or numeric value. Whitespace may precede and/or follow 2439an expression. 2440.Pp 2441The result of an expression must be an absolute number, or else an offset 2442into a particular section. If an expression is not absolute, and there is 2443not enough information when 2444.Xr as 2445sees the expression to know its section, a second pass over the source program 2446might be necessary to interpret the expression---but the second pass is currently 2447not implemented. 2448.Xr as 2449aborts with an error message in this situation. 2450.Pp 2451.Ss Empty Expressions 2452An empty expression has no value: it is just whitespace or null. Wherever 2453an absolute expression is required, you may omit the expression, and 2454.Xr as 2455assumes a value of (absolute) 0. This is compatible with other assemblers. 2456.Pp 2457.Ss Integer Expressions 2458An 2459.Em integer expression 2460is one or more 2461.Em arguments 2462delimited by 2463.Em operators . 2464.Pp 2465.Em Arguments 2466.Pp 2467.Em Arguments 2468are symbols, numbers or subexpressions. In other contexts arguments are sometimes 2469called \(lqarithmetic operands\(rq. In this manual, to avoid confusing them with the 2470\(lqinstruction operands\(rq of the machine language, we use the term \(lqargument\(rq to 2471refer to parts of expressions only, reserving the word \(lqoperand\(rq to refer only 2472to machine instruction operands. 2473.Pp 2474Symbols are evaluated to yield { 2475.Va section 2476.Va NNN 2477}where 2478.Va section 2479is one of text, data, bss, absolute, or undefined. 2480.Va NNN 2481is a signed, 2's complement 32 bit integer. 2482.Pp 2483Numbers are usually integers. 2484.Pp 2485A number can be a flonum or biGNUm. In this case, you are warned that only 2486the low order 32 bits are used, and 2487.Xr as 2488pretends these 32 bits are an integer. You may write integer-manipulating 2489instructions that act on exotic constants, compatible with other assemblers. 2490.Pp 2491Subexpressions are a left parenthesis 2492.Li ( 2493followed by an integer expression, followed by a right parenthesis 2494.Li ) ; 2495or a prefix operator followed by an argument. 2496.Pp 2497.Em Operators 2498.Pp 2499.Em Operators 2500are arithmetic functions, like 2501.Li + 2502or 2503.Li % . 2504Prefix operators are followed by an argument. Infix operators appear between 2505their arguments. Operators may be preceded and/or followed by whitespace. 2506.Pp 2507.Em Prefix Operator 2508.Pp 2509.Xr as 2510has the following 2511.Em prefix operators . 2512They each take one argument, which must be absolute. 2513.Pp 2514.Bl -tag -width Ds 2515.It - 2516.Em Negation . 2517Two's complement negation. 2518.It ~ 2519.Em Complementation . 2520Bitwise not. 2521.El 2522.Pp 2523.Em Infix Operators 2524.Pp 2525.Em Infix operators 2526take two arguments, one on either side. Operators have precedence, but operations 2527with equal precedence are performed left to right. Apart from 2528.Li + 2529or 2530.Op - , 2531both arguments must be absolute, and the result is absolute. 2532.Pp 2533.Bl -enum 2534.It 2535Highest Precedence 2536.Pp 2537.Bl -tag -width Ds 2538.It * 2539.Em Multiplication . 2540.Pp 2541.It / 2542.Em Division . 2543Truncation is the same as the C operator 2544.Li / 2545.Pp 2546.It % 2547.Em Remainder . 2548.Pp 2549.It << 2550.Em Shift Left . 2551Same as the C operator 2552.Li << . 2553.Pp 2554.It >> 2555.Em Shift Right . 2556Same as the C operator 2557.Li >> . 2558.El 2559.Pp 2560.It 2561Intermediate precedence 2562.Pp 2563.Bl -tag -width Ds 2564.It | 2565.Pp 2566.Em Bitwise Inclusive Or . 2567.Pp 2568.It & 2569.Em Bitwise And . 2570.Pp 2571.It ^ 2572.Em Bitwise Exclusive Or . 2573.Pp 2574.It ! 2575.Em Bitwise Or Not . 2576.El 2577.Pp 2578.It 2579Low Precedence 2580.Pp 2581.Bl -tag -width Ds 2582.It + 2583.Em Addition . 2584If either argument is absolute, the result has the section of the other argument. 2585You may not add together arguments from different sections. 2586.Pp 2587.It - 2588.Em Subtraction . 2589If the right argument is absolute, the result has the section of the left 2590argument. If both arguments are in the same section, the result is absolute. 2591You may not subtract arguments from different sections. 2592.Pp 2593.It == 2594.Em Is Equal To 2595.It <> 2596.It != 2597.Em Is Not Equal To 2598.It < 2599.Em Is Less Than 2600.It > 2601.Em Is Greater Than 2602.It >= 2603.Em Is Greater Than Or Equal To 2604.It <= 2605.Em Is Less Than Or Equal To 2606.Pp 2607The comparison operators can be used as infix operators. A true results has 2608a value of -1 whereas a false result has a value of 0. Note, these operators 2609perform signed comparisons. 2610.El 2611.Pp 2612.It 2613Lowest Precedence 2614.Pp 2615.Bl -tag -width Ds 2616.It && 2617.Em Logical And . 2618.Pp 2619.It || 2620.Em Logical Or . 2621.Pp 2622These two logical operations can be used to combine the results of sub expressions. 2623Note, unlike the comparison operators a true result returns a value of 1 but 2624a false results does still return 0. Also note that the logical or operator 2625has a slightly lower precedence than logical and. 2626.Pp 2627.El 2628.El 2629In short, it's only meaningful to add or subtract the 2630.Em offsets 2631in an address; you can only have a defined section in one of the two arguments. 2632.Pp 2633.Sh Assembler Directives 2634All assembler directives have names that begin with a period ( 2635.Li . ) . 2636The rest of the name is letters, usually in lower case. 2637.Pp 2638This chapter discusses directives that are available regardless of the target 2639machine configuration for the GNU assembler. 2640.Pp 2641.Ss Li .abort 2642This directive stops the assembly immediately. It is for compatibility with 2643other assemblers. The original idea was that the assembly language source 2644would be piped into the assembler. If the sender of the source quit, it could 2645use this directive tells 2646.Xr as 2647to quit also. One day 2648.Li .abort 2649will not be supported. 2650.Pp 2651.Ss Li .align Va abs-expr, Va abs-expr, Va abs-expr 2652Pad the location counter (in the current subsection) to a particular storage 2653boundary. The first expression (which must be absolute) is the alignment required, 2654as described below. 2655.Pp 2656The second expression (also absolute) gives the fill value to be stored in 2657the padding bytes. It (and the comma) may be omitted. If it is omitted, the 2658padding bytes are normally zero. However, on some systems, if the section 2659is marked as containing code and the fill value is omitted, the space is filled 2660with no-op instructions. 2661.Pp 2662The third expression is also absolute, and is also optional. If it is present, 2663it is the maximum number of bytes that should be skipped by this alignment 2664directive. If doing the alignment would require skipping more bytes than the 2665specified maximum, then the alignment is not done at all. You can omit the 2666fill value (the second argument) entirely by simply using two commas after 2667the required alignment; this can be useful if you want the alignment to be 2668filled with no-op instructions when appropriate. 2669.Pp 2670The way the required alignment is specified varies from system to system. 2671For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, s390, sparc, 2672tic4x, tic80 and xtensa, the first expression is the alignment request in 2673bytes. For example 2674.Li .align 8 2675advances the location counter until it is a multiple of 8. If the location 2676counter is already a multiple of 8, no change is needed. For the tic54x, the 2677first expression is the alignment request in words. 2678.Pp 2679For other systems, including the i386 using a.out format, and the arm and 2680strongarm, it is the number of low-order zero bits the location counter must 2681have after advancement. For example 2682.Li .align 3 2683advances the location counter until it a multiple of 8. If the location counter 2684is already a multiple of 8, no change is needed. 2685.Pp 2686This inconsistency is due to the different behaviors of the various native 2687assemblers for these systems which GAS must emulate. GAS also provides 2688.Li .balign 2689and 2690.Li .p2align 2691directives, described later, which have a consistent behavior across all architectures 2692(but are specific to GAS). 2693.Pp 2694.Ss Li .ascii " Va string"... 2695.Li .ascii 2696expects zero or more string literals (see Section 2697.Dq Strings ) 2698separated by commas. It assembles each string (with no automatic trailing 2699zero byte) into consecutive addresses. 2700.Pp 2701.Ss Li .asciz " Va string"... 2702.Li .asciz 2703is just like 2704.Li .ascii , 2705but each string is followed by a zero byte. The \(lqz\(rq in 2706.Li .asciz 2707stands for \(lqzero\(rq. 2708.Pp 2709.Ss Li .balign[wl] Va abs-expr, Va abs-expr, Va abs-expr 2710Pad the location counter (in the current subsection) to a particular storage 2711boundary. The first expression (which must be absolute) is the alignment request 2712in bytes. For example 2713.Li .balign 8 2714advances the location counter until it is a multiple of 8. If the location 2715counter is already a multiple of 8, no change is needed. 2716.Pp 2717The second expression (also absolute) gives the fill value to be stored in 2718the padding bytes. It (and the comma) may be omitted. If it is omitted, the 2719padding bytes are normally zero. However, on some systems, if the section 2720is marked as containing code and the fill value is omitted, the space is filled 2721with no-op instructions. 2722.Pp 2723The third expression is also absolute, and is also optional. If it is present, 2724it is the maximum number of bytes that should be skipped by this alignment 2725directive. If doing the alignment would require skipping more bytes than the 2726specified maximum, then the alignment is not done at all. You can omit the 2727fill value (the second argument) entirely by simply using two commas after 2728the required alignment; this can be useful if you want the alignment to be 2729filled with no-op instructions when appropriate. 2730.Pp 2731The 2732.Li .balignw 2733and 2734.Li .balignl 2735directives are variants of the 2736.Li .balign 2737directive. The 2738.Li .balignw 2739directive treats the fill pattern as a two byte word value. The 2740.Li .balignl 2741directives treats the fill pattern as a four byte longword value. For example, 2742.Li .balignw 4,0x368d 2743will align to a multiple of 4. If it skips two bytes, they will be filled 2744in with the value 0x368d (the exact placement of the bytes depends upon the 2745endianness of the processor). If it skips 1 or 3 bytes, the fill value is 2746undefined. 2747.Pp 2748.Ss Li .byte Va expressions 2749.Li .byte 2750expects zero or more expressions, separated by commas. Each expression is 2751assembled into the next byte. 2752.Pp 2753.Ss Li .comm Va symbol , Va length 2754.Li .comm 2755declares a common symbol named 2756.Va symbol . 2757When linking, a common symbol in one object file may be merged with a defined 2758or common symbol of the same name in another object file. If 2759.Li ld 2760does not see a definition for the symbol--just one or more common symbols--then 2761it will allocate 2762.Va length 2763bytes of uninitialized memory. 2764.Va length 2765must be an absolute expression. If 2766.Li ld 2767sees multiple common symbols with the same name, and they do not all have 2768the same size, it will allocate space using the largest size. 2769.Pp 2770When using ELF, the 2771.Li .comm 2772directive takes an optional third argument. This is the desired alignment 2773of the symbol, specified as a byte boundary (for example, an alignment of 277416 means that the least significant 4 bits of the address should be zero). 2775The alignment must be an absolute expression, and it must be a power of two. 2776If 2777.Li ld 2778allocates uninitialized memory for the common symbol, it will use the alignment 2779when placing the symbol. If no alignment is specified, 2780.Xr as 2781will set the alignment to the largest power of two less than or equal to the 2782size of the symbol, up to a maximum of 16. 2783.Pp 2784.Ss Li .cfi_startproc [simple] 2785.Li .cfi_startproc 2786is used at the beginning of each function that should have an entry in 2787.Li .eh_frame . 2788It initializes some internal data structures. Don't forget to close the function 2789by 2790.Li .cfi_endproc . 2791.Pp 2792Unless 2793.Li .cfi_startproc 2794is used along with parameter 2795.Li simple 2796it also emits some architecture dependent initial CFI instructions. 2797.Ss Li .cfi_endproc 2798.Li .cfi_endproc 2799is used at the end of a function where it closes its unwind entry previously 2800opened by 2801.Li .cfi_startproc , 2802and emits it to 2803.Li .eh_frame . 2804.Pp 2805.Ss Li .cfi_personality Va encoding [, Va exp] 2806.Li .cfi_personality 2807defines personality routine and its encoding. 2808.Va encoding 2809must be a constant determining how the personality should be encoded. If it 2810is 255 ( 2811.Li DW_EH_PE_omit ) , 2812second argument is not present, otherwise second argument should be a constant 2813or a symbol name. When using indirect encodings, the symbol provided should 2814be the location where personality can be loaded from, not the personality 2815routine itself. The default after 2816.Li .cfi_startproc 2817is 2818.Li .cfi_personality 0xff , 2819no personality routine. 2820.Pp 2821.Ss Li .cfi_lsda Va encoding [, Va exp] 2822.Li .cfi_lsda 2823defines LSDA and its encoding. 2824.Va encoding 2825must be a constant determining how the LSDA should be encoded. If it is 255 2826( 2827.Li DW_EH_PE_omit ) , 2828second argument is not present, otherwise second argument should be a constant 2829or a symbol name. The default after 2830.Li .cfi_startproc 2831is 2832.Li .cfi_lsda 0xff , 2833no LSDA. 2834.Pp 2835.Ss Li .cfi_def_cfa Va register, Va offset 2836.Li .cfi_def_cfa 2837defines a rule for computing CFA as: 2838.Em take address from Va register and add Va offset to it . 2839.Pp 2840.Ss Li .cfi_def_cfa_register Va register 2841.Li .cfi_def_cfa_register 2842modifies a rule for computing CFA. From now on 2843.Va register 2844will be used instead of the old one. Offset remains the same. 2845.Pp 2846.Ss Li .cfi_def_cfa_offset Va offset 2847.Li .cfi_def_cfa_offset 2848modifies a rule for computing CFA. Register remains the same, but 2849.Va offset 2850is new. Note that it is the absolute offset that will be added to a defined 2851register to compute CFA address. 2852.Pp 2853.Ss Li .cfi_adjust_cfa_offset Va offset 2854Same as 2855.Li .cfi_def_cfa_offset 2856but 2857.Va offset 2858is a relative value that is added/substracted from the previous offset. 2859.Pp 2860.Ss Li .cfi_offset Va register, Va offset 2861Previous value of 2862.Va register 2863is saved at offset 2864.Va offset 2865from CFA. 2866.Pp 2867.Ss Li .cfi_rel_offset Va register, Va offset 2868Previous value of 2869.Va register 2870is saved at offset 2871.Va offset 2872from the current CFA register. This is transformed to 2873.Li .cfi_offset 2874using the known displacement of the CFA register from the CFA. This is often 2875easier to use, because the number will match the code it's annotating. 2876.Pp 2877.Ss Li .cfi_register Va register1, Va register2 2878Previous value of 2879.Va register1 2880is saved in register 2881.Va register2 . 2882.Pp 2883.Ss Li .cfi_restore Va register 2884.Li .cfi_restore 2885says that the rule for 2886.Va register 2887is now the same as it was at the beginning of the function, after all initial 2888instruction added by 2889.Li .cfi_startproc 2890were executed. 2891.Pp 2892.Ss Li .cfi_undefined Va register 2893From now on the previous value of 2894.Va register 2895can't be restored anymore. 2896.Pp 2897.Ss Li .cfi_same_value Va register 2898Current value of 2899.Va register 2900is the same like in the previous frame, i.e. no restoration needed. 2901.Pp 2902.Ss Li .cfi_remember_state, 2903First save all current rules for all registers by 2904.Li .cfi_remember_state , 2905then totally screw them up by subsequent 2906.Li .cfi_* 2907directives and when everything is hopelessly bad, use 2908.Li .cfi_restore_state 2909to restore the previous saved state. 2910.Pp 2911.Ss Li .cfi_return_column Va register 2912Change return column 2913.Va register , 2914i.e. the return address is either directly in 2915.Va register 2916or can be accessed by rules for 2917.Va register . 2918.Pp 2919.Ss Li .cfi_signal_frame 2920Mark current function as signal trampoline. 2921.Pp 2922.Ss Li .cfi_window_save 2923SPARC register window has been saved. 2924.Pp 2925.Ss Li .cfi_escape Va expression[, ...] 2926Allows the user to add arbitrary bytes to the unwind info. One might use this 2927to add OS-specific CFI opcodes, or generic CFI opcodes that GAS does not yet 2928support. 2929.Pp 2930.Ss Li .file Va fileno Va filename 2931When emitting dwarf2 line number information 2932.Li .file 2933assigns filenames to the 2934.Li .debug_line 2935file name table. The 2936.Va fileno 2937operand should be a unique positive integer to use as the index of the entry 2938in the table. The 2939.Va filename 2940operand is a C string literal. 2941.Pp 2942The detail of filename indices is exposed to the user because the filename 2943table is shared with the 2944.Li .debug_info 2945section of the dwarf2 debugging information, and thus the user must know the 2946exact indices that table entries will have. 2947.Pp 2948.Ss Li .loc Va fileno Va lineno [ Va column] [ Va options] 2949The 2950.Li .loc 2951directive will add row to the 2952.Li .debug_line 2953line number matrix corresponding to the immediately following assembly instruction. 2954The 2955.Va fileno , 2956.Va lineno , 2957and optional 2958.Va column 2959arguments will be applied to the 2960.Li .debug_line 2961state machine before the row is added. 2962.Pp 2963The 2964.Va options 2965are a sequence of the following tokens in any order: 2966.Pp 2967.Bl -tag -width Ds 2968.It basic_block 2969This option will set the 2970.Li basic_block 2971register in the 2972.Li .debug_line 2973state machine to 2974.Li true . 2975.Pp 2976.It prologue_end 2977This option will set the 2978.Li prologue_end 2979register in the 2980.Li .debug_line 2981state machine to 2982.Li true . 2983.Pp 2984.It epilogue_begin 2985This option will set the 2986.Li epilogue_begin 2987register in the 2988.Li .debug_line 2989state machine to 2990.Li true . 2991.Pp 2992.It is_stmt Va value 2993This option will set the 2994.Li is_stmt 2995register in the 2996.Li .debug_line 2997state machine to 2998.Li value , 2999which must be either 0 or 1. 3000.Pp 3001.It isa Va value 3002This directive will set the 3003.Li isa 3004register in the 3005.Li .debug_line 3006state machine to 3007.Va value , 3008which must be an unsigned integer. 3009.Pp 3010.El 3011.Ss Li .loc_mark_blocks Va enable 3012The 3013.Li .loc_mark_blocks 3014directive makes the assembler emit an entry to the 3015.Li .debug_line 3016line number matrix with the 3017.Li basic_block 3018register in the state machine set whenever a code label is seen. The 3019.Va enable 3020argument should be either 1 or 0, to enable or disable this function respectively. 3021.Pp 3022.Ss Li .data Va subsection 3023.Li .data 3024tells 3025.Xr as 3026to assemble the following statements onto the end of the data subsection numbered 3027.Va subsection 3028(which is an absolute expression). If 3029.Va subsection 3030is omitted, it defaults to zero. 3031.Pp 3032.Ss Li .double Va flonums 3033.Li .double 3034expects zero or more flonums, separated by commas. It assembles floating point 3035numbers. 3036.Pp 3037.Ss Li .eject 3038Force a page break at this point, when generating assembly listings. 3039.Pp 3040.Ss Li .else 3041.Li .else 3042is part of the 3043.Xr as 3044support for conditional assembly; see If,, 3045.Li .if 3046\&. It marks the beginning of a section of code to be assembled if the condition 3047for the preceding 3048.Li .if 3049was false. 3050.Pp 3051.Ss Li .elseif 3052.Li .elseif 3053is part of the 3054.Xr as 3055support for conditional assembly; see If,, 3056.Li .if 3057\&. It is shorthand for beginning a new 3058.Li .if 3059block that would otherwise fill the entire 3060.Li .else 3061section. 3062.Pp 3063.Ss Li .end 3064.Li .end 3065marks the end of the assembly file. 3066.Xr as 3067does not process anything in the file past the 3068.Li .end 3069directive. 3070.Pp 3071.Ss Li .endfunc 3072.Li .endfunc 3073marks the end of a function specified with 3074.Li .func . 3075.Pp 3076.Ss Li .endif 3077.Li .endif 3078is part of the 3079.Xr as 3080support for conditional assembly; it marks the end of a block of code that 3081is only assembled conditionally.See Section 3082.Dq If . 3083.Pp 3084.Ss Li .equ Va symbol, Va expression 3085This directive sets the value of 3086.Va symbol 3087to 3088.Va expression . 3089It is synonymous with 3090.Li .set ; 3091see Set,, 3092.Li .set 3093\&. 3094.Pp 3095.Ss Li .equiv Va symbol, Va expression 3096The 3097.Li .equiv 3098directive is like 3099.Li .equ 3100and 3101.Li .set , 3102except that the assembler will signal an error if 3103.Va symbol 3104is already defined. Note a symbol which has been referenced but not actually 3105defined is considered to be undefined. 3106.Pp 3107Except for the contents of the error message, this is roughly equivalent to 3108.Bd -literal -offset indent 3109\&.ifdef SYM 3110\&.err 3111\&.endif 3112\&.equ SYM,VAL 3113.Ed 3114plus it protects the symbol from later redefinition. 3115.Pp 3116.Ss Li .eqv Va symbol, Va expression 3117The 3118.Li .eqv 3119directive is like 3120.Li .equiv , 3121but no attempt is made to evaluate the expression or any part of it immediately. 3122Instead each time the resulting symbol is used in an expression, a snapshot 3123of its current value is taken. 3124.Pp 3125.Ss Li .err 3126If 3127.Xr as 3128assembles a 3129.Li .err 3130directive, it will print an error message and, unless the 3131.Op -Z 3132option was used, it will not generate an object file. This can be used to 3133signal an error in conditionally compiled code. 3134.Pp 3135.Ss Li .error " Va string" 3136Similarly to 3137.Li .err , 3138this directive emits an error, but you can specify a string that will be emitted 3139as the error message. If you don't specify the message, it defaults to 3140.Li ".error directive invoked in source file" . 3141See Section.Dq Errors . 3142.Pp 3143.Bd -literal -offset indent 3144 .error "This code has not been assembled and tested." 3145.Ed 3146.Pp 3147.Ss Li .exitm 3148Exit early from the current macro definition.See Section 3149.Dq Macro . 3150.Pp 3151.Ss Li .extern 3152.Li .extern 3153is accepted in the source program---for compatibility with other assemblers---but 3154it is ignored. 3155.Xr as 3156treats all undefined symbols as external. 3157.Pp 3158.Ss Li .fail Va expression 3159Generates an error or a warning. If the value of the 3160.Va expression 3161is 500 or more, 3162.Xr as 3163will print a warning message. If the value is less than 500, 3164.Xr as 3165will print an error message. The message will include the value of 3166.Va expression . 3167This can occasionally be useful inside complex nested macros or conditional 3168assembly. 3169.Pp 3170.Ss Li .file Va string 3171.Li .file 3172tells 3173.Xr as 3174that we are about to start a new logical file. 3175.Va string 3176is the new file name. In general, the filename is recognized whether or not 3177it is surrounded by quotes 3178.Li " ; 3179but if you wish to specify an empty file name, you must give the quotes-- 3180.Li "" . 3181This statement may go away in future: it is only recognized to be compatible 3182with old 3183.Xr as 3184programs. 3185.Pp 3186.Ss Li .fill Va repeat , Va size , Va value 3187.Va repeat , 3188.Va size 3189and 3190.Va value 3191are absolute expressions. This emits 3192.Va repeat 3193copies of 3194.Va size 3195bytes. 3196.Va Repeat 3197may be zero or more. 3198.Va Size 3199may be zero or more, but if it is more than 8, then it is deemed to have the 3200value 8, compatible with other people's assemblers. The contents of each 3201.Va repeat 3202bytes is taken from an 8-byte number. The highest order 4 bytes are zero. 3203The lowest order 4 bytes are 3204.Va value 3205rendered in the byte-order of an integer on the computer 3206.Xr as 3207is assembling for. Each 3208.Va size 3209bytes in a repetition is taken from the lowest order 3210.Va size 3211bytes of this number. Again, this bizarre behavior is compatible with other 3212people's assemblers. 3213.Pp 3214.Va size 3215and 3216.Va value 3217are optional. If the second comma and 3218.Va value 3219are absent, 3220.Va value 3221is assumed zero. If the first comma and following tokens are absent, 3222.Va size 3223is assumed to be 1. 3224.Pp 3225.Ss Li .float Va flonums 3226This directive assembles zero or more flonums, separated by commas. It has 3227the same effect as 3228.Li .single . 3229.Pp 3230.Ss Li .func Va name[, Va label] 3231.Li .func 3232emits debugging information to denote function 3233.Va name , 3234and is ignored unless the file is assembled with debugging enabled. Only 3235.Li --gstabs[+] 3236is currently supported. 3237.Va label 3238is the entry point of the function and if omitted 3239.Va name 3240prepended with the 3241.Li leading char 3242is used. 3243.Li leading char 3244is usually 3245.Li _ 3246or nothing, depending on the target. All functions are currently defined to 3247have 3248.Li void 3249return type. The function must be terminated with 3250.Li .endfunc . 3251.Pp 3252.Ss Li .global Va symbol, Li .globl Va symbol 3253.Li .global 3254makes the symbol visible to 3255.Li ld . 3256If you define 3257.Va symbol 3258in your partial program, its value is made available to other partial programs 3259that are linked with it. Otherwise, 3260.Va symbol 3261takes its attributes from a symbol of the same name from another file linked 3262into the same program. 3263.Pp 3264Both spellings ( 3265.Li .globl 3266and 3267.Li .global ) 3268are accepted, for compatibility with other assemblers. 3269.Pp 3270.Ss Li .hidden Va names 3271This is one of the ELF visibility directives. The other two are 3272.Li .internal 3273(see Section 3274.Dq Internal ) 3275and 3276.Li .protected 3277(see Section 3278.Dq Protected ) . 3279.Pp 3280This directive overrides the named symbols default visibility (which is set 3281by their binding: local, global or weak). The directive sets the visibility 3282to 3283.Li hidden 3284which means that the symbols are not visible to other components. Such symbols 3285are always considered to be 3286.Li protected 3287as well. 3288.Pp 3289.Ss Li .hword Va expressions 3290This expects zero or more 3291.Va expressions , 3292and emits a 16 bit number for each. 3293.Pp 3294This directive is a synonym for 3295.Li .short . 3296.Pp 3297.Ss Li .ident 3298This directive is used by some assemblers to place tags in object files. The 3299behavior of this directive varies depending on the target. When using the 3300a.out object file format, 3301.Xr as 3302simply accepts the directive for source-file compatibility with existing assemblers, 3303but does not emit anything for it. When using COFF, comments are emitted to 3304the 3305.Li .comment 3306or 3307.Li .rdata 3308section, depending on the target. When using ELF, comments are emitted to 3309the 3310.Li .comment 3311section. 3312.Pp 3313.Ss Li .if Va absolute expression 3314.Li .if 3315marks the beginning of a section of code which is only considered part of 3316the source program being assembled if the argument (which must be an 3317.Va absolute expression ) 3318is non-zero. The end of the conditional section of code must be marked by 3319.Li .endif 3320(see Section 3321.Dq Endif ) ; 3322optionally, you may include code for the alternative condition, flagged by 3323.Li .else 3324(see Section 3325.Dq Else ) . 3326If you have several conditions to check, 3327.Li .elseif 3328may be used to avoid nesting blocks if/else within each subsequent 3329.Li .else 3330block. 3331.Pp 3332The following variants of 3333.Li .if 3334are also supported: 3335.Bl -tag -width Ds 3336.It .ifdef Va symbol 3337Assembles the following section of code if the specified 3338.Va symbol 3339has been defined. Note a symbol which has been referenced but not yet defined 3340is considered to be undefined. 3341.Pp 3342.It .ifb Va text 3343Assembles the following section of code if the operand is blank (empty). 3344.Pp 3345.It .ifc Va string1, Va string2 3346Assembles the following section of code if the two strings are the same. The 3347strings may be optionally quoted with single quotes. If they are not quoted, 3348the first string stops at the first comma, and the second string stops at 3349the end of the line. Strings which contain whitespace should be quoted. The 3350string comparison is case sensitive. 3351.Pp 3352.It .ifeq Va absolute expression 3353Assembles the following section of code if the argument is zero. 3354.Pp 3355.It .ifeqs Va string1, Va string2 3356Another form of 3357.Li .ifc . 3358The strings must be quoted using double quotes. 3359.Pp 3360.It .ifge Va absolute expression 3361Assembles the following section of code if the argument is greater than or 3362equal to zero. 3363.Pp 3364.It .ifgt Va absolute expression 3365Assembles the following section of code if the argument is greater than zero. 3366.Pp 3367.It .ifle Va absolute expression 3368Assembles the following section of code if the argument is less than or equal 3369to zero. 3370.Pp 3371.It .iflt Va absolute expression 3372Assembles the following section of code if the argument is less than zero. 3373.Pp 3374.It .ifnb Va text 3375Like 3376.Li .ifb , 3377but the sense of the test is reversed: this assembles the following section 3378of code if the operand is non-blank (non-empty). 3379.Pp 3380.It .ifnc Va string1, Va string2. 3381Like 3382.Li .ifc , 3383but the sense of the test is reversed: this assembles the following section 3384of code if the two strings are not the same. 3385.Pp 3386.It .ifndef Va symbol 3387.It .ifnotdef Va symbol 3388Assembles the following section of code if the specified 3389.Va symbol 3390has not been defined. Both spelling variants are equivalent. Note a symbol 3391which has been referenced but not yet defined is considered to be undefined. 3392.Pp 3393.It .ifne Va absolute expression 3394Assembles the following section of code if the argument is not equal to zero 3395(in other words, this is equivalent to 3396.Li .if ) . 3397.Pp 3398.It .ifnes Va string1, Va string2 3399Like 3400.Li .ifeqs , 3401but the sense of the test is reversed: this assembles the following section 3402of code if the two strings are not the same. 3403.El 3404.Pp 3405.Ss Li .incbin " Va file"[, Va skip[, Va count]] 3406The 3407.Li incbin 3408directive includes 3409.Va file 3410verbatim at the current location. You can control the search paths used with 3411the 3412.Li -I 3413command-line option (see Section 3414.Dq Invoking ) . 3415Quotation marks are required around 3416.Va file . 3417.Pp 3418The 3419.Va skip 3420argument skips a number of bytes from the start of the 3421.Va file . 3422The 3423.Va count 3424argument indicates the maximum number of bytes to read. Note that the data 3425is not aligned in any way, so it is the user's responsibility to make sure 3426that proper alignment is provided both before and after the 3427.Li incbin 3428directive. 3429.Pp 3430.Ss Li .include " Va file" 3431This directive provides a way to include supporting files at specified points 3432in your source program. The code from 3433.Va file 3434is assembled as if it followed the point of the 3435.Li .include ; 3436when the end of the included file is reached, assembly of the original file 3437continues. You can control the search paths used with the 3438.Li -I 3439command-line option (see Section 3440.Dq Invoking ) . 3441Quotation marks are required around 3442.Va file . 3443.Pp 3444.Ss Li .int Va expressions 3445Expect zero or more 3446.Va expressions , 3447of any section, separated by commas. For each expression, emit a number that, 3448at run time, is the value of that expression. The byte order and bit size 3449of the number depends on what kind of target the assembly is for. 3450.Pp 3451.Ss Li .internal Va names 3452This is one of the ELF visibility directives. The other two are 3453.Li .hidden 3454(see Section 3455.Dq Hidden ) 3456and 3457.Li .protected 3458(see Section 3459.Dq Protected ) . 3460.Pp 3461This directive overrides the named symbols default visibility (which is set 3462by their binding: local, global or weak). The directive sets the visibility 3463to 3464.Li internal 3465which means that the symbols are considered to be 3466.Li hidden 3467(i.e., not visible to other components), and that some extra, processor specific 3468processing must also be performed upon the symbols as well. 3469.Pp 3470.Ss Li .irp Va symbol, Va values... 3471Evaluate a sequence of statements assigning different values to 3472.Va symbol . 3473The sequence of statements starts at the 3474.Li .irp 3475directive, and is terminated by an 3476.Li .endr 3477directive. For each 3478.Va value , 3479.Va symbol 3480is set to 3481.Va value , 3482and the sequence of statements is assembled. If no 3483.Va value 3484is listed, the sequence of statements is assembled once, with 3485.Va symbol 3486set to the null string. To refer to 3487.Va symbol 3488within the sequence of statements, use 3489.Va \esymbol . 3490.Pp 3491For example, assembling 3492.Pp 3493.Bd -literal -offset indent 3494 .irp param,1,2,3 3495 move d\eparam,sp@- 3496 .endr 3497.Ed 3498.Pp 3499is equivalent to assembling 3500.Pp 3501.Bd -literal -offset indent 3502 move d1,sp@- 3503 move d2,sp@- 3504 move d3,sp@- 3505.Ed 3506.Pp 3507For some caveats with the spelling of 3508.Va symbol , 3509see also Macro. 3510.Pp 3511.Ss Li .irpc Va symbol, Va values... 3512Evaluate a sequence of statements assigning different values to 3513.Va symbol . 3514The sequence of statements starts at the 3515.Li .irpc 3516directive, and is terminated by an 3517.Li .endr 3518directive. For each character in 3519.Va value , 3520.Va symbol 3521is set to the character, and the sequence of statements is assembled. If no 3522.Va value 3523is listed, the sequence of statements is assembled once, with 3524.Va symbol 3525set to the null string. To refer to 3526.Va symbol 3527within the sequence of statements, use 3528.Va \esymbol . 3529.Pp 3530For example, assembling 3531.Pp 3532.Bd -literal -offset indent 3533 .irpc param,123 3534 move d\eparam,sp@- 3535 .endr 3536.Ed 3537.Pp 3538is equivalent to assembling 3539.Pp 3540.Bd -literal -offset indent 3541 move d1,sp@- 3542 move d2,sp@- 3543 move d3,sp@- 3544.Ed 3545.Pp 3546For some caveats with the spelling of 3547.Va symbol , 3548see also the discussion atSee Section 3549.Dq Macro . 3550.Pp 3551.Ss Li .lcomm Va symbol , Va length 3552Reserve 3553.Va length 3554(an absolute expression) bytes for a local common denoted by 3555.Va symbol . 3556The section and value of 3557.Va symbol 3558are those of the new local common. The addresses are allocated in the bss 3559section, so that at run-time the bytes start off zeroed. 3560.Va Symbol 3561is not declared global (see Section 3562.Dq Global ) , 3563so is normally not visible to 3564.Li ld . 3565.Pp 3566.Ss Li .lflags 3567.Xr as 3568accepts this directive, for compatibility with other assemblers, but ignores 3569it. 3570.Pp 3571.Ss Li .line Va line-number 3572Even though this is a directive associated with the 3573.Li a.out 3574or 3575.Li b.out 3576object-code formats, 3577.Xr as 3578still recognizes it when producing COFF output, and treats 3579.Li .line 3580as though it were the COFF 3581.Li .ln 3582.Em if 3583it is found outside a 3584.Li .def 3585/ 3586.Li .endef 3587pair. 3588.Pp 3589Inside a 3590.Li .def , 3591.Li .line 3592is, instead, one of the directives used by compilers to generate auxiliary 3593symbol information for debugging. 3594.Pp 3595.Ss Li .linkonce [ Va type] 3596Mark the current section so that the linker only includes a single copy of 3597it. This may be used to include the same section in several different object 3598files, but ensure that the linker will only include it once in the final output 3599file. The 3600.Li .linkonce 3601pseudo-op must be used for each instance of the section. Duplicate sections 3602are detected based on the section name, so it should be unique. 3603.Pp 3604This directive is only supported by a few object file formats; as of this 3605writing, the only object file format which supports it is the Portable Executable 3606format used on Windows NT. 3607.Pp 3608The 3609.Va type 3610argument is optional. If specified, it must be one of the following strings. 3611For example: 3612.Bd -literal -offset indent 3613\&.linkonce same_size 3614.Ed 3615Not all types may be supported on all object file formats. 3616.Pp 3617.Bl -tag -width Ds 3618.It discard 3619Silently discard duplicate sections. This is the default. 3620.Pp 3621.It one_only 3622Warn if there are duplicate sections, but still keep only one copy. 3623.Pp 3624.It same_size 3625Warn if any of the duplicates have different sizes. 3626.Pp 3627.It same_contents 3628Warn if any of the duplicates do not have exactly the same contents. 3629.El 3630.Pp 3631.Ss Li .ln Va line-number 3632.Li .ln 3633is a synonym for 3634.Li .line . 3635.Pp 3636.Ss Li .mri Va val 3637If 3638.Va val 3639is non-zero, this tells 3640.Xr as 3641to enter MRI mode. If 3642.Va val 3643is zero, this tells 3644.Xr as 3645to exit MRI mode. This change affects code assembled until the next 3646.Li .mri 3647directive, or until the end of the file.See Section 3648.Dq M . 3649.Pp 3650.Ss Li .list 3651Control (in conjunction with the 3652.Li .nolist 3653directive) whether or not assembly listings are generated. These two directives 3654maintain an internal counter (which is zero initially). 3655.Li .list 3656increments the counter, and 3657.Li .nolist 3658decrements it. Assembly listings are generated whenever the counter is greater 3659than zero. 3660.Pp 3661By default, listings are disabled. When you enable them (with the 3662.Li -a 3663command line option;see Section 3664.Dq Invoking ) , 3665the initial value of the listing counter is one. 3666.Pp 3667.Ss Li .long Va expressions 3668.Li .long 3669is the same as 3670.Li .int . 3671See Section.Dq Int . 3672.Pp 3673.Ss Li .macro 3674The commands 3675.Li .macro 3676and 3677.Li .endm 3678allow you to define macros that generate assembly output. For example, this 3679definition specifies a macro 3680.Li sum 3681that puts a sequence of numbers into memory: 3682.Pp 3683.Bd -literal -offset indent 3684 .macro sum from=0, to=5 3685 .long \efrom 3686 .if \eto-\efrom 3687 sum "(\efrom+1)",\eto 3688 .endif 3689 .endm 3690.Ed 3691.Pp 3692With that definition, 3693.Li SUM 0,5 3694is equivalent to this assembly input: 3695.Pp 3696.Bd -literal -offset indent 3697 .long 0 3698 .long 1 3699 .long 2 3700 .long 3 3701 .long 4 3702 .long 5 3703.Ed 3704.Pp 3705.Bl -tag -width Ds 3706.It .macro Va macname 3707.It .macro Va macname Va macargs ... 3708Begin the definition of a macro called 3709.Va macname . 3710If your macro definition requires arguments, specify their names after the 3711macro name, separated by commas or spaces. You can qualify the macro argument 3712to indicate whether all invocations must specify a non-blank value (through 3713.Li : Li req ) , 3714or whether it takes all of the remaining arguments (through 3715.Li : Li vararg ) . 3716You can supply a default value for any macro argument by following the name 3717with 3718.Li = Va deflt . 3719You cannot define two macros with the same 3720.Va macname 3721unless it has been subject to the 3722.Li .purgem 3723directive (see Section 3724.Dq Purgem ) 3725between the two definitions. For example, these are all valid 3726.Li .macro 3727statements: 3728.Pp 3729.Bl -tag -width Ds 3730.It .macro comm 3731Begin the definition of a macro called 3732.Li comm , 3733which takes no arguments. 3734.Pp 3735.It .macro plus1 p, p1 3736.It .macro plus1 p p1 3737Either statement begins the definition of a macro called 3738.Li plus1 , 3739which takes two arguments; within the macro definition, write 3740.Li \ep 3741or 3742.Li \ep1 3743to evaluate the arguments. 3744.Pp 3745.It .macro reserve_str p1=0 p2 3746Begin the definition of a macro called 3747.Li reserve_str , 3748with two arguments. The first argument has a default value, but not the second. 3749After the definition is complete, you can call the macro either as 3750.Li reserve_str Va a, Va b 3751(with 3752.Li \ep1 3753evaluating to 3754.Va a 3755and 3756.Li \ep2 3757evaluating to 3758.Va b ) , 3759or as 3760.Li reserve_str , Va b 3761(with 3762.Li \ep1 3763evaluating as the default, in this case 3764.Li 0 , 3765and 3766.Li \ep2 3767evaluating to 3768.Va b ) . 3769.Pp 3770.It .macro m p1:req, p2=0, p3:vararg 3771Begin the definition of a macro called 3772.Li m , 3773with at least three arguments. The first argument must always have a value 3774specified, but not the second, which instead has a default value. The third 3775formal will get assigned all remaining arguments specified at invocation time. 3776.Pp 3777When you call a macro, you can specify the argument values either by position, 3778or by keyword. For example, 3779.Li sum 9,17 3780is equivalent to 3781.Li sum to=17, from=9 . 3782.Pp 3783.El 3784Note that since each of the 3785.Va macargs 3786can be an identifier exactly as any other one permitted by the target architecture, 3787there may be occasional problems if the target hand-crafts special meanings 3788to certain characters when they occur in a special position. For example, 3789if the colon ( 3790.Li : ) 3791is generally permitted to be part of a symbol name, but the architecture specific 3792code special-cases it when occurring as the final character of a symbol (to 3793denote a label), then the macro parameter replacement code will have no way 3794of knowing that and consider the whole construct (including the colon) an 3795identifier, and check only this identifier for being the subject to parameter 3796substitution. So for example this macro definition: 3797.Pp 3798.Bd -literal -offset indent 3799 .macro label l 3800\el: 3801 .endm 3802.Ed 3803.Pp 3804might not work as expected. Invoking 3805.Li label foo 3806might not create a label called 3807.Li foo 3808but instead just insert the text 3809.Li \el: 3810into the assembler source, probably generating an error about an unrecognised 3811identifier. 3812.Pp 3813Similarly problems might occur with the period character ( 3814.Li . ) 3815which is often allowed inside opcode names (and hence identifier names). So 3816for example constructing a macro to build an opcode from a base name and a 3817length specifier like this: 3818.Pp 3819.Bd -literal -offset indent 3820 .macro opcode base length 3821 \ebase.\elength 3822 .endm 3823.Ed 3824.Pp 3825and invoking it as 3826.Li opcode store l 3827will not create a 3828.Li store.l 3829instruction but instead generate some kind of error as the assembler tries 3830to interpret the text 3831.Li \ebase.\elength . 3832.Pp 3833There are several possible ways around this problem: 3834.Pp 3835.Bl -tag -width Ds 3836.It Insert white space 3837If it is possible to use white space characters then this is the simplest 3838solution. eg: 3839.Pp 3840.Bd -literal -offset indent 3841 .macro label l 3842\el : 3843 .endm 3844.Ed 3845.Pp 3846.It Use Li \e() 3847The string 3848.Li \e() 3849can be used to separate the end of a macro argument from the following text. 3850eg: 3851.Pp 3852.Bd -literal -offset indent 3853 .macro opcode base length 3854 \ebase\e().\elength 3855 .endm 3856.Ed 3857.Pp 3858.It Use the alternate macro syntax mode 3859In the alternative macro syntax mode the ampersand character ( 3860.Li & ) 3861can be used as a separator. eg: 3862.Pp 3863.Bd -literal -offset indent 3864 .altmacro 3865 .macro label l 3866l&: 3867 .endm 3868.Ed 3869.El 3870.Pp 3871Note: this problem of correctly identifying string parameters to pseudo ops 3872also applies to the identifiers used in 3873.Li .irp 3874(see Section 3875.Dq Irp ) 3876and 3877.Li .irpc 3878(see Section 3879.Dq Irpc ) 3880as well. 3881.Pp 3882.It .endm 3883Mark the end of a macro definition. 3884.Pp 3885.It .exitm 3886Exit early from the current macro definition. 3887.Pp 3888.It \e@ 3889.Xr as 3890maintains a counter of how many macros it has executed in this pseudo-variable; 3891you can copy that number to your output with 3892.Li \e@ , 3893but 3894.Em only within a macro definition . 3895.Pp 3896.It LOCAL Va name [ , ... ] 3897.Em Warning: Li LOCAL is only available if you select \(lqalternate macro syntax\(rq with Li --alternate or Li .altmacro. 3898See Section.Dq Altmacro . 3899.El 3900.Pp 3901.Ss Li .altmacro 3902Enable alternate macro mode, enabling: 3903.Pp 3904.Bl -tag -width Ds 3905.It LOCAL Va name [ , ... ] 3906One additional directive, 3907.Li LOCAL , 3908is available. It is used to generate a string replacement for each of the 3909.Va name 3910arguments, and replace any instances of 3911.Va name 3912in each macro expansion. The replacement string is unique in the assembly, 3913and different for each separate macro expansion. 3914.Li LOCAL 3915allows you to write macros that define symbols, without fear of conflict between 3916separate macro expansions. 3917.Pp 3918.It String delimiters 3919You can write strings delimited in these other ways besides 3920.Li " Va string" : 3921.Pp 3922.Bl -tag -width Ds 3923.It ' Va string' 3924You can delimit strings with single-quote characters. 3925.Pp 3926.It < Va string> 3927You can delimit strings with matching angle brackets. 3928.El 3929.Pp 3930.It single-character string escape 3931To include any single character literally in a string (even if the character 3932would otherwise have some special meaning), you can prefix the character with 3933.Li ! 3934(an exclamation mark). For example, you can write 3935.Li <4.3 !> 5.4!!> 3936to get the literal text 3937.Li 4.3 > 5.4! . 3938.Pp 3939.It Expression results as strings 3940You can write 3941.Li % Va expr 3942to evaluate the expression 3943.Va expr 3944and use the result as a string. 3945.El 3946.Pp 3947.Ss Li .noaltmacro 3948Disable alternate macro mode.See Section 3949.Dq Altmacro . 3950.Pp 3951.Ss Li .nolist 3952Control (in conjunction with the 3953.Li .list 3954directive) whether or not assembly listings are generated. These two directives 3955maintain an internal counter (which is zero initially). 3956.Li .list 3957increments the counter, and 3958.Li .nolist 3959decrements it. Assembly listings are generated whenever the counter is greater 3960than zero. 3961.Pp 3962.Ss Li .octa Va biGNUms 3963This directive expects zero or more biGNUms, separated by commas. For each 3964biGNUm, it emits a 16-byte integer. 3965.Pp 3966The term \(lqocta\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence 3967.Em octa 3968-word for 16 bytes. 3969.Pp 3970.Ss Li .org Va new-lc , Va fill 3971Advance the location counter of the current section to 3972.Va new-lc . 3973.Va new-lc 3974is either an absolute expression or an expression with the same section as 3975the current subsection. That is, you can't use 3976.Li .org 3977to cross sections: if 3978.Va new-lc 3979has the wrong section, the 3980.Li .org 3981directive is ignored. To be compatible with former assemblers, if the section 3982of 3983.Va new-lc 3984is absolute, 3985.Xr as 3986issues a warning, then pretends the section of 3987.Va new-lc 3988is the same as the current subsection. 3989.Pp 3990.Li .org 3991may only increase the location counter, or leave it unchanged; you cannot 3992use 3993.Li .org 3994to move the location counter backwards. 3995.Pp 3996Because 3997.Xr as 3998tries to assemble programs in one pass, 3999.Va new-lc 4000may not be undefined. If you really detest this restriction we eagerly await 4001a chance to share your improved assembler. 4002.Pp 4003Beware that the origin is relative to the start of the section, not to the 4004start of the subsection. This is compatible with other people's assemblers. 4005.Pp 4006When the location counter (of the current subsection) is advanced, the intervening 4007bytes are filled with 4008.Va fill 4009which should be an absolute expression. If the comma and 4010.Va fill 4011are omitted, 4012.Va fill 4013defaults to zero. 4014.Pp 4015.Ss Li .p2align[wl] Va abs-expr, Va abs-expr, Va abs-expr 4016Pad the location counter (in the current subsection) to a particular storage 4017boundary. The first expression (which must be absolute) is the number of low-order 4018zero bits the location counter must have after advancement. For example 4019.Li .p2align 3 4020advances the location counter until it a multiple of 8. If the location counter 4021is already a multiple of 8, no change is needed. 4022.Pp 4023The second expression (also absolute) gives the fill value to be stored in 4024the padding bytes. It (and the comma) may be omitted. If it is omitted, the 4025padding bytes are normally zero. However, on some systems, if the section 4026is marked as containing code and the fill value is omitted, the space is filled 4027with no-op instructions. 4028.Pp 4029The third expression is also absolute, and is also optional. If it is present, 4030it is the maximum number of bytes that should be skipped by this alignment 4031directive. If doing the alignment would require skipping more bytes than the 4032specified maximum, then the alignment is not done at all. You can omit the 4033fill value (the second argument) entirely by simply using two commas after 4034the required alignment; this can be useful if you want the alignment to be 4035filled with no-op instructions when appropriate. 4036.Pp 4037The 4038.Li .p2alignw 4039and 4040.Li .p2alignl 4041directives are variants of the 4042.Li .p2align 4043directive. The 4044.Li .p2alignw 4045directive treats the fill pattern as a two byte word value. The 4046.Li .p2alignl 4047directives treats the fill pattern as a four byte longword value. For example, 4048.Li .p2alignw 2,0x368d 4049will align to a multiple of 4. If it skips two bytes, they will be filled 4050in with the value 0x368d (the exact placement of the bytes depends upon the 4051endianness of the processor). If it skips 1 or 3 bytes, the fill value is 4052undefined. 4053.Pp 4054.Ss Li .previous 4055This is one of the ELF section stack manipulation directives. The others are 4056.Li .section 4057(see Section 4058.Dq Section ) , 4059.Li .subsection 4060(see Section 4061.Dq SubSection ) , 4062.Li .pushsection 4063(see Section 4064.Dq PushSection ) , 4065and 4066.Li .popsection 4067(see Section 4068.Dq PopSection ) . 4069.Pp 4070This directive swaps the current section (and subsection) with most recently 4071referenced section (and subsection) prior to this one. Multiple 4072.Li .previous 4073directives in a row will flip between two sections (and their subsections). 4074.Pp 4075In terms of the section stack, this directive swaps the current section with 4076the top section on the section stack. 4077.Pp 4078.Ss Li .popsection 4079This is one of the ELF section stack manipulation directives. The others are 4080.Li .section 4081(see Section 4082.Dq Section ) , 4083.Li .subsection 4084(see Section 4085.Dq SubSection ) , 4086.Li .pushsection 4087(see Section 4088.Dq PushSection ) , 4089and 4090.Li .previous 4091(see Section 4092.Dq Previous ) . 4093.Pp 4094This directive replaces the current section (and subsection) with the top 4095section (and subsection) on the section stack. This section is popped off 4096the stack. 4097.Pp 4098.Ss Li .print Va string 4099.Xr as 4100will print 4101.Va string 4102on the standard output during assembly. You must put 4103.Va string 4104in double quotes. 4105.Pp 4106.Ss Li .protected Va names 4107This is one of the ELF visibility directives. The other two are 4108.Li .hidden 4109(see Section 4110.Dq Hidden ) 4111and 4112.Li .internal 4113(see Section 4114.Dq Internal ) . 4115.Pp 4116This directive overrides the named symbols default visibility (which is set 4117by their binding: local, global or weak). The directive sets the visibility 4118to 4119.Li protected 4120which means that any references to the symbols from within the components 4121that defines them must be resolved to the definition in that component, even 4122if a definition in another component would normally preempt this. 4123.Pp 4124.Ss Li .psize Va lines , Va columns 4125Use this directive to declare the number of lines---and, optionally, the number 4126of columns---to use for each page, when generating listings. 4127.Pp 4128If you do not use 4129.Li .psize , 4130listings use a default line-count of 60. You may omit the comma and 4131.Va columns 4132specification; the default width is 200 columns. 4133.Pp 4134.Xr as 4135generates formfeeds whenever the specified number of lines is exceeded (or 4136whenever you explicitly request one, using 4137.Li .eject ) . 4138.Pp 4139If you specify 4140.Va lines 4141as 4142.Li 0 , 4143no formfeeds are generated save those explicitly specified with 4144.Li .eject . 4145.Pp 4146.Ss Li .purgem Va name 4147Undefine the macro 4148.Va name , 4149so that later uses of the string will not be expanded.See Section 4150.Dq Macro . 4151.Pp 4152.Ss Li .pushsection Va name , Va subsection 4153This is one of the ELF section stack manipulation directives. The others are 4154.Li .section 4155(see Section 4156.Dq Section ) , 4157.Li .subsection 4158(see Section 4159.Dq SubSection ) , 4160.Li .popsection 4161(see Section 4162.Dq PopSection ) , 4163and 4164.Li .previous 4165(see Section 4166.Dq Previous ) . 4167.Pp 4168This directive pushes the current section (and subsection) onto the top of 4169the section stack, and then replaces the current section and subsection with 4170.Li name 4171and 4172.Li subsection . 4173.Pp 4174.Ss Li .quad Va biGNUms 4175.Li .quad 4176expects zero or more biGNUms, separated by commas. For each bignum, it emits 4177an 8-byte integer. If the biGNUm won't fit in 8 bytes, it prints a warning 4178message; and just takes the lowest order 8 bytes of the biGNUm. 4179.Pp 4180The term \(lqquad\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence 4181.Em quad 4182-word for 8 bytes. 4183.Pp 4184.Ss Li .reloc Va offset, Va reloc_name[, Va expression] 4185Generate a relocation at 4186.Va offset 4187of type 4188.Va reloc_name 4189with value 4190.Va expression . 4191If 4192.Va offset 4193is a number, the relocation is generated in the current section. If 4194.Va offset 4195is an expression that resolves to a symbol plus offset, the relocation is 4196generated in the given symbol's section. 4197.Va expression , 4198if present, must resolve to a symbol plus addend or to an absolute value, 4199but note that not all targets support an addend. e.g. ELF REL targets such 4200as i386 store an addend in the section contents rather than in the relocation. 4201This low level interface does not support addends stored in the section. 4202.Pp 4203.Ss Li .rept Va count 4204Repeat the sequence of lines between the 4205.Li .rept 4206directive and the next 4207.Li .endr 4208directive 4209.Va count 4210times. 4211.Pp 4212For example, assembling 4213.Pp 4214.Bd -literal -offset indent 4215 .rept 3 4216 .long 0 4217 .endr 4218.Ed 4219.Pp 4220is equivalent to assembling 4221.Pp 4222.Bd -literal -offset indent 4223 .long 0 4224 .long 0 4225 .long 0 4226.Ed 4227.Pp 4228.Ss Li .sbttl " Va subheading" 4229Use 4230.Va subheading 4231as the title (third line, immediately after the title line) when generating 4232assembly listings. 4233.Pp 4234This directive affects subsequent pages, as well as the current page if it 4235appears within ten lines of the top of a page. 4236.Pp 4237.Ss Li .section Va name 4238Use the 4239.Li .section 4240directive to assemble the following code into a section named 4241.Va name . 4242.Pp 4243This directive is only supported for targets that actually support arbitrarily 4244named sections; on 4245.Li a.out 4246targets, for example, it is not accepted, even with a standard 4247.Li a.out 4248section name. 4249.Pp 4250This is one of the ELF section stack manipulation directives. The others are 4251.Li .subsection 4252(see Section 4253.Dq SubSection ) , 4254.Li .pushsection 4255(see Section 4256.Dq PushSection ) , 4257.Li .popsection 4258(see Section 4259.Dq PopSection ) , 4260and 4261.Li .previous 4262(see Section 4263.Dq Previous ) . 4264.Pp 4265For ELF targets, the 4266.Li .section 4267directive is used like this: 4268.Pp 4269.Bd -literal -offset indent 4270\&.section name [, "flags"[, @type[,flag_specific_arguments]]] 4271.Ed 4272.Pp 4273The optional 4274.Va flags 4275argument is a quoted string which may contain any combination of the following 4276characters: 4277.Bl -tag -width Ds 4278.It a 4279section is allocatable 4280.It w 4281section is writable 4282.It x 4283section is executable 4284.It M 4285section is mergeable 4286.It S 4287section contains zero terminated strings 4288.It G 4289section is a member of a section group 4290.It T 4291section is used for thread-local-storage 4292.El 4293.Pp 4294The optional 4295.Va type 4296argument may contain one of the following constants: 4297.Bl -tag -width Ds 4298.It @progbits 4299section contains data 4300.It @nobits 4301section does not contain data (i.e., section only occupies space) 4302.It @note 4303section contains data which is used by things other than the program 4304.It @init_array 4305section contains an array of pointers to init functions 4306.It @fini_array 4307section contains an array of pointers to finish functions 4308.It @preinit_array 4309section contains an array of pointers to pre-init functions 4310.El 4311.Pp 4312Many targets only support the first three section types. 4313.Pp 4314Note on targets where the 4315.Li @ 4316character is the start of a comment (eg ARM) then another character is used 4317instead. For example the ARM port uses the 4318.Li % 4319character. 4320.Pp 4321If 4322.Va flags 4323contains the 4324.Li M 4325symbol then the 4326.Va type 4327argument must be specified as well as an extra argument--- 4328.Va entsize 4329---like this: 4330.Pp 4331.Bd -literal -offset indent 4332\&.section name , "flags"M, @type, entsize 4333.Ed 4334.Pp 4335Sections with the 4336.Li M 4337flag but not 4338.Li S 4339flag must contain fixed size constants, each 4340.Va entsize 4341octets long. Sections with both 4342.Li M 4343and 4344.Li S 4345must contain zero terminated strings where each character is 4346.Va entsize 4347bytes long. The linker may remove duplicates within sections with the same 4348name, same entity size and same flags. 4349.Va entsize 4350must be an absolute expression. 4351.Pp 4352If 4353.Va flags 4354contains the 4355.Li G 4356symbol then the 4357.Va type 4358argument must be present along with an additional field like this: 4359.Pp 4360.Bd -literal -offset indent 4361\&.section name , "flags"G, @type, GroupName[, linkage] 4362.Ed 4363.Pp 4364The 4365.Va GroupName 4366field specifies the name of the section group to which this particular section 4367belongs. The optional linkage field can contain: 4368.Bl -tag -width Ds 4369.It comdat 4370indicates that only one copy of this section should be retained 4371.It .GNU.linkonce 4372an alias for comdat 4373.El 4374.Pp 4375Note: if both the 4376.Va M 4377and 4378.Va G 4379flags are present then the fields for the Merge flag should come first, like 4380this: 4381.Pp 4382.Bd -literal -offset indent 4383\&.section name , "flags"MG, @type, entsize, GroupName[, linkage] 4384.Ed 4385.Pp 4386If no flags are specified, the default flags depend upon the section name. 4387If the section name is not recognized, the default will be for the section 4388to have none of the above flags: it will not be allocated in memory, nor writable, 4389nor executable. The section will contain data. 4390.Pp 4391For ELF targets, the assembler supports another type of 4392.Li .section 4393directive for compatibility with the Solaris assembler: 4394.Pp 4395.Bd -literal -offset indent 4396\&.section "name"[, flags...] 4397.Ed 4398.Pp 4399Note that the section name is quoted. There may be a sequence of comma separated 4400flags: 4401.Bl -tag -width Ds 4402.It #alloc 4403section is allocatable 4404.It #write 4405section is writable 4406.It #execinstr 4407section is executable 4408.It #tls 4409section is used for thread local storage 4410.El 4411.Pp 4412This directive replaces the current section and subsection. See the contents 4413of the gas testsuite directory 4414.Li gas/testsuite/gas/elf 4415for some examples of how this directive and the other section stack directives 4416work. 4417.Pp 4418.Ss Li .set Va symbol, Va expression 4419Set the value of 4420.Va symbol 4421to 4422.Va expression . 4423This changes 4424.Va symbol 4425\&'s value and type to conform to 4426.Va expression . 4427If 4428.Va symbol 4429was flagged as external, it remains flagged (see Section 4430.Dq Symbol Attributes ) . 4431.Pp 4432You may 4433.Li .set 4434a symbol many times in the same assembly. 4435.Pp 4436If you 4437.Li .set 4438a global symbol, the value stored in the object file is the last value stored 4439into it. 4440.Pp 4441.Ss Li .short Va expressions 4442This expects zero or more 4443.Va expressions , 4444and emits a 16 bit number for each. 4445.Pp 4446.Ss Li .single Va flonums 4447This directive assembles zero or more flonums, separated by commas. It has 4448the same effect as 4449.Li .float . 4450.Pp 4451.Ss Li .size 4452This directive is used to set the size associated with a symbol. 4453.Pp 4454For ELF targets, the 4455.Li .size 4456directive is used like this: 4457.Pp 4458.Bd -literal -offset indent 4459\&.size name , expression 4460.Ed 4461.Pp 4462This directive sets the size associated with a symbol 4463.Va name . 4464The size in bytes is computed from 4465.Va expression 4466which can make use of label arithmetic. This directive is typically used to 4467set the size of function symbols. 4468.Pp 4469.Ss Li .sleb128 Va expressions 4470.Va sleb128 4471stands for \(lqsigned little endian base 128.\(rq This is a compact, variable length 4472representation of numbers used by the DWARF symbolic debugging format.See Section 4473.Dq Uleb128 . 4474.Pp 4475.Ss Li .skip Va size , Va fill 4476This directive emits 4477.Va size 4478bytes, each of value 4479.Va fill . 4480Both 4481.Va size 4482and 4483.Va fill 4484are absolute expressions. If the comma and 4485.Va fill 4486are omitted, 4487.Va fill 4488is assumed to be zero. This is the same as 4489.Li .space . 4490.Pp 4491.Ss Li .space Va size , Va fill 4492This directive emits 4493.Va size 4494bytes, each of value 4495.Va fill . 4496Both 4497.Va size 4498and 4499.Va fill 4500are absolute expressions. If the comma and 4501.Va fill 4502are omitted, 4503.Va fill 4504is assumed to be zero. This is the same as 4505.Li .skip . 4506.Pp 4507.Ss Li .stabd, .stabn, .stabs 4508There are three directives that begin 4509.Li .stab . 4510All emit symbols (see Section 4511.Dq Symbols ) , 4512for use by symbolic debuggers. The symbols are not entered in the 4513.Xr as 4514hash table: they cannot be referenced elsewhere in the source file. Up to 4515five fields are required: 4516.Pp 4517.Bl -tag -width Ds 4518.It string 4519This is the symbol's name. It may contain any character except 4520.Li \e000 , 4521so is more general than ordinary symbol names. Some debuggers used to code 4522arbitrarily complex structures into symbol names using this field. 4523.Pp 4524.It type 4525An absolute expression. The symbol's type is set to the low 8 bits of this 4526expression. Any bit pattern is permitted, but 4527.Li ld 4528and debuggers choke on silly bit patterns. 4529.Pp 4530.It other 4531An absolute expression. The symbol's \(lqother\(rq attribute is set to the low 8 bits 4532of this expression. 4533.Pp 4534.It desc 4535An absolute expression. The symbol's descriptor is set to the low 16 bits 4536of this expression. 4537.Pp 4538.It value 4539An absolute expression which becomes the symbol's value. 4540.El 4541.Pp 4542If a warning is detected while reading a 4543.Li .stabd , 4544.Li .stabn , 4545or 4546.Li .stabs 4547statement, the symbol has probably already been created; you get a half-formed 4548symbol in your object file. This is compatible with earlier assemblers! 4549.Pp 4550.Bl -tag -width Ds 4551.It .stabd Va type , Va other , Va desc 4552.Pp 4553The \(lqname\(rq of the symbol generated is not even an empty string. It is a null 4554pointer, for compatibility. Older assemblers used a null pointer so they didn't 4555waste space in object files with empty strings. 4556.Pp 4557The symbol's value is set to the location counter, relocatably. When your 4558program is linked, the value of this symbol is the address of the location 4559counter when the 4560.Li .stabd 4561was assembled. 4562.Pp 4563.It .stabn Va type , Va other , Va desc , Va value 4564The name of the symbol is set to the empty string 4565.Li "" . 4566.Pp 4567.It .stabs Va string , Va type , Va other , Va desc , Va value 4568All five fields are specified. 4569.El 4570.Pp 4571.Ss Li .string " Va str" 4572Copy the characters in 4573.Va str 4574to the object file. You may specify more than one string to copy, separated 4575by commas. Unless otherwise specified for a particular machine, the assembler 4576marks the end of each string with a 0 byte. You can use any of the escape 4577sequences described in Strings,,Strings. 4578.Pp 4579.Ss Li .struct Va expression 4580Switch to the absolute section, and set the section offset to 4581.Va expression , 4582which must be an absolute expression. You might use this as follows: 4583.Bd -literal -offset indent 4584 .struct 0 4585field1: 4586 .struct field1 + 4 4587field2: 4588 .struct field2 + 4 4589field3: 4590.Ed 4591This would define the symbol 4592.Li field1 4593to have the value 0, the symbol 4594.Li field2 4595to have the value 4, and the symbol 4596.Li field3 4597to have the value 8. Assembly would be left in the absolute section, and you 4598would need to use a 4599.Li .section 4600directive of some sort to change to some other section before further assembly. 4601.Pp 4602.Ss Li .subsection Va name 4603This is one of the ELF section stack manipulation directives. The others are 4604.Li .section 4605(see Section 4606.Dq Section ) , 4607.Li .pushsection 4608(see Section 4609.Dq PushSection ) , 4610.Li .popsection 4611(see Section 4612.Dq PopSection ) , 4613and 4614.Li .previous 4615(see Section 4616.Dq Previous ) . 4617.Pp 4618This directive replaces the current subsection with 4619.Li name . 4620The current section is not changed. The replaced subsection is put onto the 4621section stack in place of the then current top of stack subsection. 4622.Pp 4623.Ss Li .symver 4624Use the 4625.Li .symver 4626directive to bind symbols to specific version nodes within a source file. 4627This is only supported on ELF platforms, and is typically used when assembling 4628files to be linked into a shared library. There are cases where it may make 4629sense to use this in objects to be bound into an application itself so as 4630to override a versioned symbol from a shared library. 4631.Pp 4632For ELF targets, the 4633.Li .symver 4634directive can be used like this: 4635.Bd -literal -offset indent 4636\&.symver name, name2@nodename 4637.Ed 4638If the symbol 4639.Va name 4640is defined within the file being assembled, the 4641.Li .symver 4642directive effectively creates a symbol alias with the name 4643.Va name2@nodename , 4644and in fact the main reason that we just don't try and create a regular alias 4645is that the 4646.Va @ 4647character isn't permitted in symbol names. The 4648.Va name2 4649part of the name is the actual name of the symbol by which it will be externally 4650referenced. The name 4651.Va name 4652itself is merely a name of convenience that is used so that it is possible 4653to have definitions for multiple versions of a function within a single source 4654file, and so that the compiler can unambiguously know which version of a function 4655is being mentioned. The 4656.Va nodename 4657portion of the alias should be the name of a node specified in the version 4658script supplied to the linker when building a shared library. If you are attempting 4659to override a versioned symbol from a shared library, then 4660.Va nodename 4661should correspond to the nodename of the symbol you are trying to override. 4662.Pp 4663If the symbol 4664.Va name 4665is not defined within the file being assembled, all references to 4666.Va name 4667will be changed to 4668.Va name2@nodename . 4669If no reference to 4670.Va name 4671is made, 4672.Va name2@nodename 4673will be removed from the symbol table. 4674.Pp 4675Another usage of the 4676.Li .symver 4677directive is: 4678.Bd -literal -offset indent 4679\&.symver name, name2@@nodename 4680.Ed 4681In this case, the symbol 4682.Va name 4683must exist and be defined within the file being assembled. It is similar to 4684.Va name2@nodename . 4685The difference is 4686.Va name2@@nodename 4687will also be used to resolve references to 4688.Va name2 4689by the linker. 4690.Pp 4691The third usage of the 4692.Li .symver 4693directive is: 4694.Bd -literal -offset indent 4695\&.symver name, name2@@@nodename 4696.Ed 4697When 4698.Va name 4699is not defined within the file being assembled, it is treated as 4700.Va name2@nodename . 4701When 4702.Va name 4703is defined within the file being assembled, the symbol name, 4704.Va name , 4705will be changed to 4706.Va name2@@nodename . 4707.Pp 4708.Ss Li .text Va subsection 4709Tells 4710.Xr as 4711to assemble the following statements onto the end of the text subsection numbered 4712.Va subsection , 4713which is an absolute expression. If 4714.Va subsection 4715is omitted, subsection number zero is used. 4716.Pp 4717.Ss Li .title " Va heading" 4718Use 4719.Va heading 4720as the title (second line, immediately after the source file name and pagenumber) 4721when generating assembly listings. 4722.Pp 4723This directive affects subsequent pages, as well as the current page if it 4724appears within ten lines of the top of a page. 4725.Pp 4726.Ss Li .type 4727This directive is used to set the type of a symbol. 4728.Pp 4729For ELF targets, the 4730.Li .type 4731directive is used like this: 4732.Pp 4733.Bd -literal -offset indent 4734\&.type name , type description 4735.Ed 4736.Pp 4737This sets the type of symbol 4738.Va name 4739to be either a function symbol or an object symbol. There are five different 4740syntaxes supported for the 4741.Va type description 4742field, in order to provide compatibility with various other assemblers. 4743.Pp 4744Because some of the characters used in these syntaxes (such as 4745.Li @ 4746and 4747.Li # ) 4748are comment characters for some architectures, some of the syntaxes below 4749do not work on all architectures. The first variant will be accepted by the 4750GNU assembler on all architectures so that variant should be used for maximum 4751portability, if you do not need to assemble your code with other assemblers. 4752.Pp 4753The syntaxes supported are: 4754.Pp 4755.Bd -literal -offset indent 4756 .type <name> STT_FUNCTION 4757 .type <name> STT_OBJECT 4758 4759 .type <name>,#function 4760 .type <name>,#object 4761 4762 .type <name>,@function 4763 .type <name>,@object 4764 4765 .type <name>,%function 4766 .type <name>,%object 4767 4768 .type <name>,"function" 4769 .type <name>,"object" 4770.Ed 4771.Pp 4772.Ss Li .uleb128 Va expressions 4773.Va uleb128 4774stands for \(lqunsigned little endian base 128.\(rq This is a compact, variable length 4775representation of numbers used by the DWARF symbolic debugging format.See Section 4776.Dq Sleb128 . 4777.Pp 4778.Ss Li .version " Va string" 4779This directive creates a 4780.Li .note 4781section and places into it an ELF formatted note of type NT_VERSION. The note's 4782name is set to 4783.Li string . 4784.Pp 4785.Ss Li .vtable_entry Va table, Va offset 4786This directive finds or creates a symbol 4787.Li table 4788and creates a 4789.Li VTABLE_ENTRY 4790relocation for it with an addend of 4791.Li offset . 4792.Pp 4793.Ss Li .vtable_inherit Va child, Va parent 4794This directive finds the symbol 4795.Li child 4796and finds or creates the symbol 4797.Li parent 4798and then creates a 4799.Li VTABLE_INHERIT 4800relocation for the parent whose addend is the value of the child symbol. As 4801a special case the parent name of 4802.Li 0 4803is treated as referring to the 4804.Li *ABS* 4805section. 4806.Pp 4807.Ss Li .warning " Va string" 4808Similar to the directive 4809.Li .error 4810(see Section 4811.Dq Error ) , 4812but just emits a warning. 4813.Pp 4814.Ss Li .weak Va names 4815This directive sets the weak attribute on the comma separated list of symbol 4816.Li names . 4817If the symbols do not already exist, they will be created. 4818.Pp 4819On COFF targets other than PE, weak symbols are a GNU extension. This directive 4820sets the weak attribute on the comma separated list of symbol 4821.Li names . 4822If the symbols do not already exist, they will be created. 4823.Pp 4824On the PE target, weak symbols are supported natively as weak aliases. When 4825a weak symbol is created that is not an alias, GAS creates an alternate symbol 4826to hold the default value. 4827.Pp 4828.Ss Li .weakref Va alias, Va target 4829This directive creates an alias to the target symbol that enables the symbol 4830to be referenced with weak-symbol semantics, but without actually making it 4831weak. If direct references or definitions of the symbol are present, then 4832the symbol will not be weak, but if all references to it are through weak 4833references, the symbol will be marked as weak in the symbol table. 4834.Pp 4835The effect is equivalent to moving all references to the alias to a separate 4836assembly source file, renaming the alias to the symbol in it, declaring the 4837symbol as weak there, and running a reloadable link to merge the object files 4838resulting from the assembly of the new source file and the old source file 4839that had the references to the alias removed. 4840.Pp 4841The alias itself never makes to the symbol table, and is entirely handled 4842within the assembler. 4843.Pp 4844.Ss Li .word Va expressions 4845This directive expects zero or more 4846.Va expressions , 4847of any section, separated by commas. For each expression, 4848.Xr as 4849emits a 32-bit number. 4850.Pp 4851.Ss Deprecated Directives 4852One day these directives won't work. They are included for compatibility with 4853older assemblers. 4854.Bl -tag -width Ds 4855.It .abort 4856.It .line 4857.El 4858.Pp 4859.Sh ARM Dependent Features 4860.Ss Options 4861.Bl -tag -width Ds 4862.It -mcpu= Va processor[+ Va extension...] 4863This option specifies the target processor. The assembler will issue an error 4864message if an attempt is made to assemble an instruction which will not execute 4865on the target processor. The following processor names are recognized: 4866.Li arm1 , 4867.Li arm2 , 4868.Li arm250 , 4869.Li arm3 , 4870.Li arm6 , 4871.Li arm60 , 4872.Li arm600 , 4873.Li arm610 , 4874.Li arm620 , 4875.Li arm7 , 4876.Li arm7m , 4877.Li arm7d , 4878.Li arm7dm , 4879.Li arm7di , 4880.Li arm7dmi , 4881.Li arm70 , 4882.Li arm700 , 4883.Li arm700i , 4884.Li arm710 , 4885.Li arm710t , 4886.Li arm720 , 4887.Li arm720t , 4888.Li arm740t , 4889.Li arm710c , 4890.Li arm7100 , 4891.Li arm7500 , 4892.Li arm7500fe , 4893.Li arm7t , 4894.Li arm7tdmi , 4895.Li arm7tdmi-s , 4896.Li arm8 , 4897.Li arm810 , 4898.Li strongarm , 4899.Li strongarm1 , 4900.Li strongarm110 , 4901.Li strongarm1100 , 4902.Li strongarm1110 , 4903.Li arm9 , 4904.Li arm920 , 4905.Li arm920t , 4906.Li arm922t , 4907.Li arm940t , 4908.Li arm9tdmi , 4909.Li arm9e , 4910.Li arm926e , 4911.Li arm926ej-s , 4912.Li arm946e-r0 , 4913.Li arm946e , 4914.Li arm946e-s , 4915.Li arm966e-r0 , 4916.Li arm966e , 4917.Li arm966e-s , 4918.Li arm968e-s , 4919.Li arm10t , 4920.Li arm10tdmi , 4921.Li arm10e , 4922.Li arm1020 , 4923.Li arm1020t , 4924.Li arm1020e , 4925.Li arm1022e , 4926.Li arm1026ej-s , 4927.Li arm1136j-s , 4928.Li arm1136jf-s , 4929.Li arm1156t2-s , 4930.Li arm1156t2f-s , 4931.Li arm1176jz-s , 4932.Li arm1176jzf-s , 4933.Li mpcore , 4934.Li mpcorenovfp , 4935.Li cortex-a8 , 4936.Li cortex-r4 , 4937.Li cortex-m3 , 4938.Li ep9312 4939(ARM920 with Cirrus Maverick coprocessor), 4940.Li i80200 4941(Intel XScale processor) 4942.Li iwmmxt 4943(Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) and 4944.Li xscale . 4945The special name 4946.Li all 4947may be used to allow the assembler to accept instructions valid for any ARM 4948processor. 4949.Pp 4950In addition to the basic instruction set, the assembler can be told to accept 4951various extension mnemonics that extend the processor using the co-processor 4952instruction space. For example, 4953.Li -mcpu=arm920+maverick 4954is equivalent to specifying 4955.Li -mcpu=ep9312 . 4956The following extensions are currently supported: 4957.Li +maverick 4958.Li +iwmmxt 4959and 4960.Li +xscale . 4961.Pp 4962.It -march= Va architecture[+ Va extension...] 4963This option specifies the target architecture. The assembler will issue an 4964error message if an attempt is made to assemble an instruction which will 4965not execute on the target architecture. The following architecture names are 4966recognized: 4967.Li armv1 , 4968.Li armv2 , 4969.Li armv2a , 4970.Li armv2s , 4971.Li armv3 , 4972.Li armv3m , 4973.Li armv4 , 4974.Li armv4xm , 4975.Li armv4t , 4976.Li armv4txm , 4977.Li armv5 , 4978.Li armv5t , 4979.Li armv5txm , 4980.Li armv5te , 4981.Li armv5texp , 4982.Li armv6 , 4983.Li armv6j , 4984.Li armv6k , 4985.Li armv6z , 4986.Li armv6zk , 4987.Li armv7 , 4988.Li armv7-a , 4989.Li armv7-r , 4990.Li armv7-m , 4991.Li iwmmxt 4992and 4993.Li xscale . 4994If both 4995.Li -mcpu 4996and 4997.Li -march 4998are specified, the assembler will use the setting for 4999.Li -mcpu . 5000.Pp 5001The architecture option can be extended with the same instruction set extension 5002options as the 5003.Li -mcpu 5004option. 5005.Pp 5006.It -mfpu= Va floating-point-format 5007.Pp 5008This option specifies the floating point format to assemble for. The assembler 5009will issue an error message if an attempt is made to assemble an instruction 5010which will not execute on the target floating point unit. The following format 5011options are recognized: 5012.Li softfpa , 5013.Li fpe , 5014.Li fpe2 , 5015.Li fpe3 , 5016.Li fpa , 5017.Li fpa10 , 5018.Li fpa11 , 5019.Li arm7500fe , 5020.Li softvfp , 5021.Li softvfp+vfp , 5022.Li vfp , 5023.Li vfp10 , 5024.Li vfp10-r0 , 5025.Li vfp9 , 5026.Li vfpxd , 5027.Li arm1020t , 5028.Li arm1020e , 5029.Li arm1136jf-s 5030and 5031.Li maverick . 5032.Pp 5033In addition to determining which instructions are assembled, this option also 5034affects the way in which the 5035.Li .double 5036assembler directive behaves when assembling little-endian code. 5037.Pp 5038The default is dependent on the processor selected. For Architecture 5 or 5039later, the default is to assembler for VFP instructions; for earlier architectures 5040the default is to assemble for FPA instructions. 5041.Pp 5042.It -mthumb 5043This option specifies that the assembler should start assembling Thumb instructions; 5044that is, it should behave as though the file starts with a 5045.Li .code 16 5046directive. 5047.Pp 5048.It -mthumb-interwork 5049This option specifies that the output generated by the assembler should be 5050marked as supporting interworking. 5051.Pp 5052.It -mapcs Li [26|32] 5053This option specifies that the output generated by the assembler should be 5054marked as supporting the indicated version of the Arm Procedure. Calling Standard. 5055.Pp 5056.It -matpcs 5057This option specifies that the output generated by the assembler should be 5058marked as supporting the Arm/Thumb Procedure Calling Standard. If enabled 5059this option will cause the assembler to create an empty debugging section 5060in the object file called .arm.atpcs. Debuggers can use this to determine 5061the ABI being used by. 5062.Pp 5063.It -mapcs-float 5064This indicates the floating point variant of the APCS should be used. In this 5065variant floating point arguments are passed in FP registers rather than integer 5066registers. 5067.Pp 5068.It -mapcs-reentrant 5069This indicates that the reentrant variant of the APCS should be used. This 5070variant supports position independent code. 5071.Pp 5072.It -mfloat-abi= Va abi 5073This option specifies that the output generated by the assembler should be 5074marked as using specified floating point ABI. The following values are recognized: 5075.Li soft , 5076.Li softfp 5077and 5078.Li hard . 5079.Pp 5080.It -meabi= Va ver 5081This option specifies which EABI version the produced object files should 5082conform to. The following values are recognized: 5083.Li GNU , 5084.Li 4 5085and 5086.Li 5 . 5087.Pp 5088.It -EB 5089This option specifies that the output generated by the assembler should be 5090marked as being encoded for a big-endian processor. 5091.Pp 5092.It -EL 5093This option specifies that the output generated by the assembler should be 5094marked as being encoded for a little-endian processor. 5095.Pp 5096.It -k 5097This option specifies that the output of the assembler should be marked as 5098position-independent code (PIC). 5099.Pp 5100.El 5101.Ss Syntax 5102.Em Special Characters 5103.Pp 5104The presence of a 5105.Li @ 5106on a line indicates the start of a comment that extends to the end of the 5107current line. If a 5108.Li # 5109appears as the first character of a line, the whole line is treated as a comment. 5110.Pp 5111The 5112.Li ; 5113character can be used instead of a newline to separate statements. 5114.Pp 5115Either 5116.Li # 5117or 5118.Li $ 5119can be used to indicate immediate operands. 5120.Pp 5121*TODO* Explain about /data modifier on symbols. 5122.Pp 5123.Em Register Names 5124.Pp 5125*TODO* Explain about ARM register naming, and the predefined names. 5126.Pp 5127.Em ARM relocation generation 5128.Pp 5129Specific data relocations can be generated by putting the relocation name 5130in parentheses after the symbol name. For example: 5131.Pp 5132.Bd -literal -offset indent 5133 .word foo(TARGET1) 5134.Ed 5135.Pp 5136This will generate an 5137.Li R_ARM_TARGET1 5138relocation against the symbol 5139.Va foo . 5140The following relocations are supported: 5141.Li GOT , 5142.Li GOTOFF , 5143.Li TARGET1 , 5144.Li TARGET2 , 5145.Li SBREL , 5146.Li TLSGD , 5147.Li TLSLDM , 5148.Li TLSLDO , 5149.Li GOTTPOFF 5150and 5151.Li TPOFF . 5152.Pp 5153For compatibility with older toolchains the assembler also accepts 5154.Li (PLT) 5155after branch targets. This will generate the deprecated 5156.Li R_ARM_PLT32 5157relocation. 5158.Pp 5159Relocations for 5160.Li MOVW 5161and 5162.Li MOVT 5163instructions can be generated by prefixing the value with 5164.Li #:lower16: 5165and 5166.Li #:upper16 5167respectively. For example to load the 32-bit address of foo into r0: 5168.Pp 5169.Bd -literal -offset indent 5170 MOVW r0, #:lower16:foo 5171 MOVT r0, #:upper16:foo 5172.Ed 5173.Pp 5174.Ss Floating Point 5175The ARM family uses ieee floating-point numbers. 5176.Pp 5177.Ss ARM Machine Directives 5178.Bl -tag -width Ds 5179.It .align Va expression [, Va expression] 5180This is the generic 5181.Va .align 5182directive. For the ARM however if the first argument is zero (ie no alignment 5183is needed) the assembler will behave as if the argument had been 2 (ie pad 5184to the next four byte boundary). This is for compatibility with ARM's own 5185assembler. 5186.Pp 5187.It Va name .req Va register name 5188This creates an alias for 5189.Va register name 5190called 5191.Va name . 5192For example: 5193.Pp 5194.Bd -literal -offset indent 5195 foo .req r0 5196.Ed 5197.Pp 5198.It .unreq Va alias-name 5199This undefines a register alias which was previously defined using the 5200.Li req , 5201.Li dn 5202or 5203.Li qn 5204directives. For example: 5205.Pp 5206.Bd -literal -offset indent 5207 foo .req r0 5208 .unreq foo 5209.Ed 5210.Pp 5211An error occurs if the name is undefined. Note - this pseudo op can be used 5212to delete builtin in register name aliases (eg 'r0'). This should only be 5213done if it is really necessary. 5214.Pp 5215.It Va name .dn Va register name [ Va .type] [ Va [index]] 5216.It Va name .qn Va register name [ Va .type] [ Va [index]] 5217.Pp 5218The 5219.Li dn 5220and 5221.Li qn 5222directives are used to create typed and/or indexed register aliases for use 5223in Advanced SIMD Extension (Neon) instructions. The former should be used 5224to create aliases of double-precision registers, and the latter to create 5225aliases of quad-precision registers. 5226.Pp 5227If these directives are used to create typed aliases, those aliases can be 5228used in Neon instructions instead of writing types after the mnemonic or after 5229each operand. For example: 5230.Pp 5231.Bd -literal -offset indent 5232 x .dn d2.f32 5233 y .dn d3.f32 5234 z .dn d4.f32[1] 5235 vmul x,y,z 5236.Ed 5237.Pp 5238This is equivalent to writing the following: 5239.Pp 5240.Bd -literal -offset indent 5241 vmul.f32 d2,d3,d4[1] 5242.Ed 5243.Pp 5244Aliases created using 5245.Li dn 5246or 5247.Li qn 5248can be destroyed using 5249.Li unreq . 5250.Pp 5251.It .code Li [16|32] 5252This directive selects the instruction set being generated. The value 16 selects 5253Thumb, with the value 32 selecting ARM. 5254.Pp 5255.It .thumb 5256This performs the same action as 5257.Va .code 16 . 5258.Pp 5259.It .arm 5260This performs the same action as 5261.Va .code 32 . 5262.Pp 5263.It .force_thumb 5264This directive forces the selection of Thumb instructions, even if the target 5265processor does not support those instructions 5266.Pp 5267.It .thumb_func 5268This directive specifies that the following symbol is the name of a Thumb 5269encoded function. This information is necessary in order to allow the assembler 5270and linker to generate correct code for interworking between Arm and Thumb 5271instructions and should be used even if interworking is not going to be performed. 5272The presence of this directive also implies 5273.Li .thumb 5274.Pp 5275This directive is not neccessary when generating EABI objects. On these targets 5276the encoding is implicit when generating Thumb code. 5277.Pp 5278.It .thumb_set 5279This performs the equivalent of a 5280.Li .set 5281directive in that it creates a symbol which is an alias for another symbol 5282(possibly not yet defined). This directive also has the added property in 5283that it marks the aliased symbol as being a thumb function entry point, in 5284the same way that the 5285.Li .thumb_func 5286directive does. 5287.Pp 5288.It .ltorg 5289This directive causes the current contents of the literal pool to be dumped 5290into the current section (which is assumed to be the .text section) at the 5291current location (aligned to a word boundary). 5292.Li GAS 5293maintains a separate literal pool for each section and each sub-section. The 5294.Li .ltorg 5295directive will only affect the literal pool of the current section and sub-section. 5296At the end of assembly all remaining, un-empty literal pools will automatically 5297be dumped. 5298.Pp 5299Note - older versions of 5300.Li GAS 5301would dump the current literal pool any time a section change occurred. This 5302is no longer done, since it prevents accurate control of the placement of 5303literal pools. 5304.Pp 5305.It .pool 5306This is a synonym for .ltorg. 5307.Pp 5308.It .unwind_fnstart 5309Marks the start of a function with an unwind table entry. 5310.Pp 5311.It .unwind_fnend 5312Marks the end of a function with an unwind table entry. The unwind index table 5313entry is created when this directive is processed. 5314.Pp 5315If no personality routine has been specified then standard personality routine 53160 or 1 will be used, depending on the number of unwind opcodes required. 5317.Pp 5318.It .cantunwind 5319Prevents unwinding through the current function. No personality routine or 5320exception table data is required or permitted. 5321.Pp 5322.It .personality Va name 5323Sets the personality routine for the current function to 5324.Va name . 5325.Pp 5326.It .personalityindex Va index 5327Sets the personality routine for the current function to the EABI standard 5328routine number 5329.Va index 5330.Pp 5331.It .handlerdata 5332Marks the end of the current function, and the start of the exception table 5333entry for that function. Anything between this directive and the 5334.Li .fnend 5335directive will be added to the exception table entry. 5336.Pp 5337Must be preceded by a 5338.Li .personality 5339or 5340.Li .personalityindex 5341directive. 5342.Pp 5343.It .save Va reglist 5344Generate unwinder annotations to restore the registers in 5345.Va reglist . 5346The format of 5347.Va reglist 5348is the same as the corresponding store-multiple instruction. 5349.Pp 5350.Bd -literal -offset indent 5351 .save {r4, r5, r6, lr} 5352 stmfd sp!, {r4, r5, r6, lr} 5353 .save f4, 2 5354 sfmfd f4, 2, [sp]! 5355 .save {d8, d9, d10} 5356 fstmdx sp!, {d8, d9, d10} 5357 .save {wr10, wr11} 5358 wstrd wr11, [sp, #-8]! 5359 wstrd wr10, [sp, #-8]! 5360or 5361 .save wr11 5362 wstrd wr11, [sp, #-8]! 5363 .save wr10 5364 wstrd wr10, [sp, #-8]! 5365.Ed 5366.Pp 5367.It .vsave Va vfp-reglist 5368Generate unwinder annotations to restore the VFP registers in 5369.Va vfp-reglist 5370using FLDMD. Also works for VFPv3 registers that are to be restored using 5371VLDM. The format of 5372.Va vfp-reglist 5373is the same as the corresponding store-multiple instruction. 5374.Pp 5375.Bd -literal -offset indent 5376 .vsave {d8, d9, d10} 5377 fstmdd sp!, {d8, d9, d10} 5378 .vsave {d15, d16, d17} 5379 vstm sp!, {d15, d16, d17} 5380.Ed 5381.Pp 5382Since FLDMX and FSTMX are now deprecated, this directive should be used in 5383favour of 5384.Li .save 5385for saving VFP registers for ARMv6 and above. 5386.Pp 5387.It .pad # Va count 5388Generate unwinder annotations for a stack adjustment of 5389.Va count 5390bytes. A positive value indicates the function prologue allocated stack space 5391by decrementing the stack pointer. 5392.Pp 5393.It .movsp Va reg [, # Va offset] 5394Tell the unwinder that 5395.Va reg 5396contains an offset from the current stack pointer. If 5397.Va offset 5398is not specified then it is assumed to be zero. 5399.Pp 5400.It .setfp Va fpreg, Va spreg [, # Va offset] 5401Make all unwinder annotations relaive to a frame pointer. Without this the 5402unwinder will use offsets from the stack pointer. 5403.Pp 5404The syntax of this directive is the same as the 5405.Li sub 5406or 5407.Li mov 5408instruction used to set the frame pointer. 5409.Va spreg 5410must be either 5411.Li sp 5412or mentioned in a previous 5413.Li .movsp 5414directive. 5415.Pp 5416.Bd -literal -offset indent 5417\&.movsp ip 5418mov ip, sp 5419\&... 5420\&.setfp fp, ip, #4 5421sub fp, ip, #4 5422.Ed 5423.Pp 5424.It .raw Va offset, Va byte1, ... 5425Insert one of more arbitary unwind opcode bytes, which are known to adjust 5426the stack pointer by 5427.Va offset 5428bytes. 5429.Pp 5430For example 5431.Li .unwind_raw 4, 0xb1, 0x01 5432is equivalent to 5433.Li .save {r0} 5434.Pp 5435.It .cpu Va name 5436Select the target processor. Valid values for 5437.Va name 5438are the same as for the 5439.Op -mcpu 5440commandline option. 5441.Pp 5442.It .arch Va name 5443Select the target architecture. Valid values for 5444.Va name 5445are the same as for the 5446.Op -march 5447commandline option. 5448.Pp 5449.It .object_arch Va name 5450Override the architecture recorded in the EABI object attribute section. Valid 5451values for 5452.Va name 5453are the same as for the 5454.Li .arch 5455directive. Typically this is useful when code uses runtime detection of CPU 5456features. 5457.Pp 5458.It .fpu Va name 5459Select the floating point unit to assemble for. Valid values for 5460.Va name 5461are the same as for the 5462.Op -mfpu 5463commandline option. 5464.Pp 5465.It .eabi_attribute Va tag, Va value 5466Set the EABI object attribute number 5467.Va tag 5468to 5469.Va value . 5470The value is either a 5471.Li number , 5472.Li "string" , 5473or 5474.Li number, "string" 5475depending on the tag. 5476.Pp 5477.El 5478.Ss Opcodes 5479.Li as 5480implements all the standard ARM opcodes. It also implements several pseudo 5481opcodes, including several synthetic load instructions. 5482.Pp 5483.Bl -tag -width Ds 5484.It NOP 5485.Bd -literal -offset indent 5486 nop 5487.Ed 5488.Pp 5489This pseudo op will always evaluate to a legal ARM instruction that does nothing. 5490Currently it will evaluate to MOV r0, r0. 5491.Pp 5492.It LDR 5493.Bd -literal -offset indent 5494 ldr <register> , = <expression> 5495.Ed 5496.Pp 5497If expression evaluates to a numeric constant then a MOV or MVN instruction 5498will be used in place of the LDR instruction, if the constant can be generated 5499by either of these instructions. Otherwise the constant will be placed into 5500the nearest literal pool (if it not already there) and a PC relative LDR instruction 5501will be generated. 5502.Pp 5503.It ADR 5504.Bd -literal -offset indent 5505 adr <register> <label> 5506.Ed 5507.Pp 5508This instruction will load the address of 5509.Va label 5510into the indicated register. The instruction will evaluate to a PC relative 5511ADD or SUB instruction depending upon where the label is located. If the label 5512is out of range, or if it is not defined in the same file (and section) as 5513the ADR instruction, then an error will be generated. This instruction will 5514not make use of the literal pool. 5515.Pp 5516.It ADRL 5517.Bd -literal -offset indent 5518 adrl <register> <label> 5519.Ed 5520.Pp 5521This instruction will load the address of 5522.Va label 5523into the indicated register. The instruction will evaluate to one or two PC 5524relative ADD or SUB instructions depending upon where the label is located. 5525If a second instruction is not needed a NOP instruction will be generated 5526in its place, so that this instruction is always 8 bytes long. 5527.Pp 5528If the label is out of range, or if it is not defined in the same file (and 5529section) as the ADRL instruction, then an error will be generated. This instruction 5530will not make use of the literal pool. 5531.Pp 5532.El 5533For information on the ARM or Thumb instruction sets, see 5534.Em ARM Software Development Toolkit Reference Manual , 5535Advanced RISC Machines Ltd. 5536.Pp 5537.Ss Mapping Symbols 5538The ARM ELF specification requires that special symbols be inserted into object 5539files to mark certain features: 5540.Pp 5541.Bl -tag -width Ds 5542.It $a 5543At the start of a region of code containing ARM instructions. 5544.Pp 5545.It $t 5546At the start of a region of code containing THUMB instructions. 5547.Pp 5548.It $d 5549At the start of a region of data. 5550.Pp 5551.El 5552The assembler will automatically insert these symbols for you - there is no 5553need to code them yourself. Support for tagging symbols ($b, $f, $p and $m) 5554which is also mentioned in the current ARM ELF specification is not implemented. 5555This is because they have been dropped from the new EABI and so tools cannot 5556rely upon their presence. 5557.Pp 5558.Sh 80386 Dependent Features 5559The i386 version 5560.Li as 5561supports both the original Intel 386 architecture in both 16 and 32-bit mode 5562as well as AMD x86-64 architecture extending the Intel architecture to 64-bits. 5563.Pp 5564.Ss Options 5565The i386 version of 5566.Li as 5567has a few machine dependent options: 5568.Pp 5569.Bl -tag -width Ds 5570.It --32 | --64 5571Select the word size, either 32 bits or 64 bits. Selecting 32-bit implies 5572Intel i386 architecture, while 64-bit implies AMD x86-64 architecture. 5573.Pp 5574These options are only available with the ELF object file format, and require 5575that the necessary BFD support has been included (on a 32-bit platform you 5576have to add --enable-64-bit-bfd to configure enable 64-bit usage and use x86-64 5577as target platform). 5578.Pp 5579.It -n 5580By default, x86 GAS replaces multiple nop instructions used for alignment 5581within code sections with multi-byte nop instructions such as leal 0(%esi,1),%esi. 5582This switch disables the optimization. 5583.Pp 5584.It --divide 5585On SVR4-derived platforms, the character 5586.Li / 5587is treated as a comment character, which means that it cannot be used in expressions. 5588The 5589.Li --divide 5590option turns 5591.Li / 5592into a normal character. This does not disable 5593.Li / 5594at the beginning of a line starting a comment, or affect using 5595.Li # 5596for starting a comment. 5597.Pp 5598.It -march= Va CPU 5599This option specifies an instruction set architecture for generating instructions. 5600The following architectures are recognized: 5601.Li i8086 , 5602.Li i186 , 5603.Li i286 , 5604.Li i386 , 5605.Li i486 , 5606.Li i586 , 5607.Li i686 , 5608.Li pentium , 5609.Li pentiumpro , 5610.Li pentiumii , 5611.Li pentiumiii , 5612.Li pentium4 , 5613.Li prescott , 5614.Li nocona , 5615.Li core , 5616.Li core2 , 5617.Li k6 , 5618.Li k6_2 , 5619.Li athlon , 5620.Li sledgehammer , 5621.Li opteron , 5622.Li k8 , 5623.Li generic32 5624and 5625.Li generic64 . 5626.Pp 5627This option only affects instructions generated by the assembler. The 5628.Li .arch 5629directive will take precedent. 5630.Pp 5631.It -mtune= Va CPU 5632This option specifies a processor to optimize for. When used in conjunction 5633with the 5634.Op -march 5635option, only instructions of the processor specified by the 5636.Op -march 5637option will be generated. 5638.Pp 5639Valid 5640.Va CPU 5641values are identical to 5642.Op -march= Va CPU . 5643.Pp 5644.El 5645.Ss AT&T Syntax versus Intel Syntax 5646.Li as 5647now supports assembly using Intel assembler syntax. 5648.Li .intel_syntax 5649selects Intel mode, and 5650.Li .att_syntax 5651switches back to the usual AT&T mode for compatibility with the output of 5652.Li gcc . 5653Either of these directives may have an optional argument, 5654.Li prefix , 5655or 5656.Li noprefix 5657specifying whether registers require a 5658.Li % 5659prefix. AT&T System V/386 assembler syntax is quite different from Intel syntax. 5660We mention these differences because almost all 80386 documents use Intel 5661syntax. Notable differences between the two syntaxes are: 5662.Pp 5663.Bl -bullet 5664.It 5665AT&T immediate operands are preceded by 5666.Li $ ; 5667Intel immediate operands are undelimited (Intel 5668.Li push 4 5669is AT&T 5670.Li pushl $4 ) . 5671AT&T register operands are preceded by 5672.Li % ; 5673Intel register operands are undelimited. AT&T absolute (as opposed to PC relative) 5674jump/call operands are prefixed by 5675.Li * ; 5676they are undelimited in Intel syntax. 5677.Pp 5678.It 5679AT&T and Intel syntax use the opposite order for source and destination operands. 5680Intel 5681.Li add eax, 4 5682is 5683.Li addl $4, %eax . 5684The 5685.Li source, dest 5686convention is maintained for compatibility with previous Unix assemblers. 5687Note that instructions with more than one source operand, such as the 5688.Li enter 5689instruction, do 5690.Em not 5691have reversed order. i386-Bugs. 5692.Pp 5693.It 5694In AT&T syntax the size of memory operands is determined from the last character 5695of the instruction mnemonic. Mnemonic suffixes of 5696.Li b , 5697.Li w , 5698.Li l 5699and 5700.Li q 5701specify byte (8-bit), word (16-bit), long (32-bit) and quadruple word (64-bit) 5702memory references. Intel syntax accomplishes this by prefixing memory operands 5703( 5704.Em not 5705the instruction mnemonics) with 5706.Li byte ptr , 5707.Li word ptr , 5708.Li dword ptr 5709and 5710.Li qword ptr . 5711Thus, Intel 5712.Li mov al, byte ptr Va foo 5713is 5714.Li movb Va foo, %al 5715in AT&T syntax. 5716.Pp 5717.It 5718Immediate form long jumps and calls are 5719.Li lcall/ljmp $ Va section, $ Va offset 5720in AT&T syntax; the Intel syntax is 5721.Li call/jmp far Va section: Va offset . 5722Also, the far return instruction is 5723.Li lret $ Va stack-adjust 5724in AT&T syntax; Intel syntax is 5725.Li ret far Va stack-adjust . 5726.Pp 5727.It 5728The AT&T assembler does not provide support for multiple section programs. 5729Unix style systems expect all programs to be single sections. 5730.El 5731.Pp 5732.Ss Instruction Naming 5733Instruction mnemonics are suffixed with one character modifiers which specify 5734the size of operands. The letters 5735.Li b , 5736.Li w , 5737.Li l 5738and 5739.Li q 5740specify byte, word, long and quadruple word operands. If no suffix is specified 5741by an instruction then 5742.Li as 5743tries to fill in the missing suffix based on the destination register operand 5744(the last one by convention). Thus, 5745.Li mov %ax, %bx 5746is equivalent to 5747.Li movw %ax, %bx ; 5748also, 5749.Li mov $1, %bx 5750is equivalent to 5751.Li movw $1, bx . 5752Note that this is incompatible with the AT&T Unix assembler which assumes 5753that a missing mnemonic suffix implies long operand size. (This incompatibility 5754does not affect compiler output since compilers always explicitly specify 5755the mnemonic suffix.) 5756.Pp 5757Almost all instructions have the same names in AT&T and Intel format. There 5758are a few exceptions. The sign extend and zero extend instructions need two 5759sizes to specify them. They need a size to sign/zero extend 5760.Em from 5761and a size to zero extend 5762.Em to . 5763This is accomplished by using two instruction mnemonic suffixes in AT&T syntax. 5764Base names for sign extend and zero extend are 5765.Li movs... 5766and 5767.Li movz... 5768in AT&T syntax ( 5769.Li movsx 5770and 5771.Li movzx 5772in Intel syntax). The instruction mnemonic suffixes are tacked on to this 5773base name, the 5774.Em from 5775suffix before the 5776.Em to 5777suffix. Thus, 5778.Li movsbl %al, %edx 5779is AT&T syntax for \(lqmove sign extend 5780.Em from 5781%al 5782.Em to 5783%edx.\(rq Possible suffixes, thus, are 5784.Li bl 5785(from byte to long), 5786.Li bw 5787(from byte to word), 5788.Li wl 5789(from word to long), 5790.Li bq 5791(from byte to quadruple word), 5792.Li wq 5793(from word to quadruple word), and 5794.Li lq 5795(from long to quadruple word). 5796.Pp 5797The Intel-syntax conversion instructions 5798.Pp 5799.Bl -bullet 5800.It 5801.Li cbw 5802--- sign-extend byte in 5803.Li %al 5804to word in 5805.Li %ax , 5806.Pp 5807.It 5808.Li cwde 5809--- sign-extend word in 5810.Li %ax 5811to long in 5812.Li %eax , 5813.Pp 5814.It 5815.Li cwd 5816--- sign-extend word in 5817.Li %ax 5818to long in 5819.Li %dx:%ax , 5820.Pp 5821.It 5822.Li cdq 5823--- sign-extend dword in 5824.Li %eax 5825to quad in 5826.Li %edx:%eax , 5827.Pp 5828.It 5829.Li cdqe 5830--- sign-extend dword in 5831.Li %eax 5832to quad in 5833.Li %rax 5834(x86-64 only), 5835.Pp 5836.It 5837.Li cqo 5838--- sign-extend quad in 5839.Li %rax 5840to octuple in 5841.Li %rdx:%rax 5842(x86-64 only), 5843.El 5844.Pp 5845are called 5846.Li cbtw , 5847.Li cwtl , 5848.Li cwtd , 5849.Li cltd , 5850.Li cltq , 5851and 5852.Li cqto 5853in AT&T naming. 5854.Li as 5855accepts either naming for these instructions. 5856.Pp 5857Far call/jump instructions are 5858.Li lcall 5859and 5860.Li ljmp 5861in AT&T syntax, but are 5862.Li call far 5863and 5864.Li jump far 5865in Intel convention. 5866.Pp 5867.Ss Register Naming 5868Register operands are always prefixed with 5869.Li % . 5870The 80386 registers consist of 5871.Pp 5872.Bl -bullet 5873.It 5874the 8 32-bit registers 5875.Li %eax 5876(the accumulator), 5877.Li %ebx , 5878.Li %ecx , 5879.Li %edx , 5880.Li %edi , 5881.Li %esi , 5882.Li %ebp 5883(the frame pointer), and 5884.Li %esp 5885(the stack pointer). 5886.Pp 5887.It 5888the 8 16-bit low-ends of these: 5889.Li %ax , 5890.Li %bx , 5891.Li %cx , 5892.Li %dx , 5893.Li %di , 5894.Li %si , 5895.Li %bp , 5896and 5897.Li %sp . 5898.Pp 5899.It 5900the 8 8-bit registers: 5901.Li %ah , 5902.Li %al , 5903.Li %bh , 5904.Li %bl , 5905.Li %ch , 5906.Li %cl , 5907.Li %dh , 5908and 5909.Li %dl 5910(These are the high-bytes and low-bytes of 5911.Li %ax , 5912.Li %bx , 5913.Li %cx , 5914and 5915.Li %dx ) 5916.Pp 5917.It 5918the 6 section registers 5919.Li %cs 5920(code section), 5921.Li %ds 5922(data section), 5923.Li %ss 5924(stack section), 5925.Li %es , 5926.Li %fs , 5927and 5928.Li %gs . 5929.Pp 5930.It 5931the 3 processor control registers 5932.Li %cr0 , 5933.Li %cr2 , 5934and 5935.Li %cr3 . 5936.Pp 5937.It 5938the 6 debug registers 5939.Li %db0 , 5940.Li %db1 , 5941.Li %db2 , 5942.Li %db3 , 5943.Li %db6 , 5944and 5945.Li %db7 . 5946.Pp 5947.It 5948the 2 test registers 5949.Li %tr6 5950and 5951.Li %tr7 . 5952.Pp 5953.It 5954the 8 floating point register stack 5955.Li %st 5956or equivalently 5957.Li %st(0) , 5958.Li %st(1) , 5959.Li %st(2) , 5960.Li %st(3) , 5961.Li %st(4) , 5962.Li %st(5) , 5963.Li %st(6) , 5964and 5965.Li %st(7) . 5966These registers are overloaded by 8 MMX registers 5967.Li %mm0 , 5968.Li %mm1 , 5969.Li %mm2 , 5970.Li %mm3 , 5971.Li %mm4 , 5972.Li %mm5 , 5973.Li %mm6 5974and 5975.Li %mm7 . 5976.Pp 5977.It 5978the 8 SSE registers registers 5979.Li %xmm0 , 5980.Li %xmm1 , 5981.Li %xmm2 , 5982.Li %xmm3 , 5983.Li %xmm4 , 5984.Li %xmm5 , 5985.Li %xmm6 5986and 5987.Li %xmm7 . 5988.El 5989.Pp 5990The AMD x86-64 architecture extends the register set by: 5991.Pp 5992.Bl -bullet 5993.It 5994enhancing the 8 32-bit registers to 64-bit: 5995.Li %rax 5996(the accumulator), 5997.Li %rbx , 5998.Li %rcx , 5999.Li %rdx , 6000.Li %rdi , 6001.Li %rsi , 6002.Li %rbp 6003(the frame pointer), 6004.Li %rsp 6005(the stack pointer) 6006.Pp 6007.It 6008the 8 extended registers 6009.Li %r8 6010-- 6011.Li %r15 . 6012.Pp 6013.It 6014the 8 32-bit low ends of the extended registers: 6015.Li %r8d 6016-- 6017.Li %r15d 6018.Pp 6019.It 6020the 8 16-bit low ends of the extended registers: 6021.Li %r8w 6022-- 6023.Li %r15w 6024.Pp 6025.It 6026the 8 8-bit low ends of the extended registers: 6027.Li %r8b 6028-- 6029.Li %r15b 6030.Pp 6031.It 6032the 4 8-bit registers: 6033.Li %sil , 6034.Li %dil , 6035.Li %bpl , 6036.Li %spl . 6037.Pp 6038.It 6039the 8 debug registers: 6040.Li %db8 6041-- 6042.Li %db15 . 6043.Pp 6044.It 6045the 8 SSE registers: 6046.Li %xmm8 6047-- 6048.Li %xmm15 . 6049.El 6050.Pp 6051.Ss Instruction Prefixes 6052Instruction prefixes are used to modify the following instruction. They are 6053used to repeat string instructions, to provide section overrides, to perform 6054bus lock operations, and to change operand and address sizes. (Most instructions 6055that normally operate on 32-bit operands will use 16-bit operands if the instruction 6056has an \(lqoperand size\(rq prefix.) Instruction prefixes are best written on the 6057same line as the instruction they act upon. For example, the 6058.Li scas 6059(scan string) instruction is repeated with: 6060.Pp 6061.Bd -literal -offset indent 6062 repne scas %es:(%edi),%al 6063.Ed 6064.Pp 6065You may also place prefixes on the lines immediately preceding the instruction, 6066but this circumvents checks that 6067.Li as 6068does with prefixes, and will not work with all prefixes. 6069.Pp 6070Here is a list of instruction prefixes: 6071.Pp 6072.Bl -bullet 6073.It 6074Section override prefixes 6075.Li cs , 6076.Li ds , 6077.Li ss , 6078.Li es , 6079.Li fs , 6080.Li gs . 6081These are automatically added by specifying using the 6082.Va section 6083: 6084.Va memory-operand 6085form for memory references. 6086.Pp 6087.It 6088Operand/Address size prefixes 6089.Li data16 6090and 6091.Li addr16 6092change 32-bit operands/addresses into 16-bit operands/addresses, while 6093.Li data32 6094and 6095.Li addr32 6096change 16-bit ones (in a 6097.Li .code16 6098section) into 32-bit operands/addresses. These prefixes 6099.Em must 6100appear on the same line of code as the instruction they modify. For example, 6101in a 16-bit 6102.Li .code16 6103section, you might write: 6104.Pp 6105.Bd -literal -offset indent 6106 addr32 jmpl *(%ebx) 6107.Ed 6108.Pp 6109.It 6110The bus lock prefix 6111.Li lock 6112inhibits interrupts during execution of the instruction it precedes. (This 6113is only valid with certain instructions; see a 80386 manual for details). 6114.Pp 6115.It 6116The wait for coprocessor prefix 6117.Li wait 6118waits for the coprocessor to complete the current instruction. This should 6119never be needed for the 80386/80387 combination. 6120.Pp 6121.It 6122The 6123.Li rep , 6124.Li repe , 6125and 6126.Li repne 6127prefixes are added to string instructions to make them repeat 6128.Li %ecx 6129times ( 6130.Li %cx 6131times if the current address size is 16-bits). 6132.It 6133The 6134.Li rex 6135family of prefixes is used by x86-64 to encode extensions to i386 instruction 6136set. The 6137.Li rex 6138prefix has four bits --- an operand size overwrite ( 6139.Li 64 ) 6140used to change operand size from 32-bit to 64-bit and X, Y and Z extensions 6141bits used to extend the register set. 6142.Pp 6143You may write the 6144.Li rex 6145prefixes directly. The 6146.Li rex64xyz 6147instruction emits 6148.Li rex 6149prefix with all the bits set. By omitting the 6150.Li 64 , 6151.Li x , 6152.Li y 6153or 6154.Li z 6155you may write other prefixes as well. Normally, there is no need to write 6156the prefixes explicitly, since gas will automatically generate them based 6157on the instruction operands. 6158.El 6159.Pp 6160.Ss Memory References 6161An Intel syntax indirect memory reference of the form 6162.Pp 6163.Bd -literal -offset indent 6164section:[base + index*scale + disp] 6165.Ed 6166.Pp 6167is translated into the AT&T syntax 6168.Pp 6169.Bd -literal -offset indent 6170section:disp(base, index, scale) 6171.Ed 6172.Pp 6173where 6174.Va base 6175and 6176.Va index 6177are the optional 32-bit base and index registers, 6178.Va disp 6179is the optional displacement, and 6180.Va scale , 6181taking the values 1, 2, 4, and 8, multiplies 6182.Va index 6183to calculate the address of the operand. If no 6184.Va scale 6185is specified, 6186.Va scale 6187is taken to be 1. 6188.Va section 6189specifies the optional section register for the memory operand, and may override 6190the default section register (see a 80386 manual for section register defaults). 6191Note that section overrides in AT&T syntax 6192.Em must 6193be preceded by a 6194.Li % . 6195If you specify a section override which coincides with the default section 6196register, 6197.Li as 6198does 6199.Em not 6200output any section register override prefixes to assemble the given instruction. 6201Thus, section overrides can be specified to emphasize which section register 6202is used for a given memory operand. 6203.Pp 6204Here are some examples of Intel and AT&T style memory references: 6205.Pp 6206.Bl -tag -width Ds 6207.It AT&T: Li -4(%ebp), Intel: Li [ebp - 4] 6208.Va base 6209is 6210.Li %ebp ; 6211.Va disp 6212is 6213.Li -4 . 6214.Va section 6215is missing, and the default section is used ( 6216.Li %ss 6217for addressing with 6218.Li %ebp 6219as the base register). 6220.Va index , 6221.Va scale 6222are both missing. 6223.Pp 6224.It AT&T: Li foo(,%eax,4), Intel: Li [foo + eax*4] 6225.Va index 6226is 6227.Li %eax 6228(scaled by a 6229.Va scale 62304); 6231.Va disp 6232is 6233.Li foo . 6234All other fields are missing. The section register here defaults to 6235.Li %ds . 6236.Pp 6237.It AT&T: Li foo(,1); Intel Li [foo] 6238This uses the value pointed to by 6239.Li foo 6240as a memory operand. Note that 6241.Va base 6242and 6243.Va index 6244are both missing, but there is only 6245.Em one 6246.Li , . 6247This is a syntactic exception. 6248.Pp 6249.It AT&T: Li %gs:foo; Intel Li gs:foo 6250This selects the contents of the variable 6251.Li foo 6252with section register 6253.Va section 6254being 6255.Li %gs . 6256.El 6257.Pp 6258Absolute (as opposed to PC relative) call and jump operands must be prefixed 6259with 6260.Li * . 6261If no 6262.Li * 6263is specified, 6264.Li as 6265always chooses PC relative addressing for jump/call labels. 6266.Pp 6267Any instruction that has a memory operand, but no register operand, 6268.Em must 6269specify its size (byte, word, long, or quadruple) with an instruction mnemonic 6270suffix ( 6271.Li b , 6272.Li w , 6273.Li l 6274or 6275.Li q , 6276respectively). 6277.Pp 6278The x86-64 architecture adds an RIP (instruction pointer relative) addressing. 6279This addressing mode is specified by using 6280.Li rip 6281as a base register. Only constant offsets are valid. For example: 6282.Pp 6283.Bl -tag -width Ds 6284.It AT&T: Li 1234(%rip), Intel: Li [rip + 1234] 6285Points to the address 1234 bytes past the end of the current instruction. 6286.Pp 6287.It AT&T: Li symbol(%rip), Intel: Li [rip + symbol] 6288Points to the 6289.Li symbol 6290in RIP relative way, this is shorter than the default absolute addressing. 6291.El 6292.Pp 6293Other addressing modes remain unchanged in x86-64 architecture, except registers 6294used are 64-bit instead of 32-bit. 6295.Pp 6296.Ss Handling of Jump Instructions 6297Jump instructions are always optimized to use the smallest possible displacements. 6298This is accomplished by using byte (8-bit) displacement jumps whenever the 6299target is sufficiently close. If a byte displacement is insufficient a long 6300displacement is used. We do not support word (16-bit) displacement jumps in 630132-bit mode (i.e. prefixing the jump instruction with the 6302.Li data16 6303instruction prefix), since the 80386 insists upon masking 6304.Li %eip 6305to 16 bits after the word displacement is added. (See alsosee Section 6306.Dq i386-Arch ) 6307.Pp 6308Note that the 6309.Li jcxz , 6310.Li jecxz , 6311.Li loop , 6312.Li loopz , 6313.Li loope , 6314.Li loopnz 6315and 6316.Li loopne 6317instructions only come in byte displacements, so that if you use these instructions 6318( 6319.Li gcc 6320does not use them) you may get an error message (and incorrect code). The 6321AT&T 80386 assembler tries to get around this problem by expanding 6322.Li jcxz foo 6323to 6324.Pp 6325.Bd -literal -offset indent 6326 jcxz cx_zero 6327 jmp cx_nonzero 6328cx_zero: jmp foo 6329cx_nonzero: 6330.Ed 6331.Pp 6332.Ss Floating Point 6333All 80387 floating point types except packed BCD are supported. (BCD support 6334may be added without much difficulty). These data types are 16-, 32-, and 633564- bit integers, and single (32-bit), double (64-bit), and extended (80-bit) 6336precision floating point. Each supported type has an instruction mnemonic 6337suffix and a constructor associated with it. Instruction mnemonic suffixes 6338specify the operand's data type. Constructors build these data types into 6339memory. 6340.Pp 6341.Bl -bullet 6342.It 6343Floating point constructors are 6344.Li .float 6345or 6346.Li .single , 6347.Li .double , 6348and 6349.Li .tfloat 6350for 32-, 64-, and 80-bit formats. These correspond to instruction mnemonic 6351suffixes 6352.Li s , 6353.Li l , 6354and 6355.Li t . 6356.Li t 6357stands for 80-bit (ten byte) real. The 80387 only supports this format via 6358the 6359.Li fldt 6360(load 80-bit real to stack top) and 6361.Li fstpt 6362(store 80-bit real and pop stack) instructions. 6363.Pp 6364.It 6365Integer constructors are 6366.Li .word , 6367.Li .long 6368or 6369.Li .int , 6370and 6371.Li .quad 6372for the 16-, 32-, and 64-bit integer formats. The corresponding instruction 6373mnemonic suffixes are 6374.Li s 6375(single), 6376.Li l 6377(long), and 6378.Li q 6379(quad). As with the 80-bit real format, the 64-bit 6380.Li q 6381format is only present in the 6382.Li fildq 6383(load quad integer to stack top) and 6384.Li fistpq 6385(store quad integer and pop stack) instructions. 6386.El 6387.Pp 6388Register to register operations should not use instruction mnemonic suffixes. 6389.Li fstl %st, %st(1) 6390will give a warning, and be assembled as if you wrote 6391.Li fst %st, %st(1) , 6392since all register to register operations use 80-bit floating point operands. 6393(Contrast this with 6394.Li fstl %st, mem , 6395which converts 6396.Li %st 6397from 80-bit to 64-bit floating point format, then stores the result in the 63984 byte location 6399.Li mem ) 6400.Pp 6401.Ss Intel's MMX and AMD's 3DNow! SIMD Operations 6402.Li as 6403supports Intel's MMX instruction set (SIMD instructions for integer data), 6404available on Intel's Pentium MMX processors and Pentium II processors, AMD's 6405K6 and K6-2 processors, Cyrix' M2 processor, and probably others. It also 6406supports AMD's 3DNow! instruction set (SIMD instructions for 32-bit floating 6407point data) available on AMD's K6-2 processor and possibly others in the future. 6408.Pp 6409Currently, 6410.Li as 6411does not support Intel's floating point SIMD, Katmai (KNI). 6412.Pp 6413The eight 64-bit MMX operands, also used by 3DNow!, are called 6414.Li %mm0 , 6415.Li %mm1 , 6416\&... 6417.Li %mm7 . 6418They contain eight 8-bit integers, four 16-bit integers, two 32-bit integers, 6419one 64-bit integer, or two 32-bit floating point values. The MMX registers 6420cannot be used at the same time as the floating point stack. 6421.Pp 6422See Intel and AMD documentation, keeping in mind that the operand order in 6423instructions is reversed from the Intel syntax. 6424.Pp 6425.Ss Writing 16-bit Code 6426While 6427.Li as 6428normally writes only \(lqpure\(rq 32-bit i386 code or 64-bit x86-64 code depending 6429on the default configuration, it also supports writing code to run in real 6430mode or in 16-bit protected mode code segments. To do this, put a 6431.Li .code16 6432or 6433.Li .code16gcc 6434directive before the assembly language instructions to be run in 16-bit mode. 6435You can switch 6436.Li as 6437back to writing normal 32-bit code with the 6438.Li .code32 6439directive. 6440.Pp 6441.Li .code16gcc 6442provides experimental support for generating 16-bit code from gcc, and differs 6443from 6444.Li .code16 6445in that 6446.Li call , 6447.Li ret , 6448.Li enter , 6449.Li leave , 6450.Li push , 6451.Li pop , 6452.Li pusha , 6453.Li popa , 6454.Li pushf , 6455and 6456.Li popf 6457instructions default to 32-bit size. This is so that the stack pointer is 6458manipulated in the same way over function calls, allowing access to function 6459parameters at the same stack offsets as in 32-bit mode. 6460.Li .code16gcc 6461also automatically adds address size prefixes where necessary to use the 32-bit 6462addressing modes that gcc generates. 6463.Pp 6464The code which 6465.Li as 6466generates in 16-bit mode will not necessarily run on a 16-bit pre-80386 processor. 6467To write code that runs on such a processor, you must refrain from using 6468.Em any 646932-bit constructs which require 6470.Li as 6471to output address or operand size prefixes. 6472.Pp 6473Note that writing 16-bit code instructions by explicitly specifying a prefix 6474or an instruction mnemonic suffix within a 32-bit code section generates different 6475machine instructions than those generated for a 16-bit code segment. In a 647632-bit code section, the following code generates the machine opcode bytes 6477.Li 66 6a 04 , 6478which pushes the value 6479.Li 4 6480onto the stack, decrementing 6481.Li %esp 6482by 2. 6483.Pp 6484.Bd -literal -offset indent 6485 pushw $4 6486.Ed 6487.Pp 6488The same code in a 16-bit code section would generate the machine opcode bytes 6489.Li 6a 04 6490(i.e., without the operand size prefix), which is correct since the processor 6491default operand size is assumed to be 16 bits in a 16-bit code section. 6492.Pp 6493.Ss AT&T Syntax bugs 6494The UnixWare assembler, and probably other AT&T derived ix86 Unix assemblers, 6495generate floating point instructions with reversed source and destination 6496registers in certain cases. Unfortunately, gcc and possibly many other programs 6497use this reversed syntax, so we're stuck with it. 6498.Pp 6499For example 6500.Pp 6501.Bd -literal -offset indent 6502 fsub %st,%st(3) 6503.Ed 6504results in 6505.Li %st(3) 6506being updated to 6507.Li %st - %st(3) 6508rather than the expected 6509.Li %st(3) - %st . 6510This happens with all the non-commutative arithmetic floating point operations 6511with two register operands where the source register is 6512.Li %st 6513and the destination register is 6514.Li %st(i) . 6515.Pp 6516.Ss Specifying CPU Architecture 6517.Li as 6518may be told to assemble for a particular CPU (sub-)architecture with the 6519.Li .arch Va cpu_type 6520directive. This directive enables a warning when gas detects an instruction 6521that is not supported on the CPU specified. The choices for 6522.Va cpu_type 6523are: 6524.Pp 6525.TS 6526l l l l. 6527 6528i8086 i186 i286 i386 6529i486 i586 i686 pentium 6530pentiumpro pentiumii pentiumiii pentium4 6531prescott nocona core core2 6532amdfam10 6533k6 athlon sledgehammer k8 6534\&.mmx .sse .sse2 .sse3 6535\&.ssse3 .sse4.1 .sse4.2 .sse4 6536\&.sse4a .3dnow .3dnowa .padlock 6537\&.pacifica .svme .abm 6538.TE 6539.Pp 6540Apart from the warning, there are only two other effects on 6541.Li as 6542operation; Firstly, if you specify a CPU other than 6543.Li i486 , 6544then shift by one instructions such as 6545.Li sarl $1, %eax 6546will automatically use a two byte opcode sequence. The larger three byte opcode 6547sequence is used on the 486 (and when no architecture is specified) because 6548it executes faster on the 486. Note that you can explicitly request the two 6549byte opcode by writing 6550.Li sarl %eax . 6551Secondly, if you specify 6552.Li i8086 , 6553.Li i186 , 6554or 6555.Li i286 , 6556.Em and 6557.Li .code16 6558or 6559.Li .code16gcc 6560then byte offset conditional jumps will be promoted when necessary to a two 6561instruction sequence consisting of a conditional jump of the opposite sense 6562around an unconditional jump to the target. 6563.Pp 6564Following the CPU architecture (but not a sub-architecture, which are those 6565starting with a dot), you may specify 6566.Li jumps 6567or 6568.Li nojumps 6569to control automatic promotion of conditional jumps. 6570.Li jumps 6571is the default, and enables jump promotion; All external jumps will be of 6572the long variety, and file-local jumps will be promoted as necessary. (see Section 6573.Dq i386-Jumps ) 6574.Li nojumps 6575leaves external conditional jumps as byte offset jumps, and warns about file-local 6576conditional jumps that 6577.Li as 6578promotes. Unconditional jumps are treated as for 6579.Li jumps . 6580.Pp 6581For example 6582.Pp 6583.Bd -literal -offset indent 6584 .arch i8086,nojumps 6585.Ed 6586.Pp 6587.Ss Notes 6588There is some trickery concerning the 6589.Li mul 6590and 6591.Li imul 6592instructions that deserves mention. The 16-, 32-, 64- and 128-bit expanding 6593multiplies (base opcode 6594.Li 0xf6 ; 6595extension 4 for 6596.Li mul 6597and 5 for 6598.Li imul ) 6599can be output only in the one operand form. Thus, 6600.Li imul %ebx, %eax 6601does 6602.Em not 6603select the expanding multiply; the expanding multiply would clobber the 6604.Li %edx 6605register, and this would confuse 6606.Li gcc 6607output. Use 6608.Li imul %ebx 6609to get the 64-bit product in 6610.Li %edx:%eax . 6611.Pp 6612We have added a two operand form of 6613.Li imul 6614when the first operand is an immediate mode expression and the second operand 6615is a register. This is just a shorthand, so that, multiplying 6616.Li %eax 6617by 69, for example, can be done with 6618.Li imul $69, %eax 6619rather than 6620.Li imul $69, %eax, %eax . 6621.Pp 6622.Sh IA-64 Dependent Features 6623.Ss Options 6624.Bl -tag -width Ds 6625.It -mconstant-gp 6626This option instructs the assembler to mark the resulting object file as using 6627the \(lqconstant GP\(rq model. With this model, it is assumed that the entire program 6628uses a single global pointer (GP) value. Note that this option does not in 6629any fashion affect the machine code emitted by the assembler. All it does 6630is turn on the EF_IA_64_CONS_GP flag in the ELF file header. 6631.Pp 6632.It -mauto-pic 6633This option instructs the assembler to mark the resulting object file as using 6634the \(lqconstant GP without function descriptor\(rq data model. This model is like 6635the \(lqconstant GP\(rq model, except that it additionally does away with function 6636descriptors. What this means is that the address of a function refers directly 6637to the function's code entry-point. Normally, such an address would refer 6638to a function descriptor, which contains both the code entry-point and the 6639GP-value needed by the function. Note that this option does not in any fashion 6640affect the machine code emitted by the assembler. All it does is turn on the 6641EF_IA_64_NOFUNCDESC_CONS_GP flag in the ELF file header. 6642.Pp 6643.It -milp32 6644.It -milp64 6645.It -mlp64 6646.It -mp64 6647These options select the data model. The assembler defaults to 6648.Li -mlp64 6649(LP64 data model). 6650.Pp 6651.It -mle 6652.It -mbe 6653These options select the byte order. The 6654.Li -mle 6655option selects little-endian byte order (default) and 6656.Li -mbe 6657selects big-endian byte order. Note that IA-64 machine code always uses little-endian 6658byte order. 6659.Pp 6660.It -mtune=itanium1 6661.It -mtune=itanium2 6662Tune for a particular IA-64 CPU, 6663.Va itanium1 6664or 6665.Va itanium2 . 6666The default is 6667.Va itanium2 . 6668.Pp 6669.It -munwind-check=warning 6670.It -munwind-check=error 6671These options control what the assembler will do when performing consistency 6672checks on unwind directives. 6673.Li -munwind-check=warning 6674will make the assembler issue a warning when an unwind directive check fails. 6675This is the default. 6676.Li -munwind-check=error 6677will make the assembler issue an error when an unwind directive check fails. 6678.Pp 6679.It -mhint.b=ok 6680.It -mhint.b=warning 6681.It -mhint.b=error 6682These options control what the assembler will do when the 6683.Li hint.b 6684instruction is used. 6685.Li -mhint.b=ok 6686will make the assembler accept 6687.Li hint.b . 6688.Li -mint.b=warning 6689will make the assembler issue a warning when 6690.Li hint.b 6691is used. 6692.Li -mhint.b=error 6693will make the assembler treat 6694.Li hint.b 6695as an error, which is the default. 6696.Pp 6697.It -x 6698.It -xexplicit 6699These options turn on dependency violation checking. 6700.Pp 6701.It -xauto 6702This option instructs the assembler to automatically insert stop bits where 6703necessary to remove dependency violations. This is the default mode. 6704.Pp 6705.It -xnone 6706This option turns off dependency violation checking. 6707.Pp 6708.It -xdebug 6709This turns on debug output intended to help tracking down bugs in the dependency 6710violation checker. 6711.Pp 6712.It -xdebugn 6713This is a shortcut for -xnone -xdebug. 6714.Pp 6715.It -xdebugx 6716This is a shortcut for -xexplicit -xdebug. 6717.Pp 6718.El 6719.Ss Syntax 6720The assembler syntax closely follows the IA-64 Assembly Language Reference 6721Guide. 6722.Pp 6723.Em Special Characters 6724.Pp 6725.Li // 6726is the line comment token. 6727.Pp 6728.Li ; 6729can be used instead of a newline to separate statements. 6730.Pp 6731.Em Register Names 6732.Pp 6733The 128 integer registers are referred to as 6734.Li r Va n . 6735The 128 floating-point registers are referred to as 6736.Li f Va n . 6737The 128 application registers are referred to as 6738.Li ar Va n . 6739The 128 control registers are referred to as 6740.Li cr Va n . 6741The 64 one-bit predicate registers are referred to as 6742.Li p Va n . 6743The 8 branch registers are referred to as 6744.Li b Va n . 6745In addition, the assembler defines a number of aliases: 6746.Li gp 6747( 6748.Li r1 ) , 6749.Li sp 6750( 6751.Li r12 ) , 6752.Li rp 6753( 6754.Li b0 ) , 6755.Li ret0 6756( 6757.Li r8 ) , 6758.Li ret1 6759( 6760.Li r9 ) , 6761.Li ret2 6762( 6763.Li r10 ) , 6764.Li ret3 6765( 6766.Li r9 ) , 6767.Li farg Va n 6768( 6769.Li f8+ Va n ) , 6770and 6771.Li fret Va n 6772( 6773.Li f8+ Va n ) . 6774.Pp 6775For convenience, the assembler also defines aliases for all named application 6776and control registers. For example, 6777.Li ar.bsp 6778refers to the register backing store pointer ( 6779.Li ar17 ) . 6780Similarly, 6781.Li cr.eoi 6782refers to the end-of-interrupt register ( 6783.Li cr67 ) . 6784.Pp 6785.Em IA-64 Processor-Status-Register (PSR) Bit Names 6786.Pp 6787The assembler defines bit masks for each of the bits in the IA-64 processor 6788status register. For example, 6789.Li psr.ic 6790corresponds to a value of 0x2000. These masks are primarily intended for use 6791with the 6792.Li ssm 6793/ 6794.Li sum 6795and 6796.Li rsm 6797/ 6798.Li rum 6799instructions, but they can be used anywhere else where an integer constant 6800is expected. 6801.Pp 6802.Ss Opcodes 6803For detailed information on the IA-64 machine instruction set, see the 6804.Lk http://developer.intel.com/design/itanium/arch_spec.htm . 6805.Pp 6806.Sh MIPS Dependent Features 6807GNU 6808.Li as 6809for mips architectures supports several different mips processors, and MIPS 6810ISA levels I through V, MIPS32, and MIPS64. For information about the mips 6811instruction set, see 6812.Em MIPS RISC Architecture , 6813by Kane and Heindrich (Prentice-Hall). For an overview of mips assembly conventions, 6814see \(lqAppendix D: Assembly Language Programming\(rq in the same work. 6815.Pp 6816.Ss Assembler options 6817The mips configurations of GNU 6818.Li as 6819support these special options: 6820.Pp 6821.Bl -tag -width Ds 6822.It -G Va num 6823This option sets the largest size of an object that can be referenced implicitly 6824with the 6825.Li gp 6826register. It is only accepted for targets that use ecoff format. The default 6827value is 8. 6828.Pp 6829.It -EB 6830.It -EL 6831Any mips configuration of 6832.Li as 6833can select big-endian or little-endian output at run time (unlike the other 6834GNU development tools, which must be configured for one or the other). Use 6835.Li -EB 6836to select big-endian output, and 6837.Li -EL 6838for little-endian. 6839.Pp 6840.It -KPIC 6841Generate SVR4-style PIC. This option tells the assembler to generate SVR4-style 6842position-independent macro expansions. It also tells the assembler to mark 6843the output file as PIC. 6844.Pp 6845.It -mvxworks-pic 6846Generate VxWorks PIC. This option tells the assembler to generate VxWorks-style 6847position-independent macro expansions. 6848.Pp 6849.It -mips1 6850.It -mips2 6851.It -mips3 6852.It -mips4 6853.It -mips5 6854.It -mips32 6855.It -mips32r2 6856.It -mips64 6857.It -mips64r2 6858Generate code for a particular MIPS Instruction Set Architecture level. 6859.Li -mips1 6860corresponds to the r2000 and r3000 processors, 6861.Li -mips2 6862to the r6000 processor, 6863.Li -mips3 6864to the r4000 processor, and 6865.Li -mips4 6866to the r8000 and r10000 processors. 6867.Li -mips5 , 6868.Li -mips32 , 6869.Li -mips32r2 , 6870.Li -mips64 , 6871and 6872.Li -mips64r2 6873correspond to generic MIPS V, MIPS32, MIPS32 Release 2, MIPS64, and MIPS64 6874Release 2 ISA processors, respectively. You can also switch instruction sets 6875during the assembly; see MIPS ISA, Directives to override the ISA level. 6876.Pp 6877.It -mgp32 6878.It -mfp32 6879Some macros have different expansions for 32-bit and 64-bit registers. The 6880register sizes are normally inferred from the ISA and ABI, but these flags 6881force a certain group of registers to be treated as 32 bits wide at all times. 6882.Li -mgp32 6883controls the size of general-purpose registers and 6884.Li -mfp32 6885controls the size of floating-point registers. 6886.Pp 6887The 6888.Li .set gp=32 6889and 6890.Li .set fp=32 6891directives allow the size of registers to be changed for parts of an object. 6892The default value is restored by 6893.Li .set gp=default 6894and 6895.Li .set fp=default . 6896.Pp 6897On some MIPS variants there is a 32-bit mode flag; when this flag is set, 689864-bit instructions generate a trap. Also, some 32-bit OSes only save the 689932-bit registers on a context switch, so it is essential never to use the 690064-bit registers. 6901.Pp 6902.It -mgp64 6903.It -mfp64 6904Assume that 64-bit registers are available. This is provided in the interests 6905of symmetry with 6906.Li -mgp32 6907and 6908.Li -mfp32 . 6909.Pp 6910The 6911.Li .set gp=64 6912and 6913.Li .set fp=64 6914directives allow the size of registers to be changed for parts of an object. 6915The default value is restored by 6916.Li .set gp=default 6917and 6918.Li .set fp=default . 6919.Pp 6920.It -mips16 6921.It -no-mips16 6922Generate code for the MIPS 16 processor. This is equivalent to putting 6923.Li .set mips16 6924at the start of the assembly file. 6925.Li -no-mips16 6926turns off this option. 6927.Pp 6928.It -msmartmips 6929.It -mno-smartmips 6930Enables the SmartMIPS extensions to the MIPS32 instruction set, which provides 6931a number of new instructions which target smartcard and cryptographic applications. 6932This is equivalent to putting 6933.Li .set smartmips 6934at the start of the assembly file. 6935.Li -mno-smartmips 6936turns off this option. 6937.Pp 6938.It -mips3d 6939.It -no-mips3d 6940Generate code for the MIPS-3D Application Specific Extension. This tells the 6941assembler to accept MIPS-3D instructions. 6942.Li -no-mips3d 6943turns off this option. 6944.Pp 6945.It -mdmx 6946.It -no-mdmx 6947Generate code for the MDMX Application Specific Extension. This tells the 6948assembler to accept MDMX instructions. 6949.Li -no-mdmx 6950turns off this option. 6951.Pp 6952.It -mdsp 6953.It -mno-dsp 6954Generate code for the DSP Release 1 Application Specific Extension. This tells 6955the assembler to accept DSP Release 1 instructions. 6956.Li -mno-dsp 6957turns off this option. 6958.Pp 6959.It -mdspr2 6960.It -mno-dspr2 6961Generate code for the DSP Release 2 Application Specific Extension. This option 6962implies -mdsp. This tells the assembler to accept DSP Release 2 instructions. 6963.Li -mno-dspr2 6964turns off this option. 6965.Pp 6966.It -mmt 6967.It -mno-mt 6968Generate code for the MT Application Specific Extension. This tells the assembler 6969to accept MT instructions. 6970.Li -mno-mt 6971turns off this option. 6972.Pp 6973.It -mfix7000 6974.It -mno-fix7000 6975Cause nops to be inserted if the read of the destination register of an mfhi 6976or mflo instruction occurs in the following two instructions. 6977.Pp 6978.It -mfix-vr4120 6979.It -no-mfix-vr4120 6980Insert nops to work around certain VR4120 errata. This option is intended 6981to be used on GCC-generated code: it is not designed to catch all problems 6982in hand-written assembler code. 6983.Pp 6984.It -mfix-vr4130 6985.It -no-mfix-vr4130 6986Insert nops to work around the VR4130 6987.Li mflo 6988/ 6989.Li mfhi 6990errata. 6991.Pp 6992.It -m4010 6993.It -no-m4010 6994Generate code for the LSI r4010 chip. This tells the assembler to accept the 6995r4010 specific instructions ( 6996.Li addciu , 6997.Li ffc , 6998etc.), and to not schedule 6999.Li nop 7000instructions around accesses to the 7001.Li HI 7002and 7003.Li LO 7004registers. 7005.Li -no-m4010 7006turns off this option. 7007.Pp 7008.It -m4650 7009.It -no-m4650 7010Generate code for the MIPS r4650 chip. This tells the assembler to accept 7011the 7012.Li mad 7013and 7014.Li madu 7015instruction, and to not schedule 7016.Li nop 7017instructions around accesses to the 7018.Li HI 7019and 7020.Li LO 7021registers. 7022.Li -no-m4650 7023turns off this option. 7024.Pp 7025.It -m3900 7026.It -no-m3900 7027.It -m4100 7028.It -no-m4100 7029For each option 7030.Li -m Va nnnn , 7031generate code for the MIPS r 7032.Va nnnn 7033chip. This tells the assembler to accept instructions specific to that chip, 7034and to schedule for that chip's hazards. 7035.Pp 7036.It -march= Va cpu 7037Generate code for a particular MIPS cpu. It is exactly equivalent to 7038.Li -m Va cpu , 7039except that there are more value of 7040.Va cpu 7041understood. Valid 7042.Va cpu 7043value are: 7044.Pp 7045.Qo 70462000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, vr4181, 4300, 4400, 70474600, 4650, 5000, rm5200, rm5230, rm5231, rm5261, rm5721, vr5400, vr5500, 70486000, rm7000, 8000, rm9000, 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, 70494kep, 4ksd, m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, 705034kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a 7051.Qc 7052.Pp 7053.It -mtune= Va cpu 7054Schedule and tune for a particular MIPS cpu. Valid 7055.Va cpu 7056values are identical to 7057.Li -march= Va cpu . 7058.Pp 7059.It -mabi= Va abi 7060Record which ABI the source code uses. The recognized arguments are: 7061.Li 32 , 7062.Li n32 , 7063.Li o64 , 7064.Li 64 7065and 7066.Li eabi . 7067.Pp 7068.It -msym32 7069.It -mno-sym32 7070Equivalent to adding 7071.Li .set sym32 7072or 7073.Li .set nosym32 7074to the beginning of the assembler input.See Section 7075.Dq MIPS symbol sizes . 7076.Pp 7077.It -nocpp 7078This option is ignored. It is accepted for command-line compatibility with 7079other assemblers, which use it to turn off C style preprocessing. With GNU 7080.Li as , 7081there is no need for 7082.Li -nocpp , 7083because the GNU assembler itself never runs the C preprocessor. 7084.Pp 7085.It --construct-floats 7086.It --no-construct-floats 7087The 7088.Li --no-construct-floats 7089option disables the construction of double width floating point constants 7090by loading the two halves of the value into the two single width floating 7091point registers that make up the double width register. This feature is useful 7092if the processor support the FR bit in its status register, and this bit is 7093known (by the programmer) to be set. This bit prevents the aliasing of the 7094double width register by the single width registers. 7095.Pp 7096By default 7097.Li --construct-floats 7098is selected, allowing construction of these floating point constants. 7099.Pp 7100.It --trap 7101.It --no-break 7102.Li as 7103automatically macro expands certain division and multiplication instructions 7104to check for overflow and division by zero. This option causes 7105.Li as 7106to generate code to take a trap exception rather than a break exception when 7107an error is detected. The trap instructions are only supported at Instruction 7108Set Architecture level 2 and higher. 7109.Pp 7110.It --break 7111.It --no-trap 7112Generate code to take a break exception rather than a trap exception when 7113an error is detected. This is the default. 7114.Pp 7115.It -mpdr 7116.It -mno-pdr 7117Control generation of 7118.Li .pdr 7119sections. Off by default on IRIX, on elsewhere. 7120.Pp 7121.It -mshared 7122.It -mno-shared 7123When generating code using the Unix calling conventions (selected by 7124.Li -KPIC 7125or 7126.Li -mcall_shared ) , 7127gas will normally generate code which can go into a shared library. The 7128.Li -mno-shared 7129option tells gas to generate code which uses the calling convention, but can 7130not go into a shared library. The resulting code is slightly more efficient. 7131This option only affects the handling of the 7132.Li .cpload 7133and 7134.Li .cpsetup 7135pseudo-ops. 7136.El 7137.Pp 7138.Ss MIPS ECOFF object code 7139Assembling for a mips ecoff target supports some additional sections besides 7140the usual 7141.Li .text , 7142.Li .data 7143and 7144.Li .bss . 7145The additional sections are 7146.Li .rdata , 7147used for read-only data, 7148.Li .sdata , 7149used for small data, and 7150.Li .sbss , 7151used for small common objects. 7152.Pp 7153When assembling for ecoff, the assembler uses the 7154.Li $gp 7155( 7156.Li $28 ) 7157register to form the address of a \(lqsmall object\(rq. Any object in the 7158.Li .sdata 7159or 7160.Li .sbss 7161sections is considered \(lqsmall\(rq in this sense. For external objects, or for objects 7162in the 7163.Li .bss 7164section, you can use the 7165.Li gcc 7166.Li -G 7167option to control the size of objects addressed via 7168.Li $gp ; 7169the default value is 8, meaning that a reference to any object eight bytes 7170or smaller uses 7171.Li $gp . 7172Passing 7173.Li -G 0 7174to 7175.Li as 7176prevents it from using the 7177.Li $gp 7178register on the basis of object size (but the assembler uses 7179.Li $gp 7180for objects in 7181.Li .sdata 7182or 7183.Li sbss 7184in any case). The size of an object in the 7185.Li .bss 7186section is set by the 7187.Li .comm 7188or 7189.Li .lcomm 7190directive that defines it. The size of an external object may be set with 7191the 7192.Li .extern 7193directive. For example, 7194.Li .extern sym,4 7195declares that the object at 7196.Li sym 7197is 4 bytes in length, whie leaving 7198.Li sym 7199otherwise undefined. 7200.Pp 7201Using small ecoff objects requires linker support, and assumes that the 7202.Li $gp 7203register is correctly initialized (normally done automatically by the startup 7204code). mips ecoff assembly code must not modify the 7205.Li $gp 7206register. 7207.Pp 7208.Ss Directives for debugging information 7209mips ecoff 7210.Li as 7211supports several directives used for generating debugging information which 7212are not support by traditional mips assemblers. These are 7213.Li .def , 7214.Li .endef , 7215.Li .dim , 7216.Li .file , 7217.Li .scl , 7218.Li .size , 7219.Li .tag , 7220.Li .type , 7221.Li .val , 7222.Li .stabd , 7223.Li .stabn , 7224and 7225.Li .stabs . 7226The debugging information generated by the three 7227.Li .stab 7228directives can only be read by gdb, not by traditional mips debuggers (this 7229enhancement is required to fully support C++ debugging). These directives 7230are primarily used by compilers, not assembly language programmers! 7231.Pp 7232.Ss Directives to override the size of symbols 7233The n64 ABI allows symbols to have any 64-bit value. Although this provides 7234a great deal of flexibility, it means that some macros have much longer expansions 7235than their 32-bit counterparts. For example, the non-PIC expansion of 7236.Li dla $4,sym 7237is usually: 7238.Pp 7239.Bd -literal -offset indent 7240lui $4,%highest(sym) 7241lui $1,%hi(sym) 7242daddiu $4,$4,%higher(sym) 7243daddiu $1,$1,%lo(sym) 7244dsll32 $4,$4,0 7245daddu $4,$4,$1 7246.Ed 7247.Pp 7248whereas the 32-bit expansion is simply: 7249.Pp 7250.Bd -literal -offset indent 7251lui $4,%hi(sym) 7252daddiu $4,$4,%lo(sym) 7253.Ed 7254.Pp 7255n64 code is sometimes constructed in such a way that all symbolic constants 7256are known to have 32-bit values, and in such cases, it's preferable to use 7257the 32-bit expansion instead of the 64-bit expansion. 7258.Pp 7259You can use the 7260.Li .set sym32 7261directive to tell the assembler that, from this point on, all expressions 7262of the form 7263.Li Va symbol 7264or 7265.Li Va symbol + Va offset 7266have 32-bit values. For example: 7267.Pp 7268.Bd -literal -offset indent 7269\&.set sym32 7270dla $4,sym 7271lw $4,sym+16 7272sw $4,sym+0x8000($4) 7273.Ed 7274.Pp 7275will cause the assembler to treat 7276.Li sym , 7277.Li sym+16 7278and 7279.Li sym+0x8000 7280as 32-bit values. The handling of non-symbolic addresses is not affected. 7281.Pp 7282The directive 7283.Li .set nosym32 7284ends a 7285.Li .set sym32 7286block and reverts to the normal behavior. It is also possible to change the 7287symbol size using the command-line options 7288.Op -msym32 7289and 7290.Op -mno-sym32 . 7291.Pp 7292These options and directives are always accepted, but at present, they have 7293no effect for anything other than n64. 7294.Pp 7295.Ss Directives to override the ISA level 7296GNU 7297.Li as 7298supports an additional directive to change the mips Instruction Set Architecture 7299level on the fly: 7300.Li .set mips Va n . 7301.Va n 7302should be a number from 0 to 5, or 32, 32r2, 64 or 64r2. The values other 7303than 0 make the assembler accept instructions for the corresponding isa level, 7304from that point on in the assembly. 7305.Li .set mips Va n 7306affects not only which instructions are permitted, but also how certain macros 7307are expanded. 7308.Li .set mips0 7309restores the isa level to its original level: either the level you selected 7310with command line options, or the default for your configuration. You can 7311use this feature to permit specific mips3 instructions while assembling in 731232 bit mode. Use this directive with care! 7313.Pp 7314The 7315.Li .set arch= Va cpu 7316directive provides even finer control. It changes the effective CPU target 7317and allows the assembler to use instructions specific to a particular CPU. 7318All CPUs supported by the 7319.Li -march 7320command line option are also selectable by this directive. The original value 7321is restored by 7322.Li .set arch=default . 7323.Pp 7324The directive 7325.Li .set mips16 7326puts the assembler into MIPS 16 mode, in which it will assemble instructions 7327for the MIPS 16 processor. Use 7328.Li .set nomips16 7329to return to normal 32 bit mode. 7330.Pp 7331Traditional mips assemblers do not support this directive. 7332.Pp 7333.Ss Directives for extending MIPS 16 bit instructions 7334By default, MIPS 16 instructions are automatically extended to 32 bits when 7335necessary. The directive 7336.Li .set noautoextend 7337will turn this off. When 7338.Li .set noautoextend 7339is in effect, any 32 bit instruction must be explicitly extended with the 7340.Li .e 7341modifier (e.g., 7342.Li li.e $4,1000 ) . 7343The directive 7344.Li .set autoextend 7345may be used to once again automatically extend instructions when necessary. 7346.Pp 7347This directive is only meaningful when in MIPS 16 mode. Traditional mips assemblers 7348do not support this directive. 7349.Pp 7350.Ss Directive to mark data as an instruction 7351The 7352.Li .insn 7353directive tells 7354.Li as 7355that the following data is actually instructions. This makes a difference 7356in MIPS 16 mode: when loading the address of a label which precedes instructions, 7357.Li as 7358automatically adds 1 to the value, so that jumping to the loaded address will 7359do the right thing. 7360.Pp 7361.Ss Directives to save and restore options 7362The directives 7363.Li .set push 7364and 7365.Li .set pop 7366may be used to save and restore the current settings for all the options which 7367are controlled by 7368.Li .set . 7369The 7370.Li .set push 7371directive saves the current settings on a stack. The 7372.Li .set pop 7373directive pops the stack and restores the settings. 7374.Pp 7375These directives can be useful inside an macro which must change an option 7376such as the ISA level or instruction reordering but does not want to change 7377the state of the code which invoked the macro. 7378.Pp 7379Traditional mips assemblers do not support these directives. 7380.Pp 7381.Ss Directives to control generation of MIPS ASE instructions 7382The directive 7383.Li .set mips3d 7384makes the assembler accept instructions from the MIPS-3D Application Specific 7385Extension from that point on in the assembly. The 7386.Li .set nomips3d 7387directive prevents MIPS-3D instructions from being accepted. 7388.Pp 7389The directive 7390.Li .set smartmips 7391makes the assembler accept instructions from the SmartMIPS Application Specific 7392Extension to the MIPS32 isa from that point on in the assembly. The 7393.Li .set nosmartmips 7394directive prevents SmartMIPS instructions from being accepted. 7395.Pp 7396The directive 7397.Li .set mdmx 7398makes the assembler accept instructions from the MDMX Application Specific 7399Extension from that point on in the assembly. The 7400.Li .set nomdmx 7401directive prevents MDMX instructions from being accepted. 7402.Pp 7403The directive 7404.Li .set dsp 7405makes the assembler accept instructions from the DSP Release 1 Application 7406Specific Extension from that point on in the assembly. The 7407.Li .set nodsp 7408directive prevents DSP Release 1 instructions from being accepted. 7409.Pp 7410The directive 7411.Li .set dspr2 7412makes the assembler accept instructions from the DSP Release 2 Application 7413Specific Extension from that point on in the assembly. This dirctive implies 7414.Li .set dsp . 7415The 7416.Li .set nodspr2 7417directive prevents DSP Release 2 instructions from being accepted. 7418.Pp 7419The directive 7420.Li .set mt 7421makes the assembler accept instructions from the MT Application Specific Extension 7422from that point on in the assembly. The 7423.Li .set nomt 7424directive prevents MT instructions from being accepted. 7425.Pp 7426Traditional mips assemblers do not support these directives. 7427.Pp 7428.Sh PowerPC Dependent Features 7429.Ss Options 7430The PowerPC chip family includes several successive levels, using the same 7431core instruction set, but including a few additional instructions at each 7432level. There are exceptions to this however. For details on what instructions 7433each variant supports, please see the chip's architecture reference manual. 7434.Pp 7435The following table lists all available PowerPC options. 7436.Pp 7437.Bl -tag -width Ds 7438.It -mpwrx | -mpwr2 7439Generate code for POWER/2 (RIOS2). 7440.Pp 7441.It -mpwr 7442Generate code for POWER (RIOS1) 7443.Pp 7444.It -m601 7445Generate code for PowerPC 601. 7446.Pp 7447.It -mppc, -mppc32, -m603, -m604 7448Generate code for PowerPC 603/604. 7449.Pp 7450.It -m403, -m405 7451Generate code for PowerPC 403/405. 7452.Pp 7453.It -m440 7454Generate code for PowerPC 440. BookE and some 405 instructions. 7455.Pp 7456.It -m7400, -m7410, -m7450, -m7455 7457Generate code for PowerPC 7400/7410/7450/7455. 7458.Pp 7459.It -mppc64, -m620 7460Generate code for PowerPC 620/625/630. 7461.Pp 7462.It -me500, -me500x2 7463Generate code for Motorola e500 core complex. 7464.Pp 7465.It -mspe 7466Generate code for Motorola SPE instructions. 7467.Pp 7468.It -mppc64bridge 7469Generate code for PowerPC 64, including bridge insns. 7470.Pp 7471.It -mbooke64 7472Generate code for 64-bit BookE. 7473.Pp 7474.It -mbooke, mbooke32 7475Generate code for 32-bit BookE. 7476.Pp 7477.It -me300 7478Generate code for PowerPC e300 family. 7479.Pp 7480.It -maltivec 7481Generate code for processors with AltiVec instructions. 7482.Pp 7483.It -mpower4 7484Generate code for Power4 architecture. 7485.Pp 7486.It -mpower5 7487Generate code for Power5 architecture. 7488.Pp 7489.It -mpower6 7490Generate code for Power6 architecture. 7491.Pp 7492.It -mcell 7493Generate code for Cell Broadband Engine architecture. 7494.Pp 7495.It -mcom 7496Generate code Power/PowerPC common instructions. 7497.Pp 7498.It -many 7499Generate code for any architecture (PWR/PWRX/PPC). 7500.Pp 7501.It -mregnames 7502Allow symbolic names for registers. 7503.Pp 7504.It -mno-regnames 7505Do not allow symbolic names for registers. 7506.Pp 7507.It -mrelocatable 7508Support for GCC's -mrelocatable option. 7509.Pp 7510.It -mrelocatable-lib 7511Support for GCC's -mrelocatable-lib option. 7512.Pp 7513.It -memb 7514Set PPC_EMB bit in ELF flags. 7515.Pp 7516.It -mlittle, -mlittle-endian 7517Generate code for a little endian machine. 7518.Pp 7519.It -mbig, -mbig-endian 7520Generate code for a big endian machine. 7521.Pp 7522.It -msolaris 7523Generate code for Solaris. 7524.Pp 7525.It -mno-solaris 7526Do not generate code for Solaris. 7527.El 7528.Pp 7529.Ss PowerPC Assembler Directives 7530A number of assembler directives are available for PowerPC. The following 7531table is far from complete. 7532.Pp 7533.Bl -tag -width Ds 7534.It .machine "string" 7535This directive allows you to change the machine for which code is generated. 7536.Li "string" 7537may be any of the -m cpu selection options (without the -m) enclosed in double 7538quotes, 7539.Li "push" , 7540or 7541.Li "pop" . 7542.Li .machine "push" 7543saves the currently selected cpu, which may be restored with 7544.Li .machine "pop" . 7545.El 7546.Pp 7547.Sh SPARC Dependent Features 7548.Ss Options 7549The SPARC chip family includes several successive levels, using the same core 7550instruction set, but including a few additional instructions at each level. 7551There are exceptions to this however. For details on what instructions each 7552variant supports, please see the chip's architecture reference manual. 7553.Pp 7554By default, 7555.Li as 7556assumes the core instruction set (SPARC v6), but \(lqbumps\(rq the architecture level 7557as needed: it switches to successively higher architectures as it encounters 7558instructions that only exist in the higher levels. 7559.Pp 7560If not configured for SPARC v9 ( 7561.Li sparc64-*-* ) 7562GAS will not bump passed sparclite by default, an option must be passed to 7563enable the v9 instructions. 7564.Pp 7565GAS treats sparclite as being compatible with v8, unless an architecture is 7566explicitly requested. SPARC v9 is always incompatible with sparclite. 7567.Pp 7568.Bl -tag -width Ds 7569.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite 7570.It -Av8plus | -Av8plusa | -Av9 | -Av9a 7571Use one of the 7572.Li -A 7573options to select one of the SPARC architectures explicitly. If you select 7574an architecture explicitly, 7575.Li as 7576reports a fatal error if it encounters an instruction or feature requiring 7577an incompatible or higher level. 7578.Pp 7579.Li -Av8plus 7580and 7581.Li -Av8plusa 7582select a 32 bit environment. 7583.Pp 7584.Li -Av9 7585and 7586.Li -Av9a 7587select a 64 bit environment and are not available unless GAS is explicitly 7588configured with 64 bit environment support. 7589.Pp 7590.Li -Av8plusa 7591and 7592.Li -Av9a 7593enable the SPARC V9 instruction set with UltraSPARC extensions. 7594.Pp 7595.It -xarch=v8plus | -xarch=v8plusa 7596For compatibility with the Solaris v9 assembler. These options are equivalent 7597to -Av8plus and -Av8plusa, respectively. 7598.Pp 7599.It -bump 7600Warn whenever it is necessary to switch to another level. If an architecture 7601level is explicitly requested, GAS will not issue warnings until that level 7602is reached, and will then bump the level as required (except between incompatible 7603levels). 7604.Pp 7605.It -32 | -64 7606Select the word size, either 32 bits or 64 bits. These options are only available 7607with the ELF object file format, and require that the necessary BFD support 7608has been included. 7609.El 7610.Pp 7611.Ss Enforcing aligned data 7612SPARC GAS normally permits data to be misaligned. For example, it permits 7613the 7614.Li .long 7615pseudo-op to be used on a byte boundary. However, the native SunOS and Solaris 7616assemblers issue an error when they see misaligned data. 7617.Pp 7618You can use the 7619.Li --enforce-aligned-data 7620option to make SPARC GAS also issue an error about misaligned data, just as 7621the SunOS and Solaris assemblers do. 7622.Pp 7623The 7624.Li --enforce-aligned-data 7625option is not the default because gcc issues misaligned data pseudo-ops when 7626it initializes certain packed data structures (structures defined using the 7627.Li packed 7628attribute). You may have to assemble with GAS in order to initialize packed 7629data structures in your own code. 7630.Pp 7631.Ss Floating Point 7632The Sparc uses ieee floating-point numbers. 7633.Pp 7634.Ss Sparc Machine Directives 7635The Sparc version of 7636.Li as 7637supports the following additional machine directives: 7638.Pp 7639.Bl -tag -width Ds 7640.It .align 7641This must be followed by the desired alignment in bytes. 7642.Pp 7643.It .common 7644This must be followed by a symbol name, a positive number, and 7645.Li "bss" . 7646This behaves somewhat like 7647.Li .comm , 7648but the syntax is different. 7649.Pp 7650.It .half 7651This is functionally identical to 7652.Li .short . 7653.Pp 7654.It .nword 7655On the Sparc, the 7656.Li .nword 7657directive produces native word sized value, ie. if assembling with -32 it 7658is equivalent to 7659.Li .word , 7660if assembling with -64 it is equivalent to 7661.Li .xword . 7662.Pp 7663.It .proc 7664This directive is ignored. Any text following it on the same line is also 7665ignored. 7666.Pp 7667.It .register 7668This directive declares use of a global application or system register. It 7669must be followed by a register name %g2, %g3, %g6 or %g7, comma and the symbol 7670name for that register. If symbol name is 7671.Li #scratch , 7672it is a scratch register, if it is 7673.Li #ignore , 7674it just suppresses any errors about using undeclared global register, but 7675does not emit any information about it into the object file. This can be useful 7676e.g. if you save the register before use and restore it after. 7677.Pp 7678.It .reserve 7679This must be followed by a symbol name, a positive number, and 7680.Li "bss" . 7681This behaves somewhat like 7682.Li .lcomm , 7683but the syntax is different. 7684.Pp 7685.It .seg 7686This must be followed by 7687.Li "text" , 7688.Li "data" , 7689or 7690.Li "data1" . 7691It behaves like 7692.Li .text , 7693.Li .data , 7694or 7695.Li .data 1 . 7696.Pp 7697.It .skip 7698This is functionally identical to the 7699.Li .space 7700directive. 7701.Pp 7702.It .word 7703On the Sparc, the 7704.Li .word 7705directive produces 32 bit values, instead of the 16 bit values it produces 7706on many other machines. 7707.Pp 7708.It .xword 7709On the Sparc V9 processor, the 7710.Li .xword 7711directive produces 64 bit values. 7712.El 7713.Pp 7714.Sh Reporting Bugs 7715Your bug reports play an essential role in making 7716.Xr as 7717reliable. 7718.Pp 7719Reporting a bug may help you by bringing a solution to your problem, or it 7720may not. But in any case the principal function of a bug report is to help 7721the entire community by making the next version of 7722.Xr as 7723work better. Bug reports are your contribution to the maintenance of 7724.Xr as . 7725.Pp 7726In order for a bug report to serve its purpose, you must include the information 7727that enables us to fix the bug. 7728.Pp 7729.Ss Have You Found a Bug? 7730If you are not sure whether you have found a bug, here are some guidelines: 7731.Pp 7732.Bl -bullet 7733.It 7734If the assembler gets a fatal signal, for any input whatever, that is a 7735.Xr as 7736bug. Reliable assemblers never crash. 7737.Pp 7738.It 7739If 7740.Xr as 7741produces an error message for valid input, that is a bug. 7742.Pp 7743.It 7744If 7745.Xr as 7746does not produce an error message for invalid input, that is a bug. However, 7747you should note that your idea of \(lqinvalid input\(rq might be our idea of \(lqan extension\(rq 7748or \(lqsupport for traditional practice\(rq. 7749.Pp 7750.It 7751If you are an experienced user of assemblers, your suggestions for improvement 7752of 7753.Xr as 7754are welcome in any case. 7755.El 7756.Pp 7757.Ss How to Report Bugs 7758A number of companies and individuals offer support for GNU products. If you 7759obtained 7760.Xr as 7761from a support organization, we recommend you contact that organization first. 7762.Pp 7763You can find contact information for many support companies and individuals 7764in the file 7765.Pa etc/SERVICE 7766in the GNU Emacs distribution. 7767.Pp 7768The fundamental principle of reporting bugs usefully is this: 7769.Sy report all the facts . 7770If you are not sure whether to state a fact or leave it out, state it! 7771.Pp 7772Often people omit facts because they think they know what causes the problem 7773and assume that some details do not matter. Thus, you might assume that the 7774name of a symbol you use in an example does not matter. Well, probably it 7775does not, but one cannot be sure. Perhaps the bug is a stray memory reference 7776which happens to fetch from the location where that name is stored in memory; 7777perhaps, if the name were different, the contents of that location would fool 7778the assembler into doing the right thing despite the bug. Play it safe and 7779give a specific, complete example. That is the easiest thing for you to do, 7780and the most helpful. 7781.Pp 7782Keep in mind that the purpose of a bug report is to enable us to fix the bug 7783if it is new to us. Therefore, always write your bug reports on the assumption 7784that the bug has not been reported previously. 7785.Pp 7786Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq 7787This cannot help us fix a bug, so it is basically useless. We respond by asking 7788for enough details to enable us to investigate. You might as well expedite 7789matters by sending them to begin with. 7790.Pp 7791To enable us to fix the bug, you should include all these things: 7792.Pp 7793.Bl -bullet 7794.It 7795The version of 7796.Xr as . 7797.Xr as 7798announces it if you start it with the 7799.Li --version 7800argument. 7801.Pp 7802Without this, we will not know whether there is any point in looking for the 7803bug in the current version of 7804.Xr as . 7805.Pp 7806.It 7807Any patches you may have applied to the 7808.Xr as 7809source. 7810.Pp 7811.It 7812The type of machine you are using, and the operating system name and version 7813number. 7814.Pp 7815.It 7816What compiler (and its version) was used to compile 7817.Xr as 7818---e.g. \(lq 7819.Li gcc-2.7 7820\(rq\&. 7821.Pp 7822.It 7823The command arguments you gave the assembler to assemble your example and 7824observe the bug. To guarantee you will not omit something important, list 7825them all. A copy of the Makefile (or the output from make) is sufficient. 7826.Pp 7827If we were to try to guess the arguments, we would probably guess wrong and 7828then we might not encounter the bug. 7829.Pp 7830.It 7831A complete input file that will reproduce the bug. If the bug is observed 7832when the assembler is invoked via a compiler, send the assembler source, not 7833the high level language source. Most compilers will produce the assembler 7834source when run with the 7835.Li -S 7836option. If you are using 7837.Li gcc , 7838use the options 7839.Li -v --save-temps ; 7840this will save the assembler source in a file with an extension of 7841.Pa .s , 7842and also show you exactly how 7843.Xr as 7844is being run. 7845.Pp 7846.It 7847A description of what behavior you observe that you believe is incorrect. 7848For example, \(lqIt gets a fatal signal.\(rq 7849.Pp 7850Of course, if the bug is that 7851.Xr as 7852gets a fatal signal, then we will certainly notice it. But if the bug is incorrect 7853output, we might not notice unless it is glaringly wrong. You might as well 7854not give us a chance to make a mistake. 7855.Pp 7856Even if the problem you experience is a fatal signal, you should still say 7857so explicitly. Suppose something strange is going on, such as, your copy of 7858.Xr as 7859is out of sync, or you have encountered a bug in the C library on your system. 7860(This has happened!) Your copy might crash and ours would not. If you told 7861us to expect a crash, then when ours fails to crash, we would know that the 7862bug was not happening for us. If you had not told us to expect a crash, then 7863we would not be able to draw any conclusion from our observations. 7864.Pp 7865.It 7866If you wish to suggest changes to the 7867.Xr as 7868source, send us context diffs, as generated by 7869.Li diff 7870with the 7871.Li -u , 7872.Li -c , 7873or 7874.Li -p 7875option. Always send diffs from the old file to the new file. If you even discuss 7876something in the 7877.Xr as 7878source, refer to it by context, not by line number. 7879.Pp 7880The line numbers in our development sources will not match those in your sources. 7881Your line numbers would convey no useful information to us. 7882.El 7883.Pp 7884Here are some things that are not necessary: 7885.Pp 7886.Bl -bullet 7887.It 7888A description of the envelope of the bug. 7889.Pp 7890Often people who encounter a bug spend a lot of time investigating which changes 7891to the input file will make the bug go away and which changes will not affect 7892it. 7893.Pp 7894This is often time consuming and not very useful, because the way we will 7895find the bug is by running a single example under the debugger with breakpoints, 7896not by pure deduction from a series of examples. We recommend that you save 7897your time for something else. 7898.Pp 7899Of course, if you can find a simpler example to report 7900.Em instead 7901of the original one, that is a convenience for us. Errors in the output will 7902be easier to spot, running under the debugger will take less time, and so 7903on. 7904.Pp 7905However, simplification is not vital; if you do not want to do this, report 7906the bug anyway and send us the entire test case you used. 7907.Pp 7908.It 7909A patch for the bug. 7910.Pp 7911A patch for the bug does help us if it is a good one. But do not omit the 7912necessary information, such as the test case, on the assumption that a patch 7913is all we need. We might see problems with your patch and decide to fix the 7914problem another way, or we might not understand it at all. 7915.Pp 7916Sometimes with a program as complicated as 7917.Xr as 7918it is very hard to construct an example that will make the program follow 7919a certain path through the code. If you do not send us the example, we will 7920not be able to construct one, so we will not be able to verify that the bug 7921is fixed. 7922.Pp 7923And if we cannot understand what bug you are trying to fix, or why your patch 7924should be an improvement, we will not install it. A test case will help us 7925to understand. 7926.Pp 7927.It 7928A guess about what the bug is or what it depends on. 7929.Pp 7930Such guesses are usually wrong. Even we cannot guess right about such things 7931without first using the debugger to find the facts. 7932.El 7933.Pp 7934.Sh Acknowledgements 7935If you have contributed to GAS and your name isn't listed here, it is not 7936meant as a slight. We just don't know about it. Send mail to the maintainer, 7937and we'll correct the situation. Currently the maintainer is Ken Raeburn (email 7938address 7939.Li raeburn@cyGNUs.com ) . 7940.Pp 7941Dean Elsner wrote the original GNU assembler for the VAX. 7942.Pp 7943Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug 7944information and the 68k series machines, most of the preprocessing pass, and 7945extensive changes in 7946.Pa messages.c , 7947.Pa input-file.c , 7948.Pa write.c . 7949.Pp 7950K. Richard Pixley maintained GAS for a while, adding various enhancements 7951and many bug fixes, including merging support for several processors, breaking 7952GAS up to handle multiple object file format back ends (including heavy rewrite, 7953testing, an integration of the coff and b.out back ends), adding configuration 7954including heavy testing and verification of cross assemblers and file splits 7955and renaming, converted GAS to strictly ANSI C including full prototypes, 7956added support for m680[34]0 and cpu32, did considerable work on i960 including 7957a COFF port (including considerable amounts of reverse engineering), a SPARC 7958opcode file rewrite, DECstation, rs6000, and hp300hpux host ports, updated 7959\(lqknow\(rq assertions and made them work, much other reorganization, cleanup, and 7960lint. 7961.Pp 7962Ken Raeburn wrote the high-level BFD interface code to replace most of the 7963code in format-specific I/O modules. 7964.Pp 7965The original VMS support was contributed by David L. Kashtan. Eric Youngdale 7966has done much work with it since. 7967.Pp 7968The Intel 80386 machine description was written by Eliot Dresselhaus. 7969.Pp 7970Minh Tran-Le at IntelliCorp contributed some AIX 386 support. 7971.Pp 7972The Motorola 88k machine description was contributed by Devon Bowen of Buffalo 7973University and Torbjorn Granlund of the Swedish Institute of Computer Science. 7974.Pp 7975Keith Knowles at the Open Software Foundation wrote the original MIPS back 7976end ( 7977.Pa tc-mips.c , 7978.Pa tc-mips.h ) , 7979and contributed Rose format support (which hasn't been merged in yet). Ralph 7980Campbell worked with the MIPS code to support a.out format. 7981.Pp 7982Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, tc-h8300), 7983and IEEE 695 object file format (obj-ieee), was written by Steve Chamberlain 7984of CyGNUs Support. Steve also modified the COFF back end to use BFD for some 7985low-level operations, for use with the H8/300 and AMD 29k targets. 7986.Pp 7987John Gilmore built the AMD 29000 support, added 7988.Li .include 7989support, and simplified the configuration of which versions accept which directives. 7990He updated the 68k machine description so that Motorola's opcodes always produced 7991fixed-size instructions (e.g., 7992.Li jsr ) , 7993while synthetic instructions remained shrinkable ( 7994.Li jbsr ) . 7995John fixed many bugs, including true tested cross-compilation support, and 7996one bug in relaxation that took a week and required the proverbial one-bit 7997fix. 7998.Pp 7999Ian Lance Taylor of CyGNUs Support merged the Motorola and MIT syntax for 8000the 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO 8001Unix), added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 8002and PowerPC assembler, and made a few other minor patches. 8003.Pp 8004Steve Chamberlain made GAS able to generate listings. 8005.Pp 8006Hewlett-Packard contributed support for the HP9000/300. 8007.Pp 8008Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) 8009along with a fairly extensive HPPA testsuite (for both SOM and ELF object 8010formats). This work was supported by both the Center for Software Science 8011at the University of Utah and CyGNUs Support. 8012.Pp 8013Support for ELF format files has been worked on by Mark Eichin of CyGNUs Support 8014(original, incomplete implementation for SPARC), Pete Hoogenboom and Jeff 8015Law at the University of Utah (HPPA mainly), Michael Meissner of the Open 8016Software Foundation (i386 mainly), and Ken Raeburn of CyGNUs Support (sparc, 8017and some initial 64-bit support). 8018.Pp 8019Linas Vepstas added GAS support for the ESA/390 \(lqIBM 370\(rq architecture. 8020.Pp 8021Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and 8022BFD support for openVMS/Alpha. 8023.Pp 8024Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic* 8025flavors. 8026.Pp 8027David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica, 8028Inc. added support for Xtensa processors. 8029.Pp 8030Several engineers at CyGNUs Support have also provided many small bug fixes 8031and configuration enhancements. 8032.Pp 8033Many others have contributed large or small bugfixes and enhancements. If 8034you have contributed significant work and are not mentioned on this list, 8035and want to be, let us know. Some of the history has been lost; we are not 8036intentionally leaving anyone out. 8037.Pp 8038.Sh GNU Free Documentation License 8039.Bd -filled -offset indent 8040Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, 8041Fifth Floor, Boston, MA 02110-1301 USA 8042.Pp 8043Everyone is permitted to copy and distribute verbatim copies of this license 8044document, but changing it is not allowed. 8045.Ed 8046.Pp 8047.Bl -enum 8048.It 8049PREAMBLE 8050.Pp 8051The purpose of this License is to make a manual, textbook, or other written 8052document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom 8053to copy and redistribute it, with or without modifying it, either commercially 8054or noncommercially. Secondarily, this License preserves for the author and 8055publisher a way to get credit for their work, while not being considered responsible 8056for modifications made by others. 8057.Pp 8058This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the 8059document must themselves be free in the same sense. It complements the GNU 8060General Public License, which is a copyleft license designed for free software. 8061.Pp 8062We have designed this License in order to use it for manuals for free software, 8063because free software needs free documentation: a free program should come 8064with manuals providing the same freedoms that the software does. But this 8065License is not limited to software manuals; it can be used for any textual 8066work, regardless of subject matter or whether it is published as a printed 8067book. We recommend this License principally for works whose purpose is instruction 8068or reference. 8069.Pp 8070.It 8071APPLICABILITY AND DEFINITIONS 8072.Pp 8073This License applies to any manual or other work that contains a notice placed 8074by the copyright holder saying it can be distributed under the terms of this 8075License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member 8076of the public is a licensee, and is addressed as \(lqyou.\(rq 8077.Pp 8078A \(lqModified Version\(rq of the Document means any work containing the Document 8079or a portion of it, either copied verbatim, or with modifications and/or translated 8080into another language. 8081.Pp 8082A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document 8083that deals exclusively with the relationship of the publishers or authors 8084of the Document to the Document's overall subject (or to related matters) 8085and contains nothing that could fall directly within that overall subject. 8086(For example, if the Document is in part a textbook of mathematics, a Secondary 8087Section may not explain any mathematics.) The relationship could be a matter 8088of historical connection with the subject or with related matters, or of legal, 8089commercial, philosophical, ethical or political position regarding them. 8090.Pp 8091The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, 8092as being those of Invariant Sections, in the notice that says that the Document 8093is released under this License. 8094.Pp 8095The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover 8096Texts or Back-Cover Texts, in the notice that says that the Document is released 8097under this License. 8098.Pp 8099A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented 8100in a format whose specification is available to the general public, whose 8101contents can be viewed and edited directly and straightforwardly with generic 8102text editors or (for images composed of pixels) generic paint programs or 8103(for drawings) some widely available drawing editor, and that is suitable 8104for input to text formatters or for automatic translation to a variety of 8105formats suitable for input to text formatters. A copy made in an otherwise 8106Transparent file format whose markup has been designed to thwart or discourage 8107subsequent modification by readers is not Transparent. A copy that is not 8108\(lqTransparent\(rq is called \(lqOpaque.\(rq 8109.Pp 8110Examples of suitable formats for Transparent copies include plain ASCII without 8111markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly 8112available DTD, and standard-conforming simple HTML designed for human modification. 8113Opaque formats include PostScript, PDF, proprietary formats that can be read 8114and edited only by proprietary word processors, SGML or XML for which the 8115DTD and/or processing tools are not generally available, and the machine-generated 8116HTML produced by some word processors for output purposes only. 8117.Pp 8118The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such 8119following pages as are needed to hold, legibly, the material this License 8120requires to appear in the title page. For works in formats which do not have 8121any title page as such, \(lqTitle Page\(rq means the text near the most prominent 8122appearance of the work's title, preceding the beginning of the body of the 8123text. 8124.Pp 8125.It 8126VERBATIM COPYING 8127.Pp 8128You may copy and distribute the Document in any medium, either commercially 8129or noncommercially, provided that this License, the copyright notices, and 8130the license notice saying this License applies to the Document are reproduced 8131in all copies, and that you add no other conditions whatsoever to those of 8132this License. You may not use technical measures to obstruct or control the 8133reading or further copying of the copies you make or distribute. However, 8134you may accept compensation in exchange for copies. If you distribute a large 8135enough number of copies you must also follow the conditions in section 3. 8136.Pp 8137You may also lend copies, under the same conditions stated above, and you 8138may publicly display copies. 8139.Pp 8140.It 8141COPYING IN QUANTITY 8142.Pp 8143If you publish printed copies of the Document numbering more than 100, and 8144the Document's license notice requires Cover Texts, you must enclose the copies 8145in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover 8146Texts on the front cover, and Back-Cover Texts on the back cover. Both covers 8147must also clearly and legibly identify you as the publisher of these copies. 8148The front cover must present the full title with all words of the title equally 8149prominent and visible. You may add other material on the covers in addition. 8150Copying with changes limited to the covers, as long as they preserve the title 8151of the Document and satisfy these conditions, can be treated as verbatim copying 8152in other respects. 8153.Pp 8154If the required texts for either cover are too voluminous to fit legibly, 8155you should put the first ones listed (as many as fit reasonably) on the actual 8156cover, and continue the rest onto adjacent pages. 8157.Pp 8158If you publish or distribute Opaque copies of the Document numbering more 8159than 100, you must either include a machine-readable Transparent copy along 8160with each Opaque copy, or state in or with each Opaque copy a publicly-accessible 8161computer-network location containing a complete Transparent copy of the Document, 8162free of added material, which the general network-using public has access 8163to download anonymously at no charge using public-standard network protocols. 8164If you use the latter option, you must take reasonably prudent steps, when 8165you begin distribution of Opaque copies in quantity, to ensure that this Transparent 8166copy will remain thus accessible at the stated location until at least one 8167year after the last time you distribute an Opaque copy (directly or through 8168your agents or retailers) of that edition to the public. 8169.Pp 8170It is requested, but not required, that you contact the authors of the Document 8171well before redistributing any large number of copies, to give them a chance 8172to provide you with an updated version of the Document. 8173.Pp 8174.It 8175MODIFICATIONS 8176.Pp 8177You may copy and distribute a Modified Version of the Document under the conditions 8178of sections 2 and 3 above, provided that you release the Modified Version 8179under precisely this License, with the Modified Version filling the role of 8180the Document, thus licensing distribution and modification of the Modified 8181Version to whoever possesses a copy of it. In addition, you must do these 8182things in the Modified Version: 8183.Pp 8184A. Use in the Title Page (and on the covers, if any) a title distinct from 8185that of the Document, and from those of previous versions (which should, if 8186there were any, be listed in the History section of the Document). You may 8187use the same title as a previous version if the original publisher of that 8188version gives permission. B. List on the Title Page, as authors, one or more 8189persons or entities responsible for authorship of the modifications in the 8190Modified Version, together with at least five of the principal authors of 8191the Document (all of its principal authors, if it has less than five). C. 8192State on the Title page the name of the publisher of the Modified Version, 8193as the publisher. D. Preserve all the copyright notices of the Document. 8194E. Add an appropriate copyright notice for your modifications adjacent to 8195the other copyright notices. F. Include, immediately after the copyright 8196notices, a license notice giving the public permission to use the Modified 8197Version under the terms of this License, in the form shown in the Addendum 8198below. G. Preserve in that license notice the full lists of Invariant Sections 8199and required Cover Texts given in the Document's license notice. H. Include 8200an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, 8201and its title, and add to it an item stating at least the title, year, new 8202authors, and publisher of the Modified Version as given on the Title Page. 8203If there is no section entitled \(lqHistory\(rq in the Document, create one stating 8204the title, year, authors, and publisher of the Document as given on its Title 8205Page, then add an item describing the Modified Version as stated in the previous 8206sentence. J. Preserve the network location, if any, given in the Document 8207for public access to a Transparent copy of the Document, and likewise the 8208network locations given in the Document for previous versions it was based 8209on. These may be placed in the \(lqHistory\(rq section. You may omit a network location 8210for a work that was published at least four years before the Document itself, 8211or if the original publisher of the version it refers to gives permission. 8212K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's 8213title, and preserve in the section all the substance and tone of each of the 8214contributor acknowledgements and/or dedications given therein. L. Preserve 8215all the Invariant Sections of the Document, unaltered in their text and in 8216their titles. Section numbers or the equivalent are not considered part of 8217the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section 8218may not be included in the Modified Version. N. Do not retitle any existing 8219section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. 8220.Pp 8221If the Modified Version includes new front-matter sections or appendices that 8222qualify as Secondary Sections and contain no material copied from the Document, 8223you may at your option designate some or all of these sections as invariant. 8224To do this, add their titles to the list of Invariant Sections in the Modified 8225Version's license notice. These titles must be distinct from any other section 8226titles. 8227.Pp 8228You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing 8229but endorsements of your Modified Version by various parties--for example, 8230statements of peer review or that the text has been approved by an organization 8231as the authoritative definition of a standard. 8232.Pp 8233You may add a passage of up to five words as a Front-Cover Text, and a passage 8234of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts 8235in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover 8236Text may be added by (or through arrangements made by) any one entity. If 8237the Document already includes a cover text for the same cover, previously 8238added by you or by arrangement made by the same entity you are acting on behalf 8239of, you may not add another; but you may replace the old one, on explicit 8240permission from the previous publisher that added the old one. 8241.Pp 8242The author(s) and publisher(s) of the Document do not by this License give 8243permission to use their names for publicity for or to assert or imply endorsement 8244of any Modified Version. 8245.Pp 8246.It 8247COMBINING DOCUMENTS 8248.Pp 8249You may combine the Document with other documents released under this License, 8250under the terms defined in section 4 above for modified versions, provided 8251that you include in the combination all of the Invariant Sections of all of 8252the original documents, unmodified, and list them all as Invariant Sections 8253of your combined work in its license notice. 8254.Pp 8255The combined work need only contain one copy of this License, and multiple 8256identical Invariant Sections may be replaced with a single copy. If there 8257are multiple Invariant Sections with the same name but different contents, 8258make the title of each such section unique by adding at the end of it, in 8259parentheses, the name of the original author or publisher of that section 8260if known, or else a unique number. Make the same adjustment to the section 8261titles in the list of Invariant Sections in the license notice of the combined 8262work. 8263.Pp 8264In the combination, you must combine any sections entitled \(lqHistory\(rq in the 8265various original documents, forming one section entitled \(lqHistory\(rq; likewise 8266combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled 8267\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq 8268.Pp 8269.It 8270COLLECTIONS OF DOCUMENTS 8271.Pp 8272You may make a collection consisting of the Document and other documents released 8273under this License, and replace the individual copies of this License in the 8274various documents with a single copy that is included in the collection, provided 8275that you follow the rules of this License for verbatim copying of each of 8276the documents in all other respects. 8277.Pp 8278You may extract a single document from such a collection, and distribute it 8279individually under this License, provided you insert a copy of this License 8280into the extracted document, and follow this License in all other respects 8281regarding verbatim copying of that document. 8282.Pp 8283.It 8284AGGREGATION WITH INDEPENDENT WORKS 8285.Pp 8286A compilation of the Document or its derivatives with other separate and independent 8287documents or works, in or on a volume of a storage or distribution medium, 8288does not as a whole count as a Modified Version of the Document, provided 8289no compilation copyright is claimed for the compilation. Such a compilation 8290is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained 8291works thus compiled with the Document, on account of their being thus compiled, 8292if they are not themselves derivative works of the Document. 8293.Pp 8294If the Cover Text requirement of section 3 is applicable to these copies of 8295the Document, then if the Document is less than one quarter of the entire 8296aggregate, the Document's Cover Texts may be placed on covers that surround 8297only the Document within the aggregate. Otherwise they must appear on covers 8298around the whole aggregate. 8299.Pp 8300.It 8301TRANSLATION 8302.Pp 8303Translation is considered a kind of modification, so you may distribute translations 8304of the Document under the terms of section 4. Replacing Invariant Sections 8305with translations requires special permission from their copyright holders, 8306but you may include translations of some or all Invariant Sections in addition 8307to the original versions of these Invariant Sections. You may include a translation 8308of this License provided that you also include the original English version 8309of this License. In case of a disagreement between the translation and the 8310original English version of this License, the original English version will 8311prevail. 8312.Pp 8313.It 8314TERMINATION 8315.Pp 8316You may not copy, modify, sublicense, or distribute the Document except as 8317expressly provided for under this License. Any other attempt to copy, modify, 8318sublicense or distribute the Document is void, and will automatically terminate 8319your rights under this License. However, parties who have received copies, 8320or rights, from you under this License will not have their licenses terminated 8321so long as such parties remain in full compliance. 8322.Pp 8323.It 8324FUTURE REVISIONS OF THIS LICENSE 8325.Pp 8326The Free Software Foundation may publish new, revised versions of the GNU 8327Free Documentation License from time to time. Such new versions will be similar 8328in spirit to the present version, but may differ in detail to address new 8329problems or concerns. See http://www.gnu.org/copyleft/. 8330.Pp 8331Each version of the License is given a distinguishing version number. If the 8332Document specifies that a particular numbered version of this License \(lqor any 8333later version\(rq applies to it, you have the option of following the terms and 8334conditions either of that specified version or of any later version that has 8335been published (not as a draft) by the Free Software Foundation. If the Document 8336does not specify a version number of this License, you may choose any version 8337ever published (not as a draft) by the Free Software Foundation. 8338.Pp 8339.El 8340.Ss ADDENDUM: How to use this License for your documents 8341To use this License in a document you have written, include a copy of the 8342License in the document and put the following copyright and license notices 8343just after the title page: 8344.Pp 8345.Bd -literal -offset indent 8346 8347Copyright (C) year your name. 8348Permission is granted to copy, distribute and/or modify this document 8349under the terms of the GNU Free Documentation License, Version 1.1 8350or any later version published by the Free Software Foundation; 8351with the Invariant Sections being list their titles, with the 8352Front-Cover Texts being list, and with the Back-Cover Texts being list. 8353A copy of the license is included in the section entitled "GNU 8354Free Documentation License." 8355 8356.Ed 8357.Pp 8358If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead 8359of saying which ones are invariant. If you have no Front-Cover Texts, write 8360\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being 8361.Va list 8362\(rq; likewise for Back-Cover Texts. 8363.Pp 8364If your document contains nontrivial examples of program code, we recommend 8365releasing these examples in parallel under your choice of free software license, 8366such as the GNU General Public License, to permit their use in free software. 8367.Pp 8368.Sh AS Index 8369