asem_51.doc

Free 8051 asm compiler for linux new host platforms: Win32 and Linux macro processing dramatica

     produce an Intel-HEX file eprom and a listing eprom.lst.

  4.)      asem -o rover.a51

     will assemble the 8051 assembly language program rover.a51 and produce
     an absolute OMF-51 object module rover.omf and a listing rover.lst.

  5.)      asem sample.a51 /dev/ttyS0 /dev/null

     will assemble the 8051 assembly language program sample.a51, send
     the HEX file output to the serial interface /dev/ttyS0 and suppress
     the list file output by sending it to the /dev/null device.

  6.)      asem -i /usr/local/include/asem-51:~/8051/inc app.a51

     will assemble the program app.a51, while all required include
     files will be searched first in the default directory, then in
     /usr/local/include/asem-51, and finally in ~/8051/inc.

  7.)      asem --define=Eva_Board:8000H:C universal.a51

     will assemble the program universal.a51, while the CODE symbol
     EVA_BOARD will be predefined with value 8000H during assembly.

When program errors are detected, corresponding error messages are output
to standard error. This may look as follows:


        applicat.a51(14): must be known on first pass
        userbits.inc(6): attempt to divide by zero
        defines.inc(37): symbol not defined
        applicat.a51(20): symbol not defined
        applicat.a51(27): no END statement found


Every error is flagged with the name of the source or include file, the
local line number where it was found, and the error message itself.
This output format provides a hook to run ASEM-51 from third-party IDEs.
A perfect fit may be reached with the --columns option. When specified,
the column numbers of program errors are output additionally after the
line numbers:


        applicat.a51(14,12): must be known on first pass
        userbits.inc(6,27): attempt to divide by zero
        defines.inc(37,18): symbol not defined
        applicat.a51(20,18): symbol not defined
        applicat.a51(27,1): no END statement found


If errors are detected in macro expansion lines, there is no corresponding
location in the source file. Therefore, the error is flagged with the name
of the source or include file, and the local line number from where the
macro expansion has been invoked. (For callable macros this is the line
with the macro call, and for repeat blocks this is the ENDM line.)
To give the user a hint, the macro name and expansion line (and optionally
column) number are inserted before the actual error message:


        uartio.a51(44,1): RECEIVE(3,22): segment type mismatch
        uartio.a51(87,1): REPT(4,19): symbol not defined
        uartio.a51(87,1): REPT(8,19): symbol not defined
        uartio.a51(87,1): REPT(12,19): symbol not defined


The expansion line number is the number of the expansion line within the
corresponding macro expansion, starting with 1. If the error occurs during
expansion of a repeat block, the keyword REPT replaces the macro name.

By default, ASEM-51 is totally "quiet", if no errors are detected.
If the --verbose option is specified, additional product, version, and
error summary information is written to standard output:


        MCS-51 Family Macro Assembler ASEM-51 V1.3

        uartio.a51(44,1): RECEIVE(3,22): segment type mismatch
        uartio.a51(87,1): REPT(4,19): symbol not defined
        uartio.a51(87,1): REPT(8,19): symbol not defined
        uartio.a51(87,1): REPT(12,19): symbol not defined

             4 errors detected


When terminating, ASEM-51 returns an exit code to the calling process:

     situation                           exit code
     ---------------------------------------------
     no errors                               0
     program errors detected                 1
     fatal runtime error                     2

Note: Warnings are also output on standard error,
      but do not influence the exit code!


II.2.4 Linux Environment
------------------------
To specify a search path for include files, an optional environment variable
ASEM51INC can be defined:

1.) For bash, ksh, and sh:

             ASEM51INC=<path>
             export ASEM51INC

2.) For csh, tcsh, and zsh:

             setenv ASEM51INC <path>

<path> may be any number of directories separated by ':' characters.
Be sure that the whole definition doesn't contain any blanks or tabs!
If ASEM51INC is defined, the assembler searches the specified <path> for
include files that can neither be found in the working directory, nor in
the search path specified with the --includes option.
The <path> directories will be searched from left to right.

Examples:

  1.) bash:
             ASEM51INC=/usr/local/include/asem-51:~/micros/mcs51/inc
             export ASEM51INC

     If include files can neither be found in the working directory,
     nor in the --includes path (if specified), the assembler searches
     next /usr/local/include/asem-51 and finally ~/micros/mcs51/inc.

  2.) csh:
             setenv ASEM51INC /usr/local/include/asem-51

     If ASEM51INC is defined as above in .login, the assembler finally
     searches the directory /usr/local/include/asem-51 for include files.

The maximum length of <path> is limited to 255 characters.


II.2.5 The HEXBIN Utility
-------------------------
Most EPROM programmers are accepting the Intel-HEX object file format that
is output by ASEM-51. However, for dumb EPROM burners and special purposes
it might be useful to convert the HEX file to a pure binary image file.
For this the conversion utility hexbin is provided.
It is invoked as follows:

      hexbin [<options>] <hexfile> [<binary>]

where <hexfile> is the input file in Intel-HEX format, and <binary> is the
binary output file. All file names that are specified explicitly, are left
unchanged. The parameter <binary> is optional. When omitted, the file name
is derived from the <hexfile>, but with the extension ".bin".
The maximum length of a file parameter is limited to 255 characters!

Instead of file names you may also specify device names to redirect the input
or output to I/O devices. Device names are assumed to start with "/dev/".
Of course no extensions will be added to device names!
It is not checked, whether the device is existing or suitable for the task.

hexbin recognizes the following options:

     short options  |  long options
     ---------------+---------------------
     -o <offset>    |  --offset=<offset>
     -l <length>    |  --length=<length>
     -f <fillbyte>  |  --fill=<fillbyte>
     -v             |  --verbose

The short and long options in the same row are equivalent.
Long options may be abbreviated as long as they remain unique.
All option names are case-sensitive!

The binary file output can be controlled with the options --offset,
--fill and --length.
Normally the first byte in the binary file is the first byte of the HEX
record with the lowest load address. If a number of dummy bytes is to be
inserted on top of the file (e.g. for alignment in an EPROM image), this
can be performed with the --offset option:

        --offset=1000

would insert 4096 dummy bytes before the first byte of the first HEX record
loaded. The offset must always be specified as a hex number. The default
offset is 0.
Since there may be peepholes between the HEX records, a fill byte value can
be defined with the --fill option:

        --fill=0

would fill all peepholes between the HEX records with zero bytes as well
as all the dummy bytes that might have been inserted with the --offset or
--length option. The fill byte value must always be specified as a hex
number. The default fill byte is the EPROM-friendly FFH.
By default the last byte in the binary file is the last byte of the HEX
record with the highest load address. If the binary file should have a
well defined length, then a number of dummy bytes can be appended to the
file (e.g. for exactly matching an EPROM length), this can be performed
with the --length option:

        --length=8000

would append as many dummy bytes behind the last byte of the file, that the
total file length becomes exactly 32768 bytes. The file length must always
be specified as a hex number.

By default, hexbin is totally "quiet", if no errors are detected.
If the --verbose option is specified, additional product and version
information, and a file conversion report is written to standard output:


        Hex File Converter HEXBIN V2.3

                     offset:      FF0H bytes
              first address:     7FF0H
               last address:     8255H
        fill peepholes with:       A5H
        binary image length:     2000H bytes


Examples:

  0.)      hexbin

     When invoked without parameters, hexbin displays a help screen:

           Hex File Converter HEXBIN V2.3

           usage:      hexbin [options] <hexfile> [<binary>]

           options:   -o   --offset=<offset>
                      -l   --length=<length>
                      -f   --fill=<fillbyte>
                      -v   --verbose

  1.)      hexbin program.hex

     will convert the Intel-HEX file program.hex to a pure binary image file
     program.bin.

  2.)      hexbin -f E5 tarzan.obj jungle.bin

     will convert the Intel-HEX file tarzan.obj to a binary image file
     jungle.bin and fill all peepholes between the HEX file records with
     the binary value E5H.

  3.)      hexbin --off=8000 -l10000 --fill=0 project.hex eprom

     will convert the Intel-HEX file project.hex to a binary image file
     eprom, insert 32K dummy bytes on top of file, fill all peepholes
     and the dummy bytes with nulls, and extend the file to exactly 64K.

When terminating hexbin returns an exit code to the calling process:

     situation                           exit code
     ---------------------------------------------
     no errors                               0
     conversion errors detected              1
     fatal runtime error                     2


II.3 The DEMO Program
---------------------
For getting started with a new assembler, it is always helpful to have
a program that can be assembled with it. For this purpose, the 8051
assembler program DEMO.A51 is provided, which can be used for a first
test of the ASEM-51 installation. For this, you should either have installed
ASEM-51 as described above, or keep all files of the ASEM-51 package directly
in your working directory!

Under MS-DOS or in a Windows DOS-Box simply type

        ASEM DEMO
        HEXBIN DEMO

at the DOS prompt. ASEM and HEXBIN should finish without errors and you
should have the following new files on your disk:

        DEMO.HEX          Intel-HEX file
        DEMO.LST          assembler list file of DEMO.A51
        DEMO.BIN          binary image file of DEMO.HEX

Under Linux type

        asem demo.a51
        hexbin demo.hex

Again asem and hexbin should finish without errors and you should have
the following new files on your disk:

        demo.hex          Intel-HEX file
        demo.lst          assembler list file of demo.a51
        demo.bin          binary image file of demo.hex

If something goes wrong, either ASEM-51 is not properly installed, there
may be files missing in your distribution, or the assembler simply cannot
find the include file 8052.mcu!
demo.a51 may also serve as a sample assembler program that includes examples
for (nearly) all machine instructions, pseudo instructions, assembler
controls, and meta instructions that have been implemented in ASEM-51.
Whenever in doubt how to use a particular command, demo.a51 may be a
valuable help.
Unlike other assemblers, the ASEM-51 list file is no alibi feature!
It is really instructive to compare the original source to the generated
code in the listing.


III. The ASEM-51 Assembly Language
==================================
The user should be familiar with 8051 microcontrollers and assembly
language programming. This manual will not explain the architecture of
the MCS-51 microcontroller family nor will it discuss the basic concepts
of assembly language programming. It only describes the general syntax
of assembler statements and the assembler instructions that have been
implemented in ASEM-51.


III.1 Statements
----------------
Source files consist of a sequence of statements of one of the forms:

          [symbol:]  [instruction [arguments]]     [;comment]

           symbol     instruction  argument        [;comment]

          $control   [(argument)]