as_en.doc

万能汇编工具

    +-------------------+----------------------------------------+
    +-------------------+----------------------------------------+
    | Directory LIB     |                                        |
    +-------------------+----------------------------------------+
    +-------------------+----------------------------------------+
    | Directory MAN     |                                        |
    +-------------------+----------------------------------------+
    | 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              |
    +-------------------+----------------------------------------+

Table 2.3: Standard Contents of a Binary Distribution - Part 3


Depending  on the platform,  a binary distribution  however may contain
more  files to  allow operation,  like files  necessary for  DOS exten-
ders.  In case of the DOS DPMI  version, the extensions listed in table   DPMI
2.4  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.


          +---------------+--------------------------------+
          | File          | Function                       |
          +---------------+--------------------------------+
          +---------------+--------------------------------+
          | Directory BIN |                                |
          +---------------+--------------------------------+
          | DPMI16BI.OVL  | DPMI server for the assembler  |
          | RTM.EXE       | runtime module of the extender |
          +---------------+--------------------------------+

Table 2.4: Additional Files in a DPMI Binary Distribution


An  OS/2 binary distribution  contains in addition  to the base files a   OS/2
set  of DLLs belonging  to the runtime  environment of the emx compiler
used  to build AS (table 2.5). In  case you already have these DLLs (or
newer  versions of them), you may delete  these and use your ones inst-
ed.


           +---------------+------------------------------+
           | File          | function                     |
           +---------------+------------------------------+
           +---------------+------------------------------+
           | Directory BIN |                              |
           +---------------+------------------------------+
           | EMX.DLL       | runtime libraries for AS and |
           | EMXIO.DLL     | its tools                    |
           | EMXLIBC.DLL   |                              |
           | EMXWRAP.DLL   |                              |
           +---------------+------------------------------+

Table 2.5: Additional Files in an OS/2 binary distribution



        2.3. Installation
        -----------------

There  is no need for  a special installation prior  to usage of AS. It   DOS
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 c:\as an  (I will assume in  the following that you
are  going to install AS on drive  C), change to this directory and un-
pack  the archiv,  keeping the  path names  stored in the archive (when
using  PKUNZIP, the command line option  -d is necessary for that). You
now should have the following directory tree:

c:\as
c:\as\bin
c:\as\include
c:\as\lib
c:\as\man
c:\as\doc
c:\as\demos

Now,  append the directory c:\as\bin to  the PATH statement in your AU-
TOEXEC.BAT,  which allows  the system  to find  AS and  its tools. With
your  favourite text editor, create  a file named AS.RC  in the lib di-
rectory with the following contents:

-i c:\as\include

This  so-called  key  file  tells  AS  where  to search for its include
files.  The following statement  must be added  to your AUTOEXEC.BAT to
tell AS to read this file:

set ASCMD=@c:\as\lib\as.rc

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  should principally take the same   DPMI
course  as for the pure  DOS version; as soon  as the PATH contains the
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:

  machine not in database (run DPMIINST)

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 can  generally be done just like   OS/2
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  LIBPATH entry in  your CONFIG.SYS, it  is of course  also valid to
move the DLLs into a directory already listed in LIBPATH.

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


        2.4. Start-Up Command, Parameters
        ---------------------------------

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

A  couple of message files belongs  to AS (recognizable by their suffix
MSG)  AS accesses to dynamically load  the messages appropriate for the
national  language.  AS  searches  the  following directories for these
files:

  - the current directory;
  - the EXE-file's directory;
  - the  directory named in the AS_MSGPATH environment variable, or al-
    ternitavely  the directories  listed in  the PATH environment vari-
    able;
  - the directory compiled into AS via the LIBDIR macro.

These  files are  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 COUNTRY setting under DOS and OS/2 respectively on the LANG en-
vironment variable under Unix.

In  order to  fulfill AS's  memory requirements  under DOS, the various   DOS
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
USEXMS  or USEEMS to n.  E.g., it is possible  to suppress the using of
XMS by the command:

   SET USEXMS=n

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 dur-
ing  the assembly.  In case  you should  see strange  characters in the   DOS/
messages  displayed by AS, your CONFIG.SYS  is obviously lacking a line
like this:

   device=ansi.sys 

but  the further functions of AS  will not be influenced hereby. Alter-   DPMI
natively  you are  able to  suppress the  output of ANSI sequences com-
pletely by setting the environment variable USEANSI to n.

The  DOS extender of the  DPMI version can be  influenced in its memory   DPMI
allocation  strategies  by  a  couple  of environment variables; if you
need  to know their settings, you may  look up them in the file DPMIUS-
ER.DOC.  ASX is additionally  able to extend  the available memory by a
swap  file. To do this,  set up an environment  variable ASXSWAP in the
following way:

  SET ASXSWAP=<size>[,file name]

The  size  specification  has  to  be  done  in megabytes and has to be
done.  The file  name in  contrast is  optional; if  it is missing, the
file  is  named  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 cate-
gories:  switches, key file references  (see below) and file specifica-
tions.  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:

  - the  specified switches affect all  specified source files. If sev-
    eral  source  files  shall  be  assembled  with different switches,
    this has to be done in separate runs.
  - 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.

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 can-
not  interpret a switch as  a whole word, it  tries to interprete every
letter as an individual switch. For example, if you write

 -queit

instead of

 -quiet

AS  will take  the letters  q, u,  e, i,  and 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:

  - 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).
  - 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 LST. Except one uses...
  - OLIST:  with a fiel  name as argument  allows to redirect the list-
    ing  to a different  file or a  different path. This  option may be
    used  multiple times in case multiple  files are assembled with one
    execution.
  - o:  Sets the new name of the code file generated by AS. If this op-
    tion  is used multiple  times, the names  will be assigned, one af-
    ter  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.
  - SHAREOUT:ditto for a SHARE file eventually to be created.
  - 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 H.
  - p:  SHARED-variables  will  be  written  in  a format which permits
    easy  integration into the CONST-block of a Pascal program. The ex-
    tension of the file is INC.
  - a:  SHARED-variables  will  be  written  in  a format which permits
    easy  integration into an  assembler source file.  The extension of
    the file is INC.

Concerning  effect and function of  the SHARED-symbols please see chap-
ters 2.13 resp. 3.9.1.

  - 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  ( format=MAP), a NoICE-compatible
    command  file (  format=NOICE), and  the Atmel  format used  by the
    AVR  tools ( format=ATMEL). The information  stored in the MAP for-
    mat  is comprised of a symbol table  and a table describing the as-
    signment  of source lines to machine addresses. A more detailed de-
    scription  of  the  MAP  format  can  be  found  in section 5.2 The
    file's  extension is MAP,  NOI, resp. OBJ,  depending on the chosen
    format.  If no explicit format specification  is done, the MAP for-
    mat is chosen.
  - 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 seg-
    ments  may be  added. The  assignment of  segments to bit positions
    may be taken from table 5.2.
  - w: suppress issue of warnings;
  - E  [file]: error messages and warnings produced by AS will be redi-
    rected  to  a  file.  Instead  of  a  file,  the 5 standard handles
    (STDIN..STDPRN)  can also  be specified  as !0  to !4  . Default is
    !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 ex-
    tension LOG.
  - 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 quiet instead of q.
  - h:  write hexadecimal numbers in  lowercase instead of capital let-
    ters. This option is primarily a question of personal taste.
  - 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.
  - 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 per-
    formance. In normal operation it should be switched off.
  - C:  generates a list  of cross references.  It lists which (global)
    symbols  are used in files and lines. This list will also be gener-
    ated  only in  case a  listing is  produced. This  option occupies,
    too, additional memory capacity during assembly.
  - s:  issues a  list of  all sections  (see chapter 3.8). The nesting
    is indicated by indentations (Pascal like).
  - t:  by means of this switch it  is possible to separate single com-
    ponents  of the  standard issued  assembler-listing. The assignment
    of  bits to parts can  be found in the  next section, where the ex-
    act format of the assembly listing is explained.
  - 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 ap-
    pended  equal sign, however,  you can select  other values. The ex-
    pression  following the equals sign may include operators or inter-
    nal  functions, but 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.
    CAUTION!  If the case-sensitive mode is used, this has to be speci-
    fied  in the command line  before any symbol definitions, otherwise
    symbol names will be converted to upper case at this place!
  - A:  stores  the  list  of  global  symbols in another, more compact
    form.  Use this option if the  assembler crashes with a stack over-
    flow  because of too long symbol  tables. Sometimes this option can
    increase  the processing speed  of the assembler,  but this depends
    on the sources.
  - x:  Sets the level of  detail for error messages.  The level is in-
    creased  resp. decreased  by one  each time  this option  is given.
    While  on level 0 (default) only the error message itself is print-
    ed,  an extended message is added  beginning at level 1 that should
    simplify  the  identification  of  the  error's  cause.  Appendix A
    lists  which error messages carry  which extended messages. At lev-
    el  2 (maximum), the source line  containing the error is addition-
    ally printed.
  - n:  If this option is set, the  error messages will be issued addi-
    tionally  with their error number (see appendix A). This is primar-
    ily  intended for use with shells  or IDE's to make the identifica-
    tion of errors easier by those numbers.
  - U:  This option switches AS to  the case-sensitive mode, i.e. upper
    and  lower case in the names  of symbols, sections, macros, charac-
    ter  sets, and  user-defined functions  will be distinguished. This
    is not the case by default.
  - 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 I.
  - M:  If this switch is given, AS generates a file, that contains de-
    finitions  of macros  defined in  the source  file that did not use