1279528Sbapt.Dd 2015-03-02 2279528Sbapt.Dt AS 7 3279528Sbapt.Os 4279528Sbapt.Sh NAME 5279528Sbapt.Nm as 6279528Sbapt.Nd Using as (machine specific) 7279528Sbapt.Sh Using as 8279528SbaptThis file is a user guide to the GNU assembler 9279528Sbapt.Xr as 10279528Sbaptversion "2.17.50 [FreeBSD] 2007-07-03". This version of the file describes 11279528Sbapt.Xr as 12279528Sbaptconfigured to generate code for machine specific architectures. 13279528Sbapt.Pp 14279528SbaptThis document is distributed under the terms of the GNU Free Documentation 15279528SbaptLicense. A copy of the license is included in the section entitled \(lqGNU Free 16279528SbaptDocumentation License\(rq. 17279528Sbapt.Pp 18279528Sbapt.Sh Overview 19279528SbaptHere is a brief summary of how to invoke 20279528Sbapt.Xr as . 21279528SbaptFor details, see Invoking,,Command-Line Options. 22279528Sbapt.Pp 23279528Sbapt.Bd -literal -offset indent 24279528Sbaptas [-a[cdhlns][=file]] [--alternate] [-D] 25279528Sbapt [--defsym sym=val] [-f] [-g] [--gstabs] 26279528Sbapt [--gstabs+] [--gdwarf-2] [--help] [-I dir] [-J] 27279528Sbapt [-K] [-L] [--listing-lhs-width=NUM] 28279528Sbapt [--listing-lhs-width2=NUM] [--listing-rhs-width=NUM] 29279528Sbapt [--listing-cont-lines=NUM] [--keep-locals] [-o 30279528Sbapt objfile] [-R] [--reduce-memory-overheads] [--statistics] 31279528Sbapt [-v] [-version] [--version] [-W] [--warn] 32279528Sbapt [--fatal-warnings] [-w] [-x] [-Z] [@FILE] 33279528Sbapt [--target-help] [target-options] 34279528Sbapt [--|files ...] 35279528Sbapt 36279528SbaptTarget ARM options: 37279528Sbapt [-mcpu=processor[+extension...]] 38279528Sbapt [-march=architecture[+extension...]] 39279528Sbapt [-mfpu=floating-point-format] 40279528Sbapt [-mfloat-abi=abi] 41279528Sbapt [-meabi=ver] 42279528Sbapt [-mthumb] 43279528Sbapt [-EB|-EL] 44279528Sbapt [-mapcs-32|-mapcs-26|-mapcs-float| 45279528Sbapt -mapcs-reentrant] 46279528Sbapt [-mthumb-interwork] [-k] 47279528Sbapt 48279528Sbapt 49279528SbaptTarget i386 options: 50279528Sbapt [--32|--64] [-n] 51279528Sbapt [-march=CPU] [-mtune=CPU] 52279528Sbapt 53279528Sbapt 54279528SbaptTarget IA-64 options: 55279528Sbapt [-mconstant-gp|-mauto-pic] 56279528Sbapt [-milp32|-milp64|-mlp64|-mp64] 57279528Sbapt [-mle|mbe] 58279528Sbapt [-mtune=itanium1|-mtune=itanium2] 59279528Sbapt [-munwind-check=warning|-munwind-check=error] 60279528Sbapt [-mhint.b=ok|-mhint.b=warning|-mhint.b=error] 61279528Sbapt [-x|-xexplicit] [-xauto] [-xdebug] 62279528Sbapt 63279528Sbapt 64279528SbaptTarget MIPS options: 65279528Sbapt [-nocpp] [-EL] [-EB] [-O[optimization level]] 66279528Sbapt [-g[debug level]] [-G num] [-KPIC] [-call_shared] 67279528Sbapt [-non_shared] [-xgot [-mvxworks-pic] 68279528Sbapt [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32] 69279528Sbapt [-march=CPU] [-mtune=CPU] [-mips1] [-mips2] 70279528Sbapt [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2] 71279528Sbapt [-mips64] [-mips64r2] 72279528Sbapt [-construct-floats] [-no-construct-floats] 73279528Sbapt [-trap] [-no-break] [-break] [-no-trap] 74279528Sbapt [-mfix7000] [-mno-fix7000] 75279528Sbapt [-mips16] [-no-mips16] 76279528Sbapt [-msmartmips] [-mno-smartmips] 77279528Sbapt [-mips3d] [-no-mips3d] 78279528Sbapt [-mdmx] [-no-mdmx] 79279528Sbapt [-mdsp] [-mno-dsp] 80279528Sbapt [-mdspr2] [-mno-dspr2] 81279528Sbapt [-mmt] [-mno-mt] 82279528Sbapt [-mdebug] [-no-mdebug] 83279528Sbapt [-mpdr] [-mno-pdr] 84279528Sbapt 85279528Sbapt 86279528SbaptTarget PowerPC options: 87279528Sbapt [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604| 88279528Sbapt -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke| 89279528Sbapt -mbooke32|-mbooke64] 90279528Sbapt [-mcom|-many|-maltivec] [-memb] 91279528Sbapt [-mregnames|-mno-regnames] 92279528Sbapt [-mrelocatable|-mrelocatable-lib] 93279528Sbapt [-mlittle|-mlittle-endian|-mbig|-mbig-endian] 94279528Sbapt [-msolaris|-mno-solaris] 95279528Sbapt 96279528Sbapt 97279528SbaptTarget SPARC options: 98279528Sbapt [-Av6|-Av7|-Av8|-Asparclet|-Asparclite 99279528Sbapt -Av8plus|-Av8plusa|-Av9|-Av9a] 100279528Sbapt [-xarch=v8plus|-xarch=v8plusa] [-bump] 101279528Sbapt [-32|-64] 102279528Sbapt 103279528Sbapt 104279528Sbapt 105279528Sbapt.Ed 106279528Sbapt.Pp 107279528Sbapt.Bl -tag -width Ds 108279528Sbapt.It @ Va file 109279528SbaptRead command-line options from 110279528Sbapt.Va file . 111279528SbaptThe options read are inserted in place of the original @ 112279528Sbapt.Va file 113279528Sbaptoption. If 114279528Sbapt.Va file 115279528Sbaptdoes not exist, or cannot be read, then the option will be treated literally, 116279528Sbaptand not removed. 117279528Sbapt.Pp 118279528SbaptOptions in 119279528Sbapt.Va file 120279528Sbaptare separated by whitespace. A whitespace character may be included in an 121279528Sbaptoption by surrounding the entire option in either single or double quotes. 122279528SbaptAny character (including a backslash) may be included by prefixing the character 123279528Sbaptto be included with a backslash. The 124279528Sbapt.Va file 125279528Sbaptmay itself contain additional @ 126279528Sbapt.Va file 127279528Sbaptoptions; any such options will be processed recursively. 128279528Sbapt.Pp 129279528Sbapt.It -a[cdhlmns] 130279528SbaptTurn on listings, in any of a variety of ways: 131279528Sbapt.Pp 132279528Sbapt.Bl -tag -width Ds 133279528Sbapt.It -ac 134279528Sbaptomit false conditionals 135279528Sbapt.Pp 136279528Sbapt.It -ad 137279528Sbaptomit debugging directives 138279528Sbapt.Pp 139279528Sbapt.It -ah 140279528Sbaptinclude high-level source 141279528Sbapt.Pp 142279528Sbapt.It -al 143279528Sbaptinclude assembly 144279528Sbapt.Pp 145279528Sbapt.It -am 146279528Sbaptinclude macro expansions 147279528Sbapt.Pp 148279528Sbapt.It -an 149279528Sbaptomit forms processing 150279528Sbapt.Pp 151279528Sbapt.It -as 152279528Sbaptinclude symbols 153279528Sbapt.Pp 154279528Sbapt.It =file 155279528Sbaptset the name of the listing file 156279528Sbapt.El 157279528Sbapt.Pp 158279528SbaptYou may combine these options; for example, use 159279528Sbapt.Li -aln 160279528Sbaptfor assembly listing without forms processing. The 161279528Sbapt.Li =file 162279528Sbaptoption, if used, must be the last one. By itself, 163279528Sbapt.Li -a 164279528Sbaptdefaults to 165279528Sbapt.Li -ahls . 166279528Sbapt.Pp 167279528Sbapt.It --alternate 168279528SbaptBegin in alternate macro mode.See Section 169279528Sbapt.Dq Altmacro . 170279528Sbapt.Pp 171279528Sbapt.It -D 172279528SbaptIgnored. This option is accepted for script compatibility with calls to other 173279528Sbaptassemblers. 174279528Sbapt.Pp 175279528Sbapt.It --defsym Va sym= Va value 176279528SbaptDefine the symbol 177279528Sbapt.Va sym 178279528Sbaptto be 179279528Sbapt.Va value 180279528Sbaptbefore assembling the input file. 181279528Sbapt.Va value 182279528Sbaptmust be an integer constant. As in C, a leading 183279528Sbapt.Li 0x 184279528Sbaptindicates a hexadecimal value, and a leading 185279528Sbapt.Li 0 186279528Sbaptindicates an octal value. The value of the symbol can be overridden inside 187279528Sbapta source file via the use of a 188279528Sbapt.Li .set 189279528Sbaptpseudo-op. 190279528Sbapt.Pp 191279528Sbapt.It -f 192279528Sbapt\(lqfast\(rq---skip whitespace and comment preprocessing (assume source is compiler 193279528Sbaptoutput). 194279528Sbapt.Pp 195279528Sbapt.It -g 196279528Sbapt.It --gen-debug 197279528SbaptGenerate debugging information for each assembler source line using whichever 198279528Sbaptdebug format is preferred by the target. This currently means either STABS, 199279528SbaptECOFF or DWARF2. 200279528Sbapt.Pp 201279528Sbapt.It --gstabs 202279528SbaptGenerate stabs debugging information for each assembler line. This may help 203279528Sbaptdebugging assembler code, if the debugger can handle it. 204279528Sbapt.Pp 205279528Sbapt.It --gstabs+ 206279528SbaptGenerate stabs debugging information for each assembler line, with GNU extensions 207279528Sbaptthat probably only gdb can handle, and that could make other debuggers crash 208279528Sbaptor refuse to read your program. This may help debugging assembler code. Currently 209279528Sbaptthe only GNU extension is the location of the current working directory at 210279528Sbaptassembling time. 211279528Sbapt.Pp 212279528Sbapt.It --gdwarf-2 213279528SbaptGenerate DWARF2 debugging information for each assembler line. This may help 214279528Sbaptdebugging assembler code, if the debugger can handle it. Note---this option 215279528Sbaptis only supported by some targets, not all of them. 216279528Sbapt.Pp 217279528Sbapt.It --help 218279528SbaptPrint a summary of the command line options and exit. 219279528Sbapt.Pp 220279528Sbapt.It --target-help 221279528SbaptPrint a summary of all target specific options and exit. 222279528Sbapt.Pp 223279528Sbapt.It -I Va dir 224279528SbaptAdd directory 225279528Sbapt.Va dir 226279528Sbaptto the search list for 227279528Sbapt.Li .include 228279528Sbaptdirectives. 229279528Sbapt.Pp 230279528Sbapt.It -J 231279528SbaptDon't warn about signed overflow. 232279528Sbapt.Pp 233279528Sbapt.It -K 234279528SbaptThis option is accepted but has no effect on the machine specific family. 235279528Sbapt.Pp 236279528Sbapt.It -L 237279528Sbapt.It --keep-locals 238279528SbaptKeep (in the symbol table) local symbols. These symbols start with system-specific 239279528Sbaptlocal label prefixes, typically 240279528Sbapt.Li .L 241279528Sbaptfor ELF systems or 242279528Sbapt.Li L 243279528Sbaptfor traditional a.out systems.See Section 244279528Sbapt.Dq Symbol Names . 245279528Sbapt.Pp 246279528Sbapt.It --listing-lhs-width= Va number 247279528SbaptSet the maximum width, in words, of the output data column for an assembler 248279528Sbaptlisting to 249279528Sbapt.Va number . 250279528Sbapt.Pp 251279528Sbapt.It --listing-lhs-width2= Va number 252279528SbaptSet the maximum width, in words, of the output data column for continuation 253279528Sbaptlines in an assembler listing to 254279528Sbapt.Va number . 255279528Sbapt.Pp 256279528Sbapt.It --listing-rhs-width= Va number 257279528SbaptSet the maximum width of an input source line, as displayed in a listing, 258279528Sbaptto 259279528Sbapt.Va number 260279528Sbaptbytes. 261279528Sbapt.Pp 262279528Sbapt.It --listing-cont-lines= Va number 263279528SbaptSet the maximum number of lines printed in a listing for a single line of 264279528Sbaptinput to 265279528Sbapt.Va number 266279528Sbapt+ 1. 267279528Sbapt.Pp 268279528Sbapt.It -o Va objfile 269279528SbaptName the object-file output from 270279528Sbapt.Xr as 271279528Sbapt.Va objfile . 272279528Sbapt.Pp 273279528Sbapt.It -R 274279528SbaptFold the data section into the text section. 275279528Sbapt.Pp 276279528SbaptSet the default size of GAS's hash tables to a prime number close to 277279528Sbapt.Va number . 278279528SbaptIncreasing this value can reduce the length of time it takes the assembler 279279528Sbaptto perform its tasks, at the expense of increasing the assembler's memory 280279528Sbaptrequirements. Similarly reducing this value can reduce the memory requirements 281279528Sbaptat the expense of speed. 282279528Sbapt.Pp 283279528Sbapt.It --reduce-memory-overheads 284279528SbaptThis option reduces GAS's memory requirements, at the expense of making the 285279528Sbaptassembly processes slower. Currently this switch is a synonym for 286279528Sbapt.Li --hash-size=4051 , 287279528Sbaptbut in the future it may have other effects as well. 288279528Sbapt.Pp 289279528Sbapt.It --statistics 290279528SbaptPrint the maximum space (in bytes) and total time (in seconds) used by assembly. 291279528Sbapt.Pp 292279528Sbapt.It --strip-local-absolute 293279528SbaptRemove local absolute symbols from the outgoing symbol table. 294279528Sbapt.Pp 295279528Sbapt.It -v 296279528Sbapt.It -version 297279528SbaptPrint the 298279528Sbapt.Xr as 299279528Sbaptversion. 300279528Sbapt.Pp 301279528Sbapt.It --version 302279528SbaptPrint the 303279528Sbapt.Xr as 304279528Sbaptversion and exit. 305279528Sbapt.Pp 306279528Sbapt.It -W 307279528Sbapt.It --no-warn 308279528SbaptSuppress warning messages. 309279528Sbapt.Pp 310279528Sbapt.It --fatal-warnings 311279528SbaptTreat warnings as errors. 312279528Sbapt.Pp 313279528Sbapt.It --warn 314279528SbaptDon't suppress warning messages or treat them as errors. 315279528Sbapt.Pp 316279528Sbapt.It -w 317279528SbaptIgnored. 318279528Sbapt.Pp 319279528Sbapt.It -x 320279528SbaptIgnored. 321279528Sbapt.Pp 322279528Sbapt.It -Z 323279528SbaptGenerate an object file even after errors. 324279528Sbapt.Pp 325279528Sbapt.It -- | Va files ... 326279528SbaptStandard input, or source files to assemble. 327279528Sbapt.Pp 328279528Sbapt.El 329279528SbaptThe following options are available when as is configured for the ARM processor 330279528Sbaptfamily. 331279528Sbapt.Pp 332279528Sbapt.Bl -tag -width Ds 333279528Sbapt.It -mcpu= Va processor[+ Va extension...] 334279528SbaptSpecify which ARM processor variant is the target. 335279528Sbapt.It -march= Va architecture[+ Va extension...] 336279528SbaptSpecify which ARM architecture variant is used by the target. 337279528Sbapt.It -mfpu= Va floating-point-format 338279528SbaptSelect which Floating Point architecture is the target. 339279528Sbapt.It -mfloat-abi= Va abi 340279528SbaptSelect which floating point ABI is in use. 341279528Sbapt.It -mthumb 342279528SbaptEnable Thumb only instruction decoding. 343279528Sbapt.It -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant 344279528SbaptSelect which procedure calling convention is in use. 345279528Sbapt.It -EB | -EL 346279528SbaptSelect either big-endian (-EB) or little-endian (-EL) output. 347279528Sbapt.It -mthumb-interwork 348279528SbaptSpecify that the code has been generated with interworking between Thumb and 349279528SbaptARM code in mind. 350279528Sbapt.It -k 351279528SbaptSpecify that PIC code has been generated. 352279528Sbapt.El 353279528Sbapt.Pp 354279528SbaptThe following options are available when 355279528Sbapt.Xr as 356279528Sbaptis configured for the SPARC architecture: 357279528Sbapt.Pp 358279528Sbapt.Bl -tag -width Ds 359279528Sbapt.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite 360279528Sbapt.It -Av8plus | -Av8plusa | -Av9 | -Av9a 361279528SbaptExplicitly select a variant of the SPARC architecture. 362279528Sbapt.Pp 363279528Sbapt.Li -Av8plus 364279528Sbaptand 365279528Sbapt.Li -Av8plusa 366279528Sbaptselect a 32 bit environment. 367279528Sbapt.Li -Av9 368279528Sbaptand 369279528Sbapt.Li -Av9a 370279528Sbaptselect a 64 bit environment. 371279528Sbapt.Pp 372279528Sbapt.Li -Av8plusa 373279528Sbaptand 374279528Sbapt.Li -Av9a 375279528Sbaptenable the SPARC V9 instruction set with UltraSPARC extensions. 376279528Sbapt.Pp 377279528Sbapt.It -xarch=v8plus | -xarch=v8plusa 378279528SbaptFor compatibility with the Solaris v9 assembler. These options are equivalent 379279528Sbaptto -Av8plus and -Av8plusa, respectively. 380279528Sbapt.Pp 381279528Sbapt.It -bump 382279528SbaptWarn when the assembler switches to another architecture. 383279528Sbapt.El 384279528Sbapt.Pp 385279528SbaptThe following options are available when as is configured for a mips processor. 386279528Sbapt.Pp 387279528Sbapt.Bl -tag -width Ds 388279528Sbapt.It -G Va num 389279528SbaptThis option sets the largest size of an object that can be referenced implicitly 390279528Sbaptwith the 391279528Sbapt.Li gp 392279528Sbaptregister. It is only accepted for targets that use ECOFF format, such as a 393279528SbaptDECstation running Ultrix. The default value is 8. 394279528Sbapt.Pp 395279528Sbapt.It -EB 396279528SbaptGenerate \(lqbig endian\(rq format output. 397279528Sbapt.Pp 398279528Sbapt.It -EL 399279528SbaptGenerate \(lqlittle endian\(rq format output. 400279528Sbapt.Pp 401279528Sbapt.It -mips1 402279528Sbapt.It -mips2 403279528Sbapt.It -mips3 404279528Sbapt.It -mips4 405279528Sbapt.It -mips5 406279528Sbapt.It -mips32 407279528Sbapt.It -mips32r2 408279528Sbapt.It -mips64 409279528Sbapt.It -mips64r2 410279528SbaptGenerate code for a particular mips Instruction Set Architecture level. 411279528Sbapt.Li -mips1 412279528Sbaptis an alias for 413279528Sbapt.Li -march=r3000 , 414279528Sbapt.Li -mips2 415279528Sbaptis an alias for 416279528Sbapt.Li -march=r6000 , 417279528Sbapt.Li -mips3 418279528Sbaptis an alias for 419279528Sbapt.Li -march=r4000 420279528Sbaptand 421279528Sbapt.Li -mips4 422279528Sbaptis an alias for 423279528Sbapt.Li -march=r8000 . 424279528Sbapt.Li -mips5 , 425279528Sbapt.Li -mips32 , 426279528Sbapt.Li -mips32r2 , 427279528Sbapt.Li -mips64 , 428279528Sbaptand 429279528Sbapt.Li -mips64r2 430279528Sbaptcorrespond to generic 431279528Sbapt.Li MIPS V , 432279528Sbapt.Li MIPS32 , 433279528Sbapt.Li MIPS32 Release 2 , 434279528Sbapt.Li MIPS64 , 435279528Sbaptand 436279528Sbapt.Li MIPS64 Release 2 437279528SbaptISA processors, respectively. 438279528Sbapt.Pp 439279528Sbapt.It -march= Va CPU 440279528SbaptGenerate code for a particular mips cpu. 441279528Sbapt.Pp 442279528Sbapt.It -mtune= Va cpu 443279528SbaptSchedule and tune for a particular mips cpu. 444279528Sbapt.Pp 445279528Sbapt.It -mfix7000 446279528Sbapt.It -mno-fix7000 447279528SbaptCause nops to be inserted if the read of the destination register of an mfhi 448279528Sbaptor mflo instruction occurs in the following two instructions. 449279528Sbapt.Pp 450279528Sbapt.It -mdebug 451279528Sbapt.It -no-mdebug 452279528SbaptCause stabs-style debugging output to go into an ECOFF-style .mdebug section 453279528Sbaptinstead of the standard ELF .stabs sections. 454279528Sbapt.Pp 455279528Sbapt.It -mpdr 456279528Sbapt.It -mno-pdr 457279528SbaptControl generation of 458279528Sbapt.Li .pdr 459279528Sbaptsections. 460279528Sbapt.Pp 461279528Sbapt.It -mgp32 462279528Sbapt.It -mfp32 463279528SbaptThe register sizes are normally inferred from the ISA and ABI, but these flags 464279528Sbaptforce a certain group of registers to be treated as 32 bits wide at all times. 465279528Sbapt.Li -mgp32 466279528Sbaptcontrols the size of general-purpose registers and 467279528Sbapt.Li -mfp32 468279528Sbaptcontrols the size of floating-point registers. 469279528Sbapt.Pp 470279528Sbapt.It -mips16 471279528Sbapt.It -no-mips16 472279528SbaptGenerate code for the MIPS 16 processor. This is equivalent to putting 473279528Sbapt.Li .set mips16 474279528Sbaptat the start of the assembly file. 475279528Sbapt.Li -no-mips16 476279528Sbaptturns off this option. 477279528Sbapt.Pp 478279528Sbapt.It -msmartmips 479279528Sbapt.It -mno-smartmips 480279528SbaptEnables the SmartMIPS extension to the MIPS32 instruction set. This is equivalent 481279528Sbaptto putting 482279528Sbapt.Li .set smartmips 483279528Sbaptat the start of the assembly file. 484279528Sbapt.Li -mno-smartmips 485279528Sbaptturns off this option. 486279528Sbapt.Pp 487279528Sbapt.It -mips3d 488279528Sbapt.It -no-mips3d 489279528SbaptGenerate code for the MIPS-3D Application Specific Extension. This tells the 490279528Sbaptassembler to accept MIPS-3D instructions. 491279528Sbapt.Li -no-mips3d 492279528Sbaptturns off this option. 493279528Sbapt.Pp 494279528Sbapt.It -mdmx 495279528Sbapt.It -no-mdmx 496279528SbaptGenerate code for the MDMX Application Specific Extension. This tells the 497279528Sbaptassembler to accept MDMX instructions. 498279528Sbapt.Li -no-mdmx 499279528Sbaptturns off this option. 500279528Sbapt.Pp 501279528Sbapt.It -mdsp 502279528Sbapt.It -mno-dsp 503279528SbaptGenerate code for the DSP Release 1 Application Specific Extension. This tells 504279528Sbaptthe assembler to accept DSP Release 1 instructions. 505279528Sbapt.Li -mno-dsp 506279528Sbaptturns off this option. 507279528Sbapt.Pp 508279528Sbapt.It -mdspr2 509279528Sbapt.It -mno-dspr2 510279528SbaptGenerate code for the DSP Release 2 Application Specific Extension. This option 511279528Sbaptimplies -mdsp. This tells the assembler to accept DSP Release 2 instructions. 512279528Sbapt.Li -mno-dspr2 513279528Sbaptturns off this option. 514279528Sbapt.Pp 515279528Sbapt.It -mmt 516279528Sbapt.It -mno-mt 517279528SbaptGenerate code for the MT Application Specific Extension. This tells the assembler 518279528Sbaptto accept MT instructions. 519279528Sbapt.Li -mno-mt 520279528Sbaptturns off this option. 521279528Sbapt.Pp 522279528Sbapt.It --construct-floats 523279528Sbapt.It --no-construct-floats 524279528SbaptThe 525279528Sbapt.Li --no-construct-floats 526279528Sbaptoption disables the construction of double width floating point constants 527279528Sbaptby loading the two halves of the value into the two single width floating 528279528Sbaptpoint registers that make up the double width register. By default 529279528Sbapt.Li --construct-floats 530279528Sbaptis selected, allowing construction of these floating point constants. 531279528Sbapt.Pp 532279528Sbapt.It --emulation= Va name 533279528SbaptThis option causes 534279528Sbapt.Xr as 535279528Sbaptto emulate 536279528Sbapt.Xr as 537279528Sbaptconfigured for some other target, in all respects, including output format 538279528Sbapt(choosing between ELF and ECOFF only), handling of pseudo-opcodes which may 539279528Sbaptgenerate debugging information or store symbol table information, and default 540279528Sbaptendianness. The available configuration names are: 541279528Sbapt.Li mipsecoff , 542279528Sbapt.Li mipself , 543279528Sbapt.Li mipslecoff , 544279528Sbapt.Li mipsbecoff , 545279528Sbapt.Li mipslelf , 546279528Sbapt.Li mipsbelf . 547279528SbaptThe first two do not alter the default endianness from that of the primary 548279528Sbapttarget for which the assembler was configured; the others change the default 549279528Sbaptto little- or big-endian as indicated by the 550279528Sbapt.Li b 551279528Sbaptor 552279528Sbapt.Li l 553279528Sbaptin the name. Using 554279528Sbapt.Li -EB 555279528Sbaptor 556279528Sbapt.Li -EL 557279528Sbaptwill override the endianness selection in any case. 558279528Sbapt.Pp 559279528SbaptThis option is currently supported only when the primary target 560279528Sbapt.Xr as 561279528Sbaptis configured for is a mips ELF or ECOFF target. Furthermore, the primary 562279528Sbapttarget or others specified with 563279528Sbapt.Li --enable-targets=... 564279528Sbaptat configuration time must include support for the other format, if both are 565279528Sbaptto be available. For example, the Irix 5 configuration includes support for 566279528Sbaptboth. 567279528Sbapt.Pp 568279528SbaptEventually, this option will support more configurations, with more fine-grained 569279528Sbaptcontrol over the assembler's behavior, and will be supported for more processors. 570279528Sbapt.Pp 571279528Sbapt.It -nocpp 572279528Sbapt.Xr as 573279528Sbaptignores this option. It is accepted for compatibility with the native tools. 574279528Sbapt.Pp 575279528Sbapt.It --trap 576279528Sbapt.It --no-trap 577279528Sbapt.It --break 578279528Sbapt.It --no-break 579279528SbaptControl how to deal with multiplication overflow and division by zero. 580279528Sbapt.Li --trap 581279528Sbaptor 582279528Sbapt.Li --no-break 583279528Sbapt(which are synonyms) take a trap exception (and only work for Instruction 584279528SbaptSet Architecture level 2 and higher); 585279528Sbapt.Li --break 586279528Sbaptor 587279528Sbapt.Li --no-trap 588279528Sbapt(also synonyms, and the default) take a break exception. 589279528Sbapt.Pp 590279528Sbapt.It -n 591279528SbaptWhen this option is used, 592279528Sbapt.Xr as 593279528Sbaptwill issue a warning every time it generates a nop instruction from a macro. 594279528Sbapt.El 595279528Sbapt.Pp 596279528Sbapt.Ss Structure of this Manual 597279528SbaptThis manual is intended to describe what you need to know to use GNU 598279528Sbapt.Xr as . 599279528SbaptWe cover the syntax expected in source files, including notation for symbols, 600279528Sbaptconstants, and expressions; the directives that 601279528Sbapt.Xr as 602279528Sbaptunderstands; and of course how to invoke 603279528Sbapt.Xr as . 604279528Sbapt.Pp 605279528SbaptWe also cover special features in the machine specific configuration of 606279528Sbapt.Xr as , 607279528Sbaptincluding assembler directives. 608279528Sbapt.Pp 609279528SbaptOn the other hand, this manual is 610279528Sbapt.Em not 611279528Sbaptintended as an introduction to programming in assembly language---let alone 612279528Sbaptprogramming in general! In a similar vein, we make no attempt to introduce 613279528Sbaptthe machine architecture; we do 614279528Sbapt.Em not 615279528Sbaptdescribe the instruction set, standard mnemonics, registers or addressing 616279528Sbaptmodes that are standard to a particular architecture. 617279528Sbapt.Pp 618279528Sbapt.Ss The GNU Assembler 619279528SbaptGNU 620279528Sbapt.Xr as 621279528Sbaptis really a family of assemblers. This manual describes 622279528Sbapt.Xr as , 623279528Sbapta member of that family which is configured for the machine specific architectures. 624279528SbaptIf you use (or have used) the GNU assembler on one architecture, you should 625279528Sbaptfind a fairly similar environment when you use it on another architecture. 626279528SbaptEach version has much in common with the others, including object file formats, 627279528Sbaptmost assembler directives (often called 628279528Sbapt.Em pseudo-ops ) 629279528Sbaptand assembler syntax. 630279528Sbapt.Pp 631279528Sbapt.Xr as 632279528Sbaptis primarily intended to assemble the output of the GNU C compiler 633279528Sbapt.Li gcc 634279528Sbaptfor use by the linker 635279528Sbapt.Li ld . 636279528SbaptNevertheless, we've tried to make 637279528Sbapt.Xr as 638279528Sbaptassemble correctly everything that other assemblers for the same machine would 639279528Sbaptassemble. 640279528Sbapt.Pp 641279528SbaptUnlike older assemblers, 642279528Sbapt.Xr as 643279528Sbaptis designed to assemble a source program in one pass of the source file. This 644279528Sbapthas a subtle impact on the 645279528Sbapt.Li .org 646279528Sbaptdirective (see Section 647279528Sbapt.Dq Org ) . 648279528Sbapt.Pp 649279528Sbapt.Ss Object File Formats 650279528SbaptThe GNU assembler can be configured to produce several alternative object 651279528Sbaptfile formats. For the most part, this does not affect how you write assembly 652279528Sbaptlanguage programs; but directives for debugging symbols are typically different 653279528Sbaptin different file formats.See Section 654279528Sbapt.Dq Symbol Attributes . 655279528SbaptFor the machine specific target, 656279528Sbapt.Xr as 657279528Sbaptis configured to produce ELF format object files. 658279528Sbapt.Pp 659279528Sbapt.Ss Command Line 660279528SbaptAfter the program name 661279528Sbapt.Xr as , 662279528Sbaptthe command line may contain options and file names. Options may appear in 663279528Sbaptany order, and may be before, after, or between file names. The order of file 664279528Sbaptnames is significant. 665279528Sbapt.Pp 666279528Sbapt.Pa -- 667279528Sbapt(two hyphens) by itself names the standard input file explicitly, as one of 668279528Sbaptthe files for 669279528Sbapt.Xr as 670279528Sbaptto assemble. 671279528Sbapt.Pp 672279528SbaptExcept for 673279528Sbapt.Li -- 674279528Sbaptany command line argument that begins with a hyphen ( 675279528Sbapt.Li - ) 676279528Sbaptis an option. Each option changes the behavior of 677279528Sbapt.Xr as . 678279528SbaptNo option changes the way another option works. An option is a 679279528Sbapt.Li - 680279528Sbaptfollowed by one or more letters; the case of the letter is important. All 681279528Sbaptoptions are optional. 682279528Sbapt.Pp 683279528SbaptSome options expect exactly one file name to follow them. The file name may 684279528Sbapteither immediately follow the option's letter (compatible with older assemblers) 685279528Sbaptor it may be the next command argument (GNU standard). These two command lines 686279528Sbaptare equivalent: 687279528Sbapt.Pp 688279528Sbapt.Bd -literal -offset indent 689279528Sbaptas -o my-object-file.o mumble.s 690279528Sbaptas -omy-object-file.o mumble.s 691279528Sbapt.Ed 692279528Sbapt.Pp 693279528Sbapt.Ss Input Files 694279528SbaptWe use the phrase 695279528Sbapt.Em source program , 696279528Sbaptabbreviated 697279528Sbapt.Em source , 698279528Sbaptto describe the program input to one run of 699279528Sbapt.Xr as . 700279528SbaptThe program may be in one or more files; how the source is partitioned into 701279528Sbaptfiles doesn't change the meaning of the source. 702279528Sbapt.Pp 703279528SbaptThe source program is a concatenation of the text in all the files, in the 704279528Sbaptorder specified. 705279528Sbapt.Pp 706279528SbaptEach time you run 707279528Sbapt.Xr as 708279528Sbaptit assembles exactly one source program. The source program is made up of 709279528Sbaptone or more files. (The standard input is also a file.) 710279528Sbapt.Pp 711279528SbaptYou give 712279528Sbapt.Xr as 713279528Sbapta command line that has zero or more input file names. The input files are 714279528Sbaptread (from left file name to right). A command line argument (in any position) 715279528Sbaptthat has no special meaning is taken to be an input file name. 716279528Sbapt.Pp 717279528SbaptIf you give 718279528Sbapt.Xr as 719279528Sbaptno file names it attempts to read one input file from the 720279528Sbapt.Xr as 721279528Sbaptstandard input, which is normally your terminal. You may have to type ctl-D 722279528Sbaptto tell 723279528Sbapt.Xr as 724279528Sbaptthere is no more program to assemble. 725279528Sbapt.Pp 726279528SbaptUse 727279528Sbapt.Li -- 728279528Sbaptif you need to explicitly name the standard input file in your command line. 729279528Sbapt.Pp 730279528SbaptIf the source is empty, 731279528Sbapt.Xr as 732279528Sbaptproduces a small, empty object file. 733279528Sbapt.Pp 734279528Sbapt.Em Filenames and Line-numbers 735279528Sbapt.Pp 736279528SbaptThere are two ways of locating a line in the input file (or files) and either 737279528Sbaptmay be used in reporting error messages. One way refers to a line number in 738279528Sbapta physical file; the other refers to a line number in a \(lqlogical\(rq file.See Section 739279528Sbapt.Dq Errors . 740279528Sbapt.Pp 741279528Sbapt.Em Physical files 742279528Sbaptare those files named in the command line given to 743279528Sbapt.Xr as . 744279528Sbapt.Pp 745279528Sbapt.Em Logical files 746279528Sbaptare simply names declared explicitly by assembler directives; they bear no 747279528Sbaptrelation to physical files. Logical file names help error messages reflect 748279528Sbaptthe original source file, when 749279528Sbapt.Xr as 750279528Sbaptsource is itself synthesized from other files. 751279528Sbapt.Xr as 752279528Sbaptunderstands the 753279528Sbapt.Li # 754279528Sbaptdirectives emitted by the 755279528Sbapt.Li gcc 756279528Sbaptpreprocessor. See also File,, 757279528Sbapt.Li .file 758279528Sbapt\&. 759279528Sbapt.Pp 760279528Sbapt.Ss Output (Object) File 761279528SbaptEvery time you run 762279528Sbapt.Xr as 763279528Sbaptit produces an output file, which is your assembly language program translated 764279528Sbaptinto numbers. This file is the object file. Its default name is 765279528Sbapt.Li a.out . 766279528SbaptYou can give it another name by using the 767279528Sbapt.Op -o 768279528Sbaptoption. Conventionally, object file names end with 769279528Sbapt.Pa .o . 770279528SbaptThe default name is used for historical reasons: older assemblers were capable 771279528Sbaptof assembling self-contained programs directly into a runnable program. (For 772279528Sbaptsome formats, this isn't currently possible, but it can be done for the 773279528Sbapt.Li a.out 774279528Sbaptformat.) 775279528Sbapt.Pp 776279528SbaptThe object file is meant for input to the linker 777279528Sbapt.Li ld . 778279528SbaptIt contains assembled program code, information to help 779279528Sbapt.Li ld 780279528Sbaptintegrate the assembled program into a runnable file, and (optionally) symbolic 781279528Sbaptinformation for the debugger. 782279528Sbapt.Pp 783279528Sbapt.Ss Error and Warning Messages 784279528Sbapt.Xr as 785279528Sbaptmay write warnings and error messages to the standard error file (usually 786279528Sbaptyour terminal). This should not happen when a compiler runs 787279528Sbapt.Xr as 788279528Sbaptautomatically. Warnings report an assumption made so that 789279528Sbapt.Xr as 790279528Sbaptcould keep assembling a flawed program; errors report a grave problem that 791279528Sbaptstops the assembly. 792279528Sbapt.Pp 793279528SbaptWarning messages have the format 794279528Sbapt.Pp 795279528Sbapt.Bd -literal -offset indent 796279528Sbaptfile_name:NNN:Warning Message Text 797279528Sbapt.Ed 798279528Sbapt.Pp 799279528Sbapt(where 800279528Sbapt.Sy NNN 801279528Sbaptis a line number). If a logical file name has been given (see Section 802279528Sbapt.Dq File ) 803279528Sbaptit is used for the filename, otherwise the name of the current input file 804279528Sbaptis used. If a logical line number was given then it is used to calculate the 805279528Sbaptnumber printed, otherwise the actual line in the current source file is printed. 806279528SbaptThe message text is intended to be self explanatory (in the grand Unix tradition). 807279528Sbapt.Pp 808279528SbaptError messages have the format 809279528Sbapt.Bd -literal -offset indent 810279528Sbaptfile_name:NNN:FATAL:Error Message Text 811279528Sbapt.Ed 812279528SbaptThe file name and line number are derived as for warning messages. The actual 813279528Sbaptmessage text may be rather less explanatory because many of them aren't supposed 814279528Sbaptto happen. 815279528Sbapt.Pp 816279528Sbapt.Sh Command-Line Options 817279528SbaptThis chapter describes command-line options available in 818279528Sbapt.Em all 819279528Sbaptversions of the GNU assembler; see Machine Dependencies, for options specific 820279528Sbaptto the machine specific target. 821279528Sbapt.Pp 822279528SbaptIf you are invoking 823279528Sbapt.Xr as 824279528Sbaptvia the GNU C compiler, you can use the 825279528Sbapt.Li -Wa 826279528Sbaptoption to pass arguments through to the assembler. The assembler arguments 827279528Sbaptmust be separated from each other (and the 828279528Sbapt.Li -Wa ) 829279528Sbaptby commas. For example: 830279528Sbapt.Pp 831279528Sbapt.Bd -literal -offset indent 832279528Sbaptgcc -c -g -O -Wa,-alh,-L file.c 833279528Sbapt.Ed 834279528Sbapt.Pp 835279528SbaptThis passes two options to the assembler: 836279528Sbapt.Li -alh 837279528Sbapt(emit a listing to standard output with high-level and assembly source) and 838279528Sbapt.Li -L 839279528Sbapt(retain local symbols in the symbol table). 840279528Sbapt.Pp 841279528SbaptUsually you do not need to use this 842279528Sbapt.Li -Wa 843279528Sbaptmechanism, since many compiler command-line options are automatically passed 844279528Sbaptto the assembler by the compiler. (You can call the GNU compiler driver with 845279528Sbaptthe 846279528Sbapt.Li -v 847279528Sbaptoption to see precisely what options it passes to each compilation pass, including 848279528Sbaptthe assembler.) 849279528Sbapt.Pp 850279528Sbapt.Ss Enable Listings: Op -a[cdhlns] 851279528SbaptThese options enable listing output from the assembler. By itself, 852279528Sbapt.Li -a 853279528Sbaptrequests high-level, assembly, and symbols listing. You can use other letters 854279528Sbaptto select specific options for the list: 855279528Sbapt.Li -ah 856279528Sbaptrequests a high-level language listing, 857279528Sbapt.Li -al 858279528Sbaptrequests an output-program assembly listing, and 859279528Sbapt.Li -as 860279528Sbaptrequests a symbol table listing. High-level listings require that a compiler 861279528Sbaptdebugging option like 862279528Sbapt.Li -g 863279528Sbaptbe used, and that assembly listings ( 864279528Sbapt.Li -al ) 865279528Sbaptbe requested also. 866279528Sbapt.Pp 867279528SbaptUse the 868279528Sbapt.Li -ac 869279528Sbaptoption to omit false conditionals from a listing. Any lines which are not 870279528Sbaptassembled because of a false 871279528Sbapt.Li .if 872279528Sbapt(or 873279528Sbapt.Li .ifdef , 874279528Sbaptor any other conditional), or a true 875279528Sbapt.Li .if 876279528Sbaptfollowed by an 877279528Sbapt.Li .else , 878279528Sbaptwill be omitted from the listing. 879279528Sbapt.Pp 880279528SbaptUse the 881279528Sbapt.Li -ad 882279528Sbaptoption to omit debugging directives from the listing. 883279528Sbapt.Pp 884279528SbaptOnce you have specified one of these options, you can further control listing 885279528Sbaptoutput and its appearance using the directives 886279528Sbapt.Li .list , 887279528Sbapt.Li .nolist , 888279528Sbapt.Li .psize , 889279528Sbapt.Li .eject , 890279528Sbapt.Li .title , 891279528Sbaptand 892279528Sbapt.Li .sbttl . 893279528SbaptThe 894279528Sbapt.Li -an 895279528Sbaptoption turns off all forms processing. If you do not request listing output 896279528Sbaptwith one of the 897279528Sbapt.Li -a 898279528Sbaptoptions, the listing-control directives have no effect. 899279528Sbapt.Pp 900279528SbaptThe letters after 901279528Sbapt.Li -a 902279528Sbaptmay be combined into one option, 903279528Sbapt.Em e.g. , 904279528Sbapt.Li -aln . 905279528Sbapt.Pp 906279528SbaptNote if the assembler source is coming from the standard input (e.g., because 907279528Sbaptit is being created by 908279528Sbapt.Li gcc 909279528Sbaptand the 910279528Sbapt.Li -pipe 911279528Sbaptcommand line switch is being used) then the listing will not contain any comments 912279528Sbaptor preprocessor directives. This is because the listing code buffers input 913279528Sbaptsource lines from stdin only after they have been preprocessed by the assembler. 914279528SbaptThis reduces memory usage and makes the code more efficient. 915279528Sbapt.Pp 916279528Sbapt.Ss Op --alternate 917279528SbaptBegin in alternate macro mode, see Altmacro,, 918279528Sbapt.Li .altmacro 919279528Sbapt\&. 920279528Sbapt.Pp 921279528Sbapt.Ss Op -D 922279528SbaptThis option has no effect whatsoever, but it is accepted to make it more likely 923279528Sbaptthat scripts written for other assemblers also work with 924279528Sbapt.Xr as . 925279528Sbapt.Pp 926279528Sbapt.Ss Work Faster: Op -f 927279528Sbapt.Li -f 928279528Sbaptshould only be used when assembling programs written by a (trusted) compiler. 929279528Sbapt.Li -f 930279528Sbaptstops the assembler from doing whitespace and comment preprocessing on the 931279528Sbaptinput file(s) before assembling them.See Section 932279528Sbapt.Dq Preprocessing . 933279528Sbapt.Pp 934279528Sbapt.Qo 935279528Sbapt.Em Warning: 936279528Sbaptif you use 937279528Sbapt.Li -f 938279528Sbaptwhen the files actually need to be preprocessed (if they contain comments, 939279528Sbaptfor example), 940279528Sbapt.Xr as 941279528Sbaptdoes not work correctly. 942279528Sbapt.Qc 943279528Sbapt.Pp 944279528Sbapt.Ss Li .include Search Path: Op -I Va path 945279528SbaptUse this option to add a 946279528Sbapt.Va path 947279528Sbaptto the list of directories 948279528Sbapt.Xr as 949279528Sbaptsearches for files specified in 950279528Sbapt.Li .include 951279528Sbaptdirectives (see Section 952279528Sbapt.Dq Include ) . 953279528SbaptYou may use 954279528Sbapt.Op -I 955279528Sbaptas many times as necessary to include a variety of paths. The current working 956279528Sbaptdirectory is always searched first; after that, 957279528Sbapt.Xr as 958279528Sbaptsearches any 959279528Sbapt.Li -I 960279528Sbaptdirectories in the same order as they were specified (left to right) on the 961279528Sbaptcommand line. 962279528Sbapt.Pp 963279528Sbapt.Ss Difference Tables: Op -K 964279528SbaptOn the machine specific family, this option is allowed, but has no effect. 965279528SbaptIt is permitted for compatibility with the GNU assembler on other platforms, 966279528Sbaptwhere it can be used to warn when the assembler alters the machine code generated 967279528Sbaptfor 968279528Sbapt.Li .word 969279528Sbaptdirectives in difference tables. The machine specific family does not have 970279528Sbaptthe addressing limitations that sometimes lead to this alteration on other 971279528Sbaptplatforms. 972279528Sbapt.Pp 973279528Sbapt.Ss Include Local Symbols: Op -L 974279528SbaptSymbols beginning with system-specific local label prefixes, typically 975279528Sbapt.Li .L 976279528Sbaptfor ELF systems or 977279528Sbapt.Li L 978279528Sbaptfor traditional a.out systems, are called 979279528Sbapt.Em local symbols . 980279528SbaptSee Section.Dq Symbol Names . 981279528SbaptNormally you do not see such symbols when debugging, because they are intended 982279528Sbaptfor the use of programs (like compilers) that compose assembler programs, 983279528Sbaptnot for your notice. Normally both 984279528Sbapt.Xr as 985279528Sbaptand 986279528Sbapt.Li ld 987279528Sbaptdiscard such symbols, so you do not normally debug with them. 988279528Sbapt.Pp 989279528SbaptThis option tells 990279528Sbapt.Xr as 991279528Sbaptto retain those local symbols in the object file. Usually if you do this you 992279528Sbaptalso tell the linker 993279528Sbapt.Li ld 994279528Sbaptto preserve those symbols. 995279528Sbapt.Pp 996279528Sbapt.Ss Configuring listing output: Op --listing 997279528SbaptThe listing feature of the assembler can be enabled via the command line switch 998279528Sbapt.Li -a 999279528Sbapt(see Section 1000279528Sbapt.Dq a ) . 1001279528SbaptThis feature combines the input source file(s) with a hex dump of the corresponding 1002279528Sbaptlocations in the output object file, and displays them as a listing file. 1003279528SbaptThe format of this listing can be controlled by directives inside the assembler 1004279528Sbaptsource (i.e., 1005279528Sbapt.Li .list 1006279528Sbapt(see Section 1007279528Sbapt.Dq List ) , 1008279528Sbapt.Li .title 1009279528Sbapt(see Section 1010279528Sbapt.Dq Title ) , 1011279528Sbapt.Li .sbttl 1012279528Sbapt(see Section 1013279528Sbapt.Dq Sbttl ) , 1014279528Sbapt.Li .psize 1015279528Sbapt(see Section 1016279528Sbapt.Dq Psize ) , 1017279528Sbaptand 1018279528Sbapt.Li .eject 1019279528Sbapt(see Section 1020279528Sbapt.Dq Eject ) 1021279528Sbaptand also by the following switches: 1022279528Sbapt.Pp 1023279528Sbapt.Bl -tag -width Ds 1024279528Sbapt.It --listing-lhs-width= Li number 1025279528SbaptSets the maximum width, in words, of the first line of the hex byte dump. 1026279528SbaptThis dump appears on the left hand side of the listing output. 1027279528Sbapt.Pp 1028279528Sbapt.It --listing-lhs-width2= Li number 1029279528SbaptSets the maximum width, in words, of any further lines of the hex byte dump 1030279528Sbaptfor a given input source line. If this value is not specified, it defaults 1031279528Sbaptto being the same as the value specified for 1032279528Sbapt.Li --listing-lhs-width . 1033279528SbaptIf neither switch is used the default is to one. 1034279528Sbapt.Pp 1035279528Sbapt.It --listing-rhs-width= Li number 1036279528SbaptSets the maximum width, in characters, of the source line that is displayed 1037279528Sbaptalongside the hex dump. The default value for this parameter is 100. The source 1038279528Sbaptline is displayed on the right hand side of the listing output. 1039279528Sbapt.Pp 1040279528Sbapt.It --listing-cont-lines= Li number 1041279528SbaptSets the maximum number of continuation lines of hex dump that will be displayed 1042279528Sbaptfor a given single line of source input. The default value is 4. 1043279528Sbapt.El 1044279528Sbapt.Pp 1045279528Sbapt.Ss Assemble in MRI Compatibility Mode: Op -M 1046279528SbaptThe 1047279528Sbapt.Op -M 1048279528Sbaptor 1049279528Sbapt.Op --mri 1050279528Sbaptoption selects MRI compatibility mode. This changes the syntax and pseudo-op 1051279528Sbapthandling of 1052279528Sbapt.Xr as 1053279528Sbaptto make it compatible with the 1054279528Sbapt.Li ASM68K 1055279528Sbaptor the 1056279528Sbapt.Li ASM960 1057279528Sbapt(depending upon the configured target) assembler from Microtec Research. The 1058279528Sbaptexact nature of the MRI syntax will not be documented here; see the MRI manuals 1059279528Sbaptfor more information. Note in particular that the handling of macros and macro 1060279528Sbaptarguments is somewhat different. The purpose of this option is to permit assembling 1061279528Sbaptexisting MRI assembler code using 1062279528Sbapt.Xr as . 1063279528Sbapt.Pp 1064279528SbaptThe MRI compatibility is not complete. Certain operations of the MRI assembler 1065279528Sbaptdepend upon its object file format, and can not be supported using other object 1066279528Sbaptfile formats. Supporting these would require enhancing each object file format 1067279528Sbaptindividually. These are: 1068279528Sbapt.Pp 1069279528Sbapt.Bl -bullet 1070279528Sbapt.It 1071279528Sbaptglobal symbols in common section 1072279528Sbapt.Pp 1073279528SbaptThe m68k MRI assembler supports common sections which are merged by the linker. 1074279528SbaptOther object file formats do not support this. 1075279528Sbapt.Xr as 1076279528Sbapthandles common sections by treating them as a single common symbol. It permits 1077279528Sbaptlocal symbols to be defined within a common section, but it can not support 1078279528Sbaptglobal symbols, since it has no way to describe them. 1079279528Sbapt.Pp 1080279528Sbapt.It 1081279528Sbaptcomplex relocations 1082279528Sbapt.Pp 1083279528SbaptThe MRI assemblers support relocations against a negated section address, 1084279528Sbaptand relocations which combine the start addresses of two or more sections. 1085279528SbaptThese are not support by other object file formats. 1086279528Sbapt.Pp 1087279528Sbapt.It 1088279528Sbapt.Li END 1089279528Sbaptpseudo-op specifying start address 1090279528Sbapt.Pp 1091279528SbaptThe MRI 1092279528Sbapt.Li END 1093279528Sbaptpseudo-op permits the specification of a start address. This is not supported 1094279528Sbaptby other object file formats. The start address may instead be specified using 1095279528Sbaptthe 1096279528Sbapt.Op -e 1097279528Sbaptoption to the linker, or in a linker script. 1098279528Sbapt.Pp 1099279528Sbapt.It 1100279528Sbapt.Li IDNT , 1101279528Sbapt.Li .ident 1102279528Sbaptand 1103279528Sbapt.Li NAME 1104279528Sbaptpseudo-ops 1105279528Sbapt.Pp 1106279528SbaptThe MRI 1107279528Sbapt.Li IDNT , 1108279528Sbapt.Li .ident 1109279528Sbaptand 1110279528Sbapt.Li NAME 1111279528Sbaptpseudo-ops assign a module name to the output file. This is not supported 1112279528Sbaptby other object file formats. 1113279528Sbapt.Pp 1114279528Sbapt.It 1115279528Sbapt.Li ORG 1116279528Sbaptpseudo-op 1117279528Sbapt.Pp 1118279528SbaptThe m68k MRI 1119279528Sbapt.Li ORG 1120279528Sbaptpseudo-op begins an absolute section at a given address. This differs from 1121279528Sbaptthe usual 1122279528Sbapt.Xr as 1123279528Sbapt.Li .org 1124279528Sbaptpseudo-op, which changes the location within the current section. Absolute 1125279528Sbaptsections are not supported by other object file formats. The address of a 1126279528Sbaptsection may be assigned within a linker script. 1127279528Sbapt.El 1128279528Sbapt.Pp 1129279528SbaptThere are some other features of the MRI assembler which are not supported 1130279528Sbaptby 1131279528Sbapt.Xr as , 1132279528Sbapttypically either because they are difficult or because they seem of little 1133279528Sbaptconsequence. Some of these may be supported in future releases. 1134279528Sbapt.Pp 1135279528Sbapt.Bl -bullet 1136279528Sbapt.It 1137279528SbaptEBCDIC strings 1138279528Sbapt.Pp 1139279528SbaptEBCDIC strings are not supported. 1140279528Sbapt.Pp 1141279528Sbapt.It 1142279528Sbaptpacked binary coded decimal 1143279528Sbapt.Pp 1144279528SbaptPacked binary coded decimal is not supported. This means that the 1145279528Sbapt.Li DC.P 1146279528Sbaptand 1147279528Sbapt.Li DCB.P 1148279528Sbaptpseudo-ops are not supported. 1149279528Sbapt.Pp 1150279528Sbapt.It 1151279528Sbapt.Li FEQU 1152279528Sbaptpseudo-op 1153279528Sbapt.Pp 1154279528SbaptThe m68k 1155279528Sbapt.Li FEQU 1156279528Sbaptpseudo-op is not supported. 1157279528Sbapt.Pp 1158279528Sbapt.It 1159279528Sbapt.Li NOOBJ 1160279528Sbaptpseudo-op 1161279528Sbapt.Pp 1162279528SbaptThe m68k 1163279528Sbapt.Li NOOBJ 1164279528Sbaptpseudo-op is not supported. 1165279528Sbapt.Pp 1166279528Sbapt.It 1167279528Sbapt.Li OPT 1168279528Sbaptbranch control options 1169279528Sbapt.Pp 1170279528SbaptThe m68k 1171279528Sbapt.Li OPT 1172279528Sbaptbranch control options--- 1173279528Sbapt.Li B , 1174279528Sbapt.Li BRS , 1175279528Sbapt.Li BRB , 1176279528Sbapt.Li BRL , 1177279528Sbaptand 1178279528Sbapt.Li BRW 1179279528Sbapt---are ignored. 1180279528Sbapt.Xr as 1181279528Sbaptautomatically relaxes all branches, whether forward or backward, to an appropriate 1182279528Sbaptsize, so these options serve no purpose. 1183279528Sbapt.Pp 1184279528Sbapt.It 1185279528Sbapt.Li OPT 1186279528Sbaptlist control options 1187279528Sbapt.Pp 1188279528SbaptThe following m68k 1189279528Sbapt.Li OPT 1190279528Sbaptlist control options are ignored: 1191279528Sbapt.Li C , 1192279528Sbapt.Li CEX , 1193279528Sbapt.Li CL , 1194279528Sbapt.Li CRE , 1195279528Sbapt.Li E , 1196279528Sbapt.Li G , 1197279528Sbapt.Li I , 1198279528Sbapt.Li M , 1199279528Sbapt.Li MEX , 1200279528Sbapt.Li MC , 1201279528Sbapt.Li MD , 1202279528Sbapt.Li X . 1203279528Sbapt.Pp 1204279528Sbapt.It 1205279528Sbaptother 1206279528Sbapt.Li OPT 1207279528Sbaptoptions 1208279528Sbapt.Pp 1209279528SbaptThe following m68k 1210279528Sbapt.Li OPT 1211279528Sbaptoptions are ignored: 1212279528Sbapt.Li NEST , 1213279528Sbapt.Li O , 1214279528Sbapt.Li OLD , 1215279528Sbapt.Li OP , 1216279528Sbapt.Li P , 1217279528Sbapt.Li PCO , 1218279528Sbapt.Li PCR , 1219279528Sbapt.Li PCS , 1220279528Sbapt.Li R . 1221279528Sbapt.Pp 1222279528Sbapt.It 1223279528Sbapt.Li OPT 1224279528Sbapt.Li D 1225279528Sbaptoption is default 1226279528Sbapt.Pp 1227279528SbaptThe m68k 1228279528Sbapt.Li OPT 1229279528Sbapt.Li D 1230279528Sbaptoption is the default, unlike the MRI assembler. 1231279528Sbapt.Li OPT NOD 1232279528Sbaptmay be used to turn it off. 1233279528Sbapt.Pp 1234279528Sbapt.It 1235279528Sbapt.Li XREF 1236279528Sbaptpseudo-op. 1237279528Sbapt.Pp 1238279528SbaptThe m68k 1239279528Sbapt.Li XREF 1240279528Sbaptpseudo-op is ignored. 1241279528Sbapt.Pp 1242279528Sbapt.It 1243279528Sbapt.Li .debug 1244279528Sbaptpseudo-op 1245279528Sbapt.Pp 1246279528SbaptThe i960 1247279528Sbapt.Li .debug 1248279528Sbaptpseudo-op is not supported. 1249279528Sbapt.Pp 1250279528Sbapt.It 1251279528Sbapt.Li .extended 1252279528Sbaptpseudo-op 1253279528Sbapt.Pp 1254279528SbaptThe i960 1255279528Sbapt.Li .extended 1256279528Sbaptpseudo-op is not supported. 1257279528Sbapt.Pp 1258279528Sbapt.It 1259279528Sbapt.Li .list 1260279528Sbaptpseudo-op. 1261279528Sbapt.Pp 1262279528SbaptThe various options of the i960 1263279528Sbapt.Li .list 1264279528Sbaptpseudo-op are not supported. 1265279528Sbapt.Pp 1266279528Sbapt.It 1267279528Sbapt.Li .optimize 1268279528Sbaptpseudo-op 1269279528Sbapt.Pp 1270279528SbaptThe i960 1271279528Sbapt.Li .optimize 1272279528Sbaptpseudo-op is not supported. 1273279528Sbapt.Pp 1274279528Sbapt.It 1275279528Sbapt.Li .output 1276279528Sbaptpseudo-op 1277279528Sbapt.Pp 1278279528SbaptThe i960 1279279528Sbapt.Li .output 1280279528Sbaptpseudo-op is not supported. 1281279528Sbapt.Pp 1282279528Sbapt.It 1283279528Sbapt.Li .setreal 1284279528Sbaptpseudo-op 1285279528Sbapt.Pp 1286279528SbaptThe i960 1287279528Sbapt.Li .setreal 1288279528Sbaptpseudo-op is not supported. 1289279528Sbapt.Pp 1290279528Sbapt.El 1291279528Sbapt.Ss Dependency Tracking: Op --MD 1292279528Sbapt.Xr as 1293279528Sbaptcan generate a dependency file for the file it creates. This file consists 1294279528Sbaptof a single rule suitable for 1295279528Sbapt.Li make 1296279528Sbaptdescribing the dependencies of the main source file. 1297279528Sbapt.Pp 1298279528SbaptThe rule is written to the file named in its argument. 1299279528Sbapt.Pp 1300279528SbaptThis feature is used in the automatic updating of makefiles. 1301279528Sbapt.Pp 1302279528Sbapt.Ss Name the Object File: Op -o 1303279528SbaptThere is always one object file output when you run 1304279528Sbapt.Xr as . 1305279528SbaptBy default it has the name 1306279528Sbapt.Pa a.out . 1307279528SbaptYou use this option (which takes exactly one filename) to give the object 1308279528Sbaptfile a different name. 1309279528Sbapt.Pp 1310279528SbaptWhatever the object file is called, 1311279528Sbapt.Xr as 1312279528Sbaptoverwrites any existing file of the same name. 1313279528Sbapt.Pp 1314279528Sbapt.Ss Join Data and Text Sections: Op -R 1315279528Sbapt.Op -R 1316279528Sbapttells 1317279528Sbapt.Xr as 1318279528Sbaptto write the object file as if all data-section data lives in the text section. 1319279528SbaptThis is only done at the very last moment: your binary data are the same, 1320279528Sbaptbut data section parts are relocated differently. The data section part of 1321279528Sbaptyour object file is zero bytes long because all its bytes are appended to 1322279528Sbaptthe text section. (See Section 1323279528Sbapt.Dq Sections . ) 1324279528Sbapt.Pp 1325279528SbaptWhen you specify 1326279528Sbapt.Op -R 1327279528Sbaptit would be possible to generate shorter address displacements (because we 1328279528Sbaptdo not have to cross between text and data section). We refrain from doing 1329279528Sbaptthis simply for compatibility with older versions of 1330279528Sbapt.Xr as . 1331279528SbaptIn future, 1332279528Sbapt.Op -R 1333279528Sbaptmay work this way. 1334279528Sbapt.Pp 1335279528SbaptWhen 1336279528Sbapt.Xr as 1337279528Sbaptis configured for COFF or ELF output, this option is only useful if you use 1338279528Sbaptsections named 1339279528Sbapt.Li .text 1340279528Sbaptand 1341279528Sbapt.Li .data . 1342279528Sbapt.Pp 1343279528Sbapt.Ss Display Assembly Statistics: Op --statistics 1344279528SbaptUse 1345279528Sbapt.Li --statistics 1346279528Sbaptto display two statistics about the resources used by 1347279528Sbapt.Xr as : 1348279528Sbaptthe maximum amount of space allocated during the assembly (in bytes), and 1349279528Sbaptthe total execution time taken for the assembly (in cpu seconds). 1350279528Sbapt.Pp 1351279528Sbapt.Ss Compatible Output: Op --traditional-format 1352279528SbaptFor some targets, the output of 1353279528Sbapt.Xr as 1354279528Sbaptis different in some ways from the output of some existing assembler. This 1355279528Sbaptswitch requests 1356279528Sbapt.Xr as 1357279528Sbaptto use the traditional format instead. 1358279528Sbapt.Pp 1359279528SbaptFor example, it disables the exception frame optimizations which 1360279528Sbapt.Xr as 1361279528Sbaptnormally does by default on 1362279528Sbapt.Li gcc 1363279528Sbaptoutput. 1364279528Sbapt.Pp 1365279528Sbapt.Ss Announce Version: Op -v 1366279528SbaptYou can find out what version of as is running by including the option 1367279528Sbapt.Li -v 1368279528Sbapt(which you can also spell as 1369279528Sbapt.Li -version ) 1370279528Sbapton the command line. 1371279528Sbapt.Pp 1372279528Sbapt.Ss Control Warnings: Op -W, Op --warn, Op --no-warn, Op --fatal-warnings 1373279528Sbapt.Xr as 1374279528Sbaptshould never give a warning or error message when assembling compiler output. 1375279528SbaptBut programs written by people often cause 1376279528Sbapt.Xr as 1377279528Sbaptto give a warning that a particular assumption was made. All such warnings 1378279528Sbaptare directed to the standard error file. 1379279528Sbapt.Pp 1380279528SbaptIf you use the 1381279528Sbapt.Op -W 1382279528Sbaptand 1383279528Sbapt.Op --no-warn 1384279528Sbaptoptions, no warnings are issued. This only affects the warning messages: it 1385279528Sbaptdoes not change any particular of how 1386279528Sbapt.Xr as 1387279528Sbaptassembles your file. Errors, which stop the assembly, are still reported. 1388279528Sbapt.Pp 1389279528SbaptIf you use the 1390279528Sbapt.Op --fatal-warnings 1391279528Sbaptoption, 1392279528Sbapt.Xr as 1393279528Sbaptconsiders files that generate warnings to be in error. 1394279528Sbapt.Pp 1395279528SbaptYou can switch these options off again by specifying 1396279528Sbapt.Op --warn , 1397279528Sbaptwhich causes warnings to be output as usual. 1398279528Sbapt.Pp 1399279528Sbapt.Ss Generate Object File in Spite of Errors: Op -Z 1400279528SbaptAfter an error message, 1401279528Sbapt.Xr as 1402279528Sbaptnormally produces no output. If for some reason you are interested in object 1403279528Sbaptfile output even after 1404279528Sbapt.Xr as 1405279528Sbaptgives an error message on your program, use the 1406279528Sbapt.Li -Z 1407279528Sbaptoption. If there are any errors, 1408279528Sbapt.Xr as 1409279528Sbaptcontinues anyways, and writes an object file after a final warning message 1410279528Sbaptof the form 1411279528Sbapt.Li Va n errors, Va m warnings, generating bad object file. 1412279528Sbapt.Pp 1413279528Sbapt.Sh Syntax 1414279528SbaptThis chapter describes the machine-independent syntax allowed in a source 1415279528Sbaptfile. 1416279528Sbapt.Xr as 1417279528Sbaptsyntax is similar to what many other assemblers use; it is inspired by the 1418279528SbaptBSD 4.2 assembler. 1419279528Sbapt.Pp 1420279528Sbapt.Ss Preprocessing 1421279528SbaptThe 1422279528Sbapt.Xr as 1423279528Sbaptinternal preprocessor: 1424279528Sbapt.Bl -bullet 1425279528Sbapt.It 1426279528Sbaptadjusts and removes extra whitespace. It leaves one space or tab before the 1427279528Sbaptkeywords on a line, and turns any other whitespace on the line into a single 1428279528Sbaptspace. 1429279528Sbapt.Pp 1430279528Sbapt.It 1431279528Sbaptremoves all comments, replacing them with a single space, or an appropriate 1432279528Sbaptnumber of newlines. 1433279528Sbapt.Pp 1434279528Sbapt.It 1435279528Sbaptconverts character constants into the appropriate numeric values. 1436279528Sbapt.El 1437279528Sbapt.Pp 1438279528SbaptIt does not do macro processing, include file handling, or anything else you 1439279528Sbaptmay get from your C compiler's preprocessor. You can do include file processing 1440279528Sbaptwith the 1441279528Sbapt.Li .include 1442279528Sbaptdirective (see Section 1443279528Sbapt.Dq Include ) . 1444279528SbaptYou can use the GNU C compiler driver to get other \(lqCPP\(rq style preprocessing 1445279528Sbaptby giving the input file a 1446279528Sbapt.Li .S 1447279528Sbaptsuffix.See Section 1448279528Sbapt.Dq Overall Options . 1449279528Sbapt.Pp 1450279528SbaptExcess whitespace, comments, and character constants cannot be used in the 1451279528Sbaptportions of the input text that are not preprocessed. 1452279528Sbapt.Pp 1453279528SbaptIf the first line of an input file is 1454279528Sbapt.Li #NO_APP 1455279528Sbaptor if you use the 1456279528Sbapt.Li -f 1457279528Sbaptoption, whitespace and comments are not removed from the input file. Within 1458279528Sbaptan input file, you can ask for whitespace and comment removal in specific 1459279528Sbaptportions of the by putting a line that says 1460279528Sbapt.Li #APP 1461279528Sbaptbefore the text that may contain whitespace or comments, and putting a line 1462279528Sbaptthat says 1463279528Sbapt.Li #NO_APP 1464279528Sbaptafter this text. This feature is mainly intend to support 1465279528Sbapt.Li asm 1466279528Sbaptstatements in compilers whose output is otherwise free of comments and whitespace. 1467279528Sbapt.Pp 1468279528Sbapt.Ss Whitespace 1469279528Sbapt.Em Whitespace 1470279528Sbaptis one or more blanks or tabs, in any order. Whitespace is used to separate 1471279528Sbaptsymbols, and to make programs neater for people to read. Unless within character 1472279528Sbaptconstants (see Section 1473279528Sbapt.Dq Characters ) , 1474279528Sbaptany whitespace means the same as exactly one space. 1475279528Sbapt.Pp 1476279528Sbapt.Ss Comments 1477279528SbaptThere are two ways of rendering comments to 1478279528Sbapt.Xr as . 1479279528SbaptIn both cases the comment is equivalent to one space. 1480279528Sbapt.Pp 1481279528SbaptAnything from 1482279528Sbapt.Li /* 1483279528Sbaptthrough the next 1484279528Sbapt.Li */ 1485279528Sbaptis a comment. This means you may not nest these comments. 1486279528Sbapt.Pp 1487279528Sbapt.Bd -literal -offset indent 1488279528Sbapt/* 1489279528Sbapt The only way to include a newline ('\en') in a comment 1490279528Sbapt is to use this sort of comment. 1491279528Sbapt*/ 1492279528Sbapt 1493279528Sbapt/* This sort of comment does not nest. */ 1494279528Sbapt.Ed 1495279528Sbapt.Pp 1496279528SbaptAnything from the 1497279528Sbapt.Em line comment 1498279528Sbaptcharacter to the next newline is considered a comment and is ignored. The 1499279528Sbaptline comment character is 1500279528Sbapt.Li @ 1501279528Sbapton the ARM; 1502279528Sbapt.Li # 1503279528Sbapton the i386 and x86-64; 1504279528Sbapt.Li # 1505279528Sbaptfor Motorola PowerPC; 1506279528Sbapt.Li ! 1507279528Sbapton the SPARC; see Machine Dependencies. 1508279528Sbapt.Pp 1509279528SbaptTo be compatible with past assemblers, lines that begin with 1510279528Sbapt.Li # 1511279528Sbapthave a special interpretation. Following the 1512279528Sbapt.Li # 1513279528Sbaptshould be an absolute expression (see Section 1514279528Sbapt.Dq Expressions ) : 1515279528Sbaptthe logical line number of the 1516279528Sbapt.Em next 1517279528Sbaptline. Then a string (see Section 1518279528Sbapt.Dq Strings ) 1519279528Sbaptis allowed: if present it is a new logical file name. The rest of the line, 1520279528Sbaptif any, should be whitespace. 1521279528Sbapt.Pp 1522279528SbaptIf the first non-whitespace characters on the line are not numeric, the line 1523279528Sbaptis ignored. (Just like a comment.) 1524279528Sbapt.Pp 1525279528Sbapt.Bd -literal -offset indent 1526279528Sbapt # This is an ordinary comment. 1527279528Sbapt# 42-6 "new_file_name" # New logical file name 1528279528Sbapt # This is logical line # 36. 1529279528Sbapt.Ed 1530279528SbaptThis feature is deprecated, and may disappear from future versions of 1531279528Sbapt.Xr as . 1532279528Sbapt.Pp 1533279528Sbapt.Ss Symbols 1534279528SbaptA 1535279528Sbapt.Em symbol 1536279528Sbaptis one or more characters chosen from the set of all letters (both upper and 1537279528Sbaptlower case), digits and the three characters 1538279528Sbapt.Li _.$ . 1539279528SbaptNo symbol may begin with a digit. Case is significant. There is no length 1540279528Sbaptlimit: all characters are significant. Symbols are delimited by characters 1541279528Sbaptnot in that set, or by the beginning of a file (since the source program must 1542279528Sbaptend with a newline, the end of a file is not a possible symbol delimiter).See Section 1543279528Sbapt.Dq Symbols . 1544279528Sbapt.Pp 1545279528Sbapt.Ss Statements 1546279528SbaptA 1547279528Sbapt.Em statement 1548279528Sbaptends at a newline character ( 1549279528Sbapt.Li \en ) 1550279528Sbaptor at a semicolon ( 1551279528Sbapt.Li ; ) . 1552279528SbaptThe newline or semicolon is considered part of the preceding statement. Newlines 1553279528Sbaptand semicolons within character constants are an exception: they do not end 1554279528Sbaptstatements. 1555279528Sbapt.Pp 1556279528SbaptIt is an error to end any statement with end-of-file: the last character of 1557279528Sbaptany input file should be a newline. 1558279528Sbapt.Pp 1559279528SbaptAn empty statement is allowed, and may include whitespace. It is ignored. 1560279528Sbapt.Pp 1561279528SbaptA statement begins with zero or more labels, optionally followed by a key 1562279528Sbaptsymbol which determines what kind of statement it is. The key symbol determines 1563279528Sbaptthe syntax of the rest of the statement. If the symbol begins with a dot 1564279528Sbapt.Li . 1565279528Sbaptthen the statement is an assembler directive: typically valid for any computer. 1566279528SbaptIf the symbol begins with a letter the statement is an assembly language 1567279528Sbapt.Em instruction : 1568279528Sbaptit assembles into a machine language instruction. 1569279528Sbapt.Pp 1570279528SbaptA label is a symbol immediately followed by a colon ( 1571279528Sbapt.Li : ) . 1572279528SbaptWhitespace before a label or after a colon is permitted, but you may not have 1573279528Sbaptwhitespace between a label's symbol and its colon.See Section 1574279528Sbapt.Dq Labels . 1575279528Sbapt.Pp 1576279528Sbapt.Bd -literal -offset indent 1577279528Sbaptlabel: .directive followed by something 1578279528Sbaptanother_label: # This is an empty statement. 1579279528Sbapt instruction operand_1, operand_2, ... 1580279528Sbapt.Ed 1581279528Sbapt.Pp 1582279528Sbapt.Ss Constants 1583279528SbaptA constant is a number, written so that its value is known by inspection, 1584279528Sbaptwithout knowing any context. Like this: 1585279528Sbapt.Bd -literal -offset indent 1586279528Sbapt 1587279528Sbapt\&.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\eJ # All the same value. 1588279528Sbapt\&.ascii "Ring the bell\e7" # A string constant. 1589279528Sbapt\&.octa 0x123456789abcdef0123456789ABCDEF0 # A biGNUm. 1590279528Sbapt\&.float 0f-314159265358979323846264338327\e 1591279528Sbapt95028841971.693993751E-40 # - pi, a flonum. 1592279528Sbapt 1593279528Sbapt.Ed 1594279528Sbapt.Pp 1595279528Sbapt.Em Character Constants 1596279528Sbapt.Pp 1597279528SbaptThere are two kinds of character constants. A 1598279528Sbapt.Em character 1599279528Sbaptstands for one character in one byte and its value may be used in numeric 1600279528Sbaptexpressions. String constants (properly called string 1601279528Sbapt.Em literals ) 1602279528Sbaptare potentially many bytes and their values may not be used in arithmetic 1603279528Sbaptexpressions. 1604279528Sbapt.Pp 1605279528Sbapt.No Strings 1606279528Sbapt.Pp 1607279528SbaptA 1608279528Sbapt.Em string 1609279528Sbaptis written between double-quotes. It may contain double-quotes or null characters. 1610279528SbaptThe way to get special characters into a string is to 1611279528Sbapt.Em escape 1612279528Sbaptthese characters: precede them with a backslash 1613279528Sbapt.Li \e 1614279528Sbaptcharacter. For example 1615279528Sbapt.Li \e\e 1616279528Sbaptrepresents one backslash: the first 1617279528Sbapt.Li \e 1618279528Sbaptis an escape which tells 1619279528Sbapt.Xr as 1620279528Sbaptto interpret the second character literally as a backslash (which prevents 1621279528Sbapt.Xr as 1622279528Sbaptfrom recognizing the second 1623279528Sbapt.Li \e 1624279528Sbaptas an escape character). The complete list of escapes follows. 1625279528Sbapt.Pp 1626279528Sbapt.Bl -tag -width Ds 1627279528Sbapt.It \eb 1628279528SbaptMnemonic for backspace; for ASCII this is octal code 010. 1629279528Sbapt.Pp 1630279528Sbapt.It \ef 1631279528SbaptMnemonic for FormFeed; for ASCII this is octal code 014. 1632279528Sbapt.Pp 1633279528Sbapt.It \en 1634279528SbaptMnemonic for newline; for ASCII this is octal code 012. 1635279528Sbapt.Pp 1636279528Sbapt.It \er 1637279528SbaptMnemonic for carriage-Return; for ASCII this is octal code 015. 1638279528Sbapt.Pp 1639279528Sbapt.It \et 1640279528SbaptMnemonic for horizontal Tab; for ASCII this is octal code 011. 1641279528Sbapt.Pp 1642279528Sbapt.It \e Va digit Va digit Va digit 1643279528SbaptAn octal character code. The numeric code is 3 octal digits. For compatibility 1644279528Sbaptwith other Unix systems, 8 and 9 are accepted as digits: for example, 1645279528Sbapt.Li \e008 1646279528Sbapthas the value 010, and 1647279528Sbapt.Li \e009 1648279528Sbaptthe value 011. 1649279528Sbapt.Pp 1650279528Sbapt.It \e Li x Va hex-digits... 1651279528SbaptA hex character code. All trailing hex digits are combined. Either upper or 1652279528Sbaptlower case 1653279528Sbapt.Li x 1654279528Sbaptworks. 1655279528Sbapt.Pp 1656279528Sbapt.It \e\e 1657279528SbaptRepresents one 1658279528Sbapt.Li \e 1659279528Sbaptcharacter. 1660279528Sbapt.Pp 1661279528Sbapt.It \e" 1662279528SbaptRepresents one 1663279528Sbapt.Li " 1664279528Sbaptcharacter. Needed in strings to represent this character, because an unescaped 1665279528Sbapt.Li " 1666279528Sbaptwould end the string. 1667279528Sbapt.Pp 1668279528Sbapt.It \e Va anything-else 1669279528SbaptAny other character when escaped by 1670279528Sbapt.Li \e 1671279528Sbaptgives a warning, but assembles as if the 1672279528Sbapt.Li \e 1673279528Sbaptwas not present. The idea is that if you used an escape sequence you clearly 1674279528Sbaptdidn't want the literal interpretation of the following character. However 1675279528Sbapt.Xr as 1676279528Sbapthas no other interpretation, so 1677279528Sbapt.Xr as 1678279528Sbaptknows it is giving you the wrong code and warns you of the fact. 1679279528Sbapt.El 1680279528Sbapt.Pp 1681279528SbaptWhich characters are escapable, and what those escapes represent, varies widely 1682279528Sbaptamong assemblers. The current set is what we think the BSD 4.2 assembler recognizes, 1683279528Sbaptand is a subset of what most C compilers recognize. If you are in doubt, do 1684279528Sbaptnot use an escape sequence. 1685279528Sbapt.Pp 1686279528Sbapt.No Characters 1687279528Sbapt.Pp 1688279528SbaptA single character may be written as a single quote immediately followed by 1689279528Sbaptthat character. The same escapes apply to characters as to strings. So if 1690279528Sbaptyou want to write the character backslash, you must write 1691279528Sbapt.Li '\e\e 1692279528Sbaptwhere the first 1693279528Sbapt.Li \e 1694279528Sbaptescapes the second 1695279528Sbapt.Li \e . 1696279528SbaptAs you can see, the quote is an acute accent, not a grave accent. A newline 1697279528Sbapt(or semicolon 1698279528Sbapt.Li ; ) 1699279528Sbaptimmediately following an acute accent is taken as a literal character and 1700279528Sbaptdoes not count as the end of a statement. The value of a character constant 1701279528Sbaptin a numeric expression is the machine's byte-wide code for that character. 1702279528Sbapt.Xr as 1703279528Sbaptassumes your character code is ASCII: 1704279528Sbapt.Li 'A 1705279528Sbaptmeans 65, 1706279528Sbapt.Li 'B 1707279528Sbaptmeans 66, and so on. 1708279528Sbapt.Pp 1709279528Sbapt.Em Number Constants 1710279528Sbapt.Pp 1711279528Sbapt.Xr as 1712279528Sbaptdistinguishes three kinds of numbers according to how they are stored in the 1713279528Sbapttarget machine. 1714279528Sbapt.Em Integers 1715279528Sbaptare numbers that would fit into an 1716279528Sbapt.Li int 1717279528Sbaptin the C language. 1718279528Sbapt.Em BiGNUms 1719279528Sbaptare integers, but they are stored in more than 32 bits. 1720279528Sbapt.Em Flonums 1721279528Sbaptare floating point numbers, described below. 1722279528Sbapt.Pp 1723279528Sbapt.No Integers 1724279528Sbapt.Pp 1725279528SbaptA binary integer is 1726279528Sbapt.Li 0b 1727279528Sbaptor 1728279528Sbapt.Li 0B 1729279528Sbaptfollowed by zero or more of the binary digits 1730279528Sbapt.Li 01 . 1731279528Sbapt.Pp 1732279528SbaptAn octal integer is 1733279528Sbapt.Li 0 1734279528Sbaptfollowed by zero or more of the octal digits ( 1735279528Sbapt.Li 01234567 ) . 1736279528Sbapt.Pp 1737279528SbaptA decimal integer starts with a non-zero digit followed by zero or more digits 1738279528Sbapt( 1739279528Sbapt.Li 0123456789 ) . 1740279528Sbapt.Pp 1741279528SbaptA hexadecimal integer is 1742279528Sbapt.Li 0x 1743279528Sbaptor 1744279528Sbapt.Li 0X 1745279528Sbaptfollowed by one or more hexadecimal digits chosen from 1746279528Sbapt.Li 0123456789abcdefABCDEF . 1747279528Sbapt.Pp 1748279528SbaptIntegers have the usual values. To denote a negative integer, use the prefix 1749279528Sbaptoperator 1750279528Sbapt.Li - 1751279528Sbaptdiscussed under expressions (see Section 1752279528Sbapt.Dq Prefix Ops ) . 1753279528Sbapt.Pp 1754279528Sbapt.No BiGNUms 1755279528Sbapt.Pp 1756279528SbaptA 1757279528Sbapt.Em biGNUm 1758279528Sbapthas the same syntax and semantics as an integer except that the number (or 1759279528Sbaptits negative) takes more than 32 bits to represent in binary. The distinction 1760279528Sbaptis made because in some places integers are permitted while biGNUms are not. 1761279528Sbapt.Pp 1762279528Sbapt.No Flonums 1763279528Sbapt.Pp 1764279528SbaptA 1765279528Sbapt.Em flonum 1766279528Sbaptrepresents a floating point number. The translation is indirect: a decimal 1767279528Sbaptfloating point number from the text is converted by 1768279528Sbapt.Xr as 1769279528Sbaptto a generic binary floating point number of more than sufficient precision. 1770279528SbaptThis generic floating point number is converted to a particular computer's 1771279528Sbaptfloating point format (or formats) by a portion of 1772279528Sbapt.Xr as 1773279528Sbaptspecialized to that computer. 1774279528Sbapt.Pp 1775279528SbaptA flonum is written by writing (in order) 1776279528Sbapt.Bl -bullet 1777279528Sbapt.It 1778279528SbaptThe digit 1779279528Sbapt.Li 0 . 1780279528Sbapt.Pp 1781279528Sbapt.It 1782279528SbaptA letter, to tell 1783279528Sbapt.Xr as 1784279528Sbaptthe rest of the number is a flonum. 1785279528Sbapt.Pp 1786279528Sbapt.It 1787279528SbaptAn optional sign: either 1788279528Sbapt.Li + 1789279528Sbaptor 1790279528Sbapt.Li - . 1791279528Sbapt.Pp 1792279528Sbapt.It 1793279528SbaptAn optional 1794279528Sbapt.Em integer part : 1795279528Sbaptzero or more decimal digits. 1796279528Sbapt.Pp 1797279528Sbapt.It 1798279528SbaptAn optional 1799279528Sbapt.Em fractional part : 1800279528Sbapt.Li . 1801279528Sbaptfollowed by zero or more decimal digits. 1802279528Sbapt.Pp 1803279528Sbapt.It 1804279528SbaptAn optional exponent, consisting of: 1805279528Sbapt.Pp 1806279528Sbapt.Bl -bullet 1807279528Sbapt.It 1808279528SbaptAn 1809279528Sbapt.Li E 1810279528Sbaptor 1811279528Sbapt.Li e . 1812279528Sbapt.It 1813279528SbaptOptional sign: either 1814279528Sbapt.Li + 1815279528Sbaptor 1816279528Sbapt.Li - . 1817279528Sbapt.It 1818279528SbaptOne or more decimal digits. 1819279528Sbapt.El 1820279528Sbapt.Pp 1821279528Sbapt.El 1822279528SbaptAt least one of the integer part or the fractional part must be present. The 1823279528Sbaptfloating point number has the usual base-10 value. 1824279528Sbapt.Pp 1825279528Sbapt.Xr as 1826279528Sbaptdoes all processing using integers. Flonums are computed independently of 1827279528Sbaptany floating point hardware in the computer running 1828279528Sbapt.Xr as . 1829279528Sbapt.Pp 1830279528Sbapt.Sh Sections and Relocation 1831279528Sbapt.Ss Background 1832279528SbaptRoughly, a section is a range of addresses, with no gaps; all data \(lqin\(rq those 1833279528Sbaptaddresses is treated the same for some particular purpose. For example there 1834279528Sbaptmay be a \(lqread only\(rq section. 1835279528Sbapt.Pp 1836279528SbaptThe linker 1837279528Sbapt.Li ld 1838279528Sbaptreads many object files (partial programs) and combines their contents to 1839279528Sbaptform a runnable program. When 1840279528Sbapt.Xr as 1841279528Sbaptemits an object file, the partial program is assumed to start at address 0. 1842279528Sbapt.Li ld 1843279528Sbaptassigns the final addresses for the partial program, so that different partial 1844279528Sbaptprograms do not overlap. This is actually an oversimplification, but it suffices 1845279528Sbaptto explain how 1846279528Sbapt.Xr as 1847279528Sbaptuses sections. 1848279528Sbapt.Pp 1849279528Sbapt.Li ld 1850279528Sbaptmoves blocks of bytes of your program to their run-time addresses. These blocks 1851279528Sbaptslide to their run-time addresses as rigid units; their length does not change 1852279528Sbaptand neither does the order of bytes within them. Such a rigid unit is called 1853279528Sbapta 1854279528Sbapt.Em section . 1855279528SbaptAssigning run-time addresses to sections is called 1856279528Sbapt.Em relocation . 1857279528SbaptIt includes the task of adjusting mentions of object-file addresses so they 1858279528Sbaptrefer to the proper run-time addresses. 1859279528Sbapt.Pp 1860279528SbaptAn object file written by 1861279528Sbapt.Xr as 1862279528Sbapthas at least three sections, any of which may be empty. These are named 1863279528Sbapt.Em text , 1864279528Sbapt.Em data 1865279528Sbaptand 1866279528Sbapt.Em bss 1867279528Sbaptsections. 1868279528Sbapt.Pp 1869279528Sbapt.Xr as 1870279528Sbaptcan also generate whatever other named sections you specify using the 1871279528Sbapt.Li .section 1872279528Sbaptdirective (see Section 1873279528Sbapt.Dq Section ) . 1874279528SbaptIf you do not use any directives that place output in the 1875279528Sbapt.Li .text 1876279528Sbaptor 1877279528Sbapt.Li .data 1878279528Sbaptsections, these sections still exist, but are empty. 1879279528Sbapt.Pp 1880279528SbaptWithin the object file, the text section starts at address 1881279528Sbapt.Li 0 , 1882279528Sbaptthe data section follows, and the bss section follows the data section. 1883279528Sbapt.Pp 1884279528SbaptTo let 1885279528Sbapt.Li ld 1886279528Sbaptknow which data changes when the sections are relocated, and how to change 1887279528Sbaptthat data, 1888279528Sbapt.Xr as 1889279528Sbaptalso writes to the object file details of the relocation needed. To perform 1890279528Sbaptrelocation 1891279528Sbapt.Li ld 1892279528Sbaptmust know, each time an address in the object file is mentioned: 1893279528Sbapt.Bl -bullet 1894279528Sbapt.It 1895279528SbaptWhere in the object file is the beginning of this reference to an address? 1896279528Sbapt.It 1897279528SbaptHow long (in bytes) is this reference? 1898279528Sbapt.It 1899279528SbaptWhich section does the address refer to? What is the numeric value of 1900279528Sbapt.Bd -filled -offset indent 1901279528Sbapt( 1902279528Sbapt.Va address ) 1903279528Sbapt\-( 1904279528Sbapt.Va start-address of section ) ? 1905279528Sbapt.Ed 1906279528Sbapt.It 1907279528SbaptIs the reference to an address \(lqProgram-Counter relative\(rq? 1908279528Sbapt.El 1909279528Sbapt.Pp 1910279528SbaptIn fact, every address 1911279528Sbapt.Xr as 1912279528Sbaptever uses is expressed as 1913279528Sbapt.Bd -filled -offset indent 1914279528Sbapt( 1915279528Sbapt.Va section ) 1916279528Sbapt+ ( 1917279528Sbapt.Va offset into section ) 1918279528Sbapt.Ed 1919279528SbaptFurther, most expressions 1920279528Sbapt.Xr as 1921279528Sbaptcomputes have this section-relative nature. 1922279528Sbapt.Pp 1923279528SbaptIn this manual we use the notation { 1924279528Sbapt.Va secname 1925279528Sbapt.Va N 1926279528Sbapt}to mean \(lqoffset 1927279528Sbapt.Va N 1928279528Sbaptinto section 1929279528Sbapt.Va secname 1930279528Sbapt\&.\(rq 1931279528Sbapt.Pp 1932279528SbaptApart from text, data and bss sections you need to know about the 1933279528Sbapt.Em absolute 1934279528Sbaptsection. When 1935279528Sbapt.Li ld 1936279528Sbaptmixes partial programs, addresses in the absolute section remain unchanged. 1937279528SbaptFor example, address 1938279528Sbapt.Li {absolute 0} 1939279528Sbaptis \(lqrelocated\(rq to run-time address 0 by 1940279528Sbapt.Li ld . 1941279528SbaptAlthough the linker never arranges two partial programs' data sections with 1942279528Sbaptoverlapping addresses after linking, 1943279528Sbapt.Em by definition 1944279528Sbapttheir absolute sections must overlap. Address 1945279528Sbapt.Li {absolute 239} 1946279528Sbaptin one part of a program is always the same address when the program is running 1947279528Sbaptas address 1948279528Sbapt.Li {absolute 239} 1949279528Sbaptin any other part of the program. 1950279528Sbapt.Pp 1951279528SbaptThe idea of sections is extended to the 1952279528Sbapt.Em undefined 1953279528Sbaptsection. Any address whose section is unknown at assembly time is by definition 1954279528Sbaptrendered {undefined 1955279528Sbapt.Va U 1956279528Sbapt}---where 1957279528Sbapt.Va U 1958279528Sbaptis filled in later. Since numbers are always defined, the only way to generate 1959279528Sbaptan undefined address is to mention an undefined symbol. A reference to a named 1960279528Sbaptcommon block would be such a symbol: its value is unknown at assembly time 1961279528Sbaptso it has section 1962279528Sbapt.Em undefined . 1963279528Sbapt.Pp 1964279528SbaptBy analogy the word 1965279528Sbapt.Em section 1966279528Sbaptis used to describe groups of sections in the linked program. 1967279528Sbapt.Li ld 1968279528Sbaptputs all partial programs' text sections in contiguous addresses in the linked 1969279528Sbaptprogram. It is customary to refer to the 1970279528Sbapt.Em text section 1971279528Sbaptof a program, meaning all the addresses of all partial programs' text sections. 1972279528SbaptLikewise for data and bss sections. 1973279528Sbapt.Pp 1974279528SbaptSome sections are manipulated by 1975279528Sbapt.Li ld ; 1976279528Sbaptothers are invented for use of 1977279528Sbapt.Xr as 1978279528Sbaptand have no meaning except during assembly. 1979279528Sbapt.Pp 1980279528Sbapt.Ss Linker Sections 1981279528Sbapt.Li ld 1982279528Sbaptdeals with just four kinds of sections, summarized below. 1983279528Sbapt.Pp 1984279528Sbapt.Bl -tag -width Ds 1985279528Sbapt.It named sections 1986279528SbaptThese sections hold your program. 1987279528Sbapt.Xr as 1988279528Sbaptand 1989279528Sbapt.Li ld 1990279528Sbapttreat them as separate but equal sections. Anything you can say of one section 1991279528Sbaptis true of another. When the program is running, however, it is customary 1992279528Sbaptfor the text section to be unalterable. The text section is often shared among 1993279528Sbaptprocesses: it contains instructions, constants and the like. The data section 1994279528Sbaptof a running program is usually alterable: for example, C variables would 1995279528Sbaptbe stored in the data section. 1996279528Sbapt.Pp 1997279528Sbapt.It bss section 1998279528SbaptThis section contains zeroed bytes when your program begins running. It is 1999279528Sbaptused to hold uninitialized variables or common storage. The length of each 2000279528Sbaptpartial program's bss section is important, but because it starts out containing 2001279528Sbaptzeroed bytes there is no need to store explicit zero bytes in the object file. 2002279528SbaptThe bss section was invented to eliminate those explicit zeros from object 2003279528Sbaptfiles. 2004279528Sbapt.Pp 2005279528Sbapt.It absolute section 2006279528SbaptAddress 0 of this section is always \(lqrelocated\(rq to runtime address 0. This is 2007279528Sbaptuseful if you want to refer to an address that 2008279528Sbapt.Li ld 2009279528Sbaptmust not change when relocating. In this sense we speak of absolute addresses 2010279528Sbaptbeing \(lqunrelocatable\(rq: they do not change during relocation. 2011279528Sbapt.Pp 2012279528Sbapt.It undefined section 2013279528SbaptThis \(lqsection\(rq is a catch-all for address references to objects not in the preceding 2014279528Sbaptsections. 2015279528Sbapt.El 2016279528Sbapt.Pp 2017279528SbaptAn idealized example of three relocatable sections follows. The example uses 2018279528Sbaptthe traditional section names 2019279528Sbapt.Li .text 2020279528Sbaptand 2021279528Sbapt.Li .data . 2022279528SbaptMemory addresses are on the horizontal axis. 2023279528Sbapt.Pp 2024279528Sbapt.Bd -literal -offset indent 2025279528Sbapt +-----+----+--+ 2026279528Sbaptpartial program # 1: |ttttt|dddd|00| 2027279528Sbapt +-----+----+--+ 2028279528Sbapt 2029279528Sbapt text data bss 2030279528Sbapt seg. seg. seg. 2031279528Sbapt 2032279528Sbapt +---+---+---+ 2033279528Sbaptpartial program # 2: |TTT|DDD|000| 2034279528Sbapt +---+---+---+ 2035279528Sbapt 2036279528Sbapt +--+---+-----+--+----+---+-----+~~ 2037279528Sbaptlinked program: | |TTT|ttttt| |dddd|DDD|00000| 2038279528Sbapt +--+---+-----+--+----+---+-----+~~ 2039279528Sbapt 2040279528Sbapt addresses: 0 ... 2041279528Sbapt.Ed 2042279528Sbapt.Pp 2043279528Sbapt.Ss Assembler Internal Sections 2044279528SbaptThese sections are meant only for the internal use of 2045279528Sbapt.Xr as . 2046279528SbaptThey have no meaning at run-time. You do not really need to know about these 2047279528Sbaptsections for most purposes; but they can be mentioned in 2048279528Sbapt.Xr as 2049279528Sbaptwarning messages, so it might be helpful to have an idea of their meanings 2050279528Sbaptto 2051279528Sbapt.Xr as . 2052279528SbaptThese sections are used to permit the value of every expression in your assembly 2053279528Sbaptlanguage program to be a section-relative address. 2054279528Sbapt.Pp 2055279528Sbapt.Bl -tag -width Ds 2056279528Sbapt.It ASSEMBLER-INTERNAL-LOGIC-ERROR! 2057279528SbaptAn internal assembler logic error has been found. This means there is a bug 2058279528Sbaptin the assembler. 2059279528Sbapt.Pp 2060279528Sbapt.It expr section 2061279528SbaptThe assembler stores complex expression internally as combinations of symbols. 2062279528SbaptWhen it needs to represent an expression as a symbol, it puts it in the expr 2063279528Sbaptsection. 2064279528Sbapt.El 2065279528Sbapt.Pp 2066279528Sbapt.Ss Sub-Sections 2067279528SbaptYou may have separate groups of data in named sections that you want to end 2068279528Sbaptup near to each other in the object file, even though they are not contiguous 2069279528Sbaptin the assembler source. 2070279528Sbapt.Xr as 2071279528Sbaptallows you to use 2072279528Sbapt.Em subsections 2073279528Sbaptfor this purpose. Within each section, there can be numbered subsections with 2074279528Sbaptvalues from 0 to 8192. Objects assembled into the same subsection go into 2075279528Sbaptthe object file together with other objects in the same subsection. For example, 2076279528Sbapta compiler might want to store constants in the text section, but might not 2077279528Sbaptwant to have them interspersed with the program being assembled. In this case, 2078279528Sbaptthe compiler could issue a 2079279528Sbapt.Li .text 0 2080279528Sbaptbefore each section of code being output, and a 2081279528Sbapt.Li .text 1 2082279528Sbaptbefore each group of constants being output. 2083279528Sbapt.Pp 2084279528SbaptSubsections are optional. If you do not use subsections, everything goes in 2085279528Sbaptsubsection number zero. 2086279528Sbapt.Pp 2087279528SbaptSubsections appear in your object file in numeric order, lowest numbered to 2088279528Sbapthighest. (All this to be compatible with other people's assemblers.) The object 2089279528Sbaptfile contains no representation of subsections; 2090279528Sbapt.Li ld 2091279528Sbaptand other programs that manipulate object files see no trace of them. They 2092279528Sbaptjust see all your text subsections as a text section, and all your data subsections 2093279528Sbaptas a data section. 2094279528Sbapt.Pp 2095279528SbaptTo specify which subsection you want subsequent statements assembled into, 2096279528Sbaptuse a numeric argument to specify it, in a 2097279528Sbapt.Li .text Va expression 2098279528Sbaptor a 2099279528Sbapt.Li .data Va expression 2100279528Sbaptstatement. You can also use the 2101279528Sbapt.Li .subsection 2102279528Sbaptdirective (see Section 2103279528Sbapt.Dq SubSection ) 2104279528Sbaptto specify a subsection: 2105279528Sbapt.Li .subsection Va expression . 2106279528Sbapt.Va Expression 2107279528Sbaptshould be an absolute expression (see Section 2108279528Sbapt.Dq Expressions ) . 2109279528SbaptIf you just say 2110279528Sbapt.Li .text 2111279528Sbaptthen 2112279528Sbapt.Li .text 0 2113279528Sbaptis assumed. Likewise 2114279528Sbapt.Li .data 2115279528Sbaptmeans 2116279528Sbapt.Li .data 0 . 2117279528SbaptAssembly begins in 2118279528Sbapt.Li text 0 . 2119279528SbaptFor instance: 2120279528Sbapt.Bd -literal -offset indent 2121279528Sbapt\&.text 0 # The default subsection is text 0 anyway. 2122279528Sbapt\&.ascii "This lives in the first text subsection. *" 2123279528Sbapt\&.text 1 2124279528Sbapt\&.ascii "But this lives in the second text subsection." 2125279528Sbapt\&.data 0 2126279528Sbapt\&.ascii "This lives in the data section," 2127279528Sbapt\&.ascii "in the first data subsection." 2128279528Sbapt\&.text 0 2129279528Sbapt\&.ascii "This lives in the first text section," 2130279528Sbapt\&.ascii "immediately following the asterisk (*)." 2131279528Sbapt.Ed 2132279528Sbapt.Pp 2133279528SbaptEach section has a 2134279528Sbapt.Em location counter 2135279528Sbaptincremented by one for every byte assembled into that section. Because subsections 2136279528Sbaptare merely a convenience restricted to 2137279528Sbapt.Xr as 2138279528Sbaptthere is no concept of a subsection location counter. There is no way to directly 2139279528Sbaptmanipulate a location counter---but the 2140279528Sbapt.Li .align 2141279528Sbaptdirective changes it, and any label definition captures its current value. 2142279528SbaptThe location counter of the section where statements are being assembled is 2143279528Sbaptsaid to be the 2144279528Sbapt.Em active 2145279528Sbaptlocation counter. 2146279528Sbapt.Pp 2147279528Sbapt.Ss bss Section 2148279528SbaptThe bss section is used for local common variable storage. You may allocate 2149279528Sbaptaddress space in the bss section, but you may not dictate data to load into 2150279528Sbaptit before your program executes. When your program starts running, all the 2151279528Sbaptcontents of the bss section are zeroed bytes. 2152279528Sbapt.Pp 2153279528SbaptThe 2154279528Sbapt.Li .lcomm 2155279528Sbaptpseudo-op defines a symbol in the bss section; see Lcomm,, 2156279528Sbapt.Li .lcomm 2157279528Sbapt\&. 2158279528Sbapt.Pp 2159279528SbaptThe 2160279528Sbapt.Li .comm 2161279528Sbaptpseudo-op may be used to declare a common symbol, which is another form of 2162279528Sbaptuninitialized symbol; see Comm,, 2163279528Sbapt.Li .comm 2164279528Sbapt\&. 2165279528Sbapt.Pp 2166279528Sbapt.Sh Symbols 2167279528SbaptSymbols are a central concept: the programmer uses symbols to name things, 2168279528Sbaptthe linker uses symbols to link, and the debugger uses symbols to debug. 2169279528Sbapt.Pp 2170279528Sbapt.Qo 2171279528Sbapt.Em Warning: 2172279528Sbapt.Xr as 2173279528Sbaptdoes not place symbols in the object file in the same order they were declared. 2174279528SbaptThis may break some debuggers. 2175279528Sbapt.Qc 2176279528Sbapt.Pp 2177279528Sbapt.Ss Labels 2178279528SbaptA 2179279528Sbapt.Em label 2180279528Sbaptis written as a symbol immediately followed by a colon 2181279528Sbapt.Li : . 2182279528SbaptThe symbol then represents the current value of the active location counter, 2183279528Sbaptand is, for example, a suitable instruction operand. You are warned if you 2184279528Sbaptuse the same symbol to represent two different locations: the first definition 2185279528Sbaptoverrides any other definitions. 2186279528Sbapt.Pp 2187279528Sbapt.Ss Giving Symbols Other Values 2188279528SbaptA symbol can be given an arbitrary value by writing a symbol, followed by 2189279528Sbaptan equals sign 2190279528Sbapt.Li = , 2191279528Sbaptfollowed by an expression (see Section 2192279528Sbapt.Dq Expressions ) . 2193279528SbaptThis is equivalent to using the 2194279528Sbapt.Li .set 2195279528Sbaptdirective.See Section 2196279528Sbapt.Dq Set . 2197279528SbaptIn the same way, using a double equals sign 2198279528Sbapt.Li = 2199279528Sbapt.Li = 2200279528Sbapthere represents an equivalent of the 2201279528Sbapt.Li .eqv 2202279528Sbaptdirective.See Section 2203279528Sbapt.Dq Eqv . 2204279528Sbapt.Pp 2205279528Sbapt.Ss Symbol Names 2206279528SbaptSymbol names begin with a letter or with one of 2207279528Sbapt.Li ._ . 2208279528SbaptOn most machines, you can also use 2209279528Sbapt.Li $ 2210279528Sbaptin symbol names; exceptions are noted in Machine Dependencies. That character 2211279528Sbaptmay be followed by any string of digits, letters, dollar signs (unless otherwise 2212279528Sbaptnoted for a particular target machine), and underscores. 2213279528Sbapt.Pp 2214279528SbaptCase of letters is significant: 2215279528Sbapt.Li foo 2216279528Sbaptis a different symbol name than 2217279528Sbapt.Li Foo . 2218279528Sbapt.Pp 2219279528SbaptEach symbol has exactly one name. Each name in an assembly language program 2220279528Sbaptrefers to exactly one symbol. You may use that symbol name any number of times 2221279528Sbaptin a program. 2222279528Sbapt.Pp 2223279528Sbapt.Em Local Symbol Names 2224279528Sbapt.Pp 2225279528SbaptA local symbol is any symbol beginning with certain local label prefixes. 2226279528SbaptBy default, the local label prefix is 2227279528Sbapt.Li .L 2228279528Sbaptfor ELF systems or 2229279528Sbapt.Li L 2230279528Sbaptfor traditional a.out systems, but each target may have its own set of local 2231279528Sbaptlabel prefixes. 2232279528Sbapt.Pp 2233279528SbaptLocal symbols are defined and used within the assembler, but they are normally 2234279528Sbaptnot saved in object files. Thus, they are not visible when debugging. You 2235279528Sbaptmay use the 2236279528Sbapt.Li -L 2237279528Sbaptoption (see Section 2238279528Sbapt.Dq L ) 2239279528Sbaptto retain the local symbols in the object files. 2240279528Sbapt.Pp 2241279528Sbapt.Em Local Labels 2242279528Sbapt.Pp 2243279528SbaptLocal labels help compilers and programmers use names temporarily. They create 2244279528Sbaptsymbols which are guaranteed to be unique over the entire scope of the input 2245279528Sbaptsource code and which can be referred to by a simple notation. To define a 2246279528Sbaptlocal label, write a label of the form 2247279528Sbapt.Li Sy N: 2248279528Sbapt(where 2249279528Sbapt.Sy N 2250279528Sbaptrepresents any positive integer). To refer to the most recent previous definition 2251279528Sbaptof that label write 2252279528Sbapt.Li Sy Nb , 2253279528Sbaptusing the same number as when you defined the label. To refer to the next 2254279528Sbaptdefinition of a local label, write 2255279528Sbapt.Li Sy Nf 2256279528Sbapt---the 2257279528Sbapt.Li b 2258279528Sbaptstands for \(lqbackwards\(rq and the 2259279528Sbapt.Li f 2260279528Sbaptstands for \(lqforwards\(rq. 2261279528Sbapt.Pp 2262279528SbaptThere is no restriction on how you can use these labels, and you can reuse 2263279528Sbaptthem too. So that it is possible to repeatedly define the same local label 2264279528Sbapt(using the same number 2265279528Sbapt.Li Sy N ) , 2266279528Sbaptalthough you can only refer to the most recently defined local label of that 2267279528Sbaptnumber (for a backwards reference) or the next definition of a specific local 2268279528Sbaptlabel for a forward reference. It is also worth noting that the first 10 local 2269279528Sbaptlabels ( 2270279528Sbapt.Li Sy 0: 2271279528Sbapt\&....Li Sy 9: ) 2272279528Sbaptare implemented in a slightly more efficient manner than the others. 2273279528Sbapt.Pp 2274279528SbaptHere is an example: 2275279528Sbapt.Pp 2276279528Sbapt.Bd -literal -offset indent 2277279528Sbapt1: branch 1f 2278279528Sbapt2: branch 1b 2279279528Sbapt1: branch 2f 2280279528Sbapt2: branch 1b 2281279528Sbapt.Ed 2282279528Sbapt.Pp 2283279528SbaptWhich is the equivalent of: 2284279528Sbapt.Pp 2285279528Sbapt.Bd -literal -offset indent 2286279528Sbaptlabel_1: branch label_3 2287279528Sbaptlabel_2: branch label_1 2288279528Sbaptlabel_3: branch label_4 2289279528Sbaptlabel_4: branch label_3 2290279528Sbapt.Ed 2291279528Sbapt.Pp 2292279528SbaptLocal label names are only a notational device. They are immediately transformed 2293279528Sbaptinto more conventional symbol names before the assembler uses them. The symbol 2294279528Sbaptnames are stored in the symbol table, appear in error messages, and are optionally 2295279528Sbaptemitted to the object file. The names are constructed using these parts: 2296279528Sbapt.Pp 2297279528Sbapt.Bl -tag -width Ds 2298279528Sbapt.It Em local label prefix 2299279528SbaptAll local symbols begin with the system-specific local label prefix. Normally 2300279528Sbaptboth 2301279528Sbapt.Xr as 2302279528Sbaptand 2303279528Sbapt.Li ld 2304279528Sbaptforget symbols that start with the local label prefix. These labels are used 2305279528Sbaptfor symbols you are never intended to see. If you use the 2306279528Sbapt.Li -L 2307279528Sbaptoption then 2308279528Sbapt.Xr as 2309279528Sbaptretains these symbols in the object file. If you also instruct 2310279528Sbapt.Li ld 2311279528Sbaptto retain these symbols, you may use them in debugging. 2312279528Sbapt.Pp 2313279528Sbapt.It Va number 2314279528SbaptThis is the number that was used in the local label definition. So if the 2315279528Sbaptlabel is written 2316279528Sbapt.Li 55: 2317279528Sbaptthen the number is 2318279528Sbapt.Li 55 . 2319279528Sbapt.Pp 2320279528Sbapt.It Li C-B 2321279528SbaptThis unusual character is included so you do not accidentally invent a symbol 2322279528Sbaptof the same name. The character has ASCII value of 2323279528Sbapt.Li \e002 2324279528Sbapt(control-B). 2325279528Sbapt.Pp 2326279528Sbapt.It Em ordinal number 2327279528SbaptThis is a serial number to keep the labels distinct. The first definition 2328279528Sbaptof 2329279528Sbapt.Li 0: 2330279528Sbaptgets the number 2331279528Sbapt.Li 1 . 2332279528SbaptThe 15th definition of 2333279528Sbapt.Li 0: 2334279528Sbaptgets the number 2335279528Sbapt.Li 15 , 2336279528Sbaptand so on. Likewise the first definition of 2337279528Sbapt.Li 1: 2338279528Sbaptgets the number 2339279528Sbapt.Li 1 2340279528Sbaptand its 15th definition gets 2341279528Sbapt.Li 15 2342279528Sbaptas well. 2343279528Sbapt.El 2344279528Sbapt.Pp 2345279528SbaptSo for example, the first 2346279528Sbapt.Li 1: 2347279528Sbaptmay be named 2348279528Sbapt.Li .L1 Li C-B1 , 2349279528Sbaptand the 44th 2350279528Sbapt.Li 3: 2351279528Sbaptmay be named 2352279528Sbapt.Li .L3 Li C-B44 . 2353279528Sbapt.Pp 2354279528Sbapt.Em Dollar Local Labels 2355279528Sbapt.Pp 2356279528Sbapt.Li as 2357279528Sbaptalso supports an even more local form of local labels called dollar labels. 2358279528SbaptThese labels go out of scope (i.e., they become undefined) as soon as a non-local 2359279528Sbaptlabel is defined. Thus they remain valid for only a small region of the input 2360279528Sbaptsource code. Normal local labels, by contrast, remain in scope for the entire 2361279528Sbaptfile, or until they are redefined by another occurrence of the same local 2362279528Sbaptlabel. 2363279528Sbapt.Pp 2364279528SbaptDollar labels are defined in exactly the same way as ordinary local labels, 2365279528Sbaptexcept that instead of being terminated by a colon, they are terminated by 2366279528Sbapta dollar sign, e.g., 2367279528Sbapt.Li Sy 55$ . 2368279528Sbapt.Pp 2369279528SbaptThey can also be distinguished from ordinary local labels by their transformed 2370279528Sbaptnames which use ASCII character 2371279528Sbapt.Li \e001 2372279528Sbapt(control-A) as the magic character to distinguish them from ordinary labels. 2373279528SbaptFor example, the fifth definition of 2374279528Sbapt.Li 6$ 2375279528Sbaptmay be named 2376279528Sbapt.Li .L6 Li C-A5 . 2377279528Sbapt.Pp 2378279528Sbapt.Ss The Special Dot Symbol 2379279528SbaptThe special symbol 2380279528Sbapt.Li . 2381279528Sbaptrefers to the current address that 2382279528Sbapt.Xr as 2383279528Sbaptis assembling into. Thus, the expression 2384279528Sbapt.Li melvin: .long . 2385279528Sbaptdefines 2386279528Sbapt.Li melvin 2387279528Sbaptto contain its own address. Assigning a value to 2388279528Sbapt.Li . 2389279528Sbaptis treated the same as a 2390279528Sbapt.Li .org 2391279528Sbaptdirective. Thus, the expression 2392279528Sbapt.Li .=.+4 2393279528Sbaptis the same as saying 2394279528Sbapt.Li .space 4 . 2395279528Sbapt.Pp 2396279528Sbapt.Ss Symbol Attributes 2397279528SbaptEvery symbol has, as well as its name, the attributes \(lqValue\(rq and \(lqType\(rq. Depending 2398279528Sbapton output format, symbols can also have auxiliary attributes. The detailed 2399279528Sbaptdefinitions are in 2400279528Sbapt.Pa a.out.h . 2401279528Sbapt.Pp 2402279528SbaptIf you use a symbol without defining it, 2403279528Sbapt.Xr as 2404279528Sbaptassumes zero for all these attributes, and probably won't warn you. This makes 2405279528Sbaptthe symbol an externally defined symbol, which is generally what you would 2406279528Sbaptwant. 2407279528Sbapt.Pp 2408279528Sbapt.Em Value 2409279528Sbapt.Pp 2410279528SbaptThe value of a symbol is (usually) 32 bits. For a symbol which labels a location 2411279528Sbaptin the text, data, bss or absolute sections the value is the number of addresses 2412279528Sbaptfrom the start of that section to the label. Naturally for text, data and 2413279528Sbaptbss sections the value of a symbol changes as 2414279528Sbapt.Li ld 2415279528Sbaptchanges section base addresses during linking. Absolute symbols' values do 2416279528Sbaptnot change during linking: that is why they are called absolute. 2417279528Sbapt.Pp 2418279528SbaptThe value of an undefined symbol is treated in a special way. If it is 0 then 2419279528Sbaptthe symbol is not defined in this assembler source file, and 2420279528Sbapt.Li ld 2421279528Sbapttries to determine its value from other files linked into the same program. 2422279528SbaptYou make this kind of symbol simply by mentioning a symbol name without defining 2423279528Sbaptit. A non-zero value represents a 2424279528Sbapt.Li .comm 2425279528Sbaptcommon declaration. The value is how much common storage to reserve, in bytes 2426279528Sbapt(addresses). The symbol refers to the first address of the allocated storage. 2427279528Sbapt.Pp 2428279528Sbapt.Em Type 2429279528Sbapt.Pp 2430279528SbaptThe type attribute of a symbol contains relocation (section) information, 2431279528Sbaptany flag settings indicating that a symbol is external, and (optionally), 2432279528Sbaptother information for linkers and debuggers. The exact format depends on the 2433279528Sbaptobject-code output format in use. 2434279528Sbapt.Pp 2435279528Sbapt.Sh Expressions 2436279528SbaptAn 2437279528Sbapt.Em expression 2438279528Sbaptspecifies an address or numeric value. Whitespace may precede and/or follow 2439279528Sbaptan expression. 2440279528Sbapt.Pp 2441279528SbaptThe result of an expression must be an absolute number, or else an offset 2442279528Sbaptinto a particular section. If an expression is not absolute, and there is 2443279528Sbaptnot enough information when 2444279528Sbapt.Xr as 2445279528Sbaptsees the expression to know its section, a second pass over the source program 2446279528Sbaptmight be necessary to interpret the expression---but the second pass is currently 2447279528Sbaptnot implemented. 2448279528Sbapt.Xr as 2449279528Sbaptaborts with an error message in this situation. 2450279528Sbapt.Pp 2451279528Sbapt.Ss Empty Expressions 2452279528SbaptAn empty expression has no value: it is just whitespace or null. Wherever 2453279528Sbaptan absolute expression is required, you may omit the expression, and 2454279528Sbapt.Xr as 2455279528Sbaptassumes a value of (absolute) 0. This is compatible with other assemblers. 2456279528Sbapt.Pp 2457279528Sbapt.Ss Integer Expressions 2458279528SbaptAn 2459279528Sbapt.Em integer expression 2460279528Sbaptis one or more 2461279528Sbapt.Em arguments 2462279528Sbaptdelimited by 2463279528Sbapt.Em operators . 2464279528Sbapt.Pp 2465279528Sbapt.Em Arguments 2466279528Sbapt.Pp 2467279528Sbapt.Em Arguments 2468279528Sbaptare symbols, numbers or subexpressions. In other contexts arguments are sometimes 2469279528Sbaptcalled \(lqarithmetic operands\(rq. In this manual, to avoid confusing them with the 2470279528Sbapt\(lqinstruction operands\(rq of the machine language, we use the term \(lqargument\(rq to 2471279528Sbaptrefer to parts of expressions only, reserving the word \(lqoperand\(rq to refer only 2472279528Sbaptto machine instruction operands. 2473279528Sbapt.Pp 2474279528SbaptSymbols are evaluated to yield { 2475279528Sbapt.Va section 2476279528Sbapt.Va NNN 2477279528Sbapt}where 2478279528Sbapt.Va section 2479279528Sbaptis one of text, data, bss, absolute, or undefined. 2480279528Sbapt.Va NNN 2481279528Sbaptis a signed, 2's complement 32 bit integer. 2482279528Sbapt.Pp 2483279528SbaptNumbers are usually integers. 2484279528Sbapt.Pp 2485279528SbaptA number can be a flonum or biGNUm. In this case, you are warned that only 2486279528Sbaptthe low order 32 bits are used, and 2487279528Sbapt.Xr as 2488279528Sbaptpretends these 32 bits are an integer. You may write integer-manipulating 2489279528Sbaptinstructions that act on exotic constants, compatible with other assemblers. 2490279528Sbapt.Pp 2491279528SbaptSubexpressions are a left parenthesis 2492279528Sbapt.Li ( 2493279528Sbaptfollowed by an integer expression, followed by a right parenthesis 2494279528Sbapt.Li ) ; 2495279528Sbaptor a prefix operator followed by an argument. 2496279528Sbapt.Pp 2497279528Sbapt.Em Operators 2498279528Sbapt.Pp 2499279528Sbapt.Em Operators 2500279528Sbaptare arithmetic functions, like 2501279528Sbapt.Li + 2502279528Sbaptor 2503279528Sbapt.Li % . 2504279528SbaptPrefix operators are followed by an argument. Infix operators appear between 2505279528Sbapttheir arguments. Operators may be preceded and/or followed by whitespace. 2506279528Sbapt.Pp 2507279528Sbapt.Em Prefix Operator 2508279528Sbapt.Pp 2509279528Sbapt.Xr as 2510279528Sbapthas the following 2511279528Sbapt.Em prefix operators . 2512279528SbaptThey each take one argument, which must be absolute. 2513279528Sbapt.Pp 2514279528Sbapt.Bl -tag -width Ds 2515279528Sbapt.It - 2516279528Sbapt.Em Negation . 2517279528SbaptTwo's complement negation. 2518279528Sbapt.It ~ 2519279528Sbapt.Em Complementation . 2520279528SbaptBitwise not. 2521279528Sbapt.El 2522279528Sbapt.Pp 2523279528Sbapt.Em Infix Operators 2524279528Sbapt.Pp 2525279528Sbapt.Em Infix operators 2526279528Sbapttake two arguments, one on either side. Operators have precedence, but operations 2527279528Sbaptwith equal precedence are performed left to right. Apart from 2528279528Sbapt.Li + 2529279528Sbaptor 2530279528Sbapt.Op - , 2531279528Sbaptboth arguments must be absolute, and the result is absolute. 2532279528Sbapt.Pp 2533279528Sbapt.Bl -enum 2534279528Sbapt.It 2535279528SbaptHighest Precedence 2536279528Sbapt.Pp 2537279528Sbapt.Bl -tag -width Ds 2538279528Sbapt.It * 2539279528Sbapt.Em Multiplication . 2540279528Sbapt.Pp 2541279528Sbapt.It / 2542279528Sbapt.Em Division . 2543279528SbaptTruncation is the same as the C operator 2544279528Sbapt.Li / 2545279528Sbapt.Pp 2546279528Sbapt.It % 2547279528Sbapt.Em Remainder . 2548279528Sbapt.Pp 2549279528Sbapt.It << 2550279528Sbapt.Em Shift Left . 2551279528SbaptSame as the C operator 2552279528Sbapt.Li << . 2553279528Sbapt.Pp 2554279528Sbapt.It >> 2555279528Sbapt.Em Shift Right . 2556279528SbaptSame as the C operator 2557279528Sbapt.Li >> . 2558279528Sbapt.El 2559279528Sbapt.Pp 2560279528Sbapt.It 2561279528SbaptIntermediate precedence 2562279528Sbapt.Pp 2563279528Sbapt.Bl -tag -width Ds 2564279528Sbapt.It | 2565279528Sbapt.Pp 2566279528Sbapt.Em Bitwise Inclusive Or . 2567279528Sbapt.Pp 2568279528Sbapt.It & 2569279528Sbapt.Em Bitwise And . 2570279528Sbapt.Pp 2571279528Sbapt.It ^ 2572279528Sbapt.Em Bitwise Exclusive Or . 2573279528Sbapt.Pp 2574279528Sbapt.It ! 2575279528Sbapt.Em Bitwise Or Not . 2576279528Sbapt.El 2577279528Sbapt.Pp 2578279528Sbapt.It 2579279528SbaptLow Precedence 2580279528Sbapt.Pp 2581279528Sbapt.Bl -tag -width Ds 2582279528Sbapt.It + 2583279528Sbapt.Em Addition . 2584279528SbaptIf either argument is absolute, the result has the section of the other argument. 2585279528SbaptYou may not add together arguments from different sections. 2586279528Sbapt.Pp 2587279528Sbapt.It - 2588279528Sbapt.Em Subtraction . 2589279528SbaptIf the right argument is absolute, the result has the section of the left 2590279528Sbaptargument. If both arguments are in the same section, the result is absolute. 2591279528SbaptYou may not subtract arguments from different sections. 2592279528Sbapt.Pp 2593279528Sbapt.It == 2594279528Sbapt.Em Is Equal To 2595279528Sbapt.It <> 2596279528Sbapt.It != 2597279528Sbapt.Em Is Not Equal To 2598279528Sbapt.It < 2599279528Sbapt.Em Is Less Than 2600279528Sbapt.It > 2601279528Sbapt.Em Is Greater Than 2602279528Sbapt.It >= 2603279528Sbapt.Em Is Greater Than Or Equal To 2604279528Sbapt.It <= 2605279528Sbapt.Em Is Less Than Or Equal To 2606279528Sbapt.Pp 2607279528SbaptThe comparison operators can be used as infix operators. A true results has 2608279528Sbapta value of -1 whereas a false result has a value of 0. Note, these operators 2609279528Sbaptperform signed comparisons. 2610279528Sbapt.El 2611279528Sbapt.Pp 2612279528Sbapt.It 2613279528SbaptLowest Precedence 2614279528Sbapt.Pp 2615279528Sbapt.Bl -tag -width Ds 2616279528Sbapt.It && 2617279528Sbapt.Em Logical And . 2618279528Sbapt.Pp 2619279528Sbapt.It || 2620279528Sbapt.Em Logical Or . 2621279528Sbapt.Pp 2622279528SbaptThese two logical operations can be used to combine the results of sub expressions. 2623279528SbaptNote, unlike the comparison operators a true result returns a value of 1 but 2624279528Sbapta false results does still return 0. Also note that the logical or operator 2625279528Sbapthas a slightly lower precedence than logical and. 2626279528Sbapt.Pp 2627279528Sbapt.El 2628279528Sbapt.El 2629279528SbaptIn short, it's only meaningful to add or subtract the 2630279528Sbapt.Em offsets 2631279528Sbaptin an address; you can only have a defined section in one of the two arguments. 2632279528Sbapt.Pp 2633279528Sbapt.Sh Assembler Directives 2634279528SbaptAll assembler directives have names that begin with a period ( 2635279528Sbapt.Li . ) . 2636279528SbaptThe rest of the name is letters, usually in lower case. 2637279528Sbapt.Pp 2638279528SbaptThis chapter discusses directives that are available regardless of the target 2639279528Sbaptmachine configuration for the GNU assembler. 2640279528Sbapt.Pp 2641279528Sbapt.Ss Li .abort 2642279528SbaptThis directive stops the assembly immediately. It is for compatibility with 2643279528Sbaptother assemblers. The original idea was that the assembly language source 2644279528Sbaptwould be piped into the assembler. If the sender of the source quit, it could 2645279528Sbaptuse this directive tells 2646279528Sbapt.Xr as 2647279528Sbaptto quit also. One day 2648279528Sbapt.Li .abort 2649279528Sbaptwill not be supported. 2650279528Sbapt.Pp 2651279528Sbapt.Ss Li .align Va abs-expr, Va abs-expr, Va abs-expr 2652279528SbaptPad the location counter (in the current subsection) to a particular storage 2653279528Sbaptboundary. The first expression (which must be absolute) is the alignment required, 2654279528Sbaptas described below. 2655279528Sbapt.Pp 2656279528SbaptThe second expression (also absolute) gives the fill value to be stored in 2657279528Sbaptthe padding bytes. It (and the comma) may be omitted. If it is omitted, the 2658279528Sbaptpadding bytes are normally zero. However, on some systems, if the section 2659279528Sbaptis marked as containing code and the fill value is omitted, the space is filled 2660279528Sbaptwith no-op instructions. 2661279528Sbapt.Pp 2662279528SbaptThe third expression is also absolute, and is also optional. If it is present, 2663279528Sbaptit is the maximum number of bytes that should be skipped by this alignment 2664279528Sbaptdirective. If doing the alignment would require skipping more bytes than the 2665279528Sbaptspecified maximum, then the alignment is not done at all. You can omit the 2666279528Sbaptfill value (the second argument) entirely by simply using two commas after 2667279528Sbaptthe required alignment; this can be useful if you want the alignment to be 2668279528Sbaptfilled with no-op instructions when appropriate. 2669279528Sbapt.Pp 2670279528SbaptThe way the required alignment is specified varies from system to system. 2671279528SbaptFor the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, s390, sparc, 2672279528Sbapttic4x, tic80 and xtensa, the first expression is the alignment request in 2673279528Sbaptbytes. For example 2674279528Sbapt.Li .align 8 2675279528Sbaptadvances the location counter until it is a multiple of 8. If the location 2676279528Sbaptcounter is already a multiple of 8, no change is needed. For the tic54x, the 2677279528Sbaptfirst expression is the alignment request in words. 2678279528Sbapt.Pp 2679279528SbaptFor other systems, including the i386 using a.out format, and the arm and 2680279528Sbaptstrongarm, it is the number of low-order zero bits the location counter must 2681279528Sbapthave after advancement. For example 2682279528Sbapt.Li .align 3 2683279528Sbaptadvances the location counter until it a multiple of 8. If the location counter 2684279528Sbaptis already a multiple of 8, no change is needed. 2685279528Sbapt.Pp 2686279528SbaptThis inconsistency is due to the different behaviors of the various native 2687279528Sbaptassemblers for these systems which GAS must emulate. GAS also provides 2688279528Sbapt.Li .balign 2689279528Sbaptand 2690279528Sbapt.Li .p2align 2691279528Sbaptdirectives, described later, which have a consistent behavior across all architectures 2692279528Sbapt(but are specific to GAS). 2693279528Sbapt.Pp 2694279528Sbapt.Ss Li .ascii " Va string"... 2695279528Sbapt.Li .ascii 2696279528Sbaptexpects zero or more string literals (see Section 2697279528Sbapt.Dq Strings ) 2698279528Sbaptseparated by commas. It assembles each string (with no automatic trailing 2699279528Sbaptzero byte) into consecutive addresses. 2700279528Sbapt.Pp 2701279528Sbapt.Ss Li .asciz " Va string"... 2702279528Sbapt.Li .asciz 2703279528Sbaptis just like 2704279528Sbapt.Li .ascii , 2705279528Sbaptbut each string is followed by a zero byte. The \(lqz\(rq in 2706279528Sbapt.Li .asciz 2707279528Sbaptstands for \(lqzero\(rq. 2708279528Sbapt.Pp 2709279528Sbapt.Ss Li .balign[wl] Va abs-expr, Va abs-expr, Va abs-expr 2710279528SbaptPad the location counter (in the current subsection) to a particular storage 2711279528Sbaptboundary. The first expression (which must be absolute) is the alignment request 2712279528Sbaptin bytes. For example 2713279528Sbapt.Li .balign 8 2714279528Sbaptadvances the location counter until it is a multiple of 8. If the location 2715279528Sbaptcounter is already a multiple of 8, no change is needed. 2716279528Sbapt.Pp 2717279528SbaptThe second expression (also absolute) gives the fill value to be stored in 2718279528Sbaptthe padding bytes. It (and the comma) may be omitted. If it is omitted, the 2719279528Sbaptpadding bytes are normally zero. However, on some systems, if the section 2720279528Sbaptis marked as containing code and the fill value is omitted, the space is filled 2721279528Sbaptwith no-op instructions. 2722279528Sbapt.Pp 2723279528SbaptThe third expression is also absolute, and is also optional. If it is present, 2724279528Sbaptit is the maximum number of bytes that should be skipped by this alignment 2725279528Sbaptdirective. If doing the alignment would require skipping more bytes than the 2726279528Sbaptspecified maximum, then the alignment is not done at all. You can omit the 2727279528Sbaptfill value (the second argument) entirely by simply using two commas after 2728279528Sbaptthe required alignment; this can be useful if you want the alignment to be 2729279528Sbaptfilled with no-op instructions when appropriate. 2730279528Sbapt.Pp 2731279528SbaptThe 2732279528Sbapt.Li .balignw 2733279528Sbaptand 2734279528Sbapt.Li .balignl 2735279528Sbaptdirectives are variants of the 2736279528Sbapt.Li .balign 2737279528Sbaptdirective. The 2738279528Sbapt.Li .balignw 2739279528Sbaptdirective treats the fill pattern as a two byte word value. The 2740279528Sbapt.Li .balignl 2741279528Sbaptdirectives treats the fill pattern as a four byte longword value. For example, 2742279528Sbapt.Li .balignw 4,0x368d 2743279528Sbaptwill align to a multiple of 4. If it skips two bytes, they will be filled 2744279528Sbaptin with the value 0x368d (the exact placement of the bytes depends upon the 2745279528Sbaptendianness of the processor). If it skips 1 or 3 bytes, the fill value is 2746279528Sbaptundefined. 2747279528Sbapt.Pp 2748279528Sbapt.Ss Li .byte Va expressions 2749279528Sbapt.Li .byte 2750279528Sbaptexpects zero or more expressions, separated by commas. Each expression is 2751279528Sbaptassembled into the next byte. 2752279528Sbapt.Pp 2753279528Sbapt.Ss Li .comm Va symbol , Va length 2754279528Sbapt.Li .comm 2755279528Sbaptdeclares a common symbol named 2756279528Sbapt.Va symbol . 2757279528SbaptWhen linking, a common symbol in one object file may be merged with a defined 2758279528Sbaptor common symbol of the same name in another object file. If 2759279528Sbapt.Li ld 2760279528Sbaptdoes not see a definition for the symbol--just one or more common symbols--then 2761279528Sbaptit will allocate 2762279528Sbapt.Va length 2763279528Sbaptbytes of uninitialized memory. 2764279528Sbapt.Va length 2765279528Sbaptmust be an absolute expression. If 2766279528Sbapt.Li ld 2767279528Sbaptsees multiple common symbols with the same name, and they do not all have 2768279528Sbaptthe same size, it will allocate space using the largest size. 2769279528Sbapt.Pp 2770279528SbaptWhen using ELF, the 2771279528Sbapt.Li .comm 2772279528Sbaptdirective takes an optional third argument. This is the desired alignment 2773279528Sbaptof the symbol, specified as a byte boundary (for example, an alignment of 2774279528Sbapt16 means that the least significant 4 bits of the address should be zero). 2775279528SbaptThe alignment must be an absolute expression, and it must be a power of two. 2776279528SbaptIf 2777279528Sbapt.Li ld 2778279528Sbaptallocates uninitialized memory for the common symbol, it will use the alignment 2779279528Sbaptwhen placing the symbol. If no alignment is specified, 2780279528Sbapt.Xr as 2781279528Sbaptwill set the alignment to the largest power of two less than or equal to the 2782279528Sbaptsize of the symbol, up to a maximum of 16. 2783279528Sbapt.Pp 2784279528Sbapt.Ss Li .cfi_startproc [simple] 2785279528Sbapt.Li .cfi_startproc 2786279528Sbaptis used at the beginning of each function that should have an entry in 2787279528Sbapt.Li .eh_frame . 2788279528SbaptIt initializes some internal data structures. Don't forget to close the function 2789279528Sbaptby 2790279528Sbapt.Li .cfi_endproc . 2791279528Sbapt.Pp 2792279528SbaptUnless 2793279528Sbapt.Li .cfi_startproc 2794279528Sbaptis used along with parameter 2795279528Sbapt.Li simple 2796279528Sbaptit also emits some architecture dependent initial CFI instructions. 2797279528Sbapt.Ss Li .cfi_endproc 2798279528Sbapt.Li .cfi_endproc 2799279528Sbaptis used at the end of a function where it closes its unwind entry previously 2800279528Sbaptopened by 2801279528Sbapt.Li .cfi_startproc , 2802279528Sbaptand emits it to 2803279528Sbapt.Li .eh_frame . 2804279528Sbapt.Pp 2805279528Sbapt.Ss Li .cfi_personality Va encoding [, Va exp] 2806279528Sbapt.Li .cfi_personality 2807279528Sbaptdefines personality routine and its encoding. 2808279528Sbapt.Va encoding 2809279528Sbaptmust be a constant determining how the personality should be encoded. If it 2810279528Sbaptis 255 ( 2811279528Sbapt.Li DW_EH_PE_omit ) , 2812279528Sbaptsecond argument is not present, otherwise second argument should be a constant 2813279528Sbaptor a symbol name. When using indirect encodings, the symbol provided should 2814279528Sbaptbe the location where personality can be loaded from, not the personality 2815279528Sbaptroutine itself. The default after 2816279528Sbapt.Li .cfi_startproc 2817279528Sbaptis 2818279528Sbapt.Li .cfi_personality 0xff , 2819279528Sbaptno personality routine. 2820279528Sbapt.Pp 2821279528Sbapt.Ss Li .cfi_lsda Va encoding [, Va exp] 2822279528Sbapt.Li .cfi_lsda 2823279528Sbaptdefines LSDA and its encoding. 2824279528Sbapt.Va encoding 2825279528Sbaptmust be a constant determining how the LSDA should be encoded. If it is 255 2826279528Sbapt( 2827279528Sbapt.Li DW_EH_PE_omit ) , 2828279528Sbaptsecond argument is not present, otherwise second argument should be a constant 2829279528Sbaptor a symbol name. The default after 2830279528Sbapt.Li .cfi_startproc 2831279528Sbaptis 2832279528Sbapt.Li .cfi_lsda 0xff , 2833279528Sbaptno LSDA. 2834279528Sbapt.Pp 2835279528Sbapt.Ss Li .cfi_def_cfa Va register, Va offset 2836279528Sbapt.Li .cfi_def_cfa 2837279528Sbaptdefines a rule for computing CFA as: 2838279528Sbapt.Em take address from Va register and add Va offset to it . 2839279528Sbapt.Pp 2840279528Sbapt.Ss Li .cfi_def_cfa_register Va register 2841279528Sbapt.Li .cfi_def_cfa_register 2842279528Sbaptmodifies a rule for computing CFA. From now on 2843279528Sbapt.Va register 2844279528Sbaptwill be used instead of the old one. Offset remains the same. 2845279528Sbapt.Pp 2846279528Sbapt.Ss Li .cfi_def_cfa_offset Va offset 2847279528Sbapt.Li .cfi_def_cfa_offset 2848279528Sbaptmodifies a rule for computing CFA. Register remains the same, but 2849279528Sbapt.Va offset 2850279528Sbaptis new. Note that it is the absolute offset that will be added to a defined 2851279528Sbaptregister to compute CFA address. 2852279528Sbapt.Pp 2853279528Sbapt.Ss Li .cfi_adjust_cfa_offset Va offset 2854279528SbaptSame as 2855279528Sbapt.Li .cfi_def_cfa_offset 2856279528Sbaptbut 2857279528Sbapt.Va offset 2858279528Sbaptis a relative value that is added/substracted from the previous offset. 2859279528Sbapt.Pp 2860279528Sbapt.Ss Li .cfi_offset Va register, Va offset 2861279528SbaptPrevious value of 2862279528Sbapt.Va register 2863279528Sbaptis saved at offset 2864279528Sbapt.Va offset 2865279528Sbaptfrom CFA. 2866279528Sbapt.Pp 2867279528Sbapt.Ss Li .cfi_rel_offset Va register, Va offset 2868279528SbaptPrevious value of 2869279528Sbapt.Va register 2870279528Sbaptis saved at offset 2871279528Sbapt.Va offset 2872279528Sbaptfrom the current CFA register. This is transformed to 2873279528Sbapt.Li .cfi_offset 2874279528Sbaptusing the known displacement of the CFA register from the CFA. This is often 2875279528Sbapteasier to use, because the number will match the code it's annotating. 2876279528Sbapt.Pp 2877279528Sbapt.Ss Li .cfi_register Va register1, Va register2 2878279528SbaptPrevious value of 2879279528Sbapt.Va register1 2880279528Sbaptis saved in register 2881279528Sbapt.Va register2 . 2882279528Sbapt.Pp 2883279528Sbapt.Ss Li .cfi_restore Va register 2884279528Sbapt.Li .cfi_restore 2885279528Sbaptsays that the rule for 2886279528Sbapt.Va register 2887279528Sbaptis now the same as it was at the beginning of the function, after all initial 2888279528Sbaptinstruction added by 2889279528Sbapt.Li .cfi_startproc 2890279528Sbaptwere executed. 2891279528Sbapt.Pp 2892279528Sbapt.Ss Li .cfi_undefined Va register 2893279528SbaptFrom now on the previous value of 2894279528Sbapt.Va register 2895279528Sbaptcan't be restored anymore. 2896279528Sbapt.Pp 2897279528Sbapt.Ss Li .cfi_same_value Va register 2898279528SbaptCurrent value of 2899279528Sbapt.Va register 2900279528Sbaptis the same like in the previous frame, i.e. no restoration needed. 2901279528Sbapt.Pp 2902279528Sbapt.Ss Li .cfi_remember_state, 2903279528SbaptFirst save all current rules for all registers by 2904279528Sbapt.Li .cfi_remember_state , 2905279528Sbaptthen totally screw them up by subsequent 2906279528Sbapt.Li .cfi_* 2907279528Sbaptdirectives and when everything is hopelessly bad, use 2908279528Sbapt.Li .cfi_restore_state 2909279528Sbaptto restore the previous saved state. 2910279528Sbapt.Pp 2911279528Sbapt.Ss Li .cfi_return_column Va register 2912279528SbaptChange return column 2913279528Sbapt.Va register , 2914279528Sbapti.e. the return address is either directly in 2915279528Sbapt.Va register 2916279528Sbaptor can be accessed by rules for 2917279528Sbapt.Va register . 2918279528Sbapt.Pp 2919279528Sbapt.Ss Li .cfi_signal_frame 2920279528SbaptMark current function as signal trampoline. 2921279528Sbapt.Pp 2922279528Sbapt.Ss Li .cfi_window_save 2923279528SbaptSPARC register window has been saved. 2924279528Sbapt.Pp 2925279528Sbapt.Ss Li .cfi_escape Va expression[, ...] 2926279528SbaptAllows the user to add arbitrary bytes to the unwind info. One might use this 2927279528Sbaptto add OS-specific CFI opcodes, or generic CFI opcodes that GAS does not yet 2928279528Sbaptsupport. 2929279528Sbapt.Pp 2930279528Sbapt.Ss Li .file Va fileno Va filename 2931279528SbaptWhen emitting dwarf2 line number information 2932279528Sbapt.Li .file 2933279528Sbaptassigns filenames to the 2934279528Sbapt.Li .debug_line 2935279528Sbaptfile name table. The 2936279528Sbapt.Va fileno 2937279528Sbaptoperand should be a unique positive integer to use as the index of the entry 2938279528Sbaptin the table. The 2939279528Sbapt.Va filename 2940279528Sbaptoperand is a C string literal. 2941279528Sbapt.Pp 2942279528SbaptThe detail of filename indices is exposed to the user because the filename 2943279528Sbapttable is shared with the 2944279528Sbapt.Li .debug_info 2945279528Sbaptsection of the dwarf2 debugging information, and thus the user must know the 2946279528Sbaptexact indices that table entries will have. 2947279528Sbapt.Pp 2948279528Sbapt.Ss Li .loc Va fileno Va lineno [ Va column] [ Va options] 2949279528SbaptThe 2950279528Sbapt.Li .loc 2951279528Sbaptdirective will add row to the 2952279528Sbapt.Li .debug_line 2953279528Sbaptline number matrix corresponding to the immediately following assembly instruction. 2954279528SbaptThe 2955279528Sbapt.Va fileno , 2956279528Sbapt.Va lineno , 2957279528Sbaptand optional 2958279528Sbapt.Va column 2959279528Sbaptarguments will be applied to the 2960279528Sbapt.Li .debug_line 2961279528Sbaptstate machine before the row is added. 2962279528Sbapt.Pp 2963279528SbaptThe 2964279528Sbapt.Va options 2965279528Sbaptare a sequence of the following tokens in any order: 2966279528Sbapt.Pp 2967279528Sbapt.Bl -tag -width Ds 2968279528Sbapt.It basic_block 2969279528SbaptThis option will set the 2970279528Sbapt.Li basic_block 2971279528Sbaptregister in the 2972279528Sbapt.Li .debug_line 2973279528Sbaptstate machine to 2974279528Sbapt.Li true . 2975279528Sbapt.Pp 2976279528Sbapt.It prologue_end 2977279528SbaptThis option will set the 2978279528Sbapt.Li prologue_end 2979279528Sbaptregister in the 2980279528Sbapt.Li .debug_line 2981279528Sbaptstate machine to 2982279528Sbapt.Li true . 2983279528Sbapt.Pp 2984279528Sbapt.It epilogue_begin 2985279528SbaptThis option will set the 2986279528Sbapt.Li epilogue_begin 2987279528Sbaptregister in the 2988279528Sbapt.Li .debug_line 2989279528Sbaptstate machine to 2990279528Sbapt.Li true . 2991279528Sbapt.Pp 2992279528Sbapt.It is_stmt Va value 2993279528SbaptThis option will set the 2994279528Sbapt.Li is_stmt 2995279528Sbaptregister in the 2996279528Sbapt.Li .debug_line 2997279528Sbaptstate machine to 2998279528Sbapt.Li value , 2999279528Sbaptwhich must be either 0 or 1. 3000279528Sbapt.Pp 3001279528Sbapt.It isa Va value 3002279528SbaptThis directive will set the 3003279528Sbapt.Li isa 3004279528Sbaptregister in the 3005279528Sbapt.Li .debug_line 3006279528Sbaptstate machine to 3007279528Sbapt.Va value , 3008279528Sbaptwhich must be an unsigned integer. 3009279528Sbapt.Pp 3010279528Sbapt.El 3011279528Sbapt.Ss Li .loc_mark_blocks Va enable 3012279528SbaptThe 3013279528Sbapt.Li .loc_mark_blocks 3014279528Sbaptdirective makes the assembler emit an entry to the 3015279528Sbapt.Li .debug_line 3016279528Sbaptline number matrix with the 3017279528Sbapt.Li basic_block 3018279528Sbaptregister in the state machine set whenever a code label is seen. The 3019279528Sbapt.Va enable 3020279528Sbaptargument should be either 1 or 0, to enable or disable this function respectively. 3021279528Sbapt.Pp 3022279528Sbapt.Ss Li .data Va subsection 3023279528Sbapt.Li .data 3024279528Sbapttells 3025279528Sbapt.Xr as 3026279528Sbaptto assemble the following statements onto the end of the data subsection numbered 3027279528Sbapt.Va subsection 3028279528Sbapt(which is an absolute expression). If 3029279528Sbapt.Va subsection 3030279528Sbaptis omitted, it defaults to zero. 3031279528Sbapt.Pp 3032279528Sbapt.Ss Li .double Va flonums 3033279528Sbapt.Li .double 3034279528Sbaptexpects zero or more flonums, separated by commas. It assembles floating point 3035279528Sbaptnumbers. 3036279528Sbapt.Pp 3037279528Sbapt.Ss Li .eject 3038279528SbaptForce a page break at this point, when generating assembly listings. 3039279528Sbapt.Pp 3040279528Sbapt.Ss Li .else 3041279528Sbapt.Li .else 3042279528Sbaptis part of the 3043279528Sbapt.Xr as 3044279528Sbaptsupport for conditional assembly; see If,, 3045279528Sbapt.Li .if 3046279528Sbapt\&. It marks the beginning of a section of code to be assembled if the condition 3047279528Sbaptfor the preceding 3048279528Sbapt.Li .if 3049279528Sbaptwas false. 3050279528Sbapt.Pp 3051279528Sbapt.Ss Li .elseif 3052279528Sbapt.Li .elseif 3053279528Sbaptis part of the 3054279528Sbapt.Xr as 3055279528Sbaptsupport for conditional assembly; see If,, 3056279528Sbapt.Li .if 3057279528Sbapt\&. It is shorthand for beginning a new 3058279528Sbapt.Li .if 3059279528Sbaptblock that would otherwise fill the entire 3060279528Sbapt.Li .else 3061279528Sbaptsection. 3062279528Sbapt.Pp 3063279528Sbapt.Ss Li .end 3064279528Sbapt.Li .end 3065279528Sbaptmarks the end of the assembly file. 3066279528Sbapt.Xr as 3067279528Sbaptdoes not process anything in the file past the 3068279528Sbapt.Li .end 3069279528Sbaptdirective. 3070279528Sbapt.Pp 3071279528Sbapt.Ss Li .endfunc 3072279528Sbapt.Li .endfunc 3073279528Sbaptmarks the end of a function specified with 3074279528Sbapt.Li .func . 3075279528Sbapt.Pp 3076279528Sbapt.Ss Li .endif 3077279528Sbapt.Li .endif 3078279528Sbaptis part of the 3079279528Sbapt.Xr as 3080279528Sbaptsupport for conditional assembly; it marks the end of a block of code that 3081279528Sbaptis only assembled conditionally.See Section 3082279528Sbapt.Dq If . 3083279528Sbapt.Pp 3084279528Sbapt.Ss Li .equ Va symbol, Va expression 3085279528SbaptThis directive sets the value of 3086279528Sbapt.Va symbol 3087279528Sbaptto 3088279528Sbapt.Va expression . 3089279528SbaptIt is synonymous with 3090279528Sbapt.Li .set ; 3091279528Sbaptsee Set,, 3092279528Sbapt.Li .set 3093279528Sbapt\&. 3094279528Sbapt.Pp 3095279528Sbapt.Ss Li .equiv Va symbol, Va expression 3096279528SbaptThe 3097279528Sbapt.Li .equiv 3098279528Sbaptdirective is like 3099279528Sbapt.Li .equ 3100279528Sbaptand 3101279528Sbapt.Li .set , 3102279528Sbaptexcept that the assembler will signal an error if 3103279528Sbapt.Va symbol 3104279528Sbaptis already defined. Note a symbol which has been referenced but not actually 3105279528Sbaptdefined is considered to be undefined. 3106279528Sbapt.Pp 3107279528SbaptExcept for the contents of the error message, this is roughly equivalent to 3108279528Sbapt.Bd -literal -offset indent 3109279528Sbapt\&.ifdef SYM 3110279528Sbapt\&.err 3111279528Sbapt\&.endif 3112279528Sbapt\&.equ SYM,VAL 3113279528Sbapt.Ed 3114279528Sbaptplus it protects the symbol from later redefinition. 3115279528Sbapt.Pp 3116279528Sbapt.Ss Li .eqv Va symbol, Va expression 3117279528SbaptThe 3118279528Sbapt.Li .eqv 3119279528Sbaptdirective is like 3120279528Sbapt.Li .equiv , 3121279528Sbaptbut no attempt is made to evaluate the expression or any part of it immediately. 3122279528SbaptInstead each time the resulting symbol is used in an expression, a snapshot 3123279528Sbaptof its current value is taken. 3124279528Sbapt.Pp 3125279528Sbapt.Ss Li .err 3126279528SbaptIf 3127279528Sbapt.Xr as 3128279528Sbaptassembles a 3129279528Sbapt.Li .err 3130279528Sbaptdirective, it will print an error message and, unless the 3131279528Sbapt.Op -Z 3132279528Sbaptoption was used, it will not generate an object file. This can be used to 3133279528Sbaptsignal an error in conditionally compiled code. 3134279528Sbapt.Pp 3135279528Sbapt.Ss Li .error " Va string" 3136279528SbaptSimilarly to 3137279528Sbapt.Li .err , 3138279528Sbaptthis directive emits an error, but you can specify a string that will be emitted 3139279528Sbaptas the error message. If you don't specify the message, it defaults to 3140279528Sbapt.Li ".error directive invoked in source file" . 3141279528SbaptSee Section.Dq Errors . 3142279528Sbapt.Pp 3143279528Sbapt.Bd -literal -offset indent 3144279528Sbapt .error "This code has not been assembled and tested." 3145279528Sbapt.Ed 3146279528Sbapt.Pp 3147279528Sbapt.Ss Li .exitm 3148279528SbaptExit early from the current macro definition.See Section 3149279528Sbapt.Dq Macro . 3150279528Sbapt.Pp 3151279528Sbapt.Ss Li .extern 3152279528Sbapt.Li .extern 3153279528Sbaptis accepted in the source program---for compatibility with other assemblers---but 3154279528Sbaptit is ignored. 3155279528Sbapt.Xr as 3156279528Sbapttreats all undefined symbols as external. 3157279528Sbapt.Pp 3158279528Sbapt.Ss Li .fail Va expression 3159279528SbaptGenerates an error or a warning. If the value of the 3160279528Sbapt.Va expression 3161279528Sbaptis 500 or more, 3162279528Sbapt.Xr as 3163279528Sbaptwill print a warning message. If the value is less than 500, 3164279528Sbapt.Xr as 3165279528Sbaptwill print an error message. The message will include the value of 3166279528Sbapt.Va expression . 3167279528SbaptThis can occasionally be useful inside complex nested macros or conditional 3168279528Sbaptassembly. 3169279528Sbapt.Pp 3170279528Sbapt.Ss Li .file Va string 3171279528Sbapt.Li .file 3172279528Sbapttells 3173279528Sbapt.Xr as 3174279528Sbaptthat we are about to start a new logical file. 3175279528Sbapt.Va string 3176279528Sbaptis the new file name. In general, the filename is recognized whether or not 3177279528Sbaptit is surrounded by quotes 3178279528Sbapt.Li " ; 3179279528Sbaptbut if you wish to specify an empty file name, you must give the quotes-- 3180279528Sbapt.Li "" . 3181279528SbaptThis statement may go away in future: it is only recognized to be compatible 3182279528Sbaptwith old 3183279528Sbapt.Xr as 3184279528Sbaptprograms. 3185279528Sbapt.Pp 3186279528Sbapt.Ss Li .fill Va repeat , Va size , Va value 3187279528Sbapt.Va repeat , 3188279528Sbapt.Va size 3189279528Sbaptand 3190279528Sbapt.Va value 3191279528Sbaptare absolute expressions. This emits 3192279528Sbapt.Va repeat 3193279528Sbaptcopies of 3194279528Sbapt.Va size 3195279528Sbaptbytes. 3196279528Sbapt.Va Repeat 3197279528Sbaptmay be zero or more. 3198279528Sbapt.Va Size 3199279528Sbaptmay be zero or more, but if it is more than 8, then it is deemed to have the 3200279528Sbaptvalue 8, compatible with other people's assemblers. The contents of each 3201279528Sbapt.Va repeat 3202279528Sbaptbytes is taken from an 8-byte number. The highest order 4 bytes are zero. 3203279528SbaptThe lowest order 4 bytes are 3204279528Sbapt.Va value 3205279528Sbaptrendered in the byte-order of an integer on the computer 3206279528Sbapt.Xr as 3207279528Sbaptis assembling for. Each 3208279528Sbapt.Va size 3209279528Sbaptbytes in a repetition is taken from the lowest order 3210279528Sbapt.Va size 3211279528Sbaptbytes of this number. Again, this bizarre behavior is compatible with other 3212279528Sbaptpeople's assemblers. 3213279528Sbapt.Pp 3214279528Sbapt.Va size 3215279528Sbaptand 3216279528Sbapt.Va value 3217279528Sbaptare optional. If the second comma and 3218279528Sbapt.Va value 3219279528Sbaptare absent, 3220279528Sbapt.Va value 3221279528Sbaptis assumed zero. If the first comma and following tokens are absent, 3222279528Sbapt.Va size 3223279528Sbaptis assumed to be 1. 3224279528Sbapt.Pp 3225279528Sbapt.Ss Li .float Va flonums 3226279528SbaptThis directive assembles zero or more flonums, separated by commas. It has 3227279528Sbaptthe same effect as 3228279528Sbapt.Li .single . 3229279528Sbapt.Pp 3230279528Sbapt.Ss Li .func Va name[, Va label] 3231279528Sbapt.Li .func 3232279528Sbaptemits debugging information to denote function 3233279528Sbapt.Va name , 3234279528Sbaptand is ignored unless the file is assembled with debugging enabled. Only 3235279528Sbapt.Li --gstabs[+] 3236279528Sbaptis currently supported. 3237279528Sbapt.Va label 3238279528Sbaptis the entry point of the function and if omitted 3239279528Sbapt.Va name 3240279528Sbaptprepended with the 3241279528Sbapt.Li leading char 3242279528Sbaptis used. 3243279528Sbapt.Li leading char 3244279528Sbaptis usually 3245279528Sbapt.Li _ 3246279528Sbaptor nothing, depending on the target. All functions are currently defined to 3247279528Sbapthave 3248279528Sbapt.Li void 3249279528Sbaptreturn type. The function must be terminated with 3250279528Sbapt.Li .endfunc . 3251279528Sbapt.Pp 3252279528Sbapt.Ss Li .global Va symbol, Li .globl Va symbol 3253279528Sbapt.Li .global 3254279528Sbaptmakes the symbol visible to 3255279528Sbapt.Li ld . 3256279528SbaptIf you define 3257279528Sbapt.Va symbol 3258279528Sbaptin your partial program, its value is made available to other partial programs 3259279528Sbaptthat are linked with it. Otherwise, 3260279528Sbapt.Va symbol 3261279528Sbapttakes its attributes from a symbol of the same name from another file linked 3262279528Sbaptinto the same program. 3263279528Sbapt.Pp 3264279528SbaptBoth spellings ( 3265279528Sbapt.Li .globl 3266279528Sbaptand 3267279528Sbapt.Li .global ) 3268279528Sbaptare accepted, for compatibility with other assemblers. 3269279528Sbapt.Pp 3270279528Sbapt.Ss Li .hidden Va names 3271279528SbaptThis is one of the ELF visibility directives. The other two are 3272279528Sbapt.Li .internal 3273279528Sbapt(see Section 3274279528Sbapt.Dq Internal ) 3275279528Sbaptand 3276279528Sbapt.Li .protected 3277279528Sbapt(see Section 3278279528Sbapt.Dq Protected ) . 3279279528Sbapt.Pp 3280279528SbaptThis directive overrides the named symbols default visibility (which is set 3281279528Sbaptby their binding: local, global or weak). The directive sets the visibility 3282279528Sbaptto 3283279528Sbapt.Li hidden 3284279528Sbaptwhich means that the symbols are not visible to other components. Such symbols 3285279528Sbaptare always considered to be 3286279528Sbapt.Li protected 3287279528Sbaptas well. 3288279528Sbapt.Pp 3289279528Sbapt.Ss Li .hword Va expressions 3290279528SbaptThis expects zero or more 3291279528Sbapt.Va expressions , 3292279528Sbaptand emits a 16 bit number for each. 3293279528Sbapt.Pp 3294279528SbaptThis directive is a synonym for 3295279528Sbapt.Li .short . 3296279528Sbapt.Pp 3297279528Sbapt.Ss Li .ident 3298279528SbaptThis directive is used by some assemblers to place tags in object files. The 3299279528Sbaptbehavior of this directive varies depending on the target. When using the 3300279528Sbapta.out object file format, 3301279528Sbapt.Xr as 3302279528Sbaptsimply accepts the directive for source-file compatibility with existing assemblers, 3303279528Sbaptbut does not emit anything for it. When using COFF, comments are emitted to 3304279528Sbaptthe 3305279528Sbapt.Li .comment 3306279528Sbaptor 3307279528Sbapt.Li .rdata 3308279528Sbaptsection, depending on the target. When using ELF, comments are emitted to 3309279528Sbaptthe 3310279528Sbapt.Li .comment 3311279528Sbaptsection. 3312279528Sbapt.Pp 3313279528Sbapt.Ss Li .if Va absolute expression 3314279528Sbapt.Li .if 3315279528Sbaptmarks the beginning of a section of code which is only considered part of 3316279528Sbaptthe source program being assembled if the argument (which must be an 3317279528Sbapt.Va absolute expression ) 3318279528Sbaptis non-zero. The end of the conditional section of code must be marked by 3319279528Sbapt.Li .endif 3320279528Sbapt(see Section 3321279528Sbapt.Dq Endif ) ; 3322279528Sbaptoptionally, you may include code for the alternative condition, flagged by 3323279528Sbapt.Li .else 3324279528Sbapt(see Section 3325279528Sbapt.Dq Else ) . 3326279528SbaptIf you have several conditions to check, 3327279528Sbapt.Li .elseif 3328279528Sbaptmay be used to avoid nesting blocks if/else within each subsequent 3329279528Sbapt.Li .else 3330279528Sbaptblock. 3331279528Sbapt.Pp 3332279528SbaptThe following variants of 3333279528Sbapt.Li .if 3334279528Sbaptare also supported: 3335279528Sbapt.Bl -tag -width Ds 3336279528Sbapt.It .ifdef Va symbol 3337279528SbaptAssembles the following section of code if the specified 3338279528Sbapt.Va symbol 3339279528Sbapthas been defined. Note a symbol which has been referenced but not yet defined 3340279528Sbaptis considered to be undefined. 3341279528Sbapt.Pp 3342279528Sbapt.It .ifb Va text 3343279528SbaptAssembles the following section of code if the operand is blank (empty). 3344279528Sbapt.Pp 3345279528Sbapt.It .ifc Va string1, Va string2 3346279528SbaptAssembles the following section of code if the two strings are the same. The 3347279528Sbaptstrings may be optionally quoted with single quotes. If they are not quoted, 3348279528Sbaptthe first string stops at the first comma, and the second string stops at 3349279528Sbaptthe end of the line. Strings which contain whitespace should be quoted. The 3350279528Sbaptstring comparison is case sensitive. 3351279528Sbapt.Pp 3352279528Sbapt.It .ifeq Va absolute expression 3353279528SbaptAssembles the following section of code if the argument is zero. 3354279528Sbapt.Pp 3355279528Sbapt.It .ifeqs Va string1, Va string2 3356279528SbaptAnother form of 3357279528Sbapt.Li .ifc . 3358279528SbaptThe strings must be quoted using double quotes. 3359279528Sbapt.Pp 3360279528Sbapt.It .ifge Va absolute expression 3361279528SbaptAssembles the following section of code if the argument is greater than or 3362279528Sbaptequal to zero. 3363279528Sbapt.Pp 3364279528Sbapt.It .ifgt Va absolute expression 3365279528SbaptAssembles the following section of code if the argument is greater than zero. 3366279528Sbapt.Pp 3367279528Sbapt.It .ifle Va absolute expression 3368279528SbaptAssembles the following section of code if the argument is less than or equal 3369279528Sbaptto zero. 3370279528Sbapt.Pp 3371279528Sbapt.It .iflt Va absolute expression 3372279528SbaptAssembles the following section of code if the argument is less than zero. 3373279528Sbapt.Pp 3374279528Sbapt.It .ifnb Va text 3375279528SbaptLike 3376279528Sbapt.Li .ifb , 3377279528Sbaptbut the sense of the test is reversed: this assembles the following section 3378279528Sbaptof code if the operand is non-blank (non-empty). 3379279528Sbapt.Pp 3380279528Sbapt.It .ifnc Va string1, Va string2. 3381279528SbaptLike 3382279528Sbapt.Li .ifc , 3383279528Sbaptbut the sense of the test is reversed: this assembles the following section 3384279528Sbaptof code if the two strings are not the same. 3385279528Sbapt.Pp 3386279528Sbapt.It .ifndef Va symbol 3387279528Sbapt.It .ifnotdef Va symbol 3388279528SbaptAssembles the following section of code if the specified 3389279528Sbapt.Va symbol 3390279528Sbapthas not been defined. Both spelling variants are equivalent. Note a symbol 3391279528Sbaptwhich has been referenced but not yet defined is considered to be undefined. 3392279528Sbapt.Pp 3393279528Sbapt.It .ifne Va absolute expression 3394279528SbaptAssembles the following section of code if the argument is not equal to zero 3395279528Sbapt(in other words, this is equivalent to 3396279528Sbapt.Li .if ) . 3397279528Sbapt.Pp 3398279528Sbapt.It .ifnes Va string1, Va string2 3399279528SbaptLike 3400279528Sbapt.Li .ifeqs , 3401279528Sbaptbut the sense of the test is reversed: this assembles the following section 3402279528Sbaptof code if the two strings are not the same. 3403279528Sbapt.El 3404279528Sbapt.Pp 3405279528Sbapt.Ss Li .incbin " Va file"[, Va skip[, Va count]] 3406279528SbaptThe 3407279528Sbapt.Li incbin 3408279528Sbaptdirective includes 3409279528Sbapt.Va file 3410279528Sbaptverbatim at the current location. You can control the search paths used with 3411279528Sbaptthe 3412279528Sbapt.Li -I 3413279528Sbaptcommand-line option (see Section 3414279528Sbapt.Dq Invoking ) . 3415279528SbaptQuotation marks are required around 3416279528Sbapt.Va file . 3417279528Sbapt.Pp 3418279528SbaptThe 3419279528Sbapt.Va skip 3420279528Sbaptargument skips a number of bytes from the start of the 3421279528Sbapt.Va file . 3422279528SbaptThe 3423279528Sbapt.Va count 3424279528Sbaptargument indicates the maximum number of bytes to read. Note that the data 3425279528Sbaptis not aligned in any way, so it is the user's responsibility to make sure 3426279528Sbaptthat proper alignment is provided both before and after the 3427279528Sbapt.Li incbin 3428279528Sbaptdirective. 3429279528Sbapt.Pp 3430279528Sbapt.Ss Li .include " Va file" 3431279528SbaptThis directive provides a way to include supporting files at specified points 3432279528Sbaptin your source program. The code from 3433279528Sbapt.Va file 3434279528Sbaptis assembled as if it followed the point of the 3435279528Sbapt.Li .include ; 3436279528Sbaptwhen the end of the included file is reached, assembly of the original file 3437279528Sbaptcontinues. You can control the search paths used with the 3438279528Sbapt.Li -I 3439279528Sbaptcommand-line option (see Section 3440279528Sbapt.Dq Invoking ) . 3441279528SbaptQuotation marks are required around 3442279528Sbapt.Va file . 3443279528Sbapt.Pp 3444279528Sbapt.Ss Li .int Va expressions 3445279528SbaptExpect zero or more 3446279528Sbapt.Va expressions , 3447279528Sbaptof any section, separated by commas. For each expression, emit a number that, 3448279528Sbaptat run time, is the value of that expression. The byte order and bit size 3449279528Sbaptof the number depends on what kind of target the assembly is for. 3450279528Sbapt.Pp 3451279528Sbapt.Ss Li .internal Va names 3452279528SbaptThis is one of the ELF visibility directives. The other two are 3453279528Sbapt.Li .hidden 3454279528Sbapt(see Section 3455279528Sbapt.Dq Hidden ) 3456279528Sbaptand 3457279528Sbapt.Li .protected 3458279528Sbapt(see Section 3459279528Sbapt.Dq Protected ) . 3460279528Sbapt.Pp 3461279528SbaptThis directive overrides the named symbols default visibility (which is set 3462279528Sbaptby their binding: local, global or weak). The directive sets the visibility 3463279528Sbaptto 3464279528Sbapt.Li internal 3465279528Sbaptwhich means that the symbols are considered to be 3466279528Sbapt.Li hidden 3467279528Sbapt(i.e., not visible to other components), and that some extra, processor specific 3468279528Sbaptprocessing must also be performed upon the symbols as well. 3469279528Sbapt.Pp 3470279528Sbapt.Ss Li .irp Va symbol, Va values... 3471279528SbaptEvaluate a sequence of statements assigning different values to 3472279528Sbapt.Va symbol . 3473279528SbaptThe sequence of statements starts at the 3474279528Sbapt.Li .irp 3475279528Sbaptdirective, and is terminated by an 3476279528Sbapt.Li .endr 3477279528Sbaptdirective. For each 3478279528Sbapt.Va value , 3479279528Sbapt.Va symbol 3480279528Sbaptis set to 3481279528Sbapt.Va value , 3482279528Sbaptand the sequence of statements is assembled. If no 3483279528Sbapt.Va value 3484279528Sbaptis listed, the sequence of statements is assembled once, with 3485279528Sbapt.Va symbol 3486279528Sbaptset to the null string. To refer to 3487279528Sbapt.Va symbol 3488279528Sbaptwithin the sequence of statements, use 3489279528Sbapt.Va \esymbol . 3490279528Sbapt.Pp 3491279528SbaptFor example, assembling 3492279528Sbapt.Pp 3493279528Sbapt.Bd -literal -offset indent 3494279528Sbapt .irp param,1,2,3 3495279528Sbapt move d\eparam,sp@- 3496279528Sbapt .endr 3497279528Sbapt.Ed 3498279528Sbapt.Pp 3499279528Sbaptis equivalent to assembling 3500279528Sbapt.Pp 3501279528Sbapt.Bd -literal -offset indent 3502279528Sbapt move d1,sp@- 3503279528Sbapt move d2,sp@- 3504279528Sbapt move d3,sp@- 3505279528Sbapt.Ed 3506279528Sbapt.Pp 3507279528SbaptFor some caveats with the spelling of 3508279528Sbapt.Va symbol , 3509279528Sbaptsee also Macro. 3510279528Sbapt.Pp 3511279528Sbapt.Ss Li .irpc Va symbol, Va values... 3512279528SbaptEvaluate a sequence of statements assigning different values to 3513279528Sbapt.Va symbol . 3514279528SbaptThe sequence of statements starts at the 3515279528Sbapt.Li .irpc 3516279528Sbaptdirective, and is terminated by an 3517279528Sbapt.Li .endr 3518279528Sbaptdirective. For each character in 3519279528Sbapt.Va value , 3520279528Sbapt.Va symbol 3521279528Sbaptis set to the character, and the sequence of statements is assembled. If no 3522279528Sbapt.Va value 3523279528Sbaptis listed, the sequence of statements is assembled once, with 3524279528Sbapt.Va symbol 3525279528Sbaptset to the null string. To refer to 3526279528Sbapt.Va symbol 3527279528Sbaptwithin the sequence of statements, use 3528279528Sbapt.Va \esymbol . 3529279528Sbapt.Pp 3530279528SbaptFor example, assembling 3531279528Sbapt.Pp 3532279528Sbapt.Bd -literal -offset indent 3533279528Sbapt .irpc param,123 3534279528Sbapt move d\eparam,sp@- 3535279528Sbapt .endr 3536279528Sbapt.Ed 3537279528Sbapt.Pp 3538279528Sbaptis equivalent to assembling 3539279528Sbapt.Pp 3540279528Sbapt.Bd -literal -offset indent 3541279528Sbapt move d1,sp@- 3542279528Sbapt move d2,sp@- 3543279528Sbapt move d3,sp@- 3544279528Sbapt.Ed 3545279528Sbapt.Pp 3546279528SbaptFor some caveats with the spelling of 3547279528Sbapt.Va symbol , 3548279528Sbaptsee also the discussion atSee Section 3549279528Sbapt.Dq Macro . 3550279528Sbapt.Pp 3551279528Sbapt.Ss Li .lcomm Va symbol , Va length 3552279528SbaptReserve 3553279528Sbapt.Va length 3554279528Sbapt(an absolute expression) bytes for a local common denoted by 3555279528Sbapt.Va symbol . 3556279528SbaptThe section and value of 3557279528Sbapt.Va symbol 3558279528Sbaptare those of the new local common. The addresses are allocated in the bss 3559279528Sbaptsection, so that at run-time the bytes start off zeroed. 3560279528Sbapt.Va Symbol 3561279528Sbaptis not declared global (see Section 3562279528Sbapt.Dq Global ) , 3563279528Sbaptso is normally not visible to 3564279528Sbapt.Li ld . 3565279528Sbapt.Pp 3566279528Sbapt.Ss Li .lflags 3567279528Sbapt.Xr as 3568279528Sbaptaccepts this directive, for compatibility with other assemblers, but ignores 3569279528Sbaptit. 3570279528Sbapt.Pp 3571279528Sbapt.Ss Li .line Va line-number 3572279528SbaptEven though this is a directive associated with the 3573279528Sbapt.Li a.out 3574279528Sbaptor 3575279528Sbapt.Li b.out 3576279528Sbaptobject-code formats, 3577279528Sbapt.Xr as 3578279528Sbaptstill recognizes it when producing COFF output, and treats 3579279528Sbapt.Li .line 3580279528Sbaptas though it were the COFF 3581279528Sbapt.Li .ln 3582279528Sbapt.Em if 3583279528Sbaptit is found outside a 3584279528Sbapt.Li .def 3585279528Sbapt/ 3586279528Sbapt.Li .endef 3587279528Sbaptpair. 3588279528Sbapt.Pp 3589279528SbaptInside a 3590279528Sbapt.Li .def , 3591279528Sbapt.Li .line 3592279528Sbaptis, instead, one of the directives used by compilers to generate auxiliary 3593279528Sbaptsymbol information for debugging. 3594279528Sbapt.Pp 3595279528Sbapt.Ss Li .linkonce [ Va type] 3596279528SbaptMark the current section so that the linker only includes a single copy of 3597279528Sbaptit. This may be used to include the same section in several different object 3598279528Sbaptfiles, but ensure that the linker will only include it once in the final output 3599279528Sbaptfile. The 3600279528Sbapt.Li .linkonce 3601279528Sbaptpseudo-op must be used for each instance of the section. Duplicate sections 3602279528Sbaptare detected based on the section name, so it should be unique. 3603279528Sbapt.Pp 3604279528SbaptThis directive is only supported by a few object file formats; as of this 3605279528Sbaptwriting, the only object file format which supports it is the Portable Executable 3606279528Sbaptformat used on Windows NT. 3607279528Sbapt.Pp 3608279528SbaptThe 3609279528Sbapt.Va type 3610279528Sbaptargument is optional. If specified, it must be one of the following strings. 3611279528SbaptFor example: 3612279528Sbapt.Bd -literal -offset indent 3613279528Sbapt\&.linkonce same_size 3614279528Sbapt.Ed 3615279528SbaptNot all types may be supported on all object file formats. 3616279528Sbapt.Pp 3617279528Sbapt.Bl -tag -width Ds 3618279528Sbapt.It discard 3619279528SbaptSilently discard duplicate sections. This is the default. 3620279528Sbapt.Pp 3621279528Sbapt.It one_only 3622279528SbaptWarn if there are duplicate sections, but still keep only one copy. 3623279528Sbapt.Pp 3624279528Sbapt.It same_size 3625279528SbaptWarn if any of the duplicates have different sizes. 3626279528Sbapt.Pp 3627279528Sbapt.It same_contents 3628279528SbaptWarn if any of the duplicates do not have exactly the same contents. 3629279528Sbapt.El 3630279528Sbapt.Pp 3631279528Sbapt.Ss Li .ln Va line-number 3632279528Sbapt.Li .ln 3633279528Sbaptis a synonym for 3634279528Sbapt.Li .line . 3635279528Sbapt.Pp 3636279528Sbapt.Ss Li .mri Va val 3637279528SbaptIf 3638279528Sbapt.Va val 3639279528Sbaptis non-zero, this tells 3640279528Sbapt.Xr as 3641279528Sbaptto enter MRI mode. If 3642279528Sbapt.Va val 3643279528Sbaptis zero, this tells 3644279528Sbapt.Xr as 3645279528Sbaptto exit MRI mode. This change affects code assembled until the next 3646279528Sbapt.Li .mri 3647279528Sbaptdirective, or until the end of the file.See Section 3648279528Sbapt.Dq M . 3649279528Sbapt.Pp 3650279528Sbapt.Ss Li .list 3651279528SbaptControl (in conjunction with the 3652279528Sbapt.Li .nolist 3653279528Sbaptdirective) whether or not assembly listings are generated. These two directives 3654279528Sbaptmaintain an internal counter (which is zero initially). 3655279528Sbapt.Li .list 3656279528Sbaptincrements the counter, and 3657279528Sbapt.Li .nolist 3658279528Sbaptdecrements it. Assembly listings are generated whenever the counter is greater 3659279528Sbaptthan zero. 3660279528Sbapt.Pp 3661279528SbaptBy default, listings are disabled. When you enable them (with the 3662279528Sbapt.Li -a 3663279528Sbaptcommand line option;see Section 3664279528Sbapt.Dq Invoking ) , 3665279528Sbaptthe initial value of the listing counter is one. 3666279528Sbapt.Pp 3667279528Sbapt.Ss Li .long Va expressions 3668279528Sbapt.Li .long 3669279528Sbaptis the same as 3670279528Sbapt.Li .int . 3671279528SbaptSee Section.Dq Int . 3672279528Sbapt.Pp 3673279528Sbapt.Ss Li .macro 3674279528SbaptThe commands 3675279528Sbapt.Li .macro 3676279528Sbaptand 3677279528Sbapt.Li .endm 3678279528Sbaptallow you to define macros that generate assembly output. For example, this 3679279528Sbaptdefinition specifies a macro 3680279528Sbapt.Li sum 3681279528Sbaptthat puts a sequence of numbers into memory: 3682279528Sbapt.Pp 3683279528Sbapt.Bd -literal -offset indent 3684279528Sbapt .macro sum from=0, to=5 3685279528Sbapt .long \efrom 3686279528Sbapt .if \eto-\efrom 3687279528Sbapt sum "(\efrom+1)",\eto 3688279528Sbapt .endif 3689279528Sbapt .endm 3690279528Sbapt.Ed 3691279528Sbapt.Pp 3692279528SbaptWith that definition, 3693279528Sbapt.Li SUM 0,5 3694279528Sbaptis equivalent to this assembly input: 3695279528Sbapt.Pp 3696279528Sbapt.Bd -literal -offset indent 3697279528Sbapt .long 0 3698279528Sbapt .long 1 3699279528Sbapt .long 2 3700279528Sbapt .long 3 3701279528Sbapt .long 4 3702279528Sbapt .long 5 3703279528Sbapt.Ed 3704279528Sbapt.Pp 3705279528Sbapt.Bl -tag -width Ds 3706279528Sbapt.It .macro Va macname 3707279528Sbapt.It .macro Va macname Va macargs ... 3708279528SbaptBegin the definition of a macro called 3709279528Sbapt.Va macname . 3710279528SbaptIf your macro definition requires arguments, specify their names after the 3711279528Sbaptmacro name, separated by commas or spaces. You can qualify the macro argument 3712279528Sbaptto indicate whether all invocations must specify a non-blank value (through 3713279528Sbapt.Li : Li req ) , 3714279528Sbaptor whether it takes all of the remaining arguments (through 3715279528Sbapt.Li : Li vararg ) . 3716279528SbaptYou can supply a default value for any macro argument by following the name 3717279528Sbaptwith 3718279528Sbapt.Li = Va deflt . 3719279528SbaptYou cannot define two macros with the same 3720279528Sbapt.Va macname 3721279528Sbaptunless it has been subject to the 3722279528Sbapt.Li .purgem 3723279528Sbaptdirective (see Section 3724279528Sbapt.Dq Purgem ) 3725279528Sbaptbetween the two definitions. For example, these are all valid 3726279528Sbapt.Li .macro 3727279528Sbaptstatements: 3728279528Sbapt.Pp 3729279528Sbapt.Bl -tag -width Ds 3730279528Sbapt.It .macro comm 3731279528SbaptBegin the definition of a macro called 3732279528Sbapt.Li comm , 3733279528Sbaptwhich takes no arguments. 3734279528Sbapt.Pp 3735279528Sbapt.It .macro plus1 p, p1 3736279528Sbapt.It .macro plus1 p p1 3737279528SbaptEither statement begins the definition of a macro called 3738279528Sbapt.Li plus1 , 3739279528Sbaptwhich takes two arguments; within the macro definition, write 3740279528Sbapt.Li \ep 3741279528Sbaptor 3742279528Sbapt.Li \ep1 3743279528Sbaptto evaluate the arguments. 3744279528Sbapt.Pp 3745279528Sbapt.It .macro reserve_str p1=0 p2 3746279528SbaptBegin the definition of a macro called 3747279528Sbapt.Li reserve_str , 3748279528Sbaptwith two arguments. The first argument has a default value, but not the second. 3749279528SbaptAfter the definition is complete, you can call the macro either as 3750279528Sbapt.Li reserve_str Va a, Va b 3751279528Sbapt(with 3752279528Sbapt.Li \ep1 3753279528Sbaptevaluating to 3754279528Sbapt.Va a 3755279528Sbaptand 3756279528Sbapt.Li \ep2 3757279528Sbaptevaluating to 3758279528Sbapt.Va b ) , 3759279528Sbaptor as 3760279528Sbapt.Li reserve_str , Va b 3761279528Sbapt(with 3762279528Sbapt.Li \ep1 3763279528Sbaptevaluating as the default, in this case 3764279528Sbapt.Li 0 , 3765279528Sbaptand 3766279528Sbapt.Li \ep2 3767279528Sbaptevaluating to 3768279528Sbapt.Va b ) . 3769279528Sbapt.Pp 3770279528Sbapt.It .macro m p1:req, p2=0, p3:vararg 3771279528SbaptBegin the definition of a macro called 3772279528Sbapt.Li m , 3773279528Sbaptwith at least three arguments. The first argument must always have a value 3774279528Sbaptspecified, but not the second, which instead has a default value. The third 3775279528Sbaptformal will get assigned all remaining arguments specified at invocation time. 3776279528Sbapt.Pp 3777279528SbaptWhen you call a macro, you can specify the argument values either by position, 3778279528Sbaptor by keyword. For example, 3779279528Sbapt.Li sum 9,17 3780279528Sbaptis equivalent to 3781279528Sbapt.Li sum to=17, from=9 . 3782279528Sbapt.Pp 3783279528Sbapt.El 3784279528SbaptNote that since each of the 3785279528Sbapt.Va macargs 3786279528Sbaptcan be an identifier exactly as any other one permitted by the target architecture, 3787279528Sbaptthere may be occasional problems if the target hand-crafts special meanings 3788279528Sbaptto certain characters when they occur in a special position. For example, 3789279528Sbaptif the colon ( 3790279528Sbapt.Li : ) 3791279528Sbaptis generally permitted to be part of a symbol name, but the architecture specific 3792279528Sbaptcode special-cases it when occurring as the final character of a symbol (to 3793279528Sbaptdenote a label), then the macro parameter replacement code will have no way 3794279528Sbaptof knowing that and consider the whole construct (including the colon) an 3795279528Sbaptidentifier, and check only this identifier for being the subject to parameter 3796279528Sbaptsubstitution. So for example this macro definition: 3797279528Sbapt.Pp 3798279528Sbapt.Bd -literal -offset indent 3799279528Sbapt .macro label l 3800279528Sbapt\el: 3801279528Sbapt .endm 3802279528Sbapt.Ed 3803279528Sbapt.Pp 3804279528Sbaptmight not work as expected. Invoking 3805279528Sbapt.Li label foo 3806279528Sbaptmight not create a label called 3807279528Sbapt.Li foo 3808279528Sbaptbut instead just insert the text 3809279528Sbapt.Li \el: 3810279528Sbaptinto the assembler source, probably generating an error about an unrecognised 3811279528Sbaptidentifier. 3812279528Sbapt.Pp 3813279528SbaptSimilarly problems might occur with the period character ( 3814279528Sbapt.Li . ) 3815279528Sbaptwhich is often allowed inside opcode names (and hence identifier names). So 3816279528Sbaptfor example constructing a macro to build an opcode from a base name and a 3817279528Sbaptlength specifier like this: 3818279528Sbapt.Pp 3819279528Sbapt.Bd -literal -offset indent 3820279528Sbapt .macro opcode base length 3821279528Sbapt \ebase.\elength 3822279528Sbapt .endm 3823279528Sbapt.Ed 3824279528Sbapt.Pp 3825279528Sbaptand invoking it as 3826279528Sbapt.Li opcode store l 3827279528Sbaptwill not create a 3828279528Sbapt.Li store.l 3829279528Sbaptinstruction but instead generate some kind of error as the assembler tries 3830279528Sbaptto interpret the text 3831279528Sbapt.Li \ebase.\elength . 3832279528Sbapt.Pp 3833279528SbaptThere are several possible ways around this problem: 3834279528Sbapt.Pp 3835279528Sbapt.Bl -tag -width Ds 3836279528Sbapt.It Insert white space 3837279528SbaptIf it is possible to use white space characters then this is the simplest 3838279528Sbaptsolution. eg: 3839279528Sbapt.Pp 3840279528Sbapt.Bd -literal -offset indent 3841279528Sbapt .macro label l 3842279528Sbapt\el : 3843279528Sbapt .endm 3844279528Sbapt.Ed 3845279528Sbapt.Pp 3846279528Sbapt.It Use Li \e() 3847279528SbaptThe string 3848279528Sbapt.Li \e() 3849279528Sbaptcan be used to separate the end of a macro argument from the following text. 3850279528Sbapteg: 3851279528Sbapt.Pp 3852279528Sbapt.Bd -literal -offset indent 3853279528Sbapt .macro opcode base length 3854279528Sbapt \ebase\e().\elength 3855279528Sbapt .endm 3856279528Sbapt.Ed 3857279528Sbapt.Pp 3858279528Sbapt.It Use the alternate macro syntax mode 3859279528SbaptIn the alternative macro syntax mode the ampersand character ( 3860279528Sbapt.Li & ) 3861279528Sbaptcan be used as a separator. eg: 3862279528Sbapt.Pp 3863279528Sbapt.Bd -literal -offset indent 3864279528Sbapt .altmacro 3865279528Sbapt .macro label l 3866279528Sbaptl&: 3867279528Sbapt .endm 3868279528Sbapt.Ed 3869279528Sbapt.El 3870279528Sbapt.Pp 3871279528SbaptNote: this problem of correctly identifying string parameters to pseudo ops 3872279528Sbaptalso applies to the identifiers used in 3873279528Sbapt.Li .irp 3874279528Sbapt(see Section 3875279528Sbapt.Dq Irp ) 3876279528Sbaptand 3877279528Sbapt.Li .irpc 3878279528Sbapt(see Section 3879279528Sbapt.Dq Irpc ) 3880279528Sbaptas well. 3881279528Sbapt.Pp 3882279528Sbapt.It .endm 3883279528SbaptMark the end of a macro definition. 3884279528Sbapt.Pp 3885279528Sbapt.It .exitm 3886279528SbaptExit early from the current macro definition. 3887279528Sbapt.Pp 3888279528Sbapt.It \e@ 3889279528Sbapt.Xr as 3890279528Sbaptmaintains a counter of how many macros it has executed in this pseudo-variable; 3891279528Sbaptyou can copy that number to your output with 3892279528Sbapt.Li \e@ , 3893279528Sbaptbut 3894279528Sbapt.Em only within a macro definition . 3895279528Sbapt.Pp 3896279528Sbapt.It LOCAL Va name [ , ... ] 3897279528Sbapt.Em Warning: Li LOCAL is only available if you select \(lqalternate macro syntax\(rq with Li --alternate or Li .altmacro. 3898279528SbaptSee Section.Dq Altmacro . 3899279528Sbapt.El 3900279528Sbapt.Pp 3901279528Sbapt.Ss Li .altmacro 3902279528SbaptEnable alternate macro mode, enabling: 3903279528Sbapt.Pp 3904279528Sbapt.Bl -tag -width Ds 3905279528Sbapt.It LOCAL Va name [ , ... ] 3906279528SbaptOne additional directive, 3907279528Sbapt.Li LOCAL , 3908279528Sbaptis available. It is used to generate a string replacement for each of the 3909279528Sbapt.Va name 3910279528Sbaptarguments, and replace any instances of 3911279528Sbapt.Va name 3912279528Sbaptin each macro expansion. The replacement string is unique in the assembly, 3913279528Sbaptand different for each separate macro expansion. 3914279528Sbapt.Li LOCAL 3915279528Sbaptallows you to write macros that define symbols, without fear of conflict between 3916279528Sbaptseparate macro expansions. 3917279528Sbapt.Pp 3918279528Sbapt.It String delimiters 3919279528SbaptYou can write strings delimited in these other ways besides 3920279528Sbapt.Li " Va string" : 3921279528Sbapt.Pp 3922279528Sbapt.Bl -tag -width Ds 3923279528Sbapt.It ' Va string' 3924279528SbaptYou can delimit strings with single-quote characters. 3925279528Sbapt.Pp 3926279528Sbapt.It < Va string> 3927279528SbaptYou can delimit strings with matching angle brackets. 3928279528Sbapt.El 3929279528Sbapt.Pp 3930279528Sbapt.It single-character string escape 3931279528SbaptTo include any single character literally in a string (even if the character 3932279528Sbaptwould otherwise have some special meaning), you can prefix the character with 3933279528Sbapt.Li ! 3934279528Sbapt(an exclamation mark). For example, you can write 3935279528Sbapt.Li <4.3 !> 5.4!!> 3936279528Sbaptto get the literal text 3937279528Sbapt.Li 4.3 > 5.4! . 3938279528Sbapt.Pp 3939279528Sbapt.It Expression results as strings 3940279528SbaptYou can write 3941279528Sbapt.Li % Va expr 3942279528Sbaptto evaluate the expression 3943279528Sbapt.Va expr 3944279528Sbaptand use the result as a string. 3945279528Sbapt.El 3946279528Sbapt.Pp 3947279528Sbapt.Ss Li .noaltmacro 3948279528SbaptDisable alternate macro mode.See Section 3949279528Sbapt.Dq Altmacro . 3950279528Sbapt.Pp 3951279528Sbapt.Ss Li .nolist 3952279528SbaptControl (in conjunction with the 3953279528Sbapt.Li .list 3954279528Sbaptdirective) whether or not assembly listings are generated. These two directives 3955279528Sbaptmaintain an internal counter (which is zero initially). 3956279528Sbapt.Li .list 3957279528Sbaptincrements the counter, and 3958279528Sbapt.Li .nolist 3959279528Sbaptdecrements it. Assembly listings are generated whenever the counter is greater 3960279528Sbaptthan zero. 3961279528Sbapt.Pp 3962279528Sbapt.Ss Li .octa Va biGNUms 3963279528SbaptThis directive expects zero or more biGNUms, separated by commas. For each 3964279528SbaptbiGNUm, it emits a 16-byte integer. 3965279528Sbapt.Pp 3966279528SbaptThe term \(lqocta\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence 3967279528Sbapt.Em octa 3968279528Sbapt-word for 16 bytes. 3969279528Sbapt.Pp 3970279528Sbapt.Ss Li .org Va new-lc , Va fill 3971279528SbaptAdvance the location counter of the current section to 3972279528Sbapt.Va new-lc . 3973279528Sbapt.Va new-lc 3974279528Sbaptis either an absolute expression or an expression with the same section as 3975279528Sbaptthe current subsection. That is, you can't use 3976279528Sbapt.Li .org 3977279528Sbaptto cross sections: if 3978279528Sbapt.Va new-lc 3979279528Sbapthas the wrong section, the 3980279528Sbapt.Li .org 3981279528Sbaptdirective is ignored. To be compatible with former assemblers, if the section 3982279528Sbaptof 3983279528Sbapt.Va new-lc 3984279528Sbaptis absolute, 3985279528Sbapt.Xr as 3986279528Sbaptissues a warning, then pretends the section of 3987279528Sbapt.Va new-lc 3988279528Sbaptis the same as the current subsection. 3989279528Sbapt.Pp 3990279528Sbapt.Li .org 3991279528Sbaptmay only increase the location counter, or leave it unchanged; you cannot 3992279528Sbaptuse 3993279528Sbapt.Li .org 3994279528Sbaptto move the location counter backwards. 3995279528Sbapt.Pp 3996279528SbaptBecause 3997279528Sbapt.Xr as 3998279528Sbapttries to assemble programs in one pass, 3999279528Sbapt.Va new-lc 4000279528Sbaptmay not be undefined. If you really detest this restriction we eagerly await 4001279528Sbapta chance to share your improved assembler. 4002279528Sbapt.Pp 4003279528SbaptBeware that the origin is relative to the start of the section, not to the 4004279528Sbaptstart of the subsection. This is compatible with other people's assemblers. 4005279528Sbapt.Pp 4006279528SbaptWhen the location counter (of the current subsection) is advanced, the intervening 4007279528Sbaptbytes are filled with 4008279528Sbapt.Va fill 4009279528Sbaptwhich should be an absolute expression. If the comma and 4010279528Sbapt.Va fill 4011279528Sbaptare omitted, 4012279528Sbapt.Va fill 4013279528Sbaptdefaults to zero. 4014279528Sbapt.Pp 4015279528Sbapt.Ss Li .p2align[wl] Va abs-expr, Va abs-expr, Va abs-expr 4016279528SbaptPad the location counter (in the current subsection) to a particular storage 4017279528Sbaptboundary. The first expression (which must be absolute) is the number of low-order 4018279528Sbaptzero bits the location counter must have after advancement. For example 4019279528Sbapt.Li .p2align 3 4020279528Sbaptadvances the location counter until it a multiple of 8. If the location counter 4021279528Sbaptis already a multiple of 8, no change is needed. 4022279528Sbapt.Pp 4023279528SbaptThe second expression (also absolute) gives the fill value to be stored in 4024279528Sbaptthe padding bytes. It (and the comma) may be omitted. If it is omitted, the 4025279528Sbaptpadding bytes are normally zero. However, on some systems, if the section 4026279528Sbaptis marked as containing code and the fill value is omitted, the space is filled 4027279528Sbaptwith no-op instructions. 4028279528Sbapt.Pp 4029279528SbaptThe third expression is also absolute, and is also optional. If it is present, 4030279528Sbaptit is the maximum number of bytes that should be skipped by this alignment 4031279528Sbaptdirective. If doing the alignment would require skipping more bytes than the 4032279528Sbaptspecified maximum, then the alignment is not done at all. You can omit the 4033279528Sbaptfill value (the second argument) entirely by simply using two commas after 4034279528Sbaptthe required alignment; this can be useful if you want the alignment to be 4035279528Sbaptfilled with no-op instructions when appropriate. 4036279528Sbapt.Pp 4037279528SbaptThe 4038279528Sbapt.Li .p2alignw 4039279528Sbaptand 4040279528Sbapt.Li .p2alignl 4041279528Sbaptdirectives are variants of the 4042279528Sbapt.Li .p2align 4043279528Sbaptdirective. The 4044279528Sbapt.Li .p2alignw 4045279528Sbaptdirective treats the fill pattern as a two byte word value. The 4046279528Sbapt.Li .p2alignl 4047279528Sbaptdirectives treats the fill pattern as a four byte longword value. For example, 4048279528Sbapt.Li .p2alignw 2,0x368d 4049279528Sbaptwill align to a multiple of 4. If it skips two bytes, they will be filled 4050279528Sbaptin with the value 0x368d (the exact placement of the bytes depends upon the 4051279528Sbaptendianness of the processor). If it skips 1 or 3 bytes, the fill value is 4052279528Sbaptundefined. 4053279528Sbapt.Pp 4054279528Sbapt.Ss Li .previous 4055279528SbaptThis is one of the ELF section stack manipulation directives. The others are 4056279528Sbapt.Li .section 4057279528Sbapt(see Section 4058279528Sbapt.Dq Section ) , 4059279528Sbapt.Li .subsection 4060279528Sbapt(see Section 4061279528Sbapt.Dq SubSection ) , 4062279528Sbapt.Li .pushsection 4063279528Sbapt(see Section 4064279528Sbapt.Dq PushSection ) , 4065279528Sbaptand 4066279528Sbapt.Li .popsection 4067279528Sbapt(see Section 4068279528Sbapt.Dq PopSection ) . 4069279528Sbapt.Pp 4070279528SbaptThis directive swaps the current section (and subsection) with most recently 4071279528Sbaptreferenced section (and subsection) prior to this one. Multiple 4072279528Sbapt.Li .previous 4073279528Sbaptdirectives in a row will flip between two sections (and their subsections). 4074279528Sbapt.Pp 4075279528SbaptIn terms of the section stack, this directive swaps the current section with 4076279528Sbaptthe top section on the section stack. 4077279528Sbapt.Pp 4078279528Sbapt.Ss Li .popsection 4079279528SbaptThis is one of the ELF section stack manipulation directives. The others are 4080279528Sbapt.Li .section 4081279528Sbapt(see Section 4082279528Sbapt.Dq Section ) , 4083279528Sbapt.Li .subsection 4084279528Sbapt(see Section 4085279528Sbapt.Dq SubSection ) , 4086279528Sbapt.Li .pushsection 4087279528Sbapt(see Section 4088279528Sbapt.Dq PushSection ) , 4089279528Sbaptand 4090279528Sbapt.Li .previous 4091279528Sbapt(see Section 4092279528Sbapt.Dq Previous ) . 4093279528Sbapt.Pp 4094279528SbaptThis directive replaces the current section (and subsection) with the top 4095279528Sbaptsection (and subsection) on the section stack. This section is popped off 4096279528Sbaptthe stack. 4097279528Sbapt.Pp 4098279528Sbapt.Ss Li .print Va string 4099279528Sbapt.Xr as 4100279528Sbaptwill print 4101279528Sbapt.Va string 4102279528Sbapton the standard output during assembly. You must put 4103279528Sbapt.Va string 4104279528Sbaptin double quotes. 4105279528Sbapt.Pp 4106279528Sbapt.Ss Li .protected Va names 4107279528SbaptThis is one of the ELF visibility directives. The other two are 4108279528Sbapt.Li .hidden 4109279528Sbapt(see Section 4110279528Sbapt.Dq Hidden ) 4111279528Sbaptand 4112279528Sbapt.Li .internal 4113279528Sbapt(see Section 4114279528Sbapt.Dq Internal ) . 4115279528Sbapt.Pp 4116279528SbaptThis directive overrides the named symbols default visibility (which is set 4117279528Sbaptby their binding: local, global or weak). The directive sets the visibility 4118279528Sbaptto 4119279528Sbapt.Li protected 4120279528Sbaptwhich means that any references to the symbols from within the components 4121279528Sbaptthat defines them must be resolved to the definition in that component, even 4122279528Sbaptif a definition in another component would normally preempt this. 4123279528Sbapt.Pp 4124279528Sbapt.Ss Li .psize Va lines , Va columns 4125279528SbaptUse this directive to declare the number of lines---and, optionally, the number 4126279528Sbaptof columns---to use for each page, when generating listings. 4127279528Sbapt.Pp 4128279528SbaptIf you do not use 4129279528Sbapt.Li .psize , 4130279528Sbaptlistings use a default line-count of 60. You may omit the comma and 4131279528Sbapt.Va columns 4132279528Sbaptspecification; the default width is 200 columns. 4133279528Sbapt.Pp 4134279528Sbapt.Xr as 4135279528Sbaptgenerates formfeeds whenever the specified number of lines is exceeded (or 4136279528Sbaptwhenever you explicitly request one, using 4137279528Sbapt.Li .eject ) . 4138279528Sbapt.Pp 4139279528SbaptIf you specify 4140279528Sbapt.Va lines 4141279528Sbaptas 4142279528Sbapt.Li 0 , 4143279528Sbaptno formfeeds are generated save those explicitly specified with 4144279528Sbapt.Li .eject . 4145279528Sbapt.Pp 4146279528Sbapt.Ss Li .purgem Va name 4147279528SbaptUndefine the macro 4148279528Sbapt.Va name , 4149279528Sbaptso that later uses of the string will not be expanded.See Section 4150279528Sbapt.Dq Macro . 4151279528Sbapt.Pp 4152279528Sbapt.Ss Li .pushsection Va name , Va subsection 4153279528SbaptThis is one of the ELF section stack manipulation directives. The others are 4154279528Sbapt.Li .section 4155279528Sbapt(see Section 4156279528Sbapt.Dq Section ) , 4157279528Sbapt.Li .subsection 4158279528Sbapt(see Section 4159279528Sbapt.Dq SubSection ) , 4160279528Sbapt.Li .popsection 4161279528Sbapt(see Section 4162279528Sbapt.Dq PopSection ) , 4163279528Sbaptand 4164279528Sbapt.Li .previous 4165279528Sbapt(see Section 4166279528Sbapt.Dq Previous ) . 4167279528Sbapt.Pp 4168279528SbaptThis directive pushes the current section (and subsection) onto the top of 4169279528Sbaptthe section stack, and then replaces the current section and subsection with 4170279528Sbapt.Li name 4171279528Sbaptand 4172279528Sbapt.Li subsection . 4173279528Sbapt.Pp 4174279528Sbapt.Ss Li .quad Va biGNUms 4175279528Sbapt.Li .quad 4176279528Sbaptexpects zero or more biGNUms, separated by commas. For each bignum, it emits 4177279528Sbaptan 8-byte integer. If the biGNUm won't fit in 8 bytes, it prints a warning 4178279528Sbaptmessage; and just takes the lowest order 8 bytes of the biGNUm. 4179279528Sbapt.Pp 4180279528SbaptThe term \(lqquad\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence 4181279528Sbapt.Em quad 4182279528Sbapt-word for 8 bytes. 4183279528Sbapt.Pp 4184279528Sbapt.Ss Li .reloc Va offset, Va reloc_name[, Va expression] 4185279528SbaptGenerate a relocation at 4186279528Sbapt.Va offset 4187279528Sbaptof type 4188279528Sbapt.Va reloc_name 4189279528Sbaptwith value 4190279528Sbapt.Va expression . 4191279528SbaptIf 4192279528Sbapt.Va offset 4193279528Sbaptis a number, the relocation is generated in the current section. If 4194279528Sbapt.Va offset 4195279528Sbaptis an expression that resolves to a symbol plus offset, the relocation is 4196279528Sbaptgenerated in the given symbol's section. 4197279528Sbapt.Va expression , 4198279528Sbaptif present, must resolve to a symbol plus addend or to an absolute value, 4199279528Sbaptbut note that not all targets support an addend. e.g. ELF REL targets such 4200279528Sbaptas i386 store an addend in the section contents rather than in the relocation. 4201279528SbaptThis low level interface does not support addends stored in the section. 4202279528Sbapt.Pp 4203279528Sbapt.Ss Li .rept Va count 4204279528SbaptRepeat the sequence of lines between the 4205279528Sbapt.Li .rept 4206279528Sbaptdirective and the next 4207279528Sbapt.Li .endr 4208279528Sbaptdirective 4209279528Sbapt.Va count 4210279528Sbapttimes. 4211279528Sbapt.Pp 4212279528SbaptFor example, assembling 4213279528Sbapt.Pp 4214279528Sbapt.Bd -literal -offset indent 4215279528Sbapt .rept 3 4216279528Sbapt .long 0 4217279528Sbapt .endr 4218279528Sbapt.Ed 4219279528Sbapt.Pp 4220279528Sbaptis equivalent to assembling 4221279528Sbapt.Pp 4222279528Sbapt.Bd -literal -offset indent 4223279528Sbapt .long 0 4224279528Sbapt .long 0 4225279528Sbapt .long 0 4226279528Sbapt.Ed 4227279528Sbapt.Pp 4228279528Sbapt.Ss Li .sbttl " Va subheading" 4229279528SbaptUse 4230279528Sbapt.Va subheading 4231279528Sbaptas the title (third line, immediately after the title line) when generating 4232279528Sbaptassembly listings. 4233279528Sbapt.Pp 4234279528SbaptThis directive affects subsequent pages, as well as the current page if it 4235279528Sbaptappears within ten lines of the top of a page. 4236279528Sbapt.Pp 4237279528Sbapt.Ss Li .section Va name 4238279528SbaptUse the 4239279528Sbapt.Li .section 4240279528Sbaptdirective to assemble the following code into a section named 4241279528Sbapt.Va name . 4242279528Sbapt.Pp 4243279528SbaptThis directive is only supported for targets that actually support arbitrarily 4244279528Sbaptnamed sections; on 4245279528Sbapt.Li a.out 4246279528Sbapttargets, for example, it is not accepted, even with a standard 4247279528Sbapt.Li a.out 4248279528Sbaptsection name. 4249279528Sbapt.Pp 4250279528SbaptThis is one of the ELF section stack manipulation directives. The others are 4251279528Sbapt.Li .subsection 4252279528Sbapt(see Section 4253279528Sbapt.Dq SubSection ) , 4254279528Sbapt.Li .pushsection 4255279528Sbapt(see Section 4256279528Sbapt.Dq PushSection ) , 4257279528Sbapt.Li .popsection 4258279528Sbapt(see Section 4259279528Sbapt.Dq PopSection ) , 4260279528Sbaptand 4261279528Sbapt.Li .previous 4262279528Sbapt(see Section 4263279528Sbapt.Dq Previous ) . 4264279528Sbapt.Pp 4265279528SbaptFor ELF targets, the 4266279528Sbapt.Li .section 4267279528Sbaptdirective is used like this: 4268279528Sbapt.Pp 4269279528Sbapt.Bd -literal -offset indent 4270279528Sbapt\&.section name [, "flags"[, @type[,flag_specific_arguments]]] 4271279528Sbapt.Ed 4272279528Sbapt.Pp 4273279528SbaptThe optional 4274279528Sbapt.Va flags 4275279528Sbaptargument is a quoted string which may contain any combination of the following 4276279528Sbaptcharacters: 4277279528Sbapt.Bl -tag -width Ds 4278279528Sbapt.It a 4279279528Sbaptsection is allocatable 4280279528Sbapt.It w 4281279528Sbaptsection is writable 4282279528Sbapt.It x 4283279528Sbaptsection is executable 4284279528Sbapt.It M 4285279528Sbaptsection is mergeable 4286279528Sbapt.It S 4287279528Sbaptsection contains zero terminated strings 4288279528Sbapt.It G 4289279528Sbaptsection is a member of a section group 4290279528Sbapt.It T 4291279528Sbaptsection is used for thread-local-storage 4292279528Sbapt.El 4293279528Sbapt.Pp 4294279528SbaptThe optional 4295279528Sbapt.Va type 4296279528Sbaptargument may contain one of the following constants: 4297279528Sbapt.Bl -tag -width Ds 4298279528Sbapt.It @progbits 4299279528Sbaptsection contains data 4300279528Sbapt.It @nobits 4301279528Sbaptsection does not contain data (i.e., section only occupies space) 4302279528Sbapt.It @note 4303279528Sbaptsection contains data which is used by things other than the program 4304279528Sbapt.It @init_array 4305279528Sbaptsection contains an array of pointers to init functions 4306279528Sbapt.It @fini_array 4307279528Sbaptsection contains an array of pointers to finish functions 4308279528Sbapt.It @preinit_array 4309279528Sbaptsection contains an array of pointers to pre-init functions 4310279528Sbapt.El 4311279528Sbapt.Pp 4312279528SbaptMany targets only support the first three section types. 4313279528Sbapt.Pp 4314279528SbaptNote on targets where the 4315279528Sbapt.Li @ 4316279528Sbaptcharacter is the start of a comment (eg ARM) then another character is used 4317279528Sbaptinstead. For example the ARM port uses the 4318279528Sbapt.Li % 4319279528Sbaptcharacter. 4320279528Sbapt.Pp 4321279528SbaptIf 4322279528Sbapt.Va flags 4323279528Sbaptcontains the 4324279528Sbapt.Li M 4325279528Sbaptsymbol then the 4326279528Sbapt.Va type 4327279528Sbaptargument must be specified as well as an extra argument--- 4328279528Sbapt.Va entsize 4329279528Sbapt---like this: 4330279528Sbapt.Pp 4331279528Sbapt.Bd -literal -offset indent 4332279528Sbapt\&.section name , "flags"M, @type, entsize 4333279528Sbapt.Ed 4334279528Sbapt.Pp 4335279528SbaptSections with the 4336279528Sbapt.Li M 4337279528Sbaptflag but not 4338279528Sbapt.Li S 4339279528Sbaptflag must contain fixed size constants, each 4340279528Sbapt.Va entsize 4341279528Sbaptoctets long. Sections with both 4342279528Sbapt.Li M 4343279528Sbaptand 4344279528Sbapt.Li S 4345279528Sbaptmust contain zero terminated strings where each character is 4346279528Sbapt.Va entsize 4347279528Sbaptbytes long. The linker may remove duplicates within sections with the same 4348279528Sbaptname, same entity size and same flags. 4349279528Sbapt.Va entsize 4350279528Sbaptmust be an absolute expression. 4351279528Sbapt.Pp 4352279528SbaptIf 4353279528Sbapt.Va flags 4354279528Sbaptcontains the 4355279528Sbapt.Li G 4356279528Sbaptsymbol then the 4357279528Sbapt.Va type 4358279528Sbaptargument must be present along with an additional field like this: 4359279528Sbapt.Pp 4360279528Sbapt.Bd -literal -offset indent 4361279528Sbapt\&.section name , "flags"G, @type, GroupName[, linkage] 4362279528Sbapt.Ed 4363279528Sbapt.Pp 4364279528SbaptThe 4365279528Sbapt.Va GroupName 4366279528Sbaptfield specifies the name of the section group to which this particular section 4367279528Sbaptbelongs. The optional linkage field can contain: 4368279528Sbapt.Bl -tag -width Ds 4369279528Sbapt.It comdat 4370279528Sbaptindicates that only one copy of this section should be retained 4371279528Sbapt.It .GNU.linkonce 4372279528Sbaptan alias for comdat 4373279528Sbapt.El 4374279528Sbapt.Pp 4375279528SbaptNote: if both the 4376279528Sbapt.Va M 4377279528Sbaptand 4378279528Sbapt.Va G 4379279528Sbaptflags are present then the fields for the Merge flag should come first, like 4380279528Sbaptthis: 4381279528Sbapt.Pp 4382279528Sbapt.Bd -literal -offset indent 4383279528Sbapt\&.section name , "flags"MG, @type, entsize, GroupName[, linkage] 4384279528Sbapt.Ed 4385279528Sbapt.Pp 4386279528SbaptIf no flags are specified, the default flags depend upon the section name. 4387279528SbaptIf the section name is not recognized, the default will be for the section 4388279528Sbaptto have none of the above flags: it will not be allocated in memory, nor writable, 4389279528Sbaptnor executable. The section will contain data. 4390279528Sbapt.Pp 4391279528SbaptFor ELF targets, the assembler supports another type of 4392279528Sbapt.Li .section 4393279528Sbaptdirective for compatibility with the Solaris assembler: 4394279528Sbapt.Pp 4395279528Sbapt.Bd -literal -offset indent 4396279528Sbapt\&.section "name"[, flags...] 4397279528Sbapt.Ed 4398279528Sbapt.Pp 4399279528SbaptNote that the section name is quoted. There may be a sequence of comma separated 4400279528Sbaptflags: 4401279528Sbapt.Bl -tag -width Ds 4402279528Sbapt.It #alloc 4403279528Sbaptsection is allocatable 4404279528Sbapt.It #write 4405279528Sbaptsection is writable 4406279528Sbapt.It #execinstr 4407279528Sbaptsection is executable 4408279528Sbapt.It #tls 4409279528Sbaptsection is used for thread local storage 4410279528Sbapt.El 4411279528Sbapt.Pp 4412279528SbaptThis directive replaces the current section and subsection. See the contents 4413279528Sbaptof the gas testsuite directory 4414279528Sbapt.Li gas/testsuite/gas/elf 4415279528Sbaptfor some examples of how this directive and the other section stack directives 4416279528Sbaptwork. 4417279528Sbapt.Pp 4418279528Sbapt.Ss Li .set Va symbol, Va expression 4419279528SbaptSet the value of 4420279528Sbapt.Va symbol 4421279528Sbaptto 4422279528Sbapt.Va expression . 4423279528SbaptThis changes 4424279528Sbapt.Va symbol 4425279528Sbapt\&'s value and type to conform to 4426279528Sbapt.Va expression . 4427279528SbaptIf 4428279528Sbapt.Va symbol 4429279528Sbaptwas flagged as external, it remains flagged (see Section 4430279528Sbapt.Dq Symbol Attributes ) . 4431279528Sbapt.Pp 4432279528SbaptYou may 4433279528Sbapt.Li .set 4434279528Sbapta symbol many times in the same assembly. 4435279528Sbapt.Pp 4436279528SbaptIf you 4437279528Sbapt.Li .set 4438279528Sbapta global symbol, the value stored in the object file is the last value stored 4439279528Sbaptinto it. 4440279528Sbapt.Pp 4441279528Sbapt.Ss Li .short Va expressions 4442279528SbaptThis expects zero or more 4443279528Sbapt.Va expressions , 4444279528Sbaptand emits a 16 bit number for each. 4445279528Sbapt.Pp 4446279528Sbapt.Ss Li .single Va flonums 4447279528SbaptThis directive assembles zero or more flonums, separated by commas. It has 4448279528Sbaptthe same effect as 4449279528Sbapt.Li .float . 4450279528Sbapt.Pp 4451279528Sbapt.Ss Li .size 4452279528SbaptThis directive is used to set the size associated with a symbol. 4453279528Sbapt.Pp 4454279528SbaptFor ELF targets, the 4455279528Sbapt.Li .size 4456279528Sbaptdirective is used like this: 4457279528Sbapt.Pp 4458279528Sbapt.Bd -literal -offset indent 4459279528Sbapt\&.size name , expression 4460279528Sbapt.Ed 4461279528Sbapt.Pp 4462279528SbaptThis directive sets the size associated with a symbol 4463279528Sbapt.Va name . 4464279528SbaptThe size in bytes is computed from 4465279528Sbapt.Va expression 4466279528Sbaptwhich can make use of label arithmetic. This directive is typically used to 4467279528Sbaptset the size of function symbols. 4468279528Sbapt.Pp 4469279528Sbapt.Ss Li .sleb128 Va expressions 4470279528Sbapt.Va sleb128 4471279528Sbaptstands for \(lqsigned little endian base 128.\(rq This is a compact, variable length 4472279528Sbaptrepresentation of numbers used by the DWARF symbolic debugging format.See Section 4473279528Sbapt.Dq Uleb128 . 4474279528Sbapt.Pp 4475279528Sbapt.Ss Li .skip Va size , Va fill 4476279528SbaptThis directive emits 4477279528Sbapt.Va size 4478279528Sbaptbytes, each of value 4479279528Sbapt.Va fill . 4480279528SbaptBoth 4481279528Sbapt.Va size 4482279528Sbaptand 4483279528Sbapt.Va fill 4484279528Sbaptare absolute expressions. If the comma and 4485279528Sbapt.Va fill 4486279528Sbaptare omitted, 4487279528Sbapt.Va fill 4488279528Sbaptis assumed to be zero. This is the same as 4489279528Sbapt.Li .space . 4490279528Sbapt.Pp 4491279528Sbapt.Ss Li .space Va size , Va fill 4492279528SbaptThis directive emits 4493279528Sbapt.Va size 4494279528Sbaptbytes, each of value 4495279528Sbapt.Va fill . 4496279528SbaptBoth 4497279528Sbapt.Va size 4498279528Sbaptand 4499279528Sbapt.Va fill 4500279528Sbaptare absolute expressions. If the comma and 4501279528Sbapt.Va fill 4502279528Sbaptare omitted, 4503279528Sbapt.Va fill 4504279528Sbaptis assumed to be zero. This is the same as 4505279528Sbapt.Li .skip . 4506279528Sbapt.Pp 4507279528Sbapt.Ss Li .stabd, .stabn, .stabs 4508279528SbaptThere are three directives that begin 4509279528Sbapt.Li .stab . 4510279528SbaptAll emit symbols (see Section 4511279528Sbapt.Dq Symbols ) , 4512279528Sbaptfor use by symbolic debuggers. The symbols are not entered in the 4513279528Sbapt.Xr as 4514279528Sbapthash table: they cannot be referenced elsewhere in the source file. Up to 4515279528Sbaptfive fields are required: 4516279528Sbapt.Pp 4517279528Sbapt.Bl -tag -width Ds 4518279528Sbapt.It string 4519279528SbaptThis is the symbol's name. It may contain any character except 4520279528Sbapt.Li \e000 , 4521279528Sbaptso is more general than ordinary symbol names. Some debuggers used to code 4522279528Sbaptarbitrarily complex structures into symbol names using this field. 4523279528Sbapt.Pp 4524279528Sbapt.It type 4525279528SbaptAn absolute expression. The symbol's type is set to the low 8 bits of this 4526279528Sbaptexpression. Any bit pattern is permitted, but 4527279528Sbapt.Li ld 4528279528Sbaptand debuggers choke on silly bit patterns. 4529279528Sbapt.Pp 4530279528Sbapt.It other 4531279528SbaptAn absolute expression. The symbol's \(lqother\(rq attribute is set to the low 8 bits 4532279528Sbaptof this expression. 4533279528Sbapt.Pp 4534279528Sbapt.It desc 4535279528SbaptAn absolute expression. The symbol's descriptor is set to the low 16 bits 4536279528Sbaptof this expression. 4537279528Sbapt.Pp 4538279528Sbapt.It value 4539279528SbaptAn absolute expression which becomes the symbol's value. 4540279528Sbapt.El 4541279528Sbapt.Pp 4542279528SbaptIf a warning is detected while reading a 4543279528Sbapt.Li .stabd , 4544279528Sbapt.Li .stabn , 4545279528Sbaptor 4546279528Sbapt.Li .stabs 4547279528Sbaptstatement, the symbol has probably already been created; you get a half-formed 4548279528Sbaptsymbol in your object file. This is compatible with earlier assemblers! 4549279528Sbapt.Pp 4550279528Sbapt.Bl -tag -width Ds 4551279528Sbapt.It .stabd Va type , Va other , Va desc 4552279528Sbapt.Pp 4553279528SbaptThe \(lqname\(rq of the symbol generated is not even an empty string. It is a null 4554279528Sbaptpointer, for compatibility. Older assemblers used a null pointer so they didn't 4555279528Sbaptwaste space in object files with empty strings. 4556279528Sbapt.Pp 4557279528SbaptThe symbol's value is set to the location counter, relocatably. When your 4558279528Sbaptprogram is linked, the value of this symbol is the address of the location 4559279528Sbaptcounter when the 4560279528Sbapt.Li .stabd 4561279528Sbaptwas assembled. 4562279528Sbapt.Pp 4563279528Sbapt.It .stabn Va type , Va other , Va desc , Va value 4564279528SbaptThe name of the symbol is set to the empty string 4565279528Sbapt.Li "" . 4566279528Sbapt.Pp 4567279528Sbapt.It .stabs Va string , Va type , Va other , Va desc , Va value 4568279528SbaptAll five fields are specified. 4569279528Sbapt.El 4570279528Sbapt.Pp 4571279528Sbapt.Ss Li .string " Va str" 4572279528SbaptCopy the characters in 4573279528Sbapt.Va str 4574279528Sbaptto the object file. You may specify more than one string to copy, separated 4575279528Sbaptby commas. Unless otherwise specified for a particular machine, the assembler 4576279528Sbaptmarks the end of each string with a 0 byte. You can use any of the escape 4577279528Sbaptsequences described in Strings,,Strings. 4578279528Sbapt.Pp 4579279528Sbapt.Ss Li .struct Va expression 4580279528SbaptSwitch to the absolute section, and set the section offset to 4581279528Sbapt.Va expression , 4582279528Sbaptwhich must be an absolute expression. You might use this as follows: 4583279528Sbapt.Bd -literal -offset indent 4584279528Sbapt .struct 0 4585279528Sbaptfield1: 4586279528Sbapt .struct field1 + 4 4587279528Sbaptfield2: 4588279528Sbapt .struct field2 + 4 4589279528Sbaptfield3: 4590279528Sbapt.Ed 4591279528SbaptThis would define the symbol 4592279528Sbapt.Li field1 4593279528Sbaptto have the value 0, the symbol 4594279528Sbapt.Li field2 4595279528Sbaptto have the value 4, and the symbol 4596279528Sbapt.Li field3 4597279528Sbaptto have the value 8. Assembly would be left in the absolute section, and you 4598279528Sbaptwould need to use a 4599279528Sbapt.Li .section 4600279528Sbaptdirective of some sort to change to some other section before further assembly. 4601279528Sbapt.Pp 4602279528Sbapt.Ss Li .subsection Va name 4603279528SbaptThis is one of the ELF section stack manipulation directives. The others are 4604279528Sbapt.Li .section 4605279528Sbapt(see Section 4606279528Sbapt.Dq Section ) , 4607279528Sbapt.Li .pushsection 4608279528Sbapt(see Section 4609279528Sbapt.Dq PushSection ) , 4610279528Sbapt.Li .popsection 4611279528Sbapt(see Section 4612279528Sbapt.Dq PopSection ) , 4613279528Sbaptand 4614279528Sbapt.Li .previous 4615279528Sbapt(see Section 4616279528Sbapt.Dq Previous ) . 4617279528Sbapt.Pp 4618279528SbaptThis directive replaces the current subsection with 4619279528Sbapt.Li name . 4620279528SbaptThe current section is not changed. The replaced subsection is put onto the 4621279528Sbaptsection stack in place of the then current top of stack subsection. 4622279528Sbapt.Pp 4623279528Sbapt.Ss Li .symver 4624279528SbaptUse the 4625279528Sbapt.Li .symver 4626279528Sbaptdirective to bind symbols to specific version nodes within a source file. 4627279528SbaptThis is only supported on ELF platforms, and is typically used when assembling 4628279528Sbaptfiles to be linked into a shared library. There are cases where it may make 4629279528Sbaptsense to use this in objects to be bound into an application itself so as 4630279528Sbaptto override a versioned symbol from a shared library. 4631279528Sbapt.Pp 4632279528SbaptFor ELF targets, the 4633279528Sbapt.Li .symver 4634279528Sbaptdirective can be used like this: 4635279528Sbapt.Bd -literal -offset indent 4636279528Sbapt\&.symver name, name2@nodename 4637279528Sbapt.Ed 4638279528SbaptIf the symbol 4639279528Sbapt.Va name 4640279528Sbaptis defined within the file being assembled, the 4641279528Sbapt.Li .symver 4642279528Sbaptdirective effectively creates a symbol alias with the name 4643279528Sbapt.Va name2@nodename , 4644279528Sbaptand in fact the main reason that we just don't try and create a regular alias 4645279528Sbaptis that the 4646279528Sbapt.Va @ 4647279528Sbaptcharacter isn't permitted in symbol names. The 4648279528Sbapt.Va name2 4649279528Sbaptpart of the name is the actual name of the symbol by which it will be externally 4650279528Sbaptreferenced. The name 4651279528Sbapt.Va name 4652279528Sbaptitself is merely a name of convenience that is used so that it is possible 4653279528Sbaptto have definitions for multiple versions of a function within a single source 4654279528Sbaptfile, and so that the compiler can unambiguously know which version of a function 4655279528Sbaptis being mentioned. The 4656279528Sbapt.Va nodename 4657279528Sbaptportion of the alias should be the name of a node specified in the version 4658279528Sbaptscript supplied to the linker when building a shared library. If you are attempting 4659279528Sbaptto override a versioned symbol from a shared library, then 4660279528Sbapt.Va nodename 4661279528Sbaptshould correspond to the nodename of the symbol you are trying to override. 4662279528Sbapt.Pp 4663279528SbaptIf the symbol 4664279528Sbapt.Va name 4665279528Sbaptis not defined within the file being assembled, all references to 4666279528Sbapt.Va name 4667279528Sbaptwill be changed to 4668279528Sbapt.Va name2@nodename . 4669279528SbaptIf no reference to 4670279528Sbapt.Va name 4671279528Sbaptis made, 4672279528Sbapt.Va name2@nodename 4673279528Sbaptwill be removed from the symbol table. 4674279528Sbapt.Pp 4675279528SbaptAnother usage of the 4676279528Sbapt.Li .symver 4677279528Sbaptdirective is: 4678279528Sbapt.Bd -literal -offset indent 4679279528Sbapt\&.symver name, name2@@nodename 4680279528Sbapt.Ed 4681279528SbaptIn this case, the symbol 4682279528Sbapt.Va name 4683279528Sbaptmust exist and be defined within the file being assembled. It is similar to 4684279528Sbapt.Va name2@nodename . 4685279528SbaptThe difference is 4686279528Sbapt.Va name2@@nodename 4687279528Sbaptwill also be used to resolve references to 4688279528Sbapt.Va name2 4689279528Sbaptby the linker. 4690279528Sbapt.Pp 4691279528SbaptThe third usage of the 4692279528Sbapt.Li .symver 4693279528Sbaptdirective is: 4694279528Sbapt.Bd -literal -offset indent 4695279528Sbapt\&.symver name, name2@@@nodename 4696279528Sbapt.Ed 4697279528SbaptWhen 4698279528Sbapt.Va name 4699279528Sbaptis not defined within the file being assembled, it is treated as 4700279528Sbapt.Va name2@nodename . 4701279528SbaptWhen 4702279528Sbapt.Va name 4703279528Sbaptis defined within the file being assembled, the symbol name, 4704279528Sbapt.Va name , 4705279528Sbaptwill be changed to 4706279528Sbapt.Va name2@@nodename . 4707279528Sbapt.Pp 4708279528Sbapt.Ss Li .text Va subsection 4709279528SbaptTells 4710279528Sbapt.Xr as 4711279528Sbaptto assemble the following statements onto the end of the text subsection numbered 4712279528Sbapt.Va subsection , 4713279528Sbaptwhich is an absolute expression. If 4714279528Sbapt.Va subsection 4715279528Sbaptis omitted, subsection number zero is used. 4716279528Sbapt.Pp 4717279528Sbapt.Ss Li .title " Va heading" 4718279528SbaptUse 4719279528Sbapt.Va heading 4720279528Sbaptas the title (second line, immediately after the source file name and pagenumber) 4721279528Sbaptwhen generating assembly listings. 4722279528Sbapt.Pp 4723279528SbaptThis directive affects subsequent pages, as well as the current page if it 4724279528Sbaptappears within ten lines of the top of a page. 4725279528Sbapt.Pp 4726279528Sbapt.Ss Li .type 4727279528SbaptThis directive is used to set the type of a symbol. 4728279528Sbapt.Pp 4729279528SbaptFor ELF targets, the 4730279528Sbapt.Li .type 4731279528Sbaptdirective is used like this: 4732279528Sbapt.Pp 4733279528Sbapt.Bd -literal -offset indent 4734279528Sbapt\&.type name , type description 4735279528Sbapt.Ed 4736279528Sbapt.Pp 4737279528SbaptThis sets the type of symbol 4738279528Sbapt.Va name 4739279528Sbaptto be either a function symbol or an object symbol. There are five different 4740279528Sbaptsyntaxes supported for the 4741279528Sbapt.Va type description 4742279528Sbaptfield, in order to provide compatibility with various other assemblers. 4743279528Sbapt.Pp 4744279528SbaptBecause some of the characters used in these syntaxes (such as 4745279528Sbapt.Li @ 4746279528Sbaptand 4747279528Sbapt.Li # ) 4748279528Sbaptare comment characters for some architectures, some of the syntaxes below 4749279528Sbaptdo not work on all architectures. The first variant will be accepted by the 4750279528SbaptGNU assembler on all architectures so that variant should be used for maximum 4751279528Sbaptportability, if you do not need to assemble your code with other assemblers. 4752279528Sbapt.Pp 4753279528SbaptThe syntaxes supported are: 4754279528Sbapt.Pp 4755279528Sbapt.Bd -literal -offset indent 4756279528Sbapt .type <name> STT_FUNCTION 4757279528Sbapt .type <name> STT_OBJECT 4758279528Sbapt 4759279528Sbapt .type <name>,#function 4760279528Sbapt .type <name>,#object 4761279528Sbapt 4762279528Sbapt .type <name>,@function 4763279528Sbapt .type <name>,@object 4764279528Sbapt 4765279528Sbapt .type <name>,%function 4766279528Sbapt .type <name>,%object 4767279528Sbapt 4768279528Sbapt .type <name>,"function" 4769279528Sbapt .type <name>,"object" 4770279528Sbapt.Ed 4771279528Sbapt.Pp 4772279528Sbapt.Ss Li .uleb128 Va expressions 4773279528Sbapt.Va uleb128 4774279528Sbaptstands for \(lqunsigned little endian base 128.\(rq This is a compact, variable length 4775279528Sbaptrepresentation of numbers used by the DWARF symbolic debugging format.See Section 4776279528Sbapt.Dq Sleb128 . 4777279528Sbapt.Pp 4778279528Sbapt.Ss Li .version " Va string" 4779279528SbaptThis directive creates a 4780279528Sbapt.Li .note 4781279528Sbaptsection and places into it an ELF formatted note of type NT_VERSION. The note's 4782279528Sbaptname is set to 4783279528Sbapt.Li string . 4784279528Sbapt.Pp 4785279528Sbapt.Ss Li .vtable_entry Va table, Va offset 4786279528SbaptThis directive finds or creates a symbol 4787279528Sbapt.Li table 4788279528Sbaptand creates a 4789279528Sbapt.Li VTABLE_ENTRY 4790279528Sbaptrelocation for it with an addend of 4791279528Sbapt.Li offset . 4792279528Sbapt.Pp 4793279528Sbapt.Ss Li .vtable_inherit Va child, Va parent 4794279528SbaptThis directive finds the symbol 4795279528Sbapt.Li child 4796279528Sbaptand finds or creates the symbol 4797279528Sbapt.Li parent 4798279528Sbaptand then creates a 4799279528Sbapt.Li VTABLE_INHERIT 4800279528Sbaptrelocation for the parent whose addend is the value of the child symbol. As 4801279528Sbapta special case the parent name of 4802279528Sbapt.Li 0 4803279528Sbaptis treated as referring to the 4804279528Sbapt.Li *ABS* 4805279528Sbaptsection. 4806279528Sbapt.Pp 4807279528Sbapt.Ss Li .warning " Va string" 4808279528SbaptSimilar to the directive 4809279528Sbapt.Li .error 4810279528Sbapt(see Section 4811279528Sbapt.Dq Error ) , 4812279528Sbaptbut just emits a warning. 4813279528Sbapt.Pp 4814279528Sbapt.Ss Li .weak Va names 4815279528SbaptThis directive sets the weak attribute on the comma separated list of symbol 4816279528Sbapt.Li names . 4817279528SbaptIf the symbols do not already exist, they will be created. 4818279528Sbapt.Pp 4819279528SbaptOn COFF targets other than PE, weak symbols are a GNU extension. This directive 4820279528Sbaptsets the weak attribute on the comma separated list of symbol 4821279528Sbapt.Li names . 4822279528SbaptIf the symbols do not already exist, they will be created. 4823279528Sbapt.Pp 4824279528SbaptOn the PE target, weak symbols are supported natively as weak aliases. When 4825279528Sbapta weak symbol is created that is not an alias, GAS creates an alternate symbol 4826279528Sbaptto hold the default value. 4827279528Sbapt.Pp 4828279528Sbapt.Ss Li .weakref Va alias, Va target 4829279528SbaptThis directive creates an alias to the target symbol that enables the symbol 4830279528Sbaptto be referenced with weak-symbol semantics, but without actually making it 4831279528Sbaptweak. If direct references or definitions of the symbol are present, then 4832279528Sbaptthe symbol will not be weak, but if all references to it are through weak 4833279528Sbaptreferences, the symbol will be marked as weak in the symbol table. 4834279528Sbapt.Pp 4835279528SbaptThe effect is equivalent to moving all references to the alias to a separate 4836279528Sbaptassembly source file, renaming the alias to the symbol in it, declaring the 4837279528Sbaptsymbol as weak there, and running a reloadable link to merge the object files 4838279528Sbaptresulting from the assembly of the new source file and the old source file 4839279528Sbaptthat had the references to the alias removed. 4840279528Sbapt.Pp 4841279528SbaptThe alias itself never makes to the symbol table, and is entirely handled 4842279528Sbaptwithin the assembler. 4843279528Sbapt.Pp 4844279528Sbapt.Ss Li .word Va expressions 4845279528SbaptThis directive expects zero or more 4846279528Sbapt.Va expressions , 4847279528Sbaptof any section, separated by commas. For each expression, 4848279528Sbapt.Xr as 4849279528Sbaptemits a 32-bit number. 4850279528Sbapt.Pp 4851279528Sbapt.Ss Deprecated Directives 4852279528SbaptOne day these directives won't work. They are included for compatibility with 4853279528Sbaptolder assemblers. 4854279528Sbapt.Bl -tag -width Ds 4855279528Sbapt.It .abort 4856279528Sbapt.It .line 4857279528Sbapt.El 4858279528Sbapt.Pp 4859279528Sbapt.Sh ARM Dependent Features 4860279528Sbapt.Ss Options 4861279528Sbapt.Bl -tag -width Ds 4862279528Sbapt.It -mcpu= Va processor[+ Va extension...] 4863279528SbaptThis option specifies the target processor. The assembler will issue an error 4864279528Sbaptmessage if an attempt is made to assemble an instruction which will not execute 4865279528Sbapton the target processor. The following processor names are recognized: 4866279528Sbapt.Li arm1 , 4867279528Sbapt.Li arm2 , 4868279528Sbapt.Li arm250 , 4869279528Sbapt.Li arm3 , 4870279528Sbapt.Li arm6 , 4871279528Sbapt.Li arm60 , 4872279528Sbapt.Li arm600 , 4873279528Sbapt.Li arm610 , 4874279528Sbapt.Li arm620 , 4875279528Sbapt.Li arm7 , 4876279528Sbapt.Li arm7m , 4877279528Sbapt.Li arm7d , 4878279528Sbapt.Li arm7dm , 4879279528Sbapt.Li arm7di , 4880279528Sbapt.Li arm7dmi , 4881279528Sbapt.Li arm70 , 4882279528Sbapt.Li arm700 , 4883279528Sbapt.Li arm700i , 4884279528Sbapt.Li arm710 , 4885279528Sbapt.Li arm710t , 4886279528Sbapt.Li arm720 , 4887279528Sbapt.Li arm720t , 4888279528Sbapt.Li arm740t , 4889279528Sbapt.Li arm710c , 4890279528Sbapt.Li arm7100 , 4891279528Sbapt.Li arm7500 , 4892279528Sbapt.Li arm7500fe , 4893279528Sbapt.Li arm7t , 4894279528Sbapt.Li arm7tdmi , 4895279528Sbapt.Li arm7tdmi-s , 4896279528Sbapt.Li arm8 , 4897279528Sbapt.Li arm810 , 4898279528Sbapt.Li strongarm , 4899279528Sbapt.Li strongarm1 , 4900279528Sbapt.Li strongarm110 , 4901279528Sbapt.Li strongarm1100 , 4902279528Sbapt.Li strongarm1110 , 4903279528Sbapt.Li arm9 , 4904279528Sbapt.Li arm920 , 4905279528Sbapt.Li arm920t , 4906279528Sbapt.Li arm922t , 4907279528Sbapt.Li arm940t , 4908279528Sbapt.Li arm9tdmi , 4909279528Sbapt.Li arm9e , 4910279528Sbapt.Li arm926e , 4911279528Sbapt.Li arm926ej-s , 4912279528Sbapt.Li arm946e-r0 , 4913279528Sbapt.Li arm946e , 4914279528Sbapt.Li arm946e-s , 4915279528Sbapt.Li arm966e-r0 , 4916279528Sbapt.Li arm966e , 4917279528Sbapt.Li arm966e-s , 4918279528Sbapt.Li arm968e-s , 4919279528Sbapt.Li arm10t , 4920279528Sbapt.Li arm10tdmi , 4921279528Sbapt.Li arm10e , 4922279528Sbapt.Li arm1020 , 4923279528Sbapt.Li arm1020t , 4924279528Sbapt.Li arm1020e , 4925279528Sbapt.Li arm1022e , 4926279528Sbapt.Li arm1026ej-s , 4927279528Sbapt.Li arm1136j-s , 4928279528Sbapt.Li arm1136jf-s , 4929279528Sbapt.Li arm1156t2-s , 4930279528Sbapt.Li arm1156t2f-s , 4931279528Sbapt.Li arm1176jz-s , 4932279528Sbapt.Li arm1176jzf-s , 4933279528Sbapt.Li mpcore , 4934279528Sbapt.Li mpcorenovfp , 4935279528Sbapt.Li cortex-a8 , 4936279528Sbapt.Li cortex-r4 , 4937279528Sbapt.Li cortex-m3 , 4938279528Sbapt.Li ep9312 4939279528Sbapt(ARM920 with Cirrus Maverick coprocessor), 4940279528Sbapt.Li i80200 4941279528Sbapt(Intel XScale processor) 4942279528Sbapt.Li iwmmxt 4943279528Sbapt(Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) and 4944279528Sbapt.Li xscale . 4945279528SbaptThe special name 4946279528Sbapt.Li all 4947279528Sbaptmay be used to allow the assembler to accept instructions valid for any ARM 4948279528Sbaptprocessor. 4949279528Sbapt.Pp 4950279528SbaptIn addition to the basic instruction set, the assembler can be told to accept 4951279528Sbaptvarious extension mnemonics that extend the processor using the co-processor 4952279528Sbaptinstruction space. For example, 4953279528Sbapt.Li -mcpu=arm920+maverick 4954279528Sbaptis equivalent to specifying 4955279528Sbapt.Li -mcpu=ep9312 . 4956279528SbaptThe following extensions are currently supported: 4957279528Sbapt.Li +maverick 4958279528Sbapt.Li +iwmmxt 4959279528Sbaptand 4960279528Sbapt.Li +xscale . 4961279528Sbapt.Pp 4962279528Sbapt.It -march= Va architecture[+ Va extension...] 4963279528SbaptThis option specifies the target architecture. The assembler will issue an 4964279528Sbapterror message if an attempt is made to assemble an instruction which will 4965279528Sbaptnot execute on the target architecture. The following architecture names are 4966279528Sbaptrecognized: 4967279528Sbapt.Li armv1 , 4968279528Sbapt.Li armv2 , 4969279528Sbapt.Li armv2a , 4970279528Sbapt.Li armv2s , 4971279528Sbapt.Li armv3 , 4972279528Sbapt.Li armv3m , 4973279528Sbapt.Li armv4 , 4974279528Sbapt.Li armv4xm , 4975279528Sbapt.Li armv4t , 4976279528Sbapt.Li armv4txm , 4977279528Sbapt.Li armv5 , 4978279528Sbapt.Li armv5t , 4979279528Sbapt.Li armv5txm , 4980279528Sbapt.Li armv5te , 4981279528Sbapt.Li armv5texp , 4982279528Sbapt.Li armv6 , 4983279528Sbapt.Li armv6j , 4984279528Sbapt.Li armv6k , 4985279528Sbapt.Li armv6z , 4986279528Sbapt.Li armv6zk , 4987279528Sbapt.Li armv7 , 4988279528Sbapt.Li armv7-a , 4989279528Sbapt.Li armv7-r , 4990279528Sbapt.Li armv7-m , 4991279528Sbapt.Li iwmmxt 4992279528Sbaptand 4993279528Sbapt.Li xscale . 4994279528SbaptIf both 4995279528Sbapt.Li -mcpu 4996279528Sbaptand 4997279528Sbapt.Li -march 4998279528Sbaptare specified, the assembler will use the setting for 4999279528Sbapt.Li -mcpu . 5000279528Sbapt.Pp 5001279528SbaptThe architecture option can be extended with the same instruction set extension 5002279528Sbaptoptions as the 5003279528Sbapt.Li -mcpu 5004279528Sbaptoption. 5005279528Sbapt.Pp 5006279528Sbapt.It -mfpu= Va floating-point-format 5007279528Sbapt.Pp 5008279528SbaptThis option specifies the floating point format to assemble for. The assembler 5009279528Sbaptwill issue an error message if an attempt is made to assemble an instruction 5010279528Sbaptwhich will not execute on the target floating point unit. The following format 5011279528Sbaptoptions are recognized: 5012279528Sbapt.Li softfpa , 5013279528Sbapt.Li fpe , 5014279528Sbapt.Li fpe2 , 5015279528Sbapt.Li fpe3 , 5016279528Sbapt.Li fpa , 5017279528Sbapt.Li fpa10 , 5018279528Sbapt.Li fpa11 , 5019279528Sbapt.Li arm7500fe , 5020279528Sbapt.Li softvfp , 5021279528Sbapt.Li softvfp+vfp , 5022279528Sbapt.Li vfp , 5023279528Sbapt.Li vfp10 , 5024279528Sbapt.Li vfp10-r0 , 5025279528Sbapt.Li vfp9 , 5026279528Sbapt.Li vfpxd , 5027279528Sbapt.Li arm1020t , 5028279528Sbapt.Li arm1020e , 5029279528Sbapt.Li arm1136jf-s 5030279528Sbaptand 5031279528Sbapt.Li maverick . 5032279528Sbapt.Pp 5033279528SbaptIn addition to determining which instructions are assembled, this option also 5034279528Sbaptaffects the way in which the 5035279528Sbapt.Li .double 5036279528Sbaptassembler directive behaves when assembling little-endian code. 5037279528Sbapt.Pp 5038279528SbaptThe default is dependent on the processor selected. For Architecture 5 or 5039279528Sbaptlater, the default is to assembler for VFP instructions; for earlier architectures 5040279528Sbaptthe default is to assemble for FPA instructions. 5041279528Sbapt.Pp 5042279528Sbapt.It -mthumb 5043279528SbaptThis option specifies that the assembler should start assembling Thumb instructions; 5044279528Sbaptthat is, it should behave as though the file starts with a 5045279528Sbapt.Li .code 16 5046279528Sbaptdirective. 5047279528Sbapt.Pp 5048279528Sbapt.It -mthumb-interwork 5049279528SbaptThis option specifies that the output generated by the assembler should be 5050279528Sbaptmarked as supporting interworking. 5051279528Sbapt.Pp 5052279528Sbapt.It -mapcs Li [26|32] 5053279528SbaptThis option specifies that the output generated by the assembler should be 5054279528Sbaptmarked as supporting the indicated version of the Arm Procedure. Calling Standard. 5055279528Sbapt.Pp 5056279528Sbapt.It -matpcs 5057279528SbaptThis option specifies that the output generated by the assembler should be 5058279528Sbaptmarked as supporting the Arm/Thumb Procedure Calling Standard. If enabled 5059279528Sbaptthis option will cause the assembler to create an empty debugging section 5060279528Sbaptin the object file called .arm.atpcs. Debuggers can use this to determine 5061279528Sbaptthe ABI being used by. 5062279528Sbapt.Pp 5063279528Sbapt.It -mapcs-float 5064279528SbaptThis indicates the floating point variant of the APCS should be used. In this 5065279528Sbaptvariant floating point arguments are passed in FP registers rather than integer 5066279528Sbaptregisters. 5067279528Sbapt.Pp 5068279528Sbapt.It -mapcs-reentrant 5069279528SbaptThis indicates that the reentrant variant of the APCS should be used. This 5070279528Sbaptvariant supports position independent code. 5071279528Sbapt.Pp 5072279528Sbapt.It -mfloat-abi= Va abi 5073279528SbaptThis option specifies that the output generated by the assembler should be 5074279528Sbaptmarked as using specified floating point ABI. The following values are recognized: 5075279528Sbapt.Li soft , 5076279528Sbapt.Li softfp 5077279528Sbaptand 5078279528Sbapt.Li hard . 5079279528Sbapt.Pp 5080279528Sbapt.It -meabi= Va ver 5081279528SbaptThis option specifies which EABI version the produced object files should 5082279528Sbaptconform to. The following values are recognized: 5083279528Sbapt.Li GNU , 5084279528Sbapt.Li 4 5085279528Sbaptand 5086279528Sbapt.Li 5 . 5087279528Sbapt.Pp 5088279528Sbapt.It -EB 5089279528SbaptThis option specifies that the output generated by the assembler should be 5090279528Sbaptmarked as being encoded for a big-endian processor. 5091279528Sbapt.Pp 5092279528Sbapt.It -EL 5093279528SbaptThis option specifies that the output generated by the assembler should be 5094279528Sbaptmarked as being encoded for a little-endian processor. 5095279528Sbapt.Pp 5096279528Sbapt.It -k 5097279528SbaptThis option specifies that the output of the assembler should be marked as 5098279528Sbaptposition-independent code (PIC). 5099279528Sbapt.Pp 5100279528Sbapt.El 5101279528Sbapt.Ss Syntax 5102279528Sbapt.Em Special Characters 5103279528Sbapt.Pp 5104279528SbaptThe presence of a 5105279528Sbapt.Li @ 5106279528Sbapton a line indicates the start of a comment that extends to the end of the 5107279528Sbaptcurrent line. If a 5108279528Sbapt.Li # 5109279528Sbaptappears as the first character of a line, the whole line is treated as a comment. 5110279528Sbapt.Pp 5111279528SbaptThe 5112279528Sbapt.Li ; 5113279528Sbaptcharacter can be used instead of a newline to separate statements. 5114279528Sbapt.Pp 5115279528SbaptEither 5116279528Sbapt.Li # 5117279528Sbaptor 5118279528Sbapt.Li $ 5119279528Sbaptcan be used to indicate immediate operands. 5120279528Sbapt.Pp 5121279528Sbapt*TODO* Explain about /data modifier on symbols. 5122279528Sbapt.Pp 5123279528Sbapt.Em Register Names 5124279528Sbapt.Pp 5125279528Sbapt*TODO* Explain about ARM register naming, and the predefined names. 5126279528Sbapt.Pp 5127279528Sbapt.Em ARM relocation generation 5128279528Sbapt.Pp 5129279528SbaptSpecific data relocations can be generated by putting the relocation name 5130279528Sbaptin parentheses after the symbol name. For example: 5131279528Sbapt.Pp 5132279528Sbapt.Bd -literal -offset indent 5133279528Sbapt .word foo(TARGET1) 5134279528Sbapt.Ed 5135279528Sbapt.Pp 5136279528SbaptThis will generate an 5137279528Sbapt.Li R_ARM_TARGET1 5138279528Sbaptrelocation against the symbol 5139279528Sbapt.Va foo . 5140279528SbaptThe following relocations are supported: 5141279528Sbapt.Li GOT , 5142279528Sbapt.Li GOTOFF , 5143279528Sbapt.Li TARGET1 , 5144279528Sbapt.Li TARGET2 , 5145279528Sbapt.Li SBREL , 5146279528Sbapt.Li TLSGD , 5147279528Sbapt.Li TLSLDM , 5148279528Sbapt.Li TLSLDO , 5149279528Sbapt.Li GOTTPOFF 5150279528Sbaptand 5151279528Sbapt.Li TPOFF . 5152279528Sbapt.Pp 5153279528SbaptFor compatibility with older toolchains the assembler also accepts 5154279528Sbapt.Li (PLT) 5155279528Sbaptafter branch targets. This will generate the deprecated 5156279528Sbapt.Li R_ARM_PLT32 5157279528Sbaptrelocation. 5158279528Sbapt.Pp 5159279528SbaptRelocations for 5160279528Sbapt.Li MOVW 5161279528Sbaptand 5162279528Sbapt.Li MOVT 5163279528Sbaptinstructions can be generated by prefixing the value with 5164279528Sbapt.Li #:lower16: 5165279528Sbaptand 5166279528Sbapt.Li #:upper16 5167279528Sbaptrespectively. For example to load the 32-bit address of foo into r0: 5168279528Sbapt.Pp 5169279528Sbapt.Bd -literal -offset indent 5170279528Sbapt MOVW r0, #:lower16:foo 5171279528Sbapt MOVT r0, #:upper16:foo 5172279528Sbapt.Ed 5173279528Sbapt.Pp 5174279528Sbapt.Ss Floating Point 5175279528SbaptThe ARM family uses ieee floating-point numbers. 5176279528Sbapt.Pp 5177279528Sbapt.Ss ARM Machine Directives 5178279528Sbapt.Bl -tag -width Ds 5179279528Sbapt.It .align Va expression [, Va expression] 5180279528SbaptThis is the generic 5181279528Sbapt.Va .align 5182279528Sbaptdirective. For the ARM however if the first argument is zero (ie no alignment 5183279528Sbaptis needed) the assembler will behave as if the argument had been 2 (ie pad 5184279528Sbaptto the next four byte boundary). This is for compatibility with ARM's own 5185279528Sbaptassembler. 5186279528Sbapt.Pp 5187279528Sbapt.It Va name .req Va register name 5188279528SbaptThis creates an alias for 5189279528Sbapt.Va register name 5190279528Sbaptcalled 5191279528Sbapt.Va name . 5192279528SbaptFor example: 5193279528Sbapt.Pp 5194279528Sbapt.Bd -literal -offset indent 5195279528Sbapt foo .req r0 5196279528Sbapt.Ed 5197279528Sbapt.Pp 5198279528Sbapt.It .unreq Va alias-name 5199279528SbaptThis undefines a register alias which was previously defined using the 5200279528Sbapt.Li req , 5201279528Sbapt.Li dn 5202279528Sbaptor 5203279528Sbapt.Li qn 5204279528Sbaptdirectives. For example: 5205279528Sbapt.Pp 5206279528Sbapt.Bd -literal -offset indent 5207279528Sbapt foo .req r0 5208279528Sbapt .unreq foo 5209279528Sbapt.Ed 5210279528Sbapt.Pp 5211279528SbaptAn error occurs if the name is undefined. Note - this pseudo op can be used 5212279528Sbaptto delete builtin in register name aliases (eg 'r0'). This should only be 5213279528Sbaptdone if it is really necessary. 5214279528Sbapt.Pp 5215279528Sbapt.It Va name .dn Va register name [ Va .type] [ Va [index]] 5216279528Sbapt.It Va name .qn Va register name [ Va .type] [ Va [index]] 5217279528Sbapt.Pp 5218279528SbaptThe 5219279528Sbapt.Li dn 5220279528Sbaptand 5221279528Sbapt.Li qn 5222279528Sbaptdirectives are used to create typed and/or indexed register aliases for use 5223279528Sbaptin Advanced SIMD Extension (Neon) instructions. The former should be used 5224279528Sbaptto create aliases of double-precision registers, and the latter to create 5225279528Sbaptaliases of quad-precision registers. 5226279528Sbapt.Pp 5227279528SbaptIf these directives are used to create typed aliases, those aliases can be 5228279528Sbaptused in Neon instructions instead of writing types after the mnemonic or after 5229279528Sbapteach operand. For example: 5230279528Sbapt.Pp 5231279528Sbapt.Bd -literal -offset indent 5232279528Sbapt x .dn d2.f32 5233279528Sbapt y .dn d3.f32 5234279528Sbapt z .dn d4.f32[1] 5235279528Sbapt vmul x,y,z 5236279528Sbapt.Ed 5237279528Sbapt.Pp 5238279528SbaptThis is equivalent to writing the following: 5239279528Sbapt.Pp 5240279528Sbapt.Bd -literal -offset indent 5241279528Sbapt vmul.f32 d2,d3,d4[1] 5242279528Sbapt.Ed 5243279528Sbapt.Pp 5244279528SbaptAliases created using 5245279528Sbapt.Li dn 5246279528Sbaptor 5247279528Sbapt.Li qn 5248279528Sbaptcan be destroyed using 5249279528Sbapt.Li unreq . 5250279528Sbapt.Pp 5251279528Sbapt.It .code Li [16|32] 5252279528SbaptThis directive selects the instruction set being generated. The value 16 selects 5253279528SbaptThumb, with the value 32 selecting ARM. 5254279528Sbapt.Pp 5255279528Sbapt.It .thumb 5256279528SbaptThis performs the same action as 5257279528Sbapt.Va .code 16 . 5258279528Sbapt.Pp 5259279528Sbapt.It .arm 5260279528SbaptThis performs the same action as 5261279528Sbapt.Va .code 32 . 5262279528Sbapt.Pp 5263279528Sbapt.It .force_thumb 5264279528SbaptThis directive forces the selection of Thumb instructions, even if the target 5265279528Sbaptprocessor does not support those instructions 5266279528Sbapt.Pp 5267279528Sbapt.It .thumb_func 5268279528SbaptThis directive specifies that the following symbol is the name of a Thumb 5269279528Sbaptencoded function. This information is necessary in order to allow the assembler 5270279528Sbaptand linker to generate correct code for interworking between Arm and Thumb 5271279528Sbaptinstructions and should be used even if interworking is not going to be performed. 5272279528SbaptThe presence of this directive also implies 5273279528Sbapt.Li .thumb 5274279528Sbapt.Pp 5275279528SbaptThis directive is not neccessary when generating EABI objects. On these targets 5276279528Sbaptthe encoding is implicit when generating Thumb code. 5277279528Sbapt.Pp 5278279528Sbapt.It .thumb_set 5279279528SbaptThis performs the equivalent of a 5280279528Sbapt.Li .set 5281279528Sbaptdirective in that it creates a symbol which is an alias for another symbol 5282279528Sbapt(possibly not yet defined). This directive also has the added property in 5283279528Sbaptthat it marks the aliased symbol as being a thumb function entry point, in 5284279528Sbaptthe same way that the 5285279528Sbapt.Li .thumb_func 5286279528Sbaptdirective does. 5287279528Sbapt.Pp 5288279528Sbapt.It .ltorg 5289279528SbaptThis directive causes the current contents of the literal pool to be dumped 5290279528Sbaptinto the current section (which is assumed to be the .text section) at the 5291279528Sbaptcurrent location (aligned to a word boundary). 5292279528Sbapt.Li GAS 5293279528Sbaptmaintains a separate literal pool for each section and each sub-section. The 5294279528Sbapt.Li .ltorg 5295279528Sbaptdirective will only affect the literal pool of the current section and sub-section. 5296279528SbaptAt the end of assembly all remaining, un-empty literal pools will automatically 5297279528Sbaptbe dumped. 5298279528Sbapt.Pp 5299279528SbaptNote - older versions of 5300279528Sbapt.Li GAS 5301279528Sbaptwould dump the current literal pool any time a section change occurred. This 5302279528Sbaptis no longer done, since it prevents accurate control of the placement of 5303279528Sbaptliteral pools. 5304279528Sbapt.Pp 5305279528Sbapt.It .pool 5306279528SbaptThis is a synonym for .ltorg. 5307279528Sbapt.Pp 5308279528Sbapt.It .unwind_fnstart 5309279528SbaptMarks the start of a function with an unwind table entry. 5310279528Sbapt.Pp 5311279528Sbapt.It .unwind_fnend 5312279528SbaptMarks the end of a function with an unwind table entry. The unwind index table 5313279528Sbaptentry is created when this directive is processed. 5314279528Sbapt.Pp 5315279528SbaptIf no personality routine has been specified then standard personality routine 5316279528Sbapt0 or 1 will be used, depending on the number of unwind opcodes required. 5317279528Sbapt.Pp 5318279528Sbapt.It .cantunwind 5319279528SbaptPrevents unwinding through the current function. No personality routine or 5320279528Sbaptexception table data is required or permitted. 5321279528Sbapt.Pp 5322279528Sbapt.It .personality Va name 5323279528SbaptSets the personality routine for the current function to 5324279528Sbapt.Va name . 5325279528Sbapt.Pp 5326279528Sbapt.It .personalityindex Va index 5327279528SbaptSets the personality routine for the current function to the EABI standard 5328279528Sbaptroutine number 5329279528Sbapt.Va index 5330279528Sbapt.Pp 5331279528Sbapt.It .handlerdata 5332279528SbaptMarks the end of the current function, and the start of the exception table 5333279528Sbaptentry for that function. Anything between this directive and the 5334279528Sbapt.Li .fnend 5335279528Sbaptdirective will be added to the exception table entry. 5336279528Sbapt.Pp 5337279528SbaptMust be preceded by a 5338279528Sbapt.Li .personality 5339279528Sbaptor 5340279528Sbapt.Li .personalityindex 5341279528Sbaptdirective. 5342279528Sbapt.Pp 5343279528Sbapt.It .save Va reglist 5344279528SbaptGenerate unwinder annotations to restore the registers in 5345279528Sbapt.Va reglist . 5346279528SbaptThe format of 5347279528Sbapt.Va reglist 5348279528Sbaptis the same as the corresponding store-multiple instruction. 5349279528Sbapt.Pp 5350279528Sbapt.Bd -literal -offset indent 5351279528Sbapt .save {r4, r5, r6, lr} 5352279528Sbapt stmfd sp!, {r4, r5, r6, lr} 5353279528Sbapt .save f4, 2 5354279528Sbapt sfmfd f4, 2, [sp]! 5355279528Sbapt .save {d8, d9, d10} 5356279528Sbapt fstmdx sp!, {d8, d9, d10} 5357279528Sbapt .save {wr10, wr11} 5358279528Sbapt wstrd wr11, [sp, #-8]! 5359279528Sbapt wstrd wr10, [sp, #-8]! 5360279528Sbaptor 5361279528Sbapt .save wr11 5362279528Sbapt wstrd wr11, [sp, #-8]! 5363279528Sbapt .save wr10 5364279528Sbapt wstrd wr10, [sp, #-8]! 5365279528Sbapt.Ed 5366279528Sbapt.Pp 5367279528Sbapt.It .vsave Va vfp-reglist 5368279528SbaptGenerate unwinder annotations to restore the VFP registers in 5369279528Sbapt.Va vfp-reglist 5370279528Sbaptusing FLDMD. Also works for VFPv3 registers that are to be restored using 5371279528SbaptVLDM. The format of 5372279528Sbapt.Va vfp-reglist 5373279528Sbaptis the same as the corresponding store-multiple instruction. 5374279528Sbapt.Pp 5375279528Sbapt.Bd -literal -offset indent 5376279528Sbapt .vsave {d8, d9, d10} 5377279528Sbapt fstmdd sp!, {d8, d9, d10} 5378279528Sbapt .vsave {d15, d16, d17} 5379279528Sbapt vstm sp!, {d15, d16, d17} 5380279528Sbapt.Ed 5381279528Sbapt.Pp 5382279528SbaptSince FLDMX and FSTMX are now deprecated, this directive should be used in 5383279528Sbaptfavour of 5384279528Sbapt.Li .save 5385279528Sbaptfor saving VFP registers for ARMv6 and above. 5386279528Sbapt.Pp 5387279528Sbapt.It .pad # Va count 5388279528SbaptGenerate unwinder annotations for a stack adjustment of 5389279528Sbapt.Va count 5390279528Sbaptbytes. A positive value indicates the function prologue allocated stack space 5391279528Sbaptby decrementing the stack pointer. 5392279528Sbapt.Pp 5393279528Sbapt.It .movsp Va reg [, # Va offset] 5394279528SbaptTell the unwinder that 5395279528Sbapt.Va reg 5396279528Sbaptcontains an offset from the current stack pointer. If 5397279528Sbapt.Va offset 5398279528Sbaptis not specified then it is assumed to be zero. 5399279528Sbapt.Pp 5400279528Sbapt.It .setfp Va fpreg, Va spreg [, # Va offset] 5401279528SbaptMake all unwinder annotations relaive to a frame pointer. Without this the 5402279528Sbaptunwinder will use offsets from the stack pointer. 5403279528Sbapt.Pp 5404279528SbaptThe syntax of this directive is the same as the 5405279528Sbapt.Li sub 5406279528Sbaptor 5407279528Sbapt.Li mov 5408279528Sbaptinstruction used to set the frame pointer. 5409279528Sbapt.Va spreg 5410279528Sbaptmust be either 5411279528Sbapt.Li sp 5412279528Sbaptor mentioned in a previous 5413279528Sbapt.Li .movsp 5414279528Sbaptdirective. 5415279528Sbapt.Pp 5416279528Sbapt.Bd -literal -offset indent 5417279528Sbapt\&.movsp ip 5418279528Sbaptmov ip, sp 5419279528Sbapt\&... 5420279528Sbapt\&.setfp fp, ip, #4 5421279528Sbaptsub fp, ip, #4 5422279528Sbapt.Ed 5423279528Sbapt.Pp 5424279528Sbapt.It .raw Va offset, Va byte1, ... 5425279528SbaptInsert one of more arbitary unwind opcode bytes, which are known to adjust 5426279528Sbaptthe stack pointer by 5427279528Sbapt.Va offset 5428279528Sbaptbytes. 5429279528Sbapt.Pp 5430279528SbaptFor example 5431279528Sbapt.Li .unwind_raw 4, 0xb1, 0x01 5432279528Sbaptis equivalent to 5433279528Sbapt.Li .save {r0} 5434279528Sbapt.Pp 5435279528Sbapt.It .cpu Va name 5436279528SbaptSelect the target processor. Valid values for 5437279528Sbapt.Va name 5438279528Sbaptare the same as for the 5439279528Sbapt.Op -mcpu 5440279528Sbaptcommandline option. 5441279528Sbapt.Pp 5442279528Sbapt.It .arch Va name 5443279528SbaptSelect the target architecture. Valid values for 5444279528Sbapt.Va name 5445279528Sbaptare the same as for the 5446279528Sbapt.Op -march 5447279528Sbaptcommandline option. 5448279528Sbapt.Pp 5449279528Sbapt.It .object_arch Va name 5450279528SbaptOverride the architecture recorded in the EABI object attribute section. Valid 5451279528Sbaptvalues for 5452279528Sbapt.Va name 5453279528Sbaptare the same as for the 5454279528Sbapt.Li .arch 5455279528Sbaptdirective. Typically this is useful when code uses runtime detection of CPU 5456279528Sbaptfeatures. 5457279528Sbapt.Pp 5458279528Sbapt.It .fpu Va name 5459279528SbaptSelect the floating point unit to assemble for. Valid values for 5460279528Sbapt.Va name 5461279528Sbaptare the same as for the 5462279528Sbapt.Op -mfpu 5463279528Sbaptcommandline option. 5464279528Sbapt.Pp 5465279528Sbapt.It .eabi_attribute Va tag, Va value 5466279528SbaptSet the EABI object attribute number 5467279528Sbapt.Va tag 5468279528Sbaptto 5469279528Sbapt.Va value . 5470279528SbaptThe value is either a 5471279528Sbapt.Li number , 5472279528Sbapt.Li "string" , 5473279528Sbaptor 5474279528Sbapt.Li number, "string" 5475279528Sbaptdepending on the tag. 5476279528Sbapt.Pp 5477279528Sbapt.El 5478279528Sbapt.Ss Opcodes 5479279528Sbapt.Li as 5480279528Sbaptimplements all the standard ARM opcodes. It also implements several pseudo 5481279528Sbaptopcodes, including several synthetic load instructions. 5482279528Sbapt.Pp 5483279528Sbapt.Bl -tag -width Ds 5484279528Sbapt.It NOP 5485279528Sbapt.Bd -literal -offset indent 5486279528Sbapt nop 5487279528Sbapt.Ed 5488279528Sbapt.Pp 5489279528SbaptThis pseudo op will always evaluate to a legal ARM instruction that does nothing. 5490279528SbaptCurrently it will evaluate to MOV r0, r0. 5491279528Sbapt.Pp 5492279528Sbapt.It LDR 5493279528Sbapt.Bd -literal -offset indent 5494279528Sbapt ldr <register> , = <expression> 5495279528Sbapt.Ed 5496279528Sbapt.Pp 5497279528SbaptIf expression evaluates to a numeric constant then a MOV or MVN instruction 5498279528Sbaptwill be used in place of the LDR instruction, if the constant can be generated 5499279528Sbaptby either of these instructions. Otherwise the constant will be placed into 5500279528Sbaptthe nearest literal pool (if it not already there) and a PC relative LDR instruction 5501279528Sbaptwill be generated. 5502279528Sbapt.Pp 5503279528Sbapt.It ADR 5504279528Sbapt.Bd -literal -offset indent 5505279528Sbapt adr <register> <label> 5506279528Sbapt.Ed 5507279528Sbapt.Pp 5508279528SbaptThis instruction will load the address of 5509279528Sbapt.Va label 5510279528Sbaptinto the indicated register. The instruction will evaluate to a PC relative 5511279528SbaptADD or SUB instruction depending upon where the label is located. If the label 5512279528Sbaptis out of range, or if it is not defined in the same file (and section) as 5513279528Sbaptthe ADR instruction, then an error will be generated. This instruction will 5514279528Sbaptnot make use of the literal pool. 5515279528Sbapt.Pp 5516279528Sbapt.It ADRL 5517279528Sbapt.Bd -literal -offset indent 5518279528Sbapt adrl <register> <label> 5519279528Sbapt.Ed 5520279528Sbapt.Pp 5521279528SbaptThis instruction will load the address of 5522279528Sbapt.Va label 5523279528Sbaptinto the indicated register. The instruction will evaluate to one or two PC 5524279528Sbaptrelative ADD or SUB instructions depending upon where the label is located. 5525279528SbaptIf a second instruction is not needed a NOP instruction will be generated 5526279528Sbaptin its place, so that this instruction is always 8 bytes long. 5527279528Sbapt.Pp 5528279528SbaptIf the label is out of range, or if it is not defined in the same file (and 5529279528Sbaptsection) as the ADRL instruction, then an error will be generated. This instruction 5530279528Sbaptwill not make use of the literal pool. 5531279528Sbapt.Pp 5532279528Sbapt.El 5533279528SbaptFor information on the ARM or Thumb instruction sets, see 5534279528Sbapt.Em ARM Software Development Toolkit Reference Manual , 5535279528SbaptAdvanced RISC Machines Ltd. 5536279528Sbapt.Pp 5537279528Sbapt.Ss Mapping Symbols 5538279528SbaptThe ARM ELF specification requires that special symbols be inserted into object 5539279528Sbaptfiles to mark certain features: 5540279528Sbapt.Pp 5541279528Sbapt.Bl -tag -width Ds 5542279528Sbapt.It $a 5543279528SbaptAt the start of a region of code containing ARM instructions. 5544279528Sbapt.Pp 5545279528Sbapt.It $t 5546279528SbaptAt the start of a region of code containing THUMB instructions. 5547279528Sbapt.Pp 5548279528Sbapt.It $d 5549279528SbaptAt the start of a region of data. 5550279528Sbapt.Pp 5551279528Sbapt.El 5552279528SbaptThe assembler will automatically insert these symbols for you - there is no 5553279528Sbaptneed to code them yourself. Support for tagging symbols ($b, $f, $p and $m) 5554279528Sbaptwhich is also mentioned in the current ARM ELF specification is not implemented. 5555279528SbaptThis is because they have been dropped from the new EABI and so tools cannot 5556279528Sbaptrely upon their presence. 5557279528Sbapt.Pp 5558279528Sbapt.Sh 80386 Dependent Features 5559279528SbaptThe i386 version 5560279528Sbapt.Li as 5561279528Sbaptsupports both the original Intel 386 architecture in both 16 and 32-bit mode 5562279528Sbaptas well as AMD x86-64 architecture extending the Intel architecture to 64-bits. 5563279528Sbapt.Pp 5564279528Sbapt.Ss Options 5565279528SbaptThe i386 version of 5566279528Sbapt.Li as 5567279528Sbapthas a few machine dependent options: 5568279528Sbapt.Pp 5569279528Sbapt.Bl -tag -width Ds 5570279528Sbapt.It --32 | --64 5571279528SbaptSelect the word size, either 32 bits or 64 bits. Selecting 32-bit implies 5572279528SbaptIntel i386 architecture, while 64-bit implies AMD x86-64 architecture. 5573279528Sbapt.Pp 5574279528SbaptThese options are only available with the ELF object file format, and require 5575279528Sbaptthat the necessary BFD support has been included (on a 32-bit platform you 5576279528Sbapthave to add --enable-64-bit-bfd to configure enable 64-bit usage and use x86-64 5577279528Sbaptas target platform). 5578279528Sbapt.Pp 5579279528Sbapt.It -n 5580279528SbaptBy default, x86 GAS replaces multiple nop instructions used for alignment 5581279528Sbaptwithin code sections with multi-byte nop instructions such as leal 0(%esi,1),%esi. 5582279528SbaptThis switch disables the optimization. 5583279528Sbapt.Pp 5584279528Sbapt.It --divide 5585279528SbaptOn SVR4-derived platforms, the character 5586279528Sbapt.Li / 5587279528Sbaptis treated as a comment character, which means that it cannot be used in expressions. 5588279528SbaptThe 5589279528Sbapt.Li --divide 5590279528Sbaptoption turns 5591279528Sbapt.Li / 5592279528Sbaptinto a normal character. This does not disable 5593279528Sbapt.Li / 5594279528Sbaptat the beginning of a line starting a comment, or affect using 5595279528Sbapt.Li # 5596279528Sbaptfor starting a comment. 5597279528Sbapt.Pp 5598279528Sbapt.It -march= Va CPU 5599279528SbaptThis option specifies an instruction set architecture for generating instructions. 5600279528SbaptThe following architectures are recognized: 5601279528Sbapt.Li i8086 , 5602279528Sbapt.Li i186 , 5603279528Sbapt.Li i286 , 5604279528Sbapt.Li i386 , 5605279528Sbapt.Li i486 , 5606279528Sbapt.Li i586 , 5607279528Sbapt.Li i686 , 5608279528Sbapt.Li pentium , 5609279528Sbapt.Li pentiumpro , 5610279528Sbapt.Li pentiumii , 5611279528Sbapt.Li pentiumiii , 5612279528Sbapt.Li pentium4 , 5613279528Sbapt.Li prescott , 5614279528Sbapt.Li nocona , 5615279528Sbapt.Li core , 5616279528Sbapt.Li core2 , 5617279528Sbapt.Li k6 , 5618279528Sbapt.Li k6_2 , 5619279528Sbapt.Li athlon , 5620279528Sbapt.Li sledgehammer , 5621279528Sbapt.Li opteron , 5622279528Sbapt.Li k8 , 5623279528Sbapt.Li generic32 5624279528Sbaptand 5625279528Sbapt.Li generic64 . 5626279528Sbapt.Pp 5627279528SbaptThis option only affects instructions generated by the assembler. The 5628279528Sbapt.Li .arch 5629279528Sbaptdirective will take precedent. 5630279528Sbapt.Pp 5631279528Sbapt.It -mtune= Va CPU 5632279528SbaptThis option specifies a processor to optimize for. When used in conjunction 5633279528Sbaptwith the 5634279528Sbapt.Op -march 5635279528Sbaptoption, only instructions of the processor specified by the 5636279528Sbapt.Op -march 5637279528Sbaptoption will be generated. 5638279528Sbapt.Pp 5639279528SbaptValid 5640279528Sbapt.Va CPU 5641279528Sbaptvalues are identical to 5642279528Sbapt.Op -march= Va CPU . 5643279528Sbapt.Pp 5644279528Sbapt.El 5645279528Sbapt.Ss AT&T Syntax versus Intel Syntax 5646279528Sbapt.Li as 5647279528Sbaptnow supports assembly using Intel assembler syntax. 5648279528Sbapt.Li .intel_syntax 5649279528Sbaptselects Intel mode, and 5650279528Sbapt.Li .att_syntax 5651279528Sbaptswitches back to the usual AT&T mode for compatibility with the output of 5652279528Sbapt.Li gcc . 5653279528SbaptEither of these directives may have an optional argument, 5654279528Sbapt.Li prefix , 5655279528Sbaptor 5656279528Sbapt.Li noprefix 5657279528Sbaptspecifying whether registers require a 5658279528Sbapt.Li % 5659279528Sbaptprefix. AT&T System V/386 assembler syntax is quite different from Intel syntax. 5660279528SbaptWe mention these differences because almost all 80386 documents use Intel 5661279528Sbaptsyntax. Notable differences between the two syntaxes are: 5662279528Sbapt.Pp 5663279528Sbapt.Bl -bullet 5664279528Sbapt.It 5665279528SbaptAT&T immediate operands are preceded by 5666279528Sbapt.Li $ ; 5667279528SbaptIntel immediate operands are undelimited (Intel 5668279528Sbapt.Li push 4 5669279528Sbaptis AT&T 5670279528Sbapt.Li pushl $4 ) . 5671279528SbaptAT&T register operands are preceded by 5672279528Sbapt.Li % ; 5673279528SbaptIntel register operands are undelimited. AT&T absolute (as opposed to PC relative) 5674279528Sbaptjump/call operands are prefixed by 5675279528Sbapt.Li * ; 5676279528Sbaptthey are undelimited in Intel syntax. 5677279528Sbapt.Pp 5678279528Sbapt.It 5679279528SbaptAT&T and Intel syntax use the opposite order for source and destination operands. 5680279528SbaptIntel 5681279528Sbapt.Li add eax, 4 5682279528Sbaptis 5683279528Sbapt.Li addl $4, %eax . 5684279528SbaptThe 5685279528Sbapt.Li source, dest 5686279528Sbaptconvention is maintained for compatibility with previous Unix assemblers. 5687279528SbaptNote that instructions with more than one source operand, such as the 5688279528Sbapt.Li enter 5689279528Sbaptinstruction, do 5690279528Sbapt.Em not 5691279528Sbapthave reversed order. i386-Bugs. 5692279528Sbapt.Pp 5693279528Sbapt.It 5694279528SbaptIn AT&T syntax the size of memory operands is determined from the last character 5695279528Sbaptof the instruction mnemonic. Mnemonic suffixes of 5696279528Sbapt.Li b , 5697279528Sbapt.Li w , 5698279528Sbapt.Li l 5699279528Sbaptand 5700279528Sbapt.Li q 5701279528Sbaptspecify byte (8-bit), word (16-bit), long (32-bit) and quadruple word (64-bit) 5702279528Sbaptmemory references. Intel syntax accomplishes this by prefixing memory operands 5703279528Sbapt( 5704279528Sbapt.Em not 5705279528Sbaptthe instruction mnemonics) with 5706279528Sbapt.Li byte ptr , 5707279528Sbapt.Li word ptr , 5708279528Sbapt.Li dword ptr 5709279528Sbaptand 5710279528Sbapt.Li qword ptr . 5711279528SbaptThus, Intel 5712279528Sbapt.Li mov al, byte ptr Va foo 5713279528Sbaptis 5714279528Sbapt.Li movb Va foo, %al 5715279528Sbaptin AT&T syntax. 5716279528Sbapt.Pp 5717279528Sbapt.It 5718279528SbaptImmediate form long jumps and calls are 5719279528Sbapt.Li lcall/ljmp $ Va section, $ Va offset 5720279528Sbaptin AT&T syntax; the Intel syntax is 5721279528Sbapt.Li call/jmp far Va section: Va offset . 5722279528SbaptAlso, the far return instruction is 5723279528Sbapt.Li lret $ Va stack-adjust 5724279528Sbaptin AT&T syntax; Intel syntax is 5725279528Sbapt.Li ret far Va stack-adjust . 5726279528Sbapt.Pp 5727279528Sbapt.It 5728279528SbaptThe AT&T assembler does not provide support for multiple section programs. 5729279528SbaptUnix style systems expect all programs to be single sections. 5730279528Sbapt.El 5731279528Sbapt.Pp 5732279528Sbapt.Ss Instruction Naming 5733279528SbaptInstruction mnemonics are suffixed with one character modifiers which specify 5734279528Sbaptthe size of operands. The letters 5735279528Sbapt.Li b , 5736279528Sbapt.Li w , 5737279528Sbapt.Li l 5738279528Sbaptand 5739279528Sbapt.Li q 5740279528Sbaptspecify byte, word, long and quadruple word operands. If no suffix is specified 5741279528Sbaptby an instruction then 5742279528Sbapt.Li as 5743279528Sbapttries to fill in the missing suffix based on the destination register operand 5744279528Sbapt(the last one by convention). Thus, 5745279528Sbapt.Li mov %ax, %bx 5746279528Sbaptis equivalent to 5747279528Sbapt.Li movw %ax, %bx ; 5748279528Sbaptalso, 5749279528Sbapt.Li mov $1, %bx 5750279528Sbaptis equivalent to 5751279528Sbapt.Li movw $1, bx . 5752279528SbaptNote that this is incompatible with the AT&T Unix assembler which assumes 5753279528Sbaptthat a missing mnemonic suffix implies long operand size. (This incompatibility 5754279528Sbaptdoes not affect compiler output since compilers always explicitly specify 5755279528Sbaptthe mnemonic suffix.) 5756279528Sbapt.Pp 5757279528SbaptAlmost all instructions have the same names in AT&T and Intel format. There 5758279528Sbaptare a few exceptions. The sign extend and zero extend instructions need two 5759279528Sbaptsizes to specify them. They need a size to sign/zero extend 5760279528Sbapt.Em from 5761279528Sbaptand a size to zero extend 5762279528Sbapt.Em to . 5763279528SbaptThis is accomplished by using two instruction mnemonic suffixes in AT&T syntax. 5764279528SbaptBase names for sign extend and zero extend are 5765279528Sbapt.Li movs... 5766279528Sbaptand 5767279528Sbapt.Li movz... 5768279528Sbaptin AT&T syntax ( 5769279528Sbapt.Li movsx 5770279528Sbaptand 5771279528Sbapt.Li movzx 5772279528Sbaptin Intel syntax). The instruction mnemonic suffixes are tacked on to this 5773279528Sbaptbase name, the 5774279528Sbapt.Em from 5775279528Sbaptsuffix before the 5776279528Sbapt.Em to 5777279528Sbaptsuffix. Thus, 5778279528Sbapt.Li movsbl %al, %edx 5779279528Sbaptis AT&T syntax for \(lqmove sign extend 5780279528Sbapt.Em from 5781279528Sbapt%al 5782279528Sbapt.Em to 5783279528Sbapt%edx.\(rq Possible suffixes, thus, are 5784279528Sbapt.Li bl 5785279528Sbapt(from byte to long), 5786279528Sbapt.Li bw 5787279528Sbapt(from byte to word), 5788279528Sbapt.Li wl 5789279528Sbapt(from word to long), 5790279528Sbapt.Li bq 5791279528Sbapt(from byte to quadruple word), 5792279528Sbapt.Li wq 5793279528Sbapt(from word to quadruple word), and 5794279528Sbapt.Li lq 5795279528Sbapt(from long to quadruple word). 5796279528Sbapt.Pp 5797279528SbaptThe Intel-syntax conversion instructions 5798279528Sbapt.Pp 5799279528Sbapt.Bl -bullet 5800279528Sbapt.It 5801279528Sbapt.Li cbw 5802279528Sbapt--- sign-extend byte in 5803279528Sbapt.Li %al 5804279528Sbaptto word in 5805279528Sbapt.Li %ax , 5806279528Sbapt.Pp 5807279528Sbapt.It 5808279528Sbapt.Li cwde 5809279528Sbapt--- sign-extend word in 5810279528Sbapt.Li %ax 5811279528Sbaptto long in 5812279528Sbapt.Li %eax , 5813279528Sbapt.Pp 5814279528Sbapt.It 5815279528Sbapt.Li cwd 5816279528Sbapt--- sign-extend word in 5817279528Sbapt.Li %ax 5818279528Sbaptto long in 5819279528Sbapt.Li %dx:%ax , 5820279528Sbapt.Pp 5821279528Sbapt.It 5822279528Sbapt.Li cdq 5823279528Sbapt--- sign-extend dword in 5824279528Sbapt.Li %eax 5825279528Sbaptto quad in 5826279528Sbapt.Li %edx:%eax , 5827279528Sbapt.Pp 5828279528Sbapt.It 5829279528Sbapt.Li cdqe 5830279528Sbapt--- sign-extend dword in 5831279528Sbapt.Li %eax 5832279528Sbaptto quad in 5833279528Sbapt.Li %rax 5834279528Sbapt(x86-64 only), 5835279528Sbapt.Pp 5836279528Sbapt.It 5837279528Sbapt.Li cqo 5838279528Sbapt--- sign-extend quad in 5839279528Sbapt.Li %rax 5840279528Sbaptto octuple in 5841279528Sbapt.Li %rdx:%rax 5842279528Sbapt(x86-64 only), 5843279528Sbapt.El 5844279528Sbapt.Pp 5845279528Sbaptare called 5846279528Sbapt.Li cbtw , 5847279528Sbapt.Li cwtl , 5848279528Sbapt.Li cwtd , 5849279528Sbapt.Li cltd , 5850279528Sbapt.Li cltq , 5851279528Sbaptand 5852279528Sbapt.Li cqto 5853279528Sbaptin AT&T naming. 5854279528Sbapt.Li as 5855279528Sbaptaccepts either naming for these instructions. 5856279528Sbapt.Pp 5857279528SbaptFar call/jump instructions are 5858279528Sbapt.Li lcall 5859279528Sbaptand 5860279528Sbapt.Li ljmp 5861279528Sbaptin AT&T syntax, but are 5862279528Sbapt.Li call far 5863279528Sbaptand 5864279528Sbapt.Li jump far 5865279528Sbaptin Intel convention. 5866279528Sbapt.Pp 5867279528Sbapt.Ss Register Naming 5868279528SbaptRegister operands are always prefixed with 5869279528Sbapt.Li % . 5870279528SbaptThe 80386 registers consist of 5871279528Sbapt.Pp 5872279528Sbapt.Bl -bullet 5873279528Sbapt.It 5874279528Sbaptthe 8 32-bit registers 5875279528Sbapt.Li %eax 5876279528Sbapt(the accumulator), 5877279528Sbapt.Li %ebx , 5878279528Sbapt.Li %ecx , 5879279528Sbapt.Li %edx , 5880279528Sbapt.Li %edi , 5881279528Sbapt.Li %esi , 5882279528Sbapt.Li %ebp 5883279528Sbapt(the frame pointer), and 5884279528Sbapt.Li %esp 5885279528Sbapt(the stack pointer). 5886279528Sbapt.Pp 5887279528Sbapt.It 5888279528Sbaptthe 8 16-bit low-ends of these: 5889279528Sbapt.Li %ax , 5890279528Sbapt.Li %bx , 5891279528Sbapt.Li %cx , 5892279528Sbapt.Li %dx , 5893279528Sbapt.Li %di , 5894279528Sbapt.Li %si , 5895279528Sbapt.Li %bp , 5896279528Sbaptand 5897279528Sbapt.Li %sp . 5898279528Sbapt.Pp 5899279528Sbapt.It 5900279528Sbaptthe 8 8-bit registers: 5901279528Sbapt.Li %ah , 5902279528Sbapt.Li %al , 5903279528Sbapt.Li %bh , 5904279528Sbapt.Li %bl , 5905279528Sbapt.Li %ch , 5906279528Sbapt.Li %cl , 5907279528Sbapt.Li %dh , 5908279528Sbaptand 5909279528Sbapt.Li %dl 5910279528Sbapt(These are the high-bytes and low-bytes of 5911279528Sbapt.Li %ax , 5912279528Sbapt.Li %bx , 5913279528Sbapt.Li %cx , 5914279528Sbaptand 5915279528Sbapt.Li %dx ) 5916279528Sbapt.Pp 5917279528Sbapt.It 5918279528Sbaptthe 6 section registers 5919279528Sbapt.Li %cs 5920279528Sbapt(code section), 5921279528Sbapt.Li %ds 5922279528Sbapt(data section), 5923279528Sbapt.Li %ss 5924279528Sbapt(stack section), 5925279528Sbapt.Li %es , 5926279528Sbapt.Li %fs , 5927279528Sbaptand 5928279528Sbapt.Li %gs . 5929279528Sbapt.Pp 5930279528Sbapt.It 5931279528Sbaptthe 3 processor control registers 5932279528Sbapt.Li %cr0 , 5933279528Sbapt.Li %cr2 , 5934279528Sbaptand 5935279528Sbapt.Li %cr3 . 5936279528Sbapt.Pp 5937279528Sbapt.It 5938279528Sbaptthe 6 debug registers 5939279528Sbapt.Li %db0 , 5940279528Sbapt.Li %db1 , 5941279528Sbapt.Li %db2 , 5942279528Sbapt.Li %db3 , 5943279528Sbapt.Li %db6 , 5944279528Sbaptand 5945279528Sbapt.Li %db7 . 5946279528Sbapt.Pp 5947279528Sbapt.It 5948279528Sbaptthe 2 test registers 5949279528Sbapt.Li %tr6 5950279528Sbaptand 5951279528Sbapt.Li %tr7 . 5952279528Sbapt.Pp 5953279528Sbapt.It 5954279528Sbaptthe 8 floating point register stack 5955279528Sbapt.Li %st 5956279528Sbaptor equivalently 5957279528Sbapt.Li %st(0) , 5958279528Sbapt.Li %st(1) , 5959279528Sbapt.Li %st(2) , 5960279528Sbapt.Li %st(3) , 5961279528Sbapt.Li %st(4) , 5962279528Sbapt.Li %st(5) , 5963279528Sbapt.Li %st(6) , 5964279528Sbaptand 5965279528Sbapt.Li %st(7) . 5966279528SbaptThese registers are overloaded by 8 MMX registers 5967279528Sbapt.Li %mm0 , 5968279528Sbapt.Li %mm1 , 5969279528Sbapt.Li %mm2 , 5970279528Sbapt.Li %mm3 , 5971279528Sbapt.Li %mm4 , 5972279528Sbapt.Li %mm5 , 5973279528Sbapt.Li %mm6 5974279528Sbaptand 5975279528Sbapt.Li %mm7 . 5976279528Sbapt.Pp 5977279528Sbapt.It 5978279528Sbaptthe 8 SSE registers registers 5979279528Sbapt.Li %xmm0 , 5980279528Sbapt.Li %xmm1 , 5981279528Sbapt.Li %xmm2 , 5982279528Sbapt.Li %xmm3 , 5983279528Sbapt.Li %xmm4 , 5984279528Sbapt.Li %xmm5 , 5985279528Sbapt.Li %xmm6 5986279528Sbaptand 5987279528Sbapt.Li %xmm7 . 5988279528Sbapt.El 5989279528Sbapt.Pp 5990279528SbaptThe AMD x86-64 architecture extends the register set by: 5991279528Sbapt.Pp 5992279528Sbapt.Bl -bullet 5993279528Sbapt.It 5994279528Sbaptenhancing the 8 32-bit registers to 64-bit: 5995279528Sbapt.Li %rax 5996279528Sbapt(the accumulator), 5997279528Sbapt.Li %rbx , 5998279528Sbapt.Li %rcx , 5999279528Sbapt.Li %rdx , 6000279528Sbapt.Li %rdi , 6001279528Sbapt.Li %rsi , 6002279528Sbapt.Li %rbp 6003279528Sbapt(the frame pointer), 6004279528Sbapt.Li %rsp 6005279528Sbapt(the stack pointer) 6006279528Sbapt.Pp 6007279528Sbapt.It 6008279528Sbaptthe 8 extended registers 6009279528Sbapt.Li %r8 6010279528Sbapt-- 6011279528Sbapt.Li %r15 . 6012279528Sbapt.Pp 6013279528Sbapt.It 6014279528Sbaptthe 8 32-bit low ends of the extended registers: 6015279528Sbapt.Li %r8d 6016279528Sbapt-- 6017279528Sbapt.Li %r15d 6018279528Sbapt.Pp 6019279528Sbapt.It 6020279528Sbaptthe 8 16-bit low ends of the extended registers: 6021279528Sbapt.Li %r8w 6022279528Sbapt-- 6023279528Sbapt.Li %r15w 6024279528Sbapt.Pp 6025279528Sbapt.It 6026279528Sbaptthe 8 8-bit low ends of the extended registers: 6027279528Sbapt.Li %r8b 6028279528Sbapt-- 6029279528Sbapt.Li %r15b 6030279528Sbapt.Pp 6031279528Sbapt.It 6032279528Sbaptthe 4 8-bit registers: 6033279528Sbapt.Li %sil , 6034279528Sbapt.Li %dil , 6035279528Sbapt.Li %bpl , 6036279528Sbapt.Li %spl . 6037279528Sbapt.Pp 6038279528Sbapt.It 6039279528Sbaptthe 8 debug registers: 6040279528Sbapt.Li %db8 6041279528Sbapt-- 6042279528Sbapt.Li %db15 . 6043279528Sbapt.Pp 6044279528Sbapt.It 6045279528Sbaptthe 8 SSE registers: 6046279528Sbapt.Li %xmm8 6047279528Sbapt-- 6048279528Sbapt.Li %xmm15 . 6049279528Sbapt.El 6050279528Sbapt.Pp 6051279528Sbapt.Ss Instruction Prefixes 6052279528SbaptInstruction prefixes are used to modify the following instruction. They are 6053279528Sbaptused to repeat string instructions, to provide section overrides, to perform 6054279528Sbaptbus lock operations, and to change operand and address sizes. (Most instructions 6055279528Sbaptthat normally operate on 32-bit operands will use 16-bit operands if the instruction 6056279528Sbapthas an \(lqoperand size\(rq prefix.) Instruction prefixes are best written on the 6057279528Sbaptsame line as the instruction they act upon. For example, the 6058279528Sbapt.Li scas 6059279528Sbapt(scan string) instruction is repeated with: 6060279528Sbapt.Pp 6061279528Sbapt.Bd -literal -offset indent 6062279528Sbapt repne scas %es:(%edi),%al 6063279528Sbapt.Ed 6064279528Sbapt.Pp 6065279528SbaptYou may also place prefixes on the lines immediately preceding the instruction, 6066279528Sbaptbut this circumvents checks that 6067279528Sbapt.Li as 6068279528Sbaptdoes with prefixes, and will not work with all prefixes. 6069279528Sbapt.Pp 6070279528SbaptHere is a list of instruction prefixes: 6071279528Sbapt.Pp 6072279528Sbapt.Bl -bullet 6073279528Sbapt.It 6074279528SbaptSection override prefixes 6075279528Sbapt.Li cs , 6076279528Sbapt.Li ds , 6077279528Sbapt.Li ss , 6078279528Sbapt.Li es , 6079279528Sbapt.Li fs , 6080279528Sbapt.Li gs . 6081279528SbaptThese are automatically added by specifying using the 6082279528Sbapt.Va section 6083279528Sbapt: 6084279528Sbapt.Va memory-operand 6085279528Sbaptform for memory references. 6086279528Sbapt.Pp 6087279528Sbapt.It 6088279528SbaptOperand/Address size prefixes 6089279528Sbapt.Li data16 6090279528Sbaptand 6091279528Sbapt.Li addr16 6092279528Sbaptchange 32-bit operands/addresses into 16-bit operands/addresses, while 6093279528Sbapt.Li data32 6094279528Sbaptand 6095279528Sbapt.Li addr32 6096279528Sbaptchange 16-bit ones (in a 6097279528Sbapt.Li .code16 6098279528Sbaptsection) into 32-bit operands/addresses. These prefixes 6099279528Sbapt.Em must 6100279528Sbaptappear on the same line of code as the instruction they modify. For example, 6101279528Sbaptin a 16-bit 6102279528Sbapt.Li .code16 6103279528Sbaptsection, you might write: 6104279528Sbapt.Pp 6105279528Sbapt.Bd -literal -offset indent 6106279528Sbapt addr32 jmpl *(%ebx) 6107279528Sbapt.Ed 6108279528Sbapt.Pp 6109279528Sbapt.It 6110279528SbaptThe bus lock prefix 6111279528Sbapt.Li lock 6112279528Sbaptinhibits interrupts during execution of the instruction it precedes. (This 6113279528Sbaptis only valid with certain instructions; see a 80386 manual for details). 6114279528Sbapt.Pp 6115279528Sbapt.It 6116279528SbaptThe wait for coprocessor prefix 6117279528Sbapt.Li wait 6118279528Sbaptwaits for the coprocessor to complete the current instruction. This should 6119279528Sbaptnever be needed for the 80386/80387 combination. 6120279528Sbapt.Pp 6121279528Sbapt.It 6122279528SbaptThe 6123279528Sbapt.Li rep , 6124279528Sbapt.Li repe , 6125279528Sbaptand 6126279528Sbapt.Li repne 6127279528Sbaptprefixes are added to string instructions to make them repeat 6128279528Sbapt.Li %ecx 6129279528Sbapttimes ( 6130279528Sbapt.Li %cx 6131279528Sbapttimes if the current address size is 16-bits). 6132279528Sbapt.It 6133279528SbaptThe 6134279528Sbapt.Li rex 6135279528Sbaptfamily of prefixes is used by x86-64 to encode extensions to i386 instruction 6136279528Sbaptset. The 6137279528Sbapt.Li rex 6138279528Sbaptprefix has four bits --- an operand size overwrite ( 6139279528Sbapt.Li 64 ) 6140279528Sbaptused to change operand size from 32-bit to 64-bit and X, Y and Z extensions 6141279528Sbaptbits used to extend the register set. 6142279528Sbapt.Pp 6143279528SbaptYou may write the 6144279528Sbapt.Li rex 6145279528Sbaptprefixes directly. The 6146279528Sbapt.Li rex64xyz 6147279528Sbaptinstruction emits 6148279528Sbapt.Li rex 6149279528Sbaptprefix with all the bits set. By omitting the 6150279528Sbapt.Li 64 , 6151279528Sbapt.Li x , 6152279528Sbapt.Li y 6153279528Sbaptor 6154279528Sbapt.Li z 6155279528Sbaptyou may write other prefixes as well. Normally, there is no need to write 6156279528Sbaptthe prefixes explicitly, since gas will automatically generate them based 6157279528Sbapton the instruction operands. 6158279528Sbapt.El 6159279528Sbapt.Pp 6160279528Sbapt.Ss Memory References 6161279528SbaptAn Intel syntax indirect memory reference of the form 6162279528Sbapt.Pp 6163279528Sbapt.Bd -literal -offset indent 6164279528Sbaptsection:[base + index*scale + disp] 6165279528Sbapt.Ed 6166279528Sbapt.Pp 6167279528Sbaptis translated into the AT&T syntax 6168279528Sbapt.Pp 6169279528Sbapt.Bd -literal -offset indent 6170279528Sbaptsection:disp(base, index, scale) 6171279528Sbapt.Ed 6172279528Sbapt.Pp 6173279528Sbaptwhere 6174279528Sbapt.Va base 6175279528Sbaptand 6176279528Sbapt.Va index 6177279528Sbaptare the optional 32-bit base and index registers, 6178279528Sbapt.Va disp 6179279528Sbaptis the optional displacement, and 6180279528Sbapt.Va scale , 6181279528Sbapttaking the values 1, 2, 4, and 8, multiplies 6182279528Sbapt.Va index 6183279528Sbaptto calculate the address of the operand. If no 6184279528Sbapt.Va scale 6185279528Sbaptis specified, 6186279528Sbapt.Va scale 6187279528Sbaptis taken to be 1. 6188279528Sbapt.Va section 6189279528Sbaptspecifies the optional section register for the memory operand, and may override 6190279528Sbaptthe default section register (see a 80386 manual for section register defaults). 6191279528SbaptNote that section overrides in AT&T syntax 6192279528Sbapt.Em must 6193279528Sbaptbe preceded by a 6194279528Sbapt.Li % . 6195279528SbaptIf you specify a section override which coincides with the default section 6196279528Sbaptregister, 6197279528Sbapt.Li as 6198279528Sbaptdoes 6199279528Sbapt.Em not 6200279528Sbaptoutput any section register override prefixes to assemble the given instruction. 6201279528SbaptThus, section overrides can be specified to emphasize which section register 6202279528Sbaptis used for a given memory operand. 6203279528Sbapt.Pp 6204279528SbaptHere are some examples of Intel and AT&T style memory references: 6205279528Sbapt.Pp 6206279528Sbapt.Bl -tag -width Ds 6207279528Sbapt.It AT&T: Li -4(%ebp), Intel: Li [ebp - 4] 6208279528Sbapt.Va base 6209279528Sbaptis 6210279528Sbapt.Li %ebp ; 6211279528Sbapt.Va disp 6212279528Sbaptis 6213279528Sbapt.Li -4 . 6214279528Sbapt.Va section 6215279528Sbaptis missing, and the default section is used ( 6216279528Sbapt.Li %ss 6217279528Sbaptfor addressing with 6218279528Sbapt.Li %ebp 6219279528Sbaptas the base register). 6220279528Sbapt.Va index , 6221279528Sbapt.Va scale 6222279528Sbaptare both missing. 6223279528Sbapt.Pp 6224279528Sbapt.It AT&T: Li foo(,%eax,4), Intel: Li [foo + eax*4] 6225279528Sbapt.Va index 6226279528Sbaptis 6227279528Sbapt.Li %eax 6228279528Sbapt(scaled by a 6229279528Sbapt.Va scale 6230279528Sbapt4); 6231279528Sbapt.Va disp 6232279528Sbaptis 6233279528Sbapt.Li foo . 6234279528SbaptAll other fields are missing. The section register here defaults to 6235279528Sbapt.Li %ds . 6236279528Sbapt.Pp 6237279528Sbapt.It AT&T: Li foo(,1); Intel Li [foo] 6238279528SbaptThis uses the value pointed to by 6239279528Sbapt.Li foo 6240279528Sbaptas a memory operand. Note that 6241279528Sbapt.Va base 6242279528Sbaptand 6243279528Sbapt.Va index 6244279528Sbaptare both missing, but there is only 6245279528Sbapt.Em one 6246279528Sbapt.Li , . 6247279528SbaptThis is a syntactic exception. 6248279528Sbapt.Pp 6249279528Sbapt.It AT&T: Li %gs:foo; Intel Li gs:foo 6250279528SbaptThis selects the contents of the variable 6251279528Sbapt.Li foo 6252279528Sbaptwith section register 6253279528Sbapt.Va section 6254279528Sbaptbeing 6255279528Sbapt.Li %gs . 6256279528Sbapt.El 6257279528Sbapt.Pp 6258279528SbaptAbsolute (as opposed to PC relative) call and jump operands must be prefixed 6259279528Sbaptwith 6260279528Sbapt.Li * . 6261279528SbaptIf no 6262279528Sbapt.Li * 6263279528Sbaptis specified, 6264279528Sbapt.Li as 6265279528Sbaptalways chooses PC relative addressing for jump/call labels. 6266279528Sbapt.Pp 6267279528SbaptAny instruction that has a memory operand, but no register operand, 6268279528Sbapt.Em must 6269279528Sbaptspecify its size (byte, word, long, or quadruple) with an instruction mnemonic 6270279528Sbaptsuffix ( 6271279528Sbapt.Li b , 6272279528Sbapt.Li w , 6273279528Sbapt.Li l 6274279528Sbaptor 6275279528Sbapt.Li q , 6276279528Sbaptrespectively). 6277279528Sbapt.Pp 6278279528SbaptThe x86-64 architecture adds an RIP (instruction pointer relative) addressing. 6279279528SbaptThis addressing mode is specified by using 6280279528Sbapt.Li rip 6281279528Sbaptas a base register. Only constant offsets are valid. For example: 6282279528Sbapt.Pp 6283279528Sbapt.Bl -tag -width Ds 6284279528Sbapt.It AT&T: Li 1234(%rip), Intel: Li [rip + 1234] 6285279528SbaptPoints to the address 1234 bytes past the end of the current instruction. 6286279528Sbapt.Pp 6287279528Sbapt.It AT&T: Li symbol(%rip), Intel: Li [rip + symbol] 6288279528SbaptPoints to the 6289279528Sbapt.Li symbol 6290279528Sbaptin RIP relative way, this is shorter than the default absolute addressing. 6291279528Sbapt.El 6292279528Sbapt.Pp 6293279528SbaptOther addressing modes remain unchanged in x86-64 architecture, except registers 6294279528Sbaptused are 64-bit instead of 32-bit. 6295279528Sbapt.Pp 6296279528Sbapt.Ss Handling of Jump Instructions 6297279528SbaptJump instructions are always optimized to use the smallest possible displacements. 6298279528SbaptThis is accomplished by using byte (8-bit) displacement jumps whenever the 6299279528Sbapttarget is sufficiently close. If a byte displacement is insufficient a long 6300279528Sbaptdisplacement is used. We do not support word (16-bit) displacement jumps in 6301279528Sbapt32-bit mode (i.e. prefixing the jump instruction with the 6302279528Sbapt.Li data16 6303279528Sbaptinstruction prefix), since the 80386 insists upon masking 6304279528Sbapt.Li %eip 6305279528Sbaptto 16 bits after the word displacement is added. (See alsosee Section 6306279528Sbapt.Dq i386-Arch ) 6307279528Sbapt.Pp 6308279528SbaptNote that the 6309279528Sbapt.Li jcxz , 6310279528Sbapt.Li jecxz , 6311279528Sbapt.Li loop , 6312279528Sbapt.Li loopz , 6313279528Sbapt.Li loope , 6314279528Sbapt.Li loopnz 6315279528Sbaptand 6316279528Sbapt.Li loopne 6317279528Sbaptinstructions only come in byte displacements, so that if you use these instructions 6318279528Sbapt( 6319279528Sbapt.Li gcc 6320279528Sbaptdoes not use them) you may get an error message (and incorrect code). The 6321279528SbaptAT&T 80386 assembler tries to get around this problem by expanding 6322279528Sbapt.Li jcxz foo 6323279528Sbaptto 6324279528Sbapt.Pp 6325279528Sbapt.Bd -literal -offset indent 6326279528Sbapt jcxz cx_zero 6327279528Sbapt jmp cx_nonzero 6328279528Sbaptcx_zero: jmp foo 6329279528Sbaptcx_nonzero: 6330279528Sbapt.Ed 6331279528Sbapt.Pp 6332279528Sbapt.Ss Floating Point 6333279528SbaptAll 80387 floating point types except packed BCD are supported. (BCD support 6334279528Sbaptmay be added without much difficulty). These data types are 16-, 32-, and 6335279528Sbapt64- bit integers, and single (32-bit), double (64-bit), and extended (80-bit) 6336279528Sbaptprecision floating point. Each supported type has an instruction mnemonic 6337279528Sbaptsuffix and a constructor associated with it. Instruction mnemonic suffixes 6338279528Sbaptspecify the operand's data type. Constructors build these data types into 6339279528Sbaptmemory. 6340279528Sbapt.Pp 6341279528Sbapt.Bl -bullet 6342279528Sbapt.It 6343279528SbaptFloating point constructors are 6344279528Sbapt.Li .float 6345279528Sbaptor 6346279528Sbapt.Li .single , 6347279528Sbapt.Li .double , 6348279528Sbaptand 6349279528Sbapt.Li .tfloat 6350279528Sbaptfor 32-, 64-, and 80-bit formats. These correspond to instruction mnemonic 6351279528Sbaptsuffixes 6352279528Sbapt.Li s , 6353279528Sbapt.Li l , 6354279528Sbaptand 6355279528Sbapt.Li t . 6356279528Sbapt.Li t 6357279528Sbaptstands for 80-bit (ten byte) real. The 80387 only supports this format via 6358279528Sbaptthe 6359279528Sbapt.Li fldt 6360279528Sbapt(load 80-bit real to stack top) and 6361279528Sbapt.Li fstpt 6362279528Sbapt(store 80-bit real and pop stack) instructions. 6363279528Sbapt.Pp 6364279528Sbapt.It 6365279528SbaptInteger constructors are 6366279528Sbapt.Li .word , 6367279528Sbapt.Li .long 6368279528Sbaptor 6369279528Sbapt.Li .int , 6370279528Sbaptand 6371279528Sbapt.Li .quad 6372279528Sbaptfor the 16-, 32-, and 64-bit integer formats. The corresponding instruction 6373279528Sbaptmnemonic suffixes are 6374279528Sbapt.Li s 6375279528Sbapt(single), 6376279528Sbapt.Li l 6377279528Sbapt(long), and 6378279528Sbapt.Li q 6379279528Sbapt(quad). As with the 80-bit real format, the 64-bit 6380279528Sbapt.Li q 6381279528Sbaptformat is only present in the 6382279528Sbapt.Li fildq 6383279528Sbapt(load quad integer to stack top) and 6384279528Sbapt.Li fistpq 6385279528Sbapt(store quad integer and pop stack) instructions. 6386279528Sbapt.El 6387279528Sbapt.Pp 6388279528SbaptRegister to register operations should not use instruction mnemonic suffixes. 6389279528Sbapt.Li fstl %st, %st(1) 6390279528Sbaptwill give a warning, and be assembled as if you wrote 6391279528Sbapt.Li fst %st, %st(1) , 6392279528Sbaptsince all register to register operations use 80-bit floating point operands. 6393279528Sbapt(Contrast this with 6394279528Sbapt.Li fstl %st, mem , 6395279528Sbaptwhich converts 6396279528Sbapt.Li %st 6397279528Sbaptfrom 80-bit to 64-bit floating point format, then stores the result in the 6398279528Sbapt4 byte location 6399279528Sbapt.Li mem ) 6400279528Sbapt.Pp 6401279528Sbapt.Ss Intel's MMX and AMD's 3DNow! SIMD Operations 6402279528Sbapt.Li as 6403279528Sbaptsupports Intel's MMX instruction set (SIMD instructions for integer data), 6404279528Sbaptavailable on Intel's Pentium MMX processors and Pentium II processors, AMD's 6405279528SbaptK6 and K6-2 processors, Cyrix' M2 processor, and probably others. It also 6406279528Sbaptsupports AMD's 3DNow! instruction set (SIMD instructions for 32-bit floating 6407279528Sbaptpoint data) available on AMD's K6-2 processor and possibly others in the future. 6408279528Sbapt.Pp 6409279528SbaptCurrently, 6410279528Sbapt.Li as 6411279528Sbaptdoes not support Intel's floating point SIMD, Katmai (KNI). 6412279528Sbapt.Pp 6413279528SbaptThe eight 64-bit MMX operands, also used by 3DNow!, are called 6414279528Sbapt.Li %mm0 , 6415279528Sbapt.Li %mm1 , 6416279528Sbapt\&... 6417279528Sbapt.Li %mm7 . 6418279528SbaptThey contain eight 8-bit integers, four 16-bit integers, two 32-bit integers, 6419279528Sbaptone 64-bit integer, or two 32-bit floating point values. The MMX registers 6420279528Sbaptcannot be used at the same time as the floating point stack. 6421279528Sbapt.Pp 6422279528SbaptSee Intel and AMD documentation, keeping in mind that the operand order in 6423279528Sbaptinstructions is reversed from the Intel syntax. 6424279528Sbapt.Pp 6425279528Sbapt.Ss Writing 16-bit Code 6426279528SbaptWhile 6427279528Sbapt.Li as 6428279528Sbaptnormally writes only \(lqpure\(rq 32-bit i386 code or 64-bit x86-64 code depending 6429279528Sbapton the default configuration, it also supports writing code to run in real 6430279528Sbaptmode or in 16-bit protected mode code segments. To do this, put a 6431279528Sbapt.Li .code16 6432279528Sbaptor 6433279528Sbapt.Li .code16gcc 6434279528Sbaptdirective before the assembly language instructions to be run in 16-bit mode. 6435279528SbaptYou can switch 6436279528Sbapt.Li as 6437279528Sbaptback to writing normal 32-bit code with the 6438279528Sbapt.Li .code32 6439279528Sbaptdirective. 6440279528Sbapt.Pp 6441279528Sbapt.Li .code16gcc 6442279528Sbaptprovides experimental support for generating 16-bit code from gcc, and differs 6443279528Sbaptfrom 6444279528Sbapt.Li .code16 6445279528Sbaptin that 6446279528Sbapt.Li call , 6447279528Sbapt.Li ret , 6448279528Sbapt.Li enter , 6449279528Sbapt.Li leave , 6450279528Sbapt.Li push , 6451279528Sbapt.Li pop , 6452279528Sbapt.Li pusha , 6453279528Sbapt.Li popa , 6454279528Sbapt.Li pushf , 6455279528Sbaptand 6456279528Sbapt.Li popf 6457279528Sbaptinstructions default to 32-bit size. This is so that the stack pointer is 6458279528Sbaptmanipulated in the same way over function calls, allowing access to function 6459279528Sbaptparameters at the same stack offsets as in 32-bit mode. 6460279528Sbapt.Li .code16gcc 6461279528Sbaptalso automatically adds address size prefixes where necessary to use the 32-bit 6462279528Sbaptaddressing modes that gcc generates. 6463279528Sbapt.Pp 6464279528SbaptThe code which 6465279528Sbapt.Li as 6466279528Sbaptgenerates in 16-bit mode will not necessarily run on a 16-bit pre-80386 processor. 6467279528SbaptTo write code that runs on such a processor, you must refrain from using 6468279528Sbapt.Em any 6469279528Sbapt32-bit constructs which require 6470279528Sbapt.Li as 6471279528Sbaptto output address or operand size prefixes. 6472279528Sbapt.Pp 6473279528SbaptNote that writing 16-bit code instructions by explicitly specifying a prefix 6474279528Sbaptor an instruction mnemonic suffix within a 32-bit code section generates different 6475279528Sbaptmachine instructions than those generated for a 16-bit code segment. In a 6476279528Sbapt32-bit code section, the following code generates the machine opcode bytes 6477279528Sbapt.Li 66 6a 04 , 6478279528Sbaptwhich pushes the value 6479279528Sbapt.Li 4 6480279528Sbaptonto the stack, decrementing 6481279528Sbapt.Li %esp 6482279528Sbaptby 2. 6483279528Sbapt.Pp 6484279528Sbapt.Bd -literal -offset indent 6485279528Sbapt pushw $4 6486279528Sbapt.Ed 6487279528Sbapt.Pp 6488279528SbaptThe same code in a 16-bit code section would generate the machine opcode bytes 6489279528Sbapt.Li 6a 04 6490279528Sbapt(i.e., without the operand size prefix), which is correct since the processor 6491279528Sbaptdefault operand size is assumed to be 16 bits in a 16-bit code section. 6492279528Sbapt.Pp 6493279528Sbapt.Ss AT&T Syntax bugs 6494279528SbaptThe UnixWare assembler, and probably other AT&T derived ix86 Unix assemblers, 6495279528Sbaptgenerate floating point instructions with reversed source and destination 6496279528Sbaptregisters in certain cases. Unfortunately, gcc and possibly many other programs 6497279528Sbaptuse this reversed syntax, so we're stuck with it. 6498279528Sbapt.Pp 6499279528SbaptFor example 6500279528Sbapt.Pp 6501279528Sbapt.Bd -literal -offset indent 6502279528Sbapt fsub %st,%st(3) 6503279528Sbapt.Ed 6504279528Sbaptresults in 6505279528Sbapt.Li %st(3) 6506279528Sbaptbeing updated to 6507279528Sbapt.Li %st - %st(3) 6508279528Sbaptrather than the expected 6509279528Sbapt.Li %st(3) - %st . 6510279528SbaptThis happens with all the non-commutative arithmetic floating point operations 6511279528Sbaptwith two register operands where the source register is 6512279528Sbapt.Li %st 6513279528Sbaptand the destination register is 6514279528Sbapt.Li %st(i) . 6515279528Sbapt.Pp 6516279528Sbapt.Ss Specifying CPU Architecture 6517279528Sbapt.Li as 6518279528Sbaptmay be told to assemble for a particular CPU (sub-)architecture with the 6519279528Sbapt.Li .arch Va cpu_type 6520279528Sbaptdirective. This directive enables a warning when gas detects an instruction 6521279528Sbaptthat is not supported on the CPU specified. The choices for 6522279528Sbapt.Va cpu_type 6523279528Sbaptare: 6524279528Sbapt.Pp 6525279528Sbapt.TS 6526279528Sbaptl l l l. 6527279528Sbapt 6528279528Sbapti8086 i186 i286 i386 6529279528Sbapti486 i586 i686 pentium 6530279528Sbaptpentiumpro pentiumii pentiumiii pentium4 6531279528Sbaptprescott nocona core core2 6532279528Sbaptamdfam10 6533279528Sbaptk6 athlon sledgehammer k8 6534279528Sbapt\&.mmx .sse .sse2 .sse3 6535279528Sbapt\&.ssse3 .sse4.1 .sse4.2 .sse4 6536279528Sbapt\&.sse4a .3dnow .3dnowa .padlock 6537279528Sbapt\&.pacifica .svme .abm 6538279528Sbapt.TE 6539279528Sbapt.Pp 6540279528SbaptApart from the warning, there are only two other effects on 6541279528Sbapt.Li as 6542279528Sbaptoperation; Firstly, if you specify a CPU other than 6543279528Sbapt.Li i486 , 6544279528Sbaptthen shift by one instructions such as 6545279528Sbapt.Li sarl $1, %eax 6546279528Sbaptwill automatically use a two byte opcode sequence. The larger three byte opcode 6547279528Sbaptsequence is used on the 486 (and when no architecture is specified) because 6548279528Sbaptit executes faster on the 486. Note that you can explicitly request the two 6549279528Sbaptbyte opcode by writing 6550279528Sbapt.Li sarl %eax . 6551279528SbaptSecondly, if you specify 6552279528Sbapt.Li i8086 , 6553279528Sbapt.Li i186 , 6554279528Sbaptor 6555279528Sbapt.Li i286 , 6556279528Sbapt.Em and 6557279528Sbapt.Li .code16 6558279528Sbaptor 6559279528Sbapt.Li .code16gcc 6560279528Sbaptthen byte offset conditional jumps will be promoted when necessary to a two 6561279528Sbaptinstruction sequence consisting of a conditional jump of the opposite sense 6562279528Sbaptaround an unconditional jump to the target. 6563279528Sbapt.Pp 6564279528SbaptFollowing the CPU architecture (but not a sub-architecture, which are those 6565279528Sbaptstarting with a dot), you may specify 6566279528Sbapt.Li jumps 6567279528Sbaptor 6568279528Sbapt.Li nojumps 6569279528Sbaptto control automatic promotion of conditional jumps. 6570279528Sbapt.Li jumps 6571279528Sbaptis the default, and enables jump promotion; All external jumps will be of 6572279528Sbaptthe long variety, and file-local jumps will be promoted as necessary. (see Section 6573279528Sbapt.Dq i386-Jumps ) 6574279528Sbapt.Li nojumps 6575279528Sbaptleaves external conditional jumps as byte offset jumps, and warns about file-local 6576279528Sbaptconditional jumps that 6577279528Sbapt.Li as 6578279528Sbaptpromotes. Unconditional jumps are treated as for 6579279528Sbapt.Li jumps . 6580279528Sbapt.Pp 6581279528SbaptFor example 6582279528Sbapt.Pp 6583279528Sbapt.Bd -literal -offset indent 6584279528Sbapt .arch i8086,nojumps 6585279528Sbapt.Ed 6586279528Sbapt.Pp 6587279528Sbapt.Ss Notes 6588279528SbaptThere is some trickery concerning the 6589279528Sbapt.Li mul 6590279528Sbaptand 6591279528Sbapt.Li imul 6592279528Sbaptinstructions that deserves mention. The 16-, 32-, 64- and 128-bit expanding 6593279528Sbaptmultiplies (base opcode 6594279528Sbapt.Li 0xf6 ; 6595279528Sbaptextension 4 for 6596279528Sbapt.Li mul 6597279528Sbaptand 5 for 6598279528Sbapt.Li imul ) 6599279528Sbaptcan be output only in the one operand form. Thus, 6600279528Sbapt.Li imul %ebx, %eax 6601279528Sbaptdoes 6602279528Sbapt.Em not 6603279528Sbaptselect the expanding multiply; the expanding multiply would clobber the 6604279528Sbapt.Li %edx 6605279528Sbaptregister, and this would confuse 6606279528Sbapt.Li gcc 6607279528Sbaptoutput. Use 6608279528Sbapt.Li imul %ebx 6609279528Sbaptto get the 64-bit product in 6610279528Sbapt.Li %edx:%eax . 6611279528Sbapt.Pp 6612279528SbaptWe have added a two operand form of 6613279528Sbapt.Li imul 6614279528Sbaptwhen the first operand is an immediate mode expression and the second operand 6615279528Sbaptis a register. This is just a shorthand, so that, multiplying 6616279528Sbapt.Li %eax 6617279528Sbaptby 69, for example, can be done with 6618279528Sbapt.Li imul $69, %eax 6619279528Sbaptrather than 6620279528Sbapt.Li imul $69, %eax, %eax . 6621279528Sbapt.Pp 6622279528Sbapt.Sh IA-64 Dependent Features 6623279528Sbapt.Ss Options 6624279528Sbapt.Bl -tag -width Ds 6625279528Sbapt.It -mconstant-gp 6626279528SbaptThis option instructs the assembler to mark the resulting object file as using 6627279528Sbaptthe \(lqconstant GP\(rq model. With this model, it is assumed that the entire program 6628279528Sbaptuses a single global pointer (GP) value. Note that this option does not in 6629279528Sbaptany fashion affect the machine code emitted by the assembler. All it does 6630279528Sbaptis turn on the EF_IA_64_CONS_GP flag in the ELF file header. 6631279528Sbapt.Pp 6632279528Sbapt.It -mauto-pic 6633279528SbaptThis option instructs the assembler to mark the resulting object file as using 6634279528Sbaptthe \(lqconstant GP without function descriptor\(rq data model. This model is like 6635279528Sbaptthe \(lqconstant GP\(rq model, except that it additionally does away with function 6636279528Sbaptdescriptors. What this means is that the address of a function refers directly 6637279528Sbaptto the function's code entry-point. Normally, such an address would refer 6638279528Sbaptto a function descriptor, which contains both the code entry-point and the 6639279528SbaptGP-value needed by the function. Note that this option does not in any fashion 6640279528Sbaptaffect the machine code emitted by the assembler. All it does is turn on the 6641279528SbaptEF_IA_64_NOFUNCDESC_CONS_GP flag in the ELF file header. 6642279528Sbapt.Pp 6643279528Sbapt.It -milp32 6644279528Sbapt.It -milp64 6645279528Sbapt.It -mlp64 6646279528Sbapt.It -mp64 6647279528SbaptThese options select the data model. The assembler defaults to 6648279528Sbapt.Li -mlp64 6649279528Sbapt(LP64 data model). 6650279528Sbapt.Pp 6651279528Sbapt.It -mle 6652279528Sbapt.It -mbe 6653279528SbaptThese options select the byte order. The 6654279528Sbapt.Li -mle 6655279528Sbaptoption selects little-endian byte order (default) and 6656279528Sbapt.Li -mbe 6657279528Sbaptselects big-endian byte order. Note that IA-64 machine code always uses little-endian 6658279528Sbaptbyte order. 6659279528Sbapt.Pp 6660279528Sbapt.It -mtune=itanium1 6661279528Sbapt.It -mtune=itanium2 6662279528SbaptTune for a particular IA-64 CPU, 6663279528Sbapt.Va itanium1 6664279528Sbaptor 6665279528Sbapt.Va itanium2 . 6666279528SbaptThe default is 6667279528Sbapt.Va itanium2 . 6668279528Sbapt.Pp 6669279528Sbapt.It -munwind-check=warning 6670279528Sbapt.It -munwind-check=error 6671279528SbaptThese options control what the assembler will do when performing consistency 6672279528Sbaptchecks on unwind directives. 6673279528Sbapt.Li -munwind-check=warning 6674279528Sbaptwill make the assembler issue a warning when an unwind directive check fails. 6675279528SbaptThis is the default. 6676279528Sbapt.Li -munwind-check=error 6677279528Sbaptwill make the assembler issue an error when an unwind directive check fails. 6678279528Sbapt.Pp 6679279528Sbapt.It -mhint.b=ok 6680279528Sbapt.It -mhint.b=warning 6681279528Sbapt.It -mhint.b=error 6682279528SbaptThese options control what the assembler will do when the 6683279528Sbapt.Li hint.b 6684279528Sbaptinstruction is used. 6685279528Sbapt.Li -mhint.b=ok 6686279528Sbaptwill make the assembler accept 6687279528Sbapt.Li hint.b . 6688279528Sbapt.Li -mint.b=warning 6689279528Sbaptwill make the assembler issue a warning when 6690279528Sbapt.Li hint.b 6691279528Sbaptis used. 6692279528Sbapt.Li -mhint.b=error 6693279528Sbaptwill make the assembler treat 6694279528Sbapt.Li hint.b 6695279528Sbaptas an error, which is the default. 6696279528Sbapt.Pp 6697279528Sbapt.It -x 6698279528Sbapt.It -xexplicit 6699279528SbaptThese options turn on dependency violation checking. 6700279528Sbapt.Pp 6701279528Sbapt.It -xauto 6702279528SbaptThis option instructs the assembler to automatically insert stop bits where 6703279528Sbaptnecessary to remove dependency violations. This is the default mode. 6704279528Sbapt.Pp 6705279528Sbapt.It -xnone 6706279528SbaptThis option turns off dependency violation checking. 6707279528Sbapt.Pp 6708279528Sbapt.It -xdebug 6709279528SbaptThis turns on debug output intended to help tracking down bugs in the dependency 6710279528Sbaptviolation checker. 6711279528Sbapt.Pp 6712279528Sbapt.It -xdebugn 6713279528SbaptThis is a shortcut for -xnone -xdebug. 6714279528Sbapt.Pp 6715279528Sbapt.It -xdebugx 6716279528SbaptThis is a shortcut for -xexplicit -xdebug. 6717279528Sbapt.Pp 6718279528Sbapt.El 6719279528Sbapt.Ss Syntax 6720279528SbaptThe assembler syntax closely follows the IA-64 Assembly Language Reference 6721279528SbaptGuide. 6722279528Sbapt.Pp 6723279528Sbapt.Em Special Characters 6724279528Sbapt.Pp 6725279528Sbapt.Li // 6726279528Sbaptis the line comment token. 6727279528Sbapt.Pp 6728279528Sbapt.Li ; 6729279528Sbaptcan be used instead of a newline to separate statements. 6730279528Sbapt.Pp 6731279528Sbapt.Em Register Names 6732279528Sbapt.Pp 6733279528SbaptThe 128 integer registers are referred to as 6734279528Sbapt.Li r Va n . 6735279528SbaptThe 128 floating-point registers are referred to as 6736279528Sbapt.Li f Va n . 6737279528SbaptThe 128 application registers are referred to as 6738279528Sbapt.Li ar Va n . 6739279528SbaptThe 128 control registers are referred to as 6740279528Sbapt.Li cr Va n . 6741279528SbaptThe 64 one-bit predicate registers are referred to as 6742279528Sbapt.Li p Va n . 6743279528SbaptThe 8 branch registers are referred to as 6744279528Sbapt.Li b Va n . 6745279528SbaptIn addition, the assembler defines a number of aliases: 6746279528Sbapt.Li gp 6747279528Sbapt( 6748279528Sbapt.Li r1 ) , 6749279528Sbapt.Li sp 6750279528Sbapt( 6751279528Sbapt.Li r12 ) , 6752279528Sbapt.Li rp 6753279528Sbapt( 6754279528Sbapt.Li b0 ) , 6755279528Sbapt.Li ret0 6756279528Sbapt( 6757279528Sbapt.Li r8 ) , 6758279528Sbapt.Li ret1 6759279528Sbapt( 6760279528Sbapt.Li r9 ) , 6761279528Sbapt.Li ret2 6762279528Sbapt( 6763279528Sbapt.Li r10 ) , 6764279528Sbapt.Li ret3 6765279528Sbapt( 6766279528Sbapt.Li r9 ) , 6767279528Sbapt.Li farg Va n 6768279528Sbapt( 6769279528Sbapt.Li f8+ Va n ) , 6770279528Sbaptand 6771279528Sbapt.Li fret Va n 6772279528Sbapt( 6773279528Sbapt.Li f8+ Va n ) . 6774279528Sbapt.Pp 6775279528SbaptFor convenience, the assembler also defines aliases for all named application 6776279528Sbaptand control registers. For example, 6777279528Sbapt.Li ar.bsp 6778279528Sbaptrefers to the register backing store pointer ( 6779279528Sbapt.Li ar17 ) . 6780279528SbaptSimilarly, 6781279528Sbapt.Li cr.eoi 6782279528Sbaptrefers to the end-of-interrupt register ( 6783279528Sbapt.Li cr67 ) . 6784279528Sbapt.Pp 6785279528Sbapt.Em IA-64 Processor-Status-Register (PSR) Bit Names 6786279528Sbapt.Pp 6787279528SbaptThe assembler defines bit masks for each of the bits in the IA-64 processor 6788279528Sbaptstatus register. For example, 6789279528Sbapt.Li psr.ic 6790279528Sbaptcorresponds to a value of 0x2000. These masks are primarily intended for use 6791279528Sbaptwith the 6792279528Sbapt.Li ssm 6793279528Sbapt/ 6794279528Sbapt.Li sum 6795279528Sbaptand 6796279528Sbapt.Li rsm 6797279528Sbapt/ 6798279528Sbapt.Li rum 6799279528Sbaptinstructions, but they can be used anywhere else where an integer constant 6800279528Sbaptis expected. 6801279528Sbapt.Pp 6802279528Sbapt.Ss Opcodes 6803279528SbaptFor detailed information on the IA-64 machine instruction set, see the 6804279528Sbapt.Lk http://developer.intel.com/design/itanium/arch_spec.htm . 6805279528Sbapt.Pp 6806279528Sbapt.Sh MIPS Dependent Features 6807279528SbaptGNU 6808279528Sbapt.Li as 6809279528Sbaptfor mips architectures supports several different mips processors, and MIPS 6810279528SbaptISA levels I through V, MIPS32, and MIPS64. For information about the mips 6811279528Sbaptinstruction set, see 6812279528Sbapt.Em MIPS RISC Architecture , 6813279528Sbaptby Kane and Heindrich (Prentice-Hall). For an overview of mips assembly conventions, 6814279528Sbaptsee \(lqAppendix D: Assembly Language Programming\(rq in the same work. 6815279528Sbapt.Pp 6816279528Sbapt.Ss Assembler options 6817279528SbaptThe mips configurations of GNU 6818279528Sbapt.Li as 6819279528Sbaptsupport these special options: 6820279528Sbapt.Pp 6821279528Sbapt.Bl -tag -width Ds 6822279528Sbapt.It -G Va num 6823279528SbaptThis option sets the largest size of an object that can be referenced implicitly 6824279528Sbaptwith the 6825279528Sbapt.Li gp 6826279528Sbaptregister. It is only accepted for targets that use ecoff format. The default 6827279528Sbaptvalue is 8. 6828279528Sbapt.Pp 6829279528Sbapt.It -EB 6830279528Sbapt.It -EL 6831279528SbaptAny mips configuration of 6832279528Sbapt.Li as 6833279528Sbaptcan select big-endian or little-endian output at run time (unlike the other 6834279528SbaptGNU development tools, which must be configured for one or the other). Use 6835279528Sbapt.Li -EB 6836279528Sbaptto select big-endian output, and 6837279528Sbapt.Li -EL 6838279528Sbaptfor little-endian. 6839279528Sbapt.Pp 6840279528Sbapt.It -KPIC 6841279528SbaptGenerate SVR4-style PIC. This option tells the assembler to generate SVR4-style 6842279528Sbaptposition-independent macro expansions. It also tells the assembler to mark 6843279528Sbaptthe output file as PIC. 6844279528Sbapt.Pp 6845279528Sbapt.It -mvxworks-pic 6846279528SbaptGenerate VxWorks PIC. This option tells the assembler to generate VxWorks-style 6847279528Sbaptposition-independent macro expansions. 6848279528Sbapt.Pp 6849279528Sbapt.It -mips1 6850279528Sbapt.It -mips2 6851279528Sbapt.It -mips3 6852279528Sbapt.It -mips4 6853279528Sbapt.It -mips5 6854279528Sbapt.It -mips32 6855279528Sbapt.It -mips32r2 6856279528Sbapt.It -mips64 6857279528Sbapt.It -mips64r2 6858279528SbaptGenerate code for a particular MIPS Instruction Set Architecture level. 6859279528Sbapt.Li -mips1 6860279528Sbaptcorresponds to the r2000 and r3000 processors, 6861279528Sbapt.Li -mips2 6862279528Sbaptto the r6000 processor, 6863279528Sbapt.Li -mips3 6864279528Sbaptto the r4000 processor, and 6865279528Sbapt.Li -mips4 6866279528Sbaptto the r8000 and r10000 processors. 6867279528Sbapt.Li -mips5 , 6868279528Sbapt.Li -mips32 , 6869279528Sbapt.Li -mips32r2 , 6870279528Sbapt.Li -mips64 , 6871279528Sbaptand 6872279528Sbapt.Li -mips64r2 6873279528Sbaptcorrespond to generic MIPS V, MIPS32, MIPS32 Release 2, MIPS64, and MIPS64 6874279528SbaptRelease 2 ISA processors, respectively. You can also switch instruction sets 6875279528Sbaptduring the assembly; see MIPS ISA, Directives to override the ISA level. 6876279528Sbapt.Pp 6877279528Sbapt.It -mgp32 6878279528Sbapt.It -mfp32 6879279528SbaptSome macros have different expansions for 32-bit and 64-bit registers. The 6880279528Sbaptregister sizes are normally inferred from the ISA and ABI, but these flags 6881279528Sbaptforce a certain group of registers to be treated as 32 bits wide at all times. 6882279528Sbapt.Li -mgp32 6883279528Sbaptcontrols the size of general-purpose registers and 6884279528Sbapt.Li -mfp32 6885279528Sbaptcontrols the size of floating-point registers. 6886279528Sbapt.Pp 6887279528SbaptThe 6888279528Sbapt.Li .set gp=32 6889279528Sbaptand 6890279528Sbapt.Li .set fp=32 6891279528Sbaptdirectives allow the size of registers to be changed for parts of an object. 6892279528SbaptThe default value is restored by 6893279528Sbapt.Li .set gp=default 6894279528Sbaptand 6895279528Sbapt.Li .set fp=default . 6896279528Sbapt.Pp 6897279528SbaptOn some MIPS variants there is a 32-bit mode flag; when this flag is set, 6898279528Sbapt64-bit instructions generate a trap. Also, some 32-bit OSes only save the 6899279528Sbapt32-bit registers on a context switch, so it is essential never to use the 6900279528Sbapt64-bit registers. 6901279528Sbapt.Pp 6902279528Sbapt.It -mgp64 6903279528Sbapt.It -mfp64 6904279528SbaptAssume that 64-bit registers are available. This is provided in the interests 6905279528Sbaptof symmetry with 6906279528Sbapt.Li -mgp32 6907279528Sbaptand 6908279528Sbapt.Li -mfp32 . 6909279528Sbapt.Pp 6910279528SbaptThe 6911279528Sbapt.Li .set gp=64 6912279528Sbaptand 6913279528Sbapt.Li .set fp=64 6914279528Sbaptdirectives allow the size of registers to be changed for parts of an object. 6915279528SbaptThe default value is restored by 6916279528Sbapt.Li .set gp=default 6917279528Sbaptand 6918279528Sbapt.Li .set fp=default . 6919279528Sbapt.Pp 6920279528Sbapt.It -mips16 6921279528Sbapt.It -no-mips16 6922279528SbaptGenerate code for the MIPS 16 processor. This is equivalent to putting 6923279528Sbapt.Li .set mips16 6924279528Sbaptat the start of the assembly file. 6925279528Sbapt.Li -no-mips16 6926279528Sbaptturns off this option. 6927279528Sbapt.Pp 6928279528Sbapt.It -msmartmips 6929279528Sbapt.It -mno-smartmips 6930279528SbaptEnables the SmartMIPS extensions to the MIPS32 instruction set, which provides 6931279528Sbapta number of new instructions which target smartcard and cryptographic applications. 6932279528SbaptThis is equivalent to putting 6933279528Sbapt.Li .set smartmips 6934279528Sbaptat the start of the assembly file. 6935279528Sbapt.Li -mno-smartmips 6936279528Sbaptturns off this option. 6937279528Sbapt.Pp 6938279528Sbapt.It -mips3d 6939279528Sbapt.It -no-mips3d 6940279528SbaptGenerate code for the MIPS-3D Application Specific Extension. This tells the 6941279528Sbaptassembler to accept MIPS-3D instructions. 6942279528Sbapt.Li -no-mips3d 6943279528Sbaptturns off this option. 6944279528Sbapt.Pp 6945279528Sbapt.It -mdmx 6946279528Sbapt.It -no-mdmx 6947279528SbaptGenerate code for the MDMX Application Specific Extension. This tells the 6948279528Sbaptassembler to accept MDMX instructions. 6949279528Sbapt.Li -no-mdmx 6950279528Sbaptturns off this option. 6951279528Sbapt.Pp 6952279528Sbapt.It -mdsp 6953279528Sbapt.It -mno-dsp 6954279528SbaptGenerate code for the DSP Release 1 Application Specific Extension. This tells 6955279528Sbaptthe assembler to accept DSP Release 1 instructions. 6956279528Sbapt.Li -mno-dsp 6957279528Sbaptturns off this option. 6958279528Sbapt.Pp 6959279528Sbapt.It -mdspr2 6960279528Sbapt.It -mno-dspr2 6961279528SbaptGenerate code for the DSP Release 2 Application Specific Extension. This option 6962279528Sbaptimplies -mdsp. This tells the assembler to accept DSP Release 2 instructions. 6963279528Sbapt.Li -mno-dspr2 6964279528Sbaptturns off this option. 6965279528Sbapt.Pp 6966279528Sbapt.It -mmt 6967279528Sbapt.It -mno-mt 6968279528SbaptGenerate code for the MT Application Specific Extension. This tells the assembler 6969279528Sbaptto accept MT instructions. 6970279528Sbapt.Li -mno-mt 6971279528Sbaptturns off this option. 6972279528Sbapt.Pp 6973279528Sbapt.It -mfix7000 6974279528Sbapt.It -mno-fix7000 6975279528SbaptCause nops to be inserted if the read of the destination register of an mfhi 6976279528Sbaptor mflo instruction occurs in the following two instructions. 6977279528Sbapt.Pp 6978279528Sbapt.It -mfix-vr4120 6979279528Sbapt.It -no-mfix-vr4120 6980279528SbaptInsert nops to work around certain VR4120 errata. This option is intended 6981279528Sbaptto be used on GCC-generated code: it is not designed to catch all problems 6982279528Sbaptin hand-written assembler code. 6983279528Sbapt.Pp 6984279528Sbapt.It -mfix-vr4130 6985279528Sbapt.It -no-mfix-vr4130 6986279528SbaptInsert nops to work around the VR4130 6987279528Sbapt.Li mflo 6988279528Sbapt/ 6989279528Sbapt.Li mfhi 6990279528Sbapterrata. 6991279528Sbapt.Pp 6992279528Sbapt.It -m4010 6993279528Sbapt.It -no-m4010 6994279528SbaptGenerate code for the LSI r4010 chip. This tells the assembler to accept the 6995279528Sbaptr4010 specific instructions ( 6996279528Sbapt.Li addciu , 6997279528Sbapt.Li ffc , 6998279528Sbaptetc.), and to not schedule 6999279528Sbapt.Li nop 7000279528Sbaptinstructions around accesses to the 7001279528Sbapt.Li HI 7002279528Sbaptand 7003279528Sbapt.Li LO 7004279528Sbaptregisters. 7005279528Sbapt.Li -no-m4010 7006279528Sbaptturns off this option. 7007279528Sbapt.Pp 7008279528Sbapt.It -m4650 7009279528Sbapt.It -no-m4650 7010279528SbaptGenerate code for the MIPS r4650 chip. This tells the assembler to accept 7011279528Sbaptthe 7012279528Sbapt.Li mad 7013279528Sbaptand 7014279528Sbapt.Li madu 7015279528Sbaptinstruction, and to not schedule 7016279528Sbapt.Li nop 7017279528Sbaptinstructions around accesses to the 7018279528Sbapt.Li HI 7019279528Sbaptand 7020279528Sbapt.Li LO 7021279528Sbaptregisters. 7022279528Sbapt.Li -no-m4650 7023279528Sbaptturns off this option. 7024279528Sbapt.Pp 7025279528Sbapt.It -m3900 7026279528Sbapt.It -no-m3900 7027279528Sbapt.It -m4100 7028279528Sbapt.It -no-m4100 7029279528SbaptFor each option 7030279528Sbapt.Li -m Va nnnn , 7031279528Sbaptgenerate code for the MIPS r 7032279528Sbapt.Va nnnn 7033279528Sbaptchip. This tells the assembler to accept instructions specific to that chip, 7034279528Sbaptand to schedule for that chip's hazards. 7035279528Sbapt.Pp 7036279528Sbapt.It -march= Va cpu 7037279528SbaptGenerate code for a particular MIPS cpu. It is exactly equivalent to 7038279528Sbapt.Li -m Va cpu , 7039279528Sbaptexcept that there are more value of 7040279528Sbapt.Va cpu 7041279528Sbaptunderstood. Valid 7042279528Sbapt.Va cpu 7043279528Sbaptvalue are: 7044279528Sbapt.Pp 7045279528Sbapt.Qo 7046279528Sbapt2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, vr4181, 4300, 4400, 7047279528Sbapt4600, 4650, 5000, rm5200, rm5230, rm5231, rm5261, rm5721, vr5400, vr5500, 7048279528Sbapt6000, rm7000, 8000, rm9000, 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, 7049279528Sbapt4kep, 4ksd, m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, 7050279528Sbapt34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a 7051279528Sbapt.Qc 7052279528Sbapt.Pp 7053279528Sbapt.It -mtune= Va cpu 7054279528SbaptSchedule and tune for a particular MIPS cpu. Valid 7055279528Sbapt.Va cpu 7056279528Sbaptvalues are identical to 7057279528Sbapt.Li -march= Va cpu . 7058279528Sbapt.Pp 7059279528Sbapt.It -mabi= Va abi 7060279528SbaptRecord which ABI the source code uses. The recognized arguments are: 7061279528Sbapt.Li 32 , 7062279528Sbapt.Li n32 , 7063279528Sbapt.Li o64 , 7064279528Sbapt.Li 64 7065279528Sbaptand 7066279528Sbapt.Li eabi . 7067279528Sbapt.Pp 7068279528Sbapt.It -msym32 7069279528Sbapt.It -mno-sym32 7070279528SbaptEquivalent to adding 7071279528Sbapt.Li .set sym32 7072279528Sbaptor 7073279528Sbapt.Li .set nosym32 7074279528Sbaptto the beginning of the assembler input.See Section 7075279528Sbapt.Dq MIPS symbol sizes . 7076279528Sbapt.Pp 7077279528Sbapt.It -nocpp 7078279528SbaptThis option is ignored. It is accepted for command-line compatibility with 7079279528Sbaptother assemblers, which use it to turn off C style preprocessing. With GNU 7080279528Sbapt.Li as , 7081279528Sbaptthere is no need for 7082279528Sbapt.Li -nocpp , 7083279528Sbaptbecause the GNU assembler itself never runs the C preprocessor. 7084279528Sbapt.Pp 7085279528Sbapt.It --construct-floats 7086279528Sbapt.It --no-construct-floats 7087279528SbaptThe 7088279528Sbapt.Li --no-construct-floats 7089279528Sbaptoption disables the construction of double width floating point constants 7090279528Sbaptby loading the two halves of the value into the two single width floating 7091279528Sbaptpoint registers that make up the double width register. This feature is useful 7092279528Sbaptif the processor support the FR bit in its status register, and this bit is 7093279528Sbaptknown (by the programmer) to be set. This bit prevents the aliasing of the 7094279528Sbaptdouble width register by the single width registers. 7095279528Sbapt.Pp 7096279528SbaptBy default 7097279528Sbapt.Li --construct-floats 7098279528Sbaptis selected, allowing construction of these floating point constants. 7099279528Sbapt.Pp 7100279528Sbapt.It --trap 7101279528Sbapt.It --no-break 7102279528Sbapt.Li as 7103279528Sbaptautomatically macro expands certain division and multiplication instructions 7104279528Sbaptto check for overflow and division by zero. This option causes 7105279528Sbapt.Li as 7106279528Sbaptto generate code to take a trap exception rather than a break exception when 7107279528Sbaptan error is detected. The trap instructions are only supported at Instruction 7108279528SbaptSet Architecture level 2 and higher. 7109279528Sbapt.Pp 7110279528Sbapt.It --break 7111279528Sbapt.It --no-trap 7112279528SbaptGenerate code to take a break exception rather than a trap exception when 7113279528Sbaptan error is detected. This is the default. 7114279528Sbapt.Pp 7115279528Sbapt.It -mpdr 7116279528Sbapt.It -mno-pdr 7117279528SbaptControl generation of 7118279528Sbapt.Li .pdr 7119279528Sbaptsections. Off by default on IRIX, on elsewhere. 7120279528Sbapt.Pp 7121279528Sbapt.It -mshared 7122279528Sbapt.It -mno-shared 7123279528SbaptWhen generating code using the Unix calling conventions (selected by 7124279528Sbapt.Li -KPIC 7125279528Sbaptor 7126279528Sbapt.Li -mcall_shared ) , 7127279528Sbaptgas will normally generate code which can go into a shared library. The 7128279528Sbapt.Li -mno-shared 7129279528Sbaptoption tells gas to generate code which uses the calling convention, but can 7130279528Sbaptnot go into a shared library. The resulting code is slightly more efficient. 7131279528SbaptThis option only affects the handling of the 7132279528Sbapt.Li .cpload 7133279528Sbaptand 7134279528Sbapt.Li .cpsetup 7135279528Sbaptpseudo-ops. 7136279528Sbapt.El 7137279528Sbapt.Pp 7138279528Sbapt.Ss MIPS ECOFF object code 7139279528SbaptAssembling for a mips ecoff target supports some additional sections besides 7140279528Sbaptthe usual 7141279528Sbapt.Li .text , 7142279528Sbapt.Li .data 7143279528Sbaptand 7144279528Sbapt.Li .bss . 7145279528SbaptThe additional sections are 7146279528Sbapt.Li .rdata , 7147279528Sbaptused for read-only data, 7148279528Sbapt.Li .sdata , 7149279528Sbaptused for small data, and 7150279528Sbapt.Li .sbss , 7151279528Sbaptused for small common objects. 7152279528Sbapt.Pp 7153279528SbaptWhen assembling for ecoff, the assembler uses the 7154279528Sbapt.Li $gp 7155279528Sbapt( 7156279528Sbapt.Li $28 ) 7157279528Sbaptregister to form the address of a \(lqsmall object\(rq. Any object in the 7158279528Sbapt.Li .sdata 7159279528Sbaptor 7160279528Sbapt.Li .sbss 7161279528Sbaptsections is considered \(lqsmall\(rq in this sense. For external objects, or for objects 7162279528Sbaptin the 7163279528Sbapt.Li .bss 7164279528Sbaptsection, you can use the 7165279528Sbapt.Li gcc 7166279528Sbapt.Li -G 7167279528Sbaptoption to control the size of objects addressed via 7168279528Sbapt.Li $gp ; 7169279528Sbaptthe default value is 8, meaning that a reference to any object eight bytes 7170279528Sbaptor smaller uses 7171279528Sbapt.Li $gp . 7172279528SbaptPassing 7173279528Sbapt.Li -G 0 7174279528Sbaptto 7175279528Sbapt.Li as 7176279528Sbaptprevents it from using the 7177279528Sbapt.Li $gp 7178279528Sbaptregister on the basis of object size (but the assembler uses 7179279528Sbapt.Li $gp 7180279528Sbaptfor objects in 7181279528Sbapt.Li .sdata 7182279528Sbaptor 7183279528Sbapt.Li sbss 7184279528Sbaptin any case). The size of an object in the 7185279528Sbapt.Li .bss 7186279528Sbaptsection is set by the 7187279528Sbapt.Li .comm 7188279528Sbaptor 7189279528Sbapt.Li .lcomm 7190279528Sbaptdirective that defines it. The size of an external object may be set with 7191279528Sbaptthe 7192279528Sbapt.Li .extern 7193279528Sbaptdirective. For example, 7194279528Sbapt.Li .extern sym,4 7195279528Sbaptdeclares that the object at 7196279528Sbapt.Li sym 7197279528Sbaptis 4 bytes in length, whie leaving 7198279528Sbapt.Li sym 7199279528Sbaptotherwise undefined. 7200279528Sbapt.Pp 7201279528SbaptUsing small ecoff objects requires linker support, and assumes that the 7202279528Sbapt.Li $gp 7203279528Sbaptregister is correctly initialized (normally done automatically by the startup 7204279528Sbaptcode). mips ecoff assembly code must not modify the 7205279528Sbapt.Li $gp 7206279528Sbaptregister. 7207279528Sbapt.Pp 7208279528Sbapt.Ss Directives for debugging information 7209279528Sbaptmips ecoff 7210279528Sbapt.Li as 7211279528Sbaptsupports several directives used for generating debugging information which 7212279528Sbaptare not support by traditional mips assemblers. These are 7213279528Sbapt.Li .def , 7214279528Sbapt.Li .endef , 7215279528Sbapt.Li .dim , 7216279528Sbapt.Li .file , 7217279528Sbapt.Li .scl , 7218279528Sbapt.Li .size , 7219279528Sbapt.Li .tag , 7220279528Sbapt.Li .type , 7221279528Sbapt.Li .val , 7222279528Sbapt.Li .stabd , 7223279528Sbapt.Li .stabn , 7224279528Sbaptand 7225279528Sbapt.Li .stabs . 7226279528SbaptThe debugging information generated by the three 7227279528Sbapt.Li .stab 7228279528Sbaptdirectives can only be read by gdb, not by traditional mips debuggers (this 7229279528Sbaptenhancement is required to fully support C++ debugging). These directives 7230279528Sbaptare primarily used by compilers, not assembly language programmers! 7231279528Sbapt.Pp 7232279528Sbapt.Ss Directives to override the size of symbols 7233279528SbaptThe n64 ABI allows symbols to have any 64-bit value. Although this provides 7234279528Sbapta great deal of flexibility, it means that some macros have much longer expansions 7235279528Sbaptthan their 32-bit counterparts. For example, the non-PIC expansion of 7236279528Sbapt.Li dla $4,sym 7237279528Sbaptis usually: 7238279528Sbapt.Pp 7239279528Sbapt.Bd -literal -offset indent 7240279528Sbaptlui $4,%highest(sym) 7241279528Sbaptlui $1,%hi(sym) 7242279528Sbaptdaddiu $4,$4,%higher(sym) 7243279528Sbaptdaddiu $1,$1,%lo(sym) 7244279528Sbaptdsll32 $4,$4,0 7245279528Sbaptdaddu $4,$4,$1 7246279528Sbapt.Ed 7247279528Sbapt.Pp 7248279528Sbaptwhereas the 32-bit expansion is simply: 7249279528Sbapt.Pp 7250279528Sbapt.Bd -literal -offset indent 7251279528Sbaptlui $4,%hi(sym) 7252279528Sbaptdaddiu $4,$4,%lo(sym) 7253279528Sbapt.Ed 7254279528Sbapt.Pp 7255279528Sbaptn64 code is sometimes constructed in such a way that all symbolic constants 7256279528Sbaptare known to have 32-bit values, and in such cases, it's preferable to use 7257279528Sbaptthe 32-bit expansion instead of the 64-bit expansion. 7258279528Sbapt.Pp 7259279528SbaptYou can use the 7260279528Sbapt.Li .set sym32 7261279528Sbaptdirective to tell the assembler that, from this point on, all expressions 7262279528Sbaptof the form 7263279528Sbapt.Li Va symbol 7264279528Sbaptor 7265279528Sbapt.Li Va symbol + Va offset 7266279528Sbapthave 32-bit values. For example: 7267279528Sbapt.Pp 7268279528Sbapt.Bd -literal -offset indent 7269279528Sbapt\&.set sym32 7270279528Sbaptdla $4,sym 7271279528Sbaptlw $4,sym+16 7272279528Sbaptsw $4,sym+0x8000($4) 7273279528Sbapt.Ed 7274279528Sbapt.Pp 7275279528Sbaptwill cause the assembler to treat 7276279528Sbapt.Li sym , 7277279528Sbapt.Li sym+16 7278279528Sbaptand 7279279528Sbapt.Li sym+0x8000 7280279528Sbaptas 32-bit values. The handling of non-symbolic addresses is not affected. 7281279528Sbapt.Pp 7282279528SbaptThe directive 7283279528Sbapt.Li .set nosym32 7284279528Sbaptends a 7285279528Sbapt.Li .set sym32 7286279528Sbaptblock and reverts to the normal behavior. It is also possible to change the 7287279528Sbaptsymbol size using the command-line options 7288279528Sbapt.Op -msym32 7289279528Sbaptand 7290279528Sbapt.Op -mno-sym32 . 7291279528Sbapt.Pp 7292279528SbaptThese options and directives are always accepted, but at present, they have 7293279528Sbaptno effect for anything other than n64. 7294279528Sbapt.Pp 7295279528Sbapt.Ss Directives to override the ISA level 7296279528SbaptGNU 7297279528Sbapt.Li as 7298279528Sbaptsupports an additional directive to change the mips Instruction Set Architecture 7299279528Sbaptlevel on the fly: 7300279528Sbapt.Li .set mips Va n . 7301279528Sbapt.Va n 7302279528Sbaptshould be a number from 0 to 5, or 32, 32r2, 64 or 64r2. The values other 7303279528Sbaptthan 0 make the assembler accept instructions for the corresponding isa level, 7304279528Sbaptfrom that point on in the assembly. 7305279528Sbapt.Li .set mips Va n 7306279528Sbaptaffects not only which instructions are permitted, but also how certain macros 7307279528Sbaptare expanded. 7308279528Sbapt.Li .set mips0 7309279528Sbaptrestores the isa level to its original level: either the level you selected 7310279528Sbaptwith command line options, or the default for your configuration. You can 7311279528Sbaptuse this feature to permit specific mips3 instructions while assembling in 7312279528Sbapt32 bit mode. Use this directive with care! 7313279528Sbapt.Pp 7314279528SbaptThe 7315279528Sbapt.Li .set arch= Va cpu 7316279528Sbaptdirective provides even finer control. It changes the effective CPU target 7317279528Sbaptand allows the assembler to use instructions specific to a particular CPU. 7318279528SbaptAll CPUs supported by the 7319279528Sbapt.Li -march 7320279528Sbaptcommand line option are also selectable by this directive. The original value 7321279528Sbaptis restored by 7322279528Sbapt.Li .set arch=default . 7323279528Sbapt.Pp 7324279528SbaptThe directive 7325279528Sbapt.Li .set mips16 7326279528Sbaptputs the assembler into MIPS 16 mode, in which it will assemble instructions 7327279528Sbaptfor the MIPS 16 processor. Use 7328279528Sbapt.Li .set nomips16 7329279528Sbaptto return to normal 32 bit mode. 7330279528Sbapt.Pp 7331279528SbaptTraditional mips assemblers do not support this directive. 7332279528Sbapt.Pp 7333279528Sbapt.Ss Directives for extending MIPS 16 bit instructions 7334279528SbaptBy default, MIPS 16 instructions are automatically extended to 32 bits when 7335279528Sbaptnecessary. The directive 7336279528Sbapt.Li .set noautoextend 7337279528Sbaptwill turn this off. When 7338279528Sbapt.Li .set noautoextend 7339279528Sbaptis in effect, any 32 bit instruction must be explicitly extended with the 7340279528Sbapt.Li .e 7341279528Sbaptmodifier (e.g., 7342279528Sbapt.Li li.e $4,1000 ) . 7343279528SbaptThe directive 7344279528Sbapt.Li .set autoextend 7345279528Sbaptmay be used to once again automatically extend instructions when necessary. 7346279528Sbapt.Pp 7347279528SbaptThis directive is only meaningful when in MIPS 16 mode. Traditional mips assemblers 7348279528Sbaptdo not support this directive. 7349279528Sbapt.Pp 7350279528Sbapt.Ss Directive to mark data as an instruction 7351279528SbaptThe 7352279528Sbapt.Li .insn 7353279528Sbaptdirective tells 7354279528Sbapt.Li as 7355279528Sbaptthat the following data is actually instructions. This makes a difference 7356279528Sbaptin MIPS 16 mode: when loading the address of a label which precedes instructions, 7357279528Sbapt.Li as 7358279528Sbaptautomatically adds 1 to the value, so that jumping to the loaded address will 7359279528Sbaptdo the right thing. 7360279528Sbapt.Pp 7361279528Sbapt.Ss Directives to save and restore options 7362279528SbaptThe directives 7363279528Sbapt.Li .set push 7364279528Sbaptand 7365279528Sbapt.Li .set pop 7366279528Sbaptmay be used to save and restore the current settings for all the options which 7367279528Sbaptare controlled by 7368279528Sbapt.Li .set . 7369279528SbaptThe 7370279528Sbapt.Li .set push 7371279528Sbaptdirective saves the current settings on a stack. The 7372279528Sbapt.Li .set pop 7373279528Sbaptdirective pops the stack and restores the settings. 7374279528Sbapt.Pp 7375279528SbaptThese directives can be useful inside an macro which must change an option 7376279528Sbaptsuch as the ISA level or instruction reordering but does not want to change 7377279528Sbaptthe state of the code which invoked the macro. 7378279528Sbapt.Pp 7379279528SbaptTraditional mips assemblers do not support these directives. 7380279528Sbapt.Pp 7381279528Sbapt.Ss Directives to control generation of MIPS ASE instructions 7382279528SbaptThe directive 7383279528Sbapt.Li .set mips3d 7384279528Sbaptmakes the assembler accept instructions from the MIPS-3D Application Specific 7385279528SbaptExtension from that point on in the assembly. The 7386279528Sbapt.Li .set nomips3d 7387279528Sbaptdirective prevents MIPS-3D instructions from being accepted. 7388279528Sbapt.Pp 7389279528SbaptThe directive 7390279528Sbapt.Li .set smartmips 7391279528Sbaptmakes the assembler accept instructions from the SmartMIPS Application Specific 7392279528SbaptExtension to the MIPS32 isa from that point on in the assembly. The 7393279528Sbapt.Li .set nosmartmips 7394279528Sbaptdirective prevents SmartMIPS instructions from being accepted. 7395279528Sbapt.Pp 7396279528SbaptThe directive 7397279528Sbapt.Li .set mdmx 7398279528Sbaptmakes the assembler accept instructions from the MDMX Application Specific 7399279528SbaptExtension from that point on in the assembly. The 7400279528Sbapt.Li .set nomdmx 7401279528Sbaptdirective prevents MDMX instructions from being accepted. 7402279528Sbapt.Pp 7403279528SbaptThe directive 7404279528Sbapt.Li .set dsp 7405279528Sbaptmakes the assembler accept instructions from the DSP Release 1 Application 7406279528SbaptSpecific Extension from that point on in the assembly. The 7407279528Sbapt.Li .set nodsp 7408279528Sbaptdirective prevents DSP Release 1 instructions from being accepted. 7409279528Sbapt.Pp 7410279528SbaptThe directive 7411279528Sbapt.Li .set dspr2 7412279528Sbaptmakes the assembler accept instructions from the DSP Release 2 Application 7413279528SbaptSpecific Extension from that point on in the assembly. This dirctive implies 7414279528Sbapt.Li .set dsp . 7415279528SbaptThe 7416279528Sbapt.Li .set nodspr2 7417279528Sbaptdirective prevents DSP Release 2 instructions from being accepted. 7418279528Sbapt.Pp 7419279528SbaptThe directive 7420279528Sbapt.Li .set mt 7421279528Sbaptmakes the assembler accept instructions from the MT Application Specific Extension 7422279528Sbaptfrom that point on in the assembly. The 7423279528Sbapt.Li .set nomt 7424279528Sbaptdirective prevents MT instructions from being accepted. 7425279528Sbapt.Pp 7426279528SbaptTraditional mips assemblers do not support these directives. 7427279528Sbapt.Pp 7428279528Sbapt.Sh PowerPC Dependent Features 7429279528Sbapt.Ss Options 7430279528SbaptThe PowerPC chip family includes several successive levels, using the same 7431279528Sbaptcore instruction set, but including a few additional instructions at each 7432279528Sbaptlevel. There are exceptions to this however. For details on what instructions 7433279528Sbapteach variant supports, please see the chip's architecture reference manual. 7434279528Sbapt.Pp 7435279528SbaptThe following table lists all available PowerPC options. 7436279528Sbapt.Pp 7437279528Sbapt.Bl -tag -width Ds 7438279528Sbapt.It -mpwrx | -mpwr2 7439279528SbaptGenerate code for POWER/2 (RIOS2). 7440279528Sbapt.Pp 7441279528Sbapt.It -mpwr 7442279528SbaptGenerate code for POWER (RIOS1) 7443279528Sbapt.Pp 7444279528Sbapt.It -m601 7445279528SbaptGenerate code for PowerPC 601. 7446279528Sbapt.Pp 7447279528Sbapt.It -mppc, -mppc32, -m603, -m604 7448279528SbaptGenerate code for PowerPC 603/604. 7449279528Sbapt.Pp 7450279528Sbapt.It -m403, -m405 7451279528SbaptGenerate code for PowerPC 403/405. 7452279528Sbapt.Pp 7453279528Sbapt.It -m440 7454279528SbaptGenerate code for PowerPC 440. BookE and some 405 instructions. 7455279528Sbapt.Pp 7456279528Sbapt.It -m7400, -m7410, -m7450, -m7455 7457279528SbaptGenerate code for PowerPC 7400/7410/7450/7455. 7458279528Sbapt.Pp 7459279528Sbapt.It -mppc64, -m620 7460279528SbaptGenerate code for PowerPC 620/625/630. 7461279528Sbapt.Pp 7462279528Sbapt.It -me500, -me500x2 7463279528SbaptGenerate code for Motorola e500 core complex. 7464279528Sbapt.Pp 7465279528Sbapt.It -mspe 7466279528SbaptGenerate code for Motorola SPE instructions. 7467279528Sbapt.Pp 7468279528Sbapt.It -mppc64bridge 7469279528SbaptGenerate code for PowerPC 64, including bridge insns. 7470279528Sbapt.Pp 7471279528Sbapt.It -mbooke64 7472279528SbaptGenerate code for 64-bit BookE. 7473279528Sbapt.Pp 7474279528Sbapt.It -mbooke, mbooke32 7475279528SbaptGenerate code for 32-bit BookE. 7476279528Sbapt.Pp 7477279528Sbapt.It -me300 7478279528SbaptGenerate code for PowerPC e300 family. 7479279528Sbapt.Pp 7480279528Sbapt.It -maltivec 7481279528SbaptGenerate code for processors with AltiVec instructions. 7482279528Sbapt.Pp 7483279528Sbapt.It -mpower4 7484279528SbaptGenerate code for Power4 architecture. 7485279528Sbapt.Pp 7486279528Sbapt.It -mpower5 7487279528SbaptGenerate code for Power5 architecture. 7488279528Sbapt.Pp 7489279528Sbapt.It -mpower6 7490279528SbaptGenerate code for Power6 architecture. 7491279528Sbapt.Pp 7492279528Sbapt.It -mcell 7493279528SbaptGenerate code for Cell Broadband Engine architecture. 7494279528Sbapt.Pp 7495279528Sbapt.It -mcom 7496279528SbaptGenerate code Power/PowerPC common instructions. 7497279528Sbapt.Pp 7498279528Sbapt.It -many 7499279528SbaptGenerate code for any architecture (PWR/PWRX/PPC). 7500279528Sbapt.Pp 7501279528Sbapt.It -mregnames 7502279528SbaptAllow symbolic names for registers. 7503279528Sbapt.Pp 7504279528Sbapt.It -mno-regnames 7505279528SbaptDo not allow symbolic names for registers. 7506279528Sbapt.Pp 7507279528Sbapt.It -mrelocatable 7508279528SbaptSupport for GCC's -mrelocatable option. 7509279528Sbapt.Pp 7510279528Sbapt.It -mrelocatable-lib 7511279528SbaptSupport for GCC's -mrelocatable-lib option. 7512279528Sbapt.Pp 7513279528Sbapt.It -memb 7514279528SbaptSet PPC_EMB bit in ELF flags. 7515279528Sbapt.Pp 7516279528Sbapt.It -mlittle, -mlittle-endian 7517279528SbaptGenerate code for a little endian machine. 7518279528Sbapt.Pp 7519279528Sbapt.It -mbig, -mbig-endian 7520279528SbaptGenerate code for a big endian machine. 7521279528Sbapt.Pp 7522279528Sbapt.It -msolaris 7523279528SbaptGenerate code for Solaris. 7524279528Sbapt.Pp 7525279528Sbapt.It -mno-solaris 7526279528SbaptDo not generate code for Solaris. 7527279528Sbapt.El 7528279528Sbapt.Pp 7529279528Sbapt.Ss PowerPC Assembler Directives 7530279528SbaptA number of assembler directives are available for PowerPC. The following 7531279528Sbapttable is far from complete. 7532279528Sbapt.Pp 7533279528Sbapt.Bl -tag -width Ds 7534279528Sbapt.It .machine "string" 7535279528SbaptThis directive allows you to change the machine for which code is generated. 7536279528Sbapt.Li "string" 7537279528Sbaptmay be any of the -m cpu selection options (without the -m) enclosed in double 7538279528Sbaptquotes, 7539279528Sbapt.Li "push" , 7540279528Sbaptor 7541279528Sbapt.Li "pop" . 7542279528Sbapt.Li .machine "push" 7543279528Sbaptsaves the currently selected cpu, which may be restored with 7544279528Sbapt.Li .machine "pop" . 7545279528Sbapt.El 7546279528Sbapt.Pp 7547279528Sbapt.Sh SPARC Dependent Features 7548279528Sbapt.Ss Options 7549279528SbaptThe SPARC chip family includes several successive levels, using the same core 7550279528Sbaptinstruction set, but including a few additional instructions at each level. 7551279528SbaptThere are exceptions to this however. For details on what instructions each 7552279528Sbaptvariant supports, please see the chip's architecture reference manual. 7553279528Sbapt.Pp 7554279528SbaptBy default, 7555279528Sbapt.Li as 7556279528Sbaptassumes the core instruction set (SPARC v6), but \(lqbumps\(rq the architecture level 7557279528Sbaptas needed: it switches to successively higher architectures as it encounters 7558279528Sbaptinstructions that only exist in the higher levels. 7559279528Sbapt.Pp 7560279528SbaptIf not configured for SPARC v9 ( 7561279528Sbapt.Li sparc64-*-* ) 7562279528SbaptGAS will not bump passed sparclite by default, an option must be passed to 7563279528Sbaptenable the v9 instructions. 7564279528Sbapt.Pp 7565279528SbaptGAS treats sparclite as being compatible with v8, unless an architecture is 7566279528Sbaptexplicitly requested. SPARC v9 is always incompatible with sparclite. 7567279528Sbapt.Pp 7568279528Sbapt.Bl -tag -width Ds 7569279528Sbapt.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite 7570279528Sbapt.It -Av8plus | -Av8plusa | -Av9 | -Av9a 7571279528SbaptUse one of the 7572279528Sbapt.Li -A 7573279528Sbaptoptions to select one of the SPARC architectures explicitly. If you select 7574279528Sbaptan architecture explicitly, 7575279528Sbapt.Li as 7576279528Sbaptreports a fatal error if it encounters an instruction or feature requiring 7577279528Sbaptan incompatible or higher level. 7578279528Sbapt.Pp 7579279528Sbapt.Li -Av8plus 7580279528Sbaptand 7581279528Sbapt.Li -Av8plusa 7582279528Sbaptselect a 32 bit environment. 7583279528Sbapt.Pp 7584279528Sbapt.Li -Av9 7585279528Sbaptand 7586279528Sbapt.Li -Av9a 7587279528Sbaptselect a 64 bit environment and are not available unless GAS is explicitly 7588279528Sbaptconfigured with 64 bit environment support. 7589279528Sbapt.Pp 7590279528Sbapt.Li -Av8plusa 7591279528Sbaptand 7592279528Sbapt.Li -Av9a 7593279528Sbaptenable the SPARC V9 instruction set with UltraSPARC extensions. 7594279528Sbapt.Pp 7595279528Sbapt.It -xarch=v8plus | -xarch=v8plusa 7596279528SbaptFor compatibility with the Solaris v9 assembler. These options are equivalent 7597279528Sbaptto -Av8plus and -Av8plusa, respectively. 7598279528Sbapt.Pp 7599279528Sbapt.It -bump 7600279528SbaptWarn whenever it is necessary to switch to another level. If an architecture 7601279528Sbaptlevel is explicitly requested, GAS will not issue warnings until that level 7602279528Sbaptis reached, and will then bump the level as required (except between incompatible 7603279528Sbaptlevels). 7604279528Sbapt.Pp 7605279528Sbapt.It -32 | -64 7606279528SbaptSelect the word size, either 32 bits or 64 bits. These options are only available 7607279528Sbaptwith the ELF object file format, and require that the necessary BFD support 7608279528Sbapthas been included. 7609279528Sbapt.El 7610279528Sbapt.Pp 7611279528Sbapt.Ss Enforcing aligned data 7612279528SbaptSPARC GAS normally permits data to be misaligned. For example, it permits 7613279528Sbaptthe 7614279528Sbapt.Li .long 7615279528Sbaptpseudo-op to be used on a byte boundary. However, the native SunOS and Solaris 7616279528Sbaptassemblers issue an error when they see misaligned data. 7617279528Sbapt.Pp 7618279528SbaptYou can use the 7619279528Sbapt.Li --enforce-aligned-data 7620279528Sbaptoption to make SPARC GAS also issue an error about misaligned data, just as 7621279528Sbaptthe SunOS and Solaris assemblers do. 7622279528Sbapt.Pp 7623279528SbaptThe 7624279528Sbapt.Li --enforce-aligned-data 7625279528Sbaptoption is not the default because gcc issues misaligned data pseudo-ops when 7626279528Sbaptit initializes certain packed data structures (structures defined using the 7627279528Sbapt.Li packed 7628279528Sbaptattribute). You may have to assemble with GAS in order to initialize packed 7629279528Sbaptdata structures in your own code. 7630279528Sbapt.Pp 7631279528Sbapt.Ss Floating Point 7632279528SbaptThe Sparc uses ieee floating-point numbers. 7633279528Sbapt.Pp 7634279528Sbapt.Ss Sparc Machine Directives 7635279528SbaptThe Sparc version of 7636279528Sbapt.Li as 7637279528Sbaptsupports the following additional machine directives: 7638279528Sbapt.Pp 7639279528Sbapt.Bl -tag -width Ds 7640279528Sbapt.It .align 7641279528SbaptThis must be followed by the desired alignment in bytes. 7642279528Sbapt.Pp 7643279528Sbapt.It .common 7644279528SbaptThis must be followed by a symbol name, a positive number, and 7645279528Sbapt.Li "bss" . 7646279528SbaptThis behaves somewhat like 7647279528Sbapt.Li .comm , 7648279528Sbaptbut the syntax is different. 7649279528Sbapt.Pp 7650279528Sbapt.It .half 7651279528SbaptThis is functionally identical to 7652279528Sbapt.Li .short . 7653279528Sbapt.Pp 7654279528Sbapt.It .nword 7655279528SbaptOn the Sparc, the 7656279528Sbapt.Li .nword 7657279528Sbaptdirective produces native word sized value, ie. if assembling with -32 it 7658279528Sbaptis equivalent to 7659279528Sbapt.Li .word , 7660279528Sbaptif assembling with -64 it is equivalent to 7661279528Sbapt.Li .xword . 7662279528Sbapt.Pp 7663279528Sbapt.It .proc 7664279528SbaptThis directive is ignored. Any text following it on the same line is also 7665279528Sbaptignored. 7666279528Sbapt.Pp 7667279528Sbapt.It .register 7668279528SbaptThis directive declares use of a global application or system register. It 7669279528Sbaptmust be followed by a register name %g2, %g3, %g6 or %g7, comma and the symbol 7670279528Sbaptname for that register. If symbol name is 7671279528Sbapt.Li #scratch , 7672279528Sbaptit is a scratch register, if it is 7673279528Sbapt.Li #ignore , 7674279528Sbaptit just suppresses any errors about using undeclared global register, but 7675279528Sbaptdoes not emit any information about it into the object file. This can be useful 7676279528Sbapte.g. if you save the register before use and restore it after. 7677279528Sbapt.Pp 7678279528Sbapt.It .reserve 7679279528SbaptThis must be followed by a symbol name, a positive number, and 7680279528Sbapt.Li "bss" . 7681279528SbaptThis behaves somewhat like 7682279528Sbapt.Li .lcomm , 7683279528Sbaptbut the syntax is different. 7684279528Sbapt.Pp 7685279528Sbapt.It .seg 7686279528SbaptThis must be followed by 7687279528Sbapt.Li "text" , 7688279528Sbapt.Li "data" , 7689279528Sbaptor 7690279528Sbapt.Li "data1" . 7691279528SbaptIt behaves like 7692279528Sbapt.Li .text , 7693279528Sbapt.Li .data , 7694279528Sbaptor 7695279528Sbapt.Li .data 1 . 7696279528Sbapt.Pp 7697279528Sbapt.It .skip 7698279528SbaptThis is functionally identical to the 7699279528Sbapt.Li .space 7700279528Sbaptdirective. 7701279528Sbapt.Pp 7702279528Sbapt.It .word 7703279528SbaptOn the Sparc, the 7704279528Sbapt.Li .word 7705279528Sbaptdirective produces 32 bit values, instead of the 16 bit values it produces 7706279528Sbapton many other machines. 7707279528Sbapt.Pp 7708279528Sbapt.It .xword 7709279528SbaptOn the Sparc V9 processor, the 7710279528Sbapt.Li .xword 7711279528Sbaptdirective produces 64 bit values. 7712279528Sbapt.El 7713279528Sbapt.Pp 7714279528Sbapt.Sh Reporting Bugs 7715279528SbaptYour bug reports play an essential role in making 7716279528Sbapt.Xr as 7717279528Sbaptreliable. 7718279528Sbapt.Pp 7719279528SbaptReporting a bug may help you by bringing a solution to your problem, or it 7720279528Sbaptmay not. But in any case the principal function of a bug report is to help 7721279528Sbaptthe entire community by making the next version of 7722279528Sbapt.Xr as 7723279528Sbaptwork better. Bug reports are your contribution to the maintenance of 7724279528Sbapt.Xr as . 7725279528Sbapt.Pp 7726279528SbaptIn order for a bug report to serve its purpose, you must include the information 7727279528Sbaptthat enables us to fix the bug. 7728279528Sbapt.Pp 7729279528Sbapt.Ss Have You Found a Bug? 7730279528SbaptIf you are not sure whether you have found a bug, here are some guidelines: 7731279528Sbapt.Pp 7732279528Sbapt.Bl -bullet 7733279528Sbapt.It 7734279528SbaptIf the assembler gets a fatal signal, for any input whatever, that is a 7735279528Sbapt.Xr as 7736279528Sbaptbug. Reliable assemblers never crash. 7737279528Sbapt.Pp 7738279528Sbapt.It 7739279528SbaptIf 7740279528Sbapt.Xr as 7741279528Sbaptproduces an error message for valid input, that is a bug. 7742279528Sbapt.Pp 7743279528Sbapt.It 7744279528SbaptIf 7745279528Sbapt.Xr as 7746279528Sbaptdoes not produce an error message for invalid input, that is a bug. However, 7747279528Sbaptyou should note that your idea of \(lqinvalid input\(rq might be our idea of \(lqan extension\(rq 7748279528Sbaptor \(lqsupport for traditional practice\(rq. 7749279528Sbapt.Pp 7750279528Sbapt.It 7751279528SbaptIf you are an experienced user of assemblers, your suggestions for improvement 7752279528Sbaptof 7753279528Sbapt.Xr as 7754279528Sbaptare welcome in any case. 7755279528Sbapt.El 7756279528Sbapt.Pp 7757279528Sbapt.Ss How to Report Bugs 7758279528SbaptA number of companies and individuals offer support for GNU products. If you 7759279528Sbaptobtained 7760279528Sbapt.Xr as 7761279528Sbaptfrom a support organization, we recommend you contact that organization first. 7762279528Sbapt.Pp 7763279528SbaptYou can find contact information for many support companies and individuals 7764279528Sbaptin the file 7765279528Sbapt.Pa etc/SERVICE 7766279528Sbaptin the GNU Emacs distribution. 7767279528Sbapt.Pp 7768279528SbaptThe fundamental principle of reporting bugs usefully is this: 7769279528Sbapt.Sy report all the facts . 7770279528SbaptIf you are not sure whether to state a fact or leave it out, state it! 7771279528Sbapt.Pp 7772279528SbaptOften people omit facts because they think they know what causes the problem 7773279528Sbaptand assume that some details do not matter. Thus, you might assume that the 7774279528Sbaptname of a symbol you use in an example does not matter. Well, probably it 7775279528Sbaptdoes not, but one cannot be sure. Perhaps the bug is a stray memory reference 7776279528Sbaptwhich happens to fetch from the location where that name is stored in memory; 7777279528Sbaptperhaps, if the name were different, the contents of that location would fool 7778279528Sbaptthe assembler into doing the right thing despite the bug. Play it safe and 7779279528Sbaptgive a specific, complete example. That is the easiest thing for you to do, 7780279528Sbaptand the most helpful. 7781279528Sbapt.Pp 7782279528SbaptKeep in mind that the purpose of a bug report is to enable us to fix the bug 7783279528Sbaptif it is new to us. Therefore, always write your bug reports on the assumption 7784279528Sbaptthat the bug has not been reported previously. 7785279528Sbapt.Pp 7786279528SbaptSometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq 7787279528SbaptThis cannot help us fix a bug, so it is basically useless. We respond by asking 7788279528Sbaptfor enough details to enable us to investigate. You might as well expedite 7789279528Sbaptmatters by sending them to begin with. 7790279528Sbapt.Pp 7791279528SbaptTo enable us to fix the bug, you should include all these things: 7792279528Sbapt.Pp 7793279528Sbapt.Bl -bullet 7794279528Sbapt.It 7795279528SbaptThe version of 7796279528Sbapt.Xr as . 7797279528Sbapt.Xr as 7798279528Sbaptannounces it if you start it with the 7799279528Sbapt.Li --version 7800279528Sbaptargument. 7801279528Sbapt.Pp 7802279528SbaptWithout this, we will not know whether there is any point in looking for the 7803279528Sbaptbug in the current version of 7804279528Sbapt.Xr as . 7805279528Sbapt.Pp 7806279528Sbapt.It 7807279528SbaptAny patches you may have applied to the 7808279528Sbapt.Xr as 7809279528Sbaptsource. 7810279528Sbapt.Pp 7811279528Sbapt.It 7812279528SbaptThe type of machine you are using, and the operating system name and version 7813279528Sbaptnumber. 7814279528Sbapt.Pp 7815279528Sbapt.It 7816279528SbaptWhat compiler (and its version) was used to compile 7817279528Sbapt.Xr as 7818279528Sbapt---e.g. \(lq 7819279528Sbapt.Li gcc-2.7 7820279528Sbapt\(rq\&. 7821279528Sbapt.Pp 7822279528Sbapt.It 7823279528SbaptThe command arguments you gave the assembler to assemble your example and 7824279528Sbaptobserve the bug. To guarantee you will not omit something important, list 7825279528Sbaptthem all. A copy of the Makefile (or the output from make) is sufficient. 7826279528Sbapt.Pp 7827279528SbaptIf we were to try to guess the arguments, we would probably guess wrong and 7828279528Sbaptthen we might not encounter the bug. 7829279528Sbapt.Pp 7830279528Sbapt.It 7831279528SbaptA complete input file that will reproduce the bug. If the bug is observed 7832279528Sbaptwhen the assembler is invoked via a compiler, send the assembler source, not 7833279528Sbaptthe high level language source. Most compilers will produce the assembler 7834279528Sbaptsource when run with the 7835279528Sbapt.Li -S 7836279528Sbaptoption. If you are using 7837279528Sbapt.Li gcc , 7838279528Sbaptuse the options 7839279528Sbapt.Li -v --save-temps ; 7840279528Sbaptthis will save the assembler source in a file with an extension of 7841279528Sbapt.Pa .s , 7842279528Sbaptand also show you exactly how 7843279528Sbapt.Xr as 7844279528Sbaptis being run. 7845279528Sbapt.Pp 7846279528Sbapt.It 7847279528SbaptA description of what behavior you observe that you believe is incorrect. 7848279528SbaptFor example, \(lqIt gets a fatal signal.\(rq 7849279528Sbapt.Pp 7850279528SbaptOf course, if the bug is that 7851279528Sbapt.Xr as 7852279528Sbaptgets a fatal signal, then we will certainly notice it. But if the bug is incorrect 7853279528Sbaptoutput, we might not notice unless it is glaringly wrong. You might as well 7854279528Sbaptnot give us a chance to make a mistake. 7855279528Sbapt.Pp 7856279528SbaptEven if the problem you experience is a fatal signal, you should still say 7857279528Sbaptso explicitly. Suppose something strange is going on, such as, your copy of 7858279528Sbapt.Xr as 7859279528Sbaptis out of sync, or you have encountered a bug in the C library on your system. 7860279528Sbapt(This has happened!) Your copy might crash and ours would not. If you told 7861279528Sbaptus to expect a crash, then when ours fails to crash, we would know that the 7862279528Sbaptbug was not happening for us. If you had not told us to expect a crash, then 7863279528Sbaptwe would not be able to draw any conclusion from our observations. 7864279528Sbapt.Pp 7865279528Sbapt.It 7866279528SbaptIf you wish to suggest changes to the 7867279528Sbapt.Xr as 7868279528Sbaptsource, send us context diffs, as generated by 7869279528Sbapt.Li diff 7870279528Sbaptwith the 7871279528Sbapt.Li -u , 7872279528Sbapt.Li -c , 7873279528Sbaptor 7874279528Sbapt.Li -p 7875279528Sbaptoption. Always send diffs from the old file to the new file. If you even discuss 7876279528Sbaptsomething in the 7877279528Sbapt.Xr as 7878279528Sbaptsource, refer to it by context, not by line number. 7879279528Sbapt.Pp 7880279528SbaptThe line numbers in our development sources will not match those in your sources. 7881279528SbaptYour line numbers would convey no useful information to us. 7882279528Sbapt.El 7883279528Sbapt.Pp 7884279528SbaptHere are some things that are not necessary: 7885279528Sbapt.Pp 7886279528Sbapt.Bl -bullet 7887279528Sbapt.It 7888279528SbaptA description of the envelope of the bug. 7889279528Sbapt.Pp 7890279528SbaptOften people who encounter a bug spend a lot of time investigating which changes 7891279528Sbaptto the input file will make the bug go away and which changes will not affect 7892279528Sbaptit. 7893279528Sbapt.Pp 7894279528SbaptThis is often time consuming and not very useful, because the way we will 7895279528Sbaptfind the bug is by running a single example under the debugger with breakpoints, 7896279528Sbaptnot by pure deduction from a series of examples. We recommend that you save 7897279528Sbaptyour time for something else. 7898279528Sbapt.Pp 7899279528SbaptOf course, if you can find a simpler example to report 7900279528Sbapt.Em instead 7901279528Sbaptof the original one, that is a convenience for us. Errors in the output will 7902279528Sbaptbe easier to spot, running under the debugger will take less time, and so 7903279528Sbapton. 7904279528Sbapt.Pp 7905279528SbaptHowever, simplification is not vital; if you do not want to do this, report 7906279528Sbaptthe bug anyway and send us the entire test case you used. 7907279528Sbapt.Pp 7908279528Sbapt.It 7909279528SbaptA patch for the bug. 7910279528Sbapt.Pp 7911279528SbaptA patch for the bug does help us if it is a good one. But do not omit the 7912279528Sbaptnecessary information, such as the test case, on the assumption that a patch 7913279528Sbaptis all we need. We might see problems with your patch and decide to fix the 7914279528Sbaptproblem another way, or we might not understand it at all. 7915279528Sbapt.Pp 7916279528SbaptSometimes with a program as complicated as 7917279528Sbapt.Xr as 7918279528Sbaptit is very hard to construct an example that will make the program follow 7919279528Sbapta certain path through the code. If you do not send us the example, we will 7920279528Sbaptnot be able to construct one, so we will not be able to verify that the bug 7921279528Sbaptis fixed. 7922279528Sbapt.Pp 7923279528SbaptAnd if we cannot understand what bug you are trying to fix, or why your patch 7924279528Sbaptshould be an improvement, we will not install it. A test case will help us 7925279528Sbaptto understand. 7926279528Sbapt.Pp 7927279528Sbapt.It 7928279528SbaptA guess about what the bug is or what it depends on. 7929279528Sbapt.Pp 7930279528SbaptSuch guesses are usually wrong. Even we cannot guess right about such things 7931279528Sbaptwithout first using the debugger to find the facts. 7932279528Sbapt.El 7933279528Sbapt.Pp 7934279528Sbapt.Sh Acknowledgements 7935279528SbaptIf you have contributed to GAS and your name isn't listed here, it is not 7936279528Sbaptmeant as a slight. We just don't know about it. Send mail to the maintainer, 7937279528Sbaptand we'll correct the situation. Currently the maintainer is Ken Raeburn (email 7938279528Sbaptaddress 7939279528Sbapt.Li raeburn@cyGNUs.com ) . 7940279528Sbapt.Pp 7941279528SbaptDean Elsner wrote the original GNU assembler for the VAX. 7942279528Sbapt.Pp 7943279528SbaptJay Fenlason maintained GAS for a while, adding support for GDB-specific debug 7944279528Sbaptinformation and the 68k series machines, most of the preprocessing pass, and 7945279528Sbaptextensive changes in 7946279528Sbapt.Pa messages.c , 7947279528Sbapt.Pa input-file.c , 7948279528Sbapt.Pa write.c . 7949279528Sbapt.Pp 7950279528SbaptK. Richard Pixley maintained GAS for a while, adding various enhancements 7951279528Sbaptand many bug fixes, including merging support for several processors, breaking 7952279528SbaptGAS up to handle multiple object file format back ends (including heavy rewrite, 7953279528Sbapttesting, an integration of the coff and b.out back ends), adding configuration 7954279528Sbaptincluding heavy testing and verification of cross assemblers and file splits 7955279528Sbaptand renaming, converted GAS to strictly ANSI C including full prototypes, 7956279528Sbaptadded support for m680[34]0 and cpu32, did considerable work on i960 including 7957279528Sbapta COFF port (including considerable amounts of reverse engineering), a SPARC 7958279528Sbaptopcode file rewrite, DECstation, rs6000, and hp300hpux host ports, updated 7959279528Sbapt\(lqknow\(rq assertions and made them work, much other reorganization, cleanup, and 7960279528Sbaptlint. 7961279528Sbapt.Pp 7962279528SbaptKen Raeburn wrote the high-level BFD interface code to replace most of the 7963279528Sbaptcode in format-specific I/O modules. 7964279528Sbapt.Pp 7965279528SbaptThe original VMS support was contributed by David L. Kashtan. Eric Youngdale 7966279528Sbapthas done much work with it since. 7967279528Sbapt.Pp 7968279528SbaptThe Intel 80386 machine description was written by Eliot Dresselhaus. 7969279528Sbapt.Pp 7970279528SbaptMinh Tran-Le at IntelliCorp contributed some AIX 386 support. 7971279528Sbapt.Pp 7972279528SbaptThe Motorola 88k machine description was contributed by Devon Bowen of Buffalo 7973279528SbaptUniversity and Torbjorn Granlund of the Swedish Institute of Computer Science. 7974279528Sbapt.Pp 7975279528SbaptKeith Knowles at the Open Software Foundation wrote the original MIPS back 7976279528Sbaptend ( 7977279528Sbapt.Pa tc-mips.c , 7978279528Sbapt.Pa tc-mips.h ) , 7979279528Sbaptand contributed Rose format support (which hasn't been merged in yet). Ralph 7980279528SbaptCampbell worked with the MIPS code to support a.out format. 7981279528Sbapt.Pp 7982279528SbaptSupport for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, tc-h8300), 7983279528Sbaptand IEEE 695 object file format (obj-ieee), was written by Steve Chamberlain 7984279528Sbaptof CyGNUs Support. Steve also modified the COFF back end to use BFD for some 7985279528Sbaptlow-level operations, for use with the H8/300 and AMD 29k targets. 7986279528Sbapt.Pp 7987279528SbaptJohn Gilmore built the AMD 29000 support, added 7988279528Sbapt.Li .include 7989279528Sbaptsupport, and simplified the configuration of which versions accept which directives. 7990279528SbaptHe updated the 68k machine description so that Motorola's opcodes always produced 7991279528Sbaptfixed-size instructions (e.g., 7992279528Sbapt.Li jsr ) , 7993279528Sbaptwhile synthetic instructions remained shrinkable ( 7994279528Sbapt.Li jbsr ) . 7995279528SbaptJohn fixed many bugs, including true tested cross-compilation support, and 7996279528Sbaptone bug in relaxation that took a week and required the proverbial one-bit 7997279528Sbaptfix. 7998279528Sbapt.Pp 7999279528SbaptIan Lance Taylor of CyGNUs Support merged the Motorola and MIT syntax for 8000279528Sbaptthe 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO 8001279528SbaptUnix), added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 8002279528Sbaptand PowerPC assembler, and made a few other minor patches. 8003279528Sbapt.Pp 8004279528SbaptSteve Chamberlain made GAS able to generate listings. 8005279528Sbapt.Pp 8006279528SbaptHewlett-Packard contributed support for the HP9000/300. 8007279528Sbapt.Pp 8008279528SbaptJeff Law wrote GAS and BFD support for the native HPPA object format (SOM) 8009279528Sbaptalong with a fairly extensive HPPA testsuite (for both SOM and ELF object 8010279528Sbaptformats). This work was supported by both the Center for Software Science 8011279528Sbaptat the University of Utah and CyGNUs Support. 8012279528Sbapt.Pp 8013279528SbaptSupport for ELF format files has been worked on by Mark Eichin of CyGNUs Support 8014279528Sbapt(original, incomplete implementation for SPARC), Pete Hoogenboom and Jeff 8015279528SbaptLaw at the University of Utah (HPPA mainly), Michael Meissner of the Open 8016279528SbaptSoftware Foundation (i386 mainly), and Ken Raeburn of CyGNUs Support (sparc, 8017279528Sbaptand some initial 64-bit support). 8018279528Sbapt.Pp 8019279528SbaptLinas Vepstas added GAS support for the ESA/390 \(lqIBM 370\(rq architecture. 8020279528Sbapt.Pp 8021279528SbaptRichard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and 8022279528SbaptBFD support for openVMS/Alpha. 8023279528Sbapt.Pp 8024279528SbaptTimothy Wall, Michael Hayes, and Greg Smart contributed to the various tic* 8025279528Sbaptflavors. 8026279528Sbapt.Pp 8027279528SbaptDavid Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica, 8028279528SbaptInc. added support for Xtensa processors. 8029279528Sbapt.Pp 8030279528SbaptSeveral engineers at CyGNUs Support have also provided many small bug fixes 8031279528Sbaptand configuration enhancements. 8032279528Sbapt.Pp 8033279528SbaptMany others have contributed large or small bugfixes and enhancements. If 8034279528Sbaptyou have contributed significant work and are not mentioned on this list, 8035279528Sbaptand want to be, let us know. Some of the history has been lost; we are not 8036279528Sbaptintentionally leaving anyone out. 8037279528Sbapt.Pp 8038279528Sbapt.Sh GNU Free Documentation License 8039279528Sbapt.Bd -filled -offset indent 8040279528SbaptCopyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, 8041279528SbaptFifth Floor, Boston, MA 02110-1301 USA 8042279528Sbapt.Pp 8043279528SbaptEveryone is permitted to copy and distribute verbatim copies of this license 8044279528Sbaptdocument, but changing it is not allowed. 8045279528Sbapt.Ed 8046279528Sbapt.Pp 8047279528Sbapt.Bl -enum 8048279528Sbapt.It 8049279528SbaptPREAMBLE 8050279528Sbapt.Pp 8051279528SbaptThe purpose of this License is to make a manual, textbook, or other written 8052279528Sbaptdocument \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom 8053279528Sbaptto copy and redistribute it, with or without modifying it, either commercially 8054279528Sbaptor noncommercially. Secondarily, this License preserves for the author and 8055279528Sbaptpublisher a way to get credit for their work, while not being considered responsible 8056279528Sbaptfor modifications made by others. 8057279528Sbapt.Pp 8058279528SbaptThis License is a kind of \(lqcopyleft\(rq, which means that derivative works of the 8059279528Sbaptdocument must themselves be free in the same sense. It complements the GNU 8060279528SbaptGeneral Public License, which is a copyleft license designed for free software. 8061279528Sbapt.Pp 8062279528SbaptWe have designed this License in order to use it for manuals for free software, 8063279528Sbaptbecause free software needs free documentation: a free program should come 8064279528Sbaptwith manuals providing the same freedoms that the software does. But this 8065279528SbaptLicense is not limited to software manuals; it can be used for any textual 8066279528Sbaptwork, regardless of subject matter or whether it is published as a printed 8067279528Sbaptbook. We recommend this License principally for works whose purpose is instruction 8068279528Sbaptor reference. 8069279528Sbapt.Pp 8070279528Sbapt.It 8071279528SbaptAPPLICABILITY AND DEFINITIONS 8072279528Sbapt.Pp 8073279528SbaptThis License applies to any manual or other work that contains a notice placed 8074279528Sbaptby the copyright holder saying it can be distributed under the terms of this 8075279528SbaptLicense. The \(lqDocument\(rq, below, refers to any such manual or work. Any member 8076279528Sbaptof the public is a licensee, and is addressed as \(lqyou.\(rq 8077279528Sbapt.Pp 8078279528SbaptA \(lqModified Version\(rq of the Document means any work containing the Document 8079279528Sbaptor a portion of it, either copied verbatim, or with modifications and/or translated 8080279528Sbaptinto another language. 8081279528Sbapt.Pp 8082279528SbaptA \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document 8083279528Sbaptthat deals exclusively with the relationship of the publishers or authors 8084279528Sbaptof the Document to the Document's overall subject (or to related matters) 8085279528Sbaptand contains nothing that could fall directly within that overall subject. 8086279528Sbapt(For example, if the Document is in part a textbook of mathematics, a Secondary 8087279528SbaptSection may not explain any mathematics.) The relationship could be a matter 8088279528Sbaptof historical connection with the subject or with related matters, or of legal, 8089279528Sbaptcommercial, philosophical, ethical or political position regarding them. 8090279528Sbapt.Pp 8091279528SbaptThe \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, 8092279528Sbaptas being those of Invariant Sections, in the notice that says that the Document 8093279528Sbaptis released under this License. 8094279528Sbapt.Pp 8095279528SbaptThe \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover 8096279528SbaptTexts or Back-Cover Texts, in the notice that says that the Document is released 8097279528Sbaptunder this License. 8098279528Sbapt.Pp 8099279528SbaptA \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented 8100279528Sbaptin a format whose specification is available to the general public, whose 8101279528Sbaptcontents can be viewed and edited directly and straightforwardly with generic 8102279528Sbapttext editors or (for images composed of pixels) generic paint programs or 8103279528Sbapt(for drawings) some widely available drawing editor, and that is suitable 8104279528Sbaptfor input to text formatters or for automatic translation to a variety of 8105279528Sbaptformats suitable for input to text formatters. A copy made in an otherwise 8106279528SbaptTransparent file format whose markup has been designed to thwart or discourage 8107279528Sbaptsubsequent modification by readers is not Transparent. A copy that is not 8108279528Sbapt\(lqTransparent\(rq is called \(lqOpaque.\(rq 8109279528Sbapt.Pp 8110279528SbaptExamples of suitable formats for Transparent copies include plain ASCII without 8111279528Sbaptmarkup, Texinfo input format, LaTeX input format, SGML or XML using a publicly 8112279528Sbaptavailable DTD, and standard-conforming simple HTML designed for human modification. 8113279528SbaptOpaque formats include PostScript, PDF, proprietary formats that can be read 8114279528Sbaptand edited only by proprietary word processors, SGML or XML for which the 8115279528SbaptDTD and/or processing tools are not generally available, and the machine-generated 8116279528SbaptHTML produced by some word processors for output purposes only. 8117279528Sbapt.Pp 8118279528SbaptThe \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such 8119279528Sbaptfollowing pages as are needed to hold, legibly, the material this License 8120279528Sbaptrequires to appear in the title page. For works in formats which do not have 8121279528Sbaptany title page as such, \(lqTitle Page\(rq means the text near the most prominent 8122279528Sbaptappearance of the work's title, preceding the beginning of the body of the 8123279528Sbapttext. 8124279528Sbapt.Pp 8125279528Sbapt.It 8126279528SbaptVERBATIM COPYING 8127279528Sbapt.Pp 8128279528SbaptYou may copy and distribute the Document in any medium, either commercially 8129279528Sbaptor noncommercially, provided that this License, the copyright notices, and 8130279528Sbaptthe license notice saying this License applies to the Document are reproduced 8131279528Sbaptin all copies, and that you add no other conditions whatsoever to those of 8132279528Sbaptthis License. You may not use technical measures to obstruct or control the 8133279528Sbaptreading or further copying of the copies you make or distribute. However, 8134279528Sbaptyou may accept compensation in exchange for copies. If you distribute a large 8135279528Sbaptenough number of copies you must also follow the conditions in section 3. 8136279528Sbapt.Pp 8137279528SbaptYou may also lend copies, under the same conditions stated above, and you 8138279528Sbaptmay publicly display copies. 8139279528Sbapt.Pp 8140279528Sbapt.It 8141279528SbaptCOPYING IN QUANTITY 8142279528Sbapt.Pp 8143279528SbaptIf you publish printed copies of the Document numbering more than 100, and 8144279528Sbaptthe Document's license notice requires Cover Texts, you must enclose the copies 8145279528Sbaptin covers that carry, clearly and legibly, all these Cover Texts: Front-Cover 8146279528SbaptTexts on the front cover, and Back-Cover Texts on the back cover. Both covers 8147279528Sbaptmust also clearly and legibly identify you as the publisher of these copies. 8148279528SbaptThe front cover must present the full title with all words of the title equally 8149279528Sbaptprominent and visible. You may add other material on the covers in addition. 8150279528SbaptCopying with changes limited to the covers, as long as they preserve the title 8151279528Sbaptof the Document and satisfy these conditions, can be treated as verbatim copying 8152279528Sbaptin other respects. 8153279528Sbapt.Pp 8154279528SbaptIf the required texts for either cover are too voluminous to fit legibly, 8155279528Sbaptyou should put the first ones listed (as many as fit reasonably) on the actual 8156279528Sbaptcover, and continue the rest onto adjacent pages. 8157279528Sbapt.Pp 8158279528SbaptIf you publish or distribute Opaque copies of the Document numbering more 8159279528Sbaptthan 100, you must either include a machine-readable Transparent copy along 8160279528Sbaptwith each Opaque copy, or state in or with each Opaque copy a publicly-accessible 8161279528Sbaptcomputer-network location containing a complete Transparent copy of the Document, 8162279528Sbaptfree of added material, which the general network-using public has access 8163279528Sbaptto download anonymously at no charge using public-standard network protocols. 8164279528SbaptIf you use the latter option, you must take reasonably prudent steps, when 8165279528Sbaptyou begin distribution of Opaque copies in quantity, to ensure that this Transparent 8166279528Sbaptcopy will remain thus accessible at the stated location until at least one 8167279528Sbaptyear after the last time you distribute an Opaque copy (directly or through 8168279528Sbaptyour agents or retailers) of that edition to the public. 8169279528Sbapt.Pp 8170279528SbaptIt is requested, but not required, that you contact the authors of the Document 8171279528Sbaptwell before redistributing any large number of copies, to give them a chance 8172279528Sbaptto provide you with an updated version of the Document. 8173279528Sbapt.Pp 8174279528Sbapt.It 8175279528SbaptMODIFICATIONS 8176279528Sbapt.Pp 8177279528SbaptYou may copy and distribute a Modified Version of the Document under the conditions 8178279528Sbaptof sections 2 and 3 above, provided that you release the Modified Version 8179279528Sbaptunder precisely this License, with the Modified Version filling the role of 8180279528Sbaptthe Document, thus licensing distribution and modification of the Modified 8181279528SbaptVersion to whoever possesses a copy of it. In addition, you must do these 8182279528Sbaptthings in the Modified Version: 8183279528Sbapt.Pp 8184279528SbaptA. Use in the Title Page (and on the covers, if any) a title distinct from 8185279528Sbaptthat of the Document, and from those of previous versions (which should, if 8186279528Sbaptthere were any, be listed in the History section of the Document). You may 8187279528Sbaptuse the same title as a previous version if the original publisher of that 8188279528Sbaptversion gives permission. B. List on the Title Page, as authors, one or more 8189279528Sbaptpersons or entities responsible for authorship of the modifications in the 8190279528SbaptModified Version, together with at least five of the principal authors of 8191279528Sbaptthe Document (all of its principal authors, if it has less than five). C. 8192279528SbaptState on the Title page the name of the publisher of the Modified Version, 8193279528Sbaptas the publisher. D. Preserve all the copyright notices of the Document. 8194279528SbaptE. Add an appropriate copyright notice for your modifications adjacent to 8195279528Sbaptthe other copyright notices. F. Include, immediately after the copyright 8196279528Sbaptnotices, a license notice giving the public permission to use the Modified 8197279528SbaptVersion under the terms of this License, in the form shown in the Addendum 8198279528Sbaptbelow. G. Preserve in that license notice the full lists of Invariant Sections 8199279528Sbaptand required Cover Texts given in the Document's license notice. H. Include 8200279528Sbaptan unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, 8201279528Sbaptand its title, and add to it an item stating at least the title, year, new 8202279528Sbaptauthors, and publisher of the Modified Version as given on the Title Page. 8203279528SbaptIf there is no section entitled \(lqHistory\(rq in the Document, create one stating 8204279528Sbaptthe title, year, authors, and publisher of the Document as given on its Title 8205279528SbaptPage, then add an item describing the Modified Version as stated in the previous 8206279528Sbaptsentence. J. Preserve the network location, if any, given in the Document 8207279528Sbaptfor public access to a Transparent copy of the Document, and likewise the 8208279528Sbaptnetwork locations given in the Document for previous versions it was based 8209279528Sbapton. These may be placed in the \(lqHistory\(rq section. You may omit a network location 8210279528Sbaptfor a work that was published at least four years before the Document itself, 8211279528Sbaptor if the original publisher of the version it refers to gives permission. 8212279528SbaptK. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's 8213279528Sbapttitle, and preserve in the section all the substance and tone of each of the 8214279528Sbaptcontributor acknowledgements and/or dedications given therein. L. Preserve 8215279528Sbaptall the Invariant Sections of the Document, unaltered in their text and in 8216279528Sbapttheir titles. Section numbers or the equivalent are not considered part of 8217279528Sbaptthe section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section 8218279528Sbaptmay not be included in the Modified Version. N. Do not retitle any existing 8219279528Sbaptsection as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. 8220279528Sbapt.Pp 8221279528SbaptIf the Modified Version includes new front-matter sections or appendices that 8222279528Sbaptqualify as Secondary Sections and contain no material copied from the Document, 8223279528Sbaptyou may at your option designate some or all of these sections as invariant. 8224279528SbaptTo do this, add their titles to the list of Invariant Sections in the Modified 8225279528SbaptVersion's license notice. These titles must be distinct from any other section 8226279528Sbapttitles. 8227279528Sbapt.Pp 8228279528SbaptYou may add a section entitled \(lqEndorsements\(rq, provided it contains nothing 8229279528Sbaptbut endorsements of your Modified Version by various parties--for example, 8230279528Sbaptstatements of peer review or that the text has been approved by an organization 8231279528Sbaptas the authoritative definition of a standard. 8232279528Sbapt.Pp 8233279528SbaptYou may add a passage of up to five words as a Front-Cover Text, and a passage 8234279528Sbaptof up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts 8235279528Sbaptin the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover 8236279528SbaptText may be added by (or through arrangements made by) any one entity. If 8237279528Sbaptthe Document already includes a cover text for the same cover, previously 8238279528Sbaptadded by you or by arrangement made by the same entity you are acting on behalf 8239279528Sbaptof, you may not add another; but you may replace the old one, on explicit 8240279528Sbaptpermission from the previous publisher that added the old one. 8241279528Sbapt.Pp 8242279528SbaptThe author(s) and publisher(s) of the Document do not by this License give 8243279528Sbaptpermission to use their names for publicity for or to assert or imply endorsement 8244279528Sbaptof any Modified Version. 8245279528Sbapt.Pp 8246279528Sbapt.It 8247279528SbaptCOMBINING DOCUMENTS 8248279528Sbapt.Pp 8249279528SbaptYou may combine the Document with other documents released under this License, 8250279528Sbaptunder the terms defined in section 4 above for modified versions, provided 8251279528Sbaptthat you include in the combination all of the Invariant Sections of all of 8252279528Sbaptthe original documents, unmodified, and list them all as Invariant Sections 8253279528Sbaptof your combined work in its license notice. 8254279528Sbapt.Pp 8255279528SbaptThe combined work need only contain one copy of this License, and multiple 8256279528Sbaptidentical Invariant Sections may be replaced with a single copy. If there 8257279528Sbaptare multiple Invariant Sections with the same name but different contents, 8258279528Sbaptmake the title of each such section unique by adding at the end of it, in 8259279528Sbaptparentheses, the name of the original author or publisher of that section 8260279528Sbaptif known, or else a unique number. Make the same adjustment to the section 8261279528Sbapttitles in the list of Invariant Sections in the license notice of the combined 8262279528Sbaptwork. 8263279528Sbapt.Pp 8264279528SbaptIn the combination, you must combine any sections entitled \(lqHistory\(rq in the 8265279528Sbaptvarious original documents, forming one section entitled \(lqHistory\(rq; likewise 8266279528Sbaptcombine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled 8267279528Sbapt\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq 8268279528Sbapt.Pp 8269279528Sbapt.It 8270279528SbaptCOLLECTIONS OF DOCUMENTS 8271279528Sbapt.Pp 8272279528SbaptYou may make a collection consisting of the Document and other documents released 8273279528Sbaptunder this License, and replace the individual copies of this License in the 8274279528Sbaptvarious documents with a single copy that is included in the collection, provided 8275279528Sbaptthat you follow the rules of this License for verbatim copying of each of 8276279528Sbaptthe documents in all other respects. 8277279528Sbapt.Pp 8278279528SbaptYou may extract a single document from such a collection, and distribute it 8279279528Sbaptindividually under this License, provided you insert a copy of this License 8280279528Sbaptinto the extracted document, and follow this License in all other respects 8281279528Sbaptregarding verbatim copying of that document. 8282279528Sbapt.Pp 8283279528Sbapt.It 8284279528SbaptAGGREGATION WITH INDEPENDENT WORKS 8285279528Sbapt.Pp 8286279528SbaptA compilation of the Document or its derivatives with other separate and independent 8287279528Sbaptdocuments or works, in or on a volume of a storage or distribution medium, 8288279528Sbaptdoes not as a whole count as a Modified Version of the Document, provided 8289279528Sbaptno compilation copyright is claimed for the compilation. Such a compilation 8290279528Sbaptis called an \(lqaggregate\(rq, and this License does not apply to the other self-contained 8291279528Sbaptworks thus compiled with the Document, on account of their being thus compiled, 8292279528Sbaptif they are not themselves derivative works of the Document. 8293279528Sbapt.Pp 8294279528SbaptIf the Cover Text requirement of section 3 is applicable to these copies of 8295279528Sbaptthe Document, then if the Document is less than one quarter of the entire 8296279528Sbaptaggregate, the Document's Cover Texts may be placed on covers that surround 8297279528Sbaptonly the Document within the aggregate. Otherwise they must appear on covers 8298279528Sbaptaround the whole aggregate. 8299279528Sbapt.Pp 8300279528Sbapt.It 8301279528SbaptTRANSLATION 8302279528Sbapt.Pp 8303279528SbaptTranslation is considered a kind of modification, so you may distribute translations 8304279528Sbaptof the Document under the terms of section 4. Replacing Invariant Sections 8305279528Sbaptwith translations requires special permission from their copyright holders, 8306279528Sbaptbut you may include translations of some or all Invariant Sections in addition 8307279528Sbaptto the original versions of these Invariant Sections. You may include a translation 8308279528Sbaptof this License provided that you also include the original English version 8309279528Sbaptof this License. In case of a disagreement between the translation and the 8310279528Sbaptoriginal English version of this License, the original English version will 8311279528Sbaptprevail. 8312279528Sbapt.Pp 8313279528Sbapt.It 8314279528SbaptTERMINATION 8315279528Sbapt.Pp 8316279528SbaptYou may not copy, modify, sublicense, or distribute the Document except as 8317279528Sbaptexpressly provided for under this License. Any other attempt to copy, modify, 8318279528Sbaptsublicense or distribute the Document is void, and will automatically terminate 8319279528Sbaptyour rights under this License. However, parties who have received copies, 8320279528Sbaptor rights, from you under this License will not have their licenses terminated 8321279528Sbaptso long as such parties remain in full compliance. 8322279528Sbapt.Pp 8323279528Sbapt.It 8324279528SbaptFUTURE REVISIONS OF THIS LICENSE 8325279528Sbapt.Pp 8326279528SbaptThe Free Software Foundation may publish new, revised versions of the GNU 8327279528SbaptFree Documentation License from time to time. Such new versions will be similar 8328279528Sbaptin spirit to the present version, but may differ in detail to address new 8329279528Sbaptproblems or concerns. See http://www.gnu.org/copyleft/. 8330279528Sbapt.Pp 8331279528SbaptEach version of the License is given a distinguishing version number. If the 8332279528SbaptDocument specifies that a particular numbered version of this License \(lqor any 8333279528Sbaptlater version\(rq applies to it, you have the option of following the terms and 8334279528Sbaptconditions either of that specified version or of any later version that has 8335279528Sbaptbeen published (not as a draft) by the Free Software Foundation. If the Document 8336279528Sbaptdoes not specify a version number of this License, you may choose any version 8337279528Sbaptever published (not as a draft) by the Free Software Foundation. 8338279528Sbapt.Pp 8339279528Sbapt.El 8340279528Sbapt.Ss ADDENDUM: How to use this License for your documents 8341279528SbaptTo use this License in a document you have written, include a copy of the 8342279528SbaptLicense in the document and put the following copyright and license notices 8343279528Sbaptjust after the title page: 8344279528Sbapt.Pp 8345279528Sbapt.Bd -literal -offset indent 8346279528Sbapt 8347279528SbaptCopyright (C) year your name. 8348279528SbaptPermission is granted to copy, distribute and/or modify this document 8349279528Sbaptunder the terms of the GNU Free Documentation License, Version 1.1 8350279528Sbaptor any later version published by the Free Software Foundation; 8351279528Sbaptwith the Invariant Sections being list their titles, with the 8352279528SbaptFront-Cover Texts being list, and with the Back-Cover Texts being list. 8353279528SbaptA copy of the license is included in the section entitled "GNU 8354279528SbaptFree Documentation License." 8355279528Sbapt 8356279528Sbapt.Ed 8357279528Sbapt.Pp 8358279528SbaptIf you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead 8359279528Sbaptof saying which ones are invariant. If you have no Front-Cover Texts, write 8360279528Sbapt\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being 8361279528Sbapt.Va list 8362279528Sbapt\(rq; likewise for Back-Cover Texts. 8363279528Sbapt.Pp 8364279528SbaptIf your document contains nontrivial examples of program code, we recommend 8365279528Sbaptreleasing these examples in parallel under your choice of free software license, 8366279528Sbaptsuch as the GNU General Public License, to permit their use in free software. 8367279528Sbapt.Pp 8368279528Sbapt.Sh AS Index 8369