l4/pkg/l4sys/include/types.h

   1 /*****************************************************************************/
   2 /**
   3  * \file
   4  * \brief   Common L4 ABI Data Types.
   5  * \ingroup l4_api
   6  */
   7 /*
   8  * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
   9  *               Alexander Warg <warg@os.inf.tu-dresden.de>,
  10  *               Björn Döbel <doebel@os.inf.tu-dresden.de>,
  11  *               Torsten Frenzel <frenzel@os.inf.tu-dresden.de>
  12  *     economic rights: Technische Universität Dresden (Germany)
  13  *
  14  * This file is part of TUD:OS and distributed under the terms of the
  15  * GNU General Public License 2.
  16  * Please see the COPYING-GPL-2 file for details.
  17  *
  18  * As a special exception, you may use this file as part of a free software
  19  * library without restriction.  Specifically, if other files instantiate
  20  * templates or use macros or inline functions from this file, or you compile
  21  * this file and link it with other files to produce an executable, this
  22  * file does not by itself cause the resulting executable to be covered by
  23  * the GNU General Public License.  This exception does not however
  24  * invalidate any other reasons why the executable file might be covered by
  25  * the GNU General Public License.
  26  */
  27 /*****************************************************************************/
  28 #pragma once
  29
  30 #include <l4/sys/l4int.h>
  31 #include <l4/sys/compiler.h>
  32 #include <l4/sys/consts.h>
  33
  34
  35 /**
  36  * \defgroup l4_msgtag_api Message Tag
  37  * \ingroup l4_ipc_api
  38  * \brief API related to the message tag data type.
  39  *
  40  * <c>\#include <l4/sys/types.h></c>
  41  */
  42
  43 /**
  44  * \brief Message tag for IPC operations.
  45  * \ingroup l4_msgtag_api
  46  *
  47  * All predefined protocols used by the kernel.
  48  */
  49 enum l4_msgtag_protocol
  50 {
  51   L4_PROTO_NONE          = 0,   ///< Default protocol tag to reply to kernel
  52   L4_PROTO_ALLOW_SYSCALL = 1,   ///< Allow an alien the system call
  53   L4_PROTO_PF_EXCEPTION  = 1,   ///< Make an exception out of a page fault
  54
  55   L4_PROTO_IRQ           =  -1L, ///< IRQ message
  56   L4_PROTO_PAGE_FAULT    =  -2L, ///< Page fault message
  57   L4_PROTO_PREEMPTION    =  -3L, ///< Preemption message
  58   L4_PROTO_SYS_EXCEPTION =  -4L, ///< System exception
  59   L4_PROTO_EXCEPTION     =  -5L, ///< Exception
  60   L4_PROTO_SIGMA0        =  -6L, ///< Sigma0 protocol
  61   L4_PROTO_IO_PAGE_FAULT =  -8L, ///< I/O page fault message
  62   L4_PROTO_KOBJECT       = -10L, ///< Protocol for messages to a a generic kobject
  63   L4_PROTO_TASK          = -11L, ///< Protocol for messages to a task object
  64   L4_PROTO_THREAD        = -12L, ///< Protocol for messages to a thread object
  65   L4_PROTO_LOG           = -13L, ///< Protocol for messages to a log object
  66   L4_PROTO_SCHEDULER     = -14L, ///< Protocol for messages to a scheduler object
  67   L4_PROTO_FACTORY       = -15L, ///< Protocol for messages to a factory object
  68   L4_PROTO_VM            = -16L, ///< Protocol for messages to a virtual machine object
  69   L4_PROTO_DEBUGGER      = -17L,
  70   L4_PROTO_META          = -21L, ///< Meta information protocol
  71 };
  72
  73 enum L4_varg_type
  74 {
  75   L4_VARG_TYPE_NIL    = 0x00,
  76   L4_VARG_TYPE_UMWORD = 0x01,
  77   L4_VARG_TYPE_MWORD  = 0x81,
  78   L4_VARG_TYPE_STRING = 0x02,
  79   L4_VARG_TYPE_FPAGE  = 0x03,
  80
  81   L4_VARG_TYPE_SIGN   = 0x80,
  82 };
  83
  84
  85 /**
  86  * \brief Flags for message tags.
  87  * \ingroup l4_msgtag_api
  88  */
  89 enum l4_msgtag_flags
  90 {
  91   // flags for received IPC
  92   /**
  93    * \brief Error indicator flag.
  94    * \hideinitializer
  95    */
  96   L4_MSGTAG_ERROR        = 0x8000,
  97   /**
  98    * \brief Cross-CPU invocation indicator flag.
  99    * \hideinitializer
 100    */
 101   L4_MSGTAG_XCPU         = 0x4000,
 102
 103   // flags for sending IPC
 104   /**
 105    * \brief Enable FPU transfer flag for IPC.
 106    * \hideinitializer
 107    *
 108    * By enabling this flag when sending IPC, the sender indicates that the
 109    * contents of the FPU shall be transfered to the receiving thread.
 110    * However, the receiver has to indicate its willingness to receive
 111    * FPU context in its buffer descriptor register (BDR).
 112    */
 113   L4_MSGTAG_TRANSFER_FPU = 0x1000,
 114   /**
 115    * \brief Enable schedule in IPC flag.
 116    * \hideinitializer
 117    *
 118    * Usually IPC operations donate the remaining time slice of a thread
 119    * to the called thread. Enabling this flag when sending IPC does a real
 120    * scheduling decision. However, this flag decreases IPC performance.
 121    */
 122   L4_MSGTAG_SCHEDULE     = 0x2000,
 123   /**
 124    * \brief Enable IPC propagation.
 125    * \hideinitializer
 126    *
 127    * This flag enables IPC propagation, which means an IPC reply-connection
 128    * from the current caller will be propagated to the new IPC receiver.
 129    * This makes it possible to propagate an IPC call to a third thread, which
 130    * may then directly answer to the caller.
 131    */
 132   L4_MSGTAG_PROPAGATE    = 0x4000,
 133
 134   /**
 135    * \brief Mask for all flags.
 136    * \hideinitializer
 137    */
 138   L4_MSGTAG_FLAGS        = 0xf000,
 139 };
 140
 141
 142 /**
 143  * \brief Message tag data structure.
 144  * \ingroup l4_msgtag_api
 145  *
 146  * <c>\#include <l4/sys/types.h></c>
 147  *
 148  * Describes the details of an IPC operation, in particular
 149  * which parts of the UTCB have to be transmitted, and also flags
 150  * to enable real-time and FPU extensions.
 151  *
 152  * The message tag also contains a user-defined label that could be used
 153  * to specify a protocol ID. Some negative values are reserved for kernel
 154  * protocols such as page faults and exceptions.
 155  *
 156  * The type must be treated completely opaque.
 157  */
 158 typedef struct l4_msgtag_t
 159 {
 160   l4_mword_t raw;   ///< raw value
 161 #ifdef __cplusplus
 162   /// Get the protocol value.
 163   long label() const throw() { return raw >> 16; }
 164   /// Set the protocol value.
 165   void label(long v) throw() { raw = (raw & 0x0ffff) | (v << 16); }
 166   /// Get the number of untyped words.
 167   unsigned words() const throw() { return raw & 0x3f; }
 168   /// Get the number of typed items.
 169   unsigned items() const throw() { return (raw >> 6) & 0x3f; }
 170   /**
 171    * \brief Get the flags value.
 172    *
 173    * The flags are a combination of the flags defined by
 174    * #l4_msgtag_flags.
 175    */
 176   unsigned flags() const throw() { return raw & 0xf000; }
 177   /// Test if protocol indicates page-fault protocol.
 178   bool is_page_fault() const throw() { return label() == L4_PROTO_PAGE_FAULT; }
 179   /// Test if protocol indicates preemption protocol.
 180   bool is_preemption() const throw() { return label() == L4_PROTO_PREEMPTION; }
 181   /// Test if protocol indicates system-exception protocol.
 182   bool is_sys_exception() const throw() { return label() == L4_PROTO_SYS_EXCEPTION; }
 183   /// Test if protocol indicates exception protocol.
 184   bool is_exception() const throw() { return label() == L4_PROTO_EXCEPTION; }
 185   /// Test if protocol indicates sigma0 protocol.
 186   bool is_sigma0() const throw() { return label() == L4_PROTO_SIGMA0; }
 187   /// Test if protocol indicates IO-page-fault protocol.
 188   bool is_io_page_fault() const throw() { return label() == L4_PROTO_IO_PAGE_FAULT; }
 189   /// Test if flags indicate an error.
 190   unsigned has_error() const throw() { return raw & L4_MSGTAG_ERROR; }
 191 #endif
 192 } l4_msgtag_t;
 193
 194
 195
 196 /**
 197  * \brief Create a message tag from the specified values.
 198  * \ingroup l4_msgtag_api
 199  *
 200  * \param label the user-defined label
 201  * \param words the number of untyped words within the UTCB
 202  * \param items the number of typed items (e.g., flex pages) within the UTCB
 203  * \param flags the IPC flags for realtime and FPU extensions
 204  *
 205  * \return Message tag
 206  */
 207 L4_INLINE l4_msgtag_t l4_msgtag(long label, unsigned words, unsigned items,
 208                                 unsigned flags) L4_NOTHROW;
 209
 210 /**
 211  * \brief Get the protocol of tag.
 212  * \ingroup l4_msgtag_api
 213  * \param t The tag
 214  * \return Label
 215  */
 216 L4_INLINE long l4_msgtag_label(l4_msgtag_t t) L4_NOTHROW;
 217
 218 /**
 219  * \brief Get the number of untyped words.
 220  * \ingroup l4_msgtag_api
 221  * \param t The tag
 222  * \return Number of words
 223  */
 224 L4_INLINE unsigned l4_msgtag_words(l4_msgtag_t t) L4_NOTHROW;
 225
 226 /**
 227  * \brief Get the number of typed items.
 228  * \ingroup l4_msgtag_api
 229  * \param t The tag
 230  * \return Number of items.
 231  */
 232 L4_INLINE unsigned l4_msgtag_items(l4_msgtag_t t) L4_NOTHROW;
 233
 234 /**
 235  * \brief Get the flags.
 236  * \ingroup l4_msgtag_api
 237  *
 238  * The flag are defined by #l4_msgtag_flags.
 239  *
 240  * \param t the tag
 241  * \return Flags
 242  */
 243 L4_INLINE unsigned l4_msgtag_flags(l4_msgtag_t t) L4_NOTHROW;
 244
 245 /**
 246  * \brief Test for error indicator flag.
 247  * \ingroup l4_msgtag_api
 248  * \param t the tag
 249  * \return >0 for yes, 0 for no
 250  *
 251  * Return whether the kernel operation caused a communication error, e.g.
 252  * with IPC.
 253  * if true: utcb->error is valid, otherwise utcb->error is not valid
 254  */
 255 L4_INLINE unsigned l4_msgtag_has_error(l4_msgtag_t t) L4_NOTHROW;
 256
 257 /**
 258  * \brief Test for page-fault protocol.
 259  * \ingroup l4_msgtag_api
 260  * \param t the tag
 261  * \return Boolean value
 262  */
 263 L4_INLINE unsigned l4_msgtag_is_page_fault(l4_msgtag_t t) L4_NOTHROW;
 264
 265 /**
 266  * \brief Test for preemption protocol.
 267  * \ingroup l4_msgtag_api
 268  * \param t the tag
 269  * \return Boolean value
 270  */
 271 L4_INLINE unsigned l4_msgtag_is_preemption(l4_msgtag_t t) L4_NOTHROW;
 272
 273 /**
 274  * \brief Test for system-exception protocol.
 275  * \ingroup l4_msgtag_api
 276  * \param t the tag
 277  * \return Boolean value
 278  */
 279 L4_INLINE unsigned l4_msgtag_is_sys_exception(l4_msgtag_t t) L4_NOTHROW;
 280
 281 /**
 282  * \brief Test for exception protocol.
 283  * \ingroup l4_msgtag_api
 284  * \param t the tag
 285  * \return Boolean value
 286  */
 287 L4_INLINE unsigned l4_msgtag_is_exception(l4_msgtag_t t) L4_NOTHROW;
 288
 289 /**
 290  * \brief Test for sigma0 protocol.
 291  * \ingroup l4_msgtag_api
 292  * \param t the tag
 293  * \return Boolean value
 294  */
 295 L4_INLINE unsigned l4_msgtag_is_sigma0(l4_msgtag_t t) L4_NOTHROW;
 296
 297 /**
 298  * \brief Test for IO-page-fault protocol.
 299  * \ingroup l4_msgtag_api
 300  * \param t the tag
 301  * \return Boolean value
 302  */
 303 L4_INLINE unsigned l4_msgtag_is_io_page_fault(l4_msgtag_t t) L4_NOTHROW;
 304
 305 /**
 306  * \defgroup l4_cap_api Capabilities
 307  * \ingroup l4_api
 308  * \brief Functions and definitions related to capabilities.
 309  *
 310  * C interface for capabilities:<br>
 311  * <c>\#include <l4/sys/types.h></c>
 312  */
 313 /**
 314  * \brief L4 Capability selector Type.
 315  * \ingroup l4_cap_api
 316  *
 317  * <c>\#include <l4/sys/types.h></c>
 318  */
 319 typedef unsigned long l4_cap_idx_t;
 320
 321 /**
 322  * \brief Test if a capability selector is the invalid capability.
 323  * \ingroup l4_cap_api
 324  * \param c Capability selector
 325  * \return Boolean value
 326  */
 327 L4_INLINE unsigned l4_is_invalid_cap(l4_cap_idx_t c) L4_NOTHROW;
 328
 329 /**
 330  * \brief Test if a capability selector is a valid selector.
 331  * \ingroup l4_cap_api
 332  * \param c Capability selector
 333  * \return Boolean value
 334  */
 335 L4_INLINE unsigned l4_is_valid_cap(l4_cap_idx_t c) L4_NOTHROW;
 336
 337 /**
 338  * \brief Test if two capability selectors are equal.
 339  * \ingroup l4_cap_api
 340  * \param c1 Capability
 341  * \param c2 Capability
 342  * \return 1 if equal, 0 if not equal
 343  */
 344 L4_INLINE unsigned l4_capability_equal(l4_cap_idx_t c1, l4_cap_idx_t c2) L4_NOTHROW;
 345
 346 /* ************************************************************************* */
 347 /* Implementation */
 348
 349 L4_INLINE unsigned
 350 l4_is_invalid_cap(l4_cap_idx_t c) L4_NOTHROW
 351 { return c & L4_INVALID_CAP_BIT; }
 352
 353 L4_INLINE unsigned
 354 l4_is_valid_cap(l4_cap_idx_t c) L4_NOTHROW
 355 { return !(c & L4_INVALID_CAP_BIT); }
 356
 357 L4_INLINE unsigned
 358 l4_capability_equal(l4_cap_idx_t c1, l4_cap_idx_t c2) L4_NOTHROW
 359 { return (c1 >> L4_CAP_SHIFT) == (c2 >> L4_CAP_SHIFT); }
 360
 361
 362 /**
 363  * Message tag functions
 364  */
 365 L4_INLINE
 366 l4_msgtag_t l4_msgtag(long label, unsigned words, unsigned items,
 367                       unsigned flags) L4_NOTHROW
 368 {
 369   return (l4_msgtag_t){(label << 16) | (l4_mword_t)(words & 0x3f)
 370                        | (l4_mword_t)((items & 0x3f) << 6)
 371                        | (l4_mword_t)(flags & 0xf000)};
 372 }
 373
 374
 375
 376 L4_INLINE
 377 long l4_msgtag_label(l4_msgtag_t t) L4_NOTHROW
 378 { return t.raw >> 16; }
 379
 380 L4_INLINE
 381 unsigned l4_msgtag_words(l4_msgtag_t t) L4_NOTHROW
 382 { return t.raw & 0x3f; }
 383
 384 L4_INLINE
 385 unsigned l4_msgtag_items(l4_msgtag_t t) L4_NOTHROW
 386 { return (t.raw >> 6) & 0x3f; }
 387
 388 L4_INLINE
 389 unsigned l4_msgtag_flags(l4_msgtag_t t) L4_NOTHROW
 390 { return t.raw & 0xf000; }
 391
 392
 393 L4_INLINE
 394 unsigned l4_msgtag_has_error(l4_msgtag_t t) L4_NOTHROW
 395 { return t.raw & L4_MSGTAG_ERROR; }
 396
 397
 398
 399 L4_INLINE unsigned l4_msgtag_is_page_fault(l4_msgtag_t t) L4_NOTHROW
 400 { return l4_msgtag_label(t) == L4_PROTO_PAGE_FAULT; }
 401
 402 L4_INLINE unsigned l4_msgtag_is_preemption(l4_msgtag_t t) L4_NOTHROW
 403 { return l4_msgtag_label(t) == L4_PROTO_PREEMPTION; }
 404
 405 L4_INLINE unsigned l4_msgtag_is_sys_exception(l4_msgtag_t t) L4_NOTHROW
 406 { return l4_msgtag_label(t) == L4_PROTO_SYS_EXCEPTION; }
 407
 408 L4_INLINE unsigned l4_msgtag_is_exception(l4_msgtag_t t) L4_NOTHROW
 409 { return l4_msgtag_label(t) == L4_PROTO_EXCEPTION; }
 410
 411 L4_INLINE unsigned l4_msgtag_is_sigma0(l4_msgtag_t t) L4_NOTHROW
 412 { return l4_msgtag_label(t) == L4_PROTO_SIGMA0; }
 413
 414 L4_INLINE unsigned l4_msgtag_is_io_page_fault(l4_msgtag_t t) L4_NOTHROW
 415 { return l4_msgtag_label(t) == L4_PROTO_IO_PAGE_FAULT; }