ControlMem
Controls memory permissions and ownership.
Synopsis
Err ControlMem( void *p, int32 size, int32 cmd, Item task )
Description
When a task allocates memory, it becomes the owner of that memory. Other tasks cannot write to the memory unless they are given permission by its owner. A task can give another task permission to write to one or more of its memory pages, revoke write permission that was previously granted, or transfer ownership of memory to another task or the system by calling ControlMem().
Each page of memory has a control status that specifies which task owns the memory and which tasks can write to it. Calls to ControlMem() change the control status for entire pages. If the p and size arguments (which specify the memory to change) specify any part of a page, the changes apply to the entire page.
A task can grant write permission for a page that it owns (or for some number of contiguous pages) to any number of tasks. To accomplish this, the task must make a separate call to ControlMem() for each task that is to be granted write permission.
A task that calls ControlMem() must own the memory whose control status it is changing, with one exception: A task that has write access to memory it doesn't own can relinquish its write access (by using MEMC_NOWRITE as the value of the cmd argument). If a task transfers ownership of memory it still retains write access.
Arguments
- p
- A pointer to the memory whose control status to change.
- size
- The amount of memory for which to change the control status, in bytes. If the size and p arguments specify any part of a page, the control status is changed for the entire page.
- cmd
- A constant that specifies the change to be made to the control status; possible values are listed below.
- task
- The item-number task for which to change the control status or zero for global changes (see "Notes").
The possible values of "cmd" are:
- MEMC_OKWRITE
- Grants permission to write to this memory to the task specified by the task argument.
- MEMC_NOWRITE
- Revokes permission to write to this memory from the task specified by the task argument. If task is 0 revokes write permission for all tasks.
- MEMC_GIVE
- If the calling task is the owner of the memory, this transfers ownership of the memory to the task specified by the task argument. If the specified task is 0, it gives the memory back to the system free memory pool.
Return Value
The procedure returns 0 if the change was successful or an error code (a negative value) if an error occurs. Possible error codes include:
- BADITEM
- The task argument does not specify a current task.
- ER_Kr_BadMemCmd
- The cmd argument is not one of the valid values.
- ER_BadPtr
- The p argument is not a valid pointer to memory.
Implementation
SWI implemented in kernel folio V20.
Associated Files
- mem.h
- ANSI C Prototype
Notes
A task can use ControlMem() to prevent itself from writing to memory it owns.
A task must own the memory for its I/O buffers.
A task can use ControlMem() to return ownership of memory pages to the system, thereby returning them to the system-wide free memory pool. You can do this by using 0 as the value of the task argument.
A task can use ControlMem() to unshare or write protect memory from all other tasks. Specify 0 for the task for this to happen.
We would like to support making a piece of memory writable by all other tasks by using task==0 and MEMC_OKWRITE, but this is not implemented yet.
See Also
ScavengeMem(), AllocMemBlocks()