diff options
Diffstat (limited to 'static/freebsd/man4/mem.4')
| -rw-r--r-- | static/freebsd/man4/mem.4 | 314 |
1 files changed, 314 insertions, 0 deletions
diff --git a/static/freebsd/man4/mem.4 b/static/freebsd/man4/mem.4 new file mode 100644 index 00000000..595cb8a6 --- /dev/null +++ b/static/freebsd/man4/mem.4 @@ -0,0 +1,314 @@ +.\" 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. +.\" +.Dd March 24, 2024 +.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 +.Ss Address Properties +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. +.El +.Ss Memory Ranges +.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. +.Ss Live Kernel Dumps +.Pp +The +.Dv MEM_KERNELDUMP +ioctl will initiate a kernel dump against the running system, the contents of +which will be written to a process-owned file descriptor. +The resulting dump output will be in minidump format. +The request is described by +.Bd -literal +struct mem_livedump_arg { + int fd; /* input */ + int flags /* input */ + uint8_t compression /* input */ +}; +.Ed +.Pp +The +.Va fd +field is used to pass the file descriptor. +.Pp +The +.Va flags +field is currently unused and must be set to zero. +.Pp +The +.Va compression +field can be used to specify the desired compression to +be applied to the dump output. +The supported values are defined in +.In sys/kerneldump.h ; +that is, +.Dv KERNELDUMP_COMP_NONE , +.Dv KERNELDUMP_COMP_GZIP , +or +.Dv KERNELDUMP_COMP_ZSTD . +.Pp +Kernel dumps taken against the running system may have inconsistent kernel data +structures due to allocation, deallocation, or modification of memory +concurrent to the dump procedure. +Thus, the resulting core dump is not guaranteed to be usable. +A system under load is more likely to produce an inconsistent result. +Despite this, live kernel dumps can be useful for offline debugging of certain +types of kernel bugs, such as deadlocks, or in inspecting a particular part of +the system's state. +.Sh RETURN VALUES +.Ss MEM_EXTRACT_PADDR +The +.Dv MEM_EXTRACT_PADDR +ioctl always returns a value of zero. +.Ss MEMRANGE_GET/MEMRANGE_SET +.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 +.Ss MEM_KERNELDUMP +.Bl -tag -width Er +.It Bq Er EOPNOTSUPP +Kernel minidumps are not supported on this architecture. +.It Bq Er EPERM +An attempt to begin the kernel dump failed because the calling thread lacks the +.It Bq Er EBADF +The supplied file descriptor was invalid, or does not have write permission. +.It Bq Er EBUSY +An attempt to begin the kernel dump failed because one is already in progress. +.It Bq Er EINVAL +An invalid or unsupported value was specified in +.Va flags . +.It Bq Er EINVAL +An invalid or unsupported compression type was specified. +.Dv PRIV_KMEM_READ +privilege. +.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 +.Pa /dev/mem +file appeared in +.At v1 +and +.Pa /dev/kmem +in +.At v5 . +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. |