as_en.doc

万能汇编工具

  - National Semiconductor INS807x
  - National Semiconductor COP8
  - National Semiconductor SC144xx
  - Fairchild ACE
  - NEC 鍼D 78(C)1x
  - NEC 鍼D 75xxx (alias 75K0)
  - NEC 鍼D 78xxx (alias 78K0)
  - NEC 鍼D7720/7725
  - NEC 鍼D77230
  - Symbios Logic SYM53C8xx (yes, they are programmable!)
  - Fujitsu F齅C8L
  - Fujitsu F齅C16L
  - Intersil CDP1802/1805

under work / planned / in consideration :

  - NEC 78K4
  - Intel 8008
  - Texas Instruments TMS320C54x
  - Analog Devices ADSP21xx
  - SGS-Thomson ST20
  - Texas Instruments TMS320C4x
  - Texas Instruments TMS320C8x
  - Toshiba TC9331

I'm  currently searching  for documentation  about the  following fami-
lies:

  - the complete set of OKI controllers

unloved, but now, however, present :

  - Intel 80x86, 80186, Nec V30&V35 incl. coprocessor 8087

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 proces-
sor-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 hard-
ware),  so  surprises  are  not  impossible  when working with new fea-
tures. You see, the things stated in section 1.1 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 6.

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

For  the assembler, symbols  may have either  integer, string or float-
ing  point values. These will be stored - like interim values in formu-
las  - 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 recog-
nize 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 con-
tain  any forward references, AS needs only one pass. In case AS recog-
nizes  in the second pass that it must use a shorter or longer instruc-
tion  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 documenta-
tion.

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 under-
standing  - the original Pascal version still raises its head at a cou-
ple  of places, and  I do not  share a couple  of common opinions about
'good' C coding.


        1.3. Supported Platforms
        ------------------------

Though  AS started as  a pure DOS  program, there are  a couple of ver-   DOS
sions  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. Sec-
tions  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 fur-
ther versions exist (distributed as separate packages):

In  case you runinto memory problems  when assembling large and complex   DPMI
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 ex-
tended  memory of an  AT. The assembly  becomes significantly slower by
the extender, but at least it works...

There  is a native OS/2 version of AS for friends of IBM's OS/2 operat-   OS/2
ing  system. Since version 1.41r8, this  is a full 32-bit OS/2 applica-
tion,  which of course  means that OS/2  2.x and at  least an 80386 CPU
are mandatory.

You  can leave the area  of PCs-only with the  C version of AS that was   UNIX
designed  to be compilable on a large  number of UNIX systems (this in-
cludes  OS/2 with  the emx  compiler) without  too much of tweaking. In
contrast  to the previously mentioned versions, the C version is deliv-
ered  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 pro-
viding  a dozen of  precompiled binaries for  machines I sometimes only
have limited access to...

People  who have  read 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 primar-
ily  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 po-
tential  market shares. I select platforms for me where I have fun pro-
gramming,  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 pro-
grams  so I do not simply jabber without having an idea what I am talk-
ing  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?').


        2. Assembler Usage
        ==================


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



        2.1. Hardware Requirements
        --------------------------

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

The  DOS version will  principally run on  any IBM-compatible PC, rang-   DOS
ing  from a PC/XT  with 4-dot-little megahertz  up to a Pentium. Howev-
er,  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 ad-
vanced  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  compiled  for  the  DOS  Protected Mode Interface   DPMI
(DPMI)  requires at least 1 Mbyte of free extended memory. A total mem-
ory  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 on or
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 version  mainly result from the   OS/2
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 ver-
sions  (thereby  reducing  the  processor  needs  to  at least an 80286
processor); I had however no chance to test this.

The  C version  of AS  is delivered  as source  code and  therefore re-   UNIX
quires  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  README file whether your UNIX sys-
tem  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 sys-
tem, so you should take this value only as a rough approximation.


        2.2. Delivery
        -------------

Principally,  you can obtain AS  in one of two  forms: as a binary or a
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 de-
sired  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 in-
cludes  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 appen-
dix  I, 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 directo-
ries contain the following groups of files:

  -  BIN: executable programs, text resources;
  -  INCLUDE:  include files for assembler programs, e.g. register def-
    initions or standard macros;
  -  MAN:  quick references for  the individual programs  in Unix 'man'
    format.

A  list of the files found in every binary distribution is given in ta-
bles  2.1 to 2.3. In case a file listed in one of these (or the follow-
ing)  tables is  missing, someone  took a  nap during copying (probably
me)...


 +-------------------+---------------------------------------------+
 | File              | function                                    |
 +-------------------+---------------------------------------------+
 +-------------------+---------------------------------------------+
 | Directory BIN     |                                             |
 +-------------------+---------------------------------------------+
 | 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        |                                             |
 +-------------------+---------------------------------------------+
 +-------------------+---------------------------------------------+
 | Directory DOC     |                                             |
 +-------------------+---------------------------------------------+
 | 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         |
 +-------------------+---------------------------------------------+
 +-------------------+---------------------------------------------+
 | Directory INCLUDE |                                             |
 +-------------------+---------------------------------------------+
 | 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              |
 +-------------------+---------------------------------------------+

Table 2.1: Standard Contents of a Binary Distribution - Part 1


  +-------------------+-------------------------------------------+
  | File              | Function                                  |
  +-------------------+-------------------------------------------+
  +-------------------+-------------------------------------------+
  | Directory INCLUDE |                                           |
  +-------------------+-------------------------------------------+
  | 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                                   |
  | STDDEF62.INC      | register addresses and Makros ST6         |
  | STDDEF75.INC      | register addresses 75K0                   |
  +-------------------+-------------------------------------------+

Table 2.2: Standard Contents of a Binary Distribution - Part 2


    +-------------------+----------------------------------------+
    | File              | Function                               |
    +-------------------+----------------------------------------+
    +-------------------+----------------------------------------+
    | Directory INCLUDE |                                        |
    +-------------------+----------------------------------------+
    | 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           |