1  /*
   2   * \brief  RAM session interface
   3   * \author Norman Feske
   4   * \date   2006-05-11
   5   */
   6  
   7  /*
   8   * Copyright (C) 2006-2013 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__RAM_SESSION__RAM_SESSION_H_
  15  #define _INCLUDE__RAM_SESSION__RAM_SESSION_H_
  16  
  17  #include <base/stdint.h>
  18  #include <base/capability.h>
  19  #include <base/exception.h>
  20  #include <base/cache.h>
  21  #include <dataspace/capability.h>
  22  #include <ram_session/capability.h>
  23  #include <session/session.h>
  24  
  25  namespace Genode {
  26  
  27     struct Ram_dataspace;
  28     typedef Capability<Ram_dataspace> Ram_dataspace_capability;
  29  
  30     struct Ram_session;
  31  }
  32  
  33  
  34  struct Genode::Ram_dataspace : Dataspace { };
  35  
  36  
  37  /**
  38   * RAM session interface
  39   */
  40  struct Genode::Ram_session : Session
  41  {
  42     static const char *service_name() { return "RAM"; }
  43  
  44  
  45     /*********************
  46      ** Exception types **
  47      *********************/
  48  
  49     class Alloc_failed    : public Exception    { };
  50     class Quota_exceeded  : public Alloc_failed { };
  51     class Out_of_metadata : public Alloc_failed { };
  52  
  53     /**
  54      * Destructor
  55      */
  56     virtual ~Ram_session() { }
  57  
  58     /**
  59      * Allocate RAM dataspace
  60      *
  61      * \param  size    size of RAM dataspace
  62      * \param  cached  selects cacheability attributes of the memory,
  63      *                 uncached memory, i.e., for DMA buffers
  64      *
  65      * \throw  Quota_exceeded
  66      * \throw  Out_of_metadata
  67      * \return capability to new RAM dataspace
  68      */
  69     virtual Ram_dataspace_capability alloc(size_t size,
  70                                            Cache_attribute cached = CACHED) = 0;
  71  
  72     /**
  73      * Free RAM dataspace
  74      *
  75      * \param ds  dataspace capability as returned by alloc
  76      */
  77     virtual void free(Ram_dataspace_capability ds) = 0;
  78  
  79     /**
  80      * Define reference account for the RAM session
  81      *
  82      * \param   ram_session    reference account
  83      *
  84      * \return  0 on success
  85      *
  86      * Each RAM session requires another RAM session as reference
  87      * account to transfer quota to and from. The reference account can
  88      * be defined only once.
  89      */
  90     virtual int ref_account(Ram_session_capability ram_session) = 0;
  91  
  92     /**
  93      * Transfer quota to another RAM session
  94      *
  95      * \param ram_session  receiver of quota donation
  96      * \param amount       amount of quota to donate
  97      * \return             0 on success
  98      *
  99      * Quota can only be transfered if the specified RAM session is
 100      * either the reference account for this session or vice versa.
 101      */
 102     virtual int transfer_quota(Ram_session_capability ram_session, size_t amount) = 0;
 103  
 104     /**
 105      * Return current quota limit
 106      */
 107     virtual size_t quota() = 0;
 108  
 109     /**
 110      * Return used quota
 111      */
 112     virtual size_t used() = 0;
 113  
 114     /**
 115      * Return amount of available quota
 116      */
 117     size_t avail()
 118     {
 119        size_t q = quota(), u = used();
 120        return q > u ? q - u : 0;
 121     }
 122  
 123  
 124     /*********************
 125      ** RPC declaration **
 126      *********************/
 127  
 128     GENODE_RPC_THROW(Rpc_alloc, Ram_dataspace_capability, alloc,
 129                      GENODE_TYPE_LIST(Quota_exceeded, Out_of_metadata),
 130                      size_t, Cache_attribute);
 131     GENODE_RPC(Rpc_free, void, free, Ram_dataspace_capability);
 132     GENODE_RPC(Rpc_ref_account, int, ref_account, Ram_session_capability);
 133     GENODE_RPC(Rpc_transfer_quota, int, transfer_quota, Ram_session_capability, size_t);
 134     GENODE_RPC(Rpc_quota, size_t, quota);
 135     GENODE_RPC(Rpc_used, size_t, used);
 136  
 137     GENODE_RPC_INTERFACE(Rpc_alloc, Rpc_free, Rpc_ref_account,
 138                          Rpc_transfer_quota, Rpc_quota, Rpc_used);
 139  };
 140  
 141  #endif /* _INCLUDE__RAM_SESSION__RAM_SESSION_H_ */