l4/pkg/l4sys/include/consts.h

   1 /**
   2  * \file
   3  * \brief   Common constants.
   4  * \ingroup l4_api
   5  */
   6 /*
   7  * (c) 2008-2009 Technische Universität Dresden
   8  * This file is part of TUD:OS and distributed under the terms of the
   9  * GNU General Public License 2.
  10  * Please see the COPYING-GPL-2 file for details.
  11  *
  12  * As a special exception, you may use this file as part of a free software
  13  * library without restriction.  Specifically, if other files instantiate
  14  * templates or use macros or inline functions from this file, or you compile
  15  * this file and link it with other files to produce an executable, this
  16  * file does not by itself cause the resulting executable to be covered by
  17  * the GNU General Public License.  This exception does not however
  18  * invalidate any other reasons why the executable file might be covered by
  19  * the GNU General Public License.
  20  */
  21 #ifndef __L4_SYS__INCLUDE__CONSTS_H__
  22 #define __L4_SYS__INCLUDE__CONSTS_H__
  23
  24 #include <l4/sys/compiler.h>
  25 #include <l4/sys/l4int.h>
  26
  27 /**
  28  * \addtogroup l4_cap_api
  29  *
  30  * <c>\#include <l4/sys/consts.h></c>
  31  */
  32
  33 /**
  34  * \brief Capability selector flags.
  35  * \ingroup l4_ipc_api
  36  *
  37  * These flags determine the concrete operation when a kernel object
  38  * is invoked.
  39  */
  40 enum l4_syscall_flags_t
  41 {
  42   /**
  43    * \brief Default flags (call to a kernel object).
  44    * \hideinitializer
  45    *
  46    * Using this value as flags in the capability selector for an
  47    * invocation indicates a call (send and wait for a reply).
  48    */
  49   L4_SYSF_NONE      = 0x00,
  50
  51   /**
  52    * \brief Send-phase flag.
  53    * \hideinitializer
  54    *
  55    * Setting this flag in a capability selector induces a send phase,
  56    * this means a message is send to the object denoted by the capability.
  57    * For receive phase see #L4_SYSF_RECV.
  58    */
  59   L4_SYSF_SEND      = 0x01,
  60
  61   /**
  62    * \brief Receive-phase flag.
  63    * \hideinitializer
  64    *
  65    * Setting this flag in a capability selector induces a receive phase,
  66    * this means the invoking thread waits for a message from the object
  67    * denoted by the capability.
  68    * For a send phase see #L4_SYSF_SEND.
  69    */
  70   L4_SYSF_RECV      = 0x02,
  71
  72   /**
  73    * \brief Open-wait flag.
  74    * \hideinitializer
  75    *
  76    * This flag indicates that the receive operation (see #L4_SYSF_RECV)
  77    * shall be an \em open \em wait. \em Open \em wait means that the invoking
  78    * thread shall wait for a message from any possible sender and \em not from
  79    * the sender denoted by the capability.
  80    */
  81   L4_SYSF_OPEN_WAIT = 0x04,
  82
  83   /**
  84    * \brief Reply flag.
  85    * \hideinitializer
  86    *
  87    * This flag indicates that the send phase shall use the in-kernel reply
  88    * capability instead of the capability denoted by the selector index.
  89    */
  90   L4_SYSF_REPLY     = 0x08,
  91
  92   /**
  93    * \brief Call flags (combines send and receive).
  94    * \hideinitializer
  95    *
  96    * Combines #L4_SYSF_SEND and L4_SYSF_RECV.
  97    */
  98   L4_SYSF_CALL           = L4_SYSF_SEND | L4_SYSF_RECV,
  99
 100   /**
 101    * \brief Wait flags (combines receive and open wait).
 102    * \hideinitializer
 103    *
 104    * Combines #L4_SYSF_RECV and #L4_SYSF_OPEN_WAIT.
 105    */
 106   L4_SYSF_WAIT           = L4_SYSF_OPEN_WAIT | L4_SYSF_RECV,
 107
 108   /**
 109    * \brief Send-and-wait flags.
 110    * \hideinitializer
 111    *
 112    * Combines #L4_SYSF_SEND and #L4_SYSF_WAIT.
 113    */
 114   L4_SYSF_SEND_AND_WAIT  = L4_SYSF_OPEN_WAIT | L4_SYSF_CALL,
 115
 116   /**
 117    * \brief Reply-and-wait flags.
 118    * \hideinitializer
 119    *
 120    * Combines #L4_SYSF_SEND, #L4_SYSF_REPLY, and #L4_SYSF_WAIT.
 121    */
 122   L4_SYSF_REPLY_AND_WAIT = L4_SYSF_WAIT | L4_SYSF_SEND | L4_SYSF_REPLY
 123 };
 124
 125 /**
 126  * \brief Constants related to capability selectors.
 127  * \ingroup l4_cap_api
 128  */
 129 enum l4_cap_consts_t
 130 {
 131   /** \brief Capability index shift. \hideinitializer */
 132   L4_CAP_SHIFT   = 12UL,
 133   /** \brief Offset of two consecutive capability selectors. \hideinitializer */
 134   L4_CAP_SIZE    = 1UL << L4_CAP_SHIFT,
 135   L4_CAP_OFFSET  = 1UL << L4_CAP_SHIFT,
 136   /**
 137    * \brief Mask to get only the relevant bits of an l4_cap_idx_t.
 138    * \hideinitializer
 139    */
 140   L4_CAP_MASK    = ~0UL << (L4_CAP_SHIFT -1),
 141   /** \brief Invalid capability selector. \hideinitializer */
 142   L4_INVALID_CAP = ~0UL << (L4_CAP_SHIFT -1),
 143
 144   L4_INVALID_CAP_BIT = 1UL << (L4_CAP_SHIFT -1),
 145 };
 146
 147 enum l4_sched_consts_t
 148 {
 149   L4_SCHED_MIN_PRIO = 0,
 150   L4_SCHED_MAX_PRIO = 255,
 151 };
 152
 153 /**
 154  * \brief Flags for the unmap operation.
 155  * \ingroup l4_task_api
 156  * \see L4::Task::unmap() and l4_task_unmap()
 157  */
 158 enum l4_unmap_flags_t
 159 {
 160   /**
 161    * \brief Flag to tell the unmap operation to unmap all child mappings
 162    *        including the mapping in the invoked task.
 163    * \hideinitializer
 164    * \see L4::Task::unmap() l4_task_unmap()
 165    */
 166   L4_FP_ALL_SPACES   = 0x80000000UL,
 167
 168   /**
 169    * \brief Flag that indicates that the unmap operation on a capability
 170    *        shall try to delete the corresponding objects immediately.
 171    * \hideinitializer
 172    * \see L4::Task::unmap() l4_task_unmap()
 173    */
 174   L4_FP_DELETE_OBJ   = 0xc0000000UL,
 175
 176   /**
 177    * \brief Counterpart to #L4_FP_ALL_SPACES, unmap only child mappings.
 178    * \hideinitializer
 179    * \see L4::Task::unmap() l4_task_unmap()
 180    */
 181   L4_FP_OTHER_SPACES = 0x0UL
 182 };
 183
 184 /**
 185  * \brief Constants for message items.
 186  * \ingroup l4_msgitem_api
 187  */
 188 enum l4_msg_item_consts_t
 189 {
 190   L4_ITEM_STR       = 0, ///< \deprecated
 191   L4_ITEM_MAP       = 8, ///< Identify a message item as \em map \em item.
 192
 193   /**
 194    * \brief Donote that the following item shall be put into the same receive
 195    *        item as this one.
 196    */
 197   L4_ITEM_CONT      = 1,
 198
 199   // send
 200   L4_MAP_ITEM_GRANT = 2, ///< Flag as \em grant instead of \em map operation.
 201   L4_MAP_ITEM_MAP   = 0, ///< Flag as usual \em map operation.
 202
 203   // receive
 204   /**
 205    * \brief Mark the receive buffer to be a small receive item that describes
 206    *        a buffer for a single capability.
 207    */
 208   L4_RCV_ITEM_SINGLE_CAP = L4_ITEM_MAP | 2,
 209
 210   /**
 211    * \brief The receiver requests to receive a local ID instead of a mapping
 212    *        whenever possible.
 213    */
 214   L4_RCV_ITEM_LOCAL_ID   = 4,
 215 };
 216
 217 /**
 218  * \brief Constants for buffer descriptors.
 219  * \ingroup l4_utcb_br_api
 220  */
 221 enum l4_buffer_desc_consts_t
 222 {
 223   L4_BDR_MEM_SHIFT   = 0,  ///< Bit offset for the memory-buffer index
 224   L4_BDR_IO_SHIFT    = 5,  ///< Bit offset for the IO-buffer index
 225   L4_BDR_OBJ_SHIFT   = 10, ///< Bit offset for the capability-buffer index
 226   L4_BDR_OFFSET_MASK = (1UL << 20) - 1,
 227 };
 228
 229 /**
 230  * \brief Default capabilities setup for the initial tasks.
 231  * \ingroup l4_cap_api
 232  *
 233  * <c>\#include <l4/sys/consts.h></c>
 234  *
 235  * These capability selectors are setup per default by the micro kernel
 236  * for the two initial tasks, the Root-Pager (Sigma0) and the Root-Task
 237  * (Moe).
 238  *
 239  * \attention This constants do not have any particular meaning for
 240  *            applications started by Moe, see \ref api_l4re_env for
 241  *            this kind of information.
 242  * \see \ref api_l4re_env for information useful for normal user applications.
 243  */
 244 enum l4_default_caps_t
 245 {
 246   /// Capability selector for the current task. \hideinitializer
 247   L4_BASE_TASK_CAP      = 1UL << L4_CAP_SHIFT,
 248   /// Capability selector for the factory.      \hideinitializer
 249   L4_BASE_FACTORY_CAP   = 2UL << L4_CAP_SHIFT,
 250   /// Capability selector for the first thread. \hideinitializer
 251   L4_BASE_THREAD_CAP    = 3UL << L4_CAP_SHIFT,
 252   /// Capability selector for the pager gate.   \hideinitializer
 253   L4_BASE_PAGER_CAP     = 4UL << L4_CAP_SHIFT,
 254   /// Capability selector for the log object.   \hideinitializer
 255   L4_BASE_LOG_CAP       = 5UL << L4_CAP_SHIFT,
 256   /// Capability selector for the base icu object.   \hideinitializer
 257   L4_BASE_ICU_CAP       = 6UL << L4_CAP_SHIFT,
 258   /// Capability selector for the scheduler cap.   \hideinitializer
 259   L4_BASE_SCHEDULER_CAP = 7UL << L4_CAP_SHIFT,
 260 };
 261
 262 /**
 263  * \defgroup l4_memory_api Memory related
 264  * \brief Memory related constants, data types and functions.
 265  * \ingroup l4_api
 266  */
 267 /**
 268  * \brief Minimal page size (in bytes).
 269  * \ingroup l4_memory_api
 270  * \hideinitializer
 271  */
 272 #define L4_PAGESIZE             (1UL << L4_PAGESHIFT)
 273
 274 /**
 275  * \brief Mask for the page number.
 276  * \ingroup l4_memory_api
 277  * \hideinitializer
 278  *
 279  * \note The most significant bits are set.
 280  */
 281 #define L4_PAGEMASK             (~(L4_PAGESIZE - 1))
 282
 283 /**
 284  * \brief Number of bits used for page offset.
 285  * \ingroup l4_memory_api
 286  * \hideinitializer
 287  *
 288  * Size of page in log2.
 289  */
 290 #define L4_LOG2_PAGESIZE        L4_PAGESHIFT
 291
 292 /**
 293  * \brief Size of a large page.
 294  * \ingroup l4_memory_api
 295  * \hideinitializer
 296  *
 297  * A large page is a \em super \em page on IA32 or a \em section on ARM.
 298  */
 299 #define L4_SUPERPAGESIZE        (1UL << L4_SUPERPAGESHIFT)
 300
 301 /**
 302  * \brief Mask for the number of a large page.
 303  * \ingroup l4_memory_api
 304  * \hideinitializer
 305  *
 306  * \note The most significant bits are set.
 307  */
 308 #define L4_SUPERPAGEMASK        (~(L4_SUPERPAGESIZE - 1))
 309
 310 /**
 311  * \brief Number of bits used as offset for a large page.
 312  * \ingroup l4_memory_api
 313  * \hideinitializer
 314  * Size of large page in log2
 315  */
 316 #define L4_LOG2_SUPERPAGESIZE   L4_SUPERPAGESHIFT
 317
 318 /**
 319  * \brief Round an address down to the next lower page boundary.
 320  * \ingroup l4_memory_api
 321  *
 322  * \param   address The address to round.
 323  */
 324 L4_INLINE l4_addr_t l4_trunc_page(l4_addr_t address) L4_NOTHROW;
 325 L4_INLINE l4_addr_t l4_trunc_page(l4_addr_t x) L4_NOTHROW
 326 { return x & L4_PAGEMASK; }
 327
 328 /**
 329  * \brief Round an address down to the next lower flex page with size \a bits.
 330  * \ingroup l4_memory_api
 331  *
 332  * \param address The address to round.
 333  * \param bits    The size of the flex page (log2).
 334  */
 335 L4_INLINE l4_addr_t l4_trunc_size(l4_addr_t address, unsigned char bits) L4_NOTHROW;
 336 L4_INLINE l4_addr_t l4_trunc_size(l4_addr_t x, unsigned char bits) L4_NOTHROW
 337 { return x & (~0UL << bits); }
 338
 339 /**
 340  * \brief Round address up to the next page.
 341  * \ingroup l4_memory_api
 342  *
 343  * \param   address The address to round up.
 344  */
 345 L4_INLINE l4_addr_t l4_round_page(l4_addr_t address) L4_NOTHROW;
 346 L4_INLINE l4_addr_t l4_round_page(l4_addr_t x) L4_NOTHROW
 347 { return (x + L4_PAGESIZE-1) & L4_PAGEMASK; }
 348
 349 /**
 350  * \brief Round address up to the next flex page with \a bits size.
 351  * \ingroup l4_memory_api
 352  *
 353  * \param address The address to round up to the next flex page.
 354  * \param bits    The size of the flex page (log2).
 355  */
 356 L4_INLINE l4_addr_t l4_round_size(l4_addr_t address, unsigned char bits) L4_NOTHROW;
 357 L4_INLINE l4_addr_t l4_round_size(l4_addr_t x, unsigned char bits) L4_NOTHROW
 358 { return (x + (1UL << bits) - 1) & (~0UL << bits); }
 359
 360
 361 /**
 362  * \brief Address related constants.
 363  * \ingroup l4_memory_api
 364  */
 365 enum l4_addr_consts_t {
 366   /// Invalid address.
 367   L4_INVALID_ADDR = ~0UL
 368 };
 369
 370 /**
 371  * \brief Invalid address as pointer type.
 372  * \ingroup l4_memory_api
 373  */
 374 #define L4_INVALID_PTR ((void*)L4_INVALID_ADDR)
 375
 376 #ifndef NULL
 377 #ifndef __cplusplus
 378 # define NULL ((void *)0)  /**< \ingroup l4sys_defines
 379                             **  \hideinitializer
 380                             ** NULL
 381                             **/
 382 #else
 383 # define NULL 0
 384 #endif
 385 #endif
 386
 387 #endif /* ! __L4_SYS__INCLUDE__CONSTS_H__ */