AppleIIAsm-Collection/documentation/AppleIIAsm Library Collection Technical Manual/0.6.0/6.0 Quick_Reference_D1_MAC.REQUIRED.md

Disk 1 Macros: The Required Collection

Disk 1: REQUIRED contains three main macro files, unlike most disks which only contain a single macro file. They are as follows:

• MAC.REQUIRED.ASM
  • Contains all of the Macros required by the rest of the library collection. This must always be included in the main program. This also contains emulation macros for a select number of 65C02 instructions, if limited to a 6502 instruction set.
• MAC.ALIAS.8080.ASM
  • These are aliases for some instructions in the 8080 instruction set. Note that these may not work exactly like the 8080 versions, and are considered works-in-progress.
• MAC.ALIAS.Z80.ASM
  • These are aliases for some instructions in the Z80 instruction set. Like with the previous alias file, these are works-in-progress.

Be sure to consult the detailed reference for Disk 1: The Required Library for further explanation of how the macros work, their source code, and an explanation of the source code of any subroutines the macros may rely upon.

MAC.REQUIRED.ASM

MACRO	DEPENDENCY	PARAMETERS	ACTION	DESTROYS	CYCLES	BYTES
_AXLIT	none	]1 = memory address	Determine if address sent is direct or indirect and parse accordingly in registers. .A = address low byte .X = address high byte	NZ	8	6
_AXSTR	_AXLIT	]1 = memory address	Determine if literal string or address is sent and parse accordingly. .A = address low byte .X = address high byte	NZ	11	9+
_ISLIT	none	]1 = memory address	Determine if address sent is direct or indirect and parse accordingly onto the stack .A = address low byte .X = address high byte	NZ	14	8
_ISSTR	_ISLIT	]1 = memory address	Determine if parameter is a literal string or address and parse address accordingly to the stack. .A = address low byte .X = address high byte	NZ	13 or 8	10+ or 6
_MLIT	none	]1 = memory address ]2 = destination ZP address	Determine if address sent is direct or indirect and parse accordingly to zero page .A = address low byte .X = address high byte	NZ	16	12
_MSTR	_ISLIT	]1 = memory address ]2 = destination ZP address	Determine if parameter passed is a literal string and parse address accordingly to the zero page .A address low byte .X = address high byte	NZ	15 or 8	14+ or 6
_PRN	__P	]1 = string to print	Print a literal string to the screen.	NZCV	161+	9+
_WAIT	__w	none	Loop until a button is pressed. .A = keypress value	NZ	14+	10
BEEP	none	]1 = length of beep	Make beeping sound	NZC	108+	15
BCCL	none	]1 = address to jump to if true	Long Branch if Carry is Clear	none	7	8
BCSL	none	]1 = address to jump to if true	Long Branch if Carry is Set	none	7	8
BEQL	none	]1 = address to jump to if true	Long Branch if Equal	none	7	8
BMIL	none	]1 = address to jump to if true	Long Branch if Negative	none	7	8
BNEL	none	]1 = address to jump to if true	Loong Branch if Not Equal	none	7	8
BPLL	none	]1 = address to jump to if true	Long Branch if Positive	none	7	8
BVCL	none	]1 = address to jump to if true	Long Branch if Overflow Clear	none	7	8
BVSL	none	]1 = address to jump to if true	Long Branch if Overflow Set	none	7	8
CBRA	none	]1 = address to jump to if true	Long Branch Always (65C02 emulation)	none	4	4
CPHX	none	none	.X pushed to stack (65C02 Emulation)	NZ	11	6
CPHY	none	none	.Y pushed to stack (65C02 Emulation)	NZ	12	6
CPLX	none	none	top of stack in .X (65C02 Emulation)	NZ	11	6
CPLY	none	none	top of stack in .Y (65C02 Emulation)	NZ	11	7
CTXY	none	none	.X copied to .Y (65C02 Emulation)	NZ	10	6
CTYX	none	none	.Y copied to .X (65C02 Emulation)	NZ	10	6
CLRHI	none	none	high nibble of .A cleared	NZC	10	6
DELAY	DELAYMS	]1 = number of milliseconds (0..255)	Delay for a given number of milliseconds (byte)	NZC	58+	10
DUMP	_AXLIT; __DUMP	]1 = memory address ]2 = number of bytes to dump	Dump a region of memory to the screen .A = number of bytes displayed	NZCV	811+	16
ERRH	_AXLIT; __ERRH	]1 = memory address	sets handle for Applesoft Error Handling	NZC	73	7
GBIT	none	]1 = byte to check ]2 = bit mask	Get bit from .A at specified location in byte. .A = 0 or 1	NZ	14	15
GRET	_AXLIT; __GETRET	]1 = destination address	Get RETURN value and copy it to specified address. .A = return value length	NZC	43+	27
PEEK	_AXLIT	]1 = address to peek	Load an address value into .A. .A holds address value	NZC	28	18
POKE	_AXLIT	]1 = poke value ]2 = address to poke	load a value into given address.	NZC	32	20
MFILL	_MLIT MEMFILL	]1 = starting address ]2 = length ]3 = fill value	Fill a block of memory with a single value.	none	NZ	110+
MOVB	_MLIT MEMMOVE	]1 = source address ]2 = destination address ]3 = length in bytes	Move a block of memory at one address to another address.	NZCV	267+	48
MSWAP	_MLIT MEMSWAP	]1 = first address ]2 = second address ]3 = length in bytes	Swap the values held in two different locks of memory.	NZC	98+	36

---

MAC.ALIAS.8080.ASM

MACRO	DEPENDENCIES	PARAMETERS	ACTION	CYCLES	BYTE
CALL	none	label to JSR to	mimics JSR instruction	6	3
RET	none	none	mimics RTS instruction	6	1
JA	none	label to JMP to	JMP if .A > CMP	14	9
JAE	none	label to JMP to	JMP if .A >= CMP	8	4
JB	none	label to JMP to	JMP if .A < CMP	8	4
JBE	none	label to JMP to	JMP if .A <= CMP	1	6
JC	none	label to JMP to	JMP if .C = 1	8	4
JE	none	label to JMP to	JMP if EQUAL	8	4
JG	none	label to JMP to	JA	11	9
JGE	none	label to JMP to	JAE	8	4
JL	none	label to JMP to	JB	8	4
JLE	none	label to JMP to	JBE	11	6
JNC	none	label to JMP to	JMP if .C = 0	8	4
JNE	none	label to JMP to	JMP if NOT EQUAL	8	4
JZ	none	label to JMP to	JMP if .Z = 1	8	4
JNZ	none	label to JMP to	JMP if .Z = 0	8	4
JS	none	label to JMP to	JMP if SIGNED	8	4
JNS	none	label to JMP to	JMP if NOT SIGNED	8	4
JO	none	label to JMP to	JMP if OVERFLOW = 1	8	4
JNO	none	label to JMP to	JMP if OVERFLOW = 0	8	4
ANC	none	]1 = first addend ]2 = second addend	Add No Carry (ADD in 8080)	12	8
SNC	none	]1 = Minuend ]2 = Subtrahend	Subtract No Carry (SUB in 8080)	12	8
PUSHA	none	none	Push All Registers	30	14
PULLA	none	none	Pull All Registers	19	24
POPA	none	none	PULLA	19	24

---

MAC.ALIAS.Z80.ASM

MACRO	DEPENDENCIES	PARAMETERS	ACTION	CYCLES	BYTE
CALL	none	label to JSR to	JSR equivalent	6	3
CPL	none	none	Invert bits in .A	2	2
JP	none	label to JMP to	JMP equivalent	5	1
LD	none	????	move value from source to destination (non-operational)	?	?
POP	none	none	PLA equivalent	4	1
RET	none	none	RTS equivalent	6	1
SCF	none	none	SEC equivalent	2	1

---

Return to Table of Contents

Disk 2 Quick Reference -- STDIO Macros and Subroutines