Specifiction for Eric v2.0
By Gavin R. Brewer
27/07/01
kVMem::kVMem( long target_task,
long& address,
long size,
int anywhere );
Arguments:
target_task Task whose virtual address space is to be affected.
address
Starting address. If the anwhere option is false,an attempt is made to allocate virtual memory, starting at the beginning of a virtual page, it will be rounded down to one. If there is not enough space at this address, no memory will be allocated. If the anywhere option is true, the input valie of this address will be ignored, and the space will be allocated wherever it is available.
size
Number of bytes to allocate, (rounded by the system in a machine dependent way to an integral number of virtual pages.)
anywhere
If true, the kernel should find and allocate any region of the specific size, and return the address of the resulting region in address. If false, virtual memory will be allocated starting at address, rounded to a virtual page boundary if there is sufficient space.
Description:
Allocates a region of virtual memory, placing it in the specified task's address space. The physical memory is not actually allocated until the new virtual memory is referenced. By default, the kernel rounds all addresses down to the nearset page boundary and all memory sizes up to the nearest page size.
The variable vm_page_size contains the page size. kTask::self() returns the value of the current task port which should be used as the target_task argument in order to allocate memory in the caller's address space. For languages other than C, these values can be obtained by the calls kVMem::statistics and ktask::self().
Initially, the pages of allocated memory will be protected to allow all forms of access, and may be used to change these properties. The allocated region is always zero-filled.
Throws:
ERIC_INVALID_ADDRESS Illegal address required
ERIC_NO_SPACE Not enough space left to satisfy this request.
kVMem::~kVMem( long target_task, long address, long size );
Arguments:
target_task Target whose virtual memory is to be affected.
address (will be rounded down to page boundary)
size Number of bytes to deallocate (will be rounded up to
give a page boundary).
Description:
relinquishes access to a region of a task's address space, causing further access to that memory to fail. This address range will be available for realloaction. Note, that because of the rounding to virtual page boundaries, more than size bytes may be deallocated.
Use page_size() or statistics() to find out about the current virtual page size.
This call may be used to dallocate memory that was passed to a task in a message (via out of line data). In that case, the rounding should caused no trouble, since the region of memory was allocated as a set of pages.
The deallocate() call affects only the task specified by the target_task. Other tasks which may have access to this memory may continue to reference it.
Throws:
ERIC_SUCCESS Memory deallocated
ERIC_INVALID_ADDRESS Illegal or non-allocated address
specified.
int kVMem::read( long target_task, long address,
int& size, int& data data_Cnt );
Argument:
target_task Task whose memory is to be read
address The first address to be read (page boundary)
size The number of bytes of data to be read.
data The array of data copied from the task
data_Cnt The size of the data array in bytes.
N.B Both size and data_Cnt are an integral no. of pages.
Description:
Allows on task's virtual memory to be read by another task. Note that
the data array is returned in a newly allocated region; the task reading
the data should deallocate() this region when it is done with the data.
Returns: ERIC_SUCCESS Memory written
ERIC_INVALID_ARG
Either the address does not start on a page boundary or the size is not an integral number of pages. ERIC_PROTECTION_FAILURE
The address region in the target task is protected against writing. ERIC_INVALID_ADDRESS
Illegal or non_allocated address specified or there is not data_count of allocated memory starting at address.
int kVMem::write( long target_task,
long address, Array <char> data,
int data_count );
Description:
Allows a task's virtual memory to be written by another task. Use page_size() or statistics to find out the virutal page size.
Returns:
ERIC_SUCCESS Memory written
ERIC_INVALID_ARG Either the addresss does not start on a page boundary or the size is not an inegral number of pages.
ERIC_PROTECTION_FAILURE The address region in the target task is protected against writing.
ERIC_INVALID_ADDRESS Illegal or non allocated address specified
or there is not data_Cnt of allocated memory starting at address.
int kVMem::copy( long target_task,
long source_address, int count,
long dest_address );
Arguments:
target_task Task whose virtual memory is to be affected source_address Address in target_task of the start of the source range. (Must be a page boundary). count Number of bytes (must be an integral number of pages). dest_address Address in target_task of th estart of the destination range (must be a page boundary).
Description:
Causes the source memory range to be copied to the destination address; the destination region may not overlap the source region. The destination address range must already be allocated and writable; the source range must be readable.
Returns:
ERIC_SUCCESS Memory copied
ERIC_INVALID_ARG Either the address udoes not start on a page boundary or the size is not an integral number of pages.
ERIC_PROTECTION_FAILURE Either the destination region was not
writable, or the source region was not readable.
int kVMem::( long target_task,
long& address,
int& size,
int& protection,
int& max_protection,
int inheritance,
int shared,
long& object_name,
int& offset );
Description:
Returns a description of the specified region of the target task's virtual address space. region() begins at 'address' and looks forward thru memory until until it comes to an allocated region. (If address is within a region, then that region is used.)
Various bits of information about the region are returned. If address was NOT within a region, then address is set to the start of the first region which follows the incoming value. In this way an entire address space can be scanned.
Returns:
ERIC_SUCCESS Region located and information returned. ERIC_NO_SPACE
There is no region at or above address in the specified task.
int kVMem::protect( long target_task, long address, long size,
int set_maximum, int new_protection );
Arguments:
target_task Task whose virtual memory is to be affected address Starting address (will be rounded down to boundary)
size Size in bytes of the rion for which protection is to change. (Will be rounded up to give a page boundary).
set_maximum If set, protection change apply to the maximum protection associated with this address range; otherwise, the current protection on this range is changed.
IF the maximum protection is reduced below the current protection, both will be changed to reflect the new maximum. new_protection A new protection value for this region; a set of: VM_PROT_READ, VM_PROT_WRITE, VM_PROT_EXECUTE.
Description:
Sets the virtual memory access privileges for a range of allocated addresses in a task's virtual address space. The protection argument describes a combination of read, write, and execute accesses that should be PERMITTED.
The enforcement of virtual memory protection is machine-dependent. Some combinations of access rights may not be supported. In particular, the kernel interface allows any of the following: write permission may imply read permission; read permission may imply execute permission; or, execute permission may imply read permission.
All architectures must support the following access combinations: all (read, write, and execute) access; write-protected (read and execute) access; no access.
For the VAX, RT/PC, and Sun3, all three of the reductions stated above apply. This is: VM_PROT_WRITE allos read, execute, and write access, VM_PROT_READ or VM_PROT_EXECUTE allows read and execute access, but not write access.
Returns:
ERIC_SUCCESS Memory Protected
ERIC_PROTECTION_FAILURE An attempt was made to increase the current or maximum protection beyond the existing maximum protection value.
ERIC_INVALID_ADDRESS Illegal or non-allocated address specified.
int kVMem::inherit( long target_task long address,
long size, int new_inheritance );
Arguments:
target_task Task whose virtual memory is to be affected address Starting address (will be rounded down to boundary) size Size in bytes of the region for which inheritance is to change (will be rounded up to give a page boundary). new_inheritance How this memory is to be inherited in child tasks.
Inheritance is specified by using one of these following three values: VM_INHERIT_SHARE Child tasks will share this memory with the task VM_INHERIT_COPY Child tasks will receive a copy of this region VM_INHERIT_NONE This region will be absent from child tasks.
Description:
Specifies how a region of a task's address space is to be passed onto child tasks at the time of task creation. Inheritance is an attribute of of virtual pages, thus the addresses and size of memory to be set will be rounded out to refer to whole pages.
Setting inherit() to VM_INHERIT SHARE and forking a child task is the only way two Mach tasks can share physical memory. Remember that all the threads of a given task share all the same memory. Returns:
ERIC_SUCCESS Memory protected
ERIC_INVALID_ADDRESS Illegal address specified.
int kVMem::statistics( long target_task, kVStat *vm_stats );
Arguments:
target_task Task which is requesting statistics vm_stats The structure that will receive the statistics Description:
Returns the statistics about the kernel's use of virtual memory, since the kernel was booted. pagesize can aslo be found as a variable vm_page_size whish is set at task initialization and remains constant for the life of the task.
Returns:
ERIC_SUCCESS