MC68000 Assembly Language Plugin

MC68000 Assembly Language Plugin is plugin for Jetbrains IDEs (CLion, IntelliJ, etc.).

Purpose

This plugin delivers support for MC68000 assembly language files (VAsm / DevPac-Style).

It adds a language parser with syntax highlighting, referencing and refactoring support, and a few more features.

I'm an Amiga retro democoder, and the lack of a plugin for M68k was the motivation to write one. Also, diving deep into custom language plugins has a steep learning curve.

When I started the plugin in July 2021, I was not aware of the M68k plugin efforts by Jetbrains employee Yann Cébron who has been working on the same topic for quite some time. At the time of writing, his plugin however, has not been release yet. Nevertheless, it has a lot of awesome features and is pretty advanced. Check it out. You can install both plugins at the same time and see what suits you more.

Big kudos to Yann -- a few features were inspired by his code.

My plugin, on the other hand, is still pretty basic and is the result of a few weeks of work. I released a really early first version it because I think it's " good enough" to get started, and I can return to demo coding with its current state.

Features

• Parser / Lexer for MC68000 (yes, only 68000 right now!) assembly language files in VAsm / DevPac style
• Inspection for validating the syntax of the 68000 ISA.
• Syntax highlighting and Color Settings Page (you should really modify the color settings to your likings!)
• Mnemonics code completion
• Symbols / Labels / Macros code completion
• References / Refactoring support for local and global labels, symbol assignments, and macros.
• Simple register usage flow (hover over register or press F1 for full flow)
• Brace matching
• Quote handler
• Goto Symbol support
• Structure view
• Documentation provider for symbol definitions and mnemonics (listing available addressing modes etc.).

Inspections

The plugin provides a few inspections for code analysis. An error or warning can be suppressed by placing a ; suppress <InspectionName> comment either on an end of line comment behind the statement or in a full line comment above the statement.

M68kSyntaxInspection - Assembly instruction validity

Checks the validity of the current instruction. If an instruction is not recognized, you may get one of the following errors:

• Instruction mnemonic not supported on selected cpu (you won't get this currently as only MC68000 is supported)
• No operands expected for mnemonic
• Second operand op unexpected for mnemonic
• Unsupported addressing mode for mnemonic
• Unsupported addressing mode op for first operand of mnemonic
• Unsupported addressing mode op for second operand of mnemonic
• Unsupported addressing modes for operands in this order for mnemonic (try swapping)
• Instruction mnemonic is unsized (you tried to specify .b, .w or .l)
• Operation size (.b,.w,.l) unsupported for mnemonic
• Operation size (.b,.w,.l) unsupported (should be (.b,.w,.l))

M68kDeadWriteInspection - Dead writes to registers

This inspection looks at register writes and tries to find instructions that renders a write moot because it was overwritten by another instruction before anything useful was done with it.

Analysis is aborted at global labels, flow control instructions, directives (e.g. conditional assembly) and macros with the register names as parameter.

The inspection tries to take condition code changing into account and puts out a weak warning if the statement merely changes condition codes before the contents of the register are overwritten. In this case, it is sometimes better to replace move by tst.

M68kUnexpectedConditionalInstructionInspection - Unaffected condition codes before conditional instruction

Especially for novice coders, it is not clear that some instructions do not affect the condition codes for a subsequent condition branch or scc instruction. movea, adda and suba come to my mind.

The inspection will report such suspicious instruction sequences.

However, this does not need to be a programming error. Advanced coders sometimes make use of the fact that instructions do not change condition codes and thus optimize the order of execution.

Documentation provider

M68kSymbolDefinitionDocumentationProvider

Provides the assigned value of a =, set or equ symbol definition when hovering over a symbol.

M68kRegisterFlowDocumentationProvider

When hovering over or placing the cursor at a data or address register, the documentation will scan through the instructions backwards and forwards and will show all read, changes of the register contents. It does this until an instruction is found that defines (sets) the contents of the register (according to the size of the instruction where the cursor was placed).

The analysis ignores all code flow instructions and might be inaccurate for branches, macro use, etc. It also stops at global labels.

The documentation will search up to 100 instructions in each direction, but only four when hovering over the register (so if you need the whole analysis, use the documentation window).

M68kInstructionDocumentationProvider

When hovering over a mnemonic, it will show a short description of the assembly instruction.

For the documentation window, affected condition codes, allowed operation sizes and addressing modes are listed for the selected instruction (so only stuff from cmpa is listed when you're looking at a cmp.w a0,a1 instruction).

If the current statement has no valid syntax, the instruction details of all matching mnemonics will be shown instead.

Known issues

• Find Usages always shows "Unclassified" though it shouldn't (?)
• Macro invocations are not yet evaluated, thus no referencing to symbols defined via macros (e.g. STRUCT).
• No support for includes. Scoping is for global symbols and labels is currently the whole project.
• No support for register replacement (e.g. registers replaced by EQUR or EQURL will cause syntax errors)
• While the Lexer supports the -spaces option (where a space introduces a comment), this cannot be configured yet (default is off).
• No support for other processor instructions, FPU or 68020+ address modes.
• Unit Test coverage is not as good as it could be (ahem).
• opt keyword needs special treatment and will currently show a parsing error.
• Missing but planned features:
  • Macro evaluation on invocation
  • Folding
  • More semantic inspections
  • Quick fixes
  • Maybe formatter + Code Style Settings
  • Register use analysis (but this only makes sense after macro evaluation)
  • Cycle counting

Recommendations

Currently, I would suggest using the fabulous Browse Word at Caret Plugin to highlight the same address and data registers while editing (see new View -> Highlight Word at Caret menu item).

Development notice

This plugin has been written in Kotlin 1.5 using Grammar-Kit.

It is probably the only plugin (besides Cajon from the same author) that uses JUnit 5 Jupiter for unit testing so far (or at least the only one I'm aware of ;) ). The IntelliJ framework actually uses the JUnit 3 TestCase for plugin testing, and it took me quite a while to make it work with JUnit 5. Feel free to use the code (in package de.platon42.intellij.jupiter) for your projects (with attribution).

Private TODO list

• code completion suggestion for unresolved global labels and symbols
• support include directive
• support opt directive
• suppression support via comments
• inspection: Unresolved local label
• inspection: Unresolved macro

Changelog

V0.6 (unreleased)

• Enhancement: opt and several other directives (printt, fail etc.) no longer causes a syntax error when unquoted.
• Enhancement: include, incdir and incbin and output with <pathname> quotes no longer cause syntax error.
• New: Files in include directives can be referenced and renamed/refactored.
• New: Code completion for local label definitions, suggesting undefined labels already referenced.
• New: Added inspection suppression possibility and quickfix.

V0.5 (06-Aug-21)

• Bugfix: movem ISA was wrong regarding the movem.w <ea>,<registerlist> (sign extends registers).
• Cosmetics: Changed Register Flow Documentation wording from reads to uses and from modifies to changes.
• Bugfix: Minor fix for andi/eori/ori to ccr which were not byte sized in ISA.
• Bugfix: Added alternate condition code tests HS (=CC) and LO (=CS).
• Performance: Optimized mnemonic lookup.
• Enhancement: Reworked Instruction Documentation provider, now shows condition codes.
• Bugfix: In ISA exg is no longer treated as setting a definitive value.
• New: Added inspection to find dead writes to registers!
• New: Added inspection to warn about unexpected condition code unaffecting instructions before conditional instructions.

V0.4 (03-Aug-21)

• Notice: Due to major new API use, this plugin no longer works on IDEs >=2019.3.1, but rather requires >=2020.3.
• Enhancement: Added Structure View filters.
• New: Added inspection to validate the correctness of a MC68000 instruction regarding operation size and address modes.
• Bugfix: Added several missing assembler directives (opt, machine, etc.).
• Bugfix: Uppercase hexadecimal literals were not parsed (JFlex bug?).
• Bugfix: Interpretation of register lists was wrong in BNF.
• New: Added Documentation Provider for symbol definitions (shows assigned declaration).
• New: Added Documentation Provider for mnemonics (simple version, generated out of ISA information).
• Bugfix: Macro definitions with colons and without space supported (as found in P61a source).
• New: When asking for documentation on registers, a code flow analysis is done. Cool stuff!

V0.3 (28-Jul-21)

• Enhancement: Macro contents are no longer parsed, added syntax highlighting options for macros.
• Enhancement: Macro definitions are now word and stub indexed, macro calls reference to definition.
• New: Macro definition refactoring and find usages support.
• Enhancement: Structural View also shows macro definitions.
• Bugfix: Missing REPT and ENDR assembler directives added.
• Cosmetics: Changed or added some icons at various places.
• Performance: Reference search for global labels and symbols now uses stub index.
• Compatibility: Restored compatibility with IDE versions < 2021.1.
• Performance: Optimized lexer.

V0.2 (27-Jul-21)

• Cosmetics: Added (same) icon for plugin as for file type.
• Performance: Use Word-Index for global labels and symbols instead of iterating over the file.
• Performance: Use Stub-Index for global labels and symbols.
• Bugfix: No longer reports a syntax error when file lacks terminating End-Of-Line.
• Enhancement: Registers are now offered for code completion, making editing less annoying.

V0.1 (20-Jul-21)

• Initial public release.