2 .\" Copyright (c) 2014 The DragonFly Project. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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
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.
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
37 .Nd character device files
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.
48 Userland programs should not directly map the
61 array at the front of each area to locate the desired fields.
63 The width of the field is encoded in the UPTYPE/KPTYPE elements and can be
65 User programs are not expected to handle integers of multiple sizes for
68 Declarations and data types are to be found in
71 A program can open and
74 read/write and use it to access fields from
75 .Vt struct sys_upmap :
76 .Bl -tag -width ".Fa proc_title"
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 .
87 Scheduler run ticks (aggregate, all threads).
88 This may be used by userland interpreters to determine when to soft-switch.
90 A unique non-zero 64-bit fork identifier.
92 It may be used by userland libraries to determine if a
94 has occurred by comparing against a stored value.
96 Allows to determine whether this is a vforked child accessing the
99 The current process PID.
100 This may be used to acquire the process pid without having to make
101 further system calls.
103 This starts out as an empty buffer and may be used to set the
105 To revert to the original process title, set
110 A program can open and
113 read-only and use it to access fields from
114 .Vt struct sys_kpmap :
115 .Bl -tag -width ".Fa ts_realtime"
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 .
124 version, typically 1.
126 System uptime tick counter (32 bit integer).
127 Monotonic and uncompensated.
131 format at tick-resolution.
132 Monotonic and uncompensated.
136 format at tick-resolution.
137 This is compensated so reverse-indexing is possible.
139 If the system supports a TSC of some sort, the TSC frequency is
140 recorded here, else 0.
142 The tick resolution of
146 and approximate tick resolution for the scheduler, typically 100.
151 userland may write to the entire buffer, but it is recommended that userland
152 only write to fields intended to be writable.
153 When a program forks, an area already
157 but will point to the area of the new process and not the old.
158 So libraries do not need to do anything special at
162 structure is CPU localized.
166 userland may only read from this buffer.
169 is NOT CPU localized.
170 A memory fence and double-check should be used when accessing
171 non-atomic structures which might change such as