Correctly case FreeBSD in my entry in the tips file
ClosedPublic
Actions

Authored by allanjude on Sep 8 2015, 3:58 PM.

Details

Reviewers

eadler
wblock
bcr

Commits

rS287582: Correctly case FreeBSD in my entry in the tips file

Summary

Reported by: feld

Diff Detail

Repository

rS FreeBSD src repository - subversion

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

allanjude updated this revision to Diff 8590.Sep 8 2015, 3:58 PM

allanjude retitled this revision from to Correctly case FreeBSD in my entry in the tips file.

allanjude updated this object.

allanjude edited the test plan for this revision. (Show Details)

allanjude added reviewers: bcr, wblock, eadler.

Herald added a subscriber: imp. · View Herald TranscriptSep 8 2015, 3:58 PM

Works for me.

This revision is now accepted and ready to land.Sep 8 2015, 10:46 PM

Closed by commit rS287582: Correctly case FreeBSD in my entry in the tips file (authored by allanjude). · Explain WhySep 8 2015, 10:51 PM

This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

Path

Size

head/

games/

fortune/

datfiles/

freebsd-tips

2 lines

Diff 8603

View Options

head/games/fortune/datfiles/freebsd-tips

	.\"	.\"
	.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org>	.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org>
		.\" Copyright (c) 2014 The FreeBSD Foundation
	.\" All rights reserved.	.\" All rights reserved.
	.\"	.\"
	.\" Redistribution and use in source and binary forms, with or without	.\" Redistribution and use in source and binary forms, with or without
Context not available.
	.\"	.\"
	.\" $FreeBSD$	.\" $FreeBSD$
	.\"	.\"
	.Dd July 21, 2003	.Dd August 13, 2014
	.Dt PMAP_ENTER 9	.Dt PMAP_ENTER 9
	.Os	.Os
	.Sh NAME	.Sh NAME
Context not available.
	.In sys/param.h	.In sys/param.h
	.In vm/vm.h	.In vm/vm.h
	.In vm/pmap.h	.In vm/pmap.h
	.Ft void	.Ft int
	.Fo pmap_enter	.Fo pmap_enter
	.Fa "pmap_t pmap" "vm_offset_t va" "vm_page_t p" "vm_prot_t prot"	.Fa "pmap_t pmap" "vm_offset_t va" "vm_page_t m" "vm_prot_t prot"
	.Fa "boolean_t wired"	.Fa "u_int flags" "int8_t psind"
	.Fc	.Fc
	.Sh DESCRIPTION	.Sh DESCRIPTION
	The	The
	.Fn pmap_enter	.Fn pmap_enter
	function inserts the given physical page	function creates a mapping in the physical map
		alcUnsubmitted Not Done Inline Actions This is really a comment about the existing first sentence. I find "... inserts ... into the physical map ..." to be utterly meaningless. How does the first sentence not include the word "mapping". I suggest changing this sentence to "... function creates a mapping in the physical map ... from the virtual address ... to the physical page ... with the protection ..." Maybe add the following sentence: "Any previous mapping at the virtual address ... is destroyed." alc: This is really a comment about the existing first sentence. I find "... inserts ... into the…
	.Fa p ,	.Fa pmap
	into the physical map	from the virtual address
	.Fa pmap ,	.Fa va
	at the virtual address	to the physical page
	.Fa va ,	.Fa m
	with the protection	with the protection
	.Fa prot .	.Fa prot .
	If	Any previous mapping at the virtual address
	.Fa wired	.Fa va
	is	is destroyed.
	.Dv TRUE ,	.Pp
	then increment the wired count for the page as soon as the mapping	The
	is inserted into	.Fa flags
	.Fa pmap .	argument takes the following values:
		alcUnsubmitted Not Done Inline Actions "... takes ..." -> "... may have ..." alc: "... takes ..." -> "... may have ..."
	.Sh IMPLEMENTATION NOTES	.Bl -tag -width ".Dv PMAP_ENTER_NOSLEEP"
	This routine MAY NOT lazy-evaluate the entry; it is required by	.It Dv VM_PROT_READ
	specification to make the requested entry at the time it is called.	The page access, which initiated the call, was for read.
		alcUnsubmitted Not Done Inline Actions As a rule, try to avoid passive voice, so... "A read access to the given virtual address triggered the call." alc: As a rule, try to avoid passive voice, so... "A read access to the given virtual address…
		.It Dv VM_PROT_WRITE
		The page access, which initiated the call, was for write.
		alcUnsubmitted Not Done Inline Actions "A write access to the given virtual address triggered the call." alc: "A write access to the given virtual address triggered the call."
		.It Dv VM_PROT_EXECUTE
		The page access, which initiated the call, was for execution.
		alcUnsubmitted Not Done Inline Actions I would simply say, "The mapping should be marked as wired." alc: I would simply say, "The mapping should be marked as wired."
		alcUnsubmitted Not Done Inline Actions "An execute access to the given virtual address triggered the call." alc: "An execute access to the given virtual address triggered the call."
		.It Dv PMAP_ENTER_WIRED
		The mapping should be marked as wired.
		alcUnsubmitted Not Done Inline Actions The phrasing "The pmap implementation ..." sounds like the entire pmap. Restrict it by saying, "This function may not ..." alc: The phrasing "The pmap implementation ..." sounds like the entire pmap. Restrict it by saying…
		.It Dv PMAP_ENTER_NOSLEEP
		alcUnsubmitted Not Done Inline Actions "If the mapping cannot be created without sleeping, ..." alc: "If the mapping cannot be created without sleeping, ..."
		This function may not sleep during creation of the mapping.
		If the mapping cannot be created without sleeping, an appropriate
		Mach VM error must be returned.
		alcUnsubmitted Not Done Inline Actions "... error code is returned." alc: "... error code is returned."
		.El
		If the
		.Dv PMAP_ENTER_NOSLEEP
		alcUnsubmitted Not Done Inline Actions I don't think that "lazy-evaluate" adds anything here to the clarity of the statement. I would say, "... this function must create the requested mapping before returning. It may not fail in the creation of the mapping." alc: I don't think that "lazy-evaluate" adds anything here to the clarity of the statement. I would…
		flag is not specified, this function must create the requested mapping
		before returning.
		It may not fail in the creation of the mapping.
		alcUnsubmitted Not Done Inline Actions I think you can simply say "It may not fail. alc: I think you can simply say "It may not fail.
		In order to create the requested mapping, this function may destroy
		alcUnsubmitted Not Done Inline Actions "In order to create the requested mapping, this function may destroy any non-wired mapping in any pmap." alc: "In order to create the requested mapping, this function may destroy any non-wired mapping in…
		any non-wired mapping in any pmap.
		.Pp
		alcUnsubmitted Not Done Inline Actions Insert a paragraph with a couple sentences about psind here? "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. Maybe add a bugs or implementation notes section saying that the implementation is incomplete on amd64, arm, and x86. Only 0 is supported. alc: Insert a paragraph with a couple sentences about psind here? "The psind parameter specifies…
		When destroying a managed mapping during creation of the requested entry,
		including the pre-existing mapping for the address
		.Fa va ,
		the
		.Va PGA_REFERENCED
		aflag for the corresponding page should be updated by the information
		alcUnsubmitted Not Done Inline Actions The word "managed" should really be in the first clause, not the second. I need to stop here for now. alc: The word "managed" should really be in the first clause, not the second. I need to stop here…
		from hardware.
		alcUnsubmitted Not Done Inline Actions "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. alc: "When the pmap_enter function destroys or updates a managed mapping, including an existing…
		If the hardware indicated that the destroyed mapping was used to write
		to the mapped page, the page
		.Va dirty
		field must be set with
		.Fn vm_page_dirty
		call.
		alcUnsubmitted Not Done Inline Actions "If the physical page was modified through the managed mapping, then the vm_page_dirty function is called on the vm_page structure. alc: "If the physical page was modified through the managed mapping, then the vm_page_dirty function…
		.Pp
		The
		.Va PGA_WRITEABLE
		aflag must be set for the page
		.Fa m
		if the new mapping is writeable.
		alcUnsubmitted Not Done Inline Actions We only set PGA_WRITEABLE for managed mappings. alc: We only set PGA_WRITEABLE for managed mappings.
		It is advised to clear
		.Va 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 passed page
		alcUnsubmitted Not Done Inline Actions Drop "passed". The use of "m" here makes it clear that we're talking about the given physical page. alc: Drop "passed". The use of "m" here makes it clear that we're talking about the given physical…
		.Fa m
		is managed, the page must be busied by the caller,
		or the owning object must be locked, in which case
		alcUnsubmitted Not Done Inline Actions "..., then it must be ... caller (no comma here) or ... locked. In the latter case, the PMAP_ENTER_NOSLEEP flag must be specified by the caller. alc: "..., then it must be ... caller (no comma here) or ... locked. In the latter case, the…
		.Dv PMAP_ENTER_NOSLEEP
		have to be specified in
		.Fa flags .
		.Pp
		The
		.Fn pmap_enter
		alcUnsubmitted Not Done Inline Actions This is equivalent to saying, "the Alan", which I don't think that you would do. :-) Use "this function", "the pmap_enter function", or simply "pmap_enter". alc: This is equivalent to saying, "the Alan", which I don't think that you would do. :-) Use "this…
		must handle the multiprocessor TLB consistency for the given address.
		.Sh RETURN VALUES
		If successful, the
		.Fn pmap_enter
		alcUnsubmitted Not Done Inline Actions See previous comment. alc: See previous comment.
		returns
		.Er KERN_SUCCESS.
		If the
		.Dv PMAP_ENTER_NOSLEEP
		flag was specified, and required resources cannot be acquired
		in non-sleeping manner, typical implementation returns
		alcUnsubmitted Not Done Inline Actions "... specified (no comma here) and the resources required for the mapping cannot be acquired without sleeping, KERN_RESOURCE_SHORTAGE is returned." I don't see the point of encouraging people to invent different return values. Didn't we use the same return value in all the implementations so far? alc: "... specified (no comma here) and the resources required for the mapping cannot be acquired…
		.Dv KERN_RESOURCE_SHORTAGE
		error.
	.Sh SEE ALSO	.Sh SEE ALSO
	.Xr pmap 9	.Xr pmap 9
	.Sh AUTHORS	.Sh AUTHORS
	This manual page was written by	This manual page was written by
		alcUnsubmitted Not Done Inline Actions "... was first written ... alc: "... was first written ...
	.An Bruce M Simpson Aq Mt bms@spc.org .	.An Bruce M Simpson Aq Mt bms@spc.org
		and
		.An Konstantin Belousov Aq Mt kib@freebsd.org .
Context not available.
		alcUnsubmitted Not Done Inline Actions I think that your name should go first. There is nothing left of the original text. alc: I think that your name should go first. There is nothing left of the original text.

Correctly case FreeBSD in my entry in the tips fileClosedPublicActions