Carl-Henrik Skårstedt b469ceef8c 2020-01-11 12:58:26 -08:00
..
2015-12-04 22:10:27 -08:00
2020-01-11 12:58:26 -08:00

# x65 macro library

Macros are useful for a variety of custom purposes, x65macro.i aims to provide useful common functions that function like a template library.

These macros deal with simple math, assignments, memory copy and loops.

### Operations

The base operations provided by these macros include

• set: Assign a value to the contents of an address
• move: Move the contents of an address to another address
• sub: subtraction
• asrm: arithmetic shift right
• aslm: arithmetic shift left
• neg: negate a number
• abs: make a number positive
• copy: copy memory from one location to another
• for: iterate between two numbers with optional step size
• mnop: insert multiple nop at this point

### Decorations

Letter codes following the operations have the following meaning

• b: byte
• w: word (2 bytes)
• t: triple (3 bytes)
• l: long (4 bytes)
• n: number of bytes in value
• c: copy result to target
• i: immediate, for example add a value to the contents of an address
• x: use the x register for operation as a counter or an offset
• y: use the y register for operation
• r: relative; ry=(zp),y
• a: use the contents of an address for operation (16 bits)
• s: custom step size (instead of +1 or -1) for loops
• p: positive
• m: negative
• o: use label pool for counter

## Examples

``````	; \$fc = CopyCode
; for (\$fe=\$2000; \$fe<\$4000; \$fe += (CodeEnd-CopyCode)) {
;  memcpy(\$fe, \$fc, CodeEnd-CopyCode)
; }

set.w CopyCode, \$fc
for.wsp \$2000, \$4000, \$fe, CodeSegLen
copy.ry128 \$fc, \$fe, CodeSegLen
forend
``````
``````	; int \$fc
; \$fc >>= 1
asrm.n \$fc,4
``````
``````	ldx #\$fc
aslm.nx \$fc,4
``````
``````	; int \$fc
; \$fc = -\$fc

neg.n \$fc,4
``````
``````	; int \$fc = abs(\$fc)
abs.n \$fc, 4
``````

## List of macros and args

``````set.b / .w / .t / .l Value, Target
``````
• set the contents of an 1-4 byte location to a value
• uses accumulator
``````move.b / .w / .t / .l / .n Src,Trg
``````
• copy 1-4 (or n) bytes from Src location to Trg location
• uses accumulator
``````asrm.n Target, Size
``````
• shift a signed multi byte number right
• uses accumulator
``````asrm.nx Target, Size
``````
• shift a signed multi byte number right offset by the x register
• no registers touched
``````aslm.n Target, Size
``````
• shift a multi byte number left
• no registers touched
``````aslm.nx Target, Size
``````
• shift a multi byte number left offset by the x register
• no registers changed
``````neg.cn Source, Target, Size
``````
• negate and copy a multi byte number
• uses accumulator
``````neg.n Target, Size
``````
• negate a number in place
• uses accumulator
``````abs.n Trg, Size
``````
• make a number absolute
• uses accumulator
``````neg.nx Trg, Size
``````
• negate a number in place offset by the x register
• uses accumulator
``````add.n Address1, Address2, Target, Bytes
``````
• add contents of two memory locations into a target lcoation
• uses accumulator
``````sub.n Address1, Address2, Target, Bytes
``````
• uses accumulator
``````add.ni Address, Value, Target, Bytes
``````
• add a fixed value to a memory location into a target
• uses accumulator
``````sub.ni Address, Value, Target, Bytes
``````
• Target = Address - Value
• uses accumulator
``````add.wi Address, Value, Target
``````
• Subtract 16 bit Value from contents of Address and store at Target
• uses accumulator
``````sub.wi Address1, Address2, Target
``````
• add contents of two 16 bit addresses into a target 16 bit location
• uses accumulator
``````mnop Count
``````
• add Count nops
``````copy.x Source, Target, Size
``````
• copy up to 256 bytes using the x register as a counter
• uses accumulator and x register
``````copy.y Source, Target, Size
``````
• copy up to 256 bytes using the y register as a counter
• uses accumulator and y register
``````copy.ry zpSrcPtr,zpTrgPtr,Size
``````
• copy up to 256 bytes using the y register
``````copy.ry128 zpSrcPtr,zpTrgPtr,Size
``````
• copy up to 128 bytes using the y register
``````copy.o Src,Trg,Size,PoolZP
``````
• copy more than 256 bytes using zero page label pool addresses
• uses accumulator, x and y register
``````copy.a Src,Trg,Size
``````
• copy more than 256 bytes using absolute indexed in a loop
• uses accumulator, x and y register
``````copy.zp Src,Trg,Size,zpTmp1,zpTmp2
``````
• copy more than 256 bytes using two pairs of zero page values
• uses accumulator, x and y register
``````for.x Start, End
``````
• iterate using the x register from Start to End, End is not inclusive so to iterate from 31 to 0 use for.x 31, -1
• uses x register
• end for loop with forend macro
``````for.y Start, End
``````
• same as for.x but with the y register
• uses y register
• end for loop with forend macro
``````copy.ry zpSrcPtr,zpTrgPtr,Size
``````
• copy a fixed length buffer using relative zp y indexing
• size is up to a page, changing Y and A
``````copy.ry128 zpSrcPtr,zpTrgPtr,Size
``````
• copy up to 128 bytes using the y register
``````for.w Start, End, Counter
``````
• for loop for 16 bit counter
• uses accumulator
• end for loop with forend macro
``````for.ws Start, End, Counter, Step
``````
• for loop for 16 bit counter with a step value
• uses accumulator
• end for loop with forend macro
``````for.wsp Start, End, Counter, Step {
``````
• for (word Counter=start; Counter<end; Counter += Step), Step>0
• uses accumulator
``````for.wsm Start, End, Counter, Step {
``````
• for (word Counter=start; Counter<end; Counter += Step), Step<0
• uses accumulator
``````forend
``````
• terminates for loops