L4Re simple client server example

In this tutorial we implement two applications: a simple client and server that send numbers between each other and print them. On our way we focus on the purpose of the involved L4Re objects and methods.

Please have a look at the complete source code, which can be found on github.com.

Overview

Our two tasks are called simple-client and simple-server. The simple-client sends a number to the simple-server, which prints the received number and sends the number multiplied by two back to the client, which then prints the received number.

To do this we have to go through different steps:

1. Argument marshalling: For sending data through an L4 channel (or: IPC gate) we use a specific memory area that is shared between the thread and the kernel: the User-Level Thread Control Block (UTCB). Arguments that shall be sent to another thread are put into the UTCB. This process is called marshalling.
2. Send data: we need to send the marshalled data to the server
3. Receiving data: the server needs to be ready to receive data on the channel used by the client
4. Argument unmarshalling: the server receives data into its UTCB and needs to read the number from it. This unmarshalling reverses the marshalling process.
5. Computation and reply: the server computes the doubled number and sends a reply to the client (using the UTCB).
6. Reply processing: The client receives the result and prints it again.

We will first go through each line in the main function of the client, which puts the number into the utcb, sends it to the server, receives the answer, and prints it.

Afterwards we look at the server's dispatch method, which prints the number and answers with the double of the number.

Finally we see the main function of the server, which prepares the server to be ready for receiving numbers.

ned.lua

L4Re applications are typically launched by Ned using an init-style script. These scripts are written in the Lua programming language.

Let's first look at the configuration file which sets up our example:

require("L4")

local ld = L4.default_loader
local channel = ld:new_channel()

ld:start({
            caps = {
               my_server_side = channel:svr()
            },
         }, "rom/simple-server")
ld:start({
            caps = {
               my_client_side = channel
            },
         }, "rom/simple-client")

• For this example we start two tasks, simple-server and simple-client. To achieve this, we call the start() method provided by the L4.default_loader object.
• In order to talk to each other, the applications need to be connected by a communication channel. In L4/Fiasco.OC this channel is represented by an IPC gate kernel object. Luckily, we don't need to know about the tiny details of the kernel interface. Instead, the L4 Lua package provides us a way of creating a channel and connecting the applications to it. This is done by calling ld:new_channel(), which provides us with a Lua channel object.
• To make the IPC gate accessible to the applications, the init script allows us to specify a set of capabilities that are passed to an application during startup.
  • Capabilities are references to kernel objects and are specified as a list of name = obj_ref pairs in a table named caps which can be passed to every call to ld:start(). Here, obj_ref is a reference to a kernel object, such as the channel we just created. name is the name that the application may at runtime use to obtain this reference.
  • For simple-client, we directly map the name my_client_side to the channel created previously.
  • For simple-server, we map my_server_side to channel:svr() which gives us the server-side end of the channel. The reason for this lies in the kernel interface, which only allows the server-side thread to attach to an IPC gate and receive messages from it, whereas other threads can only send messages through the channel.

client.cc

We now want to look at the straight forward client.

Cap<void> server = Env::env()->get_cap<void>("my_client_side");

We get the capability selector, which we declared for the simple-client in its caps table in the ned.lua file. Therefor we use the Env::env() object, the Initial Environment of this task given by Ned. With this object, we can access the caps table with get_cap. The returned Cap will be used to refer to the server, the receiver of this message.

Ipc::Iostream ios(l4_utcb());

The Ipc::Iostream ios handles the values in the UTCB and calls the kernel for sending these values and receiving other. It is basically a wrapper around the kernel calls and around the placement of values in the UTCB. In the constructor of ios we provide the UTCB in which the Iostream should write and read the values. With l4_utcb() we get the current UTCB of the running thread.

ios << n;

This writes the number into the UTCB at the current location as managed by ios. The current location here is the first and it is moved after writing the number.

ios.call(server.cap());

call will send and than receive data. First it sends the data stored in the UTCB to the thread were the server capability comes from. Second it blocks the current thread and makes a closed wait for the thread behind the server capability. cap() just returns the capability selector from the Cap. The thread will be unblocked if an IPC arrives, in this case the answer of the simple-server containing a number.

ios >> n;

After the answer from server has arrived, we read some number out of it.

cout << n << "\n";

And finally we print this number. Done.

server.cc

The more complex server contains a very important pattern. It defines a Server_object which does the actual work of answering requests and a Registry_server which dispatches IPCs to different Server_objects.

struct SimpleServer : Server_object

We define our SimpleServer as a Server_object and need to implement its very simple interface.

int dispatch(l4_umword_t, Ipc::Iostream &ios)

dispatch is the only method needed to implement the interface of Server_object. We discard the first argument, cause we don't need it. The second argument is more interesting. It is an already set up Ipc::Iostream, which points to the UTCB containing the earliear send number.

ios >> n;

We can read this number. Particularly sizeof(n) bytes are read from the UTCB to n from the current position and the current position is forward by this number of bytes. No we can print the number and send the answer.

ios << n * 2;
return L4_EOK;

The answer is written to the UTCB and with L4_EOK we signal to the one who called dispatch that everything is alright.

In our main function we set up our server and the Server_object we implemented and let the server loop forever for accepting incoming IPCs and answering them.

Util::Registry_server<> server;

We instantiate a Registry_server which will be the heart of our server task. It maintains a registry, where objects of type Server_object are registered and has the loop method, which accepts an incoming IPC containing the capability selector used to identify the registered Server_object. Now the Server_object can be found in the registry and the incoming IPC can be forwarded as an Iostream to the dispatch method of the Server_object, the method above in this file.

Cap<void> cap = server.registry()->register_obj(&simple_server, "my_server_side");

This is the call which actually registers the our instance of SimpleServer in the registry() of the Registry_server. As we already saw in the ned.lua file, there is the name "my_server_side" and we use it here to say that whenever an IPC is made to the IPC-Gate named "my_server_side" the IPC is forwarded to the dispatch method of simple_server.

Now we have pretty much set up everything we need to let interaction of a client and a server happen.

server.loop();

We can now loop forever and deal with IPCs by forwarding them to our own Server_object and send our answer back.

Conclusion

We have seen a simple setup for a client and a server task in L4Re. With Ipc::Iostream you can read and write to an UTCB. Methods like call will initiate an IPC. You automatically get an Ipc::Iostream when you implement Server_object. Server_object itself is used handle IPCs and actually do something with requests and construct answers. Registry_server bundles the loop which receives IPCs and dispatches them to different Server_objects. Adding Server_objects to the server is as simple as registering them at the Registry_server.