## Disk 1 Macros: The Required Library

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](#macrequiredasm)
  - 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](#macalias8080asm)
  - 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](#macaliasz80asm)
  - 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.<br /><br /> **.A** = address low byte<br />**.X** = address high byte |NZ|8|6|
| `_AXSTR` | `_AXLIT` | **\]1** = memory address | Determine if literal string or address is sent and parse accordingly.<br /><br />.**A** = address low byte<br />.**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<br /><br />.**A** = address low byte<br />.**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.<br /><br />.**A** = address low byte<br />.**X** = address high byte |NZ|13 or 8|10+ or 6|
| `_MLIT` | none | **\]1** = memory address<br />**\]2** = destination ZP address | Determine if address sent is direct or indirect and parse accordingly to zero page<br /><br />.**A** = address low byte <br />.**X** = address high byte |NZ|16|12|
| `_MSTR` | `_ISLIT` | **\]1** = memory address<br />**\]2** = destination ZP address | Determine if parameter passed is a literal string and parse address accordingly to the zero page<br /><br />.**A** address low byte <br />.**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.<br /><br />.**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`;<br />`__DUMP` | **\]1** = memory address<br />**\]2** = number of bytes to dump | Dump a region of memory to the screen<br /><br />.**A** = number of bytes displayed |NZCV|811+|16|
| `ERRH` | `_AXLIT`;<br />`__ERRH` | **\]1** = memory address | sets handle for Applesoft Error Handling |NZC|73|7|
| `GBIT` | none | **\]1** = byte to check<br />**\]2** = bit mask | Get bit from .**A** at specified location in byte.<br /><br />.**A** = 0 or 1 | NZ | 14 | 15 |
| `GRET` | `_AXLIT`;<br />`__GETRET` | **\]1** = destination address | Get RETURN value and copy it to specified address.<br /><br />.**A** = return value length |NZC|43+|27|
| `PEEK` |`_AXLIT`| **\]1** = address to peek |Load an address value into .**A**.<br /><br />.**A** holds address value|NZC|28|18|
| `POKE` |`_AXLIT`|**\]1** = poke value<br />**\]2** = address to poke|load a value into given address.|NZC|32|20|
| `MFILL` | `_MLIT` <br />`MEMFILL` | **\]1** = starting address<br />**\]2** = length<br />**\]3** = fill value | Fill a block of memory with a single value. | none | NZ | 110+ |
| `MOVB` | `_MLIT`<br />`MEMMOVE` | **\]1** = source address<br />**\]2** = destination address <br />**\]3** = length in bytes | Move a block of memory at one address to another address. | NZCV | 267+ | 48 |
| `MSWAP` | `_MLIT`<br />`MEMSWAP` | **\]1** = first address<br />**\]2** = second address <br />**\]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<br />**\]2** = second addend| Add No Carry (ADD in 8080)|12|8|
|`SNC`|none|**\]1** = Minuend<br />**\]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|