asem_51.doc

Free 8051 asm compiler for win new host platforms: Win32 and Linux macro processing dramaticall

to ASEM, but it can handle long file names and benefits of the Win32
memory management, which allows to assemble astronomically large programs!

 Hint:  If you love file names with blanks in the middle, you have to
        enclose them in double quotes, e.g.

        ASEMW "Test-Program for my 80C32 Evaluation-Board.a51"


II.1.10 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 <hex> [<bin>] [/OFFSET:o] [/LENGTH:l] [/FILL:f] [/QUIET]

where <hex> is the input file in Intel-HEX format, and <bin> is the
binary output file. The parameter <bin> is optional. When omitted, the
file name is derived from the <hex> file name, but with the extension BIN.
All file names may be specified without extensions. In these cases, the
program adds default extensions as shown below:

        file             extension
        ------------------------------
        <hex>            .HEX
        <bin>            .BIN

If you want a file name to have no extension, terminate it with a '.'!
Instead of file names you may also specify device names to redirect the
output to character I/O ports. Device names may be terminated with a ':'!
It is not checked, whether the device is existing or suitable for the task.

The binary file output can also 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.
When HEXBIN has been invoked with all the above options, it may display a
file conversion report like this:


        Hex File Converter HEXBIN V2.3

                     offset:     1000H bytes
              first address:     9000H
               last address:     A255H
        fill peepholes with:       00H
        binary image length:     8000H bytes


The /QUIET option suppresses this console output, while error messages are
displayed regardless.

Options may be abbreviated as long as they remain unique!

Examples:

  0.)      HEXBIN

     When invoked without parameters, HEXBIN displays a help screen:

           Hex File Converter HEXBIN V2.3

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

           options:     /OFFSET:offset
                        /LENGTH:length
                        /FILL:fillbyte
                        /QUIET

  1.)      HEXBIN PROGRAM

     will convert the Intel-HEX file PROGRAM.HEX to a pure binary image file
     PROGRAM.BIN.

  2.)      HEXBIN TARZAN.OBJ JUNGLE/FILL:E5

     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 PROJECT EPROM. /off:8000 /length:10000 /f:0

     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 operating system:

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

There is also a Win32 console-mode version of HEXBIN: HEXBINW.EXE!
HEXBINW is functionally identical to HEXBIN, but can handle long file names.


II.2 Linux Implementation
-------------------------
Until version 1.2, ASEM-51 was available for MS-DOS only.
To get rid of the original DOS "look and feel", many interfaces to the
operating system had to be modified or rewritten, e.g. command line
processing, console I/O, file handling, UNIX environment, and memory
management. Furthermore, the general behaviour of the programs had to be
adapted to UNIX conventions.
A certain rest of DOS flavour may still be remaining though.
On the other hand, the Linux binaries are able to read ASCII files in both
DOS and UNIX format. However, ASCII files are always written in UNIX format.
All these differences make it necessary to describe the Linux implementation
in a separate section!


II.2.1 Files
------------
Your ASEM-51 distribution archive for Linux should contain the following
groups of files:

1.)  asem_51.doc        ASEM-51 User's Manual, ASCII format
        docs.htm        index file of the ASEM-51 documentation, HTML format
           *.htm        further pages of the HTML documentation
           *.gif        GIF images referenced by HTML pages
           *.jpg        JPEG images referenced by HTML pages
        asem            assembler (Linux 386)
        asem.1          man-page for asem
      hexbin            hex-to-binary conversion utility (Linux 386)
      hexbin.1          man-page for hexbin
        demo.a51        a sample 8051 assembler program
           *.mcu        processor definition files of 8051 derivatives
                        (for a detailed list of MCU files see chapter
                         "VI. Support of 8051 Derivatives")

2.)   boot51.doc        BOOT-51 User's Manual, ASCII format
      boot51.htm        index file of the BOOT-51 documentation, HTML format
      boot51.a51        BOOT-51 assembler source (for ASEM-51 V1.3 and up)
      customiz          BOOT-51 customization utility (Linux 386)
      customiz.1        man-page for customiz
      boot              shell script for application program upload
      boot.1            man-page for boot
      upload            called by boot only (generic version)
      upload.new        "new" upload (optimized for stty 2.0 or later)
      reset51           program to reset the target system via PC ports
      reset51.1         man-page for reset51
      blink.a51         sample test program for BOOT-51

3.)   README.1ST        quick information, ASCII format
     license.doc        ASEM-51 License Agreement, ASCII format
     release.130        ASEM-51 Release Notes, ASCII format
     support.doc        ASEM-51 Support Guide, ASCII format
     install.sh         creates a proper ASEM-51 installation under Linux
    uninst51.sh         deletes all files of the ASEM-51 package (Linux)


II.2.2 Installation under Linux
-------------------------------
ASEM-51 for Linux is available as a tar archive and an rpm package.
If you have got the rpm package, login as root and simply type

   rpm -i asem51-1.3-1.i386.rpm

The rpm package has been tested on S.u.S.E.-Linux only, but should also
work on other Linux distributions that meet the FHS directory standard.
If you have got the tar archive, perform the following steps:

   gzip -d asem51-1.3-ELF.tar.gz
   tar xvf asem51-1.3-ELF.tar
   cd asem51
   sh install.sh

If you are installing ASEM-51 as root (preferred), the installation script
install.sh will install the whole package in /usr/local/share/asem-51/1.3,
and establish some symbolic links in /usr/local/bin and /usr/local/man/man1.

If you are installing ASEM-51 under another user-id, install.sh tries to
install the software in your home directory under ~/asem-51/1.3, and
establish some symbolic links in ~/bin and ~/man/man1.

For details see the messages, install.sh is displaying on the console,
and do some fine-tuning accordingly:

If you haven't installed ASEM-51 as root, it may be necessary to add
~/bin to your PATH, and ~/man to your MANPATH.

To specify a search path for the include files *.mcu provided, you can
define an optional environment variable ASEM51INC.
For this, bash, ksh, and sh users should insert the following lines into
their .profile file:

    ASEM51INC=/usr/local/share/asem-51/1.3/mcu
    export ASEM51INC

csh, tcsh, and zsh users should insert the following line into their
.login file respectively:

    setenv ASEM51INC /usr/local/share/asem-51/1.3/mcu

If you have installed ASEM-51 in your home directory, ASEM51INC should
point to ~/asem-51/1.3/mcu of course.

To read the HTML manuals, invoke your web browser and bookmark the index page

    /usr/local/share/asem-51/1.3/html/docs.htm    (installation as root)
    ~/asem-51/1.3/html/docs.htm                   (local installation)

Note that you cannot reset your 8051 target system with a PC printer port,
if you haven't installed ASEM-51 as root!
(For details see the BOOT-51 documentation provided.)

If you have installed ASEM-51, but you don't like it, you can easily
uninstall it. If you have installed the rpm package, simply type

    rpm -e asem51

If you have installed the generic tar archive, be sure to uninstall
ASEM-51 under the same user-id you previously used for installation! Run

    uninst51.sh

and that's it.


II.2.3 Linux Command Line Operation
-----------------------------------
Under Linux, the assembler is invoked by typing:

asem [<options>] <source> [<object> [<listing>]]

where <source> is the 8051 assembler source, <object> is the output
file, and <listing> is the assembler list file.
All file names that are specified explicitly, are left unchanged.
The parameters <object> and <listing> are optional. When omitted, the
<object> file name is derived from the <source> file name, but with
extension ".hex" (or ".omf"). When the <listing> file name is omitted,
it is derived from the <object> file name, but with extension ".lst":

        file             extension
        -----------------------------------------------
        <object>         .hex    (with -o option: .omf)
        <listing>        .lst

Instead of file names you may also specify device names to redirect the
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.
Although it is possible to read the source file from a character device
instead of a file, this cannot be recommended: Since ASEM-51 is a two-pass
assembler, it always reads the source file twice!
The maximum length of a file parameter is limited to 255 characters!

asem recognizes the following options:

     short options             |  long options
     --------------------------+--------------------------------
     -i path1:path2:path3      |  --includes=path1:path2:path3
     -d symbol[:value[:type]]  |  --define=symbol[:value[:type]]
     -o                        |  --omf-51
     -c                        |  --columns
     -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!

When the --includes option is used, the assembler searches the specified
path for include files that cannot be found in the working directory.
The path may be any number of directories separated by ':' characters.
The directories will be searched from left to right.
The path, specified with the --includes option, is searched before the
path, defined with the (optional) environment variable ASEM51INC!
The maximum path length is limited to 255 characters.

The --define option is useful for selecting particular program variants
from the command line that have been implemented with conditional assembly.
It allows to define a symbol with a value and a segment type in the
command line. Value and type are optional. The segment type of the symbol
defaults to NUMBER, if omitted. The symbol value defaults to 0, if omitted.
The symbol value may be any numerical constant. The symbol type must be one
of the following characters:

             C   =   CODE
             D   =   DATA
             I   =   IDATA
             X   =   XDATA
             B   =   BIT
             N   =   NUMBER    (default)