fasm68k - Motorola 68000 instruction set for fasmg (flat assembler g)

Note

Version 1.0.0. All 68k instructions are validated with about 22,000 tests, and Sonic 1 and Retail Clerk '89 are assembled after every push.

What is fasm68k?

fasm68k is a set of fasmg macros that adds the Motorola 68000 instruction set to fasmg to allow it to assemble 68k assembly code. fasm68k also has its own set of directives and adds settings to allow for some compatibility (such as aliases or support for colonless labels), with other m68k assemblers in order to make it easier to convert codebases to fasm68k.

Why?

Well, fasmg's macro language is cool, other macro languages feel a bit pale in comparison, but there was no one who had made a 68000 instruction set for it yet so here it is.

If you have no idea what fasmg is then I'll quote from it's Introduction and Overview:

This [fasmg] is a bare engine that by itself has no ability to recognize and encode instructions of any processor, however it has the ability to become an assembler for any CPU architecture. It has a macroinstruction language that is substantially improved compared to the one provided by flat assembler 1 and it allows to easily implement instruction encoders in form of customizable macroinstructions.

And that's what fasm68k is, it's a set of fasmg macros to allow fasmg to assemble 68k assembly code.

Scope

• The instruction set for the original 68000 not including any later models such as the 68020 etc. though if demand exists I might consider adding such instructions.
• Compatibility with other assemblers to aid in reproducing exactly the same binaries as other assemblers.

Performance and optimization of the produced binary is not prioritized at this point.

Example

fasm68k aims to have some compatibility with other 68k assemblers, but will probably never become 100% compatible. Here is one example of what was needed to adapt code originally for the asm68k assembler to fasm68k.

The compatibility aspect of fasm68k is still under development. I hope that it will be even easier to adapt projects to fasm68k in the future.

Installation

Linux

Get fasm68k and its dependencies (i.e. fasmg and examples) by running:

git clone --recurse-submodules git@github.com:fredrik-hjarner/fasm68k.git

Step into the repository directory:

cd fasm68k

To assemble the examples run these commands and binary files should be created which you can run in a Mega Drive/Genesis emulator:

./fasm68k examples/megadrive_simple_demo/main.asm
./fasm68k examples/megadrive_samples_fasm68k/1_hello_world/hello.asm
./fasm68k examples/megadrive_samples_fasm68k/2_scroll_planes/scroll.asm
./fasm68k examples/megadrive_samples_fasm68k/3_sprites/sprites.asm
./fasm68k examples/megadrive_samples_fasm68k/4_gamepad/gamepad.asm
./fasm68k examples/megadrive_samples_fasm68k/6_psg_tone/psg_tone.asm
./fasm68k examples/RetailClerk89_fasm68k/src/RetailClerk89.X68
./fasm68k examples/speedrun-tower_fasm68k/src/SpeedrunTower.X68

Add a new line at the bottom of your .bashrc file adding the fasm68k directory to the PATH so you can run fasm68k from anywhere and not only from the specific folder you cloned it into:

export PATH=$HOME/code/fasm68k:$PATH

Windows

Get fasm68k and it's dependencies (i.e. fasmg and examples) by running:

git clone --recurse-submodules git@github.com:fredrik-hjarner/fasm68k.git

Step into the repository directory:

cd fasm68k

To assemble the examples, run these commands using fasm68k.bat and binary files should be created which you can run in a Mega Drive/Genesis emulator:

fasm68k.bat examples/megadrive_simple_demo/main.asm
fasm68k.bat examples/megadrive_samples_fasm68k/1_hello_world/hello.asm
fasm68k.bat examples/megadrive_samples_fasm68k/2_scroll_planes/scroll.asm
fasm68k.bat examples/megadrive_samples_fasm68k/3_sprites/sprites.asm
fasm68k.bat examples/megadrive_samples_fasm68k/4_gamepad/gamepad.asm
fasm68k.bat examples/megadrive_samples_fasm68k/6_psg_tone/psg_tone.asm
fasm68k.bat examples/RetailClerk89_fasm68k/src/RetailClerk89.X68
fasm68k.bat examples/speedrun-tower_fasm68k/src/SpeedrunTower.X68

Optional: Add the fasm68k directory to your PATH so you can run fasm68k.bat from anywhere:

1. Search for "Environment Variables" in Windows Start menu
2. Click "Edit the system environment variables"
3. Click "Environment Variables..." button
4. Under "User variables", find and select "Path", then click "Edit..."
5. Click "New" and add the full path to your fasm68k directory (e.g., C:\Users\YourName\code\fasm68k)
6. Click "OK" on all dialogs

After adding to PATH, open a new command prompt and you can run:

fasm68k.bat your_file.asm

Mac

TODO

Directives and keywords

Beyond the standard fasmg directives and keywords, fasm68k adds the following ones:

Directive/ keyword	Description	Also present in these assemblers
__rs	Current value of RS counter	asm68k
rsset	Set __rs address.	asm68k
even	Word-align the current address.	asm68k, vasm
rseven	Word-align the __rs address.
rs.b	Reserve a byte of space.	asm68k
rs.w	Reserve a word of space.	asm68k
rs.l	Reserve a longword of space.	asm68k
dc.b	Define a byte.	asm68k, vasm
dc.w	Define a word.	asm68k, vasm
dc.l	Define a longword.	asm68k, vasm
incbin	Include a binary file.	asm68k, vasm

Settings Reference

This document lists the user-facing settings under m68k.settings.*, what they do, and which values are valid.

How to set a setting

Use the helper macro:

m68k.set diag_absolute_too_big, 2     ; sets to the given value

Diagnostics (severity settings)

Defined in src/settings/diagnostics.inc.

Setting	Default	Values	Meaning
diag_absolute_too_big	0	0/1/2	0=off, 1=warn, 2=error when an absolute address literal is too large for the selected addressing mode and must be truncated.
diag_instruction_word_alignment	1	0/1/2	0=off, 1=warn, 2=error when an instruction is placed on an odd address (68000 requires instruction fetches to be word-aligned).
diag_data_word_alignment	1	0/1/2	0=off, 1=warn, 2=error when non-byte data is placed on an odd address (e.g. dc.w/dc.l/dc.q, rs.w/rs.l/rs.q).

Autofixes (illegal → legal rewrites)

Defined in src/settings/autofixes.inc.

Setting	Default	Values	Meaning
autofix_eor_to_eori	2	0/1/2	When writing eor #imm,<ea> (illegal for eor): 0=error (don’t fix), 1=autofix + warn, 2=autofix silently.
autofix_cmp_to_cmpa	2	0/1/2	When writing cmp <ea>,an (illegal for cmp): 0=error (don’t fix), 1=autofix + warn, 2=autofix silently.

Optimizations (legal → “more optimal” rewrites)

Defined in src/settings/optimization.inc.

Setting	Default	Values	Meaning
optimize_cmp_to_cmpi	0	0/1/2	When first operand is immediate in a cmp-family context: 0=no optimize, 1=optimize + warn, 2=optimize silently.
optimize_add_to_addi	0	0/1/2	When first operand is immediate: 0=no optimize, 1=optimize + warn, 2=optimize silently.
optimize_sub_to_subi	0	0/1/2	When first operand is immediate: 0=no optimize, 1=optimize + warn, 2=optimize silently.
optimize_or_to_ori	0	0/1/2	When first operand is immediate: 0=no optimize, 1=optimize + warn, 2=optimize silently.
optimize_and_to_andi	0	0/1/2	When first operand is immediate: 0=no optimize, 1=optimize + warn, 2=optimize silently.

General / compatibility settings

Defined in src/settings/settings.inc (plus some behavior implemented in src/compat/*.inc).

Setting	Default	Values	Meaning / Notes
compat_operators	0	0/1	Enables common operator syntax from other assemblers (e.g. << → shl, >> → shr, & → and, `
compat_binary_percent_prefix	0	0/1	Enables %0101 style binary literals in some contexts (translated to fasmg’s 0101b).
compat_colon_equs	0	0/1	Compatibility for label: equ value syntax.
compat_colonless_labels	0	0/1	Compatibility for labels without a trailing colon (implementation-dependent).
compat_vasm_org	0	0/1	Changes ORG behavior to match vasm (see src/compat/compat_vasm.inc).
compat_vasm_align	0	0/1	Changes ALIGN behavior to match vasm (see src/compat/compat_vasm.inc).

Differences from other m68k assemblers

• Macros are completely different and it's the main reason for this project to exist. fasmg's macro langauge is more powerful than the macro languages of other assemblers. Check out fasmg's manual for more information.
• fasm68k is less pedantic when it comes to the use of whitespace. You may place an instruction in the "first column" (without any leading whitespace) for example.
• fasm68k does not support * to get the current address. Either use @ or $ instead.
• Some operators are different. While I have added support for << and >> for bit shifting, the preferred way is to use shl and shr. Likewise try to use or instead of | and and instead of &.
• Binary numbers are written as 01010101b (instead of %01010101).
• You prefix labels with dot .label1 to make them local (instead of prefixing with @ @label1).
• Currently no optimizations.

In comparison to vasm (vasmm68k_mot)

### ORG

ORG works very differently in vasm and fasmg. In fasmg the addresses in after ORG are based on the value specified in the argument. In vasm the ORG command actually adds empty bytes up to the specified address.

• I will add a compatibility setting to support the vasm behaviour. It is recommended to have that setting disabled unless you need it.

Acknowledgments and attributions

• Tomasz Grysztar for fasmg.
• BigEvilCorporation for the megadrive_samples which I simply adapted for fasm68k.
• The vasm and clownassembler assemblers were very helpful for determining correct behaviour of the encoding of the instructions.
• Hugues Johnson's RetailClerk89 and Speedrun Tower were great games to test fasm68k with.
• Exodus and Kega Fusion emulators were used to test the output of fasm68k.
• This m68k encoding pdf by GoldenCrystal was extremely helpful.