memory_object_lock_request

Function - Restrict access to memory object data.

SYNOPSIS

kern_return_t   memory_object_lock_request
                (memory_object_control_t         memory_control,
                 vm_offset_t                             offset,
                 vm_size_t                                 size,
                 memory_object_return_t           should_return,
                 boolean_t                         should_flush,
                 vm_prot_t                           lock_value,
                 mach_port_t                         reply_port);

PARAMETERS

memory_control

[in memory-cache-control send right] The memory cache control port to be used by the memory manager for cache management requests. This port is provided by the kernel in a memory_object_init call.

offset

[in scalar] The offset within the memory object, in bytes.

size

[in scalar] The number of bytes of data (starting at offset) to be affected. The number must convert to an integral number of memory object pages.

should_return

[in scalar] Clean indicator. Values are:

MEMORY_OBJECT_RETURN_NONE

Don't return any pages. If should_flush is TRUE, pages will be discarded.

MEMORY_OBJECT_RETURN_DIRTY

Return only dirty (modified) pages. If should_flush is TRUE, precious pages will be discarded; otherwise, the kernel maintains responsibility for precious pages.

MEMORY_OBJECT_RETURN_ALL

Both dirty and precious pages are returned. If should_flush is FALSE, the kernel maintains responsibility for the precious pages.

MEMORY_OBJECT_RETURN_ANYTHING

Any resident pages are returned. If should_flush is TRUE, precious pages will be discarded; otherwise, the kernel maintains responsibility for precious pages.

should_flush

[in scalar] Flush indicator. If true, the kernel discards all pages within the range.

lock_value

[in scalar] One or more forms of access not permitted for the specified data. Valid values are:

VM_PROT_NO_CHANGE

Do not change the protection of any pages.

VM_PROT_NONE

Prohibits no access (that is, all forms of access are permitted).

VM_PROT_READ

Prohibits read access.

VM_PROT_WRITE

Prohibits write access.

VM_PROT_EXECUTE

Prohibits execute access.

VM_PROT_ALL

Prohibits all forms of access.

reply_port

[in reply receive (to be converted to send) right] The response port to be used by the kernel on a call to memory_object_lock_completed, or MACH_PORT_NULL if no response is required.

DESCRIPTION

The memory_object_lock_request function allows the memory manager to make the following requests of the kernel:

• Clean the pages within the specified range by writing back all changed (that is, dirty) and precious pages. The kernel uses the memory_object_data_return call to write back the data. The should_return parameter must be set to non-zero.

• Flush all cached data within the specified range. The kernel invalidates the range of data and revokes all uses of that data. The should_flush parameter must be set to true.

• Alter access restrictions specified in the memory_object_data_supply call or a previous memory_object_lock_request call. The lock_value parameter must specify the new access restrictions. Note that this parameter can be used to unlock previously locked data.

Once the kernel performs all of the actions requested by this call, it issues a memory_object_lock_completed call using the reply_to port.

NOTES

The memory_object_lock_request call affects only data that is cached at the time of the call. Access restrictions cannot be applied to pages for which data has not been provided.

When a running thread requires an access that is currently prohibited, the kernel issues a memory_object_data_unlock call specifying the access required. The memory manager can then use memory_object_lock_request to relax its access restrictions on the data.

To indicate that an unlock request is invalid (that is, requires permission that can never be granted), the memory manager must first flush the page. When the kernel requests the data again with the higher permission, the memory manager can indicate the error by responding with a call to memory_object_data_error.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: memory_object_data_supply, memory_object_data_unlock, memory_object_lock_completed.