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 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 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>

factory.h
Common factory related definitions.

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

	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

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

	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.
	utcb	The UTCB to use for the operation.

Returns: Syscall return tag

Note: The limit (quota) of the new factory is subtracted from the limit of the factory invoked on its creation.; 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 307 of file factory.h.

Referenced by L4::Factory::create_factory(), and 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

	factory	Capability selector for factory to use for creation.
[out]	target_cap	The kernel stores the new IPC gate's capability into this slot.
	thread_cap	Optional capability selector of the thread to bind the gate to. Use L4_INVALID_CAP to create an unbound IPC gate.
	label	Optional 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_EOK	No error occurred.
-L4_ENOMEM	Out-of-memory during allocation of the Ipc_gate object.
-L4_ENOENT	`thread_cap` is void or points to something that is not a thread.
-L4_EPERM	No L4_CAP_FPAGE_S 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

	factory	Capability selector for factory to use for creation.
[out]	target_cap	The kernel stores the new IPC gate's capability into this slot.
	thread_cap	Optional capability selector of the thread to bind the gate to. Use L4_INVALID_CAP to create an unbound IPC gate.
	label	Optional label of the gate (is used if `thread_cap` is valid).
	utcb	The UTCB to use for the operation.

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_ENOENT	`thread_cap` is void or points to something that is not a thread.
-L4_EPERM	No L4_CAP_FPAGE_S rights on `thread_cap`.

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

Note: This method is only guaranteed to work with the Kernel Factory.

See also: L4::Ipc_gate

Definition at line 318 of file factory.h.

Referenced by L4::Factory::create_gate(), and 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

	factory	Factory to use for creation.
[out]	target_cap	The 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

	factory	Factory to use for creation.
[out]	target_cap	The kernel stores the new IRQ's capability into this slot.
	utcb	The 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(), and 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	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.
	utcb_area	Flexpage 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	utcb_area,
		l4_utcb_t *	utcb
	)

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.
	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.
	utcb	The 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.; This method is only guaranteed to work with the Kernel Factory.

See also: L4::Task

Definition at line 289 of file factory.h.

Referenced by L4::Factory::create_task(), and 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

	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

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

	factory	Capability selector for factory to use for creation.
[out]	target_cap	The kernel stores the new thread's capability into this slot.
	utcb	The 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(), and 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

	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

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

	factory	Capability selector for factory to use for creation.
[out]	target_cap	The kernel stores the new VM's capability into this slot.
	utcb	The 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(), and l4_factory_create_vm().

Here is the caller graph for this function:

Functions

Detailed Description

Function Documentation

◆ l4_factory_create_factory()

◆ l4_factory_create_factory_u()

◆ l4_factory_create_gate()

◆ l4_factory_create_gate_u()

◆ l4_factory_create_irq()

◆ l4_factory_create_irq_u()

◆ l4_factory_create_task()

◆ l4_factory_create_task_u()

◆ l4_factory_create_thread()

◆ l4_factory_create_thread_u()

◆ l4_factory_create_vm()

◆ l4_factory_create_vm_u()