l4/pkg/l4re/include/env

   1 // -*- Mode: C++ -*-
   2 // vim:ft=cpp
   3 /**
   4  * \file
   5  * \brief   Environment interface
   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  *     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 #pragma once
  27
  28 #include <l4/sys/types.h>
  29
  30 #include <l4/re/rm>
  31 #include <l4/re/parent>
  32 #include <l4/re/mem_alloc>
  33 #include <l4/re/log>
  34
  35 #include <l4/re/env.h>
  36
  37 namespace L4 {
  38 class Scheduler;
  39 }
  40
  41 /**
  42  * \brief L4 Runtime Environment.
  43  */
  44 namespace L4Re
  45 {
  46   /**
  47    * \defgroup api_l4re_env Initial Environment
  48    * \ingroup api_l4re
  49    * \brief Environment that is initially provided to an L4 task.
  50    *
  51    * The initial environment is provided to each L4 task that is started
  52    * by an L4Re conform loader, such as the Moe root task. The initial
  53    * environment provides access to a set of initial capabilities and
  54    * some additional information about the available resources, such as
  55    * free UTCBs (see \link l4_utcb_api Virtual Registers \endlink) and
  56    * available entries in capability table (provided by the micro kernel).
  57    *
  58    * The initial set of capabilities is:
  59    * - C[parent:L4Re::Parent] --- parent object
  60    * - C[mem_alloc:L4Re::Mem_alloc] --- initial memory allocator
  61    * - C[log:L4Re::Log] --- logging facility
  62    * - C[main_thread:L4::Thread] --- first application thread
  63    * - C[rm:L4::Rm] --- region manager
  64    * - C[factory:L4::Factory] --- factory to create kernel objects
  65    * - C[task:L4::Task] --- the task itself
  66    *
  67    * Additional information is:
  68    * - First free entry in capability table
  69    * - The \link l4_utcb_api UTCB \endlink area (as flex page)
  70    * - First free UTCB (address in the UTCB area)
  71    *
  72    * \see L4Re::Env, l4re_env_t for more information.
  73    *
  74    */
  75
  76   /**
  77    * \brief Initial Environment (C++ version).
  78    * \ingroup api_l4re_env
  79    *
  80    * This class provides an initial set of capabilities as well as
  81    * information the first free UTCB and used capability slots.
  82    *
  83    * \see \link api_l4re_env Initial environment \endlink
  84    */
  85   class L4_EXPORT Env
  86   {
  87   private:
  88     l4re_env_t _env;
  89   public:
  90
  91     /**
  92      * \brief C++ type for an entry in the initial objects array.
  93      */
  94     typedef l4re_env_cap_entry_t Cap_entry;
  95
  96     /**
  97      * \brief Returns the initial environment for the current task.
  98      *
  99      * \return Pointer to the initial environment class.
 100      *
 101      * A typical use of this function is L4Re::Env::env()->\<member\>()
 102      */
 103     static Env const *env() throw()
 104     { return reinterpret_cast<Env*>(l4re_global_env); }
 105
 106     /**
 107      * \brief Object-capability to the parent.
 108      * \return Parent object-capability
 109      */
 110     L4::Cap<Parent> parent() const throw()
 111     { return L4::Cap<Parent>(_env.parent); }
 112     /**
 113      * \brief Object-capability to the memory allocator.
 114      * \return Memory allocator object-capability
 115      */
 116     L4::Cap<Mem_alloc> mem_alloc() const throw()
 117     { return L4::Cap<Mem_alloc>(_env.mem_alloc); }
 118     /**
 119      * \brief Object-capability to the region map.
 120      * \return Region map object-capability
 121      */
 122     L4::Cap<Rm> rm() const throw()
 123     { return L4::Cap<Rm>(_env.rm); }
 124     /**
 125      * \brief Object-capability to the logging service.
 126      * \return Log object-capability
 127      */
 128     L4::Cap<Log> log() const throw()
 129     { return L4::Cap<Log>(_env.log); }
 130     /**
 131      * \brief Object-capability of the first user thread.
 132      * \return Object-capability of the first user thread.
 133      */
 134     L4::Cap<L4::Thread> main_thread() const throw()
 135     { return L4::Cap<L4::Thread>(_env.main_thread); }
 136     /**
 137      * \brief Object-capability of the user task.
 138      * \return Object-capability of the user task.
 139      */
 140     L4::Cap<L4::Task> task() const throw()
 141     { return L4::Cap<L4::Task>(L4_BASE_TASK_CAP); }
 142     /**
 143      * \brief Object-capability to the factory object available to the task.
 144      * \return Factory object-capability
 145      */
 146     L4::Cap<L4::Factory> factory() const throw()
 147     { return L4::Cap<L4::Factory>(_env.factory); }
 148     /**
 149      * \brief First available capability selector.
 150      * \return First capability selector.
 151      *
 152      * First capability selector available for use for in the application.
 153      */
 154     l4_cap_idx_t first_free_cap() const throw()
 155     { return _env.first_free_cap; }
 156     /**
 157      * \brief UTCB area of the task.
 158      * \return UTCB area
 159      */
 160     l4_fpage_t utcb_area() const throw()
 161     { return _env.utcb_area; }
 162     /**
 163      * \brief First free UTCB.
 164      * \return object-capability
 165      *
 166      * First free UTCB within the UTCB area available for the application to
 167      * use.
 168      */
 169     l4_addr_t first_free_utcb() const throw()
 170     { return _env.first_free_utcb; }
 171
 172     /**
 173      * \brief Get a pointer to the first entry in the initial objects array.
 174      * \return A pointer to the first entry in the initial objects array.
 175      */
 176     Cap_entry const *initial_caps() const throw()
 177     { return _env.caps; }
 178
 179     /**
 180      * \brief Get the Cap_entry for the object named \a name.
 181      * \param name is the name of the object.
 182      * \param l is the length of the name, thus \a name might mot be
 183      *          zero terminated.
 184      * \return A pointer to the Cap_entry for the object named \a name,
 185      *         or NULL if no such object was found.
 186      */
 187     Cap_entry const *get(char const *name, unsigned l) const throw()
 188     { return l4re_env_get_cap_l(name, l, &_env); }
 189
 190     /**
 191      * \brief Get the capability selector for the object named \a name.
 192      * \param name is the name of the object.
 193      * \param l is the length of the name, thus \a name might mot be
 194      *          zero terminated.
 195      * \return A capability selector for the object named \a name,
 196      *         or an invalid capability selector if no such object was found.
 197      */
 198     template< typename T >
 199     L4::Cap<T> get_cap(char const *name, unsigned l) const throw()
 200     {
 201       if (Cap_entry const *e = get(name, l))
 202         return L4::Cap<T>(e->cap);
 203
 204       return L4::Cap<T>(-L4_ENOENT);
 205     }
 206
 207     /**
 208      * \brief Get the capability selector for the object named \a name.
 209      * \param name is the name of the object (zero terminated).
 210      * \return A capability selector for the object named \a name,
 211      *         or an invalid capability selector if no such object was found.
 212      */
 213     template< typename T >
 214     L4::Cap<T> get_cap(char const *name) const throw()
 215     { return get_cap<T>(name, __builtin_strlen(name)); }
 216
 217     /**
 218      * \brief Set parent object-capability.
 219      * \param c  Parent object-capability
 220      */
 221     void parent(L4::Cap<Parent> const &c) throw()
 222     { _env.parent = c.cap(); }
 223     /**
 224      * \brief Set memory allocator object-capability.
 225      * \param c  Memory allocator object-capability
 226      */
 227     void mem_alloc(L4::Cap<Mem_alloc> const &c) throw()
 228     { _env.mem_alloc = c.cap(); }
 229     /**
 230      * \brief Set region map object-capability.
 231      * \param c  Region map object-capability
 232      */
 233     void rm(L4::Cap<Rm> const &c) throw()
 234     { _env.rm = c.cap(); }
 235     /**
 236      * \brief Set log object-capability.
 237      * \param c  Log object-capability
 238      */
 239     void log(L4::Cap<Log> const &c) throw()
 240     { _env.log = c.cap(); }
 241     /**
 242      * \brief Set object-capability of first user thread.
 243      * \param c  First thread's object-capability
 244      */
 245     void main_thread(L4::Cap<L4::Thread> const &c) throw()
 246     { _env.main_thread = c.cap(); }
 247     /**
 248      * \brief Set factory object-capability.
 249      * \param c  Factory object-capability
 250      */
 251     void factory(L4::Cap<L4::Factory> const &c) throw()
 252     { _env.factory = c.cap(); }
 253     /**
 254      * \brief Set first available capability selector.
 255      * \param c First capability selector available to the application.
 256      */
 257     void first_free_cap(l4_cap_idx_t c) throw()
 258     { _env.first_free_cap = c; }
 259     /**
 260      * \brief Set UTCB area of the task.
 261      * \param utcbs  UTCB area
 262      */
 263     void utcb_area(l4_fpage_t utcbs) throw()
 264     { _env.utcb_area = utcbs; }
 265     /**
 266      * \brief Set first free UTCB.
 267      * \param u First UTCB available for the application to use.
 268      */
 269     void first_free_utcb(l4_addr_t u) throw()
 270     { _env.first_free_utcb = u; }
 271
 272     /**
 273      * \brief Get the scheduler capability for the task.
 274      * \return The capability selector for the default scheduler used for this
 275      *         task.
 276      */
 277     L4::Cap<L4::Scheduler> scheduler() const throw()
 278     { return L4::Cap<L4::Scheduler>(_env.scheduler); }
 279
 280     /**
 281      * \brief Set the scheduler capability.
 282      * \param c is the capability to be set as scheduler.
 283      */
 284     void scheduler(L4::Cap<L4::Scheduler> const &c) throw()
 285     { _env.scheduler = c.cap(); }
 286
 287     /**
 288      * \brief Set the pointer to the first Cap_entry in the initial objects
 289      *        array.
 290      * \param first is the first element in the array.
 291      */
 292     void initial_caps(Cap_entry *first) throw()
 293     { _env.caps = first; }
 294   };
 295 };