Tutti II: The Tape-Enabled Tomy Tutor Emulator

Something old becomes something new

Tutti II is not designed to replace MESS's Tutor driver, which currently has the best 9918ANL and DCSG video and sound emulation, and is the only emulator to support cartridge images. If you're just looking for something that plays Traffic Jam, for example, this is not the emulator you want.

Instead, Tutti II is a programmer's emulator for hacking the Tutor on its own terms. Besides being currently the only emulator that reliably loads and saves to emulated cassette -- using XTOMYDEV-format bitstreams which can be transferred to and from a Data Recorder and then the real Tomy Tutor -- it also offers the excellent TutorEm debugger, a turbo processing mode and the ability to snapshot the running system. Tutti's cassette acceleration reads and generates bit-exact bitstreams that are perfect representations of the computer's output in just seconds, even on slow systems.

Tutti II is available under the New BSD license, as reproduced below:

Copyright © 2003, Ian Gledhill.
"ALU core derived from code originally written for the MAME project by Edward Swartz, initially converted for MAME by M. Coates, updated by R. Nabet. Conserved portions copyright © 1997-2017 MAMEDev and contributors."
Copyright © 2015-2020 Cameron Kaiser.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright
• notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright
• notice, this list of conditions and the following disclaimer in the
• documentation and/or other materials provided with the distribution.
• Neither the name of the nor the
• names of its contributors may be used to endorse or promote products
• derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

What Tutti II currently supports (and doesn't support)

• Any Mac running 10.4 or higher (PowerPC or Intel) through Catalina
• Full 9995 emulation
• Full SN76489AN sound emulation
• Highly compatible 9918A video emulation
• Full accelerated support for cassette (to and from XTOMYDEV bitstreams) in both GRAPHIC and BASIC mode
• Built-in debugger
• Stand-alone ROM disassembler utility (dutti)
• Basic joystick support
• Built-in "snapshot" freeze facility
• Turbo mode for balls-to-wall processing

• Windows, Linux or other operating systems. That said, 2.2 has Win32 code and I have done limited testing of it, so a Windows port may be available soon. Since Tutti II is also based on SDL 1.2, it should be very portable to many other systems and I would love to accept your ports assuming they do not break the core Mac port. You will need to add the system dependent portions, such as the GUI and tape and file I/O.
• Multiple joy controllers.
• Many interrupt locations are still not understood. Because of this, the 9995 subsystem actually traps execution at certain locations and simulates the operation instead.
• Other ROMs such as the Pyuuta and Pyuuta Jr. systems. I would like to support these, but those same system integration traps expect certain code entry points. The same emulator core could be used with modification for these different points once they are disassembled.
• Cartridges.
• I/O or parallel port. (Emulating the printer port shouldn't be hard, though.)

Using Tutti II

The Tutti II application encapsulates the necessary ROMs and all libraries, so just start it up. Because Tutti II includes copies of the Tomy BIOS, legally you can only use this emulator if you are entitled to do so, such as by already owning a Tomy Tutor. The Tutor 256x192 display will appear.

The Tutor keyboard is fully emulated in its original positions (keyboard layout permitting). That means double quotes on SHIFT-2, parentheses on SHIFT-8/9, equals sign on SHIFT-0, etc. The handaku (°) key is on the plus/equals key, and the underscore is on the tilde/backtick key. In addition, the Tutor puts the colon key next to the semicolon key.

With respect to Tutor-specific keys, LOCK is mapped to LEFT CONTROL, MOD to RIGHT CONTROL or RIGHT OPTION or keypad ENTER (to faciliate laptop layouts that may be missing some of these keys), and MON to backslash. As a convenience, DELETE is also mapped to the left arrow key so that you can (sort of) backspace, and both SHIFT keys are mapped to the Tutor's single SHIFT key.

Tutti also emulates a single joystick on the numeric keypad. The 8-4-5-6 inverted T sends up, left, down and right respectively, with 0 for SL and "." (dot) for SR.

Tutti also defines certain specific keys for special functions, which you can also access from the pull-down menus:

• Command-R resets the emulator. Any unsaved program or data is lost.
• Command-V pastes what's on the clipboard into the emulator as keystrokes. The emulator is smart enough to toggle the ALPHA LOCK to support lower case and pasting works in both GBASIC and BASIC modes. Most characters are transparently converted, assuming there is a Tutor equivalent. Characters the emulator cannot translate are emitted to standard error (and/or the system console depending on how you run the emulator). Be sure ALPHA LOCK is enabled (i.e., the default uppercase), or the emulator may become confused with mixed case text.
• F1 launches the integrated debugger (at the next available safe instruction, which may not necessarily be the spot of the foul). By default, the current instruction is displayed with the contents of memory, the three CPU registers, and the 16 workspace registers (as referenced by WP). While in the debugger, you can then do the following:
  • E exits back to normal execution.
  • F1 single-steps through code in the debugger.
  • F2 resumes execution automatically, but in the debugger. To stop, press F1 again.
  • F7 toggles emitting the instruction stream to standard output, which you can monitor depending on how you've started the emulator.
  • The arrow keys scroll the memory display (by default the scratchpad RAM at >F000). PAGE UP/DN jump bigger jumps.
  • By default, CPU-space is displayed (what the 9995 sees). To see VDP RAM and registers, press V. To return to CPU memory and registers, press C.

• F5 saves the current state of the emulator to a file. A file picker will appear to select the filename. This is not the same as saving to emulated tape (see below).
• F6 loads the current state of the emulator from a file. A file picker will appear to select the filename. This is not the same as loading from emulated tape (see below). Picking a file that is not an emulator state or is corrupted will likely be deleterious to your session. Unlike tape loads and saves, a saved emulator state file is specific to the endianness of the host that generated it: you cannot restore a saved snapshot made on a Power Mac on an Intel Mac, and vice versa.
• Command-B toggles the speed throttle ("Turbo Boost"). When turbo is off (default), Tutti II emulates the Tutor roughly at its original clock speed, inserting nanosleeps between instructions as necessary. When turbo is on, no nanosleeps are inserted, which unthrottles the clock speed; if IRQ 3 is also decoupled (next option), the system won't wait for screen updates either. Useful for slow code. This mode is automatically turned on and off for tape operations (see below).
• Command-L toggles locking to IRQ 3. When locking is on (default), an appropriate number of CPU cycles are allocated to each frame. When locking is off, the CPU is decoupled from the system clock and the IRQ is activated as rapidly as possible. This makes the emulated Tutor more responsive to keyboard input and certain other tasks, but causes system sounds to run too quickly and may interfere with some programs expecting exact timing, and some keys may repeat too easily. This mode is automatically turned on and off for tape operations (see below).
• Command-S stops the emulated tape if the emulator has not detected the end of data. Normally this isn't necessary (see below) and this option is typically disabled.
• Command-Q exits the emulator.
  

Tape operations

Similarly, if you attempt to LOAD a file from within the emulator, the file picker will appear to select which XTOMYDEV bitstream you will use as emulated tape input. If you give a filename argument to the LOAD command, the Tutor will scan the bitstream for that filename specifically; if no filename is given, the Tutor loads the first file it finds, which is usually what you want because if the filename is not found, an error message will appear in the emulator. In GRAPHIC mode, the filename is required but the emulator doesn't care (see Known bugs).

Tape operations function identically in both GRAPHIC and BASIC modes, and Tutti II can detect tape activity in both environments. The tape acceleration is extremely quick if I do say so myself. Even on my relatively slow 1GHz iMac G4, a GRAPHIC LOAD or SAVE takes only about three seconds; it's practically instantaneous on my Quad G5 and my i7 MacBook Air. Compare this to over six minutes on a real Tutor!

Typically tape operations are automatically stopped and started by the emulator for you while Tutti II monitors tape IRQ activity. However, if the emulated Tutor reacts badly to a tape operation, or the emulator fails to detect that a tape operation is finished, you may need to stop the emulated tape with Command-S to regain functionality.

The dutti disassembler

Known bugs

Other than what Tutti II doesn't yet support (cartridges, multiple joy controllers, etc.), the following bugs are known:

• The border is not emulated or displayed. This is not really an issue for BASIC or GBASIC, however, where the border is almost always the same as the background colour.
• Loading a defective snapshot may crash the emulator as well. Many of the weak points have been found ... but probably not all.
• The GRAPHIC LOAD trap will load the first file it finds, even if it doesn't match the filename you provide (a real Tutor will throw a FORM ERR). This is considered a "feature."
• Failed LOADs in BASIC trigger * ERR 19 in a way that is not entirely devoid of side effects.

Downloads and good stuff

Download the emulator for 32-bit (511K, PowerPC/Intel Universal) or 64-bit (220K, x86_64 only). The 32-bit version is a Universal build compatible with any Mac (PowerPC or Intel) running 10.4 through 10.13, and is accelerated for AltiVec on Power Mac G4 and G5 machines, but does not work properly on 10.14 and will not run on 10.15 or any later version of macOS. The 64-bit version is compatible with any 64-bit Intel Mac running 10.12 through 10.15. Tutti II is not signed, so 10.7+ users may need to adjust your security settings when running the app for the first time.

Download the demo tapes (50K). This includes a selection of games, pictures and demos for both GRAPHIC and BASIC. For GRAPHIC,

• a black and white dithered image of Georges Seurat's A Sunday Afternoon on the Island of La Grande Jatte generated with XTOMYDEV for GRAPHIC mode (load "BITM"),
• a "GRAPHIC 64" colour dithered image of the same painting also generated with XTOMYDEV (load "PICT"),
• a "GRAPHIC 64" colour dithered image of the lovely lady named Jayne shown at right also generated with XTOMYDEV (load "PICT"),
• four of the Pyuuta GBASIC cassette games converted for American Tutors (load "UFO1," "BOAD," "PLAT" or "MSLZ"),

• Colour Bars and 32 Sprites demos for BASIC (load "BARS" and "SPRITE" respectively).
• Canned Music (give it a minute or two to load its data) (load "CANNED"),
• and Macrossmind, a Master Mind clone with clever programming (let it set up video first) (load "MIND").

• To build the 32-bit universal OS X binary requires Xcode 2.5 or 3 (with the 10.4 SDK installed) and exactly SDL 1.2.14. Install the 1.2.14 developer framework and type make -f Makefile.osx.
• To build the 64-bit Intel binary requires current Xcode and the 10.12 SDK (to get around bugs in the 10.14 SDK; 10.13 should also work), as well as a pre-compiled copy of SDL 1.2.15. See Makefile.macos for the exact process.
• To build the Win32 version requires mxe, with gcc (for MinGW) and SDL 1.2.15. With mxe installed, type make -f Makefile.mxe. You may need to change MXE_ROOT in the Makefile.mxe to point to where you have it installed.

Version history

2.2 - "Tutti Two Point Two Meets The Hooded Fang"

• support for 64-bit macOS and Win32 (compiled with mxe)
• improved timing of interrupts and 9995 decrementer

• source code refactor to make system more modular and implement debugging
• custom SN76489AN sound emulation, including noise channel
• massively overhauled 9995 emulation with ALU core modified from MAME/MESS (this fixed a lot of bugs just by itself!)
• 9918ANL palette recalibrated
• numeric keypad keys "84560." emulate joystick (0 and . are SL/SR)
• 9995 decremeter actually works to spec using a custom algorithm
• 9995 decrementer IRQ 3 now independent of VDP sync (as on a real system)
• ... so the menu option is now "Sync IRQ3 to System Clock"
• timing loop recalibrated against a real Tutor
• screen updates are even faster
• screen updates are less frequent to improve performance/reduce tearing
• stuck final sync bits are now flushed, fixing issues with real machine LOAD
• illegal instructions hit 9995 debugger (this includes the BASIC COLOR bug)
• sprites scrolling under top border no longer display garbage
• potential crash in sprite subsystem wallpapered
• lots of old code removed

• support for paste as keystrokes
• AltiVec acceleration (G4/G5) for 9918 emulation
• 2x display (software on Intel/G3, AltiVec scaling on G4/G5)
• multiple fixes to the 9995 core
• display list 9918 sprite algorithm is now scanline correct
• fix crash in tape save dialogue
• faster writes to memory-mapped I/O
• enabled _/@ key (mapped to backquote key)
• additional alternate MOD key for keyboard without Right-Opt (iBook G4, etc) to numeric keyboard ENTER
• you can use both shift keys now (both map to "SHIFT")
• further improvements to timing loop
• debugger can emit instruction stream to stdout (toggled with F7)
• Command-M actually does minimize the window now
• 9995 STWP instruction correctly disassembled
• fix visual glitch with "2" glyph in debugger

1.0 - "Initial release as TutorEm" (for internal bookkeeping only).