VirtualBox

Porting VirtualBox to a New Platform - *DRAFT*

VirtualBox is designed with portability in mind and portability issues are addressed as they are uncovered. That said, it still requires a fair amount of work to get most of the features up and going on a new platform. The effort needed varies a bit depending on how much the new platform differs from the ones VirtualBox already has been ported to. For instance, the Mac OS X differs from Linux/GNU and Windows in object format, linker/assembler, user/kernel address space layout, and naturally the kernel, which means a lot of work. On the other hand, take FreeBSD, the only major difference is the kernel, so porting VirtualBox to FreeBSD should be a picnic compared to Mac OS X.

Step 1 - The Core Prerequisites

These are:

Step 2 - Getting It Building

  1. Get ./configure running. I would recommend running ./configure with the --disable-xpcom switch unless you have all the xpcom related things it checks for. Before you try, you should just open ./configure in an editor and change the check_environment function to recognize your OS correctly. You might also want to drop certain checks (like the libuuid one), do that in a manner similar to Darwin (aka Mac OS X).
  2. Setup Config.kmk for your OS. This means finding the closes existing port and look for specific setting in Config.kmk for that platform. (Btw. take a look at the section called "Skip stuff", you might wish to do like l4, darwin or os2 there and skip parts that aren't ported yet.)
    TODO: More details here!
  3. Once the initial Config.kmk job has been done, try run kmk on a command line and start fixing build breaks. The first round of breaks will be in the BLDPROGS pass, the kBuild template for these is usually VBOXBLDPROG which is located near the end of ./Config.kmk.
  4. At some point you will get build breaks because of #errors in headers, these are often hints that something needs porting. Most of these are in the include/iprt/ directory and will probably happen while building src/VBox/Runtime. Runtime, aka IPRT, is a mix of OS abstractions (IO, memory, etc), compiler abstractions (return address, predictions, intrinsics, symbol export/import, etc), and some generic constructs (AVL trees, md5, compression, string manipulation, etc). Again take a look at the platform closes to yours, and see what's specific to it. Start with the Makefile, then look at the headers and the implementations.
  5. Having got the libraries in Runtime building, the next problem is going to be src/VBox/HostDrivers/Support. This is where the code for VBoxDrv.sys / vboxdrv.ko / VBoxDrv.kext currently resides. This early in the porting, we don't bother with the kernel mode/driver/extension/whatever-you-call-it nor the interface to it beyond the point that the ioctl values in SUPDRVIOC.h are valid. Create a subdirectory for the new platform and copy an existing SUPLib-xxxx.cpp file into it. Strip down this SUPLib-xxxx.cpp file so that it builds but simply fails for the parts that require kernel services.
  6. There are more points of failure down the road where looking at what the other platforms does should help sort it out. I'll compile a list as we get questions about the problems:
    • In etherboot, open Makefile.kmk and search for win.x86. Add your os.arch to that list if etherboot doesn't build.
    • In recompiler, temporarily disable it and get all the other bits building first. When you get back to it, consult any existing qemu port on the platform if you get into trouble.
    • ...

Step 3 - Make VBoxBFE Work

We heading towards the first major milestone now, which is to get something up running (though it'll be dead slow). However, a couple of things might be missing at this point so we'll have to play some tricks to get results:

  • Since there isn't yet any kernel driver, you have to set an environment variable to tell src/VBox/HostDrivers/Support/SUPLib.cpp to fake the kernel driver: 
    export VBOX_SUPLIB_FAKE=fake
  • If the platform has an unknown object/image format (COFF, AOUT and OMF are the only big ones we don't yet support) you'll have to edit src/VBox/PDMLdr.cpp to make sure PDMLDR_FAKE_MODE is #defined.

Btw. before moving on, you may also have to tell your dynamic linker where the dynamic libraries are located (they are where you are standing right now).

Now enter ./out/youros.yourarch/debug/bin/ (or .../release/bin depending on the BUILD_TYPE env.var.). It's now recommended to try run the testcases in ./testcase/ and perhaps some of the ./tst* programs too. You better ask on ​irc://irc.freenode.net/vbox-dev about the specific testcase failures until we put together an exception list. You might also get useful hints about

(we'll try compile a exception list here from the feedback). If you're the impatient sort, you can of course skip the testcases and debug problems when they bite you running VBoxBFE.

Show time (or more likely time to really start debugging it, thus the gdb): 

gdb --args ./VBoxBFE -m 4

Once you've seen the BIOS logo and the following BIOS boot error, you should download a simple Linux/GNU iso image like DSL (Damn Small Linux) and try it out: 

gdb --args ./VBoxBFE -m 128 -boot d -cdrom ./DSL.iso

For NAT networking, add -natdev1 080286000042 to the commandline.

The Next Steps

Since the basic stuff is building and running now, the remaining parts can be worked on in parallel if there happens to be more people interested in helping out. These parts are:

  • The kernel component.
  • The XPCOM API (Main). Once this is done, all the front ends (src/VBox/Frontends) with the exception of VBoxBFE can be work on in parallel.
  • Host device integration: DVD/CD-ROM, Floppy, TAP, ACPI, USB (internals only), etc.

The Kernel Component

Todo.

XPCOM

Todo.

Devices

Todo.

Last modified 17 years ago Last modified on Sep 10, 2007 3:35:48 PM
Note: See TracWiki for help on using the wiki.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette