Add a upmap(4)/kpmap(4) manual page.
authorSascha Wildner <saw@online.de>
Sat, 25 Oct 2014 15:05:27 +0000 (17:05 +0200)
committerSascha Wildner <saw@online.de>
Sat, 25 Oct 2014 15:05:27 +0000 (17:05 +0200)
Submitted-by: Robin Hahling <robin.hahling@gw-computing.net>
share/man/man4/Makefile
share/man/man4/upmap.4 [new file with mode: 0644]

index 0fbcc7c..6d6cfed 100644 (file)
@@ -345,6 +345,7 @@ MAN=        aac.4 \
        ums.4 \
        unix.4 \
        uplcom.4 \
+       upmap.4 \
        urio.4 \
        usb.4 \
        uscanner.4 \
@@ -516,6 +517,7 @@ MLINKS+=ti.4 if_ti.4
 MLINKS+=tl.4 if_tl.4
 MLINKS+=tun.4 if_tun.4
 MLINKS+=txp.4 if_txp.4
+MLINKS+=upmap.4 kpmap.4
 #MLINKS+=ural.4 if_ural.4
 MLINKS+=vga.4 vesa.4
 MLINKS+=vge.4 if_vge.4
diff --git a/share/man/man4/upmap.4 b/share/man/man4/upmap.4
new file mode 100644 (file)
index 0000000..f7949a1
--- /dev/null
@@ -0,0 +1,182 @@
+.\"
+.\" Copyright (c) 2014 The DragonFly Project.  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 DragonFly Project 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 COPYRIGHT HOLDERS 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
+.\" COPYRIGHT HOLDERS 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 October 25, 2014
+.Dt UPMAP 4
+.Os
+.Sh NAME
+.Nm upmap ,
+.Nm kpmap
+.Nd character device files
+.Sh DESCRIPTION
+The special files
+.Pa /dev/upmap
+and
+.Pa /dev/kpmap
+are memory-mappable devices for accessing per-process and global kernel shared
+memory space respectively.
+They can be mapped to acquire certain information from the kernel that would
+normally require a system call in a more efficient manner.
+.Pp
+Userland programs should not directly map the
+.Vt sys_upmap
+and
+.Vt sys_kpmap
+structures.
+Instead, use
+.Xr mmap 2
+using
+.Dv UPMAP_MAPSIZE
+and
+.Dv KPMAP_MAPSIZE
+and parse the
+.Fa ukpheader[]
+array at the front of each area to locate the desired fields.
+.Pp
+The width of the field is encoded in the UPTYPE/KPTYPE elements and can be
+asserted if desired.
+User programs are not expected to handle integers of multiple sizes for
+the same field type.
+.Sh INTERFACE
+Declarations and data types are to be found in
+.In sys/upmap.h .
+.Pp
+A program can open and
+.Xr mmap 2
+.Pa /dev/upmap
+read/write and use it to access fields from
+.Vt struct sys_upmap :
+.Bl -tag -width ".Fa proc_title"
+.It Fa header[]
+An array of headers terminating with a type of 0 indicating where
+various fields are in the mapping.
+This should be used by userland instead of directly mapping to the
+.Vt struct sys_upmap .
+.It Fa version
+The
+.Vt struct sys_upmap
+version, typically 1.
+.It Fa runticks
+Scheduler run ticks (aggregate, all threads).
+This may be used by userland interpreters to determine when to soft-switch.
+.It Fa forkid
+A unique non-zero 64-bit fork identifier.
+This is not a PID.
+It may be used by userland libraries to determine if a
+.Fn fork
+has occured by comparing against a stored value.
+.It Fa invfork
+Allows to determine whether this is a vforked child accessing the
+parent's map.
+.It Fa pid
+The current process PID.
+This may be used to acquire the process pid without having to make
+further system calls.
+.It Fa proc_title
+This starts out as an empty buffer and may be used to set the
+process title.
+To revert to the original process title, set
+.Fa proc_title[0]
+to 0.
+.El
+.Pp
+A program can open and
+.Xr mmap 2
+.Pa /dev/kpmap
+read-only and use it to access fields from
+.Vt struct sys_kpmap :
+.Bl -tag -width ".Fa ts_realtime"
+.It Fa header[]
+An array of headers terminating with a header of type 0 indicating
+where various fields are in the mapping.
+This should be used by userland instead of directly mapping to the
+.Vt struct sys_kpmap .
+.It Fa version
+The
+.Vt struct sys_kpmap
+version, typically 1.
+.It Fa upticks
+System uptime tick counter (32 bit integer).
+Monotonic and uncompensated.
+.It Fa ts_uptime
+System uptime in
+.Vt struct timespec
+format at tick-resolution.
+Monotonic and uncompensated.
+.It Fa ts_realtime
+System realtime in
+.Vt struct timespec
+format at tick-resolution.
+This is compensated so reverse-indexing is possible.
+.It Va tsc_freq
+If the system supports a TSC of some sort, the TSC frequency is
+recorded here, else 0.
+.It Va tick_freq
+The tick resolution of
+.Fa ts_uptime
+and
+.Fa ts_realtime
+and approximate tick resolution for the scheduler, typically 100.
+.Sh NOTES
+With
+.Pa /dev/upmap ,
+userland may write to the entire buffer, but it is recommended that userland
+only write to fields intended to be writable.
+When a program forks, an area already
+.Fn mmap Ns ed
+remains
+.Fn mmap Ns ed
+but will point to the area of the new process and not the old.
+So libraries do not need to do anything special at
+.Fn fork .
+Access to the
+.Vt sys_upmap
+structure is CPU localized.
+.Pp
+With
+.Pa /dev/kpmap ,
+userland may only read from this buffer.
+Access to the
+.Vt struct sys_kpmap
+is NOT CPU localized.
+A memory fence and double-check should be used when accessing
+non-atomic structures which might change such as
+.Fa ts_uptime
+and
+.Fa ts_realtime .
+.Sh SEE ALSO
+.Xr mmap 2
+.Sh HISTORY
+The
+.Nm upmap
+and
+.Nm kpmap
+files appeared in
+.Dx 3.9 .