Step by step
$ make distclean config
This opens up the configuration menu. The configuration menu offers you to setup building as well as debugging options. You can navigate into the configuration menu using the arrow keys, space and enter to validate, backspace, 'q' to return/quit.
You will be given the opportunity to choose between EHCI and Serial devices to control/debug the virtualized OS.
You can decide to not control and/or debug at all by choosing none.
Notice that debugging information raised by the setup binary are always printed to screen.
Some EHCI controllers and BIOSes (on host side, the Ramooflax side) can be erratic at initialization.
Below are some options to force specific behaviors.
The EHCI_FULL option does a full controller re-init. Under certain circumstances, your keyboard will respond anymore under some buggy BIOSes.
The EHCI_2ND option forces Ramooflax to initialize the debug port found on the 2nd EHCI controller if possible. This situation has been encountered under HP Laptop where we were unable to properly setup the debug port of the 1st EHCI controller.
You can enable/disable debugging on a per subsystem basis. You can also disable any debugging information without loosing your precise configuration by clearing DEBUG_ACTIVE. Notice that some subsystems (ie emulation, etc ...) are very verbose and can slow down the boot process of the virtualized environment.
The layout of the filesystem may look like:
/media/usb/:
drwxr-xr-x 3 stf stf 1024 Sep 20 17:00 grub
-rw-r--r-- 1 stf stf 14234 Sep 20 17:00 loader.bin
-rw-r--r-- 1 stf stf 64264 Sep 20 17:00 setup.bin
-rw-r--r-- 1 stf stf 289416 Sep 20 17:00 vmm.bin
/media/usb/grub:
-rw-r--r-- 1 stf stf 102 Sep 20 17:00 menu.lst
-rw-r--r-- 1 stf stf 512 Sep 20 17:00 stage1
-rw-r--r-- 1 stf stf 108360 Sep 20 17:00 stage2
$ cat /media/usb/grub/menu.lst
default 0
timeout 0
title Ramooflax
root (hd0,0)
kernel /loader.bin
module /setup.bin
module /vmm.bin
We provide a disk creation tool, you will need GRUB (legacy) to use it:
sudo ./tools/create_disk.sh ramooflax.img 32M ../grub/ loader/build/loader.bin setup/build/setup.bin vmm/build/vmm.bin
[+] building disk image (32MB)
[+] create part on disk image
[+] formating disk
[+] mounting disk
[+] copy grub
[+] installing files
[+] configure grub
[+] install grub
[+] unmounting disk
Disk is ready !
- mnt it using : "mount -o loop,offset=512 ramooflax.img /mnt"
- run it using : "qemu -hda ramooflax.img"
This will build a 32MB disk image, bootable thanks to GRUB. You may modify it to add a Guest OS to boot after Ramooflax, whatever.
First be sure that a serial port is enabled into the BIOS of the Ramooflax virtualized machine.
When debugging using the serial port, Ramooflax sets it up as a raw 115200 serial interface.
We provide a tool to properly setup your client serial interface.
$ cd ramooflax/tools
$ gcc clean_tty.c -o /tmp/clean_tty
$ /tmp/clean_tty /dev/ttyS0
If you have a USB development board, compiles the DBGP_GADGET for your running kernel. You can compile this gadget in two fashions. One to only print messages, and one to expose a serial-like interface. The printing one will print the received messages into the standard kernel logging system, while the serial-like one will expose ttyGSxx.
Once done if you use the USB debug interface as a debugging one, you will only need to read information from the gadget exposed tty.
$ modprobe g_dbgp
$ socat - GOPEN:/dev/ttyGS0,echo=0
This will redirect every log messages received from Ramooflax into the USB debug port to the standard output of your development board terminal.
If you use the USB debug interface as a controlling one, you may not want to control Ramooflax directly from the development board but rather from your favorite workstation or laptop. You can so redirect the traffic coming from/to the g_dbgp exposed tty to a TCP socket listening for remote connections from you workstation.
$ modprobe g_dbgp
$ ./socat GOPEN:/dev/ttyGS0,echo=0,raw TCP-LISTEN:1234,reuseaddr
Consider creating a script calling socat in a loop to prevent connection failures after disconnect.
Now that your environment is ready, simply type:
$ make
This will build the following binaries:
loader/build/loader.bin
setup/build/setup.bin
vmm/build/vmm.bin
On the install configuration menu you can setup the directory where your USB key is mounted. This lets make automatically mount/copy/unmount the latest built binaries onto your device.
$ make install
When you startup the virtualized machine, try to not change its boot settings permanently. Hit the correct key to dynamically change boot order and choose the inserted USB key. This way when Ramooflax will ask the BIOS to start the already installed OS, the BIOS will still have its original configuration (1st HDD).
You can retrieve your serial logs on your client machine this way:
$ cat /dev/ttySO | tee ramooflax.logs
Once the TCP connection is opened on the development board, you can start the provided python client interface to Ramooflax on your workstation.
$ cd ramooflax/client/
$ sudo python setup.py install
$ python
>>> from ramooflax import VM, CPUFamily
>>> vm = VM(CPUFamily.Intel, "DEVBOARD_IP_ADDR:1234")
>>> vm.run(globals())
>>> vm.cpu.sr
cr0 = 0x000000008005003b
cr2 = 0x00000000b76231a0
cr3 = 0x0000000036b91000
[ ... ]
tr = 0x00000000c132df10
>>>> vm.detach()
disconnected from remote