Linux iPod Manual

Introduction

This document describes how to install and run Linux on your iPod. This document is a work in progress and attempts to document the current state of the Linux for iPod release. Note that this document deals only with the installation and operational aspects of the software. The build documentation has details on how you can build your own release.

This document is based on the 0.3 release of the Linux kernel and the 030323 release of the root filesystem.

Any feedback on this documentation is greatly appreciated.

Overview

The Linux on iPod project offers a development platform for building applications that run on the iPod hardware. This document covers the following sections.

Installation
1. Backup iPod firmware
2. Install Linux kernel
3. Install Linux root filesystem
Using Ethernet
Using the Remote Control
Compiling for the iPod

Installation

For the moment please consult the build documentation for details on how to backup your firmware and install the Linux Kernel and root filesystem.

Using Ethernet

When the iPod boots the Linux kernel it will automatically configure its local ethernet device (ethernet over firewire/IEEE1394) and then starts inetd so that network connections via telnet may be made.

The default configuration is for the iPod to use 192.10.1.2 and to allow telnet connections. The default address may be changed by editing the /etc/rc script.

Please note, the required ethernet driver is from the 2.4.20 kernel only. The newer driver in 2.4.21 and 2.5.xx will not work as it uses an incompatible protocol for ARP (which unfortunately the iPod cannot support).

Patching your Kernel

To connect to your iPod you will firstly need to configure ethernet over firewire on your host - that is your PC or Mac you are connecting to the iPod. Unfortunately due to a bug in the iPod ethernet driver it is necessary to use a special version of the ethernet driver on the host. At present this is only possible on Linux hosts running a 2.4.20 (or possibly earlier) kernel. The following patch should be applied to the eth1394.c file in the drivers/ieee1394 directory of your kernel tree.

--- eth1394.c.orig	2003-03-12 16:35:47.000000000 +0100
+++ eth1394.c	2003-03-12 16:38:27.000000000 +0100
@@ -680,6 +680,11 @@
 	}
 
 	ptask->skb = skb;
+	/* hack to address broadcast packets to the "other" node */
+	if ( (dest_node & NODE_MASK) == NODE_MASK ) {
+		dest_node = priv->host->node_id ^ 0x1;
+		addr = ETHER1394_REGION_ADDR;
+	}
 	ptask->addr = addr;
 	ptask->dest_node = dest_node;
 	INIT_TQUEUE(&ptask->tq, hpsb_write_sched, ptask);

Configuring eth1

Once you have built your modified ethernet driver you can then load that module and configure the new device.

Firstly to create the new ethernet interface you need to load the module:

	modprobe eth1394

Once loaded a new ethernet interface should be available. This new interface will normally be eth1 however if you already have a number of ethernet interfaces it may be different. As root type ifconfig -a to show all available interfaces, the last unconfigured one will likely be your firewire interface.

To configure the network simply run the command:

	ifconfig eth1 192.10.1.1

Where eth1 is the ethernet interface you have determined above. The IP address of 192.10.1.1 will work correctly with the default configuration of the iPod. If this address is not appropriate with your local network configuration you will have to modify the configuration on iPod (edit the /etc/rc script) as appropriate.

Connecting to the iPod

Once configured you should be able to ping the iPod with the following command:

	ping 192.10.1.2

Assuming that is successfull you should be able to telnet to the iPod and see a login prompt. To login, specify "root" as the username and "default" as the password.

The iPod kernel also includes NFS client support which has been used with some success. If you export file systems from your host PC, you can mount them on your iPod.

Using the Remote Control

The remote control is connected to the iPod via a UART serial device and so input can be read simply by reading from the appropriate serial device under Linux (/dev/ttyS0). More useful though a line dicipline driver converts this input to standard tty style input.

To use this driver simply start the inputattach program as so:

	inputattach -ipod /dev/ttyS0 &

Once this command is running pressing a button on the remote control will result in input on /dev/tty0. Currently each key is mapped to numerical input according to the following table.

Key Input
Play/Pause 1
Volume Up 2
Volume Down 3
Fast Forward 4
Rewind 5

Compiling for the iPod

To compile for the iPod it is recommended to use a cross compiler on your host PC.

Using the cross compiler it is necessary to use the -elf2flt option when linking in order to convert the ELF binaries to the uClinux "flat format" binaries. Normally a Makefile would specify this option in the LDFLAGS or in the CFLAGS macro.

	CFLAGS=-Wl,-elf2flt

or,

	LDLAGS=-elf2flt