Documentation/GettingStartedDevelopers

You want to contribute code, documentation or patches to QEMU?

Then...

• ... you should probably first join the mailing list.

Wiki

• Create yourselves an account in the QEMU wiki.
• Start with reading the QEMU wiki.
• Contribute to the QEMU wiki by adding new topics or improving and expanding existing topics. It should help you and others in the future.

Documentation

• Continue with reading the existing documentation and Contributions Guide.

Be prepared that all written documentation might be invalid - either because it is too old or because it was never correct. And it is never complete...

• If you find bugs in the documentation then fix them and send patches to the mailing list. See Contribute/ReportABug.
• If you find problems in the wiki, then fix them if you can, or add notes to either the applicable page or the Discussion page.

Code

• Get the code. If you want to be a developer, you almost certainly want to be building from git (see http://wiki.qemu.org/Download#Latest for the right tree)
• Run the QEMU system and user mode emulation for different targets (x86, mips, powerpc, ...). Images can be obtained from http://wiki.qemu.org/Download#QEMU_disk_images
• QEMU has a lot of different parts (hardware device emulation, target emulation, code generation for different hosts, configuration, ...).
  • Choose an interesting part and concentrate on it for some time and read the code. Its going to take some effort, so try to find something that you are really interested in - something that will be a least a little bit fun for you.
  • It will be easier if you choose a part of the code that has an active / responsive maintainer (since this gives you someone to discuss things with).
• If you find bugs in the code, then fix them and send a patch to the mailing list (http://wiki.qemu.org/Contribute/SubmitAPatch)
  • Patches need to go the mailing list, and possibly also to a specific maintainer (read the MAINTAINERS text file in the top of the source code tree).
  • Read the HACKING and CODING_STYLE text files (in the top of the source code tree) before writing the patch
  • Run your patch through the "checkstyle.pl" script (found in the directory imaginatively called "scripts"). See http://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html for how to hook it into git.
  • For very small, simple changes, you can do it as a single patch. If your change is more complex, you need to break it into smaller, separate patches (which together form a set of patches, or a patchset). Each step in the patch process can rely on previous patches, but not later patches - otherwise "git bisect" will break. This will require more effort on your part, but it saves a lot of work for everyone else.
  • If you have a lot of patches in a patchset (say five or more), then it may help to have a public git tree. You can get hosting from many places (repo.or.cz and github seem popular).

Getting to know the code

• QEMU does not have a high level design description document - only the source code tells the full story.
• There are some useful (although usually dated) descriptions for infrastructure code in various parts of the wiki, and sometimes in mailing list descriptions:
  • Tracing framework is described at http://wiki.qemu.org/Features/Tracing and in docs/tracing.txt in the source tree.
  • Some of the internal functionality (and a bit of the human monitoring / control interface) is implemented in QAPI and QMP (or will be migrated to it): http://wiki.qemu.org/Features/QAPI and http://wiki.qemu.org/QMP, plus http://www.linux-kvm.org/wiki/images/1/17/2010-forum-qmp-status-talk.pp.pdf
  • Related to the QMP changes are some proposed changes for configuration options known as QCFG: http://wiki.qemu.org/Features/QCFG
  • If you're into devices (new virtual hardware) it will help to know about QDEV: http://www.linux-kvm.org/wiki/images/f/fe/2010-forum-armbru-qdev.pdf and docs/qdev-device-use.txt in the source tree
• QEMU converts instructions in the guest system into instructions on the host system via Tiny Code Generator (TCG). See tcg/README in the source tree as a a starting point if you want to understand this.

Bugs

• Read the Bug Tracker.
• Check for topics in it for which you feel capable of handling and try to fix the issue. Send patches.

Testing your changes

• You must compile test for all targets (i.e. don't restrict the target-list at configure time). Make sure its a clean build if you are not sure.
• Think about what you've changed (review the patches) and do testing consistent with those changes. For example:
  • If you've developed a new driver (say an AHCI virtual device - used for SATA disks), make sure that it works. Make sure anything related still works (e.g. for AHCI, check the IDE driver, and no disk configurations). If your new device supports migration, make sure migration and snapshots work.
  • If you're working on Xen Hardware Virtual Machine (HVM - full virtualization), then make sure that Xen para-virtualization works.
• Its OK if your new implementation doesn't do everything (or has some deficiencies / bugs). You do need to declare that in the patch submission though.

Getting Help

• IRC might be useful. The #qemu channel is on irc://irc.oftc.net (note: no longer on Freenode).