as_en.tex

万能汇编工具

\item{Intel 80x86, 80186, Nec V30\&V35 incl. coprocessor 8087}
\end{itemize}
The switch to a different code generator is allowed even within one 
file, and as often as one wants!

The reason for this flexibility is that AS has a history, which may also
be recognized by looking at the version number. AS was created as an
extension of a macro assembler for the 68000 family. On special request, I
extended the original assembler so that it was able to translate 8051
mnemonics.  On this way (decline ?!) from the 68000 to 8051, some other
processors were created as by-products.  All others were added over time
due to user requests.  So At least for the processor-independent core of
AS, one may assume that it is well-tested and free of obvious bugs. 
However, I often do not have the chance to test a new code generator in
practice (due to lack of appropriate hardware), so surprises are not
impossible when working with new features.  You see, the things stated in
section \ref{SectLicense} have a reason...

This flexibility implies a somewhat exotic code format, therefore I
added some tools to work with it. Their description can be found in
chapter \ref{ChapTools}.

AS is a macro assembler, which means that the programmer has the
possibility to define new ''commands'' by means of macros. 
Additionally it masters conditional assembling.  Labels inside macros
are automatically processed as being local.

For the assembler, symbols may have either integer, string or floating
point values.  These will be stored - like interim values in formulas -
with a width of 32 bits for integer values, 80 or 64 bits for floating
point values, and 255 characters for strings.  For a couple of micro
controllers, there is the possibility to classify symbols by segmentation.
So the assembler has a (limited) possibility to recognize accesses to
wrong address spaces.

The assembler does not know explicit limits in the nesting depth of 
include files or macros; a limit is only given by the program stack 
restricting the recursion depth.  Nor is there a limit for the 
symbol length, which is only restricted by the maximum line length. 

From version 1.38 on, AS is a multipass-assembler.  This pompous term
means no more than the fact that the number of passes through the
source code need not be exactly two. If the source code does not
contain any forward references, AS needs only one pass.  In case AS
recognizes in the second pass that it must use a shorter or longer
instruction coding, it needs a third (fourth, fifth...) pass to
process all symbol references correctly. There is nothing more behind
the term ''multipass'', so it will not be used further more in this
documentation.

After so much praise a bitter pill: AS cannot generate linkable code. 
An extension with a linker needs considerable effort and is not planned 
at the moment.

Those who want to take a look at the sources of AS can simply get the 
Unix version of AS, which comes as source for self-compiling.  The sources
are definitely not in a format that is targeted at easy understanding -
the original Pascal version still raises its head at a couple of places,
and I do not share a couple of common opinions about 'good' C coding.

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

\section{Supported Platforms}

Though AS started as a pure DOS \marginpar{{\em DOS}} program, there are a
couple of versions available that are able to exploit a bit more than the
Real Mode of an Intel CPU.  Their usage is kept as compatible to the DOS
version as possible, but there are of course differences concerning
installation and embedding into the operating system in question. 
Sections in this manual that are only valid for a specific version of AS
are marked with a corresponding sidemark (at this paragraph for the DOS
version) aheaded to the paragraph.  In detail, the following further
versions exist (distributed as separate packages):

In case you run \marginpar{{\em DPMI}}into memory problems when assembling
large and complex programs under DOS, there is a DOS version that runs in
protected mode via a DOS extender and can therefore make use of the whole
extended memory of an AT.  The assembly becomes significantly slower by
the extender, but at least it works...

There is a native OS/2 \marginpar{{\em OS/2}} version of AS for friends of
IBM's OS/2 operating system.  Since version 1.41r8, this is a full 32-bit
OS/2 application, which of course means that OS/2 2.x and at least an
80386 CPU are mandatory.  

You can leave \marginpar{{\em UNIX}} the area of PCs-only with the C
version of AS that was designed to be compilable on a large number of UNIX
systems (this includes OS/2 with the emx compiler) without too much of
tweaking.  In contrast to the previously mentioned versions, the C version
is delivered in source code, i.e. one has to create the binaries by
oneself using a C compiler.  This is by far the simpler way (for me) than
providing a dozen of precompiled binaries for machines I sometimes only
have limited access to...

People who have read \marginpar{{\em ???}} this enumeration up to this
point will notice that world's best-selling operating system coming from
Redmont is missing in this enumeration.  People who know me personally
will know that I do not regard Windows to be a pat solution (regardless if
its 3.X, 95, or NT).  Frankly said, I am a 'windows hater'.  A large
number of people will now regard this to be somewhere between obsolete and
ridiculous, and they will tell me that I withhold AS from a large part of
potential users, but they will have to live with it: I primarily continue
to improve AS because I have fun doing it; AS is a non-commercial project
and I therefore take the freedom not to look at potential market shares.  I
select platforms for me where I have fun programming, and I definitely do
not have any fun when programming for Windows!  By the way, there was a
time when I had to write Windows programs so I do not simply jabber
without having an idea what I am talking about.  If someone wants to port
AS into this direction, I will not stand in his way, but (s)he should not
expect anything more from me than providing sources (which is why (s)he
will have to deal with questions like 'why does AS not work any more after
I changed the JUNK-CAD 18.53 registry entry from upper to lower case?').

%%===========================================================================

\cleardoublepage
\chapter{Assembler Usage}

\begin{quote}\begin{raggedright}{\it
Scotty: Captain, we din\verb!'! can reference it! \\
Kirk:   Analysis, Mr. Spock? \\
Spock:  Captain, it doesn\verb!'!t appear in the symbol table. \\
Kirk:   Then it\verb!'!s of external origin? \\
Spock:  Affirmative. \\
Kirk:   Mr. Sulu, go to pass two. \\
Sulu:   Aye aye, sir, going to pass two. \\
}\end{raggedright}\end{quote}

%%---------------------------------------------------------------------------
      
\section{Hardware Requirements}

The hardware requirements of AS vary substantially from version to
version:

The DOS version \marginpar{{\em DOS}} will principally run on any
IBM-compatible PC, ranging from a PC/XT with 4-dot-little megahertz up to
a Pentium.  However, similar to other programs, the fun using AS increases
the better your hardware is.  An XT user without a hard drive will
probably have significant trouble placing the overlay file on a floppy
because it is larger than 500 Kbytes...the PC should therefore have at
least a hard drive, allowing acceptable loading times.  AS is not very
advanced in its main memory needs: the program itself allocates less than
300 Kbytes main memory, AS should therefore work on machines with at least
512 Kbytes of memory.

The version of AS \marginpar{{\em DPMI}} compiled for the DOS Protected
Mode Interface (DPMI) requires at least 1 Mbyte of free extended memory. 
A total memory capacity of at least 2 Mbytes is therefore the absolute
minimum given one does not have other tools in the XMS (like disk caches,
RAM disks, or a hi-loaded DOS); the needs will rise then appropriately. 
If one uses the DPMI version in a DOS box of OS/2, one has to assure that
DPMI has been enabled via the box's DOS settings (set to \tty{on} or
\tty{auto}) and that a sufficient amount of XMS memory has been assigned
to the box.  The virtual memory management of OS/2 will free you
from thinking about the amount of free real memory.

The hardware requirements of the OS/2 \marginpar{{\em OS/2}} version
mainly result from the needs of the underlying operating system, i.e. at
minimum an 80386SX processor, 8 Mbytes of RAM (resp. 4 Mbytes without the
graphical user interface) and 100..150 Mbytes of hard disk space.  AS2 is
only a 16-bit application and therefore it should also work on older OS/2
versions (thereby reducing the processor needs to at least an 80286
processor); I had however no chance to test this.

The C version of AS \marginpar{{\em UNIX}} is delivered as source code and
therefore requires a UNIX or OS/2 system equipped with a C compiler.  The
compiler has to fulfill the ANSI standard (GNU-C for example is
ANSI-compliant).  You can look up in the \tty{README} file whether your
UNIX system has already been tested so that the necessary definitions have
been made.  You should reserve about 15 Mbytes of free hard disk space for
compilation; this value (and the amount needed after compilation to store
the compiled programs) strongly differs from system to system, so you
should take this value only as a rough approximation.

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

\section{Delivery}

Principally, you can obtain AS in one of two forms: as a {\em binary} or a
{\em source} distribution.  In case of a binary distribution, one gets AS,
the accomanying tools and auxiliary files readily compiled, so you can
immediately start to use it after unpacking the archive to the desired
destination on your hard drive.
Binary distibutions are made for widespread platforms, where either the
majority of users does not have a compiler or the compilation is tricky
(currently, this includes DOS and OS/2).  A source distribution in
contrast contains the complete set of C sources to generate AS; it is
ultimately a snapshot of the source tree I use for development on AS.  The
generation of AS from the sources and their structure is described in
detail in appendix \ref{ChapSource}, which is why at this place, only the
contents and installation of a binary distribution will be described:

The contents of the archive is separated into several subdirectories,
therefore you get a directory subtree immediately after unpacking without
having to sort out things manually.  The individual directories contain
the following groups of files:
\begin{itemize}
\item{{\tt BIN}: executable programs, text resources;}
\item{{\tt INCLUDE}: include files for assembler programs, e.g. register
      definitions or standard macros;}
\item{{\tt MAN}: quick references for the individual programs in Unix
      'man' format.}
\end{itemize}
A list of the files found in every binary distribution is given in tables
\ref{TabCommonPackageList1} to \ref{TabCommonPackageList3}.  In case a
file listed in one of these (or the following) tables is missing, someone
took a nap during copying (probably me)...

\begin{table*}[htp]
\begin{center}\begin{tabular}{|l|l|}
\hline
File              & function \\
\hline
\hline
{\bf Directory BIN} & \\
\hline
AS.EXE            & executable of assembler \\
PLIST.EXE         & lists contents of code files \\
PBIND.EXE         & merges code files \\
P2HEX.EXE         & converts code files to hex files \\
P2BIN.EXE         & converts code files to binary files \\
AS.MSG            & text resources for AS \\
PLIST.MSG         & text resources for PLIST \\
PBIND.MSG         & text resources for PBIND \\
P2HEX.MSG         & text resources for P2HEX \\
P2BIN.MSG         & text resources for P2BIN \\
TOOLS.MSG         & common text resources for all tools \\
CMDARG.MSG        & common text resources for all programs \\
IOERRS.MSG        & \\
\hline
\hline
{\bf Directory DOC} & \\
\hline
AS\_DE.DOC        & german documentation, ASCII format \\
AS\_DE.HTML       & german documentation, HTML format \\
AS\_DE.TEX        & german documentation, LaTeX format \\
AS\_EN.DOC        & english documentation, ASCII format \\
AS\_EN.HTML       & english documentation, HTML format \\
AS\_EN.TEX        & english documentation, LaTeX format \\
\hline
\hline
{\bf Directory INCLUDE} & \\
\hline
BITFUNCS.INC      & functions for bit manipulation \\
CTYPE.INC         & functions for classification of \\
                  & characters \\
80C50X.INC        & register addresses SAB C50x \\
80C552.INC        & register addresses 80C552 \\
H8\_3048.INC      & register addresses H8/3048 \\
REG166.INC        & addresses and instruction macros 80C166/167 \\
REG251.INC        & addresses and bits 80C251 \\
REG29K.INC        & peripheral addresses AMD 2924x \\
\hline
\end{tabular}\end{center}
\caption{Standard Contents of a Binary Distribution - Part 1
         \label{TabCommonPackageList1}}
\end{table*}
\begin{table*}[htp]
\begin{center}\begin{tabular}{|l|l|}
\hline
File              & Function \\
\hline
\hline
{\bf Directory INCLUDE} & \\
\hline
REG53X.INC        & register addresses H8/53x \\
REG683XX.INC      & register addresses 68332/68340/68360 \\
REG7000.INC       & register addresses TMS70Cxx \\
REG78K0.INC       & register addresses 78K0 \\
REG96.INC         & register addresses MCS-96 \\
REGACE.INC        & register addresses ACE \\
REGAVR.INC        & register and bit addresses AVR family \\
REGCOP8.INC       & register addresses COP8 \\
REGGP32.INC       & register addresses 68HC908GP32 \\
REGHC12.INC       & register addresses 68HC12 \\
REGM16C.INC       & register addresses Mitsubishi M16C \\
REGMSP.INC        & register addresses TI MSP430 \\
REGST9.INC        & register and Makrodefinitionen ST9 \\
REGZ380.INC       & register addresses Z380 \\
STDDEF04.INC      & register addresses 6804 \\
STDDEF16.INC      & instruction macros and register addresses \\
                  & PIC16C5x \\
STDDEF17.INC      & register addresses PIC17C4x \\
STDDEF18.INC      & register addresses PIC16C8x \\
STDDEF2X.INC      & register addresses TMS3202x \\
STDDEF37.INC      & register and bit addresses TMS370xxx \\
STDDEF3X.INC      & peripheral addresses TMS320C3x \\
STDDEF47.INC      & instruction macros TLCS-47 \\
STDDEF51.INC      & definition of SFRs and bits for \\
                  & 8051/8052/80515 \\
STDDEF56K.INC     & register addresses DSP56000 \\
STDDEF5X.INC      & peripheral addresses TMS320C5x \\
STDDEF60.INC      & instruction macros and register addresses \\
                  & PowerPC \\