[vbox-dev] Porting guest additions to Syllable
Knut St. Osmundsen
bird at innotek.de
Mon Jul 16 11:43:25 PDT 2007
this isn't quite my turf, but I'll try answer you as best as I can.
Turki Al-Marri wrote:
> Hi all,
> First, let me thank you for this great product and congratulate you on
> having Syllable 0.64, a new free open-source pure desktop system (no
> terminals), working on your VM without any problems or special
> configuration. Congratulations!
> Now my questions are:
> 1) Where can we find documentation about guest additions so that it
> could be ported to Syllable?
The documentation is mostly in form of header files and sources code I'm
afraid. I'll you a quick outline.
The additions talk to the host thru a special PCI device. You can find
the implementation of this device in src/VBox/Devices/VMMDev. This
device provides several interfaces or interface levels.
The most basic is a synchronous request interface and this is sufficient
for implementing the time synchronization daemon, absolute mouse
positioning and mouse cursor shapes. This is implemented using port I/O.
Then there is an event interface, where the device raises an interrupt
on certain events. This interface is used to implement asynchronous (or
blocking depending on point of view) requests, and to signal some other
changes. Shared folder, shared clipboard, and opengl all makes use of
There is one more interface which make use of a 4MB (or so) sized memory
buffer. I think this is used for speeding up graphics...
> 2) Will it be simple or a lot of work?
Depends, if your OS is similar to any of the OSes we currently support
(guest or host) it won't be that much work. In any case, there are quite
a bit of shared code (platform agnostic), so, you don't have to write it
all from scratch (unless you like to).
Of course some services are highly host specific (shared folders or
shared clipboard) and requires you to write quite a lot of new code,
while others are pretty generic (time sync) and you can practically
reuse the existing code unmodified.
> 3) And can it be done partially (eg. just shared folders)?
Yes, you can do it partially, service by service. The only thing you
must implement is the driver (/ kernel module / whatever you call it)
that talks to the PCI device (VMMDev).
> 4) How much does it integrate with the system? Is it a matter of
> drivers and daemons or is there more?
If you look at the Windows or OS/2 additions it looks something like this:
VBoxGuest - talks to the PCI device (VMMDev), exports interfaces that
can be used from user and kernel mode.
VBoxSF - shared folders IFS that implements the shared folders. This
talks the VM thru the kernel interface of VBoxGuest.
VBoxMouse - modified mouse driver that implements the absolute mouse
positioning. This is realized as a filter on Windows 2000 and later
IIRC, so there are two drivers in the winnt tree.
VBoxService - In the generic / OS/2 variant this primarily implements
the time sync. On windows this is actually implemented using a kernel
thread in VBoxGuest.sys. This also contains the shared clipboard code.
VBoxVideo/Display/VboxGradd/xx - vesa driver with hardware cursor,
acceleration, ++. All but the basic vesa bit is optional.
When porting the additions to a new OS, you only need to make
src/VBox/Runtime and the relevant src/VBox/Additions/ bits build.
So the first step is the runtime. Only parts of the runtime is really
required (at first). Check out the any of the _ONLY paths (like
VBOX_ADDITIONS_WIN32_ONLY), and see which targets gets built.
After making the runtime bits build writing the driver for the PCI
device is up next. I would suggest you start using the VBoxGuest driver
from the OS/2 additions as that is the more portable of the three
implementations. (Using this has advantages in that it's very similar to
the host driver, which might save time if you consider porting
VirtualBox to the OS later.) The OS/2 specific files are the one ending
with -os2.*, you have to implement something similar (look at
src/VBox/HostDrivers/Support/*/ for more similar code).
The VBoxGuest driver makes use of some common code found in
src/VBox/Additions/common/VBoxGuestLib. There are a couple of OS
specific bits here that you need to look at (SysHlp.cpp/h at least).
Once the driver is working, you can choose which of the services you
wish to implement next. I would try the timesync daemon from the OS/2
(src/VBox/Additions/os2/VBoxService) or Linux
(src/VBox/Additions/linux/daemon) additions since it won't require much
work. The VBoxService daemon makes use of some common driver interface
found in src/VBox/Additions/common/VBoxGuestLib/*R3*, but that's
relatively trivial ioctl code.
Hope some of this makes sense...
PS. I'm not quite sure if we've exported the relevant OS/2 additions
yet, if not I will see to that in a minute.
More information about the vbox-dev