1.\" 2.\" Copyright (c) 2014 The DragonFly Project. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in 12.\" the documentation and/or other materials provided with the 13.\" distribution. 14.\" 3. Neither the name of The DragonFly Project nor the names of its 15.\" contributors may be used to endorse or promote products derived 16.\" from this software without specific, prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 21.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 22.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 23.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 24.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 26.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 27.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 28.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd October 25, 2014 32.Dt UPMAP 4 33.Os 34.Sh NAME 35.Nm upmap , 36.Nm kpmap 37.Nd character device files 38.Sh DESCRIPTION 39The special files 40.Pa /dev/upmap 41and 42.Pa /dev/kpmap 43are memory-mappable devices for accessing per-process and global kernel shared 44memory space respectively. 45They can be mapped to acquire certain information from the kernel that would 46normally require a system call in a more efficient manner. 47.Pp 48Userland programs should not directly map the 49.Vt sys_upmap 50and 51.Vt sys_kpmap 52structures. 53Instead, use 54.Xr mmap 2 55using 56.Dv UPMAP_MAPSIZE 57and 58.Dv KPMAP_MAPSIZE 59and parse the 60.Fa ukpheader[] 61array at the front of each area to locate the desired fields. 62.Pp 63The width of the field is encoded in the UPTYPE/KPTYPE elements and can be 64asserted if desired. 65User programs are not expected to handle integers of multiple sizes for 66the same field type. 67.Sh INTERFACE 68Declarations and data types are to be found in 69.In sys/upmap.h . 70.Pp 71A program can open and 72.Xr mmap 2 73.Pa /dev/upmap 74read/write and use it to access fields from 75.Vt struct sys_upmap : 76.Bl -tag -width ".Fa proc_title" 77.It Fa header[] 78An array of headers terminating with a type of 0 indicating where 79various fields are in the mapping. 80This should be used by userland instead of directly mapping to the 81.Vt struct sys_upmap . 82.It Fa version 83The 84.Vt struct sys_upmap 85version, typically 1. 86.It Fa runticks 87Scheduler run ticks (aggregate, all threads). 88This may be used by userland interpreters to determine when to soft-switch. 89.It Fa forkid 90A unique non-zero 64-bit fork identifier. 91This is not a PID. 92It may be used by userland libraries to determine if a 93.Fn fork 94has occurred by comparing against a stored value. 95.It Fa invfork 96Allows to determine whether this is a vforked child accessing the 97parent's map. 98.It Fa pid 99The current process PID. 100This may be used to acquire the process pid without having to make 101further system calls. 102.It Fa proc_title 103This starts out as an empty buffer and may be used to set the 104process title. 105To revert to the original process title, set 106.Fa proc_title[0] 107to 0. 108.El 109.Pp 110A program can open and 111.Xr mmap 2 112.Pa /dev/kpmap 113read-only and use it to access fields from 114.Vt struct sys_kpmap : 115.Bl -tag -width ".Fa ts_realtime" 116.It Fa header[] 117An array of headers terminating with a header of type 0 indicating 118where various fields are in the mapping. 119This should be used by userland instead of directly mapping to the 120.Vt struct sys_kpmap . 121.It Fa version 122The 123.Vt struct sys_kpmap 124version, typically 1. 125.It Fa upticks 126System uptime tick counter (32 bit integer). 127Monotonic and uncompensated. 128.It Fa ts_uptime 129System uptime in 130.Vt struct timespec 131format at tick-resolution. 132Monotonic and uncompensated. 133.It Fa ts_realtime 134System realtime in 135.Vt struct timespec 136format at tick-resolution. 137This is compensated so reverse-indexing is possible. 138.It Va tsc_freq 139If the system supports a TSC of some sort, the TSC frequency is 140recorded here, else 0. 141.It Va tick_freq 142The tick resolution of 143.Fa ts_uptime 144and 145.Fa ts_realtime 146and approximate tick resolution for the scheduler, typically 100. 147.It Va fast_gtod 148This integer reflects the state of the "kern.gettimeofday_quick" 149sysctl. When set to 1, gettimeofday(&tv, NULL) calls will access 150the tick-resolution ts_realtime[] fields instead of executing the 151system call. Changes in the sysctl are immediately reflected in 152programs that are already running. 153.El 154.Sh NOTES 155With 156.Pa /dev/upmap , 157userland may write to the entire buffer, but it is recommended that userland 158only write to fields intended to be writable. 159When a program forks, an area already 160.Fn mmap Ns ed 161remains 162.Fn mmap Ns ed 163but will point to the area of the new process and not the old. 164So libraries do not need to do anything special at 165.Fn fork . 166Access to the 167.Vt sys_upmap 168structure is CPU localized. 169.Pp 170With 171.Pa /dev/kpmap , 172userland may only read from this buffer. 173Access to the 174.Vt struct sys_kpmap 175is NOT CPU localized. 176A memory fence and double-check should be used when accessing 177non-atomic structures which might change such as 178.Fa ts_uptime 179and 180.Fa ts_realtime . 181.Sh SEE ALSO 182.Xr mmap 2 183.Sh HISTORY 184The 185.Nm upmap 186and 187.Nm kpmap 188files appeared in 189.Dx 3.9 . 190