1// -*- Mode: C++ -*-
2// vim:ft=cpp
3/**
4 * \file
5 * \brief   Memory allocator interface
6 */
7/*
8 * Copyright (C) 2015 Kernkonzept GmbH.
9 * Author(s): Alexander Warg <alexander.warg@kernkonzept.com>
10 */
11/*
12 * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
13 *               Alexander Warg <warg@os.inf.tu-dresden.de>,
14 *               Torsten Frenzel <frenzel@os.inf.tu-dresden.de>
15 *     economic rights: Technische Universität Dresden (Germany)
16 *
17 * This file is part of TUD:OS and distributed under the terms of the
18 * GNU General Public License 2.
19 * Please see the COPYING-GPL-2 file for details.
20 *
21 * As a special exception, you may use this file as part of a free software
22 * library without restriction.  Specifically, if other files instantiate
23 * templates or use macros or inline functions from this file, or you compile
24 * this file and link it with other files to produce an executable, this
25 * file does not by itself cause the resulting executable to be covered by
26 * the GNU General Public License.  This exception does not however
27 * invalidate any other reasons why the executable file might be covered by
28 * the GNU General Public License.
29 */
30#pragma once
31
32#include <l4/sys/capability>
33#include <l4/sys/factory>
34
35namespace L4Re {
36class Dataspace;
37
38// MISSING:
39// * alignment constraints
40// * shall we support superpages in noncont memory?
41
42/**
43 * Memory allocation interface.
44 *
45 * The memory-allocator API is the basic API to allocate memory from the
46 * L4Re subsystem. The memory is allocated in terms of dataspaces (see
47 * L4Re::Dataspace). The provided dataspaces have at least the
48 * property that data written to such a dataspace is available as long
49 * as the dataspace is not freed or the data is not overwritten. In particular,
50 * the memory backing a dataspace from an allocator need not be allocated
51 * instantly, but may be allocated lazily on demand.
52 *
53 * A memory allocator can provide dataspaces with additional properties,
54 * such as physically contiguous memory, pre-allocated memory, or pinned
55 * memory. To request memory with an additional property the
56 * L4Re::Mem_alloc::alloc() method provides a flags parameter. If the
57 * concrete implementation of a memory allocator does not support or allow
58 * allocation of memory with a certain property, the allocation may be
59 * refused.
60 */
61class L4_EXPORT Mem_alloc :
62  public L4::Kobject_t<Mem_alloc, L4::Factory, L4::PROTO_EMPTY>
63{
64public:
65  /**
66   * Flags for the allocator.
67   *
68   * They describe requested properties of the allocated memory.
69   * Support of these properties by the dataspace provider is optional.
70   */
71  enum Mem_alloc_flags
72  {
73    Continuous   = 0x01,  ///< Allocate physically contiguous memory
74    Pinned       = 0x02,  ///< Deprecated, use L4Re::Dma_space instead
75    Super_pages  = 0x04,  ///< Allocate super pages
76  };
77
78  /**
79   * Allocate anonymous memory.
80   *
81   * \param      size   Size in bytes to be requested. Allocation
82   *                    granularity is (super)pages, however, the allocator
83   *                    will store the byte-granular given size as the size
84   *                    of the dataspace and consecutively will use this
85   *                    byte-granular size for servicing the dataspace.
86   *                    Allocators may optionally also implement a maximum
87   *                    allocation strategy: if `size` is a negative value and
88   *                    `flags` set the Mem_alloc_flags::Continuous bit, the
89   *                    allocator tries to allocate as much memory as possible
90   *                    leaving an amount of at least `-size` bytes within the
91   *                    associated quota.
92   * \param[out] mem    Capability slot where the capability to the
93   *                    dataspace is received.
94   * \param      flags  Special dataspace properties, see #Mem_alloc_flags
95   * \param      align  Log2 alignment of dataspace if supported by allocator,
96   *                    will be at least L4_PAGESHIFT,
97   *                    with Super_pages flag set at least L4_SUPERPAGESHIFT
98   *
99   * \retval 0           Success
100   * \retval -L4_ERANGE  Given size not supported.
101   * \retval -L4_ENOMEM  Not enough memory available.
102   * \retval <0          IPC error
103   */
104  long alloc(long size, L4::Cap<Dataspace> mem,
105             unsigned long flags = 0, unsigned long align = 0) const noexcept;
106};
107
108};
109