API primitives

Capability types

As described in Section Capability-based security, inter-component communication is based on capabilities. A capability refers to a system-wide unique object identity and can be delegated among components. At API level, each capability is associated with the type of the RPC interface the capability refers to - similar to how a C++ reference refers to the type of a specific C++ object.


Sessions and connections

Servers provide their services over session-based communication channels. A Session type is defined as an abstract interface inherited from the Session base class.


Each session interface has to provide an implementation of the following class function that returns the name of the service as constant string.

 static const char *service_name();

This function is used by the framework for the announcement of the service's root interface at the component's parent. The string returned by this function corresponds to the service name as used in the system configuration (Section System configuration).

The interaction of a client with a server involves the definition of session-construction arguments, the request of the session creation via its parent, the initialization of the matching RPC-client stub code with the received session capability, the actual use of the session interface, and the closure of the session. The Connection template class provides a way to greatly simplify the handling of session arguments, session creation, and destruction on the client side. By implementing a service-specific connection class inherited from Connection, session arguments become plain constructor arguments, session functions can be called directly on the Connection object, and the session gets properly closed when destructing the Connection.


Dataspace interface

The dataspace abstraction described in Section Dataspaces is the fundamental API primitive for representing a container of memory as provided by core's PD, IO_MEM, or ROM services. Each dataspace is referenced by a capability that can be passed among components. Each component with the capability to a dataspace can access the dataspace's content by attaching the dataspace to the region map of its PD session. In addition to the use as arguments for region-map operations, dataspaces provide the following interface.


Attached dataspace

As a utility for handling the common case where a dataspace is attached to the component's address space as long as a certain object (like a session) exists, an instance of an Attached_dataspace can be hosted as a member variable. When destructed, the dataspace will be automatically detached from the component's address space.