Linux

Current: Freemyipod Linux

We are working on supporting Samsung/S5L-based devices which have an MMU. Currently our main focus is the iPod nano (7th generation), there are also builds for iPod nano (2nd generation), iPod nano (3rd generation) and iPod nano (5th generation). An experimental source tree is available on github.com/freemyipod/linux. Aditionaly User:ZeOne is working on making it work with the iPod nano (6th generation) you can read more about that on his page.

User Guide

Not yet available, as the Linux port isn't yet practical to use. We have no storage drivers, no sound driver...

Developer Guide

If you're somewhat familiar with embedded Linux, you can get started by building wInd3x, U-Boot and the Kernel as described below. However, you will have to provide your own userland (eg. buildroot, archlinux arm, ... anything armv6 compatible) and either run it from an initramfs or over NFS. A serial cable is not necessary, but very useful to troubleshoot boot issues.

Build everything

These are not copy-paste instructions. You are expected to understand what's happening.

You will need an arm-none-eabi- toolchain into your $PATH, eg. gcc-arm-embedded from your package manager.

First, build wInd3x.

Second, build U-Boot.

Third, Linux:

$ git clone https://github.com/freemyipod/linux
$ cd linux

For iPod nano (2nd generation):

$ git checkout n2g-wip
$ make ARCH=arm nano2g_defconfig

For iPod nano (3rd generation) and iPod nano (7th generation):

$ git checkout s5l87xx
$ make ARCH=arm apple_n46_defconfig # iPod nano (3rd generation)
$ make ARCH=arm apple_n31_defconfig # iPod nano (7th generation)

For iPod nano (5th generation):

$ git checkout n5g-wip
$ make ARCH=arm nano5g_defconfig

After configuring, build the kernel:

$ make ARCH=arm CROSS_COMPILE=arm-none-eabi- -j $(nproc) zImage

By this point, have a initramfs ready. If you wanna boot directly from nfs, edit CMDLINE in the kernel .config accordingly.

Finally, bundle together an u-boot image containing the kernel, your initramfs, and the device-tree (built by u-boot):

$ mkimage -A arm -C none -O linux -T multi -a 0x08000000 -e 0x08000000 -d arch/arm/boot/zImage:initramfs.gz:../u-boot/arch/arm/dts/s5l8730.dtb mImage

mImage is your combined image.

TODO: add instructions how to use the Makefile-based initramfs generation script and mkimage from U-boot.

Running

Connect your iPod nano in DFU mode.

For iPod nano (3rd generation) and later

Execute u-boot using wInd3x:

$ ./wInd3x cfw run ../u-boot/u-boot.bin

This should start u-boot. Running this for the first time will take a while, as some bootloader stages need to be downloaded, decrypted and modified. A new USB device (05ac:8007) appear on your host. Use dfu-util to upload mImage:

dfu-util --device 05ac:8007 --download mImage
dfu-util --device 05ac:8007 --detach

Note the --detach command: this is needed to get U-Boot to exit DFU mode and actually execute the image.

For the iPod nano (2nd generation)

You will have to chainload the rockbox bootloader with U-boot.

To do this, we assume you have already built U-boot dtbs along with Linux.

To create the mImage, run this command inside your Linux folder:

$ ./create_image.sh

Note: if it dosen’t work, you will have to make it executable, usually by running:

$ chmod +x create_image.sh

After it creates the mImage, go to your u-boot folder and build u-boot.bin.

$ make CROSS_COMPILE=arm-none-eabi- -j $(nproc) u-boot.bin

Now generate a fake rockbox.ipod that tricks it into starting U-Boot:

$ ./tools/mkimage -T ipod -d u-boot.bin rockbox.ipod

Copy this new rockbox.ipod into the .rockbox folder on your iPod nano 2G.

Then, in the serial console you'll see Linux booting:

## Booting kernel from Legacy Image at 08000000 ...
...
Starting kernel ...

[    0.000000] Booting Linux on physical CPU 0x0
[    0.000000] Linux version 6.2.0-rc4-00476-g4c4af4d7e53c (q3k@mimeomia) (arm-none-eabi-gcc (GNU Arm Embedded Toolchain 10.3-2021.10) 10.3.1 20210824 (release), GNU ld (GNU Arm Embedded Toolchain 10.3-2021.10) 2.36.1.20210621) #70 Fri Jan 20 18:02:56 CET 2023
...

The LCD display should start up and show a boot log. If not, try adding console=tty0 to your CMDLINE? You might also use fbcon=rotate:1 to rotate the framebuffer 90 degrees.

If everything goes well, the kernel should boot up and attempt to mount a rootfs. It's up to you to get this part working, at least until we streamline the process. The USB CDC EEM ethernet gadget should also appear on your host (probably as usb0, or some long systemd predictable name). The other end will be visible as 'usb0' on the device.

On iPod nano (7th generation) you'll need a DCSD cable (Alex/Magico), and the command line to get proper serial output:

picocom --baud 115200 --imap lfcrlf /dev/ttyUSB0

Now go on and have a go at reverse-engineering some peripherals! :)

Legacy: iPodLinux

The iPodLinux project supports all the PortalPlayer based iPods: iPod 1G-4G, Photo/Color, Video/5G/5.5G, Mini, iPod Nano 1G. It is currently semi-abandoned, and uses a very old ucLinux kernel build.