Expermenting with starting over on the x65 documentation

This commit is contained in:
Carl-Henrik Skårstedt 2020-01-11 12:58:26 -08:00
parent eb3df4de88
commit b469ceef8c
5 changed files with 801 additions and 1 deletions

View File

@ -0,0 +1,116 @@
# Command Line Options for x65
These are the current options for controlling x65 from the command line.
## lst
-lst / -lst=(file.lst)
Generate disassembly text from result(file or stdout)
## tsl
generate listing file in TASS style
## tl
Generate labels in TASS style
## opcodes
-opcodes / -opcodes=(file.s)
Use with -cpu=... to dump all available opcodes for that CPU (file or stdout)
## endm
macros end with endm or endmacro instead of scoped('{' - '}') and rept/repeat emds with endr instead of being scoped.
## cpu
declare CPU type, use with argument
## acc [65816]
set the accumulator mode for 65816 at start, default is 8 bits
## xy [65816]
set the index register mode for 65816 at start, default is 8 bits
## org
-org=$2000 or -org=4096
force assembly for first encountered non-specific address section at given address
## kickasm
use Kick Assembler syntax (in progress)
## merlin
use Merlin syntax
## c64
(default) Include 2 byte load address in binary output
## a2b
Produce an Apple II Dos 3.3 Binary
## bin
Produce raw binary
## a2p
Produce an Apple II ProDos Binary
## a2o
Produce an Apple II GS OS executable (relocatable)
## mrg
Force merge all sections (use with -a2o)
## sect
display sections loaded and built
## sym
-sym (file.sym)
generate symbol file
## obj
-obj (file.x65)
Produce an object file instead of a binary for later linking
## vice
-vice (file.vs)
export a vice monitor command file (including vice symbols)
## xrefimp
import directive means xref, not include/incbin and export directive means xdef, not export section.

docs/directives.md Normal file
View File

@ -0,0 +1,472 @@
# X65 Directives
Directives are commands that control the assembler and include controls for conditional assembly, exporting multible binary files, creating linkable object files etc.
The directives are case insensitive and can be preceeded by a dot
.rept 8 { dc.b 1<<rept }
is the same as
REPT 8 { dc.b 1<<rept }
Some directives change behavior
Assemble for this target, valid options are:
* 6502
* 6502ill (illegal opcodes)
* 65c02
* 6502wdc (adds 18 extra instructions: stp, wai, bbr0-7 & bbs0-7)
* 65816
cpu 6502ill
## PC, ORG
Assemble as if loaded at this address
If applicable, instruct to load at this address
Export this section or disable export Note that with the -xdefimp command line option this means XDEF instead and the EXPORT directive is not available.
Enable code that will be assigned a start address during a link step, or alternatively its own load address. BSS and ZP sections will not be included in the binary output, and sections can be separately exported using the EXPORT directive.
Merge named sections in order listed
Put sections with this name at this address (must be ORG / fixed address section)
Externally declare a symbol. When using the command line option -xdefimp EXPORT means the same thing.
Reference an external symbol. When using the command line option -xdefimp IMPORT means the same thing.
Read in an object file saved from a previous build (that was assembled using the -obj command line option).
Add to address to make it evenly divisible by this. This only works at the start of a SECTION or in the middle of a section that is assembled to a fixed address.
Create a macro. When used with the command line option -endm the macro ends with a ENDMACRO or ENDM directive, and if not using -endm the macro is defined within braces ( { and } ).
; standard macro usage
MACRO ldaneg(x) {
lda #-x
; -endm macro usage
MACRO ldaneg(x)
lda #-x
Print expression to stdout during assemble. The syntax is:
EVAL <message>: <expression>
for example
EVAL Current Address: *
test_stack = 0
eval Checking referenced function, Should be 0: .referenced(test_stack)
eval Checking defined function, Should be 1: .defined(test_stack)
## DC, DV
Declare constant / Declare Value. The directive can be specific by appending .b for byte size, .w for word size, .t for triple size or .l for long size. The default size is 1 byte.
dc.b $20, *-Test
Same as dc.b
Same as dc.w
Same as dc.l
Add text to output, the order of characters can be changed with a string symbol, for instance:
TEXT [FontOrder] "HELLO #1!"
Load and assemble another file at this address.
Load another file and include as binary data at this address.
Load symbols from a .sym file
INCSYM "Main.Sym"
Symbols can also be selected by a list on the same line:
INCSYM InitMain, UpdateMain, ShutdownMain, "Main.Sym"
Add a folder to search for include files.
Generic version of INCLUDE, INCBIN with custom arguments
; include a raw binary file
IMPORT "data.bin"
IMPORT binary "data.bin"
; include a source file
IMPORT source "defines.i"
; include a binary C64 file omitting the load address (first 2 bytes)
IMPORT c64 "main.prg"
; include a text file
IMPORT text "text.txt"
IMPORT text petscii "petscii.txt"
IMPORT text petscii_shifted "petscii.txt"
IMPORT text <string symbol> "custom.txt" ; see TEXT directive
Note that if the command line argument -xdefimp is used then IMPORT is equivalent to XREF instead.
Declare a symbol as const, assgning it again will cause an error.
CONST VICBank = $4000
The constness of a symbol can be tested with the IFCONST directive or the CONST() eval function.
Optional directive create a mutable label, a way to specify non-CONST. It has no actual function.
Declare a string symbol. Strings are a little bit limited but can be used for ordering characters in a TEXT declaration, or it can be used as assembler source.
; Some custom ordered text
TEXT [FontOrder] "MAKE IT SO!"
; Macro for (x=start; x<end; x++)
macro for.x Start, End {
ldx #Start
if Start < End
string _ForEnd = "inx\ncpx #End\nbne _ForLoop"
elif Start > End
if (-1 == End) & (Start<129)
string _ForEnd = "dex\nbpl _ForLoop"
string _ForEnd = "dex\ncpx #End\nbne _ForLoop"
string _ForEnd = ""
macro forend {
_ForEnd ; _ForEnd defined by a variation of the for macro
undef _ForEnd
undef _ForLoop
for.x(5, 1)
lda buf1,x
sta buf2,x
Remove a symbol
like_bananas = 1
UNDEF like_bananas
Create a pool of addresses to assign as labels dynamically. This acts as a linear stack allocator for temporary storage and is deallocated when the scope ends if declared as a local symbol.
Pools can be defined as part of a larger pool.
pool zpGlobal $40-$f8 ; all zero page usage
zpGlobal pool zpLocal 16 ; temporary storage for regular functions
zpGlobal pool zpUtility 16 ; temporary storage for utility functions
zpGlobal pool zpInterrupt 8 ; temporary storage for interrupts
zpGlobal pool zpBuffer 64 ; per module storage
Allocate from a pool by using the pool name
zpBuffer zpIntroTimer.w ; frame counter, 2 bytes
zpBuffer zpScrollChar.8 ; 8 bytes of rol char for scroll
zpLocal .zpSrc.w ; 2 bytes source address
zpLocal .zpDst.w ; 2 bytes dest address
} ; at this point .zpSrc and .zpDst are deallocated and can be reused by other code.
zpLocal .zpCount ; 1 byte, same address as .zpSrc used above
## IF
Begin conditional code. Whatever lines follow will be assembled only if the expression following the IF evaluates to a non-zero value, the conditional block ends with ELSE, ELSEIF or ENDIF.
conditional_code = 1
IF conditional_code
... ; this will be assembled because conditional_code is not zero
Similar to IF but only takes one symbol and the following lines will be assembled only if the symbol was defined previously (IFDEF) or not defined previously (IFNDEF)
defined_symbol = 0
IFDEF defined_symbol
... ; this will be assembled because defined_symbol exists
Similar to IF but like IFDEF only takes one symbol and the following lines will be assembled if the symbol is CONST. The symbol should be defined prior to testing it.
CONST() is also an Eval Function that can be used to form more complex expressions using IF. IFCONST is equivalent to IF CONST(<symbol>)
Checks if the argument exists, mostly for use in macros to test if an argument exists.
BLANK() is also an Eval Function, IFBLANK is equivalent to IF BLANK(...)
Requires a prior IF, the following line will be assembled only if the prior conditional block was not assembled. ELSE must be terminated by an ENDIF
IF 1
lda #0
lda #2
Requires a prior IF and allows another expression check before ending the conditional blocks
IFDEF monkey
lda #monkey_value
lda #zebra_value
lda #human_value
Terminated a conditional segment of blocks.
Declare a set of labels offset from a base address.
word ArtTiles
word ArtColors
word ArtMasks
byte bgColor
Members of the structure can be referenced by the struct name dot member name:
lda ArtSetData + ArtSet.bgColor
ds SIZEOF(ArtSet)
Declare a set of incremental labels. Values can either be assigned or one more than the previous. The default first value is 0.
enum PlayerIndex {
None = -1,
Count ; there are this many players
Enum values can be referenced by enum name dot value name:
ldx #PlayerIndex.One
cpx #PlayerIndex.Count
bcc !
lda #PlayerIndex.Four
Repeats the code within { and } following the REPT directive and counter. Within the REPT code the symbol REPT has the current iteration count, starting at 0.
const words = 10
.rept words * 2 { dc.b rept / 2 }
If the command line option -endm is used then REPT uses ENDR instead of the braced scope so the equivalent to the above would be
.rept words * 2
dc.b rept / 2
## A16, A8, XY16, XY8, I16, I8
Specific to 65816 assembly, controls the current accumulator and index register width (8 or 16 bits). Different assemblers use different names so various alternatives are allowed.
Creates a dummy section between DUMMY and DUMMY_END directives.
## DS, RES
Define "section", Reserve. Reserves a number of bytes at the current address. The first argument is the number of bytes and the second argument is optional and is the byte to fill with. The main purpose is to reserve space in a BSS or ZP section.
A specialized version of a scope, does the same this as a brace scope (code between { and }) but additionally marks all labels defined within as local. An unimplemented feature is that the scope can be named and then labels defined can be accessed outside the scope as
<scope name>::<label> or <scope name>.label (TODO!)
Creates a stack for a mutable symbol so that it can temporarily be redefined and then restored.
do_thing = 1
IF do_thing
.. ; do thing
PUSH do_thing
do_thing = 0
IF do_thing
.. ; do not do thing
PULL do_thing
IF do_thing
.. ; restored symbol, let's do thing again!
Stops assembly with an error if encountered and prints the rest of the line to the output.
# Merlin Specific Directives
## MX
## STR
## DA
## DN
## ASC
## PUT
## DDB
## DB
## DFB
## HEX
## DO
## FIN
## OBJ
## TR
## END
## REL
## USR
## DUM
## LUP
## LNK
## XC
## ENT
## EXT
## ADR
## CYC

docs/macro_samples.md Normal file
View File

@ -0,0 +1,164 @@
# x65macro.i
This is a file under macros and is intended as an example to look at for understanding macro features, it is not super tested for correctness. This information is included in the header file itself but to ease reading copied here. The macros folder also has more detailed documentation.
## Suffix definition
The letters after the period has the following meanings:
- b: byte
- w: word (2 bytes)
- t: triple (3 bytes)
- l: long (4 bytes)
- n: number of bytes in value
- c: copy result to target
- i: immediate, for example add a value to the contents of an address
- x: use the x register for operation as a counter or an offset
- y: use the y register for operation
- r: relative; ry=(zp),y
- a: use the contents of an address for operation (16 bits)
- s: custom step size (instead of +1 or -1) for loops
- p: positive
- m: negative
- o: use label pool for counter
## operations
The base operations provided by these macros are:
- set: Assign a value to the contents of an address
- move: Move the contents of an address to another address
- add: addition
- sub: subtraction
- asrm: arithmetic shift right
- aslm: arithmetic shift left
- neg: negate a number
- abs: make a number positive
- copy: copy memory from one location to another
- for: iterate between two numbers with optional step size
- mnop: insert multiple nop at this point
set.b / .w / .t / .l Value, Target
- set the contents of an 1-4 byte location to a value
- uses accumulator
move.b / .w / .t / .l / .n Src,Trg
- copy 1-4 (or n) bytes from Src location to Trg location
- uses accumulator
asrm.n Target, Size
- shift a signed multi byte number right
- uses accumulator
asrm.nx Target, Size
- shift a signed multi byte number right offset by the x register
- no registers touched
aslm.n Target, Size
- shift a multi byte number left
- no registers touched
aslm.nx Target, Size
- shift a multi byte number left offset by the x register
- no registers changed
neg.cn Source, Target, Size
- negate and copy a multi byte number
- uses accumulator
neg.n Target, Size
- negate a number in place
- uses accumulator
abs.n Trg, Size
- make a number absolute
- uses accumulator
neg.nx Trg, Size
- negate a number in place offset by the x register
- uses accumulator
add.n Address1, Address2, Target, Bytes
- add contents of two memory locations into a target lcoation
- uses accumulator
sub.n Address1, Address2, Target, Bytes
- Target = Address1 - Address2
- uses accumulator
add.ni Address, Value, Target, Bytes
- add a fixed value to a memory location into a target
- uses accumulator
sub.ni Address, Value, Target, Bytes
- Target = Address - Value
- uses accumulator
add.wi Address, Value, Target
- Subtract 16 bit Value from contents of Address and store at Target
- uses accumulator
sub.wi Address1, Address2, Target
- add contents of two 16 bit addresses into a target 16 bit location
- uses accumulator
mnop Count
- add Count nops
copy.x Source, Target, Size
- copy up to 256 bytes using the x register as a counter
- uses accumulator and x register
copy.y Source, Target, Size
- copy up to 256 bytes using the y register as a counter
- uses accumulator and y register
copy.ry zpSrcPtr,zpTrgPtr,Size
- copy a fixed length buffer using relative zp y indexing
- size is up to a page, changing Y and A
copy.ry128 zpSrcPtr,zpTrgPtr,Size
- copy up to 128 bytes using the y register
copy.o Src,Trg,Size,PoolZP
- copy more than 256 bytes using zero page label pool addresses
- uses accumulator, x and y register
copy.a Src,Trg,Size
- copy more than 256 bytes using absolute indexed in a loop
- uses accumulator, x and y register
copy.zp Src,Trg,Size,zpTmp1,zpTmp2
- copy more than 256 bytes using two pairs of zero page values
- uses accumulator, x and y register
for.x Start, End
- iterate using the x register from Start to End, End is not inclusive
so to iterate from 31 to 0 use for.x 31, -1
- uses x register
- end for loop with forend macro
for.y Start, End
- same as for.x but with the y register
- uses y register
- end for loop with forend macro
for.w Start, End, Counter
- for loop for 16 bit counter
- uses accumulator
- end for loop with forend macro
for.ws Start, End, Counter, Step
- for loop for 16 bit counter with a step value
- uses accumulator
- end for loop with forend macro
for.wsp Start, End, Counter, Step {
- for (word Counter=start; Counter<end; Counter += Step), Step>0
- uses accumulator
for.wsm Start, End, Counter, Step {
- for (word Counter=start; Counter<end; Counter += Step), Step<0
- uses accumulator
- terminates for loops

docs/readme.md Normal file
View File

@ -0,0 +1,48 @@
# x65 Assembler
x65 is an open source 6502 series assembler that supports object files,
linking, fixed address assembling and a relocatable executable.
Assemblers have existed for a long time and what they do is well documented,
x65 tries to accomodate most expectations of syntax from Kick Assembler (a
Java 6502 assembler) to Merlin (an Apple II assembler).
For debugging, dump_x65 is a tool that will show all content of x65 object
files, and x65dsasm is a disassembler intended to review the assembled
## Noteworthy features:
* Code with sections, object files and linking or single file fixed
address, or mix it up with fixed address sections in object files.
* Assembler listing with cycle counting for code review.
* Export multiple binaries with a single link operation.
* C style scoping within '{' and '}' with local and pool labels
respecting scopes.
* Conditional assembly with if/ifdef/else etc.
* Assembler directives representing a variety of features.
* Local labels can be defined in a number of ways, such as leading
period (.label) or leading at-sign (@label) or terminating
dollar sign (label$).
* String Symbols system allows building user expressions and macros
during assembly.
* Reassignment of symbols and labels by default.
* No indentation required for instructions, meaning that labels can't
be mnemonics, macros or directives.
* Supporting the syntax of other 6502 assemblers (Merlin syntax
requires command line argument, -endm adds support for sources
using macro/endmacro and repeat/endrepeat combos rather
than scoeps).
* Apple II GS executable output.
## Command Line Options
See [command_line_options.md]
## Directives
See [directives.md]
## Macro examples
See [macro_samples.md]

View File

@ -635,7 +635,7 @@ _ForLoop
macro for.y Start, End {
ldx #Start
if Start < End
string _ForEnd = "iny\ncpx #End\nbne _ForLoop"
string _ForEnd = "iny\ncpy #End\nbne _ForLoop"
elif Start > End
if (-1 == End) & (Start<129)