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