1 files changed, 465 insertions, 56 deletions

diff --git a/heimdall-frontend/doc-pak/README b/heimdall-frontend/doc-pak/README
index 27fba92..8dd296e 100644
--- a/heimdall-frontend/doc-pak/README
+++ b/heimdall-frontend/doc-pak/README
@@ -5,115 +5,524 @@ DISCLAIMER:
 

     This software attempts to flash your Galaxy S device. The very nature of

     flashing is dangerous. As with all flashing software, Heimdall has the

-    potential to damage (brick) your phone if not used carefully. If you're

+    potential to damage (brick) your device if not used carefully. If you're

     concerned, don't use this software. Flashing ROMs onto your phone may also

-    void your warranty. I am not responsible for the result of your actions.

-

+    void your warranty. Benjamin Dobell and Glass Echidna are not responsible

+    for the result of your actions.

 

 

 These instructions are for Linux operating systems.

 

-Installing Heimdall from Source:

 

-    1. First make sure you have installed build-tools and pkgconfig.

+Flashing Heimdall Firmware Package with Heimdall Frontend:

 

-    2. Open a terminal and navigate to the directory you extracted Heimdall to.

+    As of Heimdall Frontend 1.3 there are now two main ways to flash a ROM from

+    Heimdall Frontend. The simpler and preferred option is to download a

+    Heimdall Firmware Package and follow the following steps.

 

-    3. Then enter the following commands to compile and install libusb-1.0:

 

-            cd libusb-1.0

-            ./configure

-            make

-            sudo make install

-            cd ..

+    1. Fully charge your device (use the wall charger as it's faster).

 

-       If you have problems please consult http://www.libusb.org/        

+    2. Open Heimdall Frontend, which can be done by entering the following

+       command in a terminal:

 

-    4. Enter the following commands to compile and install Heimdall:

+            heimdall-frontend

 

-            cd heimdall

-            ./configure

-            make

-            sudo make install

-            cd ..

+    3. From the "Load Package" tab, under the "Heimdall Firmware Package"

+       section click the "Browse" button.

 

-	    NOTE: You can use "checkinstall" instead of "make install" in order

-                  to generate a redistributable package.

+    4. Use the dialogue that appears to navigate to, and select, the Heimdall

+       firmware package that you wish to flash.

 

-    5. Done

+    5. You will see progress bars appear as the package is decompressed and

+       extracted.

 

+       When the package has finished being decompressed you should see

+       information about the particular firmware package that has been

+       selected.

 

+    6. Verify that your device is listed under "Supported Devices". If it's not

+       then STOP immediately! DO NOT flash this firmware to your device!

+       Instead search for an appropriate firmware package for your device.

 

-Installing Heimdall Frontend from Source (Optional):

+       If you believe there is a mistake and your device is actually

+       supported please get in contact with the firmware developer (not Glass

+       Echidna!) and ask them to rectify the issue. If the developer provided

+       a URL you may be able to contact them by pressing the "Homepage" button.

 

-    1. First make sure you have installed Qt 4.6 or above,

-       available from http://qt.nokia.com/.

+    7. If you've verified your device is supported you may continue to press

+       the "Load / Customise" button.

 

-    2. Open a terminal and navigate to the directory you extracted Heimdall to.

+    8. You should now be looking at the "Flash" tab. If not verify that you did

+       in fact push the "Load / Customise" button.

 

-    3. Enter the following commands to compile and install Heimdall Frontend:

+       Generally, you won't NEED or WANT to customise a firmware package! In

+       which case you can safely move on to step 9.

 

-            cd heimdall-frontend

-            qmake heimdall-frontend.pro

-            make

+       Nonetheless, the "Flash" tab provides you with a means to customise the

+       firmware package before flashing it to your device. See "Performing a

+       Custom Flash with Heimdall Frontend" for more details.

 

-       NOTE: You can use "checkinstall" instead of "make" in order to generate

-             a redistributable package.

+    9. Put your Galaxy S device into download mode and plug it in to your PC.

 

-    4. The file output will be placed in the UNIX sub-directory. Move this file

-       to your preferred location.

+       Download mode can be accessed several different ways depending on your

+       particular device model. If you're unsure how to do this please search

+       online for the appropriate method.

 

-    5. Done

+   10. Press the "Start" button.

+

+   11. Heimdall Frontend will display the progress and inform you when the

+       flash is complete.

+

+       If something went wrong i.e. your device wasn't detected because it

+       wasn't in download mode, then the status section will let you know the

+       cause of the problem.

+

+

+

+Performing a Custom Flash with Heimdall Frontend:

 

+    This is the advanced means of flashing firmware to your device. You should

+    only flash firmware to your device this way if you know what you're doing.

 

+    If you're not an advanced user or a developer, in the event that a Heimdall

+    Firmware Package doesn't exist for the particular firmware you wish to

+    flash. I strongly recommend you get in touch with developer of the

+    firmware, or an advanced user, and politely ask them to create a Heimdall

+    Firmware Package for you.

+

+    If you're looking to customise an existing Heimdall Firmware Package then

+    follow steps 1-8 of "Flashing Heimdall Firmware Package with Heimdall

+    Frontend" then start from below with step 5.

 

-Flashing Firmware with Heimdall Frontend:    

 

     1. Fully charge your device (use the wall charger as it's faster).

 

-    2. Download a decrypted Samsung Galaxy S ROM and extract it to a directory.

+    2. Download a decrypted Samsung Galaxy S ROM or a Heimdall Firmware Package

+       and extract everything to the one directory.

 

-    3. If the ROM is provided as one of more archives (nested or otherwise),

-       extract them all to the same location.

+    3. If the ROM is not a Heimdall Firmware Package it may instead be provided

+       as multiple archives (nested or otherwise), extract them all to the same

+       location.

 

-       NOTE: If you want to use the CSC then extract it last.

+       NOTE: If you want to use the CSC then extract it last. If you're asked

+             to overwrite files then do so.

+

+    3. Open Heimdall Frontend, which can be done by entering the following

+       command in a terminal:

+

+            heimdall-frontend

+

+    4. Select the "Flash" tab. From the "Flash" tab you're able to completely

+       customise a flash. 

+

+    5. Before you can chose which partitions you want to flash with particular

+       files you MUST first select a PIT file. To do this click the "Browse"

+       button in the "PIT" section. This will open a dialogue allowing you to

+       navigate to and select a valid PIT (.pit) file.

+

+    6. If a valid PIT file has been selected then "Add" button below the list

+       box will become enabled. Press this button to add a partition to your

+       flash.

+

+    7. When you first add a partition you will see the "Partition Name" and

+       "Partition ID" be populated with information. Use the "Partition Name"

+       drop down to select which partition you wish to flash. "Partition ID"

+       will automatically update and is never directly editable.

+

+    8. You must then select a file to flash to the partition that you just

+       specified using the "Browse" button under the "File / Partition". You

+       will not be able to flash, create a firmware package or add another

+       partition until you have selected a file. However, you're still able to

+       press the "Remove" button if you've decided not to flash the partition

+       you've just specified.

+

+    9. When you've specified a file name then you'll be able to see the updated

+       information in the partition list to the right. You can select any

+       partition from this list and customise it as you see fit.

+

+       You can also remove a partition from the list by selecting it and

+       clicking the "Remove" button. Removing a partition from the list doesn't

+       remove it from your device, it simply means it will not be flashed.

+

+   10. Repeat steps 7-9 as often as needed to specify all the partions/files

+       that you wish to flash.

+

+   11. Now you can chose whether you would like to repartition your device as

+       well as whether you would like to prevent the device rebooting once a

+       flash has been completed. These options can be enabled or disabled by

+       toggling the "Repartition" and "No Reboot" check-boxes.

 

-    3. Open Heimdall Frontend.

+       In the general case you will only need to enable repartition if you wish

+       to change the PIT file on your device. Keep in mind that repartitioning

+       will wipe your device!

 

-    4. Put your Galaxy S device into download mode.

+       The "No Reboot" option is rarely required. It's mostly in place so you

+       can manually boot straight into recovery mode after a flash (rather than

+       booting up normally).

 

-    5. For each file you wish to flash use "Browse" to select the file.

+   12. If you've added at least one partition to your flash (and selected a

+       file for that partition) then the "Start" button will be enabled. Press

+       the "Start" button to begin the flashing process.

 

-    6. Press "Start".

+       You may notice that the "Create Package" tab becomes available at the

+       whenever the "Start" button becomes available. From this tab you're able

+       to create a reusable, redistributable Heimdall Firmware Package with the

+       files and partitions you just selected. See "How to Create a Heimdall

+       Firmware Package" for details.

 

-    7. Heimdall Frontend will display the progress and inform you when the

+   13. Heimdall Frontend will display the progress and inform you when the

        flash is complete.

 

+       If something went wrong i.e. your device wasn't detected because it

+       wasn't in download mode, then the status section will let you know the

+       cause of the problem.

 

 

-Flashing Firmware from Command Line / Terminal:

+

+Flashing Firmware from Command Line:

 	

-    1. Fully charge your device (use the wall charger as it's faster).

+    1. Fully charge your phone (use the wall charger as it's faster).

 

-    2. Download a decrypted Samsung Galaxy S ROM and extract it to a directory.

+    2. Download a decrypted Samsung Galaxy S ROM or a Heimdall Firmware Package

+       and extract everything to the one directory.

 

-    3. If the ROM is provided as one of more archives (nested or otherwise),

-       extract them all to the same location.

+    3. If the ROM is not a Heimdall Firmware Package it may instead be provided

+       as multiple archives (nested or otherwise), extract them all to the same

+       location.

 

        NOTE: If you want to use the CSC then extract it last.

 

-    4. Open a terminal and navigate to the directory where you extracted the

-       ROM files.

+    4. Put your Galaxy S device into download mode and plug it in..

 

-    5. Type the following to list all the functionality Heimdall supports:

+    5. Open a terminal and navigate to the directory where you extracted

+       the ROM/firmware files.

+

+    6. Type the following to list all the functionality Heimdall supports:

 

             heimdall help

 

-    8. Use the instructions to manually enter a command with all the files you

+    7. Use the instructions to manually enter a command with all the files you

        want to flash.

 

-       Here is an example that does a full flash and repartition:

+       Here is an example that does a full flash and repartition on a GT-I9000:

 		

             heimdall flash --repartition --pit s1_odin_20100512.pit --factoryfs factoryfs.rfs --cache cache.rfs --dbdata dbdata.rfs --primary-boot boot.bin --secondary-boot Sbl.bin --param param.lfs --kernel zImage --modem modem.bin

 

-    9. Done

+

+    8. Heimdall will display the progress as it flashes so that you know things

+       are working as they should.

+

+

+

+How to Create a Heimdall Firmware Package:

+

+    Firstly, Heimdall's firmware package format is just a regular TAR archive

+    compressed with gzip. The only two real requirements are that a valid

+    firmware.xml must be included (refer to Appendix A) and you can only

+    include files (no directories, links etc.) As such if you'd like there is

+    nothing preventing you creating Heimdall packages manually. Of course

+    Heimdall Frontend provides a simple user interface that takes care of all

+    the hard work for you.

+

+    There are two ways in which you can create a firmware package. You can

+    create a package from scratch, or you can load an existing package, apply

+    modifications and then save the package. Creating a package from scratch

+    is the preferred approach, by taking this approach you're far less likely

+    to run into file name length limitations, these are not Heimdall's own

+    limitation but rather a limitation of the TAR archive format.

+

+    Before you can access Heimdall Frontend's firmware creation functionality

+    (available from the "Create Package" tab) you must first specify which

+    files will be included in your package as well as a few flashing options

+    i.e. Whether or not users should repartition when flashing. This

+    information must be filled out from the "Flash" tab in exactly the same

+    fashion you would provide information to flash your device (see "Performing

+    a Custom Flash with Heimdall Frontend"). As mentioned above, it's not the

+    preferred means, but you're able to load an existing package as a starting

+    point for this information.

+

+    Once you've specified the files/partitions you wish to include in your

+    firmware package the "Create Package" tab will become available. Clicking

+    this tab will display additional information that you can include in your

+    package. In order to continue you must fill out all sections except for the

+    URLs section, which is optional. The following is break-down of what all

+    these options mean.

+

+    - General Firmware Information: -

+

+        Firmware Name - This is the name of your particular firmware. An

+            example would be "Cyanogenmod".

+

+        Firmware Version - This is the particular version identifier for your

+            package. Any valid string will be accepted although a the inclusion

+            of decimal point version number is preferred releases i.e. "7.1".

+            If it makes sense then feel free to append a text string like "RC1"

+            or "Beta 1" to the decimal point version.

+

+        Platform Name - This is the name of platform (or operating system) that

+            your firmware is based on. In most cases this will simply be

+            "Android".

+

+        Platform Version - This is the operating system version that your

+            firmware is based on. Again decimal point version numbers are

+            preferred over text, i.e. "2.3.4" is preferred over "Gingerbread".

+

+

+    - Developers -

+

+    URLs (Optional):

+

+        Homepage - Here you can enter your personal URL or a URL particularly

+            pertaining to the firmware being packaged. The URL must be well

+            formed for it to work. An example of a well formed URL is

+            "http://www.glassechidna.com.au/products/heimdall/". It is

+            important to include "http://" in order to specify the protocol as

+            other protocols such as "ftp://" are equally valid although

+            unlikely to be used.

+

+        Donate - Here you can enter a URL that will link users to a page to

+            make donations for the effort you've put into developing your

+            firmware. Once again the URL must be well formed but there is no

+            requirement on how your donation page should work. For instance

+            both "http://www.glassechidna.com.au/donate/" and

+            "http://forum.xda-developers.com/donatetome.php?u=2710388" are

+            equally valid.

+

+    Developer Info:

+

+        Name - Here you can enter in the name of individual team members or a

+            team name. Click "Add" and the developer will be added to the list

+            on the right. If you make a mistake you can select a developer from

+            the list and click "Remove". You can list as many developers as you

+            like however size constraints of the "Load Package" means only a

+            few will be visible. Where possible you may want to opt for team

+            names over listing individual team members.

+

+

+    - Supported Devices -

+

+    This section allows you to create a list of devices that are supported by

+    your particular firmware. Although Heimdall isn't capable of enforcing this

+    we strongly recommend you take this section seriously. If filled out

+    correctly you could help save a number of accidental bricks!

+

+    Device Info:

+

+        Manufacturer - This is where you can enter the name of the manufacturer

+            for a particular device. For now this will most likely be

+            "Samsung".

+

+        Name - This is the human readable name for a particular device.

+            "Galaxy S", "Galaxy S II", "Droid Charge", "Vibrant" and

+            "Galaxy S (Telstra)" are all valid names. There are a lot of

+            possible variations here so be as specific as you think is

+            necessary.

+

+        Product Code - This is by far the most important bit of device

+            information. Device names tend to be region specific and further

+            subject to the whims of telecommunication companies and resellers.

+            Product Codes (or product IDs) are designated by manufacturers and

+            are generally the definitive means of referring to a particular

+            device. Examples are "GT-I9000", "GT-I9100" and "SCH-I897". If

+            you're unsure of a particular product code then Google and

+            GSMArena are your friends!

+

+

+    After filling out all the necessary information the "Build" button will be

+    enabled. If it's still disabled then you know you're missing some required

+    information. In particular you must specify at least one developer and at

+    least one supported device. Pressing the "Build" button will bring up a

+    save dialogue where you must chose a file name for your particular package.

+    Don't worry about specifying the ".tar.gz" extension Heimdall Frontend will

+    take care of this automatically.

+

+    Once you've chosen a file name Heimdall Frontend will begin the process of

+    building the firmware package. In doing so a valid firmware.xml file will

+    be generated from the information entered, all files will be archived in a

+    single TAR file then the TAR archive will be compressed via gzip

+    compression. Compression will take a little while but you will see progress

+    bars so you know the application hasn't hung. When the progress bars

+    disappear you're finished making your package.

+

+    Congratulations! You're now ready to redistribute your firmware package

+    online or by any means you see fit.

+

+

+

+Appendix A - firmware.xml

+

+The following details a part of the Heimdall Firmware Package format. This

+is only relevant to developers or advanced users who wish to create Heimdall

+Firmware Packages outside of Heimdall Frontend or in some way integrate support

+for the format in their own software.

+

+

+All Heimdall Firmware Packages must contain a file called firmware.xml. This

+file stores information stores meta-data for the package as well as information

+about other files contained in the package that indicates how they should be

+flashed.

+

+The format is fairly straight-forward so it won't be explained in great detail,

+nonetheless the following is an example of a valid firmware.xml file.

+

+<?xml version="1.0" encoding="UTF-8"?>

+<firmware version="1">

+	<name>Test Firmware</name>

+	<version>1.1</version>

+	<platform>

+		<name>Android</name>

+		<version>2.3.4</version>

+	</platform>

+	<developers>

+		<name>Benjamin Dobell</name>

+		<name>Hedonism Bot</name>

+	</developers>

+	<url>http://www.glassechidna.com.au/</url>

+	<donateurl>http://www.glassechidna.com.au/donate/</donateurl>

+	<devices>

+		<device>

+			<manufacturer>Samsung</manufacturer>

+			<product>GT-I9000</product>

+			<name>Galaxy S</name>

+		</device>

+		<device>

+			<manufacturer>Samsung</manufacturer>

+			<product>GT-I9000T</product>

+			<name>Galaxy S (Telstra)</name>

+		</device>

+		<device>

+			<manufacturer>Samsung</manufacturer>

+			<product>GT-I9000M</product>

+			<name>Vibrant</name>

+		</device>

+	</devices>

+	<pit>Nl3276-I9000 s1_odin_20100512.pit</pit>

+	<repartition>0</repartition>

+	<noreboot>0</noreboot>

+	<files>

+		<file>

+			<id>0</id>

+			<filename>gq3276-boot.bin</filename>

+		</file>

+		<file>

+			<id>24</id>

+			<filename>Uh3276-cache.rfs</filename>

+		</file>

+		<file>

+			<id>22</id>

+			<filename>em3276-factoryfs.rfs</filename>

+		</file>

+		<file>

+			<id>11</id>

+			<filename>fl3276-modem.bin</filename>

+		</file>

+		<file>

+			<id>21</id>

+			<filename>Xd3276-param.lfs</filename>

+		</file>

+		<file>

+			<id>3</id>

+			<filename>if3276-Sbl.bin</filename>

+		</file>

+		<file>

+			<id>6</id>

+			<filename>cr3276-zImage</filename>

+		</file>

+	</files>

+</firmware>

+

+

+New lines need not be included and the order in which elements are specified

+does not need to match that of the above example.

+

+One and only one <firmware> element must be included. The <firmware> element

+must also have a version attribute specified. The version must be parsable as

+an integer and indicates what version of the Heimdall Firmware Package

+specification the package adheres to.

+

+All data is stored as strings, however a <file>'s <id> element must be parsable

+as an integer. The <id> value represents the partition ID (according to the

+specified PIT file) that the file should be flashed to.

+

+A <firmware>'s <repartition> and <noreboot> elements must also be parsable as

+an integer. However, as they represent boolean values, a value of zero ("0")

+means false (or disabled) where as a non-zero value (typically "1") means true

+(or enabled).

+

+File names are specified relative to the TAR archive in which firmware.xml and

+all other files are to be stored. Heimdall Firmware Packages do not support

+directories or links, as such file names should only be a name and not a path.

+

+<url> and <donateurl> are the only optional elements, all other elements must

+be included.

+

+

+

+Appendix B - Installing Heimdall from Source:

+

+    1. First make sure you have installed build-tools and pkgconfig.

+

+    2. Open a terminal and navigate to the directory you downloaded,

+       or extracted, Heimdall to.

+

+    3. Enter the following commands to compile and install libusb-1.0:

+

+            cd libusb-1.0

+            ./configure

+            make

+            sudo make install

+            cd ..

+

+       If you have problems please consult http://www.libusb.org/

+

+    4. Enter the following commands to compile libpit.

+

+            cd libusb-1.0

+            ./configure

+            make

+            cd ..

+

+       NOTE: There is no need to run "sudo make install".

+

+    4. Enter the following commands to compile and install Heimdall:

+

+            cd heimdall

+            ./configure

+            make

+            sudo make install

+            cd ..

+

+	    NOTE: You can use "checkinstall" instead of "make install" in order

+                  to generate a redistributable package.

+

+    5. Done

+

+

+

+Appendix C - Installing Heimdall Frontend from Source:

+

+    1. Compile and install Heimdall, see Appendix B.

+

+    2. First make sure you have installed Qt 4.7 or later, available from:

+

+          http://qt.nokia.com/downloads/

+

+    3. Open a terminal and navigate to the directory you extracted Heimdall to.

+

+    4. Enter the following commands to compile and install Heimdall Frontend:

+

+            cd heimdall-frontend

+            qmake heimdall-frontend.pro

+            make

+            sudo make install

+

+       NOTE: As an alternative to "sudo make install" you may chose to generate

+             a package by typing the following:

+

+                sudo checkinstall --pkgversion <version>

+

+             Where <version> is the current Heimdall release e.g. 1.3.0

+

+    5. Done

+