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