-- gameplaySP  Gameboy Advance emulator for Playstation Portable --


-- Release log --

(legend: # bug fix, + feature addition, @ optimization)

v0.7 - (beta than ever)

# Fixed a dynarec bug involving flags generating functions in
  contiguous conditional blocks. Fixes music in Super Mario
  Advance 2-4.
# Fixed a dynarec bug where Thumb mov imm instructions wouldn't
  set flags. Fixes Zelda: Minish Cap, Megaman Battle Network,
  probably others. Comes at a slight speed cost.
# Fixed a MIPS dynarec bug where some delay slots might not
  get filled rarely, causing chaos. Don't know if it improves
  any games.
# Improved self-modifying code detection. Makes Golden Sun,
  Golden Sun 2, and Madden 2007 sorta work but excrutiatingly
  slowly. Looking for a game-specific workaround for this - if you
  want to play these games you'll have to wait for now :(
# Fixed a bug causing the interrupt disable flag to go down
  when SWIs are entered, causing crashes/resets. Fixes
  Super Mario Advance 2-4.
# Fixed menu crashing when strings with certain characters are
  printed (for instance going to the menu after loading the
  BIOS)
# Accidentally forgot to render win0 + win1 + objwin when all
  active at the same time, many weeks ago. Added that, should fix
  some parts in games that had frozen screens.
# Fixed some issues with gpsp.cfg needing to be present and
  corrupting, hopefully. At the very least sanity checks are
  performed on the config file.
# Made it so assigning the frameskip button to something besides
  triangle actually worked as expected.
# Fixed ability to restart current game if nothing is loaded
  (ie, crash)
# Added interrupt on cpsr modification support to the dynarec
  (fixes backgrounds in Castlevania: Harmony of Dissonance)
# Added open addressing for ldm/stm instructions (fixes
  Super Mario Advance 3)
# Improved cycle accuracy a little. Don't know of anything this
  fixes, but games with idle loops will run a little better w/o
  idle loop elimination (but should still be added when possible)
# Fixed some bugs causing sound to play sometimes when it shouldn't.
@ Added dead flag elimination for Thumb code. May possibly have
  noticeable performance increases (Thumb emited coded size can
  have a reduction of 20% or more)
@ Added code generation for divide SWI. May have a small speed
  increase in some games.
+ Added analog nub support (special thanks to psp298 for the
  code)
+ Added fractional frameskip. Go below 0 to get them. A frameskip
  of 1/2 for instance means render 2 out of every 3 frames, 2/3
  means render 3 out of every 4 frames, etc. Possibly useful for
  games that are not quite fast enough at fs0 but fullspeed at
  fs1...

v0.6 - (still beta quality, look out for new bugs)

NOTE: Please include gpsp.cfg with EBOOT.PBP, this shouldn't be
 necessary but I think it is right now.

# Fixed a nasty bug that shouldn't have made it into the initial
  release; a lot of games that TECM.. erm.. crash won't anymore.
  NOTE: This doesn't mean that no game will ever crash, freeze,
  otherwise not work.
# Fixed some crashes in the GUI and the ability to "go up" past
  ms0:/PSP. Made the "go up" button square like it was supposed to
  be (instead of cross).
+ There's now a menu that you can access, by default press right
  while holding down triangle for the frameskip bar.
+ Menu option: resize screen aspect ratio, the default is now
  "scaled 3:2" which makes it look more like a normal GBA. You
  can use "fullscreen" (what it was like before) or "unscaled 3:2"
  (tiny but pixel for pixel like a GBA)
+ Menu option: You can now load new games while the current one
  is running.
+ Menu option: You can now restart the currently running game.
+ Menu option: Frameskip variation - this defaults to "uniform"
  whereas it defaulted to "random" last release. Basically, turn
  it on random if you find that frameskip causes flickering
  animations to make things disappear. Other than that it will
  generally look better on uniform.
+ GUI and file loading now have "auto repeat" on the buttons so
  they're not such a pain to navigate.
+ Menu option: Added support for 128KB flash ROM, some games
  require it (Pokemon Firered/Leaf Green, Super Mario Advance 4),
  turn it on before running the game to make sure it works.
  NOTE: There are some versions of these ROMs that have been
  hacked to get around their 128KB flash, and may not even work
  properly at all. Look out for them, these games should save
  128KB save files after you set the setting to it, IF they use
  128KB flash.
+ Menu option: Added ability to make the .sav files only update
  when you exit the emulator, use with extreme caution (in other
  words, it's not a good idea to use something like this in beta
  quality software if you care about your saves). Does NOT update
  if you exit through the home button, don't use the home button
  if you can help it.
+ Zip support thanks to SiberianSTAR. It will load the first file
  with the extension .gba or .bin that it finds.
+ Menu options are saved to gpsp.cfg. Note that it does not save
  frameskip options or flash ROM options because these are very
  per game particular.
+ The emulator will now try to save backup files to something
  more matching the backup size than a fixed 64KB.
@ Loading ROMs and the auto save of the .sav files is MUCH faster
  now. Thanks for the heads up on how to improve this from pollux!
@ While coding for the screen resize code I found that SDL just
  wasn't cutting it and had to code for the GU myself. Turns out
  the new code is faster (but because it is render code any
  improvement will be diminished to nothing as frameskip is
  increased). Special thanks to Zx-81 for the tips on this one
  and for his GU code in the PSPVBA source as an example.
@ Added some games to game_config.txt. Note that not all versions
  of these ROMs will work with these options, try to use the USA
  version if possible.

8-19-2006  v0.5 - Initial release (public beta quality)


-- About --

gameplaySP (gpSP for short) is a GBA emulator written completely from
scratch. It is still pretty young (only having started a 3 months ago)
and thus rather immature, but it does a decent job of playing a number
of games. It is currently very minimalistic, in the sourcecode,
presentation, and features. Its number one focus is to deliver a GBA
gaming experience in the most playable way that PSP can manage, with
frills being secondary.

Having said that, optimization was the important way in achieving this
goal, with overall compatability being a near second. Because of this
some games may not run at the favor of running more games significantly
better. Of course, the compatability will improve with time.

Many games will run at their best out of the box, but some games will
run very slowly unless idle loops are taken care of. There is a supplied
ROM database, game_config.txt, that gives idle loop targets and other
settings that may help a game to run better (or at all) on a per-game
basis. Currently (as of the first release) only a very small number of
games are entered. This number should improve dramatically over time.

gpSP currently requires an authentic GBA BIOS image file to run. It will
make no effort to run without one present; this file is 16kb and should
be called gba_bios.bin and present in the same location as the EBOOT.PBP
file. Please do not ask me where to obtain this, you'll have to look
online or grab it from a GBA. Note that it is not legal to have this file
unless you own a GBA, and even then it's rather gray area.



-- Features --

gpSP mostly emulates the core Gameboy Advance system. As of right now it
does not emulate any special hardware present on various GBA cartridges.


What it emulates:

GBA CPU: All ARM7TDMI ARM and Thumb mode opcodes except block memory w/
 s-bit (probably aren't used in GBA games)
Video: Modes 0, 1, 2 almost completely, basic 3-5 support, sprites,
 windows/OBJ windows
Interrupts: HBlank, VBlank, all timers, all DMA channels, keypad
DMA: Immediate, HBlank, VBlank, sound timer triggered
Sound: Both DirectSound channels and all 4 GBC audio channels
Input: Basic GBA input delivered through PSP controls
Cartridges: Currently supports up to 16MB large ROMs (32MB will not load)
Backup: 32/64kb SRAM, 64kb flash, 512bit/8kb EEPROM


What it lacks:

Video: No mosaic, bitmap modes lack color effects (alpha, fades),
 there might be some minor inaccuracies in blending...
Cycle accuracy: Very cycle innacurate; CPU is effectively very
 overclocked, meaning games with rampant idle loops will probably run
 very poorly. DMA transfers effectively happen for free (0 cycle).
 Please do NOT use gpSP as a first source for developing GBA homebrew,
 try No$GBA instead.
Backup: 128kb flash is not currently supported.



-- Controls --

The control scheme is very simple and currently can not be changed.

At the ROM selection screen:

Up/down: navigate current selection window.
Left/right: switch between file window and directory window.
Circle/start: select current entry.
Square: go one directory up.

In game:

Up/down/left/right: GBA d-pad
Circle: GBA A button
Cross: GBA B button
Square/start: GBA start button
Select: GBA select button
Left trigger: GBA left trigger
Right trigger: GBA right trigger
Triangle: Adjust frameksip

In frameskip adjustment:

Hold down triangle to keep up, press up/down to increase/decrease
frameskip, respectively.



-- Frameskip --

Frameskip will only render one out of every (n + 1) frames, where n
is the current frameskip value (so 0 will render everything). Increasing
the frameskip can improve speed, especially with very graphically
intensive games. There is also fractional frameskip (try values below 0
to see it). It will also render one out of every (n + 1) frames, IE
frameskip 1/2 will render one out of every 3/2 frames, or 2 out of 3
frames.



-- FAQ --

Q) How do I run this on my PSP?

A) Provided is an EBOOT.PBP which will run as is on a 1.0 firmware
   PSP or custom firmware that can run unsigned EBOOTs. On 1.5 firmwares
   you must use a kxploit tool to run it (try SeiPSPtool). On 2.0
   firmwares and higher further exploits must be used - see
   http://pspupdates.qj.net/ for more information. Note that I have NOT
   tested this emulator on any firmware version besides 1.5, and it's
   very possible that it doesn't run well, or at all on higher versions.
   Therefore I strongly recommend you downgrade if possible, and use
   Devhook to run games that require > 1.5 version firmwares.

   Be sure to include in the same directory as the EBOOT.PBP file the
   game_config.txt file included and the gba_bios.bin file which you
   must provide yourself.

   gpSP does not run on PSPs with version 2.71 or higher firmware yet,
   nor does any other homebrew executable.


Q) What is a BIOS image file? Why do I need it to run gpSP? Other GBA
   emulators don't require this...

A) The GBA BIOS image file is a copy of a ROM on the GBA system that
   has code for starting up the GBA (it shows the logo), verifying the
   game, and most importantly, providing utility functions for the games
   to use. It is the latter that gpSP needs the BIOS present for. It's
   possible to replace all of these functions with equivilent code, but
   this will take time - in the future gpSP may not require a BIOS image.


Q) I can't find this BIOS image.. please send it to me.

A) Sorry, but you're on your own.


Q) How do I know I have the right BIOS?

A) If you have md5sum you can check if it has this hash:
   a860e8c0b6d573d191e4ec7db1b1e4f6
   That BIOS should work fine. Others might too, I really don't know at
   this point. It's possible that other images will only have partial
   compatability. It's also theoretically possible to use custom
   (and free) BIOS replacements, but I don't know of any publically
   availablone ones.


Q) My favorite game won't run.

A) There probably isn't anything you can do about this, although a
   change to game_config.txt might help. gpSP is still an emulator in
   its infancy so the compatability is not superb. I don't have time
   to test too many games so I'm releasing it as a public beta to get
   a feel for some things that don't work. The next version could
   perhaps fix it, or it might never run. There are always other
   emulators of course, please try one.


Q) My favorite game is very slow.

A) Emulating GBA takes a number of resources and getting it done well
   on PSP is no simple task by any means. Some games are just going to
   overwhelm the emulator completely. Of course, there is one special
   case of game (a lot of early generation games fall under this
   category) that can be made much faster by a simple addition to the
   game_config.txt file. Wait for a new version of this file or the
   next version of the emulator and the game may be improved.

   That aside, there are still numerous optimizations that can be done,
   and I sure you future versions will be faster (I just can't tell you
   how much)


Q) The emulator crashed!

A) Most games that don't run will probably take the emulator down with
   it, or it could be an emulator bug completely unrelated to the game
   (but unlikely). Press home and wait for the next version.


Q) How do I change image quality (resizing), sound quality, controls?

A) Right now, you can't. Wait for a later version. For those wondering,
   sound is locked at 44.1KHz (sounds a bit high? It is, but it's
   currently necessary to play everything correctly.. it'll probably be
   different in the future but this does NOT make as much of a difference
   as one might think)

   UPDATE: As of 0.6 you can resize the screen and change the controls,
   and hopefully as of 0.7 there won't be any issues with the config
   file.


Q) Does gpSP run Gameboy/Gameboy Color games?

A) No. Even though GBA can run these games it uses separate hardware
   that proper GBA games have no access to (save for the audio chip),
   and thus there's no point including it in a GBA emulator (it
   doesn't help run GBA games). I recommend using a GB/GBC emulator
   like Rin for playing these games. It'll probably give you a lot
   more options anyway.


Q) Other emulators use the PSP's graphical hardware to accelerate the
   video emulation. Is this possible for gpSP?

A) I'm honestly not too sure at this point. It's definitely a rather
   complicated procedure, and I don't think it'll be possible to
   accurately accelerate alpha blending. On the other hand, affine
   transformations could perhaps receive a speed boost this way. Any
   solution would have to be hybrid hardware/software, which might be
   possible due to the nature of the PSP's VRAM. Maybe someone will
   be willing to help me think of possibilities here?


Q) Other emulators use the PSP's second CPU to offload the sound
   emulation. Is this possible for gpSP?

A) Yes, but it wouldn't improve it nearly as much as say, SNES9x TYL.
   This is because most of the processing that goes into sound on a GBA
   game is done in the CPU, not in dedicated audio hardware. It could
   help a little, but probably not a lot. Maybe enough to be worthwhile.
   It might also be possible to split the video rendering to the main
   CPU and the main emulation to the secondary one, but there are a lot
   of coherency issues involved.


Q) Why can gpSP only load ROMs up to 16MB in size?

A) This is due to the limited amount of memory on PSP. In the future it
   will be possible to load them by swapping chunks of the ROM in and out
   of memory; in fact, gpSP is designed with this in mind. I just haven't
   gotten around to it yet (and I don't know what the speed impact will
   be like, but I do know that loading from memstick is very slow right
   now...)


Q) Savestates?

A) Sorry, not yet. Probably later.


Q) What's with the zip support?

A) I hear stories that some games work unzipped and not zipped, so you
   might want to try unzipping them if it gives you problems. You also
   might want to try making fresh zips with WinRAR - users have
   reported some higher success rates doing this.


Q) What's with the config file? Should I make it read only?

A) There was a bug in version 0.6 that caused the config file to not
   get updated or get corrupted sometimes. Hopefully this is fixed now,
   but if it DOES get corrupted making it read only can prevent this
   from happening in the future.


Q) So when WILL the next version be released?

A) Sorry, but I almost never announce release dates. Furthermore, I'll
   probably be pretty hush hush on internal development, just to keep
   people from nagging me about it and building too much suspense.


Q) I don't like this emulator. Are there other alternatives?

A) Yes. Try PSPVBA by Zx-81 (http://zx81.dcemu.co.uk/). It probably
   has vastly superior compatability across the board.


Q) I heard there was a version of gpSP for PCs. Is that true?

A) I developed this emulator internally on PC. It might have a speed
   advantage over other PC GBA emulators, although the PSP version has
   more sophisticated optimizations. Most people have fast enough
   computers to run better GBA emulators for PC and gpSP lacks some
   important features (screen resizing) that the PSP version kinda
   hides. Even though gpSP spent a majority of its development
   gestation as a PC app it was always developed with the PSP in mind,
   so the PC version will probably not see the light of the day unless
   I get overwhelming demand for it. (for those looking to build it
   yourself, sorry, it's missing one of the requisite files for this..)


Q) I want to modify gpSP. How can I do this, and am I at liberty to do
   so?

A) Yes, you are, under the terms of the GPL (see the included
   COPYING.DOC). You can download the sourcecode from whereever you
   downloaded this; if you can't find it please e-mail me and I'll give
   you a link to it. I would appreciate it if you contacted me first
   before forking my project, especially if you're just looking to gain
   recognition without adding much to it. It's better to keep all changes
   tidy in one branch of development.


Q) How do I build gpSP?

A) make -f Makefile.psp will build it. You need to have SDL for PSP
   installed, as well as the standard PSP toolchain and PSPSDK. gpSP
   isn't much of a "build it yourself" program so please don't bother
   me much about how to build it unless you have a good reason for
   wanting to do so.


Q) Donations?

A) Very appreciated. exophase@gmail.com on PayPal. <3


Q) How can I contact you?

A) exophase@gmail.com, Exophase on AIM. I'm a very lonely person so
   don't be afraid to get in touch ;P But don't nag me about ROMs or
   BIOSes, and if you hate me and my crappy emulator try to be nice
   anyway, okay?


-- Credits --

Exophase: main developer
siberianSTAR: zip support
psp298: analog nub code

Beta testers for 0.7:
theohsoawesome1
thisnamesucks837
blackdragonwave9
dagreatpeewee
xsgenji


-- Special thanks --

Quasar84: He's helped me in so many ways with this. We both kinda learned
GBA together, he did little demos for me and I got them emulated. It was
great trying out your more advanced code for your own projects once you
got to them, it was equally rewarding to see your work and to be able to
run it at the same time. Least of all I wouldn't have been able to do any
of this without your constant support and presence. I really owe this
release to you.

gladius: You are an amazing GBA coder. I wouldn't have been able to get
through some tough parts without your help. Its been good talking about
ideas with you.. I'm sure you're glad to see that there's finally a GBA
emulator with dynarec ;)


Many, many others of course, probably too many to name, and I don't want
to make anyone feel bad by putting others above them (well, except those
two, heh) so if you think you should be on here, you probably should be!
Just pretend you are for now, and maybe I'll put you here next time.

