Group 0 — core system (bits 7:0 of lirq)

PENDING $FE20 · POLARITY $FE24 · EDGE $FE28 · MASK $FE2C

Group 1 — peripherals (bits 15:8)

PENDING $FE21 · POLARITY $FE25 · EDGE $FE29 · MASK $FE2D

Group 2 — IEC bus + module IRQ pins (bits 23:16)

PENDING $FE22 · POLARITY $FE26 · EDGE $FE2A · MASK $FE2E

Group 3 — FIFO events: WiFi / keyboard / MIDI / WizNet (bits 31:24)

PENDING $FE23 · POLARITY $FE27 · EDGE $FE2B · MASK $FE2F

Controller behavior (applies to all four groups)

• Reset defaults: POLARITY = $00 (falling edge), EDGE = $FF (edge mode), MASK = $FF (all masked), PENDING = $00. These reset only on FPGA reset — a soft reboot preserves them, so mask bits a driver unmasked (e.g. wizfi’s group-3 bits) survive into the next OS boot.
• PENDING latches unconditionally: pending <= pending | irq_event — the mask gates only the CPU IRQ output (Interrupt[n] = pending[n] & ~mask[n]), never the latch.
• PENDING is write-1-to-clear; reads are side-effect-free. MASK is a plain read/write register.
• OS cold start: the Level 2 kernel writes $FF to all four MASK and PENDING registers, masking and clearing every group before driver initialization.

Definitions and board wiring

The current definitions include DMA, SD insertion and group 2/3 sources. An equate does not imply a connected peripheral: the board wrappers tie off unused VICKY inputs and MIDI-VS RX. K2-only keyboard and Ethernet inputs do not become Jr2 hardware.

Where this comes from

RC24: IRQ_Controller_Jr.v, the K2/Jr2 IO_Page0 device wrappers, OpticalKeyboardScanner.v, F256K2_MIDI_Interface.v, defs/wildbits.d, Level 2 krn.asm and the K2 typematic-overlay driver. Register decoding and board connections were reviewed together.

System RAM — who owns what at run time

Memory sizing starts with the boot map. The Longview krnp2 expands the block table to 256 entries, checks FLASHDIS.OK, and sets FLASHDIS when supported. The pool has 252 blocks (2,016 KB); only $FC–$FF are marked NotRAM. With FLASHDIS clear, $40–$9F are also excluded, leaving 156 blocks (1,248 KB). mfree reports what remains after allocations, not the full pool. Longview needs its matching kernel, disk and FEU.

The boot chain, block by block

1. Power-on → Booter (flash $7D–$7F, the top 24 KB of the addressable flash window — the three booter_*.bin pieces fnxmgr installs).
2. Booter → FEU OS-9: loads the mini system from /f0 (flash $78–$7C, the five f0_*.bin pieces, 40K). FEU = “First Executable Unit” — a Level 1-style OS-9 system with boot modules in flash and working data in RAM.
3. FEU startup → bootos9 /s0/OS9Boot: the FEU’s startup script chains to the real system — bootos9 reads the SD card’s OS9Boot into RAM blocks (8−n)…7 through the block-1 copy window.
4. Trampoline: stub at $0600, MMU identity map, jump to kernel — full OS-9 running from SD-loaded RAM. The FEU’s flash blocks return to being just the /f0 drive.

Flash at reset · FLASHDIS clear

Expansion window · FLASHDIS clear

One external-bus decode, with board-dependent attached hardware: on the K2 this is the 256 KB expansion region (physical $10_0000–$13_FFFF). On the Jr2 the same select reaches the cartridge port: /c0 is based at block $80 and /c1 at $90 (cartridge flash identification must use the actual cartridge chip; it is not necessarily the onboard flash type). This region shares the external bus — and its single write strobe — with the flash chip and the RTC, which is why the v8_rc6 core’s strobe policy covers all three.

Sectored device pages ($FC–$FF)

These are VICKY-internal pages, not RAM — mapping one into a slot windows the device, and the MMU entry pattern 1111 11xx routes there instead of to memory.

Longview system RAM

2,016 KB of SRAM in one run (K2 and Jr2): with FLASHDIS set, LUT entries $00–$FB select SRAM at $00_0000–$1F_7FFF. The former $C0–$CF device gap and $F0–$FB undecoded blocks are now RAM. Devices occupy only $FC–$FF. Every RAM block follows block × $2000 + offset; the 16-bit SRAM chip’s word-address pins carry the byte address divided by two. The kernel excludes the four device pages from its 256-entry allocation map. Fixed CPU register and vector overlays remain unchanged.

FLASHDIS — the flash window as RAM: MMU_IO_CTRL ($FFA1) bit 2

768 KB more RAM (K2 and Jr2). The SRAM is 2 MB, but the flash chip and the expansion connector sat in front of its middle third: LUT entries $40–$7F selected the flash and $80–$9F the expansion, so chip bytes $08_0000–$13_FFFF were never reachable. One bit swaps them out.

The register is readable; names as in defs/wildbits.d (equates FLASHDIS = %00000100, FLASHDIS.OK = %10000000).

What the kernel does at boot (Longview krnp2, both machines, before anything is forked):

How the split works

The CPU’s 64K space is divided into eight 8K slots, each translated through an MMU look-up entry. A single inhibit term overrides that translation for the top pages:

MMU machinery

Slot-entry encoding (physical target select)

Selected fixed I/O groups

Where this comes from

Decode logic traced in the shipping cores (both machines share these files):
• TyVKy2K2turbo_MMU_FNX6809.v — page decodes ($FDxx / $FExx / refined $FF00–$FF9F + $FFB0–$FFEF / $FFFx) and the $FFAx MMU-register select.
• TyVKy2K2x1_MMU_Register.v — RAM_Access_Inhibit (the master “not subject to the MMU” term), slot-entry target encoding, and the two $FFA1 enable bits.
• defs/wildbits.d — register names, device addresses, and the constant-RAM retention note.
One caveat: all fixed decodes are qualified by !Dbg_Mode_i — when the hardware debugger owns the bus, these carve-outs are bypassed.

How the engine works

Sprites are line-buffered, not framebuffered. The display runs 640×480 with every 320×240 pixel doubled, so the engine only needs each sprite line once per pair of scanlines. On every odd scanline, during horizontal blanking, the master video scheduler enters its sprite phase (DoSpriteHere), hands VRAM channel 3 to the sprite state machine, and fires it.

The sprite state machine then walks all 128 attribute records, from sprite 127 down to sprite 0. For each record it checks two things in two clocks: the per-sprite enable bit, and a line hit — whether the upcoming pixel row falls inside the sprite’s vertical span. Disabled records take the probe/next path; enabled records also perform the line-hit check. Rendering throughput depends on the number and width of sprites hitting that row. On a hit, the engine multiplies the row-within-sprite by the sprite’s line width, adds the pixel base address, and streams that one line of pixels (8–32 bytes, fetched 16 bits at a time) from video RAM into the sprite line buffer at horizontal position X. Because sprite 0 is written last, it wins overlaps.

During the following even scanline, the compositor reads the line buffer back at pixel rate and merges it with text, bitmap, and tiles according to the master control register. A non-zero pixel index is looked up in the sprite’s selected CLUT; index 0 lets the layers behind show through.

The scan pipeline, per line pair

Register map

Master control — $FFC0 (fixed I/O, visible in every map)

Text + overlay + graphics + sprites = $27. Add bitmap for $2F.

Sprite attribute block — VICKY page $FC, offsets $1300–$16FF

The 128 attribute records live in a dual-port BRAM inside I/O page $FC (the same page as the bitmap/gamma registers). Map the page into a CPU slot to reach it — e.g. write $FC to MMU_SLOT_2 ($FFAA) and the block appears at $4000–$5FFF. Each sprite owns 8 bytes:

The RTL rotates the page index (RecodedAddy) so that page $13 lands on BRAM rows 0–31 — the table above is the net effect; sprite 0 really is the first 8 bytes of $1300.

The 8-byte attribute record

Multi-byte fields are big-endian (high byte first, 6809-friendly), so a single 16-bit STD at the high offset stores X or Y correctly in one instruction:

Worth knowing if you are reading other documentation: pre-rework cores and the official 65C02 material describe these fields as little-endian. The 6809 rework changed it, confirmed on the hardware, and the NitrOS-9 equates were corrected to match on 2026-08-31.

The pixel-data address is a physical address in system RAM (block × $2000 + offset, for every SRAM block through $FB), pixels stored row-major, one byte per pixel, rows packed at the sprite’s width. Keep depth = 00 (8 bpp).

Graphics CLUTs — VICKY page $FD, offsets $1000–$1FFF

Sprites pick one of four CLUTs with CTRL bits 2:1. The CLUTs share page $FD with the font (font at $0000–$0FFF, CLUTs above it). Each CLUT is 256 entries × 4 bytes, ordered B, G, R, A. All four read back (the CPU port of a true dual-port RAM) and hold zeros at power-up: the shell’s colors come from the text color LUTs below, so nothing loads these until a bitmap viewer or a sprite program does.

Text color LUTs — VICKY page $FC, offsets $1700 (foreground) and $1740 (background)

Text and the banner font take their colors from two 16-entry tables in page $FC, the sprite-record page: foreground at $1700–$173F, background at $1740–$177F, 4 bytes per entry ordered B, G, R, A, indexed by the two nibbles of the character’s attribute byte. The core loads both with the OS-9 palette when the bitstream comes up, so they survive a reset; a power cycle restores them. The CPU reads them back (each table has a shadow copy written on the same strobe), so a program can save the tables it is about to change and put them back on exit. lutrd on the kit disks dumps both, plus the graphics CLUTs and the gamma tables.

Line-draw accelerator — VICKY page $FC, offsets $1080–$1087 (wildbits.d: TyVKY_LD_*)

A Bresenham line engine sits at the top of the bitmap register block (TyVKY_BM0_CTRL_REG is $F000 with page $FC in slot 7, so these are $F080–$F087). Write the two end points and a color, raise the go bit, and the engine walks the line at 100 Mhz, queueing line writes into an 8,192-entry × 34-bit FIFO (34 KB of queue data; 36 KB of allocated block RAM) that the memory manager drains into the chosen bitmap. It writes one byte per pixel at bitmap start + y×320 + x in the 320-wide 8-bit modes; in HIRES4 (GFX_HIRES4) X runs to 639 (TyVKY_LD_XMAX4) and the low nibble of the color is the dot. Pixels reach SRAM only while VKY_DRAWLINE_REG ($FFCA) bit 0 is set.

• Accepted range: X0 and X1 below 320 (640 in HIRES4), Y0 and Y1 below 240 (TyVKY_LD_XMAX8, TyVKY_LD_XMAX4, TyVKY_LD_YMAX) — a go with any end point outside is ignored (the engine stays idle, done never rises).
• Handshake: asserting the go bit while idle starts the line and the engine parks in its done state until the go bit is written back to 0; drop it before the next line. Done (bit 7 on read) says the walk has finished; the FIFO count at $1082/$1083 says how many entries are still queued. Wait for the queue to drain before treating the bitmap as complete. In HIRES4, shallow lines can combine two adjacent pixels into one entry; unpaired pixels preserve the other nibble.
• Read-back quirks: X0 cannot be read (its two bytes return the FIFO count), and the X1 and Y read order is the reverse of the write order — both are in TinyVicky_BM_Registers.v’s read multiplexer. Bit 7 on read is TyVKY_LD_DONE.
• Target address: bits 3:2 pick which bitmap layer’s start address ($1001–$1003 / $1009–$100B / $1011–$1013) the pixel addresses are built on; the layer does not have to be displayed.
• Cost: the line FIFO uses 8 × RAMB36 (288 Kbit physical), with 8,192 × 34 bits (272 Kbit) of queue data. The sprite engine has a separate 512 × 18-bit line buffer; it does not use this FIFO.

Sources: TinyVicky_BM_Registers.v (LINE_DRAWING_REG, the write decode on address bit 7, the read multiplexer), LineDraw.v (X0_Ok/Y0_Ok limits, the IDLE/RUN/DONE machine, Addy_Addyx_Offset), TinyVickyCoreModule.v (the LINEDRAWING_Reg64 wiring), TinyVKY2K2_IO_Page0_Devices.v (CS_VICKY_BITMAP: page $FC, offsets $1000–$10FF; absolute $1F_9000–$1F_90FF; the Jr2 decode is identical).

640 × 240 × 16-color bitmap mode — GFX MODE $FFCB

The bitmap engine’s native picture is 320 × 240 with one byte per dot, each dot shown twice across. HIRES4 keeps every byte where it is and reads it as two dots of four bits, the high nibble on the left, so a 320-byte row becomes 640 dots and the frame stays 76,800 bytes: same RAM, same fetch bandwidth, same raster, nothing for an old monitor to notice. Two ways to switch it on, OR’d together:

Colors. A dot’s CLUT entry is group × 16 + nibble, in the CLUT the plane’s LUT bits select; the sixteen entries of the slice are the whole palette of that plane. Nibble 0 is transparent, as byte 0 is in the 320 mode, so it shows the layer behind or VICKY’s background color ($FFCD–$FFCF). Transparency is per 640 dot: the two halves of one byte can show through to different things.

What it does not change. Sprites, tiles and text are not part of it. They fetch and draw exactly as before, at 320 dots doubled, and are composited with the 640-wide bitmap dots in the usual layer order ($FFC2/$FFC3): a sprite or tile dot always covers a pair of bitmap dots, and its X position is still a 320-column unit, so it cannot sit on an odd 640 column. Each plane decides for itself, so a 640-wide picture and a 320-wide one can share the frame. The dot order inside a pair is fixed by the design (a blanking-aligned phase, not a sampled clock), so it is the same on every build.

On the Jr2 the mode costs a second CLUT copy and a second color line in block RAM (see the block-RAM budget below); both cores carry it.

Coordinates

Sprite positions live in a space offset 32 pixels beyond the visible screen on the top and left, so sprites can slide off any edge. The visible 320×240 area spans sprite coordinates (32,32) to (351,271):

Upper-right corner for an N-wide sprite: X = 32 + 320 − N, Y = 32. For 8×8: X = 344 ($0158), Y = 32 ($0020).

Minimum recipe — a green 8×8 sprite at screen center

1. Prepare pixel data (no masking needed) — fill a 64-byte buffer in RAM you own with $01 (pixel index 1) and compute its physical address: block# × $2000 + offset. The buffer must outlive the sprite — a process’s pages are recycled at exit, so stay resident or use memory you keep.
2. Enter the masked window — save CC first, then orcc #IntMasks. Everything touching $FFA0, the slot registers, or the mapped window sits inside one masked stretch.
3. MLUT setup — read $FFA0, save it, write it back with bits [5:4] (EDIT map) copied from bits [1:0] (ACTIVE map) — otherwise slot writes edit somebody else’s map. Save slot 5 ($FFAD, window at $A000) and write $FD into it.
4. Palette (page $FD) — LUT0 entry 1 at window+$1004: write $00, $FF, $00, $00 (B, G, R, A) — pure green.
5. Sprite record (page $FC) — write $FC to $FFAD; sprite 0’s record is at window+$1300, eight bytes, big-endian fields:

   Offset	Value	Meaning
   +0	$61	enable + 8×8 (size 11) + LUT0 + depth 0
   +1..+3	addr hi, mid, lo	physical address of the pixel buffer
   +4, +5	$00, $BC	X = 188  (center: 32 + (320−8)/2)
   +6, +7	$00, $94	Y = 148  (center: 32 + (240−8)/2)

   If the other 127 records can’t be trusted (power-on garbage can carry stray enable bits), zero $1300–$16FF first.
6. Leave the window — restore $FFAD, restore $FFA0, then restore the saved CC (including the original interrupt masks).
7. Enable the layer — $FFC0 is fixed I/O: no mapping, no masking, any map, any time. Read it, OR in $26 (graphics $04 + overlay $02 + sprite $20, preserving the text bit), write it back. The green square appears at center.

To hide the sprite later: clear bit 5 of $FFC0 (no mapping needed), or clear the record’s enable bit (needs the mapped window again). The complete working implementation of this recipe is the sprtest command source: level1/wildbits/cmds/sprtest.asm.

Where this comes from

RTL and definitions read for this reference:
• Sprite_State_Machine.v — the per-line-pair scan, line-hit test and VRAM fetch.
• TinyVickyCoreModule.v — master video scheduler and compositor.
• TinyVKY2K2_IO_Page0_Devices.v — attribute BRAM, page rotation (RecodedAddy), CLUTs.
• defs/wildbits.d — register names and addresses.