================================================================================ AsbestOS README

== Introduction ==

AsbestOS is a Linux bootloader that runs off of the PS3 Lv-2 USB exploit. It is designed to boot on PS3 systems running System Software version 3.41, though it could be adapted to earlier versions. Linux runs on the GameOS partition, thus having the same access to hardware that GameOS has.

== Building ==

The PS3DEV environment variable needs to point to a usable PowerPC64 toolchain (e.g. $PS3DEV/bin/powerpc64-linux-gcc). If you don't have one, point it at an empty dir and run

$ cd toolchain && ./buildit.sh ppu

You also need the 'lzma' utility from xz-utils, and the 'dtc' utility. You can grab the latter here: http://git.jdl.com/gitweb/?p=dtc.git . Just clone the git repo and type 'make' to build, then copy the resulting 'dtc' binary to your $PS3DEV/bin directory.

To compile stage1 or stage2, just type 'make' in the respective directories. You can also compile the UDP debug message client by doing the same in the tools directory. 'make' in the root of the source tree will do all three.

== Usage ==

First compile AsbestOS and get a compatible USB exploit delivery mechanism. You should also connect your PS3 and PC to a network (they need to be in the same broadcast domain) and make sure your PC allows broadcast packets to UDP port 18194. The IP source and destination are both 255.255.255.255 for these packets.

Run tools/dbgcli to get AsbestOS debug output. Fire off the exploit device, turn on your PS3 using power followed by eject within 0.2 seconds (if required by your exploit implementation), and cross your fingers. If you get anything at all, congratulations, stage2 is running. At this point, if you have any issues, the problem should be fairly apparent from the messages.

If you get nothing, either the packets aren't making it to your PC or stage2 is failing to start up properly. If your exploit device can show the debug "print" USB messages, that might help you find out whether stage2 is at least being loaded properly.

If your PS3 panics (blinking red light) or spontaneously reboots, then something somewhere probably hit an error condition. The first thing that stage2 does is inititalize Ethernet debugging, so chances are either that failed, or stage1 failed.

Basically, if stuff doesn't work, poke me on IRC ('marcan' on either EFNet or freenode) and we'll see what we can do.

To get a kernel to load (see below for instructions to build one), you need to have a DHCP server on your network. It needs to be configured to feed a boot server and filename to the PS3. The boot server should point to a machine running a TFTP server that can serve the specified file, which should be a kboot.conf style configuration file. For example, on an OpenWRT Kamikaze router, put something like this on your /etc/config/dhcp:

config host option name ps3 option mac 00:1f:a7:aa:bb:cc option ip 192.168.3.60 option networkid ps3

config boot option networkid ps3 option filename kboot.conf option servername foobar option serveraddress 192.168.3.171

Where 192.168.3.60 is the IP that you want your PS3 to get and 192.168.3.171 is the IP of the TFTP server. The server name doesn't really matter, but it's a good idea to set it to the hostname of the TFTP server. Don't forget to specify the MAC address of your PS3 correctly.

The kboot.conf follows the usual syntax that is used with petitboot and friends. For example, the following would be a minimal file:

linux='vmlinux video=ps3fb:mode:3 root=/dev/nfs rw nfsroot=..... ip=dhcp'

This will TFTP-load a kernel named 'vmlinux', passing the specified arguments. The text to the left of the first = is a label. Quotes surrounding the right hand side are optional.

You can also specify an initrd by either using a global initrd=file line (this applies to all entries) or a per-kernel initrd=file option. The initrd will also be loaded via TFTP. root=... may also be specified as a global option.

Currently only the default entry (the first one, or the one specified with default=) is used, as there is no way to select the boot option.

== Compatible devices ==

AsbestOS can potentially run on any device capable of implementing the exploit and which has access to at least 40kB or so (currently) of free internal or external memory. The following ports are known to exist so far:

• AVR Software USB (for AVRs without hardware USB) Arduinos, etc... http://github.com/rvalles/asbestos-avr8susb Supports both >=64k AVRs and <64k AVRs with an external I2C EEPROM.

• Rockbox devices with the ARC USB controller iPods (non-Touch), ... http://github.com/shuffle2/rockbox_psgroove/wiki Supports Asbestos stage1/2

• TI-84 Plus http://brandonw.net/ps3jb/ Supports AsbestOS stage1/2

Yeah, someone should really make a port for USB AVRs (heck, I bet someone already has and just didn't tell me).

== Kernel ==

AsbestOS boots vmlinux kernels (same as usually used with petitboot and other kexec-based bootloaders). This is an ELF format kernel. AsbestOS provides the devtree and other information to the kernel. AsbestOS is also responsible for allocating all of RAM and passing the resulting memory region to the kernel. Current mainline and official ps3-linux.git do not support receiving this information and will not work (they will be restricted to 16MB RAM), so you must use the patched kernel available at:

http://git.marcansoft.com/?p=ps3-linux.git

This git tree also contains patches for early debugging via Ethernet using dbgcli and a useful default configuration.

To build such a kernel, simply 'make vmlinux' (normal Linux cross-compiling settings apply unless you're compiling on a PS3; check pmake.sh for some example vars). The file is built in the root directory of the kernel sources.

You'll probably want to strip the kernel to significantly reduce the size of the ELF image:

$ make vmlinux $ powerpc64-unknown-linux-gnu-objcopy -S vmlinux vmlinux.stripped

Commandline arguments are currently hardcoded into AsbestOS (stage2/config.h), NOT the kernel.

== Linux environment ==

The GameOS environment is essentially the same as the OtherOS environment, as they are just different LPAR configurations on the same hypervisor. The following differences are known to exist:

• Boot memory is 16MB instead of 128MB. Using my ps3-linux.git, pretty much all issues caused by this should be resolved. Former issues included framebuffer memory limitations, threads-max and ulimit being set way too low, etc. The total amount of memory is the same as under OtherOS, only the bootmem split changes.

• 3D support is available via a preallocated 3D object ID in the RSX. There is a proof of concept remote render implementation under tools/netrpc/rsxtest.py.

• Flash and HDD access limitations are different. Currently, Linux seems unable to access these devices out of the box. Investigation needed.

• Linux gets access to an additional SPE, so you get 7 instead of 6.

== TODO ==

Support some kind of video output, maybe.

Support USB in AsbestOS to load kernels from USB devices

Support the PS3 HDD to load kernels from the OtherOS partition, if any (maybe?)

== Known bugs ==

USB EHCI support is buggy, at least on recent PS3 Fat systems. This is apparently also a problem in OtherOS mode on older firmwares and unrelated to AsbestOS per se.

The PS3 video modesetting driver times out on some command, which delays video init for a few seconds. If your kernel panics before that, you will never see anything.

Storage support (Flash and HDD) needs looking into.