M68K Mode for Emacs

Motorola 68k Assembly environment for Emacs. Focusing on Amiga in the beginning with lsp-server and debugger. Might extend to support other platforms based upon interest Includes setup for lsp-mode, and experimental dap-mode.

Example screenshot using my pink-bliss-uwu theme and company-box to get documentation during completion:

(will probably look slightly different, and maybe more pleasant to you with another theme. If we wanted something standard, we would NOT be using Emacs but some cookie cutter IDE nonsense)

Installation

Only manual is supported at the moment. You can help get this ready for something like MELPA by contributing 🙂

Manual

Clone this repo and add it to your load-path, like so:

(add-to-list 'load-path "/path/to/repo")
(require 'm68k-mode)

Note that m68k-mode depends on lsp-mode!

Usage

You can simply activate m68k-mode for any buffers where you have a M68K assembly code. Language server will be started automatically, and you will be prompted for installation if you have not installed it manually already.

Tip

You can update your language server with M-x lsp-update-server

You can now use all supported LSP functionality for the server. Check the server repo for more information on supported features. Most language server features should work right out of the box. Some examples:

• lsp-format-buffer for formatting
• lsp ui documentation popups on mouse hover and lsp-ui-doc-show / lsp-ui-doc-hide
• eldoc (i.e, minibuffer area) signature documentation for instructions/mnemonics.

Cycle Counter

There is an additional cycle counter you can opt in to using. Make sure you have NPM, and more specifically the NPX tool available (should be in all newer versions of NPM). Then in your config:

(require 'm68k-cycle-counter)

To get cycle counts as an overlay in your buffer, run M-x m68k-cycle-counter-mode. At the moment, the cycle counter does not run periodically, but this is planned. Just deactivate it, and activate it again to get new counts. (activation and deactivations are both the same command). Your buffer will then look similar to the following (or the theme might be different):

(I have disable truncation of lines to make it look prettier in this example. This is the same example code as above, and is taken from grahambates/vscode-amiga-wks-example

Experimental debugger

The debugger is not enabled by default. To enable it, follow the installation instructions above, and add:

(require 'm68k-dap)

When it has been tested a bit more, it might be enabled by default as well. To debug, you will need to install the debug adapter and tooling. Make sure you have NPM installed, and run M-x m68k-dap-uae-setup. Emulators, like FS-UAE v4, is included in the tooling install. There might be some minor setup like putting Kickstart files in the correct directories if you have never used it before.

Usage is like normal for dap-mode in Emacs: Simply run dap-debug and you are debugging! There is an included debug template where you are queried for the program to debug. This one is called Amiga ASM debug. Looking at it can provide some inspiration for your own config:

(dap-register-debug-template
 "Amiga ASM debug"
 (list :type "asm68k"
       :request "launch"))

If you want the program to be debugged to be coded in, just add :program /path/to/compiled/exe to a debug template. You can also use .vscode/launch.json configuration for the debugging, but not for a compilation task list. Make sure the debug configuration has the type asm68k for dap-mode to recognize it.

If you want to compile before debugging, check the configuration section below.

Configuration

• m68k-format-case: The case the formatter will format instructions and registers to. “lower”, “upper” or “any”.
• m68k-processor-types: A vector of processing types that should be used. Used to give correct completion and documentation based upon which processor. Example values: ["mc68000"] (default) for plain 68k processor, ["mc68020", "mc68881"] for a 68020 with a floating point processor etc.
• m68k-include-paths: Vector of include paths. Has the same effect as INCDIR in code. Example: ["/path/to/my/awesome/includes.i"].

The debugger has the option to run compilation before debugging. To do so, set:

• m68k-compile-command to the command used to compile. Examples: make build, ./compile.sh or similar. If the build fails, meaning the exit code is not 0, then the debugging will not start. If set to nil, no compilation will happen, and it will be your responsibility to do it manually before debugging.

Contributing

All contributions welcome! Be kind, respectful, and constructive, and we will probably work good together :)

Feel free to report any issues you might have, and also feature requests. If we can make this a good package that create awesome M68K tooling for Emacs, then that would be awesome 🙂

Steps for contributing code:

1. Fork this repo
2. Create branch with a fitting name for what you want to work with. example: feature/tree-sitter-support, bugfix/
3. PR it with a descriptive title. Something like “Implemented tree-sitter syntax highlighting”
4. Discussion in comment, possible suggestions, and eventual merging if everything look good :)