l4/pkg/l4re/include/env.h

   1 /**
   2  * \file
   3  * \brief   Environment interface
   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
  22 #include <l4/sys/consts.h>
  23 #include <l4/sys/types.h>
  24 #include <l4/sys/kip.h>
  25
  26 #include <l4/re/consts.h>
  27
  28 /**
  29  * \brief Entry in the L4Re environment array for the named inital objects.
  30  * \ingroup api_l4re_env
  31  */
  32 typedef struct l4re_env_cap_entry_t
  33 {
  34   /**
  35    * \brief The capability selector for the obeject.
  36    */
  37   l4_cap_idx_t cap;
  38
  39   /**
  40    * \brief Some flags for the object.
  41    * \note Currently unused.
  42    */
  43   l4_umword_t flags;
  44
  45   /**
  46    * \brief The name of the object.
  47    */
  48   char name[16];
  49 #ifdef __cplusplus
  50
  51   /**
  52    * \brief Create an invalid entry.
  53    */
  54   l4re_env_cap_entry_t() : cap(L4_INVALID_CAP), flags(~0) {}
  55
  56   /**
  57    * \brief Create an entry with the name \a n, capability \a c, and
  58    *        flags \a f.
  59    *
  60    * \param n is the name of the initial object.
  61    * \param c is the capability selector that refers the initial object.
  62    * \param f are the additional flags for the object.
  63    */
  64   l4re_env_cap_entry_t(char const *n, l4_cap_idx_t c, l4_umword_t f = 0)
  65   : cap(c), flags(f)
  66   {
  67     for (unsigned i = 0; n && i < sizeof(name); ++i, ++n)
  68       {
  69         name[i] = *n;
  70         if (!*n)
  71           break;
  72       }
  73   }
  74 #endif
  75 } l4re_env_cap_entry_t;
  76
  77
  78 /**
  79  * \brief Initial Environment structure (C version)
  80  * \ingroup api_l4re_env
  81  *
  82  * \see \link api_l4re_env Initial environment \endlink
  83  */
  84 typedef struct l4re_env_t
  85 {
  86   l4_cap_idx_t parent;         /**< Parent object-capability */
  87   l4_cap_idx_t rm;             /**< Region map object-capability */
  88   l4_cap_idx_t mem_alloc;      /**< Memory allocator object-capability */
  89   l4_cap_idx_t log;            /**< Logging object-capability */
  90   l4_cap_idx_t main_thread;    /**< Object-capability of the first user thread */
  91   l4_cap_idx_t factory;        /**< Object-capability of the factory available to the task */
  92   l4_cap_idx_t scheduler;      /**< Object capability for the scheduler set to use */
  93   l4_cap_idx_t first_free_cap; /**< First capability index available to the application */
  94   l4_fpage_t utcb_area;        /**< UTCB area of the task */
  95   l4_addr_t first_free_utcb;   /**< First UTCB within the UTCB area available to the application */
  96   l4re_env_cap_entry_t *caps;
  97 } l4re_env_t;
  98
  99 /**
 100  * \internal
 101  * \brief Pointer to L4Re initial environment (C version).
 102  * \ingroup api_l4re_env
 103  */
 104 extern l4re_env_t *l4re_global_env;
 105
 106
 107 /**
 108  * \brief Get L4Re initial environment (C version).
 109  * \ingroup api_l4re_env
 110  * \return Pointer to L4Re initial environment (C version).
 111  */
 112 L4_INLINE l4re_env_t *l4re_env(void) L4_NOTHROW;
 113
 114 /*
 115  * FIXME: this seems to be at the wrong place here
 116  */
 117 /**
 118  * \brief Get Kernel Info Page.
 119  * \ingroup api_l4re_env
 120  * \return Pointer to Kernel Info Page (KIP) structure.
 121  */
 122 L4_INLINE l4_kernel_info_t *l4re_kip(void) L4_NOTHROW;
 123
 124
 125 /**
 126  * \brief Get the capability selector for the object named \a name.
 127  * \ingroup api_l4re_env
 128  * \param name is the name of the object to lookup in the initial objects.
 129  * \return A valid capability selector if the object exists or an invalid
 130  *         capability selector if not (l4_is_invalid_cap()).
 131  */
 132 L4_INLINE l4_cap_idx_t
 133 l4re_get_env_cap(char const *name) L4_NOTHROW;
 134
 135 /**
 136  * \brief Get the capability selector for the object named \a name.
 137  * \ingroup api_l4re_env
 138  * \param name is the name of the object to lookup in the initial objects.
 139  * \param e is the environment structure to use for the operation.
 140  * \return A valid capability selector if the object exists or an invalid
 141  *         capability selector if not (l4_is_invalid_cap()).
 142  */
 143 L4_INLINE l4_cap_idx_t
 144 l4re_get_env_cap_e(char const *name, l4re_env_t const *e) L4_NOTHROW;
 145
 146 /**
 147  * \brief Get the full l4re_env_cap_entry_t for the object named \a name.
 148  * \ingroup api_l4re_env
 149  * \param name is the name of the object to lookup in the initial objects.
 150  * \param l is the length of the name string, thus \a name might not be zero
 151  *          terminated.
 152  * \param e is the environment structure to use for the operation.
 153  * \return A pointer to an l4re_env_cap_entry_t if the object exists or
 154  *         NULL if not.
 155  */
 156 L4_INLINE l4re_env_cap_entry_t const *
 157 l4re_get_env_cap_l(char const *name, unsigned l, l4re_env_t const *e) L4_NOTHROW;
 158
 159
 160 L4_INLINE
 161 l4re_env_t *l4re_env() L4_NOTHROW
 162 { return l4re_global_env; }
 163
 164 L4_INLINE
 165 l4_kernel_info_t *l4re_kip() L4_NOTHROW
 166 {
 167   extern char __L4_KIP_ADDR__[1];
 168   return (l4_kernel_info_t *)__L4_KIP_ADDR__;
 169 }
 170
 171 L4_INLINE l4re_env_cap_entry_t const *
 172 l4re_get_env_cap_l(char const *name, unsigned l, l4re_env_t const *e) L4_NOTHROW
 173 {
 174   l4re_env_cap_entry_t const *c = e->caps;
 175   for (; c && c->flags != ~0UL; ++c)
 176     {
 177       unsigned i;
 178       char const *n = name;
 179       for (i = 0; i < sizeof(c->name) && i < l && c->name[i] && *n && *n == c->name[i]; ++i, ++n)
 180         ;
 181
 182       if (i == l && (i == sizeof(c->name) || !c->name[i]))
 183         return c;
 184     }
 185   return NULL;
 186 }
 187
 188 L4_INLINE l4_cap_idx_t
 189 l4re_get_env_cap_e(char const *name, l4re_env_t const *e) L4_NOTHROW
 190 {
 191   unsigned l;
 192   l4re_env_cap_entry_t const *r;
 193   for (l = 0; name[l]; ++l) ;
 194   r = l4re_get_env_cap_l(name, l, e);
 195   if (r)
 196     return r->cap;
 197
 198   return L4_INVALID_CAP;
 199 }
 200
 201 L4_INLINE l4_cap_idx_t
 202 l4re_get_env_cap(char const *name) L4_NOTHROW
 203 { return l4re_get_env_cap_e(name, l4re_env()); }
 204