--------------------------------------------
-- lc3pp_Language_Extensions.txt
-- 
-- These extensions to LC3 assembly language make programming
-- easier and programs more readable.
-- These macro definitions are expanded/replaced by the
-- pre-processors sed and m4. The sed macros are done first,
-- then the m4 macros. In the end, everything becomes plain
-- LC3 assembly which is assembled by lc3as, for example.
-- Macros with arguments can take any appropriate arguments.
-- All macros begin with an underscore "_" to avoid name conflicts.
-- All macros that manipulate registers set NZP condition codes per
-- the destination register so that subsequent branches will have
-- the expected behavior.
--------------------------------------------
-- Currently defined macros, typical usage:
--
-- intsOff__           intsOn__ 
-- getc__              putc__
-- halt__              sp__
-- mov__(r3, r5)       zero__(r2)            
-- inc__(r7)           dec__(r7)  
-- push__(r5)          pop__(r5)
-- sub__(r1, r2, r3)   or__(r1, r2, r3)
-- jsr__(mySub_BEGIN)  trap__(x13)
--------------------------------------------

====== sed definitions from lc3pp.sed:

source code      translation   example usage     translation
----------       ----------    -------------     -------------------
sp__            r6            add sp__, sp__, 1
intsOff__       trap__(x0)    ;--- See below for def'n
intsOn__        trap__(x1)    ;--- See below for def'n
getc__          trap__(x20)   ;--- See below for def'n
putc__          trap__(x21)   ;--- See below for def'n
out__           trap__(x21)   ;--- See below for def'n
halt__          trap__(x25)   ;--- See below for def'n

;;---------- macros for binary strings:
<Bin>           x             <Bin>0101__       x5
b0__            0             <Bin>b0__         x0  ;;-- leading bit.
b1__            1             <Bin>b1__         x1  ;;-- leading bit.
0000__          0
0001__          1
0010__          2
0011__          3
0100__          4
0101__          5            <Bin>0101__1100__0011__1011__    x5C3B
0110__          6
0111__          7
1000__          8
1001__          9
1010__          A
1011__          B
1100__          C
1101__          D
1110__          E
1111__          F

====== m4 definitions from lc3pp.m4:

example code         translation
----------           -----------

mov__(r3, r5)        add r3, r5, 0        ;;-- r3 <== r5

zero__(r2)           and r2, r2, 0        ;;-- r2 <== 0

inc__(r7)            add r7, r7, 1        ;;-- r7 <== r7 + 1

dec__(r7)            add r7, r7, -1       ;;-- r7 <== r7 - 1

push__(r5)           add sp__, sp__, -1
                     str r5, sp__, 0

pop__(r5)            ldr r5, sp__, 0
                     add sp__, sp__, 1
                     mov__(r1, r1)        ;;-- sets NZP CCs per r5

sub__(r1, r2, r3)    not r3, r3           ;;-- r1 <== (r2 - r3)
                     add r3, r3, 1
                     add r1, r2, r3
                     add r3, r3, -1
                     not r3, r3           ;;-- r2 and r3 unchanged,
                     mov__(r1, r1)        ;;-- sets NZP CCs per r1

or__(r1, r2, r3)    not r2, r2            ;;-- r1 <== (r2 OR r3)
                    not r3, r3
                    and r1, r2, r3
                    not r1, r1
                    not r2, r2
                    not r3, r3            ;;-- r2 and r3 unchanged,
                    mov__(r1, r1)         ;;-- sets NZP CCs per r1

jsr__(mySub_BEGIN)  push__( R7 )          ;;-- uses stack discpline,
                    jsr mySub_BEGIN       ;;-- allows nested calls
                    pop__( R7 )

trap__(x13)         push__( R7 )          ;;-- uses stack discpline,
                    trap x13              ;;-- allows nested calls
                    pop__( R7 )