LAMAlib - Lightweight Assembler MAcro library for cc65
Version: 0.12
Date: 2019-10-26
Author: Wil Elmenreich (wilfried at gmx dot at)
License: The Unlicense (public domain)
Installation and Usage
To use LAMAlib you need to have cc65 installed. Get it at https://cc65.github.io
Possibility 1: Install in cc65
Copy all LAMAlib*.inc files into directory asminc of your cc65 installation.
Copy the file LAMAlib.lib into directory lib of your cc65 installation.
Move LAMAlibdoc.html (the file you are currently viewing) either to the html directory of cc65 or to some other place where you want to conveniently keep the documentation.
You don't need to keep the original folder of LAMAlib
In your programs,
add a line .include "LAMAlib.inc" at the top of your assembler file
assemble with command cl65 yourprog.s -lib LAMAlib.lib -C c64-asm.cfg -u __EXEHDR__ -o yourprog.prg
Possibility 2: Keep LAMAlib separately
Keep a copy of the LAMAlib folder in a sister directory of your project.
In your programs,
add a line .include "../LAMAlib/LAMAlib.inc" at the top of your assembler file (the forward slash works on Linux as well as on Linux systems)
assemble with command cl65 yourprog.s -lib ../LAMAlib/LAMAlib.lib -C c64-asm.cfg -u __EXEHDR__ -o yourprog.prg
When you publish code of your project you may add LAMAlib to the package. The License has been chosen to be maximum permissive, so whatever project you have, there should be not problems adding the code.
Points to remember
Please note that the zero flag for 16/24/32 bit operations is not properly set for most macros except CMPxx, therefore a CMPxx #00 might be necessary to test for zero.
Some of the more complex functions like division and multiplication use zero page addresses $22-$2a as temporary memory. This area is also by BASIC for temporary ptrs and results, but borrowing these addresses seem not to interfere severely with the system. Using $22-2A further plays well with cc65 parts written in C and leaves the well-known free ZP addresses at $FB to $FE to the user.
Command documentation
16-bit Emulation Macros
ldax addr, ldax #arg
Loads a 16-bit value into A/X, either from an address or as immediate value
Note that the zero flag is not indicating 0 but indicating a value <256
Supports zero page addressing mode
Registers modified: A,X
stax addr
Stores the value in registers A and X to addr and addr+1
Supports zero page addressing mode
Registers modified: none
adcax addr, adcax #arg
Adds a 16 bit value at an addr or as immediate value to 16 bit value in registers A/X
Supports zero page addressing mode
Result is returned in A/X
Registers modified: A,X
sbcax addr, sbcax #addr
Subtracts the 16 bit value at an addr or as immediate value from 16 bit value in registers A/X
Supports zero page addressing mode
Result is returned in A/X
Registers modified: A,X
cmpax addr, cmpax #arg
Compares the value in A/X with the 16 bit value in addr or the immediate value
Supports zero page addressing mode
Result is returned in A/X
Registers modified: A,X
orax addr, orax #arg
Calculates the bitwise OR operation between A/X and a 16 bit value at an addr or as immediate value
Supports zero page addressing mode
Result is returned in A/X
Registers modified: A,X
andax addr, andax #arg
Calculates the bitwise AND operation between A/X and a 16 bit value at an addr or as immediate value
Supports zero page addressing mode
Result is returned in A/X
Registers modified: A,X
eorax addr, eorax #arg
Calculates the bitwise exclusive-or operation between A/X and a 16 bit value at addr or as immediate value
Supports zero page addressing mode
Result is returned in A/X
Registers modified: A,X
aslax
Performs an arithmetic shift left of A/X (essentially a multiplication with 2, MSB goes into carry)
Result is returned in A/X
Registers modified: A,X
asl16 addr
Performs an arithmetic shift left of a 16 bit number at addr
Result at addr, addr+1
Registers modified: none
lsrax
Performs a logic shift right of A/X (essentially a division by 2, LSB goes into carry)
Result is returned in A/X
Registers modified: A,X
lsr16 addr
Performs a logic shift right of a 16 bit number at addr
Result at addr, addr+1
Registers modified: none
rolax
Performs a rotate left of A/X (essentially a multiplication with 2, carry goes into LSB, MSB goes into carry)
Result is returned in A/X
Registers modified: A,X
rol16 addr
Performs a rotate left of a 16 bit number at addr
Result at addr, addr+1
Registers modified: none
rorax
Performs a rotate right of A/X (essentially a division by 2, carry goes into MSB, LSB goes into carry)
Result is returned in A/X
Registers modified: A,X
ror16 addr
Performs a rotate right of a 16 bit number at addr
Result at addr, addr+1
Registers modified: none
negax
Negates the value in A/X
Result is returned in A/X
Registers modified: A,X
absax
Makes the signed 16 bit value in A/X an absolute value
Result is returned in A/X
Registers modified: A,X
incax
Increments 16 bit value in registers A/X
Registers modified: A,X
inc16 addr
Increments the value stored at addr (lo-byte) and addr+1 (hi-byte) as a 16 bit value
Registers modified: none
decax
Decrements 16 bit value in registers A/X
Registers modified: A,X
dec16 addr
Decrements the value stored at addr (lo-byte) and addr+1 (hi-byte) as a 16 bit value
Registers modified: A
pushax
Pushes AX to the stack and preserves AX
pullax
Pulls AX from the stack
mul16 addr
Multiplies the unsigned 16 bit value in A/X with the 16 bit value stored at addr (lo-byte) and addr+1 (hi-byte)
Implemented as a subroutinge, link with -lib lamalib.lib
This function is not reentrant, don't use in interrupt and main program simultaneously
Result is returned in A/X
Registers modified: all
div16 arg
Multiplies the unsigned 16 bit value in A/X with an imediate value or the 16 bit value stored at addr (lo-byte) and addr+1 (hi-byte)
Implemented as a subroutinge, link with -lib lamalib.lib
This function is not reentrant, don't use in interrupt and main program simultaneously
Result is returned in A/X
Registers modified: all
rand8 arg ; rand8_setseed [arg]
based on the 8-bit pseudo-random number generator from White Flame
https://codebase64.org/doku.php?id=base:small_fast_8-bit_prng
Simple but very fast random generator with a period of 256
Seed is an 8 bit value, setting seed is optional. When no argument is given, the current value in the Accumulator is used as the seed
Result is returned in A
Registers modified: A
rand16 arg ; rand16_setseed arg
fast 16-bit pseudo-random number generator with period of 65535
seed must never be 32755, so setseed modifies this value it this is the case
Seed is a 16 bit value, setting seed is optional. When no argument is given, the current value in A/X is used as the seed
Result is returned in A/X
Registers modified: A,X
print arg1 [arg2 ...]
Prints the arguments as strings or numbers
An argument in parenthesis will print the 16bit value stored at this address
uses ROM functions, BASIC and KERNAL ROM need to be enabled when using this macro
Registers modified: A,Y,X
primm str
Prints the given string, string is inlined in program code
uses ROM functions, BASIC and KERNAL ROM need to be enabled when using this macro
Registers modified: A,Y,X
printax
Prints the number in A/X as a 16 bit unsigned decimal number
BASIC and KERNAL ROM need to be enabled when using this function
Registers modified: A,Y,X
printax_signed
Prints the number in A/X as a 16 bit signed decimal number
BASIC and KERNAL ROM need to be enabled when using this function
Registers modified: A,Y,X
printstr addr
Prints the null-terminated string at addr using the STROUT function
BASIC and KERNAL ROM need to be enabled when using this function
Registers modified: A,Y,X
newline
Prints a newline character
KERNAL ROM needs to be enabled when using this function
Registers modified: A,Y,X
clrscr
Clears the screen
KERNAL ROM needs to be enabled when using this function
Registers modified: A,Y,X