NAME | SYNOPSIS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO
#include <mem/chMem.h>int rgnAllocate(KnCap *actorcap, KnRgnDesc *Rgndesc);
MEM_FLAT, MEM_PROTECTED, MEM_VIRTUAL
rgnAllocate creates a region in the target actor address space and maps some newly allocated volatile memory to the region.
The target actor is specified by actorcap - a pointer to the actor capability. If actorcap is K_MYACTOR, the address space of the current actor is used. If actorcap is K_SVACTOR, the region is allocated in the supervisor address space and is not attached to any particular supervisor actor; therefore, it cannot be implicitly deallocated by an actorDelete(2K) of a supervisor actor.
rgndesc points to a KnRgnDesc structure which contains the specification of the required region, and the members of which are the following:
VmAddr startAddr ; VmSize size ; VmFlags options ; VmAddr endAddr ; void* opaque1 ; VmFlags opaque2 ; |
If neither K_ANYWHERE nor K_RESTRICTIVE options (see below) are specified, startAddr is the region start address in the target address space. The region start address must be aligned with a virtual page boundary (see vmPageSize(2K)).
size is the size of the region in bytes. If the size is not page-aligned, the kernel rounds it up to the next virtual page boundary.
endAddr is only used with the K_RESTRICTIVE option (see below).
options is a combination of following flags:
The input value of startAddr is ignored, and the region is allocated wherever possible in the limits of the target address space as returned by vmStat(2K). In this case the region's start address is returned in startAddr.
The region is allocated wherever possible between startAddr and endAddr. If startAddr is not page-aligned, the kernel rounds it up to the next virtual page boundary. If endAddr is not page-aligned the kernel rounds it down to the preceding virtual page boundary. The created region start address is returned in startAddr. If this flag is set, the K_ANYWHERE flag is ignored.
If a rgnDup(2K) is subsequently applied, taking the target actor as the source, a copy of the region will be allocated in the destination address space by the rgnDup operation.
If a rgnDup(2K) is subsequently applied, taking the target actor as the source, the region will be made shared by the rgnDup operation.
The memory eventually allocated for the region is zero-filled. Otherwise, the initial state of the memory is undefined.
Guarantees that no page faults occur during subsequent (legal) access to data within the region.
Do not wait for memory to become available. If the K_NOWAITFORMEMORY and K_NODEMAND flags are set, the rgnAllocate fails when there is not enough physical memory, and returns the K_ENOMEM error. If only K_NOWAITFORMEMORY is set, possible memory underflow during a future on demand allocation provokes a memory underflow exception. Otherwise memory underflow blocks and waits for memory to become available.
Guarantees that no pageouts occur for the data within the region.
The region is a reserved region. If K_RESERVED option is set all other options, except of K_ANYWHERE or K_RESTRICTIVE ones, are ignored. Virtual-to-physical mappings (attributes as well as addresses) of a reserved region are managed from the kernel using svPhysMap(9DKI) call. A thread can access to any effectively mapped (valid) address within a reserved region, but any fault provokes an exception processing (see svExcHandler(2K)). Mapped portions of reserved regions can also be used as data buffers for IPC messages, vmCopy, sgRead, etc. A reserved region can be deallocated by a regular rgnFree or actorDelete operation. Any other kernel operation performed on a reserved region either has no effect (eg. rgnSetProtect(2K) ), or returns K_ENOTIMP (eg. vmFlush(2K) or rgnInitFromActor(2K) ).
Optimize future region extension toward low addresses (by default extension toward high addresses is optimized).
Read access is permitted. The current implementation always permits read access for backward compatibility reasons.
Write access is permitted.
Execute access is permitted.
The region is accessible only by supervisor threads.
The region will not be dumped if the target actor is core dumped.
Any access to a region conflicting with the region protections can potentially be reported by an exception (see svExcHandler(2K)) but the guarantes of such exceptions are machine-dependent. For instance, on any available paged memory hardware the kernel guarantees that a user-level write access to a read only region provokes a protection exception, but only on some of them the kernel guarantees to detect illegal access when a thread executes a region without K_EXECUTABLE attribute.
All flags specified in the options field as well as values specified by opaque1 and opaque2 fields compose region attributes. The attributes are stored in the kernel state associated with the region and can be consulted using rgnStat(2K) kernel call.
If successful K_OK, is returned. Otherwise a negative error code is returned.
Some of the provided arguments are outside the caller's address space.
An inconsistent actor capability was given.
actorcap does not specify a reachable actor.
rgndesc->startAddr is not page-aligned.
Try to allocate a region outside the valid range for the address space of an actor as returned by vmStat(2K).
rgndesc->size is 0.
The K_ANYWHERE option was specified and there is not enough room available in the address space to allocate the region.
The K_RESTRICTIVE option was specified and there is not enough room in the target address range.
The allocated region overlaps an existing region.
The system is out of resources.
The target actor and the current actor must be located on the same site.
The K_RESTRICTIVE option is valid only in the MEM_PROTECTED and MEM_VIRTUAL modules. This option is ignored by the MEM_FLAT module.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO