L4Re - L4 Runtime Environment
mem_alloc
Go to the documentation of this file.
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 
35 namespace L4Re {
36 class 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  */
61 class L4_EXPORT Mem_alloc :
62  public L4::Kobject_t<Mem_alloc, L4::Factory, L4::PROTO_EMPTY>
63 {
64 public:
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 (granularity
82  * is (super)pages and the size is rounded up to this
83  * granularity). If `size` is a negative value and `flags`
84  * set the Mem_alloc_flags::Continuous bit the
85  * allocator tries to allocate as much memory as possible
86  * leaving an amount of at least `-size` bytes within the
87  * associated quota.
88  * \param[out] mem Capability slot where the capability to the
89  * dataspace is received.
90  * \param flags Special dataspace properties, see #Mem_alloc_flags
91  * \param align Log2 alignment of dataspace if supported by allocator,
92  * will be at least L4_PAGESHIFT,
93  * with Super_pages flag set at least L4_SUPERPAGESHIFT
94  *
95  * \retval 0 Success
96  * \retval -L4_ERANGE Given size not supported.
97  * \retval -L4_ENOMEM Not enough memory available.
98  * \retval <0 IPC error
99  */
100  long alloc(long size, L4::Cap<Dataspace> mem,
101  unsigned long flags = 0, unsigned long align = 0) const throw();
102 
103  /**
104  * Free dataspace.
105  *
106  * \param mem Dataspace to be released.
107  *
108  * \retval 0
109  *
110  * \deprecated This function is an empty stub which remains here
111  * for backward compatibility only.
112  * Use `L4::Task::unmap(mem, L4_FP_DELETE_OBJ)` or other
113  * similar means to remove a dataspace.
114  */
115  /* Deprecation message added Q4 2016 */
116  long free(L4::Cap<Dataspace> mem) const throw()
117  L4_DEPRECATED("This function is an empty stub and remains for backward compatibility only. Check documentation for details.");
118 
119 };
120 
121 };