From cdf19b639fe8fead28d11ca96355c3f62b1724c5 Mon Sep 17 00:00:00 2001 From: mickey Date: Mon, 11 Mar 1996 13:04:48 +0000 Subject: [PATCH] New pages for VM interface. Introduction need to be expanded. --- share/man/man9/Makefile | 11 ++- share/man/man9/intro.9 | 44 ++++++++++++ share/man/man9/vm_allocate.9 | 119 ++++++++++++++++++++++++++++++++ share/man/man9/vm_deallocate.9 | 97 ++++++++++++++++++++++++++ share/man/man9/vm_map_copy.9 | 102 +++++++++++++++++++++++++++ share/man/man9/vm_map_inherit.9 | 112 ++++++++++++++++++++++++++++++ share/man/man9/vm_map_protect.9 | 103 +++++++++++++++++++++++++++ 7 files changed, 586 insertions(+), 2 deletions(-) create mode 100644 share/man/man9/intro.9 create mode 100644 share/man/man9/vm_allocate.9 create mode 100644 share/man/man9/vm_deallocate.9 create mode 100644 share/man/man9/vm_map_copy.9 create mode 100644 share/man/man9/vm_map_inherit.9 create mode 100644 share/man/man9/vm_map_protect.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index e10dc6adf7f..94bc180a218 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,9 +1,13 @@ +# $OpenBSD: Makefile,v 1.3 1996/03/11 13:04:48 mickey Exp $ # $NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $ # Makefile for section 9 (kernel function and variable) manual pages. -MAN= boot.9 copy.9 disk.9 doshutdownhooks.9 fetch.9 inittodr.9 resettodr.9 \ - shutdownhook_establish.9 store.9 time.9 +MAN= boot.9 copy.9 disk.9 doshutdownhooks.9 fetch.9 intro.9 inittodr.9 \ + resettodr.9 shutdownhook_establish.9 store.9 time.9 \ + vm_allocate.9 vm_map_copy.9 vm_deallocate.9 vm_map_inherit.9 \ + vm_map_protect.9 + MLINKS+=shutdownhook_establish.9 shutdownhook_disestablish.9 MLINKS+=time.9 boottime.9 time.9 mono_time.9 time.9 runtime.9 MLINKS+=copy.9 copyin.9 copy.9 copyout.9 copy.9 copystr.9 \ @@ -15,5 +19,8 @@ MLINKS+=fetch.9 fubyte.9 fetch.9 fuibyte.9 fetch.9 fusword.9 \ fetch.9 fuswintr.9 fetch.9 fuword.9 fetch.9 fuiword.9 MLINKS+=store.9 subyte.9 store.9 suibyte.9 store.9 susword.9 \ store.9 suswintr.9 store.9 suword.9 store.9 suiword.9 +MLINKS+=vm_map_copy.9 vm_copy.9 +MLINKS+=vm_map_inherit.9 vm_inherit.9 +MLINKS+=vm_map_protect.9 vm_protect.9 .include diff --git a/share/man/man9/intro.9 b/share/man/man9/intro.9 new file mode 100644 index 00000000000..4795f32c66a --- /dev/null +++ b/share/man/man9/intro.9 @@ -0,0 +1,44 @@ +.\" $OpenBSD: intro.9,v 1.1 1996/03/11 13:04:49 mickey Exp $ +.\" +.\" Copyright (c) 1996 Michael Shalayeff +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Michael Shalayeff +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.Dd March 11, 1996 +.Dt INTRO 9 +.Os BSD 4.2 +.Sh NAME +.Nm intro +.Nd "introduction to the kernel internals" +.Sh DESCRIPTION +This section contains information related to the internal kernel +data structures, variables and functions. +.Sh HISTORY +The +.Nm intro +section manual page appeared in OpenBSD 1.2. diff --git a/share/man/man9/vm_allocate.9 b/share/man/man9/vm_allocate.9 new file mode 100644 index 00000000000..7dbee03eadd --- /dev/null +++ b/share/man/man9/vm_allocate.9 @@ -0,0 +1,119 @@ +.\" +.\" $OpenBSD: vm_allocate.9,v 1.1 1996/03/11 13:04:50 mickey Exp $ +.\" +.\" Mach Operating System +.\" Copyright (c) 1991,1990 Carnegie Mellon University +.\" All Rights Reserved. +.\" +.\" Permission to use, copy, modify and distribute this software and its +.\" documentation is hereby granted, provided that both the copyright +.\" notice and this permission notice appear in all copies of the +.\" software, derivative works or modified versions, and any portions +.\" thereof, and that both notices appear in supporting documentation. +.\" +.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" +.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. +.\" +.\" Carnegie Mellon requests users of this software to return to +.\" +.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU +.\" School of Computer Science +.\" Carnegie Mellon University +.\" Pittsburgh PA 15213-3890 +.\" +.\" any improvements or extensions that they make and grant Carnegie Mellon +.\" the rights to redistribute these changes. +.\" +.TH vm_allocate 9 9/19/93 +.CM 4 +.SH NAME +.nf +vm_allocate \- allocates virtual memory for a task +.SH SYNOPSIS +.nf +.ft B +#include + +.nf +.ft B +int vm_allocate(map, address, size, anywhere) + vm_map_t map; + vm_address_t *address; /* in/out */ + vm_size_t size; + boolean_t anywhere; + + +.fi +.ft P +.SH ARGUMENTS +.TP 15 +.B +map +Virtual address space to be affected. +.TP 15 +.B +address +Starting address. If the +.B anywhere +option is false, +an attempt is made to allocate virtual memory starting at +this virtual address. If this address is not at the beginning +of a virtual page, it will be rounded down to one. +If there is not enough space at this address, no memory will be allocated. +If the anywhere option is true, the input value of this address will +be ignored, and the space will be allocated wherever it is available. +In either case, the address at which memory was actually allocated will +be returned in +.B address +. +.TP 15 +.B +size +Number of bytes to allocate (rounded by the system in a +machine dependent way to an integral number of virtual pages). +.TP 15 +.B +anywhere +If true, the kernel should find and allocate any region of +the specified size, and return the address of the resulting region in +.B address +. If false, virtual memory will be allocated starting at +.B address +, rounded to a virtual page boundary if there +is sufficient space. + +.SH DESCRIPTION +.B vm_allocate +allocates a region of virtual memory, placing it in the +specified task's address space. The physical memory is not actually +allocated until the new virtual memory is referenced. By default, +the kernel rounds all addresses down +to the nearest page boundary and all memory sizes up to the nearest page +size. The global variable +.B cnt.vm_page_size +contains the page size. +Initially, the pages of allocated memory will be protected +to allow all forms of access, and will be inherited in child tasks as +a copy. Subsequent calls to +.B vm_map_protect +and +.B vm_map_inherit +may +be used to change these properties. The allocated region is always +zero-filled. + +.SH DIAGNOSTICS +.TP 25 +KERN_SUCCESS +Memory allocated. +.TP 25 +KERN_INVALID_ADDRESS +Illegal address specified. +.TP 25 +KERN_NO_SPACE +Not enough space left to satisfy this request + +.SH SEE ALSO +.B vm_deallocate, vm_map_inherit, vm_map_protect + diff --git a/share/man/man9/vm_deallocate.9 b/share/man/man9/vm_deallocate.9 new file mode 100644 index 00000000000..30052e89fab --- /dev/null +++ b/share/man/man9/vm_deallocate.9 @@ -0,0 +1,97 @@ +.\" +.\" $OpenBSD: vm_deallocate.9,v 1.1 1996/03/11 13:04:51 mickey Exp $ +.\" +.\" Mach Operating System +.\" Copyright (c) 1991,1990 Carnegie Mellon University +.\" All Rights Reserved. +.\" +.\" Permission to use, copy, modify and distribute this software and its +.\" documentation is hereby granted, provided that both the copyright +.\" notice and this permission notice appear in all copies of the +.\" software, derivative works or modified versions, and any portions +.\" thereof, and that both notices appear in supporting documentation. +.\" +.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" +.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. +.\" +.\" Carnegie Mellon requests users of this software to return to +.\" +.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU +.\" School of Computer Science +.\" Carnegie Mellon University +.\" Pittsburgh PA 15213-3890 +.\" +.\" any improvements or extensions that they make and grant Carnegie Mellon +.\" the rights to redistribute these changes. +.\" +.TH vm_deallocate 9 9/19/93 +.CM 4 +.SH NAME +.nf +vm_deallocate \- releases a region of a task's address space +.SH SYNOPSIS +.nf +.ft B +#include + +.nf +.ft B +int vm_deallocate(map, address, size) + vm_map_t map; + vm_address_t address; + vm_size_t size; + + +.fi +.ft P +.SH ARGUMENTS +.TP 15 +.B +map +Virtual memory map to be affected. +.TP 15 +.B +address +Starting address (will be rounded down to a page boundary). +.TP 15 +.B +size +Number of bytes to deallocate (will be rounded up to give a +page boundary). + +.SH DESCRIPTION +.B vm_deallocate +relinquishes access to a region of a map's +address space, causing further access to that memory to fail. +This address range will be available for reallocation. +Note, that because of the rounding to virtual page boundaries, more +than +.B size +bytes may be deallocated. Use +.B cnt.vm_page_size +find out the current virtual page size. + +This call may be used to deallocte memory that was passed to a task +in a message (via out of line data). In that case, the rounding should +cause no trouble, since the region of memory was allocated as a set +of pages. + +The +.B vm_deallocate +call affects only the map specified by the +.B map +. +Other maps which may have access to this memory may continue to reference it. + +.SH DIAGNOSTICS +.TP 25 +KERN_SUCCESS +Memory deallocated. +.TP 25 +KERN_INVALID_ADDRESS +Illegal or non-allocated address specified. + +.SH SEE ALSO +.B vm_allocate + diff --git a/share/man/man9/vm_map_copy.9 b/share/man/man9/vm_map_copy.9 new file mode 100644 index 00000000000..db6a6507aa9 --- /dev/null +++ b/share/man/man9/vm_map_copy.9 @@ -0,0 +1,102 @@ +.\" +.\" $OpenBSD: vm_map_copy.9,v 1.1 1996/03/11 13:04:51 mickey Exp $ +.\" +.\" Mach Operating System +.\" Copyright (c) 1991,1990 Carnegie Mellon University +.\" All Rights Reserved. +.\" +.\" Permission to use, copy, modify and distribute this software and its +.\" documentation is hereby granted, provided that both the copyright +.\" notice and this permission notice appear in all copies of the +.\" software, derivative works or modified versions, and any portions +.\" thereof, and that both notices appear in supporting documentation. +.\" +.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" +.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. +.\" +.\" Carnegie Mellon requests users of this software to return to +.\" +.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU +.\" School of Computer Science +.\" Carnegie Mellon University +.\" Pittsburgh PA 15213-3890 +.\" +.\" any improvements or extensions that they make and grant Carnegie Mellon +.\" the rights to redistribute these changes. +.\" +.TH vm_map_copy 9 9/19/93 +.CM 4 +.SH NAME +.nf +vm_map_copy \- copies memory to a destination address +.SH SYNOPSIS +.nf +.ft B +#include + +.nf +.ft B +void vm_map_copy (dst_map, src_map, dst_addr, len, sc_addr, dst_alloc, src_destroy) + vm_map_t src_map, dst_map; + vm_offset_t src_addr, dst_addr; + vm_size_t len; + boolean_t dst_alloc, src_destroy; +.fi +.ft P +.SH ARGUMENTS +.TP 15 +.B +dst_map +Virtual memory map to be affected. +.TP 15 +.B +src_map +Virtual memory map to copy from. +.TP 15 +.B +dst_addr +Address in \fBdst_map\fR +of the start of the destination range. +.TP 15 +.B +len +Number of bytes to copy. +.TP 15 +.B +src_addr +Address in \fBsrc_map\fR +of the start of the source range. +.TP 15 +.B +dst_alloc +Allocate space for destination if none exists. +.TP 15 +.B +src_destroy +Destroy the source after copy completion. +.SH DESCRIPTION +\fBvm_map_copy\fR causes the source memory range to be copied to +the destination address. The source and destination memory ranges +may overlap. The destination address range must already be allocated and +writable; the source range must be readable. + +\fBvm_map_copy\fR is equivalent to vm_read followed by vm_write. +.SH DIAGNOSTICS +.TP 25 +KERN_SUCCESS +Memory copied. +.TP 25 +KERN_PROTECTION_FAILURE +Either the destination region was not +not writable, or the source region was not readable. +.TP 25 +KERN_INVALID_ADDRESS +Illegal or non-allocated address specified or +insufficient memory allocated at one of the addresses. +.SH BUGS +The current implementation requires that \fBsrc_addr\fR, +\fBlen\fR, and \fBdst_addr\fR all be page-aligned. +Otherwise, KERN_INVALID_ARGUMENT is returned. +.SH SEE ALSO +vm_map_protect(9), diff --git a/share/man/man9/vm_map_inherit.9 b/share/man/man9/vm_map_inherit.9 new file mode 100644 index 00000000000..5172ec3af06 --- /dev/null +++ b/share/man/man9/vm_map_inherit.9 @@ -0,0 +1,112 @@ +.\" +.\" $OpenBSD: vm_map_inherit.9,v 1.1 1996/03/11 13:04:52 mickey Exp $ +.\" +.\" Mach Operating System +.\" Copyright (c) 1991,1990 Carnegie Mellon University +.\" All Rights Reserved. +.\" +.\" Permission to use, copy, modify and distribute this software and its +.\" documentation is hereby granted, provided that both the copyright +.\" notice and this permission notice appear in all copies of the +.\" software, derivative works or modified versions, and any portions +.\" thereof, and that both notices appear in supporting documentation. +.\" +.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" +.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. +.\" +.\" Carnegie Mellon requests users of this software to return to +.\" +.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU +.\" School of Computer Science +.\" Carnegie Mellon University +.\" Pittsburgh PA 15213-3890 +.\" +.\" any improvements or extensions that they make and grant Carnegie Mellon +.\" the rights to redistribute these changes. +.\" +.TH vm_map_inherit 9 9/19/93 +.CM 4 +.SH NAME +.nf +vm_map_inherit \- specifies inheritence of address space +.SH SYNOPSIS +.nf +.ft B +#include + +.nf +.ft B +int vm_inherit(map, start, end, new_inheritance) + vm_map_t map; + vm_offset_t start, end; + vm_inherit_t new_inheritance; + + +.fi +.ft P +.SH ARGUMENTS +.TP 15 +.B +map +Virtual memory map to be affected. +.TP 15 +.B +start +Starting address (will be rounded down to a page +boundary). +.TP 15 +.B +end +Ending address (will be rounded down to a page +boundary). +.TP 15 +.B +new_inheritance +How this memory is to be inherited in child maps. +Inheritance is specified by using one of these following three values: +.TP 15 +.B +VM_INHERIT_SHARE +Child maps will share this memory with this map. +.TP 15 +.B +VM_INHERIT_COPY +Child maps will receive a copy of this region. +.TP 15 +.B +VM_INHERIT_NONE +This region will be absent from child maps. + +.SH DESCRIPTION +.B vm_map_inherit +specifies how a region of a virtual address space +is to be passed to child maps at the time of map creation. +Inheritance is an attribute of virtual pages, thus the addresses +and size of memory to be set will be rounded out to refer to +whole pages. + +Setting +.B vm_map_inherit +to +.B VM_INHERIT_SHARE +and forking a child +map is the only way two +.B tasks +can share physical memory. +Remember that all the +.B theads +of a given task share all the same +memory. + +.SH DIAGNOSTICS +.TP 25 +KERN_SUCCESS +Memory protected. +.TP 25 +KERN_INVALID_ADDRESS +Illegal address specified. + +.SH SEE ALSO +.B vm_map_fork + diff --git a/share/man/man9/vm_map_protect.9 b/share/man/man9/vm_map_protect.9 new file mode 100644 index 00000000000..1dedcfc1ee9 --- /dev/null +++ b/share/man/man9/vm_map_protect.9 @@ -0,0 +1,103 @@ +.\" +.\" $OpenBSD: vm_map_protect.9,v 1.1 1996/03/11 13:04:53 mickey Exp $ +.\" +.\" Mach Operating System +.\" Copyright (c) 1991,1990 Carnegie Mellon University +.\" All Rights Reserved. +.\" +.\" Permission to use, copy, modify and distribute this software and its +.\" documentation is hereby granted, provided that both the copyright +.\" notice and this permission notice appear in all copies of the +.\" software, derivative works or modified versions, and any portions +.\" thereof, and that both notices appear in supporting documentation. +.\" +.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" +.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. +.\" +.\" Carnegie Mellon requests users of this software to return to +.\" +.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU +.\" School of Computer Science +.\" Carnegie Mellon University +.\" Pittsburgh PA 15213-3890 +.\" +.\" any improvements or extensions that they make and grant Carnegie Mellon +.\" the rights to redistribute these changes. +.\" +.TH vm_map_protect 9 9/19/93 +.CM 4 +.SH NAME +.nf +vm_map_protect \- change protection of memory +.SH SYNOPSIS +.nf +.ft B +#include + +.nf +.ft B +int vm_map_protect(map, start, end, new_prot, set_max) + vm_map_t map; + vm_offset_t start, end; + vm_prot_t new_protection; + boolean_t set_maximum; + + +.fi +.ft P +.SH ARGUMENTS +.TP 15 +.B +map +Virtual memory map to be affected. +.TP 15 +.B +start +Starting address (will be rounded down to a +page boundary). +.TP 15 +.B +end +Ending address (will be rounded down to a +page boundary). +.TP 15 +.B +new_prot +A new protection value for this region; a set of: +\fBVM_PROT_READ\fR, \fBVM_PROT_WRITE\fR, \fBVM_PROT_EXECUTE\fR. +.TP 15 +.B +set_max +If set, make the protection change apply to the +maximum protection associated with this address range; +otherwise, the current protection on this +range is changed. If the maximum protection is reduced below the +current protection, both will be changed to reflect the new maximum. + +.SH DESCRIPTION +.B vm_map_protect +sets the virtual memory access privileges for a +range of allocated addresses in a task's virtual address space. +The protection argument describes a combination of read, write, +and execute accesses that should be \fBpermitted\fR. + +The enforcement of virtual memory protection is machine-dependent. +Nominally read access requires VM_PROT_READ permission, write access +requires VM_PROT_WRITE permission, and execute access requires +VM_PROT_EXECUTE permission. However, some combinations of access +rights may not be supported. In particular, the kernel interface +allows write access to require VM_PROT_READ and VM_PROT_WRITE +permission and execute access to require VM_PROT_READ permission. + +.SH DIAGNOSTICS +.TP 25 +KERN_SUCCESS +Memory protected. +.TP 25 +KERN_PROTECTION_FAILURE +An attempt was made to increase the current +or maximum protection beyond the existing maximum protection value. +.TP 25 +KERN_INVALID_ADDRESS +Illegal or non-allocated address specified. -- 2.20.1