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

.\"  -*- nroff -*-
.\"  $Id: asm-11.1 1360 2023-01-29 11:51:48Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2013-2023 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH ASM-11 1 2023-01-27 "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 many 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
  .endc     end of .if conditional block
  .endm     end of macro
  .endr     end of .rept repeat block
  .error    raise error
  .even     ensure word aligment
  .include  include another source file
  .if       assembles block if condition is met
  .iff      assembles block if condition tests false
  .ift      assembles block if condition tests true
  .iftf     assembles block regardless of condition
  .list     minimal support for cnd,me,meb
  .nlist    minimal support for cnd,me,meb
  .macro    starts macro defintion (subset)
  .mcall    load macro definitions
  .mdelete  delete macro definitions
  .mexit    terminate macro or .rept expansion
  .narg     number of macro arguments
  .nchr     calculate string length
  .ntype    evaluate addressing mode
  .odd      align to odd byte address
  .print    insert output into listing
  .rept     starts repeat block definition
  .word     store words of data
.EE

and thus restricted macro support and no psect support.
.
.SS Differences between asm-11 and MACRO-11
.RS 2
.PD 0
.IP "-" 2
only single \.asect supported, no \.psect support
.IP "-"
assembler stops with error code 'S' when '.' exceeds 160000
.IP "-"
registers must be named r0,..,r5,sp,pc
.IP "-"
the %n notation and register expressions are not supported
.IP "-"
labeled assignment statements cause a 'Q' error (MACRO-11 accepts)
.IP "-"
the \.emt and \.trap instruction must have the trap number specified
.IP "-"
a .macro definition must end with \.endm (\.endr not accepted)
.IP "-"
a .rept block must end with \.endr (\.endm not accepted)
.IP "-"
macros: the \\ operator accepts only symbols, no expressions
.IP "-"
a \.if dif/idn doesn't work with blank arguments
.IP "-"
a \.if df/ndf sees opcodes as defined (MACRO-11 doesn't)
.IP "-"
a \.if df/ndf sees register names as undefined (MACRO-11 doesn't)
.IP "-"
error codes on invail statements differ, especially 'A' and 'Q'
.IP "-"
the \.(n)list acts only on cnd, me and meb, ignores other values
.IP "-"
the \.(n)list default is cnd=0,me=0,meb=1 (MACRO-11 cnd=1,meb=0)
.IP "-"
the following directives are not supported:
\&.cross,
\&.csect,
\&.dsabl,
\&.enabl,
\&.flt2,
\&.flt4,
\&.globl,
\&.ident,
\&.iif,
\&.irp,
\&.irpc,
\&.library,
\&.limit,
\&.nocross,
\&.packed,
\&.page,
\&.psect,
\&.rad50,
\&.radix,
\&.rem,
\&.restore,
\&.save,
\&.sbttl,
\&.title,
\&.weak
.PD
.RE
.PP
.
.SS Design goal for directive support
The following directives will be added in future releases

.EX
  .flt2     store 32 bit float
  .flt4     store 64 bit float
.EE

.\" ------------------------------------------------------------------
.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\-L\fI path\fR"
adds \fIpath\fP to the .library search path used by the \.mcall directive.
The default search path is \fI$RETROBASE/tools/asm-11\fP if \fBRETROBASE\fP is
defined.
\fB\-L\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 and .mcall 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\-list\fI opt\fR"
is equivalent to a '.list \fIopt\fP' directive at the beginning of the code.
Supported values for \fIopt\fP are 'cnd', 'me' and 'meb'. Startup
default is 'cnd' and 'me' disabled and 'meb' enabled.
\fB\-list\fP can be given multiple times.
.
.\" ----------------------------------------------
.IP "\fB\-nlist\fI opt\fR"
is equivalent to a '.nlist \fIopt\fP' directive at the beginning of the code.
\fB\-nlist\fP can be given multiple times.
\fB\-nlist\fP options are processed after \fB\-list\fP options.
.
.\" ----------------------------------------------
.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>