l4/pkg/l4sys/include/consts.h

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