linux-kernel - [PATCH 2/2] futex.7: Add description about the FUTEX_LOCK/FUTEX

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <1475270864-51787-3-git-send-email-Waiman.Long@hpe.com>
Date:   Fri, 30 Sep 2016 17:27:44 -0400
From:   Waiman Long <Waiman.Long@....com>
To:     mtk.manpages@...il.com
Cc:     linux-man@...r.kernel.org, linux-kernel@...r.kernel.org,
        Thomas Gleixner <tglx@...utronix.de>,
        Ingo Molnar <mingo@...nel.org>,
        Peter Zijlstra <peterz@...radead.org>,
        Jonathan Corbet <corbet@....net>,
        Davidlohr Bueso <dave@...olabs.net>,
        Mike Galbraith <umgwanakikbuti@...il.com>,
        Jason Low <jason.low2@....com>,
        Scott J Norton <scott.norton@....com>,
        Douglas Hatch <doug.hatch@....com>,
        Waiman Long <Waiman.Long@....com>
Subject: [PATCH 2/2] futex.7: Add description about the FUTEX_LOCK/FUTEX_UNLOCK operations

The FUTEX_LOCK and FUTEX_UNLOCK operation pair is for supporting the
new throughput-optimized futexes. The futex(7) manpage is extended
to include description about the operations.

Signed-off-by: Waiman Long <Waiman.Long@....com>
---
 man7/futex.7 |   22 ++++++++++++++++++++++
 1 files changed, 22 insertions(+), 0 deletions(-)

diff --git a/man7/futex.7 b/man7/futex.7
index 8312c6b..6adf3a2 100644
--- a/man7/futex.7
+++ b/man7/futex.7
@@ -78,6 +78,22 @@ This is done using the
 .B FUTEX_WAIT
 operation.
 .PP
+For implementing just userspace mutexes, a faster
+.B FUTEX_LOCK
+and
+.B FUTEX_UNLOCK
+operation pair can be used instead for SMP systems that support atomic
+compare and exchange instruction.
+To acquire a mutex, atomically compare and exchange the futex from 0 to
+the task's thread ID as returned by the
+.BR gettid (2)
+system call. If that fails, call into kernel using the
+.B FUTEX_LOCK
+operation. To release a mutex, atomically compare and exchange the futex
+from the thread ID to 0. If that fails, call into kernel using the
+.B FUTEX_UNLOCK
+operation.
+.PP
 The
 .BR futex (2)
 system call can optionally be passed a timeout specifying how long
@@ -94,6 +110,11 @@ The same holds for asynchronous futex waiting.
 Initial futex support was merged in Linux 2.5.7
 but with different semantics from those described above.
 Current semantics are available from Linux 2.5.40 onward.
+The
+.B FUTEX_LOCK
+and
+.B FUTEX_UNLOCK
+operation pair support was merged in Linux 4.X.
 .SH NOTES
 .PP
 To reiterate, bare futexes are not intended as an easy-to-use
@@ -116,6 +137,7 @@ primitives; it is by no means the only one.
 .BR clone (2),
 .BR futex (2),
 .BR get_robust_list (2),
+.BR gettid (2),
 .BR set_robust_list (2),
 .BR set_tid_address (2),
 .BR pthreads (7)
-- 
1.7.1