as_en.tex

万能汇编工具

STDDEF62.INC      & register addresses and Makros ST6 \\
STDDEF75.INC      & register addresses 75K0 \\
\hline
\end{tabular}\end{center}
\caption{Standard Contents of a Binary Distribution - Part 2
         \label{TabCommonPackageList2}}
\end{table*}
\begin{table*}[htp]
\begin{center}\begin{tabular}{|l|l|}
\hline
File              & Function \\
\hline
\hline
{\bf Directory INCLUDE} & \\
\hline
STDDEF87.INC      & register and memory addresses TLCS-870 \\
STDDEF90.INC      & register and memory addresses TLCS-90 \\
STDDEF96.INC      & register and memory addresses TLCS-900 \\
STDDEFXA.INC      & SFR and bit addresses Philips XA \\
STDDEFZ8.INC      & register addresses Z8 family \\
\hline
\hline
{\bf Directory LIB} & \\
\hline
\hline
{\bf Directory MAN} & \\
\hline
ASL.1             & quick reference for AS \\
PLIST.1           & quick reference for PLIST \\
PBIND.1           & quick reference for PBIND \\
P2HEX.1           & quick reference for P2HEX \\
P2BIN.1           & quick reference for P2BIN \\
\hline
\end{tabular}\end{center}
\caption{Standard Contents of a Binary Distribution - Part 3
         \label{TabCommonPackageList3}}
\end{table*}


Depending on the platform, a binary distribution however may contain more
files to allow operation, like files necessary for DOS extenders. In case
of the DOS DPMI version \marginpar{{\em DPMI}}, the extensions listed in
table \ref{TabDPMIPackageList} result.  Just to mention it: it is
perfectly O.K. to replace the tools with their counterparts from a DOS
binary distribution; on the on hand, they execute significantly faster
without the extender's overhead, and on the other hand, they do not need
the extended memory provided by the extender.

\begin{table*}[htp]
\begin{center}\begin{tabular}{|l|l|}
\hline
File              & Function \\
\hline
\hline
{\bf Directory BIN} & \\
\hline
DPMI16BI.OVL   & DPMI server for the assembler \\
RTM.EXE        & runtime module of the extender \\
\hline
\end{tabular}\end{center}
\caption{Additional Files in a DPMI Binary Distribution
         \label{TabDPMIPackageList}}
\end{table*}

An OS/2 binary distribution \marginpar{{\em OS/2}} contains in addition to
the base files a set of DLLs belonging to the runtime environment of the
emx compiler used to build AS (table \ref{TabOS2PackageList}).  In case
you already have these DLLs (or newer versions of them), you may delete
these and use your ones insted.

\begin{table*}[htp]
\begin{center}\begin{tabular}{|l|l|}
\hline
File              & function \\
\hline
\hline
{\bf Directory BIN} & \\
\hline
EMX.DLL           & runtime libraries for AS and \\
EMXIO.DLL         & its tools \\
EMXLIBC.DLL       & \\
EMXWRAP.DLL       & \\
\hline
\end{tabular}\end{center}
\caption{Additional Files in an OS/2 binary distribution
         \label{TabOS2PackageList}}
\end{table*}

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

\section{Installation}

There is no need for a \marginpar{{\em DOS}} special installation prior to
usage of AS.  It is sufficient to unpack the archive in a fitting place
and to add a few minor settings.  For example, this is an installation a
user used to UNIX-like operating systems might choose:

Create a directory \verb!c:\as! an (I will assume in the following that
you are going to install AS on drive C), change to this directory and
unpack the archiv, keeping the path names stored in the archive (when
using PKUNZIP, the command line option \verb!-d! is necessary for that).
You now should have the following directory tree:
\begin{verbatim}
c:\as
c:\as\bin
c:\as\include
c:\as\lib
c:\as\man
c:\as\doc
c:\as\demos
\end{verbatim}
Now, append the directory \verb!c:\as\bin! to the \tty{PATH} statement in
your \tty{AUTOEXEC.BAT}, which allows the system to find AS and its tools.
With your favourite text editor, create a file named \tty{AS.RC} in the
\tty{lib} directory with the following contents:
\begin{verbatim}
-i c:\as\include
\end{verbatim}  
This so-called {\em key file} tells AS where to search for its include
files.  The following statement must be added to your \tty{AUTOEXEC.BAT}
to tell AS to read this file:
\begin{verbatim}
set ASCMD=@c:\as\lib\as.rc
\end{verbatim}
There are many more things you can preset via the key file; they are
listed in the following section.

The installation of the DPMI version \marginpar{{\em DPMI}} should
principally take the same course as for the pure DOS version; as soon as
the PATH contains the {\tt bin} directory, the DOS extender's files will
be found automatically and you should not notice anything of this
mechanism (except for the longer startup time...).  When working on an
80286-based computer, it is theoretically possible tha you get confronted
with the following message upon the first start:
\begin{verbatim}
  machine not in database (run DPMIINST)
\end{verbatim}
Since the DPMIINST tool ins not any more included in newer versions of
Borland's DOS extender, I suppose that this is not an item any more...in
case you run into this, contact me!

The installation of the OS/2 version \marginpar{{\em OS/2}} can generally
be done just like for the DOS version, with the addition that the DLLs
have to be made visible for the operating system. In case you do not want
to extend the {\tt LIBPATH} entry in your {\tt CONFIG.SYS}, it is of
course also valid to move the DLLs into a directory already listed in {\tt
LIBPATH}.

As already mentioned, the installation instructions in this section limit
themselves to binary distributions.  Since an installation under Unix
\marginpar{{\em UNIX}} is currently alway a source-based installation, the
only hint I can give here is a reference to appendix \ref{ChapSource}.

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

\section{Start-Up Command, Parameters}
\label{SectCallConvention}

AS is a command line driven program, i.e. all parameters and file
options are to be given in the command line.  

A couple of message files belongs to AS (recognizable by their suffix {\tt
MSG}) AS accesses to dynamically load the messages appropriate for the
national language.  AS searches the following directories for these files:
\begin{itemize}
\item{the current directory;}
\item{the EXE-file's directory;}
\item{the directory named in the {\tt AS\_MSGPATH} environment variable,
      or alternitavely the directories listed in the {\tt PATH} environment
      variable;}
\item{the directory compiled into AS via the {\tt LIBDIR} macro.}
\end{itemize}
These files are {\em indispensable} for a proper operation of AS, i.e. AS
will terminate immediately if these files are not found.

The language selection (currently only German and English) is based on the
{\tt COUNTRY} setting under DOS and OS/2 respectively on the {\tt LANG}
environment variable under Unix.

In order to fulfill \marginpar{{\em DOS}} AS's memory requirements under
DOS, the various code generator modules of the DOS version were moved into
an overlay which is part of the EXE file.  A separate OVR file like in
earlier versions of AS therefore dose not exist any more, AS will however 
still attempt to reduce the overlaying delays by using eventually
available EMS or XMS memory.  In case this results in
trouble, you may suppress usage of EMS or XMS by setting the environment
variable \tty{USEXMS} or \tty{USEEMS} to \tty{n}.  E.g., it is possible to
suppress the using of XMS by the command:
\begin{verbatim}
   SET USEXMS=n
\end{verbatim}
Since AS performs all in- and output via the operating system (and
therefore it should run also on not 100\% compatible DOS-PC's) and
needs some basic display control, it emits ANSI control sequences
during the assembly.  
In case you \marginpar{{\em DOS/}} should see strange characters in the
messages displayed by AS, your \tty{CONFIG.SYS} is obviously lacking a
line like this:
\begin{verbatim}
   device=ansi.sys 
\end{verbatim}
but the further \marginpar{{\em DPMI}} functions of AS will not be
influenced hereby.  Alternatively you are able to suppress the output of
ANSI sequences completely by setting the environment variable
\tty{USEANSI} to \tty{n}.

The DOS extender of the DPMI version \marginpar{{\em DPMI}} can be
influenced in its memory allocation strategies by a couple of environment
variables; if you need to know their settings, you may look up them in the
file \tty{DPMIUSER.DOC}.  ASX is additionally able to extend the available
memory by a swap file.  To do this, set up an environment variable
\tty{ASXSWAP} in the following way:
\begin{verbatim}
  SET ASXSWAP=<size>[,file name]
\end{verbatim}
The size specification has to be done in megabytes and \bb{has} to be done.
The file name in contrast is optional; if it is missing, the file is
named \tty{ASX.TMP} and placed in the current directory.  In any case, the
swap file is deleted after program end.

The command line parameters can roughly be divided into three categories:
switches, key file references (see below) and file specifications. 
Parameters of these two categories may be arbitrarily mixed in the command
line.  The assembler evaluates at first all parameters and then assembles
the specified files.  From this follow two things:
\begin{itemize}
\item{the specified switches affect all specified source files. If 
      several source files shall be assembled with different switches,
      this has to be done in separate runs.}
\item{it is possible to assemble more than one file in one shot and to 
      bring it to the top, it is allowed that the file specs contain 
      wildcards.}
\end{itemize}
Parameter switches are recognized by AS by starting with 
a slash (/) or hyphen (-).  There are switches that are only one
character long and additionally switches composed of a whole word. 
Whenever AS cannot interpret a switch as a whole word, it tries to
interprete every letter as an individual switch.  For example, if you
write 
\begin{verbatim}
 -queit
\end{verbatim}
instead of
\begin{verbatim}
 -quiet
\end{verbatim}
AS will take the letters \tty{q, u, e, i}, and \tty{t} as individual
switches.  Multiple-letter switches additionally have the difference to
single-letter switches that AS will accept an arbitrary mixture of upper
and lower casing, whereas single-letter switches may have a different
meaning depending on whether upper or lower case is used.

At the moment, the following switches are defined:
\ttindex{SHARED}
\begin{itemize}
\item{\tty{l}: sends assembler listing to console terminal (mostly screen).  
      In case several passes have to be done, the listing of all 
      passes will be send to the console (in opposite to the next
      option).}
\item{\tty{L}: writes assembler listing into a file. The list file will get
      the same name as the source file, only the extension is 
      replaced by \tty{LST}.  Except one uses... }
\item{\tty{OLIST}: with a fiel name as argument allows to redirect the
      listing to a different file or a different path.  This option may
      be used multiple times in case multiple files are assembled with
      one execution.}
\item{\tty{o}: Sets the new name of the code file generated by AS.  If this 
      option is used multiple times, the names will be assigned, one
      after the other, to the source files which have to be
      assembled.  A negation (see below) of this option in
      connection with a name erases this name from the list.  A
      negation without a name erases the whole list.}
\item{\tty{SHAREOUT}:ditto for a SHARE file eventually to be created.}
\item{\tty{c}: SHARED-variables will be written in a format which permits 
      an easy integration into a C-source file.  The extension of 
      the file is \tty{H}.}
\item{\tty{p}: SHARED-variables will be written in a format which permits 
      easy integration into the CONST-block of a Pascal program. 
      The extension of the file is \tty{INC}.}
\item{\tty{a}: SHARED-variables will be written in a format which permits 
      easy integration into an assembler source file. The 
      extension of the file is \tty{INC}.}
\end{itemize}
Concerning effect and function of the SHARED-symbols please see 
chapters \ref{ChapShareMain} resp. \ref{ChapShareOrder}.
\begin{itemize}
\item{\tty{g [format]}: 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}), a
      NoICE-compatible command file ({\tt format=NOICE}), and the Atmel
      format used by the AVR tools ({\tt format=ATMEL}). 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
      \ref{SectDebugFormat}  The file's extension is \tty{MAP}, \tty{NOI},