Zilog Z80 · microcomputer.world

This is the executable guide to Dromaios's instruction-level Z80. It owns the complete model: stored state, both register banks, all 698 documented instruction forms, prefix decoding, reset, execution, IRQ/NMI entry, and the public interface. The build generates its TypeScript implementation from the cpu fences below.

CPU tests · Public type checks · Coverage

Historical background

The Z80 grew out of Zilog, founded by Federico Faggin and Ralph Ungermann after leaving Intel in 1974. Masatoshi Shima joined the development in 1975. Their oral history at the Computer History Museum describes a design that retained 8080 machine-code compatibility while adding index registers, a second register set, more word operations, and a richer interrupt system. The processor reached the market in 1976.

Compatibility made existing software useful, but the Z80 was a distinct processor. Even familiar byte instructions need their own flag rules. The formal definitions below expose those differences rather than treating the Z80 as an 8080 with a few extra opcode handlers.

The programmer's machine

The model has an eight-bit data path and a sixteen-bit memory address space. Bytes range from $00 to $FF; addresses range from $0000 to $FFFF. As in the other specifications, $ introduces hexadecimal and an opcode pattern lists bits from most to least significant. Instruction operands and memory words put the low byte first.

Processor architecture: registers, operations, and their connections. — Architecture diagram · drawn with Sauvignon. Select to enlarge.

B:C, D:E, and H:L are word views of stored bytes. H=$12, L=$34 means HL=$1234; there is no second value to synchronize. An operand written (HL) means the memory byte at that address. It is not another register. IX and IY are separately stored words. Their indexed byte operations add a signed displacement, wrapping the resulting address to sixteen bits.

The alternate bank contains A′, B′, C′, D′, E′, H′, L′, and flags F′. EX AF,AF′ exchanges A and its flags; EXX exchanges BC, DE, and HL. Ordinary instructions still name the main bank. These exchanges do not select a persistent bank number: they swap the stored values. A program must manage which values belong to which context.

Register	Role
A	Accumulator and ordinary byte ALU destination
B, C, D, E, H, L	Byte operands or halves of BC, DE, HL
IX, IY	Index pointers
PC, SP	Next instruction address and RAM stack pointer
I	High byte used in interrupt mode 2 vector addressing
R	Refresh register; the decoder advances its low seven bits on M1 fetches
IFF1, IFF2	Interrupt enable state
IM	Interrupt mode 0, 1, or 2

Flags distinguish parity from overflow

F holds six modeled flags: S (sign), Z (zero), H (half carry), P/V (parity or overflow), N (subtraction), and C (carry or borrow). P/V describes signed overflow for arithmetic and even bit parity for logical operations. Unlike the 8080, subtraction reports half borrow, and AND always sets H. These are instruction effects, not properties continuously recomputed from A: loading A with zero leaves the old Z unchanged.

Operation	Result	P/V	C	Why
`$7F + $01`	`$80`	1	0	Signed overflow without unsigned carry
`$FF + $01`	`$00`	0	1	Unsigned carry without signed overflow
`$80 - $01`	`$7F`	1	0	Signed overflow without unsigned borrow
`$03 XOR $00`	`$03`	1	0	Two set bits give even parity

The model omits undocumented F bits 5 and 3. Packing emits zero in those positions and unpacking ignores them; that is a modeling limit, not a claim that the silicon holds them at zero.

Physical operation and the model boundary

Zilog's CPU manual describes M1 opcode fetches, refresh, memory and I/O transfers, and interrupt acknowledgement as distinct bus activities. The original design uses an eight-bit data bus, sixteen-bit address bus, a single clock input and a +5 V supply. WAIT and bus-request signals let the surrounding system delay transfers or take control of the buses.

Dromaios models instruction effects, not clock phases or electrical pins. R advances on modeled opcode fetches; operand and displacement reads do not all advance it. Refresh itself performs no recorded RAM access. Neither access counts nor R alone measure elapsed cycles. The execution contract below defines prefix fetching, reset, retirement, and explicit external interrupt entry.

Stored state

Each bank owns its own flags object. Architectural names are uppercase; stored JavaScript fields are lowercase unless explicitly mapped. ALTERNATE.B means B in the named bank, while plain B refers to the main bank. PC and SP are independent words. The two deferral latches and STOPPED describe instruction boundary behavior; they are not additional programmer-visible registers.

cpu "z80"
state {
  register A: 8
  register B: 8
  register C: 8
  register D: 8
  register E: 8
  register H: 8
  register L: 8
  flag S
  flag Z
  flag H
  flag PV
  flag N
  flag C
  bank ALTERNATE = alternate {
    register A: 8
    register B: 8
    register C: 8
    register D: 8
    register E: 8
    register H: 8
    register L: 8
    flag S
    flag Z
    flag H
    flag PV
    flag N
    flag C
  }
  register IX: 16
  register IY: 16
  register PC: 16
  register SP: 16
  register I: 8
  register R: 8
  latch IFF1
  latch IFF2
  choice IM: 0, 1, 2
  latch IRQDEFERRED = interruptDeferred
  latch NMIDEFERRED = nmiDeferred
  latch STOPPED = halted
}

CpuZ80State requires every stored field. The machine language uses uppercase register and flag names, with PV for the manual's P/V flag. Public TypeScript uses the stored names declared above. The main H register and H flag are separate fields, as are their alternate counterparts. BC/DE/HL are derived readonly views in each snapshot, never separately initialized state. There is no public raw F or AF view; the internal packed view serves stack operations.

Construction and inspection

Memory uses the byte-connection contract, with RAM as the usual connection.

new CpuZ80(ram, initialState, ports?, onReti?) requires a 64 KiB byte-memory address space and explicit state. It copies declared fields from both banks and both flag objects, then validates byte and word ranges, Boolean flags and latches, and integer IM in 0–2. Invalid numeric fields throw RangeError; invalid Boolean fields throw TypeError. Construction performs no reset, execution, or RAM/device accesses. The optional BytePorts connection supplies readPort(port) and writePort(port, value) callbacks. Port addresses are full 16-bit numbers and transferred values are bytes. The device owns its state; restoring a CPU snapshot does not restore or reconnect the device. onReti, when supplied, is called after a documented RETI retires. It is an architectural notification, independent of port transfers, and adds no entry to the memory/port log. RETN does not call it.

Each declared input property is read once; copying does not depend on property enumerability. Extra metadata and derived views are ignored, so a snapshot can also be used as initialization data. Caller objects, including initially shared bank or flag objects, do not remain connected to internal state.

snapshot() returns detached main and alternate banks, flags, register views, and control state without accessing RAM. Public types are recursively readonly. Objects are ordinary JavaScript values, not frozen objects: even if a caller bypasses readonly typing and edits one, it cannot alter CPU state or another snapshot. The CPU keeps mutable private state and retains no record history.

Instruction steps

step() attempts one instruction, or one block iteration, and returns CpuZ80StepRecord:

before and after: independent complete snapshots.
instruction: its starting address and the bytes actually fetched, in order; null only when already halted on entry.
accesses: ordered CpuZ80Access entries. Memory read/write entries carry address and value; port input/output entries carry port and value. Both kinds share one log in their actual transfer order. CpuZ80MemoryAccess remains the memory-only type alias.
outcome: executed, halted, or unsupported. Only unsupported carries reason: "opcode".

Supported instructions advance PC while fetching bytes, wrapping at 16 bits. Word operands, including immediate pair loads and absolute addresses, are fetched low byte first. NOP changes PC/R and consumes existing inhibition under the retirement rules. Stores record the write even when the value is unchanged, and never read the destination to reconstruct an old value. Captured instruction bytes survive stores that overwrite code. Subsequent steps fetch current RAM.

Each supported instruction increments the low seven bits of R for each opcode fetch, preserving bit 7: once for an unprefixed instruction and twice for every supported prefixed form. In DD/FD CB d op, only the first two bytes are M1 opcode fetches; neither the displacement nor the final opcode increments R. Operand reads and data accesses do not increment R. For example, unprefixed 7F becomes 00, while prefixed FF becomes 81. PC and R are advanced only after the complete supported encoding has been identified. LD A,R observes this increment; LD R,A then replaces all eight bits with A.

An unsupported opcode is read and recorded, but PC, R, all other CPU state, and RAM remain unchanged. This atomic rejection is a model policy, including the choice to leave R unchanged despite the recorded reads. CB, ED, DD, and FD fetch a second byte, wrapping at FFFF. An unsupported entry retains both reads without fetching operands. DD/FD CB additionally fetch displacement and final opcode before rejecting an unsupported entry, retaining all four reads. SLL, index half-register operations, indexed-CB register destinations, repeated prefixes, ignored-prefix encodings, and undocumented ED aliases are unsupported. Repeating an unsupported attempt reads current RAM again and preserves all state.

HALT advances PC past its opcode, increments R once, sets halted, and reports outcome: "halted" with the HALT instruction. Subsequent halted steps report instruction: null, no accesses, and unchanged state, including R.

Physical HALT continues bus and refresh activity. Those cycles, clock timing, and dummy accesses remain outside this instruction-level model. Interrupts are explicitly offered between steps; step() does not poll devices. There is no synthetic lesson-completion instruction or state; caller completion belongs to the runner.

Reset and execution

Reset sets PC, I, R, and IM to zero, disables both interrupt flip-flops, clears both deferral latches, and releases HALT. It preserves both register banks, IX, IY, SP, and RAM. Reset records detached before/after snapshots and an empty access list: it neither reads a vector nor fabricates a power-on state. CpuZ80ResetRecord has no instruction or step outcome. Repeated reset has the same defined effects and produces fresh records. Preserving registers whose reset values the manual leaves unspecified is a deterministic model policy, not a claim about physical power-on values. An example's fresh factory instead restores its initial CPU, program, and RAM.

view NEXT "next instruction address": 16 {
  current = register PC
  return current
}
action setPC "write the next instruction address" (word: 16) {
  PC <- word
}
action reset "apply the reset boundary" () {
  PC <- u16(0)
  I <- u8(0)
  R <- u8(0)
  IFF1 <- 0
  IFF2 <- 0
  IM <- 0
  NMIDEFERRED <- 0
  IRQDEFERRED <- 0
  STOPPED <- 0
}

The complete opcode encoding is read and validated before PC or R changes. An unsupported prefix combination records the bytes read but preserves stored state. A halted step performs no access or retirement. For a supported opcode, PC first advances past the encoding, then R advances once for each opcode fetch. Only R's low seven bits count; bit 7 retains its stored value. Ordinary opcodes count once, CB/ED/DD/FD opcodes twice, and DD CB d op / FD CB d op also count twice: their displacement and final opcode are ordinary reads.

Operands are then read through the live PC, advancing it after each successful read. All addresses wrap to sixteen bits; words read low byte first. An access failure retains earlier effects, including committed PC/R, but does not retire the instruction. Each step executes one instruction or one repeating block iteration and records ordered memory and port accesses.

action refresh "advance the low seven refresh bits" (count: 8) {
  original = register R
  R <- or(and(original, u8($80)), and(add(original, count), u8($7F)))
}
action afterRetirement "consume NMI inhibition" () {
  NMIDEFERRED <- 0
}

A successful instruction consumes previous IRQ inhibition. A defer irq request from EI or an IFF-changing return replaces it with a new one-instruction inhibition; every successful instruction also clears NMI inhibition. RETI requests device notification, delivered only after these retirement effects. A failing notification callback leaves the completed return intact.

Step, reset, and interrupt entry share a reentrancy guard, including during memory, port, acknowledgement, and RETI callbacks. Snapshot inspection remains available to callbacks. The entry contract selects NMI and IM 0/1/2 delivery explicitly, using the same decoder and retirement boundary for mode 0.

Pair and status views

Reading a pair captures its high byte and then its low byte. Snapshots derive both banks' pair values from their detached stored-state copies. The views do not fetch memory or change registers.

view BC "B:C register pair": 16 {
  high = register B
  low = register C
  return concat(high, low)
}
view DE "D:E register pair": 16 {
  high = register D
  low = register E
  return concat(high, low)
}
view HL "H:L register pair": 16 {
  high = register H
  low = register L
  return concat(high, low)
}
view BC_ALT "alternate B:C register pair": 16 {
  high = register ALTERNATE.B
  low = register ALTERNATE.C
  return concat(high, low)
}
view DE_ALT "alternate D:E register pair": 16 {
  high = register ALTERNATE.D
  low = register ALTERNATE.E
  return concat(high, low)
}
view HL_ALT "alternate H:L register pair": 16 {
  high = register ALTERNATE.H
  low = register ALTERNATE.L
  return concat(high, low)
}

F packs S Z 0 H 0 PV N C, reading the six flags in that order. PUSH AF captures A before this view; POP AF writes A before replacing the flags object. The status action below supplies that replacement to the existing stack body. All six new flag values are computed before the old object is replaced.

view F "packed documented flags": 8 {
  sign = flag S
  zero = flag Z
  half = flag H
  parity = flag PV
  subtract = flag N
  carry = flag C
  return pack<8>(sign, zero, 0, half, 0, parity, subtract, carry)
}
policy FFLAGS "restore all documented flags" (status: 8) {
  S = bit(status, 7)
  Z = bit(status, 6)
  H = bit(status, 4)
  PV = bit(status, 2)
  N = bit(status, 1)
  C = bit(status, 0)
}
action writeF "replace packed F" (status: 8) {
  replace FFLAGS(status)
}

Writing register pairs

A pair write replaces its high byte before its low byte. These actions also serve the prefixed word definitions. Reading a pair always captures both bytes before any split write, even when source and destination alias.

action writeBC "write B:C" (word: 16) {
  B <- highByte(word)
  C <- lowByte(word)
}
action writeDE "write D:E" (word: 16) {
  D <- highByte(word)
  E <- lowByte(word)
}
action writeHL "write H:L" (word: 16) {
  H <- highByte(word)
  L <- lowByte(word)
}

Byte operands and transfers

In 01 ddd sss, ddd selects the destination and sss the source. Both fields use the same catalogue: B/C/D/E/H/L/(HL)/A. The (HL),(HL) slot is HALT, not a memory-to-memory load. 00 ddd 110 loads a following immediate byte. Reading (HL) resolves H then L before the memory read. Writing it resolves H then L after capturing the source, without reading destination memory.

source immediateByte "immediate byte": 8 {
  byte = fetch
  return byte
}
operands bytes {
  000 "B" = register B
  001 "C" = register C
  010 "D" = register D
  011 "E" = register E
  100 "H" = register H
  101 "L" = register L
  110 "(HL)" = memory HL
  111 "A" = register A
}

Capture the source completely before writing the destination. Register self-copies still read and write; immediate loads fetch before resolving a memory destination. Preserve all flags, the alternate bank, and control state. A failed source read prevents writeback.

family LD "01 ddd sss" for d in bytes, s in bytes named "LD {d},{s}" except "01 110 110" {
  result = operand s
  operand d <- result
}
family LDImmediate "00 ddd 110" for d in bytes named "LD {d},n" {
  result = fetch
  operand d <- result
}

Accumulator arithmetic and logic

The shared encodings are 10 ooo sss for a register or (HL) and 11 ooo 110 for an immediate byte. ooo selects the operation below. Each body captures the operand, then incoming C if needed, then A. Selecting A as the source deliberately reads it twice. Results wrap to eight bits. All six flags update before A; CP performs the subtraction without writing A. Indexed memory bodies reuse these actions after their specification-defined address decoding.

ooo	Operation	P/V	H	N	C
000	ADD	Signed overflow	Half carry	0	Carry
001	ADC	Signed overflow	Half carry including C	0	Carry including C
010	SUB	Signed overflow	Half borrow	1	Borrow
011	SBC	Signed overflow	Half borrow including C	1	Borrow including C
100	AND	Even parity	1	0	0
101	XOR	Even parity	0	0	0
110	OR	Even parity	0	0	0
111	CP	Signed overflow	Half borrow	1	Borrow

S and Z describe the result. The remaining flag values are explicit policy arguments so the arithmetic and logical distinctions stay visible at each use. Policy expressions read only captured values; incoming flags are never reread after updates begin. Flags update in S/Z/H/PV/N/C order without replacing the flag object, preserving access and failure behavior of the existing model.

policy ALU "Z80 byte result flags" (result: 8, half: flag, parity: flag, subtract: flag, carry: flag) {
  S = negative(result)
  Z = zero(result)
  H = half
  PV = parity
  N = subtract
  C = carry
}