L4Re - L4 Runtime Environment
|
An interface definition in L4Re is normally declared as a class derived from L4::Kobject_t.
For example, the simple calculator example declares its interface like that:
The signature of each function is first declared using on of the RPC macros (see below) and then all the functions need to be listed in the Rpcs type.
Generally all value parameters, const reference parameters, and const pointer parameters to an RPC interface are considered as input parameters for the RPC and are transmitted from the client to the server.
char const *
is treated as an input char
and not as a zero terminated string value, for strings see L4::Ipc::String<>.Parameters that are non-const references or non-const pointers are treated as output parameters going from the server to the client.
The example shows the declaration of a method called test
with long
as return type, arg1
is an int
input, arg2
a char
input, and ret1
an unsigned
output parameter.
Type | Direction | Client-Type | Server-Type |
---|---|---|---|
T | Input | T | T |
T const & | Input | T const & | T const & |
T const * | Input | T const * | T const & |
T & | Output | T & | T & |
T * | Output | T * | T & |
L4::Ipc::In_out<T &> | In/Out | T & | T & |
L4::Ipc::In_out<T *> | In/Out | T * | T & |
L4::Ipc::Cap<T> | Input | L4::Ipc::Cap<T> | L4::Ipc::Snd_fpage |
L4::Ipc::Out<L4::Cap<T> > | Output | L4::Cap<T> | L4::Ipc::Cap<T> & |
Array types can be used to transmit arrays of variable length. They can either be stored in a client-provided buffer (L4::Ipc::Array), copied into a server-provided buffer (L4::Ipc::Array_in_buf) or directly read and written into the UTCB (L4::Ipc::Array_ref). For latter type, the start position of an array type needs to be known in advance. That implies that only one such array can be transmitted per direction and it must be the last part in the message.
Type | Direction | Client-Type | Server-Type |
---|---|---|---|
L4::Ipc::Array<const T> | Input | L4::Ipc::Array<const T> | L4::Ipc::Array_ref<const T> |
L4::Ipc::Array<const T> | Input | L4::Ipc::Array<const T> | L4::Ipc::Array_in_buf<T> const & |
L4::Ipc::Array<T> & | Output | L4::Ipc::Array<T> & | L4::Ipc::Array_ref<T> & |
L4::Ipc::Array_ref<T> & | Output | L4::Ipc::Array_ref<T> & | L4::Ipc::Array_ref<T> & |
Finally, there are some optional types where the sender can choose if the parameter should be included in the message. These types are for the implementation of some legacy message formats and should generally not be needed for the definition of ordinary interfaces.
Type | Direction | Client-Type | Server-Type |
---|---|---|---|
L4::Ipc::Opt<T> | Input | L4::Ipc::Opt<T> | T |
L4::Ipc::Opt<const T*> | Input | L4::Ipc::Opt<const T*> | T |
L4::Ipc::Opt<T &> | Output | T & | L4::Ipc::Opt<T> & |
L4::Ipc::Opt<T *> | Output | T * | L4::Ipc::Opt<T> & |
L4::Ipc::Opt<Array_ref<T> &> | Output | Array_ref<T> & | L4::Ipc::Opt<Array_ref<T>> & |
On the server side, the return type of an RPC handling function is always long
. The return value is transmitted via the label field in l4_msgtag_t and is therefore restricted to its length. Per convention, a negative return value is interpreted as an error condition. If the return value is negative, output parameters are not transmitted back to the client.
On the client-side, the return value of the RPC is set as defined in the RPC macro. If l4_msgtag_t
is given, then the client has access to the full message tag, otherwise the return type should be long
. Note that the client might not only receive the server return value in response but also an IPC error code.
RPC member functions can be declared using one of the following C++ macros.
For inline RPC stubs, where the RPC stub code itself is inline
:
For external RPC stubs, where the RPC stub code must be defined in a separate compile unit (usually a .cc
file):
To generate the implementation of an external RPC stub:
The NF
versions of the macro generally do not generate a callable member function named <name>
but do only generate the type <name>_t
. This data type can be used to call the RPC stub explicitly using <name>_t::call(L4::Cap<Iface_class> cap, args...)
.