ChorusOS man pages section 2K: Kernel System Calls

rgnStat(2K)

NAME

rgnStat- get the statistics of a region of an actor address space

SYNOPSIS

#include <mem/chMem.h>

actorcap

rgndesc

stat

buffsize

API RESTRICTIONS

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.

FEATURES

MEM_FLAT, MEM_PROTECTED, MEM_VIRTUAL

DESCRIPTION

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

Note -

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.

RETURN VALUE

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.

ERRORS

K_EFAULT: Some of the arguments provided are outside the caller's address space.
K_EINVAL: An inconsistent actor capability was given, or the options flags of the second argument are incorrect.
K_EUNKNOWN: actorcap does not specify a reachable actor.

RESTRICTIONS

The target actor and the current actor must be located on the same site.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving