| David 'Digit' Turner | 7fd10ad | 2014-01-30 23:32:39 +0100 | [diff] [blame] | 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 | *************************************************************************** |