L4::Factory Class Reference

C++ Factory interface, see Factory for the C interface. More...

#include <factory>

Inheritance diagram for L4::Factory:

Collaboration diagram for L4::Factory:

Data Structures
struct	Lstr
	Special type to add a pascal string into the factory create stream. More...
struct	Nil
	Special type to add a void argument into the factory create stream. More...
class	S
	Stream class for the create() argument stream. More...

Public Member Functions
S	create (Cap< void > target, long obj, l4_utcb_t *utcb=l4_utcb()) noexcept
	Generic create call to the factory.
template<typename OBJ >
S	create (Cap< OBJ > target, l4_utcb_t *utcb=l4_utcb()) noexcept
	Create call for typed capabilities.
l4_msgtag_t	create_task (Cap< Task > const &target_cap, l4_fpage_t const &utcb_area, l4_utcb_t *utcb=l4_utcb()) noexcept
	Create a new task.
l4_msgtag_t	create_factory (Cap< Factory > const &target_cap, unsigned long limit, l4_utcb_t *utcb=l4_utcb()) noexcept
	Create a new factory.
l4_msgtag_t	create_gate (Cap< void > const &target_cap, Cap< Thread > const &thread_cap, l4_umword_t label, l4_utcb_t *utcb=l4_utcb()) noexcept
	Create a new IPC gate.
Public Member Functions inherited from L4::Kobject
l4_msgtag_t	dec_refcnt (l4_mword_t diff, l4_utcb_t *utcb=l4_utcb())
	Decrement the in kernel reference counter for the object.

Additional Inherited Members
Protected Types inherited from L4::Kobject_t< Factory, Kobject, L4_PROTO_FACTORY >
typedef Factory	Class
	The target interface type (inheriting from Kobject_t)
typedef Typeid::Iface< PROTO, Factory >	__Iface
	The interface description for the derived class.
typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Base::__Iface_list >	__Iface_list
	The list of all RPC interfaces provided directly or through inheritance.
Protected Member Functions inherited from L4::Kobject_t< Factory, Kobject, L4_PROTO_FACTORY >
L4::Cap< Class >	c () const noexcept
	Get the capability to ourselves.
Protected Member Functions inherited from L4::Kobject
l4_cap_idx_t	cap () const noexcept
	Return capability selector.
Static Protected Member Functions inherited from L4::Kobject_t< Factory, Kobject, L4_PROTO_FACTORY >
static void	__check_protocols__ () noexcept
	Helper to check for protocol conflicts.

Detailed Description

C++ Factory interface, see Factory for the C interface.

Factories provide an interface to create objects which are accessed via capabilities.

For additional information about which objects can be created via this interface, see server-specific information in Kernel Factory and L4Re Servers.

Include File

#include <l4/sys/factory> 

For the C interface refer to Factory.

Definition at line 48 of file factory.

Member Function Documentation

create() [1/2]

template<typename OBJ >

S L4::Factory::create ( Cap< OBJ >  target, l4_utcb_t *  utcb = l4_utcb()  )

inlinenoexcept

Create call for typed capabilities.

Template Parameters

OBJ	Capability type of the object to be created.

Parameters

[out]	target	Capability of type OBJ.
	utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns

A create stream that allows additional arguments to be passed to the create() call via the left-shift (<<) operator.

This method does not directly invoke the factory. The factory is invoked when the create stream returned by this method is converted to an l4_msgtag_t, or otherwise when the stream goes out of scope.

Note

Refer to S::operator l4_msgtag_t () for description of error codes in the returned create stream.

The create stream uses the UTCB to store parameters for the service call. During the lifetime of a create stream or, until it is converted to a l4_msgtag_t, other UTCB-using operations must not be used.

Usage:

L4::Cap<L4Re::Dataspace> ds = L4Re::Util::cap_alloc.alloc<L4Re::Dataspace>();
factory->create(ds) << l4_mword_t(size_in_bytes);

Definition at line 308 of file factory.

References L4::Kobject::cap().

Here is the call graph for this function:

create() [2/2]

S L4::Factory::create ( Cap< void >  target, long  obj, l4_utcb_t *  utcb = l4_utcb()  )

inlinenoexcept

Generic create call to the factory.

Parameters

[out]	target	Capability selector for the new object. The caller must allocate the capability slot. The kernel stores the new objects's capability into this slot.
	obj	The protocol ID that specifies which kind of object shall be created.
	utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns

A create stream that allows additional arguments to be passed to the create() call via the left-shift (<<) operator.

This method does not directly invoke the factory. The factory is invoked when the create stream returned by this method is converted to an l4_msgtag_t, or otherwise when the stream goes out of scope.

Note

Refer to S::operator l4_msgtag_t () for description of error codes in the returned create stream.

The create stream uses the UTCB to store parameters for the service call. During the lifetime of a create stream or, until it is converted to a l4_msgtag_t, other UTCB-using operations must not be used.

See also

create(Cap<OBJ>, l4_utcb_t *)

Definition at line 274 of file factory.

References L4::Kobject::cap().

Here is the call graph for this function:

create_factory()

l4_msgtag_t L4::Factory::create_factory ( Cap< Factory > const &  target_cap, unsigned long  limit, l4_utcb_t *  utcb = l4_utcb()  )

inlinenoexcept

Create a new factory.

Parameters

[out]	target_cap	The kernel stores the new factory's capability into this slot.
	limit	Limit for the new factory in bytes.
	utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns

Syscall return tag

Return values

L4_EOK	No error occurred.
-L4_EPERM	The factory instance requires L4_CAP_FPAGE_S rights on the invoked capability and L4_CAP_FPAGE_S is not present.
<0	Error code.

Note

In addition to memory needed for internal data structures, the limit (quota) of the new factory is counted towards the quota of the creating factory. The limit must be within 1 ≤ limit ≤ 2^(8 * sizeof(l4_umword_t) − 1) − 2 otherwise the behavior is undefined.

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 377 of file factory.

References L4::Cap_base::cap(), and L4::Kobject::cap().

Here is the call graph for this function:

create_gate()

l4_msgtag_t L4::Factory::create_gate ( Cap< void > const &  target_cap, Cap< Thread > const &  thread_cap, l4_umword_t  label, l4_utcb_t *  utcb = l4_utcb()  )

inlinenoexcept

Create a new IPC gate.

Parameters

[out]	target_cap	The kernel stores the new IPC gate's capability into this slot.
	thread_cap	Optional capability selector of a thread to bind the gate to. Use L4_INVALID_CAP to create an unbound IPC gate.
	label	Optional label of the gate (precisely used if thread_cap is valid). If thread_cap is valid, label must be present.
	utcb	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

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	thread_cap is void or points to something that is not a thread.
-L4_EPERM	The factory instance requires L4_CAP_FPAGE_S rights on the invoked capability or thread_cap and L4_CAP_FPAGE_S is not present.

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

See also

L4::Ipc_gate

Definition at line 410 of file factory.

References L4::Cap_base::cap(), and L4::Kobject::cap().

Here is the call graph for this function:

create_task()

l4_msgtag_t L4::Factory::create_task ( Cap< Task > const &  target_cap, l4_fpage_t const &  utcb_area, l4_utcb_t *  utcb = l4_utcb()  )

inlinenoexcept

Create a new task.

Parameters

[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	UTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Returns

Syscall return tag

Return values

L4_EOK	No error occurred.
-L4_EPERM	The factory instance requires L4_CAP_FPAGE_S rights on the invoked capability and L4_CAP_FPAGE_S is not present.
<0	Error 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

L4::Task

Definition at line 344 of file factory.

References L4::Cap_base::cap(), and L4::Kobject::cap().

Here is the call graph for this function:

---

The documentation for this class was generated from the following file:

• l4/sys/factory