0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ======
0004 futex2
0005 ======
0006
0007 :Author: André Almeida <andrealmeid@collabora.com>
0008
0009 futex, or fast user mutex, is a set of syscalls to allow userspace to create
0010 performant synchronization mechanisms, such as mutexes, semaphores and
0011 conditional variables in userspace. C standard libraries, like glibc, uses it
0012 as a means to implement more high level interfaces like pthreads.
0013
0014 futex2 is a followup version of the initial futex syscall, designed to overcome
0015 limitations of the original interface.
0016
0017 User API
0018 ========
0019
0020 ``futex_waitv()``
0021 -----------------
0022
0023 Wait on an array of futexes, wake on any::
0024
0025 futex_waitv(struct futex_waitv *waiters, unsigned int nr_futexes,
0026 unsigned int flags, struct timespec *timeout, clockid_t clockid)
0027
0028 struct futex_waitv {
0029 __u64 val;
0030 __u64 uaddr;
0031 __u32 flags;
0032 __u32 __reserved;
0033 };
0034
0035 Userspace sets an array of struct futex_waitv (up to a max of 128 entries),
0036 using ``uaddr`` for the address to wait for, ``val`` for the expected value
0037 and ``flags`` to specify the type (e.g. private) and size of futex.
0038 ``__reserved`` needs to be 0, but it can be used for future extension. The
0039 pointer for the first item of the array is passed as ``waiters``. An invalid
0040 address for ``waiters`` or for any ``uaddr`` returns ``-EFAULT``.
0041
0042 If userspace has 32-bit pointers, it should do a explicit cast to make sure
0043 the upper bits are zeroed. ``uintptr_t`` does the tricky and it works for
0044 both 32/64-bit pointers.
0045
0046 ``nr_futexes`` specifies the size of the array. Numbers out of [1, 128]
0047 interval will make the syscall return ``-EINVAL``.
0048
0049 The ``flags`` argument of the syscall needs to be 0, but it can be used for
0050 future extension.
0051
0052 For each entry in ``waiters`` array, the current value at ``uaddr`` is compared
0053 to ``val``. If it's different, the syscall undo all the work done so far and
0054 return ``-EAGAIN``. If all tests and verifications succeeds, syscall waits until
0055 one of the following happens:
0056
0057 - The timeout expires, returning ``-ETIMEOUT``.
0058 - A signal was sent to the sleeping task, returning ``-ERESTARTSYS``.
0059 - Some futex at the list was woken, returning the index of some waked futex.
0060
0061 An example of how to use the interface can be found at ``tools/testing/selftests/futex/functional/futex_waitv.c``.
0062
0063 Timeout
0064 -------
0065
0066 ``struct timespec *timeout`` argument is an optional argument that points to an
0067 absolute timeout. You need to specify the type of clock being used at
0068 ``clockid`` argument. ``CLOCK_MONOTONIC`` and ``CLOCK_REALTIME`` are supported.
0069 This syscall accepts only 64bit timespec structs.
0070
0071 Types of futex
0072 --------------
0073
0074 A futex can be either private or shared. Private is used for processes that
0075 shares the same memory space and the virtual address of the futex will be the
0076 same for all processes. This allows for optimizations in the kernel. To use
0077 private futexes, it's necessary to specify ``FUTEX_PRIVATE_FLAG`` in the futex
0078 flag. For processes that doesn't share the same memory space and therefore can
0079 have different virtual addresses for the same futex (using, for instance, a
0080 file-backed shared memory) requires different internal mechanisms to be get
0081 properly enqueued. This is the default behavior, and it works with both private
0082 and shared futexes.
0083
0084 Futexes can be of different sizes: 8, 16, 32 or 64 bits. Currently, the only
0085 supported one is 32 bit sized futex, and it need to be specified using
0086 ``FUTEX_32`` flag.
