[entropy_src/doc] Clarify purpose of CONF.THRESHOLD_SCOPE field

hw/ip/entropy_src/README.md

@@ -52,7 +52,7 @@ These tests include:
 The Repetition Count and Adaptive Proportion test are specifically recommended by SP 800-90B, and are implemented in accordance with those recommendations.
 In FIPS/CC compliant mode, all checks except the Repetition Count test are performed on a fixed window of data of configurable size, by default consisting of 2048 bits each.
 Per the definition in SP 800-90B, the Repetition Count test does not operate on a fixed window.
-The repetition count test fails if any sequence of bits continuously asserts the same value for too many samples, as determined by the programmable threshold, regardless of whether that sequence crosses any window boundaries.
+The Repetition Count Test fails if any sequence of bits continuously asserts the same value for too many samples, as determined by the programmable threshold, regardless of whether that sequence crosses any window boundaries.
 The thresholds for these tests should be chosen to achieve a low false-positive rate (α) given a conservative estimate of the manufacturing tolerances of the PTRNG noise source.
 The combined choice of threshold and window size then determine the false-negative rate (β), or the probability of missing statistical defects at any particular magnitude.
 

hw/ip/entropy_src/data/entropy_src.hjson

@@ -486,10 +486,15 @@
           name: "THRESHOLD_SCOPE",
           mubi: true,
           desc: '''
-                This field controls the scope (either by-line or by-sum) of the health checks.
-                If set to `kMultiBitBool4True`, the Adaptive Proportion and Markov Tests will accumulate all RNG input lines into a single score, and thresholds will be applied to the sum all the entropy input lines.
-                If set to `kMultiBitBool4False`, the RNG input lines are all scored individually.
-                A statistical deviation in any one input line, be it due to coincidence or failure, will force rejection of the sample, and count toward the total alert count.
+                This field controls the scope (either by-line or by-sum) of the Adaptive Proportion and the Markov health tests.
+                It has no effect if !!CONF.RNG_BIT_ENABLE is set to `kMultiBitBool4True`, i.e., if the ENTROPY_SRC is operating in single-channel mode.
+
+                If set to `kMultiBitBool4False`, the minimum/maximum results of the individual, line-based tests are taken and compared against the configured thresholds.
+                This allows detecting failures of individual noise source channels in multi-channel mode.
+                If set to `kMultiBitBool4True`, the individual, line-based test results are summed up and then compared against the configured thresholds.
+                This allows lowering the likelihood for coincidental test failures (higher alpha).
+
+                Note that the value of THRESHOLD_SCOPE needs to be considered when defining the health test thresholds.
                 '''
           resval: false
         },
@@ -576,7 +581,7 @@
                 Note that the number of tested bits taken by the conditioner to produce a seed is equal to the window size x symbol size, where the symbol size is 1 in single-channel mode.
                 The only exception is the startup seed which is produced using the bits of two subsequent windows, i.e., 2 x window size x symbol tested bits.
 
-                Note that NIST SP 800-90B (Table 2) requires the adaptive proportion test to be run on 1024 or 512 samples in single-channel or multi-channel mode, respectively (see !!ENTROPY_SRC.RNG_BIT_ENABLE).
+                Note that NIST SP 800-90B (Table 2) requires the Adaptive Proportion Test to be run on 1024 or 512 samples in single-channel or multi-channel mode, respectively (see !!ENTROPY_SRC.RNG_BIT_ENABLE).
                 The startup tests must be run on at least 1024 consecutive samples (see Section 4.3 Requirements for Health Tests of NIST SP 800-90B) and this block always uses two subsequent windows for startup health testing.
                 The use of window sizes below 512 samples is thus not recommended as this may not comply with NIST SP 800-90B.
                 '''
@@ -597,7 +602,7 @@
       ]
     },
     { name: "REPCNT_THRESHOLDS",
-      desc: "Repetition count test thresholds register",
+      desc: "Repetition Count Test thresholds register",
       swaccess: "rw",
       hwaccess: "hrw",
       hwext: "true",
@@ -608,7 +613,7 @@
       fields: [
         { bits: "15:0",
           name: "FIPS_THRESH",
-          desc: '''This is the threshold size for the repetition count health test.
+          desc: '''This is the threshold for the Repetition Count Test.
                    This value is used in FIPS mode.
                    This register must be written before the module is enabled.
                    Writing to this register will only update the register if the
@@ -619,7 +624,7 @@
         }
         { bits: "31:16",
           name: "BYPASS_THRESH",
-          desc: '''This is the threshold size for the repetition count health test
+          desc: '''This is the threshold for the Repetition Count Test
                    running in bypass mode. This mode is active after reset for the
                    first and only test run, or when this mode is programmed by firmware.
                    This register must be written before the module is enabled.
@@ -632,7 +637,7 @@
       ]
     },
     { name: "REPCNTS_THRESHOLDS",
-      desc: "Repetition count symbol test thresholds register",
+      desc: "Repetition Count Symbol Test thresholds register",
       swaccess: "rw",
       hwaccess: "hrw",
       hwext: "true",
@@ -643,7 +648,7 @@
       fields: [
         { bits: "15:0",
           name: "FIPS_THRESH",
-          desc: '''This is the threshold size for the repetition count symbol health test.
+          desc: '''This is the threshold for the Repetition Count Symbol Test.
                    This value is used in FIPS mode.
                    This register must be written before the module is enabled.
                    Writing to this register will only update the register if the
@@ -654,7 +659,7 @@
         }
         { bits: "31:16",
           name: "BYPASS_THRESH",
-          desc: '''This is the threshold size for the repetition count symbol health test
+          desc: '''This is the threshold for the Repetition Count Symbol Test
                    running in bypass mode. This mode is active after reset for the
                    first and only test run, or when this mode is programmed by firmware.
                    This register must be written before the module is enabled.
@@ -678,7 +683,7 @@
       fields: [
         { bits: "15:0",
           name: "FIPS_THRESH",
-          desc: '''This is the threshold size for the adaptive proportion health test.
+          desc: '''This is the threshold for the Adaptive Proportion Test.
                    This value is used in FIPS mode.
                    This register must be written before the module is enabled.
                    Writing to this register will only update the register if the
@@ -689,7 +694,7 @@
         }
         { bits: "31:16",
           name: "BYPASS_THRESH",
-          desc: '''This is the threshold size for the adaptive proportion health test
+          desc: '''This is the threshold for the Adaptive Proportion Test
                    running in bypass mode. This mode is active after reset for the
                    first and only test run, or when this mode is programmed by firmware.
                    This register must be written before the module is enabled.
@@ -713,7 +718,7 @@
       fields: [
         { bits: "15:0",
           name: "FIPS_THRESH",
-          desc: '''This is the threshold size for the adaptive proportion health test.
+          desc: '''This is the threshold for the Adaptive Proportion Test.
                    This value is used in FIPS mode.
                    This register must be written before the module is enabled.
                    Writing to this register will only update the register if the
@@ -724,7 +729,7 @@
         }
         { bits: "31:16",
           name: "BYPASS_THRESH",
-          desc: '''This is the threshold size for the adaptive proportion health test
+          desc: '''This is the threshold for the Adaptive Proportion Test
                    running in bypass mode. This mode is active after reset for the
                    first and only test run, or when this mode is programmed by firmware.
                    This register must be written before the module is enabled.
@@ -934,13 +939,13 @@
             { value: "0",
               name: "REPCNT_HI",
               desc: '''
-                    Repetition count test high watermark.
+                    Repetition Count Test high watermark.
                     '''
             },
             { value: "1",
               name: "REPCNTS_HI",
               desc: '''
-                    Repetition count symbol test high watermark.
+                    Repetition Count Symbol Test high watermark.
                     '''
             },
             { value: "2",
@@ -1009,7 +1014,7 @@
       ]
     },
     { name:     "REPCNT_TOTAL_FAILS",
-      desc:     "Repetition count test failure counter register",
+      desc:     "Repetition Count Test failure counter register",
       swaccess: "ro",
       hwaccess: "hwo",
       hwext: "true",
@@ -1023,7 +1028,7 @@
       ]
     },
     { name:     "REPCNTS_TOTAL_FAILS",
-      desc:     "Repetition count symbol test failure counter register",
+      desc:     "Repetition Count Symbol Test failure counter register",
       swaccess: "ro",
       hwaccess: "hwo",
       hwext: "true",
@@ -1139,7 +1144,7 @@
             Alert threshold register
 
             This register determines during how many subsequent health test windows one or more health test failures can occur before a recoverable alert is raised and the ENTROPY_SRC block stops operating.
-            Note that continuous health tests such as the repetition count test or the repetition count symbol test can trigger multiple test failures within a single window.
+            Note that continuous health tests such as the Repetition Count Test or the Repetition Count Symbol Test can trigger multiple test failures within a single window.
             Each symbol for which at least one continuous health test fails counts separately towards the threshold.
             In case the configured threshold is reached, firmware needs to disable/re-enable the block to restart operation including the startup health testing.
 
@@ -1175,7 +1180,7 @@
 
             This register holds the total number of subsequent health test windows during which one or more health test failures occurred.
             For information on which health tests failed specifically, refer to !!ALERT_FAIL_COUNTS and !!EXTHT_FAIL_COUNTS.
-            Note that continuous health tests such as the repetition count test or the repetition count symbol test can trigger multiple test failures within a single window.
+            Note that continuous health tests such as the Repetition Count Test or the Repetition Count Symbol Test can trigger multiple test failures within a single window.
             Each symbol for which at least one continuous health test fails is counted separately.
 
             If the value of this register reaches the value configured in the !!ALERT_THRESHOLD register, a recoverable alert is raised and the ENTROPY_SRC block stops operating.

hw/ip/entropy_src/data/entropy_src_testplan.hjson

@@ -350,7 +350,7 @@
       name: cont_ht_cg
       desc: '''
             Covers a range of thresholds and configurations for the continuous health tests: REPCNT
-            (the repetition count test), and REPCNTS (the symbol based repetition count test).
+            (the Repetition Count Test), and REPCNTS (the Repetition Count Symbol Test).
             The primary cover points are the test_type (REPCNT vs. REPCNTS), the pass or fail value
             of the test, and the "score". The score is a generalization of the numerical value of
             the test output, which accounts for the fact it is far more likely to see high values

hw/ip/entropy_src/doc/programmers_guide.md

@@ -99,10 +99,10 @@ To select which specific bit should be used, the `RNG_BIT_SEL` field in the [`CO
 
 When ENTROPY_SRC is configured in RNG bit mode, only a subset of the health tests are applicable and the health test thresholds need to be set to account for this.
 For this reason, the thresholds for both the bypass and the FIPS values must be set accordingly.
-The repetition count test, Markov test and adaptive proportion test can all still be performed on a single lane.
+The Repetition Count Test, Markov test and Adaptive Proportion Test can all still be performed on a single lane.
 However, to get the same number of entropy bits, we now must collect four times as many individual symbols from the PTRNG.
 This should be considered when choosing the health test thresholds, whereas the health test window size is adjusted internally.
-In contrast, the symbol repetition count test and the bucket test are not applicable to a single lane.
+In contrast, the Repetition Count Symbol Test and the bucket test are not applicable to a single lane.
 They need to be disabled by setting the corresponding thresholds to the maximum value.
 The `THRESHOLD_SCOPE` field in the [`CONF`](registers.md#conf) register is also not applicable to the single lane mode and must be set to `kMultiBitBool4False`.