as_en.html

万能汇编工具

<UL>
<LI> <TT>g [format]</TT>: This switch instructs AS to create an
    additional file that contains debug information for the program.
    Allowed formats are the AS-specific MAP format (<TT>
    format=MAP</TT>), a NoICE-compatible command file (<TT>
    format=NOICE</TT>), and the Atmel format used by the AVR tools
    (<TT> format=ATMEL</TT>). The information stored in the MAP
    format is comprised of a symbol table and a table describing the
    assignment of source lines to machine addresses. A more detailed
    description of the MAP format can be found in section <A
    HREF="#ref_SectDebugFormat">5.2</A> The file's extension is<TT>
    MAP</TT>,<TT> NOI</TT>, resp.<TT> OBJ</TT>, depending on the
    chosen format. If no explicit format specification is done, the
    MAP format is chosen.</LI>
<LI> <TT>noicemask [value]</TT>: By default, AS lists only symbols from
    the CODE segment in NoICE debug info files. With this option and
    an integer value interpreted as a bit mask, symbols fom other
    segments may be added. The assignment of segments to bit
    positions may be taken from table <A
    HREF="#ref_TabSegmentNums">5.2</A>.</LI>
<LI> <TT>w</TT>: suppress issue of warnings;</LI>
<LI> <TT>E [file]</TT>: error messages and warnings produced by AS will
    be redirected to a file. Instead of a file, the 5 standard
    handles (STDIN..STDPRN) can also be specified as<TT> !0</TT>
    to<TT> !4</TT> . Default is<TT> !2</TT>, meaning STDERR. If the
    file option is left out, the name of the error file is the same
    as of the source file, but with the extension<TT> LOG</TT>.</LI>
<LI> <TT>q</TT>: This switch suppresses all messages of AS, the
    exceptions are error messages and outputs which are are forced
    from the source file. The time needed for assembly is slightly
    reduced hereby and if you call AS from a shell there is no
    redirection required. The disadvantage is that you may ''stay in
    the dark'' for several minutes ... It is valid to write<TT>
    quiet</TT> instead of<TT> q</TT>.</LI>
<LI> <TT>h</TT>: write hexadecimal numbers in lowercase instead of
    capital letters. This option is primarily a question of personal
    taste.</LI>
<LI> <TT>i &lt;path list&gt;</TT>: issues a list of directories where the
    assembler shall automatically search for include files, in case
    it didn't find a file in the current directory. The different
    directories have to be separated by semicolons.</LI>
<LI> <TT>u</TT>: calculate a list of areas which are occupied in the
    segments. This option is effective only in case a listing is
    produced. This option requires considerable additional memory and
    computing performance. In normal operation it should be switched
    off.</LI>
<LI> <TT>C</TT>: generates a list of cross references. It lists which
    (global) symbols are used in files and lines. This list will also
    be generated only in case a listing is produced. This option
    occupies, too, additional memory capacity during assembly.</LI>
<LI> <TT>s</TT>: issues a list of all sections (see chapter <A
    HREF="#ref_ChapLocSyms">3.8</A>). The nesting is indicated by
    indentations (Pascal like).</LI>
<LI> <TT>t</TT>: by means of this switch it is possible to separate
    single components of the standard issued assembler-listing. The
    assignment of bits to parts can be found in the next section,
    where the exact format of the assembly listing is explained.</LI>
<LI> <TT>D</TT>: defines symbols. The symbols which are specified behind
    this option and separated by commas are written to the global
    symbol table before starting the assembly. As default these
    symbols are written as integer numbers with the value TRUE, by
    means of an appended equal sign, however, you can select other
    values. The expression following the equals sign may include
    operators or internal functions, but<B> not</B> any further
    symbols, even if these should have been defined before in the
    list! Together with the commands for conditional assembly (see
    there) you may produce different program versions out of one
    source file by command line inputs.<B> CAUTION!</B> If the
    case-sensitive mode is used, this has to be specified in the
    command line<EM> before</EM> any symbol definitions, otherwise
    symbol names will be converted to upper case at this place!</LI>
<LI> <TT>A</TT>: stores the list of global symbols in another, more
    compact form. Use this option if the assembler crashes with a
    stack overflow because of too long symbol tables. Sometimes this
    option can increase the processing speed of the assembler, but
    this depends on the sources.</LI>
<LI> <TT>x</TT>: Sets the level of detail for error messages. The level
    is increased resp. decreased by one each time this option is
    given. While on level 0 (default) only the error message itself
    is printed, an extended message is added beginning at level 1
    that should simplify the identification of the error's cause.
    Appendix <A HREF="#ref_ChapErrMess">A</A> lists which error
    messages carry which extended messages. At level 2 (maximum), the
    source line containing the error is additionally printed.</LI>
<LI> <TT>n</TT>: If this option is set, the error messages will be issued
    additionally with their error number (see appendix <A
    HREF="#ref_ChapErrMess">A</A>). This is primarily intended for
    use with shells or IDE's to make the identification of errors
    easier by those numbers.</LI>
<LI> <TT>U</TT>: This option switches AS to the case-sensitive mode, i.e.
    upper and lower case in the names of symbols, sections, macros,
    character sets, and user-defined functions will be distinguished.
    This is not the case by default.</LI>
<LI> <TT>P</TT>: Instructs AS to write the source text processed by macro
    processor and conditional assembly into a file. Additional blank
    and pure comment lines are missing in this file. The extension of
    this file is<TT> I</TT>.</LI>
<LI> <TT>M</TT>: If this switch is given, AS generates a file, that
    contains definitions of macros defined in the source file that
    did not use the<TT> NOEXPORT</TT> option. This new file has the
    same name as the source file, only the extension is modified
    into<TT> MAC</TT>.</LI>
<LI> <TT>G</TT>: this switch defines whether AS should produce code or
    not. If switched off, the processing will be stopped after the
    macro processor. This switch is activated by default (logically,
    otherwise you would not get a code file). This switch can be used
    in conjunction with the<TT> P</TT> switch, if only the macro
    processor of AS shall be used.</LI>
<LI> <TT>r [n]</TT>: issue warnings if situations occur that force a
    further pass. This information can be used to reduce the number
    of passes. You may optionally specify the number of the first
    pass where issuing of such messages shall start. Without this
    argument, warnings will come starting with the first pass. Be
    prepared for a bunch of messages!!</LI>
<LI> <TT>cpu &lt;name&gt;</TT>: this switch allows to set the target
    processor AS shall generate code for, in case the source file
    does not contain a<TT> CPU</TT> instruction and is not 68008
    code.</LI>
<LI> <TT>alias &lt;new&gt;=&lt;old&gt;</TT>: defines the processor
    type<TT> &lt;new&gt;</TT> to be an alias for the type<TT>
    &lt;old&gt;</TT>. See section <A HREF="#ref_SectAlias">2.14</A>
    for the sense of processor aliases.</LI>
<LI> <TT> gnuerrors</TT>: display messages about errors resp. warnings
    not in the As standard format, but instaed in a format similar to
    the GNU C compiler. This simplifies the integration of AS into
    environments tuned for this format, however also suppresses the
    display of precise error positions in macro bodies!</LI>
</UL>
As long as switches require no arguments and their concatenation does
not result in a multi-letter switch, it is possible to specify
several switches at one time, as in the following example :
<PRE>

 as test*.asm firstprog -cl /i c:\as\8051\include

</PRE>
All files<TT> TEST*.ASM</TT> as well as the file<TT>
FIRSTPROG.ASM</TT> will be assembled, whereby listings of all files
are displayed on the console terminal. Additional sharefiles will be
generated in the C- format. The assembler should search for
additional include files in the directory C:\AS\8051\INCLUDE.
<P>
This example shows that the assembler assumes<TT> ASM</TT> as the
default extension for source files.
<P>
A bit of caution should be applied when using switches that have
optional arguments: if a file specification immediately follows such
aswitch without the optional argument, AS will try to interprete the
file specification as argument - what of course fails:
<PRE>

 as -g test.asm

</PRE>
The solution in this case would either be to move the -g option the
end or to specify an explicit MAP argument.
<P>
Beside from specifying options in the command line, permanently
needed options may be placed in the environment variable<TT>
ASCMD</TT>. For example, if someone always wants to have assembly
listings and has a fixed directory for include files, he can save a
lot of typing with the following command:
<PRE>

 set ascmd=-L -i c:\as\8051\include

</PRE>
The environment options are processed before the command line, so
options in the command line can override contradicting ones in the
environment variable.
<P>
In the case of very long path names, space in the<TT> ASCMD</TT>
variable may become a problem. For such cases a key file may be the
alternative, in which the options can be written in the same way as
in the command line or the<TT> ASCMD</TT>-variable. But this file may
contain several lines each with a maximum length of 255 characters.
In a key file it is important, that for options which require an
argument, switches and argument have to be written in the<B> same</B>
line. AS gets informed of the name of the key file by a<TT> @</TT>
aheaded in the<TT> ASCMD</TT> variable, e.g.
<PRE>

set ASCMD=@c:\as\as.key

</PRE>
In order to neutralize options in the<TT> ASCMD</TT> variable (or in
the key file), prefix the option with a plus sign. For example, if
you do not want to generate an assembly listing in an individual
case, the option can be retracted in this way:
<PRE>

as +L &lt;file&gt;

</PRE>
Naturally it is not consequently logical to deny an option by a plus
sign.... UNIX soit qui mal y pense.
<P>
References to key files may not only come from the<TT> ASCMD</TT>
variable, but also directly from the command line. Similarly to
the<TT> ASCMD</TT> variable, prepend the file's name with a @
character:
<PRE>
 
 as @&lt;file&gt; ....

</PRE>
The options read from a key file in this situation are processed as
if they had been written out in the command line in place of the
reference,<EM> not</EM> like the key file referenced by the<TT>
ASCMD</TT> variable that is processed prior to the command line
options.
<P>
Referencing a key file from a key file itself is not allowed and will
be answered wit an error message by AS.
<P>
In case that you like to start AS from another program or a shell and
this shell hands over only lower-case or capital letters in the
command line, the following workaround exists: if a tilde (~) is put
in front of an option letter, the following letter is always
interpreted as a lower-case letter. Similarly a<TT> #</TT> demands
the interpretation as a capital letter. For example, the following
transformations result for:
<PRE>

 /~I ---&gt; /i
 -#u ---&gt; -U

</PRE>
In dependence of the assembly's outcome, the assembler ends with the
following return codes:
<DL COMPACT>
<DT>0<DD>error free run, at maximum warnings occurred</DD>
<DT>1<DD>The assembler displayed only its command-line parameters and
    terminated immediately afterwards.</DD>
<DT>2<DD>Errors occurred during assembly, no code file has been produced.</DD>
<DT>3<DD>A fatal error occurred what led to immediate termination of the
    run.</DD>
<DT>4<DD>An error occurred already while starting the assembler. This may be a
    parameter error or a faulty overlay file.</DD>
<DT>255<DD>An internal error occurred during initialization that should not
    occur in any case...reboot, try again, and contact me if the
    problem is reproducible!</DD>
</DL>
Similar to UNIX, OS/2 extends an application's data segment on demand    
when the application really needs the memory. Therefore, an output
like
<PRE>

  511 KByte available memory

</PRE>
does not indicate a shortly to come system crash due to memory lack,
it simply shows the distance to the limit when OS/2 will push up the
data segment's size again...
<P>
As there is no compatible way in C under different operating systens     
to find out the amount of available memory resp. stack, both lines
are missing completely from the statistics the C version prints.
<P>

<H2><A NAME="sect_2_5_">2.5. Format of the Input Files</A></H2>
<A NAME="ref_AttrTypes"></A>
<P>
Like most assemblers, AS expects exactly one instruction per line
(blank lines are naturally allowed as well). The lines must not be
longer than 255 characters, additional characters are discarded.
<P>
A single line has following format:
<PRE>

[label[:]] &lt;mnemonic&gt;[.attr] [param[,param..]] [;comment]

</PRE>
A line may also be split over several lines in the source file,
continuation characters chain these parts together to a single line.
One must however consider that, due to the internal buffer structure,
the total line must not be longer than 256 characters. Line
references in error messages always relate to the last line of such a
composed source line.
<P>
The colon for the label is optional, in case the label starts in the
first column (the consequence is that a mnemonic must not start in
column 1). It is necessary to set the colon in case the label does
not start in the first column so that AS is able to distinguish it
from a mnemonic. In the latter case, there must be at least one space
between colon and mnemonic if the processor belongs to a family that
supports an attribute that denotes an instruction format and is
separated from the mnemonic by a colon. This restriction is necessary
to avoid ambiguities: a distinction between a mnemonic with format
and a label with mnemonic would otherwise be impossible.
<P>
Some signal processor families from Texas Instruments optionally use
a double line (||) in place of the label to signify the prallel
execution with the previous instruction(s). If these two assembler
instructions become a single instruction word at machine level (C3x),
an additional label in front of the second instruction of course does
not make sense and is not allowed. The situation is different for the
C6x with its instruction packets of variable length: If someone wants
to jump into the middle of an instruction packet (bad style, if you
ask me...), he has to place the necessary label<EM> before</EM> into
a separate line. The same is valid for conditions, which however may
be combined with the double line in a single source line.
<P>
The attribute is used by a couple of processors to specify variations
or different codings of a certain instruction. The most prominent
usage of the attibute is is the specification of the operand size,
for example in the case of the 680x0 family (table <A
HREF="#ref_TabAttrs">2.6</A>).

<CENTER>
<P><CENTER><TABLE SUMMARY="No Summary" BORDER=1 CELLPADDING=5>
<TR ALIGN=LEFT>
<TH VALIGN=TOP NOWRAP ALIGN=LEFT>attribute<