[v4,01/16] Document ioemu MiniOS stubdomain protocol

Commit Message

Marek Marczykowski-Górecki Jan. 15, 2020, 2:39 a.m. UTC

Add documentation based on reverse-engineered toolstack-ioemu stubdomain
protocol.

Signed-off-by: Marek Marczykowski-Górecki <[e-mail]>
---
 docs/misc/stubdom.txt | 53 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+)

Comments

Jason Andryuk Jan. 20, 2020, 6:30 p.m. UTC | #1

On Tue, Jan 14, 2020 at 9:41 PM Marek Marczykowski-Górecki
<[e-mail]> wrote:
>
> Add documentation based on reverse-engineered toolstack-ioemu stubdomain
> protocol.
>
> Signed-off-by: Marek Marczykowski-Górecki <[e-mail]>
> ---
>  docs/misc/stubdom.txt | 53 ++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 53 insertions(+)
>
> diff --git a/docs/misc/stubdom.txt b/docs/misc/stubdom.txt
> index de7b6c7..4c524f2 100644
> --- a/docs/misc/stubdom.txt
> +++ b/docs/misc/stubdom.txt
> @@ -23,6 +23,59 @@ and http://wiki.xen.org/wiki/Device_Model_Stub_Domains for more

<snip>

> +Startup:
> +1. PV stubdomain is started with ioemu-stubdom.gz kernel and no initrd
> +2. stubdomain initialize relevant devices
> +2. stubdoma signal readiness by writing "running" to /local/domain/<stubdom-id>/device-model/<target-id>/state xenstore path

s/stubdoma/stubdomain/

Numbering is off - 2 is duplicated.

> +3. now stubdomain is considered running

I'm not familiar with mini-os stubdom to review the content you've written.

Regards,
Jason

Patch

diff --git a/docs/misc/stubdom.txt b/docs/misc/stubdom.txt
index de7b6c7..4c524f2 100644
--- a/docs/misc/stubdom.txt
+++ b/docs/misc/stubdom.txt
@@ -23,6 +23,59 @@  and http://wiki.xen.org/wiki/Device_Model_Stub_Domains for more
 information on device model stub domains
 
 
+Toolstack to MiniOS ioemu stubdomain protocol
+---------------------------------------------
+
+This section describe communication protocol between toolstack and
+qemu-traditional running in MiniOS stubdomain. The protocol include
+expectations of both qemu and stubdomain itself.
+
+Setup (done by toolstack, expected by stubdomain):
+ - Block devices for target domain are connected as PV disks to stubdomain,
+   according to configuration order, starting with xvda
+ - Network devices for target domain are connected as PV nics to stubdomain,
+   according to configuration order, starting with 0
+ - if graphics output is expected, VFB and VKB devices are set for stubdomain
+   (its backend is responsible for exposing them using appropriate protocol
+   like VNC or Spice)
+ - other target domain's devices are not connected at this point to stubdomain
+   (may be hot-plugged later)
+ - QEMU command line (space separated arguments) is stored in
+   /vm/<target-uuid>/image/dmargs xenstore path
+ - target domain id is stored in /local/domain/<stubdom-id>/target xenstore path
+?? - bios type is stored in /local/domain/<target-id>/hvmloader/bios
+ - stubdomain's console 0 is connected to qemu log file
+ - stubdomain's console 1 is connected to qemu save file (for saving state)
+ - stubdomain's console 2 is connected to qemu save file (for restoring state)
+ - next consoles are connected according to target guest's serial console configuration
+
+Startup:
+1. PV stubdomain is started with ioemu-stubdom.gz kernel and no initrd
+2. stubdomain initialize relevant devices
+2. stubdoma signal readiness by writing "running" to /local/domain/<stubdom-id>/device-model/<target-id>/state xenstore path
+3. now stubdomain is considered running
+
+Runtime control (hotplug etc):
+Toolstack can issue command through xenstore. The sequence is (from toolstack POV):
+1. Write parameter to /local/domain/<stubdom-id>/device-model/<target-id>/parameter.
+2. Write command to /local/domain/<stubdom-id>/device-model/<target-id>/command.
+3. Wait for command result in /local/domain/<stubdom-id>/device-model/<target-id>/state (command specific value).
+4. Write "running" back to /local/domain/<stubdom-id>/device-model/<target-id>/state.
+
+Defined commands:
+ - "pci-ins" - PCI hot plug, results:
+   - "pci-inserted" - success
+   - "pci-insert-failed" - failure
+ - "pci-rem" - PCI hot remove, results:
+   - "pci-removed" - success
+   - ??
+ - "save" - save domain state to console 1, results:
+   - "paused" - success
+ - "continue" - resume domain execution, after loading state from console 2 (require -loadvm command argument), results:
+   - "running" - success
+
+
+
                                    PV-GRUB
                                    =======