1  /*
   2   * \brief  ROM session interface
   3   * \author Norman Feske
   4   * \date   2006-07-06
   5   *
   6   * A ROM session corresponds to a ROM module. The module name is specified as
   7   * an argument on session creation.
   8   */
   9  
  10  /*
  11   * Copyright (C) 2006-2014 Genode Labs GmbH
  12   *
  13   * This file is part of the Genode OS framework, which is distributed
  14   * under the terms of the GNU General Public License version 2.
  15   */
  16  
  17  #ifndef _INCLUDE__ROM_SESSION__ROM_SESSION_H_
  18  #define _INCLUDE__ROM_SESSION__ROM_SESSION_H_
  19  
  20  #include <dataspace/capability.h>
  21  #include <session/session.h>
  22  #include <base/signal.h>
  23  
  24  namespace Genode {
  25  
  26     struct Rom_dataspace;
  27     struct Rom_session;
  28  
  29     typedef Capability<Rom_dataspace> Rom_dataspace_capability;
  30  }
  31  
  32  
  33  struct Genode::Rom_dataspace : Dataspace { };
  34  
  35  
  36  struct Genode::Rom_session : Session
  37  {
  38     static const char *service_name() { return "ROM"; }
  39  
  40     virtual ~Rom_session() { }
  41  
  42     /**
  43      * Request dataspace containing the ROM session data
  44      *
  45      * \return  capability to ROM dataspace
  46      *
  47      * The capability may be invalid.
  48      *
  49      * Consecutive calls of this method are not guaranteed to return the
  50      * same dataspace as dynamic ROM sessions may update the ROM data
  51      * during the lifetime of the session. When calling the method, the
  52      * server may destroy the old dataspace and replace it with a new one
  53      * containing the updated data. Hence, prior calling this method, the
  54      * client should make sure to detach the previously requested dataspace
  55      * from its local address space.
  56      */
  57     virtual Rom_dataspace_capability dataspace() = 0;
  58  
  59     /**
  60      * Update ROM dataspace content
  61      *
  62      * This method is an optimization for use cases where ROM dataspaces
  63      * are updated at a high rate. In such cases, requesting a new
  64      * dataspace for each update induces a large overhead because
  65      * memory mappings must be revoked and updated (e.g., handling the
  66      * page faults referring to the dataspace). If the updated content
  67      * fits in the existing dataspace, those costly operations can be
  68      * omitted.
  69      *
  70      * When this method is called, the server may replace the dataspace
  71      * content with new data.
  72      *
  73      * \return true if the existing dataspace contains up-to-date content,
  74      *         or false if a new dataspace must be requested via the
  75      *         `dataspace` method
  76      */
  77     virtual bool update() { return false; }
  78  
  79     /**
  80      * Register signal handler to be notified of ROM data changes
  81      *
  82      * The ROM session interface allows for the implementation of ROM
  83      * services that dynamically update the data exported as ROM dataspace
  84      * during the lifetime of the session. This is useful in scenarios
  85      * where this data is generated rather than originating from a static
  86      * file, for example to update a program`s configuration at runtime.
  87      *
  88      * By installing a signal handler using the `sigh()` method, the
  89      * client will receive a notification each time the data changes at the
  90      * server. From the client`s perspective, the original data contained
  91      * in the currently used dataspace remains unchanged until the client
  92      * calls `dataspace()` the next time.
  93      */
  94     virtual void sigh(Signal_context_capability sigh) = 0;
  95  
  96  
  97     /*********************
  98      ** RPC declaration **
  99      *********************/
 100  
 101     GENODE_RPC(Rpc_dataspace, Rom_dataspace_capability, dataspace);
 102     GENODE_RPC(Rpc_sigh, void, sigh, Signal_context_capability);
 103     GENODE_RPC(Rpc_update, bool, update);
 104  
 105     GENODE_RPC_INTERFACE(Rpc_dataspace, Rpc_update, Rpc_sigh);
 106  };
 107  
 108  #endif /* _INCLUDE__ROM_SESSION__ROM_SESSION_H_ */