DESCRIPTIONThe bbcheck utility is is tool for quickly and simply analysing the output of a BitBabbler RNG at various bitrates. It can run tests on multiple devices in parallel, and highlight the best and worst results from a series of tests on each device.
OPTIONSThe following options are available:
- -s, --scan
Scan the system for available BitBabbler devices.
- -i, --device-id=id
Select a BitBabbler device to analyse by its unique ID. If no devices are
explicitly specified then the default is to use all of them which are present
when testing begins. This option may be passed multiple times to test multiple
devices. The id may be the device serial number, or its logical address
in the form:
or on systems where knowing the USB topology is supported, its physical address in the form
For a logical address the busnum part is optional, but if devnum is not unique across all buses, then exactly which device will be selected if it is not fully specified becomes a matter of chance. All of the available IDs which can be used to refer to a device will be reported by the --scan option. Bus, device, and port numbers are expected to be decimal integers.
Since bbcheck only operates on available devices and does not wait for a device to be hotplugged, it is an error to specify an ID which does not refer to a device currently available in the system.
- -r, --bitrate=min[:max]
Select the bitrate, or range of bitrates, to analyse (in bits per second).
The available bitrates are determined by an integer clock divider, so not every
rate is exactly achievable. An unsupported rate will be rounded up to the next
higher rate. For convenience the rate may be followed by an SI multiplier (eg.
2.5M for 2500000). If a colon separated range is specified, then all possible
bitrates between min and max will be tested.
- -b, --bytes=n
The number of bytes to analyse for each test. A suffix of 'k', 'M', or 'G' will
multiply n by the respective power of two.
- -B, --block-size=bytes
The block size used for folding. This size must be a multiple of 2^n, where n
is the level of folding used (ie. it must be able to fold the desired number of
times without any remainder). A suffix of 'k', 'M', or 'G' will scale
bytes by the respective power of two. Default is 64kB. A larger block
size will mix samples taken over a longer timescale. At high bitrates this will
mean more of the lower frequency noise can be factored into each sample where
otherwise the higher frequency noise would dominate. The optimum block size
(beyond which any change to the result is negligible) for any given bitrate is
still a matter that is ripe for further study. See the --fold option
below for a more detailed description of folding.
- -A, --all-results
Show all the test results, not just the final summary.
Don't colour the final results. By default the four best results will be
highlighted bright-green, dull-green, yellow, and orange, while the worst
result will be highlighted in red. This option suppresses the output of
terminal escape codes which are responsible for that.
- -v, --verbose
Make more noise about what is going on internally. If used (once) with the
--scan option this will show more information about each device, but
otherwise it's mostly only information useful for debugging. It may be passed
multiple times to get swamped with even more information.
- -?, --help
Show a shorter version of all of this, which may fit on a single page.
Report the bbcheck release version.
Per device optionsThe following options may be used multiple times to individually configure each device when more than one BitBabbler is available. If passed before any --device-id option, then they set new default values which will apply to every device. If passed after one of those options they will only be applied to the immediately preceding device.
Override the calculated value for the USB latency timer. This controls the
maximum amount of time that the device will wait if there is any data in its
internal buffer (but less than a full packet), before sending it to the host.
If this timer expires before a packet can be filled, then a short packet will
be sent to the host. The default value is chosen to ensure that we do not
send more short packets than necessary for the selected bitrate, since that
will increase the number of packets sent and the amount of CPU time which must
be spent processing them, to transfer the same amount of data.
Unless you are experimenting with changes to the low level code, there is probably no reason to ever use this option to override the latency manually.
- -f, --fold=n
Set the number of times to fold the BitBabbler output before analysing it.
Each fold will take the first half of the block that was read and XOR it with
the bits in the second half. This will halve the throughput, but concentrate
the available entropy more densely into the bits that remain.
There are two main things this is expected to do based on the BitBabbler design. It will better mix the low-frequency noise that is captured with that of the higher frequencies, allowing it to sample at higher bitrates without narrowing the noise bandwidth available to influence adjacent bits. It will help to break up any transient local correlations that might occur in the physical processes from which ambient environmental noise is collected.
Folding should never reduce the real entropy of each sample, but when all is working exactly as it should, it may not do anything to increase it either. Mathematically, an XOR summation is expected to exponentially smooth any bias in a stream of independent bits, with the result having at least as much entropy as the least predictable of either of the two inputs (in the same way that a one time pad is no less secure despite the plaintext having much less entropy than the pad does).
Select a subset of the generators on BitBabbler devices with multiple entropy
sources. The argument is a bitmask packed from the LSB, with each bit position
controlling an individual source, enabling it when set to 1. As a special
case for bbcheck, if a mask of 0 is used, then the tests will be
performed on each source unit individually. A mask of 16 (0x10) will
first test each source individually, and then all of of them enabled together