1 Android emulator upstream integration madness 2 ============================================= 3 4 After more than 2 years of inactivity, the Android emulator sources are 5 being refactored to match the level of a much more recent upstream QEMU. 6 7 The main goal for this work is to get to reuse Intel, ARM and MIPS 64-bit 8 emulation support, as well as to clean up some of the cruft accumulated over 9 the years. 10 11 A secondary goal is to make it drastically easier to send patches to QEMU 12 upstream to support Android use cases, when that makes sense, and if they 13 are interested. 14 15 16 I. Branches: 17 ------------ 18 19 All work happens in the open on the public AOSP source/gerrit servers, but 20 two branches are being used: 21 22 idea133 23 This branch is currently used by the Android SDK tools team to 24 develop the next release of all SDK tools, emulator included. 25 26 If you have a general fix that is not related to the refactoring 27 work, this is where to send your contributions if you want them 28 to appear as soon as possible in the next public SDK tools release. 29 30 master 31 This branch is used to host a series of several hundred small patches 32 needed by the refactoring work. Each patch should try to do one simple 33 thing at a time. However, due to the extremely high coupling present in 34 the QEMU code base, even changing a couple header lines might impact 35 several dozen sources. 36 37 Each patch *must* result in a perfectly buildable emulator for all 38 supported host systems, and ideally not break anything when running it. 39 40 Because these patches are so numerous, they are typically uploaded to 41 the AOSP server as a batch of 20 or 50, through an explicit merge 42 commit. I.e. the batch will appear on Gerrit as a simple change, instead 43 of 20-50 individual ones. 44 45 We currently discourage you to submit to this branch on your own, unless 46 you've contacted tools (a] android.com first (we can help rebasing your 47 patches on top of the next batch before they happen). 48 49 See section III. to see how to checkout and submit to the idea133 branch. 50 51 Explicit (manual) merges will happen too: 52 53 - Merging aosp/idea133 into aosp/master will happen frequently, to ensure that 54 general fixes go into the refactored codebase. 55 56 - Merging aosp/master into aosp/idea133 will happen more rarely, and after 57 significant testing from the team to ensure that doesn't break anything. 58 59 For reference, the master branch is currently targetting the upstream QEMU 60 commit with the following SHA-1: 61 62 47acdd63a33a5966bf4fc94a6ac835d72a70c555 63 64 Which may be updated later to integrate more upstream fixes. 65 66 67 II. Scope: 68 ---------- 69 70 The priority is to get the following components to the level of upstream 71 as soon as possible: 72 73 - tcg 74 - cpu emulation 75 - softmmu 76 - kvm / haxm 77 - virtual devices (goldfish and others). 78 79 Other components like block/, net/, ui/, audio/ have lower priority. 80 Some upstream components like qmp, tracing or migration will not be used. 81 In case of doubt, contact tools (a] android.com. 82 83 The content of android/ will also be refactored to make it more testable and 84 less dependant on the QEMU parts of the code, whenever possible. It is expected 85 that some of this code will be rewritten in C++ too. This is lower priority and 86 will probably happen in the idea133 branch, instead of the master one. 87 88 89 III. Checking it out and sending patches to idea133: 90 ---------------------------------------------------- 91 92 If you plan to work on general emulator fixes, without other parts of the 93 platform, it is highly recommended to checkout the full branch with repo: 94 95 cd android-idea133 96 repo init -u https://android.googlesource.com/a/platform/manifest -b idea133 97 repo sync 98 99 In that case, "repo upload" will send your patches directly from the right 100 branch when you upload them to gerrit. 101 102 103 If you already have a 'master' checkout of AOSP, you can still work on individual 104 changes for the branch, but do _not_ use repo to upload them, instead do 105 something like: 106 107 cd external/qemu 108 git checkout -t -b my-fix aosp/idea133 109 110 ... edit files ... 111 mm # Verify that everything builds. 112 emulator_unittests # Run the unit tests. 113 emulator @my-test-avd # Verify manually that everything runs. 114 115 git add . 116 git commit 117 git push aosp +HEAD:refs/for/idea133 118 119 This will upload the patch to gerrit to the right branch. 120 121 Be careful that a "repo sync" will erase all custom branches that are not 122 tracking master. If this happens use "git reflog" to get your past state 123 (but not your branches). 124
