wiki:Tutorial

Version 11 (modified by Martin Decky, 10 years ago) ( diff )

fix typo

What is HelenOS

​HelenOS is a portable general-purpose operating system designed and implemented from scratch. It is based on microkernel multiserver design principles. This means that the kernel of the system has relatively limited responsibilities (mostly just memory and resource management, scheduling of threads and facilitating communication between user space tasks) and most of the core system functionality is implemented in user space (including for example device and file system drivers). The core system functionality is decomposed into individual, isolated, intensively communicating and mostly simple user space tasks. This orthogonal decomposition of concerns follows the concepts of component-based software engineering. You can learn more about HelenOS in our FAQ.

The HelenOS project has been in constant development since 2005 (with earlier prototypes even predating its official inception), but the development team is rather small and its manpower is limited. Therefore HelenOS is still not a drop-in replacement for mature operating systems such as GNU/Linux. It simply lacks some end-user features of desktop operating systems. But it is an excellent research, experimenting and prototyping tool, also thanks to a well-documented and readable code. Over the years, many contributions to HelenOS were done by university students in the context of their bachelor/master theses or programs such as Google Summer of Code and ESA Summer of Code in Space. This also demonstrates the friendly learning curve of HelenOS.

As for the features, HelenOS currently supports 7 hardware architectures (in most cases on actual hardware, not just in emulators) from a single portable code base. HelenOS has support for SMP, textual and graphical user interface (a compositing window manager), multiple file system types (ext4, FAT, exFAT, ISO 9660, UDF, etc.), IPv4 and IPv6 networking (including drivers for several NICs), USB bus and USB devices, PATA and SATA disk drives, sound (including drivers for Sound Blaster 16 and Intel HD Audio) and more.

This is a brief step-by-step tutorial for running HelenOS in QEMU and experiencing some of its features. There is also a more comprehensive guide and an entire wiki with various user and developer resources.

How to Run HelenOS in QEMU

Assuming you have downloaded the x86-64 ISO image called HelenOS-0.6.0-rc3-amd64.iso, you can use the following ​QEMU command line to run it: 

qemu-system-x86_64 -device e1000,vlan=0 -net user -redir tcp:2223::2223 -redir tcp:8080::8080 -usb -device intel-hda -device hda-duplex -boot d -cdrom HelenOS-0.6.0-rc3-amd64.iso

If you know what you are doing, you can also extend the QEMU command with the following arguments:

  • -m <size>
    • You can configure more emulated physical memory for HelenOS to use.
  • --enable-kvm
    • If your host x86-64 machine has support for hardware virtualization, you can enable it and make HelenOS run faster.
  • -smp <count>
    • You can enable multiple virtual CPUs in QEMU. However, please note that without hardware virtualization, this will not speed up the execution of HelenOS in the emulator.
  • -hda <disk_image>
    • You can attach a disk image to QEMU and then access it from within HelenOS.
  • -usbdevice host:<bus>.<addr>
    • You can delegate a USB device connected to your host machine to HelenOS running in QEMU.

For more details (such as running different ports than x86-64 in QEMU or configuring bridged networking), please follow the user's guide.

The Boot Process

HelenOS for x86-64 uses the ​GRUB boot loader to boot the kernel and load a few initial user space tasks that are required to bring the system up. A RAM disk containing the root file system is also loaded by GRUB. During HelenOS bootstrap you can see some log entries, either from the kernel or from the user space tasks as they are started and initialized. After a while the user space GUI compositor should take over the screen and you should see three windows. At that time, there are more than 35 user space tasks already running in the system and providing its functionality.

The First Steps

The window titled vterm is a terminal where you can run commands via a command line. The terminal is running a bdsh (Brain Dead Shell, named so because of its simplicity). The vlaunch window demonstrates some other widgets of our GUI framework and it also allows you to run another instance of vterm. The untitled window in the right-bottom corner of the screen is a simple liveness indicator.

The GUI is rather simple, but it supports the common window manipulations using the mouse. You can move the windows around by dragging the window title, you can switch the focus by clicking on the windows, etc. But the GUI is more capable than just that. It uses a desktop compositor and therefore you can use the following hot-keys to manipulate the focused window in more fancy ways:

Key Action
Alt + Q, Alt + E Rotate window (clockwise, counter-clockwise)
Alt + C, Alt + V Window opacity (more transparent, more opaque)

Once you get bored by this, just run tetris from the terminal window. This should make you occupied for some time :)

The shell supports some basic commands you are likely familiar with: ls, cat, cd, pwd, cp, mv, rm, mkdir, echo, etc. If you get totally lost, just run the help command to give you some hints. You can use help commands to list the internal commands of the shell and help help to get more information on how the help system works. The shell provides commands history (Up and Down keys), tab completion and clipboard integration (Shift + Left and Shift + Right keys to select, Ctrl + C and Ctrl + V to copy and paste).

There is also a basiv support for different keyboard layouts. You can switch between three sample layouts using:

Key Layout
Ctrl + F1 US QWERTY
Ctrl + F2 US Dvorak
Ctrl + F3 Czech QWERTZ

Cool Stuff

This is a brief list of quick and interesting things to do in HelenOS. We assume you have used the suggested QEMU command line to run HelenOS, otherwise your mileage may vary. Simply run these commands in the terminal window:

  • ping 127.0.0.1
    • Ping the localhost.
  • ping 10.0.2.2
    • Ping the QEMU virtual gateway.
  • dnsres google.com
    • Try to resolve the IP address of google.com. You can use the arguments -4 and -6 to specifically ask for an IPv4 or IPv6 address.
  • websrv -p 8080
    • Start a web server on port 8080. You can then go to the URL ​http://localhost:8080 in your browser in your host system and see what happens.
  • wavplay demo.wav
    • Play a sample sound file.
  • modplay demo.xm
    • Play a sample XM module file. The pitch of some of the notes is not correct because the player does not implement all the FastTracker II effects yet.
  • edit demo.txt
    • Run a simple text editor to edit a sample UTF-8 text file. The entire HelenOS uses UTF-8 to store character strings and texts, although the terminal font does not support all Unicode glyphs.
  • loc
    • Display the location service entries (mostly hardware devices known to the system).
  • nic
    • List the network interface cards.
  • inet
    • Display the network configuration.
  • usbinfo --list
    • List the connected USB devices.
  • top
    • List currently running tasks, display CPU and memory utilization and other system statistics.
  • tetris
    • Play tetris.

If you are interested in the other commands, you can use our command reference page.

In addition to this, if the networking runs, you can also login to the running HelenOS system remotely from your host machine. In GNU/Linux, just run: 

telnet localhost 2223

Advanced: Development and Testing

Because of the ongoing development, HelenOS changes rapidly and needs to be tested and debugged. For the most fundamental debugging you can switch to the kernel console using the kcon command. Note that the kernel console brutally violates the microkernel design principles, but it was never meant to be a part of a production system. It is just a debugging tool. Also note that the user space is not aware of the kernel console and therefore the user space GUI output might sometimes overwrite the kernel output.

You can use the Page Up and Page Down keys to scroll back in the kernel console output. Some of the more commonly used commands of the kernel console are:

  • help
    • Print all kernel console commands.
  • continue
    • Leave the kernel console and enable the user space input/output again.
  • tasks
    • List the tasks running in the system.
  • ipc <taskid>
    • Print the information about the communication between the given task and other tasks.
  • threads
    • Print the threads running in the system.
  • physmem and zones
    • Display the physical memory map and usage.
  • slabs
    • Print the kernel virtual memory statistics.
  • test
    • Run kernel tests.
  • btrace <threadid>
    • Print a stack trace of the given thread.

There are also user space testing and debugging means. You can examine the following commands:

  • stats
    • List the running tasks.
  • trace
    • Trace the execution of a task. You can trace thread creation/termination, kernel syscalls and task communication (either on the level of basic messages or on the protocol level).
  • taskdump
    • Create a core dump of a task for later examination. A core dump can be also created automatically if a task crashes.
  • tester
    • Run tests that test various features of HelenOS.
  • redir
    • Redirect the standard/error output of a task to a file for later examination.

Advanced: File systems

HelenOS provides means to access other file systems than the root file system. To test this functionality in a completely safe way, you can create an empty disk image in your host system. For example in GNU/Linux: 

dd if=/dev/zero of=disk.img bs=4096 count=1024

Then run QEMU as usual, but add the -hda disk.img command line argument. Now you should be able to ask the location service in HelenOS for the block device name: 

/ # loc show-cat bd
bd:
        devices/\hw\pci0\00:01.0\ata-c1\d0 : devman
        devices/\hw\pci0\00:01.0\ata-c2\d0 : devman

The first device is your disk image attached to PATA primary master port (the second image is the PATA secondary master port with the live CD that was used to boot HelenOS from). The following listing shows how to create a FAT file system on the disk device, run the FAT file system driver, mount the file system, store a file on it and unmount the file system. If you then examine the disk image in your host system, you will see the file stored on the file system. 

/ # mkfat --type 12 devices/\hw\pci0\00:01.0\ata-c1\d0
Device: devices/\hw\pci0\00:01.0\ata-c1\d0
mkfat: Block device has 8192 blocks.
mkfat: Creating FAT12 filesystem on device devices/\hw\pci0\00:01.0\ata-c1\d0.
Writing allocation table 1.
Writing allocation table 2.
Writing root directory.
Success.
/ # mkdir /mnt
/ # fat
fat: HelenOS FAT file system server
fat: Accepting connections
/ # mount fat /mnt devices/\hw\pci0\00:01.0\ata-c1\d0
/ # cp demo.txt /mnt/
/ # umount /mnt

HelenOS supports more file system types than just FAT. Just remember to run the appropriate file system driver first. If your disk image contains an MBR or GUID partition table, use the mbr_part and g_part drivers to create individual partition device nodes to access.

You can also create a disk image in a file on the file system already mounted in HelenOS, create a loopback device from it and mount that image: 

/ # mkfile --size 102400 disk.img
/ # file_bd disk.img bd/loop0
file_bd: File-backed block device driver
file_bd: Accepting connections
/ # mkfat --type 12 bd/loop0
Device: bd/loop0
mkfat: Block device has 200 blocks.
mkfat: Creating FAT12 filesystem on device bd/loop0.
Writing allocation table 1.
Writing allocation table 2.
Writing root directory.
Success.
/ # mkdir /mnt
/ # fat
fat: HelenOS FAT file system server
fat: Accepting connections
/ # mount fat /mnt bd/loop0
/ # cp demo.txt /mnt/
/ # umount /mnt
Note: See TracWiki for help on using the wiki.