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