linux/tools/testing/selftests/futex
Linus Torvalds f38b1f243e Update for the futex subsystem:
- Switch the reference counting to a RCU based per-CPU reference to
      address a performance bottleneck vs. the single instance rcuref
      variant.
 
    - Make the futex selftest build on 32-bit architectures which only
      support 64-bit time_t, e.g. RISCV-32.
 
    - Cleanups and improvements in selftests and futex bench
 -----BEGIN PGP SIGNATURE-----
 
 iQJHBAABCgAxFiEEQp8+kY+LLUocC4bMphj1TA10mKEFAmiIiDITHHRnbHhAbGlu
 dXRyb25peC5kZQAKCRCmGPVMDXSYoblTD/0eV9w21tFVmn6ICrhgQgsrejJ0BANs
 mm5mE/0d29MZHEhnJO2CSccGXBDfykuk/gxHXHsUZ9tiVSOgjz9dDl1bcrZ8Je9V
 YNWMXiHASQrLctmrKLPSdjlcxQnPIxCm+K4lajoa+CyvReHE24sUDgCN8GC3P9pH
 VxTmQ7UjGrzvIRlfd4AL9GJBF1IGKNnpPHCeSwjn/cmlDxu4RxEdjRWTbW8Tbz9N
 1ay/T8vEE1SykI2qZOXIP16sYZw2dP9FOgARO90Ahb6hwAwbI72MvC69GpZe3lh5
 1B1ZgpEiUMa4IT5jJ43Wkm3k8BF6meW+rIUjUBt+y8yjNgaR4degvgnDx44YPZ94
 5Ek3cJgpTpVnWbfRxn2b2vRL8rZkRBIq9ezswp0/8KLgC7Gd+zPuQKPvoo2m+n3S
 UMufGGT2h5oJbx0qGry5rxZz03eGE6oWAm3H/WRl2wIw5D/kvU5ol6AYKJ5eGTyj
 JdPJVzzPBH319iCMZ1olqo/h5er148aYL16ga7w6w9pqhPuxGud30BFf8SHQ8F1R
 NIZiu6O3L2ge0RLb/8wxukFkDz3R1gZBWeTLxLEymTJG3TaA3uIByOI6UO03zgW/
 QBbNLr7ndkIcm8E31hAWamGQy+EAXj1/e5GYREvhhHOwUV+y/E1FTrrdwtT4GA0S
 tBYACfeCbOojsA==
 =WqFq
 -----END PGP SIGNATURE-----

Merge tag 'locking-futex-2025-07-29' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip

Pull futex updates from Thomas Gleixner:

 - Switch the reference counting to a RCU based per-CPU reference to
   address a performance bottleneck vs the single instance rcuref
   variant

 - Make the futex selftest build on 32-bit architectures which only
   support 64-bit time_t, e.g. RISCV-32

 - Cleanups and improvements in selftests and futex bench

* tag 'locking-futex-2025-07-29' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
  selftests/futex: Fix spelling mistake "Succeffuly" -> "Successfully"
  selftests/futex: Define SYS_futex on 32-bit architectures with 64-bit time_t
  perf bench futex: Remove support for IMMUTABLE
  selftests/futex: Remove support for IMMUTABLE
  futex: Remove support for IMMUTABLE
  futex: Make futex_private_hash_get() static
  futex: Use RCU-based per-CPU reference counting instead of rcuref_t
  selftests/futex: Adapt the private hash test to RCU related changes
2025-07-29 14:39:42 -07:00
..
functional selftests/futex: Fix spelling mistake "Succeffuly" -> "Successfully" 2025-07-22 11:18:43 +02:00
include Update for the futex subsystem: 2025-07-29 14:39:42 -07:00
Makefile selftests/futex: don't redefine .PHONY targets (all, clean) 2024-05-31 14:37:04 -06:00
README
run.sh treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 152 2019-05-30 11:26:32 -07:00

Futex Test
==========
Futex Test is intended to thoroughly test the Linux kernel futex system call
API.

Functional tests shall test the documented behavior of the futex operation
code under test. This includes checking for proper behavior under normal use,
odd corner cases, regression tests, and abject abuse and misuse.

Futextest will also provide example implementation of mutual exclusion
primitives. These can be used as is in user applications or can serve as
examples for system libraries. These will likely be added to either a new lib/
directory or purely as header files under include/, I'm leaning toward the
latter.

Quick Start
-----------
# make
# ./run.sh

Design and Implementation Goals
-------------------------------
o Tests should be as self contained as is practical so as to facilitate sharing
  the individual tests on mailing list discussions and bug reports.
o The build system shall remain as simple as possible, avoiding any archive or
  shared object building and linking.
o Where possible, any helper functions or other package-wide code shall be
  implemented in header files, avoiding the need to compile intermediate object
  files.
o External dependencies shall remain as minimal as possible. Currently gcc
  and glibc are the only dependencies.
o Tests return 0 for success and < 0 for failure.

Output Formatting
-----------------
Test output shall be easily parsable by both human and machine. Title and
results are printed to stdout, while intermediate ERROR or FAIL messages are
sent to stderr. Tests shall support the -c option to print PASS, FAIL, and
ERROR strings in color for easy visual parsing. Output shall conform to the
following format:

test_name: Description of the test
	Arguments: arg1=val1 #units specified for clarity where appropriate
	ERROR: Description of unexpected error
	 FAIL: Reason for test failure
	# FIXME: Perhaps an " INFO: informational message" option would be
	#        useful here. Using -v to toggle it them on and off, as with -c.
	# there may be multiple ERROR or FAIL messages
Result: (PASS|FAIL|ERROR)

Naming
------
o FIXME: decide on a sane test naming scheme.  Currently the tests are named
  based on the primary futex operation they test. Eventually this will become a
  problem as we intend to write multiple tests which collide in this namespace.
  Perhaps something like "wait-wake-1" "wait-wake-2" is adequate, leaving the
  detailed description in the test source and the output.

Coding Style
------------
o The Futex Test project adheres to the coding standards set forth by Linux
  kernel as defined in the Linux source Documentation/process/coding-style.rst.