l4/pkg/l4sys/include/task.h

   1 /**
   2  * \file
   3  * \brief Common task related definitions.
   4  */
   5 /*
   6  * (c) 2008-2009 Technische Universität Dresden
   7  * This file is part of TUD:OS and distributed under the terms of the
   8  * GNU General Public License 2.
   9  * Please see the COPYING-GPL-2 file for details.
  10  *
  11  * As a special exception, you may use this file as part of a free software
  12  * library without restriction.  Specifically, if other files instantiate
  13  * templates or use macros or inline functions from this file, or you compile
  14  * this file and link it with other files to produce an executable, this
  15  * file does not by itself cause the resulting executable to be covered by
  16  * the GNU General Public License.  This exception does not however
  17  * invalidate any other reasons why the executable file might be covered by
  18  * the GNU General Public License.
  19  */
  20 #pragma once
  21 #include <l4/sys/types.h>
  22 #include <l4/sys/utcb.h>
  23
  24 /**
  25  * \defgroup l4_task_api Task
  26  * \ingroup  l4_kernel_object_api
  27  * \brief Class definition of the Task kernel object.
  28  *
  29  * <c>\#include <l4/sys/task.h></c>
  30  *
  31  * The L4 task class represents a combination of the address spaces provided
  32  * by the L4 micro kernel. A task consists of at least a memory address space
  33  * and an object address space. On IA32 there is also an IO-port address space.
  34  *
  35  * A task object can be created using a Factory, see \ref l4_factory_api
  36  * (l4_factory_create_task()).
  37  */
  38
  39 /**
  40  * \brief Map resources available in the source task to a destination task.
  41  * \ingroup l4_task_api
  42  *
  43  * \param dst_task      Capability selector of destination task
  44  * \param src_task      Capability selector of source task
  45  * \param snd_fpage     Send flexpage that describes an area in the
  46  *                      address space or object space of the source task
  47  * \param snd_base      Send base that describes an offset in the receive
  48  *                      window of the destination task.
  49  *
  50  * \return Syscall return tag
  51  *
  52  * This method allows for asynchronous rights delegation from one task to
  53  * another. It can be used to share memory as well as to delegate access to
  54  * objects.
  55  */
  56 L4_INLINE l4_msgtag_t
  57 l4_task_map(l4_cap_idx_t dst_task, l4_cap_idx_t src_task,
  58             l4_fpage_t const snd_fpage, l4_addr_t snd_base) L4_NOTHROW;
  59
  60 /**
  61  * \internal
  62  */
  63 L4_INLINE l4_msgtag_t
  64 l4_task_map_u(l4_cap_idx_t dst_task, l4_cap_idx_t src_task,
  65               l4_fpage_t const snd_fpage, l4_addr_t snd_base, l4_utcb_t *utcb) L4_NOTHROW;
  66
  67 /**
  68  * \brief Revoke rights from the task.
  69  * \ingroup l4_task_api
  70  *
  71  * \param task          Capability selector of destination task
  72  * \param fpage         Flexpage that describes an area in the address space or
  73  *                      object space of the destination task
  74  * \param map_mask      Unmap mask, see #l4_unmap_flags_t
  75  *
  76  * \return Syscall return tag
  77  *
  78  * This method allows to revoke rights from the destination task and from all the
  79  * tasks that got the rights delegated from that task (i.e., this operation
  80  * does a recursive rights revocation).
  81  *
  82  * \note Calling this function on the object space can cause a root capability
  83  *       of an object to be destructed, which destroys the object itself.
  84  */
  85 L4_INLINE l4_msgtag_t
  86 l4_task_unmap(l4_cap_idx_t task, l4_fpage_t const fpage,
  87               l4_umword_t map_mask) L4_NOTHROW;
  88
  89 /**
  90  * \internal
  91  */
  92 L4_INLINE l4_msgtag_t
  93 l4_task_unmap_u(l4_cap_idx_t task, l4_fpage_t const fpage,
  94                 l4_umword_t map_mask, l4_utcb_t *utcb) L4_NOTHROW;
  95
  96 /**
  97  * \brief Revoke rights from a task.
  98  * \ingroup l4_task_api
  99  *
 100  * \param task          Capability selector of destination task
 101  * \param fpages        An array of flexpages that describes an area in the
 102  *                      address space or object space of the destination task each
 103  * \param num_fpages    The size of the fpages array in elements (number of
 104  *                      fpages sent).
 105  * \param map_mask      Unmap mask, see #l4_unmap_flags_t
 106  *
 107  * \return Syscall return tag
 108  *
 109  * This method allows to revoke rights from the destination task and from all the
 110  * tasks that got the rights delegated from that task (i.e., this operation
 111  * does a recursive rights revocation).
 112  *
 113  * \pre The caller needs to take care that num_fpages is not bigger
 114  *      than L4_UTCB_GENERIC_DATA_SIZE - 2.
 115  *
 116  * \note Calling this function on the object space can cause a root capability
 117  *       of an object to be destructed, which destroys the object itself.
 118  */
 119 L4_INLINE l4_msgtag_t
 120 l4_task_unmap_batch(l4_cap_idx_t task, l4_fpage_t const *fpages,
 121                     unsigned num_fpages, unsigned long map_mask) L4_NOTHROW;
 122
 123 /**
 124  * \internal
 125  */
 126 L4_INLINE l4_msgtag_t
 127 l4_task_unmap_batch_u(l4_cap_idx_t task, l4_fpage_t const *fpages,
 128                       unsigned num_fpages, unsigned long map_mask,
 129                       l4_utcb_t *u) L4_NOTHROW;
 130 /**
 131  * \brief Test whether a capability selector points to a valid capability.
 132  * \ingroup l4_task_api
 133  *
 134  * \param task         Capability selector of the destination task to do the
 135  *                     lookup in
 136  * \param cap          Capability selector to look up in the destination task
 137  * \return label contains 1 if valid, 0 if invalid
 138  */
 139 L4_INLINE l4_msgtag_t
 140 l4_task_cap_valid(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW;
 141
 142 /**
 143  * \internal
 144  */
 145 L4_INLINE l4_msgtag_t
 146 l4_task_cap_valid_u(l4_cap_idx_t task, l4_cap_idx_t cap, l4_utcb_t *utcb) L4_NOTHROW;
 147
 148 /**
 149  * \brief Test whether a capability has child mappings (in another task).
 150  * \ingroup l4_task_api
 151  *
 152  * \param task         Capability selector of the destination task to do the
 153  *                     lookup in
 154  * \param cap          Capability selector to look up in the destination task
 155  * \return label contains 1 if it has at least one child, 0 if not or invalid
 156  */
 157 L4_INLINE l4_msgtag_t
 158 l4_task_cap_has_child(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW;
 159
 160 /**
 161  * \internal
 162  */
 163 L4_INLINE l4_msgtag_t
 164 l4_task_cap_has_child_u(l4_cap_idx_t task, l4_cap_idx_t cap, l4_utcb_t *utcb) L4_NOTHROW;
 165
 166 /**
 167  * \brief Test if two capabilities point to the same object.
 168  * \ingroup l4_task_api
 169  *
 170  * \param task         Capability selector of the destination task to do the
 171  *                     lookup in
 172  * \param cap_a        Capability selector to compare
 173  * \param cap_b        Capability selector to compare
 174  *
 175  * \return label contains 1 if equal, 0 if not equal
 176  */
 177 L4_INLINE l4_msgtag_t
 178 l4_task_cap_equal(l4_cap_idx_t task, l4_cap_idx_t cap_a,
 179                   l4_cap_idx_t cap_b) L4_NOTHROW;
 180
 181 /**
 182  * \internal
 183  */
 184 L4_INLINE l4_msgtag_t
 185 l4_task_cap_equal_u(l4_cap_idx_t task, l4_cap_idx_t cap_a,
 186                     l4_cap_idx_t cap_b, l4_utcb_t *utcb) L4_NOTHROW;
 187
 188 /**
 189  * \internal
 190  * \brief Operations on task objects.
 191  * \ingroup l4_task_api
 192  */
 193 enum L4_task_ops
 194 {
 195   L4_TASK_MAP_OP         = 0UL,    /**< Map */
 196   L4_TASK_UNMAP_OP       = 1UL,    /**< Unmap */
 197   L4_TASK_CAP_INFO_OP    = 2UL,    /**< Cap info */
 198   L4_TASK_LDT_SET_X86_OP = 0x11UL, /**< x86: LDT set */
 199   L4_TASK_VM_OPS         = 0x20UL, /**< VM op */
 200 };
 201
 202
 203 /* IMPLEMENTATION -----------------------------------------------------------*/
 204
 205 #include <l4/sys/ipc.h>
 206
 207
 208 L4_INLINE l4_msgtag_t
 209 l4_task_map_u(l4_cap_idx_t dst_task, l4_cap_idx_t src_task,
 210               l4_fpage_t const snd_fpage, unsigned long snd_base, l4_utcb_t *u) L4_NOTHROW
 211 {
 212   l4_msg_regs_t *v = l4_utcb_mr_u(u);
 213   v->mr[0] = L4_TASK_MAP_OP;
 214   v->mr[3] = l4_map_obj_control(0,0);
 215   v->mr[4] = l4_obj_fpage(src_task, 0, L4_FPAGE_RWX).raw;
 216   v->mr[1] = snd_base;
 217   v->mr[2] = snd_fpage.raw;
 218   return l4_ipc_call(dst_task, u, l4_msgtag(L4_PROTO_TASK, 3, 1, 0), L4_IPC_NEVER);
 219 }
 220
 221 L4_INLINE l4_msgtag_t
 222 l4_task_unmap_u(l4_cap_idx_t task, l4_fpage_t const fpage,
 223                 unsigned long map_mask, l4_utcb_t *u) L4_NOTHROW
 224 {
 225   l4_msg_regs_t *v = l4_utcb_mr_u(u);
 226   v->mr[0] = L4_TASK_UNMAP_OP;
 227   v->mr[1] = map_mask;
 228   v->mr[2] = fpage.raw;
 229   return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 3, 0, 0), L4_IPC_NEVER);
 230 }
 231
 232 L4_INLINE l4_msgtag_t
 233 l4_task_unmap_batch_u(l4_cap_idx_t task, l4_fpage_t const *fpages,
 234                       unsigned num_fpages, unsigned long map_mask,
 235                       l4_utcb_t *u) L4_NOTHROW
 236 {
 237   l4_msg_regs_t *v = l4_utcb_mr_u(u);
 238   v->mr[0] = L4_TASK_UNMAP_OP;
 239   v->mr[1] = map_mask;
 240   __builtin_memcpy(&v->mr[2], fpages, num_fpages * sizeof(l4_fpage_t));
 241   return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 2 + num_fpages, 0, 0), L4_IPC_NEVER);
 242 }
 243
 244 L4_INLINE l4_msgtag_t
 245 l4_task_cap_valid_u(l4_cap_idx_t task, l4_cap_idx_t cap, l4_utcb_t *u) L4_NOTHROW
 246 {
 247   l4_msg_regs_t *v = l4_utcb_mr_u(u);
 248   v->mr[0] = L4_TASK_CAP_INFO_OP;
 249   v->mr[1] = cap & ~1UL;
 250   return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 2, 0, 0), L4_IPC_NEVER);
 251 }
 252
 253 L4_INLINE l4_msgtag_t
 254 l4_task_cap_has_child_u(l4_cap_idx_t task, l4_cap_idx_t cap, l4_utcb_t *u) L4_NOTHROW
 255 {
 256   l4_msg_regs_t *v = l4_utcb_mr_u(u);
 257   v->mr[0] = L4_TASK_CAP_INFO_OP;
 258   v->mr[1] = cap | 1UL;
 259   return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 2, 0, 0), L4_IPC_NEVER);
 260 }
 261
 262 L4_INLINE l4_msgtag_t
 263 l4_task_cap_equal_u(l4_cap_idx_t task, l4_cap_idx_t cap_a,
 264                     l4_cap_idx_t cap_b, l4_utcb_t *u) L4_NOTHROW
 265 {
 266   l4_msg_regs_t *v = l4_utcb_mr_u(u);
 267   v->mr[0] = L4_TASK_CAP_INFO_OP;
 268   v->mr[1] = cap_a;
 269   v->mr[2] = cap_b;
 270   return l4_ipc_call(task, u, l4_msgtag(L4_PROTO_TASK, 3, 0, 0), L4_IPC_NEVER);
 271 }
 272
 273
 274
 275
 276 L4_INLINE l4_msgtag_t
 277 l4_task_map(l4_cap_idx_t dst_task, l4_cap_idx_t src_task,
 278             l4_fpage_t const snd_fpage, unsigned long snd_base) L4_NOTHROW
 279 {
 280   return l4_task_map_u(dst_task, src_task, snd_fpage, snd_base, l4_utcb());
 281 }
 282
 283 L4_INLINE l4_msgtag_t
 284 l4_task_unmap(l4_cap_idx_t task, l4_fpage_t const fpage,
 285               unsigned long map_mask) L4_NOTHROW
 286 {
 287   return l4_task_unmap_u(task, fpage, map_mask, l4_utcb());
 288 }
 289
 290 L4_INLINE l4_msgtag_t
 291 l4_task_unmap_batch(l4_cap_idx_t task, l4_fpage_t const *fpages,
 292                     unsigned num_fpages, unsigned long map_mask) L4_NOTHROW
 293 {
 294   return l4_task_unmap_batch_u(task, fpages, num_fpages, map_mask,
 295                                l4_utcb());
 296 }
 297
 298 L4_INLINE l4_msgtag_t
 299 l4_task_cap_valid(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW
 300 {
 301   return l4_task_cap_valid_u(task, cap, l4_utcb());
 302 }
 303
 304 L4_INLINE l4_msgtag_t
 305 l4_task_cap_has_child(l4_cap_idx_t task, l4_cap_idx_t cap) L4_NOTHROW
 306 {
 307   return l4_task_cap_has_child_u(task, cap, l4_utcb());
 308 }
 309
 310 L4_INLINE l4_msgtag_t
 311 l4_task_cap_equal(l4_cap_idx_t task, l4_cap_idx_t cap_a,
 312                   l4_cap_idx_t cap_b) L4_NOTHROW
 313 {
 314   return l4_task_cap_equal_u(task, cap_a, cap_b, l4_utcb());
 315 }