,$A JUST=1; LEFT=2
$A INVERT=0; INVO=0
$A PAGENO=1; BOTTOM=4; TOP=3; PAGE=58
$A LINE=72; MARK=2
$A CAP=0; CAPO=0; CAPSH=0; CAPSHO=0
$A TAB=4,8,12,18,20,24,28,32,36,40,44,48,52,56,60,64,68
$N
$B20
$L1M
H A L K
$B2$L2M
A HIGH-LEVEL ASSEMBLY LANGUAGE
FOR THE KMC11
$B6
$L1M
AN INFORMAL INTRODUCTION
$N
$B2$T0%Introduction
$B2HALK is based upon the language HAL, designed and
implemented by Hamish Dewar on the Interdata 70 series and the
ICL 7502.  Various modifications have been made to
accommodate the idiosyncrasies of the KMC11, and it should be noted
that it is neither a subset, nor a superset, of HAL.
$B1It is assumed that the reader is familiar with the
following three documents:
$B1$T3KMC11 Users's Manual (DEC)
$B0$T3KMC11 Programmer's Manual (DEC)
$B0$T3HAL70 MANUAL (CS DEPT)
$B4$C49Gordon Brebner
$B0$C49ERCC
$B0$C49April 1978
$B8$T0%Index$T12%Page
$B1$T0Tags, Literals$T12 3
$B0$T0Expressions$T12 4
$B0$T0Data memory, conditions$t12 6
$B0$T0Statement termination, comments, spaces$t12 7
$B0$T0Assignments$T12 8
$B0$T0Jumps, conditional bracketing$T12 9
$B0$T0Loop bracketing, control labels$T12 10
$B0$T0Data statements, macro calls$T12 11
$B0$T0Assembler directives$T12 12
$B2%Appendices
$B1$T0A. Pre-defined tags$T12 16
$B0$T0B. Implementation$T12 17
$B0$T0C. Error reports$T12 18
$B0$T0D. Object file format$T12 20
$B0$T0E. Sample HALK assembler listing
$N
$A INDENT=0
$B2$T0%TAGS
$b
A tag is a string of letters and digits, starting with a letter.
$B1Five different %types of tag may appear in a HALK program, as
follows:
$A INDENT=2
$B1$T0 (1)$T2Hardware names, e.g$. SP12, BRG, CSR1, MAR.
  A full list is given in Appendix A.
$B1$T0 (2)$T2Constants.
$B0$T2These are defined by the user, either as an explicit
constant, e.g$. NL=10, or by labelling a %control memory
location,
$B0e.g$. FRED: SP1=BRG.
$B1$T0(3)$T2Data memory identifiers.
$B0$T2These are defined by the user by labelling a %data
memory location, e.g$. FRED: 0.
$B1$T0(4)$T2Macro identifiers.
$B1$T0(5)$T2Keywords, e.g$. JUMP, IF, REPEAT.
$A INDENT=0
$B1Only the first six characters of tags are significant.
$V15
$B6$T0%LITERALS
$B1The following forms are provided:
$A INDENT=1
$B1$T1Decimal, e.g. 0, 5, 132 (non-negative)
$B1$T1Binary, e.g. 2$_101, 2$_100011
$B1$T1Octal, e.g. 8$_5, 8$_43
$B1$T1Hexadecimal, e.g. 16$_5, 16$_83, 16$_FF
$B1$T1Character, e.g. 'A', '*', '''
$A INDENT=0
$N
$B2$T0%EXPRESSIONS
$V15
$B4$T0%(a)$ EXPRESSIONS$ FOR$ ASSEMBLY-TIME$ EVALUATION
$B1The following operators are available, in order of precedence,
$B1$T1\ $T4(unary NOT)
$B0$T1<<, >> $T4(left and right shift)
$B0$T1&, !, !! $T4(AND, OR, exclusive OR)
$b0$t1*, / $T4(multiply and divide)
$B0$T1+, - $C+1$T4add and subtract)
$B1$T0Operands must be either literals or constant tags.  The
following special symbols are regarded as constants:
$B1$T0(a)$T2$C+1.$T4$C-2: the current location in control memory
$B0$T0(b)$T2$C+1@$T4$C-2: the current location in data memory
$B0$T0(c)$T2$C+1# <name>, where <name> is a data memory identifier,
$B0$T4$C-2: the address of <name>
$A INDENT=4
$A INDENT=0
$B1Brackets may be used freely to alter the order of evaluation.
$B1Expressions and bracketed sub-expressions are evaluated to full 16-bit
accuracy, and then truncated to 10 bits.  Data values are
further truncated to 8 bits.
$B1A special case of an assembly-time expression consists solely of
a (so far) undefined tag.  When the tag occurs %as$ a$ label,
the current address (control or data) is taken as the value.
$N
$B2$T0%(b)$ EXPRESSIONS$ FOR$ RUN-TIME$ EVALUATION
$B2These are restricted to the binary and unary operations
supported by the KMC11 ALU.  The left hand side of a binary expression
must be a scratch pad memory, i.e$. SP<n>.  The right hand side may be
a hardware name, a constant, or a data memory identifier.
$B1The syntax for each operator is as follows:
$B1$T0<A> + <B>$T4$C-2: addition
$B0$T0<A> + <B> + C$T4$C-2: addition with carry
$B0$T0<A> - <B> - \C$T4$C-2: subtraction with borrow
$B0$T0<A> + C$T4$C-2: identity plus carry (<A> is SPM)
$B0$T0<A>$T4$C-2: identity (<A> as for binary RHS)
$B0$T0<A> !\ <B>$T4$C-2: A OR (NOT B)
$B0$T0<A> ! <B>$T4$C-2: Logical OR
$B0$T0<A> & <B>$T4$C-2: Logical AND
$B0$T0<A> !! <B>$T4$C-2: Exclusive OR
$B0$T0<A> - <B>$T4$C-2: Subtraction (2s C)
$B0$T0<A> - <B> -1$T4$C-2: Subtraction (1s C)
$B1$T0C is a hardware name tag.
$B1$T0Note that any RHS which cannot be immediately used will be
%temporarily$ stored$ in$ the$ Branch$ register prior to
evaluation of the expression.
$N
$B1$T0%DATA$ MEMORY
$B1The current data memory location at run-time (as selected by
the MAR) may be used by giving the tag MEMORY as an operand.
$b1If a data memory identifier is used, the MAR low-order bits are loaded
with the correct address before memory is used as an operand.  Note
that the correct setting of the PAGE (high order bits of the MAR)
%is$ the$ responsibility$ of$ the$ user.
$B1Particular memory locations may be accessed by using the
construct B(<assembly-time expr>).  This has the same
effect as above, with the MAR being loaded with the expression
value.
$V15
$B6$T0%RUN-TIME$ CONDITIONS
$B1A simple condition has the form:
$B1$T3<A> <relator> <B>
$B1with two meanings, as follows:
$A INDENT=3
$B1$T0(1)$T3<A> is a SPM
$B0$T3 <relator> is =, #, <, >, <=, >=
$B0$T3<B> is a hardware name, constant, or data memory identifier.
$B1$T0(2)$T3<A> is either
$A INDENT=4
$B0$T4(i) <A'>.<bit>, where <A'> is a hardware name, constant,
or data memory identifier and <bit> is 0, 1, 4, or 7
$B0$T4or (ii) C (carry bit) or Z (zero bit)
$A INDENT=3
$B0$T3<relator> <B> is =0 or #0.
$B0$T3(#0 may be omitted, if desired)
$B1The appropriate bit of <A'> is tested, using the Branch register
temporarily.
$A INDENT=0
$B1Complex conditions may be constructed from simple conditions
using AND and OR.  The condition is evaluated from left to right,
as far as is necessary to make a decision.  Where ANDs and ORs
occur in the same condition, the condition is considered
as being right parenthesised, e.g. <c1> AND <c2> OR <c3> AND <c4>
is equivalent to
$B0$T2
<c1> AND (<c2> OR (<c3> AND <c4>)).
$N
$B2$T0%STATEMENT$ TERMINATION$ AND$ COMMENTS
$B1A statement is terminated by semi-colon (;)
 or newline.
$B1The statement starting with '!' is ignored.
$B6$T0%SPACES
$B1Spaces may be included freely, except within tags and literals.
$N
$B2$T0%ASSIGNMENT$ STATEMENTS
$B1ASSIGNMENT STATEMENTS HAVE THE FORM <A> = <B>
$B1$T0<A>, the destination, is a hardware name.
$B1$T0Where the instruction format permits, multiple
assignments are possible.  These are:
$A INDENT=3
$B1$T0(a)$T3MAR = <A> =, or PAGE = <A> =, where
<A> is a hardware name, not MAR or PAGE
$B0$T0(b)$T3SP<n> = BRG =
$A INDENT=0
$B1The ordering of multiple destinations is arbitrary.
$B1$T0<B>, the source, is an expression, either assembly-time
or run-time.  Note that the branch register may be used
temporarily if the source and destination
are incompatible.
$B1If the destination(s) do not include MAR or PAGE, the
assignment statement may be followed by the construct: ,MAR = MAR+1 which
causes the MAR to be incremented %after the assignment.
$B1An assignment may be made conditional by following it with
$b0$T1
IF <condition>.
$N
$B2$T0%JUMP$ STATEMENTS
$B1Jump statements have the form JUMP <expression>.  If <expression> is to
be computed at run-time, it may be preceded by the construct,
$B1$T2<page>:, where <page> is PAGE0, PAGE1, PAGE2, or PAGE3.
$B1The page bits are set correctly for addresses known at assembly
time, and to the current page address otherwise.
$B1$T0Note that <expression> yields a %control$ memory$ address.
$B1A jump may be made conditional by following it with: IF <condition>.
$V15
$B6$T0%CONDITIONAL$ BRACKETING$ STATEMENTS
$B1$T0Form:$C+2IF <condition>
$B1$T3<sequence of statements>
$B1$T2ELSE
$B1$T3<alternative sequence>
$B1$T2FINISH
$B1$T0Instructions are dumped to ensure correct conditional
execution at run-time.
$B1The ELSE <alternative sequence> is optional.
$B1The construct ELSE IF is permitted as an abbreviation in nested
conditions, with the additional FINISH omitted.
$B1Conditions may be nested.
$N$T0%LOOP$ BRACKETING$ STATEMENTS
$B1$T0Forms:$C+1CYCLE$T8WHILE <condition>
$B1$T3<sequence> $C+3or$T9<sequence>
$B1$T2REPEAT$T8REPEAT
$B1$T0Instructions are dumped to execute a loop (conditional in the
case of WHILE).
$B1Repetition may be made conditional by following REPEAT by
$B0$T1IF <condition>.
$B1Loops may be nested.
$B6$T0%CONTROL$ LABELS
$B1Any of the above four types of statement may be labelled by
preceding them with <tag>:.
$B1The tag should not have been previously defined.
$B1$T0Multiple labels are permitted.
$B1$T0The label tag created has type %constant, and its
value is that of the current control memory location.
$N$T0%DATA$ STATEMENTS
$B1A data statement consists of a list of (defined) assembly-time
expressions separated by commas.
$B1An expression may be optionally followed by a second expression
in parentheses, which is a repeat count.
$B1Data statements may be labelled by preceding them with <tag>:.
The label tag created has type %data$ memory$ identifier.
$V15
$B6$T0%MACRO$ CALL$ STATEMENTS
$B1A macro call statement consists of a macro identifier followed
by a list of arguments,
separated by commas, which are substituted for the dummy arguments in
the macro expansion.  If the characters space, comma, semi-colon, or the
sequence 'IF', are to be included in an argument, they must be placed in
square brackets, which are removed on substitution.
$B1Recursive, and nested, calls are permitted.
$B1A macro call may be made conditional by following it with 
$B0$T1IF <condition>.
$B1Any labels on a macro call statement are transferred to the next
code, or data, generating statement.
$N$T0%ASSEMBLER$ DIRECTIVES
$B1Assembler directives consists of $$ followed by a keyword tag and
possibly parameters.
$B1Directives may be preceded by labels, which are transferred to the
next code-, or data-generating statement.
$B6$T0%(1)$ TAG$ DEFINITION
$A INDENT=3
$b1$T0Form:$T3$$DEF <def1>, <def2>, ..., where <defn> is <tag1> =  <tag2>.
$B1<tag2> must have been previously defined.
$B0<tag1> is given the type and value of <tag2>.
$B1Alternatively, <tag2> may be a (defined) assembly-time
expression, in which case <tag1> gets type constant, with the value of
the expression.
$A INDENT=0
$B6$T0%(2)$ LOCATION$ COUNTER$ SPECIFICATION
$A INDENT=3
$B1$T0(a)$T3Control.  Form: $$CTRL <assembly-time expr>
$B1The current control memory location at assembly time (.) is set to the
value of the expression.
$B2$T0(b)$T3Data.  Form: $$DATA <assembly-time expr>
$B1The current data memory location at assembly time (@) is set to the value
of the expression.
$N$T0%(3)$ LISTING$ CONTROL
$B1$T0Form: $$LIST <assembly-time expr>
$A INDENT=0
$B0The value of the expresion should lie between 0 and 4 inclusive,
with the following meanings:
$A INDENT=2
$B1$T0 0 :$T2List only error reports
$B0$T0 1 :$T2 0, and list statements
$B0$T0 2 :$T2 1, and list macro expansions
$B0$T0 3 :$T2 2, and list all code and data dumped
$B0$T0 4 :$T2 3, and list failed conditional assembly
lines.
$A INDENT=0
$B1$T0Option 3 is the default.
$B6$T0%(4)$ CONDITIONAL$ ASSEMBLY$ STATEMENTS
$B1$T0Form:$C+2$$IF $T3<tag1><relator><tag2>
$B1$T3<sequence of statements>
$B1$T2$$ELSE
$B1$T3<alternative sequence>
$B1$T2$$FINISH
$A INDENT=2
$B1$T2<tag1> and <tag2> should either be tags, or
assembly-time expressions, which are treated as
constant tags.
$B0<relator> is either =, meaning type and value of <tag1>
and <tag2> are both the same, or #, which is the negation of =.
$A INDENT=0
$B1If the condition is true, the following sequence of
statements is assembled.  If the condition is false and
an alternative is given, it is assembled.  Conditional
assembly statements may not be nested.
$N$T0%(5)$ MACRO$ DEFINITIONS
$B1A macro defintion is introduced by a statement of the form:
$B1$$MACRO <macro identifier tag> <dummy arg list>
$A INDENT=2
$B0$T2where <dummy arg list> is a list of tags separated by commas.
These tags can be %arbitrary.
$A INDENT=0
$B1The macro text then follows, terminated by a statement
of the form: $$END.
$B1When the macro is called, any occurrences of the dummy argument tags in
the macro text are replaced by the actual argument.
$B0The macro text must not include macro definitions.
$B6$T0%PROGRAM$ TERMINATION
$B1No special terminating statement is used.  An EOT character in the
source file terminates assembly.  The EOT should %not
occur within macro text, or within a skipped conditional assembly sequence.
$N $B2$T0%APPENDIX$ A$ -$ PRE-DEFINED$ TAGS
$A INDENT=1
$B2$T0%(a)$ Hardware
$B1$T1SP0,SP1,...,SP15 :Scratchpad memories.
$B0$T1BRG : Branch register.
$B0$T1MEMORY : Memory Location addressed by MAR.
$B0$T1CSR0,CSR1,...,CSR7 : Control and status regsters.
$B0$T1ADR0,ADR1,...,ADR7 : NPR address and data registers.
$B0$T1NPR : NPR control register.
$B0$T1MISC : uPMISC control register
$B0$T1USR0,USR1,...,USR7 : User-defined external registers.
$B0$T1C : Carry bit (valid only in conditions and expressions).
$B0$T1 Z; Zero bit (valid only in conditions)
$B0$T1MAR : Memory address register bits 0-7 (write-only)
$B0$T1PAGE : Memory address register bits 8,9 (write-only)
$B0$T1NODEST : Null destination (write-only)
$B0$T1BRGSHR : BRG shifted right (write-only)
$B3$T0%(b)$ Data$ memory$ identifier
$B1$T1B : Byte at given memory address
$B3$T0%(c)$ Keywords
$B1$T1PAGE0, PAGE1, PAGE2, PAGE3, JUMP, IF, ELSE, FINISH, CYCLE,
WHILE, REPEAT, CTRL, DATA, DEF, MACRO, LIST, END, AND, OR.
$A INDENT=0
$N $B2$T0%APPENDIX$ B$ -$ IMPLEMENTATION
$B1The HALK assembler is implemented on a PDP-11/40,
running under the DEIMOS operating system.
$B1$T0Command form: KMC KPRIMS, <src>/<obj>,<list>
$B1$T1where$T3<src> is the source file
$B0$T3<obj> is the object file (see appendix D)
$B0$T3<list> is the listing file.
$B1The input file KPRIMS is necessary during the development stage
of the assembler.
$B1An illustration of the listing file produced from a demonstration
program is included as appendix E.
$B1The assembler is one-pass - forward references are filled in
as they are resolved, the new code or data dumped being marked with an
asterisk in the listing.
$B1Data memory locations used are marked by @@ in the listing.
$N $B2$T0%APPENDIX$ C$ -$ ERROR$ REPORTS
$B1Error reports have the form:
$B0$T1*** ERROR: <message> [<integer>]
$B0<message> outlines the general area of the error, and
<integer> gives more specific information, as indicated below.
$B1$T0LIMIT EXCEEDED (due to variable assembler restriction)
$A INDENT=2
$B1$T0[1]$T2Too many tags (>256)
$B0$T0[2]$T2Too many labels on statement (>15)
$B0$T0[3]$T2Too many forward references (>256)
$B0$T0[4]$T2IFs and CYCLEs nested to deeply (>10)
$B0$T0[5]$T2Macro has too many dummy arguments (>6)
$B0$T0[6]$T2Macro calls nested to deeply (>5)
$B0$T0[7]$T2Too much macro text (>8192 bytes)
$B0$T0[8]$T2Condition too complex (>30 instructions).
$B1$T0INVALID ASS EXPR (invalid assembly-time expression)
$B1$T0[1]$T2Invalid operand
$B1$T0INVALID RUN EXPR (invalid run-time expression)
$B1$T0[1]$T2Invalid right hand side
$B0$T0[2]$T2Extra operand should be C (carry)
$B1$T0INVALID COND (invalid run-time condition)
$B1$T0[1]$T2Invalid relator
$B0$T0[2]$T2Bit test not =0 or #0
$B0$T0[3]$T2Invalid left hand side
$B0$T0[4]$T2Invalid right hand side
$B1$T0INVALID ASSIGN (invalid assignment)
$B1$T0[1]$T2Destination not followed by '='
$B0$T0[2]$T2MAR already assigned
$B0$T0[3]$T2Multiple assignment invalid
$B0$T0[4]$T2Destination invalid
$B0$T0[5]$T2MAR= MAR+1 invalid
$B1$T0INVALID JUMP
$B1$T0[1]$T2Specified page inconsistent with address
$B0$T0[2]$T2Page specifier not followed by :
$B1$T0BAD TERMINATION (legal construct not terminated correctly)
$B1$T0[1]$T2No ';', or NL at end of statement
$B0$T0[2]$T2No ')' after data value repeat count
$B0$T0[3]$T2No ')' after assembly-time subexpression
$B0$T0[4]$T2No matching ']' in macro actual parameter
$B1$T0NESTING
$B1$T0[1]$T2Macro definition not terminated by $$END
$B0$T0[2]$T2IF does not preced ELSE or FINISH statement
$B0$T0[3]$T2WHILE or CYCLE does not preced REPEAT
$B0$T0[4]$T2Missing FINISH
$B0$T0[5]$T2Missing REPEAT
$B1$T0DIRECTIVE
$B1$T0[1]$T2Invalid tag following $$
$B0$T0[2]$T2$$DEF lhs already defined, or not
followed by =
$B0$T0[3]$T2$$DEF rhs not defined
$B0$T0[4]$T2$$MACRO identifier already used
$B0$T0[5]$T2Nested macro definitions not permitted
$B0$T0[6]$T2$$LIST value invalid
$B0$T0[7]$T2Nested $$IFs not permitted
$B0$T0[8]$T2Comparitor in $$IF must be = or #
$B0$T0[9]$t2$$IF does not precede $$ELSE or $$FINISH
$B1$T0MACRO
$B1$T0[1]$T2Actual argument not set.
$N$B2$T0%APPENDIX$ D$ -$ OBJECT$ FILE$ FORMAT
$A INDENT=0
$B1Object file consists of a sequence of 16-bit values.
$B1$T1First word : 160000 octal
$B1$T1Control memory :
$B0$T2 Branch immediate with test field %zero (undefined instruction) :
$B0$T3Dump instructions from address given in instruction.
$B1$T2Otherwise, instruction to be dumped.
$B1$T1Data memory :
$B0$T2 Branch on memory with test field %zero (undefined instruction) :
$B0$T3Dump data from address given in instruction.
$B1$T2Otherwise, data value to be dumped.
$B1$T1Final word : 160000 octal
$N$B2$T0%APPENDIX$ E$ -$ SAMPLE$ HALK$ ASSEMBLER$ LISTING
$N
$E