From 0800455fb6619c45f5313b3dbc74db88ec4922a4 Mon Sep 17 00:00:00 2001
From: Xi Ruoyao <xry111@xry111.site>
Date: Sun, 18 Feb 2024 15:34:58 +0800
Subject: [PATCH] Glibc: Re-organize test failures and mention how to rule out
 timed out tests

Glibc tests occansionally fail due to a timeout because:

1. The hardware is slower than the developers expected.
2. Some tests use multiple or even all CPU cores internally, for e.g.
   with 8 active CPU cores we may end up running 8 tests (due to -j8)
   each of them uses 8 cores in the worst case, resulting a severe
   congestion.

I'm almost sure nptl/tst-thread-affinity* are cases of 2.

Let's document how to rule out the timed out tests instead of making the
list of known failures longer and longer.
---
 chapter08/glibc.xml | 44 ++++++++++++++++++++++----------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/chapter08/glibc.xml b/chapter08/glibc.xml
index e8432fe19..10fccb3a9 100644
--- a/chapter08/glibc.xml
+++ b/chapter08/glibc.xml
@@ -163,34 +163,34 @@ esac</userinput></screen>
         is known to fail in the LFS chroot environment.</para>
       </listitem>
 
-      <listitem>
-        <para>Three <emphasis>nptl/tst-thread-affinity*</emphasis>
-        tests are known to fail.</para>
-      </listitem>
-
-<!-- Did not fail with glibc-2.38
-      <listitem>
-        <para><emphasis>misc/tst-ttyname</emphasis>
-        is known to fail in the LFS chroot environment.</para>
-      </listitem>
--->
-
-      <!-- https://sourceware.org/pipermail/libc-alpha/2022-August/141567.html -->
-      <listitem>
-        <para>The <emphasis>stdlib/tst-arc4random-thread</emphasis>
-        test is known to fail if the host kernel is relatively old.</para>
-      </listitem>
-
       <listitem>
         <para>Some tests, for example
-        <emphasis>nss/tst-nss-files-hosts-multi</emphasis>,
-        are known to fail on relatively slow systems due to an internal
-        timeout.</para>
+        <emphasis>nss/tst-nss-files-hosts-multi</emphasis> and
+        <emphasis>nptl/tst-thread-affinity*</emphasis>
+        are known to fail due to a timeout (especially when the system is
+        relatively slow and/or running the test suite with multiple
+        parallel make jobs).  These tests can be identified with:</para>
+
+        <!-- TODO: Using nodump for freeze.  Change it to role="test" after
+             12.1 release so jhalfs can list these in the log.  -->
+        <screen role="nodump"><userinput>grep "Timed out" -l $(find -name \*.out)</userinput></screen>
+
+        <para>It's possible to re-run a single test with enlarged timeout
+        with
+        <command>TIMEOUTFACTOR=<replaceable>&lt;factor&gt;</replaceable>
+        make test t=<replaceable>&lt;test name&gt;</replaceable></command>.
+        For example, <command>TIMEOUTFACTOR=10 make test
+        t=nss/tst-nss-files-hosts-multi</command> will re-run
+        <emphasis>nss/tst-nss-files-hosts-multi</emphasis> with ten times
+        the original timeout.</para>
       </listitem>
 
       <listitem>
         <para>Additionally, some tests may fail with a relatively old CPU
-        model or host kernel version.</para>
+        model (for example
+        <emphasis>elf/tst-cpu-features-cpuinfo</emphasis>) or host kernel
+        version (for example
+        <emphasis>stdlib/tst-arc4random-thread</emphasis>).</para>
       </listitem>
     </itemizedlist>