Loading...
Searching...
No Matches
Interface Definition Language

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:

struct Calc : L4::Kobject_t<Calc, L4::Kobject>
{
L4_INLINE_RPC(long, sub, (l4_uint32_t a, l4_uint32_t b, l4_uint32_t *res));
L4_INLINE_RPC(long, neg, (l4_uint32_t a, l4_uint32_t *res));
typedef L4::Typeid::Rpcs<sub_t, neg_t> Rpcs;
};
L4::Kobject_t
Helper class to create an L4Re interface class that is derived from a single base class.
Definition __typeinfo.h:750
l4_uint32_t
unsigned int l4_uint32_t
Unsigned 32bit value.
Definition l4int.h:29
L4_INLINE_RPC
#define L4_INLINE_RPC(res, name, args, attr...)
Define an inline RPC call (type and callable).
Definition ipc_iface:482
L4::Typeid::Rpcs
Standard list of RPCs of an interface.
Definition __typeinfo.h:428

The signature of each function is first declared using one of the RPC macros (see below) and then all the functions need to be listed in the Rpcs type.

Clients invoke these functions with the name given to the RPC macros, sub and neg above. Servers implement them by defining functions with an op_ prepended, op_sub and op_neg. The types of the parameters in the macro definition, on the server side, and on the client side are not the same. The following section describes how they are related to each other.

# Parameter types for RPC

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.

Note
  This means that 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.

There are special data types that appear on only one side (client or server) when used, see the following table for details.

L4_RPC(long, test, (int arg1, char const *arg2, unsigned *ret1));
L4_RPC
#define L4_RPC(res, name, args, attr...)
Define an RPC call (type and callable).
Definition ipc_iface:541

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> &
L4::Ipc::Rcv_fpage | Input | L4::Ipc::Rcv_fpage | void
L4::Ipc::Small_buf | Input | L4::Ipc::Small_buf | void

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).

Constraints on L4::Ipc::Array_ref:

- the start position of this array type needs to be known in advance.
- it must be the last parameter of a message.
- the size of the array type is not transmitted to the server, only the client side knows the intended size of the input array. The server assumes the rest of the UTCB as the actual array. Different sever-side behavior must be steered otherwise, e.g. through another parameter.

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>> &

# Server Side Interface

The server side function signature for the Calc example above is

long op_sub(Calc::Rights, l4_uint32_t a, l4_uint32_t b, l4_uint32_t &res);

The first rights parameter is a bitfield encoding the rights the client has on the used capability in the lower two bits. Currently, the W-right and S-right are supported. The rest of the Rights-bitfield is reserved.

The second and third arguments are input parameters as can be deduced from the tables above. The fourth parameter is an output parameter, delivered to the client with the return value of type long.

# RPC Return Types

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.

Attention
  The client must never rely on the content of output parameters when the return value is negative.

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 Method Declaration

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:

- L4_INLINE_RPC(res, name, (args...), flags)
  Define an inline RPC call (type and callable).
- L4_INLINE_RPC_OP(op, res, name, (args...), flags)
  L4_INLINE_RPC_OP
  #define L4_INLINE_RPC_OP(op, res, name, args, attr...)
  Define an inline RPC call with specific opcode (type and callable).
  Definition ipc_iface:497
  Define an inline RPC call with specific opcode (type and callable).
- L4_INLINE_RPC_NF(res, name, (args...), flags)
  L4_INLINE_RPC_NF
  #define L4_INLINE_RPC_NF(res, name, args...)
  Define an inline RPC call type (the type only, no callable).
  Definition ipc_iface:453
  Define an inline RPC call type (the type only, no callable).
- L4_INLINE_RPC_NF_OP(opcode, Ret_type, func_name, (args...), flags)
  L4_INLINE_RPC_NF_OP
  #define L4_INLINE_RPC_NF_OP(op, res, name, args...)
  Define an inline RPC call type with specific opcode (the type only, no callable).
  Definition ipc_iface:466
  Define an inline RPC call type with specific opcode (the type only, no callable).

For external RPC stubs, where the RPC stub code must be defined in a separate compile unit (usually a .cc file):

- L4_RPC(Ret_type, func_name, (args...), flags)
  Define an RPC call (type and callable).
- L4_RPC_OP(opcode, Ret_type, func_name, (args...), flags)
  L4_RPC_OP
  #define L4_RPC_OP(op, res, name, args, attr...)
  Define an RPC call with specific opcode (type and callable).
  Definition ipc_iface:556
  Define an RPC call with specific opcode (type and callable).
- L4_RPC_NF(Ret_type, func_name, (args...), flags)
  L4_RPC_NF
  #define L4_RPC_NF(res, name, args...)
  Define an RPC call type (the type only, no callable).
  Definition ipc_iface:510
  Define an RPC call type (the type only, no callable).
- L4_RPC_NF_OP(opcode, Ret_type, func_name, (args...), flags)
  L4_RPC_NF_OP
  #define L4_RPC_NF_OP(op, res, name, args...)
  Define an RPC call type with specific opcode (the type only, no callable).
  Definition ipc_iface:525
  Define an RPC call type with specific opcode (the type only, no callable).

To generate the implementation of an external RPC stub:

- L4_RPC_DEF(class_name::func_name)
  L4_RPC_DEF
  #define L4_RPC_DEF(name)
  Generate the definition of an RPC stub.
  Definition ipc_client:32
  Generate the definition of an 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...).