NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUES | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO
#include <mem/chMem.h>int rgnAllocate(KnCap *actorcap, KnRgnDesc *Rgndesc);
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
rgnAllocate() creates a region in the target actor address space and maps 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. The members of KnRgnDesc 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) is 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 microkernel 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 the 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 microkernel rounds it up to the next virtual page boundary. If endAddr is not page-aligned the microkernel rounds it down to the preceding virtual page boundary. The start address of the created region is returned in startAddr. If this flag is set, the K_ANYWHERE flag is ignored.
If an rgnDup(2K) is subsequently applied, taking the target actor as the source, a copy of the region is allocated in the destination address space by the rgnDup() operation.
If an rgnDup(2K) is subsequently applied, taking the target actor as the source, the region is 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, 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 the K_RESERVED option is set, all other options, with the exception of K_ANYWHERE and K_RESTRICTIVE, are ignored. Virtual-to-physical mappings (attributes as well as addresses) of a reserved region are managed from the microkernel using the svPhysMap(9DKI) call. A thread can access any effectively mapped (valid) address within a reserved region, but any fault provokes an exception (see svExcHandler(2K)). Mapped portions of reserved regions can also be used as data buffers for IPC messages, such as vmCopy(2K). A reserved region can be deallocated by a regular rgnFree(2K) or actorDelete(2K) operation. Any other microkernel operation performed on a reserved region either has no effect (see rgnSetProtect(2K)), or returns K_ENOTIMP (see rgnInitFromActor(2K)).
Optimize future region extension toward low addresses (extension toward high addresses is optimized by default).
Read access is permitted. The current implementation always permits read access for backward compatibility.
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 guarantees of such exceptions are machine-dependent. On paged-memory hardware, for example, the microkernel guarantees that user-level write access to a read-only region provokes a protection exception, but only guarantees detection of illegal access when a thread executes a region without K_EXECUTABLE attribute on certain platforms.
All flags specified in the options field, as well as values specified by opaque1 and opaque2 fields, specify region attributes. The attributes are stored in the microkernel state associated with the region and can be consulted using the rgnStat(2K) microkernel call.
If successful K_OK, is returned. Otherwise a negative error code is returned.
Some of the arguments provided are outside the caller's address space.
An inconsistent actor capability was given.
The K_INHERITSHARE and the K_INHERITCOPY option flags are being used together.
actorcap does not specify a reachable actor.
rgndesc->startAddr is not page-aligned.
An attempt was made to allocate a region outside the valid range for the address space of an actor, as returned by vmStat(2K).
rgndesc->size is 0.
rgndesc->startAddr is not page-aligned. This error code is not returned with the FLAT memory model.
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 K_SUPERVISOR option was specified and the actor is not a system actor.
The allocated region overlaps an existing region.
The system is out of resources.
The K_ANYWHERE option cannot be used with the K_RESERVED option when the memory feature is MEM_FLAT. K_EINVAL is returned. Opaque fields are only supported for the MEM_VIRTUAL memory feature.
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 | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUES | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO