linux-kernel - [PATCH 1/2] futex.2: 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] [day] [month] [year] [list]

Message-Id: <1475270864-51787-2-git-send-email-Waiman.Long@hpe.com>
Date:   Fri, 30 Sep 2016 17:27:43 -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 1/2] futex.2: 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(2) manpage is extended
to include description about the operations.

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

diff --git a/man2/futex.2 b/man2/futex.2
index 5b0083e..6cf67cc 100644
--- a/man2/futex.2
+++ b/man2/futex.2
@@ -816,6 +816,55 @@ arguments are ignored.
 .\"
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .\"
+.TP
+.BR FUTEX_LOCK " (since Linux 4.X)"
+This operation is used for the locking part of contended userspace mutexes.
+The waiter will attempt to steal the lock once at the beginning of the system
+call. If it can't get the lock, it will be put into the waiting queue of
+a seralization kernel mutex. Once it becomes the owner of the mutex,
+it will spin on the futex owner while it is running until the owner releases
+the futex. The spinning is done without sleeping as long as the futex owner
+is running and the waiter hasn't run out its scheduling time slice.
+The same is true for those waiting within the serialization mutex.
+As a result, the unlock-to-lock latency is reduced leading to faster
+performance.
+
+As long as the serialization mutex owner is running, it won't cause
+the futex owner to release the futex by using the
+.BR FUTEX_UNLOCK
+operation. So more lock stealings can go on in userspace leading to
+better performance. When the mutex owner is sleeping, the futex owner will
+have to call into the kernel to wake up the mutex owner and release the futex.
+
+One consequence of this design is lock starvation as the kernel waiter has
+no guarantee that it will ever get the lock. This is counteracted by a
+lock hand-off mechanism where the futex owner is forced to call into
+the kernel to explicitly transfer the lock ownership to the mutex owner
+when the latter has waited too long without getting the futex.
+
+The
+.IR val ,
+.I uaddr2
+and
+.I val3
+arguments are ignored.
+.\"
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.\"
+.TP
+.BR FUTEX_UNLOCK " (since Linux 4.X)"
+This operation is used for the unlocking part of contended userspace mutexes.
+This call is only needed when the serialization mutex owner is sleeping
+or lock hand-off is activated. In this case, the sleeping waiter is woken
+up and the futex is either released or its ownership transferred to the
+mutex owner.
+
+All the arugments except
+.I uaddr
+are ignored.
+.\"
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.\"
 .SS Priority-inheritance futexes
 Linux supports priority-inheritance (PI) futexes in order to handle
 priority-inversion problems that can be encountered with
-- 
1.7.1