CPCAdvance V0.5
--------------------------------------------------------------------------------
This is an Amstrad CPC emulator for the GBA.
It started as a quick and dirty hack of an existing GBA Z80 emulator.

Features:
 A lot of games can actually be played.
 Supports .SNA snapshots, .DSK disc images, .CDT cassette images and .CPR
 Amstrad Plus / GX4000 cartridges.
 Discs boot through AMSDOS and tapes through the 464 firmware; in both cases
 the RUN" line is typed for you (and "Press PLAY then any key" answered).
 Tapes load at real speed with the cassette signal on the speaker, as a 464
 does - use your emulator's fast-forward if you are in a hurry.
 Two-side tapes and multi-disc games are handled: see "Multi-part games".
 Savestates (Save States-> in the menu, or the quick-save combo).

Bugs:
 Probably a lot.

--------------------------------------------------------------------------------
How to use:
--------------------------------------------------------------------------------
!!! You must supply the firmware to be able to run anything !!!
Put cpc464.rom (32K, OS + BASIC, CRC32:074E07DA) in the ROMS folder, and
amsdos.rom (16K, CRC32:06B89E97) if you want .DSK games - discs are skipped
without it. Freely available firmware:
https://github.com/ColinPitrat/caprice32/tree/master/rom

Optional extras: cpc664.rom (32K, CRC32:EEC1E53E) and cpc6128.rom (32K,
CRC32:EE9F0C98). Bundle either one and the Machine option in the menu can boot
it instead of the 464 - the option skips any firmware the bundle does not carry.
Most games want the 464, but a few only get going on a 6128.

Put your games in the GAMES folder (.sna / .dsk / .cdt / .cpr) and run
build.bat. It bundles the emulator core (cpcadva.gba), the ROMS and every
game into cpc.gba, ready for a GBA, a flashcart or an emulator.
A GBA cartridge can address 32MB, so keep the GAMES folder within that. The
builder still writes a bigger cpc.gba - it warns, and says which media is using
the space - but the part past 32MB will not be reachable on the hardware.

Menu titles come from the filenames: the extension and any "(1987)(Company)" tags
are taken off, and what is left is cut to the 31 characters the menu has room
for - so name the files the way you want them to read.
Files of one game tagged "(Side A)"/"(Side B)" or "(Disk 1)"/"(Disk 2)" are a set,
and the emulator swaps between them at the end of a tape, or when a disc is
missing a sector the other one has.

When the emulator starts, use Up/Down to select a game, then A or B to run it.
Press L+R to open the menu, A to choose, B (or L+R again) to cancel.

Default in-game controls:
	D-Pad:	Joystick.
	A & B:	Fire buttons.
	L:		0.
	R:		1.
	Start:	2.
	Select:	3.
	R+Start:Bring up the on-screen keyboard.

Controller->: Settings for the controller
	Controller: 1P=Joystick1, 2P=Joystick2, Cursor=Keyboard cursor keys.
	Remapping: Use the joypad to select a key and press A to confirm.
Display->: Settings for the display
	Unscaled mode:  Hold R and D-Pad to pan, L and D-Pad to resize.
Other->: Misc settings
	Speed modes:  L+START switches between throttled/unthrottled mode.
	Sleep:  START+SELECT wakes up from sleep mode (activated from the menu or
		5/10/30 minutes of inactivity).
Media: <title>: the side/disc currently in the drive of a multi-part game
	(shows "single" otherwise). Press A to put the next side in by hand.

--------------------------------------------------------------------------------
Multi-part games (two-side tapes, multi-disc games):
--------------------------------------------------------------------------------
Name the files with the usual tags and put them all in GAMES:
	Game (1990)(Company)(Side A).cdt
	Game (1990)(Company)(Side B).cdt
	Another Game (1991)(Company)(Disk 1).dsk
	Another Game (1991)(Company)(Disk 2).dsk
"(Side x)", "(Disk n)", "(Disc n)", "(Disc n of m)", "(Tape n)" and "(Part n)"
are recognised. Files of one title and one media type form a set; every part
is still listed in the menu (side B is sometimes a separate program), and the
emulator swaps between the parts of the set the running game belongs to:
 - Tape: when the tape runs out with the motor running, the next side goes in
   after a short pause (a single-side tape is rewound instead). Games that ask
   you to turn the tape over just carry on.
 - Disc: when the game keeps re-reading a sector that is not on the disc in
   the drive but is on another disc of the set ("insert disc 2"), that disc
   goes in.
 - By hand: the "Media:" line in the L+R menu cycles through the set.
A savestate remembers which part was in the drive.

--------------------------------------------------------------------------------
Bundle layout (cpc.gba), for anyone writing their own builder:
--------------------------------------------------------------------------------
	[ cpcadva.gba core ][ entry ][ entry ]...  (padded up to 512KB if smaller)
Each entry is a 64-byte header followed by the file, padded to 4 bytes:
	+0   "COL",0x1A            magic
	+4   u32 size              payload size (little-endian, padded)
	+8   u8  media             0 = .sna, 1 = .dsk, 2 = .cpr, 3 = .cdt. Every
	                           file goes in exactly as it is on disk - the
	                           emulator reads the .cpr RIFF container itself
	+12  u16 group             multi-part set number, 0 = not part of a set
	+14  u8  side              index of this part within the set (0-based)
	+15  u8  sides             number of parts in the set
	+16  u8  system            1 = firmware ROM (cpc464.rom), 2 = AMSDOS ROM,
	                           3 = cpc664.rom, 4 = cpc6128.rom; 0 = a game
	+32  char title[32]        NUL-terminated menu title
System entries come first (firmware, then AMSDOS); games follow sorted by title.

--------------------------------------------------------------------------------
Advanced:
--------------------------------------------------------------------------------
EWRAM speed: this changes the waitstate on EWRAM between 2 and 1, this
can probably damage your GBA and definitely uses more power,
around 10% speed gain. Use at your own risk!

Link transfer:  Send a CPC game to another GBA.  The other GBA must be in
  multiboot receive mode (no cartridge inserted, powered on and waiting with
  the "GAME BOY" logo displayed). Only one game can be sent at a time, and
  only if it's small enough to send (approx. 128kB or less). A game can only
  be sent to 1 (one) Gameboy at a time, disconnect all other gameboys during
  transfer.

Use an original Nintendo cable!

Pogoshell:
Add an empty file and a BIOS.
Copy cpc.gba to the plugin folder then rename it to cpcadvance.mb
(or compress it to .mbz)  and add this line to the pogo.cfg file:
rom 1 cpcadvance.mb 2
or
rom 1 cpcadvance.mbz 2


--------------------------------------------------------------------------------
Credits:
--------------------------------------------------------------------------------
Huge thanks to FluBBa and Loopy for the original emulator and the builder.
Markus F.X.J. Oberhumer for the miniLZO data-compression library (v1.07,
  http://www.oberhumer.com/opensource/lzo/), used to compress savestates.
