blob: a10dcb8377fbcc7ba87ed6878deb9962f17d527c [file] [log] [blame]
I. Helper script:
We now provide a helper script to rebuild the kernel,
it is under $AOSP/prebuilts/qemu-kernel/
Make sure to use a checkout of aosp/master, not one of the aosp/studio-XXX
branches, the latter do not contain the prebuilt target toolchain binaries
required to rebuild the kernel.
You need the sources in,
in branch origin/android-goldfish-<version>, where <version> is the
kernel version that applies to your system image.
Roughly speaking:
2.6.27 -> Anything before Gingerbread. (<= Android 2.2)
2.6.29 -> For Gingerbread (2.3) until JellyBean MR2 (4.2.x)
3.4 -> For KitKat (4.4.x) and Lollipop 32 bit (5.0/5.1)
3.10 -> For Lollipop 64 bit and Marshmallow (6.0)
3.18 -> Currently experimental.
Besides, you need to select the right 'config', which corresponds to the
virtual board you want to support. There are currently two to consider:
- The legacy virtual board is called 'goldfish', and corresponds to
the virtual hardware supported by the legacy QEMU1 code base.
- The newest virtual board is called 'ranchu', and corresponds to the
virtual hardware supported by the QEMU2 code base.
The main difference between them is that 'goldfish' supports obsolete
goldfish-specific NAND and eMMC virtual devices that are replaced by
virtio-block in QEMU2 (for much better performance and reliability).
For more details, see docs/GOLDFISH-VIRTUAL-HARDWARE.TXT.
You specify which architecture to build for with the --arch=<name>
option, where <name> is one of the emulator's CPU architecture name
(e.g. 'arm', 'mips', 'x86', 'x86_64', 'arm64' and 'mips64').
Each architecture has a default configuration (typically 'goldfish') that
you can override with the --config=<name> option, where <name> is the name
of a sub-directory under $KERNEL/arch/*/configs/
The default output directory will be /tmp/kernel-qemu/<arch>-<kernel_version>/
but this can be overriden with the --out=<dir> option.
By default the script tries to find an appropriate toolchain from
$AOSP/prebuilts/gcc/, but you can specify a different one using the
--cross=<prefix> option.
See --help for more options and details.
Here's a table of options to rebuild popular kernel configuration:
32-bit ARMv7-A --arch=arm
32-bit i386 --arch=x86
32-bit MIPS --arch=mips
64-bit x86_64 --arch=x86_64
32-bit ARMv7-A --arch=arm --config=ranchu
32-bit i386 --arch=x86 --config=i386_ranchu
32-bit MIPS --arch=mips --config=ranchu
64-bit ARMv8 --arch=arm64
64-bit x86_64 --arch=x86_64 --config=x86_64_ranchu
64-bit MIPS --arch=mip64 --config=ranchu
The script will generate the following files in its output directory:
kernel-qemu The kernel image to be used with QEMU, use
the emulator's '-kernel <file>' option to use it,
where <file> is the path to this file.
vmlinux-qemu The symbol file used to debug the kernel with
GDB (see below).
LINUX_KERNEL_COPYING The kernel's license file, must be provided with
each copy of the binary.
README Small README file explaining how this was built.
II. Debugging the kernel with QEMU:
In the case where you need to debug the kernel (e.g. to inspect kernel panics)
you can do that by following this procedure:
1) Rebuild the kernel from sources (see previous section).
2) Start the emulator with special options to use the new kernel image,
start kernel debugging, and not start the vCPU to wait to GDB:
emulator -kernel /path/to/kernel-qemu \
<other-options> \
-qemu -s -S
3) In another terminal, start a GDB client that will attach to the emulator
process, after reading the kernel symbol file:
file /path/to/vmlinux-qemu
target remote :1234
b panic
NOTE: The version of gdb under $AOSP/prebuilts/ supports all Android target
architectures. Your 'host' gdb probably only supports x86/x86_64.
NOTE: You can place as many breakpoints as you want with the 'b' command before
starting execution with the 'c' command.
Once you reach the breakpoint, use 'bt' to print a stack trace. See the GDB
manual for more information.
III. Rebuilding from scratch:
If you don't or can't use the script, here are manual instructions:
You need to have an appropriate cross-toolchain in your path
(e.g. 'arm-eabi-gcc --version' must work)
then (for version 2.6.29):
git clone kernel-goldfish
cd kernel-goldfish
git checkout origin/android-goldfish-2.6.29
export CROSS_COMPILE=arm-eabi-
export ARCH=arm
export SUBARCH=arm
make goldfish_defconfig # configure the kernel
make -j2 # build it
=> this generates a file named arch/arm/boot/zImage
NOTE: Branch android-goldfish-2.6.27 is obsolete now. Do not use it.
Now, you can use it with:
emulator -kernel path/to/your/new/zImage <other-options>
You can build an ARMv7-compatible kernel image by using goldfish_armv7_defconfig
in the above instructions (instead of goldfish_defconfig). Note that you will
need to enable ARMv7 emulation by using the -cpu cortex-a8 option, as in:
emulator -kernel path/to/your/new/zImage <other-options> -qemu -cpu cortex-a8
As a special convenience, if the name of your kernel image ends in -armv7, then
the emulator binary will automatically enable ARMv7 emulation for you, so doing
the following should be equivalent
emulator -kernel path/to/your/kernel-armv7 <other-options>
Voila !