preliminary update
This is a preliminary update to all disks in the library, along with documentation up to the hires collection. This is simply to make sure the library is backed up; the complete rewrite of the library will be coming after the speaker routines are finished along with the rest of the documentation.
This commit is contained in:
Nathan D Riggs
parent
9f8c6c88f5
commit
00ed4c7146
Binary file not shown.
Binary file not shown.
Binary file not shown.
|
|
@ -1,3 +1,3 @@
|
|||
You will find the current disks being worked on here. Commits to these files, unfortunately, may spam the documentation.
|
||||
|
||||
Note that the core part of the collection is numbered, while there rest has yet to be decided on or oncorporated.
|
||||
Note that the core part of the collection is numbered, while there rest has yet to be decided on or incorporated.
|
||||
|
|
|
|||
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
BIN
bin/d04_math.dsk
BIN
bin/d04_math.dsk
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 210 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
|
Before Width: | Height: | Size: 840 KiB After Width: | Height: | Size: 840 KiB |
|
Before Width: | Height: | Size: 840 KiB After Width: | Height: | Size: 840 KiB |
|
Before Width: | Height: | Size: 840 KiB After Width: | Height: | Size: 840 KiB |
|
Before Width: | Height: | Size: 840 KiB After Width: | Height: | Size: 840 KiB |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
|
|
@ -68,13 +68,18 @@ limitations under the License.
|
|||
5. [Software Architecture](4.0%20Software_Architecture.md)
|
||||
6. [Macro/Subroutine Quick References](5.0%20Quick_Reference_TOC.md)
|
||||
7. - [Quick Reference Introduction](5.0%20Quick_Reference_TOC.md)
|
||||
- [Disk 1 -- REQUIRED Macros and Subroutines](6.0%20Quick_Reference_D1_MACREQUIRED.md)
|
||||
- [Disk 2 -- STDIO Macros and Subroutines](7.0%20Quick_Reference_D2_MACSTDIO.md)
|
||||
- [Disk 1 -- REQUIRED Macros](6.0%20Quick_Reference_D1_MAC.REQUIRED.md)
|
||||
- [Disk 2 -- STDIO Macros](7.0%20Quick_Reference_D2_MAC.STDIO.md)
|
||||
- [Disk 3 -- ARRAYS Macros](8.0%20Quick_Reference_D3_MAC.ARRAYS.md)
|
||||
- [Disk 4 -- MATH Macros](9.0%20quick_reference_d4_mac.math.md)
|
||||
7. Detailed References and Source Code Listings
|
||||
- [Disk 1: Required Library and Aliases](30.0%20Detailed_Reference_D1_REQUIRED.md)
|
||||
- [Disk 2: STDIO Macros and Subroutines](31.0%20Detailed_Reference_D2_STDIO.md)
|
||||
- [Disk 3: Array Macros and Subroutines](32.0%20Detailed_Reference_D3_Arrays.md)
|
||||
- [Disk 4: Basic Math Macros and Subroutines](33.0%20Detailed_Reference_D4_MATH.md)
|
||||
8. Appendices
|
||||
- Supplemental Texts
|
||||
- Further Reference
|
||||
- Optimizations
|
||||
- Typical Assembly Opimizations
|
||||
- Typical Assembly Optimizations
|
||||
- Architecture Clobbering Optimizations
|
||||
|
|
@ -1,10 +1,10 @@
|
|||
## Preface
|
||||
|
||||
This is the first complete reference manual for the _AppleIIAsm_ macro and subroutine library collection. Currently, this collection is in the alpha stages of development: not all disks are complete, there may be some bugs here and there, and major workflow decisions might still be in flux. However, this version, 0.7.0, represents a major step forward in functionality, optimization and standardization, and at least for what is complete---the first eleven disks, the technical manual, AppleChop introduction as well as some demos---the collection can be reasonably considered to be stable. That does not, of course, mean that there are any guarantees.
|
||||
This is the first complete reference manual for the _AppleIIAsm_ macro and subroutine library. Currently, this library is in the alpha stages of development: not all disks (collections) are complete, there may be some bugs here and there, and major workflow decisions might still be in flux. However, this version, 0.7.0, represents a major step forward in functionality, optimization and standardization, and at least for what is complete--the first eleven disks, the technical manual, AppleChop introduction as well as some demos--the collection can be reasonably considered to be stable. That does not, of course, mean that there are any guarantees.
|
||||
|
||||
I started this project as research into how the Apple II works as a platform for another book I am writing, and eventually became interested in the cohesive technical documentation (or sometimes lack thereof) that was available to beginning coders in the heyday of the Apple II as well as those looking to learn Apple II (6502) Assembly today. Having no prior experience with Assembly language, I began coding these libraries as part of my own learning process while trying to write subroutines that provided much of the functionality afforded by Applesoft BASIC. Eventually, this became a beast of its own, and what you’re reading here is (part) of the result.
|
||||
|
||||
As the libraries grow and morph, so will this document. If nothing else, I hope that the collection and its accompanying documentation helps hobbyists, researchers, and otherwise self-hating hopeless nerds learn and accomplish what they want or need---at least as much as it has helped, and harmed, me.
|
||||
As the library collections grow and morph, so will this document. If nothing else, I hope that the collection and its accompanying documentation helps hobbyists, researchers, and otherwise self-hating hopeless nerds learn and accomplish what they want or need---at least as much as it has helped, and harmed, me.
|
||||
|
||||
|
||||
|
||||
|
|
@ -12,7 +12,12 @@ Nathan Riggs
|
|||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
[Return to Table of Contents](0.0%20Title_to_TOC)
|
||||
[Next: Introduction](2.0%20Introduction.md)
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,40 @@
|
|||
# Disk 5: Strings and Substrings
|
||||
|
||||
|
||||
|
||||
The Strings Collection of the AppleIIAsm Library is dedicated to macros used for handling strings and substrings. In particular, this refers to the default type of string: those with a preceding length-byte. If these macros need to be used on another type of string, such as a null-terminated string, then the `STRPC` macro should be used on the string first to convert it to a preceding length-byte type.
|
||||
|
||||
The strings collection can be divided further into two categories: those that deal with whole strings and those that deal with substrings exclusively. This is currently reflected in the fact that the macros are held in separate files and use different demos.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
### MAC.STRINGS.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------- | ------------------ | ----------------------------------------- | -------------------- | -------- | ------ | ----- |
|
||||
| `SCMP` | `SUB.STRCOMP.ASM` | ]1 = First string<br />]2 = Second string | Compare strings | NZCV | 110+ | 67 |
|
||||
| `SCAT` | `SUB.STRCAT.ASM` | ]1 = First string<br />]2 = Second string | Concatenate strings | NZCV | 170+ | 113 |
|
||||
| `STRIM` | `SUB.STRIM.ASM` | ]1 = String<br />]2 = Token | Trim string | NZCV | 123+ | 80 |
|
||||
| `STRUP` | `SUB.STRUPPER.ASM` | ]1 = String | Convert to uppercase | NZCV | 114+ | 64 |
|
||||
| `SLO` | `SUB.STRLOWER.ASM` | ]1 = String | Convert to lowercase | NZCV | 113+ | 64 |
|
||||
| `SREV` | `SUB.STRREV.ASM` | ]1 = String | Reverse a string | NZCV | 70+ | 41 |
|
||||
| `SCAP` | `SUB.STRCAP.ASM` | ]1 = String | Capitalize sentences | NZCV | 192+ | 117 |
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### MAC.SUBSTRINGS.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------ | -------------------- | ------------------------------------------------------ | --------------------------- | -------- | ------ | ----- |
|
||||
| `SPOS` | `SUB.SUBPOS.ASM` | ]1 = String<br />]2 = Substring | Get substring position | NZCV | 205+ | 136 |
|
||||
| `SCPY` | `SUB.SUBCOPY.ASM` | ]1 = Source string<br />]2 = Index<br />]3 = Length | Copy substring | NZCV | 95+ | 71 |
|
||||
| `SDEL` | `SUB.SUBDEL.ASM` | ]1 = Source string<br />]2 = Index<br />]3 = Length | Delete substring | NZCV | 135+ | 79 |
|
||||
| `SINS` | `SUB.SUBINS.ASM` | ]1 = Source string<br />]2 = Substring<br />]3 = Index | Insert substring | NZCV | 177+ | 111 |
|
||||
| `STOK` | `SUB.SUBTOK.ASM` | ]1 = String<br />]2 = Token<br />]3 = Token number | Find tokenized substring | NZCV | 182+ | 118 |
|
||||
| `SCNT` | `SUB.SUBCHARCNT.ASM` | ]1 = String<br />]2 = Character | Count character occurrences | NZCV | 88+ | 57 |
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
# Disk 6: Apple DOS
|
||||
|
||||
|
||||
|
||||
The DOS Collection of the AppleIIAsm Library consists of macros and subroutines dedicated to interfacing with Apple DOS, providing an abstraction layer for the programmer on top of the lower level routines used by DOS such as the file manager and RWTS. All of the basic functions of DOS are available for use, save for specific macros dedicated solely to reading and writing text files. The reasoning for this is that 1) unless you are interfacing with a BASIC program or another system, text files are largely unnecessary (binary files work better), and 2) text file manipulation often requires creating a system of your own since there is no simple default way to read the end of a file. The macros and routines that do exist can be used to create your own custom system for reading and writing text files.
|
||||
|
||||
Of all the collections in the library, the DOS collection is perhaps the most convoluted and has the largest overhead due to the more complex nature of its functionality. There are many subroutines and macros that are meant to be used only by the collection itself, though the enterprising programmer may of course utilize them. These are described in the detailed listings.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
### MAC.DOSREQ.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------- | ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ------ | ----- |
|
||||
| `FMFIL` | HEAD.DOS.ASM | ]1 = Command <br/>]2 = Slot<br />]3 = Drive<br />]4 = Volume<br />]5 = Record | Fill most common parameters of the File Manager. | NZCV | 603 | 303 |
|
||||
| `FMNAM` | HEAD.DOS.ASM | ]1 = String Address | Copy a string to the file name parameter in the File Parameter List. | NZCV | 117 | 70 |
|
||||
| `FRWB` | HEAD.DOS.ASM | ]1 = Read/Write flag <br />]2 = Command<br />]3 = Slot<br />]4 = Drive<br />]5 = Volume<br />]6 = Record<br />]7 = Byte Offset<br />]8 = Write Byte | Read or write a byte from or to a file. Use `FRWRTB` and `FRDB` instead of this, both of which call this macro. | NZCV | 779 | 404 |
|
||||
| `FWRTB` | HEAD.DOS.ASM | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record<br />]5 = Byte Offset<br />]6 = Write Byte | Write a byte to a file. | NZCV | 665 | 337 |
|
||||
| `FRDB` | HEAD.DOS.ASM | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record<br />]5 = Byte Offset<br />]6 = Write Byte (always 0) | Read a byte from a file. | NZCV | 700 | 357 |
|
||||
| `FRWR` | HEAD.DOS.ASM | ]1 = Read/Write flag<br />]2 = Command<br />]3 = Slot<br />]4 = Drive<br />]5 = Volume<br />]6 = Record<br />]7 = Byte Offset<br />]8 = Range Address<br />]TEMP = Range Length | Read or write a range of bytes in a file. Use `FRDR` or `FWRTR` instead of this macro directly. | NZCV | 846 | 451 |
|
||||
| `FRDR` | HEAD.DOS.ASM | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record<br />]5 = Byte Offset<br />]6 = Range Address<br />]7 = Range Length | Read a range of bytes from a file. | NZCV | 697 | 361 |
|
||||
| `FWRTR` | HEAD.DOS.ASM | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record<br />]5 = Byte Offset<br />]6 = Range Address<br />]7 = Range Length | Write a range of bytes to a file. | NZCV | 940 | 509 |
|
||||
| `sRWTS` | HEAD.DOS.ASM | ]1 = Slot<br />]2 = Drive<br />]3 = Volume <br />]4 = Track<br />]5 = Sector<br />]6 = Buffer<br />]7 = Command | Set the most common RWTS parameters. | NZCV | 228 | 141 |
|
||||
| `GRWTS` | HEAD.DOS.ASM | none | Execute the RWTS routine. | NZCV | 19 | 11 |
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### MAC.DOSFM.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------- | -------------- | ------------------------------------------------------------ | ----------------- | -------- | ------ | ----- |
|
||||
| `FCAT` | HEAD.DOS.ASM | ]1 = Slot <br />]2 = Drive | Catalog. | NZCV | 657 | 348 |
|
||||
| `FULCK` | HEAD.DOS.ASM | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive | File unlock. | NZCV | 629 | 353 |
|
||||
| `FLOCK` | HEAD.DOS.ASM | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive | File lock. | NZCV | 172 | 116 |
|
||||
| `FDEL` | HEAD.DOS.ASM | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive | File delete. | NZCV | 791 | 412 |
|
||||
| `FVFY` | HEAD.DOS.ASM | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive | File verify. | NZCV | 791 | 411 |
|
||||
| `FCLOS` | HEAD.DOS.ASM | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive | File close. | NZCV | 797 | 415 |
|
||||
| `FRENM` | HEAD.DOS.ASM | ]1 = Filename address<br />]2 = New filename address<br />]3 = Slot<br />]4 = Drive | File rename. | NZCV | 927 | 578 |
|
||||
| `FOPEN` | HEAD.DOS.ASM | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive<br />]4 = Volume<br />]5 = Record | File open. | NZCV | 828 | 433 |
|
||||
| `BLOAD` | SUB.FBLOAD.ASM | ]1 = Filename address<br />]2 = Load address<br />]3 = Slot<br />]4 = Drive<br />]5 = Volume | Load binary file. | NZCV | 3768 | 2735 |
|
||||
| `BSAVE` | SUB.FBSAVE.ASM | ]1 = Filename address<br />]2 = Load address<br />]3 = Range length<br />]4 = Slot<br />]5 = Drive<br />]6 = Volume | Save binary file. | NZCV | 5300 | 2758 |
|
||||
|
||||
|
||||
|
||||
### MAC.DOSMORE.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------- | ---------- | ---------- | -------------------------------------------- | -------- | ------ | ----- |
|
||||
| `DVER` | none | none | Get DOS version. | NZCV | 28 | 18 |
|
||||
| `DOSIN` | none | none | Check if DOS is loaded. | NZCV | 17 | 12 |
|
||||
| `ABAS` | none | none | Check if Applesoft is loaded. | NZCV | 40 | 29 |
|
||||
| `IBEX` | none | none | Check if Integer Basic program is running. | NZCV | 17 | 12 |
|
||||
| `ABEX` | none | none | Check if Applesoft Basic program is running. | NZCV | 26 | 18 |
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
# Disk #7: Conversion
|
||||
|
||||
|
||||
|
||||
The Conversion Collection contains macros and subroutines for converting between different data types. This currently includes macros for converting a:
|
||||
|
||||
- numeric value to an integer string
|
||||
- integer string to a numeric value
|
||||
- numeric value to a hexadecimal string
|
||||
- hexadecimal string to a numeric value
|
||||
- numeric value to a binary string
|
||||
- binary string to a numeric value
|
||||
|
||||
In future revisions, other conversions will include:
|
||||
|
||||
- string type conversions (preceding length byte, null-terminated, etc.)
|
||||
- string to array
|
||||
- array to string
|
||||
|
||||
Note that some of these subroutines are redundant due to the fact that some conversions are already available in the ROM. However, for the sake of understanding how these conversions work, they are provided here if for nothing more than illustration.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------- | ------------------ | -------------------------------- | ------------------------------------------- | -------- | ------ | ----- |
|
||||
| `I2STR` | SUB.HEX2INTASC.ASM | ]1 = Value to convert or address | Convert numeric value to integer string | NZCV | 290 | 172 |
|
||||
| `STR2I` | SUB.INTASC2HEX.ASM | ]1 = String address | Convert integer string to numeric value | NZCV | 415 | 196 |
|
||||
| `H2STR` | SUB.HEX2HEXASC.ASM | ]1 = Value to convert or address | Convert numeric value to hexadecimal string | NZCV | 97 | 59 |
|
||||
| `STR2H` | SUB.HEXASC2HEX.ASM | ]1 = String address | Convert hexadecimal string to numeric value | NZCV | 116 | 71 |
|
||||
| `B2STR` | SUB.HEX2BINASC.ASM | ]1 = Value to convert or address | Convert numeric value to binary string | NZCV | 262 | 167 |
|
||||
| `STR2B` | SUB.BINASC2HEX.ASM | ]1 = String address | Convert binary string to numeric value | NZCV | 501 | 331 |
|
||||
|
||||
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
## Introduction
|
||||
|
||||
The AppleIIAsm Library Collection is an array of subroutines and macros for the Apple II line of computers, aimed at providing a stable set of assembly routines for most common tasks. Additionally, this library is meant to ease the transition between programming in Applesoft BASIC and 6502 Assembly by not only providing the basic data structures and functions found in higher-level languages but also by providing a set a macros—currently dubbed AppleChop—that simulates the design and workflow of BASIC. A companion booklet to this library, *From Applesoft to AppleChop to Assembly,* provides a framework for making that transition.
|
||||
The AppleIIAsm Library is an array of subroutines and macros for the Apple II line of computers, aimed at providing a stable set of assembly routines for most common tasks. Additionally, this library is meant to ease the transition between programming in Applesoft BASIC and 6502 Assembly by not only providing the basic data structures and functions found in higher-level languages but also by providing a set a macros--currently dubbed AppleChop--that simulates the design and workflow of BASIC. A companion booklet to this library, *From Applesoft to AppleChop to Assembly,* provides a framework for making that transition.
|
||||
|
||||
These subroutines and macros are written for the Merlin 8 Pro assembler, which should run on any Apple II with 64k of memory (programs assembled with Merlin 8 Pro will run on machines with less than 64k, however). Since we are using 6502 Assembly here, however, it should not be too difficult to port the subroutines to other assemblers and even other systems like the Commodore 64, Nintendo Entertainment System, BBC Micro, and more. For a guide on using the Merlin Pro 8 Assembler, see the other companion booklet, *The New Merlin Pro 8 Quick Start User Guide*.
|
||||
These subroutines and macros are written for the Merlin 8 Pro assembler, which should run on any Apple II with 64k of memory (programs assembled with Merlin 8 Pro will run on machines with less than 64k, however). Since we are using 6502 Assembly here, it should not be too difficult to port the subroutines to other assemblers and even other systems like the Commodore 64, Nintendo Entertainment System, BBC Micro, and more. For a guide on using the Merlin Pro 8 Assembler, see the other companion booklet, *The New Merlin Pro 8 Quick Start User Guide*.
|
||||
|
||||
It should be noted that the core libraries in this collection---those on disks one to eleven---should be compatible with every iteration of the Apple II family, from the original Apple II in 1977 to the Apple IIGS in 1986. Disks beyond that core collection are considered bonus disks, and are dedicated to either creating libraries for specialized hardware (such as much of the IIGS, or the Mockingboard) or are there to serve as more complicated and integrated demos for the user to peruse.
|
||||
|
||||
|
|
@ -14,17 +14,17 @@ The primary audience for this manual is someone who is already familiar with 650
|
|||
|
||||
**Who is this manual NOT for?**
|
||||
|
||||
This manual is definitely not for someone completely unexposed to Assembly language,, but nor is it really aimed at 6502 experts. The collection itself can be used by beginner and expert alike, but whereas this manual would likely confuse the absolute beginner, an expert interested in optimizing their work (and these subroutines) will not find much help here. For those well-versed in 6502 Assembly, this collection might better serve as a prototyping system that then gets torn apart and optimized; for those barely versed in 6502 Assembly, this collection, and especially the AppleChop library, this collection will best serve to ease the transition between a standard knowedge of BASIC and the quirks of Assembly language (commenting is excessive in the libraries for this very reason). Both extremes may find this collection useful, but for wildly different reasons.
|
||||
This manual is definitely not for someone completely unexposed to Assembly language, but nor is it really aimed at 6502 experts. The collection itself can be used by beginner and expert alike, but whereas this manual would likely confuse the absolute beginner, an expert interested in optimizing their work (and these subroutines) will not find much help here. For those well-versed in 6502 Assembly, this collection might better serve as a prototyping system that then gets torn apart and optimized; for those barely versed in 6502 Assembly, this library, and especially the AppleChop collection, will best serve to ease the transition between a standard knowledge of BASIC and the quirks of Assembly language (commenting is excessive in the libraries for this very reason). Both extremes may find this collection useful, but for wildly different reasons.
|
||||
|
||||
As someone who spends a *lot* of time thinking about, writing about, and teaching different facets of technical writing (in its broadest sense), I can confirm the following: there are thousands of books written about the 6502 architecture and Assembly programming. I can also confirm that these books---as well as most websites---tend to approach the subject from a "writerly" position rather than a reader-centered one; that is, written for engineers and computer scientists who have already spent a lot of time and money understanding the theory, learning the jargon, and training themselves to be able to do things by muscle memory. That's great for established engineers, mathematicians, computer scientists and the like, as well as those who can afford to dedicate years of their lives (and again, gobs of $$$) to obtain a degree that qualifies them as entry level in the field. It is not so great, however, for beginners, hobbyists, or those trying to study it from a non-engineering theoretical perspective. That is, at least, part of the gap I am hoping to fill; after all, this book is part of my research for writing another book aimed at a non-technical audience.
|
||||
|
||||
That said, I myself would have failed quite readily without at least a few key texts and websites, and it would be remiss to not list them here. And if you're committed to learning this, know that there is no good replacement to sitting down, typing out a listing from a book, assembling it and then trying to figure out what the hell you just did---or what you did wrong! There is no doing without learning, and there is no learning without doing. At risk of pontificting, I believe many of us have forgotten this mantra, and the internet has not helped matters.
|
||||
That said, I myself would have failed quite readily without at least a few key texts and websites, and it would be remiss to not list them here. And if you're committed to learning this, know that there is no good replacement to sitting down, typing out a listing from a book, assembling it and then trying to figure out what the hell you just did---or what you did wrong! There is no doing without learning, and there is no learning without doing. At risk of pontificating, I believe many of us have forgotten this mantra, and the internet has not helped matters.
|
||||
|
||||
**Why Merlin Pro 8? Why not something...modern?**
|
||||
|
||||
Understanding how coding for a specific platform and a specific era works is not merely a matter of knowledge, but a matter of practice. Much of the way development happens, in computer software or not, is predicated on the apparatus in place that allows for it. Changing that apparatus, whether it be adding modern components like multiple open files, faster assembly, easier access and legibility and so on changes your understanding of how everything worked (and works). Especially with an ancient (and largely obsolete) language like 6502 assembly, few people are learning it to accomplish a practical task. Instead, we are approaching the topic more like an archaeologist or historical reenactor: going through the same motions to understand the topic cohesively. This is explained more thoroughly in the Preface.
|
||||
|
||||
That said, there is nothing inherently wrong with using modern tools—it just does not fit the goals for writing this library. Brutal Deluxe software has rewritten a more modern version of Merlin 16, and the CC65 compiler/assembler makes contemporary 6502 development far more efficient and less frustrating overall. If Merlin 8 Pro feels too dated—and to many, it will feel hopelessly so—by all means use these modern software packages. Just be aware that some substantial effort may be involved in rewriting the code here for different assemblers. If you must, I would suggest using an Apple II emulator like _AppleWin_ with a high speed setting for compile time---though be careful if so, as it is easy to miss error interruptions.
|
||||
That said, there is nothing inherently wrong with using modern tools--it just does not fit the goals for writing this library. Brutal Deluxe software has rewritten a more modern version of Merlin 16, and the CC65 compiler/assembler makes contemporary 6502 development far more efficient and less frustrating overall. If Merlin 8 Pro feels too dated--and to many, it will feel hopelessly so--by all means use these modern software packages. Just be aware that some substantial effort may be involved in rewriting the code here for different assemblers. If you must, I would suggest using an Apple II emulator like _AppleWin_ with a high speed setting for compile time---though be careful if so, as it is easy to miss error interruptions.
|
||||
|
||||
**Further Resources**
|
||||
|
||||
|
|
@ -79,3 +79,11 @@ A number of folk are doing work on 6502 or the Apple II on GitHub. While I canno
|
|||
- [CC65](https://github.com/cc65), a modern cross-compiling C compiler and assembler for 6502 systems. <https://github.com/cc65>
|
||||
- [PLASMA: The Proto-Language Assembler for All](https://github.com/dschmenk/PLASMA) --- this was originally written for the Apple II alone, but has recently expanded to other systems. <https://github.com/dschmenk/PLASMA>
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
[Return to Table of Contents](0.0%20Title_to_TOC)
|
||||
[Next: Package Overiew](3.0%20Package_Overview.md)
|
||||
|
|
@ -1,10 +1,10 @@
|
|||
## Package Overview
|
||||
|
||||
The **AppleIIAsm** package consists of 25 disks that contain thematically related subroutines, demos and utilities, as well as extra disks that hold minified versions of every subroutine for convenience. The contents of each disk and library are covered in Part II: Detailed Descriptions and Listings. The disks are ordered as follows:
|
||||
The **AppleIIAsm** package library consists of 25 disks that contain thematically related subroutines, demos and utilities, as well as extra disks that hold minified versions of every subroutine for convenience. The contents of each disk and collection are covered in Part II: Detailed Descriptions and Listings. The disks are ordered as follows:
|
||||
|
||||
- **Disk 0** BOOT (for setting up own environment)
|
||||
|
||||
### CORE LIBRARIES
|
||||
### CORE COLLECTIONS
|
||||
|
||||
- **Disk 1** REQUIRED (Required and Common Libraries)
|
||||
- **Disk 2** STDIO (Standard Input and Output Library)
|
||||
|
|
@ -38,3 +38,13 @@ The **AppleIIAsm** package consists of 25 disks that contain thematically relate
|
|||
- **Disk 24** IIGSAUDIO (IIGS AUDIO library) (3.5" diskette)
|
||||
- **Disk 25** IIGSGRAPHICS (IIGS Additional Graphics Mode Libraries) (3.5" diskette)
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[Return to Table of Contents](0.0%20Title_to_TOC)
|
||||
[Software Architecture](4.0%20Software_Architecture.md)
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -108,7 +108,7 @@ After necessary assembler directives, files should be loaded in the following or
|
|||
|
||||
**_Subroutine Independence_**
|
||||
|
||||
Beyond needing the core required library files as well as the hook files for the library category in question, a subroutine should be able to operate independently of other subroutines in the library. This will generally mean some wasted bytes here and there, but this can be remedied by the end programmer if code size is a major concern.
|
||||
Beyond needing the core required library files as well as the header files for the library collection in question, a subroutine should be able to operate independently of other subroutines in the library. This will generally mean some wasted bytes here and there, but this can be remedied by the end programmer if code size is a major concern.
|
||||
|
||||
**_Control Structures_**
|
||||
|
||||
|
|
@ -116,4 +116,15 @@ While a number of helpful, higher-level control structures are included as part
|
|||
|
||||
**_ASM Suffix_**
|
||||
|
||||
The .ASM suffix on most files in the collection are mainly used for GitHub and modern operating systems to associate the dumped text version of the source with a filetype.
|
||||
The .ASM suffix on most files in the collection are mainly used for GitHub and modern operating systems to associate the dumped text version of the source with a filetype.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
[Return to Table of Contents](0.0%20Title_to_TOC)
|
||||
|
||||
[Quick Reference Introduction](5.0%20Quick_Reference_TOC.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,21 @@
|
|||
# Quick Reference: Macros
|
||||
|
||||
- [Disk 1: REQUIRED Library Macros](./6.0%20Quick_Reference_D1_MAC.REQUIRED.md)
|
||||
- [Disk 2: STDIO Library Macros](./7.0%20Quick_Reference_D2_MAC.STDIO.md)
|
||||
- [Disk 3: Arrays Library Macros](./8.0%20Quick_Reference_D3_MAC.ARRAYS.md)
|
||||
- [Disk 1: REQUIRED Collection Macros](./6.0%20Quick_Reference_D1_MAC.REQUIRED.md)
|
||||
- [Disk 2: STDIO Collection Macros](./7.0%20Quick_Reference_D2_MAC.STDIO.md)
|
||||
- [Disk 3: Arrays Collection Macros](./8.0%20Quick_Reference_D3_MAC.ARRAYS.md)
|
||||
- [Disk 4: Math Collection Macros](./9.0%20Quick_Reference_D4_MAC.MATH.md)
|
||||
- [Disk 5: Strings Collection Macros](./10.0%20Quick_Reference_D5_MAC.STRINGS.md)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
[Return to Table of Contents](0.0%20Title_to_TOC)
|
||||
|
||||
[Disk 1 -- REQUIRED Macros and Subroutines](6.0%20Quick_Reference_D1_MAC.REQUIRED.md)
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
## Disk 1 Macros: The Required Library
|
||||
## 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:
|
||||
|
||||
|
|
@ -66,6 +66,10 @@ Be sure to consult the detailed reference for Disk 1: The Required Library for f
|
|||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
### MAC.ALIAS.8080.ASM
|
||||
|
||||
| MACRO | DEPENDENCIES | PARAMETERS | ACTION | CYCLES | BYTE |
|
||||
|
|
@ -98,6 +102,10 @@ Be sure to consult the detailed reference for Disk 1: The Required Library for f
|
|||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
### MAC.ALIAS.Z80.ASM
|
||||
|
||||
| MACRO | DEPENDENCIES | PARAMETERS | ACTION | CYCLES | BYTE |
|
||||
|
|
@ -111,3 +119,13 @@ Be sure to consult the detailed reference for Disk 1: The Required Library for f
|
|||
|`SCF`|none|none| `SEC` equivalent|2|1|
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
[Return to Table of Contents](0.0%20Title_to_TOC)
|
||||
|
||||
[Disk 2 Quick Reference -- STDIO Macros and Subroutines](7.0%20Quick_Reference_D2_MAC.STDIO.md)
|
||||
|
|
@ -0,0 +1,114 @@
|
|||
## Disk 2 Macros: The STDIO Collection
|
||||
|
||||
Disk 2: STDIO contains four macro files, each dedicated to different aspects of standard input and output. They are:
|
||||
|
||||
- [MAC.COUT.STDOUT.ASM](#mac.cout.stdout.asm)
|
||||
- This package contains macros that use the Apple II's COUT functionality. This can range from simple printing to the screen and moving the cursor position to word-wrapping a null-terminated string to the screen until the entire string is read.
|
||||
- [MAC.SCRMEM.STDIO.ASM](#mac.scrmeme.stdio.asm)
|
||||
- This package contains macros that deal directly with screen memory. This means that the macros tend to be **fast**, at least compared to COUT; thus, most of the macros found here have to do with plotting more complicated shapes to the screen rather than focus on simple text output alone. It should be noted that because these macros do not inform COUT of any screen memory changes, they do not exactly play well with using COUT.
|
||||
- [MAC.STDIN.ASM](#mac.stdin.asm)
|
||||
- These macros focus on input from the keyboard and paddles. More unique input devices, like a mouse, may be supported in the future.
|
||||
- [MAC.MISC.STDIO.ASM](#mac.misc.stdio.asm)
|
||||
- This package contains macros that do not easily fit in with any of the preceding three groupings. Some of these macros may move to different packages in the future, as their relevance to one set of functionalities rather than another becomes more apparent.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### MAC.COUT.STDOUT.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------- | ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ------ | ----- |
|
||||
| `CURB` | none | ]1 = # of spaces | Move cursor backward | NZCV | 10+ | 7 |
|
||||
| `CURD` | none | ]1 = # of spaces | Move cursor Downward | NZCV | 10+ | 7 |
|
||||
| `CURF` | none | ]1 = # of spaces | Move cursor forward | NZCV | 10+ | 7 |
|
||||
| `CURU` | none | ]1 = # of spaces | Move cursor upward | NZCV | 10+ | 7 |
|
||||
| `PRN` | `DPRINT`<br />`XPRINT` | ]1 = Memory address or literal string | Print a literal string or a null-terminated string to the display | NZCV | 159+ | 34 |
|
||||
| `SCPOS` | none | ]1 = Column <br/>]2 = Row | Set Cursor Position | NZCV | 10+ | 8 |
|
||||
| `SETCX` | none | ]1 = Column | Set Cursor Column | | 10+ | 8 |
|
||||
| `SETCY` | none | ]1 = Row | Set Cursor Row | NZCV | 4+ | 5 |
|
||||
| `SPRN` | `PRNSTR` | ]1 = memory address of string | Display a regular string | NZCV | 147+ | 35 |
|
||||
| `TMORE` | `TXTMORE` | ]1 = String Address<br />]2 = Line Length<br />]3 = Pause Interval | Word-wrap a null-terminated string to the display, pausing either at a regular line interval or every time a linefeed is encountered. | NZCV | 482+ | 472 |
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
### MAC.SCRMEM.STDIO.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ------ | ----- |
|
||||
| `CPUT` | `TXTPUT` | ]1 = X-pos<br/>]2 = Y-pos<br/>]3 = character | Plot a character at the given X,Y coordinate | NZCV | 91+ | 31 |
|
||||
| `RCPOS` | none | ]1 = Column <br/>]2 = Row | Return a character located on screen at given coordinate | NZCV | 10+ | 6 |
|
||||
| `SPUT` | `STRPUT` | ]1 = X-pos<br>]2 = Y-pos<br>]3 = String address | Plot a string at the given X,Y coordinate | NZCV | 124+ | 50 |
|
||||
| `TCIRC` | `TCIRCLE` | ]1 = Center X-position<br>]2 = Center Y-position<br>]3 = Radius<br>]4 = Fill value | Create a circle with a text character and display it at given screen coordinates | NZCV | 627+ | 290 |
|
||||
| `TCLR` | `TXTCLR` | ]1 = Fill Value | Fill the text screen with a given character | NZCV | 50+ | 42 |
|
||||
| `THLIN` | `THLINE` | ]1 = X-pos origin<br>]2 = X-pos destination<br>]3 = Y-position <br>]4 = Fill value | Create a horizontal line on the screen made of a single fill character | NZCV | 107+ | 38 |
|
||||
| `TVLIN` | `TVLINE` | ]1 = Y-pos origin<br>]2 = Y-pos destination<br>]3 = X-position <br>]4 = Fill value | Create a vertical line on the screen made of a single fill character | NZCV | 104+ | 45 |
|
||||
| `TLINE` | `TBLINE` | ]1 = X origin <br>]2 = Y origin <br>]3 = X dest <br>]4 = Y dest <br>]5 = fill value | Create a diagonal line an X,Y origin to an X,Y destination with a single fill character | NZCV | 305+ | 198 |
|
||||
| `TREC` | `TRECT` | ]1 = X Origin<br />]2 = Y Origin <br />]3 = X Destination<br />]4 = Y Destination<br />]5 = Fill Value | Create an unfilled rectangle on the text screen that is composed of a single character | NZCV | 362+ | 115 |
|
||||
| `TRECF` | `TRECTF` | ]1 = X origin <br>]2 = Y origin <br>]3 = X dest<br>]4 = Y dest<br>]5 = Fill vallue | Create a filled rectangle on the screen made of a single fill character | NZCV | 157+ | 77 |
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
### MAC.STDIN.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------ | ---------- | ------------------- | ---------------------------------------------------- | -------- | ------ | ----- |
|
||||
| `GKEY` | none | none | Wait for a keypress and hold the key value in **.A** | NZCV | 11+ | 7 |
|
||||
| `INP` | `SINPUT` | none | input a line of text from the keyboard | NZCV | 64+ | 41 |
|
||||
| `PBX` | none | ]1 = paddle button | Read paddle button state | NZCV | 8+ | 8 |
|
||||
| `PDL` | none | ]1 = paddle address | Read the specified paddle value (0..255) | NZCV | 8+ | 5 |
|
||||
| `WAIT` | none | none | wait for a keypress | NZCV | 9+ | 8 |
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
### MAC.MISC.STDIO.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------- | ---------- | -------------------------------------- | ------------------------------- | -------- | ------ | ----- |
|
||||
| `COL40` | none | none | Enter 40-column mode | NZCV | 8+ | 5 |
|
||||
| `COL80` | none | none | Enter 80-column mode | NZCV | 8+ | 5 |
|
||||
| `DIE80` | none | none | End 80-column mode | NZCV | 8+ | 5 |
|
||||
| `TCTR` | `TXTCENT` | ]1 = short string <br>]2 = long string | Center a string in a given line | NZCV | 47+ | 27 |
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
[Return to Table of Contents](0.0%20Title_to_TOC)
|
||||
|
||||
[Disk 3 Quick Reference -- Array Macros and Subroutines](8.0%20Quick_Reference_D3_MAC.ARRAYS)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,79 @@
|
|||
## Disk 3 Macros: The Array Collection
|
||||
|
||||
Disk 3: ARRAYS contains four macro files that have the same kinds of macros for different kinds of arrays; that is, each macro file is dedicated to an array of 8-bits or 16-bits and one or two dimensions, and contains the functionality to initialize an array, get data from it and put data into it. The are as follows:
|
||||
|
||||
- [MAC.ARR8B1D.ASM](#mac.arr8b1d.asm)
|
||||
- This packages contains `DIM`, `GET` and `PUT` macros for eight-bit, one-dimensional arrays.
|
||||
- [MAC.ARR8B2D.ASM](#mac.arr8b2d.asm)
|
||||
- This packages contains `DIM`, `GET` and `PUT` macros for eight-bit, two-dimensional arrays.
|
||||
- [MAC.ARR16B1D.ASM](#mac.arr16b1d.asm)
|
||||
- This packages contains `DIM`, `GET` and `PUT` macros for sixteen-bit, one-dimensional arrays.
|
||||
- [MAC.ARR16B2S.ASM](#mac.arr16b2d.asm)
|
||||
- This packages contains `DIM`, `GET` and `PUT` macros for sixteen-bit, two-dimensional arrays.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### MAC.ARR8B1D.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------- | -------- | ------ | ----- |
|
||||
| `DIM81` | `ADIM81` | ]1 = Array addr <br>]2 = # of elements <br>]3 = element size <br>]4 = fill value | Initialize a 1D, 8-bit array | NZCV | 234+ | 146 |
|
||||
| `GET81` | `AGET81` | ]1 = Array addr <br>]2 = Element Index | Get a value from an element in a 1D, 8-bit array. | NZCV | 193+ | 125 |
|
||||
| `PUT81` | `APUT81` | ]1 = Source addr <br>]2 = Array addr <br>]3 = Element Index | Put a value into an element in a 1D, 8-bit array. | NZCV | 216+ | 131 |
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
### MAC.ARR8B2D.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------- | -------- | ------ | ----- |
|
||||
| `DIM82` | `ADIM82` | ]1 = Array addr <br>]2 = 1st dimension length <br>]3 = 2nd dimension length <br>]4 = fill value | Initialize a 2D, 8-bit array | NZCV | 355+ | 228 |
|
||||
| `GET82` | `AGET82` | ]1 = Array addr <br>]2 = 1st Dimension Index <br>]3 = 2nd Dimension Index | Get a value from an element in a 2D, 8-bit array. | NZCV | 340+ | 255 |
|
||||
| `PUT82` | `APUT82` | ]1 = Source addr <br>]2 = Destination addr <br>]3 = 1st Dimension Index <br>4] = 2nd Dimension Index | Put a value into an element in a 2D, 8-bit array. | NZCV | 352+ | 223 |
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
### MAC.ARR16B1D.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| -------- | ---------- | ------------------------------------------------------------ | -------------------------------------------------- | -------- | ------ | ----- |
|
||||
| `DIM161` | `ADIM161` | ]1 = Array Addr <br>]2 = # of elements <br>]3 = Element length <br>]4 = Fill Value | Initialize a 1D, 16-bit array | NZCV | 271+ | 165 |
|
||||
| `GET161` | `AGET161` | ]1 = Array addr <br>]2 = Element Index | Get a value from an element in a 1D, 16-bit array. | NZCV | 223+ | 130 |
|
||||
| `PUT161` | `APUT161` | ]1 = Source addr <br>]2 = Array addr <br>]3 = Element index | Put a value into an element in a 1D, 16-bit array. | NZCV | 238+ | 148 |
|
||||
|
||||
|
||||
|
||||
----
|
||||
|
||||
|
||||
|
||||
### MAC.ARR16B2D.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| -------- | ---------- | ------------------------------------------------------------ | -------------------------------------------------- | -------- | ------ | ----- |
|
||||
| `DIM162` | `ADIM162` | ]1 = Array Address<br />]2 = First Dimension Element Count<br />]3 = Second Dimension Element Count<br />]4 = Byte size of Elements<br />]5 = Default Fill Value | Initialize a 2D, 16-bit array | NZCV | 464+ | 373 |
|
||||
| `GET162` | `AGET162` | ]1 = Array Address<br />]2 = First Dimension Element Address<br />]3 = Second Dimension Element Address | Get a value from an element in a 2D, 16-bit array. | NZCV | 436+ | 263 |
|
||||
| `PUT162` | `APUT162` | ]1 = Source Address<br />]2 = Destination Array Address<br />]3 = First Dimension Element Address<br />]4 = Second Dimension Element Address | Put a value into an element in a 2D, 16-bit array. | NZCV | 352+ | 223 |
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
[Return to Table of Contents](0.0%20Title_to_TOC)
|
||||
|
||||
|
|
@ -0,0 +1,125 @@
|
|||
# Disk 4: Basic Math and Pseudorandom Numbers
|
||||
|
||||
|
||||
|
||||
The Basic Math collection contains macros and subroutines dedicated to addition, subtraction, multiplication and division operations, as well as a 16-bit comparison routine and several macros for generating pseudorandom numbers. These are grouped into several macro files, as such:
|
||||
|
||||
|
||||
|
||||
- [MAC.D8BY.ASM](#mac.d8by.asm)
|
||||
- This group contains macros that are used to divide an 8-bit number by a fixed constant between 2 and 10.
|
||||
- [MAC.M8BY.ASM](#mac.m8by.asm)
|
||||
- This group contains macros that are used to multiply an 8-bit number by a fixed constant between 2 and 10.
|
||||
- [MAC.M16BY.ASM](#mac.m16by.asm)
|
||||
- This group contains macros that are used to multiply a 16-bit number by a fixed constant between 2 and 10, as well as by 100.
|
||||
- [MAC.MATH8.ASM](#mac.math8.asm)
|
||||
- This group contains macros for adding, subtracting, multiplying and dividing 8-bit numbers.
|
||||
- [MAC.MATH16.ASM](#mac.math16.asm)
|
||||
- This group contains macros for adding, subtracting, multiplying and dividing 16-bit numbers. It also includes a macro for 16-bit comparison.
|
||||
- [MAC.MATHRND.ASM](#mac.mathrnd.asm)
|
||||
- This group contains macros for managing and generating pseudorandom numbers.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### MAC.D8BY.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| -------- | ---------- | ---------- | ------------------------------- | -------- | ------ | ----- |
|
||||
| `D8BY2` | none | none | Divide an 8-bit number by two | NZCV | 6 | 4 |
|
||||
| `D8BY3` | none | none | Divide an 8-bit number by three | NZCV | 29 | 19 |
|
||||
| `D8BY4` | none | none | Divide an 8-bit number by four | NZCV | 8 | 5 |
|
||||
| `D8BY5` | none | none | Divide an 8-bit number by five | NZCV | 34 | 21 |
|
||||
| `D8BY6` | none | none | Divide an 8-bit number by six | NZCV | 36 | 21 |
|
||||
| `D8BY7` | none | none | Divide an 8-bit number by seven | NZCV | 33 | 19 |
|
||||
| `D8BY8` | none | none | Divide an 8-bit number by eight | NZCV | 10 | 6 |
|
||||
| `D8BY9` | none | none | Divide an 8-bit number by nine | NZCV | 36 | 21 |
|
||||
| `D8BY10` | none | none | Divide an 8-bit number by ten | NZCV | 36 | 21 |
|
||||
|
||||
|
||||
|
||||
### MAC.M8BY.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| -------- | ---------- | ---------- | --------------------------------- | -------- | ------ | ----- |
|
||||
| `M8BY2` | none | none | Multiply an 8-bit number by two | NZCV | 6 | 4 |
|
||||
| `M8BY3` | none | none | Multiply an 8-bit number by three | NZCV | 6 | 4 |
|
||||
| `M8BY4` | none | none | Multiply an 8-bit number by four | NZCV | 8 | 5 |
|
||||
| `M8BY5` | none | none | Multiply an 8-bit number by five | NZCV | 15 | 10 |
|
||||
| `M8BY6` | none | none | Multiply an 8-bit number by six | NZCV | 15 | 10 |
|
||||
| `M8BY7` | none | none | Multiply an 8-bit number by seven | NZCV | 33 | 20 |
|
||||
| `M8BY8` | none | none | Multiply an 8-bit number by eight | NZCV | 10 | 6 |
|
||||
| `M8BY9` | none | none | Multiply an 8-bit number by nine | NZCV | 18 | 11 |
|
||||
| `M8BY10` | none | none | Multiply an 8-bit number by ten | NZCV | 18 | 11 |
|
||||
|
||||
|
||||
|
||||
### MAC.M16BY.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| --------- | ---------- | ---------- | --------------------------------------- | -------- | ------ | ----- |
|
||||
| `M16BY2` | none | none | Multiply a 16-bit number by two | NZCV | 20 | 13 |
|
||||
| `M16BY3` | none | none | Multiply a 16-bit number by three | NZCV | 47 | 32 |
|
||||
| `M16BY4` | none | none | Multiply a 16-bit number by four | NZCV | 37 | 24 |
|
||||
| `M16BY5` | none | none | Multiply a 16-bit number by five | NZCV | 46 | 30 |
|
||||
| `M16BY6` | none | none | Multiply a 16-bit number by six | NZCV | 58 | 38 |
|
||||
| `M16BY7` | none | none | Multiply a 16-bit number by seven | NZCV | 72 | 47 |
|
||||
| `M16BY8` | none | none | Multiply a 16-bit number by eight | NZCV | 34 | 21 |
|
||||
| `M16BY9` | none | none | Multiply a 16-bit number by nine | NZCV | 62 | 36 |
|
||||
| `M16BY10` | none | none | Multiply a 16-bit number by ten | NZCV | 66 | 39 |
|
||||
| `M16BY1H` | none | none | Multiply a 16-bit number by one hundred | NZCV | 124 | 70 |
|
||||
|
||||
|
||||
|
||||
### MAC.MATH8.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------ | ---------- | ------------------------------------------- | -------------------------------------- | -------- | ------ | ----- |
|
||||
| `ADD8` | none | ]1 = number to add <br />]2 = number to add | Add two 8-bit numbers | NZCV | 21 | 15 |
|
||||
| `SUB8` | none | ]1 = Minuend </br>]2 = Subtrahend | Subtract one 8-bit number from another | NZCV | 21 | 15 |
|
||||
| `MUL8` | `MULTU8` | ]1 = Multiplicand<br />]2 = Multiplier | Multiply two 8-bit numbers | NZCV | 97 | 56 |
|
||||
| `DIV8` | `DIVDU8` | ]1 = Dividend<br />]2 = Divisor | Divide one 8-bit number by another | NZCV | 75 | 43 |
|
||||
|
||||
|
||||
|
||||
### MAC.MATH16.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| ------- | ---------- | ------------------------------------------------------------ | --------------------------------------- | -------- | ------ | ----- |
|
||||
| `ADD16` | `ADDIT16` | ]1 = First number to add<br />]2 = Second number to add | Add two 16-bit numbers | NZCV | 78 | 51 |
|
||||
| `SUB16` | `SUBT16` | ]1 = Minuend<br >]2 = Subtrahend | Subtract one 16-bit number from another | NZCV | 79 | 51 |
|
||||
| `MUL16` | `MULTU16` | ]1 = Multiplier<br />]2 = Multiplicand | Multiply two 16-bit numbers | NZCV | 144 | 91 |
|
||||
| `DIV16` | `DIVDU16` | ]1 = Dividend<br />]2 = Divisor | Divide one 16-bit number by another | NZCV | 133 | 81 |
|
||||
| `CMP16` | `COMP16` | ]1 = First Comparison Number <br />]2 = Second Comparison Number | Compare one 16-bit number to another | NZCV | 100 | 53 |
|
||||
|
||||
|
||||
|
||||
### MAC.MATHRND.ASM
|
||||
|
||||
| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
|
||||
| -------- | ---------- | ------------------------------------- | --------------------------------------------------------- | -------- | ------ | ----- |
|
||||
| `RNDEOR` | none | ]1 = Seed <br />]2 = EOR Index | Set the seed and magic number value | NZCV | 30 | 22 |
|
||||
| `RNDMZ` | none | ]1 = Seed<br />]2 = EOR Magic Number | Set the seed and set the magic number index | NZCV | 56 | 35 |
|
||||
| `RND8` | `RAND8` | none | Generate a value between 0 and 255 | NZCV | 51 | 30 |
|
||||
| `RAND` | `RANDB` | ]1 = Low bounds<br />]2 = High bounds | Generate a value between a given low value and high value | NZCV | 263 | 171 |
|
||||
| `RND16` | `RAND16` | none | Generate a value between 0 and 65,355 | NZCV | 101 | 63 |
|
||||
|
||||
Loading…
Reference in New Issue