8.3 KiB
AppleIIASM Architecture
AppleIIAsmLib follows certain conventions due to hardware limitations, operating system requirements, ease of reading, program flow and just plain old personal preference. While there might be times when these conventions are eschewed or changed entirely, you can reasonably expect, and be expected to follow, adherence to the following architecture. Note that this architecture is designed to be fairly easily break apart in order to help with optimization after initial prototype is finished.
Naming Conventions
Files
Given the lack of directory structures in DOS 3.3, we are using a filename prefixes to indicate file types rather than suffixes. The extensions should be applied to a filename in this order:
- MIN: signifies that the code has been stripped of comments
- HEAD: indicates that this should be included first before the rest of the library. It holds hooks, variables, and subroutines necessary for the rest of the library to function.
- SUB: signifies that the file holds a subroutine
- MAC: signifies a collection of macros
- LIB: signifies a collection of subroutines
- DEMO: signifies that the program is a sub-library demo
- <FILENAME>: the actual name of the subroutine, macro, our other file.
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.
Sample Filenames
- T.MIN.MAC.STDIO
- T.SUB.TFILLA
- T.MIN.LIB.REQUIRED
- T.DEMO.STDIO
Variables
In Merlin Pro 8, 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 Hooks
Local labels are preceded by a : sign (colon) in Merlin Pro 8. When at all possible, local subroutines should have local labels. This does not apply to Merlin variables.
Macros
Macros should be named with regard to mnemonic 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.
Commenting Conventions
Inline Comments
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. Note that the audience for these comments are readers who may not have a good grasp of 6502 Assembly, so they should be as descriptive as possible.
File Headers
If the file does not hold a single subroutine, every file should include a header with the following information:
- A brief description of the file
- Any subroutines or macros that are included in the file, along with brief descriptions of each.
- Operating System, Main Author, Contact Information, Date of Last Revision, and intended Assembler.
- If the file contains a collection of macros, the subroutines used by the macros should be listed as well.
Subroutine Headers
All subroutines require headers that document its input, output, register, flag and memory destructions, minimum number of cycles used, and the size of the subroutine in bytes. Headers should all follow the same basic format, and a single space should be used to denote section inclusion.
Macro Headers
Macro headers should include a brief description of the macro, a listing of the parameters with short descriptions thereof, and a sample usage section.
Other Comments
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.
Parameter Passing
Macro Parameters
In general, macro parameters follow a specific hierarchy of order, with the exception of rare cases where another order makes more sense. The hierarchy is as follows:
Source > Destination > Index > Value > Other
Additionally, parameters passed to macros, when addresses are concerned, follow a strict distinction between literal addresses and indirect addresses. If the address passed is a literal value (preceded by # in Merlin Pro 8), then that is the actual address of the data in question. If, however, the address passed is non-literal, then the two-byte value at that address is used as the intended address to be used.
Subroutine Parameters
Subroutines are passed parameters by way of the registers, zero-page location values, or via the stack. Which one of these are used depends on the number of bytes being passed; different methods are used in order to maximize speed based on the needs of a subroutine.
If there are less than four bytes of data being passed, the registers are used; when a 16-bit address is being passed, it is convention to pass the low byte in .A and the high byte in .X.
If there are between four and ten total bytes in need of passing, the zero page is used. The locations used are defined in HEAD.REQUIRED, and specify three areas for 16-bit (two-byte word) values and four areas for 8-bit (single-byte) values. These are labeled as WPAR1, WPAR2, WPAR3, BPAR1, BPAR2, BPAR3, and BPAR4, respectively.
As a last resort, parameters are passed via that stack. This should, however, be a rare occurrence, as it is the slowest method available of passing parameters. Thankfully, since most of the subroutines in the library are meant to provide basic higher-level functionality, there is little need for recourse to this option.
By and large, all parameters should be one or two-byte values; if a string, array or other data type is being passed, its address is passed rather than the data itself.
Since the method of passing parameters can change from subroutine to subroutine, it is highly suggested to use the macros that call the subroutines when possible.
Main Source Sequencing
After necessary assembler directives, files should be loaded in the following order:
- HEAD.REQUIRED is always loaded first (PUT).
- MAC.REQUIRED always follows second (USE).
- Any additional HEAD files should be loaded afterwards (PUT).
- Any MAC files being utilized should be loaded next.
- Now comes the source of the main listing that the programmer will write.
- After the main source, LIB.REQUIRED should be included (PUT).
- Then, any needed subroutine (SUB) files should be included (PUT).
- Any user-created PUT or USE files should be placed at the very end.
Miscellaneous Standards
Subroutine Independence
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
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 BEQW being used to branch beyond the normal byte limit; such macros forego the preceding @-sign.
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.