Files
VCCPlusOSS/platforms/macos/App/AssemblyReferenceInstructions.swift

208 lines
18 KiB
Swift
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// SPDX-License-Identifier: GPL-3.0-or-later
import Foundation
extension AssemblyReference {
static func instructions() -> [AssemblyReferenceEntry] {
var entries: [AssemblyReferenceEntry] = []
let same = "CC is preserved."
let nz = "N reflects the sign bit. Z marks a zero result."
let logic = nz + " V clears. C is preserved."
let add = nz + " V marks signed overflow. C marks unsigned carry."
let sub = nz + " V marks signed overflow. C marks a borrow."
func instruction(_ name: String, _ hd: Bool, _ form: AssemblyOperandForm, _ operation: String,
_ flags: String, _ pages: String, aliases: [String] = [], detail: String = "",
links: [String] = [], example: String? = nil) {
let citation = "Atkinson (2009), pp. " + pages
var citations = [citation]
if name == "TFM" { citations.append("VCC Plus, Native Debugger, HD6309 Step") }
if !hd { citations.append("Motorola (1981), Appendix A, " + name.trimmingCharacters(in: .decimalDigits)) }
citations.append("Astle, LWTools 4.25, ch. 3")
var related = links
switch form {
case .value, .memory, .indexed, .maskMemory: related.append("Indexed")
case .relative: related.append("Relative")
case .immediate: related.append("Immediate")
case .bit: related.append("Direct")
default: break
}
if !related.contains("Condition codes") { related.append("Condition codes") }
entries.append(.init(name, .instructions, only6309: hd, aliases: aliases, form: form,
operation: operation, flags: flags, detail: detail, links: related,
citations: citations, example: example))
}
// Available registers differ across both instruction families and processors.
for (op, portable, extra) in [
("LD","A B D X Y U S","E F W Q"), ("ST","A B D X Y U S","E F W Q"),
("ADD","A B D","E F W"), ("ADC","A B","D"), ("SUB","A B D","E F W"), ("SBC","A B","D"),
("CMP","A B D X Y U S","E F W"), ("AND","A B","D"), ("OR","A B","D"),
("EOR","A B","D"), ("BIT","A B","D")
] {
let base = portable.components(separatedBy: " ")
for reg in base + extra.components(separatedBy: " ") {
let byte = ["A","B","E","F"].contains(reg)
let operation: String, flags: String, pages: String
var detail = "", lesson: String?
switch op {
case "LD":
operation = "Copy the operand into \(reg). Use # for a literal or read \(byte ? "one byte" : reg == "Q" ? "four bytes" : "two bytes") from the addressed memory."
flags = logic; pages = byte ? "90" : reg == "Q" ? "94" : "91"
if reg == "A" {
detail = "LDA #$20 places $20 in A. LDA $0400 reads the byte at $0400. LDA ,X+ reads at X, then advances X by one. The remaining CC bits keep their values. Immediate LDA takes 2 cycles. Extended LDA takes 5 on MC6809 or HD6309 emulation mode and 4 in HD6309 native mode. Indexed timing depends on the postbyte."
lesson = "cell"
} else if reg == "W" {
detail = "LDW #$1234 encodes as 10 86 12 34. E becomes $12 and F becomes $34 in either HD6309 execution mode."
lesson = "word"
}
case "ST":
operation = "Copy \(reg) to the destination address. Multi-byte stores write the high byte first."
flags = logic; pages = byte ? "127" : reg == "Q" ? "130" : "128"
if reg == "A" { lesson = "cell" }
case "ADD", "ADC":
operation = "Add the operand" + (op == "ADC" ? " and incoming carry" : "") + " to \(reg). Keep the low \(byte ? 8 : 16) bits in \(reg)."
flags = add + (byte ? " H records carry from bit 3." : " H is preserved.")
pages = op == "ADC" ? (byte ? "5" : "6") : (byte ? "8" : "9")
case "SUB", "SBC", "CMP":
operation = "Subtract the operand" + (op == "SBC" ? " and incoming borrow" : "") + " from \(reg). " + (op == "CMP" ? "Keep \(reg) intact for a later branch." : "Write the difference to \(reg).")
flags = sub + (byte ? " H is undefined." : "")
pages = op == "CMP" ? (byte ? "50" : "51") : op == "SBC" ? (byte ? "122" : "123") : (byte ? "131" : "132")
if op == "CMP" { lesson = "signed" }
default:
let action = ["AND":"Keep bits set in both inputs.", "OR":"Set bits present in either input.",
"EOR":"Set bits where the inputs differ.", "BIT":"Test the bits of \(reg) selected by the operand."][op]!
operation = action + (op == "BIT" ? " Preserve both inputs." : " Combine \(reg) with the operand and save the result in \(reg).")
flags = logic
pages = ["AND":byte ? "12" : "14", "OR":byte ? "106" : "108",
"EOR":byte ? "62" : "63", "BIT":byte ? "32" : "33"][op]!
}
instruction(op + reg, !base.contains(reg), op == "ST" ? .memory : .value,
operation, flags, pages, detail: detail, links: [reg], example: lesson)
}
}
for (op, extra, operation, flags, pages) in [
("ASL","D","Shift one place left and fill bit 0 with zero.",nz + " C receives the old top bit. V is N XOR C.","16–17"),
("ASR","D","Shift right, preserving the sign bit.",nz + " C receives the old bit 0. V is preserved.","18–19"),
("LSR","D W","Shift right, bringing zero into the top bit.","N clears. Z marks zero. C receives the old bit 0. V is preserved.","98–99"),
("ROL","D W","Shift left, moving the old carry into bit 0.",nz + " C receives the old top bit. V is N XOR C.","116–117"),
("ROR","D W","Shift right, moving the old carry into the top bit.",nz + " C receives the old bit 0. V is preserved.","118–119"),
("CLR","D E F W","Write zero.","Z sets. N, V and C clear.","48–49"),
("COM","D E F W","Invert every bit.",nz + " C sets and V clears.","53–54"),
("NEG","D","Subtract the value from zero.",nz + " C sets for a nonzero input. V marks negation of the most negative value.","102–103"),
("INC","D E F W","Add one.",nz + " V sets on crossing from maximum positive to minimum negative. C is preserved.","67–68"),
("DEC","D E F W","Subtract one.",nz + " V sets on crossing from minimum negative to maximum positive. C is preserved.","57–58"),
("TST","D E F W","Test the value while preserving it.",logic,"140–141")
] {
for reg in ["","A","B"] + extra.components(separatedBy: " ") {
let hd = !["","A","B"].contains(reg)
let destination = reg.isEmpty ? "a memory byte" : "register " + reg
instruction(op + reg, hd, reg.isEmpty ? .memory : .inherent,
"Operate on \(destination). " + operation, flags + (["ASL","ASR"].contains(op) && !hd ? " H is undefined." : ""), pages,
aliases: op == "ASL" ? ["LSL" + reg] : [], example: op == "DEC" ? "count" : nil)
}
}
for (suffix, condition, page, longPage) in [
("CC","C is clear (unsigned higher or equal after a compare)",21,71), ("CS","C is set (unsigned lower)",22,72),
("EQ","Z is set (equal)",24,73), ("NE","Z is clear (unequal)",40,83),
("GE","N equals V (signed greater or equal)",25,74), ("GT","Z is clear and N equals V (signed greater)",26,75),
("LE","Z is set or N differs from V (signed less or equal)",35,78), ("LT","N differs from V (signed less)",38,81),
("HI","C and Z are both clear (unsigned higher)",27,76), ("LS","C or Z is set (unsigned lower or equal)",37,80),
("MI","N is set (negative)",39,82), ("PL","N is clear (nonnegative)",42,84),
("VC","V is clear (no signed overflow)",46,88), ("VS","V is set (signed overflow)",47,89),
("RA","always",43,85), ("RN","never",44,86), ("SR","call",45,87)
] {
for long in [false,true] {
let prefix = long ? "LB" : "B"
let action: String
switch suffix {
case "RA": action = "Continue at the target. A branch to its own label forms a hold loop."
case "RN": action = "Read the displacement and continue at the next instruction."
case "SR": action = "Push the following instruction’s address on S, then continue at the target. RTS returns to the caller."
default: action = "Continue at the target when " + condition + ". Otherwise execute the next instruction."
}
let aliases = suffix == "CC" ? [prefix + "HS"] : suffix == "CS" ? [prefix + "LO"] : []
instruction(prefix + suffix, false, .relative, action, same, String(long ? longPage : page),
aliases: aliases, detail: "The signed \(long ? 16 : 8)-bit displacement is relative to the following instruction.",
example: suffix == "NE" ? "count" : suffix == "SR" ? "call" : "signed")
}
}
for (reg, flag) in [("X",true),("Y",true),("S",false),("U",false)] {
instruction("LEA" + reg, false, .indexed, "Calculate an indexed address and place it in \(reg). Indirect addressing reads a pointer before producing the address.",
flag ? "Only Z changes, to indicate a zero address." : same, "95", links: [reg])
}
for (op, action, flags, page) in [
("ADDR","Add source to destination.",add,10), ("ADCR","Add source and carry to destination.",add,7),
("SUBR","Subtract source from destination.",sub,133), ("SBCR","Subtract source and borrow from destination.",sub,124),
("CMPR","Compare destination minus source, preserving both.",sub,52), ("ANDR","Apply bitwise AND to the destination using the source.",logic,15),
("ORR","Apply bitwise OR to the destination using the source.",logic,109),
("EORR","Toggle destination bits selected by the source.",logic,64)
] {
instruction(op, true, .pair, action, flags, String(page),
detail: "The destination selects the width. A word source supplies its low byte to a byte destination. For a word destination A/B supply D, E/F supply W, CC is zero-extended and DP supplies the high byte. PC is undefined in this family. See Atkinson, p. 143.", links: ["W"])
}
for (op, action, page) in [("AIM","AND",11),("OIM","OR",105),("EIM","exclusive OR",61),("TIM","AND",139)] {
instruction(op, true, .maskMemory, "Combine the literal mask and the addressed byte with \(action). " + (op == "TIM" ? "Use the result only to test flags." : "Write the result to that address."), logic, String(page))
}
for (op, action, page) in [("BAND","AND",20),("BIAND","AND with the inverted source",29),("BOR","OR",41),("BIOR","OR with the inverted source",31),("BEOR","exclusive OR",23),("BIEOR","exclusive OR with the inverted source",30),("LDBT","copy",92),("STBT","store",129)] {
let description = op == "STBT" ? "Copy the selected register bit to the destination bit in direct-page memory." :
"Combine the selected memory bit with the destination register bit using \(action). Only the destination bit changes."
instruction(op, true, .bit, description, "CC can change when a destination bit in CC is selected.", String(page))
}
for (stack, other) in [("S","U"),("U","S")] {
for push in [true,false] {
let prefix = push ? "PSH" : "PUL"
instruction(prefix + stack, false, .stack, push ? "Save selected registers on \(stack). The stack grows toward lower addresses." :
"Restore selected registers from \(stack), advancing the stack pointer. Pulling PC transfers control.",
push ? same : "Pulling CC replaces all its flags.", push ? "110" : "113",
detail: "Select CC, A, B, DP, X, Y, \(other) or PC. LWASM also accepts D for A and B. Hardware determines the register order.", links: [stack], example: "call")
instruction(prefix + stack + "W", true, .inherent, push ? "Push both bytes of W onto \(stack), subtracting two from the pointer." :
"Pull two bytes into W from \(stack), advancing the pointer by two.",
same, String((push ? 111 : 114) + (stack == "S" ? 0 : 1)), links: ["W",stack])
}
}
instruction("TFM", true, .transfer, "Copy W bytes between addresses held in D, X, Y, U or S. Each suffix advances, retreats or holds its pointer after a byte. W counts down to zero. Without interruption the transfer costs 6 cycles plus 3 per byte.", same, "136",
aliases: ["COPY","COPY+","COPY-","TFRP","TFRM","IMP","IMPLODE","TFRS","EXP","EXPAND","TFRR"],
detail: "LWASM’s alternative spellings take two bare registers. COPY/COPY+/TFRP advance both, COPY-/TFRM retreat both, IMP/IMPLODE/TFRS advance the source and EXP/EXPAND/TFRR advance the destination. In VCC Plus, debugger Step finishes the block. Continue can hit a breakpoint again between bytes.",
links: ["HD6309 modes","W"], example: "transfer")
for (name, action, page) in [("EXG","Exchange the contents of the two registers.","65–66"),("TFR","Copy the source register to the destination.","137–138")] {
instruction(name, false, .pair, action, "Writing CC replaces its flags.", page,
detail: "Use equal-width registers on the MC6809. The HD6309 has additional registers and defined mixed-width behavior. Writing PC transfers control.", links: ["D","W"])
}
for (name, operation, flags, page) in [
("ANDCC","Keep only CC bits selected by the mask.","Any CC bit can clear.",13),("ORCC","Set each CC bit selected by the mask.","Any CC bit can set.",107),
("CWAI","AND CC with the mask, stack the full interrupt context on S, then wait for an eligible interrupt.","The mask updates CC. E sets for the stacked full context.",55),
("LDMD","Write the low two mode-control bits of MD.",same,93),
("BITMD","Test the masked trap status bits of MD. Reading a selected sticky error clears it.","Z sets if no selected error was pending.",34)
] {
instruction(name, name.hasSuffix("MD"), .immediate, operation, flags, String(page), links: name.hasSuffix("MD") ? ["HD6309 modes"] : [])
}
for (name, action, page) in [("JMP","Set PC to the effective address.",69),("JSR","Push the return address on S, then set PC to the effective address.",70)] {
instruction(name, false, .memory, action, same, String(page), example: "call")
}
for (name, action, flags, page) in [
("ABX","Add the unsigned byte in B to X.",same,4),
("DAA","Adjust A after adding packed BCD bytes, using H and C from the addition.",nz + " C reports decimal carry. V is undefined.",56),
("MUL","Multiply unsigned A by B and place the 16-bit product in D.","Z marks a zero product. C receives product bit 7.",100),
("NOP","Advance to the following instruction.",same,104),
("RTS","Pull the return address from S into PC and advance S by two.",same,121),
("RTI","Pull CC and the return state from S. Stacked E determines whether to restore a full frame.","Restores saved CC.",120),
("SEX","Copy B’s sign bit across A to extend B into D.",nz + " V and C are preserved.",125),
("SEXW","Copy W’s sign bit across D to extend W into Q.",nz + " V and C are preserved.",126),
("SYNC","Wait for an interrupt request. Even a masked request can release the wait.",same,135)
] {
instruction(name, name == "SEXW", .inherent, action, flags, String(page), example: name == "RTS" ? "call" : nil)
}
for (name, vector) in [("SWI","FFFA"),("SWI2","FFF4"),("SWI3","FFF2")] {
instruction(name, false, .inherent, "Save a full interrupt frame on S and fetch the new PC from $\(vector).",
"E sets." + (name == "SWI" ? " I and F set after stacking." : " I and F keep their values."), "134", links: ["HD6309 modes","RTI"])
}
for (name, dividend, divisor, quotient, remainder, page) in [("DIVD","D","byte","B","A",59),("DIVQ","Q","word","W","D",60)] {
instruction(name, true, .value, "Divide signed \(dividend) by a signed \(divisor). The quotient goes in \(quotient) and the remainder in \(remainder). A zero divisor traps.",
"For an in-range quotient, N and Z describe it, V clears, and C receives its low bit. Signed overflow sets V. Range overflow preserves the dividend and clears N, Z and C.",
String(page), detail: name == "DIVQ" ? "VCC Plus’s retained core has differences in DIVQ overflow and carry handling. Treat these flags as processor documentation." : "", links: ["MD"])
}
instruction("MULD", true, .value, "Multiply signed D by a signed 16-bit operand and store the 32-bit product in Q.",nz + " V and C clear.","101", links: ["Q"])
return entries
}
}