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

While at it, I also shortened the lines of the first example a little bit.
Otherwise they showed up with a horizontal scrollbar in my Firefox browser.

Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 v2:
 - Added the changes that have been suggested by Cornelia
 - Talk about "Linux kernel" instead of just saying "kernel", just in case.

 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..36d1c96bfb 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 Linux 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
 
 * 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 Linux 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 very basic. In particular:
+
+* Only one 3270 device is supported.
+
+* It has only been tested with Linux guests and the x3270 emulator.
+
+* TLS/SSL is not supported.
+
+* Resizing on reattach is not supported.
+
+* Multiple commands in one inbound buffer (for example, when the reset key
+  is pressed while the network is slow) are not supported.
-- 
2.18.1

On Mon, 13 Jul 2020 09:51:12 +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).
> 
> While at it, I also shortened the lines of the first example a little bit.
> Otherwise they showed up with a horizontal scrollbar in my Firefox browser.
> 
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>  v2:
>  - Added the changes that have been suggested by Cornelia
>  - Talk about "Linux kernel" instead of just saying "kernel", just in case.
> 
>  docs/system/s390x/3270.rst | 43 ++++++++++++++++++++++++++++++++------
>  1 file changed, 37 insertions(+), 6 deletions(-)

(...)

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

While you're at it,

s/addtional/additional/

> +
> +* If you want to use the 3270 device as the Linux 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 very basic. In particular:
> +
> +* Only one 3270 device is supported.
> +
> +* It has only been tested with Linux guests and the x3270 emulator.
> +
> +* TLS/SSL is not supported.
> +
> +* Resizing on reattach is not supported.
> +
> +* Multiple commands in one inbound buffer (for example, when the reset key
> +  is pressed while the network is slow) are not supported.

Looks good.

Reviewed-by: Cornelia Huck <cohuck@redhat.com>

(Feel free to send it yourself if you have some patches in your queue, I
don't have anything for s390x right now.)