l4/pkg/l4re/include/mem_alloc

   1 // -*- Mode: C++ -*-
   2 // vim:ft=cpp
   3 /**
   4  * \file
   5  * \brief   Memory allocator interface
   6  */
   7 /*
   8  * (c) 2008-2009 Technische Universität Dresden
   9  * This file is part of TUD:OS and distributed under the terms of the
  10  * GNU General Public License 2.
  11  * Please see the COPYING-GPL-2 file for details.
  12  *
  13  * As a special exception, you may use this file as part of a free software
  14  * library without restriction.  Specifically, if other files instantiate
  15  * templates or use macros or inline functions from this file, or you compile
  16  * this file and link it with other files to produce an executable, this
  17  * file does not by itself cause the resulting executable to be covered by
  18  * the GNU General Public License.  This exception does not however
  19  * invalidate any other reasons why the executable file might be covered by
  20  * the GNU General Public License.
  21  */
  22 #pragma once
  23
  24 #include <l4/sys/capability>
  25 #include <l4/re/protocols>
  26
  27 namespace L4Re {
  28 class Dataspace;
  29
  30 // MISSING:
  31 // * alignment constraints
  32 // * shall we support superpages in noncont memory?
  33
  34 /**
  35  * \defgroup api_l4re_mem_alloc Memory allocator API
  36  * \ingroup api_l4re
  37  * \brief Memory-allocator interface.
  38  *
  39  * The memory-allocator API is the basic API to allocate memory from the
  40  * L4Re subsystem. The memory is allocated in terms of data spaces (see
  41  * L4Re::Dataspace). The provided data spaces have at least the
  42  * property that data written to such a data space is available as long
  43  * as the data space is not freed or the data is not overwritten. In particular,
  44  * the memory backing a data space from an allocator need not be allocated
  45  * instantly, but may be allocated lazily on demand.
  46  *
  47  * A memory allocator can provide data spaces with a additional properties,
  48  * such as physically contiguous memory, pre-allocated memory, or pinned
  49  * memory. To request memory with an additional property the
  50  * L4Re::Mem_alloc::alloc() method provides a flags parameter. If the
  51  * concrete implementation of a memory allocator does not support or allow
  52  * allocation of memory with a certain property, the allocation may be
  53  * refused.
  54  *
  55  * The main interface is defined by the class L4Re::Mem_alloc.
  56  */
  57
  58 /**
  59  * \brief Memory allocator.
  60  * \ingroup api_l4re_mem_alloc
  61  *
  62  * Memory-allocator interface, for more information see
  63  * \link api_l4re_mem_alloc Memory-allocator API \endlink.
  64  */
  65 class L4_EXPORT Mem_alloc :
  66   public L4::Kobject_t<Mem_alloc, L4::Kobject, L4Re::Protocol::Mem_alloc>
  67 {
  68   L4_KOBJECT(Mem_alloc)
  69
  70 public:
  71   /**
  72    * \brief Flags for the allocator
  73    */
  74   enum Mem_alloc_flags
  75   {
  76     Continuous   = 0x01, ///< Allocate physically contiguous data space, if supported by the allocator
  77     Pinned       = 0x02, ///< Allocate pinned data space, if supported by the allocator
  78     Super_pages  = 0x04, ///< Allocate super pages, if supported by the allocator
  79   };
  80   /**
  81    * \brief Allocate anonymous memory.
  82    *
  83    * \param size  Size to be requested in bytes (granularity
  84    *               is (super)pages and the size is rounded up to this
  85    *               granularity).
  86    * \param mem   Object capability for the data space to be allocated.
  87    * \param flags Flags, see #Mem_alloc_flags, default none
  88    *
  89    * \return 0 on success, <0 on error
  90    *         - -#L4_ENOMEM
  91    *         - IPC errors
  92    */
  93   long alloc(unsigned long size, L4::Cap<Dataspace> mem,
  94              unsigned long flags = 0) const throw();
  95   /**
  96    * \brief Free data space.
  97    *
  98    * \param mem  Data space that contains the memory.
  99    *
 100    * \return 0 on success, <0 on error
 101    *         - -#L4_EINVAL
 102    *         - IPC errors
 103    */
 104   long free(L4::Cap<Dataspace> mem) const throw();
 105
 106 };
 107
 108 };