133965Sjdp\input texinfo @c -*-Texinfo-*- 278828Sobrien@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 3218822Sdim@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 438889Sjdp@c Free Software Foundation, Inc. 533965Sjdp@c UPDATE!! On future updates-- 633965Sjdp@c (1) check for new machine-dep cmdline options in 733965Sjdp@c md_parse_option definitions in config/tc-*.c 833965Sjdp@c (2) for platform-specific directives, examine md_pseudo_op 933965Sjdp@c in config/tc-*.c 1033965Sjdp@c (3) for object-format specific directives, examine obj_pseudo_op 1133965Sjdp@c in config/obj-*.c 1233965Sjdp@c (4) portable directives in potable[] in read.c 1333965Sjdp@c %**start of header 1433965Sjdp@setfilename as.info 1533965Sjdp@c ---config--- 1689857Sobrien@macro gcctabopt{body} 1789857Sobrien@code{\body\} 1889857Sobrien@end macro 1933965Sjdp@c defaults, config file may override: 2033965Sjdp@set have-stabs 2133965Sjdp@c --- 22130561Sobrien@c man begin NAME 23130561Sobrien@c --- 2433965Sjdp@include asconfig.texi 25218822Sdim@include bfdver.texi 2633965Sjdp@c --- 2789857Sobrien@c man end 28130561Sobrien@c --- 2933965Sjdp@c common OR combinations of conditions 30130561Sobrien@ifset COFF 31130561Sobrien@set COFF-ELF 32130561Sobrien@end ifset 33130561Sobrien@ifset ELF 34130561Sobrien@set COFF-ELF 35130561Sobrien@end ifset 3633965Sjdp@ifset AOUT 3733965Sjdp@set aout-bout 3833965Sjdp@end ifset 3938889Sjdp@ifset ARM/Thumb 4038889Sjdp@set ARM 4138889Sjdp@end ifset 4233965Sjdp@ifset BOUT 4333965Sjdp@set aout-bout 4433965Sjdp@end ifset 4533965Sjdp@ifset H8/300 4633965Sjdp@set H8 4733965Sjdp@end ifset 4833965Sjdp@ifset SH 4933965Sjdp@set H8 5033965Sjdp@end ifset 5133965Sjdp@ifset HPPA 5233965Sjdp@set abnormal-separator 5333965Sjdp@end ifset 5433965Sjdp@c ------------ 5533965Sjdp@ifset GENERIC 5633965Sjdp@settitle Using @value{AS} 5733965Sjdp@end ifset 5833965Sjdp@ifclear GENERIC 5933965Sjdp@settitle Using @value{AS} (@value{TARGET}) 6033965Sjdp@end ifclear 6133965Sjdp@setchapternewpage odd 6233965Sjdp@c %**end of header 6333965Sjdp 6433965Sjdp@c @smallbook 6533965Sjdp@c @set SMALL 6633965Sjdp@c WARE! Some of the machine-dependent sections contain tables of machine 6733965Sjdp@c instructions. Except in multi-column format, these tables look silly. 6833965Sjdp@c Unfortunately, Texinfo doesn't have a general-purpose multi-col format, so 6933965Sjdp@c the multi-col format is faked within @example sections. 7033965Sjdp@c 7133965Sjdp@c Again unfortunately, the natural size that fits on a page, for these tables, 7233965Sjdp@c is different depending on whether or not smallbook is turned on. 7333965Sjdp@c This matters, because of order: text flow switches columns at each page 7433965Sjdp@c break. 7533965Sjdp@c 7633965Sjdp@c The format faked in this source works reasonably well for smallbook, 7733965Sjdp@c not well for the default large-page format. This manual expects that if you 7833965Sjdp@c turn on @smallbook, you will also uncomment the "@set SMALL" to enable the 7933965Sjdp@c tables in question. You can turn on one without the other at your 8033965Sjdp@c discretion, of course. 8133965Sjdp@ifinfo 8233965Sjdp@set SMALL 8333965Sjdp@c the insn tables look just as silly in info files regardless of smallbook, 8433965Sjdp@c might as well show 'em anyways. 8533965Sjdp@end ifinfo 8633965Sjdp 8733965Sjdp@ifinfo 8833965Sjdp@format 8933965SjdpSTART-INFO-DIR-ENTRY 9033965Sjdp* As: (as). The GNU assembler. 9191041Sobrien* Gas: (as). The GNU assembler. 9233965SjdpEND-INFO-DIR-ENTRY 9333965Sjdp@end format 9433965Sjdp@end ifinfo 9533965Sjdp 9633965Sjdp@finalout 9733965Sjdp@syncodeindex ky cp 9833965Sjdp 99218822Sdim@copying 10033965SjdpThis file documents the GNU Assembler "@value{AS}". 10133965Sjdp 10289857Sobrien@c man begin COPYRIGHT 103218822SdimCopyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002, 104218822Sdim2006, 2007 Free Software Foundation, Inc. 10533965Sjdp 10689857SobrienPermission is granted to copy, distribute and/or modify this document 10789857Sobrienunder the terms of the GNU Free Documentation License, Version 1.1 10889857Sobrienor any later version published by the Free Software Foundation; 10989857Sobrienwith no Invariant Sections, with no Front-Cover Texts, and with no 11089857SobrienBack-Cover Texts. A copy of the license is included in the 111130561Sobriensection entitled ``GNU Free Documentation License''. 11233965Sjdp 11389857Sobrien@c man end 114218822Sdim@end copying 11589857Sobrien 11633965Sjdp@titlepage 11733965Sjdp@title Using @value{AS} 11833965Sjdp@subtitle The @sc{gnu} Assembler 11933965Sjdp@ifclear GENERIC 12033965Sjdp@subtitle for the @value{TARGET} family 12133965Sjdp@end ifclear 122218822Sdim@ifset VERSION_PACKAGE 12333965Sjdp@sp 1 124218822Sdim@subtitle @value{VERSION_PACKAGE} 125218822Sdim@end ifset 126218822Sdim@sp 1 12760484Sobrien@subtitle Version @value{VERSION} 12833965Sjdp@sp 1 12933965Sjdp@sp 13 130218822SdimThe Free Software Foundation Inc.@: thanks The Nice Computer 13133965SjdpCompany of Australia for loaning Dean Elsner to write the 13289857Sobrienfirst (Vax) version of @command{as} for Project @sc{gnu}. 13333965SjdpThe proprietors, management and staff of TNCCA thank FSF for 13433965Sjdpdistracting the boss while they got some work 13533965Sjdpdone. 13633965Sjdp@sp 3 13733965Sjdp@author Dean Elsner, Jay Fenlason & friends 13833965Sjdp@page 13933965Sjdp@tex 14033965Sjdp{\parskip=0pt 14133965Sjdp\hfill {\it Using {\tt @value{AS}}}\par 14233965Sjdp\hfill Edited by Cygnus Support\par 14333965Sjdp} 14433965Sjdp%"boxit" macro for figures: 14533965Sjdp%Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3) 14633965Sjdp\gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt 14733965Sjdp \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil 14833965Sjdp#2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline 14933965Sjdp\gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box 15033965Sjdp@end tex 15133965Sjdp 15233965Sjdp@vskip 0pt plus 1filll 153218822SdimCopyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002, 154218822Sdim2006, 2007 Free Software Foundation, Inc. 15533965Sjdp 15677298Sobrien Permission is granted to copy, distribute and/or modify this document 15777298Sobrien under the terms of the GNU Free Documentation License, Version 1.1 15877298Sobrien or any later version published by the Free Software Foundation; 15977298Sobrien with no Invariant Sections, with no Front-Cover Texts, and with no 16077298Sobrien Back-Cover Texts. A copy of the license is included in the 161130561Sobrien section entitled ``GNU Free Documentation License''. 16233965Sjdp 16333965Sjdp@end titlepage 164218822Sdim@contents 16533965Sjdp 16692828Sobrien@ifnottex 16733965Sjdp@node Top 16833965Sjdp@top Using @value{AS} 16933965Sjdp 170218822SdimThis file is a user guide to the @sc{gnu} assembler @command{@value{AS}} 171218822Sdim@ifset VERSION_PACKAGE 172218822Sdim@value{VERSION_PACKAGE} 173218822Sdim@end ifset 174218822Sdimversion @value{VERSION}. 17533965Sjdp@ifclear GENERIC 17689857SobrienThis version of the file describes @command{@value{AS}} configured to generate 17733965Sjdpcode for @value{TARGET} architectures. 17833965Sjdp@end ifclear 17977298Sobrien 18077298SobrienThis document is distributed under the terms of the GNU Free 18177298SobrienDocumentation License. A copy of the license is included in the 182130561Sobriensection entitled ``GNU Free Documentation License''. 18377298Sobrien 18433965Sjdp@menu 18533965Sjdp* Overview:: Overview 18633965Sjdp* Invoking:: Command-Line Options 18733965Sjdp* Syntax:: Syntax 18833965Sjdp* Sections:: Sections and Relocation 18933965Sjdp* Symbols:: Symbols 19033965Sjdp* Expressions:: Expressions 19133965Sjdp* Pseudo Ops:: Assembler Directives 19233965Sjdp* Machine Dependencies:: Machine Dependent Features 19333965Sjdp* Reporting Bugs:: Reporting Bugs 19433965Sjdp* Acknowledgements:: Who Did What 19577298Sobrien* GNU Free Documentation License:: GNU Free Documentation License 196218822Sdim* AS Index:: AS Index 19733965Sjdp@end menu 19892828Sobrien@end ifnottex 19933965Sjdp 20033965Sjdp@node Overview 20133965Sjdp@chapter Overview 20233965Sjdp@iftex 20389857SobrienThis manual is a user guide to the @sc{gnu} assembler @command{@value{AS}}. 20433965Sjdp@ifclear GENERIC 20589857SobrienThis version of the manual describes @command{@value{AS}} configured to generate 20633965Sjdpcode for @value{TARGET} architectures. 20733965Sjdp@end ifclear 20833965Sjdp@end iftex 20933965Sjdp 21033965Sjdp@cindex invocation summary 21133965Sjdp@cindex option summary 21233965Sjdp@cindex summary of options 21389857SobrienHere is a brief summary of how to invoke @command{@value{AS}}. For details, 214218822Sdimsee @ref{Invoking,,Command-Line Options}. 21533965Sjdp 21689857Sobrien@c man title AS the portable GNU assembler. 21789857Sobrien 21889857Sobrien@ignore 21989857Sobrien@c man begin SEEALSO 22089857Sobriengcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. 22189857Sobrien@c man end 22289857Sobrien@end ignore 22389857Sobrien 22433965Sjdp@c We don't use deffn and friends for the following because they seem 22533965Sjdp@c to be limited to one line for the header. 22633965Sjdp@smallexample 22789857Sobrien@c man begin SYNOPSIS 228218822Sdim@value{AS} [@b{-a}[@b{cdhlns}][=@var{file}]] [@b{--alternate}] [@b{-D}] 229218822Sdim [@b{--defsym} @var{sym}=@var{val}] [@b{-f}] [@b{-g}] [@b{--gstabs}] 230218822Sdim [@b{--gstabs+}] [@b{--gdwarf-2}] [@b{--help}] [@b{-I} @var{dir}] [@b{-J}] 231218822Sdim [@b{-K}] [@b{-L}] [@b{--listing-lhs-width}=@var{NUM}] 232218822Sdim [@b{--listing-lhs-width2}=@var{NUM}] [@b{--listing-rhs-width}=@var{NUM}] 233218822Sdim [@b{--listing-cont-lines}=@var{NUM}] [@b{--keep-locals}] [@b{-o} 234218822Sdim @var{objfile}] [@b{-R}] [@b{--reduce-memory-overheads}] [@b{--statistics}] 235218822Sdim [@b{-v}] [@b{-version}] [@b{--version}] [@b{-W}] [@b{--warn}] 236218822Sdim [@b{--fatal-warnings}] [@b{-w}] [@b{-x}] [@b{-Z}] [@b{@@@var{FILE}}] 237218822Sdim [@b{--target-help}] [@var{target-options}] 23889857Sobrien [@b{--}|@var{files} @dots{}] 23989857Sobrien@c 24089857Sobrien@c Target dependent options are listed below. Keep the list sorted. 24189857Sobrien@c Add an empty line for separation. 24291041Sobrien@ifset ALPHA 24391041Sobrien 24491041Sobrien@emph{Target Alpha options:} 24591041Sobrien [@b{-m@var{cpu}}] 24691041Sobrien [@b{-mdebug} | @b{-no-mdebug}] 24791041Sobrien [@b{-relax}] [@b{-g}] [@b{-G@var{size}}] 24891041Sobrien [@b{-F}] [@b{-32addr}] 24991041Sobrien@end ifset 25038889Sjdp@ifset ARC 25189857Sobrien 25289857Sobrien@emph{Target ARC options:} 25389857Sobrien [@b{-marc[5|6|7|8]}] 25489857Sobrien [@b{-EB}|@b{-EL}] 25538889Sjdp@end ifset 25638889Sjdp@ifset ARM 25789857Sobrien 25889857Sobrien@emph{Target ARM options:} 25989857Sobrien@c Don't document the deprecated options 26089857Sobrien [@b{-mcpu}=@var{processor}[+@var{extension}@dots{}]] 26189857Sobrien [@b{-march}=@var{architecture}[+@var{extension}@dots{}]] 262130561Sobrien [@b{-mfpu}=@var{floating-point-format}] 263130561Sobrien [@b{-mfloat-abi}=@var{abi}] 264218822Sdim [@b{-meabi}=@var{ver}] 26589857Sobrien [@b{-mthumb}] 26689857Sobrien [@b{-EB}|@b{-EL}] 26789857Sobrien [@b{-mapcs-32}|@b{-mapcs-26}|@b{-mapcs-float}| 26889857Sobrien @b{-mapcs-reentrant}] 269218822Sdim [@b{-mthumb-interwork}] [@b{-k}] 27038889Sjdp@end ifset 27191041Sobrien@ifset CRIS 27291041Sobrien 27391041Sobrien@emph{Target CRIS options:} 27491041Sobrien [@b{--underscore} | @b{--no-underscore}] 27591041Sobrien [@b{--pic}] [@b{-N}] 27691041Sobrien [@b{--emulation=criself} | @b{--emulation=crisaout}] 277218822Sdim [@b{--march=v0_v10} | @b{--march=v10} | @b{--march=v32} | @b{--march=common_v10_v32}] 27891041Sobrien@c Deprecated -- deliberately not documented. 27991041Sobrien@c [@b{-h}] [@b{-H}] 28091041Sobrien@end ifset 28133965Sjdp@ifset D10V 28289857Sobrien 28389857Sobrien@emph{Target D10V options:} 28489857Sobrien [@b{-O}] 28533965Sjdp@end ifset 28660484Sobrien@ifset D30V 28789857Sobrien 28889857Sobrien@emph{Target D30V options:} 28989857Sobrien [@b{-O}|@b{-n}|@b{-N}] 29060484Sobrien@end ifset 29133965Sjdp@ifset H8 292130561Sobrien@c Renesas family chips have no machine-dependent assembler options 29333965Sjdp@end ifset 29433965Sjdp@ifset HPPA 29533965Sjdp@c HPPA has no machine-dependent assembler options (yet). 29633965Sjdp@end ifset 29789857Sobrien@ifset I80386 29889857Sobrien 29989857Sobrien@emph{Target i386 options:} 300130561Sobrien [@b{--32}|@b{--64}] [@b{-n}] 301218822Sdim [@b{-march}=@var{CPU}] [@b{-mtune}=@var{CPU}] 30260484Sobrien@end ifset 30333965Sjdp@ifset I960 30489857Sobrien 30589857Sobrien@emph{Target i960 options:} 30633965Sjdp@c see md_parse_option in tc-i960.c 30789857Sobrien [@b{-ACA}|@b{-ACA_A}|@b{-ACB}|@b{-ACC}|@b{-AKA}|@b{-AKB}| 30889857Sobrien @b{-AKC}|@b{-AMC}] 30989857Sobrien [@b{-b}] [@b{-no-relax}] 31033965Sjdp@end ifset 311104834Sobrien@ifset IA64 312104834Sobrien 313104834Sobrien@emph{Target IA-64 options:} 314104834Sobrien [@b{-mconstant-gp}|@b{-mauto-pic}] 315104834Sobrien [@b{-milp32}|@b{-milp64}|@b{-mlp64}|@b{-mp64}] 316104834Sobrien [@b{-mle}|@b{mbe}] 317218822Sdim [@b{-mtune=itanium1}|@b{-mtune=itanium2}] 318218822Sdim [@b{-munwind-check=warning}|@b{-munwind-check=error}] 319218822Sdim [@b{-mhint.b=ok}|@b{-mhint.b=warning}|@b{-mhint.b=error}] 320104834Sobrien [@b{-x}|@b{-xexplicit}] [@b{-xauto}] [@b{-xdebug}] 321104834Sobrien@end ifset 322130561Sobrien@ifset IP2K 323130561Sobrien 324130561Sobrien@emph{Target IP2K options:} 325130561Sobrien [@b{-mip2022}|@b{-mip2022ext}] 326130561Sobrien@end ifset 327218822Sdim@ifset M32C 328218822Sdim 329218822Sdim@emph{Target M32C options:} 330218822Sdim [@b{-m32c}|@b{-m16c}] 331218822Sdim@end ifset 33277298Sobrien@ifset M32R 33389857Sobrien 33489857Sobrien@emph{Target M32R options:} 33589857Sobrien [@b{--m32rx}|@b{--[no-]warn-explicit-parallel-conflicts}| 336104834Sobrien @b{--W[n]p}] 33777298Sobrien@end ifset 33833965Sjdp@ifset M680X0 33989857Sobrien 34089857Sobrien@emph{Target M680X0 options:} 34189857Sobrien [@b{-l}] [@b{-m68000}|@b{-m68010}|@b{-m68020}|@dots{}] 34233965Sjdp@end ifset 34389857Sobrien@ifset M68HC11 34489857Sobrien 34589857Sobrien@emph{Target M68HC11 options:} 346130561Sobrien [@b{-m68hc11}|@b{-m68hc12}|@b{-m68hcs12}] 347130561Sobrien [@b{-mshort}|@b{-mlong}] 348130561Sobrien [@b{-mshort-double}|@b{-mlong-double}] 349218822Sdim [@b{--force-long-branches}] [@b{--short-branches}] 35089857Sobrien [@b{--strict-direct-mode}] [@b{--print-insn-syntax}] 35189857Sobrien [@b{--print-opcodes}] [@b{--generate-example}] 35289857Sobrien@end ifset 35360484Sobrien@ifset MCORE 35489857Sobrien 35589857Sobrien@emph{Target MCORE options:} 35689857Sobrien [@b{-jsri2bsr}] [@b{-sifilter}] [@b{-relax}] 35789857Sobrien [@b{-mcpu=[210|340]}] 35860484Sobrien@end ifset 35933965Sjdp@ifset MIPS 36089857Sobrien 36189857Sobrien@emph{Target MIPS options:} 362130561Sobrien [@b{-nocpp}] [@b{-EL}] [@b{-EB}] [@b{-O}[@var{optimization level}]] 363104834Sobrien [@b{-g}[@var{debug level}]] [@b{-G} @var{num}] [@b{-KPIC}] [@b{-call_shared}] 364218822Sdim [@b{-non_shared}] [@b{-xgot} [@b{-mvxworks-pic}] 365104834Sobrien [@b{-mabi}=@var{ABI}] [@b{-32}] [@b{-n32}] [@b{-64}] [@b{-mfp32}] [@b{-mgp32}] 366104834Sobrien [@b{-march}=@var{CPU}] [@b{-mtune}=@var{CPU}] [@b{-mips1}] [@b{-mips2}] 367130561Sobrien [@b{-mips3}] [@b{-mips4}] [@b{-mips5}] [@b{-mips32}] [@b{-mips32r2}] 368130561Sobrien [@b{-mips64}] [@b{-mips64r2}] 369104834Sobrien [@b{-construct-floats}] [@b{-no-construct-floats}] 370104834Sobrien [@b{-trap}] [@b{-no-break}] [@b{-break}] [@b{-no-trap}] 371104834Sobrien [@b{-mfix7000}] [@b{-mno-fix7000}] 372104834Sobrien [@b{-mips16}] [@b{-no-mips16}] 373218822Sdim [@b{-msmartmips}] [@b{-mno-smartmips}] 374104834Sobrien [@b{-mips3d}] [@b{-no-mips3d}] 375104834Sobrien [@b{-mdmx}] [@b{-no-mdmx}] 376218822Sdim [@b{-mdsp}] [@b{-mno-dsp}] 377218822Sdim [@b{-mdspr2}] [@b{-mno-dspr2}] 378218822Sdim [@b{-mmt}] [@b{-mno-mt}] 379104834Sobrien [@b{-mdebug}] [@b{-no-mdebug}] 380130561Sobrien [@b{-mpdr}] [@b{-mno-pdr}] 38133965Sjdp@end ifset 38289857Sobrien@ifset MMIX 38389857Sobrien 38489857Sobrien@emph{Target MMIX options:} 38589857Sobrien [@b{--fixed-special-register-names}] [@b{--globalize-symbols}] 38689857Sobrien [@b{--gnu-syntax}] [@b{--relax}] [@b{--no-predefined-symbols}] 38789857Sobrien [@b{--no-expand}] [@b{--no-merge-gregs}] [@b{-x}] 38891041Sobrien [@b{--linker-allocated-gregs}] 38989857Sobrien@end ifset 39089857Sobrien@ifset PDP11 39189857Sobrien 39289857Sobrien@emph{Target PDP11 options:} 39389857Sobrien [@b{-mpic}|@b{-mno-pic}] [@b{-mall}] [@b{-mno-extensions}] 39489857Sobrien [@b{-m}@var{extension}|@b{-mno-}@var{extension}] 39589857Sobrien [@b{-m}@var{cpu}] [@b{-m}@var{machine}] 39689857Sobrien@end ifset 39789857Sobrien@ifset PJ 39889857Sobrien 39989857Sobrien@emph{Target picoJava options:} 40089857Sobrien [@b{-mb}|@b{-me}] 40189857Sobrien@end ifset 40289857Sobrien@ifset PPC 40389857Sobrien 40489857Sobrien@emph{Target PowerPC options:} 40589857Sobrien [@b{-mpwrx}|@b{-mpwr2}|@b{-mpwr}|@b{-m601}|@b{-mppc}|@b{-mppc32}|@b{-m603}|@b{-m604}| 40689857Sobrien @b{-m403}|@b{-m405}|@b{-mppc64}|@b{-m620}|@b{-mppc64bridge}|@b{-mbooke}| 40789857Sobrien @b{-mbooke32}|@b{-mbooke64}] 40889857Sobrien [@b{-mcom}|@b{-many}|@b{-maltivec}] [@b{-memb}] 40989857Sobrien [@b{-mregnames}|@b{-mno-regnames}] 41089857Sobrien [@b{-mrelocatable}|@b{-mrelocatable-lib}] 41189857Sobrien [@b{-mlittle}|@b{-mlittle-endian}|@b{-mbig}|@b{-mbig-endian}] 41289857Sobrien [@b{-msolaris}|@b{-mno-solaris}] 41389857Sobrien@end ifset 41489857Sobrien@ifset SPARC 41589857Sobrien 41689857Sobrien@emph{Target SPARC options:} 41789857Sobrien@c The order here is important. See c-sparc.texi. 41889857Sobrien [@b{-Av6}|@b{-Av7}|@b{-Av8}|@b{-Asparclet}|@b{-Asparclite} 41989857Sobrien @b{-Av8plus}|@b{-Av8plusa}|@b{-Av9}|@b{-Av9a}] 42089857Sobrien [@b{-xarch=v8plus}|@b{-xarch=v8plusa}] [@b{-bump}] 42189857Sobrien [@b{-32}|@b{-64}] 42289857Sobrien@end ifset 42389857Sobrien@ifset TIC54X 42489857Sobrien 42589857Sobrien@emph{Target TIC54X options:} 42689857Sobrien [@b{-mcpu=54[123589]}|@b{-mcpu=54[56]lp}] [@b{-mfar-mode}|@b{-mf}] 42789857Sobrien [@b{-merrors-to-file} @var{<filename>}|@b{-me} @var{<filename>}] 42889857Sobrien@end ifset 429218822Sdim 430218822Sdim@ifset Z80 431218822Sdim 432218822Sdim@emph{Target Z80 options:} 433218822Sdim [@b{-z80}] [@b{-r800}] 434218822Sdim [@b{ -ignore-undocumented-instructions}] [@b{-Wnud}] 435218822Sdim [@b{ -ignore-unportable-instructions}] [@b{-Wnup}] 436218822Sdim [@b{ -warn-undocumented-instructions}] [@b{-Wud}] 437218822Sdim [@b{ -warn-unportable-instructions}] [@b{-Wup}] 438218822Sdim [@b{ -forbid-undocumented-instructions}] [@b{-Fud}] 439218822Sdim [@b{ -forbid-unportable-instructions}] [@b{-Fup}] 440218822Sdim@end ifset 441218822Sdim 44289857Sobrien@ifset Z8000 44389857Sobrien@c Z8000 has no machine-dependent assembler options 44489857Sobrien@end ifset 445130561Sobrien@ifset XTENSA 446130561Sobrien 447130561Sobrien@emph{Target Xtensa options:} 448218822Sdim [@b{--[no-]text-section-literals}] [@b{--[no-]absolute-literals}] 449130561Sobrien [@b{--[no-]target-align}] [@b{--[no-]longcalls}] 450218822Sdim [@b{--[no-]transform}] 451218822Sdim [@b{--rename-section} @var{oldname}=@var{newname}] 452130561Sobrien@end ifset 45389857Sobrien@c man end 45433965Sjdp@end smallexample 45533965Sjdp 45689857Sobrien@c man begin OPTIONS 45789857Sobrien 45889857Sobrien@table @gcctabopt 459218822Sdim@include at-file.texi 460218822Sdim 46138889Sjdp@item -a[cdhlmns] 46233965SjdpTurn on listings, in any of a variety of ways: 46333965Sjdp 46489857Sobrien@table @gcctabopt 46538889Sjdp@item -ac 46638889Sjdpomit false conditionals 46738889Sjdp 46833965Sjdp@item -ad 46933965Sjdpomit debugging directives 47033965Sjdp 47133965Sjdp@item -ah 47233965Sjdpinclude high-level source 47333965Sjdp 47433965Sjdp@item -al 47533965Sjdpinclude assembly 47633965Sjdp 47738889Sjdp@item -am 47838889Sjdpinclude macro expansions 47938889Sjdp 48033965Sjdp@item -an 48133965Sjdpomit forms processing 48233965Sjdp 48333965Sjdp@item -as 48433965Sjdpinclude symbols 48533965Sjdp 48633965Sjdp@item =file 48733965Sjdpset the name of the listing file 48833965Sjdp@end table 48933965Sjdp 49033965SjdpYou may combine these options; for example, use @samp{-aln} for assembly 49133965Sjdplisting without forms processing. The @samp{=file} option, if used, must be 49238889Sjdpthe last one. By itself, @samp{-a} defaults to @samp{-ahls}. 49333965Sjdp 494218822Sdim@item --alternate 495218822SdimBegin in alternate macro mode. 496218822Sdim@ifclear man 497218822Sdim@xref{Altmacro,,@code{.altmacro}}. 498218822Sdim@end ifclear 499218822Sdim 50033965Sjdp@item -D 50133965SjdpIgnored. This option is accepted for script compatibility with calls to 50233965Sjdpother assemblers. 50333965Sjdp 50433965Sjdp@item --defsym @var{sym}=@var{value} 50533965SjdpDefine the symbol @var{sym} to be @var{value} before assembling the input file. 50633965Sjdp@var{value} must be an integer constant. As in C, a leading @samp{0x} 507218822Sdimindicates a hexadecimal value, and a leading @samp{0} indicates an octal 508218822Sdimvalue. The value of the symbol can be overridden inside a source file via the 509218822Sdimuse of a @code{.set} pseudo-op. 51033965Sjdp 51133965Sjdp@item -f 51233965Sjdp``fast''---skip whitespace and comment preprocessing (assume source is 51333965Sjdpcompiler output). 51433965Sjdp 515218822Sdim@item -g 516218822Sdim@itemx --gen-debug 517218822SdimGenerate debugging information for each assembler source line using whichever 518218822Sdimdebug format is preferred by the target. This currently means either STABS, 519218822SdimECOFF or DWARF2. 520218822Sdim 52138889Sjdp@item --gstabs 52238889SjdpGenerate stabs debugging information for each assembler line. This 52338889Sjdpmay help debugging assembler code, if the debugger can handle it. 52438889Sjdp 525130561Sobrien@item --gstabs+ 526130561SobrienGenerate stabs debugging information for each assembler line, with GNU 527130561Sobrienextensions that probably only gdb can handle, and that could make other 528130561Sobriendebuggers crash or refuse to read your program. This 529130561Sobrienmay help debugging assembler code. Currently the only GNU extension is 530130561Sobrienthe location of the current working directory at assembling time. 531130561Sobrien 532218822Sdim@item --gdwarf-2 53360484SobrienGenerate DWARF2 debugging information for each assembler line. This 534130561Sobrienmay help debugging assembler code, if the debugger can handle it. Note---this 53577298Sobrienoption is only supported by some targets, not all of them. 53660484Sobrien 53733965Sjdp@item --help 53833965SjdpPrint a summary of the command line options and exit. 53933965Sjdp 54077298Sobrien@item --target-help 54177298SobrienPrint a summary of all target specific options and exit. 54277298Sobrien 54333965Sjdp@item -I @var{dir} 54433965SjdpAdd directory @var{dir} to the search list for @code{.include} directives. 54533965Sjdp 54633965Sjdp@item -J 54733965SjdpDon't warn about signed overflow. 54833965Sjdp 54933965Sjdp@item -K 55033965Sjdp@ifclear DIFF-TBL-KLUGE 55133965SjdpThis option is accepted but has no effect on the @value{TARGET} family. 55233965Sjdp@end ifclear 55333965Sjdp@ifset DIFF-TBL-KLUGE 55433965SjdpIssue warnings when difference tables altered for long displacements. 55533965Sjdp@end ifset 55633965Sjdp 55733965Sjdp@item -L 55838889Sjdp@itemx --keep-locals 559218822SdimKeep (in the symbol table) local symbols. These symbols start with 560218822Sdimsystem-specific local label prefixes, typically @samp{.L} for ELF systems 561218822Sdimor @samp{L} for traditional a.out systems. 562218822Sdim@ifclear man 563218822Sdim@xref{Symbol Names}. 564218822Sdim@end ifclear 56533965Sjdp 56689857Sobrien@item --listing-lhs-width=@var{number} 56789857SobrienSet the maximum width, in words, of the output data column for an assembler 56889857Sobrienlisting to @var{number}. 56989857Sobrien 57089857Sobrien@item --listing-lhs-width2=@var{number} 57189857SobrienSet the maximum width, in words, of the output data column for continuation 57289857Sobrienlines in an assembler listing to @var{number}. 57389857Sobrien 57489857Sobrien@item --listing-rhs-width=@var{number} 57589857SobrienSet the maximum width of an input source line, as displayed in a listing, to 57689857Sobrien@var{number} bytes. 57789857Sobrien 57889857Sobrien@item --listing-cont-lines=@var{number} 57989857SobrienSet the maximum number of lines printed in a listing for a single line of input 58089857Sobriento @var{number} + 1. 58189857Sobrien 58233965Sjdp@item -o @var{objfile} 58389857SobrienName the object-file output from @command{@value{AS}} @var{objfile}. 58433965Sjdp 58533965Sjdp@item -R 58633965SjdpFold the data section into the text section. 58733965Sjdp 588218822Sdim@kindex --hash-size=@var{number} 589218822SdimSet the default size of GAS's hash tables to a prime number close to 590218822Sdim@var{number}. Increasing this value can reduce the length of time it takes the 591218822Sdimassembler to perform its tasks, at the expense of increasing the assembler's 592218822Sdimmemory requirements. Similarly reducing this value can reduce the memory 593218822Sdimrequirements at the expense of speed. 594218822Sdim 595218822Sdim@item --reduce-memory-overheads 596218822SdimThis option reduces GAS's memory requirements, at the expense of making the 597218822Sdimassembly processes slower. Currently this switch is a synonym for 598218822Sdim@samp{--hash-size=4051}, but in the future it may have other effects as well. 599218822Sdim 60033965Sjdp@item --statistics 60133965SjdpPrint the maximum space (in bytes) and total time (in seconds) used by 60233965Sjdpassembly. 60333965Sjdp 60438889Sjdp@item --strip-local-absolute 60538889SjdpRemove local absolute symbols from the outgoing symbol table. 60638889Sjdp 60733965Sjdp@item -v 60833965Sjdp@itemx -version 60989857SobrienPrint the @command{as} version. 61033965Sjdp 61133965Sjdp@item --version 61289857SobrienPrint the @command{as} version and exit. 61333965Sjdp 61433965Sjdp@item -W 61560484Sobrien@itemx --no-warn 61633965SjdpSuppress warning messages. 61733965Sjdp 61860484Sobrien@item --fatal-warnings 61960484SobrienTreat warnings as errors. 62060484Sobrien 62160484Sobrien@item --warn 62260484SobrienDon't suppress warning messages or treat them as errors. 62360484Sobrien 62433965Sjdp@item -w 62533965SjdpIgnored. 62633965Sjdp 62733965Sjdp@item -x 62833965SjdpIgnored. 62933965Sjdp 63033965Sjdp@item -Z 63133965SjdpGenerate an object file even after errors. 63233965Sjdp 63333965Sjdp@item -- | @var{files} @dots{} 63433965SjdpStandard input, or source files to assemble. 63533965Sjdp 63633965Sjdp@end table 63733965Sjdp 63833965Sjdp@ifset ARC 63933965SjdpThe following options are available when @value{AS} is configured for 64033965Sjdpan ARC processor. 64133965Sjdp 64289857Sobrien@table @gcctabopt 64377298Sobrien@item -marc[5|6|7|8] 64477298SobrienThis option selects the core processor variant. 64577298Sobrien@item -EB | -EL 64677298SobrienSelect either big-endian (-EB) or little-endian (-EL) output. 64733965Sjdp@end table 64833965Sjdp@end ifset 64933965Sjdp 65038889Sjdp@ifset ARM 65138889SjdpThe following options are available when @value{AS} is configured for the ARM 65238889Sjdpprocessor family. 65338889Sjdp 65489857Sobrien@table @gcctabopt 65589857Sobrien@item -mcpu=@var{processor}[+@var{extension}@dots{}] 65660484SobrienSpecify which ARM processor variant is the target. 65789857Sobrien@item -march=@var{architecture}[+@var{extension}@dots{}] 65860484SobrienSpecify which ARM architecture variant is used by the target. 65989857Sobrien@item -mfpu=@var{floating-point-format} 66077298SobrienSelect which Floating Point architecture is the target. 661130561Sobrien@item -mfloat-abi=@var{abi} 662130561SobrienSelect which floating point ABI is in use. 66389857Sobrien@item -mthumb 66489857SobrienEnable Thumb only instruction decoding. 665218822Sdim@item -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant 66638889SjdpSelect which procedure calling convention is in use. 66738889Sjdp@item -EB | -EL 66838889SjdpSelect either big-endian (-EB) or little-endian (-EL) output. 66960484Sobrien@item -mthumb-interwork 67060484SobrienSpecify that the code has been generated with interworking between Thumb and 67160484SobrienARM code in mind. 67260484Sobrien@item -k 67360484SobrienSpecify that PIC code has been generated. 67438889Sjdp@end table 67538889Sjdp@end ifset 67638889Sjdp 67791041Sobrien@ifset CRIS 67891041SobrienSee the info pages for documentation of the CRIS-specific options. 67991041Sobrien@end ifset 68091041Sobrien 68133965Sjdp@ifset D10V 68233965SjdpThe following options are available when @value{AS} is configured for 68333965Sjdpa D10V processor. 68489857Sobrien@table @gcctabopt 68533965Sjdp@cindex D10V optimization 68633965Sjdp@cindex optimization, D10V 68733965Sjdp@item -O 68833965SjdpOptimize output by parallelizing instructions. 68933965Sjdp@end table 69033965Sjdp@end ifset 69133965Sjdp 69260484Sobrien@ifset D30V 69360484SobrienThe following options are available when @value{AS} is configured for a D30V 69460484Sobrienprocessor. 69589857Sobrien@table @gcctabopt 69660484Sobrien@cindex D30V optimization 69760484Sobrien@cindex optimization, D30V 69860484Sobrien@item -O 69960484SobrienOptimize output by parallelizing instructions. 70038889Sjdp 70160484Sobrien@cindex D30V nops 70260484Sobrien@item -n 70360484SobrienWarn when nops are generated. 70460484Sobrien 70560484Sobrien@cindex D30V nops after 32-bit multiply 70660484Sobrien@item -N 70760484SobrienWarn when a nop after a 32-bit multiply instruction is generated. 70860484Sobrien@end table 70960484Sobrien@end ifset 71060484Sobrien 71133965Sjdp@ifset I960 71233965SjdpThe following options are available when @value{AS} is configured for the 71333965SjdpIntel 80960 processor. 71433965Sjdp 71589857Sobrien@table @gcctabopt 71633965Sjdp@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC 71733965SjdpSpecify which variant of the 960 architecture is the target. 71833965Sjdp 71933965Sjdp@item -b 72033965SjdpAdd code to collect statistics about branches taken. 72133965Sjdp 72233965Sjdp@item -no-relax 72333965SjdpDo not alter compare-and-branch instructions for long displacements; 72433965Sjdperror if necessary. 72533965Sjdp 72633965Sjdp@end table 72733965Sjdp@end ifset 72833965Sjdp 729130561Sobrien@ifset IP2K 730130561SobrienThe following options are available when @value{AS} is configured for the 731130561SobrienUbicom IP2K series. 732130561Sobrien 733130561Sobrien@table @gcctabopt 734130561Sobrien 735130561Sobrien@item -mip2022ext 736130561SobrienSpecifies that the extended IP2022 instructions are allowed. 737130561Sobrien 738130561Sobrien@item -mip2022 739130561SobrienRestores the default behaviour, which restricts the permitted instructions to 740130561Sobrienjust the basic IP2022 ones. 741130561Sobrien 742130561Sobrien@end table 743130561Sobrien@end ifset 744130561Sobrien 745218822Sdim@ifset M32C 746218822SdimThe following options are available when @value{AS} is configured for the 747218822SdimRenesas M32C and M16C processors. 748218822Sdim 749218822Sdim@table @gcctabopt 750218822Sdim 751218822Sdim@item -m32c 752218822SdimAssemble M32C instructions. 753218822Sdim 754218822Sdim@item -m16c 755218822SdimAssemble M16C instructions (the default). 756218822Sdim 757218822Sdim@end table 758218822Sdim@end ifset 759218822Sdim 76077298Sobrien@ifset M32R 76177298SobrienThe following options are available when @value{AS} is configured for the 762130561SobrienRenesas M32R (formerly Mitsubishi M32R) series. 76338889Sjdp 76489857Sobrien@table @gcctabopt 76577298Sobrien 76677298Sobrien@item --m32rx 76777298SobrienSpecify which processor in the M32R family is the target. The default 76877298Sobrienis normally the M32R, but this option changes it to the M32RX. 76977298Sobrien 77077298Sobrien@item --warn-explicit-parallel-conflicts or --Wp 77177298SobrienProduce warning messages when questionable parallel constructs are 77277298Sobrienencountered. 77377298Sobrien 77477298Sobrien@item --no-warn-explicit-parallel-conflicts or --Wnp 77577298SobrienDo not produce warning messages when questionable parallel constructs are 77677298Sobrienencountered. 77777298Sobrien 77877298Sobrien@end table 77977298Sobrien@end ifset 78077298Sobrien 78133965Sjdp@ifset M680X0 78233965SjdpThe following options are available when @value{AS} is configured for the 78333965SjdpMotorola 68000 series. 78433965Sjdp 78589857Sobrien@table @gcctabopt 78633965Sjdp 78733965Sjdp@item -l 78833965SjdpShorten references to undefined symbols, to one word instead of two. 78933965Sjdp 79089857Sobrien@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 79189857Sobrien@itemx | -m68040 | -m68060 | -m68302 | -m68331 | -m68332 79289857Sobrien@itemx | -m68333 | -m68340 | -mcpu32 | -m5200 79333965SjdpSpecify what processor in the 68000 family is the target. The default 79433965Sjdpis normally the 68020, but this can be changed at configuration time. 79533965Sjdp 79633965Sjdp@item -m68881 | -m68882 | -mno-68881 | -mno-68882 79733965SjdpThe target machine does (or does not) have a floating-point coprocessor. 79833965SjdpThe default is to assume a coprocessor for 68020, 68030, and cpu32. Although 79933965Sjdpthe basic 68000 is not compatible with the 68881, a combination of the 80033965Sjdptwo can be specified, since it's possible to do emulation of the 80133965Sjdpcoprocessor instructions with the main processor. 80233965Sjdp 80333965Sjdp@item -m68851 | -mno-68851 80433965SjdpThe target machine does (or does not) have a memory-management 80533965Sjdpunit coprocessor. The default is to assume an MMU for 68020 and up. 80633965Sjdp 80733965Sjdp@end table 80833965Sjdp@end ifset 80933965Sjdp 81089857Sobrien@ifset PDP11 81189857Sobrien 81289857SobrienFor details about the PDP-11 machine dependent features options, 81389857Sobriensee @ref{PDP-11-Options}. 81489857Sobrien 81589857Sobrien@table @gcctabopt 81689857Sobrien@item -mpic | -mno-pic 81789857SobrienGenerate position-independent (or position-dependent) code. The 81889857Sobriendefault is @option{-mpic}. 81989857Sobrien 82089857Sobrien@item -mall 82189857Sobrien@itemx -mall-extensions 82289857SobrienEnable all instruction set extensions. This is the default. 82389857Sobrien 82489857Sobrien@item -mno-extensions 82589857SobrienDisable all instruction set extensions. 82689857Sobrien 82789857Sobrien@item -m@var{extension} | -mno-@var{extension} 82889857SobrienEnable (or disable) a particular instruction set extension. 82989857Sobrien 83089857Sobrien@item -m@var{cpu} 83189857SobrienEnable the instruction set extensions supported by a particular CPU, and 83289857Sobriendisable all other extensions. 83389857Sobrien 83489857Sobrien@item -m@var{machine} 83589857SobrienEnable the instruction set extensions supported by a particular machine 83689857Sobrienmodel, and disable all other extensions. 83789857Sobrien@end table 83889857Sobrien 83989857Sobrien@end ifset 84089857Sobrien 84160484Sobrien@ifset PJ 84260484SobrienThe following options are available when @value{AS} is configured for 84360484Sobriena picoJava processor. 84460484Sobrien 84589857Sobrien@table @gcctabopt 84660484Sobrien 84760484Sobrien@cindex PJ endianness 84860484Sobrien@cindex endianness, PJ 84960484Sobrien@cindex big endian output, PJ 85060484Sobrien@item -mb 85160484SobrienGenerate ``big endian'' format output. 85260484Sobrien 85360484Sobrien@cindex little endian output, PJ 85460484Sobrien@item -ml 85560484SobrienGenerate ``little endian'' format output. 85660484Sobrien 85760484Sobrien@end table 85860484Sobrien@end ifset 85960484Sobrien 86077298Sobrien@ifset M68HC11 86177298SobrienThe following options are available when @value{AS} is configured for the 86277298SobrienMotorola 68HC11 or 68HC12 series. 86360484Sobrien 86489857Sobrien@table @gcctabopt 86577298Sobrien 866130561Sobrien@item -m68hc11 | -m68hc12 | -m68hcs12 86777298SobrienSpecify what processor is the target. The default is 86877298Sobriendefined by the configuration option when building the assembler. 86977298Sobrien 870130561Sobrien@item -mshort 871130561SobrienSpecify to use the 16-bit integer ABI. 872130561Sobrien 873130561Sobrien@item -mlong 874130561SobrienSpecify to use the 32-bit integer ABI. 875130561Sobrien 876130561Sobrien@item -mshort-double 877130561SobrienSpecify to use the 32-bit double ABI. 878130561Sobrien 879130561Sobrien@item -mlong-double 880130561SobrienSpecify to use the 64-bit double ABI. 881130561Sobrien 882218822Sdim@item --force-long-branches 88377298SobrienRelative branches are turned into absolute ones. This concerns 88477298Sobrienconditional branches, unconditional branches and branches to a 88577298Sobriensub routine. 88677298Sobrien 887218822Sdim@item -S | --short-branches 888218822SdimDo not turn relative branches into absolute ones 88977298Sobrienwhen the offset is out of range. 89077298Sobrien 89177298Sobrien@item --strict-direct-mode 89277298SobrienDo not turn the direct addressing mode into extended addressing mode 89377298Sobrienwhen the instruction does not support direct addressing mode. 89477298Sobrien 89577298Sobrien@item --print-insn-syntax 89677298SobrienPrint the syntax of instruction in case of error. 89777298Sobrien 89877298Sobrien@item --print-opcodes 89977298Sobrienprint the list of instructions with syntax and then exit. 90077298Sobrien 90177298Sobrien@item --generate-example 90277298Sobrienprint an example of instruction for each possible instruction and then exit. 90389857SobrienThis option is only useful for testing @command{@value{AS}}. 90477298Sobrien 90577298Sobrien@end table 90677298Sobrien@end ifset 90777298Sobrien 90833965Sjdp@ifset SPARC 90989857SobrienThe following options are available when @command{@value{AS}} is configured 91033965Sjdpfor the SPARC architecture: 91133965Sjdp 91289857Sobrien@table @gcctabopt 91338889Sjdp@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite 91438889Sjdp@itemx -Av8plus | -Av8plusa | -Av9 | -Av9a 91533965SjdpExplicitly select a variant of the SPARC architecture. 91633965Sjdp 91738889Sjdp@samp{-Av8plus} and @samp{-Av8plusa} select a 32 bit environment. 91838889Sjdp@samp{-Av9} and @samp{-Av9a} select a 64 bit environment. 91938889Sjdp 92038889Sjdp@samp{-Av8plusa} and @samp{-Av9a} enable the SPARC V9 instruction set with 92138889SjdpUltraSPARC extensions. 92238889Sjdp 92333965Sjdp@item -xarch=v8plus | -xarch=v8plusa 92433965SjdpFor compatibility with the Solaris v9 assembler. These options are 92538889Sjdpequivalent to -Av8plus and -Av8plusa, respectively. 92633965Sjdp 92733965Sjdp@item -bump 92833965SjdpWarn when the assembler switches to another architecture. 92933965Sjdp@end table 93033965Sjdp@end ifset 93133965Sjdp 93277298Sobrien@ifset TIC54X 93377298SobrienThe following options are available when @value{AS} is configured for the 'c54x 93477298Sobrienarchitecture. 93577298Sobrien 93689857Sobrien@table @gcctabopt 93777298Sobrien@item -mfar-mode 93877298SobrienEnable extended addressing mode. All addresses and relocations will assume 93977298Sobrienextended addressing (usually 23 bits). 94077298Sobrien@item -mcpu=@var{CPU_VERSION} 94177298SobrienSets the CPU version being compiled for. 94277298Sobrien@item -merrors-to-file @var{FILENAME} 94377298SobrienRedirect error output to a file, for broken systems which don't support such 94477298Sobrienbehaviour in the shell. 94577298Sobrien@end table 94677298Sobrien@end ifset 94777298Sobrien 94833965Sjdp@ifset MIPS 94933965SjdpThe following options are available when @value{AS} is configured for 950104834Sobriena @sc{mips} processor. 95133965Sjdp 95289857Sobrien@table @gcctabopt 95333965Sjdp@item -G @var{num} 95433965SjdpThis option sets the largest size of an object that can be referenced 95533965Sjdpimplicitly with the @code{gp} register. It is only accepted for targets that 95633965Sjdpuse ECOFF format, such as a DECstation running Ultrix. The default value is 8. 95733965Sjdp 95833965Sjdp@cindex MIPS endianness 95933965Sjdp@cindex endianness, MIPS 96033965Sjdp@cindex big endian output, MIPS 96133965Sjdp@item -EB 96233965SjdpGenerate ``big endian'' format output. 96333965Sjdp 96433965Sjdp@cindex little endian output, MIPS 96533965Sjdp@item -EL 96633965SjdpGenerate ``little endian'' format output. 96733965Sjdp 96833965Sjdp@cindex MIPS ISA 96933965Sjdp@item -mips1 97033965Sjdp@itemx -mips2 97133965Sjdp@itemx -mips3 97277298Sobrien@itemx -mips4 973104834Sobrien@itemx -mips5 97477298Sobrien@itemx -mips32 975130561Sobrien@itemx -mips32r2 97689857Sobrien@itemx -mips64 977130561Sobrien@itemx -mips64r2 978104834SobrienGenerate code for a particular @sc{mips} Instruction Set Architecture level. 979104834Sobrien@samp{-mips1} is an alias for @samp{-march=r3000}, @samp{-mips2} is an 980104834Sobrienalias for @samp{-march=r6000}, @samp{-mips3} is an alias for 981104834Sobrien@samp{-march=r4000} and @samp{-mips4} is an alias for @samp{-march=r8000}. 982130561Sobrien@samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, @samp{-mips64}, and 983130561Sobrien@samp{-mips64r2} 984130561Sobriencorrespond to generic 985130561Sobrien@samp{MIPS V}, @samp{MIPS32}, @samp{MIPS32 Release 2}, @samp{MIPS64}, 986130561Sobrienand @samp{MIPS64 Release 2} 987130561SobrienISA processors, respectively. 98833965Sjdp 989104834Sobrien@item -march=@var{CPU} 990104834SobrienGenerate code for a particular @sc{mips} cpu. 99133965Sjdp 992104834Sobrien@item -mtune=@var{cpu} 993104834SobrienSchedule and tune for a particular @sc{mips} cpu. 99433965Sjdp 995104834Sobrien@item -mfix7000 996104834Sobrien@itemx -mno-fix7000 997104834SobrienCause nops to be inserted if the read of the destination register 998104834Sobrienof an mfhi or mflo instruction occurs in the following two instructions. 999104834Sobrien 1000104834Sobrien@item -mdebug 1001104834Sobrien@itemx -no-mdebug 1002104834SobrienCause stabs-style debugging output to go into an ECOFF-style .mdebug 1003104834Sobriensection instead of the standard ELF .stabs sections. 1004104834Sobrien 1005130561Sobrien@item -mpdr 1006130561Sobrien@itemx -mno-pdr 1007130561SobrienControl generation of @code{.pdr} sections. 1008130561Sobrien 1009104834Sobrien@item -mgp32 1010104834Sobrien@itemx -mfp32 1011104834SobrienThe register sizes are normally inferred from the ISA and ABI, but these 1012104834Sobrienflags force a certain group of registers to be treated as 32 bits wide at 1013104834Sobrienall times. @samp{-mgp32} controls the size of general-purpose registers 1014104834Sobrienand @samp{-mfp32} controls the size of floating-point registers. 1015104834Sobrien 1016104834Sobrien@item -mips16 1017104834Sobrien@itemx -no-mips16 1018104834SobrienGenerate code for the MIPS 16 processor. This is equivalent to putting 1019104834Sobrien@code{.set mips16} at the start of the assembly file. @samp{-no-mips16} 1020104834Sobrienturns off this option. 1021104834Sobrien 1022218822Sdim@item -msmartmips 1023218822Sdim@itemx -mno-smartmips 1024218822SdimEnables the SmartMIPS extension to the MIPS32 instruction set. This is 1025218822Sdimequivalent to putting @code{.set smartmips} at the start of the assembly file. 1026218822Sdim@samp{-mno-smartmips} turns off this option. 1027218822Sdim 1028104834Sobrien@item -mips3d 1029104834Sobrien@itemx -no-mips3d 1030104834SobrienGenerate code for the MIPS-3D Application Specific Extension. 1031104834SobrienThis tells the assembler to accept MIPS-3D instructions. 1032104834Sobrien@samp{-no-mips3d} turns off this option. 1033104834Sobrien 1034104834Sobrien@item -mdmx 1035104834Sobrien@itemx -no-mdmx 1036104834SobrienGenerate code for the MDMX Application Specific Extension. 1037104834SobrienThis tells the assembler to accept MDMX instructions. 1038104834Sobrien@samp{-no-mdmx} turns off this option. 1039104834Sobrien 1040218822Sdim@item -mdsp 1041218822Sdim@itemx -mno-dsp 1042218822SdimGenerate code for the DSP Release 1 Application Specific Extension. 1043218822SdimThis tells the assembler to accept DSP Release 1 instructions. 1044218822Sdim@samp{-mno-dsp} turns off this option. 1045218822Sdim 1046218822Sdim@item -mdspr2 1047218822Sdim@itemx -mno-dspr2 1048218822SdimGenerate code for the DSP Release 2 Application Specific Extension. 1049218822SdimThis option implies -mdsp. 1050218822SdimThis tells the assembler to accept DSP Release 2 instructions. 1051218822Sdim@samp{-mno-dspr2} turns off this option. 1052218822Sdim 1053218822Sdim@item -mmt 1054218822Sdim@itemx -mno-mt 1055218822SdimGenerate code for the MT Application Specific Extension. 1056218822SdimThis tells the assembler to accept MT instructions. 1057218822Sdim@samp{-mno-mt} turns off this option. 1058218822Sdim 1059104834Sobrien@item --construct-floats 1060104834Sobrien@itemx --no-construct-floats 1061104834SobrienThe @samp{--no-construct-floats} option disables the construction of 1062104834Sobriendouble width floating point constants by loading the two halves of the 1063104834Sobrienvalue into the two single width floating point registers that make up 1064104834Sobrienthe double width register. By default @samp{--construct-floats} is 1065104834Sobrienselected, allowing construction of these floating point constants. 1066104834Sobrien 106733965Sjdp@cindex emulation 106833965Sjdp@item --emulation=@var{name} 106989857SobrienThis option causes @command{@value{AS}} to emulate @command{@value{AS}} configured 107033965Sjdpfor some other target, in all respects, including output format (choosing 107133965Sjdpbetween ELF and ECOFF only), handling of pseudo-opcodes which may generate 107233965Sjdpdebugging information or store symbol table information, and default 107333965Sjdpendianness. The available configuration names are: @samp{mipsecoff}, 107433965Sjdp@samp{mipself}, @samp{mipslecoff}, @samp{mipsbecoff}, @samp{mipslelf}, 107533965Sjdp@samp{mipsbelf}. The first two do not alter the default endianness from that 107633965Sjdpof the primary target for which the assembler was configured; the others change 107733965Sjdpthe default to little- or big-endian as indicated by the @samp{b} or @samp{l} 107833965Sjdpin the name. Using @samp{-EB} or @samp{-EL} will override the endianness 107933965Sjdpselection in any case. 108033965Sjdp 108133965SjdpThis option is currently supported only when the primary target 1082104834Sobrien@command{@value{AS}} is configured for is a @sc{mips} ELF or ECOFF target. 108333965SjdpFurthermore, the primary target or others specified with 108433965Sjdp@samp{--enable-targets=@dots{}} at configuration time must include support for 108533965Sjdpthe other format, if both are to be available. For example, the Irix 5 108633965Sjdpconfiguration includes support for both. 108733965Sjdp 108833965SjdpEventually, this option will support more configurations, with more 108933965Sjdpfine-grained control over the assembler's behavior, and will be supported for 109033965Sjdpmore processors. 109133965Sjdp 109233965Sjdp@item -nocpp 109389857Sobrien@command{@value{AS}} ignores this option. It is accepted for compatibility with 109433965Sjdpthe native tools. 109533965Sjdp 109633965Sjdp@item --trap 109733965Sjdp@itemx --no-trap 109833965Sjdp@itemx --break 109933965Sjdp@itemx --no-break 110033965SjdpControl how to deal with multiplication overflow and division by zero. 110133965Sjdp@samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception 110233965Sjdp(and only work for Instruction Set Architecture level 2 and higher); 110333965Sjdp@samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a 110433965Sjdpbreak exception. 110589857Sobrien 110689857Sobrien@item -n 110789857SobrienWhen this option is used, @command{@value{AS}} will issue a warning every 110889857Sobrientime it generates a nop instruction from a macro. 110933965Sjdp@end table 111033965Sjdp@end ifset 111133965Sjdp 111260484Sobrien@ifset MCORE 111360484SobrienThe following options are available when @value{AS} is configured for 111460484Sobrienan MCore processor. 111560484Sobrien 111689857Sobrien@table @gcctabopt 111760484Sobrien@item -jsri2bsr 111860484Sobrien@itemx -nojsri2bsr 111960484SobrienEnable or disable the JSRI to BSR transformation. By default this is enabled. 112060484SobrienThe command line option @samp{-nojsri2bsr} can be used to disable it. 112160484Sobrien 112260484Sobrien@item -sifilter 112360484Sobrien@itemx -nosifilter 112460484SobrienEnable or disable the silicon filter behaviour. By default this is disabled. 112577298SobrienThe default can be overridden by the @samp{-sifilter} command line option. 112660484Sobrien 112760484Sobrien@item -relax 112860484SobrienAlter jump instructions for long displacements. 112960484Sobrien 113077298Sobrien@item -mcpu=[210|340] 113177298SobrienSelect the cpu type on the target hardware. This controls which instructions 113277298Sobriencan be assembled. 113360484Sobrien 113477298Sobrien@item -EB 113577298SobrienAssemble for a big endian target. 113677298Sobrien 113777298Sobrien@item -EL 113877298SobrienAssemble for a little endian target. 113977298Sobrien 114060484Sobrien@end table 114160484Sobrien@end ifset 114260484Sobrien 114389857Sobrien@ifset MMIX 114489857SobrienSee the info pages for documentation of the MMIX-specific options. 114589857Sobrien@end ifset 114689857Sobrien 1147130561Sobrien@ifset XTENSA 1148130561SobrienThe following options are available when @value{AS} is configured for 1149130561Sobrienan Xtensa processor. 1150130561Sobrien 1151130561Sobrien@table @gcctabopt 1152130561Sobrien@item --text-section-literals | --no-text-section-literals 1153130561SobrienWith @option{--text-@-section-@-literals}, literal pools are interspersed 1154130561Sobrienin the text section. The default is 1155130561Sobrien@option{--no-@-text-@-section-@-literals}, which places literals in a 1156218822Sdimseparate section in the output file. These options only affect literals 1157218822Sdimreferenced via PC-relative @code{L32R} instructions; literals for 1158218822Sdimabsolute mode @code{L32R} instructions are handled separately. 1159130561Sobrien 1160218822Sdim@item --absolute-literals | --no-absolute-literals 1161218822SdimIndicate to the assembler whether @code{L32R} instructions use absolute 1162218822Sdimor PC-relative addressing. The default is to assume absolute addressing 1163218822Sdimif the Xtensa processor includes the absolute @code{L32R} addressing 1164218822Sdimoption. Otherwise, only the PC-relative @code{L32R} mode can be used. 1165218822Sdim 1166130561Sobrien@item --target-align | --no-target-align 1167130561SobrienEnable or disable automatic alignment to reduce branch penalties at the 1168130561Sobrienexpense of some code density. The default is @option{--target-@-align}. 1169130561Sobrien 1170130561Sobrien@item --longcalls | --no-longcalls 1171130561SobrienEnable or disable transformation of call instructions to allow calls 1172130561Sobrienacross a greater range of addresses. The default is 1173130561Sobrien@option{--no-@-longcalls}. 1174218822Sdim 1175218822Sdim@item --transform | --no-transform 1176218822SdimEnable or disable all assembler transformations of Xtensa instructions. 1177218822SdimThe default is @option{--transform}; 1178218822Sdim@option{--no-transform} should be used only in the rare cases when the 1179218822Sdiminstructions must be exactly as specified in the assembly source. 1180130561Sobrien@end table 1181130561Sobrien@end ifset 1182130561Sobrien 1183218822Sdim@ifset Z80 1184218822SdimThe following options are available when @value{AS} is configured for 1185218822Sdima Z80 family processor. 1186218822Sdim@table @gcctabopt 1187218822Sdim@item -z80 1188218822SdimAssemble for Z80 processor. 1189218822Sdim@item -r800 1190218822SdimAssemble for R800 processor. 1191218822Sdim@item -ignore-undocumented-instructions 1192218822Sdim@itemx -Wnud 1193218822SdimAssemble undocumented Z80 instructions that also work on R800 without warning. 1194218822Sdim@item -ignore-unportable-instructions 1195218822Sdim@itemx -Wnup 1196218822SdimAssemble all undocumented Z80 instructions without warning. 1197218822Sdim@item -warn-undocumented-instructions 1198218822Sdim@itemx -Wud 1199218822SdimIssue a warning for undocumented Z80 instructions that also work on R800. 1200218822Sdim@item -warn-unportable-instructions 1201218822Sdim@itemx -Wup 1202218822SdimIssue a warning for undocumented Z80 instructions that do not work on R800. 1203218822Sdim@item -forbid-undocumented-instructions 1204218822Sdim@itemx -Fud 1205218822SdimTreat all undocumented instructions as errors. 1206218822Sdim@item -forbid-unportable-instructions 1207218822Sdim@itemx -Fup 1208218822SdimTreat undocumented Z80 instructions that do not work on R800 as errors. 1209218822Sdim@end table 1210218822Sdim@end ifset 1211218822Sdim 121289857Sobrien@c man end 121389857Sobrien 121433965Sjdp@menu 121533965Sjdp* Manual:: Structure of this Manual 121633965Sjdp* GNU Assembler:: The GNU Assembler 121733965Sjdp* Object Formats:: Object File Formats 121833965Sjdp* Command Line:: Command Line 121933965Sjdp* Input Files:: Input Files 122033965Sjdp* Object:: Output (Object) File 122133965Sjdp* Errors:: Error and Warning Messages 122233965Sjdp@end menu 122333965Sjdp 122433965Sjdp@node Manual 122533965Sjdp@section Structure of this Manual 122633965Sjdp 122733965Sjdp@cindex manual, structure and purpose 122833965SjdpThis manual is intended to describe what you need to know to use 122989857Sobrien@sc{gnu} @command{@value{AS}}. We cover the syntax expected in source files, including 123033965Sjdpnotation for symbols, constants, and expressions; the directives that 123189857Sobrien@command{@value{AS}} understands; and of course how to invoke @command{@value{AS}}. 123233965Sjdp 123333965Sjdp@ifclear GENERIC 123433965SjdpWe also cover special features in the @value{TARGET} 123589857Sobrienconfiguration of @command{@value{AS}}, including assembler directives. 123633965Sjdp@end ifclear 123733965Sjdp@ifset GENERIC 123833965SjdpThis manual also describes some of the machine-dependent features of 123933965Sjdpvarious flavors of the assembler. 124033965Sjdp@end ifset 124133965Sjdp 124233965Sjdp@cindex machine instructions (not covered) 124333965SjdpOn the other hand, this manual is @emph{not} intended as an introduction 124433965Sjdpto programming in assembly language---let alone programming in general! 124533965SjdpIn a similar vein, we make no attempt to introduce the machine 124633965Sjdparchitecture; we do @emph{not} describe the instruction set, standard 124733965Sjdpmnemonics, registers or addressing modes that are standard to a 124833965Sjdpparticular architecture. 124933965Sjdp@ifset GENERIC 125033965SjdpYou may want to consult the manufacturer's 125133965Sjdpmachine architecture manual for this information. 125233965Sjdp@end ifset 125333965Sjdp@ifclear GENERIC 125433965Sjdp@ifset H8/300 125533965SjdpFor information on the H8/300 machine instruction set, see @cite{H8/300 1256130561SobrienSeries Programming Manual}. For the H8/300H, see @cite{H8/300H Series 1257130561SobrienProgramming Manual} (Renesas). 125833965Sjdp@end ifset 125933965Sjdp@ifset SH 1260130561SobrienFor information on the Renesas (formerly Hitachi) / SuperH SH machine instruction set, 1261130561Sobriensee @cite{SH-Microcomputer User's Manual} (Renesas) or 1262130561Sobrien@cite{SH-4 32-bit CPU Core Architecture} (SuperH) and 1263130561Sobrien@cite{SuperH (SH) 64-Bit RISC Series} (SuperH). 126433965Sjdp@end ifset 126533965Sjdp@ifset Z8000 126633965SjdpFor information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual} 126733965Sjdp@end ifset 126833965Sjdp@end ifclear 126933965Sjdp 127033965Sjdp@c I think this is premature---doc@cygnus.com, 17jan1991 127133965Sjdp@ignore 127233965SjdpThroughout this manual, we assume that you are running @dfn{GNU}, 127333965Sjdpthe portable operating system from the @dfn{Free Software 127433965SjdpFoundation, Inc.}. This restricts our attention to certain kinds of 127533965Sjdpcomputer (in particular, the kinds of computers that @sc{gnu} can run on); 127633965Sjdponce this assumption is granted examples and definitions need less 127733965Sjdpqualification. 127833965Sjdp 127989857Sobrien@command{@value{AS}} is part of a team of programs that turn a high-level 128033965Sjdphuman-readable series of instructions into a low-level 128133965Sjdpcomputer-readable series of instructions. Different versions of 128289857Sobrien@command{@value{AS}} are used for different kinds of computer. 128333965Sjdp@end ignore 128433965Sjdp 128533965Sjdp@c There used to be a section "Terminology" here, which defined 128633965Sjdp@c "contents", "byte", "word", and "long". Defining "word" to any 128733965Sjdp@c particular size is confusing when the .word directive may generate 16 128833965Sjdp@c bits on one machine and 32 bits on another; in general, for the user 128933965Sjdp@c version of this manual, none of these terms seem essential to define. 129033965Sjdp@c They were used very little even in the former draft of the manual; 129133965Sjdp@c this draft makes an effort to avoid them (except in names of 129233965Sjdp@c directives). 129333965Sjdp 129433965Sjdp@node GNU Assembler 129533965Sjdp@section The GNU Assembler 129633965Sjdp 129789857Sobrien@c man begin DESCRIPTION 129889857Sobrien 129989857Sobrien@sc{gnu} @command{as} is really a family of assemblers. 130033965Sjdp@ifclear GENERIC 130189857SobrienThis manual describes @command{@value{AS}}, a member of that family which is 130233965Sjdpconfigured for the @value{TARGET} architectures. 130333965Sjdp@end ifclear 130433965SjdpIf you use (or have used) the @sc{gnu} assembler on one architecture, you 130533965Sjdpshould find a fairly similar environment when you use it on another 130633965Sjdparchitecture. Each version has much in common with the others, 130733965Sjdpincluding object file formats, most assembler directives (often called 130833965Sjdp@dfn{pseudo-ops}) and assembler syntax.@refill 130933965Sjdp 131033965Sjdp@cindex purpose of @sc{gnu} assembler 131189857Sobrien@command{@value{AS}} is primarily intended to assemble the output of the 131233965Sjdp@sc{gnu} C compiler @code{@value{GCC}} for use by the linker 131389857Sobrien@code{@value{LD}}. Nevertheless, we've tried to make @command{@value{AS}} 131433965Sjdpassemble correctly everything that other assemblers for the same 131533965Sjdpmachine would assemble. 131633965Sjdp@ifset VAX 131733965SjdpAny exceptions are documented explicitly (@pxref{Machine Dependencies}). 131833965Sjdp@end ifset 131933965Sjdp@ifset M680X0 132033965Sjdp@c This remark should appear in generic version of manual; assumption 132133965Sjdp@c here is that generic version sets M680x0. 132289857SobrienThis doesn't mean @command{@value{AS}} always uses the same syntax as another 132333965Sjdpassembler for the same architecture; for example, we know of several 132433965Sjdpincompatible versions of 680x0 assembly language syntax. 132533965Sjdp@end ifset 132633965Sjdp 132789857Sobrien@c man end 132889857Sobrien 132989857SobrienUnlike older assemblers, @command{@value{AS}} is designed to assemble a source 133033965Sjdpprogram in one pass of the source file. This has a subtle impact on the 133133965Sjdp@kbd{.org} directive (@pxref{Org,,@code{.org}}). 133233965Sjdp 133333965Sjdp@node Object Formats 133433965Sjdp@section Object File Formats 133533965Sjdp 133633965Sjdp@cindex object file format 133733965SjdpThe @sc{gnu} assembler can be configured to produce several alternative 133833965Sjdpobject file formats. For the most part, this does not affect how you 133933965Sjdpwrite assembly language programs; but directives for debugging symbols 134033965Sjdpare typically different in different file formats. @xref{Symbol 134133965SjdpAttributes,,Symbol Attributes}. 134233965Sjdp@ifclear GENERIC 134333965Sjdp@ifclear MULTI-OBJ 1344130561SobrienFor the @value{TARGET} target, @command{@value{AS}} is configured to produce 134533965Sjdp@value{OBJ-NAME} format object files. 134633965Sjdp@end ifclear 134733965Sjdp@c The following should exhaust all configs that set MULTI-OBJ, ideally 134833965Sjdp@ifset I960 134989857SobrienOn the @value{TARGET}, @command{@value{AS}} can be configured to produce either 135033965Sjdp@code{b.out} or COFF format object files. 135133965Sjdp@end ifset 135233965Sjdp@ifset HPPA 135389857SobrienOn the @value{TARGET}, @command{@value{AS}} can be configured to produce either 135433965SjdpSOM or ELF format object files. 135533965Sjdp@end ifset 135633965Sjdp@end ifclear 135733965Sjdp 135833965Sjdp@node Command Line 135933965Sjdp@section Command Line 136033965Sjdp 136133965Sjdp@cindex command line conventions 136289857Sobrien 136389857SobrienAfter the program name @command{@value{AS}}, the command line may contain 136433965Sjdpoptions and file names. Options may appear in any order, and may be 136533965Sjdpbefore, after, or between file names. The order of file names is 136633965Sjdpsignificant. 136733965Sjdp 136833965Sjdp@cindex standard input, as input file 136933965Sjdp@kindex -- 137033965Sjdp@file{--} (two hyphens) by itself names the standard input file 137189857Sobrienexplicitly, as one of the files for @command{@value{AS}} to assemble. 137233965Sjdp 137333965Sjdp@cindex options, command line 137433965SjdpExcept for @samp{--} any command line argument that begins with a 137533965Sjdphyphen (@samp{-}) is an option. Each option changes the behavior of 137689857Sobrien@command{@value{AS}}. No option changes the way another option works. An 137733965Sjdpoption is a @samp{-} followed by one or more letters; the case of 137833965Sjdpthe letter is important. All options are optional. 137933965Sjdp 138033965SjdpSome options expect exactly one file name to follow them. The file 138133965Sjdpname may either immediately follow the option's letter (compatible 138233965Sjdpwith older assemblers) or it may be the next command argument (@sc{gnu} 138333965Sjdpstandard). These two command lines are equivalent: 138433965Sjdp 138533965Sjdp@smallexample 138633965Sjdp@value{AS} -o my-object-file.o mumble.s 138733965Sjdp@value{AS} -omy-object-file.o mumble.s 138833965Sjdp@end smallexample 138933965Sjdp 139033965Sjdp@node Input Files 139133965Sjdp@section Input Files 139233965Sjdp 139333965Sjdp@cindex input 139433965Sjdp@cindex source program 139533965Sjdp@cindex files, input 139633965SjdpWe use the phrase @dfn{source program}, abbreviated @dfn{source}, to 139789857Sobriendescribe the program input to one run of @command{@value{AS}}. The program may 139833965Sjdpbe in one or more files; how the source is partitioned into files 139933965Sjdpdoesn't change the meaning of the source. 140033965Sjdp 140133965Sjdp@c I added "con" prefix to "catenation" just to prove I can overcome my 140233965Sjdp@c APL training... doc@cygnus.com 140333965SjdpThe source program is a concatenation of the text in all the files, in the 140433965Sjdporder specified. 140533965Sjdp 140689857Sobrien@c man begin DESCRIPTION 140789857SobrienEach time you run @command{@value{AS}} it assembles exactly one source 140833965Sjdpprogram. The source program is made up of one or more files. 140933965Sjdp(The standard input is also a file.) 141033965Sjdp 141189857SobrienYou give @command{@value{AS}} a command line that has zero or more input file 141233965Sjdpnames. The input files are read (from left file name to right). A 141333965Sjdpcommand line argument (in any position) that has no special meaning 141433965Sjdpis taken to be an input file name. 141533965Sjdp 141689857SobrienIf you give @command{@value{AS}} no file names it attempts to read one input file 141789857Sobrienfrom the @command{@value{AS}} standard input, which is normally your terminal. You 141889857Sobrienmay have to type @key{ctl-D} to tell @command{@value{AS}} there is no more program 141933965Sjdpto assemble. 142033965Sjdp 142133965SjdpUse @samp{--} if you need to explicitly name the standard input file 142233965Sjdpin your command line. 142333965Sjdp 142489857SobrienIf the source is empty, @command{@value{AS}} produces a small, empty object 142533965Sjdpfile. 142633965Sjdp 142789857Sobrien@c man end 142889857Sobrien 142933965Sjdp@subheading Filenames and Line-numbers 143033965Sjdp 143133965Sjdp@cindex input file linenumbers 143233965Sjdp@cindex line numbers, in input files 143333965SjdpThere are two ways of locating a line in the input file (or files) and 143433965Sjdpeither may be used in reporting error messages. One way refers to a line 143533965Sjdpnumber in a physical file; the other refers to a line number in a 143633965Sjdp``logical'' file. @xref{Errors, ,Error and Warning Messages}. 143733965Sjdp 143833965Sjdp@dfn{Physical files} are those files named in the command line given 143989857Sobriento @command{@value{AS}}. 144033965Sjdp 144133965Sjdp@dfn{Logical files} are simply names declared explicitly by assembler 144260484Sobriendirectives; they bear no relation to physical files. Logical file names help 144389857Sobrienerror messages reflect the original source file, when @command{@value{AS}} source 144489857Sobrienis itself synthesized from other files. @command{@value{AS}} understands the 144560484Sobrien@samp{#} directives emitted by the @code{@value{GCC}} preprocessor. See also 144660484Sobrien@ref{File,,@code{.file}}. 144733965Sjdp 144833965Sjdp@node Object 144933965Sjdp@section Output (Object) File 145033965Sjdp 145133965Sjdp@cindex object file 145233965Sjdp@cindex output file 145333965Sjdp@kindex a.out 145433965Sjdp@kindex .o 145589857SobrienEvery time you run @command{@value{AS}} it produces an output file, which is 145633965Sjdpyour assembly language program translated into numbers. This file 145733965Sjdpis the object file. Its default name is 145833965Sjdp@ifclear BOUT 145933965Sjdp@code{a.out}. 146033965Sjdp@end ifclear 146133965Sjdp@ifset BOUT 146233965Sjdp@ifset GENERIC 146333965Sjdp@code{a.out}, or 146433965Sjdp@end ifset 146589857Sobrien@code{b.out} when @command{@value{AS}} is configured for the Intel 80960. 146633965Sjdp@end ifset 146789857SobrienYou can give it another name by using the @option{-o} option. Conventionally, 146833965Sjdpobject file names end with @file{.o}. The default name is used for historical 146933965Sjdpreasons: older assemblers were capable of assembling self-contained programs 147033965Sjdpdirectly into a runnable program. (For some formats, this isn't currently 147133965Sjdppossible, but it can be done for the @code{a.out} format.) 147233965Sjdp 147333965Sjdp@cindex linker 147433965Sjdp@kindex ld 147533965SjdpThe object file is meant for input to the linker @code{@value{LD}}. It contains 147633965Sjdpassembled program code, information to help @code{@value{LD}} integrate 147733965Sjdpthe assembled program into a runnable file, and (optionally) symbolic 147833965Sjdpinformation for the debugger. 147933965Sjdp 148033965Sjdp@c link above to some info file(s) like the description of a.out. 148133965Sjdp@c don't forget to describe @sc{gnu} info as well as Unix lossage. 148233965Sjdp 148333965Sjdp@node Errors 148433965Sjdp@section Error and Warning Messages 148533965Sjdp 148689857Sobrien@c man begin DESCRIPTION 148789857Sobrien 148877298Sobrien@cindex error messages 148933965Sjdp@cindex warning messages 149033965Sjdp@cindex messages from assembler 149189857Sobrien@command{@value{AS}} may write warnings and error messages to the standard error 149233965Sjdpfile (usually your terminal). This should not happen when a compiler 149389857Sobrienruns @command{@value{AS}} automatically. Warnings report an assumption made so 149489857Sobrienthat @command{@value{AS}} could keep assembling a flawed program; errors report a 149533965Sjdpgrave problem that stops the assembly. 149633965Sjdp 149789857Sobrien@c man end 149889857Sobrien 149933965Sjdp@cindex format of warning messages 150033965SjdpWarning messages have the format 150133965Sjdp 150233965Sjdp@smallexample 150333965Sjdpfile_name:@b{NNN}:Warning Message Text 150433965Sjdp@end smallexample 150533965Sjdp 150633965Sjdp@noindent 150733965Sjdp@cindex line numbers, in warnings/errors 150833965Sjdp(where @b{NNN} is a line number). If a logical file name has been given 150960484Sobrien(@pxref{File,,@code{.file}}) it is used for the filename, otherwise the name of 151060484Sobrienthe current input file is used. If a logical line number was given 151133965Sjdp@ifset GENERIC 151233965Sjdp(@pxref{Line,,@code{.line}}) 151333965Sjdp@end ifset 151433965Sjdpthen it is used to calculate the number printed, 151533965Sjdpotherwise the actual line in the current source file is printed. The 151633965Sjdpmessage text is intended to be self explanatory (in the grand Unix 151733965Sjdptradition). 151833965Sjdp 151933965Sjdp@cindex format of error messages 152033965SjdpError messages have the format 152133965Sjdp@smallexample 152233965Sjdpfile_name:@b{NNN}:FATAL:Error Message Text 152333965Sjdp@end smallexample 152433965SjdpThe file name and line number are derived as for warning 152533965Sjdpmessages. The actual message text may be rather less explanatory 152633965Sjdpbecause many of them aren't supposed to happen. 152733965Sjdp 152833965Sjdp@node Invoking 152933965Sjdp@chapter Command-Line Options 153033965Sjdp 153133965Sjdp@cindex options, all versions of assembler 153233965SjdpThis chapter describes command-line options available in @emph{all} 1533218822Sdimversions of the @sc{gnu} assembler; see @ref{Machine Dependencies}, 1534218822Sdimfor options specific 153533965Sjdp@ifclear GENERIC 1536130561Sobriento the @value{TARGET} target. 153733965Sjdp@end ifclear 153833965Sjdp@ifset GENERIC 153933965Sjdpto particular machine architectures. 154033965Sjdp@end ifset 154133965Sjdp 154289857Sobrien@c man begin DESCRIPTION 154389857Sobrien 1544130561SobrienIf you are invoking @command{@value{AS}} via the @sc{gnu} C compiler, 154560484Sobrienyou can use the @samp{-Wa} option to pass arguments through to the assembler. 154660484SobrienThe assembler arguments must be separated from each other (and the @samp{-Wa}) 154760484Sobrienby commas. For example: 154833965Sjdp 154933965Sjdp@smallexample 155033965Sjdpgcc -c -g -O -Wa,-alh,-L file.c 155133965Sjdp@end smallexample 155233965Sjdp 155333965Sjdp@noindent 155460484SobrienThis passes two options to the assembler: @samp{-alh} (emit a listing to 1555130561Sobrienstandard output with high-level and assembly source) and @samp{-L} (retain 155660484Sobrienlocal symbols in the symbol table). 155733965Sjdp 155833965SjdpUsually you do not need to use this @samp{-Wa} mechanism, since many compiler 155933965Sjdpcommand-line options are automatically passed to the assembler by the compiler. 156033965Sjdp(You can call the @sc{gnu} compiler driver with the @samp{-v} option to see 156133965Sjdpprecisely what options it passes to each compilation pass, including the 156233965Sjdpassembler.) 156333965Sjdp 156489857Sobrien@c man end 156589857Sobrien 156633965Sjdp@menu 156733965Sjdp* a:: -a[cdhlns] enable listings 1568218822Sdim* alternate:: --alternate enable alternate macro syntax 156933965Sjdp* D:: -D for compatibility 157033965Sjdp* f:: -f to work faster 157133965Sjdp* I:: -I for .include search path 157233965Sjdp@ifclear DIFF-TBL-KLUGE 157333965Sjdp* K:: -K for compatibility 157433965Sjdp@end ifclear 157533965Sjdp@ifset DIFF-TBL-KLUGE 157633965Sjdp* K:: -K for difference tables 157733965Sjdp@end ifset 157833965Sjdp 1579218822Sdim* L:: -L to retain local symbols 158089857Sobrien* listing:: --listing-XXX to configure listing output 158133965Sjdp* M:: -M or --mri to assemble in MRI compatibility mode 158238889Sjdp* MD:: --MD for dependency tracking 158333965Sjdp* o:: -o to name the object file 158433965Sjdp* R:: -R to join data and text sections 158533965Sjdp* statistics:: --statistics to see statistics about assembly 158638889Sjdp* traditional-format:: --traditional-format for compatible output 158733965Sjdp* v:: -v to announce version 158860484Sobrien* W:: -W, --no-warn, --warn, --fatal-warnings to control warnings 158933965Sjdp* Z:: -Z to make object file even after errors 159033965Sjdp@end menu 159133965Sjdp 159233965Sjdp@node a 159389857Sobrien@section Enable Listings: @option{-a[cdhlns]} 159433965Sjdp 159533965Sjdp@kindex -a 159633965Sjdp@kindex -ac 159733965Sjdp@kindex -ad 159833965Sjdp@kindex -ah 159933965Sjdp@kindex -al 160033965Sjdp@kindex -an 160133965Sjdp@kindex -as 160233965Sjdp@cindex listings, enabling 160333965Sjdp@cindex assembly listings, enabling 160433965Sjdp 160533965SjdpThese options enable listing output from the assembler. By itself, 160633965Sjdp@samp{-a} requests high-level, assembly, and symbols listing. 160733965SjdpYou can use other letters to select specific options for the list: 160833965Sjdp@samp{-ah} requests a high-level language listing, 160933965Sjdp@samp{-al} requests an output-program assembly listing, and 161033965Sjdp@samp{-as} requests a symbol table listing. 161133965SjdpHigh-level listings require that a compiler debugging option like 161233965Sjdp@samp{-g} be used, and that assembly listings (@samp{-al}) be requested 161333965Sjdpalso. 161433965Sjdp 161533965SjdpUse the @samp{-ac} option to omit false conditionals from a listing. Any lines 161633965Sjdpwhich are not assembled because of a false @code{.if} (or @code{.ifdef}, or any 161733965Sjdpother conditional), or a true @code{.if} followed by an @code{.else}, will be 161833965Sjdpomitted from the listing. 161933965Sjdp 162033965SjdpUse the @samp{-ad} option to omit debugging directives from the 162133965Sjdplisting. 162233965Sjdp 162333965SjdpOnce you have specified one of these options, you can further control 162433965Sjdplisting output and its appearance using the directives @code{.list}, 162533965Sjdp@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and 162633965Sjdp@code{.sbttl}. 162733965SjdpThe @samp{-an} option turns off all forms processing. 162833965SjdpIf you do not request listing output with one of the @samp{-a} options, the 162933965Sjdplisting-control directives have no effect. 163033965Sjdp 163133965SjdpThe letters after @samp{-a} may be combined into one option, 163233965Sjdp@emph{e.g.}, @samp{-aln}. 163333965Sjdp 1634218822SdimNote if the assembler source is coming from the standard input (e.g., 1635218822Sdimbecause it 163689857Sobrienis being created by @code{@value{GCC}} and the @samp{-pipe} command line switch 163789857Sobrienis being used) then the listing will not contain any comments or preprocessor 163889857Sobriendirectives. This is because the listing code buffers input source lines from 163989857Sobrienstdin only after they have been preprocessed by the assembler. This reduces 164089857Sobrienmemory usage and makes the code more efficient. 164189857Sobrien 1642218822Sdim@node alternate 1643218822Sdim@section @option{--alternate} 1644218822Sdim 1645218822Sdim@kindex --alternate 1646218822SdimBegin in alternate macro mode, see @ref{Altmacro,,@code{.altmacro}}. 1647218822Sdim 164833965Sjdp@node D 164989857Sobrien@section @option{-D} 165033965Sjdp 165133965Sjdp@kindex -D 165233965SjdpThis option has no effect whatsoever, but it is accepted to make it more 165333965Sjdplikely that scripts written for other assemblers also work with 165489857Sobrien@command{@value{AS}}. 165533965Sjdp 165633965Sjdp@node f 165789857Sobrien@section Work Faster: @option{-f} 165833965Sjdp 165933965Sjdp@kindex -f 166033965Sjdp@cindex trusted compiler 166189857Sobrien@cindex faster processing (@option{-f}) 166233965Sjdp@samp{-f} should only be used when assembling programs written by a 166333965Sjdp(trusted) compiler. @samp{-f} stops the assembler from doing whitespace 166433965Sjdpand comment preprocessing on 166533965Sjdpthe input file(s) before assembling them. @xref{Preprocessing, 166633965Sjdp,Preprocessing}. 166733965Sjdp 166833965Sjdp@quotation 166933965Sjdp@emph{Warning:} if you use @samp{-f} when the files actually need to be 167089857Sobrienpreprocessed (if they contain comments, for example), @command{@value{AS}} does 167133965Sjdpnot work correctly. 167233965Sjdp@end quotation 167333965Sjdp 167433965Sjdp@node I 1675130561Sobrien@section @code{.include} Search Path: @option{-I} @var{path} 167633965Sjdp 167733965Sjdp@kindex -I @var{path} 167833965Sjdp@cindex paths for @code{.include} 167933965Sjdp@cindex search path for @code{.include} 168033965Sjdp@cindex @code{include} directive search path 168133965SjdpUse this option to add a @var{path} to the list of directories 168289857Sobrien@command{@value{AS}} searches for files specified in @code{.include} 168389857Sobriendirectives (@pxref{Include,,@code{.include}}). You may use @option{-I} as 168433965Sjdpmany times as necessary to include a variety of paths. The current 168589857Sobrienworking directory is always searched first; after that, @command{@value{AS}} 168633965Sjdpsearches any @samp{-I} directories in the same order as they were 168733965Sjdpspecified (left to right) on the command line. 168833965Sjdp 168933965Sjdp@node K 169089857Sobrien@section Difference Tables: @option{-K} 169133965Sjdp 169233965Sjdp@kindex -K 169333965Sjdp@ifclear DIFF-TBL-KLUGE 169433965SjdpOn the @value{TARGET} family, this option is allowed, but has no effect. It is 169533965Sjdppermitted for compatibility with the @sc{gnu} assembler on other platforms, 169633965Sjdpwhere it can be used to warn when the assembler alters the machine code 169733965Sjdpgenerated for @samp{.word} directives in difference tables. The @value{TARGET} 169833965Sjdpfamily does not have the addressing limitations that sometimes lead to this 169933965Sjdpalteration on other platforms. 170033965Sjdp@end ifclear 170133965Sjdp 170233965Sjdp@ifset DIFF-TBL-KLUGE 170333965Sjdp@cindex difference tables, warning 170433965Sjdp@cindex warning for altered difference tables 1705218822Sdim@command{@value{AS}} sometimes alters the code emitted for directives of the 1706218822Sdimform @samp{.word @var{sym1}-@var{sym2}}. @xref{Word,,@code{.word}}. 170733965SjdpYou can use the @samp{-K} option if you want a warning issued when this 170833965Sjdpis done. 170933965Sjdp@end ifset 171033965Sjdp 171133965Sjdp@node L 1712218822Sdim@section Include Local Symbols: @option{-L} 171333965Sjdp 171433965Sjdp@kindex -L 1715218822Sdim@cindex local symbols, retaining in output 1716218822SdimSymbols beginning with system-specific local label prefixes, typically 1717218822Sdim@samp{.L} for ELF systems or @samp{L} for traditional a.out systems, are 1718218822Sdimcalled @dfn{local symbols}. @xref{Symbol Names}. Normally you do not see 1719218822Sdimsuch symbols when debugging, because they are intended for the use of 1720218822Sdimprograms (like compilers) that compose assembler programs, not for your 1721218822Sdimnotice. Normally both @command{@value{AS}} and @code{@value{LD}} discard 1722218822Sdimsuch symbols, so you do not normally debug with them. 172333965Sjdp 1724218822SdimThis option tells @command{@value{AS}} to retain those local symbols 172533965Sjdpin the object file. Usually if you do this you also tell the linker 1726218822Sdim@code{@value{LD}} to preserve those symbols. 172733965Sjdp 172889857Sobrien@node listing 172989857Sobrien@section Configuring listing output: @option{--listing} 173089857Sobrien 173189857SobrienThe listing feature of the assembler can be enabled via the command line switch 173289857Sobrien@samp{-a} (@pxref{a}). This feature combines the input source file(s) with a 173389857Sobrienhex dump of the corresponding locations in the output object file, and displays 1734218822Sdimthem as a listing file. The format of this listing can be controlled by 1735218822Sdimdirectives inside the assembler source (i.e., @code{.list} (@pxref{List}), 1736218822Sdim@code{.title} (@pxref{Title}), @code{.sbttl} (@pxref{Sbttl}), 1737218822Sdim@code{.psize} (@pxref{Psize}), and 1738218822Sdim@code{.eject} (@pxref{Eject}) and also by the following switches: 173989857Sobrien 174089857Sobrien@table @gcctabopt 174189857Sobrien@item --listing-lhs-width=@samp{number} 174289857Sobrien@kindex --listing-lhs-width 174389857Sobrien@cindex Width of first line disassembly output 174489857SobrienSets the maximum width, in words, of the first line of the hex byte dump. This 174589857Sobriendump appears on the left hand side of the listing output. 174689857Sobrien 174789857Sobrien@item --listing-lhs-width2=@samp{number} 174889857Sobrien@kindex --listing-lhs-width2 174989857Sobrien@cindex Width of continuation lines of disassembly output 175089857SobrienSets the maximum width, in words, of any further lines of the hex byte dump for 1751130561Sobriena given input source line. If this value is not specified, it defaults to being 175289857Sobrienthe same as the value specified for @samp{--listing-lhs-width}. If neither 175389857Sobrienswitch is used the default is to one. 175489857Sobrien 175589857Sobrien@item --listing-rhs-width=@samp{number} 175689857Sobrien@kindex --listing-rhs-width 175789857Sobrien@cindex Width of source line output 175889857SobrienSets the maximum width, in characters, of the source line that is displayed 175989857Sobrienalongside the hex dump. The default value for this parameter is 100. The 176089857Sobriensource line is displayed on the right hand side of the listing output. 176189857Sobrien 176289857Sobrien@item --listing-cont-lines=@samp{number} 176389857Sobrien@kindex --listing-cont-lines 176489857Sobrien@cindex Maximum number of continuation lines 176589857SobrienSets the maximum number of continuation lines of hex dump that will be 176689857Sobriendisplayed for a given single line of source input. The default value is 4. 176789857Sobrien@end table 176889857Sobrien 176933965Sjdp@node M 177089857Sobrien@section Assemble in MRI Compatibility Mode: @option{-M} 177133965Sjdp 177233965Sjdp@kindex -M 177333965Sjdp@cindex MRI compatibility mode 177489857SobrienThe @option{-M} or @option{--mri} option selects MRI compatibility mode. This 177589857Sobrienchanges the syntax and pseudo-op handling of @command{@value{AS}} to make it 177633965Sjdpcompatible with the @code{ASM68K} or the @code{ASM960} (depending upon the 177733965Sjdpconfigured target) assembler from Microtec Research. The exact nature of the 177833965SjdpMRI syntax will not be documented here; see the MRI manuals for more 177933965Sjdpinformation. Note in particular that the handling of macros and macro 178033965Sjdparguments is somewhat different. The purpose of this option is to permit 178189857Sobrienassembling existing MRI assembler code using @command{@value{AS}}. 178233965Sjdp 178333965SjdpThe MRI compatibility is not complete. Certain operations of the MRI assembler 178433965Sjdpdepend upon its object file format, and can not be supported using other object 178533965Sjdpfile formats. Supporting these would require enhancing each object file format 178633965Sjdpindividually. These are: 178733965Sjdp 178833965Sjdp@itemize @bullet 178933965Sjdp@item global symbols in common section 179033965Sjdp 179133965SjdpThe m68k MRI assembler supports common sections which are merged by the linker. 179289857SobrienOther object file formats do not support this. @command{@value{AS}} handles 179333965Sjdpcommon sections by treating them as a single common symbol. It permits local 179433965Sjdpsymbols to be defined within a common section, but it can not support global 179533965Sjdpsymbols, since it has no way to describe them. 179633965Sjdp 179733965Sjdp@item complex relocations 179833965Sjdp 179933965SjdpThe MRI assemblers support relocations against a negated section address, and 180033965Sjdprelocations which combine the start addresses of two or more sections. These 180133965Sjdpare not support by other object file formats. 180233965Sjdp 180333965Sjdp@item @code{END} pseudo-op specifying start address 180433965Sjdp 180533965SjdpThe MRI @code{END} pseudo-op permits the specification of a start address. 180633965SjdpThis is not supported by other object file formats. The start address may 180789857Sobrieninstead be specified using the @option{-e} option to the linker, or in a linker 180833965Sjdpscript. 180933965Sjdp 181033965Sjdp@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops 181133965Sjdp 181233965SjdpThe MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module 181333965Sjdpname to the output file. This is not supported by other object file formats. 181433965Sjdp 181533965Sjdp@item @code{ORG} pseudo-op 181633965Sjdp 181733965SjdpThe m68k MRI @code{ORG} pseudo-op begins an absolute section at a given 181889857Sobrienaddress. This differs from the usual @command{@value{AS}} @code{.org} pseudo-op, 181933965Sjdpwhich changes the location within the current section. Absolute sections are 182033965Sjdpnot supported by other object file formats. The address of a section may be 182133965Sjdpassigned within a linker script. 182233965Sjdp@end itemize 182333965Sjdp 182433965SjdpThere are some other features of the MRI assembler which are not supported by 182589857Sobrien@command{@value{AS}}, typically either because they are difficult or because they 182633965Sjdpseem of little consequence. Some of these may be supported in future releases. 182733965Sjdp 182833965Sjdp@itemize @bullet 182933965Sjdp 183033965Sjdp@item EBCDIC strings 183133965Sjdp 183233965SjdpEBCDIC strings are not supported. 183333965Sjdp 183433965Sjdp@item packed binary coded decimal 183533965Sjdp 183633965SjdpPacked binary coded decimal is not supported. This means that the @code{DC.P} 183733965Sjdpand @code{DCB.P} pseudo-ops are not supported. 183833965Sjdp 183933965Sjdp@item @code{FEQU} pseudo-op 184033965Sjdp 184133965SjdpThe m68k @code{FEQU} pseudo-op is not supported. 184233965Sjdp 184333965Sjdp@item @code{NOOBJ} pseudo-op 184433965Sjdp 184533965SjdpThe m68k @code{NOOBJ} pseudo-op is not supported. 184633965Sjdp 184733965Sjdp@item @code{OPT} branch control options 184833965Sjdp 184933965SjdpThe m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB}, 185089857Sobrien@code{BRL}, and @code{BRW}---are ignored. @command{@value{AS}} automatically 185133965Sjdprelaxes all branches, whether forward or backward, to an appropriate size, so 185233965Sjdpthese options serve no purpose. 185333965Sjdp 185433965Sjdp@item @code{OPT} list control options 185533965Sjdp 185633965SjdpThe following m68k @code{OPT} list control options are ignored: @code{C}, 185733965Sjdp@code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M}, 185833965Sjdp@code{MEX}, @code{MC}, @code{MD}, @code{X}. 185933965Sjdp 186033965Sjdp@item other @code{OPT} options 186133965Sjdp 186233965SjdpThe following m68k @code{OPT} options are ignored: @code{NEST}, @code{O}, 186333965Sjdp@code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}. 186433965Sjdp 186533965Sjdp@item @code{OPT} @code{D} option is default 186633965Sjdp 186733965SjdpThe m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler. 186833965Sjdp@code{OPT NOD} may be used to turn it off. 186933965Sjdp 187033965Sjdp@item @code{XREF} pseudo-op. 187133965Sjdp 187233965SjdpThe m68k @code{XREF} pseudo-op is ignored. 187333965Sjdp 187433965Sjdp@item @code{.debug} pseudo-op 187533965Sjdp 187633965SjdpThe i960 @code{.debug} pseudo-op is not supported. 187733965Sjdp 187833965Sjdp@item @code{.extended} pseudo-op 187933965Sjdp 188033965SjdpThe i960 @code{.extended} pseudo-op is not supported. 188133965Sjdp 188233965Sjdp@item @code{.list} pseudo-op. 188333965Sjdp 188433965SjdpThe various options of the i960 @code{.list} pseudo-op are not supported. 188533965Sjdp 188633965Sjdp@item @code{.optimize} pseudo-op 188733965Sjdp 188833965SjdpThe i960 @code{.optimize} pseudo-op is not supported. 188933965Sjdp 189033965Sjdp@item @code{.output} pseudo-op 189133965Sjdp 189233965SjdpThe i960 @code{.output} pseudo-op is not supported. 189333965Sjdp 189433965Sjdp@item @code{.setreal} pseudo-op 189533965Sjdp 189633965SjdpThe i960 @code{.setreal} pseudo-op is not supported. 189733965Sjdp 189833965Sjdp@end itemize 189933965Sjdp 190038889Sjdp@node MD 1901130561Sobrien@section Dependency Tracking: @option{--MD} 190238889Sjdp 190338889Sjdp@kindex --MD 190438889Sjdp@cindex dependency tracking 190538889Sjdp@cindex make rules 190638889Sjdp 190789857Sobrien@command{@value{AS}} can generate a dependency file for the file it creates. This 190838889Sjdpfile consists of a single rule suitable for @code{make} describing the 190938889Sjdpdependencies of the main source file. 191038889Sjdp 191138889SjdpThe rule is written to the file named in its argument. 191238889Sjdp 191338889SjdpThis feature is used in the automatic updating of makefiles. 191438889Sjdp 191533965Sjdp@node o 191689857Sobrien@section Name the Object File: @option{-o} 191733965Sjdp 191833965Sjdp@kindex -o 191933965Sjdp@cindex naming object file 192033965Sjdp@cindex object file name 192189857SobrienThere is always one object file output when you run @command{@value{AS}}. By 192233965Sjdpdefault it has the name 192333965Sjdp@ifset GENERIC 192433965Sjdp@ifset I960 192533965Sjdp@file{a.out} (or @file{b.out}, for Intel 960 targets only). 192633965Sjdp@end ifset 192733965Sjdp@ifclear I960 192833965Sjdp@file{a.out}. 192933965Sjdp@end ifclear 193033965Sjdp@end ifset 193133965Sjdp@ifclear GENERIC 193233965Sjdp@ifset I960 193333965Sjdp@file{b.out}. 193433965Sjdp@end ifset 193533965Sjdp@ifclear I960 193633965Sjdp@file{a.out}. 193733965Sjdp@end ifclear 193833965Sjdp@end ifclear 193933965SjdpYou use this option (which takes exactly one filename) to give the 194033965Sjdpobject file a different name. 194133965Sjdp 194289857SobrienWhatever the object file is called, @command{@value{AS}} overwrites any 194333965Sjdpexisting file of the same name. 194433965Sjdp 194533965Sjdp@node R 194689857Sobrien@section Join Data and Text Sections: @option{-R} 194733965Sjdp 194833965Sjdp@kindex -R 194933965Sjdp@cindex data and text sections, joining 195033965Sjdp@cindex text and data sections, joining 195133965Sjdp@cindex joining text and data sections 195233965Sjdp@cindex merging text and data sections 195389857Sobrien@option{-R} tells @command{@value{AS}} to write the object file as if all 195433965Sjdpdata-section data lives in the text section. This is only done at 195533965Sjdpthe very last moment: your binary data are the same, but data 195633965Sjdpsection parts are relocated differently. The data section part of 195733965Sjdpyour object file is zero bytes long because all its bytes are 195833965Sjdpappended to the text section. (@xref{Sections,,Sections and Relocation}.) 195933965Sjdp 196089857SobrienWhen you specify @option{-R} it would be possible to generate shorter 196133965Sjdpaddress displacements (because we do not have to cross between text and 196233965Sjdpdata section). We refrain from doing this simply for compatibility with 196389857Sobrienolder versions of @command{@value{AS}}. In future, @option{-R} may work this way. 196433965Sjdp 1965130561Sobrien@ifset COFF-ELF 1966130561SobrienWhen @command{@value{AS}} is configured for COFF or ELF output, 196733965Sjdpthis option is only useful if you use sections named @samp{.text} and 196833965Sjdp@samp{.data}. 196933965Sjdp@end ifset 197033965Sjdp 197133965Sjdp@ifset HPPA 197289857Sobrien@option{-R} is not supported for any of the HPPA targets. Using 197389857Sobrien@option{-R} generates a warning from @command{@value{AS}}. 197433965Sjdp@end ifset 197533965Sjdp 197633965Sjdp@node statistics 197789857Sobrien@section Display Assembly Statistics: @option{--statistics} 197833965Sjdp 197933965Sjdp@kindex --statistics 198033965Sjdp@cindex statistics, about assembly 198133965Sjdp@cindex time, total for assembly 198233965Sjdp@cindex space used, maximum for assembly 198333965SjdpUse @samp{--statistics} to display two statistics about the resources used by 198489857Sobrien@command{@value{AS}}: the maximum amount of space allocated during the assembly 198533965Sjdp(in bytes), and the total execution time taken for the assembly (in @sc{cpu} 198633965Sjdpseconds). 198733965Sjdp 198838889Sjdp@node traditional-format 1989130561Sobrien@section Compatible Output: @option{--traditional-format} 199038889Sjdp 199138889Sjdp@kindex --traditional-format 199289857SobrienFor some targets, the output of @command{@value{AS}} is different in some ways 199338889Sjdpfrom the output of some existing assembler. This switch requests 199489857Sobrien@command{@value{AS}} to use the traditional format instead. 199538889Sjdp 199638889SjdpFor example, it disables the exception frame optimizations which 199789857Sobrien@command{@value{AS}} normally does by default on @code{@value{GCC}} output. 199838889Sjdp 199933965Sjdp@node v 200089857Sobrien@section Announce Version: @option{-v} 200133965Sjdp 200233965Sjdp@kindex -v 200333965Sjdp@kindex -version 200433965Sjdp@cindex assembler version 200533965Sjdp@cindex version of assembler 200633965SjdpYou can find out what version of as is running by including the 200733965Sjdpoption @samp{-v} (which you can also spell as @samp{-version}) on the 200833965Sjdpcommand line. 200933965Sjdp 201033965Sjdp@node W 201189857Sobrien@section Control Warnings: @option{-W}, @option{--warn}, @option{--no-warn}, @option{--fatal-warnings} 201233965Sjdp 201389857Sobrien@command{@value{AS}} should never give a warning or error message when 201433965Sjdpassembling compiler output. But programs written by people often 201589857Sobriencause @command{@value{AS}} to give a warning that a particular assumption was 201633965Sjdpmade. All such warnings are directed to the standard error file. 201733965Sjdp 2018130561Sobrien@kindex -W 2019130561Sobrien@kindex --no-warn 202060484Sobrien@cindex suppressing warnings 202160484Sobrien@cindex warnings, suppressing 202289857SobrienIf you use the @option{-W} and @option{--no-warn} options, no warnings are issued. 202360484SobrienThis only affects the warning messages: it does not change any particular of 202489857Sobrienhow @command{@value{AS}} assembles your file. Errors, which stop the assembly, 202560484Sobrienare still reported. 202660484Sobrien 2027130561Sobrien@kindex --fatal-warnings 202860484Sobrien@cindex errors, caused by warnings 202960484Sobrien@cindex warnings, causing error 203089857SobrienIf you use the @option{--fatal-warnings} option, @command{@value{AS}} considers 203160484Sobrienfiles that generate warnings to be in error. 203260484Sobrien 2033130561Sobrien@kindex --warn 203460484Sobrien@cindex warnings, switching on 203589857SobrienYou can switch these options off again by specifying @option{--warn}, which 203660484Sobriencauses warnings to be output as usual. 203760484Sobrien 203833965Sjdp@node Z 203989857Sobrien@section Generate Object File in Spite of Errors: @option{-Z} 204033965Sjdp@cindex object file, after errors 204133965Sjdp@cindex errors, continuing after 204289857SobrienAfter an error message, @command{@value{AS}} normally produces no output. If for 204333965Sjdpsome reason you are interested in object file output even after 204489857Sobrien@command{@value{AS}} gives an error message on your program, use the @samp{-Z} 204589857Sobrienoption. If there are any errors, @command{@value{AS}} continues anyways, and 204633965Sjdpwrites an object file after a final warning message of the form @samp{@var{n} 204733965Sjdperrors, @var{m} warnings, generating bad object file.} 204833965Sjdp 204933965Sjdp@node Syntax 205033965Sjdp@chapter Syntax 205133965Sjdp 205233965Sjdp@cindex machine-independent syntax 205333965Sjdp@cindex syntax, machine-independent 205433965SjdpThis chapter describes the machine-independent syntax allowed in a 205589857Sobriensource file. @command{@value{AS}} syntax is similar to what many other 205633965Sjdpassemblers use; it is inspired by the BSD 4.2 205733965Sjdp@ifclear VAX 205833965Sjdpassembler. 205933965Sjdp@end ifclear 206033965Sjdp@ifset VAX 206189857Sobrienassembler, except that @command{@value{AS}} does not assemble Vax bit-fields. 206233965Sjdp@end ifset 206333965Sjdp 206433965Sjdp@menu 206533965Sjdp* Preprocessing:: Preprocessing 206633965Sjdp* Whitespace:: Whitespace 206733965Sjdp* Comments:: Comments 206833965Sjdp* Symbol Intro:: Symbols 206933965Sjdp* Statements:: Statements 207033965Sjdp* Constants:: Constants 207133965Sjdp@end menu 207233965Sjdp 207333965Sjdp@node Preprocessing 207433965Sjdp@section Preprocessing 207533965Sjdp 207633965Sjdp@cindex preprocessing 207789857SobrienThe @command{@value{AS}} internal preprocessor: 207833965Sjdp@itemize @bullet 207933965Sjdp@cindex whitespace, removed by preprocessor 208033965Sjdp@item 208133965Sjdpadjusts and removes extra whitespace. It leaves one space or tab before 208233965Sjdpthe keywords on a line, and turns any other whitespace on the line into 208333965Sjdpa single space. 208433965Sjdp 208533965Sjdp@cindex comments, removed by preprocessor 208633965Sjdp@item 208733965Sjdpremoves all comments, replacing them with a single space, or an 208833965Sjdpappropriate number of newlines. 208933965Sjdp 209033965Sjdp@cindex constants, converted by preprocessor 209133965Sjdp@item 209233965Sjdpconverts character constants into the appropriate numeric values. 209333965Sjdp@end itemize 209433965Sjdp 209533965SjdpIt does not do macro processing, include file handling, or 209633965Sjdpanything else you may get from your C compiler's preprocessor. You can 209733965Sjdpdo include file processing with the @code{.include} directive 209833965Sjdp(@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver 2099130561Sobriento get other ``CPP'' style preprocessing by giving the input file a 2100218822Sdim@samp{.S} suffix. @xref{Overall Options, ,Options Controlling the Kind of 210133965SjdpOutput, gcc.info, Using GNU CC}. 210233965Sjdp 210333965SjdpExcess whitespace, comments, and character constants 210433965Sjdpcannot be used in the portions of the input text that are not 210533965Sjdppreprocessed. 210633965Sjdp 210733965Sjdp@cindex turning preprocessing on and off 210833965Sjdp@cindex preprocessing, turning on and off 210933965Sjdp@kindex #NO_APP 211033965Sjdp@kindex #APP 211133965SjdpIf the first line of an input file is @code{#NO_APP} or if you use the 211233965Sjdp@samp{-f} option, whitespace and comments are not removed from the input file. 211333965SjdpWithin an input file, you can ask for whitespace and comment removal in 211433965Sjdpspecific portions of the by putting a line that says @code{#APP} before the 211533965Sjdptext that may contain whitespace or comments, and putting a line that says 211633965Sjdp@code{#NO_APP} after this text. This feature is mainly intend to support 211733965Sjdp@code{asm} statements in compilers whose output is otherwise free of comments 211833965Sjdpand whitespace. 211933965Sjdp 212033965Sjdp@node Whitespace 212133965Sjdp@section Whitespace 212233965Sjdp 212333965Sjdp@cindex whitespace 212433965Sjdp@dfn{Whitespace} is one or more blanks or tabs, in any order. 212533965SjdpWhitespace is used to separate symbols, and to make programs neater for 212633965Sjdppeople to read. Unless within character constants 212733965Sjdp(@pxref{Characters,,Character Constants}), any whitespace means the same 212833965Sjdpas exactly one space. 212933965Sjdp 213033965Sjdp@node Comments 213133965Sjdp@section Comments 213233965Sjdp 213333965Sjdp@cindex comments 213489857SobrienThere are two ways of rendering comments to @command{@value{AS}}. In both 213533965Sjdpcases the comment is equivalent to one space. 213633965Sjdp 213733965SjdpAnything from @samp{/*} through the next @samp{*/} is a comment. 213833965SjdpThis means you may not nest these comments. 213933965Sjdp 214033965Sjdp@smallexample 214133965Sjdp/* 214233965Sjdp The only way to include a newline ('\n') in a comment 214333965Sjdp is to use this sort of comment. 214433965Sjdp*/ 214533965Sjdp 214633965Sjdp/* This sort of comment does not nest. */ 214733965Sjdp@end smallexample 214833965Sjdp 214933965Sjdp@cindex line comment character 215033965SjdpAnything from the @dfn{line comment} character to the next newline 215133965Sjdpis considered a comment and is ignored. The line comment character is 215238889Sjdp@ifset ARC 215338889Sjdp@samp{;} on the ARC; 215438889Sjdp@end ifset 215560484Sobrien@ifset ARM 215660484Sobrien@samp{@@} on the ARM; 215760484Sobrien@end ifset 215833965Sjdp@ifset H8/300 215933965Sjdp@samp{;} for the H8/300 family; 216033965Sjdp@end ifset 216133965Sjdp@ifset HPPA 216233965Sjdp@samp{;} for the HPPA; 216333965Sjdp@end ifset 216477298Sobrien@ifset I80386 216577298Sobrien@samp{#} on the i386 and x86-64; 216677298Sobrien@end ifset 216733965Sjdp@ifset I960 216833965Sjdp@samp{#} on the i960; 216933965Sjdp@end ifset 217089857Sobrien@ifset PDP11 217189857Sobrien@samp{;} for the PDP-11; 217289857Sobrien@end ifset 217360484Sobrien@ifset PJ 217460484Sobrien@samp{;} for picoJava; 217560484Sobrien@end ifset 217689857Sobrien@ifset PPC 2177130561Sobrien@samp{#} for Motorola PowerPC; 217889857Sobrien@end ifset 217933965Sjdp@ifset SH 2180130561Sobrien@samp{!} for the Renesas / SuperH SH; 218133965Sjdp@end ifset 218233965Sjdp@ifset SPARC 218333965Sjdp@samp{!} on the SPARC; 218433965Sjdp@end ifset 2185130561Sobrien@ifset IP2K 2186130561Sobrien@samp{#} on the ip2k; 2187130561Sobrien@end ifset 2188218822Sdim@ifset M32C 2189218822Sdim@samp{#} on the m32c; 2190218822Sdim@end ifset 219138889Sjdp@ifset M32R 219238889Sjdp@samp{#} on the m32r; 219338889Sjdp@end ifset 219433965Sjdp@ifset M680X0 219533965Sjdp@samp{|} on the 680x0; 219633965Sjdp@end ifset 219777298Sobrien@ifset M68HC11 219877298Sobrien@samp{#} on the 68HC11 and 68HC12; 219977298Sobrien@end ifset 220033965Sjdp@ifset VAX 220133965Sjdp@samp{#} on the Vax; 220233965Sjdp@end ifset 2203218822Sdim@ifset Z80 2204218822Sdim@samp{;} for the Z80; 2205218822Sdim@end ifset 220633965Sjdp@ifset Z8000 220733965Sjdp@samp{!} for the Z8000; 220833965Sjdp@end ifset 220938889Sjdp@ifset V850 221038889Sjdp@samp{#} on the V850; 221138889Sjdp@end ifset 2212130561Sobrien@ifset XTENSA 2213130561Sobrien@samp{#} for Xtensa systems; 2214130561Sobrien@end ifset 221533965Sjdpsee @ref{Machine Dependencies}. @refill 221689857Sobrien@c FIXME What about i860? 221733965Sjdp 221833965Sjdp@ifset GENERIC 221933965SjdpOn some machines there are two different line comment characters. One 222033965Sjdpcharacter only begins a comment if it is the first non-whitespace character on 222133965Sjdpa line, while the other always begins a comment. 222233965Sjdp@end ifset 222333965Sjdp 222438889Sjdp@ifset V850 222538889SjdpThe V850 assembler also supports a double dash as starting a comment that 222638889Sjdpextends to the end of the line. 222738889Sjdp 222838889Sjdp@samp{--}; 222938889Sjdp@end ifset 223038889Sjdp 223133965Sjdp@kindex # 223233965Sjdp@cindex lines starting with @code{#} 223333965Sjdp@cindex logical line numbers 223433965SjdpTo be compatible with past assemblers, lines that begin with @samp{#} have a 223533965Sjdpspecial interpretation. Following the @samp{#} should be an absolute 223633965Sjdpexpression (@pxref{Expressions}): the logical line number of the @emph{next} 2237218822Sdimline. Then a string (@pxref{Strings, ,Strings}) is allowed: if present it is a 223833965Sjdpnew logical file name. The rest of the line, if any, should be whitespace. 223933965Sjdp 224033965SjdpIf the first non-whitespace characters on the line are not numeric, 224133965Sjdpthe line is ignored. (Just like a comment.) 224233965Sjdp 224333965Sjdp@smallexample 224433965Sjdp # This is an ordinary comment. 224533965Sjdp# 42-6 "new_file_name" # New logical file name 224633965Sjdp # This is logical line # 36. 224733965Sjdp@end smallexample 224833965SjdpThis feature is deprecated, and may disappear from future versions 224989857Sobrienof @command{@value{AS}}. 225033965Sjdp 225133965Sjdp@node Symbol Intro 225233965Sjdp@section Symbols 225333965Sjdp 225433965Sjdp@cindex characters used in symbols 225533965Sjdp@ifclear SPECIAL-SYMS 225633965SjdpA @dfn{symbol} is one or more characters chosen from the set of all 225733965Sjdpletters (both upper and lower case), digits and the three characters 225833965Sjdp@samp{_.$}. 225933965Sjdp@end ifclear 226033965Sjdp@ifset SPECIAL-SYMS 226133965Sjdp@ifclear GENERIC 226233965Sjdp@ifset H8 226333965SjdpA @dfn{symbol} is one or more characters chosen from the set of all 226433965Sjdpletters (both upper and lower case), digits and the three characters 226533965Sjdp@samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in 226633965Sjdpsymbol names.) 226733965Sjdp@end ifset 226833965Sjdp@end ifclear 226933965Sjdp@end ifset 227033965Sjdp@ifset GENERIC 227133965SjdpOn most machines, you can also use @code{$} in symbol names; exceptions 227233965Sjdpare noted in @ref{Machine Dependencies}. 227333965Sjdp@end ifset 227433965SjdpNo symbol may begin with a digit. Case is significant. 227533965SjdpThere is no length limit: all characters are significant. Symbols are 227633965Sjdpdelimited by characters not in that set, or by the beginning of a file 227733965Sjdp(since the source program must end with a newline, the end of a file is 227833965Sjdpnot a possible symbol delimiter). @xref{Symbols}. 227933965Sjdp@cindex length of symbols 228033965Sjdp 228133965Sjdp@node Statements 228233965Sjdp@section Statements 228333965Sjdp 228433965Sjdp@cindex statements, structure of 228533965Sjdp@cindex line separator character 228633965Sjdp@cindex statement separator character 228733965Sjdp@ifclear GENERIC 228833965Sjdp@ifclear abnormal-separator 228933965SjdpA @dfn{statement} ends at a newline character (@samp{\n}) or at a 229033965Sjdpsemicolon (@samp{;}). The newline or semicolon is considered part of 229133965Sjdpthe preceding statement. Newlines and semicolons within character 229233965Sjdpconstants are an exception: they do not end statements. 229333965Sjdp@end ifclear 229433965Sjdp@ifset abnormal-separator 229533965Sjdp@ifset HPPA 229633965SjdpA @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation 229733965Sjdppoint (@samp{!}). The newline or exclamation point is considered part of the 229833965Sjdppreceding statement. Newlines and exclamation points within character 229933965Sjdpconstants are an exception: they do not end statements. 230033965Sjdp@end ifset 230133965Sjdp@ifset H8 230233965SjdpA @dfn{statement} ends at a newline character (@samp{\n}); or (for the 2303218822SdimH8/300) a dollar sign (@samp{$}); or (for the Renesas-SH) a semicolon 230433965Sjdp(@samp{;}). The newline or separator character is considered part of 230533965Sjdpthe preceding statement. Newlines and separators within character 230633965Sjdpconstants are an exception: they do not end statements. 230733965Sjdp@end ifset 230833965Sjdp@end ifset 230933965Sjdp@end ifclear 231033965Sjdp@ifset GENERIC 231133965SjdpA @dfn{statement} ends at a newline character (@samp{\n}) or line 2312218822Sdimseparator character. (The line separator is usually @samp{;}, unless this 2313218822Sdimconflicts with the comment character; see @ref{Machine Dependencies}.) The 231433965Sjdpnewline or separator character is considered part of the preceding 231533965Sjdpstatement. Newlines and separators within character constants are an 231633965Sjdpexception: they do not end statements. 231733965Sjdp@end ifset 231833965Sjdp 231933965Sjdp@cindex newline, required at file end 232033965Sjdp@cindex EOF, newline must precede 232133965SjdpIt is an error to end any statement with end-of-file: the last 232233965Sjdpcharacter of any input file should be a newline.@refill 232333965Sjdp 232433965SjdpAn empty statement is allowed, and may include whitespace. It is ignored. 232533965Sjdp 232633965Sjdp@cindex instructions and directives 232733965Sjdp@cindex directives and instructions 232833965Sjdp@c "key symbol" is not used elsewhere in the document; seems pedantic to 232933965Sjdp@c @defn{} it in that case, as was done previously... doc@cygnus.com, 233033965Sjdp@c 13feb91. 233133965SjdpA statement begins with zero or more labels, optionally followed by a 233233965Sjdpkey symbol which determines what kind of statement it is. The key 233333965Sjdpsymbol determines the syntax of the rest of the statement. If the 233433965Sjdpsymbol begins with a dot @samp{.} then the statement is an assembler 233533965Sjdpdirective: typically valid for any computer. If the symbol begins with 233633965Sjdpa letter the statement is an assembly language @dfn{instruction}: it 233733965Sjdpassembles into a machine language instruction. 233833965Sjdp@ifset GENERIC 233989857SobrienDifferent versions of @command{@value{AS}} for different computers 234033965Sjdprecognize different instructions. In fact, the same symbol may 234133965Sjdprepresent a different instruction in a different computer's assembly 234233965Sjdplanguage.@refill 234333965Sjdp@end ifset 234433965Sjdp 234533965Sjdp@cindex @code{:} (label) 234633965Sjdp@cindex label (@code{:}) 234733965SjdpA label is a symbol immediately followed by a colon (@code{:}). 234833965SjdpWhitespace before a label or after a colon is permitted, but you may not 234933965Sjdphave whitespace between a label's symbol and its colon. @xref{Labels}. 235033965Sjdp 235133965Sjdp@ifset HPPA 235233965SjdpFor HPPA targets, labels need not be immediately followed by a colon, but 235333965Sjdpthe definition of a label must begin in column zero. This also implies that 235433965Sjdponly one label may be defined on each line. 235533965Sjdp@end ifset 235633965Sjdp 235733965Sjdp@smallexample 235833965Sjdplabel: .directive followed by something 235933965Sjdpanother_label: # This is an empty statement. 236033965Sjdp instruction operand_1, operand_2, @dots{} 236133965Sjdp@end smallexample 236233965Sjdp 236333965Sjdp@node Constants 236433965Sjdp@section Constants 236533965Sjdp 236633965Sjdp@cindex constants 236733965SjdpA constant is a number, written so that its value is known by 236833965Sjdpinspection, without knowing any context. Like this: 236933965Sjdp@smallexample 237033965Sjdp@group 237133965Sjdp.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value. 237233965Sjdp.ascii "Ring the bell\7" # A string constant. 237333965Sjdp.octa 0x123456789abcdef0123456789ABCDEF0 # A bignum. 237433965Sjdp.float 0f-314159265358979323846264338327\ 237533965Sjdp95028841971.693993751E-40 # - pi, a flonum. 237633965Sjdp@end group 237733965Sjdp@end smallexample 237833965Sjdp 237933965Sjdp@menu 238033965Sjdp* Characters:: Character Constants 238133965Sjdp* Numbers:: Number Constants 238233965Sjdp@end menu 238333965Sjdp 238433965Sjdp@node Characters 238533965Sjdp@subsection Character Constants 238633965Sjdp 238733965Sjdp@cindex character constants 238833965Sjdp@cindex constants, character 238933965SjdpThere are two kinds of character constants. A @dfn{character} stands 239033965Sjdpfor one character in one byte and its value may be used in 239133965Sjdpnumeric expressions. String constants (properly called string 239233965Sjdp@emph{literals}) are potentially many bytes and their values may not be 239333965Sjdpused in arithmetic expressions. 239433965Sjdp 239533965Sjdp@menu 239633965Sjdp* Strings:: Strings 239733965Sjdp* Chars:: Characters 239833965Sjdp@end menu 239933965Sjdp 240033965Sjdp@node Strings 240133965Sjdp@subsubsection Strings 240233965Sjdp 240333965Sjdp@cindex string constants 240433965Sjdp@cindex constants, string 240533965SjdpA @dfn{string} is written between double-quotes. It may contain 240633965Sjdpdouble-quotes or null characters. The way to get special characters 240733965Sjdpinto a string is to @dfn{escape} these characters: precede them with 240833965Sjdpa backslash @samp{\} character. For example @samp{\\} represents 240933965Sjdpone backslash: the first @code{\} is an escape which tells 241089857Sobrien@command{@value{AS}} to interpret the second character literally as a backslash 241189857Sobrien(which prevents @command{@value{AS}} from recognizing the second @code{\} as an 241233965Sjdpescape character). The complete list of escapes follows. 241333965Sjdp 241433965Sjdp@cindex escape codes, character 241533965Sjdp@cindex character escape codes 241633965Sjdp@table @kbd 241733965Sjdp@c @item \a 241833965Sjdp@c Mnemonic for ACKnowledge; for ASCII this is octal code 007. 241933965Sjdp@c 242033965Sjdp@cindex @code{\b} (backspace character) 242133965Sjdp@cindex backspace (@code{\b}) 242233965Sjdp@item \b 242333965SjdpMnemonic for backspace; for ASCII this is octal code 010. 242433965Sjdp 242533965Sjdp@c @item \e 242633965Sjdp@c Mnemonic for EOText; for ASCII this is octal code 004. 242733965Sjdp@c 242833965Sjdp@cindex @code{\f} (formfeed character) 242933965Sjdp@cindex formfeed (@code{\f}) 243033965Sjdp@item \f 243133965SjdpMnemonic for FormFeed; for ASCII this is octal code 014. 243233965Sjdp 243333965Sjdp@cindex @code{\n} (newline character) 243433965Sjdp@cindex newline (@code{\n}) 243533965Sjdp@item \n 243633965SjdpMnemonic for newline; for ASCII this is octal code 012. 243733965Sjdp 243833965Sjdp@c @item \p 243933965Sjdp@c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}. 244033965Sjdp@c 244133965Sjdp@cindex @code{\r} (carriage return character) 244233965Sjdp@cindex carriage return (@code{\r}) 244333965Sjdp@item \r 244433965SjdpMnemonic for carriage-Return; for ASCII this is octal code 015. 244533965Sjdp 244633965Sjdp@c @item \s 244733965Sjdp@c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with 244833965Sjdp@c other assemblers. 244933965Sjdp@c 245033965Sjdp@cindex @code{\t} (tab) 245133965Sjdp@cindex tab (@code{\t}) 245233965Sjdp@item \t 245333965SjdpMnemonic for horizontal Tab; for ASCII this is octal code 011. 245433965Sjdp 245533965Sjdp@c @item \v 245633965Sjdp@c Mnemonic for Vertical tab; for ASCII this is octal code 013. 245733965Sjdp@c @item \x @var{digit} @var{digit} @var{digit} 245833965Sjdp@c A hexadecimal character code. The numeric code is 3 hexadecimal digits. 245933965Sjdp@c 246033965Sjdp@cindex @code{\@var{ddd}} (octal character code) 246133965Sjdp@cindex octal character code (@code{\@var{ddd}}) 246233965Sjdp@item \ @var{digit} @var{digit} @var{digit} 246333965SjdpAn octal character code. The numeric code is 3 octal digits. 246433965SjdpFor compatibility with other Unix systems, 8 and 9 are accepted as digits: 246533965Sjdpfor example, @code{\008} has the value 010, and @code{\009} the value 011. 246633965Sjdp 246733965Sjdp@cindex @code{\@var{xd...}} (hex character code) 246833965Sjdp@cindex hex character code (@code{\@var{xd...}}) 246933965Sjdp@item \@code{x} @var{hex-digits...} 247033965SjdpA hex character code. All trailing hex digits are combined. Either upper or 247133965Sjdplower case @code{x} works. 247233965Sjdp 247333965Sjdp@cindex @code{\\} (@samp{\} character) 247433965Sjdp@cindex backslash (@code{\\}) 247533965Sjdp@item \\ 247633965SjdpRepresents one @samp{\} character. 247733965Sjdp 247833965Sjdp@c @item \' 247933965Sjdp@c Represents one @samp{'} (accent acute) character. 248033965Sjdp@c This is needed in single character literals 248133965Sjdp@c (@xref{Characters,,Character Constants}.) to represent 248233965Sjdp@c a @samp{'}. 248333965Sjdp@c 248433965Sjdp@cindex @code{\"} (doublequote character) 248533965Sjdp@cindex doublequote (@code{\"}) 248633965Sjdp@item \" 248733965SjdpRepresents one @samp{"} character. Needed in strings to represent 248833965Sjdpthis character, because an unescaped @samp{"} would end the string. 248933965Sjdp 249033965Sjdp@item \ @var{anything-else} 249133965SjdpAny other character when escaped by @kbd{\} gives a warning, but 249233965Sjdpassembles as if the @samp{\} was not present. The idea is that if 249333965Sjdpyou used an escape sequence you clearly didn't want the literal 249489857Sobrieninterpretation of the following character. However @command{@value{AS}} has no 249589857Sobrienother interpretation, so @command{@value{AS}} knows it is giving you the wrong 249633965Sjdpcode and warns you of the fact. 249733965Sjdp@end table 249833965Sjdp 249933965SjdpWhich characters are escapable, and what those escapes represent, 250033965Sjdpvaries widely among assemblers. The current set is what we think 250133965Sjdpthe BSD 4.2 assembler recognizes, and is a subset of what most C 250233965Sjdpcompilers recognize. If you are in doubt, do not use an escape 250333965Sjdpsequence. 250433965Sjdp 250533965Sjdp@node Chars 250633965Sjdp@subsubsection Characters 250733965Sjdp 250833965Sjdp@cindex single character constant 250933965Sjdp@cindex character, single 251033965Sjdp@cindex constant, single character 251133965SjdpA single character may be written as a single quote immediately 251233965Sjdpfollowed by that character. The same escapes apply to characters as 251333965Sjdpto strings. So if you want to write the character backslash, you 251433965Sjdpmust write @kbd{'\\} where the first @code{\} escapes the second 251533965Sjdp@code{\}. As you can see, the quote is an acute accent, not a 251633965Sjdpgrave accent. A newline 251733965Sjdp@ifclear GENERIC 251833965Sjdp@ifclear abnormal-separator 251933965Sjdp(or semicolon @samp{;}) 252033965Sjdp@end ifclear 252133965Sjdp@ifset abnormal-separator 252233965Sjdp@ifset H8 252333965Sjdp(or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the 2524218822SdimRenesas SH) 252533965Sjdp@end ifset 252633965Sjdp@end ifset 252733965Sjdp@end ifclear 252833965Sjdpimmediately following an acute accent is taken as a literal character 252933965Sjdpand does not count as the end of a statement. The value of a character 253033965Sjdpconstant in a numeric expression is the machine's byte-wide code for 253189857Sobrienthat character. @command{@value{AS}} assumes your character code is ASCII: 253233965Sjdp@kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill 253333965Sjdp 253433965Sjdp@node Numbers 253533965Sjdp@subsection Number Constants 253633965Sjdp 253733965Sjdp@cindex constants, number 253833965Sjdp@cindex number constants 253989857Sobrien@command{@value{AS}} distinguishes three kinds of numbers according to how they 254033965Sjdpare stored in the target machine. @emph{Integers} are numbers that 254133965Sjdpwould fit into an @code{int} in the C language. @emph{Bignums} are 254233965Sjdpintegers, but they are stored in more than 32 bits. @emph{Flonums} 254333965Sjdpare floating point numbers, described below. 254433965Sjdp 254533965Sjdp@menu 254633965Sjdp* Integers:: Integers 254733965Sjdp* Bignums:: Bignums 254833965Sjdp* Flonums:: Flonums 254933965Sjdp@ifclear GENERIC 255033965Sjdp@ifset I960 255133965Sjdp* Bit Fields:: Bit Fields 255233965Sjdp@end ifset 255333965Sjdp@end ifclear 255433965Sjdp@end menu 255533965Sjdp 255633965Sjdp@node Integers 255733965Sjdp@subsubsection Integers 255833965Sjdp@cindex integers 255933965Sjdp@cindex constants, integer 256033965Sjdp 256133965Sjdp@cindex binary integers 256233965Sjdp@cindex integers, binary 256333965SjdpA binary integer is @samp{0b} or @samp{0B} followed by zero or more of 256433965Sjdpthe binary digits @samp{01}. 256533965Sjdp 256633965Sjdp@cindex octal integers 256733965Sjdp@cindex integers, octal 256833965SjdpAn octal integer is @samp{0} followed by zero or more of the octal 256933965Sjdpdigits (@samp{01234567}). 257033965Sjdp 257133965Sjdp@cindex decimal integers 257233965Sjdp@cindex integers, decimal 257333965SjdpA decimal integer starts with a non-zero digit followed by zero or 257433965Sjdpmore digits (@samp{0123456789}). 257533965Sjdp 257633965Sjdp@cindex hexadecimal integers 257733965Sjdp@cindex integers, hexadecimal 257833965SjdpA hexadecimal integer is @samp{0x} or @samp{0X} followed by one or 257933965Sjdpmore hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}. 258033965Sjdp 258133965SjdpIntegers have the usual values. To denote a negative integer, use 258233965Sjdpthe prefix operator @samp{-} discussed under expressions 258333965Sjdp(@pxref{Prefix Ops,,Prefix Operators}). 258433965Sjdp 258533965Sjdp@node Bignums 258633965Sjdp@subsubsection Bignums 258733965Sjdp 258833965Sjdp@cindex bignums 258933965Sjdp@cindex constants, bignum 259033965SjdpA @dfn{bignum} has the same syntax and semantics as an integer 259133965Sjdpexcept that the number (or its negative) takes more than 32 bits to 259233965Sjdprepresent in binary. The distinction is made because in some places 259333965Sjdpintegers are permitted while bignums are not. 259433965Sjdp 259533965Sjdp@node Flonums 259633965Sjdp@subsubsection Flonums 259733965Sjdp@cindex flonums 259833965Sjdp@cindex floating point numbers 259933965Sjdp@cindex constants, floating point 260033965Sjdp 260133965Sjdp@cindex precision, floating point 260233965SjdpA @dfn{flonum} represents a floating point number. The translation is 260333965Sjdpindirect: a decimal floating point number from the text is converted by 260489857Sobrien@command{@value{AS}} to a generic binary floating point number of more than 260533965Sjdpsufficient precision. This generic floating point number is converted 260633965Sjdpto a particular computer's floating point format (or formats) by a 260789857Sobrienportion of @command{@value{AS}} specialized to that computer. 260833965Sjdp 260933965SjdpA flonum is written by writing (in order) 261033965Sjdp@itemize @bullet 261133965Sjdp@item 261233965SjdpThe digit @samp{0}. 261333965Sjdp@ifset HPPA 261433965Sjdp(@samp{0} is optional on the HPPA.) 261533965Sjdp@end ifset 261633965Sjdp 261733965Sjdp@item 261889857SobrienA letter, to tell @command{@value{AS}} the rest of the number is a flonum. 261933965Sjdp@ifset GENERIC 262033965Sjdp@kbd{e} is recommended. Case is not important. 262133965Sjdp@ignore 262233965Sjdp@c FIXME: verify if flonum syntax really this vague for most cases 262333965Sjdp(Any otherwise illegal letter works here, but that might be changed. Vax BSD 262433965Sjdp4.2 assembler seems to allow any of @samp{defghDEFGH}.) 262533965Sjdp@end ignore 262633965Sjdp 2627218822SdimOn the H8/300, Renesas / SuperH SH, 262833965Sjdpand AMD 29K architectures, the letter must be 262933965Sjdpone of the letters @samp{DFPRSX} (in upper or lower case). 263033965Sjdp 263138889SjdpOn the ARC, the letter must be one of the letters @samp{DFRS} 263238889Sjdp(in upper or lower case). 263333965Sjdp 263433965SjdpOn the Intel 960 architecture, the letter must be 263533965Sjdpone of the letters @samp{DFT} (in upper or lower case). 263633965Sjdp 263733965SjdpOn the HPPA architecture, the letter must be @samp{E} (upper case only). 263833965Sjdp@end ifset 263933965Sjdp@ifclear GENERIC 264038889Sjdp@ifset ARC 264138889SjdpOne of the letters @samp{DFRS} (in upper or lower case). 264238889Sjdp@end ifset 264333965Sjdp@ifset H8 264433965SjdpOne of the letters @samp{DFPRSX} (in upper or lower case). 264533965Sjdp@end ifset 264633965Sjdp@ifset HPPA 264733965SjdpThe letter @samp{E} (upper case only). 264833965Sjdp@end ifset 264933965Sjdp@ifset I960 265033965SjdpOne of the letters @samp{DFT} (in upper or lower case). 265133965Sjdp@end ifset 265233965Sjdp@end ifclear 265333965Sjdp 265433965Sjdp@item 265533965SjdpAn optional sign: either @samp{+} or @samp{-}. 265633965Sjdp 265733965Sjdp@item 265833965SjdpAn optional @dfn{integer part}: zero or more decimal digits. 265933965Sjdp 266033965Sjdp@item 266133965SjdpAn optional @dfn{fractional part}: @samp{.} followed by zero 266233965Sjdpor more decimal digits. 266333965Sjdp 266433965Sjdp@item 266533965SjdpAn optional exponent, consisting of: 266633965Sjdp 266733965Sjdp@itemize @bullet 266833965Sjdp@item 266933965SjdpAn @samp{E} or @samp{e}. 267033965Sjdp@c I can't find a config where "EXP_CHARS" is other than 'eE', but in 267133965Sjdp@c principle this can perfectly well be different on different targets. 267233965Sjdp@item 267333965SjdpOptional sign: either @samp{+} or @samp{-}. 267433965Sjdp@item 267533965SjdpOne or more decimal digits. 267633965Sjdp@end itemize 267733965Sjdp 267833965Sjdp@end itemize 267933965Sjdp 268033965SjdpAt least one of the integer part or the fractional part must be 268133965Sjdppresent. The floating point number has the usual base-10 value. 268233965Sjdp 268389857Sobrien@command{@value{AS}} does all processing using integers. Flonums are computed 268433965Sjdpindependently of any floating point hardware in the computer running 268589857Sobrien@command{@value{AS}}. 268633965Sjdp 268733965Sjdp@ifclear GENERIC 268833965Sjdp@ifset I960 268933965Sjdp@c Bit fields are written as a general facility but are also controlled 269033965Sjdp@c by a conditional-compilation flag---which is as of now (21mar91) 269133965Sjdp@c turned on only by the i960 config of GAS. 269233965Sjdp@node Bit Fields 269333965Sjdp@subsubsection Bit Fields 269433965Sjdp 269533965Sjdp@cindex bit fields 269633965Sjdp@cindex constants, bit field 269733965SjdpYou can also define numeric constants as @dfn{bit fields}. 2698218822SdimSpecify two numbers separated by a colon--- 269933965Sjdp@example 270033965Sjdp@var{mask}:@var{value} 270133965Sjdp@end example 270233965Sjdp@noindent 270389857Sobrien@command{@value{AS}} applies a bitwise @sc{and} between @var{mask} and 270433965Sjdp@var{value}. 270533965Sjdp 270633965SjdpThe resulting number is then packed 270733965Sjdp@ifset GENERIC 270833965Sjdp@c this conditional paren in case bit fields turned on elsewhere than 960 270933965Sjdp(in host-dependent byte order) 271033965Sjdp@end ifset 271133965Sjdpinto a field whose width depends on which assembler directive has the 271233965Sjdpbit-field as its argument. Overflow (a result from the bitwise and 271333965Sjdprequiring more binary digits to represent) is not an error; instead, 271433965Sjdpmore constants are generated, of the specified width, beginning with the 271533965Sjdpleast significant digits.@refill 271633965Sjdp 271733965SjdpThe directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long}, 271833965Sjdp@code{.short}, and @code{.word} accept bit-field arguments. 271933965Sjdp@end ifset 272033965Sjdp@end ifclear 272133965Sjdp 272233965Sjdp@node Sections 272333965Sjdp@chapter Sections and Relocation 272433965Sjdp@cindex sections 272533965Sjdp@cindex relocation 272633965Sjdp 272733965Sjdp@menu 272833965Sjdp* Secs Background:: Background 272933965Sjdp* Ld Sections:: Linker Sections 273033965Sjdp* As Sections:: Assembler Internal Sections 273133965Sjdp* Sub-Sections:: Sub-Sections 273233965Sjdp* bss:: bss Section 273333965Sjdp@end menu 273433965Sjdp 273533965Sjdp@node Secs Background 273633965Sjdp@section Background 273733965Sjdp 273833965SjdpRoughly, a section is a range of addresses, with no gaps; all data 273933965Sjdp``in'' those addresses is treated the same for some particular purpose. 274033965SjdpFor example there may be a ``read only'' section. 274133965Sjdp 274233965Sjdp@cindex linker, and assembler 274333965Sjdp@cindex assembler, and linker 274433965SjdpThe linker @code{@value{LD}} reads many object files (partial programs) and 274589857Sobriencombines their contents to form a runnable program. When @command{@value{AS}} 274633965Sjdpemits an object file, the partial program is assumed to start at address 0. 274733965Sjdp@code{@value{LD}} assigns the final addresses for the partial program, so that 274833965Sjdpdifferent partial programs do not overlap. This is actually an 274989857Sobrienoversimplification, but it suffices to explain how @command{@value{AS}} uses 275033965Sjdpsections. 275133965Sjdp 275233965Sjdp@code{@value{LD}} moves blocks of bytes of your program to their run-time 275333965Sjdpaddresses. These blocks slide to their run-time addresses as rigid 275433965Sjdpunits; their length does not change and neither does the order of bytes 275533965Sjdpwithin them. Such a rigid unit is called a @emph{section}. Assigning 275633965Sjdprun-time addresses to sections is called @dfn{relocation}. It includes 275733965Sjdpthe task of adjusting mentions of object-file addresses so they refer to 275833965Sjdpthe proper run-time addresses. 275933965Sjdp@ifset H8 2760218822SdimFor the H8/300, and for the Renesas / SuperH SH, 276189857Sobrien@command{@value{AS}} pads sections if needed to 276233965Sjdpensure they end on a word (sixteen bit) boundary. 276333965Sjdp@end ifset 276433965Sjdp 276533965Sjdp@cindex standard assembler sections 276689857SobrienAn object file written by @command{@value{AS}} has at least three sections, any 276733965Sjdpof which may be empty. These are named @dfn{text}, @dfn{data} and 276833965Sjdp@dfn{bss} sections. 276933965Sjdp 2770130561Sobrien@ifset COFF-ELF 277133965Sjdp@ifset GENERIC 2772130561SobrienWhen it generates COFF or ELF output, 277333965Sjdp@end ifset 277489857Sobrien@command{@value{AS}} can also generate whatever other named sections you specify 277533965Sjdpusing the @samp{.section} directive (@pxref{Section,,@code{.section}}). 277633965SjdpIf you do not use any directives that place output in the @samp{.text} 277733965Sjdpor @samp{.data} sections, these sections still exist, but are empty. 277833965Sjdp@end ifset 277933965Sjdp 278033965Sjdp@ifset HPPA 278133965Sjdp@ifset GENERIC 278289857SobrienWhen @command{@value{AS}} generates SOM or ELF output for the HPPA, 278333965Sjdp@end ifset 278489857Sobrien@command{@value{AS}} can also generate whatever other named sections you 278533965Sjdpspecify using the @samp{.space} and @samp{.subspace} directives. See 278633965Sjdp@cite{HP9000 Series 800 Assembly Language Reference Manual} 278733965Sjdp(HP 92432-90001) for details on the @samp{.space} and @samp{.subspace} 278833965Sjdpassembler directives. 278933965Sjdp 279033965Sjdp@ifset SOM 279189857SobrienAdditionally, @command{@value{AS}} uses different names for the standard 279233965Sjdptext, data, and bss sections when generating SOM output. Program text 279333965Sjdpis placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and 279433965SjdpBSS into @samp{$BSS$}. 279533965Sjdp@end ifset 279633965Sjdp@end ifset 279733965Sjdp 279833965SjdpWithin the object file, the text section starts at address @code{0}, the 279933965Sjdpdata section follows, and the bss section follows the data section. 280033965Sjdp 280133965Sjdp@ifset HPPA 280233965SjdpWhen generating either SOM or ELF output files on the HPPA, the text 280333965Sjdpsection starts at address @code{0}, the data section at address 280433965Sjdp@code{0x4000000}, and the bss section follows the data section. 280533965Sjdp@end ifset 280633965Sjdp 280733965SjdpTo let @code{@value{LD}} know which data changes when the sections are 280889857Sobrienrelocated, and how to change that data, @command{@value{AS}} also writes to the 280933965Sjdpobject file details of the relocation needed. To perform relocation 281033965Sjdp@code{@value{LD}} must know, each time an address in the object 281133965Sjdpfile is mentioned: 281233965Sjdp@itemize @bullet 281333965Sjdp@item 281433965SjdpWhere in the object file is the beginning of this reference to 281533965Sjdpan address? 281633965Sjdp@item 281733965SjdpHow long (in bytes) is this reference? 281833965Sjdp@item 281933965SjdpWhich section does the address refer to? What is the numeric value of 282033965Sjdp@display 282133965Sjdp(@var{address}) @minus{} (@var{start-address of section})? 282233965Sjdp@end display 282333965Sjdp@item 282433965SjdpIs the reference to an address ``Program-Counter relative''? 282533965Sjdp@end itemize 282633965Sjdp 282733965Sjdp@cindex addresses, format of 282833965Sjdp@cindex section-relative addressing 282989857SobrienIn fact, every address @command{@value{AS}} ever uses is expressed as 283033965Sjdp@display 283133965Sjdp(@var{section}) + (@var{offset into section}) 283233965Sjdp@end display 283333965Sjdp@noindent 283489857SobrienFurther, most expressions @command{@value{AS}} computes have this section-relative 283533965Sjdpnature. 283633965Sjdp@ifset SOM 283733965Sjdp(For some object formats, such as SOM for the HPPA, some expressions are 283833965Sjdpsymbol-relative instead.) 283933965Sjdp@end ifset 284033965Sjdp 284133965SjdpIn this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset 284233965Sjdp@var{N} into section @var{secname}.'' 284333965Sjdp 284433965SjdpApart from text, data and bss sections you need to know about the 284533965Sjdp@dfn{absolute} section. When @code{@value{LD}} mixes partial programs, 284633965Sjdpaddresses in the absolute section remain unchanged. For example, address 284733965Sjdp@code{@{absolute 0@}} is ``relocated'' to run-time address 0 by 284833965Sjdp@code{@value{LD}}. Although the linker never arranges two partial programs' 284933965Sjdpdata sections with overlapping addresses after linking, @emph{by definition} 285033965Sjdptheir absolute sections must overlap. Address @code{@{absolute@ 239@}} in one 285133965Sjdppart of a program is always the same address when the program is running as 285233965Sjdpaddress @code{@{absolute@ 239@}} in any other part of the program. 285333965Sjdp 285433965SjdpThe idea of sections is extended to the @dfn{undefined} section. Any 285533965Sjdpaddress whose section is unknown at assembly time is by definition 285633965Sjdprendered @{undefined @var{U}@}---where @var{U} is filled in later. 285733965SjdpSince numbers are always defined, the only way to generate an undefined 285833965Sjdpaddress is to mention an undefined symbol. A reference to a named 285933965Sjdpcommon block would be such a symbol: its value is unknown at assembly 286033965Sjdptime so it has section @emph{undefined}. 286133965Sjdp 286233965SjdpBy analogy the word @emph{section} is used to describe groups of sections in 286333965Sjdpthe linked program. @code{@value{LD}} puts all partial programs' text 286433965Sjdpsections in contiguous addresses in the linked program. It is 286533965Sjdpcustomary to refer to the @emph{text section} of a program, meaning all 286633965Sjdpthe addresses of all partial programs' text sections. Likewise for 286733965Sjdpdata and bss sections. 286833965Sjdp 286933965SjdpSome sections are manipulated by @code{@value{LD}}; others are invented for 287089857Sobrienuse of @command{@value{AS}} and have no meaning except during assembly. 287133965Sjdp 287233965Sjdp@node Ld Sections 287333965Sjdp@section Linker Sections 287433965Sjdp@code{@value{LD}} deals with just four kinds of sections, summarized below. 287533965Sjdp 287633965Sjdp@table @strong 287733965Sjdp 2878130561Sobrien@ifset COFF-ELF 287933965Sjdp@cindex named sections 288033965Sjdp@cindex sections, named 288133965Sjdp@item named sections 288233965Sjdp@end ifset 288333965Sjdp@ifset aout-bout 288433965Sjdp@cindex text section 288533965Sjdp@cindex data section 288633965Sjdp@itemx text section 288733965Sjdp@itemx data section 288833965Sjdp@end ifset 288989857SobrienThese sections hold your program. @command{@value{AS}} and @code{@value{LD}} treat them as 289033965Sjdpseparate but equal sections. Anything you can say of one section is 2891130561Sobrientrue of another. 2892130561Sobrien@c @ifset aout-bout 289333965SjdpWhen the program is running, however, it is 289433965Sjdpcustomary for the text section to be unalterable. The 289533965Sjdptext section is often shared among processes: it contains 289633965Sjdpinstructions, constants and the like. The data section of a running 289733965Sjdpprogram is usually alterable: for example, C variables would be stored 289833965Sjdpin the data section. 2899130561Sobrien@c @end ifset 290033965Sjdp 290133965Sjdp@cindex bss section 290233965Sjdp@item bss section 290333965SjdpThis section contains zeroed bytes when your program begins running. It 290477298Sobrienis used to hold uninitialized variables or common storage. The length of 290533965Sjdpeach partial program's bss section is important, but because it starts 290633965Sjdpout containing zeroed bytes there is no need to store explicit zero 290733965Sjdpbytes in the object file. The bss section was invented to eliminate 290833965Sjdpthose explicit zeros from object files. 290933965Sjdp 291033965Sjdp@cindex absolute section 291133965Sjdp@item absolute section 291233965SjdpAddress 0 of this section is always ``relocated'' to runtime address 0. 291333965SjdpThis is useful if you want to refer to an address that @code{@value{LD}} must 291433965Sjdpnot change when relocating. In this sense we speak of absolute 291533965Sjdpaddresses being ``unrelocatable'': they do not change during relocation. 291633965Sjdp 291733965Sjdp@cindex undefined section 291833965Sjdp@item undefined section 291933965SjdpThis ``section'' is a catch-all for address references to objects not in 292033965Sjdpthe preceding sections. 292133965Sjdp@c FIXME: ref to some other doc on obj-file formats could go here. 292233965Sjdp@end table 292333965Sjdp 292433965Sjdp@cindex relocation example 292533965SjdpAn idealized example of three relocatable sections follows. 2926130561Sobrien@ifset COFF-ELF 292733965SjdpThe example uses the traditional section names @samp{.text} and @samp{.data}. 292833965Sjdp@end ifset 292933965SjdpMemory addresses are on the horizontal axis. 293033965Sjdp 293133965Sjdp@c TEXI2ROFF-KILL 2932130561Sobrien@ifnottex 293333965Sjdp@c END TEXI2ROFF-KILL 293433965Sjdp@smallexample 293533965Sjdp +-----+----+--+ 293633965Sjdppartial program # 1: |ttttt|dddd|00| 293733965Sjdp +-----+----+--+ 293833965Sjdp 293933965Sjdp text data bss 294033965Sjdp seg. seg. seg. 294133965Sjdp 294233965Sjdp +---+---+---+ 294333965Sjdppartial program # 2: |TTT|DDD|000| 294433965Sjdp +---+---+---+ 294533965Sjdp 294633965Sjdp +--+---+-----+--+----+---+-----+~~ 294733965Sjdplinked program: | |TTT|ttttt| |dddd|DDD|00000| 294833965Sjdp +--+---+-----+--+----+---+-----+~~ 294933965Sjdp 295033965Sjdp addresses: 0 @dots{} 295133965Sjdp@end smallexample 295233965Sjdp@c TEXI2ROFF-KILL 2953130561Sobrien@end ifnottex 295433965Sjdp@need 5000 295533965Sjdp@tex 2956130561Sobrien\bigskip 295733965Sjdp\line{\it Partial program \#1: \hfil} 295833965Sjdp\line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} 295933965Sjdp\line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil} 296033965Sjdp 296133965Sjdp\line{\it Partial program \#2: \hfil} 296233965Sjdp\line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} 296333965Sjdp\line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil} 296433965Sjdp 296533965Sjdp\line{\it linked program: \hfil} 296633965Sjdp\line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil} 296733965Sjdp\line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt 296833965Sjdpttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt 296933965SjdpDDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil} 297033965Sjdp 297133965Sjdp\line{\it addresses: \hfil} 297233965Sjdp\line{0\dots\hfil} 297333965Sjdp 297433965Sjdp@end tex 297533965Sjdp@c END TEXI2ROFF-KILL 297633965Sjdp 297733965Sjdp@node As Sections 297833965Sjdp@section Assembler Internal Sections 297933965Sjdp 298033965Sjdp@cindex internal assembler sections 298133965Sjdp@cindex sections in messages, internal 298289857SobrienThese sections are meant only for the internal use of @command{@value{AS}}. They 298333965Sjdphave no meaning at run-time. You do not really need to know about these 298489857Sobriensections for most purposes; but they can be mentioned in @command{@value{AS}} 298533965Sjdpwarning messages, so it might be helpful to have an idea of their 298689857Sobrienmeanings to @command{@value{AS}}. These sections are used to permit the 298733965Sjdpvalue of every expression in your assembly language program to be a 298833965Sjdpsection-relative address. 298933965Sjdp 299033965Sjdp@table @b 299133965Sjdp@cindex assembler internal logic error 299233965Sjdp@item ASSEMBLER-INTERNAL-LOGIC-ERROR! 299333965SjdpAn internal assembler logic error has been found. This means there is a 299433965Sjdpbug in the assembler. 299533965Sjdp 299633965Sjdp@cindex expr (internal section) 299733965Sjdp@item expr section 299833965SjdpThe assembler stores complex expression internally as combinations of 299933965Sjdpsymbols. When it needs to represent an expression as a symbol, it puts 300033965Sjdpit in the expr section. 300133965Sjdp@c FIXME item debug 300233965Sjdp@c FIXME item transfer[t] vector preload 300333965Sjdp@c FIXME item transfer[t] vector postload 300433965Sjdp@c FIXME item register 300533965Sjdp@end table 300633965Sjdp 300733965Sjdp@node Sub-Sections 300833965Sjdp@section Sub-Sections 300933965Sjdp 301033965Sjdp@cindex numbered subsections 301133965Sjdp@cindex grouping data 301233965Sjdp@ifset aout-bout 301333965SjdpAssembled bytes 3014130561Sobrien@ifset COFF-ELF 301533965Sjdpconventionally 301633965Sjdp@end ifset 301733965Sjdpfall into two sections: text and data. 301833965Sjdp@end ifset 301933965SjdpYou may have separate groups of 302033965Sjdp@ifset GENERIC 302133965Sjdpdata in named sections 302233965Sjdp@end ifset 302333965Sjdp@ifclear GENERIC 302433965Sjdp@ifclear aout-bout 302533965Sjdpdata in named sections 302633965Sjdp@end ifclear 302733965Sjdp@ifset aout-bout 302833965Sjdptext or data 302933965Sjdp@end ifset 303033965Sjdp@end ifclear 303133965Sjdpthat you want to end up near to each other in the object file, even though they 303289857Sobrienare not contiguous in the assembler source. @command{@value{AS}} allows you to 303333965Sjdpuse @dfn{subsections} for this purpose. Within each section, there can be 303433965Sjdpnumbered subsections with values from 0 to 8192. Objects assembled into the 303533965Sjdpsame subsection go into the object file together with other objects in the same 303633965Sjdpsubsection. For example, a compiler might want to store constants in the text 303733965Sjdpsection, but might not want to have them interspersed with the program being 303833965Sjdpassembled. In this case, the compiler could issue a @samp{.text 0} before each 303933965Sjdpsection of code being output, and a @samp{.text 1} before each group of 304033965Sjdpconstants being output. 304133965Sjdp 304233965SjdpSubsections are optional. If you do not use subsections, everything 304333965Sjdpgoes in subsection number zero. 304433965Sjdp 304533965Sjdp@ifset GENERIC 304633965SjdpEach subsection is zero-padded up to a multiple of four bytes. 304733965Sjdp(Subsections may be padded a different amount on different flavors 304889857Sobrienof @command{@value{AS}}.) 304933965Sjdp@end ifset 305033965Sjdp@ifclear GENERIC 305133965Sjdp@ifset H8 3052218822SdimOn the H8/300 platform, each subsection is zero-padded to a word 305333965Sjdpboundary (two bytes). 3054130561SobrienThe same is true on the Renesas SH. 305533965Sjdp@end ifset 305633965Sjdp@ifset I960 305733965Sjdp@c FIXME section padding (alignment)? 305833965Sjdp@c Rich Pixley says padding here depends on target obj code format; that 305933965Sjdp@c doesn't seem particularly useful to say without further elaboration, 306033965Sjdp@c so for now I say nothing about it. If this is a generic BFD issue, 306133965Sjdp@c these paragraphs might need to vanish from this manual, and be 306233965Sjdp@c discussed in BFD chapter of binutils (or some such). 306333965Sjdp@end ifset 306433965Sjdp@end ifclear 306533965Sjdp 306633965SjdpSubsections appear in your object file in numeric order, lowest numbered 306733965Sjdpto highest. (All this to be compatible with other people's assemblers.) 306833965SjdpThe object file contains no representation of subsections; @code{@value{LD}} and 306933965Sjdpother programs that manipulate object files see no trace of them. 307033965SjdpThey just see all your text subsections as a text section, and all your 307133965Sjdpdata subsections as a data section. 307233965Sjdp 307333965SjdpTo specify which subsection you want subsequent statements assembled 307433965Sjdpinto, use a numeric argument to specify it, in a @samp{.text 307533965Sjdp@var{expression}} or a @samp{.data @var{expression}} statement. 3076218822Sdim@ifset COFF 307733965Sjdp@ifset GENERIC 3078218822SdimWhen generating COFF output, you 307933965Sjdp@end ifset 308033965Sjdp@ifclear GENERIC 308133965SjdpYou 308233965Sjdp@end ifclear 308333965Sjdpcan also use an extra subsection 308433965Sjdpargument with arbitrary named sections: @samp{.section @var{name}, 308533965Sjdp@var{expression}}. 308633965Sjdp@end ifset 3087218822Sdim@ifset ELF 3088218822Sdim@ifset GENERIC 3089218822SdimWhen generating ELF output, you 3090218822Sdim@end ifset 3091218822Sdim@ifclear GENERIC 3092218822SdimYou 3093218822Sdim@end ifclear 3094218822Sdimcan also use the @code{.subsection} directive (@pxref{SubSection}) 3095218822Sdimto specify a subsection: @samp{.subsection @var{expression}}. 3096218822Sdim@end ifset 3097218822Sdim@var{Expression} should be an absolute expression 3098218822Sdim(@pxref{Expressions}). If you just say @samp{.text} then @samp{.text 0} 309933965Sjdpis assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly 310033965Sjdpbegins in @code{text 0}. For instance: 310133965Sjdp@smallexample 310233965Sjdp.text 0 # The default subsection is text 0 anyway. 310333965Sjdp.ascii "This lives in the first text subsection. *" 310433965Sjdp.text 1 310533965Sjdp.ascii "But this lives in the second text subsection." 310633965Sjdp.data 0 310733965Sjdp.ascii "This lives in the data section," 310833965Sjdp.ascii "in the first data subsection." 310933965Sjdp.text 0 311033965Sjdp.ascii "This lives in the first text section," 311133965Sjdp.ascii "immediately following the asterisk (*)." 311233965Sjdp@end smallexample 311333965Sjdp 311433965SjdpEach section has a @dfn{location counter} incremented by one for every byte 311533965Sjdpassembled into that section. Because subsections are merely a convenience 311689857Sobrienrestricted to @command{@value{AS}} there is no concept of a subsection location 311733965Sjdpcounter. There is no way to directly manipulate a location counter---but the 311833965Sjdp@code{.align} directive changes it, and any label definition captures its 311933965Sjdpcurrent value. The location counter of the section where statements are being 312033965Sjdpassembled is said to be the @dfn{active} location counter. 312133965Sjdp 312233965Sjdp@node bss 312333965Sjdp@section bss Section 312433965Sjdp 312533965Sjdp@cindex bss section 312633965Sjdp@cindex common variable storage 312733965SjdpThe bss section is used for local common variable storage. 312833965SjdpYou may allocate address space in the bss section, but you may 312933965Sjdpnot dictate data to load into it before your program executes. When 313033965Sjdpyour program starts running, all the contents of the bss 313133965Sjdpsection are zeroed bytes. 313233965Sjdp 313333965SjdpThe @code{.lcomm} pseudo-op defines a symbol in the bss section; see 313433965Sjdp@ref{Lcomm,,@code{.lcomm}}. 313533965Sjdp 313633965SjdpThe @code{.comm} pseudo-op may be used to declare a common symbol, which is 3137218822Sdimanother form of uninitialized symbol; see @ref{Comm,,@code{.comm}}. 313833965Sjdp 313933965Sjdp@ifset GENERIC 314033965SjdpWhen assembling for a target which supports multiple sections, such as ELF or 314133965SjdpCOFF, you may switch into the @code{.bss} section and define symbols as usual; 314233965Sjdpsee @ref{Section,,@code{.section}}. You may only assemble zero values into the 314333965Sjdpsection. Typically the section will only contain symbol definitions and 314433965Sjdp@code{.skip} directives (@pxref{Skip,,@code{.skip}}). 314533965Sjdp@end ifset 314633965Sjdp 314733965Sjdp@node Symbols 314833965Sjdp@chapter Symbols 314933965Sjdp 315033965Sjdp@cindex symbols 315133965SjdpSymbols are a central concept: the programmer uses symbols to name 315233965Sjdpthings, the linker uses symbols to link, and the debugger uses symbols 315333965Sjdpto debug. 315433965Sjdp 315533965Sjdp@quotation 315633965Sjdp@cindex debuggers, and symbol order 315789857Sobrien@emph{Warning:} @command{@value{AS}} does not place symbols in the object file in 315833965Sjdpthe same order they were declared. This may break some debuggers. 315933965Sjdp@end quotation 316033965Sjdp 316133965Sjdp@menu 316233965Sjdp* Labels:: Labels 316333965Sjdp* Setting Symbols:: Giving Symbols Other Values 316433965Sjdp* Symbol Names:: Symbol Names 316533965Sjdp* Dot:: The Special Dot Symbol 316633965Sjdp* Symbol Attributes:: Symbol Attributes 316733965Sjdp@end menu 316833965Sjdp 316933965Sjdp@node Labels 317033965Sjdp@section Labels 317133965Sjdp 317233965Sjdp@cindex labels 317333965SjdpA @dfn{label} is written as a symbol immediately followed by a colon 317433965Sjdp@samp{:}. The symbol then represents the current value of the 317533965Sjdpactive location counter, and is, for example, a suitable instruction 317633965Sjdpoperand. You are warned if you use the same symbol to represent two 317733965Sjdpdifferent locations: the first definition overrides any other 317833965Sjdpdefinitions. 317933965Sjdp 318033965Sjdp@ifset HPPA 318133965SjdpOn the HPPA, the usual form for a label need not be immediately followed by a 318233965Sjdpcolon, but instead must start in column zero. Only one label may be defined on 318389857Sobriena single line. To work around this, the HPPA version of @command{@value{AS}} also 318433965Sjdpprovides a special directive @code{.label} for defining labels more flexibly. 318533965Sjdp@end ifset 318633965Sjdp 318733965Sjdp@node Setting Symbols 318833965Sjdp@section Giving Symbols Other Values 318933965Sjdp 319033965Sjdp@cindex assigning values to symbols 319133965Sjdp@cindex symbol values, assigning 319233965SjdpA symbol can be given an arbitrary value by writing a symbol, followed 319333965Sjdpby an equals sign @samp{=}, followed by an expression 319433965Sjdp(@pxref{Expressions}). This is equivalent to using the @code{.set} 3195218822Sdimdirective. @xref{Set,,@code{.set}}. In the same way, using a double 3196218822Sdimequals sign @samp{=}@samp{=} here represents an equivalent of the 3197218822Sdim@code{.eqv} directive. @xref{Eqv,,@code{.eqv}}. 319833965Sjdp 319933965Sjdp@node Symbol Names 320033965Sjdp@section Symbol Names 320133965Sjdp 320233965Sjdp@cindex symbol names 320333965Sjdp@cindex names, symbol 320433965Sjdp@ifclear SPECIAL-SYMS 320533965SjdpSymbol names begin with a letter or with one of @samp{._}. On most 320633965Sjdpmachines, you can also use @code{$} in symbol names; exceptions are 320733965Sjdpnoted in @ref{Machine Dependencies}. That character may be followed by any 3208218822Sdimstring of digits, letters, dollar signs (unless otherwise noted for a 3209218822Sdimparticular target machine), and underscores. 321033965Sjdp@end ifclear 321133965Sjdp@ifset SPECIAL-SYMS 321233965Sjdp@ifset H8 321333965SjdpSymbol names begin with a letter or with one of @samp{._}. On the 3214218822SdimRenesas SH you can also use @code{$} in symbol names. That 3215130561Sobriencharacter may be followed by any string of digits, letters, dollar signs (save 3216130561Sobrienon the H8/300), and underscores. 321733965Sjdp@end ifset 321833965Sjdp@end ifset 321933965Sjdp 322033965SjdpCase of letters is significant: @code{foo} is a different symbol name 322133965Sjdpthan @code{Foo}. 322233965Sjdp 322333965SjdpEach symbol has exactly one name. Each name in an assembly language program 322433965Sjdprefers to exactly one symbol. You may use that symbol name any number of times 322533965Sjdpin a program. 322633965Sjdp 322733965Sjdp@subheading Local Symbol Names 322833965Sjdp 322933965Sjdp@cindex local symbol names 323033965Sjdp@cindex symbol names, local 3231218822SdimA local symbol is any symbol beginning with certain local label prefixes. 3232218822SdimBy default, the local label prefix is @samp{.L} for ELF systems or 3233218822Sdim@samp{L} for traditional a.out systems, but each target may have its own 3234218822Sdimset of local label prefixes. 3235218822Sdim@ifset HPPA 3236218822SdimOn the HPPA local symbols begin with @samp{L$}. 3237218822Sdim@end ifset 3238218822Sdim 3239218822SdimLocal symbols are defined and used within the assembler, but they are 3240218822Sdimnormally not saved in object files. Thus, they are not visible when debugging. 3241218822SdimYou may use the @samp{-L} option (@pxref{L, ,Include Local Symbols: 3242218822Sdim@option{-L}}) to retain the local symbols in the object files. 3243218822Sdim 3244218822Sdim@subheading Local Labels 3245218822Sdim 3246218822Sdim@cindex local labels 324733965Sjdp@cindex temporary symbol names 324833965Sjdp@cindex symbol names, temporary 3249218822SdimLocal labels help compilers and programmers use names temporarily. 325089857SobrienThey create symbols which are guaranteed to be unique over the entire scope of 325189857Sobrienthe input source code and which can be referred to by a simple notation. 3252218822SdimTo define a local label, write a label of the form @samp{@b{N}:} (where @b{N} 325389857Sobrienrepresents any positive integer). To refer to the most recent previous 3254218822Sdimdefinition of that label write @samp{@b{N}b}, using the same number as when 325589857Sobrienyou defined the label. To refer to the next definition of a local label, write 3256218822Sdim@samp{@b{N}f}---the @samp{b} stands for ``backwards'' and the @samp{f} stands 325789857Sobrienfor ``forwards''. 325833965Sjdp 325989857SobrienThere is no restriction on how you can use these labels, and you can reuse them 326089857Sobrientoo. So that it is possible to repeatedly define the same local label (using 326189857Sobrienthe same number @samp{@b{N}}), although you can only refer to the most recently 326289857Sobriendefined local label of that number (for a backwards reference) or the next 326389857Sobriendefinition of a specific local label for a forward reference. It is also worth 326489857Sobriennoting that the first 10 local labels (@samp{@b{0:}}@dots{}@samp{@b{9:}}) are 326589857Sobrienimplemented in a slightly more efficient manner than the others. 326633965Sjdp 326789857SobrienHere is an example: 326833965Sjdp 326989857Sobrien@smallexample 327089857Sobrien1: branch 1f 327189857Sobrien2: branch 1b 327289857Sobrien1: branch 2f 327389857Sobrien2: branch 1b 327489857Sobrien@end smallexample 327589857Sobrien 327689857SobrienWhich is the equivalent of: 327789857Sobrien 327889857Sobrien@smallexample 327989857Sobrienlabel_1: branch label_3 328089857Sobrienlabel_2: branch label_1 328189857Sobrienlabel_3: branch label_4 328289857Sobrienlabel_4: branch label_3 328389857Sobrien@end smallexample 328489857Sobrien 3285218822SdimLocal label names are only a notational device. They are immediately 328689857Sobrientransformed into more conventional symbol names before the assembler uses them. 3287218822SdimThe symbol names are stored in the symbol table, appear in error messages, and 3288218822Sdimare optionally emitted to the object file. The names are constructed using 3289218822Sdimthese parts: 329033965Sjdp 329133965Sjdp@table @code 3292218822Sdim@item @emph{local label prefix} 3293218822SdimAll local symbols begin with the system-specific local label prefix. 3294218822SdimNormally both @command{@value{AS}} and @code{@value{LD}} forget symbols 3295218822Sdimthat start with the local label prefix. These labels are 329633965Sjdpused for symbols you are never intended to see. If you use the 329789857Sobrien@samp{-L} option then @command{@value{AS}} retains these symbols in the 329833965Sjdpobject file. If you also instruct @code{@value{LD}} to retain these symbols, 329933965Sjdpyou may use them in debugging. 330033965Sjdp 330189857Sobrien@item @var{number} 330289857SobrienThis is the number that was used in the local label definition. So if the 330389857Sobrienlabel is written @samp{55:} then the number is @samp{55}. 330433965Sjdp 330589857Sobrien@item @kbd{C-B} 330689857SobrienThis unusual character is included so you do not accidentally invent a symbol 330789857Sobrienof the same name. The character has ASCII value of @samp{\002} (control-B). 330833965Sjdp 330933965Sjdp@item @emph{ordinal number} 331089857SobrienThis is a serial number to keep the labels distinct. The first definition of 331189857Sobrien@samp{0:} gets the number @samp{1}. The 15th definition of @samp{0:} gets the 331289857Sobriennumber @samp{15}, and so on. Likewise the first definition of @samp{1:} gets 3313218822Sdimthe number @samp{1} and its 15th definition gets @samp{15} as well. 331433965Sjdp@end table 331533965Sjdp 3316218822SdimSo for example, the first @code{1:} may be named @code{.L1@kbd{C-B}1}, and 3317218822Sdimthe 44th @code{3:} may be named @code{.L3@kbd{C-B}44}. 331833965Sjdp 331989857Sobrien@subheading Dollar Local Labels 332089857Sobrien@cindex dollar local symbols 332189857Sobrien 332289857Sobrien@code{@value{AS}} also supports an even more local form of local labels called 3323218822Sdimdollar labels. These labels go out of scope (i.e., they become undefined) as 3324218822Sdimsoon as a non-local label is defined. Thus they remain valid for only a small 332589857Sobrienregion of the input source code. Normal local labels, by contrast, remain in 332689857Sobrienscope for the entire file, or until they are redefined by another occurrence of 332789857Sobrienthe same local label. 332889857Sobrien 332989857SobrienDollar labels are defined in exactly the same way as ordinary local labels, 333089857Sobrienexcept that instead of being terminated by a colon, they are terminated by a 3331218822Sdimdollar sign, e.g., @samp{@b{55$}}. 333289857Sobrien 333389857SobrienThey can also be distinguished from ordinary local labels by their transformed 3334218822Sdimnames which use ASCII character @samp{\001} (control-A) as the magic character 3335218822Sdimto distinguish them from ordinary labels. For example, the fifth definition of 3336218822Sdim@samp{6$} may be named @samp{.L6@kbd{C-A}5}. 333789857Sobrien 333833965Sjdp@node Dot 333933965Sjdp@section The Special Dot Symbol 334033965Sjdp 334133965Sjdp@cindex dot (symbol) 334233965Sjdp@cindex @code{.} (symbol) 334333965Sjdp@cindex current address 334433965Sjdp@cindex location counter 334533965SjdpThe special symbol @samp{.} refers to the current address that 334689857Sobrien@command{@value{AS}} is assembling into. Thus, the expression @samp{melvin: 334733965Sjdp.long .} defines @code{melvin} to contain its own address. 334833965SjdpAssigning a value to @code{.} is treated the same as a @code{.org} 334933965Sjdpdirective. Thus, the expression @samp{.=.+4} is the same as saying 335033965Sjdp@ifclear no-space-dir 335133965Sjdp@samp{.space 4}. 335233965Sjdp@end ifclear 335333965Sjdp 335433965Sjdp@node Symbol Attributes 335533965Sjdp@section Symbol Attributes 335633965Sjdp 335733965Sjdp@cindex symbol attributes 335833965Sjdp@cindex attributes, symbol 335933965SjdpEvery symbol has, as well as its name, the attributes ``Value'' and 336033965Sjdp``Type''. Depending on output format, symbols can also have auxiliary 336133965Sjdpattributes. 336233965Sjdp@ifset INTERNALS 336333965SjdpThe detailed definitions are in @file{a.out.h}. 336433965Sjdp@end ifset 336533965Sjdp 336689857SobrienIf you use a symbol without defining it, @command{@value{AS}} assumes zero for 336733965Sjdpall these attributes, and probably won't warn you. This makes the 336833965Sjdpsymbol an externally defined symbol, which is generally what you 336933965Sjdpwould want. 337033965Sjdp 337133965Sjdp@menu 337233965Sjdp* Symbol Value:: Value 337333965Sjdp* Symbol Type:: Type 337433965Sjdp@ifset aout-bout 337533965Sjdp@ifset GENERIC 337633965Sjdp* a.out Symbols:: Symbol Attributes: @code{a.out} 337733965Sjdp@end ifset 337833965Sjdp@ifclear GENERIC 337933965Sjdp@ifclear BOUT 338033965Sjdp* a.out Symbols:: Symbol Attributes: @code{a.out} 338133965Sjdp@end ifclear 338233965Sjdp@ifset BOUT 338333965Sjdp* a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out} 338433965Sjdp@end ifset 338533965Sjdp@end ifclear 338633965Sjdp@end ifset 338733965Sjdp@ifset COFF 338833965Sjdp* COFF Symbols:: Symbol Attributes for COFF 338933965Sjdp@end ifset 339033965Sjdp@ifset SOM 339133965Sjdp* SOM Symbols:: Symbol Attributes for SOM 339233965Sjdp@end ifset 339333965Sjdp@end menu 339433965Sjdp 339533965Sjdp@node Symbol Value 339633965Sjdp@subsection Value 339733965Sjdp 339833965Sjdp@cindex value of a symbol 339933965Sjdp@cindex symbol value 340033965SjdpThe value of a symbol is (usually) 32 bits. For a symbol which labels a 340133965Sjdplocation in the text, data, bss or absolute sections the value is the 340233965Sjdpnumber of addresses from the start of that section to the label. 340333965SjdpNaturally for text, data and bss sections the value of a symbol changes 340433965Sjdpas @code{@value{LD}} changes section base addresses during linking. Absolute 340533965Sjdpsymbols' values do not change during linking: that is why they are 340633965Sjdpcalled absolute. 340733965Sjdp 340833965SjdpThe value of an undefined symbol is treated in a special way. If it is 340933965Sjdp0 then the symbol is not defined in this assembler source file, and 341033965Sjdp@code{@value{LD}} tries to determine its value from other files linked into the 341133965Sjdpsame program. You make this kind of symbol simply by mentioning a symbol 341233965Sjdpname without defining it. A non-zero value represents a @code{.comm} 341333965Sjdpcommon declaration. The value is how much common storage to reserve, in 341433965Sjdpbytes (addresses). The symbol refers to the first address of the 341533965Sjdpallocated storage. 341633965Sjdp 341733965Sjdp@node Symbol Type 341833965Sjdp@subsection Type 341933965Sjdp 342033965Sjdp@cindex type of a symbol 342133965Sjdp@cindex symbol type 342233965SjdpThe type attribute of a symbol contains relocation (section) 342333965Sjdpinformation, any flag settings indicating that a symbol is external, and 342433965Sjdp(optionally), other information for linkers and debuggers. The exact 342533965Sjdpformat depends on the object-code output format in use. 342633965Sjdp 342733965Sjdp@ifset aout-bout 342833965Sjdp@ifclear GENERIC 342933965Sjdp@ifset BOUT 343033965Sjdp@c The following avoids a "widow" subsection title. @group would be 343133965Sjdp@c better if it were available outside examples. 343233965Sjdp@need 1000 343333965Sjdp@node a.out Symbols 343433965Sjdp@subsection Symbol Attributes: @code{a.out}, @code{b.out} 343533965Sjdp 343633965Sjdp@cindex @code{b.out} symbol attributes 343733965Sjdp@cindex symbol attributes, @code{b.out} 343889857SobrienThese symbol attributes appear only when @command{@value{AS}} is configured for 343933965Sjdpone of the Berkeley-descended object output formats---@code{a.out} or 344033965Sjdp@code{b.out}. 344133965Sjdp 344233965Sjdp@end ifset 344333965Sjdp@ifclear BOUT 344433965Sjdp@node a.out Symbols 344533965Sjdp@subsection Symbol Attributes: @code{a.out} 344633965Sjdp 344733965Sjdp@cindex @code{a.out} symbol attributes 344833965Sjdp@cindex symbol attributes, @code{a.out} 344933965Sjdp 345033965Sjdp@end ifclear 345133965Sjdp@end ifclear 345233965Sjdp@ifset GENERIC 345333965Sjdp@node a.out Symbols 345433965Sjdp@subsection Symbol Attributes: @code{a.out} 345533965Sjdp 345633965Sjdp@cindex @code{a.out} symbol attributes 345733965Sjdp@cindex symbol attributes, @code{a.out} 345833965Sjdp 345933965Sjdp@end ifset 346033965Sjdp@menu 346133965Sjdp* Symbol Desc:: Descriptor 346233965Sjdp* Symbol Other:: Other 346333965Sjdp@end menu 346433965Sjdp 346533965Sjdp@node Symbol Desc 346633965Sjdp@subsubsection Descriptor 346733965Sjdp 346833965Sjdp@cindex descriptor, of @code{a.out} symbol 346933965SjdpThis is an arbitrary 16-bit value. You may establish a symbol's 347033965Sjdpdescriptor value by using a @code{.desc} statement 347133965Sjdp(@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to 347289857Sobrien@command{@value{AS}}. 347333965Sjdp 347433965Sjdp@node Symbol Other 347533965Sjdp@subsubsection Other 347633965Sjdp 347733965Sjdp@cindex other attribute, of @code{a.out} symbol 347889857SobrienThis is an arbitrary 8-bit value. It means nothing to @command{@value{AS}}. 347933965Sjdp@end ifset 348033965Sjdp 348133965Sjdp@ifset COFF 348233965Sjdp@node COFF Symbols 348333965Sjdp@subsection Symbol Attributes for COFF 348433965Sjdp 348533965Sjdp@cindex COFF symbol attributes 348633965Sjdp@cindex symbol attributes, COFF 348733965Sjdp 348833965SjdpThe COFF format supports a multitude of auxiliary symbol attributes; 348933965Sjdplike the primary symbol attributes, they are set between @code{.def} and 349033965Sjdp@code{.endef} directives. 349133965Sjdp 349233965Sjdp@subsubsection Primary Attributes 349333965Sjdp 349433965Sjdp@cindex primary attributes, COFF symbols 349533965SjdpThe symbol name is set with @code{.def}; the value and type, 349633965Sjdprespectively, with @code{.val} and @code{.type}. 349733965Sjdp 349833965Sjdp@subsubsection Auxiliary Attributes 349933965Sjdp 350033965Sjdp@cindex auxiliary attributes, COFF symbols 350189857SobrienThe @command{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl}, 3502218822Sdim@code{.size}, @code{.tag}, and @code{.weak} can generate auxiliary symbol 3503218822Sdimtable information for COFF. 350433965Sjdp@end ifset 350533965Sjdp 350633965Sjdp@ifset SOM 350733965Sjdp@node SOM Symbols 350833965Sjdp@subsection Symbol Attributes for SOM 350933965Sjdp 351033965Sjdp@cindex SOM symbol attributes 351133965Sjdp@cindex symbol attributes, SOM 351233965Sjdp 351333965SjdpThe SOM format for the HPPA supports a multitude of symbol attributes set with 351433965Sjdpthe @code{.EXPORT} and @code{.IMPORT} directives. 351533965Sjdp 351633965SjdpThe attributes are described in @cite{HP9000 Series 800 Assembly 351733965SjdpLanguage Reference Manual} (HP 92432-90001) under the @code{IMPORT} and 351833965Sjdp@code{EXPORT} assembler directive documentation. 351933965Sjdp@end ifset 352033965Sjdp 352133965Sjdp@node Expressions 352233965Sjdp@chapter Expressions 352333965Sjdp 352433965Sjdp@cindex expressions 352533965Sjdp@cindex addresses 352633965Sjdp@cindex numeric values 352733965SjdpAn @dfn{expression} specifies an address or numeric value. 352833965SjdpWhitespace may precede and/or follow an expression. 352933965Sjdp 353033965SjdpThe result of an expression must be an absolute number, or else an offset into 353133965Sjdpa particular section. If an expression is not absolute, and there is not 353289857Sobrienenough information when @command{@value{AS}} sees the expression to know its 353333965Sjdpsection, a second pass over the source program might be necessary to interpret 353433965Sjdpthe expression---but the second pass is currently not implemented. 353589857Sobrien@command{@value{AS}} aborts with an error message in this situation. 353633965Sjdp 353733965Sjdp@menu 353833965Sjdp* Empty Exprs:: Empty Expressions 353933965Sjdp* Integer Exprs:: Integer Expressions 354033965Sjdp@end menu 354133965Sjdp 354233965Sjdp@node Empty Exprs 354333965Sjdp@section Empty Expressions 354433965Sjdp 354533965Sjdp@cindex empty expressions 354633965Sjdp@cindex expressions, empty 354733965SjdpAn empty expression has no value: it is just whitespace or null. 354833965SjdpWherever an absolute expression is required, you may omit the 354989857Sobrienexpression, and @command{@value{AS}} assumes a value of (absolute) 0. This 355033965Sjdpis compatible with other assemblers. 355133965Sjdp 355233965Sjdp@node Integer Exprs 355333965Sjdp@section Integer Expressions 355433965Sjdp 355533965Sjdp@cindex integer expressions 355633965Sjdp@cindex expressions, integer 355733965SjdpAn @dfn{integer expression} is one or more @emph{arguments} delimited 355833965Sjdpby @emph{operators}. 355933965Sjdp 356033965Sjdp@menu 356133965Sjdp* Arguments:: Arguments 356233965Sjdp* Operators:: Operators 356333965Sjdp* Prefix Ops:: Prefix Operators 356433965Sjdp* Infix Ops:: Infix Operators 356533965Sjdp@end menu 356633965Sjdp 356733965Sjdp@node Arguments 356833965Sjdp@subsection Arguments 356933965Sjdp 357033965Sjdp@cindex expression arguments 357133965Sjdp@cindex arguments in expressions 357233965Sjdp@cindex operands in expressions 357333965Sjdp@cindex arithmetic operands 357433965Sjdp@dfn{Arguments} are symbols, numbers or subexpressions. In other 357533965Sjdpcontexts arguments are sometimes called ``arithmetic operands''. In 357633965Sjdpthis manual, to avoid confusing them with the ``instruction operands'' of 357733965Sjdpthe machine language, we use the term ``argument'' to refer to parts of 357833965Sjdpexpressions only, reserving the word ``operand'' to refer only to machine 357933965Sjdpinstruction operands. 358033965Sjdp 358133965SjdpSymbols are evaluated to yield @{@var{section} @var{NNN}@} where 358233965Sjdp@var{section} is one of text, data, bss, absolute, 358333965Sjdpor undefined. @var{NNN} is a signed, 2's complement 32 bit 358433965Sjdpinteger. 358533965Sjdp 358633965SjdpNumbers are usually integers. 358733965Sjdp 358833965SjdpA number can be a flonum or bignum. In this case, you are warned 358989857Sobrienthat only the low order 32 bits are used, and @command{@value{AS}} pretends 359033965Sjdpthese 32 bits are an integer. You may write integer-manipulating 359133965Sjdpinstructions that act on exotic constants, compatible with other 359233965Sjdpassemblers. 359333965Sjdp 359433965Sjdp@cindex subexpressions 359533965SjdpSubexpressions are a left parenthesis @samp{(} followed by an integer 359633965Sjdpexpression, followed by a right parenthesis @samp{)}; or a prefix 359733965Sjdpoperator followed by an argument. 359833965Sjdp 359933965Sjdp@node Operators 360033965Sjdp@subsection Operators 360133965Sjdp 360233965Sjdp@cindex operators, in expressions 360333965Sjdp@cindex arithmetic functions 360433965Sjdp@cindex functions, in expressions 360533965Sjdp@dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix 360633965Sjdpoperators are followed by an argument. Infix operators appear 360733965Sjdpbetween their arguments. Operators may be preceded and/or followed by 360833965Sjdpwhitespace. 360933965Sjdp 361033965Sjdp@node Prefix Ops 361133965Sjdp@subsection Prefix Operator 361233965Sjdp 361333965Sjdp@cindex prefix operators 361489857Sobrien@command{@value{AS}} has the following @dfn{prefix operators}. They each take 361533965Sjdpone argument, which must be absolute. 361633965Sjdp 361733965Sjdp@c the tex/end tex stuff surrounding this small table is meant to make 361833965Sjdp@c it align, on the printed page, with the similar table in the next 361933965Sjdp@c section (which is inside an enumerate). 362033965Sjdp@tex 362133965Sjdp\global\advance\leftskip by \itemindent 362233965Sjdp@end tex 362333965Sjdp 362433965Sjdp@table @code 362533965Sjdp@item - 362633965Sjdp@dfn{Negation}. Two's complement negation. 362733965Sjdp@item ~ 362833965Sjdp@dfn{Complementation}. Bitwise not. 362933965Sjdp@end table 363033965Sjdp 363133965Sjdp@tex 363233965Sjdp\global\advance\leftskip by -\itemindent 363333965Sjdp@end tex 363433965Sjdp 363533965Sjdp@node Infix Ops 363633965Sjdp@subsection Infix Operators 363733965Sjdp 363833965Sjdp@cindex infix operators 363933965Sjdp@cindex operators, permitted arguments 364033965Sjdp@dfn{Infix operators} take two arguments, one on either side. Operators 364133965Sjdphave precedence, but operations with equal precedence are performed left 364289857Sobriento right. Apart from @code{+} or @option{-}, both arguments must be 364333965Sjdpabsolute, and the result is absolute. 364433965Sjdp 364533965Sjdp@enumerate 364633965Sjdp@cindex operator precedence 364733965Sjdp@cindex precedence of operators 364833965Sjdp 364933965Sjdp@item 365033965SjdpHighest Precedence 365133965Sjdp 365233965Sjdp@table @code 365333965Sjdp@item * 365433965Sjdp@dfn{Multiplication}. 365533965Sjdp 365633965Sjdp@item / 365733965Sjdp@dfn{Division}. Truncation is the same as the C operator @samp{/} 365833965Sjdp 365933965Sjdp@item % 366033965Sjdp@dfn{Remainder}. 366133965Sjdp 3662218822Sdim@item << 366333965Sjdp@dfn{Shift Left}. Same as the C operator @samp{<<}. 366433965Sjdp 3665218822Sdim@item >> 366633965Sjdp@dfn{Shift Right}. Same as the C operator @samp{>>}. 366733965Sjdp@end table 366833965Sjdp 366933965Sjdp@item 367033965SjdpIntermediate precedence 367133965Sjdp 367233965Sjdp@table @code 367333965Sjdp@item | 367433965Sjdp 367533965Sjdp@dfn{Bitwise Inclusive Or}. 367633965Sjdp 367733965Sjdp@item & 367833965Sjdp@dfn{Bitwise And}. 367933965Sjdp 368033965Sjdp@item ^ 368133965Sjdp@dfn{Bitwise Exclusive Or}. 368233965Sjdp 368333965Sjdp@item ! 368433965Sjdp@dfn{Bitwise Or Not}. 368533965Sjdp@end table 368633965Sjdp 368733965Sjdp@item 368878828SobrienLow Precedence 368933965Sjdp 369033965Sjdp@table @code 369133965Sjdp@cindex addition, permitted arguments 369233965Sjdp@cindex plus, permitted arguments 369333965Sjdp@cindex arguments for addition 369433965Sjdp@item + 369533965Sjdp@dfn{Addition}. If either argument is absolute, the result has the section of 369633965Sjdpthe other argument. You may not add together arguments from different 369733965Sjdpsections. 369833965Sjdp 369933965Sjdp@cindex subtraction, permitted arguments 370033965Sjdp@cindex minus, permitted arguments 370133965Sjdp@cindex arguments for subtraction 370233965Sjdp@item - 370333965Sjdp@dfn{Subtraction}. If the right argument is absolute, the 370433965Sjdpresult has the section of the left argument. 370533965SjdpIf both arguments are in the same section, the result is absolute. 370633965SjdpYou may not subtract arguments from different sections. 370733965Sjdp@c FIXME is there still something useful to say about undefined - undefined ? 370878828Sobrien 370978828Sobrien@cindex comparison expressions 371078828Sobrien@cindex expressions, comparison 371178828Sobrien@item == 371278828Sobrien@dfn{Is Equal To} 371378828Sobrien@item <> 3714218822Sdim@itemx != 371578828Sobrien@dfn{Is Not Equal To} 371678828Sobrien@item < 371778828Sobrien@dfn{Is Less Than} 3718218822Sdim@item > 371978828Sobrien@dfn{Is Greater Than} 3720218822Sdim@item >= 372178828Sobrien@dfn{Is Greater Than Or Equal To} 3722218822Sdim@item <= 372378828Sobrien@dfn{Is Less Than Or Equal To} 372478828Sobrien 372578828SobrienThe comparison operators can be used as infix operators. A true results has a 372678828Sobrienvalue of -1 whereas a false result has a value of 0. Note, these operators 372778828Sobrienperform signed comparisons. 372833965Sjdp@end table 372978828Sobrien 373078828Sobrien@item Lowest Precedence 373178828Sobrien 373278828Sobrien@table @code 373378828Sobrien@item && 373478828Sobrien@dfn{Logical And}. 373578828Sobrien 373678828Sobrien@item || 373778828Sobrien@dfn{Logical Or}. 373878828Sobrien 373978828SobrienThese two logical operations can be used to combine the results of sub 374078828Sobrienexpressions. Note, unlike the comparison operators a true result returns a 374178828Sobrienvalue of 1 but a false results does still return 0. Also note that the logical 374278828Sobrienor operator has a slightly lower precedence than logical and. 374378828Sobrien 374478828Sobrien@end table 374533965Sjdp@end enumerate 374633965Sjdp 374733965SjdpIn short, it's only meaningful to add or subtract the @emph{offsets} in an 374833965Sjdpaddress; you can only have a defined section in one of the two arguments. 374933965Sjdp 375033965Sjdp@node Pseudo Ops 375133965Sjdp@chapter Assembler Directives 375233965Sjdp 375333965Sjdp@cindex directives, machine independent 375433965Sjdp@cindex pseudo-ops, machine independent 375533965Sjdp@cindex machine independent directives 375633965SjdpAll assembler directives have names that begin with a period (@samp{.}). 375733965SjdpThe rest of the name is letters, usually in lower case. 375833965Sjdp 375933965SjdpThis chapter discusses directives that are available regardless of the 376033965Sjdptarget machine configuration for the @sc{gnu} assembler. 376133965Sjdp@ifset GENERIC 376233965SjdpSome machine configurations provide additional directives. 376333965Sjdp@xref{Machine Dependencies}. 376433965Sjdp@end ifset 376533965Sjdp@ifclear GENERIC 376633965Sjdp@ifset machine-directives 3767218822Sdim@xref{Machine Dependencies}, for additional directives. 376833965Sjdp@end ifset 376933965Sjdp@end ifclear 377033965Sjdp 377133965Sjdp@menu 377233965Sjdp* Abort:: @code{.abort} 377333965Sjdp@ifset COFF 3774218822Sdim* ABORT (COFF):: @code{.ABORT} 377533965Sjdp@end ifset 377633965Sjdp 377733965Sjdp* Align:: @code{.align @var{abs-expr} , @var{abs-expr}} 3778218822Sdim* Altmacro:: @code{.altmacro} 377933965Sjdp* Ascii:: @code{.ascii "@var{string}"}@dots{} 378033965Sjdp* Asciz:: @code{.asciz "@var{string}"}@dots{} 378133965Sjdp* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}} 378233965Sjdp* Byte:: @code{.byte @var{expressions}} 378333965Sjdp* Comm:: @code{.comm @var{symbol} , @var{length} } 3784130561Sobrien 3785218822Sdim* CFI directives:: @code{.cfi_startproc [simple]}, @code{.cfi_endproc}, etc. 3786130561Sobrien 378733965Sjdp* Data:: @code{.data @var{subsection}} 378833965Sjdp@ifset COFF 378933965Sjdp* Def:: @code{.def @var{name}} 379033965Sjdp@end ifset 379133965Sjdp@ifset aout-bout 379233965Sjdp* Desc:: @code{.desc @var{symbol}, @var{abs-expression}} 379333965Sjdp@end ifset 379433965Sjdp@ifset COFF 379533965Sjdp* Dim:: @code{.dim} 379633965Sjdp@end ifset 379733965Sjdp 379833965Sjdp* Double:: @code{.double @var{flonums}} 379933965Sjdp* Eject:: @code{.eject} 380033965Sjdp* Else:: @code{.else} 380160484Sobrien* Elseif:: @code{.elseif} 380260484Sobrien* End:: @code{.end} 380333965Sjdp@ifset COFF 380433965Sjdp* Endef:: @code{.endef} 380533965Sjdp@end ifset 380633965Sjdp 380760484Sobrien* Endfunc:: @code{.endfunc} 380833965Sjdp* Endif:: @code{.endif} 380933965Sjdp* Equ:: @code{.equ @var{symbol}, @var{expression}} 381033965Sjdp* Equiv:: @code{.equiv @var{symbol}, @var{expression}} 3811218822Sdim* Eqv:: @code{.eqv @var{symbol}, @var{expression}} 381233965Sjdp* Err:: @code{.err} 3813218822Sdim* Error:: @code{.error @var{string}} 381460484Sobrien* Exitm:: @code{.exitm} 381533965Sjdp* Extern:: @code{.extern} 381660484Sobrien* Fail:: @code{.fail} 381733965Sjdp@ifclear no-file-dir 381833965Sjdp* File:: @code{.file @var{string}} 381933965Sjdp@end ifclear 382033965Sjdp 382133965Sjdp* Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}} 382233965Sjdp* Float:: @code{.float @var{flonums}} 382360484Sobrien* Func:: @code{.func} 382433965Sjdp* Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}} 382577298Sobrien@ifset ELF 382677298Sobrien* Hidden:: @code{.hidden @var{names}} 382777298Sobrien@end ifset 382877298Sobrien 382933965Sjdp* hword:: @code{.hword @var{expressions}} 383033965Sjdp* Ident:: @code{.ident} 383133965Sjdp* If:: @code{.if @var{absolute expression}} 383289857Sobrien* Incbin:: @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]} 383333965Sjdp* Include:: @code{.include "@var{file}"} 383433965Sjdp* Int:: @code{.int @var{expressions}} 383577298Sobrien@ifset ELF 383677298Sobrien* Internal:: @code{.internal @var{names}} 383777298Sobrien@end ifset 383877298Sobrien 383933965Sjdp* Irp:: @code{.irp @var{symbol},@var{values}}@dots{} 384033965Sjdp* Irpc:: @code{.irpc @var{symbol},@var{values}}@dots{} 384133965Sjdp* Lcomm:: @code{.lcomm @var{symbol} , @var{length}} 384233965Sjdp* Lflags:: @code{.lflags} 384333965Sjdp@ifclear no-line-dir 384433965Sjdp* Line:: @code{.line @var{line-number}} 384533965Sjdp@end ifclear 384633965Sjdp 384733965Sjdp* Linkonce:: @code{.linkonce [@var{type}]} 384833965Sjdp* List:: @code{.list} 3849218822Sdim* Ln:: @code{.ln @var{line-number}} 3850218822Sdim 3851218822Sdim* LNS directives:: @code{.file}, @code{.loc}, etc. 3852218822Sdim 385333965Sjdp* Long:: @code{.long @var{expressions}} 385433965Sjdp@ignore 385533965Sjdp* Lsym:: @code{.lsym @var{symbol}, @var{expression}} 385633965Sjdp@end ignore 385733965Sjdp 385833965Sjdp* Macro:: @code{.macro @var{name} @var{args}}@dots{} 385933965Sjdp* MRI:: @code{.mri @var{val}} 3860218822Sdim* Noaltmacro:: @code{.noaltmacro} 386133965Sjdp* Nolist:: @code{.nolist} 386233965Sjdp* Octa:: @code{.octa @var{bignums}} 3863218822Sdim* Org:: @code{.org @var{new-lc}, @var{fill}} 3864218822Sdim* P2align:: @code{.p2align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} 386577298Sobrien@ifset ELF 386677298Sobrien* PopSection:: @code{.popsection} 386777298Sobrien* Previous:: @code{.previous} 386877298Sobrien@end ifset 386977298Sobrien 387060484Sobrien* Print:: @code{.print @var{string}} 387177298Sobrien@ifset ELF 387277298Sobrien* Protected:: @code{.protected @var{names}} 387377298Sobrien@end ifset 387477298Sobrien 387533965Sjdp* Psize:: @code{.psize @var{lines}, @var{columns}} 387660484Sobrien* Purgem:: @code{.purgem @var{name}} 387777298Sobrien@ifset ELF 387877298Sobrien* PushSection:: @code{.pushsection @var{name}} 387977298Sobrien@end ifset 388077298Sobrien 388133965Sjdp* Quad:: @code{.quad @var{bignums}} 3882218822Sdim* Reloc:: @code{.reloc @var{offset}, @var{reloc_name}[, @var{expression}]} 388333965Sjdp* Rept:: @code{.rept @var{count}} 388433965Sjdp* Sbttl:: @code{.sbttl "@var{subheading}"} 388533965Sjdp@ifset COFF 388633965Sjdp* Scl:: @code{.scl @var{class}} 388733965Sjdp@end ifset 3888130561Sobrien@ifset COFF-ELF 3889130561Sobrien* Section:: @code{.section @var{name}} 3890130561Sobrien@end ifset 389133965Sjdp 389233965Sjdp* Set:: @code{.set @var{symbol}, @var{expression}} 389333965Sjdp* Short:: @code{.short @var{expressions}} 389433965Sjdp* Single:: @code{.single @var{flonums}} 3895130561Sobrien@ifset COFF-ELF 389677298Sobrien* Size:: @code{.size [@var{name} , @var{expression}]} 3897130561Sobrien@end ifset 3898130561Sobrien 389933965Sjdp* Skip:: @code{.skip @var{size} , @var{fill}} 390038889Sjdp* Sleb128:: @code{.sleb128 @var{expressions}} 390133965Sjdp* Space:: @code{.space @var{size} , @var{fill}} 390233965Sjdp@ifset have-stabs 390333965Sjdp* Stab:: @code{.stabd, .stabn, .stabs} 390433965Sjdp@end ifset 390533965Sjdp 390633965Sjdp* String:: @code{.string "@var{str}"} 390760484Sobrien* Struct:: @code{.struct @var{expression}} 390833965Sjdp@ifset ELF 390977298Sobrien* SubSection:: @code{.subsection} 391033965Sjdp* Symver:: @code{.symver @var{name},@var{name2@@nodename}} 391133965Sjdp@end ifset 391277298Sobrien 391333965Sjdp@ifset COFF 391433965Sjdp* Tag:: @code{.tag @var{structname}} 391533965Sjdp@end ifset 391633965Sjdp 391733965Sjdp* Text:: @code{.text @var{subsection}} 391833965Sjdp* Title:: @code{.title "@var{heading}"} 3919130561Sobrien@ifset COFF-ELF 392077298Sobrien* Type:: @code{.type <@var{int} | @var{name} , @var{type description}>} 3921130561Sobrien@end ifset 3922130561Sobrien 392377298Sobrien* Uleb128:: @code{.uleb128 @var{expressions}} 392433965Sjdp@ifset COFF 392533965Sjdp* Val:: @code{.val @var{addr}} 392633965Sjdp@end ifset 392777298Sobrien 392860484Sobrien@ifset ELF 392977298Sobrien* Version:: @code{.version "@var{string}"} 393077298Sobrien* VTableEntry:: @code{.vtable_entry @var{table}, @var{offset}} 393177298Sobrien* VTableInherit:: @code{.vtable_inherit @var{child}, @var{parent}} 393260484Sobrien@end ifset 393333965Sjdp 3934218822Sdim* Warning:: @code{.warning @var{string}} 3935218822Sdim* Weak:: @code{.weak @var{names}} 3936218822Sdim* Weakref:: @code{.weakref @var{alias}, @var{symbol}} 393733965Sjdp* Word:: @code{.word @var{expressions}} 393833965Sjdp* Deprecated:: Deprecated Directives 393933965Sjdp@end menu 394033965Sjdp 394133965Sjdp@node Abort 394233965Sjdp@section @code{.abort} 394333965Sjdp 394433965Sjdp@cindex @code{abort} directive 394533965Sjdp@cindex stopping the assembly 394633965SjdpThis directive stops the assembly immediately. It is for 394733965Sjdpcompatibility with other assemblers. The original idea was that the 394833965Sjdpassembly language source would be piped into the assembler. If the sender 394989857Sobrienof the source quit, it could use this directive tells @command{@value{AS}} to 395033965Sjdpquit also. One day @code{.abort} will not be supported. 395133965Sjdp 395233965Sjdp@ifset COFF 3953218822Sdim@node ABORT (COFF) 3954218822Sdim@section @code{.ABORT} (COFF) 395533965Sjdp 395633965Sjdp@cindex @code{ABORT} directive 395789857SobrienWhen producing COFF output, @command{@value{AS}} accepts this directive as a 395833965Sjdpsynonym for @samp{.abort}. 395933965Sjdp 396033965Sjdp@ifset BOUT 396189857SobrienWhen producing @code{b.out} output, @command{@value{AS}} accepts this directive, 396233965Sjdpbut ignores it. 396333965Sjdp@end ifset 396433965Sjdp@end ifset 396533965Sjdp 396633965Sjdp@node Align 396733965Sjdp@section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} 396833965Sjdp 396933965Sjdp@cindex padding the location counter 397033965Sjdp@cindex @code{align} directive 397133965SjdpPad the location counter (in the current subsection) to a particular storage 397233965Sjdpboundary. The first expression (which must be absolute) is the alignment 397333965Sjdprequired, as described below. 397433965Sjdp 397533965SjdpThe second expression (also absolute) gives the fill value to be stored in the 397633965Sjdppadding bytes. It (and the comma) may be omitted. If it is omitted, the 397733965Sjdppadding bytes are normally zero. However, on some systems, if the section is 397833965Sjdpmarked as containing code and the fill value is omitted, the space is filled 397933965Sjdpwith no-op instructions. 398033965Sjdp 398133965SjdpThe third expression is also absolute, and is also optional. If it is present, 398233965Sjdpit is the maximum number of bytes that should be skipped by this alignment 398333965Sjdpdirective. If doing the alignment would require skipping more bytes than the 398433965Sjdpspecified maximum, then the alignment is not done at all. You can omit the 398533965Sjdpfill value (the second argument) entirely by simply using two commas after the 398633965Sjdprequired alignment; this can be useful if you want the alignment to be filled 398733965Sjdpwith no-op instructions when appropriate. 398833965Sjdp 398933965SjdpThe way the required alignment is specified varies from system to system. 3990218822SdimFor the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, 3991130561Sobriens390, sparc, tic4x, tic80 and xtensa, the first expression is the 399233965Sjdpalignment request in bytes. For example @samp{.align 8} advances 399333965Sjdpthe location counter until it is a multiple of 8. If the location counter 3994130561Sobrienis already a multiple of 8, no change is needed. For the tic54x, the 3995130561Sobrienfirst expression is the alignment request in words. 399633965Sjdp 399761843SobrienFor other systems, including the i386 using a.out format, and the arm and 399861843Sobrienstrongarm, it is the 399933965Sjdpnumber of low-order zero bits the location counter must have after 400033965Sjdpadvancement. For example @samp{.align 3} advances the location 400133965Sjdpcounter until it a multiple of 8. If the location counter is already a 400233965Sjdpmultiple of 8, no change is needed. 400333965Sjdp 400433965SjdpThis inconsistency is due to the different behaviors of the various 400533965Sjdpnative assemblers for these systems which GAS must emulate. 400633965SjdpGAS also provides @code{.balign} and @code{.p2align} directives, 400733965Sjdpdescribed later, which have a consistent behavior across all 400833965Sjdparchitectures (but are specific to GAS). 400933965Sjdp 401033965Sjdp@node Ascii 401133965Sjdp@section @code{.ascii "@var{string}"}@dots{} 401233965Sjdp 401333965Sjdp@cindex @code{ascii} directive 401433965Sjdp@cindex string literals 401533965Sjdp@code{.ascii} expects zero or more string literals (@pxref{Strings}) 401633965Sjdpseparated by commas. It assembles each string (with no automatic 401733965Sjdptrailing zero byte) into consecutive addresses. 401833965Sjdp 401933965Sjdp@node Asciz 402033965Sjdp@section @code{.asciz "@var{string}"}@dots{} 402133965Sjdp 402233965Sjdp@cindex @code{asciz} directive 402333965Sjdp@cindex zero-terminated strings 402433965Sjdp@cindex null-terminated strings 402533965Sjdp@code{.asciz} is just like @code{.ascii}, but each string is followed by 402633965Sjdpa zero byte. The ``z'' in @samp{.asciz} stands for ``zero''. 402733965Sjdp 402833965Sjdp@node Balign 402933965Sjdp@section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} 403033965Sjdp 403133965Sjdp@cindex padding the location counter given number of bytes 403233965Sjdp@cindex @code{balign} directive 403333965SjdpPad the location counter (in the current subsection) to a particular 403433965Sjdpstorage boundary. The first expression (which must be absolute) is the 403533965Sjdpalignment request in bytes. For example @samp{.balign 8} advances 403633965Sjdpthe location counter until it is a multiple of 8. If the location counter 403733965Sjdpis already a multiple of 8, no change is needed. 403833965Sjdp 403933965SjdpThe second expression (also absolute) gives the fill value to be stored in the 404033965Sjdppadding bytes. It (and the comma) may be omitted. If it is omitted, the 404133965Sjdppadding bytes are normally zero. However, on some systems, if the section is 404233965Sjdpmarked as containing code and the fill value is omitted, the space is filled 404333965Sjdpwith no-op instructions. 404433965Sjdp 404533965SjdpThe third expression is also absolute, and is also optional. If it is present, 404633965Sjdpit is the maximum number of bytes that should be skipped by this alignment 404733965Sjdpdirective. If doing the alignment would require skipping more bytes than the 404833965Sjdpspecified maximum, then the alignment is not done at all. You can omit the 404933965Sjdpfill value (the second argument) entirely by simply using two commas after the 405033965Sjdprequired alignment; this can be useful if you want the alignment to be filled 405133965Sjdpwith no-op instructions when appropriate. 405233965Sjdp 405333965Sjdp@cindex @code{balignw} directive 405433965Sjdp@cindex @code{balignl} directive 405533965SjdpThe @code{.balignw} and @code{.balignl} directives are variants of the 405633965Sjdp@code{.balign} directive. The @code{.balignw} directive treats the fill 405733965Sjdppattern as a two byte word value. The @code{.balignl} directives treats the 405833965Sjdpfill pattern as a four byte longword value. For example, @code{.balignw 405933965Sjdp4,0x368d} will align to a multiple of 4. If it skips two bytes, they will be 406033965Sjdpfilled in with the value 0x368d (the exact placement of the bytes depends upon 406133965Sjdpthe endianness of the processor). If it skips 1 or 3 bytes, the fill value is 406233965Sjdpundefined. 406333965Sjdp 406433965Sjdp@node Byte 406533965Sjdp@section @code{.byte @var{expressions}} 406633965Sjdp 406733965Sjdp@cindex @code{byte} directive 406833965Sjdp@cindex integers, one byte 406933965Sjdp@code{.byte} expects zero or more expressions, separated by commas. 407033965SjdpEach expression is assembled into the next byte. 407133965Sjdp 407233965Sjdp@node Comm 407333965Sjdp@section @code{.comm @var{symbol} , @var{length} } 407433965Sjdp 407533965Sjdp@cindex @code{comm} directive 407633965Sjdp@cindex symbol, common 407733965Sjdp@code{.comm} declares a common symbol named @var{symbol}. When linking, a 407833965Sjdpcommon symbol in one object file may be merged with a defined or common symbol 407933965Sjdpof the same name in another object file. If @code{@value{LD}} does not see a 408033965Sjdpdefinition for the symbol--just one or more common symbols--then it will 408133965Sjdpallocate @var{length} bytes of uninitialized memory. @var{length} must be an 408233965Sjdpabsolute expression. If @code{@value{LD}} sees multiple common symbols with 408333965Sjdpthe same name, and they do not all have the same size, it will allocate space 408433965Sjdpusing the largest size. 408533965Sjdp 408633965Sjdp@ifset ELF 408733965SjdpWhen using ELF, the @code{.comm} directive takes an optional third argument. 408833965SjdpThis is the desired alignment of the symbol, specified as a byte boundary (for 408933965Sjdpexample, an alignment of 16 means that the least significant 4 bits of the 409033965Sjdpaddress should be zero). The alignment must be an absolute expression, and it 409133965Sjdpmust be a power of two. If @code{@value{LD}} allocates uninitialized memory 409233965Sjdpfor the common symbol, it will use the alignment when placing the symbol. If 409389857Sobrienno alignment is specified, @command{@value{AS}} will set the alignment to the 409433965Sjdplargest power of two less than or equal to the size of the symbol, up to a 409533965Sjdpmaximum of 16. 409633965Sjdp@end ifset 409733965Sjdp 409833965Sjdp@ifset HPPA 409933965SjdpThe syntax for @code{.comm} differs slightly on the HPPA. The syntax is 410033965Sjdp@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional. 410133965Sjdp@end ifset 410233965Sjdp 4103130561Sobrien@node CFI directives 4104218822Sdim@section @code{.cfi_startproc [simple]} 4105130561Sobrien@cindex @code{cfi_startproc} directive 4106130561Sobrien@code{.cfi_startproc} is used at the beginning of each function that 4107130561Sobrienshould have an entry in @code{.eh_frame}. It initializes some internal 4108218822Sdimdata structures. Don't forget to close the function by 4109130561Sobrien@code{.cfi_endproc}. 4110130561Sobrien 4111218822SdimUnless @code{.cfi_startproc} is used along with parameter @code{simple} 4112218822Sdimit also emits some architecture dependent initial CFI instructions. 4113218822Sdim 4114130561Sobrien@section @code{.cfi_endproc} 4115130561Sobrien@cindex @code{cfi_endproc} directive 4116130561Sobrien@code{.cfi_endproc} is used at the end of a function where it closes its 4117130561Sobrienunwind entry previously opened by 4118218822Sdim@code{.cfi_startproc}, and emits it to @code{.eh_frame}. 4119130561Sobrien 4120218822Sdim@section @code{.cfi_personality @var{encoding} [, @var{exp}]} 4121218822Sdim@code{.cfi_personality} defines personality routine and its encoding. 4122218822Sdim@var{encoding} must be a constant determining how the personality 4123218822Sdimshould be encoded. If it is 255 (@code{DW_EH_PE_omit}), second 4124218822Sdimargument is not present, otherwise second argument should be 4125218822Sdima constant or a symbol name. When using indirect encodings, 4126218822Sdimthe symbol provided should be the location where personality 4127218822Sdimcan be loaded from, not the personality routine itself. 4128218822SdimThe default after @code{.cfi_startproc} is @code{.cfi_personality 0xff}, 4129218822Sdimno personality routine. 4130218822Sdim 4131218822Sdim@section @code{.cfi_lsda @var{encoding} [, @var{exp}]} 4132218822Sdim@code{.cfi_lsda} defines LSDA and its encoding. 4133218822Sdim@var{encoding} must be a constant determining how the LSDA 4134218822Sdimshould be encoded. If it is 255 (@code{DW_EH_PE_omit}), second 4135218822Sdimargument is not present, otherwise second argument should be a constant 4136218822Sdimor a symbol name. The default after @code{.cfi_startproc} is @code{.cfi_lsda 0xff}, 4137218822Sdimno LSDA. 4138218822Sdim 4139130561Sobrien@section @code{.cfi_def_cfa @var{register}, @var{offset}} 4140130561Sobrien@code{.cfi_def_cfa} defines a rule for computing CFA as: @i{take 4141130561Sobrienaddress from @var{register} and add @var{offset} to it}. 4142130561Sobrien 4143130561Sobrien@section @code{.cfi_def_cfa_register @var{register}} 4144130561Sobrien@code{.cfi_def_cfa_register} modifies a rule for computing CFA. From 4145130561Sobriennow on @var{register} will be used instead of the old one. Offset 4146130561Sobrienremains the same. 4147130561Sobrien 4148130561Sobrien@section @code{.cfi_def_cfa_offset @var{offset}} 4149130561Sobrien@code{.cfi_def_cfa_offset} modifies a rule for computing CFA. Register 4150130561Sobrienremains the same, but @var{offset} is new. Note that it is the 4151130561Sobrienabsolute offset that will be added to a defined register to compute 4152130561SobrienCFA address. 4153130561Sobrien 4154130561Sobrien@section @code{.cfi_adjust_cfa_offset @var{offset}} 4155130561SobrienSame as @code{.cfi_def_cfa_offset} but @var{offset} is a relative 4156130561Sobrienvalue that is added/substracted from the previous offset. 4157130561Sobrien 4158130561Sobrien@section @code{.cfi_offset @var{register}, @var{offset}} 4159130561SobrienPrevious value of @var{register} is saved at offset @var{offset} from 4160130561SobrienCFA. 4161130561Sobrien 4162130561Sobrien@section @code{.cfi_rel_offset @var{register}, @var{offset}} 4163130561SobrienPrevious value of @var{register} is saved at offset @var{offset} from 4164130561Sobrienthe current CFA register. This is transformed to @code{.cfi_offset} 4165130561Sobrienusing the known displacement of the CFA register from the CFA. 4166130561SobrienThis is often easier to use, because the number will match the 4167130561Sobriencode it's annotating. 4168130561Sobrien 4169218822Sdim@section @code{.cfi_register @var{register1}, @var{register2}} 4170218822SdimPrevious value of @var{register1} is saved in register @var{register2}. 4171218822Sdim 4172218822Sdim@section @code{.cfi_restore @var{register}} 4173218822Sdim@code{.cfi_restore} says that the rule for @var{register} is now the 4174218822Sdimsame as it was at the beginning of the function, after all initial 4175218822Sdiminstruction added by @code{.cfi_startproc} were executed. 4176218822Sdim 4177218822Sdim@section @code{.cfi_undefined @var{register}} 4178218822SdimFrom now on the previous value of @var{register} can't be restored anymore. 4179218822Sdim 4180218822Sdim@section @code{.cfi_same_value @var{register}} 4181218822SdimCurrent value of @var{register} is the same like in the previous frame, 4182218822Sdimi.e. no restoration needed. 4183218822Sdim 4184218822Sdim@section @code{.cfi_remember_state}, 4185218822SdimFirst save all current rules for all registers by @code{.cfi_remember_state}, 4186218822Sdimthen totally screw them up by subsequent @code{.cfi_*} directives and when 4187218822Sdimeverything is hopelessly bad, use @code{.cfi_restore_state} to restore 4188218822Sdimthe previous saved state. 4189218822Sdim 4190218822Sdim@section @code{.cfi_return_column @var{register}} 4191218822SdimChange return column @var{register}, i.e. the return address is either 4192218822Sdimdirectly in @var{register} or can be accessed by rules for @var{register}. 4193218822Sdim 4194218822Sdim@section @code{.cfi_signal_frame} 4195218822SdimMark current function as signal trampoline. 4196218822Sdim 4197130561Sobrien@section @code{.cfi_window_save} 4198130561SobrienSPARC register window has been saved. 4199130561Sobrien 4200130561Sobrien@section @code{.cfi_escape} @var{expression}[, @dots{}] 4201130561SobrienAllows the user to add arbitrary bytes to the unwind info. One 4202130561Sobrienmight use this to add OS-specific CFI opcodes, or generic CFI 4203130561Sobrienopcodes that GAS does not yet support. 4204130561Sobrien 4205218822Sdim@node LNS directives 4206218822Sdim@section @code{.file @var{fileno} @var{filename}} 4207218822Sdim@cindex @code{file} directive 4208218822SdimWhen emitting dwarf2 line number information @code{.file} assigns filenames 4209218822Sdimto the @code{.debug_line} file name table. The @var{fileno} operand should 4210218822Sdimbe a unique positive integer to use as the index of the entry in the table. 4211218822SdimThe @var{filename} operand is a C string literal. 4212218822Sdim 4213218822SdimThe detail of filename indices is exposed to the user because the filename 4214218822Sdimtable is shared with the @code{.debug_info} section of the dwarf2 debugging 4215218822Sdiminformation, and thus the user must know the exact indices that table 4216218822Sdimentries will have. 4217218822Sdim 4218218822Sdim@section @code{.loc @var{fileno} @var{lineno} [@var{column}] [@var{options}]} 4219218822Sdim@cindex @code{loc} directive 4220218822SdimThe @code{.loc} directive will add row to the @code{.debug_line} line 4221218822Sdimnumber matrix corresponding to the immediately following assembly 4222218822Sdiminstruction. The @var{fileno}, @var{lineno}, and optional @var{column} 4223218822Sdimarguments will be applied to the @code{.debug_line} state machine before 4224218822Sdimthe row is added. 4225218822Sdim 4226218822SdimThe @var{options} are a sequence of the following tokens in any order: 4227218822Sdim 4228218822Sdim@table @code 4229218822Sdim@item basic_block 4230218822SdimThis option will set the @code{basic_block} register in the 4231218822Sdim@code{.debug_line} state machine to @code{true}. 4232218822Sdim 4233218822Sdim@item prologue_end 4234218822SdimThis option will set the @code{prologue_end} register in the 4235218822Sdim@code{.debug_line} state machine to @code{true}. 4236218822Sdim 4237218822Sdim@item epilogue_begin 4238218822SdimThis option will set the @code{epilogue_begin} register in the 4239218822Sdim@code{.debug_line} state machine to @code{true}. 4240218822Sdim 4241218822Sdim@item is_stmt @var{value} 4242218822SdimThis option will set the @code{is_stmt} register in the 4243218822Sdim@code{.debug_line} state machine to @code{value}, which must be 4244218822Sdimeither 0 or 1. 4245218822Sdim 4246218822Sdim@item isa @var{value} 4247218822SdimThis directive will set the @code{isa} register in the @code{.debug_line} 4248218822Sdimstate machine to @var{value}, which must be an unsigned integer. 4249218822Sdim 4250218822Sdim@end table 4251218822Sdim 4252218822Sdim@section @code{.loc_mark_blocks @var{enable}} 4253218822Sdim@cindex @code{loc_mark_blocks} directive 4254218822SdimThe @code{.loc_mark_blocks} directive makes the assembler emit an entry 4255218822Sdimto the @code{.debug_line} line number matrix with the @code{basic_block} 4256218822Sdimregister in the state machine set whenever a code label is seen. 4257218822SdimThe @var{enable} argument should be either 1 or 0, to enable or disable 4258218822Sdimthis function respectively. 4259218822Sdim 426033965Sjdp@node Data 426133965Sjdp@section @code{.data @var{subsection}} 426233965Sjdp 426333965Sjdp@cindex @code{data} directive 426489857Sobrien@code{.data} tells @command{@value{AS}} to assemble the following statements onto the 426533965Sjdpend of the data subsection numbered @var{subsection} (which is an 426633965Sjdpabsolute expression). If @var{subsection} is omitted, it defaults 426733965Sjdpto zero. 426833965Sjdp 426933965Sjdp@ifset COFF 427033965Sjdp@node Def 427133965Sjdp@section @code{.def @var{name}} 427233965Sjdp 427333965Sjdp@cindex @code{def} directive 427433965Sjdp@cindex COFF symbols, debugging 427533965Sjdp@cindex debugging COFF symbols 427633965SjdpBegin defining debugging information for a symbol @var{name}; the 427733965Sjdpdefinition extends until the @code{.endef} directive is encountered. 427833965Sjdp@ifset BOUT 427933965Sjdp 428089857SobrienThis directive is only observed when @command{@value{AS}} is configured for COFF 428133965Sjdpformat output; when producing @code{b.out}, @samp{.def} is recognized, 428233965Sjdpbut ignored. 428333965Sjdp@end ifset 428433965Sjdp@end ifset 428533965Sjdp 428633965Sjdp@ifset aout-bout 428733965Sjdp@node Desc 428833965Sjdp@section @code{.desc @var{symbol}, @var{abs-expression}} 428933965Sjdp 429033965Sjdp@cindex @code{desc} directive 429133965Sjdp@cindex COFF symbol descriptor 429233965Sjdp@cindex symbol descriptor, COFF 429333965SjdpThis directive sets the descriptor of the symbol (@pxref{Symbol Attributes}) 429433965Sjdpto the low 16 bits of an absolute expression. 429533965Sjdp 429633965Sjdp@ifset COFF 429789857SobrienThe @samp{.desc} directive is not available when @command{@value{AS}} is 429833965Sjdpconfigured for COFF output; it is only for @code{a.out} or @code{b.out} 429989857Sobrienobject format. For the sake of compatibility, @command{@value{AS}} accepts 430033965Sjdpit, but produces no output, when configured for COFF. 430133965Sjdp@end ifset 430233965Sjdp@end ifset 430333965Sjdp 430433965Sjdp@ifset COFF 430533965Sjdp@node Dim 430633965Sjdp@section @code{.dim} 430733965Sjdp 430833965Sjdp@cindex @code{dim} directive 430933965Sjdp@cindex COFF auxiliary symbol information 431033965Sjdp@cindex auxiliary symbol information, COFF 431133965SjdpThis directive is generated by compilers to include auxiliary debugging 431233965Sjdpinformation in the symbol table. It is only permitted inside 431333965Sjdp@code{.def}/@code{.endef} pairs. 431433965Sjdp@ifset BOUT 431533965Sjdp 431633965Sjdp@samp{.dim} is only meaningful when generating COFF format output; when 431789857Sobrien@command{@value{AS}} is generating @code{b.out}, it accepts this directive but 431833965Sjdpignores it. 431933965Sjdp@end ifset 432033965Sjdp@end ifset 432133965Sjdp 432233965Sjdp@node Double 432333965Sjdp@section @code{.double @var{flonums}} 432433965Sjdp 432533965Sjdp@cindex @code{double} directive 432633965Sjdp@cindex floating point numbers (double) 432733965Sjdp@code{.double} expects zero or more flonums, separated by commas. It 432833965Sjdpassembles floating point numbers. 432933965Sjdp@ifset GENERIC 433033965SjdpThe exact kind of floating point numbers emitted depends on how 433189857Sobrien@command{@value{AS}} is configured. @xref{Machine Dependencies}. 433233965Sjdp@end ifset 433333965Sjdp@ifclear GENERIC 433433965Sjdp@ifset IEEEFLOAT 433533965SjdpOn the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers 433633965Sjdpin @sc{ieee} format. 433733965Sjdp@end ifset 433833965Sjdp@end ifclear 433933965Sjdp 434033965Sjdp@node Eject 434133965Sjdp@section @code{.eject} 434233965Sjdp 434333965Sjdp@cindex @code{eject} directive 434433965Sjdp@cindex new page, in listings 434533965Sjdp@cindex page, in listings 434633965Sjdp@cindex listing control: new page 434733965SjdpForce a page break at this point, when generating assembly listings. 434833965Sjdp 434933965Sjdp@node Else 435033965Sjdp@section @code{.else} 435133965Sjdp 435233965Sjdp@cindex @code{else} directive 435389857Sobrien@code{.else} is part of the @command{@value{AS}} support for conditional 4354218822Sdimassembly; see @ref{If,,@code{.if}}. It marks the beginning of a section 435533965Sjdpof code to be assembled if the condition for the preceding @code{.if} 435633965Sjdpwas false. 435733965Sjdp 435860484Sobrien@node Elseif 435960484Sobrien@section @code{.elseif} 436060484Sobrien 436160484Sobrien@cindex @code{elseif} directive 436289857Sobrien@code{.elseif} is part of the @command{@value{AS}} support for conditional 4363218822Sdimassembly; see @ref{If,,@code{.if}}. It is shorthand for beginning a new 436460484Sobrien@code{.if} block that would otherwise fill the entire @code{.else} section. 436560484Sobrien 436660484Sobrien@node End 436733965Sjdp@section @code{.end} 436833965Sjdp 436933965Sjdp@cindex @code{end} directive 437089857Sobrien@code{.end} marks the end of the assembly file. @command{@value{AS}} does not 437160484Sobrienprocess anything in the file past the @code{.end} directive. 437233965Sjdp 437333965Sjdp@ifset COFF 437433965Sjdp@node Endef 437533965Sjdp@section @code{.endef} 437633965Sjdp 437733965Sjdp@cindex @code{endef} directive 437833965SjdpThis directive flags the end of a symbol definition begun with 437933965Sjdp@code{.def}. 438033965Sjdp@ifset BOUT 438133965Sjdp 438233965Sjdp@samp{.endef} is only meaningful when generating COFF format output; if 438389857Sobrien@command{@value{AS}} is configured to generate @code{b.out}, it accepts this 438433965Sjdpdirective but ignores it. 438533965Sjdp@end ifset 438633965Sjdp@end ifset 438733965Sjdp 438860484Sobrien@node Endfunc 438960484Sobrien@section @code{.endfunc} 439060484Sobrien@cindex @code{endfunc} directive 439160484Sobrien@code{.endfunc} marks the end of a function specified with @code{.func}. 439260484Sobrien 439333965Sjdp@node Endif 439433965Sjdp@section @code{.endif} 439533965Sjdp 439633965Sjdp@cindex @code{endif} directive 439789857Sobrien@code{.endif} is part of the @command{@value{AS}} support for conditional assembly; 439833965Sjdpit marks the end of a block of code that is only assembled 439933965Sjdpconditionally. @xref{If,,@code{.if}}. 440033965Sjdp 440133965Sjdp@node Equ 440233965Sjdp@section @code{.equ @var{symbol}, @var{expression}} 440333965Sjdp 440433965Sjdp@cindex @code{equ} directive 440533965Sjdp@cindex assigning values to symbols 440633965Sjdp@cindex symbols, assigning values to 440733965SjdpThis directive sets the value of @var{symbol} to @var{expression}. 4408218822SdimIt is synonymous with @samp{.set}; see @ref{Set,,@code{.set}}. 440933965Sjdp 441033965Sjdp@ifset HPPA 441133965SjdpThe syntax for @code{equ} on the HPPA is 441233965Sjdp@samp{@var{symbol} .equ @var{expression}}. 441333965Sjdp@end ifset 441433965Sjdp 4415218822Sdim@ifset Z80 4416218822SdimThe syntax for @code{equ} on the Z80 is 4417218822Sdim@samp{@var{symbol} equ @var{expression}}. 4418218822SdimOn the Z80 it is an eror if @var{symbol} is already defined, 4419218822Sdimbut the symbol is not protected from later redefinition. 4420218822SdimCompare @ref{Equiv}. 4421218822Sdim@end ifset 4422218822Sdim 442333965Sjdp@node Equiv 442433965Sjdp@section @code{.equiv @var{symbol}, @var{expression}} 442533965Sjdp@cindex @code{equiv} directive 442633965SjdpThe @code{.equiv} directive is like @code{.equ} and @code{.set}, except that 4427130561Sobrienthe assembler will signal an error if @var{symbol} is already defined. Note a 4428130561Sobriensymbol which has been referenced but not actually defined is considered to be 4429130561Sobrienundefined. 443033965Sjdp 443133965SjdpExcept for the contents of the error message, this is roughly equivalent to 443233965Sjdp@smallexample 443333965Sjdp.ifdef SYM 443433965Sjdp.err 443533965Sjdp.endif 443633965Sjdp.equ SYM,VAL 443733965Sjdp@end smallexample 4438218822Sdimplus it protects the symbol from later redefinition. 443933965Sjdp 4440218822Sdim@node Eqv 4441218822Sdim@section @code{.eqv @var{symbol}, @var{expression}} 4442218822Sdim@cindex @code{eqv} directive 4443218822SdimThe @code{.eqv} directive is like @code{.equiv}, but no attempt is made to 4444218822Sdimevaluate the expression or any part of it immediately. Instead each time 4445218822Sdimthe resulting symbol is used in an expression, a snapshot of its current 4446218822Sdimvalue is taken. 4447218822Sdim 444833965Sjdp@node Err 444933965Sjdp@section @code{.err} 445033965Sjdp@cindex @code{err} directive 445189857SobrienIf @command{@value{AS}} assembles a @code{.err} directive, it will print an error 445289857Sobrienmessage and, unless the @option{-Z} option was used, it will not generate an 4453218822Sdimobject file. This can be used to signal an error in conditionally compiled code. 445433965Sjdp 4455218822Sdim@node Error 4456218822Sdim@section @code{.error "@var{string}"} 4457218822Sdim@cindex error directive 4458218822Sdim 4459218822SdimSimilarly to @code{.err}, this directive emits an error, but you can specify a 4460218822Sdimstring that will be emitted as the error message. If you don't specify the 4461218822Sdimmessage, it defaults to @code{".error directive invoked in source file"}. 4462218822Sdim@xref{Errors, ,Error and Warning Messages}. 4463218822Sdim 4464218822Sdim@smallexample 4465218822Sdim .error "This code has not been assembled and tested." 4466218822Sdim@end smallexample 4467218822Sdim 446860484Sobrien@node Exitm 446960484Sobrien@section @code{.exitm} 447060484SobrienExit early from the current macro definition. @xref{Macro}. 447160484Sobrien 447233965Sjdp@node Extern 447333965Sjdp@section @code{.extern} 447433965Sjdp 447533965Sjdp@cindex @code{extern} directive 447633965Sjdp@code{.extern} is accepted in the source program---for compatibility 447789857Sobrienwith other assemblers---but it is ignored. @command{@value{AS}} treats 447833965Sjdpall undefined symbols as external. 447933965Sjdp 448060484Sobrien@node Fail 448160484Sobrien@section @code{.fail @var{expression}} 448260484Sobrien 448360484Sobrien@cindex @code{fail} directive 448460484SobrienGenerates an error or a warning. If the value of the @var{expression} is 500 448589857Sobrienor more, @command{@value{AS}} will print a warning message. If the value is less 448689857Sobrienthan 500, @command{@value{AS}} will print an error message. The message will 448760484Sobrieninclude the value of @var{expression}. This can occasionally be useful inside 448860484Sobriencomplex nested macros or conditional assembly. 448960484Sobrien 449033965Sjdp@ifclear no-file-dir 449133965Sjdp@node File 449233965Sjdp@section @code{.file @var{string}} 449333965Sjdp 449433965Sjdp@cindex @code{file} directive 449533965Sjdp@cindex logical file name 449633965Sjdp@cindex file name, logical 449789857Sobrien@code{.file} tells @command{@value{AS}} that we are about to start a new logical 449860484Sobrienfile. @var{string} is the new file name. In general, the filename is 449960484Sobrienrecognized whether or not it is surrounded by quotes @samp{"}; but if you wish 450060484Sobriento specify an empty file name, you must give the quotes--@code{""}. This 450160484Sobrienstatement may go away in future: it is only recognized to be compatible with 450289857Sobrienold @command{@value{AS}} programs. 450333965Sjdp@end ifclear 450433965Sjdp 450533965Sjdp@node Fill 450633965Sjdp@section @code{.fill @var{repeat} , @var{size} , @var{value}} 450733965Sjdp 450833965Sjdp@cindex @code{fill} directive 450933965Sjdp@cindex writing patterns in memory 451033965Sjdp@cindex patterns, writing in memory 451189857Sobrien@var{repeat}, @var{size} and @var{value} are absolute expressions. 451233965SjdpThis emits @var{repeat} copies of @var{size} bytes. @var{Repeat} 451333965Sjdpmay be zero or more. @var{Size} may be zero or more, but if it is 451433965Sjdpmore than 8, then it is deemed to have the value 8, compatible with 451533965Sjdpother people's assemblers. The contents of each @var{repeat} bytes 451633965Sjdpis taken from an 8-byte number. The highest order 4 bytes are 451733965Sjdpzero. The lowest order 4 bytes are @var{value} rendered in the 451889857Sobrienbyte-order of an integer on the computer @command{@value{AS}} is assembling for. 451933965SjdpEach @var{size} bytes in a repetition is taken from the lowest order 452033965Sjdp@var{size} bytes of this number. Again, this bizarre behavior is 452133965Sjdpcompatible with other people's assemblers. 452233965Sjdp 452333965Sjdp@var{size} and @var{value} are optional. 452433965SjdpIf the second comma and @var{value} are absent, @var{value} is 452533965Sjdpassumed zero. If the first comma and following tokens are absent, 452633965Sjdp@var{size} is assumed to be 1. 452733965Sjdp 452833965Sjdp@node Float 452933965Sjdp@section @code{.float @var{flonums}} 453033965Sjdp 453133965Sjdp@cindex floating point numbers (single) 453233965Sjdp@cindex @code{float} directive 453333965SjdpThis directive assembles zero or more flonums, separated by commas. It 453433965Sjdphas the same effect as @code{.single}. 453533965Sjdp@ifset GENERIC 453633965SjdpThe exact kind of floating point numbers emitted depends on how 453789857Sobrien@command{@value{AS}} is configured. 453833965Sjdp@xref{Machine Dependencies}. 453933965Sjdp@end ifset 454033965Sjdp@ifclear GENERIC 454133965Sjdp@ifset IEEEFLOAT 454233965SjdpOn the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers 454333965Sjdpin @sc{ieee} format. 454433965Sjdp@end ifset 454533965Sjdp@end ifclear 454633965Sjdp 454760484Sobrien@node Func 454860484Sobrien@section @code{.func @var{name}[,@var{label}]} 454960484Sobrien@cindex @code{func} directive 455060484Sobrien@code{.func} emits debugging information to denote function @var{name}, and 455160484Sobrienis ignored unless the file is assembled with debugging enabled. 4552130561SobrienOnly @samp{--gstabs[+]} is currently supported. 455360484Sobrien@var{label} is the entry point of the function and if omitted @var{name} 455460484Sobrienprepended with the @samp{leading char} is used. 455560484Sobrien@samp{leading char} is usually @code{_} or nothing, depending on the target. 455660484SobrienAll functions are currently defined to have @code{void} return type. 455760484SobrienThe function must be terminated with @code{.endfunc}. 455860484Sobrien 455933965Sjdp@node Global 456033965Sjdp@section @code{.global @var{symbol}}, @code{.globl @var{symbol}} 456133965Sjdp 456233965Sjdp@cindex @code{global} directive 456333965Sjdp@cindex symbol, making visible to linker 456433965Sjdp@code{.global} makes the symbol visible to @code{@value{LD}}. If you define 456533965Sjdp@var{symbol} in your partial program, its value is made available to 456633965Sjdpother partial programs that are linked with it. Otherwise, 456733965Sjdp@var{symbol} takes its attributes from a symbol of the same name 456833965Sjdpfrom another file linked into the same program. 456933965Sjdp 457033965SjdpBoth spellings (@samp{.globl} and @samp{.global}) are accepted, for 457133965Sjdpcompatibility with other assemblers. 457233965Sjdp 457333965Sjdp@ifset HPPA 457433965SjdpOn the HPPA, @code{.global} is not always enough to make it accessible to other 457533965Sjdppartial programs. You may need the HPPA-only @code{.EXPORT} directive as well. 4576218822Sdim@xref{HPPA Directives, ,HPPA Assembler Directives}. 457733965Sjdp@end ifset 457833965Sjdp 457977298Sobrien@ifset ELF 458077298Sobrien@node Hidden 458177298Sobrien@section @code{.hidden @var{names}} 458277298Sobrien 4583130561Sobrien@cindex @code{hidden} directive 4584130561Sobrien@cindex visibility 4585218822SdimThis is one of the ELF visibility directives. The other two are 458677298Sobrien@code{.internal} (@pxref{Internal,,@code{.internal}}) and 458777298Sobrien@code{.protected} (@pxref{Protected,,@code{.protected}}). 458877298Sobrien 458977298SobrienThis directive overrides the named symbols default visibility (which is set by 459077298Sobrientheir binding: local, global or weak). The directive sets the visibility to 459177298Sobrien@code{hidden} which means that the symbols are not visible to other components. 459277298SobrienSuch symbols are always considered to be @code{protected} as well. 459377298Sobrien@end ifset 459477298Sobrien 459533965Sjdp@node hword 459633965Sjdp@section @code{.hword @var{expressions}} 459733965Sjdp 459833965Sjdp@cindex @code{hword} directive 459933965Sjdp@cindex integers, 16-bit 460033965Sjdp@cindex numbers, 16-bit 460133965Sjdp@cindex sixteen bit integers 460233965SjdpThis expects zero or more @var{expressions}, and emits 460333965Sjdpa 16 bit number for each. 460433965Sjdp 460533965Sjdp@ifset GENERIC 460633965SjdpThis directive is a synonym for @samp{.short}; depending on the target 460733965Sjdparchitecture, it may also be a synonym for @samp{.word}. 460833965Sjdp@end ifset 460933965Sjdp@ifclear GENERIC 461033965Sjdp@ifset W32 461133965SjdpThis directive is a synonym for @samp{.short}. 461233965Sjdp@end ifset 461333965Sjdp@ifset W16 461433965SjdpThis directive is a synonym for both @samp{.short} and @samp{.word}. 461533965Sjdp@end ifset 461633965Sjdp@end ifclear 461733965Sjdp 461833965Sjdp@node Ident 461933965Sjdp@section @code{.ident} 462033965Sjdp 462133965Sjdp@cindex @code{ident} directive 462233965Sjdp 4623218822SdimThis directive is used by some assemblers to place tags in object files. The 4624218822Sdimbehavior of this directive varies depending on the target. When using the 4625218822Sdima.out object file format, @command{@value{AS}} simply accepts the directive for 4626218822Sdimsource-file compatibility with existing assemblers, but does not emit anything 4627218822Sdimfor it. When using COFF, comments are emitted to the @code{.comment} or 4628218822Sdim@code{.rdata} section, depending on the target. When using ELF, comments are 4629218822Sdimemitted to the @code{.comment} section. 4630218822Sdim 463133965Sjdp@node If 463233965Sjdp@section @code{.if @var{absolute expression}} 463333965Sjdp 463433965Sjdp@cindex conditional assembly 463533965Sjdp@cindex @code{if} directive 463633965Sjdp@code{.if} marks the beginning of a section of code which is only 463733965Sjdpconsidered part of the source program being assembled if the argument 463833965Sjdp(which must be an @var{absolute expression}) is non-zero. The end of 463933965Sjdpthe conditional section of code must be marked by @code{.endif} 464033965Sjdp(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the 464133965Sjdpalternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}). 464260484SobrienIf you have several conditions to check, @code{.elseif} may be used to avoid 464360484Sobriennesting blocks if/else within each subsequent @code{.else} block. 464433965Sjdp 464533965SjdpThe following variants of @code{.if} are also supported: 464633965Sjdp@table @code 464733965Sjdp@cindex @code{ifdef} directive 464833965Sjdp@item .ifdef @var{symbol} 464933965SjdpAssembles the following section of code if the specified @var{symbol} 4650130561Sobrienhas been defined. Note a symbol which has been referenced but not yet defined 4651130561Sobrienis considered to be undefined. 465233965Sjdp 4653218822Sdim@cindex @code{ifb} directive 4654218822Sdim@item .ifb @var{text} 4655218822SdimAssembles the following section of code if the operand is blank (empty). 4656218822Sdim 465760484Sobrien@cindex @code{ifc} directive 465860484Sobrien@item .ifc @var{string1},@var{string2} 465960484SobrienAssembles the following section of code if the two strings are the same. The 466060484Sobrienstrings may be optionally quoted with single quotes. If they are not quoted, 466160484Sobrienthe first string stops at the first comma, and the second string stops at the 466260484Sobrienend of the line. Strings which contain whitespace should be quoted. The 466360484Sobrienstring comparison is case sensitive. 466460484Sobrien 466560484Sobrien@cindex @code{ifeq} directive 466660484Sobrien@item .ifeq @var{absolute expression} 466760484SobrienAssembles the following section of code if the argument is zero. 466860484Sobrien 466933965Sjdp@cindex @code{ifeqs} directive 467060484Sobrien@item .ifeqs @var{string1},@var{string2} 467160484SobrienAnother form of @code{.ifc}. The strings must be quoted using double quotes. 467233965Sjdp 467360484Sobrien@cindex @code{ifge} directive 467460484Sobrien@item .ifge @var{absolute expression} 467560484SobrienAssembles the following section of code if the argument is greater than or 467660484Sobrienequal to zero. 467760484Sobrien 467860484Sobrien@cindex @code{ifgt} directive 467960484Sobrien@item .ifgt @var{absolute expression} 468060484SobrienAssembles the following section of code if the argument is greater than zero. 468160484Sobrien 468260484Sobrien@cindex @code{ifle} directive 468360484Sobrien@item .ifle @var{absolute expression} 468460484SobrienAssembles the following section of code if the argument is less than or equal 468560484Sobriento zero. 468660484Sobrien 468760484Sobrien@cindex @code{iflt} directive 468860484Sobrien@item .iflt @var{absolute expression} 468960484SobrienAssembles the following section of code if the argument is less than zero. 469060484Sobrien 4691218822Sdim@cindex @code{ifnb} directive 4692218822Sdim@item .ifnb @var{text} 4693218822SdimLike @code{.ifb}, but the sense of the test is reversed: this assembles the 4694218822Sdimfollowing section of code if the operand is non-blank (non-empty). 4695218822Sdim 469660484Sobrien@cindex @code{ifnc} directive 469760484Sobrien@item .ifnc @var{string1},@var{string2}. 469860484SobrienLike @code{.ifc}, but the sense of the test is reversed: this assembles the 469960484Sobrienfollowing section of code if the two strings are not the same. 470060484Sobrien 470133965Sjdp@cindex @code{ifndef} directive 470233965Sjdp@cindex @code{ifnotdef} directive 470333965Sjdp@item .ifndef @var{symbol} 470433965Sjdp@itemx .ifnotdef @var{symbol} 470533965SjdpAssembles the following section of code if the specified @var{symbol} 4706130561Sobrienhas not been defined. Both spelling variants are equivalent. Note a symbol 4707130561Sobrienwhich has been referenced but not yet defined is considered to be undefined. 470833965Sjdp 470960484Sobrien@cindex @code{ifne} directive 471060484Sobrien@item .ifne @var{absolute expression} 471160484SobrienAssembles the following section of code if the argument is not equal to zero 471260484Sobrien(in other words, this is equivalent to @code{.if}). 471360484Sobrien 471460484Sobrien@cindex @code{ifnes} directive 471560484Sobrien@item .ifnes @var{string1},@var{string2} 471660484SobrienLike @code{.ifeqs}, but the sense of the test is reversed: this assembles the 471760484Sobrienfollowing section of code if the two strings are not the same. 471833965Sjdp@end table 471933965Sjdp 472089857Sobrien@node Incbin 472189857Sobrien@section @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]} 472289857Sobrien 472389857Sobrien@cindex @code{incbin} directive 472489857Sobrien@cindex binary files, including 472589857SobrienThe @code{incbin} directive includes @var{file} verbatim at the current 472689857Sobrienlocation. You can control the search paths used with the @samp{-I} command-line 472789857Sobrienoption (@pxref{Invoking,,Command-Line Options}). Quotation marks are required 472889857Sobrienaround @var{file}. 472989857Sobrien 473089857SobrienThe @var{skip} argument skips a number of bytes from the start of the 473189857Sobrien@var{file}. The @var{count} argument indicates the maximum number of bytes to 473289857Sobrienread. Note that the data is not aligned in any way, so it is the user's 473389857Sobrienresponsibility to make sure that proper alignment is provided both before and 473489857Sobrienafter the @code{incbin} directive. 473589857Sobrien 473633965Sjdp@node Include 473733965Sjdp@section @code{.include "@var{file}"} 473833965Sjdp 473933965Sjdp@cindex @code{include} directive 474033965Sjdp@cindex supporting files, including 474133965Sjdp@cindex files, including 474233965SjdpThis directive provides a way to include supporting files at specified 474333965Sjdppoints in your source program. The code from @var{file} is assembled as 474433965Sjdpif it followed the point of the @code{.include}; when the end of the 474533965Sjdpincluded file is reached, assembly of the original file continues. You 474633965Sjdpcan control the search paths used with the @samp{-I} command-line option 474733965Sjdp(@pxref{Invoking,,Command-Line Options}). Quotation marks are required 474833965Sjdparound @var{file}. 474933965Sjdp 475033965Sjdp@node Int 475133965Sjdp@section @code{.int @var{expressions}} 475233965Sjdp 475333965Sjdp@cindex @code{int} directive 475433965Sjdp@cindex integers, 32-bit 475533965SjdpExpect zero or more @var{expressions}, of any section, separated by commas. 475633965SjdpFor each expression, emit a number that, at run time, is the value of that 475733965Sjdpexpression. The byte order and bit size of the number depends on what kind 475833965Sjdpof target the assembly is for. 475933965Sjdp 476033965Sjdp@ifclear GENERIC 476133965Sjdp@ifset H8 4762218822SdimOn most forms of the H8/300, @code{.int} emits 16-bit 4763130561Sobrienintegers. On the H8/300H and the Renesas SH, however, @code{.int} emits 476433965Sjdp32-bit integers. 476533965Sjdp@end ifset 476633965Sjdp@end ifclear 476733965Sjdp 476877298Sobrien@ifset ELF 476977298Sobrien@node Internal 477077298Sobrien@section @code{.internal @var{names}} 477177298Sobrien 4772130561Sobrien@cindex @code{internal} directive 4773130561Sobrien@cindex visibility 4774218822SdimThis is one of the ELF visibility directives. The other two are 477577298Sobrien@code{.hidden} (@pxref{Hidden,,@code{.hidden}}) and 477677298Sobrien@code{.protected} (@pxref{Protected,,@code{.protected}}). 477777298Sobrien 477877298SobrienThis directive overrides the named symbols default visibility (which is set by 477977298Sobrientheir binding: local, global or weak). The directive sets the visibility to 478077298Sobrien@code{internal} which means that the symbols are considered to be @code{hidden} 4781130561Sobrien(i.e., not visible to other components), and that some extra, processor specific 478277298Sobrienprocessing must also be performed upon the symbols as well. 478377298Sobrien@end ifset 478477298Sobrien 478533965Sjdp@node Irp 478633965Sjdp@section @code{.irp @var{symbol},@var{values}}@dots{} 478733965Sjdp 478833965Sjdp@cindex @code{irp} directive 478933965SjdpEvaluate a sequence of statements assigning different values to @var{symbol}. 479033965SjdpThe sequence of statements starts at the @code{.irp} directive, and is 479133965Sjdpterminated by an @code{.endr} directive. For each @var{value}, @var{symbol} is 479233965Sjdpset to @var{value}, and the sequence of statements is assembled. If no 479333965Sjdp@var{value} is listed, the sequence of statements is assembled once, with 479433965Sjdp@var{symbol} set to the null string. To refer to @var{symbol} within the 479533965Sjdpsequence of statements, use @var{\symbol}. 479633965Sjdp 479733965SjdpFor example, assembling 479833965Sjdp 479933965Sjdp@example 480033965Sjdp .irp param,1,2,3 480133965Sjdp move d\param,sp@@- 480233965Sjdp .endr 480333965Sjdp@end example 480433965Sjdp 480533965Sjdpis equivalent to assembling 480633965Sjdp 480733965Sjdp@example 480833965Sjdp move d1,sp@@- 480933965Sjdp move d2,sp@@- 481033965Sjdp move d3,sp@@- 481133965Sjdp@end example 481233965Sjdp 4813218822SdimFor some caveats with the spelling of @var{symbol}, see also @ref{Macro}. 4814218822Sdim 481533965Sjdp@node Irpc 481633965Sjdp@section @code{.irpc @var{symbol},@var{values}}@dots{} 481733965Sjdp 481833965Sjdp@cindex @code{irpc} directive 481933965SjdpEvaluate a sequence of statements assigning different values to @var{symbol}. 482033965SjdpThe sequence of statements starts at the @code{.irpc} directive, and is 482133965Sjdpterminated by an @code{.endr} directive. For each character in @var{value}, 482233965Sjdp@var{symbol} is set to the character, and the sequence of statements is 482333965Sjdpassembled. If no @var{value} is listed, the sequence of statements is 482433965Sjdpassembled once, with @var{symbol} set to the null string. To refer to 482533965Sjdp@var{symbol} within the sequence of statements, use @var{\symbol}. 482633965Sjdp 482733965SjdpFor example, assembling 482833965Sjdp 482933965Sjdp@example 483033965Sjdp .irpc param,123 483133965Sjdp move d\param,sp@@- 483233965Sjdp .endr 483333965Sjdp@end example 483433965Sjdp 483533965Sjdpis equivalent to assembling 483633965Sjdp 483733965Sjdp@example 483833965Sjdp move d1,sp@@- 483933965Sjdp move d2,sp@@- 484033965Sjdp move d3,sp@@- 484133965Sjdp@end example 484233965Sjdp 4843218822SdimFor some caveats with the spelling of @var{symbol}, see also the discussion 4844218822Sdimat @xref{Macro}. 4845218822Sdim 484633965Sjdp@node Lcomm 484733965Sjdp@section @code{.lcomm @var{symbol} , @var{length}} 484833965Sjdp 484933965Sjdp@cindex @code{lcomm} directive 485033965Sjdp@cindex local common symbols 485133965Sjdp@cindex symbols, local common 485233965SjdpReserve @var{length} (an absolute expression) bytes for a local common 485333965Sjdpdenoted by @var{symbol}. The section and value of @var{symbol} are 485433965Sjdpthose of the new local common. The addresses are allocated in the bss 485533965Sjdpsection, so that at run-time the bytes start off zeroed. @var{Symbol} 485633965Sjdpis not declared global (@pxref{Global,,@code{.global}}), so is normally 485733965Sjdpnot visible to @code{@value{LD}}. 485833965Sjdp 485933965Sjdp@ifset GENERIC 486033965SjdpSome targets permit a third argument to be used with @code{.lcomm}. This 486133965Sjdpargument specifies the desired alignment of the symbol in the bss section. 486233965Sjdp@end ifset 486333965Sjdp 486433965Sjdp@ifset HPPA 486533965SjdpThe syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is 486633965Sjdp@samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional. 486733965Sjdp@end ifset 486833965Sjdp 486933965Sjdp@node Lflags 487033965Sjdp@section @code{.lflags} 487133965Sjdp 487233965Sjdp@cindex @code{lflags} directive (ignored) 487389857Sobrien@command{@value{AS}} accepts this directive, for compatibility with other 487433965Sjdpassemblers, but ignores it. 487533965Sjdp 487633965Sjdp@ifclear no-line-dir 487733965Sjdp@node Line 487833965Sjdp@section @code{.line @var{line-number}} 487933965Sjdp 488033965Sjdp@cindex @code{line} directive 488133965Sjdp@end ifclear 488233965Sjdp@ifset no-line-dir 488333965Sjdp@node Ln 488433965Sjdp@section @code{.ln @var{line-number}} 488533965Sjdp 488633965Sjdp@cindex @code{ln} directive 488733965Sjdp@end ifset 488833965Sjdp@cindex logical line number 488933965Sjdp@ifset aout-bout 489033965SjdpChange the logical line number. @var{line-number} must be an absolute 489133965Sjdpexpression. The next line has that logical line number. Therefore any other 489233965Sjdpstatements on the current line (after a statement separator character) are 489333965Sjdpreported as on logical line number @var{line-number} @minus{} 1. One day 489489857Sobrien@command{@value{AS}} will no longer support this directive: it is recognized only 489533965Sjdpfor compatibility with existing assembler programs. 489633965Sjdp 489733965Sjdp@end ifset 489833965Sjdp 489933965Sjdp@ifclear no-line-dir 490033965SjdpEven though this is a directive associated with the @code{a.out} or 490189857Sobrien@code{b.out} object-code formats, @command{@value{AS}} still recognizes it 490233965Sjdpwhen producing COFF output, and treats @samp{.line} as though it 490333965Sjdpwere the COFF @samp{.ln} @emph{if} it is found outside a 490433965Sjdp@code{.def}/@code{.endef} pair. 490533965Sjdp 490633965SjdpInside a @code{.def}, @samp{.line} is, instead, one of the directives 490733965Sjdpused by compilers to generate auxiliary symbol information for 490833965Sjdpdebugging. 490933965Sjdp@end ifclear 491033965Sjdp 491133965Sjdp@node Linkonce 491233965Sjdp@section @code{.linkonce [@var{type}]} 491333965Sjdp@cindex COMDAT 491433965Sjdp@cindex @code{linkonce} directive 491533965Sjdp@cindex common sections 491633965SjdpMark the current section so that the linker only includes a single copy of it. 491733965SjdpThis may be used to include the same section in several different object files, 491833965Sjdpbut ensure that the linker will only include it once in the final output file. 491933965SjdpThe @code{.linkonce} pseudo-op must be used for each instance of the section. 492033965SjdpDuplicate sections are detected based on the section name, so it should be 492133965Sjdpunique. 492233965Sjdp 492333965SjdpThis directive is only supported by a few object file formats; as of this 492433965Sjdpwriting, the only object file format which supports it is the Portable 492533965SjdpExecutable format used on Windows NT. 492633965Sjdp 492733965SjdpThe @var{type} argument is optional. If specified, it must be one of the 492833965Sjdpfollowing strings. For example: 492933965Sjdp@smallexample 493033965Sjdp.linkonce same_size 493133965Sjdp@end smallexample 493233965SjdpNot all types may be supported on all object file formats. 493333965Sjdp 493433965Sjdp@table @code 493533965Sjdp@item discard 493633965SjdpSilently discard duplicate sections. This is the default. 493733965Sjdp 493833965Sjdp@item one_only 493933965SjdpWarn if there are duplicate sections, but still keep only one copy. 494033965Sjdp 494133965Sjdp@item same_size 494233965SjdpWarn if any of the duplicates have different sizes. 494333965Sjdp 494433965Sjdp@item same_contents 494533965SjdpWarn if any of the duplicates do not have exactly the same contents. 494633965Sjdp@end table 494733965Sjdp 494833965Sjdp@node Ln 494933965Sjdp@section @code{.ln @var{line-number}} 495033965Sjdp 495133965Sjdp@cindex @code{ln} directive 495233965Sjdp@ifclear no-line-dir 495333965Sjdp@samp{.ln} is a synonym for @samp{.line}. 495433965Sjdp@end ifclear 495533965Sjdp@ifset no-line-dir 495689857SobrienTell @command{@value{AS}} to change the logical line number. @var{line-number} 495733965Sjdpmust be an absolute expression. The next line has that logical 495833965Sjdpline number, so any other statements on the current line (after a 495933965Sjdpstatement separator character @code{;}) are reported as on logical 496033965Sjdpline number @var{line-number} @minus{} 1. 496133965Sjdp@ifset BOUT 496233965Sjdp 496389857SobrienThis directive is accepted, but ignored, when @command{@value{AS}} is 496433965Sjdpconfigured for @code{b.out}; its effect is only associated with COFF 496533965Sjdpoutput format. 496633965Sjdp@end ifset 496733965Sjdp@end ifset 496833965Sjdp 496933965Sjdp@node MRI 497033965Sjdp@section @code{.mri @var{val}} 497133965Sjdp 497233965Sjdp@cindex @code{mri} directive 497333965Sjdp@cindex MRI mode, temporarily 497489857SobrienIf @var{val} is non-zero, this tells @command{@value{AS}} to enter MRI mode. If 497589857Sobrien@var{val} is zero, this tells @command{@value{AS}} to exit MRI mode. This change 497633965Sjdpaffects code assembled until the next @code{.mri} directive, or until the end 497733965Sjdpof the file. @xref{M, MRI mode, MRI mode}. 497833965Sjdp 497933965Sjdp@node List 498033965Sjdp@section @code{.list} 498133965Sjdp 498233965Sjdp@cindex @code{list} directive 498333965Sjdp@cindex listing control, turning on 498433965SjdpControl (in conjunction with the @code{.nolist} directive) whether or 498533965Sjdpnot assembly listings are generated. These two directives maintain an 498633965Sjdpinternal counter (which is zero initially). @code{.list} increments the 498733965Sjdpcounter, and @code{.nolist} decrements it. Assembly listings are 498833965Sjdpgenerated whenever the counter is greater than zero. 498933965Sjdp 499033965SjdpBy default, listings are disabled. When you enable them (with the 499133965Sjdp@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}), 499233965Sjdpthe initial value of the listing counter is one. 499333965Sjdp 499433965Sjdp@node Long 499533965Sjdp@section @code{.long @var{expressions}} 499633965Sjdp 499733965Sjdp@cindex @code{long} directive 4998218822Sdim@code{.long} is the same as @samp{.int}. @xref{Int,,@code{.int}}. 499933965Sjdp 500033965Sjdp@ignore 500133965Sjdp@c no one seems to know what this is for or whether this description is 500233965Sjdp@c what it really ought to do 500333965Sjdp@node Lsym 500433965Sjdp@section @code{.lsym @var{symbol}, @var{expression}} 500533965Sjdp 500633965Sjdp@cindex @code{lsym} directive 500733965Sjdp@cindex symbol, not referenced in assembly 500833965Sjdp@code{.lsym} creates a new symbol named @var{symbol}, but does not put it in 500933965Sjdpthe hash table, ensuring it cannot be referenced by name during the 501033965Sjdprest of the assembly. This sets the attributes of the symbol to be 501133965Sjdpthe same as the expression value: 501233965Sjdp@smallexample 501333965Sjdp@var{other} = @var{descriptor} = 0 501433965Sjdp@var{type} = @r{(section of @var{expression})} 501533965Sjdp@var{value} = @var{expression} 501633965Sjdp@end smallexample 501733965Sjdp@noindent 501833965SjdpThe new symbol is not flagged as external. 501933965Sjdp@end ignore 502033965Sjdp 502133965Sjdp@node Macro 502233965Sjdp@section @code{.macro} 502333965Sjdp 502433965Sjdp@cindex macros 502533965SjdpThe commands @code{.macro} and @code{.endm} allow you to define macros that 502633965Sjdpgenerate assembly output. For example, this definition specifies a macro 502733965Sjdp@code{sum} that puts a sequence of numbers into memory: 502833965Sjdp 502933965Sjdp@example 503033965Sjdp .macro sum from=0, to=5 503133965Sjdp .long \from 503233965Sjdp .if \to-\from 503333965Sjdp sum "(\from+1)",\to 503433965Sjdp .endif 503533965Sjdp .endm 503633965Sjdp@end example 503733965Sjdp 503833965Sjdp@noindent 503933965SjdpWith that definition, @samp{SUM 0,5} is equivalent to this assembly input: 504033965Sjdp 504133965Sjdp@example 504233965Sjdp .long 0 504333965Sjdp .long 1 504433965Sjdp .long 2 504533965Sjdp .long 3 504633965Sjdp .long 4 504733965Sjdp .long 5 504833965Sjdp@end example 504933965Sjdp 505033965Sjdp@ftable @code 505133965Sjdp@item .macro @var{macname} 505233965Sjdp@itemx .macro @var{macname} @var{macargs} @dots{} 505333965Sjdp@cindex @code{macro} directive 505433965SjdpBegin the definition of a macro called @var{macname}. If your macro 505533965Sjdpdefinition requires arguments, specify their names after the macro name, 5056218822Sdimseparated by commas or spaces. You can qualify the macro argument to 5057218822Sdimindicate whether all invocations must specify a non-blank value (through 5058218822Sdim@samp{:@code{req}}), or whether it takes all of the remaining arguments 5059218822Sdim(through @samp{:@code{vararg}}). You can supply a default value for any 5060218822Sdimmacro argument by following the name with @samp{=@var{deflt}}. You 5061218822Sdimcannot define two macros with the same @var{macname} unless it has been 5062218822Sdimsubject to the @code{.purgem} directive (@pxref{Purgem}) between the two 5063218822Sdimdefinitions. For example, these are all valid @code{.macro} statements: 506433965Sjdp 506533965Sjdp@table @code 506633965Sjdp@item .macro comm 506733965SjdpBegin the definition of a macro called @code{comm}, which takes no 506833965Sjdparguments. 506933965Sjdp 5070218822Sdim@item .macro plus1 p, p1 507133965Sjdp@itemx .macro plus1 p p1 507233965SjdpEither statement begins the definition of a macro called @code{plus1}, 507333965Sjdpwhich takes two arguments; within the macro definition, write 507433965Sjdp@samp{\p} or @samp{\p1} to evaluate the arguments. 507533965Sjdp 507633965Sjdp@item .macro reserve_str p1=0 p2 507733965SjdpBegin the definition of a macro called @code{reserve_str}, with two 507833965Sjdparguments. The first argument has a default value, but not the second. 507933965SjdpAfter the definition is complete, you can call the macro either as 508033965Sjdp@samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to 508133965Sjdp@var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str 508233965Sjdp,@var{b}} (with @samp{\p1} evaluating as the default, in this case 508333965Sjdp@samp{0}, and @samp{\p2} evaluating to @var{b}). 508433965Sjdp 5085218822Sdim@item .macro m p1:req, p2=0, p3:vararg 5086218822SdimBegin the definition of a macro called @code{m}, with at least three 5087218822Sdimarguments. The first argument must always have a value specified, but 5088218822Sdimnot the second, which instead has a default value. The third formal 5089218822Sdimwill get assigned all remaining arguments specified at invocation time. 5090218822Sdim 509133965SjdpWhen you call a macro, you can specify the argument values either by 509233965Sjdpposition, or by keyword. For example, @samp{sum 9,17} is equivalent to 509333965Sjdp@samp{sum to=17, from=9}. 509433965Sjdp 5095218822Sdim@end table 5096218822Sdim 5097218822SdimNote that since each of the @var{macargs} can be an identifier exactly 5098218822Sdimas any other one permitted by the target architecture, there may be 5099218822Sdimoccasional problems if the target hand-crafts special meanings to certain 5100218822Sdimcharacters when they occur in a special position. For example, if the colon 5101218822Sdim(@code{:}) is generally permitted to be part of a symbol name, but the 5102218822Sdimarchitecture specific code special-cases it when occurring as the final 5103218822Sdimcharacter of a symbol (to denote a label), then the macro parameter 5104218822Sdimreplacement code will have no way of knowing that and consider the whole 5105218822Sdimconstruct (including the colon) an identifier, and check only this 5106218822Sdimidentifier for being the subject to parameter substitution. So for example 5107218822Sdimthis macro definition: 5108218822Sdim 5109218822Sdim@example 5110218822Sdim .macro label l 5111218822Sdim\l: 5112218822Sdim .endm 5113218822Sdim@end example 5114218822Sdim 5115218822Sdimmight not work as expected. Invoking @samp{label foo} might not create a label 5116218822Sdimcalled @samp{foo} but instead just insert the text @samp{\l:} into the 5117218822Sdimassembler source, probably generating an error about an unrecognised 5118218822Sdimidentifier. 5119218822Sdim 5120218822SdimSimilarly problems might occur with the period character (@samp{.}) 5121218822Sdimwhich is often allowed inside opcode names (and hence identifier names). So 5122218822Sdimfor example constructing a macro to build an opcode from a base name and a 5123218822Sdimlength specifier like this: 5124218822Sdim 5125218822Sdim@example 5126218822Sdim .macro opcode base length 5127218822Sdim \base.\length 5128218822Sdim .endm 5129218822Sdim@end example 5130218822Sdim 5131218822Sdimand invoking it as @samp{opcode store l} will not create a @samp{store.l} 5132218822Sdiminstruction but instead generate some kind of error as the assembler tries to 5133218822Sdiminterpret the text @samp{\base.\length}. 5134218822Sdim 5135218822SdimThere are several possible ways around this problem: 5136218822Sdim 5137218822Sdim@table @code 5138218822Sdim@item Insert white space 5139218822SdimIf it is possible to use white space characters then this is the simplest 5140218822Sdimsolution. eg: 5141218822Sdim 5142218822Sdim@example 5143218822Sdim .macro label l 5144218822Sdim\l : 5145218822Sdim .endm 5146218822Sdim@end example 5147218822Sdim 5148218822Sdim@item Use @samp{\()} 5149218822SdimThe string @samp{\()} can be used to separate the end of a macro argument from 5150218822Sdimthe following text. eg: 5151218822Sdim 5152218822Sdim@example 5153218822Sdim .macro opcode base length 5154218822Sdim \base\().\length 5155218822Sdim .endm 5156218822Sdim@end example 5157218822Sdim 5158218822Sdim@item Use the alternate macro syntax mode 5159218822SdimIn the alternative macro syntax mode the ampersand character (@samp{&}) can be 5160218822Sdimused as a separator. eg: 5161218822Sdim 5162218822Sdim@example 5163218822Sdim .altmacro 5164218822Sdim .macro label l 5165218822Sdiml&: 5166218822Sdim .endm 5167218822Sdim@end example 5168218822Sdim@end table 5169218822Sdim 5170218822SdimNote: this problem of correctly identifying string parameters to pseudo ops 5171218822Sdimalso applies to the identifiers used in @code{.irp} (@pxref{Irp}) 5172218822Sdimand @code{.irpc} (@pxref{Irpc}) as well. 5173218822Sdim 517433965Sjdp@item .endm 517533965Sjdp@cindex @code{endm} directive 517633965SjdpMark the end of a macro definition. 517733965Sjdp 517833965Sjdp@item .exitm 517933965Sjdp@cindex @code{exitm} directive 518033965SjdpExit early from the current macro definition. 518133965Sjdp 518233965Sjdp@cindex number of macros executed 518333965Sjdp@cindex macros, count executed 518433965Sjdp@item \@@ 518589857Sobrien@command{@value{AS}} maintains a counter of how many macros it has 518633965Sjdpexecuted in this pseudo-variable; you can copy that number to your 518733965Sjdpoutput with @samp{\@@}, but @emph{only within a macro definition}. 518833965Sjdp 518933965Sjdp@item LOCAL @var{name} [ , @dots{} ] 519033965Sjdp@emph{Warning: @code{LOCAL} is only available if you select ``alternate 5191218822Sdimmacro syntax'' with @samp{--alternate} or @code{.altmacro}.} 5192218822Sdim@xref{Altmacro,,@code{.altmacro}}. 5193218822Sdim@end ftable 519433965Sjdp 5195218822Sdim@node Altmacro 5196218822Sdim@section @code{.altmacro} 5197218822SdimEnable alternate macro mode, enabling: 5198218822Sdim 5199218822Sdim@ftable @code 5200218822Sdim@item LOCAL @var{name} [ , @dots{} ] 5201218822SdimOne additional directive, @code{LOCAL}, is available. It is used to 5202218822Sdimgenerate a string replacement for each of the @var{name} arguments, and 520333965Sjdpreplace any instances of @var{name} in each macro expansion. The 520433965Sjdpreplacement string is unique in the assembly, and different for each 520533965Sjdpseparate macro expansion. @code{LOCAL} allows you to write macros that 520633965Sjdpdefine symbols, without fear of conflict between separate macro expansions. 5207218822Sdim 5208218822Sdim@item String delimiters 5209218822SdimYou can write strings delimited in these other ways besides 5210218822Sdim@code{"@var{string}"}: 5211218822Sdim 5212218822Sdim@table @code 5213218822Sdim@item '@var{string}' 5214218822SdimYou can delimit strings with single-quote characters. 5215218822Sdim 5216218822Sdim@item <@var{string}> 5217218822SdimYou can delimit strings with matching angle brackets. 5218218822Sdim@end table 5219218822Sdim 5220218822Sdim@item single-character string escape 5221218822SdimTo include any single character literally in a string (even if the 5222218822Sdimcharacter would otherwise have some special meaning), you can prefix the 5223218822Sdimcharacter with @samp{!} (an exclamation mark). For example, you can 5224218822Sdimwrite @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}. 5225218822Sdim 5226218822Sdim@item Expression results as strings 5227218822SdimYou can write @samp{%@var{expr}} to evaluate the expression @var{expr} 5228218822Sdimand use the result as a string. 522933965Sjdp@end ftable 523033965Sjdp 5231218822Sdim@node Noaltmacro 5232218822Sdim@section @code{.noaltmacro} 5233218822SdimDisable alternate macro mode. @xref{Altmacro}. 5234218822Sdim 523533965Sjdp@node Nolist 523633965Sjdp@section @code{.nolist} 523733965Sjdp 523833965Sjdp@cindex @code{nolist} directive 523933965Sjdp@cindex listing control, turning off 524033965SjdpControl (in conjunction with the @code{.list} directive) whether or 524133965Sjdpnot assembly listings are generated. These two directives maintain an 524233965Sjdpinternal counter (which is zero initially). @code{.list} increments the 524333965Sjdpcounter, and @code{.nolist} decrements it. Assembly listings are 524433965Sjdpgenerated whenever the counter is greater than zero. 524533965Sjdp 524633965Sjdp@node Octa 524733965Sjdp@section @code{.octa @var{bignums}} 524833965Sjdp 524933965Sjdp@c FIXME: double size emitted for "octa" on i960, others? Or warn? 525033965Sjdp@cindex @code{octa} directive 525133965Sjdp@cindex integer, 16-byte 525233965Sjdp@cindex sixteen byte integer 525333965SjdpThis directive expects zero or more bignums, separated by commas. For each 525433965Sjdpbignum, it emits a 16-byte integer. 525533965Sjdp 525633965SjdpThe term ``octa'' comes from contexts in which a ``word'' is two bytes; 525733965Sjdphence @emph{octa}-word for 16 bytes. 525833965Sjdp 525933965Sjdp@node Org 526033965Sjdp@section @code{.org @var{new-lc} , @var{fill}} 526133965Sjdp 526233965Sjdp@cindex @code{org} directive 526333965Sjdp@cindex location counter, advancing 526433965Sjdp@cindex advancing location counter 526533965Sjdp@cindex current address, advancing 526633965SjdpAdvance the location counter of the current section to 526733965Sjdp@var{new-lc}. @var{new-lc} is either an absolute expression or an 526833965Sjdpexpression with the same section as the current subsection. That is, 526933965Sjdpyou can't use @code{.org} to cross sections: if @var{new-lc} has the 527033965Sjdpwrong section, the @code{.org} directive is ignored. To be compatible 527133965Sjdpwith former assemblers, if the section of @var{new-lc} is absolute, 527289857Sobrien@command{@value{AS}} issues a warning, then pretends the section of @var{new-lc} 527333965Sjdpis the same as the current subsection. 527433965Sjdp 527533965Sjdp@code{.org} may only increase the location counter, or leave it 527633965Sjdpunchanged; you cannot use @code{.org} to move the location counter 527733965Sjdpbackwards. 527833965Sjdp 527933965Sjdp@c double negative used below "not undefined" because this is a specific 528033965Sjdp@c reference to "undefined" (as SEG_UNKNOWN is called in this manual) 528133965Sjdp@c section. doc@cygnus.com 18feb91 528289857SobrienBecause @command{@value{AS}} tries to assemble programs in one pass, @var{new-lc} 528333965Sjdpmay not be undefined. If you really detest this restriction we eagerly await 528433965Sjdpa chance to share your improved assembler. 528533965Sjdp 528633965SjdpBeware that the origin is relative to the start of the section, not 528733965Sjdpto the start of the subsection. This is compatible with other 528833965Sjdppeople's assemblers. 528933965Sjdp 529033965SjdpWhen the location counter (of the current subsection) is advanced, the 529133965Sjdpintervening bytes are filled with @var{fill} which should be an 529233965Sjdpabsolute expression. If the comma and @var{fill} are omitted, 529333965Sjdp@var{fill} defaults to zero. 529433965Sjdp 529533965Sjdp@node P2align 529633965Sjdp@section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} 529733965Sjdp 529833965Sjdp@cindex padding the location counter given a power of two 529933965Sjdp@cindex @code{p2align} directive 530033965SjdpPad the location counter (in the current subsection) to a particular 530133965Sjdpstorage boundary. The first expression (which must be absolute) is the 530233965Sjdpnumber of low-order zero bits the location counter must have after 530333965Sjdpadvancement. For example @samp{.p2align 3} advances the location 530433965Sjdpcounter until it a multiple of 8. If the location counter is already a 530533965Sjdpmultiple of 8, no change is needed. 530633965Sjdp 530733965SjdpThe second expression (also absolute) gives the fill value to be stored in the 530833965Sjdppadding bytes. It (and the comma) may be omitted. If it is omitted, the 530933965Sjdppadding bytes are normally zero. However, on some systems, if the section is 531033965Sjdpmarked as containing code and the fill value is omitted, the space is filled 531133965Sjdpwith no-op instructions. 531233965Sjdp 531333965SjdpThe third expression is also absolute, and is also optional. If it is present, 531433965Sjdpit is the maximum number of bytes that should be skipped by this alignment 531533965Sjdpdirective. If doing the alignment would require skipping more bytes than the 531633965Sjdpspecified maximum, then the alignment is not done at all. You can omit the 531733965Sjdpfill value (the second argument) entirely by simply using two commas after the 531833965Sjdprequired alignment; this can be useful if you want the alignment to be filled 531933965Sjdpwith no-op instructions when appropriate. 532033965Sjdp 532133965Sjdp@cindex @code{p2alignw} directive 532233965Sjdp@cindex @code{p2alignl} directive 532333965SjdpThe @code{.p2alignw} and @code{.p2alignl} directives are variants of the 532433965Sjdp@code{.p2align} directive. The @code{.p2alignw} directive treats the fill 532533965Sjdppattern as a two byte word value. The @code{.p2alignl} directives treats the 532633965Sjdpfill pattern as a four byte longword value. For example, @code{.p2alignw 532733965Sjdp2,0x368d} will align to a multiple of 4. If it skips two bytes, they will be 532833965Sjdpfilled in with the value 0x368d (the exact placement of the bytes depends upon 532933965Sjdpthe endianness of the processor). If it skips 1 or 3 bytes, the fill value is 533033965Sjdpundefined. 533133965Sjdp 533277298Sobrien@ifset ELF 533377298Sobrien@node Previous 533477298Sobrien@section @code{.previous} 533577298Sobrien 5336130561Sobrien@cindex @code{previous} directive 533777298Sobrien@cindex Section Stack 533877298SobrienThis is one of the ELF section stack manipulation directives. The others are 533977298Sobrien@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}), 534077298Sobrien@code{.pushsection} (@pxref{PushSection}), and @code{.popsection} 534177298Sobrien(@pxref{PopSection}). 534277298Sobrien 534377298SobrienThis directive swaps the current section (and subsection) with most recently 534477298Sobrienreferenced section (and subsection) prior to this one. Multiple 534577298Sobrien@code{.previous} directives in a row will flip between two sections (and their 534677298Sobriensubsections). 534777298Sobrien 534877298SobrienIn terms of the section stack, this directive swaps the current section with 534977298Sobrienthe top section on the section stack. 535077298Sobrien@end ifset 535177298Sobrien 535277298Sobrien@ifset ELF 535377298Sobrien@node PopSection 535477298Sobrien@section @code{.popsection} 535577298Sobrien 5356130561Sobrien@cindex @code{popsection} directive 535777298Sobrien@cindex Section Stack 535877298SobrienThis is one of the ELF section stack manipulation directives. The others are 535977298Sobrien@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}), 536077298Sobrien@code{.pushsection} (@pxref{PushSection}), and @code{.previous} 536177298Sobrien(@pxref{Previous}). 536277298Sobrien 536377298SobrienThis directive replaces the current section (and subsection) with the top 536477298Sobriensection (and subsection) on the section stack. This section is popped off the 536577298Sobrienstack. 536677298Sobrien@end ifset 536777298Sobrien 536860484Sobrien@node Print 536960484Sobrien@section @code{.print @var{string}} 537060484Sobrien 537160484Sobrien@cindex @code{print} directive 537289857Sobrien@command{@value{AS}} will print @var{string} on the standard output during 537360484Sobrienassembly. You must put @var{string} in double quotes. 537460484Sobrien 537577298Sobrien@ifset ELF 537677298Sobrien@node Protected 537777298Sobrien@section @code{.protected @var{names}} 537877298Sobrien 5379130561Sobrien@cindex @code{protected} directive 5380130561Sobrien@cindex visibility 5381218822SdimThis is one of the ELF visibility directives. The other two are 538277298Sobrien@code{.hidden} (@pxref{Hidden}) and @code{.internal} (@pxref{Internal}). 538377298Sobrien 538477298SobrienThis directive overrides the named symbols default visibility (which is set by 538577298Sobrientheir binding: local, global or weak). The directive sets the visibility to 538677298Sobrien@code{protected} which means that any references to the symbols from within the 538777298Sobriencomponents that defines them must be resolved to the definition in that 538877298Sobriencomponent, even if a definition in another component would normally preempt 538977298Sobrienthis. 539077298Sobrien@end ifset 539177298Sobrien 539233965Sjdp@node Psize 539333965Sjdp@section @code{.psize @var{lines} , @var{columns}} 539433965Sjdp 539533965Sjdp@cindex @code{psize} directive 539633965Sjdp@cindex listing control: paper size 539733965Sjdp@cindex paper size, for listings 539833965SjdpUse this directive to declare the number of lines---and, optionally, the 539933965Sjdpnumber of columns---to use for each page, when generating listings. 540033965Sjdp 540133965SjdpIf you do not use @code{.psize}, listings use a default line-count 540233965Sjdpof 60. You may omit the comma and @var{columns} specification; the 540333965Sjdpdefault width is 200 columns. 540433965Sjdp 540589857Sobrien@command{@value{AS}} generates formfeeds whenever the specified number of 540633965Sjdplines is exceeded (or whenever you explicitly request one, using 540733965Sjdp@code{.eject}). 540833965Sjdp 540933965SjdpIf you specify @var{lines} as @code{0}, no formfeeds are generated save 541033965Sjdpthose explicitly specified with @code{.eject}. 541133965Sjdp 541260484Sobrien@node Purgem 541360484Sobrien@section @code{.purgem @var{name}} 541460484Sobrien 541560484Sobrien@cindex @code{purgem} directive 541660484SobrienUndefine the macro @var{name}, so that later uses of the string will not be 541760484Sobrienexpanded. @xref{Macro}. 541860484Sobrien 541977298Sobrien@ifset ELF 542077298Sobrien@node PushSection 542177298Sobrien@section @code{.pushsection @var{name} , @var{subsection}} 542277298Sobrien 5423130561Sobrien@cindex @code{pushsection} directive 542477298Sobrien@cindex Section Stack 542577298SobrienThis is one of the ELF section stack manipulation directives. The others are 542677298Sobrien@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}), 542777298Sobrien@code{.popsection} (@pxref{PopSection}), and @code{.previous} 542877298Sobrien(@pxref{Previous}). 542977298Sobrien 5430218822SdimThis directive pushes the current section (and subsection) onto the 5431218822Sdimtop of the section stack, and then replaces the current section and 5432218822Sdimsubsection with @code{name} and @code{subsection}. 543377298Sobrien@end ifset 543477298Sobrien 543533965Sjdp@node Quad 543633965Sjdp@section @code{.quad @var{bignums}} 543733965Sjdp 543833965Sjdp@cindex @code{quad} directive 543933965Sjdp@code{.quad} expects zero or more bignums, separated by commas. For 544033965Sjdpeach bignum, it emits 544133965Sjdp@ifclear bignum-16 544233965Sjdpan 8-byte integer. If the bignum won't fit in 8 bytes, it prints a 544333965Sjdpwarning message; and just takes the lowest order 8 bytes of the bignum. 544433965Sjdp@cindex eight-byte integer 544533965Sjdp@cindex integer, 8-byte 544633965Sjdp 544733965SjdpThe term ``quad'' comes from contexts in which a ``word'' is two bytes; 544833965Sjdphence @emph{quad}-word for 8 bytes. 544933965Sjdp@end ifclear 545033965Sjdp@ifset bignum-16 545133965Sjdpa 16-byte integer. If the bignum won't fit in 16 bytes, it prints a 545233965Sjdpwarning message; and just takes the lowest order 16 bytes of the bignum. 545333965Sjdp@cindex sixteen-byte integer 545433965Sjdp@cindex integer, 16-byte 545533965Sjdp@end ifset 545633965Sjdp 5457218822Sdim@node Reloc 5458218822Sdim@section @code{.reloc @var{offset}, @var{reloc_name}[, @var{expression}]} 5459218822Sdim 5460218822Sdim@cindex @code{reloc} directive 5461218822SdimGenerate a relocation at @var{offset} of type @var{reloc_name} with value 5462218822Sdim@var{expression}. If @var{offset} is a number, the relocation is generated in 5463218822Sdimthe current section. If @var{offset} is an expression that resolves to a 5464218822Sdimsymbol plus offset, the relocation is generated in the given symbol's section. 5465218822Sdim@var{expression}, if present, must resolve to a symbol plus addend or to an 5466218822Sdimabsolute value, but note that not all targets support an addend. e.g. ELF REL 5467218822Sdimtargets such as i386 store an addend in the section contents rather than in the 5468218822Sdimrelocation. This low level interface does not support addends stored in the 5469218822Sdimsection. 5470218822Sdim 547133965Sjdp@node Rept 547233965Sjdp@section @code{.rept @var{count}} 547333965Sjdp 547433965Sjdp@cindex @code{rept} directive 547533965SjdpRepeat the sequence of lines between the @code{.rept} directive and the next 547633965Sjdp@code{.endr} directive @var{count} times. 547733965Sjdp 547833965SjdpFor example, assembling 547933965Sjdp 548033965Sjdp@example 548133965Sjdp .rept 3 548233965Sjdp .long 0 548333965Sjdp .endr 548433965Sjdp@end example 548533965Sjdp 548633965Sjdpis equivalent to assembling 548733965Sjdp 548833965Sjdp@example 548933965Sjdp .long 0 549033965Sjdp .long 0 549133965Sjdp .long 0 549233965Sjdp@end example 549333965Sjdp 549433965Sjdp@node Sbttl 549533965Sjdp@section @code{.sbttl "@var{subheading}"} 549633965Sjdp 549733965Sjdp@cindex @code{sbttl} directive 549833965Sjdp@cindex subtitles for listings 549933965Sjdp@cindex listing control: subtitle 550033965SjdpUse @var{subheading} as the title (third line, immediately after the 550133965Sjdptitle line) when generating assembly listings. 550233965Sjdp 550333965SjdpThis directive affects subsequent pages, as well as the current page if 550433965Sjdpit appears within ten lines of the top of a page. 550533965Sjdp 550633965Sjdp@ifset COFF 550733965Sjdp@node Scl 550833965Sjdp@section @code{.scl @var{class}} 550933965Sjdp 551033965Sjdp@cindex @code{scl} directive 551133965Sjdp@cindex symbol storage class (COFF) 551233965Sjdp@cindex COFF symbol storage class 551333965SjdpSet the storage-class value for a symbol. This directive may only be 551433965Sjdpused inside a @code{.def}/@code{.endef} pair. Storage class may flag 551533965Sjdpwhether a symbol is static or external, or it may record further 551633965Sjdpsymbolic debugging information. 551733965Sjdp@ifset BOUT 551833965Sjdp 551933965SjdpThe @samp{.scl} directive is primarily associated with COFF output; when 552089857Sobrienconfigured to generate @code{b.out} output format, @command{@value{AS}} 552133965Sjdpaccepts this directive but ignores it. 552233965Sjdp@end ifset 552333965Sjdp@end ifset 552433965Sjdp 5525130561Sobrien@ifset COFF-ELF 552633965Sjdp@node Section 5527130561Sobrien@section @code{.section @var{name}} 552833965Sjdp 552933965Sjdp@cindex named section 553033965SjdpUse the @code{.section} directive to assemble the following code into a section 553133965Sjdpnamed @var{name}. 553233965Sjdp 553333965SjdpThis directive is only supported for targets that actually support arbitrarily 553433965Sjdpnamed sections; on @code{a.out} targets, for example, it is not accepted, even 553533965Sjdpwith a standard @code{a.out} section name. 553633965Sjdp 5537130561Sobrien@ifset COFF 5538130561Sobrien@ifset ELF 5539130561Sobrien@c only print the extra heading if both COFF and ELF are set 5540130561Sobrien@subheading COFF Version 5541130561Sobrien@end ifset 5542130561Sobrien 5543130561Sobrien@cindex @code{section} directive (COFF version) 554433965SjdpFor COFF targets, the @code{.section} directive is used in one of the following 554533965Sjdpways: 554677298Sobrien 554733965Sjdp@smallexample 554833965Sjdp.section @var{name}[, "@var{flags}"] 554933965Sjdp.section @var{name}[, @var{subsegment}] 555033965Sjdp@end smallexample 555133965Sjdp 555233965SjdpIf the optional argument is quoted, it is taken as flags to use for the 555333965Sjdpsection. Each flag is a single character. The following flags are recognized: 555433965Sjdp@table @code 555533965Sjdp@item b 555633965Sjdpbss section (uninitialized data) 555733965Sjdp@item n 555833965Sjdpsection is not loaded 555933965Sjdp@item w 556033965Sjdpwritable section 556133965Sjdp@item d 556233965Sjdpdata section 556333965Sjdp@item r 556433965Sjdpread-only section 556533965Sjdp@item x 556633965Sjdpexecutable section 556760484Sobrien@item s 556860484Sobrienshared section (meaningful for PE targets) 5569104834Sobrien@item a 5570104834Sobrienignored. (For compatibility with the ELF version) 557133965Sjdp@end table 557233965Sjdp 557333965SjdpIf no flags are specified, the default flags depend upon the section name. If 557433965Sjdpthe section name is not recognized, the default will be for the section to be 557589857Sobrienloaded and writable. Note the @code{n} and @code{w} flags remove attributes 557689857Sobrienfrom the section, rather than adding them, so if they are used on their own it 557789857Sobrienwill be as if no flags had been specified at all. 557833965Sjdp 557933965SjdpIf the optional argument to the @code{.section} directive is not quoted, it is 558033965Sjdptaken as a subsegment number (@pxref{Sub-Sections}). 5581130561Sobrien@end ifset 558277298Sobrien 5583130561Sobrien@ifset ELF 5584130561Sobrien@ifset COFF 5585130561Sobrien@c only print the extra heading if both COFF and ELF are set 5586130561Sobrien@subheading ELF Version 5587130561Sobrien@end ifset 558877298Sobrien 558977298Sobrien@cindex Section Stack 559077298SobrienThis is one of the ELF section stack manipulation directives. The others are 559177298Sobrien@code{.subsection} (@pxref{SubSection}), @code{.pushsection} 559277298Sobrien(@pxref{PushSection}), @code{.popsection} (@pxref{PopSection}), and 559377298Sobrien@code{.previous} (@pxref{Previous}). 559433965Sjdp 5595130561Sobrien@cindex @code{section} directive (ELF version) 559633965SjdpFor ELF targets, the @code{.section} directive is used like this: 559777298Sobrien 559833965Sjdp@smallexample 5599218822Sdim.section @var{name} [, "@var{flags}"[, @@@var{type}[,@var{flag_specific_arguments}]]] 560033965Sjdp@end smallexample 560177298Sobrien 560233965SjdpThe optional @var{flags} argument is a quoted string which may contain any 560377298Sobriencombination of the following characters: 560433965Sjdp@table @code 560533965Sjdp@item a 560633965Sjdpsection is allocatable 560733965Sjdp@item w 560833965Sjdpsection is writable 560933965Sjdp@item x 561033965Sjdpsection is executable 561189857Sobrien@item M 561289857Sobriensection is mergeable 561389857Sobrien@item S 561489857Sobriensection contains zero terminated strings 5615218822Sdim@item G 5616218822Sdimsection is a member of a section group 5617218822Sdim@item T 5618218822Sdimsection is used for thread-local-storage 561933965Sjdp@end table 562033965Sjdp 562133965SjdpThe optional @var{type} argument may contain one of the following constants: 562233965Sjdp@table @code 562333965Sjdp@item @@progbits 562433965Sjdpsection contains data 562533965Sjdp@item @@nobits 562633965Sjdpsection does not contain data (i.e., section only occupies space) 5627218822Sdim@item @@note 5628218822Sdimsection contains data which is used by things other than the program 5629218822Sdim@item @@init_array 5630218822Sdimsection contains an array of pointers to init functions 5631218822Sdim@item @@fini_array 5632218822Sdimsection contains an array of pointers to finish functions 5633218822Sdim@item @@preinit_array 5634218822Sdimsection contains an array of pointers to pre-init functions 563533965Sjdp@end table 563633965Sjdp 5637218822SdimMany targets only support the first three section types. 5638218822Sdim 5639130561SobrienNote on targets where the @code{@@} character is the start of a comment (eg 5640130561SobrienARM) then another character is used instead. For example the ARM port uses the 5641130561Sobrien@code{%} character. 5642130561Sobrien 5643218822SdimIf @var{flags} contains the @code{M} symbol then the @var{type} argument must 5644218822Sdimbe specified as well as an extra argument---@var{entsize}---like this: 564589857Sobrien 5646218822Sdim@smallexample 5647218822Sdim.section @var{name} , "@var{flags}"M, @@@var{type}, @var{entsize} 5648218822Sdim@end smallexample 5649218822Sdim 5650218822SdimSections with the @code{M} flag but not @code{S} flag must contain fixed size 5651218822Sdimconstants, each @var{entsize} octets long. Sections with both @code{M} and 5652218822Sdim@code{S} must contain zero terminated strings where each character is 5653218822Sdim@var{entsize} bytes long. The linker may remove duplicates within sections with 5654218822Sdimthe same name, same entity size and same flags. @var{entsize} must be an 5655218822Sdimabsolute expression. 5656218822Sdim 5657218822SdimIf @var{flags} contains the @code{G} symbol then the @var{type} argument must 5658218822Sdimbe present along with an additional field like this: 5659218822Sdim 5660218822Sdim@smallexample 5661218822Sdim.section @var{name} , "@var{flags}"G, @@@var{type}, @var{GroupName}[, @var{linkage}] 5662218822Sdim@end smallexample 5663218822Sdim 5664218822SdimThe @var{GroupName} field specifies the name of the section group to which this 5665218822Sdimparticular section belongs. The optional linkage field can contain: 5666218822Sdim@table @code 5667218822Sdim@item comdat 5668218822Sdimindicates that only one copy of this section should be retained 5669218822Sdim@item .gnu.linkonce 5670218822Sdiman alias for comdat 5671218822Sdim@end table 5672218822Sdim 5673218822SdimNote: if both the @var{M} and @var{G} flags are present then the fields for 5674218822Sdimthe Merge flag should come first, like this: 5675218822Sdim 5676218822Sdim@smallexample 5677218822Sdim.section @var{name} , "@var{flags}"MG, @@@var{type}, @var{entsize}, @var{GroupName}[, @var{linkage}] 5678218822Sdim@end smallexample 5679218822Sdim 568033965SjdpIf no flags are specified, the default flags depend upon the section name. If 568133965Sjdpthe section name is not recognized, the default will be for the section to have 568233965Sjdpnone of the above flags: it will not be allocated in memory, nor writable, nor 568333965Sjdpexecutable. The section will contain data. 568433965Sjdp 568533965SjdpFor ELF targets, the assembler supports another type of @code{.section} 568633965Sjdpdirective for compatibility with the Solaris assembler: 568777298Sobrien 568833965Sjdp@smallexample 568933965Sjdp.section "@var{name}"[, @var{flags}...] 569033965Sjdp@end smallexample 569177298Sobrien 569233965SjdpNote that the section name is quoted. There may be a sequence of comma 569333965Sjdpseparated flags: 569433965Sjdp@table @code 569533965Sjdp@item #alloc 569633965Sjdpsection is allocatable 569733965Sjdp@item #write 569833965Sjdpsection is writable 569933965Sjdp@item #execinstr 570033965Sjdpsection is executable 5701218822Sdim@item #tls 5702218822Sdimsection is used for thread local storage 570333965Sjdp@end table 570433965Sjdp 5705218822SdimThis directive replaces the current section and subsection. See the 5706218822Sdimcontents of the gas testsuite directory @code{gas/testsuite/gas/elf} for 5707218822Sdimsome examples of how this directive and the other section stack directives 5708218822Sdimwork. 5709130561Sobrien@end ifset 5710130561Sobrien@end ifset 571177298Sobrien 571233965Sjdp@node Set 571333965Sjdp@section @code{.set @var{symbol}, @var{expression}} 571433965Sjdp 571533965Sjdp@cindex @code{set} directive 571633965Sjdp@cindex symbol value, setting 571733965SjdpSet the value of @var{symbol} to @var{expression}. This 571833965Sjdpchanges @var{symbol}'s value and type to conform to 571933965Sjdp@var{expression}. If @var{symbol} was flagged as external, it remains 572033965Sjdpflagged (@pxref{Symbol Attributes}). 572133965Sjdp 572233965SjdpYou may @code{.set} a symbol many times in the same assembly. 572333965Sjdp 572433965SjdpIf you @code{.set} a global symbol, the value stored in the object 572533965Sjdpfile is the last value stored into it. 572633965Sjdp 572733965Sjdp@ifset HPPA 572833965SjdpThe syntax for @code{set} on the HPPA is 572933965Sjdp@samp{@var{symbol} .set @var{expression}}. 573033965Sjdp@end ifset 573133965Sjdp 5732218822Sdim@ifset Z80 5733218822SdimOn Z80 @code{set} is a real instruction, use 5734218822Sdim@samp{@var{symbol} defl @var{expression}} instead. 5735218822Sdim@end ifset 5736218822Sdim 573733965Sjdp@node Short 573833965Sjdp@section @code{.short @var{expressions}} 573933965Sjdp 574033965Sjdp@cindex @code{short} directive 574133965Sjdp@ifset GENERIC 574233965Sjdp@code{.short} is normally the same as @samp{.word}. 574333965Sjdp@xref{Word,,@code{.word}}. 574433965Sjdp 574533965SjdpIn some configurations, however, @code{.short} and @code{.word} generate 5746218822Sdimnumbers of different lengths. @xref{Machine Dependencies}. 574733965Sjdp@end ifset 574833965Sjdp@ifclear GENERIC 574933965Sjdp@ifset W16 575033965Sjdp@code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}. 575133965Sjdp@end ifset 575233965Sjdp@ifset W32 575333965SjdpThis expects zero or more @var{expressions}, and emits 575433965Sjdpa 16 bit number for each. 575533965Sjdp@end ifset 575633965Sjdp@end ifclear 575733965Sjdp 575833965Sjdp@node Single 575933965Sjdp@section @code{.single @var{flonums}} 576033965Sjdp 576133965Sjdp@cindex @code{single} directive 576233965Sjdp@cindex floating point numbers (single) 576333965SjdpThis directive assembles zero or more flonums, separated by commas. It 576433965Sjdphas the same effect as @code{.float}. 576533965Sjdp@ifset GENERIC 576633965SjdpThe exact kind of floating point numbers emitted depends on how 576789857Sobrien@command{@value{AS}} is configured. @xref{Machine Dependencies}. 576833965Sjdp@end ifset 576933965Sjdp@ifclear GENERIC 577033965Sjdp@ifset IEEEFLOAT 577133965SjdpOn the @value{TARGET} family, @code{.single} emits 32-bit floating point 577233965Sjdpnumbers in @sc{ieee} format. 577333965Sjdp@end ifset 577433965Sjdp@end ifclear 577533965Sjdp 5776130561Sobrien@ifset COFF-ELF 577733965Sjdp@node Size 5778130561Sobrien@section @code{.size} 577933965Sjdp 5780130561SobrienThis directive is used to set the size associated with a symbol. 578177298Sobrien 5782130561Sobrien@ifset COFF 5783130561Sobrien@ifset ELF 5784130561Sobrien@c only print the extra heading if both COFF and ELF are set 5785130561Sobrien@subheading COFF Version 5786130561Sobrien@end ifset 5787130561Sobrien 5788130561Sobrien@cindex @code{size} directive (COFF version) 5789130561SobrienFor COFF targets, the @code{.size} directive is only permitted inside 5790130561Sobrien@code{.def}/@code{.endef} pairs. It is used like this: 5791130561Sobrien 5792130561Sobrien@smallexample 5793130561Sobrien.size @var{expression} 5794130561Sobrien@end smallexample 5795130561Sobrien 579633965Sjdp@ifset BOUT 579733965Sjdp@samp{.size} is only meaningful when generating COFF format output; when 579889857Sobrien@command{@value{AS}} is generating @code{b.out}, it accepts this directive but 579933965Sjdpignores it. 580033965Sjdp@end ifset 5801130561Sobrien@end ifset 580233965Sjdp 5803130561Sobrien@ifset ELF 5804130561Sobrien@ifset COFF 5805130561Sobrien@c only print the extra heading if both COFF and ELF are set 5806130561Sobrien@subheading ELF Version 5807130561Sobrien@end ifset 580877298Sobrien 5809130561Sobrien@cindex @code{size} directive (ELF version) 5810130561SobrienFor ELF targets, the @code{.size} directive is used like this: 5811130561Sobrien 5812130561Sobrien@smallexample 5813130561Sobrien.size @var{name} , @var{expression} 5814130561Sobrien@end smallexample 5815130561Sobrien 5816130561SobrienThis directive sets the size associated with a symbol @var{name}. 581777298SobrienThe size in bytes is computed from @var{expression} which can make use of label 581877298Sobrienarithmetic. This directive is typically used to set the size of function 581977298Sobriensymbols. 5820130561Sobrien@end ifset 5821130561Sobrien@end ifset 582277298Sobrien 582338889Sjdp@node Sleb128 582438889Sjdp@section @code{.sleb128 @var{expressions}} 582538889Sjdp 582638889Sjdp@cindex @code{sleb128} directive 582738889Sjdp@var{sleb128} stands for ``signed little endian base 128.'' This is a 582838889Sjdpcompact, variable length representation of numbers used by the DWARF 5829218822Sdimsymbolic debugging format. @xref{Uleb128, ,@code{.uleb128}}. 583038889Sjdp 583133965Sjdp@ifclear no-space-dir 583233965Sjdp@node Skip 583333965Sjdp@section @code{.skip @var{size} , @var{fill}} 583433965Sjdp 583533965Sjdp@cindex @code{skip} directive 583633965Sjdp@cindex filling memory 583733965SjdpThis directive emits @var{size} bytes, each of value @var{fill}. Both 583833965Sjdp@var{size} and @var{fill} are absolute expressions. If the comma and 583933965Sjdp@var{fill} are omitted, @var{fill} is assumed to be zero. This is the same as 584033965Sjdp@samp{.space}. 584133965Sjdp 584233965Sjdp@node Space 584333965Sjdp@section @code{.space @var{size} , @var{fill}} 584433965Sjdp 584533965Sjdp@cindex @code{space} directive 584633965Sjdp@cindex filling memory 584733965SjdpThis directive emits @var{size} bytes, each of value @var{fill}. Both 584833965Sjdp@var{size} and @var{fill} are absolute expressions. If the comma 584933965Sjdpand @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same 585033965Sjdpas @samp{.skip}. 585133965Sjdp 585233965Sjdp@ifset HPPA 585333965Sjdp@quotation 585433965Sjdp@emph{Warning:} @code{.space} has a completely different meaning for HPPA 585533965Sjdptargets; use @code{.block} as a substitute. See @cite{HP9000 Series 800 585633965SjdpAssembly Language Reference Manual} (HP 92432-90001) for the meaning of the 585733965Sjdp@code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives}, 585833965Sjdpfor a summary. 585933965Sjdp@end quotation 586033965Sjdp@end ifset 586133965Sjdp@end ifclear 586233965Sjdp 586333965Sjdp@ifset have-stabs 586433965Sjdp@node Stab 586533965Sjdp@section @code{.stabd, .stabn, .stabs} 586633965Sjdp 586733965Sjdp@cindex symbolic debuggers, information for 586833965Sjdp@cindex @code{stab@var{x}} directives 586933965SjdpThere are three directives that begin @samp{.stab}. 587033965SjdpAll emit symbols (@pxref{Symbols}), for use by symbolic debuggers. 587189857SobrienThe symbols are not entered in the @command{@value{AS}} hash table: they 587233965Sjdpcannot be referenced elsewhere in the source file. 587333965SjdpUp to five fields are required: 587433965Sjdp 587533965Sjdp@table @var 587633965Sjdp@item string 587733965SjdpThis is the symbol's name. It may contain any character except 587833965Sjdp@samp{\000}, so is more general than ordinary symbol names. Some 587933965Sjdpdebuggers used to code arbitrarily complex structures into symbol names 588033965Sjdpusing this field. 588133965Sjdp 588233965Sjdp@item type 588333965SjdpAn absolute expression. The symbol's type is set to the low 8 bits of 588433965Sjdpthis expression. Any bit pattern is permitted, but @code{@value{LD}} 588533965Sjdpand debuggers choke on silly bit patterns. 588633965Sjdp 588733965Sjdp@item other 588833965SjdpAn absolute expression. The symbol's ``other'' attribute is set to the 588933965Sjdplow 8 bits of this expression. 589033965Sjdp 589133965Sjdp@item desc 589233965SjdpAn absolute expression. The symbol's descriptor is set to the low 16 589333965Sjdpbits of this expression. 589433965Sjdp 589533965Sjdp@item value 589633965SjdpAn absolute expression which becomes the symbol's value. 589733965Sjdp@end table 589833965Sjdp 589933965SjdpIf a warning is detected while reading a @code{.stabd}, @code{.stabn}, 590033965Sjdpor @code{.stabs} statement, the symbol has probably already been created; 590133965Sjdpyou get a half-formed symbol in your object file. This is 590233965Sjdpcompatible with earlier assemblers! 590333965Sjdp 590433965Sjdp@table @code 590533965Sjdp@cindex @code{stabd} directive 590633965Sjdp@item .stabd @var{type} , @var{other} , @var{desc} 590733965Sjdp 590833965SjdpThe ``name'' of the symbol generated is not even an empty string. 590933965SjdpIt is a null pointer, for compatibility. Older assemblers used a 591033965Sjdpnull pointer so they didn't waste space in object files with empty 591133965Sjdpstrings. 591233965Sjdp 591333965SjdpThe symbol's value is set to the location counter, 591433965Sjdprelocatably. When your program is linked, the value of this symbol 591533965Sjdpis the address of the location counter when the @code{.stabd} was 591633965Sjdpassembled. 591733965Sjdp 591833965Sjdp@cindex @code{stabn} directive 591933965Sjdp@item .stabn @var{type} , @var{other} , @var{desc} , @var{value} 592033965SjdpThe name of the symbol is set to the empty string @code{""}. 592133965Sjdp 592233965Sjdp@cindex @code{stabs} directive 592333965Sjdp@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value} 592433965SjdpAll five fields are specified. 592533965Sjdp@end table 592633965Sjdp@end ifset 592733965Sjdp@c end have-stabs 592833965Sjdp 592933965Sjdp@node String 593033965Sjdp@section @code{.string} "@var{str}" 593133965Sjdp 593233965Sjdp@cindex string, copying to object file 593333965Sjdp@cindex @code{string} directive 593433965Sjdp 593533965SjdpCopy the characters in @var{str} to the object file. You may specify more than 593633965Sjdpone string to copy, separated by commas. Unless otherwise specified for a 593733965Sjdpparticular machine, the assembler marks the end of each string with a 0 byte. 593833965SjdpYou can use any of the escape sequences described in @ref{Strings,,Strings}. 593933965Sjdp 594060484Sobrien@node Struct 594160484Sobrien@section @code{.struct @var{expression}} 594260484Sobrien 594360484Sobrien@cindex @code{struct} directive 594460484SobrienSwitch to the absolute section, and set the section offset to @var{expression}, 594560484Sobrienwhich must be an absolute expression. You might use this as follows: 594660484Sobrien@smallexample 594760484Sobrien .struct 0 594860484Sobrienfield1: 594960484Sobrien .struct field1 + 4 595060484Sobrienfield2: 595160484Sobrien .struct field2 + 4 595260484Sobrienfield3: 595360484Sobrien@end smallexample 595460484SobrienThis would define the symbol @code{field1} to have the value 0, the symbol 595560484Sobrien@code{field2} to have the value 4, and the symbol @code{field3} to have the 595660484Sobrienvalue 8. Assembly would be left in the absolute section, and you would need to 595760484Sobrienuse a @code{.section} directive of some sort to change to some other section 595860484Sobrienbefore further assembly. 595960484Sobrien 596033965Sjdp@ifset ELF 596177298Sobrien@node SubSection 596277298Sobrien@section @code{.subsection @var{name}} 596377298Sobrien 5964130561Sobrien@cindex @code{subsection} directive 596577298Sobrien@cindex Section Stack 596677298SobrienThis is one of the ELF section stack manipulation directives. The others are 596777298Sobrien@code{.section} (@pxref{Section}), @code{.pushsection} (@pxref{PushSection}), 596877298Sobrien@code{.popsection} (@pxref{PopSection}), and @code{.previous} 596977298Sobrien(@pxref{Previous}). 597077298Sobrien 597177298SobrienThis directive replaces the current subsection with @code{name}. The current 597277298Sobriensection is not changed. The replaced subsection is put onto the section stack 597377298Sobrienin place of the then current top of stack subsection. 597477298Sobrien@end ifset 597577298Sobrien 597677298Sobrien@ifset ELF 597733965Sjdp@node Symver 597833965Sjdp@section @code{.symver} 597933965Sjdp@cindex @code{symver} directive 598033965Sjdp@cindex symbol versioning 598133965Sjdp@cindex versions of symbols 598233965SjdpUse the @code{.symver} directive to bind symbols to specific version nodes 598333965Sjdpwithin a source file. This is only supported on ELF platforms, and is 598433965Sjdptypically used when assembling files to be linked into a shared library. 598533965SjdpThere are cases where it may make sense to use this in objects to be bound 598633965Sjdpinto an application itself so as to override a versioned symbol from a 598733965Sjdpshared library. 598833965Sjdp 598977298SobrienFor ELF targets, the @code{.symver} directive can be used like this: 599033965Sjdp@smallexample 599133965Sjdp.symver @var{name}, @var{name2@@nodename} 599233965Sjdp@end smallexample 599377298SobrienIf the symbol @var{name} is defined within the file 599477298Sobrienbeing assembled, the @code{.symver} directive effectively creates a symbol 599533965Sjdpalias with the name @var{name2@@nodename}, and in fact the main reason that we 599633965Sjdpjust don't try and create a regular alias is that the @var{@@} character isn't 599733965Sjdppermitted in symbol names. The @var{name2} part of the name is the actual name 599833965Sjdpof the symbol by which it will be externally referenced. The name @var{name} 599933965Sjdpitself is merely a name of convenience that is used so that it is possible to 600033965Sjdphave definitions for multiple versions of a function within a single source 600133965Sjdpfile, and so that the compiler can unambiguously know which version of a 600233965Sjdpfunction is being mentioned. The @var{nodename} portion of the alias should be 600333965Sjdpthe name of a node specified in the version script supplied to the linker when 600433965Sjdpbuilding a shared library. If you are attempting to override a versioned 600533965Sjdpsymbol from a shared library, then @var{nodename} should correspond to the 600633965Sjdpnodename of the symbol you are trying to override. 600777298Sobrien 600877298SobrienIf the symbol @var{name} is not defined within the file being assembled, all 600977298Sobrienreferences to @var{name} will be changed to @var{name2@@nodename}. If no 601077298Sobrienreference to @var{name} is made, @var{name2@@nodename} will be removed from the 601177298Sobriensymbol table. 601277298Sobrien 601377298SobrienAnother usage of the @code{.symver} directive is: 601477298Sobrien@smallexample 601577298Sobrien.symver @var{name}, @var{name2@@@@nodename} 601677298Sobrien@end smallexample 601777298SobrienIn this case, the symbol @var{name} must exist and be defined within 601877298Sobrienthe file being assembled. It is similar to @var{name2@@nodename}. The 601977298Sobriendifference is @var{name2@@@@nodename} will also be used to resolve 602077298Sobrienreferences to @var{name2} by the linker. 602177298Sobrien 602277298SobrienThe third usage of the @code{.symver} directive is: 602377298Sobrien@smallexample 602477298Sobrien.symver @var{name}, @var{name2@@@@@@nodename} 602577298Sobrien@end smallexample 602677298SobrienWhen @var{name} is not defined within the 602777298Sobrienfile being assembled, it is treated as @var{name2@@nodename}. When 602877298Sobrien@var{name} is defined within the file being assembled, the symbol 602977298Sobrienname, @var{name}, will be changed to @var{name2@@@@nodename}. 603033965Sjdp@end ifset 603133965Sjdp 603233965Sjdp@ifset COFF 603333965Sjdp@node Tag 603433965Sjdp@section @code{.tag @var{structname}} 603533965Sjdp 603633965Sjdp@cindex COFF structure debugging 603733965Sjdp@cindex structure debugging, COFF 603833965Sjdp@cindex @code{tag} directive 603933965SjdpThis directive is generated by compilers to include auxiliary debugging 604033965Sjdpinformation in the symbol table. It is only permitted inside 604133965Sjdp@code{.def}/@code{.endef} pairs. Tags are used to link structure 604233965Sjdpdefinitions in the symbol table with instances of those structures. 604333965Sjdp@ifset BOUT 604433965Sjdp 604533965Sjdp@samp{.tag} is only used when generating COFF format output; when 604689857Sobrien@command{@value{AS}} is generating @code{b.out}, it accepts this directive but 604733965Sjdpignores it. 604833965Sjdp@end ifset 604933965Sjdp@end ifset 605033965Sjdp 605133965Sjdp@node Text 605233965Sjdp@section @code{.text @var{subsection}} 605333965Sjdp 605433965Sjdp@cindex @code{text} directive 605589857SobrienTells @command{@value{AS}} to assemble the following statements onto the end of 605633965Sjdpthe text subsection numbered @var{subsection}, which is an absolute 605733965Sjdpexpression. If @var{subsection} is omitted, subsection number zero 605833965Sjdpis used. 605933965Sjdp 606033965Sjdp@node Title 606133965Sjdp@section @code{.title "@var{heading}"} 606233965Sjdp 606333965Sjdp@cindex @code{title} directive 606433965Sjdp@cindex listing control: title line 606533965SjdpUse @var{heading} as the title (second line, immediately after the 606633965Sjdpsource file name and pagenumber) when generating assembly listings. 606733965Sjdp 606833965SjdpThis directive affects subsequent pages, as well as the current page if 606933965Sjdpit appears within ten lines of the top of a page. 607033965Sjdp 6071130561Sobrien@ifset COFF-ELF 607233965Sjdp@node Type 6073130561Sobrien@section @code{.type} 607433965Sjdp 6075130561SobrienThis directive is used to set the type of a symbol. 6076130561Sobrien 6077130561Sobrien@ifset COFF 6078130561Sobrien@ifset ELF 6079130561Sobrien@c only print the extra heading if both COFF and ELF are set 6080130561Sobrien@subheading COFF Version 6081130561Sobrien@end ifset 6082130561Sobrien 608333965Sjdp@cindex COFF symbol type 608433965Sjdp@cindex symbol type, COFF 6085130561Sobrien@cindex @code{type} directive (COFF version) 6086130561SobrienFor COFF targets, this directive is permitted only within 6087130561Sobrien@code{.def}/@code{.endef} pairs. It is used like this: 608877298Sobrien 6089130561Sobrien@smallexample 6090130561Sobrien.type @var{int} 6091130561Sobrien@end smallexample 6092130561Sobrien 6093130561SobrienThis records the integer @var{int} as the type attribute of a symbol table 6094130561Sobrienentry. 6095130561Sobrien 609633965Sjdp@ifset BOUT 609733965Sjdp@samp{.type} is associated only with COFF format output; when 609889857Sobrien@command{@value{AS}} is configured for @code{b.out} output, it accepts this 609933965Sjdpdirective but ignores it. 610033965Sjdp@end ifset 6101130561Sobrien@end ifset 610233965Sjdp 6103130561Sobrien@ifset ELF 6104130561Sobrien@ifset COFF 6105130561Sobrien@c only print the extra heading if both COFF and ELF are set 6106130561Sobrien@subheading ELF Version 6107130561Sobrien@end ifset 610877298Sobrien 610977298Sobrien@cindex ELF symbol type 611077298Sobrien@cindex symbol type, ELF 6111130561Sobrien@cindex @code{type} directive (ELF version) 6112130561SobrienFor ELF targets, the @code{.type} directive is used like this: 6113130561Sobrien 6114130561Sobrien@smallexample 6115130561Sobrien.type @var{name} , @var{type description} 6116130561Sobrien@end smallexample 6117130561Sobrien 6118130561SobrienThis sets the type of symbol @var{name} to be either a 611977298Sobrienfunction symbol or an object symbol. There are five different syntaxes 612077298Sobriensupported for the @var{type description} field, in order to provide 6121218822Sdimcompatibility with various other assemblers. 612277298Sobrien 6123218822SdimBecause some of the characters used in these syntaxes (such as @samp{@@} and 6124218822Sdim@samp{#}) are comment characters for some architectures, some of the syntaxes 6125218822Sdimbelow do not work on all architectures. The first variant will be accepted by 6126218822Sdimthe GNU assembler on all architectures so that variant should be used for 6127218822Sdimmaximum portability, if you do not need to assemble your code with other 6128218822Sdimassemblers. 6129218822Sdim 6130218822SdimThe syntaxes supported are: 6131218822Sdim 613277298Sobrien@smallexample 6133218822Sdim .type <name> STT_FUNCTION 6134218822Sdim .type <name> STT_OBJECT 6135218822Sdim 613677298Sobrien .type <name>,#function 613777298Sobrien .type <name>,#object 613877298Sobrien 613977298Sobrien .type <name>,@@function 614077298Sobrien .type <name>,@@object 614177298Sobrien 614277298Sobrien .type <name>,%function 614377298Sobrien .type <name>,%object 614477298Sobrien 614577298Sobrien .type <name>,"function" 614677298Sobrien .type <name>,"object" 614777298Sobrien@end smallexample 6148130561Sobrien@end ifset 6149130561Sobrien@end ifset 615077298Sobrien 615177298Sobrien@node Uleb128 615277298Sobrien@section @code{.uleb128 @var{expressions}} 615377298Sobrien 615477298Sobrien@cindex @code{uleb128} directive 615577298Sobrien@var{uleb128} stands for ``unsigned little endian base 128.'' This is a 615677298Sobriencompact, variable length representation of numbers used by the DWARF 6157218822Sdimsymbolic debugging format. @xref{Sleb128, ,@code{.sleb128}}. 615877298Sobrien 615933965Sjdp@ifset COFF 616033965Sjdp@node Val 616133965Sjdp@section @code{.val @var{addr}} 616233965Sjdp 616333965Sjdp@cindex @code{val} directive 616433965Sjdp@cindex COFF value attribute 616533965Sjdp@cindex value attribute, COFF 616633965SjdpThis directive, permitted only within @code{.def}/@code{.endef} pairs, 616733965Sjdprecords the address @var{addr} as the value attribute of a symbol table 616833965Sjdpentry. 616933965Sjdp@ifset BOUT 617033965Sjdp 617189857Sobrien@samp{.val} is used only for COFF output; when @command{@value{AS}} is 617233965Sjdpconfigured for @code{b.out}, it accepts this directive but ignores it. 617333965Sjdp@end ifset 617433965Sjdp@end ifset 617533965Sjdp 617677298Sobrien@ifset ELF 617777298Sobrien@node Version 617877298Sobrien@section @code{.version "@var{string}"} 617938889Sjdp 6180130561Sobrien@cindex @code{version} directive 618177298SobrienThis directive creates a @code{.note} section and places into it an ELF 618277298Sobrienformatted note of type NT_VERSION. The note's name is set to @code{string}. 618377298Sobrien@end ifset 618438889Sjdp 618560484Sobrien@ifset ELF 618677298Sobrien@node VTableEntry 618777298Sobrien@section @code{.vtable_entry @var{table}, @var{offset}} 618860484Sobrien 6189218822Sdim@cindex @code{vtable_entry} directive 619077298SobrienThis directive finds or creates a symbol @code{table} and creates a 619177298Sobrien@code{VTABLE_ENTRY} relocation for it with an addend of @code{offset}. 619260484Sobrien 619377298Sobrien@node VTableInherit 619477298Sobrien@section @code{.vtable_inherit @var{child}, @var{parent}} 619560484Sobrien 6196218822Sdim@cindex @code{vtable_inherit} directive 619777298SobrienThis directive finds the symbol @code{child} and finds or creates the symbol 619877298Sobrien@code{parent} and then creates a @code{VTABLE_INHERIT} relocation for the 619977298Sobrienparent whose addend is the value of the child symbol. As a special case the 6200218822Sdimparent name of @code{0} is treated as referring to the @code{*ABS*} section. 620177298Sobrien@end ifset 620260484Sobrien 6203218822Sdim@node Warning 6204218822Sdim@section @code{.warning "@var{string}"} 6205218822Sdim@cindex warning directive 6206218822SdimSimilar to the directive @code{.error} 6207218822Sdim(@pxref{Error,,@code{.error "@var{string}"}}), but just emits a warning. 6208218822Sdim 620977298Sobrien@node Weak 621077298Sobrien@section @code{.weak @var{names}} 621160484Sobrien 6212130561Sobrien@cindex @code{weak} directive 621377298SobrienThis directive sets the weak attribute on the comma separated list of symbol 621477298Sobrien@code{names}. If the symbols do not already exist, they will be created. 621560484Sobrien 6216218822SdimOn COFF targets other than PE, weak symbols are a GNU extension. This 6217218822Sdimdirective sets the weak attribute on the comma separated list of symbol 6218218822Sdim@code{names}. If the symbols do not already exist, they will be created. 6219218822Sdim 6220218822SdimOn the PE target, weak symbols are supported natively as weak aliases. 6221218822SdimWhen a weak symbol is created that is not an alias, GAS creates an 6222218822Sdimalternate symbol to hold the default value. 6223218822Sdim 6224218822Sdim@node Weakref 6225218822Sdim@section @code{.weakref @var{alias}, @var{target}} 6226218822Sdim 6227218822Sdim@cindex @code{weakref} directive 6228218822SdimThis directive creates an alias to the target symbol that enables the symbol to 6229218822Sdimbe referenced with weak-symbol semantics, but without actually making it weak. 6230218822SdimIf direct references or definitions of the symbol are present, then the symbol 6231218822Sdimwill not be weak, but if all references to it are through weak references, the 6232218822Sdimsymbol will be marked as weak in the symbol table. 6233218822Sdim 6234218822SdimThe effect is equivalent to moving all references to the alias to a separate 6235218822Sdimassembly source file, renaming the alias to the symbol in it, declaring the 6236218822Sdimsymbol as weak there, and running a reloadable link to merge the object files 6237218822Sdimresulting from the assembly of the new source file and the old source file that 6238218822Sdimhad the references to the alias removed. 6239218822Sdim 6240218822SdimThe alias itself never makes to the symbol table, and is entirely handled 6241218822Sdimwithin the assembler. 6242218822Sdim 624333965Sjdp@node Word 624433965Sjdp@section @code{.word @var{expressions}} 624533965Sjdp 624633965Sjdp@cindex @code{word} directive 624733965SjdpThis directive expects zero or more @var{expressions}, of any section, 624833965Sjdpseparated by commas. 624933965Sjdp@ifclear GENERIC 625033965Sjdp@ifset W32 625189857SobrienFor each expression, @command{@value{AS}} emits a 32-bit number. 625233965Sjdp@end ifset 625333965Sjdp@ifset W16 625489857SobrienFor each expression, @command{@value{AS}} emits a 16-bit number. 625533965Sjdp@end ifset 625633965Sjdp@end ifclear 625733965Sjdp@ifset GENERIC 625833965Sjdp 625933965SjdpThe size of the number emitted, and its byte order, 626033965Sjdpdepend on what target computer the assembly is for. 626133965Sjdp@end ifset 626233965Sjdp 626333965Sjdp@c on amd29k, i960, sparc the "special treatment to support compilers" doesn't 626433965Sjdp@c happen---32-bit addressability, period; no long/short jumps. 626533965Sjdp@ifset DIFF-TBL-KLUGE 626633965Sjdp@cindex difference tables altered 626733965Sjdp@cindex altered difference tables 626833965Sjdp@quotation 626933965Sjdp@emph{Warning: Special Treatment to support Compilers} 627033965Sjdp@end quotation 627133965Sjdp 627233965Sjdp@ifset GENERIC 627333965SjdpMachines with a 32-bit address space, but that do less than 32-bit 627433965Sjdpaddressing, require the following special treatment. If the machine of 627533965Sjdpinterest to you does 32-bit addressing (or doesn't require it; 627633965Sjdp@pxref{Machine Dependencies}), you can ignore this issue. 627733965Sjdp 627833965Sjdp@end ifset 627933965SjdpIn order to assemble compiler output into something that works, 628089857Sobrien@command{@value{AS}} occasionally does strange things to @samp{.word} directives. 628133965SjdpDirectives of the form @samp{.word sym1-sym2} are often emitted by 628289857Sobriencompilers as part of jump tables. Therefore, when @command{@value{AS}} assembles a 628333965Sjdpdirective of the form @samp{.word sym1-sym2}, and the difference between 628489857Sobrien@code{sym1} and @code{sym2} does not fit in 16 bits, @command{@value{AS}} 628533965Sjdpcreates a @dfn{secondary jump table}, immediately before the next label. 628633965SjdpThis secondary jump table is preceded by a short-jump to the 628733965Sjdpfirst byte after the secondary table. This short-jump prevents the flow 628833965Sjdpof control from accidentally falling into the new table. Inside the 628933965Sjdptable is a long-jump to @code{sym2}. The original @samp{.word} 629033965Sjdpcontains @code{sym1} minus the address of the long-jump to 629133965Sjdp@code{sym2}. 629233965Sjdp 629333965SjdpIf there were several occurrences of @samp{.word sym1-sym2} before the 629433965Sjdpsecondary jump table, all of them are adjusted. If there was a 629533965Sjdp@samp{.word sym3-sym4}, that also did not fit in sixteen bits, a 629633965Sjdplong-jump to @code{sym4} is included in the secondary jump table, 629733965Sjdpand the @code{.word} directives are adjusted to contain @code{sym3} 629833965Sjdpminus the address of the long-jump to @code{sym4}; and so on, for as many 629933965Sjdpentries in the original jump table as necessary. 630033965Sjdp 630133965Sjdp@ifset INTERNALS 630289857Sobrien@emph{This feature may be disabled by compiling @command{@value{AS}} with the 630333965Sjdp@samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse 630433965Sjdpassembly language programmers. 630533965Sjdp@end ifset 630633965Sjdp@end ifset 630733965Sjdp@c end DIFF-TBL-KLUGE 630833965Sjdp 630933965Sjdp@node Deprecated 631033965Sjdp@section Deprecated Directives 631133965Sjdp 631233965Sjdp@cindex deprecated directives 631333965Sjdp@cindex obsolescent directives 631433965SjdpOne day these directives won't work. 631533965SjdpThey are included for compatibility with older assemblers. 631633965Sjdp@table @t 631733965Sjdp@item .abort 631833965Sjdp@item .line 631933965Sjdp@end table 632033965Sjdp 632133965Sjdp@ifset GENERIC 632233965Sjdp@node Machine Dependencies 632333965Sjdp@chapter Machine Dependent Features 632433965Sjdp 632533965Sjdp@cindex machine dependencies 632633965SjdpThe machine instruction sets are (almost by definition) different on 632789857Sobrieneach machine where @command{@value{AS}} runs. Floating point representations 632889857Sobrienvary as well, and @command{@value{AS}} often supports a few additional 632933965Sjdpdirectives or command-line options for compatibility with other 633033965Sjdpassemblers on a particular platform. Finally, some versions of 633189857Sobrien@command{@value{AS}} support special pseudo-instructions for branch 633233965Sjdpoptimization. 633333965Sjdp 633433965SjdpThis chapter discusses most of these differences, though it does not 633533965Sjdpinclude details on any machine's instruction set. For details on that 633633965Sjdpsubject, see the hardware manufacturer's manual. 633733965Sjdp 633833965Sjdp@menu 633991041Sobrien@ifset ALPHA 634091041Sobrien* Alpha-Dependent:: Alpha Dependent Features 634191041Sobrien@end ifset 634238889Sjdp@ifset ARC 634338889Sjdp* ARC-Dependent:: ARC Dependent Features 634438889Sjdp@end ifset 634538889Sjdp@ifset ARM 634638889Sjdp* ARM-Dependent:: ARM Dependent Features 634738889Sjdp@end ifset 6348218822Sdim@ifset AVR 6349218822Sdim* AVR-Dependent:: AVR Dependent Features 6350218822Sdim@end ifset 6351218822Sdim@ifset BFIN 6352218822Sdim* BFIN-Dependent:: BFIN Dependent Features 6353218822Sdim@end ifset 6354218822Sdim@ifset CR16 6355218822Sdim* CR16-Dependent:: CR16 Dependent Features 6356218822Sdim@end ifset 635791041Sobrien@ifset CRIS 635891041Sobrien* CRIS-Dependent:: CRIS Dependent Features 635991041Sobrien@end ifset 636033965Sjdp@ifset D10V 636133965Sjdp* D10V-Dependent:: D10V Dependent Features 636233965Sjdp@end ifset 636360484Sobrien@ifset D30V 636460484Sobrien* D30V-Dependent:: D30V Dependent Features 636560484Sobrien@end ifset 636633965Sjdp@ifset H8/300 6367130561Sobrien* H8/300-Dependent:: Renesas H8/300 Dependent Features 636833965Sjdp@end ifset 636933965Sjdp@ifset HPPA 637033965Sjdp* HPPA-Dependent:: HPPA Dependent Features 637133965Sjdp@end ifset 637260484Sobrien@ifset I370 637360484Sobrien* ESA/390-Dependent:: IBM ESA/390 Dependent Features 637460484Sobrien@end ifset 637533965Sjdp@ifset I80386 637677298Sobrien* i386-Dependent:: Intel 80386 and AMD x86-64 Dependent Features 637733965Sjdp@end ifset 637877298Sobrien@ifset I860 637977298Sobrien* i860-Dependent:: Intel 80860 Dependent Features 638077298Sobrien@end ifset 638133965Sjdp@ifset I960 638233965Sjdp* i960-Dependent:: Intel 80960 Dependent Features 638333965Sjdp@end ifset 6384218822Sdim@ifset IA64 6385218822Sdim* IA-64-Dependent:: Intel IA-64 Dependent Features 6386218822Sdim@end ifset 6387130561Sobrien@ifset IP2K 6388130561Sobrien* IP2K-Dependent:: IP2K Dependent Features 6389130561Sobrien@end ifset 6390218822Sdim@ifset M32C 6391218822Sdim* M32C-Dependent:: M32C Dependent Features 6392218822Sdim@end ifset 639377298Sobrien@ifset M32R 639477298Sobrien* M32R-Dependent:: M32R Dependent Features 639577298Sobrien@end ifset 639633965Sjdp@ifset M680X0 639733965Sjdp* M68K-Dependent:: M680x0 Dependent Features 639833965Sjdp@end ifset 639977298Sobrien@ifset M68HC11 640077298Sobrien* M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features 640177298Sobrien@end ifset 640233965Sjdp@ifset MIPS 640333965Sjdp* MIPS-Dependent:: MIPS Dependent Features 640433965Sjdp@end ifset 640589857Sobrien@ifset MMIX 640689857Sobrien* MMIX-Dependent:: MMIX Dependent Features 640789857Sobrien@end ifset 6408130561Sobrien@ifset MSP430 6409130561Sobrien* MSP430-Dependent:: MSP430 Dependent Features 6410130561Sobrien@end ifset 641133965Sjdp@ifset SH 6412130561Sobrien* SH-Dependent:: Renesas / SuperH SH Dependent Features 6413130561Sobrien* SH64-Dependent:: SuperH SH64 Dependent Features 641433965Sjdp@end ifset 641589857Sobrien@ifset PDP11 641689857Sobrien* PDP-11-Dependent:: PDP-11 Dependent Features 641789857Sobrien@end ifset 641860484Sobrien@ifset PJ 641960484Sobrien* PJ-Dependent:: picoJava Dependent Features 642060484Sobrien@end ifset 642189857Sobrien@ifset PPC 642289857Sobrien* PPC-Dependent:: PowerPC Dependent Features 642389857Sobrien@end ifset 642433965Sjdp@ifset SPARC 642533965Sjdp* Sparc-Dependent:: SPARC Dependent Features 642633965Sjdp@end ifset 642777298Sobrien@ifset TIC54X 642877298Sobrien* TIC54X-Dependent:: TI TMS320C54x Dependent Features 642977298Sobrien@end ifset 643038889Sjdp@ifset V850 643138889Sjdp* V850-Dependent:: V850 Dependent Features 643238889Sjdp@end ifset 6433130561Sobrien@ifset XTENSA 6434130561Sobrien* Xtensa-Dependent:: Xtensa Dependent Features 6435130561Sobrien@end ifset 6436218822Sdim@ifset Z80 6437218822Sdim* Z80-Dependent:: Z80 Dependent Features 6438218822Sdim@end ifset 643933965Sjdp@ifset Z8000 644033965Sjdp* Z8000-Dependent:: Z8000 Dependent Features 644133965Sjdp@end ifset 644233965Sjdp@ifset VAX 644333965Sjdp* Vax-Dependent:: VAX Dependent Features 644433965Sjdp@end ifset 644533965Sjdp@end menu 644633965Sjdp 644733965Sjdp@lowersections 644833965Sjdp@end ifset 644933965Sjdp 645033965Sjdp@c The following major nodes are *sections* in the GENERIC version, *chapters* 645133965Sjdp@c in single-cpu versions. This is mainly achieved by @lowersections. There is a 645233965Sjdp@c peculiarity: to preserve cross-references, there must be a node called 645333965Sjdp@c "Machine Dependencies". Hence the conditional nodenames in each 645433965Sjdp@c major node below. Node defaulting in makeinfo requires adjacency of 645533965Sjdp@c node and sectioning commands; hence the repetition of @chapter BLAH 645633965Sjdp@c in both conditional blocks. 645733965Sjdp 645891041Sobrien@ifset ALPHA 645991041Sobrien@include c-alpha.texi 646091041Sobrien@end ifset 646191041Sobrien 646238889Sjdp@ifset ARC 646377298Sobrien@include c-arc.texi 646438889Sjdp@end ifset 646533965Sjdp 646638889Sjdp@ifset ARM 646738889Sjdp@include c-arm.texi 646838889Sjdp@end ifset 646938889Sjdp 6470218822Sdim@ifset AVR 6471218822Sdim@include c-avr.texi 6472218822Sdim@end ifset 6473218822Sdim 6474218822Sdim@ifset BFIN 6475218822Sdim@include c-bfin.texi 6476218822Sdim@end ifset 6477218822Sdim 6478218822Sdim@ifset CR16 6479218822Sdim@include c-cr16.texi 6480218822Sdim@end ifset 6481218822Sdim 648291041Sobrien@ifset CRIS 648391041Sobrien@include c-cris.texi 648491041Sobrien@end ifset 648591041Sobrien 6486130561Sobrien@ifset Renesas-all 648733965Sjdp@ifclear GENERIC 648833965Sjdp@node Machine Dependencies 648933965Sjdp@chapter Machine Dependent Features 649033965Sjdp 6491130561SobrienThe machine instruction sets are different on each Renesas chip family, 649233965Sjdpand there are also some syntax differences among the families. This 649389857Sobrienchapter describes the specific @command{@value{AS}} features for each 649433965Sjdpfamily. 649533965Sjdp 649633965Sjdp@menu 6497130561Sobrien* H8/300-Dependent:: Renesas H8/300 Dependent Features 6498130561Sobrien* SH-Dependent:: Renesas SH Dependent Features 649933965Sjdp@end menu 650033965Sjdp@lowersections 650133965Sjdp@end ifclear 650233965Sjdp@end ifset 650333965Sjdp 650433965Sjdp@ifset D10V 650533965Sjdp@include c-d10v.texi 650633965Sjdp@end ifset 650733965Sjdp 650860484Sobrien@ifset D30V 650960484Sobrien@include c-d30v.texi 651060484Sobrien@end ifset 651138889Sjdp 651233965Sjdp@ifset H8/300 651333965Sjdp@include c-h8300.texi 651433965Sjdp@end ifset 651533965Sjdp 651633965Sjdp@ifset HPPA 651733965Sjdp@include c-hppa.texi 651833965Sjdp@end ifset 651933965Sjdp 652060484Sobrien@ifset I370 652160484Sobrien@include c-i370.texi 652260484Sobrien@end ifset 652360484Sobrien 652433965Sjdp@ifset I80386 652533965Sjdp@include c-i386.texi 652633965Sjdp@end ifset 652733965Sjdp 652877298Sobrien@ifset I860 652977298Sobrien@include c-i860.texi 653077298Sobrien@end ifset 653177298Sobrien 653233965Sjdp@ifset I960 653333965Sjdp@include c-i960.texi 653433965Sjdp@end ifset 653533965Sjdp 6536104834Sobrien@ifset IA64 6537104834Sobrien@include c-ia64.texi 6538104834Sobrien@end ifset 6539104834Sobrien 6540130561Sobrien@ifset IP2K 6541130561Sobrien@include c-ip2k.texi 6542130561Sobrien@end ifset 6543130561Sobrien 6544218822Sdim@ifset M32C 6545218822Sdim@include c-m32c.texi 6546218822Sdim@end ifset 6547218822Sdim 654877298Sobrien@ifset M32R 654977298Sobrien@include c-m32r.texi 655077298Sobrien@end ifset 655138889Sjdp 655233965Sjdp@ifset M680X0 655333965Sjdp@include c-m68k.texi 655433965Sjdp@end ifset 655533965Sjdp 655677298Sobrien@ifset M68HC11 655777298Sobrien@include c-m68hc11.texi 655877298Sobrien@end ifset 655977298Sobrien 656033965Sjdp@ifset MIPS 656133965Sjdp@include c-mips.texi 656233965Sjdp@end ifset 656333965Sjdp 656489857Sobrien@ifset MMIX 656589857Sobrien@include c-mmix.texi 656689857Sobrien@end ifset 656789857Sobrien 6568130561Sobrien@ifset MSP430 6569130561Sobrien@include c-msp430.texi 6570130561Sobrien@end ifset 6571130561Sobrien 657233965Sjdp@ifset NS32K 657333965Sjdp@include c-ns32k.texi 657433965Sjdp@end ifset 657533965Sjdp 657689857Sobrien@ifset PDP11 657789857Sobrien@include c-pdp11.texi 657889857Sobrien@end ifset 657989857Sobrien 658060484Sobrien@ifset PJ 658160484Sobrien@include c-pj.texi 658260484Sobrien@end ifset 658360484Sobrien 658489857Sobrien@ifset PPC 658589857Sobrien@include c-ppc.texi 658689857Sobrien@end ifset 658789857Sobrien 658833965Sjdp@ifset SH 658933965Sjdp@include c-sh.texi 659091041Sobrien@include c-sh64.texi 659133965Sjdp@end ifset 659233965Sjdp 659333965Sjdp@ifset SPARC 659433965Sjdp@include c-sparc.texi 659533965Sjdp@end ifset 659633965Sjdp 659777298Sobrien@ifset TIC54X 659877298Sobrien@include c-tic54x.texi 659977298Sobrien@end ifset 660077298Sobrien 6601218822Sdim@ifset Z80 6602218822Sdim@include c-z80.texi 6603218822Sdim@end ifset 6604218822Sdim 660533965Sjdp@ifset Z8000 660633965Sjdp@include c-z8k.texi 660733965Sjdp@end ifset 660833965Sjdp 660933965Sjdp@ifset VAX 661033965Sjdp@include c-vax.texi 661133965Sjdp@end ifset 661233965Sjdp 661338889Sjdp@ifset V850 661438889Sjdp@include c-v850.texi 661538889Sjdp@end ifset 661638889Sjdp 6617130561Sobrien@ifset XTENSA 6618130561Sobrien@include c-xtensa.texi 6619130561Sobrien@end ifset 6620130561Sobrien 662133965Sjdp@ifset GENERIC 662233965Sjdp@c reverse effect of @down at top of generic Machine-Dep chapter 662333965Sjdp@raisesections 662433965Sjdp@end ifset 662533965Sjdp 662633965Sjdp@node Reporting Bugs 662733965Sjdp@chapter Reporting Bugs 662833965Sjdp@cindex bugs in assembler 662933965Sjdp@cindex reporting bugs in assembler 663033965Sjdp 663189857SobrienYour bug reports play an essential role in making @command{@value{AS}} reliable. 663233965Sjdp 663333965SjdpReporting a bug may help you by bringing a solution to your problem, or it may 663433965Sjdpnot. But in any case the principal function of a bug report is to help the 663589857Sobrienentire community by making the next version of @command{@value{AS}} work better. 663689857SobrienBug reports are your contribution to the maintenance of @command{@value{AS}}. 663733965Sjdp 663833965SjdpIn order for a bug report to serve its purpose, you must include the 663933965Sjdpinformation that enables us to fix the bug. 664033965Sjdp 664133965Sjdp@menu 664233965Sjdp* Bug Criteria:: Have you found a bug? 664333965Sjdp* Bug Reporting:: How to report bugs 664433965Sjdp@end menu 664533965Sjdp 664633965Sjdp@node Bug Criteria 6647130561Sobrien@section Have You Found a Bug? 664833965Sjdp@cindex bug criteria 664933965Sjdp 665033965SjdpIf you are not sure whether you have found a bug, here are some guidelines: 665133965Sjdp 665233965Sjdp@itemize @bullet 665333965Sjdp@cindex fatal signal 665433965Sjdp@cindex assembler crash 665533965Sjdp@cindex crash of assembler 665633965Sjdp@item 665733965SjdpIf the assembler gets a fatal signal, for any input whatever, that is a 665889857Sobrien@command{@value{AS}} bug. Reliable assemblers never crash. 665933965Sjdp 666033965Sjdp@cindex error on valid input 666133965Sjdp@item 666289857SobrienIf @command{@value{AS}} produces an error message for valid input, that is a bug. 666333965Sjdp 666433965Sjdp@cindex invalid input 666533965Sjdp@item 666689857SobrienIf @command{@value{AS}} does not produce an error message for invalid input, that 666733965Sjdpis a bug. However, you should note that your idea of ``invalid input'' might 666833965Sjdpbe our idea of ``an extension'' or ``support for traditional practice''. 666933965Sjdp 667033965Sjdp@item 667133965SjdpIf you are an experienced user of assemblers, your suggestions for improvement 667289857Sobrienof @command{@value{AS}} are welcome in any case. 667333965Sjdp@end itemize 667433965Sjdp 667533965Sjdp@node Bug Reporting 6676130561Sobrien@section How to Report Bugs 667733965Sjdp@cindex bug reports 667833965Sjdp@cindex assembler bugs, reporting 667933965Sjdp 668033965SjdpA number of companies and individuals offer support for @sc{gnu} products. If 668189857Sobrienyou obtained @command{@value{AS}} from a support organization, we recommend you 668233965Sjdpcontact that organization first. 668333965Sjdp 668433965SjdpYou can find contact information for many support companies and 668533965Sjdpindividuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 668633965Sjdpdistribution. 668733965Sjdp 6688218822Sdim@ifset BUGURL 668989857SobrienIn any event, we also recommend that you send bug reports for @command{@value{AS}} 6690218822Sdimto @value{BUGURL}. 6691218822Sdim@end ifset 669233965Sjdp 669333965SjdpThe fundamental principle of reporting bugs usefully is this: 669433965Sjdp@strong{report all the facts}. If you are not sure whether to state a 669533965Sjdpfact or leave it out, state it! 669633965Sjdp 669733965SjdpOften people omit facts because they think they know what causes the problem 669833965Sjdpand assume that some details do not matter. Thus, you might assume that the 669933965Sjdpname of a symbol you use in an example does not matter. Well, probably it does 670033965Sjdpnot, but one cannot be sure. Perhaps the bug is a stray memory reference which 670133965Sjdphappens to fetch from the location where that name is stored in memory; 670233965Sjdpperhaps, if the name were different, the contents of that location would fool 670333965Sjdpthe assembler into doing the right thing despite the bug. Play it safe and 670433965Sjdpgive a specific, complete example. That is the easiest thing for you to do, 670533965Sjdpand the most helpful. 670633965Sjdp 670733965SjdpKeep in mind that the purpose of a bug report is to enable us to fix the bug if 670833965Sjdpit is new to us. Therefore, always write your bug reports on the assumption 670933965Sjdpthat the bug has not been reported previously. 671033965Sjdp 671133965SjdpSometimes people give a few sketchy facts and ask, ``Does this ring a 6712130561Sobrienbell?'' This cannot help us fix a bug, so it is basically useless. We 6713130561Sobrienrespond by asking for enough details to enable us to investigate. 6714130561SobrienYou might as well expedite matters by sending them to begin with. 671533965Sjdp 671633965SjdpTo enable us to fix the bug, you should include all these things: 671733965Sjdp 671833965Sjdp@itemize @bullet 671933965Sjdp@item 672089857SobrienThe version of @command{@value{AS}}. @command{@value{AS}} announces it if you start 672133965Sjdpit with the @samp{--version} argument. 672233965Sjdp 672333965SjdpWithout this, we will not know whether there is any point in looking for 672489857Sobrienthe bug in the current version of @command{@value{AS}}. 672533965Sjdp 672633965Sjdp@item 672789857SobrienAny patches you may have applied to the @command{@value{AS}} source. 672833965Sjdp 672933965Sjdp@item 673033965SjdpThe type of machine you are using, and the operating system name and 673133965Sjdpversion number. 673233965Sjdp 673333965Sjdp@item 673489857SobrienWhat compiler (and its version) was used to compile @command{@value{AS}}---e.g. 673533965Sjdp``@code{gcc-2.7}''. 673633965Sjdp 673733965Sjdp@item 673833965SjdpThe command arguments you gave the assembler to assemble your example and 673933965Sjdpobserve the bug. To guarantee you will not omit something important, list them 674033965Sjdpall. A copy of the Makefile (or the output from make) is sufficient. 674133965Sjdp 674233965SjdpIf we were to try to guess the arguments, we would probably guess wrong 674333965Sjdpand then we might not encounter the bug. 674433965Sjdp 674533965Sjdp@item 674633965SjdpA complete input file that will reproduce the bug. If the bug is observed when 674733965Sjdpthe assembler is invoked via a compiler, send the assembler source, not the 674833965Sjdphigh level language source. Most compilers will produce the assembler source 674933965Sjdpwhen run with the @samp{-S} option. If you are using @code{@value{GCC}}, use 675033965Sjdpthe options @samp{-v --save-temps}; this will save the assembler source in a 675133965Sjdpfile with an extension of @file{.s}, and also show you exactly how 675289857Sobrien@command{@value{AS}} is being run. 675333965Sjdp 675433965Sjdp@item 675533965SjdpA description of what behavior you observe that you believe is 675633965Sjdpincorrect. For example, ``It gets a fatal signal.'' 675733965Sjdp 675889857SobrienOf course, if the bug is that @command{@value{AS}} gets a fatal signal, then we 675933965Sjdpwill certainly notice it. But if the bug is incorrect output, we might not 676033965Sjdpnotice unless it is glaringly wrong. You might as well not give us a chance to 676133965Sjdpmake a mistake. 676233965Sjdp 676333965SjdpEven if the problem you experience is a fatal signal, you should still say so 676433965Sjdpexplicitly. Suppose something strange is going on, such as, your copy of 6765218822Sdim@command{@value{AS}} is out of sync, or you have encountered a bug in the C 676633965Sjdplibrary on your system. (This has happened!) Your copy might crash and ours 676733965Sjdpwould not. If you told us to expect a crash, then when ours fails to crash, we 676833965Sjdpwould know that the bug was not happening for us. If you had not told us to 676933965Sjdpexpect a crash, then we would not be able to draw any conclusion from our 677033965Sjdpobservations. 677133965Sjdp 677233965Sjdp@item 677389857SobrienIf you wish to suggest changes to the @command{@value{AS}} source, send us context 677433965Sjdpdiffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p} 677533965Sjdpoption. Always send diffs from the old file to the new file. If you even 677689857Sobriendiscuss something in the @command{@value{AS}} source, refer to it by context, not 677733965Sjdpby line number. 677833965Sjdp 677933965SjdpThe line numbers in our development sources will not match those in your 678033965Sjdpsources. Your line numbers would convey no useful information to us. 678133965Sjdp@end itemize 678233965Sjdp 678333965SjdpHere are some things that are not necessary: 678433965Sjdp 678533965Sjdp@itemize @bullet 678633965Sjdp@item 678733965SjdpA description of the envelope of the bug. 678833965Sjdp 678933965SjdpOften people who encounter a bug spend a lot of time investigating 679033965Sjdpwhich changes to the input file will make the bug go away and which 679133965Sjdpchanges will not affect it. 679233965Sjdp 679333965SjdpThis is often time consuming and not very useful, because the way we 679433965Sjdpwill find the bug is by running a single example under the debugger 679533965Sjdpwith breakpoints, not by pure deduction from a series of examples. 679633965SjdpWe recommend that you save your time for something else. 679733965Sjdp 679833965SjdpOf course, if you can find a simpler example to report @emph{instead} 679933965Sjdpof the original one, that is a convenience for us. Errors in the 680033965Sjdpoutput will be easier to spot, running under the debugger will take 680133965Sjdpless time, and so on. 680233965Sjdp 680333965SjdpHowever, simplification is not vital; if you do not want to do this, 680433965Sjdpreport the bug anyway and send us the entire test case you used. 680533965Sjdp 680633965Sjdp@item 680733965SjdpA patch for the bug. 680833965Sjdp 680933965SjdpA patch for the bug does help us if it is a good one. But do not omit 681033965Sjdpthe necessary information, such as the test case, on the assumption that 681133965Sjdpa patch is all we need. We might see problems with your patch and decide 681233965Sjdpto fix the problem another way, or we might not understand it at all. 681333965Sjdp 681489857SobrienSometimes with a program as complicated as @command{@value{AS}} it is very hard to 681533965Sjdpconstruct an example that will make the program follow a certain path through 681633965Sjdpthe code. If you do not send us the example, we will not be able to construct 681733965Sjdpone, so we will not be able to verify that the bug is fixed. 681833965Sjdp 681933965SjdpAnd if we cannot understand what bug you are trying to fix, or why your 682033965Sjdppatch should be an improvement, we will not install it. A test case will 682133965Sjdphelp us to understand. 682233965Sjdp 682333965Sjdp@item 682433965SjdpA guess about what the bug is or what it depends on. 682533965Sjdp 682633965SjdpSuch guesses are usually wrong. Even we cannot guess right about such 682733965Sjdpthings without first using the debugger to find the facts. 682833965Sjdp@end itemize 682933965Sjdp 683033965Sjdp@node Acknowledgements 683133965Sjdp@chapter Acknowledgements 683233965Sjdp 6833218822SdimIf you have contributed to GAS and your name isn't listed here, 683433965Sjdpit is not meant as a slight. We just don't know about it. Send mail to the 683533965Sjdpmaintainer, and we'll correct the situation. Currently 683633965Sjdp@c (January 1994), 683733965Sjdpthe maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}). 683833965Sjdp 683933965SjdpDean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any 684033965Sjdpmore details?} 684133965Sjdp 684233965SjdpJay Fenlason maintained GAS for a while, adding support for GDB-specific debug 684333965Sjdpinformation and the 68k series machines, most of the preprocessing pass, and 684433965Sjdpextensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}. 684533965Sjdp 684633965SjdpK. Richard Pixley maintained GAS for a while, adding various enhancements and 684733965Sjdpmany bug fixes, including merging support for several processors, breaking GAS 684833965Sjdpup to handle multiple object file format back ends (including heavy rewrite, 684933965Sjdptesting, an integration of the coff and b.out back ends), adding configuration 685033965Sjdpincluding heavy testing and verification of cross assemblers and file splits 685133965Sjdpand renaming, converted GAS to strictly ANSI C including full prototypes, added 685233965Sjdpsupport for m680[34]0 and cpu32, did considerable work on i960 including a COFF 685333965Sjdpport (including considerable amounts of reverse engineering), a SPARC opcode 685433965Sjdpfile rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know'' 685533965Sjdpassertions and made them work, much other reorganization, cleanup, and lint. 685633965Sjdp 685733965SjdpKen Raeburn wrote the high-level BFD interface code to replace most of the code 685833965Sjdpin format-specific I/O modules. 685933965Sjdp 686033965SjdpThe original VMS support was contributed by David L. Kashtan. Eric Youngdale 686133965Sjdphas done much work with it since. 686233965Sjdp 686333965SjdpThe Intel 80386 machine description was written by Eliot Dresselhaus. 686433965Sjdp 686533965SjdpMinh Tran-Le at IntelliCorp contributed some AIX 386 support. 686633965Sjdp 686733965SjdpThe Motorola 88k machine description was contributed by Devon Bowen of Buffalo 686833965SjdpUniversity and Torbjorn Granlund of the Swedish Institute of Computer Science. 686933965Sjdp 687033965SjdpKeith Knowles at the Open Software Foundation wrote the original MIPS back end 687133965Sjdp(@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support 687233965Sjdp(which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to 687333965Sjdpsupport a.out format. 687433965Sjdp 6875218822SdimSupport for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, 6876218822Sdimtc-h8300), and IEEE 695 object file format (obj-ieee), was written by 687733965SjdpSteve Chamberlain of Cygnus Support. Steve also modified the COFF back end to 687833965Sjdpuse BFD for some low-level operations, for use with the H8/300 and AMD 29k 687933965Sjdptargets. 688033965Sjdp 688133965SjdpJohn Gilmore built the AMD 29000 support, added @code{.include} support, and 688233965Sjdpsimplified the configuration of which versions accept which directives. He 688333965Sjdpupdated the 68k machine description so that Motorola's opcodes always produced 6884130561Sobrienfixed-size instructions (e.g., @code{jsr}), while synthetic instructions 688533965Sjdpremained shrinkable (@code{jbsr}). John fixed many bugs, including true tested 688633965Sjdpcross-compilation support, and one bug in relaxation that took a week and 688733965Sjdprequired the proverbial one-bit fix. 688833965Sjdp 688933965SjdpIan Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the 689033965Sjdp68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix), 689133965Sjdpadded support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and 689233965SjdpPowerPC assembler, and made a few other minor patches. 689333965Sjdp 6894218822SdimSteve Chamberlain made GAS able to generate listings. 689533965Sjdp 689633965SjdpHewlett-Packard contributed support for the HP9000/300. 689733965Sjdp 689833965SjdpJeff Law wrote GAS and BFD support for the native HPPA object format (SOM) 689933965Sjdpalong with a fairly extensive HPPA testsuite (for both SOM and ELF object 690033965Sjdpformats). This work was supported by both the Center for Software Science at 690133965Sjdpthe University of Utah and Cygnus Support. 690233965Sjdp 690333965SjdpSupport for ELF format files has been worked on by Mark Eichin of Cygnus 690433965SjdpSupport (original, incomplete implementation for SPARC), Pete Hoogenboom and 690533965SjdpJeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open 690633965SjdpSoftware Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc, 690733965Sjdpand some initial 64-bit support). 690833965Sjdp 6909130561SobrienLinas Vepstas added GAS support for the ESA/390 ``IBM 370'' architecture. 691060484Sobrien 691133965SjdpRichard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD 691233965Sjdpsupport for openVMS/Alpha. 691333965Sjdp 691477298SobrienTimothy Wall, Michael Hayes, and Greg Smart contributed to the various tic* 691577298Sobrienflavors. 691677298Sobrien 6917130561SobrienDavid Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica, 6918218822SdimInc.@: added support for Xtensa processors. 6919130561Sobrien 692033965SjdpSeveral engineers at Cygnus Support have also provided many small bug fixes and 692133965Sjdpconfiguration enhancements. 692233965Sjdp 692333965SjdpMany others have contributed large or small bugfixes and enhancements. If 692433965Sjdpyou have contributed significant work and are not mentioned on this list, and 692533965Sjdpwant to be, let us know. Some of the history has been lost; we are not 692633965Sjdpintentionally leaving anyone out. 692733965Sjdp 6928130561Sobrien@include fdl.texi 692977298Sobrien 6930218822Sdim@node AS Index 6931218822Sdim@unnumbered AS Index 693233965Sjdp 693333965Sjdp@printindex cp 693433965Sjdp 693533965Sjdp@bye 693633965Sjdp@c Local Variables: 693733965Sjdp@c fill-column: 79 693833965Sjdp@c End: 6939