[PATCH 0/3] s390x: improve documentation

[PATCH 0/3] s390x: improve documentation

[Cornelia Huck]

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

-- 
2.21.3

[PATCH 1/3] docs/s390x: document the virtual css

[Cornelia Huck]

Add some hints about "devno" rules.

Signed-off-by: Cornelia Huck <cohuck@redhat.com>
---
 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

diff --git a/docs/system/s390x/css.rst b/docs/system/s390x/css.rst
new file mode 100644
index 000000000000..8e18194a2f0a
--- /dev/null
+++ b/docs/system/s390x/css.rst
@@ -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.
diff --git a/docs/system/target-s390x.rst b/docs/system/target-s390x.rst
index 7d76ae97b401..37ca032d98ef 100644
--- a/docs/system/target-s390x.rst
+++ b/docs/system/target-s390x.rst
@@ -23,6 +23,7 @@ or vfio-ap is also available.
 
 .. toctree::
    s390x/vfio-ap
+   s390x/css
 
 Architectural features
 ======================
-- 
2.21.3

Re: [PATCH 1/3] docs/s390x: document the virtual css

[Thomas Huth]

On 05/05/2020 15.50, Cornelia Huck wrote:
> Add some hints about "devno" rules.

Thanks a lot for doing this, some documentation in this area is
extremely useful!

> Signed-off-by: Cornelia Huck <cohuck@redhat.com>
> ---
>  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
> 
> diff --git a/docs/system/s390x/css.rst b/docs/system/s390x/css.rst
> new file mode 100644
> index 000000000000..8e18194a2f0a
> --- /dev/null
> +++ b/docs/system/s390x/css.rst
> @@ -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``.

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

> +* 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" ?

> +* 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.

> +* 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

[Cornelia Huck]

On Fri, 15 May 2020 09:04:13 +0200
Thomas Huth <thuth@redhat.com> wrote:

> On 05/05/2020 15.50, Cornelia Huck wrote:

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

> 
> > +* 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.

> 
> > +* 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 :)

> 
> > +* 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

[Thomas Huth]

On 15/05/2020 10.51, Cornelia Huck wrote:
> On Fri, 15 May 2020 09:04:13 +0200
> Thomas Huth <thuth@redhat.com> wrote:
> 
>> On 05/05/2020 15.50, Cornelia Huck wrote:
[...]
>>> +
>>> +  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

[Cornelia Huck]

On Fri, 15 May 2020 10:57:26 +0200
Thomas Huth <thuth@redhat.com> wrote:

> On 15/05/2020 10.51, Cornelia Huck wrote:
> > On Fri, 15 May 2020 09:04:13 +0200
> > Thomas Huth <thuth@redhat.com> wrote:
> >   
> >> On 05/05/2020 15.50, Cornelia Huck wrote:  
> [...]
> >>> +
> >>> +  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?

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

[Cornelia Huck]

Add some basic info how to use 3270 devices.

Signed-off-by: Cornelia Huck <cohuck@redhat.com>
---
 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

diff --git a/docs/system/s390x/3270.rst b/docs/system/s390x/3270.rst
new file mode 100644
index 000000000000..e367a457e001
--- /dev/null
+++ b/docs/system/s390x/3270.rst
@@ -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 serial-getty@3270-tty1.service
+
+This should get you an addtional tty for logging into the guest.
diff --git a/docs/system/target-s390x.rst b/docs/system/target-s390x.rst
index 37ca032d98ef..2592a05303ef 100644
--- a/docs/system/target-s390x.rst
+++ b/docs/system/target-s390x.rst
@@ -24,6 +24,7 @@ or vfio-ap is also available.
 .. toctree::
    s390x/vfio-ap
    s390x/css
+   s390x/3270
 
 Architectural features
 ======================
-- 
2.21.3

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

[Thomas Huth]

On 05/05/2020 15.50, Cornelia Huck wrote:
> Add some basic info how to use 3270 devices.
> 
> Signed-off-by: Cornelia Huck <cohuck@redhat.com>
> ---
>  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
> 
> diff --git a/docs/system/s390x/3270.rst b/docs/system/s390x/3270.rst
> new file mode 100644
> index 000000000000..e367a457e001
> --- /dev/null
> +++ b/docs/system/s390x/3270.rst
> @@ -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.

?

> +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?)

> +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?

> +Example configuration
> +---------------------
> +
> +* Add a ``tn3270`` chardev and a ``x-3270device`` to the QEMU command line::

"x-terminal3270" ?

> +    -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

[Cornelia Huck]

On Fri, 15 May 2020 09:29:42 +0200
Thomas Huth <thuth@redhat.com> wrote:

> On 05/05/2020 15.50, Cornelia Huck wrote:
> > Add some basic info how to use 3270 devices.
> > 
> > Signed-off-by: Cornelia Huck <cohuck@redhat.com>
> > ---
> >  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
> > 
> > diff --git a/docs/system/s390x/3270.rst b/docs/system/s390x/3270.rst
> > new file mode 100644
> > index 000000000000..e367a457e001
> > --- /dev/null
> > +++ b/docs/system/s390x/3270.rst
> > @@ -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.

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.

> 
> ?
> 
> > +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.

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

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

> 
> > +Example configuration
> > +---------------------
> > +
> > +* Add a ``tn3270`` chardev and a ``x-3270device`` to the QEMU command line::  
> 
> "x-terminal3270" ?

Nod.

> 
> > +    -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 :)

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

[Thomas Huth]

On 15/05/2020 11.00, Cornelia Huck wrote:
> On Fri, 15 May 2020 09:29:42 +0200
> Thomas Huth <thuth@redhat.com> wrote:
> 
>> On 05/05/2020 15.50, Cornelia Huck wrote:
>>> Add some basic info how to use 3270 devices.
>>>
>>> Signed-off-by: Cornelia Huck <cohuck@redhat.com>
>>> ---
>>>  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
>>>
>>> diff --git a/docs/system/s390x/3270.rst b/docs/system/s390x/3270.rst
>>> new file mode 100644
>>> index 000000000000..e367a457e001
>>> --- /dev/null
>>> +++ b/docs/system/s390x/3270.rst
>>> @@ -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.
> 
> 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

[Cornelia Huck]

On Fri, 15 May 2020 11:14:40 +0200
Thomas Huth <thuth@redhat.com> wrote:

> On 15/05/2020 11.00, Cornelia Huck wrote:
> > On Fri, 15 May 2020 09:29:42 +0200
> > Thomas Huth <thuth@redhat.com> wrote:
> >   
> >> On 05/05/2020 15.50, Cornelia Huck wrote:  
> >>> Add some basic info how to use 3270 devices.
> >>>
> >>> Signed-off-by: Cornelia Huck <cohuck@redhat.com>
> >>> ---
> >>>  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
> >>>
> >>> diff --git a/docs/system/s390x/3270.rst b/docs/system/s390x/3270.rst
> >>> new file mode 100644
> >>> index 000000000000..e367a457e001
> >>> --- /dev/null
> >>> +++ b/docs/system/s390x/3270.rst
> >>> @@ -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.  
> > 
> > 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

[Thomas Huth]

On 15/05/2020 11.45, Cornelia Huck wrote:
> On Fri, 15 May 2020 11:14:40 +0200
> Thomas Huth <thuth@redhat.com> wrote:
> 
>> On 15/05/2020 11.00, Cornelia Huck wrote:
>>> On Fri, 15 May 2020 09:29:42 +0200
>>> Thomas Huth <thuth@redhat.com> wrote:
>>>   
>>>> On 05/05/2020 15.50, Cornelia Huck wrote:  
>>>>> Add some basic info how to use 3270 devices.
>>>>>
>>>>> Signed-off-by: Cornelia Huck <cohuck@redhat.com>
>>>>> ---
>>>>>  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
>>>>>
>>>>> diff --git a/docs/system/s390x/3270.rst b/docs/system/s390x/3270.rst
>>>>> new file mode 100644
>>>>> index 000000000000..e367a457e001
>>>>> --- /dev/null
>>>>> +++ b/docs/system/s390x/3270.rst
>>>>> @@ -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.  
>>>
>>> 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."
> 
> ?

Yes, that sounds good!

 Thanks,
  Thomas

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

[Cornelia Huck]

Add a basic example for passing a dasd via vfio-ccw.

Signed-off-by: Cornelia Huck <cohuck@redhat.com>
---
 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

diff --git a/docs/system/s390x/vfio-ccw.rst b/docs/system/s390x/vfio-ccw.rst
new file mode 100644
index 000000000000..3b465578971f
--- /dev/null
+++ b/docs/system/s390x/vfio-ccw.rst
@@ -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
diff --git a/docs/system/target-s390x.rst b/docs/system/target-s390x.rst
index 2592a05303ef..644e404ef9fd 100644
--- a/docs/system/target-s390x.rst
+++ b/docs/system/target-s390x.rst
@@ -25,6 +25,7 @@ or vfio-ap is also available.
    s390x/vfio-ap
    s390x/css
    s390x/3270
+   s390x/vfio-ccw
 
 Architectural features
 ======================
-- 
2.21.3

Re: [PATCH 3/3] docs/s390x: document vfio-ccw

[Thomas Huth]

On 05/05/2020 15.50, Cornelia Huck wrote:
> Add a basic example for passing a dasd via vfio-ccw.
> 
> Signed-off-by: Cornelia Huck <cohuck@redhat.com>
> ---
>  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
> 
> diff --git a/docs/system/s390x/vfio-ccw.rst b/docs/system/s390x/vfio-ccw.rst
> new file mode 100644
> index 000000000000..3b465578971f
> --- /dev/null
> +++ b/docs/system/s390x/vfio-ccw.rst
> @@ -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/ ?

> +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?

> 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

I'd remove the "[root@host ~]" part from all examples.

> +* 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?

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

> +    [  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

[Cornelia Huck]

On Fri, 15 May 2020 09:54:44 +0200
Thomas Huth <thuth@redhat.com> wrote:

> On 05/05/2020 15.50, Cornelia Huck wrote:
> > Add a basic example for passing a dasd via vfio-ccw.
> > 
> > Signed-off-by: Cornelia Huck <cohuck@redhat.com>
> > ---
> >  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
> > 
> > diff --git a/docs/system/s390x/vfio-ccw.rst b/docs/system/s390x/vfio-ccw.rst
> > new file mode 100644
> > index 000000000000..3b465578971f
> > --- /dev/null
> > +++ b/docs/system/s390x/vfio-ccw.rst
> > @@ -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/ ?

I've seen 'DASD' used both as singular and as plural. Can use 'DASDs'
if that is less confusing.

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

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

> 
> > +* 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.

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

> 
> > +    [  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 0/3] s390x: improve documentation

[Cornelia Huck]

On Tue,  5 May 2020 15:50:22 +0200
Cornelia Huck <cohuck@redhat.com> 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
> 
>  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?