genode/repos/base/include/rom_session/rom_session.h
2017-05-31 13:16:21 +02:00

122 lines
3.7 KiB
C++

/*
* \brief ROM session interface
* \author Norman Feske
* \date 2006-07-06
*
* A ROM session corresponds to a ROM module. The module name is specified as
* an argument on session creation.
*/
/*
* Copyright (C) 2006-2017 Genode Labs GmbH
*
* This file is part of the Genode OS framework, which is distributed
* under the terms of the GNU Affero General Public License version 3.
*/
#ifndef _INCLUDE__ROM_SESSION__ROM_SESSION_H_
#define _INCLUDE__ROM_SESSION__ROM_SESSION_H_
#include <dataspace/capability.h>
#include <session/session.h>
#include <base/signal.h>
namespace Genode {
struct Rom_dataspace;
struct Rom_session;
struct Rom_session_client;
typedef Capability<Rom_dataspace> Rom_dataspace_capability;
}
struct Genode::Rom_dataspace : Dataspace { };
struct Genode::Rom_session : Session
{
/**
* \noapi
*/
static const char *service_name() { return "ROM"; }
/*
* A ROM session consumes a dataspace capability for the session-object
* allocation, a dataspace capability for the ROM dataspace, and its
* session capability.
*/
enum { CAP_QUOTA = 3 };
typedef Rom_session_client Client;
virtual ~Rom_session() { }
/**
* Request dataspace containing the ROM session data
*
* \return capability to ROM dataspace
*
* The capability may be invalid.
*
* Consecutive calls of this method are not guaranteed to return the
* same dataspace as dynamic ROM sessions may update the ROM data
* during the lifetime of the session. When calling the method, the
* server may destroy the old dataspace and replace it with a new one
* containing the updated data. Hence, prior calling this method, the
* client should make sure to detach the previously requested dataspace
* from its local address space.
*/
virtual Rom_dataspace_capability dataspace() = 0;
/**
* Update ROM dataspace content
*
* This method is an optimization for use cases where ROM dataspaces
* are updated at a high rate. In such cases, requesting a new
* dataspace for each update induces a large overhead because
* memory mappings must be revoked and updated (e.g., handling the
* page faults referring to the dataspace). If the updated content
* fits in the existing dataspace, those costly operations can be
* omitted.
*
* When this method is called, the server may replace the dataspace
* content with new data.
*
* \return true if the existing dataspace contains up-to-date content,
* or false if a new dataspace must be requested via the
* 'dataspace' method
*/
virtual bool update() { return false; }
/**
* Register signal handler to be notified of ROM data changes
*
* The ROM session interface allows for the implementation of ROM
* services that dynamically update the data exported as ROM dataspace
* during the lifetime of the session. This is useful in scenarios
* where this data is generated rather than originating from a static
* file, for example to update a program's configuration at runtime.
*
* By installing a signal handler using the 'sigh()' method, the
* client will receive a notification each time the data changes at the
* server. From the client's perspective, the original data contained
* in the currently used dataspace remains unchanged until the client
* calls 'dataspace()' the next time.
*/
virtual void sigh(Signal_context_capability sigh) = 0;
/*********************
** RPC declaration **
*********************/
GENODE_RPC(Rpc_dataspace, Rom_dataspace_capability, dataspace);
GENODE_RPC(Rpc_sigh, void, sigh, Signal_context_capability);
GENODE_RPC(Rpc_update, bool, update);
GENODE_RPC_INTERFACE(Rpc_dataspace, Rpc_update, Rpc_sigh);
};
#endif /* _INCLUDE__ROM_SESSION__ROM_SESSION_H_ */