Genode Programming

Genode OS FrameworkProgramming Environment

Norman Feske<[email protected]>

Outline

1. Source tree overview

2. Build system

3. Run scripts

4. Inter-process communication

5. Client-server example

Genode OS Framework Programming Environment 2

Outline


2. Build system

3. Run scripts




Get the source code

Code is hosted at GitHub:

https://github.com/genodelabs/genode

Clone the main repository:

git clone https://github.com/genodelabs/genode.git

Contains genuine Genode code only3rd-party code not included, must be downloaded


Repositories

Foster modular code base instead of one big tree

For a given project, only a subset of repositories is relevant→ Helps to focus attention to relevant parts→ Clean organization defeats ad-hoc solutions


Repository shadowing

Set of used repositories defined by build directory→ Selected repositories form one logical source tree(similar to unionfs)

REPOSITORIES = <list-of-repo-directories>

Repositories can shadow each other

I target description filesI library description filesI include-search directories

Order is REPOSITORIES list is important

I Earlier entries shadow later entries


Repositories shadowing (II)


Repositories in practice

Tweak existing components without breaking existing code

Want to add code? → Simply introduce a new repository

I Can be hosted outside the mainline Genode treeI Use a revision control system of your choice


Specs

Source repositories → coarse grained modularity

Challenges:

Multiple kernelsMultiple hardware platformsDifferent flavours of implementationsifndef-endif yields frustration, messes up test coverage

Build specs → fine grained modularity


Specs: Build targets express their needs

Examples:

Specific peripheral (device driver)Particular property of CPU architecture if code is not generic

I only 32-bitI only arm v7a

Licensing conditions

Example, target.mk file

REQUIRES = x86

...


Specs: Build directory defines build properties

Spec values characterize the build

Example <build-dir>/etc/specs.conf

SPECS = genode foc_panda

High-level spec values refined to low-level spec values


Specs: Refinement


Specs: Steering the build process

Traverse <repos>/mk/spec-<value>.mk filesI Platform-specific build settings (CFLAGS ...)I Include more specialized spec-<value>.mk files

Match target’s REQUIRES against build-dir’s SPECS

Prefer specialized libraries:<repo>/lib/mk/blit.mk generic library<repo>/lib/mk/x86 32/blit.mk specialized library


Specs: Benefits

→ No preprocessor-based configuration→ No artificial abstractions (architecture, platform, cpu, ...)→ Easy to extend→ Easy to configure


Anatomy of a repository

Directory Description

doc/ Documentation, specific for the repository

etc/ Default configuration of the build process

include/ Globally visible header files

src/ Source codes and target build descriptions

lib/mk/ Library build descriptions


Repository relationships


Integration of 3rd-party source code

Download and integrate a kernel:

make -C <genode-dir>/base-nova prepare

Works uniformly for all kernels!


Integration of 3rd-party source code

Ported applications and libraries reside in libports and ports.List available 3rd-party libraries:

make -C libports

Download and integrate a set of libraries:

make -C libports prepare PKG=’libc freetype’

...a lot to explore


Outline


2. Build system

3. Run scripts




Tool chain

Needed because

C++ support libraries normally require a libcI We need C++ supportI We don’t want to depend on a libc

Multi-threading support is OS-specificI Linux TLS

Limit varienty of tool-chain related errorsI Compiler versionsI Linux distributions

→ http://genode.org/download/tool-chain


Build directory

<build-dir>/etc/build.conf

Defines base/ locationDefines source repositories to use

REPOSITORIES = <list-of-repo-dirs>

Make flags

MAKE += -j4


Build directory (II)

<build-dir>/etc/specs.conf

Included after <repos>/etc/specs.confDefine build characteristics via spec values

SPECS = genode foc_panda

Defaults in base-<platform>/etc/specs.confExtend spec values

SPECS += i915


Build directory (III)

<build-dir>/Makefilesymlink to<genode-dir>/tool/builddir/build.mk

Front end of the build system


Build directory creation tool

<genode-dir>/tool/create builddir

Creates templates for a variety of supported platforms:

create_builddir nova_x86_32 BUILD_DIR=/tmp/build

Revisit generated build.conf:

Enable repositoriesAdd make flags as desired


Building targets

Single target

make <rel-dir-to-target>

Example:

make drivers/atapi

Looks for target.mk within <repos>/src/drivers/atapiTests REQUIRES agains SPECS

Builds all libraries the target depends onBuilds target


Building targets (II)

Tree of targets

make <rel-dir>

Example:

make drivers

Builds all targets within <repos>/src/drivers.


Building targets (III)

List of targets

make <rel-dir> ...

Example:

make core init drivers/timer

Builds all targets found in any of the specific src/ locations


Outline


2. Build system

3. Run scripts




Typical work flow


Run script

build "core init test/printf"

create_boot_directory

install_config {

<config>

<parent-provides>

<service name="LOG"/>

</parent-provides>

<default-route>

<any-service> <parent/> </any-service>

</default-route>

<start name="test-printf">

<resource name="RAM" quantum="1M"/>

</start>

</config> }

build_boot_image "core init test-printf"

append qemu_args "-nographic -m 64"

run_genode_until {-1 = -1 = -1} 10


Run script (II)

Located at <repos>/run/<script-name>.runExecutable from within the build directory

make run/<script-name>


Run script (III)

→ Single file describes a complete system scenario

→ One run script works across different kernels

→ Great for bug reports

→ Run script + little work = automated test case


Outline


2. Build system

3. Run scripts




Remote procedure calls (RPC)


Remote procedure calls: Classes


Remote procedure calls: New RPC object


Remote procedure calls: Invocation


Shared memory


Asynchronous notifications


Asynchronous notifications (II)


Mechanisms combined

RPC + shared memory→ Synchronous bulk data (transaction)

Signalling + dataspace→ Asynchronous bulk data (streaming)


Synchronous bulk data transfer


Asynchronous bulk data transfer


Packet stream example


Outline


2. Build system

3. Run scripts




Scenario overview


Classes overview


Create a new repository

Designated content:

hello_tutorial

hello_tutorial/include

hello_tutorial/include/hello_session

hello_tutorial/src

hello_tutorial/src/hello

hello_tutorial/src/hello/server

hello_tutorial/src/hello/client


Server interface


Server interface

#include <session/session.h>

#include <base/rpc.h>

namespace Hello {

struct Session : public Genode::Session

{

static const char *service_name() { return "Hello"; }

virtual void say_hello() = 0;

virtual int add(int a, int b) = 0;

GENODE_RPC(Rpc_say_hello, void, say_hello);

GENODE_RPC(Rpc_add, int, add, int, int);

GENODE_RPC_INTERFACE(Rpc_say_hello, Rpc_add);

};

}


Server-side interface implementation


Server-side interface implementation

#include <base/printf.h>

#include <hello_session/hello_session.h>

#include <base/rpc_server.h>

namespace Hello {

struct Session_component : Genode::Rpc_object<Session>

{

void say_hello()

{

Genode::printf("I am here... Hello.\n");

}

int add(int a, int b) { return a + b; }

};

}


Server-side root interface


Server-side root interface

#include <root/component.h>

namespace Hello {

struct Root_component : Genode::Root_component<Session_component>

{

Session_component *_create_session(const char *args)

{

return new (md_alloc()) Session_component();

}

Root_component(Genode::Rpc_entrypoint *ep,

Genode::Allocator *allocator)

: Genode::Root_component<Session_component>(ep, allocator)

{ }

};

}


Server main program

#include <base/sleep.h>

#include <cap_session/connection.h>

int main(void)

{

using namespace Genode;

Cap_connection cap;

Sliced_heap md_alloc(env()->ram_session(), env()->rm_session());

enum { STACK_SIZE = 4096 };

Rpc_entrypoint ep(&cap, STACK_SIZE, "hello_ep");

Hello::Root_component hello_root(&ep, &md_alloc);

env()->parent()->announce(ep.manage(&hello_root));

sleep_forever();

return 0;

}


Server build description files

src/hello/server/target.mk

TARGET = hello_server

SRC_CC = main.cc

LIBS = cxx env server


Client main program


Client main program

#include <base/env.h>


#include <base/rpc_client.h>


int main(void)

{


Capability<Hello::Session>

hello(env()->parent()->session<Hello::Session>("ram_quota=4K"));

hello.call<Hello::Session::Rpc_say_hello>();

printf("sum = %d",

hello.call<Hello::Session::Rpc_add>(13, 14));

return 0;

}


Client-side convenience wrapper


Client-side convenience wrapper

#include <base/rpc_client.h>


namespace Hello {

struct Session_client : Genode::Rpc_client<Session>

{

Session_client(Genode::Capability<Session> cap)

: Genode::Rpc_client<Session>(cap) { }

void say_hello() { call<Rpc_say_hello>(); }

int add(int a, int b) { return call<Rpc_add>(a, b); }

};

}


Client-side connection object


Client-side connection object

#include <hello_session/client.h>

#include <base/connection.h>

namespace Hello {

struct Connection : Genode::Connection<Session>, Session_client

{

Connection()

:

Genode::Connection<Hello::Session>(session("ram_quota=4K")),

Session_client(cap())

{ }

};

}


Simplified client main program

#include <base/env.h>


#include <hello_session/connection.h>

int main(void)

{


Hello_connection hello;

hello.say_hello();

printf("sum = %d", hello.add(13, 14));

return 0;

}


Client build description file

src/hello/client/target.mk

TARGET = hello_client

SRC_CC = main.cc

LIBS = cxx env


Run script

build { core init hello }

create_boot_directory

install_config {

<config>

<parent-provides>

<service name="CAP"/> <service name="LOG"/>

</parent-provides>

<default-route>

<any-service> <parent/> <any-child/> </any-service>

</default-route>

<start name="hello_server">


<provides> <service name="Hello"/> </provides>

</start>

<start name="hello_client">


</start>

</config>}

build_boot_image { core init hello_client hello_server }

run_genode_until forever


Advanced features

Extending existing RPC interfaces

GENODE_RPC_INTERFACE_INHERIT(Base_interface_type,

Rpc_func ...)

Throwing exceptions accross process boundaries

GENODE_RPC_THROW(Rpc_unlink, void, unlink,

GENODE_TYPE_LIST(Permission_denied,

Invalid_name,

Lookup_failed),

Dir_handle, Name const &);


Observations

RPC stub code generated by C++ compiler

No external tools needed

No language boundary to conquer

Type safety


Thank you

What we covered todayProgramming environment

1. Source tree overview2. Build system3. Run scripts4. Inter-process communication5. Client-server example

Coming up next...Components

1. Classes of components2. Unified configuration

concept3. Session routing4. Components overview

More information and resources:http://genode.org


Genode Programming

Education

build processtraverse

genode foc

repositories list

subset of repositories

unionfs repositories

mainline genode treeuse

source tree overview2

party libraries