|
L4Re Operating System Framework
Interface and Usage Documentation
|
#include <l4/re/rm>
Data Structures | |
| struct | F |
| Rm flags definitions. More... | |
| class | Unique_region |
| Unique region. More... | |
| struct | Region |
| A region is a range of virtual addresses which is backed by content. More... | |
| struct | Area |
| An area is a range of virtual addresses which is reserved, see L4Re::Rm::reserve_area(). More... | |
Public Types | |
| enum | Detach_result { Detached_ds = 0 , Kept_ds = 1 , Split_ds = 2 , Detach_result_mask = 3 , Detach_again = 4 , Unmapped_range = 8 } |
| Result values for detach operation. More... | |
| enum | Region_flag_shifts { Caching_shift = Dataspace::F::Caching_shift } |
| Region flag shifts. More... | |
| enum | Detach_flags { Detach_exact = 1 , Detach_overlap = 2 } |
| Flags for detach operation. More... | |
| typedef l4_ret_t(* | page_in_fn) (l4_addr_t min_addr, l4_addr_t max_addr, Region_flags rights) |
| In-thread eager paging function. | |
| typedef L4::Typeid::Rpcs< attach_t, detach_t, find_t, reserve_area_t, free_area_t, get_regions_t, get_areas_t, get_info_t, add_rescue_jump_t, remove_rescue_jump_t, page_in_t > | Rpcs |
| Eager paging RPC call. | |
Public Member Functions | |
| l4_ret_t | reserve_area (l4_addr_t *start, unsigned long size, Flags flags=Flags(0), unsigned char align=L4_PAGESHIFT) const noexcept |
| Reserve the given area in the region map. | |
| template<typename T> | |
| l4_ret_t | reserve_area (T **start, unsigned long size, Flags flags=Flags(0), unsigned char align=L4_PAGESHIFT) const noexcept |
| Reserve the given area in the region map. | |
| l4_ret_t | free_area (l4_addr_t addr) |
| Free an area from the region map. | |
| l4_ret_t | attach (l4_addr_t *start, unsigned long size, Flags flags, L4::Ipc::Cap< Dataspace > mem, Offset offs=0, unsigned char align=L4_PAGESHIFT, L4::Cap< L4::Task > const task=L4::Cap< L4::Task >::Invalid, char const *name=nullptr, Offset backing_offset=0) const noexcept |
| Attach a data space to a region. | |
| template<typename T> | |
| l4_ret_t | attach (T **start, unsigned long size, Flags flags, L4::Ipc::Cap< Dataspace > mem, Offset offs=0, unsigned char align=L4_PAGESHIFT, L4::Cap< L4::Task > const task=L4::Cap< L4::Task >::Invalid, char const *name=nullptr, Offset backing_offset=0) const noexcept |
| Attach a data space to a region. | |
| l4_ret_t | detach (l4_addr_t addr, L4::Cap< Dataspace > *mem, L4::Cap< L4::Task > const &task=This_task) const noexcept |
| Detach and unmap a region from the address space. | |
| l4_ret_t | detach (void *addr, L4::Cap< Dataspace > *mem, L4::Cap< L4::Task > const &task=This_task) const noexcept |
| Detach and unmap a region from the address space. | |
| l4_ret_t | detach (l4_addr_t start, unsigned long size, L4::Cap< Dataspace > *mem, L4::Cap< L4::Task > const &task=This_task) const noexcept |
| Detach and unmap all parts of the regions within the specified interval. | |
| l4_ret_t | find (l4_addr_t *addr, unsigned long *size, Offset *offset, L4Re::Rm::Flags *flags, L4::Cap< Dataspace > *m) noexcept |
| Find a region given an address and size. | |
| l4_ret_t | get_regions (l4_addr_t start, L4::Ipc::Array_ref< Region > ®ions) |
| Return the list of regions whose starting addresses are higher or equal to start in the address space managed by this region map. | |
| long | get_areas (l4_addr_t start, L4::Ipc::Array_ref< Area > &areas) |
| Return the list of areas whose starting addresses are higher or equal to start in the address space managed by this region map. | |
| l4_ret_t | get_info (l4_addr_t addr, L4::Ipc::String< char > &name, Offset &backing_offset) |
| Return auxiliary information of a region. | |
| l4_ret_t | add_rescue_jump (l4_addr_t pc_begin, l4_addr_t pc_end, l4_addr_t rescue_pc) |
| Register a rescue jump for a range of program counters. | |
| l4_ret_t | remove_rescue_jump (l4_addr_t pc) |
| Remove a previously registered rescue jump. | |
| l4_ret_t | page_in (l4_addr_t start, unsigned long size, Region_flags rights, L4::Cap< L4::Task > dst=L4::Cap< L4::Task >::Invalid) const noexcept |
| Allocate and map pages for the given region. | |
| Public Member Functions inherited from L4::Pager | |
| l4_msgtag_t | page_fault (l4_umword_t pfa, l4_umword_t pc, L4::Ipc::Rcv_fpage rwin, L4::Ipc::Opt< L4::Ipc::Snd_fpage & > fp) |
| Page-fault protocol message. | |
| Public Member Functions inherited from L4::Io_pager | |
| l4_msgtag_t | io_page_fault (l4_fpage_t io_pfa, l4_umword_t pc, L4::Ipc::Rcv_fpage rwin, L4::Ipc::Opt< L4::Ipc::Snd_fpage & > fp) |
| IO page fault protocol message. | |
Additional Inherited Members | |
| Protected Types inherited from L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > > | |
| typedef Rm | Class |
| The target interface type (inheriting from Kobject_t). | |
| typedef Typeid::Iface< PROTO, Rm > | __Iface |
| The interface description for the derived class. | |
| typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename L4::Pager::__Iface_list > | __Iface_list |
| The list of all RPC interfaces provided directly or through inheritance. | |
| Protected Types inherited from L4::Kobject_t< Pager, Io_pager, L4_PROTO_PAGE_FAULT > | |
| typedef Pager | Class |
| The target interface type (inheriting from Kobject_t). | |
| typedef Typeid::Iface< PROTO, Pager > | __Iface |
| The interface description for the derived class. | |
| typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Io_pager::__Iface_list > | __Iface_list |
| The list of all RPC interfaces provided directly or through inheritance. | |
| Protected Member Functions inherited from L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > > | |
| L4::Cap< Class > | c () const noexcept |
| Get the capability to ourselves. | |
| Protected Member Functions inherited from L4::Kobject_t< Pager, Io_pager, L4_PROTO_PAGE_FAULT > | |
| L4::Cap< Class > | c () const noexcept |
| Get the capability to ourselves. | |
| Static Protected Member Functions inherited from L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > > | |
| static void | __check_protocols__ () noexcept |
| Helper to check for protocol conflicts. | |
| Static Protected Member Functions inherited from L4::Kobject_t< Pager, Io_pager, L4_PROTO_PAGE_FAULT > | |
| static void | __check_protocols__ () noexcept |
| Helper to check for protocol conflicts. | |
Register a rescue jump for a range of program counters.
If a synchronous exception (e.g. a SIGSEGV with SEGV_MAPERR) is raised by an instruction whose program counter lies in the half-open range [pc_begin, pc_end), execution is diverted to rescue_pc instead of delivering the signal to the application.
The registered rescue jumps must not overlap.
| pc_begin | Inclusive start of the instruction range. |
| pc_end | Exclusive end of the instruction range. |
| rescue_pc | Program counter to jump to on a fault in the range. |
| 0 | Success |
| -L4_EINVAL | Invalid arguments (e.g. pc_begin >= pc_end). |
| -L4_EEXIST | The given range overlaps with an already registered rescue jump. |
| -L4_ENOMEM | Out of memory. |
| <0 | IPC errors |
Referenced by get_info().
|
noexcept |
Attach a data space to a region.
| [in,out] | start | Virtual start address where the region manager shall attach the data space. Will be rounded down to the nearest start of a page. If L4Re::Rm::F::Search_addr is given this value is used as the start address to search for a free virtual memory region and the resulting address is returned here. If L4Re::Rm::F::In_area is given the value is used as a selector for the area (see L4Re::Rm::reserve_area) to attach the data space to. |
| size | Size of the data space to attach (in bytes). Will be rounded up to the nearest multiple of the page size. | |
| flags | The flags control how and with which rights the dataspace is attached to the region. See L4Re::Rm::F::Attach_flags and L4Re::Rm::F::Region_flags. The caller must specify the desired rights of the attached region explicitly. The default set of rights is empty. | |
| mem | Data space. | |
| offs | Offset into the data space to use. | |
| align | Alignment of the virtual region, log2-size, default: a page (L4_PAGESHIFT). This is only meaningful if the L4Re::Rm::F::Search_addr flag is used. | |
| task | Optional destination task of mapping if F::Eager_map flag was passed. If invalid, the mapping is established in the current task. This parameter is only useful if the region manager is for a foreign task. | |
| name | Optional name of the region. | |
| backing_offset | Optional value describing an offset into the backing store of this region. |
| 0 | Success |
| -L4_ENOENT | No area could be found (see L4Re::Rm::F::In_area) |
| -L4_EPERM | Operation not allowed. |
| -L4_EINVAL | |
| -L4_EADDRNOTAVAIL | The given address is not available. |
| <0 | IPC errors |
Makes the whole or parts of a data space visible in the virtual memory of the corresponding task. The corresponding region in the virtual address space is backed with the contents of the dataspace.
Definition at line 38 of file rm_impl.h.
References L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > >::c(), L4Re::Rm::F::Eager_map, L4Re::Rm::F::Kernel, L4Re::Rm::F::No_eager_map, page_in(), L4Re::Rm::F::Reserved, L4Re::Rm::F::Rights_mask, and L4Re::Rm::F::RWX.
Referenced by attach(), and free_area().
|
inlinenoexcept |
Attach a data space to a region.
| [in,out] | start | Virtual start address where the region manager shall attach the data space. Will be rounded down to the nearest start of a page. If L4Re::Rm::F::Search_addr is given this value is used as the start address to search for a free virtual memory region and the resulting address is returned here. If L4Re::Rm::F::In_area is given the value is used as a selector for the area (see L4Re::Rm::reserve_area) to attach the data space to. |
| size | Size of the data space to attach (in bytes). Will be rounded up to the nearest multiple of the page size. | |
| flags | The flags control how and with which rights the dataspace is attached to the region. See L4Re::Rm::F::Attach_flags and L4Re::Rm::F::Region_flags. The caller must specify the desired rights of the attached region explicitly. The default set of rights is empty. | |
| mem | Data space. | |
| offs | Offset into the data space to use. | |
| align | Alignment of the virtual region, log2-size, default: a page (L4_PAGESHIFT). This is only meaningful if the L4Re::Rm::F::Search_addr flag is used. | |
| task | Optional destination task of mapping if F::Eager_map flag was passed. If invalid, the mapping is established in the current task. This parameter is only useful if the region manager is for a foreign task. | |
| name | Optional name of the region. | |
| backing_offset | Optional value describing an offset into the backing store of this region. |
| 0 | Success |
| -L4_ENOENT | No area could be found (see L4Re::Rm::F::In_area) |
| -L4_EPERM | Operation not allowed. |
| -L4_EINVAL | |
| -L4_EADDRNOTAVAIL | The given address is not available. |
| <0 | IPC errors |
Makes the whole or parts of a data space visible in the virtual memory of the corresponding task. The corresponding region in the virtual address space is backed with the contents of the dataspace.
Definition at line 405 of file rm.
References attach(), and L4_PAGESHIFT.
|
inlinenoexcept |
Detach and unmap a region from the address space.
| addr | Virtual address of region, any address within the region is valid. | |
| [out] | mem | Dataspace that is affected. Give 0 if not interested. |
| task | This argument specifies the task where the pages are unmapped. Provide L4::Cap<L4::Task>::Invalid for none. The default is the current task. |
| L4Re::Rm::Detach_result | On success. |
| -L4_ENOENT | No region found. |
| <0 | IPC errors |
Frees a region in the virtual address space given by addr (address type). The corresponding part of the address space is now available again.
Definition at line 886 of file rm.
References detach(), and Detach_overlap.
Referenced by detach(), detach(), detach(), free_area(), and remove_rescue_jump().
|
inlinenoexcept |
Detach and unmap all parts of the regions within the specified interval.
| start | Start of area to detach, must be within region. | |
| size | Size of of area to detach (in bytes). | |
| [out] | mem | Dataspace that is affected. Give 0 if not interested. |
| task | This argument specifies the task where the pages are unmapped. Provide L4::Cap<L4::Task>::Invalid for none. The default is the current task. |
| L4Re::Rm::Detach_result | On success. |
| -L4_ENOENT | No region found. |
| <0 | IPC errors |
Frees all regions within the interval given by start and size. If a region overlaps the start or the end of the interval this region is only detached partly. If the interval is within one region the original region is split up into two separate regions.
Definition at line 899 of file rm.
References detach(), and Detach_exact.
|
inlinenoexcept |
Detach and unmap a region from the address space.
| addr | Virtual address of region, any address within the region is valid. | |
| [out] | mem | Dataspace that is affected. Give 0 if not interested. |
| task | This argument specifies the task where the pages are unmapped. Provide L4::Cap<L4::Task>::Invalid for none. The default is the current task. |
| L4Re::Rm::Detach_result | On success. |
| -L4_ENOENT | No region found. |
| <0 | IPC errors |
Frees a region in the virtual address space given by addr (address type). The corresponding part of the address space is now available again.
Definition at line 891 of file rm.
References detach(), and Detach_overlap.
|
inlinenoexcept |
Find a region given an address and size.
| [in,out] | addr | Address to look for. Returns the start address of the found region. |
| [in,out] | size | Size of the area to look for (in bytes). Returns the size of the found region (in bytes). |
| [out] | offset | Offset at the beginning of the region within the associated dataspace. |
| [out] | flags | Region flags, see F::Region_flags (and F::In_area). |
| [out] | m | Associated dataspace or paging service. |
| 0 | Success |
| -L4_EPERM | Operation not allowed. |
| -L4_ENOENT | No region found. |
| <0 | IPC errors |
This function returns the properties of the region that contains the area described by the addr and size parameter. If no such region is found but a reserved area, the area is returned and F::In_area is set in flags. Note, in the case of an area the offset and m return values are invalid.
size-out
/ \
/ \
addr-out \
^________________\
------------|----------------|------------------
| | Region | Dataspace |
| |_______|___|____| |
------------|-------|---|-----------------------
\ / |\ /
\ / | |> size-in
offset-out |
|> addr-in
Definition at line 671 of file rm.
References L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > >::c().
Free an area from the region map.
| addr | An address within the area to free. |
| 0 | Success |
| -L4_ENOENT | No area found. |
| <0 | IPC errors |
References attach(), detach(), free_area(), L4::Cap_base::Invalid, and L4_PAGESHIFT.
Referenced by free_area().
| long L4Re::Rm::get_areas | ( | l4_addr_t | start, |
| L4::Ipc::Array_ref< Area > & | areas ) |
Return the list of areas whose starting addresses are higher or equal to start in the address space managed by this region map.
| start | Virtual address from where to start searching. | |
| [out] | areas | List of areas found in this region map. |
| >=0 | Number of returned areas in the areas array. |
| <0 | IPC errors |
References get_areas(), and get_info().
Referenced by get_areas().
| l4_ret_t L4Re::Rm::get_info | ( | l4_addr_t | addr, |
| L4::Ipc::String< char > & | name, | ||
| Offset & | backing_offset ) |
Return auxiliary information of a region.
This is a debugging feature and might not be available.
| addr | Virtual address of the region. | |
| [out] | name | Name of the region. |
| [out] | backing_offset | Backing offset information. |
| 0 | Success |
| -L4_ENOENT | Region not found. |
| -L4_ENOSYS | Function not available. |
| <0 | IPC errors |
References add_rescue_jump().
Referenced by get_areas().
| l4_ret_t L4Re::Rm::get_regions | ( | l4_addr_t | start, |
| L4::Ipc::Array_ref< Region > & | regions ) |
Return the list of regions whose starting addresses are higher or equal to start in the address space managed by this region map.
| start | Virtual address from where to start searching. | |
| [out] | regions | List of regions found in this region map. |
| >=0 | Number of returned regions in the regions array. |
| <0 | IPC errors |
References get_regions().
Referenced by get_regions().
|
noexcept |
Allocate and map pages for the given region.
Establish mappings of all pages in a region so that no page faults should happen after the call returned. Note that dataspace providers may unmap pages at their own discretion. This call is therefore no guarantee that page faults cannot happen.
The whole range must be backed by attached regions. It is not possible to request more rights than with what the region was attached in the first place.
| start | Start address. |
| size | Size of region. |
| rights | Requested mapping attributes (any combination of F::R, F::W and F::X). |
| dst | Optional destination task of mapping. If invalid, the mapping is established in the current task. This parameter is only useful if the region manager is for a foreign task. |
| 0 | Success |
| -L4_EACCESS | More rights requested than attached region. |
| -L4_ENOENT | At least some part of the range was not covered by a region. |
| -L4_ENODEV | Region was not backed by a dataspace. |
| <0 | IPC errors and other errors from dataspace provider (see L4Re::Dataspace::map). |
Definition at line 116 of file rm_impl.h.
References L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > >::c(), L4_EINVAL, L4_WHOLE_ADDRESS_SPACE, L4::Ipc::Rcv_fpage::mem(), L4Re::Rm::F::R, L4::Ipc::Snd_fpage::rcv_order(), and L4Re::Rm::F::RWX.
Referenced by attach(), and remove_rescue_jump().
Remove a previously registered rescue jump.
The rescue jump whose instruction range contains pc is removed.
| pc | Any program counter inside the registered range. |
| 0 | Success |
| -L4_ENOENT | No rescue jump covers pc. |
| <0 | IPC errors |
References detach(), L4::Cap_base::Invalid, page_in(), and remove_rescue_jump().
Referenced by remove_rescue_jump().
|
inlinenoexcept |
Reserve the given area in the region map.
| [in,out] | start | The virtual start address of the area to reserve. Returns the start address of the area. |
| size | The size of the area to reserve (in bytes). | |
| flags | Flags for the reserved area (see F::Search_addr, F::Kernel and F::Reserved). | |
| align | Alignment of area if searched as bits (log2 value). |
| 0 | Success |
| -L4_EADDRNOTAVAIL | The given area cannot be reserved. |
| -L4_EINVAL | Invalid parameters |
| <0 | IPC errors |
This function reserves an area within the virtual address space managed by the region map. There are two kinds of areas available:
Definition at line 275 of file rm.
References L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > >::c(), and L4_PAGESHIFT.
|
inlinenoexcept |
Reserve the given area in the region map.
| [in,out] | start | The virtual start address of the area to reserve. Returns the start address of the area. |
| size | The size of the area to reserve (in bytes). | |
| flags | Flags for the reserved area (see F::Search_addr, F::Kernel and F::Reserved). | |
| align | Alignment of area if searched as bits (log2 value). |
| 0 | Success |
| -L4_EADDRNOTAVAIL | The given area cannot be reserved. |
| -L4_EINVAL | Invalid parameters |
| <0 | IPC errors |
For more information, please refer to the analogous function
Definition at line 304 of file rm.
References L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > >::c(), and L4_PAGESHIFT.