Loader 2

Getting it / Download

• You can 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).

To install Loader 2 we are using ipodpatcher. ipodpatcher is a tool designed for installing the Rockbox bootloader on your iPod, but we can use it to install Loader 2 as well.

Download ipodpatcher here:

• Windows32
• MacOSX (universal binary)
• Linux32x86
• Linux64amd64

On Linux and MacOSX you have be root to use ipodpatcher or use the administrator account if you are doing this step on Windows.

Rename the loader binary to loader.bin. Copy the ipodpatcher binary and loader.bin into the same directory. Open the terminal (on Windows Click on start > run. Type cmd and hit return) and use the cd command to go to the directory where ipodpatcher and loader.bin are in.

Install the loader with the following command:

# ./ipodpatcher -ab loader.bin

Reboot your iPod, and all should work:

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

Updating

If you want to update Loader 2 you can use the very same command without uninstalling the older version.

Uninstalling the Loader

You can uninstall the bootloader nearly the same way you have installed it. Download ipodpatcher from above and run the following command from the terminal:

# ./ipodpatcher -d

Alternatively you can double click the ipodpatcher binary and press "d" if it asks you what you want to do.

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 2/boot/
• 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/boot/ipodloader.conf

• partition 2/loader.cfg
• partition 2/Notes/loader.cfg
• partition 2/boot/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
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. 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.

Since version 2.6, easier shortcuts for partitions can be used in configuration files. The format is [type]/path where type is one of the following: dos, fat, win, vfat, fat32, ext, ext2, hfs, hfs+ or linux. A shortcut will match the first partition of the specified type. Only linux will match the first ext2 partition and will then, if no partition was found, fallback to the first HFS+ partition. Examples can be seen below:

# Try to load Rockbox from the FAT32 partition:
Rockbox @ [fat]/.rockbox/rockbox.ipod
Rockbox @ [win]/.rockbox/rockbox.ipod

# Try to load Linux from the EXT2 partition:
Linux @ [ext2]/linux.bin

# Try to load Apple OS from the HFS+ partition:
Linux @ [hfs]/appleos.bin

# Try to load Linux first from the EXT2, then from the HFS+ partition:
Linux @ [linux]/linux.bin

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 with everything documented out. For Windows and Linux users.

fiftyfour123's tutorial 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

Note: Incase you've made a mistake with creating a configuration file and neither the Apple firmware nor the Disk Mode entries are on the menu anymore read the Key Combinations page to figure out how to reboot your iPod into Disk Mode manually to fix the configuration file.

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

Loading Rockbox with Loader 2 should work fine right now, but there is no guarantee that the next commit to Rockbox' SVN tree won't break it again. If you have problems with loading Rockbox from Loader 2 make sure you test loading it with the official Rockbox bootloader before. To do so simply double click ipodpatcher and follow the instructions on the screen. You do not have to uninstall Loader 2 before. If loading Rockbox works fine now, please add a bug report in our tracker. If Rockbox still doesn't work now with the official Rockbox bootloader check Rockbox' Tracker.

Loader 2 autodetects Rockbox if you haven't made a configuration file yet. To add a Rockbox entry to your boot menu simply add the folloing line to your configuration file:

Rockbox @ (hd0,1)/.rockbox/rockbox.ipod

Several things you need to know:

• Do not change the name of the .rockbox directory or the name of the rockbox.ipod firmware file inside the .rockbox directory.
• Rockbox only works on FAT formatted WinPods, but not on HFS+ formatted MacPods (that is a Rockbox limitation)!

Caveats

• If something doesn't work as described here, please check the bug tracker and fill a bug report if needed.
• 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.

Old versions

• Loader 2.3
• Loader 2.4
• Loader 2.5

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.