Fix a number of typos in manual pages and user-visible messages.
[dragonfly.git] / share / man / man4 / upmap.4
CommitLineData
1ec97b1e
SW
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
1ef3b4ca 94has occurred by comparing against a stored value.
1ec97b1e
SW
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.
8ffa5452 147.El
1ec97b1e
SW
148.Sh NOTES
149With
150.Pa /dev/upmap ,
151userland may write to the entire buffer, but it is recommended that userland
152only write to fields intended to be writable.
153When a program forks, an area already
154.Fn mmap Ns ed
155remains
156.Fn mmap Ns ed
157but will point to the area of the new process and not the old.
158So libraries do not need to do anything special at
159.Fn fork .
160Access to the
161.Vt sys_upmap
162structure is CPU localized.
163.Pp
164With
165.Pa /dev/kpmap ,
166userland may only read from this buffer.
167Access to the
168.Vt struct sys_kpmap
169is NOT CPU localized.
170A memory fence and double-check should be used when accessing
171non-atomic structures which might change such as
172.Fa ts_uptime
173and
174.Fa ts_realtime .
175.Sh SEE ALSO
176.Xr mmap 2
177.Sh HISTORY
178The
179.Nm upmap
180and
181.Nm kpmap
182files appeared in
183.Dx 3.9 .