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:

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_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_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_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_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_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_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_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_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_utcb().

Here is the call graph for this function:

Functions

Detailed Description

Function Documentation

◆ l4_factory_create()

◆ l4_factory_create_factory()

◆ l4_factory_create_gate()

◆ l4_factory_create_irq()

◆ l4_factory_create_task()

◆ l4_factory_create_thread()

◆ l4_factory_create_thread_group()

◆ l4_factory_create_vcpu_context()

◆ l4_factory_create_vm()