Low level primitives

This section would usually be called "kernel" section for traditional OSes. In Genode, the below live in user space, as most everything else, hence the need for another name.

1. Logging, tracing

In a nutshell

#include <log.h>
...
Genode::log( "Hello, world!" );

Basics

Includes:

• repos/base/include/base/log.h
• repos/base/include/base/printf.h
• repos/base/include/base/debug.h
• libc/libc_pdbg.h (for C code which cannot use the Genode:: namespace)

Methods in Genode namespace:

• log()
• warning()
• error()
• trace() (Genode 19.06+) (outputs to a buffer accessible as a VFS "file" -- see Genodians for details, especially the README link at the end)

Helpers:

• Genode::Hex(int) -> for logging a pretty hex value, e.g. : Genode::log( "Result: ", Genode::Hex(res) );

Also see macros like PLOG()/PDBG() from printf.h, for colored lines.

Forwarding stdout

Lots of printf()s in your code that you'd rather keep as-is ?

Don't fret -- it is possible to forward stdout lines (from printf() and friends) of a component, to the Genode LOG. Just edit said component's XML config like thus:

• setup a "vfs" xml node, and add children nodes to create a /dev/log FS.
• setup a "libc" xml node like thus: <libc stdout="/dev/log" stderr="/dev/log">

From then on, your component's printf() and fprintf(stderr, ...) strings will appear in the system log, as if they had been generated by calls to Genode::log(), i.e. in white color.

Misc

If for some reason you are in need of a more elaborate scheme (say, to use custom colors instead of white text color), some more legwork is needed. As an example, let's forward tracing in the ntfs-3g driver:

Create a C++/C bridge "forwarder" routine and include it in the build:

• create a _genode_tracing.cc file, beside the existing init.cc used by the ntfs driver
• add it to the makefile (fuse_fs/ntfs-3g/target.mk) beside the existing init.cc

We roll our own forwarding routine in _genode_tracing.cc (we cannot just use libc/libc_pdbg.h's genode_printf() function as that one does not take a "va_arg" structure parameter) :

extern "C" {
void hog_trace( const char * format, va_list args )
{
	Genode::vprintf( format, args );
...

Then tweak the ntfs logging code (logging.c) to use that routine:

-	ntfs_log.handler(function, file, line, level, data, format, args);
+	extern void hog_trace( const char * format, va_list args );
+	hog_trace( format, args );

2. Thread, synchronization, timing

Those are the "traditional" APIs: other OSes provide semaphores and the like, and Genode is no exception.

Threads

Include: repos/base/include/base/thread.h

Usage:

• subclass to implement entry()
• use e.g. this simple ctor: Thread(Env &env, Name const &name, size_t stack_size);
• thread.start()

Semaphores

Include: repos/base/include/semaphore.h

Example:

#include <semaphore.h>
...
Genode::Semaphore sem;
..
sem.down();
// do some critical stuff here
sem.up();

Caution: class Semaphore does not have "bitwise copy guards" (it does not make the default bitwise copy ctor and operator= inaccessible). So you have to remember not to put semaphores in e.g. an std::vector<> as that will misbehave without warning (the compiler will happily create faulty code without complaining about anything).

3. Heap memory

base/include/base/heap.h: Genode::Heap, Genode::Sliced_heap base/include/base/slab.h

4. Images/binaries

In addition to executables and shared libraries, it seems Genode provides 'plugins' that can be loaded/unloaded dynamically (similar to Haiku's add-ons) by the executable at run time.

See e.g. file_system_factory.cc, which loads an .so object (e.g. "vfs_fat_fs.lib.so") like an add-on in _load_factory(), then looks up a C symbol and jumps to it:

Genode::Shared_object *shared_object = new ...... (
	env.env(),
	env.alloc(),
	lib_name.string(),
	Genode::Shared_object::BIND_LAZY,
	Genode::Shared_object::DONT_KEEP)
Query_fn query_fn = shared_object->lookup<Query_fn>(_factory_symbol());
return *query_fn();

Also see dynamic_linker.cc for the well known functions:

• dlopen()
• dlsym()
• ..etc

5. Sessions, RPC

This is where we get Genode-specific, yum.

Sessions

Capabilities

RPC