as_en.tex

万能汇编工具

Since this manual is not also meant as a user's manual for the processor
families supported by AS, this is unfortunately not the place to enumerate
all possible attributes for all families.  It should however be mentioned
that in general, not all instructions of a given instruction set allow all
attributes and that the omission of an attribute generally leads to the
usage of the ''natural'' operand size of a processor family. For more
thorough studies, consult a reasonable programmer's manual, e.g.
\cite{Williams} for the 68K's.

In the case of TLCS-9000, H8/500, and M16(C), the attribute serves
both as an operand size specifier (if it is not obvious from the
operands) and as a description of the instruction format to be used. 
A colon has to be used to separate the format from the operand size,
e.g. like this:
\begin{verbatim}
    add.w:g   rw10,rw8
\end{verbatim}
This example does not show that there may be a format specification
without an operand size.  In contrast, if an operand size is used
without a format specification, AS will automatically use the
shortest possible format.  The allowed formats and operand sizes
again depend on the machine instruction and may be looked up e.g. in
\cite{Tosh900}, \cite{HitH8_5}, \cite{MitM16}, resp. \cite{MitM16C}.

The number of instruction parameters depends on the mnemonic and is 
principally located between 0 and 20.  The separation of the parameters 
from each other is to be performed only by commas (exception: DSP56xxx, 
its parallel data transfers are separated with blanks).  Commas that 
are included in brackets or quotes, of course, are not taken into 
consideration.  

Instead of a comment at the end, the whole line can consist of 
comment if it starts in the first column with a semicolon.

To separate the individual components you may also use tabulators
instead of spaces.

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

\section{Format of the Listing}

The listing produced by AS using the command line options i or I is 
roughly divisible into the following parts :
\begin{enumerate}
\item{issue of the source code assembled;}
\item{symbol list;}
\item{usage list;}
\item{cross reference list.}
\end{enumerate}
The two last ones are only generated if they have been demanded by 
additional command line options.

In the first part, AS lists the complete contents of all source files 
including the produced code.  A line of this listing has the following 
form:
\begin{verbatim}
[<n>] <line>/<address> <code> <source>
\end{verbatim}
In the field \tty{n}, AS displays the include nesting level.  The main file 
(the file where assembly was started) has the depth 0, an included 
file from there has depth 1 etc..  Depth 0 is not displayed.

In the field \tty{line}, the source line number of the referenced file is 
issued. The first line of a file has the number 1.  The address at 
which the code generated from this line is written follows after the 
slash in the field \tty{address}.

The code produced is written behind \tty{address} in the field \tty{code}, 
in hexadecimal notation. Depending on the processor type and actual 
segment the values are formatted either as bytes or 16/32-bit-words.
If more code is generated than the field can take, additional lines
will be  generated, in which case only this field is used.

Finally, in the field \tty{source}, the line of the source file is issued in 
its original form.

The symbol table was designed in a way that it can be displayed on an
80-column display whenever possible. For symbols of ''normal length'',
a double column output is used.  If symbols exceed (with their name
and value) the limit of 40 columns (characters), they will be issued
in a separate line. The output is done in alphabetical order. 
Symbols that have been defined but were never used are marked with a
star (*) as prefix.

The parts mentioned so far as well as the list of all macros/functions 
defined can be selectively masked out from the listing. 
This can be done by the already mentioned command line switch \tty{-t}. 
There is an internal byte inside AS whose bits represent which parts 
are to be written.  The assignment of bits to parts of the listing is
listed in table \ref{TabTBits}.
\par
\begin{table*}[htb]
\begin{center}\begin{tabular}{|l|l|}
\hline
bit &  part \\
\hline
\hline
0   & source file(s) + produced code \\
1   & symbol table \\
2   & macro list \\
3   & function list \\
4   & line numbering \\
5   & register symbol list \\
7   & character set table \\
\hline
\end{tabular}\end{center}
\caption{Assignment of Bits to Listing Components\label{TabTBits}}
\end{table*}
All bits are set to 1 by default, when using the switch
\begin{verbatim}
-t <mask>
\end{verbatim}
Bits set in \tty{$<$mask$>$} are cleared, so that the respective listing 
parts are suppressed.  Accordingly it is possible to switch on single 
parts again with a plus sign, in case you had switched off too much 
with the \tty{ASCMD} variable... If someone wants to have, for example, 
only the symbol table, it is enough to write:
\begin{verbatim}
-t 2  
\end{verbatim}
The usage list issues the occupied areas hexadecimally for every 
single segment.  If the area has only one address, only this is written, 
otherwise the first and last address.

The cross reference list issues any defined symbol in alphabetical 
order and has the following form:
\begin{verbatim}
 symbol <symbol name> (=<value>,<file>/<line>): 
  file <file 1>:
  <n1>[(m1)]  ..... <nk>[(mk)]
  .
  .
  file <file l>:
  <n1>[(m1)]  ..... <nk>[(mk)]
\end{verbatim}
The cross reference list lists for every symbol in which files and lines
it has been used.  If a symbol was used several times in the same line,
this would be indicated by a number in brackets behind the line number. 
If a symbol was never used, it would not appear in the list; The same is
true for a file that does not contain any references for the symbol in
question.

\bb{CAUTION!}  AS can only print the listing correctly if it was
previously informed about the output media's page length and width! 
This has to be done with the \tty{PAGE} instruction (see there).  The
preset default is a length of 60 lines and an unlimited line width.

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

\section{Symbol Conventions}
\label{SectSymConv}

Symbols are allowed to be up to 255 characters long (as hinted already 
in the introduction) and are being distinguished on the whole 
length, but the symbol names have to meet some conventions:
 
Symbol names are allowed to consist of a random combination of 
letters, digits, underlines and dots, whereby the first character must 
not be a digit. The dot is only allowed to meet the MCS-51 notation of 
register bits and should - as far as possible - not be used in own symbol 
names.  To separate symbol names in any case the underline (\tty{\_}) and not 
the dot (\tty{.}) should be used .

AS is by default not case-sensitive, i.e. it does not matter whether
one uses upper or lower case characters.  The command line switch \tty{U}
however allows to switch AS into a mode where upper and lower case
makes a difference.  The predefined symbol \tty{CASESENSITIVE} signifies
whether AS has been switched to this mode: TRUE means case-sensitiveness,
and FALSE its absence.

Table \ref{TabPredefined} shows the most important symbols which are 
predefined by AS.
\begin{table*}[htb]
\begin{center}\begin{tabular}{|l|l|}
\hline
name          & meaning \\
\hline
\hline
TRUE          & logically ''true'' \\
FALSE         & logically ''false'' \\
CONSTPI       & Pi (3.1415.....) \\
VERSION       & version of AS in BCD-coding, \\
              & e.g. 1331 hex for version 1.33p1 \\
ARCHITECTURE  & target platform AS was compiled for, in \\
              & the style processor-manufacturer-operating \\
              & system \\
DATE          & date and \\
TIME          & time of the assembly (start) \\
MOMCPU        & current target CPU \\
              & (see the CPU instruction) \\
MOMFILE       & current source file \\
MOMLINE       & line number in source file \\
MOMPASS       & number of the currently running pass \\
MOMSECTION    & name of the current section \\
              & or an empty string \\
\verb!*!, \$ resp. PC & current value of program counter \\
\hline
\end{tabular}\end{center}
\caption{Predefined Symbols\label{TabPredefined}}
\end{table*}
\bb{CAUTION!}  While it does not matter in case-sensitive mode which
combination of upper and lower case to use to reference predefined
symbols, one has to use exactly the version given above (only upper
case) when AS is in case-sensitive mode!

Additionally some pseudo instructions define symbols that reflect the
value that has been set  with these instructions.  Their descriptions
are explained at the individual commands belonging to them.

A hidden feature (that has to be used with care) is that symbol names
may be assembled from the contents of string symbols.  This can be
achieved by framing the string symbol's name with braces and
inserting it into the new symbol's name.  This allows for example to
define a symbol's name based on the value of another symbol:
\begin{verbatim}
cnt             set     cnt+1
temp            equ     "\{CNT}"
                jnz     skip{temp}
                .
                .
skip{temp}:     nop
\end{verbatim}
\bb{CAUTION:} The programmer has to assure that only valid symbol names
are generated!

A complete list of all symbols predefined by AS can be found in
appendix \ref{AppInternSyms}.

Apart from its value, every symbol also owns a marker which signifies to
which {\em segment} it belongs.  Such a distinction is mainly needed for
processors that have more than one address space.  The additional
information allows AS to issue a warning when a wrong instruction is used
to access a symbol from a certain address space.  A segment attribute is
automatically added to a symbol when is gets defined via a label or a
special instruction like \tty{BIT}; a symbol defined via the ''allround
instructions'' \tty{SET} resp. \tty{EQU} is however ''typeless'', i.e. its
usage will never trigger warnings.  A symbol's segment attribute may be
queried via the buit-in function \tty{SYMTYPE}, e.g.:
\begin{verbatim}
Label:
        .
        .
Attr    equ     symtype(Label)  ; results in 1
\end{verbatim}
The individual segment types have the assigned numbers listed in table
\ref{TabSegNums}.  Register symbols which do not really fit into the order
of normal symbols are explained in section \ref{SectRegSyms}.  The
\tty{SYMTYPE} function delivers -1 as result when called with an undefined
symbol as argument.
\begin{table}[htb]
\begin{center}
\begin{tabular}{|l|c|}
\hline      
segment & return value \\
\hline      
$<$none$>$ & 0 \\
CODE & 1 \\ 
DATA & 2 \\                                       
IDATA & 3 \\
XDATA & 4 \\                                      
YDATA & 5 \\                                      
BITDATA & 6 \\
IO & 7 \\
REG & 8 \\                                        
ROMDATA & 9 \\
$<$register symbol$>$ & 128 \\                     
\hline                                            
\end{tabular}                                     
\end{center}                                      
\caption{return values of the \tty{SYMTYPE} function\label{TabSegNums}}
\end{table}

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

\section{Temporary Symbols}

Especially when dealing with programs that contain sequences of loops of
if-like statements, one is continuously faced with the problem of
inventing new names for labels - labels of which you know exactly that you
will never need to reference them again afterwards and you really would
like to get 'rid' of them somehow.  A simple solution if you don't want to
swing the large hammer of sections (see chapter \ref{ChapLocSyms}) are
{\em temporary} symbols which remain valid as long as a new,
non-temporary symbol gets defined.  Othe assemblers offer a similar
mechanism which is commnoly referred as 'local symbols'; however, for the
sake of a better distinction, I want to stay with the term 'temporary
symbols'.  AS distinguishes between two types of temporary symbols, {\em
named} and {\em nameless} symbols:

\section{Named Temporary Symbols}

A symbol whose name starts with two dollar signs (something that is
neither allowed for non-temporary symbols nor for constants) is a named
temporary symbol.  AS keeps an internal counter which is reset to 0 before
assembly begins and which gets incremented upon every