3044 lines
94 KiB
HTML
3044 lines
94 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>Using The GNU Assembler</TITLE>
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
|
|
</HEAD>
|
|
<BODY BGCOLOR="#FFF9D3">
|
|
<TABLE COLS=3 WIDTH="100%" NOSAVE >
|
|
<TR>
|
|
<TD WIDTH="1%"><A HREF="http://www.amazon.com/exec/obidos/ISBN=0201308215">
|
|
<IMG SRC="../ladcover-sm.jpg"></A></TD>
|
|
<TD><B><FONT COLOR="#953654" SIZE=+4>Linux
|
|
<BR>Application
|
|
<BR>Development</FONT></B></TD>
|
|
|
|
<TD>
|
|
<CENTER>
|
|
<HR WIDTH="100%">
|
|
<B><I><FONT COLOR="#0F696F" SIZE=+3>Michael K. Johnson
|
|
<BR>Erik W. Troan</FONT></I></B>
|
|
<HR WIDTH="100%"></CENTER>
|
|
</TD>
|
|
</TR>
|
|
</TABLE>
|
|
|
|
|
|
<H1>Using </H1>
|
|
<H2>The GNU Assembler</H2>
|
|
<H2>for the family</H2>
|
|
<H2>January 1994</H2>
|
|
<ADDRESS>Dean Elsner, Jay Fenlason & friends</ADDRESS>
|
|
<P>
|
|
<P><HR><P>
|
|
<H1>Table of Contents</H1>
|
|
<UL>
|
|
<LI><A NAME="TOC1" HREF="#SEC1">Overview</A>
|
|
<UL>
|
|
<LI><A NAME="TOC2" HREF="#SEC2">Structure of this Manual</A>
|
|
<LI><A NAME="TOC3" HREF="#SEC3">The GNU Assembler</A>
|
|
<LI><A NAME="TOC4" HREF="#SEC4">Object File Formats</A>
|
|
<LI><A NAME="TOC5" HREF="#SEC5">Command Line</A>
|
|
<LI><A NAME="TOC6" HREF="#SEC6">Input Files</A>
|
|
<LI><A NAME="TOC7" HREF="#SEC7">Output (Object) File</A>
|
|
<LI><A NAME="TOC8" HREF="#SEC8">Error and Warning Messages</A>
|
|
</UL>
|
|
<LI><A NAME="TOC9" HREF="#SEC9">Command-Line Options</A>
|
|
<UL>
|
|
<LI><A NAME="TOC10" HREF="#SEC10">Enable Listings: <CODE>-a[cdhlns]</CODE></A>
|
|
<LI><A NAME="TOC11" HREF="#SEC11"><CODE>-D</CODE></A>
|
|
<LI><A NAME="TOC12" HREF="#SEC12">Work Faster: <CODE>-f</CODE></A>
|
|
<LI><A NAME="TOC13" HREF="#SEC13"><CODE>.include</CODE> search path: <CODE>-I</CODE> <VAR>path</VAR></A>
|
|
<LI><A NAME="TOC14" HREF="#SEC14">Difference Tables: <CODE>-K</CODE></A>
|
|
<LI><A NAME="TOC15" HREF="#SEC15">Include Local Labels: <CODE>-L</CODE></A>
|
|
<LI><A NAME="TOC16" HREF="#SEC16">Assemble in MRI Compatibility Mode: <CODE>-M</CODE></A>
|
|
<LI><A NAME="TOC17" HREF="#SEC17">Name the Object File: <CODE>-o</CODE></A>
|
|
<LI><A NAME="TOC18" HREF="#SEC18">Join Data and Text Sections: <CODE>-R</CODE></A>
|
|
<LI><A NAME="TOC19" HREF="#SEC19">Display Assembly Statistics: <CODE>--statistics</CODE></A>
|
|
<LI><A NAME="TOC20" HREF="#SEC20">Announce Version: <CODE>-v</CODE></A>
|
|
<LI><A NAME="TOC21" HREF="#SEC21">Suppress Warnings: <CODE>-W</CODE></A>
|
|
<LI><A NAME="TOC22" HREF="#SEC22">Generate Object File in Spite of Errors: <CODE>-Z</CODE></A>
|
|
</UL>
|
|
<LI><A NAME="TOC23" HREF="#SEC23">Syntax</A>
|
|
<UL>
|
|
<LI><A NAME="TOC24" HREF="#SEC24">Preprocessing</A>
|
|
<LI><A NAME="TOC25" HREF="#SEC25">Whitespace</A>
|
|
<LI><A NAME="TOC26" HREF="#SEC26">Comments</A>
|
|
<LI><A NAME="TOC27" HREF="#SEC27">Symbols</A>
|
|
<LI><A NAME="TOC28" HREF="#SEC28">Statements</A>
|
|
<LI><A NAME="TOC29" HREF="#SEC29">Constants</A>
|
|
<UL>
|
|
<LI><A NAME="TOC30" HREF="#SEC30">Character Constants</A>
|
|
<UL>
|
|
<LI><A NAME="TOC31" HREF="#SEC31">Strings</A>
|
|
<LI><A NAME="TOC32" HREF="#SEC32">Characters</A>
|
|
</UL>
|
|
<LI><A NAME="TOC33" HREF="#SEC33">Number Constants</A>
|
|
<UL>
|
|
<LI><A NAME="TOC34" HREF="#SEC34">Integers</A>
|
|
<LI><A NAME="TOC35" HREF="#SEC35">Bignums</A>
|
|
<LI><A NAME="TOC36" HREF="#SEC36">Flonums</A>
|
|
</UL>
|
|
</UL>
|
|
</UL>
|
|
<LI><A NAME="TOC37" HREF="#SEC37">Sections and Relocation</A>
|
|
<UL>
|
|
<LI><A NAME="TOC38" HREF="#SEC38">Background</A>
|
|
<LI><A NAME="TOC39" HREF="#SEC39">Linker Sections</A>
|
|
<LI><A NAME="TOC40" HREF="#SEC40">Assembler Internal Sections</A>
|
|
<LI><A NAME="TOC41" HREF="#SEC41">Sub-Sections</A>
|
|
<LI><A NAME="TOC42" HREF="#SEC42">bss Section</A>
|
|
</UL>
|
|
<LI><A NAME="TOC43" HREF="#SEC43">Symbols</A>
|
|
<UL>
|
|
<LI><A NAME="TOC44" HREF="#SEC44">Labels</A>
|
|
<LI><A NAME="TOC45" HREF="#SEC45">Giving Symbols Other Values</A>
|
|
<LI><A NAME="TOC46" HREF="#SEC46">Symbol Names</A>
|
|
<LI><A NAME="TOC47" HREF="#SEC47">The Special Dot Symbol</A>
|
|
<LI><A NAME="TOC48" HREF="#SEC48">Symbol Attributes</A>
|
|
<UL>
|
|
<LI><A NAME="TOC49" HREF="#SEC49">Value</A>
|
|
<LI><A NAME="TOC50" HREF="#SEC50">Type</A>
|
|
<LI><A NAME="TOC51" HREF="#SEC51">Symbol Attributes: <CODE>a.out</CODE></A>
|
|
<UL>
|
|
<LI><A NAME="TOC52" HREF="#SEC52">Descriptor</A>
|
|
<LI><A NAME="TOC53" HREF="#SEC53">Other</A>
|
|
</UL>
|
|
</UL>
|
|
</UL>
|
|
<LI><A NAME="TOC54" HREF="#SEC54">Expressions</A>
|
|
<UL>
|
|
<LI><A NAME="TOC55" HREF="#SEC55">Empty Expressions</A>
|
|
<LI><A NAME="TOC56" HREF="#SEC56">Integer Expressions</A>
|
|
<UL>
|
|
<LI><A NAME="TOC57" HREF="#SEC57">Arguments</A>
|
|
<LI><A NAME="TOC58" HREF="#SEC58">Operators</A>
|
|
<LI><A NAME="TOC59" HREF="#SEC59">Prefix Operator</A>
|
|
<LI><A NAME="TOC60" HREF="#SEC60">Infix Operators</A>
|
|
</UL>
|
|
</UL>
|
|
<LI><A NAME="TOC61" HREF="#SEC61">Assembler Directives</A>
|
|
<UL>
|
|
<LI><A NAME="TOC62" HREF="#SEC62"><CODE>.abort</CODE></A>
|
|
<LI><A NAME="TOC63" HREF="#SEC63"><CODE>.align <VAR>abs-expr</VAR>, <VAR>abs-expr</VAR>, <VAR>abs-expr</VAR></CODE></A>
|
|
<LI><A NAME="TOC64" HREF="#SEC64"><CODE>.app-file <VAR>string</VAR></CODE></A>
|
|
<LI><A NAME="TOC65" HREF="#SEC65"><CODE>.ascii "<VAR>string</VAR>"</CODE>...</A>
|
|
<LI><A NAME="TOC66" HREF="#SEC66"><CODE>.asciz "<VAR>string</VAR>"</CODE>...</A>
|
|
<LI><A NAME="TOC67" HREF="#SEC67"><CODE>.balign[wl] <VAR>abs-expr</VAR>, <VAR>abs-expr</VAR>, <VAR>abs-expr</VAR></CODE></A>
|
|
<LI><A NAME="TOC68" HREF="#SEC68"><CODE>.byte <VAR>expressions</VAR></CODE></A>
|
|
<LI><A NAME="TOC69" HREF="#SEC69"><CODE>.comm <VAR>symbol</VAR> , <VAR>length</VAR> </CODE></A>
|
|
<LI><A NAME="TOC70" HREF="#SEC70"><CODE>.data <VAR>subsection</VAR></CODE></A>
|
|
<LI><A NAME="TOC71" HREF="#SEC71"><CODE>.double <VAR>flonums</VAR></CODE></A>
|
|
<LI><A NAME="TOC72" HREF="#SEC72"><CODE>.eject</CODE></A>
|
|
<LI><A NAME="TOC73" HREF="#SEC73"><CODE>.else</CODE></A>
|
|
<LI><A NAME="TOC74" HREF="#SEC74"><CODE>.endif</CODE></A>
|
|
<LI><A NAME="TOC75" HREF="#SEC75"><CODE>.equ <VAR>symbol</VAR>, <VAR>expression</VAR></CODE></A>
|
|
<LI><A NAME="TOC76" HREF="#SEC76"><CODE>.equiv <VAR>symbol</VAR>, <VAR>expression</VAR></CODE></A>
|
|
<LI><A NAME="TOC77" HREF="#SEC77"><CODE>.err</CODE></A>
|
|
<LI><A NAME="TOC78" HREF="#SEC78"><CODE>.extern</CODE></A>
|
|
<LI><A NAME="TOC79" HREF="#SEC79"><CODE>.file <VAR>string</VAR></CODE></A>
|
|
<LI><A NAME="TOC80" HREF="#SEC80"><CODE>.fill <VAR>repeat</VAR> , <VAR>size</VAR> , <VAR>value</VAR></CODE></A>
|
|
<LI><A NAME="TOC81" HREF="#SEC81"><CODE>.float <VAR>flonums</VAR></CODE></A>
|
|
<LI><A NAME="TOC82" HREF="#SEC82"><CODE>.global <VAR>symbol</VAR></CODE>, <CODE>.globl <VAR>symbol</VAR></CODE></A>
|
|
<LI><A NAME="TOC83" HREF="#SEC83"><CODE>.hword <VAR>expressions</VAR></CODE></A>
|
|
<LI><A NAME="TOC84" HREF="#SEC84"><CODE>.ident</CODE></A>
|
|
<LI><A NAME="TOC85" HREF="#SEC85"><CODE>.if <VAR>absolute expression</VAR></CODE></A>
|
|
<LI><A NAME="TOC86" HREF="#SEC86"><CODE>.include "<VAR>file</VAR>"</CODE></A>
|
|
<LI><A NAME="TOC87" HREF="#SEC87"><CODE>.int <VAR>expressions</VAR></CODE></A>
|
|
<LI><A NAME="TOC88" HREF="#SEC88"><CODE>.irp <VAR>symbol</VAR>,<VAR>values</VAR></CODE>...</A>
|
|
<LI><A NAME="TOC89" HREF="#SEC89"><CODE>.irpc <VAR>symbol</VAR>,<VAR>values</VAR></CODE>...</A>
|
|
<LI><A NAME="TOC90" HREF="#SEC90"><CODE>.lcomm <VAR>symbol</VAR> , <VAR>length</VAR></CODE></A>
|
|
<LI><A NAME="TOC91" HREF="#SEC91"><CODE>.lflags</CODE></A>
|
|
<LI><A NAME="TOC92" HREF="#SEC92"><CODE>.line <VAR>line-number</VAR></CODE></A>
|
|
<LI><A NAME="TOC93" HREF="#SEC93"><CODE>.linkonce [<VAR>type</VAR>]</CODE></A>
|
|
<LI><A NAME="TOC94" HREF="#SEC94"><CODE>.ln <VAR>line-number</VAR></CODE></A>
|
|
<LI><A NAME="TOC95" HREF="#SEC95"><CODE>.mri <VAR>val</VAR></CODE></A>
|
|
<LI><A NAME="TOC96" HREF="#SEC96"><CODE>.list</CODE></A>
|
|
<LI><A NAME="TOC97" HREF="#SEC97"><CODE>.long <VAR>expressions</VAR></CODE></A>
|
|
<LI><A NAME="TOC98" HREF="#SEC98"><CODE>.macro</CODE></A>
|
|
<LI><A NAME="TOC99" HREF="#SEC99"><CODE>.nolist</CODE></A>
|
|
<LI><A NAME="TOC100" HREF="#SEC100"><CODE>.octa <VAR>bignums</VAR></CODE></A>
|
|
<LI><A NAME="TOC101" HREF="#SEC101"><CODE>.org <VAR>new-lc</VAR> , <VAR>fill</VAR></CODE></A>
|
|
<LI><A NAME="TOC102" HREF="#SEC102"><CODE>.p2align[wl] <VAR>abs-expr</VAR>, <VAR>abs-expr</VAR>, <VAR>abs-expr</VAR></CODE></A>
|
|
<LI><A NAME="TOC103" HREF="#SEC103"><CODE>.psize <VAR>lines</VAR> , <VAR>columns</VAR></CODE></A>
|
|
<LI><A NAME="TOC104" HREF="#SEC104"><CODE>.quad <VAR>bignums</VAR></CODE></A>
|
|
<LI><A NAME="TOC105" HREF="#SEC105"><CODE>.rept <VAR>count</VAR></CODE></A>
|
|
<LI><A NAME="TOC106" HREF="#SEC106"><CODE>.sbttl "<VAR>subheading</VAR>"</CODE></A>
|
|
<LI><A NAME="TOC107" HREF="#SEC107"><CODE>.section <VAR>name</VAR></CODE></A>
|
|
<LI><A NAME="TOC108" HREF="#SEC108"><CODE>.set <VAR>symbol</VAR>, <VAR>expression</VAR></CODE></A>
|
|
<LI><A NAME="TOC109" HREF="#SEC109"><CODE>.short <VAR>expressions</VAR></CODE></A>
|
|
<LI><A NAME="TOC110" HREF="#SEC110"><CODE>.single <VAR>flonums</VAR></CODE></A>
|
|
<LI><A NAME="TOC111" HREF="#SEC111"><CODE>.skip <VAR>size</VAR> , <VAR>fill</VAR></CODE></A>
|
|
<LI><A NAME="TOC112" HREF="#SEC112"><CODE>.space <VAR>size</VAR> , <VAR>fill</VAR></CODE></A>
|
|
<LI><A NAME="TOC113" HREF="#SEC113"><CODE>.stabd, .stabn, .stabs</CODE></A>
|
|
<LI><A NAME="TOC114" HREF="#SEC114"><CODE>.string</CODE> "<VAR>str</VAR>"</A>
|
|
<LI><A NAME="TOC115" HREF="#SEC115"><CODE>.text <VAR>subsection</VAR></CODE></A>
|
|
<LI><A NAME="TOC116" HREF="#SEC116"><CODE>.title "<VAR>heading</VAR>"</CODE></A>
|
|
<LI><A NAME="TOC117" HREF="#SEC117"><CODE>.word <VAR>expressions</VAR></CODE></A>
|
|
<LI><A NAME="TOC118" HREF="#SEC118">Deprecated Directives</A>
|
|
</UL>
|
|
<LI><A NAME="TOC119" HREF="#SEC119">Reporting Bugs</A>
|
|
<UL>
|
|
<LI><A NAME="TOC120" HREF="#SEC120">Have you found a bug?</A>
|
|
<LI><A NAME="TOC121" HREF="#SEC121">How to report bugs</A>
|
|
</UL>
|
|
<LI><A NAME="TOC122" HREF="#SEC122">Acknowledgements</A>
|
|
<LI><A NAME="TOC123" HREF="#SEC123">Index</A>
|
|
</UL>
|
|
<P><HR><P>
|
|
|
|
<P>
|
|
The Free Software Foundation Inc. thanks The Nice Computer
|
|
Company of Australia for loaning Dean Elsner to write the
|
|
first (Vax) version of <CODE>as</CODE> for Project GNU.
|
|
The proprietors, management and staff of TNCCA thank FSF for
|
|
distracting the boss while they got some work
|
|
done.
|
|
<P>
|
|
|
|
</P>
|
|
<P>
|
|
Copyright (C) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
|
|
|
|
</P>
|
|
<P>
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
</P>
|
|
<P>
|
|
Permission is granted to copy and distribute modified versions of this manual
|
|
under the conditions for verbatim copying, provided that the entire resulting
|
|
derived work is distributed under the terms of a permission notice identical to
|
|
this one.
|
|
|
|
</P>
|
|
<P>
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H1><A NAME="SEC1" HREF="#TOC1">Overview</A></H1>
|
|
<P>
|
|
This manual is a user guide to the GNU assembler <CODE></CODE>.
|
|
This version of the manual describes <CODE></CODE> configured to generate
|
|
code for architectures.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX1"></A>
|
|
<A NAME="IDX2"></A>
|
|
<A NAME="IDX3"></A>
|
|
Here is a brief summary of how to invoke <CODE></CODE>. For details,
|
|
see section <A HREF="#SEC9">Command-Line Options</A>.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
[ -a[cdhlns][=file] ] [ -D ] [ --defsym <VAR>sym</VAR>=<VAR>val</VAR> ]
|
|
[ -f ] [ --help ] [ -I <VAR>dir</VAR> ] [ -J ] [ -K ] [ -L ]
|
|
[ -o <VAR>objfile</VAR> ] [ -R ] [ --statistics ] [ -v ] [ -version ]
|
|
[ --version ] [ -W ] [ -w ] [ -x ] [ -Z ]
|
|
|
|
[ -- | <VAR>files</VAR> ... ]
|
|
</PRE>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>-a[dhlns]</CODE>
|
|
<DD>
|
|
Turn on listings, in any of a variety of ways:
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>-ad</CODE>
|
|
<DD>
|
|
omit debugging directives
|
|
|
|
<DT><CODE>-ah</CODE>
|
|
<DD>
|
|
include high-level source
|
|
|
|
<DT><CODE>-al</CODE>
|
|
<DD>
|
|
include assembly
|
|
|
|
<DT><CODE>-an</CODE>
|
|
<DD>
|
|
omit forms processing
|
|
|
|
<DT><CODE>-as</CODE>
|
|
<DD>
|
|
include symbols
|
|
|
|
<DT><CODE>=file</CODE>
|
|
<DD>
|
|
set the name of the listing file
|
|
</DL>
|
|
|
|
You may combine these options; for example, use <SAMP>`-aln'</SAMP> for assembly
|
|
listing without forms processing. The <SAMP>`=file'</SAMP> option, if used, must be
|
|
the last one. By itself, <SAMP>`-a'</SAMP> defaults to <SAMP>`-ahls'</SAMP>---that is, all
|
|
listings turned on.
|
|
|
|
<DT><CODE>-D</CODE>
|
|
<DD>
|
|
Ignored. This option is accepted for script compatibility with calls to
|
|
other assemblers.
|
|
|
|
<DT><CODE>--defsym <VAR>sym</VAR>=<VAR>value</VAR></CODE>
|
|
<DD>
|
|
Define the symbol <VAR>sym</VAR> to be <VAR>value</VAR> before assembling the input file.
|
|
<VAR>value</VAR> must be an integer constant. As in C, a leading <SAMP>`0x'</SAMP>
|
|
indicates a hexadecimal value, and a leading <SAMP>`0'</SAMP> indicates an octal value.
|
|
|
|
<DT><CODE>-f</CODE>
|
|
<DD>
|
|
"fast"---skip whitespace and comment preprocessing (assume source is
|
|
compiler output).
|
|
|
|
<DT><CODE>--help</CODE>
|
|
<DD>
|
|
Print a summary of the command line options and exit.
|
|
|
|
<DT><CODE>-I <VAR>dir</VAR></CODE>
|
|
<DD>
|
|
Add directory <VAR>dir</VAR> to the search list for <CODE>.include</CODE> directives.
|
|
|
|
<DT><CODE>-J</CODE>
|
|
<DD>
|
|
Don't warn about signed overflow.
|
|
|
|
<DT><CODE>-K</CODE>
|
|
<DD>
|
|
This option is accepted but has no effect on the family.
|
|
|
|
<DT><CODE>-L</CODE>
|
|
<DD>
|
|
Keep (in the symbol table) local symbols, starting with <SAMP>`L'</SAMP>.
|
|
|
|
<DT><CODE>-o <VAR>objfile</VAR></CODE>
|
|
<DD>
|
|
Name the object-file output from <CODE></CODE> <VAR>objfile</VAR>.
|
|
|
|
<DT><CODE>-R</CODE>
|
|
<DD>
|
|
Fold the data section into the text section.
|
|
|
|
<DT><CODE>--statistics</CODE>
|
|
<DD>
|
|
Print the maximum space (in bytes) and total time (in seconds) used by
|
|
assembly.
|
|
|
|
<DT><CODE>-v</CODE>
|
|
<DD>
|
|
<DT><CODE>-version</CODE>
|
|
<DD>
|
|
Print the <CODE>as</CODE> version.
|
|
|
|
<DT><CODE>--version</CODE>
|
|
<DD>
|
|
Print the <CODE>as</CODE> version and exit.
|
|
|
|
<DT><CODE>-W</CODE>
|
|
<DD>
|
|
Suppress warning messages.
|
|
|
|
<DT><CODE>-w</CODE>
|
|
<DD>
|
|
Ignored.
|
|
|
|
<DT><CODE>-x</CODE>
|
|
<DD>
|
|
Ignored.
|
|
|
|
<DT><CODE>-Z</CODE>
|
|
<DD>
|
|
Generate an object file even after errors.
|
|
|
|
<DT><CODE>-- | <VAR>files</VAR> ...</CODE>
|
|
<DD>
|
|
Standard input, or source files to assemble.
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC2" HREF="#TOC2">Structure of this Manual</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX4"></A>
|
|
This manual is intended to describe what you need to know to use
|
|
GNU <CODE></CODE>. We cover the syntax expected in source files, including
|
|
notation for symbols, constants, and expressions; the directives that
|
|
<CODE></CODE> understands; and of course how to invoke <CODE></CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
We also cover special features in the
|
|
configuration of <CODE></CODE>, including assembler directives.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX5"></A>
|
|
On the other hand, this manual is <EM>not</EM> intended as an introduction
|
|
to programming in assembly language--let alone programming in general!
|
|
In a similar vein, we make no attempt to introduce the machine
|
|
architecture; we do <EM>not</EM> describe the instruction set, standard
|
|
mnemonics, registers or addressing modes that are standard to a
|
|
particular architecture.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC3" HREF="#TOC3">The GNU Assembler</A></H2>
|
|
|
|
<P>
|
|
GNU <CODE>as</CODE> is really a family of assemblers.
|
|
This manual describes <CODE></CODE>, a member of that family which is
|
|
configured for the architectures.
|
|
If you use (or have used) the GNU assembler on one architecture, you
|
|
should find a fairly similar environment when you use it on another
|
|
architecture. Each version has much in common with the others,
|
|
including object file formats, most assembler directives (often called
|
|
<STRONG>pseudo-ops</STRONG>) and assembler syntax.
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX6"></A>
|
|
<CODE></CODE> is primarily intended to assemble the output of the
|
|
GNU C compiler <CODE></CODE> for use by the linker
|
|
<CODE></CODE>. Nevertheless, we've tried to make <CODE></CODE>
|
|
assemble correctly everything that other assemblers for the same
|
|
machine would assemble.
|
|
|
|
</P>
|
|
<P>
|
|
Unlike older assemblers, <CODE></CODE> is designed to assemble a source
|
|
program in one pass of the source file. This has a subtle impact on the
|
|
<KBD>.org</KBD> directive (see section <A HREF="#SEC101"><CODE>.org <VAR>new-lc</CODE> , <VAR>fill</VAR></VAR></A>).
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC4" HREF="#TOC4">Object File Formats</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX7"></A>
|
|
The GNU assembler can be configured to produce several alternative
|
|
object file formats. For the most part, this does not affect how you
|
|
write assembly language programs; but directives for debugging symbols
|
|
are typically different in different file formats. See section <A HREF="#SEC48">Symbol Attributes</A>.
|
|
On the , <CODE></CODE> is configured to produce
|
|
format object files.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC5" HREF="#TOC5">Command Line</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX8"></A>
|
|
After the program name <CODE></CODE>, the command line may contain
|
|
options and file names. Options may appear in any order, and may be
|
|
before, after, or between file names. The order of file names is
|
|
significant.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX9"></A>
|
|
<A NAME="IDX10"></A>
|
|
<TT>`--'</TT> (two hyphens) by itself names the standard input file
|
|
explicitly, as one of the files for <CODE></CODE> to assemble.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX11"></A>
|
|
Except for <SAMP>`--'</SAMP> any command line argument that begins with a
|
|
hyphen (<SAMP>`-'</SAMP>) is an option. Each option changes the behavior of
|
|
<CODE></CODE>. No option changes the way another option works. An
|
|
option is a <SAMP>`-'</SAMP> followed by one or more letters; the case of
|
|
the letter is important. All options are optional.
|
|
|
|
</P>
|
|
<P>
|
|
Some options expect exactly one file name to follow them. The file
|
|
name may either immediately follow the option's letter (compatible
|
|
with older assemblers) or it may be the next command argument (GNU
|
|
standard). These two command lines are equivalent:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
-o my-object-file.o mumble.s
|
|
-omy-object-file.o mumble.s
|
|
</PRE>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC6" HREF="#TOC6">Input Files</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX12"></A>
|
|
<A NAME="IDX13"></A>
|
|
<A NAME="IDX14"></A>
|
|
We use the phrase <STRONG>source program</STRONG>, abbreviated <STRONG>source</STRONG>, to
|
|
describe the program input to one run of <CODE></CODE>. The program may
|
|
be in one or more files; how the source is partitioned into files
|
|
doesn't change the meaning of the source.
|
|
|
|
</P>
|
|
<P>
|
|
The source program is a concatenation of the text in all the files, in the
|
|
order specified.
|
|
|
|
</P>
|
|
<P>
|
|
Each time you run <CODE></CODE> it assembles exactly one source
|
|
program. The source program is made up of one or more files.
|
|
(The standard input is also a file.)
|
|
|
|
</P>
|
|
<P>
|
|
You give <CODE></CODE> a command line that has zero or more input file
|
|
names. The input files are read (from left file name to right). A
|
|
command line argument (in any position) that has no special meaning
|
|
is taken to be an input file name.
|
|
|
|
</P>
|
|
<P>
|
|
If you give <CODE></CODE> no file names it attempts to read one input file
|
|
from the <CODE></CODE> standard input, which is normally your terminal. You
|
|
may have to type <KBD>ctl-D</KBD> to tell <CODE></CODE> there is no more program
|
|
to assemble.
|
|
|
|
</P>
|
|
<P>
|
|
Use <SAMP>`--'</SAMP> if you need to explicitly name the standard input file
|
|
in your command line.
|
|
|
|
</P>
|
|
<P>
|
|
If the source is empty, <CODE></CODE> produces a small, empty object
|
|
file.
|
|
|
|
</P>
|
|
|
|
<H3>Filenames and Line-numbers</H3>
|
|
|
|
<P>
|
|
<A NAME="IDX15"></A>
|
|
<A NAME="IDX16"></A>
|
|
There are two ways of locating a line in the input file (or files) and
|
|
either may be used in reporting error messages. One way refers to a line
|
|
number in a physical file; the other refers to a line number in a
|
|
"logical" file. See section <A HREF="#SEC8">Error and Warning Messages</A>.
|
|
|
|
</P>
|
|
<P>
|
|
<STRONG>Physical files</STRONG> are those files named in the command line given
|
|
to <CODE></CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
<STRONG>Logical files</STRONG> are simply names declared explicitly by assembler
|
|
directives; they bear no relation to physical files. Logical file names
|
|
help error messages reflect the original source file, when <CODE></CODE>
|
|
source is itself synthesized from other files.
|
|
See section <A HREF="#SEC64"><CODE>.app-file <VAR>string</CODE></VAR></A>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC7" HREF="#TOC7">Output (Object) File</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX17"></A>
|
|
<A NAME="IDX18"></A>
|
|
<A NAME="IDX19"></A>
|
|
<A NAME="IDX20"></A>
|
|
Every time you run <CODE></CODE> it produces an output file, which is
|
|
your assembly language program translated into numbers. This file
|
|
is the object file. Its default name is
|
|
<CODE>a.out</CODE>.
|
|
<CODE>b.out</CODE> when <CODE></CODE> is configured for the Intel 80960.
|
|
You can give it another name by using the <CODE>-o</CODE> option. Conventionally,
|
|
object file names end with <TT>`.o'</TT>. The default name is used for historical
|
|
reasons: older assemblers were capable of assembling self-contained programs
|
|
directly into a runnable program. (For some formats, this isn't currently
|
|
possible, but it can be done for the <CODE>a.out</CODE> format.)
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX21"></A>
|
|
<A NAME="IDX22"></A>
|
|
The object file is meant for input to the linker <CODE></CODE>. It contains
|
|
assembled program code, information to help <CODE></CODE> integrate
|
|
the assembled program into a runnable file, and (optionally) symbolic
|
|
information for the debugger.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC8" HREF="#TOC8">Error and Warning Messages</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX23"></A>
|
|
<A NAME="IDX24"></A>
|
|
<A NAME="IDX25"></A>
|
|
<CODE></CODE> may write warnings and error messages to the standard error
|
|
file (usually your terminal). This should not happen when a compiler
|
|
runs <CODE></CODE> automatically. Warnings report an assumption made so
|
|
that <CODE></CODE> could keep assembling a flawed program; errors report a
|
|
grave problem that stops the assembly.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX26"></A>
|
|
Warning messages have the format
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
file_name:<B>NNN</B>:Warning Message Text
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX27"></A>
|
|
(where <B>NNN</B> is a line number). If a logical file name has been given
|
|
(see section <A HREF="#SEC64"><CODE>.app-file <VAR>string</CODE></VAR></A>) it is used for the filename,
|
|
otherwise the name of the current input file is used. If a logical line
|
|
number was given
|
|
(see section <A HREF="#SEC92"><CODE>.line <VAR>line-number</CODE></VAR></A>)
|
|
then it is used to calculate the number printed,
|
|
otherwise the actual line in the current source file is printed. The
|
|
message text is intended to be self explanatory (in the grand Unix
|
|
tradition).
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX28"></A>
|
|
Error messages have the format
|
|
|
|
<PRE>
|
|
file_name:<B>NNN</B>:FATAL:Error Message Text
|
|
</PRE>
|
|
|
|
<P>
|
|
The file name and line number are derived as for warning
|
|
messages. The actual message text may be rather less explanatory
|
|
because many of them aren't supposed to happen.
|
|
|
|
</P>
|
|
|
|
|
|
<H1><A NAME="SEC9" HREF="#TOC9">Command-Line Options</A></H1>
|
|
|
|
<P>
|
|
<A NAME="IDX29"></A>
|
|
This chapter describes command-line options available in <EM>all</EM>
|
|
versions of the GNU assembler; @xref{Machine Dependencies}, for options specific
|
|
to the .
|
|
|
|
</P>
|
|
<P>
|
|
If you are invoking <CODE></CODE> via the GNU C compiler (version 2), you
|
|
can use the <SAMP>`-Wa'</SAMP> option to pass arguments through to the
|
|
assembler. The assembler arguments must be separated from each other
|
|
(and the <SAMP>`-Wa'</SAMP>) by commas. For example:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
gcc -c -g -O -Wa,-alh,-L file.c
|
|
</PRE>
|
|
|
|
<P>
|
|
emits a listing to standard output with high-level
|
|
and assembly source.
|
|
|
|
</P>
|
|
<P>
|
|
Usually you do not need to use this <SAMP>`-Wa'</SAMP> mechanism, since many compiler
|
|
command-line options are automatically passed to the assembler by the compiler.
|
|
(You can call the GNU compiler driver with the <SAMP>`-v'</SAMP> option to see
|
|
precisely what options it passes to each compilation pass, including the
|
|
assembler.)
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC10" HREF="#TOC10">Enable Listings: <CODE>-a[cdhlns]</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX30"></A>
|
|
<A NAME="IDX31"></A>
|
|
<A NAME="IDX32"></A>
|
|
<A NAME="IDX33"></A>
|
|
<A NAME="IDX34"></A>
|
|
<A NAME="IDX35"></A>
|
|
<A NAME="IDX36"></A>
|
|
<A NAME="IDX37"></A>
|
|
<A NAME="IDX38"></A>
|
|
|
|
</P>
|
|
<P>
|
|
These options enable listing output from the assembler. By itself,
|
|
<SAMP>`-a'</SAMP> requests high-level, assembly, and symbols listing.
|
|
You can use other letters to select specific options for the list:
|
|
<SAMP>`-ah'</SAMP> requests a high-level language listing,
|
|
<SAMP>`-al'</SAMP> requests an output-program assembly listing, and
|
|
<SAMP>`-as'</SAMP> requests a symbol table listing.
|
|
High-level listings require that a compiler debugging option like
|
|
<SAMP>`-g'</SAMP> be used, and that assembly listings (<SAMP>`-al'</SAMP>) be requested
|
|
also.
|
|
|
|
</P>
|
|
<P>
|
|
Use the <SAMP>`-ac'</SAMP> option to omit false conditionals from a listing. Any lines
|
|
which are not assembled because of a false <CODE>.if</CODE> (or <CODE>.ifdef</CODE>, or any
|
|
other conditional), or a true <CODE>.if</CODE> followed by an <CODE>.else</CODE>, will be
|
|
omitted from the listing.
|
|
|
|
</P>
|
|
<P>
|
|
Use the <SAMP>`-ad'</SAMP> option to omit debugging directives from the
|
|
listing.
|
|
|
|
</P>
|
|
<P>
|
|
Once you have specified one of these options, you can further control
|
|
listing output and its appearance using the directives <CODE>.list</CODE>,
|
|
<CODE>.nolist</CODE>, <CODE>.psize</CODE>, <CODE>.eject</CODE>, <CODE>.title</CODE>, and
|
|
<CODE>.sbttl</CODE>.
|
|
The <SAMP>`-an'</SAMP> option turns off all forms processing.
|
|
If you do not request listing output with one of the <SAMP>`-a'</SAMP> options, the
|
|
listing-control directives have no effect.
|
|
|
|
</P>
|
|
<P>
|
|
The letters after <SAMP>`-a'</SAMP> may be combined into one option,
|
|
<EM>e.g.</EM>, <SAMP>`-aln'</SAMP>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC11" HREF="#TOC11"><CODE>-D</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX39"></A>
|
|
This option has no effect whatsoever, but it is accepted to make it more
|
|
likely that scripts written for other assemblers also work with
|
|
<CODE></CODE>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC12" HREF="#TOC12">Work Faster: <CODE>-f</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX40"></A>
|
|
<A NAME="IDX41"></A>
|
|
<A NAME="IDX42"></A>
|
|
<SAMP>`-f'</SAMP> should only be used when assembling programs written by a
|
|
(trusted) compiler. <SAMP>`-f'</SAMP> stops the assembler from doing whitespace
|
|
and comment preprocessing on
|
|
the input file(s) before assembling them. See section <A HREF="#SEC24">Preprocessing</A>.
|
|
|
|
</P>
|
|
|
|
<BLOCKQUOTE>
|
|
<P>
|
|
<EM>Warning:</EM> if you use <SAMP>`-f'</SAMP> when the files actually need to be
|
|
preprocessed (if they contain comments, for example), <CODE></CODE> does
|
|
not work correctly.
|
|
</BLOCKQUOTE>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC13" HREF="#TOC13"><CODE>.include</CODE> search path: <CODE>-I</CODE> <VAR>path</VAR></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX43"></A>
|
|
<A NAME="IDX44"></A>
|
|
<A NAME="IDX45"></A>
|
|
<A NAME="IDX46"></A>
|
|
Use this option to add a <VAR>path</VAR> to the list of directories
|
|
<CODE></CODE> searches for files specified in <CODE>.include</CODE>
|
|
directives (see section <A HREF="#SEC86"><CODE>.include "<VAR>file</CODE>"</VAR></A>). You may use <CODE>-I</CODE> as
|
|
many times as necessary to include a variety of paths. The current
|
|
working directory is always searched first; after that, <CODE></CODE>
|
|
searches any <SAMP>`-I'</SAMP> directories in the same order as they were
|
|
specified (left to right) on the command line.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC14" HREF="#TOC14">Difference Tables: <CODE>-K</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX47"></A>
|
|
On the family, this option is allowed, but has no effect. It is
|
|
permitted for compatibility with the GNU assembler on other platforms,
|
|
where it can be used to warn when the assembler alters the machine code
|
|
generated for <SAMP>`.word'</SAMP> directives in difference tables. The
|
|
family does not have the addressing limitations that sometimes lead to this
|
|
alteration on other platforms.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC15" HREF="#TOC15">Include Local Labels: <CODE>-L</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX48"></A>
|
|
<A NAME="IDX49"></A>
|
|
Labels beginning with <SAMP>`L'</SAMP> (upper case only) are called <STRONG>local
|
|
labels</STRONG>. See section <A HREF="#SEC46">Symbol Names</A>. Normally you do not see such labels when
|
|
debugging, because they are intended for the use of programs (like
|
|
compilers) that compose assembler programs, not for your notice.
|
|
Normally both <CODE></CODE> and <CODE></CODE> discard such labels, so you do not
|
|
normally debug with them.
|
|
|
|
</P>
|
|
<P>
|
|
This option tells <CODE></CODE> to retain those <SAMP>`L...'</SAMP> symbols
|
|
in the object file. Usually if you do this you also tell the linker
|
|
<CODE></CODE> to preserve symbols whose names begin with <SAMP>`L'</SAMP>.
|
|
|
|
</P>
|
|
<P>
|
|
By default, a local label is any label beginning with <SAMP>`L'</SAMP>, but each
|
|
target is allowed to redefine the local label prefix.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC16" HREF="#TOC16">Assemble in MRI Compatibility Mode: <CODE>-M</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX50"></A>
|
|
<A NAME="IDX51"></A>
|
|
The <CODE>-M</CODE> or <CODE>--mri</CODE> option selects MRI compatibility mode. This
|
|
changes the syntax and pseudo-op handling of <CODE></CODE> to make it
|
|
compatible with the <CODE>ASM68K</CODE> or the <CODE>ASM960</CODE> (depending upon the
|
|
configured target) assembler from Microtec Research. The exact nature of the
|
|
MRI syntax will not be documented here; see the MRI manuals for more
|
|
information. Note in particular that the handling of macros and macro
|
|
arguments is somewhat different. The purpose of this option is to permit
|
|
assembling existing MRI assembler code using <CODE></CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
The MRI compatibility is not complete. Certain operations of the MRI assembler
|
|
depend upon its object file format, and can not be supported using other object
|
|
file formats. Supporting these would require enhancing each object file format
|
|
individually. These are:
|
|
|
|
</P>
|
|
|
|
<UL>
|
|
<LI>global symbols in common section
|
|
|
|
The m68k MRI assembler supports common sections which are merged by the linker.
|
|
Other object file formats do not support this. <CODE></CODE> handles
|
|
common sections by treating them as a single common symbol. It permits local
|
|
symbols to be defined within a common section, but it can not support global
|
|
symbols, since it has no way to describe them.
|
|
|
|
<LI>complex relocations
|
|
|
|
The MRI assemblers support relocations against a negated section address, and
|
|
relocations which combine the start addresses of two or more sections. These
|
|
are not support by other object file formats.
|
|
|
|
<LI><CODE>END</CODE> pseudo-op specifying start address
|
|
|
|
The MRI <CODE>END</CODE> pseudo-op permits the specification of a start address.
|
|
This is not supported by other object file formats. The start address may
|
|
instead be specified using the <CODE>-e</CODE> option to the linker, or in a linker
|
|
script.
|
|
|
|
<LI><CODE>IDNT</CODE>, <CODE>.ident</CODE> and <CODE>NAME</CODE> pseudo-ops
|
|
|
|
The MRI <CODE>IDNT</CODE>, <CODE>.ident</CODE> and <CODE>NAME</CODE> pseudo-ops assign a module
|
|
name to the output file. This is not supported by other object file formats.
|
|
|
|
<LI><CODE>ORG</CODE> pseudo-op
|
|
|
|
The m68k MRI <CODE>ORG</CODE> pseudo-op begins an absolute section at a given
|
|
address. This differs from the usual <CODE></CODE> <CODE>.org</CODE> pseudo-op,
|
|
which changes the location within the current section. Absolute sections are
|
|
not supported by other object file formats. The address of a section may be
|
|
assigned within a linker script.
|
|
</UL>
|
|
|
|
<P>
|
|
There are some other features of the MRI assembler which are not supported by
|
|
<CODE></CODE>, typically either because they are difficult or because they
|
|
seem of little consequence. Some of these may be supported in future releases.
|
|
|
|
</P>
|
|
|
|
<UL>
|
|
|
|
<LI>EBCDIC strings
|
|
|
|
EBCDIC strings are not supported.
|
|
|
|
<LI>packed binary coded decimal
|
|
|
|
Packed binary coded decimal is not supported. This means that the <CODE>DC.P</CODE>
|
|
and <CODE>DCB.P</CODE> pseudo-ops are not supported.
|
|
|
|
<LI><CODE>FEQU</CODE> pseudo-op
|
|
|
|
The m68k <CODE>FEQU</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>NOOBJ</CODE> pseudo-op
|
|
|
|
The m68k <CODE>NOOBJ</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>OPT</CODE> branch control options
|
|
|
|
The m68k <CODE>OPT</CODE> branch control options---<CODE>B</CODE>, <CODE>BRS</CODE>, <CODE>BRB</CODE>,
|
|
<CODE>BRL</CODE>, and <CODE>BRW</CODE>---are ignored. <CODE></CODE> automatically
|
|
relaxes all branches, whether forward or backward, to an appropriate size, so
|
|
these options serve no purpose.
|
|
|
|
<LI><CODE>OPT</CODE> list control options
|
|
|
|
The following m68k <CODE>OPT</CODE> list control options are ignored: <CODE>C</CODE>,
|
|
<CODE>CEX</CODE>, <CODE>CL</CODE>, <CODE>CRE</CODE>, <CODE>E</CODE>, <CODE>G</CODE>, <CODE>I</CODE>, <CODE>M</CODE>,
|
|
<CODE>MEX</CODE>, <CODE>MC</CODE>, <CODE>MD</CODE>, <CODE>X</CODE>.
|
|
|
|
<LI>other <CODE>OPT</CODE> options
|
|
|
|
The following m68k <CODE>OPT</CODE> options are ignored: <CODE>NEST</CODE>, <CODE>O</CODE>,
|
|
<CODE>OLD</CODE>, <CODE>OP</CODE>, <CODE>P</CODE>, <CODE>PCO</CODE>, <CODE>PCR</CODE>, <CODE>PCS</CODE>, <CODE>R</CODE>.
|
|
|
|
<LI><CODE>OPT</CODE> <CODE>D</CODE> option is default
|
|
|
|
The m68k <CODE>OPT</CODE> <CODE>D</CODE> option is the default, unlike the MRI assembler.
|
|
<CODE>OPT NOD</CODE> may be used to turn it off.
|
|
|
|
<LI><CODE>XREF</CODE> pseudo-op.
|
|
|
|
The m68k <CODE>XREF</CODE> pseudo-op is ignored.
|
|
|
|
<LI><CODE>.debug</CODE> pseudo-op
|
|
|
|
The i960 <CODE>.debug</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>.extended</CODE> pseudo-op
|
|
|
|
The i960 <CODE>.extended</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>.list</CODE> pseudo-op.
|
|
|
|
The various options of the i960 <CODE>.list</CODE> pseudo-op are not supported.
|
|
|
|
<LI><CODE>.optimize</CODE> pseudo-op
|
|
|
|
The i960 <CODE>.optimize</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>.output</CODE> pseudo-op
|
|
|
|
The i960 <CODE>.output</CODE> pseudo-op is not supported.
|
|
|
|
<LI><CODE>.setreal</CODE> pseudo-op
|
|
|
|
The i960 <CODE>.setreal</CODE> pseudo-op is not supported.
|
|
|
|
</UL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC17" HREF="#TOC17">Name the Object File: <CODE>-o</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX52"></A>
|
|
<A NAME="IDX53"></A>
|
|
<A NAME="IDX54"></A>
|
|
There is always one object file output when you run <CODE></CODE>. By
|
|
default it has the name
|
|
<TT>`a.out'</TT>.
|
|
<TT>`a.out'</TT>.
|
|
You use this option (which takes exactly one filename) to give the
|
|
object file a different name.
|
|
|
|
</P>
|
|
<P>
|
|
Whatever the object file is called, <CODE></CODE> overwrites any
|
|
existing file of the same name.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC18" HREF="#TOC18">Join Data and Text Sections: <CODE>-R</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX55"></A>
|
|
<A NAME="IDX56"></A>
|
|
<A NAME="IDX57"></A>
|
|
<A NAME="IDX58"></A>
|
|
<A NAME="IDX59"></A>
|
|
<CODE>-R</CODE> tells <CODE></CODE> to write the object file as if all
|
|
data-section data lives in the text section. This is only done at
|
|
the very last moment: your binary data are the same, but data
|
|
section parts are relocated differently. The data section part of
|
|
your object file is zero bytes long because all its bytes are
|
|
appended to the text section. (See section <A HREF="#SEC37">Sections and Relocation</A>.)
|
|
|
|
</P>
|
|
<P>
|
|
When you specify <CODE>-R</CODE> it would be possible to generate shorter
|
|
address displacements (because we do not have to cross between text and
|
|
data section). We refrain from doing this simply for compatibility with
|
|
older versions of <CODE></CODE>. In future, <CODE>-R</CODE> may work this way.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC19" HREF="#TOC19">Display Assembly Statistics: <CODE>--statistics</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX60"></A>
|
|
<A NAME="IDX61"></A>
|
|
<A NAME="IDX62"></A>
|
|
<A NAME="IDX63"></A>
|
|
Use <SAMP>`--statistics'</SAMP> to display two statistics about the resources used by
|
|
<CODE></CODE>: the maximum amount of space allocated during the assembly
|
|
(in bytes), and the total execution time taken for the assembly (in CPU
|
|
seconds).
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC20" HREF="#TOC20">Announce Version: <CODE>-v</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX64"></A>
|
|
<A NAME="IDX65"></A>
|
|
<A NAME="IDX66"></A>
|
|
<A NAME="IDX67"></A>
|
|
You can find out what version of as is running by including the
|
|
option <SAMP>`-v'</SAMP> (which you can also spell as <SAMP>`-version'</SAMP>) on the
|
|
command line.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC21" HREF="#TOC21">Suppress Warnings: <CODE>-W</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX68"></A>
|
|
<A NAME="IDX69"></A>
|
|
<A NAME="IDX70"></A>
|
|
<CODE></CODE> should never give a warning or error message when
|
|
assembling compiler output. But programs written by people often
|
|
cause <CODE></CODE> to give a warning that a particular assumption was
|
|
made. All such warnings are directed to the standard error file.
|
|
If you use this option, no warnings are issued. This option only
|
|
affects the warning messages: it does not change any particular of how
|
|
<CODE></CODE> assembles your file. Errors, which stop the assembly, are
|
|
still reported.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC22" HREF="#TOC22">Generate Object File in Spite of Errors: <CODE>-Z</CODE></A></H2>
|
|
<P>
|
|
<A NAME="IDX71"></A>
|
|
<A NAME="IDX72"></A>
|
|
After an error message, <CODE></CODE> normally produces no output. If for
|
|
some reason you are interested in object file output even after
|
|
<CODE></CODE> gives an error message on your program, use the <SAMP>`-Z'</SAMP>
|
|
option. If there are any errors, <CODE></CODE> continues anyways, and
|
|
writes an object file after a final warning message of the form <SAMP>`<VAR>n</VAR>
|
|
errors, <VAR>m</VAR> warnings, generating bad object file.'</SAMP>
|
|
|
|
</P>
|
|
|
|
|
|
<H1><A NAME="SEC23" HREF="#TOC23">Syntax</A></H1>
|
|
|
|
<P>
|
|
<A NAME="IDX73"></A>
|
|
<A NAME="IDX74"></A>
|
|
This chapter describes the machine-independent syntax allowed in a
|
|
source file. <CODE></CODE> syntax is similar to what many other
|
|
assemblers use; it is inspired by the BSD 4.2
|
|
assembler.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC24" HREF="#TOC24">Preprocessing</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX75"></A>
|
|
The <CODE></CODE> internal preprocessor:
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
<A NAME="IDX76"></A>
|
|
|
|
adjusts and removes extra whitespace. It leaves one space or tab before
|
|
the keywords on a line, and turns any other whitespace on the line into
|
|
a single space.
|
|
|
|
<A NAME="IDX77"></A>
|
|
<LI>
|
|
|
|
removes all comments, replacing them with a single space, or an
|
|
appropriate number of newlines.
|
|
|
|
<A NAME="IDX78"></A>
|
|
<LI>
|
|
|
|
converts character constants into the appropriate numeric values.
|
|
</UL>
|
|
|
|
<P>
|
|
It does not do macro processing, include file handling, or
|
|
anything else you may get from your C compiler's preprocessor. You can
|
|
do include file processing with the <CODE>.include</CODE> directive
|
|
(see section <A HREF="#SEC86"><CODE>.include "<VAR>file</CODE>"</VAR></A>). You can use the GNU C compiler driver
|
|
to get other "CPP" style preprocessing, by giving the input file a
|
|
<SAMP>`.S'</SAMP> suffix. See section `Options Controlling the Kind of Output' in <CITE>Using GNU CC</CITE>.
|
|
|
|
</P>
|
|
<P>
|
|
Excess whitespace, comments, and character constants
|
|
cannot be used in the portions of the input text that are not
|
|
preprocessed.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX79"></A>
|
|
<A NAME="IDX80"></A>
|
|
<A NAME="IDX81"></A>
|
|
<A NAME="IDX82"></A>
|
|
If the first line of an input file is <CODE>#NO_APP</CODE> or if you use the
|
|
<SAMP>`-f'</SAMP> option, whitespace and comments are not removed from the input file.
|
|
Within an input file, you can ask for whitespace and comment removal in
|
|
specific portions of the by putting a line that says <CODE>#APP</CODE> before the
|
|
text that may contain whitespace or comments, and putting a line that says
|
|
<CODE>#NO_APP</CODE> after this text. This feature is mainly intend to support
|
|
<CODE>asm</CODE> statements in compilers whose output is otherwise free of comments
|
|
and whitespace.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC25" HREF="#TOC25">Whitespace</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX83"></A>
|
|
<STRONG>Whitespace</STRONG> is one or more blanks or tabs, in any order.
|
|
Whitespace is used to separate symbols, and to make programs neater for
|
|
people to read. Unless within character constants
|
|
(see section <A HREF="#SEC30">Character Constants</A>), any whitespace means the same
|
|
as exactly one space.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC26" HREF="#TOC26">Comments</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX84"></A>
|
|
There are two ways of rendering comments to <CODE></CODE>. In both
|
|
cases the comment is equivalent to one space.
|
|
|
|
</P>
|
|
<P>
|
|
Anything from <SAMP>`/*'</SAMP> through the next <SAMP>`*/'</SAMP> is a comment.
|
|
This means you may not nest these comments.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
/*
|
|
The only way to include a newline ('\n') in a comment
|
|
is to use this sort of comment.
|
|
*/
|
|
|
|
/* This sort of comment does not nest. */
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX85"></A>
|
|
Anything from the <STRONG>line comment</STRONG> character to the next newline
|
|
is considered a comment and is ignored. The line comment character is
|
|
see @xref{Machine Dependencies}.
|
|
</P>
|
|
|
|
<P>
|
|
<A NAME="IDX86"></A>
|
|
<A NAME="IDX87"></A>
|
|
<A NAME="IDX88"></A>
|
|
To be compatible with past assemblers, lines that begin with <SAMP>`#'</SAMP> have a
|
|
special interpretation. Following the <SAMP>`#'</SAMP> should be an absolute
|
|
expression (see section <A HREF="#SEC54">Expressions</A>): the logical line number of the <EM>next</EM>
|
|
line. Then a string (see section <A HREF="#SEC31">Strings</A>) is allowed: if present it is a
|
|
new logical file name. The rest of the line, if any, should be whitespace.
|
|
|
|
</P>
|
|
<P>
|
|
If the first non-whitespace characters on the line are not numeric,
|
|
the line is ignored. (Just like a comment.)
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
# This is an ordinary comment.
|
|
# 42-6 "new_file_name" # New logical file name
|
|
# This is logical line # 36.
|
|
</PRE>
|
|
|
|
<P>
|
|
This feature is deprecated, and may disappear from future versions
|
|
of <CODE></CODE>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC27" HREF="#TOC27">Symbols</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX89"></A>
|
|
A <STRONG>symbol</STRONG> is one or more characters chosen from the set of all
|
|
letters (both upper and lower case), digits and the three characters
|
|
<SAMP>`_.$'</SAMP>.
|
|
No symbol may begin with a digit. Case is significant.
|
|
There is no length limit: all characters are significant. Symbols are
|
|
delimited by characters not in that set, or by the beginning of a file
|
|
(since the source program must end with a newline, the end of a file is
|
|
not a possible symbol delimiter). See section <A HREF="#SEC43">Symbols</A>.
|
|
<A NAME="IDX90"></A>
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC28" HREF="#TOC28">Statements</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX91"></A>
|
|
<A NAME="IDX92"></A>
|
|
<A NAME="IDX93"></A>
|
|
A <STRONG>statement</STRONG> ends at a newline character (<SAMP>`\n'</SAMP>) or at a
|
|
semicolon (<SAMP>`;'</SAMP>). The newline or semicolon is considered part of
|
|
the preceding statement. Newlines and semicolons within character
|
|
constants are an exception: they do not end statements.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX94"></A>
|
|
<A NAME="IDX95"></A>
|
|
It is an error to end any statement with end-of-file: the last
|
|
character of any input file should be a newline.
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX96"></A>
|
|
<A NAME="IDX97"></A>
|
|
<A NAME="IDX98"></A>
|
|
You may write a statement on more than one line if you put a
|
|
backslash (<KBD>\</KBD>) immediately in front of any newlines within the
|
|
statement. When <CODE></CODE> reads a backslashed newline both
|
|
characters are ignored. You can even put backslashed newlines in
|
|
the middle of symbol names without changing the meaning of your
|
|
source program.
|
|
|
|
</P>
|
|
<P>
|
|
An empty statement is allowed, and may include whitespace. It is ignored.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX99"></A>
|
|
<A NAME="IDX100"></A>
|
|
A statement begins with zero or more labels, optionally followed by a
|
|
key symbol which determines what kind of statement it is. The key
|
|
symbol determines the syntax of the rest of the statement. If the
|
|
symbol begins with a dot <SAMP>`.'</SAMP> then the statement is an assembler
|
|
directive: typically valid for any computer. If the symbol begins with
|
|
a letter the statement is an assembly language <STRONG>instruction</STRONG>: it
|
|
assembles into a machine language instruction.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX101"></A>
|
|
<A NAME="IDX102"></A>
|
|
A label is a symbol immediately followed by a colon (<CODE>:</CODE>).
|
|
Whitespace before a label or after a colon is permitted, but you may not
|
|
have whitespace between a label's symbol and its colon. See section <A HREF="#SEC44">Labels</A>.
|
|
|
|
</P>
|
|
|
|
|
|
<PRE>
|
|
label: .directive followed by something
|
|
another_label: # This is an empty statement.
|
|
instruction operand_1, operand_2, ...
|
|
</PRE>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC29" HREF="#TOC29">Constants</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX103"></A>
|
|
A constant is a number, written so that its value is known by
|
|
inspection, without knowing any context. Like this:
|
|
|
|
<PRE>
|
|
.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
|
|
.ascii "Ring the bell\7" # A string constant.
|
|
.octa 0x123456789abcdef0123456789ABCDEF0 # A bignum.
|
|
.float 0f-314159265358979323846264338327\
|
|
95028841971.693993751E-40 # - pi, a flonum.
|
|
</PRE>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC30" HREF="#TOC30">Character Constants</A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX104"></A>
|
|
<A NAME="IDX105"></A>
|
|
There are two kinds of character constants. A <STRONG>character</STRONG> stands
|
|
for one character in one byte and its value may be used in
|
|
numeric expressions. String constants (properly called string
|
|
<EM>literals</EM>) are potentially many bytes and their values may not be
|
|
used in arithmetic expressions.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H4><A NAME="SEC31" HREF="#TOC31">Strings</A></H4>
|
|
|
|
<P>
|
|
<A NAME="IDX106"></A>
|
|
<A NAME="IDX107"></A>
|
|
A <STRONG>string</STRONG> is written between double-quotes. It may contain
|
|
double-quotes or null characters. The way to get special characters
|
|
into a string is to <STRONG>escape</STRONG> these characters: precede them with
|
|
a backslash <SAMP>`\'</SAMP> character. For example <SAMP>`\\'</SAMP> represents
|
|
one backslash: the first <CODE>\</CODE> is an escape which tells
|
|
<CODE></CODE> to interpret the second character literally as a backslash
|
|
(which prevents <CODE></CODE> from recognizing the second <CODE>\</CODE> as an
|
|
escape character). The complete list of escapes follows.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX108"></A>
|
|
<A NAME="IDX109"></A>
|
|
<DL COMPACT>
|
|
|
|
<DT><KBD>\b</KBD>
|
|
<DD>
|
|
<A NAME="IDX110"></A>
|
|
<A NAME="IDX111"></A>
|
|
|
|
Mnemonic for backspace; for ASCII this is octal code 010.
|
|
|
|
<A NAME="IDX112"></A>
|
|
<A NAME="IDX113"></A>
|
|
<DT><KBD>\f</KBD>
|
|
<DD>
|
|
Mnemonic for FormFeed; for ASCII this is octal code 014.
|
|
|
|
<A NAME="IDX114"></A>
|
|
<A NAME="IDX115"></A>
|
|
<DT><KBD>\n</KBD>
|
|
<DD>
|
|
Mnemonic for newline; for ASCII this is octal code 012.
|
|
|
|
<A NAME="IDX116"></A>
|
|
<A NAME="IDX117"></A>
|
|
<DT><KBD>\r</KBD>
|
|
<DD>
|
|
Mnemonic for carriage-Return; for ASCII this is octal code 015.
|
|
|
|
<A NAME="IDX118"></A>
|
|
<A NAME="IDX119"></A>
|
|
<DT><KBD>\t</KBD>
|
|
<DD>
|
|
Mnemonic for horizontal Tab; for ASCII this is octal code 011.
|
|
|
|
<A NAME="IDX120"></A>
|
|
<A NAME="IDX121"></A>
|
|
<DT><KBD>\ <VAR>digit</VAR> <VAR>digit</VAR> <VAR>digit</VAR></KBD>
|
|
<DD>
|
|
An octal character code. The numeric code is 3 octal digits.
|
|
For compatibility with other Unix systems, 8 and 9 are accepted as digits:
|
|
for example, <CODE>\008</CODE> has the value 010, and <CODE>\009</CODE> the value 011.
|
|
|
|
<A NAME="IDX122"></A>
|
|
<A NAME="IDX123"></A>
|
|
<DT><KBD>\<CODE>x</CODE> <VAR>hex-digits...</VAR></KBD>
|
|
<DD>
|
|
A hex character code. All trailing hex digits are combined. Either upper or
|
|
lower case <CODE>x</CODE> works.
|
|
|
|
<A NAME="IDX124"></A>
|
|
<A NAME="IDX125"></A>
|
|
<DT><KBD>\\</KBD>
|
|
<DD>
|
|
Represents one <SAMP>`\'</SAMP> character.
|
|
|
|
<A NAME="IDX126"></A>
|
|
<A NAME="IDX127"></A>
|
|
<DT><KBD>\"</KBD>
|
|
<DD>
|
|
Represents one <SAMP>`"'</SAMP> character. Needed in strings to represent
|
|
this character, because an unescaped <SAMP>`"'</SAMP> would end the string.
|
|
|
|
<DT><KBD>\ <VAR>anything-else</VAR></KBD>
|
|
<DD>
|
|
Any other character when escaped by <KBD>\</KBD> gives a warning, but
|
|
assembles as if the <SAMP>`\'</SAMP> was not present. The idea is that if
|
|
you used an escape sequence you clearly didn't want the literal
|
|
interpretation of the following character. However <CODE></CODE> has no
|
|
other interpretation, so <CODE></CODE> knows it is giving you the wrong
|
|
code and warns you of the fact.
|
|
</DL>
|
|
|
|
<P>
|
|
Which characters are escapable, and what those escapes represent,
|
|
varies widely among assemblers. The current set is what we think
|
|
the BSD 4.2 assembler recognizes, and is a subset of what most C
|
|
compilers recognize. If you are in doubt, do not use an escape
|
|
sequence.
|
|
|
|
</P>
|
|
|
|
|
|
<H4><A NAME="SEC32" HREF="#TOC32">Characters</A></H4>
|
|
|
|
<P>
|
|
<A NAME="IDX128"></A>
|
|
<A NAME="IDX129"></A>
|
|
<A NAME="IDX130"></A>
|
|
A single character may be written as a single quote immediately
|
|
followed by that character. The same escapes apply to characters as
|
|
to strings. So if you want to write the character backslash, you
|
|
must write <KBD>'\\</KBD> where the first <CODE>\</CODE> escapes the second
|
|
<CODE>\</CODE>. As you can see, the quote is an acute accent, not a
|
|
grave accent. A newline
|
|
(or semicolon <SAMP>`;'</SAMP>)
|
|
immediately following an acute accent is taken as a literal character
|
|
and does not count as the end of a statement. The value of a character
|
|
constant in a numeric expression is the machine's byte-wide code for
|
|
that character. <CODE></CODE> assumes your character code is ASCII:
|
|
<KBD>'A</KBD> means 65, <KBD>'B</KBD> means 66, and so on.
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC33" HREF="#TOC33">Number Constants</A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX131"></A>
|
|
<A NAME="IDX132"></A>
|
|
<CODE></CODE> distinguishes three kinds of numbers according to how they
|
|
are stored in the target machine. <EM>Integers</EM> are numbers that
|
|
would fit into an <CODE>int</CODE> in the C language. <EM>Bignums</EM> are
|
|
integers, but they are stored in more than 32 bits. <EM>Flonums</EM>
|
|
are floating point numbers, described below.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H4><A NAME="SEC34" HREF="#TOC34">Integers</A></H4>
|
|
<P>
|
|
<A NAME="IDX133"></A>
|
|
<A NAME="IDX134"></A>
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX135"></A>
|
|
<A NAME="IDX136"></A>
|
|
A binary integer is <SAMP>`0b'</SAMP> or <SAMP>`0B'</SAMP> followed by zero or more of
|
|
the binary digits <SAMP>`01'</SAMP>.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX137"></A>
|
|
<A NAME="IDX138"></A>
|
|
An octal integer is <SAMP>`0'</SAMP> followed by zero or more of the octal
|
|
digits (<SAMP>`01234567'</SAMP>).
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX139"></A>
|
|
<A NAME="IDX140"></A>
|
|
A decimal integer starts with a non-zero digit followed by zero or
|
|
more digits (<SAMP>`0123456789'</SAMP>).
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX141"></A>
|
|
<A NAME="IDX142"></A>
|
|
A hexadecimal integer is <SAMP>`0x'</SAMP> or <SAMP>`0X'</SAMP> followed by one or
|
|
more hexadecimal digits chosen from <SAMP>`0123456789abcdefABCDEF'</SAMP>.
|
|
|
|
</P>
|
|
<P>
|
|
Integers have the usual values. To denote a negative integer, use
|
|
the prefix operator <SAMP>`-'</SAMP> discussed under expressions
|
|
(see section <A HREF="#SEC59">Prefix Operator</A>).
|
|
|
|
</P>
|
|
|
|
|
|
<H4><A NAME="SEC35" HREF="#TOC35">Bignums</A></H4>
|
|
|
|
<P>
|
|
<A NAME="IDX143"></A>
|
|
<A NAME="IDX144"></A>
|
|
A <STRONG>bignum</STRONG> has the same syntax and semantics as an integer
|
|
except that the number (or its negative) takes more than 32 bits to
|
|
represent in binary. The distinction is made because in some places
|
|
integers are permitted while bignums are not.
|
|
|
|
</P>
|
|
|
|
|
|
<H4><A NAME="SEC36" HREF="#TOC36">Flonums</A></H4>
|
|
<P>
|
|
<A NAME="IDX145"></A>
|
|
<A NAME="IDX146"></A>
|
|
<A NAME="IDX147"></A>
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX148"></A>
|
|
A <STRONG>flonum</STRONG> represents a floating point number. The translation is
|
|
indirect: a decimal floating point number from the text is converted by
|
|
<CODE></CODE> to a generic binary floating point number of more than
|
|
sufficient precision. This generic floating point number is converted
|
|
to a particular computer's floating point format (or formats) by a
|
|
portion of <CODE></CODE> specialized to that computer.
|
|
|
|
</P>
|
|
<P>
|
|
A flonum is written by writing (in order)
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
The digit <SAMP>`0'</SAMP>.
|
|
|
|
<LI>
|
|
|
|
A letter, to tell <CODE></CODE> the rest of the number is a flonum.
|
|
|
|
<LI>
|
|
|
|
An optional sign: either <SAMP>`+'</SAMP> or <SAMP>`-'</SAMP>.
|
|
|
|
<LI>
|
|
|
|
An optional <STRONG>integer part</STRONG>: zero or more decimal digits.
|
|
|
|
<LI>
|
|
|
|
An optional <STRONG>fractional part</STRONG>: <SAMP>`.'</SAMP> followed by zero
|
|
or more decimal digits.
|
|
|
|
<LI>
|
|
|
|
An optional exponent, consisting of:
|
|
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
An <SAMP>`E'</SAMP> or <SAMP>`e'</SAMP>.
|
|
<LI>
|
|
|
|
Optional sign: either <SAMP>`+'</SAMP> or <SAMP>`-'</SAMP>.
|
|
<LI>
|
|
|
|
One or more decimal digits.
|
|
</UL>
|
|
|
|
</UL>
|
|
|
|
<P>
|
|
At least one of the integer part or the fractional part must be
|
|
present. The floating point number has the usual base-10 value.
|
|
|
|
</P>
|
|
<P>
|
|
<CODE></CODE> does all processing using integers. Flonums are computed
|
|
independently of any floating point hardware in the computer running
|
|
<CODE></CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
into a field whose width depends on which assembler directive has the
|
|
bit-field as its argument. Overflow (a result from the bitwise and
|
|
requiring more binary digits to represent) is not an error; instead,
|
|
more constants are generated, of the specified width, beginning with the
|
|
least significant digits.
|
|
</P>
|
|
<P>
|
|
The directives <CODE>.byte</CODE>, <CODE>.hword</CODE>, <CODE>.int</CODE>, <CODE>.long</CODE>,
|
|
<CODE>.short</CODE>, and <CODE>.word</CODE> accept bit-field arguments.
|
|
|
|
</P>
|
|
|
|
|
|
<H1><A NAME="SEC37" HREF="#TOC37">Sections and Relocation</A></H1>
|
|
<P>
|
|
<A NAME="IDX149"></A>
|
|
<A NAME="IDX150"></A>
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC38" HREF="#TOC38">Background</A></H2>
|
|
|
|
<P>
|
|
Roughly, a section is a range of addresses, with no gaps; all data
|
|
"in" those addresses is treated the same for some particular purpose.
|
|
For example there may be a "read only" section.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX151"></A>
|
|
<A NAME="IDX152"></A>
|
|
The linker <CODE></CODE> reads many object files (partial programs) and
|
|
combines their contents to form a runnable program. When <CODE></CODE>
|
|
emits an object file, the partial program is assumed to start at address 0.
|
|
<CODE></CODE> assigns the final addresses for the partial program, so that
|
|
different partial programs do not overlap. This is actually an
|
|
oversimplification, but it suffices to explain how <CODE></CODE> uses
|
|
sections.
|
|
|
|
</P>
|
|
<P>
|
|
<CODE></CODE> moves blocks of bytes of your program to their run-time
|
|
addresses. These blocks slide to their run-time addresses as rigid
|
|
units; their length does not change and neither does the order of bytes
|
|
within them. Such a rigid unit is called a <EM>section</EM>. Assigning
|
|
run-time addresses to sections is called <STRONG>relocation</STRONG>. It includes
|
|
the task of adjusting mentions of object-file addresses so they refer to
|
|
the proper run-time addresses.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX153"></A>
|
|
An object file written by <CODE></CODE> has at least three sections, any
|
|
of which may be empty. These are named <STRONG>text</STRONG>, <STRONG>data</STRONG> and
|
|
<STRONG>bss</STRONG> sections.
|
|
|
|
</P>
|
|
<P>
|
|
<CODE></CODE> can also generate whatever other named sections you specify
|
|
using the <SAMP>`.section'</SAMP> directive (see section <A HREF="#SEC107"><CODE>.section <VAR>name</CODE></VAR></A>).
|
|
If you do not use any directives that place output in the <SAMP>`.text'</SAMP>
|
|
or <SAMP>`.data'</SAMP> sections, these sections still exist, but are empty.
|
|
|
|
</P>
|
|
<P>
|
|
<CODE></CODE> can also generate whatever other named sections you
|
|
specify using the <SAMP>`.space'</SAMP> and <SAMP>`.subspace'</SAMP> directives. See
|
|
<CITE>HP9000 Series 800 Assembly Language Reference Manual</CITE>
|
|
(HP 92432-90001) for details on the <SAMP>`.space'</SAMP> and <SAMP>`.subspace'</SAMP>
|
|
assembler directives.
|
|
|
|
</P>
|
|
|
|
<P>
|
|
Within the object file, the text section starts at address <CODE>0</CODE>, the
|
|
data section follows, and the bss section follows the data section.
|
|
|
|
</P>
|
|
|
|
<P>
|
|
To let <CODE></CODE> know which data changes when the sections are
|
|
relocated, and how to change that data, <CODE></CODE> also writes to the
|
|
object file details of the relocation needed. To perform relocation
|
|
<CODE></CODE> must know, each time an address in the object
|
|
file is mentioned:
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
Where in the object file is the beginning of this reference to
|
|
an address?
|
|
<LI>
|
|
|
|
How long (in bytes) is this reference?
|
|
<LI>
|
|
|
|
Which section does the address refer to? What is the numeric value of
|
|
|
|
<PRE>
|
|
(<VAR>address</VAR>) - (<VAR>start-address of section</VAR>)?
|
|
</PRE>
|
|
|
|
<LI>
|
|
|
|
Is the reference to an address "Program-Counter relative"?
|
|
</UL>
|
|
|
|
<P>
|
|
<A NAME="IDX154"></A>
|
|
<A NAME="IDX155"></A>
|
|
In fact, every address <CODE></CODE> ever uses is expressed as
|
|
|
|
<PRE>
|
|
(<VAR>section</VAR>) + (<VAR>offset into section</VAR>)
|
|
</PRE>
|
|
|
|
<P>
|
|
Further, most expressions <CODE></CODE> computes have this section-relative
|
|
nature.
|
|
|
|
</P>
|
|
<P>
|
|
In this manual we use the notation {<VAR>secname</VAR> <VAR>N</VAR>} to mean "offset
|
|
<VAR>N</VAR> into section <VAR>secname</VAR>."
|
|
|
|
</P>
|
|
<P>
|
|
Apart from text, data and bss sections you need to know about the
|
|
<STRONG>absolute</STRONG> section. When <CODE></CODE> mixes partial programs,
|
|
addresses in the absolute section remain unchanged. For example, address
|
|
<CODE>{absolute 0}</CODE> is "relocated" to run-time address 0 by
|
|
<CODE></CODE>. Although the linker never arranges two partial programs'
|
|
data sections with overlapping addresses after linking, <EM>by definition</EM>
|
|
their absolute sections must overlap. Address <CODE>{absolute 239}</CODE> in one
|
|
part of a program is always the same address when the program is running as
|
|
address <CODE>{absolute 239}</CODE> in any other part of the program.
|
|
|
|
</P>
|
|
<P>
|
|
The idea of sections is extended to the <STRONG>undefined</STRONG> section. Any
|
|
address whose section is unknown at assembly time is by definition
|
|
rendered {undefined <VAR>U</VAR>}---where <VAR>U</VAR> is filled in later.
|
|
Since numbers are always defined, the only way to generate an undefined
|
|
address is to mention an undefined symbol. A reference to a named
|
|
common block would be such a symbol: its value is unknown at assembly
|
|
time so it has section <EM>undefined</EM>.
|
|
|
|
</P>
|
|
<P>
|
|
By analogy the word <EM>section</EM> is used to describe groups of sections in
|
|
the linked program. <CODE></CODE> puts all partial programs' text
|
|
sections in contiguous addresses in the linked program. It is
|
|
customary to refer to the <EM>text section</EM> of a program, meaning all
|
|
the addresses of all partial programs' text sections. Likewise for
|
|
data and bss sections.
|
|
|
|
</P>
|
|
<P>
|
|
Some sections are manipulated by <CODE></CODE>; others are invented for
|
|
use of <CODE></CODE> and have no meaning except during assembly.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC39" HREF="#TOC39">Linker Sections</A></H2>
|
|
<P>
|
|
<CODE></CODE> deals with just four kinds of sections, summarized below.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
These sections hold your program. <CODE></CODE> and <CODE></CODE> treat them as
|
|
separate but equal sections. Anything you can say of one section is
|
|
true another.
|
|
|
|
<DT><STRONG>bss section</STRONG>
|
|
<DD>
|
|
<A NAME="IDX156"></A>
|
|
|
|
This section contains zeroed bytes when your program begins running. It
|
|
is used to hold unitialized variables or common storage. The length of
|
|
each partial program's bss section is important, but because it starts
|
|
out containing zeroed bytes there is no need to store explicit zero
|
|
bytes in the object file. The bss section was invented to eliminate
|
|
those explicit zeros from object files.
|
|
|
|
<A NAME="IDX157"></A>
|
|
<DT><STRONG>absolute section</STRONG>
|
|
<DD>
|
|
Address 0 of this section is always "relocated" to runtime address 0.
|
|
This is useful if you want to refer to an address that <CODE></CODE> must
|
|
not change when relocating. In this sense we speak of absolute
|
|
addresses being "unrelocatable": they do not change during relocation.
|
|
|
|
<A NAME="IDX158"></A>
|
|
<DT><STRONG>undefined section</STRONG>
|
|
<DD>
|
|
This "section" is a catch-all for address references to objects not in
|
|
the preceding sections.
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="IDX159"></A>
|
|
An idealized example of three relocatable sections follows.
|
|
Memory addresses are on the horizontal axis.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC40" HREF="#TOC40">Assembler Internal Sections</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX160"></A>
|
|
<A NAME="IDX161"></A>
|
|
These sections are meant only for the internal use of <CODE></CODE>. They
|
|
have no meaning at run-time. You do not really need to know about these
|
|
sections for most purposes; but they can be mentioned in <CODE></CODE>
|
|
warning messages, so it might be helpful to have an idea of their
|
|
meanings to <CODE></CODE>. These sections are used to permit the
|
|
value of every expression in your assembly language program to be a
|
|
section-relative address.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><B>ASSEMBLER-INTERNAL-LOGIC-ERROR!</B>
|
|
<DD>
|
|
<A NAME="IDX162"></A>
|
|
|
|
An internal assembler logic error has been found. This means there is a
|
|
bug in the assembler.
|
|
|
|
<A NAME="IDX163"></A>
|
|
<DT><B>expr section</B>
|
|
<DD>
|
|
The assembler stores complex expression internally as combinations of
|
|
symbols. When it needs to represent an expression as a symbol, it puts
|
|
it in the expr section.
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC41" HREF="#TOC41">Sub-Sections</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX164"></A>
|
|
<A NAME="IDX165"></A>
|
|
fall into two sections: text and data.
|
|
You may have separate groups of
|
|
data in named sections
|
|
that you want to end up near to each other in the object file, even though they
|
|
are not contiguous in the assembler source. <CODE></CODE> allows you to
|
|
use <STRONG>subsections</STRONG> for this purpose. Within each section, there can be
|
|
numbered subsections with values from 0 to 8192. Objects assembled into the
|
|
same subsection go into the object file together with other objects in the same
|
|
subsection. For example, a compiler might want to store constants in the text
|
|
section, but might not want to have them interspersed with the program being
|
|
assembled. In this case, the compiler could issue a <SAMP>`.text 0'</SAMP> before each
|
|
section of code being output, and a <SAMP>`.text 1'</SAMP> before each group of
|
|
constants being output.
|
|
|
|
</P>
|
|
<P>
|
|
Subsections are optional. If you do not use subsections, everything
|
|
goes in subsection number zero.
|
|
|
|
</P>
|
|
|
|
<P>
|
|
Subsections appear in your object file in numeric order, lowest numbered
|
|
to highest. (All this to be compatible with other people's assemblers.)
|
|
The object file contains no representation of subsections; <CODE></CODE> and
|
|
other programs that manipulate object files see no trace of them.
|
|
They just see all your text subsections as a text section, and all your
|
|
data subsections as a data section.
|
|
|
|
</P>
|
|
<P>
|
|
To specify which subsection you want subsequent statements assembled
|
|
into, use a numeric argument to specify it, in a <SAMP>`.text
|
|
<VAR>expression</VAR>'</SAMP> or a <SAMP>`.data <VAR>expression</VAR>'</SAMP> statement.
|
|
You
|
|
can also use an extra subsection
|
|
argument with arbitrary named sections: <SAMP>`.section <VAR>name</VAR>,
|
|
<VAR>expression</VAR>'</SAMP>.
|
|
<VAR>Expression</VAR> should be an absolute expression.
|
|
(See section <A HREF="#SEC54">Expressions</A>.) If you just say <SAMP>`.text'</SAMP> then <SAMP>`.text 0'</SAMP>
|
|
is assumed. Likewise <SAMP>`.data'</SAMP> means <SAMP>`.data 0'</SAMP>. Assembly
|
|
begins in <CODE>text 0</CODE>. For instance:
|
|
|
|
<PRE>
|
|
.text 0 # The default subsection is text 0 anyway.
|
|
.ascii "This lives in the first text subsection. *"
|
|
.text 1
|
|
.ascii "But this lives in the second text subsection."
|
|
.data 0
|
|
.ascii "This lives in the data section,"
|
|
.ascii "in the first data subsection."
|
|
.text 0
|
|
.ascii "This lives in the first text section,"
|
|
.ascii "immediately following the asterisk (*)."
|
|
</PRE>
|
|
|
|
<P>
|
|
Each section has a <STRONG>location counter</STRONG> incremented by one for every byte
|
|
assembled into that section. Because subsections are merely a convenience
|
|
restricted to <CODE></CODE> there is no concept of a subsection location
|
|
counter. There is no way to directly manipulate a location counter--but the
|
|
<CODE>.align</CODE> directive changes it, and any label definition captures its
|
|
current value. The location counter of the section where statements are being
|
|
assembled is said to be the <STRONG>active</STRONG> location counter.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC42" HREF="#TOC42">bss Section</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX166"></A>
|
|
<A NAME="IDX167"></A>
|
|
The bss section is used for local common variable storage.
|
|
You may allocate address space in the bss section, but you may
|
|
not dictate data to load into it before your program executes. When
|
|
your program starts running, all the contents of the bss
|
|
section are zeroed bytes.
|
|
|
|
</P>
|
|
<P>
|
|
The <CODE>.lcomm</CODE> pseudo-op defines a symbol in the bss section; see
|
|
section <A HREF="#SEC90"><CODE>.lcomm <VAR>symbol</CODE> , <VAR>length</VAR></VAR></A>.
|
|
|
|
</P>
|
|
<P>
|
|
The <CODE>.comm</CODE> pseudo-op may be used to declare a common symbol, which is
|
|
another form of uninitialized symbol; see See section <A HREF="#SEC69"><CODE>.comm <VAR>symbol</CODE> , <VAR>length</VAR> </VAR></A>.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H1><A NAME="SEC43" HREF="#TOC43">Symbols</A></H1>
|
|
|
|
<P>
|
|
<A NAME="IDX168"></A>
|
|
Symbols are a central concept: the programmer uses symbols to name
|
|
things, the linker uses symbols to link, and the debugger uses symbols
|
|
to debug.
|
|
|
|
</P>
|
|
|
|
<BLOCKQUOTE>
|
|
<A NAME="IDX169"></A>
|
|
<P>
|
|
<EM>Warning:</EM> <CODE></CODE> does not place symbols in the object file in
|
|
the same order they were declared. This may break some debuggers.
|
|
</BLOCKQUOTE>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC44" HREF="#TOC44">Labels</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX170"></A>
|
|
A <STRONG>label</STRONG> is written as a symbol immediately followed by a colon
|
|
<SAMP>`:'</SAMP>. The symbol then represents the current value of the
|
|
active location counter, and is, for example, a suitable instruction
|
|
operand. You are warned if you use the same symbol to represent two
|
|
different locations: the first definition overrides any other
|
|
definitions.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC45" HREF="#TOC45">Giving Symbols Other Values</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX171"></A>
|
|
<A NAME="IDX172"></A>
|
|
A symbol can be given an arbitrary value by writing a symbol, followed
|
|
by an equals sign <SAMP>`='</SAMP>, followed by an expression
|
|
(see section <A HREF="#SEC54">Expressions</A>). This is equivalent to using the <CODE>.set</CODE>
|
|
directive. See section <A HREF="#SEC108"><CODE>.set <VAR>symbol</CODE>, <VAR>expression</VAR></VAR></A>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC46" HREF="#TOC46">Symbol Names</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX173"></A>
|
|
<A NAME="IDX174"></A>
|
|
Symbol names begin with a letter or with one of <SAMP>`._'</SAMP>. On most
|
|
machines, you can also use <CODE>$</CODE> in symbol names; exceptions are
|
|
noted in @xref{Machine Dependencies}. That character may be followed by any
|
|
string of digits, letters, dollar signs (unless otherwise noted in
|
|
@xref{Machine Dependencies}), and underscores.
|
|
|
|
</P>
|
|
|
|
<P>
|
|
Case of letters is significant: <CODE>foo</CODE> is a different symbol name
|
|
than <CODE>Foo</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
Each symbol has exactly one name. Each name in an assembly language program
|
|
refers to exactly one symbol. You may use that symbol name any number of times
|
|
in a program.
|
|
|
|
</P>
|
|
|
|
<H3>Local Symbol Names</H3>
|
|
|
|
<P>
|
|
<A NAME="IDX175"></A>
|
|
<A NAME="IDX176"></A>
|
|
<A NAME="IDX177"></A>
|
|
<A NAME="IDX178"></A>
|
|
Local symbols help compilers and programmers use names temporarily.
|
|
There are ten local symbol names, which are re-used throughout the
|
|
program. You may refer to them using the names <SAMP>`0'</SAMP> <SAMP>`1'</SAMP>
|
|
... <SAMP>`9'</SAMP>. To define a local symbol, write a label of the form
|
|
<SAMP>`<B>N</B>:'</SAMP> (where <B>N</B> represents any digit). To refer to the most
|
|
recent previous definition of that symbol write <SAMP>`<B>N</B>b'</SAMP>, using the
|
|
same digit as when you defined the label. To refer to the next
|
|
definition of a local label, write <SAMP>`<B>N</B>f'</SAMP>---where <B>N</B> gives you
|
|
a choice of 10 forward references. The <SAMP>`b'</SAMP> stands for
|
|
"backwards" and the <SAMP>`f'</SAMP> stands for "forwards".
|
|
|
|
</P>
|
|
<P>
|
|
Local symbols are not emitted by the current GNU C compiler.
|
|
|
|
</P>
|
|
<P>
|
|
There is no restriction on how you can use these labels, but
|
|
remember that at any point in the assembly you can refer to at most
|
|
10 prior local labels and to at most 10 forward local labels.
|
|
|
|
</P>
|
|
<P>
|
|
Local symbol names are only a notation device. They are immediately
|
|
transformed into more conventional symbol names before the assembler
|
|
uses them. The symbol names stored in the symbol table, appearing in
|
|
error messages and optionally emitted to the object file have these
|
|
parts:
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>L</CODE>
|
|
<DD>
|
|
All local labels begin with <SAMP>`L'</SAMP>. Normally both <CODE></CODE> and
|
|
<CODE></CODE> forget symbols that start with <SAMP>`L'</SAMP>. These labels are
|
|
used for symbols you are never intended to see. If you use the
|
|
<SAMP>`-L'</SAMP> option then <CODE></CODE> retains these symbols in the
|
|
object file. If you also instruct <CODE></CODE> to retain these symbols,
|
|
you may use them in debugging.
|
|
|
|
<DT><CODE><VAR>digit</VAR></CODE>
|
|
<DD>
|
|
If the label is written <SAMP>`0:'</SAMP> then the digit is <SAMP>`0'</SAMP>.
|
|
If the label is written <SAMP>`1:'</SAMP> then the digit is <SAMP>`1'</SAMP>.
|
|
And so on up through <SAMP>`9:'</SAMP>.
|
|
|
|
<DT><CODE><KBD>C-A</KBD></CODE>
|
|
<DD>
|
|
This unusual character is included so you do not accidentally invent
|
|
a symbol of the same name. The character has ASCII value
|
|
<SAMP>`\001'</SAMP>.
|
|
|
|
<DT><CODE><EM>ordinal number</EM></CODE>
|
|
<DD>
|
|
This is a serial number to keep the labels distinct. The first
|
|
<SAMP>`0:'</SAMP> gets the number <SAMP>`1'</SAMP>; The 15th <SAMP>`0:'</SAMP> gets the
|
|
number <SAMP>`15'</SAMP>; <EM>etc.</EM>. Likewise for the other labels <SAMP>`1:'</SAMP>
|
|
through <SAMP>`9:'</SAMP>.
|
|
</DL>
|
|
|
|
<P>
|
|
For instance, the first <CODE>1:</CODE> is named <CODE>L1<KBD>C-A</KBD>1</CODE>, the 44th
|
|
<CODE>3:</CODE> is named <CODE>L3<KBD>C-A</KBD>44</CODE>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC47" HREF="#TOC47">The Special Dot Symbol</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX179"></A>
|
|
<A NAME="IDX180"></A>
|
|
<A NAME="IDX181"></A>
|
|
<A NAME="IDX182"></A>
|
|
The special symbol <SAMP>`.'</SAMP> refers to the current address that
|
|
<CODE></CODE> is assembling into. Thus, the expression <SAMP>`melvin:
|
|
.long .'</SAMP> defines <CODE>melvin</CODE> to contain its own address.
|
|
Assigning a value to <CODE>.</CODE> is treated the same as a <CODE>.org</CODE>
|
|
directive. Thus, the expression <SAMP>`.=.+4'</SAMP> is the same as saying
|
|
<SAMP>`.space 4'</SAMP>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC48" HREF="#TOC48">Symbol Attributes</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX183"></A>
|
|
<A NAME="IDX184"></A>
|
|
Every symbol has, as well as its name, the attributes "Value" and
|
|
"Type". Depending on output format, symbols can also have auxiliary
|
|
attributes.
|
|
|
|
</P>
|
|
<P>
|
|
If you use a symbol without defining it, <CODE></CODE> assumes zero for
|
|
all these attributes, and probably won't warn you. This makes the
|
|
symbol an externally defined symbol, which is generally what you
|
|
would want.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC49" HREF="#TOC49">Value</A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX185"></A>
|
|
<A NAME="IDX186"></A>
|
|
The value of a symbol is (usually) 32 bits. For a symbol which labels a
|
|
location in the text, data, bss or absolute sections the value is the
|
|
number of addresses from the start of that section to the label.
|
|
Naturally for text, data and bss sections the value of a symbol changes
|
|
as <CODE></CODE> changes section base addresses during linking. Absolute
|
|
symbols' values do not change during linking: that is why they are
|
|
called absolute.
|
|
|
|
</P>
|
|
<P>
|
|
The value of an undefined symbol is treated in a special way. If it is
|
|
0 then the symbol is not defined in this assembler source file, and
|
|
<CODE></CODE> tries to determine its value from other files linked into the
|
|
same program. You make this kind of symbol simply by mentioning a symbol
|
|
name without defining it. A non-zero value represents a <CODE>.comm</CODE>
|
|
common declaration. The value is how much common storage to reserve, in
|
|
bytes (addresses). The symbol refers to the first address of the
|
|
allocated storage.
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC50" HREF="#TOC50">Type</A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX187"></A>
|
|
<A NAME="IDX188"></A>
|
|
The type attribute of a symbol contains relocation (section)
|
|
information, any flag settings indicating that a symbol is external, and
|
|
(optionally), other information for linkers and debuggers. The exact
|
|
format depends on the object-code output format in use.
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC51" HREF="#TOC51">Symbol Attributes: <CODE>a.out</CODE></A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX189"></A>
|
|
<A NAME="IDX190"></A>
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H4><A NAME="SEC52" HREF="#TOC52">Descriptor</A></H4>
|
|
|
|
<P>
|
|
<A NAME="IDX191"></A>
|
|
This is an arbitrary 16-bit value. You may establish a symbol's
|
|
descriptor value by using a <CODE>.desc</CODE> statement
|
|
(@xref{Desc,,<CODE>.desc</CODE>}). A descriptor value means nothing to
|
|
<CODE></CODE>.
|
|
|
|
</P>
|
|
|
|
|
|
<H4><A NAME="SEC53" HREF="#TOC53">Other</A></H4>
|
|
|
|
<P>
|
|
<A NAME="IDX192"></A>
|
|
This is an arbitrary 8-bit value. It means nothing to <CODE></CODE>.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H1><A NAME="SEC54" HREF="#TOC54">Expressions</A></H1>
|
|
|
|
<P>
|
|
<A NAME="IDX193"></A>
|
|
<A NAME="IDX194"></A>
|
|
<A NAME="IDX195"></A>
|
|
An <STRONG>expression</STRONG> specifies an address or numeric value.
|
|
Whitespace may precede and/or follow an expression.
|
|
|
|
</P>
|
|
<P>
|
|
The result of an expression must be an absolute number, or else an offset into
|
|
a particular section. If an expression is not absolute, and there is not
|
|
enough information when <CODE></CODE> sees the expression to know its
|
|
section, a second pass over the source program might be necessary to interpret
|
|
the expression--but the second pass is currently not implemented.
|
|
<CODE></CODE> aborts with an error message in this situation.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC55" HREF="#TOC55">Empty Expressions</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX196"></A>
|
|
<A NAME="IDX197"></A>
|
|
An empty expression has no value: it is just whitespace or null.
|
|
Wherever an absolute expression is required, you may omit the
|
|
expression, and <CODE></CODE> assumes a value of (absolute) 0. This
|
|
is compatible with other assemblers.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC56" HREF="#TOC56">Integer Expressions</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX198"></A>
|
|
<A NAME="IDX199"></A>
|
|
An <STRONG>integer expression</STRONG> is one or more <EM>arguments</EM> delimited
|
|
by <EM>operators</EM>.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC57" HREF="#TOC57">Arguments</A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX200"></A>
|
|
<A NAME="IDX201"></A>
|
|
<A NAME="IDX202"></A>
|
|
<A NAME="IDX203"></A>
|
|
<STRONG>Arguments</STRONG> are symbols, numbers or subexpressions. In other
|
|
contexts arguments are sometimes called "arithmetic operands". In
|
|
this manual, to avoid confusing them with the "instruction operands" of
|
|
the machine language, we use the term "argument" to refer to parts of
|
|
expressions only, reserving the word "operand" to refer only to machine
|
|
instruction operands.
|
|
|
|
</P>
|
|
<P>
|
|
Symbols are evaluated to yield {<VAR>section</VAR> <VAR>NNN</VAR>} where
|
|
<VAR>section</VAR> is one of text, data, bss, absolute,
|
|
or undefined. <VAR>NNN</VAR> is a signed, 2's complement 32 bit
|
|
integer.
|
|
|
|
</P>
|
|
<P>
|
|
Numbers are usually integers.
|
|
|
|
</P>
|
|
<P>
|
|
A number can be a flonum or bignum. In this case, you are warned
|
|
that only the low order 32 bits are used, and <CODE></CODE> pretends
|
|
these 32 bits are an integer. You may write integer-manipulating
|
|
instructions that act on exotic constants, compatible with other
|
|
assemblers.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX204"></A>
|
|
Subexpressions are a left parenthesis <SAMP>`('</SAMP> followed by an integer
|
|
expression, followed by a right parenthesis <SAMP>`)'</SAMP>; or a prefix
|
|
operator followed by an argument.
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC58" HREF="#TOC58">Operators</A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX205"></A>
|
|
<A NAME="IDX206"></A>
|
|
<A NAME="IDX207"></A>
|
|
<STRONG>Operators</STRONG> are arithmetic functions, like <CODE>+</CODE> or <CODE>%</CODE>. Prefix
|
|
operators are followed by an argument. Infix operators appear
|
|
between their arguments. Operators may be preceded and/or followed by
|
|
whitespace.
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC59" HREF="#TOC59">Prefix Operator</A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX208"></A>
|
|
<CODE></CODE> has the following <STRONG>prefix operators</STRONG>. They each take
|
|
one argument, which must be absolute.
|
|
|
|
</P>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>-</CODE>
|
|
<DD>
|
|
<STRONG>Negation</STRONG>. Two's complement negation.
|
|
<DT><CODE>~</CODE>
|
|
<DD>
|
|
<STRONG>Complementation</STRONG>. Bitwise not.
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC60" HREF="#TOC60">Infix Operators</A></H3>
|
|
|
|
<P>
|
|
<A NAME="IDX209"></A>
|
|
<A NAME="IDX210"></A>
|
|
<STRONG>Infix operators</STRONG> take two arguments, one on either side. Operators
|
|
have precedence, but operations with equal precedence are performed left
|
|
to right. Apart from <CODE>+</CODE> or <CODE>-</CODE>, both arguments must be
|
|
absolute, and the result is absolute.
|
|
|
|
</P>
|
|
|
|
<OL>
|
|
|
|
<LI>
|
|
|
|
<A NAME="IDX211"></A>
|
|
<A NAME="IDX212"></A>
|
|
|
|
Highest Precedence
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>*</CODE>
|
|
<DD>
|
|
<STRONG>Multiplication</STRONG>.
|
|
|
|
<DT><CODE>/</CODE>
|
|
<DD>
|
|
<STRONG>Division</STRONG>. Truncation is the same as the C operator <SAMP>`/'</SAMP>
|
|
|
|
<DT><CODE>%</CODE>
|
|
<DD>
|
|
<STRONG>Remainder</STRONG>.
|
|
|
|
<DT><CODE><</CODE>
|
|
<DD>
|
|
<DT><CODE><<</CODE>
|
|
<DD>
|
|
<STRONG>Shift Left</STRONG>. Same as the C operator <SAMP>`<<'</SAMP>.
|
|
|
|
<DT><CODE>></CODE>
|
|
<DD>
|
|
<DT><CODE>>></CODE>
|
|
<DD>
|
|
<STRONG>Shift Right</STRONG>. Same as the C operator <SAMP>`>>'</SAMP>.
|
|
</DL>
|
|
|
|
<LI>
|
|
|
|
Intermediate precedence
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>|</CODE>
|
|
<DD>
|
|
<STRONG>Bitwise Inclusive Or</STRONG>.
|
|
|
|
<DT><CODE>&</CODE>
|
|
<DD>
|
|
<STRONG>Bitwise And</STRONG>.
|
|
|
|
<DT><CODE>^</CODE>
|
|
<DD>
|
|
<STRONG>Bitwise Exclusive Or</STRONG>.
|
|
|
|
<DT><CODE>!</CODE>
|
|
<DD>
|
|
<STRONG>Bitwise Or Not</STRONG>.
|
|
</DL>
|
|
|
|
<LI>
|
|
|
|
Lowest Precedence
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>+</CODE>
|
|
<DD>
|
|
<A NAME="IDX213"></A>
|
|
<A NAME="IDX214"></A>
|
|
<A NAME="IDX215"></A>
|
|
|
|
<STRONG>Addition</STRONG>. If either argument is absolute, the result has the section of
|
|
the other argument. You may not add together arguments from different
|
|
sections.
|
|
|
|
<A NAME="IDX216"></A>
|
|
<A NAME="IDX217"></A>
|
|
<A NAME="IDX218"></A>
|
|
<DT><CODE>-</CODE>
|
|
<DD>
|
|
<STRONG>Subtraction</STRONG>. If the right argument is absolute, the
|
|
result has the section of the left argument.
|
|
If both arguments are in the same section, the result is absolute.
|
|
You may not subtract arguments from different sections.
|
|
</DL>
|
|
</OL>
|
|
|
|
<P>
|
|
In short, it's only meaningful to add or subtract the <EM>offsets</EM> in an
|
|
address; you can only have a defined section in one of the two arguments.
|
|
|
|
</P>
|
|
|
|
|
|
<H1><A NAME="SEC61" HREF="#TOC61">Assembler Directives</A></H1>
|
|
|
|
<P>
|
|
<A NAME="IDX219"></A>
|
|
<A NAME="IDX220"></A>
|
|
<A NAME="IDX221"></A>
|
|
All assembler directives have names that begin with a period (<SAMP>`.'</SAMP>).
|
|
The rest of the name is letters, usually in lower case.
|
|
|
|
</P>
|
|
<P>
|
|
This chapter discusses directives that are available regardless of the
|
|
target machine configuration for the GNU assembler.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC62" HREF="#TOC62"><CODE>.abort</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX222"></A>
|
|
<A NAME="IDX223"></A>
|
|
This directive stops the assembly immediately. It is for
|
|
compatibility with other assemblers. The original idea was that the
|
|
assembly language source would be piped into the assembler. If the sender
|
|
of the source quit, it could use this directive tells <CODE></CODE> to
|
|
quit also. One day <CODE>.abort</CODE> will not be supported.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC63" HREF="#TOC63"><CODE>.align <VAR>abs-expr</VAR>, <VAR>abs-expr</VAR>, <VAR>abs-expr</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX224"></A>
|
|
<A NAME="IDX225"></A>
|
|
Pad the location counter (in the current subsection) to a particular storage
|
|
boundary. The first expression (which must be absolute) is the alignment
|
|
required, as described below.
|
|
|
|
</P>
|
|
<P>
|
|
The second expression (also absolute) gives the fill value to be stored in the
|
|
padding bytes. It (and the comma) may be omitted. If it is omitted, the
|
|
padding bytes are normally zero. However, on some systems, if the section is
|
|
marked as containing code and the fill value is omitted, the space is filled
|
|
with no-op instructions.
|
|
|
|
</P>
|
|
<P>
|
|
The third expression is also absolute, and is also optional. If it is present,
|
|
it is the maximum number of bytes that should be skipped by this alignment
|
|
directive. If doing the alignment would require skipping more bytes than the
|
|
specified maximum, then the alignment is not done at all. You can omit the
|
|
fill value (the second argument) entirely by simply using two commas after the
|
|
required alignment; this can be useful if you want the alignment to be filled
|
|
with no-op instructions when appropriate.
|
|
|
|
</P>
|
|
<P>
|
|
The way the required alignment is specified varies from system to system.
|
|
For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF
|
|
format,
|
|
the first expression is the
|
|
alignment request in bytes. For example <SAMP>`.align 8'</SAMP> advances
|
|
the location counter until it is a multiple of 8. If the location counter
|
|
is already a multiple of 8, no change is needed.
|
|
|
|
</P>
|
|
<P>
|
|
For other systems, including the i386 using a.out format, it is the
|
|
number of low-order zero bits the location counter must have after
|
|
advancement. For example <SAMP>`.align 3'</SAMP> advances the location
|
|
counter until it a multiple of 8. If the location counter is already a
|
|
multiple of 8, no change is needed.
|
|
|
|
</P>
|
|
<P>
|
|
This inconsistency is due to the different behaviors of the various
|
|
native assemblers for these systems which GAS must emulate.
|
|
GAS also provides <CODE>.balign</CODE> and <CODE>.p2align</CODE> directives,
|
|
described later, which have a consistent behavior across all
|
|
architectures (but are specific to GAS).
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC64" HREF="#TOC64"><CODE>.app-file <VAR>string</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX226"></A>
|
|
<A NAME="IDX227"></A>
|
|
<A NAME="IDX228"></A>
|
|
<CODE>.app-file</CODE>
|
|
(which may also be spelled <SAMP>`.file'</SAMP>)
|
|
tells <CODE></CODE> that we are about to start a new
|
|
logical file. <VAR>string</VAR> is the new file name. In general, the
|
|
filename is recognized whether or not it is surrounded by quotes <SAMP>`"'</SAMP>;
|
|
but if you wish to specify an empty file name is permitted,
|
|
you must give the quotes--<CODE>""</CODE>. This statement may go away in
|
|
future: it is only recognized to be compatible with old <CODE></CODE>
|
|
programs.
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC65" HREF="#TOC65"><CODE>.ascii "<VAR>string</VAR>"</CODE>...</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX229"></A>
|
|
<A NAME="IDX230"></A>
|
|
<CODE>.ascii</CODE> expects zero or more string literals (see section <A HREF="#SEC31">Strings</A>)
|
|
separated by commas. It assembles each string (with no automatic
|
|
trailing zero byte) into consecutive addresses.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC66" HREF="#TOC66"><CODE>.asciz "<VAR>string</VAR>"</CODE>...</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX231"></A>
|
|
<A NAME="IDX232"></A>
|
|
<A NAME="IDX233"></A>
|
|
<CODE>.asciz</CODE> is just like <CODE>.ascii</CODE>, but each string is followed by
|
|
a zero byte. The "z" in <SAMP>`.asciz'</SAMP> stands for "zero".
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC67" HREF="#TOC67"><CODE>.balign[wl] <VAR>abs-expr</VAR>, <VAR>abs-expr</VAR>, <VAR>abs-expr</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX234"></A>
|
|
<A NAME="IDX235"></A>
|
|
Pad the location counter (in the current subsection) to a particular
|
|
storage boundary. The first expression (which must be absolute) is the
|
|
alignment request in bytes. For example <SAMP>`.balign 8'</SAMP> advances
|
|
the location counter until it is a multiple of 8. If the location counter
|
|
is already a multiple of 8, no change is needed.
|
|
|
|
</P>
|
|
<P>
|
|
The second expression (also absolute) gives the fill value to be stored in the
|
|
padding bytes. It (and the comma) may be omitted. If it is omitted, the
|
|
padding bytes are normally zero. However, on some systems, if the section is
|
|
marked as containing code and the fill value is omitted, the space is filled
|
|
with no-op instructions.
|
|
|
|
</P>
|
|
<P>
|
|
The third expression is also absolute, and is also optional. If it is present,
|
|
it is the maximum number of bytes that should be skipped by this alignment
|
|
directive. If doing the alignment would require skipping more bytes than the
|
|
specified maximum, then the alignment is not done at all. You can omit the
|
|
fill value (the second argument) entirely by simply using two commas after the
|
|
required alignment; this can be useful if you want the alignment to be filled
|
|
with no-op instructions when appropriate.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX236"></A>
|
|
<A NAME="IDX237"></A>
|
|
The <CODE>.balignw</CODE> and <CODE>.balignl</CODE> directives are variants of the
|
|
<CODE>.balign</CODE> directive. The <CODE>.balignw</CODE> directive treats the fill
|
|
pattern as a two byte word value. The <CODE>.balignl</CODE> directives treats the
|
|
fill pattern as a four byte longword value. For example, <CODE>.balignw
|
|
4,0x368d</CODE> will align to a multiple of 4. If it skips two bytes, they will be
|
|
filled in with the value 0x368d (the exact placement of the bytes depends upon
|
|
the endianness of the processor). If it skips 1 or 3 bytes, the fill value is
|
|
undefined.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC68" HREF="#TOC68"><CODE>.byte <VAR>expressions</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX238"></A>
|
|
<A NAME="IDX239"></A>
|
|
<CODE>.byte</CODE> expects zero or more expressions, separated by commas.
|
|
Each expression is assembled into the next byte.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC69" HREF="#TOC69"><CODE>.comm <VAR>symbol</VAR> , <VAR>length</VAR> </CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX240"></A>
|
|
<A NAME="IDX241"></A>
|
|
<CODE>.comm</CODE> declares a common symbol named <VAR>symbol</VAR>. When linking, a
|
|
common symbol in one object file may be merged with a defined or common symbol
|
|
of the same name in another object file. If <CODE></CODE> does not see a
|
|
definition for the symbol--just one or more common symbols--then it will
|
|
allocate <VAR>length</VAR> bytes of uninitialized memory. <VAR>length</VAR> must be an
|
|
absolute expression. If <CODE></CODE> sees multiple common symbols with
|
|
the same name, and they do not all have the same size, it will allocate space
|
|
using the largest size.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC70" HREF="#TOC70"><CODE>.data <VAR>subsection</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX242"></A>
|
|
<CODE>.data</CODE> tells <CODE></CODE> to assemble the following statements onto the
|
|
end of the data subsection numbered <VAR>subsection</VAR> (which is an
|
|
absolute expression). If <VAR>subsection</VAR> is omitted, it defaults
|
|
to zero.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC71" HREF="#TOC71"><CODE>.double <VAR>flonums</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX243"></A>
|
|
<A NAME="IDX244"></A>
|
|
<CODE>.double</CODE> expects zero or more flonums, separated by commas. It
|
|
assembles floating point numbers.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC72" HREF="#TOC72"><CODE>.eject</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX245"></A>
|
|
<A NAME="IDX246"></A>
|
|
<A NAME="IDX247"></A>
|
|
<A NAME="IDX248"></A>
|
|
Force a page break at this point, when generating assembly listings.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC73" HREF="#TOC73"><CODE>.else</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX249"></A>
|
|
<CODE>.else</CODE> is part of the <CODE></CODE> support for conditional
|
|
assembly; see section <A HREF="#SEC85"><CODE>.if <VAR>absolute expression</CODE></VAR></A>. It marks the beginning of a section
|
|
of code to be assembled if the condition for the preceding <CODE>.if</CODE>
|
|
was false.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC74" HREF="#TOC74"><CODE>.endif</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX250"></A>
|
|
<CODE>.endif</CODE> is part of the <CODE></CODE> support for conditional assembly;
|
|
it marks the end of a block of code that is only assembled
|
|
conditionally. See section <A HREF="#SEC85"><CODE>.if <VAR>absolute expression</CODE></VAR></A>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC75" HREF="#TOC75"><CODE>.equ <VAR>symbol</VAR>, <VAR>expression</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX251"></A>
|
|
<A NAME="IDX252"></A>
|
|
<A NAME="IDX253"></A>
|
|
This directive sets the value of <VAR>symbol</VAR> to <VAR>expression</VAR>.
|
|
It is synonymous with <SAMP>`.set'</SAMP>; see section <A HREF="#SEC108"><CODE>.set <VAR>symbol</CODE>, <VAR>expression</VAR></VAR></A>.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC76" HREF="#TOC76"><CODE>.equiv <VAR>symbol</VAR>, <VAR>expression</VAR></CODE></A></H2>
|
|
<P>
|
|
<A NAME="IDX254"></A>
|
|
The <CODE>.equiv</CODE> directive is like <CODE>.equ</CODE> and <CODE>.set</CODE>, except that
|
|
the assembler will signal an error if <VAR>symbol</VAR> is already defined.
|
|
|
|
</P>
|
|
<P>
|
|
Except for the contents of the error message, this is roughly equivalent to
|
|
|
|
<PRE>
|
|
.ifdef SYM
|
|
.err
|
|
.endif
|
|
.equ SYM,VAL
|
|
</PRE>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC77" HREF="#TOC77"><CODE>.err</CODE></A></H2>
|
|
<P>
|
|
<A NAME="IDX255"></A>
|
|
If <CODE></CODE> assembles a <CODE>.err</CODE> directive, it will print an error
|
|
message and, unless the <CODE>-Z</CODE> option was used, it will not generate an
|
|
object file. This can be used to signal error an conditionally compiled code.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC78" HREF="#TOC78"><CODE>.extern</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX256"></A>
|
|
<CODE>.extern</CODE> is accepted in the source program--for compatibility
|
|
with other assemblers--but it is ignored. <CODE></CODE> treats
|
|
all undefined symbols as external.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC79" HREF="#TOC79"><CODE>.file <VAR>string</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX257"></A>
|
|
<A NAME="IDX258"></A>
|
|
<A NAME="IDX259"></A>
|
|
<CODE>.file</CODE> (which may also be spelled <SAMP>`.app-file'</SAMP>) tells
|
|
<CODE></CODE> that we are about to start a new logical file.
|
|
<VAR>string</VAR> is the new file name. In general, the filename is
|
|
recognized whether or not it is surrounded by quotes <SAMP>`"'</SAMP>; but if
|
|
you wish to specify an empty file name, you must give the
|
|
quotes--<CODE>""</CODE>. This statement may go away in future: it is only
|
|
recognized to be compatible with old <CODE></CODE> programs.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC80" HREF="#TOC80"><CODE>.fill <VAR>repeat</VAR> , <VAR>size</VAR> , <VAR>value</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX260"></A>
|
|
<A NAME="IDX261"></A>
|
|
<A NAME="IDX262"></A>
|
|
<VAR>result</VAR>, <VAR>size</VAR> and <VAR>value</VAR> are absolute expressions.
|
|
This emits <VAR>repeat</VAR> copies of <VAR>size</VAR> bytes. <VAR>Repeat</VAR>
|
|
may be zero or more. <VAR>Size</VAR> may be zero or more, but if it is
|
|
more than 8, then it is deemed to have the value 8, compatible with
|
|
other people's assemblers. The contents of each <VAR>repeat</VAR> bytes
|
|
is taken from an 8-byte number. The highest order 4 bytes are
|
|
zero. The lowest order 4 bytes are <VAR>value</VAR> rendered in the
|
|
byte-order of an integer on the computer <CODE></CODE> is assembling for.
|
|
Each <VAR>size</VAR> bytes in a repetition is taken from the lowest order
|
|
<VAR>size</VAR> bytes of this number. Again, this bizarre behavior is
|
|
compatible with other people's assemblers.
|
|
|
|
</P>
|
|
<P>
|
|
<VAR>size</VAR> and <VAR>value</VAR> are optional.
|
|
If the second comma and <VAR>value</VAR> are absent, <VAR>value</VAR> is
|
|
assumed zero. If the first comma and following tokens are absent,
|
|
<VAR>size</VAR> is assumed to be 1.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC81" HREF="#TOC81"><CODE>.float <VAR>flonums</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX263"></A>
|
|
<A NAME="IDX264"></A>
|
|
This directive assembles zero or more flonums, separated by commas. It
|
|
has the same effect as <CODE>.single</CODE>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC82" HREF="#TOC82"><CODE>.global <VAR>symbol</VAR></CODE>, <CODE>.globl <VAR>symbol</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX265"></A>
|
|
<A NAME="IDX266"></A>
|
|
<CODE>.global</CODE> makes the symbol visible to <CODE></CODE>. If you define
|
|
<VAR>symbol</VAR> in your partial program, its value is made available to
|
|
other partial programs that are linked with it. Otherwise,
|
|
<VAR>symbol</VAR> takes its attributes from a symbol of the same name
|
|
from another file linked into the same program.
|
|
|
|
</P>
|
|
<P>
|
|
Both spellings (<SAMP>`.globl'</SAMP> and <SAMP>`.global'</SAMP>) are accepted, for
|
|
compatibility with other assemblers.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC83" HREF="#TOC83"><CODE>.hword <VAR>expressions</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX267"></A>
|
|
<A NAME="IDX268"></A>
|
|
<A NAME="IDX269"></A>
|
|
<A NAME="IDX270"></A>
|
|
This expects zero or more <VAR>expressions</VAR>, and emits
|
|
a 16 bit number for each.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC84" HREF="#TOC84"><CODE>.ident</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX271"></A>
|
|
This directive is used by some assemblers to place tags in object files.
|
|
<CODE></CODE> simply accepts the directive for source-file
|
|
compatibility with such assemblers, but does not actually emit anything
|
|
for it.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC85" HREF="#TOC85"><CODE>.if <VAR>absolute expression</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX272"></A>
|
|
<A NAME="IDX273"></A>
|
|
<CODE>.if</CODE> marks the beginning of a section of code which is only
|
|
considered part of the source program being assembled if the argument
|
|
(which must be an <VAR>absolute expression</VAR>) is non-zero. The end of
|
|
the conditional section of code must be marked by <CODE>.endif</CODE>
|
|
(see section <A HREF="#SEC74"><CODE>.endif</CODE></A>); optionally, you may include code for the
|
|
alternative condition, flagged by <CODE>.else</CODE> (see section <A HREF="#SEC73"><CODE>.else</CODE></A>).
|
|
|
|
</P>
|
|
<P>
|
|
The following variants of <CODE>.if</CODE> are also supported:
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>.ifdef <VAR>symbol</VAR></CODE>
|
|
<DD>
|
|
<A NAME="IDX274"></A>
|
|
|
|
Assembles the following section of code if the specified <VAR>symbol</VAR>
|
|
has been defined.
|
|
|
|
<A NAME="IDX275"></A>
|
|
<A NAME="IDX276"></A>
|
|
<DT><CODE>.ifndef <VAR>symbol</VAR></CODE>
|
|
<DD>
|
|
<DT><CODE>.ifnotdef <VAR>symbol</VAR></CODE>
|
|
<DD>
|
|
Assembles the following section of code if the specified <VAR>symbol</VAR>
|
|
has not been defined. Both spelling variants are equivalent.
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC86" HREF="#TOC86"><CODE>.include "<VAR>file</VAR>"</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX277"></A>
|
|
<A NAME="IDX278"></A>
|
|
<A NAME="IDX279"></A>
|
|
This directive provides a way to include supporting files at specified
|
|
points in your source program. The code from <VAR>file</VAR> is assembled as
|
|
if it followed the point of the <CODE>.include</CODE>; when the end of the
|
|
included file is reached, assembly of the original file continues. You
|
|
can control the search paths used with the <SAMP>`-I'</SAMP> command-line option
|
|
(see section <A HREF="#SEC9">Command-Line Options</A>). Quotation marks are required
|
|
around <VAR>file</VAR>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC87" HREF="#TOC87"><CODE>.int <VAR>expressions</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX280"></A>
|
|
<A NAME="IDX281"></A>
|
|
Expect zero or more <VAR>expressions</VAR>, of any section, separated by commas.
|
|
For each expression, emit a number that, at run time, is the value of that
|
|
expression. The byte order and bit size of the number depends on what kind
|
|
of target the assembly is for.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC88" HREF="#TOC88"><CODE>.irp <VAR>symbol</VAR>,<VAR>values</VAR></CODE>...</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX282"></A>
|
|
Evaluate a sequence of statements assigning different values to <VAR>symbol</VAR>.
|
|
The sequence of statements starts at the <CODE>.irp</CODE> directive, and is
|
|
terminated by an <CODE>.endr</CODE> directive. For each <VAR>value</VAR>, <VAR>symbol</VAR> is
|
|
set to <VAR>value</VAR>, and the sequence of statements is assembled. If no
|
|
<VAR>value</VAR> is listed, the sequence of statements is assembled once, with
|
|
<VAR>symbol</VAR> set to the null string. To refer to <VAR>symbol</VAR> within the
|
|
sequence of statements, use <VAR>\symbol</VAR>.
|
|
|
|
</P>
|
|
<P>
|
|
For example, assembling
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
.irp param,1,2,3
|
|
move d\param,sp@-
|
|
.endr
|
|
</PRE>
|
|
|
|
<P>
|
|
is equivalent to assembling
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
move d1,sp@-
|
|
move d2,sp@-
|
|
move d3,sp@-
|
|
</PRE>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC89" HREF="#TOC89"><CODE>.irpc <VAR>symbol</VAR>,<VAR>values</VAR></CODE>...</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX283"></A>
|
|
Evaluate a sequence of statements assigning different values to <VAR>symbol</VAR>.
|
|
The sequence of statements starts at the <CODE>.irpc</CODE> directive, and is
|
|
terminated by an <CODE>.endr</CODE> directive. For each character in <VAR>value</VAR>,
|
|
<VAR>symbol</VAR> is set to the character, and the sequence of statements is
|
|
assembled. If no <VAR>value</VAR> is listed, the sequence of statements is
|
|
assembled once, with <VAR>symbol</VAR> set to the null string. To refer to
|
|
<VAR>symbol</VAR> within the sequence of statements, use <VAR>\symbol</VAR>.
|
|
|
|
</P>
|
|
<P>
|
|
For example, assembling
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
.irpc param,123
|
|
move d\param,sp@-
|
|
.endr
|
|
</PRE>
|
|
|
|
<P>
|
|
is equivalent to assembling
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
move d1,sp@-
|
|
move d2,sp@-
|
|
move d3,sp@-
|
|
</PRE>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC90" HREF="#TOC90"><CODE>.lcomm <VAR>symbol</VAR> , <VAR>length</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX284"></A>
|
|
<A NAME="IDX285"></A>
|
|
<A NAME="IDX286"></A>
|
|
Reserve <VAR>length</VAR> (an absolute expression) bytes for a local common
|
|
denoted by <VAR>symbol</VAR>. The section and value of <VAR>symbol</VAR> are
|
|
those of the new local common. The addresses are allocated in the bss
|
|
section, so that at run-time the bytes start off zeroed. <VAR>Symbol</VAR>
|
|
is not declared global (see section <A HREF="#SEC82"><CODE>.global <VAR>symbol</CODE></VAR>, <CODE>.globl <VAR>symbol</CODE></VAR></A>), so is normally
|
|
not visible to <CODE></CODE>.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC91" HREF="#TOC91"><CODE>.lflags</CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX287"></A>
|
|
<CODE></CODE> accepts this directive, for compatibility with other
|
|
assemblers, but ignores it.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC92" HREF="#TOC92"><CODE>.line <VAR>line-number</VAR></CODE></A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX288"></A>
|
|
<A NAME="IDX289"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Even though this is a directive associated with the <CODE>a.out</CODE> or
|
|
<CODE>b.out</CODE> object-code formats, <CODE></CODE> still recognizes it
|
|
when producing COFF output, and treats <SAMP>`.line'</SAMP> as though it
|
|
were the COFF <SAMP>`.ln'</SAMP> <EM>if</EM> it is found outside a
|
|
<CODE>.def</CODE>/<CODE>.endef</CODE> pair.
|
|
|
|
</P>
|
|
<P>
|
|
Inside a <CODE>.def</CODE>, <SAMP>`.line'</SAMP> is, instead, one of the directives
|
|
used by compilers to generate auxiliary symbol information for
|
|
debugging.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC93" HREF="#TOC93"><CODE>.linkonce [<VAR>type</VAR>]</CODE></A></H2>
|
|
<P>
|
|
<A NAME="IDX290"></A>
|
|
<A NAME="IDX291"></A>
|
|
<A NAME="IDX292"></A>
|
|
Mark the current section so that the linker only includes a single copy of it.
|
|
This may be used to include the same section in several different object files,
|
|
but ensure that the linker will only include it once in the final output file.
|
|
The <CODE>.linkonce</CODE> pse
|