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