Re: [PATCH] docs/system/s390x: Improve the 3270 documentation

[Cornelia Huck]

On Thu,  9 Jul 2020 18:04:39 +0200
Thomas Huth <thuth@redhat.com> wrote:

> There is some additional information about the 3270 support in our
> Wiki at https://wiki.qemu.org/Features/3270 - so let's include this
> information into the main documentation now to have one single
> source of information (the Wiki page could later be removed).

No objection; but what should our general policy with regard to wiki
pages vs. documentation be? The 3270 support is pretty much static, but
e.g. for vfio-ccw, we use the wiki page as a place where we track
things that should be worked on etc.

(Related: What is the scope of our QEMU documentation? Is a libvirt XML
snippet on topic? Kernel configuration options (as in here)?)

> 
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>  docs/system/s390x/3270.rst | 43 ++++++++++++++++++++++++++++++++------
>  1 file changed, 37 insertions(+), 6 deletions(-)
> 
> diff --git a/docs/system/s390x/3270.rst b/docs/system/s390x/3270.rst
> index 1774cdcadf..80350264d7 100644
> --- a/docs/system/s390x/3270.rst
> +++ b/docs/system/s390x/3270.rst
> @@ -1,9 +1,15 @@
>  3270 devices
>  ============
>  
> -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.
> +The 3270 is the classic 'green-screen' console of the mainframes (see the
> +`IBM 3270 Wikipedia article <https://en.wikipedia.org/wiki/IBM_3270>`__).
> +
> +The 3270 data stream is not implemented within QEMU; the device only provides
> +TN3270 (a telnet extension; see `RFC 854 
> <https://tools.ietf.org/html/rfc854>`__
> +and `RFC 1576 <https://tools.ietf.org/html/rfc1576>`__) and leaves the heavy
> +lifting to 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.
>  
>  To provide a 3270 device to a guest, create a ``x-terminal3270`` linked to
>  a ``tn3270`` chardev. The guest will see a 3270 channel device. In order
> @@ -12,10 +18,14 @@ to actually be able to use it, attach the ``x3270`` 
> emulator to the chardev.
>  Example configuration
>  ---------------------
>  
> +* Make sure that 3270 support is enabled in the guest's kernel. You need
> +  ``CONFIG_TN3270`` and at least one of ``CONFIG_TN3270_TTY`` (for additional
> +  ttys) or ``CONFIG_TN3270_CONSOLE`` (for a 3270 console).
> +
>  * Add a ``tn3270`` chardev and a ``x-terminal3270`` to the QEMU command 
> line::
>  
> -    -chardev socket,id=char_0,host=0.0.0.0,port=2300,nowait,server,tn3270
> -    -device x-terminal3270,chardev=char_0,devno=fe.0.000a,id=terminal_0
> +   -chardev socket,id=ch0,host=0.0.0.0,port=2300,nowait,server,tn3270
> +   -device x-terminal3270,chardev=ch0,devno=fe.0.000a,id=terminal0

Any reason why you changed this?

>  
>  * Start the guest. In the guest, use ``chccwdev -e 0.0.000a`` to enable
>    the device.
> @@ -29,4 +39,25 @@ Example configuration
>  
>      systemctl start serial-getty@3270-tty1.service
>  
> -This should get you an addtional tty for logging into the guest.
> +  This should get you an addtional tty for logging into the guest.
> +
> +* If you want to use the 3270 device as the kernel console instead of an
> +  additional tty, you can also append ``conmode=3270 condev=000a`` to the
> +  guest's kernel command line. The kernel then should use the 3270 as
> +  console after the next boot.
> +
> +Restrictions
> +------------
> +
> +3270 support is still experimental. In particular:

s/still experimental/very basic/

I don't think there's much progress on the horizon; let's not give
people false hope :)

> +
> +* Only one 3270 device is supported.
> +
> +* It has only been tested with Linux guests and the x3270 emulator.
> +
> +* TLS/SSL is not yet supported.

s/yet //

> +
> +* Resizing on reattach is not yet supported.

s/yet //

> +
> +* Multiple commands in one inbound buffer (for example, when the reset key
> +  is pressed while the network is slow) are not yet supported.

s/yet //