diff options
Diffstat (limited to 'static/freebsd/man4/mem.4 3.html')
| -rw-r--r-- | static/freebsd/man4/mem.4 3.html | 270 |
1 files changed, 270 insertions, 0 deletions
diff --git a/static/freebsd/man4/mem.4 3.html b/static/freebsd/man4/mem.4 3.html new file mode 100644 index 00000000..eec983b3 --- /dev/null +++ b/static/freebsd/man4/mem.4 3.html @@ -0,0 +1,270 @@ +<table class="head"> + <tr> + <td class="head-ltitle">MEM(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">MEM(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">mem</code>, <code class="Nm">kmem</code> — + <span class="Nd">memory files</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Cd">device mem</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The special file <span class="Pa">/dev/mem</span> 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 <span class="Pa">/dev/mem</span> are allowed.</p> +<p class="Pp">Kernel virtual memory is accessed through the interface + <span class="Pa">/dev/kmem</span> in the same manner as + <span class="Pa">/dev/mem</span>. Only kernel virtual addresses that are + currently mapped to memory are allowed.</p> +<p class="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 + <code class="Dv">UPAGES</code> long, and ends at virtual address + 0xf0000000.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="IOCTL_INTERFACE"><a class="permalink" href="#IOCTL_INTERFACE">IOCTL + INTERFACE</a></h1> +<section class="Ss"> +<h2 class="Ss" id="Address_Properties"><a class="permalink" href="#Address_Properties">Address + Properties</a></h2> +<p class="Pp">The <code class="Dv">MEM_EXTRACT_PADDR</code> 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</p> +<div class="Bd Pp Li"> +<pre>struct mem_extract { + uint64_t me_vaddr; /* input */ + uint64_t me_paddr; /* output */ + int me_domain; /* output */ + int me_state; /* output */ +};</pre> +</div> +<p class="Pp">The ioctl returns an error if the address is not valid. The + information returned by <code class="Dv">MEM_EXTRACT_PADDR</code> 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 + <a class="Xr">mlock(2)</a>, will not be reclaimed by the system.</p> +<p class="Pp">The <var class="Fa">me_state</var> field provides information + about the state of the virtual page:</p> +<dl class="Bl-tag"> + <dt id="ME_STATE_INVALID"><a class="permalink" href="#ME_STATE_INVALID"><code class="Dv">ME_STATE_INVALID</code></a></dt> + <dd>The virtual address is invalid.</dd> + <dt id="ME_STATE_VALID"><a class="permalink" href="#ME_STATE_VALID"><code class="Dv">ME_STATE_VALID</code></a></dt> + <dd>The virtual address is valid but is not mapped at the time of the ioctl + call.</dd> + <dt id="ME_STATE_MAPPED"><a class="permalink" href="#ME_STATE_MAPPED"><code class="Dv">ME_STATE_MAPPED</code></a></dt> + <dd>The virtual address corresponds to a physical page mapping, and the + <var class="Fa">me_paddr</var> and <var class="Fa">me_domain</var> fields + are valid.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Memory_Ranges"><a class="permalink" href="#Memory_Ranges">Memory + Ranges</a></h2> +<p class="Pp">Several architectures allow attributes to be associated with + ranges of physical memory. These attributes can be manipulated via + <a class="permalink" href="#ioctl"><code class="Fn" id="ioctl">ioctl</code></a>() + calls performed on <span class="Pa">/dev/mem</span>. Declarations and data + types are to be found in + <code class="In"><<a class="In">sys/memrange.h</a>></code>.</p> +<p class="Pp">The specific attributes, and number of programmable ranges may + vary between architectures. The full set of supported attributes is:</p> +<dl class="Bl-tag"> + <dt id="MDF_UNCACHEABLE"><a class="permalink" href="#MDF_UNCACHEABLE"><code class="Dv">MDF_UNCACHEABLE</code></a></dt> + <dd>The region is not cached.</dd> + <dt id="MDF_WRITECOMBINE"><a class="permalink" href="#MDF_WRITECOMBINE"><code class="Dv">MDF_WRITECOMBINE</code></a></dt> + <dd>Writes to the region may be combined or performed out of order.</dd> + <dt id="MDF_WRITETHROUGH"><a class="permalink" href="#MDF_WRITETHROUGH"><code class="Dv">MDF_WRITETHROUGH</code></a></dt> + <dd>Writes to the region are committed synchronously.</dd> + <dt id="MDF_WRITEBACK"><a class="permalink" href="#MDF_WRITEBACK"><code class="Dv">MDF_WRITEBACK</code></a></dt> + <dd>Writes to the region are committed asynchronously.</dd> + <dt id="MDF_WRITEPROTECT"><a class="permalink" href="#MDF_WRITEPROTECT"><code class="Dv">MDF_WRITEPROTECT</code></a></dt> + <dd>The region cannot be written to.</dd> +</dl> +<p class="Pp">Memory ranges are described by</p> +<div class="Bd Pp Li"> +<pre>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]; +};</pre> +</div> +<p class="Pp">In addition to the region attributes listed above, the following + flags may also be set in the <var class="Fa">mr_flags</var> field:</p> +<dl class="Bl-tag"> + <dt>MDF_FIXBASE</dt> + <dd>The region's base address cannot be changed.</dd> + <dt>MDF_FIXLEN</dt> + <dd>The region's length cannot be changed.</dd> + <dt>MDF_FIRMWARE</dt> + <dd>The region is believed to have been established by the system + firmware.</dd> + <dt>MDF_ACTIVE</dt> + <dd>The region is currently active.</dd> + <dt>MDF_BOGUS</dt> + <dd>We believe the region to be invalid or otherwise erroneous.</dd> + <dt>MDF_FIXACTIVE</dt> + <dd>The region cannot be disabled.</dd> + <dt>MDF_BUSY</dt> + <dd>The region is currently owned by another process and may not be + altered.</dd> +</dl> +<p class="Pp">Operations are performed using</p> +<div class="Bd Pp Li"> +<pre>struct mem_range_op { + struct mem_range_desc *mo_desc; + int mo_arg[2]; +};</pre> +</div> +<p class="Pp">The <code class="Dv">MEMRANGE_GET</code> ioctl is used to retrieve + current memory range attributes. If <var class="Va">mo_arg[0]</var> is set + to 0, it will be updated with the total number of memory range descriptors. + If greater than 0, the array at <var class="Va">mo_desc</var> will be filled + with a corresponding number of descriptor structures, or the maximum, + whichever is less.</p> +<p class="Pp">The <code class="Dv">MEMRANGE_SET</code> ioctl is used to add, + alter and remove memory range attributes. A range with the + <code class="Dv">MDF_FIXACTIVE</code> flag may not be removed; a range with + the <code class="Dv">MDF_BUSY</code> flag may not be removed or updated.</p> +<p class="Pp"><var class="Va">mo_arg[0]</var> should be set to + <code class="Dv">MEMRANGE_SET_UPDATE</code> to update an existing or + establish a new range, or to <code class="Dv">MEMRANGE_SET_REMOVE</code> to + remove a range.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Live_Kernel_Dumps"><a class="permalink" href="#Live_Kernel_Dumps">Live + Kernel Dumps</a></h2> +<p class="Pp">The <code class="Dv">MEM_KERNELDUMP</code> 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</p> +<div class="Bd Pp Li"> +<pre>struct mem_livedump_arg { + int fd; /* input */ + int flags /* input */ + uint8_t compression /* input */ +};</pre> +</div> +<p class="Pp">The <var class="Va">fd</var> field is used to pass the file + descriptor.</p> +<p class="Pp">The <var class="Va">flags</var> field is currently unused and must + be set to zero.</p> +<p class="Pp">The <var class="Va">compression</var> field can be used to specify + the desired compression to be applied to the dump output. The supported + values are defined in + <code class="In"><<a class="In">sys/kerneldump.h</a>></code>; that is, + <code class="Dv">KERNELDUMP_COMP_NONE</code>, + <code class="Dv">KERNELDUMP_COMP_GZIP</code>, or + <code class="Dv">KERNELDUMP_COMP_ZSTD</code>.</p> +<p class="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.</p> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<section class="Ss"> +<h2 class="Ss" id="MEM_EXTRACT_PADDR"><a class="permalink" href="#MEM_EXTRACT_PADDR">MEM_EXTRACT_PADDR</a></h2> +<p class="Pp">The <code class="Dv">MEM_EXTRACT_PADDR</code> ioctl always returns + a value of zero.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MEMRANGE_GET/MEMRANGE_SET"><a class="permalink" href="#MEMRANGE_GET/MEMRANGE_SET">MEMRANGE_GET/MEMRANGE_SET</a></h2> +<dl class="Bl-tag"> + <dt>[<code class="Er">EOPNOTSUPP</code>]</dt> + <dd>Memory range operations are not supported on this architecture.</dd> + <dt>[<code class="Er">ENXIO</code>]</dt> + <dd>No memory range descriptors are available (e.g., firmware has not enabled + any).</dd> + <dt>[<code class="Er">EINVAL</code>]</dt> + <dd>The memory range supplied as an argument is invalid or overlaps another + range in a fashion not supported by this architecture.</dd> + <dt>[<code class="Er">EBUSY</code>]</dt> + <dd>An attempt to remove or update a range failed because the range is + busy.</dd> + <dt>[<code class="Er">ENOSPC</code>]</dt> + <dd>An attempt to create a new range failed due to a shortage of hardware + resources (e.g., descriptor slots).</dd> + <dt>[<code class="Er">ENOENT</code>]</dt> + <dd>An attempt to remove a range failed because no range matches the + descriptor base/length supplied.</dd> + <dt>[<code class="Er">EPERM</code>]</dt> + <dd>An attempt to remove a range failed because the range is permanently + enabled.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="MEM_KERNELDUMP"><a class="permalink" href="#MEM_KERNELDUMP">MEM_KERNELDUMP</a></h2> +<dl class="Bl-tag"> + <dt>[<code class="Er">EOPNOTSUPP</code>]</dt> + <dd>Kernel minidumps are not supported on this architecture.</dd> + <dt>[<code class="Er">EPERM</code>]</dt> + <dd>An attempt to begin the kernel dump failed because the calling thread + lacks the</dd> + <dt>[<code class="Er">EBADF</code>]</dt> + <dd>The supplied file descriptor was invalid, or does not have write + permission.</dd> + <dt>[<code class="Er">EBUSY</code>]</dt> + <dd>An attempt to begin the kernel dump failed because one is already in + progress.</dd> + <dt>[<code class="Er">EINVAL</code>]</dt> + <dd>An invalid or unsupported value was specified in + <var class="Va">flags</var>.</dd> + <dt>[<code class="Er">EINVAL</code>]</dt> + <dd>An invalid or unsupported compression type was specified. + <code class="Dv">PRIV_KMEM_READ</code> privilege.</dd> +</dl> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<dl class="Bl-tag Bl-compact"> + <dt><span class="Pa">/dev/mem</span></dt> + <dd style="width: auto;"> </dd> + <dt><span class="Pa">/dev/kmem</span></dt> + <dd style="width: auto;"> </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">kvm(3)</a>, <a class="Xr">memcontrol(8)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <span class="Pa">/dev/mem</span> file appeared in + <span class="Ux">Version 1 AT&T UNIX</span> and + <span class="Pa">/dev/kmem</span> in <span class="Ux">Version 5 + AT&T UNIX</span>. The ioctl interface for memory range attributes was + added in <span class="Ux">FreeBSD 3.2</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">Busy range attributes are not yet managed correctly.</p> +<p class="Pp">This device is required for all users of <a class="Xr">kvm(3)</a> + to operate.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 24, 2024</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |