247 lines
7.1 KiB
Groff
247 lines
7.1 KiB
Groff
.\" Copyright (c) 1991 The Regents of the University of California.
|
|
.\" 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.
|
|
.\" 3. 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.
|
|
.\"
|
|
.\" @(#)mem.4 5.3 (Berkeley) 5/2/91
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd August 25, 2020
|
|
.Dt MEM 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mem ,
|
|
.Nm kmem
|
|
.Nd memory files
|
|
.Sh SYNOPSIS
|
|
.Cd "device mem"
|
|
.Sh DESCRIPTION
|
|
The special file
|
|
.Pa /dev/mem
|
|
is an interface to the physical memory of the computer.
|
|
Byte offsets in this file are interpreted as physical memory addresses.
|
|
Reading and writing this file is equivalent to reading and writing
|
|
memory itself.
|
|
Only offsets within the bounds of
|
|
.Pa /dev/mem
|
|
are allowed.
|
|
.Pp
|
|
Kernel virtual memory is accessed through the interface
|
|
.Pa /dev/kmem
|
|
in the same manner as
|
|
.Pa /dev/mem .
|
|
Only kernel virtual addresses that are currently mapped to memory are allowed.
|
|
.Pp
|
|
On ISA the I/O memory space begins at physical address 0x000a0000
|
|
and runs to 0x00100000.
|
|
The
|
|
per-process data
|
|
size
|
|
for the current process
|
|
is
|
|
.Dv UPAGES
|
|
long, and ends at virtual
|
|
address 0xf0000000.
|
|
.Sh IOCTL INTERFACE
|
|
The
|
|
.Dv MEM_EXTRACT_PADDR
|
|
ioctl can be used to look up the physical address and NUMA domain of a given
|
|
virtual address in the calling process' address space.
|
|
The request is described by
|
|
.Bd -literal
|
|
struct mem_extract {
|
|
uint64_t me_vaddr; /* input */
|
|
uint64_t me_paddr; /* output */
|
|
int me_domain; /* output */
|
|
int me_state; /* output */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The ioctl returns an error if the address is not valid.
|
|
The information returned by
|
|
.Dv MEM_EXTRACT_PADDR
|
|
may be out of date by the time that the ioctl call returns.
|
|
Specifically, concurrent system calls, page faults, or system page reclamation
|
|
activity may have unmapped the virtual page or replaced the backing physical
|
|
page before the ioctl call returns.
|
|
Wired pages, e.g., those locked by
|
|
.Xr mlock 2 ,
|
|
will not be reclaimed by the system.
|
|
.Pp
|
|
The
|
|
.Fa me_state
|
|
field provides information about the state of the virtual page:
|
|
.Bl -tag -width indent
|
|
.It Dv ME_STATE_INVALID
|
|
The virtual address is invalid.
|
|
.It Dv ME_STATE_VALID
|
|
The virtual address is valid but is not mapped at the time of the ioctl call.
|
|
.It Dv ME_STATE_MAPPED
|
|
The virtual address corresponds to a physical page mapping, and the
|
|
.Fa me_paddr
|
|
and
|
|
.Fa me_domain
|
|
fields are valid.
|
|
.Pp
|
|
Several architectures allow attributes to be associated with ranges of physical
|
|
memory.
|
|
These attributes can be manipulated via
|
|
.Fn ioctl
|
|
calls performed on
|
|
.Pa /dev/mem .
|
|
Declarations and data types are to be found in
|
|
.In sys/memrange.h .
|
|
.Pp
|
|
The specific attributes, and number of programmable ranges may vary between
|
|
architectures.
|
|
The full set of supported attributes is:
|
|
.Bl -tag -width indent
|
|
.It Dv MDF_UNCACHEABLE
|
|
The region is not cached.
|
|
.It Dv MDF_WRITECOMBINE
|
|
Writes to the region may be combined or performed out of order.
|
|
.It Dv MDF_WRITETHROUGH
|
|
Writes to the region are committed synchronously.
|
|
.It Dv MDF_WRITEBACK
|
|
Writes to the region are committed asynchronously.
|
|
.It Dv MDF_WRITEPROTECT
|
|
The region cannot be written to.
|
|
.El
|
|
.Pp
|
|
Memory ranges are described by
|
|
.Bd -literal
|
|
struct mem_range_desc {
|
|
uint64_t mr_base; /* physical base address */
|
|
uint64_t mr_len; /* physical length of region */
|
|
int mr_flags; /* attributes of region */
|
|
char mr_owner[8];
|
|
};
|
|
.Ed
|
|
.Pp
|
|
In addition to the region attributes listed above, the following flags
|
|
may also be set in the
|
|
.Fa mr_flags
|
|
field:
|
|
.Bl -tag -width indent
|
|
.It MDF_FIXBASE
|
|
The region's base address cannot be changed.
|
|
.It MDF_FIXLEN
|
|
The region's length cannot be changed.
|
|
.It MDF_FIRMWARE
|
|
The region is believed to have been established by the system firmware.
|
|
.It MDF_ACTIVE
|
|
The region is currently active.
|
|
.It MDF_BOGUS
|
|
We believe the region to be invalid or otherwise erroneous.
|
|
.It MDF_FIXACTIVE
|
|
The region cannot be disabled.
|
|
.It MDF_BUSY
|
|
The region is currently owned by another process and may not be
|
|
altered.
|
|
.El
|
|
.Pp
|
|
Operations are performed using
|
|
.Bd -literal
|
|
struct mem_range_op {
|
|
struct mem_range_desc *mo_desc;
|
|
int mo_arg[2];
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Dv MEMRANGE_GET
|
|
ioctl is used to retrieve current memory range attributes.
|
|
If
|
|
.Va mo_arg[0]
|
|
is set to 0, it will be updated with the total number of memory range
|
|
descriptors.
|
|
If greater than 0, the array at
|
|
.Va mo_desc
|
|
will be filled with a corresponding number of descriptor structures,
|
|
or the maximum, whichever is less.
|
|
.Pp
|
|
The
|
|
.Dv MEMRANGE_SET
|
|
ioctl is used to add, alter and remove memory range attributes.
|
|
A range
|
|
with the
|
|
.Dv MDF_FIXACTIVE
|
|
flag may not be removed; a range with the
|
|
.Dv MDF_BUSY
|
|
flag may not be removed or updated.
|
|
.Pp
|
|
.Va mo_arg[0]
|
|
should be set to
|
|
.Dv MEMRANGE_SET_UPDATE
|
|
to update an existing or establish a new range, or to
|
|
.Dv MEMRANGE_SET_REMOVE
|
|
to remove a range.
|
|
.El
|
|
.Sh RETURN VALUES
|
|
.Bl -tag -width Er
|
|
.It Bq Er EOPNOTSUPP
|
|
Memory range operations are not supported on this architecture.
|
|
.It Bq Er ENXIO
|
|
No memory range descriptors are available (e.g., firmware has not enabled
|
|
any).
|
|
.It Bq Er EINVAL
|
|
The memory range supplied as an argument is invalid or overlaps another
|
|
range in a fashion not supported by this architecture.
|
|
.It Bq Er EBUSY
|
|
An attempt to remove or update a range failed because the range is busy.
|
|
.It Bq Er ENOSPC
|
|
An attempt to create a new range failed due to a shortage of hardware
|
|
resources (e.g., descriptor slots).
|
|
.It Bq Er ENOENT
|
|
An attempt to remove a range failed because no range matches the descriptor
|
|
base/length supplied.
|
|
.It Bq Er EPERM
|
|
An attempt to remove a range failed because the range is permanently
|
|
enabled.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /dev/kmem -compact
|
|
.It Pa /dev/mem
|
|
.It Pa /dev/kmem
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr kvm 3 ,
|
|
.Xr memcontrol 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm mem
|
|
and
|
|
.Nm kmem
|
|
files appeared in
|
|
.At v6 .
|
|
The ioctl interface for memory range attributes was added in
|
|
.Fx 3.2 .
|
|
.Sh BUGS
|
|
Busy range attributes are not yet managed correctly.
|
|
.Pp
|
|
This device is required for all users of
|
|
.Xr kvm 3
|
|
to operate.
|