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