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
HISTORY
The upmap and
kpmap files appeared in DragonFly
3.9.