asem_51.doc

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

    - macro processing (that _really_ works)
    - nested include file processing
    - nested conditional assembly
    - absolute OMF-51 module output (with debug information)
    - Intel-HEX file output
    - hex-to-binary conversion utility
    - built-in symbols for 8051 special function registers (can be disabled)
    - direct support of more than seventy 8051 derivatives
    - support of user-defined 8051 derivatives
    - special support of the Philips 83C75x family
    - 8051 register bank support
    - detailed assembler listing with symbol table or cross reference
    - further fancy printing facilities  ;-)
    - documentation in ASCII and HTML format
    - bootstrap program for testing on the MCS-51 target board
    - support for easy integration into the popular Borland IDE
    - limited update service by the author

The ASEM-51 software package has been developed with:

    Borland-Pascal mit Objekten 7.0 (c) Borland International 1992
    Delphi 2.0 Client/Server Suite (c) Borland International 1996
    FreePascal 1.0.6 (c) Florian Klaempfl 2002


II. Getting started
===================
This chapter describes the ASEM-51 distributions, their installation on the
supported host platforms, and how to use them in daily work.


II.1 DOS and Windows Implementation
-----------------------------------
Until version 1.2, ASEM-51 was available in a real-mode implementation for
plain MS-DOS only. Meanwhile a DOS protected-mode version and a Win32 console
mode version have been added to the package.
In contrast to the new Linux implementation, all the DOS and Windows flavours
are functionally identical and their basic operation can therefore be
described together. Only a few minor differences and special features have
to be discussed separately.
Since it should be possible to share program sources with the Linux version,
all DOS and Windows executables are able to read ASCII files in both DOS and
UNIX format, but write ASCII files in their native (DOS) format only.


II.1.1 Files
------------
Your ASEM-51 distribution archive for DOS/Windows 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.EXE        assembler (DOS real-mode)
        ASEM.PIF        ASEM program information file for Windows 3.1x
        ASEM.ICO        ASEM icon file for Windows 3.1x
    ASEM2MSG.EXE        ASEM-51 message filter for Borland-IDE (DOS)
    ASEM2MSG.PAS        Turbo-Pascal source of ASEM2MSG.EXE
       ASEMX.EXE        assembler (DOS protected-mode)
       ASEMX.PIF        ASEMX program information file for Windows 3.1x
       ASEMX.ICO        ASEMX icon file for Windows 3.1x
    DPMI16BI.OVL        Borland's 16-bit DPMI server (for ASEMX.EXE)
         RTM.EXE        Borland's 16-bit DPMI runtime manager
      ASEM32.BAT        runs ASEMX with Borland's 32-bit DPMI server
       ASEMW.EXE        assembler (Win32 console-mode)
      HEXBIN.EXE        hex-to-binary conversion utility (DOS)
     HEXBINW.EXE        hex-to-binary conversion utility (Win32)
        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 (requires ASEM-51 V1.3)
    CUSTOMIZ.EXE        BOOT-51 customization utility
        BOOT.BAT        batch file for application program upload
      UPLOAD.BAT        called by BOOT.BAT only
     COMPORT.EXE        setup utility for PC serial ports
     RESET51.EXE        program to reset target system via PC ports
       SLEEP.EXE        program to wait for the reset recovery time
       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.BAT        creates a proper ASEM-51 installation under MS-DOS
    KILLASEM.BAT        deletes all files of the ASEM-51 package (DOS)

The first group contains all files directly associated with the assembler.
The second group contains all files directly associated with the bootstrap
program. The third group contains general support and documentation files
that apply to the whole package.


II.1.2 Installation under MS-DOS or Windows
-------------------------------------------
In principle ASEM-51 doesn't require a fuzzy software installation or
configuration. In the simplest case you can copy all files of the package
to your working directory, and enjoy the benefits of true plug-and-play
compatibility!
On the other hand, an installation of ASEM-51 under MS-DOS is very simple:

  - Create a new, empty scratch directory on your harddisk.

  - Unpack your ASEM-51 distribution archive into this directory,
    or copy all files of the ASEM-51 package into it.

  - Make the scratch directory default, run the batch file
    INSTALL.BAT provided, and follow the instructions.

If you don't like anything that is running automatically, or things are not
quite clear, ASEM-51 can also be installed manually as follows:

  - Create a new directory on your harddisk, e.g. C:\ASEM51.

  - Copy all files of the ASEM-51 package into this directory.

  - Append it to your PATH statement in file AUTOEXEC.BAT, e.g.

        PATH C:\DOS;C:\UTIL;C:\ASEM51

  - If this has not already been done while unpacking the distribution
    archive, create a subdirectory, e.g. C:\ASEM51\MCU, and move all
    the *.MCU files provided to this subdirectory, for better survey.

  - Create another subdirectory, e.g. C:\ASEM51\HTML, and move all
    the *.HTM, *.GIF and *.JPG files to this subdirectory, respectively.
    (To read that HTML manual, invoke your web browser and start with
     file C:\ASEM51\HTML\DOCS.HTM!)

  - Optionally define a DOS environment variable ASEM51INC in
    AUTOEXEC.BAT, to specify a search path for include files, e.g.

        SET ASEM51INC=C:\ASEM51\MCU;D:\MICROS\MCS51\INCL

  - For a proper operation of the Borland 16-bit DPMI server on computers
    with more than 16 MB RAM, be sure that EMM386.EXE (included in DOS 5.0
    or later) is loaded, and define the environment variable DPMIMEM in
    AUTOEXEC.BAT as follows:

        SET DPMIMEM=MAXMEM 16383

  - Reboot your PC.

The installation batch file INSTALL.BAT should work properly on MS-DOS,
Windows 3.1x, and Windows 9x systems. It has not yet been tested on other
Windows versions. Especially for the NT-based Windows versions NT 4.0,
2000 and XP, a manual installation is recommended.


II.1.3 DOS Command Line Operation
---------------------------------
ASEM-51 provides full support of command line operation and batch capability
as the best commercial development tools.     ;-)
Nevertheless, it can be integrated into foreign development environments,
if desired. The assembler is invoked by typing:

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

where <source> is the 8051 assembler source, <object> is the output file,
and <listing> is the assembler list file. The parameters <object> and
<listing> are optional. When omitted, the file names are derived from the
<source> file name, but with extensions HEX (or OMF) and LST. All file names
may be specified without extensions. In these cases, the assembler adds
default extensions as shown below:

        file             extension
        ------------------------------------------------------
        <source>         .A51
        <object>         .HEX      (with /OMF-51 option: .OMF)
        <listing>        .LST

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.
Although it is possible to read the source file from a character device
(e.g. CON:) instead of a file, this cannot be recommended: Since ASEM-51
is a two-pass assembler, it always reads the source file twice!

ASEM recognizes the following options:

     /INCLUDES:path1[;path2[; ... ;pathn]]
     /DEFINE:symbol[:value[:type]]
     /OMF-51
     /COLUMNS
     /QUIET

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) DOS environment variable ASEM51INC!

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)

By default, ASEM-51 generates an object file in Intel-HEX format.
When the /OMF-51 option is specified, an absolute OMF-51 module is generated.

Options may be abbreviated as long as they remain unique!

Examples:

  0.)      ASEM

     When invoked without parameters, the assembler displays a help screen:

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

           usage:     ASEM <source> [<object> [<listing>]] [options]

           options:        /INCLUDES:path1;path2;path3
                           /DEFINE:symbol[:value[:type]]
                           /OMF-51
                           /COLUMNS
                           /QUIET

  1.)      ASEM PROGRAM

     will assemble the 8051 assembly language program PROGRAM.A51 and
     produce an Intel-HEX file PROGRAM.HEX and a listing PROGRAM.LST.

  2.)      ASEM TARZAN.ASM JANE JUNGLE.PRN

     will assemble the 8051 assembly language program TARZAN.ASM and
     produce an Intel-HEX file JANE.HEX and a listing JUNGLE.PRN.

  3.)      ASEM PROJECT EPROM.

     will assemble the 8051 assembly language program PROJECT.A51 and
     produce an Intel-HEX file EPROM and a listing PROJECT.LST.

  4.)      ASEM ROVER /OMF

     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 COM2: NUL

     will assemble the 8051 assembly language program SAMPLE.A51, send
     the HEX file output to the serial interface COM2 and suppress the
     list file output by sending it to the NUL device.

  6.)      ASEM APPLICAT /INC:C:\ASEM51\MCU;D:\MICROS\8051\HEADERS

     will assemble the program APPLICAT.A51, while all required include
     files will be searched first in the default directory, then in
     C:\ASEM51\MCU, and finally in D:\MICROS\8051\HEADERS.

  7.)      ASEM UNIVERSL /D:Eva_Board:8000H:C

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

When program errors are detected, they are flagged on the console. This
may look as follows:


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

        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

             5 errors detected


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 makes it easy to integrate ASEM-51 into existing foreign
development environments or workbenches.
A perfect fit for the Turbo C++ IDE (and perhaps others) can be reached
with the /COLUMNS option. When specified, the column numbers of program
errors are output additionally after the line numbers:


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

        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

             5 errors detected


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:


        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