--- Disc Image Loader `Kai' for Fenrir ODE ---
An alternate disc image selection and ODE configuration utility, for Fenrir ODE.
 By cafe-alpha
 https://ppcenter.webou.net/pskai/
 http://ppcenter.free.fr/pskai/ (mirror)


1. Overview
==========================================
Fenrir is an Optical Disc Emulator (ODE, a modern replacement for CD-ROM drive)
which uses SD card to store CD image to play on Saturn.
More informations about Fenrir is available at the following page :
    https://www.fenrir-ode.fr/

Fenrir SD card can contain several disc images, and selection of which one to
play on Saturn is done via a loader embedded into Fenrir firmware.
In order to make the usage of Pseudo Saturn Kai features user-friendly, the
configuration job normally done on Fenrir loader is available on Pseudo Saturn
Kai side, thus allowing image selection and selection of cheat codes by only the
usage of a couple of menus.


2. Features
==========================================
The following features are available in Fenrir Loader Kai :
 - User friendly list of disc images available for ODE
 - Automatic selection of previously loaded disc image
 - Cheat codes functionality
 - Save Data Manager
 - Official Fenrir Loader included

Usage of a cartridge is not mandatory : all the features above such as cheat
codes and Save Data Manager are available simply by copying fenrir.kai.iso
executable on SD card.


3. Limitations of Fenrir Loader Kai
==========================================
 3a. Lack of features requiring cartridge ROM
------------------------------------------
The features below are disabled because of of cartridge ROM unavailability :
 - In-game USB transfer with USB dev cart
 - ROM-based cheat codes handler
In practical terms, theses limitations are not invalidant : ROM-based cheat
codes handler is the slowest one, hence enabled only when other can't be used, 
which happens when enabling too many cheats at once.

 3b. Lack of "Load Cart" feature
------------------------------------------
"Load Cart" feature in Fenrir official loader isn't available in Fenrir Loader
Kai for the simple reason that installing Pseudo Saturn Kai on a bootable
cartridge does this job.
As a consequence, usage of legacy firmware such as Action Replay or X-Terminator
isn't supported by Fenrir Loader Kai.

 3c. Incomplete support of hard reset
-------------------------------------
When Pseudo Saturn Kai is booted with fenrir.kai.iso placed on the Fenrir SD 
card, in-game hard reset will usually return to the disc image selection menu.
However, this relies on a very specific trick so it doesn't work with all games. 

When fenrir.kai.iso is booted without a cartridge inserted, in-game hard reset
while holding the A button will return to the disc image selection menu, or
will reset the game itself when not holding any buttons.

In both cases, it is more convenient to use soft reset when that feature is
available in-game.

 3d. Insufficient region bypass
------------------------------------------
Games requiring JHL game loader (for example Panzer Dragoon Saga) are not
covered by region bypass feature. This can be fixed with configuration of the
BIOS Region setting in the Fenrir Configuration menu (accessed by pressing left
shoulder button in the disc image selection menu), which enables on-the-fly
region patching of all Saturn games on the ODE side.

It should be noted that the JHL loader in the cartridge-based versions of Pseudo
Saturn Kai is region-free, hence it is not strictly necessary to configure the
BIOS Region setting when using Fenrir Loader Kai there. 
However, it is still recommended to configure this setting in order to avoid the 
"Game disc/cartridge not suitable for this system" error that prevents returning
to Fenrir Loader Kai. This occurs when loading a game that doesn't match the 
system's region via the CWX or JHL loader and then performing a soft/hard reset.

 3e. Some disc image names are not fully displayed
------------------------------------------
Fenrir firmware cuts disc image name when it is longer than 58 characters and as
a consequence these disc images are not completely displayed in both Fenrir
official loader and Fenrir Loader Kai.

 3f. Lack of extra display methods
------------------------------------------
This release of Fenrir Loader Kai can only display disc image names, but future
version shall display more informations such as region, release date etc.
In the meanwhile of next update of Fenrir Loader Kai, please be patient and
what's more important, please enjoy playing with your Saturn :)

 3g. Incomplete support for Memory Card Plus and EMS 8MEG Cartridge
------------------------------------------
Memory Card Plus and EMS 8MEG cartridge backup memory is recognized only when
CWX loader is used. As a consequence, games requiring JHL loader (Panzer Dragoon
Saga etc) can only access Saturn internal backup memory.

Additionally, as Memory Card Plus not available after in-game soft reset, it is
required to do an hardware reset (with the button on the Saturn) to keep the
ability to access saves on the cartridge after that.

Furthermore, EMS 8MEG cartridge memory is not available after both in-game reset
methods, so it is required to turn the Saturn off and on in order to restore
access to cartridge memory.

 3h. JHL loader unavailable after in-game reset in full firmware
------------------------------------------
If you load a game with the CWX or JHL loader in the full firmware and then
perform a soft/hard reset back to Fenrir Loader Kai, loading another game via
the JHL loader will crash the Saturn.


4. Setup
==========================================
 4a. Note about compatibility with Fenrir firmware
------------------------------------------
Fenrir firmware version 2021/07/02 is at least required to be compatible with
Fenrir Loader Kai. Firmware can be retrieved from the link below :
    https://www.fenrir-ode.fr/firmware.html

There's no warranty that Fenrir Loader Kai will be compatible with future
revisions of Fenrir firmware, so please revert to previous firmware version in
the case Fenrir Loader Kai stops working after a firmware update.

If you require an unsupported firmware, then please consider uninstalling Fenrir
Loader Kai and using the official loader instead.

 4b. About boot cartridge and standalone modes
------------------------------------------
There are two modes of operation for Fenrir Loader, as described below.
 - Standalone mode :
   -> Runs instead of Fenrir official loader
   -> Doesn't requires any cartridge to work
 - Boot cartridge mode :
   -> Installation on boot cartridge such as Action Replay or Gameshark etc

 4c. Fenrir Loader Kai installation : standalone mode
------------------------------------------
Please copy fenrir.kai.iso in the root folder of your Fenrir' SD card.
 [SD card Root]
 |-fenrir.kai.iso    <- this file in the root folder
 |-[My First Game]   (folder)
 | |-IMAGE.CCD
 | |-IMAGE.IMG
 | |-IMAGE.SUB
 |-[My Second Game]   (folder)
 | |-SomeGame.bin
 | |-SomeGame.cue
 
Once booted into Fenrir Loader Kai, press the left shoulder button in the disc
image selection menu and set the BIOS Region setting so that it matches your
console's region.

 4d. Fenrir Loader Kai installation : boot cartridge mode
------------------------------------------
Please install Pseudo Saturn Kai on your cartridge by using flasher utility.
Installation step is similar to normal usage without ODE :
 1. Copy flasher utility to Fenrir SD card
 2. Load flasher utility on Saturn
 3. Follow instructions displayed on screen
For more information, please refer to section 4 of the Pseudo Saturn Kai 
main readme file.

After first run of Pseudo Saturn Kai, it is necessary to change optical disc
type to "Fenrir" in Loader Settings available from main menu. Once in the disc
image selection menu, press the left shoulder button and and set the BIOS Region
setting so that it matches your console's region.

Additionally to installation on cartridge, it is recommended to install
fenrir.kai.iso as detailed in standalone mode setup steps.
This is optional, but required for the following features :
 - Save Data Manager
 - Complete soft reset support
 - Partial hard reset support


5. Fenrir Save Data Manager
==========================================
 5a. Fenrir Save Data Manager : Setup and first usage
------------------------------------------
Fenrir Save Data Manager is a part of Fenrir Loader Kai. For this reason
fenrir.kai.iso must be installed on Fenrir SD card.
Then, Save Data Manager is accessible by pressing L shoulder button in the disc
image selection menu and selecting "Save Data Manager".

 5b. Save Data Export : How-to
------------------------------------------
There are many kinds of backup memory devices existing, and all of them have
their own particularities. This section describes which export method should be
selected from the Save Data Export menu, depending on your particular need.

 - Saturn internal backup memory :
    -> Export Save(s) from Memory Device(s) : [++ ]
    -> Export Saturn Backup RAM             : [+++]

   "Export Saturn Backup RAM" solution is a bit faster if backup RAM contains
   many save files hence should be prefered in that case. Also, it is convenient
   because it exports into a format compatible with a wide variety of emulators.

 - Official memory cartridge :
    -> Export Save(s) from Memory Device(s) : [+++]
    -> Export Cartridge Backup RAM          : [+  ]

   Because "Export Cartridge Backup RAM" is relatively slow, it is recommended
   to select relevant saves in "Export Save(s) from Memory Device(s)" feature.
   In some particular cases, such as usage on emulator or recovery of a deleted
   save, it is then recommended to use "Export Cartridge Backup RAM" feature
   because it saves whole internal structure of the memory cartridge.

 - Floppy Disk Drive :
    -> As only "Export Save(s) from Memory Device(s)" is allowed to export
       saves from this device, choice of export method shouldn't be a difficult
       problem.

 - Boot cartridge :
    -> Export Save(s) from Memory Device(s) : [+++]
    -> Export Save(s) from Action Replay    : [+  ]
    -> Export Cartridge Boot ROM            : [++ ]

   There are a lot of hardware and firmware variations of Saturn boot cartridge
   and consequently the choice of a proper export method requires some care.

   First, use "Export Save(s) from Memory Device(s)" method when saves are
   available from there. If not, use "Export Cartridge Boot ROM" method.
   In case of doubt, use "Export Save(s) from Action Replay" but please note
   that this method is currently experimental and doesn't supports all existing
   compression algorithms too.

   Known problems with "Export Save(s) from Action Replay" method :
    - In the case of Memory Cart Plus and EMS 8MEG firmwares, previously-deleted
      save data might be listed and extraction errors may occur.

   Known problems with "Export Cartridge Boot ROM" method :
    - In the case of Memory Cart Plus and EMS 8MEG firmwares, previously-deleted
      save data may be exported.

   For these reasons, it is recommended to use "Export Save(s) from Memory
   Device(s)" feature with Memory Card Plus, EMS 8MEG Cartridge, and other boot
   cartridges with direct-access backup memory.

   Lastly, as a "tedious but safe method", please consider temporarily copying
   saves to Saturn internal backup memory with the utility provided by the
   cartridge and then export these saves to Fenrir SD with "Export Save(s) from
   Memory Device(s)" method.
   With Action Replay firmware, this utility is available from third item in
   main menu and usually indicated as "MEMORY MANAGER". And when Memory Cart
   Plus (or equivalent) firmware, this is possible to copy saves by opening
   official save data manager (first row, middle icon in multiplayer screen)
   when being kicked there just after SEGA boot logo.

 5c. Save Data Import : How-to
------------------------------------------
In comparison with save data export, it's way easier to import saves on backup
memory device : simply copy the files in root folder of Fenrir SD card, launch
Save Data Manager by pressing L shoulder button in the disc image selection
menu and then selecting "Save Data Manager".

Fenrir Save Data Manager supports many formats of save data, but if the file is
not recognized, or its loading fails then please convert the saves to a common
format (such as BUP or Yabause-compatible raw binary format) with the PC utility
of your choice.

   Known problems with Save Data Import:
    - When browsing the dump file of a boot cartridge such as Action Replay,
      certain save files might be missing. If this occurs, reloading the dump
      file should make them appear.
    - When importing save data from a Memory Cart Plus or EMS 8MEG dump file,
      extraction errors may occur.

 5d. Fenrir Save Data Manager : Limitations
------------------------------------------
 - Access to Action Replay cartridges is limited to save data export : 
   It is not possible to import save files from an Action Replay cartridge to
   Saturn internal memory. That's not a big problem though, since the stock
   Action Replay firmware can already do that.

 - Incomplete support for saves compressed into Action Replay ROM :
   It is not currently possible to export save files from an Action Replay
   cartridge if it gets too full and a second layer of compression has been
   applied. Likewise, it is also not possible to import save files from a
   compressed Action Replay dump.
   Once enough save files have been removed from the Action Replay, this second
   compression layer is automatically removed and these operations can be
   performed again.
   In the case individual save export from Action Replay doesn't works with a
   given flavor of legacy firmwares and/or save data compression scheme, it is
   necessary to manually copy the saves to export into Saturn internal backup
   memory (with save data manager utility embedded into the cartridge) and then
   export to Fenrir from there.

 - Save data import/export is restricted to SD root folder
   Due to a limitation in the Fenrir firmware, it is not currently possible to
   import save data from a subfolder, or export save data to a subfolder.

 - Save Data Import does not work with all save files when Fenrir firmware
   2021/07/02 is used :
   Due to a bug in this version of Fenrir firmware, it is not possible to
   correctly import save files that are larger than 2KB and whose size is not a
   multiple of 2KB. To address this issue, Fenrir Save Data Manager will:
   1) Throw an "Unrecognised dump file" error if you attempt to import a save
      file that is not a multiple of 2KB.
   2) Round exported save files to the upper multiple of 2KB. File header of BUP
      format contains the save data size so this padding is removed when
      importing save files back to a given memory device, thereby preserving the
      integrity of the original data.
   In order to import non Fenrir-compliant save files, please use the
   SaveRepack utility (found in the 'tools' folder in the release archive) to
   inject them into a custom Save Data Manager ISO, then launch the ISO on
   Fenrir and import the save files through there. Finally, you can convert them
   to Fenrir-compliant format by exporting the save files back to Fenrir.
   Please note that internal memory dumps (32KB) and cartridge memory dumps
   (512KB) are unaffected by this bug since their sizes are multiples of 2KB.


6. Credits
==========================================
 - Ced2911
 - CyberWarriorX
 - privateye
