Loader 2

From wikiPodLinux

**ipodloader 2**
iPodLinux Bootloader

Category	Utility
Maintainer	Thomas Tempelmann
Last updated	18 May 2006
Version	2.5
Runs on	All iPods
Requires	an iPod
Download
Support	Loader 2 Talk Page

ipodloader2 (Loader2) is a new bootloader for iPodLinux that allows you to load the kernel from a file on a FAT32 or ext2 filesystem, instead of having to re-make_fw whenever it changes. It also has a GUI, as opposed to Loader 1.

Current released version is 2.5, which supports all Windows and Macintosh formatted iPods (WinPods and MacPods).

Specifically, the iPod may be formatted in ext2/3, FAT16, FAT32 or HFS+ (Mac OS Extended) but not HFS (Mac OS Standard) for the Loader to be able to read files such as the kernel and configuration file from it (though you may also place those into the firmware partition, which the loader can always read).

How it works

The main purpose of this bootloader is to allow you to choose between different operating systems for your iPod. By default, you can choose between Apple's, iPodLinux, and, if installed, Rockbox.

It will sound a short beep and display a menu with the available choices when you reboot the iPod. (Note: The bootloader does not make any sound on 1G, 2G and 3G models yet.)

You can select from the menu by turning the wheel or pressing the Rew, Fwd, Menu or Play buttons, then press the Center (Action) button to make your choice. At that point either the Apple software will start or one of the other firmware files will be loaded and then started.

There is also a optional timeout - if you do not make a choice, a default will be chosen for you. That prevents that the iPod remains unnecessarily waiting in the bootloader.

You can disable this timeout, though. If you do not make a choice within a minute then the iPod will beep once as a reminder, and shut itself off after another minute, to preserve power.

Getting it

An older version (Loader 2.4) is included with Installer 2.

You can also download a compiled version of the loader above in the blue box.

You may also get the source code and compile it yourself. iPodLoader2 source code is available from the Subversion repository. Fetch it with the following command:

% svn co https://ipodlinux.svn.sourceforge.net/svnroot/ipodlinux/apps/ipod/ipodloader2/

Compile with (you'll need the toolchain 3.4.3 installed):

% cd ipodloader2

% make

Installing the Loader

The loader.bin file needs to be merged into the firmware partition so that when the iPod loads the Apple firmware, it will instead load the loader, which takes over control (however, the way the loader gets inserted will lead to the Apple firmware still being loaded along with it, which makes it possible to start the Apple OS then via the ramimg option instead of having to load it again from disk).

Windows installation

Automatic installation

You can automatically install Loader 2 onto an iPod using the iPod Application Manager. Please note that the iPod Application Manager is Unsupported by the core iPodLinux Developers.

Manual installation

You will need the programs ipod_fw.exe (http://ipl.dataghost.com/ipod_fw.exe) and ipodpatcher.exe (http://download.rockbox.org/bootloader/ipod/ipodpatcher/win32/ipodpatcher.exe).
Create a new folder, e.g. call it "iPodLoader", and place loader.bin, ipod_fw.exe and ipodpatcher.exe into it. If you do not know how to use the Command Prompt, please create the folder directly on your desktop and use the given examples in the following instructions.
Open a Command Prompt (shell), by pressing Start -> Run and then typing "cmd" and pressing enter.
Go to the directory mentioned above (e.g.: cd desktop, then cd ipodloader)
Type ipodpatcher 0. If it outputs a partition table, remember the number 0 and type it in instead of NUMBER when you do the commmands below. If you get an error, type ipodpatcher 1. If you get an error again, type ipodpatcher 2 and keep going on and on untill it outputs a partition table. Then remember the number. If you don't find it by 9, something might be wrong.
Then type the commands below, replacing IPOD MODEL with 1g, 2g, 3g, 4g, 5g, scroll, touch, dock, mini, photo, color, nano or video. Press enter after every command and wait for it to complete.

ipodpatcher.exe NUMBER -r bootpartition.bin (This one may take a while)
ipod_fw.exe -o apple_os.bin -e 0 bootpartition.bin

If your iPod is an iPod Video (5G) or an iPod nano 1G with firmware version 1.2 or above then do this additional step:

ipod_fw.exe -o apple_sw_5g_rcsc.bin -e 1 bootpartition.bin

Now you have extracted the original Apple firmware. Use the following commands to create a new firmware including the loader:

ipod_fw.exe -g IPOD MODEL -o iplboot.bin -i apple_os.bin loader.bin

Note: If you have a nano 1G with FW-version 1.2 or above IPOD MODEL has to be 5G.

ipodpatcher.exe NUMBER -w iplboot.bin

Mac OS X and Linux installation

You have to use make_fw for the following instructions.

While the following instructions are made for Linux and OS X users, Windows users you may also read Using Cygwin and then follow the instructions here.

Preparation (once)

First you'll have to save the original firmware image from your ipod to a file.

Use this command on Linux (see here for help):

% dd if=/dev/sdX1 of=orig_firmware.bin

Or, if you're on a Mac (see here for help):

% dd if=/dev/diskX skip=63 count=30000 of=orig_firmware.bin

This will create a file of up to 120MB with the content of the firmware partition.

The following command extracts the Apple OS firmware from the partition backup file:

% ./make_fw -o apple_os.bin -e 0 orig_firmware.bin

For a fifth-generation iPod (5G, iPod Video) or a nano 1G (with firmware version 1.2 or above), you will in addition need to execute:

% ./make_fw -o apple_sw_5g_rcsc.bin -e 1 orig_firmware.bin

Note: Remember not to change the first filename, it's hard-coded into make_fw when reading it back later.

If the above yields a 40 byte file, you may need to start over with the above dd line, but with an offset of 252 instead of 63 like so:

% dd if=/dev/diskX skip=252 count=30000 of=orig_firmware.bin

Conversely, you could do the following as well, instead:

% dd if=/dev/diskX skip=63 bs=2048 count=7500 of=orig_firmware.bin

If you understand why these are interchangable, give yourself a cookie.

Inserting the loader into the firmware

Recreate the firmware file by combining the original firmware and loader.bin:

% ./make_fw -g gen -v -o my_sw.bin -i apple_os.bin loader.bin

Note:: Replace gen with the generation code of your iPod (run ./make_fw without arguments to see the names it allows). If you have a nano 1G with FW-version 1.2 or above gen has to be 5G.

Finally, copy the new firmware file in my_sw.bin (which is a few MB in size) back to the firmware partition of your iPod.

REMEMBER to replace the 63 below with 252 as above, if that worked for you.

If you're using Linux:

% dd if=my_sw.bin of=/dev/sdX seek=63

If you're on a Mac:

% diskutil unmount /dev/diskXs3  (use s2 if it's a WinPod)
% dd if=my_sw.bin of=/dev/diskX seek=63

And if you use Windows with Cygwin:

% dd if=my_sw.bin of='\\.\physicaldriveX' seek=63

Note: There is no "1" nor "s2" at the end of the disk name! Instead, by using seek=63, it ensures that it always gets to the right location, no matter if it's a MacPod or a WinPod.

Simple usage

If your needs are simple (you just want to boot Linux, Rockbox or Apple's iPod software), you don't need to make a configuration file.

Simply place the iPodLinux kernel file in any of the following folders:

partition 2/ (this is your FAT32 or HFS+ formatted music partition)
partition 2/Notes/
partition 3/ (this is the ext2 partition added to WinPods to contain the iPodLinux system files)
partition 3/boot/

And name the kernel file either:

kernel.bin
linux.bin
vmlinux

(You may also place the kernel as a file (image) called "linx" into the firmware partition, but you'd need to use make_fw to accomplish that, and you're on your own with that.)

Reboot your iPod, and all should work:

A menu appears with the choices to start the Apple OS, turn the iPod off, and, if the linux kernel file is present, start Linux.

More complex usage

If your needs aren't simple, you'll need to create a configuration file.

Config File Locations

Pick one of the following spots for it:

partition 2/ipodloader.conf
partition 2/Notes/ipodloader.conf
partition 2/loader.cfg
partition 2/Notes/loader.cfg
partition 3/ipodloader.conf
partition 3/boot/ipodloader.conf
partition 3/loader.cfg
partition 3/boot/loader.cfg
partition 1/lcnf (that is the firmware partition, you can add files into it using the make_fw tool)

The above order is significant - if you have a file in multiple places, the first one found from this list is taken.

The configuration file format is very simple and somewhat GRUB-esque. It consists of a few settings, followed by your list of image files for the menu, one per line.

A line in the config file is ignored if it begins with ";" or "#"

Startup Settings

The following setting commands are available (their format is: name = value):

timeout: seconds to wait before the default item in the menu is automatically chosen. Set to 0 to have no timeout. Default is 15 seconds.
default: menu item number that is chosen when then timeout has been reached. Default is 1 (meaning the first item).
debug: a set of values you can combine (add) for debugging purposes:

1 - print messages to screen and pause for a few seconds before the menu appears or an image is started.
2 - print messages to screen and wait for a keypress before the menu appears or an image is started.
4 - print messages to screen and pause for a second after each printed line
8 - lines counting from 1 to 15 will be printed. This is to test the scroll feature (see below)
16 - (in version 2.3) show a test screen in which you can adjust the contrast, turn backlight on/off and test the keys.

contrast: adjustment for the contrast used when the menu is displayed. Use a positive value to increase, a negative value to decrease the contrast - this value should hardly be outside of -10 to +10, or you'll probably not see anything on the display. Default is 0 (= no adjustment).
backlight: turn backlight on (1) or off (0) when the menu is displayed. Default is 0 (off)for grayscale iPods and 1 (on) for color iPods.
Menu colors can be specified in the configuration file now (provide values from 0 to 255 for the red, green and blue values):
- bg_color = (r,g,b) -- menu background color, default is (0,255,128).
- hilight_color = (r,g,b) -- menu hilight and progress bar color, default is (128,128,0).
- bg_gradient = x -- set x to 0 to have a plain background or 1 to have a gradient ranging from black to bgcolor, default is 1.
Once the loader has started, as well as after an idle time of a minute in the menu, it beeps once (not supported on 1G to 3G models yet). The beep duration and pitch can be altered in the config file:
- beep_duration -- duration of beep in ms (1/1000s of seconds), default is 50ms. You may set it to 0 to disable beeps (including wheel clicks).
- beep_period -- pitch of beep. The lower the value the higher the frequency. Recommended is a value between 20 and 40, default is 30.

Menu Entries

Next come the menu choices. Here's an example.

Apple OS @ ramimg
iPodLinux @ (hd0,1)/linux.bin
Rockbox @ (hd0,1)/.rockbox/rockbox.ipod
Disk Mode @ diskmode
Sleep @ standby

The line format is a name, followed by an at sign (or an equals sign, or a space if the name has no spaces — your choice), then the path to the image. Paths are of the format (hd0,part)/path where part is the partition number (the first partition, containing the loader and usually as well the Apple firmware, is zero) and path is the path to your file. Remember that files on the FAT partition must have 8.3 names, and be in 8.3 directories (that is, names consisting of at most eight characters plus at most three characters of extension). Thus, (hd0,0) in this example refers to the firmware partition, and (hd0,1) refers to the FAT32 (on WinPods) or to the HFS+ (on MacPods) partition, which is the one usually mounted on your computer when you plug in your iPod and which contains your music files.

You can have up to 16 entries in the menu, although iPods may not be able to show so many entries on the small screen.

Caution: The image file name must not contain blanks (space characters)!

There are some "special" image names supported:

reboot: reboots the iPod, getting you then back to the loader (not very useful other than for testing, probably)
diskmode: puts the iPod into disk mode
ramimg or osos: starts the "osos" image already loaded into memory with the loader. This is the quickest way to use for launching the Apple firmware.
standby: puts the iPod to sleep (but only if it is not connected via FireWire or USB to a computer, or it will wake up and reboot again).

Parameter Passing

You can pass arguments to the Linux kernel:

Simply add a blank (space character) and then the arguments in text form after the image path name (this means that you can not have a blank in the image name)

Current versions of the kernel do not evaluate the arguments yet. But once the kernel is updated, you can then find the arguments in /proc/cmdline.

Until then, you can retrieve the argument string using the tool getLoader2Args which is included in the source distrubution of Loader2. It includes a Readme file giving you more detailed instructions on how to use it.

If you'd like a tutorial in the forums, here are two you can check out:

KyleV's extensive tutorial (http://ipodlinux.org/forums/viewtopic.php?t=9615) with everything documented out. For Windows and Linux users.

fiftyfour123's tutorial (http://ipodlinux.org/forums/viewtopic.php?t=9616) with a zip file to download and install. For Mac users.

Config File Example

Here is a more complete example for a config file:

# iPodLoader 2.3 config file
backlight = 1
timeout = 10
default = 2
# here come the menu choices:
Apple @ ramimg
iPodLinux @ (hd0,1)/linux.bin
Sleep @ standby
Disk Mode @ diskmode

Loading the Apple iPod firmware

You can also place Apple's firmware into the other partitions, in case you like to alter it often, so that you do not have to insert it into the firmware partition using make_fw every time. To do that, place the extracted apple_os.bin onto your iPod's file system and add a line such as this to your config file:

Apple OS @ (hd0,1)/apple_os.bin

Loading the Rockbox firmware

Several things you need to know:

Do not change the name of the .rockbox directory or the name of the rockbox.ipod firmware file. This is necessary because the Rockbox software provides an update feature which can only work if it can locate itself under this name.
Rockbox only works on FAT formatted WinPods, but not on HFS formatted MacPods! (That's a Rockbox limitation).
Since 2007-03-20 the rockbox.ipod file moved inside the /.rockbox directory.
When listing the file name in the configuration file, it needs to be named something like /.rockbox/rockbox.ipod .

Caveats

If something doesn't work as described here, let us know. Preferrably, contact Tempel.
You can't load Linux images in the old way, from the firmware partition. Yet.
- Update: this should now work; load from (hd0,0)/osos1. The 1 is for a non-default Linux; use 0 if it's default.
Disk reading is slow.
The slowness of framebuffer updates on 5g makes disk reading seem even slower.

Known problems

1G, 2G and 3G models can't make beeps nor clicks via their piezo buzzer. Reason is just lazyness. Perhaps one day someone will make the effort to add the code (serial comms) to the loader.
Loading the Apple OS as a file does not work with Loader 2.4 (.zip). If you need that feature use either an older version (Loader 2.3) or the latest version which can be found above in the blue box.

Authors

ipodloader2 was written by slowcoder.
The config system, this guide, and some tweaks to the ext2 implementation were done by josh.
HFS+ support by Thomas Tempelmann.

Retrieved from "http://ipodlinux.org/Loader_2"

Categories: Bootloaders | Installation | Utilities