[Xen-devel] [PATCH 3/4] docs: add pvscsi.txt

[Olaf Hering <olaf@xxxxxxxxx>]

Signed-off-by: Olaf Hering <olaf@xxxxxxxxx>
Cc: Ian Campbell <ian.campbell@xxxxxxxxxx>
Cc: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
Cc: Jan Beulich <jbeulich@xxxxxxxx>
Cc: Keir Fraser <keir@xxxxxxx>
Cc: Tim Deegan <tim@xxxxxxx>
---
 docs/misc/pvscsi.txt | 147 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 147 insertions(+)

diff --git a/docs/misc/pvscsi.txt b/docs/misc/pvscsi.txt
new file mode 100644
index 0000000..2af050f
--- /dev/null
+++ b/docs/misc/pvscsi.txt
@@ -0,0 +1,147 @@
+. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+PVSCSI
+
+== Overview ==
+
+PVSCSI allows to assing a "physical" SCSI device from dom0 to a domU. The 
device
+is not limited to be a native SCSI device. Everything visible as SCSI device in
+dom0 can be used. Currently PVSCSI is only available in Linux dom0 and domU.
+
+== TODO ===
+
+How to do live migration?
+ - pdev will likely be evaluated again on the target host if it came from
+   domU.cfg. But what about pdev from 'xl scsi-attach pdev vdev'? Its required
+   to adjust h:c:t:l on the target host.
+
+Implement checks for duplicate pdev assignments?
+ - Not sure if SCSI devices can be shared. Will the state be consistent during
+   concurrent access? Should the host admin assume cooperative access from
+   multiple domUs?
+ - The easiest way would be to do nothing and assume the host admin knows what
+   to do.
+
+How to handle FIXME in libxl_retrieve_domain_configuration?
+ - "MERGE(vscsi, vscsis, COMPARE_DEVID, {});", when does this code run?
+ 
+Implement libvirt integration.
+ - Is the API used by xl usable for libvirt?
+ - How does libvirt assign a raw SCSI device?
+   Jim said:
+    > vscsi=[ '/dev/sda,0:1:2:3', '4:3:2:1,1:1:1:1,feature-host' ]
+    In libvirt-speak, this is SCSI host device assignment
+    http://libvirt.org/formatdomain.html#elementsHostDev
+    Here's the SCSI example
+      <devices>
+       <hostdev mode='subsystem' type='scsi' sgio='filtered' rawio='yes'>
+        <source>
+         <adapter name='scsi_host0'/>
+         <address type='scsi' bus='0' target='0' unit='0'/>
+        </source>
+        <readonly/>
+        <address type='drive' controller='0' bus='0' target='0' unit='0'/>
+       </hostdev>
+      ...
+      </devices>
+    I suppose 'feature-host' maps to attributes such as 'sgio' and 'rawio'.
+    The source element describes the SCSI device as seen from the host.
+
+
+== History ==
+
+Support for PVSCSI was added to the classic xenlinux kernel and to xend in
+xen-3.3 in 2008. Support for PVSCSI was added to the upstream pvops kernel 3.18
+in 2014. Backends exists just for Linux. A frontend exists for Linux, and maybe
+for FreeBSD according to google.
+
+
+== Config Format ==
+
+The domU.cfg syntax is "vscsi=[ 'pdev,vdev[,option]' ]". pdev is the dom0 
device
+in either /dev/$device or pHOST:CHANNEL:TARGET:LUN notation.  vdev is the domU
+device in vHOST:CHANNEL:TARGET:LUN notation. 'option' lists additional flags.
+Currently only the value "feature-host" is recognized. SCSI command emulation 
in
+backend driver is bypassed when "feature-host" is specified.
+
+
+== Xenstore Format ==
+
+The backend driver uses a single_host:many_devices notation to manage domU
+devices. Everything is stored in /local/domain/0/backend/vscsi/. The xenstore
+layout looks like this:
+
+    <domid>/<vhost>/feature-host = "0"
+    <domid>/<vhost>/frontend = "/local/domain/<domid>/device/vscsi/0"
+    <domid>/<vhost>/frontend-id = "<domid>"
+    <domid>/<vhost>/online = "1"
+    <domid>/<vhost>/state = "4"
+    <domid>/<vhost>/vscsi-devs/dev-0/p-dev = "8:0:2:1"
+    <domid>/<vhost>/vscsi-devs/dev-0/state = "4"
+    <domid>/<vhost>/vscsi-devs/dev-0/v-dev = "0:0:0:0"
+    <domid>/<vhost>/vscsi-devs/dev-1/p-dev = "8:0:2:2"
+    <domid>/<vhost>/vscsi-devs/dev-1/state = "4"
+    <domid>/<vhost>/vscsi-devs/dev-1/v-dev = "0:0:1:0"
+
+The frontend driver maintains its state in /local/domain/<domid>/device/vscsi/.
+
+    <vhost>/backend = "/local/domain/0/backend/vscsi/<domid>/<vhost>"
+    <vhost>/backend-id = "0"
+    <vhost>/event-channel = "20"
+    <vhost>/ring-ref = "43"
+    <vhost>/state = "4"
+    <vhost>/vscsi-devs/dev-0/state = "4"
+    <vhost>/vscsi-devs/dev-1/state = "4"
+
+In addition to the entries for backend and frontend these flags are stored for
+the toolstack:
+
+    <domid>/<vhost>/vscsi-devs/dev-1/p-devname = "/dev/$device"
+
+
+== Backend - Frontend Protocol ==
+
+To create a vhost along with a device:
+    <domid>/<vhost>/feature-host = "0"
+    <domid>/<vhost>/frontend = "/local/domain/<domid>/device/vscsi/0"
+    <domid>/<vhost>/frontend-id = "<domid>"
+    <domid>/<vhost>/online = "1"
+    <domid>/<vhost>/state = "1"
+    <domid>/<vhost>/vscsi-devs/dev-0/p-dev = "8:0:2:1"
+    <domid>/<vhost>/vscsi-devs/dev-0/state = "1"
+    <domid>/<vhost>/vscsi-devs/dev-0/v-dev = "0:0:0:0"
+Wait for <domid>/<vhost>/state + <domid>/<vhost>/vscsi-devs/dev-0/state become 
4
+
+To add another device to a vhost:
+    <domid>/<vhost>/state = "7"
+    <domid>/<vhost>/vscsi-devs/dev-1/p-dev = "8:0:2:2"
+    <domid>/<vhost>/vscsi-devs/dev-1/state = "1"
+    <domid>/<vhost>/vscsi-devs/dev-1/v-dev = "0:0:1:0"
+Wait for <domid>/<vhost>/state + <domid>/<vhost>/vscsi-devs/dev-1/state become 
4
+
+To remove a device from a vhost:
+    <domid>/<vhost>/state = "7"
+    <domid>/<vhost>/vscsi-devs/dev-1/state = "5"
+Wait for <domid>/<vhost>/state to become 4
+Wait for <domid>/<vhost>/vscsi-devs/dev-1/state become 6
+Remove <domid>/<vhost>/vscsi-devs/dev-1/{state,p-dev,v-dev,p-devname}
+Remove <domid>/<vhost>/vscsi-devs/dev-1/
+
+
+== Interface in xl ==
+
+xl scsi-attach domid <PhysDevice> <VirtDevice>[,<option>]
+xl scsi-detach domid <VirtDevice>
+xl scsi-list domid [domid, ...]
+
+
+== Interface in libxl ==
+
+To be defined so that both xl and libvirt pass in the same data.
+
+
+== Interface in libvirt ==
+
+Has yet to be found.
+
+. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+# vim: tw=80 et ts=4

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel