---
name: "pmap_enter"
section: "9"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/pmap_enter"
---

# pmap\_enter(9)

insert a virtual page into a physical map

## NAME

**pmap\_enter** – insert a virtual page into a physical map

## SYNOPSIS

**#include \<sys/param.h\>**

**#include \<vm/vm.h\>**

**#include \<vm/pmap.h\>**

*int*\

**pmap\_enter**(*pmap\_t pmap*, *vm\_offset\_t va*, *vm\_page\_t m*, *vm\_prot\_t prot*, *u\_int flags*, *int8\_t psind*);

## DESCRIPTION

The **pmap\_enter**() function creates a mapping in the physical map *pmap* from the virtual address *va* to the physical page *m* with the protection *prot*. Any previous mapping at the virtual address *va* is destroyed.

The *flags* argument may have the following values:

- VM\_PROT\_READ

  A read access to the given virtual address triggered the call.

- VM\_PROT\_WRITE

  A write access to the given virtual address triggered the call.

- VM\_PROT\_EXECUTE

  An execute access to the given virtual address triggered the call.

- PMAP\_ENTER\_WIRED

  The mapping should be marked as wired.

- PMAP\_ENTER\_NOSLEEP

  This function may not sleep during creation of the mapping. If the mapping cannot be created without sleeping, an appropriate Mach VM error is returned.

If the PMAP\_ENTER\_NOSLEEP flag is not specified, this function must create the requested mapping before returning. It may not fail. In order to create the requested mapping, this function may destroy any non-wired mapping in any pmap.

The *psind* parameter specifies the page size that should be used by the mapping. The supported page sizes are described by the global array pagesizes\[\]. The desired page size is specified by passing the index of the array element that equals the desired page size.

When the **pmap\_enter**() function destroys or updates a managed mapping, including an existing mapping at virtual address *va*, it updates the *vm\_page* structure corresponding to the previously mapped physical page. If the physical page was accessed through the managed mapping, then the *vm\_page* structure's PGA\_REFERENCED aflag is set. If the physical page was modified through the managed mapping, then the **vm\_page\_dirty**() function is called on the *vm\_page* structure.

The PGA\_WRITEABLE aflag must be set for the page *m* if the new mapping is managed and writeable. It is advised to clear PGA\_WRITEABLE for destroyed mappings if the implementation can ensure that no other writeable managed mappings for the previously mapped pages exist.

If the request modifies an existing mapping to use a different physical page, an implementation of **pmap\_enter** must invalidate the previous mapping before installing the new one. This ensures that all threads sharing the pmap keep a consistent view of the mapping, which is necessary for the correct handling of CoW (copy on write) faults.

If the page *m* is managed, the page must be busied by the caller or the owning object must be locked. In the later case, the PMAP\_ENTER\_NOSLEEP must be specified by the caller.

The **pmap\_enter**() function must handle the multiprocessor TLB consistency for the given address.

## NOTES

On arm and i386 architectures the existing implementation of the **pmap\_enter** function is incomplete, only value 0 for *psind* is supported. Other supported architectures, except amd64, have pagesizes\[\] array of size 1.

## RETURN VALUES

If successful, the **pmap\_enter**() function returns KERN\_SUCCESS. If the PMAP\_ENTER\_NOSLEEP flag was specified and the resources required for the mapping cannot be acquired without sleeping, KERN\_RESOURCE\_SHORTAGE is returned.

## SEE ALSO

[pmap(9)](/pmap/9.md)

## AUTHORS

This manual page was first written by Bruce M Simpson ⟨*bms@spc.org*⟩ and then rewritten by Alan Cox ⟨*alc@FreeBSD.org*⟩ and Konstantin Belousov ⟨*kib@FreeBSD.org*⟩.