Skip to contentSkip to conversation

hwrng: document the quality field

PATCH In review Michael S. Tsirkin 2 participants 2 messages Sep 25, 2018 – Oct 5, 2018

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 hwrng: document the quality field

quality field is currently documented as being 'per mill'. In fact the math involved is:

add_hwgenerator_randomness((void *)rng_fillbuf, rc,
rc * current_quality * 8 >> 10);

thus the actual definition is "bits of entropy per 1024 bits of input".

The current documentation seems to have confused multiple people in the past, let's fix the documentation to match code.

An alternative is to change core to match driver expectations, replacing

	rc * current_quality * 8 >> 10
with
	rc * current_quality / 1000

but that has performance costs, so probably isn't a good option.

Fixes 0f734e6e768 ("hwrng: add per-device entropy derating")

---

 drivers/char/hw_random/core.c | 4 ++--
 include/linux/hw_random.h     | 3 ++-
 2 files changed, 4 insertions(+), 3 deletions(-)
drivers/char/hw_random/core.c +2 -2
index aaf9e5afaad4..95be7228f327 100644
@@ -44,10 +44,10 @@ static unsigned short default_quality; /* = 0; default to "off" */
 
 module_param(current_quality, ushort, 0644);
 MODULE_PARM_DESC(current_quality,
-		 "current hwrng entropy estimation per mill");
+		 "current hwrng entropy estimation per 1024 bits of input");
 module_param(default_quality, ushort, 0644);
 MODULE_PARM_DESC(default_quality,
-		 "default entropy content of hwrng per mill");
+		 "default entropy content of hwrng per 1024 bits of input");
 
 static void drop_current_rng(void);
 static int hwrng_init(struct hwrng *rng);
include/linux/hw_random.h +2 -1
index bee0827766a3..c0b93e0ff0c0 100644
@@ -33,7 +33,8 @@
  *			and max is a multiple of 4 and >= 32 bytes.
  * @priv:		Private data, for use by the RNG driver.
  * @quality:		Estimation of true entropy in RNG's bitstream
- *			(per mill).
+ *			(in bits of entropy per 1024 bits of input;
+ *			valid values: 1 to 1024, or 0 for unknown).
  */
 struct hwrng {
 	const char *name;
Signature · 1 line
MST
maintainer
#1 lore raw
Quoted 20 lines · Michael S. Tsirkin

quality field is currently documented as being 'per mill'. In fact the math involved is:

add_hwgenerator_randomness((void *)rng_fillbuf, rc,
rc * current_quality * 8 >> 10);

thus the actual definition is "bits of entropy per 1024 bits of input".

The current documentation seems to have confused multiple people in the past, let's fix the documentation to match code.

An alternative is to change core to match driver expectations, replacing

	rc * current_quality * 8 >> 10
with
	rc * current_quality / 1000

but that has performance costs, so probably isn't a good option.

Fixes 0f734e6e768 ("hwrng: add per-device entropy derating")
Quoted 6 lines

---

 drivers/char/hw_random/core.c | 4 ++--
 include/linux/hw_random.h     | 3 ++-
 2 files changed, 4 insertions(+), 3 deletions(-)

Patch applied. Thanks.

Signature · 3 lines
Email: Herbert Xu <[email protected]>
Home Page: http://gondor.apana.org.au/~herbert/
PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt