as_en.tex

万能汇编工具

      resp. \tty{OBJ}, depending on the chosen format.  If no explicit
      format specification is done, the MAP format is chosen.}
\item{\tty{noicemask [value]}: 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 \ref{TabSegmentNums}.}
\item{\tty{w}: suppress issue of warnings;}
\item{\tty{E [file]}: 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 
      \tty{!0} to \tty{!4} . Default is \tty{!2}, 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 \tty{LOG}.}
\item{\tty{q}: 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 \tty{quiet} instead
      of \tty{q}.}
\item{\tty{h}: write hexadecimal numbers in lowercase instead of capital
      letters. This option is primarily a question of personal
      taste.}
\item{\tty{i $<$path list$>$}: 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.}
\item{\tty{u}: 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.}
\item{\tty{C}: 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.}
\item{\tty{s}: issues a list of all sections (see chapter
      \ref{ChapLocSyms}).  The nesting is indicated  by indentations
      (Pascal like).}
\item{\tty{t}: 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.}
\item{\tty{D}: 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 \bb{not}
      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. {\bf CAUTION!} If the case-sensitive mode is used, this has
      to be specified in the command line {\em before} any symbol
      definitions, otherwise symbol names will be converted to upper
      case at this place!}
\item{\tty{A}: 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.}
\item{\tty{x}: 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
      \ref{ChapErrMess} lists which error messages carry which extended
      messages.  At level 2 (maximum), the source line containing the
      error is additionally printed.}
\item{\tty{n}: If this option is set, the error messages will be issued 
      additionally with their error number (see appendix
      \ref{ChapErrMess}).  This is primarily intended for use with shells
      or IDE's to make the identification of errors easier by those
      numbers.}
\item{\tty{U}: 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.}
\item{\tty{P}: 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 \tty{I}.}
\item{\tty{M}: If this switch is given, AS generates a file, that contains 
      definitions of macros defined in the source file that did not
      use the \tty{NOEXPORT} option.  This new file has the same name as
      the source file, only the extension is modified into \tty{MAC}.}
\item{\tty{G}: 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 \tty{P} switch, if only the macro
      processor of AS shall be used.}
\item{\tty{r [n]}: 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!!}
\item{\tty{cpu $<$name$>$}: this switch allows to set the target processor
      AS shall generate code for, in case the source file does not contain 
      a {\tt CPU} instruction and is not 68008 code.}
\item{\tty{alias $<$new$>$=$<$old$>$}:
      defines the processor type \tty{$<$new$>$} to be an alias for the
      type \tty{$<$old$>$}.  See section \ref{SectAlias} for the sense of
      processor aliases.}
\item{{\tt gnuerrors}: 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!}
\end{itemize}
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 :
\begin{verbatim}
 as test*.asm firstprog -cl /i c:\as\8051\include
\end{verbatim}
All files \tty{TEST*.ASM} as well as the file \tty{FIRSTPROG.ASM} 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 \verb!C:\AS\8051\INCLUDE!.

This example shows that the assembler assumes \tty{ASM} as the default 
extension for source files.

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:
\begin{verbatim}
 as -g test.asm
\end{verbatim}
The solution in this case would either be to move the -g option the  
end or to specify an explicit MAP argument.


Beside from specifying options in the command line, permanently
needed options may be placed in the environment variable \tty{ASCMD}.  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:
\begin{verbatim}
 set ascmd=-L -i c:\as\8051\include
\end{verbatim}
The environment options are processed before the command line,
so options in the command line can override contradicting ones in the
environment variable.

In the case of very long path names, space in the \tty{ASCMD} 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 \tty{ASCMD}-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 \bb{same} line.  AS gets informed of
the name of the key file by a \tty{@} aheaded in the \tty{ASCMD} variable,
e.g.
\begin{verbatim}
set ASCMD=@c:\as\as.key
\end{verbatim}
In order to neutralize options in the \tty{ASCMD} 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:
\begin{verbatim}
as +L <file>
\end{verbatim}
Naturally it is not consequently logical to deny an option by a 
plus sign....  UNIX soit qui mal y pense.

References to key files may not only come from the {\tt ASCMD} variable,
but also directly from the command line.  Similarly to the {\tt ASCMD}
variable, prepend the file's name with a \@ character:
\begin{verbatim} 
 as @<file> ....
\end{verbatim}
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} like the key file referenced by the {\tt ASCMD} variable that is
processed prior to the command line options.

Referencing a key file from a key file itself is not allowed and will be
answered wit an error message by AS.

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 (\verb!~!) is put
in front of an option letter, the following letter is always
interpreted as a lower-case letter.  Similarly a \tty{\#} demands the
interpretation as a capital letter.  For example, the following
transformations result for:
\begin{verbatim}
 /~I ---> /i
 -#u ---> -U
\end{verbatim}
In dependence of the assembly's outcome, the assembler ends with
the following return codes:
\begin{description}
\item[0]{error free run, at maximum warnings occurred}
\item[1]{The assembler displayed only its command-line parameters and 
         terminated immediately afterwards.}
\item[2]{Errors occurred during assembly, no code file has been produced.}
\item[3]{A fatal error occurred what led to immediate termination of the run.}
\item[4]{An error occurred already while starting the assembler.
         This may be a parameter error or a faulty overlay file.}
\item[255]{An internal error occurred during initialization that should not
         occur in any case...reboot, try again, and contact me if the
         problem is reproducible!}
\end{description}
Similar to UNIX, OS/2 \marginpar{{\em OS/2}} extends an application's data
segment on demand when the application really needs the memory. 
Therefore, an output like
\begin{verbatim}
  511 KByte available memory
\end{verbatim}
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...

As there is no compatible way in C \marginpar{{\em UNIX}} 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.

%%---------------------------------------------------------------------------

\section{Format of the Input Files}
\label{AttrTypes}

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.

A single line has following format:
\begin{verbatim}
[label[:]] <mnemonic>[.attr] [param[,param..]] [;comment]
\end{verbatim}
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.
\par
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.

Some signal processor families from Texas Instruments optionally use a
double line (\verb!||!) 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} into a separate line.  The
same is valid for conditions, which however may be combined with the
double line in a single source line.

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 \ref{TabAttrs}).
\begin{table*}[htb]
\begin{center}\begin{tabular}{|l|l|l|}
\hline
attribute & arithmetic-logic instruction & jump instruction\\
\hline
\hline
B     & byte (8 bits)                       &  --------- \\
W     & word (16 bits)                      &  --------- \\
L     & long word (32 bits)                 &  16-bit-displacement \\
Q     & quad word (64 bits)                 &  --------- \\
S     & single precision (32 bits)          &  8-bit-displacement \\
D     & double precision (64 bits)          &  --------- \\
X     & extended precision (80/96 bits)     &  32-bit-displacement \\
P     & decimal floating point (80/96 bits) &  --------- \\
\hline
\end{tabular}\end{center}
\caption{Allowed Attributes (Example 680x0) \label{TabAttrs}}
\end{table*}
\par