**********************************************************************************************************************
* Kermit v0.4.0004 [PUBLIC BETA]                                                                                     *
* Copyright(C) SilverBull/ASSEMblergames forums, 2006-2010                                                           *
*                                                                                                                    *
* DISCLAIMER: Although great care has been taken during development and testing of this software, I cannot guarantee *
* it'll work as expected on your particular equipment. In addition, although I have written no code to purposefully  *
* destroy hardware or software, I cannot guarantee this not to happen. You - the user of this software - are respon- *
* sible for anything you do with it. This software is provided free of charge, without any warranty of any kind, not *
* even fitness for a particular purpose.                                                                             *
*                                                                                                                    *
* Trademarks are not marked as such. All trademarks mentioned below belong to their respective owners.               *
**********************************************************************************************************************


---------------
1) Introduction
---------------
Kermit is a combined system-level debugger, cheat engine and optical disc emulator (ODEM) for use on Sony's
PlayStation 2. It is accompanied by a collection of PC-side software that can be used to interact with the PS2 via the
EE's SIO or the built-in i.Link/Firewire/1394 port. Other communication ports of the PS2, like USB or Ethernet, cannot
be employed for Kermit; if other software is running while Kermit is active, it may use these ports in any way it sees
fit.

The PS2-side software has been developed entirely using open-source software, tools and libraries, which have been
provided independent of this project by members of the PS2DEV community (ps2dev.org). The provided ELF is believed
to be free of any binary code owned or developed by Sony, besides certain code sequences ("patterns") that had to be
inserted in order to let Kermit find the locations in PS2 memory to install callbacks. In order not to infringe Sony
copyright, these patterns have been kept to the bare minimum needed, at the discretion of the authors.

Main features of Kermit include the following:

- PC communication while PS2 software is running (both EE SIO and 1394 supported)
- PC communication while PS1 software is running (EE SIO and modchip required, may be incompatible with certain chips)
- Dumping and Hex Editing of live memory (via PC connection)
- Gameshark-like cheat codes (via PC connection)
- DECI2 support for retail PS2s (PS2-mode only, requires parts of a TOOL BIOS for IOP side, IOP side still bugged).
  This allows using Sony-provided programs like DSEDB (and, partially, DSIDB) on non-TOOL machines.
- HDL-style disc emulation from IDE HDD (both PCMCIA and Expansion Bay-type models supported). Image partitions can
  be made bootable if certain requirements are met


---------------
2) Requirements
---------------

2.1) PS2-side:
--------------
- Any console from the range from SCPH-/DTL-H1x00x up to 5000x
  - Newer slimline models may work, but have not been tested
  - 1394 is only available up to 3900x
  - Kermit is known to interfere with certain modchips. When using a Crystal Chip, be sure to use SHUTDOWN "MM" before
    launching Kermit, or the system may crash. Other modchips may or may not work.
- OR, alternatively: A PS2TOOL/DTL-T10000
  - Kermit may also work on the Performance Analyzer DTL-T15000, but couldn't be tested due to lack of hardware
  - TOOLs require additional setup steps, as detailed in section 3 below

- For ODEM:
  - Internal or external IDE HDD setup, depending on the console. For the 10k series, a corresponding PCMCIA card
    as well as an external power supply for the HDD must be used. For later models, a network adapter is required.
  - The employed HDD can be an official Sony-sanctioned one, but it does not need to. Please note, though, that there
    are additional caveats when using the HDD-enabled Sony Browser with non-Sony HDDs.
  - Bootable Kermit partitions require additional setup steps (please refer to section 3 below)


2.2) PC-side:
-------------
- Microsoft Windows XP SP2
  - Earlier or later versions or patchlevels might work as well, but have not been tested
- Microsoft .NET Framework 2.0 SP1 Runtime/Redistributable
- 1394 Device Driver (for 1394 communication only; supplied in the Kermit distribution)
- Hex Editor (only necessary if you intend to use ODEM on a TOOL)


---------------
3) Installation
---------------

3.1) Overview
-------------
Kermit needs to be installed on both the PS2 and the PC in a certain way to work correctly, as described in sections
3.2 (PS2) and 3.3 (PC) below. In addition, if one of the following applies to you or your setup, you must perform some
additional steps:

- You want to use Kermit on a PS2TOOL (please refer to section 3.4 below)
- You want to make ODEM Disc Image Partitions bootable from the HDD-enabled Sony Browser/OSD (section 3.5 below)


3.2) PS2-side
-------------
Kermit contains code to check from which device and directory it has been started, but unfortunately most homebrewn
launchers do not pass this information correctly when starting from anything but CDVD or MC. Therefore, I suggest to
always place the Kermit ELF and all secondary support files onto a memory card, even if your machine has a HDD
installed.

TOOL-specific note: you can use the "host?:" file system instead of a memory card

To install Kermit to a memory card:
- Copy the complete folder \PS\mc0\KERMIT from the distribution archive to one of your memory cards
  - The slot in the PS2 doesn't matter, as long as your loader passes correct information to Kermit (uLE does :)

TOOL-specific note: you can copy \PS\mc0\KERMIT somewhere onto your development PC instead

Don't take your memory card out yet in case you want to make bootable ODEM Disc Image Partitions, as you'll need to
perform additional steps as described in section 3.5 below.


3.3) PC-side
------------
3.3.1) Basic Installation
To install Kermit:
- If you have not already done so, install the Microsoft .NET Framework 2.0 SP1 Redistributable
  - Be sure to run Windows Update afterwards and download/install all offered .NET patches
  - It *SHOULD* also work to install the 2.0 Redistributable (without "SP1" in the name) first, then perform Windows
    Update until it doesn't show any outstanding/required .NET patches
- Copy the complete folder \PC from the distribution archive to your PC's drive, and make sure it is writable for the
  user you wish to run Kermit as
- Install the 1394 driver from \PC\1394 once requested by the system (please read on :)

If you want to use 1394 for communication with the PS2 (and I suggest you do), the system will prompt you to install
a driver for a "SilverBull Kermit Processor" device at the first time you connect a PS2 with a running Kermit instance.
The corresponding driver can be found in \PC\1394. Be sure to specify to Windows that it should NOT automatically
search for a driver, but you want to specify one manually. Then, point the install wizard to the \PC\1394 folder, and
Windows should take that driver.

The contained driver has not been signed, so it might refuse to install on systems that require driver signing. In
this case, you need to lower the corresponding system security setting to also accept unsigned drivers. To do so, go
to Control Panel, System, Hardware tab, Driver Signing, and set the policy level to Warn.

3.3.2) Compiling the 1394 Driver yourself
In case you do not feel comfortable installing a driver from an anonymous source like me, you might also choose to
compile the driver yourself. I'm currently using a famous Microsoft sample driver for Kermit, so you won't loose any
functionality this way. Compiling is described in the remainder of section 3.3; if you want to use the provided driver
instead, you can skip the following parts. 

To compile the driver yourself, begin by downloading the latest Microsoft WDK that still targets your operating system;
e.g., WDK 6001.18002, available at the time of writing via connect.microsoft.com, is usable for our purpose for Windows
XP and later. Then, perform as follows:

- Build the 1394diag sample using the respective build environment; you can use the "Free" variant instead of "Checked"
  if you do not want your driver to include debug information. To do so, open the build environment, navigate to
  <WDK>\src\[wdm\]1394, then type "build"
- Once compiled, copy the SYS files (1394diag, 1394vdev), 1394api.dll, 1394vdev.inf and win1394.exe into a new folder.
- Patch your copy of 1394vdev.inf the following way:

  - Insert the following line into the [Strings] section
    1394\SILVERBULL&KERMIT_PROCESSOR.DeviceDesc="SilverBull Kermit Processor"
  - Insert the following line into the [Microsoft.NTx86] section
    %1394\SILVERBULL&KERMIT_PROCESSOR.DeviceDesc%=1394DIAG,1394\SILVERBULL&KERMIT_PROCESSOR
  - Check that after the "=" the string "1394DIAG" until the following "," matches with all other lines in that
    respective section. If it doesn't you might have a different version of the INF that needs different patching.
    
You should now be able to point the driver installation to the directory containing your newly-compiled drivers and
patched INF, and it should install the 1394diag.sys driver for the Kermit Processor device.

NOTE: The above example assumes you are using a 32-bit x86 installation, so it only patches that part of the INF. The
1394-specific part of the PC-side software does not support 64-bit operating systems at this time (mainly because I
don't have the equipment yet to test it).


3.4) Installation for use on a TOOL
-----------------------------------
The TOOL's BIOS is considerably different from a retail machine, up to the point where homebrewn PS2 libraries like the
ones Kermit has been linked to do not work anymore. Therefore, if Kermit is running on a TOOL, it has to load the
corresponding BIOS parts itself, via the "host" file system.

The following instructions assume that you have a dump of a retail machine's BIOS (ROM0 only) named "retail.rom0", as
well as a dump of the corresponding TOOL's BIOS named "tool.rom0" (you can use the respective t10000-rel???.bin file
if you have access to it). You'll now use the ROMFS program that is part of the Kermit distribution to extract certain
files of your two BIOSes

Open a command prompt on the PC having the installation from section 3.3, navigate to the \PC folder, then execute
the following commands (you might want to change the paths to retail.rom0 and tool.rom0 according to your installation,
but everything else should stay the same):

    mkdir outdir
    romfs x retail.rom0 outdir -f "^SIO2MAN$" "^PADMAN$" "^MCMAN$" "^MCSERV$" "^FONTM$"
    romfs x tool.rom0 outdir -f "^SYSCLIB$" "^UDNL$"
    romfs mk-ioprp retail.rom0 outdir\IOPRP.IMG
    romfs mk-tool-eeloadcnf retail.rom0 outdir\EELOADCNF tool.rom0

Afterwards, open outdir\UDNL in your favourite hex editor and search for the following hex characters (these should be
relatively close to the start of the file; for t10000-rel300.bin, they are at +0x118):

    03 00 62 10 01 00 C6 24 08 00 E0 03 01 00 02 24
                                         |
Change the marked byte from 01 to 00,    |
then save the file                       |
                                         |
    03 00 62 10 01 00 C6 24 08 00 E0 03 00 00 02 24

NOTE: Strictly speaking, you don't need to patch UDNL unless you want to use ODEM on the TOOL. However, I thought it'd
be better not to mention this before, as it'll surely cause confusion if people choose not to do this, then want to try
ODEM somewhere in the future after having long forgotten that they need to patch UDNL to do so :).

With your outdir prepared this way, you basically have two choices now, depending on which programs you intend to use
to access your TOOL:

- If you want to use Sony's PS2 SDK (DSEDB or DSEFILESV), you need to copy the entire contents of outdir into your
  Linux home directory.
- If you want to use Kermit's DSFILESV, you need to make a directory named "~" under your intended DRFP root, then
  copy all files from outdir into that directory.
  
NOTE: I highly recommend you also copy retail.rom0, tool.rom0 and romfs.exe into outdir, then place it somewhere safe
outside the reach of DS[E|I]FILESV or other programs. Just to be sure you don't need to perform these steps again :).


3.5) Preparing the Boot Loader for ODEM Disc Image Partitions
-------------------------------------------------------------
If you want to make disc image partitions installed by Kermit bootable from within the HDD-enabled Sony Browser, you
need to prepare the corresponding encrypted boot file first, then copy it into the same directory that already contains
the Kermit ELF and support files (the one you were supposed to create on a memory card in section 3.2 above). Please
note that these steps are completely optional. If you don't do this, your disc image partitions won't be bootable, but
ODEM will still work if started via the Kermit GUI.

For these steps, you'll need the following:

- The "embed" tools developed by neme at psx-scene.com. v1.3 works perfectly, but v1.2 should be fine as well.
- An encrypted (unchanged) DVDELF from a "fat" PS2 console (non-slimline) of the same region you want your ODEM
  partitions to be bootable for. This is the big DVDELF (~1.2MB), not the small one (~75KB) of the slimlines.
- A fully-decrypted version (including MagicGate header and decrypted bittable) of said DVDELF
- The file hddload_mono.elf from \PS\mc0\KERMIT of the Kermit distribution archive

Now, open a command line and navigate to the directory containing neme's tools. Assuming your files are reachable via
paths "E\DVDELF" (original DVDELF), "E\DVDELF.DEC" (decrypted DVDELF) and "hddload_mono.elf", respectively, run the
following commands (tested on v1.3R1 of neme's tools):

    embed E\DVDELF.DEC hddload_mono.elf -o HDDLOAD.KELF.dec
    build E\DVDELF HDDLOAD.KELF.dec
    ren osdmain.elf HDDLOAD.KELF

This should produce a file named HDDLOAD.KELF having the same size as DVDELF (~1.2MB). Copy this file into the folder
on your memory card containing the KERMIT.ELF (the one created during section 3.2). From now on, the command "Save
HDDOSD Data" from a disc image menu of the ODEM Manager makes partitions bootable.

NOTE: As with FreeMCBoot, the generated HDDLOAD.KELF does only work on consoles from the same region the original
DVDELF came from. There is no known method to create partitions that are bootable on two different consoles from
different regions.

TOOL-/TEST-specific NOTE: Although Kermit can install a HDDLOAD.KELF onto a partition, the TOOL cannot boot such a
file. There is no usable DVDELF for TOOLs, and even if there were any, most TOOLs (as well as TESTs) do not support
the necessary commands for file decryption.


---------------------------
4) Basic Usage Instructions
---------------------------

4.1) Starting Kermit on the PS2
-------------------------------
Begin by starting KERMIT.ELF on the PS2. The exact steps depend on your setup; I generally suggest to use uLE unless
you have specific reasons to do otherwise. Here are some examples:

- Generic retail console: FreeMCBoot to patched OSDSYS, then use a direct boot entry for Kermit or uLE
- My DTL-H10000 doesn't like uLE, so I have to use ps2link. Once its running, use ps2client to load SIO2MAN, MCMAN and
  MCSERV (in this order), then make it run KERMIT from memory card.
- TOOL: DSEDB's RUN command, or Load/Exec from Kermit's PC-side application.
  - Please note that DSEDB's RUN doesn't like the compressed KERMIT.ELF because of the partially-invalid file format
    ps2-packer emits. You can use \PS.TOOL\KERMIT-TOOL.ELF instead :)


4.2) Kermit Operation on the PS2
--------------------------------

4.2.1) The Main Menu
Upon start of KERMIT.ELF, you should see the splash screen, followed by the main menu. You have the following choices
now:

- If Kermit is not active on the machine, you can set an initial configuration. Settings won't take effect until you
  choose "Start DBGCORE and Exit", which'll take you back to the Sony browser with Kermit running in the background.
- If Kermit is already active on the machine, you can change its options (like enable Comm Throttling if you forget it
  the first time :)). Use the "Set Config and Exit" command if you are done and want to save your settings.
- If you want to use ODEM, select the "ODEM Manager" menu entry. This'll bring you to a new menu system, as will be
  explained in section 4.2.2.

For each setting, the buttons that can be used to change it or perform some actions are listed at the bottom of the
screen. Settings in the main menu are divided into the following categories:

- "General Settings" control overall operation of DBGCORE. You can shut down or throttle host communication if you
  like or enabled/disable certain hooks. Choose options according to your needs or in case you experience problems
  with some games. There are some dependencies upon these options, though:
  
  Host communication is necessary for, well, host communication. If you set it to OFF, your PC won't be able to send
  commands to the PS2 (or, obviously, control the DECI2 debugger).
  The SifSetReg and V_COMMON hooks are necessary for DECI2 debugging, and should generally be turned on unless there
  is some specific reason to turn them off. They are also used to notify DBGCORE that it should poll the host
  connection, so the PC may not be able to communicate with the PS2 if too much hooks are disabled.
  Halt on ExecPS2 does exactly as its name suggests: it lets the console run into either a Kermit HALT or EE DECI2
  breakpoint. Use this carefully (e.g., to debug program startup code), or your system may hang indefinitely.
  
- "Serial I/O Settings" control the EE's SIO port. You can set its baudrate or prevent Kermit from using SIO (while
  keeping the 1394 interface active).
  
  NOTE: Be sure that both the PC-side and the PS2 use the same baudrate.
  
- "Firewire Settings" lets you disable 1394 while keeping SIO active. This might be useful if you want to debug a game
  that uses 1394 itself.
  
  NOTE: This has never been tested, as I don't have access to such a game.

- "DECI2 Bridge Settings" controls how Kermit interacts with the console's DECI2 subsystem. Generally, the EE and IOP
  use completely separate DECI2 software, and Kermit can communicate with both of them independently. EE DECI2 is
  assumed to be stable, while IOP DECI2 is not; enable this at your own risk.
  
  NOTE: You need to enable the SifSetReg hook, V_COMMON hook and IRX loading under "General Settings" for IOP DECI2 to
        work. You also need to extract the DECI2 file (and, possibly, DECI2DRS) from a TOOL ROM and place it into the
        same directory as the Kermit ELF. Without a DECI2 Manager, IOP DECI2 doesn't work, even if all the other
        modules mentioned in this section are active.
  
  NOTE: PATCHMAN is highly experimental and should be turned off.


4.2.2) The ODEM Manager
The main purpose of the ODEM Manager is to show a list of game disc images installed on the system's hard drive. You
can select an image for emulation from this menu, or you can install new games (currently only from the console's CDVD
drive) or delete existing ones.

If you press RIGHT on a game entry, the corresponding Image menu is displayed, which contains additional tasks that
influence that specific image only:

- "Show partition information" is meant as a debugging aid. It displays various information about the game partition,
  like information from the HDL partition header or absolute sector numbers of the data sectors.
  
- "Compatiblity Flags" is similar to the corresponding section from HDL, although Kermit ignores most of them. I
  generally recommand to disable all these options for ODEM, as they are not really needed.
  
  NOTE: "Disable DVD9 Support" is broken and should always be turned off. ODEM includes correct DVD9 support, so no
        "flattening" or "rebuilding" of game ISOs should be necessary.

- "Configuration Maintenance Tasks" can be used to save the current Kermit configuration (from the main menu) to the
  image partition, or delete the existing configuration block. This needs to be used if you want to create bootable
  partitions (see section 6 for details).
  
- "Image Maintenance Tasks" is used for everything else one can do to images: rename and delete. The option to make an
  image partition bootable can also be found here.

Once a disc image is selected for emulation, you can set various ODEM options via the main menu:

- "Launch method" should generally be set to "Standard", unless you know exactly what you are doing. For the very first
  SCPH-/DTL-H10000 machines, "OSD Patch" is preselected and should be used. "System Restart" is not advisable, but it
  may come in handy if everything else fails to start a game.
  
- "EE Initial Breakpoint" is similar to "Halt on ExecPS2", but only influences ODEM. This is useful for debugging
  game's startup code.
  
- "HDD Transfer Mode" specifies the method and speed used to read from the HDD. UDMA4 should work for almost all games,
  but in case some games hang, you might try to lower this setting.
  
  NOTE: An unpatched FFXII image works on my DTL-H10000 only @MDMA2, not UDMA4. However, it always fails to start on
        my TOOL, regardless of the transfer mode.
        
- "Stream implementation" and "Active stream state" should generally be set to async/spin.


4.2.3) Running Kermit on a TOOL
Kermit fully supports running on a PS2 TOOL, as long as certain rules are followed. As written in section 3.4 above,
both the Kermit GUI and ODEM need parts of a retail machine's BIOS to work; if these files are not available, Kermit
will simply hang.

Kermit uses the "host0:" file system (DECI2 protocol type DRFP0) to read needed files, so a corresponding server must
be registered at the TOOL's DSNETM for the program to work. Depending on which programs you intend to use with Kermit,
you can do the following:

- If you are using Sony's PS2 SDK, either use DSEDB to run Kermit, or activate DSEFILESV. In each case, make sure the
  files created in the outdir directory from section 3.4 are present in your Linux home directory.
- For Windows users, you can employ DSFILESV that is part of the Kermit distribution archive:

  dsfilesv -d <TOOL's IP> -p drfp0 -l -ro <DRFP root directory>
  
  In this case, <TOOL's IP> is the IP address or DNS name of the TOOL (needed only in case the DSNETM environment
  variable is not set), and <DRFP root directory> is a directory serving as the virtual root for the file system
  available via DRFP0. As written in section 3.4, this directory must contain a subdirectory named "~" that itself
  contains all files from outdir.
  
  NOTE: Make sure the tool.rom0 you used to create EELOADCNF, as well as extracted SYSCLIB and UDNL from, is the same
        version as your TOOL's flash. If you are unsure, you might use Kermit's PC-side part (EE DECI2 with the "Tools\
        Path EE DECI2 DMA" command, or IOP DECI2) connect to your TOOL and dump its rom0.


4.3) Kermit Operation on the PC
-------------------------------

4.3.1) Device Connections
The PC-side software uses virtual device connections to control a PS2. It currently supports three types of devices:

- 1394, via either the 1394diag (KERMIT.SYS) or 1394vdev driver. If a PS2 running Kermit is connected via 1394, it
  should appear as an entry in the 1394diag device list.
- SIO, via a regular serial port connected to the EE. Serial ports always appear in the Kermit GUI because the software
  does not have any means to check whether there's actually a PS2 connected.
- DECI2, using either the EE or IOP as a target. If you have a TOOL, you can control it directly, by connecting to the
  same IP address or DNS name you'd use for DSEDB or similar utility. If you have a retail or TEST machine, you can set
  up two Kermit instances like this: use the first one to use 1394/SIO and run DSNETM simulation, then use the second
  one to connect to the first via EE/IOP DECI2. This configuration is described in section 4.3.3 below.
  
The list of available devices is generated upon program start. If you connect your PS2 later, use Connection\Rescan to
update it.

NOTE: Sometimes, when using 1394, the PS2 is not recognized by the PC. In this case, unplug and replug the 1394 cable,
      then use the Rescan command again if necessary.


4.3.2) Basic Operation
Most Kermit commands are only available when connected to a PS2, but there are exceptions:

- Kermit implements a rudimentary text editor with syntax highlighting for common programming languages.
  
- The ROMFS menu provides a means to analyze PS2 ROM dumps (like ROM0 dumps, IOP Replacement Images and so on). This
  is the graphical interface to most of the commands offered by the command-line utility romfs.

Once connected to a PS2, you can do the following:

- Dump memory via the "Memory Dump\Dump live memory" command. This copies an entire region of the target's memory into
  a temporary file, which can then be used for the usual commands (search value, compare with different dump, ...).
  Dumps are identified by ID as shown in the Dump window. When comparing dumps, a new one known as a "state dump" is
  created; if you open one dump in the integrated hex editor, you can use "View\Overlap state dump" to highlight
  changes found in a comparison. "View\Go to (next/previous) mark" jumps to the next/following marked section.
  
- Edit live memory via "Memory Dump\Open live memory editor". The difference to a memory dump is that only a section of
  the PS2's addresses are visible, and all changes made in the hex editor are sent immediately to the console.
  
- The Break and Continue command from the Debug menu are used to halt a PS2 or resume operation, respectively. Halting
  a PS2 via a DECI2 target is equivalent to a break-in via the corresponding Sony debugger; i.e., the machine will
  invoke a breakpoint at the next opportunity. If you are using a 1394 or SIO connection, the machine will simply halt
  at DBGCORE's next attempt to communicate with the PC.
  
- Remaining commands from the Debug menu resemble what you'd expect from a normal debugger. This includes things like
  step-in or step-over, as well as the ones to view breakpoints and registers. "Symbol tables" provides a means to load
  debugging information for programs; if a symbol table has been loaded, Kermit displays certain named in hex editors
  (if set to disassembly mode), and also allows source-level debugging if "Debug\Source mode" is active and the source
  file for the instruction at the current instruction pointer is known.
  
  NOTE: Kermit currently only supports native debug information for the ELF format (names only, not source lines) as
        well as STABS (names+source lines). Therefore, you can debug IRXes in source mode if they have been compiled
        using the current open-source ps2dev toolchain with -g, as the compiler generates STABS for them. However, if
        you want to use source mode for debugging EE-side code, you need to set -gstabs for ee-gcc, as it uses DWARF
        as default format for -g which Kermit cannot parse.

- The "Watch" window from the debugger menu is particularly interesting, because it allows you to evaluate arbitrary
  (almost; that means everything minus those I have forgotton or screwed up :) C expressions. It is also aware of type
  information loaded from symbol tables, and can display structured data if the expression has the correct type or is
  casted appropriately.
  
- "Tools\Show IOP (module|library) list" provides a quick way to inspect IOP memory. Data is read directly from the
  target, without going through appropriate DECI2 facilities (even if the are available), so this command is always
  available as long as the IOP is accessible. In the current version, function names for library exports are not
  resolved, so all names display using library name and export index only.
  
  NOTE: When connected to a TOOL via EE DECI2, these commands are not available because the DECI2 implementation in
        the TOOL's kernel is broken. To repair it, use "Tools\Patch EE DECI2 DMA".

- If you are connected via EE DECI2, you can use the Video RAM commands from the Tools menu to capture contents of the
  VRAM. The suggested procedure is to use "Dump Video RAM" once to copy VRAM to the PC, then use "Tools\Display Video
  RAM" (or the equivalent "View" button from the dump window's toolbar) to open subviews. If a subview exists, it is
  automatically updated if its parent dump is updated, using the same buffer options.
  
  NOTE: The "Buffer configuration" displayed in the "VRAM View Options" window uses the same parameter encoding as the
        corresponding library function from the official PS2 SDK (sceGsSetDefStoreImage). That is, the VRAM is
        mapped from a linear buffer to a two-dimensional graphics surface, then each access is performed in this
        two-dimensional space.


4.3.3) Using the DECI2 Debugger on Retail and TEST Machines
As already mentioned briefly in section 4.3.1, you can use a subset of DECI2 debugger commands (that are natively
available for TOOLs) on retail and TEST machines as well. To do so, the DECI2 Bridge must have been activated when
Kermit was started on the PS2. EE DECI2 is always available, but if you need IOP DECI2 as well, you must have also
supplied a TOOL's DECI2 Manager (rom0:DECI2) in the memory card folder the Kermit ELF has been started from, then
configured Kermit appropriately to load it (see section 4.2.1 for details).

NOTE: As written in 4.2.1, IOP DECI2 support is highly experimental; i.e., unstable.

When using DECI2 on a TOOL, your system configuration basically looks like this:

       PS2 Side of TOOL       |    Linux Side of TOOL
                              |
    /----\         /-----\    |    /-----\    /--------\
    | EE |---SIF---| IOP |---AIF---| MRP |----| DSNETM |
    \----/         \-----/    |    \-----/    \--------/
                              |                   |
                                                  |
                                                 LAN
                                                  |
                          ... ------*-------------*------ ...
                                    |             |
                              /----------\  /----------\
                              | Client 1 |  | Client 2 |  ...
                              \----------/  \----------/

That is, the EE communicates with the IOP, which in turn forwards DECI2 messages via the AIF chip and the MRP driver to
the DSNETM server running on the TOOL's Linux system. DSNETM accepts connections from DECI2 clients via LAN (TCP/IP)
and (de)multiplexes messages as necessary.

On the other hand, when using a Retail or TEST machine, the DECI2 software on the IOP as well as the hardware support
(AIF) is missing, so this is where Kermit comes in. The resulting system looks like this:

    /----\ (emulated)        (real) /-----\
    | EE |--SIF--\          /--SIF--| IOP |
    \----/       |          |       \-----/
                 |          |
               /--------------\
               | DECI2 Bridge |
               \--------------/       (Retail
                      |                or
                      |                TEST
               Kermit Connection       PS2)
 ---------------- (1394/SIO) ----------------
                      |               (PC)
                      |                
                /-----------\
                |  DSNETM   |
                | Simulator |
                \-----------/
                      |
                     LAN
                      |
      ... ------*-------------*------ ...
                |             |
          /----------\  /----------\
          | Client 1 |  | Client 2 |  ...
          \----------/  \----------/

On the PC, you need a single Kermit instance that mimics the DSNETM of a TOOL. Once this server is up and running,
other DECI2-compatible applications (like the Sony debuggers DSEDB and DSIDB, DS(E|I)CONS and so on) can connect to
this DSNETM, thinking it represents a TOOL, and then control the machine via the Kermit connection. Please note,
though, that Kermit is just used as a transport layer for DECI2 messages in this case; actual functionality (like
reading or writing memory, reading VRAM, stepping through code etc.) must still be implemented by the DECI2 facilities
of the EE or IOP. Luckily, the EE kernel contains everything necessary, even on retails and TESTS; on the other hand,
the corresponding IOP modules are missing, so this is why they need to be loaded by Kermit as needed.

To use Kermit in this mode, connect to your PS2 as usual (e.g., via 1394), but then start the DSNETM server via
"DSNETM\Start server" and data exchange via "DSNETM\Start packet pump". Afterwards, you can start any DECI2-capable
application (including a second instance of Kermit PC-side software itself), pointing at your Kermit-DSNETM instance
as its target.

You can monitor the status of the DECI2 Bridge and PC-side communication facilities via "DSNETM\Show status". That
window displays all status flags from the PS2 in decoded format (separately for both the emulated SIF interface to the
EE, the real one to the IOP, as well as both transceiver FSM's state flags), as well as a summary of the PC-side state.

- "Show bridge status" and "Show FSM status" toggle whether the display is automatically updated as the system
  operates. This is useful for debugging, but can severly impact performance (up to the point certain applications get
  timeouts for DECI2 messages).
- "Trace Packets" and "Hx" control individually for the EE and IOP whether transmitted packets are dumped to the DECI2
  standard dump protocol (STTYP). "Trace packet pump to STTYP" does the same for the global data exchange FSM. All
  these options are generally only useful for debugging.
- "EE Kernel TTY" and "IOP Kernel TTY" allow to open console windows showing debug messages from the EE and IOP
  (only via EKTTYP and IKTTYP, respectively).
- "DCMP_[DIS]CONNECT" allow sending the specified message directly, to allow the user to control the DECI2 session.
- "Reset mgr (IF dwn)" and "Connect IOP (IF up)" report changes of the simulated EE<->IOP link to the EE DECI2 Manager.
  The IF down command disables DECI2 processing of the EE and resets status (e.g., it clears the list of target-
  controlled breakpoints), whereas the IF up command resumes processing and allows the EE kernel to react to messages.
  These commands, in addition to "Reset FSM" and "Clear packet queue" for the data pump, are useful sometimes to bring
  the DECI2 system to a defined state.
  
  NOTE: In contrast to the TOOL, the DECI2 Bridge does not send the IF down command into the EE DECI2 Manager when the
        IOP reboots. Therefore, certain global state is not cleared on retail and TEST machines in this case, which
        might confuse some applications. This will likely be automated in some future version, but for the time being,
        the user is expected to send the corresponding messages manually, after halting the packet pump if necessary.
  
  NOTE: Sending IF down when the EE kernel debugger is sitting on a breakpoint triggers a fatal error. This situation
        can only be cleared by a system restart.
  
  NOTE: For the current version, if you want to use one application to start another, I suggest you let the first
        application sit in an idle state (not on a breakpoint), then do the following: stop packet pump, EE IF dwn,
        reset FSM, clear packet queue, start packet pump. This should ensure the next application can correctly
        process its DECI2 packets.


-------------------
5) Acknowledgements
-------------------

I owe quite a number of people a debt of gratitude for making this project possible, so I apologize in advance in
case I miss mentioning anybody's name in here :).

unclejun for his ideas and constructive criticism towards this Project, as well as my very first PS2 TOOL. Without him,
  it might have taken me quite a bit longer to acquire one of these awesome machines.
  
Parris for his excellent PS2 TOOL Disassembly Guide, which saved quite a bunch of TOOLs from ending up in the bin.

l_oliveira for his ideas, constructive criticism, and the countless hours of time he has invested to debug my buggy
  code. Without him, this program wouldn't be in its current state.

Thank you guys!


Special thanks go to:
*) MrBrown for EE SIO
*) The FreeMCBoot hackers: jimmikaelkael for reversing SECRMAN and making FMCB possible, neme for his OSD hack and the
   embed tool
*) sjeep for making HDL

AND

*) Sony for making the PS2
   (Okay, I'll recall half of it for various annoyances along the line: regional lockout, subregional MechaCon
    encryption, shooting down HDL, shooting down modchips in my country, not publishing the PS2 HDD + FFXI in PAL
    countries and so on.
    
    And another half for crippling the nice hardware the PS2 could have been by not publishing hardware documentation.
   )


-----------
6) Contacts
-----------

For bug reports, comments, constructive criticism, feature requests and so on, don't hesitate to contact me at the
usual places :)
