VIXEN-32 Video Interface Hardware — MEGA65 Edition ================================================== The VIH ("GPU") is the FPGA video/audio subsystem of the VIXEN-32 computer as it runs on the MEGA65 R6 (Xilinx Artix-7 XC7A200T). The machine's main CPU is the on-FPGA RISC-V soft core (VexRiscv "Murax", 100 MHz, 512 KBytes RAM based at 0x0); it drives the VIH through a DIRECT fabric control bus decoded at 0x3A000000+ — chosen for C64-style poke-address muscle memory, with nothing but wires behind it. Beside it sits the 8-bit CPU block: a 6502 and a Z80 with 64 KBytes of their own RAM, the VIC-20's VIC and VIAs, the C64's VIC-II, CIAs and PLA, and a YM2151, all run by the RISC-V. The FPGA renders three composited layers (framebuffer, tile map, hardware sprites) plus a programmable border, driven by a 1024-entry copper list, to a 384x224 display — and provides a streaming BLITTER that draws whole Z-buffered, perspective-textured triangles, a VIC-II-style raster interrupt system, SID + 4-voice PCM + YM2151 audio, and pixel-perfect sprite collision. Backing store is the R6's onboard 64 MBytes SDRAM. Everything below reflects core v0.96 (November 2026). Companion documents: docs/chipset/Vixen-32_Chipset_Reference.md (the full manual, every register bit-exact), risc/vih_regs.h (the C API and the authoritative register list), docs/BasicMachine.txt (the BASIC machine and its POKE map), docs/Vixen-32_User_Guide.pdf (the user's manual) and mega65/SDRAM_BRINGUP.md (how the SDRAM was brought up + measured). Platform Summary ---------------- - Host: MEGA65 R6 mainboard. Since core v0.94 the core is VIXEN's own top level -- no MiSTer2MEGA65 framework, no QNICE, no framework menu -- and since v0.95 every part of it is VIXEN's own code, the SD card controller, the SDRAM controller and the SID included. The core is closed, all rights reserved (Leif Arne Søderholm); the notices for VexRiscv (MIT), T80 (the Z80) and ymfm (the YM2151's reference) are in NOTICES.txt. - Video out, simultaneously: * Analog VGA connector: VIXEN's TRUE 15,625 Hz PAL raster with composite sync — 1084S-class CRT monitors are first-class. * HDMI (core v0.94, VIXEN's own): 720x576 at 50.08 Hz, 4:3, with sound, locked to the analog PAL picture (624 lines a frame, every VIXEN line twice, all 384 pixels across the 720). Zoom and scanlines (v0.95): see "HDMI" below. - The HELP key is an ordinary key since v0.94. The kernel's file browser (in KERNEL.BIN) answers it: load programs, mount disk images, open the commander, switch HDMI zoom and scanlines. There is no F12 menu. - Keyboard: the MEGA65's own matrix, read by VIXEN's own reader (v0.94), delivered as native key numbers (no PS/2 emulation) — see "Keyboard". - Joystick: BOTH DB9 ports, read identically (JOYSTICK $3A000180, JOYSTICK2 $3A0001E8). An Amiga mouse on port 1 reads through MOUSE ($3A0001EC) -- quadrature plus buttons. The ports' paddle (pot) pins are never sampled: a paddle drain made an optical mouse unusable, so it stays off. The C64's and the VIC-20's paddles and the 1351 mouse (v0.96) are values the RISC-V writes into the 8-bit CPU block -- c64hw and vic20hw turn the Amiga mouse into them. - SD card: VIXEN's own controller since v0.95 (SPI from the SD spec, the bus at 25 MHz, twice v0.94's 12.5), both slots, SD_CTRL/CMD/STATUS $3A0001F0-$3A0001F8 (vih_sd.h), with FAT16/32 layers on top (vih_fat.h read-only; the kernel's FatFs module write-capable). Claim it, use it, release it. BURST2 (core v0.74): SD_CMD bit 20 returns TWO buffer bytes per clock-domain crossing ({N+1,N} in SD_STATUS[15:0]), 256 crossings per sector instead of ~1024 -- streaming reads run 3-4x faster. The kernel's FatFs reads with it since kernel 147; the bootstrap tier (vih_sd.h) stays classic-only. BOTH SLOTS (core v0.84): the back micro SD slot always wins; the internal (bottom tray) slot is used only when the back slot is empty. Chosen once per reset at the first claim and kept until reset. - RESET BUTTON (core v0.80/v0.81): reloads KERNEL.BIN -- the core keeps a read-only copy of the SD bootstrap and restores it after every reset, so kernel and BASIC come back even after a game took all 512 KBytes. The bootstrap clears both tile maps first: a reset looks like power-on. - LEDs (v0.94): the power LED is green; the keyboard's drive LED is green while the network is on. - TRAPDOOR RAM (core v0.87): 256 KBytes extra on-chip RAM at 0x80000-0xBFFFF, code and data, one extra clock per read (code 66% / data 90% of CPU-RAM speed; 99% for code with the instruction cache). vih_trapdoor_present(). - CPU8 RAM (core v0.95): the 8-bit CPU block's 64 KBytes at 0xC0000-0xCFFFF, straight after Trapdoor RAM and as fast. With no 6502 or Z80 program running it is 64 KBytes more RAM for the RISC-V. - ZORRO RAM (core v0.89): the other 48 MBytes of the SDRAM chip at 0x41000000-0x43FFFFFF, CPU only (blitter, video and audio cannot see it), data and code through the same caches at chip-RAM speed; copy to chip RAM at ~13 MBytes/s (v0.95; ~8 before). vih_zorro_present(). - INSTRUCTION CACHE (core v0.88): VIH_ICACHE $3A0001DC, opt-in, 8 KBytes, caches only code fetched from above the 512 KBytes (Trapdoor RAM, CPU8 RAM, chip RAM, Zorro RAM). vih_cache_invalidate() also empties it -- call it after writing new code there. - FPGA TEMPERATURE (core v0.82): VIH_TEMP $3A0001FC (read), vih_temp_mc(). - Virtual floppy drives A:/B: (core v0.71): 512-byte-sector disk images, registers $3A0002A0/$3A0002B0, buffers at $3A101000/$3A101200 (vih_disk.h). The kernel's file browser mounts .IMG files from the SD card into them. Chipset Reference, chapter 12. - Ethernet (core v0.59..v0.64): 100 Mbit on the RJ45, registers $3A000260-$3A00028C, 2 KBytes packet buffers at $3A100000/$3A100800 (vih_eth.h). The IP stack (ARP/IPv4/UDP/TCP/ICMP/DHCP/DNS + a TFTP server) is the kmodnet kernel module in chip RAM -- SHIFT+POUND at the Ready prompt switches it on, MEGA+POUND switches it on with the TFTP server. Chipset Reference, chapter 11. - No welcome screen: the core boots straight into VIXEN's splash. - THE KERNEL IS NOT IN THE CORE (v0.56 on). The bitstream holds only a small bootstrap that loads /VIXEN-32/KERNEL.BIN off the SD card (the file was BOOT.BIN up to core v0.93); the kernel, EhBASIC and the programs KERNEL.BIN carries (VMOS, the file browser, the commander, the VIC-20 and the C64) live on the card, so changing them is a file copy. There is no fallback -- a missing or bad image gets an error screen and the machine stops. See the Chipset Reference, chapter 10. - EhBASIC RUNS ON THE CORE'S OWN 6502 (kernel 138 on): the 8-bit CPU block at 25 MHz, its 64 KBytes at 0xC0000. The RISC-V answers the 6502's trapped I/O page; the 6502 emulated in C (fake6502) is gone from the kernel. docs/BasicMachine.txt tells how. - Install: vixen32-*.cor on the SD card, hold No Scroll at power-on, flash to a free slot. Dev loop: `m65 -q .bit` over USB-JTAG. - Build: `bash mega65/nom2m_build.sh` (Vivado 2022.2, non-project, on the build server; mega65/nom2m_try.sh retries a build that misses timing with other placements). Sources: rtl/mega65/ (the top level, clocks, HDMI, keyboard, joysticks, audio DAC, SD controller), mega65/ (pins and scripts) and the shared rtl/ core. Display & Timing ---------------- - 384 x 224 active pixels, 8bpp indexed color. - 256 simultaneous colors, each a 16-bit RGB565 value from a 65536-color space. Since core v0.95 EIGHT such palettes: each layer (and each tile cell and sprite) shows one of them and the copper switches them per line -- up to 2,048 colors on screen (see "Palettes"). - Palette fully re-programmable at runtime (per-entry writes or full reload). - PAL, 50.08 Hz refresh. Total raster 500 x 312. H: 384 active + 12 front + 48 sync + 56 back = 500 V: 224 active + 36 front + 3 sync + 49 back = 312 - Video clock 31.25 MHz with a /4 pixel enable -> 7.8125 MHz pixel clock. H freq = 15,625 Hz (PAL exact). - System/render clock clk_sys = 100 MHz (CPU + SDRAM + reader + blitter + SID + PCM domain). The video clock is a SEPARATE asynchronous domain. - The "visible area" is whatever the border leaves exposed. A common default is 320 x 200 (32px side borders, 12px top/bottom); opening all borders gives the full 384 x 224. - HI-RES TEXT (core v0.95): the tile layer can run at 768 dots a line (a dot = half a pixel), 80 columns over the unchanged picture and sprites (see "Tile Map"). - EXACT COORDINATES (core v0.95): framebuffer column x and sprite x both land on screen x, border included. Before v0.95 the picture showed one pixel to the right and the sprites one pixel to the left; a program that set the GFX x scroll to 1 to make up for it now sets it back to 0. HDMI (core v0.94 / v0.95) ------------------------- - 720x576 at 50.08 Hz, sent as VIC 17 (4:3), 27 MHz pixel clock from the same oscillator as the PAL video and locked to it: one HDMI frame per VIXEN frame, 624 lines, ~0.06 ms behind the analog picture. Each VIXEN line is sent twice, all 384 pixels across the 720 (x = hx*8/15), 64 black lines above and below. Sound travels in the HDMI stream. - VIH_HDMI $3A000290 (W, v0.95) -- the user's display setting; only the HDMI output reads it, the 15 kHz analog picture never changes: [0] zoom VIXEN's 224 lines fill all 576 HDMI lines (every 7 become 18) and the frame is sent as 16:9 (VIC 18), so a TV widens it back to within 4% of the normal shape. [1] scanlines the second HDMI line of each VIXEN line at half brightness. Zoomed: soft CRT scanlines -- each VIXEN line drawn as a beam, bright in its middle and darker at its edges. Taken at the start of a frame. 0 after a reset; vih_init_registers() and a .rvk launch leave it alone, so the kernel restores the user's choice from /VIXEN-32/CONFIG.TXT at boot (F1 / F3 in the file browser switch zoom / scanlines and save them). Switching zoom moves the HDMI frame once against the machine (as a reset does), so a TV may blank for a moment; the rate stays 50 Hz. - Hi-res text on HDMI: dots 24-743 of the 768 on its 720, every column whole. Framebuffer (GFX layer) ----------------------- "Amiga bitmap pointer" model: VIH_GFX_PTR holds a 4096-byte block index; gfx_ptr*4096 = the SDRAM byte address the framebuffer is streamed from. The pointer is latched at the start of EVERY frame (core v121), so writing it flips buffers TEAR-FREE — double/triple buffering is just pointer math anywhere in the 16 MBytes chip RAM. For a clean flip write the pointer around beam line ~216, just before the frame-start latch. - 8bpp indexed, one byte per pixel. Row stride 512 bytes = a 512-pixel CIRCULAR line; 384 px visible, the rest is horizontal scroll room. - 256 rows per buffer (224 displayed + 32 off-screen for Y scroll room). - Index 0 is transparent: shows bg_color (the C64 $D021 equivalent), or a behind-sprite / tile beneath. - Column x of a line shows at screen x, border included (core v0.95): with the default border, columns 32-351 are the 320-pixel picture. - Fetched per scanline into a line FIFO (4x48-word SDRAM page bursts). x/y scroll are applied in the fetch (coarse) and pixel pipeline (fine) so the burst structure stays constant. - PER-SCANLINE X SPEEDS (core v125): the fine scroll phase travels with each fetched line, so a copper program that rewrites X_SCROLL mid-frame gives every band its own PIXEL-SMOOTH speed — banded bitmap parallax (tut13's sky/trees) and Out Run-style roads. A band's new value applies from the next fetched line (band edges are exact to about one line). Palettes (8 x 256, core v0.95) ------------------------------ - VIH_PALETTE $3A000154: {palette[26:24], index[23:16], rgb565[15:0]}. One write sets one entry. Palette 0 is the one every older program writes (bits [26:24] = 0) and sees; all eight power up the same (the C64 colors, the grey ramp, black). vih_set_palette8(palette, index, rgb565). - VIH_PAL_SEL $3A000294 (W): which palette each layer is looked up in -- [2:0] the GFX picture (and BG_COLOR) [6:4] the tile layer [10:8] every sprite [14:12] the border A tile cell's own palette (cell bits [30:28]) and a sprite's own (SPRITE_ATTR [24:22]) are ADDED to their layer's, mod 8: with the layer at 0 they pick the palette directly. 0 at power-on and from vih_init_registers(): every layer in palette 0, as before. - The copper writes both (IDs $14 and $16), so the picture can be shown in bands of different palettes -- each band up to 256 colors of its own, e.g. a video whose strips each have their own palette. Border ------ - Programmable width on all four sides, in pixels. Solid color (palette index). bg_color separately fills transparent FB pixels inside the window. - The copper can change border dimensions/color PER SCANLINE (side-border opening, split screens, raster bars, per-line sine "pinch" effects). - Top and bottom are never 0 since core v0.78: a 0 from the CPU or the copper is stored as 1 (one border line keeps fine X scrolling working). Copper ------ - 1024-entry copper list in a synchronous-read BRAM (256 before core v0.72); each entry is {line u16, reg u16, value u32}, sorted by line. - ANY NUMBER of entries may share the same line (core v121): the copper drains every due entry at one entry per 2 clocks (~6400 clocks per scanline), so even the full 1024-entry list could fire on a single line. Border + background color pairs, sprite multiplex bursts, whole register batches per line — all fine. - BUDGET: because every due entry fires, a per-line effect costs one entry per line PER THING it moves. A four-layer starfield setting a sprite X on each of 192 visible lines is 768 entries by itself. Arm no more entries than you wrote: unwritten ones read as zero = {line 0, reg 0, value 0}, and reg 0 is BORDER_DIMS, so an over-long count blanks all four borders. - Entries are poked directly into the copper BRAM (VIH_COPPER_WR_ADDR / _DATA, auto-increment) and armed via VIH_COPPER_CNT. - Register IDs: 0x00 BORDER_DIMS {bottom,top,right,left} bytes *** TOP AND BOTTOM MUST BOTH BE >= 1. See the warning under the register map below. *** 0x01 BORDER_COLOR palette index 0x02 X_SCROLL framebuffer X scroll (0..511, circular) 0x03 BG_COLOR background color for transparent FB pixels 0x04 FONT_MODE [0]=font_src(0=ROM,1=BRAM) [1]=height(0=8x8,1=8x16) 0x05 TILEMAP_PTR [0]=which tile map shows, 0 or 1 (drives tile_bram_sel; overridden once TILEMAP_ROW_PTR has taken ownership -- $0E is the modern form) 0x06 TILE_COLOR_MODE [0]=0:1bpp font, 1:8bpp font 0x07 TILE_BG_TRANS [0]=1: tile bg index 0 is transparent 0x08 TILES_ENABLE [0]=1: tile layer on 0x09 SPRITE_ENABLE value[15:0] = 16-bit channel enable mask 0x0C GFX_ENABLE [0]=GFX layer on/off (0 = bg_color shows) 0x0D AUDIO_ENABLE [0]=master audio mute at the mixer 0x0E TILEMAP_ROW_PTR [6:0]=base row 0..127 into the merged tile BRAM 0x0F SPRITE_MOVE write sprite_inst[ch] POSITION {ch,Y,X} directly 0x10 SPRITE_SLOT write sprite_inst[ch] ATTRS {palette[28:26], flags[25:20], color[19:12], slot[11:4], ch[3:0]} 0x11 GFX_PTR [12:0]=FB block index (per-scanline bitmap split) 0x12 Y_SCROLL [7:0]=framebuffer Y scroll 0x13 TILE_SCROLL {y[24:16], x[8:0]} (wavy/parallax tiles) 0x14 PALETTE {palette[26:24], index[23:16], rgb565[15:0]} (per-line gradients) 0x15 TILE_PRIORITY [0]=tiles above/below GFX 0x16 PAL_SEL each layer's palette, as VIH_PAL_SEL (v0.95) (Sprite channels are written directly — SPRITE_MOVE/SPRITE_SLOT; the legacy descriptor-pool indirection IDs 0x0A/0x0B are not used on this platform.) - Ideas, NOT in the core -- noted so they are not lost; each is new RTL work if ever wanted: BLIT_GO copper-issued blitter ops: the copper pokes the blit registers/GO so drawing races the beam with ZERO CPU cost (Amiga's copper could start blits). The copper must not stall on a busy blitter. (It once had ID 0x16 reserved; PAL_SEL took that ID in v0.95.) 0x17 (reserved) AUDIO_POKE copper-timed audio: per-scanline SID register pokes / PCM triggers (filter sweeps, sample starts locked to the raster, C64 demo-style). Today the only audio register the copper can touch is AUDIO_ENABLE ($0D). - Copper timing note: the copper compares the READER's line counter, which runs ~12 lines ahead of the displayed beam — schedule line numbers ~12 higher than the visual target. The copper is the cycle-exact per-line tool; the raster IRQ (below) is for CPU-side logic at a line. Blitter ------- A chunky-8bpp streaming block-transfer + drawing engine on the SDRAM "chip RAM" (first 16 MBytes, byte-addressed, 1 byte = 1 pixel). Amiga-style interface — pointers, width/height, per-row modulos, GO — but NO barrel shifter and no cookie-cut logic needed: a pixel is a byte, arbitrary alignment falls out of the SDRAM per-byte write mask, and COLOR-KEY transparency replaces masking. Since core v0.90-v0.93 it is also a 3D engine: a Z buffer, perspective-correct texture mapping and whole triangles in one op. Operations: - FILL: constant byte -> rectangle (uncapped width; ~40-50 MBytes/s). - COPY: rect -> rect, optional color-key (source==key pixels skipped); arbitrary alignment, odd widths, independent src/dst modulos (~25-35 MBytes/s; ~250-300 animated 32x32 BOBs erase+draw per 50 Hz frame — Amiga OCS did ~60-70; the MEGA65's own DMAgic moves 40/20 MBytes/s but only inside 384 KBytes BRAM — the blitter works across the full 16 MBytes). ALL widths down to a single pixel are exact (core v126 fixed a legacy 1-word read path that fed narrow keyed blits garbage; fully-transparent words write nothing). - XOR: dest = src^dest (copy) or const^dest (fill; 0xFF = invert). Self-inverse: draw twice = perfectly erased. Non-destructive cursors, rubber-band boxes, flash effects. Color-key composes (keyed pixels XOR nothing). NOTE: XOR overlays and backup-restore BOBs must not overlap — the two restore mechanisms don't commute. - LINE: hardware Bresenham, any slope/direction, any palette color, one byte-write per pixel (~7 Mpix/s ~ 7x Amiga). The CPU passes the start ADDRESS, |dx|/|dy|, stride and an x-direction flag; NO hardware clipping — keep endpoints on the bitmap. - TEXTURED SPANS: a 256x256-texel TEXTURE CACHE (64 KBytes, core v120) lives inside the engine. TEXLOAD burst-reads any WxH region (w,h <= 256, even src/width) from SDRAM into the cache (~40 us for a full 256x256 — swap textures many times per frame if wanted). TEXSPAN draws a horizontal span of pixels sampled at (u,v) stepping (du,dv) per pixel — all Q16.16, affine (PS1-style). U/V wrap at 256 = free tiling; color-key composes = transparent texels. ~1.5 cycles/pixel (~60 Mpix/s peak) regardless of texture content. Atlas technique: pack many small textures into one cache image and select by UV window. - PERSPECTIVE SPANS (core v0.91, opt-in per span): CTRL bit 18 with bit 6 (TEXSPAN; not with the TEXRECT row loop). The span takes the values that ARE linear across the screen: TEX_U/TEX_V = u*w and v*w at the first pixel and TEX_DU/TEX_DV their steps (Q24.8 signed), ZSTART/ZSTEP = w = 1/z and its step (Q16.16, the same values the Z buffer takes). The core cuts the span into 32-pixel pieces, divides at both ends of each piece (a 256-entry reciprocal table, one Newton step, two multiplies, within 0.001 texel of exact) and steps u and v straight between them, as Quake did in software -- ~16 clocks more to start a span, nothing per piece. Keep |u*w| and |v*w| below 2^23. Texture wrap, color key, CBASE and the LUT work as on an affine span. vih_blit_texspan_persp[_ex](). - GOURAUD SPANS: the palette INDEX itself is interpolated per pixel along a span — start index and per-pixel step in Q16.16 (reusing TEX_U / TEX_DU), CTRL bit 16. Point it at an ordered palette ramp and per-vertex lighting shades every face smoothly at flat-fill speed. - TRIANGLES (core v0.93, opt-in per op): CTRL bit 19 with a fill (bit 1), a textured span (bit 6), a perspective span (bits 6 + 18) or a Gouraud span (bit 16). ONE op draws a whole triangle: the blitter walks its rows itself and draws each one exactly as the span a program would have handed over — the same pixels, the same Z test, texture, color key, CBASE and LUT — so the CPU does no work and writes no registers per row. The CPU gives the triangle split at its middle vertex: the long edge (top to bottom vertex, TRI_XL/TRI_DXL), the first short edge (TRI_XS/TRI_DXS, N1 rows), the second (TRI_XS2/TRI_DXS2, N2 rows), TRI_ROWS {N2, N1}, 1/z, u, v on the long edge at the first row (ZSTART/TEX_U/TEX_V) with their steps per row (TRI_DZL/DUL/DVL) and per pixel (ZSTEP/TEX_DU/TEX_DV), and TRI_CLIP {first pixel not drawn, first pixel drawn}. BLIT_DST = pixel (0, first row), BLIT_MOD's dst field = the row stride; BLIT_DIMS is not used. Rows are NOT clipped: give only rows on the screen. ~6 clocks a row to work the row out (the blitter lets go of the bus meanwhile) instead of the ~1.6 us a row costs the CPU. Every triangle value travels through the pend slot and the 256-deep queue, so the next triangle is set up while one draws. vih_blit_tri(), vih_blit_tri_clip(); vih_tri.h sets a triangle up from three vertices (vih_tri_setup() / vih_tri_draw()). - Z BUFFER (core v0.90, opt-in): the blitter's own Z RAM (block RAM in the FPGA, not chip RAM), one cell per 2 pixels of the 384 x 224 screen (192 x 224 = 43008 cells): [15:0] Z = 1/z, BIGGER = NEARER, 0 = empty; [16]/[17] left/right pixel drawn this frame. With BLIT_ZCTRL[0] = 1 every FILL, TEXSPAN, TEXRECT, GOURAUD and triangle op tests and writes it (COPY, XOR, LINE, TEXLOAD never do). Per cell, the op's 1/z at the cell's left pixel is compared (>= wins, so two polygons on one plane tie at their shared edge): a win draws the op's pixels and takes the cell; a loss draws only pixels not yet drawn this frame. Every pixel is drawn once per frame, so a renderer drops its polygon sort. BLIT_ZCLEAR clears all cells in ~0.43 ms BESIDE the blitter (a background FILL can run meanwhile; BLIT_STATUS [2] = 1 while it runs; Z ops wait for it on their own). Not cleared at reset: clear it before the first frame. Speed with Z on (core v0.92): a FILL row costs a plain fill + ~10 clocks, a textured or Gouraud row ~7 clocks more. 1/z below 0 counts as 0, from 65536 up as 65535: scale 1/z so the visible depth range uses the 16 bits. Rows outside the 384 x 224 screen at ZBASE draw as if Z were off. BLIT_ZCTRL is off after every reset, every VIH_OWN_RELEASE write (each .rvk launch) and in vih_init_registers(). - TEXTURED RECT (core v0.33): a whole scaled sprite in ONE op instead of one TEXSPAN per pixel row. CTRL bit 17 turns a textured span into a rectangle: the row loop runs in hardware — u restarts at BLIT_TEX_U each row, v steps by BLIT_TEX_DV per ROW (not per pixel), and dst advances width + dst_mod bytes per row. Color-key / CBASE / LUT apply exactly as on a normal textured span. Slashes the per-op CPU cost of heavy sprite scenes (Out Run: ~1000 span issues/frame -> ~80 rect issues). - COLOR BASE (core v0.30): BLIT_CBASE [7:0] is added to every non-keyed COPY / TEXSPAN pixel before it is stored (the key still tests the raw source byte). Slides a 0..15-valued source bob onto any 16-color block of the 256-entry palette; 0 = legacy behavior. FILL / LINE / XOR / GOURAUD ignore it. - COLOR REMAP LUT (core v0.31): a 256-byte table applied AFTER CBASE on the same COPY / TEXSPAN pixels — written byte = lut[(src + cbase) & 0xFF]. Where CBASE only slides a block, the LUT lands each source value on an ARBITRARY palette entry (global-palette schemes). Disabled at boot = v0.30 behavior. NOT snapshotted by the op queue — a running blit reads the LUT live, so drain (or use the op-serial guard) before rewriting entries a queued blit still references. - OP QUEUE (core v0.32): a GO issued while the blitter is busy is no longer dropped — its parameters are latched and it auto-starts when the current blit ends (one deep). Wait for BLIT_STATUS [1] (pend) = 0 for "queue has room" instead of [0] (busy) = 0 for "fully idle", overlapping CPU work with the blitter. Programs that only wait for busy = 0 are unaffected. - DEEP QUEUE (core v0.85, opt-in): BLIT_QUEUE $3A0001D8 [0] = 1 puts 256 queued blits in front of the one above (vih_blit_queue(1)). Then [0] busy = running OR queued and [1] pend = queue FULL, so vih_blit_wait() and vih_blit_wait_pend() keep their meaning. Off at reset, at every OWN_RELEASE write (every .rvk launch) and in vih_init_registers(). Use vih_blit_wait() before flipping the screen. - CPU SDRAM READ: the texture cache doubles as a CPU read window — TEXLOAD any region, then read cache words back via BLIT_TEXIDX (write word index) / BLIT_TEXDATA (read). vih_sdram_read(dst, src, n) does bulk SDRAM->CPU at ~5 MBytes/s (16 KBytes chunks); vih_sdram_peek8() for single bytes. CLOBBERS the cache (re-TEXLOAD textures after). Contract: discard the FIRST TEXDATA read after writing TEXIDX (the index write is still in flight through the bridge; the helpers do this). Since core v0.39 the CPU simply reads chip RAM through its own window (see "SDRAM") -- new code should use that. Engine facts: - Row-oriented streaming: burst-read source row -> line buffer, assemble the destination row (data + per-word byte masks), stream out with page-mode BURST WRITES at one word (2 px) per clock. - Bus position: the last SDRAM master, priority video reader > PCM DMA > CPU cache > VIC picture writer > blitter. Sprites/display ALWAYS win; blitter grants are bounded, so the display can never be disturbed. - WATCHDOGS: the bus arbiter force-releases any grant stuck ~82 us; the blitter aborts any blit stuck ~1.3 ms (busy clears, done fires). A rare glitch costs one corrupted blit, never a wedged machine. Since core v0.77 only time the blitter actually HOLDS the bus counts: a blit starved by a long CPU write burst into chip RAM pauses and finishes, instead of being cut off after a line or two. - Completion: blit_done raises VIH IRQ source bit 1; BLIT_STATUS [0] is a polled busy flag (vih_blit_wait()) and [1] is the op-queue pend flag (vih_blit_wait_pend(), core v0.32). - Registers (via the ctrl bus): 0x3A0001A0 BLIT_SRC [23:0] source byte address 0x3A0001A4 BLIT_DST [23:0] destination byte address 0x3A0001A8 BLIT_DIMS {height[31:16], width[15:0]} pixels 0x3A0001AC BLIT_MOD {dst_mod[31:16], src_mod[15:0]} bytes/row (LINE and triangles: dst_mod = row stride) 0x3A0001B0 BLIT_CTRL [0]GO [1]fill [2]colorkey [3]XOR [4]line [5]line-x-negative [6]texspan [7]texload [15:8]key/fill/line color [16]gouraud [17]texrect (hardware row loop, core v0.33) [18]persp (perspective span, core v0.91) [19]tri (whole triangle, core v0.93) 0x3A0001B4 BLIT_STATUS (read) [0]=busy [1]=pend (queue full, v0.32) [2]=Z clear running (v0.90) 0x3A0001B8 BLIT_TEX_U span start U (Q16.16); texrect: per-row restart; persp: u*w (Q24.8) 0x3A0001BC BLIT_TEX_V span start V (Q16.16); persp: v*w (Q24.8) 0x3A0001C0 BLIT_TEX_DU per-pixel dU (Q16.16, signed); persp: Q24.8 0x3A0001C4 BLIT_TEX_DV per-pixel dV (Q16.16, signed); texrect: per-ROW v step; persp: Q24.8 0x3A0001C8 BLIT_TEXIDX CPU read window: cache word index (write) 0x3A0001CC BLIT_TEXDATA CPU read window: cache word (read, [15:0]) 0x3A0001D0 BLIT_CBASE [7:0] color base added to COPY/TEXSPAN pixels (core v0.30); 0 = legacy. RISC-V write only. 0x3A0001D4 BLIT_LUT color remap table (core v0.31). RISC-V write: [31]=1 -> enable = [0]; [31]=0 -> lut[[15:8]] = [7:0]. Applied after CBASE on COPY/TEXSPAN. 0x3A0001D8 BLIT_QUEUE [0] = 1: 256-deep op queue (core v0.85). 0x3A0002C0 BLIT_ZCTRL [0] = 1: Z buffer on (core v0.90); taken with each op 0x3A0002C4 BLIT_ZBASE [23:0] byte address of the framebuffer's pixel (0,0), even, 512-byte rows; read LIVE -- change it only while the blitter is idle 0x3A0002C8 BLIT_ZSTART 1/z at the op's first pixel, Q16.16 unsigned 0x3A0002CC BLIT_ZSTEP 1/z step per pixel, Q16.16 signed 0x3A0002D0 BLIT_ZCLEAR any write clears the Z buffer 0x3A0002D4 TRI_XL long edge x at the first row, Q16.16 (v0.93) 0x3A0002D8 TRI_DXL its step per row, Q16.16 signed 0x3A0002DC TRI_XS first short edge x at the first row 0x3A0002E0 TRI_DXS its step per row 0x3A0002E4 TRI_XS2 second short edge x at row N1 0x3A0002E8 TRI_DXS2 its step per row 0x3A0002EC TRI_ROWS [9:0] N1, [25:16] N2 rows 0x3A0002F0 TRI_DZL 1/z step per row along the long edge 0x3A0002F4 TRI_DUL u step per row along the long edge 0x3A0002F8 TRI_DVL v step per row along the long edge 0x3A0002FC TRI_CLIP [9:0] first pixel drawn, [25:16] first pixel not drawn (0..1023 after reset, OWN_RELEASE and vih_init_registers()) C API (risc/vih_regs.h): vih_blit_fill/copy/copy_key/xor/xor_fill/line, vih_blit_texload/texspan/texspan_ex/texrect, vih_blit_gouraud, VIH_BLIT_CBASE, vih_blit_lut_set/lut_enable, vih_blit_z/zbase/zclear/zclear_wait/zspan (v0.90), vih_blit_texspan_persp/texspan_persp_ex (v0.91), vih_blit_tri/tri_clip and vih_tri.h (v0.93), vih_sdram_read/peek8, vih_blit_busy()/vih_blit_wait()/vih_blit_wait_pend(). - COPY/XOR/TEXSPAN width capped at 1024 px per op (line buffers); FILL and LINE uncapped (line up to 2047 px of major axis). 3D on the blitter. The CPU rotates and projects the vertices (hardware mul/div, Q16.16) and culls back faces (one cross product per face); the blitter does the rest. Since core v0.93 one triangle op per polygon (vih_tri.h sets it up from three vertices), the Z buffer replacing the polygon sort (v0.90) and perspective-correct texturing per triangle (v0.91). The older recipe -- the CPU walks the edges and issues one span per scanline, flat FILLs, TEXSPANs or GOURAUD spans -- still works (risc/apptest/apptest_vect.c), with vih_blit_zspan() giving each span its 1/z. Per frame with Z: vih_blit_wait(); /* last frame's ops are done */ vih_blit_z(0u); /* background without Z ... */ vih_blit_zbase(fb); vih_blit_zclear(); /* ... while the Z RAM clears */ vih_blit_fill(fb, 512u - 384u, 384u, 224u, 0u); vih_blit_z(1u); /* then the triangles (or spans) */ Interrupts (KERNAL-style) ------------------------- The kernel (in KERNEL.BIN, loaded from the SD card) owns the trap machinery; apps install ONE handler through a RAM vector. - Hardware trap -> mtvec 0x20 -> kernel dispatcher (saves registers, reads mcause) -> source routine -> calls THROUGH the common vector at 0x24 (the C64 $0314/CINV equivalent, in always-writable low RAM). - Common handler signature: bool irq(uint32_t status) — status is the KERNEL's remapped bit struct (irq_status_t, shared/boot_protocol.h): [0] timer, [1] raster, [2] blitter-done, [3] key, [4] Ethernet, [5] vblank. Return true = handled (source is acked), false = leave pending (re-fires). NOTE this word is NOT VIH_IRQ_STATUS: the raw VIH sources (listed below) use their own bit order. Bits [3]-[5] are set from kernel build 125; earlier kernels forwarded key/Ethernet/vblank with every bit clear, so an app had to read 0x3A000188 itself. - An app installs its handler by writing a function pointer to IRQ_VECTOR (0x24) — no core rebuild. Default = a do-nothing bootloader handler. - Sources: * 50 Hz machine timer (Murax APB timer, set up by the bootloader). * VIH raster compare: write the target scanline to VIH_RASTER_TARGET (0x184), enable bit 0 in VIH_IRQ_MASK (0x18C). CPU-timescale (a few lines of latency) — use the copper for cycle-exact per-line effects. * Blitter done: VIH IRQ source bit 1. * Keyboard event queued: bit 2. * Ethernet frame received: bit 3 (core v0.62). * Vertical blank started: bit 4 (core v0.65). Once per frame, at the moment the display stops reading -- so a buffer flip or a sprite move made here cannot tear. Not the same as a raster compare on the last visible line, which fires while the fetch is still running. VIH_IRQ_STATUS (0x188): read = pending bits, write = 1-to-clear ack. - Helpers: vih_raster_at(line), vih_irq_enable(mask), vih_irq_ack(bits). Tile Map (text/tile layer) -------------------------- - One MERGED 128-row tile BRAM = two 64x64 maps' worth of contiguous, row-addressable space. 8x8 (or 8x16) tiles, 48x28 visible. - Display base selected by a ROW-GRANULAR pointer (VIH_TILEMAP_PTR, 0..127): +64 = classic two-screen switch, +1 = one-tile-row "tall scroll" through the whole 128-row space. - Cell = 32 bits: [7:0] char (bit [26] = char high bit, 512 glyphs), [15:8] fg, [23:16] bg, [24] h-flip, [25] v-flip, [27] char bit 9 for the 8bpp font only (1024 glyphs, core v0.86), [30:28] the cell's palette, added to the tile layer's (core v0.95). - Per-tile 1bpp (fg over bg) or 8bpp (full-color glyph) via TILE_COLOR_MODE. - bg index 0 optionally transparent (GFX shows through) or solid. - Smooth pixel-accurate X/Y scrolling, wraps on the 64-tile map. - Tile layer sits above or below the GFX framebuffer (tile priority). - Direct cell writes: the tile maps are mapped at 0x3A038A00 / 0x3A040200 on the ctrl bus. - HI-RES TEXT (core v0.95): VIH_VIDEO_MODE $3A000298 [0] = 1 draws the tile layer at twice the horizontal resolution: 768 DOTS a line (a dot every 64 ns), 640 across the picture, so 80 columns of 8x8 text fit where 40 did. The GFX picture, the sprites and the border keep their pixels (each pixel two dots, in the same place); line and frame rates and the 15 kHz analog picture's size do not change. The map is 128 cells wide: a text row is two map rows (cells 0-63 in map row 2r, 64-127 in 2r+1), so cell (row, col) is VIH_TILE_MAP0_BASE[row * VIH_HIRES_MAP_W + col]. Columns count dots from the screen's left edge: with the usual 32-pixel border column 8 is the picture's left edge and 80 columns are 8-87. TILE_SCROLL x counts dots. Cells, fonts, colors, flips and the 8bpp font work as in lo-res, glyphs half as wide, 8x8 only. Taken where the next frame starts; 0 at power-on, at every .rvk launch and from vih_init_registers(); vih_video_mode(1) switches it on. Fonts ----- - ROM font: built-in character ROM, 8x8, 1bpp (font_src=0). MEGA65 ASCII set since v0.42 (was the C64 set, which had no lowercase). Codes $A0-$D4 hold the V32 boot logo; $D5-$F7 are blank and free. - BRAM font: uploaded, 512 chars, 8x8 or 8x16, 1bpp (font_src=1 + height bit). - 8bpp font ("font8"): uploaded, 512 chars x 8 rows, one palette byte/pixel. 1024 chars (64 KBytes) since core v0.86: cell bit 27 picks 512-1023; the upload index is 13 bits. - Upload: poke glyphs directly into the font BRAMs (VIH_FONT_WR_ADDR selects {bram, entry}, pairs of VIH_FONT_WR_DATA write 64-bit entries, auto-increment) — helpers vih_font1_glyph(), vih_font1_glyph_8x16(), vih_font8_glyph(). Hardware Sprites ---------------- - 16 sprite channels, composited every scanline with NO per-line limit — all 16 can overlap the same line (pipelined fetch/write compositor). - 64 x 64 pixels each, 1bpp (single fg color) or 8bpp (256-color). - Signed X/Y (grid-absolute, C64-style: (0,0) tucks behind the top-left border); compositor clips off-screen parts. Sprite x lands exactly on screen x since core v0.95 (one pixel to the left before). - Per-sprite priority (on_top), H/V flip, index-0 transparency (8bpp can disable it), and its own palette (SPRITE_ATTR [24:22], added to PAL_SEL's sprite palette, core v0.95). - Channels are written directly: VIH_SPRITE_POS {ch,Y,X} and VIH_SPRITE_ATTR {ch,flags,color,slot} take effect immediately (not frame-latched — for tear-free motion, update in the reader-idle gap, beam lines ~211..222; spin on VIH_RASTER_VPOS, see the vblank() idiom in the tutorials — the old vih_wait_frames/vih_wait_raster helpers are REMOVED). The copper can do the same per scanline (SPRITE_MOVE / SPRITE_SLOT) to multiplex channels down the screen. - Sprite pixel data lives in SDRAM (4096-byte slots; slot number = addr/4096). Upload via the CPU's chip-RAM window, the blitter, or bundled as .rvpk assets. Sprite Collision (VIC-II style) ------------------------------- - Pixel-perfect, per-sprite, computed every frame. - Sprite-to-sprite (like $D01E) and sprite-to-background (like $D01F, background = non-transparent FB pixel or opaque tile) 16-bit masks. In hi-res text mode the sprite-to-background test runs every dot. - Read the per-frame snapshot at VIH_SPRITE_COLL (0x3A000150). Layer Compositing (bottom to top) --------------------------------- Border (outside the active window) Background color / transparent index 0 HW sprites with on_top = 0 (behind) Framebuffer (GFX) Tile map (* priority-selectable vs GFX) HW sprites with on_top = 1 (front) Scrolling --------- - Framebuffer X: pixel-accurate 0..511, circular on the 512px line. * The FINE (sub-8px) part requires border_top >= 1 (or bottom) — the fine offset re-latches only on a vertical-border scanline. Left/right borders do not help. Since core v0.78 a top or bottom of 0 is stored as 1, so this always holds. - Framebuffer Y: 0..255, circular on the 256-row buffer (32 off-screen rows). - X and Y combine freely (diagonal). Tile map scroll is independent. Audio ----- Every source sums to one 16-bit output (stereo where a source is stereo), delivered to the 3.5 mm jack (VIXEN's own AK4432 DAC driver, v0.94) and to HDMI. - SID: VIXEN's own (core v0.95), a cycle-modelled MOS 6581 with its DC offsets, R-2R DACs and multi-mode filter, sounding as the SID before it; 3 voices, ADSR, filters, ring-mod/sync, 1 MHz clock enable (clk_sys/100). Poke any register via VIH_SID {reg[12:8], value[7:0]} — C64 $D400-style. (From EhBASIC: POKE 46080+reg.) Since core v0.79 every write reaches the SID in order, at most one per 1 MHz tick: gate off + gate on back to back restarts the note, like a C64. While the C64 chips are on (v0.96) the C64 owns and clocks the SID, and its OSC3 and ENV3 read back. - Square-wave beeper: one divisor register (audio_freq); 0 = silent. The divisor scale matches the historical 24.576 MHz reference (synthesized from clk_sys by a fractional divider), so existing app pitch tables work. - 4-channel PCM sample player: per voice SDRAM sample base/length, Q16.16 pitch with linear interpolation to the ~48 kHz mix, 8-bit volume, one-shot or loop with arbitrary loop start (Amiga/Paula-style sustain loops). 8-bit signed (packed) or 16-bit samples, streamed from SDRAM through per-voice BRAM rings, refilled by a round-robin DMA during vblank. Control block written via VIH_PCM_IDX / VIH_PCM_DATA. Optional 75/25 stereo pan (Amiga voice routing). Since core v0.95 the DMA reads only a sample's own words, so samples no longer turn distorted after long use with resets. - YM2151 (core v0.95, VIXEN's own, sample for sample as ymfm): 8 FM voices of 4 operators, stereo. The RISC-V writes it through VIH_CPU8_YM $3A00033C (W {register[15:8], value[7:0]}, queued; R status [0] timer A [1] timer B [7] busy); the Z80 can drive it on its own through two ports or addresses, its timers on the Z80's INT, as on arcade sound boards. - The VIC-20's VIC (6561) adds its three voices and noise while the VIC-20 chips are on (v0.95). - risc/mod_player.h: full 4-channel ProTracker (.mod) replayer on the PCM engine (pattern sequencer + effects at 50 Hz on the CPU; FPGA mixes). - VIH_AUDIO_ENABLE: master mute at the mixer (copper-drivable). The 8-bit CPU Block (core v0.95 / v0.96) ---------------------------------------- A 6502 and a Z80 inside the core, next to the RISC-V. They share 64 KBytes of their own RAM at 0x000C0000-0x000CFFFF (the RISC-V reads and writes it as ordinary memory, Trapdoor RAM speed); one of them runs at a time, from 1 MHz (or slower) up to 25 MHz (CPU8_SPEED = Hz x 2^32 / 50,000,000). The 6502 is VIXEN's own: an NMOS 6502 with every opcode, documented and undocumented, bus-cycle exact. The Z80 is T80. The RISC-V loads code, sets the speed and lets the CPU run; nothing in the RISC-V slows down. EhBASIC runs on this 6502 (kernel 138 on), and so do the VIC-20 (GO V20 / GO 20) and the C64 (GO 64); CP/M runs on the Z80. - Registers $3A000300-$3A00033C: CPU8_CTRL (run, Z80/6502, reset, IRQ, NMI, [5] VIC-20 chips, [6] the 6502 on the VIC's clock, [7] C64 chips), CPU8_SPEED, CPU8_TRAP (4 KBytes blocks whose accesses go to the RISC-V; [16] every Z80 IN/OUT), CPU8_ROM, CPU8_STATUS, CPU8_TRAPINFO, CPU8_REPLY, CPU8_PC, CPU8_KEYS0/1 (the VIC-20's or the C64's keyboard matrix), CPU8_JOY, CPU8_VICFB (the VIC's or VIC-II's picture into chip RAM), CPU8_VICPOS, CPU8_RESUME, CPU8_STOPPOS, CPU8_YM. The state window $3B010000-$3B0103FF holds one item a word: the CPUs', VIAs', VIC's and CIAs' registers, the page map, the trap map, the ROM loader, the cartridge lines and the paddles. - TRAPS: an access to a trapped block stops the CPU in the middle of that access until the RISC-V answers (poll CPU8_STATUS [1], read CPU8_TRAPINFO, write CPU8_REPLY). Dummy reads and writes trap too, exactly as they would touch real I/O. - VIC-20 CHIPS (v0.95, CTRL [5], the 6502 only): the VIC (6561 PAL, at $9000) and two 6522 VIAs (keyboard, joystick, timers), all VIXEN's own, cycle for cycle with the 6502. The VIC writes its picture into chip RAM, one byte a pixel = palette bank x 16 + VIC color, and its sound into the mix. CTRL [6] runs the 6502 on the VIC's clock (1,108,405 Hz, 22,152 cycles a frame). - PAGE MAP (v0.95): each 1 KByte page of the 64 KBytes is RAM, ROM, absent or trapped -- every VIC-20 memory layout and cartridge. - CONTEXT SWITCH (v0.95): every register of the CPU, the VIC and the VIAs can be read and written while the CPU is stopped, and CPU8_RESUME starts it again in the exact VIC cycle where it stopped -- several machines can take turns on the one CPU. - C64 CHIPS (v0.96, CTRL [7], the 6502 only): a VIC-II (6569 PAL) at $D000, two 6526 CIAs at $DC00/$DD00, the PLA's memory map and the 6510's port at $00/$01, on the machine's own SID. 20 KBytes of ROM and 1 KByte of color RAM beside the 64 KBytes, loaded by the RISC-V (the core holds no Commodore ROM: c64hw loads the user's own from /VIXEN-32/C64/). The 6502 runs on the VIC-II's clock (985,249 Hz) and is stopped on bad lines and for sprites, as on a C64. The VIC-II writes its picture into chip RAM: 448 pixels a line, all 312 lines. - C64 CARTRIDGE PORT (v0.96): 16 KBytes of ROML/ROMH and a second ROMH bank switched in the core for Zaxxon; GAME and EXROM lines read by the PLA. A TRAP MAP (a bit for every 16 bytes) gives $DE00-$DFFF and any bank to the RISC-V, which plays a cartridge's registers and bank switching. - PADDLES AND THE 1351 MOUSE (v0.96): POTX/POTY values the RISC-V writes, read by the C64 on control port 1 or 2 and by the VIC-20 at $9008/$9009. Every bit of it: Chipset Reference, chapter 9, "8-bit CPU block". RISC-V CPU & Control Interface ------------------------------ - VexRiscv "Murax" (rv32im + Zicsr, pipelined DSP multiplier), 100 MHz, 512 KBytes on-chip RAM based at 0x0 (retro-style memory map, KERNAL at the summit): 0x00000 reset jump 0x00020 trap vector 0x00024 IRQ common vector 0x0000C BL_LOCK write-protect map 0x00100 application RAM (~423 KBytes contiguous) 0x6A000 compressed BASIC payload (72 KBytes, to 0x7C000; free RAM once booted -- an app's stack is capped at 0x76000) 0x7C000 KERNAL work stack (8 KBytes) 0x7E000 resident KERNAL (top 8 KBytes, hardware write-protected) 0x7FF00 kernel jump table (64 entries, anchored at the top: entry n at 0x80000 - 4n) 0x80000 TRAPDOOR RAM, 256 KBytes, to 0xBFFFF (core v0.87) 0xC0000 CPU8 RAM, the 8-bit CPU block's 64 KBytes, to 0xCFFFF (core v0.95) 0x3A000000 VIH control registers 0x3B010000 the 8-bit CPU block's state window (core v0.95) 0x40000000 CHIP RAM window, 16 MBytes (cached; see SDRAM below) 0x41000000 ZORRO RAM, 48 MBytes, to 0x43FFFFFF (core v0.89, CPU only) - BL_LOCK (word 0x0C): 16-bit hardware lock map, one bit per 8 KBytes block of the TOP 128 KBytes (0x60000-0x7FFFF); bit set = read-only (writes silently dropped). NOTHING is locked at reset since v0.55 (the kernel comes off the SD card and locks its own block after landing -- C64 $01-style). A blocked write DOES NOT FAULT: it is silently discarded and reads still pass. The lower 384 KBytes is always writable. - The VIH control bus decodes 0x3A000000+ DIRECTLY in fabric. - Register defaults & ownership: every VIH register has a sane reset default (the boot screen needs no setup). A register written by the CPU stays CPU-owned (sticky riscv_owns_* latch) and the copper/default source is ignored for it from then on. Peer registers (border_color, bg_color, tile_bram_sel, gfx_enable, audio_enable) are last-write-wins with the copper instead. A LAUNCHER hands registers back with VIH_OWN_RELEASE (0x19C): one write drops ALL the latches and puts the opt-in features back to their classic state (deep blitter queue, instruction cache, Z buffer, triangle clip, hi-res text, the 8-bit CPU block) -- this, not the soft reset, is the app-launch path (the soft reset -- ctrl_word bits 2+1 together -- also zeroes copper_count and the display defaults, which is a bigger hammer than a handover wants). Every app re-pokes what it needs (vih_init_registers()). - SDRAM "chip RAM" write port: VIH_SDRAM_ADDR (24-bit dest, auto-inc) + VIH_SDRAM_DATA (16-bit words) through a FIFO drained each vblank — a startup loader path (the CPU window and the blitter are the fast movers). 16 MBytes limit with an honest overrun flag (VIH_SDRAM_STATUS). - Read-back registers (via the bridge): raster hpos/vpos (0x04/0x0C), border/bg color LIVE (0x104/0x108 -- a copper-set value included), SDRAM write status (0x14C), sprite collisions (0x150), joysticks (0x180/0x1E8), mouse (0x1EC), IRQ pending (0x188 -- the MASK at 0x18C stays write-only), keyboard FIFO head (0x190), OSD status/size (0x194/0x198, always 0 since v0.94), blitter status + texture read window (0x1B4/0x1CC), FPU result (0x208), SD status (0x1F8), the Ethernet block, the drive blocks, the 8-bit CPU block's registers. Everything else reads 0 -- keep a shadow, never read-modify-write. - Code+asset loading: single-file .rvpk container — code -> BRAM or chip RAM, assets -> chip RAM, placed by the launcher. Code blocks may target either memory: BRAM for speed, chip RAM for programs too big for it (see the chip-RAM notes below). Register map (0x3A000100+, all 32-bit): 0x100 boot_ack 0x104 border_color 0x108 bg_color 0x10C copper_cnt 0x110 font_ctrl 0x114 ctrl_word 0x118 tile_bram_sel 0x11C tile_scroll 0x120 tilepatch_en 0x124 tile_priority 0x128 sprite_enable 0x12C tiles_enable 0x130 border_dims 0x134 gfx_enable 0x138 audio_enable ^^^^^^^^^^^ NEVER SET TOP AND BOTTOM BOTH TO 0. The vertical border lines are when the engine re-latches the sub-8-pixel scroll offset and starts the line fetch. With none of them: fine X scrolling stops working (the picture jumps a whole 8-pixel cell instead of one pixel), and the layer can come up displaced sideways by a multiple of 8 -- a different amount each power-on. One line top and bottom is enough; the 12/12 default is well clear. Since core v0.78 the core enforces it: a top or bottom of 0 is stored as 1. 0x13C sprite_pos 0x140 sprite_attr 0x144 sdram_wr_addr 0x148 sdram_wr_data 0x14C sdram_status(R) 0x150 sprite_coll(R) 0x154 palette 0x158 gfx_ptr 0x15C gfx_scroll 0x160 sid 0x164 pcm_idx 0x168 pcm_data 0x16C tilemap_ptr 0x170 font_wr_addr 0x174 font_wr_data 0x178 copper_wr_addr 0x17C copper_wr_data 0x180 joystick(R) 0x184 raster_target 0x188 irq_status(R/W1C) 0x18C irq_mask 0x190 keyboard(R/W) 0x194 osd_status(R) 0x198 osd_size(R) 0x19C own_release(W) 0x1A0-0x1D4 blitter incl. texture regs, CPU read window, CBASE, LUT 0x1D8 blit_queue(W) [0] = 1: 256-deep blitter queue (core v0.85) 0x1DC icache(W) [0] = 1: instruction cache for code above the 512 KBytes (core v0.88) 0x1E0 sdram_phase(W) SDRAM clock fine-phase target, 0..559 steps of ~17.86 ps (one full 100 MHz period). Actual position + busy read back via Murax GPIO input (0xF0000000, bits [26:16] = {busy, current}). Ship setting is 0 (180 deg, centre of both measured data eyes); the sweep instrument is POKE 45298,1 in EhBASIC. 0x1E4 cache_inval(W) drop the whole 32 KBytes chip-RAM cache (~10 us); also empties the instruction cache (core v0.88) 0x1E8 joystick2(R) port 2, same bit order as port 1 0x1EC mouse(R) Amiga mouse: free-running X/Y counters + buttons 0x1F0-0x1F8 SD card claim / one-access command port / status 0x1FC temp(R) {valid[31], code[11:0]} FPGA temperature (v0.82) 0x200-0x238 FPU operand A / result (read stalls) / GO-per-op (add sub mul div f2i i2f u2f f2u eq lt le); not reentrant -- no floats in interrupt handlers 0x260-0x28C Ethernet ctrl/status/rx/tx/MAC + carrier/frames/CRC/PHY counters; packet buffers at 0x3A100000/0x3A100800 0x290 hdmi(W) [0] zoom [1] scanlines (core v0.95) 0x294 pal_sel(W) each layer's palette (core v0.95) 0x298 video_mode(W) [0] = 1: hi-res text (core v0.95) 0x2A0-0x2BC drives A:/B: LBA/ctrl/status/size; sector buffers at 0x3A101000/0x3A101200 (32-bit accesses only) 0x2C0-0x2D0 Z buffer BLIT_ZCTRL/ZBASE/ZSTART/ZSTEP/ZCLEAR (core v0.90) 0x2D4-0x2FC triangles TRI_XL ... TRI_CLIP (core v0.93) 0x300-0x33C 8-bit CPU block: CPU8_CTRL ... CPU8_YM (core v0.95) Keyboard -------- Events arrive at 0x190 as {valid[10], pressed[9], extended[8], code[7:0]}; a write pops the 8-deep FIFO; a push raises IRQ pending bit 2. On the MEGA65 each event carries the NATIVE key number: code = 0x80 | key (0..79, C65 matrix order) from VIXEN's own keyboard reader — no PS/2 emulation. The kernel decodes these through true C64-layout tables, so every key types what is printed on it (shift+2 = '"', and with MEGA held the character printed on the front of the key). Since core v0.94 every key reaches the core, HELP included. File Loading ------------ Since core v0.94 the kernel loads files itself: the file browser in KERNEL.BIN (the HELP key) starts .RVK programs, loads .BAS and .PRG files into EhBASIC and mounts .IMG disk images as A: and B:, all through the kernel's FatFs on the SD card; from EhBASIC, READF loads any file into chip RAM. The old platform-menu path -- a file streamed into SDRAM staging at 0x800000, completion published at 0x194 (OSD_STATUS) and its size at 0x198 (OSD_SIZE) -- is gone with the framework: both registers still exist and always read 0, so a program polling them simply never sees a load. SDRAM (64 MBytes "chip RAM") ---------------------------- - The R6's onboard IS42S16320F (32M x 16), driven by VIXEN's own controller (rewritten from the datasheet in core v0.95, the same timing clock for clock) at 100 MHz CL2 through pins with measured data eyes ~4 ns wide (default clock phase centred — see mega65/SDRAM_BRINGUP.md for the bring-up story and the three constraints/RTL rules it produced). - First 16 MBytes = the byte-addressed "chip RAM": sprite slots (addr/4096), PCM samples, textures, framebuffers, the VIC's and VIC-II's pictures, file staging at 0x800000. - THE CPU SEES ALL OF IT AS ORDINARY MEMORY, through a 16 MBytes window at 0x40000000 backed by a 32 KBytes cache (core v0.39): volatile uint8_t *p = VIH_SDRAM_MEM; /* 0x40000000 */ p[addr] = 0x42; /* write */ v = p[addr]; /* read */ Reads and writes both go through it — no FIFO, no blitter round-trip. The older paths still exist and still work: the vblank write FIFO (VIH_SDRAM_ADDR/DATA) as a startup loader, and vih_sdram_read() through the blitter's texture-cache window for one-shot bulk reads. New code should just use the window. - FASTER 32-BIT STORES (core v0.95): a 32-bit CPU store to chip or Zorro RAM is ONE two-word SDRAM burst in one bus grant (it was two writes): clearing 1 MByte of chip RAM with the CPU takes 62 ms (was 113), Zorro to chip copies run at ~13 MBytes/s (was ~8). Byte and halfword stores, reads and the blitter are unchanged. - CODE CAN RUN FROM CHIP RAM, not only data (core v0.39). That lifts the limit on program size from the CPU's 512 KBytes to megabytes — a 1.5 MBytes program runs. It is slower than running from CPU RAM, so the rule is: hot loops and per-pixel buffers in CPU RAM, bulk code and assets in chip RAM. A program that fits in CPU RAM should stay there. - CACHE RULE: the cache only watches the CPU. After the BLITTER, the VIC or the FILE LOADER writes chip RAM, call vih_cache_invalidate() before reading those bytes, or the CPU may serve the old ones. CPU writes are write-through and never need it. ~10 us, so once per batch. - The remaining 48 MBytes is outside the 24-bit chip-RAM bus. Since core v0.89 it is ZORRO RAM: the CPU's window is 64 MBytes, and 0x41000000-0x43FFFFFF is the other 48 MBytes, for the CPU only (same cache, same speed, data and code). Keep assets there and copy what the blitter, display or audio need into chip RAM (~13 MBytes/s). Not cleared at reset; vih_zorro_present() first. - Bus masters, fixed priority: video reader > PCM DMA > CPU cache > the VIC's or VIC-II's picture writer (v0.95) > blitter. (The old file-staging port sits between PCM and the CPU and has been idle since v0.94.) The display can never be disturbed; watchdogs bound every grant. - Diagnostics: POKE 45298,1 runs the built-in test/eye-sweep instrument. EhBASIC boot (from the SD card, v0.56 on) ----------------------------------------- The machine powers on into a complete BASIC computer, but the kernel is NOT IN THE CORE: the bitstream holds a small bootstrap that loads /VIXEN-32/KERNEL.BIN off the card (BOOT.BIN up to core v0.93), zeroes BRAM, unpacks the image and hands over. The bootstrap reads only the kernel part of KERNEL.BIN; the programs after it (VMOS, the file browser, the VIC-20, the commander, the C64) are read when they are started. Kernel and BASIC updates are a file copy -- no core rebuild. A missing or bad image gets a red-bordered error screen (E01..E09) and the machine stops; see the Chipset Reference, chapter 10. EhBASIC itself runs on the core's 6502 (kernel 138 on). See docs/BasicMachine.txt for the machine BASIC lands in, the kernel jump table (shared/kernel_api.h, anchored at the top of RAM), and the POKE map. Clocking Summary ---------------- VIXEN's own clocks (rtl/mega65/vixen_clocks.sv, core v0.94), all from the MEGA65's 100 MHz board oscillator. One MMCM, VCO 1000 MHz: clk_sys 100 MHz CPU (Murax), SDRAM, reader, compositor, blitter, SID sequencer, PCM clk_vid 31.25 MHz video clock (PAL-exact chain; separate async domain) ce_pix 7.8125 MHz pixel rate (clk_vid / 4) sdram_ck 100 MHz SDRAM chip clock, runtime-tunable phase (~17.86 ps/step via 0x3A0001E0), base 180 deg clk_50 50 MHz the SD card controller (25 MHz SPI) and the 8-bit CPU block (a 6502 cycle or Z80 T state is one step of it divided down) ce_1m 1 MHz SID core clock enable (clk_sys / 100) beeper ref 24.576 MHz equivalent, synthesized from clk_sys by a fractional divider (keeps historical pitch scale) A second MMCM makes the audio DAC's 12.288 MHz master clock (256 x 48 kHz); a third makes HDMI's 27 MHz pixel clock and the 135 MHz serializer clock. All three come from the same oscillator, so an HDMI frame stays locked to the PAL frame.