208 lines
18 KiB
Swift
208 lines
18 KiB
Swift
// 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
|
||
}
|
||
}
|