Developer Tips

On this page some random stuff is gathered that may be helpful to get started with working on this project.

Before anything else you should be able to compile QEMU from source. A good place to start is the QEMU wiki Getting Started for Developers page. Then you will need to get acquainted with the QEMU sources. There is no real good docs I know of but this summary of most important APIs might come in handy for reference. Otherwise looking at similar devices or boards and searching the sources with git grep (or your favourite content search facility) can turn up useful examples for specific problems.

When implementing new machine emulation it is useful to know the info qtree and info mtree QEMU monitor commands that show the device tree and memory map of the emulated machine. You can compare this to the real machine to identify what's missing or not emulated correctly. It can also help to uncomment the #define DEBUG_UNASSIGNED line in qemu/memory.c which will print accesses to adresses where no device is assigned which often shows if the guest is expecting something that is not emulated. (Beware that address offsets may be relative to some memory region e.g. for PCI devices so this may need some guessing to know which devices they belong.)

When working on unfinished emulation guest code will often not start or work correctly yet to give you useful info on what's happening so you have to observe QEMU to find out what is it doing and where is it failing. Always run QEMU with -d unimp,guest_errors option to print warnings for detected errors or unimplemented instructions. This can help to hint what may be missing but sometimes you have to go deeper and also add -d in_asm to print disassembly of executed guest code (which will generate a lot of output so best to redirect it to a file and know that normally Translated Blocks are only printed the first time they are encountered, next time they may be executed from TB cache without retranslating and thus appearing in in_asm output).

When debugging a specific device and need more info on what it does look for DEBUG defines (in case of older devices) or trace events (for newer devices) that you can enable. For trace events look in the trace-events file in the subdirectory where the code is. To enable specific traces: either put patterns in a file and use -trace events=filename or use -trace enable=pattern (e.g. -trace enable="pci*") or you can even enable trace events at runtime with the trace-event monitor command.