CDi_MiSTer/README.md

# CDi_MiSTer

A project dedicated to create an FPGA implementation of the Philips CD-i to be usable for the MiSTer FPGA project.
As every Philips CD-i player is based on different hardware, this project focuses on reverse engineering the "Mono I".
This mainboard is used in models like the 210/00, 210/05 or 220/20.

This project also aims to replicate the 22ER9141 Digital Video Cartridge based on the VMPEG hardware.

Most games utilizing the hardware of a base CD-i, should work as expected.
Titles which require the Digital Video Cartridge are considered experimental.

## Usage

To play a title, load a CD and press on the play button at the start screen.
CD images can be stored as CHD or CUE/BIN format.

### Button layout

The CD-i usually has 2 buttons: • and ••
Originally, this project aimed for replicating the `Philips RV 8701 Paddle Controller`.
That has one downside of having no •/•• button, to press • and •• at the same time. Some games really need it.

So instead, this project currently aims for a hybrid of the `RV 8701` and a `Philips 22ER9017 Touchpad`,
which is similar to a `Gravis Ultrapad`. The layout can be compared to a SNES controller without shoulder buttons.
Since the MiSTer is built around the modern PSX layout, this should be pretty accessible.

### Required ROM files

Place `cdi200.rom` as `boot0.rom` in `/media/fat/games/CD-i`.
Place `zx405042p__cdi_slave_2.0__b43t__zzmk9213.mc68hc705c8a_withtestrom.7206` as `boot1.rom` next to it.
Place `vmpega_split.rom` as `boot2.rom` next to it for DVC functionality.

This core is tested against these files and their respective md5sum:

    2969341396aa61e0143dc2351aaa6ef6  cdi200.rom
    3d20cf7550f1b723158b42a1fd5bac62  zx405042p__cdi_slave_2.0__b43t__zzmk9213.mc68hc705c8a_withtestrom.7206
    9694c466f9b65c1990a81b7a6280546b  vmpega_split.rom
    53ba3bf7443187a657baa272d01d3771  vmpega.rom

Due to legal reasons, they must be sourced separately!

To generate the vmpeg_split rom, use this:

    dd if=vmpega.rom bs=1024 count=128 of=vmpega_split.rom

### NvRAM storage

Save files are stored inside an 8K NvRAM. MiSTer will create one save file per CD.
Whenever the NvRAM state changes, the "User" LED will light up, indicating
a change is queued to store. When the OSD is opened, the NvRAM will be flushed to SD card.

The save files containing the NvRAM are compatible with the CD-i emulation of MAME.

### Pointing Devices

The Philips CD-i has support for 3 classes of "Pointing Devices"

* Maneuvering devices -> Gamepad (Digital or Analog)
* Relative Coordinate Devices -> Mouse and Trackball
* Absolute Coordinate Devices -> Light Gun, Graphics Tablet, Light Pen (not yet supported)

Digital gamepads, Analog gamepads and Mice are supported for use with this core.

To switch between Mouse and Gamepad, simply move the Mouse around. The core will switch automatically
by unplugging the current device and plugging in the next.

### OSD

* Audio & Video
  * Video Region
    * PAL/NTSC - essentially a 50/60 Hz switch. PAL is preferred for the CD-i, reset required to apply
  * Aspect Ratio
  * Scale
  * Vertical Crop - Off, On(270) - For improved integer scaling
  * RGB Scale
    * 0-255 - Full RGB range
    * 16-235 - Reduced RGB range (might provide more accurate color / more contrast)
* Hardware Config
  * Ports - Either 1 Player with additional UART, or 2 players.*
  * Disable VMPEG DVC - Reset core to take effect
  * Overclock input device - Increase update rate (no longer accurate, but recommended for games)
  * Fast CD Seek - Skip 20 sector seek delay, a real CDIC always ensures (might be unstable)
  * CPU Turbo - Slightly increases CPU speed (might be unstable)
  * NvRAM live update - Allows loading NvRAM from storage on CD image change without reset (might corrupt NvRAM)
* Autoplay - Injects a kernel module into OS9 to skip the system menu and directly start the title (thx to CD-i Fan for this)

Note*: 2 controllers are an unusual state for a CD-i machine. Keep that in mind.

## Troubleshooting

* My NTSC CRT television set is not getting a stable image
  *  Please switch the core to NTSC and reset via OSD. This should fix the problem.
* The image has a vertical offset
  * Do you have used "NvRAM live update" together with a switch between PAL and NTSC? That might be the cause. Please reset the machine to fix the NvRAM.
* The number of controllers is not updated
  * Do you have used "NvRAM live update" together with a switch between PAL and NTSC? That might be the cause because the info is stored there. Please reset the machine to fix the NvRAM.

## Status

[Statistics generated by Quartus](doc/statistics.md)

### TODOs and known issues

[This core is not yet feature complete](doc/todo.md)

### Usage for CD-i homebrew development?

By the time of writing, an optical drive emulator is not available for physical CD-i machines.
It is therefore encouraged to test on CD-i emulators before burning to disc.
[This core can be used to test your creations to some extent](doc/cdi_homebrew.md)

### Issues with external dependencies

* A dump of the SLAVE 3.2 ROM is required to fix some hacks
  * I2C front panel data is not correctly handled (e.g. Play button)
  * The IR codes from the Remote have the same issue when media control buttons are used.

## FAQ, Issues and Quirks

The production quality of CD-i hardware and software is sometimes questionable.
For this reason, I've created a list of some known quirks, one might suspect of being caused
by emulation errors but are also present on the real machine.

* Is the "Digital Video Cartridge" supported?
    * Please stop asking! >.<
* The map of "Zelda - Wand of Gamelon" has micro jitter during scrolling
    * This also happens on real 210/05 hardware
* "Hotel Mario" seems to have the first samples of every ingame song repeated
    * You have good ears as it is barely noticeable. This also happens on real hardware.
* Some earlier CD-i titles have both stereo channels swapped
    * Yes, according to an [internal memo from Philips](http://icdia.co.uk/docs/mono2status.zip) there
      were manufacturing issues and some early players have the left and right channel swapped.
      This might explain discrepancies.
    * One known quirk is inverted stereo on the "Philips Logo Jingle" of "Zelda - Wand of Gamelon"
* During the rotating transition in "Myst" there are glitched lines at the bottom
    * This also happens to some extent on a real 210/05 hardware and is caused by a misplaced Video IRQ
      The video data is changed while it is displayed.
* When I load a save game in "Burn:Cycle" it plays a short and unclean loop of noise until I do something
    * I thought that was a bug in the core at first too. However, it is actually like this on a real CD-i too.
* The music of Burn:Cycle sometimes has "pops" and "clicks"
    * This game is special. It doesn't play music from CD like most games for this system would do.
    * Small loops of sampled music are loaded from CD, stored in memory and randomly concatenated together
      to create the background music. These samples are sometimes not very "loopable" creating a pop at looping points.
    * This issue is reproducible on a real 210/05 as well
* The music during the Philips Logo animation of Burn:Cycle has broken audio
    * This issue is reproducible on a real 210/05 as well
    * For some reason, it seems to be absent on other models with different hardware, like the 450/00
    * The problem can be fixed by overclocking the CPU
* Burn:Cycle - Random flickery animated text in front of the "Psychic Roulette" credit card terminal
    * This actually happens on the real machine. I also thought this might be a CPU speed issue, considering that
      the flickering disappears if the CPU is slightly overclocked.
* Flashback: The audio and video during the intro are asynchronous
    * This curiously happens on the real machine as well and doesn't even depend on 50 or 60 Hz
    * It seems to be an oversight by the developers when the game was ported to CD-i
* When dying in "Zelda's Adventure" the accompanying sound effect doesn't match the audio data on CD
    * Good catch! This is a programming error which can be reproduced on a real CD-i 210/05 as well,
      which causes the audio playback to start one sector too late.
    * The same phenomenon exists in the "Help cutscene" of "Zelda - Wand of Gamelon"
        * It is not audible in that game, because of silence in the beginning
* The intro music of Zenith is played only on the left audio channel
  * Yes, this happens on a real 210/05 too. To be sure, I've tested it as well
    on a 450/00. It seems to be an oversight by the developers.
* During the cinematic intro of Kether, the screen flickers to black on some frames during the fading slideshows
  * This curiously happens on a real 210/05 too.
* If I mash the buttons really hard when booting up Tetris, I get a colorful glitched screen instead of the Philips Logo
  * Congratulations for this obscure finding. This happens on a real 210/05 too!
* During the intro of "Zombie Dinos vom Planeten Zeltoid", the title text looks like the last row of pixels is missing during the scaling effect
  * Yes, an oversight it seems. The scaling operation is broken, even on the real machine.
* QuizMania - Missing animation graphics during intro and alignment issues during video playback in menu
  * This game seems to have problems with 60Hz/NTSC mode. Both issues can be reproduced using real 210/05 hardware
  * I assume that this was a local production for the italian market and no testing was performed on NTSC machines
* Inside the settings menu on the start screen, there are purple glitch pixels on the right edge of the screen
  * How could they miss this? It is also present on a real 210/05
* Lemmings is running slow on the core when compared to the Amiga version
  * "Oh No!" *Explodes* It is running as slow as on real hardware,
    but it seems that the CPU Turbo fixes this issue and makes it behave
    more like the Amiga version.
* There is a small green artifact at the top left of the Philips Intro in "Lost Eden"
  * I thought that this is a decoding error, but it is actually there on real hardware
* "Lost Eden" hangs for 1-2 seconds when the music restarts
  * This seems to be an oversight by the developers. It occurs on real hardware all well.
* Graphical glitches at the top of the Philips Intro in "Mystic Midway - Rest in Pieces"
  * Yes, those exist on real hardware as well and are maybe hidden by overscan
  * A side note, "Dr. Dearth" was probably filmed in front of a blue screen, but the cut out is not very good.
    Blue pixels at the edges are visible on real hardware as well.
* "The Lost Ride"
  * It sometimes has an unexpected mirrored column of pixels on the right side of the screen
    * This happens on real hardware as well. This seems to be an oversight by the developer.
  * The main menu has a weird freeze frame when the cutscene before that is skipped
    * Like on real hardware. I don't know what they were thinking.
* During the intro of "The Ultimate Noah's Ark", the Mike Wilks artwork has repeated pixels on the bottom and right edge.
  * This looks wrong but real hardware does that too.
  * There is also a weirdly wrong column of pixels during the title page on the left inside the black frame
* "Marlboro – Follow Your Dreams" is not booting and hangs on a cyan screen
  * You are probably using NTSC mode. Being made by a German publisher, this title was probably only tested on European models. It behaves like this on real hardware as well

## Simulation

Even so, the [sim](sim) folder seems to be the correct one, it is deprecated.
It was used for mixed language simulation with the free version of ModelSim when the project has started.

The [sim2](sim2) folder is the current one, used for most development and makes use of Verilator for improved performance.

## Used resources

This MiSTer core would've probably never been possible without the reverse engineering efforts of certain people.
Thanks to [CD-i Fan](https://www.cdiemu.org/) for the insights into his closed source CD-i Emulator.
Also Thanks to MooglyGuy, which took on the task of implementing a CD-i emulator into MAME, which I used to analyse
the program flow of the CD-i boot process.

* https://github.com/TobiFlex/TG68K.C
* https://opencores.org/projects/68hc05
* https://github.com/cdifan/cdichips
* http://www.icdia.co.uk/microware/index.html
* https://github.com/Stovent/CeDImu/blob/master/src/CDI/OS9/SystemCalls.hpp
* playcdi (by CD-i Fan) (auto play for Mono I PCB)