[ms2-kexec] / README

Android kexec port
By Matthew Veety, et al.

Contents:
	Synopsis
	Cross-compiling on Gentoo and other Linuxes How-to
	Troubleshooting

================================================================================

Synopsis:

This is the kmod from the project trying to unlock the Milestone. It is still
localized to that phone, but, with modification, I got working on the Droid X
and a few others. Currently, this is a work in progress and is not recommended
for mission critical situations.

To compile:
Place your kernel sources into kernel/ and build the kernel
in that directory. Then run make (or gmake on freebsd) to build
the kernel module. I highly recommend actually doing the build on
the phone you desire to run the kmod on. I use a gentoo stage3
chroot environment on my Droid X to do the building.

Targets:
Droid X

In-progress Targets:
Droid 2
Nexus S

Future Targets:
Droid 2 Global
Droid Bionic

================================================================================

Cross-compiling on Gentoo and other Linuxes How-to:

    To set this up you need a cross-compiler. A cross-compiler allows your to 
make binaries for something other than your platform. If you've ever built Android 
then you've used one. There are two methods to do this; the first method is using
Android's cross-compiler to build. There are tools to set this up and it seems 
to be very easy to use, but I've never got that method to work. The method I use 
uses a nice tool that is in portage (I'm a gentoo user) called cross dev.

	~note from palmercurling~
	To set up a cross-compiler in Debian or a Debian fork (Ubuntu, Mint, others)
	follow the steps at http://www.scratchbox.org/

Your first step should be setting up a stage3 chroot. The Gentoo handbook outlines
how to do this, and the process is pretty simple. It only needs to be very 
minimal and doesn't need X or any other sort of graphical environment. 
I install mine to /opt because I have a nice 300 GB hard drive mounted there to 
hold all of my Android things. 

So after you're chrooted into your cross environment install crossdev by running:
# emerge -avp crossdev      # This is to see dependencies
# emerge -av crossdev        # This makes sure you want to go through with it

After crossdev gets done emerging run:
# emerge --sync
to get the latest version of the portage tree. If rsync is blocked choose the http
method outlined in the Gentoo Handbook.

crossdev has pretty simple options that can be seen by invoking:
$ crossdev
or
# crossdev

The option you'll be interested in is --target. This allows your to build the specified
gcc, libc, and binutils. --target takes its option as ARCH-VENDOR-OS-LIBC. For
possible choices invoke:
$ crossdev -t help
$ crossdev --target help
# crossdev -t help
or
# crossdev --target help

Now because Adnroid is Linux and initx requires glibc your tuple for --target
will look something like ARCH-VENDOR-linux-glibc. Also because Android
kexec only supports ARM right now you're going to want either arm or armeb
for ARCH. That is phone dependent. The Droid X seems to run fine with either,
but the Nexus One really doesn't like using arm without compiling the kernel with
softfloat in the vendor.

TIPS: This doesn't work on Gentoo/FreeBSD yet. No idea why either. Cross
works fine on normal *BSD though. Crossdev is also crazy useful for 
compiling Windows apps. crossdev + wine = windows development bliss.

================================================================================

TROUBLESHOOTING:

1. I'm getting segmentation faults!
    Check your cross setup. The common cause for me is adding in softfloat when I
    didn't need it. Don't feel bad, it's a common issue.
2. kexec won't load into the kernel!
    The cross setup needs to be the same configuration as the one that compiles your
    kernel. Check your CHOST after running make menuconfig in your kernel. 
3. I'm getting errors on compile!
    Read them and fix them, if it's my fault send me a fix for it.
4. How do I actually use this?
     You'll need to write a wrapper to make the system call. I did that so inexperienced
     users won't damage their phone. kexec is pretty well documented, and you can look
     at the i686 sources for a really well done reference, plus the man pages have it pretty
     well documented.
5. This file looks funny in my emacs window!
   I know, I didn't format it to 80 cols just to be a dick to you :P. Actually, I use
   TextEdit.app (it's a GNUstep app because I'm a GNUstep user) which doesn't easily
   understand the concepts of "wrap the damn line at 80."
Commit	Line	Data
4e93cb00 MG	1	Android kexec port
	2	By Matthew Veety, et al.
	3
	4	Contents:
	5	Synopsis
	6	Cross-compiling on Gentoo and other Linuxes How-to
	7	Troubleshooting
	8
	9	================================================================================
	10
	11	Synopsis:
	12
	13	This is the kmod from the project trying to unlock the Milestone. It is still
	14	localized to that phone, but, with modification, I got working on the Droid X
	15	and a few others. Currently, this is a work in progress and is not recommended
	16	for mission critical situations.
	17
	18	To compile:
	19	Place your kernel sources into kernel/ and build the kernel
	20	in that directory. Then run make (or gmake on freebsd) to build
	21	the kernel module. I highly recommend actually doing the build on
	22	the phone you desire to run the kmod on. I use a gentoo stage3
	23	chroot environment on my Droid X to do the building.
	24
	25	Targets:
	26	Droid X
	27
	28	In-progress Targets:
	29	Droid 2
	30	Nexus S
	31
	32	Future Targets:
	33	Droid 2 Global
	34	Droid Bionic
	35
	36	================================================================================
	37
	38	Cross-compiling on Gentoo and other Linuxes How-to:
	39
	40	To set this up you need a cross-compiler. A cross-compiler allows your to
	41	make binaries for something other than your platform. If you've ever built Android
	42	then you've used one. There are two methods to do this; the first method is using
	43	Android's cross-compiler to build. There are tools to set this up and it seems
	44	to be very easy to use, but I've never got that method to work. The method I use
	45	uses a nice tool that is in portage (I'm a gentoo user) called cross dev.
	46
	47	~note from palmercurling~
	48	To set up a cross-compiler in Debian or a Debian fork (Ubuntu, Mint, others)
	49	follow the steps at http://www.scratchbox.org/
	50
	51	Your first step should be setting up a stage3 chroot. The Gentoo handbook outlines
	52	how to do this, and the process is pretty simple. It only needs to be very
	53	minimal and doesn't need X or any other sort of graphical environment.
	54	I install mine to /opt because I have a nice 300 GB hard drive mounted there to
	55	hold all of my Android things.
	56
	57	So after you're chrooted into your cross environment install crossdev by running:
	58	# emerge -avp crossdev # This is to see dependencies
	59	# emerge -av crossdev # This makes sure you want to go through with it
	60
	61	After crossdev gets done emerging run:
	62	# emerge --sync
	63	to get the latest version of the portage tree. If rsync is blocked choose the http
	64	method outlined in the Gentoo Handbook.
65
66	crossdev has pretty simple options that can be seen by invoking:
67	$ crossdev
68	or
69	# crossdev
70
71	The option you'll be interested in is --target. This allows your to build the specified
72	gcc, libc, and binutils. --target takes its option as ARCH-VENDOR-OS-LIBC. For
73	possible choices invoke:
74	$ crossdev -t help
75	$ crossdev --target help
76	# crossdev -t help
77	or
78	# crossdev --target help
79
80	Now because Adnroid is Linux and initx requires glibc your tuple for --target
81	will look something like ARCH-VENDOR-linux-glibc. Also because Android
82	kexec only supports ARM right now you're going to want either arm or armeb
83	for ARCH. That is phone dependent. The Droid X seems to run fine with either,
84	but the Nexus One really doesn't like using arm without compiling the kernel with
85	softfloat in the vendor.
86
87	TIPS: This doesn't work on Gentoo/FreeBSD yet. No idea why either. Cross
88	works fine on normal *BSD though. Crossdev is also crazy useful for
89	compiling Windows apps. crossdev + wine = windows development bliss.
90
91	================================================================================
92
93	TROUBLESHOOTING:
94
95	1. I'm getting segmentation faults!
96	Check your cross setup. The common cause for me is adding in softfloat when I
97	didn't need it. Don't feel bad, it's a common issue.
98	2. kexec won't load into the kernel!
99	The cross setup needs to be the same configuration as the one that compiles your
100	kernel. Check your CHOST after running make menuconfig in your kernel.
101	3. I'm getting errors on compile!
102	Read them and fix them, if it's my fault send me a fix for it.
103	4. How do I actually use this?
104	You'll need to write a wrapper to make the system call. I did that so inexperienced
105	users won't damage their phone. kexec is pretty well documented, and you can look
106	at the i686 sources for a really well done reference, plus the man pages have it pretty
107	well documented.
108	5. This file looks funny in my emacs window!
109	I know, I didn't format it to 80 cols just to be a dick to you :P. Actually, I use
110	TextEdit.app (it's a GNUstep app because I'm a GNUstep user) which doesn't easily
111	understand the concepts of "wrap the damn line at 80."