wfjm.w11/tools/man/man1/asm-11.1

.\"  -*- nroff -*-
.\"  $Id: asm-11.1 1286 2022-08-25 06:53:38Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2013-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH ASM-11 1 2019-05-25 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
.SH NAME
asm-11 \- simple assembler for MACRO-11 style PDP-11 code
.\" ------------------------------------------------------------------
.SH SYNOPSIS
.
.SY asm-11
.RI [ OPTION ]...
.I FILE...
.
.SY asm-11
.B \-\-help
.YS
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
\fBasm-11\fP 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.

\fBasm-11\fP accepts a subset of the MACRO-11 language and generates an
absolute binary in the formats
.RS 2
.PD 0
.IP "-" 2
\fBlda-11\fP(5): the DEC standard absolute binary format, can be directly
used with the paper tape loader.
Activated with the \fB\-\-lda\fP or \fB\-\-olda\fP options.
.IP "-"
\fBcof-11\fP(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 \fB\-\-cof\fP or \fB\-\-ocof\fP options.
.IP "-"
\fBlsm-11\fP(5): very simple word wise 'addr:data' memory dump. Useful when
used in combination with some w11 tools, e.g. \fBdasm-11\fP.
Activated with the \fB\-\-lsm\fP or \fB\-\-olsm\fP options.
.PD
.RE
.PP

\fBasm-11\fP can create a listing in a format very close to that generated by
the MACRO-11 assembler.
Activated with the \fB\-\-lst\fP or \fB\-\-olst\fP options.

\fBasm-11\fP provides only the most basic assembler directives

.EX
  .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
.EE

and thus restricted macro support and neither conditional assembly,
nor psect support.
.
.SS Level of macro support
Enough for simple macros and useful for writing test benches.
Auto-labels are supported (?name syntax). Main limitations:
.RS 2
.PD 0
.IP "-" 2
no \\var support (pass by value)
.IP "-"
only positional parameters
.IP "-"
no concatination support
.IP "-"
no .mexit, .mdelete, .mcall support
.PD
.RE
.PP

.
.\" ------------------------------------------------------------------
.SH OPTIONS
.
.\" ----------------------------------------------
.IP "\fB\-I\fI path\fR"
adds \fIpath\fP to the .include search path.
The default search path is '.'  plus \fI$RETROBASE/tools/asm-11\fP if
\fBRETROBASE\fP is defined. Each \fB\-I\fP adds \fIpath\fP after '.'.
\fB\-I\fP can be given multiple times und must have a single path name.
.
.\" ----------------------------------------------
.IP "\fB\-E\fR"
write .include processed code to \fIstdout\fP and stop after 1st pass.
No other outputs are created, options like \fB\-\-lst\fR 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).
.
.\" ----------------------------------------------
.IP "\fB\-M\fR"
write rules to \fIstdout\fP suitable for \fBmake\fP(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 \fIFILE\fP is not '-'. Was inspired by the -M option of gcc(1).
.
.\" ----------------------------------------------
.IP "\fB\-\-lst\fR"
create listing with a default file name built from the basename of the last
\fIFILE\fP plus a \fI.lst\fP extension.
If \fIFILE\fP is '-' the output is written to \fIstdout\fP.
.
.\" ----------------------------------------------
.IP "\fB\-\-olst=\fIfnam\fR"
create a listing and write it to file \fIfnam\fR.
If \fIfnam\fP is '-' the listing is written to \fIstdout\fP.
.
.\" ----------------------------------------------
.IP "\fB\-\-lda\fR"
create absolute loader output in \fBlda-11\fP(5) format with a default file name
built from the basename of the last \fIFILE\fP plus a \fI.lda\fP extension.
If \fIFILE\fP is '-' the output is written to \fIstdout\fP.

.
.\" ----------------------------------------------
.IP "\fB\-\-olda=\fIfnam\fR"
create absolute loader output in \fBlda-11\fP(5) format and write it to
file \fIfnam\fR.
If \fIfnam\fP is '-' the compound output is written to \fIstdout\fP.
.
.\" ----------------------------------------------
.IP "\fB\-\-cof\fR"
create compound output in \fBcof-11\fP(5) format with a default file name
built from the basename of the last \fIFILE\fP plus a \fI.cof\fP extension.
If \fIFILE\fP is '-' the output is written to \fIstdout\fP.
.
.\" ----------------------------------------------
.IP "\fB\-\-ocof=\fIfnam\fR"
create compound output in \fBcof-11\fP(5) format and write it to file \fIfnam\fR.
If \fIfnam\fP is '-' the compound output is written to \fIstdout\fP.
If both \fB\-\-olst=-\fP and \fB\-\-ocof=-\fP and are specified, the listing
output comes first, followed by the compound output.
.
.\" ----------------------------------------------
.IP "\fB\-\-lsm\fR"
create lsmem style memory dump in \fBlsm-11\fP(5) format with a default file
name built from the basename of the last \fIFILE\fP plus a \fI.lsm\fP extension.
If \fIFILE\fP is '-' the output is written to \fIstdout\fP.
.
.\" ----------------------------------------------
.IP "\fB\-\-olsm=\fIfnam\fR"
create lsmem style memory dump in \fBlsm-11\fP(5) format and write it to
file \fIfnam\fR.
If \fIfnam\fP is '-' the compound output is written to \fIstdout\fP.
.
.\" ----------------------------------------------
.IP "\fB\-help\fR"
print full help text and exit.
.
.\" ------------------------------------------------------------------
.SH OPTIONS FOR DEBUG
.
.\" ----------------------------------------------
.IP "\fB\-\-tpass1\fR"
trace line context in pass 1.
.
.\" ----------------------------------------------
.IP "\fB\-\-tpass2\fR"
trace line context in pass 2.
.
.\" ----------------------------------------------
.IP "\fB\-\-dsym1\fR"
dump psect and ust tables after pass 1.
.
.\" ----------------------------------------------
.IP "\fB\-\-dsym2\fR"
dump psect and ust tables after pass 2.
.
.\" ----------------------------------------------
.IP "\fB\-\-ttoken\fR"
trace tokenizer.
.
.\" ----------------------------------------------
.IP "\fB\-\-tparse\fR"
trace parser.
.
.\" ----------------------------------------------
.IP "\fB\-\-temit\fR"
trace code emit.
.
.\" ----------------------------------------------
.IP "\fB\-\-tout\fR"
trace output file write.
.
.\" ------------------------------------------------------------------
.SH ENVIRONMENT
.IP \fBRETROBASE\fP
If defined adds an include path to the \fBasm-11\fP standard library.
.
.\" ------------------------------------------------------------------
.SH EXIT STATUS
If files can't be opened or an assembler error is detected an
exit status 1 is returned.

.\" ------------------------------------------------------------------
.SH EXAMPLES
.\" --------------------------------------------------------
.SS Direct usage
.
.IP "\fBasm-11 -lst -lda test.mac\fR" 4
Compiles \fItest.mac\fP and creates listing file \fItest.lst\fP and
absolute loader file \fItest.lda\fP.
.
.IP "\fBasm-11 \-\-olst=\- \-\-ocof=\- \-\fR"
Reads the input from \fIstdin\fP and writes a listing followed by a
compound output to \fIstdout\fP. This usage style is convenient when
integrating \fBasm-11\fP with other tools.
.\" --------------------------------------------------------
.SS Embedded usage
.
.IP "\fBfrom ti_w11 command line\fR" 4
The \fB-e\fP option of the \fBti_w11\fP command uses \fBasm-11\fP to compile a
\fI.mac\fP source file and load the binary in either a
w11 design on an FGPA or a test bench. Example
.EX
  ti_w11 -n4d -e $RETROBASE/tools/mcode/dl11/dl11echo.mac
.EE
.
.IP "\fBfrom ti_w11 command prompt\fR"
The \fBlsasm\fP subcommand of a CPU object uses \fBasm-11\fP to compile a
\fI.mac\fP source file, load the binary, and capture the listing and
the symbol table.

.EX
  cpu0 ldasm -file "test.mac" -sym sym -lst lst
  cpu0 cp stapc $sym(...end)
.EE

compiles \fItest.mac\fP and leaves the listing in Tcl variable \fIsym\fP and
the symbol table in Tcl array \fIlst\fP. If the code specified a start address
via a \fI.end\fP directive it can be accessed via \fI$sym(...end)\fP.

.EX
  cpu0 ldasm -lst lst -sym sym {
    ... MACRO-11 code ...
  }
.EE

compiles and loads a code snippet embedded in the Tcl script.
Again, the symbol table in Tcl array \fIlst\fP.
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.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR asm-11_expect (1),
.BR ti_w11 (1),
.BR dasm-11 (1),
.BR lda-11 (5),
.BR cof-11 (5),
.BR lsm-11 (5)

.\" ------------------------------------------------------------------
.SH AUTHOR
Walter F.J. Mueller <W.F.J.Mueller@gsi.de>