L4Re Operating System Framework – Interface and Usage Documentation
Loading...
Searching...
No Matches
L4::Task Class Reference

C++ interface of the Task kernel object, see Task for the C interface. More...

#include <task>

+ Inheritance diagram for L4::Task:
+ Collaboration diagram for L4::Task:

Public Member Functions

l4_msgtag_t map (Cap< Task > const &src_task, l4_fpage_t const &snd_fpage, l4_umword_t snd_base, l4_utcb_t *utcb=l4_utcb()) noexcept
 Map resources available in the source task to a destination task.
 
l4_msgtag_t unmap (l4_fpage_t const &fpage, l4_umword_t map_mask, l4_utcb_t *utcb=l4_utcb()) noexcept
 Revoke rights from the task.
 
l4_msgtag_t unmap_batch (l4_fpage_t const *fpages, unsigned num_fpages, l4_umword_t map_mask, l4_utcb_t *utcb=l4_utcb()) noexcept
 Revoke rights from a task.
 
l4_msgtag_t delete_obj (L4::Cap< void > obj, l4_utcb_t *utcb=l4_utcb()) noexcept
 Release capability and delete object.
 
l4_msgtag_t release_cap (L4::Cap< void > cap, l4_utcb_t *utcb=l4_utcb()) noexcept
 Release object capability.
 
l4_msgtag_t cap_valid (Cap< void > const &cap, l4_utcb_t *utcb=l4_utcb()) noexcept
 Check whether a capability is present (refers to an object).
 
l4_msgtag_t cap_equal (Cap< void > const &cap_a, Cap< void > const &cap_b, l4_utcb_t *utcb=l4_utcb()) noexcept
 Test whether two capabilities point to the same object with the same rights.
 
l4_msgtag_t add_ku_mem (l4_fpage_t const &fpage, l4_utcb_t *utcb=l4_utcb()) noexcept
 Add kernel-user memory.
 
- 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< Task, Kobject, L4_PROTO_TASK, Type_info::Demand_t< 2 > >
typedef Task Class
 The target interface type (inheriting from Kobject_t)
 
typedef Typeid::Iface< PROTO, Task__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< Task, Kobject, L4_PROTO_TASK, Type_info::Demand_t< 2 > >
L4::Cap< Classc () 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< Task, Kobject, L4_PROTO_TASK, Type_info::Demand_t< 2 > >
static void __check_protocols__ () noexcept
 Helper to check for protocol conflicts.
 

Detailed Description

C++ interface of the Task kernel object, see Task for the C interface.

The L4::Task class represents a combination of the address spaces provided by the L4Re micro kernel. A task consists of at least a memory address space and an object address space. On IA32 there is also an IO-port address space associated with an L4::Task.

L4::Task objects are created using the L4::Factory interface.

Include File
#include <l4/sys/task>
Common task related definitions.

Definition at line 44 of file task.

Member Function Documentation

◆ add_ku_mem()

l4_msgtag_t L4::Task::add_ku_mem ( l4_fpage_t const &  fpage,
l4_utcb_t utcb = l4_utcb() 
)
inlinenoexcept

Add kernel-user memory.

Parameters
fpageFlexpage describing the virtual area the memory goes to.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Returns
Syscall return tag

Kernel-user memory (ku_mem) is memory that is shared between the kernel and user-space. It is needed for the UTCB area of threads (see L4::Thread::Attr::bind()) and for (extended) vCPU state. Note that existing kernel-user memory cannot be unmapped or mapped somewhere else.

Note
The amount of kernel-user memory that can be allocated at once is limited by the used kernel implementation. The minimum allocatable amount is one page (L4_PAGESIZE). A portable implementation should not depend on allocations greater than 16KiB to succeed.
This function is only guaranteed to work on L4::Task objects. It might or might not work on L4::Vm objects or on L4Re::Dma_space objects but there is no practical use for adding kernel-user memory to L4::Vm objects or to L4Re::Dma_space objects.

Definition at line 253 of file task.

References L4::Kobject::cap().

+ Here is the call graph for this function:

◆ cap_equal()

l4_msgtag_t L4::Task::cap_equal ( Cap< void > const &  cap_a,
Cap< void > const &  cap_b,
l4_utcb_t utcb = l4_utcb() 
)
inlinenoexcept

Test whether two capabilities point to the same object with the same rights.

Parameters
cap_aFirst capability selector to compare.
cap_bSecond capability selector to compare.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Return values
l4_msgtag_t::label() = 1cap_a and cap_b point to the same object.
l4_msgtag_t::label() = 0The two caps do not point to the same object.

Definition at line 225 of file task.

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

+ Here is the call graph for this function:

◆ cap_valid()

l4_msgtag_t L4::Task::cap_valid ( Cap< void > const &  cap,
l4_utcb_t utcb = l4_utcb() 
)
inlinenoexcept

Check whether a capability is present (refers to an object).

Parameters
capValid capability to check for presence.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Return values
l4_msgtag_t::label() > 0Capability is present (refers to an object).
l4_msgtag_t::label() == 0No capability present (void object).

A capability is considered present when it refers to an existing kernel object.

Precondition
cap must be a valid capability (i.e. cap.is_valid() == true). If you are unsure about the validity of your capability use L4::Cap.validate() instead.

Definition at line 208 of file task.

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

+ Here is the call graph for this function:

◆ delete_obj()

l4_msgtag_t L4::Task::delete_obj ( L4::Cap< void >  obj,
l4_utcb_t utcb = l4_utcb() 
)
inlinenoexcept

Release capability and delete object.

Parameters
objCapability index of the object to delete.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Returns
Syscall return tag

If obj has the delete permission, initiates the deletion of the object. This implies that all capabilities for that object are gone afterwards. However, kernel-internally, objects are not destroyed until all other kernel objects holding a reference to it drop the reference. Hence, quota used by that object might not be freed immediately.

If obj does not have the delete permission, no error will be reported and only the capability obj is removed. (Note that, depending on the object’s reference counter, this might still imply initiation of deletion.)

This operation is equivalent to unmap() with L4_FP_DELETE_OBJ flag.

Definition at line 168 of file task.

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

+ Here is the call graph for this function:

◆ map()

l4_msgtag_t L4::Task::map ( Cap< Task > const &  src_task,
l4_fpage_t const &  snd_fpage,
l4_umword_t  snd_base,
l4_utcb_t utcb = l4_utcb() 
)
inlinenoexcept

Map resources available in the source task to a destination task.

Parameters
src_taskCapability selector of the source task.
snd_fpageSend flexpage that describes an area in the address space or object space of the source task.
snd_baseSend base that describes an offset in the receive window of the destination task. The lower bits contain additional map control flags (see l4_fpage_cacheability_opt_t for memory mappings, L4_obj_fpage_ctl for object mappings, and L4_MAP_ITEM_GRANT; also see l4_map_control() and l4_map_obj_control()).
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Returns
Syscall return tag. The function l4_error() shall be used to test if the map operation was successful.
Return values
L4_EOKOperation successful (but see notes below).
-L4_EPERMNo L4_CAP_FPAGE_W right on capability used to invoke this operation.
-L4_EINVALInvalid source task capability.
-L4_IPC_SEMAPFAILEDThe map operation failed due to limited quota.

This method allows for asynchronous transfer of capabilities, memory mappings, and IO-port mappings (on IA32) from one task to another. The destination task is the task referenced by the capability on which the map is invoked, and the receive window is the whole address space of that task. By specifying proper rights in the snd_fpage and snd_base, it is possible to remove rights during transfer.

Note
If the send flex page is of type L4_FPAGE_OBJ, the L4_CAP_FPAGE_S right is removed from the transferred capability unless both the source and destination task capabilities possess the L4_CAP_FPAGE_S right themselves.
Even with l4_error() returning L4_EOK there might be cases where not all pages of the send flexpage were mapped respectively granted to the destination task, for instance, if the corresponding mapping in the destination task does already exist.

For more information on spaces and mappings, see Spaces and Mappings. The flexpage API is described in more detail at Flex pages.

Note
For peculiarities when using grant, see L4_MAP_ITEM_GRANT.

Definition at line 95 of file task.

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

+ Here is the call graph for this function:

◆ release_cap()

l4_msgtag_t L4::Task::release_cap ( L4::Cap< void >  cap,
l4_utcb_t utcb = l4_utcb() 
)
inlinenoexcept

Release object capability.

Parameters
capCapability selector of the object to release.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Returns
Syscall return tag.

This operation unmaps the capability from this task.

Note
If the reference counter of the kernel object referenced by cap goes down to zero, the deletion of the object is initiated. Objects are not destroyed until all other kernel objects holding a reference to it drop the reference.

Definition at line 187 of file task.

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

+ Here is the call graph for this function:

◆ unmap()

l4_msgtag_t L4::Task::unmap ( l4_fpage_t const &  fpage,
l4_umword_t  map_mask,
l4_utcb_t utcb = l4_utcb() 
)
inlinenoexcept

Revoke rights from the task.

Parameters
fpageFlexpage that describes an area in one capability space of this task
map_maskUnmap mask, see l4_unmap_flags_t
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.
Returns
Syscall return tag

This method allows to revoke rights from the destination task. For a flex page describing IO ports or memory, it also revokes rights from all the tasks that got the rights delegated from the destination task (i.e., this operation does a recursive rights revocation). If the set of rights is empty after the revocation, the capability is unmapped. It is guaranteed that the rights revocation is completed before this function returns.

Note
If the reference counter of a kernel object referenced in fpage goes down to zero (as a result of deleting capabilities), the deletion of the object is initiated. Objects are not destroyed until all other kernel objects holding a reference to it drop the reference.

Definition at line 123 of file task.

References L4::Kobject::cap().

+ Here is the call graph for this function:

◆ unmap_batch()

l4_msgtag_t L4::Task::unmap_batch ( l4_fpage_t const *  fpages,
unsigned  num_fpages,
l4_umword_t  map_mask,
l4_utcb_t utcb = l4_utcb() 
)
inlinenoexcept

Revoke rights from a task.

Parameters
fpagesAn array of flexpages. Each item describes an area in one capability space of this task.
num_fpagesNumber of fpages in the fpages array.
map_maskUnmap mask, see l4_unmap_flags_t.
utcbUTCB to be used for this operation, shall be the UTCB of the calling thread. Defaults to l4_utcb.

Revoke rights for an array of flexpages, see unmap for details.

Precondition
The caller needs to take care that num_fpages is not bigger than L4_UTCB_GENERIC_DATA_SIZE - 2.

Definition at line 142 of file task.

References L4::Kobject::cap().

+ Here is the call graph for this function:

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