README.md
1<!--
2 Copyright 2019, Data61, CSIRO (ABN 41 687 119 230)
3
4 SPDX-License-Identifier: CC-BY-SA-4.0
5-->
6
7# libsel4rpc
8
9Libsel4rpc provides a basic library for managing allocating resources over
10process boundaries. It provides a protobuf-based protocol definition, and a few
11simple wrappers to ease receiving/replying to RPC messages on the server side,
12and sending RPC requests on the client side.
13
14Resource allocation across process boundaries is reasonably common in seL4,
15where we often have a "parent" process (e.g. sel4test's driver), and a "child"
16process (e.g. sel4test's tests). Previously, if the child process wanted a
17resource (e.g. an IRQ, or a specific frame of memory), the parent had to know
18in advance and supply the resource(s) to the parent process to the child at
19process creation time.
20
21Libsel4rpc provides a simple way to remove the need for allocation in advance,
22and allows the parent to provide capabilities to the child process on demand.
23
24For example, a small sample is below...
25
26Server:
27```c
28// initialise the server
29sel4rpc_server_env_t rpc_server;
30sel4rpc_server_init(&rpc_server, vka, my_handler_function, my_data,
31 &env->reply, simple);
32
33// the main RPC loop
34while (1) {
35 seL4_MessageInfo_t info = api_recv(process_ep, &badge, env->reply.cptr);
36 if (seL4_GetMR(0) == blah) {
37 sel4rpc_server_recv(&rpc_server);
38 }
39}
40```
41
42Client:
43```c
44// initialise the client
45sel4rpc_client_t rpc_client;
46sel4rpc_client_init(&rpc_client, server_endpoint);
47
48// make an RPC request
49// create the request object: allocate an untyped object at address 0x10440000
50// this will be encoded into the process's IPC buffer by sel4rpc_call
51// and sent to the server.
52RpcMessage msg = {
53 .which_msg = RpcMessage_memory_tag,
54 .msg.memory = {
55 .address = 0x10440000,
56 .size_bits = 12,
57 .type = seL4_UntypedObject,
58 },
59};
60
61// set up somewhere to put our received capability
62cspacepath_t path;
63int ret = vka_alloc_path(vka, &path);
64if (ret)
65 ZF_LOGF("Failed to alloc path: %d", ret);
66
67// call, putting the response cap (if there is one) into the cap
68// represented by 'path'.
69ret = sel4rpc_call(&rpc_client, &msg, path.root, path.capPtr, path.capDepth);
70if (ret)
71 ZF_LOGF("RPC call failed: %d", ret);
72
73int errorCode = msg.msg.errorCode;
74if (errorCode)
75 ZF_LOGF("RPC alloc request failed: %d", errorCode);
76
77// at this point, the cap was successfully allocated and is ready to use.
78```
79