Page MenuHomeFreeBSD
Differential D3312 Diff 7718 share/man/man9/pmap_quick_enter_page.9

Changeset View

Standalone View

View Options

share/man/man9/pmap_quick_enter_page.9

  • This file was added.
PropertyOld ValueNew Value
svn:eol-stylenullnative
\ No newline at end of property
svn:keywordsnullFreeBSD=%H
\ No newline at end of property
svn:mime-typenulltext/plain
\ No newline at end of property
.\"
.\" Copyright (c) 2015 Jason A. Harmening <jah@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 5, 2015
.Dt PMAP_QUICK_ENTER_PAGE 9
.Os
.Sh NAME
.Nm pmap_quick_enter_page ,
.Nm pmap_quick_remove_page
.Nd manage fast, single-page kernel address space mappings
.Sh SYNOPSIS
kibUnsubmitted
Done
Inline Actions

address space

kib: address space
.In sys/param.h
.In vm/vm.h
.In vm/pmap.h
.Ft vm_offset_t
.Fn pmap_quick_enter_page "vm_page_t m"
.Ft void
.Fn pmap_quick_remove_page "vm_offset_t kva"
.Sh DESCRIPTION
The
.Fn pmap_quick_enter_page
function accepts a single page
.Fa m ,
kibUnsubmitted
Done
Inline Actions

I do not think that wired is any sort of requirement for the state of the page m. Caller must ensure that the page is not reused for something undesirable, but thats all. E.g., the page could be unmanaged, or it could be managed but held instead of wired, or it could be busy. Any of the listed condition are enough to keep the m content stable.

kib: I do not think that wired is any sort of requirement for the state of the page m. Caller must…
and enters this page into a preallocated address in kernel virtual
address (KVA) space.
This function is intended for temporary mappings that will only
be used for a very short period, for example a copy operation on
the page contents.
.Pp
The
.Fn pmap_quick_remove_page
function removes a mapping previously created by
.Fn pmap_quick_enter_page at
kibUnsubmitted
Done
Inline Actions

s/.$/, making the KVA frame used by pmap_quick_enter_page() available for reuse./

Or, some other way to say that the calling thread must not recurse into the dynamic region marked by pmap_quick_enter/remove.

kib: s/.$/, making the KVA frame used by pmap_quick_enter_page() available for reuse./ Or, some…
.Fa kva ,
wblockUnsubmitted
Not Done
Inline Actions

The "at" should be on a separate line:

.Fn pmap_quick_enter_page
at
wblock: The "at" should be on a separate line: ``` .Fn pmap_quick_enter_page at ```
making the KVA frame used by
.Fn pmap_quick_enter_page
available for reuse.
.Pp
On many architectures,
kibUnsubmitted
Done
Inline Actions

This sentence does not describe implementation, it should be moved to the main body of the function description. In particular, main text must say that the region cannot be nested, that the locking cannot be used in the region, and remove must be called as soon as possible.

Also, the context where the function can be called should be mentioned (thread but not interrupt handler, no spinlock may be owned when called).

kib: This sentence does not describe implementation, it should be moved to the main body of the…
.Fn pmap_quick_enter_page
uses a per-CPU pageframe.
In those cases, it must disable preemption on the local CPU.
The corresponding call to
.Fn pmap_quick_remove_page
then re-enables preemption.
It is therefore not safe for machine-independent code to sleep
or perform locking operations while holding these mappings.
Current implementations only guarantee the availability of a single
page for the calling thread, so calls to
kibUnsubmitted
Done
Inline Actions

See above, this should be moved from notes.

kib: See above, this should be moved from notes.
.Fn pmap_quick_enter_page
must not be nested.
.Pp
.Fn pmap_quick_enter_page
and
kibUnsubmitted
Done
Inline Actions

'Cannot fail' claim must be also moved.

kib: 'Cannot fail' claim must be also moved.
.Fn pmap_quick_remove_page
do not sleep and cannot fail.
kibUnsubmitted
Done
Inline Actions

....

kib: ....
It is safe to use them under all types of locks except spin mutexes.
wblockUnsubmitted
Not Done
Inline Actions

"cannot fail" implies that they always work, but the next two sentences have some exceptions.

wblock: "cannot fail" implies that they always work, but the next two sentences have some exceptions.
It is safe to use them in all thread contexts except primary interrupt context.
.Pp
The page
kibUnsubmitted
Done
Inline Actions

No.

kib: No.
.Em must
not be swapped or otherwise reused while the mapping is valid.
It must be either wired or held, or it must belong to an unmanaged
kibUnsubmitted
Not Done
Inline Actions

Note that even if the page is swapped, nothing wrong would happen with the mapping. Both the page and the *m are still there. It is up to the caller to decide is it worrying.

kib: Note that even if the page is swapped, nothing wrong would happen with the mapping. Both the…
wblockUnsubmitted
Not Done
Inline Actions

"is valid" is ambiguous for the reader, who might not know what that means. Maybe "in place" or "active" or something like that?

wblock: "is valid" is ambiguous for the reader, who might not know what that means. Maybe "in place"…
region such as I/O device memory.
.Pp
bruefferUnsubmitted
Not Done
Inline Actions

This .Pp is superfluous.

brueffer: This .Pp is superfluous.
.Sh RETURN VALUES
The
.Fn pmap_quick_enter_page
function returns the kernel virtual address
kibUnsubmitted
Done
Inline Actions

I propose not to say this in the man page.

kib: I propose not to say this in the man page.
that is mapped to the page
.Fa m .
.Pp
bruefferUnsubmitted
Not Done
Inline Actions

This is superfluous as well.

Please run mandoc -Tlint on the manpage, it catches these kind of things :-)

brueffer: This is superfluous as well. Please run mandoc -Tlint on the manpage, it catches these kind of…
.Sh SEE ALSO
.Xr pmap 9
.Sh AUTHORS
This manual page was written by
.An Jason A Harmening Aq Mt jah@FreeBSD.org .