Oberon || Library || Module Index || Search Engine || Definition || Module


Ulm's Oberon Library:
SysMemory


NAME

SysMemory - interface to memory related system calls

SYNOPSIS

(* prot parameter of Map and Protect *)
CONST read = { 31 };         (* page can be read *)
CONST write = { 30 };        (* page can be written *)
CONST exec = { 29 };         (* page can be executed *)
CONST none = {};             (* page cannot be accessed *)
(* flags parameter of Map *)
CONST shared = { 31 };       (* share changes *)
CONST private = { 30 };      (* changes are private *)
CONST typeMask = { 28..31 }; (* allows comparisons against shared or private *)
CONST fixed = { 27 };        (* interpret address exactly *)
(* flags parameter of Sync *)
CONST async = { 31 };        (* return immediately *)
CONST invalidate = { 30 };   (* invalidate mappings *)
(* advise parameter of Advise *)
CONST normal = 0;            (* no further special treatment *)
CONST random = 1;            (* expect random page references *)
CONST sequential = 2;        (* expect sequential page references *)
CONST willneed = 3;          (* will need these pages *)
CONST dontneed = 4;          (* don't need these pages *)
(* mode of LockAll *)
CONST current = 1;           (* lock all current mappings *)
CONST future = 2;            (* lock all future mappings *)


PROCEDURE GetPageSize() : SysTypes.Size; PROCEDURE Map(address: SysTypes.Address; len: SysTypes.Size; prot: SET; flags: SET; fd: SysTypes.File; off: SysTypes.Offset; VAR mapaddress: SysTypes.Address; VAR errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE Unmap(address: SysTypes.Address; len: SysTypes.Size; errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE Protect(addr: SysTypes.Address; len: SysTypes.Size; prot: SET; VAR errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE Sync(addr: SysTypes.Address; len: SysTypes.Size; flags: SET; VAR errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE Advise(addr: SysTypes.Address; len: SysTypes.Size; advise: INTEGER; VAR errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE Lock(addr: SysTypes.Address; len: SysTypes.Size; VAR errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE Unlock(addr: SysTypes.Address; len: SysTypes.Size; VAR errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE Lockall(mode: INTEGER; VAR errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE UnlockAll(VAR errors: RelatedEvents.Object) : BOOLEAN; PROCEDURE InCore(addr: SysTypes.Address; len: SysTypes.Size; VAR vector: SysTypes.Address; VAR errors: RelatedEvents.Object) : BOOLEAN;

DESCRIPTION

SysMemory interfaces all system calls which are related to mmap(2). These system calls allow to map regular and some special files into arbritrary positions (on page boundaries) in the address space of the current process. They allow to replace the traditional brk(2) system call.

GetPageSize returns the page size of the system. All addresses and sizes given to one of the other procedures should be multiples of the page size. The page size may differ on different kernel architectures: while it is safe to regard a page size constant during the lifetime of a process it is unsafe to assume a constant page size for multiple runs.

Map maps the range [off, off+len) of the file referenced by fd into the address space at [address, address+len). Unless fixed has been given in flags, the system is free to choose another address instead of address which is returned in mapaddress. prot specifies the protection mode of the affected memory region. read, write and exec may be given in any combination. Following flags may be given to flags:

shared
requests the mapped file to be changed on write operations.
private
causes a copy to created on the first write operation onto a mapped page which is referenced on further operations.
fixed
requests the given address to be interpreted exactly (see above).

Unmap removes the mappings for pages in the given memory range. Protect changes the protections of the mappings specified by the given range. Sync writes dirty pages of the given memory range to their permanent storage locations. Following options may be specified in flags:

async
requests Sync to return immediately. By default, Sync returns after all write operations are completed.
invalidate
causes all cached copies of the mapped range to be re-obtained upon the next reference.

Advise allows to tell the kernel the indicated access pattern of a given memory range. This allows the kernel to parameterize its paging algorithm to achieve better performance. Following access patterns are supported:

normal
return to default behaviour.
random
requests the kernel to expect random page references.
sequential
sequential page references are to be assumed.
willneed
tells that the given pages are needed and to be kept in memory, if possible.
dontneed
allows the kernel to swap out the pages immediately without performance penalties.

Lock requests the given memory range to be locked into physical memory. Because the possible impact on system resources, this system call is restricted to the super-user. Alternatively, Advise may be used. Unlock undoes the effect of lock for the given memory range. Lockall requests all pages (or optionally all pages which are added to the address pages or replaced by new mappings) to be locked up into physical memory. The operational mode is determined by mode:

current
lock all pages which are currently allocated.
future
lock all pages which are allocated in the future or replaced by new mappings.
Unlockall removes all locks.

InCore tells which pages of the given memory range are currently cached into physical memory. The status is returned as a byte-per-page array which is stored into area pointed to by vector. Bytes set to 1 indicate that the corresponding page is in physical memory.

DIAGNOSTICS

System call failures lead to events of SysErrors. The errors parameter is passed to SysErrors.Raise. All routines return FALSE in error case.

FILES

/dev/zero
a special file of zeroes which may be mapped into memory.

SEE ALSO

brk(2)
traditional memory allocation
getpagesize(2)
GetPageSize
madvise(3)
Advise
mctl(2)
Advise, Lock, Lockall, Sync, Unlock, UnlockAll
mincore(2)
InCore
mlock(3)
Lock, Unlock
mlockall(3)
Lockall, Unlockall
mmap(2)
Map
mprotect(2)
Protect
msync(2)
Sync
munmap(2)
Unmap
zero(4)
special file with zeroes for Map
SysErrors
error handling
SysIPC
shared memory operations of System V

Edited by: borchert, last change: 2003/07/10, revision: 1.2, converted to HTML: 2003/07/10

Oberon || Library || Module Index || Search Engine || Definition || Module