#include <mem/chMem.h>int rgnStat(KnCap *actorcap, KnRgnDesc *rgndesc, KnRgnStat *stat, unsigned buffsize);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
MEM_FLAT, MEM_PROTECTED, MEM_VIRTUAL
The rgnStat() function gets the status of regions from the given address range of the target actor address space.
The target actor is specified by actorcap, which is a pointer to the actor capability. If actorcap is -K_MYACTOR, the address space of the current actor is used. If the target actor is a user actor, rgnStat() takes all regions of the target address range into account. If the target actor is a supervisor actor, rgnStat() only takes into account the regions attached to the target supervisor actor. If actorcap is -K_SVACTOR, rgnStat() takes all regions of the target supervisor address range into account.
The rgndesc pointer points to a KnRgnDesc structure which contains the specification of the target address range. Only the following members of the structure are used:
VmAddr startAddr ; VmSize size ; VmFlags options
The startAddr field gives the start of the target address range and the size field gives its size.
The stat argument points to a buffer in which the description of the region is returned. The buffsize argument gives the size of the buffer. If the -K_USERSPACE flag is set in rgndesc->option, the buffer is in the current user address space. Otherwise the buffer is in the caller (current user or supervisor) address space.
Status is returned as a number of items, each one describing a particular sub-range of the target address range. The KnRgnStat structure defines the fields of each item, as follows:
VmAddr startAddr ; VmSize size ; VmFlags options ; void* opaque1 ; VmFlags opaque2 ; VmOffset offset ; KnLcStat lcstat ;
The startAddr field is the starting address of the sub-range described by the item and size is size of the sub-range. There is exactly one item per region which has a non-empty intersection with the target address range. Items are sorted by increasing order of startAddr. If rgndesc->startAddr is inside a region, the startAddr of the first item is equal to rgndesc->startAddr. If rgndesc->startAddr + rgndesc->size is inside a region, the size of the last item is equal to (rgndesc->startAddr + rgndesc->size) - rgn_start_addr, where rgn_start_addr is the start address of the last region of the target range. Otherwise, an item describes precisely one region.
The options field defines the region options as specified in rgnAllocate(2K).
The following four fields are only meaningful if virtual memory management is being used.
The values opaque1 and opaque2 define the opaque values associated with the region.
The offset value defines the offset of the item's startAddr within the mapped segment.
If the -K_RGNFULLSTAT flag is set in the rgndesc->options field, the lcstat field contains the following status information about the range of the local cache mapped to the item's adress range:
VmSize physMem ; VmSize lockMem ; KnCap segcap; KnCap lccap ;
The physMem field contains the size (in bytes) of the physical memory mapped to the address range.
The lockMem field contains the size (in bytes) of no-demand physical memory mapped to the address range.
If the target local cache corresponds to an external segment, the segcap field contains the capability of the segment. Otherwise the field contains zero.
If the target local cache can be designated by a capability, the lccap field contains the capability of the local cache. Otherwise the field contains zero.
If successful, rgnStat() returns the number of items needed to describe the target address range. Otherwise a negative error code is returned. When the MEM_FLAT module is enabled and the caller is a supervisor actor (-K_SVACTOR), this primitive returns 0. In this case no regions are available.
Some of the arguments provided are outside the caller's address space.
An inconsistent actor capability was given, or the options flags of the second argument are incorrect.
actorcap does not specify a reachable actor.
The target actor and the current actor must be located on the same site.
See attributes(5) for descriptions of the following attributes:
|ATTRIBUTE TYPE||ATTRIBUTE VALUE|