manual.shtml

<!--#include file="include/iplHeader.html"-->

<h1>Linux iPod Manual</h1>

<h2>Introduction</h2>

<p>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 <a href="build.shtml">build documentation</a> has details on how you can build your own release.

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

<p>Any feedback on this documentation is greatly appreciated.


<h2>Overview</h2>

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

<ul>
	<li>Installation
		<ol>
		<li>Backup iPod firmware
		<li>Install Linux kernel
		<li>Install Linux root filesystem
		</ol>

	<li>Using Ethernet
	<li>Using the Remote Control
	<li>Compiling for the iPod
</ul>

<h2>Installation</h2>

<p>For the moment please consult the <a href="build.shtml">build documentation</a> for details on how to backup your firmware and install the Linux Kernel and root filesystem.

<!-- 
<h3>Backup iPod firmware</h3>
<h3>Install Linux kernel</h3>
<h3>Install Linux root filesystem</h3>
-->

<h2>Using Ethernet</h2>

<p>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.

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

<p>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).

<h3>Patching your Kernel</h3>

<p>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 <code>eth1394.c</code> file in the <code>drivers/ieee1394</code> directory of your kernel tree.

<pre>
--- 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);
</pre>


<h3>Configuring eth1</h3>

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

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

<pre>
	modprobe eth1394
</pre>

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

<p>To configure the network simply run the command:

<pre>
	ifconfig eth1 192.10.1.1
</pre>

<p>Where <code>eth1</code> 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 <code>/etc/rc</code> script) as appropriate.

<h3>Connecting to the iPod</h3>

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

<pre>
	ping 192.10.1.2
</pre>

<p>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.

<p>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.


<h2>Using the Remote Control</h2>

<p>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 (<code>/dev/ttyS0</code>).  More useful though a line dicipline driver converts this input to standard tty style input.

<p>To use this driver simply start the <code>inputattach</code> program as so:

<pre>
	inputattach -ipod /dev/ttyS0 &
</pre>

<p>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.

<p><blockquote><table>
<tr><th>Key<th>Input
<tr><td>Play/Pause<td>1
<tr><td>Volume Up<td>2
<tr><td>Volume Down<td>3
<tr><td>Fast Forward<td>4
<tr><td>Rewind<td>5
</table>
</blockquote>


<h2>Compiling for the iPod</h2>

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

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

<pre>
	CFLAGS=-Wl,-elf2flt
</pre>

<p>or,

<pre>
	LDLAGS=-elf2flt
</pre>

<!--#include file="include/iplFooter.html"-->