[PATCH 12/32] docs: formatdomain-devices: Split out <lease>

Start splitting out part of <devices> into smaller sections. Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/formatdomain-devices-lease.rst | 35 +++++++++++++++++++++++++++ docs/formatdomain-devices.rst | 37 +---------------------------- docs/meson.build | 1 + 3 files changed, 37 insertions(+), 36 deletions(-) create mode 100644 docs/formatdomain-devices-lease.rst diff --git a/docs/formatdomain-devices-lease.rst b/docs/formatdomain-devices-lease.rst new file mode 100644 index 0000000000..722f9a629f --- /dev/null +++ b/docs/formatdomain-devices-lease.rst @@ -0,0 +1,35 @@ +:anchor:`<a id="elementsLease"/>` + +Device leases +~~~~~~~~~~~~~ + +When using a lock manager, it may be desirable to record device leases against a +VM. The lock manager will ensure the VM won't start unless the leases can be +acquired. + +:: + + ... + <devices> + ... + <lease> + <lockspace>somearea</lockspace> + <key>somekey</key> + <target path='/some/lease/path' offset='1024'/> + </lease> + ... + </devices> + ... + +``lockspace`` + This is an arbitrary string, identifying the lockspace within which the key + is held. Lock managers may impose extra restrictions on the format, or length + of the lockspace name. +``key`` + This is an arbitrary string, uniquely identifying the lease to be acquired. + Lock managers may impose extra restrictions on the format, or length of the + key. +``target`` + This is the fully qualified path of the file associated with the lockspace. + The offset specifies where the lease is stored within the file. If the lock + manager does not require an offset, just pass 0. diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst index e65020330d..d704cbe05b 100644 --- a/docs/formatdomain-devices.rst +++ b/docs/formatdomain-devices.rst @@ -44,42 +44,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` .. include:: formatdomain-devices-address.rst .. include:: formatdomain-devices-virtio.rst .. include:: formatdomain-devices-controller.rst - -:anchor:`<a id="elementsLease"/>` - -Device leases -~~~~~~~~~~~~~ - -When using a lock manager, it may be desirable to record device leases against a -VM. The lock manager will ensure the VM won't start unless the leases can be -acquired. - -:: - - ... - <devices> - ... - <lease> - <lockspace>somearea</lockspace> - <key>somekey</key> - <target path='/some/lease/path' offset='1024'/> - </lease> - ... - </devices> - ... - -``lockspace`` - This is an arbitrary string, identifying the lockspace within which the key - is held. Lock managers may impose extra restrictions on the format, or length - of the lockspace name. -``key`` - This is an arbitrary string, uniquely identifying the lease to be acquired. - Lock managers may impose extra restrictions on the format, or length of the - key. -``target`` - This is the fully qualified path of the file associated with the lockspace. - The offset specifies where the lease is stored within the file. If the lock - manager does not require an offset, just pass 0. +.. include:: formatdomain-devices-lease.rst :anchor:`<a id="elementsHostDev"/>` diff --git a/docs/meson.build b/docs/meson.build index fb65cef2e5..0609bfa6a8 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -129,6 +129,7 @@ docs_rst_files = [ 'formatdomain-devices-address.rst', 'formatdomain-devices-virtio.rst', 'formatdomain-devices-controller.rst', + 'formatdomain-devices-lease.rst', ] }, { 'name': 'hacking' }, -- 2.26.2