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”:

fileextension
<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 optionslong 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)

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.


Examples: 

0.)    asem
When invoked without parameters, the assembler displays a help screen: 
           MCS-51 Family Macro Assembler ASEM-51 V1.3

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

           options:   -i   --includes=path1:path2:path3
                      -d   --define=symbol[:value[:type]]
                      -o   --omf-51
                      -c   --columns
                      -v   --verbose

1.)    asem program.a51
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 and a listing jungle.prn. 
3.)    asem project eprom
will assemble the 8051 assembly language program project and 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:

situationexit code
no errors0
program errors detected1
fatal runtime error2

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