// -*- Mode: C++ -*-
// vim:ft=cpp
/**
 * \file
 * \brief   Memory allocator interface
 */
/*
 * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
 *               Alexander Warg <warg@os.inf.tu-dresden.de>,
 *               Torsten Frenzel <frenzel@os.inf.tu-dresden.de>
 *     economic rights: Technische Universität Dresden (Germany)
 *
 * This file is part of TUD:OS and distributed under the terms of the
 * GNU General Public License 2.
 * Please see the COPYING-GPL-2 file for details.
 *
 * As a special exception, you may use this file as part of a free software
 * library without restriction.  Specifically, if other files instantiate
 * templates or use macros or inline functions from this file, or you compile
 * this file and link it with other files to produce an executable, this
 * file does not by itself cause the resulting executable to be covered by
 * the GNU General Public License.  This exception does not however
 * invalidate any other reasons why the executable file might be covered by
 * the GNU General Public License.
 */
#pragma once

#include <l4/sys/capability>
#include <l4/re/protocols>

namespace L4Re {
class Dataspace;

// MISSING:
// * alignment constraints
// * shall we support superpages in noncont memory?

/**
 * \defgroup api_l4re_mem_alloc Memory allocator API
 * \ingroup api_l4re
 * \brief Memory-allocator interface.
 *
 * The memory-allocator API is the basic API to allocate memory from the
 * L4Re subsystem. The memory is allocated in terms of data spaces (see
 * L4Re::Dataspace). The provided data spaces have at least the
 * property that data written to such a data space is available as long
 * as the data space is not freed or the data is not overwritten. In particular,
 * the memory backing a data space from an allocator need not be allocated
 * instantly, but may be allocated lazily on demand.
 *
 * A memory allocator can provide data spaces with a additional properties,
 * such as physically contiguous memory, pre-allocated memory, or pinned
 * memory. To request memory with an additional property the
 * L4Re::Mem_alloc::alloc() method provides a flags parameter. If the
 * concrete implementation of a memory allocator does not support or allow
 * allocation of memory with a certain property, the allocation may be
 * refused.
 *
 * The main interface is defined by the class L4Re::Mem_alloc.
 */

/**
 * \brief Memory allocator.
 * \ingroup api_l4re_mem_alloc
 *
 * Memory-allocator interface, for more information see
 * \link api_l4re_mem_alloc Memory-allocator API \endlink.
 */
class L4_EXPORT Mem_alloc :
  public L4::Kobject_t<Mem_alloc, L4::Kobject, L4Re::Protocol::Mem_alloc>
{
  L4_KOBJECT(Mem_alloc)

public:
  /**
   * \brief Flags for the allocator
   */
  enum Mem_alloc_flags
  {
    Continuous   = 0x01, ///< Allocate physically contiguous data space, if supported by the allocator
    Pinned       = 0x02, ///< Allocate pinned data space, if supported by the allocator
    Super_pages  = 0x04, ///< Allocate super pages, if supported by the allocator
  };

  /**
   * \brief Allocate anonymous memory.
   *
   * \param size  Size to be requested in bytes (granularity
   *               is (super)pages and the size is rounded up to this
   *               granularity).
   * \param mem   Object capability for the data space to be allocated.
   * \param flags Flags, see #Mem_alloc_flags, default none
   * \param align Log2 alignment of dataspace if supported by allocator,
   *              will be at least L4_PAGESHIFT,
   *              with Super_pages flag set at least L4_SUPERPAGESHIFT,
   *              default 0
   *
   * \return 0 on success, <0 on error
   *         - -#L4_ENOMEM
   *         - IPC errors
   */
  long alloc(unsigned long size, L4::Cap<Dataspace> mem,
             unsigned long flags = 0, unsigned long align = 0) const throw();
  /**
   * \brief Free data space.
   *
   * \param mem  Data space that contains the memory.
   *
   * \return 0 on success, <0 on error
   *         - -#L4_EINVAL
   *         - IPC errors
   */
  long free(L4::Cap<Dataspace> mem) const throw();

};

};