L4Re - L4 Runtime Environment
dataspace
Go to the documentation of this file.
1 // -*- Mode: C++ -*-
2 // vim:ft=cpp
3 /**
4  * \file
5  * Dataspace 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  * Björn Döbel <doebel@os.inf.tu-dresden.de>,
11  * Torsten Frenzel <frenzel@os.inf.tu-dresden.de>
12  * economic rights: Technische Universität Dresden (Germany)
13  *
14  * This file is part of TUD:OS and distributed under the terms of the
15  * GNU General Public License 2.
16  * Please see the COPYING-GPL-2 file for details.
17  *
18  * As a special exception, you may use this file as part of a free software
19  * library without restriction. Specifically, if other files instantiate
20  * templates or use macros or inline functions from this file, or you compile
21  * this file and link it with other files to produce an executable, this
22  * file does not by itself cause the resulting executable to be covered by
23  * the GNU General Public License. This exception does not however
24  * invalidate any other reasons why the executable file might be covered by
25  * the GNU General Public License.
26  */
27 
28 #pragma once
29 
30 #include <l4/sys/types.h>
31 #include <l4/sys/l4int.h>
32 #include <l4/sys/capability>
33 #include <l4/re/protocols.h>
34 #include <l4/sys/cxx/ipc_types>
35 #include <l4/sys/cxx/ipc_iface>
36 
37 namespace L4Re
38 {
39 
40  // MISSING:
41  // * size support in map, mapped size in reply
42 
43 /**
44  * Interface for memory-like objects.
45  *
46  * Dataspaces are a central abstraction provided by L4Re. A dataspace is
47  * an abstraction for any thing that is available via usual memory access
48  * instructions. A dataspace can be a file, as well as the memory-mapped
49  * registers of a device, or anonymous memory, such as a heap.
50  *
51  * The dataspace interface defines a set of methods that allow any kind
52  * of dataspace to be attached (mapped) to the virtual address space of
53  * an L4 task and then be accessed via memory-access instructions.
54  * The L4Re::Rm interface can be used to attach a dataspace to a
55  * virtual address space of a task paged by a certain instance of a region map.
56  *
57  * \includefile{l4/re/dataspace}
58  */
59 class L4_EXPORT Dataspace :
60  public L4::Kobject_t<Dataspace, L4::Kobject, L4RE_PROTO_DATASPACE,
61  L4::Type_info::Demand_t<1> >
62 {
63 public:
64 
65  /**
66  * Flags for map operations.
67  */
68  enum Map_flags
69  {
70  Map_ro = 0, ///< Request read-only mapping.
71  Map_rw = 1, ///< Request writable mapping.
72 
73  Map_normal = 0x00, ///< request normal memory mapping
74  Map_cacheable = Map_normal, ///< request normal memory mapping
75  Map_bufferable = 0x10, ///< request bufferable (write buffered) mappings
76  Map_uncacheable = 0x20, ///< request uncacheable memory mappings
77 
78  Map_caching_mask = 0x30, ///< mask for caching flags
79  Map_caching_shift = 4, ///< shift value for caching flags
80  };
81 
82  /**
83  * Information about the dataspace.
84  */
85  struct Stats {
86  unsigned long size; ///< size
87  unsigned long flags; ///< flags
88  };
89 
90 
91  /**
92  * Request a flex-page mapping from the dataspace.
93  *
94  * \param offset Offset to start within dataspace
95  * \param flags map flags, see #Map_flags.
96  * \param local_addr Local address to map to.
97  * \param min_addr Defines start of receive window.
98  * (Rounded down to page size.)
99  * \param max_addr Defines end of receive window.
100  * (Rounded up to page size.)
101  *
102  * \retval L4_EOK Success
103  * \retval -L4_ERANGE Invalid offset.
104  * \retval -L4_EPERM Insufficient permission to map with requested rights.
105  * \retval <0 IPC errors
106  *
107  * The map call will attempt to map the largest possible flexpage that
108  * covers the given local address and still fits into the region
109  * defined by `min_addr` and `max_addr`. If the given region is
110  * invalid or does not overlap the local address, the smallest valid
111  * page size is used.
112  */
113  long map(l4_addr_t offset, unsigned long flags, l4_addr_t local_addr,
114  l4_addr_t min_addr, l4_addr_t max_addr) const throw();
115 
116  /**
117  * Map a part of a dataspace completely.
118  *
119  * \param offset Offset to start within dataspace
120  * \param flags map flags, see #Map_flags.
121  * \param min_addr Defines start of receive window.
122  * (Rounded down to page size.)
123  * \param max_addr Defines end of receive window.
124  * (Rounded up to page size.)
125  *
126  * \retval L4_EOK Success
127  * \retval -L4_ERANGE Invalid offset.
128  * \retval -L4_EPERM Insufficient permission to map with requested rights.
129  * \retval <0 IPC errors
130  */
131  long map_region(l4_addr_t offset, unsigned long flags,
132  l4_addr_t min_addr, l4_addr_t max_addr) const throw();
133 
134  /**
135  * Clear parts of a dataspace.
136  *
137  * \param offset Offset within dataspace (in bytes).
138  * \param size Size of region to clear (in bytes).
139  *
140  * \retval >=0 Success.
141  * \retval -L4_ERANGE Given range is outside the dataspace.
142  * (A dataspace provider may also silently ignore areas
143  * outside the dataspace.)
144  * \retval -L4_EACCESS Dataspace is read-only.
145  * \retval <0 IPC errors
146  *
147  * Zeroes out the memory. Depending on the type of memory
148  * the memory could also be deallocated and replaced by
149  * a shared zero-page.
150  */
151  L4_RPC(long, clear, (l4_addr_t offset, unsigned long size));
152 
153  /**
154  * Allocate a range in the dataspace.
155  *
156  * \param offset Offset in the dataspace, in bytes.
157  * \param size Size of the range, in bytes.
158  *
159  * \retval L4_EOK Success
160  * \retval -L4_ERANGE Given range is outside the dataspace.
161  * (A dataspace provider may also silently ignore areas
162  * outside the dataspace.)
163  * \retval -L4_ENOMEM Not enough memory available.
164  * \retval <0 IPC errors
165  *
166  * On success, at least the given range is guaranteed to be allocated. The
167  * dataspace manager may also allocate more memory due to page granularity.
168  *
169  * The memory is allocated with the same rights as the dataspace
170  * capability.
171  */
172  L4_RPC(long, allocate, (l4_addr_t offset, l4_size_t size));
173 
174  /**
175  * Copy contents from another dataspace.
176  *
177  * \param dst_offs Offset in destination dataspace.
178  * \param src Source dataspace to copy from.
179  * \param src_offs Offset in the source dataspace.
180  * \param size Size to copy (in bytes).
181  *
182  * \retval L4_EOK Success
183  * \retval -L4_EACCESS Destination dataspace not writable.
184  * \retval -L4_EINVAL Invalid parameter supplied.
185  * \retval <0 IPC errors
186  *
187  * The copy operation may use copy-on-write mechanisms. The operation may
188  * also fail if both dataspaces are not from the same dataspace manager
189  * or the dataspace managers do not cooperate.
190  */
191  L4_RPC(long, copy_in, (l4_addr_t dst_offs, L4::Ipc::Cap<Dataspace> src,
192  l4_addr_t src_offs, unsigned long size));
193 
194 
195  /**
196  * Get the physical addresses of a dataspace.
197  *
198  * \param offset Offset in dataspace
199  * \retval phys_addr Physical address.
200  * \retval phys_size Size of largest physically contiguous region
201  * in the dataspace after `phys_addr` (in bytes).
202  *
203  * \retval L4_EOK Success
204  * \retval -L4_EINVAL Dataspace is not pinned.
205  * \retval <0 IPC errors
206  *
207  * This call will only succeed on pinned memory dataspaces.
208  *
209  * \deprecated Use L4Re::Dma_space instead. This function will be removed
210  * in future releases.
211  */
212  L4_RPC(long, phys, (l4_addr_t offset, l4_addr_t &phys_addr, l4_size_t &phys_size));
213 
214  /**
215  * Get size of a dataspace.
216  *
217  * \return Size of the dataspace in bytes.
218  */
219  unsigned long size() const throw();
220 
221  /**
222  * Get flags of the dataspace.
223  *
224  * \retval >=0 Flags of the dataspace
225  * \retval <0 IPC errors
226  *
227  * \see L4Re::Dataspace::Map_flags
228  */
229  long flags() const throw();
230 
231  /**
232  * Get information on the dataspace.
233  *
234  * \param[out] stats Dataspace information
235  *
236  * \retval 0 Success
237  * \retval <0 IPC errors
238  */
239  L4_RPC(long, info, (Stats *stats));
240 
241  /**
242  * \internal
243  * Take operation.
244  * \return 0 on success, <0 on errors
245  * - IPC errors
246  *
247  * \deprecated Dataspaces exist as long as a capability
248  * on the dataspace exists.
249  */
250  L4_RPC(long, take, ());
251 
252  /**
253  * \internal
254  * Release operation.
255  * \return 0 on success, <0 on errors
256  * - IPC errors
257  *
258  * \deprecated Dataspaces exist as long as a capability
259  * on the dataspace exists.
260  */
261  L4_RPC(long, release, ());
262 
263  L4_RPC_NF(long, map, (unsigned long offset, l4_addr_t spot,
264  unsigned long flags, L4::Ipc::Rcv_fpage r,
265  L4::Ipc::Snd_fpage &fp));
266 private:
267 
268  long __map(l4_addr_t offset, unsigned char *size, unsigned long flags,
269  l4_addr_t local_addr) const throw();
270 
271 public:
272  typedef L4::Typeid::Rpcs<map_t, clear_t, info_t, copy_in_t, take_t,
273  release_t, phys_t, allocate_t> Rpcs;
274 
275 };
276 
277 
278 }
279