Skip to contentSkip to conversation

s390x: improve documentation

PATCH Superseded Cornelia Huck 2 participants 16 messages May 5, 2020 – May 15, 2020

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
new file mode 100644
index 000000000000..8e18194a2f0a
@@ -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
index 7d76ae97b401..37ca032d98ef 100644
@@ -23,6 +23,7 @@ or vfio-ap is also available.
 
 .. toctree::
    s390x/vfio-ap
+   s390x/css
 
 Architectural features
 ======================
Signature · 1 line
2.21.3
#2 lore raw

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
---
 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 +34 -0
new file mode 100644
index 000000000000..8e18194a2f0a
@@ -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

#3 lore raw

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?

#4 lore raw

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

#5 lore raw

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)

#6 lore raw

PATCH 2/3 docs/s390x: document 3270

In reply to Cornelia Huck

Add 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
new file mode 100644
index 000000000000..e367a457e001
@@ -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
index 37ca032d98ef..2592a05303ef 100644
@@ -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
#7 lore raw

Re: [PATCH 2/3] docs/s390x: document 3270

Quoted 15 lines · Cornelia Huck

Add 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 +0 -0
new file mode 100644
index 000000000000..e367a457e001

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

#8 lore raw

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.

---
 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 +0 -0
new file mode 100644
index 000000000000..e367a457e001

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:

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 to  

The 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_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?

Makes sense. This example was lifted straight from the wiki page :)

#9 lore raw

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.

---
 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 +0 -0
new file mode 100644
index 000000000000..e367a457e001

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:

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

#10 lore raw

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.

---
 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 +0 -0
new file mode 100644
index 000000000000..e367a457e001

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.

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."

?

#11 lore raw

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.

---
 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 +0 -0
new file mode 100644
index 000000000000..e367a457e001

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.

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

#12 lore raw

PATCH 3/3 docs/s390x: document vfio-ccw

In reply to Cornelia Huck

Add 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
new file mode 100644
index 000000000000..3b465578971f
@@ -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
index 2592a05303ef..644e404ef9fd 100644
@@ -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
#13 lore raw

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.

---
 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 +0 -0
new file mode 100644
index 000000000000..3b465578971f

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

#14 lore raw

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.

---
 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 +3 -0
new file mode 100644
index 000000000000..3b465578971f
@@ -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.0313  

I'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/create  

Maybe 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 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.

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: dasda1  

Thomas

#15 lore raw
In reply to Cornelia Huck
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?