-  -  -- -------------------------------------------------------------------*-
               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 should support all PSO versions (PAL, US, and JAP) but JAP support
has not be fully tested yet.

Using PSUL you can upload executable code up 14MB to your Gamecube and pass 
arguments (and even a file) to the executed programs. Thanks to the integrated
DNS server, you don't need to install any other program on your computer to
use PSUL.

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

HAVE PHUN!

Special thanks to Crusader of Kalisto, without him PSUL and the whole PSO
hack concept wouldn't exist!
 
 Greets : peter, costis, crowtrobo, desktopman, nagr0r, lac0r, loser, 
          everyone involved in GC hacking, and of course all my friends and
          the whole CZN family !!!


                                                    -- Titanik 

Usage
=====

 usage: psul [options] [file.dol] [args...]

 options :
    -f <file> : gives an argument file to the DOL, if supported
    -s        : save user info on memcard if you never played PSO online
    -b        : input file is not a DOL file but a binary file
    -d        : disable internal DNS server
    -n        : only launch the internal DNS server, don't upload any file
    -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 -f rom_file.n64 emulator.dol  ; Execute emulator.dol and gives him
                                    ; rom_file.n64 as file argument
                                    
 psul printer.dol hello     ; execute PRINTER.DOL and gives him "hello" as
                            ; argument                                    
   
 Advanced examples :
 -------------------
 
 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" put
              - 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) You can now use arguments in main() ! 
   Just declare 
   
                   void main (int argc, char* argv[])
                   
   like you'd do on PC. 
   If you're not using the nintendo SDK, be sure to use the crt0.s file 
   included with this archive (it also enables FPU support). See Usage 
   paragraph to see how to send arguments using PSUL.

2) 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. Introduced
  in version 1.1 there is a new method to do that easily.
  
  New Method
  ----------
  If you're using included crt0.s, just declare 
  
          void main (int argc, char* argv[], int argfsize, void* argf)
                  
  and if you receive an argfsize that is not equal to zero it means there is
  a file attached, in pointer argf. Easy isn't it?
  You just need then to specify in the DOL header that your executable is
  accepting files as argument. Just put 0x46494C45 ("FILE") at offset 0xF8, and
  maximum file size in big endian at offset 0xFC.
  
  If you're not using included crt0.s but the SDK for example, check the
  "PSUL bootinfo" block in the crt0.s file to see how to implement it.
  
  Maximum argument file size using this method is a bit more than 8Mb, if you
  want to send bigger files, use the old method.  
 
  Old Method
  ---------- 
  The old method is to 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... 
  
3) 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  
  
4) 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]
-*------------------------------------------------------------------- -- -   -                   