Skip to content
This repository has been archived by the owner on Jan 28, 2023. It is now read-only.

Google Summer of Code 2019

Jump to bottom
Yu Ning edited this page Feb 26, 2019 · 4 revisions

We are trying to get HAXM admitted to Google Summer of Code as a mentoring organization for the first time. The idea was first proposed by our community, and since then we have received a lot of support. We have submitted our GSoC 2019 application, and will be notified of the result by the end of February. Meanwhile, if you are interested in participating as either a student or a mentor, do let us know! Please join the discussion at #153.

EDIT (2/26/2019): Unfortunately, HAXM did not make it into GSoC 2019. Nevertheless, we are very grateful for all the support we received from the community during the application process. All the following project ideas remain valid for anyone interested in contributing to HAXM.

Project Ideas

Develop a more useful haxm-check tool

haxm-check is a CLI tool included in every HAXM release for Windows (binary name haxm_check.exe) and macOS (binary name haxm-check). Its purpose is to check whether the host computer meets the system requirements for running HAXM (see below), and can be either integrated with the HAXM installer or run manually as a diagnostic tool. However, the current implementation only covers a few basic CPUID checks, which are not enough for today’s computers. For instance, on Windows, the tool may misleadingly report that the host CPU lacks support for Intel VT-x, when the real problem is that the user has not turned Hyper-V off.

The current tool is not open source, but since the code is trivial, it would be easier to start afresh. Your goal is to develop a new haxm-check tool that performs the following checks on the host:

  • Hardware
    • CPU vendor and model
    • Whether Intel VT-x is supported by CPU
    • Whether Intel VT-x is enabled in BIOS
    • Whether EPT is supported by CPU
  • Software
    • OS version and architecture
    • Whether Hyper-V is enabled (Windows only)

The new tool should be able to run on all Windows and macOS versions that HAXM supports. With a good design, it should be easily portable to other host OSes (e.g. Linux) as well.

  • Skills required: Proficiency in C, C++ or Golang.
  • Possible mentors: @raphaelning, @wcwang.
  • Difficulty level: Easy.

References:

  1. System requirements for running HAXM
  2. emulator-check tool (part of Android Emulator)
  3. System Information tool for Windows (msinfo32.exe)

Develop a new HAXM installer for Windows

The HAXM installer is a friendly GUI application that helps the user install HAXM on their computer. It was excluded from the HAXM open source release for various reasons, one of which is that it uses some proprietary components. As an open source project, HAXM should have an open source installer that everyone can help improve.

Your goal is to develop an open source replacement for HAXM’s Windows installer. Conceptually, it is quite simple: because HAXM is a non-PnP (software only) driver, its installation does not require an INF file, and only involves the creation of a kernel driver service, as has been demonstrated by the HaxmLoader tool (see below). However, a production quality installer needs to be robust and user friendly. It should:

  • Run pre-installation checks (existing installation, active HAXM guests, system requirements, etc.).
  • Install different driver binaries for different Windows versions.
  • In case of failure, tell the user what went wrong.
  • Support uninstallation.
  • Support silent (unattended) (un)installation.

Use of a Windows installer builder/framework might speed up development, but these tools usually come with a scripting language that you need to learn.

  • Skills required: Proficiency in C, C++ or Golang.
  • Skills preferred: Experience with at least one Windows installer framework (NSIS, WiX, msitools, etc.).
  • Possible mentors: @raphaelning, @wcwang.
  • Difficulty level: Medium.

References:

  1. Current HAXM installer for Windows
  2. HaxmLoader
  3. KMDF non-PnP driver sample
  4. NSIS
  5. WiX

Enable persistent HAXM driver logs on Windows

On Windows hosts, the HAXM driver uses DbgPrint() to log debug and error messages. These messages are not written to any file, and therefore are permanently lost unless the user takes explicit action to capture them at runtime (e.g. by launching DebugView or WinDbg in advance). This makes it inconvenient for an ordinary user to provide diagnostic information about driver issues, especially in case of a random bug that is hard to reproduce. At least, the critical error messages (including the driver panic dump) need to go into persistent storage for retrieval at a later time.

Your goal is to enhance or even revamp the logging interface used throughout HAXM, and enable persistence for critical errors (or even better, for any type of message) on Windows. One way to do that is to create a system event log entry for each HAXM log entry, which will appear in Event Viewer.

  • Skills required: Proficiency in C or C++; experience with Windows API.
  • Skills preferred: Experience with Windows driver development.
  • Possible mentors: @raphaelning.
  • Difficulty level: Medium.

References:

  1. Current HAXM logging helpers (Windows)
  2. Capturing HAXM driver logs
  3. DbgPrint
  4. Logging driver errors
  5. Event Tracing for Windows (ETW)

Add AMD SVM support

HAXM is designed as a cross-platform type-2 hypervisor by abstracting away functions specific to the host kernel. It powers several emulators, most notably Android Studio / QEMU, on Windows, MacOS, NetBSD and Linux hosts. To reach as many developers and researchers as possible, we would like to support non-VMX x86 virtualization extensions, particularly AMD SVM (aka. AMD-V).

Originally, only Intel VMX support was considered, which is reflected in VCPU management code at vcpu.c [1]. After learning about Intel VMX [2] and AMD SVM [3], your first goal will be (1) designing an interface that both backends should implement, e.g. [4], and (2) making vcpu.c extension-agnostic by consuming said interface. The Intel VMX backend could be easily implemented from the existing VMX-specific code in vcpu.c and cpu.c. The second goal, and the main challenge of this project, will be implementing the AMD SVM backend. In addition to your mentor's full support, you might also seek inspiration from other AMD SVM hypervisors [5], insofar as licenses allow that. In summary, in this project you will:

  • Learn about AMD SVM, and compare it to Intel VMX.
  • Design an interface to abstract away their differences.
  • Keep extension-agnostic code in vcpu.c, moving VMX-specific code to vmx.c.
  • Implement an AMD SVM backend in svm.c.

By using the existing platform-agnostic functions, this will make HAXM compatible with AMD CPUs on all supported host kernels. This means that developers will be able to create hardware-accelerated emulators using the same interface and still reach nearly everyone running an x86-based computer!

  • Skills required: Proficiency in C.
  • Skills preferred: Experience with x86 and hypervisors.
  • Possible mentors: @AlexAltea.
  • Difficulty level: Hard.

References:

  1. Current VCPU implementation in HAXM
  2. Documentation for Intel VMX: Intel SDM Vol. 3C, Chapters 23-33
  3. Documentation for AMD SVM: AMD64 APM Vol. 2, Chapter 15
  4. Interface for x86 virtualization shared by VMX/SVM in KVM
  5. SimpleSvm: Minimalistic educational AMD-V hypervisor for Windows

Develop mini-guest based hypervisor unit tests

There are already a small number of unit tests written for HAXM (under tests/). They are based on the renowned Google Test framework, and have been very helpful so far in testing code that does not use any privileged instructions (i.e. code that can be made to run in user mode, such as the x86 instruction emulator). However, since these tests do not even load the HAXM driver or launch any guest, they cannot cover the majority of the HAXM code, which only works in kernel mode.

Your goal is to develop a different kind of unit tests for HAXM, which are complementary to the existing ones. Conceptually, they are similar to kvm-unit-tests: each test contains a minimal guest operating system (which can be written in pure assembly), and runs it by calling the HAXM API directly, in order to verify a specific hypervisor behavior (e.g. whether a particular kind of VM exit is handled correctly). Unlike full-blown integration tests, which involve running a sophisticated guest in QEMU, these lightweight tests will allow us to catch bugs early and fix them quickly.

You can choose to adapt kvm-unit-tests for HAXM, in which case we may have to create a separate repository for the new code due to the license difference between the two projects. Or you can write the new unit tests from scratch and put them alongside the existing ones, ideally integrating them with Google Test. Either way, the new hypervisor tests should share a common framework which facilitates adding more tests. In addition, you can develop them on any host OS that HAXM can run on, but they must be easily portable to Windows.

  • Skills required: Proficiency in C/C++ and x86 assembly, experience with OS kernel development.
  • Skills preferred: Experience with hypervisor development, experience with a unit test framework.
  • Possible mentors: We will find you a mentor.
  • Difficulty level: Hard.

References:

  1. Current HAXM unit tests
  2. Google Test
  3. kvm-unit-tests
Clone this wiki locally