***** VIRTUAL V 4/8/89 ***** (An Early Release) By Jonathan Green -= Public Domain =- Document For: VM4-G.BIN VM4-G.ASM VM2-G.BIN VM2-G.BIN General Stuff ============= VM4-G will make your 512K Color Computer act like four independent 128K CoCos (virtual machines). VM2-G will make your CoCo act like two 128K machines, leaving the balance of the memory for RAMdisk or whatever. To run either program, load the program (LOADM"VM4-G" or LOADM"VM2-G") and type EXEC. It takes a few seconds to install, printing >VM1 when done instead of the usual OK prompt. Press SHIFT/BREAK (both keys at the same time) to switch to the next virtual machine. The prompt will tell you wich virtual machine you are in. You can switch virtual machines at any time. (Wait for the disk drive to stop before switching, else the drive won't get a "turn off" command.) Anything that is in the first 128K of memory will be copied to all virtual machines. For instance, if you load and install a RAMdisk before loading and executing VM2-G, the RAMdisk driver will be copied to all virtual machines. Possible Problems ================= These programs are new and have not been tested for every possible bug. But they have worked fine for everything I've tried. So far. Please use with caution and consider that crashes can be caused by the conditions described below and not necessarily by a bug. Virtual machines are fragile. A number of things can cause a crash, most notably a reset invoked by software or by pushing the reset button. If you add a patch to make it reset-proof, (perhaps with a special hard reset command so you can reset the machine without turning it off), I'd be grateful if you sent the source code. Leave messages to "Big Jon" on "Murray's Hidey-Hole" (315) 668-8929 (24 hrs. 8/1/N 300/1200/2400). Also, a message to the sysop or uploads should find me. Below are some conditions that may cause problems sometimes, but not necessarily always. Most well-written programs, Basic or machine language, should work. ++ A reset, software or hardware invoked. For instance, Telewriter 128 won't work in a virtual machine. I think it does a partial reset, but I haven't looked. ++ Any program that modifies the POLCAT keyboard reading routine or modifies the vectors to POLCAT. Also any program that handles its own input, bypassing POLCAT. The WEFAX program does this. ++ Any program that won't fit in 128K ++ Any program that directly addresses the hi-res screens. DISKPEEK does this. It will only work in VM1 which uses the same memory locations as a standard 128K CoCo. ++ Any program that writes to disk and leaves the disk file open when you go to another virtual machine. The disk directory is not updated until the file closes, and another virtual machine could overwrite the last data written. ++ Any program which has a special use for the SHIFT/BREAK combination. ++ Any program which uses the extra, unused space in Super Extended Color Basic. This program lives there. This is the memory area where you'll find the values for the picture you get when you press reset while holding down the ALT and CTRL keys. ++ Any program that tinkers with system parameters such as the GIME and particularly the MMU and MMU maps. Such programs won't always cause problems, though. ++ Any program which directly addresses an MMU block of RAM (DAT) which is outside the 128K allocated to the current virtual machine. Or even addresses an MMU block within the current virtual machine by direct reference rather than by offset to a current MMU block (except in VM1). How It Works ============ The VM programs are composed of three basic parts: 1) the Startup routine, 2) the Hotkey intercept routine, and 3) the Context Switcher. All routines are loaded to their respective RAM space by the LOADM command (multiple ORGs). Startup loads at $6000, Hotkey at $FA77 and Context Switcher at $FA84, immediately following Hotkey. In a nutshell, the whole Color Computer operating system resides in and uses only the 128K of memory that comes with the basic CoCo 3. In the 512K CoCo 3, the standard CoCo system cannot directly make use of the other three 128K blocks of memory. The Startup routine copies the 128K memory where the operating system lives to the other three 128K blocks of memory, making some changes along the way. Essentially, you wind up with the original operating system and three copies. The Hotkey routine checks to see if the SHIFT/BREAK key combination was pressed every time the operating system scans the keyboard. If that combination was pressed, Hotkey jumps to the Context Switcher routine. Context Switcher gracefully takes the current 128K out of the CoCo's memory map and substitutes the next 128K block. This will place you into another copy of the operating system. Since each operating system stays within its own 128K memory block, it's like switching to another 128K CoCo. Context Switcher is also responsible for restoring whatever video screen was in use the last time that virtual machine was active, and returning control to the exact spot the program (or the operating system) was at when the virtual machine was exited. Startup Routine --------------- Startup is invoked by typing EXEC and enter. You don't need to specify $6000. The last five bytes of a program assembled by EDTASM+ will be FF 00 00 00 00. The last two bytes will specify where the program will start when just EXEC is entered. Use a disk editing program like DISKPEEK to change these. Startup performs the following operations: 1) Build a stack that Context Switcher will pull the first time a virtual machine is run. The idea is that the first time you switch into a virtual machine, it will think it is at the end of the Startup routine and drop back to the Basic command mode. (Context Switcher will restore the registers and pull the return address.) 2) Stack an image of $FF22 for the same purpose. $FF22 is the old PIA1 PB address. It connected to the VDG control lines CSS, GM0, GM1, GM2, and *A/G. The GIME preserves this for compatibility. The value at $FF22 is used to determine/reset VDG screen modes on a context switch. 3) Save the S stack pointer to local RAM so the Context Switcher will know where the stack is. 4) Change vectors to POLCAT so keypresses will be intercepted by Hotkey. 5) Change POLCATs odd-key lookup table so it will recognize the SHIFT/BREAK combination. 6) Change the prompt from OK to >VM1 (other numbers will be substituted for 1 later). 7) Get rid of that disgusting flashing block cursor and slow the cursor blink rate. 8) Set RAM at $FExx to not be constant, else cursor location, etc. is screwed up. 9) Copy MMU blocks $30 through $3F across all blocks (or just $20 - $2F for VM2-G). 10) Patch inappropriate fixed references in each virtual machine. A) Screen vertical offsets B) Fixed value references to MMU blocks C) Change number in prompt for each virtual machine Hotkey Routine -------------- Hotkey does the following: 1) Jump subroutine to POLCAT. 2) Return to calling program if no key pressed. 3) If a key was pressed, checks if it was SHIFT/BREAK. 4) If it is, jumps to Context Switcher. 5) Else returns to the calling program. Context Switcher Routine ------------------------ Context Switcher (CONSWI): 1) Stack registers A, B, X, Y, CC, U, DP 2) Saves the value at $FF22. 3) Saves the S stack pointer to local RAM. 4) Move the current virtual machine out of memory and the next one in. 5) Restores the palette register for this virtual machine (resets GIME registers to the current palette, not the default). 6) Restores the current hi-res text screen. 7) Restores the current hi-res graphics screen if in use. 8) Preclears the VDG display offset registers and the VDG mode registers so the program only has to set what's needed. Saves space. 9) Retrieve $FF22 value and restore it. Holds VDG values. 10) Test bit 7 of $FF22 to determine the VDG mode (bit 7 is *A/G) 11) If VDG text screen is active, restore it. (Set VDG mode and VDG display offset) 12) If VDG graphics is active, restore it. A) Get value at $BA and set VDG display offset, F0 to F6. $BA is the most significant byte of the current VDG graphic page address. The first seven bits map to F0 - F6. See the SAM data sheet for more. B) Retrieve the value at $B6. This is PMODEs current argument. Set the VDG mode accordingly. 13) Restore registers A, B, X, Y, CC, U, DP 14) Pull the program counter from the stack and continue where you left off the last time you were in this virtual machine (RTS). Hacking This Beast ================== I've included the commented source code for your hacking convenience. Excessive hacking is encouraged. I ask only three things: 1) PLEASE document your changes. And change the name from VM4-G to VM4-something else. That way we all know more-or-less what we have. And with the changes documented, enhancements can be made and bugs fixed much more easily. Besides, it's an ego trip to put your name on a good hack. 2) PLEASE! PLEASE! PLEASE! distribute the programs with source code. I have some neat public domain programs that could readily be made better. If only I had the source code. It would take too much time and effort to disassemble and reverse engineer them. 3) Make an effort to debug things and put notes about what could go wrong in the document (you do document at least a little, don't you?). Of course you're not gonna test for six months before you give it away, but do try to catch/fix/warn about the obvious stuff. There's more than enough junky public domain stuff out there now. -- Enjoy!