Added boot process information to help someone find out what really happens.
[bootos.git] / PORTING
blob6918832869d44c43bef2685fd609124eb7af7f01
1 ================================================================================
2                          Porting AsbestOS to a device
3 ================================================================================
5 AsbestOS is designed to be easy to port to any implementation of the Lv-2 USB
6 exploit (or, indeed, even future exploits). There are two main components
7 in the distribution:
9 - stage1
10 - stage2
12 Stage1 is the first code portion of AsbestOS that runs (it may be preceded by
13 an "egghunt" exploit phase on some versions of the exploit, but that's up to the
14 exploit). It installs a USB driver into Lv-2, then waits until the "final" USB
15 device is connected. Once it is, it requests stage2 in chunks, then launches it.
16 It is also responsible for initially catching both CPU threads.
18 Stage2 is the main portion of AsbestOS and is responsible for replacing Lv-2,
19 cleaning up after it, setting up the initial network, and loading the kernel via
20 TFTP. It is also compressed and wrapped with a decompressor stub.
22 AsbestOS has very few requirements, making it very easy to port to existing
23 implementations of the USB exploit, whether on microcontroller dongles, portable
24 media players, phones, etc. The only requirements are:
26 - At least 40KB of free internal or external storage (currently),
27 - Implementation of a few USB control messages to deliver stage2 on-demand,
28 - An incarnation of the exploit able to execute at least a <3KB buffer of code
29   (no requirements on location or input registers).
31 Your implementation must eventually load and direct execution to the code in
32 stage1.bin. This code is position-independent (with some overlapping exceptions)
33 and does not require any specific values for input arguments. It will return to
34 the caller when done installing the device driver. If your implementation
35 requires any headers before the payload (e.g. descriptors, metadata), keep those
36 and simply replace the data where the executable code begins.
38 The device must eventually virtually insert a USB device with vendor ID 0xAAAA
39 and Product ID 0x3713. At this stage, stage1 will issue the following USB
40 control requests to it:
42 PRINT (bmRequestType=0x40, bRequest=1, wLength=len)
43         Print a debug message. If you don't have any usable debug output, just
44         accept and discard the data.
45 GET_STAGE2_SIZE (bmRequestType=0xc0, bRequest=2, wLength=4)
46         Get the total size of stage2. You should return 4 bytes indicating the size
47         of stage2 in BIG-ENDIAN byte ordering.
48 READ_STAGE2_BLOCK (bmRequestType=0xc0, bRequest=3, wIndex=offset, wLength=len)
49         Return a block of stage2. The stage1 code issues reads in blocks of 0x1000
50         bytes, except for the last block. wIndex is the offset in units of 0x1000
51         bytes (that is, the offset >> 12).
53 For example, on a microcontroller with at least 64KB of Flash, you could build
54 in stage2, while on a microcontroller with less Flash you could stream it from
55 an external memory (EEPROM, Flash, SD card, ...) or even through a serial port
56 from a PC.
58 In other words, on any device currently executing a PSJailbreak-derived payload,
59 you just need to replace it with stage1, add in stage2, and add three request
60 handlers to deliver stage2 when requested, and change the final device VID to
61 0x3713.
63 If you believe that the current vanilla stage1 will not work for your device,
64 please drop me a line and I'll try to accomodate for it. It's easier if I add
65 a few configuration options and keep a common codebase instead of ending up with
66 a dozen minor forks for device-specific tweaks. There shouldn't be much to
67 change in stage1 anyway, except for possibly timing.
69 Licensing notes:
71 Stage1 and stage2 are licensed under the GNU General Public License, version 2.
72 However, you can insert stage1/2 into any implementation of the exploit, which
73 need not be licensed under the GPLv2. This is because simply embedding a binary
74 blob isn't considered "linking" in any practical sense (even if you technically
75 use the linker); it isn't any different from, say, embedding GPLv3 code inside
76 an initramfs built into a GPLv2 Linux kernel. Any modifications that you make
77 to the stage1 or stage2 code, must be licensed under the GPLv2. As usual,
78 please make sure that you comply with all the licenses involved.