Basic usage and example invocation.
Signed-off-by: Alex Bennée alex.bennee@linaro.org --- docs/tools/index.rst | 1 + docs/tools/vhost-user-rpmb.rst | 102 +++++++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+) create mode 100644 docs/tools/vhost-user-rpmb.rst
diff --git a/docs/tools/index.rst b/docs/tools/index.rst index 232ce9f3e463..488784b3bf1f 100644 --- a/docs/tools/index.rst +++ b/docs/tools/index.rst @@ -15,3 +15,4 @@ Contents: qemu-trace-stap virtfs-proxy-helper virtiofsd + vhost-user-rpmb diff --git a/docs/tools/vhost-user-rpmb.rst b/docs/tools/vhost-user-rpmb.rst new file mode 100644 index 000000000000..40d5d3bceb7c --- /dev/null +++ b/docs/tools/vhost-user-rpmb.rst @@ -0,0 +1,102 @@ +QEMU vhost-user-rpmb - rpmb emulation backend +============================================= + +Synopsis +-------- + +**vhost-user-rpmb** [*OPTIONS*] + +Description +----------- + +This program is a vhost-user backed that emulates a VirtIO Replay +Protected Memory Block device. These are usually special partitions +that are part of a flash device that offer protection against reply +attacks. They are used to store secure information in a way that is +hard to tamper with. + +This program is designed to work with QEMU's ``--device +vhost-user-rpmb-pci`` but should work with any virtual machine +monitor (VMM) that supports vhost-user. See the Examples section +below. + +This program requires a backing store to persist any data programmed +into the device. The spec supports devices up 32Mb in size. For the +daemon this is simply a raw file of the appropriate size. To program +the device it needs to have a key. This can either be programmed by +the guest at the start or come from a key file supplied to the daemon. + +Options +------- + +.. program:: vhost-user-rpmb + +.. option:: -h, --help + + Print help. + +.. option:: -V, --version + + Print version. + +.. option:: -v, --verbose + + Increase verbosity of output + +.. option:: --debug + + Enable debug output. + +.. option:: --socket-path=PATH + + Listen on vhost-user UNIX domain socket at PATH. Incompatible with --fd. + +.. option:: --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:: --flash-path=PATH + + Path to the backing store for the flash image, can be up to 32Mb in size. + +.. option:: --key-path=PATH + + Path to the backing store for the key of 32 bytes. + +.. option:: --key-set + + Treat the value of key-path as set meaning the key cannot be + reprogrammed by the guest. + +.. option:: --initial-counter=N + + Set the initial value of the devices write count. It is + incremented by each write operation. + +Examples +-------- + +The daemon should be started first: + +:: + + host# vhost-user-rpmb --socket-path=vrpmb.sock \ + --flash-path=flash.img \ + --key-path=key --key-set \ + --initial-counter=1234 + +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=vrpmb.sock,id=vrpmb \ + -device vhost-user-rpmb-pci,chardev=vrpmb,id=rpmb \ + -m 4096 \ + -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on \ + -numa node,memdev=mem \ + ... +