Technical Reference: Kernel and Subsystems, Volume 1

rmmap_create64 Kernel Service

Purpose

Defines an Effective Address [EA] to Real Address [RA] translation region for either 64-bit or 32-bit Effective Addresses.

Syntax

#include <sys/ioacc.h>
#include <sys/adspace.h>
int rmmap_create64(eaddrp, iomp, flags )
unsigned long long *eaddrp;
struct io_map *iomp;
int flags;

Parameters

eaddrp	Desired process effective address of the mapping region. This address is interpreted as a 64-bit quantity if the current user address space is 64-bits, and is interpreted as a 32-bit (not remapped) quantity if the current user address space is 32-bits.
iomp	The bus memory to which the effective address described by the eaddr parameter should correspond. For real memory, the bus id should be set to REALMEM_BID and the bus address should be set to the real memory address. The size field must be at least PAGESIZE, no larger than SEGSIZE, and a multiple of PAGESIZE. The key should be set to IO_MEM_MAP. The flags field is not used.
flags	The flags select page and segment attributes of the translation. Not all page attribute flags are compatible. See below for the valid combination of page attribute flags. RMMAP_PAGE_W PowerPC "Write Through" page attribute. Valid with all other flags. If set, page operates write-through. If clear, operates write-back.
	RMMAP_PAGE_W PowerPC "Write Through" page attribute. Write-through mode is not supported, and if this flag is set, EINVAL will be reported.
	RMMAP_PAGE_I PowerPC "Cache Inhibited" page attribute. Valid with all other flags. If set, page operates cache inhibited. If clear, page is considered cacheable.
	RMMAP_PAGE_I PowerPC "Cache Inhibited" page attribute. This flag is valid for I/O mappings, but is not allowed for real memory mappings.
	RMMAP_PAGE_M PowerPC "Memory Coherency Required" page attribute. Valid with all other flags. If set, accesses to a location are serialized within the processor complex. Otherwise, there is no guaranteed ordering. The default operating mode for real memory pages has this bit set.
	RMMAP_PAGE_M PowerPC "Memory Coherency Required" page attribute. This flag is optional for I/O mappings, however, it is required for memory mappings. The default operating mode for real memory pages has this bit set.
	RMMAP_PAGE_G PowerPC "Guarded" page attribute. Valid with all other flags. When set, the processor will not make unnecessary (speculative) references to the page. This includes out of order read/write operations and branch fetching. When clear, normal PowerPC speculative execution rules apply. This bit does not exist on the PowerPC 601 RISC Microprocessor (running AIX 5.1 or earlier) and is ignored.
	RMMAP_PAGE_G PowerPC "Guarded" page attribute. This flag is optional for I/O mappings, and must be 0 for real memory mappings. Note that although optional for I/O, it is strongly recommended that this be set for I/O mappings. When set, the processor will not make unnecessary (speculative) references to the page. This includes out of order read/write operations and branch fetching. When clear, normal PowerPC speculative execution rules apply. This bit does not exist on the PowerPC 601 RISC Microprocessor (running AIX 5.1 or earlier) and is ignored.
	RMMAP_RDONLY When set, the page protection bits used in the HTAB will not allow write operations regardless of the setting of the key bit in the associated segment register. Exactly one of: RMMAP_RDONLY, and RMMAP_RDWR must be specified.
	RMMAP_RDWR When set, the page protection bits used in the HTAB will allow read and write operations regardless of the setting of the key bit in the associated segment register. Exactly one of: RMMAP_RDONLY, and RMMAP_RDWR must be specified.
	RMMAP_PRELOAD When set, the protection attributes of this region will be entered immediately into the hardware page table. This is very slow initially, but prevents each referenced page in the region from faulting in separately. This is only advisory. The rmmap_create64 reserves the right to preload regions which do not specify this flag and to ignore the flag on regions which do. This flag is not maintained as an attribute of the map region, it is used only during the current call.
	RMMAP_INHERIT When set, this specifies that the translation region created by this rmmap_create64 invocation should be inherited on a fork operation, to the child process. This inheritance is achieved with copy-semantics. That is to say that the child has its own private mapping to the same I/O or real memory address range as the parent.

Description

The translation regions created with the rmmap_create64 kernel service are maintained in I/O mapping segments. Any single such segment may translate up to 256 Megabytes of memory mapped I/O in a single region. The only granularity for which the rmmap_remove64 service may be invoked is a single mapping created by a single call to rmmap_create64.

There are constraints on the size of the mapping and the flags parameter, described later, which will cause the call to fail regardless of whether adequate effective address space exists.

If the rmmap_create64 kernel service is called with the effective address of zero (0), the function will attempt to find free space in the process address space. If successful, an I/O mapping segment is created and the effective address (which is passed by reference) is changed to the effective address that is mapped to the first page of the iomp memory.

If rmmap_create64 kernel service is called with a non-zero effective address, it is taken as the desired effective address that should translate to the passed iomp memory. This function verifies that the requested range is free. If not, it fails and returns EINVAL. If the mapping at the effective address is not contained in a single segment, the function fails and returns ENOSPC. Otherwise, the region is allocated and the effective address is not modified. The effective address is mapped to the first page of iomp memory. References outside of the mapped regions but within the same segment are invalid.

The effective address (if provided) and the bus address (or real address for real memory mappings) must be a multiple of PAGESIZE or EINVAL is returned.

The real address range described by the iomp parameter must be unique within this I/O mapping segment.

If the rmmap_create64 kernel service is called with a length which is either not a multiple of PAGESIZE, is less than PAGESIZE, or is greater than SEGSIZE, EINVAL is returned. This return code takes precedence in cases where otherwise the segment would overflow and ENOSPC is returned.

I/O mapping segments are not inherited by child processes after a fork subroutine except when RMMAP_INHERIT is specified. These segments are deleted by exec,exit, or rmmap_remove64 of the last range in a segment.

Only certain combinations of page flags are permitted, depending on the type of memory being mapped. For real memory mappings, RMMAP_PAGE_M is required while RMMAP_PAGE_W, RMMAP_PAGE_I, and RMMAP_PAGE_G are not allowed. For I/O mappings, it is valid to specify only RMMAP_PAGE_M, with no other page attribute flags. It is also valid to specify RMMAP_PAGE_I and optionally, either or both of the RMMAP_PAGE_M, and RMMAP_PAGE_G. RMMAP_PAGE_W is never allowed.

Execution Environment

The rmmap_create64 kernel service can be called from the process environment only.

Return Values

On successful completion, the rmmap_create64 kernel service returns zero and modifies the effective address to the value at which the newly created mapping region was attached to the process address space. Otherwise, it returns one of:

EINVAL	Some type of parameter error occured. These include, but are not limited to, size errors and mutually exclusive flag selections.
ENOMEM	The operating system could not allocate the necessary data structures to represent the mapping.
ENOSPC	Effective address space exhausted in the region indicated by eaddr.
EPERM	This hardware platform does not implement this service.

Implementation Specifics

This service only functions on PowerPC microprocessors.

Related Information

The rmmap_remove64 kernel service.

Memory Kernel Services and Understanding Virtual Memory Manager Interfaces in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.