Individual Computers Turbo Chameleon 64 User manual

Turbo Chameleon 64
User Manual
Draft Version (Beta 7b)
12/06/12

Contents
1. Contents
1. Contents...........................................................................................................................................2
2. Getting started................................................................................................................................4
2 1 What's in the Box? 5
2 2 Operation in standalone mode 6
2 2 1 Using the docking station 7
2 3 Operation in cartridge mode 9
2 3 1 Operation on a C64 9
2 4 Sound output 10
3. Updating the Chameleon..............................................................................................................11
3 1 Updating using update prg 11
3 2 Updating via USB 12
3 2 1 Preparations 12
3 2 2 Using the updater program 12
3 2 3 Using ChaCo 12
3 3 If something goes wrong 13
4. Overview........................................................................................................................................14
4 1 Flash memory organization 14
4 2 Using disk images 15
4 2 1 Disk slot organization 15
4 2 2 Mounting images 15
4 2 3 Unmounting images 15
4 3 Using cartridges 16
4 3 1 Cartridge slot organization 16
4 3 2 Expert Cartridge 16
4 3 3 Mounting cartridge images 17
4 4 using custom ROM images 17
5. Chameleon Menu System.............................................................................................................1
5 1 Boot Loader 18
5 1 1 Limitations of the boot-loader 19
5 2 Keys 20
5 3 Main Menu 21
5 4 Options 22
5 4 1 CPU Turbo 22
5 4 2 Emulated drives 22
5 4 3 Cartridges and Memory Expansions 23
5 4 4 Input devices 23
5 4 5 VGA output 24
5 4 6 Emulation settings 24
5 4 7 RTC 24
5 4 8 Boot-loader and Menu settings 25
5 4 9 Buttons 26
5 5 File Browser 28
5 5 1 Keys 28
5 5 2 User / File menu 30
5 5 3 Supported File types 31
5 5 4 Plugins 32
5 5 5 Limitations of the file-browser 34
5 6 ML Monitor 35
5 6 1 Features 35
5 6 2 Commands 35
5 7 Online Help 37
5 7 1 Keys 37
5 8 System Info 38
2

Contents
6. ChaCo, the Chameleon Control Software..................................................................................39
6 1 Preparations 39
6 1 1 Linux / Mac OSX 39
6 2 Linux notes 39
6 3 Mac OSX notes 39
6 4 Overview 40
6 4 1 Slot Management 41
6 4 2 Memory Access 41
6 4 3 Debugging 41
6 4 4 Status display 41
6 5 Examples 42
6 5 1 Starting a core 42
6 5 2 Flashing a Core 43
6 5 3 Accessing memory 44
6 6 Command-line options 47
6 7 chacocmd 48
6 7 1 examples 48
7. Frequently asked questions..........................................................................................................49
. known Bugs and Limitations.......................................................................................................52
8 1 Turbo Chameleon FPGA Core 52
8 2 Menu System 52
8 2 1 MMC/SD Card compatibility 52
8 2 2 PRG Launcher 53
8 2 3 G64 Mounter 53
8 2 4 G64 Saver 53
8 2 5 CRT Launcher 53
8 2 6 SID Player 54
8 3 ChaCo 55
8 3 1 Windows 55
8 3 2 Linux 55
9. Reporting Bugs.............................................................................................................................56
9 1 Test Procedure 56
9 1 1 general 56
9 1 2 MMC/SD Card compatibility 56
9 1 3 non volatile user options 56
9 1 4 upgrading the core 57
9 1 5 File-browser 57
9 1 6 Plugins 57
10. Developer information...............................................................................................................5
11. Related projects...........................................................................................................................59
12. Appendix......................................................................................................................................60
12 1 PS/2 Keyboard Key Assignment 60
12 2 PS/2 Keyboard Joystick Assignment 61
12 3 CDTV Remote Control Key Assignment 62
12 4 supported Cartridge types 63
12 5 Opening the Cartridge 64
12 6 Re-programming the USB micro-controller 66
12 6 1 Linux 69
12 7 configuring Quartus for JTAG 70
12 8 Chameleon cable pinouts 75
12 9 Technical Data 77
12 9 1 Turbo Chameleon FPGA Core 77
13. Credits..........................................................................................................................................7
14. Fine print.....................................................................................................................................79
3

Getting started
2. Getting started
Thank you for purchasing an Individual Computers product The Chameleon is one of the most
complex projects that we've ever made for any computer, and it will take much more than this user
manual to explain all the features and possibilities of this cartridge Take your time to read all of this
document
You've been made aware a number of times that the current state of the firmware is beta, and we
appreciate that you've bought the unit anyway If you find any bugs, please report them either
directly to Individual Computers, or to the Yahoo mailing list:
http://tech.groups.yahoo.com/group/chameleon_64/
This is where the developers meet, and where your questions will be answered by the people who
made the cartridge We will also make important announcements on that list, so even if you don't
have anything to report, please subscribe to that list
Please download the latest version of the FPGA Core and ChaCo, the Chameleon Control software,
from:
http://beta.icomp.de/
4

Getting started
2.1. What's in the Box?
•upper left corner: mini USB cable (for data transfers, 180cm)
•middle bottom: Turbo Chameleon 64 :-)
•upper right corner: breakout cable with connectors for USB (power supply, 80cm), keyboard
and mouse (both PS/2, 20cm), IEC (DIN, 20cm)
•a short user manual (which you do not need any more now that you have found this one)
5

Getting started
2.2. Operation in standalone mode
In stand-alone mode, you will need at least the breakout cable to connect to Chameleon, because it
will provide power to the cartridge Make sure that the power supply can deliver at least the 2 5W
(5V and 500mA) that's specified for a USB connection The Chameleon hardware will take about 2
Watts of power, so make sure that your keyboard and mouse don't overload the power supply! Most
PCs don't have any trouble supplying Chameleon with power Note that some PCs don't provide
power without a data connection on a USB port In that case, please use a separate power supply
Connect your monitor to the VGA output By default the Turbo Chameleon 64 FPGA core uses a
standard 800x600 mode with a refresh rate of 72Hz Some monitors don't support this high
frequency Please consult your monitor's manual if you have any trouble with Chameleon's VGA
output
Connect your keyboard to the purple PS/2 connector, and your mouse to the green PS/2 connector
The IEC connector can be left open If you want to use ChaCo with the cartridge, you also need to
connect the mini-USB cable to that PC (see chapter 6 ChaCo, the Chameleon Control Software)
6

Getting started
2.2.1. Using the docking station
The Chameleon docking station extends the available ports of your Chameleon by the following:
–four joystick ports
–one C64 keyboard connector
–one Amiga 500 keyboard connector
Both keyboard connectors are keyed, which means that they have a missing pin in order to help you
finding the correct orientation of the connector However, the A500 keyboard connector is not
always keyed, so you have to take a close look at the colours The black wire of the A500 keyboard
is marked next to the connector Wrong connection may destroy both, the docking station and the
keyboard! Better double-check before you apply power to the unit
All C64 keyboards that we have encountered have been keyed There is no danger when plugging in
the keyboard the wrong way round – you will just observe funny behaviour Caution: This only
applies to the Chameleon docking station! You may actually destroy a C64 if you connect the
keyboard the wrong way round!
Please download and install Chameleon core Beta-7 or higher before you use the docking station
It's available from http://beta.icomp.de/ Older cores will not support the docking station,
and the ports won't be of any use to you For flashing, please disconnect all external hardware:
Remove the mouse, remove the PS/2 keyboard and remove the SD card from the slot Do not
connect the docking station to Chameleon when you're updating the flash!
7

Getting started
There is only one way that Chameleon fits the docking station: It's with the button side up Slide the
cartridge all the way in until the black connector is at least covered half by the Chameleon Make
sure that there's proper contact between the docking station and the Chameleon – the cartridge may
not be tilted at all
Connect the breakout cable and supply power to the whole setup through the USB connector of the
breakout cable Make sure that your power supply is strong enough! With the docking station, we
recommend to use a 5V/1000mA power supply If available, use a 5 2V/1000mA power supply, but
never use any higher voltage than 5 2V Only use regulated power supplies
8

Getting started
2.3. Operation in cartridge mode
WARNING: Chameleon is a C64 cartridge It does not work in the C12 . Don't even try, as this
might cause damage to the computer, the cartridge or both. Don't experiment, it can not work
and you risk damage to valuable equipment that's not covered by warranty
WARNING: Also, Chameleon does not work in cartridge port expanders – neither as the only
cartridge, nor together with other cartridges It will only work if it's plugged directly to the C64
Don't experiment with combinations of cartridges! It cannot work, and you risk damage to valuable
equipment that's not covered by warranty
2.3.1. Operation on a C64
Remove the protective plastic from the Chameleon expansion connector Just push it in and rotate it
until it comes out – be gentle, there's no force required! The brown rubber is glued in place Don't
try to peel it out, it is required if you want to put the protection back in The rubber will not conflict
with the C64's expansion port
9

Getting started
Now insert the cartridge into the C64 expansion port with the buttons facing up Connect your VGA
monitor to the VGA output of Chameleon At this point, we recommend to also connect your old
15kHz screen, so you can compare the output of Chameleon against the output of the original VIC
chip
Use of the breakout cable is optional on the C64 If you want to use a PS/2 keyboard or mouse,
you'll need it
If you want to use the ChaCo software with this setup, you also need to connect the mini-USB cable
to your PC (see chapter 6 ChaCo, the Chameleon Control Software)
Note for SX- 4 users
•If for some reason the Chameleon fails to start the menu system, power-cycle the computer
and hold "2" during power-on This will make the menu use a fail safe configuration (skips
booting from SD card and copying ROMs from C64)
•There seems to be a timing problem that makes copying ROMs from the C64 fail on some
SX-64s, this will result in a crash when exiting the menu system If this is the case, disable
the "copy ROMs from C64" option (see chapter 5 4 Options), write options and power-cycle
the computer Optionally you can enable "boot from SD card" and put a SX-64 kernal (or
whatever else you want to use) ROM image on it (see chapter 5 1 Boot Loader)
2.4. Sound output
Chameleon and C64 each have their own audio outputs, the Chameleon doesn't get the audio from
the C64 and the C64 doesn't get the audio from the Chameleon so each must be connected
seperately
The Chameleon has a stereo output (it can emulate 2 SIDs) You connect it to your speakers with an
3 5 mm stereo-audio plug similar what portable players and many laptops have You need speakers
with build-in amplifier (or separate amplifier as Chameleon doesn't have one)
10

Updating the Chameleon
3. Updating the Chameleon
Each release archive contains a combined ChaCo, core and software update The two files needed
to update manually (* rbf for the core and * bin for the menu and ROMs) can be found in the
UPDATE directory The CHAM64 directory contains files used by the menu system, such as the
online help Just copy the entire directory to your SD card
Updates are made available at http://beta.icomp.de on a regular basis Please make sure
that you are running the latest firmware and are using the latest version of ChaCo before reporting
problems
3.1. Updating using update.prg
Copy the UPDATE directory and UPDATE.PR to the root of your SD card (or simply unpack the
entire release archive to it), insert the SD card and power-cycle the Chameleon (If you are updating
from beta-7a or earlier, run UPDATE.PR from the file-browser )
In addition to the files contained in the release archive, the UPDATE directory may contain the
following custom ROM files:
•“BASIC.ROM" - C64 basic ROM
•"KERNAL.ROM" - C64 kernal ROM
•"CHAR EN.ROM" - C64 character ROM
•"MMC64.ROM" - MMC64 BIOS ROM
•"SLOT1.ROM" - Cartridge slot 1 ROM (*1)
•"SLOT2.ROM" - Cartridge slot 2 ROM (*1)
•"DRIVE1.ROM" - 1541 drive 1 ROM
•"DRIVE2.ROM" - 1541 drive 2 ROM
*1) Cartridge ROMs must be plain binaries (without load address), NOT crt files Files in proper
format can be created by the ROM saver (see chapter 5 5 2 User / File menu ) Cartridges which are
bigger than 64k can not be used in slot 1 and 2, see chapter 12 4 supported Cartridge types for
details To make cartridges readily available for use, the respective cartridge type must be
configured in the settings first (see chapter 5 4 Options)
It is recommended to first test custom ROM files by loading them from SD card (see 5 1 Boot
Loader) before flashing them permanently Flashing broken ROM files may render the C64 or the
menu system unusable
11

Updating the Chameleon
3.2. Updating via USB
3.2.1. Preparations
Before updating your Chameleon, please make sure that it has sufficient power Any and all trouble
that has been reported so far was related to power problems that were caused by external power
draining To be safe, please:
•disconnect the Chameleon docking station
•disconnect the PS2 keyboard
•disconnect the PS2 mouse
•you MUST remove the SD/MMC card from the card slot (else you will get an error message
and can not update)
If you are using a USB charger as your power supply, please make sure it's a 1000mA type
Although Chameleon takes just over 400mA of power, many 500mA types are already at their limit
with a Chameleon If possible, use a 5 2V/1000mA type instead of 5V/1000mA However, do not
go over 5 2V for supply voltage!
3.2.2. Using the updater program
Windows users just double-click the update.exe file in Windows explorer and follow the
instructions on screen
Linux und OSX users may run the respective updater program from a terminal Since the executable
bit of the binary is not preserved in the archive, you will have to set it manually first like this:
$ sudo chmod +x ./update-linux32
After that run the updater as root:
$ sudo ./update-linux32
3.2.3. Using ChaCo
You may also update the Chameleon manually using ChaCo or chacocmd, you can find the required
files in the UPDATE directory (See chapter 6 5 2 Flashing a Core)
12

Updating the Chameleon
3.3. If something goes wrong
First, don't panic :) There is no way to “brick” the Chameleon by updating, the Chameleon might
not start, but it can always be fixed by updating with a valid FPGA core image In case updating
using UPDATE PRG failed (please report this), re-try updating via USB (see 3 2 Updating via USB
above)
If you have trouble flashing, try again Before a re-try:
•Double check that you have sufficient power Maybe try another USB port
•Make sure to select the correct files (when updating manually)
•PLEASE POWER-CYCLE YOUR CHAMELEON It may then give an error-blink on the
red LED, but there's nothing to worry about Updating will fix it
13

Overview
4. Overview
Upon power-up, Chameleon will load the OS from its on board flash It will then start the menu
system which lets you perform various actions (see chapter 5 Chameleon Menu System)
The outermost button (right button) is your reset button The middle button is the freeze and menu
button The left button can be used to perform various actions such as change disks in the emulated
floppy
Press and hold the reset button for more than 0 8 seconds to re-launch the Chameleon core This is
(almost) equivalent to a fresh power-up Press and hold the Freeze button for more than 0 8 seconds
to enter the menu system
Button PS/2 Key remote Function
Left button F11 GENLOCK Multi purpose, see chapter 5 4 Options
Middle button F12 CD/TV Freeze, hold longer than 0 7s to enter menu
Right button PrntScrn POWER Reset, enter menu if "reset to menu" option is enabled
4.1. Flash memory organization
There is a flash chip built into Chameleon that's purely for system purposes and hence can't be
utilized by the user The flash carries FPGA cores and their respective ROM files The FPGA core is
the true core of Chameleon's operations – it defines the hardware behaviour If we fix a bug in the
hardware (such as a VIC effect emulation or register functions of a freezer), we will provide the fix
in the form of an FPGA core file
The size of the on-board flash is 16 MByte, organized in 16 slots of 1 MByte each Every slot can
carry one FPGA core and the corresponding ROM file If Chameleon is powered up, the FPGA is
started from slot number 0
If starting the FPGA was not successful, then the micro-controller will tell you so by sending out a
blink code on the red LED of Chameleon The blink code will tell you which slot was attempted to
be used Just count the number of blinks, subtract one and you'll know which slot of the flash chip is
corrupted If for example slot 0 is corrupted, then the LED will flash once, then pause for a second
and start over If the LED blinks four times, then slot number three is the one you should take a
closer look at
14

Overview
4.2. Using disk images
4.2.1. isk slot organization
There are two emulated 1541 floppy drives of which each handles up to 4 different disk images
which can be mounted via the file browser and then changed by pressing the left button (see chapter
5 4 Options)
4.2.2. Mounting images
Before you can mount a disk image, one of the emulated drives must be enabled, and to use more
than one disk slot per drive, the left button must be configured accordingly (see chapter 5 4
Options)
To mount a D64 or G64 image press CBM+M on the selected image or RETURN on a PRG file
inside an image (see chapter 5 5 1 Keys) You will then be prompted to select a drive and whether to
start a new list (“first disk”) or to add the image to the existing list (“next disk”) for this drive
Starting a new list means that all mounted images for this drive will get unmounted and the selected
image will become the first image in the list for the selected drive
4.2.3. Unmounting images
To write changes made to a mounted image back to the D64 file on SD card you will either have to
make a copy manually (see chapter 5 5 2 User / File menu ) or unmount it by pressing CBM+U (see
chapter 5 5 1 Keys) Also the menu will check if changes to an image have been made when
entering the menu system and when mounting images, and ask whether the image on SD card
should get updated or not
WARNING: If you choose to ignore this the menu system will “forget” about the respective
image being changed and not ask again. You will have to make sure to save the image
manually if you want to keep these changes.
Note: due to the current limits of the drive emulation, G64 images will not get written back
automatically (as the disk layout is not exactly preserved, which would most likely result in a
corrupted G64)
15

Overview
4.3. Using cartridges
Please note that a real-world cartridge consists of two major building blocks: The hardware, and the
software By switching a slot to a specific cartridge type, you merely select the hardware, but you
don't have the contained software yet Real C64 cartridges bring their software typically on
EPROMs, which are emulated in the RAM space of Chameleon Just choosing a cartridge type for a
slot therefore does not mean that you actually can already use the cartridge, because it would appear
like an empty shell to the computer Compared to a real-world cartridge, it can be compared to
removing the EPROM chips from the cartridge and then plugging it into the computer, which will
not work
Note that the EPROM contents of the Retro Replay and Final Cartridge 3 freezers come with every
menu system, which is why you can use these cartridges after power-up and without an SD-card
However, it would be a waste of memory space to keep all the EPROM contents of all supported
cartridges in the menu system: They would not even fit in Chameleon's memory! This is why all
other cartridges require the use of a crt or rom file containing a binary image of the cartridge
EPROM Please see chapter 4 3 3 Mounting cartridge images below for a detailed description of
how to use cartridge image files
4.3.1. Cartridge slot organization
There are 4 cartridge slots Slot 1 and 2 can hold cartridges of max 64k, slot 3 and 4 can hold max
1Mb Slot 1 and 2 will get loaded from flash when the Chameleon boots, by default there is a retro
replay ROM in slot 1 and a final cartridge 3 ROM in slot 2 Additional/other cartridge ROMs can be
loaded by the boot-loader (see chapter 5 1 Boot Loader) or by the CRT loader in the file-browser
(see chapter 5 5 File Browser) Slot 3 is configured as expert cartridge by default, and slot 4 remains
empty
4.3.2. Expert Cartridge
The original expert cartridge has a 3-position switch that is emulated by the left button on the
Chameleon The button configuration must be set to ”cartridge” when using the expert emulation A
short press toggles the expert emulation between ON and OFF (green LED is lit when the cartridge
is on) A long press puts the expert in programming mode PRG (green LED is flashing when the
cartridge is in programming mode)
Please understand that this manual cannot cover the use of all cartridges in detail Using this
cartridge requires software on a disk (image) that is not included with Chameleon
16

Overview
4.3.3. Mounting cartridge images
Cartridge images can be mounted by the boot loader (see chapter 5 1 Boot Loader) or the file
browser In the file browser simply press return on a ROM or CRT file Unless configured to always
use slot 4, you will be asked which cartridge slot to use and the cartridge will be started
Note that ROM files must be in a Chameleon specific layout (which may be different from what
you get from converting a CRT file to binary), you can create such files using the ROM saver in the
file browser (see chapter 5 5 2 User / File menu ) Also when using ROM files, you will have to set
up the correct cartridge type manually (see chapter 5 4 Options)
4.4. using custom ROM images
You may use custom ROM files that replace the kernal, basic and character ROMs of the c64 or the
ROM of the emulated 1541 floppy drives To do this you may either place the respective ROM
images in the CHAM64 directory and enable booting from SD card (see chapter 5 1 Boot Loader
below) or load the respective images through the file browser (see chapter 5 5 File Browser)
Note that loading custom ROM images has several implications For example loading a broken
kernal will make the c64 crash, loading an invalid character ROM will eventually render the menu
system unusable
Also note that the timing of the drive emulation is not perfect yet, which causes problems with some
speed loaders whose timing is very much “on the edge” One such known case is jiffy dos on PAL
setups, which is even unreliable on some real C64s, so problems are expected
17

Chameleon Menu System
5. Chameleon Menu System
5.1. Boot Loader
The boot loader is executed once at start-up, it's job is to do some basic initialization:
•load the configuration data from flash
•set up default MMU mapping
If "copy ROMs from C64" is enabled:
•copy C64 kernal- and basic-ROM to Chameleon RAM
If "UPDATE.PR " is present:
•load and execute "UPDATE.PR " (Chameleon updater)
If "boot from SD-card" is enabled:
•load a custom menu binary "MENU.BIN" (if present)
•load a REU image "BOOT.REU" (if present)
•load a GEORAM image "BOOT. EO" (if present)
•load a custom boot program "BOOT.PR " (if present)
•load custom ROMs from "/CHAM64" directory (if present):
•“CHAM64/BASIC.ROM" - C64 basic ROM
•"CHAM64/KERNAL.ROM" - C64 kernal ROM
•"CHAM64/CHAR EN.ROM" - C64 character ROM
•"CHAM64/MMC64.ROM" - MMC64 BIOS ROM
•"CHAM64/SLOT1.ROM" - Cartridge slot 1 ROM (*1)
•"CHAM64/SLOT2.ROM" - Cartridge slot 2 ROM (*1)
•"CHAM64/SLOT3.ROM" - Cartridge slot 3 ROM (*1)
•"CHAM64/SLOT4.ROM" - Cartridge slot 4 ROM (*1)
•"CHAM64/DRIVE1.ROM" - 1541 drive 1 ROM
•"CHAM64/DRIVE2.ROM" - 1541 drive 2 ROM
and finally:
•if a boot program was loaded, execute it If not, execute the menu system
*1) Cartridge ROMs must be plain binaries (without load address), NOT crt files Files in proper
format can be created by the ROM saver (see chapter 5 5 2 User / File menu ) Cartridges which are
bigger than 64k can only be used in slot 3 and 4, see chapter 12 4 supported Cartridge types for
details To make cartridges readily available for use after loading, the respective cartridge type must
be configured in the settings (see chapter 5 4 Options)
18

Chameleon Menu System
At start-up the boot loader will check the following "magic keys":
key remote
← (Arrow left) ESCAPE hold down when loading core to skip boot loader (see NOTE)
1 hold to force default configuration
2 hold to force fail safe configuration
3 hold to skip menu
After the boot loader has started, hold down any key other than space (since space is used by the
config-ROM for the same thing) to pause before it starts the menu so you can see boot-loader
messages
NOTE
When skipping the boot loader, a hard-coded default setup will be used (MMC64 + Retro Replay)
which is meant for testing and to eventually recover from a broken boot loader and/or menu system
If you press the menu button to enter the menu after skipping the boot-loader, the result will be that
the boot loader will run and initialize the Chameleon the same way as if was not skipped - meaning
various settings may change or even a boot program may get executed
Bottom line: Usually the boot loader should not be skipped If you don't want the Chameleon to
start up with the menu system, use the "skip menu at boot" option (see chapter 5 4 Options) This
will then result in the Chameleon starting up using the settings used in the options menu, and further
freezing/ restarting will work as expected
5.1.1. Limitations of the boot-loader
•MMC, SD, SDHC cards supported (max medium size: 2TB)
•File-system must be FAT12, FAT16 or FAT32
•no long file-names
The limits of the boot-loader do not apply to the file-browser, see chapter 5 5 5 Limitations of the
file-browser below
19

Chameleon Menu System
5.2. Keys
The menu system can be controlled by the following keys / buttons:
Key PS/2 Key Remote Joy #2 Function
<- (arrow left)
RUN/STOP
ESCAPE ESCAPE exit menu/one level up
Cursor
up/down
Cursor
up/down
PLAY/STOP up/down navigate up/down
Cursor
left/right
Cursor
left/right
REW/FWD left/right enter sub menu/toggle item
RETURN Enter ENTER Fire enter sub menu/toggle item
F1 Page up 1 Page up
F2 F2 2 Go to first menu item
F7 Page
down
7 Page down
F8 F8 8 Go to last menu item
20