* [PATCH] docs/system/s390x: Improve the 3270 documentation
@ 2020-07-09 16:04 Thomas Huth
2020-07-10 10:55 ` Cornelia Huck
0 siblings, 1 reply; 4+ messages in thread
From: Thomas Huth @ 2020-07-09 16:04 UTC (permalink / raw)
To: qemu-devel, Cornelia Huck; +Cc: qemu-s390x
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).
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
* 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:
+
+* Only one 3270 device is supported.
+
+* It has only been tested with Linux guests and the x3270 emulator.
+
+* TLS/SSL is not yet supported.
+
+* Resizing on reattach is not yet supported.
+
+* Multiple commands in one inbound buffer (for example, when the reset key
+ is pressed while the network is slow) are not yet supported.
--
2.18.1
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] docs/system/s390x: Improve the 3270 documentation
2020-07-09 16:04 [PATCH] docs/system/s390x: Improve the 3270 documentation Thomas Huth
@ 2020-07-10 10:55 ` Cornelia Huck
2020-07-10 11:40 ` Peter Maydell
2020-07-13 7:38 ` Thomas Huth
0 siblings, 2 replies; 4+ messages in thread
From: Cornelia Huck @ 2020-07-10 10:55 UTC (permalink / raw)
To: Thomas Huth; +Cc: qemu-s390x, qemu-devel
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 //
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] docs/system/s390x: Improve the 3270 documentation
2020-07-10 10:55 ` Cornelia Huck
@ 2020-07-10 11:40 ` Peter Maydell
2020-07-13 7:38 ` Thomas Huth
1 sibling, 0 replies; 4+ messages in thread
From: Peter Maydell @ 2020-07-10 11:40 UTC (permalink / raw)
To: Cornelia Huck; +Cc: Thomas Huth, qemu-s390x, QEMU Developers
On Fri, 10 Jul 2020 at 11:56, Cornelia Huck <cohuck@redhat.com> wrote:
>
> 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.
I think that (apart from docs/devel) the ideal would be that a
user should be able to look at the documentation to find what
they need to know and not have to look in the wiki. So "feature X
is unsupported" is useful to have in the documentation; developer
TODO lists, design notes, suggestions for improvements, etc
would be better on the wiki.
> (Related: What is the scope of our QEMU documentation? Is a libvirt XML
> snippet on topic? Kernel configuration options (as in here)?)
If we don't think they're liable to become rapidly out of date,
I guess we might as well err on the side of providing information
that's helpful to users. (I think a full-on "here is a tutorial
and how-to guide on setting up guest OS Foo on this model"
would perhaps be a bit out of place, but there's lots of space
between here and there.)
thanks
-- PMM
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] docs/system/s390x: Improve the 3270 documentation
2020-07-10 10:55 ` Cornelia Huck
2020-07-10 11:40 ` Peter Maydell
@ 2020-07-13 7:38 ` Thomas Huth
1 sibling, 0 replies; 4+ messages in thread
From: Thomas Huth @ 2020-07-13 7:38 UTC (permalink / raw)
To: Cornelia Huck; +Cc: qemu-s390x, qemu-devel
On 10/07/2020 12.55, Cornelia Huck wrote:
> 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.
I think that docs which are "done" should go into the git repo. If they
are rather still work-in-progress and change very often, or relate to a
feature that has not been merged yet, the wiki is likely the better place.
> (Related: What is the scope of our QEMU documentation? Is a libvirt XML
> snippet on topic? Kernel configuration options (as in here)?)
As long as the focus is still on QEMU, I think it is fine. If the
information is only about libvirt or the kernel, that documentation
should maybe rather be added to libvirt.org or linux-kvm.org instead.
>> 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?
The lines were too long - Firefox displayed this example with a
horizontal scrollbar, even if I resized the browser window large enough.
With my change, it shows up nicely without scrollbar.
>>
>> * 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 //
>
I'll fix these in v2.
Thanks for the review!
Thomas
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2020-07-13 7:39 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-07-09 16:04 [PATCH] docs/system/s390x: Improve the 3270 documentation Thomas Huth
2020-07-10 10:55 ` Cornelia Huck
2020-07-10 11:40 ` Peter Maydell
2020-07-13 7:38 ` Thomas Huth
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.