L4Re Operating System Framework
Interface and Usage Documentation
Loading...
Searching...
No Matches

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 thread_cap, l4_umword_t label) L4_NOTHROW
 Create a new IPC gate.
 
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 hardware vCPU context.
 
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:

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>
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
factoryFactory to use for creation.
objProtocol ID to describe the type of the object to create.
[out]targetThe kernel stores the new objects's capability into this slot.
Return values
L4_EOKNo error occurred.
-L4_EPERMThe factory instance requires L4_CAP_FPAGE_S rights on factory and L4_CAP_FPAGE_S is not present.
<0Error code.

Definition at line 648 of file factory.h.

References 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
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
Return values
L4_EOKNo error occurred.
-L4_EPERMThe factory instance requires L4_CAP_FPAGE_S rights on factory and L4_CAP_FPAGE_S is not present.
<0Error code.
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 495 of file factory.h.

References 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  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 a thread to bind the gate to. Use L4_INVALID_CAP to create an unbound IPC gate.
labelOptional label of the gate (precisely used if thread_cap is valid). If thread_cap is valid, label must be present.
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_EINVALthread_cap is void or points to something that is not a thread.
-L4_EPERMNo L4_CAP_FPAGE_S rights on factory or thread_cap.

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

See also
IPC-Gate API

Definition at line 503 of file factory.h.

References 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
factoryFactory to use for creation.
[out]target_capThe kernel stores the new IRQ's capability into this slot.
Return values
L4_EOKNo error occurred.
-L4_EPERMThe factory instance requires L4_CAP_FPAGE_S rights on factory and L4_CAP_FPAGE_S is not present.
<0Error code.
See also
IRQs
Examples
examples/sys/isr/main.c.

Definition at line 511 of file factory.h.

References 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
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new task's capability into this slot.
[in,out]utcb_areaPointer 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_EOKNo error occurred.
-L4_EPERMThe factory instance requires L4_CAP_FPAGE_S rights on factory and L4_CAP_FPAGE_S is not present.
<0Error code.
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 481 of file factory.h.

References 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
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
Return values
L4_EOKNo error occurred.
-L4_EPERMThe factory instance requires L4_CAP_FPAGE_S rights on factory and L4_CAP_FPAGE_S is not present.
<0Error code.
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 488 of file factory.h.

References 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 hardware vCPU context.

A hardware vCPU context typically represents a hardware vCPU control structure (e.g. VMX VMCS).

Parameters
factoryCapability selector for factory to use for creation.
[out]target_capThe kernel stores the new hardware vCPU context's capability into this slot.
Returns
Syscall return tag
Return values
L4_EOKNo error occurred.
-L4_EPERMThe factory instance requires L4_CAP_FPAGE_S rights on factory and L4_CAP_FPAGE_S is not present.
<0Error code.
See also
Virtual Machines

Definition at line 525 of file factory.h.

References 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
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
Return values
L4_EOKNo error occurred.
-L4_EPERMThe factory instance requires L4_CAP_FPAGE_S rights on factory and L4_CAP_FPAGE_S is not present.
<0Error code.
See also
Virtual Machines

Definition at line 518 of file factory.h.

References l4_utcb().

+ Here is the call graph for this function: