Page MenuHomeFreeBSD
Files F160504647

D57659.id180091.diff
No OneTemporary
Actions

D57659.id180091.diff
View Options

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -438,6 +438,7 @@
${_ntb_hw_intel.4} \
${_ntb_hw_plx.4} \
${_ntb_transport.4} \
+ ntsync.4 \
${_nda.4} \
${_if_ntb.4} \
null.4 \
diff --git a/share/man/man4/ntsync.4 b/share/man/man4/ntsync.4
new file mode 100644
--- /dev/null
+++ b/share/man/man4/ntsync.4
@@ -0,0 +1,227 @@
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright 2026 The FreeBSD Foundation
+.\"
+.\" This documentation was written by Konstantin Belousov <kib@FreeBSD.org>
+.\" under sponsorship from the FreeBSD Foundation.
+.\"
+.Dd June 19, 2026
+.Dt NTSYNC 4
+.Os
+.Sh NAME
+.Nm ntsync
+.Nd NT-like synchronization operations device driver
+.Sh SYNOPSIS
+.In dev/ntsync/ntsync.h
+.Sh DESCRIPTION
+The
+.Nm
+device driver provides synchonization primitives that mimic the operations
+provided by the Windows NT kernel.
+The userspace interface is copied from the identically named driver written
+for the Linux kernel, with the goal of helping Wine implement Win32 API.
+.Pp
+The driver provides the
+.Pa /dev/ntsync
+special device node that handles
+.Xr ioctl 2
+requests of several groups:
+.Bl -tag
+.It object creation
+among them semaphores, mutexes, and events.
+.It wait operations
+waiting for the set of objects to become signalled, either all
+or any objects in the set can be wait for.
+.El
+.Pp
+An
+.Xr open 2
+of the
+.Pa /dev/ntsync
+device returns the file descriptor which represents the synchronization
+domain.
+Each object created by the
+.Xr ioctl 2
+on the ntsync file descriptor belong to it.
+Wait requests must not mix the objects belonging to other domains.
+.Pp
+The synchronization objects are represented by file descriptors, each
+implementing type-specific set of ioctl requests.
+.Sh SEMAPHORES
+The semaphores operations usually take the
+.Bd -literal
+struct ntsync_sem_args {
+ uint32_t count;
+ uint32_t max;
+}
+.Ed
+as an argument.
+The semaphore requests are:
+.Bl -tag -width "NTSYNC_IOC_SEM_RELEASE"
+.It Dv NTSYNC_IOC_CREATE_SEM
+Creates the semaphore and returns the semaphore file descriptor.
+Must be issued on the
+.Pa /dev/ntsync
+file descriptor.
+.It Dv NTSYNC_IOC_SEM_RELEASE
+Releases the semaphore.
+.It Dv NTSYNC_IOC_SEM_READ
+Returns the current state of the semaphore.
+.El
+.Sh MUTEXES
+The mutexes operations usually take the
+.Bd -literal
+struct ntsync_mutex_args {
+ uint32_t owner;
+ uint32_t count;
+}
+.Ed
+as the argument.
+.Pp
+The mutex requests are:
+.Bl -tag -width "NTSYNC_IOC_CREATE_MUTEX"
+.It Dv NTSYNC_IOC_CREATE_MUTEX
+Creates the mutex and returns the mutex file descriptor.
+Must be issued on the
+.Pa /dev/ntsync
+file descriptor.
+.It Dv NTSYNC_IOC_MUTEX_UNLOCK
+Unlocks the mutex.
+.It Dv NTSYNC_IOC_MUTEX_KILL
+Abandon the mutex.
+The pending waiters are woken up, and get the
+.Ev EOWNERDEAD
+result.
+The state is cleared by next succesfull wait on the mutex.
+.It Dv NTSYNC_IOC_MUTEX_READ
+Returns the current state of the mutex.
+For abandoned mutexes, the
+.Ev EOWNERDEAD
+error is returned in addition to the state.
+.El
+.Sh EVENTS
+The events operations usually take the
+.Bd -literal
+struct ntsync_event_args {
+ uint32_t manual;
+ uint32_t signaled;
+}
+.Ed
+.Pp
+The events requests are:
+.Bl -tag -width "NTSYNC_IOC_CREATE_EVENT"
+.It Dv NTSYNC_IOC_CREATE_EVENT
+Creates the event and returns the event file descriptor.
+Must be issued on the
+.Pa /dev/ntsync
+file descriptor.
+.Pp
+Events can be of two types: manual and automatic.
+Manual events needs to be reset by the request after being set.
+Automatic events are reset by the system after a wait is satisfied.
+.It Dv NTSYNC_IOC_EVENT_SET
+Set (arm) the event.
+.It Dv NTSYNC_IOC_EVENT_RESET
+Reset (dis-arms) the event.
+.It Dv NTSYNC_IOC_EVENT_PULSE
+Atomically sets and then resets the event.
+.It Dv NTSYNC_IOC_EVENT_READ
+Returns the current state of the event.
+.El
+.Sh WAIT OPERATIONS
+Wait operations take the
+.Bd -literal
+struct ntsync_wait_args {
+ uint64_t timeout;
+ uint64_t objs;
+ uint32_t count;
+ uint32_t index;
+ uint32_t flags;
+ uint32_t owner;
+ uint32_t alert;
+ uint32_t pad;
+}
+.Ed
+as the argument.
+.Pp
+The signalled objects which cause the wait to satisfied are
+consumed by the operation, e.g. the semaphore is acquired,
+mutex is locked, manual event becomes not signalled.
+.Pp
+The
+.Dv timeout
+is in the nanoseconds for timeout.
+If
+.Dv timeout
+is zero, the wait request only returns when either the wait
+condition is satisfied, or a signal is queued.
+.Pp
+The
+.Dv objs
+member points to the array of the synchronization object's file
+descriptors.
+It's size if passed in the
+.Dv count
+member.
+It might be as large as
+.Dv NTSYNC_MAX_WAIT_COUNT ,
+which is 64.
+.Pp
+The
+.Dv alert
+if non-zero specifies the event file descriptor,
+singalling of which finishes the wait regardless the state of
+other objects in the
+.Dv objs
+array.
+.Pp
+On non-error return from the wait requests, the
+.Dv index
+member contains the index of the signalled object that caused
+the wait request to be satisfied.
+If the object is semaphore, the
+.Dv owner
+member reports the owner of the signalled semaphore.
+.Pp
+The possible values for the
+.Va flags
+parameter are
+.Bl -tag -width "NTSYNC_WAIT_REALTIME"
+.It Dv NTSYNC_WAIT_REALTIME
+The specified timeout is for
+.Dv CLOCK_REALTIME
+absolute value, otherwise it is for
+.Dv CLOCK_MONOTONIC ,
+see
+.Xr clock_gettime 2 .
+.El
+.Pp
+The wait requests are:
+.Bl -tag -width "NTSYNC_IOC_WAIT_ANY"
+.It Dv NTSYNC_IOC_WAIT_ANY
+Wait for any of the objects to become signalled.
+.It Dv NTSYNC_IOC_WAIT_ALL
+Wait for all of the objects to become signalled.
+This means that the wait is satisfied only when all objects
+can be consumed together, which is done atomically.
+.Pp
+No duplicate objects are allowed in the
+.Dv objs
+array.
+.El
+.Sh SEE ALSO
+Refer to the file
+.Pa Documentation/userspace-api/ntsync.rst
+in the Linux kernel sources for the Linux API reference,
+that was used for the implementation of the
+.Fx
+driver.
+.Sh HISTORY
+The
+.Nm
+driver and manual page first appeared in
+.Fx 15.2 .
+.Sh AUTHORS
+.An -nosplit
+The driver and the manual page were written by
+.An Konstantin Belousov Aq Mt kib@FreeBSD.org .

File Metadata

Mime Type
text/plain
Expires
Fri, Jun 26, 4:44 AM (17 h, 29 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
34341933
Default Alt Text
D57659.id180091.diff (6 KB)

Event Timeline