1  /*
   2   * \brief  Region manager session interface
   3   * \author Norman Feske
   4   * \date   2006-05-15
   5   */
   6  
   7  /*
   8   * Copyright (C) 2006-2010 Genode Labs GmbH
   9   *
  10   * This file is part of the Genode OS framework, which is distributed
  11   * under the terms of the GNU General Public License version 2.
  12   */
  13  
  14  #ifndef _INCLUDE__RM_SESSION__RM_SESSION_H_
  15  #define _INCLUDE__RM_SESSION__RM_SESSION_H_
  16  
  17  #include <base/exception.h>
  18  #include <base/stdint.h>
  19  #include <base/signal.h>
  20  #include <dataspace/capability.h>
  21  #include <thread/capability.h>
  22  #include <pager/capability.h>
  23  
  24  namespace Genode {
  25  
  26     class Rm_session
  27     {
  28        protected:
  29  
  30           enum Opcode { ATTACH, DETACH, ADD_CLIENT, FAULT_HANDLER, STATE, DATASPACE };
  31  
  32        public:
  33  
  34           enum Fault_type {
  35              READY = 0, READ_FAULT = 1, WRITE_FAULT = 2, EXEC_FAULT = 3
  36           };
  37  
  38           /**
  39            * State of region-manager session
  40            *
  41            * If a client accesses a location outside the regions attached to
  42            * the region-manager session, a fault occurs and gets signalled to
  43            * the registered fault handler. The fault handler, in turn needs
  44            * the information about the fault address and fault type to
  45            * resolve the fault. This information is represented by this
  46            * structure.
  47            */
  48           struct State
  49           {
  50              /**
  51               * Type of occurred fault
  52               */
  53              Fault_type type;
  54  
  55              /**
  56               * Fault address
  57               */
  58              addr_t addr;
  59  
  60              /**
  61               * Default constructor
  62               */
  63              State() : type(READY), addr(0) { }
  64  
  65              /**
  66               * Constructor
  67               */
  68              State(Fault_type fault_type, addr_t fault_addr) :
  69                 type(fault_type), addr(fault_addr) { }
  70           };
  71  
  72           static const char *service_name() { return "RM"; }
  73  
  74  
  75           /*********************
  76            ** Exception types **
  77            *********************/
  78  
  79           class Attach_failed     : public Exception         { };
  80           class Invalid_dataspace : public Attach_failed     { };
  81           class Region_conflict   : public Attach_failed     { };
  82  
  83           class Invalid_thread    : public Exception { };
  84           class Out_of_memory     : public Exception { };
  85  
  86  
  87           /**
  88            * Destructor
  89            */
  90           virtual ~Rm_session() { }
  91  
  92           /**
  93            * Map dataspace into local address space
  94            *
  95            * \param ds              capability of dataspace to map
  96            * \param size            size of the locally mapped region
  97            *                        default (0) is the whole dataspace
  98            * \param offset          start at offset in dataspace
  99            * \param use_local_addr  if set to true, attach the dataspace at
 100            *                        the specified `local_addr`
 101            * \param local_addr      local destination address
 102            *
 103            * \throw Attach_failed   if dataspace is invalid
 104            *                        or on region conflict
 105            *
 106            * \return                local address of mapped dataspace
 107            *
 108            */
 109           virtual void *attach(Dataspace_capability ds,
 110                                size_t size = 0, off_t offset = 0,
 111                                bool use_local_addr = false,
 112                                addr_t local_addr = 0) = 0;
 113  
 114           /**
 115            * Shortcut for attaching a dataspace at a predefined local address
 116            */
 117           void *attach_at(Dataspace_capability ds, addr_t local_addr,
 118                           size_t size = 0, off_t offset = 0) {
 119              return attach(ds, size, offset, true, local_addr); }
 120  
 121           /**
 122            * Remove region from local address space
 123            */
 124           virtual void detach(void *local_addr) = 0;
 125  
 126           /**
 127            * Add client to pager
 128            *
 129            * \param thread  thread that will be paged
 130            * \throw         Invalid_thread
 131            * \throw         Out_of_memory
 132            * \return        capability to be used for handling page faults
 133            *
 134            * This method must be called at least once to establish a valid
 135            * communication channel between the pager part of the region manager
 136            * and the client thread.
 137            */
 138           virtual Pager_capability add_client(Thread_capability thread) = 0;
 139  
 140           /**
 141            * Register signal handler for region-manager faults
 142            */
 143           virtual void fault_handler(Signal_context_capability handler) = 0;
 144  
 145           /**
 146            * Request current state of RM session
 147            */
 148           virtual State state() = 0;
 149  
 150           /**
 151            * Return dataspace representation of region-manager session
 152            */
 153           virtual Dataspace_capability dataspace() = 0;
 154     };
 155  }
 156  
 157  #endif /* _INCLUDE__RM_SESSION__RM_SESSION_H_ */
© 2010 Genode Labs