geoProgrammer Macros

Ariel's GEOS Programmer's Reference Guide
Back: Programming Notes (TODO)	Up: Contents	Next: GEOS Character Sets

Quick Reference

Provided with geoProgrammer

Macro	Parameters	Summary
LoadB	dest,value	Load Byte
LoadW	dest,value	Load Word
MoveB	source,dest	Move Byte
MoveW	source,dest	Move Word
add	source	Add Byte
AddB	source,dest	Add Bytes
AddW	source,dest	Add Words
AddVB	value,dest	Add Value to Byte
AddVW	value,dest	Add Value to Word
sub	source	Subtract Byte
SubB	source,dest	Subtract Bytes
SubW	source,dest	Subtract Words
CmpB	source,dest	Compare Bytes
CmpBI	source,immed	Compare Byte to Immediate
CmpW	source,dest	Compare Words
CmpWI	source,immed	Compare Word to Immediate
PushB	source	Push Byte
PushW	source	Push Word
PopB	dest	Pop Byte
PopW	dest	Pop Word
bra	addr	Branch Relative Always
smb	bitNumber,dest	Set Bit
smbf	bitNumber,dest	Set Bit Faster
rmb	bitNumber,dest	Reset Bit
rmbf	bitNumber,dest	Reset Bit Faster
bbs	bitNumber,source,addr	Branch on Bit Set
bbsf	bitNumber,source,addr	Branch on Bit Set Faster
bbr	bitNumber,source,addr	Branch on Bit Reset
bbrf	bitNumber,source,addr	Branch on Bit Reset Faster

Not Provided with geoProgrammer But Offered in The Hitchhiker's Guide to GEOS

Macro	Parameters	Summary
IncW	dest	Increment Word
DecW	zdest	Decrement Word
DecW2	dest	Decrement Word Faster

geoAssembler is a macro assembler, and the geoProgrammer disks come with a collection of useful and frequently referenced macros that make 16-bit word values easier to work with and source code easier to read. However, for those who don't program in geoProgrammer, seeing these macros so frequently referenced without definitions can be frustrating.

Presented here are the macros defined in the geoProgrammer files geosMacros and geosMac:

LoadB dest,value -- Load Byte

value -> dest

dest: Destination address to load with a byte value
value: Byte value to load

.macro  LoadB   dest,value
        lda     #value
        sta     dest
.endm

LoadW dest,value -- Load Word

value -> dest, dest+1

dest: Destination address to load with a word value
value: Word value to load

.macro  LoadW   dest,value
        lda     #](value)     ;high byte
        sta     dest+1
        lda     #[(value)     ;low byte
        sta     dest+0
.endm

MoveB source,dest -- Move Byte

source -> dest

source: Source address to copy byte from
dest: Destination address to copy byte to

.macro  MoveB   source,dest
        lda     source
        sta     dest
.endm

MoveW source,dest -- Move Word

source, source+1 -> dest, dest+1

source: Source address to copy word from
dest: Destination address to copy word to

.macro  MoveW   source,dest
        lda     source+1      ;high byte
        sta     dest+1
        lda     source+0      ;low byte
        sta     dest+0
.endm

add source -- Add Byte

clear carry, A = A + source

source: Either address of byte to add or immediate value to add

.macro  add     source
        clc
        adc     source
.endm

AddB source,dest -- Add Bytes

clear carry, dest = dest + source

source: Address of byte value to be added
dest: Address of byte value to be added to and hold the sum value

.macro  AddB    source,dest
        clc
        lda     source
        adc     dest
        sta     dest
.endm

AddW source,dest -- Add Words

clear carry, (dest, dest+1) = (dest, dest+1) + (source, source+1)

source: Address of word value to be added
dest: Address of word value to be added to and hold the sum value

.macro  AddW    source,dest
        lda     source     ;low byte
        clc
        adc     dest+0
        sta     dest+0
        lda     source+1   ;high byte with carry
        adc     dest+1
        sta     dest+1
.endm

AddVB value,dest -- Add Value to Byte

clear carry, dest = dest + value

value: Constant or immediate byte value to add
dest: Address of byte value to be added to and hold the sum value

.macro  AddVB   value,dest
        lda     dest
        clc
        adc     #value
        sta     dest
.endm

AddVW value,dest -- Add Value to Word

clear carry, (dest, dest+1) = (dest, dest+1) + value

value: Constant or immediate word value to add
dest: Address of word value to be added to and hold the sum value

.macro  AddVW   value,dest
        clc
        lda     #[(value)     ;low byte
        adc     dest+0
        sta     dest+0

.if     (value >= 0) && (value <= 255)
        bcc     noInc         ;carry was set if adc above overflowed
        inc     dest+1
noInc:
.else
        lda     #](value)     ;high byte
        adc     dest+1
        sta     dest+1
.endif

.endm

Note: In the file geosMacros, this macro incorrectly treats the high byte as the low byte. This macro is defined correctly in the file geosMac.

sub source -- Subtract Byte

set carry, A = A - source

source: Either address of byte to subtract or immediate value to subtract

.macro  sub     source
        sec
        sbc     source
.endm

SubB source,dest -- Subtract Bytes

set carry, dest = dest - source

source: Address of byte value be subtracted
dest: Address of byte value to be subtracted from and hold the difference value

.macro  SubB    source,dest
        sec
        lda     dest
        sbc     source
        sta     dest
.endm

SubW source,dest -- Subtract Words

set carry, (dest, dest+1) = (dest,dest+1) - (source,source+1)

source: Address of word value to be subtracted
dest: Address of word value to be subtracted from and hold the difference value

.macro  SubW    source,dest
        lda     dest+0     ;low byte
        sec
        sbc     source+0
        sta     dest+0
        lda     dest+1     ;high byte
        sbc     source+1
        sta     dest+1
.endm

CmpB source,dest -- Compare Bytes

(source - dest) applied to flags N, Z, C

source: Address of byte value to be compared
dest: Address of byte value to compare against

.macro  CmpB    source,dest
        lda     source
        cmp     dest
.endm

CmpBI source,immed -- Compare Byte to Immediate

(source - immed) applied to flags N, Z, C

source: Address of byte value to be compared
immed: Byte value to compare against

.macro  CmpBI   source,immed
        lda     source
        cmp     #immed
.endm

CmpW source,dest -- Compare Words

(source,source+1 - dest,dest+1) applied to flags N, Z, C

source: Address of word value to be compared
dest: Address of word value to compare against

.macro  CmpW    source,dest
        lda     source+1     ;high byte
        cmp     dest+1
        bne     done         ;need low byte?
        lda     source+0     ;low byte
        cmp     dest+0
done:
.endm

CmpWI source,immed -- Compare Word to Immediate

(source,source+1 - immed [16-bit]) applied to flags N, Z, C

source: Address of word value to be compared
immed: Word value to compare against

.macro  CmpWI   source,immed
        lda     source+1     ;high byte
        cmp     #](immed)
        bne     done         ;need low byte?
        lda     source+0     ;low byte
        cmp     #[(immed)
done:
.endm

Note: In the file geosMacros, this macro omits the done: label. This macro is defined correctly in the file geosMac.

PushB source -- Push Byte

source -> stack

source: Address of byte to push

.macro  PushB   source
        lda     source
        pha
.endm

PushW source -- Push Word

source+1 -> stack, source -> stack

source: Address of word to push

.macro  PushW   source
        lda     source+1     ;high byte
        pha
        lda     source+0     ;low byte
        pha
.endm

PopB dest -- Pop Byte

stack -> dest

dest: Address to receive byte popped

.macro  PopB    dest
        pla
        sta     dest
.endm

PopW dest -- Pop Word

stack -> dest, stack -> dest+1

dest: Address to received word popped

.macro  PopW    dest
        pla                ;low byte
        sta     dest+0
        pla                ;high byte
        sta     dest+1
.endm

bra addr -- Branch Relavite Always

Unconditional relative branch

dest: Relative address branching to

.macro  bra     addr
        clv
        bvc     addr
.endm

smb bitNumber,dest -- Set Bit

%1 -> bit bitNumber of dest

bitNumber: Bit to set (0-7)
dest: Address of byte to have a bit set

.macro  smb     bitNumber,dest
        pha
        lda     #(1 << bitNumber)
        ora     dest
        sta     dest
        pla
.endm

smbf bitNumber,dest -- Set Bit Faster

%1 -> bit bitNumber of dest, A = dest

bitNumber: Bit to set (0-7)
dest: Address of byte to have a bit set

.macro  smbf    bitNumber,dest
        lda     #(1 << bitNumber)
        ora     dest
        sta     dest
.endm

rmb bitNumber,dest -- Reset Bit

%0 -> bit bitNumber of dest

bitNumber: Bit to clear (0-7)
dest: Address of byte to have a bit cleared

.macro  rmb     bitNumber,dest
        pha
        lda     #[~(1 << bitNumber)
        and     dest
        sta     dest
        pla
.endm

rmbf bitNumber,dest -- Reset Bit Faster

%0 -> bit bitNumber of dest, A = dest

bitNumber: Bit to clear (0-7)
dest: Address of byte to have a bit cleared

.macro  rmbf    bitNumber,dest
        lda     #[~(1 << bitNumber)
        and     dest
        sta     dest
.endm

bbs bitNumber,source,addr -- Branch on Bit Set

Test bit bitNumber of source, branch to addr if %1

bitNumber: Bit to test (0-7)
source: Address of byte to have a bit tested
addr: Address to branch to if bit is set

.macro  bbs     bitNumber,source,addr
        php
        pha
        lda     source
        and     #(1 << bitNumber)
        beq     nobranch
        pla
        plp
        bra     addr
nobranch:
        pla
        plp
.endm

bbsf bitNumber,source,addr -- Branch on Bit Set Faster

Test bit bitNumber of source, branch to addr if %1, maybe destroy A

bitNumber: Bit to test (0-7)
source: Address of byte to have a bit tested
addr: Address to branch to if bit is set

.macro  bbsf    bitNumber,source,addr
.if     (bitNumber = 7)
        bit     source
        bmi     addr
.elif   (bitNumber = 6)
        bit     source
        bvs     addr
.else
        lda     source
        and     #(1 << bitNumber)
        bne     addr
.endif
.endm

bbr bitNumber,source,addr -- Branch on Bit Reset

Test bit bitNumber of source, branch to addr if %0

bitNumber: Bit to test (0-7)
source: Address of byte to have a bit tested
addr: Address to branch to if bit is clear

.macro  bbr     bitNumber,source,addr
        php
        pha
        lda     source
        and     #(1 << bitNumber)
        bne     nobranch
        pla
        plp
        bra     addr
nobranch:
        pla
        plp
.endm

bbrf bitNumber,source,addr -- Branch on Bit Reset Faster

Test bit bitNumber of source, branch to addr if %0, maybe destroy A

bitNumber: Bit to test (0-7)
source: Address of byte to have a bit tested
addr: Address to branch to if bit is clear

.macro  bbrf    bitNumber,source,addr
.if     (bitNumber = 7)
        bit     source
        bpl     addr
.elif   (bitNumber = 6)
        bit     source
        bvc     addr
.else
        lda     source
        and     #(1 << bitNumber)
        beq     addr
.endif
.endm

Not Provided with geoProgrammer But Offered in The Hitchhiker's Guide to GEOS

Provided here are macros Berkeley Softworks used in house and probably intended to include in geoProgrammer at some point.

IncW dest -- Increment Word

Increment a word in memory

Not provided with geoProgrammer

dest: Address of word value to increment

.macro  IncW    dest
        inc     addr
        bne     done
        inc     addr+1
done:
.endm

DecW zdest -- Decrement Word

Decrement a word in Zero Page memory, destroy A and X

Not provided with geoProgrammer

zdest: Address in Zero Page of word value to decrement

.macro  DecW    zdest
        ldx     #zdest
        jsr     Ddec       ; use GEOS Kernal routine to decrement word
.endm

DecW2 dest -- Decrement Word Faster

Decrement a word in memory, don't set flags on reaching $0000, destroy A

Not provided with geoProgrammer

dest: Address of word value to decrement

.macro  DecW2   dest
        lda     dest
        bne     noOverflow
        dec     addr+1
noOverflow:
        dec     addr
.endm