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.