-  -  -- -------------------------------------------------------------------*-
               P S U L - The Gamecube Code Uploader using PSO
                     (C) 2003, Titanik of Crazy Nation
                   PSO Hack found by Crusader of Kalisto
-*------------------------------------------------------------------- -- -   -


WTF???
======

PSUL is a PC tool that lets you run executable code on your Gamecube, using
the Phantasy Star game with the GC Broadband adapter (and a Memory card).

For now, it works with the PAL version, the US, and _should_ work with the 
early JAP version too (doesn't work with the latest version of PSO JAP).

There were 2 versions of the American PSO released. Only the newer version of 
the American PSO - after January or so - will work. It will be fixed in a
future version.

Using PSUL you can upload executable code up to approx 2MB to your GC. 
**** YOU CAN'T RUN BACKUPED GAMES ****, but both the recent Freeloader and
Action Replay releases have been tested and are working!

The CZN-TEST.DOL file included in this archive should display some logo in 
NTSC mode ;-) (made in ASM without sdk/libs/whatever)

HAVE PHUN!

 Greets : crusader (thanks for all man;), costis, nagr0r, lac0r, loser, 
          everyone involved in GC hacking, and of course all my friends and
          the whole CZN family (loomy: plus que 9 ! ;-)

                                                    -- Titanik 
Usage
=====

 psul [options] [file.dol]

 options :
    -f [file] : gives an argument file to the DOL, if the DOL program supports
                this option. 
    -b        : input file is not a DOL file but a binary file
    -s        : save user info on memcard if you never played PSO online
    -d        : disable internal DNS server
    -i [ip]   : specifies the IP to which the GC should connect, if autodetect
                didn't work. 
    
 Exemples:
 
 psul czn-test.dol          ; execute the CZN-TEST.DOL file on the GC
 psul -b code.bin           ; execute the CODE.BIN file as binary file
 
 psul -d czn-test.dol       ; execute czn-test.dol, but don't run the internal
                            ; DNS server. you may want to do this if you're
                            ; already running your own DNS server. 
 
 psul -i 192.168.0.1 czn-test.dol   ; runs CZN-TEST.DOL, and specifies that
                                    ; the Gamecube sees the PC as 192.168.0.1
                                    ; use it only if PC address autodect
                                    ; didn't work
           

Configuring PSO
===============
  
  Network setup
  -------------
  1) In Main Menu, go to Options -> Network Option -> Provider Option
  2) Go to Network Setup in the Network Setup Menu ;)
  3) In "Select network Information settings", hit Edit 
  4) In "Edit ISP name", you don't need to change anything
  5) In "Ethernet settings", choose
              - Manually set an IP address
              - Do not automatically disconnect
  6) In "IP address manual-settings
              - IP address: put the IP address you want the gamecube to have
                            (like 192.168.0.7)
              - Subnet mask: the subnet mask of this IP (like 255.255.255.0)
              - Default router: enter the IP address of your computer, as seen 
                                by the gamecube (like 192.168.0.1)
              - Primary DNS: same IP as default router
              - Secondary DNS: leave it blank
              - Enter the IP of the computer as seen by the gamecube in the
                Primary DNS, leave the Secondary DNS field blank
              - DHCP Hostname : Not set  
  7) In "Browser settings", you don't need to change anything
  8) Hit save to save all the net info, and you can go back to main menu.
                
  First connection 
  ----------------  
  The purpose of the first connection is to let PSO save the user info into
  the memcard so you don't have to enter them every time... If you already
  played PSO online, you don't need to do that.
  
  1) run "psul -s" 
  2) In Main Menu, choose Online game, and create a new character
  3) Enter any Serial Number, Access Key and Password (you won't have to
     remember them), and skip the useless menus
  4) Save the Password to the memory card when prompted
  5) The GC should connect to the PC and you should get this message on PC :
            Saving user info on memory card...
            Done...  
  6) Configuration phase is done, let's run some code, see the "Usage" 
     paragraph! ;-)

About DNS
=========
PSUL has its own tiny DNS server so the GC connects to your PC instead of 
connecting to SEGA. 
If you run your own DNS server, you need to use the -d switch and cause these
domains to resolve to your PC's IP address:

   - pso-gc01.sonic.isao.net (Japanese PSO)
   - gc01.st-pso.games.sega.net (American PSO)
   - pso-gc1.pso.playsega.com (European PSO)

If you don't know how to do this, maybe you shouldn't be running a DNS server.


Running a program on the GC
===========================
  1) run PSUL on the PC (see Usage paragraph)
  2) Go into Online gaming, and choose the character you made. PSO will
     then connect to the PC and program will be uploaded and run.


Troobleshooting
===============
  If you get a "DNS Error > Can't bind socket" you need to run your own DNS
  server.
 
    
For Coders
==========

1) The -f option of PSUL lets you pass a file as argument. So let's say if you
  are coding a GB EMU, you could pass a GB ROM to your program. To do that,
  allocate a static buffer in your program.
  In the resulting DOL file at offset 0xF8 put the Address of this static
  buffer in the DOL file (32 bit big endian), and at offset 0xFC put the
  length of this buffer (32 bit big endian).
  
  When the program is called with the -f option, it will check if your program
  supports it (checks offset 0xF8 and 0xFC), if so it will copy the content
  of the file passed in argument at the buffer address + 0x04.  It will put
  the size of the readed file at the buffer address.
  
  Example: - get STARCUBE's freeloader release,   at offset 0xF8 put 
             00 01 09 1C 00 00 00 15
           - make a small text file (less than 0x15 bytes) with some text
           - run  psul -f test.txt s3-f106b.dol
           - if everything worked right, the "Insert Disc Game" message was
             changed with your text... 
  
2) The -b option allows you to run a binary file directy. It should be noted
  that this binary file is loaded in 0x80003100 in the GC ram, and its entry
  point is also 0x80003100  
  
3) The input files are not read before a connection from PSO is etablished,
   so basically you can make a small .bat file that runs PSUL in an infinite
   loop, and just restart PSO on GCeach time you want to test a change of 
   your file, it will always take the latest one

      
-  -  -- -------------------------------------------------------------------*-
                 [eof]  C r a z y  N a t i o n  2 O O 3  [eof]
-*------------------------------------------------------------------- -- -   -                   