[vbox-dev] Porting guest additions to Syllable

[Knut St. Osmundsen]

Hi,

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 
this interface.

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...

Kind Regards,
  knut

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.