================================================================================
                               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 (but not
ps3pwn).

To compile ps3pwn, you need to be on the target platform (ARM-Linux OMAP3) with
a native compiler (or hack the Makefile to use some cross compiler). Just type
'make' in that directory. ps3pwn is just the reference implementation of the
exploit and is not required as there are alternatives (see below).

== 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=<label>) 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:

- TI OMAP3 devices running Linux (ps3pwn reference implementation)
  IGEPv2 board, BeagleBoard, Nokia n900, Palm Pre, Motorola Droid, Pandora...
  Included in this distribution.
  Implements the MUSB device driver in userspace. You need to disable all USB
  services (if any) and either unload the kernel musb driver or unbind it via
  sysfs. Do not remove the driver for your OTG PHY, though (varies).

- 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.