Mathieu Poirier <mathieu.poir...@linaro.org> writes:
> Add description and example for the vhost-user based RNG implementation. > Tailored on Viresh Kumar's vhost-user-i2c documentation. > > Signed-off-by: Mathieu Poirier <mathieu.poir...@linaro.org> > --- > docs/tools/index.rst | 1 + > docs/tools/vhost-user-rng.rst | 74 +++++++++++++++++++++++++++++++++++ > 2 files changed, 75 insertions(+) > create mode 100644 docs/tools/vhost-user-rng.rst > > diff --git a/docs/tools/index.rst b/docs/tools/index.rst > index d923834a7398..9d80fa89eceb 100644 > --- a/docs/tools/index.rst > +++ b/docs/tools/index.rst > @@ -15,5 +15,6 @@ Contents: > qemu-nbd > qemu-pr-helper > qemu-trace-stap > + vhost-user-rng > virtfs-proxy-helper > virtiofsd > diff --git a/docs/tools/vhost-user-rng.rst b/docs/tools/vhost-user-rng.rst > new file mode 100644 > index 000000000000..7f69d7bb3c58 > --- /dev/null > +++ b/docs/tools/vhost-user-rng.rst > @@ -0,0 +1,74 @@ > +QEMU vhost-user-rng - RNG emulation backend > +=========================================== > + > +Synopsis > +-------- > + > +**vhost-user-rng** [*OPTIONS*] > + > +Description > +----------- > + > +This program is a vhost-user backend that emulates a VirtIO random number > +generator (RNG). It uses the host's random number generator pool, > +/dev/urandom by default but configurable at will, to satisfy requests from > +guests. > + > +This program is designed to work with QEMU's ``-device > +vhost-user-rng-pci`` but should work with any virtual machine monitor > +(VMM) that supports vhost-user. See the Examples section below. > + > +Options > +------- > + > +.. program:: vhost-user-rng > + > +.. option:: -h, --help > + > + Print help. > + > +.. option:: -v, --verbose > + > + Increase verbosity of output > + > +.. option:: -s, --socket-path=PATH > + > + Listen on vhost-user UNIX domain socket at PATH. Incompatible with --fd. > + > +.. option:: -f, --fd=FDNUM > + > + Accept connections from vhost-user UNIX domain socket file descriptor > FDNUM. > + The file descriptor must already be listening for connections. > + Incompatible with --socket-path. > + > +.. option:: -p, --period > + > + Rate, in milliseconds, at which the RNG hardware can generate random data. > + Used in conjunction with the --max-bytes option. > + > +.. option:: -m, --max-bytes > + > + In conjuction with the --period parameter, provides the maximum number of > byte > + per milliseconds a RNG device can generate. > + > +Examples > +-------- > + > +The daemon should be started first: > + > +:: > + > + host# vhost-user-rng --socket-path=rng.sock --period=1000 --max-bytes=4096 > + > +The QEMU invocation needs to create a chardev socket the device can > +use to communicate as well as share the guests memory over a memfd. > + > +:: > + > + host# qemu-system > \ > + -chardev socket,path=$(PATH)/rng.sock,id=rng0 > \ > + -device vhost-user-rng-pci,chardev=rng0 > \ > + -m 4096 > \ > + -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on > \ > + -numa node,memdev=mem > \ > + ... Would it be worth pointing out how a guest may consume the randomness? I appreciate this will be guest specific but currently I'm struggling how to consume the entropy in a Linux guest. cat /dev/urandom > /dev/null didn't seem to cause any to be consumed above what was during boot up. -- Alex Bennée
