Loading...
Searching...
No Matches
Factory
Base API » Kernel Objects

C factory interface to create objects, see L4::Factory for the C++ interface. More...

Collaboration diagram for Factory:

## Functions

l4_msgtag_t | l4_factory_create_task (l4_cap_idx_t factory, l4_cap_idx_t target_cap, l4_fpage_t *utcb_area) L4_NOTHROW
| Create a new task.
l4_msgtag_t | l4_factory_create_thread (l4_cap_idx_t factory, l4_cap_idx_t target_cap) L4_NOTHROW
| Create a new thread.
l4_msgtag_t | l4_factory_create_factory (l4_cap_idx_t factory, l4_cap_idx_t target_cap, unsigned long limit) L4_NOTHROW
| Create a new factory.
l4_msgtag_t | l4_factory_create_gate (l4_cap_idx_t factory, l4_cap_idx_t target_cap, l4_cap_idx_t snd_dst_cap, l4_umword_t label) L4_NOTHROW
| Create a new IPC gate, optionally bound to a send destination (a thread or thread group).
l4_msgtag_t | l4_factory_create_irq (l4_cap_idx_t factory, l4_cap_idx_t target_cap) L4_NOTHROW
| Create a new IRQ sender.
l4_msgtag_t | l4_factory_create_vm (l4_cap_idx_t factory, l4_cap_idx_t target_cap) L4_NOTHROW
| Create a new virtual machine.
l4_msgtag_t | l4_factory_create_vcpu_context (l4_cap_idx_t factory, l4_cap_idx_t target_cap) L4_NOTHROW
| Create a new vCPU context.
l4_msgtag_t | l4_factory_create_thread_group (l4_cap_idx_t factory, l4_cap_idx_t target_cap, unsigned policy) L4_NOTHROW
| Create a new thread group.
l4_msgtag_t | l4_factory_create (l4_cap_idx_t factory, long obj, l4_cap_idx_t target) L4_NOTHROW
| Create a new object.

## Detailed Description

C factory interface to create objects, see L4::Factory for the C++ interface.

A factory is used to create all kinds of kernel objects:

- Task
- Thread
- Factory
- IPC-Gate API
- IRQs
- Virtual Machines

To create a new kernel object the caller has to specify the factory to use for creation. The caller has to allocate a capability slot where the kernel stores the new object's capability.

The factory is equipped with a limit that limits the amount of kernel memory available for that factory.

Note
  The limit does not give any guarantee for the amount of available kernel memory.

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

For the C++ interface refer to L4::Factory.

## Function Documentation

## l4_factory_create()

l4_msgtag_t l4_factory_create | ( | l4_cap_idx_t | factory,
|  | long | obj,
|  | l4_cap_idx_t | target )

inline

Create a new object.

Parameters

  | factory | Factory to use for creation.
  | obj | Protocol ID to describe the type of the object to create.
  [out] | target | The kernel stores the new objects's capability into this slot.

Return values

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

Precondition
  The capability factory must have the permission L4_CAP_FPAGE_S.

Definition at line 707 of file factory.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_factory_create_factory()

l4_msgtag_t l4_factory_create_factory | ( | l4_cap_idx_t | factory,
|  | l4_cap_idx_t | target_cap,
|  | unsigned long | limit )

inline

Create a new factory.

Parameters

  | factory | Capability selector for factory to use for creation.
  [out] | target_cap | The kernel stores the new factory's capability into this slot.
  | limit | Limit for the new factory in bytes.

Returns
  Syscall return tag

Return values

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

Precondition
  The capability factory must have the permission L4_CAP_FPAGE_S.

Note
  The limit of the new factory is subtracted from the available amount of the factory used for creation.
  This method is only guaranteed to work with the Kernel Factory. For other services, use the generic L4::Factory::create() method and consult the service documentation for information on the arguments that need to be passed to the create stream.

Definition at line 545 of file factory.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_factory_create_gate()

l4_msgtag_t l4_factory_create_gate | ( | l4_cap_idx_t | factory,
|  | l4_cap_idx_t | target_cap,
|  | l4_cap_idx_t | snd_dst_cap,
|  | l4_umword_t | label )

inline

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

Parameters

  | factory | Capability selector for factory to use for creation.
  [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.

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 capability factory must have the permission L4_CAP_FPAGE_S. Also snd_dst_cap (if not L4_INVALID_CAP) must have the permission L4_CAP_FPAGE_S.

An unbound IPC gate can be bound to a thread using l4_rcv_ep_bind_thread().

See also
  IPC-Gate API

Definition at line 553 of file factory.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_factory_create_irq()

l4_msgtag_t l4_factory_create_irq | ( | l4_cap_idx_t | factory,
|  | l4_cap_idx_t | target_cap )

inline

Create a new IRQ sender.

Parameters

  | factory | Factory to use for creation.
  [out] | target_cap | The kernel stores the new IRQ's capability into this slot.

Return values

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

Precondition
  The capability factory must have the permission L4_CAP_FPAGE_S.

See also
  IRQs

Examples
  examples/sys/isr/main.c.

Definition at line 561 of file factory.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_factory_create_task()

l4_msgtag_t l4_factory_create_task | ( | l4_cap_idx_t | factory,
|  | l4_cap_idx_t | target_cap,
|  | l4_fpage_t * | utcb_area )

inline

Create a new task.

Parameters

  | factory | Capability selector for factory to use for creation.
  [out] | target_cap | The kernel stores the new task's capability into this slot.
  [in,out] | utcb_area | Pointer to flexpage that describes an area of kernel-user memory that can be used for 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.

Returns
  Syscall return tag.

Return values

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

Precondition
  The capability factory 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
  Task

Definition at line 531 of file factory.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_factory_create_thread()

l4_msgtag_t l4_factory_create_thread | ( | l4_cap_idx_t | factory,
|  | l4_cap_idx_t | target_cap )

inline

Create a new thread.

Parameters

  | factory | Capability selector for factory to use for creation.
  [out] | target_cap | The kernel stores the new thread's capability into this slot.

Returns
  Syscall return tag

Return values

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

Precondition
  The capability factory must have the permission L4_CAP_FPAGE_S.

See also
  Thread

Examples
  examples/sys/aliens/main.c, examples/sys/singlestep/main.c, examples/sys/start-with-exc/main.c, and examples/sys/utcb-ipc/main.c.

Definition at line 538 of file factory.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_factory_create_thread_group()

l4_msgtag_t l4_factory_create_thread_group | ( | l4_cap_idx_t | factory,
|  | l4_cap_idx_t | target_cap,
|  | unsigned | policy )

inline

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

  | factory | Capability selector for factory to use for creation.
  [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.

Returns
  Syscall return tag

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 factory and L4_CAP_FPAGE_S is not present.
  <0 | Error code.

See also
  Thread groups

Definition at line 582 of file factory.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_factory_create_vcpu_context()

l4_msgtag_t l4_factory_create_vcpu_context | ( | l4_cap_idx_t | factory,
|  | l4_cap_idx_t | target_cap )

inline

Create a new vCPU context.

A vCPU context typically represents a hardware structure that captures the state of a vCPU on a CPU (e.g. VMX VMCS).

Parameters

  | factory | Capability selector for factory to use for creation.
  [out] | target_cap | The kernel stores the new vCPU context's capability into this slot.

Returns
  Syscall return tag

Return values

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

Precondition
  The capability factory must have the permission L4_CAP_FPAGE_S.

See also
  Virtual Machines

Definition at line 575 of file factory.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function:

## l4_factory_create_vm()

l4_msgtag_t l4_factory_create_vm | ( | l4_cap_idx_t | factory,
|  | l4_cap_idx_t | target_cap )

inline

Create a new virtual machine.

Parameters

  | factory | Capability selector for factory to use for creation.
  [out] | target_cap | The kernel stores the new VM's capability into this slot.

Returns
  Syscall return tag

Return values

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

Precondition
  The capability factory must have the permission L4_CAP_FPAGE_S.

See also
  Virtual Machines

Definition at line 568 of file factory.h.

References L4_NOTHROW, and l4_utcb().

Here is the call graph for this function: