as_en.doc

万能汇编工具

    the  NOEXPORT  option.  This  new  file  has  the  same name as the
    source file, only the extension is modified into MAC.
  - G:  this switch defines  whether AS should  produce code or not. If
    switched  off,  the  processing  will  be  stopped  after the macro
    processor.  This switch is activated  by default (logically, other-
    wise  you would not  get a code  file). This switch  can be used in
    conjunction  with the P  switch, if only  the macro processor of AS
    shall be used.
  - r  [n]: issue  warnings if  situations occur  that force  a further
    pass.  This information can  be used to  reduce the number of pass-
    es.  You may optionally specify the  number of the first pass where
    issuing  of such messages shall start. Without this argument, warn-
    ings  will come  starting with  the first  pass. Be  prepared for a
    bunch of messages!!
  - cpu  <name>:  this  switch  allows  to  set the target processor AS
    shall  generate code for, in case  the source file does not contain
    a CPU instruction and is not 68008 code.
  - alias  <new>=<old>:  defines  the  processor  type  <new>  to be an
    alias  for  the  type  <old>.  See  section  2.14  for the sense of
    processor aliases.
  -  gnuerrors:  display messages  about errors  resp. warnings  not in
    the  As standard  format, but  instaed in  a format  similar to the
    GNU  C compiler. This  simplifies the integration  of AS into envi-
    ronments  tuned for this  format, however also  suppresses the dis-
    play of precise error positions in macro bodies!

As  long as switches require no  arguments and their concatenation does
not  result in a multi-letter switch,  it is possible to specify sever-
al switches at one time, as in the following example :

 as test*.asm firstprog -cl /i c:\as\8051\include

All  files TEST*.ASM as  well as the  file FIRSTPROG.ASM will be assem-
bled,  whereby listings of all files  are displayed on the console ter-
minal.  Additional sharefiles will  be generated in  the C- format. The
assembler  should search for additional  include files in the directory
C:\AS\8051\INCLUDE.

This  example shows that  the assembler assumes  ASM as the default ex-
tension for source files.

A  bit of caution should  be applied when using  switches that have op-
tional  arguments:  if  a  file  specification immediately follows such
aswitch  without the optional  argument, AS will  try to interprete the
file specification as argument - what of course fails:

 as -g test.asm

The  solution in this  case would either  be to move  the -g option the
end or to specify an explicit MAP argument.

Beside  from specifying options in  the command line, permanently need-
ed  options may be placed in  the environment variable ASCMD. For exam-
ple,  if  someone  always  wants  to  have  assembly listings and has a
fixed  directory for include  files, he can  save a lot  of typing with
the following command:

 set ascmd=-L -i c:\as\8051\include

The  environment options are processed before  the command line, so op-
tions  in the command line can override contradicting ones in the envi-
ronment variable.

In  the case of very  long path names, space  in the ASCMD variable may
become  a problem. For  such cases a  key file may  be the alternative,
in  which the options can be written in  the same way as in the command
line  or the  ASCMD-variable. But  this file  may contain several lines
each  with a maximum length of 255 characters.  In a key file it is im-
portant,  that for options which require  an argument, switches and ar-
gument  have to be  written in the  same line. AS  gets informed of the
name of the key file by a @ aheaded in the ASCMD variable, e.g.

set ASCMD=@c:\as\as.key

In  order to neutralize  options in the  ASCMD variable (or  in the key
file),  prefix the option with a plus  sign. For example, if you do not
want  to generate  an assembly  listing in  an individual case, the op-
tion can be retracted in this way:

as +L <file>

Naturally  it is not consequently  logical to deny an  option by a plus
sign.... UNIX soit qui mal y pense.

References  to key  files may  not only  come from  the ASCMD variable,
but  also directly from the command  line. Similarly to the ASCMD vari-
able, prepend the file's name with a @ character:
 
 as @<file> ....

The  options read from  a key file  in this situation  are processed as
if  they had been written out in the  command line in place of the ref-
erence,  not like  the key  file referenced  by the ASCMD variable that
is processed prior to the command line options.

Referencing  a key file from a key  file itself is not allowed and will
be answered wit an error message by AS.

In  case that you like to start AS  from another program or a shell and
this  shell hands over  only lower-case or  capital letters in the com-
mand  line, the following workaround  exists: if a tilde  (~) is put in
front  of an option letter, the  following letter is always interpreted
as  a lower-case letter. Similarly a  # demands the interpretation as a
capital  letter.  For  example,  the  following  transformations result
for:

 /~I ---> /i
 -#u ---> -U

In  dependence of the  assembly's outcome, the  assembler ends with the
following return codes:

  0 error free run, at maximum warnings occurred
  1 The  assembler displayed only its  command-line parameters and ter-
    minated immediately afterwards.
  2 Errors occurred during assembly, no code file has been produced.
  3 A  fatal error  occurred what  led to  immediate termination of the
    run.
  4 An  error occurred already  while starting the  assembler. This may
    be a parameter error or a faulty overlay file.
255 An  internal error  occurred during  initialization that should not
    occur  in any case...reboot, try again, and contact me if the prob-
    lem is reproducible!

Similar  to UNIX, OS/2 extends an  application's data segment on demand   OS/2
when  the  application  really  needs  the memory. Therefore, an output
like

  511 KByte available memory

does  not indicate a shortly  to come system crash  due to memory lack,
it  simply shows the distance  to the limit when  OS/2 will push up the
data segment's size again...

As  there is no  compatible way in  C under different operating systens   UNIX
to  find out  the amount  of available  memory resp.  stack, both lines
are missing completely from the statistics the C version prints.


        2.5. Format of the Input Files
        ------------------------------

Like  most  assemblers,  AS  expects  exactly  one instruction per line
(blank  lines are  naturally allowed  as well).  The lines  must not be
longer than 255 characters, additional characters are discarded.

A single line has following format:

[label[:]] <mnemonic>[.attr] [param[,param..]] [;comment]

A  line may also be  split over several lines  in the source file, con-
tinuation  characters chain these parts together  to a single line. One
must  however consider that, due to  the internal buffer structure, the
total  line must not be longer  than 256 characters. Line references in
error  messages  always  relate  to  the  last  line of such a composed
source line.

The  colon for the label  is optional, in case  the label starts in the
first  column (the  consequence is  that a  mnemonic must  not start in
column  1). It  is necessary  to set  the colon  in case the label does
not  start in  the first  column so  that AS  is able to distinguish it
from  a mnemonic. In the latter case,  there must be at least one space
between  colon and mnemonic  if the processor  belongs to a family that
supports  an attribute that denotes an  instruction format and is sepa-
rated  from the mnemonic  by a colon.  This restriction is necessary to
avoid  ambiguities: a distinction between a  mnemonic with format and a
label with mnemonic would otherwise be impossible.

Some  signal processor  families from  Texas Instruments optionally use
a  double line (||) in place of the label to signify the prallel execu-
tion  with the previous instruction(s). If these two assembler instruc-
tions  become a single instruction word  at machine level (C3x), an ad-
ditional  label in front  of the second  instruction of course does not
make  sense and is not allowed. The  situation is different for the C6x
with  its instruction packets  of variable length:  If someone wants to
jump  into the middle of  an instruction packet (bad  style, if you ask
me...),  he has  to place  the necessary  label before  into a separate
line.  The same is valid for  conditions, which however may be combined
with the double line in a single source line.

The  attribute is used by a  couple of processors to specify variations
or  different codings of a certain  instruction. The most prominent us-
age  of the attibute is  is the specification of  the operand size, for
example in the case of the 680x0 family (table 2.6).

+-----------+-------------------------------------+---------------------+
| attribute | arithmetic-logic instruction        | jump instruction    |
+-----------+-------------------------------------+---------------------+
+-----------+-------------------------------------+---------------------+
| B         | byte (8 bits)                       | ---------           |
| W         | word (16 bits)                      | ---------           |
| L         | long word (32 bits)                 | 16-bit-displacement |
| Q         | quad word (64 bits)                 | ---------           |
| S         | single precision (32 bits)          | 8-bit-displacement  |
| D         | double precision (64 bits)          | ---------           |
| X         | extended precision (80/96 bits)     | 32-bit-displacement |
| P         | decimal floating point (80/96 bits) | ---------           |
+-----------+-------------------------------------+---------------------+

Table 2.6: Allowed Attributes (Example 680x0)


Since  this manual is not also meant as a user's manual for the proces-
sor  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 instruc-
tion  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 pro-
grammer's manual, e.g. [1] 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:

    add.w:g   rw10,rw8

This  example does  not show  that there  may be a format specification
without  an operand size. In contrast, if an operand size is used with-
out  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 [99], [19],
[38], resp. [39].

The  number of  instruction parameters  depends on  the mnemonic and is
principally  located between  0 and  20. The  separation of the parame-
ters  from each  other is  to be  performed only  by commas (exception:
DSP56xxx,  its parallel data transfers are separated with blanks). Com-
mas  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 com-
ment if it starts in the first column with a semicolon.

To  separate the individual components you  may also use tabulators in-
stead of spaces.


        2.6. Format of the Listing
        --------------------------

The  listing produced by  AS using the  command line options  i or I is
roughly divisible into the following parts :

  1 issue of the source code assembled;
  2 symbol list;
  3 usage list;
  4 cross reference list.

The  two last ones are only generated if they have been demanded by ad-
ditional 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:

[<n>] <line>/<address> <code> <source>

In  the field 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 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 address.

The  code  produced  is  written  behind  address in the field code, in
hexadecimal  notation. Depending on the  processor type and actual seg-
ment  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  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 or-
der.  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 -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 2.7.


               +-----+--------------------------------+
               | bit | part                           |
               +-----+--------------------------------+
               +-----+--------------------------------+
               | 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            |
               +-----+--------------------------------+

Table 2.7: Assignment of Bits to Listing Components

All bits are set to 1 by default, when using the switch

-t <mask>

Bits  set in <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  ASCMD variable... If someone wants  to have, for example, only the
symbol table, it is enough to write:

-t 2  

The  usage list issues the occupied  areas hexadecimally for every sin-
gle  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 or-
der and has the following form:

 symbol <symbol name> (=<value>,<file>/<line>): 
  file <file 1>:
  <n1>[(m1)]  ..... <nk>[(mk)]
  .
  .
  file <file l>:
  <n1>[(m1)]  ..... <nk>[(mk)]

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 refer-
ences for