5 * \brief Environment interface
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)
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.
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.
28 #include <l4/sys/types.h>
31 #include <l4/re/parent>
32 #include <l4/re/mem_alloc>
35 #include <l4/re/env.h>
42 * \brief L4 Runtime Environment.
47 * \defgroup api_l4re_env Initial Environment
49 * \brief Environment that is initially provided to an L4 task.
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).
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
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)
72 * \see L4Re::Env, l4re_env_t for more information.
77 * \brief Initial Environment (C++ version).
78 * \ingroup api_l4re_env
80 * This class provides an initial set of capabilities as well as
81 * information the first free UTCB and used capability slots.
83 * \see \link api_l4re_env Initial environment \endlink
92 * \brief C++ type for an entry in the initial objects array.
94 typedef l4re_env_cap_entry_t Cap_entry;
97 * \brief Returns the initial environment for the current task.
99 * \return Pointer to the initial environment class.
101 * A typical use of this function is L4Re::Env::env()->\<member\>()
103 static Env const *env() throw()
104 { return reinterpret_cast<Env*>(l4re_global_env); }
107 * \brief Object-capability to the parent.
108 * \return Parent object-capability
110 L4::Cap<Parent> parent() const throw()
111 { return L4::Cap<Parent>(_env.parent); }
113 * \brief Object-capability to the memory allocator.
114 * \return Memory allocator object-capability
116 L4::Cap<Mem_alloc> mem_alloc() const throw()
117 { return L4::Cap<Mem_alloc>(_env.mem_alloc); }
119 * \brief Object-capability to the region map.
120 * \return Region map object-capability
122 L4::Cap<Rm> rm() const throw()
123 { return L4::Cap<Rm>(_env.rm); }
125 * \brief Object-capability to the logging service.
126 * \return Log object-capability
128 L4::Cap<Log> log() const throw()
129 { return L4::Cap<Log>(_env.log); }
131 * \brief Object-capability of the first user thread.
132 * \return Object-capability of the first user thread.
134 L4::Cap<L4::Thread> main_thread() const throw()
135 { return L4::Cap<L4::Thread>(_env.main_thread); }
137 * \brief Object-capability of the user task.
138 * \return Object-capability of the user task.
140 L4::Cap<L4::Task> task() const throw()
141 { return L4::Cap<L4::Task>(L4_BASE_TASK_CAP); }
143 * \brief Object-capability to the factory object available to the task.
144 * \return Factory object-capability
146 L4::Cap<L4::Factory> factory() const throw()
147 { return L4::Cap<L4::Factory>(_env.factory); }
149 * \brief First available capability selector.
150 * \return First capability selector.
152 * First capability selector available for use for in the application.
154 l4_cap_idx_t first_free_cap() const throw()
155 { return _env.first_free_cap; }
157 * \brief UTCB area of the task.
160 l4_fpage_t utcb_area() const throw()
161 { return _env.utcb_area; }
163 * \brief First free UTCB.
164 * \return object-capability
166 * First free UTCB within the UTCB area available for the application to
169 l4_addr_t first_free_utcb() const throw()
170 { return _env.first_free_utcb; }
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.
176 Cap_entry const *initial_caps() const throw()
177 { return _env.caps; }
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
184 * \return A pointer to the Cap_entry for the object named \a name,
185 * or NULL if no such object was found.
187 Cap_entry const *get(char const *name, unsigned l) const throw()
188 { return l4re_env_get_cap_l(name, l, &_env); }
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
195 * \return A capability selector for the object named \a name,
196 * or an invalid capability selector if no such object was found.
198 template< typename T >
199 L4::Cap<T> get_cap(char const *name, unsigned l) const throw()
201 if (Cap_entry const *e = get(name, l))
202 return L4::Cap<T>(e->cap);
204 return L4::Cap<T>(-L4_ENOENT); //L4::Cap<T>::Invalid;
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.
213 template< typename T >
214 L4::Cap<T> get_cap(char const *name) const throw()
215 { return get_cap<T>(name, __builtin_strlen(name)); }
218 * \brief Set parent object-capability.
219 * \param c Parent object-capability
221 void parent(L4::Cap<Parent> const &c) throw()
222 { _env.parent = c.cap(); }
224 * \brief Set memory allocator object-capability.
225 * \param c Memory allocator object-capability
227 void mem_alloc(L4::Cap<Mem_alloc> const &c) throw()
228 { _env.mem_alloc = c.cap(); }
230 * \brief Set region map object-capability.
231 * \param c Region map object-capability
233 void rm(L4::Cap<Rm> const &c) throw()
234 { _env.rm = c.cap(); }
236 * \brief Set log object-capability.
237 * \param c Log object-capability
239 void log(L4::Cap<Log> const &c) throw()
240 { _env.log = c.cap(); }
242 * \brief Set object-capability of first user thread.
243 * \param c First thread's object-capability
245 void main_thread(L4::Cap<L4::Thread> const &c) throw()
246 { _env.main_thread = c.cap(); }
248 * \brief Set factory object-capability.
249 * \param c Factory object-capability
251 void factory(L4::Cap<L4::Factory> const &c) throw()
252 { _env.factory = c.cap(); }
254 * \brief Set first available capability selector.
255 * \param c First capability selector available to the application.
257 void first_free_cap(l4_cap_idx_t c) throw()
258 { _env.first_free_cap = c; }
260 * \brief Set UTCB area of the task.
261 * \param utcbs UTCB area
263 void utcb_area(l4_fpage_t utcbs) throw()
264 { _env.utcb_area = utcbs; }
266 * \brief Set first free UTCB.
267 * \param u First UTCB available for the application to use.
269 void first_free_utcb(l4_addr_t u) throw()
270 { _env.first_free_utcb = u; }
273 * \brief Get the scheduler capability for the task.
274 * \return The capability selector for the default scheduler used for this
277 L4::Cap<L4::Scheduler> scheduler() const throw()
278 { return L4::Cap<L4::Scheduler>(_env.scheduler); }
281 * \brief Set the scheduler capability.
282 * \param c is the capability to be set as scheduler.
284 void scheduler(L4::Cap<L4::Scheduler> const &c) throw()
285 { _env.scheduler = c.cap(); }
288 * \brief Set the pointer to the first Cap_entry in the initial objects
290 * \param first is the first element in the array.
292 void initial_caps(Cap_entry *first) throw()
293 { _env.caps = first; }