Official uLaunchELF Documentation

LaunchELF User Guide

Unofficial LaunchELF releases by EP + dlanor based off Mirakichi's source to LaunchELF v3.41

1. Starting LaunchELF
2. The Interface
3. Internal Functions
4. The Settings File (Advanced)
5. Changelog
6. Acknowledgements

Preface

This documentation is provided as an open method for users and programmers to help each other understand LaunchELF. All users are able (and encouraged) to contribute to it. If you wish your work to be included in the official documentation provided with each LaunchELF release, then submit your revised changes or additions to the uLaunchELF documentation thread on the ps2-scene.org forums. If your work is of professional quality and usefulness, it will be added to the main documentation.

If you feel your work has been included by mistake, without your permission, or that you have not been accredited, please make a post on the uLaunchELF documentation thread on the ps2-scene.org forums.

The latest official version of this document is always available at
http://www.ps2-scene.org/forums/showthread.php?t=40179

Welcome to LaunchELF

LaunchELF is an open source file manager and executable launcher for the Playstation 2 console. LaunchELF makes it possible to move, copy, rename and delete files to and from many mediums, including Hard Drive, Memory Card, CD/DVD ROM, and USB from a minimal and functional interface.

1. Starting LaunchELF

Top

LaunchELF is designed to run in a variety of situations. Most users run the program from either the hard drive or memory card, but it is also possible to run LaunchELF from CD or DVD. Depending on your system setup, you may consider using one of these methods.

Run LaunchELF directly from CD/DVD
Use Swap Magic 3.6's USB functionality to boot mass:/SWAPMAGIC/SWAPMAGIC.ELF from USB mass storage device
Use your modchip's Devolution Mode 1 (DEV1) to allow direct boot from memory card on system startup
Use your modchip's Devolution Mode 2 (DEV2) to allow direct boot from hard drive on system startup
Use M.R.Brown's PS2 Independence Exploit to allow boot from memory card when an assigned PSX disc is inserted

The first two options are often used by users who have a Playstation 2 which is incompatible with the exploit and do not have a modchip, but have a Swap Magic. It is less favourable to the other methods since it is harder to upgrade the program, and frequent swaps are required in order to use the program. You can however boot LaunchELF from CD/DVD and use it to copy itself to the desired location on your memory card or hard drive.

The last three options require LaunchELF to be stored on a storage medium generally only accessible from the Playstation 2. Most modchips look for the Devolution Boot Executable in mc0:/BOOT/BOOT.ELF or hdd0:/__boot/boot.elf. The PS2 Independence Exploit looks for the boot executable in mc0:/BxDATA-SYSTEM. The x represents your PS2's region (I=Japan/Asia, A=America, E=Europe).

2. The Interface

Top

LaunchELF allows the user to access its functions through a graphical user interface (GUI). Through the use of the Playstation 2 controller, the user is able to control LaunchELF directly onscreen.

The directional pad (D-PAD) controls to focus or highlighted entry on the screen. The other buttons on the control pad activate certain functions depending on what item is focused, and what screen the user is on. Apart from the main screen, Circle usually represents OK or Accept, while Cross represents Cancel or Back. (see 2b.ii, key mapping for details)

2a. The Main Screen

LaunchELF's main screen is in essence a button handler. Designed for launching programs quickly, LaunchELF responds to a key press on the Playstation 2 controller by executing the corresponding program linked to that button.

All buttons, minus the D-PAD and Select launch the specified program or function when pressed.

If you are running LaunchELF for the first time, there will be no entries set up on the main screen. To add an entry, use the settings page to map a program or action to a button. To enter the settings screen, press Select at the main menu.

User presses X		Find Program assigned to X		Execute Program
		Figure 2.1: Logic when button X is pressed on main screen.

2b. The Settings Screen

The settings screen is the central point for configuring LaunchELF. To access this screen, press Select

from the main menu.

Button Setting

DEFAULT: Assign an ELF to launch if main screen is displayed for a length of time
From "O" to "START": Assign an ELF to launch if corresponding button is pressed on the main screen.

Misc

TIMEOUT: Length of time (secs) to wait until DEFAULT program is run
DISC CONTROL: Stop the disc from spinning (v7 users)
PRINT ONLY FILENAME: Omit file extension display on main screen
SCREEN SETTINGS: Go to Screen Settings page
STARTUP SETTINGS: Go to Startup Settings page
NETWORK SETTINGS: Go to Network Settings page
OK: Accept changes and return to Main Screen
CANCEL: Cancel changes and return to Main Screen

2b.i. Settings > Screen Settings

COLORx R: Adjust red value for color detail x (0 - 255)
COLORx G: Adjust green value for color detail x (0 - 255)
COLORx B: Adjust blue value for color detail x (0 - 255)
Screen X: Adjust screen position (horizontal / x plane, INT)
Adjusting this value will cause the screen to move on the x plane (left and right). This is useful if the output to the television is off centered or cut off.
Screen Y: Adjust screen position (vertical / y plane, INT)
Adjusting this value will cause the screen to move on the y plane (up and down). This is useful if the output to the television is off cent red or cut off.
Interlace: Activate interlaced display. (BOOLEAN)
[Explanation]
Return: Accept changes and return to main screen
Initial Screen Settings: Load program defaults for values on this page.

2b.ii. Settings > Startup Settings

RESET IOP: Reset Input/Output Processor when LaunchELF starts (BOOLEAN)
Some programs require an IOP reset to be performed before being run. If you experience problems loading a specific program, try enabling this option.
Number of CNFs: Number of profiles (config files) LaunchELF should use (CARD)
If you wish to have more programs than buttons on the main screen, increase the number of config files here, then use LEFT and RIGHT at the main menu to switch between them.
Key Mapping: Select Western or Eastern OK/CANCEL button configuration (default, = OK, = CANCEL)
Return: Accept changes and return to main screen

2b.iii. Settings > Network Settings

IP Address: Allows you to set your PS2 IP Address
Netmask: Allows you to set your Subnet Mask
Gateway: Allows you to set your Default Gateway (usually your router or your PC)

Adjust settings by using D-Pad to move between octets (the numbers separated by periods) then add or subtract using Cross or Circle . Save settings when finished.

Below are the network settings for the Playstation 2 stored in the file IPCONFIG.DAT, located in mc0:/SYS-CONF/ on the Memory Card (Slot1).

IP ADDRESS	NETMASK	GATEWAY
192.168.0.10	255.255.255.0	192.168.0.1

These are the defaults used if no IPCONFIG.DAT is found, or if the file is unreadable. Therefore, if you use these defaults, you don't really need the file.

2c. The File Manager Screen

LaunchELF uses a virtual file system to allow both devices and internal procedures to be run. This file system is displayed when

a) The user wishes to choose to map an action to a button, or b) The user opens the file manager.

The structure of the virtual file system is as follows:

mc0:/ - Display contents of memory card in slot 1
mc1:/ - Display contents of memory card in slot 2
hdd0:/ - Display PFS partitions located in the PS2 HDD, and in turn, display the contents of the selected partition.
cdfs:/ - Display contents of current CD or DVD inside the PS2 CDVD-ROM
mass:/ - Display contents of USB memory device
host:/ - (available only in File Manager Mode). Display contents of the networked host volumes
MISC:/ - (available only in Button Mapping Mode)
- FileBrowser [Internal Function] - Display this screen
- PS2Browser [Internal Function] - Execute Sony PS2 browser (rom0:OSDSYS) from ROM
- PS2Disc [Internal Function] - Execute a Playstation 2 disc in the CDVD-ROM drive (parse SYSTEM.CNF, run target ELF)
- PS2Net [Internal Function] - Starts FTP server and PS2Net

=	Navigating through the File Manager ========================>
•	If a folder, partition or device is selected, and Circle is pressed, LaunchELF will descend into that item, and display its contents on screen.
•	If an .ELF file is selected, and Circle is pressed, LaunchELF will:
	a) Map the ELF to the requested button, then return to the settings screen, if the user requested to do so,	-OR-	b) Execute the program, if the user came from the FileManager item.
•	If Triangle is pressed, the file browser will move up a level in the filesystem hierarchy, and ascend to the parent directory or device.
•	If Cross is pressed, the highlighted file or directory will be marked for manipulation with the operations menu (see 2c.i, The Operations Menu for details)
•	If Square is pressed, the file manager will:
	a) mark all files in the current directory for manipulation with the operations menu (see 2c.i, The Operations Menu for details)	-OR-	b) only display files with the .ELF extension, if the user is mapping an ELF to a button. LaunchELF makes it easier to browse memory card saves, as it reads the title of the save-game from its icon.sys file.
•	If L1 is pressed while browsing a memory card, the title of the save will be displayed in filename order.
•	If L2 is pressed while browsing a memory card, the title of the save will be displayed in title order.

2c.i. The Operations Menu

All LaunchELF's file manager functions are accessed through the operations menu.

To display the operations menu, select a file or directory in the file manager, then press R1 .

Copy: Marks the selected file or directory to be copied.
Cut: Marks the selected file or directory to be moved.
Paste: Performs the copy or move operation on the item marked using Copy or Cut respectively to the current directory.
mcPaste:
1. mcPaste is ONLY intended for handling backups of commercial game saves, since homebrew stuff mostly ignore MC attributes and timestamps. Using mcPaste for homebrew stuff won't be harmful, but it simply isn't necessary.
2. mcPaste is intended to backup saves from MC to any non-MC media, or to restore such backups from any non-MC media to MC. But the safest media of all to use is a PS2 IDE HDD, as it allows all filenames that are valid on MC.
Delete: Deletes the currently selected file.
Rename: Changes the currently selected file or directory's filename.
New Dir: Creates a new directory in the current directory.
Get Size: Returns the file size of the currently selected file.

The operations menu can be performed on multiple items. Use Cross to select multiple files at once, then access the operations menu as usual.

Rename is not available from memory card; paste is not available from host.

3. Internal Functions

Top

3a. FTP Server

LaunchELF runs a FTP server quietly in the background. If your Playstation 2 is connected to the local network, you can take advantage of this function by connecting to the IP address specified in IPCONFIG.DAT with your PC's FTP client.

3b. Copying Game Saves

To copy a game save, activate the file manager and enable MC Title mode. Select the game save you wish to copy, then open the context menu and select Copy. Browse to the location you wish to copy the save, then open the context menu and select Paste.

Some games require time stamping to be present which LaunchELF currently does not support. If you manipulate these saves with LaunchELF, it is possible that the game will reject the save next time it is loaded.

3c. Virtual Keyboard

LaunchELF does not support data entry via traditional keyboard. If textual entry is needed, LaunchELF will display the virtual keyboard onscreen. Use the D-PAD

to select a character, then press Circle

to add the character to the input string displayed at the top of the keyboard. The blank spaces represent the Space Character.

To make a correction, use L1 and R1 to move the cursor left and right inside the string. To accept changes, highlight ENTER, then press Circle . To cancel changes, highlight CANCEL then press Circle .

3d. Supported File System Detail

Memory Card

Playstation File System (PFS) filesystem.

Hard Drive

Playstation File System (PFS) filesystem sitting on APA partition.

CDFS

ISO 9660 Level 1 (relaxed)
ISO 9660 Level 2 (relaxed)
Joliet
UDF

USB Mass Storage Device

FAT12 Read/Write with long filename support
FAT16 Read/Write with long filename support
FAT32 Read/Write with long filename support
NOTE: Only the first readable partition is used.

Host

Standard read only host support for volumes specified in host:/elflist.txt
NOTE: You do not have to boot from host in order to access files on host:/. Use ps2client -h ps2.ip.address listen

4. The settings file (advanced)

Top

All of LaunchELF's settings are configured from the GUI, then saved to file. However, power users may prefer to manipulate the settings file directly.

4a. Profiles

Traditionally, all settings are stored in LAUNCHELF.CNF. Since version 3.4b, LaunchELF is able to use multiple settings files (profiles) at once. The profiles feature (if enabled) results in LAUNCHELFn.CNF being used, where n is a cardinal value from 1 to setting -> numCNF (number of configs).

4b. Locating the Settings File "LAUNCHELF.CNF"

Purpose: Define new format and defaults for LaunchELF CNF files, to serve as a guide in developing the code implementing these changes. Note that LaunchELF v3.41t (or later) will accept this file as-is when loading CNF, but if you modify any settings so that LaunchELF saves the file again, then all comments will be removed.

Upon program execution, several locations are probed in order to read the configuration settings. If the settings file is located in the current directory, LaunchELF stores the location and reads the file to memory. The file is parsed and settings are restored accordingly. Future settings changes will result in a write process to the file which was originally read into memory. The file is read in the following order

Directory LaunchELF was run from
mc0:/SYS-CONF/
mc1:/SYS-CONF/

If the settings file is not found, LaunchELF creates the file and loads default settings to mc0:/SYS-CONF/LAUNCHELF.CNF, only if the directory mc0:/SYS-CONF exists.

4c. Settings File Layout "LAUNCHELF.CNF"

Each line of the settings file corresponds to a particular setting or value. Each line of the settings file is described below.

LAUNCHELF.CNF
CNF_version = 2.0	The CNF_version variable MUST exist for a CNF to be accepted as valid, and it must also be the first variable defined in the file. That way an old CNF can't cause damage when read by new LaunchELF versions. Future LaunchELF versions may also check the value for some features.

Next follows the 12 (as yet) launching links, here kept in traditional order, though users are allowed to vary the order at will. For these 12 variables the following name conventions apply:

LK_auto_E1 = LK_Circle_E1 = MISC/FileBrowser LK_Cross_E1 = LK_Square_E1 = LK_Triangle_E1 = LK_L1_E1 = LK_R1_E1 = LK_L2_E1 = LK_R2_E1 = LK_L3_E1 = LK_R3_E1 = LK_Start_E1 =	"LK_" is an abbreviation for Launch Key and is used as a prefix for the key descriptor (eg: Square ). That is then followed by the suffix "_E1" which is an abbreviation for Execution Method 1. At present that is the only method we have, but hopefully that will change... The default value for most of these should be an empty string, except that one link should start the file browser, so people can start to copy stuff without having to make a new CNF.

LK_auto_Timer = 10 Menu_Hide_Paths = 1	After the launch key definitions we have the variables for diverse settings, most of which use obvious naming schemes and have their traditional default values. Some exceptions are the variables for GUI colour values, which are described in the next section.

GUI_Col_1_ABGR = 00808080 GUI_Col_2_ABGR = 00404040 GUI_Col_3_ABGR = 00000060 GUI_Col_4_ABGR = 00000000 Screen_X = 128 Screen_Y = 30	Next we have the GUI colour values, for which I made some choices that differ widely from all the other variables so far. First and foremost, I switched their data format to pure hex, to make it practical for a human to edit the byte values. I also added a suffix to the names, so the user has a mnemonic key to the usage of the byte values. And finally, I chose some new default values that I've been working on for a while. The effects of these settings are as follows: Normal text is fully black, while the background is half-level white. Border, submenus, and LaunchELF title text use a medium grey colour, with half the brightness of the background, while alerts and progress messages use a clear but subdued red colour. My goal with these defaults was to achieve max clarity with no glare, and I think this succeeded fairly well, though the final results do depend greatly on your monitor settings as well.

Init_CDVD_Check = 0 Screen_Interlace = 0 Init_Reset_IOP = 1 Menu_Pages = 1 GUI_Swap_Keys = 0	Note that I have changed the default for IOP reset, as this has been long-term tested now, and proven superior to starting without it. I have also changed the default for CDVD checking, as the old default could cause lockup on some PS2 models if started with empty tray.

The variables below have been added after the original design (v3.41t) of the new CNF format. They should be used as follows:

USBD_FILE =	USBD_FILE is valid in v3.41u and later versions. It's used to choose an alternate USBD.IRX file, which LaunchELF will then use instead of the embedded one. You can set it in the 'STARTUP SETTINGS' screen.

NET_HOSTwrite = 0	NET_HOSTwrite is valid in v3.44 and later versions. It's can enable the ability of the networked HOST interface to write on your PC HDDs! Users who want to avoid risks for their PC should leave it as default, which disables these new abilities. For safety reasons it can only be changed by direct user editing. Edit it to a non-zero value to enable the new abilities. (You'll need a very new ps2client.exe as well.)

5. Changelog

Top

Unofficial LaunchELF releases by EP + dlanor

LaunchELF v3.51 (2006.03.03)

Added experimental support for HDD on 'slim PStwo' models, released as separate ELFs in the same release ZIP. Developers should be aware that this patch adds a new module to PS2SDK, named "ps2hdd_slim_PStwo.irx" and serving the same purpose for those models that "ps2hdd.irx" does for traditional PS2 models. Thanks go to 'lonwern' at PS2-Scene for pointing out the precise function in the source code that needed patching.

LaunchELF v3.50 (2006.03.01)

Modified the ELF loader so it can reside at the same address used in LaunchELF versions earlier than v3.46, and still retain compatibility with current version of PS2Link. This eliminates the incompatibility that v3.46-v3.49 had with some unpacker stubs, and thus with all programs using those stubs, (notably myPS2). Full compatibility is now restored for those programs.

LaunchELF v3.49 (2006.02.26)

EP Fixed an issue where garbage could be displayed at startup when LaunchELF was booted by another program's generic launcher function. (Note: Issue only appeared to occur randomly with the packed ELF when using only one CNF).

LaunchELF v3.48 (2006.02.25)

EP corrected a bug in the reading of free size on MC. This bug could cause menu commands to fail with extremely slow MC. (Noted with 64MB MCs from Datel.) Thanks go to 'cmal1492' for bringing this bug to our attention. (It is older than the uLaunchELF project.)

LaunchELF v3.47 (2006.02.22)

Corrected a serious bug in the IOP Reset routine (reverse logic for SifIopSync).

LaunchELF v3.46 (2006.02.20)

Modified the ELF loader of LaunchELF to improve compatibility with PS2Link. This resulted in slightly smaller code, and as a side effect the loader will no longer display the name of the ELF to be loaded on screen. The major benefit is that LaunchELF will work well with the new version of PS2Link, also released this night. Thanks go to Drakonite for his advice on how to improve this compatibility

LaunchELF v3.45 (2006.02.19)

Fixed a LaunchELF bug that prevented folder overwrites when pasting to HOST.
Fixed a PS2Client bug that prevented detection of folder conflicts on HOST.
Added a progress report (written file bytes counter) to 'Paste' and 'mcPaste'.
EP fixed a few issues that prevented PS1 memory cards from appearing in FTP listing. (Note: Files on PS1 memory cards lack timestamps so the timestamps come from the current PS2 system time).

LaunchELF v3.44 (2006.02.18)

Implemented HOST interface write access to networked PC. This uses a new CNF variable named "NET_HOSTwrite" which has a default value of "0" meaning it is disabled. For reasons of safety there is no way to change this value from the config menu. Edit it yourself, and set its value to "1" (or any other non-zero value) to enable the new abilities, which include the following menu functions 'Cut', 'Paste', 'mcPaste', 'Delete', 'Rename', 'New Dir'. Note that most of the new functions require a very recent version of ps2client or RadHostClient to function, and at present the 'Rename' function only works with the ps2client version specially patched for LaunchELF. (Available in the LaunchELF forum.) (NB: file writing seems bugged in RadHostClient v1.5)
Added modified sources for ps2client to the folder "Changed source for external projects".

LaunchELF v3.43 (2006.02.16)

This release is purely a bugfix for an old bug in the HOST interface. That bug was mostly harmless in older versions, but became capable of freezing the console in v3.41u and v3.42.

LaunchELF v3.42 (2006.02.15) NB: switched date format to YYYY.MM.DD

Implemented mcPaste command in submenu. Like the old Paste command this copies all selected files and folders (recursively), but it is specially intended for MC backups. It can only be used either to copy from MC to non-MC (making backups from MC) or to copy from non-MC to MC (restoring backups to MC). These backups on non-MC media will have an extra file in each folder, holding the original MC attributes and timestamps of all files in that folder. This data will be used when restoring the backups to MC, so that games will accept the restored files as being the originals. The 'extra' files are filtered out from such copying so they don't appear among the restored files on MC. Those 'extra' files all use the same filename, which is "PS2_MC_Backup_Attributes.BUP.bin" (to avoid any confusion with 'real' files).

LaunchELF v3.41u (02/13/2006)

Implemented new standards for handling of file and folder attributes on PS2 memory cards. This ensures that all gamesaves copied from one such MC to another such MC will have all attributes and timestamps preserved, so the copies remain acceptable to the games. It also improves the chances of successful backup/restore of gamesaves to/from non-MC devices, by using standard attributes for files and folders that match what the majority of games use.
Implemented a patch to the 'Get Size' command, so that it will display real attributes and modification timestamp of a file/folder on MC. For non MC this will show a standard attribute and zeroed timestamp, so that's not very useful. This patch is just a temporary thing, until we make something better.
Implemented selection of external USBD.IRX files, for those that have trouble using the one embedded into LaunchELF. (This change was contributed by 'sincro'.)

LaunchELF v3.41t (02/03/2006)

Implemented a new CNF format and various new defaults for the settings. Essentially this means that all settings are specified as named variables, and line order is no longer significant. This will allow easy human editing as well as many new features in the future. For details on new defaults, study the enclosed LAUNCHELF.CNF

LaunchELF v3.41s (01/13/2006)

Modified a comment in fat_write.c to fix an IOP 3.2.2 compiler issue for the usb mass driver.
Added a new line to the end of imports.lst to eliminate an IOP 3.2.2 compiler warning for host.
Rebuilt everything with the IOP 3.2.2 compiler. (Note: includes cdvd, ps2ftpd, and usb_mass modules).
Modified the makefile to use the ps2dev9.irx module from the PS2SDK instead of the older one from the original LaunchELF source package. (Note: Are there still reliability problems?)
Updated "Development related issues.txt" removing both the ps2dev9.irx reliability issue that now appears fine and the ps2ftpd.irx issue that is now fixed.