ltpin Kernel Service

Purpose

Pins the address range in the system (kernel) space and frees the page space for the associated pages.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/pin.h>
int ltpin (addr, length) 
caddr_t  addr;  
int      length;  
   

Parameters

Item Description
addr Specifies the address of the first byte to pin.
length Specifies the number of bytes to pin.

Description

The ltpin (long term pin) kernel service pins the real memory pages touched by the address range specified by the addr and length parameters in the system (kernel) address space. It pins the real-memory pages to ensure that page faults do not occur for memory references in this address range. The ltpin kernel service increments the long-term pin count for each real-memory page. While either the long-term or short-term pin count is nonzero, the page cannot be paged out of real memory.

The ltpin kernel service pins either the entire address range or none of it. Only a limited number of pages are pinned in the system. If there are not enough unpinned pages in the system, the ltpin kernel service returns an error code. The ltpin kernel service is not a published interface.

Note: The operating system pins only whole pages at a time. Therfore, if the requested range is not aligned on a page boundary, then memory outside this range is also pinned.

The ltpin kernel service can only be called for addresses within the system (kernel) address space.

Return Values

Item Description
0 Indicates successful completion.
EINVAL Indicates that the length parameter has a negative value. Otherwise, the area of memory beginning at the address of the first byte to pin (the addr parameter) and extending for the number of bytes specified by the length parameter is not defined.
EIO Indicates that a permanent I/O error occurred while referencing data.
ENOMEM Indicates that the pin kernel service was unable to pin due to insufficient real memory or exceeding the system-wide pin count.
ENOSPC Indicates insufficient file system or paging space.