1 Introduction: 2 ------------- 3 4 This document provides important information about the Android 5 emulator codebase, which will be useful for anyone planning to 6 contribute 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 15 I. Building from sources: 16 ------------------------- 17 18 This is covered in docs/BUILDING.TXT 19 20 21 II. Overall source layout: 22 -------------------------- 23 24 The Android emulator sources contains many, heavily-modified, sources from the 25 upstream 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 69 Generally speaking, some QEMU source files have been rewritten in so signficant 70 ways that they gained an -android prefix (e.g. vl-android.c versus vl.c). The 71 original file is typically kept as a reference to make it easier to see 72 modifications and eventually integrate upstream changes. 73 74 Only a fraction of the QEMU sources are actually part of the Android emulator 75 sources, and this is intentional. It makes maintaining them easier, especially 76 when trying to compare with the state of upstream QEMU. 77 78 79 III. Testing: 80 ------------- 81 82 There is currently very limited automated testing for the Android emulator, 83 in the form of the "android_unittests" and "android64_unittests" programs, 84 which, when invoked, will run a series of GoogleTest-based unit tests that 85 only check internal features of the Android-specific code. 86 87 There is work to significantly increase the coverage of these unit tests, as 88 well as plans for automated function testing. However, for now manual testing of 89 the emulator binaries with existing SDK system images remains necessary. 90 91 92 III. Integrating upstream QEMU changes: 93 --------------------------------------- 94 95 It is sometimes useful to integrate changes from upstream QEMU into the Android 96 emulator code (e.g. to gain new features, like the ability to emulate new CPUs, 97 or fix some bugs). 98 99 Doing this is a delicate affair, but workable when using directory comparison 100 tools (e.g. meld), and a lot of patience. It is strongly recommended to read 101 both Android emulator and QEMU documentation before trying to do so though. 102 103 Do not try to integrate QEMU features that are not directly useful to the 104 Android emulator. It's generally preferable to write stubs. The Android emulator 105 does not use many QEMU features, like user-mode-emulation, the QEMU monitor, 106 the 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
