ASM-11(1)

NAME
asm-11 - simple assembler for MACRO-11 style PDP-11 code

SYNOPSIS
asm-11 [OPTION]... FILE...
asm-11 --help

DESCRIPTION
asm-11 is a simple assembler for MACRO-11 style PDP-11 code that directly generates a load module for an absolute loader. It is mainly used to compile test bench code or other small bare-metal programs into a loadable format. asm-11 accepts a subset of the MACRO-11 language and generates an absolute binary in the formats
    -   lda-11(5): the DEC standard absolute binary format, can be directly used with the paper tape loader. Activated with the --lda or --olda options.
    -   cof-11(5): a custom format that contains the full symbol table and the absolute binary. Very useful when access to the symbol table is needed, for example in test bench codes. Activated with the --cof or --ocof options.
    -   lsm-11(5): very simple word wise 'addr:data' memory dump. Useful when used in combination with some w11 tools, e.g. dasm-11. Activated with the --lsm or --olsm options.

asm-11 can create a listing in a format very close to that generated by the MACRO-11 assembler. Activated with the --lst or --olst options. asm-11 provides only the most basic assembler directives
      .ascii    stores ascii string
      .asciz    stores ascii string with trailing zero
      .asect    absolute program section (current default, dummy imp)
      .blkb     allocate bytes of storage
      .blkw     allocate words of storage
      .byte     store bytes of data
      .end      end of source
      .endm     end of macro
      .even     ensure word aligment
      .include  include another source file
      .list     parsed but otherwise ignored; me always enabled
      .nlist    parsed but otherwise ignored
      .macro    subset of macro functionality
      .odd      align to odd byte address
      .word     store words of data
and thus restricted macro support and neither conditional assembly, nor psect support.

  Level of macro support
Enough for simple macros and useful for writing test benches. Auto-labels are supported (?name syntax). Main limitations:
    -   no \var support (pass by value)
    -   only positional parameters
    -   no concatination support
    -   no .mexit, .mdelete, .mcall support

OPTIONS

-I path
    adds path to the .include search path. The default search path is '.' plus $RETROBASE/tools/asm-11 if RETROBASE is defined. Each -I adds path after '.'. -I can be given multiple times und must have a single path name.

-E  write .include processed code to stdout and stop after 1st pass. No other outputs are created, options like --lst are ignored. Useful for the generation of self-contained macro files that are free of .include directives and thus free of external references. Was inspired by the -E option of gcc(1).

-M  write rules to stdout suitable for make(1) describing the dependencies of generated .lda and .lst files from the source files. Outputs for .lda and .lst targets one rule per input or included file. Only useful when FILE is not '-'. Was inspired by the -M option of gcc(1).

--lst
    create listing with a default file name built from the basename of the last FILE plus a .lst extension. If FILE is '-' the output is written to stdout.

--olst=fnam
    create a listing and write it to file fnam. If fnam is '-' the listing is written to stdout.

--lda
    create absolute loader output in lda-11(5) format with a default file name built from the basename of the last FILE plus a .lda extension. If FILE is '-' the output is written to stdout.

--olda=fnam
    create absolute loader output in lda-11(5) format and write it to file fnam. If fnam is '-' the compound output is written to stdout.

--cof
    create compound output in cof-11(5) format with a default file name built from the basename of the last FILE plus a .cof extension. If FILE is '-' the output is written to stdout.

--ocof=fnam
    create compound output in cof-11(5) format and write it to file fnam. If fnam is '-' the compound output is written to stdout. If both --olst=- and --ocof=- and are specified, the listing output comes first, followed by the compound output.

--lsm
    create lsmem style memory dump in lsm-11(5) format with a default file name built from the basename of the last FILE plus a .lsm extension. If FILE is '-' the output is written to stdout.

--olsm=fnam
    create lsmem style memory dump in lsm-11(5) format and write it to file fnam. If fnam is '-' the compound output is written to stdout.

-help
    print full help text and exit.

OPTIONS FOR DEBUG

--tpass1
    trace line context in pass 1.

--tpass2
    trace line context in pass 2.

--dsym1
    dump psect and ust tables after pass 1.

--dsym2
    dump psect and ust tables after pass 2.

--ttoken
    trace tokenizer.

--tparse
    trace parser.

--temit
    trace code emit.

--tout
    trace output file write.

ENVIRONMENT

RETROBASE
    If defined adds an include path to the asm-11 standard library.

EXIT STATUS
If files can't be opened or an assembler error is detected an exit status 1 is returned.

EXAMPLES

  Direct usage

asm-11 -lst -lda test.mac
    Compiles test.mac and creates listing file test.lst and absolute loader file test.lda.

asm-11 --olst=- --ocof=- -
    Reads the input from stdin and writes a listing followed by a compound output to stdout. This usage style is convenient when integrating asm-11 with other tools.

  Embedded usage

from ti_w11 command line
    The -e option of the ti_w11 command uses asm-11 to compile a .mac source file and load the binary in either a w11 design on an FGPA or a test bench. Example
          ti_w11 -n4d -e $RETROBASE/tools/mcode/dl11/dl11echo.mac

from ti_w11 command prompt
    The lsasm subcommand of a CPU object uses asm-11 to compile a .mac source file, load the binary, and capture the listing and the symbol table.
          cpu0 ldasm -file "test.mac" -sym sym -lst lst
          cpu0 cp stapc $sym(...end)
    compiles test.mac and leaves the listing in Tcl variable sym and the symbol table in Tcl array lst. If the code specified a start address via a .end directive it can be accessed via $sym(...end).
          cpu0 ldasm -lst lst -sym sym {
            ... MACRO-11 code ...
          }
    compiles and loads a code snippet embedded in the Tcl script. Again, the symbol table in Tcl array lst. This usage style is heavily used in test benches. The direct and easy access to the symbol table allows a very tight interaction between the verification code in the test bench and the code executed on the target system.

SEE ALSO
asm-11_expect(1), ti_w11(1), dasm-11(1), lda-11(5), cof-11(5), lsm-11(5)

AUTHOR
Walter F.J. Mueller <W.F.J.Mueller@gsi.de>