1Introduction: 2------------- 3 4This document provides important information about the Android 5emulator codebase, which will be useful for anyone planning to 6contribute patches to it. 7 8 **** IMPORTANT NOTE ******************************************************* 9 THE ANDROID EMULATOR SOURCES ARE CURRENTLY HEAVILY BEING REFACTORED, IF YOU 10 PLAN TO SUBMIT CONTRIBUTIONS, PLEASE READ docs/REFACTORING-MADNESS.TXT FOR 11 DETAILS ON HOW TO AVOID BREAKAGES. 12 *************************************************************************** 13 14 15I. Building from sources: 16------------------------- 17 18This is covered in docs/BUILDING.TXT 19 20 21II. Overall source layout: 22-------------------------- 23 24The Android emulator sources contains many, heavily-modified, sources from the 25upstream QEMU project (http://www.qemu.org). It adds the following directories: 26 27 android/ 28 Android-specific code, used to implement a UI and functional layer on 29 top of the QEMU code base. Ideally, anything that shouldn't impact the 30 QEMU internals should be here. 31 32 include/hw/android/goldfish/ 33 Headers for the Android-specific goldfish virtual devices. 34 See docs/GOLDFISH-VIRTUAL-PLATFORM.TXT for more details. 35 36 hw/android/goldfish/ 37 Implementation files for the Android-specific goldfish virtual devices. 38 39 hw/android/ 40 Implementation files for the Android-specific virtual ARM and MIPS 41 boards. For x86, the content of hw/i386/pc.c was modified instead. 42 43 distrib/ 44 Contains various third-party libraries the emulator depends on 45 (e.g. zlib, libpng, libSDL). 46 47 elff/ 48 Generic ELF processing library, used by memcheck/ implementation. 49 Also used by the "ndk-stack" Android NDK tool. Should probably move 50 to distrib/ or android/ though. 51 52 memcheck/ 53 Implementation files related to the Valgrind-like memory checking mode 54 triggered by the -memcheck option (see -help-memcheck). Should move 55 to android/ 56 57 slirp-android/ 58 Modified version of the slirp/ directory, which adds various Android-specific 59 features and modifications. 60 61 telephony/ 62 GSM modem emulation code. Implemented as a QEMU CharDevice (probably 63 needs to be refactored then move to android/). 64 65 proxy/ 66 A transparent HTTP rewriting proxy used to implement the -http-proxy option. 67 (need refactor + move to android/) 68 69Generally speaking, some QEMU source files have been rewritten in so signficant 70ways that they gained an -android prefix (e.g. vl-android.c versus vl.c). The 71original file is typically kept as a reference to make it easier to see 72modifications and eventually integrate upstream changes. 73 74Only a fraction of the QEMU sources are actually part of the Android emulator 75sources, and this is intentional. It makes maintaining them easier, especially 76when trying to compare with the state of upstream QEMU. 77 78 79III. Testing: 80------------- 81 82There is currently very limited automated testing for the Android emulator, 83in the form of the "android_unittests" and "android64_unittests" programs, 84which, when invoked, will run a series of GoogleTest-based unit tests that 85only check internal features of the Android-specific code. 86 87There is work to significantly increase the coverage of these unit tests, as 88well as plans for automated function testing. However, for now manual testing of 89the emulator binaries with existing SDK system images remains necessary. 90 91 92III. Integrating upstream QEMU changes: 93--------------------------------------- 94 95It is sometimes useful to integrate changes from upstream QEMU into the Android 96emulator code (e.g. to gain new features, like the ability to emulate new CPUs, 97or fix some bugs). 98 99Doing this is a delicate affair, but workable when using directory comparison 100tools (e.g. meld), and a lot of patience. It is strongly recommended to read 101both Android emulator and QEMU documentation before trying to do so though. 102 103Do not try to integrate QEMU features that are not directly useful to the 104Android emulator. It's generally preferable to write stubs. The Android emulator 105does not use many QEMU features, like user-mode-emulation, the QEMU monitor, 106the QMP protocol, tracing, and many many more. 107 108 109 **** IMPORTANT NOTE ******************************************************* 110 THE ANDROID EMULATOR SOURCES ARE CURRENTLY HEAVILY BEING REFACTORED, IF YOU 111 PLAN TO SUBMIT CONTRIBUTIONS, PLEASE READ docs/REFACTORING-MADNESS.TXT FOR 112 DETAILS ON HOW TO AVOID BREAKAGES. 113 *************************************************************************** 114