DragonFly On-Line Manual Pages
UPMAP(4) DragonFly Kernel Interfaces Manual UPMAP(4)
NAME
upmap, kpmap -- character device files
DESCRIPTION
The special files /dev/upmap and /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.
Userland programs should not directly map the sys_upmap and sys_kpmap
structures. Instead, use mmap(2) using UPMAP_MAPSIZE and KPMAP_MAPSIZE
and parse the ukpheader[] array at the front of each area to locate the
desired fields.
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.
INTERFACE
Declarations and data types are to be found in <sys/upmap.h>.
A program can open and mmap(2) /dev/upmap read/write and use it to access
fields from struct sys_upmap:
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 struct
sys_upmap.
version The struct sys_upmap version, typically 1.
runticks Scheduler run ticks (aggregate, all threads). This may be
used by userland interpreters to determine when to soft-
switch.
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 fork()
has occurred by comparing against a stored value.
invfork Allows to determine whether this is a vforked child accessing
the parent's map.
pid The current process PID. This may be used to acquire the
process pid without having to make further system calls.
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
proc_title[0] to 0.
A program can open and mmap(2) /dev/kpmap read-only and use it to access
fields from struct sys_kpmap:
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 struct sys_kpmap.
version The struct sys_kpmap version, typically 1.
upticks System uptime tick counter (32 bit integer). Monotonic and
uncompensated.
ts_uptime System uptime in struct timespec format at tick-resolution.
Monotonic and uncompensated.
ts_realtime System realtime in struct timespec format at tick-
resolution. This is compensated so reverse-indexing is
possible.
tsc_freq If the system supports a TSC of some sort, the TSC frequency
is recorded here, else 0.
tick_freq The tick resolution of ts_uptime and ts_realtime and
approximate tick resolution for the scheduler, typically
100.
fast_gtod This integer reflects the state of the
"kern.gettimeofday_quick" sysctl. When set to 1,
gettimeofday(&tv, NULL) calls will access the tick-
resolution ts_realtime[] fields instead of executing the
system call. Changes in the sysctl are immediately
reflected in programs that are already running.
NOTES
With /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 mmap()ed remains mmap()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 fork(). Access to the sys_upmap
structure is CPU localized.
With /dev/kpmap, userland may only read from this buffer. Access to the
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 ts_uptime and ts_realtime.
SEE ALSO
mmap(2)
HISTORY
The upmap and kpmap files appeared in DragonFly 3.9.
DragonFly 5.5 October 25, 2014 DragonFly 5.5