3 * \brief Common task related definitions.
6 * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
7 * Alexander Warg <warg@os.inf.tu-dresden.de>,
8 * Björn Döbel <doebel@os.inf.tu-dresden.de>,
9 * Torsten Frenzel <frenzel@os.inf.tu-dresden.de>
10 * economic rights: Technische Universität Dresden (Germany)
12 * This file is part of TUD:OS and distributed under the terms of the
13 * GNU General Public License 2.
14 * Please see the COPYING-GPL-2 file for details.
16 * As a special exception, you may use this file as part of a free software
17 * library without restriction. Specifically, if other files instantiate
18 * templates or use macros or inline functions from this file, or you compile
19 * this file and link it with other files to produce an executable, this
20 * file does not by itself cause the resulting executable to be covered by
21 * the GNU General Public License. This exception does not however
22 * invalidate any other reasons why the executable file might be covered by
23 * the GNU General Public License.
26 #include <l4/sys/types.h>
27 #include <l4/sys/utcb.h>
30 * \defgroup l4_task_api Task
31 * \ingroup l4_kernel_object_api
32 * \brief Class definition of the Task kernel object.
34 * <c>\#include <l4/sys/task.h></c>
36 * The L4 task class represents a combination of the address spaces provided
37 * by the L4 micro kernel. A task consists of at least a memory address space
38 * and an object address space. On IA32 there is also an IO-port address space.
40 * A task object can be created using a Factory, see \ref l4_factory_api
41 * (l4_factory_create_task()).
45 * \brief Map resources available in the source task to a destination task.
46 * \ingroup l4_task_api
48 * \param dst_task Capability selector of destination task
49 * \param src_task Capability selector of source task
50 * \param snd_fpage Send flexpage that describes an area in the
51 * address space or object space of the source task
52 * \param snd_base Send base that describes an offset in the receive
53 * window of the destination task.
55 * \return Syscall return tag
57 * This method allows for asynchronous rights delegation from one task to
58 * another. It can be used to share memory as well as to delegate access to
62 l4_task_map(l4_cap_idx_t dst_task, l4_cap_idx_t src_task,
63 l4_fpage_t const snd_fpage, l4_addr_t snd_base) L4_NOTHROW;
69 l4_task_map_u(l4_cap_idx_t dst_task, l4_cap_idx_t src_task,
70 l4_fpage_t const snd_fpage, l4_addr_t snd_base, l4_utcb_t *utcb) L4_NOTHROW;
73 * \brief Revoke rights from the task.
74 * \ingroup l4_task_api
76 * \param task Capability selector of destination task
77 * \param fpage Flexpage that describes an area in the address space or
78 * object space of the destination task
79 * \param map_mask Unmap mask, see #l4_unmap_flags_t
81 * \return Syscall return tag
83 * This method allows to revoke rights from the destination task and from all the
84 * tasks that got the rights delegated from that task (i.e., this operation
85 * does a recursive rights revocation).
87 * \note Calling this function on the object space can cause a root capability
88 * of an object to be destructed, which destroys the object itself.
91 l4_task_unmap(l4_cap_idx_t task, l4_fpage_t const fpage,
92 l4_umword_t map_mask) L4_NOTHROW;
98 l4_task_unmap_u(l4_cap_idx_t task, l4_fpage_t const fpage,
99 l4_umword_t map_mask, l4_utcb_t *utcb) L4_NOTHROW;
102 * \brief Revoke rights from a task.
103 * \ingroup l4_task_api
105 * \param task Capability selector of destination task
106 * \param fpages An array of flexpages that describes an area in the
107 * address space or object space of the destination task each
108 * \param num_fpages The size of the fpages array in elements (number of
110 * \param map_mask Unmap mask, see #l4_unmap_flags_t
112 * \return Syscall return tag
114 * This method allows to revoke rights from the destination task and from all the
115 * tasks that got the rights delegated from that task (i.e., this operation
116 * does a recursive rights revocation).
118 * \pre The caller needs to take care that num_fpages is not bigger
119 * than L4_UTCB_GENERIC_DATA_SIZE - 2.
121 * \note Calling this function on the object space can cause a root capability
122 * of an object to be destructed, which destroys the object itself.
124 L4_INLINE l4_msgtag_t
125 l4_task_unmap_batch(l4_cap_idx_t task, l4_fpage_t const *fpages,
126 unsigned num_fpages, unsigned long map_mask) L4_NOTHROW;
131 L4_INLINE l4_msgtag_t
132 l4_task_unmap_batch_u(l4_cap_idx_t task, l4_fpage_t const *fpages,
133 unsigned num_fpages, unsigned long map_mask,
134 l4_utcb_t *u) L4_NOTHROW;
136 * \brief Test whether a capability selector points to a valid capability.
137 * \ingroup l4_task_api
139 * \param task Capability selector of the destination task to do the
141 * \param cap Capability selector to look up in the destination task
142 * \return label contains 1 if valid, 0 if invalid
144 L4_INLINE l4_msgtag_t
145 l4_task_cap_valid(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW;
150 L4_INLINE l4_msgtag_t
151 l4_task_cap_valid_u(l4_cap_idx_t task, l4_cap_idx_t cap, l4_utcb_t *utcb) L4_NOTHROW;
154 * \brief Test whether a capability has child mappings (in another task).
155 * \ingroup l4_task_api
157 * \param task Capability selector of the destination task to do the
159 * \param cap Capability selector to look up in the destination task
160 * \return label contains 1 if it has at least one child, 0 if not or invalid
162 L4_INLINE l4_msgtag_t
163 l4_task_cap_has_child(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW;
168 L4_INLINE l4_msgtag_t
169 l4_task_cap_has_child_u(l4_cap_idx_t task, l4_cap_idx_t cap, l4_utcb_t *utcb) L4_NOTHROW;
172 * \brief Test if two capabilities point to the same object.
173 * \ingroup l4_task_api
175 * \param task Capability selector of the destination task to do the
177 * \param cap_a Capability selector to compare
178 * \param cap_b Capability selector to compare
180 * \return label contains 1 if equal, 0 if not equal
182 L4_INLINE l4_msgtag_t
183 l4_task_cap_equal(l4_cap_idx_t task, l4_cap_idx_t cap_a,
184 l4_cap_idx_t cap_b) L4_NOTHROW;
189 L4_INLINE l4_msgtag_t
190 l4_task_cap_equal_u(l4_cap_idx_t task, l4_cap_idx_t cap_a,
191 l4_cap_idx_t cap_b, l4_utcb_t *utcb) L4_NOTHROW;
195 * \brief Operations on task objects.
196 * \ingroup l4_task_api
200 L4_TASK_MAP_OP = 0UL, /**< Map */
201 L4_TASK_UNMAP_OP = 1UL, /**< Unmap */
202 L4_TASK_CAP_INFO_OP = 2UL, /**< Cap info */
203 L4_TASK_LDT_SET_X86_OP = 0x11UL, /**< x86: LDT set */
204 L4_TASK_VM_OPS = 0x20UL, /**< VM op */
208 /* IMPLEMENTATION -----------------------------------------------------------*/
210 #include <l4/sys/ipc.h>
213 L4_INLINE l4_msgtag_t
214 l4_task_map_u(l4_cap_idx_t dst_task, l4_cap_idx_t src_task,
215 l4_fpage_t const snd_fpage, unsigned long snd_base, l4_utcb_t *u) L4_NOTHROW
217 l4_msg_regs_t *v = l4_utcb_mr_u(u);
218 v->mr[0] = L4_TASK_MAP_OP;
219 v->mr[3] = l4_map_obj_control(0,0);
220 v->mr[4] = l4_obj_fpage(src_task, 0, L4_FPAGE_RWX).raw;
222 v->mr[2] = snd_fpage.raw;
223 return l4_ipc_call(dst_task, u, l4_msgtag(L4_PROTO_TASK, 3, 1, 0), L4_IPC_NEVER);
226 L4_INLINE l4_msgtag_t
227 l4_task_unmap_u(l4_cap_idx_t task, l4_fpage_t const fpage,
228 unsigned long map_mask, l4_utcb_t *u) L4_NOTHROW
230 l4_msg_regs_t *v = l4_utcb_mr_u(u);
231 v->mr[0] = L4_TASK_UNMAP_OP;
233 v->mr[2] = fpage.raw;
234 return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 3, 0, 0), L4_IPC_NEVER);
237 L4_INLINE l4_msgtag_t
238 l4_task_unmap_batch_u(l4_cap_idx_t task, l4_fpage_t const *fpages,
239 unsigned num_fpages, unsigned long map_mask,
240 l4_utcb_t *u) L4_NOTHROW
242 l4_msg_regs_t *v = l4_utcb_mr_u(u);
243 v->mr[0] = L4_TASK_UNMAP_OP;
245 __builtin_memcpy(&v->mr[2], fpages, num_fpages * sizeof(l4_fpage_t));
246 return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 2 + num_fpages, 0, 0), L4_IPC_NEVER);
249 L4_INLINE l4_msgtag_t
250 l4_task_cap_valid_u(l4_cap_idx_t task, l4_cap_idx_t cap, l4_utcb_t *u) L4_NOTHROW
252 l4_msg_regs_t *v = l4_utcb_mr_u(u);
253 v->mr[0] = L4_TASK_CAP_INFO_OP;
254 v->mr[1] = cap & ~1UL;
255 return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 2, 0, 0), L4_IPC_NEVER);
258 L4_INLINE l4_msgtag_t
259 l4_task_cap_has_child_u(l4_cap_idx_t task, l4_cap_idx_t cap, l4_utcb_t *u) L4_NOTHROW
261 l4_msg_regs_t *v = l4_utcb_mr_u(u);
262 v->mr[0] = L4_TASK_CAP_INFO_OP;
263 v->mr[1] = cap | 1UL;
264 return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 2, 0, 0), L4_IPC_NEVER);
267 L4_INLINE l4_msgtag_t
268 l4_task_cap_equal_u(l4_cap_idx_t task, l4_cap_idx_t cap_a,
269 l4_cap_idx_t cap_b, l4_utcb_t *u) L4_NOTHROW
271 l4_msg_regs_t *v = l4_utcb_mr_u(u);
272 v->mr[0] = L4_TASK_CAP_INFO_OP;
275 return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 3, 0, 0), L4_IPC_NEVER);
281 L4_INLINE l4_msgtag_t
282 l4_task_map(l4_cap_idx_t dst_task, l4_cap_idx_t src_task,
283 l4_fpage_t const snd_fpage, unsigned long snd_base) L4_NOTHROW
285 return l4_task_map_u(dst_task, src_task, snd_fpage, snd_base, l4_utcb());
288 L4_INLINE l4_msgtag_t
289 l4_task_unmap(l4_cap_idx_t task, l4_fpage_t const fpage,
290 unsigned long map_mask) L4_NOTHROW
292 return l4_task_unmap_u(task, fpage, map_mask, l4_utcb());
295 L4_INLINE l4_msgtag_t
296 l4_task_unmap_batch(l4_cap_idx_t task, l4_fpage_t const *fpages,
297 unsigned num_fpages, unsigned long map_mask) L4_NOTHROW
299 return l4_task_unmap_batch_u(task, fpages, num_fpages, map_mask,
303 L4_INLINE l4_msgtag_t
304 l4_task_cap_valid(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW
306 return l4_task_cap_valid_u(task, cap, l4_utcb());
309 L4_INLINE l4_msgtag_t
310 l4_task_cap_has_child(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW
312 return l4_task_cap_has_child_u(task, cap, l4_utcb());
315 L4_INLINE l4_msgtag_t
316 l4_task_cap_equal(l4_cap_idx_t task, l4_cap_idx_t cap_a,
317 l4_cap_idx_t cap_b) L4_NOTHROW
319 return l4_task_cap_equal_u(task, cap_a, cap_b, l4_utcb());