1 /**
2 * \file
3 * \brief Memory allocator C interface
4 */
5 /*
6 * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>
7 * economic rights: Technische Universität Dresden (Germany)
8 *
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/re/env.h>
25 #include <l4/sys/consts.h>
26
27 #include <l4/re/c/dataspace.h>
28
29 /**
30 * \defgroup api_l4re_c_mem_alloc Memory allocator
31 * \ingroup api_l4re_c
32 * \brief Memory allocator C interface.
33 */
34
35 EXTERN_C_BEGIN
36
37 /**
38 * \brief Flags for requesting memory at the memory allocator.
39 * \ingroup api_l4re_c_mem_alloc
40 * \see L4Re::Mem_alloc::Mem_alloc_flags
41 */
42 enum l4re_ma_flags {
43 L4RE_MA_CONTINUOUS = 0x01,
44 L4RE_MA_PINNED = 0x02,
45 L4RE_MA_SUPER_PAGES = 0x04,
46 };
47
48
49 /**
50 * \brief Allocate memory
51 * \ingroup api_l4re_c_mem_alloc
52 *
53 * \param size Size in bytes to be requested. Allocation
54 * granularity is (super)pages, however, the allocator
55 * will store the byte-granular given size as the size
56 * of the dataspace and consecutively will use this
57 * byte-granular size for servicing the dataspace.
58 * Allocators may optionally also implement a maximum allocation
59 * strategy: if `size` is a negative value and `flags`
60 * set the Mem_alloc_flags::Continuous bit, the
61 * allocator tries to allocate as much memory as possible
62 * leaving an amount of at least `-size` bytes within the
63 * associated quota.
64 * \param mem Capability slot where the capability to the
65 * dataspace is received.
66 * \param flags Special dataspace properties, see #l4re_ma_flags
67 *
68 * \retval 0 Success
69 * \retval -L4_ERANGE Given size not supported.
70 * \retval -L4_ENOMEM Not enough memory available.
71 * \retval <0 IPC error
72 *
73 * \see L4Re::Mem_alloc::alloc
74 *
75 * The memory allocator returns a dataspace.
76 *
77 * \note This function is using the L4Re::Env::env()->mem_alloc() service.
78 */
79 L4_CV L4_INLINE long
80 l4re_ma_alloc(long size, l4re_ds_t const mem,
81 unsigned long flags) L4_NOTHROW;
82
83 /**
84 * \brief Allocate memory
85 * \ingroup api_l4re_c_mem_alloc
86 *
87 * \param size Size in bytes to be requested. Allocation
88 * granularity is (super)pages, however, the allocator
89 * will store the byte-granular given size as the size
90 * of the dataspace and consecutively will use this
91 * byte-granular size for servicing the dataspace.
92 * Allocators may optionally also implement a maximum allocation
93 * strategy: if `size` is a negative value and `flags`
94 * set the Mem_alloc_flags::Continuous bit, the
95 * allocator tries to allocate as much memory as possible
96 * leaving an amount of at least `-size` bytes within the
97 * associated quota.
98 * \param mem Capability slot where the capability to the
99 * dataspace is received.
100 * \param flags Special dataspace properties, see #l4re_ma_flags
101 * \param align Log2 alignment of dataspace if supported by allocator,
102 * will be at least L4_PAGESHIFT,
103 * with Super_pages flag set at least L4_SUPERPAGESHIFT
104 *
105 * \retval 0 Success
106 * \retval -L4_ERANGE Given size not supported.
107 * \retval -L4_ENOMEM Not enough memory available.
108 * \retval <0 IPC error
109 *
110 * \see L4Re::Mem_alloc::alloc and \see l4re_ma_alloc
111 *
112 * The memory allocator returns a dataspace.
113 *
114 * \note This function is using the L4Re::Env::env()->mem_alloc() service.
115 */
116 L4_CV L4_INLINE long
117 l4re_ma_alloc_align(long size, l4re_ds_t const mem,
118 unsigned long flags, unsigned long align) L4_NOTHROW;
119
120 /**
121 * \brief Allocate memory.
122 * \ingroup api_l4re_c_mem_alloc
123 *
124 * \param srv Memory allocator service.
125 * \param size Size to be requested.
126 * \param mem Capability slot to put the requested dataspace in
127 * \param flags Flags, see #l4re_ma_flags
128 * \param align Log2 alignment of dataspace if supported by allocator,
129 * will be at least L4_PAGESHIFT,
130 * with Super_pages flag set at least L4_SUPERPAGESHIFT,
131 * default 0
132 * \return 0 on success, <0 on error
133 *
134 * \see L4Re::Mem_alloc::alloc
135 *
136 * The memory allocator returns a dataspace.
137 */
138 L4_CV long
139 l4re_ma_alloc_align_srv(l4_cap_idx_t srv, long size,
140 l4re_ds_t const mem, unsigned long flags,
141 unsigned long align) L4_NOTHROW;
142
143 /***************** Implementation *****************/
144
145 L4_CV L4_INLINE long
l4re_ma_alloc(long size,l4re_ds_t const mem,unsigned long flags)146 l4re_ma_alloc(long size, l4re_ds_t const mem,
147 unsigned long flags) L4_NOTHROW
148 {
149 return l4re_ma_alloc_align_srv(l4re_global_env->mem_alloc, size, mem,
150 flags, 0);
151 }
152
153 L4_CV L4_INLINE long
l4re_ma_alloc_align(long size,l4re_ds_t const mem,unsigned long flags,unsigned long align)154 l4re_ma_alloc_align(long size, l4re_ds_t const mem,
155 unsigned long flags, unsigned long align) L4_NOTHROW
156 {
157 return l4re_ma_alloc_align_srv(l4re_global_env->mem_alloc, size, mem,
158 flags, align);
159 }
160
161 EXTERN_C_END
162