This documentation is currently being updated to reflect massive changes between version 0.3 and the next release, 0.5. Generally, these updates are happening in the order of disks: STDIO, then COMMON, etc. Once this is finished, v0.5.0 will go live, and future updates will be piecemeal, by and large, rather than in large chunks. Until then, use the internal documentation (comments) for macro and subroutine usage.
This is a general purpose library in 6502 Assembly for the Apple II. Originally, I began this project as research for a platform study of the Apple \]\[ system, learning Assembly for the first time. However, after speaking to a number of folk who are still actively involved in a community of enthusiasts, I noticed that there was no cohesive place for a first-time learner to find well-documented code, basic data structures and control loops, or even a good and intuitive listing of hooks for the system. There are plenty of books--some very old, some very new--that detail these things somewhat cohesively and are fantastic resources for beginners, but very few of them adequately serve as an good basis for understanding the platform as a whole. There are also many webpages out there dedicated to this matter--but as is the nature of the Internet, they are fractured resources that come and go at the blink of an eye. Thus, Appl\]\[AsmLib began.
Ultimately, my aim is to create a large enough collection of routines to address any domain of development for the Apple II family in Assembly while maintaining an ease of access to beginners that is hard to come by. I'll do my best to acknowledge when a routine is inspired by (or mostly copied from) another source, and will exclude them from the Apache License 2.0 when necessary; I hope to replace anything of this sort with original work as I revise. If you find your own source here, but would rather it not be here, please reach out to me and I'll remove it immediately.
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, it's 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, mathemeticians, 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.
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, compiling 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; but maybe these can help.
* Roger Wagner, Chris Torrence. [_Assembly Lines: The Complete Book_](https://www.amazon.com/Assembly-Lines-Complete-Roger-Wagner/dp/1312089407/). May 10, 2017.
* Lance A. Leventhal, Winthrop Saville. _6502 Assembly Language Subroutines_. 1982.
* Don Lancaster. _Assembly Cookbook for the Apple II, IIe_. 1984, 2011.
* Mark Andrews. _Apple Roots: Assembly Language Programming for the Apple IIe and IIc. 1986.
* CW Finley, Jr., Roy E. Meyers. _Assembly Language for the Applesoft Programmer_. 1984.
* Randy Hyde. _Using 6502 Assembly Language_. 1981.
* Glen Bredon. _Merlin Pro Instruction Manual_. 1984.
More books have been written over the past forty years than could be read within a reasonable timeframe. However, I have found some books more fruitful than others in understanding both the technical aspects of the Apple \]\[ as well as the cultural ones. If you know of any essential books or websites that are missing here, by all means get in touch or contribute it here yourself!
* Bill Martens, Brian Wiser, William F. Luebbert, Phil Daley. [_What's Where in the Apple, Enhanced Edition: A Complete Guide to the Apple \]\[ Computer_.](https://www.amazon.com/gp/product/136517364X/) October 11, 2016.
* David L. Craddock. [_Break Out: How the Apple II Launched the PC Gaming Revolution_](https://www.amazon.com/gp/product/0764353225/). September 28, 2017.
* Steven Weyhrich. [_Sophistication & Simplicity: The Life and Times of the Apple II Computer_](https://www.amazon.com/gp/product/0986832278/). December 1, 2013.
* Ken Williams, Bob Kernagham, Lisa Kernagham. [_Apple II Computer Graphics_](https://www.amazon.com/gp/product/B01FIXG7ZK/). November 3, 1983.
* Lon Poole. [_Apple II Users' Guide_.](https://www.amazon.com/gp/product/0931988462/). 1981.
A number of folk are doing work on 6502 or the Apple II on GitHub. While I cannot possibly list each and every one (that's what the search function is for!), these are projects I have found particularly useful, informative, entertaining, or inspiring.
* [Prince of Persia Apple II Source Code](https://github.com/fabiensanglard/Prince-of-Persia-Apple-II), by Jordan Mechner
* [Doss33FSProgs](https://github.com/deater/dos33fsprogs), programs for manipulating the DOS 3.3 filesystem
* [ADTPro](https://github.com/ADTPro/adtpro), a requirement for anyone working with real Apple II hardware today.
* [CC65](https://github.com/cc65), a modern cross-compiling C compiler and assembler for 6502 systems.
* [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.
Each sub-library will have a hooks file, a var file, and a mac file. All subroutines within that sub-library will require the hooks file to be included at the top of the main listing, and the var file included directly before including the subroutine (usually at the end of the main program). Additionally, every subroutine requires the use of the required header file, required library file, and required var file.
* HOOKS files: these include various hooks that are used by the sub-library's subroutines. Additional hooks that may be used by the end programmer are commented out.
* VAR files: these carry temporarily labeled variables and equates for the sub-library's operation. All subroutines use the variables defined here rather than create their own. Note that because the labels are temporary, it is necessary to include the var file directly before including the subroutines in question.
* MAC files: the macros for a given sub-library are included here, and are included by the "USE" pseudo-op rather than PUT.
* HEAD file: The required library uses a header file that all sub-libraries and subroutines rely on. This should be included directly after setting the memory address.
* LIB file: the required library comes in a single package rather than in separate subroutines. This must be included prior to the inclusion of other sub-libraries.
### Naming Conventions
#### Filenames
Given the lack of directory structures in DOS 3.3, we are using a filename precursed extension system. The extensions should be applied to a filename in this order:
* MIN: signifies that the code has been stripped of comments
* DEMO: signifies that the program is a sub-library demo
Additionally, Merlin Appends a ".S" to the end of a filename if it is saved as a source, and prepends the file with "T." to signify it being a text file. This prepended T. overrides our own naming conventions.
In Merlin 8 Pro, assembler variables are preceded by a ] sign. These variables are temporarily assigned, and can be overwritten further down in the code. Unless highly impractical, constant hooks should use native assembly's system of assigning labels (just the label), as should hook entry points. The exception to this is within macro files, as these could easily lead to label conflicts.
Local labels are preceded by a : sign in Merlin Pro 8. When at all possible, local subroutines should have local labels. This does not apply to Merlin variables.
#### Macros
Macros should named with regard to mneumonic function, when possible, and should not exceed five characters unless absolutely necessary. Additionally, macros may use the following prefixes to signify their classification:
*@: signifies a higher-level control structure, such as @IF,@ELSE,@IFX.
* \_: signifies a macro mostly meant to be used internally, though it may have limited use outside of that context.
### Subroutine Independence
Beyond needing the core required library files as well as the hook and variable 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.
### Control Structures
While a number of helpful, higher-level control structures are included as part of the core required library, subroutines in the library itself should refrain from using this shorthand. Control Structure Macros are preceded with a '@' sign to signify their classification as such. Exceptions can be given to control structures that merely extend existing directives for better use, such as BEQL being used to branch beyond the normal byte limit; such macros forego the preceding @-sign.
### Parameter Passing
As a rule of thump, if more than three bytes are being passed to a subroutine, it happens via pushing those parameters to the stack. Otherwise, the .A, .X, and .Y registers are used. When passing an address or other 16-bit value, the low byte should be put into register .A, and the high byte in register .X.
### Literal and Indirect Passing
All macros should accept either a literal value (\#) or an indirect reference via simply passing the address that holds another address. The required macro library sorts out which value will be passed to the subroutine at assembly-time.
For the sake of beginners, *at least* every other directive should have an inline comment that describes what that line, or two lines, is accomplishing. Inline comments are added at the end of a line with a semicolon to denote the comment.
All subroutines require headers that document its input, output, register and memory destructions, minimum number of cycles used, and the size of the subroutine in bytes.
If a section of code needs more explanation than can be explained at the end of a line (a common issue, since there is limited space on the Apple II screen), these should be placed just above the code in question using asterisks to denote the line is a comment. Have a blank comment line before and after the comment with only one asterisk, while using two asterisks for the lines with actual comments.
Every Macro and subroutine should have an entry in the the table of contents, cheat sheet area, calls and clobbers list, and detailed descriptions. Detailed descriptions should include the information in the tables as well as a more abstract description of what the subroutine accomplishes, and how it does so. Indented copy of the code in question may also be presented for easier reference than supplied by Merin 8 Pro.
Each disk contains a single Macro (.mac) file, one or more subroutine files related to the overarching theme of the disk, and a "minified" version of the mac and subroutine files that the entire library relies upon. Additionally, each library has a correlating .hooks file for declaring useful hooks at the beginning of a program used in that library's operations, as well as a variable file that must be included with any subroutine's inclusion into the main listing.
In the following disk descriptions, we'll be listing the .mac contents that are relevant to the theme of the disk only, as many of the macros are calls to single subroutines. A table in section XXX lists the calls each macro makes to each subroutine, and the same information can be obtained from the detailed descriptions of macros and subroutines.
This disk is dedicated to Standard Input/Output operations, and a couple non-standard ones. Note that this is for 40-column mode only in order to keep compatibility with earlier hardware, and focuses on screen output alone in order to help with execution speed. However, most of these subroutines will work in 80col mode, with the exception of those that directly read or write the screen memory.
This disk is dedicated to common and useful subroutines that don't necessarily fit neatly into another category worth dedicating an entire disk to, as well as the fully commented code for the required libraries and macros that exist on every disk in minified form.
This disk contains libraries and subroutines related to the management of 8-bit and 16-bit one-dimensional and two-dimensional arrays that hold n-length elements. "8-bit" and "16-bit" refers to the number of elements the arrays can hold.
* MAC.ARRAYS
*`DIM81`: Create a 1D, 8-bit array at a given address with a given element size and number of elements.
*`DIM82`: Create a 2D, 8-bit array at a given address with a given element size and number of elements in each dimension.
*`DIM161`: Create a 1D, 16-bit array.
*`DIM162`: Create a 2D, 16-bit array.
*`GET81`: Get the element at the given index in a 1D, 8-bit array.
*`GET82`: Get the element at the given index in a 2D, 8-bit array.
*`GET161`: Get an element from a 1D, 16-bit array.
*`GET162`: Get an element from a 2D, 16-bit array.
*`PUT81`: Put a value (literal or memory address) into a 1D, 8-bit array at the given index.
*`PUT82`: Put a value into a 2D,8-bit array at the given index.
This disk hold routines related to standard mathematical calculations for signed and unsigned integer math; macros for using Woz's floating-point math routines will be added in the future. Note that this only includes some rather basic math functions; more complicated problems should be addressed by the main program using the libraries.
This disk holds routines and macros related to string and substring manipulation. In the future, certain tasks like "TONUM" and "TOSTR" may be relegated to their own disk for data type conversion routines.
* stdio80.mac: stdio library for 80-column output. Most of these will be identical to the routines on the stdio disk.
*`80CB`: Move Cursor Backward by [n] spaces
*`80CD`: Move Cursor Down by [n] spaces
*`80CF`: Move Cursor Forward by [n] spaces
*`80CU`: Move Cursor Up by [n] spaces
*`80INP`: String Input Macro
*`80PBX`: Read State of Paddle Button [x]
*`80PCR`: Print Carraige Return
*`80PDL`: Read Current Paddle State
*`80PRN`: Flexible (screen) Printing routine
*`80RCP`: Read Cursor Position
*`80SCP`: Set Cursor position at [x],[y]
*`80SCX`: Set Cursor Horizontal Position
*`80SCY`: Set Cursor Vertical Position
*`80TFIL`: Text Fill square [x1],[x2],[y1],[y2] with Character [n]
*`80THLN`: Text Horizontal Line Fill with Character [n]
*`80TVLN`: Text Vertical Line Fill with Character [n]
* 80to40.mac: a simple set of macros that calls the 80-column macros when 40-column macros are invoked. Obviously, the 40-column stdio.mac cannot be used simultaneously.
The following table shows which subroutines each Macro calls, along with the resulting registers, flags, and memory locations clobbered. This is up to date for version 0.3.0. Note that by "clobbered" here, I don't mean that the register or memory location has trash in it; it's just been altered in some way. For list of what useful imformation is passed after a Macro is executed, see [the cheat sheet](#macro-usage-cheat-sheet).
Once Macros are mostly finished in how they are called, you can find how to use them here. New versions, of course, always run the risk of changing something integral; This cheat sheet will be updated accordingly.