asem_51.doc

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

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.

The /QUIET option suppresses all console output except error messages.

When terminating, ASEM-51 returns an exit code to the operating system:

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

Note: Warnings do not influence the exit code!


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

             SET 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.)      SET ASEM51INC=C:\ASEM51\MCU;D:\MICROS\MCS51\INCL

     If include files can neither be found in the working directory,
     nor in the /INCLUDES path (if specified), the assembler searches
     next C:\ASEM51\MCU and finally D:\MICROS\MCS51\INCL.

  2.)      SET ASEM51INC=C:\ASEM51\MCU;%PATH%

     If ASEM51INC is defined as above in AUTOEXEC.BAT after the PATH
     statement, the assembler finally searches the directory C:\ASEM51\MCU
     and then all the directories, contained in the DOS program search
     path, from left to right!

The maximum length of <path> is limited to 255 characters. This cannot be
exceeded with the SET command of the DOS command interpreter COMMAND.COM,
but with third party command interpreters like 4DOS (max. 512 characters)!

Note that trailing blanks and tabs behind the names of environment variables
seem to be considered significant under MS-DOS! If one subsequently defines

             SET ASEM51INC =C:\ASEM51\MCU
and          SET ASEM51INC=C:\8051\MCU

there will be two (!) entries concurrently in the DOS environment! However,
the assembler will recognize the second one only. Since DOS doesn't truncate
trailing blanks and tabs from variable names, the assembler can't do this
either! That is why you should be sure, to always define the environment
variable without blanks and tabs.


II.1.5 Running ASEM-51 in the Borland-IDE
-----------------------------------------
Turbo C++ (1.0 thru 3.0) users will appreciate the possibility to invoke
ASEM-51 as a transfer program from the Borland IDE. (DOS versions only!)
For this, the filter program ASEM2MSG for the ASEM-51 error messages
has been provided. To integrate ASEM-51 into the Borland IDE, perform
the following steps:

  - Be sure that ASEM-51 has been installed properly as described before,
    or that ASEM.EXE and ASEM2MSG.EXE are somewhere in your PATH.

  - Start the Turbo C++ (or Borland C++) IDE for DOS.

  - For Turbo C++ 1.0, first click:  Options | Full menus | ON

  - Click from the menu bar:         Options | Transfer

  - When the "Transfer" dialog box is active, press the Edit button.

  - Now the "Modify/New Transfer Item" dialog box should be active.
    Fill in the following items:

         Program Title:   ASEM-~51
         Program Path:    ASEM
         Command Line:    $NOSWAP $SAVE CUR $CAP MSG(ASEM2MSG) $EDNAME /C
         Translator:      [X]
         Hot key:         Shift F8

    Then press the New button.

  - When returned to the "Transfer" dialog box, press the OK button.

  - Click from the menu bar:         Options | Save | OK

Now it should be possible, to assemble the file in the active edit
window with ASEM-51, when pressing Shift-F8. The error messages (if any)
should appear in the "Message" window. You can browse through the errors,
and jump into the source text by simply pressing <Enter>. This even works,
if the error is not in the program itself, but in an include file!

Turbo-Pascal 7.0 users can also employ their Borland IDE for assembly.
To integrate ASEM-51 into the Turbo-Pascal IDE, perform the following
steps:

  - Be sure that ASEM-51 has been installed properly as described before,
    or that ASEM.EXE and ASEM2MSG.EXE are somewhere in your PATH.

  - Start the Turbo-Pascal 7.0 (or Borland-Pascal 7.0) IDE for DOS.

  - Click from the menu bar:         Options | Tools

  - When the "Tools" dialog box is active, press the New button.

  - Now the "Modify/New Tool" dialog box should be active.
    Fill in the following items:

         Title:           ASEM-~5~1
         Program path:    ASEM
         Command line:    $NOSWAP $SAVE CUR $CAP MSG(ASEM2MSG) $EDNAME
         Hot keys:        Shift+F8

    Then press the OK button.

  - When returned to the "Tools" dialog box, press the OK button.

  - Click from the menu bar:         Options | Environment | Preferences

  - When the "Preferences" dialog box is active, disable the "Close on
    go to source" item in the "Options" checkbox. Then press the OK button.

  - Finally click from the menu bar: Options | Save

Now ASEM-51 can be invoked with Shift-F8, to assemble the program in the
active edit window, while error messages (if any) appear in the "Messages"
window.

Users of both Turbo C++ and Turbo-Pascal should prefer the Turbo C++ IDE.
In the Turbo-Pascal 7.0 IDE, the /COLUMNS (or /C) option has no effect!
Turbo-Pascal versions prior to 7.0 didn't implement the Tools menu.

Note that the transfer macro $SAVE CUR saves the contents of the active
edit window (if modified), before ASEM.EXE is invoked! If your assembler
program includes further source files (which may be currently loaded into
other edit windows), better specify $SAVE ALL. This will save the contents
of all (modified) edit windows to disk files, before invoking ASEM.EXE!
If you are not sure, specify $SAVE PROMPT. This will prompt you for every
(modified) edit window to save the contents before running ASEM.EXE. For
further information on transfer macros, refer to the Borland online help!

Important: ASEM2MSG.EXE is not suitable for Win32 versions of the Borland IDE!


II.1.6 Running ASEM-51 from Windows 3.1x
----------------------------------------
Of course ASEM and ASEMX are running fine in the Windows 3.1x DOS-Box!
But for integration into the Windows 3.1x desktop, the files ASEM.PIF
and ASEM.ICO have been provided. To insert ASEM-51 into a group of the
Program Manager, perform the following steps:

  - Be sure that ASEM-51 has been installed properly for MS-DOS
    as described before.

  - Start Windows 3.1x and expand the Program Manager window to its
    full screen size representation, if necessary.

  - Focus the program group in which ASEM-51 is to be inserted,
    e.g. "Applications".

  - Click from the Program Manager menu bar:   File | New

  - When the "New Program Object" dialog box is active, choose
    the option "Program Item", and click the OK button.

  - Now the "Program Item Properties" dialog box should be active.
    Fill in the following items:

         Description:          ASEM-51
         Command Line:         ASEM.PIF
         Working Directory:                  (whatever you want)
         Shortcut Key:                       (whatever you want)
         Run Minimized:        [ ]

    Then press the [Change Icon] button.

  - Now a message box appears with the error message
    "There are no icons available for the specified file".
    Simply press the OK button.

  - The "Change Icon" dialog box should be displayed now. Fill in

         File Name:      ASEM.ICO

    and press the OK button. Now the ASEM-51 icon should be displayed
    in the icon field. Press the OK button again.

  - When returned to the "Program Item Properties" dialog box, press
    the OK button.

(In national Windows versions, things may look slightly different.)

Now ASEM.EXE can be invoked by simply double-clicking the ASEM-51 icon.
After entering the program parameters in a corresponding dialog box,
ASEM is running in a DOS window, which remains open after program
termination, to let you have a look on the error messages.

In principle, the installation of the protected-mode assembler ASEMX.EXE
can also be done as described above. However, the <Description> field
should be filled with "ASEM-51 XMS", the <Command Line> should be
"ASEMX.PIF", and the icon <File Name> should be ASEMX.ICO instead.


II.1.7 Running ASEM-51 from BRIEF
---------------------------------
BRIEF 3.x users can integrate ASEM-51 into their editor by simply
defining another DOS environment variable in their AUTOEXEC.BAT with

         SET BCA51="ASEM %%s"

This specifies the command for compiling files with extension *.A51.
After that, ASEM-51 can be invoked from BRIEF with Alt-F10.


II.1.8 The DOS Protected-Mode Assembler ASEMX
---------------------------------------------
In general, the proven real-mode assembler ASEM.EXE is sufficient also
for very large programs. Nevertheless, it may be running out of memory,
if a program contains a huge number of long user-defined symbols, or lots
of large macro definitions.
To close the gap, the ASEM-51 package includes the new protected-mode
assembler ASEMX.EXE. ASEMX is functionally identical to ASEM, but it can
use extended memory, to meet extreme workspace requirements.
ASEMX is accompanied by Borland's 16-bit DPMI server DPMI16BI.OVL and
runtime manager RTM.EXE. It requires a 286 CPU (or better), and at least
512 kB of free XMS memory (1 MB recommended)!
When ASEMX is invoked, DPMI16BI.OVL and RTM.EXE must be either

     - in your default directory,
     - where ASEMX.EXE is, or
     - somewhere in your PATH

During startup, the DPMI server tries to allocate all the remaining free
XMS memory for use by ASEMX. If you don't want this, you can restrict the
amount of allocated memory with the DOS environment variable DPMIMEM:

       SET DPMIMEM=MAXMEM n

will restrict the XMS memory space, used for the DPMI interface, to n kB.
Never set n to a value greater than 16383!!!

In general, the Borland DPMI interface is very reliable and does normally
not conflict with other memory managers. ASEMX will also run with other
versions of DPMI16BI.OVL and RTM.EXE provided with various Borland software
packages (except TC++ 3.0 and BC++ 3.1).

However, there is trouble ahead on systems with more than 16 MB RAM!
Without specific installation, there is a fatal tendency to crash, hang,
or even boot, whenever a DPMI program like ASEMX is invoked.
For proper operation of the DPMI interface, MS-DOS 5.0 (or later) is
required, and EMM386.EXE must be loaded!
If EMM386.EXE has been loaded with parameters (e.g. NOEMS), the Borland
16-bit DPMI server cannot handle more than 16 MB! However, without
parameters (i=nnnn, x=nnnn are o.k.) or with other DPMI servers there may
be more. In these cases, ASEMX can use up to 64 MB of extended memory!

If ASEMX is running in a system environment with an own DPMI server, e.g.
the Windows DOS-Box, RTM.EXE will detect this and use the active DPMI server
instead of DPMI16BI.OVL. In this case, the environment variable DPMIMEM has
no effect.
To restrict (or increase) the available XMS memory for the Windows 3.1x DOS
prompt, change file DOSPRMPT.PIF in your WINDOWS directory with the Windows
PIF file editor.
For further information on how to make more or less XMS memory available
to application programs in other system environments, see the corresponding
user manuals.

Another interesting alternative is the Borland 32-bit DPMI server with
virtual memory management. It cannot be provided with the ASEM-51 package
for license reasons, but is contained in Borland's Turbo-Assembler 4.0
and 5.0, Borland C++ 4.5x and 5.0x, and maybe others. It has originally been
developed for the Borland command line tools, but it also works with ASEMX.
It requires a 386 CPU (or better), and allows to extend the free physical
memory with a swap file that can be created with the program MAKESWAP.EXE.
Apart of that, the 32-bit DPMI server DPMI32VM.OVL and the runtime manager
32RTM.EXE are required.
The batch file ASEM32.BAT, provided with the ASEM-51 package, shows how to
run ASEMX with 64 MB of virtual memory, using Borland's 32-bit DPMI server.


II.1.9 The Win32 Console-Mode Assembler ASEMW
---------------------------------------------
In principle, the DOS assemblers ASEM and ASEMX are also running in the
Windows 9x/NT/2000/XP DOS-Box, but with some typical DOS-specific limitations:
file names are restricted to the 8.3 format, path strings are limited to
64 characters, the real-mode assembler cannot access more than 640 kB RAM,
and DOS support is getting worse and worse with every new Windows version.
To overcome these disadvantages, the ASEM-51 package comes with the new
Win32 console-mode assembler ASEMW.EXE. ASEMW is functionally identical
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: