VIXEN-32 BASIC Machine — EhBASIC 2.22 on the core's 6502 ======================================================== The machine's interactive face: the core's own 6502 (the 8-bit CPU block, 25 MHz -- kernel build 138 on; up to 137 a 6502 emulated in C, fake6502) running EhBASIC 2.22, wired to a 40x25 tile-map text console (80x25 after ESC X, build 141 on) with a C64-style full-screen editor. All of it is ONE RISC-V application: risc/basic_test.c. SINCE CORE v0.56 IT IS NOT AN .rvk YOU LOAD -- it is the kernel image at the front of /VIXEN-32/KERNEL.BIN, the file the bitstream bootstrap loads off the SD card at power-on (cores up to v0.93 load the same image as /VIXEN-32/BOOT.BIN), so changing BASIC is a file copy and needs no core rebuild: `make basic packb`, then `make KERNEL.BIN` in risc/sdboot (the kernel image followed by VMOS, the file browser, the VIC-20, the commander and the C64), then copy KERNEL.BIN to /VIXEN-32/. There is no fallback -- a missing or damaged KERNEL.BIN gets a red-bordered error screen and the machine stops. See release/version_basic.txt for its own version history, and the Chipset Reference chapter 10 for the boot chain. Confirmed on hardware 2026-07-16 (MEGA65 R6); originally brought up on the now-removed host-CPU target 2026-07-14 — and visibly faster than a real C64 (interpreted 6502 on the 100 MHz RISC-V runs at a few MHz effective; since build 138 the core's 6502 runs EhBASIC about seven times faster again). ONE payload serves both platforms: the keyboard code auto-detects PS/2 scancodes (legacy path, kept) vs native MEGA65 key numbers. Boot flow --------- 1. Console init (blue screen + yellow border, white text, ROM font, ctrl_word stabilization). 2. Boot screen drawn: the V32 logo with the machine banner beside it. The logo is TEXT -- glyphs $A0-$D4 of the character ROM, printed as ordinary console cells with per-cell color, so it scrolls away like any other output. 3. 6502 machine built: 44 KBytes RAM + EhBASIC ROM + the trapped I/O pages (see maps). 4. The 6502 leaves reset -> min_mon asks (C)old/(W)arm -- auto-answered 'C'. EhBASIC's start-up output (that prompt, "Memory size ?", bytes free, the version line) is SUPPRESSED so the boot screen stays clean; the gate lifts the moment BASIC first reaches its line-input loop. 5. "Ready" printed directly under the logo -- spelled the way EhBASIC spells its own prompts and error messages, not "READY.". Keys ---- Enter feed the screen line under the cursor to BASIC (see editor) Arrows move the cursor anywhere Backspace local screen edit (Ins/Del on the MEGA65) ESC RUN/STOP -- sends Ctrl-C ($03): "BREAK IN LINE n", CONT resumes (the MEGA65's RUN/STOP key does the same) ESC then X 40 / 80 columns, as on a MEGA65 (build 141 on): press ESC, let go, press X. See 80 COLUMNS below. MEGA held the characters printed on the front of the MEGA65's keys, as in VMOS (build 144 on): MEGA + / = \ MEGA + , = ~ MEGA + . = | MEGA + = = _ MEGA + : = { MEGA + ; = } MEGA + left arrow = ` (no key shows it) RUN/STOP + RESTORE the C64 panic escape (core v0.68). Resets the border and background to the boot colors, clears the screen and returns to a "Ready" prompt. Unlike Ctrl-C this does not ask the running program to stop -- it jumps the 6502 to EhBASIC's warm start, so it also rescues you from machine code that never returns. (all keys auto-repeat: 0.5 s delay, ~16 Hz; letters are sent uppercase -- EhBASIC keywords require it) Layout by platform (kbd events carry the source in code bit 7, see the VIH manual's 0x190 notes): - PS/2 path (legacy, still compiled in): scancodes, US positions (shift+2 = '@' etc.). - MEGA65: NATIVE key numbers decoded through true C64-layout tables -- every key types what is printed on it: shift+2 = '"', shift+7 = ''', colon/semicolon/at/asterisk/+/-/= on their own keys. POKE reference (the $B000 window and friends) --------------------------------------------- $B000 is the machine's I/O page, laid out like a C64's $D000 -- $B020 is the border exactly as $D020 is on a C64, so a sprite routine ports by changing one digit. Full table with decimal addresses: Chipset Reference, Appendix B. Sprites, VIC-II layout: POKE 45056+n*2,x sprite n X ($B000, $D000) POKE 45057+n*2,y sprite n Y ($B001, $D001) POKE 45072,v sprite X bit 8 ($B010, $D010) POKE 45077,v enable sprites 0-7 ($B015, $D015) POKE 45095+n,c sprite n color ($B027, $D027) PEEK(45086)/PEEK(45087) collisions ($B01E/$B01F) VIXEN has 16 sprites, so 8-15 are reached through a select window: POKE 45104,n select sprite 0-15 ($B030) then $B031-$B036 X lo / X hi / Y / image slot / color / flags POKE 45112,v enable sprites 8-15 ($B038) Screen and layers: POKE 45088,c border color ($B020, $D020) POKE 45089,c background color ($B021, $D021) POKE 45120,v tile layer on/off ($B040) POKE 45121,v tiles in front ($B041) POKE 45122..45125,v tile scroll X/Y ($B042-$B045) POKE 45136,v bitmap layer on/off ($B050) POKE 45137/45138,v bitmap pointer ($B051/$B052) POKE 45139..45141,v bitmap scroll ($B053-$B055) Input (all reads): NOTE ON THE RASTER: PEEK(45074) is there, but BASIC cannot chase it. A PAL line is 64us and one BASIC statement is far slower, so the value jumps tens of lines between reads -- an exact test never matches. Use it to tell roughly where the beam is, not to sync to a line. PEEK(45152) joystick 1 ($B060) PEEK(45153) joystick 2 ($B061) PEEK(45154)/PEEK(45155) mouse X / Y ($B062/$B063) PEEK(45156) mouse buttons L/R/M ($B064) Joystick bits are active-high and not in a compact order: 1 = down, 2 = up, 4 = fire, 8 = right, 32 = left. IF (PEEK(45152) AND 4) THEN ... tests fire on port 1. Mouse counters free-run and wrap at 256 (like the Amiga's JOY0DAT) -- subtract your previous reading to get the movement since then. Sprite images (a C64 pokes these into 6502 RAM; VIXEN keeps them in SDRAM, so they go through this window): POKE 45184,n select slot n, resets offset ($B080) POKE 45185/45186,v offset within the slot, lo / hi ($B081/$B082) POKE 45187,v one byte; the offset advances ($B083) 1bpp = 8 bytes per row, 64 rows (512 bytes). Byte 0 is the leftmost 8 pixels, bit 7 the leftmost pixel -- same order as a C64 sprite, so C64 sprite DATA can be poked straight in. 8bpp = 1 byte per pixel, 4096. Worked example: basic/test_hw.bas on the card flies the C64 balloon. Copper (one entry at a time): POKE 45169/45170,line scanline lo / bit 8 ($B071/$B072) POKE 45171,reg register id ($B073) POKE 45172..45175,v value, low byte first ($B074-$B077) POKE 45176,n commit as entry n ($B078) POKE 45177,n run the first n entries ($B079) Machine control and SID: POKE 45296,1 ($B0F0) launch the staged .RVK (the auto-typed stub's RUN) POKE 45297,1 ($B0F1) launch WITHOUT the VIH soft reset (diagnostic) POKE 45298,1 ($B0F2) SDRAM bring-up instrument (MEGA65): phase-shifter check, pattern tests, and the read/write data-eye sweep printed live -- see mega65/SDRAM_BRINGUP.md POKE 45299,1 ($B0F3) CPU-RAM test: pattern-sweeps the free expansion region (0x40000-0x68FFF, up to the stack guard) and proves the KERNAL's write shield still drops writes. <1 s, PASS/FAIL. POKE 45300,1 ($B0F4) chip-RAM write speed test: pushes 512KB through the CPU->SDRAM FIFO, prints MS + KB/S and verifies the first/last words landed (~2300 KB/s on core v119+). POKE 46080+r,v ($B400+r) SID register r (0-28), C64-style: the $D400 block relocated into the VIXEN POKE window. First sound: POKE 46104,15 volume POKE 46080,137 voice 1 freq lo POKE 46081,65 voice 1 freq hi POKE 46085,0 attack/decay POKE 46086,240 sustain/release POKE 46084,17 triangle + gate ON POKE 46084,16 gate OFF Core v0.79+: gate OFF then gate ON straight after each other restarts the note, as on a C64. (sprite position/enable and border/bg pokes: see the VIC-II-mirrored block at $B000+ in basic_test.c -- same offsets as the C64's $D000.) Learning to program the machine ------------------------------- Thirteen self-contained tutorials live in risc/tuts/ (tut1 hello world up to tut13, a five-plane parallax scroller) -- each is one small, heavily commented C file with its own Makefile, building one .rvk you load exactly like any app below. risc/tuts/README.md covers the toolchain setup (a portable RISC-V gcc tarball, no installer). Loading files ------------- HELP at Ready -> the file browser (below; on the M2M core, up to v0.93, the Help menu's "Load RVK:" / "Load BAS:" / "Load PRG:", F12). The file streams into SDRAM staging and BASIC reacts: "LOADING..." prints the moment the stream starts (the transfer takes a few seconds); a .BAS then auto-types into the editor (RUN it yourself), a .RVK prints its size and a 2-line stub -- RUN launches it. .PRG (core v0.68) is the C64-style form: the first two bytes are the load address, little-endian, and the rest is placed there. It does NOT auto-run. If it loaded at BASIC's program start ($0301) the kernel walks the line links and points start-of-variables just past the null link, so LIST shows the program and RUN starts it -- exactly as if you had typed it in. BASIC KNOWS NOTHING ABOUT ANY MACHINE CODE ABOVE THAT. A .PRG may carry assembly after its BASIC text (the classic stub-plus-code layout, e.g. 10 CALL $310), and BASIC's idea of where the program ends deliberately covers only the BASIC lines. Whatever overwrites the machine code -- a variable, a longer typed line -- is the programmer's business, which is how it worked on the machines this imitates. LOAD AND SAVE, TO A MOUNTED DISK (kernel build 41+). SAVE "TEST" to drive A: LOAD "TEST" LOAD "B:GAME" drive B: SAVE "C:GAME.BAS" a text listing in /VIXEN-32/BASIC/ (build 120+) The format is the same .PRG described above, so files move both ways between BASIC and the file browser, and LOAD does not auto-run either way. Errors: ?FILE NOT FOUND, ?FILENAME MISSING, ?NOTHING TO SAVE, ?WRITE ERROR, ?FILE TOO SHORT. HOW IT IS DONE, because it is worth knowing there is no interpreter surgery involved: EhBASIC already HAS the LOAD and SAVE keywords, and both are nothing but `JMP (vector)` through two RAM words a host system is expected to fill in (basic.asm, V_LOAD/V_SAVE at $0209/$020B). Those vectors are pointed at $BFF0 and $BFF2 -- addresses inside the VIXEN I/O page -- so the 6502 arrives there to fetch an opcode, the register READ handler performs the whole command in C, and the byte handed back is $60 (RTS). The vectors are re-installed every frame, because a cold start (and RUN/STOP+RESTORE is one) rewrites page 2 from the monitor's table. BASIC CONTAINS NO FILESYSTEM CODE. It calls the kernel jump table -- kdisk_open/read/write/close -- and the table's file entries point into the FatFs module living in SDRAM. Long filenames, mixed case and subdirectories work, because the module is built with FatFs's LFN support. DISK COMMANDS (kernel build 54+) DIR list the current directory DIR B: DIR DATA CD DATA change directory CD \ back to root CD B: move to drive B: CD print where DEL NAME delete MKDIR NAME make a directory COPY SRC DST copy MOVE OLD NEW rename/move Arguments are separated by a SPACE, DOS style, so a filename cannot contain one. A destination that names no file takes the source's name: `COPY FILE B:` and `COPY FILE DOC` (DOC being a directory) both keep it. A directory destination is DETECTED, not signalled -- the trailing slash in `COPY FILE DOC/` is optional. MOVE is a rename and stays on one disk; across drives use COPY then DEL. MKDISK GAME a blank 1.44 MB disk image (kernel build 121+) MKDISK GAME 720 a blank 720K one MKDISK writes /VIXEN-32/IMG/GAME.IMG on the SD card (the folder is made on first use, .IMG added when the name has none), labelled with the name, in the standard DOS floppy layout -- mount it from the file browser (HELP, then CTRL+A or CTRL+B). Sizes are 720 and 1440 only (?SIZE: 720 OR 1440); a size typed with no name before it answers ?NAME MISSING (build 122). An image that already exists is never overwritten (?DISK EXISTS), a drive letter other than C: is refused (?DISK IMAGES GO ON C:), and it follows the C: rule: A: and B: unmounted. A key pressed while it writes stops it and deletes the half-made image. Token $F5, trap $BFDC. VMOS (kernel build 128+) VMOS on a line of its own, at Ready ARE YOU SURE (Y/N)? Y starts VMOS, N goes back to Ready; no other key answers. VMOS takes BASIC's memory, so Y ends BASIC and the program in it. VMOS is not in the kernel's memory: it rides in KERNEL.BIN -- the kernel image with VMOS's .rvk behind it from the next 512-byte boundary (risc/sdboot: make KERNEL.BIN) -- which the core boots. Its bootstrap reads only the kernel's blocks, so VMOS costs no boot time; the command reads the VMOS part of /VIXEN-32/KERNEL.BIN into the .RVK staging area and starts it as any .rvk is started. (A BOOT.BIN, for cores up to v0.93, has the command too and reads the same KERNEL.BIN.) NOT A KEYWORD: the kernel takes the line before EhBASIC sees it, and only while BASIC waits at Ready -- typed as the answer to INPUT it is just text (the 6502's stack tells the two apart, EHBASIC_DIRECT_RET). Refusals: ?NO /VIXEN-32/KERNEL.BIN, ?NO VMOS IN KERNEL.BIN, and ?UNMOUNT A: AND B: FIRST (the C: rule). GO V20 (kernel build 136+) GO V20 on a line of its own, at Ready (spaces count for nothing, as in the C128's GO 64: GOV20 is the same) GO 20 the same as GO V20, and so is GO20 (build 146+) ARE YOU SURE (Y/N)? Y starts the VIC-20: the core's own 6502, VIC and two VIAs (core v0.95 and later), run by risc/vic20hw -- the fourth part of KERNEL.BIN, "VIC20" in its table of contents (risc/sdboot/mkkernel.py). N goes back to Ready. Like VMOS it ends EhBASIC and the program in it, costs no boot time and stays on the card until asked for. KERNEL.BIN holds NO VIC-20 ROM: the user puts their own in /VIXEN-32/VIC20/ -- KERNAL.ROM 8 KBytes the KERNAL ($E000) BASIC.ROM 8 KBytes VIC-20 BASIC ($C000) CHAR.ROM 4 KBytes the character ROM ($8000) -- and the kernel looks for all three before it asks. A missing one (?/VIXEN-32/VIC20/CHAR.ROM NOT FOUND) or one of the wrong size (?BASIC.ROM IS NOT 8 KBYTES) goes back to Ready. The rest as VMOS: only at Ready, not a keyword; ?NO /VIXEN-32/KERNEL.BIN, ?NO VIC-20 IN KERNEL.BIN, ?UNMOUNT A: AND B: FIRST. vic20hw loaded as an .rvk (b07 and later) reads the same three files and says the same on its own screen. HELP in the VIC-20 opens its game menu: the games of /VIXEN-32/VIC20/GAMES and its folders. Each game's memory is kept in GAMES/CFG/NAME.CFG; the first time a game is loaded the memory box asks for it. RETURN into a folder, or load the game DEL up a folder M the memory box for the game at the bar F1 the VIC-20 restarted to BASIC SHIFT+F1 the memory box for F1: RETURN saves it and restarts F3 fit to screen on or off F5 the Amiga mouse as two paddles on or off (core v0.96, vic20hw b18): left / right = paddle 1, up / down = paddle 2, its buttons their fire buttons F7, SHIFT+F7 the paddles faster, slower: 12% to 150%, starts at 50% RUN/STOP ESC HELP back to the VIC-20 as it was ALT + cursor keys move the picture. Only the reset button leaves the VIC-20. GO 64 (kernel build 145+) GO 64 on a line of its own, at Ready (spaces count for nothing, as in the C128's: GO64 is the same) ARE YOU SURE (Y/N)? Y starts the C64: the core's own 6502, VIC-II, two CIAs, PLA and SID (core v0.96 and later), run by c64hw -- the sixth part of KERNEL.BIN, "C64" in its table of contents (risc/sdboot/mkkernel.py). N goes back to Ready. Everything else is as GO V20: it ends EhBASIC and the program in it, costs no boot time, and KERNEL.BIN holds NO C64 ROM -- the user puts their own in /VIXEN-32/C64/ -- KERNAL.ROM 8 KBytes the KERNAL ($E000) BASIC.ROM 8 KBytes C64 BASIC ($A000) CHAR.ROM 4 KBytes the character ROM ($D000) -- and the kernel looks for all three before it asks: ?/VIXEN-32/C64/ KERNAL.ROM NOT FOUND or ?CHAR.ROM IS NOT 4 KBYTES goes back to Ready, and so do ?NO /VIXEN-32/KERNEL.BIN, ?NO C64 IN KERNEL.BIN and ?UNMOUNT A: AND B: FIRST. The MEGA65's keyboard is a C64 keyboard, key for key, and both joystick ports work as on a C64. HELP in the C64 opens its game menu: the .PRG, .CRT, .D64 and .TAP files of /VIXEN-32/C64/GAMES and its folders. The C64 stands still while the menu is open. RETURN into a folder, or start the game SHIFT+RETURN a .D64 into drive 8 without starting it (disk 2 of a game); on the disk that is in: takes it out. A .TAP the same way into the tape (side 2) INST/DEL, <- up a folder CRSR up / down the bar; CRSR left / right a page; CLR/HOME the first a letter, digit the next entry starting with it F1 switch the C64 off and on: BASIC F3 the Amiga mouse in control port 1: JOYSTICK IN PORT 1, PADDLES IN PORT 1 / 2, 1351 MOUSE IN PORT 1 / 2 SHIFT+F3 the joystick ports swapped (the MEGA65's port 1 is the C64's port 2, its port 2 the C64's port 1), or back; kept from game to game, PORTS SWAPPED on the status bar (c64hw b19). The paddles / 1351 stay in their port F5 / F7 the mouse slower / faster as paddles or a 1351: 12% to 150%, starts at 50% HELP ESC RUN/STOP back to the C64 as it was As paddles: left / right = paddle 1, up / down = paddle 2, the left button paddle 1's fire, the right button paddle 2's. As a 1351: the left button is fire, the right button up. The settings stay from game to game; a game still needs its own setting for them, as on a real C64. ALT + cursor keys move the picture, 4 pixels or 2 lines a press; ALT + CLR/HOME puts it back. Only the reset button leaves the C64. DRIVE 8 (c64hw b16). A .D64 shows in the menu as DISK. RETURN puts it in drive 8, restarts the C64 and types LOAD"*",8,1 and RUN; SHIFT+RETURN only puts it in, so a game's second disk can follow its first. The status bar shows DRIVE 8: and the disk. There is no 1541 in the core and none is needed: c64hw answers the KERNAL's own disk calls, so programs that load with the KERNAL load, and the error channel answers (73 CBM DOS V2.6 1541 after a restart). The disk is read only: SAVE writes nothing and the error channel says 26,WRITE PROTECT ON. Games with a fast loader of their own do not load. THE TAPE (c64hw b20, core v0.98). A .TAP shows in the menu as TAPE. RETURN puts it in, presses PLAY, restarts the C64 and types LOAD and RUN (what SHIFT+RUN/STOP types); SHIFT+RETURN only puts it in and presses PLAY (side 2). The status bar shows TAPE: and the tape. The core plays its pulses into CIA 1's FLAG at the C64's own cycles, PLAY and the motor on the 6510's port, so turbo loaders load as on a Datasette, in the same time. The tape stands while the menu is open, follows the motor, is rewound when the C64 is switched off and on, and lets PLAY up at its end. Read only; .TAP versions 0 and 1, up to 8 MBytes (in Zorro RAM). .CRT TYPES (c64hw b17). 0 normal 8K, 16K and Ultimax; 3 Final Cartridge III; 4 Simons' Basic; 5 Ocean; 7 Fun Play; 8 Super Games; 11 Westermann; 12 Rex Utility; 13 Final Cartridge I; 15 C64 Game System; 17 Dinamic; 18 Zaxxon; 19 Magic Desk; 21 Comal 80; 32 EasyFlash; 60 GMod2. Any other type says so in the menu and is not started: 1 Action Replay, 2 KCS Power, 9 Atomic Power and 10 Epyx Fastload among them. There is no freeze button. A new type is a change to c64hw (cart.c), not to the core. A GMod2's EEPROM (2 KBytes, its game's saves) is kept on the card as GAME.EEP beside GAME.CRT, as VICE's .eep: read when the game starts, written a second after the game last wrote it and when HELP opens the menu. "The game's save could not be written to the card" in the menu if the card refused it; it is tried again a second later. THE HELP KEY: A FILE BROWSER (kernel build 133+) The M2M-free core has no Help menu, so HELP (C65 matrix key 67) at Ready opens a browser instead -- risc/help, its own program, the third part of KERNEL.BIN, found through the table of contents in the file's last 512 bytes (risc/sdboot/mkkernel.py). The kernel reads it into chip RAM at $F30000 (kernel-module slots 3-15, out of BASIC's reach), zeroes its bss and calls it on BASIC's stack. VMOS's 63-column look and load box: the card's folders from the root down, .RVK .PRG .BAS and .IMG files only, cursor keys / RETURN / DEL, mouse with double click, and a picture (8-bit or 4-bit BMP, box 162 x 112, its colors in palette entries 37-255): NAME.BMP next to NAME.RVK; on a folder the COVER.BMP inside it (else FOLDER.BMP next to it); inside a folder its COVER.BMP for every entry with no picture of its own, [..] included (help b04). RETURN on .RVK read into staging, NEW + "10 REM RISC APP, n BYTES" + "20 POKE 45296,1" typed in -- RUN starts it RETURN on .PRG loaded like LOAD (bas_load_file) RETURN on .BAS typed in from staging a letter, digit the first entry starting with it (again: the next) CTRL+UP / DOWN a page, the selection keeps its row CTRL+LEFT / RIGHT first / last CTRL+A / B the .IMG into drive A: / B: (RETURN = A:) CTRL+SHIFT+A / B eject F1 / F3 HDMI zoom / HDMI scanlines on or off, at once and saved in CONFIG.TXT (help b06); a click on the line too F5 the commander (help b09, below); a click on the line too RUN/STOP ESC HELP back to BASIC, untouched A .BAS or .PRG picked on the card makes C: and its own folder current (kernel 148), as CD C: and CD to that folder would: a program reads the files beside it by name alone, READF 2,"FONT16.RAW",0 in /VIXEN-32/BASIC/BAS3.BAS included. Nothing is printed; CD shows where you are. While A: or B: is mounted from the M2M core's F12 menu (C: refused) nothing moves. An .RVK or .BAS comes in 32 KBytes at a time and counts up on its line, "LOADING... [ 30%]" to "[100%]" -- a game of a few MBytes takes 5-10 seconds. The cursor is off from the moment the browser closes until Ready (kernel 137). BASIC IS NOT TOUCHED. The browser switches the tile layer off and draws on its own two framebuffers; it borrows sprite channel 15 and slot 4 for the pointer (slot 4 saved and put back), runs the timer at 1 kHz for the mouse (every 20th tick still goes to BASIC's handler) and gives both back. The kernel then restores every video register from its shadows -- border, colors, layers, the bitmap pointer, sprite enable and channel 15, and since kernel 142 (for the commander) the text scroll, the tile map pointer, the font and 40 or 80 columns -- and palette 16-255 from g_pal565, its copy of the palette (VIH registers cannot be read). Cancelled, the screen is pixel for pixel what it was. Only at Ready: in a running program or at INPUT, HELP is the program's key. The browser remembers its folder and line (help_state_t in the kernel). CONFIG.TXT (kernel 134, help b06). /VIXEN-32/CONFIG.TXT holds the user's settings, one a line, NAME=VALUE in any case; ON, YES or 1 is on. The browser writes it when F1 or F3 is pressed and keeps every line it does not know; the kernel reads it once at boot, before the boot screen, and writes VIH_HDMI (0x3A000290, write-only: g_hdmi is the kernel's copy, handed to the browser as help_call_t.hdmi, HELP_ABI 2). Today: HDMI_ZOOM=ON VIXEN's 224 lines fill the HDMI height, 16:9 HDMI_SCANLINES=OFF every second HDMI line at half brightness, with zoom on or off (F3 refused it with zoom on until help b08) No file, or one over 4096 bytes: both off. Cores before v0.95 ignore the register. The 15 kHz analog PAL picture never changes. THE COMMANDER: VCMD IN 80 COLUMNS (help b09, vcmd b05; risc/help/vcmd.h). F5 in the browser opens a Norton Commander: two panels, a drive each, in the core's 80-column mode, with the browser's colors, boxes, mouse and sliders, and long file names (shown whole on the line under the panels). Its own program, part "VCMD" of KERNEL.BIN, read into chip $F30000 when it is asked for -- the browser's place: the kernel (142 on) runs it after the browser has returned, never both at once, and reads the browser in again on F10. BASIC's screen comes back once, when it is all left. The keys are the cc65 VCMD.PRG's, the moving about the browser's: F1 the next drive: A: -> B: -> C: -> A: F2 (SHIFT+F1) rename the entry at the cursor, file or folder: its name is edited in place -- LEFT / RIGHT (CTRL: the ends), HOME, DEL, SHIFT+DEL, typing goes in at the cursor; RETURN renames, ESC leaves it (vcmd b05) SPACE mark the entry (its name turns red) and move on; again: unmark. CTRL+A marks everything, again nothing. F5, F6 and F8 then work on all that is marked; with nothing marked, on the entry at the cursor. The panel's bottom line says how many and their files' bytes; another folder clears the marks F3, RETURN view a file: 1 text, 3 hex, the cursor keys, CTRL+UP / DOWN a page, CTRL+LEFT / RIGHT the ends, a slider; ESC or F3 back F5 / F6 copy / move the entry into the other panel's folder (asks); a folder goes with everything in it (vcmd b03). A move on one drive is a rename; to another drive a copy, then the original deleted F7 / F8 a new folder (asks its name) / delete (asks; a folder goes with everything in it) TAB the other panel RETURN, DEL into a folder, up a folder; letters, CTRL+UP / DOWN, CTRL+LEFT / RIGHT and the mouse as in the browser F10 (SHIFT+F9), HELP back to the browser, where it was RUN/STOP, ESC back to BASIC, untouched A copy runs 32 KBytes a step with a bar on the message line; RUN/STOP stops it and the half-made file is deleted. Marked entries are one job: one question ("Copy 12 entries to C:/X?"), one count, one bar; a name there already asks Y, N or A (A: yes to the rest of the job), N leaves that one marked; each entry done is unmarked, so after a stop the rest is still marked. A folder is counted first, then one bar runs over all its bytes; a folder of the same name in the other panel is copied into, files of the same name replaced, after asking. Stopped, what was copied so far stays. On C: nothing is written, made, moved or deleted outside /VIXEN-32/ (BASIC's own rule -- the commander checks it, the kernel's file calls do not), and /VIXEN-32/BOOT.BIN and KERNEL.BIN are never deleted, moved or written over. It draws its text in tile map 1 (whatever was there is lost) and its boxes on its own two framebuffers; tile map 0, BASIC's screen, is never touched. It mends its own screen (vcmd b04): every frame it writes its display registers again and draws one more row of both framebuffers and of the text, so a display write the board loses is back within half a second (on the board the boxes were once gone, only the text left). The panels, their folders and the cursor are kept by the kernel from one F5 to the next (vcmd_state_t). risc/help/vcmdtest_bNN.rvk runs the commander on its own, for trying it without the kernel. A: AND B: FROM .IMG FILES. With no QNICE to serve the vih_disk drives, the FatFs module serves an image file itself (kmodfat/kimg.h): mounting turns the file's clusters into a list of card sectors (FatFs's link map, up to 64 pieces), and the drive reads and writes those sectors straight on the card -- no file stays open, so a card release between commands cannot pull the disk away. Jump entries 5, 6, 7 and 23 come from the module now and fall back to vih_disk for a drive with no file (the M2M core's F12 disks). An image file in a drive cannot be deleted, renamed or opened for writing on C: (FR_LOCKED), nor mounted in both drives. The C: rule only applies to the M2M core's F12 disks now. Mounts end at reset and power-off. HOW FAST IS IT? Both figures below are MEASURED on hardware, and they are an order of magnitude apart, so which path you use matters: raw sector read 37 KB/s 13 ms/sector COPY between images 3.5 KB/s ~140 ms/sector of file data The raw figure is a boot block reading 141,388 bytes in 3.7 s, timed by the machine itself with the jiffy clock. The slow one is a 790,148-byte COPY, 3 min 41 s by stopwatch. The difference is not the drive: a copy pays for a read AND a write of every sector, plus FatFs updating the FAT and the directory as it goes. So: raw sector reads are floppy-speed -- between an Amiga drive (~25 KB/s) and a PC 1.44 MB drive (~30-45 KB/s) -- and are the right path for loading a program or streaming demo data. Copying files is ten times slower and is fine for programs and saves, wrong for megabytes. Bulk game data still belongs on the SD card via vih_fat/FatFs (~360 KB/s, and 3-4x that through FatFs on core v0.74 and later, which reads the card in bursts). DIR AND CD ARE REAL KEYWORDS, added as VIXEN extension tokens ($E6 up) in their own table, so no EhBASIC token number moved and every saved .PRG stays valid. Adding another keyword is two table lines and a routine -- see basic.asm, "VIXEN-32 EXTENSION TOKENS". Drive units: 0 = A:, 1 = B:, 2 = a hard-disk image (reserved, not built), 3 = the SD card itself. See the Chipset Reference chapter 12. WHO THIS MACHINE IS BUILT FROM POKE 45214,1 prints the notices: EhBASIC, FatFs, tinf, newlib (the 6502 emulation left the list with build 138, when EhBASIC moved onto the core's own 6502). The full text ships as NOTICES.txt with the release. VIXEN-32's BASIC is DERIVED FROM EhBASIC by Lee Davison, which is free for NON-COMMERCIAL use -- that is a condition on the machine, not a footnote, and the string is inside the shipped image as the licence asks. READF AND WRITEF: FILES AS DATA (kernel build 96/97) READF unit,"NAME",addr WRITEF unit,"NAME",addr,len A file straight into memory, and memory straight into a file -- sprite sheets, level maps, samples, high scores. unit 0 is the 6502's RAM, unit 1 is chip RAM (the full 16 MB, 24-bit addresses), and unit -1 asks the size of a file without reading it. The address is a real expression -- A, or BASE+N*4096 -- not just a literal. WRITEF needs the length, because memory has no end marker: only the program knows how much of it means anything. Results come back where a program can PEEK them: PEEK(45244-45246) bytes read, or the size for a -1 query PEEK(45247) status: 0 ok, 1 no file, 2 I/O error, 3 address refused, 4 bad unit, 5 no disk ALWAYS CHECK PEEK(45247). READF NEVER STOPS THE PROGRAM: a missing file sets the status and returns, because "is it there and how big" is a question worth asking -- and the cost is that an unchecked failure looks exactly like success, with the next line working on whatever that memory held before. The one refused address range is chip RAM's last megabyte -- the kernel module slots, where landing a file would take the disk or the network out from under the machine. Everything below is fair game, sprite slots included. The same registers work from 6502 machine code with no BASIC involved: Appendix B of the Chipset Reference documents the block. THERE IS NO DRIVE C: (build 119) A: and B: are the drives this machine has. The SD card was reachable as C: in builds 116 to 118 and is switched off again: DIR C: ?NO DRIVE C: -- ONLY A: AND B: CD C: the same, and the current drive does NOT move WHY IT IS OFF. The card can be driven by one side of the machine at a time, and A: and B: are disk IMAGES STORED ON THAT CARD, served by the other side. Any operation with C: on one side and A: or B: on the other -- a copy, a move -- needs the card held by both at once, and the hardware cannot do that: the transfer fails part way through. A drive that cannot exchange files with the drives next to it is worse than no drive at all. WHAT WOULD BRING IT BACK PROPERLY is handing the card over once per block instead of holding it for a whole transfer. Every handover needs a card reset, so it costs speed -- a decision to be made deliberately, which is why C: is a SWITCH and not a deletion: VX_DRIVE_C in risc/basic_test.c, set back to 1, restores everything described above (including the /VIXEN-32/ write jail, which never went away). Files still reach the card without a drive letter: TFTP writes there over the network, and the file browser (then F12, now HELP) loads from it. DRIVE C: IS BACK (build 120) -- REFUSED WHILE A: OR B: IS MOUNTED. DIR C: ?UNMOUNT A: AND B: TO USE C: (while A: or B: is in) That rule is what makes the C:<->A: copy above impossible to start instead of failing part way. C: holds the card for one command only, so mounting A: from F12 (the M2M core) afterwards works; the NEXT C: command is refused. READF/WRITEF answer status 1, the file API at $B120 status 11. The NETWORK.TXT read and the TFTP server do not go through the check. SAVE "C:NAME.BAS" writes a PLAIN-TEXT LISTING (what LIST shows, CR LF line ends) into /VIXEN-32/BASIC/, created on first use -- the format the file browser (HELP) types back in; LOAD reads .PRG only. Any other name, and every name on A: or B:, is the .PRG as before. DIR and CD print the card as C: (it used to come out as A: or as the filesystem's own name, SD:). READF LEARNED FOUR MORE DESTINATIONS (builds 100-105). The unit number says where the bytes land, and three of those places have no address the CPU can reach -- they are only writable through a port, which is exactly the sort of thing a command should hide: READF 2,"FONT.CHR",0 the 1bpp character set; the address is a byte offset into it, a multiple of 8 READF 3,"COLOR.CHR",0 the 8bpp character set READF 4,"TITLE.MAP",0 the screen, one byte per cell, drawn from the current position with the current colors READF 5,"DEMO.PAL",16 the palette, three bytes an entry, from the entry the address names WRITEF CANNOT GO THE OTHER WAY on 2, 3 or 5, and that is the hardware rather than a policy: the font and palette memories have a write port and no read port, so there is nothing to save. Keep your own copy. Those units return status 4. THE SCREEN, CHARACTER BY CHARACTER (build 102) A C64 pokes 1024+x for a character and 55296+x for its color, and that is how every type-in game ever written draws. A VIXEN cell is 32 bits -- character, foreground, background, two flip bits -- so it can never be one POKE. It is a cursor instead: $B0A7 column 0-39 (0-79) $B0AB bit0 flip X, bit1 flip Y, $B0A8 row 0-24 bit2 = character bit 8 (256-511), $B0A9 ink bit3 = draw on map 1 $B0AA paper $B0AC the character: WRITING IT PUTS THE CELL DOWN and steps on, wrapping to the next row 10 POKE $B0A7,0 : POKE $B0A8,5 : POKE $B0A9,7 20 FOR I=0 TO 39 : POKE $B0AC,65+I : NEXT Colors and flags STICK, so a whole row is one POKE per cell rather than five -- which at 3 MHz is the difference between a screenful appearing and a screenful happening. Reading $B0AC gives the character already there and does NOT step on, or no program could look at what it just wrote. MAP 0 IS THE CONSOLE'S AND IT WILL FIGHT YOU. The console keeps its own copy of the screen so it can scroll, and a scroll redraws from that copy -- wiping anything poked underneath. Bit 3 of $B0AB draws into map 1 instead, which nothing else touches; POKE $B046,1 then shows it. Draw hidden, then flip: that is what the second map is for. YOUR OWN CHARACTER SET (build 100) Glyphs live in the video hardware's own memory, with no CPU address at all, so this is the same uploader shape the sprites use: $B0C0 the character to define, 0-255 (writing it restarts the glyph) $B0C1 bit0 = code bit 8, bit1 = 8bpp, bit2 = 8x16 $B0CF one byte of glyph data, the offset advancing by itself $B0CE bit0 = show the uploaded font, bit1 = display 8x16 10 POKE $B0C0,65 20 FOR I=0 TO 7 : READ B : POKE $B0CF,B : NEXT 30 POKE $B0CE,1 40 DATA 60,66,165,129,165,153,66,60 Bit 7 is the leftmost pixel and row 0 comes first, exactly as a C64 character, so charset data written for a C64 maps straight across. A glyph is 8 bytes at 8x8, 16 at 8x16, 64 at 8bpp; 512 characters either way. SWITCHING TO AN EMPTY FONT BLANKS THE SCREEN, "Ready" included, because the console draws with the ROM font too. That is not a fault -- it is what a C64 does when you point the VIC at uninitialised RAM. Upload first, switch second. There is no read port: a glyph can never be PEEKed back. 512 CHARACTERS ARE A BITMAP. At 8x16 the screen is 40 x 12 = 480 cells and the machine has 512 characters, so every cell can be different: a 320x192 picture, drawn as text, with a foreground and background color per cell. tuts/basic/BAS3.BAS does exactly this. ALL 256 COLORS (build 105) Thirty-two colors exist when the machine powers on -- the 16 C64 ones and a 16-step grey ramp -- and everything above 31 is black. These four registers give the other 224 away: $B0B9 red $B0BA green $B0BB blue (0-255 each) $B0AF entry 16-255: WRITING IT COMMITS the color above 10 POKE $B0B9,255 : POKE $B0BA,128 : POKE $B0BB,0 20 POKE $B0AF,64 Components in any order, then the entry number. ENTRIES 0-15 ARE REFUSED, not discouraged: they are what the boot screen, the console and every C64-style program are drawn in, and a program must not be able to repaint them by accident. The greys at 16-31 are allowed. The hardware stores RGB565, so the bottom bits of each component go: 255,255,255 and 249,253,249 are the same white. THE BLITTER (build 106) BASIC pokes pixels at 3 MHz. The blitter fills at sixty million a second, and the gap between those two numbers is the gap between writing a game in BASIC and watching BASIC draw a rectangle. $B0D1-$B0D3 source address $B0D7/$B0D8 width $B0D4-$B0D6 destination $B0D9/$B0DA height $B0DB/$B0DC source stride $B0DF color, or the key $B0DD/$B0DE destination stride $B0D0 1 = fill, 2 = copy, 3 = copy skipping the key color. WRITING IT STARTS THE BLIT. 10 POKE $B0D4,0 : POKE $B0D5,0 : POKE $B0D6,32 : REM dest $200000 20 POKE $B0DD,0 : POKE $B0DE,2 : REM stride 512 30 POKE $B0D7,100 : POKE $B0D8,0 : REM width 40 POKE $B0D9,50 : POKE $B0DA,0 : REM height 50 POKE $B0DF,2 : POKE $B0D0,1 : REM fill GIVE IT THE STRIDE, NOT THE MODULO. The hardware wants bytes-to-skip at the end of each row, which is stride minus width; the kernel does that subtraction. A stride belongs to the surface -- 512 for the bitmap layer -- and stays put while widths change. Operation 3 skips source pixels equal to $B0DF, which is how something with a transparent background gets drawn into a bitmap. The kernel waits for the blitter to finish and invalidates the CPU cache afterwards. Both are things a BASIC program should never have to know about: the blitter writes memory behind the cache, so without that, reading a pixel back would return what was there before it was drawn. SAMPLED SOUND (build 106) Four channels of PCM, which BASIC could not reach until READF could put a sample into chip RAM. This is the other half: $B0E2 channel 0-3 $B0E5 length, in 4096-byte blocks $B0E3/$B0E4 sample start, $B0E6 rate in HUNDREDS of Hz (80 = 8000) in 4096-byte blocks $B0E7 volume 0-255 $B0E8 0 stop, 1 play once, 2 loop: ACTS 10 READF 1,"SOUND.RAW",$100000 20 POKE $B0E2,0 : POKE $B0E3,0 : POKE $B0E4,1 30 POKE $B0E5,2 : POKE $B0E6,80 : POKE $B0E7,255 40 POKE $B0E8,1 SAMPLES ARE SIGNED 8-BIT: 0 is silence and 128 is nearly full deflection. Start and length are in blocks, the same granularity as sprite slots, because a sample must be word-aligned or it drifts out of tune after its first loop -- and no emulator will show you that. Changing the rate between triggers is how one sample becomes a scale. A WINDOW INTO CHIP RAM (build 106) READF fills chip RAM and WRITEF saves it, but until now BASIC could not look at a single byte of it -- nothing generated, only loaded, and no way to read back what the blitter drew. $B0E9/$B0EA/$B0EB address, 24 bits, low / mid / high $B0EC the byte there. READ OR WRITE, and either one steps the address on by one. Stepping on a read as well as a write is deliberate: walking a buffer is the common case. Set the address again to read a byte twice. Setting it also invalidates the cache, because the blitter and the sprite DMA write chip RAM behind the CPU's back. THE BEEPER (build 103) The third voice, beside the SID and the PCM engine: one square wave, the same thing a PC speaker is, and two POKEs to use. $B0AD tone in Hz, low byte $B0AE tone in Hz, high byte 10 POKE $B0AE,1 : POKE $B0AD,184 : REM 440 Hz, and it IS 440 Hz It takes HERTZ, not a divisor. Either byte sets the tone from the pair, and 0 is silence. One voice, no volume and no envelope -- beeps, alarms and simple tunes; music with any shape to it is the SID's job. ONE BYTE (build 124) Two POKEs per pitch means the beeper plays a wrong pitch between them, so a sweep from BASIC crackles. $B09C is the whole tone in one write: $B09C 0 = silence, 1-255 = a tone: Hz = 8660 * 2^((value-255)/32) 1 = 35 Hz 31 = 68 Hz 63 = 135 Hz 95 = 271 Hz 127 = 541 Hz 159 = 1082 Hz 191 = 2165 Hz 223 = 4330 Hz 255 = 8660 Hz 10 FOR V=88 TO 162 : POKE $B09C,V : NEXT : REM a clean sweep up 20 POKE $B09C,0 : REM silence Every step is the same change of pitch, 32 steps to the octave: +32 doubles it. PEEK returns the value poked. $B09C and $B0AD/$B0AE drive the same beeper: the last write wins. WHICH KEYS ARE DOWN (build 107) GET READS THE KEYS WHILE A PROGRAM RUNS (kernel 148), as on a C64. At Ready and in an INPUT, typing edits the SCREEN -- that is what makes this a C64-style screen editor -- and only Enter feeds a line to BASIC. While a program runs, every key is the program's instead: GET returns it and nothing is typed on the screen. Letters come as capitals, RETURN as 13, and the editing keys as their C64 codes: DEL 20, INST 148, HOME 19, CLR 147, cursor down 17, up 145, right 29, left 157. Up to 15 keys wait for GET; when BASIC waits for a line again (Ready, or an INPUT), any it never took are dropped, so a key pressed for one program never answers the next. RUN/STOP still breaks, and GET never gets it: it is left for the break check, so "PRESS A KEY" cannot take it as a key (kernel 149). (Up to kernel 147 GET saw only Enter.) GET takes one key per press, though, and a game needs to know what is HELD. Three registers read the keyboard itself: $B0E0 the last key code reported $B0E1 1 while THAT key is still down $B0ED a key code to ask about (write it) $B0EE 1 if THAT key is down right now (read it) $B0E0/$B0E1 only ever describe the most recent key, so pressing a second one throws the first one's state away -- left AND up AND fire could not be asked for at all. $B0ED/$B0EE fix that: any key, any number of them, at any time. 10 POKE $B0ED,184 : IF PEEK($B0EE) THEN PRINT "1 IS DOWN" 20 POKE $B0ED,187 : IF PEEK($B0EE) THEN PRINT "2 IS DOWN" A C64 does this by scanning its keyboard matrix through $DC00/$DC01, and pays for it with ghosting -- certain three-key combinations produce phantom presses, which is why C64 games choose their keys carefully. This is a record of what the hardware reported rather than a matrix being scanned, so every combination reads correctly. THE CODES ARE C65 MATRIX NUMBERS, not ASCII and not PS/2. "1" is 184 but "3" is 136; they are not in any order you can guess. Press the key and PEEK $B0E0 to find its number -- that is what $B0E0 is for, and it beats deriving it from a keyboard diagram and being wrong. TURN THE EDITOR OFF WHILE YOU DO IT (build 109). Polling $B0EE tells a program which keys are down, but the editor is still doing its own job at the same time: every key pressed also prints itself on the screen, in the middle of whatever the program is drawing. A C64 game switches the editor off for exactly this reason. POKE $B0EF,1 keys go ONLY to $B0E0/$B0E1/$B0ED/$B0EE POKE $B0EF,0 back to normal typing RUN/STOP STILL WORKS in raw mode, and the mode ends at Ready, however the program stopped -- RUN/STOP, END, STOP or an error (kernel 149; up to 148 only RUN/STOP+RESTORE cleared it, and BAS13 broken with RUN/STOP left a keyboard that typed nothing). An INPUT inside a running program keeps it. DRAWING: CANVAS AND LINE (build 110) The blitter block is the hardware as it is -- addresses, strides, modulos. These are the same silicon with the arithmetic taken off you: CANVAS addr,stride,width,height LINE x0,y0,x1,y1,color[,thickness] 10 CANVAS $200000,512,384,224 20 LINE 0,0,383,223,1 30 LINE 0,223,383,0,2,5 : REM five pixels thick CANVAS IS SET ONCE and every drawing command uses it, so a line is only ever coordinates and a color. Used with no CANVAS at all, the canvas IS THE BITMAP LAYER: whatever $B051/$B052 points at, 384x224, stride 512. So LINE works the moment the layer is switched on, and CANVAS is what you reach for to draw somewhere else -- a hidden page you then flip to, say. COORDINATES ARE CLIPPED, not trusted. The blitter has no clipping of its own: a line running off the canvas would keep writing across whatever follows it in chip RAM -- the next page, a sample, a sprite -- and the first thing you would notice is something unrelated breaking. BASIC is exactly where off-screen coordinates come from, so LINE clips properly rather than refusing. RECT AND IMAGE (build 111) RECT x,y,w,h,color[,thickness] thickness 0 draws it SOLID IMAGE x,y,w,h,src[,sw,sh] a 64x64 image out of chip RAM 10 RECT 20,20,120,80,2,0 : REM a solid red block 20 RECT 160,20,120,80,7,4 : REM a frame four pixels thick 30 READF 1,"IMG64.RAW",64*4096 40 IMAGE 60,40,64,64,64*4096 : REM as it is 50 IMAGE 150,30,128,128,64*4096: REM twice the size, same cost AN IMAGE SOURCE IS 64x64 -- THE SAME SIZE AS A SPRITE SLOT, so slot N lives at N*4096 and one file can be used either way. BUT NOT THE SAME FORMAT. A sprite image is 1bpp -- eight pixels to a byte, like a C64's. An IMAGE is 8bpp, one byte per pixel, 4096 bytes for a 64x64 square. They are both "a 64x64 image" and they are not interchangeable; pointing IMAGE at sprite data draws noise. Color 0 is transparent in both. w,h ARE THE SIZE ON SCREEN. Give numbers different from the source and the hardware scales as it draws -- the same span engine, so a doubled image costs exactly what an unscaled one does. This is how a BASIC program gets more moving objects than the sixteen hardware sprites. The texture cache is reloaded only when the source address changes, so drawing the same image a hundred times in a frame pays for the upload once. It is also reloaded after anything else has used the cache (kernel 148): a LOAD, a program typed in from HELP, the HELP browser itself, or a READF into chip RAM. Up to kernel 147 the next IMAGE of the same source drew 64 bytes of program text along its top row -- the streak over BAS15's balls. THICKNESS IS SEVERAL PARALLEL LINES, offset across the direction of travel, because the hardware draws single pixels. The ends come out square rather than round. REAL INTERRUPTS IN BASIC (build 112) EhBASIC always had ON IRQ, IRQ ON and RETIRQ; the machine just never pulled the 6502's interrupt line. Now it does: $B10E enable: bit0 = the 50 Hz tick, bit1 = raster compare $B10F read: which sources fired since last read -- READING ACKS $B110 raster line, low byte $B111 raster line, bit 8 10 ON IRQ 100 20 IRQ ON : POKE $B10E,1 30 REM ... the program carries on ... 100 REM this line runs 50 times a second 199 RETIRQ A machine-code program patches the handler at $020D instead -- the hardware vector at $FFFE ends up there, in RAM, exactly the job the C64's $0314 does one step earlier. (Since build 138 $FFFE points at $F3F0, a JMP $020D the kernel watches: the 6502 fetching it is the moment the interrupt was taken, and the line is let go -- one interrupt a firing.) BREAKING A PROGRAM TURNS INTERRUPTS OFF, so a crashed handler cannot keep firing into the prompt. Delivery lands within microseconds of the event -- under a scanline, so a border effect sits still. For cycle-exact per-scanline work the copper is still the right tool: it is hardware, with no jitter at all. TWO THINGS IN EhBASIC THAT WILL CATCH YOU AND IS 16-BIT. "A AND 255" fails outright once A is above 65535, so a 24-bit chip address cannot be split by masking. Divide instead: H=INT(A/65536) : M=INT(A/256)-H*256 : L=A-INT(A/256)*256 RND(N) SEEDS THE GENERATOR WHENEVER N IS NOT ZERO, so RND(1) returns the same number every single time it is called. Seed once and then always ask for the next one with zero: 10 Z=RND(PEEK($B090)+1) : REM seed from the clock, once 20 X=INT(RND(0)*320) : REM ...and RND(0) from then on Line 10 is optional since kernel 143. EhBASIC never sets a seed of its own (on a real 6502 board the junk in RAM at power-on does), the boot clears the 6502's memory, and from a seed of 0 RND(0) gives 0 for ever. Now the kernel seeds it ($D8-$DB) when a key is pressed, from the raster line and the time since power-on at that moment -- never the same twice, where the boot itself takes the same time every time. Only while the seed is still 0: a program's own RND(n) is never overwritten, so a fixed seed still gives the same numbers every run. Both of these were found by writing the tutorials, not by reading the source. DIR AND COPY FROM MACHINE CODE (build 117) DIR, COPY, MOVE, DEL and MKDIR read their arguments out of the BASIC program text and report by printing on the console -- both useless to a machine-code program with a screen of its own. A register block at $B120 does the same jobs from registers instead: nineteen commands covering STAT, directory listing, MKDIR, DELETE, RENAME, DELTREE, stepwise COPY, file open/read/close, CHDIR, GETCWD, LABEL and SIZE. A command RUNS INSIDE THE POKE that starts it, so the status and the result are already there when the next instruction reads them: nothing to wait for and no interrupt to catch. Copying is the exception and is done in steps -- a copy off the card can run for seconds, and a machine that stops answering for seconds cannot draw a progress bar or be interrupted. Appendix B of the Chipset Reference has the full register table and the command numbers. VIXEN COMMANDER vcmd_bNN.prg is what that API was built for: a two-panel file manager, a drive on each side, with the function keys where they have been since 1986 -- F1 switch that panel between A: and B:, F3 view, F5 copy, F6 move, F7 make directory, F8 delete, F10 quit, TAB to swap sides, RETURN to open a directory. LOAD "VCMD_B2.PRG" RUN The build number is in the filename, so an older one is still there to go back to. It draws on tile map 1, so the BASIC screen underneath is still there when it exits, program and all. THE TUTORIALS risc/tuts/basic/ holds sixteen programs, one idea each: screen cells, a custom font, the 480-character bitmap, the hidden map, a sprite, the 256-color layer, the copper, sound, files, input, a real picture with its own palette, RECT and IMAGE, sampled sound, LINE, IMAGE as thirty moving objects, and a raster interrupt written in machine code. They ship as .PRG on a disk image, with the .BAS source beside each one and the data files they load. aztec/ is a demo rather than a lesson: the man runs at the pyramid from Aztec Challenge, it grows as he approaches (one IMAGE, rescaled every frame -- the fake 3D is a single hardware scale), spearmen throw high from the left and low from the right, and arriving swaps in the full scene with its own palette. Double-buffered, and all BASIC. A TEXT .BAS CANNOT BE LOADED. LOAD expects two bytes of load address followed by tokenised BASIC, so a text file's first two characters get taken as an address and nothing sensible happens. The .PRG files were made by typing each program in and SAVEing it. SWAPPING A DISK IN THE MIDDLE OF A SESSION (build 114, core v0.75+) Pick another image in the file browser (HELP; the F12 menu on the M2M core) and the next DIR shows the new disk. That is worth stating because it did not always: the filesystem keeps the disk's tables cached, and nothing told it the disk had changed, so listings came back as garbage names with impossible sizes until the drive was ejected and re-mounted by hand. The kernel now watches both drives and drops the cached state the moment what is in one changes. The core has to make the change visible for that to work -- replacing an image never used to blip the "mounted" signal at all -- which is what core v0.75 fixed; on an older core, eject with SPACE first and it behaves. PEEK(45330) counts the changes the kernel has seen. It exists because that number is what separated the two halves of this bug, and it costs one byte to keep. BOOTABLE DISKS (kernel build 56+) MOUNT A DISK AND IT BOOTS. If sector 0 of a disk mounted in A: carries the signature "V32B" at offset $3E, the sector is copied to $A000 and entered at $A042. No prompt, no key to hold: the disk decides. A power cycle clears every drive, so a bad boot block costs one power cycle and nothing else. ONLY A: BOOTS. The same disk in B: is just data, so a bootable disk can be listed and copied from safely. ONLY WHILE BASIC IS IDLE at Ready. A disk mounted during a running program is remembered and boots when the program ends, rather than killing it mid-run. THE BOOT BLOCK IS 6502 CODE -- 450 bytes of it (offset $42 to the end of the sector; $3E-$41 hold the signature). It reaches the drive through the sector-access registers in the POKE map: $B0B0 drive (0 = A:, 1 = B:) $B0B1-B3 sector number (LBA, low byte first) $B0B4 sector count $B0B5-B6 target address (low, high) $B0B7 bank: 0 = 6502 RAM, 1 = SDRAM staging in 512-byte units -- which is where a .RVK belongs $B0B8 write = go, read = result (0 = ok) So a boot block can load more 6502 code and JMP to it, or stream a RISC-V .RVK into SDRAM staging and hand the machine over with POKE $B0F0,1. Both are demonstrated in risc/bootdisk/, and the raw read path runs at floppy speed (37 KB/s -- the measured figure above IS a boot block). THE DISK STAYS A NORMAL DISK. Only the boot sector's code area ($3E on) is used, so the BPB survives and the disk mounts, DIRs and takes files as usual. In the .RVK example the payload is an ordinary FILE -- it shows up in DIR -- and the packer patches the boot sector with the file's first sector and length, so 450 bytes of 6502 can stream it with no filesystem code at all. Writing boot code? Two things that will catch you: $FFD2 is a C64 KERNAL address and does not exist here -- character output is JMP ($0207) -- and the console wants CR *and* LF. .RVK containers are v3 (shared/rvpk.h): per-block raw-DEFLATE compression, applied automatically by mkrvpk where it helps (typ. code shrinks to ~30-50%); the launcher inflates through the KERNAL's decompressor and verifies a checksum over the DECOMPRESSED bytes -- a corrupt or mis-inflated block can never launch. v2 files still load. Large SDRAM assets are compressed too, split by mkrvpk into pieces that fit the loader's staging window. A code block targeting BRAM may be up to 292 KB. That is NOT the limit on program size any more: a code block can target CHIP RAM instead and run from there (core v0.39), which allows megabytes -- a 1.5 MB program runs. BRAM is faster, so the usual split is hot code in BRAM and the bulk in chip RAM. See the chipset reference, "Running code from chip RAM". Networking ---------- The machine boots with the network DOWN and joins only when asked: SHIFT + POUND switch the network on (and off again) MEGA + POUND network on AND the TFTP server on (build 132+) NET link, address, gateway, DNS, lease, counters PING 192.168.5.1 round trip in microseconds PING GOOGLE.COM ...by name, once DNS is working That key is the MEGA65's own convention, and the default is deliberate: a retro machine should not join a network because someone switched it on. Once it is up, the machine ANSWERS PINGS while sitting at the Ready prompt -- BASIC pumps the stack between 6502 slices, so it stays visible on the network even while a BASIC program runs, with no effect on what is on screen (the video is hardware, and a reply costs a few hundred microseconds of a 20 ms frame). A .RVK app replaces BASIC entirely, so a game hears nothing unless it runs the stack itself. /VIXEN-32/NETWORK.TXT --------------------- How this machine gets on the network, in a file you can edit on a PC: ip: 192.168.5.77 or ip: dhcp mask: 255.255.255.0 gw: 192.168.5.1 dns: 8.8.8.8 mac: AA:AA:AA:AA:AA:A1 optional # anything starting with a hash is ignored Keys are case-insensitive and the MAC accepts any separator. With no file at all -- or no ip: line -- the machine uses DHCP and the built-in MAC, which is what it did before the file existed. THE MAC LINE IS THE POINT for anyone with two of these: the built-in address is fixed, so two VIXENs on one network would clash. Give each one its own line and they appear as two devices. An explicit dns: line WINS over the one a DHCP lease provides, because somebody who wrote it down meant it. The file lives on the SD card, so on the M2M core reading it CLAIMS the card from QNICE for a moment: while we hold it the F12 browser and any mounted disk image cannot be read. It is read once, at switch-on, and handed straight back. The ethernet line says which was used -- (NETWORK.TXT) or (NO NETWORK.TXT) -- and NET reports FROM NETWORK.TXT or FROM DEFAULTS. A silent fallback is exactly the kind of thing that wastes an evening. TFTP: putting files on the machine over the network -------------------------------------------------- TFTP ON start the server TFTP OFF stop it NET shows ON / BUSY and how many files it has moved From a PC (Windows' own client; -i means binary): tftp -i 192.168.5.69 put game.rvk tftp -i 192.168.5.69 put game.rvk A:GAME.RVK tftp -i 192.168.5.69 put KERNEL.BIN KERNEL.BIN tftp -i 192.168.5.69 get README.TXT or with tftp-hpa on Linux/WSL (netkit's tftp has no -c and defaults to netascii, which corrupts binaries): tftp -v -m binary 192.168.5.69 -c put game.rvk WHERE FILES GO A:NAME into drive A:, anywhere on it B:NAME into drive B: NAME the SD card, under /VIXEN-32/ -- subfolders allowed, so tftp/SUB.BIN lands in /VIXEN-32/tftp/ A leading slash or ".." anywhere is refused: writes from the network stay inside /VIXEN-32/. Files ARE overwritten without asking, which is the point -- re-uploading something you just rebuilt is the main use. MEASURED: 1 MB up in 16.4 s, down in 15.2 s -- about 64-69 KB/s, verified byte for byte. That is twice an Amiga floppy and far quicker than the machine's own virtual drives. THIS IS HOW KERNEL.BIN GETS UPDATED NOW. Upload it as KERNEL.BIN, read it back, compare, power cycle -- the card never leaves the machine. (The reset button on the side reloads KERNEL.BIN too.) The read-back matters: the upload overwrites the card as it goes, so a transfer that dies half way leaves a partial kernel that only fails at the next power cycle. THE CARD IS HANDED BACK when a transfer ends (kernel build 92). On the M2M core the SD card is shared with QNICE and whoever holds it locks the other out: before this, the first upload left it claimed and the F12 browser went blind until a power cycle -- so a .rvk could be sent to the machine and then not loaded on it. The server serves from the same poll that answers pings, so BASIC switching it on is enough -- no app, no .rvk. A .rvk game takes the machine and the server stops with everything else BASIC-side. An abandoned transfer is dropped after ten seconds of SILENCE (every packet resets that, so a slow megabyte is fine). What the stack is ----------------- ARP, IPv4, UDP, ICMP, DHCP, DNS and TCP, living in SDRAM as a KERNEL MODULE (slot 1, 0x40F10000) rather than in BASIC -- so BASIC carries no network code and an app gets the stack without linking one. It is reached through the kernel table, entries -34..-51. TCP (kernel build 91) is a CLIENT: it connects out, it does not listen. One segment in flight at a time, retransmitted until acknowledged, two connections at once, and nothing blocks -- connect() returns immediately and the caller watches the state. Proved on hardware by fetching example.com: name looked up, 828 bytes, HTTP/1.1 200 OK. Why stop-and-wait rather than a real window: the lossy element here is the MACHINE, not the fibre. The Ethernet receiver holds ONE frame, so a second segment sent before the first is acknowledged is a segment likely to arrive while the machine is busy drawing. Waiting costs a round trip per block -- about 20 KB/s to a server 26 ms away -- and buys a stack that cannot get its own sequence numbers wrong. Timings measured on hardware: a ping to the gateway answers in a few hundred microseconds, one to Google in about 26 ms -- the same figure Windows reports for the same host, which is the check worth doing. TWO THINGS AN APP THAT USES THE NETWORK MUST DO * RE-ARM THE CLOCK. The module holds the millisecond clock BASIC gave it, and BASIC's code is what an app is loaded OVER. Poll the stack before replacing that clock and the machine jumps into the app's own code: it freezes so completely that even the reset key does nothing, and only a power cycle recovers it. Read the addressing back with net_info(), the MAC from the Ethernet registers, and call net_up() again with a clock of your own. * PUT THE RESOLVER BACK. That same call clears the DNS server the lease provided, so a server named rather than numbered becomes unreachable for a reason nothing on screen explains. Call set_dns() after it. FOUR THINGS THAT WILL BITE ANYONE EXTENDING THIS * An Ethernet frame must be at least 60 bytes. Our first pings carried a 16-byte payload (58 bytes total), vanished without being counted anywhere, and the machine could answer pings it could not send. * The PHY needs a second or two after being enabled. Anything sent immediately -- a DHCP DISCOVER, say -- goes into a dead cable. * Ask more than once. The first DHCP DISCOVER after link-up was lost every time even with PortFast on the switch. * Resolve ARP before sending to an off-network address, or the first send reports "ARP in progress" and callers read it as a failure. Network Pong: the first game that plays across the wire ------------------------------------------------------- PONG_BNN.RVK on the SD card, started from the file browser (HELP) like any other .rvk. 1 one player, against the machine. No network needed. 2 two player, against whoever else joined the server. RUN/STOP leave a game, back to the menu The mouse moves your paddle -- the machine has no paddle port, and the mouse counters are the analogue input it does have. First to 9. NOBODY HOSTS A GAME. Both players connect OUT to a small server (it runs on a PC, a Linux box or a VPS: tools/pongserv in the source tree), which owns the ball and puts the first two who ask into a match. That is what lets two people play through two routers with no forwarded ports. The opponent can be another VIXEN, a PC (tools/pongpc), or the bot that ships with the server. TWO PLAYER NEEDS THE NETWORK UP FIRST -- SHIFT+POUND at the Ready prompt, because the machine boots with it down. The game says so rather than switching it on behind your back. The server's address comes from /VIXEN-32/TFTP/PONG.TXT, beside the game: server: pong.example.com a name, or server: 192.168.5.102 an address port: 7777 A NAME IS LOOKED UP WHEN YOU PRESS 2, and needs DNS -- which DHCP provides, or the dns: line in NETWORK.TXT. A name is what you want for a server on the internet, whose address may change under it; an address is what you want on your own network, and needs no DNS at all. A name that will not resolve is reported separately from an address that will not answer: one is a DNS problem and the other a server problem. The menu shows the address it read and whether it came from the file or the built-in default, so a machine that cannot connect says where it was trying to connect to. Send a new file over TFTP whenever the server moves. While joining, WAITING FOR AN OPPONENT means the server answered and nobody else has arrived; NO ANSWER FROM ... means nothing is at that address at all. UDP reports neither failure by itself, which is why the two are spelled out differently. WHY IT DOES NOT STUTTER. The whole court is sent 50 times a second as a complete snapshot -- never a difference from the last one -- so a packet missed while the machine is drawing costs one frame of smoothness and nothing else. Your own paddle is drawn from your own mouse and only the opponent's comes off the wire, so the network is never felt as the machine ignoring your hand. The BBS: dial the board ----------------------- TERMINAL_BNN.RVK in /VIXEN-32/network/, started from the file browser (HELP). (It was called BBS_BNN.RVK up to build 16 -- it is a terminal, and the board is the BBS.) The network must already be up -- SHIFT+POUND at the Ready prompt. It dials the VIXEN-32 board (vixen-32.mooo.com), with the handshake sound a modem made, then CONNECT 1200 -- and the board really does arrive at 1200 baud: you watch the logon art paint itself in, exactly as it felt. The speed is the sysop's setting, announced by the board; the terminal just obeys. New callers pick a username and password at the prompt. The board is the server: art, menus, chat -- all composed there and sent as standard ANSI text, so it can grow without this .rvk ever changing. On it today: multi-user CHAT, WHO IS ON, three MESSAGE BASES, a FILE AREA, STATS drawn as a chart, and UPDATES for the machine itself -- and eight lines, so a ninth caller gets ALL LINES ARE BUSY, which was always half the experience. Anything that speaks telnet can call the same board. FILES: [F] gives the areas -- GAMES, DEMOS, UTILS -- then a list, then a confirmation, then the file. A DOWNLOAD IS NOT PACED: the 1200 baud is a way of drawing text, not a property of the line, so the board frames the transfer and sends it as fast as the wire manages while the terminal stops rendering and writes straight to the card, counting 0% to 100%. Files land in /VIXEN-32/DOWNLOAD/, which the file browser can then run. Every transfer carries a checksum, and a file that does not add up is reported rather than kept. UPDATES: [U] compares this machine against the board. The terminal announces its kernel build and its own when it connects, so the board can mark what is OUT OF DATE and say in words which number to press. A kernel lands as /VIXEN-32/BOOT.TMP and becomes BOOT.BIN only once the checksum matches -- a half-written kernel means pulling the card -- and a new terminal lands in /VIXEN-32/network/ beside this one. NOTHING IS EVER PUSHED: the download is a key you press. While a machine is behind, the menu is the update and nothing else: [U] to fix it, [G] to hang up. The terminal understands the ANSI that matters (clear, position, the 16 colors as a real palette, and the CP437 block characters art is drawn with), sends every keystroke raw with no local echo -- the board echoes, which is how a password stays hidden -- and RUN/STOP hangs up. The board's address is BUILT IN from build 18 on: vixen-32.mooo.com, port 2323. It is a name the sysop owns, so if the machine it runs on moves the name follows it -- there is nothing on the card to keep in step, and nothing to have gone missing when the terminal will not dial. (Building with -DBBS_CFG_FILE brings back the old /VIXEN-32/NETWORK/BBS.TXT reader, for a second board.) IRC: the machine on a real chat network --------------------------------------- IRC_BNN.RVK in /VIXEN-32/network/, started from the file browser (HELP) like any other .rvk. The network must already be up -- SHIFT+POUND at the Ready prompt. It connects, registers, joins one channel and shows what people say. The bottom row is yours: type and press RETURN. A line beginning with / goes to the server as a command with the slash removed, so /join #channel, /nick newname, /msg someone hello and /quit all work. RUN/STOP leaves. Configured by /VIXEN-32/NETWORK/IRC.TXT, beside the .rvk: server: irc.libera.chat a name, or an address port: 6667 nick: vixen32 channel: #vixen-32 NO TLS. The server must accept plain connections on 6667 -- Libera, IRCnet and EFnet still do, some networks have stopped. A TLS library is bigger than this machine's entire BASIC, so that is a limit rather than an unfinished corner. If the connection drops it counts down RETRY IN 60 and reconnects itself. That minute is deliberate: a session ended with the power switch rather than RUN/STOP is still open as far as the server is concerned for a few minutes, and reconnecting at once fails in a way that looks like a ban but is only impatience. C64-style full-screen editor ---------------------------- Typing edits the SCREEN (shadow buffer), not BASIC. Enter feeds the whole physical line under the cursor to EhBASIC with echo suppression -- so LIST, cursor up, overtype, Enter re-enters the line. INPUT MARK: every byte BASIC prints records where its output ended. Enter on that same row feeds only the text AFTER the mark -- this is why prompts ("Memory size ?", INPUT) don't get fed back into BASIC. Enter on any other row feeds the full line (that's the screen editing). LOGICAL LINES (kernel build 18+). A line may be 80 characters, laid across two screen rows, exactly as on a C64. con_cont[] marks a row as the CONTINUATION of the one above -- set when the cursor ran off the right edge, cleared when something printed a newline. Enter submits the whole logical line, so LIST, cursor up onto a long line, edit, Enter re-enters all of it. A line stops at TWO rows: run off the end of the second and a new logical line starts, which is what keeps DEL and INST from dragging unrelated lines around. Trailing spaces come off the END OF THE LINE, not per row. Trim per row and a shrunken two-row line gets stored padded to 40 characters; LIST then prints exactly 40, the row wraps by itself, and every LIST shows a blank line under that line forever. INST/DEL (build 23+) also work on the logical line: DEL pulls the rest of the line left, INST pushes it right and REFUSES once the line is full rather than dropping the last character off the end. Typing off the end of a row pushes the lines below DOWN to make room -- but only while typing; BASIC printing must keep flowing, or LIST would shuffle the screen about as it went. The C64 "insert mode" (control codes becoming reverse graphics until the opened space is filled) is deliberately NOT copied: that is where the unprintable characters in C64 listings come from. CURSOR KEYS wrap at the screen edge on any line, empty ones included, and cursor-down on the bottom row scrolls. Moving the cursor never joins two lines into one logical line -- only typing or printing past the edge does. 80 COLUMNS (kernel build 141+). ESC then X switches between 40 and 80 columns, as on a MEGA65. 80 columns is the core's hi-res text (core v0.95): the same 25 rows and the same characters, half as wide; the border, the bitmap layer, the sprites and the 15 kHz PAL picture on a 1084S are exactly as in 40. The machine always boots in 40. - Into 80 the screen stays where it was, on the left half, cursor and all. A line that wrapped onto two rows in 40 becomes one row of 80 (the rows under it move up one), so RETURN on it still hands BASIC the whole line. - Back to 40 the screen is cleared: 80 columns do not fit in 40. - In 80 a line is one row: the same 80-character limit, INST refuses once the row is full, DEL pulls the rest of the row left, and typing off the end of the row starts a new line on the row below. - RUN does not switch: a program prints in whichever mode the screen is in. RUN/STOP + RESTORE keeps the mode. HELP shows its browser as always and comes back to 80 columns; VMOS, GO V20, GO 64 and every .RVK start in 40 as before. - The cursor POKEs ($B0A4, and $B0A7 for single cells) take columns 0-79, and a whole screen read with READF counts 80 cells a row. - ESC on its own still breaks a running program; at Ready EhBASIC ignores it. Any other key between ESC and X and the X is just an X. EhBASIC quirk: leading spaces of an input line are skipped (teletype convention, not a bug) -- and they are skipped WITHOUT BEING ECHOED, which matters here: Enter asks for the next N printed characters to be swallowed as the echo of a line already on screen, so a line typed with leading spaces echoes short. The residue is dropped at the newline that ends the echo; without that, " LIST" answered "eady". EhBASIC build pipeline ---------------------- risc/ehbasic/ pristine clone of Klaus Dormann's EhBASIC 2.22 risc/ehbasic/patched/ upstream's patched sources (the ones we build) risc/ehbasic/build/ Kowalski -> 64tass syntax conversion: [expr] -> (expr), .byte -> .text, bare .end tools/64tass assembler (Ubuntu package, extracted w/o root) Build: cd risc/ehbasic/build && ../../../tools/64tass -q -b min_mon.asm -o ehbasic.bin (16 KB image, $C000-$FFFF) risc/ehbasic_rom.h the image as a C array (regenerate with the python snippet in the repo history, or xxd -i) RISC-V memory map while BASIC runs (Murax, 512 KB BRAM @ 0x0) ------------------------------------------------------------- 0x00000000 +----------------------------------------------+ | Reset jump + low page | | 0x0000C BL_LOCK write-protect map | | 0x00020 trap vector (mtvec) | | 0x00024 IRQ common vector ($0314-style) | 0x00000100 +----------------------------------------------+ | .text basic_test code (~16 KB): | | console, keyboard, screen editor, | | the 6502's trap handlers (build 138; the | | fake6502 CPU core before) | 0x0000400C +----------------------------------------------+ | .rodata (~19 KB): | | EHBASIC ROM IMAGE (16 KB, copied into the | | 6502 at boot), scancode tables, strings | 0x00008D34 +----------------------------------------------+ | .bss (~73 KB): | | con_shadow (80x25 screen buffer, 141 on) | | (up to build 137 also ram[65536], the whole | | 6502; since 138 that is the core's 64 | | KBytes at 0x000C0000) | 0x0001B253 +----------------------------------------------+ | free RAM (~315 KB) ... stack grows down | | from 0x6A000 (incl. the 0x40000+ expansion | | half) | 0x0006A000 +----------------------------------------------+ | compressed BASIC payload (72 KB, to 0x7C000; | | it took over the old 24 KB KERNAL reserve | | at 0x76000) -- ordinary free RAM once BASIC | | has booted | 0x0007C000 +----------------------------------------------+ | KERNAL work stack (8 KB) | 0x0007E000 +----------------------------------------------+ | KERNAL (8 KB, hardware write-protected) | | 0x7FF00 kernel jump table (64 entries) | 0x00080000 +----------------------------------------------+ THE JUMP TABLE IS ANCHORED AT THE TOP AND GROWS DOWNWARD, which is the part of the C64 KERNAL's design that mattered: entry n is at 0x80000 - 4*n, so entry 1 is 0x7FFFC and entry 16 is 0x7FFC0 no matter how many entries exist. Adding a call never moves an existing one -- the reason IOBASE stayed at $FFF3 from the VIC-20 to the C128. The 0x7FF00 floor is a linker reservation (64 entries today), not part of the interface. -1..-4 reserved -5..-7 disk_read_sectors / write_sectors / status (kernel) -8..-11 read_file / write_file / file_exists / file_size -12..-14 dir_open / dir_next / dir_close -15 delete -16 uncompress -- the original entry, where it has always been -17..-21 open / read / write / seek / close -22..-23 free / sectors -24..-27 rename / mkdir / label / release -28..-31 reserved; -32 onward is the next module's The sector entries are the kernel's own code (vih_disk.h). The file entries are pointers copied out of the FatFs kernel module at start-up; they stay zero if that module is missing, while the sector ones keep working. There is deliberately NO magic word and NO version word, and the wrappers do not check for an empty entry: a program that calls a service this kernel does not have jumps to zero and dies, exactly as a bad JMP through the C64's table did. KERNEL MODULES LIVE IN SDRAM, NOT IN BRAM. The last megabyte of chip RAM is sixteen 64 KB slots; FatFs is slot 0 at 0x40F00000 (the CPU's cached view of chip 0xF00000) and the kernel image carries it as a third block. A module's call table is the first thing in its image, so a slot address is fixed and the module grows upward inside it. See risc/kernel_modules/kmodfat/. MMIO (not RAM): 0x3A000000+ VIH bus (tiles, blitter, keyboard 0x190...) 0xF0000000+ GPIO, Murax timer (addresses from the 2026-07 build; .bss symbols shift as code grows -- `nm basic_test.elf | grep " ram"` gives the current 6502-RAM address) 6502 memory map (the core's 64 KBytes, build 138) as basic_test builds it ------------------------------------------------------------------------- $0000 +----------------------------------------------+ | Zero page -- EhBASIC working variables | $0100 +----------------------------------------------+ | 6502 hardware stack | $0200 +----------------------------------------------+ | EhBASIC vectors (CHRIN/CHROUT/LOAD/SAVE -- | | patchable!) + IRQ/NMI RAM vectors + buffers | $0300 +----------------------------------------------+ | BASIC program + variables + strings | | (to $AFFF -- what "Memory size ?" found) | $B000 +----------------------------------------------+ | VIXEN I/O page, TRAPPED (the POKE map, the | | $BFxx C calls behind LOAD, SAVE, DIR ...) | $C000 +----------------------------------------------+ | EhBASIC 2.22 ROM (16 KB, ROM pages -- POKEs | | bounce off) | $F000 | +- $F000-$F3FF console page, TRAPPED: | | | $F001 write -> console CHROUT | | | ($0A = newline, $0D ignored) | | | $F004 read -> keyboard CHRIN | | | (ASCII from the key queue, 0 = none) | | | $F3F0 the IRQ gate (JMP $020D) | $FFFA | +- vectors: NMI $FFFA RESET $FFFC IRQ $FFFE| $FFFF +----------------------------------------------+ The core's page map makes each 1 KByte page RAM, ROM or TRAPPED. A 6502 access to a trapped page waits, in the middle of its instruction, until the kernel has run the register's handler and answered -- that's how $B000 and $F000 reach the console, the disks and the chips while the 6502 runs everything else on its own at 25 MHz. EhBASIC's memory count at a cold start is stopped at $B000 by the kernel (up to build 137, by a byte at $AFFF), so FRE(0) is one byte more than before. Planned: the C64 compatibility map (not yet built) -------------------------------------------------- $0400-$07E7 screen RAM, unified with the console shadow buffer (POKE 1024+40*Y+X,code; C64 screen-code translation) $D800-$DBE7 color RAM -> per-cell tile fg color $D020/$D021 border / background color (POKE 53280,2!) $D400-$D41C SID registers -> vih_sid passthrough (ALREADY AVAILABLE today at $B400-$B41C / POKE 46080+, see the POKE reference; $D400 stays the future full-compat alias) $D000+ sprites; new VIXEN-only addresses for the blitter Screen is 40x25, same as a C64. It always was 25 rows on screen; the console only claimed 24 of them until kernel build 21.