On 11/09/2025 18:00, Collin Funk wrote:
Pádraig Brady <[email protected]> writes:
On 11/09/2025 00:31, Collin Funk wrote:
Pádraig Brady <[email protected]> writes:
This is useful to give better test coverage at least,
and may be useful for users who already may have
GLIBC_TUNABLES defined to tune their environment,
avoiding CPU throttling for example.
Probably worth documenting this behavior.
Although it is hard to imagine that many people use the glibc.cpu
tunables to disable capabilities that their hardware supports, one might
be surprised that Coreutils checks them unless it is documented.
I might do a "Hardware acceleration" section in the texinfo that
documents the supported accelerations in cksum, wc, sha*sum etc,
the configure options (--with-linux-crypto, --with-openssl).
I could also mention there the honored env vars.
That sounds like a good idea to me.
Attached.
cheers,
Padraig
From 2ccc172e8affb9de948b6897dc5c613d52aa5ed9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Tue, 16 Sep 2025 22:51:20 +0100
Subject: [PATCH] doc: add hardware acceleration configuration docs
* NEWS: Mention the new GLIBC_TUNABLES feature.
* doc/coreutils.texi (Hardware Acceleration): A new node
detailing the build time and run time configuration options.
---
NEWS | 6 +++++
doc/coreutils.texi | 65 ++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 71 insertions(+)
diff --git a/NEWS b/NEWS
index 972bdfbad..ce4335071 100644
--- a/NEWS
+++ b/NEWS
@@ -127,6 +127,12 @@ GNU coreutils NEWS -*- outline -*-
Also on other systems the full set of supported baud rates
is determined at build time if possible.
+ Commands that support hardware acceleration like cksum and wc
+ can now disable this acceleration at runtime through the
+ standard GLIBC_TUNABLES environment variable. For example
+ to disable the use of AVX512 instructions in cksum, you can:
+ export GLIBC_TUNABLES='glibc.cpu.hwcaps=-AVX512F'
+
** Changes to conform better to POSIX.1-2024
readlink now defaults to being verbose if the POSIXLY_CORRECT
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 5853a4728..df0b9216e 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -225,6 +225,7 @@ Common Options
* Backup options:: Backup options
* Block size:: Block size
* Floating point:: Floating point number representation
+* Hardware Acceleration:: Hardware acceleration configuration
* Signal specifications:: Specifying signals
* Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax
* Random sources:: Sources of random data
@@ -809,6 +810,7 @@ Items applicable to all programs:
* Exit status:: Indicating program success or failure.
* Floating point:: Floating point number representation.
+* Hardware Acceleration:: Hardware acceleration configuration
* Standards conformance:: Conformance to the POSIX standard.
* Multi-call invocation:: Multi-call program invocation.
@end menu
@@ -1576,6 +1578,69 @@ they treat @samp{3.14} like @samp{3,14} if the current locale uses
comma as a decimal point.
+@node Hardware Acceleration
+@section Hardware Acceleration Configuration
+@cindex hardware acceleration
+
+The @command{cksum} and @command{wc} utilities can use non-generic hardware
+acceleration when available, which can significantly speed up processing. This
+acceleration can be implemented internally within the coreutils themselves,
+delegated to libraries like OpenSSL, or handled by the Linux kernel.
+
+@subsection Build Configuration
+
+By default, the build enables hardware acceleration detection for all supported
+features. This applies to both the accelerated code used internally within
+coreutils and the accelerated code used in external libraries.
+
+The detection performed internally within coreutils can be overridden at build
+time using various configure variables, which currently include:
+
+@table @samp
+@item utils_cv_vmull_intrinsic_exists
+@item utils_cv_pclmul_intrinsic_exists
+@item utils_cv_avx2_pclmul_intrinsic_exists
+@item utils_cv_avx512_pclmul_intrinsic_exists
+@item utils_cv_avx2_intrinsic_exists
+@end table
+
+External library detection is automatic for OpenSSL, so you must use the
+@samp{--with-openssl=no} configure option to disable this if desired.
+Conversely, the Linux kernel cryptographic API is not used automatically and
+must be explicitly enabled with the @samp{--with-linux-crypto} configure
+option.
+
+@subsection Runtime Configuration
+
+The usual method for runtime configuration of hardware detection is through
+environment variables, since you typically want to configure hardware
+interactions quite broadly. Note that these environment variables are not
+specific to coreutils, but coreutils will honor them when set.
+
+For example, the following commands would disable hardware acceleration both
+within coreutils and in libcrypto (if used) on x86_64, ARM, and AArch64
+platforms:
+
+@example
+export OPENSSL_ia32cap='0x0'
+export OPENSSL_armcap='0x0'
+export GLIBC_TUNABLES='glibc.cpu.hwcaps=-AVX512F,-AVX2,-AVX,-PMULL'
+@end example
+
+The @option{--debug} option is available on all utilities supporting
+hardware acceleration and will report the current acceleration mode in use.
+For example:
+
+@example
+$ wc -l --debug /dev/null >/dev/null
+wc: using avx2 hardware support
+
+$ cksum --debug /dev/null >/dev/null
+cksum: avx512 support not detected
+cksum: avx2 support not detected
+cksum: using pclmul hardware support
+@end example
+
@node Standards conformance
@section Standards conformance
--
2.50.1
