aboutsummaryrefslogtreecommitdiffstats
path: root/OSX
diff options
context:
space:
mode:
authorBenjamin Dobell <benjamin.dobell+git@glassechidna.com.au>2013-05-13 00:08:30 +1000
committerBenjamin Dobell <benjamin.dobell+git@glassechidna.com.au>2013-05-13 00:08:30 +1000
commit07dcba54fc8cc5b7c6515305aa233e24a58adc94 (patch)
tree60b65485b8e446c87d883922e70aee1b7104bfd8 /OSX
parent4b089d808482f6e4c32250f29a3c723ef9c9d673 (diff)
downloadexternal_heimdall-07dcba54fc8cc5b7c6515305aa233e24a58adc94.zip
external_heimdall-07dcba54fc8cc5b7c6515305aa233e24a58adc94.tar.gz
external_heimdall-07dcba54fc8cc5b7c6515305aa233e24a58adc94.tar.bz2
Update copyright notices, version identifier and documentation for 1.4.0 release.
Diffstat (limited to 'OSX')
-rw-r--r--OSX/README.txt1074
1 files changed, 543 insertions, 531 deletions
diff --git a/OSX/README.txt b/OSX/README.txt
index 3f27a04..47b0bf4 100644
--- a/OSX/README.txt
+++ b/OSX/README.txt
@@ -1,533 +1,545 @@
-Heimdall (c) 2010-2011 Benjamin Dobell, Glass Echidna
-http://www.glassechidna.com.au/products/heimdall/
-
-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 device if not used carefully. If you're
- concerned, don't use this software. Flashing ROMs onto your phone may also
- void your warranty. Benjamin Dobell and Glass Echidna are not responsible
- for the result of your actions.
-
-
-These instructions are for OS X operating systems.
-
-
-Installing Heimdall and Heimdall Frontend Binaries:
-
- 1. Run "Heimdall Suite.pkg" and follow the instructions.
-
- 2. Reboot your system.
-
- 3. Done
-
-
-
-Flashing Heimdall Firmware Package with Heimdall Frontend:
-
- 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.
-
-
- 1. Fully charge your device (use the wall charger as it's faster).
-
- 2. Open the Heimdall Frontend (heimdall-frontend) application.
-
- 3. From the "Load Package" tab, under the "Heimdall Firmware Package"
- section click the "Browse" button.
-
- 4. Use the dialogue that appears to navigate to, and select, the Heimdall
- firmware package that you wish to flash.
-
- 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.
-
- 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.
-
- 7. If you've verified your device is supported you may continue to press
- the "Load / Customise" button.
-
- 8. You should now be looking at the "Flash" tab. If not verify that you did
- in fact push the "Load / Customise" button.
-
- Generally, you won't NEED or WANT to customise a firmware package! In
- which case you can safely move on to step 9.
-
- 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.
-
- 9. Put your Galaxy S device into download mode and plug it in to your PC.
-
- 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.
-
- 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.
-
- 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 (or files) that
- you wish to flash, then I strongly recommend you get in touch with developer
- of the firmware (or files) and politely ask them to create a Heimdall
- Firmware Package for you. In doing so then you don't have to worry about
- making mistakes due to inexperience.
-
- 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.
-
-
- 1. Fully charge your device (use the wall charger as it's faster).
-
- 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 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.
-
- 3. Open the Heimdall Frontend (heimdall-frontend) application.
-
- 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.
-
- If you do not already have a valid PIT file stored on your computer you
- can download your device's PIT file from the "Utilities" tab.
-
- 6. If a valid PIT file has been selected then "Add" button below the
- "Partitions (Files)" 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.
-
- 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!
-
- 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).
-
- 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.
-
- 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.
-
- 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:
-
- 1. Fully charge your phone (use the wall charger as it's faster).
-
- 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 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. If you're asked
- to overwrite files then do so.
-
- 4. Put your Galaxy S device into download mode and plug it in..
-
- 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
-
- 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 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
-
-
- 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 from 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 a 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 version identifier for your package. Any
- valid string will be accepted although a the inclusion of decimal
- point version number is preferred 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 the 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 visual constraints of the "Load Package" tab means
- only a few names 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 both 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 flash information and meta-data for the package as well as
-information about other files contained within the package.
-
-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 XCode and pkgconfig.
-
- NOTE: There are several different ways you can install pkgconfig, one
- option is to use Macports (http://www.macports.org/).
-
- 2. Open a terminal and navigate to the directory you downloaded,
- or extracted, Heimdall to.
-
- 3. Download, compile and install libusb-1.0:
-
+Heimdall (c) 2010-2013 Benjamin Dobell, Glass Echidna
+http://www.glassechidna.com.au/products/heimdall/
+
+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 device if not used carefully. If you're
+ concerned, don't use this software. Flashing ROMs onto your phone may also
+ void your warranty. Benjamin Dobell and Glass Echidna are not responsible
+ for the result of your actions.
+
+
+These instructions are for OS X operating systems.
+
+
+Installing Heimdall and Heimdall Frontend Binaries:
+
+ 1. Run "Heimdall Suite.pkg" and follow the instructions.
+
+ 2. Reboot your system.
+
+ 3. Done
+
+
+
+Flashing Heimdall Firmware Package with Heimdall Frontend:
+
+ 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.
+
+
+ 1. Fully charge your device (use the wall charger as it's faster).
+
+ 2. Open the Heimdall Frontend (heimdall-frontend) application.
+
+ 3. From the "Load Package" tab, under the "Heimdall Firmware Package"
+ section click the "Browse" button.
+
+ 4. Use the dialogue that appears to navigate to, and select, the Heimdall
+ firmware package that you wish to flash.
+
+ 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.
+
+ 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.
+
+ 7. If you've verified your device is supported you may continue to press
+ the "Load / Customise" button.
+
+ 8. You should now be looking at the "Flash" tab. If not verify that you did
+ in fact push the "Load / Customise" button.
+
+ Generally, you won't NEED or WANT to customise a firmware package! In
+ which case you can safely move on to step 9.
+
+ 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.
+
+ 9. Put your Galaxy S device into download mode and plug it in to your PC.
+
+ 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.
+
+ 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.
+
+ 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 (or files) that
+ you wish to flash, then I strongly recommend you get in touch with developer
+ of the firmware (or files) and politely ask them to create a Heimdall
+ Firmware Package for you. In doing so then you don't have to worry about
+ making mistakes due to inexperience.
+
+ 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.
+
+
+ 1. Fully charge your device (use the wall charger as it's faster).
+
+ 2. Download a decrypted device ROM or a Heimdall Firmware Package
+ and extract everything to the one directory.
+
+ 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.
+
+ 3. Open the Heimdall Frontend (heimdall-frontend) application.
+
+ 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.
+
+ If you do not already have a valid PIT file stored on your computer you
+ can download your device's PIT file from the "Utilities" tab.
+
+ 6. If a valid PIT file has been selected then "Add" button below the
+ "Partitions (Files)" 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.
+
+ 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!
+
+ 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).
+
+ 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.
+
+ 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.
+
+ 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:
+
+ 1. Fully charge your phone (use the wall charger as it's faster).
+
+ 2. Download a decrypted device ROM or a Heimdall Firmware Package
+ and extract everything to the one directory.
+
+ 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. If you're asked
+ to overwrite files then do so.
+
+ 4. Put your Galaxy S device into download mode and plug it in..
+
+ 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
+
+ 7. Before flashing, you must first know the names of the partitions you
+ wish to flash. These can be obtained by executing:
+
+ heimdall print-pit --no-reboot
+
+ The inclusion of --no-reboot ensures the phone will not reboot after PIT
+ file has been downloaded and displayed. After executing a command with
+ the --no-reboot argument, the next command should include the --resume
+ argument.
+
+ NOTE: You can still safely reboot your phone manually (with the power
+ button) after executing --no-reboot commands.
+
+ 8. Use the help and print-pit output to construct a command with all the
+ file you want to flash.
+
+ Here is an example that does a full flash and repartition on a GT-I9000:
+
+ heimdall flash --repartition --resume --pit s1_odin_20100512.pit --FACTORYFS factoryfs.rfs --CACHE cache.rfs --DBDATA dbdata.rfs --IBL+PBL boot.bin --SBL Sbl.bin --PARAM param.lfs --KERNEL zImage --MODEM modem.bin
+
+ 9. 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 from 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 a 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 version identifier for your package. Any
+ valid string will be accepted although a the inclusion of decimal
+ point version number is preferred 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 the 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 visual constraints of the "Load Package" tab means
+ only a few names 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 both 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 flash information and meta-data for the package as well as
+information about other files contained within the package.
+
+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 XCode and pkgconfig.
+
+ NOTE: There are several different ways you can install pkgconfig, one
+ option is to use Macports (http://www.macports.org/).
+
+ 2. Open a terminal and navigate to the directory you downloaded,
+ or extracted, Heimdall to.
+
+ 3. Download, compile and install libusb-1.0:
+
http://www.libusb.org/
- NOTE: Alternatively you may install Macport's libusb-devel package.
-
- 4. Enter the following commands to compile libpit.
-
- cd libpit
- ./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 ..
-
- 5. If you haven't installed the driver before, enter the following:
-
- cd OSX
- sudo ./install-kext.sh
-
- 6. Done
-
-
-
-Appendix C - Installing Heimdall Frontend from Source:
-
- 1. Compile and install Heimdall, see Appendix B.
-
- 2. First make sure you have installed XCode from your OS X install DVD.
- You'll also need 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
-
- 5. Open Finder and navigate to the heimdall-frontend sub-directory. Open
- the newly created XCode project.
-
- 6. From the menu bar select Build -> Build. This outputs heimdall-frontend
- to /Applications
-
- 7. Done
-
+ NOTE: Alternatively you may install Macport's libusb-devel package.
+
+ 4. Enter the following commands to compile libpit.
+
+ cd libpit
+ ./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 ..
+
+ 5. If you haven't installed the driver before, enter the following:
+
+ cd OSX
+ sudo ./install-kext.sh
+
+ 6. Done
+
+
+
+Appendix C - Installing Heimdall Frontend from Source:
+
+ 1. Compile and install Heimdall, see Appendix B.
+
+ 2. First make sure you have installed XCode from your OS X install DVD.
+ You'll also need 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
+
+ 5. Open Finder and navigate to the heimdall-frontend sub-directory. Open
+ the newly created XCode project.
+
+ 6. From the menu bar select Build -> Build. This outputs heimdall-frontend
+ to /Applications
+
+ 7. Done
+