1Android emulator upstream integration madness 2============================================= 3 4After more than 2 years of inactivity, the Android emulator sources are 5being refactored to match the level of a much more recent upstream QEMU. 6 7The main goal for this work is to get to reuse Intel, ARM and MIPS 64-bit 8emulation support, as well as to clean up some of the cruft accumulated over 9the years. 10 11A secondary goal is to make it drastically easier to send patches to QEMU 12upstream to support Android use cases, when that makes sense, and if they 13are interested. 14 15 16I. Branches: 17------------ 18 19All work happens in the open on the public AOSP source/gerrit servers, but 20two 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@android.com first (we can help rebasing your 47 patches on top of the next batch before they happen). 48 49See section III. to see how to checkout and submit to the idea133 branch. 50 51Explicit (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 59For reference, the master branch is currently targetting the upstream QEMU 60commit with the following SHA-1: 61 62 47acdd63a33a5966bf4fc94a6ac835d72a70c555 63 64Which may be updated later to integrate more upstream fixes. 65 66 67II. Scope: 68---------- 69 70The priority is to get the following components to the level of upstream 71as soon as possible: 72 73 - tcg 74 - cpu emulation 75 - softmmu 76 - kvm / haxm 77 - virtual devices (goldfish and others). 78 79Other components like block/, net/, ui/, audio/ have lower priority. 80Some upstream components like qmp, tracing or migration will not be used. 81In case of doubt, contact tools@android.com. 82 83The content of android/ will also be refactored to make it more testable and 84less dependant on the QEMU parts of the code, whenever possible. It is expected 85that some of this code will be rewritten in C++ too. This is lower priority and 86will probably happen in the idea133 branch, instead of the master one. 87 88 89III. Checking it out and sending patches to idea133: 90---------------------------------------------------- 91 92If you plan to work on general emulator fixes, without other parts of the 93platform, 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 99In that case, "repo upload" will send your patches directly from the right 100branch when you upload them to gerrit. 101 102 103If you already have a 'master' checkout of AOSP, you can still work on individual 104changes for the branch, but do _not_ use repo to upload them, instead do 105something 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 119This will upload the patch to gerrit to the right branch. 120 121Be careful that a "repo sync" will erase all custom branches that are not 122tracking master. If this happens use "git reflog" to get your past state 123(but not your branches). 124