From ea7c0b280c76e0b570cf473b35bc4b9a7f837760 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?=
 <marmarek@invisiblethingslab.com>
Date: Mon, 1 May 2017 02:52:50 +0200
Subject: [PATCH] mgmt1: clarify devices handling, add options support

- devices can be attached with some options (like 'ro=True' for block
  devices)
- clarify that backend domain and device ident is separated with '+'
  (':' is not allowed in qrexec call argument)
- clarify how to attach devices "persistently"
---
 services/mgmt1.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/services/mgmt1.md b/services/mgmt1.md
index 274a7a90..3e2951a4 100644
--- a/services/mgmt1.md
+++ b/services/mgmt1.md
@@ -57,10 +57,10 @@ to set the policy using current mechanism.
 | `mgmt.vm.firewall.SetPolicy`          | vm        | -         | `accept|drop`                             | -                                                         |
 | `mgmt.vm.firewall.GetPolicy`          | vm        | -         | -                                         | `accept|drop`                                             |
 | `mgmt.vm.firewall.Reload`             | vm        | -         | -                                         | -                                                         | force reload firewall without changing any rule
-| `mgmt.vm.device.<class>.Attach`       | vm        | device    | options                                   | -                                                         | optional options given in `key=value` format, separated with spaces
-| `mgmt.vm.device.<class>.Detach`       | vm        | device    | -                                         | -                                                         |
+| `mgmt.vm.device.<class>.Attach`       | vm        | device    | options                                   | -                                                         | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=yes` to "persistently" attach the device (default is temporary)
+| `mgmt.vm.device.<class>.Detach`       | vm        | device    | -                                         | -                                                         | `device` is in form `<backend-name>+<device-ident>`
 | `mgmt.vm.device.<class>.List`         | vm        | -         | -                                         | `<device> <options>\n`                                    |
-| `mgmt.vm.device.<class>.Available`    | vm        | -         | -                                         | `<device>\n`                                              |
+| `mgmt.vm.device.<class>.Available`    | vm        | device-ident | -                                         | `<device-ident> <properties> description=<desc>\n`        | optional service argument may be used to get info about a single device, <br/>optional (device class specific) properties are in `key=value` form, <br/>`description` must be the last one and is the only one allowed to contain spaces; <br/>options can include `persistent=yes` for "persistently" attached devices (default is temporary)
 | `mgmt.vm.microphone.Attach`           | vm        | -         | -                                         | -                                                         |
 | `mgmt.vm.microphone.Detach`           | vm        | -         | -                                         | -                                                         |
 | `mgmt.pool.List`                      | `dom0`    | -         | -                                         | `<pool>\n`                                                |
@@ -161,6 +161,9 @@ does not by itself support translation.
 ## General notes
 
 - there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call
+- generally actions `*.List` return a list of objects and have "object
+  identifier" as first word in a row. Such action can be also called with "object
+  identifier" in argument to get only a single entry (in the same format).
 
 ## TODO