docs/system/s390x: Improve the 3270 documentation
PATCH 1/1 docs/system/s390x: Improve the 3270 documentation
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).
--- docs/system/s390x/3270.rst | 43 ++++++++++++++++++++++++++++++++------ 1 file changed, 37 insertions(+), 6 deletions(-)
docs/system/s390x/3270.rst +37 -6
@@ -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 [email protected] -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.
Signature · 1 line
2.18.1
Quoted 4 lines · On Thu, 9 Jul 2020 18:04:39 +0200 Thomas Huth <[email protected]> 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)?)
Quoted 33 lines
Signed-off-by Thomas Huth <[email protected]>--- docs/system/s390x/3270.rst | 43 ++++++++++++++++++++++++++++++++------ 1 file changed, 37 insertions(+), 6 deletions(-)docs/system/s390x/3270.rst +9
-3@@ -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 ---------------------
docs/system/s390x/3270.rst to actually be able to use it, attach the ``x3270`` emulator to the chardev. · line 28
Quoted 10 lines
docs/system/s390x/3270.rst +6
-2+* 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?
Quoted 9 lines
docs/system/s390x/3270.rst +1
-1* Start the guest. In the guest, use ``chccwdev -e 0.0.000a`` to enable the device.@@ -29,4 +39,25 @@ Example configuration systemctl start [email protected] -This should get you an addtional tty for logging into the guest. + This should get you an addtional tty for logging into the guest.
docs/system/s390x/3270.rst Example configuration · line 52
Quoted 10 lines
docs/system/s390x/3270.rst +10
-0+ +* 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 :)
docs/system/s390x/3270.rst Example configuration · line 58
Quoted 6 lines
docs/system/s390x/3270.rst +6
-0+ +* 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 //
docs/system/s390x/3270.rst Example configuration · line 60
Quoted 2 lines
docs/system/s390x/3270.rst +2
-0+ +* Resizing on reattach is not yet supported.
s/yet //
docs/system/s390x/3270.rst Example configuration · line 63
Quoted 3 lines
docs/system/s390x/3270.rst +3
-0+ +* 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 //
Quoted 9 lines · Cornelia Huck
Quoted 4 lines · On Thu, 9 Jul 2020 18:04:39 +0200 Thomas Huth <[email protected]> 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).
Quoted 4 lines
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.
Quoted 2 lines
(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
Quoted 8 lines · Cornelia Huck
Quoted 4 lines · On Thu, 9 Jul 2020 18:04:39 +0200 Thomas Huth <[email protected]> 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).
Quoted 4 lines
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.
Quoted 2 lines
(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.
Quoted 38 lines
Quoted 38 lines
Signed-off-by Thomas Huth <[email protected]>--- docs/system/s390x/3270.rst | 43 ++++++++++++++++++++++++++++++++------ 1 file changed, 37 insertions(+), 6 deletions(-)docs/system/s390x/3270.rst +13
-3@@ -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::
Quoted 6 lines
docs/system/s390x/3270.rst to actually be able to use it, attach the ``x3270`` emulator to the chardev. · line 28
Quoted 4 lines
docs/system/s390x/3270.rst +2
-2- -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=terminal0Any 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.
Quoted 39 lines
Quoted 9 lines
docs/system/s390x/3270.rst +1
-1* Start the guest. In the guest, use ``chccwdev -e 0.0.000a`` to enable the device.@@ -29,4 +39,25 @@ Example configuration systemctl start [email protected] -This should get you an addtional tty for logging into the guest. + This should get you an addtional tty for logging into the guest.docs/system/s390x/3270.rst Example configuration · line 52
Quoted 10 lines
docs/system/s390x/3270.rst +10
-0+ +* 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 :)
docs/system/s390x/3270.rst Example configuration · line 58
Quoted 6 lines
docs/system/s390x/3270.rst +6
-0+ +* 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 //
docs/system/s390x/3270.rst Example configuration · line 60
Quoted 2 lines
docs/system/s390x/3270.rst +2
-0+ +* Resizing on reattach is not yet supported.s/yet //
Quoted 6 lines
docs/system/s390x/3270.rst Example configuration · line 63
Quoted 3 lines
docs/system/s390x/3270.rst +3
-0+ +* 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