L4Re - L4 Runtime Environment
task
Go to the documentation of this file.
1 // vi:set ft=cpp: -*- Mode: C++ -*-
2 /**
3  * \file
4  * Common task related definitions.
5  */
6 /*
7  * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
8  * Alexander Warg <warg@os.inf.tu-dresden.de>
9  * economic rights: Technische Universit├Ąt Dresden (Germany)
10  *
11  * This file is part of TUD:OS and distributed under the terms of the
12  * GNU General Public License 2.
13  * Please see the COPYING-GPL-2 file for details.
14  *
15  * As a special exception, you may use this file as part of a free software
16  * library without restriction. Specifically, if other files instantiate
17  * templates or use macros or inline functions from this file, or you compile
18  * this file and link it with other files to produce an executable, this
19  * file does not by itself cause the resulting executable to be covered by
20  * the GNU General Public License. This exception does not however
21  * invalidate any other reasons why the executable file might be covered by
22  * the GNU General Public License.
23  */
24 
25 #pragma once
26 
27 #include <l4/sys/task.h>
28 #include <l4/sys/capability>
29 
30 namespace L4 {
31 
32 /**
33  * C++ interface of the Task kernel object.
34  *
35  * The L4::Task class represents a combination of the address spaces provided
36  * by the L4Re micro kernel. A task consists of at least a memory address space
37  * and an object address space. On IA32 there is also an IO-port address space
38  * associated with an L4::Task.
39  *
40  * L4::Task objects are created using the L4::Factory interface.
41  * \includefile{l4/sys/task}
42  */
43 class Task :
44  public Kobject_t<Task, Kobject, L4_PROTO_TASK,
45  Type_info::Demand_t<2> >
46 {
47 public:
48  /**
49  * Map resources available in the source task to a destination task.
50  *
51  * \param src_task Capability selector of the source task.
52  * \param snd_fpage Send flexpage that describes an area in the address
53  * space or object space of the source task.
54  * \param snd_base Send base that describes an offset in the receive window
55  * of the destination task. The lower bits contain additional
56  * map control flags.
57  * \param utcb UTCB pointer of the calling thread.
58  *
59  * \return Syscall return tag.
60  *
61  * This method allows for asynchronous rights delegation from one task to
62  * another. It can be used to share memory as well as to delegate access to
63  * objects.
64  * The destination task is the task referenced by the capability invoking map
65  * and the receive window is the whole address space of said task.
66  */
67  l4_msgtag_t map(Cap<Task> const &src_task,
68  l4_fpage_t const &snd_fpage, l4_addr_t snd_base,
69  l4_utcb_t *utcb = l4_utcb()) throw()
70  { return l4_task_map_u(cap(), src_task.cap(), snd_fpage, snd_base, utcb); }
71 
72  /**
73  * Revoke rights from the task.
74  *
75  * \param fpage Flexpage that describes an area in the address space or
76  * object space of `this` task
77  * \param map_mask Unmap mask, see #l4_unmap_flags_t
78  * \param utcb UTCB pointer of the calling thread.
79  *
80  * \return Syscall return tag
81  *
82  * This method allows to revoke rights from the destination task and from all the
83  * tasks that got the rights delegated from that task (i.e., this operation
84  * does a recursive rights revocation).
85  *
86  * \note If the capability possesses delete rights or if it is the last
87  * capability pointing to the object, calling this function might
88  * destroy the object itself.
89  */
90  l4_msgtag_t unmap(l4_fpage_t const &fpage,
91  l4_umword_t map_mask,
92  l4_utcb_t *utcb = l4_utcb()) throw()
93  { return l4_task_unmap_u(cap(), fpage, map_mask, utcb); }
94 
95  /**
96  * Revoke rights from a task.
97  *
98  * \param fpages An array of flexpages. Each item describes an area in
99  * the address or object space of `this` task.
100  * \param num_fpages Number of fpages in the `fpages` array.
101  * \param map_mask Unmap mask, see #l4_unmap_flags_t.
102  * \param utcb UTCB pointer of the calling thread.
103  *
104  * This method allows to revoke rights from the destination task and from all
105  * the tasks that got the rights delegated from that task (i.e., this
106  * operation does a recursive rights revocation).
107  *
108  * \pre The caller needs to take care that `num_fpages` is not bigger
109  * than L4_UTCB_GENERIC_DATA_SIZE - 2.
110  *
111  * \note If the capability possesses delete rights or if it is the last
112  * capability pointing to the object, calling this function might
113  * destroy the object itself.
114  */
115  l4_msgtag_t unmap_batch(l4_fpage_t const *fpages,
116  unsigned num_fpages,
117  l4_umword_t map_mask,
118  l4_utcb_t *utcb = l4_utcb()) throw()
119  { return l4_task_unmap_batch_u(cap(), fpages, num_fpages, map_mask, utcb); }
120 
121  /**
122  * Release capability and delete object.
123  *
124  * \param obj Capability selector of the object to delete.
125  * \param utcb UTCB pointer of the calling thread.
126  *
127  * \return Syscall return tag
128  *
129  * The object will be deleted if the `obj` has sufficient rights. No error
130  * will be reported if the rights are insufficient, however, the capability
131  * is removed in all cases.
132  */
133  l4_msgtag_t delete_obj(L4::Cap<void> obj,
134  l4_utcb_t *utcb = l4_utcb()) throw()
135  { return l4_task_delete_obj_u(cap(), obj.cap(), utcb); }
136 
137  /**
138  * Release capability.
139  *
140  * \param cap Capability selector to release.
141  * \param utcb UTCB pointer of the calling thread.
142  *
143  * \return Syscall return tag.
144  *
145  * This operation unmaps the capability from `this` task.
146  */
147  l4_msgtag_t release_cap(L4::Cap<void> cap,
148  l4_utcb_t *utcb = l4_utcb()) throw()
149  { return l4_task_release_cap_u(this->cap(), cap.cap(), utcb); }
150 
151  /**
152  * Check whether a capability is present (refers to an object).
153  *
154  * \param cap Capability to check for presence.
155  * \utcb{utcb}
156  *
157  * \retval tag.label() > 0 Capability is present (refers to an object).
158  * \retval tag.label() == 0 No capability present (void object).
159  *
160  * A capability is considered present when it refers to an existing
161  * kernel object.
162  */
163  l4_msgtag_t cap_valid(Cap<void> const &cap,
164  l4_utcb_t *utcb = l4_utcb()) throw()
165  { return l4_task_cap_valid_u(this->cap(), cap.cap(), utcb); }
166 
167  /**
168  * Test whether a capability has child mappings (in another task).
169  *
170  * \param cap Capability selector to look up in the destination task.
171  * \param utcb UTCB pointer of the calling thread.
172  *
173  * \retval tag.label() = 1: The capability has at least on child mapping in
174  * another task.
175  * \retval tag.label() = 0: No child mappings.
176  *
177  * \deprecated Do not use. Undetermined future, might be removed.
178  */
179  l4_msgtag_t cap_has_child(Cap<void> const &cap,
180  l4_utcb_t *utcb = l4_utcb()) throw()
181  L4_DEPRECATED("Do not use. Future uncertain.")
182  { return l4_task_cap_has_child_u(this->cap(), cap.cap(), utcb); }
183 
184  /**
185  * Test whether two capabilities point to the same object with the same
186  * rights.
187  *
188  * \param cap_a First capability selector to compare.
189  * \param cap_b Second capability selector to compare.
190  * \param utcb Optional: UTCB pointer of the calling thread.
191  *
192  * \retval tag.label() = 1: `cap_a` and `cap_b` point to the same object.
193  * \retval tag.label() = 0: The two caps do **not** point to the same
194  * object.
195  */
196  l4_msgtag_t cap_equal(Cap<void> const &cap_a,
197  Cap<void> const &cap_b,
198  l4_utcb_t *utcb = l4_utcb()) throw()
199  { return l4_task_cap_equal_u(cap(), cap_a.cap(), cap_b.cap(), utcb); }
200 
201  /**
202  * Add kernel-user memory.
203  *
204  * \param fpage Flexpage describing the virtual area the memory goes to.
205  * \param utcb UTCP pointer of the calling thread.
206  *
207  * \return Syscall return tag
208  */
209  l4_msgtag_t add_ku_mem(l4_fpage_t const &fpage,
210  l4_utcb_t *utcb = l4_utcb()) throw()
211  { return l4_task_add_ku_mem_u(cap(), fpage, utcb); }
212 
213 };
214 }
215 
216