ChorusOS man pages section 2SEG: Virtual Memory Segment Services

MpGetAccess(2SEG)

NAME

MpGetAccess- get access to data through a local cache

SYNOPSIS

#include <mem/chMem.h>

#include <mem/chMapper.h>

MpGetAccess

request annex (KnMpGetAccess structure):

   int            service ;

   KnKey          segkey ;

   KnCap          lccap ;

   VmOffset       accessOffset ;

   VmSize         accessSize ;

   VmFlags        requiredAccess ;

   VmSize         requiredAccessOffset ;

   VmSize         requiredAccessSize ;

response annex (KnMpGetAccessReply structure):

   int           diag ;

   VmFlags        grantedAccess ;

   unsigned long  ordinalNumber ;

   VmOffset       returnAccessOffset ;

   VmSize         returnAccessSize ;

   VmSize         inClusterSize ;

   VmSize          outClusterSize ;

FEATURES

MEM_VM

DESCRIPTION

This system call is strictly reserved for internal use only. It MUST NOT be used by any application.

In order to demand access rights for a range of a segment through a local cache, the kernel memory management system performs an MpGetAccess message transaction. In other words it sends, using ipcCall(2K), an MpGetAccess request message to the mapper managing the segment. The mapper is identified by the ui field of the segment capability.

The request message consists of an annex (no body) whose head matches the KnMpGetAccess structure defined above. The service field of this structure must be set to KN_MPGETACCESS.

The kernel demands access rights to accessSize bytes of data using the accessOffset, the starting offset in the segment is specified by segkey on the invoked mapper, for the local cache specified by lccap. Both accessOffset and accessSize are always page-aligned.

The kernel also specifies in the message that access rights for requiredAccessSize bytes of data with the requiredAccessOffset starting offset is mandatory. The kernel guarantees that [accessOffset, accessOffset + accessSize] includes [requiredAccessOffset, requiredAccessOffset + requiredAccessSize].

The kernel can send a get access request when it performs one of the following operations:

lc(sg)Read or a lc(sg)Write kernel calls. In this case [requiredAccessOffset, requiredAccessOffset + requiredAccessSize) specifies the exact (in bytes) boundaries of the operation.

The kernel can perform a lc(sg)Read/Write call without a MpGetAccess transaction if it already has access to the required range.
any other operation which acts on a range of the segment through a virtual address space as a page fault or vmLock, vmCopy, rgnSetPaging, rgnInit, for example.

In this, and only this, case the K_PAGEFAULT flag is set in the requiredAccess field.

The kernel can ask for access rights to the operation range (the operation range of a page fault is the whole faulty page) using a number of consecutive MpGetAccess transactions. The requiredAccessOffset of each transaction is page-aligned and requiredSize % vmPageSize() is equal to 1 (the last byte of the required range is the first byte of a page).

The kernel can perform the operation without an MpGetAccess request for a particular page overlapping the operation range if it has already the requested access to the whole page.

If the K_WRITABLE flag in the requiredAccess field is set, write access to the data is requested, otherwise read-only access is requested.

The mapper must reply with a message, consisting of an annex (no body) whose head matches the KnMpGetAccessReply structure.

The diag field is the transaction return code. The diag field must be either 0 (K_OK), or a negative number. When a negative error code is returned, there are two possibilities:

returnAccessSize is equal to zero. In this case the kernel immediately gives up the processing of the original operation and returns from the original kernel operation with a diag error code.
returnAccessSize is positive. In this case the kernel reduces the original operation range until returnAccessOffset + returnAccessSize, completes the operation and returns from the original kernel operation with a diag error code. Also, if it's allowed by the interface of the operation (lcRead or lcWrite calls), the number of bytes effectively processed will be returned.

If the original kernel operation is a page fault an error provokes exception processing at the end of the page fault handler execution (see svExcHandler(2K)).

The K_MPIVERS bitmask defines a bit-field of the grantedAccess field which specifies the version of the MpGetAccess protocol supported by the mapper. The protocol version has to be equal to K_MPIVER1.

The mapper grants access to returnAccessSize bytes of data with the starting offset in the segment equal to returnAccessOffset. The mapper has to guarantee that [returnAccessOffset, returnAccessOffset + returnAccessSize] is included in [accessOffset, accessOffset + accessSize] but includes [requiredAccessOffset, requiredAccessOffset + requiredAccessSize]. Note that if diag is negative (see above) the last condition can be not respected.

The kernel requires returnAccessOffset and returnAccessSize to be "fragment"-aligned. The size of the fagment is implementation--dependent but usually equal to the virtual page size devided by 8 (number of bits in one byte).

The alignment requirements above mean that the mapper can return access rights to a partial page. The kernel implements the following policy with respect to pages with partial access rights:

The kernel maps the page to the target virtual address if required by the target operation. The kernel page fault handler can map a page with partial access rights to the faulty virtual address after the corresponding MpGetAccess return. Note that in the case of another page fault on a page with partial access rights, the kernel will call MpGetAccess again.
The kernel doesn't guarantee that the page compliment (the ranges of the page without access rights) will be included in a subsequent mpPushOut request even if it was modified using mmu. Neither does the kernel guarantee that the page complement will not be included in any subsequent mpPushOut request.

If the mapper grants write access, it sets the K_WRITABLE flag in the grantedAccess field, otherwise read only access is granted. The mapper could grant write access in response to a read-only access request, but it must grant write access in response to a write access request.

If the K_ORDERED flag is set in the grantedAccess field, the ordinalNumber field specifies the reply message order number. It allows the kernel to detect the situation when two mesages sent by a mapper in one order are received by the kernel in another. For instance, suppose the mapper grants access rights in an MpGetAccess reply first, and then, processing another request, calls an lcFlush to recall the access rights. In this case, the order numbers indicate to the kernel that the access returned by the MpGetAccess reply was already recalled by the mapper, and performs a MpGetAccess request again.

If the K_STALE flags is set in the grantedAccess field, any data already cached from the returned range are considered as stale and will be destroyed by the kernel upon receipt of the reply message.

The mapper may also set the K_RELEASE flag (in the grantedAccess field). In this case the memory management has to perform an MpRelease request prior to destroying the local cache.

If the K_GETATTR flag is set in the requiredAccess field of the request message, the current MpGetAccess request is combined with a "get segment attributes" request. When the mapper replies to a combined request it may return the segment clustering attributes. If the mapper sets the K_CLUSTER flag (in the grantedAccess field) the inClusterSize and outClusterSize fields define the segment clustering attributes. The inClusterSize defines the optimal (from the mapper point of view) data size for any future MpPullIn operation performed on the segment . The outClusterSize defines the optimal data size for any future MpPushOut operation. Both inClusterSize and outClusterSize have to be a power of two and page-aligned.

If the kernel detects that the mapper is not adhering to the protocol desscribed above, the K_EMAPPER error is returned to the orginal kernel operation. If the original kernel operation is a page fault an error provokes exception processing at the end of the page fault handler execution (see svExcHandler(2K)).

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving