| Message ID | 20210710005929.1702431-5-mathieu.poirier@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | virtio: Add vhost-user based RNG | expand |
Mathieu Poirier <mathieu.poirier@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.poirier@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
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 \ + ...
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.poirier@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 -- 2.25.1