2011-12-22 15:19:25 +00:00
|
|
|
/*
|
|
|
|
* \brief Generic root component implementation
|
|
|
|
* \author Norman Feske
|
|
|
|
* \date 2006-05-22
|
|
|
|
*
|
|
|
|
* This class is there for your convenience. It performs the common actions
|
|
|
|
* that must always be taken when creating a new session.
|
|
|
|
*/
|
|
|
|
|
|
|
|
/*
|
2017-02-20 12:23:52 +00:00
|
|
|
* Copyright (C) 2006-2017 Genode Labs GmbH
|
2011-12-22 15:19:25 +00:00
|
|
|
*
|
|
|
|
* This file is part of the Genode OS framework, which is distributed
|
2017-02-20 12:23:52 +00:00
|
|
|
* under the terms of the GNU Affero General Public License version 3.
|
2011-12-22 15:19:25 +00:00
|
|
|
*/
|
|
|
|
|
|
|
|
#ifndef _INCLUDE__ROOT__COMPONENT_H_
|
|
|
|
#define _INCLUDE__ROOT__COMPONENT_H_
|
|
|
|
|
|
|
|
#include <root/root.h>
|
base: avoid use of deprecated base/printf.h
Besides adapting the components to the use of base/log.h, the patch
cleans up a few base headers, i.e., it removes unused includes from
root/component.h, specifically base/heap.h and
ram_session/ram_session.h. Hence, components that relied on the implicit
inclusion of those headers have to manually include those headers now.
While adjusting the log messages, I repeatedly stumbled over the problem
that printing char * arguments is ambiguous. It is unclear whether to
print the argument as pointer or null-terminated string. To overcome
this problem, the patch introduces a new type 'Cstring' that allows the
caller to express that the argument should be handled as null-terminated
string. As a nice side effect, with this type in place, the optional len
argument of the 'String' class could be removed. Instead of supplying a
pair of (char const *, size_t), the constructor accepts a 'Cstring'.
This, in turn, clears the way let the 'String' constructor use the new
output mechanism to assemble a string from multiple arguments (and
thereby getting rid of snprintf within Genode in the near future).
To enforce the explicit resolution of the char * ambiguity, the 'char *'
overload of the 'print' function is marked as deleted.
Issue #1987
2016-07-13 17:07:09 +00:00
|
|
|
#include <base/allocator.h>
|
2011-12-22 15:19:25 +00:00
|
|
|
#include <base/rpc_server.h>
|
2016-05-20 10:01:50 +00:00
|
|
|
#include <base/entrypoint.h>
|
2016-11-06 13:26:34 +00:00
|
|
|
#include <base/service.h>
|
2011-12-22 15:19:25 +00:00
|
|
|
#include <util/arg_string.h>
|
base: avoid use of deprecated base/printf.h
Besides adapting the components to the use of base/log.h, the patch
cleans up a few base headers, i.e., it removes unused includes from
root/component.h, specifically base/heap.h and
ram_session/ram_session.h. Hence, components that relied on the implicit
inclusion of those headers have to manually include those headers now.
While adjusting the log messages, I repeatedly stumbled over the problem
that printing char * arguments is ambiguous. It is unclear whether to
print the argument as pointer or null-terminated string. To overcome
this problem, the patch introduces a new type 'Cstring' that allows the
caller to express that the argument should be handled as null-terminated
string. As a nice side effect, with this type in place, the optional len
argument of the 'String' class could be removed. Instead of supplying a
pair of (char const *, size_t), the constructor accepts a 'Cstring'.
This, in turn, clears the way let the 'String' constructor use the new
output mechanism to assemble a string from multiple arguments (and
thereby getting rid of snprintf within Genode in the near future).
To enforce the explicit resolution of the char * ambiguity, the 'char *'
overload of the 'print' function is marked as deleted.
Issue #1987
2016-07-13 17:07:09 +00:00
|
|
|
#include <base/log.h>
|
2011-12-22 15:19:25 +00:00
|
|
|
|
|
|
|
namespace Genode {
|
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
class Single_client;
|
|
|
|
class Multiple_clients;
|
|
|
|
template <typename, typename POLICY = Multiple_clients> class Root_component;
|
|
|
|
}
|
2011-12-22 15:19:25 +00:00
|
|
|
|
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
/**
|
|
|
|
* Session creation policy for a single-client service
|
|
|
|
*/
|
|
|
|
class Genode::Single_client
|
|
|
|
{
|
|
|
|
private:
|
2011-12-22 15:19:25 +00:00
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
bool _used;
|
2011-12-22 15:19:25 +00:00
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
public:
|
2011-12-22 15:19:25 +00:00
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
Single_client() : _used(0) { }
|
2011-12-22 15:19:25 +00:00
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
void aquire(const char *)
|
|
|
|
{
|
|
|
|
if (_used)
|
|
|
|
throw Root::Unavailable();
|
2011-12-22 15:19:25 +00:00
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
_used = true;
|
|
|
|
}
|
2011-12-22 15:19:25 +00:00
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
void release() { _used = false; }
|
|
|
|
};
|
2011-12-22 15:19:25 +00:00
|
|
|
|
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
/**
|
|
|
|
* Session-creation policy for a multi-client service
|
|
|
|
*/
|
|
|
|
struct Genode::Multiple_clients
|
|
|
|
{
|
|
|
|
void aquire(const char *) { }
|
|
|
|
void release() { }
|
|
|
|
};
|
2011-12-22 15:19:25 +00:00
|
|
|
|
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
/**
|
|
|
|
* Template for implementing the root interface
|
|
|
|
*
|
|
|
|
* \param SESSION_TYPE session-component type to manage,
|
|
|
|
* derived from 'Rpc_object'
|
|
|
|
* \param POLICY session-creation policy
|
|
|
|
*
|
|
|
|
* The 'POLICY' template parameter allows for constraining the session
|
|
|
|
* creation to only one instance at a time (using the 'Single_session'
|
|
|
|
* policy) or multiple instances (using the 'Multiple_sessions' policy).
|
|
|
|
*
|
2015-03-20 16:50:41 +00:00
|
|
|
* The 'POLICY' class must provide the following two methods:
|
2015-03-04 20:12:14 +00:00
|
|
|
*
|
2015-05-13 20:11:46 +00:00
|
|
|
* 'aquire(const char *args)' is called with the session arguments
|
|
|
|
* at creation time of each new session. It can therefore implement
|
|
|
|
* a session-creation policy taking session arguments into account.
|
|
|
|
* If the policy denies the creation of a new session, it throws
|
|
|
|
* one of the exceptions defined in the 'Root' interface.
|
2015-03-04 20:12:14 +00:00
|
|
|
*
|
2015-05-13 20:11:46 +00:00
|
|
|
* 'release' is called at the destruction time of a session. It enables
|
|
|
|
* the policy to keep track of and impose restrictions on the number
|
|
|
|
* of existing sessions.
|
2015-03-04 20:12:14 +00:00
|
|
|
*
|
|
|
|
* The default policy 'Multiple_clients' imposes no restrictions on the
|
|
|
|
* creation of new sessions.
|
|
|
|
*/
|
|
|
|
template <typename SESSION_TYPE, typename POLICY>
|
|
|
|
class Genode::Root_component : public Rpc_object<Typed_root<SESSION_TYPE> >,
|
2016-11-06 13:26:34 +00:00
|
|
|
public Local_service<SESSION_TYPE>::Factory,
|
2015-03-04 20:12:14 +00:00
|
|
|
private POLICY
|
|
|
|
{
|
|
|
|
private:
|
|
|
|
|
|
|
|
/*
|
|
|
|
* Entry point that manages the session objects
|
|
|
|
* created by this root interface
|
|
|
|
*/
|
|
|
|
Rpc_entrypoint *_ep;
|
|
|
|
|
|
|
|
/*
|
|
|
|
* Allocator for allocating session objects.
|
|
|
|
* This allocator must be used by the derived
|
|
|
|
* class when calling the 'new' operator for
|
|
|
|
* creating a new session.
|
|
|
|
*/
|
|
|
|
Allocator *_md_alloc;
|
|
|
|
|
2016-11-06 13:26:34 +00:00
|
|
|
/*
|
|
|
|
* Used by both the legacy 'Root::session' and the new 'Factory::create'
|
|
|
|
*/
|
|
|
|
SESSION_TYPE &_create(Session_state::Args const &args, Affinity affinity)
|
|
|
|
{
|
|
|
|
POLICY::aquire(args.string());
|
|
|
|
|
2017-02-21 14:17:41 +00:00
|
|
|
/*
|
|
|
|
* Guard to ensure that 'release' is called whenever the scope
|
|
|
|
* is left with an exception.
|
|
|
|
*/
|
|
|
|
struct Guard
|
|
|
|
{
|
|
|
|
bool ack = false;
|
|
|
|
Root_component &root;
|
|
|
|
Guard(Root_component &root) : root(root) { }
|
|
|
|
~Guard() { if (!ack) root.release(); }
|
|
|
|
} aquire_guard { *this };
|
|
|
|
|
2016-11-06 13:26:34 +00:00
|
|
|
/*
|
|
|
|
* We need to decrease 'ram_quota' by
|
|
|
|
* the size of the session object.
|
|
|
|
*/
|
|
|
|
size_t ram_quota = Arg_string::find_arg(args.string(), "ram_quota").ulong_value(0);
|
|
|
|
size_t needed = sizeof(SESSION_TYPE) + md_alloc()->overhead(sizeof(SESSION_TYPE));
|
|
|
|
|
|
|
|
if (needed > ram_quota) {
|
base: remove Child::heap
This patch improves the accounting for the backing store of
session-state meta data. Originally, the session state used to be
allocated by a child-local heap partition fed from the child's RAM
session. However, whereas this approach was somehow practical from a
runtime's (parent's) point of view, the child component could not count
on the quota in its own RAM session. I.e., if the Child::heap grew at
the parent side, the child's RAM session would magically diminish. This
caused two problems. First, it violates assumptions of components like
init that carefully manage their RAM resources (and giving most of them
away their children). Second, if a child transfers most of its RAM
session quota to another RAM session (like init does), the child's RAM
session may actually not allow the parent's heap to grow, which is a
very difficult error condition to deal with.
In the new version, there is no Child::heap anymore. Instead, session
states are allocated from the runtime's RAM session. In order to let
children pay for these costs, the parent withdraws the local session
costs from the session quota donated from the child when the child
initiates a new session. Hence, in principle, all components on the
route of the session request take a small bite from the session quota to
pay for their local book keeping
Consequently, the session quota that ends up at the server may become
depleted more or less, depending on the route. In the case where the
remaining quota is insufficient for the server, the server responds with
'QUOTA_EXCEEDED'. Since this behavior must generally be expected, this
patch equips the client-side 'Env::session' implementation with the
ability to re-issue session requests with successively growing quota
donations.
For several of core's services (ROM, IO_MEM, IRQ), the default session
quota has now increased by 2 KiB, which should suffice for session
requests to up to 3 hops as is the common case for most run scripts. For
longer routes, the retry mechanism as described above comes into effect.
For the time being, we give a warning whenever the server-side quota
check triggers the retry mechanism. The warning may eventually be
removed at a later stage.
2017-02-19 09:31:50 +00:00
|
|
|
warning("insufficient ram quota "
|
|
|
|
"for ", SESSION_TYPE::service_name(), " session, "
|
|
|
|
"provided=", ram_quota, ", required=", needed);
|
2016-11-06 13:26:34 +00:00
|
|
|
throw Root::Quota_exceeded();
|
|
|
|
}
|
|
|
|
|
|
|
|
size_t const remaining_ram_quota = ram_quota - needed;
|
|
|
|
|
|
|
|
/*
|
|
|
|
* Deduce ram quota needed for allocating the session object from the
|
|
|
|
* donated ram quota.
|
|
|
|
*
|
|
|
|
* XXX the size of the 'adjusted_args' buffer should dependent
|
|
|
|
* on the message-buffer size and stack size.
|
|
|
|
*/
|
|
|
|
enum { MAX_ARGS_LEN = 256 };
|
|
|
|
char adjusted_args[MAX_ARGS_LEN];
|
|
|
|
strncpy(adjusted_args, args.string(), sizeof(adjusted_args));
|
|
|
|
char ram_quota_buf[64];
|
|
|
|
snprintf(ram_quota_buf, sizeof(ram_quota_buf), "%lu",
|
|
|
|
remaining_ram_quota);
|
|
|
|
Arg_string::set_arg(adjusted_args, sizeof(adjusted_args),
|
|
|
|
"ram_quota", ram_quota_buf);
|
|
|
|
|
|
|
|
SESSION_TYPE *s = 0;
|
|
|
|
try { s = _create_session(adjusted_args, affinity); }
|
2017-01-30 14:23:13 +00:00
|
|
|
catch (Allocator::Out_of_memory) {
|
|
|
|
error("out of memory for session creation, '", args, "'");
|
|
|
|
throw Root::Unavailable();
|
|
|
|
}
|
2016-11-06 13:26:34 +00:00
|
|
|
|
|
|
|
_ep->manage(s);
|
|
|
|
|
2017-02-21 14:17:41 +00:00
|
|
|
aquire_guard.ack = true;
|
2016-11-06 13:26:34 +00:00
|
|
|
return *s;
|
|
|
|
}
|
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
protected:
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Create new session (to be implemented by a derived class)
|
|
|
|
*
|
|
|
|
* Only a derived class knows the constructor arguments of
|
|
|
|
* a specific session. Therefore, we cannot unify the call
|
|
|
|
* of its 'new' operator and must implement the session
|
|
|
|
* creation at a place, where the required knowledge exist.
|
|
|
|
*
|
2015-03-20 16:50:41 +00:00
|
|
|
* In the implementation of this method, the heap, provided
|
2015-03-04 20:12:14 +00:00
|
|
|
* by 'Root_component' must be used for allocating the session
|
|
|
|
* object.
|
|
|
|
*
|
|
|
|
* If the server implementation does not evaluate the session
|
|
|
|
* affinity, it suffices to override the overload without the
|
|
|
|
* affinity argument.
|
|
|
|
*
|
|
|
|
* \throw Allocator::Out_of_memory typically caused by the
|
|
|
|
* meta-data allocator
|
|
|
|
* \throw Root::Invalid_args typically caused by the
|
|
|
|
* session-component constructor
|
|
|
|
*/
|
|
|
|
virtual SESSION_TYPE *_create_session(const char *args,
|
|
|
|
Affinity const &)
|
|
|
|
{
|
|
|
|
return _create_session(args);
|
|
|
|
}
|
|
|
|
|
|
|
|
virtual SESSION_TYPE *_create_session(const char *args)
|
|
|
|
{
|
|
|
|
throw Root::Invalid_args();
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Inform session about a quota upgrade
|
|
|
|
*
|
|
|
|
* Once a session is created, its client can successively extend
|
2015-03-20 16:50:41 +00:00
|
|
|
* its quota donation via the 'Parent::transfer_quota' operation.
|
2015-03-04 20:12:14 +00:00
|
|
|
* This will result in the invokation of 'Root::upgrade' at the
|
|
|
|
* root interface the session was created with. The root interface,
|
|
|
|
* in turn, informs the session about the new resources via the
|
2015-03-20 16:50:41 +00:00
|
|
|
* '_upgrade_session' method. The default implementation is
|
2015-03-04 20:12:14 +00:00
|
|
|
* suited for sessions that use a static amount of resources
|
|
|
|
* accounted for at session-creation time. For such sessions, an
|
|
|
|
* upgrade is not useful. However, sessions that dynamically
|
|
|
|
* allocate resources on behalf of its client, should respond to
|
2015-03-20 16:50:41 +00:00
|
|
|
* quota upgrades by implementing this method.
|
2015-03-04 20:12:14 +00:00
|
|
|
*
|
|
|
|
* \param session session to upgrade
|
|
|
|
* \param args description of additional resources in the
|
|
|
|
* same format as used at session creation
|
|
|
|
*/
|
|
|
|
virtual void _upgrade_session(SESSION_TYPE *, const char *) { }
|
|
|
|
|
|
|
|
virtual void _destroy_session(SESSION_TYPE *session) {
|
2016-11-06 13:26:34 +00:00
|
|
|
Genode::destroy(_md_alloc, session); }
|
2015-03-04 20:12:14 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Return allocator to allocate server object in '_create_session()'
|
|
|
|
*/
|
2015-03-20 16:50:41 +00:00
|
|
|
Allocator *md_alloc() { return _md_alloc; }
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Return entrypoint that serves the root component
|
|
|
|
*/
|
|
|
|
Rpc_entrypoint *ep() { return _ep; }
|
2015-03-04 20:12:14 +00:00
|
|
|
|
|
|
|
public:
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Constructor
|
|
|
|
*
|
2016-05-20 10:01:50 +00:00
|
|
|
* \param ep entry point that manages the sessions of this
|
|
|
|
* root interface
|
|
|
|
* \param md_alloc meta-data allocator providing the backing store
|
|
|
|
* for session objects
|
2015-03-04 20:12:14 +00:00
|
|
|
*/
|
2016-05-20 10:01:50 +00:00
|
|
|
Root_component(Entrypoint &ep, Allocator &md_alloc)
|
|
|
|
:
|
|
|
|
_ep(&ep.rpc_ep()), _md_alloc(&md_alloc)
|
|
|
|
{ }
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Constructor
|
|
|
|
*
|
|
|
|
* \deprecated use the constructor with the 'Entrypoint &'
|
|
|
|
* argument instead
|
|
|
|
*/
|
|
|
|
Root_component(Rpc_entrypoint *ep, Allocator *md_alloc)
|
|
|
|
:
|
|
|
|
_ep(ep), _md_alloc(md_alloc)
|
|
|
|
{ }
|
2015-03-04 20:12:14 +00:00
|
|
|
|
|
|
|
|
2016-11-06 13:26:34 +00:00
|
|
|
/**************************************
|
|
|
|
** Local_service::Factory interface **
|
|
|
|
**************************************/
|
|
|
|
|
|
|
|
SESSION_TYPE &create(Session_state::Args const &args,
|
|
|
|
Affinity affinity) override
|
|
|
|
{
|
|
|
|
try {
|
|
|
|
return _create(args, affinity); }
|
base: remove Child::heap
This patch improves the accounting for the backing store of
session-state meta data. Originally, the session state used to be
allocated by a child-local heap partition fed from the child's RAM
session. However, whereas this approach was somehow practical from a
runtime's (parent's) point of view, the child component could not count
on the quota in its own RAM session. I.e., if the Child::heap grew at
the parent side, the child's RAM session would magically diminish. This
caused two problems. First, it violates assumptions of components like
init that carefully manage their RAM resources (and giving most of them
away their children). Second, if a child transfers most of its RAM
session quota to another RAM session (like init does), the child's RAM
session may actually not allow the parent's heap to grow, which is a
very difficult error condition to deal with.
In the new version, there is no Child::heap anymore. Instead, session
states are allocated from the runtime's RAM session. In order to let
children pay for these costs, the parent withdraws the local session
costs from the session quota donated from the child when the child
initiates a new session. Hence, in principle, all components on the
route of the session request take a small bite from the session quota to
pay for their local book keeping
Consequently, the session quota that ends up at the server may become
depleted more or less, depending on the route. In the case where the
remaining quota is insufficient for the server, the server responds with
'QUOTA_EXCEEDED'. Since this behavior must generally be expected, this
patch equips the client-side 'Env::session' implementation with the
ability to re-issue session requests with successively growing quota
donations.
For several of core's services (ROM, IO_MEM, IRQ), the default session
quota has now increased by 2 KiB, which should suffice for session
requests to up to 3 hops as is the common case for most run scripts. For
longer routes, the retry mechanism as described above comes into effect.
For the time being, we give a warning whenever the server-side quota
check triggers the retry mechanism. The warning may eventually be
removed at a later stage.
2017-02-19 09:31:50 +00:00
|
|
|
catch (Root::Quota_exceeded) { throw Service::Quota_exceeded(); }
|
2016-11-06 13:26:34 +00:00
|
|
|
catch (...) {
|
|
|
|
throw typename Local_service<SESSION_TYPE>::Factory::Denied(); }
|
|
|
|
}
|
|
|
|
|
|
|
|
void upgrade(SESSION_TYPE &session,
|
|
|
|
Session_state::Args const &args) override
|
|
|
|
{
|
|
|
|
_upgrade_session(&session, args.string());
|
|
|
|
}
|
|
|
|
|
|
|
|
void destroy(SESSION_TYPE &session) override
|
|
|
|
{
|
|
|
|
close(session.cap());
|
|
|
|
}
|
|
|
|
|
|
|
|
|
2015-03-04 20:12:14 +00:00
|
|
|
/********************
|
|
|
|
** Root interface **
|
|
|
|
********************/
|
|
|
|
|
|
|
|
Session_capability session(Root::Session_args const &args,
|
|
|
|
Affinity const &affinity) override
|
|
|
|
{
|
2016-05-11 16:21:47 +00:00
|
|
|
if (!args.valid_string()) throw Root::Invalid_args();
|
2016-11-06 13:26:34 +00:00
|
|
|
SESSION_TYPE &session = _create(args.string(), affinity);
|
|
|
|
return session.cap();
|
2015-03-04 20:12:14 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
void upgrade(Session_capability session, Root::Upgrade_args const &args) override
|
|
|
|
{
|
2016-05-11 16:21:47 +00:00
|
|
|
if (!args.valid_string()) throw Root::Invalid_args();
|
2015-03-04 20:12:14 +00:00
|
|
|
|
2015-08-10 11:34:16 +00:00
|
|
|
_ep->apply(session, [&] (SESSION_TYPE *s) {
|
|
|
|
if (!s) return;
|
2015-03-04 20:12:14 +00:00
|
|
|
|
2015-08-10 11:34:16 +00:00
|
|
|
_upgrade_session(s, args.string());
|
|
|
|
});
|
2015-03-04 20:12:14 +00:00
|
|
|
}
|
|
|
|
|
2015-08-10 11:34:16 +00:00
|
|
|
void close(Session_capability session_cap) override
|
2015-03-04 20:12:14 +00:00
|
|
|
{
|
2015-08-10 11:34:16 +00:00
|
|
|
SESSION_TYPE * session;
|
2015-03-04 20:12:14 +00:00
|
|
|
|
2015-08-10 11:34:16 +00:00
|
|
|
_ep->apply(session_cap, [&] (SESSION_TYPE *s) {
|
|
|
|
session = s;
|
2015-03-04 20:12:14 +00:00
|
|
|
|
2015-08-10 11:34:16 +00:00
|
|
|
/* let the entry point forget the session object */
|
|
|
|
if (session) _ep->dissolve(session);
|
|
|
|
});
|
|
|
|
|
|
|
|
if (!session) return;
|
|
|
|
|
|
|
|
_destroy_session(session);
|
2015-03-04 20:12:14 +00:00
|
|
|
|
|
|
|
POLICY::release();
|
|
|
|
}
|
|
|
|
};
|
2011-12-22 15:19:25 +00:00
|
|
|
|
|
|
|
#endif /* _INCLUDE__ROOT__COMPONENT_H_ */
|