From owner-svn-src-all@FreeBSD.ORG Tue Jan 27 09:48:03 2015 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id A49C3239; Tue, 27 Jan 2015 09:48:03 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 858D9C8B; Tue, 27 Jan 2015 09:48:03 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id t0R9m3Q9038162; Tue, 27 Jan 2015 09:48:03 GMT (envelope-from kib@FreeBSD.org) Received: (from kib@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id t0R9m39S038161; Tue, 27 Jan 2015 09:48:03 GMT (envelope-from kib@FreeBSD.org) Message-Id: <201501270948.t0R9m39S038161@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: kib set sender to kib@FreeBSD.org using -f From: Konstantin Belousov Date: Tue, 27 Jan 2015 09:48:03 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r277793 - head/share/man/man9 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 27 Jan 2015 09:48:03 -0000 Author: kib Date: Tue Jan 27 09:48:02 2015 New Revision: 277793 URL: https://svnweb.freebsd.org/changeset/base/277793 Log: Rewrite pmap_enter(9) man page. In collaboration with: alc Differential Revision: https://reviews.freebsd.org/D1531 Sponsored by: The FreeBSD Foundation and EMC / Isilon Storage Division MFC after: 1 week Modified: head/share/man/man9/pmap_enter.9 Modified: head/share/man/man9/pmap_enter.9 ============================================================================== --- head/share/man/man9/pmap_enter.9 Tue Jan 27 07:20:00 2015 (r277792) +++ head/share/man/man9/pmap_enter.9 Tue Jan 27 09:48:02 2015 (r277793) @@ -1,5 +1,6 @@ .\" .\" Copyright (c) 2003 Bruce M Simpson +.\" Copyright (c) 2014 The FreeBSD Foundation .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -25,7 +26,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 21, 2003 +.Dd January 27, 2015 .Dt PMAP_ENTER 9 .Os .Sh NAME @@ -35,34 +36,129 @@ .In sys/param.h .In vm/vm.h .In vm/pmap.h -.Ft void +.Ft int .Fo pmap_enter -.Fa "pmap_t pmap" "vm_offset_t va" "vm_page_t p" "vm_prot_t prot" -.Fa "boolean_t wired" +.Fa "pmap_t pmap" "vm_offset_t va" "vm_page_t m" "vm_prot_t prot" +.Fa "u_int flags" "int8_t psind" .Fc .Sh DESCRIPTION The .Fn pmap_enter -function inserts the given physical page -.Fa p , -into the physical map -.Fa pmap , -at the virtual address -.Fa va , +function creates a mapping in the physical map +.Fa pmap +from the virtual address +.Fa va +to the physical page +.Fa m with the protection .Fa prot . -If -.Fa wired -is -.Dv TRUE , -then increment the wired count for the page as soon as the mapping -is inserted into -.Fa pmap . -.Sh IMPLEMENTATION NOTES -This routine MAY NOT lazy-evaluate the entry; it is required by -specification to make the requested entry at the time it is called. +Any previous mapping at the virtual address +.Fa va +is destroyed. +.Pp +The +.Fa flags +argument may have the following values: +.Bl -tag -width ".Dv PMAP_ENTER_NOSLEEP" +.It Dv VM_PROT_READ +A read access to the given virtual address triggered the call. +.It Dv VM_PROT_WRITE +A write access to the given virtual address triggered the call. +.It Dv VM_PROT_EXECUTE +An execute access to the given virtual address triggered the call. +.It Dv PMAP_ENTER_WIRED +The mapping should be marked as wired. +.It Dv 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. +.El +If the +.Dv 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. +.Pp +The +.Fa psind +parameter specifies the page size that should be used by the mapping. +The supported page sizes are described by the global array +.Dv pagesizes[] . +The desired page size is specified by passing the index of the array +element that equals the desired page size. +.Pp +When the +.Fn pmap_enter +function destroys or updates a managed mapping, including an existing +mapping at virtual address +.Fa va , +it updates the +.Ft vm_page +structure corresponding to the previously mapped physical page. +If the physical page was accessed through the managed mapping, +then the +.Ft vm_page +structure's +.Dv PGA_REFERENCED +aflag is set. +If the physical page was modified through the managed mapping, then the +.Fn vm_page_dirty +function is called on the +.Ft vm_page +structure. +.Pp +The +.Dv PGA_WRITEABLE +aflag must be set for the page +.Fa m +if the new mapping is managed and writeable. +It is advised to clear +.Dv PGA_WRITEABLE +for destroyed mappings if the implementation can ensure +that no other writeable managed mappings for the previously +mapped pages exist. +.Pp +If the page +.Fa m +is managed, the page must be busied by the caller +or the owning object must be locked. +In the later case, the +.Dv PMAP_ENTER_NOSLEEP +must be specified by the caller. +.Pp +The +.Fn pmap_enter +function must handle the multiprocessor TLB consistency for the +given address. +.Sh NOTES +On amd64, arm and i386 architectures the existing implementation +of the +.Nm +function is incomplete, only value 0 for +.Fa psind +is supported. +Other supported architectures have +.Dv pagesizes[] +array of size 1. +.Sh RETURN VALUES +If successful, the +.Fn pmap_enter +function returns +.Er KERN_SUCCESS . +If the +.Dv PMAP_ENTER_NOSLEEP +flag was specified and the resources required for the mapping cannot +be acquired without sleeping, +.Dv KERN_RESOURCE_SHORTAGE +is returned. .Sh SEE ALSO .Xr pmap 9 .Sh AUTHORS -This manual page was written by -.An Bruce M Simpson Aq Mt bms@spc.org . +This manual page was first written by +.An Bruce M Simpson Aq Mt bms@spc.org +and then rewritten by +.An Alan Cox Aq Mt alc@FreeBSD.org +and +.An Konstantin Belousov Aq Mt kib@FreeBSD.org .