Loading...
Searching...
No Matches
L4Re::Env Class Reference

C++ interface of the initial environment that is provided to an L4 task. More...

`#include <env>`

Collaboration diagram for L4Re::Env:

## Public Types

typedef l4re_env_cap_entry_t | Cap_entry
| C++ type for an entry in the initial objects array.

## Public Member Functions

L4::Cap< Parent > | parent () const noexcept
| Object-capability to the parent.
L4::Cap< Mem_alloc > | mem_alloc () const noexcept
| Object-capability to the memory allocator.
L4::Cap< L4::Factory > | user_factory () const noexcept
| Object-capability to the user-level object factory.
L4::Cap< Rm > | rm () const noexcept
| Object-capability to the region map.
L4::Cap< Log > | log () const noexcept
| Object-capability to the logging service.
L4::Cap< L4::Thread > | main_thread () const noexcept
| Object-capability of the first user thread.
L4::Cap< L4::Task > | task () const noexcept
| Object-capability of the user task.
L4::Cap< L4::Factory > | factory () const noexcept
| Object-capability to the factory object available to the task.
l4_cap_idx_t | first_free_cap () const noexcept
| First available capability selector.
l4_fpage_t | utcb_area () const noexcept
| UTCB area of the task.
l4_addr_t | first_free_utcb () const noexcept
| First free UTCB.
Cap_entry const * | initial_caps () const noexcept
| Get a pointer to the first entry in the initial objects array.
Cap_entry const * | get (char const *name, unsigned l) const noexcept
| Get the Cap_entry for the object named name.
template<typename T>
L4::Cap< T > | get_cap (char const *name, unsigned l) const noexcept
| Get the capability selector for the object named name.
template<typename T>
L4::Cap< T > | get_cap (char const *name) const noexcept
| Get the capability selector for the object named name.
void | parent (L4::Cap< Parent > const &c) noexcept
| Set parent object-capability.
void | mem_alloc (L4::Cap< Mem_alloc > const &c) noexcept
| Set memory allocator object-capability.
void | rm (L4::Cap< Rm > const &c) noexcept
| Set region map object-capability.
void | log (L4::Cap< Log > const &c) noexcept
| Set log object-capability.
void | main_thread (L4::Cap< L4::Thread > const &c) noexcept
| Set object-capability of first user thread.
void | factory (L4::Cap< L4::Factory > const &c) noexcept
| Set factory object-capability.
void | first_free_cap (l4_cap_idx_t c) noexcept
| Set first available capability selector.
void | utcb_area (l4_fpage_t utcbs) noexcept
| Set UTCB area of the task.
void | first_free_utcb (l4_addr_t u) noexcept
| Set first free UTCB.
L4::Cap< L4::Scheduler > | scheduler () const noexcept
| Get the scheduler capability for the task.
void | scheduler (L4::Cap< L4::Scheduler > const &c) noexcept
| Set the scheduler capability.
L4::Cap< Itas > | itas () const noexcept
| Object-capability to the ITAS services.
void | itas (L4::Cap< Itas > const &c) noexcept
| Set the ITAS capability.
L4::Cap< Dbg_events > | dbg_events () const noexcept
| Object-capability to a debugger events service.
void | dbg_events (L4::Cap< Dbg_events > const &dbg_events) noexcept
| Set the dbg_events capability.
void | initial_caps (Cap_entry *first) noexcept
| Set the pointer to the first Cap_entry in the initial objects array.

## Static Public Member Functions

static Env const * | env () noexcept
| Returns the initial environment for the current task.

## Detailed Description

C++ interface of the initial environment that is provided to an L4 task.

The initial environment is provided to each L4 task that is started by an L4Re conform loader, such as the Moe root task. The initial environment provides access to a set of initial capabilities and some additional information about the available resources, such as free UTCBs (see Virtual Registers ) and available entries in capability table (provided by the micro kernel).

Each of the initial capabilities is stored at a fixed index in the task's capability table and the L4 runtime environment provides convenience functions to retrieve the capabilities. See the table below for an comprehensive overview.

Name | Object Type | Convenience Function
--- | --- | ---
parent | L4Re::Parent | L4Re::Env::parent()
user_factory | L4::Factory | L4Re::Env::user_factory()
log | L4Re::Log | L4Re::Env::log()
main_thread | L4::Thread | L4Re::Env::main_thread()
rm | L4Re::Rm | L4Re::Env::rm()
factory | L4::Factory | L4Re::Env::factory()
task | L4::Task | L4Re::Env::task()
scheduler | L4::Scheduler | L4Re::Env::scheduler()
itas | L4Re::Itas | L4Re::Env::itas()

Additional information found in the initial environment is:

- First free entry in capability table
- The UTCB area (as flexpage)
- First free UTCB (address in the UTCB area)

Include File
  #include <l4/re/env>
  env
  Environment interface.

For an explanation of the default task capabilites see l4_default_caps_t.

For the C interface refer to Initial Environment.

Definition at line 78 of file env.

## Member Function Documentation

## dbg_events() [1/2]

L4::Cap< Dbg_events > L4Re::Env::dbg_events | ( |  | ) | const

inlinenoexcept

Object-capability to a debugger events service.

Returns
  Dbg_events object-capability

This capability can be invalid.

Definition at line 310 of file env.

Referenced by dbg_events().

Here is the caller graph for this function:

## dbg_events() [2/2]

void L4Re::Env::dbg_events | ( | L4::Cap< Dbg_events > const & | dbg_events | ) |

inlinenoexcept

Set the dbg_events capability.

Parameters

  dbg_events | is the capability to be set for the debug events service.

Note that the capability can be invalid.

Definition at line 320 of file env.

References dbg_events().

Here is the call graph for this function:

## env()

Env const * L4Re::Env::env | ( |  | ) |

inlinestaticnoexcept

Returns the initial environment for the current task.

Returns
  Pointer to the initial environment class.

A typical use of this function is L4Re::Env::env()-><member>()

Examples
  examples/clntsrv/src/client.cc, examples/libs/l4re/c++/mem_alloc/ma+rm.cc, examples/libs/l4re/c++/shared_ds/ds_clnt.cc, examples/libs/l4re/c++/shared_ds/ds_srv.cc, examples/libs/l4re/streammap/client.cc, and examples/sys/migrate/thread_migrate.cc.

Definition at line 96 of file env.

Referenced by L4virtio::Svr::Dev_config::Dev_config(), L4virtio::Driver::Device::driver_connect(), L4vcpu::Vcpu::ext_alloc(), L4Re::Util::Event_t< Default_event_payload >::init(), L4Re::Util::Event_t< Default_event_payload >::init_poll(), L4Re::Util::kumem_alloc(), L4virtio::Driver::Block_device::setup_device(), and L4virtio::Driver::Virtio_net_device::setup_device().

Here is the caller graph for this function:

## factory() [1/2]

L4::Cap< L4::Factory > L4Re::Env::factory | ( |  | ) | const

inlinenoexcept

Object-capability to the factory object available to the task.

Returns
  Factory object-capability

Definition at line 144 of file env.

## factory() [2/2]

void L4Re::Env::factory | ( | L4::Cap< L4::Factory > const & | c | ) |

inlinenoexcept

Set factory object-capability.

Parameters

  c | Factory object-capability

Definition at line 249 of file env.

## first_free_cap() [1/2]

l4_cap_idx_t L4Re::Env::first_free_cap | ( |  | ) | const

inlinenoexcept

First available capability selector.

Returns
  First capability selector.

First capability selector available for use for in the application.

Definition at line 152 of file env.

## first_free_cap() [2/2]

void L4Re::Env::first_free_cap | ( | l4_cap_idx_t | c | ) |

inlinenoexcept

Set first available capability selector.

Parameters

  c | First capability selector available to the application.

Definition at line 255 of file env.

## first_free_utcb() [1/2]

l4_addr_t L4Re::Env::first_free_utcb | ( |  | ) | const

inlinenoexcept

First free UTCB.

Returns
  object-capability

First free UTCB within the UTCB area available for the application to use.

Definition at line 167 of file env.

## first_free_utcb() [2/2]

void L4Re::Env::first_free_utcb | ( | l4_addr_t | u | ) |

inlinenoexcept

Set first free UTCB.

Parameters

  u | First UTCB available for the application to use.

Definition at line 267 of file env.

## get()

Cap_entry const * L4Re::Env::get | ( | char const * | name,
|  | unsigned | l ) const

inlinenoexcept

Get the Cap_entry for the object named name.

Parameters

  name | is the name of the object.
  l | is the length of the name, thus name might not be zero terminated.

Returns
  A pointer to the Cap_entry for the object named name, or NULL if no such object was found.

Definition at line 185 of file env.

References l4re_env_get_cap_l().

Referenced by get_cap().

Here is the call graph for this function:
Here is the caller graph for this function:

## get_cap() [1/2]

template<typename T>

L4::Cap< T > L4Re::Env::get_cap | ( | char const * | name | ) | const

inlinenoexcept

Get the capability selector for the object named name.

Parameters

  name | is the name of the object (zero terminated).

Returns
  A capability selector for the object named name, or an invalid capability selector if no such object was found.

Definition at line 212 of file env.

References get_cap().

Here is the call graph for this function:

## get_cap() [2/2]

template<typename T>

L4::Cap< T > L4Re::Env::get_cap | ( | char const * | name,
|  | unsigned | l ) const

inlinenoexcept

Get the capability selector for the object named name.

Parameters

  name | is the name of the object.
  l | is the length of the name, thus name might not be zero terminated.

Returns
  A capability selector for the object named name, or an invalid capability selector if no such object was found.

Examples
  examples/clntsrv/src/client.cc, examples/libs/l4re/c++/shared_ds/ds_clnt.cc, and examples/libs/l4re/streammap/client.cc.

Definition at line 197 of file env.

References get(), and L4_ENOENT.

Referenced by get_cap().

Here is the call graph for this function:
Here is the caller graph for this function:

## initial_caps() [1/2]

Cap_entry const * L4Re::Env::initial_caps | ( |  | ) | const

inlinenoexcept

Get a pointer to the first entry in the initial objects array.

Returns
  A pointer to the first entry in the initial objects array.

Definition at line 174 of file env.

## initial_caps() [2/2]

void L4Re::Env::initial_caps | ( | Cap_entry * | first | ) |

inlinenoexcept

Set the pointer to the first Cap_entry in the initial objects array.

Parameters

  first | is the first element in the array.

Definition at line 327 of file env.

## itas() [1/2]

L4::Cap< Itas > L4Re::Env::itas | ( |  | ) | const

inlinenoexcept

Object-capability to the ITAS services.

Returns
  ITAS object-capability

Attention: this capability might be invalid, depending on the system configuration. Regular applications must not use it directly as it is an implementation detail of the L4Re libc that is subject to change without notice!

Definition at line 294 of file env.

## itas() [2/2]

void L4Re::Env::itas | ( | L4::Cap< Itas > const & | c | ) |

inlinenoexcept

Set the ITAS capability.

Parameters

  c | is the capability to be set as ITAS.

Definition at line 301 of file env.

## log() [1/2]

L4::Cap< Log > L4Re::Env::log | ( |  | ) | const

inlinenoexcept

Object-capability to the logging service.

Returns
  Log object-capability

Definition at line 126 of file env.

## log() [2/2]

void L4Re::Env::log | ( | L4::Cap< Log > const & | c | ) |

inlinenoexcept

Set log object-capability.

Parameters

  c | Log object-capability

Definition at line 237 of file env.

## main_thread() [1/2]

L4::Cap< L4::Thread > L4Re::Env::main_thread | ( |  | ) | const

inlinenoexcept

Object-capability of the first user thread.

Returns
  Object-capability of the first user thread.

Definition at line 132 of file env.

## main_thread() [2/2]

void L4Re::Env::main_thread | ( | L4::Cap< L4::Thread > const & | c | ) |

inlinenoexcept

Set object-capability of first user thread.

Parameters

  c | First thread's object-capability

Definition at line 243 of file env.

## mem_alloc() [1/2]

L4::Cap< Mem_alloc > L4Re::Env::mem_alloc | ( |  | ) | const

inlinenoexcept

Object-capability to the memory allocator.

Returns
  Memory allocator object-capability

Examples
  examples/libs/l4re/c++/shared_ds/ds_srv.cc.

Definition at line 109 of file env.

## mem_alloc() [2/2]

void L4Re::Env::mem_alloc | ( | L4::Cap< Mem_alloc > const & | c | ) |

inlinenoexcept

Set memory allocator object-capability.

Parameters

  c | Memory allocator object-capability

Definition at line 225 of file env.

## parent() [1/2]

L4::Cap< Parent > L4Re::Env::parent | ( |  | ) | const

inlinenoexcept

Object-capability to the parent.

Returns
  Parent object-capability

Definition at line 103 of file env.

## parent() [2/2]

void L4Re::Env::parent | ( | L4::Cap< Parent > const & | c | ) |

inlinenoexcept

Set parent object-capability.

Parameters

  c | Parent object-capability

Definition at line 219 of file env.

## rm() [1/2]

L4::Cap< Rm > L4Re::Env::rm | ( |  | ) | const

inlinenoexcept

Object-capability to the region map.

Returns
  Region map object-capability

Examples
  examples/libs/l4re/c++/shared_ds/ds_clnt.cc, and examples/libs/l4re/c++/shared_ds/ds_srv.cc.

Definition at line 120 of file env.

## rm() [2/2]

void L4Re::Env::rm | ( | L4::Cap< Rm > const & | c | ) |

inlinenoexcept

Set region map object-capability.

Parameters

  c | Region map object-capability

Definition at line 231 of file env.

## scheduler() [1/2]

L4::Cap< L4::Scheduler > L4Re::Env::scheduler | ( |  | ) | const

inlinenoexcept

Get the scheduler capability for the task.

Returns
  The capability selector for the default scheduler used for this task.

Definition at line 275 of file env.

## scheduler() [2/2]

void L4Re::Env::scheduler | ( | L4::Cap< L4::Scheduler > const & | c | ) |

inlinenoexcept

Set the scheduler capability.

Parameters

  c | is the capability to be set as scheduler.

Definition at line 282 of file env.

## task()

L4::Cap< L4::Task > L4Re::Env::task | ( |  | ) | const

inlinenoexcept

Object-capability of the user task.

Returns
  Object-capability of the user task.

Definition at line 138 of file env.

## utcb_area() [1/2]

l4_fpage_t L4Re::Env::utcb_area | ( |  | ) | const

inlinenoexcept

UTCB area of the task.

Returns
  UTCB area

Definition at line 158 of file env.

## utcb_area() [2/2]

void L4Re::Env::utcb_area | ( | l4_fpage_t | utcbs | ) |

inlinenoexcept

Set UTCB area of the task.

Parameters

  utcbs | UTCB area

Definition at line 261 of file env.

The documentation for this class was generated from the following file:

- l4/re/env