Loading...
Searching...
No Matches
L4::Factory Class Reference

C++ Factory interface, see Factory for the C interface. More...

`#include <factory>`

Inheritance diagram for L4::Factory:
Collaboration diagram for L4::Factory:

## Data Structures

struct | Nil
| Special type to add a void argument into the factory create stream. More...
struct | Lstr
| Special type to add a pascal string into the factory create stream. More...
class | S
| Stream class for the create() argument stream. More...

## Public Member Functions

S | create (Cap< void > target, long obj, l4_utcb_t *utcb=l4_utcb()) noexcept
| Generic create call to the factory.
template<typename OBJ>
S | create (Cap< OBJ > target, l4_utcb_t *utcb=l4_utcb()) noexcept
| Create call for typed capabilities.
l4_msgtag_t | create_task (Cap< Task > const &target_cap, l4_fpage_t *utcb_area, l4_utcb_t *utcb=l4_utcb()) noexcept
| Create a new task.
l4_msgtag_t | create_factory (Cap< Factory > const &target_cap, unsigned long limit, l4_utcb_t *utcb=l4_utcb()) noexcept
| Create a new factory.
l4_msgtag_t | create_gate (Cap< void > const &target_cap, Cap< Snd_destination > const &snd_dst_cap, l4_umword_t label, l4_utcb_t *utcb=l4_utcb()) noexcept
| Create a new IPC gate, optionally bound to a send destination (a thread or thread group).
l4_msgtag_t | create_thread_group (Cap< Thread_group > const &target_cap, unsigned policy, l4_utcb_t *utcb=l4_utcb()) noexcept
| Create a new thread group.
Public Member Functions inherited from L4::Kobject
l4_msgtag_t | dec_refcnt (l4_mword_t diff, l4_utcb_t *utcb=l4_utcb())
| Decrement the in kernel reference counter for the object.

## Additional Inherited Members

Protected Types inherited from L4::Kobject_t< Factory, Kobject, L4_PROTO_FACTORY >
typedef Factory | Class
| The target interface type (inheriting from Kobject_t).
typedef Typeid::Iface< PROTO, Factory > | __Iface
| The interface description for the derived class.
typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Kobject::__Iface_list > | __Iface_list
| The list of all RPC interfaces provided directly or through inheritance.
Protected Member Functions inherited from L4::Kobject_t< Factory, Kobject, L4_PROTO_FACTORY >
L4::Cap< Class > | c () const noexcept
| Get the capability to ourselves.
Protected Member Functions inherited from L4::Kobject
l4_cap_idx_t | cap () const noexcept
| Return capability selector.
Static Protected Member Functions inherited from L4::Kobject_t< Factory, Kobject, L4_PROTO_FACTORY >
static void | __check_protocols__ () noexcept
| Helper to check for protocol conflicts.

## Detailed Description

C++ Factory interface, see Factory for the C interface.

Factories provide an interface to create objects which are accessed via capabilities.

For additional information about which objects can be created via this interface, see server-specific information in Kernel Factory and L4Re Servers.

Include File
  #include <l4/sys/factory>
  factory
  Common factory related definitions.

For the C interface refer to Factory.

Definition at line 38 of file factory.

## Member Function Documentation

## create() [1/2]

template<typename OBJ>

S L4::Factory::create | ( | Cap< OBJ > | target,
|  | l4_utcb_t * | utcb = l4_utcb() )

inlinenoexcept

Create call for typed capabilities.

Template Parameters

  OBJ | Capability type of the object to be created.

Parameters

  [out] | target | Capability of type OBJ.
  | utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns
  A create stream that allows additional arguments to be passed to the create() call via the left-shift (<<) operator (see #S::operator <<).

This method does not directly invoke the factory. The factory is invoked when the create stream returned by this method is converted to an l4_msgtag_t (see S::operator l4_msgtag_t()), or otherwise when the stream goes out of scope (not rcommended; see #S::~S()).

Precondition
  The invoked Factory capability must have the permission L4_CAP_FPAGE_S, otherwise the later factory IPC will fail with L4_EPERM (see S::operator l4_msgtag_t()).

Note
  The create stream uses the UTCB to store parameters for the service call. During the lifetime of a create stream or, until it is converted to an l4_msgtag_t, other UTCB-using operations must not be used.

Usage:

L4::Cap<L4Re::Dataspace> ds = L4Re::Util::cap_alloc.alloc<L4Re::Dataspace>();
factory->create(ds) << l4_mword_t(size_in_bytes);
L4Re::Dataspace
Interface for memory-like objects.
Definition dataspace:53
L4::Cap
C++ interface for capabilities.
Definition capability.h:224
l4_mword_t
signed long l4_mword_t
Signed machine word.
Definition l4int.h:37
L4Re::Util::cap_alloc
_Cap_alloc & cap_alloc
Capability allocator.

Definition at line 329 of file factory.

References L4::Kobject::cap().

Here is the call graph for this function:

## create() [2/2]

S L4::Factory::create | ( | Cap< void > | target,
|  | long | obj,
|  | l4_utcb_t * | utcb = l4_utcb() )

inlinenoexcept

Generic create call to the factory.

Parameters

  [out] | target | Capability selector for the new object. The caller must allocate the capability slot. The kernel stores the new objects's capability into this slot.
  | obj | The protocol ID that specifies which kind of object shall be created.
  | utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns
  A create stream that allows additional arguments to be passed to the create() call via the left-shift (<<) operator (see #S::operator <<).

This method does not directly invoke the factory. The factory is invoked when the create stream returned by this method is converted to an l4_msgtag_t (see S::operator l4_msgtag_t()), or otherwise when the stream goes out of scope (not recommended; see #S::~S()).

Precondition
  The invoked Factory capability must have the permission L4_CAP_FPAGE_S, otherwise the later factory IPC will fail with L4_EPERM (see S::operator l4_msgtag_t()).

Note
  The create stream uses the UTCB to store parameters for the service call. During the lifetime of a create stream or, until it is converted to an l4_msgtag_t, other UTCB-using operations must not be used.

See also
  create(Cap<OBJ>, l4_utcb_t *)

Definition at line 292 of file factory.

References L4::Kobject::cap().

Here is the call graph for this function:

## create_factory()

l4_msgtag_t L4::Factory::create_factory | ( | Cap< Factory > const & | target_cap,
|  | unsigned long | limit,
|  | l4_utcb_t * | utcb = l4_utcb() )

inlinenoexcept

Create a new factory.

Parameters

  [out] | target_cap | The kernel stores the new factory's capability into this slot.
  | limit | Limit for the new factory in bytes.
  | utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns
  Syscall return tag

Return values

  L4_EOK | No error occurred.
  -L4_EPERM | Insufficient permissions; see precondition.
  <0 | Error code.

Precondition
  The invoked Factory capability must have the permission L4_CAP_FPAGE_S.

Note
  In addition to memory needed for internal data structures, the limit (quota) of the new factory is counted towards the quota of the creating factory. The limit must be within 1 ≤ limit ≤ 2^(8 * sizeof(l4_umword_t) − 1) − 2 otherwise the behavior is undefined.
  This method is only guaranteed to work with the Kernel Factory. For other services, use the generic create() method and consult the service documentation for information on the arguments that need to be passed to the create stream.

Definition at line 404 of file factory.

References L4::Cap_base::cap(), and L4::Kobject::cap().

Here is the call graph for this function:

## create_gate()

l4_msgtag_t L4::Factory::create_gate | ( | Cap< void > const & | target_cap,
|  | Cap< Snd_destination > const & | snd_dst_cap,
|  | l4_umword_t | label,
|  | l4_utcb_t * | utcb = l4_utcb() )

inlinenoexcept

Create a new IPC gate, optionally bound to a send destination (a thread or thread group).

Parameters

  [out] | target_cap | The kernel stores the new IPC gate's capability into this slot.
  | snd_dst_cap | Optional capability selector of a thread or thread group to bind the gate to. Use L4_INVALID_CAP to create an unbound IPC gate.
  | label | Optional label of the gate (precisely used if snd_dst_cap is valid). If snd_dst_cap is valid, label must be present.
  | utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns
  Syscall return tag containing one of the following return codes.

Return values

  L4_EOK | No error occurred.
  -L4_ENOMEM | Out-of-memory during allocation of the Ipc_gate object.
  -L4_EINVAL | snd_dst_cap is void or points to something that is not a thread or thread group.
  -L4_EPERM | Insufficient permissions; see precondition.

Precondition
  The invoked Factory capability must have the permission L4_CAP_FPAGE_S. Also snd_dst_cap (if valid) must have the permission L4_CAP_FPAGE_S.

An unbound IPC gate can be bound to a thread or thread group using L4::Ipc_gate::bind_thread() or bind_snd_destination().

See also
  L4::Ipc_gate

Definition at line 440 of file factory.

References L4::Cap_base::cap(), and L4::Kobject::cap().

Here is the call graph for this function:

## create_task()

l4_msgtag_t L4::Factory::create_task | ( | Cap< Task > const & | target_cap,
|  | l4_fpage_t * | utcb_area,
|  | l4_utcb_t * | utcb = l4_utcb() )

inlinenoexcept

Create a new task.

Parameters

  [out] | target_cap | The kernel stores the new task's capability into this slot.
  [in,out] | utcb_area | Flexpage that describes an area in the address space of the new task, where the kernel should map the kernel-allocated kernel-user memory to. The kernel uses the kernel-user memory to store UTCBs and vCPU state-save-areas of the new task.

On systems without MMU, the flexpage is adjusted to reflect the acually allocated physical address.

Parameters

  utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns
  Syscall return tag

Return values

  L4_EOK | No error occurred.
  -L4_EPERM | Insufficient permissions; see precondition.
  <0 | Error code.

Precondition
  The invoked Factory capability must have the permission L4_CAP_FPAGE_S.

Note
  The size of the UTCB area specifies indirectly the number of UTCBs available for this task. Refer to L4::Task::add_ku_mem for adding more of this type of memory.

See also
  L4::Task

Definition at line 370 of file factory.

References L4::Cap_base::cap(), and L4::Kobject::cap().

Here is the call graph for this function:

## create_thread_group()

l4_msgtag_t L4::Factory::create_thread_group | ( | Cap< Thread_group > const & | target_cap,
|  | unsigned | policy,
|  | l4_utcb_t * | utcb = l4_utcb() )

inlinenoexcept

Create a new thread group.

An IPC endpoint can be bound to a thread group. When a message arrives at the IPC endpoint, a specific thread of the thread group is selected to actually receive the message. A thread group is a send destination for an IPC endpoint.

Parameters

  [out] | target_cap | The kernel stores the new thread group's capability into this slot.
  | policy | Policy parameter for the thread group. See L4_thread_group_policy for a list of supported values.
  | utcb | UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns
  Syscall return tag containing one of the following return codes.

Return values

  L4_EOK | No error occurred.
  -L4_ENOMEM | Out-of-memory during allocation of the Thread_group object.
  -L4_EINVAL | Invalid policy parameter.
  -L4_EPERM | The factory instance requires L4_CAP_FPAGE_S rights on the invoked capability and L4_CAP_FPAGE_S is not present.

Definition at line 475 of file factory.

References L4::Cap_base::cap(), and L4::Kobject::cap().

Here is the call graph for this function:

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

- l4/sys/factory