Commodore-LCD.lgb.hu :: My emulator

This is the home of my JavaScript Commodore LCD emulator. If you don't know what Commodore LCD ("CLCD" in my documents) is, please visit this page first. As usual, I often update the page with new information, corrections. If you have any feedback, bugfix, etc, please contact me. You can find contact information on this page. About other Commodore LCD emulators, please visit this page, though - as far as I know - my emulator is the only one currently (but this statement can be obsoleted meanwhile ...).

You can try my (on-line, written in JavaScript) emulator >> HERE << but you should read the rest of this page first.

Here is the test-ROM version.

This is a Commodore LCD emulator which tries to emulate the machine on its hardware level. That means: it runs the original unmodified ROM images^* and (more or less at the moment ...) works, no custom modifications and patches are done (but see limitations).

The emulator itself (all parts) are written by me, and can be used, modified, redistribute under the terms of GNU/GPL license v3 or possible later versions. Currently I don't give download link, as it's a web "application", you can save the html and js files, it's still a download possibility :)

However the emulator wouldn't be born without some nice people, please visit the "thanks" page. I also learnt a lot from the disassembly tries of the ROM code, even if it's still far from being completed, you can see the partial result here (kernal only). I only touched the "raw" disassembly result at parts what I needed or what I was interested in during the work. For more information, please read the specification. That page also writes about the details of the emulation and about my emulator and its bugs too.

Current limitations/known bugs of the emulator

• Probably won't run with Internet Explorer, but this is a "WONTFIX" item, as IE in general is so slow to adopt new web technologies. Also I have never used IE nor Windows, so it would be hard for me to test. I'm using Chrome, so Chrome (on Linux, but it should not matter) and webkit based browsers (like Safari) should be OK, firefox seems work well too. Probably even mobile browsers would work, if they are up-to-date enough (though the keyboard can be issue - no specific code for that).
• The JavaScript console is flooded with various debug messages :)
• Keyboard emulation is not ready yet: currently most keys works on US keyboard layout (beware: it's a position based mapping - where it was possible -, some keys cannot be emulated with the correct US position because it would be shifted on the CLCD but unshifted on the PC, or vice versa - it can be handled later to introduce "virtual shift" pressed by the emulator, etc). Also, it seems Firefox uses another key codes in some cases than Chrome, it can be a problem! The keyboard matrix is shown next to the display itself, you can try to click it to press/release a key, but the emulator can be easily confused to use the keyboard and the matrix at the same time, also some positions (the bottom line) will cause to "freeze" the emulation, because bits there (the 3 bit MSB) has special meaning, unrelated to the keyboard for real. This "virtual" matrix is used by me to figure out the keyboard map by "pressing" keys and checking out the visible/functional result.
• LCD controller emulation is more-or-less correct, however I don't know enough on specific "controller bits" (though graphical mode seems to be OK, tested with BASIC with GRAPHIC and CIRCLE commands), nor the X-scroll register. The fefresh rate of the LCD controller is totally unknown I'm using 25FPS right now. I also don't know the exact effect on the CPU speed caused by the read bus accesses by the LCD controller.
• The ROM images seem to contain a character set in 6*8 resolution, the layout seems to be the normal CBM "screen codes". It's upper case only charset though. However CLCD really uses two alternate character sets, but I haven't been able to locate the other. Currently, it seems for me, that character generator ROM can be another ROM, and I have no ROM image for that. The character set I was able to find may be used only for software purposes (eg rendering characters in graphical mode, or so?). However, since I have no other choice, a very ugly an incorrect trick must be used: I use the charset found in the KERNAL, and I produce the other character set by cloning the existing one, with relocating capital letters, and use some random internet resource to get a 6*8 matrix for lower case chars. Thus, the look of the emulated CLCD in my emulator may not be exactly what you would see with a real CLCD "on level of pixels". To correct this, I would need the missing character generator ROM image.
• The emulation is far from being cycle exact. It should run about an 1MHz CPU clock, but I can be wrong on 65C02 opcode timings, also not everything is emulated (plus cycles on certain addressing modes when crossing page boundaries etc). The VIA emulation is also not cycle exact, especially if you set up modes not used by CLCD by default (eg only PHI2 clocked timer and shift register is emulated).
• Hardware components are emulated by my own Javascript code, which can be wrong, of course, and maybe not even ideal. Well, I am certenly not the best Javascript programmer/coder on this planet (the code is the prove), that's for sure. One of my goals was exactly to learn some JavaScript programming.
• The current emulator organization is a mess, lots of code in HTML, heavy usage of global scope, many remainment of "dead" and "test" code everywhere, outdated comments, etc. I plan to fix these later so the emulator can be placed into any given HTML without too much extra work than including some JS files, defining a canvas, and calling a single function to start the emulator.
• VIA emulation is quite messy, not cycle exact, unfinished and there can be other bugs. Things seem not to be absolutely needed for the CLCD emulation are not even emulated at all.
• Writing ACIA emulation is started, but left unfinished. I planned to emulate a little "command line shell" to the emulator internals, which could be used throughout the CLCD's builtin terminal software then :)
• I've also started to write hardware level of the IEC bus emulation (so not patched ROMs!), to be able to translate IEC commands into AJAX calls :) However it's unfinished at the early stage and I had problems with that. Maybe CLCD does not have working IEC bus in the ROM code? A minimal C64 emulator with the very same IEC code seems to be OK ... (till the point it's done at least which is just the ATN and sending bytes, IEC turnaround, answer, etc are not implemented). Please ready the point about the "RAM disk" (virtual 1541) later to get to know: some odd hardware emulation problem can be quite picky what it causes and everything other can look normal :)
• CLCD has an RTC chip. Currently, it's emulated at a level that current time/date can be read, so if the clock of your machine (which is used to run the web browser to use the emulator, ie your PC) is used, however, modification of time/date will not work! Thus if you try to set the clock in the SHELL, you'll still see your system time, instead of the value set by yourself. Also, the time display for seconds changes not so smoothly, it seems. It can be a problem with my emulator, etc.
• It seems, CLCD has primitive sound, basically a single channel of square wave (technically: timer 2 of VIA#2 is used). However sound is not emulated at all by my emulator at this time.
• Emulator won't remember the state (and virtual 1541) of the previous emulator session after page reload / close. Of course it's not really a bug but the nature of JavaScript, since it runs in your browser only, there is no server side storage (later eg HTML5 local storage can be used to save the state within your browser).
• Emulated LCD screen is somewhat blurry. It's important to note that this is not an effect by intent as someone suggested. This is the browser: it's allowed to use a 2D canvas in different (eg smaller) size and let the browser to scale-up. This is quite essential, as the whole emulation would be lot slower if I want to do the scaling from software (JavaScript). However it seems browsers force antialias and similar things on scaling up, and the script can't control the process. Anyway, maybe it looks even more realistic in this way :)

Usage of the emulator and the CLCD itself

This chapter is about the CLCD softwares itself. Note, that the SHELL, the setup etc, are not the emulator's setup, it's part of the CLCD ROM even on the original machine.

Currently no external disk is emulated. The included softwares can be tested though. After "starting" the emulator (visit the link above) the KERNAL scans for ROMs and you should press a key to continue when you will see the "SHELL" (basically a menu system, somewhat PDA like in my opinion.

Within the SHELL you can navigate between the available softwares with the cursor keys, and you can use enter/return to activate an item. You must choose BASIC to exit to BASIC, and you can use the "exit" command then to return to the SHELL. You can also type anything in the SHELL and by hitting enter/return it will be executed, so you can even type "basic" instead of navigate in the menu system.

The bottom line usually contains inverse "blocks" they refer for the F1...F8 keys. Usually F8 is the exit in all situation. In the SHELL you can use F7 to do some setup, cursor left-right navigates between the various settings, up-down selects the option (no need to press enter, etc just leave the selected - inverse - line where you want), here F8 exists from setup mode.

Setting up the default storage "def stor" can be left for RAMDISK. Since external IEC bus is not implemented in the emulator disk 8-11 won't work. The RAMDISK is a purely software thing (and of course the content won't be preserved on web page reloads ... on a real CLCD it's written that battery backs up even the memory, so normally you can use RAMDISK without problems and need to use external drives (though the low capacity can be a problem ...). However RAMDISK seems to be not work, I have no idea what the problem can be, please read the section "limitations" above about this topic.

The emulator

This emulator is written in JavaScript for modern browsers and it should work on at least latest versions of Chrome, Safari and Firefox (see section limitations above).

All parts of the emulator (even the CPU, VIA emulation) is written by me for this project. As I've stated, the software license is GNU/GPL v3 or possible any later version of GNU/GPL in the future.

At the beginning I've started with a Python implementation of the emulator which was a terminal based solution, and it was awfully slow. But it helped a lot to be able to hack/test my ideas on CLCD. Why would someone write an emulator in JavaScript then? Well, just pick an answer freely:

• I'm dumb.
• I'd like to learn JS better even for my professional work, it's a nice way to learn to write something I'd be interested in anyway.
• No need to code for a custom GUI/API/OS, cross platform easily.

As I've started to write my own JavaScript based Enterprise-128 emulator some time ago, it was a quite logical choice to use JS again ... For a more mature application, some should implement the emulation inside VICE for example. The bonus: you have most components there already: 65C02, VIAs, IEC serial bus & drive, etc emulated certainly a much correct way compared to my quickly written ugly solutions ...