--------
Overview
--------

These files are the porkupan/igorsk test firmware loader, as well as some
cleanup and modifications to run a script from an SD card by Xaphiosis.

DISCLAIMER: use of these tools may cause filesystem damage requiring
reformatting, thereby erasing any notes/books/pictures/whatever you may have on
it. Also, it may put the filesystem in a state where the reader cannot perform
the reformat itself. Although the loader/runsd itself shouldn't do any other
damage, they might load a cramfs system or execute another script which will.
The software is provided "as is" with no warranty or support. Tread carefully.

------------
Requirements
------------

Sony reader PRS600 running the porkupan/boroda firmware with autorun support.
At the time of writing, that is 1.05d, available as PRS600.upd.1.05d.zip

An SD card.

------------
Installation
------------

Place these files in the /test directory on your reader's internal memory. This
typically appears with the label READER on your system when the reader is
plugged in via USB.

On the SD card, create the following file (its contents is irrelevant):
    /Sony Reader/software/autorun.xml

Perform this test
 * make sure the reader isn't plugged in via USB
 * press the VOL+ and HOME keys simultaneously
 * keep holding them while you insert the SD card
 * keep holding them until a menu appears

If you see a menu with a warning sign in the middle and text involving
porkupan/igorsk and "loader version 0.2", everything works.

If you see a neat sony menu with lots of diagnostic options, you did not
install the files in this directory into /test on READER or aren't running
firmware with autorun support.

If nothing happens, you didn't create autorun.xml in the appropriate place.

-----
Usage - Firmware loader
-----

If you wish to make use of the firmware test loader functionality, place your
cramfs image and the md5 hash in the same directory, i.e.
    /test/new_opt.600.img
    /test/new_opt.600.md5
    on the reader's internal memory

Note that the .md5 file looks like this:

89fbf4532f1033dc0b353c64ddbe2796 *new_opt.600.img

That "*" may or may not be relevant, I don't know. Tools like md5sum don't put
it in, so I put it in by hand. Other than that, you can generate the md5 like
so:
    md5sum new_opt.600.img > new_opt.600.md5

To load the new firmware, insert SD card while VOL+ and HOME buttons are
pressed (as per Installation above), and press the zoom key (looking glass with
+ in it). You'll see "Running Script", then "Script Finished". Then the ebook
software will restart, which takes a while (the LED blinks a few times). When
you see the main screen again, you should be running new firmware. In order to
make sure you actually are running the main firmware, try change the
Settings->About screen.

Although it is referred to as a "test firmware loader", it does not actually
load the entire firmware. The "firmware" loader actually decompresses the
cramfs image, then re-mounts all the relevant directories (/usr, /opt, /bin,
etc) using mount --bind, and then restarts tinyhttp (which hosts the sony ebook
reader application).

Essentially, it is useful to test modifications to the tinyhttp environment,
such as changing the javascript code, modifying fonts, etc. without needing to
reflash and possibly brick the reader. It does not re-run any boot scripts or
reload drivers.

IMPORTANT: if you've used the loader to load a new cramfs image, shut down the
device before trying to do that again, otherwise strange things will happen.
Also, if you modify the files in /test on READER, it's a good idea to shut down
the device, as some files are cached.

-----
Usage - Running a script on an SD card
-----

The other option on the loader menu (VOL+ and HOME while inserting SD card, as
per Installation) is "run SD script". To activate it, press the OPTION key.

What it does is mount the SD card and execute the following file on it if it
exists:
    /reader/main.sh

The executed file may assume the following:
 * SD card is mounted at /tmp/sd_card
 * Executing files/scripts from /tmp/sd_card/reader will work

Although it is possible, I recommend placing output files (logs etc) in a
different directory to prevent polluting the source, but that's up to you.

-------------------------
How the running bit works
-------------------------

The file libfskLoad.so is a fake extension module. It has one function: fskLoad.

This function executes the following via system():
    chmod +x /tmp/script.sh
    /tmp/script.sh

The file myvm2.xml is a configuration file understood by the fsk configuration
loader. It just declares that there's an extension in /tmp/libfskLoad

So all we have to do is copy any script we want into /tmp/script.sh and
libfskLoad.so into /tmp, and then tell the Fsk system to load the configuration
from myvm2.xml

This can be done from javascript:
    var myvm = FskInclude.load(path);
    var t = myvm.load();
    (see autorun.js)
When Fsk attempts to load the extension, it'll call FskLoad. Normally this
performs some bizarre registration mechanism, but in the case of our module it
just runs /tmp/script.sh

-------------------
xaph.net - May 2010

