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

Region map. More...

#include <l4/re/rm>

Inheritance diagram for L4Re::Rm:
Collaboration diagram for L4Re::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 > &regions)
 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< Classc () const noexcept
 Get the capability to ourselves.
Protected Member Functions inherited from L4::Kobject_t< Pager, Io_pager, L4_PROTO_PAGE_FAULT >
L4::Cap< Classc () 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.

Detailed Description

Region map.

See also
Region map API .

Definition at line 81 of file rm.

Member Enumeration Documentation

◆ Detach_flags

Flags for detach operation.

Enumerator
Detach_exact 

Do an unmap of the exact region given.

Detach_overlap 

Do an unmap of all overlapping regions.

Definition at line 223 of file rm.

◆ Detach_result

Result values for detach operation.

Enumerator
Detached_ds 

Detached data space.

Kept_ds 

Kept data space.

Split_ds 

Split data space, and done.

Detach_again 

Detached data space, more to do.

Unmapped_range 

The region mananager has already unmapped the pages.

Definition at line 89 of file rm.

◆ Region_flag_shifts

Region flag shifts.

Enumerator
Caching_shift 

Start of Rm cache bits.

Definition at line 102 of file rm.

Member Function Documentation

◆ add_rescue_jump()

l4_ret_t L4Re::Rm::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.

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.

Parameters
pc_beginInclusive start of the instruction range.
pc_endExclusive end of the instruction range.
rescue_pcProgram counter to jump to on a fault in the range.
Return values
0Success
-L4_EINVALInvalid arguments (e.g. pc_begin >= pc_end).
-L4_EEXISTThe given range overlaps with an already registered rescue jump.
-L4_ENOMEMOut of memory.
<0IPC errors

Referenced by get_info().

Here is the caller graph for this function:

◆ attach() [1/2]

l4_ret_t L4Re::Rm::attach ( l4_addr_t * start,
unsigned long size,
Rm::Flags flags,
L4::Ipc::Cap< Dataspace > mem,
Rm::Offset offs = 0,
unsigned char align = L4_PAGESHIFT,
L4::Cap< L4::Task > const task = L4::Cap<L4::Task>::Invalid,
char const * name = nullptr,
Rm::Offset backing_offset = 0 ) const
noexcept

Attach a data space to a region.

Parameters
[in,out]startVirtual 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.
sizeSize of the data space to attach (in bytes). Will be rounded up to the nearest multiple of the page size.
flagsThe 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.
memData space.
offsOffset into the data space to use.
alignAlignment 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.
taskOptional 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.
nameOptional name of the region.
backing_offsetOptional value describing an offset into the backing store of this region.
Return values
0Success
-L4_ENOENTNo area could be found (see L4Re::Rm::F::In_area)
-L4_EPERMOperation not allowed.
-L4_EINVAL
-L4_EADDRNOTAVAILThe given address is not available.
<0IPC 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.

Note
When searching for a free place in the virtual address space, the space between start and the end of the virtual address space is searched.
There is no region object created, instead the region is defined by a virtual address within this range (see L4Re::Rm::find).

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

Here is the call graph for this function:
Here is the caller graph for this function:

◆ attach() [2/2]

template<typename T>
l4_ret_t L4Re::Rm::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
inlinenoexcept

Attach a data space to a region.

Parameters
[in,out]startVirtual 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.
sizeSize of the data space to attach (in bytes). Will be rounded up to the nearest multiple of the page size.
flagsThe 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.
memData space.
offsOffset into the data space to use.
alignAlignment 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.
taskOptional 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.
nameOptional name of the region.
backing_offsetOptional value describing an offset into the backing store of this region.
Return values
0Success
-L4_ENOENTNo area could be found (see L4Re::Rm::F::In_area)
-L4_EPERMOperation not allowed.
-L4_EINVAL
-L4_EADDRNOTAVAILThe given address is not available.
<0IPC 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.

Note
When searching for a free place in the virtual address space, the space between start and the end of the virtual address space is searched.
There is no region object created, instead the region is defined by a virtual address within this range (see L4Re::Rm::find).

Definition at line 405 of file rm.

References attach(), and L4_PAGESHIFT.

Here is the call graph for this function:

◆ detach() [1/3]

l4_ret_t L4Re::Rm::detach ( l4_addr_t addr,
L4::Cap< Dataspace > * mem,
L4::Cap< L4::Task > const & task = This_task ) const
inlinenoexcept

Detach and unmap a region from the address space.

Parameters
addrVirtual address of region, any address within the region is valid.
[out]memDataspace that is affected. Give 0 if not interested.
taskThis argument specifies the task where the pages are unmapped. Provide L4::Cap<L4::Task>::Invalid for none. The default is the current task.
Return values
L4Re::Rm::Detach_resultOn success.
-L4_ENOENTNo region found.
<0IPC 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().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ detach() [2/3]

l4_ret_t L4Re::Rm::detach ( l4_addr_t start,
unsigned long size,
L4::Cap< Dataspace > * mem,
L4::Cap< L4::Task > const & task = This_task ) const
inlinenoexcept

Detach and unmap all parts of the regions within the specified interval.

Parameters
startStart of area to detach, must be within region.
sizeSize of of area to detach (in bytes).
[out]memDataspace that is affected. Give 0 if not interested.
taskThis argument specifies the task where the pages are unmapped. Provide L4::Cap<L4::Task>::Invalid for none. The default is the current task.
Return values
L4Re::Rm::Detach_resultOn success.
-L4_ENOENTNo region found.
<0IPC 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.

Here is the call graph for this function:

◆ detach() [3/3]

l4_ret_t L4Re::Rm::detach ( void * addr,
L4::Cap< Dataspace > * mem,
L4::Cap< L4::Task > const & task = This_task ) const
inlinenoexcept

Detach and unmap a region from the address space.

Parameters
addrVirtual address of region, any address within the region is valid.
[out]memDataspace that is affected. Give 0 if not interested.
taskThis argument specifies the task where the pages are unmapped. Provide L4::Cap<L4::Task>::Invalid for none. The default is the current task.
Return values
L4Re::Rm::Detach_resultOn success.
-L4_ENOENTNo region found.
<0IPC 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.

Here is the call graph for this function:

◆ find()

l4_ret_t L4Re::Rm::find ( l4_addr_t * addr,
unsigned long * size,
Offset * offset,
L4Re::Rm::Flags * flags,
L4::Cap< Dataspace > * m )
inlinenoexcept

Find a region given an address and size.

Parameters
[in,out]addrAddress to look for. Returns the start address of the found region.
[in,out]sizeSize of the area to look for (in bytes). Returns the size of the found region (in bytes).
[out]offsetOffset at the beginning of the region within the associated dataspace.
[out]flagsRegion flags, see F::Region_flags (and F::In_area).
[out]mAssociated dataspace or paging service.
Return values
0Success
-L4_EPERMOperation not allowed.
-L4_ENOENTNo region found.
<0IPC 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
Note
The value of the size input parameter should be 1 to assure that a region can be determined unambiguously.

Definition at line 671 of file rm.

References L4::Kobject_t< Rm, L4::Pager, L4RE_PROTO_RM, L4::Type_info::Demand_t< 1 > >::c().

Here is the call graph for this function:

◆ free_area()

l4_ret_t L4Re::Rm::free_area ( l4_addr_t addr)

Free an area from the region map.

Parameters
addrAn address within the area to free.
Return values
0Success
-L4_ENOENTNo area found.
<0IPC errors
Note
The data spaces that are attached to that area are not detached by this operation.
See also
reserve_area() for more information about areas.

References attach(), detach(), free_area(), L4::Cap_base::Invalid, and L4_PAGESHIFT.

Referenced by free_area().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ get_areas()

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.

Parameters
startVirtual address from where to start searching.
[out]areasList of areas found in this region map.
Return values
>=0Number of returned areas in the areas array.
<0IPC errors
Note
The returned list of areas might not be complete and the caller shall use the function repeatedly with a start address one larger than the end address of the last area from the previous call.

References get_areas(), and get_info().

Referenced by get_areas().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ get_info()

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.

Parameters
addrVirtual address of the region.
[out]nameName of the region.
[out]backing_offsetBacking offset information.
Return values
0Success
-L4_ENOENTRegion not found.
-L4_ENOSYSFunction not available.
<0IPC errors

References add_rescue_jump().

Referenced by get_areas().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ get_regions()

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.

Parameters
startVirtual address from where to start searching.
[out]regionsList of regions found in this region map.
Return values
>=0Number of returned regions in the regions array.
<0IPC errors
Note
The returned list of regions might not be complete and the caller shall use the function repeatedly with a start address one larger that the end address of the last region from the previous call.

References get_regions().

Referenced by get_regions().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ page_in()

l4_ret_t L4Re::Rm::page_in ( l4_addr_t start,
unsigned long size,
Rm::Region_flags rights,
L4::Cap< L4::Task > dst = L4::Cap<L4::Task>::Invalid ) const
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.

Parameters
startStart address.
sizeSize of region.
rightsRequested mapping attributes (any combination of F::R, F::W and F::X).
dstOptional 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.
Return values
0Success
-L4_EACCESSMore rights requested than attached region.
-L4_ENOENTAt least some part of the range was not covered by a region.
-L4_ENODEVRegion was not backed by a dataspace.
<0IPC 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().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ remove_rescue_jump()

l4_ret_t L4Re::Rm::remove_rescue_jump ( l4_addr_t pc)

Remove a previously registered rescue jump.

The rescue jump whose instruction range contains pc is removed.

Parameters
pcAny program counter inside the registered range.
Return values
0Success
-L4_ENOENTNo rescue jump covers pc.
<0IPC errors

References detach(), L4::Cap_base::Invalid, page_in(), and remove_rescue_jump().

Referenced by remove_rescue_jump().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ reserve_area() [1/2]

l4_ret_t L4Re::Rm::reserve_area ( l4_addr_t * start,
unsigned long size,
Flags flags = Flags(0),
unsigned char align = L4_PAGESHIFT ) const
inlinenoexcept

Reserve the given area in the region map.

Parameters
[in,out]startThe virtual start address of the area to reserve. Returns the start address of the area.
sizeThe size of the area to reserve (in bytes).
flagsFlags for the reserved area (see F::Search_addr, F::Kernel and F::Reserved).
alignAlignment of area if searched as bits (log2 value).
Return values
0Success
-L4_EADDRNOTAVAILThe given area cannot be reserved.
-L4_EINVALInvalid parameters
<0IPC errors

This function reserves an area within the virtual address space managed by the region map. There are two kinds of areas available:

  • Reserved areas (flags = L4Re::Rm::F::Reserved), where no data spaces can be attached
  • Special purpose areas (flags = 0), where data spaces can be attached to the area via the L4Re::Rm::F::In_area flag and a start address within the area itself.
Note
When searching for a free place in the virtual address space (with flags = L4Re::Rm::F::Search_addr), the space between start and the end of the virtual address space is searched.

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.

Here is the call graph for this function:

◆ reserve_area() [2/2]

template<typename T>
l4_ret_t L4Re::Rm::reserve_area ( T ** start,
unsigned long size,
Flags flags = Flags(0),
unsigned char align = L4_PAGESHIFT ) const
inlinenoexcept

Reserve the given area in the region map.

Parameters
[in,out]startThe virtual start address of the area to reserve. Returns the start address of the area.
sizeThe size of the area to reserve (in bytes).
flagsFlags for the reserved area (see F::Search_addr, F::Kernel and F::Reserved).
alignAlignment of area if searched as bits (log2 value).
Return values
0Success
-L4_EADDRNOTAVAILThe given area cannot be reserved.
-L4_EINVALInvalid parameters
<0IPC errors

For more information, please refer to the analogous function

See also
L4Re::Rm::reserve_area.

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.

Here is the call graph for this function:

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