L4Re - L4 Runtime Environment

C factory interface to create kernel objects. 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 const utcb_area) L4_NOTHROW
 Create a new task. More...
 
l4_msgtag_t l4_factory_create_task_u (l4_cap_idx_t factory, l4_cap_idx_t target_cap, l4_fpage_t const utcb_area, l4_utcb_t *utcb) L4_NOTHROW
 Create a new task. More...
 
l4_msgtag_t l4_factory_create_thread (l4_cap_idx_t factory, l4_cap_idx_t target_cap) L4_NOTHROW
 Create a new thread. More...
 
l4_msgtag_t l4_factory_create_thread_u (l4_cap_idx_t factory, l4_cap_idx_t target_cap, l4_utcb_t *utcb) L4_NOTHROW
 Create a new thread. More...
 
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. More...
 
l4_msgtag_t l4_factory_create_factory_u (l4_cap_idx_t factory, l4_cap_idx_t target_cap, unsigned long limit, l4_utcb_t *utcb) L4_NOTHROW
 Create a new factory. More...
 
l4_msgtag_t l4_factory_create_gate (l4_cap_idx_t factory, l4_cap_idx_t target_cap, l4_cap_idx_t thread_cap, l4_umword_t label) L4_NOTHROW
 Create a new IPC gate. More...
 
l4_msgtag_t l4_factory_create_gate_u (l4_cap_idx_t factory, l4_cap_idx_t target_cap, l4_cap_idx_t thread_cap, l4_umword_t label, l4_utcb_t *utcb) L4_NOTHROW
 Create a new IPC gate. More...
 
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. More...
 
l4_msgtag_t l4_factory_create_irq_u (l4_cap_idx_t factory, l4_cap_idx_t target_cap, l4_utcb_t *utcb) L4_NOTHROW
 Create a new IRQ. More...
 
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. More...
 
l4_msgtag_t l4_factory_create_vm_u (l4_cap_idx_t factory, l4_cap_idx_t target_cap, l4_utcb_t *utcb) L4_NOTHROW
 Create a new virtual machine. More...
 

Detailed Description

C factory interface to create kernel objects.

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

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>

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

Function Documentation

◆ 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
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new factory's capability into this slot.
limitLimit for the new factory in bytes.
Returns
Syscall return tag
Note
The limit of the new factory is subtracted from the available amount of the factory used for creation.

Definition at line 373 of file factory.h.

References l4_factory_create_factory_u(), and l4_utcb().

+ Here is the call graph for this function:

◆ l4_factory_create_factory_u()

l4_msgtag_t l4_factory_create_factory_u ( l4_cap_idx_t  factory,
l4_cap_idx_t  target_cap,
unsigned long  limit,
l4_utcb_t utcb 
)
inline

Create a new factory.

Parameters
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new factory's capability into this slot.
limitLimit for the new factory in bytes.
utcbThe UTCB to use for the operation.
Returns
Syscall return tag
Note
The limit of the new factory is subtracted from the available amount of the factory used for creation.

Definition at line 307 of file factory.h.

Referenced by l4_factory_create_factory().

+ Here is the caller 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  thread_cap,
l4_umword_t  label 
)
inline

Create a new IPC gate.

Parameters
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new IPC gate's capability into this slot.
thread_capOptional capability selector of the thread to bind the gate to. Use L4_INVALID_CAP to create an unbound IPC gate.
labelOptional label of the gate (is used if thread_cap is valid).
Returns
Syscall return tag containing one of the following return codes.
Return values
L4_EOKNo error occurred.
-L4_ENOMEMOut-of-memory during allocation of the Ipc_gate object.
-L4_ENOENTthread_cap is void or points to something that is not a thread.
-L4_EPERMNo write rights on thread_cap.

An unbound IPC gate can be bound to a thread using l4_ipc_gate_bind_thread.

See also
IPC-Gate API

Definition at line 381 of file factory.h.

References l4_factory_create_gate_u(), and l4_utcb().

+ Here is the call graph for this function:

◆ l4_factory_create_gate_u()

l4_msgtag_t l4_factory_create_gate_u ( l4_cap_idx_t  factory,
l4_cap_idx_t  target_cap,
l4_cap_idx_t  thread_cap,
l4_umword_t  label,
l4_utcb_t utcb 
)
inline

Create a new IPC gate.

Parameters
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new IPC gate's capability into this slot.
thread_capOptional capability selector of the thread to bind the gate to. Use L4_INVALID_CAP to create an unbound IPC gate.
labelOptional label of the gate (is used if thread_cap is valid).
utcbThe UTCB to use for the operation.
Returns
Syscall return tag containing one of the following return codes.
Return values
L4_EOKNo error occurred.
-L4_ENOMEMOut-of-memory during allocation of the Ipc_gate object.
-L4_ENOENTthread_cap is void or points to something that is not a thread.
-L4_EPERMNo write rights on thread_cap.

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

See also
L4::Ipc_gate

Definition at line 318 of file factory.h.

Referenced by l4_factory_create_gate().

+ Here is the caller 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
factoryFactory to use for creation.
[out]target_capThe kernel stores the new IRQ's capability into this slot.
Returns
Syscall return tag
See also
IRQs
Examples:
examples/sys/isr/main.c.

Definition at line 389 of file factory.h.

References l4_factory_create_irq_u(), and l4_utcb().

+ Here is the call graph for this function:

◆ l4_factory_create_irq_u()

l4_msgtag_t l4_factory_create_irq_u ( l4_cap_idx_t  factory,
l4_cap_idx_t  target_cap,
l4_utcb_t utcb 
)
inline

Create a new IRQ.

Parameters
factoryFactory to use for creation.
[out]target_capThe kernel stores the new IRQ's capability into this slot.
utcbThe UTCB to use for the operation.
Returns
Syscall return tag
Deprecated:
Use create() with Cap<Irq> as argument instead.
See also
L4::Irq

Definition at line 340 of file factory.h.

Referenced by l4_factory_create_irq().

+ Here is the caller 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 const  utcb_area 
)
inline

Create a new task.

Parameters
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new task's capability into this slot.
utcb_areaFlexpage that describes an area of kernel-user memory that can be used for UTCBs and vCPU state-save-areas of the new task.
Returns
Syscall return tag.
Note
The size of the UTCB area specifies indirectly the number of UTCBs available for this task. Refer to L4::Task::add_ku_mem / l4_task_add_ku_mem() for adding more of this type of memory.
See also
Task

Definition at line 359 of file factory.h.

References l4_factory_create_task_u(), and l4_utcb().

+ Here is the call graph for this function:

◆ l4_factory_create_task_u()

l4_msgtag_t l4_factory_create_task_u ( l4_cap_idx_t  factory,
l4_cap_idx_t  target_cap,
l4_fpage_t const  utcb_area,
l4_utcb_t utcb 
)
inline

Create a new task.

Parameters
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new task's capability into this slot.
utcb_areaFlexpage 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.
utcbThe UTCB to use for the operation.
Returns
Syscall return tag
Note
The size of the UTCB area specifies indirectly the number of UTCBs available for this task. Refer to L4::Task::add_ku_mem / l4_task_add_ku_mem() for adding more of this type of memory.
See also
L4::Task

Definition at line 289 of file factory.h.

Referenced by l4_factory_create_task().

+ Here is the caller 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
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new thread's capability into this slot.
Returns
Syscall return tag
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 366 of file factory.h.

References l4_factory_create_thread_u(), and l4_utcb().

+ Here is the call graph for this function:

◆ l4_factory_create_thread_u()

l4_msgtag_t l4_factory_create_thread_u ( l4_cap_idx_t  factory,
l4_cap_idx_t  target_cap,
l4_utcb_t utcb 
)
inline

Create a new thread.

Parameters
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new thread's capability into this slot.
utcbThe UTCB to use for the operation.
Returns
Syscall return tag
Deprecated:
Use create() with Cap<Thread> as argument instead.
See also
L4::Thread

Definition at line 300 of file factory.h.

Referenced by l4_factory_create_thread().

+ Here is the caller 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
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new VM's capability into this slot.
Returns
Syscall return tag
See also
Virtual Machines

Definition at line 396 of file factory.h.

References l4_factory_create_vm_u(), and l4_utcb().

+ Here is the call graph for this function:

◆ l4_factory_create_vm_u()

l4_msgtag_t l4_factory_create_vm_u ( l4_cap_idx_t  factory,
l4_cap_idx_t  target_cap,
l4_utcb_t utcb 
)
inline

Create a new virtual machine.

Parameters
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new VM's capability into this slot.
utcbThe UTCB to use for the operation.
Returns
Syscall return tag
Deprecated:
Use create() with Cap<Vm> as argument instead.
See also
L4::Vm

Definition at line 347 of file factory.h.

Referenced by l4_factory_create_vm().

+ Here is the caller graph for this function: