AsmPDP - PDP11 Assembler, Version 1.21
                  ======================================
         J.G.Harston, 70 Camm Street, Walkley, Sheffield S6 3TR
                http://mdfs.net/Software/PDP11/Assembler
                            Date: 30-Sep-2023

AsmPDP is a PDP11 assembler which will run on any platform capable of running
BBC BASIC V, such as RISC OS, DOS, Windows and Unix. AsmPDP is also available
as a precompiled executable for DOS/Windows. On running, various command line
options can be given:

        AsmPDP [-a] [-v] [-Dlabel] [<infile> [<outfile> [<listfile>]]]

<infile>   is the source file. This should be plain text.

<outfile>  is the destination file to save the object code to. On RISC OS this
           will be filetyped to &1C5 "PDP11". If absent, the infile is
           assembled, but no outfile is created.

<listfile> is a file to output the assembler listing to. If absent, no listing
           file will be generated. On RISC OS this file will be filetyped to
           &FFF "Text".

-Dlabel=value
-Dlabel    defines the label before assembling. Must be given before the
           filenames. If no =value is given, the label is set to -1. There can
           be several -D switches on the command line.

-a         if set, ADR pseudo-ops generate absolute addressing.

-v         if set, listing is displayed to screen.

If no parameters are given, then AsmPDP prompts for them.

On exit, the return value is set to any operating system error number if
greater than 127, or to the number of errors found in the assembly source up to
127. Zero indicates a successful assembly with no errors.

Source Format
-------------
AsmPDP recognises the DEC opcodes and syntax detailed on the "PDP11 Programming
Card", in "Assembly Language for the PDP11", Kapps & Stafford and in
"Introduction to the PDP11 And Its Assembly Language", Frank.

Opcodes can be upper or lower case.

Comments start with ';' and carry on to the end of the line.

Labels are declared with '.label' or 'label:' at the start of a line. Labels
are case sensitive. As the BBC BASIC evaluator is used, labels cannot be BASIC
commands or functions, eg 'PRINT' or 'TAN'. Use lower case or prefix with with
additional characters, eg 'cmdPRINT'.

Numeric values can be any valid value recognised by BBC BASIC. Hexadecimal
constants start with &, octal constants start with &o, binary constants start
with %. Character constants can be specified with 'x'. The current location
counter can be found with '$' or 'P%'.


Assembler directives
--------------------
#define <label> (<value>) Defines the label with the given value, or -1.
#include <filename>       Includes the specified file.
#ifndef <label>           Continue assembling if <label> is undefined.
#ifdef <label>            Continue assembling if <label> is defined.
#if <value>               Continue assembling if <value> is non-zero.
#else                     Toggle assembly.
#endif                    Continue assembling.
#error <string>           Generates an inline error. Usually used within #if.

#include "filename" will first search the same directory as the file with the
                    calling #include directive, and then search the current
                    directory.
#include <filename> will first search a directory called LIB within the directory
                    AsmPDP is in, then search the same directory as the file with
                    the calling #include directive, and then search the current
                    directory. This allows you to have a library of common code.

If directives are nestable to about 30 levels. Include directives are nestable
to about 10 levels.

Assembler pseudo-ops
--------------------
org  <address>          Sets the location counter.
bss                     Marks the start of the uninitialised data section and
                        the final point of saved code. Setting the label _BSS%
                        also sets the bss limit.
adr  <value>,dst        Calculates the absolute address of the specified label
addr <value>,dst        in a position-independent manner as an offset from the
                        program counter.
align (<value>)         Forces the location counter to align to the specified
                        byte boundary, which must be a power of two. If <value>
                        is omitted, defaults to 2 to align the location power
                        to an even value. Any extra memory is padded with zero
                        bytes.
equm <size of memory>   Reserves an amount of memory, padding with zeros.
equs <string>           Stores the specified string.
equb <byte>             Stores the specified byte.
equw <16-bit word>      Stores the specified 16-bit word, low byte first.
equd <32-bit word>      Stores the specified 32-bit word, low byte first.
equ  <value>            Sets the label to the specified value.

Multiple values can be stored with a single equ pseudo-op, for instance:

        equs "AND", 128, "!" ; Stores 5 bytes
        equb "MOD", 131, "\" ; Also stores 5 bytes
        equw 16383,"Start"   ; Stores 16-bit word then 5-byte string
        equd "Finish", -1    ; Stores 6-byte string then 32-bit word

Note: AsmPDP will attempt to parse "&o" within a string as an octal constant,
and a semicolon will break a string into a comment.

The following DEC/Macro11 pseudo-ops are also recognised:

DEC                AsmPDP
.even              align            Forces the location counter to an even
                                    value.
.align <value>     align <value>    Forces the location counter to the
                                    power-of-two value.
.blkb <value>      equm <value>     Reserves the specified amount of memory.
.byte <bytes>      equb <bytes>     Stores the specified bytes.
.word <word>       equw <word>      Stores the specified 16-bit word, low
                                    byte first.
.ascii <string>    equs <string>    Stores the specified string.
.asciiz <string>   equs <string>,0  Stores the specified string followed by a
                                    zero byte.

Labels
------
Labels are case sensitive, and as the BBC BASIC evaluator is used, labels
cannot be BASIC commands or functions, eg 'PRINT' or 'TAN'. Use lower case or
prefix with with additional characters, eg 'cmdPRINT'. Other than that the only
restriction is that labels must start with a letter and be no longer than 254
letters or digits.

Labels can start with an underline character, but it is recommended that such
names be reserved for use in libraries and with system calls. For instance, the
Unix header library uses the labels _TEXT%, _ENTRY%, _DATA%, _BSS% and _END%.

Filenames
---------
Filenames have '.', '/' and '\' characters swapped where needed to be able to
use RISC OS filenames and Unix/DOS/Windows filenames. So, for example, #include
"Lib/UnixIO.mac" will read the file "Lib.UnixIO/mac" on RISC OS and the file
"Lib\UnixIO.mac" on DOS/Windows. Leafnames are also truncated to ten characters
when needed.

If no file extension is specified on an input filename, a search is made first
for the plain filename, and then with a '.mac' or '/mac' extension.

Bugs, ommissions
----------------
- adr/addr only generates correct code for address modes 0-5. Using with
  predecrement and postincrement modes will double the decrement or increment.
- ALIGN and EQUM will only emit up to 256 zeros, EQUM with a parameter larger
  than 256 will emit 256 zeros then random bytes.
- Semicolons, commas, dollars and &o within strings are parsed incorrectly.
- Requires a BASIC that implements: GET$#n, BPUT#n,s$, LOCAL ERROR, REPORT$.
- Pseudo-op ".cpu num" and command line option "-c num" is reserved to
  specify a CPU. AsmPDP defaults to PDP11.

History
-------
v1.04 31-Aug-2005 Added #include, checks for DOS filenames.
v1.05 30-Apr-2006 Runs correctly as a Windows console application.
v1.06 19-May-2006 '$' recognised in constants.
v1.07 25-Feb-2007 Implemented ADR label,dst.
v1.08 02-Mar-2007 Errors trapped in evaluation, SXT, SWAB, ENDCODE implemented.
v1.09 12-Aug-2008 SOB, M[T|F][PI|PD|PS] implemented.
v1.10 20-Feb-2009 Listing only output if list file given or error occurs.
v1.11 27-Jul-2009 Correctly parses quoted parameters, eg AsmPDP "File 1.mac".
                  label-$ correctly gives error if label not defined.
v1.12 20-Aug-2010 Added .byte .word .ascii .asciiz pseudo-ops.
v1.13 26-Mar-2011 Listing silent unless -v option used, errors return return
                  value. outfile can be omitted without problems. .psuedo
                  after EQU works, added .even. label .pseudo allowed.
v1.14 07-Apr-2011 Sets datestamp on output files, listing lists bytes for
                  byte values.
v1.15 08-Sep-2013 ALIGN can take any power of two, ALIGN and EQUM emit zeros.
                  $ can be suffixed, eg $+label, $-label, &o octal values
                  accepted. Arguments to MUL correct way around. Added
                  #if/etc. directives.
v1.16 03-Oct-2015 EQU can take strings, -Dlabel option added.
v1.17 24-Jul-2016 -Dlabel=value, opcode suffix checked, single dd checked.
v1.18 14-Sep-2016 #if is nestable, better filename munging.
v1.19 25-Dec-2018 Added #define, #include searches <> and "" paths, leafnames
                  truncated if too long.
v1.20 27-Dec-2018 Checks for missing #endif. _BSS% also sets the BSS limit.
                  Added #error, 'X', BLO, BHIS, BLOS, @Rn, ADDR. TABs expanded.
v1.21 30-Sep-2023 Label setting rewritten to run on PDP11 BASIC, added -a, -c.