s68k is an M68K assembler and interpreter written in Rust. The assembler reports errors and warnings to help with learning assembly and encodes instructions in memory as EASy68K does. The interpreter runs the assembled program and supports stepping, undo, and breakpoints.
The library compiles to WebAssembly for use from JavaScript and Node.js. It is available on npm.
It is part of a family of JavaScript assembly interpreters and simulators:
- MIPS: git repo, npm package
- RISC-V: git repo, npm package
- X86: git repo, npm package
- M68K: git repo, npm package
- Z80: git repo, npm package
s68k is a teaching tool for M68K assembly. Its diagnostics explain invalid syntax, addressing modes, and directives. It can write programs as S-record files in the format produced by EASy68K's assembler and loaded by its simulator. It is not intended to produce binaries for real 68000 systems.
The library has four parts:
-
Assembler (
src/assembler/): reads project source files starting from the entry file. It reports all diagnostics it finds and, if there are no errors, returns a program. It contains a tokenizer, parser, symbol table, expression evaluator, layout pass, instruction table and analyzer. -
Program: the assembler's output. It contains assembled instructions with their addresses, sizes, encodings and source locations, along with initial memory, symbols and the entry point.
-
Interpreter (
src/interpreter.rs): runs a program from memory using registers and the status register. It supports stepping, running to the end, undo history, breakpoints and a call stack. A watched memory range supports a memory-mapped device: every store to the range ends the run. -
Machine (
src/machine/): handles processor encodings. The decoder reads instruction words for the 68000, 68010 and 68020, the encoder writes them, and the disassembler prints EASy68K syntax. The decode cache holds instructions for the interpreter. Exception frames and cycle counts follow the selected processor.
The assembler chooses each instruction's 68000 encoding as EASy68K does (below) and writes it into the program's memory at its real size. Addresses therefore match those of a 68000 and EASy68K's listing. The interpreter runs those bytes (below, "Code is memory").
The interpreter runs the bytes in memory through a cache of decoded instructions. The cache uses 4 KB pages with one slot per word, allocated only where code exists. When the interpreter is created, the cache is filled from the assembler's instructions, so that code does not need decoding while it runs.
Every write passes through the cache, including writes by the program, trap tasks, the host and undo. A write clears the instructions it covers, which are decoded from their new bytes before they run. A program can therefore read and change its own code, as on a 68000. Undo restores the old bytes, so the old instruction runs again.
- A code write occurs when a program store or a trap task's answer writes into an instruction that has been decoded. Each step reports the first instruction overwritten (
wroteCodeon the step,getCodeWrite()), giving its address and line index. WithrunWithBreakpoints(…, {stopOnCodeWrite: true}), a run stops after a code write with statusCodeWrite; the next run continues. A Poke, a testcase's starting memory and undo never report a code write. - Source locations come from the program's map of the lines it laid out. The map does not move when bytes change: a changed line keeps its location, breakpoint and
getInstructionAtresult as assembled.disassembleAt(address)instead prints the current contents of memory.getInstructionAtalso reports an assembler-selected form that differs from the source (assembledAs):add.l #1,d0isADDQ.L #1,D0,bra loopisBRA.S loop, andlea $1000,a0isLEA $1000.W,A0. - The 24-bit bus. Memory covers the 16 MB reachable by the 68000's 24 address lines. Addresses use their low 24 bits, as in EASy68K's
& ADDRMASK. An access past$FFFFFFwraps to$000000: this applies to a long at$FFFFFE, a stack pushed below$000000, instruction words crossing the end, strings read and lines written by trap tasks, and host reads and writes. File task buffers are the exception, as in EASy68K: a read or write past the end returns 2 (below). The map, decode cache and watched range see the bytes at their wrapped addresses. Only a run of bytes longer than the whole 16 MB is refused as out of bounds. - The end.
$FFFF $FFFFis EASy68K's SIMHALT wherever it occurs. Within bytes placed by the program, whether code or data, it pauses execution likesimhalt. Elsewhere it ends the program withEndOfProgramand the address. Memory starts as$FF, so a program that does not end itself stops there, one past its last instruction if nothing follows it. Other bytes execute as the instructions they decode to: execution that reaches or jumps into data runs that data, and a word that is not an instruction raises an illegal instruction exception. Fetching an instruction at an odd address raises an address error; a jump to an odd address raises it in the jump itself, as on a 68000.
The machine follows the 68000, including where EASy68K differs from it. Every exception is taken through the vector table at $000 to $3FF:
| Vector | Address | Raised by | Stacked PC |
|---|---|---|---|
| 2 | $008 |
a bus error: an access the memory map refuses (below, "The memory map") | as for an address error at the same access; an instruction that could not be fetched, its own |
| 3 | $00C |
an address error: a word or long at an odd address, an instruction fetched from one, a jump to one | where the prefetch had got to, the 68000's (below) |
| 4 | $010 |
illegal, and a word that is no instruction |
the instruction's |
| 5 | $014 |
divs or divu by zero |
the next instruction's |
| 6 | $018 |
chk out of bounds |
the next instruction's |
| 7 | $01C |
trapv with V set |
the next instruction's |
| 8 | $020 |
a privileged instruction in user mode: move <ea>,sr, andi/ori/eori #n,sr, rte, stop, reset, move usp |
the instruction's |
| 9 | $024 |
trace: after an instruction that started with T set | the next instruction's, or the handler's of the exception it raised |
| 10, 11 | $028, $02C |
a line A word $Axxx and a line F word $Fxxx |
the instruction's |
| 25 to 31 | $064 to $07C |
an interrupt request at level 1 to 7, through its autovector (below, "Interrupts") | the instruction it came before |
| 32 to 46 | $080 to $0B8 |
trap #0 to trap #14 |
the next instruction's |
| 47 | $0BC |
a trap #15 task that is none of EASy68K's |
the next instruction's |
The 68010 uses the same table and adds bkpt and movec of a register it does not have as causes of vector 4. An rte format error uses vector 14 at $038. The processor reads vectors through VBR, pushes 68010 frames, and stacks the faulting instruction's address for address and bus errors (below, "The 68010").
The 68020 has the 68010's exceptions, adds chk2 and trapcc alongside chk and trapv, and uses 68020 frames. It permits data reads and writes at odd addresses, so its only address error is an instruction fetch at an odd address (below, "The 68020's supervisor model").
- Taking an exception. The processor reads the vector, copies the status register, sets S, clears T, pushes a frame on the supervisor stack and jumps to the handler. A normal frame is six bytes: the status register followed by the program counter. A bus or address error frame is 14 bytes: the special status word, access address, instruction register, status register and program counter. The special status word contains bits 15 to 5 of the instruction register, R/W, I/N clear, and the function code for the mode and space of the access.
rtepops six bytes; a bus or address error handler removes the other eight itself. - No handler. An odd address in a vector means there is no handler. The program ends with the error and vector in
Exception {cause, vector}. Memory starts as$FF, so each vector reads$FFFFFFFFuntil the program writes 8BD0 it. A program that installs no handler therefore ends when an exception is raised. - A double fault halts the processor with
Halted {cause, vector}. This happens if a frame is pushed on an odd supervisor stack pointer or into a range refused by the memory map, if a vector is read from an invalid range, or if the map refuses to fetch a bus or address error handler. Other exception handlers are fetched by the next step. If that fetch causes a bus error and its handler cannot be fetched, the processor halts in turn. - Supervisor and user mode. A program starts in supervisor mode with EASy68K's registers: SR
$2000, A7 as the supervisor stack pointer at$01000000, and the user stack pointer at$00FF0000. A7 holds the stack pointer for the mode selected by S. A write to SR, an exception orrtecan swap the two.getSystem()returns{sr, usp, ssp};setSr,setUspandsetSspwrite them and are journaled inside a poke. The 68020 has a third, master stack pointer selected by M (below, "The 68020's supervisor model"). On a 68000,move sr,<ea>is not privileged andtrap #15works in user mode, as in EASy68K. - Trace. T is sampled before an instruction. If it was set, a trace exception follows the instruction unless it raised an illegal instruction, privilege violation, line A or F, or address error and did not finish. After
trap,trapv,chkor division by zero, the trace frame is pushed on top of that exception's frame. The trace handler runs first and returns to the other handler, as on a 68000; EASy68K pushes the frames in the opposite order. Atrap #15task that waits for the host is traced after it is answered. - Address error PC and side effects. These follow the 68000 behavior left by MAME's microcode for the 55,606 address errors in the conformance suite. A jump to an odd address faults in its own prefetch:
bsrhas pushed its return address, butjsrhas not. A data access stacks the address reached by prefetch, which depends on the operands. A word access through(An)+has moved the register; a long access has not.clrandmove sr,<ea>read their destination first, so an odd destination faults as a read. The rules are insrc/machine/exception.rs. - The call stack gains a frame for each exception, with
kind: 'exception', itsvector, the error name incause, and the vector base register used invbr. Like a call's frame, it is gone once the stack pointer of the stack it was pushed on is above it, whichrtedoes, and so does anrtrthat pops it. The step recordsPushException(with the samecauseandvbr) andPopException, and stack swaps through theWriteStackPointersmutation (which identifies the stack pointer A7 became). Undo reverses all of it.
The 68000's interrupt requests, IRQs, are EASy68K's without its hardware window: seven levels, all autovectored, from timers, the keyboard and the mouse.
-
Latched. A request at level 1 to 7 waits in a latch until it is taken. A second request at an already pending level is the same request.
-
Taken between instructions. Before the next instruction, the processor takes the highest pending level above the status register's interrupt mask. Level 7 is taken regardless of the mask. The autovector is vector 24 plus the level, at
$60plus four times the level. The exception pushes a six-byte frame on the supervisor stack, sets S, clears T and raises the mask to the level. A handler can therefore be interrupted only by a higher level or level 7. Taking an IRQ is a separate execution step withkind: 'irq'and no location; History shows it and Undo reverses it on its own. An autovector with no handler ends the program withIrq {level}as the cause and identifies the vector. -
Other exceptions. As on a 68000, an instruction's trace frame and the frame for
trap,chk,trapvor division by zero are pushed first, and the IRQ handler runs before their handlers. An illegal instruction at the program counter has not yet been fetched, so it raises its exception after the IRQ handler'srte. A request arriving while atrap #15task waits for the host is taken after the answer. EASy68K loses an interrupt taken beside a trap and runs an illegal instruction twice. -
stop #nis privileged and loads the whole status register, including T and S. The processor waits for a request above the new mask, with statusStoppedand the program counter at the next instruction. While it waits,step()and every run returnStoppedimmediately. A request that can wake it changes the status toRunningimmediately, and the next step takes the request.getMachineState().stoppedis true until then. If a request above the new mask is already pending,stopdoes not wait. If it starts with T set, it takes the trace exception instead of stopping, as on a 68000. With S clear in the immediate, the processor stops in user mode; EASy68K raises a privilege violation instead. EASy68K also runs one more instruction before the interrupt that wakes it. -
resetis privileged and takes 132 cycles but does nothing else (below, "Cycles"). There are no devices behind the reset line, and nothing runs the 68000's reset sequence. -
The sources. The program configures interrupt sources and the host delivers their requests:
Task D1What it sets 32 D1.B= 6, withD2.BandD3.Lthe timers, EASy68K's setAutoIRQ:D2.B= 0 turns all off, 1 to 7 turns that level's off,$81to$87fires that level everyD3.Lmilliseconds; any otherD2.Bdoes nothing60 level in bits 15 to 8, events in bits 0 to 2 the mouse's: a button down (bit 0), a button up (bit 1), a move (bit 2), each chosen one set to the level, 0 turning it off; a level above 7 makes the call do nothing 62 the same, bits 0 and 1 the keyboard's: a key down (bit 0) and a key up (bit 1) For
D1.B= 4, task 32 also returns EASy68K's version,$00051001, inD1.L; it accepts 5 as well. Values 0 to 3 and 7 request the hardware window and its devices' addresses and are refused withUnsupportedTrapTask {task: 32}because there is no hardware window. Any otherD1.Bdoes nothing, as in EASy68K. -
The host calls.
getMachineState()returns{pendingIrqs, stopped, autoIrqs: {level, intervalMs}[], keyboardLevels: {keyDown, keyUp}, mouseLevels: {down, up, move}}. A level of 0 means none. The host runs timers on the program's time and callsraiseIrq(level)at each firing. It reports screen events withdeviceEvent('keyDown' | 'keyUp' | 'mouseDown' | 'mouseUp' | 'mouseMove'), which latches and returns the level configured by the program, ornull. Both calls provide input between instructions, like a key press, and do nothing after the program ends. -
Undo. The program's configuration and the stopped state are journaled like registers in a
SetMachineState {old, new}mutation. Undo restores them. The latch also contains host input: undoing an IRQ step makes its request pending again, so continuing takes it again. A request arriving after a step remains pending when that step is undone, since the program never saw it.
A program declares ranges of EASy68K's memory map with memory, one of each kind at most, and the interpreter enforces them as EASy68K's simulator does (memoryMapCheck, mem_put and mem_req in its UTILS.CPP):
| Kind | A read | A write |
|---|---|---|
rom |
allowed | ignored: memory keeps what it held, and it is no error |
read |
allowed | a bus error |
protected |
a bus error from user mode | a bus error from user mode |
invalid |
a bus error | a bus error |
- Checks. Reads are checked against invalid and protected ranges by their first byte. Writes are checked against all four kinds by every byte. A long that starts below a range and extends into it is therefore refused as a write but not as a read. Each instruction word is checked as it is fetched, as EASy68K fetches each word as a read. Code in an invalid range, or in a protected range in user mode, raises a bus error in program space. The kinds are checked in EASy68K's order: invalid, protected, read only, then ROM. Address errors take precedence over the map.
- Bus errors use vector 2 and the 14-byte address error frame. The 68000 status word records R/W for the access, clears I/N and gives the function code for the processor's actual mode. EASy68K always reports a supervisor write. Without a handler, the program ends with
BusError {address, size, access, range}and the vector. The instruction aborts at the error, as on a 68000; EASy68K finishes it. - Protected ranges use the processor's S bit; EASy68K instead reads the SR field in its window. An exception vector is read in supervisor mode, so a protected vector table can serve user mode.
- ROM stores are ignored. They create no journal entry, change no code, and are neither code writes nor watched writes.
trap #15buffers are checked as in EASy68K. Strings read by tasks 0, 1, 13, 14, 17, 18 and 95, and paths read by tasks 51, 52, 57, 59, 70, 71, 73 and 74, are checked from the start through the NUL against invalid ranges. Task 54's file-write buffer is checked against invalid ranges. Task 53's file-read buffer is checked against invalid, read-only and ROM ranges; a ROM range accepts nothing and the task does nothing. None checks protected ranges. Task 2's line and task 58's dialog are written without checks, as in EASy68K. An empty buffer, a string consisting only of its NUL, or a read of no bytes is refused if it starts inside a range after its first byte, but not on that first byte. This follows EASy68K'sloc + bytes - 1 >= start && loc <= endcheck.- Debugger and host access bypasses the map: Pokes, testcase starting memory, host reads,
disassembleAt, undo and the program's initial contents are not checked. - With no range declared, an access checks one flag and continues. The decode cache does not keep instructions whose words overlap invalid or protected ranges. Each fetch is decoded and checked in the current processor mode, and a write into one is not a code write.
The interpreter counts the clock cycles a 68000 takes, with the 68000's own time for each instruction, exception and interrupt request (src/machine/timing.rs). A 68010 program also uses exact processor timings. A 68020 program uses an estimate based on the cache case in the 68020 manual (below, "The 68020's cycles").
- Sources. Base instruction and effective-address times come from section 8 of the 68000 User's Manual, with corrections from Yacht ("Yet Another Cycle Hunting Table"). Each is checked against the cycle lengths recorded by the conformance suite (below, "Conformance"). As in that suite, the bus responds immediately, with no wait states.
- Data-dependent times.
mulutakes two cycles for each set bit in its source, andmulstakes two for each change between its bits.divuanddivsuse the microcode loop time, calculated with Jorge Cwik's method: 76 to 136 and 120 to 156 cycles respectively, or 10 and 16 or 18 when the quotient overflows. A register shift or rotate takes two cycles per bit of its count, modulo 64.movemtakes four or eight per register.Bcctakes 10 when it branches, or 8 for.sand 12 for.wwhen it does not.DBcctakes 10 when it branches back, 12 when the condition is true and 14 when the counter runs out.Scctakes two more cycles when it sets a register;bchg,bclrandbsettake two more for a register bit above 15. - Exceptions take the 68000's time for the whole step: 34 cycles for
trap #0to#14,trapv, illegal instructions, privilege violations and line A and F words; 38 plus the source effective address for division by zero; and 38 above the bound or 40 below zero forchk, plus the source effective address. An address or bus error takes 58 cycles from the aborted access, after the time the instruction has already taken. Trace adds 34 after the instruction; an IRQ takes 44 in its own step.stoptakes 4 andreset132. trap #15tasks take no time, as in EASy68K. A number that is not an EASy68K task takes 34 cycles as atrapthrough vector 47.- The counter is 64 bits.
getCycles()returns it as abigint(get_cycles()in Rust). Each history step records its owncycles, and undo restores the counter. Task 30 clears the counter; task 31 reads it intoD1.L, returning 0 once it exceeds 32 bits, as in EASy68K. A step that clears the counter still records its own time. - Processor precision. The 68010 counts its own time (below, "The 68010"); the 68020 uses an estimate (below, "The 68020's cycles").
program.getInfo().cyclesExact, orprogram.hasExactCycles()in TypeScript, reports whether the count is exact. It is true for 68000 and 68010 programs and false for 68020 programs, whose count a host shows as an estimate. It is also false for a 68000 or 68010 program usingopt bitwith a bit-field instruction: those instructions take EASy68K's time, the 68020 cache case (below, "The 68020's instructions"), while the other instructions retain exact timings.
Where EASy68K's counts differ from the 68000's, s68k counts the 68000's:
| s68k, the 68000 | EASy68K | |
|---|---|---|
trap #0 to #14, and a task through vector 47 |
34 | 38 |
| a division by zero | 38 and the source's effective address | 42 |
chk out of bounds |
38 above the bound, 40 below zero, and the source's effective address | 44 |
| an IRQ | 44 when it is taken | 34 when it is taken, and 44 more when it is requested |
| an address or bus error | the time before the access, and 58 | 50 |
tst of memory |
4 and the effective address | 4 |
muls |
two per change between two bits of the source, a zero below the lowest | two per change, counted slightly differently |
The interpreter is checked against SingleStepTests/m68000, a suite generated from MAME's microcoded 68000 (MIT). Each test provides the state before and after one instruction. The runner sets the initial state, executes the instruction and compares the registers, status register, program counter, every RAM word listed in the final state, and cycle count. It also checks that nothing else was written. Musashi's sixty self-checking 68000 programs run as well, each until it writes its verdict.
-
cargo testruns the vendored subset, the first 50 tests of each of the 127 files that raise no address error (tests/m68000/), and Musashi's programs (tests/musashi/mc68000/). -
The whole suite, 317,500 tests, runs from a fetched copy:
scripts/fetch-m68000-tests.sh cargo test --release --features conformance conformance:: -- --ignored --nocaptureThe suite takes a few minutes and prints counts for every file. The
conformance::filter excludes the crate's other ignored tests, which need GNU binutils for m68k.S68K_M68000_ONLY=ASR.b,ASR.wselects only the named files;S68K_M68000_TESTSpoints to another copy of the suite'sv1folder. A GitHub Actions workflow runs the suite weekly. -
The skip list gives a reason for each exclusion (
src/conformance/skips.rs):trap #15, EASy68K's service trap. Every exception the suite takes is checked, including its frame: address errors, privilege violations, line A and F,trap,chk,trapvandrte, in both modes. The suite also checksstopandreset. Sincestopleaves the processor stopped before prefetch, its program counter is compared with the suite's next prefetch. -
Every test's length is compared with its step's cycle count (above, "Cycles"), including
tasandtrapv. The suite's README does not vouch for those two timings, but its results agree with the 68000's times for all 2,500 tests of each.
The counts on 2026-10-28, with the suite at its pinned commit, the lengths compared:
| Tests | Run and passed | Failed | Skipped | |
|---|---|---|---|---|
| The whole suite | 317,500 | 317,340 | 0 | 160 |
| The vendored subset | 6,350 | 6,347 | 0 | 3 |
| Musashi's programs | 60 | 55 | 0 | 5 |
| Musashi's 68040 programs, as 68020 programs | 17 | 17 | 0 | 0 |
Of the 127 files, 126 pass all 2,500 tests, including their lengths. TRAP passes all 2,340 tests that are not trap #15, the only skip. Five Musashi programs remain skipped. abcd, sbcd, divs and divu check Musashi's answers where they differ from 68000 microcode: BCD digits above 9 and flags after division overflow. move uses a 68020 form of cmpi.
No single-step suite covers the 68010, so a differential harness runs s68k alongside a reference 68010, one instruction at a time (src/test/differential.rs). It runs every first word the decoder accepts as a 68010 instruction from random states. Under Musashi, one in eight states has trace enabled. The harness compares registers, both stack pointers, the status register, program counter, VBR, SFC, DFC, every byte either implementation wrote (including frames), and cycles.
Both references are MIT licensed and fetched rather than vendored. For host tests, build.rs compiles each with the cc crate only when its feature is enabled:
scripts/fetch-musashi.sh
cargo test --release --features musashi differential -- --ignored --nocapture
scripts/fetch-moira.sh
cargo test --release --features moira differential -- --ignored --nocapture- Musashi checks behaviour. The
RELAXATIONSlist gives a reason for each case excluded because Musashi differs from a 68010: it has no address errors in 68010 mode, forgets a pending trace when an instruction takes an exception, allows a 68010movecCACR, runs the 68040'smove16, and pusheslink a7's A7 four lower. It also sets flags left undefined by the manual differently from MAME's 68000 and does not check therteversion. Its cycle table gives maxima and has no loop mode, so cycles are reported but not compared. - Moira checks behaviour and cycles. Its 68010 counts cycles for each bus access and is checked against cputester on hardware, including loop mode. The harness compiles it with precise timing and without Musashi mimicry. Each one-word instruction also runs step by step against Moira in a loop with a
dbfback to it. The harness excludes flags the manual leaves undefined after decimal instructions and division by zero. It also excludes cycles fordivsof$80000000, whose absolute value Moira computes in 32 bits. - GNU
as -m68010encodes every 68010 instruction form the same way in the crate's opt-in GNUascheck. The check compares every form in the table withas -m68000and the 68010 forms withas -m68010:S68K_BINUTILS_PREFIX=/usr/bin/m68k-linux-gnu- cargo test --release gnu_as -- --ignored.
The counts on 2026-10-29 use two cases of each first word, or four against Moira:
| Cases | Agree | Left out | |
|---|---|---|---|
| Musashi, behaviour | 102,543 | 102,543 | 5,847, by the list |
| Moira, behaviour and cycles | 216,536 | 216,536 | 244 |
| Moira, loop mode, step by step | 28,064 loops, 10,786 of them in loop mode | 28,064 | 9,813, which take an exception |
GNU as -m68010 |
134 lines | 134 |
- Macros and conditional assembly
| Type | Instructions |
|---|---|
| Arithmetic | add, sub, suba, adda, divs, divu, muls, mulu, addq, subq, addi, subi, addx, subx, negx |
| Comparison | tst, cmp, cmpi, cmpa, cmpm |
| Branching and jumping | bcc, bcs, beq, bne, blt, ble, bgt, bge, bls, bhi, bpl, bmi, blo, bhs, bvc, bvs, bsr, bra, jmp, jsr, rts, dbcc, dbcs, dbeq, dbne, dbge, dbgt, dble, dbls, dblt, dbhi, dbmi, dbpl, dbvc, dbvs, dbf, dbt, dbhs, dblo, dbra |
| Condition codes and status | scc, scs, seq, sne, sge, sgt, sle, sls, slt, shi, smi, spl, svc, svs, sf, st, shs, slo, move/andi/ori/eori with sr or ccr as an operand, and move usp,an and move an,usp; move ccr,<ea> is the 68010's, under opt p=68010 |
| Bitwise | not, or, ori, and, andi, eor, eori, lsl, lsr, asr, asl, rol, ror, roxl, roxr, btst, bclr, bchg, bset |
| Binary coded decimal | abcd, sbcd, nbcd |
| Other | clr, exg, neg, ext, swap, move, link, unlk, lea, pea, moveq, movea, movem, movep, tas, nop, and the 68020's extb under opt p=68020 |
| The 68010's | rtd, bkpt, movec, moves and move ccr,<ea>, under opt p=68010 or opt p=68020 |
| The 68020's | chk2, cmp2, cas, cas2, pack, unpk, divsl, divul, trapcc and its aliases, the long forms of muls, mulu, divs, divu, chk and link, link.w, the 68020 manual's spelling of link, tst and cmpi with operands the 68000 cannot read, and extb, under opt p=68020 (below, "The 68020's instructions") |
| Bit fields | bftst, bfextu, bfexts, bfffo, bfchg, bfclr, bfset, bfins, under opt p=68020, or opt bit with the 68000's addressing modes |
| Exceptions | chk, trapv, illegal, trap #0 to #14, rte, and rtr, which returns and restores the condition codes (above, "Exceptions") |
| Interrupts and control | stop, which waits for an interrupt request, and reset (above, "Interrupts") |
| Interrupt | trap #15, with the I/O tasks 0-9, 11-20, 23, 24 and 33 in d0, the file tasks 50-59, the mouse task 61, the sound tasks 70-77, the graphics tasks 80-96, the interrupt-request tasks 60 and 62, and task 32 with 4, 5 or 6 in d1.b (the Interrupt enum of src/instructions.rs is the list of those the host answers) |
Where the 68000 has several encodings of a line, s68k picks the one EASy68K picks:
- The first of EASy68K's forms that fits:
cmp #n,dniscmp, andcmp #n,(a0)iscmpi;and #n,dnandor #n,dnareandandor, and into memoryandiandori;eor #niseori;add #n,anandsub #n,anareaddaandsuba, andadd #n,dnisaddi. - The optimisations EASy68K always makes:
move.l #n,dnof -128 to 127 ismoveq, and anadd,addi,adda,sub,subiorsubaof 1 to 8 isaddqorsubq. Writing the immediate#n.lkeeps the long form,move.l #1.l,d0; it is the one size suffix an immediate takes. - An unsized branch is short if its target is above the line and its displacement fits a byte and is not 0. Zero marks a word branch. Otherwise, the branch is a word.
.sand.bforce a short branch, and.wforces a word branch. On the 68000,.lalso forces a word branch, as in EASy68K, because there is no long branch. Underopt p=68020, 10000 it forces the 68020's six-byte long branch (below, "Processor dialects"). An unsized absolute address is.wif it is above the line and fits a word, and.lotherwise. "Above" includes a label on the same line; a number is always above. - An immediate is kept at the size the instruction reads it at, so
move.w #-1,d0holds$FFFF, andexg a0,d0isexg d0,a0. - Under
opt p=68020, a line that the 68000 can encode keeps its 68000 encoding. The assembler chooses a wider 68020 form only where the 68000 has none. For a known displacement above the line that exceeds a 68000 field—a word ford(An)andd(PC), or a byte ford(An,Xn)andd(PC,Xn)—it selects a word or long 68020 base displacement as needed. An unsized backward branch beyond word range becomes long, as in vasm. A name defined below the line keeps the 68000 field and causes an error if it does not fit. The hint suggests an explicit width,(label.w,a0,d0)orbra.l: without relaxation, a forward branch that might be long would always be long. In 68020-specific forms, an unsized base or outer displacement is omitted for a known zero, uses a word or long as needed for a known value, and uses a long for a name below (below, "The 68020's addressing modes").
Like EASy68K, the assembler uses two passes with nothing in between. The first chooses instruction sizes using these rules; a name defined below the line is always given the long form, whatever its value. The second encodes each instruction at its laid-out size. Instructions start on even addresses and occupy two to ten bytes, or up to 22 with 68020 addressing modes.
A branch displacement that does not fit is an error, as in EASy68K. A short branch must be in -128 to 127 and cannot target the very next instruction, because displacement 0 marks a word branch. A word branch or dbcc must be in -32768 to 32767. A PC-relative displacement is measured from its own extension word: two bytes past the instruction, four for movem, btst #n and 68020 instructions whose own extension word comes first, and four or six for the 68020's cmpi against the program counter.
Three lines EASy68K refuses are refused here too, since the 68000 has no encoding for them: an address register added into memory (add.l a0,(a1)), a bit number written as an immediate on an immediate (btst #1,#5, where btst d1,#5 is the instruction), and a link displacement outside -32768 to 32767.
A program targets the 68000 unless it specifies opt p=68010 or opt p=68020 before its first instruction. This is Devpac syntax, also accepted by vasm. opt bit retains EASy68K's meaning: it enables the 68020's bit-field instructions on a 68000. p=68020 implies it.
The program exposes its selection through program.getProcessor() and the processor and bitFields fields of program.getInfo(). The latter also has cyclesExact, which is false for the 68020's estimated cycles (below, "The 68020's cycles") and for a program using a bit-field instruction under opt bit. The program's code is decoded for the selected processor. A later processor's word is an illegal instruction in an earlier processor's program, both during execution and in disassembleAt.
S68k.assemble also returns processor and bitFields beside diagnostics, whether or not it builds a program. An editor can therefore identify the target even when the source has an error.
- Selection must precede code. Each instruction is checked and measured for the processor in force. An
opt p=oropt bitafter an instruction is an error (processor_chosen_after_code) and changes nothing. Repeating the same processor is harmless; selecting another isprocessor_chosen_twice, even across project files. A processor other than these three producesunknown_processor. - Instruction availability. Each form in
S68k.instructionTable()has aprocessorfield naming the first processor that supports it. A later form is refused withneeds_a_later_processor. Its hint gives the 68000 alternative and theopt p=line to add. The TypeScript diagnostic'sfixescontains both suggestions, with theopt p=fix first. Each has a title, location and replacement text; a location without columns inserts text. - The 68010 is complete (below).
- The 68020 has every user-mode integer instruction except
callmandrtm, which are permanently omitted (below, "The 68020's addressing modes" and "The 68020's instructions"). It includes the 68010 instructions, long branchesbra.l,bsr.landb<cc>.l, every addressing mode, and every form it adds to a 68000 instruction. A later form such asmuls.lortst a0in an earlier program producesneeds_a_later_processor, just like a new 68020 instruction. The supervisor model is that of a 68EC020 (below, "The 68020's supervisor model"); cycle counts are estimates based on the manual's cache case (below, "The 68020's cycles"). opt bitgives a 68000 or 68010 program the eight 68020 bit-field instructions, as in EASy68K, using that processor's addressing modes. For example,bfextu (8,a0,d1.w*4){0:8},d0still needsopt p=68020. Without the option, a bit-field instruction in an earlier program producesneeds_a_later_processor, whose second fix addsopt bit. The code decodes for the selected processor and its bit fields.
opt p=68020 gives a program every addressing mode of the 68020 (the M68000 Programmer's Reference Manual, 2.2.7 to 2.2.10 and 2.2.13 to 2.2.15), written in the Motorola syntax vasm and GNU as read (docs/grammar.md 2.5), wherever the 68000 takes d8(An,Xn) or d8(PC,Xn):
| Form | Example | What it reaches |
|---|---|---|
| A scaled index, the brief extension word | (4,a0,d1.w*4), 8(pc,d0.l*2) |
A0 + 4 + D1.W × 4 |
| A base displacement of a word or a long | (1000,a0,d1.l), (100000.l,a0) |
A0 + 1000 + D1.L |
| A base suppressed or left out | (d0.l*4), (table,d1.w*2), (4,za0,d1), (zpc,d0) |
D0.L × 4; table + D1.W × 2 |
| An index suppressed | (a0,zd0), (label.l,pc,zd0) |
A0 |
| Memory indirect, postindexed | ([4,a0],d1.w*4,8) |
the long at A0 + 4, + D1.W × 4 + 8 |
| Memory indirect, preindexed | ([4,a0,d1.w*4],8) |
the long at A0 + 4 + D1.W × 4, + 8 |
| The same from the program counter | ([table,pc],d0.l), ([zpc]) |
reads in program space |
-
Omitted parts. The base, index and either displacement may be omitted, as the manual allows. Write a displacement width as
.wor.lafter it, or let the assembler choose (above, "Encodings").(d.w,An)and(d.w,PC)are the 68000's ownd(An)andd(PC). An index without a size is.w, as on the 68000; GNUasmakes it long.za0toza7,zd0tozd7andzpcare registers only inside parentheses, wherepcis also a register, and only if no Symbol has that name. A Symbol namedza0keeps its meaning wherever it can stand:(za0)is its address and(za0,a1,d0)uses it as a displacement. This also holds in a 68000 program, which has no suppressed registers. A 68020 program receivessymbol_named_like_a_registerwhere the name could also have been a register (docs/grammar.md1.10). -
Extension words. These are the brief and full extension words of M68020UM, with base and outer displacements after the full word. The decoder reads a 68020 Program's index word as a 68020 does: bits 10–8 mark the scale and full word. Other Programs use the 68000 interpretation. Reserved combinations are read bit by bit as in Musashi and printed as their words. The disassembler prints every form with its widths; its output assembles back to the same words.
-
Running. A memory indirect Operand reads its long pointer as a program read, in program space when using the program counter. A pointer or operand at an odd address is read normally, as the 68020 permits data at any address.
-
Cycles. Each mode uses its row in the manual's effective-address tables, according to displacement widths and whether it reads memory (below, "The 68020's cycles").
-
Long branches
bra.l,bsr.landb<cc>.luse a 32-bit displacement. An unsized backward branch beyond word range uses this form. -
Verification. GNU
as -m68020writes the same words for every form in the 2,000-line opt-in check (S68K_BINUTILS_PREFIX=… cargo test --release gnu_as -- --ignored). The differential harness also runs random Operands of every mode against Musashi's 68EC020:cargo test --release --features musashi the_68020s_addressing -- --ignored. All 39,930 cases agree, including data at odd addresses. The 70 jumps to an odd address are excluded: they are the only exception these cases raise, and s68k's 68020 takes an address error while Musashi's 68020 has none. The supervisor-model runs compare every other exception (below).
opt p=68020 enables the 68020's user-mode integer instructions described in M68020UM and the Programmer's Reference Manual. Where Motorola leaves a flag or the result for overlapping registers undefined, s68k follows WinUAE's 68020 behavior, derived from Toni Wilen's cputester runs on hardware (newcpu_common.cpp and gencpu.cpp). This sometimes differs from the 68040 modeled by Musashi.
| Instruction | Forms | What it does |
|---|---|---|
chk.l |
chk.l <ea>,Dn |
chk of the whole register against a long bound, vector 6 |
link.l, link.w |
link.l An,#d, link.w An,#d |
link with a 32-bit displacement; and the 68000's link written with its size, as the 68020's manual, GNU as and vasm write it, which EASy68K refuses, so an earlier program is told it is the 68020's and offered link without the size |
tst, cmpi, cmp |
tst.w a0, tst.l #5, tst.b label(pc), cmpi.w #1,label(pc) |
the 68000's, of an address register (a word or a long), an immediate and the program counter |
trapcc |
trapeq, trapne.w #n, trapgt.l #n, the sixteen conditions with hs and lo |
vector 7 when the condition is true, the stacked program counter past the operand, which only the handler reads (ConditionalTrap); with no size an operand is a word |
muls.l, mulu.l |
<ea>,Dl and <ea>,Dh:Dl |
32 bits by 32, into the low 32 with V when bits are lost, or into all 64; N and Z of what is kept; into Dh:Dh the high half wins |
divs.l, divu.l, divsl.l, divul.l |
<ea>,Dq, <ea>,Dr:Dq (64 by 32), divsl.l <ea>,Dr:Dq (32 by 32) |
the quotient into Dq and the remainder, of the dividend's sign, into Dr; a quotient past 32 bits sets V and leaves the registers; 0 is vector 5 |
pack, unpk |
pack d0,d1,#adj, unpk -(a0),-(a1),#adj |
two digits of a word plus the adjustment into a byte, or a byte's two digits spread into a word plus the adjustment; in memory pack reads the word below Ax, which moves by two even for A7, and unpk writes one below Ay; no flag changes |
chk2, cmp2 |
chk2.b bounds,a0, cmp2.w (a0),d1 |
the register against the lower and the upper bound at the operand: a data register at the size, an address register whole against the bounds sign extended; signed when the lower bound is not above the upper, and otherwise the unsigned range that wraps round. Z says it is on a bound, C outside; chk2 traps through vector 6 there (Chk2OutOfBounds) |
cas, cas2 |
cas.w d0,d1,(a0), cas2.l d0:d1,d2:d3,(a0):(d4) |
compare, then swap when equal or load the compare registers when not, both operands of cas2 or neither; one register for both compare values keeps the first operand |
| Bit fields | bfextu d0{4:8},d1, bfins d1,(a0){d2:d3}, bfffo (a0){0:32},d0 |
a field of a data register, from bit 31 down modulo 32 and wrapping round, or of memory, from the byte the operand names plus the offset over eight, any distance either way, one to five bytes read and written; N and Z of the field, or of the value bfins inserts; bfffo answers the offset as written plus how far in its first set bit is |
- Syntax. Write a register pair as
d1:d2andcas2's two addresses as(a0):(d1), using an address or data register for each. A bit field follows its operand as{offset:width}. Each part is a number, with or without#, or a data register. A literal offset is 0 to 31 and a literal width is 1 to 32 (docs/grammar.md2.5). A data register holds an offset of any size and a width modulo 32. casandcas2read and write in one indivisible step. s68k has one processor and no bus to lock.- Cycles. Each instruction takes the manual's cache-case time (below, "The 68020's cycles"). For bit fields in a 68000 program under
opt bit, s68k uses EASy68K's timing: the 68020 cache case for the field plus the 68000 effective-address time, with more for a field spanning five bytes. No 68000 or 68010 has these instructions, so that timing belongs to no processor. A program containing one reports an estimated count withcyclesExactfalse, although its other instructions retain their exact timings. - Verification.
- GNU
as -m68020writes the same words for all 550 lines of 68020 forms, includingextb.landlink.w, in the opt-in check (S68K_BINUTILS_PREFIX=… cargo test --release gnu_as -- --ignored). - The differential harness runs every first word available on the 68020 but not the 68010 against Musashi's 68EC020, with 64 random cases each. It starts from 68020 supervisor-model states and compares exceptions and frames (
cargo test --release --features musashi the_68020s_instructions -- --ignored). All 70,612 cases agree. The list insrc/test/differential.rsexcludes the supervisor-model gaps (below, "The 68020's supervisor model") and cases where Musashi differs from the 68020. Musashi sign-extendscas2.w's compare value through an address register, readspackbytes in the opposite order, and compares achk2address register at operand size and its bounds as signed only. It also misplaces a bit field with an offset within eight of −2³¹, takes abffforegister offset modulo 32, keeps the second operand in a shared compare register, and leaves its own undefined flags. - Musashi and the decoder agree on which of the 65,536 first words are 68020 instructions, except for
callm,rtm,illegaland the line F words that a 68020 without a coprocessor takes as line F. - Seventeen of Musashi's self-checking 68040 programs run and pass as 68020 programs (
tests/musashi/mc68040): bit fields,cas,chk2,cmp2, long multiplies and divides,trapcc,rtd,jmpandshifts3. Their checks of the 68040's undefined flags after division are relaxed, as are checks ofchk2andcmp2that depend on Musashi's interpretation. Each relaxation has a reason (src/conformance/skips.rs).
- GNU
opt p=68020 gives a program the supervisor model of the 68EC020, the 68020 with the 68000's 24-bit bus (M68020UM, sections 1, 2.3, 6 and 7), with no coprocessor and no cache:
-
The status register contains T1, T0, S, M, the interrupt mask and condition codes. Thus
move #$FFFF,srreads back$F71F; a 68000 or 68010 reads$A71F. T1 corresponds to the 68000's T and traces every instruction. With T1 clear, T0 traces instructions that change program flow: a taken branch,braandbsralways,jmp,jsr,rts,rtr,rtdandrte. It also traces writes to the status register:moveto SR andandi,oriandeorito SR or CCR, as in WinUAE's 68020 based on cputester. An instruction that raises an exception is not traced by T0 because taking the exception clears T0, andstopstops. T1 tracesstop, which then does not stop. The trace frame is format$2and includes the traced instruction's address. -
Three stack pointers. With S clear, A7 is the user stack pointer. With S set, A7 is the interrupt stack pointer (ISP) if M is clear, or the master stack pointer (MSP) if M is set. ISP is the 68000's SSP. A program starts with ISP at
$01000000and M clear; one that never sets M runs as on a 68010. A write to SR, an exception orrtecan swap the pointers. Each retains its own stack top for the memory view (getStackTop()). -
An interrupt in master state pushes a format
$0frame on MSP, clears M and pushes a format$1throwaway frame on ISP. The latter contains the same program counter and vector, with S set in the interrupted status register, as in Musashi and WinUAE. The handler runs on ISP. Itsrtepops the throwaway frame; that frame's status register has S and M set, making A7 the MSP again.rtethen continues to the frame there. -
movecaccessesmsp,isp,cacrandcaarin addition to the 68010's four registers, using codes$803,$804,$002and$802. A stack pointer is A7 when it is the active pointer. CACR retains E and F, bits 0 and 1. C and CE, bits 3 and 2, are cache-clear commands and read as 0. s68k has no cache, so code written by a program always runs as written. CAAR retains all 32 bits. The four codes are illegal instructions on a 68010, and the names are reserved in every program. An earlier program that names one is told it is a 68020 control register. -
Frames follow M68020UM 6.5. Format
$0is eight bytes and is used for interrupts,trap #n, illegal instructions, line A and F, privilege violations and format errors. Format$2is twelve bytes, adding the instruction address after the format word, and is used forchk,chk2,trapcc,trapv, division by zero and trace.Bus and address errors use the long bus fault frame, format
$B, of 92 bytes. A bus error fetching an instruction at an instruction boundary, before any of it ran, instead uses the 32-byte short frame$A. An odd program counter's address error uses$B, as in WinUAE's 68020. Like the 68010's$8frame, these frames are simplified. The program counter identifies the instruction; the special status word at+$0Aand data-cycle fault address at+$10are real. The status word contains DF for a data access, RW for a read, SIZ and the function code; a fetch is a word read in program space. Every internal word is zero, including$B's version at+$36. -
rtepops formats$0,$2,$Aand$B. The last two return to the faulting instruction, which restarts, provided$B's version is 0. For$1,rtepops the frame and continues to the frame on the stack named by its status register. Any other format, including the 68010's$8, causes a format error that stacks therteand leaves flags unchanged, as in WinUAE's 68020. -
Unaligned data. Words and longs at odd addresses can be read and written through every memory path: operands of any mode, stack and frames,
movem, memory-indirect Operand pointers, memory-map checks, code writes and watched ranges, including accesses wrapping past$FFFFFF. Only an instruction fetch, jump or return to an odd address causes an address error. The processor is checked only after an odd address is found, so an even access does not need a processor check. -
Line F. Without a coprocessor, line F uses vector 11 and a format
$0frame stacking the instruction. Every word from$F000to$FFFF, including FPU and coprocessor words, decodes as a one-word line F instruction, except EASy68K'ssimhalt,$FFFF $FFFF. -
System registers. For a 68020 program,
getSystem()addsisp,msp,cacrandcaar;sspis ISP under its 68000 name.setIsp,setMsp,setCacrandsetCaarpoke these registers and throwInvalidArgumentin an earlier program. History'sWriteStackPointerscarries{usp, ssp, msp}(mspis 0 before the 68020) anda7, identifying which pointer A7 becomes. The mutations remain in order when anrtethrough a throwaway frame swaps twice.WriteControlRegisterrecordscacrandcaar. -
Verification. The hand tests cover every format, T1 and T0, MSP and ISP and undo across them,
movec,rte's checks and odd accesses on every path (src/test/m68020_supervisor.rs). The differential harness runs Musashi's 68EC020, which models the 68020's frames, its three stack pointers and M, from states with T1, T0, S and M random and a master stack of their own (src/test/differential.rs):cargo test --release --features musashi the_68020s -- --ignored --nocaptureOn 2026-10-29, the results were:
- For 68010 instructions on the 68020, two cases per first word: 96,980 agree, including exceptions, frames, tracing and odd accesses.
- For the 68020's own instructions, 64 cases per first word: 70,612 agree.
- For interrupts: 20,000 agree, including 10,007 in master state with throwaway frames.
- For
rteon frames both implementations pop: 20,000 agree, including 6,678 through a throwaway frame.
RELAXATIONS_SUPERVISORlists excluded cases with a reason for each, in addition to the exclusions for the 68010 and 68020 instructions themselves. Musashi has no 68020 address error, so jumps and returns to odd addresses are not compared. It forgets pending trace when an instruction takes an exception. Under T0, it tracesnop,movec,moves,moveto USP,stop,casandcas2as a 68040 does, but does not traceandi,orioreorito CCR. Of the SR writes, it does not tracemove Dn,sr.Musashi also runs line F words as FPU and coprocessor instructions, raises a format error on
$Aand$Band stacks the address afterrtefor that error, and retains CACR's C and CE bits. Flags that the 68020 leaves undefined afterchk,chk2and long division are also excluded from the status registers stacked in frames; s68k sets them as WinUAE's 68020 does.
A 68020 program uses an estimated count based on the cache case in the M68020 User's Manual timing tables: section 8 of the 1995 edition or section 9 of the 1984 edition, which have the same values (src/machine/timing.rs). This assumes the instruction is in the cache and does not overlap its neighbours. The manual gives a best, cache and worst case for each row and says exact times cannot be determined from the tables: they depend on the instruction cache, prefetch and overlap. The cache case is the deterministic middle case, also used by Musashi's 68020. program.getInfo().cyclesExact, or program.hasExactCycles() in TypeScript, is false for a 68020 program so a host can show the count as an estimate.
-
Calculation. As the manual's notes specify, the count combines operation time with the operand's fetch, calculate, immediate or jump effective-address time. Instructions with their own extension word, including
movem,chk2,muls.land bit fields, add its time.movehas its own table: two cycles plus the source fetch and destination time, reduced after a memory source because the write overlaps the read. A scaled brief extension uses thed8(An,Xn)row. Full-extension rows depend on displacement widths and whether memory is read; base or index suppression, index size and scale do not change the time. Operands are assumed aligned and there are no wait states. -
Data-dependent times.
Bcc.stakes 4 cycles, or 6 when taken;Bcc.w,Bcc.landbratake 6.DBcctakes 6, or 10 when its counter runs out. A memory bit field spanning five bytes costs more than one spanning four.castakes 12 andcas222, each with 3 more when writing.rtetakes 21, 43 for a short bus fault frame, 92 for a long one and 16 more through a throwaway frame.A shift or rotate takes the same time for any count.
mulu.wtakes 27,divu.w44,divs.w56,mulu.l43,divu.l78 anddivs.l90 regardless of operands.movemtakes 8 plus 4 per register from memory, or 4 plus 3 per register into memory. -
Exceptions replace the instruction's time with the manual's exception time: 20 for
trap #n, illegal instructions, privilege violations and line A and F; 25 for a takentrapccortrapv; and 25 after the instruction for trace. An IRQ takes 26, or 41 in master state with its throwaway frame. A bus or address error takes 43 or 79 for a short or long bus fault frame.stoptakes 8 andreset518;trap #15tasks take no time, as on the 68000. -
Manual gaps. s68k makes these choices in
machine::timing'sm68020:chk,chk2and division by zero taketrapv's 25 plus their source effective address, just as the 68000 uses its trap time plus the address;bkpttakes its 10-cycle breakpoint plus the illegal instruction's 20; a format error takesrte's 21 plus an exception's 20. A bus or address error takes its frame time alone because the manual gives no time for work before the fault. Memorynbcdtakes Musashi's 6 plus fetch.Where the manual is inconsistent or omits a row, a full extension with a word displacement uses
(d16,B)as in Musashi, rather than the lower(d16,An,Xn)times for the same word.-(An)is absent from the calculate-immediate table and uses(An)+as in the calculate table.([d16,B],I,d32)is absent from the fetch-immediate table and uses([d16,B],I,d16), as every other outer long uses its word equivalent. -
Verification. Unit tests check every cell of the manual's MOVE table, the effective address tables through
tst,cmpi,lea,jmpandmovem, rows of every other table and the exceptions, and programs that run them (src/machine/timing.rs,src/test/cycles.rs). Musashi's 68EC020 keeps the cache case too, one number per opcode and a table per mode, and the differential harness reports how the two compare rather than asserting it:cargo test --release --features musashi the_68020s_cycles -- --ignored --nocaptureOn 2026-10-29, 92,080 of 134,646 cases agree: 76,833 of 96,980 cases of 68010 instructions on the 68020 (two per first word), 6,481 of 17,703 of the 68020's own (sixteen each), and 8,766 of 19,963 addressing-mode cases in
lea,move,add,clrandjmp.Where they differ, Musashi departs from the manual in these ways:
- It adds fetch time where the manual adds calculate or jump time:
lea,pea,jmp,jsr,clr,Scc,tas,movefrom SR,movem,moves,casand bit fields. - It omits the immediate for
addiand related instructions to a register, and the extension word ofmuls.l,divu.l,chk2andcmp2. - It adds both effective addresses for memory-to-memory
move, where the manual overlaps them. - It takes one cycle per rotate bit, 10 for
bra, 8 formove sr,Dn, 4 per register formoveminto memory, 12 forcas2and 84 for every long division. - It takes 20 for a taken
trapccortrapvand 20 forbkpt, where the manual has 25 and 30. It uses its 68000 times of 40, 38 and 34 for out-of-boundschk, division by zero and privilege violation.
- It adds fetch time where the manual adds calculate or jump time:
opt p=68010 gives a program the whole 68010 of the 68000 User's Manual (its sections 6 and 9 and appendix A) and the Programmer's Reference Manual:
-
Instructions.
move ccr,<ea>lets user mode read condition codes.rtd #dreturns and adds the displacement to the stack pointer.bkpt #ntakes the illegal instruction exception, as a 68010 does when no debugger answers its breakpoint cycle. Privilegedmovectransfers between a general register andsfc,dfc,usporvbr; any other control register causes an illegal instruction.movesis also privileged.s68k has one address space, so
movesaccesses the same memory asmove, as a supervisor data access regardless of SFC and DFC. Each is three bits, writable and readable withmovec.sfc,dfcandvbrare reserved in every program, as isusp. -
move sr,<ea>is privileged, the one change visible to a user-mode program.clrandmove srno longer read before writing. -
VBR. Every exception, including IRQs, reads its vector at VBR plus four times the vector number. VBR is 0 until
movecchanges it. -
Frames. Every exception except the two in group 0 pushes an eight-byte format
$0frame: status register, program counter, and format/vector-offset word containing four times the vector. Bus and address errors push a 29-word format$8frame; its three reserved words are not written. It contains the status register, faulting instruction's program counter,$8and the vector offset, special status word (IF, DF, BY, R/W and function code), fault address, three buffers and sixteen internal words. The buffers and internal words are zero, including version 0. -
rtereads the format word first. It pops eight bytes for$0and 58 for$8, then returns to the stacked program counter. The faulting instruction runs again because s68k retains no internal state to continue it. Any other format or a version other than 0 causes format error vector 14. The frame stays in place and therteaddress is stacked. For an unsupported format, N is set to its high bit and Z and V are cleared, as on a 68010. -
Cycles follow section 9 of the manual and Moira where the manual gives a maximum or differs (
src/machine/timing.rs).mulutakes 40,muls40 or 42 depending on the source,divu78 plus two per step without a carry, anddivs118 or 120; overflow takes 8 and 16 respectively. An exception takes 38, an IRQ 46,chk42 or 44, division by zero 42,trapv40,bkpt42 andrte24. An address or bus error takes 134 from the access, after the 68010's own lead.Bcc.stakes 6 when not taken and 10 when taken;DBcctakes 10, or 16 when its counter runs out. -
Loop mode. With T clear, a
DBccwith displacement −4 enters loop mode when it branches back to an eligible one-word instruction. Subsequent iterations fetch nothing:move.w (a0)+,(a1)+takes 8 anddbra6, instead of 12 and 10. Loop mode ends when the counter runs out or the condition is true, at the time the instruction gives it, on any exception including an IRQ, or on a write to either loop instruction by the program, a trap task or a Poke. After a write, the words are decoded again and the loop runs outside loop mode untilDBccenters it again. Undo restores the mode. Loop mode changes cycles only.
Program::to_srecord(), or program.toSRecord() in TypeScript, writes a .S68 file in the format produced by EASy68K's assembler. EASy68K's simulator can load and run it (src/assembler/srecord.rs, after EASy68K's OBJECT.CPP):
- the header
S0record,68KPROG 20CREATED BY EASY68K, which is what tells EASy68K's loader the file is its own; - the code and the data, every byte the program writes and nothing else, in
S1records when a record's first address fits 16 bits andS2when it fits 24, up to 32 bytes each; - one more
S0record for each range of the memory map, as EASy68K writes them,ROM 008000,008FFF; - the
S8record of the entry point.
Each record ends with CR LF, as EASy68K writes them on Windows. EASy68K breaks its data records where the next item it assembles would not fit, and these break every 32 bytes; both load the same bytes at the same addresses.
| Directive | What it does |
|---|---|
org |
sets the address the following lines are laid out at; the default origin is $1000 |
equ |
names a value, once |
set |
names a value that may be set again; each use sees the latest definition above it |
dc |
puts values or a string in memory, .b, .w or .l |
dcb |
puts a value in memory a given number of times |
ds |
reserves room and writes nothing to it |
end |
ends the program and, with an operand, sets the entry point |
reg |
names a movem register list, AllRegs reg d0-d7/a0-a6, for movem.l AllRegs,-(sp) |
fail |
reports the rest of the line as an error of the program's own; the assembly carries on |
simhalt |
assembles to $FFFF $FFFF, EASy68K's halt, and pauses the run there; the next run or step resumes at the following instruction |
section |
switches between the sixteen location counters, 0 to 15, each going on from where it was left |
offset |
opens a region that produces no bytes, where ds names the fields of a structure by their offsets; org * ends it |
include |
assembles another file of the project here, as if its lines had been pasted at this line |
incbin |
puts another file's bytes in memory here, as a dc.b of the whole file would |
memory |
declares a range of EASy68K's memory map, memory rom $8000,$8FFF: rom, read, protected or invalid, each kind once; the program carries it, and the interpreter enforces it (above, "The memory map") |
opt |
opt p=68000, p=68010 or p=68020 chooses the processor the program is written for, and opt bit the 68020's bit-field instructions, once and before the first instruction (above, "Processor dialects"); EASy68K's listing options cre, mex, sex, war and cex, and each with no, are accepted and ignored, and any other word is a warning |
list, nolist, page |
accepted and ignored; they control a listing file, which s68k does not produce |
Without end, the entry point is the label START, or the first instruction if there is no START label.
memory reads addresses as EASy68K does. Forward references are not allowed, and each address is masked to the 24-bit address bus: $FF001000 becomes $001000. The map has one range of each kind. A second memory rom replaces the first with a warning. A range ending before it starts covers nothing and also produces a warning.
equ, set and reg require a label. A section without a number also requires one and sets it to the current section number. page, memory and conditional directives take no label. Define a reg list before the movem that reads it; the list cannot appear in an expression.
A project maps root-relative paths to file text or bytes and specifies the path of the entry file to assemble. The assembler reads other files only when the entry file reaches them through include or incbin. It never opens files on disk.
S68k.assemble({
files: {'main.x68': source, 'lib/io.x68': library, 'data/sprite.bin': bytes},
entry: 'main.x68'
})include is textual: the included lines are assembled at the include line, in the same section and at the same address. They share the symbol namespace, and local label scopes cross the file boundary. A file name may be unquoted or enclosed in either kind of quote. The assembler looks beside the including file first, then at the project root. A file may be included more than once. end may appear only in the entry file.
incbin accepts either kind of file: binary files contribute their bytes, and text files contribute their Windows-1252 bytes. A label on the directive names the first byte.
Each location names its file, so diagnostics, breakpoints ({file, line}), the current line and call-stack frames identify a project file. A diagnostic in an included file carries the include lines through which it was reached as related locations. Each assembled instruction carries them too, in includeChain, innermost first. If a file is included twice, each line has one location but two addresses; the chain distinguishes the copies.
Characters use one byte in Windows-1252, EASy68K's code page. It replaces the Latin-1 control characters at $80 to $9F with € ‚ ƒ „ … † ‡ ˆ ‰ Š ‹ Œ Ž ‘ ’ “ ” • – — ˜ ™ š › œ ž Ÿ. The assembler stores dc.b 'café €' using those bytes and rejects a character with no corresponding byte (character_above_latin1). The interpreter uses the same table for encoding and decoding at run time.
TRAP #15 stops the interpreter with an Interrupt and waits for an answer. The interpreter defines each task; the host displays text and passes on typed input:
| Task | The interrupt carries, or the answer is |
|---|---|
| 0, 1 | the text: the D1.W characters at (A1), at most 255, stopping at a NUL |
| 13, 14 | the text: the NUL terminated string at (A1) |
| 3 | D1.L as a signed decimal number: -5 |
| 6 | the character in D1.B |
| 15 | D1.L unsigned in the base in D2.B, upper case: FF |
| 17 | the string at (A1), then D1.L as in task 3, as one text |
| 20 | D1.L in a field of D2.B columns, a signed byte: -5 for 6, -5 for -6 |
| 2 | answered with the line typed: its first 79 characters go to (A1) with a NUL, and their count to D1.L |
| 4, 18 | answered with the line typed, read into D1.L by atoi: 12abc is 12, abc and an empty line are 0 |
| 5 | answered with the key typed, into D1.B; Enter is $0D, whether the host sends '\r' or '\n' |
A line ends at its first line terminator. A typed character that Windows-1252 cannot represent is stored as ?. atoi reads leading whitespace, one sign and digits up to the first non-digit. Numbers too long for 32 bits wrap, so every number from -2147483648 to 4294967295 lands in D1.L exactly.
Task 12 turns input echo off when D1.B = 0 and on for any other value. Task 16 turns the input prompt (EASy68K's flashing cursor) off and on with D1.B = 0 and 1. Values 2 and 3 turn off and on the line feed echoed after the carriage return when a key read receives Enter.
These tasks raise no interrupt. The settings belong to the interpreter and are available through getInputSettings() as {echo, prompt, line_feed}. All start on, as in EASy68K. Changes are journaled like registers with a SetInputSettings mutation, so undo restores them. While a read task waits, the host reads the settings and displays input accordingly. Even with echo off, Enter ends a line read on a new line, as in EASy68K.
Task 30 clears the cycle counter. Task 31 reads it into D1.L, returning 0 once it exceeds 32 bits, as in EASy68K (above, "Cycles"). Neither task raises an interrupt or takes time. Undo restores the counter.
The host's file system performs file operations. Each file task raises an interrupt with decoded arguments, and the host answers with the result. The interpreter writes EASy68K's result to D0.W: 0 for success, 1 for end of file, 2 for an error and 3 for read only.
A path is a NUL-terminated string of at most 255 characters, decoded from Windows-1252. Backslashes (\) are sent as / because Windows accepts both separators. The host maps the path to its own files.
| Task | The interrupt carries | The answer, and what is written |
|---|---|---|
| 50 | CloseAllFiles |
true when every file closed: 0, else 2 |
| 51 | OpenFile(path): open an existing file for reading and writing, or for reading only when it cannot be written |
{handle, read_only} or null: D1.L is the file number and D0.W 0, or 3 for reading only; null is -1 in D1.L and 2 |
| 52 | NewFile(path): open for reading and writing, creating the file or emptying it |
the file number or null, as for 51 |
| 53 | ReadFile {handle, count}: at most D2.L bytes from the file's position |
the bytes or null: some bytes go to (A1), their count to D2.L and 0 to D0.W, a short read included; none is the end of the file, 1, with D2.L left as it was; null is 2 |
| 54 | WriteFile {handle, bytes}: the D2.L bytes at (A1) |
true when all were written: 0, else 2 |
| 55 | PositionFile {handle, offset}: D2.L bytes from the start |
true: 0, else 2 |
| 56 | CloseFile(handle) |
true: 0, else 2 |
| 57 | DeleteFile(path) |
true: 0, else 2 |
| 58 | FileDialog {mode, title, filter, path}: D1.L 0 opens and 1 saves; the title at (A1) and the filter at (A2) are empty when their register is 0; the path at (A3) is where the dialog starts |
the path chosen or null for a cancel: a path goes to (A3), at most 255 characters and NULs to 256 bytes, with 1 in D1.L; a cancel is 0 in D1.L; D0.W is 0, or 2 when the 256 bytes do not fit |
| 59 | FileExists(path) |
"Writable", "ReadOnly" or "Missing": 0, 3 or 2 |
File numbers run from 0 to 7; the lowest free number is used, as in EASy68K. The host opens at most eight files and answers null for a ninth. The interpreter handles checks EASy68K makes before touching a file, returning 2 in D0.W without an interrupt: a file number outside 0 to 7 for tasks 53 to 56, a zero-byte read or write, a buffer past the end of memory, or a negative position. Opening a read-only file returns 3; writing to it fails with 2, as EASy68K's fwrite does.
Read and write bytes cross the WebAssembly boundary as a Uint8Array (serde bytes copied in one operation by serde_wasm_bindgen). The interpreter journals bytes written to memory by a read, so undo restores them.
The interpreter does not play sound itself. It raises interrupts with the arguments: PlaySound(path) (70), LoadSound {path, index} (71), PlayLoadedSound(index) (72), and their DirectX forms PlaySoundDirectX, LoadSoundDirectX and PlayLoadedSoundDirectX (73 to 75). Tasks 76 and 77 use ControlSound {index, control} and ControlSoundDirectX. The index is D1.B and control is D2.L: 0 plays once, 1 loops, 2 stops the sound and 3 stops every sound.
A host with a player answers with a SoundOutcome describing what it did. The interpreter writes D0.W as EASy68K does; task 71 has no result. A host without a player answers Terminate.
| Outcome | It means | 70, 72 | 73 to 77 |
|---|---|---|---|
"Done" |
the task did what it asked: a sound started, a load loaded, a stop stopped | 1 | 1 |
"Busy" |
the standard player was still playing an earlier sound; the DirectX player mixes, so it is never busy | 0 | 0 |
"Missing" |
no file at the path, or no sound in the slot | D0 left as it was | 0 |
"Unplayable" |
a file that is there but cannot be played | 0 | 0 |
An error with a 68000 exception goes through its vector (above, "Exceptions"). It ends the program only if the vector has no handler. In that case the status is TerminatedWithException, the error is thrown, and getTermination() returns the cause and vector.
Trap tasks can also raise these errors:
UnsupportedTrapTask {task}for a number that is not an EASy68K task goes through vector 47, as in EASy68K. Tasks a browser page cannot perform faithfully (10, 21, 22, 25, 32 with 0 to 3 or 7 inD1.B, 40 to 43, and 100 to 107) instead end the program regardless of vector 47.InvalidTrapArgument {task, reason}ends the program when a task receives an invalid value. The reason names the register.
Undoing the failed step returns the program to it in the running state.
getTermination() returns null while the program runs. After it ends, it reports TerminateTask for task 9, EndOfProgram {address} when execution reaches $FFFF $FFFF the program did not place (above), TerminatedByHost when the host answers an interrupt with Terminate, or Halted {cause, vector} for a double fault.
It reports Exception {cause, vector} for an error that ends the program. The cause can be Irq {level} when an IRQ's vector has no handler. The vector is present for an unhandled CPU exception or IRQ; it is absent for an error the program cannot handle.
An interrupt accepts an answer of the same type with a value valid for its task. Terminate answers any task and ends the program. Other answers are rejected with a typed error and the interrupt remains waiting. Errors include NoPendingInterrupt; InvalidAnswer {interrupt, reason} for the wrong answer type, a value that is not an answer, a key state of the other form, too many bytes for a read, or a file number above 7; and OutOfBounds for a write that does not fit in memory. WebAssembly methods throw RuntimeError objects and do not panic, so a bad call leaves the interpreter usable.
Where s68k departs from EASy68K, on purpose:
- For task 15, a base outside 2 to 36 stops the program with
InvalidTrapArgument. The same error stops it for task 16 with D1.B outside 0 to 3, or task 58 with D1.L other than 0 or 1. EASy68K does nothing for these values, and task 58 reports success. - A task s68k does not carry out stops the program with
UnsupportedTrapTask; EASy68K carries it out. - For tasks 0 and 1, s68k displays up to 255 characters when D1.W is
$8000or more, as it does for any D1.W above 255. EASy68K reads such a value as a negative index into its buffer. atoioverflow wraps modulo 2^32. EASy68K's ownatoi(Borland's runtime) was not available to check.- s68k drops characters typed after the 79th character of a line. EASy68K ends the line at the 80th key and keeps the next key for the following read.
- A read of no bytes (task 53 with D2.L = 0) reports 2. After an earlier read reaches the end of the file, EASy68K's
freadinstead reports 1 using C's end-of-file indicator; s68k does not keep that indicator. - A count past the end of memory reports 2 even when (A1) + D2.L passes 4 GB. EASy68K's 32-bit check wraps around in that case and reads past its memory. Task 58 checks all 256 bytes it writes; EASy68K checks only the name.
- s68k sends paths with
/in place of\. - On Windows, EASy68K cannot delete an open file and reports 2. In s68k, the host file system determines whether an open file can be deleted.
- Cycle counts assume an immediately responding bus without wait states. The 68020 count estimates the manual's cache case, with aligned operands and no instruction cache, prefetch or overlap between neighbouring instructions (above, "The 68020's cycles").
- A step retains ten bytes of the instruction it ran, the 68000's maximum. If a longer 68020 instruction is decoded from memory written by the program or reached in its data, the step omits
ran; an instruction placed by the assembler is reported. Retaining 22 bytes would cost space in every step that keeps a history. - On the 68010 and 68020,
rterestarts bus and address errors at the instruction's beginning instead of continuing from internal processor state, which s68k writes as zeros. The 68020's choice of short or long bus fault frame follows an s68k rule rather than the pipeline. - The 68020 has no instruction cache, so CACR's E bit has no effect, and it has no coprocessor. SFC and DFC do not select an address space.
- Loop mode changes cycles only. An IRQ can still be taken between the looped instruction and its
DBcc, whereas a 68010 takes it after theDBcc. - Vectored and spurious interrupts, the reset exception and the 68000's HALT pin are omitted, as in EASy68K. Nothing reads the vectors at
$0and$4, andresetdoes not run a reset sequence. - The host runs task 32's timers. The interpreter keeps their settings and takes requests raised by the host. EASy68K's hardware window, IRQ buttons and devices are not present.
Install Rust, clone the repository,
and run cargo run from its root. This assembles and runs code-to-run.asm.
To run another file, pass its path: cargo run -- my-program.asm.
The command line handles text tasks in the terminal, honouring task 12's echo setting, and file tasks on disk. Paths are relative to the directory of the file being run. Task 51 opens a file read-only if it cannot write it. Task 58 asks for a path in the terminal; an empty line cancels the dialog.
Graphics, mouse and sound tasks are reported and end the run. The last line reports why the program ended. The command line raises no interrupt requests, so a program that executes stop ends the run there, waiting.
Install wasm-pack, then run
npm run build-wasm in the ts-lib directory. This creates the compiled
package in ts-lib/src/pkg.