2010
02.11
This is a method to boot into Debian via fastboot on the nexus one from
your SD-card. This is NOT a chroot Debian image, it is honest to goodness
Debian running directly on the hardware. This is completely non destructive to
the android OS. Connectivity to the device can be provided by adbd, ssh, or
serial console. Wifi works perfectly. I have not tested bluetooth. Touchscreen
works, but needs tweaking. X11 works in framebuffer using the Debian
testing branch (squeeze). In order to get a full fledged X driver with
3D acceleration we'll need the driver from
https://www.codeaurora.org/index.php?xwinp which I haven't been able to get
to build. This doesn't mean it's broken. It just means I suck
at cross compiling.

Todo:
-Tweak settings to make X more usable.
-Get the CodeAurora MSM/QSD X driver working.
-Find decent method to input text.
-Test bluetooth
-Look into using the GSM radio.
-Audio
-Figure out how to configure adbd.

This how-to pulls heavily from the debian-arm install guide.
http://www.debian.org/releases/stable/arm/index.html.en

Requirements:
adb (android-sdk)
fastboot
chroot (on your phone)
sdcard with room for Debian - 2gigs seems to be sufficient for Debian + xfce.
I Had about a gig leftover. For this guide, I'm starting fresh with a 4GB sdcard
that I'm devoting completely to Debian. According to the Debian install guide,
you need at least 32MB of memory and 500MB of hard disk space. The guide
recommends at least 5GB of storage for a comfortable install. But since I'm
using the lighter XFCE4 desktop I haven't had any space issues.
http://www.debian.org/releases/stable/arm/ch03s04.html.en

1. Re size the SD card
(don't forget to backup your data before you go messing with partition tables!!)
	(optional) Instead of using a partition on your main SD card, you could
	simply use another sdcard and dedicate the entire thing to Debian.
	Note: android didn't like me very much when I did this. I put in a
	tiny (30MB) vfat partition right at the beginning of the blank sdcard
	I mounted the sdcard on my Ubuntu system and used gparted to break
	off 2 gigs to use for Debian. Make sure you keep the normal android
	sdcard partition as the first partition otherwise android
	will not be able to find it.
	If you're using apps to SD or anything else like that. Debian should
	probably have the last partition. I'm not 100% sure on this since I
	don't use my sdcard for anything else.

2. Format the new partition.
	ext2 is probably best. (least abusive on the sdcard. ext3 & 4 have
	journaling which may be bad for the life of your sdcard)
	I used Gparted for this part as well.

3. If you are installing from an Ubuntu or Debian desktop, install debootstrap
	$ sudo apt-get install debootstrap
	Users of other distros may be able to get debootstrap but I'm not sure.

4. Mount the sdcard on your desktop.
	anywhere will do just remember where you put it :-p
	ex. mount /dev/sde2 /mnt/android

5. debootstrap
	run debootstrap
	you can change to a mirror closer to you if you don't want to use the
	US mirror - http://www.debian.org/misc/README.mirrors
	I'm using the Debian testing release (squeeze). I had issues getting
	X11 running in lenny, and have not tested sid.
	(lenny is stable, squeeze is testing, and sid is unstable)
	http://www.debian.org/releases/

	debootstrap --arch armel --foreign <release> </path/to/debian> <mirror>
	# debootstrap --arch armel --foreign squeeze /mnt/android \

http://ftp.us.debian.org/debian
6. debootstrap(part2)
	Unmount the sdcard from your desktop.
	Reboot the phone here since you've been mucking with the sdcard
	file system. Android didn't like my sdcard until I did.

	$ adb shell

	mount the sdcard somewhere on the android file system.
	look in /dev/block for the sdcard.
	Typically mmcblk0p# where # is the partition number.
	ex. # mount -t ext2 /dev/block/mmcblk0p2 /data/local/mnt

	chroot/debootstrap

	# chroot /data/local/mnt/ /debootstrap/debootstrap --second-stage
	this will take a while especially if you have a slower sdcard.

6. While that's working, now is a good time to get to work on your kernel
	I used the open source android kernel 2.6.29
	http://android.git.kernel.org/
	Started with mahimahi_defconfig (default nexus one kernel config from google) and starting customizing from there.
	Things to note.
	- file systems - don't forget to add support for whatever file systems
	  you need. Your root file system support cannot be built as a module.
	- wireless driver config - You may want to change the location the
	  kernel looks for your wifi firmware (this is different from the
	  kernel module).
	  I stuck mine in /etc/firmware, default is /system/etc/firmware.
	  If you don't change this, you will have to put the firmware
	  in /system/etc/firmware
	- wireless - Add in support for standard wifi extensions.
	- networking - standard tcp/ip stuff... iptables if you want ect...
	- I wasn't able to get the kernel to boot into Debian until I turned
	  off initramfs support.
	  (note. this was before I discovered the 'noinitrd' kernel
	  kernel cmdline option. So disabling initrd may not be required)
	- If for some reason you are using ext4, it will fail to mount unless
	  you add in large devices and files support
	- Default kernel command string - has no effect.
	  This gets overwritten when you boot with fastboot or make a boot.img
	- Drivers - I left all the normal android drivers in.
		-Changed the firmware path for wifi.
		-Added in support for virtual terminal under character devices
		-Enabled MSM serial support (if you don't have a serial cable
		 this is useless to you)
		-You can build the wifi driver into the kernel if you want.

	Link to the kernel config I used. Use at your own risk.
	It works for me but I can't promise it's perfect or even good.
	http://irregular-expression.com/tmp/config
	I would love input on building a better kernel config.
If you don't want to build your own kernel. You can download mine here.

7. Chroot and configure Debian.
	There are still some things that need configuring before we reboot into
	Debian. Since fbconsole does not appear to be working, if you don't
	have a serial cable you will be flying blind until Debian is fully
	booted and you can connect with ssh. Since there are still things to do
	before we reboot, we're going to chroot into Debian just like if we are
	using a Debian chroot image.

	For more information and examples of config files.
	http://www.debian.org/releases/stable/arm/apds03.html.en

	It's probably best to use wifi for your data on the phone for this.
	If you're on Linux and connected to the same router as the phone, copy
	over your resolv.conf

	$ adb push /etc/resolv.conf /data/local/etc/resolv.conf

	If you are not in Linux or are not connected to wifi you will need to
	set up resolv.conf with something sane.

	ex. from jay freeman's original Debian chroot.
	$ echo 'nameserver 4.2.2.2' > /data/local/etc/resolv.conf

	push wifi driver to the device

	$ adb push <kernelroot>/drivers/net/wireless/bcm4329/bcm4329.ko \
	  /data/local/etc/firmware

	copy /system/etc/firmware/fw_bcm4329.bin to wherever you
	specified in the kernel config.

	# cp /system/etc/firmware/fw_bcm4329.bin /data/local/mnt/etc/firmware/

	Setup environment variables, copy over adbd, and other stuff needed to
	make things work. This should all be run from within an adb shell

	# cp /sbin/adbd /data/local/mnt/sbin/adbd
	# sysctl -w net.ipv4.ip_forward=1
	# export PATH=/usr/bin:/usr/sbin:/bin:$PATH
	# export TERM=linux
	# export HOME=/root

	Next chroot and setup mount points

	# chroot /data/local/mnt /bin/bash
	# mount -t devpts devpts /dev/pts
	# mount -t proc proc /proc
	# mount -t sysfs sysfs /sys

	Welcome to Debian chroot that we all know and love.
	Lets finish configuring this thing.

	Configure adbd to run on boot and create a symlink so
	adbd can find bash.

	Edit /etc/rc.local. Add adbd before exit 0

	#add this to /etc/rc.local
	/sbin/adbd &

	# mkdir -p /system/bin/
	# ln -s /bin/bash /system/bin/sh

	Now we need to be able to install packages
	don't forget if you are not using squeeze to change it here

	# echo 'deb http://ftp.us.debian.org/debian squeeze main' \
	   >> /etc/apt/sources.list
	# apt-get update

	You should see aptitude updating it's package list.

	Install some needed packages

	# apt-get install wpasupplicant wireless-tools udev ssh

	Other packages
	All up to your choice. Things like text editors, X, ect...
	some suggested packages

	# apt-get install locales vi

	Wifi driver
	When you try to load the wifi module, Linux will complain about not
	being able to parse modprobe.d. To fix this run depmod. If it complains
	a directory doesn't exist then create it.

	# depmod -a

	move bcm4329.ko to /lib/modules
	# cp /etc/firmware/bcm4329.ko /lib/modules

	Edit /etc/modules and add the bcm4329 module 

	# /etc/modules: kernel modules to load at boot time.
	#
	# This file contains the names of kernel modules that should be loaded
	# at boot time, one per line. Lines beginning with "#" are ignored.
	# Parameters can be specified after the module name.
	bcm4329

	Setup fstab - critical: don't forget to configure the root file system
	or your system won't boot. If you like, mount your vfat sdcard partition
	here too. Don't forget to mkdir for the mount point.
	*note* after boot the memory card is located at /dev/mmcblk0p#.

	Here is my /etc/fstab

	# /etc/fstab: static file system information.
	#
	# file system    mount point   type    options     dump pass

	/dev/block/mmcblk0p2 / ext2 defaults 1 1
	proc /proc proc defaults 0 0
	/dev/mmcblk0p1 /media/sdcard vfat defaults 0 0

	configure network
	These two files will be tuned to what you need.
	Here are a couple examples.

	/etc/network/interfaces

		auto lo
		iface lo inet loopback

		auto eth0
		iface eth0 inet dhcp
		wpa-driver wext
		wpa-conf /etc/wpa_supplicant.conf

	/etc/wpa_supplicant.conf

		ctrl_interface=/var/run/wpa_supplicant

		network={
        	ssid="myOpenNetwork"
        	scan_ssid=1
        	key_mgmt=NONE
		}
		network={
        	ssid="MyHomeNetwork"
        	scan_ssid=1
        	key_mgmt=WPA-PSK
        	psk="MyWifiPassword"
		}
		network={
        	ssid="MyFriendsWifi"
        	scan_ssid=1
        	key_mgmt=WPA-PSK
        	psk="MyFriendsWifiPassword"
		}

	inittab
	no need for getty so comment it out in /etc/inittab
	if you have a serial cable, configure it here. something like this.
	T0:23:respawn:/sbin/getty -L ttyMSM0 115200 linux

	hostname
	configure your system's hostname - you can set this to whatever you like
	# echo DebianHostName > /etc/hostname

	Set root password
	# passwd

	Add user account
	# useradd -m yourusername -s /bin/bash
	# passwd yourusername

8. Almost there!
	Double check your configs and have your kernel handy.
	The next step is to boot into Debian.

9. Boot Debian
	put the device into fastboot mode
	$ adb reboot bootloader
	the '-c' flag specifies arguments to pass to the kernel for boot.
	This is probably the bare minimum.

	Format is "fastboot -c 'kernelcmdline' boot zImage"

$ fastboot -c 'root=/dev/mmcblk0p2 rw rootfs=ext2 init=/sbin/init \
rootwait noinitrd' boot zImage
	Wait just a few minutes. DHCP is probably the longest part of this.

10. Connect via ADB.
	If everything went well you should be able to log into the
	phone via adb. adb push and pull work as well. 

	$ adb shell

11. Install X11
	For a basic X11 install. This is probably not what you want.
	# apt-get install xserver-xorg

	You can install whatever window manager/desktop environment you like,
	I used XFCE. Most window managers likely depend on xserver-xorg so it
	will get pulled in when you install. 

	# apt-get install xfce4 

	After I installed xfce4 I was able to get X on the main display by
	simply running startxfce4

	# startxfce4

	By default Debian is configured to only allow root to startx.
	If you want to be able to run X as a user edit /etc/X11/Xwrapper.config
	*note* even with this I haven't been able to run X as a normal user.
	Only root.

	Change allowed_users=console
	to allowed_users=anybody

Currently touchscreen is a little weird. It feels almost like using a
laptop touchpad. The mouse moves much faster then your finger and tapping for
click isn't enabled by default but two finger tap will right click. You can
also move the mouse with the trackball. Clicking the trackball registers a
click. But you have to wiggle the trackball just a tiny bit after you click to
make it register. I am going to work on tweaking the fdi policy files to
make things a little more usable.

Text entry is a bit of a pain point currently. There are several on screen
keyboards out there. One interesting one I found is called cellwriter.
The touchscreen will need to be tweaked before it will work well with
onscreen keyboards.

For other ideas on window managers and other software check out this link
http://wiki.openmoko.org/wiki/Debian
Screenies! http://picasaweb.google.com/JairunCaloth/Debian?feat=directlink

18 comments so far

Add Your Comment
  1. Very Cool! Makes me want one just to play with this a bit! Debian FTW!

  2. oh man, can you make it more simple ?, download the file from terminal is big problem :(, can you just share your sd image please.
    thanks

  3. I went through all of this. But It doesn’t boot. I get to the part where I use flashboot to flash the kernel and the boot image over, and that seems to go ok, with no errors, but after only a little while the phone reboots itself and goes into my normal ROM with no debian.

  4. I’ve identified a problem with the fastboot command line in the howto.

    Try this:
    fastboot -c ‘root=/dev/mmcblk0p2 rw rootfs=ext2 init=/sbin/init rootwait noinitrd’ boot zImage

  5. WOW! Quite an hard procedure but I think it’s worth the while!

  6. Have you been able to test any other hardware? I’m considering getting a Motorola Droid and it’d be funny to see Debian on my phone. :P

  7. I have not tested on other hardware, though the process should be very similar. I would think the main thing you would need to change is rebuilding the kernel for your specific device.

  8. Well, When I get my Droid finally, Would you be interested in helping me? Is there a irc channel that you would recommend? It seems like a worthwhile goal to have a distro like Debian on a phone like the droid. Especially since the droid is USB host capable. There’s work being done to enable android’s kernel to allow it and it would be awesome to have a portable server in a sense.

  9. I have exactly the same issue as digitalirony. Did you work out a solution digitalirony or does the author have any suggestions?

    Any help much appreciated.

  10. Any chance the actual GSM/HSDPA phone features can work under this setup? I’m torn between an n900 and a nexusone, but if there was a chance I could get a debian environment running on the nexusone that still has basic phone functionality, that would be very cool.

  11. Any news on booting this on other devices?

    Got this [ http://www.androidfanatic.com/component/fireboard/?func=view&id=2248&catid=9 ] working on my Hero and this [ http://www.androidfanatic.com/component/fireboard/?func=view&id=1615&catid=9 ]!

    Anw i’m asking cause i want ubuntu to boot on my device. tried a blog that had a lot of info but didnt succeed… anyone?

  12. Maybe… I’ve been able to send an SMS using ofono http://ofono.org

  13. The brcm driver gives an error and reboots the machine :(
    http://pastebin.ca/1887723

  14. I used the config from my phone, You can extract it from /proc/config.gz on your phone (I guess it’s up to HTC to include it, so it might not be available on all phones)
    I also downloaded the kernel source from developer.htc.com rather than using the one from the GIT tree

  15. hi, I think the most important thing lacking is an alsa driver,
    I tried to write one but it plays 4x faster
    apart that you have a todo:
    >-Get the CodeAurora MSM/QSD X driver working.
    that is complicated, I tried for the htcdream and succedded but it was an old version.
    source can be find here:
    http://cgit.openembedded.org/cgit.cgi/openembedded/tree/recipes/xorg-driver/xf86-video-msm_git.bb
    >-Find decent method to input text.
    under the SHR distribution(http://www.shr-project.org/trac ) we have software keyboard. so…
    * or we have portrait and the keyboard is ultra-small
    * or we use landscape and the keyboard uses all the screen
    >-Look into using the GSM radio.
    I’ve tested it, under android with the free software reference ril that comes with full source code it works, with fso it doesn’t(but it can detect that the sim card is lacking so it somewhat works)
    >-Audio
    the biggest problem, altough I’ve a workarround for mplayer:
    ao=pcm:file=/dev/msm_pcm_out,
    >-Figure out how to configure adbd.
    not necessary with usbnet(need some small include patch)

    we have our status here:
    http://wiki.freesmartphone.org/index.php/HardwareComparison
    I need a better place for a more detailed status.
    maybe htc-linux wiki

    btw, I hang on freenode as GNUtoo|laptop(#htc-linux,#openmoko-cdevel etc…) maybe we should talk.

    personally without an alsa driver I don’t think it’s worth porting SHR on it.

  16. Hi,

    I tried it on a HTC Dream but with the kernel modified to this phone (trout). But i have a problem triying command fastboot. It loads kernel but when phone restart at splash image (next step will be load debian), it stucks. Dont work my zImage.

    I know its a problem with my .config, because i downloaded this zImage from internet (GALOULA version) and it works with same “fastboot command”.

    Could you help me to find the problem?

    Thank you for this post! its very fine!

  17. How did you debug this? Is there a way to get see the kernel messages during boot?

  18. Jorge, it’s hard to say without seeing where and why it’s failing. One common issue that you should double check is making sure your file system drivers are present. Odds are if you are using a stock .config for an android phone it doesn’t have ext built in.

    Anon, I used a usb to serial adapter breakout board from sparkfun to build a serial cable to watch the N1 boot. The N1 can output TTL serial on the D+/D- pins of the USB connector.

*