--------------------------------------------------------------------------------
Chameleon Menu System (User Guide)
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
Chameleon Boot Loader
--------------------------------------------------------------------------------

The boot loader is executed once at startup, it's job is to do some basic
initialization:

- load the configuration data from flash
- setup default MMU mapping

if "copy ROMs from c64" is enabled:
- copy c64 kernal- and basic-ROM to chameleon ram

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.geo" (if present)
- load custom ROMs from "CHAM64" directory (if present):
  - "cham64/basic.rom"        C64 basic rom
  - "cham64/kernal.rom"       c64 kernal rom
  - "cham64/chargen.rom"      c64 character rom
  - "cham64/mmc64.rom"        mmc64 bios rom
  - "cham64/rr.rom"           retro replay rom
  - "cham64/fc3.rom"          final cartridge 3 rom
  - "cham64/drive1.rom"       iec drive 1 rom
  - "cham64/drive2.rom"       iec drive 2 rom
- (if present) load a c64 boot program "boot.prg" and execute it (*NA)

- execute the menu system

at startup 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 config
2                                   hold to force fail safe config
3                                   hold to skip menu

after the bootloader 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 bootloader messages.

*NA) not yet implemented.

NOTE:

when skipping the boot loader, a hardcoded default setup will be used (MMC64 +
Retro Replay) which is ment 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 bootloader,
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 below). 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.

limitations:
- MMC, SD, SDHC cards supported (max. medium size: 2TB)
- filesystem must be FAT12, FAT16 or FAT32
- no long filenames

--------------------------------------------------------------------------------
Chameleon Menu
--------------------------------------------------------------------------------

The menu is the main user interface and provides access to all features of the
chameleon core.

general usage:

button                  remote

middle button           cd/tv       hold longer than 0.7s to enter menu
reset                   power       enter menu (if "reset to menu" option is
                                    enabled)

key                     remote      joy #2

<- (arrow left) or      escape                  exit menu/one level up
 "run/stop"
cursor up/down          play/stop   up/down     navigate up/down
cursor left/right       rew/fwd     left/right  enter submenu/toggle item
return                  enter       fire        enter submenu/toggle item

--------------------------------------------------------------------------------

Chameleon Main Menu:
--------------------

hotkey:

F1              Clear C64 Memory        fill C64 memory with zeros and reset
F2              Clear ALL Memory        fill c64 mem,reu,georam with 0 and reset
F3              Reset to Basic          reset with all cartridges and expansions disabled
F5              File Browser            enter file browser (see below)
F6              Monitor (*NA)
F7              Reset with Cartridge    reset with selected default cartridge enabled
F8              Launch Core             start FPGA core
<- (arrow left) restart C64 (unfreeze)  restart currently running program (*1)
                Options                 enter options menu
                Online help (*NA)
                System Info             show some general info

additionally you can press one of the following hotkeys:

0..9            start with cartridge in slot 0..9 (*2)
A..P            start FPGA core slot 0-15

*1) this will either "unfreeze" or "reset with cartridge" depending on wether
    the menu was entered by reset or pressing the menu (freezer) button.

    NOTE: not all options can/will be changed when restarting, see below.

*2) currently hardcoded as

0 - retro replay
1 - final cartridge 3
2 - expert cartridge

(others: no cartridge)

*NA) this feature is not implemented yet

--------------------------------------------------------------------------------

Options
-------

Turbo Mode              enable turbo mode
Turbo Speed Limit       maximum speed if turbo is enabled
Turbo d030 bit          enable emulation of the VIC-IIe (C128) 2Mhz bit

IEC Drive 1 Device ID   set device number for first emulated drive
IEC Drive 2 Device ID   set device number for second emulated drive
IEC bus connection      choose wether the IEC bus of the emulated drive is
                        connected internally or only to the breakout cable (use
                        this if you want to use the chameleon as a standalone
                        drive emulator)
C64 IEC bus             enable / disable the C64s IEC bus. SX-64 users may use
                        this to "disconnect" the internal drive.
IEC bus reset           sends a reset to all emulated IEC devices

MMC64                   enable mmc64 emulation
default Cartridge       set default cartridge used by "reset with cartridge"
Clock Port              select clock port mapping
RR-NET MAC Address      set default MAC Address for RR-NET
REU Size                enable REU and set emulated size
GeoRAM Size             enable GeoRAM and set emulated size

PS/2 Mouse              autodetect or disable emulated mouse
PS/2 Mouse port         set port for emulated mouse

IR Receiver             toggle cdtv ir enable

VGA Mode                set display mode used for VGA output. this features is
                        currently highly experimental and only 800x600 (which is
                        also the default) is expected to work properly.
VGA Mode Test           test selected mode. press return once to switch to
                        selected mode, then return again to confirm or any other
                        to switch back to default mode.
VGA Debug Overlay       toggle vga debug overlay

VIC-II type             choose vic-ii type. this setting has no effect in
                        cartridge mode
VIC-II VGA Output       enable VIC output to VGA. disabling this will allow to
                        use the framebuffer from within a running program.

SID Emulation           select type and mapping of emulated SID(s)
SID Real Stereo Chip    select type and mapping of real SID(s). this setting has
                        no effect in standalone mode.

RTC Time                set current Time (Hours:Minutes:Seconds)
RTC Date                set current Date (Day:Month:Year)
RTC Weekday             set day of week

boot from SD card       enable loading various files at boot time (see boot loader)
boot skips menu         if enabled the c64 starts with default cartridge
copy ROMs from C64      copy basic- and kernal- ROM from C64

Left Button             select function for the leftmost button
Reset goes to menu      if enabled, pressing reset goes to menu instead of
                        resetting the emulated c64

Browser Exec Setup      execution setup that applies when starting programs and/
                        or cartridges via the file browser. "custom" will use the
                        setup from config menu, "compatible" will disable most
                        things and configure a bare stock c64.

Read Settings           read config from flash
Write Settings          write config to flash
restore Defaults        restore default config

back                    go back to main menu

NOTE: all options will generally, and always, get applied when leaving the menu.
however there are some exceptions that apply when the menu was entered by
"freezing" using the menu button and then "unfreezing" the running c64. this is
needed so for example chameleon aware programs can also be interrupted.

- default cartridge setting has no effect when unfreezing (would almost certainly
  result in a crash anyway, and this way interrupting a gamecartridge is possible)

- VIC-II settings have no effect when unfreezing. (this allows to interrupt
  chameleon aware programs that change them)

- turbo settings will be copied from the register(s) to the options when entering
  the menu by freezing. (so they can be changed after freezing, and restarting
  does not alter them otherwise)

a chameleon aware program should generally not touch any of the above settings
(or their respective registers), with the following exceptions (which are handled
by the freezer and not altered when unfreezing):

- enabling config mode
- Register settings (CFGREG)
- Turbo settings (CFGTUR)
- Cartridge settings (CFGCRT)
- VIC-II extension settings (upper 4 bits of CFGVIC)
- MMU settings (all MMU registers)
- VGA settings (all VGA registers) (*NA)

- all Cartridge registers, with the following precautions:
  - freezing during an ongoing SPI transfer (RTC, flash, SD-card) is impossible
    to handle, for this reason the result is completely undefined.
  - freezing while rr-net is in use, and then entering a menu option that uses
    it may result in undefined behavior when restarting.
  - freezing during a REU transfer may be problematic, although the menu itself
    does not use the REU registers.

*NA) not implemented yet, since the vga stuff will get completely redesigned

Note for SX-64 users:
---------------------

- if for some reason the chameleon fails to start the menu system, powercycle
  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, write options and
  powercycle 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
  "bootloader").

--------------------------------------------------------------------------------

File Browser
------------

WARNING: the file browser is still under construction and work in progress

limitations:

- MMC, SD, SDHC cards supported (max. medium size: 2TB)
- filesystem must be FAT12, FAT16 or FAT32
- max. 1023 entries per directory
- max 40 characters per filename (including extension and the dot) are displayed
- max 255 characters per filename are handled before the name is replaced by its
  short 8.3 filename.
- for speed reasons, filetypes will only be determined by looking at the file
  extension (and not by reading their header)

key                     remote      joy #2

<- (arrow left) or      escape                  exit file browser
 "run/stop"

cursor up/down          play/stop   up/down     navigate up/down
cursor left/right       rew/fwd     left/right  choose left or right tab
F1 / F7                 1 / 7                   page up / page down
F2 / F8                 2 / 8                   start / end of list

return                  enter       fire        enter subdirectory, default
                                                action for selected file

F3                      3                       view file
F4                      4                       user menu (see below)
F5                      5                       copy file (*NA)
F6                      6                       copy image

pound                                           select sd-card (device 0)
1..7,8..0                                       select iec device 11-17,8-10
+ / -                                           choose device number

@                                               send DOS command (to IEC drive)

CBM + H                                         show quick reference / help
CBM + P                                         toggle panel size
CBM + R                                         (re)read directory of active panel
CBM + S                                         sort directory of active panel
CBM + M                                         mount image file
CBM + L                                         load file
CBM + E                                         load and execute file. note that
                                                this will NOT mount the image
                                                it is used in and just load the
                                                selected file.
CBM + D                                         delete file or directory (must
                                                be empty)
CBM + N                                         rename file

*NA) not implemented yet

user menu (brought up by F4):

create directory                creates a new directory (only on sd-card)
create empty d64                creates an empty d64 file (only on sd-card)
save GEORAM image               save current GEORAM content to a file
save REU image                  save current REU content to a file

files:  default action: (return)

.d64    enter image
.t64    enter image
.g64    mount
.sid    play sid file
.prg    load and execute. inside images also mount image.
.crt    load and start cartridge image.
.reu    load
.geo    load
.txt    view text file
other   view hex file

files:  mount action: (CBM + M)

.d64    mount disk image on emulated drive (*2)
.g64    mount disk image on emulated drive (*2)

files:  load action: (CBM + L)

.prg    load prg file to c64 memory (*1)
.reu    load REU image
.geo    load GeoRAM image

files:  execute action: (CBM + E)

.prg    load and run prg file (*1)
.crt    load and start cartridge image. supported CRT types are:
         0: generic (8k game, 16k game, ultimax)
         1: action replay
         2: kcs power cartridge
         3: final cartridge 3
         4: simons basic
         5: ocean
         6: expert cartridge
         7: funplay
         8: supergames
        10: Epyx Fastload
        11: Westermann
        15: c64 game system (system 3)
        16: warpspeed
        17: dinamic
        18: zaxxon
        19: magic desk
        20: super snapshot v5
        21: comal 80
        23: ROSS
        28: mikro assembler
        31: stardos
        32: Easyflash
        34: capture
        36: retro replay
        43: prophet64
        51: Mach5
        53: Pagefox
        54: Kingsoft (Business Basic, S'more)

files:  view action: (F3)

.txt    view text file
other   view file as hex dump. this is also the fallback used in some cases when
        a certain action is not available.

files:  copy file: (F5)

any     copy file to opposite panel (*NA)

files:  copy image: (F6)

.d64    write .d64 file to drive (other panel)

note: to read an image from a drive to a file, change to the drive panel and
      then press F6 (on any file).

*1) note that this will NOT mount the image it is used in and just load the
    selected file.

*2) the slot selection interface is under construction. right now when selecting
    a slot when mounting, the respective slot will also be set as the last slot
    available. so if you want to mount several disks, you have to mount the last
    slot last.

*NA) not implemented yet

--------------------------------------------------------------------------------

Monitor
-------

not implemented yet.

--------------------------------------------------------------------------------

Help
----

not implemented yet.

--------------------------------------------------------------------------------
Chameleon Extensions
--------------------------------------------------------------------------------

note: none of the following is implemented yet.

if "chameleon extensions" are enabled in the menu, then one page is mapped to
$d700 - $d7ff. this page is reserved for trampoline code to enable using code
from the menu system (like sd card functions).

some things which are planned:

- a basic extension supporting most chameleon specific features, if possible in
  a way that is compatible with existing basic dialects (turbo, reu, ...)
- a kernal extension for direct (not very compatible, but very fast) sd-card
  access
