.\"
.\" 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.
.El
.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 .