tomharte / clk

A latency-hating emulator of: the Acorn Electron and Archimedes, Amstrad CPC, Apple II/II+/IIe and early Macintosh, Atari 2600 and ST, ColecoVision, Enterprise 64/128, Commodore Vic-20 and Amiga, MSX 1/2, Oric 1/Atmos, early PC compatibles, Sega Master System, Sinclair ZX80/81 and ZX Spectrum.

Clock Signal

Clock Signal ('CLK') is an emulator that seeks to be invisible. Users directly launch classic software, avoiding the learning curves associated with emulators and with classic machines.

macOS and source releases are hosted on GitHub. A Qt-based Linux build is available as a Snap.

This emulator seeks to offer:

• single-click load of any piece of source media for any supported platform;
• with a heavy signal processing tilt for accurate reproduction of original outputs;
• avoiding latency as much as possible.

It currently contains emulations of the:

• Acorn Electron;
• Amstrad CPC;
• Apple II/II+ and IIe;
• Atari 2600;
• Atari ST;
• ColecoVision;
• Commodore Vic-20 (and Commodore 1540/1);
• Enterprise 64/128;
• Macintosh 128K, 512K, 512Ke, and Plus;
• MSX 1 and 2;
• Oric 1/Atmos;
• Sega Master System;
• Sinclair ZX80/81; and
• Sinclair ZX Spectrum.

Also present but very much upcoming are the:

• Acorn Archimedes;
• Commodore Amiga; and
• early PC compatible.

On the Mac it is a native Cocoa and Metal application; under Linux, BSD and other UNIXes and UNIX-alikes it uses OpenGL and can be built either with Qt or with SDL.

Single-step Loading

Through static and runtime analysis CLK seeks automatically to select and configure the appropriate machine to run any provided disk, tape or ROM; to issue any commands necessary to run the software contained on the disk, tape or ROM; and to provide accelerated loading where feasible.

With CLK installed the full process of loading a piece of software — even if you've never used the machine it runs on before — is:

1. locate it in your OS;
2. double click it.

There's no need to wade through creating a new machine, inserting media into it or figuring out which loading command goes with this piece of software, and no import procedure — CLK does not attempt to take ownership of your files or to usurp your OS.

Keep your emulated titles on your desktop, in your dock, or wherever else you usually prefer to launch software from, and launch in a single step. Just like any other piece of desktop software.

Signal Processing

Consider an ordinary, unmodified Commodore Vic-20. Its only video output is composite. Therefore the emulated machine's only video output is composite. In order to display the video output, your GPU must decode composite video. Therefore composite video artefacts are present and correct — not because of a post hoc filter but because the real signal is really being processed.

Similar effort is put into audio generation. If the real machine normally generates audio at 192Khz then the emulator generates a 192Khz source signal and filters it down to whatever the host machine can output.

Samples

1:1 Pixel Copying	Composite Decoded

1:1 Pixel Copying	Correct Aspect Ratio, Filtered

Low Latency

The display produced is an emulated CRT, with phosphor decay. Therefore if you have a 140Hz 4k monitor it can produce 140 distinct frames per second at 4k resolution. Latency is dictated by the host hardware, not the emulated machine or emulator.

Audio latency is disjoint from frame rate and is generally restrained to 5–10ms.

Accurate Emulation

Accuracy is a user-experience issue; the more accurate an emulator, the more likely that a user can run every piece of software they're interested in without further intervention.

This emulator attempts cycle-accurate emulation of all supported machines. In some cases it succeeds.

Additional Screenshots

Sponsorship

I've been asked several times whether it is possible to sponsor this project; I think that's a poor fit for this emulator's highly-malleable scope, and it makes me uncomfortable because as the author I primarily see only its defects.

An Amazon US wishlist is now attached in the hope of avoiding the question in future. A lot of it is old books now available only secondhand — I like to read about potential future additions well in advance of starting on them. Despite the optimism of some book sellers, please don't purchase anything that is currently listed only at an absurd price; they were sorted by secondhand price when added to the list, with the cheapest being $5.

clk's Issues

Downloads

Where to find executables files? There are unix versions?

ColecoVision should be able to open rom images with a .bin extension

Which implies being able to disambiguate them from Atari images.

'ascii' codec can't decode byte 0xc3 in position 12: ordinal not in range(128)

Hi
When I try to build, I have this error :

'ascii' codec can't decode byte 0xc3 in position 12: ordinal not in range(128)

OS : Manjaro

Thank for your help.

Oric does not recognise HFEs

Per http://forum.defence-force.org/viewtopic.php?f=22&t=1698&p=16926#p16925:

... none of my HFE images are working. :( I use the command line tool to convert DSK to HFE.

Declarations of display and quick load options between machines are duplicative

ZX81: Humpty Dumpty doesn't load

Typer hierarchy can lead to diamond inheritance of KeyboardMachine::Machine

Typing Command-V after copying some text in the Oric BASIC results in string of "V" characters.

Using the latest version (https://github.com/TomHarte/CLK/releases/tag/2018-04-13).
Under macOS (Sierra 10.12.6).
Using a new instance of the Oric/Atmos (no MicroDrive).
Copy (using Command-C) the BASIC program listed in this Defense Force forum thread : http://forum.defence-force.org/viewtopic.php?p=5611#p5611.
Then, selecting the CLK Oric window so it has focus.
Type Command-V to paste the copied program.

Notice that this results in a series of "V" characters (and a few others) typed sequentially in the BASIC window.

Note that, if the Oric window loses focus, the sequence stops and does not resume upon giving it focus again.

I am not sure if Copy-Pasting of text is actually supported by the emulator (as a naive user, I would expect it to, otherwise I would not have tried this and discovered the issue ;) ) but it seems reasonable to think that the current behavior is not as designed. ;)

Here is the exact text copied from the forum post:

1 '***********************
2 ' MICROSOFT! Easter Egg
3 '***********************
4 B=#E435 : E=B+9
5 FOR I=E TO B STEP -1
6 J=PEEK(I) : J=J-INT(J/64)*64
7 IF I>B THEN A$=A$+CHR$(J+64) ELSE A$=A$+CHR$(J)
8 NEXT I
9 PRINT A$

This said, I would wager that any copied text causes this result.

On a VIC-20 instance, copying that same text generates a single "V" character but seems to confuse further the input routine:

• Typing the "A" key does not produce any result
• Typing the "Q" key produce the "QV" sequence of characters, "E" gives "EV", and so on...
  As for the Oric instance, losing focus and restoring it restores normal behavior.

Vic-20 causes owner to make incorrect audio assumptions

It initially reports a zero audio output rate, before settling on its real number.

Add a no-command-line kiosk mode

When running in kiosk mode, Clock Signal provides no interface chrome whatsoever. This would prima facie make it ideal as an embeddable emulator: one that could be used to provide the Linux/Windows/macOS version of a homebrew title for any of the supported machines.

Two obstacles present themselves:

• the title to load must be specified at the command line; and
• the machine's system ROMs, if any, are always sought out in a location intended to conform to the Filesystem Hierarchy Standard.

The former implies an extra level of indirection in launching that could confuse a user; the latter effectively blocks embedded distribution for Windows and macOS and introduces an undesired side-effect in Linux in branding the embedded game with the CLK name.

Therefore it is desirable to offer:

• the trivial ability to build or to package an existing build so that it will perform only exactly one command line; and
• to allow system ROM locations to be specified on the command line.

So e.g. a Windows distribution of Stormlord might look like:

• stormlord.exe (identical to clksignal.exe, appropriately renamed);
• stormlord.conf (which contains the proper command line to launch Stormlord);
• sdl2.dll (as this hypothetical is a Windows target);
• data/basic11.rom (the Oric BASIC ROM);
• data/stormlord.tap (the original Oric tape file).

Where the user launches stormlord.exe and is promptly greeted by the Stormlord title screen.

Eliminate `union` that underlies static analyser results

For exposing too much information, too widely. Why should the Electron care if I introduce a new Vic-20 memory model?

Putting it on the heap and getting to expected types by dynamic casting would be more appropriate.

Implement noise-to-signal gain on floppy drives

With a real floppy drive what should happen when there are no flux transitions for an extended period is that the automatic gain is dialled up until the drive starts to report background noise as data. In other words: no flux transitions for 12ms or so implies random data subsequently reported.

This feature is utilised by some original copy-protected titles on platforms where the disk controller does not natively allow a long gap with no flux transitions to be written. It is also a prerequisite for claiming a complete implementation of the WOZ file format.

Add support for ZX80/81 UDG

Which, as I understand it, primarily means putting RAM in place of the ROM mirrors in the low 16kb area.

MSX fast tape loading works poorly with TSXs

Specifically: get_byte's hard-coded polarity (ostensibly to the MSX BIOS spec) is problematic.

SDL build fails under Linux due to missing dependencies

Per http://forum.defence-force.org/viewtopic.php?f=22&t=1698&p=16926#p16925:

About CLK for Linux - build from current git sources fails with 3 problems:

• I have to add ../../ClockReceiver to include path
• StaticAnalyser.cpp - memcmp wants #include <string.h>
• MultiJoystickMachine.cpp - std::find wants #include

SDL version does not respond to drag and drop

macOS - Drag and dropping the C64 kindness demo disk image causes crash

The latest macOS release of CLK crashes when drag and dropping the .d64 image of the "kindness" demo on its dock icon.

(OS: Sierra 10.12.6)

Steps:

• download https://github.com/c64scene-ar/4kindness/raw/master/bin/4kindness.d64
• launch the latest release of CLK (*)
• drag 4kindness.d64 over the dock icon of CLK
• notice CLK crashes

(*) https://github.com/TomHarte/CLK/releases/download/2018-03-22/Clock.Signal.macOS.2018-03-22.zip

Mac only: add system for importing of system ROMs

Provide a user-friendly system for importation of those system ROMs that are not bundled with the macOS build of the application.

Particular obstacles:

• different storage, e.g. the Disk II ROM is sometimes in its natural order, sometimes bits are rearranged into Beneath Apple DOS order;
• different packaging, e.g. sometimes the Apple II ROMs are distributed as their individual original chips, sometimes as the full block of 12kb;
• compression, possibly.

Audio subsystem contains substantial design errors in use of compile-time polymorphism

In particular, each sound chip is itself a speaker — it's both something that privately knows how to generate audio and, through inheritance, something that knows how to filter for an output.

This coupling of discrete tasks creates composition problems.

Oric (1 or Atmos) with Microdisk produces random colorful jittering screen

For both releases 2018-04-13 and 2018-05-15, on macOS Sierra (10.12.6):

1. Launch Clock Signal
2. Go to menu "File -> New ..."
3. Select Oric1 or Atmos (both cause the issue)
4. Select "Microdisk"
5. Start the guest machine

This will produce a very colorful animated random screen.
The guest computer does not seem to respond to any input thereafter.

Note that dropping a disk image such as the one listed in the Defense Force forum post linked below generates a non animated version of that screen, at least for release 2018-05-15.
Post: http://forum.defence-force.org/viewtopic.php?p=17531#p17531

Implement a direct-NTSC machine

When implementing the direct TED phases as part of the Vic colour revamp, PAL numbers transcribed directly but NTSC phases had to be entered as 90° - phase.

Given that the Oric uses its colour ROM so I'm not directly generating the PAL colour signal there but the correct thing is coming out, that strongly suggests I'm switching chrominance channels somewhere when dealing with NTSC colour.

Implement a machine with fully well-defined NTSC signal generation to verify that — an absolutely basic Apple II, for example.

SDL version does not communicate necessary ROM images

SDL version does not accept pasted text

ZX80 and '81 do not automatically RUN software they've loaded

So the process for launching software on those platforms is not always fully automated.

Atari 2600 runs PAL games with incorrect colours

It applies the same phase shift formula, in multiples of a cycle, as for NTSC, which is clearly incorrect.

Electron demonstrates incorrect timing in Mode 3

Running the test at http://www.stardot.org.uk/forums/viewtopic.php?t=10069 , all modes are correct except Mode 3. The program should take almost 12s to run; it completes in just 7.74.

Audio channel input for systems with tape support?

I realize that this might be an unconventional suggestion, technically as well as user experience wise but maybe you might think there is some value to it, so bear with me for a few paragraphs. ;)

Upon reading a Symoon post on the "Experimental very fast tape loading" thread on the Defence Force forums where he attached a ZIP file containing WAV files to be used as tape input for physical Oric machines, I wondered about the feasibility and practicality of being able to emulate a similar setup. (The post: http://forum.defence-force.org/viewtopic.php?p=17538#p17391.)

Since I do not have access to an actual Oric at the moment, I must resort to emulation to test Symoon's fast loading technique. However, it does not look like Clock Signal offers a way to use an audio file to emulate a tape input signal at the moment.

Providing an user interface of some kind to allow the (necessarily interactive/dynamic) specification of an audio file to be used to emulate the tape input signal seems simple enough. It even seems possible that some other Oric emulators already offer such an interface and adding one to Clock Signal does not seem particularly technically challenging (feel free to contradict me though, I would love to learn about it).

But, another idea popped into my devious mind:

what if, instead of offering a conventional "please choose your audio file to be used as tape input signal" selection dialog, Clock Signal simply used an actual macOS audio input channel for tape signal input?

I see several advantages to such a system:

• no need to offer a silly selection dialog, users are responsible for sending audio to the emulator
• most macOS applications which output sound allow to configure on which channel to send the audio, so users can use their favorite app and possibly scripts
• users are in perfect control of when they start playing audio, just like they are on an actual Oric (or other) machine
• audio streaming/mixing systems/apps such as "Audio Hijack" and "Loopback" from Rogue Amoeba allow to interject audio processing filters in between the audio source and the receiving channel, offering potential ways to enhance signal decoding by the emulated machine when using digitized audio from actual cassette tapes, possibly damaged. (Audio Hijack: https://rogueamoeba.com/audiohijack/.)
• technically, this is much simpler to implement: just read the bytes from the input audio channel, no audio format to decode, no library to add, etc.
• this is actually real audio input emulation and kinda really fits with Clock Signal "signal" philosophy.

What do you think? ;)

Almost half of MSX MegaROMs run incorrectly

Owing to a failure in static analysis to determine the type of paging scheme.

Atari 2600 is mute

Oric display is incorrect under Linux

Display can strobe due to phase error when displaying exactly 60Hz content (or close)

On my machine with an exactly-60Hz display:

• a machine that outputs exactly 60Hz may find itself permanently out of phase with the output display, leading to unambiguously avoidable visual strobing/tearing; and
• a machine that is outputting very close to 60Hz will similarly strobe, when nudging its clock rate a little would lead to a more accurate emulation (in the sense that: not strobing and running 0.1% off the real speed is closer to a real experience than strobing).

Consider implementing sufficient tracking and a negligibly variable clock in order to: (i) be able to move the first case into phase with the output device; and (ii) to be able to move and to accelerate/decelerate the latter case, within acceptable bounds, so that it is in phase.

Naturally nothing about 60Hz should be specified: 50 -> 50, 50 -> 100, 60 -> 120, etc, should all work equivalently. Given that some machines have a variable output frequency (at least the Atari, ZX80/81 and CPC), this will also need to be the result of active tracking rather than something knowable in advance.

Add visual and/or audible signs of disk (and tape?) activity

As the emulated machines become more disk heavy — particularly re: the CPC and the upcoming Apple II — it becomes more of an impediment to use that there are no visible or audible cues indicating disk activity. Correct this.

macOS Sierra - Crash when using menu "File -> New".

Using this release: https://github.com/TomHarte/CLK/releases/download/2018-03-23/Clock.Signal.macOS.2018-03-23.zip

Accessing the menu entry "File -> New" causes CLK to crash.

(Note that Sierra offers to send a bug report to Apple, do you receive them? If so, I will fill and tag them so you can associate them with the corresponding issues in GitHub.)

TZX/TSX support omits blocks: 0x15 (direct recording), 0x18 (CSW)

Linux: launching can break window manager

http://forum.defence-force.org/viewtopic.php?f=22&t=1698&p=16926#p16925:

But more important is that when I start ./clksignal it breaks my Window Manager i.e. all open windows lose their title bars, frames, buttons etc.

macOS - "QuickLook" icon preview looks like the default Apple application icon.

This is certainly not a big issue but on Sierra (10.12.6), after obtaining the latest release from GitHub and extracting it from the archive, the quicklook icon which appears in the Finder looks like the generic Apple application image:

The app's icon itself as shown next to the file name seems normal (a dark/grey CRT monitor).

SDL version does not communicate available command-line options

ZX81 runs BiggOil incorrectly

See this thread:

It looks like something I'm doing in BiggOil upsets Clock Signal. Let me know if there's anything you would like from me if you choose to investigate.

BiggOil is a GitHub project and a binary is available here.

VIC timings are askew

As per http://sleepingelephant.com/ipw-web/bulletin/bb/viewtopic.php?f=14&t=8057&start=45#p100159 :

You should check the timing of the NTSC (and possibly also the PAL) version.

In the first screenshot, the splits of the background register happen at the wrong place (after the first text column), whereas they're supposed to happen just after HSync, at the beginning of the raster. With non-interlaced modes on NTSC, the change of the raster register ($9004) actually happens in the middle(!) of the raster line, not at the start, this is being taken care of by my routines.

The splits also do not honor, that changes of the colour registers on real h/w take effect one hires pixel late w.r.t. half char boundaries.

Add S-Video display path

The Vic-20 has native S-Video output, the Atari 2600 can be modified easily for it — TIA natively outputs S-Video. S-Video offers a higher-quality picture than composite video.

Add an S-Video path to the emulator, and enhance those machines to support it.

macOS - GateKeeper : App is from an unidentified developer.

When attempting to open the latest release on macOS Sierra (10.12.6) (*),
GateKeeper indicates that the application is from an unidentified developer and thus cannot be opened.

This can of course be worked around manually but it is probably a good idea to not teach users to ignore GateKeeper warnings and to properly register the app to Apple instead.
The required fee is not too high (90$ if I recall correctly).

As a developer and end user, I would feel much safer knowing that the app is running under the protection of GateKeeper.

Thanks!

(*) https://github.com/TomHarte/CLK/releases/download/2018-03-22/Clock.Signal.macOS.2018-03-22.zip

Z80 does not demonstrate proper MEMPTR behaviour

Implement the Apple II floating bus

Cf. http://rich12345.tripod.com/aiivideo/softalk.html

... a complete sixty-five-cycle scan line consists of sixty-five consecutive bytes of display buffer memory that starts twenty-five bytes prior to the actual data to be displayed.

During VBL the data acts just as if it were starting a whole new frame from the beginning, but it never finishes this pseudo-frame. After getting one third of the way through the frame (to scan line $3F), it suddenly repeats the previous six scan lines ($3A through $3F) before aborting to begin the next true frame

Add option to launch a stated machine without providing a piece of media

As presently formulated the emulator is launched by providing a piece of media. It runs an analyser on the media to determine target machine and machine configuration, then launches that machine with the media inserted.

It is a user request that the emulator also be launchable by specifying a machine (and configuration), more like a classic emulator.

WD1770/1793/etc does not respond to Type IV interrupt commands

Contract around IntermediateShader's inputStart, outputStart, ends and phaseTimeAndAmplitude is fragile

Specifically re: repetition across two source files, and undocumented binding guarantees.

macOS Sierra - CLK crashes when attempting to create a new tab

With release https://github.com/TomHarte/CLK/releases/download/2018-03-23/Clock.Signal.macOS.2018-03-23.zip,

(With CLK automatically loading the kindness.d64 disk image mentioned in #378 )
Start CLK
Notice the VIC20 display window opens with kindness.d64 being loaded
Access the menu entry "View -> Show Tab Bar" to have the tab bar showing.
Click the "+" button of the tab bar.
Notice that CLK crashes.

Composite output aliases

Based on a very quick analysis, specifically in point sampling to form the in-phase composite buffer. It's very easy to see on a TMS or Atari because they remain in phase for their entire frame.

Add ZonX support for the ZX81

SDL version has greater audio latency