2018-01-04 00:15:04 +00:00
# Using assembly within Millfork programs
There are two ways to include raw assembly code in your Millfork programs:
* inline assembly code blocks
* whole assembly functions
## Assembly syntax
Millfork inline assembly uses the same three-letter opcodes as most other 6502 assemblers.
Indexing syntax is also the same. Only instructions available on the current CPU architecture are available.
2018-03-03 00:21:57 +00:00
**Work in progress**:
Currently, `RMBx` /`SMBx`/`BBRx`/`BBSx` and some extra 65CE02/HuC6280/65816 instructions are not supported yet.
2018-01-04 00:15:04 +00:00
Undocumented instructions are supported using various opcodes
2018-02-27 12:26:56 +00:00
Labels have to be followed by a colon and they can optionally be on a separate line.
Indentation is not important:
2018-01-04 00:15:04 +00:00
first: INC x
second:
INC y
2018-02-27 12:26:56 +00:00
INC z
2018-01-04 00:15:04 +00:00
Label names have to start with a letter and can contain digits, underscores and letters.
This means than they cannot start with a period like in many other assemblers.
Similarly, anonymous labels designated with `+` or `-` are also not supported
Labels are global,
which means that they live in the same namespace as functions, types and global variables.
Assembly can refer to variables and constants defined in Millfork,
but you need to be careful with using absolute vs immediate addressing:
const byte fiveConstant = 5
byte fiveVariable = 5
byte ten() {
byte result
asm {
LDA #fiveConstant
CLC
ADC fiveVariable
STA result
}
return result
}
Any assembly opcode can be prefixed with `?` , which allows the optimizer change it or elide it if needed.
Opcodes without that prefix will be always compiled as written.
2018-03-10 20:52:28 +00:00
You can insert macros into assembly, by prefixing them with `+` and using the same syntax as in Millfork:
macro void run(byte x) {
output = x
}
byte output @$c000
void main () {
byte a
a = 7
asm {
+ run(a)
}
}
2018-04-02 19:40:54 +00:00
You can insert raw bytes into your assembly using the array syntax:
[ $EA, $EA ]
"this is a string to print" apple2
["this is a string to print but this time it's zero-terminated so it will actually work" apple2, 0]
[for x,0,until,8 [x]]
2018-01-04 00:15:04 +00:00
## Assembly functions
2018-02-01 21:39:38 +00:00
Assembly functions can be declared as `macro` or not.
2018-01-04 00:15:04 +00:00
2018-02-01 21:39:38 +00:00
A macro assembly function is inserted into the calling function like an inline assembly block,
2018-01-04 00:15:04 +00:00
and therefore usually it shouldn't end with `RTS` or `RTI` .
2018-02-01 21:39:38 +00:00
A non-macro assembly function should end with `RTS` , `JMP` or `RTI` as appropriate,
2018-01-04 00:15:04 +00:00
or it should be an external function.
2018-01-31 23:22:53 +00:00
2018-02-01 21:39:38 +00:00
For both macro and non-macro assembly functions,
2018-01-31 23:22:53 +00:00
the return type can be any valid return type, like for Millfork functions.
2018-01-04 00:15:04 +00:00
If the size of the return type is one byte,
then the result is passed via the accumulator.
If the size of the return type is two bytes,
then the low byte of the result is passed via the accumulator
and the high byte of the result is passed via the X register.
### Assembly function parameters
An assembly function can have parameters.
They differ from what is used by Millfork functions.
2018-02-01 21:39:38 +00:00
Macro assembly functions can have the following parameter types:
2018-01-04 00:15:04 +00:00
* reference parameters: `byte ref paramname` : every occurrence of the parameter will be replaced with the variable given as an argument
* constant parameters: `byte const paramname` : every occurrence of the parameter will be replaced with the constant value given as an argument
For example, if you have:
inline asm void increase(byte ref v, byte const inc) {
LDA v
CLC
ADC #inc
STA v
}
and call `increase(score, 10)` , the entire call will compile into:
LDA score
CLC
ADC #10
STA score
2018-02-01 21:39:38 +00:00
Non-macro functions can only have their parameters passed via registers:
2018-01-04 00:15:04 +00:00
* `byte a` , `byte x` , `byte y` : a single byte passed via the given CPU register
* `word xa` , `word ax` , `word ay` , `word ya` , `word xy` , `word yx` : a 2-byte word byte passed via given two CPU registers, with the high byte passed through the first register and the low byte passed through the second register
2018-02-01 21:39:38 +00:00
Macro assembly functions can have maximum one parameter passed via a register.
2018-01-31 23:22:53 +00:00
2018-01-04 00:15:04 +00:00
### External functions
An external function should be declared with a defined memory address
and the `extern` keyword instead of the body:
asm void putchar(byte a) @$FFD2 extern
## Safe assembly
Since assembly gives the programmer unlimited access to all machine features,
certain assumptions about the code may be broken.
In order to make assembly cooperate with the rest of the Millfork code,
it should abide to the following rules:
* don't leave the D flag set
* don't jump between functions if either of functions has stack variables
* don't do `RTS` or `RTI` if the function has stack variables
* don't jump or call things that are not functions or labels
* don't store data in locations other than variables or arrays
* don't change the stack pointer
* end non-inline assembly functions with `RTS` , `JMP` or `RTI` as appropriate
2018-03-03 00:21:57 +00:00
* on NMOS 6502:
* don't use `XAA` , `LXA` , `AHX` , `SHX` , `SHY` , `LAS` and `TAS` instructions
* on 65816:
* keep the direct page register set to $0000
* keep the M and X flags set to 1 (8-bit registers by default, native mode)
* if running in the native mode, be careful with the stack pointer (you should keep it between $000100 and $0001FF)
* do not change the data page register (keep an eye at the `PLD` , `MVN` , `MVP` instructions)
* explicitly use 16-bit immediate operands when appropriate; the assembler doesn't track flags and assumes 8-bit immediates by default
* use far jumps unless you're sure that the called function returns with an `RTS`
* on 65CE02:
* keep the `B` register set to $00
* don't change the `E` flag
* on HuC6280
* don't use the `SET` instruction
2018-01-04 00:15:04 +00:00
The above list is not exhaustive.