l4/pkg/l4sys/include/task.h

   1 /**
   2  * \file
   3  * \brief Common task related definitions.
   4  */
   5 /*
   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)
  11  *
  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.
  15  *
  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.
  24  */
  25 #pragma once
  26 #include <l4/sys/types.h>
  27 #include <l4/sys/utcb.h>
  28
  29 /**
  30  * \defgroup l4_task_api Task
  31  * \ingroup  l4_kernel_object_api
  32  * \brief Class definition of the Task kernel object.
  33  *
  34  * <c>\#include <l4/sys/task.h></c>
  35  *
  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.
  39  *
  40  * A task object can be created using a Factory, see \ref l4_factory_api
  41  * (l4_factory_create_task()).
  42  */
  43
  44 /**
  45  * \brief Map resources available in the source task to a destination task.
  46  * \ingroup l4_task_api
  47  *
  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.
  54  *
  55  * \return Syscall return tag
  56  *
  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
  59  * objects.
  60  */
  61 L4_INLINE l4_msgtag_t
  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;
  64
  65 /**
  66  * \internal
  67  */
  68 L4_INLINE l4_msgtag_t
  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;
  71
  72 /**
  73  * \brief Revoke rights from the task.
  74  * \ingroup l4_task_api
  75  *
  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
  80  *
  81  * \return Syscall return tag
  82  *
  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).
  86  *
  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.
  89  */
  90 L4_INLINE l4_msgtag_t
  91 l4_task_unmap(l4_cap_idx_t task, l4_fpage_t const fpage,
  92               l4_umword_t map_mask) L4_NOTHROW;
  93
  94 /**
  95  * \internal
  96  */
  97 L4_INLINE l4_msgtag_t
  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;
 100
 101 /**
 102  * \brief Revoke rights from a task.
 103  * \ingroup l4_task_api
 104  *
 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
 109  *                      fpages sent).
 110  * \param map_mask      Unmap mask, see #l4_unmap_flags_t
 111  *
 112  * \return Syscall return tag
 113  *
 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).
 117  *
 118  * \pre The caller needs to take care that num_fpages is not bigger
 119  *      than L4_UTCB_GENERIC_DATA_SIZE - 2.
 120  *
 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.
 123  */
 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;
 127
 128 /**
 129  * \internal
 130  */
 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;
 135 /**
 136  * \brief Test whether a capability selector points to a valid capability.
 137  * \ingroup l4_task_api
 138  *
 139  * \param task         Capability selector of the destination task to do the
 140  *                     lookup in
 141  * \param cap          Capability selector to look up in the destination task
 142  * \return label contains 1 if valid, 0 if invalid
 143  */
 144 L4_INLINE l4_msgtag_t
 145 l4_task_cap_valid(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW;
 146
 147 /**
 148  * \internal
 149  */
 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;
 152
 153 /**
 154  * \brief Test whether a capability has child mappings (in another task).
 155  * \ingroup l4_task_api
 156  *
 157  * \param task         Capability selector of the destination task to do the
 158  *                     lookup in
 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
 161  */
 162 L4_INLINE l4_msgtag_t
 163 l4_task_cap_has_child(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW;
 164
 165 /**
 166  * \internal
 167  */
 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;
 170
 171 /**
 172  * \brief Test if two capabilities point to the same object.
 173  * \ingroup l4_task_api
 174  *
 175  * \param task         Capability selector of the destination task to do the
 176  *                     lookup in
 177  * \param cap_a        Capability selector to compare
 178  * \param cap_b        Capability selector to compare
 179  *
 180  * \return label contains 1 if equal, 0 if not equal
 181  */
 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;
 185
 186 /**
 187  * \internal
 188  */
 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;
 192
 193 /**
 194  * \internal
 195  * \brief Operations on task objects.
 196  * \ingroup l4_task_api
 197  */
 198 enum L4_task_ops
 199 {
 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 */
 205 };
 206
 207
 208 /* IMPLEMENTATION -----------------------------------------------------------*/
 209
 210 #include <l4/sys/ipc.h>
 211
 212
 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
 216 {
 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;
 221   v->mr[1] = snd_base;
 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);
 224 }
 225
 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
 229 {
 230   l4_msg_regs_t *v = l4_utcb_mr_u(u);
 231   v->mr[0] = L4_TASK_UNMAP_OP;
 232   v->mr[1] = map_mask;
 233   v->mr[2] = fpage.raw;
 234   return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 3, 0, 0), L4_IPC_NEVER);
 235 }
 236
 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
 241 {
 242   l4_msg_regs_t *v = l4_utcb_mr_u(u);
 243   v->mr[0] = L4_TASK_UNMAP_OP;
 244   v->mr[1] = map_mask;
 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);
 247 }
 248
 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
 251 {
 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);
 256 }
 257
 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
 260 {
 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);
 265 }
 266
 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
 270 {
 271   l4_msg_regs_t *v = l4_utcb_mr_u(u);
 272   v->mr[0] = L4_TASK_CAP_INFO_OP;
 273   v->mr[1] = cap_a;
 274   v->mr[2] = cap_b;
 275   return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 3, 0, 0), L4_IPC_NEVER);
 276 }
 277
 278
 279
 280
 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
 284 {
 285   return l4_task_map_u(dst_task, src_task, snd_fpage, snd_base, l4_utcb());
 286 }
 287
 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
 291 {
 292   return l4_task_unmap_u(task, fpage, map_mask, l4_utcb());
 293 }
 294
 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
 298 {
 299   return l4_task_unmap_batch_u(task, fpages, num_fpages, map_mask,
 300                                l4_utcb());
 301 }
 302
 303 L4_INLINE l4_msgtag_t
 304 l4_task_cap_valid(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW
 305 {
 306   return l4_task_cap_valid_u(task, cap, l4_utcb());
 307 }
 308
 309 L4_INLINE l4_msgtag_t
 310 l4_task_cap_has_child(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW
 311 {
 312   return l4_task_cap_has_child_u(task, cap, l4_utcb());
 313 }
 314
 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
 318 {
 319   return l4_task_cap_equal_u(task, cap_a, cap_b, l4_utcb());
 320 }