docs: Document TIMEOUT_MULTIPLIER for raising test timeouts

Our test infrastructure allows you to set the TIMEOUT_MULTIPLIER
environment variable to raise the test timeouts if you're building
for a slow environment.  (scripts/mtest2make.py reads it and sets the
meson test -t argument accordingly.)

Document this so it's not a secret feature only known to a select
few.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
Message-id: 20260427161132.1463385-1-peter.maydell@linaro.org

diff --git a/docs/devel/testing/main.rst b/docs/devel/testing/main.rst
index 0662766b5c915bde9964ec4e45897083f9839cf1..b01a3748656f3f7e204b285e55ab7218e8615144 100644 (file)
--- a/docs/devel/testing/main.rst
+++ b/docs/devel/testing/main.rst
@@ -52,6 +52,21 @@ Before running tests, it is best to build QEMU programs first. Some tests
 expect the executables to exist and will fail with obscure messages if they
 cannot find them.
 
+The timeouts for QEMU tests are set conservatively so you should not
+in general find that tests time out. However, if you are running on a
+particularly slow host or with a slow configuration (such as a build
+with the clang address-sanitizer enabled) you can globally raise all
+the timeouts, by setting the ``TIMEOUT_MULTIPLIER`` environment
+variable. For instance:
+
+.. code::
+
+ TIMEOUT_MULTIPLIER=3 make check
+
+will run with all the default timeouts multiplied by three. You can
+also disable timeouts entirely by setting the environment variable to
+``0``.
+
 .. _unit-tests:
 
 Unit tests
@@ -959,6 +974,9 @@ Python. You can run the functional tests simply by executing:
 
 See :ref:`checkfunctional-ref` for more details.
 
+The harness for the functional tests also honours the
+``TIMEOUT_MULTIPLIER`` environment variable.
+
 .. _checktcg-ref:
 
 Testing with "make check-tcg"