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 30namespace L4 { 31 32/** 33 * C++ interface of the Task kernel object, see \ref l4_task_api for 34 * the C interface. 35 * 36 * The L4::Task class represents a combination of the address spaces provided 37 * by the L4Re 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 39 * associated with an L4::Task. 40 * 41 * L4::Task objects are created using the L4::Factory interface. 42 * \includefile{l4/sys/task} 43 */ 44class Task : 45 public Kobject_t<Task, Kobject, L4_PROTO_TASK, 46 Type_info::Demand_t<2> > 47{ 48public: 49 /** 50 * Map resources available in the source task to a destination task. 51 * 52 * \param src_task Capability selector of the source task. 53 * \param snd_fpage Send flexpage that describes an area in the address 54 * space or object space of the source task. 55 * \param snd_base Send base that describes an offset in the receive window 56 * of the destination task. The lower bits contain additional 57 * map control flags. 58 * \param utcb UTCB pointer of the calling thread. 59 * 60 * \return Syscall return tag. 61 * 62 * This method allows for asynchronous transfer of capabilities, memory 63 * mappings, and IO-port mappings (on IA32) from one task to another. 64 * The destination task is the task referenced by the capability on which the 65 * map is invoked, and the receive window is the whole address space of that 66 * task. 67 * 68 * For more information on spaces and mappings, see 69 * \ref l4re_concepts_mapping. The flexpage API is described in more detail at 70 * \ref l4_fpage_api. 71 */ 72 l4_msgtag_t map(Cap<Task> const &src_task, 73 l4_fpage_t const &snd_fpage, l4_umword_t snd_base, 74 l4_utcb_t *utcb = l4_utcb()) noexcept 75 { return l4_task_map_u(cap(), src_task.cap(), snd_fpage, snd_base, utcb); } 76 77 /** 78 * Revoke rights from the task. 79 * 80 * \param fpage Flexpage that describes an area in one capability space 81 * of `this` task 82 * \param map_mask Unmap mask, see #l4_unmap_flags_t 83 * \param utcb UTCB pointer of the calling thread. 84 * 85 * \return Syscall return tag 86 * 87 * This method allows to revoke rights from the destination task. For a flex 88 * page describing IO ports or memory, it also revokes rights from all the 89 * tasks that got the rights delegated from the destination task (i.e., this 90 * operation does a recursive rights revocation). If the set of rights is 91 * empty after the revocation, the capability is unmapped. 92 * 93 * \note If the reference counter of a kernel object referenced in `fpage` 94 * goes down to zero (as a result of deleting capabilities), the 95 * deletion of the object is initiated. Objects are not destroyed until 96 * all other kernel objects holding a reference to it drop the 97 * reference. 98 */ 99 l4_msgtag_t unmap(l4_fpage_t const &fpage, 100 l4_umword_t map_mask, 101 l4_utcb_t *utcb = l4_utcb()) noexcept 102 { return l4_task_unmap_u(cap(), fpage, map_mask, utcb); } 103 104 /** 105 * Revoke rights from a task. 106 * 107 * \param fpages An array of flexpages. Each item describes an area in 108 * one capability space of `this` task. 109 * \param num_fpages Number of fpages in the `fpages` array. 110 * \param map_mask Unmap mask, see #l4_unmap_flags_t. 111 * \param utcb UTCB pointer of the calling thread. 112 * 113 * Revoke rights for an array of flexpages, see #unmap for details. 114 * 115 * \pre The caller needs to take care that `num_fpages` is not bigger 116 * than L4_UTCB_GENERIC_DATA_SIZE - 2. 117 */ 118 l4_msgtag_t unmap_batch(l4_fpage_t const *fpages, 119 unsigned num_fpages, 120 l4_umword_t map_mask, 121 l4_utcb_t *utcb = l4_utcb()) noexcept 122 { return l4_task_unmap_batch_u(cap(), fpages, num_fpages, map_mask, utcb); } 123 124 /** 125 * Release capability and delete object. 126 * 127 * \param obj Capability selector of the object to delete. 128 * \param utcb UTCB pointer of the calling thread. 129 * 130 * \return Syscall return tag 131 * 132 * Initiates the deletion of the object if `obj` has the delete permission. 133 * Objects are not destroyed until all other kernel objects holding a 134 * reference to it drop the reference. No error will be reported if the rights 135 * are insufficient, however, the capability is removed in all cases from the 136 * destination task. 137 */ 138 l4_msgtag_t delete_obj(L4::Cap<void> obj, 139 l4_utcb_t *utcb = l4_utcb()) noexcept 140 { return l4_task_delete_obj_u(cap(), obj.cap(), utcb); } 141 142 /** 143 * Release object capability. 144 * 145 * \param obj Capability selector of the object to release. 146 * \param utcb UTCB pointer of the calling thread. 147 * 148 * \return Syscall return tag. 149 * 150 * This operation unmaps the capability from `this` task. 151 * 152 * \note If the reference counter of the kernel object referenced by `cap` 153 * goes down to zero, the deletion of the object is initiated. Objects 154 * are not destroyed until all other kernel objects holding a reference 155 * to it drop the reference. 156 */ 157 l4_msgtag_t release_cap(L4::Cap<void> cap, 158 l4_utcb_t *utcb = l4_utcb()) noexcept 159 { return l4_task_release_cap_u(this->cap(), cap.cap(), utcb); } 160 161 /** 162 * Check whether a capability is present (refers to an object). 163 * 164 * \param cap Valid capability to check for presence. 165 * \utcb{utcb} 166 * 167 * \retval tag.label() > 0 Capability is present (refers to an object). 168 * \retval tag.label() == 0 No capability present (void object). 169 * 170 * A capability is considered present when it refers to an existing 171 * kernel object. 172 * 173 * \pre `cap` must be a valid capability (i.e. `cap.is_valid() == true`). 174 * If you are unsure about the validity of your capability use 175 * L4::Cap.validate() instead. 176 */ 177 l4_msgtag_t cap_valid(Cap<void> const &cap, 178 l4_utcb_t *utcb = l4_utcb()) noexcept 179 { return l4_task_cap_valid_u(this->cap(), cap.cap(), utcb); } 180 181 /** 182 * Test whether two capabilities point to the same object with the same 183 * rights. 184 * 185 * \param cap_a First capability selector to compare. 186 * \param cap_b Second capability selector to compare. 187 * \param utcb Optional: UTCB pointer of the calling thread. 188 * 189 * \retval tag.label() = 1: `cap_a` and `cap_b` point to the same object. 190 * \retval tag.label() = 0: The two caps do **not** point to the same 191 * object. 192 */ 193 l4_msgtag_t cap_equal(Cap<void> const &cap_a, 194 Cap<void> const &cap_b, 195 l4_utcb_t *utcb = l4_utcb()) noexcept 196 { return l4_task_cap_equal_u(cap(), cap_a.cap(), cap_b.cap(), utcb); } 197 198 /** 199 * Add kernel-user memory. 200 * 201 * \param fpage Flexpage describing the virtual area the memory goes to. 202 * \param utcb UTCP pointer of the calling thread. 203 * 204 * \note 205 * The amount of kernel-user memory that can be allocated at once is limited 206 * by the used kernel implementation. The minimum allocatable amount is one 207 * page (`L4_PAGESIZE`). A portable implementation should not depend on 208 * allocations greater than 16KiB to succeed. 209 * 210 * \return Syscall return tag 211 */ 212 l4_msgtag_t add_ku_mem(l4_fpage_t const &fpage, 213 l4_utcb_t *utcb = l4_utcb()) noexcept 214 { return l4_task_add_ku_mem_u(cap(), fpage, utcb); } 215 216}; 217} 218 219 220