s390x: improve documentation
cover s390x: improve documentation
The documentation for the s390x system emulation target still has quite a bit of room for improvement, so I started adding some device documentation.
I'm not quite happy with the long command/output lines in the 3270 and vfio-ccw sections, but don't know how to make that more readable. Suggestions welcome.
Cornelia Huck (3):
docs/s390x: document the virtual css
docs/s390x: document 3270
docs/s390x: document vfio-ccw
docs/system/s390x/3270.rst | 32 +++++++++++++++++ docs/system/s390x/css.rst | 64 ++++++++++++++++++++++++++++++++++ docs/system/s390x/vfio-ccw.rst | 58 ++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 3 ++ 4 files changed, 157 insertions(+) create mode 100644 docs/system/s390x/3270.rst create mode 100644 docs/system/s390x/css.rst create mode 100644 docs/system/s390x/vfio-ccw.rst
Signature · 1 line
2.21.3
PATCH 1/3 docs/s390x: document the virtual css
Add some hints about "devno" rules.
--- docs/system/s390x/css.rst | 64 ++++++++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 1 + 2 files changed, 65 insertions(+) create mode 100644 docs/system/s390x/css.rst
docs/system/s390x/css.rst new file +64 -0
@@ -0,0 +1,64 @@ +The virtual channel subsystem +============================= + +QEMU implements a virtual channel subsystem with subchannels, (mostly +functionless) channel paths, and channel devices (virtio-ccw, 3270, and +devices passed via vfio-ccw). It supports multiple subchannel sets (MSS) and +multiple channel subsystems extended (MCSS-E). + +All channel devices support the ``devno`` property, which takes a parameter +in the form ``<cssid>.<ssid>.<device number>``. + +The default channel subsystem image id (``<cssid>``) is ``0xfe``. Devices in +there will show up in channel subsystem image ``0`` to guests that do not +enable MCSS-E. Note that devices with a different cssid will not be visible +if the guest OS does not enable MCSS-E (which is true of all supported guest +operating systems today). + +Supported values for the subchannel set id (``<ssid>``) range from ``0-3``. +Devices with a ssid that is not ``0`` will not be visible if the guest OS +does not enable MSS (any Linux version that supports virtio also enables MSS). +Any device may be put into any subchannel set, there is no restriction by +device type. + +The device number can range from ``0-0xffff``. + +If the ``devno`` property is not specified for a device, QEMU will choose the +next free device number in subchannel set 0, skipping to the next subchannel +set if no more device numbers are free. + +QEMU places a device at the first free subchannel in the specified subchannel +set. If a device is hotunplugged and later replugged, it may appear at a +different subchannel. (This is similar to how z/VM works.) + + +Examples +-------- + +* a virtio-net device, cssid/ssid/devno automatically assigned:: + + -device virtio-net-ccw + + In a Linux guest (without default devices and no other devices specified + prior to this one), this will show up as ``0.0.0000`` under subchannel + ``0.0.0000``. + +* a virtio-rng device in subchannel set ``0``:: + + -device virtio-rng-ccw,devno=fe.0.0042 + + If added to the same Linux guest as above, it would show up as ``0.0.0042`` + under subchannel ``0.0.0001``. + +* a virtio-gpu device in subchannel set ``2``:: + + -device virtio-gpu-ccw,devno=fe.2.1111 + + If added to the same Linux guest as above, it would show up as ``0.2.1111`` + under subchannel ``0.2.0000``. + +* a virtio-mouse device in a non-standard channel subsystem:: + + -device virtio-mouse-ccw,devno=2.0.2222 + + This would not show up in a standard Linux guest.
docs/system/target-s390x.rst +1 -0
@@ -23,6 +23,7 @@ or vfio-ap is also available. .. toctree:: s390x/vfio-ap + s390x/css Architectural features ======================
Signature · 1 line
2.21.3
Re: [PATCH 1/3] docs/s390x: document the virtual css
Quoted 1 line · Cornelia Huck
Add some hints about "devno" rules.
Thanks a lot for doing this, some documentation in this area is extremely useful!
Quoted 47 lines
Signed-off-by Cornelia Huck <[email protected]>--- docs/system/s390x/css.rst | 64 ++++++++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 1 + 2 files changed, 65 insertions(+) create mode 100644 docs/system/s390x/css.rstdocs/system/s390x/css.rst new file +34
-0@@ -0,0 +1,64 @@ +The virtual channel subsystem +============================= + +QEMU implements a virtual channel subsystem with subchannels, (mostly +functionless) channel paths, and channel devices (virtio-ccw, 3270, and +devices passed via vfio-ccw). It supports multiple subchannel sets (MSS) and +multiple channel subsystems extended (MCSS-E). + +All channel devices support the ``devno`` property, which takes a parameter +in the form ``<cssid>.<ssid>.<device number>``. + +The default channel subsystem image id (``<cssid>``) is ``0xfe``. Devices in +there will show up in channel subsystem image ``0`` to guests that do not +enable MCSS-E. Note that devices with a different cssid will not be visible +if the guest OS does not enable MCSS-E (which is true of all supported guest +operating systems today). + +Supported values for the subchannel set id (``<ssid>``) range from ``0-3``. +Devices with a ssid that is not ``0`` will not be visible if the guest OS +does not enable MSS (any Linux version that supports virtio also enables MSS). +Any device may be put into any subchannel set, there is no restriction by +device type. + +The device number can range from ``0-0xffff``. + +If the ``devno`` property is not specified for a device, QEMU will choose the +next free device number in subchannel set 0, skipping to the next subchannel +set if no more device numbers are free. + +QEMU places a device at the first free subchannel in the specified subchannel +set. If a device is hotunplugged and later replugged, it may appear at a +different subchannel. (This is similar to how z/VM works.) + +
docs/system/s390x/css.rst line 44
Quoted 10 lines
docs/system/s390x/css.rst new file +10
-0+Examples +-------- + +* a virtio-net device, cssid/ssid/devno automatically assigned:: + + -device virtio-net-ccw + + In a Linux guest (without default devices and no other devices specified + prior to this one), this will show up as ``0.0.0000`` under subchannel + ``0.0.0000``.
Maybe mention the QEMU side again, e.g. that when you run "info qtree" in the HMP monitor, you see the device with dev_id = "fe.0.0000".
docs/system/s390x/css.rst line 51
Quoted 6 lines
docs/system/s390x/css.rst new file +6
-0+* a virtio-rng device in subchannel set ``0``:: + + -device virtio-rng-ccw,devno=fe.0.0042 + + If added to the same Linux guest as above, it would show up as ``0.0.0042`` + under subchannel ``0.0.0001``.
Does "same" matter here? Otherwise, maybe just say "to a Linux guest" ?
docs/system/s390x/css.rst line 58
Quoted 6 lines
docs/system/s390x/css.rst new file +6
-0+* a virtio-gpu device in subchannel set ``2``:: + + -device virtio-gpu-ccw,devno=fe.2.1111 + + If added to the same Linux guest as above, it would show up as ``0.2.1111`` + under subchannel ``0.2.0000``.
Dito.
docs/system/s390x/css.rst line 64
Quoted 5 lines
docs/system/s390x/css.rst new file +5
-0+* a virtio-mouse device in a non-standard channel subsystem:: + + -device virtio-mouse-ccw,devno=2.0.2222 + + This would not show up in a standard Linux guest.
Ok ... and what happens if you use devno=0.0.1234 ? Will that then show up under fe.0.1234 in the guest??
Thomas
Re: [PATCH 1/3] docs/s390x: document the virtual css
Quoted 15 lines · On Fri, 15 May 2020 09:04:13 +0200 Thomas Huth <[email protected]> wrote:
docs/system/s390x/css.rst line 44
Quoted 10 lines · Cornelia Huck
docs/system/s390x/css.rst new file +10
-0+Examples +-------- + +* a virtio-net device, cssid/ssid/devno automatically assigned:: + + -device virtio-net-ccw + + In a Linux guest (without default devices and no other devices specified + prior to this one), this will show up as ``0.0.0000`` under subchannel + ``0.0.0000``.Maybe mention the QEMU side again, e.g. that when you run "info qtree" in the HMP monitor, you see the device with
dev_id= "fe.0.0000".
Yes, that's a good idea.
Quoted 9 lines
docs/system/s390x/css.rst line 51
Quoted 7 lines
docs/system/s390x/css.rst new file +6
-0+* a virtio-rng device in subchannel set ``0``:: + + -device virtio-rng-ccw,devno=fe.0.0042 + + If added to the same Linux guest as above, it would show up as ``0.0.0042`` + under subchannel ``0.0.0001``.Does "same" matter here? Otherwise, maybe just say "to a Linux guest" ?
I wanted to provide the subchannel number in my examples as well. As QEMU always picks the first free one (and you cannot specify it manually), I wanted to make the examples build upon each other.
Quoted 9 lines
docs/system/s390x/css.rst line 58
Quoted 7 lines
docs/system/s390x/css.rst new file +6
-0+* a virtio-gpu device in subchannel set ``2``:: + + -device virtio-gpu-ccw,devno=fe.2.1111 + + If added to the same Linux guest as above, it would show up as ``0.2.1111`` + under subchannel ``0.2.0000``.Dito.
dito :)
Quoted 9 lines
docs/system/s390x/css.rst line 64
Quoted 6 lines
docs/system/s390x/css.rst new file +5
-0+* a virtio-mouse device in a non-standard channel subsystem:: + + -device virtio-mouse-ccw,devno=2.0.2222 + + This would not show up in a standard Linux guest.Ok ... and what happens if you use devno=0.0.1234 ? Will that then show up under fe.0.1234 in the guest??
That won't show up in the guest, either -- do you think I should add an example for that as well?
Re: [PATCH 1/3] docs/s390x: document the virtual css
Quoted 4 lines · Cornelia Huck
Quoted 1 line · On Fri, 15 May 2020 09:04:13 +0200 Thomas Huth <[email protected]> wrote:
On 05/05/2020 15.50, Cornelia Huck wrote:
[...]
Quoted 8 lines
Quoted 5 lines
Review
Quoted 2 lines
(quoted diff) +2
-0+ + This would not show up in a standard Linux guest.Ok ... and what happens if you use devno=0.0.1234 ? Will that then show up under fe.0.1234 in the guest??
That won't show up in the guest, either -- do you think I should add an example for that as well?
It could help to clarify the question that came to my mind here. And what would happen if the guest supported MCSS-E ? Would it then show up as fe.0.1234 indeed?
Thomas
Re: [PATCH 1/3] docs/s390x: document the virtual css
Quoted 12 lines · On Fri, 15 May 2020 10:57:26 +0200 Thomas Huth <[email protected]> wrote:
Quoted 4 lines · Cornelia Huck
Quoted 1 line · On Fri, 15 May 2020 09:04:13 +0200 Thomas Huth <[email protected]> wrote:
On 05/05/2020 15.50, Cornelia Huck wrote:
[...]
Quoted 6 lines
Quoted 5 lines
Review
Quoted 2 lines
(quoted diff) +2
-0+ + This would not show up in a standard Linux guest.Ok ... and what happens if you use devno=0.0.1234 ? Will that then show up under fe.0.1234 in the guest??
Quoted 6 lines
Quoted 2 lines
That won't show up in the guest, either -- do you think I should add an example for that as well?
It could help to clarify the question that came to my mind here. And what would happen if the guest supported MCSS-E ? Would it then show up as fe.0.1234 indeed?
No, it would show up as 0.0.1234, and the devices in the default css (0xfe) would show up as fe.x.yyyy.
But I have not seen a Linux kernel with support for MCSS-E in the wild :) (nor any other OS, for that matter)
PATCH 2/3 docs/s390x: document 3270
In reply to Cornelia HuckAdd some basic info how to use 3270 devices.
--- docs/system/s390x/3270.rst | 32 ++++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 1 + 2 files changed, 33 insertions(+) create mode 100644 docs/system/s390x/3270.rst
docs/system/s390x/3270.rst new file +32 -0
@@ -0,0 +1,32 @@ +3270 devices +============ + +With the aid of the ``x3270`` emulator, QEMU provides limited support +for making a single 3270 device available to a guest. Note that this +supports basic features only. + +To provide a 3270 device to a guest, create a ``x-3270device`` linked to +a ``tn3270`` chardev. The guest will see a 3270 channel device. In order +to actually be able to use it, attach the ``x3270`` emulator to the chardev. + +Example configuration +--------------------- + +* Add a ``tn3270`` chardev and a ``x-3270device`` to the QEMU command line:: + + -chardev socket,id=char_0,host=0.0.0.0,port=23,nowait,server,tn3270 + -device x-terminal3270,chardev=char_0,devno=fe.0.000a,id=terminal_0 + +* Start the guest. In the guest, use ``chccwdev -e 0.0.000a`` to enable + the device. + +* On the host, start the ``x3270`` emulator:: + + x3270 <host>:23 + +* In the guest, locate the 3270 device node under ``/dev/3270/`` (say, + ``tty1``) and start a getty on it:: + + systemctl start [email protected] + +This should get you an addtional tty for logging into the guest.
docs/system/target-s390x.rst +1 -0
@@ -24,6 +24,7 @@ or vfio-ap is also available. .. toctree:: s390x/vfio-ap s390x/css + s390x/3270 Architectural features ======================
Signature · 1 line
2.21.3
Re: [PATCH 2/3] docs/s390x: document 3270
Quoted 15 lines · Cornelia Huck
Add some basic info how to use 3270 devices.
Signed-off-by Cornelia Huck <[email protected]>--- docs/system/s390x/3270.rst | 32 ++++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 1 + 2 files changed, 33 insertions(+) create mode 100644 docs/system/s390x/3270.rstdocs/system/s390x/3270.rst new file +0
-0
docs/system/s390x/3270.rst line 6
Quoted 6 lines
docs/system/s390x/3270.rst new file +6
-0@@ -0,0 +1,32 @@ +3270 devices +============ + +With the aid of the ``x3270`` emulator, QEMU provides limited support +for making a single 3270 device available to a guest. Note that this +supports basic features only.
The first sentence sounds somewhat confusing. Maybe rather something like:
QEMU can emulate a 3270 device attached to a guest, which then can be used with a program like ``x3270`` to get a traditional 3270 terminal for your guest.
?
docs/system/s390x/3270.rst line 8
Quoted 1 line
docs/system/s390x/3270.rst new file +1
-0+To provide a 3270 device to a guest, create a ``x-3270device`` linked to
The device is called "x-terminal3270", isn't it?
(By the way, why did we never remove the x- prefix here? Is it still experimental?)
docs/system/s390x/3270.rst line 10
Quoted 2 lines
docs/system/s390x/3270.rst new file +2
-0+a ``tn3270`` chardev. The guest will see a 3270 channel device. In order +to actually be able to use it, attach the ``x3270`` emulator to the chardev.
Can the guest only use the 3270 device if there is a x3270 attached to it? Or are you talking about the user here?
docs/system/s390x/3270.rst line 15
Quoted 4 lines
docs/system/s390x/3270.rst new file +4
-0+Example configuration +--------------------- + +* Add a ``tn3270`` chardev and a ``x-3270device`` to the QEMU command line::
"x-terminal3270" ?
docs/system/s390x/3270.rst line 18
Quoted 2 lines
docs/system/s390x/3270.rst new file +2
-0+ -chardev socket,id=char_0,host=0.0.0.0,port=23,nowait,server,tn3270 + -device x-terminal3270,chardev=char_0,devno=fe.0.000a,id=terminal_0
qemu-system-s390x: -chardev socket,id=char_0,host=0.0.0.0,port=23,nowait,server,tn3270: Failed to bind socket: Permission denied
... maybe better use a non-privileged port in the example?
Thomas
Re: [PATCH 2/3] docs/s390x: document 3270
Quoted 25 lines · On Fri, 15 May 2020 09:29:42 +0200 Thomas Huth <[email protected]> wrote:
Quoted 15 lines · Cornelia Huck
Add some basic info how to use 3270 devices.
Signed-off-by Cornelia Huck <[email protected]>--- docs/system/s390x/3270.rst | 32 ++++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 1 + 2 files changed, 33 insertions(+) create mode 100644 docs/system/s390x/3270.rstdocs/system/s390x/3270.rst new file +0
-0docs/system/s390x/3270.rst line 6
Quoted 6 lines
docs/system/s390x/3270.rst new file +6
-0@@ -0,0 +1,32 @@ +3270 devices +============ + +With the aid of the ``x3270`` emulator, QEMU provides limited support +for making a single 3270 device available to a guest. Note that this +supports basic features only.The first sentence sounds somewhat confusing. Maybe rather something like:
Quoted 3 lines
QEMU can emulate a 3270 device attached to a guest, which then can be used with a program like ``x3270`` to get a traditional 3270 terminal for your guest.
But QEMU actually relies on x3270 (or a comparable program). It only emulates the basic ccw plumbing; for the actual protocol (beyond negotiating tn3270), it relies on the emulation done by x3270.
Quoted 6 lines
?
docs/system/s390x/3270.rst line 8
Quoted 1 line
docs/system/s390x/3270.rst new file +1
-0+To provide a 3270 device to a guest, create a ``x-3270device`` linked toThe device is called "x-terminal3270", isn't it?
Yeah, no idea how I manged to mess that up.
Quoted 3 lines
(By the way, why did we never remove the x- prefix here? Is it still experimental?)
I'd still consider it experimental: only basic functionality is supported, and (more importantly), we never came up with a scheme to properly support more than one 3270 device. The usefulness of it is quite limited.
Quoted 6 lines
docs/system/s390x/3270.rst line 10
Quoted 3 lines
docs/system/s390x/3270.rst new file +2
-0+a ``tn3270`` chardev. The guest will see a 3270 channel device. In order +to actually be able to use it, attach the ``x3270`` emulator to the chardev.Can the guest only use the 3270 device if there is a x3270 attached to it? Or are you talking about the user here?
See above: x3270 does most of the heavy lifting.
Quoted 7 lines
docs/system/s390x/3270.rst line 15
Quoted 5 lines
docs/system/s390x/3270.rst new file +4
-0+Example configuration +--------------------- + +* Add a ``tn3270`` chardev and a ``x-3270device`` to the QEMU command line::"x-terminal3270" ?
Nod.
Quoted 9 lines
docs/system/s390x/3270.rst line 18
Quoted 3 lines
docs/system/s390x/3270.rst new file +2
-0+ -chardev socket,id=char_0,host=0.0.0.0,port=23,nowait,server,tn3270 + -device x-terminal3270,chardev=char_0,devno=fe.0.000a,id=terminal_0qemu-system-s390x: -chardev socket,id=char_0,host=0.0.0.0,port=23,nowait,server,tn3270: Failed to bind socket: Permission denied
... maybe better use a non-privileged port in the example?
Makes sense. This example was lifted straight from the wiki page :)
Re: [PATCH 2/3] docs/s390x: document 3270
Quoted 28 lines · Cornelia Huck
Quoted 25 lines · On Fri, 15 May 2020 09:29:42 +0200 Thomas Huth <[email protected]> wrote:
Quoted 15 lines · Cornelia Huck
Add some basic info how to use 3270 devices.
Signed-off-by Cornelia Huck <[email protected]>--- docs/system/s390x/3270.rst | 32 ++++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 1 + 2 files changed, 33 insertions(+) create mode 100644 docs/system/s390x/3270.rstdocs/system/s390x/3270.rst new file +0
-0docs/system/s390x/3270.rst line 6
Quoted 6 lines
docs/system/s390x/3270.rst new file +6
-0@@ -0,0 +1,32 @@ +3270 devices +============ + +With the aid of the ``x3270`` emulator, QEMU provides limited support +for making a single 3270 device available to a guest. Note that this +supports basic features only.The first sentence sounds somewhat confusing. Maybe rather something like:
Quoted 7 lines
Quoted 3 lines
QEMU can emulate a 3270 device attached to a guest, which then can be used with a program like ``x3270`` to get a traditional 3270 terminal for your guest.
But QEMU actually relies on x3270 (or a comparable program). It only emulates the basic ccw plumbing; for the actual protocol (beyond negotiating tn3270), it relies on the emulation done by x3270.
Ok, makes sense now. Maybe something like:
QEMU provides the possibility to connect an external 3270 terminal emulator (like ``x3270``) to a guest?
Thomas
Re: [PATCH 2/3] docs/s390x: document 3270
Quoted 33 lines · On Fri, 15 May 2020 11:14:40 +0200 Thomas Huth <[email protected]> wrote:
Quoted 32 lines · Cornelia Huck
Quoted 28 lines · On Fri, 15 May 2020 09:29:42 +0200 Thomas Huth <[email protected]> wrote:
Quoted 15 lines · Cornelia Huck
Add some basic info how to use 3270 devices.
Signed-off-by Cornelia Huck <[email protected]>--- docs/system/s390x/3270.rst | 32 ++++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 1 + 2 files changed, 33 insertions(+) create mode 100644 docs/system/s390x/3270.rstdocs/system/s390x/3270.rst new file +0
-0docs/system/s390x/3270.rst line 6
Quoted 6 lines
docs/system/s390x/3270.rst new file +6
-0@@ -0,0 +1,32 @@ +3270 devices +============ + +With the aid of the ``x3270`` emulator, QEMU provides limited support +for making a single 3270 device available to a guest. Note that this +supports basic features only.The first sentence sounds somewhat confusing. Maybe rather something like:
QEMU can emulate a 3270 device attached to a guest, which then can be used with a program like ``x3270`` to get a traditional 3270 terminal for your guest.
Quoted 8 lines
Quoted 3 lines
But QEMU actually relies on x3270 (or a comparable program). It only emulates the basic ccw plumbing; for the actual protocol (beyond negotiating tn3270), it relies on the emulation done by x3270.
Ok, makes sense now. Maybe something like:
QEMU provides the possibility to connect an external 3270 terminal emulator (like ``x3270``) to a guest?
Hm...
"QEMU supports connecting an external 3270 terminal emulator (such as ``x3270``) to make a single 3270 device available to a guest. Note that this supports basic features only."
?
Re: [PATCH 2/3] docs/s390x: document 3270
Quoted 45 lines · Cornelia Huck
Quoted 33 lines · On Fri, 15 May 2020 11:14:40 +0200 Thomas Huth <[email protected]> wrote:
Quoted 32 lines · Cornelia Huck
Quoted 28 lines · On Fri, 15 May 2020 09:29:42 +0200 Thomas Huth <[email protected]> wrote:
Quoted 15 lines · Cornelia Huck
Add some basic info how to use 3270 devices.
Signed-off-by Cornelia Huck <[email protected]>--- docs/system/s390x/3270.rst | 32 ++++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 1 + 2 files changed, 33 insertions(+) create mode 100644 docs/system/s390x/3270.rstdocs/system/s390x/3270.rst new file +0
-0docs/system/s390x/3270.rst line 6
Quoted 6 lines
docs/system/s390x/3270.rst new file +6
-0@@ -0,0 +1,32 @@ +3270 devices +============ + +With the aid of the ``x3270`` emulator, QEMU provides limited support +for making a single 3270 device available to a guest. Note that this +supports basic features only.The first sentence sounds somewhat confusing. Maybe rather something like:
QEMU can emulate a 3270 device attached to a guest, which then can be used with a program like ``x3270`` to get a traditional 3270 terminal for your guest.
Quoted 8 lines
Quoted 3 lines
But QEMU actually relies on x3270 (or a comparable program). It only emulates the basic ccw plumbing; for the actual protocol (beyond negotiating tn3270), it relies on the emulation done by x3270.
Ok, makes sense now. Maybe something like:
QEMU provides the possibility to connect an external 3270 terminal emulator (like ``x3270``) to a guest?
Quoted 7 lines
Hm...
"QEMU supports connecting an external 3270 terminal emulator (such as ``x3270``) to make a single 3270 device available to a guest. Note that this supports basic features only."
?
Yes, that sounds good!
Thanks,
Thomas
PATCH 3/3 docs/s390x: document vfio-ccw
In reply to Cornelia HuckAdd a basic example for passing a dasd via vfio-ccw.
--- docs/system/s390x/vfio-ccw.rst | 58 ++++++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 1 + 2 files changed, 59 insertions(+) create mode 100644 docs/system/s390x/vfio-ccw.rst
docs/system/s390x/vfio-ccw.rst new file +58 -0
@@ -0,0 +1,58 @@ +Subchannel passthrough via vfio-ccw +=================================== + +vfio-ccw (based upon the mediated vfio device infrastructure) allows to +make certain I/O subchannels and their devices available to a guest. The +host will not interact with those subchannels/devices any more. + +Note that while vfio-ccw should work with most non-QDIO devices, only ECKD +DASD have really been tested. + +Example configuration +--------------------- + +Step 1: configure the host device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Note: it is recommended to use the ``mdevctl`` tool for this step. If this +is not possible or wanted, follow the manual procedure below. + +* Locate the subchannel for the device (in this example, ``0.0.2b09``):: + + [root@host ~]# lscss | grep 0.0.2b09 | awk '{print $2}' + 0.0.0313 + +* Unbind the subchannel (in this example, ``0.0.0313``) from the standard + I/O subchannel driver and bind it to the vfio-ccw driver:: + + [root@host ~]# echo 0.0.0313 > /sys/bus/css/devices/0.0.0313/driver/unbind + [root@host ~]# echo 0.0.0313 > /sys/bus/css/drivers/vfio_ccw/bind + +* Create the mediated device (identified by a uuid):: + + [root@host ~]# uuidgen + 7e270a25-e163-4922-af60-757fc8ed48c6 + [root@host ~]# echo "7e270a25-e163-4922-af60-757fc8ed48c6" > /sys/bus/css/devices/0.0.0313/mdev_supported_types/vfio_ccw-io/create + +Step 2: configure QEMU +~~~~~~~~~~~~~~~~~~~~~~ + +* Reference the created mediated device and (optionally) pick a device id to + be presented in the guest (here, ``fe.0.1234``, which will end up visible + in the guest as ``0.0.1234``:: + + -device vfio-ccw,devno=fe.0.1234,sysfsdev=/sys/bus/mdev/devices/7e270a25-e163-4922-af60-757fc8ed48c6 + +* Start the guest. The device (here, ``0.0.1234``) should now be usable:: + + [root@guest ~]# lscss -d 0.0.1234 + Device Subchan. DevType CU Type Use PIM PAM POM CHPIDs + ---------------------------------------------------------------------- + 0.0.1234 0.0.0007 3390/0e 3990/e9 f0 f0 ff 1a2a3a0a 00000000 + [root@guest ~]# chccwdev -e 0.0.1234 + Setting device 0.0.1234 online + [ 197.011652] dasd-eckd 0.0.1234: A channel path to the device has become operational + [ 197.014468] dasd-eckd 0.0.1234: New DASD 3390/0E (CU 3990/01) with 10017 cylinders, 15 heads, 224 sectors + [ 197.045606] dasd-eckd 0.0.1234: DASD with 4 KB/block, 7212240 KB total size, 48 KB/track, compatible disk layout + [ 197.049034] dasda:VOL1/ 0X2B09: dasda1 + Done
docs/system/target-s390x.rst +1 -0
@@ -25,6 +25,7 @@ or vfio-ap is also available. s390x/vfio-ap s390x/css s390x/3270 + s390x/vfio-ccw Architectural features ======================
Signature · 1 line
2.21.3
Re: [PATCH 3/3] docs/s390x: document vfio-ccw
Quoted 15 lines · Cornelia Huck
Add a basic example for passing a dasd via vfio-ccw.
Signed-off-by Cornelia Huck <[email protected]>--- docs/system/s390x/vfio-ccw.rst | 58 ++++++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 1 + 2 files changed, 59 insertions(+) create mode 100644 docs/system/s390x/vfio-ccw.rstdocs/system/s390x/vfio-ccw.rst new file +0
-0
docs/system/s390x/vfio-ccw.rst line 9
Quoted 9 lines
docs/system/s390x/vfio-ccw.rst new file +9
-0@@ -0,0 +1,58 @@ +Subchannel passthrough via vfio-ccw +=================================== + +vfio-ccw (based upon the mediated vfio device infrastructure) allows to +make certain I/O subchannels and their devices available to a guest. The +host will not interact with those subchannels/devices any more. + +Note that while vfio-ccw should work with most non-QDIO devices, only ECKD +DASD have really been tested.
s/DASD/DASDs/ ?
docs/system/s390x/vfio-ccw.rst
Quoted 7 lines
docs/system/s390x/vfio-ccw.rst new file +7
-0+Example configuration +--------------------- + +Step 1: configure the host device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Note: it is recommended to use the ``mdevctl`` tool for this step.
Can you also give an example on how to use it?
docs/system/s390x/vfio-ccw.rst line 23
Quoted 7 lines
If this
docs/system/s390x/vfio-ccw.rst new file +6
-0+is not possible or wanted, follow the manual procedure below. + +* Locate the subchannel for the device (in this example, ``0.0.2b09``):: + + [root@host ~]# lscss | grep 0.0.2b09 | awk '{print $2}' + 0.0.0313
I'd remove the "[root@host ~]" part from all examples.
docs/system/s390x/vfio-ccw.rst line 35
Quoted 11 lines
docs/system/s390x/vfio-ccw.rst new file +11
-0+* Unbind the subchannel (in this example, ``0.0.0313``) from the standard + I/O subchannel driver and bind it to the vfio-ccw driver:: + + [root@host ~]# echo 0.0.0313 > /sys/bus/css/devices/0.0.0313/driver/unbind + [root@host ~]# echo 0.0.0313 > /sys/bus/css/drivers/vfio_ccw/bind + +* Create the mediated device (identified by a uuid):: + + [root@host ~]# uuidgen + 7e270a25-e163-4922-af60-757fc8ed48c6 + [root@host ~]# echo "7e270a25-e163-4922-af60-757fc8ed48c6" > /sys/bus/css/devices/0.0.0313/mdev_supported_types/vfio_ccw-io/create
Maybe break the long line with a backslash?
Quoted 7 lines
docs/system/s390x/vfio-ccw.rst new file +7
-0+Step 2: configure QEMU +~~~~~~~~~~~~~~~~~~~~~~ + +* Reference the created mediated device and (optionally) pick a device id to + be presented in the guest (here, ``fe.0.1234``, which will end up visible + in the guest as ``0.0.1234``:: +
docs/system/s390x/vfio-ccw.rst line 53
Quoted 10 lines
docs/system/s390x/vfio-ccw.rst new file +10
-0+ -device vfio-ccw,devno=fe.0.1234,sysfsdev=/sys/bus/mdev/devices/7e270a25-e163-4922-af60-757fc8ed48c6 + +* Start the guest. The device (here, ``0.0.1234``) should now be usable:: + + [root@guest ~]# lscss -d 0.0.1234 + Device Subchan. DevType CU Type Use PIM PAM POM CHPIDs + ---------------------------------------------------------------------- + 0.0.1234 0.0.0007 3390/0e 3990/e9 f0 f0 ff 1a2a3a0a 00000000 + [root@guest ~]# chccwdev -e 0.0.1234 + Setting device 0.0.1234 online
Here I'd add a sentence saying that you could run "dmesg -t" now to check the kernel log. Then omit the timestamp in the example output below, that will shorten the lines quite a bit.
docs/system/s390x/vfio-ccw.rst line 57
Quoted 4 lines
docs/system/s390x/vfio-ccw.rst new file +4
-0+ [ 197.011652] dasd-eckd 0.0.1234: A channel path to the device has become operational + [ 197.014468] dasd-eckd 0.0.1234: New DASD 3390/0E (CU 3990/01) with 10017 cylinders, 15 heads, 224 sectors + [ 197.045606] dasd-eckd 0.0.1234: DASD with 4 KB/block, 7212240 KB total size, 48 KB/track, compatible disk layout + [ 197.049034] dasda:VOL1/ 0X2B09: dasda1
Thomas
Re: [PATCH 3/3] docs/s390x: document vfio-ccw
Quoted 19 lines · On Fri, 15 May 2020 09:54:44 +0200 Thomas Huth <[email protected]> wrote:
Quoted 18 lines · Cornelia Huck
Add a basic example for passing a dasd via vfio-ccw.
Signed-off-by Cornelia Huck <[email protected]>--- docs/system/s390x/vfio-ccw.rst | 58 ++++++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 1 + 2 files changed, 59 insertions(+) create mode 100644 docs/system/s390x/vfio-ccw.rstdocs/system/s390x/vfio-ccw.rst new file +3
-0@@ -0,0 +1,58 @@ +Subchannel passthrough via vfio-ccw +=================================== +
Quoted 8 lines
docs/system/s390x/vfio-ccw.rst line 9
Quoted 6 lines
docs/system/s390x/vfio-ccw.rst new file +6
-0+vfio-ccw (based upon the mediated vfio device infrastructure) allows to +make certain I/O subchannels and their devices available to a guest. The +host will not interact with those subchannels/devices any more. + +Note that while vfio-ccw should work with most non-QDIO devices, only ECKD +DASD have really been tested.s/DASD/DASDs/ ?
I've seen 'DASD' used both as singular and as plural. Can use 'DASDs' if that is less confusing.
Quoted 10 lines
docs/system/s390x/vfio-ccw.rst
Quoted 8 lines
docs/system/s390x/vfio-ccw.rst new file +7
-0+Example configuration +--------------------- + +Step 1: configure the host device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Note: it is recommended to use the ``mdevctl`` tool for this step.Can you also give an example on how to use it?
Maybe
"To define the same device as configured below to be started automatically, use
::
[root@host ~]+ driverctl -b css set-override 0.0.0313 vfio_ccw
[root@host ~]# mdevctl define -u 7e270a25-e163-4922-af60-757fc8ed48c6 \
-p 0.0.0313 -t vfio-ccw_io -a"
Quoted 10 lines
docs/system/s390x/vfio-ccw.rst line 23
Quoted 8 lines
If this
docs/system/s390x/vfio-ccw.rst new file +6
-0+is not possible or wanted, follow the manual procedure below. + +* Locate the subchannel for the device (in this example, ``0.0.2b09``):: + + [root@host ~]# lscss | grep 0.0.2b09 | awk '{print $2}' + 0.0.0313I'd remove the "[root@host ~]" part from all examples.
I'd rather keep them, just to make it clear where each command is issued (there are commands issued in the guest in step 2.)
Quoted 14 lines
docs/system/s390x/vfio-ccw.rst line 35
Quoted 12 lines
docs/system/s390x/vfio-ccw.rst new file +11
-0+* Unbind the subchannel (in this example, ``0.0.0313``) from the standard + I/O subchannel driver and bind it to the vfio-ccw driver:: + + [root@host ~]# echo 0.0.0313 > /sys/bus/css/devices/0.0.0313/driver/unbind + [root@host ~]# echo 0.0.0313 > /sys/bus/css/drivers/vfio_ccw/bind + +* Create the mediated device (identified by a uuid):: + + [root@host ~]# uuidgen + 7e270a25-e163-4922-af60-757fc8ed48c6 + [root@host ~]# echo "7e270a25-e163-4922-af60-757fc8ed48c6" > /sys/bus/css/devices/0.0.0313/mdev_supported_types/vfio_ccw-io/createMaybe break the long line with a backslash?
Makes sense.
Quoted 13 lines
Quoted 13 lines
docs/system/s390x/vfio-ccw.rst new file +12
-0+Step 2: configure QEMU +~~~~~~~~~~~~~~~~~~~~~~ + +* Reference the created mediated device and (optionally) pick a device id to + be presented in the guest (here, ``fe.0.1234``, which will end up visible + in the guest as ``0.0.1234``:: + + -device vfio-ccw,devno=fe.0.1234,sysfsdev=/sys/bus/mdev/devices/7e270a25-e163-4922-af60-757fc8ed48c6 + +* Start the guest. The device (here, ``0.0.1234``) should now be usable:: + + [root@guest ~]# lscss -d 0.0.1234
Quoted 8 lines
docs/system/s390x/vfio-ccw.rst line 53
Quoted 5 lines
docs/system/s390x/vfio-ccw.rst new file +5
-0+ Device Subchan. DevType CU Type Use PIM PAM POM CHPIDs + ---------------------------------------------------------------------- + 0.0.1234 0.0.0007 3390/0e 3990/e9 f0 f0 ff 1a2a3a0a 00000000 + [root@guest ~]# chccwdev -e 0.0.1234 + Setting device 0.0.1234 onlineHere I'd add a sentence saying that you could run "dmesg -t" now to check the kernel log. Then omit the timestamp in the example output below, that will shorten the lines quite a bit.
Makes sense as well.
Quoted 7 lines
docs/system/s390x/vfio-ccw.rst line 57
Quoted 5 lines
docs/system/s390x/vfio-ccw.rst new file +4
-0+ [ 197.011652] dasd-eckd 0.0.1234: A channel path to the device has become operational + [ 197.014468] dasd-eckd 0.0.1234: New DASD 3390/0E (CU 3990/01) with 10017 cylinders, 15 heads, 224 sectors + [ 197.045606] dasd-eckd 0.0.1234: DASD with 4 KB/block, 7212240 KB total size, 48 KB/track, compatible disk layout + [ 197.049034] dasda:VOL1/ 0X2B09: dasda1Thomas
Quoted 12 lines · On Tue, 5 May 2020 15:50:22 +0200 Cornelia Huck <[email protected]> wrote:
The documentation for the s390x system emulation target still has quite a bit of room for improvement, so I started adding some device documentation.
I'm not quite happy with the long command/output lines in the 3270 and vfio-ccw sections, but don't know how to make that more readable. Suggestions welcome.
Cornelia Huck (3):
docs/s390x: document the virtual css
docs/s390x: document 3270
docs/s390x: document vfio-ccw
Quoted 9 lines
docs/system/s390x/3270.rst | 32 +++++++++++++++++ docs/system/s390x/css.rst | 64 ++++++++++++++++++++++++++++++++++ docs/system/s390x/vfio-ccw.rst | 58 ++++++++++++++++++++++++++++++ docs/system/target-s390x.rst | 3 ++ 4 files changed, 157 insertions(+) create mode 100644 docs/system/s390x/3270.rst create mode 100644 docs/system/s390x/css.rst create mode 100644 docs/system/s390x/vfio-ccw.rst
Anybody feel like taking a look?