Home

Awesome

C/C++ CI GitHub Release GitHub License

osiemu

Ohio Scientific Instruments, Inc. Emulator for Linux, Windows, and macOS

Binary releases for Linux, Windows, and macOS are here.

screenshot

  1. Features
  2. Keybindings
  3. Monitor
  4. Command line options
  5. Configuration files
  6. Build instructions
  7. Disk images
  8. GUI launcher
  9. CP/M-65
  10. Notes

Features

Keybindings

KeyFunction
F3Hardware switch, hi-res overlay
F4Hardware switch, normal font / graphics font
F5Hardware reset
F8Enter monitor
F9Exit emulator
F11Toggle fullscreen

Monitor

CommandArgumentsFunction
q,quitexit emulator
contcontinue emulation
helpprint this help
showshow emulation window
hidehide emulation window
d[mem]dump memory contents
cmem val ...change memory to value(s)
fbeg end valfill memory with value
regsdisplay CPU registers
setcputypeset CPU type to nmos|undef|cmos
u[mem]unassemble memory
setbpmemset breakpoint
clrbpclear breakpoint
lmem fileload raw data from file to mem
sbeg end filesave raw data to file
setpcvalset PC to value
setavalset A to value
setxvalset X to value
setyvalset Y to value
setspvalset SP to value
setpvalset P to value
tapeslist current tape files
ejectinput | outputeject input or output tape
insertinput | output fileinsert input or output tape
rewindinput | outputrewind input or output tape
driveslist mounted floppies
swapnumx numyswap drives numx and numy
unmountnumunmount drive
mountnum filemount file to drive num
traceon | off | clear | save [file]CPU tracing
hmon | off | clr | save [file] | img [file]memory heatmap (r/w)
stackon | off | showstack tracing
btbacktrace (needs stack on)

Command line options

usage: osiemu <config-file>
       osiemu [options]

options:

    -b/--basic filename.rom    specify BASIC ROM
    -k/--kernel filename.rom   specify kernel ROM

    -c/--font filename         specify character set font (8x2048 image)
    -q/--graph-font filename   specify graphics font (8x2048 image)

    -K/--cpu-speed speed       select speed: quarter    0.983040 MHz (default)
                                             half       1.966080 MHz
                                             510c-slow  1.000000 MHz
                                             510c-fast  2.000000 MHz
                                             540bw      0.982500 MHz
                                             540col     1.006667 MHz

    -v/--disable-video         disable video RAM (default: enabled)
    -m/--video-mode mode       forced modes:   64x32 (default)
                                               64x16
                                               32x32
                                               32x32s64
                               variable modes: 540b (32x32s64 / 64x32)
                                               600 (32x32 / 64x16)
    -M/--mono-color color      monochrome color green, amber, bluish or white
    -a/--aspect mode           aspect mode: full (default), 16:9 or 4:3
    -z/--zoom factor           increase display size by factor (2, 3, or 4)
    -V/--smooth-video          enable anti-aliased scaling
    -C/--color-mode mode       mode: monochrome (default), 440b, 540b, 630
    -d/--frame-rate rate       display rate: 60     60.000000 Hz (default)
                                             540bw  59.967041 Hz
                                             540col 61.442057 Hz
                                             (unknown is treated as float)
    -s/--saturation            color saturation [0.0-1.0], default: 0.75
    -H/--hires-mode mode       mode: none, 440b (128x128), 541 (256x256)
    -S/--scanlines             emulate visual scanlines (zoom >= 2 only)
    -x/--pixels                emulate visual pixels (implies scanlines)

    -A/--ascii-keyboard        enable ASCII keyboard at 0xdf01
    -r/--raw-keyboard          enable raw keyboard mode
    -i/--invert-keyboard       invert keyboard matrix signals (model 542)
    -n/--inverse-caps          invert CAPS

    -j/--joystick1 index       specify joystick 1
    -J/--joystick2 index       specify joystick 2

    -t/--tape-input file       specify tape input file (default: none)
    -T/--tape-output file      specify tape output file (default: none)
    -L/--tape-location         ACIA location: f000 (default), fc00
    -B/--tape-baseclock        set baseclock (default: 4800)

    -f/--floppy0 file          specify floppy0 file (default: none)
    -F/--floppy1 file          specify floppy1 file (default: none)
    -g/--floppy2 file          specify floppy2 file (default: none)
    -G/--floppy3 file          specify floppy3 file (default: none)

    -R/--force-ramtop hex      force RAM top to location hex
    -X/--extra-ram flag,...    enable Model 555 eXtra RAM bank(s):
                                   d0  enable $d000-$dfff
                                   e0  enable $e000-$efff
                                   f0  enable $f000-$ffff (unofficial)
                               note: RAM has lowest priority in conflicts with
                                     video cards, ACIA, or kernel ROM

    -y/--sound-mode mode       mode: none, 542b (DAC+tone), 600 (DAC)
    -Y/--sound-bufsize size    set sound buffer size (32-2048, default: 256)

    -w/--warp-speed            run emulator as fast as possible

    -Z/--switches switches     comma separated list of hardware switches
                               "flipped" before startup
                                 hires       enable high resolution overlay
                                 graph       enable graphics font
                                 nobasic     disable BASIC ROM (8kB extra RAM)
                                 fullscreen  start fullscreen

    -D/--debug flag,...        enable debug messages: floppy

    -h/--help                  show usage information

Configuration files

Configuration files contain command line options, one per line. The leading -- is optional. If an option requires an argument, the option and the argument can be separated by either a space or a '='. Everything after the first space or '=' until the end of the line is considered the argument. There's no need (and it's not supported) to put arguments between single or double quotes. Escaping of characters isn't needed either.

Example:

zoom 2
scanlines
video-mode=32x32
--cpu-speed half
kernel=long path with spaces/synmon.rom

More examples are in the config directory.

Build instructions

Prerequisites

To build from source you need to install the development packages of libSDL2 and libSDL2_image. The exact name depends on your Linux distribution, Cygwin, or homebrew. For example, on Ubuntu 22.04 they are called libsdl2-dev, and libsdl2-image-dev.

Linux

git clone --depth=1 --recurse-submodules https://github.com/ivop/osiemu
cd osiemu
git checkout Release-0.9.2
make release

If you skip the checkout, you'll end up with the next release cycle version which might not be what you want. Use git tag to see all tagged versions. make without any arguments will build a debug version (no optimizations, and level 3 debug info).
You can override the sdl2-config utility used by setting the SDL2CONFIG variable on the command line, i.e.

make -j8 release SDL2CONFIG=/path/to/sdl2-config CC=/path/to/my/compiler

Windows

Use Cygwin64. MinGW64 doesn't work because it is missing mmap, O_NONBLOCK, and getline.

macOS

For macOS 12 (Monterey) and later, homebrew should work. For earlier versions, use MacPorts. Has been tested to be fully working on Big Sur with MacPorts.

Disk images

osiemu uses its own disk image format. For each track it contains the complete bitstream that enters the floppy ACIA, including all the framing and prolonged stop bits for timing. See doc/disk-format.txt for details. The tools directory contains hfe2osi and osi2hfe to convert from and to HFE flux dumps from/for real hardware.

GUI launcher

<img src="screenshots/osiemu-launcher.png" alt="screenshot-launcher" height="256"/>

If you are tired of fiddling with command line options, there's also a GUI launcher. To build, use:

make osiemu-launcher

You'll need either Qt5 or Qt6 to build it. If you want to override the default qmake that's used during the build process, you can specify it on the command line. For example:

make -j8 osiemu-launcher QMAKE=/path/to/Qt/6.7.2/gcc_64/bin/qmake6 CXX=/path/to/clang++

forces a build against Qt 6.7.2 and use the clang compiler. It has been tested with Qt 5.15.x and Qt 6.5.x and up. On Windows, contrary to the main osiemu binary that has to be built with Cygwin, the launcher binary has to be built with MinGW. Preferably the version that is distributed with Qt itself.

CP/M-65

The cpm65 directory contains several disk images of the Ohio Scientific port of CP/M-65. Alongside you'll find .settings files for the GUI launcher, and .config files that can be used from the command line. For more information on what CP/M-65 exactly is, how to use it, and possibly newer disk images, see the CP/M-65 website. If you want to try out the serial systems version, you'll need to make sure the serial tape input and output settings point to the right (virtual) device. As an example, they now point to /dev/pts/3.

Notes

Linux example:

$ socat -d -d pty,rawer,echo=0 pty,rawer,echo=0
2024/09/06 01:02:38 socat[936204] N PTY is /dev/pts/9
2024/09/06 01:02:38 socat[936204] N PTY is /dev/pts/10
2024/09/06 01:02:38 socat[936204] N starting data transfer loop with FDs [5,5] and [7,7]

In another window:

$ minicom -D /dev/pts/9 -b 19200

And in yet another window:

$ ./osiemu --disable-video \
           --kernel kernel/syn-c3-serial-hdm.rom \
           --tape-location fc00 \
           --tape-baseclock 19200 \
           --tape-input /dev/pts/10 \
           --tape-output /dev/pts/10 \
           --floppy0 some-floppy.os8

On Windows, you can do the same if you install Cygwin64. The device names will be slightly different though. socat will tell you which devices it created.

If you don't want to install Cygwin64, you can also use com0com to create a pair of virtual COM: ports and connect them with a virtual null-modem. For example, you create a pair called COM6: and COM7:. Now connect PuTTY (or any other serial terminal program) to COM6 and connect the tape-input and tape-output of osiemu to /dev/ttyS6, which is COM7: because ttyS serial devices start counting at 0 and Windows COM: ports start at 1, so you have to subtract 1 to get the ttyS name.

Future additions?