[okl4-developer] HelloWorld Iguana server HowTo

[Remy Gottschalk]

Hi all

Here is the next howto. This one concerns how doing a helloworld iguana
server. It will be followed by an howto about using it from wombat. Again
feel free to comment, correct, ameliorate...

-------------------------
Iguana hello world server
-------------------------

We will create the simplest iguana server while using magpie's abilities
to generate code and interfaces.

 1 File structure
 ----------------

The files concerning our server will be located in two directories :
iguana/[Server Name]/	Contains server implementation
libs/[Server Name]/	Contains interface that clients have access to.

For our example the full structure is as following :

|--iguana (Server Side)
|    |--hello
|         |--SConscript
|         |--src
|             |--hello_server.c
|
|--libs   (Client side)
     |--hello
          |--SConscript
          |--include
          |    |--hello.h
          |    |--interface
          |           |--hello.idl4
          |--scr
               |--hello.c

 2 IDL4 interface
 ----------------

First we will write the IDL4 interface for our server. It defines the
functionalities the server will provide to the clients.
It will be located in libs/[Server Name]/include/interface/[Server Name].idl4

$ mkdir -r libs/hello/include/interfaces/
$ touch libs/hello/include/interface/hello.idl4

This file contains only one interface providing one function.

$ cat libs/hello/include/interface/hello.idl4
import "iguana/types.h";

[uuid(45)]
interface hello_
{
  void say_hello(void);
};

Note : It is possible to have, for a single server, several interfaces
each containing several functions.

This will allow magpie to generate, amongst other things, the server loop
hello_server_loop() and the hello__say_hello() functions.

 3 The server
 ------------

Now we will create the server according to the definitions made in the
IDL4 file. This code will be in iguana/[Server Name] and this folder will
contain :
A src directory for source files
A SConscript file to link with the compilation system

$ ls -R iguana/hello
iguana/hello:
SConscript  src

iguana/hello/src:
hello_server.c

This code define a main and the  hello__say_hello_impl functions. The
later implement the function say_hello from hello_ interface previously
declared.

$ cat iguana/hello/src/hello_server.c
#include <assert.h>
#include <stdio.h>

#include <interfaces/hello_serverdecls.h>

int  main(int argc, char **argv)
{
  printf("<===== Hello Server Started =====>\n");
  hello_server_loop();
  assert(!"Shouldn't reach here\n");
}

void	hello__say_hello_impl(CORBA_Object _caller, idl4_server_environment *
_env)
{
  printf("I say hello\n");
}

As we can see the main function call hello_server_loop() which is
generated by magpie using the IDL4 file and is found in
build/iguana/object/libs_hello/include/interfaces/hello_serverloop.c

We will add to this a SConscript file. We notice the definition of the
server's name (OKL4_HELLO_SERVER), his priority, and the list of depending
libraries.

$ cat iguana/hello/SConscript

Import("*")
weaver = env.WeaverIguanaProgramServer(server_name = "OKL4_HELLO_SERVER",
                                       priority=50)

obj = env.KengeProgram("ig_hello",
                       weaver = weaver,
                       extra_source =
args["idl_server_src"]['hello.idl4'],
                       LIBS=["c", "naming", "iguana", "l4", "l4e",
"mutex"])
Return("obj")


 4 The client side
 -----------------

In addition to the interface defined by the IDL4 file we will add a
wrapper which provide an abstraction layer for using the server. Headers
will be in libs/hello/include/ and sources in libs/hello/src/

$ cat libs/hello/include/hello.h
#ifndef __HELLO_H__
#define __HELLO_H__

void    hello_init(void);
void    say_hello(void);

#endif

$ cat libs/hello/src/hello.c

#include <iguana/env.h>
#include <iguana/memsection.h>
#include <iguana/thread.h>
#include <l4/thread.h>

#include <interfaces/hello_client.h>
#include <hello/hello.h>

static  L4_ThreadId_t server_tid;

void hello_init(void)
{
    thread_ref_t server_;

    memsection_lookup((objref_t)
env_memsection_base(iguana_getenv("OKL4_HELLO_SERVER")),
                      &server_);
    server_tid = thread_l4tid(server_);
}

void    say_hello(void)
{
  hello__say_hello(server_tid, NULL);
}

The main purpose of this layer is to mask the TID handling. The TID is the
server's thread identifier and is necessary to communicate with it. So
using the server will summarize with calling hello_init for TID
initialization and then say_hello for asking the server to print.

Lastly we need a SConscript for the client side :

$ cat libs/hello/SConscript
 Import("*")
(client_headers, client_src, server_headers, server_src) = env.KengeIDL()

lib = env.KengeLibrary("hello", LIBS=["c", "iguana", "l4e"],
                       extra_headers = client_headers,
                       extra_source = client_src)

Return("lib", "server_headers", "server_src")

 5 Global SConscript
 -------------------

To allow the compilation of our server we need to add it in the main
SConstruct file :

$ cat project/iguana/SConstruct
[...]
#################################
## Hello Servers
#################################
(hello_lib, hello_headers, hello_servers) = ig_env.Package("libs/hello")

iguana_hello = ig_env.Package("iguana/hello",
                               idl_server_headers = hello_headers,
idl_server_src = hello_servers)
apps += [iguana_hello]
[...]

This modification add to “apps” the server hello at  iguana/hello using
the library at libs/hello.

 6 First tests
 -------------

We can now test if the server compile and execute smoothly.

$ ./tools/build.py machine=ia32_pc99 project=iguana wombat=True
toolprefix=i686-unknown-linux-gnu-
[...]
$ qemu -nographic -hda build/image/c.img
[...]
<===== Hello Server Started =====>
[...]

 7 Generated files
 -----------------

The compile-time copied or generated files are :

$ find build -iname "*hello*"
build/iguana/lib/libhello.a
build/iguana/ig_hello
build/iguana/ig_hello/object/src/hello_server.o
build/iguana/object/libs_hello
build/iguana/object/libs_hello/src/hello.o
build/iguana/object/libs_hello/include/interfaces/hello_serverdecls.h
build/iguana/object/libs_hello/include/interfaces/hello_client.h
build/iguana/object/libs_hello/include/interfaces/hello_serverloop.c
build/iguana/include/hello
build/iguana/include/hello/hello.h
build/iguana/include/interfaces/hello_serverdecls.h
build/iguana/include/interfaces/hello_client.h
build/iguana/include/interfaces/hello_serverloop.c
build/iguana/include/interfaces/hello_serverloop.o
build/iguana/bin/ig_hello.linkaddress
build/iguana/bin/ig_hello

The most interesting are  :
- build/iguana/lib/libhello.a
    The client library for using the server
- build/iguana/object/libs_hello/include/interfaces/hello_serverloop.c
    Contain amongs others thing hello_server_loop()
- build/iguana/include/hello/hello.h
    Copy of libs/hello/include/hello.h
- build/iguana/bin/ig_hello
    Our server binary

 8 Using the server
 ------------------

In order to communate with our server using the defined interface a
program must :
- be linked with libhello.a
- include hello/hello.h
- initialize communication with hello_init()
Then, he can make the server print with say_hello()