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 <b...@spc.org> +.\" 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 b...@spc.org . +This manual page was first written by +.An Bruce M Simpson Aq Mt b...@spc.org +and then rewritten by +.An Alan Cox Aq Mt a...@freebsd.org +and +.An Konstantin Belousov Aq Mt k...@freebsd.org . _______________________________________________ svn-src-head@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-head To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"
