share/man/man4/upmap.4

   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
  39 The special files
  40 .Pa /dev/upmap
  41 and
  42 .Pa /dev/kpmap
  43 are memory-mappable devices for accessing per-process and global kernel shared
  44 memory space respectively.
  45 They can be mapped to acquire certain information from the kernel that would
  46 normally require a system call in a more efficient manner.
  47 .Pp
  48 Userland programs should not directly map the
  49 .Vt sys_upmap
  50 and
  51 .Vt sys_kpmap
  52 structures.
  53 Instead, use
  54 .Xr mmap 2
  55 using
  56 .Dv UPMAP_MAPSIZE
  57 and
  58 .Dv KPMAP_MAPSIZE
  59 and parse the
  60 .Fa ukpheader[]
  61 array at the front of each area to locate the desired fields.
  62 .Pp
  63 The width of the field is encoded in the UPTYPE/KPTYPE elements and can be
  64 asserted if desired.
  65 User programs are not expected to handle integers of multiple sizes for
  66 the same field type.
  67 .Sh INTERFACE
  68 Declarations and data types are to be found in
  69 .In sys/upmap.h .
  70 .Pp
  71 A program can open and
  72 .Xr mmap 2
  73 .Pa /dev/upmap
  74 read/write and use it to access fields from
  75 .Vt struct sys_upmap :
  76 .Bl -tag -width ".Fa proc_title"
  77 .It Fa header[]
  78 An array of headers terminating with a type of 0 indicating where
  79 various fields are in the mapping.
  80 This should be used by userland instead of directly mapping to the
  81 .Vt struct sys_upmap .
  82 .It Fa version
  83 The
  84 .Vt struct sys_upmap
  85 version, typically 1.
  86 .It Fa runticks
  87 Scheduler run ticks (aggregate, all threads).
  88 This may be used by userland interpreters to determine when to soft-switch.
  89 .It Fa forkid
  90 A unique non-zero 64-bit fork identifier.
  91 This is not a PID.
  92 It may be used by userland libraries to determine if a
  93 .Fn fork
  94 has occurred by comparing against a stored value.
  95 .It Fa invfork
  96 Allows to determine whether this is a vforked child accessing the
  97 parent's map.
  98 .It Fa pid
  99 The current process PID.
 100 This may be used to acquire the process pid without having to make
 101 further system calls.
 102 .It Fa proc_title
 103 This starts out as an empty buffer and may be used to set the
 104 process title.
 105 To revert to the original process title, set
 106 .Fa proc_title[0]
 107 to 0.
 108 .El
 109 .Pp
 110 A program can open and
 111 .Xr mmap 2
 112 .Pa /dev/kpmap
 113 read-only and use it to access fields from
 114 .Vt struct sys_kpmap :
 115 .Bl -tag -width ".Fa ts_realtime"
 116 .It Fa header[]
 117 An array of headers terminating with a header of type 0 indicating
 118 where various fields are in the mapping.
 119 This should be used by userland instead of directly mapping to the
 120 .Vt struct sys_kpmap .
 121 .It Fa version
 122 The
 123 .Vt struct sys_kpmap
 124 version, typically 1.
 125 .It Fa upticks
 126 System uptime tick counter (32 bit integer).
 127 Monotonic and uncompensated.
 128 .It Fa ts_uptime
 129 System uptime in
 130 .Vt struct timespec
 131 format at tick-resolution.
 132 Monotonic and uncompensated.
 133 .It Fa ts_realtime
 134 System realtime in
 135 .Vt struct timespec
 136 format at tick-resolution.
 137 This is compensated so reverse-indexing is possible.
 138 .It Va tsc_freq
 139 If the system supports a TSC of some sort, the TSC frequency is
 140 recorded here, else 0.
 141 .It Va tick_freq
 142 The tick resolution of
 143 .Fa ts_uptime
 144 and
 145 .Fa ts_realtime
 146 and approximate tick resolution for the scheduler, typically 100.
 147 .It Va fast_gtod
 148 This integer reflects the state of the "kern.gettimeofday_quick"
 149 sysctl.  When set to 1, gettimeofday(&tv, NULL) calls will access
 150 the tick-resolution ts_realtime[] fields instead of executing the
 151 system call.  Changes in the sysctl are immediately reflected in
 152 programs that are already running.
 153 .El
 154 .Sh NOTES
 155 With
 156 .Pa /dev/upmap ,
 157 userland may write to the entire buffer, but it is recommended that userland
 158 only write to fields intended to be writable.
 159 When a program forks, an area already
 160 .Fn mmap Ns ed
 161 remains
 162 .Fn mmap Ns ed
 163 but will point to the area of the new process and not the old.
 164 So libraries do not need to do anything special at
 165 .Fn fork .
 166 Access to the
 167 .Vt sys_upmap
 168 structure is CPU localized.
 169 .Pp
 170 With
 171 .Pa /dev/kpmap ,
 172 userland may only read from this buffer.
 173 Access to the
 174 .Vt struct sys_kpmap
 175 is NOT CPU localized.
 176 A memory fence and double-check should be used when accessing
 177 non-atomic structures which might change such as
 178 .Fa ts_uptime
 179 and
 180 .Fa ts_realtime .
 181 .Sh SEE ALSO
 182 .Xr mmap 2
 183 .Sh HISTORY
 184 The
 185 .Nm upmap
 186 and
 187 .Nm kpmap
 188 files appeared in
 189 .Dx 3.9 .