1 files changed, 68 insertions, 33 deletions
diff --git a/share/man/man9/random_harvest.9 b/share/man/man9/random_harvest.9
index 7b72f3e..cb89a05 100644
--- a/share/man/man9/random_harvest.9
+++ b/share/man/man9/random_harvest.9
@@ -1,5 +1,5 @@
 .\"
-.\" Copyright (c) 2002 Mark R V Murray
+.\" Copyright (c) 2002-2015 Mark R V Murray
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 6, 2002
+.Dd June 30, 2015
 .Dt RANDOM_HARVEST 9
 .Os
 .Sh NAME
@@ -35,59 +35,93 @@
 .In sys/types.h
 .In sys/random.h
 .Ft void
-.Fo random_harvest
+.Fo random_harvest_direct
+.Fa "void *entropy"
+.Fa "u_int size"
+.Fa "u_int bits"
+.Fa "enum esource source"
+.Fc
+.Ft void
+.Fo random_harvest_fast
+.Fa "void *entropy"
+.Fa "u_int size"
+.Fa "u_int bits"
+.Fa "enum esource source"
+.Fc
+.Ft void
+.Fo random_harvest_queue
 .Fa "void *entropy"
 .Fa "u_int size"
 .Fa "u_int bits"
-.Fa "u_int frac"
 .Fa "enum esource source"
 .Fc
 .Sh DESCRIPTION
 The
-.Fn random_harvest
-function is used by device drivers
+.Fn random_harvest_*
+functions are used by device drivers
 and other kernel processes to pass data
 that is considered (at least partially) stochastic
 to the entropy device.
 .Pp
-The caller should pass a pointer (to no more than 16 bytes) of
-the
+The caller should pass
+a pointer pointing to the
 .Dq random
 data in
 .Fa entropy .
 The argument
 .Fa size
 contains the number of bytes pointed to.
-The caller should
+The
+.Fa source
+is chosen from one of
+the values enumerated in
+.Pa sys/dev/random.h .
+and is used to indicate the source of the entropy.
+.Pp
+The
+.Fo random_harvest_direct
+.Fc
+variant is used
+for early harvesting
+before any multitasking
+is enabled.
+.Pp
+The
+.Fn random_harvest_fast
+variant is used
+by sources that
+should not take
+a performance hit
+from harvesting,
+as they are high-rate
+sources.
+Some entropy is sacrificed,
+but the hig rate of supply
+will compensate for this.
+.Pp
+The
+.Fn random_harvest_queue
+variant is used
+for general harvesting
+and is the default
+choice for most entropy sources
+such as interrupts
+or console events.
+.Pp
+The
+.Fa bits
+argument is only used
+by the deprecated Yarrow algorithm.
+For compatibility,
+the caller should
 .Em "very conservatively"
 estimate the number of random bits
 in the sample,
 and pass this in
-.Fa bits
-or
-.Fa frac .
-If the estimated number of bits per sample is an integer, then
-.Fa bits
-is used, and
-.Fa frac
-is 0.
-Otherwise,
-for low-entropy samples,
-.Dq fractional
-entropy can be supplied in
-.Fa frac .
-(This is considered to be
-.Fa frac /
-1024 bits of entropy.)
-The
-.Fa source
-is chosen from
-.Dv RANDOM_WRITE , RANDOM_KEYBOARD , RANDOM_MOUSE , RANDOM_NET
-and
-.Dv RANDOM_INTERRUPT ,
-and is used to indicate the source of the entropy.
+.Fa bits .
 .Pp
-Interrupt harvesting has been simplified
+Interrupt harvesting has been
+in part simplified simplified
 for the kernel programmer.
 If a device driver registers an interrupt handler
 with
@@ -101,6 +135,7 @@ bit in the
 .Fa flags
 argument to have that interrupt source
 be used for entropy harvesting.
+This should be done wherever practicable.
 .Sh SEE ALSO
 .Xr random 4 ,
 .Xr BUS_SETUP_INTR 9