xlate_create Kernel Service

Purpose

Creates pretranslation data structures.

Syntax

int xlate_create (dp, baddr, count, flags)
struct xmem*dp;
caddr_t baddr;
int count;
uint flags;

Description

The xlate_create kernel service creates pretranslation data structures capable of pretranslating all pages of the virtual buffer indicated by the baddr parameter for length of count into a list of physical page numbers, appended to the cross memory descriptor pointed to by dp.

If the XLATE_ALLOC flag is set, only the data structures are created and no pretranslation is done. If the flag is not set, in addition to the data structures being created, each page of the buffer is translated and the access permissions verified, requiring read-write access to each page. The XLATE_ALLOC flag is useful when the buffer will be pinned and utilized later, through the xlate_pin and xlate_unpin kernel services.

The XLATE_SPARSE flag can be used to indicate that only selected portions of a pretranslated region may be valid (pinned and pretranslated) at any given time. The XLATE_SPARSE flag can be used in conjunction with the XLATE_ALLOC flag to preallocate the pretranslation data structures for an address region that will be dynamically managed.

The xlate_create kernel service is primarily for use when memory buffers will be reused for I/O. The use of this service to create a pretranslation for the memory buffer avoids page translation and access checking overhead for all future DMAs involving the memory buffer until the xlate_remove kernel service is called.

Parameters

Item	Description
dp	Points to the cross memory descriptor.
baddr	Points to the virtual buffer.
count	Specifies the length of the virtual buffer.
flags	Specifies the operation. Valid values are as follows: XLATE_PERSISTENT Indicates that the pretranslation data structures should be persistent across calls to pretranslation services. XLATE_ALLOC Indicates that the pretranslation data structures should be allocated only, and no translation should be performed. XLATE_SPARSE Indicates that the pretranslation information will be sparse, allowing for the coexistence of valid (active) pretranslation regions and invalid (inactive) pretranslation regions.

Return Values

Item	Description
ENOMEM	Unable to allocate memory
XMEM_FAIL	No physical translation, or No Access to a Page
XMEM_SUCC	Successful pretranslation created

Execution Environment

The xlate_create kernel service can only be called from the process environment. The entire buffer must be pinned (unless the XLATE_ALLOC flag is set), and the cross memory descriptor valid.